From 4f9ca58a6d97b93217b6d4ea0bf8fab5d84af7fc Mon Sep 17 00:00:00 2001 From: "failproofai-canary[bot]" Date: Sat, 12 Sep 2026 20:36:10 +0000 Subject: [PATCH 1/8] docs: update translations for changed English sources --- docs/ar/start/integrations/custom-agents.mdx | 371 +++++++-------- docs/de/start/integrations/custom-agents.mdx | 276 ++++++----- docs/es/start/integrations/custom-agents.mdx | 242 +++++----- docs/fr/start/integrations/custom-agents.mdx | 250 +++++----- docs/he/start/integrations/custom-agents.mdx | 416 ++++++++-------- docs/hi/start/integrations/custom-agents.mdx | 450 +++++++++--------- docs/it/start/integrations/custom-agents.mdx | 326 +++++++------ docs/ja/start/integrations/custom-agents.mdx | 374 ++++++++------- docs/ko/start/integrations/custom-agents.mdx | 344 +++++++------ .../start/integrations/custom-agents.mdx | 228 ++++----- docs/ru/start/integrations/custom-agents.mdx | 404 ++++++++-------- docs/tr/start/integrations/custom-agents.mdx | 408 ++++++++-------- docs/vi/start/integrations/custom-agents.mdx | 352 +++++++------- docs/zh/start/integrations/custom-agents.mdx | 358 +++++++------- 14 files changed, 2387 insertions(+), 2412 deletions(-) diff --git a/docs/ar/start/integrations/custom-agents.mdx b/docs/ar/start/integrations/custom-agents.mdx index 6e5db3c2..088cdb6c 100644 --- a/docs/ar/start/integrations/custom-agents.mdx +++ b/docs/ar/start/integrations/custom-agents.mdx @@ -1,13 +1,14 @@ --- +--- title: "الوكلاء المخصصون" sidebarTitle: "الوكلاء المخصصون" -description: "أدرج وكيلاً كتبته بنفسك، أو إطار عمل لا يوجد له محول في Failproof AI." +description: "أدرج وكيلًا كتبته بنفسك، أو إطار عمل لا يتوفر له محول." icon: "code" --- -لوكيل كتبته بنفسك، أو إطار عمل لا يوجد له محول في Failproof AI. لا شيء يجب إدراجه: أنت تصدر الأحداث. +لوكيل كتبته بنفسك، أو إطار عمل لا يتوفر له محول من Failproof AI. لا يوجد شيء لإدراجه: أنت تُصدر الأحداث. -هذا هو نفس API الذي يستدعيه محولات الأطر الأربعة. وهي جداول ترجمة فوقه. +هذا هو نفس الواجهة البرمجية التي تستدعيها محولات الإطارات الأربعة. وهي جداول ترجمة فوقها. ## التثبيت @@ -32,25 +33,25 @@ with failproofai_sdk.session(): # one run اقرأه من الأعلى إلى الأسفل وسيخبرك بما يعنيه: -| غلف فيه | للقول | +| لف فيه | لتقول | | --- | --- | | `session()` | هذه الأحداث تنتمي إلى نفس التشغيل | -| `agent()` | شيء ما يقوم بالعمل — أعطه اسماً ستتعرف عليه في القائمة | +| `agent()` | شيء ما يقوم بعمل — أعطه اسمًا ستتعرف عليه في القائمة | | `tool_call()` | هذه أداة واحدة، وإليك ما أرجعته | -وما يصدره كل واحد فعلياً: +وما يصدره كل واحد بالفعل: | النطاق | يصدر | الغرض | | --- | --- | --- | -| `session()` | لا شيء | يربط معرف الجلسة، مجموعة تشغيل واحدة | -| `agent()` | `agent_start`, `agent_end` | يحيط بوحدة عمل واحدة | +| `session()` | لا شيء | يربط معرف الجلسة، ويجمع تشغيلًا واحدًا | +| `agent()` | `agent_start`, `agent_end` | يحيط بوحدة عمل | | `tool_call()` | `tool_use`, `tool_result` | يحيط بأداة واحدة ويقيسها | -كل شيء بالداخل يمكن أن يحذف `session_id` و `agent_id`. تربط النطاقات الهوية على متغيرات السياق وكل نداء حدث يقرأها مرة أخرى، لذلك لا تمرر أبداً المعرفات من خلال وظائفك. +كل شيء بداخله يمكن حذف `session_id` و `agent_id`. تربط النطاقات الهوية على متغيرات السياق وكل استدعاء حدث يقرأها مرة أخرى، لذا لا تمرر المعرفات عبر وظائفك أبدًا. -تعمل الثلاثة جميعاً مع `async with` وكذلك مع `with`. +جميعها تعمل تحت `async with` وكذلك `with`. -يبني التداخل للوكلاء الشجرة. يتم حساب `parent_id` والعمق من المكدس: +وضع الوكلاء المتداخل يبني الشجرة. يتم حساب `parent_id` والعمق من المكدس: ```python with failproofai_sdk.session(): @@ -61,44 +62,44 @@ with failproofai_sdk.session(): ## كيف يغلق النطاق -`agent()` يتعامل مع الاستثناءات لك: +`agent()` يتعامل مع الاستثناءات نيابة عنك: | ما حدث | الأحداث | النتيجة | | --- | --- | --- | -| لم يحدث شيء | `agent_end` | `success` | +| لا شيء تم رفعه | `agent_end` | `success` | | `Exception` | `error`، ثم `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`، ثم `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | `agent_end` فقط | `cancelled` | -يتم إصدار الخطأ قبل `agent_end`، لأن لوحة التحكم تغلق الامتداد في `agent_end` وأي شيء بعده يُنسب إلى لا شيء. الإلغاء ليس فشلاً، لذلك لا تلوث التشغيلات الملغاة سطح الأخطاء. يتم إعادة رفع الاستثناء دائماً: النطاق لا يبتلعه أبداً. +يتم إصدار الخطأ قبل `agent_end`، لأن لوحة المعلومات تغلق الامتداد في `agent_end` وأي شيء بعده ينسب إلى لا شيء. الإلغاء ليس فشلًا، لذا لا تلوث عمليات التشغيل الملغاة سطح الأخطاء. يتم إعادة رفع الاستثناء دائمًا: لا يبتلع نطاق أبدًا. -## طرق الحدث +## طرق الأحداث -خمسة عشر طريقة في ست عائلات. معظمها يأتي في أزواج — تصدر الفاتحة، ثم الأغلق، و SDK يقيس الامتداد بينهما. +خمسة عشر طريقة في ست عائلات. معظمها يأتي على شكل أزواج — تصدر الفتاحة، ثم الأغلقة، وتقيس SDK الامتداد بينهما. -| العائلة | فتح | إغلاق | مستقل | +| العائلة | يفتح | يغلق | مستقل | | --- | --- | --- | --- | | **الوكلاء** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | | **النماذج** | `model_request` | `model_response` | — | | **الأدوات** | `tool_use` | `tool_result` | — | -| **الخطافات** | `hook_triggered` | `hook_completed` | — | +| **الخطاطيف** | `hook_triggered` | `hook_completed` | — | | **البشر** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | -| **الأعطال** | — | — | `error` | +| **الأخطاء** | — | — | `error` | - فضّل النطاقات — `agent()` و `tool_call()` — أينما كانت مناسبة. إنها تضمن حدث الإغلاق حتى عندما يرفع الجسم. تصل إلى هذه الطرق مباشرة عندما لا يتداخل تدفق التحكم، مثل نداء نموذج داخل مساعد. + فضّل النطاقات — `agent()` و `tool_call()` — حيثما تناسب. تضمن حدث الإغلاق حتى عندما يرفع الجسم استثناءً. وصل إلى هذه الطرق مباشرة عندما لا يتداخل تدفق التحكم، مثل استدعاء نموذج داخل دالة مساعدة. -```python الوكلاء +```python Agents failproofai_sdk.event.agent_start(agent_id="planner", goal="find the cheapest flight") failproofai_sdk.event.agent_end(agent_id="planner", outcome="success", summary="...") failproofai_sdk.event.agent_pause(pause_id="p1", reason="awaiting approval") failproofai_sdk.event.agent_resume(pause_id="p1") ``` -```python النماذج +```python Models failproofai_sdk.event.model_request( model="gpt-4o-mini", messages=[{"role": "user", "content": "..."}], @@ -114,24 +115,24 @@ failproofai_sdk.event.model_response( ) ``` -```python الأدوات +```python Tools failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1", input={"q": "..."}) failproofai_sdk.event.tool_result(tool_name="search", tool_call_id="c1", output="...") ``` -```python الخطافات +```python Hooks failproofai_sdk.event.hook_triggered(hook_name="retrieve", hook_id="h1", trigger_event="node") failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome="success") ``` -```python البشر +```python Humans failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") failproofai_sdk.event.human_interrupt(reason="operator stopped the run", at_step="step_3") ``` -```python الأعطال +```python Failures failproofai_sdk.event.error( error_type="TimeoutError", message="provider timed out after 30s", @@ -141,23 +142,23 @@ failproofai_sdk.event.error( - **العائلتان البشريتان تشير في اتجاهين متعاكسين.** + **عائلتا البشر تشيران في الاتجاهات المعاكسة.** | الطرق | المعنى | | --- | --- | - | `human_wait` / `human_input` | **الوكيل طلب من شخص** — بوابة موافقة، سؤال توضيحي | - | `human_pause` / `human_interrupt` | **شخص تصرف على الوكيل** — زر إيقاف، توقف المشغل | + | `human_wait` / `human_input` | **طلب الوكيل من شخص** — بوابة موافقة، سؤال توضيحي | + | `human_pause` / `human_interrupt` | **شخص تصرف على الوكيل** — زر إيقاف، إيقاف مؤقت من المشغل | - لا يشير أي إطار عمل إلى الزوج الثاني، لذا فهو دائماً لك لإصداره. + لا يشير أي إطار عمل الزوج الثاني، لذا فهو دائمًا لك لإصداره. - **مرر `request_id` عندما تعمل نداءات النموذج بالتزامن.** بدونه، تتزاوج طلبات الاستجابات بترتيب الوصول لكل وكيل — والنداءات المتزامنة تتزاوج بشكل خاطئ، مرفقة كل استجابة بالطلب الخاطئ. + **مرر `request_id` عندما تعمل استدعاءات النموذج بالتزامن.** بدونه، يتم إقران الطلبات والردود بترتيب الوصول لكل وكيل — والمكالمات المتزامنة تقترن بشكل خاطئ، وتوصل كل رد إلى الطلب الخاطئ. ## مثال -حلقة استدعاء الأداة مقابل OpenAI API، بدون إطار عمل وكيل: +حلقة استدعاء أدوات ضد OpenAI API، بدون إطار عمل للوكيل: ```python import json @@ -204,11 +205,11 @@ with failproofai_sdk.session(): }) ``` -ينتج عن هذا نفس أنواع الأحداث الستة التي سيعطيك المحول. الإصدار الكامل القابل للتشغيل، مع تعريفات الأداة، يأتي في مستودع SDK تحت `docs/manual/examples/`. +ينتج عن هذا نفس أنواع الأحداث الستة التي يعطيك محول. تشحن النسخة الكاملة القابلة للتشغيل، مع تعريفات الأداة، في مستودع SDK تحت `docs/manual/examples/`. -## الخيوط و async +## الخيوط والعمليات غير المتزامنة -تنتشر متغيرات السياق في مهام asyncio تلقائياً. لا تنتشر في خيوط جديدة، لأن الخيط يبدأ بسياق فارغ. +تنتشر متغيرات السياق في مهام asyncio تلقائيًا. لا تنتشر في الخيوط الجديدة، لأن الخيط يبدأ بسياق فارغ. ```python # asyncio: nothing to do @@ -221,35 +222,35 @@ threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -بدون `propagate()`، تثير أحداث العامل `TypeError` تسمي الإصلاح بدلاً من الهبوط على جلسة لا شيء. هذا متعمد: حدث بدون جلسة يتم تخطيه بواسطة ingest والإجابة `200`، وهو الفشل الصامت الذي توجد طبقة الهوية لمنعه. +بدون `propagate()`، تثير أحداث العامل `TypeError` تسمي الإصلاح بدلاً من الهبوط بدون جلسة. هذا مقصود: حدث بدون جلسة يتم تخطيه بواسطة الاستيعاب والإجابة `200`، وهو الفشل الصامت الذي تم تصميم طبقة الهوية لمنعه. ## أدرج إطار عمل بدون محول -كل إطار عمل وكيل يعطيك نفس الفتحات الثلاثة. اربطها وسيكون لديك تتبع كامل — المحولات الأربعة المشحونة لا تفعل أكثر من هذا. +يعطيك كل إطار عمل للوكيل نفس ثلاثة طبقات. مرّرها ولديك تتبع كامل — لا تفعل المحولات الأربعة المشحونة أكثر من هذا. -| الفتحة | ما تكتبه | ما يهبط | +| الطبقة | ما تكتبه | ما يصل | | --- | --- | --- | | التشغيل | `session()` + `agent()` | `agent_start`, `agent_end` | | كل أداة | `tool_call()` | `tool_use`, `tool_result` | -| كل نداء نموذج | زوج `model_*` | `model_request`, `model_response` | +| كل استدعاء نموذج | زوج `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - في أي مكان يستدعيه الإطار غلاف أداة أو برنامج وسيط. + + في أياً كان ما يسميه الإطار غلافًا للأداة أو وسيطًا. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -264,31 +265,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **لديك عقدة أو خطوة أو حدود برنامج وسيط تستحق الرؤية؟** غلفها في زوج خطاف — `hook_triggered` / `hook_completed` — وليس `agent()` متداخل. `agent_id` هو جانب cardinality منخفض، وإدخال واحد لكل عقدة يغرقه. تُعرض امتدادات الخطاف بنفس الطريقة وتمنحك زمن الكمون لكل عقدة. + **هل لديك عقدة أو حدود خطوة أو وسيط يستحق الرؤية؟** لفّه في زوج خطاطيف — `hook_triggered` / `hook_completed` — وليس وكيل `agent()` متداخل. `agent_id` هو جانب منخفض الأساسية، وإدخال واحد لكل عقدة يغرقه. تُعرض امتدادات الخطاطيف بنفس الطريقة وتعطيك كمون لكل عقدة. - **اليدوي والتلقائي يتكونان.** يدخل محول يعمل داخل نطاق مكتوب يدوياً تلك الجلسة والآباء إلى ذلك الوكيل، حتى تحصل على شجرة واحدة بدلاً من شجرتين — مفيد عندما تدرج إطار عمل بنفسك إلى جانب واحد مدعوم. + **اليدوي والتلقائي يتكونان.** محول يعمل داخل نطاق مكتوب يدويًا ينضم إلى تلك الجلسة والآباء لهذا الوكيل، لذا تحصل على شجرة واحدة بدلاً من اثنتين — مفيد عندما تدرج إطار عمل واحد بنفسك إلى جانب واحد مدعوم. - سببان، والفتحات الثلاثة أعلاه هي الإجابة على كليهما: + سببان، والطبقات الثلاث أعلاه هي الإجابة على كليهما: - `autogen-core` لم يتم صيانته منذ سبتمبر 2025. - - AG2 لا يعرض نقطة تسجيل على مستوى العملية تعادل خطافات أطر العمل الأخرى، لذا فإن إدراجها يعني تغليف كل وكيل في كل موقع البناء. + - لا تفضح AG2 نقطة تسجيل على مستوى العملية معادلة لخطاطيف أطر العمل الأخرى، لذا فإن إدراجها يعني لف كل وكيل في كل موقع بناء. - يسجل رسم الفتحات يدوياً نفس الأحداث، بنفس الدقة، كما سيفعل محول مشحون. + يسجل تخطيط الطبقات اليدوية نفس الأحداث، بنفس الدقة، كما سيفعل محول مشحون. ## الذهاب أعمق -كيف يعمل التسجيل فعلياً. لا شيء من هذا مطلوب للبدء. +كيف يعمل التسجيل بالفعل. لا شيء من هذا مطلوب للبدء. - + -كل تسجيل له نفس الشكل: يفتح امتداد، يتداخل العمل بداخله، وكل حدث افتتاحي يحصل على حدث إغلاق. +كل تسجيل له نفس الشكل: يفتح امتداد، يتداخل العمل داخله، وكل حدث فتح يحصل على حدث إغلاق. ```mermaid flowchart LR @@ -300,9 +301,9 @@ flowchart LR C --> E(["agent_end"]) ``` -**الزوج** هو الوحدة. كل حدث إغلاق يحمل مدة يقيسها SDK من الحدث الافتتاحي الخاص به. +**الزوج** هو الوحدة. كل حدث إغلاق يحمل مدة تقيسها SDK من حدثها الافتتاحي. -فيما يلي تشغيل واحد حقيقي لكل إطار عمل — مأخوذ من الأمثلة المشحونة مع SDK، اسم النموذج معياري. لاحظ كم يعود من نداء واحد. +فيما يلي تشغيل حقيقي واحد لكل إطار عمل — تم التقاطه من الأمثلة التي تشحن مع SDK، اسم النموذج معياري. لاحظ كم يعود من استدعاء واحد. @@ -323,7 +324,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - تصبح العقد أزواج خطاف، لذا تحصل على زمن الكمون لكل عقدة بدون أن تزحمها قائمة الوكيل. + تصبح العقد أزواج خطاطيف، لذا تحصل على كمون لكل عقدة دون أن تملأ قائمة الوكيل. @@ -340,7 +341,7 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - يصبح `role` لكل وكيل اسم امتداده، لذا ينقسم زمن الكمون ومصروف الرمز حسب الدور. + يصبح `role` لكل وكيل اسم امتداده، لذا ينقسم الكمون ومصروف التوكن حسب الدور. @@ -360,7 +361,7 @@ flowchart LR 26 +7.038s agent_end Agent · success ``` - حلقة الوكيل نفسها مرئية، ليس فقط نداءاته النموذجية. + حلقة الوكيل نفسها مرئية، وليس فقط استدعاءات النموذج الخاصة به. @@ -375,10 +376,10 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - لا توجد أزواج خطاف: Pydantic AI لا يملك حد عقدة أو خطوة للإحاطة به. + لا توجد أزواج خطاطيف: Pydantic AI ليس لديه حد عقدة أو خطوة لحيط. - + ```text 6 events 1 +0.000s agent_start main 2 +0.000s tool_use population @@ -388,7 +389,7 @@ flowchart LR 6 +0.000s agent_end main · success ``` - أنت تصدر هذه بنفسك. نفس أنواع الأحداث، نفس الدقة — إنه يكلفك مواقع الاستدعاء. + تصدر هذه بنفسك. نفس أنواع الأحداث، نفس الدقة — تكلفك مواقع المكالمة. @@ -396,28 +397,28 @@ flowchart LR -**لا توجد حدث نهاية الجلسة.** الجلسة ليست شيء تغلقه — إنها مجموعة من الأحداث تشترك في `session_id`. +**لا يوجد حدث نهاية جلسة.** الجلسة ليست شيئًا تغلقه — إنها مجموعة من الأحداث التي تشارك `session_id`. -يتم استخلاص الحالة من شكل التتبع: +يتم استنتاج الحالة من شكل التتبع: | الحالة | متى | | --- | --- | -| `ongoing` | لا يزال امتداد واحد على الأقل مفتوحاً | -| `paused` | `agent_pause` بدون `agent_resume` مطابقة | -| `error` | لا شيء مفتوح، وحدث واحد على الأقل فشل | -| `done` | لا شيء مفتوح، وشيء فشل | +| `ongoing` | لا يزال امتداد واحد على الأقل مفتوحًا | +| `paused` | `agent_pause` ليس له عنوان `agent_resume` المطابق | +| `error` | لا شيء مفتوح، وفشل حدث واحد على الأقل | +| `done` | لا شيء مفتوح، وفشل لا شيء | -لذلك تنتهي الجلسة عندما يتم إغلاق كل زوج. يصدر المحولات `agent_end` لك، وعند الهدم يغلقون أي شيء لا يزال مفتوحاً ويوقعونه كغير كامل — يستقر التشغيل المتعطل كـ `done` بفجوة مرئية بدلاً من التعليق. +لذا تنتهي الجلسة عندما يتم إغلاق كل زوج. تصدر المحولات `agent_end` نيابة عنك، وعند الهدم تغلق أي شيء لا يزال مفتوحًا وتصرفه كناقص — تستقر عملية تشغيل منهارة كـ `done` مع فجوة مرئية بدلاً من التعليق. - هذا هو السبب في أن الجلسة يمكن أن تمتد على نداءين. يوقف `interrupt()` في LangGraph التشغيل، يبقى الامتداد الجذري مفتوحاً عن قصد، والنداء المستأنف يغلقه. كلا النداءين جلسة واحدة. + هذا هو السبب في أن الجلسة يمكن أن تمتد على استدعاءين. يوقف `interrupt()` من LangGraph التشغيل، وامتداد الجذر يبقى مفتوحًا متعمدًا، واستدعاء الاستئناف يغلقه. كلا الاستدعاءين جلسة واحدة. - + -`session_id` و `agent_id` اختياريان في كل طريقة حدث. محذوفاً، يحلان من النطاق المرفق: +`session_id` و `agent_id` اختياريان على كل طريقة حدث. محذوف، يتم حلهما من النطاق المحيط: ```python with failproofai_sdk.session(): @@ -425,123 +426,123 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -تمريرهما بشكل صريح يعمل بعد ذلك ويأخذ الأسبقية. بدون شيء مرتبط وبدون شيء تم تمريره، يرفع الاستدعاء `TypeError` تسمية الإصلاح بدلاً من إصدار حدث بدون جلسة، والتي ستقفزها ingest مع الإجابة `200`. +تمريرها بشكل صريح لا يزال يعمل ويأخذ الأسبقية. بدون شيء مرتبط وبدون تمرير، يرفع الاستدعاء `TypeError` تسمي الإصلاح بدلاً من إصدار حدث بدون جلسة، والذي ستتخطاه الاستيعاب أثناء الإجابة `200`. -تربط النطاقات الهوية على متغيرات السياق. تلك تنتشر في مهام asyncio تلقائياً لكن ليس في خيوط جديدة — غلف عامل في `failproofai_sdk.propagate()`. +تربط النطاقات الهوية على متغيرات السياق. تنتشر تلك إلى مهام asyncio تلقائيًا ولكن ليس إلى خيوط جديدة — لف العامل في `failproofai_sdk.propagate()`. #### من يضرب أي معرف -| المعرف | تم ضربه بواسطة | ملاحظات | +| المعرف | يضرب بواسطة | ملاحظات | | --- | --- | --- | -| `session_id` | أنت، أو SDK | `session("chat-42")` يُستخدم حرفياً؛ محذوفاً، ينشئ SDK `uuid4().hex` | -| `agent_id` | أنت، أو الإطار | من `agent("analyst")`، `role` في CrewAI، `FunctionAgent.name`. يتم رفض قيمة تبدو مثل UUID واستبدالها | -| `tool_call_id`, `hook_id`, `request_id` | أنت، أو الإطار | تعيد المحولات استخدام معرفات التشغيل الخاصة بالإطار، وهذا هو السبب في أن الأزواج تبقى نقافز الخيط | -| **معرف الحدث** | **السحابة، عند الاستقبال** | SDK لا ينبعث أي | -| **`dedup_key`** | **السحابة، عند الاستقبال** | تجزئة org و session و timestamp و type و payload. هذه هي الهوية الحقيقية — إنها تجعل دفعة أعيد محاولتها تنهار بدلاً من التكرار | +| `session_id` | أنت، أو SDK | `session("chat-42")` يُستخدم حرفيًا؛ محذوف، SDK يُنشئ `uuid4().hex` | +| `agent_id` | أنت، أو الإطار | من `agent("analyst")`، أو `role` من CrewAI، أو `FunctionAgent.name`. تُرفض القيمة التي تبدو مثل UUID وتُستبدل | +| `tool_call_id`, `hook_id`, `request_id` | أنت، أو الإطار | تعيد المحولات استخدام معرفات التشغيل الخاصة بالإطار، وهذا هو السبب في بقاء الأزواج بعد قفزات الخيط | +| **معرف الحدث** | **السحابة، عند الاستيعاب** | SDK لا يصدر أي شيء | +| **`dedup_key`** | **السحابة، عند الاستيعاب** | بصمة تجزئة من org والجلسة والطابع الزمني والنوع والحمل. هذه هي الهوية الحقيقية — فهي تجعل دفعة معاد محاولتها تنهار بدلاً من التكرار | #### كيف تحل المحولات `session_id` -أول تطابق يفوز: +المباراة الأولى تفوز: -1. `session_id` خيار صريح -2. البيانات الوصفية لكل نداء -3. نطاق `session()` المرفق -4. بيانات إطار العمل الوصفية -5. معرف التشغيل الخاص بإطار العمل +1. `session_id` صريح خيار +2. البيانات الوصفية لكل استدعاء +3. نطاق `session()` المحيط +4. البيانات الوصفية للإطار +5. معرف التشغيل الخاص بالإطار -لا يتم اختراعه أبداً مع وجود أحد تلك — معرف مركب سيقسم تشغيل واحد عبر عدة جلسات. +لا يتم اختراعه أثناء وجود أحد هؤلاء — سيؤدي معرف مركب إلى تقسيم تشغيل واحد عبر عدة جلسات. -#### حافظ على `agent_id` على cardinality منخفضة +#### احتفظ بـ `agent_id` منخفض الأساسية -إنه الجانب الأساسي على كل سطح لوحة تحكم، وعمود `LowCardinality(String)`. تقلل القيمة لكل تشغيل العمود وتملأ قائمة القائمة المنسدلة بإدخال واحد لكل تشغيل. +إنه الجانب الأساسي على كل سطح لوحة معلومات، وعمود `LowCardinality(String)`. قيمة لكل تشغيل تضعف العمود وتملأ منتقي التصفية بإدخال واحد لكل تشغيل. -تحافظ المحولات على هذا العمود لك: +تدافع المحولات عن هذا العمود نيابة عنك: -| يسلم الإطار | مسجل باسم | لماذا | +| الإطار يسلّم | مسجل باسم | لماذا | | --- | --- | --- | -| `3f9a1c2b-…` (معرف فريد) | `main` | لا شيء يمكن قراءته للاحتفاظ به | -| سلسلة سادسة عشرية طويلة عارية | `main` | نفس | -| `agent-3f9a1c2b-…` | `agent` | تم تجريد معرف لكل تشغيل، تم الاحتفاظ بالجزء القابل للقراءة | -| `agent-v2` | `agent-v2` | تُترك الأجزاء القصيرة وحدها | -| `step-3` | `step-3` | نفس | +| `3f9a1c2b-…` (UUID) | `main` | لا شيء قابل للقراءة للحفظ | +| سلسلة سداسية عشرية عارية طويلة | `main` | نفس الشيء | +| `agent-3f9a1c2b-…` | `agent` | معرف كل تشغيل مقطوع، الجزء القابل للقراءة محفوظ | +| `agent-v2` | `agent-v2` | يتم ترك الأجزاء القصيرة وحدها | +| `step-3` | `step-3` | نفس الشيء | -المعرف الحقيقي يبقى على `fw_agent_id` / `fw_run_id`، حيث يبقى قابلاً للاستعلام بدون أن يكون جانباً. +معرف حقيقي محفوظ على `fw_agent_id` / `fw_run_id`، حيث يبقى قابلًا للاستعلام بدون أن يكون جانبًا. - **هذا الحراس يلمس فقط التسميات التي اختارها *الإطار*.** `agent_id` تمرره بنفسك — إلى `event.*`، أو إلى `failproofai_sdk.agent(...)` — مسجل تماماً كما هو محدد. إعادة كتابة صريحة لحجة صريحة ستكون أسوأ من cardinality التي تمنعها، لذا سمِّ امتدادات خاصة بك وفقاً لذلك. + **هذا الحارس يلمس فقط التسميات التي **اختارها الإطار**. `agent_id` تمرره بنفسك — إلى `event.*`، أو إلى `failproofai_sdk.agent(...)` — يتم تسجيله بالضبط كما هو معطى. إعادة كتابة حجة صريحة بصمت ستكون أسوأ من الأساسية التي تمنعها، لذا سمّ امتداداتك وفقًا لذلك. - + | المجموعة | الأحداث | | --- | --- | | الوكلاء | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | | النماذج | `model_request`, `model_response` | | الأدوات | `tool_use`, `tool_result` | -| الخطافات | `hook_triggered`, `hook_completed` | +| الخطاطيف | `hook_triggered`, `hook_completed` | | البشر | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | -| الأعطال | `error` | +| الأخطاء | `error` | -أي إطار عمل يسجل ماذا، مقاس من التشغيلات أعلاه: +أي إطار عمل يسجل ما، المقاس من التشغيلات أعلاه: -| الحدث | LangGraph | CrewAI | LlamaIndex | Pydantic AI | مخصص | +| الحدث | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | -| بداية الوكيل والنهاية | نعم | نعم | نعم | نعم | أنت | -| نموذج الطلب والاستجابة | نعم | نعم | نعم | نعم | أنت | -| استخدام الأداة والنتيجة | نعم | نعم | نعم | نعم | أنت | -| تم تشغيل الخطاف واكتمل | عقدة | مهمة | خطوة | — | أنت | -| خطأ | نعم | نعم | نعم | نعم | تلقائي | -| الانتظار البشري والمدخلات | نعم | نعم | نعم | — | أنت | -| الوكيل يوقف ويستأنف | نعم | نعم | نعم | — | أنت | +| بدء الوكيل ونهايته | Yes | Yes | Yes | Yes | You | +| طلب النموذج والرد | Yes | Yes | Yes | Yes | You | +| استخدام الأداة والنتيجة | Yes | Yes | Yes | Yes | You | +| تم تشغيل الخطاف واكتمل | Node | Task | Step | — | You | +| خطأ | Yes | Yes | Yes | Yes | Automatic | +| انتظار الإنسان والإدخال | Yes | Yes | Yes | — | You | +| إيقاف الوكيل واستئنافه | Yes | Yes | Yes | — | You | -الشرطة تعني أن الإطار ليس لديه مثل هذا المفهوم. `human_pause` و `human_interrupt` تصف *شخص* يتصرف على الوكيل، الذي لا يشير إليه أي إطار — انبعث بنفسك. +شرطة تعني الإطار ليس لديه مثل هذا المفهوم. `human_pause` و `human_interrupt` يصفان **شخصًا** يتصرف على الوكيل، والذي لا يشير إليه أي إطار عمل — أصدر هؤلاء بنفسك. -حدث لا يصل وحده أبداً. يفتح أحدهما امتداد، يغلقه الآخر، والحدث الإغلاق يحمل مدة يقيسها SDK من الحدث الافتتاحي. +حدث أبدًا لا يصل وحده. يفتح امتداد واحد، يغلق واحد، وحدث الإغلاق يحمل مدة تقيسها SDK من الحدث الافتتاحي. -| يفتح | يغلق | الحدث الإغلاق يحمل | +| يفتح | يغلق | حدث الإغلاق يحمل | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | -| `model_request` | `model_response` | الرموز، `stop_reason`، زمن الكمون | +| `model_request` | `model_response` | توكنات، `stop_reason`، الكمون | | `tool_use` | `tool_result` | `output` أو `error`، المدة | | `hook_triggered` | `hook_completed` | `outcome`، المدة | -| `agent_pause` | `agent_resume` | كم دامت الوقفة | -| `human_wait` | `human_input` | الإجابة، وكم استغرق الشخص | +| `agent_pause` | `agent_resume` | كم دامت الإيقافة | +| `human_wait` | `human_input` | الإجابة، وكم من الوقت استغرق الشخص | - حدث افتتاحي بدون حدث إغلاق هو امتداد لا ينتهي أبداً. تُرسّم الجلسة كما لا تزال قيد التشغيل، إلى الأبد، ومدتها النشطة تستمر في النمو. هذا هو فشل العرض الذي يجب مراقبته عند الإدراج يدوياً. + حدث افتتاح بدون إغلاق هو امتداد لا ينتهي. الجلسة تُعرض كما لو كانت لا تزال قيد التشغيل، إلى الأبد، ومدة نشاطها الفعلية تستمر في الزيادة. هذا هو وضع الفشل الذي يجب الحذر منه عندما تدرج يدويًا. #### قواعد الارتباط -- أعد استخدام نفس `tool_call_id` أو `hook_id` أو `pause_id` أو `input_id` لحدث الإكمال المطابق. -- حسابات SDK `duration_ms` لـ `tool_result` و `hook_completed` و `agent_resume` و `human_input`. تمريره إلى تلك الطرق يرفع `ValueError`. -- `duration_ms` **يُقبل** على `model_response`، لأن فقط المتصل يعرف زمن المزود الحقيقي. يجب أن يكون عدداً صحيحاً — عدد عشري يرفع `ValueError` في موقع الاستدعاء، لأن الخادم يقرأ العمود كعدد صحيح بدون إشارة 32 بت ويخزن NULL لأي شيء آخر. -- مفاتيح الارتباط مجالها حسب النوع والجلسة، لذا يمكن لاستدعاء أداة وخطاف مشاركة معرف بأمان، ويمكن لجلستين متزامنتين إعادة استخدام نفس المعرفات بدون تصادم. لا تكون مجالاً بواسطة وكيل: زوج مفتوح تحت وكيل واحد ومغلق تحت آخر لا يزال يرتبط، وهي الحالة العادية في الأطر متعددة الوكلاء. -- `request_id` يزاوج `model_request` مع `model_response`. بدونه، أحداث النموذج تتزاوج بالترتيب لكل وكيل، لذا تتزاوج النداءات المتزامنة بشكل خاطئ. -- زوج مقسم عبر العمليات لا يزال يرتبط في المصب، لكن SDK لا يمكنه حساب مدته في العملية. -- تمسك الخريطة المعلقة بـ 10,000 ابدأ كحد أقصى وتطرد الإدخال الأقدم عندما تكون ممتلئة. +- أعد استخدام نفس `tool_call_id`, `hook_id`, `pause_id`, أو `input_id` لحدث الإكمال المطابق. +- SDK يحسب `duration_ms` لـ `tool_result`, `hook_completed`, `agent_resume`, و `human_input`. تمريره إلى تلك الطرق يرفع `ValueError`. +- يتم قبول `duration_ms` **في** `model_response`، لأن المتصل فقط يعرف الكمون الحقيقي للمزود. يجب أن يكون عددًا صحيحًا — عدد عشري يرفع `ValueError` في موقع الاستدعاء، لأن الخادم يقرأ العمود كعدد صحيح بدون إشارة 32 بت وسيخزن NULL لأي شيء آخر. +- مفاتيح الارتباط محدودة حسب النوع والجلسة، لذا قد تشارك أداة وخطاف معرفًا بأمان، وقد تعيد جلستان متزامنتان استخدام نفس المعرفات بدون تضارب. لا تقتصر على الوكيل: الزوج الذي يُفتح تحت وكيل واحد ويُغلق تحت وكيل آخر لا يزال يرتبط، وهي الحالة العادية في أطر العمل متعددة الوكلاء. +- `request_id` يقترن `model_request` مع `model_response`. بدونه، تُقرن أحداث النموذج بالترتيب لكل وكيل، لذا تقترن المكالمات المتزامنة بشكل خاطئ. +- الزوج المقسم عبر العمليات لا يزال يرتبط باتجاه مصب النهر، لكن SDK لا يمكنه حساب مدته داخل العملية. +- خريطة قيد الانتظار تحتوي على 000 بداية على الأكثر، وتطرد الإدخال الأقدم عندما تكون ممتلئة. - + -تثبيت `failproofai-sdk` يثبت كل شيء، كل المحولات الأربعة مضمونة. تسحب الإضافات **الإطار**، وليس المحول. +تثبيت `failproofai-sdk` يثبت كل شيء، جميع محولات الأربعة مضمنة. تسحب الإضافات **الإطار**، وليس المحول. ```python import failproofai_sdk # loads nothing outside the standard library failproofai_sdk.instrument() # imports only the adapters you actually need ``` -`import failproofai_sdk` هو بدون تبعيات بموجب العقد، مفروض بواسطة اختبار يثبت العجلة المدمجة بـ `--no-deps` وآخر يثبت عدم وصول أي إطار إلى `sys.modules`. +`import failproofai_sdk` منطقيًا بدون تبعيات، يتم إنفاذه بواسطة اختبار يثبت الـ wheel المبني مع `--no-deps` وآخر يثبت عدم وصول أي إطار عمل إلى `sys.modules`. - لا يوجد `failproofai_sdk.crewai` تصريح. المحولات مقصودة عن قصد ألا تُعرّض على حزمة المستوى الأعلى: لمس أحدها سيستورد الإطار كتأثير جانبي لوصول السمة، مما يكسر وعد عدم التبعيات. استخدم `instrument()`. + لا يوجد `failproofai_sdk.crewai` attribute. المحولات متعمدة غير معروضة على حزمة المستوى الأعلى: لمس واحد كان سيستورد الإطار كأثر جانبي لوصول الخاصية، مكسرًا وعد عدم التبعية. استخدم `instrument()`. ```python @@ -550,14 +551,14 @@ failproofai_sdk.instrument("crewai") # exactly one, by name failproofai_sdk.uninstrument("crewai") # put it back ``` -| الاسم | يقبل أيضاً | +| الاسم | يقبل أيضًا | | --- | --- | | `langchain` | `langgraph`, `langchain_core` | | `crewai` | — | | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -قراءة الكشف التلقائي `sys.modules`، وليس قائمة الحزمة المثبتة، لذا فإن إطار عمل لديك مثبت لكن لم تستورده أبداً لا يتم إدراجه ولا يتم استيراده نيابة عنك. لرؤية ما هو موصول: +يقرأ الكشف التلقائي `sys.modules`، وليس قائمة الحزمة المثبتة، لذا الإطار الذي لديك مثبت لكن لم تستورده أبدًا لا يتم إدراجه ولا يتم استيراده بالنيابة عنك. لترى ما يتم وضعه: ```python from failproofai_sdk.integrations import active, available @@ -567,38 +568,38 @@ active() # ('langchain',) ``` - **`instrument("crewai")` على جهاز بدون CrewAI لا يرفع.** يسجل تحذيراً ويرجع `()`، حتى أحد إطر العمل المفقودة لا تأخذ عملية تدرج أيضاً آخرين. + **`instrument("crewai")` على آلة بدون CrewAI لا يرفع.** إنه يسجل تحذيرًا ويعود `()`، لذا إطار واحد مفقود لا يأخذ عملية تدرج الآخرين. - التحذير يحمل `ImportError` الأساسي، وتلك الرسالة تسمي أمر التثبيت الدقيق — لذا الإصلاح يكون في سجلاتك، ليس مختبئاً. + التحذير يحمل `ImportError` الأساسي، وتلك الرسالة تسمي أمر التثبيت الدقيق — لذا الإصلاح في سجلاتك، وليس مخفيًا. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - اضبط `FAILPROOFAI_SDK_STRICT=1` لإرفاعه بدلاً من ذلك. تُقرأ تلك العلم **مرة واحدة وتُخزن مؤقتاً**، لذا يصدرها قبل بدء العملية بدلاً من تعيينها في منتصف التشغيل. + اضبط `FAILPROOFAI_SDK_STRICT=1` لجعله يرفع بدلاً من ذلك. يتم قراءة هذا الرايز **مرة واحدة وتخزينه مؤقتًا**، لذا صدّره قبل أن تبدأ عمليتك بدلاً من تعيينه في منتصف التشغيل. - **`instrument()` يجب أن يأتي *بعد* استيراد إطار العمل الخاص بك.** قراءة الكشف التلقائي `sys.modules`، لذا نداء عارٍ فوق الاستيراد يجد لا شيء، يثبت لا شيء، ويرجع `()`. + **`instrument()` يجب أن يأتي *بعد* استيراد إطار العمل الخاص بك.** الكشف التلقائي يقرأ `sys.modules`، لذا استدعاء عاري فوق الاستيراد يجد لا شيء، ويثبت لا شيء، ويعود `()`. -```python خطأ +```python Wrong import failproofai_sdk failproofai_sdk.instrument() # sys.modules has no langchain yet -> () import langchain # too late, nothing is wired ``` -```python صحيح +```python Right import langchain # import the framework first import failproofai_sdk failproofai_sdk.instrument() # finds it -> ('langchain',) ``` -```python صحيح، مستقل الترتيب +```python Right, order-proof import failproofai_sdk # Naming it imports the adapter on request, so this works from anywhere. @@ -606,7 +607,7 @@ failproofai_sdk.instrument("langchain") ``` -احصل على هذا خطأ والعملية تعمل مع SDK مستوردة، المحول يبدو مثبتاً، و **حدث واحد لم يُصدر**. يسجل تحذيراً يقول بالضبط ذلك — لذا تحقق من السجلات أولاً عندما لا يسجل التشغيل شيئاً. +أخطئ في هذا والعملية تعمل مع SDK مستوردة، والمحول يبدو منصبًا، و **لم يصدر حدث واحد**. إنه يسجل تحذيرًا يقول بالضبط ذلك — لذا تحقق من سجلاتك أولاً عندما لا يسجل التشغيل شيئًا. @@ -614,85 +615,83 @@ failproofai_sdk.instrument("langchain") ```mermaid flowchart LR - A["وكيلك"] --> B["محول"] - B --> C["كاتب
قائمة الذاكرة"] - C -->|"كل 0.5s"| D["ملف
JSONL على القرص"] - D --> E["مراقب Failproof"] - E -->|"HTTPS"| F["السحابة"] + A["Your agent"] --> B["Adapter"] + B --> C["Writer
in-memory queue"] + C -->|"every 0.5s"| D["Spool
JSONL on disk"] + D --> E["Failproof daemon"] + E -->|"HTTPS"| F["Cloud"] ``` | المرحلة | الوظيفة | يعمل في | | --- | --- | --- | -| محول | ترجمة رد اتصال الإطار إلى أحد أنواع الأحداث 15 | عمليتك | -| كاتب | طوابير، دفعات، كتابة JSONL ذرية | عمليتك، خيط الخلفية | -| ملف | نقل دائم، ينجو من خروج عملية | القرص المحلي | -| مراقب | يراقب الملف، سفن دفعات، حذف ما ينقله | آلتك | -| استقبال | يعين معرف صف و dedup key، يرقي أعمدة قابلة للاستعلام | السحابة | +| المحول | يترجم استدعاء استدعاء الإطار إلى أحد أنواع الأحداث الـ 15 | عمليتك | +| الكاتب | يصف قائمة، دفعات، يكتب JSONL بذرية | عمليتك، خيط خلفي | +| البكرة | نقل متين، يبقى بعد خروج عمليتك | قرص محلي | +| الشيطان | يراقب البكرة، يشحن الدفعات، يحذف ما شحنه | آلتك | +| الاستيعاب | يعين معرف الصف ومفتاح dedup، ينقل الأعمدة القابلة للاستعلام | السحابة | -الملف هو ما يجعل هذا آمناً: وكيلك لا يسد أبداً على الشبكة، وانقطاع السحابة يعني دليل ينمو بدلاً من فقدان الأحداث. +البكرة هي ما يجعل هذا آمنًا: وكيلك لا ينتظر أبدًا الشبكة، وانقطاع السحابة يعني ديريتوري متنامي بدلاً من فقدان الأحداث. -كل تنظيف يكتب ملف دفعة واحدة، `.tmp` أولاً، ثم `fsync`، ثم إعادة تسمية ذرية: +كل تصريف يكتب ملف دفعة واحدة، `.tmp` أولاً، ثم `fsync`، ثم إعادة تسمية ذرية: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -يختار المراقب فقط `.jsonl`، لذا لا يمكن أبداً قراءة ملف نصف مكتوب. الجذع يحمل طابع زمني، معرف العملية ورقم التسلسل، لذا لا يمكن لعمليتين تنظيف في نفس الميلي ثانية أن تصطدما. تُغطى القائمة بـ 10,000 حدث؛ بعد ذلك تسقط الأقدم وتسجل. +الشيطان يلتقط `.jsonl` فقط، لذا لا يمكنه أبدًا قراءة ملف نصف مكتوب. الساق يحمل طابعًا زمنيًا ومعرف عملية ورقم تسلسل، لذا عمليتان تصريفتان في نفس الميلي ثانية لا يمكن أن تصطدما. يتم تغطية قائمة الانتظار بـ 000 حدث؛ بعد ذلك يسقط الأقدم ويسجل. - **`collector.redact` لا ينطبق على أحداث SDK الخاصة بك.** لا يراها أبداً. + **`collector.redact` يافتراضي إلى `minimal` لأحداث SDK أيضًا.** يكشط SDK قبل كتابة دفعة على القرص، ويكرر الشيطان نفس المسار الحتمي قبل التحميل بحيث تكون الدفعات من SDKs الأقدم محمية. -المراقب **ينقل** دفعاتك. إنه لا يفتحها أو يعيد كتابتها. +يقرأ الشيطان كل دفعة ويطبق الكشط في الذاكرة قبل التحميل. لا يعيد كتابة ملف البكرة الذي قرأه. -| الأحداث | مكتوب بواسطة | معاد بواسطة `collector.redact`؟ | +| الأحداث | مكتوب بواسطة | أين يعمل الكشط الحد الأدنى | | --- | --- | --- | -| نصوص جلسة CLI | المراقب | نعم | -| نشاط الخطاف | المراقب | نعم | -| **كل ما يصدره SDK** | **عمليتك** | **لا** | - -التعديل يعمل حيث **يكتب** المراقب أحداثه الخاصة — وليس حيث تُنقل الدفعات. لذا طلب أو حجة أداة تحمل مفتاح API لا تزال تحمله عند الوصول. +| نصوص جلسات CLI | الشيطان | قبل كتابة الشيطان للدفعة | +| نشاط الخطاطيف | الشيطان | قبل كتابة الشيطان للدفعة | +| **كل شيء يصدره SDK** | **عمليتك** | **قبل كتابة SDK للدفعة وقبل تحميل الشيطان مرة أخرى** | -هذا مقصود. هذه هي نداءات الإدراج الخاصة بك، وإعادة الكتابة في الحركة ستعني أن الأحداث التي تستقبلها ليست الأحداث التي أصدرتها. +اضبط `collector.redact` على `off` فقط عندما تكون الحمولات الحرفية متطلبًا صريحًا؛ SDK والشيطان كلاهما يحترم هذا الإعداد. يمسك الكشط الحد الأدنى مفاتيح API الشائعة والتوكنات الحاملة و JWTs والتنازلات السرية. لا يمكنها تحديد نثر حساس تعسفي. - **أنت تتحكم في الحمولات من المصدر، في مكانين:** + **تتحكم في الحمولات في المصدر، في مكانين:** - - أوقف التقاط المحتوى على المحول. **اسم الخيار يختلف، ومحول واحد لا يملك أي** — هذا ليس مفتاح عام واحد: - - LangChain / LangGraph, Pydantic AI — `capture_content=False` + - أطفئ التقاط المحتوى على المحول. **اسم الخيار يختلف، وأحد المحولات ليس لديه** — هذا ليس مفتاحًا عامًا واحدًا: + - LangChain / LangGraph، Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **لا مفتاح محتوى على الإطلاق**؛ `session_id` هو الخيار الوحيد الذي يقرأه، لذا يتم تسجيل الطلبات والإكمالات دائماً. + - CrewAI — **لا توجد مفاتيح محتوى على الإطلاق**؛ `session_id` هو الخيار الوحيد الذي تقرأه، لذا يتم تسجيل المطالبات والإكمالات دائمًا. - `instrument()` يسقط الخيارات التي لا يقرأها محول، لذا تمرير الاسم الخاطئ لا يرفع شيء ولا يغير شيء. - - لا تسلم السر إلى `input=` في المقام الأول. + `instrument()` يسقط الخيارات التي لا يقرأها محول، لذا تمرير الاسم الخاطئ لا يرفع شيئًا ولا يغير شيئًا. + - لا تسلم السر `input=` في المقام الأول. - `collector.redact` ليس بديلاً عن أي منهما. + `collector.redact` دفاع متعمق، وليس بديلاً لأي منهما. - **دليل ملف فارغ هو الحالة الصحية.** لا تستخدمه للتحقق من التسليم. + **ديريتوري بكرة فارغ هو الحالة الصحية.** لا تستخدمه للتحقق من التسليم. -يحذف المراقب كل دفعة في غضون ميلي ثانية من نقلها، لذا فإن `ls` يتسابق المجمع ويظهر جزء من ما أصدرته — لا يمكن تمييزه عن SDK لم يسجل شيء. +يحذف الشيطان كل دفعة في ميلي ثانية من شحنها، لذا `ls` يتسابق مع جامع البيانات ويُظهر جزءًا من ما أصدرته — لا يمكن تمييزه عن SDK لم يسجل شيئًا. -للتأكد من أن الأحداث هبطت فعلاً، تحقق من لوحة التحكم. لمراقبة امتلاء الملف، توقف المراقب أولاً. +لتأكيد وصول الأحداث بالفعل، تحقق من لوحة المعلومات. لمراقبة ملء البكرة، توقف الشيطان أولاً. - + -كل رد اتصال يعمل داخل غلاف وظيفته الوحيدة هي إعادة الرفع، لذا استدعاؤك يجلس في `try` واحدة بالضبط وكل شيء SDK يحدث خارجها. +كل استدعاء يعمل داخل غلاف وظيفته الوحيدة إعادة الرفع، لذا استدعاؤك يجلس في `try` واحد تمامًا وكل ما يفعله SDK يحدث خارجه. | ما يحدث | النتيجة | | --- | --- | -| خطاف يرفع | مسجل مرة واحدة مع traceback الخاص به. استدعاؤك غير متأثر | -| نفس الخطاف يرفع ثلاث مرات | يتم تعطيل ذاك الخطاف للعملية المتبقية، مع سطر خطأ واحد | -| `FAILPROOFAI_SDK_STRICT=1` معين | يتم إعادة رفع الاستثناء بدلاً من ذلك | +| خطاف يرفع | مسجل مرة واحدة مع التتبع الخاص به. استدعاؤك لم يتأثر | +| نفس الخطاف يرفع ثلاث مرات | يتم تعطيل هذا الخطاف الواحد لبقية العملية، بسطر خطأ واحد | +| `FAILPROOFAI_SDK_STRICT=1` تم تعيينه | يتم إعادة رفع الاستثناء بدلاً من ذلك | | إصدار إطار عمل خارج النطاق المختبر | يحذر مرة واحدة، يدرج على أي حال | -| قدرة واحدة مفقودة | يتم تعطيل ذاك الخطاف فقط، لا أبداً محول كامل | +| قدرة واحدة مفقودة | يتم تعطيل هذا الخطاف الواحد، ليس المحول كله | -الافتراضي صحيح في الإنتاج وخاطئ أثناء التصحيح، لأنه لا يمكن أبداً إثبات أنه لم يتعطل. اضبط `FAILPROOFAI_SDK_STRICT=1` لإسكات الفشل المبتلع. +الافتراضي صحيح في الإنتاج وخاطئ أثناء التصحيح، لأنه يمكن فقط إثبات أنه لم ينهار. اضبط `FAILPROOFAI_SDK_STRICT=1` لجعل الفشل المبلل عالي الصوت. @@ -701,24 +700,24 @@ flowchart LR ## مشاكل شائعة - - حدث افتتاحي بدون حدث إغلاق: `model_request` بدون `model_response`، أو `tool_use` بدون `tool_result`. استخدم النطاقات، التي تضمن الزوج حتى عندما يرفع الجسم. إذا استدعيت طرق الحدث مباشرة، استخدم `try` و `finally`. + + حدث افتتاح بدون إغلاق: `model_request` بدون `model_response`، أو `tool_use` بدون `tool_result`. استخدم النطاقات، التي تضمن الزوج حتى عندما يرفع الجسم. إذا استدعيت طرق الحدث مباشرة، استخدم `try` و `finally`. - يتم قياسه من حدث الافتتاح المطابق، لذا يتم رفضه على `tool_result` و `hook_completed` و `agent_resume` و `human_input`. يتم قبوله على `model_response`، لأن فقط أنت تعرف زمن المزود الحقيقي، ويجب أن يكون عدداً صحيحاً. + يتم قياسه من حدث الفتح المطابق، لذا يتم رفضه على `tool_result`, `hook_completed`, `agent_resume`, و `human_input`. يتم قبوله على `model_response`، لأن فقط أنت تعرف كمون المزود الحقيقي، ويجب أن يكون عددًا صحيحًا. - - الخيط لم يرث السياق أبداً. غلف الدالة في `failproofai_sdk.propagate()`. انظر [الخيوط و async](#threads-and-async). + + الخيط لم يرث السياق أبدًا. لف الاستدعاء في `failproofai_sdk.propagate()`. انظر [الخيوط والعمليات غير المتزامنة](#threads-and-async). - - الحقول الإضافية تدمج آخراً، لذا أحد باسم مثل حقل حقيقي مثل `model` أو `outcome` سيكتب فوقه ويغير عمود مخزن. مساحة أسماء لك؛ المحولات تستخدم بادئة `fw_`. + + الحقول الإضافية تدمج أخيرًا، لذا الحقل المسمى مثل حقل حقيقي مثل `model` أو `outcome` كان سيستبدله ويغير عمودًا مخزنًا. مساحة الأسماء لك؛ المحولات تستخدم بادئة `fw_`. - - `agent_id` هو جانب cardinality منخفض وأنت وضعت معرف تشغيل فيه. استخدم دوراً أو اسم عقدة وضع المعرف الحقيقي في حقل الحمولة. + + `agent_id` هو جانب منخفض الأساسية وأدخلت معرف التشغيل. استخدم اسم دور أو عقدة وضع المعرف الحقيقي في حقل حمولة. @@ -728,10 +727,10 @@ flowchart LR الأزواج والمعرفات ودورة حياة الجلسة والتسليم. - - اتبع السببية عبر الجلسة التي التقطتها للتو. + + اتبع السببية عبر الجلسة التي استعرتها للتو. - LangGraph و CrewAI و LlamaIndex و Pydantic AI. + LangGraph، CrewAI، LlamaIndex، و Pydantic AI. \ No newline at end of file diff --git a/docs/de/start/integrations/custom-agents.mdx b/docs/de/start/integrations/custom-agents.mdx index 824fb42f..9e643a29 100644 --- a/docs/de/start/integrations/custom-agents.mdx +++ b/docs/de/start/integrations/custom-agents.mdx @@ -5,9 +5,9 @@ description: "Instrumentiere einen selbst geschriebenen Agenten oder ein Framewo icon: "code" --- -Für einen selbst geschriebenen Agenten oder ein Framework, für das Failproof AI keinen Adapter hat. Es ist nichts zu instrumentieren: Du sendest die Events selbst. +Für selbst geschriebene Agenten oder Frameworks, für die Failproof AI keinen Adapter bereitstellt. Es gibt nichts zu instrumentieren: Du sendest die Events selbst. -Das ist dieselbe API, die die vier Framework-Adapter im Hintergrund nutzen. Sie sind lediglich Übersetzungsschichten darüber. +Das ist dieselbe API, die auch die vier Framework-Adapter intern verwenden. Sie sind lediglich Übersetzungstabellen darüber. ## Installation @@ -30,23 +30,23 @@ with failproofai_sdk.session(): # ein Durchlauf t.output = search(q) # ein Tool-Aufruf ``` -Von oben nach unten gelesen, sagt es genau das, was es bedeutet: +Von oben nach unten gelesen erklärt sich der Code von selbst: -| Umschließen mit | Bedeutet | +| Einschließen mit | Bedeutung | | --- | --- | | `session()` | Diese Events gehören zum selben Durchlauf | -| `agent()` | Etwas erledigt Arbeit – gib ihm einen Namen, den du in einer Liste erkennen würdest | -| `tool_call()` | Das ist ein Tool, und hier ist sein Rückgabewert | +| `agent()` | Etwas verrichtet Arbeit – gib ihm einen erkennbaren Namen | +| `tool_call()` | Das ist ein Tool-Aufruf, und das ist sein Ergebnis | -Und was jeder Scope tatsächlich sendet: +Und was jedes davon tatsächlich sendet: | Scope | Sendet | Zweck | | --- | --- | --- | -| `session()` | Nichts | Bindet eine Session-ID, gruppiert einen Durchlauf | -| `agent()` | `agent_start`, `agent_end` | Klammert eine Arbeitseinheit ein | -| `tool_call()` | `tool_use`, `tool_result` | Klammert ein Tool ein und misst es | +| `session()` | Nichts | Bindet eine Session-ID und gruppiert einen Durchlauf | +| `agent()` | `agent_start`, `agent_end` | Klammert eine Arbeitseinheit | +| `tool_call()` | `tool_use`, `tool_result` | Klammert einen Tool-Aufruf und misst ihn | -Alles darin kann `session_id` und `agent_id` weglassen. Die Scopes binden die Identität auf Kontextvariablen, und jeder Event-Aufruf liest sie zurück – du musst IDs nie durch deine Funktionen durchreichen. +Alles im Inneren kann `session_id` und `agent_id` weglassen. Die Scopes binden die Identität an Kontextvariablen, und jeder Event-Aufruf liest sie von dort – du musst keine IDs durch deine Funktionen durchreichen. Alle drei funktionieren sowohl mit `async with` als auch mit `with`. @@ -61,20 +61,20 @@ with failproofai_sdk.session(): ## Wie ein Scope schließt -`agent()` behandelt Exceptions für dich: +`agent()` behandelt Ausnahmen für dich: -| Was passiert ist | Events | Ergebnis | +| Was passiert | Events | Ergebnis | | --- | --- | --- | -| Keine Exception | `agent_end` | `success` | +| Keine Ausnahme | `agent_end` | `success` | | `Exception` | `error`, dann `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, dann `agent_end` | `failed` | -| `CancelledError`, `GeneratorExit` | nur `agent_end` | `cancelled` | +| `CancelledError`, `GeneratorExit` | Nur `agent_end` | `cancelled` | -Der Fehler wird vor `agent_end` gesendet, weil das Dashboard den Span bei `agent_end` schließt und alles danach keinem Span mehr zugeordnet wird. Eine Stornierung ist kein Fehler, daher verschmutzen abgebrochene Durchläufe die Fehlerübersicht nicht. Die Exception wird immer erneut ausgelöst: Ein Scope verschluckt sie nie. +Der Fehler wird vor `agent_end` gesendet, weil das Dashboard den Span bei `agent_end` schließt und alles Spätere keinem Span mehr zugeordnet wird. Ein Abbruch ist kein Fehler, daher verschmutzen abgebrochene Durchläufe die Fehleransicht nicht. Die Ausnahme wird immer weitergeleitet – ein Scope schluckt niemals. ## Die Event-Methoden -Fünfzehn Methoden in sechs Familien. Die meisten kommen paarweise – du sendest den Öffner, dann den Schließer, und das SDK misst den Span dazwischen. +Fünfzehn Methoden in sechs Familien. Die meisten kommen paarweise – du sendest den Öffner, dann den Schließer, und das SDK misst die Zeitspanne dazwischen. | Familie | Öffnet | Schließt | Eigenständig | | --- | --- | --- | --- | @@ -87,7 +87,7 @@ Fünfzehn Methoden in sechs Familien. Die meisten kommen paarweise – du sendes | **Fehler** | — | — | `error` | - Bevorzuge die Scopes – `agent()` und `tool_call()` – wo immer sie passen. Sie garantieren das schließende Event, auch wenn der Body eine Exception wirft. Greife direkt auf diese Methoden zurück, wenn dein Kontrollfluss nicht verschachtelt ist, z. B. bei einem Modellaufruf innerhalb eines Hilfsfunktions. + Bevorzuge die Scopes – `agent()` und `tool_call()` – wo immer sie passen. Sie garantieren das schließende Event auch dann, wenn der Rumpf eine Ausnahme wirft. Greife direkt auf diese Methoden zurück, wenn dein Kontrollfluss nicht schachtelt, etwa bei einem Modellaufruf innerhalb einer Hilfsfunktion. @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **Die beiden Human-Familien zeigen in entgegengesetzte Richtungen.** + **Die zwei Human-Familien zeigen in entgegengesetzte Richtungen.** | Methoden | Bedeutung | | --- | --- | | `human_wait` / `human_input` | Der **Agent hat eine Person gefragt** – ein Freigabe-Gate, eine Rückfrage | | `human_pause` / `human_interrupt` | Eine **Person hat auf den Agenten eingewirkt** – ein Stopp-Button, eine Operator-Pause | - Kein Framework signalisiert das zweite Paar – das musst du immer selbst senden. + Kein Framework signalisiert das zweite Paar – es liegt immer an dir, diese Events zu senden. - **Übergib `request_id`, wenn Modellaufrufe parallel laufen.** Ohne sie werden Anfragen und Antworten in Eingangsreihenfolge pro Agent gepaart – und parallele Aufrufe werden falsch gepaart, sodass jede Antwort der falschen Anfrage zugeordnet wird. + **Übergib `request_id`, wenn Modellaufrufe gleichzeitig laufen.** Ohne sie werden Anfragen und Antworten in Empfangsreihenfolge pro Agent zugeordnet – bei gleichzeitigen Aufrufen entstehen so falsche Paarungen, bei denen jede Antwort der falschen Anfrage zugewiesen wird. ## Beispiel -Eine Tool-Calling-Schleife gegen die OpenAI API, ohne Agent-Framework: +Eine Tool-Calling-Schleife gegen die OpenAI-API, ohne Agent-Framework: ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """Ein Modellaufruf, eingerahmt durch das Paar.""" + """Ein Modellaufruf, eingeklammert durch das Paar.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # begrenzt; eine unbegrenzte Agent-Schleife ist ein eigener Fehler + for _ in range(4): # begrenzt; eine unbegrenzte Agentenschleife ist ein eigener Fehler message = turn(messages) if not message.tool_calls: break @@ -204,47 +204,45 @@ with failproofai_sdk.session(): }) ``` -Das erzeugt dieselben sechs Event-Typen, die ein Adapter liefern würde. Die vollständige -ausführbare Version inklusive Tool-Definitionen liegt im SDK-Repository unter -`docs/manual/examples/`. +Das erzeugt dieselben sechs Event-Typen, die auch ein Adapter liefern würde. Die vollständige, ausführbare Version mit den Tool-Definitionen liegt im SDK-Repository unter `docs/manual/examples/`. -## Threads und Async +## Threads und async -Kontextvariablen werden automatisch in asyncio-Tasks übertragen. In neue Threads werden sie nicht übertragen, da ein Thread mit einem leeren Kontext startet. +Kontextvariablen werden automatisch in asyncio-Tasks weitergegeben. In neue Threads werden sie nicht weitergegeben, da ein Thread mit einem leeren Kontext startet. ```python # asyncio: nichts zu tun async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# Threads: Callable einwickeln +# Threads: das Callable einwickeln pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Ohne `propagate()` wirft das Worker-Event einen `TypeError`, der den Fix benennt, anstatt auf keiner Session zu landen. Das ist beabsichtigt: Ein Event ohne Session wird beim Ingest übersprungen und mit `200` beantwortet – das ist genau der stille Fehler, den die Identitätsschicht verhindern soll. +Ohne `propagate()` werfen die Events des Workers einen `TypeError`, der den Fix benennt, anstatt auf keiner Session zu landen. Das ist beabsichtigt: Ein Event ohne Session wird bei der Verarbeitung übersprungen und mit `200` beantwortet – genau der stille Fehler, den die Identitätsschicht verhindern soll. ## Ein Framework ohne Adapter instrumentieren -Jedes Agent-Framework gibt dir dieselben drei Nahtpunkte. Mappe sie und du hast eine vollständige Trace – die vier mitgelieferten Adapter tun nichts anderes. +Jedes Agent-Framework bietet dieselben drei Ansatzpunkte. Bilde sie ab und du hast einen vollständigen Trace – die vier mitgelieferten Adapter tun nichts weiter als das. -| Der Nahtpunkt | Was du schreibst | Was landet | +| Der Ansatzpunkt | Was du schreibst | Was landet | | --- | --- | --- | | Der Durchlauf | `session()` + `agent()` | `agent_start`, `agent_end` | -| Jedes Tool | `tool_call()` | `tool_use`, `tool_result` | +| Jeder Tool-Aufruf | `tool_call()` | `tool_use`, `tool_result` | | Jeder Modellaufruf | Das `model_*`-Paar | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - In was auch immer das Framework als Tool-Wrapper oder Middleware bezeichnet. + + In dem, was das Framework als Tool-Wrapper oder Middleware bezeichnet. ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -266,20 +264,20 @@ Jedes Agent-Framework gibt dir dieselben drei Nahtpunkte. Mappe sie und du hast - **Hast du eine Node-, Step- oder Middleware-Grenze, die es wert ist, sichtbar zu sein?** Wickle sie in ein Hook-Paar – `hook_triggered` / `hook_completed` – und nicht in ein verschachteltes `agent()`. `agent_id` ist eine Facette mit niedriger Kardinalität, und ein Eintrag pro Node überfüllt sie. Hook-Spans werden genauso dargestellt und geben dir Latenz pro Node. + **Gibt es eine Node-, Step- oder Middleware-Grenze, die sichtbar sein soll?** Wickle sie in ein Hook-Paar – `hook_triggered` / `hook_completed` – nicht in ein verschachteltes `agent()`. `agent_id` ist eine Facette mit niedriger Kardinalität, und ein Eintrag pro Node würde sie überfluten. Hook-Spans werden genauso gerendert und liefern dir die Latenz pro Node. - **Manuell und automatisch komponieren.** Ein Adapter, der innerhalb eines manuell erstellten Scopes läuft, schließt sich dieser Session an und wird dem Agenten als übergeordnet zugeordnet – du bekommst einen Baum statt zwei. Das ist nützlich, wenn du ein Framework selbst instrumentierst, das neben einem unterstützten läuft. + **Manuelle und automatische Instrumentierung ergänzen sich.** Ein Adapter, der innerhalb eines handgeschriebenen Scopes läuft, tritt der Session bei und wird dem Agenten untergeordnet – du erhältst einen einzigen Baum statt zwei. Das ist nützlich, wenn du ein Framework selbst instrumentierst und gleichzeitig ein unterstütztes verwendest. - Zwei Gründe, und die drei Nahtpunkte oben sind die Antwort auf beide: + Zwei Gründe, und die drei Ansatzpunkte oben sind die Antwort auf beide: - `autogen-core` wird seit September 2025 nicht mehr gepflegt. - - AG2 bietet keinen prozessweiten Registrierungspunkt, der dem Hook-System der anderen Frameworks entspricht – die Instrumentierung erfordert daher das Einwickeln jedes Agenten an jeder Konstruktionsstelle. + - AG2 bietet keinen prozessweiten Registrierungspunkt, der den Hooks anderer Frameworks entspricht, sodass die Instrumentierung bedeutet, jeden Agenten an jeder Konstruktionsstelle zu wrappen. - Das manuelle Mappen der Nahtpunkte zeichnet dieselben Events mit derselben Genauigkeit auf wie ein mitgelieferter Adapter. + Durch manuelles Abbilden der Ansatzpunkte werden dieselben Events mit derselben Genauigkeit aufgezeichnet wie durch einen mitgelieferten Adapter. ## Tiefer eintauchen @@ -288,9 +286,9 @@ Wie die Aufzeichnung tatsächlich funktioniert. Nichts davon ist nötig, um losz - + -Jede Aufzeichnung hat dieselbe Form: Ein Span öffnet sich, Arbeit wird darin verschachtelt, und jedes öffnende Event bekommt ein schließendes. +Jede Aufzeichnung hat dieselbe Form: Ein Span öffnet sich, Arbeit schachtelt sich hinein, und jeder öffnende Event erhält einen schließenden. ```mermaid flowchart LR @@ -302,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -Das **Paar** ist die Einheit. Jedes schließende Event trägt eine Dauer, die das SDK vom öffnenden Event an misst. +Das **Paar** ist die Grundeinheit. Jeder schließende Event trägt eine Dauer, die das SDK vom öffnenden Event an gemessen hat. -Unten ist ein realer Durchlauf pro Framework – aufgenommen aus den Beispielen, die mit dem SDK mitgeliefert werden, Modellname normalisiert. Beachte, wie viel von einem einzigen Aufruf zurückkommt. +Unten ist je ein echter Durchlauf pro Framework – aufgezeichnet aus den Beispielen, die mit dem SDK geliefert werden, Modellname normalisiert. Beachte, wie viel ein einzelner Aufruf zurückliefert. @@ -325,7 +323,7 @@ Unten ist ein realer Durchlauf pro Framework – aufgenommen aus den Beispielen, 14 +5.721s agent_end LangGraph · success ``` - Nodes werden zu Hook-Paaren, sodass du Latenz pro Node erhältst, ohne die Agentenliste zu überfüllen. + Nodes werden zu Hook-Paaren, sodass du die Latenz pro Node erhältst, ohne die Agentenliste zu überfüllen. @@ -342,7 +340,7 @@ Unten ist ein realer Durchlauf pro Framework – aufgenommen aus den Beispielen, 10 +5.739s agent_end crew · success ``` - Die `role` jedes Agenten wird zu seinem Span-Namen, sodass Latenz und Token-Verbrauch pro Rolle aufgeschlüsselt werden. + Die `role` jedes Agenten wird zu seinem Span-Namen, sodass Latenz und Token-Verbrauch nach Rolle aufgeschlüsselt werden. @@ -362,7 +360,7 @@ Unten ist ein realer Durchlauf pro Framework – aufgenommen aus den Beispielen, 26 +7.038s agent_end Agent · success ``` - Die Agent-Schleife selbst ist sichtbar, nicht nur ihre Modellaufrufe. + Die Agentenschleife selbst ist sichtbar, nicht nur ihre Modellaufrufe. @@ -377,7 +375,7 @@ Unten ist ein realer Durchlauf pro Framework – aufgenommen aus den Beispielen, 8 +8.119s agent_end agent · success ``` - Keine Hook-Paare: Pydantic AI hat keine Node- oder Step-Grenzen zum Einrahmen. + Keine Hook-Paare: Pydantic AI hat keine Node- oder Step-Grenze zum Einklammern. @@ -390,17 +388,17 @@ Unten ist ein realer Durchlauf pro Framework – aufgenommen aus den Beispielen, 6 +0.000s agent_end main · success ``` - Du sendest diese selbst. Dieselben Event-Typen, dieselbe Genauigkeit – es kostet dich die Aufrufstellen. + Diese sendest du selbst. Dieselben Event-Typen, dieselbe Genauigkeit – es kostet dich die Aufrufstellen. - + -**Es gibt kein Session-End-Event.** Eine Session ist nichts, das du schließt – sie ist eine Gruppe von Events, die eine `session_id` teilen. +**Es gibt kein Session-End-Event.** Eine Session ist nichts, das man schließt – sie ist eine Gruppe von Events, die dieselbe `session_id` teilen. -Der Status wird aus der Form der Trace abgeleitet: +Der Status wird aus der Form des Traces abgeleitet: | Status | Wann | | --- | --- | @@ -409,10 +407,10 @@ Der Status wird aus der Form der Trace abgeleitet: | `error` | Nichts ist offen, und mindestens ein Event ist fehlgeschlagen | | `done` | Nichts ist offen, und nichts ist fehlgeschlagen | -Eine Session endet also, wenn jedes Paar geschlossen ist. Die Adapter senden `agent_end` für dich, und beim Teardown schließen sie alles noch Offene und markieren es als unvollständig – ein abgestürzter Durchlauf wird als `done` mit einer sichtbaren Lücke abgeschlossen, statt hängen zu bleiben. +Eine Session endet also, wenn jedes Paar geschlossen wurde. Die Adapter senden `agent_end` für dich und schließen beim Beenden alles noch Offene, markiert als unvollständig – ein abgestürzter Durchlauf endet als `done` mit einer sichtbaren Lücke, statt hängenzubleiben. - Deshalb kann eine Session zwei Aufrufe umspannen. Ein LangGraph `interrupt()` pausiert den Durchlauf, der Root-Span bleibt absichtlich offen, und der fortsetzende Aufruf schließt ihn. Beide Aufrufe gehören zu einer Session. + Deshalb kann eine Session zwei Aufrufe überspannen. Ein LangGraph `interrupt()` pausiert den Durchlauf, der Root-Span bleibt absichtlich offen, und der wiederaufnehmende Aufruf schließt ihn. Beide Aufrufe sind eine Session. @@ -427,23 +425,23 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Sie explizit zu übergeben funktioniert weiterhin und hat Vorrang. Wenn nichts gebunden und nichts übergeben wurde, wirft der Aufruf einen `TypeError`, der den Fix benennt, anstatt ein Event ohne Session zu senden, das beim Ingest übersprungen und mit `200` beantwortet werden würde. +Sie explizit zu übergeben funktioniert ebenfalls und hat Vorrang. Ist nichts gebunden und nichts übergeben, wirft der Aufruf einen `TypeError`, der den Fix benennt, statt ein Event ohne Session zu senden, das die Verarbeitung überspringen und mit `200` antworten würde. -Scopes binden die Identität auf Kontextvariablen. Diese werden automatisch in asyncio-Tasks übertragen, aber nicht in neue Threads – wickle einen Worker in `failproofai_sdk.propagate()` ein. +Scopes binden Identität an Kontextvariablen. Diese werden automatisch in asyncio-Tasks weitergegeben, aber nicht in neue Threads – wickle einen Worker in `failproofai_sdk.propagate()`. #### Wer welche ID vergibt | ID | Vergeben von | Hinweise | | --- | --- | --- | -| `session_id` | Dir oder dem SDK | `session("chat-42")` wird direkt verwendet; weggelassen generiert das SDK ein `uuid4().hex` | +| `session_id` | Dir oder dem SDK | `session("chat-42")` wird unverändert verwendet; wird sie weggelassen, generiert das SDK ein `uuid4().hex` | | `agent_id` | Dir oder dem Framework | Aus `agent("analyst")`, einer CrewAI-`role`, einem `FunctionAgent.name`. Ein UUID-ähnlicher Wert wird abgelehnt und ersetzt | -| `tool_call_id`, `hook_id`, `request_id` | Dir oder dem Framework | Adapter verwenden die eigenen Run-IDs des Frameworks wieder, weshalb Paare Thread-Wechsel überleben | -| **Event-ID** | **Cloud beim Ingest** | Das SDK sendet keine | -| **`dedup_key`** | **Cloud beim Ingest** | Ein Hash aus Org, Session, Timestamp, Typ und Payload. Das ist die echte Identität – sie sorgt dafür, dass ein wiederholter Batch zusammengefasst statt dupliziert wird | +| `tool_call_id`, `hook_id`, `request_id` | Dir oder dem Framework | Adapter verwenden die eigenen Run-IDs des Frameworks, weshalb Paare auch Thread-Wechsel überleben | +| **Event-ID** | **Cloud, bei der Verarbeitung** | Das SDK sendet keine | +| **`dedup_key`** | **Cloud, bei der Verarbeitung** | Ein Hash aus Org, Session, Zeitstempel, Typ und Payload. Das ist die echte Identität – sie lässt einen wiederholten Batch zusammenfallen statt zu duplizieren | #### Wie Adapter `session_id` auflösen -Der erste Treffer gewinnt: +Erste Übereinstimmung gewinnt: 1. Eine explizite `session_id`-Option 2. Metadaten pro Aufruf @@ -451,11 +449,11 @@ Der erste Treffer gewinnt: 4. Framework-Metadaten 5. Die eigene Run-ID des Frameworks -Sie wird nie erfunden, solange eines davon existiert – eine synthetisierte ID würde einen Durchlauf auf mehrere Sessions aufteilen. +Sie wird nie erfunden, solange eine dieser Quellen vorhanden ist – eine synthetisierte ID würde einen Durchlauf auf mehrere Sessions aufteilen. -#### `agent_id` niedrig halten +#### `agent_id` niedrig-kardinal halten -Sie ist die primäre Facette auf jeder Dashboard-Ansicht und eine `LowCardinality(String)`-Spalte. Ein Wert pro Durchlauf degradiert die Spalte und füllt das Filter-Dropdown mit einem Eintrag pro Durchlauf. +Es ist die primäre Facette auf jeder Dashboard-Ansicht und eine `LowCardinality(String)`-Spalte. Ein per-Run-Wert verschlechtert die Spalte und füllt das Filter-Dropdown mit einem Eintrag pro Durchlauf. Adapter schützen diese Spalte für dich: @@ -463,19 +461,19 @@ Adapter schützen diese Spalte für dich: | --- | --- | --- | | `3f9a1c2b-…` (eine UUID) | `main` | Nichts Lesbares zu behalten | | Ein langer reiner Hex-String | `main` | Dasselbe | -| `agent-3f9a1c2b-…` | `agent` | Pro-Durchlauf-ID entfernt, lesbarer Teil behalten | +| `agent-3f9a1c2b-…` | `agent` | Per-Run-ID entfernt, lesbarer Teil behalten | | `agent-v2` | `agent-v2` | Kurze Segmente werden unverändert gelassen | | `step-3` | `step-3` | Dasselbe | -Die echte ID wird auf `fw_agent_id` / `fw_run_id` behalten, wo sie abfragbar bleibt, ohne eine Facette zu sein. +Die echte ID wird auf `fw_agent_id` / `fw_run_id` gespeichert, wo sie abfragbar bleibt, ohne eine Facette zu sein. - **Diese Schutzmaßnahme betrifft nur Labels, die das *Framework* gewählt hat.** Eine `agent_id`, die du selbst übergibst – an `event.*` oder an `failproofai_sdk.agent(...)` – wird genau so aufgezeichnet. Ein explizites Argument stillschweigend umzuschreiben wäre schlimmer als die Kardinalität, die es verhindert – benenne deine eigenen Spans entsprechend. + **Dieser Schutz betrifft nur Labels, die das *Framework* gewählt hat.** Eine `agent_id`, die du selbst übergibst – an `event.*` oder an `failproofai_sdk.agent(...)` – wird exakt so aufgezeichnet. Ein explizites Argument stillschweigend umzuschreiben wäre schlimmer als die Kardinalität, die es verhindert – benenne deine eigenen Spans entsprechend. - + | Gruppe | Events | | --- | --- | @@ -488,23 +486,23 @@ Die echte ID wird auf `fw_agent_id` / `fw_run_id` behalten, wo sie abfragbar ble Welches Framework was aufzeichnet, gemessen aus den obigen Durchläufen: -| Event | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | +| Event | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Eigene | | --- | :--: | :--: | :--: | :--: | :--: | -| Agent Start und End | Ja | Ja | Ja | Ja | Du | -| Model Request und Response | Ja | Ja | Ja | Ja | Du | -| Tool Use und Result | Ja | Ja | Ja | Ja | Du | -| Hook Triggered und Completed | Node | Task | Step | — | Du | +| Agent start und end | Ja | Ja | Ja | Ja | Du | +| Model request und response | Ja | Ja | Ja | Ja | Du | +| Tool use und result | Ja | Ja | Ja | Ja | Du | +| Hook triggered und completed | Node | Task | Step | — | Du | | Error | Ja | Ja | Ja | Ja | Automatisch | -| Human Wait und Input | Ja | Ja | Ja | — | Du | -| Agent Pause und Resume | Ja | Ja | Ja | — | Du | +| Human wait und input | Ja | Ja | Ja | — | Du | +| Agent pause und resume | Ja | Ja | Ja | — | Du | -Ein Strich bedeutet, das Framework kennt dieses Konzept nicht. `human_pause` und `human_interrupt` beschreiben eine *Person*, die auf den Agenten einwirkt – das signalisiert kein Framework. Diese musst du selbst senden. +Ein Strich bedeutet, das Framework kennt dieses Konzept nicht. `human_pause` und `human_interrupt` beschreiben eine *Person*, die auf den Agenten einwirkt – kein Framework signalisiert das, sende diese Events selbst. -Ein Event kommt nie allein. Eines öffnet einen Span, eines schließt ihn, und das schließende Event trägt eine Dauer, die das SDK vom öffnenden Event an misst. +Ein Event kommt nie allein. Eines öffnet einen Span, eines schließt ihn, und das schließende Event trägt eine Dauer, die das SDK vom öffnenden Event an gemessen hat. | Öffnet | Schließt | Das schließende Event trägt | | --- | --- | --- | @@ -512,28 +510,28 @@ Ein Event kommt nie allein. Eines öffnet einen Span, eines schließt ihn, und d | `model_request` | `model_response` | Tokens, `stop_reason`, Latenz | | `tool_use` | `tool_result` | `output` oder `error`, Dauer | | `hook_triggered` | `hook_completed` | `outcome`, Dauer | -| `agent_pause` | `agent_resume` | Wie lange die Pause gedauert hat | -| `human_wait` | `human_input` | Die Antwort und wie lange die Person gebraucht hat | +| `agent_pause` | `agent_resume` | Wie lange die Pause dauerte | +| `human_wait` | `human_input` | Die Antwort und wie lange die Person brauchte | - Ein öffnendes Event ohne schließendes ist ein Span, der nie endet. Die Session wird als noch laufend angezeigt, für immer, und ihre aktive Dauer wächst weiter. Das ist der Fehlerfall, auf den du achten musst, wenn du manuell instrumentierst. + Ein öffnendes Event ohne schließendes ist ein Span, der nie endet. Die Session wird als noch laufend angezeigt, für immer, und ihre aktive Dauer wächst weiter. Das ist der Fehlerfall, auf den man achten muss, wenn man manuell instrumentiert. #### Korrelationsregeln -- Verwende dieselbe `tool_call_id`, `hook_id`, `pause_id` oder `input_id` für das passende Abschlussevent. -- Das SDK berechnet `duration_ms` für `tool_result`, `hook_completed`, `agent_resume` und `human_input`. Es an diese Methoden zu übergeben wirft einen `ValueError`. -- `duration_ms` **wird** bei `model_response` akzeptiert, weil nur der Aufrufer die echte Provider-Latenz kennt. Es muss ein Integer sein – ein Float wirft am Aufrufpunkt einen `ValueError`, da der Server die Spalte als vorzeichenlosen 32-Bit-Integer liest und sonst NULL speichern würde. -- Korrelationsschlüssel sind nach Art und Session begrenzt, sodass ein Tool-Aufruf und ein Hook sicher dieselbe ID teilen dürfen, und zwei parallele Sessions dieselben IDs wiederverwenden können, ohne zu kollidieren. Sie sind nicht nach Agent begrenzt: Ein Paar, das unter einem Agenten geöffnet und unter einem anderen geschlossen wird, korreliert trotzdem – das ist der Normalfall in Multi-Agent-Frameworks. -- `request_id` paart `model_request` mit `model_response`. Ohne sie werden Model-Events in Reihenfolge pro Agent gepaart, sodass parallele Aufrufe falsch gepaart werden. -- Ein über Prozesse hinweg aufgeteiltes Paar korreliert noch auf der Serverseite, aber das SDK kann seine In-Process-Dauer nicht berechnen. -- Die Pending-Map hält maximal 10.000 Starts und entfernt den ältesten Eintrag, wenn sie voll ist. +- Verwende dieselbe `tool_call_id`, `hook_id`, `pause_id` oder `input_id` für das passende Abschluss-Event. +- Das SDK berechnet `duration_ms` für `tool_result`, `hook_completed`, `agent_resume` und `human_input`. Diese Methoden werfen einen `ValueError`, wenn du es übergibst. +- `duration_ms` **wird** bei `model_response` akzeptiert, weil nur der Aufrufer die echte Provider-Latenz kennt. Es muss ein Integer sein – ein Float wirft am Aufrufpunkt einen `ValueError`, weil der Server die Spalte als vorzeichenlose 32-Bit-Ganzzahl liest und für alles andere NULL speichern würde. +- Korrelationsschlüssel sind nach Art und Session begrenzt, sodass ein Tool-Aufruf und ein Hook gefahrlos dieselbe ID teilen dürfen, und zwei gleichzeitige Sessions können dieselben IDs ohne Kollision wiederverwenden. Sie sind nicht nach Agent begrenzt: Ein Paar, das unter einem Agenten geöffnet und unter einem anderen geschlossen wird, korreliert trotzdem – das ist der normale Fall in Multi-Agenten-Frameworks. +- `request_id` paart `model_request` mit `model_response`. Ohne sie werden Model-Events pro Agent der Reihe nach gepaart, sodass gleichzeitige Aufrufe falsch zugeordnet werden. +- Ein über Prozesse hinweg gespaltenes Paar korreliert nachgelagert noch, aber das SDK kann seine In-Process-Dauer nicht berechnen. +- Die Pending-Map hält höchstens 10.000 Starts und verdrängt den ältesten Eintrag, wenn sie voll ist. -Die Installation von `failproofai-sdk` installiert alles, alle vier Adapter inklusive. Die Extras ziehen das **Framework** nach, nicht den Adapter. +Die Installation von `failproofai-sdk` installiert alles, alle vier Adapter inklusive. Die Extras holen das **Framework**, nicht den Adapter. ```python import failproofai_sdk # lädt nichts außerhalb der Standardbibliothek @@ -543,7 +541,7 @@ failproofai_sdk.instrument() # importiert nur die Adapter, die du tatsächlich `import failproofai_sdk` ist vertraglich abhängigkeitsfrei, erzwungen durch einen Test, der das gebaute Wheel mit `--no-deps` installiert, und einen weiteren, der beweist, dass kein Framework `sys.modules` erreicht. - Es gibt kein `failproofai_sdk.crewai`-Attribut. Adapter werden absichtlich nicht am Top-Level-Paket exponiert: Darauf zuzugreifen würde das Framework als Nebeneffekt des Attributzugriffs importieren und das Null-Abhängigkeits-Versprechen brechen. Verwende `instrument()`. + Es gibt kein `failproofai_sdk.crewai`-Attribut. Adapter werden bewusst nicht im Top-Level-Paket exponiert: Das Berühren eines Adapters würde das Framework als Nebeneffekt eines Attributzugriffs importieren und das Versprechen der Abhängigkeitsfreiheit brechen. Verwende `instrument()`. ```python @@ -559,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # rückgängig machen | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -Die Auto-Erkennung liest `sys.modules`, nicht die Liste installierter Pakete – ein installiertes, aber nie importiertes Framework wird nicht instrumentiert und nie in deinem Namen importiert. Um zu sehen, was verdrahtet ist: +Die automatische Erkennung liest `sys.modules`, nicht die installierte Paketliste – ein Framework, das installiert, aber nie importiert wurde, wird nicht instrumentiert und nie in deinem Namen importiert. Um zu sehen, was verdrahtet ist: ```python from failproofai_sdk.integrations import active, available @@ -569,20 +567,20 @@ active() # ('langchain',) ``` - **`instrument("crewai")` auf einer Maschine ohne CrewAI wirft keine Exception.** Es loggt eine Warnung und gibt `()` zurück, sodass ein fehlendes Framework nie einen Prozess zum Absturz bringt, der auch andere instrumentiert. + **`instrument("crewai")` auf einem Rechner ohne CrewAI wirft keine Exception.** Es protokolliert eine Warnung und gibt `()` zurück, sodass ein fehlendes Framework nie einen Prozess beendet, der auch andere instrumentiert. - Die Warnung enthält den zugrunde liegenden `ImportError`, und diese Meldung nennt den genauen Installationsbefehl – die Lösung steht also in deinen Logs, nicht versteckt. + Die Warnung enthält den zugrundeliegenden `ImportError`, und diese Meldung nennt den genauen Installationsbefehl – der Fix steckt also in deinen Logs, nicht versteckt. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Setze `FAILPROOFAI_SDK_STRICT=1`, damit stattdessen eine Exception ausgelöst wird. Dieses Flag wird **einmal gelesen und gecacht**, also exportiere es vor dem Start deines Prozesses, statt es mittendrin zu setzen. + Setze `FAILPROOFAI_SDK_STRICT=1`, um stattdessen eine Exception zu werfen. Dieses Flag wird **einmal gelesen und gecacht**, also setze es vor dem Prozessstart, nicht mittendrin. - **`instrument()` muss *nach* deinem Framework-Import kommen.** Die Auto-Erkennung liest `sys.modules`, also findet ein bloßer Aufruf vor dem Import nichts, installiert nichts und gibt `()` zurück. + **`instrument()` muss *nach* dem Framework-Import aufgerufen werden.** Die automatische Erkennung liest `sys.modules`, ein nackter Aufruf vor dem Import findet nichts, installiert nichts und gibt `()` zurück. @@ -594,7 +592,7 @@ import langchain # zu spät, nichts ist verdrahtet ``` ```python Right -import langchain # Framework zuerst importieren +import langchain # erst das Framework importieren import failproofai_sdk failproofai_sdk.instrument() # findet es -> ('langchain',) @@ -603,12 +601,12 @@ failproofai_sdk.instrument() # findet es -> ('langchain',) ```python Right, order-proof import failproofai_sdk -# Den Namen anzugeben importiert den Adapter auf Anfrage, also funktioniert das überall. +# Den Namen anzugeben importiert den Adapter auf Anfrage, funktioniert also von überall. failproofai_sdk.instrument("langchain") ``` -Machst du das falsch, läuft der Prozess mit importiertem SDK, scheinbar installiertem Adapter und **keinem einzigen gesendeten Event**. Es loggt eine Warnung, die genau das sagt – also prüfe zuerst deine Logs, wenn ein Durchlauf nichts aufzeichnet. +Machst du das falsch, läuft der Prozess mit importiertem SDK, scheinbar installiertem Adapter und **keinem einzigen gesendeten Event**. Es protokolliert eine Warnung, die genau das sagt – prüfe also zuerst deine Logs, wenn ein Durchlauf nichts aufzeichnet. @@ -618,83 +616,81 @@ Machst du das falsch, läuft der Prozess mit importiertem SDK, scheinbar install flowchart LR A["Dein Agent"] --> B["Adapter"] B --> C["Writer
In-Memory-Queue"] - C -->|"alle 0,5s"| D["Spool
JSONL auf Disk"] - D --> E["Failproof Daemon"] + C -->|"alle 0,5 s"| D["Spool
JSONL auf Disk"] + D --> E["Failproof-Daemon"] E -->|"HTTPS"| F["Cloud"] ``` | Stufe | Aufgabe | Läuft in | | --- | --- | --- | | Adapter | Übersetzt einen Framework-Callback in einen von 15 Event-Typen | Dein Prozess | -| Writer | Reiht in Warteschlange, bündelt, schreibt JSONL atomar | Dein Prozess, Hintergrund-Thread | +| Writer | Reiht Events ein, bündelt sie, schreibt JSONL atomar | Dein Prozess, Hintergrund-Thread | | Spool | Dauerhafter Übergabepunkt, überlebt den Prozessabbruch | Lokale Disk | -| Daemon | Beobachtet den Spool, verschickt Batches, löscht Versendetes | Deine Maschine | -| Ingest | Weist Row-ID und Dedup-Key zu, befördert abfragbare Spalten | Cloud | +| Daemon | Überwacht den Spool, sendet Batches, löscht Versendetes | Deine Maschine | +| Ingest | Vergibt Row-ID und Dedup-Schlüssel, befördert abfragbare Spalten | Cloud | -Der Spool macht das Ganze sicher: Dein Agent blockiert nie auf das Netzwerk, und ein Cloud-Ausfall bedeutet ein wachsendes Verzeichnis statt verlorener Events. +Der Spool macht das sicher: Dein Agent blockiert nie auf das Netzwerk, und ein Cloud-Ausfall bedeutet ein wachsendes Verzeichnis statt verlorene Events. -Jeder Flush schreibt eine Batch-Datei: zuerst `.tmp`, dann `fsync`, dann ein atomares Umbenennen: +Jeder Flush schreibt eine Batch-Datei, zuerst `.tmp`, dann `fsync`, dann ein atomares Umbenennen: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Der Daemon liest nur `.jsonl`, kann also nie eine halb geschriebene Datei lesen. Der Dateiname trägt Timestamp, Prozess-ID und Sequenznummer, sodass zwei Prozesse, die in derselben Millisekunde flushen, nicht kollidieren können. Die Queue ist auf 10.000 Events begrenzt; darüber hinaus werden die ältesten gelöscht und geloggt. +Der Daemon liest nur `.jsonl`, kann also nie eine halb geschriebene Datei lesen. Der Dateiname enthält Zeitstempel, Prozess-ID und Sequenznummer, sodass zwei Prozesse, die in derselben Millisekunde flushen, nicht kollidieren können. Die Queue ist auf 10.000 Events begrenzt; darüber hinaus werden die ältesten verworfen und protokolliert. - **`collector.redact` gilt nicht für deine SDK-Events.** Es sieht sie nie. + **`collector.redact` ist auch für SDK-Events standardmäßig auf `minimal` gesetzt.** Das SDK bereinigt, bevor es einen Batch auf Disk schreibt, und der Daemon wiederholt denselben deterministischen Durchlauf vor dem Upload, sodass Batches älterer SDKs geschützt sind. -Der Daemon **versendet** deine Batches. Er öffnet oder überschreibt sie nicht. +Der Daemon liest jeden Batch und wendet die Bereinigung im Speicher vor dem Upload an. Er schreibt die gelesene Spool-Datei nicht neu. -| Events | Geschrieben von | Durch `collector.redact` bereinigt? | +| Events | Geschrieben von | Wo minimale Bereinigung läuft | | --- | --- | --- | -| CLI-Session-Transkripte | Dem Daemon | Ja | -| Hook-Aktivität | Dem Daemon | Ja | -| **Alles, was das SDK sendet** | **Deinem Prozess** | **Nein** | +| CLI-Session-Transkripte | Der Daemon | Bevor der Daemon den Batch schreibt | +| Hook-Aktivität | Der Daemon | Bevor der Daemon den Batch schreibt | +| **Alles, was das SDK sendet** | **Dein Prozess** | **Bevor das SDK den Batch schreibt und erneut vor dem Daemon-Upload** | -Bereinigung läuft dort, wo der Daemon seine *eigenen* Events schreibt – nicht wo Batches *versendet* werden. Ein Prompt oder ein Tool-Argument mit einem API-Key enthält ihn also noch beim Ankommen. - -Das ist beabsichtigt. Das sind deine eigenen Instrumentierungsaufrufe, und sie im Transit umzuschreiben würde bedeuten, dass die Events, die du empfängst, nicht die Events sind, die du gesendet hast. +Setze `collector.redact` nur auf `off`, wenn verbatim Payloads eine explizite Anforderung sind; SDK und Daemon beachten diese Einstellung beide. Minimale Bereinigung erkennt gängige API-Schlüssel, Bearer-Tokens, JWTs und Secret-Zuweisungen. Sie kann keine beliebig sensiblen Freitexte erkennen. **Du kontrollierst Payloads an der Quelle, an zwei Stellen:** - - Schalte Content-Capture am Adapter aus. **Der Optionsname unterscheidet sich, und ein Adapter hat keinen** – das ist kein universeller Schalter: + - Deaktiviere die Content-Erfassung im Adapter. **Der Optionsname unterscheidet sich, und ein Adapter hat keinen** – das ist kein universeller Schalter: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **kein Content-Schalter**; `session_id` ist die einzige Option, die es liest – Prompts und Completions werden also immer aufgezeichnet. + - CrewAI — **kein Content-Schalter**; `session_id` ist die einzige Option, die es liest, also werden Prompts und Completions immer aufgezeichnet. - `instrument()` ignoriert Optionen, die ein Adapter nicht liest, sodass das Übergeben des falschen Namens nichts auslöst und nichts ändert. - - Gib das Geheimnis von vornherein nicht an `input=` weiter. + `instrument()` ignoriert Optionen, die ein Adapter nicht liest, sodass ein falscher Name nichts auslöst und nichts ändert. + - Übergib das Geheimnis erst gar nicht an `input=`. - `collector.redact` ist kein Ersatz für beides. + `collector.redact` ist Defense-in-Depth, kein Ersatz für beides. - **Ein leeres Spool-Verzeichnis ist der gesunde Zustand.** Verwende es nicht zur Lieferungsüberprüfung. + **Ein leeres Spool-Verzeichnis ist der gesunde Zustand.** Verwende es nicht zur Lieferkontrolle. -Der Daemon löscht jeden Batch innerhalb von Millisekunden nach dem Versenden, sodass ein `ls` mit dem Collector um die Wette läuft und nur einen Bruchteil der gesendeten Events zeigt – nicht zu unterscheiden von einem SDK, das nichts aufgezeichnet hat. +Der Daemon löscht jeden Batch innerhalb von Millisekunden nach dem Versand, sodass ein `ls` mit dem Collector konkurriert und nur einen Bruchteil des Gesendeten zeigt – nicht zu unterscheiden von einem SDK, das nichts aufgezeichnet hat. -Um zu bestätigen, dass Events tatsächlich angekommen sind, prüfe das Dashboard. Um den Spool beim Füllen zu beobachten, stoppe den Daemon zuerst. +Um zu bestätigen, dass Events tatsächlich angekommen sind, prüfe das Dashboard. Um den Spool beim Füllen zu beobachten, stoppe zuerst den Daemon. -Jeder Callback läuft innerhalb eines Wrappers, dessen einzige Aufgabe es ist, weiterzuwerfen – dein Aufruf sitzt also in genau einem `try`, und alles, was das SDK tut, geschieht außerhalb davon. +Jeder Callback läuft in einem Wrapper, dessen einzige Aufgabe das Weiterleiten ist, sodass dein Aufruf in genau einem `try` sitzt und alles, was das SDK tut, außerhalb davon passiert. | Was passiert | Ergebnis | | --- | --- | -| Ein Hook wirft | Einmalig mit Traceback geloggt. Dein Aufruf ist nicht betroffen | -| Derselbe Hook wirft dreimal | Dieser eine Hook ist für den Rest des Prozesses deaktiviert, mit einer Fehlerzeile | -| `FAILPROOFAI_SDK_STRICT=1` ist gesetzt | Die Exception wird stattdessen weitergegeben | -| Eine Framework-Version liegt außerhalb des getesteten Bereichs | Einmalige Warnung, Instrumentierung trotzdem | -| Eine einzelne Fähigkeit fehlt | Nur dieser eine Hook ist deaktiviert, nie der gesamte Adapter | +| Ein Hook wirft eine Exception | Einmal mit Traceback protokolliert. Dein Aufruf ist unberührt | +| Derselbe Hook wirft dreimal | Dieser eine Hook wird für den Rest des Prozesses deaktiviert, mit einer Fehlerzeile | +| `FAILPROOFAI_SDK_STRICT=1` ist gesetzt | Die Exception wird stattdessen weitergeleitet | +| Eine Framework-Version liegt außerhalb des getesteten Bereichs | Einmalige Warnung, wird trotzdem instrumentiert | +| Eine einzelne Fähigkeit fehlt | Genau dieser Hook wird deaktiviert, nie der gesamte Adapter | -Der Standard ist in Produktion richtig und beim Debuggen falsch, weil er nur beweisen kann „es ist nicht abgestürzt". Setze `FAILPROOFAI_SDK_STRICT=1`, um einen verschluckten Fehler laut zu machen. +Der Standard ist in Produktion richtig und beim Debuggen falsch, weil er nur beweisen kann, dass es nicht abgestürzt ist. Setze `FAILPROOFAI_SDK_STRICT=1`, um einen geschluckten Fehler laut zu machen. @@ -704,34 +700,34 @@ Der Standard ist in Produktion richtig und beim Debuggen falsch, weil er nur bew - Ein öffnendes Event hat kein schließendes: ein `model_request` ohne `model_response` oder ein `tool_use` ohne `tool_result`. Verwende die Scopes, die das Paar auch dann garantieren, wenn der Body eine Exception wirft. Wenn du die Event-Methoden direkt aufrufst, verwende `try` und `finally`. + Ein öffnendes Event hat kein schließendes: ein `model_request` ohne `model_response` oder ein `tool_use` ohne `tool_result`. Verwende die Scopes, die das Paar auch dann garantieren, wenn der Rumpf eine Exception wirft. Rufst du die Event-Methoden direkt auf, verwende `try` und `finally`. - Es wird vom passenden öffnenden Event an gemessen und wird daher bei `tool_result`, `hook_completed`, `agent_resume` und `human_input` abgelehnt. Bei `model_response` wird es akzeptiert, weil nur du die echte Provider-Latenz kennst, und es muss ein Integer sein. + Es wird vom passenden öffnenden Event aus gemessen und daher bei `tool_result`, `hook_completed`, `agent_resume` und `human_input` abgelehnt. Bei `model_response` wird es akzeptiert, weil nur du die echte Provider-Latenz kennst, und es muss ein Integer sein. - Der Thread hat den Kontext nie geerbt. Wickle das Callable in `failproofai_sdk.propagate()` ein. Siehe [Threads und Async](#threads-und-async). + Der Thread hat den Kontext nie geerbt. Wickle das Callable in `failproofai_sdk.propagate()`. Siehe [Threads und async](#threads-and-async). - Zusätzliche Felder werden zuletzt zusammengeführt, sodass eines mit dem Namen eines echten Feldes wie `model` oder `outcome` dieses überschreiben und eine gespeicherte Spalte verändern würde. Verwende einen Namespace; die Adapter nutzen das Präfix `fw_`. + Zusätzliche Felder werden zuletzt zusammengeführt, sodass eines mit dem Namen eines echten Felds wie `model` oder `outcome` dieses überschreiben und eine gespeicherte Spalte verändern würde. Verwende eigene Namespaces; die Adapter nutzen ein `fw_`-Präfix. - - `agent_id` ist eine Facette mit niedriger Kardinalität, und du hast eine Run-ID hineingespeichert. Verwende eine Rolle oder einen Node-Namen und leg die echte ID in ein Payload-Feld. + + `agent_id` ist eine Facette mit niedriger Kardinalität, und du hast eine Run-ID hineingesteckt. Verwende eine Rollen- oder Node-Bezeichnung und lege die echte ID in ein Payload-Feld. ## Weiter - + Paare, IDs, Session-Lebenszyklus und Zustellung. - - Folge der Kausalität durch die soeben aufgezeichnete Session. + + Verfolge die Kausalität durch die soeben erfasste Session. LangGraph, CrewAI, LlamaIndex und Pydantic AI. diff --git a/docs/es/start/integrations/custom-agents.mdx b/docs/es/start/integrations/custom-agents.mdx index 09d79215..c1241eff 100644 --- a/docs/es/start/integrations/custom-agents.mdx +++ b/docs/es/start/integrations/custom-agents.mdx @@ -7,7 +7,7 @@ icon: "code" Para un agente que escribiste tú mismo, o un framework para el que Failproof AI no tiene adaptador. No hay nada que instrumentar: tú emites los eventos. -Esta es la misma API que los cuatro adaptadores de framework utilizan internamente. Son tablas de traducción sobre ella. +Esta es la misma API que utilizan internamente los cuatro adaptadores de frameworks. Son tablas de traducción sobre ella. ## Instalación @@ -15,7 +15,7 @@ Esta es la misma API que los cuatro adaptadores de framework utilizan internamen pip install failproofai-sdk ``` -Sin extras ni dependencias. +Sin extras y sin dependencias. ## Instrumentación @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # una ejecución t.output = search(q) # una llamada a herramienta ``` -Léelo de arriba a abajo y verás lo que significa: +Léelo de arriba a abajo y dice exactamente lo que significa: | Envuélvelo en | Para indicar | | --- | --- | | `session()` | Estos eventos pertenecen a la misma ejecución | -| `agent()` | Algo está haciendo trabajo — dale un nombre que reconocerías en una lista | -| `tool_call()` | Esta es una herramienta, y esto es lo que devolvió | +| `agent()` | Algo está realizando trabajo — dale un nombre que reconocerías en una lista | +| `tool_call()` | Esta es una herramienta y esto fue lo que devolvió | -Y lo que cada uno emite realmente: +Y lo que emite cada uno realmente: | Ámbito | Emite | Propósito | | --- | --- | --- | -| `session()` | Nada | Vincula un id de sesión, agrupando una ejecución | +| `session()` | Nada | Vincula un session id, agrupando una ejecución | | `agent()` | `agent_start`, `agent_end` | Delimita una unidad de trabajo | | `tool_call()` | `tool_use`, `tool_result` | Delimita una herramienta y la mide | -Todo lo que esté dentro puede omitir `session_id` y `agent_id`. Los ámbitos vinculan la identidad en variables de contexto y cada llamada a evento la lee de vuelta, por lo que nunca necesitas pasar ids a través de tus funciones. +Todo lo que está dentro puede omitir `session_id` y `agent_id`. Los ámbitos vinculan la identidad en variables de contexto y cada llamada a evento la recupera, de modo que nunca necesitas pasar ids a través de tus funciones. -Los tres funcionan tanto con `async with` como con `with`. +Los tres también funcionan con `async with` además de `with`. -Anidar agentes construye el árbol. `parent_id` y la profundidad se calculan desde la pila: +Anidar agentes construye el árbol. `parent_id` y la profundidad se calculan a partir de la pila: ```python with failproofai_sdk.session(): @@ -61,7 +61,7 @@ with failproofai_sdk.session(): ## Cómo se cierra un ámbito -`agent()` gestiona las excepciones por ti: +`agent()` maneja las excepciones por ti: | Qué ocurrió | Eventos | Resultado | | --- | --- | --- | @@ -70,11 +70,11 @@ with failproofai_sdk.session(): | `KeyboardInterrupt`, `SystemExit` | `error`, luego `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | solo `agent_end` | `cancelled` | -El error se emite antes de `agent_end`, porque el panel cierra el span en `agent_end` y cualquier cosa posterior no se atribuye a nada. Una cancelación no es un fallo, por lo que las ejecuciones canceladas no contaminan la superficie de errores. La excepción siempre se relanza: un ámbito nunca la suprime. +El error se emite antes de `agent_end`, porque el dashboard cierra el span en `agent_end` y cualquier cosa después no se atribuye a nada. Una cancelación no es un fallo, por lo que las ejecuciones canceladas no contaminan la superficie de errores. La excepción siempre se vuelve a lanzar: un ámbito nunca la suprime. ## Los métodos de evento -Quince métodos en seis familias. La mayoría vienen en pares: emites el abridor, luego el cierre, y el SDK mide el span entre ellos. +Quince métodos en seis familias. La mayoría vienen en pares — emites el apertura, luego el cierre, y el SDK mide el span entre ambos. | Familia | Abre | Cierra | Independiente | | --- | --- | --- | --- | @@ -87,7 +87,7 @@ Quince métodos en seis familias. La mayoría vienen en pares: emites el abridor | **Fallos** | — | — | `error` | - Prefiere los ámbitos — `agent()` y `tool_call()` — donde encajen. Garantizan el evento de cierre incluso cuando el cuerpo lanza una excepción. Recurre a estos métodos directamente cuando tu flujo de control no se anida, como una llamada a modelo dentro de un helper. + Prefiere los ámbitos — `agent()` y `tool_call()` — siempre que encajen. Garantizan el evento de cierre incluso cuando el cuerpo lanza una excepción. Recurre a estos métodos directamente cuando tu flujo de control no anida, como una llamada a modelo dentro de una función auxiliar. @@ -146,13 +146,13 @@ failproofai_sdk.event.error( | Métodos | Significado | | --- | --- | | `human_wait` / `human_input` | El **agente le preguntó a una persona** — una puerta de aprobación, una pregunta aclaratoria | - | `human_pause` / `human_interrupt` | Una **persona actuó sobre el agente** — un botón de parada, una pausa de operador | + | `human_pause` / `human_interrupt` | **Una persona actuó sobre el agente** — un botón de parada, una pausa del operador | - Ningún framework señaliza el segundo par, por lo que siempre es tuya la responsabilidad de emitirlo. + Ningún framework señaliza el segundo par, por lo que siempre te corresponde a ti emitirlo. - **Pasa `request_id` cuando las llamadas al modelo se ejecuten de forma concurrente.** Sin él, las solicitudes y respuestas se emparejan en orden de llegada por agente, y las llamadas concurrentes se emparejan incorrectamente, asociando cada respuesta con la solicitud equivocada. + **Pasa `request_id` cuando las llamadas a modelos se ejecutan concurrentemente.** Sin él, las solicitudes y respuestas se emparejan en orden de llegada por agente — y las llamadas concurrentes se desemparejan, asociando cada respuesta con la solicitud equivocada. ## Ejemplo @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # acotado; un bucle de agente sin límite es un bug propio + for _ in range(4): # acotado; un bucle de agente sin límite es un bug en sí mismo message = turn(messages) if not message.tool_calls: break @@ -204,8 +204,8 @@ with failproofai_sdk.session(): }) ``` -Esto produce los mismos seis tipos de eventos que te daría un adaptador. La versión -ejecutable completa, con las definiciones de herramientas, se incluye en el repositorio del SDK bajo +Eso produce los mismos seis tipos de eventos que te daría un adaptador. La versión +completa y ejecutable, con las definiciones de herramientas, se incluye en el repositorio del SDK bajo `docs/manual/examples/`. ## Hilos y async @@ -223,13 +223,13 @@ threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Sin `propagate()`, los eventos del worker lanzan un `TypeError` que indica la corrección en lugar de terminar sin sesión. Esto es deliberado: un evento sin sesión es omitido por el ingest y respondido con `200`, que es el fallo silencioso que la capa de identidad existe para prevenir. +Sin `propagate()`, los eventos del worker lanzan un `TypeError` que indica la solución en lugar de llegar a ninguna sesión. Esto es deliberado: un evento sin sesión es omitido por la ingesta y respondido con `200`, que es el fallo silencioso que la capa de identidad existe para prevenir. ## Instrumentar un framework sin adaptador -Cada framework de agentes te ofrece los mismos tres puntos de enganche. Mapéalos y tendrás una traza completa — los cuatro adaptadores incluidos no hacen nada más que esto. +Todo framework de agentes te da los mismos tres puntos de enganche. Mapéalos y tendrás un trace completo — los cuatro adaptadores incluidos no hacen nada más que esto. -| El punto de enganche | Lo que escribes | Lo que resulta | +| El punto de enganche | Lo que escribes | Lo que llega | | --- | --- | --- | | La ejecución | `session()` + `agent()` | `agent_start`, `agent_end` | | Cada herramienta | `tool_call()` | `tool_use`, `tool_result` | @@ -244,7 +244,7 @@ Cada framework de agentes te ofrece los mismos tres puntos de enganche. Mapéalo ``` - En lo que el framework llame wrapper de herramienta o middleware. + En lo que sea que el framework llame wrapper de herramienta o middleware. ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -270,27 +270,27 @@ Cada framework de agentes te ofrece los mismos tres puntos de enganche. Mapéalo - **Manual y automático se combinan.** Un adaptador que se ejecuta dentro de un ámbito escrito a mano se une a esa sesión y se convierte en hijo de ese agente, de modo que obtienes un único árbol en lugar de dos — útil cuando instrumentas un framework tú mismo junto a uno soportado. + **Lo manual y lo automático se componen.** Un adaptador ejecutándose dentro de un ámbito escrito a mano se une a esa sesión y toma ese agente como padre, de modo que obtienes un solo árbol en lugar de dos — útil cuando instrumentas un framework tú mismo junto a uno compatible. - + Dos razones, y los tres puntos de enganche anteriores son la respuesta a ambas: - - `autogen-core` no tiene mantenimiento desde septiembre de 2025. - - AG2 no expone ningún punto de registro a nivel de proceso equivalente a los hooks de los otros frameworks, por lo que instrumentarlo significa envolver cada agente en cada punto de construcción. + - `autogen-core` no ha tenido mantenimiento desde septiembre de 2025. + - AG2 no expone ningún punto de registro a nivel de proceso equivalente a los hooks de los otros frameworks, por lo que instrumentarlo implica envolver cada agente en cada lugar donde se construye. Mapear los puntos de enganche a mano registra los mismos eventos, con la misma fidelidad, que un adaptador incluido. -## Profundizando +## Más a fondo -Cómo funciona la grabación realmente. Nada de esto es necesario para empezar. +Cómo funciona realmente el registro. Nada de esto es necesario para empezar. - + -Toda grabación tiene la misma forma: un span se abre, el trabajo se anida dentro, y cada evento de apertura recibe uno de cierre. +Cada registro tiene la misma forma: se abre un span, el trabajo se anida dentro de él, y cada evento de apertura recibe uno de cierre. ```mermaid flowchart LR @@ -302,9 +302,9 @@ flowchart LR C --> E(["agent_end"]) ``` -El **par** es la unidad. Cada evento de cierre lleva una duración que el SDK mide desde el de apertura. +El **par** es la unidad. Cada evento de cierre lleva una duración que el SDK mide desde el evento de apertura correspondiente. -A continuación se muestra una ejecución real por framework — capturada de los ejemplos que se incluyen con el SDK, con el nombre del modelo normalizado. Fíjate en cuánto se obtiene de una sola llamada. +A continuación se muestra una ejecución real por framework — capturada de los ejemplos incluidos con el SDK, con el nombre del modelo normalizado. Observa cuánto se obtiene de una sola llamada. @@ -342,7 +342,7 @@ A continuación se muestra una ejecución real por framework — capturada de lo 10 +5.739s agent_end crew · success ``` - El `role` de cada agente se convierte en su nombre de span, por lo que la latencia y el gasto en tokens se desglosan por rol. + El `role` de cada agente se convierte en el nombre de su span, de modo que la latencia y el consumo de tokens se desglosan por rol. @@ -390,34 +390,34 @@ A continuación se muestra una ejecución real por framework — capturada de lo 6 +0.000s agent_end main · success ``` - Los emites tú mismo. Los mismos tipos de eventos, la misma fidelidad — te cuesta los puntos de llamada. + Tú emites estos tú mismo. Los mismos tipos de eventos, la misma fidelidad — a cambio de los puntos de llamada. - + **No existe un evento de fin de sesión.** Una sesión no es algo que cierras — es un grupo de eventos que comparten un `session_id`. -El estado se deriva de la forma de la traza: +El estado se deriva de la forma del trace: | Estado | Cuándo | | --- | --- | | `ongoing` | Al menos un span sigue abierto | -| `paused` | Un `agent_pause` no tiene un `agent_resume` correspondiente | +| `paused` | Un `agent_pause` no tiene `agent_resume` correspondiente | | `error` | Nada está abierto y al menos un evento falló | | `done` | Nada está abierto y nada falló | -Por tanto, una sesión termina cuando todos los pares están cerrados. Los adaptadores emiten `agent_end` por ti, y al finalizar cierran todo lo que siga abierto y lo marcan como incompleto — una ejecución que se interrumpió se resuelve como `done` con un hueco visible en lugar de quedar colgada. +Por tanto, una sesión termina cuando todos los pares están cerrados. Los adaptadores emiten `agent_end` por ti, y al desmontar cierran cualquier cosa que siga abierta y la marcan como incompleta — una ejecución con crash se resuelve como `done` con una brecha visible en lugar de quedarse colgada. - Por eso una sesión puede abarcar dos llamadas. Un `interrupt()` de LangGraph pausa la ejecución, el span raíz permanece deliberadamente abierto, y la llamada de reanudación lo cierra. Ambas llamadas son una sola sesión. + Por esto una sesión puede abarcar dos llamadas. Un `interrupt()` de LangGraph pausa la ejecución, el span raíz permanece deliberadamente abierto, y la llamada de reanudación lo cierra. Ambas llamadas son una sola sesión. - + `session_id` y `agent_id` son opcionales en todos los métodos de evento. Si se omiten, se resuelven desde el ámbito que los contiene: @@ -427,19 +427,19 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Pasarlos explícitamente también funciona y tiene precedencia. Si no hay nada vinculado ni nada pasado, la llamada lanza un `TypeError` que indica la corrección en lugar de emitir un evento sin sesión, que el ingest omitiría respondiendo con `200`. +Pasarlos explícitamente también funciona y tiene precedencia. Sin nada vinculado y sin nada pasado, la llamada lanza un `TypeError` que indica la solución en lugar de emitir un evento sin sesión, que la ingesta omitiría respondiendo `200`. -Los ámbitos vinculan la identidad en variables de contexto. Estas se propagan automáticamente a las tareas de asyncio pero no a los nuevos hilos — envuelve un worker en `failproofai_sdk.propagate()`. +Los ámbitos vinculan la identidad en variables de contexto. Estas se propagan automáticamente a las tareas de asyncio pero no a nuevos hilos — envuelve un worker en `failproofai_sdk.propagate()`. #### Quién genera cada id | Id | Generado por | Notas | | --- | --- | --- | -| `session_id` | Tú, o el SDK | `session("chat-42")` se usa tal cual; si se omite, el SDK genera un `uuid4().hex` | +| `session_id` | Tú, o el SDK | `session("chat-42")` se usa literalmente; si se omite, el SDK genera un `uuid4().hex` | | `agent_id` | Tú, o el framework | De `agent("analyst")`, un `role` de CrewAI, un `FunctionAgent.name`. Un valor con aspecto de UUID es rechazado y reemplazado | -| `tool_call_id`, `hook_id`, `request_id` | Tú, o el framework | Los adaptadores reutilizan los ids de ejecución propios del framework, por eso los pares sobreviven a los saltos entre hilos | -| **Id de evento** | **Cloud, en el ingest** | El SDK no emite ninguno | -| **`dedup_key`** | **Cloud, en el ingest** | Un hash de org, sesión, timestamp, tipo y payload. Esta es la identidad real — hace que un lote reintentado colapse en lugar de duplicarse | +| `tool_call_id`, `hook_id`, `request_id` | Tú, o el framework | Los adaptadores reutilizan los ids de ejecución propios del framework, razón por la que los pares sobreviven a los cambios de hilo | +| **Event id** | **Cloud, en la ingesta** | El SDK no emite ninguno | +| **`dedup_key`** | **Cloud, en la ingesta** | Un hash de org, sesión, timestamp, tipo y payload. Esta es la identidad real — hace que un batch reintentado se colapse en lugar de duplicarse | #### Cómo los adaptadores resuelven `session_id` @@ -451,31 +451,31 @@ Gana la primera coincidencia: 4. Metadatos del framework 5. El id de ejecución propio del framework -Nunca se inventa mientras exista alguna de esas — un id sintetizado dividiría una ejecución en varias sesiones. +Nunca se inventa mientras exista alguna de esas fuentes — un id sintetizado dividiría una ejecución entre varias sesiones. #### Mantén `agent_id` con baja cardinalidad -Es la faceta principal en todas las superficies del panel, y una columna `LowCardinality(String)`. Un valor por ejecución degrada la columna y llena el desplegable de filtros con una entrada por ejecución. +Es la faceta principal en todas las vistas del dashboard, y una columna `LowCardinality(String)`. Un valor por ejecución degrada la columna y llena el desplegable de filtros con una entrada por ejecución. Los adaptadores protegen esa columna por ti: -| Lo que entrega el framework | Registrado como | Por qué | +| El framework entrega | Se registra como | Por qué | | --- | --- | --- | | `3f9a1c2b-…` (un UUID) | `main` | No hay nada legible que conservar | | Una cadena hexadecimal larga | `main` | Igual | | `agent-3f9a1c2b-…` | `agent` | Se elimina el id por ejecución, se conserva la parte legible | -| `agent-v2` | `agent-v2` | Los segmentos cortos se dejan tal cual | +| `agent-v2` | `agent-v2` | Los segmentos cortos se dejan como están | | `step-3` | `step-3` | Igual | El id real se conserva en `fw_agent_id` / `fw_run_id`, donde sigue siendo consultable sin ser una faceta. - **Esta protección solo afecta a las etiquetas que eligió el *framework*.** Un `agent_id` que pasas tú mismo — a `event.*`, o a `failproofai_sdk.agent(...)` — se registra exactamente como se dio. Reescribir silenciosamente un argumento explícito sería peor que la cardinalidad que previene, así que nombra tus propios spans en consecuencia. + **Esta protección solo afecta a las etiquetas que eligió el *framework*.** Un `agent_id` que pasas tú mismo — a `event.*` o a `failproofai_sdk.agent(...)` — se registra exactamente como se da. Reescribir silenciosamente un argumento explícito sería peor que la cardinalidad que previene, así que ponle nombres apropiados a tus propios spans. - + | Grupo | Eventos | | --- | --- | @@ -486,25 +486,25 @@ El id real se conserva en `fw_agent_id` / `fw_run_id`, donde sigue siendo consul | Humanos | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | Fallos | `error` | -Qué registra cada framework, medido desde las ejecuciones anteriores: +Qué registra cada framework, medido a partir de las ejecuciones anteriores: | Evento | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | -| Inicio y fin de agente | Sí | Sí | Sí | Sí | Tú | -| Solicitud y respuesta de modelo | Sí | Sí | Sí | Sí | Tú | -| Uso y resultado de herramienta | Sí | Sí | Sí | Sí | Tú | -| Hook disparado y completado | Nodo | Tarea | Paso | — | Tú | +| Agent start y end | Sí | Sí | Sí | Sí | Tú | +| Model request y response | Sí | Sí | Sí | Sí | Tú | +| Tool use y result | Sí | Sí | Sí | Sí | Tú | +| Hook triggered y completed | Nodo | Tarea | Paso | — | Tú | | Error | Sí | Sí | Sí | Sí | Automático | -| Espera e input humano | Sí | Sí | Sí | — | Tú | -| Pausa y reanudación de agente | Sí | Sí | Sí | — | Tú | +| Human wait y input | Sí | Sí | Sí | — | Tú | +| Agent pause y resume | Sí | Sí | Sí | — | Tú | -Un guion indica que el framework no tiene ese concepto. `human_pause` y `human_interrupt` describen a una *persona* actuando sobre el agente, algo que ningún framework señaliza — emítelos tú mismo. +Un guión significa que el framework no tiene ese concepto. `human_pause` y `human_interrupt` describen a una *persona* actuando sobre el agente, lo que ningún framework señaliza — emítelos tú mismo. -Un evento nunca llega solo. Uno abre un span, otro lo cierra, y el evento de cierre lleva una duración que el SDK mide desde el de apertura. +Un evento nunca llega solo. Uno abre un span, otro lo cierra, y el evento de cierre lleva una duración que el SDK mide desde el evento de apertura. | Abre | Cierra | El evento de cierre lleva | | --- | --- | --- | @@ -516,40 +516,40 @@ Un evento nunca llega solo. Uno abre un span, otro lo cierra, y el evento de cie | `human_wait` | `human_input` | la respuesta y cuánto tardó la persona | - Un evento de apertura sin uno de cierre es un span que nunca termina. La sesión se muestra como aún en ejecución, para siempre, y su duración activa sigue creciendo. Este es el modo de fallo que hay que vigilar cuando se instrumenta a mano. + Un evento de apertura sin evento de cierre es un span que nunca termina. La sesión se muestra como aún en ejecución, para siempre, y su duración activa sigue creciendo. Este es el modo de fallo a vigilar cuando instrumentas a mano. #### Reglas de correlación -- Reutiliza el mismo `tool_call_id`, `hook_id`, `pause_id` o `input_id` para el evento de completado correspondiente. +- Reutiliza el mismo `tool_call_id`, `hook_id`, `pause_id` o `input_id` para el evento de completación correspondiente. - El SDK calcula `duration_ms` para `tool_result`, `hook_completed`, `agent_resume` y `human_input`. Pasarlo a esos métodos lanza `ValueError`. -- `duration_ms` **sí** se acepta en `model_response`, porque solo el llamador conoce la latencia real del proveedor. Debe ser un entero — un float lanza `ValueError` en el punto de llamada, porque el servidor lee la columna como un entero de 32 bits sin signo y almacenaría NULL para cualquier otro valor. -- Las claves de correlación tienen ámbito por tipo y sesión, por lo que una llamada a herramienta y un hook pueden compartir un id sin problemas, y dos sesiones concurrentes pueden reutilizar los mismos ids sin colisionar. No tienen ámbito por agente: un par abierto bajo un agente y cerrado bajo otro sigue correlacionando, que es el caso habitual en frameworks multi-agente. -- `request_id` empareja `model_request` con `model_response`. Sin él, los eventos de modelo se emparejan en orden por agente, por lo que las llamadas concurrentes se emparejan incorrectamente. -- Un par dividido entre procesos sigue correlacionando en destino, pero el SDK no puede calcular su duración en proceso. -- El mapa de pendientes almacena como máximo 10.000 inicios y desaloja la entrada más antigua cuando se llena. +- `duration_ms` **sí** se acepta en `model_response`, porque solo el llamador conoce la latencia real del proveedor. Debe ser un entero — un float lanza `ValueError` en el punto de llamada, porque el servidor lee la columna como un entero sin signo de 32 bits y almacenaría NULL para cualquier otro tipo. +- Las claves de correlación tienen como ámbito el tipo y la sesión, por lo que una llamada a herramienta y un hook pueden compartir un id de forma segura, y dos sesiones concurrentes pueden reutilizar los mismos ids sin colisiones. No tienen como ámbito el agente: un par abierto bajo un agente y cerrado bajo otro sigue correlacionándose, que es el caso habitual en frameworks multi-agente. +- `request_id` empareja `model_request` con `model_response`. Sin él, los eventos de modelo se emparejan en orden por agente, de modo que las llamadas concurrentes se desemparejan. +- Un par dividido entre procesos sigue correlacionándose en destino, pero el SDK no puede calcular su duración en proceso. +- El mapa de pendientes admite como máximo 10.000 inicios y desaloja la entrada más antigua cuando se llena. - + -Instalar `failproofai-sdk` instala todo, los cuatro adaptadores incluidos. Los extras incorporan el **framework**, no el adaptador. +Instalar `failproofai-sdk` instala todo, incluyendo los cuatro adaptadores. Los extras instalan el **framework**, no el adaptador. ```python import failproofai_sdk # no carga nada fuera de la biblioteca estándar failproofai_sdk.instrument() # importa solo los adaptadores que realmente necesitas ``` -`import failproofai_sdk` es contractualmente sin dependencias, verificado por un test que instala la wheel compilada con `--no-deps` y otro que demuestra que ningún framework llega a `sys.modules`. +`import failproofai_sdk` es contractualmente de cero dependencias, verificado por una prueba que instala la wheel construida con `--no-deps` y otra que demuestra que ningún framework llega a `sys.modules`. - No existe el atributo `failproofai_sdk.crewai`. Los adaptadores no se exponen deliberadamente en el paquete de nivel superior: acceder a uno importaría el framework como efecto secundario del acceso al atributo, rompiendo la promesa de cero dependencias. Usa `instrument()`. + No existe el atributo `failproofai_sdk.crewai`. Los adaptadores no están expuestos deliberadamente en el paquete de nivel superior: acceder a uno importaría el framework como efecto secundario del acceso al atributo, rompiendo la promesa de cero dependencias. Usa `instrument()`. ```python failproofai_sdk.instrument() # todos los frameworks ya importados failproofai_sdk.instrument("crewai") # exactamente uno, por nombre -failproofai_sdk.uninstrument("crewai") # deshacerlo +failproofai_sdk.uninstrument("crewai") # restaurarlo ``` | Nombre | También acepta | @@ -559,7 +559,7 @@ failproofai_sdk.uninstrument("crewai") # deshacerlo | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -La detección automática lee `sys.modules`, no la lista de paquetes instalados, por lo que un framework que tienes instalado pero nunca has importado no se instrumenta y nunca se importa en tu nombre. Para ver qué está conectado: +La detección automática lee `sys.modules`, no la lista de paquetes instalados, por lo que un framework que tienes instalado pero que nunca importaste no se instrumenta y nunca se importa en tu nombre. Para ver qué está conectado: ```python from failproofai_sdk.integrations import active, available @@ -569,20 +569,20 @@ active() # ('langchain',) ``` - **`instrument("crewai")` en una máquina sin CrewAI no lanza una excepción.** Registra una advertencia y devuelve `()`, por lo que un framework faltante nunca derrumba un proceso que también instrumenta otros. + **`instrument("crewai")` en una máquina sin CrewAI no lanza una excepción.** Registra una advertencia y devuelve `()`, de modo que un framework que falta nunca derriba un proceso que también instrumenta otros. - La advertencia incluye el `ImportError` subyacente, y ese mensaje indica el comando de instalación exacto — así que la corrección está en tus logs, no oculta. + La advertencia lleva el `ImportError` subyacente, y ese mensaje indica el comando de instalación exacto — así que la solución está en tus logs, no oculta. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Establece `FAILPROOFAI_SDK_STRICT=1` para que lance una excepción en su lugar. Ese flag se **lee una vez y se cachea**, así que expórtalo antes de que inicie tu proceso, no lo establezcas a mitad de ejecución. + Establece `FAILPROOFAI_SDK_STRICT=1` para que lance una excepción en su lugar. Ese flag se lee **una vez y se cachea**, así que expórtalo antes de que tu proceso inicie en lugar de establecerlo a mitad de la ejecución. - **`instrument()` debe llamarse *después* de importar tu framework.** La detección automática lee `sys.modules`, por lo que una llamada sin argumentos antes del import no encuentra nada, no instala nada y devuelve `()`. + **`instrument()` debe ir *después* de la importación de tu framework.** La detección automática lee `sys.modules`, por lo que una llamada vacía antes de la importación no encuentra nada, no instala nada y devuelve `()`. @@ -594,7 +594,7 @@ import langchain # demasiado tarde, nada está conectado ``` ```python Right -import langchain # importa el framework primero +import langchain # primero importa el framework import failproofai_sdk failproofai_sdk.instrument() # lo encuentra -> ('langchain',) @@ -608,55 +608,53 @@ failproofai_sdk.instrument("langchain") ``` -Si te equivocas, el proceso se ejecuta con el SDK importado, el adaptador aparentemente instalado, y **sin emitir un solo evento**. Registra una advertencia que lo indica exactamente — así que comprueba tus logs primero cuando una ejecución no registra nada. +Si te equivocas, el proceso se ejecuta con el SDK importado, el adaptador aparentemente instalado y **sin emitir ni un solo evento**. Registra una advertencia que dice exactamente eso — así que comprueba tus logs primero cuando una ejecución no registra nada. - + ```mermaid flowchart LR A["Tu agente"] --> B["Adaptador"] B --> C["Writer
cola en memoria"] C -->|"cada 0.5s"| D["Spool
JSONL en disco"] - D --> E["Daemon de Failproof"] + D --> E["Failproof daemon"] E -->|"HTTPS"| F["Cloud"] ``` | Etapa | Función | Se ejecuta en | | --- | --- | --- | -| Adaptador | Traduce un callback del framework en uno de los 15 tipos de evento | Tu proceso | -| Writer | Encola, agrupa y escribe JSONL atómicamente | Tu proceso, hilo de fondo | -| Spool | Transferencia durable, sobrevive a que tu proceso termine | Disco local | -| Daemon | Vigila el spool, envía lotes y elimina los enviados | Tu máquina | -| Ingest | Asigna un id de fila y clave de dedup, promueve columnas consultables | Cloud | +| Adaptador | Traduce un callback del framework a uno de los 15 tipos de eventos | Tu proceso | +| Writer | Encola, agrupa y escribe JSONL atómicamente | Tu proceso, hilo en segundo plano | +| Spool | Handoff duradero, sobrevive a la salida de tu proceso | Disco local | +| Daemon | Vigila el spool, envía batches, elimina lo que envió | Tu máquina | +| Ingest | Asigna id de fila y clave de deduplicación, promueve columnas consultables | Cloud | -El spool es lo que hace esto seguro: tu agente nunca bloquea esperando la red, y una interrupción de Cloud significa un directorio en crecimiento en lugar de eventos perdidos. +El spool es lo que hace esto seguro: tu agente nunca se bloquea en la red, y una interrupción de Cloud significa un directorio creciente en lugar de eventos perdidos. -Cada flush escribe un archivo de lote, primero como `.tmp`, luego `fsync`, luego un renombrado atómico: +Cada flush escribe un archivo de batch, primero `.tmp`, luego `fsync`, luego un rename atómico: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -El daemon solo recoge `.jsonl`, por lo que nunca puede leer un archivo a medio escribir. El nombre lleva un timestamp, id de proceso y número de secuencia, por lo que dos procesos que hagan flush en el mismo milisegundo no colisionan. La cola tiene un límite de 10.000 eventos; a partir de ahí descarta los más antiguos y lo registra en el log. +El daemon solo recoge `.jsonl`, por lo que nunca puede leer un archivo escrito a medias. El nombre lleva timestamp, id de proceso y número de secuencia, de modo que dos procesos que hagan flush en el mismo milisegundo no pueden colisionar. La cola tiene un límite de 10.000 eventos; a partir de ahí descarta el más antiguo y lo registra. - **`collector.redact` no se aplica a los eventos de tu SDK.** Nunca los ve. + **`collector.redact` tiene por defecto `minimal` también para los eventos del SDK.** El SDK limpia antes de escribir un batch en disco, y el daemon repite el mismo paso determinista antes de subir para que los batches de SDKs más antiguos estén protegidos. -El daemon **envía** tus lotes. No los abre ni los reescribe. +El daemon lee cada batch y aplica redacción en memoria antes de subir. No reescribe el archivo del spool que leyó. -| Eventos | Escritos por | ¿Redactados por `collector.redact`? | +| Eventos | Escritos por | Dónde se ejecuta la redacción minimal | | --- | --- | --- | -| Transcripciones de sesión CLI | El daemon | Sí | -| Actividad de hooks | El daemon | Sí | -| **Todo lo que emite el SDK** | **Tu proceso** | **No** | +| Transcripciones de sesión CLI | El daemon | Antes de que el daemon escriba el batch | +| Actividad de hooks | El daemon | Antes de que el daemon escriba el batch | +| **Todo lo que emite el SDK** | **Tu proceso** | **Antes de que el SDK escriba el batch y de nuevo antes de la subida del daemon** | -La redacción se ejecuta donde el daemon *escribe* sus propios eventos — no donde se *envían* los lotes. Así que un prompt o un argumento de herramienta que contenga una clave API la conservará al llegar. - -Esto es deliberado. Estas son tus propias llamadas de instrumentación, y reescribirlas en tránsito significaría que los eventos que recibes no son los que emitiste. +Establece `collector.redact` en `off` solo cuando los payloads literales sean un requisito explícito; tanto el SDK como el daemon respetan esa configuración. La redacción minimal detecta claves de API comunes, tokens bearer, JWTs y asignaciones de secretos. No puede identificar texto sensible arbitrario. **Controlas los payloads en el origen, en dos lugares:** @@ -664,37 +662,37 @@ Esto es deliberado. Estas son tus propias llamadas de instrumentación, y reescr - Desactiva la captura de contenido en el adaptador. **El nombre de la opción varía, y un adaptador no tiene ninguna** — no es un único interruptor universal: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **sin interruptor de contenido en absoluto**; `session_id` es la única opción que lee, por lo que los prompts y las respuestas siempre se registran. + - CrewAI — **sin interruptor de contenido**; `session_id` es la única opción que lee, por lo que prompts y completaciones siempre se registran. - `instrument()` descarta las opciones que un adaptador no lee, por lo que pasar el nombre incorrecto no lanza nada ni cambia nada. - - No pases el secreto a `input=` desde el principio. + `instrument()` descarta las opciones que un adaptador no lee, por lo que pasar un nombre incorrecto no lanza nada ni cambia nada. + - Simplemente no pases el secreto a `input=` desde el principio. - `collector.redact` no es un sustituto de ninguna de las dos opciones. + `collector.redact` es defensa en profundidad, no un sustituto de ninguno de los dos. **Un directorio de spool vacío es el estado saludable.** No lo uses para verificar la entrega. -El daemon elimina cada lote en milisegundos después de enviarlo, por lo que un `ls` compite con el collector y muestra una fracción de lo que emitiste — indistinguible de un SDK que no registró nada. +El daemon elimina cada batch en milisegundos tras enviarlo, por lo que un `ls` compite con el colector y muestra una fracción de lo que emitiste — indistinguible de un SDK que no registró nada. -Para confirmar que los eventos realmente llegaron, comprueba el panel. Para ver cómo se llena el spool, detén el daemon primero. +Para confirmar que los eventos realmente llegaron, comprueba el dashboard. Para ver cómo se llena el spool, detén primero el daemon. - + -Cada callback se ejecuta dentro de un wrapper cuyo único trabajo es relanzar, por lo que tu llamada está en exactamente un `try` y todo lo que hace el SDK ocurre fuera de él. +Cada callback se ejecuta dentro de un wrapper cuya única función es volver a lanzar, de modo que tu llamada está en exactamente un `try` y todo lo que hace el SDK ocurre fuera de él. | Qué ocurre | Resultado | | --- | --- | | Un hook lanza una excepción | Se registra una vez con su traceback. Tu llamada no se ve afectada | -| El mismo hook lanza tres veces | Ese hook se deshabilita para el resto del proceso, con una línea de error | -| `FAILPROOFAI_SDK_STRICT=1` está establecido | La excepción se relanza en su lugar | -| Una versión del framework está fuera del rango probado | Avisa una vez, instrumenta de todas formas | -| Falta una sola capacidad | Ese hook se deshabilita, nunca el adaptador completo | +| El mismo hook lanza tres veces | Ese hook se desactiva para el resto del proceso, con una línea de error | +| Se establece `FAILPROOFAI_SDK_STRICT=1` | La excepción se vuelve a lanzar en su lugar | +| Una versión de framework está fuera del rango probado | Avisa una vez e instrumenta de todas formas | +| Falta una capacidad individual | Solo ese hook se desactiva, nunca el adaptador completo | -El comportamiento por defecto es correcto en producción e incorrecto al depurar, porque solo puede demostrar que no se produjo un crash. Establece `FAILPROOFAI_SDK_STRICT=1` para hacer visible un fallo suprimido. +El comportamiento por defecto es el correcto en producción y el incorrecto al depurar, porque solo puede demostrar "no falló". Establece `FAILPROOFAI_SDK_STRICT=1` para que un fallo suprimido sea ruidoso. @@ -704,7 +702,7 @@ El comportamiento por defecto es correcto en producción e incorrecto al depurar - Un evento de apertura no tiene uno de cierre: un `model_request` sin `model_response`, o un `tool_use` sin `tool_result`. Usa los ámbitos, que garantizan el par incluso cuando el cuerpo lanza una excepción. Si llamas a los métodos de evento directamente, usa `try` y `finally`. + Un evento de apertura no tiene cierre correspondiente: un `model_request` sin `model_response`, o un `tool_use` sin `tool_result`. Usa los ámbitos, que garantizan el par incluso cuando el cuerpo lanza una excepción. Si llamas a los métodos de evento directamente, usa `try` y `finally`. @@ -712,28 +710,28 @@ El comportamiento por defecto es correcto en producción e incorrecto al depurar - El hilo nunca heredó el contexto. Envuelve el callable en `failproofai_sdk.propagate()`. Consulta [Hilos y async](#threads-and-async). + El hilo nunca heredó el contexto. Envuelve el callable en `failproofai_sdk.propagate()`. Ver [Hilos y async](#threads-and-async). - Los campos extra se fusionan al final, por lo que uno con el nombre de un campo real como `model` o `outcome` lo sobreescribiría y cambiaría una columna almacenada. Usa un espacio de nombres propio; los adaptadores utilizan el prefijo `fw_`. + Los campos extra se fusionan al final, por lo que uno con el nombre de un campo real como `model` o `outcome` lo sobreescribiría y cambiaría una columna almacenada. Ponle un namespace al tuyo; los adaptadores usan el prefijo `fw_`. - `agent_id` es una faceta de baja cardinalidad y pusiste un id de ejecución en ella. Usa un rol o nombre de nodo y guarda el id real en un campo del payload. + `agent_id` es una faceta de baja cardinalidad y pusiste un id de ejecución en ella. Usa un nombre de rol o nodo y pon el id real en un campo del payload. -## Siguiente paso +## Siguientes pasos - Pares, ids, ciclo de vida de sesión y entrega. + Pares, ids, ciclo de vida de la sesión y entrega. - + Sigue la causalidad a través de la sesión que acabas de capturar. - + LangGraph, CrewAI, LlamaIndex y Pydantic AI. \ No newline at end of file diff --git a/docs/fr/start/integrations/custom-agents.mdx b/docs/fr/start/integrations/custom-agents.mdx index 0fd0f1cd..b122924e 100644 --- a/docs/fr/start/integrations/custom-agents.mdx +++ b/docs/fr/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "Agents personnalisés" sidebarTitle: "Agents personnalisés" -description: "Instrumentez un agent que vous avez écrit vous-même, ou un framework sans adaptateur." +description: "Instrumentez un agent que vous avez développé vous-même, ou un framework sans adaptateur." icon: "code" --- -Pour un agent que vous avez écrit vous-même, ou un framework pour lequel Failproof AI ne dispose pas d'adaptateur. Il n'y a rien à instrumenter : vous émettez les événements. +Pour un agent que vous avez développé vous-même, ou un framework pour lequel Failproof AI ne dispose pas d'adaptateur. Il n'y a rien à instrumenter : vous émettez les événements. -C'est la même API que les quatre adaptateurs de framework utilisent en interne. Ils ne sont que des tables de traduction par-dessus. +C'est la même API qu'appellent les quatre adaptateurs de framework en coulisses. Ce sont des tables de correspondance au-dessus d'elle. ## Installation @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # une exécution t.output = search(q) # un appel d'outil ``` -Lisez-le de haut en bas et il dit ce qu'il signifie : +En lisant de haut en bas, le sens est explicite : -| À encadrer | Pour indiquer | +| Envelopper dans | Pour indiquer | | --- | --- | | `session()` | Ces événements appartiennent à la même exécution | -| `agent()` | Quelque chose effectue un travail — donnez-lui un nom reconnaissable dans une liste | -| `tool_call()` | Ceci est un outil, et voici ce qu'il a retourné | +| `agent()` | Quelque chose effectue un travail — donnez-lui un nom que vous reconnaîtriez dans une liste | +| `tool_call()` | Il s'agit d'un outil, et voici ce qu'il a retourné | Et ce que chacun émet réellement : -| Portée | Émet | Objectif | +| Portée | Émet | Rôle | | --- | --- | --- | | `session()` | Rien | Lie un identifiant de session, regroupant une exécution | -| `agent()` | `agent_start`, `agent_end` | Encadre une unité de travail | -| `tool_call()` | `tool_use`, `tool_result` | Encadre un outil et le mesure | +| `agent()` | `agent_start`, `agent_end` | Délimite une unité de travail | +| `tool_call()` | `tool_use`, `tool_result` | Délimite un outil et le mesure | -Tout ce qui se trouve à l'intérieur peut omettre `session_id` et `agent_id`. Les portées lient l'identité sur des variables de contexte et chaque appel d'événement la récupère, vous n'avez donc jamais besoin de propager les ids à travers vos fonctions. +Tout ce qui se trouve à l'intérieur peut omettre `session_id` et `agent_id`. Les portées lient l'identité sur des variables de contexte, et chaque appel d'événement la relit — vous n'avez donc jamais à propager des identifiants dans vos fonctions. -Les trois fonctionnent avec `async with` comme avec `with`. +Les trois fonctionnent aussi bien avec `async with` qu'avec `with`. -L'imbrication d'agents construit l'arbre. `parent_id` et la profondeur sont calculés à partir de la pile : +L'imbrication d'agents construit l'arbre. `parent_id` et la profondeur sont calculés depuis la pile : ```python with failproofai_sdk.session(): @@ -59,7 +59,7 @@ with failproofai_sdk.session(): ... ``` -## Comment une portée se ferme +## Fermeture d'une portée `agent()` gère les exceptions pour vous : @@ -70,11 +70,11 @@ with failproofai_sdk.session(): | `KeyboardInterrupt`, `SystemExit` | `error`, puis `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | `agent_end` uniquement | `cancelled` | -L'erreur est émise avant `agent_end`, car le tableau de bord ferme le span à `agent_end` et tout ce qui suit ne serait attribué à rien. Une annulation n'est pas un échec, donc les exécutions annulées ne polluent pas la surface des erreurs. L'exception est toujours re-levée : une portée n'avale jamais les exceptions. +L'erreur est émise avant `agent_end`, car le tableau de bord ferme le span à `agent_end` et tout ce qui suit n'est attribué à rien. Une annulation n'est pas un échec, donc les exécutions annulées ne polluent pas la surface des erreurs. L'exception est toujours re-levée : une portée n'avale jamais. ## Les méthodes d'événements -Quinze méthodes en six familles. La plupart vont par paires — vous émettez l'ouverture, puis la fermeture, et le SDK mesure le span entre les deux. +Quinze méthodes en six familles. La plupart vont par paires — vous émettez l'ouverture, puis la fermeture, et le SDK mesure l'intervalle entre les deux. | Famille | Ouvre | Ferme | Autonome | | --- | --- | --- | --- | @@ -87,7 +87,7 @@ Quinze méthodes en six familles. La plupart vont par paires — vous émettez l | **Échecs** | — | — | `error` | - Préférez les portées — `agent()` et `tool_call()` — partout où elles s'adaptent. Elles garantissent l'événement de fermeture même si le corps lève une exception. Recourez à ces méthodes directement quand votre flux de contrôle ne se prête pas à l'imbrication, comme un appel de modèle dans une fonction auxiliaire. + Préférez les portées — `agent()` et `tool_call()` — partout où elles s'appliquent. Elles garantissent l'événement de fermeture même lorsque le corps lève une exception. Utilisez ces méthodes directement lorsque votre flux de contrôle ne s'imbrique pas, par exemple un appel de modèle dans une fonction auxiliaire. @@ -148,16 +148,16 @@ failproofai_sdk.event.error( | `human_wait` / `human_input` | **L'agent a sollicité une personne** — une porte d'approbation, une question de clarification | | `human_pause` / `human_interrupt` | **Une personne a agi sur l'agent** — un bouton d'arrêt, une pause opérateur | - Aucun framework ne signale la seconde paire, c'est donc toujours à vous de l'émettre. + Aucun framework ne signale la deuxième paire, donc c'est toujours à vous de l'émettre. - **Passez `request_id` lorsque des appels de modèles s'exécutent en parallèle.** Sans lui, les requêtes et les réponses sont appariées dans l'ordre d'arrivée par agent — et les appels concurrents sont mal appariés, associant chaque réponse à la mauvaise requête. + **Passez `request_id` lorsque des appels de modèle s'exécutent en parallèle.** Sans lui, les requêtes et les réponses sont appariées dans l'ordre d'arrivée par agent — et les appels concurrents sont mal appariés, associant chaque réponse à la mauvaise requête. ## Exemple -Une boucle d'appel d'outils contre l'API OpenAI, sans framework d'agent : +Une boucle d'appels d'outils contre l'API OpenAI, sans framework d'agent : ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """Un appel de modèle, encadré par la paire.""" + """Un appel de modèle, délimité par la paire.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # borné ; une boucle non bornée est un bug en soi + for _ in range(4): # borné ; une boucle d'agent non bornée est un bug en soi message = turn(messages) if not message.tool_calls: break @@ -204,7 +204,7 @@ with failproofai_sdk.session(): }) ``` -Cela produit les mêmes six types d'événements qu'un adaptateur vous fournirait. La version exécutable complète, avec les définitions d'outils, est incluse dans le dépôt du SDK sous `docs/manual/examples/`. +Cela produit les six mêmes types d'événements qu'un adaptateur vous donnerait. La version exécutable complète, avec les définitions d'outils, est incluse dans le dépôt du SDK sous `docs/manual/examples/`. ## Threads et async @@ -215,33 +215,33 @@ Les variables de contexte se propagent automatiquement dans les tâches asyncio. async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads : enveloppez l'appelable +# threads : enveloppez le callable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Sans `propagate()`, les événements du worker lèvent une `TypeError` indiquant le correctif plutôt que d'atterrir sans session. C'est délibéré : un événement sans session est ignoré à l'ingestion avec une réponse `200`, ce qui constitue l'échec silencieux que la couche d'identité existe précisément pour éviter. +Sans `propagate()`, les événements du worker lèvent un `TypeError` indiquant le correctif à apporter plutôt que d'atterrir sur aucune session. C'est intentionnel : un événement sans session est ignoré par l'ingest et reçoit une réponse `200`, ce qui est l'échec silencieux que la couche d'identité existe précisément pour prévenir. ## Instrumenter un framework sans adaptateur -Tout framework d'agent vous expose les mêmes trois points d'insertion. Mappez-les et vous avez une trace complète — les quatre adaptateurs fournis ne font rien de plus que cela. +Chaque framework d'agent vous offre les mêmes trois points d'ancrage. Mappez-les et vous obtenez une trace complète — les quatre adaptateurs livrés ne font rien de plus que cela. -| Le point d'insertion | Ce que vous écrivez | Ce qui est enregistré | +| Le point d'ancrage | Ce que vous écrivez | Ce qui est enregistré | | --- | --- | --- | | L'exécution | `session()` + `agent()` | `agent_start`, `agent_end` | | Chaque outil | `tool_call()` | `tool_use`, `tool_result` | | Chaque appel de modèle | La paire `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - + Dans ce que le framework appelle un wrapper d'outil ou un middleware. ```python @@ -264,23 +264,23 @@ Tout framework d'agent vous expose les mêmes trois points d'insertion. Mappez-l - **Vous avez un nœud, une étape ou une frontière de middleware qui mérite d'être visible ?** Enveloppez-le dans une paire de hooks — `hook_triggered` / `hook_completed` — et non dans un `agent()` imbriqué. `agent_id` est une facette à faible cardinalité, et une entrée par nœud la sature. Les spans de hooks s'affichent de la même façon et vous donnent la latence par nœud. + **Vous avez un nœud, une étape ou une frontière de middleware qui mérite d'être visible ?** Enveloppez-le dans une paire de hooks — `hook_triggered` / `hook_completed` — et non dans un `agent()` imbriqué. `agent_id` est une facette à faible cardinalité, et une entrée par nœud la noie. Les spans de hooks s'affichent de la même façon et vous donnent la latence par nœud. - **Manuel et automatique se combinent.** Un adaptateur s'exécutant dans une portée écrite à la main rejoint cette session et se parenté à cet agent, vous obtenez donc un seul arbre plutôt que deux — utile quand vous instrumentez vous-même un framework aux côtés d'un framework supporté. + **Le manuel et l'automatique se composent.** Un adaptateur s'exécutant dans une portée écrite à la main rejoint cette session et se rattache à cet agent, vous donnant un seul arbre plutôt que deux — utile lorsque vous instrumentez vous-même un framework en parallèle d'un framework supporté. - - Deux raisons, et les trois points d'insertion ci-dessus sont la réponse aux deux : + + Deux raisons, et les trois points d'ancrage ci-dessus sont la réponse aux deux : - `autogen-core` n'est plus maintenu depuis septembre 2025. - - AG2 n'expose aucun point d'enregistrement global équivalent aux hooks des autres frameworks, ce qui fait qu'instrumenter AG2 implique d'envelopper chaque agent à chaque site de construction. + - AG2 n'expose aucun point d'enregistrement global équivalent aux hooks des autres frameworks, donc l'instrumenter signifie envelopper chaque agent à chaque site de construction. - Mapper les points d'insertion à la main enregistre les mêmes événements, avec la même fidélité, qu'un adaptateur fourni. + Mapper les points d'ancrage à la main enregistre les mêmes événements, avec la même fidélité, qu'un adaptateur livré le ferait. -## Aller plus loin +## Approfondir Comment l'enregistrement fonctionne réellement. Rien de tout cela n'est nécessaire pour démarrer. @@ -288,7 +288,7 @@ Comment l'enregistrement fonctionne réellement. Rien de tout cela n'est nécess -Chaque enregistrement a la même forme : un span s'ouvre, le travail s'imbrique à l'intérieur, et chaque événement d'ouverture reçoit un événement de fermeture correspondant. +Chaque enregistrement a la même forme : un span s'ouvre, le travail s'imbrique à l'intérieur, et chaque événement d'ouverture reçoit un événement de fermeture. ```mermaid flowchart LR @@ -300,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -La **paire** est l'unité. Chaque événement de fermeture porte une durée que le SDK mesure depuis l'événement d'ouverture correspondant. +La **paire** est l'unité. Chaque événement de fermeture porte une durée mesurée par le SDK depuis son événement d'ouverture. -Voici une vraie exécution par framework — capturée à partir des exemples fournis avec le SDK, nom de modèle normalisé. Notez tout ce qu'un seul appel renvoie. +Voici une exécution réelle par framework — capturée depuis les exemples livrés avec le SDK, nom du modèle normalisé. Notez la quantité d'informations retournées par un seul appel. @@ -323,7 +323,7 @@ Voici une vraie exécution par framework — capturée à partir des exemples fo 14 +5.721s agent_end LangGraph · success ``` - Les nœuds deviennent des paires de hooks, vous obtenez donc la latence par nœud sans encombrer la liste des agents. + Les nœuds deviennent des paires de hooks, vous obtenez donc la latence par nœud sans qu'ils encombrent la liste des agents. @@ -360,7 +360,7 @@ Voici une vraie exécution par framework — capturée à partir des exemples fo 26 +7.038s agent_end Agent · success ``` - La boucle de l'agent elle-même est visible, pas seulement ses appels de modèles. + La boucle de l'agent elle-même est visible, pas seulement ses appels de modèle. @@ -375,7 +375,7 @@ Voici une vraie exécution par framework — capturée à partir des exemples fo 8 +8.119s agent_end agent · success ``` - Pas de paires de hooks : Pydantic AI n'a pas de frontière de nœud ou d'étape à encadrer. + Pas de paires de hooks : Pydantic AI n'a pas de frontière de nœud ou d'étape à délimiter. @@ -394,11 +394,11 @@ Voici une vraie exécution par framework — capturée à partir des exemples fo - + -**Il n'y a pas d'événement de fin de session.** Une session n'est pas quelque chose que vous fermez — c'est un groupe d'événements partageant un même `session_id`. +**Il n'y a pas d'événement de fin de session.** Une session n'est pas quelque chose que vous fermez — c'est un groupe d'événements partageant un `session_id`. -Le statut est dérivé de la forme de la trace : +Le statut est déduit de la forme de la trace : | Statut | Quand | | --- | --- | @@ -407,17 +407,17 @@ Le statut est dérivé de la forme de la trace : | `error` | Rien n'est ouvert, et au moins un événement a échoué | | `done` | Rien n'est ouvert, et rien n'a échoué | -Une session se termine donc quand chaque paire est fermée. Les adaptateurs émettent `agent_end` pour vous, et au moment du teardown ils ferment tout ce qui est encore ouvert en le marquant incomplet — une exécution ayant planté se stabilise en `done` avec un écart visible plutôt que de rester suspendue. +Une session se termine donc quand toutes les paires sont fermées. Les adaptateurs émettent `agent_end` pour vous, et au démontage ils ferment tout ce qui est encore ouvert et le marquent comme incomplet — une exécution plantée se règle en `done` avec un écart visible plutôt qu'en restant bloquée. - C'est pourquoi une session peut s'étendre sur deux appels. Un `interrupt()` LangGraph met l'exécution en pause, le span racine reste délibérément ouvert, et l'appel de reprise le ferme. Les deux appels forment une seule session. + C'est pourquoi une session peut s'étendre sur deux appels. Un `interrupt()` LangGraph met l'exécution en pause, le span racine reste délibérément ouvert, et l'appel de reprise le ferme. Les deux appels constituent une seule session. - + -`session_id` et `agent_id` sont optionnels sur chaque méthode d'événement. S'ils sont omis, ils sont résolus depuis la portée englobante : +`session_id` et `agent_id` sont optionnels sur chaque méthode d'événement. Omis, ils sont résolus depuis la portée englobante : ```python with failproofai_sdk.session(): @@ -425,55 +425,55 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Les passer explicitement fonctionne toujours et prend la priorité. Si rien n'est lié et rien n'est passé, l'appel lève une `TypeError` indiquant le correctif plutôt que d'émettre un événement sans session, que l'ingestion ignorerait tout en répondant `200`. +Les passer explicitement fonctionne toujours et prend la priorité. Sans rien de lié ni passé, l'appel lève un `TypeError` indiquant le correctif plutôt que d'émettre un événement sans session, que l'ingest ignorerait tout en répondant `200`. Les portées lient l'identité sur des variables de contexte. Celles-ci se propagent automatiquement dans les tâches asyncio mais pas dans les nouveaux threads — enveloppez un worker dans `failproofai_sdk.propagate()`. -#### Qui crée quel identifiant +#### Qui génère quel identifiant -| Id | Créé par | Notes | +| Identifiant | Généré par | Notes | | --- | --- | --- | -| `session_id` | Vous, ou le SDK | `session("chat-42")` est utilisé tel quel ; si omis, le SDK génère un `uuid4().hex` | +| `session_id` | Vous, ou le SDK | `session("chat-42")` est utilisé tel quel ; omis, le SDK génère un `uuid4().hex` | | `agent_id` | Vous, ou le framework | Depuis `agent("analyst")`, un `role` CrewAI, un `FunctionAgent.name`. Une valeur ressemblant à un UUID est refusée et remplacée | -| `tool_call_id`, `hook_id`, `request_id` | Vous, ou le framework | Les adaptateurs réutilisent les propres ids d'exécution du framework, ce qui permet aux paires de survivre aux sauts de threads | -| **Id d'événement** | **Cloud, à l'ingestion** | Le SDK n'en émet aucun | -| **`dedup_key`** | **Cloud, à l'ingestion** | Un hash de l'org, de la session, du timestamp, du type et du payload. C'est la vraie identité — elle fait qu'un batch réessayé s'effondre en un seul plutôt que de se dupliquer | +| `tool_call_id`, `hook_id`, `request_id` | Vous, ou le framework | Les adaptateurs réutilisent les identifiants d'exécution propres au framework, ce qui explique pourquoi les paires survivent aux sauts de threads | +| **Identifiant d'événement** | **Cloud, à l'ingest** | Le SDK n'en émet aucun | +| **`dedup_key`** | **Cloud, à l'ingest** | Un hash de l'organisation, de la session, du timestamp, du type et du payload. C'est la véritable identité — elle fait qu'un lot réessayé se compresse plutôt que de se dupliquer | #### Comment les adaptateurs résolvent `session_id` -Le premier match gagne : +La première correspondance gagne : 1. Une option `session_id` explicite 2. Des métadonnées par appel 3. La portée `session()` englobante -4. Les métadonnées du framework -5. Le propre id d'exécution du framework +4. Des métadonnées du framework +5. L'identifiant d'exécution propre au framework -Il n'est jamais inventé tant qu'un de ces éléments existe — un id synthétisé fractionnerait une exécution en plusieurs sessions. +Il n'est jamais inventé tant que l'une de ces sources existe — un identifiant synthétisé fragmenterait une exécution sur plusieurs sessions. #### Gardez `agent_id` à faible cardinalité -C'est la facette principale sur chaque surface du tableau de bord, et une colonne `LowCardinality(String)`. Une valeur par exécution dégrade la colonne et remplit le menu déroulant de filtre avec une entrée par exécution. +C'est la facette principale sur toutes les surfaces du tableau de bord, et une colonne `LowCardinality(String)`. Une valeur par exécution dégrade la colonne et remplit le menu déroulant de filtres avec une entrée par exécution. Les adaptateurs défendent cette colonne pour vous : | Ce que le framework fournit | Enregistré comme | Pourquoi | | --- | --- | --- | | `3f9a1c2b-…` (un UUID) | `main` | Rien de lisible à conserver | -| Une longue chaîne hexadécimale brute | `main` | Idem | -| `agent-3f9a1c2b-…` | `agent` | Id par exécution supprimé, partie lisible conservée | +| Une longue chaîne hexadécimale brute | `main` | Même raison | +| `agent-3f9a1c2b-…` | `agent` | Identifiant par exécution supprimé, partie lisible conservée | | `agent-v2` | `agent-v2` | Les segments courts sont laissés tels quels | -| `step-3` | `step-3` | Idem | +| `step-3` | `step-3` | Même chose | -Le vrai id est conservé dans `fw_agent_id` / `fw_run_id`, où il reste interrogeable sans être une facette. +Le véritable identifiant est conservé dans `fw_agent_id` / `fw_run_id`, où il reste interrogeable sans être une facette. - **Cette protection ne touche que les labels choisis par le *framework*.** Un `agent_id` que vous passez vous-même — à `event.*`, ou à `failproofai_sdk.agent(...)` — est enregistré exactement tel quel. Réécrire silencieusement un argument explicite serait pire que la cardinalité qu'il évite, nommez donc vos propres spans en conséquence. + **Cette protection ne touche que les libellés choisis par le *framework*.** Un `agent_id` que vous passez vous-même — à `event.*`, ou à `failproofai_sdk.agent(...)` — est enregistré exactement tel que fourni. Réécrire silencieusement un argument explicite serait pire que la cardinalité qu'il prévient, donc nommez vos propres spans en conséquence. - + | Groupe | Événements | | --- | --- | @@ -484,7 +484,7 @@ Le vrai id est conservé dans `fw_agent_id` / `fw_run_id`, où il reste interrog | Humains | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | Échecs | `error` | -Quel framework enregistre quoi, mesuré depuis les exécutions ci-dessus : +Ce que chaque framework enregistre, mesuré depuis les exécutions ci-dessus : | Événement | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | @@ -493,7 +493,7 @@ Quel framework enregistre quoi, mesuré depuis les exécutions ci-dessus : | Utilisation et résultat d'outil | Oui | Oui | Oui | Oui | Vous | | Hook déclenché et complété | Nœud | Tâche | Étape | — | Vous | | Erreur | Oui | Oui | Oui | Oui | Automatique | -| Attente et saisie humaine | Oui | Oui | Oui | — | Vous | +| Attente humaine et saisie | Oui | Oui | Oui | — | Vous | | Pause et reprise d'agent | Oui | Oui | Oui | — | Vous | Un tiret signifie que le framework n'a pas ce concept. `human_pause` et `human_interrupt` décrivent une *personne* agissant sur l'agent, ce qu'aucun framework ne signale — émettez-les vous-même. @@ -510,44 +510,44 @@ Un événement n'arrive jamais seul. Un ouvre un span, un le ferme, et l'événe | `model_request` | `model_response` | tokens, `stop_reason`, latence | | `tool_use` | `tool_result` | `output` ou `error`, durée | | `hook_triggered` | `hook_completed` | `outcome`, durée | -| `agent_pause` | `agent_resume` | combien de temps a duré la pause | -| `human_wait` | `human_input` | la réponse, et combien de temps la personne a mis | +| `agent_pause` | `agent_resume` | la durée de la pause | +| `human_wait` | `human_input` | la réponse, et le temps que la personne a mis | - Un événement d'ouverture sans événement de fermeture correspondant est un span qui ne se termine jamais. La session s'affiche comme toujours en cours, indéfiniment, et sa durée active ne cesse de croître. C'est le mode d'échec à surveiller quand vous instrumentez à la main. + Un événement d'ouverture sans événement de fermeture est un span qui ne se termine jamais. La session s'affiche comme toujours en cours, à l'infini, et sa durée active continue de croître. C'est le mode d'échec à surveiller lorsque vous instrumentez manuellement. #### Règles de corrélation -- Réutilisez le même `tool_call_id`, `hook_id`, `pause_id` ou `input_id` pour l'événement de complétion correspondant. -- Le SDK calcule `duration_ms` pour `tool_result`, `hook_completed`, `agent_resume` et `human_input`. Le passer à ces méthodes lève une `ValueError`. -- `duration_ms` **est** accepté sur `model_response`, car seul l'appelant connaît la vraie latence du fournisseur. Il doit être un entier — un flottant lève une `ValueError` au site d'appel, car le serveur lit la colonne comme un entier non signé 32 bits et stockerait NULL pour tout autre valeur. -- Les clés de corrélation sont délimitées par type et session, donc un appel d'outil et un hook peuvent partager un id en toute sécurité, et deux sessions concurrentes peuvent réutiliser les mêmes ids sans collision. Elles ne sont pas délimitées par agent : une paire ouverte sous un agent et fermée sous un autre se corrèle quand même, ce qui est le cas ordinaire dans les frameworks multi-agents. +- Réutilisez le même `tool_call_id`, `hook_id`, `pause_id`, ou `input_id` pour l'événement de complétion correspondant. +- Le SDK calcule `duration_ms` pour `tool_result`, `hook_completed`, `agent_resume`, et `human_input`. Le passer à ces méthodes lève un `ValueError`. +- `duration_ms` **est** accepté sur `model_response`, car seul l'appelant connaît la vraie latence du fournisseur. Il doit être un entier — un float lève un `ValueError` au site d'appel, car le serveur lit la colonne comme un entier non signé 32 bits et stockerait NULL pour toute autre valeur. +- Les clés de corrélation sont délimitées par type et session, donc un appel d'outil et un hook peuvent partager un identifiant en toute sécurité, et deux sessions concurrentes peuvent réutiliser les mêmes identifiants sans collision. Elles ne sont pas délimitées par agent : une paire ouverte sous un agent et fermée sous un autre est toujours corrélée, ce qui est le cas ordinaire dans les frameworks multi-agents. - `request_id` apparie `model_request` avec `model_response`. Sans lui, les événements de modèle sont appariés dans l'ordre par agent, donc les appels concurrents sont mal appariés. -- Une paire répartie sur plusieurs processus se corrèle toujours en aval, mais le SDK ne peut pas calculer sa durée en cours de processus. -- La map des événements en attente contient au maximum 10 000 entrées et expulse la plus ancienne quand elle est pleine. +- Une paire répartie entre plusieurs processus est toujours corrélée en aval, mais le SDK ne peut pas calculer sa durée intra-processus. +- La table des opérations en attente contient au maximum 10 000 démarrages et expulse l'entrée la plus ancienne quand elle est pleine. - + -L'installation de `failproofai-sdk` installe tout, les quatre adaptateurs inclus. Les extras tirent le **framework**, pas l'adaptateur. +Installer `failproofai-sdk` installe tout, les quatre adaptateurs inclus. Les extras récupèrent le **framework**, pas l'adaptateur. ```python import failproofai_sdk # ne charge rien en dehors de la bibliothèque standard failproofai_sdk.instrument() # importe uniquement les adaptateurs dont vous avez besoin ``` -`import failproofai_sdk` est contractuellement sans dépendance, vérifié par un test qui installe la wheel construite avec `--no-deps` et un autre qui prouve qu'aucun framework n'atteint `sys.modules`. +`import failproofai_sdk` est contractuellement sans dépendance, imposé par un test qui installe le wheel construit avec `--no-deps` et un autre qui prouve qu'aucun framework n'atteint `sys.modules`. - Il n'existe pas d'attribut `failproofai_sdk.crewai`. Les adaptateurs ne sont délibérément pas exposés sur le package de premier niveau : y accéder importerait le framework comme effet de bord d'un accès d'attribut, rompant la promesse de zéro dépendance. Utilisez `instrument()`. + Il n'y a pas d'attribut `failproofai_sdk.crewai`. Les adaptateurs ne sont délibérément pas exposés sur le package de niveau supérieur : y accéder importerait le framework comme effet secondaire d'un accès à un attribut, brisant la promesse zéro-dépendance. Utilisez `instrument()`. ```python -failproofai_sdk.instrument() # tous les frameworks déjà importés +failproofai_sdk.instrument() # tout framework déjà importé failproofai_sdk.instrument("crewai") # exactement un, par nom -failproofai_sdk.uninstrument("crewai") # le remettre comme avant +failproofai_sdk.uninstrument("crewai") # le remettre en place ``` | Nom | Accepte aussi | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # le remettre comme avant | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -La détection automatique lit `sys.modules`, pas la liste des packages installés, donc un framework installé mais jamais importé n'est pas instrumenté et n'est jamais importé à votre place. Pour voir ce qui est câblé : +La détection automatique lit `sys.modules`, pas la liste des packages installés, donc un framework installé mais jamais importé n'est pas instrumenté et n'est jamais importé en votre nom. Pour voir ce qui est connecté : ```python from failproofai_sdk.integrations import active, available @@ -567,20 +567,20 @@ active() # ('langchain',) ``` - **`instrument("crewai")` sur une machine sans CrewAI ne lève pas d'exception.** Il enregistre un avertissement et retourne `()`, donc un framework manquant ne fait jamais tomber un processus qui instrumente d'autres frameworks. + **`instrument("crewai")` sur une machine sans CrewAI ne lève pas d'exception.** Il enregistre un avertissement et retourne `()`, donc un framework manquant ne fait jamais tomber un processus qui instrumente aussi d'autres frameworks. - L'avertissement porte l'`ImportError` sous-jacent, et ce message indique la commande d'installation exacte — le correctif est donc dans vos logs, pas caché. + L'avertissement contient l'`ImportError` sous-jacent, et ce message nomme la commande d'installation exacte — le correctif est donc dans vos logs, pas caché. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Définissez `FAILPROOFAI_SDK_STRICT=1` pour qu'il lève une exception à la place. Ce flag est lu **une seule fois et mis en cache**, exportez-le donc avant le démarrage de votre processus plutôt que de le définir en cours d'exécution. + Définissez `FAILPROOFAI_SDK_STRICT=1` pour qu'il lève une exception à la place. Ce drapeau est lu **une seule fois et mis en cache**, donc exportez-le avant le démarrage de votre processus plutôt que de le définir en cours d'exécution. - **`instrument()` doit venir *après* l'import de votre framework.** La détection automatique lit `sys.modules`, donc un appel nu avant l'import ne trouve rien, n'installe rien et retourne `()`. + **`instrument()` doit être appelé *après* l'import de votre framework.** La détection automatique lit `sys.modules`, donc un appel nu avant l'import ne trouve rien, n'installe rien, et retourne `()`. @@ -588,11 +588,11 @@ active() # ('langchain',) import failproofai_sdk failproofai_sdk.instrument() # sys.modules n'a pas encore langchain -> () -import langchain # trop tard, rien n'est câblé +import langchain # trop tard, rien n'est connecté ``` ```python Right -import langchain # importer le framework en premier +import langchain # importez d'abord le framework import failproofai_sdk failproofai_sdk.instrument() # le trouve -> ('langchain',) @@ -601,63 +601,61 @@ failproofai_sdk.instrument() # le trouve -> ('langchain',) ```python Right, order-proof import failproofai_sdk -# Le nommer importe l'adaptateur à la demande, donc cela fonctionne de n'importe où. +# Le nommer importe l'adaptateur à la demande, donc cela fonctionne depuis n'importe où. failproofai_sdk.instrument("langchain") ``` -Faites cette erreur et le processus s'exécute avec le SDK importé, l'adaptateur apparemment installé, **et pas un seul événement émis**. Cela enregistre un avertissement qui le dit explicitement — vérifiez donc vos logs en premier quand une exécution n'enregistre rien. +Faites une erreur ici et le processus s'exécute avec le SDK importé, l'adaptateur apparemment installé, et **pas un seul événement émis**. Il enregistre un avertissement qui l'indique explicitement — vérifiez donc vos logs en premier lorsqu'une exécution n'enregistre rien. - + ```mermaid flowchart LR A["Votre agent"] --> B["Adaptateur"] B --> C["Writer
file d'attente en mémoire"] C -->|"toutes les 0,5s"| D["Spool
JSONL sur disque"] - D --> E["Daemon Failproof"] + D --> E["Failproof daemon"] E -->|"HTTPS"| F["Cloud"] ``` | Étape | Rôle | S'exécute dans | | --- | --- | --- | -| Adaptateur | Traduit un callback framework en un des 15 types d'événements | Votre processus | -| Writer | Met en file d'attente, regroupe, écrit du JSONL atomiquement | Votre processus, thread en arrière-plan | -| Spool | Transfert durable, survit à la fermeture de votre processus | Disque local | -| Daemon | Surveille le spool, envoie les batches, supprime ce qui a été envoyé | Votre machine | -| Ingest | Attribue un id de ligne et une clé de déduplication, promeut les colonnes interrogeables | Cloud | +| Adaptateur | Traduit un callback du framework en l'un des 15 types d'événements | Votre processus | +| Writer | Met en file d'attente, regroupe, écrit le JSONL de façon atomique | Votre processus, thread d'arrière-plan | +| Spool | Transfert durable, survit à la sortie de votre processus | Disque local | +| Daemon | Surveille le spool, envoie les lots, supprime ce qui a été envoyé | Votre machine | +| Ingest | Assigne un identifiant de ligne et une clé de déduplication, promeut les colonnes interrogeables | Cloud | -Le spool est ce qui rend cela sûr : votre agent ne bloque jamais sur le réseau, et une panne Cloud signifie un répertoire qui grossit plutôt que des événements perdus. +Le spool est ce qui rend cela sûr : votre agent ne se bloque jamais sur le réseau, et une panne Cloud signifie un répertoire qui grossit plutôt que des événements perdus. -Chaque flush écrit un fichier batch, `.tmp` d'abord, puis `fsync`, puis un renommage atomique : +Chaque flush écrit un fichier de lot, `.tmp` d'abord, puis `fsync`, puis un renommage atomique : ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Le daemon ne prend que les `.jsonl`, il ne peut donc jamais lire un fichier à moitié écrit. Le nom de fichier porte un timestamp, un id de processus et un numéro de séquence, donc deux processus flushing dans la même milliseconde ne peuvent pas entrer en collision. La file d'attente est limitée à 10 000 événements ; au-delà, elle supprime les plus anciens et enregistre un log. +Le daemon ne récupère que les `.jsonl`, il ne peut donc jamais lire un fichier partiellement écrit. Le nom du fichier contient un timestamp, un identifiant de processus et un numéro de séquence, de sorte que deux processus flushing dans la même milliseconde ne peuvent pas entrer en collision. La file d'attente est limitée à 10 000 événements ; au-delà, elle abandonne les plus anciens et enregistre un log. - **`collector.redact` ne s'applique pas à vos événements SDK.** Il ne les voit jamais. + **`collector.redact` est à `minimal` par défaut pour les événements SDK également.** Le SDK expurge avant d'écrire un lot sur disque, et le daemon répète le même passage déterministe avant l'upload afin que les lots d'anciens SDK soient protégés. -Le daemon **envoie** vos batches. Il ne les ouvre ni ne les réécrit. +Le daemon lit chaque lot et applique la rédaction en mémoire avant l'upload. Il ne réécrit pas le fichier spool qu'il a lu. -| Événements | Écrits par | Traités par `collector.redact` ? | +| Événements | Écrits par | Où la rédaction minimale s'exécute | | --- | --- | --- | -| Transcriptions de sessions CLI | Le daemon | Oui | -| Activité des hooks | Le daemon | Oui | -| **Tout ce que le SDK émet** | **Votre processus** | **Non** | +| Transcriptions de sessions CLI | Le daemon | Avant que le daemon écrive le lot | +| Activité de hooks | Le daemon | Avant que le daemon écrive le lot | +| **Tout ce que le SDK émet** | **Votre processus** | **Avant que le SDK écrive le lot et à nouveau avant l'upload par le daemon** | -La rédaction s'exécute là où le daemon *écrit* ses propres événements — pas là où les batches sont *envoyés*. Donc un prompt ou un argument d'outil contenant une clé API la conserve à l'arrivée. - -C'est délibéré. Ce sont vos propres appels d'instrumentation, et réécrire les événements en transit signifierait que les événements que vous recevez ne sont pas ceux que vous avez émis. +Mettez `collector.redact` à `off` uniquement lorsque des payloads verbatim sont une exigence explicite ; le SDK et le daemon honorent tous les deux ce paramètre. La rédaction minimale attrape les clés d'API courantes, les tokens bearer, les JWT et les affectations de secrets. Elle ne peut pas identifier une prose sensible arbitraire. - **Vous contrôlez les payloads à la source, en deux endroits :** + **Vous contrôlez les payloads à la source, à deux endroits :** - Désactivez la capture de contenu sur l'adaptateur. **Le nom de l'option diffère, et un adaptateur n'en a aucune** — ce n'est pas un interrupteur universel unique : - LangChain / LangGraph, Pydantic AI — `capture_content=False` @@ -665,16 +663,16 @@ C'est délibéré. Ce sont vos propres appels d'instrumentation, et réécrire l - CrewAI — **aucun interrupteur de contenu du tout** ; `session_id` est la seule option qu'il lit, donc les prompts et les complétions sont toujours enregistrés. `instrument()` ignore les options qu'un adaptateur ne lit pas, donc passer le mauvais nom ne lève rien et ne change rien. - - Ne transmettez pas le secret à `input=` en premier lieu. + - Ne donnez pas le secret à `input=` en premier lieu. - `collector.redact` ne remplace ni l'un ni l'autre. + `collector.redact` est une défense en profondeur, pas un substitut à l'un ou l'autre. **Un répertoire spool vide est l'état sain.** Ne l'utilisez pas pour vérifier la livraison. -Le daemon supprime chaque batch dans les millisecondes qui suivent son envoi, donc un `ls` est en concurrence avec le collecteur et ne montre qu'une fraction de ce que vous avez émis — impossible à distinguer d'un SDK qui n'a rien enregistré. +Le daemon supprime chaque lot dans les millisecondes suivant son envoi, donc un `ls` est en compétition avec le collecteur et ne montre qu'une fraction de ce que vous avez émis — impossible à distinguer d'un SDK qui n'a rien enregistré. Pour confirmer que les événements sont bien arrivés, consultez le tableau de bord. Pour observer le remplissage du spool, arrêtez d'abord le daemon. @@ -682,7 +680,7 @@ Pour confirmer que les événements sont bien arrivés, consultez le tableau de -Chaque callback s'exécute dans un wrapper dont le seul rôle est de re-lever les exceptions, votre appel se trouve donc dans exactement un `try` et tout ce que fait le SDK se passe en dehors. +Chaque callback s'exécute dans un wrapper dont le seul rôle est de re-lever, donc votre appel se trouve dans exactement un `try` et tout ce que fait le SDK se passe en dehors. | Ce qui se passe | Résultat | | --- | --- | @@ -692,7 +690,7 @@ Chaque callback s'exécute dans un wrapper dont le seul rôle est de re-lever le | Une version de framework est hors de la plage testée | Avertit une fois, instrumente quand même | | Une seule capacité est manquante | Ce hook est désactivé, jamais l'adaptateur entier | -Le comportement par défaut est correct en production et problématique lors du débogage, car il ne peut que prouver que ça n'a pas planté. Définissez `FAILPROOFAI_SDK_STRICT=1` pour rendre visible un échec avalé. +Le comportement par défaut est correct en production et incorrect lors du débogage, car il ne peut que prouver « ça n'a pas planté ». Définissez `FAILPROOFAI_SDK_STRICT=1` pour rendre bruyant un échec silencieux. @@ -702,23 +700,23 @@ Le comportement par défaut est correct en production et problématique lors du - Un événement d'ouverture n'a pas d'événement de fermeture correspondant : un `model_request` sans `model_response`, ou un `tool_use` sans `tool_result`. Utilisez les portées, qui garantissent la paire même si le corps lève une exception. Si vous appelez les méthodes d'événements directement, utilisez `try` et `finally`. + Un événement d'ouverture n'a pas d'événement de fermeture : un `model_request` sans `model_response`, ou un `tool_use` sans `tool_result`. Utilisez les portées, qui garantissent la paire même lorsque le corps lève une exception. Si vous appelez les méthodes d'événements directement, utilisez `try` et `finally`. - - Il est mesuré depuis l'événement d'ouverture correspondant, il est donc refusé sur `tool_result`, `hook_completed`, `agent_resume` et `human_input`. Il est accepté sur `model_response`, car seul vous connaissez la vraie latence du fournisseur, et il doit être un entier. + + Il est mesuré depuis l'événement d'ouverture correspondant, donc il est refusé sur `tool_result`, `hook_completed`, `agent_resume`, et `human_input`. Il est accepté sur `model_response`, car seul vous connaissez la vraie latence du fournisseur, et il doit être un entier. - - Le thread n'a jamais hérité du contexte. Enveloppez l'appelable dans `failproofai_sdk.propagate()`. Voir [Threads et async](#threads-and-async). + + Le thread n'a jamais hérité du contexte. Enveloppez le callable dans `failproofai_sdk.propagate()`. Voir [Threads et async](#threads-and-async). Les champs supplémentaires sont fusionnés en dernier, donc un champ nommé comme un vrai champ tel que `model` ou `outcome` l'écraserait et modifierait une colonne stockée. Préfixez les vôtres ; les adaptateurs utilisent le préfixe `fw_`. - - `agent_id` est une facette à faible cardinalité et vous y avez mis un id d'exécution. Utilisez un nom de rôle ou de nœud et mettez le vrai id dans un champ de payload. + + `agent_id` est une facette à faible cardinalité et vous y avez mis un identifiant d'exécution. Utilisez un nom de rôle ou de nœud et placez le vrai identifiant dans un champ de payload. @@ -726,7 +724,7 @@ Le comportement par défaut est correct en production et problématique lors du - Paires, ids, cycle de vie des sessions et livraison. + Paires, identifiants, cycle de vie de session et livraison. Suivez la causalité à travers la session que vous venez de capturer. diff --git a/docs/he/start/integrations/custom-agents.mdx b/docs/he/start/integrations/custom-agents.mdx index a7c18715..e58fedde 100644 --- a/docs/he/start/integrations/custom-agents.mdx +++ b/docs/he/start/integrations/custom-agents.mdx @@ -1,13 +1,14 @@ --- -title: "סוכנים מותאמים אישית" -sidebarTitle: "סוכנים מותאמים אישית" -description: "הוסף מעקב לסוכן שכתבת בעצמך, או לפריימוורק ללא מתאם." +--- +title: "סוכנים מותאמים" +sidebarTitle: "סוכנים מותאמים" +description: "כלאו סוכן שכתבת בעצמך, או פריימוורק ללא מתאם." icon: "code" --- -לסוכן שכתבת בעצמך, או לפריימוורק של Failproof AI אין לו מתאם. אין כלום להוסיף: אתה פולט את האירועים. +עבור סוכן שכתבת בעצמך, או פריימוורק שאין ל-Failproof AI מתאם בשבילו. אין שום דבר להכין: אתה פולט את האירועים. -זה אותו API שארבעת מתאמי הפריימוורק קוראים תחתיו. הם טבלאות תרגום עליו. +זו אותה API שמתאמי הפריימוורק הארבעה קוראים בעומק. הם טבלאות תרגום עליה. ## התקנה @@ -15,42 +16,42 @@ icon: "code" pip install failproofai-sdk ``` -ללא תוספים, וללא תלויות. +ללא תוספות, וללא תלויות. -## הוספת מעקב +## הכנה ```python import failproofai_sdk failproofai_sdk.configure(environment="production") -with failproofai_sdk.session(): # הרצה אחת - with failproofai_sdk.agent("planner"): # יחידת עבודה אחת +with failproofai_sdk.session(): # one run + with failproofai_sdk.agent("planner"): # one unit of work with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # קריאת כלי אחת + t.output = search(q) # one tool call ``` -קרא זאת מלמעלה למטה והיא אומרת מה זה אומר: +קרא את זה מלמעלה למטה וזה אומר מה זה אומר: -| עטוף אותו ב | כדי לומר | +| עטוף בו | כדי לומר | | --- | --- | -| `session()` | האירועים הללו שייכים לאותה הרצה | +| `session()` | אירועים אלה שייכים לאותו ריצה | | `agent()` | משהו עושה עבודה — תן לו שם שהיית מזהה ברשימה | -| `tool_call()` | זהו כלי אחד, וזה מה שהוא החזיר | +| `tool_call()` | זה כלי אחד, והנה מה שהוא החזיר | -ומה כל אחד מהם למעשה פולט: +ומה כל אחד בעצם פולט: | טווח | פולט | מטרה | | --- | --- | --- | -| `session()` | כלום | קושר מזהה session, ומקבץ הרצה אחת | -| `agent()` | `agent_start`, `agent_end` | תוחם יחידת עבודה | -| `tool_call()` | `tool_use`, `tool_result` | תוחם כלי אחד ומודד אותו | +| `session()` | כלום | קושר מזהה סשן, קיבוץ ריצה אחת | +| `agent()` | `agent_start`, `agent_end` | מסוגריים יחידת עבודה | +| `tool_call()` | `tool_use`, `tool_result` | מסוגריים כלי אחד ומודד אותו | -הכל בתוך יכול להשמיט `session_id` ו-`agent_id`. הטווחים קושרים זהות על משתנות context ותוך כל קריאת event היא קוראת אותה חזרה, כך שאתה אף פעם לא מחליק מזהים דרך הפונקציות שלך. +הכל בפנים יכול להשמיט את `session_id` ו-`agent_id`. הטווחים קושרים זהות על משתני הקשר וכל קריאת אירוע קוראת אותה בחזרה, אז אתה לעולם לא מעביר ids דרך הפונקציות שלך. -כל השלושה עובדים תחת `async with` כמו גם תחת `with`. +שלושתם עובדים תחת `async with` כמו גם `with`. -קינון סוכנים בונה את העץ. `parent_id` והעמוק מחושבים מהערימה: +קינון סוכנים בונה את העץ. `parent_id` וגובה מחושבים מהערום: ```python with failproofai_sdk.session(): @@ -59,22 +60,22 @@ with failproofai_sdk.session(): ... ``` -## כיצד טווח סוגר +## איך טווח נסגר -`agent()` מטפל בחריגות עבורך: +`agent()` מטפל בחריגים בשבילך: | מה קרה | אירועים | תוצאה | | --- | --- | --- | -| כלום לא הוגבה | `agent_end` | `success` | -| `Exception` | `error`, ואז `agent_end` | `failed` | -| `KeyboardInterrupt`, `SystemExit` | `error`, ואז `agent_end` | `failed` | +| כלום לא הוצא | `agent_end` | `success` | +| `Exception` | `error`, אז `agent_end` | `failed` | +| `KeyboardInterrupt`, `SystemExit` | `error`, אז `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | `agent_end` בלבד | `cancelled` | -השגיאה פלטת לפני `agent_end`, כי הדashboard סוגר את ה-span ב-`agent_end` וכל דבר אחרי זה מיוחס לכלום. ביטול אינו כשל, כך שהרצות מבולות לא מזוהמות על משטח השגיאות. החריגה תמיד מוגבה מחדש: טווח אף פעם לא בולע. +השגיאה מופצת לפני `agent_end`, כי לוח הבקרה סוגר את ה-span ב-`agent_end` וכל דבר אחרי זה מיוחס לכלום. ביטול זה לא כישלון, אז ריצות מבוטלות לא מעלמות את משטח השגיאות. החריג תמיד מועלה מחדש: טווח לעולם לא בולע. ## שיטות האירוע -חמש עשרה שיטות בשש משפחות. רובן מגיעות בזוגות — אתה פולט את הפותח, ואז את הסוגר, והSDK מודד את ה-span ביניהם. +חמש עשרה שיטות בשש משפחות. רובן מגיעים בזוגות — אתה פולט את ה-opener, אז את ה-closer, וה-SDK מודד את ה-span ביניהם. | משפחה | פותח | סוגר | עצמאי | | --- | --- | --- | --- | @@ -82,12 +83,12 @@ with failproofai_sdk.session(): | | `agent_pause` | `agent_resume` | — | | **מודלים** | `model_request` | `model_response` | — | | **כלים** | `tool_use` | `tool_result` | — | -| **וו (Hook)** | `hook_triggered` | `hook_completed` | — | -| **בני אדם** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **Hooks** | `hook_triggered` | `hook_completed` | — | +| **אנשים** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | | **כשלים** | — | — | `error` | - העדף את הטווחים — `agent()` ו-`tool_call()` — בכל מקום שהם מתאימים. הם מבטיחים את אירוע הסיום גם כאשר הגוף מגביל. פנה לשיטות אלה ישירות כאשר זרימת הבקרה שלך לא קינה, כמו קריאה למודל בתוך עוזר. + העדף את הטווחים — `agent()` ו-`tool_call()` — איפה שהם מתאימים. הם מבטיחים את אירוע הסגירה גם כשהגוף מעלה. הגיע לשיטות אלו ישירות כשזרימת הבקרה שלך לא מקוננת, כמו קריאת מודל בתוך עוזר. @@ -119,12 +120,12 @@ failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1", input={"q" failproofai_sdk.event.tool_result(tool_name="search", tool_call_id="c1", output="...") ``` -```python וו +```python Hooks failproofai_sdk.event.hook_triggered(hook_name="retrieve", hook_id="h1", trigger_event="node") failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome="success") ``` -```python בני אדם +```python אנשים failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") @@ -141,23 +142,23 @@ failproofai_sdk.event.error( - **שתי משפחות בני אדם מצביעות בכיוונים מנוגדים.** + **שתי משפחות האנשים מצביעות בכיוונים מנוגדים.** | שיטות | משמעות | | --- | --- | - | `human_wait` / `human_input` | **הסוכן שאל אדם** — שער אישור, שאלה הבהרה | + | `human_wait` / `human_input` | ה**סוכן ביקש מאדם** — שער אישור, שאלה מבהירה | | `human_pause` / `human_interrupt` | **אדם פעל על הסוכן** — כפתור עצור, השהיית מפעיל | - אף פריימוורק לא משדר את הזוג השני, כך שתמיד שלך להפליט. + אף פריימוורק לא משדר את הזוג השני, אז זה תמיד שלך לפליטה. - **עבור `request_id` כאשר קריאות מודל פועלות במקביל.** בלעדיו, בקשות ותגובות מתזווגות בסדר הגעה לכל סוכן — וקריאות מקבילות מתזווגות בצורה שגויה, ומצרפות כל תגובה לבקשה הלא נכונה. + **עבור `request_id` כאשר קריאות מודל פועלות בו-זמנית.** ללא זה, בקשות תגובות מתאימות בסדר הגעה לכל סוכן — וקריאות בו-זמנית מתאימות בצורה שגויה, וקובעות כל תגובה לבקשה השגויה. ## דוגמה -לולאת קריאת כלי כנגד ה-OpenAI API, ללא פריימוורק סוכנים: +לולאת קריאת כלים כנגד ה-OpenAI API, ללא מסגרת סוכן: ```python import json @@ -171,7 +172,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """קריאה מודל אחת, תוחומה בזוג.""" + """One model call, bracketed by the pair.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -204,53 +205,52 @@ with failproofai_sdk.session(): }) ``` -זה מייצר את אותם ששת סוגי אירוע שמתאם היה נותן לך. הגרסה הרצה המלאה, עם הגדרות הכלים, משפנה ב-SDK repository תחת -`docs/manual/examples/`. +זה מייצר אותם שישה סוגי אירוע שמתאם היה נותן לך. הגרסה הריצה המלאה, עם הגדרות הכלים, משלחת ב-SDK ב-`docs/manual/examples/`. -## חוטים ו-async +## Threads ו-async -משתנות context מתפשטות לתוך asyncio tasks באופן אוטומטי. הן לא מתפשטות לתוך חוטים חדשים, כי חוט מתחיל עם context ריק. +משתני הקשר מתפשטים למשימות asyncio באופן אוטומטי. הם לא מתפשטים לחוטים חדשים, כי חוט מתחיל עם קשר ריק. ```python -# asyncio: כלום לא לעשות +# asyncio: nothing to do async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads: עטוף את ה-callable +# threads: wrap the callable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -ללא `propagate()`, אירועי העובד מגבילים `TypeError` ששם את התיקון במקום נחיתה ללא session. זה כוונתי: אירוע ללא session מדולל על ידי ingest וענות `200`, שזה הכשל שקט שלנו שה-identity layer קיים כדי למנוע. +ללא `propagate()`, אירועי העובד מעלים `TypeError` ששם את התיקון ולא נוחתים בשום סשן. זה בכוונה: אירוע ללא סשן מדולג על ידי ingest וענה `200`, שזה כישלון שקט שרמת הזהות קיימת כדי למנוע. -## הוסף מעקב לפריימוורק ללא מתאם +## הכנת פריימוורק ללא מתאם -כל סוכן פריימוורק נותן לך את אותם שלושה seams. מפה אותם ויש לך עקבות מלא — ארבעת המתאמים המספקים לא עושים יותר מזה. +כל מסגרת סוכן נותנת לך אותם שלושה seams. מפה אותם ויש לך עקבות שלם — ארבעת המתאמים המשודרים לא עושים יותר מזה. -| ה-seam | מה שאתה כותב | מה נחיתה | +| ה-seam | מה אתה כותב | מה נוחת | | --- | --- | --- | -| ה-run | `session()` + `agent()` | `agent_start`, `agent_end` | +| הריצה | `session()` + `agent()` | `agent_start`, `agent_end` | | כל כלי | `tool_call()` | `tool_use`, `tool_result` | | כל קריאת מודל | הזוג `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - בכל מה שהפריימוורק קורא tool wrapper או middleware. + + בכל מה שהפריימוורק קורא עטיפת כלי או middleware. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -265,31 +265,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **יש node, step או middleware boundary שחייב להיות נראה?** עטוף אותו בזוג hook — `hook_triggered` / `hook_completed` — לא nested `agent()`. `agent_id` הוא facet low-cardinality, והערך אחד לכל node טובע אותו. Hook spans מתרנדרים בדרך זהה וגם נותנים לך לטנציה לכל node. + **יש לך צומת, שלב או גבול middleware שכדאי לראות?** עטוף אותו בזוג hook — `hook_triggered` / `hook_completed` — לא `agent()` מקונן. `agent_id` הוא facet בעל עוצמה נמוכה, וערך אחד לכל צומת טובע אותו. span hook משדרו באותו אופן ונותן לך אותך-צומת latency. - **ידני והאוטומטי מרכיבים.** מתאם שנמצא בתוך scope כתוב ביד מצטרף לשיוך זה ומוריש לסוכן זה, כך שאתה מקבל עץ אחד ולא שניים — שימושי כאשר אתה מעביר מסגרת אחת בעצמך לצד אחד בעל תמיכה. + **ידני ואוטומטי מרכיבים.** מתאם הפועל בתוך טווח כתוב בעצמך מצטרף לסשן זה ו-parents לסוכן זה, אז אתה מקבל עץ אחד במקום שניים — שימושי כאשר אתה מכין פריימוורק אחד בעצמך לצד אחד נתמך. - שתי סיבות, והשלושת ה-seams למעלה הן התשובה לשניהם: + שתי סיבות, ושלושת ה-seams לעיל הם התשובה לשתיהן: - - `autogen-core` לא תופסת תחזוקה מ-September 2025. - - AG2 לא חושף נקודת רישום כללית תהליך שווה ערך למשדרים של פריימוורקים אחרים, כך שהוספת מעקב אומר עטיפת כל סוכן בכל אתר בנייה. + - `autogen-core` היה לא תחזוקה מאז ספטמבר 2025. + - AG2 לא חושף נקודת רישום בהיקף תהליך שקולה לה של הפריימוורקים האחרים' hooks, אז הכנה זה אומר עטיפת כל סוכן בכל אתר בנייה. - מיפוי ה-seams ביד רושם את אותם אירועים, בדיוק זהה, שמתאם משודר היה עושה. + מיפוי ה-seams ביד רושמות את אותם אירועים, באותה נאמנות, כמו מתאם משודר היה. -## עומק יותר +## הלוך עמוק יותר -איך ההקלטה למעשה עובדת. כלום מזה לא נחוץ כדי להתחיל. +איך ההקלטה בעצם עובדת. כלום לא הכרחי כדי להתחיל. -לכל הקלטה אותו צורה: span נפתח, עבודה קינה בתוכו, ולכל אירוע פותח יש אירוע סוגר אחד. +לכל הקלטה יש אותה צורה: span נפתח, עבודה מקוננת בתוכה, וכל אירוע פתיחה מקבל אירוע סגירה. ```mermaid flowchart LR @@ -301,9 +301,9 @@ flowchart LR C --> E(["agent_end"]) ``` -ה**זוג** הוא היחידה. כל אירוע סוגר נושא משך זמן SDK מודד מה-opening שלו. +ה**זוג** הוא היחידה. כל אירוע סגירה נושא משך הזמן שה-SDK מודד מהפתיחה שלו. -להלן הרצה אמיתית אחת לכל פריימוורק — תפוסה מהדוגמאות שנמצאות עם ה-SDK, שם מודל מנורמל. שים לב כמה חוזר מקריאה יחידה. +להלן ריצה אמיתית אחת לכל פריימוורק — תפוסה מהדוגמאות המשלחות עם ה-SDK, שם מודל מנורמל. שימו לב כמה חוזר מקריאה אחת. @@ -324,7 +324,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - Nodes הופכים לזוגות hook, כך שאתה מקבל לטנציה לכל node ללא טביעת הרשימה סוכנים. + צמתים הופכים לזוגות hook, אז אתה מקבל per-node latency ללא שהם חונקים את רשימת הסוכן. @@ -341,7 +341,7 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - `role` של כל סוכן הופך לשם ה-span שלו, כך שלטנציה ו-token spend מתפרקים לפי תפקיד. + כל `role` של סוכן הופך לשם span שלו, אז latency וtoken spend שבור למטה per role. @@ -361,7 +361,7 @@ flowchart LR 26 +7.038s agent_end Agent · success ``` - לולאת סוכן עצמה נראית, לא רק קריאות המודל שלו. + לולאת הסוכן עצמה גלויה, לא רק קריאות הדגם שלה. @@ -376,10 +376,10 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - אין זוגות hook: ל-Pydantic AI אין node או step boundary לתחום. + אין זוגות hook: Pydantic AI אין לא צומת או גבול שלב לסוגר. - + ```text 6 events 1 +0.000s agent_start main 2 +0.000s tool_use population @@ -389,36 +389,36 @@ flowchart LR 6 +0.000s agent_end main · success ``` - אתה פולט אלה בעצמך. אותם סוגי אירוע, דיוק זהה — זה עולה לך לאתרי קריאה. + אתה פולט אלה בעצמך. אותם סוגי אירוע, אותה נאמנות — זה עולה אתה את אתרי הקריאה. - + -**אין אירוע session-end.** session אינה משהו שאתה סוגר — היא קבוצה של אירועים השיתוף `session_id`. +**אין אירוע session-end.** סשן זה לא משהו אתה סוגר — זה קבוצה של אירועים המשתפים `session_id`. -סטטוס נגזר מצורת העקבות: +סטטוס מגוזר מצורת העקבות: | סטטוס | מתי | | --- | --- | | `ongoing` | לפחות span אחד עדיין פתוח | -| `paused` | `agent_pause` אין לו matching `agent_resume` | -| `error` | כלום לא פתוח, ולפחות אירוע אחד נכשל | +| `paused` | `agent_pause` אין שום matching `agent_resume` | +| `error` | כלום לא פתוח, וולפחות אירוע אחד נכשל | | `done` | כלום לא פתוח, וכלום לא נכשל | -כך שsession מסתיים כאשר כל זוג סוגר. המתאמים פולטים `agent_end` עבורך, והם סוגרים כל דבר עדיין פתוח ומסימנים אותו לא שלם — הרצה קרוסה מתפזרת כ-`done` עם פער גלוי במקום תלויה לנצח. +אז סשן מסתיים כאשר כל זוג סגור. המתאמים פולטים `agent_end` בשבילך, וב-teardown הם סוגרים כל דבר עדיין פתוח ומסמנים אותו לא שלם — ריצה שהתרסקה מסתדרת כ-`done` עם פער גלוי במקום תלוי לנצח. - זה למה session יכול להקיף שתי קריאות. LangGraph `interrupt()` השהה את ה-run, ה-root span בכוונה נשאר פתוח, והקריאה הממשיכה סוגרת אותה. שתי הקריאות הן session אחד. + זו הסיבה שסשן יכול להשתרע על שתי קריאות. `interrupt()` LangGraph מעצור את הריצה, ה-root span נשאר בכוונה פתוח, וקריאת השחזור סוגרת אותה. שתי הקריאות הן סשן אחד. - + -`session_id` ו-`agent_id` הם אופציונליים בכל שיטת event. בהשמטה, הם מתפזרים מהטווח שוקע: +`session_id` ו-`agent_id` אופציונליים בכל שיטת אירוע. השמיט, הם פותרים מה-scoping: ```python with failproofai_sdk.session(): @@ -426,139 +426,139 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -העברתם בגלוי עדיין עובדת ולוקחת עדיפות. ללא כלום קשור וכלום עברר, הקריאה מגבילה `TypeError` שם את התיקון במקום הפקת אירוע ללא session, אשר ingest היה דלל תוך התשובה `200`. +העברתם בצורה מפורשת עדיין עובדת ותקיחה עדיפות. עם כלום קשור וכלום עבר, הקריאה מעלה `TypeError` ששם את התיקון במקום פליטת אירוע עם לא סשן, וזה ingest היה דילוג עד בעת ענוה `200`. -טווחים קושרים זהות על משתנות context. אלה מתפשטות לתוך asyncio tasks באופן אוטומטי אך לא לתוך חוטים חדשים — עטוף עובד ב-`failproofai_sdk.propagate()`. +Scopes קשרים זהות על משתני הקשר. אלה מתפשטים למשימות asyncio באופן אוטומטי אך לא לחוטים חדשים — עטוף עובד ב-`failproofai_sdk.propagate()`. -#### מי חושב איזה id +#### מי טביע איזה id -| Id | חשוב על ידי | הערות | +| Id | טבוע על ידי | הערות | | --- | --- | --- | -| `session_id` | אתה, או ה-SDK | `session("chat-42")` משמש verbatim; בהשמטה, SDK מייצר `uuid4().hex` | -| `agent_id` | אתה, או הפריימוורק | מ-`agent("analyst")`, CrewAI `role`, `FunctionAgent.name`. ערך דומה UUID נדחה והחלפה | -| `tool_call_id`, `hook_id`, `request_id` | אתה, או הפריימוורק | מתאמים מחדשים שימוש ב-framework's שלהם run ids, שזה למה זוגות שורדים thread hops | -| **Event id** | **Cloud, ב-ingest** | ה-SDK לא פולט | -| **`dedup_key`** | **Cloud, ב-ingest** | hash של org, session, timestamp, type ו-payload. זאת הזהות האמיתית — היא גורמת batch שנו נסכל בקריסה במקום כפול | +| `session_id` | אתה, או ה-SDK | `session("chat-42")` משמש verbatim; השמיט, ה-SDK מייצר `uuid4().hex` | +| `agent_id` | אתה, או הפריימוורק | מ-`agent("analyst")`, CrewAI `role`, `FunctionAgent.name`. ערך הנראה כ-UUID מוחזק וקבע | +| `tool_call_id`, `hook_id`, `request_id` | אתה, או הפריימוורק | מתאמים עוד שוב להשתמש בה-framework שלה עוד ids, וזו למה זוגות עמוד חוט הקפצות | +| **אירוע id** | **ענן, ב-ingest** | ה-SDK פולט כלום | +| **`dedup_key`** | **ענן, ב-ingest** | גיבוב של ארגון, סשן, timestamp, סוג וחומלת עומס. זו הזהות האמיתית — זה עושה נסיון מחדש batch כמצטבר בקריסה במקום שכפול | -#### איך מתאמים מתפזרים `session_id` +#### איך מתאמים פותרים `session_id` -תאימה ראשונה זוכה: +משחק ראשון זוכה: -1. ערך `session_id` מפורש -2. metadata לכל קריאה -3. טווח `session()` שוקע -4. framework metadata -5. framework's שלהם run id +1. `session_id` בגלוי אפשרות +2. לכל קריאה מטא-נתונים +3. ה-enclosing `session()` scope +4. מטא-נתונים פריימוורק +5. ה-framework שלה עוד id ריצה -זה אף פעם לא המצוי בזמן אחד מאלה קיים — id סינתטי היה מפלג הרצה אחת על פני מספר sessions. +זו לעולם לא המצאה בזמן שאחת מאלה קיימת — id סינתטי היה לחלק ריצה אחת על פני מספר סשנים. #### שמור `agent_id` low cardinality -זה ה-facet ראשי בכל משטח dashboard, ו-`LowCardinality(String)` כולונה. ערך לכל run מורידה את הכולונה ומלאה את ה-filter dropdown בערך אחד לכל run. +זו פן ראשי על כל משטח לוח בקרה, וא `LowCardinality(String)` עמודה. ערך לכל ריצה מדרדר העמודה ומלא את dropdown המסנן עם ערך אחד לכל ריצה. -מתאמים בטחון כולונה זו עבורך: +מתאמים שומרים על העמודה בשבילך: -| הפריימוורק מוביל על | הוקלט כ | למה | +| הפריימוורק מסר | רשום כ | למה | | --- | --- | --- | -| `3f9a1c2b-…` (UUID) | `main` | כלום קריא לשמור | -| hex ארוך חשוף string | `main` | זהה | -| `agent-3f9a1c2b-…` | `agent` | לכל run id חשוף, ible part שמור | -| `agent-v2` | `agent-v2` | קטגוריה קצרה משומרת | +| `3f9a1c2b-…` (UUID) | `main` | כלום קריא להחזיק | +| מחרוזת hex ארוכה חשופה | `main` | זהה | +| `agent-3f9a1c2b-…` | `agent` | לכל ריצה id קורוע, חלק קריא שמור | +| `agent-v2` | `agent-v2` | מקטעים קצרים נותרו לבדם | | `step-3` | `step-3` | זהה | -ה-ID האמיתי שמור ב-`fw_agent_id` / `fw_run_id`, איפה זה נשאר queryable ללא להיות facet. +ה-id האמיתי נשמר ב-`fw_agent_id` / `fw_run_id`, איפה זה נשאר queried ללא להיות facet. - **שמירה זו רק נוגעת בתוויות **הפריימוורק** בחר.** `agent_id` אתה עבור עצמך — ל-`event.*`, או ל-`failproofai_sdk.agent(...)` — הוקלט בדיוק כנתון. שמאלה כתוב argument מפורש היה גרוע יותר מה-cardinality זה מנע, כך שקרא את הspan שלך בהתאם. + **הגן זה רק נוגע תוויות ה-*framework* בחר.** `agent_id` אתה עובר בעצמך — ל-`event.*`, או `failproofai_sdk.agent(...)` — רשום בדיוק כפי שניתן. שקט כתיבה מחדש של טיעון מפורש היה גרוע יותר מ-cardinality זה מונע, אז שם שלך משל עצמך ספאנס בהתאם. - + | קבוצה | אירועים | | --- | --- | | סוכנים | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | | מודלים | `model_request`, `model_response` | | כלים | `tool_use`, `tool_result` | -| וו | `hook_triggered`, `hook_completed` | -| בני אדם | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| Hooks | `hook_triggered`, `hook_completed` | +| אנשים | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | כשלים | `error` | -איזה פריימוורק רושם מה, נמדד מה-runs למעלה: +איזה מסגרת רושמת מה, נמדד מהריצות למעלה: -| אירוע | LangGraph | CrewAI | LlamaIndex | Pydantic AI | מותאם אישית | +| אירוע | LangGraph | CrewAI | LlamaIndex | Pydantic AI | מותאם | | --- | :--: | :--: | :--: | :--: | :--: | -| תחילת וסוף סוכן | כן | כן | כן | כן | אתה | +| התחלה ולסוף סוכן | כן | כן | כן | כן | אתה | | בקשת מודל ותגובה | כן | כן | כן | כן | אתה | -| שימוש בכלי ותוצאה | כן | כן | כן | כן | אתה | -| וו מתוגבר וסיום | Node | משימה | Step | — | אתה | +| שימוש בכלים ותוצאה | כן | כן | כן | כן | אתה | +| Hook triggered וsupplied | צומת | משימה | שלב | — | אתה | | שגיאה | כן | כן | כן | כן | אוטומטי | -| חכיית אדם וקלט | כן | כן | כן | — | אתה | -| השהיית סוכן וחידוש | כן | כן | כן | — | אתה | +| האדם מחכה ויזמה | כן | כן | כן | — | אתה | +| סוכן עצור וחזור | כן | כן | כן | — | אתה | -dash פירושו הפריימוורק אין לו כזה קונספט. `human_pause` ו-`human_interrupt` תארו **אדם** פועל על סוכן, אשר אף פריימוורק משדר — הפלוט אלה בעצמך. +מקף אומר לפריימוורק אין מושג כזה. `human_pause` ו-`human_interrupt` תאר *אדם* פעל על הסוכן, וזה אף פריימוורק משדר — פלט אלה בעצמך. - + -אירוע אף פעם לא מגיע בודד. אחד פותח span, אחד סוגר אותו, ואירוע הסיום נוצא משך זמן SDK מודד מה-opening. +אירוע לעולם לא מגיע לבדו. אחד פותח span, אחד סוגר אותה, ואירוע הסגירה נושא משך הזמן שה-SDK מודד מהפתיחה. -| פותח | סוגר | אירוע הסיום נוצא | +| פותח | סוגר | אירוע הסגירה נושא | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | | `model_request` | `model_response` | tokens, `stop_reason`, latency | -| `tool_use` | `tool_result` | `output` או `error`, duration | -| `hook_triggered` | `hook_completed` | `outcome`, duration | +| `tool_use` | `tool_result` | `output` או `error`, משך | +| `hook_triggered` | `hook_completed` | `outcome`, משך | | `agent_pause` | `agent_resume` | כמה זמן ההשהיה נמשכה | | `human_wait` | `human_input` | התשובה, וכמה זמן האדם לקח | - אירוע פותח ללא סוגר אחד הוא span שלא סיים. השיוך מתרנדר כעדיין פעיל, לנצח, וה-active duration שלו ממשיך לגדול. זה כשל mode לצפות בו כאשר אתה מוסיף מעקב ביד. + אירוע פתיחה ללא סגירה הוא span שלעולם לא מסתיים. הסשן משדר כעדיין פועל, לנצח, ומשך הזמן הפעיל שלו ממשיך לגדול. זה מצב הכשל לצפות כאשר אתה מכין ביד. -#### כללי קורלציה +#### כללי מתאם -- חזור על אותו `tool_call_id`, `hook_id`, `pause_id`, או `input_id` לאירוע השלמה תואם. -- SDK מחשבות `duration_ms` לכל `tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. עברור אותו הודעות raises `ValueError`. -- `duration_ms` **הוא** קבול ב-`model_response`, כי רק ה-caller יודע ה-real provider latency. זה חייב להיות integer — float raises `ValueError` בקריאה site, כי השרת קורא את הכולונה כ-unsigned 32-bit integer וחנה NULL לכל דבר אחר. -- מפתחות קורלציה בטוח לפי סוג וsession, אז tool call ו-hook עשוי בטוח שיתוף id, וsessions מקבילות שני חזור על אותם ids ללא התנגשות. הם לא בטוח על ידי סוכן: זוג פתוח תחת סוכן אחד וסגור תחת אחר עדיין קורלציה, שהיא המקרה הרגיל במסגרות רב סוכנים. -- `request_id` זוגות `model_request` עם `model_response`. ללא אותו, אירועי מודל זוג בסדר לכל סוכן, כך קריאות מקבילות mispair. -- זוג פיצול על פני processes עדיין קורלציה downstream, אך SDK לא יכול לחשב in-process duration. -- מפת pending מחזיקה לכל היותר 10,000 starts ו-evicts ערך עתיק כאשר מלא. +- עוד שוב את אותו `tool_call_id`, `hook_id`, `pause_id`, או `input_id` לאירוע ההשלמה התואם. +- ה-SDK מחשב `duration_ms` ל-`tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. עברת אותו לשיטות אלו מעלה `ValueError`. +- `duration_ms` **כן** מקבל ב-`model_response`, כי רק הקורא יודע את latency ספק אמיתי. זה חייב להיות מספר שלם — float מעלה `ValueError` ב-אתר הקריאה, כי השרת קורא את העמודה כמספר שלם לא חתום ב-32 ביט וישמור NULL לכל אחר. +- מפתחות מתאם מתוחמים לפי סוג וסשן, אז כלי קוראה וחוק עשויים בבטחה לשתף id, וששתי סשנים בו-זמנים עשויים לעשות שימוש חוזר באותו ids ללא התנגשות. הם לא מתוחמים על ידי סוכן: זוג פתוח תחת סוכן אחד וסגור תחת שנייה עדיין מתאמים, שזה המקרה הרגיל במסגרות סוכן רבות. +- `request_id` זוגות `model_request` עם `model_response`. ללא זה, אירועי מודל זוגות בסדר לכל סוכן, אז קריאות בו-זמנים מתאימות בצורה שגויה. +- זוג לחלוקה על פני תהליכים עדיין מתאמים downstream, אך ה-SDK לא יכול לחשב משך הזמן בתוך הפרוסס שלה. +- המפה התלויה אחזיקה בסך הכל 10,000 התחלות ומסיקות את הערך הישן ביותר כאשר מלא. - + -התקנת `failproofai-sdk` מתקנת הכל, כל ארבעת המתאמים כלול. ה-extras משדרים את **הפריימוורק**, לא את המתאם. +הקנו `failproofai-sdk` מקנה את הכל, את כל ארבעת המתאמים כלול. התוספות משכו את **פריימוורק**, לא את המתאם. ```python -import failproofai_sdk # עומס כלום חוץ מה-standard library -failproofai_sdk.instrument() # ייבוא רק המתאמים אתה בעצם צריך +import failproofai_sdk # loads nothing outside the standard library +failproofai_sdk.instrument() # imports only the adapters you actually need ``` -`import failproofai_sdk` הוא חוזה אפס תלויות, אינפורמציה על ידי בדיקה שמתקנת את הגלגלון עם `--no-deps` ועוד שמוכיח אף פריימוורק מגיע ל-`sys.modules`. +`import failproofai_sdk` הוא חוזה אפס-תלוי, אנוף על ידי בדיקה המקנה את הגלגל הבנוי עם `--no-deps` ואחר שמוכיח שאין פריימוורק מגיע ל-`sys.modules`. - אין `failproofai_sdk.crewai` תכונה. מתאמים בכוונת לא חשוף על הפרה עליונה חבילה: לוגע אחד היה ייבוא הפריימוורק כ-side effect של גישה תכונה, שבירת אפס תלויות הבטחה. השתמש `instrument()`. + אין `failproofai_sdk.crewai` תכונה. המתאמים בכוונה לא חשופים על חבילה ברמה עליונה: מגע של אחד היה לייבא את הפריימוורק כתופעת לוואי של גישה תכונה, שבור בחוזה אפס-תלוי. השתמש ב-`instrument()`. ```python -failproofai_sdk.instrument() # כל פריימוורק כבר ייובא -failproofai_sdk.instrument("crewai") # בדיוק אחד, לפי שם -failproofai_sdk.uninstrument("crewai") # שים חזרה +failproofai_sdk.instrument() # every framework already imported +failproofai_sdk.instrument("crewai") # exactly one, by name +failproofai_sdk.uninstrument("crewai") # put it back ``` -| שם | גם קבול | +| שם | אף קבל | | --- | --- | | `langchain` | `langgraph`, `langchain_core` | | `crewai` | — | | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -גילוי אוטומטי קורא `sys.modules`, לא את רשימת חבילה מותקנת, אז פריימוורק שיש לך מותקן אבל אף פעם לא ייבוא הוא לא מוכן והוא אף פעם לא ייובא בשמך. להראות מה חווט למעלה: +גילוי אוטו קורא `sys.modules`, לא את חבילה מותקנת רשימה, אז פריימוורק שיש לך מותקן אך לעולם לא יובא לא מכונו וישעדם לעולם לא יובא על בעד שלך. לראות מה חיווט עד: ```python from failproofai_sdk.integrations import active, available @@ -568,132 +568,130 @@ active() # ('langchain',) ``` - **`instrument("crewai")` על מכונה ללא CrewAI לא מגביל.** זה עוקב אזהרה ו-return `()`, אז פריימוורק חמיץ אף פעם לוקח תהליך שגם מהמרות אחרים. + **`instrument("crewai")` על מכונה ללא CrewAI לא מעלה.** זה עליו קריאה וחזרות `()`, כך אחד פריימוורק חסר לעולם לא קח למטה תהליך גם כן מכין אחרים. - האזהרה נוצא ה-`ImportError` בקדמה, וזה הודעה שם את פקודת התקנה מדויקת — כך התיקון בלוגים שלך, לא מוסתר. + התרעה נושא בו `ImportError`, והודעה זו שם קומנדה התקנה בדיוק — אז תיקון ב-יומנים שלך, לא מוסתר. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - ערכה `FAILPROOFAI_SDK_STRICT=1` כדי יש לו מגביל במקום. זה דגל קורא **פעם אחת ו-cached**, אז ייצוא זה לפני התהליך מתחיל במקום קביעה mid-run. + קבע `FAILPROOFAI_SDK_STRICT=1` כדי היה זה מעלה במקום. דגל זה קורא **פעם וcached**, אז יצוא זה לפני הפרוסס שלך מתחיל במקום הגדרה בתוך ריצה. - **`instrument()` חייב לבוא **אחרי** ייבוא הפריימוורק שלך.** גילוי אוטומטי קורא `sys.modules`, אז קריאה ערומה מעל הייבוא מוצא כלום, מתקן כלום, וחוזר `()`. + **`instrument()` חייב לבוא *לאחר* הייבא פריימוורק שלך.** גילוי אוטו קורא `sys.modules`, אז קריאה חשופה מעל הייבא מוצא כלום, מקנה כלום, וחזרות `()`. -```python שגוי +```python Wrong import failproofai_sdk -failproofai_sdk.instrument() # sys.modules אין langchain עדיין -> () +failproofai_sdk.instrument() # sys.modules has no langchain yet -> () -import langchain # מאוחר מדי, כלום לא חווט +import langchain # too late, nothing is wired ``` -```python נכון -import langchain # ייבוא הפריימוורק ראשון +```python Right +import langchain # import the framework first import failproofai_sdk -failproofai_sdk.instrument() # מוצא זה -> ('langchain',) +failproofai_sdk.instrument() # finds it -> ('langchain',) ``` -```python נכון, order-proof +```python Right, order-proof import failproofai_sdk -# שם זה ייבוא את המתאם על בקשה, אז זה עובד מכל מקום. +# Naming it imports the adapter on request, so this works from anywhere. failproofai_sdk.instrument("langchain") ``` -קבל את זה שגוי והתהליך פועל עם ה-SDK ייובא, המתאם לכאורה מותקן, ו**לא אירוע אחד פלט**. זה עוקב אזהרה אומר בדיוק זה — אז בדוק לוגים ראשון כאשר run רושם כלום. +קבל זה לא ישר ותהליך פועל עם ה-SDK יובא, המתאם לכאורה מותקן, ו**לא אירוע אחד פלט**. זה עליו קריאה התרעה שכוללת בדיוק זה — אז בדוק יומנים שלך ראשון כאשר ריצה רושמת כלום. - + ```mermaid flowchart LR - A["הסוכן שלך"] --> B["מתאם"] - B --> C["כותב
תור בזיכרון"] - C -->|"כל 0.5s"| D["Spool
JSONL בדיסק"] + A["Your agent"] --> B["Adapter"] + B --> C["Writer
in-memory queue"] + C -->|"every 0.5s"| D["Spool
JSONL on disk"] D --> E["Failproof daemon"] E -->|"HTTPS"| F["Cloud"] ``` -| שלב | משימה | פועל בתוך | +| בימה | עבודה | רץ ב | | --- | --- | --- | -| מתאם | תרגם callback פריימוורק לתוך אחד מ-15 סוגי אירוע | התהליך שלך | -| כותב | תור, אצווה, כתיבה JSONL אטומית | התהליך שלך, חוט רקע | -| Spool | Durable handoff, שורד התהליך יציאה | דיסק מקומי | -| Daemon | שומר spool, משלח אצוות, מוחק מה-shipped | המכונה שלך | -| Ingest | מקצה שורה id ו-dedup key, מקדם שאלה כולוניות | Cloud | +| מתאם | תרגום קלט פריימוורק לאחד מ-15 סוגי אירוע | הפרוסס שלך | +| כותב | קיוו, אצווה, כתוב JSONL אטומית | הפרוסס שלך, חוט רקע | +| סקול | מעביר עמיד, שורד הפרוסס שלך יוצא | דיסק מקומי | +| דיימון | שמור סקול, ספינה אצווה, מחק מה ספינה | מכונה שלך | +| Ingest | הקצה שורה id וdedup מפתח, טלל queried עמודות | ענן | -ה-spool הוא מה עושה זה בטוח: סוכן שלך אף פעם לא חסום על הרשת, וCloud outage אומר ספריה גדלה במקום קביעה אירועים. +ה-spool הוא מה עושה זה בטח: הסוכן שלך לעולם לא חסום ברשת, והפרה ענן אומר ספרייה גדלה במקום אבוד אירועים. -כל flush כתוב קובץ אצווה אחד, `.tmp` ראשון, ואז `fsync`, ואז atomic rename: +כל שטוף כותב אחד אצווה קובץ, `.tmp` ראשון, אז `fsync`, אז שינוי אטומית: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -ה-daemon רק עוזב `.jsonl`, אז זה לא יכול אף פעם קרא חצי כתוב קובץ. הגזע נוצא timestamp, process id וסדר מספר, אז שני תהליכים flush בה-millisecond לא יכול להתנגש. התור כובל בחסום 10,000 אירועים; העבר זה זה טיפל הוקדם וrelog. +הדיימון רק כריע `.jsonl`, אז זה יכול לעולם קרא חצי-כתוב קובץ. ה-stem נושא timestamp, פרוסס id ומספר רצף, אז שני תהליכים שטוף באותה מילישנייה לא יכולה התנגשות. הקיוו מכוסה ב-10,000 אירועים; עבר זה זה משחזר הישן וגב. - **`collector.redact` עושה לא חל ל-SDK אירועים שלך.** זה אף פעם לא רואה אותם. + **`collector.redact` ברירות ל-`minimal` ל-SDK אירועים גם כן.** ה-SDK מנקה לפני כתיבה אצווה לדיסק, והדיימון חזר מעל אותו דטרמיניסטי לפני העלאה אז אצווה מה SDK ישן מוגן. -ה-daemon **משלח** אצוות שלך. זה לא פתוח או לשכתב אותם. +הדיימון קורא כל אצווה וחל redaction בזיכרון לפני העלאה. זה לא כתיבה מחדש הדיסק קובץ זה קרא. -| אירועים | כתוב על ידי | Redacted על ידי `collector.redact`? | +| אירועים | כתוב על ידי | איפה redaction minimal רץ | | --- | --- | --- | -| CLI session תחקירי | Daemon | כן | -| וו פעילות | Daemon | כן | -| **הכל ה-SDK פלט** | **התהליך שלך** | **לא** | - -Redaction פועל איפה ה-daemon **כתוב** שלהם אירועים — לא איפה אצוות **משודרים**. כך prompt או tool argument מחזיק API key עדיין מחזיק זה בהגעה. +| עדכני סשן CLב | הדיימון | לפני הדיימון כתיבה האצווה | +| Hook פעילות | הדיימון | לפני הדיימון כתיבה האצווה | +| **הכל ה-SDK פולט** | **הפרוסס שלך** | **לפני ה-SDK כותב האצווה ושוב לפני daemon ההעלאה** | -זה כוונתי. אלה בעצמך מעקב קריאות, וכתיבה מחדש בטרנזיט יומר את אירועים אתה קבל הם לא אירועים אתה פלט. +קבע `collector.redact` ל-`off` רק כאשר verbatim מטענים הוא תבחין מפורש; ה-SDK וdaemon שניהם כבדו הגדרה. redaction minimal תופס API מנוצל, bearer אסימונים, JWTs, וסוד מטימות. זה לא יכול מייצר שרירות רגישות שרירותיות. - **אתה שלוט בפעילויות ב-source, בשני מקומות:** + **אתה שלוט מטענים ב-מקור, ב-שתי מקומות:** - - כבה לכידת תוכן על המתאם. **שם אפשרות שונה, ומתאם אחד אין אחד** — זה לא אחד כללי אוניברסלי מתג: + - תור עוד תכן תופס ב-מתאם. **שם האפשרות שונה, ואחד מתאם אין כלום** — זה לא בחירה אוניברסלית יחידה: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **אין מתג תוכן בכל**; `session_id` היא רק אפשרות שהיא קורא, אז prompts ו-completions תמיד רשום. + - CrewAI — **אין תור תכן לכל**; `session_id` הוא רק אפשרות זה קורא, אז prompts השלמות תמיד רשום. - `instrument()` טיול אפשרויות מתאם לא קורא, אז עברור שם שגוי מגביל כלום ושינויים כלום. - - אל תעביר את הסוד ל-`input=` בראשון מקום. + `instrument()` טיל אפשרויות מתאם לא קורא, אז עברת שם שגוי מעלה כלום ושינויים כלום. + - אל תיד הסוד ל-`input=` ב-ראשון מקום. - `collector.redact` הוא לא תחליף לאף אחד מאלה. + `collector.redact` הוא הגנה בעומק, לא תחליף לכל אחד. - **ספריה spool ריקה היא המדינה הבריאה.** אל תשתמש בזה כדי בדוק משלוח. + **ספרייה סקול ריק הוא המצב בריא.** אל להשתמש זה לתברואה חלוקה. -ה-daemon מוחק כל אצווה בתוך milliseconds משליחה, אז `ls` מרוצים collector וש fraction של מה אתה פלט — לא ניתנת להבחנה מ-SDK ש קיבוץ כלום. +הדיימון מחק כל אצווה בתוך מילישנייה ספינה, אז `ls` מרוץ הקולקטור ותגיד שבר מה כוללים — בהבחנה מ-SDK שרשום כלום. -לאשר אירועים באמת נחתו, בדוק את ה-dashboard. לצפות ה-spool תמלא, עצור את ה-daemon ראשון. +כדי לעזוב אירועים בעצם נחתו, בדוק לוח בקרה. לצפות הסקול למטלאות, עצור דיימון ראשון. - + -כל callback פועל בתוך wrapper שלה יחידה משימה היא להגביל מחדש, אז קריאה שלך יושבת בדיוק אחד `try` והכל SDK עושה קורה מחוץ אותה. +כל קלט רץ בתוך עטיפה שעבודה היחידה הוא להעלות מחדש, אז הקריאה שלך יושבת בדיוק אחד `try` וכול דבר ה-SDK עושה קורה חוץ זה. -| מה קורה | תוצאה | +| מה קרה | תוצאה | | --- | --- | -| hook מגביל | עיתון פעם עם traceback. קריאה שלך לא השפעה | -| אותו hook מגביל שלוש פעמים | זה hook אחד משוביץ לנו התהליך, עם שורה טעות אחד | -| `FAILPROOFAI_SDK_STRICT=1` הוא קביעה | החריגה הוא re-raised במקום | -| פריימוורק גרסה חוץ בדוקו טווח | הזהרות פעם, מהמרות בכל זאת | -| יחיד יכולת היא חמיץ | זה חוק אחד משוביץ, אף פעם כל מתאם | +| חוק מעלה | רשום כפעם עם traceback שלה. הקריאה שלך לא מושפעת | +| אותו חוק מעלה שלוש פעמים | זה חוק אחד מנוטרל שאר הפרוסס, עם קו שגיאה אחד | +| `FAILPROOFAI_SDK_STRICT=1` קבע | החריג מוגבה במקום | +| פריימוורק גרסה מחוץ לטווח בדוק | קוראים פעם, מכין בכל זאת | +| יכול אחד חסר | זה חוק אחד מנוטרל, לעולם לא מתאם מלא | -ה-default הוא ימין בייצור וחצי בזמן debug, כי זה יכול רק אי פעם הוכח אתה לא קרס. קביעה `FAILPROOFAI_SDK_STRICT=1` לעשות בוליט כשל קול. +ברירת זה כון בייצור ולא בזמן ירא, כי זה יכול רק לעולם הוכיח טו לא קרס. קבע `FAILPROOFAI_SDK_STRICT=1` כדי עשה כישלון בולע רועם. @@ -702,24 +700,24 @@ Redaction פועל איפה ה-daemon **כתוב** שלהם אירועים — ## בעיות נפוצות - - אירוע פותח אין אחד סוגר: `model_request` ללא `model_response`, או `tool_use` ללא `tool_result`. השתמש הטווחים, אשר ערובה הזוג אפילו כאשר הגוף מגביל. אם אתה קורא את שיטות האירוע ישירות, השתמש `try` ו-`finally`. + + אירוע פתיחה אין סגירה: `model_request` עם לא `model_response`, או `tool_use` עם לא `tool_result`. השתמש הטווחים, גם ערבות הזוג כאשר גוף מעלה. אם קריאה יוש שיטות אירוע, השתמש `try` ו-`finally`. - - זה נמדד מה-opening תואם אירוע, אז זה דחוי ב-`tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. זה קבול ב-`model_response`, כי רק אתה יודע ה-real provider latency, וזה חייב להיות integer. + + זה מודד מה אירוע פתיחה מתאם, אז זה דחה ב-`tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. זה קבול ב-`model_response`, כי רק אתה דע ספק אמיתי latency, וחייב להיות מספר שלם. - - החוט לא אף פעם inherited ה-context. עטוף את ה-callable ב-`failproofai_sdk.propagate()`. ראה [חוטים ו-async](#threads-and-async). + + החוט לא עדיין ירש הקשר. עטוף הקריא ב-`failproofai_sdk.propagate()`. עיין [Threads וasync](#threads-and-async). - - שדות תוספת מיזוג אחרון, אז אחד שנקרא כמו שדה אמיתי כמו `model` או `outcome` היה כתוב על זה ו-שינוי כלונה שמור. Namespace שלך; המתאמים משתמשים `fw_` קידומת. + + שדות תוספת מגיעים אחרון, אז אחד שם כמו שדה אמיתי כגון `model` או `outcome` היה overwrite זה ושינוי עמודה אחסון. שדה שלך; המתאמים משתמש `fw_` קידומת. - - `agent_id` היא low-cardinality facet ו-אתה שים run id בזה. השתמש תפקיד או node שם ו-שים ה-ID אמיתי בשדה payload. + + `agent_id` הוא low-cardinality facet וגם אתה שם id ריצה בו. השתמש תפקיד או צומת שם וגם שם id אמיתי ב-שדה מטענה. @@ -727,12 +725,12 @@ Redaction פועל איפה ה-daemon **כתוב** שלהם אירועים — - זוגות, ids, session lifecycle, ו-delivery. + זוגות, ids, סשן lifecycle, וחלוקה. - - עקוב סיבתיות דרך ה-session אתה רק תפוסה. + + עקוב causality דרך הסשן בדיוק תפסת. - + LangGraph, CrewAI, LlamaIndex, ו-Pydantic AI. \ No newline at end of file diff --git a/docs/hi/start/integrations/custom-agents.mdx b/docs/hi/start/integrations/custom-agents.mdx index 52b1fcc4..e7b8f675 100644 --- a/docs/hi/start/integrations/custom-agents.mdx +++ b/docs/hi/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "कस्टम एजेंट" sidebarTitle: "कस्टम एजेंट" -description: "एक एजेंट को इंस्ट्रूमेंट करें जिसे आपने स्वयं लिखा है, या एक फ्रेमवर्क जिसके लिए कोई एडेप्टर नहीं है।" +description: "अपने द्वारा लिखे गए एजेंट या ऐसे फ्रेमवर्क को इंस्ट्रूमेंट करें जिसके लिए कोई एडाप्टर नहीं है।" icon: "code" --- -एक एजेंट के लिए जिसे आपने स्वयं लिखा है, या एक फ्रेमवर्क जिसके लिए Failproof AI के पास कोई एडेप्टर नहीं है। इंस्ट्रूमेंट करने के लिए कुछ नहीं है: आप ईवेंट उत्सर्जित करते हैं। +एजेंट जो आपने अपने आप लिखा हो, या कोई ऐसा फ्रेमवर्क जिसके लिए Failproof AI के पास एडाप्टर नहीं है। इंस्ट्रूमेंट करने के लिए कुछ नहीं है: आप ही इवेंट्स को एमिट करते हैं। -यह वही API है जिसे चारों फ्रेमवर्क एडेप्टर अंदर से कॉल करते हैं। वे इसके ऊपर अनुवाद तालिकाएं हैं। +यह वही API है जिसे चारों फ्रेमवर्क एडाप्टर अंदर से कॉल करते हैं। वे इसके ऊपर ट्रांसलेशन टेबल हैं। ## इंस्टॉल करें @@ -15,7 +15,7 @@ icon: "code" pip install failproofai-sdk ``` -कोई अतिरिक्त नहीं, और कोई निर्भरता नहीं। +कोई एक्सट्रास नहीं, और कोई डिपेंडेंसीज नहीं। ## इंस्ट्रूमेंट करें @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # एक रन t.output = search(q) # एक टूल कॉल ``` -इसे ऊपर से नीचे पढ़ें और यह कहता है कि इसका मतलब क्या है: +इसे ऊपर से नीचे पढ़ें और यह कहता है कि इसका क्या मतलब है: -| इसे लपेटें | कहने के लिए | +| इसमें रखें | यह कहने के लिए | | --- | --- | -| `session()` | ये ईवेंट एक ही रन से संबंधित हैं | -| `agent()` | कुछ काम कर रहा है — इसे एक नाम दें जिसे आप सूची में पहचान सकें | -| `tool_call()` | यह एक टूल है, और यहां यह क्या लौटाया है | +| `session()` | ये इवेंट्स एक ही रन से संबंधित हैं | +| `agent()` | कोई काम कर रहा है — इसे एक नाम दें जिसे आप किसी लिस्ट में पहचान सकें | +| `tool_call()` | यह एक टूल है, और इसने यह वापस किया | -और प्रत्येक वास्तव में क्या उत्सर्जित करता है: +और हर एक वास्तव में क्या एमिट करता है: -| स्कोप | उत्सर्जन | उद्देश्य | +| स्कोप | एमिट करता है | उद्देश्य | | --- | --- | --- | -| `session()` | कुछ नहीं | एक सेशन id बांधता है, एक रन को समूहीकृत करता है | +| `session()` | कुछ नहीं | एक सेशन आईडी को बांधता है, एक रन को ग्रुप करता है | | `agent()` | `agent_start`, `agent_end` | काम की एक यूनिट को ब्रैकेट करता है | | `tool_call()` | `tool_use`, `tool_result` | एक टूल को ब्रैकेट करता है और इसे मापता है | -अंदर सब कुछ `session_id` और `agent_id` को छोड़ सकता है। स्कोप संदर्भ चर पर पहचान बांधते हैं और हर ईवेंट कॉल इसे वापस पढ़ता है, इसलिए आप अपने फ़ंक्शन के माध्यम से कभी id का धागा नहीं डालते। +इसके अंदर कुछ भी `session_id` और `agent_id` को छोड़ सकता है। स्कोप्स कॉन्टेक्स्ट वेरिएबल्स पर आइडेंटिटी को बांधते हैं और हर इवेंट कॉल इसे वापस पढ़ता है, इसलिए आप कभी आईडीज को अपने फंक्शन्स के माध्यम से थ्रेड नहीं करते। -तीनों `async with` और `with` दोनों के तहत काम करते हैं। +तीनों `with` के साथ-साथ `async with` के तहत भी काम करते हैं। -एजेंट को नेस्ट करने से पेड़ बनता है। `parent_id` और गहराई को स्टैक से गणना की जाती है: +एजेंट्स को नेस्ट करना ट्री बनाता है। `parent_id` और डेप्थ को स्टैक से कंप्यूट किया जाता है: ```python with failproofai_sdk.session(): @@ -61,44 +61,44 @@ with failproofai_sdk.session(): ## एक स्कोप कैसे बंद होता है -`agent()` आपके लिए अपवाद संभालता है: +`agent()` आपके लिए एक्सेप्शन्स को हैंडल करता है: -| क्या हुआ | ईवेंट | परिणाम | +| क्या हुआ | इवेंट्स | परिणाम | | --- | --- | --- | | कुछ नहीं उठा | `agent_end` | `success` | | `Exception` | `error`, फिर `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, फिर `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | केवल `agent_end` | `cancelled` | -त्रुटि `agent_end` से पहले उत्सर्जित होती है, क्योंकि डैशबोर्ड `agent_end` पर स्पान को बंद करता है और इसके बाद कुछ भी कुछ भी में जिम्मेदार नहीं है। एक रद्दीकरण एक विफलता नहीं है, इसलिए रद्द किए गए रन त्रुटि सतह को प्रदूषित नहीं करते। अपवाद हमेशा फिर से उठाया जाता है: एक स्कोप कभी निगल नहीं लेता। +एरर को `agent_end` से पहले एमिट किया जाता है, क्योंकि डैशबोर्ड `agent_end` पर स्पैन को बंद करता है और इसके बाद कुछ भी कुछ नहीं के लिए एट्रिब्यूट किया जाता है। कैंसलेशन एक विफलता नहीं है, इसलिए कैंसल किए गए रन एरर्स सर्फेस को प्रदूषित नहीं करते। एक्सेप्शन को हमेशा फिर से उठाया जाता है: एक स्कोप कभी निगल नहीं जाता। -## ईवेंट विधियां +## इवेंट मेथड्स -छह परिवारों में पंद्रह विधियां। अधिकतर जोड़े में आते हैं — आप ओपनर उत्सर्जित करते हैं, फिर क्लोजर, और SDK उनके बीच का स्पान मापता है। +छः परिवारों में पंद्रह मेथड्स। अधिकांश जोड़े में आते हैं — आप ओपनर को एमिट करते हैं, फिर क्लोजर को, और SDK उनके बीच के स्पैन को मापता है। -| परिवार | खुलता है | बंद होता है | स्टैंडअलोन | +| परिवार | खोलता है | बंद करता है | स्टैंडअलोन | | --- | --- | --- | --- | -| **एजेंट** | `agent_start` | `agent_end` | — | +| **एजेंट्स** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | -| **मॉडल** | `model_request` | `model_response` | — | -| **टूल** | `tool_use` | `tool_result` | — | -| **हुक** | `hook_triggered` | `hook_completed` | — | -| **मनुष्य** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **मॉडल्स** | `model_request` | `model_response` | — | +| **टूल्स** | `tool_use` | `tool_result` | — | +| **हुक्स** | `hook_triggered` | `hook_completed` | — | +| **ह्यूमन्स** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | | **विफलताएं** | — | — | `error` | - स्कोप को प्राथमिकता दें — `agent()` और `tool_call()` — जहां वे फिट हों। वे बंद होने वाली ईवेंट की गारंटी देते हैं यहां तक कि जब बॉडी उठे। इन विधियों को सीधे तब पकड़ें जब आपका नियंत्रण प्रवाह नेस्ट न हो, जैसे कि एक हेल्पर के अंदर एक मॉडल कॉल। + स्कोप्स को प्राथमिकता दें — `agent()` और `tool_call()` — जहां कहीं वे फिट हों। वे क्लोजिंग इवेंट को गारंटी देते हैं भले ही बॉडी उठे। इन मेथड्स को सीधे तब तक के लिए रीच करें जब तक आपके कंट्रोल फ्लो नेस्ट न हों, जैसे किसी हेल्पर के अंदर एक मॉडल कॉल। -```python एजेंट +```python एजेंट्स failproofai_sdk.event.agent_start(agent_id="planner", goal="find the cheapest flight") failproofai_sdk.event.agent_end(agent_id="planner", outcome="success", summary="...") failproofai_sdk.event.agent_pause(pause_id="p1", reason="awaiting approval") failproofai_sdk.event.agent_resume(pause_id="p1") ``` -```python मॉडल +```python मॉडल्स failproofai_sdk.event.model_request( model="gpt-4o-mini", messages=[{"role": "user", "content": "..."}], @@ -114,17 +114,17 @@ failproofai_sdk.event.model_response( ) ``` -```python टूल +```python टूल्स failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1", input={"q": "..."}) failproofai_sdk.event.tool_result(tool_name="search", tool_call_id="c1", output="...") ``` -```python हुक +```python हुक्स failproofai_sdk.event.hook_triggered(hook_name="retrieve", hook_id="h1", trigger_event="node") failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome="success") ``` -```python मनुष्य +```python ह्यूमन्स failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **दो मानव परिवार विपरीत दिशा में इंगित करते हैं।** + **दोनों ह्यूमन परिवार विपरीत दिशाओं में इशारा करते हैं।** - | विधियां | अर्थ | + | मेथड्स | मतलब | | --- | --- | - | `human_wait` / `human_input` | **एजेंट ने एक व्यक्ति से पूछा** — एक अनुमोदन गेट, एक स्पष्ट प्रश्न | - | `human_pause` / `human_interrupt` | **किसी व्यक्ति ने एजेंट पर कार्य किया** — एक स्टॉप बटन, एक ऑपरेटर पॉज़ | + | `human_wait` / `human_input` | **एजेंट ने किसी व्यक्ति से पूछा** — एक अनुमोदन गेट, एक स्पष्टीकरण प्रश्न | + | `human_pause` / `human_interrupt` | **किसी व्यक्ति ने एजेंट पर काम किया** — एक स्टॉप बटन, एक ऑपरेटर पॉज़ | - कोई फ्रेमवर्क दूसरी जोड़ी का संकेत नहीं देता, इसलिए यह हमेशा आपकी है कि उत्सर्जन करें। + कोई भी फ्रेमवर्क दूसरी जोड़ी को सिग्नल नहीं करता, इसलिए यह हमेशा आपका है। - **जब मॉडल कॉल समवर्ती रूप से चलते हैं तो `request_id` पास करें।** इसके बिना, अनुरोध और प्रतिक्रियाएं प्रति एजेंट आगमन क्रम में जोड़ी होती हैं — और समवर्ती कॉल गलत जोड़ी बनाते हैं, प्रत्येक प्रतिक्रिया को गलत अनुरोध से जोड़ते हैं। + **जब मॉडल कॉल्स एक साथ चलते हैं तो `request_id` पास करें।** इसके बिना, रिक्वेस्ट्स और रिस्पांसेस प्रति एजेंट एरिवल ऑर्डर में जोड़े जाते हैं — और एक साथ कॉल्स मिस्पेयर होते हैं, हर रिस्पांस को गलत रिक्वेस्ट से जोड़ते हैं। ## उदाहरण -OpenAI API के विरुद्ध एक टूल-कॉलिंग लूप, कोई एजेंट फ्रेमवर्क के बिना: +OpenAI API के खिलाफ एक टूल-कॉलिंग लूप, कोई एजेंट फ्रेमवर्क के बिना: ```python import json @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # सीमाबद्ध; एक असीमित एजेंट लूप इसका अपना बग है + for _ in range(4): # bounded; an unbounded agent loop is its own bug message = turn(messages) if not message.tool_calls: break @@ -204,34 +204,34 @@ with failproofai_sdk.session(): }) ``` -यह छह ईवेंट प्रकार का उत्पादन करता है जो एक एडेप्टर आपको देगा। पूर्ण चलने योग्य संस्करण, टूल परिभाषाओं के साथ, SDK रिपोजिटरी में `docs/manual/examples/` के तहत शिप होता है। +यह छः इवेंट टाइप्स को प्रोड्यूस करता है जो एक एडाप्टर आपको देगा। संपूर्ण रनेबल वर्जन, टूल डेफिनिशन्स के साथ, SDK रिपॉजिटरी में `docs/manual/examples/` के तहत शिप होता है। ## थ्रेड्स और async -संदर्भ चर asyncio कार्यों में स्वचालित रूप से प्रसारित होते हैं। वे नए थ्रेड में प्रसारित नहीं होते, क्योंकि एक थ्रेड एक खाली संदर्भ के साथ शुरू होता है। +कॉन्टेक्स्ट वेरिएबल्स asyncio टास्क्स में स्वचालित रूप से प्रोपेगेट होते हैं। वे नए थ्रेड्स में प्रोपेगेट नहीं होते, क्योंकि एक थ्रेड खाली कॉन्टेक्स्ट के साथ शुरू होता है। ```python -# asyncio: कुछ भी नहीं करना है +# asyncio: कुछ नहीं करना है async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# थ्रेड्स: कॉलेबल को लपेटें +# threads: कॉलेबल को रैप करें pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -`propagate()` के बिना, वर्कर की ईवेंट एक `TypeError` उठाती हैं जो सुधार का नाम देते हैं बजाय किसी सेशन पर उतरने के। यह जानबूझकर है: कोई सेशन के साथ एक ईवेंट को ingest द्वारा छोड़ दिया जाता है और `200` उत्तर दिया जाता है, जो मूक विफलता है जिसे पहचान परत रोकने के लिए मौजूद है। +`propagate()` के बिना, वर्कर की इवेंट्स एक `TypeError` को उठाती हैं जो फिक्स को नाम देता है उसके बजाय कि कोई सेशन न हो। यह जानबूझकर है: कोई इवेंट कोई सेशन के साथ इनजेस्ट द्वारा स्किप किया जाता है और `200` का जवाब दिया जाता है, जो साइलेंट विफलता है जो आइडेंटिटी लेयर मौजूद होने के लिए है। -## एडेप्टर के बिना एक फ्रेमवर्क इंस्ट्रूमेंट करें +## एक फ्रेमवर्क को इंस्ट्रूमेंट करें जिसके पास एडाप्टर नहीं है -हर एजेंट फ्रेमवर्क आपको एक ही तीन सीम देता है। उन्हें मैप करें और आपके पास एक पूर्ण ट्रेस है — चारों शिप किए गए एडेप्टर इससे अधिक कुछ नहीं करते। +हर एजेंट फ्रेमवर्क आपको तीन समान सीम देता है। उन्हें मैप करें और आपके पास एक संपूर्ण ट्रेस है — चारों शिप किए गए एडाप्टर इससे ज्यादा कुछ नहीं करते। -| सीम | आप क्या लिखते हैं | क्या उतरता है | +| सीम | आप क्या लिखते हैं | क्या लैंड होता है | | --- | --- | --- | | रन | `session()` + `agent()` | `agent_start`, `agent_end` | -| प्रत्येक टूल | `tool_call()` | `tool_use`, `tool_result` | -| प्रत्येक मॉडल कॉल | `model_*` जोड़ी | `model_request`, `model_response` | +| हर टूल | `tool_call()` | `tool_use`, `tool_result` | +| हर मॉडल कॉल | `model_*` जोड़ी | `model_request`, `model_response` | @@ -241,15 +241,15 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) result = framework.run(task) ``` - - जो कुछ भी फ्रेमवर्क एक टूल रैपर या मिडलवेयर कहता है उसमें। + + जो कुछ भी फ्रेमवर्क एक टूल रैपर या मिडलवेयर कहता है। ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -264,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **एक नोड, स्टेप या मिडलवेयर सीमा देखने योग्य है?** इसे एक हुक जोड़ी में लपेटें — `hook_triggered` / `hook_completed` — एक नेस्ट किए गए `agent()` में नहीं। `agent_id` कम-कार्डिनलिटी पहलू है, और प्रति नोड एक प्रविष्टि इसे डुबो देती है। हुक स्पान एक ही तरह से प्रस्तुत होते हैं और आपको प्रति-नोड विलंबता देते हैं। + **क्या आपके पास कोई नोड, स्टेप या मिडलवेयर बाउंड्री है जो देखने लायक है?** इसे एक हुक जोड़ी में रैप करें — `hook_triggered` / `hook_completed` — एक नेस्टेड `agent()` नहीं। `agent_id` एक लो-कार्डिनैलिटी फैसेट है, और प्रति नोड एक प्रविष्टि इसे डूब देती है। हुक स्पैन्स एक जैसे रेंडर होते हैं और आपको प्रति-नोड लेटेंसी देते हैं। - **मैनुअल और स्वचालित मिश्रित होते हैं।** एक एडेप्टर एक हाथ से लिखे गए स्कोप के अंदर चल रहा है उस सेशन से जुड़ता है और उस एजेंट का माता-पिता बनता है, इसलिए आपको एक पेड़ मिलता है दो के बजाय — उपयोगी जब आप एक फ्रेमवर्क को स्वयं एक समर्थित के साथ इंस्ट्रूमेंट करते हैं। + **मैनुअल और ऑटोमैटिक कम्पोज़ होते हैं।** एक एडाप्टर एक हाथ से लिखे गए स्कोप के अंदर चलता है जो उस सेशन को जॉइन करता है और उस एजेंट को पेरेंट करता है, इसलिए आप एक ट्री प्राप्त करते हैं न कि दो — उपयोगी जब आप एक फ्रेमवर्क को अपने आप से इंस्ट्रूमेंट करते हैं किसी समर्थित के साथ। - - दो कारण, और ऊपर दिए गए तीन सीम दोनों का उत्तर हैं: + + दो कारण हैं, और उपरोक्त तीन सीम दोनों के लिए जवाब हैं: - - `autogen-core` सितंबर 2025 के बाद से अरक्षित है। - - AG2 अन्य फ्रेमवर्क के हुक के समकक्ष कोई प्रक्रिया-व्यापी पंजीकरण बिंदु नहीं उजागर करता है, इसलिए इसे इंस्ट्रूमेंट करने का अर्थ हर निर्माण साइट पर हर एजेंट को लपेटना है। + - `autogen-core` सितंबर 2025 के बाद से अनमेन्टेन्ड है। + - AG2 कोई प्रोसेस-वाइड रजिस्ट्रेशन पॉइंट नहीं देता है अन्य फ्रेमवर्क्स के हुक्स के बराबर, इसलिए इसे इंस्ट्रूमेंट करने का मतलब हर निर्माण साइट पर हर एजेंट को रैप करना है। - सीम को हाथ से मैप करना एक ही ईवेंट को एक ही निष्ठा पर रिकॉर्ड करता है जो एक शिप किया गया एडेप्टर होगा। + सीम्स को हाथ से मैप करना वही इवेंट्स रिकॉर्ड करता है, एक शिप किए गए एडाप्टर की तरह ही फिडेलिटी पर। -## गहराई में जाना +## गहराई में जाएं -रिकॉर्डिंग वास्तव में कैसे काम करती है। शुरुआत करने के लिए इसमें से कोई भी आवश्यक नहीं है। +रिकॉर्डिंग वास्तव में कैसे काम करती है। शुरुआत करने के लिए इसमें से कोई भी जरूरी नहीं है। -हर रिकॉर्डिंग का एक ही आकार है: एक स्पान खुलता है, काम इसके अंदर नेस्ट होता है, और हर ओपनिंग ईवेंट को एक क्लोजिंग ईवेंट मिलता है। +हर रिकॉर्डिंग का एक जैसा आकार है: एक स्पैन खुलता है, काम इसके अंदर नेस्ट होता है, और हर ओपनिंग इवेंट को क्लोजिंग इवेंट मिलता है। ```mermaid flowchart LR @@ -300,17 +300,17 @@ flowchart LR C --> E(["agent_end"]) ``` -**जोड़ी** यूनिट है। प्रत्येक क्लोजिंग ईवेंट एक अवधि ले जाता है जो SDK इसके ओपनिंग वाले से मापता है। +**जोड़ी** यूनिट है। हर क्लोजिंग इवेंट एक डेशन लेकर आती है जिसे SDK इसके ओपनिंग वन से मापता है। -नीचे एक वास्तविक रन प्रति फ्रेमवर्क है — SDK के साथ शिप किए गए उदाहरणों से कैप्चर किया गया, मॉडल नाम सामान्यीकृत। ध्यान दें कि एक एकल कॉल से कितना वापस आता है। +नीचे एक रियल रन प्रति फ्रेमवर्क है — SDK के साथ शिप किए गए उदाहरणों से कैप्चर किया गया, मॉडल नाम नॉर्मलाइज़्ड। ध्यान दें कि एक एकल कॉल से कितना वापस आता है। - ```text 14 ईवेंट + ```text 14 events 1 +0.000s agent_start LangGraph 2 +0.001s hook_triggered agent 3 +0.002s model_request gpt-4o-mini - 4 +3.023s model_response gpt-4o-mini · 21 आउट-टोक + 4 +3.023s model_response gpt-4o-mini · 21 out-tok 5 +3.024s hook_completed agent 6 +3.024s hook_triggered tools 7 +3.025s tool_use word_count @@ -318,77 +318,77 @@ flowchart LR 9 +3.025s hook_completed tools 10 +3.026s hook_triggered agent 11 +3.027s model_request gpt-4o-mini - 12 +5.717s model_response gpt-4o-mini · 5 आउट-टोक + 12 +5.717s model_response gpt-4o-mini · 5 out-tok 13 +5.720s hook_completed agent 14 +5.721s agent_end LangGraph · success ``` - नोड्स हुक जोड़ी बन जाते हैं, इसलिए आप प्रति-नोड विलंबता प्राप्त करते हैं बिना उन्हें एजेंट सूची में भीड़ किए। + नोड्स हुक जोड़े बन जाते हैं, इसलिए आप प्रति-नोड लेटेंसी प्राप्त करते हैं बिना इसके कि वे एजेंट लिस्ट को भीड़ में ले जाएं। - ```text 10 ईवेंट + ```text 10 events 1 +0.000s agent_start crew - 2 +0.050s agent_start analyst · crew के तहत + 2 +0.050s agent_start analyst · under crew 3 +0.057s model_request gpt-4o-mini - 4 +3.475s model_response gpt-4o-mini · 19 आउट-टोक + 4 +3.475s model_response gpt-4o-mini · 19 out-tok 5 +3.478s tool_use lookup_metric 6 +3.478s tool_result lookup_metric · ok 7 +3.486s model_request gpt-4o-mini - 8 +5.694s model_response gpt-4o-mini · 9 आउट-टोक + 8 +5.694s model_response gpt-4o-mini · 9 out-tok 9 +5.727s agent_end analyst · success 10 +5.739s agent_end crew · success ``` - प्रत्येक एजेंट का `role` इसका स्पान नाम बनता है, इसलिए विलंबता और टोकन खर्च प्रति भूमिका में विभाजित होते हैं। + हर एजेंट की `role` इसका स्पैन नाम बन जाती है, इसलिए लेटेंसी और टोकन स्पेंड प्रति रोल को तोड़ते हैं। - ```text 26 ईवेंट + ```text 26 events 1 +0.000s agent_start Agent 2 +0.001s hook_triggered init_run 4 +0.501s hook_triggered setup_agent 6 +0.503s hook_triggered run_agent_step 7 +0.505s model_request gpt-4o-mini - 8 +3.083s model_response gpt-4o-mini · 18 आउट-टोक + 8 +3.083s model_response gpt-4o-mini · 18 out-tok 10 +3.197s hook_triggered parse_agent_output 12 +3.355s hook_triggered call_tool 13 +3.355s tool_use city_population 14 +3.355s tool_result city_population · ok 16 +3.356s hook_triggered aggregate_tool_results - ... दूसरा पुनरावृत्ति + ... दूसरा इटरेशन 26 +7.038s agent_end Agent · success ``` - एजेंट लूप स्वयं दृश्यमान है, केवल इसके मॉडल कॉल नहीं। + एजेंट लूप ही दिखाई देता है, केवल इसकी मॉडल कॉल्स नहीं। - ```text 8 ईवेंट + ```text 8 events 1 +0.000s agent_start agent 2 +0.001s model_request gpt-4o-mini - 3 +4.413s model_response gpt-4o-mini · 17 आउट-टोक + 3 +4.413s model_response gpt-4o-mini · 17 out-tok 4 +4.415s tool_use population 5 +4.415s tool_result population · ok 6 +4.416s model_request gpt-4o-mini - 7 +8.118s model_response gpt-4o-mini · 6 आउट-टोक + 7 +8.118s model_response gpt-4o-mini · 6 out-tok 8 +8.119s agent_end agent · success ``` - कोई हुक जोड़ी नहीं: Pydantic AI के पास कोई नोड या स्टेप सीमा नहीं है कि ब्रैकेट करने के लिए। + कोई हुक जोड़ी नहीं: Pydantic AI के पास कोई नोड या स्टेप बाउंड्री नहीं है। - - ```text 6 ईवेंट + + ```text 6 events 1 +0.000s agent_start main 2 +0.000s tool_use population 3 +0.000s tool_result population · ok 4 +0.000s model_request gpt-4o-mini - 5 +0.000s model_response gpt-4o-mini · 3 आउट-टोक + 5 +0.000s model_response gpt-4o-mini · 3 out-tok 6 +0.000s agent_end main · success ``` - आप स्वयं इन्हें उत्सर्जित करते हैं। एक ही ईवेंट प्रकार, एक ही निष्ठा — इसका मतलब कॉल साइट है। + आप इन्हें अपने आप एमिट करते हैं। एक ही इवेंट टाइप्स, एक ही फिडेलिटी — यह आपको कॉल साइट्स खर्च करता है। @@ -396,28 +396,28 @@ flowchart LR -**कोई सेशन-अंत ईवेंट नहीं है।** एक सेशन कुछ ऐसा नहीं है जिसे आप बंद करते हैं — यह एक `session_id` साझा करने वाली ईवेंट का एक समूह है। +**कोई सेशन-एंड इवेंट नहीं है।** एक सेशन कुछ नहीं है जिसे आप बंद करते हैं — यह एक `session_id` साझा करने वाली इवेंट्स का एक समूह है। -स्थिति ट्रेस के आकार से प्राप्त की जाती है: +स्टेटस ट्रेस के आकार से निकाला गया है: -| स्थिति | कब | +| स्टेटस | कब | | --- | --- | -| `ongoing` | कम से कम एक स्पान अभी भी खुला है | -| `paused` | एक `agent_pause` का कोई मिलान `agent_resume` नहीं है | -| `error` | कुछ नहीं खुला है, और कम से कम एक ईवेंट विफल रहा | -| `done` | कुछ नहीं खुला है, और कुछ भी विफल नहीं रहा | +| `ongoing` | कम से कम एक स्पैन अभी भी खुला है | +| `paused` | एक `agent_pause` का कोई मेल खाता `agent_resume` नहीं है | +| `error` | कुछ नहीं खुला है, और कम से कम एक इवेंट विफल हुई | +| `done` | कुछ नहीं खुला है, और कुछ विफल नहीं हुआ | -तो एक सेशन तब समाप्त होता है जब हर जोड़ी बंद हो जाती है। एडेप्टर आपके लिए `agent_end` उत्सर्जित करते हैं, और टियरडाउन पर वे कुछ भी अभी भी खुला बंद करते हैं और इसे अधूरा चिह्नित करते हैं — एक क्रैश किया गया रन `done` बैठता है एक दृश्यमान अंतराल के साथ बजाय हैंगिंग के। +तो एक सेशन तब समाप्त होता है जब हर जोड़ी बंद हो जाती है। एडाप्टर आपके लिए `agent_end` एमिट करते हैं, और टियरडाउन पर वे कुछ भी अभी भी खुला छोड़ देते हैं और इसे अधूरा चिह्नित करते हैं — एक क्रैश किया रन `done` के रूप में एक दृश्य अंतराल के साथ सेट हो जाता है हैंगिंग की बजाय। - यह है कि एक सेशन दो कॉल पर फैल सकता है। एक LangGraph `interrupt()` रन को रोकता है, रूट स्पान जानबूझकर खुला रहता है, और पुनरारंभ करने वाली कॉल इसे बंद करती है। दोनों कॉल एक सेशन हैं। + यह है कि क्यों एक सेशन दो कॉल्स को स्पैन कर सकता है। एक LangGraph `interrupt()` रन को रोकता है, रूट स्पैन जानबूझकर खुला रहता है, और रेज़्यूमिंग कॉल इसे बंद करता है। दोनों कॉल्स एक सेशन हैं। - + -`session_id` और `agent_id` हर ईवेंट विधि पर वैकल्पिक हैं। छोड़ा गया, वे एनक्लोजिंग स्कोप से समाधान करते हैं: +`session_id` और `agent_id` हर इवेंट मेथड पर वैकल्पिक हैं। छोड़े गए, वे एनक्लोजिंग स्कोप से रिज़ॉल्व होते हैं: ```python with failproofai_sdk.session(): @@ -425,129 +425,129 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -उन्हें स्पष्ट रूप से पास करने से अभी भी काम करता है और प्राथमिकता लेता है। कुछ भी बांधा नहीं और कुछ भी पारित नहीं, कॉल एक `TypeError` उठाता है जो सुधार का नाम देता है बजाय कोई सेशन के साथ एक ईवेंट उत्सर्जित करने के, जिसे ingest `200` का उत्तर देते हुए छोड़ देगा। +उन्हें स्पष्ट रूप से पास करना अभी भी काम करता है और प्राथमिकता लेता है। कुछ भी बाउंड न हो और कुछ पास न हो, कॉल एक `TypeError` को उठाती है जो फिक्स को नाम देता है न कि कोई सेशन के साथ एक इवेंट एमिट करने के बजाय, जिसे इनजेस्ट स्किप करेगा `200` का जवाब देते हुए। -स्कोप संदर्भ चर पर पहचान बांधते हैं। वे asyncio कार्यों में स्वचालित रूप से प्रसारित होते हैं लेकिन नए थ्रेड में नहीं — `failproofai_sdk.propagate()` में एक वर्कर लपेटें। +स्कोप्स कॉन्टेक्स्ट वेरिएबल्स पर आइडेंटिटी को बांधते हैं। वे asyncio टास्क्स में स्वचालित रूप से प्रोपेगेट होते हैं लेकिन नए थ्रेड्स में नहीं — `failproofai_sdk.propagate()` में एक वर्कर को रैप करें। -#### कौन कौन सी id बनाता है +#### कौन कौन सी आईडी मिंट करता है -| Id | द्वारा बनाई गई | नोट्स | +| आईडी | मिंट किया गया है | नोट्स | | --- | --- | --- | -| `session_id` | आप, या SDK | `session("chat-42")` को शब्दशः उपयोग किया जाता है; छोड़ा गया, SDK एक `uuid4().hex` उत्पन्न करता है | -| `agent_id` | आप, या फ्रेमवर्क | `agent("analyst")` से, एक CrewAI `role`, एक `FunctionAgent.name` से। UUID जैसा मान अस्वीकार और प्रतिस्थापित है | -| `tool_call_id`, `hook_id`, `request_id` | आप, या फ्रेमवर्क | एडेप्टर फ्रेमवर्क के अपने रन id को पुनः उपयोग करते हैं, जिसके कारण जोड़ी थ्रेड हॉप के बाद जीवित रहती हैं | -| **ईवेंट id** | **क्लाउड, ingest पर** | SDK कोई उत्सर्जित नहीं करता है | -| **`dedup_key`** | **क्लाउड, ingest पर** | Org, सेशन, टाइमस्टैम्प, प्रकार और पेलोड का एक हैश। यह असली पहचान है — यह एक पुनः प्रयास की गई बैच को डुप्लिकेट करने के बजाय ढहा देता है | +| `session_id` | आप, या SDK | `session("chat-42")` वर्बैटिम है; छोड़े गए, SDK एक `uuid4().hex` जेनरेट करता है | +| `agent_id` | आप, या फ्रेमवर्क | `agent("analyst")` से, एक CrewAI `role`, एक `FunctionAgent.name`। UUID-लुकिंग वैल्यू को अस्वीकार किया जाता है और बदला जाता है | +| `tool_call_id`, `hook_id`, `request_id` | आप, या फ्रेमवर्क | एडाप्टर फ्रेमवर्क की अपनी रन आईडीज को दोबारा उपयोग करते हैं, जो है क्यों जोड़े थ्रेड हॉप्स को सर्वाइव करते हैं | +| **इवेंट आईडी** | **क्लाउड, इनजेस्ट पर** | SDK कोई एमिट नहीं करता है | +| **`dedup_key`** | **क्लाउड, इनजेस्ट पर** | org, session, timestamp, type और payload का एक हैश। यह असली आइडेंटिटी है — यह एक रिट्राइड बैच को डुप्लीकेट होने की बजाय कोलैप्स करता है | -#### एडेप्टर `session_id` कैसे समाधान करते हैं +#### एडाप्टर `session_id` को कैसे रिज़ॉल्व करते हैं -पहला मैच जीता: +पहला मैच जीतता है: 1. एक स्पष्ट `session_id` विकल्प 2. प्रति-कॉल मेटाडेटा 3. एनक्लोजिंग `session()` स्कोप 4. फ्रेमवर्क मेटाडेटा -5. फ्रेमवर्क का अपना रन id +5. फ्रेमवर्क की अपनी रन आईडी -इसे कभी आविष्कार नहीं किया जाता है जबकि इनमें से एक मौजूद है — एक संश्लेषित id एक रन को कई सेशन में विभाजित करेगा। +यह कभी भी तब तक इन्वेंट नहीं किया जाता जब तक उनमें से एक मौजूद है — एक सिंथेसाइज़्ड आईडी एक रन को कई सेशन्स में स्प्लिट करेगी। -#### `agent_id` को कम कार्डिनलिटी रखें +#### `agent_id` को लो कार्डिनैलिटी रखें -यह हर डैशबोर्ड सतह पर प्राथमिक पहलू है, और एक `LowCardinality(String)` कॉलम। एक प्रति-रन मान कॉलम को खराब करता है और फ़िल्टर ड्रॉपडाउन को प्रति रन एक प्रविष्टि से भरता है। +यह हर डैशबोर्ड सर्फेस पर प्राथमिक फैसेट है, और एक `LowCardinality(String)` कॉलम है। एक प्रति-रन वैल्यू कॉलम को डिग्रेड करती है और फिल्टर ड्रॉपडाउन को प्रति रन एक प्रविष्टि से भर देती है। -एडेप्टर उस कॉलम की रक्षा करते हैं: +एडाप्टर आपके लिए उस कॉलम की रक्षा करते हैं: -| फ्रेमवर्क सौंपता है | रिकॉर्ड किया गया | क्यों | +| फ्रेमवर्क हाथ ओवर करता है | रिकॉर्ड किया गया है | क्यों | | --- | --- | --- | -| `3f9a1c2b-…` (एक UUID) | `main` | कुछ पठनीय नहीं रखने के लिए | -| एक लंबी नंगी हेक्स स्ट्रिंग | `main` | वही | -| `agent-3f9a1c2b-…` | `agent` | प्रति-रन id छीन लिया गया, पठनीय भाग रखा गया | -| `agent-v2` | `agent-v2` | छोटे सेगमेंट अकेले छोड़ दिए जाते हैं | +| `3f9a1c2b-…` (एक UUID) | `main` | रखने के लिए कुछ भी पठनीय नहीं | +| एक लंबी खाली हेक्स स्ट्रिंग | `main` | वही | +| `agent-3f9a1c2b-…` | `agent` | प्रति-रन आईडी स्ट्रिप, पठनीय भाग रखा | +| `agent-v2` | `agent-v2` | शॉर्ट सेगमेंट्स अकेला छोड़ दिया गया | | `step-3` | `step-3` | वही | -असली id `fw_agent_id` / `fw_run_id` पर रखा जाता है, जहां यह एक पहलू बने बिना पूछताछ योग्य रहता है। +असली आईडी को `fw_agent_id` / `fw_run_id` पर रखा जाता है, जहां यह एक फैसेट होने के बिना क्वेरीएबल रहता है। - **यह गार्ड केवल *फ्रेमवर्क* द्वारा चुने गए लेबल को छूता है।** एक `agent_id` जिसे आप स्वयं पास करते हैं — `event.*`, या `failproofai_sdk.agent(...)` के लिए — ठीक जैसे दिया गया रिकॉर्ड किया जाता है। एक स्पष्ट तर्क को मूक रूप से फिर से लिखना उस कार्डिनलिटी से बदतर होगा जिसे यह रोकता है, इसलिए अपने स्वयं के स्पान का नाम तदनुसार रखें। + **यह गार्ड केवल लेबल को छूता है जो *फ्रेमवर्क* ने चुना।** एक `agent_id` जो आप खुद पास करते हैं — `event.*` को, या `failproofai_sdk.agent(...)` को — बिल्कुल जैसे दिया गया है रिकॉर्ड किया जाता है। एक स्पष्ट तर्क को साइलेंटली दोबारा लिखना इसे रोकने वाली कार्डिनैलिटी से बदतर होगा, इसलिए अपने स्वयं के स्पैन्स को तदनुसार नाम दें। - + -| समूह | ईवेंट | +| ग्रुप | इवेंट्स | | --- | --- | -| एजेंट | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | -| मॉडल | `model_request`, `model_response` | -| टूल | `tool_use`, `tool_result` | -| हुक | `hook_triggered`, `hook_completed` | -| मनुष्य | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| एजेंट्स | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| मॉडल्स | `model_request`, `model_response` | +| टूल्स | `tool_use`, `tool_result` | +| हुक्स | `hook_triggered`, `hook_completed` | +| ह्यूमन्स | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | विफलताएं | `error` | -कौन सा फ्रेमवर्क क्या रिकॉर्ड करता है, ऊपर से रन से मापा गया: +कौन सा फ्रेमवर्क क्या रिकॉर्ड करता है, उपरोक्त रन से मापा गया: -| ईवेंट | LangGraph | CrewAI | LlamaIndex | Pydantic AI | कस्टम | +| इवेंट | LangGraph | CrewAI | LlamaIndex | Pydantic AI | कस्टम | | --- | :--: | :--: | :--: | :--: | :--: | -| एजेंट शुरु और अंत | हां | हां | हां | हां | आप | -| मॉडल अनुरोध और प्रतिक्रिया | हां | हां | हां | हां | आप | -| टूल उपयोग और परिणाम | हां | हां | हां | हां | आप | -| हुक ट्रिगर और पूर्ण | नोड | कार्य | स्टेप | — | आप | -| त्रुटि | हां | हां | हां | हां | स्वचालित | -| मानव प्रतीक्षा और इनपुट | हां | हां | हां | — | आप | -| एजेंट पॉज़ और पुनरारंभ | हां | हां | हां | — | आप | +| एजेंट स्टार्ट और एंड | हाँ | हाँ | हाँ | हाँ | आप | +| मॉडल रिक्वेस्ट और रिस्पांस | हाँ | हाँ | हाँ | हाँ | आप | +| टूल यूज़ और रिजल्ट | हाँ | हाँ | हाँ | हाँ | आप | +| हुक ट्रिगर्ड और कम्पलीटेड | नोड | टास्क | स्टेप | — | आप | +| एरर | हाँ | हाँ | हाँ | हाँ | ऑटोमैटिक | +| ह्यूमन वेट और इनपुट | हाँ | हाँ | हाँ | — | आप | +| एजेंट पॉज़ और रेज़्यूम | हाँ | हाँ | हाँ | — | आप | -एक डैश का मतलब फ्रेमवर्क के पास कोई ऐसी अवधारणा नहीं है। `human_pause` और `human_interrupt` एक *व्यक्ति* द्वारा एजेंट पर कार्य करने का वर्णन करते हैं, जिसका कोई फ्रेमवर्क संकेत नहीं देता — स्वयं उत्सर्जन करें। +एक डैश का मतलब है कि फ्रेमवर्क के पास ऐसी कोई कॉन्सेप्ट नहीं है। `human_pause` और `human_interrupt` एक *व्यक्ति* को एजेंट पर काम करने का वर्णन करते हैं, जिसे कोई फ्रेमवर्क सिग्नल नहीं करता — इन्हें अपने आप एमिट करें। - + -एक ईवेंट कभी अकेले नहीं आता। एक स्पान खुलता है, एक बंद होता है, और क्लोजिंग ईवेंट एक अवधि ले जाता है जो SDK इसके ओपनिंग वाले से मापता है। +एक इवेंट कभी भी अकेली नहीं आती। एक स्पैन को खोलता है, एक इसे बंद करता है, और क्लोजिंग इवेंट एक डेशन लेकर आती है जिसे SDK ओपनिंग वन से मापता है। -| खुलता है | बंद होता है | क्लोजिंग ईवेंट ले जाता है | +| खोलता है | बंद करता है | क्लोजिंग इवेंट लेकर आती है | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | -| `model_request` | `model_response` | टोकन, `stop_reason`, विलंबता | -| `tool_use` | `tool_result` | `output` या `error`, अवधि | -| `hook_triggered` | `hook_completed` | `outcome`, अवधि | -| `agent_pause` | `agent_resume` | पॉज़ कितने समय तक चला | -| `human_wait` | `human_input` | उत्तर, और व्यक्ति को कितना समय लगा | +| `model_request` | `model_response` | टोकन्स, `stop_reason`, लेटेंसी | +| `tool_use` | `tool_result` | `output` या `error`, डेशन | +| `hook_triggered` | `hook_completed` | `outcome`, डेशन | +| `agent_pause` | `agent_resume` | पॉज़ कितना लंबा रहा | +| `human_wait` | `human_input` | जवाब, और व्यक्ति को कितना समय लगा | - कोई क्लोजिंग के साथ एक ओपनिंग ईवेंट कभी खत्म नहीं होने वाला एक स्पान है। सेशन हमेशा चल रहे के रूप में प्रस्तुत होता है, हमेशा के लिए, और इसकी सक्रिय अवधि बढ़ती रहती है। यह वह विफलता मोड है जिसे हाथ से इंस्ट्रूमेंट करते समय देखने के लिए है। + कोई क्लोजिंग इवेंट के साथ एक ओपनिंग इवेंट एक स्पैन है जो कभी ख़त्म नहीं होता है। सेशन हमेशा चल रहा दिखाई देता है, हमेशा के लिए, और इसकी एक्टिव डेशन बढ़ती रहती है। यह विफलता मोड है जब आप हाथ से इंस्ट्रूमेंट करते हैं तो देखने के लिए है। -#### सहसंबंध नियम +#### कोरिलेशन नियम -- मिलान पूर्णता ईवेंट के लिए एक ही `tool_call_id`, `hook_id`, `pause_id`, या `input_id` का पुनः उपयोग करें। -- SDK `tool_result`, `hook_completed`, `agent_resume`, और `human_input` के लिए `duration_ms` की गणना करता है। इसे उन विधियों में पास करने से `ValueError` उठता है। -- `duration_ms` **स्वीकार किया जाता है** `model_response` पर, क्योंकि केवल कॉलर असली प्रदाता विलंबता जानता है। यह एक पूर्णांक होना चाहिए — एक फ्लोट कॉल साइट पर `ValueError` उठाता है, क्योंकि सर्वर कॉलम को एक अहस्ताक्षरित 32-बिट पूर्णांक के रूप में पढ़ता है और कुछ और के लिए NULL संग्रहीत करेगा। -- सहसंबंध कुंजियां तरह और सेशन द्वारा स्कोप की जाती हैं, इसलिए एक टूल कॉल और एक हुक सुरक्षित रूप से एक id साझा कर सकते हैं, और दो समवर्ती सेशन टकराए बिना समान id का पुनः उपयोग कर सकते हैं। वे एजेंट द्वारा स्कोप नहीं किए जाते हैं: एक जोड़ी एक एजेंट के तहत खुली और दूसरे के तहत बंद अभी भी सहसंबंधित होती है, जो बहु-एजेंट फ्रेमवर्क में सामान्य मामला है। -- `request_id` `model_request` को `model_response` के साथ जोड़ी करता है। इसके बिना, मॉडल ईवेंट प्रति एजेंट क्रम में जोड़ी होती हैं, इसलिए समवर्ती कॉल गलत जोड़ी बनाती हैं। -- प्रक्रियाओं में विभाजित एक जोड़ी अभी भी डाउनस्ट्रीम में सहसंबंधित होती है, लेकिन SDK इसकी प्रक्रिया में-अवधि की गणना नहीं कर सकता है। -- लंबित मानचित्र अधिकतम 10,000 स्टार्ट पकड़ता है और पूर्ण होने पर सबसे पुरानी प्रविष्टि को निष्कासित करता है। +- मेल खाती कम्पलीशन इवेंट के लिए एक ही `tool_call_id`, `hook_id`, `pause_id`, या `input_id` को दोबारा यूज़ करें। +- SDK `tool_result`, `hook_completed`, `agent_resume`, और `human_input` के लिए `duration_ms` को कंप्यूट करता है। इसे उन मेथड्स को पास करना `ValueError` को उठाता है। +- `duration_ms` **को स्वीकार किया जाता है** `model_response` पर, क्योंकि केवल कॉलर असली प्रोवाइडर लेटेंसी को जानता है। यह एक इंटीजर होना चाहिए — एक फ्लोट कॉल साइट पर `ValueError` को उठाता है, क्योंकि सर्वर कॉलम को एक अनसाइन्ड 32-बिट इंटीजर के रूप में पढ़ता है और कुछ भी और के लिए NULL स्टोर करेगा। +- कोरिलेशन कीज़ को kind और session द्वारा स्कोप किया जाता है, इसलिए एक टूल कॉल और एक हुक सुरक्षित रूप से एक आईडी साझा कर सकते हैं, और दो एक साथ सेशन्स बिना कोलाइड किए एक ही आईडीज को दोबारा उपयोग कर सकते हैं। वे एजेंट द्वारा स्कोप नहीं किए जाते: एक जोड़ी एक एजेंट के तहत खुली और दूसरे के तहत बंद अभी भी डाउनस्ट्रीम में कोरिलेट होती है, जो मल्टी-एजेंट फ्रेमवर्क्स में सामान्य केस है। +- `request_id` `model_request` को `model_response` से जोड़ता है। इसके बिना, मॉडल इवेंट्स प्रति एजेंट ऑर्डर में जोड़े जाते हैं, इसलिए एक साथ कॉल्स मिस्पेयर होती हैं। +- एक जोड़ी प्रोसेस्स में स्प्लिट डाउनस्ट्रीम में अभी भी कोरिलेट होती है, लेकिन SDK इसकी इन-प्रोसेस डेशन को कंप्यूट नहीं कर सकता है। +- पेंडिंग मैप सर्वाधिक 10,000 स्टार्ट्स रखता है और पूर्ण होने पर सबसे पुरानी प्रविष्टि को निष्कासित करता है। - + -`failproofai-sdk` इंस्टॉल करने से सब कुछ इंस्टॉल होता है, सभी चार एडेप्टर शामिल हैं। अतिरिक्त एडेप्टर नहीं, **फ्रेमवर्क** खींचते हैं। +`failproofai-sdk` को इंस्टॉल करने से सब कुछ इंस्टॉल होता है, सभी चारों एडाप्टर शामिल। एक्सट्रास **फ्रेमवर्क** को पुल इन करते हैं, एडाप्टर को नहीं। ```python -import failproofai_sdk # मानक पुस्तकालय के बाहर कुछ भी लोड नहीं करता है -failproofai_sdk.instrument() # केवल एडेप्टर आयात करता है जिसकी आपको वास्तव में आवश्यकता है +import failproofai_sdk # स्टैंडर्ड लाइब्रेरी के बाहर कुछ नहीं लोड करता है +failproofai_sdk.instrument() # केवल एडाप्टर्स को इंपोर्ट करता है जिन्हें आप वास्तव में चाहते हैं ``` -`import failproofai_sdk` अनुबंध शून्य-निर्भरता है, एक परीक्षण द्वारा प्रवर्तित जो निर्मित व्हील को `--no-deps` के साथ इंस्टॉल करता है और एक और जो साबित करता है कि कोई फ्रेमवर्क `sys.modules` तक नहीं पहुंचता है। +`import failproofai_sdk` संविदात्मक रूप से शून्य-निर्भरता है, एक टेस्ट द्वारा लागू किया गया है जो `--no-deps` के साथ बिल्ट व्हील को इंस्टॉल करता है और एक अन्य जो साबित करता है कि कोई फ्रेमवर्क `sys.modules` तक नहीं पहुंचता है। - कोई `failproofai_sdk.crewai` विशेषता नहीं है। एडेप्टर जानबूझकर शीर्ष-स्तरीय पैकेज पर प्रदर्शित नहीं होते हैं: एक को छूना एक विशेषता पहुंच के दुष्प्रभाव के रूप में फ्रेमवर्क आयात करेगा, शून्य-निर्भरता प्रतिश्रुति को तोड़ते हुए। `instrument()` का उपयोग करें। + कोई `failproofai_sdk.crewai` एट्रिब्यूट नहीं है। एडाप्टर्स को जानबूझकर टॉप-लेवल पैकेज पर एक्सपोज़ नहीं किया जाता है: एक को छूना एक एट्रिब्यूट एक्सेस के साइड इफेक्ट के रूप में फ्रेमवर्क को इंपोर्ट करेगा, शून्य-निर्भरता प्रॉमिस को तोड़ देगा। `instrument()` का यूज़ करें। ```python -failproofai_sdk.instrument() # हर फ्रेमवर्क पहले से ही आयात किया गया है +failproofai_sdk.instrument() # हर फ्रेमवर्क पहले से ही इंपोर्ट किया गया failproofai_sdk.instrument("crewai") # बिल्कुल एक, नाम से -failproofai_sdk.uninstrument("crewai") # इसे वापस रखो +failproofai_sdk.uninstrument("crewai") # इसे वापस रखें ``` | नाम | यह भी स्वीकार करता है | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # इसे वापस रखो | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -ऑटो-डिटेक्शन `sys.modules` को पढ़ता है, न कि इंस्टॉल किए गए पैकेज सूची को, इसलिए एक फ्रेमवर्क जिसे आपने इंस्टॉल किया है लेकिन कभी आयात नहीं किया वह इंस्ट्रूमेंट नहीं है और आपकी ओर से कभी आयात नहीं किया जाता है। यह देखने के लिए कि क्या वायर्ड है: +ऑटो-डिटेक्शन `sys.modules` को पढ़ता है, इंस्टॉल किए गए पैकेज लिस्ट को नहीं, इसलिए एक फ्रेमवर्क जो आपके पास इंस्टॉल है लेकिन कभी इंपोर्ट नहीं किया गया इंस्ट्रूमेंट नहीं है और आपकी ओर से कभी इंपोर्ट नहीं होता है। क्या है यह देखने के लिए वायर्ड अप: ```python from failproofai_sdk.integrations import active, available @@ -567,132 +567,130 @@ active() # ('langchain',) ``` - **बिना CrewAI वाली मशीन पर `instrument("crewai")` नहीं उठाता।** यह एक चेतावनी लॉग करता है और `()` लौटाता है, इसलिए एक लापता फ्रेमवर्क कभी एक प्रक्रिया को नीचे नहीं लाता है जो अन्य को भी इंस्ट्रूमेंट करता है। + **`instrument("crewai")` एक मशीन पर CrewAI के बिना उठाता नहीं है।** यह एक चेतावनी लॉग करता है और `()` रिटर्न करता है, इसलिए एक गायब फ्रेमवर्क कभी भी एक प्रोसेस को नीचे नहीं ले जाता जो अन्य लोगों को भी इंस्ट्रूमेंट करता है। - चेतावनी अंतर्निहित `ImportError` ले जाती है, और वह संदेश सटीक install कमांड का नाम देता है — इसलिए सुधार आपके लॉग में है, छिपा नहीं। + चेतावनी अंतर्निहित `ImportError` को लेकर आती है, और वह संदेश सटीक इंस्टॉल कमांड को नाम देता है — इसलिए फिक्स आपके लॉग्स में है, छिपा नहीं है। ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - इसके बजाय उठाने के लिए `FAILPROOFAI_SDK_STRICT=1` सेट करें। वह झंडा **एक बार पढ़ा जाता है और कैश किया जाता है**, इसलिए मध्य-रन सेट करने के बजाय अपनी प्रक्रिया शुरू होने से पहले निर्यात करें। + इसे उठाने के लिए `FAILPROOFAI_SDK_STRICT=1` सेट करें। वह फ्लैग **एक बार पढ़ा जाता है और कैश किया जाता है**, इसलिए इसे अपनी प्रोसेस शुरू होने से पहले एक्सपोर्ट करें न कि मिड-रन सेट करें। - **`instrument()` *आपके फ्रेमवर्क आयात के बाद* आना चाहिए।** ऑटो-डिटेक्शन `sys.modules` को पढ़ता है, इसलिए आयात के ऊपर एक नंगा कॉल कुछ भी नहीं खोजता है, कुछ भी इंस्टॉल नहीं करता है, और `()` लौटाता है। + **`instrument()` आपके फ्रेमवर्क इंपोर्ट के *बाद* आना चाहिए।** ऑटो-डिटेक्शन `sys.modules` को पढ़ता है, इसलिए इंपोर्ट के ऊपर एक खाली कॉल कुछ नहीं खोजता है, कुछ नहीं इंस्टॉल करता है, और `()` रिटर्न करता है। ```python गलत import failproofai_sdk -failproofai_sdk.instrument() # sys.modules के पास अभी तक कोई langchain नहीं है -> () +failproofai_sdk.instrument() # sys.modules के पास अभी langchain नहीं है -> () -import langchain # बहुत देर हो गई, कुछ भी वायर्ड नहीं है +import langchain # बहुत देर, कुछ नहीं वायर्ड है ``` ```python सही -import langchain # पहले फ्रेमवर्क आयात करें +import langchain # पहले फ्रेमवर्क को इंपोर्ट करें import failproofai_sdk failproofai_sdk.instrument() # इसे खोजता है -> ('langchain',) ``` -```python सही, क्रम-प्रूफ +```python सही, ऑर्डर-प्रूफ import failproofai_sdk -# इसका नाम देने से एडेप्टर अनुरोध पर आयात होता है, इसलिए यह कहीं से भी काम करता है। +# इसे नाम देने से एडाप्टर को अनुरोध पर इंपोर्ट करता है, इसलिए यह कहीं से भी काम करता है। failproofai_sdk.instrument("langchain") ``` -यह गलत प्राप्त करें और प्रक्रिया SDK आयातित, एडेप्टर स्पष्ट रूप से इंस्टॉल, और **कोई भी ईवेंट उत्सर्जित नहीं** के साथ चलता है। यह एक चेतावनी लॉग करता है जो बिल्कुल ऐसा कहता है — इसलिए एक रन रिकॉर्ड नहीं करते समय पहले अपने लॉग जांचें। +यह गलत प्राप्त करें और प्रोसेस SDK इंपोर्ट के साथ चलता है, एडाप्टर स्पष्ट रूप से इंस्टॉल किया गया, और **एक भी इवेंट एमिट नहीं।** यह यह कह रही एक चेतावनी लॉग करता है — इसलिए जब एक रन कुछ भी रिकॉर्ड नहीं करता है तो पहले अपने लॉग्स को चेक करें। - + ```mermaid flowchart LR - A["आपका एजेंट"] --> B["एडेप्टर"] - B --> C["राइटर
इन-मेमोरी कतार"] + A["आपका एजेंट"] --> B["एडाप्टर"] + B --> C["राइटर
इन-मेमोरी क्यू"] C -->|"हर 0.5s"| D["स्पूल
डिस्क पर JSONL"] - D --> E["Failproof डेमन"] + D --> E["Failproof डेमॉन"] E -->|"HTTPS"| F["क्लाउड"] ``` -| चरण | काम | में चलता है | +| स्टेज | जॉब | रन में | | --- | --- | --- | -| एडेप्टर | एक फ्रेमवर्क कॉलबैक को 15 ईवेंट प्रकारों में से एक में अनुवाद करता है | आपकी प्रक्रिया | -| राइटर | कतार, बैच, JSONL परमाणु रूप से लिखता है | आपकी प्रक्रिया, पृष्ठभूमि थ्रेड | -| स्पूल | टिकाऊ हस्तांतरण, आपकी प्रक्रिया से बचता है | स्थानीय डिस्क | -| डेमन | स्पूल देखता है, बैच भेजता है, जो भेजा गया है उसे हटाता है | आपकी मशीन | -| Ingest | एक पंक्ति id और dedup कुंजी असाइन करता है, पूछताछ योग्य कॉलम को बढ़ावा देता है | क्लाउड | +| एडाप्टर | एक फ्रेमवर्क कॉलबैक को 15 इवेंट टाइप्स में से एक में ट्रांसलेट करता है | आपकी प्रोसेस | +| राइटर | क्यू करता है, बैच करता है, JSONL को परमाणु रूप से लिखता है | आपकी प्रोसेस, बैकग्राउंड थ्रेड | +| स्पूल | टिकाऊ हैंडऑफ, आपकी प्रोसेस से बाहर निकलना सर्वाइव करता है | स्थानीय डिस्क | +| डेमॉन | स्पूल को देखता है, बैच को शिप करता है, जो शिप करता है उसे डिलीट करता है | आपकी मशीन | +| इनजेस्ट | एक पंक्ति आईडी और डीडुप की असाइन करता है, क्वेरीएबल कॉलम्स को प्रमोट करता है | क्लाउड | -स्पूल वह है जो इसे सुरक्षित बनाता है: आपका एजेंट कभी नेटवर्क पर ब्लॉक नहीं होता है, और एक क्लाउड आउटेज एक बढ़ती डायरेक्टरी का मतलब है खोई हुई ईवेंट के बजाय। +स्पूल यह है जो यह सुरक्षित बनाता है: आपका एजेंट कभी भी नेटवर्क पर ब्लॉक नहीं करता है, और एक क्लाउड आउटेज का मतलब एक बढ़ती हुई डायरेक्टरी है खोई हुई इवेंट्स की बजाय। -प्रत्येक फ्लश एक बैच फाइल लिखता है, पहले `.tmp`, फिर `fsync`, फिर एक परमाणु नाम बदलना: +हर फ्लश एक बैच फ़ाइल लिखता है, `.tmp` पहले, फिर `fsync`, फिर एक परमाणु रीनेम: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -डेमन केवल `.jsonl` उठाता है, इसलिए यह कभी आधी-लिखी गई फाइल नहीं पढ़ सकता। स्टेम एक टाइमस्टैम्प, प्रक्रिया id और अनुक्रम संख्या ले जाता है, इसलिए दो प्रक्रियाएं एक ही मिलीसेकंड में फ्लश करना संघर्ष नहीं कर सकती हैं। कतार 10,000 ईवेंट पर capped है; इसके बाद यह सबसे पुरानी को बंद करता है और लॉग करता है। +डेमॉन केवल `.jsonl` को पिक अप करता है, इसलिए यह कभी भी एक आधी-लिखी गई फ़ाइल को नहीं पढ़ सकता है। स्टेम एक टाইमस्टैम्प, प्रोसेस आईडी और सीक्वेंस नंबर को लेकर आती है, इसलिए दो प्रोसेस्स एक ही मिलीसेकंड में फ्लश होने से कोलाइड नहीं कर सकते हैं। क्यू को 10,000 इवेंट्स पर कैप किया गया है; उसके आगे यह सबसे पुरानी को ड्रॉप करता है और लॉग करता है। - **`collector.redact` आपकी SDK ईवेंट पर लागू नहीं होता है।** यह कभी उन्हें नहीं देखता है। + **`collector.redact` SDK इवेंट्स के लिए भी `minimal` को डिफ़ॉल्ट करता है।** SDK बैच को डिस्क में लिखने से पहले स्क्रब करता है, और डेमॉन अपलोड से पहले एक ही नियतिवादी पास को दोहराता है इसलिए पुराने SDKs से बैच संरक्षित हैं। -डेमन आपकी बैच **भेजता है**। वह उन्हें खोलता या फिर से लिखता नहीं है। +डेमॉन हर बैच को पढ़ता है और अपलोड से पहले इन-मेमोरी में रीडेक्शन को लागू करता है। यह पढ़ी गई स्पूल फ़ाइल को दोबारा लिखता नहीं है। -| ईवेंट | द्वारा लिखा गया | `collector.redact` से संरक्षित? | +| इवेंट्स | लिखा गया है | जहां न्यूनतम रीडेक्शन चलता है | | --- | --- | --- | -| CLI सेशन प्रतिलेख | डेमन | हां | -| हुक गतिविधि | डेमन | हां | -| **SDK जो कुछ भी उत्सर्जित करता है** | **आपकी प्रक्रिया** | **नहीं** | +| CLI सेशन ट्रांसक्रिप्ट्स | डेमॉन | डेमॉन बैच लिखने से पहले | +| हुक एक्टिविटी | डेमॉन | डेमॉन बैच लिखने से पहले | +| **सब कुछ SDK एमिट करता है** | **आपकी प्रोसेस** | **SDK बैच लिखने से पहले और डेमॉन अपलोड से पहले** | -संपादन जहां डेमन अपनी स्वयं की ईवेंट **लिखता है** — जहां बैच **भेजे जाते हैं** नहीं। इसलिए एक प्रॉम्प्ट या एक टूल तर्क जिसमें एक API कुंजी होती है अभी भी आगमन पर रखती है। - -यह जानबूझकर है। ये आपके स्वयं के इंस्ट्रूमेंटेशन कॉल हैं, और पारगमन में उन्हें फिर से लिखने का अर्थ होगा कि आप जो ईवेंट प्राप्त करते हैं वे ईवेंट नहीं हैं जो आपने उत्सर्जित किए हैं। +`collector.redact` को `off` पर केवल तब सेट करें जब वर्बैटिम पेलोड्स एक स्पष्ट आवश्यकता हों; SDK और डेमॉन दोनों उस सेटिंग को सम्मानित करते हैं। न्यूनतम रीडेक्शन सामान्य API की, बेयरर टोकन्स, JWTs, और सीक्रेट असाइनमेंट्स को पकड़ता है। यह मनमाना संवेदनशील गद्य को आइडेंटिफाई नहीं कर सकता है। - **आप स्रोत पर पेलोड को नियंत्रित करते हैं, दो जगहों में:** + **आप पेलोड्स को स्रोत पर नियंत्रित करते हैं, दो जगहों में:** - - एडेप्टर पर सामग्री कैप्चर बंद करें। **विकल्प नाम भिन्न होता है, और एक एडेप्टर के पास कोई नहीं है** — यह एक एकल सार्वभौमिक स्विच नहीं है: + - एडाप्टर पर कॉन्टेंट कैप्चर को बंद करें। **विकल्प नाम भिन्न होता है, और एक एडाप्टर के पास कोई नहीं है** — यह एक एकल सार्वभौमिक स्विच नहीं है: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **कोई सामग्री स्विच नहीं**; `session_id` एकमात्र विकल्प है यह पढ़ता है, इसलिए प्रॉम्प्ट और पूर्ति हमेशा रिकॉर्ड किए जाते हैं। + - CrewAI — **कोई कॉन्टेंट स्विच नहीं**; `session_id` एकमात्र विकल्प है जो यह पढ़ता है, इसलिए प्रॉम्प्ट्स और कम्पलीशन्स हमेशा रिकॉर्ड होते हैं। - `instrument()` एडेप्टर द्वारा पढ़ी जाने वाली विकल्प को छोड़ता है, इसलिए गलत नाम पास करने से कुछ नहीं उठाया जाता है और कुछ भी नहीं बदलता है। - - पहली जगह में रहस्य को `input=` को हाथ न सौंपें। + `instrument()` ऐसे विकल्पों को ड्रॉप करता है जो एक एडाप्टर पढ़ता नहीं है, इसलिए गलत नाम को पास करना कुछ भी उठाता नहीं और कुछ भी नहीं बदलता है। + - सीक्रेट को `input=` में पहली जगह पर हाथ न दें। - `collector.redact` किसी के लिए विकल्प नहीं है। + `collector.redact` डिफेंस इन डेप्थ है, किसी भी का विकल्प नहीं। - **एक खाली स्पूल डायरेक्टरी स्वस्थ स्थिति है।** इसे डिलीवरी की जांच करने के लिए न बनाएं। + **एक खाली स्पूल डायरेक्टरी स्वस्थ स्टेट है।** डिलीवरी को चेक करने के लिए इसका यूज़ न करें। -डेमन इसे भेजने के मिलीसेकंड के भीतर प्रत्येक बैच को हटा देता है, इसलिए एक `ls` रेस एकत्रकर्ता और आपने जो उत्सर्जित किया उसका एक अंश दिखाता है — एक SDK से अप्रभेद्य जो कुछ भी रिकॉर्ड नहीं करता है। +डेमॉन इसे शिप करने के एक मिलीसेकंड के अंदर हर बैच को डिलीट करता है, इसलिए एक `ls` कलेक्टर को रेस करता है और आपने जो एमिट किया उसका एक अंश दिखाता है — एक SDK से अलग नहीं जिसने कुछ भी रिकॉर्ड नहीं किया। -ईवेंट वास्तव में उतरे हैं यह पुष्टि करने के लिए, डैशबोर्ड की जांच करें। स्पूल को भरते हुए देखने के लिए, पहले डेमन को रोकें। +इवेंट्स वास्तव में लैंड किए गए हैं यह कन्फर्म करने के लिए, डैशबोर्ड को चेक करें। स्पूल को भरते हुए देखने के लिए, पहले डेमॉन को स्टॉप करें। - + -हर कॉलबैक एक रैपर के अंदर चलता है जिसका एकमात्र काम पुनः उठाना है, इसलिए आपकी कॉल ठीक एक `try` में बैठता है और सब कुछ SDK करता है इसके बाहर होता है। +हर कॉलबैक एक रैपर के अंदर चलता है जिसका एकमात्र जॉब फिर से उठाना है, इसलिए आपकी कॉल बिल्कुल एक `try` में बैठती है और सब कुछ SDK करता है इसके बाहर होता है। | क्या होता है | परिणाम | | --- | --- | -| एक हुक उठाता है | अपने ट्रेसबैक के साथ एक बार लॉग किया गया। आपकी कॉल अप्रभावित है | -| एक ही हुक तीन बार उठाता है | वह एक हुक बाकी के लिए अक्षम हो जाता है, एक त्रुटि पंक्ति के साथ | -| `FAILPROOFAI_SDK_STRICT=1` सेट है | अपवाद के बजाय फिर से उठाया जाता है | -| एक फ्रेमवर्क संस्करण परीक्षित सीमा के बाहर है | एक बार चेतावनी, किसी भी तरह इंस्ट्रूमेंट | -| एक एकल क्षमता लापता है | वह एक हुक अक्षम है, संपूर्ण एडेप्टर कभी नहीं | +| एक हुक उठाता है | अपनी ट्रेसबैक के साथ एक बार लॉग किया गया। आपकी कॉल अप्रभावित है | +| एक ही हुक तीन बार उठाता है | वह हुक बाकी प्रोसेस के लिए डिसेबल्ड है, एक एरर लाइन के साथ | +| `FAILPROOFAI_SDK_STRICT=1` सेट है | एक्सेप्शन को फिर से उठाया जाता है | +| एक फ्रेमवर्क वर्जन टेस्ट्ड रेंज के बाहर है | एक बार चेतावनी, अभी भी इंस्ट्रूमेंट करता है | +| एक एकल क्षमता गायब है | वह हुक डिसेबल्ड है, कभी पूरा एडाप्टर नहीं | -डिफ़ॉल्ट उत्पादन में सही है और डीबग करते समय गलत है, क्योंकि यह केवल यह साबित कर सकता है कि यह क्रैश नहीं हुआ। डीबग करते समय इसे जोर देने के लिए `FAILPROOFAI_SDK_STRICT=1` सेट करें। +डिफ़ॉल्ट प्रोडक्शन में सही है और डीबग करते समय गलत है, क्योंकि यह केवल यह साबित कर सकता है कि यह क्रैश नहीं हुआ। `FAILPROOFAI_SDK_STRICT=1` सेट करें एक निगली हुई विफलता को जोर दे करने के लिए। @@ -701,24 +699,24 @@ flowchart LR ## सामान्य समस्याएं - - एक ओपनिंग ईवेंट का कोई क्लोजिंग नहीं है: एक `model_request` के बिना `model_response`, या एक `tool_use` के बिना `tool_result`। स्कोप का उपयोग करें, जो शरीर उठाए जाने पर भी जोड़ी की गारंटी देते हैं। यदि आप ईवेंट विधियों को सीधे कॉल करते हैं, तो `try` और `finally` का उपयोग करें। + + एक ओपनिंग इवेंट का कोई क्लोजिंग नहीं है: एक `model_request` कोई `model_response` के बिना, या एक `tool_use` कोई `tool_result` के बिना। स्कोप्स का यूज़ करें, जो भले ही बॉडी उठे तब भी जोड़ी को गारंटी देते हैं। यदि आप इवेंट मेथड्स को सीधे कॉल करते हैं, तो `try` और `finally` का यूज़ करें। - - यह मिलान ओपनिंग ईवेंट से मापा जाता है, इसलिए यह `tool_result`, `hook_completed`, `agent_resume`, और `human_input` पर अस्वीकार किया जाता है। यह `model_response` पर स्वीकार किया जाता है, क्योंकि केवल आप असली प्रदाता विलंबता जानते हैं, और यह एक पूर्णांक होना चाहिए। + + यह मेल खाती ओपनिंग इवेंट से मापा जाता है, इसलिए यह `tool_result`, `hook_completed`, `agent_resume`, और `human_input` पर अस्वीकार किया जाता है। यह `model_response` पर स्वीकार किया जाता है, क्योंकि केवल आप असली प्रोवाइडर लेटेंसी को जानते हैं, और यह एक इंटीजर होना चाहिए। - - थ्रेड ने कभी संदर्भ को विरासत में नहीं दिया। कॉलेबल को `failproofai_sdk.propagate()` में लपेटें। [थ्रेड्स और async](#threads-and-async) देखें। + + थ्रेड ने कभी कॉन्टेक्स्ट को इन्हेरिट नहीं किया। कॉलेबल को `failproofai_sdk.propagate()` में रैप करें। [थ्रेड्स और async](#threads-and-async) को देखें। - - अतिरिक्त फील्ड आखिरी में मर्ज होते हैं, इसलिए `model` या `outcome` जैसे वास्तविक फील्ड का नाम इसे अधिलेखित करेगा और एक संग्रहीत कॉलम बदल देगा। अपना नामस्थान; एडेप्टर एक `fw_` उपसर्ग का उपयोग करते हैं। + + एक्सट्रा फ़ील्ड्स आखिरी में मर्ज होती हैं, इसलिए `model` या `outcome` जैसी असली फ़ील्ड की तरह एक का नाम इसे ओवरराइट करेगा और एक स्टोर किए गए कॉलम को बदलेगा। अपने को नेमस्पेस दें; एडाप्टर्स एक `fw_` प्रीफिक्स का यूज़ करते हैं। - - `agent_id` कम-कार्डिनलिटी पहलू है और आपने एक रन id में डाल दिया। एक भूमिका या नोड नाम का उपयोग करें और असली id को एक पेलोड फील्ड में डालें। + + `agent_id` एक लो-कार्डिनैलिटी फैसेट है और आपने एक रन आईडी को इसमें डाल दिया। एक रोल या नोड नाम का यूज़ करें और असली आईडी को एक पेलोड फ़ील्ड में डालें। @@ -726,12 +724,12 @@ flowchart LR - जोड़ी, id, सेशन जीवनचक्र, और डिलीवरी। + जोड़े, आईडीज, सेशन लाइफसाइकल, और डिलीवरी। - - आपके द्वारा अभी कैप्चर किए गए सेशन के माध्यम से कारणात्मकता का पालन करें। + + सेशन के माध्यम से कारण को फॉलो करें जिसे आपने अभी कैप्चर किया है। - + LangGraph, CrewAI, LlamaIndex, और Pydantic AI। \ No newline at end of file diff --git a/docs/it/start/integrations/custom-agents.mdx b/docs/it/start/integrations/custom-agents.mdx index 9e2f4361..7b6ed12e 100644 --- a/docs/it/start/integrations/custom-agents.mdx +++ b/docs/it/start/integrations/custom-agents.mdx @@ -7,7 +7,7 @@ icon: "code" Per un agente che hai scritto tu stesso, o un framework per il quale Failproof AI non ha un adapter. Non c'è nulla da strumentare: tu emetti gli eventi. -Questa è la stessa API che i quattro adapter di framework chiamano internamente. Sono tabelle di traduzione su di essa. +Questa è la stessa API che i quattro adapter del framework chiamano internamente. Sono tabelle di traduzione su di essa. ## Installa @@ -15,7 +15,7 @@ Questa è la stessa API che i quattro adapter di framework chiamano internamente pip install failproofai-sdk ``` -Nessun extra, nessuna dipendenza. +Nessun extra, e nessuna dipendenza. ## Strumenta @@ -24,33 +24,33 @@ import failproofai_sdk failproofai_sdk.configure(environment="production") -with failproofai_sdk.session(): # una esecuzione - with failproofai_sdk.agent("planner"): # un'unità di lavoro +with failproofai_sdk.session(): # one run + with failproofai_sdk.agent("planner"): # one unit of work with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # una chiamata dello strumento + t.output = search(q) # one tool call ``` -Leggi da cima a fondo e dice quello che significa: +Leggilo dall'alto al basso e dice quello che significa: -| Avvolgi con | Per dire | +| Avvolgilo in | Per dire | | --- | --- | | `session()` | Questi eventi appartengono alla stessa esecuzione | -| `agent()` | Qualcosa sta svolgendo un lavoro — assegnale un nome che riconosceresti in un elenco | +| `agent()` | Qualcosa sta facendo lavoro — dagli un nome che riconosceresti in una lista | | `tool_call()` | Questo è uno strumento, e ecco cosa ha restituito | -E cosa emette effettivamente ciascuno: +E quello che ognuno effettivamente emette: | Ambito | Emette | Scopo | | --- | --- | --- | -| `session()` | Nulla | Associa un session id, raggruppando un'esecuzione | +| `session()` | Niente | Associa un session id, raggruppando un'esecuzione | | `agent()` | `agent_start`, `agent_end` | Racchiude un'unità di lavoro | | `tool_call()` | `tool_use`, `tool_result` | Racchiude uno strumento e lo misura | -Tutto ciò che è contenuto può omettere `session_id` e `agent_id`. Gli ambiti vincolano l'identità su variabili di contesto e ogni chiamata di evento la legge di nuovo, quindi non devi mai passare gli id attraverso le tue funzioni. +Tutto ciò che è dentro può omettere `session_id` e `agent_id`. Gli ambiti associano l'identità su variabili di contesto e ogni chiamata di evento la legge di nuovo, quindi non devi mai passare gli id attraverso le tue funzioni. -Tutti e tre funzionano sia con `async with` che con `with`. +Tutti e tre funzionano con `async with` così come con `with`. -L'annidamento di agenti costruisce l'albero. `parent_id` e profondità sono calcolati dalla stack: +Annidare gli agenti costruisce l'albero. `parent_id` e la profondità vengono calcolati dallo stack: ```python with failproofai_sdk.session(): @@ -59,24 +59,24 @@ with failproofai_sdk.session(): ... ``` -## Come un ambito si chiude +## Come si chiude un ambito `agent()` gestisce le eccezioni per te: | Cosa è successo | Eventi | Risultato | | --- | --- | --- | -| Nulla lanciato | `agent_end` | `success` | +| Niente sollevato | `agent_end` | `success` | | `Exception` | `error`, poi `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, poi `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | solo `agent_end` | `cancelled` | -L'errore è emesso prima di `agent_end`, perché il dashboard chiude lo span a `agent_end` e qualsiasi cosa dopo è attribuita a nulla. Una cancellazione non è un fallimento, quindi le esecuzioni cancellate non inquinano la superficie degli errori. L'eccezione è sempre lanciata di nuovo: un ambito non inghiotte mai. +L'errore viene emesso prima di `agent_end`, perché la dashboard chiude lo span a `agent_end` e qualsiasi cosa dopo viene attribuita al nulla. Un'annullamento non è un fallimento, quindi le esecuzioni annullate non inquinano la superficie degli errori. L'eccezione viene sempre sollevata di nuovo: un ambito non la inghiotte mai. -## I metodi evento +## I metodi degli eventi -Quindici metodi in sei famiglie. La maggior parte viene in coppia — emetti l'apertura, poi la chiusura, e l'SDK misura l'intervallo tra loro. +Quindici metodi in sei famiglie. La maggior parte viene in coppie — tu emetti l'apertura, poi la chiusura, e l'SDK misura lo span tra loro. -| Famiglia | Apre | Chiude | Indipendente | +| Famiglia | Apre | Chiude | Autonomo | | --- | --- | --- | --- | | **Agenti** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | @@ -87,7 +87,7 @@ Quindici metodi in sei famiglie. La maggior parte viene in coppia — emetti l'a | **Fallimenti** | — | — | `error` | - Preferisci gli ambiti — `agent()` e `tool_call()` — ovunque si adattino. Garantiscono l'evento di chiusura anche quando il corpo genera un'eccezione. Raggiungi questi metodi direttamente quando il tuo flusso di controllo non si annida, ad esempio una chiamata di modello dentro un helper. + Preferisci gli ambiti — `agent()` e `tool_call()` — ovunque si adattino. Garantiscono l'evento di chiusura anche quando il corpo solleva. Raggiungi questi metodi direttamente quando il flusso di controllo non si annida, come una chiamata di modello all'interno di un helper. @@ -148,16 +148,16 @@ failproofai_sdk.event.error( | `human_wait` / `human_input` | L'**agente ha chiesto a una persona** — un gate di approvazione, una domanda di chiarimento | | `human_pause` / `human_interrupt` | Una **persona ha agito sull'agente** — un pulsante di arresto, una pausa dell'operatore | - Nessun framework segnala la seconda coppia, quindi è sempre tuo compito emetterla. + Nessun framework segnala la seconda coppia, quindi spetta sempre a te emetterla. - **Passa `request_id` quando le chiamate di modello vengono eseguite contemporaneamente.** Senza di esso, le richieste e le risposte si abbinano in ordine di arrivo per agente — e le chiamate contemporanee si abbinano male, allegando ogni risposta alla richiesta sbagliata. + **Passa `request_id` quando le chiamate di modello vengono eseguite contemporaneamente.** Senza di esso, le richieste e le risposte si associano in ordine di arrivo per agente — e le chiamate contemporanee si accopiano male, allegando ogni risposta alla richiesta sbagliata. ## Esempio -Un ciclo di chiamata di strumenti contro l'API di OpenAI, senza framework di agenti: +Un ciclo di tool-calling rispetto all'API OpenAI, senza framework di agenti: ```python import json @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # limitato; un ciclo di agente illimitato è un suo bug + for _ in range(4): # bounded; an unbounded agent loop is its own bug message = turn(messages) if not message.tool_calls: break @@ -204,30 +204,30 @@ with failproofai_sdk.session(): }) ``` -Questo produce gli stessi sei tipi di evento che un adapter ti darebbe. La versione completamente eseguibile, con le definizioni degli strumenti, è fornita nel repository SDK under `docs/manual/examples/`. +Questo produce gli stessi sei tipi di evento che darebbe un adapter. La versione completamente eseguibile, con le definizioni degli strumenti, è spedita nel repository dell'SDK sotto `docs/manual/examples/`. ## Thread e async -Le variabili di contesto si propagano nei task asyncio automaticamente. Non si propagano nei nuovi thread, perché un thread inizia con un contesto vuoto. +Le variabili di contesto si propagano nei compiti asyncio automaticamente. Non si propagano nei nuovi thread, perché un thread inizia con un contesto vuoto. ```python -# asyncio: nulla da fare +# asyncio: nothing to do async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# thread: avvolgi il callable +# threads: wrap the callable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Senza `propagate()`, gli eventi del worker generano un `TypeError` che nomina la correzione anziché atterrare su nessuna sessione. È intenzionale: un evento senza sessione è saltato dall'ingest e restituito `200`, che è il fallimento silenzioso che il livello di identità esiste per prevenire. +Senza `propagate()`, gli eventi del worker sollevano un `TypeError` nominando la correzione piuttosto che arrivare a nessuna sessione. È intenzionale: un evento senza sessione viene saltato dall'ingest e riceve `200`, che è il fallimento silenzioso che il livello di identità esiste per prevenire. ## Strumenta un framework senza un adapter -Ogni framework di agenti ti dà le stesse tre giunzioni. Mappale e hai una traccia completa — i quattro adapter forniti non fanno nulla di più che questo. +Ogni framework di agenti ti dà le stesse tre giunture. Mappale e hai una traccia completa — i quattro adapter spediti non fanno niente di più che questo. -| La giunzione | Quello che scrivi | Quello che atterra | +| La giuntura | Quello che scrivi | Quello che arriva | | --- | --- | --- | | L'esecuzione | `session()` + `agent()` | `agent_start`, `agent_end` | | Ogni strumento | `tool_call()` | `tool_use`, `tool_result` | @@ -242,7 +242,7 @@ Ogni framework di agenti ti dà le stesse tre giunzioni. Mappale e hai una tracc ``` - In qualsiasi cosa il framework chiami wrapper di strumento o middleware. + In qualunque cosa il framework chiami un wrapper di strumento o middleware. ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -264,31 +264,31 @@ Ogni framework di agenti ti dà le stesse tre giunzioni. Mappale e hai una tracc - **Hai un confine di nodo, passo o middleware che vale la pena vedere?** Avvolgilo in una coppia di hook — `hook_triggered` / `hook_completed` — non in un `agent()` annidato. `agent_id` è una sfaccettatura a bassa cardinalità, e un'entry per nodo lo annega. Gli span hook si rendono allo stesso modo e ti danno latenza per nodo. + **Hai un confine di nodo, step o middleware che vale la pena vedere?** Avvolgilo in una coppia di hook — `hook_triggered` / `hook_completed` — non un `agent()` annidato. `agent_id` è una facet a bassa cardinalità, e un'entry per nodo l'annega. Gli span Hook si rendono nello stesso modo e ti danno una latenza per nodo. - **Manuale e automatico si compongono.** Un adapter in esecuzione dentro un ambito scritto a mano si unisce a quella sessione e si aggancia a quell'agente, quindi ottieni un albero anziché due — utile quando strumenti un framework da solo insieme a uno supportato. + **Manuale e automatico si compongono.** Un adapter in esecuzione all'interno di un ambito scritto a mano si unisce a quella sessione e ha come padre quell'agente, quindi ottieni un albero piuttosto che due — utile quando strumenti un framework tu stesso insieme a uno supportato. - Due motivi, e le tre giunzioni sopra sono la risposta ad entrambi: + Due ragioni, e le tre giunture sopra sono la risposta a entrambe: - - `autogen-core` non è stata mantenuta dal settembre 2025. - - AG2 non espone un punto di registrazione a livello di processo equivalente agli hook degli altri framework, quindi strumentarlo significa avvolgere ogni agente ad ogni sito di costruzione. + - `autogen-core` non è stato mantenuto da settembre 2025. + - AG2 non espone un punto di registrazione a livello di processo equivalente agli hook dei framework altri, quindi strumentarlo significa avvolgere ogni agente in ogni sito di costruzione. - Mappare le giunzioni a mano registra gli stessi eventi, con la stessa fedeltà, che un adapter fornito darebbe. + Mappare le giunture a mano registra gli stessi eventi, con la stessa fedeltà, di un adapter spedito. ## Approfondisci -Come la registrazione funziona effettivamente. Niente di tutto ciò è necessario per iniziare. +Come funziona effettivamente la registrazione. Niente di questo è necessario per iniziare. -Ogni registrazione ha la stessa forma: uno span si apre, il lavoro si annida dentro, e ogni evento di apertura ne ottiene uno di chiusura. +Ogni registrazione ha la stessa forma: uno span si apre, il lavoro si annida dentro, e ogni evento di apertura riceve uno di chiusura. ```mermaid flowchart LR @@ -302,15 +302,15 @@ flowchart LR La **coppia** è l'unità. Ogni evento di chiusura porta una durata che l'SDK misura dal suo evento di apertura. -Di seguito è una vera esecuzione per framework — catturata dagli esempi forniti con l'SDK, nome del modello normalizzato. Nota quanto ritorna da una singola chiamata. +Di seguito è una vera esecuzione per framework — catturata dagli esempi spediti con l'SDK, il nome del modello normalizzato. Nota quanto ritorna da una singola chiamata. - ```text 14 eventi + ```text 14 events 1 +0.000s agent_start LangGraph 2 +0.001s hook_triggered agent 3 +0.002s model_request gpt-4o-mini - 4 +3.023s model_response gpt-4o-mini · 21 token-out + 4 +3.023s model_response gpt-4o-mini · 21 out-tok 5 +3.024s hook_completed agent 6 +3.024s hook_triggered tools 7 +3.025s tool_use word_count @@ -318,24 +318,24 @@ Di seguito è una vera esecuzione per framework — catturata dagli esempi forni 9 +3.025s hook_completed tools 10 +3.026s hook_triggered agent 11 +3.027s model_request gpt-4o-mini - 12 +5.717s model_response gpt-4o-mini · 5 token-out + 12 +5.717s model_response gpt-4o-mini · 5 out-tok 13 +5.720s hook_completed agent 14 +5.721s agent_end LangGraph · success ``` - I nodi diventano coppie di hook, quindi ottieni la latenza per nodo senza che affollino l'elenco degli agenti. + I nodi diventano coppie di hook, quindi ottieni la latenza per nodo senza che affollino la lista degli agenti. - ```text 10 eventi + ```text 10 events 1 +0.000s agent_start crew 2 +0.050s agent_start analyst · under crew 3 +0.057s model_request gpt-4o-mini - 4 +3.475s model_response gpt-4o-mini · 19 token-out + 4 +3.475s model_response gpt-4o-mini · 19 out-tok 5 +3.478s tool_use lookup_metric 6 +3.478s tool_result lookup_metric · ok 7 +3.486s model_request gpt-4o-mini - 8 +5.694s model_response gpt-4o-mini · 9 token-out + 8 +5.694s model_response gpt-4o-mini · 9 out-tok 9 +5.727s agent_end analyst · success 10 +5.739s agent_end crew · success ``` @@ -344,19 +344,19 @@ Di seguito è una vera esecuzione per framework — catturata dagli esempi forni - ```text 26 eventi + ```text 26 events 1 +0.000s agent_start Agent 2 +0.001s hook_triggered init_run 4 +0.501s hook_triggered setup_agent 6 +0.503s hook_triggered run_agent_step 7 +0.505s model_request gpt-4o-mini - 8 +3.083s model_response gpt-4o-mini · 18 token-out + 8 +3.083s model_response gpt-4o-mini · 18 out-tok 10 +3.197s hook_triggered parse_agent_output 12 +3.355s hook_triggered call_tool 13 +3.355s tool_use city_population 14 +3.355s tool_result city_population · ok 16 +3.356s hook_triggered aggregate_tool_results - ... seconda iterazione + ... second iteration 26 +7.038s agent_end Agent · success ``` @@ -364,60 +364,60 @@ Di seguito è una vera esecuzione per framework — catturata dagli esempi forni - ```text 8 eventi + ```text 8 events 1 +0.000s agent_start agent 2 +0.001s model_request gpt-4o-mini - 3 +4.413s model_response gpt-4o-mini · 17 token-out + 3 +4.413s model_response gpt-4o-mini · 17 out-tok 4 +4.415s tool_use population 5 +4.415s tool_result population · ok 6 +4.416s model_request gpt-4o-mini - 7 +8.118s model_response gpt-4o-mini · 6 token-out + 7 +8.118s model_response gpt-4o-mini · 6 out-tok 8 +8.119s agent_end agent · success ``` - Nessuna coppia di hook: Pydantic AI non ha un confine di nodo o passo da racchiudere. + Nessuna coppia di hook: Pydantic AI non ha un confine di nodo o step da racchiudere. - ```text 6 eventi + ```text 6 events 1 +0.000s agent_start main 2 +0.000s tool_use population 3 +0.000s tool_result population · ok 4 +0.000s model_request gpt-4o-mini - 5 +0.000s model_response gpt-4o-mini · 3 token-out + 5 +0.000s model_response gpt-4o-mini · 3 out-tok 6 +0.000s agent_end main · success ``` - Tu emetti questi. Stessi tipi di evento, stessa fedeltà — ti costa i siti di chiamata. + Tu emetti questi tu stesso. Stessi tipi di evento, stessa fedeltà — ti costa i siti di chiamata. - + -**Non c'è evento di chiusura sessione.** Una sessione non è qualcosa che chiudi — è un gruppo di eventi che condividono un `session_id`. +**Non esiste un evento session-end.** Una sessione non è qualcosa che chiudi — è un gruppo di eventi che condividono un `session_id`. Lo stato è derivato dalla forma della traccia: | Stato | Quando | | --- | --- | | `ongoing` | Almeno uno span è ancora aperto | -| `paused` | Un `agent_pause` non ha un corrispondente `agent_resume` | -| `error` | Nulla è aperto, e almeno un evento ha fallito | -| `done` | Nulla è aperto, e nulla ha fallito | +| `paused` | Un `agent_pause` non ha un `agent_resume` corrispondente | +| `error` | Niente è aperto, e almeno un evento ha fallito | +| `done` | Niente è aperto, e niente ha fallito | -Quindi una sessione termina quando ogni coppia è chiusa. Gli adapter emettono `agent_end` per te, e in fase di teardown chiudono qualsiasi cosa ancora aperta e la contrassegnano come incompleta — un'esecuzione arrestata si assesta come `done` con un gap visibile anziché stare sospesa. +Quindi una sessione finisce quando ogni coppia è chiusa. Gli adapter emettono `agent_end` per te, e allo smontaggio chiudono tutto ciò che è ancora aperto e lo contrassegnano come incompleto — un'esecuzione in crash si risolve come `done` con un vuoto visibile piuttosto che rimanendo sospesa. - Questo è il motivo per cui una sessione può coprire due chiamate. Un `interrupt()` di LangGraph mette in pausa l'esecuzione, lo span radice rimane deliberatamente aperto, e la chiamata ripresa lo chiude. Entrambe le chiamate sono una sessione. + Ecco perché una sessione può durare due chiamate. Un `interrupt()` LangGraph mette in pausa l'esecuzione, lo span radice rimane volutamente aperto, e la chiamata riprendente lo chiude. Entrambe le chiamate sono una sessione. - + -`session_id` e `agent_id` sono opzionali in ogni metodo evento. Omessi, si risolvono dall'ambito che li racchiude: +`session_id` e `agent_id` sono opzionali su ogni metodo di evento. Omessi, si risolvono dall'ambito che li racchiude: ```python with failproofai_sdk.session(): @@ -425,50 +425,50 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Pasarli esplicitamente funziona ancora e ha precedenza. Senza nulla vincolato e nulla passato, la chiamata genera un `TypeError` che nomina la correzione anziché emettere un evento senza sessione, che l'ingest salterebbe mentre restituisce `200`. +Passarli esplicitamente funziona ancora e ha la precedenza. Senza niente associato e niente passato, la chiamata solleva un `TypeError` nominando la correzione piuttosto che emettendo un evento senza sessione, che ingest salterebbe rispondendo `200`. -Gli ambiti vincolano l'identità su variabili di contesto. Queste si propagano nei task asyncio automaticamente ma non nei nuovi thread — avvolgi un worker in `failproofai_sdk.propagate()`. +Gli ambiti associano l'identità su variabili di contesto. Queste si propagano nei compiti asyncio automaticamente ma non nei nuovi thread — avvolgi un worker in `failproofai_sdk.propagate()`. -#### Chi conia quale id +#### Chi crea quale id -| Id | Coniato da | Note | +| Id | Creato da | Note | | --- | --- | --- | -| `session_id` | Tu, o l'SDK | `session("chat-42")` è usato verbatim; omesso, l'SDK genera un `uuid4().hex` | -| `agent_id` | Tu, o il framework | Da `agent("analyst")`, un `role` di CrewAI, un `FunctionAgent.name`. Un valore che somiglia a UUID è rifiutato e sostituito | -| `tool_call_id`, `hook_id`, `request_id` | Tu, o il framework | Gli adapter riutilizzano gli id di esecuzione propri del framework, motivo per cui le coppie sopravvivono ai salti di thread | -| **Id evento** | **Cloud, in ingest** | L'SDK non ne emette alcuno | -| **`dedup_key`** | **Cloud, in ingest** | Un hash di org, sessione, timestamp, tipo e payload. Questa è l'identità reale — rende un batch ritentato collassato anziché duplicato | +| `session_id` | Tu, o l'SDK | `session("chat-42")` viene usato verbatim; omesso, l'SDK genera un `uuid4().hex` | +| `agent_id` | Tu, o il framework | Da `agent("analyst")`, un `role` di CrewAI, un `FunctionAgent.name`. Un valore simile a UUID viene rifiutato e sostituito | +| `tool_call_id`, `hook_id`, `request_id` | Tu, o il framework | Gli adapter riutilizzano gli id di esecuzione del framework stesso, ecco perché le coppie sopravvivono ai salti di thread | +| **Event id** | **Cloud, all'ingest** | L'SDK non ne emette nessuno | +| **`dedup_key`** | **Cloud, all'ingest** | Un hash di org, sessione, timestamp, tipo e payload. Questa è l'identità reale — fa collassare un batch ritentato invece di duplicarlo | #### Come gli adapter risolvono `session_id` La prima corrispondenza vince: 1. Un `session_id` esplicito -2. Metadati per-chiamata -3. L'ambito `session()` che lo racchiude +2. Metadati per-call +3. L'ambito `session()` che racchiude 4. Metadati del framework -5. L'id di esecuzione proprio del framework +5. L'id di esecuzione del framework stesso -Non è mai inventato mentre uno di questi esiste — un id sintetizzato dividerebbe un'esecuzione su più sessioni. +Non viene mai inventato mentre uno di quelli esiste — un id sintetizzato dividerebbe un'esecuzione su più sessioni. #### Mantieni `agent_id` a bassa cardinalità -È la sfaccettatura primaria su ogni superficie del dashboard, e una colonna `LowCardinality(String)`. Un valore per-esecuzione degrada la colonna e riempie il dropdown del filtro con un'entry per esecuzione. +È la facet primaria su ogni superficie della dashboard, e una colonna `LowCardinality(String)`. Un valore per-esecuzione degrada la colonna e riempie il menu filtro con un'entry per esecuzione. Gli adapter difendono quella colonna per te: | Il framework consegna | Registrato come | Perché | | --- | --- | --- | -| `3f9a1c2b-…` (un UUID) | `main` | Nulla di leggibile da conservare | -| Una lunga stringa hex nuda | `main` | Uguale | -| `agent-3f9a1c2b-…` | `agent` | Id per-esecuzione rimosso, parte leggibile conservata | -| `agent-v2` | `agent-v2` | Brevi segmenti sono lasciati soli | -| `step-3` | `step-3` | Uguale | +| `3f9a1c2b-…` (un UUID) | `main` | Niente di leggibile da mantenere | +| Una lunga stringa di hex nuda | `main` | Stesso | +| `agent-3f9a1c2b-…` | `agent` | Id per-esecuzione strappato, parte leggibile mantenuta | +| `agent-v2` | `agent-v2` | Segmenti brevi vengono lasciati soli | +| `step-3` | `step-3` | Stesso | -L'id reale è conservato su `fw_agent_id` / `fw_run_id`, dove rimane interrogabile senza essere una sfaccettatura. +L'id reale viene mantenuto su `fw_agent_id` / `fw_run_id`, dove rimane interrogabile senza essere una facet. - **Questa guardia tocca solo etichette che il *framework* ha scelto.** Un `agent_id` che passi tu stesso — a `event.*`, o a `failproofai_sdk.agent(...)` — è registrato esattamente come dato. Riscrivere silenziosamente un argomento esplicito sarebbe peggio della cardinalità che previene, quindi nomina i tuoi span di conseguenza. + **Questo guard tocca solo le etichette che il *framework* ha scelto.** Un `agent_id` che passi tu stesso — a `event.*`, o a `failproofai_sdk.agent(...)` — viene registrato esattamente come dato. Riscrivere silenziosamente un argomento esplicito sarebbe peggio della cardinalità che previene, quindi nomina i tuoi span di conseguenza. @@ -491,18 +491,18 @@ Quale framework registra cosa, misurato dalle esecuzioni sopra: | Inizio e fine dell'agente | Sì | Sì | Sì | Sì | Tu | | Richiesta e risposta del modello | Sì | Sì | Sì | Sì | Tu | | Uso e risultato dello strumento | Sì | Sì | Sì | Sì | Tu | -| Hook attivato e completato | Nodo | Attività | Passo | — | Tu | +| Hook attivato e completato | Nodo | Compito | Step | — | Tu | | Errore | Sì | Sì | Sì | Sì | Automatico | -| Attesa umana e input | Sì | Sì | Sì | — | Tu | +| Attesa e input umano | Sì | Sì | Sì | — | Tu | | Pausa e ripresa dell'agente | Sì | Sì | Sì | — | Tu | -Un trattino significa che il framework non ha un tale concetto. `human_pause` e `human_interrupt` descrivono una *persona* che agisce sull'agente, che nessun framework segnala — emettili tu stesso. +Un trattino significa che il framework non ha un tale concetto. `human_pause` e `human_interrupt` descrivono una *persona* che agisce sull'agente, che nessun framework segnala — emetti quelli tu stesso. -Un evento non arriva mai solo. Uno apre uno span, uno lo chiude, e l'evento di chiusura porta una durata che l'SDK misura dal suo evento di apertura. +Un evento non arriva mai da solo. Uno apre uno span, uno lo chiude, e l'evento di chiusura porta una durata che l'SDK misura dal suo evento di apertura. | Apre | Chiude | L'evento di chiusura porta | | --- | --- | --- | @@ -511,43 +511,43 @@ Un evento non arriva mai solo. Uno apre uno span, uno lo chiude, e l'evento di c | `tool_use` | `tool_result` | `output` o `error`, durata | | `hook_triggered` | `hook_completed` | `outcome`, durata | | `agent_pause` | `agent_resume` | quanto è durata la pausa | -| `human_wait` | `human_input` | la risposta, e quanto tempo la persona ha impiegato | +| `human_wait` | `human_input` | la risposta, e quanto tempo ha impiegato la persona | - Un evento di apertura senza uno di chiusura è uno span che non finisce mai. La sessione si rende come ancora in esecuzione, per sempre, e la sua durata attiva continua a crescere. Questo è il modo di fallimento da osservare quando strumenti a mano. + Un evento di apertura senza uno di chiusura è uno span che non finisce mai. La sessione si mostra come ancora in esecuzione, per sempre, e la sua durata attiva continua a crescere. Questo è il modo di fallimento da guardare quando strumenti a mano. #### Regole di correlazione - Riutilizza lo stesso `tool_call_id`, `hook_id`, `pause_id`, o `input_id` per l'evento di completamento corrispondente. -- L'SDK calcola `duration_ms` per `tool_result`, `hook_completed`, `agent_resume`, e `human_input`. Passarlo a questi metodi genera `ValueError`. -- `duration_ms` **è** accettato su `model_response`, perché solo il chiamante conosce la vera latenza del provider. Deve essere un intero — un float genera `ValueError` al sito di chiamata, perché il server legge la colonna come un intero senza segno a 32 bit e memorizzerebbe NULL per qualsiasi cosa diversa. -- Le chiavi di correlazione sono scoped per genere e sessione, quindi una chiamata di strumento e un hook possono condividere un id in sicurezza, e due sessioni contemporanee possono riutilizzare gli stessi id senza collisioni. Non sono scoped per agente: una coppia aperta sotto un agente e chiusa sotto un altro ancora si correla, che è il caso ordinario nei framework multi-agente. -- `request_id` accoppia `model_request` con `model_response`. Senza di esso, gli eventi di modello si abbinano in ordine per agente, quindi le chiamate contemporanee si abbinano male. -- Una coppia divisa tra processi ancora si correla a valle, ma l'SDK non può calcolarne la durata in-processo. -- La mappa in sospeso contiene al massimo 10.000 avviamenti e elimina l'entry più vecchia quando è piena. +- L'SDK calcola `duration_ms` per `tool_result`, `hook_completed`, `agent_resume`, e `human_input`. Passarlo a quei metodi solleva `ValueError`. +- `duration_ms` **è** accettato su `model_response`, perché solo il chiamante conosce la vera latenza del provider. Deve essere un intero — un float solleva `ValueError` al sito di chiamata, perché il server legge la colonna come un intero senza segno a 32 bit e memorizzerebbe NULL per qualsiasi cosa. +- Le chiavi di correlazione sono scoped per genere e sessione, quindi una chiamata di strumento e un hook possono tranquillamente condividere un id, e due sessioni contemporanee possono riutilizzare gli stessi id senza collidere. Non sono scoped per agente: una coppia aperta sotto un agente e chiusa sotto un altro correla ancora, che è il caso ordinario nei framework multi-agente. +- `request_id` accoppia `model_request` con `model_response`. Senza di esso, gli eventi di modello si accopiano in ordine per agente, quindi le chiamate contemporanee si accopiano male. +- Una coppia divisa tra processi correla ancora downstream, ma l'SDK non può calcolarne la durata in-process. +- La mappa in sospeso contiene al massimo 10.000 avvii ed estrae l'entry più vecchia quando è piena. - + -Installare `failproofai-sdk` installa tutto, tutti e quattro gli adapter inclusi. Gli extra tirano il **framework**, non l'adapter. +L'installazione di `failproofai-sdk` installa tutto, tutti e quattro gli adapter inclusi. Gli extra tirano il **framework**, non l'adapter. ```python -import failproofai_sdk # non carica nulla fuori dalla libreria standard -failproofai_sdk.instrument() # importa solo gli adapter che effettivamente usi +import failproofai_sdk # loads nothing outside the standard library +failproofai_sdk.instrument() # imports only the adapters you actually need ``` `import failproofai_sdk` è contrattualmente zero-dipendenza, applicato da un test che installa la wheel costruita con `--no-deps` e un altro che prova che nessun framework raggiunge `sys.modules`. - Non c'è un attributo `failproofai_sdk.crewai`. Gli adapter sono deliberatamente non esposti sul package di livello superiore: toccare uno importerebbe il framework come effetto collaterale di un accesso agli attributi, rompendo la promessa di zero-dipendenza. Usa `instrument()`. + Non esiste un attributo `failproofai_sdk.crewai`. Gli adapter sono deliberatamente non esposti sul pacchetto di primo livello: toccarne uno importerebbe il framework come effetto collaterale di un accesso dell'attributo, rompendo la promessa zero-dipendenza. Usa `instrument()`. ```python -failproofai_sdk.instrument() # ogni framework già importato -failproofai_sdk.instrument("crewai") # esattamente uno, per nome -failproofai_sdk.uninstrument("crewai") # rimettilo come era +failproofai_sdk.instrument() # every framework already imported +failproofai_sdk.instrument("crewai") # exactly one, by name +failproofai_sdk.uninstrument("crewai") # put it back ``` | Nome | Accetta anche | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # rimettilo come era | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -L'auto-rilevamento legge `sys.modules`, non l'elenco dei pacchetti installati, quindi un framework che hai installato ma mai importato non è strumentato e non è mai importato per tuo conto. Per vedere cosa è collegato: +L'auto-rilevamento legge `sys.modules`, non l'elenco dei pacchetti installati, quindi un framework che hai installato ma mai importato non viene strumentato e non viene mai importato per tuo conto. Per vedere cosa è cablato: ```python from failproofai_sdk.integrations import active, available @@ -567,46 +567,46 @@ active() # ('langchain',) ``` - **`instrument("crewai")` su una macchina senza CrewAI non genera.** Registra un avviso e restituisce `()`, quindi un framework mancante non fa mai cadere un processo che strumenta anche altri. + **`instrument("crewai")` su una macchina senza CrewAI non solleva.** Registra un avviso e restituisce `()`, quindi un framework mancante non porta mai giù un processo che strumenta anche altri. - L'avviso porta il sottostante `ImportError`, e quel messaggio nomina il comando di installazione esatto — così la correzione è nei tuoi log, non nascosta. + L'avviso porta l'`ImportError` sottostante, e quel messaggio nomina il comando di installazione esatto — quindi la correzione è nei tuoi log, non nascosta. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Imposta `FAILPROOFAI_SDK_STRICT=1` affinché generi al contrario. Quel flag è letto **una sola volta e cachato**, quindi esportalo prima che il tuo processo inizi anziché impostarlo mid-run. + Imposta `FAILPROOFAI_SDK_STRICT=1` per farlo sollevare invece. Quel flag viene letto **una volta e cachato**, quindi esportalo prima che il tuo processo inizi piuttosto che impostarlo a metà esecuzione. - **`instrument()` deve venire *dopo* il tuo import del framework.** L'auto-rilevamento legge `sys.modules`, quindi una chiamata nuda sopra l'import trova nulla, installa nulla, e restituisce `()`. + **`instrument()` deve venire *dopo* l'importazione del tuo framework.** L'auto-rilevamento legge `sys.modules`, quindi una chiamata nuda sopra l'importazione non trova niente, non installa niente, e restituisce `()`. ```python Sbagliato import failproofai_sdk -failproofai_sdk.instrument() # sys.modules non ha langchain ancora -> () +failproofai_sdk.instrument() # sys.modules has no langchain yet -> () -import langchain # troppo tardi, nulla è cablato +import langchain # too late, nothing is wired ``` ```python Giusto -import langchain # importa il framework per primo +import langchain # import the framework first import failproofai_sdk -failproofai_sdk.instrument() # lo trova -> ('langchain',) +failproofai_sdk.instrument() # finds it -> ('langchain',) ``` -```python Giusto, order-proof +```python Giusto, a prova di ordine import failproofai_sdk -# Nominarlo importa l'adapter su richiesta, quindi questo funziona da qualsiasi parte. +# Naming it imports the adapter on request, so this works from anywhere. failproofai_sdk.instrument("langchain") ``` -Fai male e il processo viene eseguito con l'SDK importato, l'adapter apparentemente installato, e **nemmeno un evento emesso**. Registra un avviso dicendo esattamente quello — quindi controlla i tuoi log per primo quando un'esecuzione non registra nulla. +Sbaglialo e il processo gira con l'SDK importato, l'adapter apparentemente installato, e **non un evento emesso**. Registra un avviso dicendo esattamente questo — quindi controlla prima i tuoi log quando un'esecuzione non registra niente. @@ -614,85 +614,83 @@ Fai male e il processo viene eseguito con l'SDK importato, l'adapter apparenteme ```mermaid flowchart LR - A["Il tuo agente"] --> B["Adapter"] - B --> C["Writer
coda in-memoria"] - C -->|"ogni 0.5s"| D["Spool
JSONL su disco"] - D --> E["Daemon Failproof"] + A["Your agent"] --> B["Adapter"] + B --> C["Writer
in-memory queue"] + C -->|"every 0.5s"| D["Spool
JSONL on disk"] + D --> E["Failproof daemon"] E -->|"HTTPS"| F["Cloud"] ``` -| Fase | Compito | Eseguita in | +| Fase | Lavoro | Gira in | | --- | --- | --- | | Adapter | Traduce un callback del framework in uno dei 15 tipi di evento | Il tuo processo | -| Writer | Accoda, raggruppa, scrive JSONL atomicamente | Il tuo processo, thread di background | -| Spool | Consegna duratura, sopravvive all'uscita del tuo processo | Disco locale | -| Daemon | Guarda lo spool, spedisce batch, cancella quello che ha spedito | La tua macchina | -| Ingest | Assegna un id riga e dedup key, promuove colonne interrogabili | Cloud | +| Writer | Coda, batch, scrive JSONL atomicamente | Il tuo processo, thread di background | +| Spool | Consegna durabile, sopravvive all'uscita del tuo processo | Disco locale | +| Daemon | Osserva lo spool, spedisce i batch, cancella quello che ha spedito | La tua macchina | +| Ingest | Assegna un id di riga e chiave dedup, promuove colonne interrogabili | Cloud | -Lo spool è quello che rende questo sicuro: il tuo agente non si blocca mai sulla rete, e un'interruzione di Cloud significa una directory in crescita anziché eventi persi. +Lo spool è quello che rende questo sicuro: il tuo agente non blocca mai sulla rete, e un'interruzione di Cloud significa una directory in crescita piuttosto che eventi persi. -Ogni flush scrive un file batch, `.tmp` per primo, poi `fsync`, poi un rename atomico: +Ogni flush scrive un file batch, `.tmp` prima, poi `fsync`, poi una ridenominazione atomica: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Il daemon raccoglie solo `.jsonl`, quindi non può mai leggere un file scritto a metà. Lo stem porta un timestamp, id processo e numero di sequenza, quindi due processi che flushano nello stesso millisecondo non possono collisioni. La coda è limitata a 10.000 eventi; passato questo i più vecchi sono scartati e registrati. +Il daemon raccoglie solo `.jsonl`, quindi non può mai leggere un file mezzo scritto. Lo stem porta un timestamp, id processo e numero di sequenza, quindi due processi che fanno flush nello stesso millisecondo non possono collidere. La coda è limitata a 10.000 eventi; oltre quello cancella il più vecchio e registra. - **`collector.redact` non si applica ai tuoi eventi SDK.** Non li vede mai. + **`collector.redact` predefinisce a `minimal` anche per gli eventi SDK.** L'SDK scrappa prima di scrivere un batch su disco, e il daemon ripete lo stesso passaggio deterministico prima dell'upload così i batch da SDK più vecchi sono protetti. -Il daemon **spedisce** i tuoi batch. Non li apre o li riscrive. +Il daemon legge ogni batch e applica la redazione in memoria prima dell'upload. Non riscrittore il file spool che ha letto. -| Eventi | Scritti da | Redatti da `collector.redact`? | +| Eventi | Scritti da | Dove gira la redazione minima | | --- | --- | --- | -| Trascritti di sessione CLI | Il daemon | Sì | -| Attività hook | Il daemon | Sì | -| **Tutto ciò che l'SDK emette** | **Il tuo processo** | **No** | +| Trascritti di sessione CLI | Il daemon | Prima che il daemon scriva il batch | +| Attività hook | Il daemon | Prima che il daemon scriva il batch | +| **Tutto quello che emette l'SDK** | **Il tuo processo** | **Prima che l'SDK scriva il batch e di nuovo prima dell'upload del daemon** | -La redazione viene eseguita dove il daemon *scrive* i suoi propri eventi — non dove i batch sono *spediti*. Quindi un prompt o un argomento di strumento che tiene una chiave API ancora la tiene all'arrivo. - -È deliberato. Queste sono le tue stesse chiamate di strumentazione, e riscriverle in transito significherebbe che gli eventi che ricevi non sono gli eventi che hai emesso. +Imposta `collector.redact` su `off` solo quando i payload verbatim sono un requisito esplicito; sia l'SDK che il daemon onorano quell'impostazione. La redazione minima cattura chiavi API comuni, token bearer, JWT e assegnazioni segrete. Non può identificare prosa sensibile arbitraria. - **Controlli i payload alla sorgente, in due posti:** + **Controlli i payload alla fonte, in due posti:** - - Spegni la cattura di contenuto sull'adapter. **Il nome dell'opzione differisce, e un adapter non ne ha alcuno** — non è un singolo interruttore universale: + - Disattiva l'acquisizione di contenuti sull'adapter. **Il nome dell'opzione differisce, e un adapter non ne ha nessuno** — questo non è un singolo interruttore universale: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **nessuno switch di contenuto**; `session_id` è l'unica opzione che legge, quindi i prompt e i completamenti sono sempre registrati. + - CrewAI — **nessuno switch di contenuto**; `session_id` è l'unica opzione che legge, quindi i prompt e i completamenti vengono sempre registrati. - `instrument()` scarta le opzioni che un adapter non legge, quindi passare il nome sbagliato non genera nulla e non cambia nulla. + `instrument()` elimina le opzioni che un adapter non legge, quindi passare il nome sbagliato non solleva niente e non cambia niente. - Non consegnare il segreto a `input=` in primo luogo. - `collector.redact` non è un sostituto per nessuno dei due. + `collector.redact` è difesa in profondità, non un sostituto per nessuno dei due. - **Una directory spool vuota è lo stato salutistico.** Non usarla per controllare la consegna. + **Una directory spool vuota è lo stato sano.** Non usarla per controllare la consegna. -Il daemon cancella ogni batch entro millisecondi dalla sua spedizione, quindi un `ls` corre il collector e mostra una frazione di ciò che hai emesso — indistinguibile da un SDK che non ha registrato nulla. +Il daemon cancella ogni batch entro millisecondi dal suo invio, quindi un `ls` gara il collettore e mostra una frazione di quello che hai emesso — indistinguibile da un SDK che non ha registrato niente. -Per confermare che gli eventi effettivamente atterrano, controlla il dashboard. Per osservare lo spool riempirsi, ferma prima il daemon. +Per confermare che gli eventi sono effettivamente arrivati, controlla la dashboard. Per guardare lo spool riempirsi, ferma il daemon prima. -Ogni callback viene eseguito dentro un wrapper il cui unico compito è lanciare di nuovo, quindi la tua chiamata sta esattamente in un `try` e tutto ciò che l'SDK fa accade al di fuori di esso. +Ogni callback gira dentro un wrapper il cui unico lavoro è ri-sollevare, quindi la tua chiamata si trova in esattamente uno `try` e tutto quello che l'SDK fa accade fuori da esso. | Cosa succede | Risultato | | --- | --- | -| Un hook genera | Registrato una volta con il suo traceback. La tua chiamata non è interessata | -| Lo stesso hook genera tre volte | Quell'hook è disabilitato per il resto del processo, con una riga di errore | -| `FAILPROOFAI_SDK_STRICT=1` è impostato | L'eccezione è lanciata di nuovo al contrario | -| Una versione di framework è fuori dall'intervallo testato | Avvisa una volta, strumenta comunque | +| Un hook solleva | Registrato una volta con il suo traceback. La tua chiamata non è interessata | +| Lo stesso hook solleva tre volte | Quell'hook è disabilitato per il resto del processo, con una riga di errore | +| `FAILPROOFAI_SDK_STRICT=1` è impostato | L'eccezione viene ri-sollevata invece | +| Una versione del framework è fuori dall'intervallo testato | Avverte una volta, strumenta comunque | | Una singola capacità è mancante | Quell'hook è disabilitato, mai l'intero adapter | -Il default è giusto in produzione e sbagliato mentre esegui il debug, perché può solo mai provare "non è crashato". Imposta `FAILPROOFAI_SDK_STRICT=1` per rendere un fallimento ingoiato rumoroso. +L'impostazione predefinita è giusta in produzione e sbagliata durante il debug, perché può solo mai provare il non-crash. Imposta `FAILPROOFAI_SDK_STRICT=1` per rendere forte un fallimento ingoiato. @@ -702,27 +700,27 @@ Il default è giusto in produzione e sbagliato mentre esegui il debug, perché p - Un evento di apertura non ha uno di chiusura: un `model_request` senza `model_response`, o un `tool_use` senza `tool_result`. Usa gli ambiti, che garantiscono la coppia anche quando il corpo genera. Se chiami i metodi evento direttamente, usa `try` e `finally`. + Un evento di apertura non ha uno di chiusura: un `model_request` senza `model_response`, o un `tool_use` senza `tool_result`. Usa gli ambiti, che garantiscono la coppia anche quando il corpo solleva. Se chiami i metodi di evento direttamente, usa `try` e `finally`. - - È misurato dall'evento di apertura corrispondente, quindi è rifiutato su `tool_result`, `hook_completed`, `agent_resume`, e `human_input`. È accettato su `model_response`, perché solo tu conosci la vera latenza del provider, e deve essere un intero. + + Viene misurato dal suo evento di apertura corrispondente, quindi viene rifiutato su `tool_result`, `hook_completed`, `agent_resume`, e `human_input`. Viene accettato su `model_response`, perché solo tu conosci la vera latenza del provider, e deve essere un intero. - - Il thread non ha mai ereditato il contesto. Avvolgi il callable in `failproofai_sdk.propagate()`. Vedi [Thread e async](#thread-e-async). + + Il thread non ha mai ereditato il contesto. Avvolgi il callable in `failproofai_sdk.propagate()`. Vedi [Thread e async](#threads-and-async). - I campi extra si fondono ultimi, quindi uno denominato come un campo reale come `model` o `outcome` lo sovrascriverebbe e cambierebbe una colonna memorizzata. Spazianomina i tuoi; gli adapter usano un prefisso `fw_`. + I campi extra si uniscono per ultimo, quindi uno nominato come un campo reale come `model` o `outcome` lo sovrascrivererebbe e cambierebbe una colonna memorizzata. Usa uno spazio dei nomi; gli adapter usano un prefisso `fw_`. - `agent_id` è una sfaccettatura a bassa cardinalità e ci hai messo un id di esecuzione. Usa un nome di ruolo o nodo e metti l'id reale in un campo di payload. + `agent_id` è una facet a bassa cardinalità e tu hai messo un id di esecuzione in esso. Usa un ruolo o nome di nodo e metti l'id reale in un campo payload. -## Avanti +## Prossimo @@ -731,7 +729,7 @@ Il default è giusto in produzione e sbagliato mentre esegui il debug, perché p Segui la causalità attraverso la sessione che hai appena catturato. - + LangGraph, CrewAI, LlamaIndex, e Pydantic AI. \ No newline at end of file diff --git a/docs/ja/start/integrations/custom-agents.mdx b/docs/ja/start/integrations/custom-agents.mdx index 38782e56..9bbfe90b 100644 --- a/docs/ja/start/integrations/custom-agents.mdx +++ b/docs/ja/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "カスタムエージェント" sidebarTitle: "カスタムエージェント" -description: "自作のエージェント、またはアダプターのないフレームワークにインストルメンテーションを追加する。" +description: "自作のエージェントや、アダプターのないフレームワークをインストゥルメントします。" icon: "code" --- -自作のエージェント、またはFailproof AIがアダプターを提供していないフレームワーク向けの説明です。インストルメンテーションの設定は不要です。イベントを自分で送出するだけです。 +自作のエージェント、またはFailproof AIがアダプターを提供していないフレームワークを対象としています。インストゥルメントするものは何もありません。イベントを直接発行するだけです。 -これは、4つのフレームワークアダプターが内部で呼び出しているのと同じAPIです。それらのアダプターは、このAPIの変換テーブルにすぎません。 +これは4つのフレームワークアダプターが内部で呼び出しているAPIと同じです。アダプターはその上に構築された変換テーブルにすぎません。 ## インストール @@ -15,42 +15,42 @@ icon: "code" pip install failproofai-sdk ``` -追加パッケージも依存関係もありません。 +追加パッケージもなく、依存関係もありません。 -## インストルメンテーション +## インストゥルメント ```python import failproofai_sdk failproofai_sdk.configure(environment="production") -with failproofai_sdk.session(): # 1回の実行 - with failproofai_sdk.agent("planner"): # 1つの作業単位 +with failproofai_sdk.session(): # one run + with failproofai_sdk.agent("planner"): # one unit of work with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # 1回のツール呼び出し + t.output = search(q) # one tool call ``` -上から読んでいくと、その意味がそのまま伝わります： +上から下に読めば、そのまま意味がわかります： -| ラップする対象 | 意味 | +| スコープ | 意味 | | --- | --- | | `session()` | これらのイベントは同じ実行に属する | -| `agent()` | 何かが作業をしている — リストで認識できる名前を付ける | -| `tool_call()` | これは1つのツールであり、その返り値がここにある | +| `agent()` | 何かが作業を行っている — リストで認識できる名前を付ける | +| `tool_call()` | これは1つのツールで、返した結果がこれ | -各スコープが実際に送出するイベント： +各スコープが実際に発行するもの： -| スコープ | 送出するイベント | 目的 | +| スコープ | 発行するイベント | 用途 | | --- | --- | --- | | `session()` | なし | セッションIDをバインドし、1回の実行をグループ化する | -| `agent()` | `agent_start`、`agent_end` | 作業単位の前後を囲む | +| `agent()` | `agent_start`、`agent_end` | 作業単位を囲む | | `tool_call()` | `tool_use`、`tool_result` | 1つのツールを囲み、計測する | -スコープ内のコードは `session_id` や `agent_id` を省略できます。スコープはコンテキスト変数にIDをバインドし、すべてのイベント呼び出しがそこから読み取るため、関数にIDを引き回す必要はありません。 +内部では `session_id` と `agent_id` を省略できます。スコープはコンテキスト変数にIDをバインドし、すべてのイベント呼び出しがそれを参照するため、関数間でIDを引き回す必要はありません。 -3つのスコープはいずれも `async with` と `with` の両方で動作します。 +3つすべてが `async with` にも `with` にも対応しています。 -エージェントをネストするとツリーが構築されます。`parent_id` と深さはスタックから自動計算されます： +エージェントをネストするとツリーが構築されます。`parent_id` と深さはスタックから自動的に計算されます： ```python with failproofai_sdk.session(): @@ -59,35 +59,35 @@ with failproofai_sdk.session(): ... ``` -## スコープの終了方法 +## スコープのクローズ方法 -`agent()` は例外を自動で処理します： +`agent()` は例外を自動的に処理します： -| 発生したこと | イベント | 結果 | +| 状況 | イベント | 結果 | | --- | --- | --- | | 例外なし | `agent_end` | `success` | -| `Exception` | `error`、次に `agent_end` | `failed` | -| `KeyboardInterrupt`、`SystemExit` | `error`、次に `agent_end` | `failed` | +| `Exception` | `error`、その後 `agent_end` | `failed` | +| `KeyboardInterrupt`、`SystemExit` | `error`、その後 `agent_end` | `failed` | | `CancelledError`、`GeneratorExit` | `agent_end` のみ | `cancelled` | -エラーは `agent_end` の前に送出されます。これはダッシュボードが `agent_end` でスパンを閉じるため、それ以降に発生したイベントはどのスパンにも帰属しなくなるためです。キャンセルは失敗ではないため、キャンセルされた実行はエラーサーフェスを汚染しません。例外は常に再送出されます。スコープが例外を握りつぶすことはありません。 +エラーは `agent_end` の前に発行されます。ダッシュボードが `agent_end` でスパンを閉じるため、それ以降のものは何にも帰属されないからです。キャンセルは失敗ではないため、キャンセルされた実行はエラー画面を汚染しません。例外は必ず再スローされます。スコープが例外を飲み込むことはありません。 ## イベントメソッド -6つのファミリーに分類された15のメソッドがあります。ほとんどはペアで提供されます — オープナーを送出し、次にクローザーを送出すると、SDKがその間のスパンを計測します。 +6つのファミリーに分かれた15のメソッドです。ほとんどはペアで提供されます。開始側を発行し、次に終了側を発行すると、SDKがその間のスパンを計測します。 -| ファミリー | 開く | 閉じる | 単独 | +| ファミリー | 開始 | 終了 | 単独 | | --- | --- | --- | --- | | **エージェント** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | | **モデル** | `model_request` | `model_response` | — | | **ツール** | `tool_use` | `tool_result` | — | | **フック** | `hook_triggered` | `hook_completed` | — | -| **人間** | `human_wait` | `human_input` | `human_pause`、`human_interrupt` | +| **ヒューマン** | `human_wait` | `human_input` | `human_pause`、`human_interrupt` | | **失敗** | — | — | `error` | - 可能な限りスコープ — `agent()` と `tool_call()` — を優先してください。本体が例外を送出した場合でも、クローズイベントの送出を保証します。制御フローがネストされない場合（ヘルパー内のモデル呼び出しなど）は、これらのメソッドを直接使用してください。 + 制御フローがネストできる場合は、`agent()` や `tool_call()` などのスコープを優先してください。本体が例外を発生させても、クローズイベントが保証されます。ヘルパー内のモデル呼び出しなど、制御フローがネストしない場合は、これらのメソッドを直接使用してください。 @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **2つの人間ファミリーは方向が逆です。** + **2つのヒューマンファミリーは方向が逆です。** | メソッド | 意味 | | --- | --- | - | `human_wait` / `human_input` | **エージェントが人間に問いかけた** — 承認ゲート、確認のための質問 | - | `human_pause` / `human_interrupt` | **人間がエージェントに働きかけた** — 停止ボタン、オペレーターによる一時停止 | + | `human_wait` / `human_input` | **エージェントが人に尋ねた** — 承認ゲート、確認の質問 | + | `human_pause` / `human_interrupt` | **人がエージェントに作用した** — 停止ボタン、オペレーターによる一時停止 | - どのフレームワークも後者のペアを通知しないため、常に自分で送出する必要があります。 + フレームワークは後者のペアをシグナルしないため、常に自分で発行する必要があります。 - **モデル呼び出しを並行実行する場合は `request_id` を渡してください。** 指定しない場合、リクエストとレスポンスはエージェントごとの受信順にペアリングされます。並行呼び出しでは順序が保証されないため、各レスポンスが誤ったリクエストに紐付く可能性があります。 + **モデル呼び出しが並行して実行される場合は `request_id` を渡してください。** 指定しない場合、リクエストとレスポンスはエージェントごとの到着順にペアリングされ、並行呼び出しでは各レスポンスが誤ったリクエストに関連付けられます。 -## 使用例 +## 例 -エージェントフレームワークなしで、OpenAI APIに対してツール呼び出しループを実行する例： +エージェントフレームワークを使わず、OpenAI APIに対するツール呼び出しループの例： ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """1回のモデル呼び出し。ペアで囲む。""" + """One model call, bracketed by the pair.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # 上限あり。無制限のエージェントループはそれ自体がバグ + for _ in range(4): # bounded; an unbounded agent loop is its own bug message = turn(messages) if not message.tool_calls: break @@ -204,34 +204,34 @@ with failproofai_sdk.session(): }) ``` -これにより、アダプターが生成するのと同じ6種類のイベントタイプが生成されます。ツール定義を含む完全な実行可能バージョンは、SDKリポジトリの `docs/manual/examples/` に含まれています。 +これにより、アダプターが生成するものと同じ6種類のイベントタイプが生成されます。ツール定義を含む完全な実行可能バージョンは、SDKリポジトリの `docs/manual/examples/` に収録されています。 ## スレッドと非同期 -コンテキスト変数はasyncioタスクに自動的に伝播します。新しいスレッドには伝播しません。スレッドは空のコンテキストで開始されるためです。 +コンテキスト変数はasyncioタスクに自動的に伝播します。新しいスレッドには伝播しません。スレッドは空のコンテキストで開始するためです。 ```python -# asyncio: 特別な操作不要 +# asyncio: nothing to do async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# スレッド: callableをラップする +# threads: wrap the callable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -`propagate()` なしでは、ワーカーのイベントがセッションなしで着信する代わりに、修正方法を示す `TypeError` が発生します。これは意図的な設計です。セッションのないイベントはインジェスト側でスキップされつつ `200` が返されるため、無音の失敗となります。それを防ぐためにIDレイヤーが存在します。 +`propagate()` なしでは、ワーカーのイベントがセッションなしで着信する代わりに、修正方法を示す `TypeError` が発生します。これは意図的な設計です。セッションのないイベントはインジェスト時にスキップされ `200` が返されますが、それはIDレイヤーが防ごうとしているサイレントな失敗だからです。 -## アダプターのないフレームワークへのインストルメンテーション +## アダプターのないフレームワークをインストゥルメントする -どのエージェントフレームワークにも同じ3つの接合点があります。それらをマッピングすれば、完全なトレースが得られます — 4つの既存アダプターもこれ以上のことはしていません。 +どのエージェントフレームワークにも同じ3つのシームがあります。それらをマッピングすれば完全なトレースが得られます。出荷済みの4つのアダプターもこれ以上のことはしていません。 -| 接合点 | 書くコード | 記録されるイベント | +| シーム | 書くもの | 記録されるもの | | --- | --- | --- | | 実行 | `session()` + `agent()` | `agent_start`、`agent_end` | | 各ツール | `tool_call()` | `tool_use`、`tool_result` | -| 各モデル呼び出し | `model_*` のペア | `model_request`、`model_response` | +| 各モデル呼び出し | `model_*` ペア | `model_request`、`model_response` | @@ -242,7 +242,7 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` - フレームワークのツールラッパーまたはミドルウェアに相当する箇所に追加します。 + フレームワークがツールラッパーまたはミドルウェアと呼ぶものの中で。 ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -264,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **ノード、ステップ、ミドルウェア境界を可視化したい場合は？** ネストされた `agent()` ではなく、フックペア — `hook_triggered` / `hook_completed` — でラップしてください。`agent_id` は低カーディナリティのファセットであり、ノードごとに1エントリ追加するとすぐに埋め尽くされます。フックスパンは同様にレンダリングされ、ノードごとのレイテンシを確認できます。 + **確認する価値のあるノード、ステップ、ミドルウェアの境界がありますか？** ネストされた `agent()` ではなく、フックペア（`hook_triggered` / `hook_completed`）で囲んでください。`agent_id` は低カーディナリティのファセットで、ノードごとに1エントリあるとリストが溢れます。フックスパンは同じように表示され、ノードごとのレイテンシが確認できます。 - **手動計装と自動計装は組み合わせ可能です。** 手書きスコープ内で実行されるアダプターは、そのセッションに参加し、そのエージェントを親として設定します。2つのツリーではなく1つのツリーが得られるため、対応フレームワークと独自フレームワークを同時に計装する際に便利です。 + **手動と自動は組み合わせられます。** 手書きのスコープ内で実行するアダプターはそのセッションに参加し、そのエージェントの配下に入るため、2つのツリーではなく1つのツリーが得られます。サポート済みのフレームワークと並行して自分でインストゥルメントするときに便利です。 - - 2つの理由があります。上記の3つの接合点が、その両方に対する答えです： + + 2つの理由があり、上記の3つのシームがその両方に対する答えです： - `autogen-core` は2025年9月以降メンテナンスされていません。 - - AG2には他のフレームワークのフックに相当するプロセス全体の登録ポイントがないため、計装するにはすべての構築箇所でエージェントをラップする必要があります。 + - AG2は他のフレームワークのフックに相当するプロセス全体の登録ポイントを公開していないため、インストゥルメントするにはすべての構築サイトでエージェントをラップする必要があります。 - 接合点を手動でマッピングすることで、既存アダプターと同じイベントが同じ精度で記録されます。 + シームを手動でマッピングすることで、出荷済みアダプターと同じイベントを同じ精度で記録できます。 -## 詳細 +## より深く理解する -記録の実際の仕組みについて。始めるために必要な知識ではありません。 +記録の実際の仕組みです。始めるためには何も必要ありません。 - + -すべての記録は同じ形をしています。スパンが開き、その中に作業がネストされ、各オープンイベントに対応するクローズイベントがあります。 +すべての記録は同じ形をしています。スパンが開き、作業がその中にネストされ、各開始イベントに対応する終了イベントがあります。 ```mermaid flowchart LR @@ -300,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -**ペア**が基本単位です。各クローズイベントには、SDKがオープンイベントからの経過時間として計測したdurationが含まれます。 +**ペア**が基本単位です。各終了イベントには、対応する開始イベントからSDKが計測した期間が含まれます。 -以下は各フレームワークの実際の1回の実行 — SDKに同梱されているサンプルから取得、モデル名は正規化済み。1回の呼び出しでどれだけ多くの情報が返されるかに注目してください。 +以下はフレームワークごとの実際の1回の実行です。SDKに付属するサンプルからキャプチャし、モデル名を正規化しています。1回の呼び出しでどれだけ多くの情報が返ってくるかに注目してください。 @@ -323,7 +323,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - ノードがフックペアになるため、エージェントリストを埋め尽くすことなくノードごとのレイテンシを確認できます。 + ノードがフックペアになるため、エージェントリストを圧迫することなくノードごとのレイテンシが確認できます。 @@ -356,11 +356,11 @@ flowchart LR 13 +3.355s tool_use city_population 14 +3.355s tool_result city_population · ok 16 +3.356s hook_triggered aggregate_tool_results - ... 2回目のイテレーション + ... second iteration 26 +7.038s agent_end Agent · success ``` - エージェントループ自体が可視化され、モデル呼び出しだけでなくループ全体が見えます。 + モデル呼び出しだけでなく、エージェントループ自体が可視化されます。 @@ -375,7 +375,7 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - フックペアなし: Pydantic AIにはブラケットで囲むべきノードやステップ境界がありません。 + フックペアなし：Pydantic AIにはブラケットするノードやステップの境界がありません。 @@ -388,36 +388,36 @@ flowchart LR 6 +0.000s agent_end main · success ``` - これらを自分で送出します。同じイベントタイプ、同じ精度 — 呼び出し箇所を書くコストがかかります。 + これらは自分で発行します。同じイベントタイプ、同じ精度 — 呼び出しサイトのコストがかかります。 - + -**セッション終了イベントは存在しません。** セッションは閉じるものではなく、同じ `session_id` を共有するイベントのグループです。 +**セッション終了イベントはありません。** セッションはクローズするものではなく、`session_id` を共有するイベントのグループです。 -ステータスはトレースの形状から導出されます： +ステータスはトレースの形から導出されます： | ステータス | 条件 | | --- | --- | | `ongoing` | 少なくとも1つのスパンがまだ開いている | | `paused` | `agent_pause` に対応する `agent_resume` がない | -| `error` | 開いているスパンがなく、少なくとも1つのイベントが失敗した | -| `done` | 開いているスパンがなく、失敗もない | +| `error` | 開いているものがなく、少なくとも1つのイベントが失敗した | +| `done` | 開いているものがなく、失敗もない | -つまり、すべてのペアが閉じられるとセッションが終了します。アダプターは `agent_end` を自動送出し、テアダウン時にはまだ開いているものをすべて閉じてincompleteとしてマークします — クラッシュした実行は永遠にハングするのではなく、visible gapを持つ `done` として落ち着きます。 +つまり、すべてのペアが閉じられるとセッションが終了します。アダプターは `agent_end` を自動で発行し、ティアダウン時に残っているものをすべて閉じて不完全とマークします。クラッシュした実行は、永遠にハングするのではなく、可視ギャップのある `done` として落ち着きます。 - これが、1つのセッションが2回の呼び出しにまたがれる理由です。LangGraphの `interrupt()` は実行を一時停止し、ルートスパンを意図的に開いたままにします。再開する呼び出しがそれを閉じます。両方の呼び出しが1つのセッションです。 + これがセッションが2回の呼び出しにまたがれる理由です。LangGraphの `interrupt()` が実行を一時停止し、ルートスパンが意図的に開いたままになり、再開する呼び出しがそれを閉じます。両方の呼び出しが1つのセッションです。 - + -`session_id` と `agent_id` はすべてのイベントメソッドでオプションです。省略した場合、囲んでいるスコープから解決されます： +`session_id` と `agent_id` はすべてのイベントメソッドでオプションです。省略した場合、囲むスコープから解決されます： ```python with failproofai_sdk.session(): @@ -425,55 +425,55 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -明示的に渡すことも可能で、その場合は優先されます。何もバインドされておらず何も渡されない場合、セッションなしでイベントを送出する代わりに、修正方法を示す `TypeError` が発生します（インジェストはセッションなしのイベントをスキップしつつ `200` を返します）。 +明示的に渡すことも可能で、その場合は優先されます。何もバインドされておらず何も渡されていない場合、セッションなしのイベントを発行する代わりに（インジェストはそれをスキップして `200` を返します）、修正方法を示す `TypeError` が発生します。 -スコープはコンテキスト変数にIDをバインドします。asyncioタスクには自動的に伝播しますが、新しいスレッドには伝播しません — ワーカーを `failproofai_sdk.propagate()` でラップしてください。 +スコープはコンテキスト変数にIDをバインドします。それらはasyncioタスクには自動的に伝播しますが、新しいスレッドには伝播しません。ワーカーを `failproofai_sdk.propagate()` でラップしてください。 -#### どのIDを誰が発行するか +#### 誰がどのIDを生成するか -| ID | 発行者 | 備考 | +| ID | 生成者 | 備考 | | --- | --- | --- | -| `session_id` | ユーザー、またはSDK | `session("chat-42")` はそのまま使用される。省略時、SDKは `uuid4().hex` を生成する | -| `agent_id` | ユーザー、またはフレームワーク | `agent("analyst")`、CrewAIの `role`、`FunctionAgent.name` から。UUIDのような値は拒否されて置換される | -| `tool_call_id`、`hook_id`、`request_id` | ユーザー、またはフレームワーク | アダプターはフレームワーク独自の実行IDを再利用する。ペアがスレッドホップを越えて一致するのはそのためである | -| **イベントID** | **Cloud（インジェスト時）** | SDKは送出しない | -| **`dedup_key`** | **Cloud（インジェスト時）** | org、session、timestamp、type、payloadのハッシュ。これが実際のID — 再試行されたバッチが重複する代わりに折りたたまれる | +| `session_id` | あなた、またはSDK | `session("chat-42")` はそのまま使用される。省略した場合、SDKが `uuid4().hex` を生成する | +| `agent_id` | あなた、またはフレームワーク | `agent("analyst")`、CrewAIの `role`、`FunctionAgent.name` から。UUID形式の値は拒否されて置き換えられる | +| `tool_call_id`、`hook_id`、`request_id` | あなた、またはフレームワーク | アダプターはフレームワーク自身の実行IDを再利用するため、スレッドをまたいでもペアが維持される | +| **イベントID** | **クラウド、インジェスト時** | SDKは発行しない | +| **`dedup_key`** | **クラウド、インジェスト時** | org、セッション、タイムスタンプ、タイプ、ペイロードのハッシュ。これが本当のID — リトライされたバッチが重複する代わりに集約される | #### アダプターが `session_id` を解決する方法 -最初のマッチが優先されます： +最初にマッチしたものが使われます： 1. 明示的な `session_id` オプション 2. 呼び出しごとのメタデータ -3. 囲んでいる `session()` スコープ +3. 囲む `session()` スコープ 4. フレームワークのメタデータ -5. フレームワーク独自の実行ID +5. フレームワーク自身の実行ID -これらのいずれかが存在する間は、IDが新規生成されることはありません — 合成されたIDは1回の実行を複数のセッションに分割してしまうためです。 +これらのいずれかが存在する間は生成されません。合成されたIDは1つの実行を複数のセッションに分割してしまいます。 #### `agent_id` は低カーディナリティに保つ -すべてのダッシュボードサーフェスの主要ファセットであり、`LowCardinality(String)` カラムです。実行ごとの値を使用するとカラムが劣化し、フィルターのドロップダウンが実行1件につき1エントリで埋まります。 +これはすべてのダッシュボード画面の主要ファセットであり、`LowCardinality(String)` カラムです。実行ごとの値はカラムを劣化させ、フィルタードロップダウンを実行ごとの1エントリで埋めてしまいます。 アダプターはそのカラムを守ります： | フレームワークが渡す値 | 記録される値 | 理由 | | --- | --- | --- | -| `3f9a1c2b-…`（UUID） | `main` | 読める情報がない | -| 長い16進数文字列 | `main` | 同上 | -| `agent-3f9a1c2b-…` | `agent` | 実行IDを削除し、読める部分を保持 | -| `agent-v2` | `agent-v2` | 短いセグメントはそのまま残す | +| `3f9a1c2b-…`（UUID） | `main` | 読める部分がない | +| 長い生の16進数文字列 | `main` | 同上 | +| `agent-3f9a1c2b-…` | `agent` | 実行IDが除去され、読める部分が保持される | +| `agent-v2` | `agent-v2` | 短いセグメントはそのまま | | `step-3` | `step-3` | 同上 | -実際のIDは `fw_agent_id` / `fw_run_id` に保持されるため、ファセットにならずともクエリ可能です。 +実際のIDは `fw_agent_id` / `fw_run_id` に保持され、ファセットにならずにクエリ可能なままです。 - **このガードは*フレームワーク*が選んだラベルにのみ適用されます。** `event.*` や `failproofai_sdk.agent(...)` に自分で渡す `agent_id` は、渡したとおりに記録されます。明示的な引数を暗黙的に書き換えることは、防ごうとするカーディナリティの問題よりも悪いため、スパン名は適切に命名してください。 + **このガードは*フレームワーク*が選んだラベルにのみ適用されます。** `event.*` や `failproofai_sdk.agent(...)` に自分で渡す `agent_id` はそのまま記録されます。明示的な引数をサイレントに書き換えることは、それが防ぐカーディナリティ問題よりも悪いためです。自分のスパンには適切な名前を付けてください。 - + | グループ | イベント | | --- | --- | @@ -481,73 +481,73 @@ with failproofai_sdk.session(): | モデル | `model_request`、`model_response` | | ツール | `tool_use`、`tool_result` | | フック | `hook_triggered`、`hook_completed` | -| 人間 | `human_wait`、`human_input`、`human_pause`、`human_interrupt` | +| ヒューマン | `human_wait`、`human_input`、`human_pause`、`human_interrupt` | | 失敗 | `error` | -上記の実行から計測した、フレームワークごとの記録内容： +上記の実行から計測した、フレームワーク別の記録対象： | イベント | LangGraph | CrewAI | LlamaIndex | Pydantic AI | カスタム | | --- | :--: | :--: | :--: | :--: | :--: | -| エージェント開始・終了 | あり | あり | あり | あり | 自前 | -| モデルリクエスト・レスポンス | あり | あり | あり | あり | 自前 | -| ツール使用・結果 | あり | あり | あり | あり | 自前 | -| フックトリガー・完了 | ノード | タスク | ステップ | — | 自前 | -| エラー | あり | あり | あり | あり | 自動 | -| 人間の待機・入力 | あり | あり | あり | — | 自前 | -| エージェント一時停止・再開 | あり | あり | あり | — | 自前 | +| エージェント開始・終了 | Yes | Yes | Yes | Yes | あなた | +| モデルリクエスト・レスポンス | Yes | Yes | Yes | Yes | あなた | +| ツール使用・結果 | Yes | Yes | Yes | Yes | あなた | +| フックトリガー・完了 | Node | Task | Step | — | あなた | +| エラー | Yes | Yes | Yes | Yes | 自動 | +| ヒューマン待機・入力 | Yes | Yes | Yes | — | あなた | +| エージェント一時停止・再開 | Yes | Yes | Yes | — | あなた | -ダッシュはそのフレームワークにその概念がないことを意味します。`human_pause` と `human_interrupt` は*人間*がエージェントに働きかけることを表しており、どのフレームワークも通知しません — これらは自分で送出してください。 +ダッシュはフレームワークにそのような概念がないことを意味します。`human_pause` と `human_interrupt` は*人*がエージェントに作用することを表しており、どのフレームワークもシグナルしません。自分で発行してください。 - + -イベントは単独では届きません。1つがスパンを開き、1つが閉じます。クローズイベントには、SDKがオープンイベントからの経過時間として計測したdurationが含まれます。 +イベントは単独では届きません。1つが開き、1つが閉じ、終了イベントにはSDKが開始イベントから計測した期間が含まれます。 -| 開く | 閉じる | クローズイベントが持つ値 | +| 開始 | 終了 | 終了イベントが持つもの | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`、`summary` | -| `model_request` | `model_response` | トークン数、`stop_reason`、レイテンシ | -| `tool_use` | `tool_result` | `output` または `error`、duration | -| `hook_triggered` | `hook_completed` | `outcome`、duration | +| `model_request` | `model_response` | トークン、`stop_reason`、レイテンシ | +| `tool_use` | `tool_result` | `output` または `error`、期間 | +| `hook_triggered` | `hook_completed` | `outcome`、期間 | | `agent_pause` | `agent_resume` | 一時停止の継続時間 | -| `human_wait` | `human_input` | 回答、および人間が要した時間 | +| `human_wait` | `human_input` | 回答、および人が要した時間 | - クローズイベントのないオープンイベントは、永遠に終わらないスパンです。セッションはずっと実行中としてレンダリングされ、アクティブdurationが増え続けます。これは手動で計装する際に注意すべき失敗パターンです。 + 対応する終了イベントのない開始イベントは、永遠に終わらないスパンになります。セッションは永遠に実行中として表示され、アクティブな期間が増え続けます。これが手動インストゥルメント時に注意すべき失敗モードです。 #### 相関ルール -- マッチするクロージングイベントには同じ `tool_call_id`、`hook_id`、`pause_id`、または `input_id` を再利用してください。 +- マッチする完了イベントには同じ `tool_call_id`、`hook_id`、`pause_id`、または `input_id` を再利用してください。 - SDKは `tool_result`、`hook_completed`、`agent_resume`、`human_input` の `duration_ms` を計算します。これらのメソッドに渡すと `ValueError` が発生します。 -- `duration_ms` は `model_response` では**受け付けられます**。これは実際のプロバイダーレイテンシを知っているのが呼び出し側だけだからです。整数でなければなりません — floatを渡すと呼び出し箇所で `ValueError` が発生します（サーバーはそのカラムを符号なし32ビット整数として読み取るため、それ以外はNULLとして保存されます）。 -- 相関キーはkindとsessionでスコープされます。ツール呼び出しとフックは同じIDを安全に共有でき、2つの並行セッションは衝突なく同じIDを再利用できます。agentによるスコープはありません。あるエージェントで開かれ別のエージェントで閉じられたペアも相関します。これはマルチエージェントフレームワークでは通常のケースです。 -- `request_id` は `model_request` と `model_response` をペアリングします。指定しない場合、モデルイベントはエージェントごとの順序でペアリングされるため、並行呼び出しではペアが誤ります。 -- プロセスをまたいで分割されたペアはダウンストリームで相関しますが、SDKはプロセス内のdurationを計算できません。 -- ペンディングマップは最大10,000エントリを保持し、満杯になると最古のエントリを削除します。 +- `duration_ms` は `model_response` では**受け付けられます**。本当のプロバイダーレイテンシを知っているのは呼び出し元だけだからです。整数でなければなりません。浮動小数点数は呼び出しサイトで `ValueError` が発生します。サーバーはカラムを符号なし32ビット整数として読み取るため、それ以外はNULLとして格納されます。 +- 相関キーはKindとセッションでスコープされているため、ツール呼び出しとフックは安全にIDを共有でき、2つの並行セッションは同じIDを衝突なしに再利用できます。エージェントではスコープされません。あるエージェントで開かれ別のエージェントで閉じられたペアも相関します。これはマルチエージェントフレームワークでの通常のケースです。 +- `request_id` は `model_request` と `model_response` をペアにします。これなしでは、モデルイベントはエージェントごとの順序でペアリングされるため、並行呼び出しは誤ってペアリングされます。 +- プロセスをまたぐペアは下流で相関しますが、SDKはプロセス内の期間を計算できません。 +- ペンディングマップは最大10,000件の開始エントリを保持し、満杯になると最古のエントリを削除します。 - + -`failproofai-sdk` をインストールすると、4つのアダプターを含むすべてがインストールされます。extrasが引き込むのはアダプターではなく**フレームワーク**です。 +`failproofai-sdk` をインストールすると、4つのアダプターすべてを含むすべてのものがインストールされます。エクストラは**フレームワーク**を引き込むものであり、アダプターではありません。 ```python -import failproofai_sdk # 標準ライブラリ以外は何もロードしない -failproofai_sdk.instrument() # 実際に必要なアダプターのみインポートする +import failproofai_sdk # loads nothing outside the standard library +failproofai_sdk.instrument() # imports only the adapters you actually need ``` -`import failproofai_sdk` は契約上ゼロ依存であり、`--no-deps` でビルド済みwheelをインストールするテストと、どのフレームワークも `sys.modules` に到達しないことを証明するテストによって強制されます。 +`import failproofai_sdk` は契約上ゼロ依存です。ビルドされたwheelを `--no-deps` でインストールするテストと、フレームワークが `sys.modules` に到達しないことを証明するテストによって強制されています。 - `failproofai_sdk.crewai` という属性は存在しません。アダプターはトップレベルパッケージに意図的に公開されていません。属性アクセスの副作用としてフレームワークがインポートされ、ゼロ依存の約束が破られるためです。`instrument()` を使用してください。 + `failproofai_sdk.crewai` 属性はありません。アダプターはトップレベルパッケージに意図的に公開されていません。属性アクセスの副作用としてフレームワークがインポートされ、ゼロ依存の約束が破られるからです。`instrument()` を使用してください。 ```python -failproofai_sdk.instrument() # インポート済みのすべてのフレームワーク -failproofai_sdk.instrument("crewai") # 名前で1つだけ指定 -failproofai_sdk.uninstrument("crewai") # 元に戻す +failproofai_sdk.instrument() # every framework already imported +failproofai_sdk.instrument("crewai") # exactly one, by name +failproofai_sdk.uninstrument("crewai") # put it back ``` | 名前 | 別名 | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # 元に戻す | `llama_index` | `llamaindex`、`llama-index` | | `pydantic_ai` | `pydantic-ai`、`pydanticai` | -自動検出はインストール済みパッケージリストではなく `sys.modules` を読み取ります。インストールはしてあるがインポートしていないフレームワークは計装されず、代わりにインポートされることもありません。現在の状態を確認するには： +自動検出はインストール済みパッケージリストではなく `sys.modules` を読み取るため、インストール済みだがインポートしていないフレームワークはインストゥルメントされず、代わりにインポートされることもありません。接続されているものを確認するには： ```python from failproofai_sdk.integrations import active, available @@ -567,16 +567,16 @@ active() # ('langchain',) ``` - **CrewAIがインストールされていないマシンで `instrument("crewai")` を呼び出しても例外は発生しません。** 警告をログに記録して `()` を返すため、1つのフレームワークが欠けていても他を計装するプロセスが停止することはありません。 + **CrewAIのないマシンで `instrument("crewai")` を呼び出しても例外は発生しません。** 警告をログに記録して `()` を返すため、フレームワークが1つ欠けていても他のインストゥルメントをしているプロセスを停止させません。 - 警告には元の `ImportError` が含まれており、そのメッセージに正確なインストールコマンドが示されています — 修正方法はログに記録されており、隠されていません。 + 警告には根本的な `ImportError` が含まれており、そのメッセージには正確なインストールコマンドが記載されています。修正方法はログにあり、隠れていません。 ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - 代わりに例外を発生させるには `FAILPROOFAI_SDK_STRICT=1` を設定してください。このフラグは**一度だけ読み取られてキャッシュされます**。実行中に設定するのではなく、プロセス起動前にエクスポートしてください。 + `FAILPROOFAI_SDK_STRICT=1` を設定すると、代わりに例外が発生します。このフラグは**一度だけ読み取られてキャッシュされる**ため、プロセス実行中に設定するのではなく、プロセスが開始する前にエクスポートしてください。 @@ -586,113 +586,111 @@ active() # ('langchain',) ```python Wrong import failproofai_sdk -failproofai_sdk.instrument() # sys.modulesにlangchainがまだない -> () +failproofai_sdk.instrument() # sys.modules has no langchain yet -> () -import langchain # 遅すぎる。何もワイヤリングされない +import langchain # too late, nothing is wired ``` ```python Right -import langchain # 先にフレームワークをインポート +import langchain # import the framework first import failproofai_sdk -failproofai_sdk.instrument() # 検出される -> ('langchain',) +failproofai_sdk.instrument() # finds it -> ('langchain',) ``` ```python Right, order-proof import failproofai_sdk -# 名前を指定するとアダプターが要求時にインポートされるため、どこからでも動作する +# Naming it imports the adapter on request, so this works from anywhere. failproofai_sdk.instrument("langchain") ``` -これを誤ると、SDKがインポートされアダプターが一見インストールされているのに、**イベントが1件も送出されない**状態になります。ログにその旨の警告が記録されます — 実行が何も記録しない場合、まずログを確認してください。 +これを誤るとプロセスはSDKがインポートされ、アダプターが明らかにインストールされているにもかかわらず、**1つもイベントが発行されない**状態で動作します。まさにそれを示す警告がログに記録されます。実行が何も記録しない場合はまずログを確認してください。 - + ```mermaid flowchart LR - A["エージェント"] --> B["アダプター"] - B --> C["Writer
インメモリキュー"] - C -->|"0.5秒ごと"| D["Spool
ディスク上のJSONL"] - D --> E["Failproofデーモン"] + A["Your agent"] --> B["Adapter"] + B --> C["Writer
in-memory queue"] + C -->|"every 0.5s"| D["Spool
JSONL on disk"] + D --> E["Failproof daemon"] E -->|"HTTPS"| F["Cloud"] ``` | ステージ | 役割 | 実行場所 | | --- | --- | --- | -| アダプター | フレームワークのコールバックを15種類のイベントタイプに変換 | プロセス内 | -| Writer | キューに追加、バッチ化、JSONLをアトミックに書き込む | プロセス内（バックグラウンドスレッド） | -| Spool | 耐久性のある引き渡し。プロセス終了後も保存される | ローカルディスク | -| デーモン | Spoolを監視し、バッチを送信し、送信済みを削除する | マシン上 | -| インジェスト | 行IDとdedup keyを割り当て、クエリ可能なカラムに昇格させる | Cloud | +| アダプター | フレームワークのコールバックを15種類のイベントタイプのいずれかに変換する | あなたのプロセス | +| ライター | キューに入れ、バッチ処理し、JSONLをアトミックに書き込む | あなたのプロセス、バックグラウンドスレッド | +| スプール | 耐久性のあるハンドオフ。プロセスが終了しても生き残る | ローカルディスク | +| デーモン | スプールを監視し、バッチを送信し、送信済みのものを削除する | あなたのマシン | +| インジェスト | 行IDとdedupキーを割り当て、クエリ可能なカラムを昇格させる | クラウド | -Spoolがこれを安全にする理由です。エージェントはネットワークをブロックすることなく動作し、Cloudの障害は消失したイベントではなくディレクトリの増大として現れます。 +スプールがこれを安全にしています。エージェントがネットワークをブロックすることはなく、クラウドが停止してもイベントが失われる代わりにディレクトリが大きくなるだけです。 -各フラッシュは1つのバッチファイルを書き込みます。`.tmp` で書き始め、次に `fsync`、そしてアトミックリネームを行います： +各フラッシュは1つのバッチファイルを書き込みます。`.tmp` として書き込み、`fsync`、その後アトミックなリネームを行います： ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -デーモンは `.jsonl` のみを読み取るため、書き込み途中のファイルを読むことは決してありません。ファイル名にはタイムスタンプ、プロセスID、シーケンス番号が含まれるため、2つのプロセスが同じミリ秒にフラッシュしても衝突しません。キューの上限は10,000イベントで、それを超えると最古のものを削除してログに記録します。 +デーモンは `.jsonl` のみを読み取るため、半分書かれたファイルを読む可能性はありません。ステムにはタイムスタンプ、プロセスID、シーケンス番号が含まれているため、同じミリ秒にフラッシュする2つのプロセスが衝突することはありません。キューの上限は10,000イベントで、それを超えると最古のものをドロップしてログに記録します。 - **`collector.redact` はSDKイベントには適用されません。** SDKイベントは `collector.redact` の処理対象外です。 + **`collector.redact` はSDKイベントにもデフォルトで `minimal` が適用されます。** SDKはバッチをディスクに書き込む前にスクラブし、デーモンはアップロード前に同じ決定論的パスを繰り返します。これにより古いSDKからのバッチも保護されます。 -デーモンはバッチを**送信**します。バッチを開いたり書き換えたりしません。 +デーモンは各バッチを読み取り、アップロード前にメモリ内でリダクションを適用します。読み取ったスプールファイルを書き換えることはありません。 -| イベント | 書き込み者 | `collector.redact` による編集 | +| イベント | 書き込み元 | 最小リダクションの実行タイミング | | --- | --- | --- | -| CLIセッションのトランスクリプト | デーモン | あり | -| フックのアクティビティ | デーモン | あり | -| **SDKが送出するすべてのイベント** | **プロセス** | **なし** | +| CLIセッションのトランスクリプト | デーモン | デーモンがバッチを書き込む前 | +| フックアクティビティ | デーモン | デーモンがバッチを書き込む前 | +| **SDKが発行するすべてのもの** | **あなたのプロセス** | **SDKがバッチを書き込む前、およびデーモンのアップロード前** | -編集はデーモンが自身のイベントを*書き込む*場所で実行されます — バッチが*送信される*場所ではありません。そのため、APIキーを含むプロンプトやツール引数は、到着時もそのままの状態です。 - -これは意図的な設計です。これらはご自身の計装コールであり、送受信中に書き換えることは、送出したイベントと受け取るイベントが異なるものになることを意味します。 +逐語的なペイロードが明示的な要件である場合にのみ `collector.redact` を `off` に設定してください。SDKとデーモンの両方がその設定を尊重します。最小リダクションは一般的なAPIキー、ベアラートークン、JWT、シークレットの代入をキャッチします。任意の機密テキストを識別することはできません。 - **ペイロードはソースの2箇所で制御できます：** + **ペイロードはソースで2か所制御できます：** - - アダプターでコンテンツキャプチャを無効にする。**オプション名はアダプターによって異なり、対応していないアダプターもあります** — 共通の単一スイッチではありません： + - アダプターのコンテンツキャプチャをオフにする。**オプション名は異なり、コンテンツスイッチのないアダプターもあります** — これは単一の汎用スイッチではありません： - LangChain / LangGraph、Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **コンテンツスイッチなし**。読み取るオプションは `session_id` のみのため、プロンプトと補完は常に記録されます。 + - CrewAI — **コンテンツスイッチなし**。読み取るオプションは `session_id` のみで、プロンプトと補完は常に記録されます。 - `instrument()` はアダプターが読み取らないオプションを無視するため、誤った名前を渡しても何も起きず、何も変わりません。 + `instrument()` はアダプターが読み取らないオプションをドロップするため、誤った名前を渡しても例外は発生せず、何も変わりません。 - そもそもシークレットを `input=` に渡さない。 - `collector.redact` はどちらの代替手段にもなりません。 + `collector.redact` は多層防御であり、どちらかの代替ではありません。 - **Spoolディレクトリが空の状態が正常です。** 配信確認のために使用しないでください。 + **スプールディレクトリが空なのが正常な状態です。** 配信確認にそれを使わないでください。 -デーモンは送信後数ミリ秒以内に各バッチを削除するため、`ls` はコレクターと競合し、実際に送出したイベントのごく一部しか表示されません — 何も記録していないSDKと区別がつきません。 +デーモンは送信から数ミリ秒以内に各バッチを削除するため、`ls` はコレクターと競合し、実際に発行したもののごく一部しか表示されません。これは何も記録していないSDKと区別がつきません。 -イベントが実際に届いたかどうかはダッシュボードで確認してください。Spoolが埋まる様子を観察するには、先にデーモンを停止してください。 +イベントが実際に届いたことを確認するにはダッシュボードを確認してください。スプールが満たされるのを見るにはまずデーモンを停止してください。 - + -すべてのコールバックは再送出のみを行うラッパー内で実行されます。コードは1つの `try` の中に置かれ、SDKが行うすべての処理はその外側で実行されます。 +すべてのコールバックは、再スローすることだけが役割のラッパー内で実行されます。呼び出しは正確に1つの `try` の中にあり、SDKが行うすべてのことはその外で行われます。 -| 発生したこと | 結果 | +| 状況 | 結果 | | --- | --- | -| フックが例外を送出した | トレースバック付きで1回ログに記録される。コードは影響を受けない | -| 同じフックが3回例外を送出した | そのフックはプロセスの残り時間中無効化され、1行のエラーログが記録される | -| `FAILPROOFAI_SDK_STRICT=1` が設定されている | 代わりに例外が再送出される | -| フレームワークのバージョンがテスト済み範囲外 | 1回警告が出されるが、計装は続行される | -| 1つの機能が欠けている | そのフックのみ無効化される。アダプター全体は無効化されない | +| フックが例外を発生させる | トレースバック付きで1回ログに記録される。呼び出しへの影響なし | +| 同じフックが3回例外を発生させる | そのフックはプロセスの残りの間無効化され、エラー行が1つ記録される | +| `FAILPROOFAI_SDK_STRICT=1` が設定されている | 例外が代わりに再スローされる | +| フレームワークのバージョンがテスト済み範囲外 | 1回警告し、インストゥルメントを続行する | +| 単一の機能が欠けている | そのフックのみ無効化され、アダプター全体ではない | -デフォルトは本番環境では適切ですが、デバッグ時には不適切です。「クラッシュしなかった」ことしか証明できないためです。隠れた失敗を顕在化させるには `FAILPROOFAI_SDK_STRICT=1` を設定してください。 +デフォルトは本番では正しく、デバッグ中は誤りです。「クラッシュしなかった」ことしか証明できないからです。`FAILPROOFAI_SDK_STRICT=1` を設定して、飲み込まれた失敗を顕在化させてください。 @@ -701,24 +699,24 @@ Spoolがこれを安全にする理由です。エージェントはネットワ ## よくある問題 - - オープンイベントに対応するクローズイベントがありません。`model_request` に `model_response` がない、または `tool_use` に `tool_result` がない状態です。スコープを使用してください。本体が例外を送出した場合でもペアが保証されます。イベントメソッドを直接呼び出す場合は `try` と `finally` を使用してください。 + + 開始イベントに対応する終了イベントがありません。`model_request` に `model_response` がない、または `tool_use` に `tool_result` がない場合です。本体が例外を発生させてもペアを保証するスコープを使用してください。イベントメソッドを直接呼び出す場合は `try` と `finally` を使用してください。 - - `tool_result`、`hook_completed`、`agent_resume`、`human_input` では、対応するオープンイベントからの経過時間として計測されるため拒否されます。`model_response` では受け付けられます。実際のプロバイダーレイテンシを知っているのが呼び出し側だけだからです。整数でなければなりません。 + + これは対応する開始イベントから計測されるため、`tool_result`、`hook_completed`、`agent_resume`、`human_input` では拒否されます。本当のプロバイダーレイテンシを知っているのは呼び出し元だけであるため、`model_response` では受け付けられます。整数でなければなりません。 - - スレッドがコンテキストを継承していません。callableを `failproofai_sdk.propagate()` でラップしてください。[スレッドと非同期](#threads-and-async) を参照してください。 + + スレッドがコンテキストを継承しませんでした。呼び出し可能オブジェクトを `failproofai_sdk.propagate()` でラップしてください。[スレッドと非同期](#threads-and-async)を参照してください。 - - 追加フィールドは最後にマージされます。`model` や `outcome` など実際のフィールドと同じ名前を使用すると上書きされ、保存されるカラムが変わります。独自フィールドには名前空間を付けてください。アダプターは `fw_` プレフィックスを使用しています。 + + 追加フィールドは最後にマージされるため、`model` や `outcome` などの実際のフィールドと同じ名前のものはそれを上書きし、格納されるカラムを変更します。独自のものには名前空間を付けてください。アダプターは `fw_` プレフィックスを使用しています。 - - `agent_id` は低カーディナリティのファセットですが、実行IDを設定しています。ロール名やノード名を使用し、実際のIDはペイロードフィールドに格納してください。 + + `agent_id` は低カーディナリティのファセットで、実行IDが入っています。ロール名またはノード名を使用し、実際のIDはペイロードフィールドに入れてください。 @@ -726,10 +724,10 @@ Spoolがこれを安全にする理由です。エージェントはネットワ - ペア、ID、セッションのライフサイクル、配信の詳細。 + ペア、ID、セッションライフサイクル、配信について。 - 記録したセッションの因果関係をたどる。 + キャプチャしたセッションを通じて因果関係を追う。 LangGraph、CrewAI、LlamaIndex、Pydantic AI。 diff --git a/docs/ko/start/integrations/custom-agents.mdx b/docs/ko/start/integrations/custom-agents.mdx index 4fea8d3c..38ab23b7 100644 --- a/docs/ko/start/integrations/custom-agents.mdx +++ b/docs/ko/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "커스텀 에이전트" sidebarTitle: "커스텀 에이전트" -description: "직접 작성한 에이전트나 어댑터가 없는 프레임워크에 계측을 적용하세요." +description: "직접 작성한 에이전트 또는 어댑터가 없는 프레임워크를 계측합니다." icon: "code" --- -직접 작성한 에이전트나 Failproof AI에 어댑터가 없는 프레임워크에 사용합니다. 별도로 계측할 것은 없습니다. 이벤트를 직접 발행하면 됩니다. +직접 작성한 에이전트 또는 Failproof AI에 어댑터가 없는 프레임워크에 적합합니다. 별도로 계측할 것은 없습니다. 이벤트를 직접 발행하면 됩니다. -이는 네 가지 프레임워크 어댑터가 내부적으로 호출하는 것과 동일한 API입니다. 어댑터들은 이 API에 대한 변환 테이블입니다. +이 API는 네 가지 프레임워크 어댑터가 내부적으로 호출하는 것과 동일합니다. 어댑터들은 이 API 위에 구현된 변환 테이블입니다. ## 설치 @@ -27,30 +27,30 @@ failproofai_sdk.configure(environment="production") with failproofai_sdk.session(): # 하나의 실행 with failproofai_sdk.agent("planner"): # 하나의 작업 단위 with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # 하나의 도구 호출 + t.output = search(q) # 하나의 툴 호출 ``` -위에서 아래로 읽으면 그 의미가 그대로 드러납니다: +위에서 아래로 읽으면 의미가 그대로 드러납니다: | 감싸는 것 | 의미 | | --- | --- | -| `session()` | 이 이벤트들은 동일한 실행에 속합니다 | -| `agent()` | 무언가 작업을 수행하고 있습니다 — 목록에서 알아볼 수 있는 이름을 붙이세요 | -| `tool_call()` | 이것은 하나의 도구이며, 반환한 값입니다 | +| `session()` | 이 이벤트들은 동일한 실행에 속함 | +| `agent()` | 무언가가 작업 중 — 목록에서 알아볼 수 있는 이름을 부여 | +| `tool_call()` | 하나의 툴이며 반환값이 이것 | 각각이 실제로 발행하는 이벤트: | 스코프 | 발행 이벤트 | 목적 | | --- | --- | --- | -| `session()` | 없음 | 세션 id를 바인딩하여 하나의 실행을 그룹화합니다 | -| `agent()` | `agent_start`, `agent_end` | 작업 단위를 괄호로 묶습니다 | -| `tool_call()` | `tool_use`, `tool_result` | 하나의 도구를 괄호로 묶고 측정합니다 | +| `session()` | 없음 | 세션 id를 바인딩하여 하나의 실행을 그룹화 | +| `agent()` | `agent_start`, `agent_end` | 작업 단위를 괄호로 묶음 | +| `tool_call()` | `tool_use`, `tool_result` | 하나의 툴을 괄호로 묶고 측정 | -내부의 모든 코드는 `session_id`와 `agent_id`를 생략할 수 있습니다. 스코프는 컨텍스트 변수에 식별자를 바인딩하며, 모든 이벤트 호출이 이를 읽어오므로 함수를 통해 id를 전달할 필요가 없습니다. +내부의 모든 것은 `session_id`와 `agent_id`를 생략할 수 있습니다. 스코프가 컨텍스트 변수에 id를 바인딩하고 모든 이벤트 호출이 이를 읽어오므로, 함수에 id를 직접 전달할 필요가 없습니다. 세 가지 모두 `with`뿐만 아니라 `async with`에서도 동작합니다. -에이전트를 중첩하면 트리가 만들어집니다. `parent_id`와 깊이는 스택에서 자동으로 계산됩니다: +에이전트를 중첩하면 트리가 만들어집니다. `parent_id`와 깊이는 스택에서 계산됩니다: ```python with failproofai_sdk.session(): @@ -59,35 +59,35 @@ with failproofai_sdk.session(): ... ``` -## 스코프가 닫히는 방식 +## 스코프 종료 방식 `agent()`는 예외를 자동으로 처리합니다: -| 발생한 상황 | 이벤트 | 결과 | +| 상황 | 이벤트 | 결과 | | --- | --- | --- | | 예외 없음 | `agent_end` | `success` | | `Exception` | `error`, 이후 `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, 이후 `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | `agent_end`만 | `cancelled` | -`agent_end` 이전에 오류가 발행되는 이유는, 대시보드가 `agent_end`에서 스팬을 닫고 그 이후의 이벤트는 아무것에도 귀속되지 않기 때문입니다. 취소는 실패가 아니므로 취소된 실행은 오류 목록을 오염시키지 않습니다. 예외는 항상 다시 발생됩니다. 스코프는 예외를 삼키지 않습니다. +오류는 `agent_end` 이전에 발행됩니다. 대시보드가 `agent_end`에서 스팬을 닫기 때문에 그 이후의 이벤트는 귀속 대상이 없어지기 때문입니다. 취소는 실패가 아니므로 취소된 실행은 오류 목록을 오염시키지 않습니다. 예외는 항상 다시 발생합니다. 스코프는 절대 예외를 삼키지 않습니다. ## 이벤트 메서드 -여섯 가지 계열에 걸쳐 열다섯 가지 메서드가 있습니다. 대부분은 쌍으로 이루어져 있으며, 여는 이벤트를 발행한 뒤 닫는 이벤트를 발행하면 SDK가 그 사이의 스팬을 측정합니다. +6개 패밀리, 15개 메서드. 대부분 쌍으로 구성되어 있으며 — 시작 이벤트를 발행한 후 종료 이벤트를 발행하면 SDK가 그 사이의 스팬을 측정합니다. -| 계열 | 여는 이벤트 | 닫는 이벤트 | 단독 이벤트 | +| 패밀리 | 시작 | 종료 | 단독 | | --- | --- | --- | --- | | **에이전트** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | | **모델** | `model_request` | `model_response` | — | -| **도구** | `tool_use` | `tool_result` | — | +| **툴** | `tool_use` | `tool_result` | — | | **훅** | `hook_triggered` | `hook_completed` | — | -| **사람** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **휴먼** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | | **실패** | — | — | `error` | - 가능하면 `agent()`와 `tool_call()` 스코프를 사용하세요. 본문에서 예외가 발생해도 닫는 이벤트를 보장합니다. 제어 흐름이 중첩되지 않는 경우, 예를 들어 헬퍼 함수 내부의 모델 호출처럼 스코프가 맞지 않을 때는 이벤트 메서드를 직접 사용하세요. + 가능한 곳에서는 스코프 — `agent()`와 `tool_call()` — 를 사용하세요. 본문에서 예외가 발생하더라도 종료 이벤트를 보장합니다. 모델 호출이 헬퍼 내부에 있는 것처럼 제어 흐름이 중첩되지 않을 때에만 이 메서드들을 직접 사용하세요. @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **두 가지 사람 관련 계열은 방향이 반대입니다.** + **두 휴먼 패밀리는 방향이 반대입니다.** | 메서드 | 의미 | | --- | --- | - | `human_wait` / `human_input` | **에이전트가 사람에게 요청** — 승인 게이트, 확인 질문 | - | `human_pause` / `human_interrupt` | **사람이 에이전트에 개입** — 중지 버튼, 운영자 일시 정지 | + | `human_wait` / `human_input` | **에이전트가 사람에게 요청** — 승인 게이트, 명확화 질문 | + | `human_pause` / `human_interrupt` | **사람이 에이전트에 개입** — 중지 버튼, 운영자 일시정지 | - 두 번째 쌍은 어떤 프레임워크도 신호를 보내지 않으므로, 항상 직접 발행해야 합니다. + 어떤 프레임워크도 두 번째 쌍을 신호로 보내지 않으므로 항상 직접 발행해야 합니다. - **모델 호출이 동시에 실행될 때는 `request_id`를 전달하세요.** 전달하지 않으면 에이전트별로 요청과 응답이 도착 순서대로 쌍을 이루기 때문에, 동시 호출 시 잘못된 요청에 응답이 연결될 수 있습니다. + **모델 호출이 동시에 실행될 때는 `request_id`를 전달하세요.** 없으면 에이전트별 도착 순서대로 요청과 응답이 쌍을 이루어 동시 호출 시 잘못된 쌍이 만들어집니다. -## 예시 +## 예제 -에이전트 프레임워크 없이 OpenAI API를 사용하는 도구 호출 루프: +에이전트 프레임워크 없이 OpenAI API를 사용하는 툴 호출 루프: ```python import json @@ -204,52 +204,52 @@ with failproofai_sdk.session(): }) ``` -이 코드는 어댑터가 생성하는 것과 동일한 여섯 가지 이벤트 타입을 생성합니다. 도구 정의를 포함한 완전히 실행 가능한 버전은 SDK 저장소의 `docs/manual/examples/` 경로에 포함되어 있습니다. +이 코드는 어댑터가 생성하는 것과 동일한 6가지 이벤트 타입을 만들어냅니다. 툴 정의가 포함된 실행 가능한 전체 버전은 SDK 저장소의 `docs/manual/examples/`에 있습니다. ## 스레드와 비동기 -컨텍스트 변수는 asyncio 태스크에 자동으로 전파됩니다. 하지만 새 스레드는 빈 컨텍스트로 시작하기 때문에 스레드로는 자동 전파되지 않습니다. +컨텍스트 변수는 asyncio 태스크에 자동으로 전파됩니다. 스레드는 빈 컨텍스트로 시작하기 때문에 새 스레드에는 전파되지 않습니다. ```python -# asyncio: 별도 작업 불필요 +# asyncio: 별도 처리 불필요 async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# 스레드: callable을 감쌀 것 +# threads: callable을 감싸기 pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -`propagate()`를 사용하지 않으면, 워커의 이벤트는 세션 없이 처리되는 대신 수정 방법을 알려주는 `TypeError`를 발생시킵니다. 이는 의도적인 동작입니다. 세션이 없는 이벤트는 인제스트에서 건너뛰어지고 `200`으로 응답되는데, 이는 식별자 레이어가 방지하려는 무음 실패이기 때문입니다. +`propagate()`를 사용하지 않으면 워커의 이벤트가 세션 없이 전달되는 대신, 수정 방법을 알려주는 `TypeError`가 발생합니다. 이는 의도적인 동작입니다. 세션이 없는 이벤트는 인제스트에서 건너뛰고 `200`으로 응답하는데, 이것이 바로 id 레이어가 방지하고자 하는 조용한 실패이기 때문입니다. ## 어댑터 없이 프레임워크 계측하기 -모든 에이전트 프레임워크는 동일한 세 가지 연결 지점을 제공합니다. 이를 매핑하면 완전한 트레이스를 얻을 수 있습니다. 출시된 네 가지 어댑터도 이것 이상을 하지 않습니다. +모든 에이전트 프레임워크는 동일한 세 가지 접합점을 제공합니다. 이것들을 매핑하면 완전한 트레이스를 얻을 수 있습니다 — 제공되는 네 가지 어댑터도 이것 이상을 하지 않습니다. -| 연결 지점 | 작성할 코드 | 생성되는 이벤트 | +| 접합점 | 작성 내용 | 기록되는 것 | | --- | --- | --- | | 실행 | `session()` + `agent()` | `agent_start`, `agent_end` | -| 각 도구 | `tool_call()` | `tool_use`, `tool_result` | +| 각 툴 | `tool_call()` | `tool_use`, `tool_result` | | 각 모델 호출 | `model_*` 쌍 | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - 프레임워크에서 도구 래퍼나 미들웨어라고 부르는 곳에서 처리합니다. + + 프레임워크에서 툴 래퍼 또는 미들웨어라고 부르는 곳에서. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -264,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **노드, 스텝, 미들웨어 경계를 추적하고 싶다면?** 중첩된 `agent()` 대신 훅 쌍(`hook_triggered` / `hook_completed`)으로 감싸세요. `agent_id`는 저기수성 패싯이라 노드마다 항목이 생기면 목록이 넘쳐납니다. 훅 스팬은 동일하게 렌더링되면서 노드별 레이턴시를 제공합니다. + **노드, 스텝 또는 미들웨어 경계를 확인하고 싶다면?** 중첩된 `agent()` 대신 훅 쌍 — `hook_triggered` / `hook_completed` — 으로 감싸세요. `agent_id`는 카디널리티가 낮은 패싯이며 노드마다 하나씩 항목을 만들면 이를 가득 채웁니다. 훅 스팬은 동일한 방식으로 렌더링되고 노드별 레이턴시를 제공합니다. - **수동 계측과 자동 계측은 함께 동작합니다.** 직접 작성한 스코프 안에서 실행되는 어댑터는 해당 세션에 참여하고 해당 에이전트의 하위에 위치하므로, 두 개의 트리가 아닌 하나의 트리를 얻을 수 있습니다. 지원되는 프레임워크와 함께 다른 프레임워크를 직접 계측할 때 유용합니다. + **수동 계측과 자동 계측은 함께 사용할 수 있습니다.** 직접 작성한 스코프 내에서 실행되는 어댑터는 해당 세션에 합류하고 해당 에이전트의 자식이 되므로, 두 개의 트리가 아닌 하나의 트리를 얻을 수 있습니다 — 지원되는 프레임워크와 함께 하나의 프레임워크를 직접 계측할 때 유용합니다. - 두 가지 이유가 있으며, 위의 세 가지 연결 지점이 두 경우 모두에 대한 답입니다: + 두 가지 이유가 있으며, 위의 세 가지 접합점이 그 답입니다: - - `autogen-core`는 2025년 9월 이후 유지 관리가 중단되었습니다. - - AG2는 다른 프레임워크들의 훅에 해당하는 프로세스 수준의 등록 지점을 제공하지 않기 때문에, 계측하려면 에이전트를 생성하는 모든 위치에서 래핑해야 합니다. + - `autogen-core`는 2025년 9월부터 유지보수가 중단되었습니다. + - AG2는 다른 프레임워크의 훅에 상응하는 프로세스 전체 등록 지점을 노출하지 않아, 계측하려면 모든 생성 지점에서 각 에이전트를 감싸야 합니다. - 연결 지점을 직접 매핑하면 출시된 어댑터와 동일한 이벤트를, 동일한 정밀도로 기록할 수 있습니다. + 접합점을 직접 매핑하면 제공되는 어댑터와 동일한 이벤트를 동일한 정밀도로 기록할 수 있습니다. ## 더 깊이 알아보기 -레코딩이 실제로 동작하는 방식입니다. 시작하는 데 필요한 내용은 아닙니다. +기록이 실제로 어떻게 동작하는지. 시작하는 데는 필요하지 않습니다. - + -모든 레코딩은 동일한 형태를 가집니다. 스팬이 열리고, 그 안에 작업이 중첩되며, 각 열린 이벤트에 닫는 이벤트가 생깁니다. +모든 기록은 동일한 형태를 가집니다: 스팬이 열리고, 작업이 그 안에 중첩되고, 각 시작 이벤트에 종료 이벤트가 대응됩니다. ```mermaid flowchart LR @@ -300,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -**쌍**이 기본 단위입니다. 각 닫는 이벤트는 SDK가 여는 이벤트부터 측정한 지속 시간을 가집니다. +**쌍**이 기본 단위입니다. 각 종료 이벤트는 SDK가 시작 이벤트로부터 측정한 지속 시간을 포함합니다. -아래는 프레임워크별 실제 실행 결과입니다. SDK와 함께 제공되는 예시에서 캡처했으며 모델 이름은 정규화했습니다. 단 한 번의 호출에서 얼마나 많은 정보가 반환되는지 확인해 보세요. +아래는 프레임워크별 실제 실행 하나를 캡처한 것입니다 — SDK와 함께 제공되는 예제에서 가져왔으며 모델 이름은 정규화되었습니다. 단일 호출에서 얼마나 많은 정보가 반환되는지 확인하세요. @@ -323,7 +323,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - 노드가 훅 쌍이 되므로, 에이전트 목록을 복잡하게 만들지 않고도 노드별 레이턴시를 얻을 수 있습니다. + 노드가 훅 쌍이 되므로 에이전트 목록을 채우지 않고도 노드별 레이턴시를 얻을 수 있습니다. @@ -340,7 +340,7 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - 각 에이전트의 `role`이 스팬 이름이 되므로, 레이턴시와 토큰 사용량을 역할별로 분석할 수 있습니다. + 각 에이전트의 `role`이 스팬 이름이 되므로 레이턴시와 토큰 사용량을 역할별로 분석할 수 있습니다. @@ -360,7 +360,7 @@ flowchart LR 26 +7.038s agent_end Agent · success ``` - 에이전트 루프 자체가 보이며, 모델 호출만 보이는 것이 아닙니다. + 에이전트 루프 자체가 보이며, 모델 호출만이 아닙니다. @@ -388,36 +388,36 @@ flowchart LR 6 +0.000s agent_end main · success ``` - 직접 발행합니다. 동일한 이벤트 타입, 동일한 정밀도 — 호출 위치를 직접 작성하는 비용이 있습니다. + 이것들을 직접 발행합니다. 동일한 이벤트 타입, 동일한 정밀도 — 호출 지점의 코드 작성이 필요합니다. - + -**세션 종료 이벤트는 없습니다.** 세션은 닫는 것이 아니라, `session_id`를 공유하는 이벤트들의 그룹입니다. +**세션 종료 이벤트는 없습니다.** 세션은 닫는 것이 아니라 `session_id`를 공유하는 이벤트들의 그룹입니다. 상태는 트레이스의 형태에서 도출됩니다: | 상태 | 조건 | | --- | --- | | `ongoing` | 적어도 하나의 스팬이 아직 열려 있음 | -| `paused` | `agent_pause`에 대응하는 `agent_resume`이 없음 | -| `error` | 열린 스팬이 없고, 적어도 하나의 이벤트가 실패함 | -| `done` | 열린 스팬이 없고, 실패한 이벤트도 없음 | +| `paused` | `agent_pause`에 매칭되는 `agent_resume`가 없음 | +| `error` | 열린 것이 없고 최소 하나의 이벤트가 실패함 | +| `done` | 열린 것이 없고 실패한 것도 없음 | -즉, 모든 쌍이 닫히면 세션이 종료됩니다. 어댑터는 `agent_end`를 자동으로 발행하며, 종료 시 아직 열려 있는 것들을 닫고 불완전으로 표시합니다. 충돌한 실행은 보이는 공백과 함께 `done`으로 정리되며 영원히 대기 상태로 남지 않습니다. +따라서 모든 쌍이 닫히면 세션이 종료됩니다. 어댑터는 `agent_end`를 자동으로 발행하며, 종료 시 아직 열려 있는 것은 모두 닫고 불완전으로 표시합니다 — 충돌한 실행은 영원히 걸리는 것이 아니라 눈에 보이는 갭과 함께 `done`으로 처리됩니다. - 이것이 세션이 두 번의 호출에 걸쳐 있을 수 있는 이유입니다. LangGraph의 `interrupt()`는 실행을 일시 정지하고, 루트 스팬은 의도적으로 열린 상태를 유지하며, 재개하는 호출이 그것을 닫습니다. 두 호출은 하나의 세션입니다. + 이것이 세션이 두 번의 호출에 걸쳐 있을 수 있는 이유입니다. LangGraph의 `interrupt()`가 실행을 일시 중지하면 루트 스팬은 의도적으로 열려 있고, 재개 호출이 이를 닫습니다. 두 호출은 하나의 세션입니다. - + -`session_id`와 `agent_id`는 모든 이벤트 메서드에서 선택 사항입니다. 생략하면 감싸는 스코프에서 해결됩니다: +`session_id`와 `agent_id`는 모든 이벤트 메서드에서 선택적입니다. 생략하면 감싸는 스코프에서 해결됩니다: ```python with failproofai_sdk.session(): @@ -425,139 +425,139 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -명시적으로 전달하면 여전히 동작하며 우선순위를 가집니다. 바인딩된 것도 없고 전달된 것도 없으면, 세션 없이 이벤트를 발행하는 대신 수정 방법을 알려주는 `TypeError`가 발생합니다. 세션 없는 이벤트는 인제스트에서 건너뛰어지고 `200`으로 응답됩니다. +명시적으로 전달하는 것도 여전히 작동하며 우선적으로 적용됩니다. 바인딩된 것도 없고 전달된 것도 없으면, 세션 없이 이벤트를 발행하는 대신 수정 방법을 알려주는 `TypeError`가 발생합니다 — 인제스트는 세션 없는 이벤트를 건너뛰고 `200`으로 응답합니다. -스코프는 컨텍스트 변수에 식별자를 바인딩합니다. 이는 asyncio 태스크에는 자동으로 전파되지만 새 스레드에는 전파되지 않으므로, 워커를 `failproofai_sdk.propagate()`로 감싸야 합니다. +스코프는 컨텍스트 변수에 id를 바인딩합니다. asyncio 태스크에는 자동으로 전파되지만 새 스레드에는 전파되지 않습니다 — 워커를 `failproofai_sdk.propagate()`로 감싸세요. -#### 누가 어떤 id를 생성하는가 +#### 어떤 id를 누가 생성하는가 -| Id | 생성자 | 비고 | +| Id | 생성 주체 | 비고 | | --- | --- | --- | -| `session_id` | 사용자 또는 SDK | `session("chat-42")`는 그대로 사용됨; 생략하면 SDK가 `uuid4().hex`를 생성 | -| `agent_id` | 사용자 또는 프레임워크 | `agent("analyst")`, CrewAI `role`, `FunctionAgent.name`에서 옴. UUID처럼 보이는 값은 거부되고 대체됨 | -| `tool_call_id`, `hook_id`, `request_id` | 사용자 또는 프레임워크 | 어댑터는 프레임워크 자체의 실행 id를 재사용하므로 쌍이 스레드 전환에서도 유지됨 | -| **이벤트 id** | **클라우드, 인제스트 시** | SDK는 발행하지 않음 | -| **`dedup_key`** | **클라우드, 인제스트 시** | 조직, 세션, 타임스탬프, 타입, 페이로드의 해시. 이것이 실제 식별자로, 재시도된 배치가 중복 대신 하나로 합쳐지게 함 | +| `session_id` | 사용자 또는 SDK | `session("chat-42")`는 그대로 사용됨; 생략하면 SDK가 `uuid4().hex` 생성 | +| `agent_id` | 사용자 또는 프레임워크 | `agent("analyst")`, CrewAI `role`, `FunctionAgent.name`에서. UUID처럼 생긴 값은 거부되고 대체됨 | +| `tool_call_id`, `hook_id`, `request_id` | 사용자 또는 프레임워크 | 어댑터는 프레임워크 자체의 실행 id를 재사용하므로 쌍이 스레드 이동에서도 유지됨 | +| **이벤트 id** | **인제스트 시 클라우드** | SDK는 발행하지 않음 | +| **`dedup_key`** | **인제스트 시 클라우드** | 조직, 세션, 타임스탬프, 타입, 페이로드의 해시. 이것이 실제 id — 재시도된 배치가 중복 없이 합쳐지게 함 | -#### 어댑터가 `session_id`를 해결하는 방식 +#### 어댑터의 `session_id` 해결 방식 -첫 번째 매칭이 우선: +첫 번째 매치가 우선합니다: 1. 명시적인 `session_id` 옵션 2. 호출별 메타데이터 3. 감싸는 `session()` 스코프 4. 프레임워크 메타데이터 -5. 프레임워크 자체 실행 id +5. 프레임워크 자체의 실행 id -이 중 하나가 존재하는 동안에는 임의로 생성되지 않습니다. 합성된 id는 하나의 실행을 여러 세션으로 분리하게 됩니다. +이 중 하나가 존재하는 동안에는 id가 임의로 생성되지 않습니다 — 합성된 id는 하나의 실행을 여러 세션으로 분리할 수 있기 때문입니다. -#### `agent_id`는 저기수성으로 유지하세요 +#### `agent_id`의 카디널리티를 낮게 유지하기 -모든 대시보드 화면의 주요 패싯이며 `LowCardinality(String)` 컬럼입니다. 실행별 값을 사용하면 컬럼 성능이 저하되고 필터 드롭다운에 실행마다 하나씩 항목이 쌓입니다. +모든 대시보드 화면의 주요 패싯이며 `LowCardinality(String)` 컬럼입니다. 실행당 값을 사용하면 컬럼의 성능을 저하시키고 필터 드롭다운에 실행당 하나의 항목이 가득 차게 됩니다. -어댑터는 이 컬럼을 자동으로 보호합니다: +어댑터가 이 컬럼을 자동으로 보호합니다: -| 프레임워크가 전달한 값 | 기록되는 값 | 이유 | +| 프레임워크가 전달하는 것 | 기록되는 것 | 이유 | | --- | --- | --- | -| `3f9a1c2b-…` (UUID) | `main` | 보존할 읽기 가능한 부분 없음 | +| `3f9a1c2b-…` (UUID) | `main` | 읽을 수 있는 내용이 없음 | | 긴 순수 16진수 문자열 | `main` | 동일 | -| `agent-3f9a1c2b-…` | `agent` | 실행별 id 제거, 읽기 가능한 부분 유지 | +| `agent-3f9a1c2b-…` | `agent` | 실행별 id는 제거되고 읽을 수 있는 부분만 유지 | | `agent-v2` | `agent-v2` | 짧은 세그먼트는 그대로 유지 | | `step-3` | `step-3` | 동일 | -실제 id는 `fw_agent_id` / `fw_run_id`에 보존되어 패싯이 되지 않으면서도 쿼리 가능합니다. +실제 id는 `fw_agent_id` / `fw_run_id`에 유지되어 패싯이 되지 않으면서도 쿼리 가능합니다. - **이 보호는 프레임워크가 선택한 레이블에만 적용됩니다.** `event.*` 또는 `failproofai_sdk.agent(...)`에 직접 전달한 `agent_id`는 그대로 기록됩니다. 명시적인 인자를 조용히 재작성하는 것은 방지하려는 기수성 문제보다 더 나쁘기 때문입니다. 직접 작성하는 스팬 이름에 주의하세요. + **이 가드는 프레임워크가 선택한 레이블에만 적용됩니다.** `event.*`나 `failproofai_sdk.agent(...)`에 직접 전달하는 `agent_id`는 그대로 기록됩니다. 명시적인 인수를 조용히 재작성하는 것은 방지하려는 카디널리티 문제보다 더 나쁘기 때문입니다. 따라서 직접 명명한 스팬은 적절히 이름을 지으세요. - + | 그룹 | 이벤트 | | --- | --- | | 에이전트 | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | | 모델 | `model_request`, `model_response` | -| 도구 | `tool_use`, `tool_result` | +| 툴 | `tool_use`, `tool_result` | | 훅 | `hook_triggered`, `hook_completed` | -| 사람 | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| 휴먼 | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | 실패 | `error` | -위의 실행 결과를 기준으로 프레임워크별 기록 여부: +위의 실행에서 측정한 프레임워크별 기록 항목: | 이벤트 | LangGraph | CrewAI | LlamaIndex | Pydantic AI | 커스텀 | | --- | :--: | :--: | :--: | :--: | :--: | | 에이전트 시작/종료 | 예 | 예 | 예 | 예 | 직접 | | 모델 요청/응답 | 예 | 예 | 예 | 예 | 직접 | -| 도구 사용/결과 | 예 | 예 | 예 | 예 | 직접 | -| 훅 시작/완료 | 노드 | 태스크 | 스텝 | — | 직접 | +| 툴 사용/결과 | 예 | 예 | 예 | 예 | 직접 | +| 훅 트리거/완료 | 노드 | 태스크 | 스텝 | — | 직접 | | 오류 | 예 | 예 | 예 | 예 | 자동 | -| 사람 대기/입력 | 예 | 예 | 예 | — | 직접 | +| 휴먼 대기/입력 | 예 | 예 | 예 | — | 직접 | | 에이전트 일시정지/재개 | 예 | 예 | 예 | — | 직접 | -대시(—)는 프레임워크에 해당 개념이 없음을 의미합니다. `human_pause`와 `human_interrupt`는 에이전트에 _사람_이 개입하는 것을 나타내며, 어떤 프레임워크도 신호를 보내지 않으므로 직접 발행해야 합니다. +대시(—)는 해당 프레임워크에 그런 개념이 없음을 의미합니다. `human_pause`와 `human_interrupt`는 에이전트에 개입하는 사람을 나타내며, 어떤 프레임워크도 이를 신호로 보내지 않으므로 직접 발행해야 합니다. - + -이벤트는 단독으로 도착하지 않습니다. 하나가 스팬을 열고, 하나가 닫으며, 닫는 이벤트는 SDK가 여는 이벤트부터 측정한 지속 시간을 가집니다. +이벤트는 절대 단독으로 오지 않습니다. 하나가 스팬을 열고 하나가 닫으며, 종료 이벤트는 SDK가 시작 이벤트로부터 측정한 지속 시간을 포함합니다. -| 여는 이벤트 | 닫는 이벤트 | 닫는 이벤트에 포함된 내용 | +| 시작 | 종료 | 종료 이벤트에 포함되는 것 | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | | `model_request` | `model_response` | 토큰, `stop_reason`, 레이턴시 | | `tool_use` | `tool_result` | `output` 또는 `error`, 지속 시간 | | `hook_triggered` | `hook_completed` | `outcome`, 지속 시간 | -| `agent_pause` | `agent_resume` | 일시 정지 지속 시간 | -| `human_wait` | `human_input` | 응답, 응답까지 걸린 시간 | +| `agent_pause` | `agent_resume` | 일시정지 지속 시간 | +| `human_wait` | `human_input` | 응답, 그리고 사람이 걸린 시간 | - 닫는 이벤트가 없는 여는 이벤트는 영원히 끝나지 않는 스팬입니다. 세션은 계속 실행 중으로 표시되고 활성 지속 시간이 계속 증가합니다. 이것이 수동 계측 시 주의해야 할 실패 패턴입니다. + 종료 이벤트가 없는 시작 이벤트는 영원히 끝나지 않는 스팬입니다. 세션은 영원히 실행 중으로 표시되고 활성 지속 시간이 계속 증가합니다. 직접 계측할 때 주의해야 할 실패 모드입니다. #### 상관관계 규칙 -- 매칭되는 완료 이벤트에 동일한 `tool_call_id`, `hook_id`, `pause_id`, `input_id`를 재사용하세요. -- SDK는 `tool_result`, `hook_completed`, `agent_resume`, `human_input`에 대해 `duration_ms`를 계산합니다. 이 메서드들에 전달하면 `ValueError`가 발생합니다. -- `duration_ms`는 `model_response`에서 **허용됩니다**. 실제 프로바이더 레이턴시는 호출자만 알기 때문입니다. 정수여야 합니다. 부동소수점은 호출 시점에 `ValueError`를 발생시킵니다. 서버가 해당 컬럼을 부호 없는 32비트 정수로 읽어 다른 값은 NULL로 저장하기 때문입니다. -- 상관관계 키는 종류와 세션별로 범위가 지정되므로, 도구 호출과 훅이 같은 id를 안전하게 공유할 수 있으며, 동시 세션도 동일한 id를 충돌 없이 재사용할 수 있습니다. 에이전트별로는 범위가 지정되지 않습니다. 한 에이전트 아래서 열리고 다른 에이전트 아래서 닫히는 쌍도 여전히 상관관계를 유지합니다. 이는 다중 에이전트 프레임워크에서 일반적인 경우입니다. -- `request_id`는 `model_request`와 `model_response`를 쌍으로 묶습니다. 없으면 모델 이벤트가 에이전트별 순서대로 쌍을 이루므로, 동시 호출 시 잘못된 쌍이 생깁니다. -- 프로세스를 넘나드는 쌍은 다운스트림에서도 상관관계를 유지하지만, SDK는 프로세스 내 지속 시간을 계산할 수 없습니다. -- 대기 중인 맵은 최대 10,000개의 시작 이벤트를 보유하며, 가득 차면 가장 오래된 항목을 삭제합니다. +- 매칭되는 완료 이벤트에 동일한 `tool_call_id`, `hook_id`, `pause_id`, 또는 `input_id`를 재사용하세요. +- SDK는 `tool_result`, `hook_completed`, `agent_resume`, `human_input`의 `duration_ms`를 계산합니다. 이 메서드들에 전달하면 `ValueError`가 발생합니다. +- `duration_ms`는 `model_response`에는 허용됩니다. 실제 프로바이더 레이턴시는 호출자만 알기 때문입니다. 정수여야 합니다 — float는 호출 지점에서 `ValueError`가 발생합니다. 서버가 해당 컬럼을 부호 없는 32비트 정수로 읽어 다른 값이면 NULL을 저장하기 때문입니다. +- 상관관계 키는 종류와 세션으로 범위가 지정되므로 툴 호출과 훅이 안전하게 id를 공유할 수 있고, 두 동시 세션이 충돌 없이 동일한 id를 재사용할 수 있습니다. 에이전트로는 범위가 지정되지 않습니다: 한 에이전트에서 열리고 다른 에이전트에서 닫힌 쌍도 여전히 상관관계를 가지며, 이것이 멀티 에이전트 프레임워크에서 일반적인 경우입니다. +- `request_id`는 `model_request`와 `model_response`를 쌍으로 묶습니다. 없으면 에이전트별 순서대로 모델 이벤트가 쌍을 이루어 동시 호출 시 잘못된 쌍이 만들어집니다. +- 프로세스에 걸쳐 분리된 쌍은 다운스트림에서 여전히 상관관계를 가지지만 SDK는 프로세스 내 지속 시간을 계산할 수 없습니다. +- 보류 맵은 최대 10,000개의 시작 이벤트를 보유하며 가득 찼을 때 가장 오래된 항목을 제거합니다. - + `failproofai-sdk`를 설치하면 네 가지 어댑터를 포함한 모든 것이 설치됩니다. extras는 어댑터가 아닌 **프레임워크**를 가져옵니다. ```python -import failproofai_sdk # 표준 라이브러리 외 아무것도 로드하지 않음 +import failproofai_sdk # 표준 라이브러리 외에는 아무것도 로드하지 않음 failproofai_sdk.instrument() # 실제로 필요한 어댑터만 임포트 ``` -`import failproofai_sdk`는 계약상 의존성이 없으며, `--no-deps`로 빌드된 wheel을 설치하는 테스트와 어떤 프레임워크도 `sys.modules`에 없음을 증명하는 테스트로 강제됩니다. +`import failproofai_sdk`는 계약상 의존성이 없으며, `--no-deps`로 빌드된 wheel을 설치하는 테스트와 어떤 프레임워크도 `sys.modules`에 도달하지 않음을 증명하는 테스트로 강제됩니다. - `failproofai_sdk.crewai` 속성은 없습니다. 어댑터는 의도적으로 최상위 패키지에 노출되지 않습니다. 하나를 건드리면 속성 접근의 부작용으로 프레임워크가 임포트되어 의존성 없음 약속이 깨집니다. `instrument()`를 사용하세요. + `failproofai_sdk.crewai` 속성은 없습니다. 어댑터는 의도적으로 최상위 패키지에 노출되지 않습니다: 속성에 접근하면 속성 접근의 부작용으로 프레임워크가 임포트되어 의존성 없음 약속이 깨집니다. `instrument()`를 사용하세요. ```python failproofai_sdk.instrument() # 이미 임포트된 모든 프레임워크 failproofai_sdk.instrument("crewai") # 이름으로 정확히 하나 -failproofai_sdk.uninstrument("crewai") # 되돌리기 +failproofai_sdk.uninstrument("crewai") # 원래대로 되돌리기 ``` -| 이름 | 대체 이름 허용 | +| 이름 | 대체 허용 | | --- | --- | | `langchain` | `langgraph`, `langchain_core` | | `crewai` | — | | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -자동 탐지는 설치된 패키지 목록이 아닌 `sys.modules`를 읽으므로, 설치했지만 임포트하지 않은 프레임워크는 계측되지 않으며 임의로 임포트되지도 않습니다. 현재 연결된 것을 확인하려면: +자동 감지는 설치된 패키지 목록이 아닌 `sys.modules`를 읽으므로, 설치되었지만 임포트되지 않은 프레임워크는 계측되지 않으며 대신 임포트되지도 않습니다. 연결된 것을 확인하려면: ```python from failproofai_sdk.integrations import active, available @@ -567,32 +567,32 @@ active() # ('langchain',) ``` - **CrewAI가 없는 머신에서 `instrument("crewai")`를 호출해도 예외가 발생하지 않습니다.** 경고를 로그에 남기고 `()`를 반환하므로, 하나의 프레임워크가 없어도 다른 프레임워크를 계측하는 프로세스가 중단되지 않습니다. + **CrewAI가 없는 머신에서 `instrument("crewai")`를 호출해도 예외가 발생하지 않습니다.** 경고를 로그로 출력하고 `()`를 반환하므로, 하나의 프레임워크가 없어도 다른 프레임워크를 계측하는 프로세스가 중단되지 않습니다. - 경고에는 기본 `ImportError`가 포함되며, 해당 메시지에 정확한 설치 명령이 나와 있습니다. 수정 방법이 숨겨지지 않고 로그에 있습니다. + 경고에는 기본 `ImportError`가 포함되며, 해당 메시지에 정확한 설치 명령이 나타납니다 — 수정 방법이 숨겨지지 않고 로그에 있습니다. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - 예외를 발생시키려면 `FAILPROOFAI_SDK_STRICT=1`을 설정하세요. 이 플래그는 **한 번 읽히고 캐시되므로**, 실행 중에 설정하지 말고 프로세스 시작 전에 내보내세요. + 대신 예외를 발생시키려면 `FAILPROOFAI_SDK_STRICT=1`을 설정하세요. 해당 플래그는 **한 번 읽히고 캐시되므로** 실행 중에 설정하는 것이 아니라 프로세스 시작 전에 내보내야 합니다. - **`instrument()`는 프레임워크 임포트 *이후*에 와야 합니다.** 자동 탐지는 `sys.modules`를 읽으므로, 임포트 전에 빈 호출을 하면 아무것도 찾지 못하고, 아무것도 설치하지 않고, `()`를 반환합니다. + **`instrument()`는 프레임워크 임포트 이후에 호출해야 합니다.** 자동 감지가 `sys.modules`를 읽으므로, 임포트 전에 호출하면 아무것도 찾지 못하고, 아무것도 설치하지 않고, `()`를 반환합니다. ```python Wrong import failproofai_sdk -failproofai_sdk.instrument() # sys.modules에 langchain 없음 -> () +failproofai_sdk.instrument() # sys.modules에 langchain이 아직 없음 -> () import langchain # 너무 늦음, 아무것도 연결되지 않음 ``` ```python Right -import langchain # 프레임워크를 먼저 임포트 +import langchain # 먼저 프레임워크를 임포트 import failproofai_sdk failproofai_sdk.instrument() # 찾음 -> ('langchain',) @@ -601,135 +601,133 @@ failproofai_sdk.instrument() # 찾음 -> ('langchain',) ```python Right, order-proof import failproofai_sdk -# 이름으로 지정하면 요청 시 어댑터를 임포트하므로 어디서든 동작합니다. +# 이름을 지정하면 어댑터를 요청 시 임포트하므로 어디서나 동작합니다. failproofai_sdk.instrument("langchain") ``` -잘못하면 SDK는 임포트되고 어댑터는 설치된 것처럼 보이지만 **이벤트가 하나도 발행되지 않습니다**. 정확히 그 내용을 알리는 경고를 로그에 남기므로, 실행이 아무것도 기록하지 않을 때 로그를 먼저 확인하세요. +이를 잘못하면 SDK가 임포트되고, 어댑터가 설치된 것처럼 보이며, **이벤트는 하나도 발행되지 않습니다**. 정확히 그 내용을 알려주는 경고가 로그로 출력됩니다 — 실행에서 아무것도 기록되지 않을 때 먼저 로그를 확인하세요. - + ```mermaid flowchart LR - A["Your agent"] --> B["Adapter"] - B --> C["Writer
in-memory queue"] - C -->|"every 0.5s"| D["Spool
JSONL on disk"] - D --> E["Failproof daemon"] - E -->|"HTTPS"| F["Cloud"] + A["에이전트"] --> B["어댑터"] + B --> C["Writer
인메모리 큐"] + C -->|"0.5초마다"| D["Spool
디스크의 JSONL"] + D --> E["Failproof 데몬"] + E -->|"HTTPS"| F["클라우드"] ``` | 단계 | 역할 | 실행 위치 | | --- | --- | --- | | 어댑터 | 프레임워크 콜백을 15가지 이벤트 타입 중 하나로 변환 | 사용자 프로세스 | -| 라이터 | 큐에 넣고, 배치로 묶어, JSONL을 원자적으로 쓰기 | 사용자 프로세스, 백그라운드 스레드 | -| 스풀 | 프로세스 종료에도 살아남는 내구성 있는 전달 지점 | 로컬 디스크 | -| 데몬 | 스풀을 감시하고, 배치를 전송하고, 전송한 것을 삭제 | 사용자 머신 | -| 인제스트 | 행 id와 dedup 키를 부여하고, 쿼리 가능한 컬럼으로 승격 | 클라우드 | +| Writer | 큐에 넣고, 배치로 묶고, JSONL을 원자적으로 작성 | 사용자 프로세스, 백그라운드 스레드 | +| Spool | 내구성 있는 핸드오프, 프로세스 종료 후에도 유지 | 로컬 디스크 | +| 데몬 | spool을 감시하고, 배치를 전송하고, 전송된 것을 삭제 | 사용자 머신 | +| 인제스트 | 행 id와 dedup 키를 할당하고, 쿼리 가능한 컬럼을 승격 | 클라우드 | -스풀이 안전성의 핵심입니다. 에이전트는 네트워크에서 절대 차단되지 않으며, 클라우드 장애 시 이벤트가 유실되는 대신 디렉터리가 커집니다. +spool이 이 방식을 안전하게 만드는 요소입니다: 에이전트는 네트워크를 기다리지 않으며, 클라우드 장애는 이벤트 손실이 아닌 디렉토리 증가를 의미합니다. -각 플러시는 하나의 배치 파일을 씁니다. `.tmp`로 먼저 쓰고, `fsync`한 뒤, 원자적으로 이름을 변경합니다: +각 플러시는 하나의 배치 파일을 작성합니다. `.tmp` 먼저, 그 다음 `fsync`, 그 다음 원자적 이름 변경: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -데몬은 `.jsonl`만 읽으므로 절반만 쓰인 파일을 읽을 수 없습니다. 파일명에 타임스탬프, 프로세스 id, 시퀀스 번호가 포함되어 있어 두 프로세스가 같은 밀리초에 플러시해도 충돌하지 않습니다. 큐는 10,000개 이벤트로 제한되며, 초과 시 가장 오래된 것을 삭제하고 로그를 남깁니다. +데몬은 `.jsonl`만 읽으므로 절반만 작성된 파일을 읽을 수 없습니다. 파일 이름에 타임스탬프, 프로세스 id, 순번이 포함되어 같은 밀리초에 두 프로세스가 플러시해도 충돌하지 않습니다. 큐는 10,000개의 이벤트로 제한되며, 초과 시 가장 오래된 것을 삭제하고 로그로 출력합니다. - **`collector.redact`는 SDK 이벤트에 적용되지 않습니다.** 절대 해당 이벤트를 볼 수 없습니다. + **`collector.redact`는 SDK 이벤트에도 기본값이 `minimal`입니다.** SDK는 배치를 디스크에 작성하기 전에 스크럽하고, 데몬은 이전 SDK의 배치도 보호될 수 있도록 업로드 전에 동일한 결정적 처리를 반복합니다. -데몬은 배치를 **전송**합니다. 열거나 다시 쓰지 않습니다. +데몬은 각 배치를 읽고 업로드 전에 메모리에서 리댁션을 적용합니다. 읽은 spool 파일은 재작성하지 않습니다. -| 이벤트 | 작성자 | `collector.redact` 적용 여부 | +| 이벤트 | 작성 주체 | 최소 리댁션 실행 위치 | | --- | --- | --- | -| CLI 세션 트랜스크립트 | 데몬 | 예 | -| 훅 활동 | 데몬 | 예 | -| **SDK가 발행하는 모든 것** | **사용자 프로세스** | **아니오** | +| CLI 세션 트랜스크립트 | 데몬 | 데몬이 배치를 작성하기 전 | +| 훅 활동 | 데몬 | 데몬이 배치를 작성하기 전 | +| **SDK가 발행하는 모든 것** | **사용자 프로세스** | **SDK가 배치를 작성하기 전, 그리고 데몬 업로드 전 다시** | -리댁션은 데몬이 자체 이벤트를 *쓰는* 곳에서 실행됩니다. 배치가 *전송*되는 곳이 아닙니다. 따라서 API 키를 포함한 프롬프트나 도구 인자는 도착 시에도 그대로입니다. - -이는 의도적입니다. 이것은 사용자 자신의 계측 호출이며, 전송 중에 이를 재작성하면 받은 이벤트가 발행한 이벤트와 다르게 됩니다. +페이로드를 그대로 보내는 것이 명시적인 요구사항인 경우에만 `collector.redact`를 `off`로 설정하세요. SDK와 데몬 모두 해당 설정을 따릅니다. 최소 리댁션은 일반적인 API 키, 베어러 토큰, JWT, 시크릿 할당을 잡아냅니다. 임의의 민감한 내용은 식별할 수 없습니다. - **페이로드는 소스에서 두 곳에서 제어할 수 있습니다:** + **소스에서 페이로드를 두 곳에서 제어할 수 있습니다:** - - 어댑터에서 콘텐츠 캡처를 끄세요. **옵션 이름이 다르며, 하나의 어댑터에는 옵션이 없습니다.** 이것은 단일 범용 스위치가 아닙니다: + - 어댑터에서 콘텐츠 캡처를 끄세요. **옵션 이름이 다르며, 하나의 어댑터에는 없습니다** — 이것은 단일 범용 스위치가 아닙니다: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **콘텐츠 스위치 없음**; `session_id`가 읽는 유일한 옵션이므로 프롬프트와 완성은 항상 기록됩니다. + - CrewAI — **콘텐츠 스위치 없음**; `session_id`만 읽으므로 프롬프트와 완성 내용이 항상 기록됩니다. - `instrument()`는 어댑터가 읽지 않는 옵션을 무시하므로, 잘못된 이름을 전달해도 오류 없이 아무 변화도 없습니다. - - 처음부터 `input=`에 비밀을 전달하지 마세요. + `instrument()`는 어댑터가 읽지 않는 옵션을 무시하므로, 잘못된 이름을 전달해도 예외가 발생하지 않고 아무것도 변경되지 않습니다. + - 애초에 `input=`에 시크릿을 전달하지 마세요. - `collector.redact`는 두 경우 중 어느 것도 대체하지 않습니다. + `collector.redact`는 심층 방어이며, 이 둘 중 어느 것의 대체가 아닙니다. - **빈 스풀 디렉터리가 정상 상태입니다.** 전달 여부 확인에 사용하지 마세요. + **spool 디렉토리가 비어 있는 것이 정상 상태입니다.** 이것으로 전달 여부를 확인하지 마세요. -데몬은 각 배치를 전송 후 수 밀리초 내에 삭제하므로, `ls`를 실행하면 수집기와 경쟁하게 되어 발행한 것의 일부만 보입니다. 아무것도 기록하지 않은 SDK와 구분할 수 없습니다. +데몬은 배치를 전송한 후 수 밀리초 내에 삭제하므로, `ls`는 콜렉터와 경쟁하여 발행한 것의 일부만 보여줍니다 — 아무것도 기록하지 않은 SDK와 구별할 수 없습니다. -이벤트가 실제로 도달했는지 확인하려면 대시보드를 확인하세요. 스풀이 채워지는 것을 관찰하려면 먼저 데몬을 중지하세요. +이벤트가 실제로 전달되었는지 확인하려면 대시보드를 확인하세요. spool이 채워지는 것을 보려면 먼저 데몬을 중지하세요. -모든 콜백은 재발생만을 담당하는 래퍼 안에서 실행됩니다. 따라서 호출은 정확히 하나의 `try` 안에 있고, SDK가 하는 모든 것은 그 밖에서 일어납니다. +모든 콜백은 단 하나의 역할만 하는 래퍼 안에서 실행됩니다 — 다시 발생시키는 것. 따라서 호출은 정확히 하나의 `try`에 있으며 SDK가 하는 모든 일은 그 밖에서 일어납니다. -| 발생한 상황 | 결과 | +| 발생 상황 | 결과 | | --- | --- | -| 훅이 예외 발생 | 트레이스백과 함께 한 번 로그됨. 호출에는 영향 없음 | -| 같은 훅이 세 번 예외 발생 | 해당 훅만 프로세스 나머지 동안 비활성화, 오류 한 줄 | -| `FAILPROOFAI_SDK_STRICT=1` 설정됨 | 예외가 대신 다시 발생 | -| 프레임워크 버전이 테스트 범위 밖 | 한 번 경고, 그래도 계측 진행 | -| 단일 기능이 없음 | 해당 훅만 비활성화, 어댑터 전체는 아님 | +| 훅에서 예외 발생 | 트레이스백과 함께 한 번 로그됨. 호출에 영향 없음 | +| 같은 훅에서 세 번 예외 발생 | 해당 훅만 프로세스의 나머지 동안 비활성화되며, 오류 한 줄 출력 | +| `FAILPROOFAI_SDK_STRICT=1` 설정 | 대신 예외가 다시 발생 | +| 프레임워크 버전이 테스트 범위 밖 | 한 번 경고하고 계측은 진행 | +| 단일 기능 누락 | 해당 훅만 비활성화되며, 전체 어댑터는 아님 | -기본값은 프로덕션에서는 맞고 디버깅 시에는 맞지 않습니다. "충돌하지 않았다"는 것만 증명할 수 있기 때문입니다. 삼켜진 실패를 드러내려면 `FAILPROOFAI_SDK_STRICT=1`을 설정하세요. +기본값은 프로덕션에서는 맞고 디버깅 중에는 틀립니다. "충돌하지 않았다"는 것만 증명할 수 있기 때문입니다. 삼켜진 실패를 명확히 드러내려면 `FAILPROOFAI_SDK_STRICT=1`을 설정하세요. -## 자주 발생하는 문제 +## 일반적인 문제 - - 여는 이벤트에 닫는 이벤트가 없는 경우입니다. `model_request`에 `model_response`가 없거나 `tool_use`에 `tool_result`가 없는 경우입니다. 본문에서 예외가 발생해도 쌍을 보장하는 스코프를 사용하세요. 이벤트 메서드를 직접 호출한다면 `try`와 `finally`를 사용하세요. + + 시작 이벤트에 대응하는 종료 이벤트가 없습니다: `model_response`가 없는 `model_request`, 또는 `tool_result`가 없는 `tool_use`. 본문에서 예외가 발생해도 쌍을 보장하는 스코프를 사용하세요. 이벤트 메서드를 직접 호출한다면 `try`와 `finally`를 사용하세요. - - 매칭되는 여는 이벤트부터 측정되므로, `tool_result`, `hook_completed`, `agent_resume`, `human_input`에서는 거부됩니다. `model_response`에서는 허용되며, 실제 프로바이더 레이턴시는 사용자만 알기 때문입니다. 정수여야 합니다. + + 매칭되는 시작 이벤트로부터 측정되므로 `tool_result`, `hook_completed`, `agent_resume`, `human_input`에서는 거부됩니다. 실제 프로바이더 레이턴시는 사용자만 알기 때문에 `model_response`에서는 허용되며, 정수여야 합니다. - - 스레드가 컨텍스트를 상속받지 못했습니다. callable을 `failproofai_sdk.propagate()`로 감싸세요. [스레드와 비동기](#threads-and-async)를 참고하세요. + + 스레드가 컨텍스트를 상속받지 않았습니다. callable을 `failproofai_sdk.propagate()`로 감싸세요. [스레드와 비동기](#threads-and-async)를 참조하세요. - - 추가 필드는 마지막에 병합되므로, `model`이나 `outcome` 같은 실제 필드와 같은 이름이면 덮어쓰고 저장된 컬럼을 변경합니다. 네임스페이스를 사용하세요. 어댑터는 `fw_` 접두사를 사용합니다. + + 추가 필드는 마지막에 병합되므로 `model`이나 `outcome` 같은 실제 필드와 같은 이름을 사용하면 덮어씌워져 저장된 컬럼이 변경됩니다. 네임스페이스를 사용하세요. 어댑터는 `fw_` 접두사를 사용합니다. - `agent_id`는 저기수성 패싯인데 실행 id를 넣었습니다. 역할이나 노드 이름을 사용하고 실제 id는 페이로드 필드에 넣으세요. + `agent_id`는 카디널리티가 낮은 패싯인데 실행 id를 넣었습니다. 역할이나 노드 이름을 사용하고 실제 id는 페이로드 필드에 넣으세요. ## 다음 단계 - - 쌍, id, 세션 생명주기, 전달 방식. + + 쌍, id, 세션 생명주기, 그리고 전달. - 방금 캡처한 세션의 인과관계를 따라가세요. + 방금 캡처한 세션에서 인과관계를 추적합니다. LangGraph, CrewAI, LlamaIndex, Pydantic AI. diff --git a/docs/pt-br/start/integrations/custom-agents.mdx b/docs/pt-br/start/integrations/custom-agents.mdx index fd1ab4f0..bb396cc8 100644 --- a/docs/pt-br/start/integrations/custom-agents.mdx +++ b/docs/pt-br/start/integrations/custom-agents.mdx @@ -5,9 +5,9 @@ description: "Instrumente um agente que você mesmo escreveu, ou um framework se icon: "code" --- -Para um agente que você mesmo escreveu, ou um framework para o qual Failproof AI não possui adaptador. Não há nada a instrumentar: você emite os eventos. +Para um agente que você escreveu, ou um framework sem adaptador no Failproof AI. Não há nada a instrumentar: você emite os eventos. -Esta é a mesma API que os quatro adaptadores de framework utilizam internamente. Eles são tabelas de tradução sobre ela. +Esta é a mesma API que os quatro adaptadores de framework utilizam por baixo dos panos. Eles são tabelas de tradução sobre ela. ## Instalação @@ -30,7 +30,7 @@ with failproofai_sdk.session(): # uma execução t.output = search(q) # uma chamada de ferramenta ``` -Leia de cima para baixo e o código diz o que significa: +Leia de cima para baixo e o código diz exatamente o que significa: | Envolva em | Para dizer | | --- | --- | @@ -38,15 +38,15 @@ Leia de cima para baixo e o código diz o que significa: | `agent()` | Algo está realizando trabalho — dê um nome que você reconheceria em uma lista | | `tool_call()` | Esta é uma ferramenta, e aqui está o que ela retornou | -E o que cada um emite de fato: +E o que cada um realmente emite: | Escopo | Emite | Propósito | | --- | --- | --- | -| `session()` | Nada | Vincula um session id, agrupando uma execução | +| `session()` | Nada | Vincula um id de sessão, agrupando uma execução | | `agent()` | `agent_start`, `agent_end` | Delimita uma unidade de trabalho | -| `tool_call()` | `tool_use`, `tool_result` | Delimita uma ferramenta e mede sua duração | +| `tool_call()` | `tool_use`, `tool_result` | Delimita uma ferramenta e a mede | -Tudo que está dentro pode omitir `session_id` e `agent_id`. Os escopos vinculam identidade em variáveis de contexto e cada chamada de evento a lê de volta, então você nunca precisa passar ids pelas suas funções. +Tudo dentro pode omitir `session_id` e `agent_id`. Os escopos vinculam identidade em variáveis de contexto e toda chamada de evento lê de volta, então você nunca precisa passar ids pelas suas funções. Os três funcionam com `async with` assim como com `with`. @@ -61,20 +61,20 @@ with failproofai_sdk.session(): ## Como um escopo é fechado -`agent()` trata exceções para você: +`agent()` trata exceções por você: | O que aconteceu | Eventos | Resultado | | --- | --- | --- | | Nada foi lançado | `agent_end` | `success` | | `Exception` | `error`, depois `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, depois `agent_end` | `failed` | -| `CancelledError`, `GeneratorExit` | Apenas `agent_end` | `cancelled` | +| `CancelledError`, `GeneratorExit` | apenas `agent_end` | `cancelled` | -O erro é emitido antes de `agent_end`, porque o dashboard fecha o span em `agent_end` e qualquer coisa depois disso não é atribuída a nada. Um cancelamento não é uma falha, então execuções canceladas não poluem a superfície de erros. A exceção sempre é relançada: um escopo nunca a engole. +O erro é emitido antes de `agent_end`, porque o dashboard fecha o span em `agent_end` e qualquer coisa depois disso não é atribuída a nada. Um cancelamento não é uma falha, portanto execuções canceladas não poluem a superfície de erros. A exceção sempre é relançada: um escopo nunca a engole. ## Os métodos de evento -Quinze métodos em seis famílias. A maioria vem em pares — você emite o abridor, depois o fechador, e o SDK mede o span entre eles. +Quinze métodos em seis famílias. A maioria vem em pares — você emite o abridor, depois o fechador, e o SDK mede o intervalo entre eles. | Família | Abre | Fecha | Independente | | --- | --- | --- | --- | @@ -87,7 +87,7 @@ Quinze métodos em seis famílias. A maioria vem em pares — você emite o abri | **Falhas** | — | — | `error` | - Prefira os escopos — `agent()` e `tool_call()` — sempre que se encaixarem. Eles garantem o evento de fechamento mesmo quando o corpo lança uma exceção. Recorra a esses métodos diretamente quando seu fluxo de controle não for aninhado, como uma chamada de modelo dentro de um helper. + Prefira os escopos — `agent()` e `tool_call()` — sempre que possível. Eles garantem o evento de fechamento mesmo quando o corpo lança uma exceção. Use esses métodos diretamente quando o seu fluxo de controle não aninha, como uma chamada de modelo dentro de uma função auxiliar. @@ -145,19 +145,19 @@ failproofai_sdk.event.error( | Métodos | Significado | | --- | --- | - | `human_wait` / `human_input` | O **agente perguntou a uma pessoa** — uma porta de aprovação, uma pergunta de esclarecimento | - | `human_pause` / `human_interrupt` | **Uma pessoa agiu sobre o agente** — um botão de parada, uma pausa do operador | + | `human_wait` / `human_input` | O **agente perguntou a uma pessoa** — uma aprovação, uma pergunta de esclarecimento | + | `human_pause` / `human_interrupt` | Uma **pessoa agiu sobre o agente** — um botão de parada, uma pausa do operador | - Nenhum framework sinaliza o segundo par, então sempre cabe a você emiti-lo. + Nenhum framework sinaliza o segundo par, portanto cabe sempre a você emiti-lo. - **Passe `request_id` quando chamadas de modelo rodarem concorrentemente.** Sem ele, requisições e respostas são emparelhadas na ordem de chegada por agente — e chamadas concorrentes se desemparelham, associando cada resposta à requisição errada. + **Passe `request_id` quando chamadas de modelo ocorrem concorrentemente.** Sem ele, requisições e respostas são pareadas por ordem de chegada por agente — e chamadas concorrentes são emparelhadas incorretamente, associando cada resposta à requisição errada. ## Exemplo -Um loop de chamada de ferramentas contra a API da OpenAI, sem framework de agentes: +Um loop de chamadas de ferramenta contra a API da OpenAI, sem nenhum framework de agente: ```python import json @@ -204,13 +204,13 @@ with failproofai_sdk.session(): }) ``` -Isso produz os mesmos seis tipos de evento que um adaptador forneceria. A versão -completa e executável, com as definições de ferramentas, está disponível no repositório do SDK em +Isso produz os mesmos seis tipos de evento que um adaptador geraria. A versão +completa e executável, com as definições de ferramentas, está no repositório do SDK em `docs/manual/examples/`. ## Threads e async -Variáveis de contexto se propagam automaticamente para tarefas asyncio. Elas não se propagam para novas threads, porque uma thread começa com um contexto vazio. +Variáveis de contexto propagam automaticamente para tasks do asyncio. Elas não propagam para novas threads, porque uma thread começa com um contexto vazio. ```python # asyncio: nada a fazer @@ -223,13 +223,13 @@ threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Sem `propagate()`, os eventos do worker lançam um `TypeError` indicando a correção, em vez de serem associados a nenhuma sessão. Isso é intencional: um evento sem sessão é ignorado pelo ingest e respondido com `200`, que é a falha silenciosa que a camada de identidade existe para evitar. +Sem `propagate()`, os eventos do worker lançam um `TypeError` informando a correção em vez de aterrissar em nenhuma sessão. Isso é intencional: um evento sem sessão é ignorado pelo ingest e respondido com `200`, que é a falha silenciosa que a camada de identidade existe para prevenir. ## Instrumentar um framework sem adaptador -Todo framework de agentes oferece as mesmas três costuras. Mapeie-as e você terá um trace completo — os quatro adaptadores fornecidos não fazem nada além disso. +Todo framework de agente oferece as mesmas três costuras. Mapeie-as e você terá um trace completo — os quatro adaptadores incluídos não fazem nada além disso. -| A costura | O que você escreve | O que registra | +| A costura | O que você escreve | O que é registrado | | --- | --- | --- | | A execução | `session()` + `agent()` | `agent_start`, `agent_end` | | Cada ferramenta | `tool_call()` | `tool_use`, `tool_result` | @@ -244,14 +244,14 @@ Todo framework de agentes oferece as mesmas três costuras. Mapeie-as e você te ``` - No que quer que o framework chame de wrapper de ferramenta ou middleware. + No que quer que o framework chame de wrapper ou middleware de ferramenta. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -266,20 +266,20 @@ Todo framework de agentes oferece as mesmas três costuras. Mapeie-as e você te - **Tem um limite de nó, passo ou middleware que vale a pena visualizar?** Envolva-o em um par de hook — `hook_triggered` / `hook_completed` — não em um `agent()` aninhado. `agent_id` é uma faceta de baixa cardinalidade, e uma entrada por nó a satura. Spans de hook são renderizados da mesma forma e fornecem latência por nó. + **Tem um boundary de nó, etapa ou middleware que vale ver?** Envolva-o em um par de hooks — `hook_triggered` / `hook_completed` — em vez de um `agent()` aninhado. `agent_id` é uma faceta de baixa cardinalidade, e uma entrada por nó o sobrecarrega. Spans de hook são renderizados da mesma forma e fornecem latência por nó. - **Manual e automático se compõem.** Um adaptador rodando dentro de um escopo escrito à mão entra nessa sessão e torna-se filho daquele agente, então você obtém uma árvore em vez de duas — útil quando você instrumenta um framework manualmente ao lado de um suportado. + **Manual e automático se compõem.** Um adaptador executando dentro de um escopo escrito à mão se junta a essa sessão e se torna filho daquele agente, então você obtém uma árvore em vez de duas — útil quando você instrumenta um framework você mesmo ao lado de um suportado. Dois motivos, e as três costuras acima são a resposta para ambos: - - `autogen-core` não é mantido desde setembro de 2025. - - O AG2 não expõe nenhum ponto de registro global equivalente aos hooks dos outros frameworks, então instrumentá-lo significa envolver cada agente em cada local de construção. + - `autogen-core` está sem manutenção desde setembro de 2025. + - AG2 não expõe um ponto de registro global equivalente aos hooks dos outros frameworks, então instrumentá-lo significa envolver cada agente em cada ponto de construção. - Mapear as costuras manualmente registra os mesmos eventos, com a mesma fidelidade, que um adaptador fornecido faria. + Mapear as costuras manualmente registra os mesmos eventos, com a mesma fidelidade, que um adaptador incluído faria. ## Indo mais fundo @@ -290,7 +290,7 @@ Como a gravação realmente funciona. Nada disso é necessário para começar. -Toda gravação tem a mesma forma: um span abre, o trabalho aninha dentro dele, e cada evento de abertura recebe um de fechamento. +Toda gravação tem a mesma forma: um span abre, o trabalho é aninhado dentro dele, e cada evento de abertura recebe um de fechamento. ```mermaid flowchart LR @@ -304,7 +304,7 @@ flowchart LR O **par** é a unidade. Cada evento de fechamento carrega uma duração que o SDK mede a partir do evento de abertura correspondente. -Abaixo há uma execução real por framework — capturada a partir dos exemplos que acompanham o SDK, com o nome do modelo normalizado. Note o quanto retorna de uma única chamada. +Abaixo está uma execução real por framework — capturada dos exemplos que acompanham o SDK, com o nome do modelo normalizado. Observe quanto retorna de uma única chamada. @@ -325,7 +325,7 @@ Abaixo há uma execução real por framework — capturada a partir dos exemplos 14 +5.721s agent_end LangGraph · success ``` - Nós se tornam pares de hook, então você obtém latência por nó sem sobrecarregar a lista de agentes. + Nós se tornam pares de hooks, então você obtém latência por nó sem sobrecarregar a lista de agentes. @@ -342,7 +342,7 @@ Abaixo há uma execução real por framework — capturada a partir dos exemplos 10 +5.739s agent_end crew · success ``` - O `role` de cada agente torna-se seu nome de span, então latência e consumo de tokens se dividem por role. + O `role` de cada agente se torna o nome do seu span, então latência e gasto de tokens se decompõem por papel. @@ -362,7 +362,7 @@ Abaixo há uma execução real por framework — capturada a partir dos exemplos 26 +7.038s agent_end Agent · success ``` - O loop do agente em si fica visível, não apenas suas chamadas de modelo. + O próprio loop do agente está visível, não apenas suas chamadas de modelo. @@ -377,7 +377,7 @@ Abaixo há uma execução real por framework — capturada a partir dos exemplos 8 +8.119s agent_end agent · success ``` - Sem pares de hook: Pydantic AI não possui limite de nó ou passo para delimitar. + Sem pares de hooks: Pydantic AI não tem nó ou boundary de etapa para delimitar. @@ -390,7 +390,7 @@ Abaixo há uma execução real por framework — capturada a partir dos exemplos 6 +0.000s agent_end main · success ``` - Você emite esses eventos você mesmo. Mesmos tipos de evento, mesma fidelidade — custa-lhe os pontos de chamada. + Você emite esses eventos você mesmo. Mesmos tipos de evento, mesma fidelidade — custa os pontos de chamada. @@ -398,7 +398,7 @@ Abaixo há uma execução real por framework — capturada a partir dos exemplos -**Não existe evento de fim de sessão.** Uma sessão não é algo que você fecha — é um grupo de eventos que compartilham um `session_id`. +**Não há evento de encerramento de sessão.** Uma sessão não é algo que você fecha — é um grupo de eventos compartilhando um `session_id`. O status é derivado da forma do trace: @@ -409,15 +409,15 @@ O status é derivado da forma do trace: | `error` | Nada está aberto e pelo menos um evento falhou | | `done` | Nada está aberto e nada falhou | -Então uma sessão termina quando todos os pares são fechados. Os adaptadores emitem `agent_end` para você, e no encerramento fecham tudo que ainda estiver aberto e marcam como incompleto — uma execução com crash se resolve como `done` com uma lacuna visível, em vez de ficar pendente. +Portanto, uma sessão termina quando todos os pares estão fechados. Os adaptadores emitem `agent_end` por você, e durante o encerramento fecham tudo que ainda está aberto e marcam como incompleto — uma execução com falha se estabiliza como `done` com uma lacuna visível em vez de ficar presa. - É por isso que uma sessão pode abranger duas chamadas. Um `interrupt()` do LangGraph pausa a execução, o span raiz permanece aberto deliberadamente, e a chamada de retomada o fecha. Ambas as chamadas são uma única sessão. + É por isso que uma sessão pode abranger duas chamadas. Um `interrupt()` do LangGraph pausa a execução, o span raiz permanece deliberadamente aberto, e a chamada de retomada o fecha. Ambas as chamadas são uma única sessão. - + `session_id` e `agent_id` são opcionais em todo método de evento. Quando omitidos, são resolvidos a partir do escopo envolvente: @@ -427,50 +427,50 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Passá-los explicitamente ainda funciona e tem precedência. Se nada estiver vinculado e nada for passado, a chamada lança um `TypeError` indicando a correção, em vez de emitir um evento sem sessão, que o ingest ignoraria enquanto responderia `200`. +Passá-los explicitamente ainda funciona e tem precedência. Com nada vinculado e nada passado, a chamada lança um `TypeError` informando a correção em vez de emitir um evento sem sessão, que o ingest ignoraria respondendo com `200`. -Os escopos vinculam identidade em variáveis de contexto. Essas se propagam automaticamente para tarefas asyncio, mas não para novas threads — envolva um worker em `failproofai_sdk.propagate()`. +Escopos vinculam identidade em variáveis de contexto. Essas propagam para tasks do asyncio automaticamente, mas não para novas threads — envolva um worker em `failproofai_sdk.propagate()`. -#### Quem gera qual id +#### Quem cria qual id -| Id | Gerado por | Observações | +| Id | Criado por | Notas | | --- | --- | --- | -| `session_id` | Você, ou o SDK | `session("chat-42")` é usado literalmente; se omitido, o SDK gera um `uuid4().hex` | -| `agent_id` | Você, ou o framework | De `agent("analyst")`, um `role` do CrewAI, um `FunctionAgent.name`. Valores com aparência de UUID são recusados e substituídos | -| `tool_call_id`, `hook_id`, `request_id` | Você, ou o framework | Adaptadores reutilizam os ids de execução do próprio framework, por isso os pares sobrevivem a saltos entre threads | -| **Event id** | **Cloud, no ingest** | O SDK não emite nenhum | -| **`dedup_key`** | **Cloud, no ingest** | Um hash de org, sessão, timestamp, tipo e payload. Esta é a identidade real — faz com que um lote reprocessado colapse em vez de duplicar | +| `session_id` | Você, ou o SDK | `session("chat-42")` é usado literalmente; quando omitido, o SDK gera um `uuid4().hex` | +| `agent_id` | Você, ou o framework | De `agent("analyst")`, um `role` do CrewAI, um `FunctionAgent.name`. Um valor com aparência de UUID é recusado e substituído | +| `tool_call_id`, `hook_id`, `request_id` | Você, ou o framework | Adaptadores reutilizam os próprios ids de execução do framework, por isso pares sobrevivem a saltos de thread | +| **Id do evento** | **Cloud, no ingest** | O SDK não emite nenhum | +| **`dedup_key`** | **Cloud, no ingest** | Um hash de org, sessão, timestamp, tipo e payload. Esta é a identidade real — faz um batch reprocessado colapsar em vez de duplicar | -#### Como adaptadores resolvem `session_id` +#### Como os adaptadores resolvem `session_id` O primeiro match vence: -1. Uma opção `session_id` explícita +1. Uma opção explícita `session_id` 2. Metadados por chamada 3. O escopo `session()` envolvente 4. Metadados do framework 5. O próprio id de execução do framework -Ele nunca é inventado enquanto um desses existir — um id sintetizado dividiria uma execução entre várias sessões. +Nunca é inventado enquanto um desses existe — um id sintetizado dividiria uma execução em várias sessões. #### Mantenha `agent_id` com baixa cardinalidade -É a faceta principal em toda superfície do dashboard, e uma coluna `LowCardinality(String)`. Um valor por execução degrada a coluna e preenche o dropdown de filtros com uma entrada por execução. +É a faceta primária em toda superfície do dashboard, e uma coluna `LowCardinality(String)`. Um valor por execução degrada a coluna e preenche o dropdown de filtro com uma entrada por execução. -Os adaptadores protegem essa coluna para você: +Os adaptadores defendem essa coluna por você: -| O framework entrega | Gravado como | Por quê | +| O framework entrega | Registrado como | Por quê | | --- | --- | --- | | `3f9a1c2b-…` (um UUID) | `main` | Nada legível para manter | -| Uma longa string hexadecimal | `main` | Igual | +| Uma longa string hex pura | `main` | Mesmo motivo | | `agent-3f9a1c2b-…` | `agent` | Id por execução removido, parte legível mantida | | `agent-v2` | `agent-v2` | Segmentos curtos são mantidos | -| `step-3` | `step-3` | Igual | +| `step-3` | `step-3` | Mesmo motivo | O id real é mantido em `fw_agent_id` / `fw_run_id`, onde permanece consultável sem ser uma faceta. - **Esta proteção só toca rótulos que o *framework* escolheu.** Um `agent_id` que você passa você mesmo — para `event.*` ou para `failproofai_sdk.agent(...)` — é gravado exatamente como fornecido. Reescrever silenciosamente um argumento explícito seria pior do que a cardinalidade que previne, então nomeie seus próprios spans adequadamente. + **Essa proteção só toca rótulos que o *framework* escolheu.** Um `agent_id` que você passa você mesmo — para `event.*` ou para `failproofai_sdk.agent(...)` — é registrado exatamente como fornecido. Reescrever silenciosamente um argumento explícito seria pior do que a cardinalidade que previne, então nomeie seus próprios spans adequadamente. @@ -493,12 +493,12 @@ O que cada framework registra, medido a partir das execuções acima: | Início e fim de agente | Sim | Sim | Sim | Sim | Você | | Requisição e resposta de modelo | Sim | Sim | Sim | Sim | Você | | Uso e resultado de ferramenta | Sim | Sim | Sim | Sim | Você | -| Hook disparado e concluído | Nó | Tarefa | Passo | — | Você | +| Hook disparado e concluído | Nó | Task | Etapa | — | Você | | Erro | Sim | Sim | Sim | Sim | Automático | | Espera e entrada humana | Sim | Sim | Sim | — | Você | | Pausa e retomada de agente | Sim | Sim | Sim | — | Você | -Um traço significa que o framework não possui tal conceito. `human_pause` e `human_interrupt` descrevem uma *pessoa* agindo sobre o agente, o que nenhum framework sinaliza — emita-os você mesmo. +Um traço significa que o framework não tem esse conceito. `human_pause` e `human_interrupt` descrevem uma *pessoa* agindo sobre o agente, o que nenhum framework sinaliza — emita esses você mesmo. @@ -512,26 +512,26 @@ Um evento nunca chega sozinho. Um abre um span, outro o fecha, e o evento de fec | `model_request` | `model_response` | tokens, `stop_reason`, latência | | `tool_use` | `tool_result` | `output` ou `error`, duração | | `hook_triggered` | `hook_completed` | `outcome`, duração | -| `agent_pause` | `agent_resume` | quanto tempo a pausa durou | +| `agent_pause` | `agent_resume` | quanto tempo durou a pausa | | `human_wait` | `human_input` | a resposta e quanto tempo a pessoa levou | - Um evento de abertura sem evento de fechamento é um span que nunca termina. A sessão é renderizada como ainda em execução, para sempre, e sua duração ativa continua crescendo. Este é o modo de falha a observar quando você instrumenta manualmente. + Um evento de abertura sem evento de fechamento correspondente é um span que nunca termina. A sessão é renderizada como ainda em execução, para sempre, e sua duração ativa continua crescendo. Este é o modo de falha a observar quando você instrumenta manualmente. #### Regras de correlação - Reutilize o mesmo `tool_call_id`, `hook_id`, `pause_id` ou `input_id` para o evento de conclusão correspondente. - O SDK calcula `duration_ms` para `tool_result`, `hook_completed`, `agent_resume` e `human_input`. Passá-lo nesses métodos lança `ValueError`. -- `duration_ms` **é** aceito em `model_response`, porque apenas quem chama conhece a latência real do provedor. Deve ser um inteiro — um float lança `ValueError` no ponto de chamada, porque o servidor lê a coluna como um inteiro sem sinal de 32 bits e armazenaria NULL para qualquer outro valor. +- `duration_ms` **é** aceito em `model_response`, porque somente o chamador conhece a latência real do provedor. Deve ser um inteiro — um float lança `ValueError` no ponto de chamada, porque o servidor lê a coluna como um inteiro de 32 bits sem sinal e armazenaria NULL para qualquer outra coisa. - Chaves de correlação têm escopo por tipo e sessão, então uma chamada de ferramenta e um hook podem compartilhar um id com segurança, e duas sessões concorrentes podem reutilizar os mesmos ids sem colisão. Elas não têm escopo por agente: um par aberto sob um agente e fechado sob outro ainda correlaciona, que é o caso comum em frameworks multi-agente. -- `request_id` emparelha `model_request` com `model_response`. Sem ele, eventos de modelo são emparelhados em ordem por agente, então chamadas concorrentes se desemparelham. -- Um par dividido entre processos ainda correlaciona no downstream, mas o SDK não pode calcular sua duração em processo. -- O mapa pendente armazena no máximo 10.000 inícios e remove a entrada mais antiga quando cheio. +- `request_id` pareia `model_request` com `model_response`. Sem ele, eventos de modelo são pareados em ordem por agente, então chamadas concorrentes são emparelhadas incorretamente. +- Um par dividido entre processos ainda correlaciona no downstream, mas o SDK não consegue calcular sua duração em processo. +- O mapa pendente comporta no máximo 10.000 inícios e descarta a entrada mais antiga quando cheio. - + Instalar `failproofai-sdk` instala tudo, incluindo os quatro adaptadores. Os extras instalam o **framework**, não o adaptador. @@ -540,16 +540,16 @@ import failproofai_sdk # não carrega nada fora da biblioteca padrão failproofai_sdk.instrument() # importa apenas os adaptadores que você realmente precisa ``` -`import failproofai_sdk` é contratualmente de dependência zero, verificado por um teste que instala o wheel compilado com `--no-deps` e outro que prova que nenhum framework alcança `sys.modules`. +`import failproofai_sdk` é contratualmente zero-dependência, aplicado por um teste que instala o wheel construído com `--no-deps` e outro que prova que nenhum framework chega a `sys.modules`. - Não existe atributo `failproofai_sdk.crewai`. Os adaptadores são deliberadamente não expostos no pacote de nível superior: acessar um importaria o framework como efeito colateral de um acesso a atributo, quebrando a promessa de dependência zero. Use `instrument()`. + Não existe atributo `failproofai_sdk.crewai`. Adaptadores são deliberadamente não expostos no pacote de nível superior: tocar em um importaria o framework como efeito colateral de um acesso de atributo, quebrando a promessa de zero-dependência. Use `instrument()`. ```python failproofai_sdk.instrument() # todo framework já importado failproofai_sdk.instrument("crewai") # exatamente um, pelo nome -failproofai_sdk.uninstrument("crewai") # desfaz +failproofai_sdk.uninstrument("crewai") # desfazer ``` | Nome | Também aceita | @@ -559,7 +559,7 @@ failproofai_sdk.uninstrument("crewai") # desfaz | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -A detecção automática lê `sys.modules`, não a lista de pacotes instalados, então um framework que você tem instalado mas nunca importou não é instrumentado e nunca é importado em seu nome. Para ver o que está conectado: +A detecção automática lê `sys.modules`, não a lista de pacotes instalados, então um framework que você instalou mas nunca importou não é instrumentado e nunca é importado por você. Para ver o que está conectado: ```python from failproofai_sdk.integrations import active, available @@ -571,24 +571,24 @@ active() # ('langchain',) **`instrument("crewai")` em uma máquina sem CrewAI não lança exceção.** Registra um aviso e retorna `()`, então um framework ausente nunca derruba um processo que também instrumenta outros. - O aviso carrega o `ImportError` subjacente, e essa mensagem indica o comando exato de instalação — então a correção está nos seus logs, não oculta. + O aviso carrega o `ImportError` subjacente, e essa mensagem indica o comando de instalação exato — então a correção está nos seus logs, não escondida. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Defina `FAILPROOFAI_SDK_STRICT=1` para que ele lance uma exceção em vez disso. Essa flag é lida **uma vez e armazenada em cache**, então exporte-a antes de seu processo iniciar em vez de defini-la durante a execução. + Defina `FAILPROOFAI_SDK_STRICT=1` para que ele lance em vez disso. Esse flag é lido **uma vez e armazenado em cache**, então exporte-o antes de seu processo iniciar em vez de defini-lo durante a execução. - **`instrument()` deve vir *depois* da importação do seu framework.** A detecção automática lê `sys.modules`, então uma chamada sem argumentos acima do import não encontra nada, não instala nada e retorna `()`. + **`instrument()` deve vir *depois* do import do seu framework.** A detecção automática lê `sys.modules`, então uma chamada simples antes do import não encontra nada, não instala nada e retorna `()`. ```python Wrong import failproofai_sdk -failproofai_sdk.instrument() # sys.modules não tem langchain ainda -> () +failproofai_sdk.instrument() # sys.modules ainda não tem langchain -> () import langchain # tarde demais, nada está conectado ``` @@ -597,18 +597,18 @@ import langchain # tarde demais, nada está conectado import langchain # importe o framework primeiro import failproofai_sdk -failproofai_sdk.instrument() # encontra -> ('langchain',) +failproofai_sdk.instrument() # encontra ele -> ('langchain',) ``` ```python Right, order-proof import failproofai_sdk -# Nomear importa o adaptador sob demanda, então isso funciona de qualquer lugar. +# Nomear o framework importa o adaptador sob demanda, então funciona de qualquer lugar. failproofai_sdk.instrument("langchain") ``` -Errar isso e o processo roda com o SDK importado, o adaptador aparentemente instalado, e **nenhum evento emitido**. Ele registra um aviso dizendo exatamente isso — então verifique seus logs primeiro quando uma execução não registrar nada. +Erre isso e o processo roda com o SDK importado, o adaptador aparentemente instalado, e **nenhum evento emitido**. Ele registra um aviso dizendo exatamente isso — então verifique seus logs primeiro quando uma execução não registra nada. @@ -623,78 +623,80 @@ flowchart LR E -->|"HTTPS"| F["Cloud"] ``` -| Estágio | Função | Roda em | +| Estágio | Função | Executa em | | --- | --- | --- | | Adaptador | Traduz um callback do framework em um dos 15 tipos de evento | Seu processo | | Writer | Enfileira, agrupa, escreve JSONL atomicamente | Seu processo, thread em background | | Spool | Handoff durável, sobrevive ao encerramento do seu processo | Disco local | -| Daemon | Monitora o spool, envia lotes, deleta o que enviou | Sua máquina | -| Ingest | Atribui id de linha e chave de dedup, promove colunas consultáveis | Cloud | +| Daemon | Monitora o spool, envia batches, exclui o que enviou | Sua máquina | +| Ingest | Atribui um id de linha e chave de dedup, promove colunas consultáveis | Cloud | O spool é o que torna isso seguro: seu agente nunca bloqueia na rede, e uma interrupção do Cloud significa um diretório crescendo em vez de eventos perdidos. -Cada flush escreve um arquivo de lote, `.tmp` primeiro, depois `fsync`, depois um rename atômico: +Cada flush escreve um arquivo de batch, `.tmp` primeiro, depois `fsync`, depois um rename atômico: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -O daemon só lê `.jsonl`, então nunca pode ler um arquivo parcialmente escrito. O nome do arquivo carrega um timestamp, id de processo e número de sequência, então dois processos fazendo flush no mesmo milissegundo não podem colidir. A fila tem capacidade máxima de 10.000 eventos; além disso, descarta os mais antigos e registra um log. +O daemon só coleta `.jsonl`, então nunca pode ler um arquivo escrito parcialmente. O nome do arquivo carrega timestamp, id de processo e número de sequência, então dois processos fazendo flush no mesmo milissegundo não colidem. A fila está limitada a 10.000 eventos; além disso, descarta os mais antigos e registra um log. - **`collector.redact` não se aplica aos seus eventos do SDK.** Ele nunca os vê. + **`collector.redact` tem padrão `minimal` para eventos do SDK também.** O SDK + limpa antes de escrever um batch em disco, e o daemon repete a mesma + passagem determinística antes do upload para que batches de SDKs mais antigos sejam protegidos. -O daemon **envia** seus lotes. Ele não os abre nem os reescreve. +O daemon lê cada batch e aplica redação em memória antes do upload. Ele +não reescreve o arquivo de spool que leu. -| Eventos | Escritos por | Redacted por `collector.redact`? | +| Eventos | Escritos por | Onde a redação minimal é executada | | --- | --- | --- | -| Transcrições de sessão CLI | O daemon | Sim | -| Atividade de hook | O daemon | Sim | -| **Tudo que o SDK emite** | **Seu processo** | **Não** | +| Transcrições de sessão CLI | O daemon | Antes do daemon escrever o batch | +| Atividade de hook | O daemon | Antes do daemon escrever o batch | +| **Tudo que o SDK emite** | **Seu processo** | **Antes do SDK escrever o batch e novamente antes do upload do daemon** | -A redação roda onde o daemon *escreve* seus próprios eventos — não onde os lotes são *enviados*. Então um prompt ou argumento de ferramenta contendo uma chave de API ainda a contém na chegada. - -Isso é intencional. Estas são suas próprias chamadas de instrumentação, e reescrevê-las em trânsito significaria que os eventos que você recebe não são os eventos que você emitiu. +Defina `collector.redact` como `off` apenas quando payloads literais forem um requisito explícito; +o SDK e o daemon honram essa configuração. A redação minimal detecta chaves de API comuns, bearer tokens, JWTs e atribuições de segredos. Ela não consegue identificar prosa sensível arbitrária. - **Você controla os payloads na fonte, em dois lugares:** + **Você controla payloads na fonte, em dois lugares:** - - Desative a captura de conteúdo no adaptador. **O nome da opção é diferente, e um adaptador não tem nenhuma** — este não é um interruptor universal único: + - Desative a captura de conteúdo no adaptador. **O nome da opção é diferente, e um adaptador não tem nenhuma** — este não é um switch universal único: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **sem opção de conteúdo alguma**; `session_id` é a única opção que ele lê, então prompts e completions são sempre gravados. + - CrewAI — **nenhum switch de conteúdo**; `session_id` é a única opção que ele lê, então prompts e completions são sempre gravados. - `instrument()` descarta opções que um adaptador não lê, então passar o nome errado não lança nada e não altera nada. + `instrument()` descarta opções que um adaptador não lê, então passar o nome errado não lança nada e não muda nada. - Não passe o segredo para `input=` em primeiro lugar. - `collector.redact` não é substituto para nenhum dos dois. + `collector.redact` é defesa em profundidade, não substituto para nenhum dos dois. **Um diretório de spool vazio é o estado saudável.** Não o use para verificar a entrega. -O daemon deleta cada lote em milissegundos após enviá-lo, então um `ls` compete com o collector e mostra uma fração do que você emitiu — indistinguível de um SDK que não gravou nada. +O daemon exclui cada batch em milissegundos após enviá-lo, então um `ls` compete com o coletor e mostra uma fração do que você emitiu — indistinguível de um SDK que não registrou nada. -Para confirmar que os eventos realmente chegaram, verifique o dashboard. Para observar o spool enchendo, pare o daemon primeiro. +Para confirmar que os eventos realmente chegaram, verifique o dashboard. Para observar o spool se enchendo, pare o daemon primeiro. -Todo callback roda dentro de um wrapper cuja única função é relançar, então sua chamada fica em exatamente um `try` e tudo que o SDK faz acontece fora dele. +Todo callback executa dentro de um wrapper cujo único trabalho é relançar, então sua chamada fica em exatamente um `try` e tudo que o SDK faz acontece fora dele. | O que acontece | Resultado | | --- | --- | | Um hook lança | Registrado uma vez com seu traceback. Sua chamada não é afetada | -| O mesmo hook lança três vezes | Aquele hook é desabilitado pelo resto do processo, com uma linha de erro | +| O mesmo hook lança três vezes | Esse hook é desabilitado pelo restante do processo, com uma linha de erro | | `FAILPROOFAI_SDK_STRICT=1` está definido | A exceção é relançada em vez disso | -| Uma versão de framework está fora do intervalo testado | Avisa uma vez, instrumenta mesmo assim | -| Uma única capacidade está ausente | Apenas aquele hook é desabilitado, nunca o adaptador inteiro | +| Uma versão do framework está fora do intervalo testado | Avisa uma vez, instrumenta mesmo assim | +| Uma única capacidade está ausente | Apenas esse hook é desabilitado, nunca o adaptador inteiro | -O padrão é correto em produção e errado durante debug, porque só pode provar "não crashou". Defina `FAILPROOFAI_SDK_STRICT=1` para tornar uma falha engolida visível. +O padrão é correto em produção e errado durante a depuração, porque só pode provar que não travou. Defina `FAILPROOFAI_SDK_STRICT=1` para tornar uma falha engolida barulhenta. @@ -704,23 +706,23 @@ O padrão é correto em produção e errado durante debug, porque só pode prova - Um evento de abertura não tem evento de fechamento: um `model_request` sem `model_response`, ou um `tool_use` sem `tool_result`. Use os escopos, que garantem o par mesmo quando o corpo lança uma exceção. Se você chamar os métodos de evento diretamente, use `try` e `finally`. + Um evento de abertura não tem evento de fechamento correspondente: um `model_request` sem `model_response`, ou um `tool_use` sem `tool_result`. Use os escopos, que garantem o par mesmo quando o corpo lança uma exceção. Se você chamar os métodos de evento diretamente, use `try` e `finally`. - - É medido a partir do evento de abertura correspondente, então é rejeitado em `tool_result`, `hook_completed`, `agent_resume` e `human_input`. É aceito em `model_response`, porque apenas você conhece a latência real do provedor, e deve ser um inteiro. + + Ele é medido a partir do evento de abertura correspondente, então é rejeitado em `tool_result`, `hook_completed`, `agent_resume` e `human_input`. É aceito em `model_response`, porque somente você conhece a latência real do provedor, e deve ser um inteiro. - - A thread nunca herdou o contexto. Envolva o callable em `failproofai_sdk.propagate()`. Veja [Threads e async](#threads-and-async). + + A thread nunca herdou o contexto. Envolva o callable em `failproofai_sdk.propagate()`. Consulte [Threads e async](#threads-and-async). - Campos extras são mesclados por último, então um nomeado como um campo real, como `model` ou `outcome`, o sobrescreveria e alteraria uma coluna armazenada. Use um namespace nos seus; os adaptadores usam o prefixo `fw_`. + Campos extras são mesclados por último, então um nomeado como um campo real, como `model` ou `outcome`, o sobrescreveria e alteraria uma coluna armazenada. Use um namespace para os seus; os adaptadores usam o prefixo `fw_`. - `agent_id` é uma faceta de baixa cardinalidade e você colocou um id de execução nela. Use um nome de role ou nó e coloque o id real em um campo de payload. + `agent_id` é uma faceta de baixa cardinalidade e você colocou um id de execução nele. Use um nome de papel ou nó e coloque o id real em um campo de payload. @@ -728,7 +730,7 @@ O padrão é correto em produção e errado durante debug, porque só pode prova - Pares, ids, ciclo de vida da sessão e entrega. + Pares, ids, ciclo de vida de sessão e entrega. Siga a causalidade pela sessão que você acabou de capturar. diff --git a/docs/ru/start/integrations/custom-agents.mdx b/docs/ru/start/integrations/custom-agents.mdx index 17b107d2..38170069 100644 --- a/docs/ru/start/integrations/custom-agents.mdx +++ b/docs/ru/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "Пользовательские агенты" sidebarTitle: "Пользовательские агенты" -description: "Инструментируйте агента, который вы написали сами, или фреймворк без адаптера." +description: "Инструментируйте агента, написанного вами самим, или фреймворк, для которого нет адаптера." icon: "code" --- -Для агента, который вы написали сами, или фреймворка, для которого у Failproof AI нет адаптера. Инструментировать нечего — вы сами генерируете события. +Для агента, написанного вами самим, или фреймворка, для которого у Failproof AI нет адаптера. Здесь нечего инструментировать: вы сами испускаете события. -Это тот же API, который используют четыре адаптера фреймворков. Они — таблицы трансляции над ним. +Это тот же API, который используют четыре встроенных адаптера фреймворков. Они — таблицы трансляции над ним. ## Установка @@ -15,9 +15,9 @@ icon: "code" pip install failproofai-sdk ``` -Никаких дополнений и зависимостей. +Без дополнительных зависимостей. -## Инструментирование +## Инструментация ```python import failproofai_sdk @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # один запуск t.output = search(q) # один вызов инструмента ``` -Читайте сверху вниз — и станет ясно, что это означает: +Читайте сверху вниз — это говорит, что имеется в виду: | Оберните в | Чтобы сказать | | --- | --- | -| `session()` | Эти события принадлежат одному запуску | -| `agent()` | Что-то выполняет работу — дайте ему имя, которое вы узнаете в списке | +| `session()` | Эти события относятся к одному запуску | +| `agent()` | Что-то работает — дайте ему имя, которое вы узнаете в списке | | `tool_call()` | Это один инструмент и вот что он вернул | -И что каждый из них фактически генерирует: +И что каждый из них на самом деле испускает: -| Область | Генерирует | Назначение | +| Область | Испускает | Назначение | | --- | --- | --- | -| `session()` | Ничего | Привязывает session id, группируя один запуск | -| `agent()` | `agent_start`, `agent_end` | Ограничивает единицу работы | -| `tool_call()` | `tool_use`, `tool_result` | Ограничивает один инструмент и его результат | +| `session()` | Ничего | Привязывает идентификатор сессии, группирует один запуск | +| `agent()` | `agent_start`, `agent_end` | Обрамляет единицу работы | +| `tool_call()` | `tool_use`, `tool_result` | Обрамляет один инструмент и измеряет его | -Всё внутри может опустить `session_id` и `agent_id`. Области привязывают идентификацию на переменные контекста и каждый вызов события читает её обратно, поэтому вам никогда не нужно передавать id через функции. +Всё внутри может опустить `session_id` и `agent_id`. Области привязывают идентичность к переменным контекста, и каждый вызов события считывает её обратно, поэтому вы никогда не передаёте идентификаторы через функции. -Все три работают с `async with` наравне с `with`. +Все три работают как с `async with`, так и с `with`. -Вложенные агенты строят дерево. `parent_id` и глубина вычисляются из стека: +Вложение агентов строит дерево. `parent_id` и глубина вычисляются из стека: ```python with failproofai_sdk.session(): @@ -59,7 +59,7 @@ with failproofai_sdk.session(): ... ``` -## Как закрывается область +## Как область закрывается `agent()` обрабатывает исключения за вас: @@ -70,35 +70,35 @@ with failproofai_sdk.session(): | `KeyboardInterrupt`, `SystemExit` | `error`, затем `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | только `agent_end` | `cancelled` | -Ошибка генерируется перед `agent_end`, потому что панель управления закрывает span при `agent_end` и всё после этого не атрибутируется ничему. Отмена — не ошибка, поэтому отменённые запуски не загромождают поверхность ошибок. Исключение всегда переиспускается: область никогда его не подавляет. +Ошибка испускается до `agent_end`, потому что панель закрывает span на `agent_end`, и всё после этого атрибутируется ничему. Отмена — не неудача, поэтому отменённые запуски не загрязняют поверхность ошибок. Исключение всегда переиспускается: область никогда не глушит. -## Методы события +## Методы событий -Пятнадцать методов в шести семействах. Большинство идут парами — вы генерируете открывающее событие, затем закрывающее, и SDK измеряет промежуток между ними. +Пятнадцать методов в шести семействах. Большинство идут парами — вы испускаете открытие, затем закрытие, и SDK измеряет промежуток между ними. -| Семейство | Открывает | Закрывает | Самостоятельное | +| Семейство | Открывает | Закрывает | Самостоятельно | | --- | --- | --- | --- | -| **Agents** | `agent_start` | `agent_end` | — | +| **Агенты** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | -| **Models** | `model_request` | `model_response` | — | -| **Tools** | `tool_use` | `tool_result` | — | +| **Модели** | `model_request` | `model_response` | — | +| **Инструменты** | `tool_use` | `tool_result` | — | | **Hooks** | `hook_triggered` | `hook_completed` | — | -| **Humans** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | -| **Failures** | — | — | `error` | +| **Люди** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **Ошибки** | — | — | `error` | - Предпочитайте области — `agent()` и `tool_call()` — везде, где они подходят. Они гарантируют закрывающее событие даже когда тело выбрасывает исключение. Обращайтесь к этим методам напрямую, когда ваш управляющий поток не вложен, например вызов модели внутри вспомогательной функции. + Предпочитайте области — `agent()` и `tool_call()` — где они подходят. Они гарантируют событие закрытия даже если тело возбуждает исключение. Обращайтесь к этим методам напрямую, когда ваш поток управления не вложен, например вызов модели внутри вспомогательной функции. -```python Agents +```python Агенты failproofai_sdk.event.agent_start(agent_id="planner", goal="find the cheapest flight") failproofai_sdk.event.agent_end(agent_id="planner", outcome="success", summary="...") failproofai_sdk.event.agent_pause(pause_id="p1", reason="awaiting approval") failproofai_sdk.event.agent_resume(pause_id="p1") ``` -```python Models +```python Модели failproofai_sdk.event.model_request( model="gpt-4o-mini", messages=[{"role": "user", "content": "..."}], @@ -114,7 +114,7 @@ failproofai_sdk.event.model_response( ) ``` -```python Tools +```python Инструменты failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1", input={"q": "..."}) failproofai_sdk.event.tool_result(tool_name="search", tool_call_id="c1", output="...") ``` @@ -124,14 +124,14 @@ failproofai_sdk.event.hook_triggered(hook_name="retrieve", hook_id="h1", trigger failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome="success") ``` -```python Humans +```python Люди failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") failproofai_sdk.event.human_interrupt(reason="operator stopped the run", at_step="step_3") ``` -```python Failures +```python Ошибки failproofai_sdk.event.error( error_type="TimeoutError", message="provider timed out after 30s", @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **Два семейства human указывают в противоположных направлениях.** + **Два семейства «люди» указывают в противоположные стороны.** | Методы | Значение | | --- | --- | - | `human_wait` / `human_input` | **Агент попросил человека** — ворота одобрения, уточняющий вопрос | - | `human_pause` / `human_interrupt` | **Человек действовал на агента** — кнопка остановки, пауза оператора | + | `human_wait` / `human_input` | **Агент попросил человека** — врата одобрения, уточняющий вопрос | + | `human_pause` / `human_interrupt` | **Человек действовал на агента** — кнопка стоп, пауза оператора | - Ни один фреймворк не сигнализирует вторую пару, поэтому её всегда нужно генерировать вам. + Ни один фреймворк не сигнализирует вторую пару, поэтому вы всегда испускаете её. - **Передавайте `request_id` когда вызовы модели выполняются одновременно.** Без него запросы и ответы сопряжаются в порядке поступления за агента — и одновременные вызовы неправильно сопрягаются, присоединяя каждый ответ к неправильному запросу. + **Передавайте `request_id` когда вызовы модели выполняются одновременно.** Без него запросы и ответы согласуются в порядке прихода на агента — и одновременные вызовы не согласуются, каждый ответ прикрепляется к неправильному запросу. ## Пример -Цикл вызовов инструментов против OpenAI API без фреймворка агента: +Цикл вызовов инструментов с API OpenAI без фреймворка агента: ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """Один вызов модели, ограниченный парой событий.""" + """Один вызов модели, обрамлённый парой.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # ограниченное количество; бесконечный цикл агента — его собственная ошибка + for _ in range(4): # ограничено; неограниченный цикл агента — его собственная ошибка message = turn(messages) if not message.tool_calls: break @@ -204,44 +204,44 @@ with failproofai_sdk.session(): }) ``` -Это генерирует те же шесть типов событий, которые даст адаптер. Полная рабочая версия с определениями инструментов поставляется в репозитории SDK в `docs/manual/examples/`. +Это производит те же шесть типов событий, которые дал бы адаптер. Полная исполняемая версия с определениями инструментов поставляется в репозитории SDK в `docs/manual/examples/`. ## Потоки и async -Переменные контекста автоматически распространяются в asyncio задачи. Они не распространяются в новые потоки, потому что поток начинается с пустым контекстом. +Переменные контекста распространяются в задачи asyncio автоматически. Они не распространяются в новые потоки, потому что поток начинается с пустым контекстом. ```python # asyncio: ничего не нужно делать async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads: оберните callable +# потоки: оберните вызываемое pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Без `propagate()` события рабочего выбросят `TypeError` с названием исправления вместо приземления без session. Это намеренно: событие без session пропускается при обработке и ему ответили `200`, что — это скрытый отказ, который существует уровень идентификации чтобы предотвратить. +Без `propagate()` события рабочего возбуждают `TypeError`, называя исправление, а не приземляются без сессии. Это намеренно: событие без сессии пропускается при приёме и отвечается `200`, что является молчаливой неудачей, которую предотвращает слой идентичности. -## Инструментирование фреймворка без адаптера +## Инструментируйте фреймворк без адаптера -Каждый фреймворк агента даёт вам те же три точки. Отобразите их — и у вас есть полная трассировка. Четыре поставляемых адаптера делают ровно это. +Каждый фреймворк агентов даёт вам одни и те же три точки соединения. Отобразите их — и у вас есть полная трассировка — четыре встроенных адаптера ничего больше не делают. -| Точка | Что вы пишете | Что попадает | +| Точка соединения | Что вы пишете | Что приземляется | | --- | --- | --- | | Запуск | `session()` + `agent()` | `agent_start`, `agent_end` | | Каждый инструмент | `tool_call()` | `tool_use`, `tool_result` | | Каждый вызов модели | Пара `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - + В чём бы фреймворк ни называл обёртку инструмента или middleware. ```python @@ -249,7 +249,7 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -264,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **Есть граница узла, шага или middleware, достойная внимания?** Оберните её в пару hook — `hook_triggered` / `hook_completed` — а не вложенный `agent()`. `agent_id` — низко-кардинальный фасет, и одна запись на узел его захламляет. Span-ы hook отображаются так же и дают вам задержку за узел. + **Есть граница узла, шага или middleware, достойная внимания?** Оберните её в пару hook — `hook_triggered` / `hook_completed` — а не вложенный `agent()`. `agent_id` — низкокардинальный аспект, и одна запись на узел его топит. Spans hook отображаются одинаково и дают вам задержку на узел. - **Ручное и автоматическое взаимодействуют.** Адаптер, работающий внутри ручной области, присоединяется к этой session и становится родителем этого агента, поэтому вы получаете одно дерево вместо двух — это полезно когда вы инструментируете один фреймворк сами наряду с поддерживаемым. + **Ручная и автоматическая комбинируются.** Адаптер, работающий внутри написанной вручную области, присоединяется к этой сессии и становится родителем этому агенту, так что вы получаете одно дерево вместо двух — полезно когда вы инструментируете один фреймворк сами рядом с поддерживаемым. - Две причины, и три точки выше — ответ на обе: + Две причины, и три точки соединения выше — ответ на обе: - `autogen-core` не обслуживается с сентября 2025. - - AG2 не раскрывает точку регистрации масштаба процесса, эквивалентную хукам других фреймворков, поэтому инструментирование означает обёртывание каждого агента на каждом месте конструирования. + - AG2 не предоставляет глобальную точку регистрации, эквивалентную hooks других фреймворков, поэтому инструментация означает обёртывание каждого агента в каждом месте конструкции. - Ручное отображение точек записывает те же события с той же точностью, что и поставляемый адаптер. + Отображение точек соединения вручную записывает те же события с той же полнотой, что делал бы встроенный адаптер. ## Глубже -Как запись фактически работает. Ничего из этого не требуется для начала. +Как запись на самом деле работает. Ничего из этого не требуется для начала. - + -Каждая запись имеет одну форму: span открывается, работа вложена внутри, и каждому открывающему событию соответствует закрывающее. +Каждая запись имеет одну форму: span открывается, работа вложена в него, и каждое открывающее событие получает закрывающее. ```mermaid flowchart LR @@ -300,13 +300,13 @@ flowchart LR C --> E(["agent_end"]) ``` -**Пара** — это единица. Каждое закрывающее событие несёт длительность, которую SDK измеряет от открывающего. +**Пара** — это единица. Каждое закрывающее событие несёт продолжительность, которую SDK измеряет от открывающего события. -Ниже один реальный запуск на фреймворк — захвачен из примеров, которые поставляются с SDK, имя модели нормализовано. Обратите внимание, сколько возвращается из одного вызова. +Ниже — один реальный запуск на фреймворк — захвачен из примеров, поставляемых с SDK, имя модели нормализовано. Обратите внимание, сколько возвращается из одного вызова. - ```text 14 events + ```text 14 событий 1 +0.000s agent_start LangGraph 2 +0.001s hook_triggered agent 3 +0.002s model_request gpt-4o-mini @@ -323,11 +323,11 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - Узлы становятся парами hook, поэтому вы получаете задержку за узел без того, чтобы они загромождали список агентов. + Узлы становятся парами hook, так что вы получаете задержку на узел без их переполнения списка агентов. - ```text 10 events + ```text 10 событий 1 +0.000s agent_start crew 2 +0.050s agent_start analyst · under crew 3 +0.057s model_request gpt-4o-mini @@ -340,11 +340,11 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - Каждый `role` агента становится имя span-а, поэтому задержка и трата токенов разбиваются по role. + `role` каждого агента становится именем его span, так что задержка и трата токенов разбиваются на роль. - ```text 26 events + ```text 26 событий 1 +0.000s agent_start Agent 2 +0.001s hook_triggered init_run 4 +0.501s hook_triggered setup_agent @@ -356,15 +356,15 @@ flowchart LR 13 +3.355s tool_use city_population 14 +3.355s tool_result city_population · ok 16 +3.356s hook_triggered aggregate_tool_results - ... second iteration + ... вторая итерация 26 +7.038s agent_end Agent · success ``` - Цикл агента сам видим, не только его вызовы модели. + Цикл агента видим сам, не только его вызовы модели. - ```text 8 events + ```text 8 событий 1 +0.000s agent_start agent 2 +0.001s model_request gpt-4o-mini 3 +4.413s model_response gpt-4o-mini · 17 out-tok @@ -375,11 +375,11 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - Нет пар hook: Pydantic AI не имеет границы узла или шага для ограничения. + Нет пар hook: Pydantic AI не имеет границы узла или шага для обрамления. - - ```text 6 events + + ```text 6 событий 1 +0.000s agent_start main 2 +0.000s tool_use population 3 +0.000s tool_result population · ok @@ -388,36 +388,36 @@ flowchart LR 6 +0.000s agent_end main · success ``` - Вы генерируете их сами. Те же типы событий, та же точность — это стоит вам мест вызовов. + Вы испускаете их сами. Те же типы событий, та же полнота — это стоит вам вызовов. - + -**Нет события завершения session.** Session — это не то, что вы закрываете — это группа событий, разделяющих `session_id`. +**Нет события конца сессии.** Сессия — это не то, что вы закрываете — это группа событий, делящих `session_id`. Статус выводится из формы трассировки: | Статус | Когда | | --- | --- | -| `ongoing` | По крайней мере один span всё ещё открыт | -| `paused` | `agent_pause` не имеет соответствующей `agent_resume` | -| `error` | Ничего не открыто и по крайней мере одно событие не прошло | -| `done` | Ничего не открыто и ничего не провалилось | +| `ongoing` | По крайней мере один span ещё открыт | +| `paused` | `agent_pause` не имеет согласованного `agent_resume` | +| `error` | Ничего не открыто, и по крайней мере одно событие не удалось | +| `done` | Ничего не открыто, и ничего не не удалось | -Поэтому session заканчивается когда каждая пара закрыта. Адаптеры генерируют `agent_end` для вас, и при завершении они закрывают всё ещё открытое и отмечают его неполным — упавший запуск урегулируется как `done` с видимым пробелом вместо вечного зависания. +Поэтому сессия заканчивается, когда каждая пара закрыта. Адаптеры испускают `agent_end` за вас, и при разборке они закрывают всё ещё открытое и отмечают его неполным — сбойный запуск устанавливается как `done` с видимым промежутком вместо вечного зависания. - Вот почему session может охватывать два вызова. `interrupt()` LangGraph пауза запуска, root span намеренно остаётся открыт, и возобновляющий вызов его закрывает. Оба вызова — одна session. + Вот почему сессия может охватывать два вызова. LangGraph `interrupt()` приостанавливает запуск, корневой span намеренно остаётся открыт, и возобновляющий вызов закрывает его. Оба вызова — одна сессия. - + -`session_id` и `agent_id` опциональны для каждого метода события. Опущены — они разрешаются из вмещающей области: +`session_id` и `agent_id` необязательны на каждом методе события. Опущены, они разрешаются из области охватывающей: ```python with failproofai_sdk.session(): @@ -425,50 +425,50 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Их явная передача всё ещё работает и имеет приоритет. Без привязанного и без переданного вызов выбросит `TypeError` с названием исправления вместо того чтобы генерировать событие без session, которое ingest пропустит при ответе `200`. +Передача их явно всё ещё работает и имеет приоритет. Ничто не привязано и ничто не передано — вызов возбуждает `TypeError`, называя исправление, а не испускает событие без сессии, которое инgest пропустит отвечая `200`. -Области привязывают идентификацию на переменные контекста. Они распространяются в asyncio задачи автоматически но не в новые потоки — оберните рабочего в `failproofai_sdk.propagate()`. +Области привязывают идентичность к переменным контекста. Те распространяются в задачи asyncio автоматически но не в новые потоки — оберните рабочего в `failproofai_sdk.propagate()`. #### Кто создаёт какой id -| Id | Создан | Заметки | +| Id | Создано | Примечания | | --- | --- | --- | -| `session_id` | Вы или SDK | `session("chat-42")` используется как есть; опущен, SDK генерирует `uuid4().hex` | -| `agent_id` | Вы или фреймворк | От `agent("analyst")`, CrewAI `role`, имя `FunctionAgent.name`. UUID-подобное значение отклоняется и заменяется | -| `tool_call_id`, `hook_id`, `request_id` | Вы или фреймворк | Адаптеры переиспользуют собственные id запуска фреймворка, вот почему пары выживают переходы через потоки | -| **Event id** | **Cloud at ingest** | SDK не генерирует | -| **`dedup_key`** | **Cloud at ingest** | Хеш org, session, timestamp, type и payload. Это реальная идентификация — делает повторённую партию коллапсом вместо дублирования | +| `session_id` | Вы или SDK | `session("chat-42")` используется дословно; опущено, SDK генерирует `uuid4().hex` | +| `agent_id` | Вы или фреймворк | Из `agent("analyst")`, `role` CrewAI, `FunctionAgent.name`. Значение похожее на UUID отклоняется и заменяется | +| `tool_call_id`, `hook_id`, `request_id` | Вы или фреймворк | Адаптеры переиспользуют собственные run ids фреймворка, вот почему пары выживают прыжки потоков | +| **Event id** | **Cloud при приёме** | SDK не испускает ни один | +| **`dedup_key`** | **Cloud при приёме** | Хеш org, сессии, временной метки, типа и полезной нагрузки. Это реальная идентичность — она заставляет переданный batch схлопнуться вместо дублирования | #### Как адаптеры разрешают `session_id` Первое совпадение выигрывает: -1. Явная опция `session_id` -2. Per-call метаданные -3. Вмещающая область `session()` +1. Явное значение `session_id` +2. Метаданные по вызову +3. Область охватывающая `session()` 4. Метаданные фреймворка 5. Собственный run id фреймворка -Она никогда не синтезируется пока одна из них существует — синтезированный id расколол бы один запуск на несколько session. +Это никогда не выдумывается пока существует одно из них — синтезированный id разделил бы один запуск на несколько сессий. -#### Держите `agent_id` низко-кардинальным +#### Держите `agent_id` низкокардинальным -Это первичный фасет на каждой поверхности панели управления и `LowCardinality(String)` колонка. Per-run значение деградирует колонку и заполняет выпадающий фильтр одной записью за запуск. +Это первичный аспект на каждой поверхности панели, и колонка `LowCardinality(String)`. Значение на запуск деградирует колонку и заполняет раскрывающееся меню фильтра одной записью на запуск. -Адаптеры защищают эту колонку для вас: +Адаптеры защищают эту колонку за вас: -| Фреймворк передаёт | Записано как | Почему | +| Фреймворк передаёт | Записывается как | Почему | | --- | --- | --- | -| `3f9a1c2b-…` (UUID) | `main` | Нечего читаемого хранить | -| Долгая чистая hex строка | `main` | То же самое | -| `agent-3f9a1c2b-…` | `agent` | Per-run id удалён, читаемая часть сохранена | -| `agent-v2` | `agent-v2` | Короткие сегменты оставлены одни | -| `step-3` | `step-3` | То же самое | +| `3f9a1c2b-…` (UUID) | `main` | Нечего читаемое держать | +| Длинная голая hex-строка | `main` | То же | +| `agent-3f9a1c2b-…` | `agent` | Id на запуск убран, читаемая часть сохранена | +| `agent-v2` | `agent-v2` | Короткие сегменты оставлены в покое | +| `step-3` | `step-3` | То же | -Реальный id хранится на `fw_agent_id` / `fw_run_id`, где остаётся queryable без того чтобы быть фасетом. +Реальный id сохранён на `fw_agent_id` / `fw_run_id`, где он остаётся запрашиваемым без того, чтобы быть аспектом. - **Эта защита только трогает ярлыки, которые **фреймворк** выбрал.** `agent_id`, который вы сами передали — в `event.*` или в `failproofai_sdk.agent(...)` — записывается ровно как дано. Молчаливое переписывание явного аргумента было бы хуже чем кардинальность, которую оно предотвращает, поэтому называйте ваши span-ы сами соответственно. + **Эта защита трогает только ярлыки, выбранные *фреймворком*.** `agent_id`, который вы передали сами — в `event.*` или в `failproofai_sdk.agent(...)` — записывается ровно как дано. Молчаливая переделка явного аргумента хуже кардинальности, которую она предотвращает, поэтому назовите свои spans соответственно. @@ -477,77 +477,77 @@ with failproofai_sdk.session(): | Группа | События | | --- | --- | -| Agents | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | -| Models | `model_request`, `model_response` | -| Tools | `tool_use`, `tool_result` | +| Агенты | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| Модели | `model_request`, `model_response` | +| Инструменты | `tool_use`, `tool_result` | | Hooks | `hook_triggered`, `hook_completed` | -| Humans | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | -| Failures | `error` | +| Люди | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| Ошибки | `error` | -Какой фреймворк что записывает, измеренный от запусков выше: +Какой фреймворк что записывает, измеренное из запусков выше: -| События | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | +| Событие | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | -| Старт и конец агента | Yes | Yes | Yes | Yes | You | -| Запрос и ответ модели | Yes | Yes | Yes | Yes | You | -| Использование и результат инструмента | Yes | Yes | Yes | Yes | You | -| Hook triggered и completed | Node | Task | Step | — | You | -| Error | Yes | Yes | Yes | Yes | Automatic | -| Human wait и input | Yes | Yes | Yes | — | You | -| Agent pause и resume | Yes | Yes | Yes | — | You | +| Начало и конец агента | Да | Да | Да | Да | Вы | +| Запрос и ответ модели | Да | Да | Да | Да | Вы | +| Использование и результат инструмента | Да | Да | Да | Да | Вы | +| Hook триггер и завершение | Узел | Задача | Шаг | — | Вы | +| Ошибка | Да | Да | Да | Да | Автоматически | +| Ожидание и ввод человека | Да | Да | Да | — | Вы | +| Пауза и возобновление агента | Да | Да | Да | — | Вы | -Тире означает фреймворк не имеет такой концепции. `human_pause` и `human_interrupt` описывают **человека**, действующего на агента, что ни один фреймворк не сигнализирует — генерируйте их сами. +Прочерк означает, что фреймворк не имеет такой концепции. `human_pause` и `human_interrupt` описывают *человека*, действующего на агента, что ни один фреймворк не сигнализирует — испускайте их сами. - + -Событие никогда не приходит одно. Одно открывает span, одно закрывает его, и закрывающее событие несёт длительность, которую SDK измеряет от открывающего. +Событие никогда не прибывает одно. Одно открывает span, одно закрывает его, и закрывающее событие несёт продолжительность, которую SDK измеряет от открывающего. | Открывает | Закрывает | Закрывающее событие несёт | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | -| `model_request` | `model_response` | токены, `stop_reason`, задержка | -| `tool_use` | `tool_result` | `output` или `error`, длительность | -| `hook_triggered` | `hook_completed` | `outcome`, длительность | -| `agent_pause` | `agent_resume` | как долго пауза длилась | -| `human_wait` | `human_input` | ответ и как долго человек занимал | +| `model_request` | `model_response` | токены, `stop_reason`, задержку | +| `tool_use` | `tool_result` | `output` или `error`, продолжительность | +| `hook_triggered` | `hook_completed` | `outcome`, продолжительность | +| `agent_pause` | `agent_resume` | как долго длилась пауза | +| `human_wait` | `human_input` | ответ и как долго человек ждал | - Открывающее событие без закрывающего — это span, который никогда не завершается. Session отображается как всё ещё работающий, навсегда, и его активная длительность продолжает расти. Это режим отказа, за которым нужно следить когда вы инструментируете вручную. + Открывающее событие без закрывающего — это span, который никогда не заканчивается. Сессия отображается всё ещё работающей вечно, и её активная продолжительность растёт. Это режим неудачи, который нужно наблюдать при инструментации вручную. #### Правила корреляции -- Переиспользуйте тот же `tool_call_id`, `hook_id`, `pause_id` или `input_id` для соответствующего события завершения. -- SDK вычисляет `duration_ms` для `tool_result`, `hook_completed`, `agent_resume` и `human_input`. Передача его этим методам выбросит `ValueError`. -- `duration_ms` **принят** на `model_response`, потому что только вызывающий знает реальную задержку провайдера. Это должно быть целое число — float выбросит `ValueError` на месте вызова, потому что сервер читает колонку как 32-битное целое число без знака и сохранит NULL для чего-либо ещё. -- Ключи корреляции ограничены видом и session, поэтому вызов инструмента и hook могут безопасно разделить id, и две одновременные session могут переиспользовать те же id без столкновения. Они не ограничены агентом: пара открытая под одним агентом и закрытая под другим всё ещё коррелирует, это обычный случай в multi-agent фреймворках. -- `request_id` сопрягает `model_request` с `model_response`. Без него события модели сопрягаются в порядке за агента, поэтому одновременные вызовы неправильно сопрягаются. -- Пара разделённая через процессы всё ещё коррелирует downstream, но SDK не может вычислить её in-process длительность. -- Ожидающая карта держит максимум 10,000 стартов и вытеснит самую старую запись когда полна. +- Переиспользуйте то же `tool_call_id`, `hook_id`, `pause_id` или `input_id` для согласованного события завершения. +- SDK вычисляет `duration_ms` для `tool_result`, `hook_completed`, `agent_resume` и `human_input`. Передача его этим методам возбуждает `ValueError`. +- `duration_ms` **принимается** на `model_response`, потому что только вызывающий знает реальную задержку провайдера. Это должно быть целое число — float возбуждает `ValueError` на месте вызова, потому что сервер читает колонку как беззнаковое 32-битное целое и хранил бы NULL для чего-либо ещё. +- Ключи корреляции ограничены типом и сессией, поэтому вызов инструмента и hook могут безопасно делить id, и две одновременные сессии могут переиспользовать одни и те же ids без коллизий. Они не ограничены агентом: пара открытая под одним агентом и закрытая под другим всё ещё коррелирует, что обычно в мультиагентных фреймворках. +- `request_id` согласует `model_request` с `model_response`. Без него события модели согласуются по порядку на агента, поэтому одновременные вызовы не согласуются. +- Пара, разделённая процессами, всё ещё коррелирует ниже по течению, но SDK не может вычислить её в процессе продолжительность. +- Карта ожидания содержит максимум 10 000 начал и вытесняет самую старую запись когда полна. -Установка `failproofai-sdk` устанавливает всё, все четыре адаптера включены. Extras вытягивают **фреймворк**, а не адаптер. +Установка `failproofai-sdk` устанавливает всё, все четыре адаптера включены. Extras тянут **фреймворк**, не адаптер. ```python -import failproofai_sdk # загружает ничего вне стандартной библиотеки -failproofai_sdk.instrument() # импортирует только адаптеры, которые вам фактически нужны +import failproofai_sdk # ничего за пределами стандартной библиотеки +failproofai_sdk.instrument() # импортирует только адаптеры, которые вы фактически используете ``` -`import failproofai_sdk` контрактно ноль-зависимости, принудительно тестом который устанавливает построенное колесо с `--no-deps` и другое которое доказывает что ни один фреймворк не достигает `sys.modules`. +`import failproofai_sdk` контрактно беззависимость, обеспечено тестом, который устанавливает встроенное колесо с `--no-deps` и другим, который доказывает что ни один фреймворк не достигает `sys.modules`. - Нет атрибута `failproofai_sdk.crewai`. Адаптеры намеренно не раскрыты на пакете верхнего уровня: трогание одного импортировало бы фреймворк как побочный эффект доступа атрибута, ломая ноль-зависимость обещание. Используйте `instrument()`. + Нет атрибута `failproofai_sdk.crewai`. Адаптеры намеренно не выставлены на пакет верхнего уровня: трогание одного импортировало бы фреймворк как побочный эффект доступа атрибута, нарушая обещание беззависимости. Используйте `instrument()`. ```python failproofai_sdk.instrument() # каждый фреймворк уже импортирован -failproofai_sdk.instrument("crewai") # ровно один, по имени -failproofai_sdk.uninstrument("crewai") # вернуть его +failproofai_sdk.instrument("crewai") # ровно один по имени +failproofai_sdk.uninstrument("crewai") # верните его обратно ``` | Имя | Также принимает | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # вернуть его | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -Auto-detection читает `sys.modules`, не список установленных пакетов, поэтому фреймворк, который вы установили но никогда не импортировали, не инструментируется и никогда не импортируется от вашего имени. Чтобы увидеть что подключено: +Автообнаружение читает `sys.modules`, не список установленных пакетов, поэтому фреймворк, который вы установили но никогда не импортировали, не инструментируется и никогда не импортируется вашим именем. Чтобы видеть, что подключено: ```python from failproofai_sdk.integrations import active, available @@ -567,46 +567,46 @@ active() # ('langchain',) ``` - **`instrument("crewai")` на машине без CrewAI не выбросит.** Это логирует предупреждение и возвращает `()`, поэтому один отсутствующий фреймворк никогда не возьмёт процесс который также инструментирует других. + **`instrument("crewai")` на машине без CrewAI не возбуждает.** Оно логирует предупреждение и возвращает `()`, поэтому один отсутствующий фреймворк никогда не снимает процесс, который также инструментирует других. - Предупреждение несёт базовую `ImportError`, и это сообщение называет точную команду установки — поэтому исправление в ваших логах, не спрятано. + Предупреждение несёт основной `ImportError`, и то сообщение называет точную команду установки — так что исправление в ваших логах, не спрятано. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Установите `FAILPROOFAI_SDK_STRICT=1` чтобы это выбросило вместо этого. Этот флаг читается **один раз и кэшируется**, поэтому экспортируйте его перед тем как ваш процесс начнётся вместо того чтобы устанавливать mid-run. + Установите `FAILPROOFAI_SDK_STRICT=1` чтобы заставить её возбуждать вместо этого. Этот флаг читается **один раз и кешируется**, поэтому экспортируйте его перед началом вашего процесса вместо установки посредине запуска. - **`instrument()` должен прийти *после* вашего импорта фреймворка.** Auto-detection читает `sys.modules`, поэтому чистый вызов выше импорта находит ничего, устанавливает ничего, и возвращает `()`. + **`instrument()` должен идти *после* импорта вашего фреймворка*.** Автообнаружение читает `sys.modules`, поэтому голый вызов выше импорта находит ничего, устанавливает ничего и возвращает `()`. -```python Wrong +```python Неправильно import failproofai_sdk failproofai_sdk.instrument() # sys.modules ещё не имеет langchain -> () import langchain # слишком поздно, ничего не подключено ``` -```python Right +```python Правильно import langchain # импортируйте фреймворк первым import failproofai_sdk failproofai_sdk.instrument() # находит его -> ('langchain',) ``` -```python Right, order-proof +```python Правильно, порядок-доказательство import failproofai_sdk -# Называние этого импортирует адаптер по запросу, поэтому это работает отовсюду. +# Называние его импортирует адаптер по запросу, поэтому это работает откуда угодно. failproofai_sdk.instrument("langchain") ``` -Получите это неправильно и процесс работает с импортированным SDK, видимо установленным адаптером, и **не одно событие не генерируется**. Это логирует предупреждение говоря ровно это — поэтому проверьте ваши логи первым когда запуск ничего не записывает. +Ошибитесь в этом и процесс работает с импортированным SDK, адаптер видимо установлен, и **ни одно событие не испущено**. Оно логирует предупреждение говоря ровно это — так что сначала проверьте ваши логи когда запуск ничего не записывает. @@ -614,122 +614,120 @@ failproofai_sdk.instrument("langchain") ```mermaid flowchart LR - A["Your agent"] --> B["Adapter"] - B --> C["Writer
in-memory queue"] - C -->|"every 0.5s"| D["Spool
JSONL on disk"] - D --> E["Failproof daemon"] + A["Ваш агент"] --> B["Адаптер"] + B --> C["Писатель
очередь в памяти"] + C -->|"каждые 0.5s"| D["Катушка
JSONL на диске"] + D --> E["Daemon Failproof"] E -->|"HTTPS"| F["Cloud"] ``` -| Этап | Работа | Работает в | +| Этап | Задача | Работает в | | --- | --- | --- | -| Adapter | Переводит обратный вызов фреймворка в один из 15 типов событий | Ваш процесс | -| Writer | Очереди, батчи, писать JSONL атомарно | Ваш процесс, фоновый поток | -| Spool | Прочная передача, выживает выход вашего процесса | Локальный диск | -| Daemon | Следит за spool, доставляет батчи, удаляет то что он доставил | Ваша машина | -| Ingest | Присваивает row id и dedup key, рекламирует queryable колонки | Cloud | +| Адаптер | Переводит callback фреймворка в один из 15 типов событий | Ваш процесс | +| Писатель | Ставит в очередь, батчит, пишет JSONL атомарно | Ваш процесс, фоновый поток | +| Катушка | Прочная передача, выживает выход вашего процесса | Локальный диск | +| Daemon | Смотрит на катушку, отправляет батчи, удаляет отправленное | Ваша машина | +| Приём | Назначает id строки и ключ dedup, повышает запрашиваемые колонки | Cloud | -Spool — это то что делает это безопасным: ваш агент никогда не блокируется на сети, и Cloud outage означает растущую директорию вместо потерянных событий. +Катушка — это то, что делает это безопасным: ваш агент никогда не блокирует на сети, и Cloud outage означает растущий директорий вместо потерянных событий. -Каждый flush пишет один batch файл, `.tmp` сначала, затем `fsync`, затем атомарное переименование: +Каждый flush пишет один batch файл, `.tmp` первым, затем `fsync`, затем атомарное переименование: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Daemon только подбирает `.jsonl`, поэтому никогда не может прочитать наполовину написанный файл. Stem несёт timestamp, process id и sequence number, поэтому два процесса flushing в той же миллисекунде не могут столкнуться. Очередь ограничена 10,000 событиями; сверх этого она отбрасывает самое старое и логирует. +Daemon берёт только `.jsonl`, поэтому он никогда не может читать полупиписанный файл. Основание несёт временную метку, id процесса и номер последовательности, поэтому два процесса, flushing в одной миллисекунде, не могут коллизировать. Очередь ограничена 10 000 событиями; свыше того она выбрасывает самое старое и логирует. - **`collector.redact` не применяется к вашим SDK событиям.** Он их никогда не видит. + **`collector.redact` по умолчанию `minimal` для событий SDK тоже.** SDK скребёт перед написанием batch на диск, и daemon повторяет тот же детерминистский проход перед загрузкой так что batch от старших SDKs защищены. -Daemon **доставляет** ваши батчи. Он их не открывает и не переписывает. +Daemon читает каждый batch и применяет редакцию в памяти перед загрузкой. Он не переписывает файл катушки, который прочитал. -| События | Написано | Отредактировано `collector.redact`? | +| События | Написаны | Где minimal редакция работает | | --- | --- | --- | -| CLI session транскрипты | Daemon | Yes | -| Hook activity | Daemon | Yes | -| **Всё что SDK генерирует** | **Ваш процесс** | **No** | +| CLI стенограммы сессии | Daemon | Перед тем как daemon пишет batch | +| Активность Hook | Daemon | Перед тем как daemon пишет batch | +| **Всё что SDK испускает** | **Ваш процесс** | **Перед тем как SDK пишет batch и снова перед daemon загрузкой** | -Редакция работает где daemon **пишет** его собственные события — не где батчи **доставляются**. Поэтому prompt или инструмент argument держащий API key всё ещё держит его по прибытии. - -Это намеренно. Это ваши собственные вызовы инструментирования, и переписывание их в пути бы означало события которые вы получаете не события которые вы генерировали. +Установите `collector.redact` на `off` только когда дословные полезные нагрузки — явное требование; SDK и daemon оба уважают эту установку. Minimal редакция ловит обычные API ключи, bearer токены, JWTs и секретные назначения. Она не может определить произвольную чувствительную прозу. - **Вы контролируете payloads на источнике в двух местах:** + **Вы управляете полезными нагрузками у источника в двух местах:** - - Выключите захват контента на адаптере. **Имя опции отличается и один адаптер не имеет** — это не один универсальный переключатель: + - Выключите захват содержимого на адаптере. **Имя опции различается, и один адаптер не имеет ни одного** — это не один универсальный переключатель: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **no content switch at all**; `session_id` единственная опция, которую он читает, поэтому prompts и completions всегда записываются. + - CrewAI — **нет переключателя содержимого**; `session_id` — единственная опция, которую он читает, так что prompts и completions всегда записываются. - `instrument()` отбрасывает опции адаптер не читает, поэтому передача неправильного имени выбросит ничего и изменит ничего. - - Не передавайте secret в `input=` в первую очередь. + `instrument()` выбрасывает опции адаптер не читает, поэтому передача неправильного имени ничего не возбуждает и ничего не меняет. + - Не передавайте секрет в `input=` первом месте. - `collector.redact` не является заменой для обоих. + `collector.redact` — защита в глубину, не замена для любого. - **Пустая spool директория — здоровое состояние.** Не используйте её для проверки доставки. + **Пустой директорий катушки — здоровое состояние.** Не используйте его для проверки доставки. -Daemon удаляет каждый батч в миллисекундах доставки, поэтому `ls` гонится по collector и показывает fraction того что вы генерировали — неразличимый от SDK который ничего не записал. +Daemon удаляет каждый batch в миллисеконде доставки, поэтому `ls` гонится с collector и показывает дробь того, что вы испустили — неразличимо от SDK, который ничего не записал. -Чтобы подтвердить события действительно приземлились, проверьте панель управления. Чтобы看着 spool заполняться, сначала остановите daemon. +Чтобы подтвердить события действительно приземлились, проверьте панель. Чтобы смотреть катушку наполняться, сначала остановите daemon. - + -Каждый обратный вызов работает внутри обёртки чья единственная работа переиспустить, поэтому ваш вызов сидит в ровно одном `try` и всё что SDK делает происходит вне его. +Каждый callback работает внутри обёртки, единственная задача которой переиспускать, поэтому ваш вызов сидит в ровно одном `try` и всё что SDK делает происходит вне него. | Что происходит | Результат | | --- | --- | -| Hook выбросит | Логировано один раз с его traceback. Ваш вызов не затронут | -| Тот же hook выбросит трижды | Тот хук отключен для остатка процесса, с одной линией ошибки | +| Hook возбуждает | Логируется один раз с traceback. Ваш вызов не затронут | +| Один и то же hook возбуждает три раза | Этот один hook отключён для остатка процесса с одной error линией | | `FAILPROOFAI_SDK_STRICT=1` установлен | Исключение переиспущено вместо этого | | Версия фреймворка вне протестированного диапазона | Предупреждает один раз, инструментирует всё равно | -| Один capability отсутствует | Тот хук отключен, никогда весь адаптер | +| Одна возможность отсутствует | Этот один hook отключён, никогда не весь адаптер | -Default правильный в production и неправильный при debugging, потому что может только когда-либо доказать that it did not crash. Установите `FAILPROOFAI_SDK_STRICT=1` чтобы сделать проглоченную ошибку громкой. +По умолчанию правильно в production и неправильно при отладке, потому что оно может только когда-нибудь доказать — не сломалось. Установите `FAILPROOFAI_SDK_STRICT=1` чтобы заставить проглоченную неудачу быть громкой. -## Частые проблемы +## Общие проблемы - - Открывающее событие не имеет закрывающего: `model_request` без `model_response` или `tool_use` без `tool_result`. Используйте области, которые гарантируют пару даже когда тело выбросит. Если вы вызываете методы события напрямую, используйте `try` и `finally`. + + Открывающее событие не имеет закрывающего: `model_request` без `model_response` или `tool_use` без `tool_result`. Используйте области, которые гарантируют пару даже когда тело возбуждает. Если вы вызываете методы события напрямую используйте `try` и `finally`. - - Это измеряется от соответствующего открывающего события, поэтому отклоняется на `tool_result`, `hook_completed`, `agent_resume` и `human_input`. Принято на `model_response`, потому что только вы знаете реальную задержку провайдера, и это должно быть целое число. + + Она измеряется от согласованного открывающего события, поэтому она отклоняется на `tool_result`, `hook_completed`, `agent_resume` и `human_input`. Она принимается на `model_response`, потому что только вы знаете реальную задержку провайдера, и она должна быть целое число. - - Поток никогда не наследовал контекст. Оберните callable в `failproofai_sdk.propagate()`. См. [Потоки и async](#threads-and-async). + + Поток никогда не наследовал контекст. Оберните вызываемое в `failproofai_sdk.propagate()`. См. [Потоки и async](#потоки-и-async). - - Дополнительные поля слияны последние, поэтому одно названное как реальное поле такое как `model` или `outcome` переписало бы его и изменило сохранённую колонку. Пространство имён ваши; адаптеры используют префикс `fw_`. + + Дополнительные поля объединяются последними, поэтому одно с именем как реальное поле такое как `model` или `outcome` перезаписало бы его и изменило бы сохранённую колонку. Пространство имён своих; адаптеры используют префикс `fw_`. - `agent_id` — низко-кардинальный фасет и вы положили в него run id. Используйте role или имя узла и положите реальный id в поле payload. + `agent_id` — низкокардинальный аспект и вы поставили id запуска в него. Используйте роль или имя узла и поставьте реальный id в поле полезной нагрузки. -## Дальше +## Далее - Пары, id, жизненный цикл session и доставка. + Пары, ids, жизненный цикл сессии и доставка. - - Следите за причинностью через session которую вы только что захватили. + + Следите причинности через сессию, которую вы только что захватили. LangGraph, CrewAI, LlamaIndex и Pydantic AI. diff --git a/docs/tr/start/integrations/custom-agents.mdx b/docs/tr/start/integrations/custom-agents.mdx index b091505d..b93694ce 100644 --- a/docs/tr/start/integrations/custom-agents.mdx +++ b/docs/tr/start/integrations/custom-agents.mdx @@ -1,23 +1,23 @@ --- -title: "Özel aracılar" -sidebarTitle: "Özel aracılar" -description: "Kendiniz yazdığınız bir aracıyı veya adaptörü olmayan bir çerçeveyi enstrüman edin." +title: "Özel ajanlar" +sidebarTitle: "Özel ajanlar" +description: "Kendi yazdığınız bir ajana veya uyarlaması olmayan bir çerçeveye bir alet yerleştirin." icon: "code" --- -Kendiniz yazdığınız bir aracı veya Failproof AI'nin adaptörü olmayan bir çerçeve için. Enstrümante edilecek bir şey yoktur: olayları siz yayınlarsınız. +Kendi yazdığınız bir ajan için veya Failproof AI'ın uyarlaması olmayan bir çerçeve için. Yerleştirilecek hiçbir şey yoktur: siz olayları yayınlarsınız. -Bu, dört çerçeve adaptörünün altında çağırdığı API'dir. Bunlar onun üzerinde çeviri tablolarıdır. +Bu, dört çerçeve adaptörünün altında çağırdığı API'dir. Bunlar bunun üzerindeki çeviri tablolarıdır. -## Yükleme +## Kurulum ```bash pip install failproofai-sdk ``` -Ek paket yok, bağımlılık yok. +Ekstralar ve bağımlılıklar yok. -## Enstrümantasyon +## Yerleştirme ```python import failproofai_sdk @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # bir çalışma t.output = search(q) # bir araç çağrısı ``` -Baştan sona okuyun, söylediği şey budur: +Yukarıdan aşağıya okuyun ve ne demek istediğini söyler: -| Bunu sarın | Demek için | +| İçinde sarmalayın | Söylemek için | | --- | --- | | `session()` | Bu olaylar aynı çalışmaya ait | -| `agent()` | Birisi çalışıyor — listedeki tanıyacağınız bir ad verin | +| `agent()` | Bir şey çalışma yapıyor — bir listede tanıyabileceğiniz bir ad verin | | `tool_call()` | Bu bir araç ve işte ne döndürdüğü | -Ve her biri aslında neyi yayınlar: +Ve her biri gerçekten ne yayınlar: | Kapsam | Yayınlar | Amaç | | --- | --- | --- | -| `session()` | Hiçbir şey | Oturum kimliğini bağlar, bir çalışmayı gruplandırır | -| `agent()` | `agent_start`, `agent_end` | Bir iş birimini köşeli ayraç içine alır | -| `tool_call()` | `tool_use`, `tool_result` | Bir aracı köşeli ayraç içine alır ve ölçer | +| `session()` | Hiçbir şey | Bir oturumu bağlar, bir çalışmayı gruplandırır | +| `agent()` | `agent_start`, `agent_end` | Bir iş birimini parantez içine alır | +| `tool_call()` | `tool_use`, `tool_result` | Bir aracı parantez içine alır ve ölçer | -İçindeki her şey `session_id` ve `agent_id` atlamabilir. Kapsamlar kimliği bağlam değişkenlerine bağlar ve her olay çağrısı onu geri okur, bu yüzden kimlikler hiçbir zaman işlevler aracılığıyla iletilmez. +İçindeki her şey `session_id` ve `agent_id` öğesini atlayabilir. Kapsamlar kimliği bağlam değişkenlerine bağlar ve her olay çağrısı bunu geri okur, bu nedenle hiçbir zaman işlevleriniz arasında kimlikleri geçirmezsiniz. -Üçü de `async with` ve `with` altında çalışır. +Her üçü `async with` kadar `with` altında da çalışır. -Aracıları iç içe yerleştirmek ağacı oluşturur. `parent_id` ve derinlik yığından hesaplanır: +Ajanlari yuvalamak ağacı oluşturur. `parent_id` ve derinlik yığından hesaplanır: ```python with failproofai_sdk.session(): @@ -59,42 +59,42 @@ with failproofai_sdk.session(): ... ``` -## Bir kapsam nasıl kapanır +## Bir kapsam kapanırken -`agent()` istisnaları sizin için işler: +`agent()` istisnalar sizin için işler: | Ne oldu | Olaylar | Sonuç | | --- | --- | --- | | Hiçbir şey yükseltilmedi | `agent_end` | `success` | | `Exception` | `error`, sonra `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, sonra `agent_end` | `failed` | -| `CancelledError`, `GeneratorExit` | yalnızca `agent_end` | `cancelled` | +| `CancelledError`, `GeneratorExit` | sadece `agent_end` | `cancelled` | -Hata `agent_end` öncesinde yayınlanır, çünkü gösterge paneli yayını `agent_end` konumunda kapatır ve bundan sonra gelen her şey hiçbir şeye atfedilir. İptal bir hata değildir, bu nedenle iptal edilen çalışmalar hata yüzeyini kirletmez. İstisna her zaman yeniden yükseltilir: bir kapsam asla yutmaz. +Hata `agent_end` öncesinde yayınlanır, çünkü pano aralığı `agent_end` adresinde kapatır ve bundan sonra her şey hiçbir şeye atfedilir. İptal bir başarısızlık değildir, bu nedenle iptal edilen çalışmalar hata yüzeyini kirletmez. İstisna her zaman yeniden yükseltilir: bir kapsam hiçbir zaman istisna kalmaz. ## Olay yöntemleri -On beş yöntem altı ailededir. Çoğu çiftler halinde gelir — açan yayını yayınlarsınız, sonra kapatanı yayınlarsınız ve SDK aralarındaki yayını ölçer. +On beş yöntem altı aileden. Çoğu çiftler halinde gelir — açıcıyı siz yayınlarsınız, sonra kapatıcıyı yayınlarsınız ve SDK arası aralığı ölçer. | Aile | Açar | Kapatır | Bağımsız | | --- | --- | --- | --- | -| **Aracılar** | `agent_start` | `agent_end` | — | +| **Ajanlar** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | | **Modeller** | `model_request` | `model_response` | — | | **Araçlar** | `tool_use` | `tool_result` | — | | **Kancalar** | `hook_triggered` | `hook_completed` | — | | **İnsanlar** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | -| **Hatalar** | — | — | `error` | +| **Başarısızlıklar** | — | — | `error` | - Kapsamları tercih edin — `agent()` ve `tool_call()` — uygun oldukları yerlerde. Gövde yükseltirse bile kapanan olayı garantilerler. İçerik akışınız iç içe olmadığında doğrudan bu yöntemlere ulaşın; örneğin yardımcı içinde bir model çağrısı. + Kapsamlar — `agent()` ve `tool_call()` — her yerde tercih edin. Gövde yükselttiğinde bile kapatma olayını garantilerler. İçinde iç içe geçmeyen kontrol akışına (örneğin bir yardımcı içinde bir model çağrısı) sahip olduğunuzda bu yöntemlere doğrudan ulaşın. -```python Aracılar -failproofai_sdk.event.agent_start(agent_id="planner", goal="en ucuz uçuşu bul") +```python Ajanlar +failproofai_sdk.event.agent_start(agent_id="planner", goal="find the cheapest flight") failproofai_sdk.event.agent_end(agent_id="planner", outcome="success", summary="...") -failproofai_sdk.event.agent_pause(pause_id="p1", reason="onay beklemede") +failproofai_sdk.event.agent_pause(pause_id="p1", reason="awaiting approval") failproofai_sdk.event.agent_resume(pause_id="p1") ``` @@ -125,39 +125,39 @@ failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome ``` ```python İnsanlar -failproofai_sdk.event.human_wait(input_id="i1", prompt="Onayla?", options=["yes", "no"]) +failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") -failproofai_sdk.event.human_pause(reason="operatör çalışmayı duraklatttı", user_id="dana") -failproofai_sdk.event.human_interrupt(reason="operatör çalışmayı durdurdu", at_step="step_3") +failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") +failproofai_sdk.event.human_interrupt(reason="operator stopped the run", at_step="step_3") ``` -```python Hatalar +```python Başarısızlıklar failproofai_sdk.event.error( error_type="TimeoutError", - message="sağlayıcı 30 saniye sonra zaman aşımına uğradı", + message="provider timed out after 30s", traceback="...", ) ``` - **İki insan ailesi zıt yönleri gösterir.** + **İki insan ailesi zıt yönleri işaret eder.** | Yöntemler | Anlamı | | --- | --- | - | `human_wait` / `human_input` | **Aracı bir kişiye sordu** — onay kapısı, açıklayıcı soru | - | `human_pause` / `human_interrupt` | **Bir kişi aracıya etkide bulundu** — durdur düğmesi, operatör duraklaması | + | `human_wait` / `human_input` | **Ajan bir kişiye sordu** — bir onay kapısı, açıklayıcı bir soru | + | `human_pause` / `human_interrupt` | **Bir kişi ajana hareket etti** — durdur düğmesi, operatör duraklatması | - Hiçbir çerçeve ikinci çifti sinyal vermez, bu yüzden her zaman siz yayınlarsınız. + Hiçbir çerçeve ikinci çifti sinyal vermez, bu nedenle her zaman sizin yayınlamanız gereken şeydir. - **Model çağrıları eşzamanlı olarak çalıştığında `request_id` geçirin.** Olmadan, istekler ve yanıtlar ajan başına varış sırasına göre eşleşir — ve eşzamanlı çağrılar yanlış eşleşir, her yanıtı yanlış isteğe iliştirir. + **Model çağrıları eşzamanlı olarak çalıştığında `request_id` geçirin.** Olmadan, istekler ve yanıtlar ajan başına varış sırasıyla eşleşir — ve eşzamanlı çağrılar yanlış eşleşir ve her yanıtı yanlış isteğe ekler. ## Örnek -OpenAI API'sine karşı araç çağırma döngüsü, ajan çerçevesi olmadan: +OpenAI API'sine karşı bir araç çağırma döngüsü, ajan çerçevesi olmadan: ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """Bir model çağrısı, çift tarafından köşeli ayraç içine alınmış.""" + """Bir model çağrısı, çift tarafından parantez içine alındı.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -185,8 +185,8 @@ def turn(messages: list): with failproofai_sdk.session(): - with failproofai_sdk.agent("inventory", goal="fiyat raporu"): - for _ in range(4): # sınırlandırılmış; sınırsız ajan döngüsü kendi hatası + with failproofai_sdk.agent("inventory", goal="price report"): + for _ in range(4): # sınırlı; sınırsız bir ajan döngüsü kendi bir hatadır message = turn(messages) if not message.tool_calls: break @@ -204,45 +204,45 @@ with failproofai_sdk.session(): }) ``` -Bu, bir adaptörün size vereceği altı olay türünü üretir. Tam çalıştırılabilir sürüm, araç tanımlarıyla birlikte, SDK deposunda `docs/manual/examples/` altında bulunur. +Bu, bir adaptörün sağlayacağı aynı altı olay türünü üretir. Tam çalıştırılabilir sürüm, araç tanımlarıyla birlikte, SDK deposunda `docs/manual/examples/` altında gemi. ## İş parçacıkları ve async -Bağlam değişkenleri asyncio görevlerine otomatik olarak yayılır. Bir iş parçacığı boş bir bağlamla başladığı için yeni iş parçacıklarına yayılmaz. +Bağlam değişkenleri asyncio görevlerine otomatik olarak yayılır. Bir iş parçacığı boş bir bağlamla başladığı için yeni iş parçacıklarına yayılmazlar. ```python -# asyncio: yapılacak bir şey yok +# asyncio: yapılacak hiçbir şey yok async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# iş parçacıkları: çağrıyı sarın +# iş parçacıkları: çağrılanı sarmalayın pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -`propagate()` olmadan, worker'ın olayları düzeltmeyi adlandıran bir `TypeError` yükseltir, bu da hiçbir oturuma gitmez. Bu kasıtlıdır: oturumu olmayan bir olay ingest tarafından atlanır ve `200` ile yanıtlanır, bu da kimlik katmanının önlemesi amaçladığı sessiz başarısızdır. +`propagate()` olmadan, çalışanın olayları düzeltmeyi adlandıran bir `TypeError` yükseltir, bunun yerine hiçbir oturuma iniş. Bu kasıtlıdır: hiçbir oturuma sahip olmayan bir olay alımında atlanır ve `200` ile yanıtlanır, bu da kimlik katmanının var olması için sessiz başarısızlıktır. -## Adaptörü olmayan bir çerçeveyi enstrümante edin +## Adaptörü olmayan bir çerçeveye alet takın -Her ajan çerçevesi aynı üç bağlantı noktası sağlar. Onları harita yapın ve tam bir izlemeniz vardır — sevk edilen dört adaptör bundan fazla bir şey yapmaz. +Her ajan çerçevesi aynı üç dikiş verir. Onları eşleştirin ve tam bir izin aldınız — dört gemi adaptörü bundan daha fazlasını yapmazlar. -| Bağlantı noktası | Yazarınız | İnişi olan | +| Dikiş | Yazarız | Arazileri | | --- | --- | --- | | Çalışma | `session()` + `agent()` | `agent_start`, `agent_end` | | Her araç | `tool_call()` | `tool_use`, `tool_result` | | Her model çağrısı | `model_*` çifti | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - Çerçevenin araç sarıcısı veya ara yazılım olarak adlandırdığı her şeyde. + + Çerçevenin bir araç sarmalayıcısı veya ara yazılım dediği ne olursa olsun. ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -264,31 +264,31 @@ Her ajan çerçevesi aynı üç bağlantı noktası sağlar. Onları harita yap - **Görmeye değer bir düğüm, adım veya ara yazılım sınırı var mı?** Bunu iç içe bir `agent()` değil, kancanın içine sarın — `hook_triggered` / `hook_completed`. `agent_id` düşük kardinalite yönüdür ve düğüm başına bir giriş onu boğar. Kancanın yayını aynı şekilde işlenir ve düğüm başına gecikme süresi sağlar. + **Görmek değer bir düğüm, adım veya ara yazılım sınırı var mı?** Bir kanca çifti içinde sarmalayın — `hook_triggered` / `hook_completed` — iç içe geçmiş `agent()` değil. `agent_id`, düşük kardinalite bir nitelik ve düğüm başına bir giriş onu boğar. Kanca aralıkları aynı şekilde renderlenir ve size düğüm başına gecikme süresi verir. - **Manuel ve otomatik oluşturma.** El yazısı bir kapsam içinde çalışan bir adaptör bu oturuma katılır ve bu aracıya ebeveyn olur, bu nedenle iki tane yerine bir ağaç alırsınız — desteklenen bir tarafı kendiniz enstrümante ederken bir çerçeveyi yan yana kullanışlı olduğunda. + **Manuel ve otomatik oluştur.** Bir uyarlanmış içinde çalışan bir çerçeve, bu oturuma katılır ve bu ajana üst olur, bu nedenle iki ağaç yerine bir ağaç alırsınız — bir desteklenen çerçeve ile birlikte kendi kendine bir çerçeve alet takmanız yararlı. - - İki neden vardır ve yukarıdaki üç bağlantı noktası her ikisine de cevaptır: + + İki neden ve yukarıdaki üç dikiş her ikisinin cevabıdır: - - `autogen-core` Eylül 2025'ten beri bakımsız olmuştur. - - AG2, diğer çerçevelerin kancanlarına eşdeğer hiçbir işlem açısından kayıt noktası açığa çıkarmaz, bu nedenle enstrümantasyonu her inşaat alanında her aracıyı sararak anlamına gelir. + - `autogen-core` Eylül 2025'ten beri bakımsızdır. + - AG2, diğer çerçevelerin kancaları eşdeğer işlem çapında bir kayıt noktası ortaya çıkarmaz, bu nedenle bunu araç takınmak her inşaat sitesinde her ajanı sarmalamak anlamına gelir. - Bağlantı noktalarını elle harita yaparak, sevk edilen bir adaptörün yaptığı aynı fidelitede aynı olayları kaydeder. + Dikiş eşleştirmesini el ile yapmak, bir gemi adaptörü olarak aynı olayları aynı doğrulukta kaydeder. -## Daha derine gitme +## Daha derine inmek -Kaydın aslında nasıl çalıştığı. Başlamak için buna ihtiyaç yoktur. +Kayıt gerçekten nasıl çalışır. Başlamak için bunların hiçbiri gerekli değildir. - + -Her kaydın aynı şekli vardır: bir yay açılır, iş içinde iç içe geçer ve her açma olayı kapatma olayı alır. +Her kaydın aynı şekli vardır: bir aralık açılır, çalışma içinde yuvalanır ve her açılış olayı kapatma olayı alır. ```mermaid flowchart LR @@ -300,17 +300,17 @@ flowchart LR C --> E(["agent_end"]) ``` -**Çift** birimdir. Her kapatma olayı SDK'nın açma olayından ölçtüğü bir süre taşır. +**Çift** birim. Her kapatma olayı, SDK'nın açılış olayından ölçtüğü bir süreyi taşır. -Aşağıda SDK ile sevk edilen örneklerden yakalanan çerçeve başına bir gerçek çalışma vardır — model adı normalleştirilmiştir. Tek bir çağrıdan ne kadar döndüğüne dikkat edin. +Aşağıda SDK ile birlikte gelen örneklerden yakalanan çerçeve başına bir gerçek çalışma — model adı normalleştirildi. Tek bir çağrıdan ne kadar geri döndüğüne dikkat edin. - ```text 14 olay + ```text 14 olaylar 1 +0.000s agent_start LangGraph 2 +0.001s hook_triggered agent 3 +0.002s model_request gpt-4o-mini - 4 +3.023s model_response gpt-4o-mini · 21 çıkış-tok + 4 +3.023s model_response gpt-4o-mini · 21 out-tok 5 +3.024s hook_completed agent 6 +3.024s hook_triggered tools 7 +3.025s tool_use word_count @@ -318,106 +318,106 @@ Aşağıda SDK ile sevk edilen örneklerden yakalanan çerçeve başına bir ger 9 +3.025s hook_completed tools 10 +3.026s hook_triggered agent 11 +3.027s model_request gpt-4o-mini - 12 +5.717s model_response gpt-4o-mini · 5 çıkış-tok + 12 +5.717s model_response gpt-4o-mini · 5 out-tok 13 +5.720s hook_completed agent 14 +5.721s agent_end LangGraph · success ``` - Düğümler kancanın çiftleri olur, bu nedenle onları kalabalık yapmadan düğüm başına gecikme süresi alırsınız. + Düğümler kanca çiftleri haline gelir, böylece ajan listesini doldurmadan düğüm başına gecikme süresi alırsınız. - ```text 10 olay + ```text 10 olaylar 1 +0.000s agent_start crew 2 +0.050s agent_start analyst · under crew 3 +0.057s model_request gpt-4o-mini - 4 +3.475s model_response gpt-4o-mini · 19 çıkış-tok + 4 +3.475s model_response gpt-4o-mini · 19 out-tok 5 +3.478s tool_use lookup_metric 6 +3.478s tool_result lookup_metric · ok 7 +3.486s model_request gpt-4o-mini - 8 +5.694s model_response gpt-4o-mini · 9 çıkış-tok + 8 +5.694s model_response gpt-4o-mini · 9 out-tok 9 +5.727s agent_end analyst · success 10 +5.739s agent_end crew · success ``` - Her aracının `role` yay adı olur, bu nedenle gecikme süresi ve jeton harcaması rol başına bölünür. + Her ajanın `role` aralık adı haline gelir, böylece gecikme ve jeton harcaması rol başına bölünür. - ```text 26 olay + ```text 26 olaylar 1 +0.000s agent_start Agent 2 +0.001s hook_triggered init_run 4 +0.501s hook_triggered setup_agent 6 +0.503s hook_triggered run_agent_step 7 +0.505s model_request gpt-4o-mini - 8 +3.083s model_response gpt-4o-mini · 18 çıkış-tok + 8 +3.083s model_response gpt-4o-mini · 18 out-tok 10 +3.197s hook_triggered parse_agent_output 12 +3.355s hook_triggered call_tool 13 +3.355s tool_use city_population 14 +3.355s tool_result city_population · ok 16 +3.356s hook_triggered aggregate_tool_results - ... ikinci iterasyon + ... ikinci yineleme 26 +7.038s agent_end Agent · success ``` - Ajan döngüsü kendisi görünür, yalnızca model çağrıları değil. + Ajan döngüsünün kendisi görülebilir, sadece model çağrıları değil. - ```text 8 olay + ```text 8 olaylar 1 +0.000s agent_start agent 2 +0.001s model_request gpt-4o-mini - 3 +4.413s model_response gpt-4o-mini · 17 çıkış-tok + 3 +4.413s model_response gpt-4o-mini · 17 out-tok 4 +4.415s tool_use population 5 +4.415s tool_result population · ok 6 +4.416s model_request gpt-4o-mini - 7 +8.118s model_response gpt-4o-mini · 6 çıkış-tok + 7 +8.118s model_response gpt-4o-mini · 6 out-tok 8 +8.119s agent_end agent · success ``` - Kancanın çifti yok: Pydantic AI'nin köşeli ayraç içine alacak düğüm veya adım sınırı yok. + Kanca çifti yok: Pydantic AI'nin parantez içine alacak bir düğüm veya adım sınırı yoktur. - - ```text 6 olay + + ```text 6 olaylar 1 +0.000s agent_start main 2 +0.000s tool_use population 3 +0.000s tool_result population · ok 4 +0.000s model_request gpt-4o-mini - 5 +0.000s model_response gpt-4o-mini · 3 çıkış-tok + 5 +0.000s model_response gpt-4o-mini · 3 out-tok 6 +0.000s agent_end main · success ``` - Bunları kendiniz yayınlarsınız. Aynı olay türleri, aynı fidelite — çağrı alanlarına mal olur. + Bunları kendiniz yayınlıyorsunuz. Aynı olay türleri, aynı doğruluk — çağrı sitelerine mal olur. - + -**Oturum sonu olayı yoktur.** Oturum kapattığınız bir şey değil — `session_id` paylaşan bir olay grubudur. +**Oturum sonu olayı yoktur.** Bir oturum kapatıp kapatmadığınız bir şey değildir — aynı `session_id` paylaşan bir olay grubudur. -Durum izlemenin şeklinden türetilir: +Durum izin şeklinden türetilir: | Durum | Ne zaman | | --- | --- | -| `ongoing` | En az bir yay hala açık | -| `paused` | Bir `agent_pause` eşleşen `agent_resume` yok | +| `ongoing` | En az bir aralık hala açık | +| `paused` | `agent_pause` eşleşen `agent_resume` yok | | `error` | Hiçbir şey açık değil ve en az bir olay başarısız oldu | | `done` | Hiçbir şey açık değil ve hiçbir şey başarısız olmadı | -Yani bir oturum her çift kapatıldığında biter. Adaptörler sizin için `agent_end` yayınlar ve kapalı kaldığında açık kalan her şeyi kapatırlar ve eksik olarak işaretlerler — çökmüş bir çalışma asılı kalmak yerine görünür bir boşlukla `done` olarak yerleşir. +Bu nedenle bir oturum her çift kapandığında biter. Adaptörler sizin için `agent_end` yayınlar ve bozulma sırasında hala açık olan her şeyi kapatır ve eksik olarak işaretler — kilitlenmiş bir çalışma, asılı kalmak yerine görünen boşluk olarak `done` çözümlenir. - Bu yüzden bir oturum iki çağrıya yayılabilir. Bir LangGraph `interrupt()` çalışmayı duraklatır, kök yayı kasıtlı olarak açık kalır ve devam eden çağrı onu kapatır. Her iki çağrı bir oturuma aittir. + Bu nedenle bir oturum iki çağrıya yayılabilir. Bir LangGraph `interrupt()` çalışmayı duraklatır, kök aralığı kasıtlı olarak açık kalır ve devam çağrısı bunu kapatır. Her iki çağrı da bir oturumdu. - + -`session_id` ve `agent_id` her olay yönteminde isteğe bağlıdır. Atlanırsa, çevreleyen kapsamdan çözülürler: +`session_id` ve `agent_id` her olay yönteminde isteğe bağlıdır. Atlanıldığında, çevreleyen kapsamdan çözülebilirler: ```python with failproofai_sdk.session(): @@ -425,84 +425,84 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Bunları açıkça iletmek yine de işe yarar ve önceliği alır. Hiçbir şey bağlı değil ve hiçbir şey iletilmezse, çağrı düzeltmeyi adlandıran bir `TypeError` yükseltir, ingest atlamış olacağı oturumu olmayan bir olayı yayınlamak yerine, `200` ile yanıtlar. +Bunları açıkça geçirmek yine de çalışır ve öncelik alır. Hiçbir şey bağlı olmayıp hiçbir şey geçmediyse, çağrı düzeltmeyi adlandıran bir `TypeError` yükseltir, yoksa alım tarafından atlanacak hiçbir oturuma sahip bir olay yayınlar ve `200` ile yanıtlar. -Kapsamlar kimliği bağlam değişkenlerine bağlar. Bunlar asyncio görevlerine otomatik olarak yayılır ancak yeni iş parçacıklarına yayılmaz — bir worker'ı `failproofai_sdk.propagate()` içine sarın. +Kapsamlar kimliği bağlam değişkenlerine bağlar. Bunlar asyncio görevlerine otomatik olarak yayılır, ancak yeni iş parçacıklarına değil — bir işçiyi `failproofai_sdk.propagate()` içinde sarmalayın. -#### Hangi kimlik kim tarafından basım yapılır +#### Hangi kimlik kim başlatır -| Kimlik | Basım yapan | Notlar | +| Kimlik | Tarafından başlatıldı | Notlar | | --- | --- | --- | -| `session_id` | Siz veya SDK | `session("chat-42")` kelimesi kelimesine kullanılır; atlanırsa, SDK bir `uuid4().hex` oluşturur | -| `agent_id` | Siz veya çerçeve | `agent("analyst")`, CrewAI `role`, bir `FunctionAgent.name`'den. UUID görünüşlü bir değer reddedilir ve değiştirilir | -| `tool_call_id`, `hook_id`, `request_id` | Siz veya çerçeve | Adaptörler çerçevenin kendi çalışma kimliklerini yeniden kullanır, bu yüzden çiftler iş parçacığı atlamalarında hayatta kalır | -| **Olay kimliği** | **Bulut, ingest'te** | SDK hiçbirini yayınlamaz | -| **`dedup_key`** | **Bulut, ingest'te** | Kuruluş, oturum, zaman damgası, tür ve yüke karşı bir karma. Bu gerçek kimlik — yeniden denenen bir topluyu çoğaltmak yerine daraltır | +| `session_id` | Siz veya SDK | `session("chat-42")` tam olarak kullanılır; atlanıldığında, SDK bir `uuid4().hex` üretir | +| `agent_id` | Siz veya çerçeve | `agent("analyst")` danışmanından, CrewAI `role`, bir `FunctionAgent.name`. UUID benzeri bir değer reddedilir ve değiştirilir | +| `tool_call_id`, `hook_id`, `request_id` | Siz veya çerçeve | Adaptörler çerçevenin kendi çalışma kimliklerini yeniden kullanır, bu da çiftlerin iş parçacığı atlaması nedeniyle hayatta kaldığı nedenidir | +| **Olay kimliği** | **Bulut, alımda** | SDK hiçbirini yayınlamaz | +| **`dedup_key`** | **Bulut, alımda** | Org, oturum, zaman damgası, tür ve yükün karması. Bu gerçek kimlik — bir yeniden denenen toplu işin kopyalanmak yerine çökmesini sağlar | -#### Adaptörler `session_id` nasıl çözer +#### Adaptörler `session_id` nasıl çözerler İlk eşleşme kazanır: -1. Açık bir `session_id` seçeneği -2. Çağrı başına meta veri -3. Çevreleyen `session()` kapsamı +1. Açık `session_id` seçeneği +2. Çağrı başına meta veriler +3. `session()` kapsamını çevreleyen 4. Çerçeve meta verileri 5. Çerçevenin kendi çalışma kimliği -Bunlardan biri vardığı sürece asla icat edilmez — sentezlenmiş bir kimlik bir çalışmayı birkaç oturuma böler. +Bunlardan biri var iken asla icat edilmez — sentezlenmiş bir kimlik bir çalışmayı birkaç oturum arasında bölmek olur. -#### `agent_id` düşük kardinaliteyi koruyun +#### `agent_id` düşük kardinaliteyi tutun -Bu her gösterge paneli yüzeyinde birincil yönüdür ve `LowCardinality(String)` sütunu. Çalışma başına bir değer sütunu düşürür ve filtre açılır menüsünü çalışma başına bir giriş ile doldurur. +Her pano yüzeyinde birincil yüz ve bir `LowCardinality(String)` sütunudur. Çalışma başına bir değer sütunu bozar ve filtre açılır penceresini çalışma başına bir giriş ile doldurur. Adaptörler bu sütunu sizin için savunur: -| Çerçeve teslim eder | Kaydedilmiş olarak | Neden | +| Çerçeve teslim eder | Olarak kaydedildi | Neden | | --- | --- | --- | -| `3f9a1c2b-…` (bir UUID) | `main` | Tutmak için okunabilir bir şey yok | -| Uzun çıplak hex dizesi | `main` | Aynı | -| `agent-3f9a1c2b-…` | `agent` | Çalışma başına kimlik çıkarıldı, okunabilir bölüm tutuldu | +| `3f9a1c2b-…` (UUID) | `main` | Tutacak hiçbir şey okunaklı | +| Uzun çıplak onaltılık dize | `main` | Aynı | +| `agent-3f9a1c2b-…` | `agent` | Çalışma başına kimlik çıkarıldı, okunaklı kısım tutuldu | | `agent-v2` | `agent-v2` | Kısa segmentler yalnız bırakılır | | `step-3` | `step-3` | Aynı | -Gerçek kimlik `fw_agent_id` / `fw_run_id` üzerinde tutulur, burada yönü olmuş bir yüzey olmadan sorgulanabilir kalır. +Gerçek kimlik, nitelik olmadan sorgulanabilir kaldığı `fw_agent_id` / `fw_run_id` üzerinde tutulur. - **Bu koruma yalnızca **çerçevenin** seçtiği etiketlere dokunur.** Kendiniz ilettiğiniz bir `agent_id` — `event.*` veya `failproofai_sdk.agent(...)` için — tam olarak verilen şekilde kaydedilir. Açık bir bağımsız değişkeni sessizce yeniden yazmak, kardinalieti önledikten daha kötü olur, bu yüzden kendi yaylarınızı buna göre adlandırın. + **Bu koruma yalnızca *çerçevenin* seçtiği etiketlere dokunur.** Kendi geçtiğiniz bir `agent_id` — `event.*` veya `failproofai_sdk.agent(...)` — tam olarak verilen gibi kaydedilir. Açık bir argümanı sessizce yeniden yazmak önlediği kardinaliteden daha kötü olur, bu nedenle kendi aralıklarınızı buna göre adlandırın. - + | Grup | Olaylar | | --- | --- | -| Aracılar | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| Ajanlar | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | | Modeller | `model_request`, `model_response` | | Araçlar | `tool_use`, `tool_result` | | Kancalar | `hook_triggered`, `hook_completed` | | İnsanlar | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | -| Hatalar | `error` | +| Başarısızlıklar | `error` | -Hangi çerçeve neyi kaydeder, yukarıdaki çalışmalardan ölçülen: +Hangi çerçeve ne kaydeder, yukarıdaki çalışmalardan ölçülmüştür: | Olay | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Özel | | --- | :--: | :--: | :--: | :--: | :--: | -| Ajan başı ve sonu | Evet | Evet | Evet | Evet | Siz | +| Ajan başlangıcı ve sonu | Evet | Evet | Evet | Evet | Siz | | Model isteği ve yanıtı | Evet | Evet | Evet | Evet | Siz | | Araç kullanımı ve sonucu | Evet | Evet | Evet | Evet | Siz | -| Kancanın tetiklenmesi ve tamamlanması | Düğüm | Görev | Adım | — | Siz | +| Kanca tetiklendi ve tamamlandı | Düğüm | Görev | Adım | — | Siz | | Hata | Evet | Evet | Evet | Evet | Otomatik | -| İnsan bekleme ve girişi | Evet | Evet | Evet | — | Siz | -| Ajan duraklaması ve devam etmesi | Evet | Evet | Evet | — | Siz | +| İnsan bekle ve giriş | Evet | Evet | Evet | — | Siz | +| Ajan duraklat ve devam et | Evet | Evet | Evet | — | Siz | -Tire, çerçevenin böyle bir kavramı olmadığı anlamına gelir. `human_pause` ve `human_interrupt`, aracıya etkide bulunan bir *kişiyi* tanımlar, hiçbir çerçeve sinyal vermez — bunları kendiniz yayınlayın. +Bir tire çerçevenin böyle bir kavramı olmadığı anlamına gelir. `human_pause` ve `human_interrupt` ajana etki eden bir *kişi* anlatılar — hiçbir çerçeve sinyal vermez — bunları kendiniz yayınlayın. -Bir olay asla yalnız gelmez. Biri bir yayı açar, biri onu kapatır ve kapatma olayı SDK'nın açma olayından ölçtüğü bir süre taşır. +Bir olay asla tek başına gelmez. Biri aralığı açar, biri kapatır ve kapatma olayı SDK'nın açılış olayından ölçtüğü bir süreyi taşır. | Açar | Kapatır | Kapatma olayı taşır | | --- | --- | --- | @@ -510,44 +510,44 @@ Bir olay asla yalnız gelmez. Biri bir yayı açar, biri onu kapatır ve kapatma | `model_request` | `model_response` | jetonlar, `stop_reason`, gecikme | | `tool_use` | `tool_result` | `output` veya `error`, süre | | `hook_triggered` | `hook_completed` | `outcome`, süre | -| `agent_pause` | `agent_resume` | duraklamanın ne kadar sürdüğü | -| `human_wait` | `human_input` | cevap ve kişinin ne kadar sürdüğü | +| `agent_pause` | `agent_resume` | duraklatmanın ne kadar sürdüğü | +| `human_wait` | `human_input` | cevap ve kişi kaç süre aldı | - Kapatma olayı olmayan açma olayı hiçbir zaman bitmez bir yaydır. Oturum sonsuza dek çalışıyor olarak işlenir ve etkin süresi büyümeye devam eder. Bu, el ile enstrümante ederken izlenecek hata modudur. + Kapatma olayı olmayan bir açılış olayı hiçbir zaman bitmeyen bir araçlıktır. Oturum sonsuza dek hala çalışıyor olarak renderlenir ve etkin süresi artmaya devam eder. Bu, elinizle alet takınırken izlenecek başarısızlık modudur. #### Korelasyon kuralları - Eşleşen tamamlama olayı için aynı `tool_call_id`, `hook_id`, `pause_id` veya `input_id` yeniden kullanın. -- SDK `tool_result`, `hook_completed`, `agent_resume` ve `human_input` için `duration_ms` hesaplar. Bunları iletmek `ValueError` yükseltir. -- `duration_ms` **kabul edilir** `model_response` üzerinde, çünkü yalnızca arayan gerçek sağlayıcı gecikmesini bilir. Bir tamsayı olmalı — bir kayan sayı çağrı sitesinde `ValueError` yükseltir, sunucu sütunu işaretsiz 32 bitlik bir tamsayı olarak okur ve başka bir şey için NULL depolar. -- Korelasyon anahtarları tür ve oturum kapsamındadır, böylece bir araç çağrısı ve kancanın kimliği güvenle paylaşabilir ve iki eşzamanlı oturum kimlikler yeniden kullanabilir çarpışma olmadan. Agent kapsamında değil: bir ajan altında açılan ve diğeri altında kapatılan bir çift yine de ilişkilendirilir, bu multi-ajan çerçevelerdeki sıradan durumdur. -- `request_id` `model_request` `model_response` ile eşleştirir. Olmadan, model olayları ajan başına sırada eşleşir, bu nedenle eşzamanlı çağrılar yanlış eşleşir. -- İşlemler arasında bölünmüş bir çift yine de aşağı doğru ilişkilendirilir, ancak SDK işlem içi süresini hesaplayamaz. -- Bekleyen harita en fazla 10.000 başlangıç tutar ve dolu olduğunda en eski giriş tahliye eder. +- SDK, `tool_result`, `hook_completed`, `agent_resume` ve `human_input` için `duration_ms` hesaplar. Bunu bu yöntemlere geçirmek `ValueError` yükseltir. +- `duration_ms` **kabul edilir** `model_response` adresinde, çünkü yalnızca arayana gerçek sağlayıcı gecikmesi bilinir. Tamsayı olmalı — bir kayan nokta çağrı sitesinde `ValueError` yükseltir, çünkü sunucu sütunu imzasız 32 bitlik bir tamsayı olarak okur ve diğer her şey için NULL depolar. +- Korelasyon anahtarları tür ve oturum tarafından kapsamlandırılır, bu nedenle bir araç çağrısı ve kanca güvenli bir şekilde bir kimliği paylaşabilir ve iki eşzamanlı oturum aynı kimlikleri çarpışmadan yeniden kullanabilir. Ajan tarafından kapsamlandırılmaz: bir ajan altında açılıp başka bir ajan altında kapatılan bir çift hala korelat olur, bu da çok ajanı çerçevelerde sıradan bir durumdur. +- `request_id` `model_request` ile `model_response` eşleştiriler. Olmadan, model olayları ajan başına sipariş olarak eşleşir, bu nedenle eşzamanlı çağrılar yanlış eşleşir. +- İşlemler arasında bölünmüş bir çift hala aşağı akışta korelat, ancak SDK işlem içi süresini hesaplayamaz. +- Beklemede harita en fazla 10.000 başlama tutar ve dolu olduğunda en eski girişi tahliye eder. - + -`failproofai-sdk` kurmak her şeyi, dört adaptör dahil olmak üzere yükler. Ekstralar adaptörü değil, **çerçeveyi** çeker. +`failproofai-sdk` kurulması her şeyi kurar, dört adaptör dahildir. Ekstralar **çerçeveyi** kurar, adaptörü değil. ```python import failproofai_sdk # standart kitaplığın dışında hiçbir şey yüklemez -failproofai_sdk.instrument() # yalnızca gerçekten ihtiyaç duyduğunuz adaptörleri içe aktarır +failproofai_sdk.instrument() # gerçekten ihtiyacınız olan adaptörleri yalnızca alır ``` -`import failproofai_sdk` sözleşmeli olarak sıfır bağımlılıktır, yerleşik tekerleği `--no-deps` ile kuran ve hiçbir çerçevenin `sys.modules` erişmemesini kanıtlayan başka bir test tarafından uygulanır. +`import failproofai_sdk` sözleşmeli olarak sıfır bağımlılık, inşa edilen tekerleği `--no-deps` ile kuran bir test ve hiçbir çerçevenin `sys.modules` ulaşmadığını kanıtlayan başka bir test tarafından zorunlu. - `failproofai_sdk.crewai` niteliği yoktur. Adaptörler kasıtlı olarak en üst düzey pakette açığa çıkarılmaz: birini değmek, öznitelik erişiminin yan etkisi olarak çerçeveyi içe aktarır, sıfır bağımlılık vaadini kırarak. `instrument()` kullanın. + `failproofai_sdk.crewai` özniteliği yoktur. Adaptörler kasıtlı olarak üst düzey pakette ortaya çıkmaz: bir adaptörü dokunmak çerçeveyi bir öznitelik erişiminin yan etkisi olarak içe aktarır, sıfır bağımlılık sözünü kırar. `instrument()` kullanın. ```python -failproofai_sdk.instrument() # her çerçeve zaten içe aktarıldı -failproofai_sdk.instrument("crewai") # tam olarak bir, adıyla -failproofai_sdk.uninstrument("crewai") # geri koyun +failproofai_sdk.instrument() # her çerçeve zaten alındı +failproofai_sdk.instrument("crewai") # tam olarak biri, ada göre +failproofai_sdk.uninstrument("crewai") # geri koy ``` | Ad | Ayrıca kabul eder | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # geri koyun | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -Otomatik algılama `sys.modules` okur, yüklü paket listesi değil, bu nedenle kurmuş ancak asla içe aktarmadığınız bir çerçeve enstrümente edilmez ve asla sizin adınıza içe aktarılmaz. Neyin bağlı olduğunu görmek için: +Otomatik algılama `sys.modules` okur, yüklü paket listesi değil, bu nedenle yüklediğiniz ancak asla içe aktarmadığınız bir çerçeve alet takılmaz ve hiçbir zaman sizin adınıza alınmaz. Neler bağlıdır görmek için: ```python from failproofai_sdk.integrations import active, available @@ -567,132 +567,130 @@ active() # ('langchain',) ``` - **CrewAI olmayan bir makinede `instrument("crewai")` yükseltmez.** Bir uyarı kaydeder ve `()` döndürür, bu nedenle bir eksik çerçeve diğerlerini de enstrümante eden bir işlemi asla alır. + **CrewAI olmayan bir makinede `instrument("crewai")` yükseltmez.** Bir uyarı günlüğe kaydeder ve `()` döndürür, bu nedenle eksik bir çerçeve diğerlerini de alet takmayan bir işlemi asla çökertmez. - Uyarı temel `ImportError` taşır ve bu ileti tam kurulum komutu adlandırır — düzeltme günlüklerde gizli değildir. + Uyarı temel `ImportError` taşır ve bu ileti kesin kurulum komutunu adlandırır — bu nedenle onarım günlüklerinizde, gizli değildir. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Bunun yerine yükseltmesini sağlamak için `FAILPROOFAI_SDK_STRICT=1` ayarlayın. Bu bayrak **bir kez okunur ve önbelleğe alınır**, bu yüzden işleminiz başlamadan önce bunu dışa aktarın, çalışma sırasında ayarlamak yerine. + Bunun yerine yükseltmesini sağlamak için `FAILPROOFAI_SDK_STRICT=1` ayarlayın. Bu bayrak **bir kez okunur ve önbelleğe alınır**, bu nedenle mid-run ayarlamak yerine işleminiz başlamadan önce ihraç edin. - **`instrument()` çerçeve ithalinizin *sonra* gelmeli.** Otomatik algılama `sys.modules` okur, bu yüzden içeri aktarmanın üstünde açık bir çağrı hiçbir şey bulmaz, hiçbir şey yüklemez ve `()` döndürür. + **`instrument()` çerçeve alımınızdan *sonra* gelmelidir.** Otomatik algılama `sys.modules` okur, bu nedenle alımın üstünde bir çıplak çağrı hiçbir şey bulamaz, hiçbir şey kurmaz ve `()` döndürür. ```python Yanlış import failproofai_sdk -failproofai_sdk.instrument() # sys.modules'da henüz langchain yok -> () +failproofai_sdk.instrument() # sys.modules'te henüz langchain yok -> () import langchain # çok geç, hiçbir şey bağlı değil ``` ```python Doğru -import langchain # çerçeveyi ilk olarak içe aktarın +import langchain # ilk çerçeveyi içe aktarın import failproofai_sdk failproofai_sdk.instrument() # onu bulur -> ('langchain',) ``` -```python Doğru, sıra-kanıtlı +```python Doğru, düzen kanıtı import failproofai_sdk -# Adını verme, adaptörü talep üzerine yükler, bu yüzden buradan herhangi bir yerden işe yarar. +# Bunu adlandırmak adaptörü isteğe bağlı olarak alır, bu nedenle buradan her yerde çalışır. failproofai_sdk.instrument("langchain") ``` -Bunu yanlış yapın ve işlem SDK'yı içe aktarılmış, adaptör görünüşte yüklenmiş ve **tek bir olayı yayınla olmayan** ile çalışır. Bu tam olarak söyleyen bir uyarı kaydeder — çalışma hiçbir şey kaydedildiğinde loglarınızı ilk kontrol edin. +Bunu yanlış aldıktan sonra işlem SDK alındı, adaptör görünen kurulu ve **hiçbir olay yayınlanmamış** dengan çalışır. Bu yayınlanan bir uyarı tam olarak söyler — bu nedenle bir çalışma hiçbir şey kaydettiğinde günlüklerinizi ilk kontrol edin. - + ```mermaid flowchart LR - A["Ajanız"] --> B["Adaptör"] - B --> C["Yazar
bellek içi kuyruk"] - C -->|"her 0.5s"| D["Makara
diskte JSONL"] + A["Sizin ajanınız"] --> B["Adaptör"] + B --> C["Yazar
bellek içi sıra"] + C -->|"her 0.5s"| D["Makara
diskette JSONL"] D --> E["Failproof daemon"] E -->|"HTTPS"| F["Bulut"] ``` -| Aşama | İş | Çalışır | +| Aşama | İş | Çalışması | | --- | --- | --- | -| Adaptör | Çerçeve geri çağrısını 15 olay türünden birine çevirir | İşleminiz | -| Yazar | Kuyruklar, toplar, JSONL atomik olarak yazar | İşleminiz, arka plan iş parçacığı | -| Makara | Dayanıklı teslim, işleminiz çıktığında hayatta kalır | Yerel disk | -| Daemon | Makarayı izler, topluları gönderir, gönderdiklerini siler | Makineniz | -| Ingest | Satır kimliği ve dedup anahtarı atar, sorgulanabilir sütunları yükseltir | Bulut | +| Adaptör | Çerçeve geri aramasını 15 olay türünden birine çevirir | Sizin işleminiz | +| Yazar | Kuyruklar, toplu işler, JSONL atomik olarak yazar | Sizin işleminiz, arka plan iş parçacığı | +| Makara | Dayanıklı teslim, işleminizin çıkışını devam ettirir | Yerel disk | +| Daemon | Makarayı izler, toplu işler gemi, ne gemi yaptığını siler | Sizin makineniz | +| Alım | Satır kimliği ve dedup anahtarı atar, sorgulanabilir sütunları yükseltir | Bulut | -Makara bunu güvenli yapar: ajanız hiçbir zaman ağda bloke olmaz ve Bulut kesintisi, kayıp olaylar yerine büyüyen bir dizin anlamına gelir. +Makara ne yapar güvenli bu: ajanınız hiçbir zaman ağda engellenmez ve Bulut kesintisi kayıp olaylar yerine büyüyen bir dizin anlamına gelir. -Her temizleme bir toplu dosya yazar, `.tmp` ilk, sonra `fsync`, sonra atomik yeniden adlandır: +Her temizleme bir toplu işlem dosyası yazar, ilk `.tmp`, sonra `fsync`, sonra atomik adı değiştir: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Daemon yalnızca `.jsonl` alır, bu nedenle asla yarı yazılı dosya okuyamaz. Gövde zaman damgası, işlem kimliği ve sıra numarası taşır, bu nedenle iki işlem aynı milisaniyede temizlenirse çarpışamaz. Kuyruk 10.000 olayda sınırlıdır; bunun ötesinde en eskisini bırakır ve kaydeder. +Daemon yalnızca `.jsonl` alır, bu nedenle hiçbir zaman yarı yazılı bir dosya okunamaz. Gövde bir zaman damgası, işlem kimliği ve sıra numarası taşır, bu nedenle iki işlem aynı milisaniye içinde temizleme yapabilen çarpışamaz. Sıra 10.000 olaya sınırlı; geçtikten sonra en eski bırakır ve günlüğe kaydeder. - **`collector.redact` SDK olaylarınıza uygulanmaz.** Asla onları görmez. + **`collector.redact` SDK olayları için de `minimal` varsayılan olarak belirtilir.** SDK diske bir toplu işlem yazmadan önce kaşıntı çıkarır ve daemon yeniden deneme sırasında aynı belirleneci geçişi yapar, böylece eski SDK'lardan toplu işlemler korunur. -Daemon **gönderir** topluları. Açmaz veya yeniden yazmaları yapmaz. +Daemon her toplu işlem okur ve bellekte yükleme öncesi redaction uygular. Okuduğu makara dosyasını yeniden yazmaz. -| Olaylar | Tarafından yazılan | `collector.redact` tarafından redakte mi? | +| Olaylar | Tarafından yazıldı | Minimal redaction nerede çalışır | | --- | --- | --- | -| CLI oturum transkriptleri | Daemon | Evet | -| Kancanın aktivitesi | Daemon | Evet | -| **SDK'nin yayınladığı her şey** | **İşleminiz** | **Hayır** | +| CLI oturum transkriptleri | Daemon | Daemon toplu işlem yazmadan önce | +| Kanca etkinliği | Daemon | Daemon toplu işlem yazmadan önce | +| **SDK yayınlayan her şey** | **Sizin işleminiz** | **SDK toplu işlem yazmadan önce ve daemon yükleme öncesi** | -Redaksiyon daemon'un kendi olaylarını *yazdığı* yerde çalışır — topluların *sevk edildiği* yerde değil. Bu yüzden bir istemi veya bir API anahtarı tutan araç bağımsız değişkeni varışta tutmaya devam eder. - -Bu kasıtlıdır. Bunlar kendi enstrümantasyon çağrılarınızdır ve bunları aktarım sırasında yeniden yazmak, aldığınız olayların yayınladığınız olaylar olmadığı anlamına gelir. +`collector.redact` yalnızca verbatim yükleri açık bir gereklilik olduğunda `off` ayarlayın; SDK ve daemon her ikisi de bu ayarı onurlandırır. Minimal redaction yaygın API anahtarlarını, taşıyıcı jetonlarını, JWT'leri ve gizli atamalarını yakalar. Keyfi hassas nesri tanımlayamaz. - **Yüklemeleri kaynakta kontrol edersiniz, iki yerde:** + **Kaynakta, iki yerde yükleri kontrol edersiniz:** - - Adaptörde içerik yakalamayı kapatın. **Seçenek adı farklıdır ve bir adaptörün hiçbiri yoktur** — bu tek evrensel anahtar değildir: + - Adaptör üzerinde içerik yakalamayı kapatın. **Seçenek adı farklıdır ve bir adaptör hiç yoktur** — bu tek bir evrensel anahtar değildir: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **içerik anahtarı hiç yoktur**; `session_id` okuduğu tek seçenektir, bu yüzden istekler ve tamamlamalar her zaman kaydedilir. + - CrewAI — **hiç içerik anahtarı yok**; `session_id` okuduğu tek seçenektir, bu nedenle istemler ve tamamlamalar her zaman kaydedilir. - `instrument()` bir adaptörün okumuyor olduğu seçenekleri bırakır, bu nedenle yanlış adı iletmek hiçbir şey yükseltmez ve hiçbir şey değiştirmez. - - Sırrı ilk yerde `input=` tutmayın. + `instrument()` bir adaptörün okumadığı seçenekleri düşürür, bu nedenle yanlış adı geçirmek hiçbir şeyi yükseltmez ve değiştiremez. + - Gizli anahtarı ilk yerde `input=` adresine geçirmeyin. - `collector.redact` ikisi için bir yedek değil. + `collector.redact` derinlemesine savunma, ikisinin yerine değildir. - **Boş bir makara dizini sağlıklı durumdur.** Teslimi kontrol etmek için kullanmayın. + **Boş bir makara dizini sağlıklı durumdur.** Teslimatı kontrol etmek için kullanmayın. -Daemon her topluyu gönderdikten sonra milisaniyeler içinde siler, bu yüzden `ls` toplayıcıyı yarışır ve yayınladığınız kesirini gösterir — hiçbir şey kaydeden bir SDK'dan ayırt edilemez. +Daemon her toplu işlem yükleme sayılı milisaniye içinde siler, bu nedenle bir `ls` dedektif ve yayınladığınız kesrini gösterir — hiç bir SDK kayıtlı olmamış bir dedektiften ayırt edilemez. -Olayların gerçekten iniş yaptığını doğrulamak için gösterge panelini kontrol edin. Makarayı dolmaya karşı izlemek için daemon'u ilk durdurun. +Olayların gerçekten indiğini doğrulamak için panoyu kontrol edin. Makara doldurmak için izlemek için ilk daemon'u durdurun. - + -Her geri çağrı, tek işi yeniden yükseltmek olan bir sarıcı içinde çalışır, bu nedenle çağrınız tam olarak bir `try` içinde oturur ve SDK'nın yaptığı her şey bunun dışında olur. +Her geri arama, tek işi yeniden yükseltmek olan bir sarmalayıcı içinde çalışır, bu nedenle çağrınız tam olarak bir `try` ve SDK'nın yaptığı her şey dışında oturur. | Ne oldu | Sonuç | | --- | --- | -| Bir kancanın yükseltmesi | Traceback ile bir kez kaydedildi. Çağrınız etkilenmez | -| Aynı kancanın üç kez yükseltmesi | O bir kancanın geri kalanı için devre dışı, tek bir hata satırı | -| `FAILPROOFAI_SDK_STRICT=1` ayarlanmış | İstisna bunun yerine yeniden yükseltildi | -| Bir çerçeve sürümü test edilen aralığın dışında | Uyarılar bir kez, yine de enstrümente eder | -| Tek bir yetenek eksik | O bir kancanın devre dışı, asla tüm adaptör | +| Bir kanca yükseltilir | Traceback ile bir kez günlüğe kaydedildi. Çağrınız etkilenmez | +| Aynı kanca üç kez yükseltilir | O kanca, işlem geri kalanı için devre dışı bırakılır, bir hata satırı ile | +| `FAILPROOFAI_SDK_STRICT=1` ayarlandı | İstisna bunun yerine yeniden yükseltilir | +| Bir çerçeve sürümü sınanan aralığın dışında | Bir kez uyarır, yine de araç takın | +| Tek bir yetenek eksiktir | O kanca devre dışı bırakılır, asla adaptörün tamamı değil | -Varsayılan, üretimde doğru ve hata ayıklarken yanlıştır, çünkü yalnızca hiçbir zaman çökmediğini kanıtlayabilir. Yutkunmuş bir başarısızlığı yüksek sesle yapmak için `FAILPROOFAI_SDK_STRICT=1` ayarlayın. +Varsayılan üretimde doğrudur ve hata ayıklama sırasında yanlış, çünkü sadece "çökertmedi" kanıtlayabilir. Yutulmuş bir başarısızlığı yüksek yapmak için `FAILPROOFAI_SDK_STRICT=1` ayarlayın. @@ -701,24 +699,24 @@ Varsayılan, üretimde doğru ve hata ayıklarken yanlıştır, çünkü yalnız ## Yaygın sorunlar - - Açma olayı kapatma olayı olmaz: `model_response` olmayan `model_request` veya `tool_result` olmayan `tool_use`. Kapsamları kullanın, gövde yükseltirse bile çifti garanti ederler. Olay yöntemlerini doğrudan çağrırsanız, `try` ve `finally` kullanın. + + Bir açılış olayının hiçbir kapatma olayı yoktur: `model_response` olmayan `model_request` veya `tool_result` olmayan `tool_use`. Gövde yükselttiğinde bile çifti garantileyen kapsamları kullanın. Olay yöntemlerini doğrudan çağırırsanız, `try` ve `finally` kullanın. - - Eşleşen açma olayından ölçüldüğü için `tool_result`, `hook_completed`, `agent_resume` ve `human_input` üzerinde reddedilir. `model_response` üzerinde kabul edilir, çünkü yalnızca siz gerçek sağlayıcı gecikmesini bilirsiniz ve bir tamsayı olmalı. + + Eşleşen açılış olayından ölçülür, bu nedenle `tool_result`, `hook_completed`, `agent_resume` ve `human_input` üzerinde reddedilir. `model_response` adresinde kabul edilir, çünkü gerçek sağlayıcı gecikmesi yalnızca sizin biliyor ve tamsayı olması gerekir. - - İş parçacığı asla bağlamı devralması olmadı. Çağrıyı `failproofai_sdk.propagate()` içine sarın. Bkz. [İş parçacıkları ve async](#threads-and-async). + + İş parçacığı hiçbir zaman bağlamı devralması. Çağrılanı `failproofai_sdk.propagate()` içinde sarmalayın. [İş parçacıkları ve async](#threads-and-async) adresine bakın. - Ekstra alanlar son olarak birleşir, bu nedenle `model` veya `outcome` gibi gerçek alana benzer bir ad, onu yeniden yazar ve depolanmış sütunu değiştirir. Sizinkini ad alanı yapın; adaptörler bir `fw_` ön eki kullanır. + Ekstra alanlar en son birleşir, bu nedenle `model` veya `outcome` gibi gerçek bir alanın adıyla biri bunu üzerine yazardı ve depolanmış bir sütunu değiştirir. Sizinkini ad alanı; adaptörler bir `fw_` öneki kullanır. - - `agent_id` düşük kardinalite yönüdür ve bir çalışma kimliğini içine koydunuz. Rol veya düğüm adı kullanın ve gerçek kimliği yayın alanına koyun. + + `agent_id` düşük kardinalite nitelik ve siz buna bir çalışma kimliği koydunuz. Bir rol veya düğüm adı kullanın ve gerçek kimliği bir yük alanına koyun. @@ -728,8 +726,8 @@ Varsayılan, üretimde doğru ve hata ayıklarken yanlıştır, çünkü yalnız Çiftler, kimlikler, oturum yaşam döngüsü ve teslim. - - Az önce yakaladığınız oturum aracılığıyla nedenselliği takip edin. + + Yeni yakaladığınız oturum aracılığıyla nedenselliği izleyin. LangGraph, CrewAI, LlamaIndex ve Pydantic AI. diff --git a/docs/vi/start/integrations/custom-agents.mdx b/docs/vi/start/integrations/custom-agents.mdx index 6a0b9f03..31fc9ed0 100644 --- a/docs/vi/start/integrations/custom-agents.mdx +++ b/docs/vi/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "Các agent tùy chỉnh" sidebarTitle: "Các agent tùy chỉnh" -description: "Công cụ hóa một agent bạn tự viết hoặc một framework mà Failproof AI không có adapter cho." +description: "Instrument một agent mà bạn đã viết, hoặc một framework mà Failproof AI không có adapter cho." icon: "code" --- -Đối với một agent mà bạn tự viết, hoặc một framework mà Failproof AI không có adapter cho. Không có gì phải công cụ hóa: bạn phát ra các sự kiện. +Đối với một agent mà bạn đã viết hoặc một framework mà Failproof AI không có adapter cho. Không có gì để instrument: bạn phát ra các sự kiện. -Đây là cùng một API mà bốn adapter framework gọi bên dưới. Chúng là các bảng dịch của nó. +Đây là cùng một API mà bốn framework adapter gọi bên dưới. Chúng là bảng dịch lên nó. ## Cài đặt @@ -15,42 +15,42 @@ icon: "code" pip install failproofai-sdk ``` -Không có thêm gì, và không có phụ thuộc. +Không có extras và không có phụ thuộc. -## Công cụ hóa +## Instrument ```python import failproofai_sdk failproofai_sdk.configure(environment="production") -with failproofai_sdk.session(): # one run - with failproofai_sdk.agent("planner"): # one unit of work +with failproofai_sdk.session(): # một run + with failproofai_sdk.agent("planner"): # một đơn vị công việc with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # one tool call + t.output = search(q) # một lệnh gọi công cụ ``` -Đọc từ trên xuống dưới và nó nói những gì nó có nghĩa: +Đọc từ trên xuống dưới và nó nói ra ý của nó: -| Bao nó trong | Để nói | +| Bao bọc nó trong | Để nói | | --- | --- | -| `session()` | Những sự kiện này thuộc về cùng một lần chạy | -| `agent()` | Có cái gì đó đang làm việc — đặt tên cho nó bằng tên mà bạn sẽ nhận ra trong danh sách | -| `tool_call()` | Đây là một công cụ, và đây là những gì nó trả về | +| `session()` | Những sự kiện này thuộc cùng một run | +| `agent()` | Cái gì đó đang làm việc — hãy đặt tên cho nó mà bạn sẽ nhận ra trong một danh sách | +| `tool_call()` | Đây là một công cụ và đây là kết quả trả về của nó | -Và những gì mỗi cái thực sự phát ra: +Và kết quả thực tế mà mỗi cái phát ra: | Phạm vi | Phát ra | Mục đích | | --- | --- | --- | -| `session()` | Không có gì | Liên kết một session id, nhóm một lần chạy | -| `agent()` | `agent_start`, `agent_end` | Dấu ngoặc một đơn vị công việc | -| `tool_call()` | `tool_use`, `tool_result` | Dấu ngoặc một công cụ và đo lường nó | +| `session()` | Không có gì | Ràng buộc một session id, nhóm một run | +| `agent()` | `agent_start`, `agent_end` | Đặt dấu ngoặc cho một đơn vị công việc | +| `tool_call()` | `tool_use`, `tool_result` | Đặt dấu ngoặc cho một công cụ và đo lường nó | -Mọi thứ bên trong có thể bỏ qua `session_id` và `agent_id`. Các phạm vi liên kết danh tính trên các biến ngữ cảnh và mỗi lệnh gọi sự kiện đọc lại nó, vì vậy bạn không bao giờ phải điều phối các id thông qua các hàm của bạn. +Mọi thứ bên trong có thể bỏ qua `session_id` và `agent_id`. Các phạm vi ràng buộc nhận dạng trên các biến ngữ cảnh và mỗi lệnh gọi sự kiện đều đọc nó trở lại, do đó bạn không bao giờ phải truyền id qua các hàm của mình. Cả ba đều hoạt động dưới `async with` cũng như `with`. -Lồng các agent xây dựng cây. `parent_id` và độ sâu được tính từ ngăn xếp: +Lồng các agent xây dựng cây. `parent_id` và độ sâu được tính toán từ ngăn xếp: ```python with failproofai_sdk.session(): @@ -63,18 +63,18 @@ with failproofai_sdk.session(): `agent()` xử lý ngoại lệ cho bạn: -| Những gì xảy ra | Sự kiện | Kết quả | +| Chuyện gì đã xảy ra | Sự kiện | Kết quả | | --- | --- | --- | -| Không có gì được nâng lên | `agent_end` | `success` | +| Không có gì được raise | `agent_end` | `success` | | `Exception` | `error`, sau đó `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, sau đó `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | chỉ `agent_end` | `cancelled` | -Lỗi được phát ra trước `agent_end`, bởi vì bảng điều khiển đóng span tại `agent_end` và bất cứ điều gì sau đó được quy cho không có gì. Hủy bỏ không phải là thất bại, vì vậy các lần chạy bị hủy không làm ô nhiễm bề mặt lỗi. Ngoại lệ luôn được nâng lại: một phạm vi không bao giờ nuốt chửng. +Lỗi được phát ra trước `agent_end`, vì dashboard đóng span tại `agent_end` và bất kỳ thứ gì sau nó đều được ghi cho không có gì. Hủy bỏ không phải là một thất bại, do đó các run bị hủy không làm ô nhiễm bề mặt lỗi. Ngoại lệ luôn được tạo lại: một phạm vi không bao giờ nuốt chửng. ## Các phương thức sự kiện -Mười năm phương thức trong sáu gia đình. Hầu hết đều đi thành cặp — bạn phát ra phần mở, sau đó là phần đóng, và SDK đo khoảng thời gian giữa chúng. +Mười lăm phương thức trong sáu gia đình. Hầu hết đều có dạng cặp — bạn phát ra phần mở, sau đó là phần đóng, và SDK đo lường khoảng giữa chúng. | Gia đình | Mở | Đóng | Độc lập | | --- | --- | --- | --- | @@ -87,7 +87,7 @@ Mười năm phương thức trong sáu gia đình. Hầu hết đều đi thàn | **Failures** | — | — | `error` | - Ưu tiên các phạm vi — `agent()` và `tool_call()` — ở bất kỳ nơi nào chúng phù hợp. Chúng đảm bảo sự kiện đóng ngay cả khi phần nội dung tăng. Chuyển đến các phương thức này trực tiếp khi luồng điều khiển của bạn không lồng nhau, chẳng hạn như lệnh gọi mô hình bên trong một trợ giúp. + Ưu tiên các phạm vi — `agent()` và `tool_call()` — ở bất cứ nơi nào chúng phù hợp. Chúng đảm bảo sự kiện đóng ngay cả khi phần thân raise. Hãy sử dụng các phương thức này trực tiếp khi dòng điều khiển của bạn không lồng nhau, chẳng hạn như lệnh gọi mô hình bên trong trợ giúp. @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **Hai gia đình con người chỉ theo hướng ngược lại.** + **Hai gia đình con người chỉ theo các hướng ngược lại.** - | Phương thức | Ý nghĩa | + | Phương thức | Nghĩa | | --- | --- | | `human_wait` / `human_input` | **Agent yêu cầu một người** — cổng phê duyệt, câu hỏi làm rõ | - | `human_pause` / `human_interrupt` | **Một người hành động trên agent** — nút dừng, tạm dừng người điều hành | + | `human_pause` / `human_interrupt` | **Một người hoạt động trên agent** — nút dừng, tạm dừng của người điều hành | - Không có framework nào báo hiệu cặp thứ hai, vì vậy nó luôn là của bạn để phát ra. + Không có framework nào phát tín hiệu cho cặp thứ hai, do đó nó luôn là của bạn để phát ra. - **Chuyển `request_id` khi các lệnh gọi mô hình chạy đồng thời.** Nếu không có nó, các yêu cầu và phản hồi ghép thành từng lệnh gọi trên mỗi agent — và các lệnh gọi đồng thời bị ghép sai, gắn mỗi phản hồi vào yêu cầu sai. + **Chuyển `request_id` khi các lệnh gọi mô hình chạy song song.** Nếu không có nó, các yêu cầu và phản hồi ghép nối theo thứ tự đến hạn trên mỗi agent — và các lệnh gọi song song bị ghép nối sai, gắn mỗi phản hồi vào yêu cầu sai. ## Ví dụ -Một vòng lặp gọi công cụ trên API OpenAI, không có framework agent: +Một vòng lặp gọi công cụ chống lại API OpenAI, không có agent framework: ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """One model call, bracketed by the pair.""" + """Một lệnh gọi mô hình, được đặt dấu ngoặc bởi cặp.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -204,52 +204,52 @@ with failproofai_sdk.session(): }) ``` -Điều đó tạo ra cùng sáu loại sự kiện mà một adapter sẽ cung cấp cho bạn. Phiên bản chạy được hoàn chỉnh, với các định nghĩa công cụ, được gửi trong kho SDK dưới `docs/manual/examples/`. +Điều đó tạo ra cùng sáu loại sự kiện mà một adapter sẽ cho bạn. Phiên bản chạy được hoàn chỉnh, với các định nghĩa công cụ, được gửi trong kho SDK dưới `docs/manual/examples/`. -## Luồng và async +## Threads và async -Các biến ngữ cảnh lan truyền vào các tác vụ asyncio một cách tự động. Họ không lan truyền vào các luồng mới, bởi vì một luồng bắt đầu với một ngữ cảnh trống. +Các biến ngữ cảnh lan truyền vào tác vụ asyncio tự động. Chúng không lan truyền vào các thread mới, vì một thread bắt đầu với bối cảnh trống. ```python -# asyncio: nothing to do +# asyncio: không cần làm gì async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads: wrap the callable +# threads: bao bọc callable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Nếu không có `propagate()`, sự kiện của worker sẽ tăng lên một `TypeError` đặt tên cho phần sửa chữa chứ không là đếm không có session. Điều này cố ý: một sự kiện không có session bị bỏ qua bằng cách nhập và trả lời `200`, đó là lỗi im lặng mà lớp danh tính tồn tại để ngăn chặn. +Nếu không có `propagate()`, các sự kiện của worker sẽ raise `TypeError` đặt tên cho bản sửa chữa thay vì hạ cánh trên không session. Điều đó là cố ý: một sự kiện không có session được bỏ qua bởi ingest và trả lời `200`, đó là lỗi yên tĩnh mà tầng nhận dạng tồn tại để ngăn chặn. -## Công cụ hóa một framework mà không có adapter +## Instrument một framework mà không có adapter -Mỗi framework agent cung cấp cho bạn ba đường nối tương tự. Ánh xạ chúng và bạn có một dấu vết hoàn chỉnh — bốn adapter được gửi không làm gì nhiều hơn thế. +Mỗi agent framework đều cung cấp cho bạn ba chỗ điểm. Ánh xạ chúng và bạn có một dấu vết hoàn chỉnh — bốn adapter được gửi không làm gì nhiều hơn thế. -| Đường nối | Những gì bạn viết | Những gì hạ cánh | +| Chỗ điểm | Cái bạn viết | Cái hạ cánh | | --- | --- | --- | -| Lần chạy | `session()` + `agent()` | `agent_start`, `agent_end` | +| Run | `session()` + `agent()` | `agent_start`, `agent_end` | | Mỗi công cụ | `tool_call()` | `tool_use`, `tool_result` | | Mỗi lệnh gọi mô hình | Cặp `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - Ở bất kỳ nơi nào framework gọi trình bao bọc công cụ hoặc middleware. + + Trong bất kỳ cái mà framework gọi là một bộ gói công cụ hoặc middleware. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -264,31 +264,31 @@ Mỗi framework agent cung cấp cho bạn ba đường nối tương tự. Ánh - **Có một nút, bước hoặc ranh giới middleware đáng xem?** Bao nó trong một cặp hook — `hook_triggered` / `hook_completed` — không phải một `agent()` lồng nhau. `agent_id` là một khía cạnh cardinality thấp, và một mục nhập trên mỗi nút làm chìm nó. Các khoảng hook hiển thị cùng cách và cung cấp cho bạn độ trễ trên mỗi nút. + **Có một node, step hoặc middleware boundary đáng nhìn?** Bao bọc nó trong một cặp hook — `hook_triggered` / `hook_completed` — không phải một `agent()` lồng nhau. `agent_id` là một facet cardinality thấp, và một entry trên mỗi node sẽ làm chìm nó. Hook span render cùng cách và cung cấp cho bạn độ trễ trên mỗi node. - **Tay và tự động soạn.** Một adapter chạy bên trong một phạm vi viết tay tham gia session đó và phụ huynh của đó, vì vậy bạn nhận được một cây chứ không phải hai — hữu ích khi bạn công cụ hóa một framework tự bên cạnh một cái được hỗ trợ. + **Manual và automatic kết hợp.** Một adapter chạy bên trong một phạm vi viết tay tham gia session đó và cha mẹ đó agent, do đó bạn nhận được một cây chứ không phải hai — hữu ích khi bạn instrument một framework tự mình cùng một được hỗ trợ. - - Hai lý do, và ba đường nối trên là câu trả lời cho cả hai: + + Hai lý do, và ba chỗ điểm ở trên là câu trả lời cho cả hai: - `autogen-core` đã không được bảo trì kể từ tháng 9 năm 2025. - - AG2 không cung cấp điểm đăng ký toàn bộ quy trình tương đương với các hook của các framework khác, vì vậy công cụ hóa nó có nghĩa là bao bọc mỗi agent ở mỗi trang xây dựng. + - AG2 không expose điểm đăng ký toàn quy trình tương đương với các hook của framework khác, do đó instrument nó có nghĩa là bao bọc mỗi agent tại mỗi trang xây dựng. - Ánh xạ các đường nối bằng tay ghi lại những sự kiện giống nhau, với cùng một độ tin cậy, như một adapter được gửi sẽ làm. + Ánh xạ các chỗ điểm bằng tay ghi lại các sự kiện tương tự, với cùng độ trung thực, như một adapter được gửi sẽ làm. ## Đi sâu hơn -Cách ghi âm thực sự hoạt động. Không cần thiết phải bắt đầu. +Cách ghi âm thực tế hoạt động. Không cần bất kỳ thứ gì trong số này để bắt đầu. - + -Mỗi bản ghi có cùng một hình dạng: một span mở, công việc lồng nhau bên trong nó, và mỗi sự kiện mở nhận được một sự kiện đóng. +Mỗi bản ghi đều có hình dạng tương tự: một span mở, công việc lồng nhau bên trong nó, và mỗi sự kiện mở lại nhận được một sự kiện đóng. ```mermaid flowchart LR @@ -300,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -**Cặp** là đơn vị. Mỗi sự kiện đóng mang một khoảng thời gian mà SDK đo lường từ sự kiện mở của nó. +**Cặp** là đơn vị. Mỗi sự kiện đóng mang theo một khoảng thời gian mà SDK đo từ cái mở của nó. -Dưới đây là một lần chạy thực tế trên mỗi framework — bắt được từ các ví dụ được gửi với SDK, tên mô hình bình thường hóa. Lưu ý bao nhiêu quay lại từ một lệnh gọi duy nhất. +Dưới đây là một run thực trên mỗi framework — được chụp từ các ví dụ được gửi với SDK, tên mô hình được chuẩn hóa. Lưu ý có bao nhiêu quay trở lại từ một lệnh gọi duy nhất. @@ -323,7 +323,7 @@ Dưới đây là một lần chạy thực tế trên mỗi framework — bắt 14 +5.721s agent_end LangGraph · success ``` - Các nút trở thành các cặp hook, vì vậy bạn nhận được độ trễ trên mỗi nút mà không có chúng làm chìm danh sách agent. + Node trở thành hook pair, do đó bạn nhận được độ trễ mỗi node mà không chúng tấn công danh sách agent. @@ -340,7 +340,7 @@ Dưới đây là một lần chạy thực tế trên mỗi framework — bắt 10 +5.739s agent_end crew · success ``` - Mỗi `role` của agent trở thành tên span của nó, vì vậy độ trễ và chi tiêu token chia nhỏ theo vai trò. + `role` của mỗi agent trở thành tên span của nó, do đó độ trễ và chi phí token chia nhỏ theo role. @@ -360,7 +360,7 @@ Dưới đây là một lần chạy thực tế trên mỗi framework — bắt 26 +7.038s agent_end Agent · success ``` - Vòng lặp agent chính nó là khả nhìn thấy, không chỉ các lệnh gọi mô hình của nó. + Vòng lặp agent tự nó đã hiển thị, không chỉ các lệnh gọi mô hình của nó. @@ -375,7 +375,7 @@ Dưới đây là một lần chạy thực tế trên mỗi framework — bắt 8 +8.119s agent_end agent · success ``` - Không có các cặp hook: Pydantic AI không có ranh giới nút hoặc bước để dấu ngoặc. + Không có hook pair: Pydantic AI không có node hoặc step boundary để đặt dấu ngoặc. @@ -388,17 +388,17 @@ Dưới đây là một lần chạy thực tế trên mỗi framework — bắt 6 +0.000s agent_end main · success ``` - Bạn phát ra những cái này. Các loại sự kiện giống nhau, cùng độ tin cậy — nó chi phí cho bạn các trang gọi. + Bạn phát ra các cái này tự mình. Cùng loại sự kiện, cùng độ trung thực — nó có giá là các trang gọi. - + -**Không có sự kiện kết thúc phiên.** Một phiên không phải là cái gì bạn đóng — nó là một nhóm các sự kiện chia sẻ một `session_id`. +**Không có session-end event.** Một session không phải là cái gì bạn đóng — nó là một nhóm sự kiện chia sẻ một `session_id`. -Trạng thái được lấy từ hình dạng của dấu vết: +Trạng thái được rút ra từ hình dạng của dấu vết: | Trạng thái | Khi nào | | --- | --- | @@ -407,17 +407,17 @@ Trạng thái được lấy từ hình dạng của dấu vết: | `error` | Không có gì mở, và ít nhất một sự kiện thất bại | | `done` | Không có gì mở, và không có gì thất bại | -Vì vậy, một phiên kết thúc khi mỗi cặp đóng. Các adapter phát ra `agent_end` cho bạn, và khi phân hủy chúng đóng bất cứ thứ gì vẫn mở và đánh dấu nó không đầy đủ — một lần chạy bị lỗi giải quyết dưới dạng `done` với một khoảng trống có thể nhìn thấy chứ không phải treo mãi mãi. +Vì vậy một session kết thúc khi mọi cặp được đóng. Các adapter phát ra `agent_end` cho bạn, và khi tắt chúng đóng bất kỳ thứ gì vẫn còn mở và đánh dấu nó không hoàn chỉnh — một run bị crash giải quyết là `done` với một khoảng trống nhìn thấy được chứ không phải treo. - Đây là lý do tại sao một phiên có thể kéo dài hai lệnh gọi. Một `interrupt()` LangGraph tạm dừng lần chạy, span gốc cố ý để mở, và lệnh gọi tiếp tục đóng nó. Cả hai lệnh gọi là một phiên. + Đây là lý do tại sao một session có thể trải dài hai cuộc gọi. Một LangGraph `interrupt()` tạm dừng run, root span cố ý giữ mở, và cuộc gọi tiếp tục đóng nó. Cả hai cuộc gọi là một session. - + -`session_id` và `agent_id` là tùy chọn trên mỗi phương thức sự kiện. Bỏ qua, chúng giải quyết từ phạm vi bao quanh: +`session_id` và `agent_id` là tùy chọn trên mỗi phương thức sự kiện. Được bỏ qua, chúng giải quyết từ phạm vi bao quanh: ```python with failproofai_sdk.session(): @@ -425,50 +425,50 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Chuyển chúng rõ ràng vẫn hoạt động và ưu tiên. Không có gì liên kết và không có gì được chuyển, lệnh gọi tăng lên `TypeError` đặt tên cho phần sửa chữa chứ không phải phát ra sự kiện không có phiên, cái mà ingest sẽ bỏ qua trong khi trả lời `200`. +Vượt qua chúng một cách rõ ràng vẫn hoạt động và có ưu tiên. Nếu không có gì bị ràng buộc và không có gì bị vượt qua, cuộc gọi sẽ raise `TypeError` đặt tên cho bản sửa chữa chứ không phát ra một sự kiện không có session, mà ingest sẽ bỏ qua trong khi trả lời `200`. -Phạm vi liên kết danh tính trên các biến ngữ cảnh. Những cái đó lan truyền vào các tác vụ asyncio một cách tự động nhưng không vào các luồng mới — bao một worker trong `failproofai_sdk.propagate()`. +Các phạm vi ràng buộc nhận dạng trên các biến ngữ cảnh. Những cái đó lan truyền vào tác vụ asyncio tự động nhưng không vào thread mới — bao bọc một worker trong `failproofai_sdk.propagate()`. #### Ai tạo ra id nào | Id | Được tạo bởi | Ghi chú | | --- | --- | --- | -| `session_id` | Bạn, hoặc SDK | `session("chat-42")` được sử dụng từng chữ; bỏ qua, SDK tạo một `uuid4().hex` | -| `agent_id` | Bạn, hoặc framework | Từ `agent("analyst")`, một `role` CrewAI, một `FunctionAgent.name`. Một giá trị trông giống như UUID bị từ chối và thay thế | -| `tool_call_id`, `hook_id`, `request_id` | Bạn, hoặc framework | Các adapter tái sử dụng các id chạy của riêng framework, đó là lý do tại sao các cặp sống sót qua bước hoa | -| **Event id** | **Cloud, tại ingest** | SDK không phát ra cái nào | -| **`dedup_key`** | **Cloud, tại ingest** | Một hash của org, phiên, dấu thời gian, loại và tải trọng. Đây là danh tính thực — nó làm cho một lô được thử lại sập thay vì sao chép | +| `session_id` | Bạn, hoặc SDK | `session("chat-42")` được sử dụng nguyên văn; bỏ qua, SDK tạo một `uuid4().hex` | +| `agent_id` | Bạn, hoặc framework | Từ `agent("analyst")`, một CrewAI `role`, một `FunctionAgent.name`. Một giá trị giống UUID bị từ chối và thay thế | +| `tool_call_id`, `hook_id`, `request_id` | Bạn, hoặc framework | Adapter tái sử dụng id run riêng của framework, đó là lý do tại sao các cặp sống sót qua thread hop | +| **Event id** | **Cloud, tại ingest** | SDK không phát ra bất kỳ cái nào | +| **`dedup_key`** | **Cloud, tại ingest** | Một hash của org, session, timestamp, type và payload. Đây là nhận dạng thực — nó làm cho một batch được thử lại bị sụp đổi thay vì nhân đôi | -#### Cách các adapter giải quyết `session_id` +#### Làm thế nào các adapter giải quyết `session_id` -Trận đấu đầu tiên thắng: +Trận đầu tiên thắng: -1. Một `session_id` tùy chọn rõ ràng -2. Siêu dữ liệu trên mỗi cuộc gọi +1. Một tùy chọn `session_id` rõ ràng +2. Metadata mỗi cuộc gọi 3. Phạm vi `session()` bao quanh -4. Siêu dữ liệu framework -5. Id chạy của riêng framework +4. Metadata framework +5. Id run riêng của framework -Nó không bao giờ được phát minh trong khi một trong những cái đó tồn tại — một id tổng hợp sẽ chia một lần chạy thành nhiều phiên. +Nó không bao giờ được phát minh trong khi một cái đó tồn tại — một id tổng hợp sẽ chia một run thành nhiều session. #### Giữ `agent_id` cardinality thấp -Đó là khía cạnh chính trên mỗi bề mặt bảng điều khiển, và một cột `LowCardinality(String)`. Một giá trị trên mỗi lần chạy làm giảm cột và lấp đầy thả xuống bộ lọc với một mục nhập trên mỗi lần chạy. +Nó là facet chính trên mọi bề mặt dashboard, và một cột `LowCardinality(String)`. Một giá trị mỗi run làm giảm chất lượng cột và lấp đầy dropdown bộ lọc bằng một entry trên mỗi run. Các adapter bảo vệ cột đó cho bạn: -| Framework trao | Được ghi lại dưới dạng | Tại sao | +| Framework trao | Ghi lại là | Tại sao | | --- | --- | --- | -| `3f9a1c2b-…` (một UUID) | `main` | Không có gì có thể đọc được để giữ | +| `3f9a1c2b-…` (một UUID) | `main` | Không có gì có thể đọc để giữ | | Một chuỗi hex trần dài | `main` | Giống nhau | -| `agent-3f9a1c2b-…` | `agent` | Id trên mỗi lần chạy bị tước, phần có thể đọc được được giữ | -| `agent-v2` | `agent-v2` | Các đoạn ngắn bị bỏ lại | +| `agent-3f9a1c2b-…` | `agent` | Id per-run bị tước, phần có thể đọc được được giữ | +| `agent-v2` | `agent-v2` | Các phân đoạn ngắn bị bỏ lại | | `step-3` | `step-3` | Giống nhau | -Id thực được giữ trên `fw_agent_id` / `fw_run_id`, nơi nó vẫn có thể truy vấn được mà không là một khía cạnh. +Id thực được giữ trên `fw_agent_id` / `fw_run_id`, nơi nó vẫn có thể truy vấn được mà không phải là một facet. - **Bảo vệ này chỉ chạm vào các nhãn mà *framework* lựa chọn.** Một `agent_id` mà bạn tự chuyển — để `event.*`, hoặc để `failproofai_sdk.agent(...)` — được ghi lại chính xác như đã cho. Im lặng viết lại một đối số rõ ràng sẽ tệ hơn cardinality mà nó ngăn chặn, vì vậy đặt tên cho các span của riêng bạn phù hợp. + **Cái này bảo vệ chỉ các nhãn *framework* được chọn.** Một `agent_id` bạn vượt qua chính mình — để `event.*`, hoặc để `failproofai_sdk.agent(...)` — được ghi lại chính xác như được cho. Yên tĩnh viết lại một argument rõ ràng sẽ tồi tệ hơn cardinality nó ngăn chặn, vì vậy hãy đặt tên cho span của riêng bạn cho phù hợp. @@ -484,25 +484,25 @@ Id thực được giữ trên `fw_agent_id` / `fw_run_id`, nơi nó vẫn có t | Humans | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | Failures | `error` | -Framework nào ghi lại gì, được đo lường từ các lần chạy trên: +Framework nào ghi lại cái gì, được đo từ các run ở trên: | Sự kiện | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | | Bắt đầu và kết thúc agent | Có | Có | Có | Có | Bạn | -| Yêu cầu mô hình và phản hồi | Có | Có | Có | Có | Bạn | +| Yêu cầu và phản hồi mô hình | Có | Có | Có | Có | Bạn | | Sử dụng công cụ và kết quả | Có | Có | Có | Có | Bạn | -| Hook được kích hoạt và hoàn thành | Nút | Nhiệm vụ | Bước | — | Bạn | +| Hook triggered và completed | Node | Task | Step | — | Bạn | | Lỗi | Có | Có | Có | Có | Tự động | -| Con người chờ và đầu vào | Có | Có | Có | — | Bạn | -| Agent tạm dừng và tiếp tục | Có | Có | Có | — | Bạn | +| Con người chờ và nhập | Có | Có | Có | — | Bạn | +| Tạm dừng và tiếp tục agent | Có | Có | Có | — | Bạn | -Một dấu gạch ngang có nghĩa là framework không có khái niệm như vậy. `human_pause` và `human_interrupt` mô tả một *người* hành động trên agent, mà không có framework nào báo hiệu — tự phát ra những cái đó. +Một dấu gạch ngang có nghĩa là framework không có khái niệm như vậy. `human_pause` và `human_interrupt` mô tả một *người* hoạt động trên agent, mà không có framework nào phát tín hiệu — phát ra những cái đó tự mình. -Một sự kiện không bao giờ đến một mình. Một cái mở một span, một cái đóng nó, và sự kiện đóng mang một khoảng thời gian mà SDK đo lường từ sự kiện mở của nó. +Một sự kiện không bao giờ đến một mình. Một mở một span, một đóng nó, và sự kiện đóng mang theo một khoảng thời gian mà SDK đo từ cái mở của nó. | Mở | Đóng | Sự kiện đóng mang theo | | --- | --- | --- | @@ -510,44 +510,44 @@ Một sự kiện không bao giờ đến một mình. Một cái mở một spa | `model_request` | `model_response` | token, `stop_reason`, độ trễ | | `tool_use` | `tool_result` | `output` hoặc `error`, khoảng thời gian | | `hook_triggered` | `hook_completed` | `outcome`, khoảng thời gian | -| `agent_pause` | `agent_resume` | bao lâu tạm dừng kéo dài | -| `human_wait` | `human_input` | câu trả lời, và bao lâu người đó mất | +| `agent_pause` | `agent_resume` | tạm dừng kéo dài bao lâu | +| `human_wait` | `human_input` | câu trả lời, và người tốn bao lâu | - Một sự kiện mở mà không có sự kiện đóng là một span không bao giờ kết thúc. Phiên hiển thị vẫn chạy, mãi mãi, và khoảng thời gian hoạt động của nó tiếp tục phát triển. Đây là chế độ lỗi để xem xét khi bạn công cụ hóa bằng tay. + Một sự kiện mở mà không có sự kiện đóng là một span không bao giờ hoàn thành. Session render như vẫn đang chạy, mãi mãi, và khoảng thời gian hoạt động của nó tiếp tục tăng. Đây là chế độ thất bại để xem khi bạn instrument bằng tay. #### Quy tắc tương quan - Tái sử dụng cùng `tool_call_id`, `hook_id`, `pause_id`, hoặc `input_id` cho sự kiện hoàn thành phù hợp. -- SDK tính toán `duration_ms` cho `tool_result`, `hook_completed`, `agent_resume`, và `human_input`. Chuyển nó cho những phương thức đó tăng `ValueError`. -- `duration_ms` **được** chấp nhận trên `model_response`, bởi vì chỉ người gọi biết độ trễ nhà cung cấp thực sự. Nó phải là một số nguyên — một float tăng `ValueError` tại trang gọi, bởi vì máy chủ đọc cột dưới dạng số nguyên 32-bit không dấu và sẽ lưu trữ NULL cho bất cứ điều gì khác. -- Khóa tương quan được phạm vi theo loại và phiên, vì vậy lệnh gọi công cụ và một hook có thể an toàn chia sẻ một id, và hai phiên đồng thời có thể tái sử dụng các id giống nhau mà không va chạm. Chúng không được phạm vi bởi agent: một cặp mở dưới một agent và đóng dưới một agent khác vẫn tương quan, đó là trường hợp thông thường trong các framework đa agent. -- `request_id` ghép `model_request` với `model_response`. Nếu không có nó, các sự kiện mô hình ghép theo thứ tự trên mỗi agent, vì vậy các lệnh gọi đồng thời bị ghép sai. -- Một cặp phân tách qua các quy trình vẫn tương quan xuôi dòng, nhưng SDK không thể tính toán khoảng thời gian trong quy trình của nó. -- Bản đồ chờ đợi giữ tối đa 10.000 bắt đầu và loại bỏ mục nhập cũ nhất khi đầy. +- SDK tính toán `duration_ms` cho `tool_result`, `hook_completed`, `agent_resume`, và `human_input`. Vượt qua nó cho các phương thức đó sẽ raise `ValueError`. +- `duration_ms` **được** chấp nhận trên `model_response`, vì chỉ người gọi biết độ trễ nhà cung cấp thực. Nó phải là một số nguyên — một float sẽ raise `ValueError` tại trang gọi, vì máy chủ đọc cột là một số nguyên 32-bit không dấu và sẽ lưu trữ NULL cho bất kỳ thứ gì khác. +- Kóa tương quan được định phạm vi theo loại và session, vì vậy một lệnh gọi công cụ và một hook có thể an toàn chia sẻ một id, và hai session đồng thời có thể tái sử dụng cùng id mà không va chạm. Chúng không được định phạm vi theo agent: một cặp mở dưới một agent và đóng dưới một agent khác vẫn tương quan, đây là trường hợp thông thường trong framework đa agent. +- `request_id` ghép nối `model_request` với `model_response`. Nếu không có nó, các sự kiện mô hình ghép nối theo thứ tự trên mỗi agent, vì vậy các lệnh gọi đồng thời bị ghép nối sai. +- Một cặp chia nhỏ trên các quy trình vẫn tương quan xuôi dòng, nhưng SDK không thể tính toán khoảng thời gian trong quy trình của nó. +- Bản đồ đang chờ xử lý giữ tối đa 10.000 lần bắt đầu và loại bỏ entry cũ nhất khi đầy. - + -Cài đặt `failproofai-sdk` cài đặt mọi thứ, cả bốn adapter được bao gồm. Các extras kéo **framework**, không phải adapter. +Cài đặt `failproofai-sdk` cài đặt mọi thứ, cả bốn adapter được bao gồm. Các extras kéo vào **framework**, không phải adapter. ```python -import failproofai_sdk # loads nothing outside the standard library -failproofai_sdk.instrument() # imports only the adapters you actually need +import failproofai_sdk # tải không có gì ngoài thư viện tiêu chuẩn +failproofai_sdk.instrument() # nhập chỉ các adapter bạn thực sự cần ``` -`import failproofai_sdk` được hợp đồng không phụ thuộc, được thực thi bởi một bài kiểm tra cài đặt bánh xe xây dựng với `--no-deps` và một bài kiểm tra khác chứng minh không có framework nào đến `sys.modules`. +`import failproofai_sdk` được hợp đồng bằng không phụ thuộc, thực thi bởi một bài kiểm tra cài đặt wheel xây dựng với `--no-deps` và một cái khác chứng minh không frame framework nào đạt `sys.modules`. - Không có thuộc tính `failproofai_sdk.crewai`. Các adapter cố ý không được phơi bày trên gói cấp cao: chạm vào một cái sẽ nhập framework như một tác dụng phụ của truy cập thuộc tính, phá vỡ lời hứa không phụ thuộc. Sử dụng `instrument()`. + Không có thuộc tính `failproofai_sdk.crewai`. Các adapter cố ý không được expose trên gói cấp cao: chạm vào một cái sẽ nhập framework như một tác dụng phụ của việc truy cập thuộc tính, phá vỡ lời hứa zero-dependency. Sử dụng `instrument()`. ```python -failproofai_sdk.instrument() # every framework already imported -failproofai_sdk.instrument("crewai") # exactly one, by name -failproofai_sdk.uninstrument("crewai") # put it back +failproofai_sdk.instrument() # mỗi framework đã được nhập +failproofai_sdk.instrument("crewai") # chính xác một, theo tên +failproofai_sdk.uninstrument("crewai") # đặt nó trở lại ``` | Tên | Cũng chấp nhận | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # put it back | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -Tự động phát hiện đọc `sys.modules`, không phải danh sách gói được cài đặt, vì vậy một framework bạn đã cài đặt nhưng không bao giờ nhập không được công cụ hóa và không bao giờ được nhập thay bạn. Để xem những gì được kết nối: +Phát hiện tự động đọc `sys.modules`, không phải danh sách gói được cài đặt, vì vậy một framework mà bạn có cài đặt nhưng không bao giờ nhập không được instrument và không bao giờ được nhập thay mặt bạn. Để xem cái gì được kết nối: ```python from failproofai_sdk.integrations import active, available @@ -567,50 +567,50 @@ active() # ('langchain',) ``` - **`instrument("crewai")` trên máy không có CrewAI không tăng.** Nó ghi một cảnh báo và trả về `()`, vì vậy một framework bị thiếu không bao giờ hạ một quy trình cũng công cụ hóa những cái khác. + **`instrument("crewai")` trên một máy không có CrewAI sẽ không raise.** Nó ghi lại cảnh báo và trả lại `()`, vì vậy một framework bị thiếu không bao giờ đánh bại một quy trình cũng instrument những cái khác. - Cảnh báo mang theo `ImportError` cơ bản, và tin nhắn đó đặt tên cho lệnh cài đặt chính xác — vì vậy bản sửa chữa nằm trong nhật ký của bạn, không bị ẩn. + Cảnh báo mang theo `ImportError` cơ bản, và thông điệp đó đặt tên cho lệnh cài đặt chính xác — vì vậy bản sửa chữa nằm trong log của bạn, không bị ẩn. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Đặt `FAILPROOFAI_SDK_STRICT=1` để làm cho nó tăng thay thế. Cờ đó được đọc **một lần và được lưu trong bộ đệm**, vì vậy xuất khẩu nó trước khi quy trình của bạn bắt đầu chứ không phải đặt nó giữa cuộc chạy. + Đặt `FAILPROOFAI_SDK_STRICT=1` để có nó raise thay thế. Cái cờ đó được đọc **một lần và cached**, vì vậy xuất nó trước khi quy trình của bạn bắt đầu thay vì đặt nó giữa run. - **`instrument()` phải đến *sau* nhập framework của bạn.** Tự động phát hiện đọc `sys.modules`, vì vậy một cuộc gọi trần trên nhập tìm không có gì, cài đặt không có gì, và trả về `()`. + **`instrument()` phải đến *sau* nhập framework của bạn.** Phát hiện tự động đọc `sys.modules`, vì vậy một lệnh gọi trần ở trên nhập tìm không có gì, cài đặt không có gì, và trả lại `()`. -```python Wrong +```python Sai import failproofai_sdk -failproofai_sdk.instrument() # sys.modules has no langchain yet -> () +failproofai_sdk.instrument() # sys.modules không có langchain chưa -> () -import langchain # too late, nothing is wired +import langchain # quá muộn, không có gì được kết nối ``` -```python Right -import langchain # import the framework first +```python Đúng +import langchain # nhập framework trước import failproofai_sdk -failproofai_sdk.instrument() # finds it -> ('langchain',) +failproofai_sdk.instrument() # tìm thấy nó -> ('langchain',) ``` -```python Right, order-proof +```python Đúng, order-proof import failproofai_sdk -# Naming it imports the adapter on request, so this works from anywhere. +# Đặt tên nó nhập adapter theo yêu cầu, vì vậy điều này hoạt động từ bất cứ đâu. failproofai_sdk.instrument("langchain") ``` -Sai cái này và quy trình chạy với SDK được nhập, adapter rõ ràng được cài đặt, và **không một sự kiện được phát ra**. Nó ghi một cảnh báo nói chính xác điều đó — vì vậy kiểm tra nhật ký của bạn trước khi một lần chạy ghi lại không có gì. +Làm sai điều này và quy trình chạy với SDK được nhập, adapter rõ ràng được cài đặt, và **không một sự kiện nào được phát ra**. Nó ghi lại cảnh báo nói chính xác điều đó — vì vậy hãy kiểm tra log của bạn trước khi một run ghi lại không có gì. - + ```mermaid flowchart LR @@ -623,102 +623,100 @@ flowchart LR | Giai đoạn | Công việc | Chạy trong | | --- | --- | --- | -| Adapter | Dịch lệnh gọi lại framework thành một trong 15 loại sự kiện | Quy trình của bạn | -| Writer | Xếp hàng, hàng loạt, viết JSONL một cách nguyên tử | Quy trình của bạn, luồng nền | -| Spool | Bàn giao bền, sống sót qua quá trình thoát của bạn | Đĩa cục bộ | -| Daemon | Xem spool, tàu hàng loạt, xóa những gì nó gửi | Máy của bạn | -| Ingest | Gán một hàng id và khóa dedup, thúc đẩy các cột có thể truy vấn | Cloud | +| Adapter | Dịch một callback framework thành một trong 15 loại sự kiện | Quy trình của bạn | +| Writer | Xếp hàng, batch, viết JSONL nguyên tử | Quy trình của bạn, thread nền | +| Spool | Handoff bền vững, sống sót qua quy trình của bạn thoát | Đĩa cục bộ | +| Daemon | Xem spool, ship batch, xóa cái nó gửi | Máy của bạn | +| Ingest | Gán một hàng id và dedup key, quảng bá các cột có thể truy vấn | Cloud | -Spool là những gì làm cho điều này an toàn: agent của bạn không bao giờ chặn trên mạng, và mất điện Cloud có nghĩa là một thư mục phát triển chứ không phải các sự kiện bị mất. +Spool là những gì làm điều này an toàn: agent của bạn không bao giờ chặn trên mạng, và một Cloud outage có nghĩa là một thư mục phát triển thay vì các sự kiện bị mất. -Mỗi xóa viết một tệp lô, `.tmp` đầu tiên, sau đó `fsync`, sau đó một đổi tên nguyên tử: +Mỗi flush viết một file batch, `.tmp` trước, sau đó `fsync`, sau đó một rename nguyên tử: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Daemon chỉ nhặt `.jsonl`, vì vậy nó không bao giờ có thể đọc một tệp nửa viết. Thân phần mang một dấu thời gian, id quy trình và số thứ tự, vì vậy hai quy trình xóa trong cùng một mili giây không thể va chạm. Hàng đợi bị giới hạn ở 10.000 sự kiện; quá điểm đó, nó bỏ cái cũ nhất và ghi nhật ký. +Daemon chỉ nhặt `.jsonl`, vì vậy nó không bao giờ đọc một file nửa viết. Thân mác mang theo một timestamp, process id và số thứ tự, vì vậy hai quy trình flush trong cùng một mili giây không thể va chạm. Hàng đợi được cắt ở 10.000 sự kiện; quá những gì nó thả cái cũ nhất và ghi lại. - **`collector.redact` không áp dụng cho các sự kiện SDK của bạn.** Nó không bao giờ nhìn thấy chúng. + **`collector.redact` mặc định `minimal` cho sự kiện SDK quá.** SDK tẩy sạch trước khi viết một batch để đĩa, và daemon lặp lại cùng một pass xác định trước khi tải lên vì vậy batch từ SDK cũ được bảo vệ. -Daemon **tàu** lô của bạn. Nó không mở hoặc viết lại chúng. +Daemon đọc mỗi batch và áp dụng redaction trong bộ nhớ trước khi tải lên. Nó không viết lại file spool nó đọc. -| Sự kiện | Viết bởi | Được chỉnh sửa bởi `collector.redact`? | +| Sự kiện | Viết bởi | Nơi redaction tối thiểu chạy | | --- | --- | --- | -| Bản ghi phiên CLI | Daemon | Có | -| Hoạt động hook | Daemon | Có | -| **Mọi thứ SDK phát ra** | **Quy trình của bạn** | **Không** | +| Phiên bản ghi session CLI | Daemon | Trước daemon viết batch | +| Hoạt động hook | Daemon | Trước daemon viết batch | +| **Mọi thứ SDK phát ra** | **Quy trình của bạn** | **Trước SDK viết batch và lại trước daemon tải lên** | -Chỉnh sửa chạy ở nơi daemon *viết* sự kiện riêng của nó — không phải ở nơi lô được *gửi*. Vì vậy, một lời nhắc hoặc một đối số công cụ giữ một khóa API vẫn giữ nó trên lẫn. - -Điều đó cố ý. Đây là các cuộc gọi công cụ hóa của riêng bạn, và viết lại chúng trong quá trình không có nghĩa là các sự kiện bạn nhận được không phải là các sự kiện bạn phát ra. +Đặt `collector.redact` để `off` chỉ khi payload nguyên văn là một yêu cầu rõ ràng; SDK và daemon cả sẽ tôn trọng cài đặt đó. Redaction tối thiểu bắt các API key chung, bearer token, JWT, và gán bí mật. Nó không thể xác định đặc biệt prose nhạy cảm. - **Bạn kiểm soát tải trọng tại nguồn, ở hai nơi:** + **Bạn kiểm soát payload tại nguồn, ở hai nơi:** - - Tắt quay phim nội dung trên adapter. **Tên tùy chọn khác nhau, và một adapter không có cái nào** — đây không phải là một công tắc chung duy nhất: + - Tắt chụp nội dung trên adapter. **Tên tùy chọn khác nhau, và một adapter không có tùy chọn** — đây không phải là một công tắc phổ quát duy nhất: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **không có công tắc nội dung nào cả**; `session_id` là tùy chọn duy nhất nó đọc, vì vậy lời nhắc và hoàn thành luôn được ghi lại. + - CrewAI — **không công tắc nội dung nào cả**; `session_id` là tùy chọn duy nhất nó đọc, vì vậy prompt và completion luôn được ghi lại. - `instrument()` bỏ các tùy chọn một adapter không đọc, vì vậy chuyển tên sai không tăng và không thay đổi gì. - - Đừng trao bí mật cho `input=` ở nơi đầu tiên. + `instrument()` thả các tùy chọn mà adapter không đọc, vì vậy vượt qua tên sai sẽ không raise và không thay đổi gì cả. + - Đừng trao bí mật để `input=` ở nơi đầu tiên. - `collector.redact` không phải là thay thế cho cái nào cả. + `collector.redact` là bảo vệ sâu, không thay thế cho bất kỳ cái. - **Một thư mục spool trống là trạng thái lành mạnh.** Đừng sử dụng nó để kiểm tra giao hàng. + **Một thư mục spool trống là trạng thái khoẻ mạnh.** Đừng sử dụng nó để kiểm tra giao hàng. -Daemon xóa mỗi lô trong vài mili giây gửi nó, vì vậy một `ls` đua với bộ sưu tập và cho thấy một phần nhỏ những gì bạn phát ra — không thể phân biệt với một SDK không ghi lại được gì. +Daemon xóa mỗi batch trong mili giây gửi nó, vì vậy một `ls` đua daemon và hiển thị một phần của cái bạn phát ra — không thể phân biệt từ một SDK ghi lại không có gì. -Để xác nhận các sự kiện thực sự hạ cánh, kiểm tra bảng điều khiển. Để xem spool lấp đầy, dừng daemon trước tiên. +Để xác nhận sự kiện thực sự hạ cánh, kiểm tra dashboard. Để xem spool lấp đầy, dừng daemon trước. - + -Mỗi cuộc gọi lại chạy bên trong một trình bao bọc công việc duy nhất của nó là nâng lên lại, vì vậy cuộc gọi của bạn nằm trong chính xác một `try` và mọi thứ SDK làm xảy ra bên ngoài nó. +Mỗi callback chạy bên trong một bộ gói có công việc duy nhất là tạo lại, vì vậy cuộc gọi của bạn nằm trong chính xác một `try` và mọi thứ SDK làm xảy ra bên ngoài nó. -| Những gì xảy ra | Kết quả | +| Chuyện gì xảy ra | Kết quả | | --- | --- | -| Một móc tăng | Ghi lại một lần với dấu vết của nó. Cuộc gọi của bạn không bị ảnh hưởng | -| Cùng một móc tăng ba lần | Cái móc đó bị vô hiệu hóa cho phần còn lại của quy trình, với một dòng lỗi | -| `FAILPROOFAI_SDK_STRICT=1` được đặt | Ngoại lệ được nâng lại thay thế | -| Phiên bản framework ở ngoài phạm vi được kiểm tra | Cảnh báo một lần, công cụ hóa dù sao | -| Một khả năng duy nhất bị thiếu | Cái móc đó bị vô hiệu hóa, không bao giờ là toàn bộ adapter | +| Một hook raise | Ghi lại một lần với traceback của nó. Cuộc gọi của bạn không bị ảnh hưởng | +| Hook tương tự raise ba lần | Cái hook đó bị vô hiệu hóa cho phần còn lại của quy trình, với một hàng lỗi | +| `FAILPROOFAI_SDK_STRICT=1` được đặt | Ngoại lệ được tạo lại thay thế | +| Một phiên bản framework nằm ngoài phạm vi được kiểm tra | Cảnh báo một lần, instrument dù sao | +| Một khả năng duy nhất bị thiếu | Cái hook đó bị vô hiệu hóa, không bao giờ toàn bộ adapter | -Giá trị mặc định là đúng trong sản xuất và sai trong khi gỡ lỗi, bởi vì nó chỉ có thể chứng minh được "nó không bị sập". Đặt `FAILPROOFAI_SDK_STRICT=1` để làm cho một thất bại bị nuốt chửng trở nên ồn ào. +Mặc định là đúng ở production và sai trong khi gỡ lỗi, vì nó chỉ có thể chứng minh "nó không bị sập". Đặt `FAILPROOFAI_SDK_STRICT=1` để làm cho một thất bại nuốt chửng lớn. -## Vấn đề phổ biến +## Các vấn đề phổ biến - - Một sự kiện mở không có sự kiện đóng: một `model_request` không có `model_response`, hoặc một `tool_use` không có `tool_result`. Sử dụng các phạm vi, chúng đảm bảo cặp ngay cả khi phần nội dung tăng. Nếu bạn gọi các phương thức sự kiện trực tiếp, sử dụng `try` và `finally`. + + Một sự kiện mở không có sự kiện đóng: một `model_request` không có `model_response`, hoặc một `tool_use` không có `tool_result`. Sử dụng các phạm vi, những cái đó đảm bảo cặp ngay cả khi phần thân raise. Nếu bạn gọi các phương thức sự kiện trực tiếp, sử dụng `try` và `finally`. - - Nó được đo lường từ sự kiện mở phù hợp, vì vậy nó bị từ chối trên `tool_result`, `hook_completed`, `agent_resume`, và `human_input`. Nó được chấp nhận trên `model_response`, bởi vì chỉ bạn biết độ trễ nhà cung cấp thực sự, và nó phải là một số nguyên. + + Nó được đo từ sự kiện mở phù hợp, vì vậy nó bị từ chối trên `tool_result`, `hook_completed`, `agent_resume`, và `human_input`. Nó được chấp nhận trên `model_response`, vì chỉ bạn biết độ trễ nhà cung cấp thực, và nó phải là một số nguyên. - - Luồng không bao giờ kế thừa ngữ cảnh. Bao `callable` trong `failproofai_sdk.propagate()`. Xem [Luồng và async](#threads-and-async). + + Thread không bao giờ kế thừa bối cảnh. Bao bọc callable trong `failproofai_sdk.propagate()`. Xem [Thread và async](#threads-and-async). - Các trường bổ sung hợp nhất cuối cùng, vì vậy cái nào có tên giống như trường thực như `model` hoặc `outcome` sẽ ghi đè nó và thay đổi một cột được lưu trữ. Không gian tên của bạn; các adapter sử dụng tiền tố `fw_`. + Các trường bổ sung hợp nhất cuối cùng, vì vậy một cái được đặt tên như một trường thực như `model` hoặc `outcome` sẽ ghi đè nó và thay đổi một cột được lưu trữ. Namespace của bạn; các adapter sử dụng một tiền tố `fw_`. - - `agent_id` là một khía cạnh cardinality thấp và bạn để một id chạy vào nó. Sử dụng một vai trò hoặc tên nút và để id thực vào một trường tải trọng. + + `agent_id` là một facet cardinality thấp và bạn đặt một run id vào nó. Sử dụng một role hoặc node name và đặt id thực vào một trường payload. @@ -726,12 +724,12 @@ Giá trị mặc định là đúng trong sản xuất và sai trong khi gỡ l - Cặp, id, vòng đời phiên và giao hàng. + Cặp, id, vòng đời session, và giao hàng. - Theo nhân quả thông qua phiên bạn vừa bắt được. + Theo causality thông qua session bạn vừa chụp. - + LangGraph, CrewAI, LlamaIndex, và Pydantic AI. \ No newline at end of file diff --git a/docs/zh/start/integrations/custom-agents.mdx b/docs/zh/start/integrations/custom-agents.mdx index 796ddd1b..15c8bf83 100644 --- a/docs/zh/start/integrations/custom-agents.mdx +++ b/docs/zh/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- -title: "自定义 agents" -sidebarTitle: "自定义 agents" -description: "为自行编写的 agent 或没有适配器的框架添加埋点。" +title: "自定义 Agent" +sidebarTitle: "自定义 Agent" +description: "为自己编写的 agent 或没有适配器的框架接入 SDK。" icon: "code" --- -适用于自行编写的 agent，或 Failproof AI 尚无适配器的框架。无需额外配置——你只需直接发出事件。 +适用于您自己编写的 agent，或 Failproof AI 尚无适配器的框架。无需任何插桩操作：您只需直接发送事件即可。 -这与四个框架适配器底层调用的 API 完全相同。适配器不过是对它的封装映射表。 +这与四个框架适配器底层调用的 API 完全相同，适配器不过是对其的封装映射。 ## 安装 @@ -15,9 +15,9 @@ icon: "code" pip install failproofai-sdk ``` -无额外依赖。 +无额外依赖，也无任何外部依赖项。 -## 埋点 +## 接入 ```python import failproofai_sdk @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # 一次运行 t.output = search(q) # 一次工具调用 ``` -从上到下读，含义一目了然： +从上到下阅读，含义一目了然： | 包裹在 | 表示 | | --- | --- | | `session()` | 这些事件属于同一次运行 | -| `agent()` | 某个组件正在执行工作——给它一个在列表中能识别的名称 | -| `tool_call()` | 这是一次工具调用，以及它的返回值 | +| `agent()` | 某个组件正在执行工作——给它一个在列表中易于识别的名称 | +| `tool_call()` | 这是一次工具调用，以及它的返回结果 | -每个作用域实际发出的事件： +各作用域实际发送的事件： -| 作用域 | 发出的事件 | 用途 | +| 作用域 | 发送事件 | 用途 | | --- | --- | --- | -| `session()` | 无 | 绑定 session id，将一次运行归组 | -| `agent()` | `agent_start`、`agent_end` | 标记一个工作单元的开始和结束 | -| `tool_call()` | `tool_use`、`tool_result` | 标记一次工具调用并计时 | +| `session()` | 无 | 绑定 session id，将一次运行分组 | +| `agent()` | `agent_start`、`agent_end` | 标记一个工作单元的起止 | +| `tool_call()` | `tool_use`、`tool_result` | 标记一次工具调用的起止并计时 | -内部的所有内容都可以省略 `session_id` 和 `agent_id`。作用域将身份信息绑定在上下文变量上，每次事件调用都会自动读取，无需在函数间手动传递 id。 +内部的所有内容都可以省略 `session_id` 和 `agent_id`。作用域会将身份信息绑定到上下文变量中，每次事件调用都会自动读取，因此无需在函数间手动传递 id。 -三者均支持 `async with` 和普通 `with`。 +三者均支持 `async with` 和 `with`。 -嵌套 agent 会构建树形结构。`parent_id` 和深度由调用栈自动计算： +嵌套 agent 可构建调用树，`parent_id` 和深度会根据调用栈自动计算： ```python with failproofai_sdk.session(): @@ -63,31 +63,31 @@ with failproofai_sdk.session(): `agent()` 会自动处理异常： -| 发生了什么 | 发出的事件 | 结果 | +| 发生情况 | 事件 | 结果 | | --- | --- | --- | | 无异常 | `agent_end` | `success` | | `Exception` | `error`，然后 `agent_end` | `failed` | | `KeyboardInterrupt`、`SystemExit` | `error`，然后 `agent_end` | `failed` | | `CancelledError`、`GeneratorExit` | 仅 `agent_end` | `cancelled` | -error 事件在 `agent_end` 之前发出，因为 dashboard 在收到 `agent_end` 时关闭 span，之后的事件将无法归属。取消不是失败，因此已取消的运行不会污染错误面板。异常始终会被重新抛出——作用域永远不会吞掉异常。 +错误事件在 `agent_end` 之前发出，因为 dashboard 在 `agent_end` 时关闭 span，之后的任何内容都无法归属。取消操作不是失败，因此已取消的运行不会污染错误视图。异常始终会被重新抛出：作用域永远不会吞掉异常。 ## 事件方法 -六个类别，共十五个方法。大多数成对出现——你发出开启事件，再发出关闭事件，SDK 会测量两者之间的时间跨度。 +六个系列，共十五个方法。大多数成对出现——发送开始事件，再发送结束事件，SDK 会自动计算两者之间的时间跨度。 -| 类别 | 开启 | 关闭 | 独立 | +| 系列 | 开始 | 结束 | 独立 | | --- | --- | --- | --- | | **Agents** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | -| **模型** | `model_request` | `model_response` | — | -| **工具** | `tool_use` | `tool_result` | — | +| **Models** | `model_request` | `model_response` | — | +| **Tools** | `tool_use` | `tool_result` | — | | **Hooks** | `hook_triggered` | `hook_completed` | — | -| **人工** | `human_wait` | `human_input` | `human_pause`、`human_interrupt` | -| **失败** | — | — | `error` | +| **Humans** | `human_wait` | `human_input` | `human_pause`、`human_interrupt` | +| **Failures** | — | — | `error` | - 在适用的场景下优先使用作用域——`agent()` 和 `tool_call()`。它们能保证即使函数体抛出异常也会发出关闭事件。只有当控制流无法嵌套时（例如在辅助函数内的模型调用）才直接使用这些方法。 + 在适用的场景下，优先使用作用域——`agent()` 和 `tool_call()`。即使主体代码抛出异常，它们也能保证关闭事件被发出。只有当控制流无法嵌套时（例如辅助函数中的模型调用），才直接使用这些方法。 @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **两组人工事件的方向相反。** + **两组人类事件方向相反。** | 方法 | 含义 | | --- | --- | - | `human_wait` / `human_input` | **agent 向人发起请求**——审批门控、澄清问题 | - | `human_pause` / `human_interrupt` | **人对 agent 采取了操作**——停止按钮、运维暂停 | + | `human_wait` / `human_input` | **agent 询问人员**——审批门控、澄清性问题 | + | `human_pause` / `human_interrupt` | **人员操作 agent**——停止按钮、操作员暂停 | - 没有任何框架会发出第二对事件，因此始终需要你自己发出。 + 没有任何框架会发出第二组事件，因此始终需要您自行发送。 - **并发执行模型调用时请传入 `request_id`。** 若不传，请求和响应将按每个 agent 的到达顺序配对——并发调用会错配，将每个响应关联到错误的请求。 + **当模型调用并发执行时，请传入 `request_id`。** 如果不传，请求和响应将按每个 agent 的到达顺序配对——并发调用会错误配对，将每个响应关联到错误的请求上。 ## 示例 -一个基于 OpenAI API 的工具调用循环，不使用任何 agent 框架： +直接调用 OpenAI API 的工具调用循环，不使用任何 agent 框架： ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """一次模型调用，由事件对包裹。""" + """一次模型调用，由事件对标记起止。""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # 有界循环；无界的 agent 循环本身就是一个 bug + for _ in range(4): # 有界循环；无界 agent 循环本身就是一个 bug message = turn(messages) if not message.tool_calls: break @@ -204,14 +204,14 @@ with failproofai_sdk.session(): }) ``` -这将产生与适配器相同的六种事件类型。包含工具定义的完整可运行版本位于 SDK 仓库的 `docs/manual/examples/` 目录下。 +这会生成与适配器相同的六种事件类型。包含工具定义的完整可运行版本位于 SDK 仓库的 `docs/manual/examples/` 目录下。 ## 线程与异步 -上下文变量会自动传播到 asyncio 任务中，但不会传播到新线程——线程启动时上下文为空。 +上下文变量会自动传播到 asyncio 任务中，但不会传播到新线程，因为线程启动时上下文为空。 ```python -# asyncio：无需任何操作 +# asyncio：无需额外操作 async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) @@ -221,28 +221,28 @@ threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -不使用 `propagate()` 时，worker 的事件会抛出 `TypeError` 并提示修复方法，而不是静默地落到没有 session 的状态。这是有意为之：没有 session 的事件在摄入时会被跳过并返回 `200`，这正是身份层要防止的静默失败。 +不使用 `propagate()` 时，worker 的事件会抛出 `TypeError` 并提示修复方法，而不是落入无 session 的状态。这是有意为之：没有 session 的事件会被摄取层跳过并返回 `200`，而这正是身份层要防止的静默失败。 -## 为没有适配器的框架添加埋点 +## 为没有适配器的框架接入 -每个 agent 框架都提供相同的三个切入点。映射它们即可获得完整的追踪——四个内置适配器也仅此而已。 +每个 agent 框架都提供相同的三个切入点。映射它们即可获得完整的追踪——已提供的四个适配器所做的不过如此。 -| 切入点 | 你需要编写 | 产生的事件 | +| 切入点 | 您编写的内容 | 产生的事件 | | --- | --- | --- | | 运行 | `session()` + `agent()` | `agent_start`、`agent_end` | | 每次工具调用 | `tool_call()` | `tool_use`、`tool_result` | | 每次模型调用 | `model_*` 事件对 | `model_request`、`model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - 在框架的工具包装器或中间件中添加。 + + 在框架中称为工具包装器或中间件的位置。 ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -264,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **有值得观测的节点、步骤或中间件边界？** 用 hook 对——`hook_triggered` / `hook_completed`——来包裹，而不是嵌套的 `agent()`。`agent_id` 是低基数维度，每个节点一个条目会使其失效。Hook span 的渲染方式相同，还能提供每节点的延迟数据。 + **有值得观察的节点、步骤或中间件边界？** 用 hook 对——`hook_triggered` / `hook_completed`——来包裹，而不是嵌套 `agent()`。`agent_id` 是低基数维度，每个节点都创建一个条目会使其不可用。Hook span 的渲染方式相同，且能提供每个节点的延迟数据。 - **手动埋点与自动埋点可以组合使用。** 在手动编写的作用域内运行的适配器会加入该 session 并以该 agent 为父节点，从而形成一棵树而非两棵——当你同时对一个框架手动埋点和使用受支持的框架时非常有用。 + **手动接入与自动接入可以组合使用。** 在手写作用域内运行的适配器会加入该 session 并以该 agent 作为父节点，从而生成一棵统一的树，而不是两棵独立的树——当您将一个框架与已支持的框架混合接入时非常有用。 - 原因有两点，而上述三个切入点正是对这两点的解答： + 原因有两点，上述三个切入点就是解决方案： - `autogen-core` 自 2025 年 9 月起已停止维护。 - - AG2 没有提供等同于其他框架 hook 的全局注册点，因此要对其埋点就意味着在每个构建位置包裹每个 agent。 + - AG2 没有提供等同于其他框架钩子的全局注册点，因此接入它意味着需要在每个构造点包裹每个 agent。 - 手动映射这三个切入点所记录的事件，与内置适配器的保真度完全相同。 + 手动映射切入点可以记录与正式适配器相同的事件，且精度相同。 ## 深入了解 -记录机制的工作原理。入门时无需了解这些内容。 +以下是录制机制的工作原理，入门时无需阅读。 - + -每次记录的结构相同：一个 span 开启，工作嵌套在其中，每个开启事件都有对应的关闭事件。 +每条录制的结构相同：一个 span 开始，工作嵌套其中，每个开始事件都有对应的结束事件。 ```mermaid flowchart LR @@ -300,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -**事件对**是基本单元。每个关闭事件携带 SDK 从对应开启事件起测量的持续时间。 +**事件对**是基本单元。每个结束事件携带 SDK 从对应开始事件起计算的持续时间。 -以下是每个框架各一次真实运行的记录——来自 SDK 附带的示例，模型名称已统一。注意单次调用能带回多少信息。 +以下是每个框架的一次真实运行——来自 SDK 附带的示例，模型名称已规范化。注意单次调用能返回多少信息。 @@ -323,7 +323,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - 节点转换为 hook 对，因此你可以获得每节点的延迟，而不会使 agent 列表过于拥挤。 + 节点转换为 hook 对，因此您可以获取每个节点的延迟数据，而不会让 agent 列表过于拥挤。 @@ -340,7 +340,7 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - 每个 agent 的 `role` 成为其 span 名称，因此延迟和 token 消耗可按角色分解。 + 每个 agent 的 `role` 成为其 span 名称，因此延迟和 token 消耗可按角色细分。 @@ -360,7 +360,7 @@ flowchart LR 26 +7.038s agent_end Agent · success ``` - agent 循环本身是可见的，不仅仅是它的模型调用。 + agent 循环本身清晰可见，而不仅仅是其模型调用。 @@ -375,7 +375,7 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - 无 hook 对：Pydantic AI 没有可供包裹的节点或步骤边界。 + 无 hook 对：Pydantic AI 没有可标记的节点或步骤边界。 @@ -388,36 +388,36 @@ flowchart LR 6 +0.000s agent_end main · success ``` - 这些事件由你自己发出。事件类型相同，保真度相同——代价是需要手动添加调用点。 + 这些事件由您自行发送。事件类型相同，精度相同——代价是需要在调用处手动添加。 - + -**没有 session 结束事件。** session 不是你去关闭的东西——它是一组共享同一 `session_id` 的事件。 +**没有 session 结束事件。** Session 不是需要主动关闭的东西——它是一组共享同一 `session_id` 的事件。 状态由追踪的形态推导： -| 状态 | 时机 | +| 状态 | 条件 | | --- | --- | -| `ongoing` | 至少有一个 span 仍处于打开状态 | -| `paused` | `agent_pause` 没有对应的 `agent_resume` | -| `error` | 没有打开的 span，且至少有一个事件失败 | -| `done` | 没有打开的 span，且没有失败 | +| `ongoing` | 至少有一个 span 仍处于开放状态 | +| `paused` | 存在没有对应 `agent_resume` 的 `agent_pause` | +| `error` | 没有开放的 span，且至少有一个事件失败 | +| `done` | 没有开放的 span，且没有失败 | -因此，当所有事件对都关闭时，session 即结束。适配器会为你发出 `agent_end`，并在拆卸时关闭所有仍打开的 span 并标记为未完成——崩溃的运行会以 `done` 状态结算，留下一个可见的缺口，而不是永久挂起。 +因此，当所有事件对都关闭时，session 就结束了。适配器会为您发出 `agent_end`，在销毁时关闭所有仍处于开放状态的内容并标记为不完整——崩溃的运行会以 `done` 状态结束，并显示一个明显的缺口，而不是永远挂起。 - 这就是为什么一个 session 可以跨两次调用。LangGraph 的 `interrupt()` 会暂停运行，根 span 故意保持打开状态，由后续恢复调用来关闭它。两次调用属于同一个 session。 + 这就是为什么一个 session 可以跨越两次调用。LangGraph `interrupt()` 会暂停运行，根 span 故意保持开放，恢复调用时再将其关闭。两次调用属于同一个 session。 - + -`session_id` 和 `agent_id` 在每个事件方法中都是可选的。省略时，它们从外层作用域解析： +`session_id` 和 `agent_id` 在每个事件方法上都是可选的。省略时，它们从外层作用域解析： ```python with failproofai_sdk.session(): @@ -425,128 +425,128 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -显式传入仍然有效且优先级更高。若既没有绑定作用域也没有传入参数，调用会抛出 `TypeError` 并提示修复方法，而不是发出一个没有 session 的事件（这类事件在摄入时会被跳过并返回 `200`）。 +显式传入时优先生效。如果没有绑定任何值也没有传入，调用会抛出 `TypeError` 并提示修复方法，而不是发出没有 session 的事件（摄取层会跳过该事件并返回 `200`）。 -作用域将身份信息绑定在上下文变量上。这些变量会自动传播到 asyncio 任务中，但不会传播到新线程——需要将 worker 包裹在 `failproofai_sdk.propagate()` 中。 +作用域将身份信息绑定到上下文变量中。这些变量会自动传播到 asyncio 任务，但不会传播到新线程——需要用 `failproofai_sdk.propagate()` 包裹 worker。 -#### 各 id 的生成者 +#### 各 id 的生成方 -| Id | 生成者 | 说明 | +| Id | 生成方 | 说明 | | --- | --- | --- | -| `session_id` | 你，或 SDK | `session("chat-42")` 原样使用；省略时 SDK 生成 `uuid4().hex` | -| `agent_id` | 你，或框架 | 来自 `agent("analyst")`、CrewAI 的 `role`、`FunctionAgent.name`。看起来像 UUID 的值会被拒绝并替换 | -| `tool_call_id`、`hook_id`、`request_id` | 你，或框架 | 适配器复用框架自身的运行 id，因此事件对在线程跳转后仍能正确配对 | -| **事件 id** | **Cloud，在摄入时** | SDK 不发出此值 | -| **`dedup_key`** | **Cloud，在摄入时** | 组织、session、时间戳、类型和载荷的哈希值。这才是真正的身份标识——它让重试的批次折叠而不是重复 | +| `session_id` | 您，或 SDK | `session("chat-42")` 按原样使用；省略时，SDK 生成 `uuid4().hex` | +| `agent_id` | 您，或框架 | 来自 `agent("analyst")`、CrewAI 的 `role`、`FunctionAgent.name`。看起来像 UUID 的值会被拒绝并替换 | +| `tool_call_id`、`hook_id`、`request_id` | 您，或框架 | 适配器复用框架自身的运行 id，这就是为什么事件对能在线程切换后仍能正确配对 | +| **事件 id** | **Cloud，在摄取时** | SDK 不发送 | +| **`dedup_key`** | **Cloud，在摄取时** | 组织、session、时间戳、类型和 payload 的哈希值。这是真正的身份标识——使重试的批次合并而不是重复 | #### 适配器如何解析 `session_id` -按优先级，第一个匹配生效： +先匹配者优先： 1. 显式传入的 `session_id` 选项 2. 每次调用的元数据 -3. 外层的 `session()` 作用域 +3. 外层 `session()` 作用域 4. 框架元数据 5. 框架自身的运行 id -在上述任一来源存在时，绝不会凭空生成——合成的 id 会将一次运行拆分到多个 session 中。 +在上述来源存在时，永远不会凭空生成——合成的 id 会将一次运行拆分为多个 session。 -#### 保持 `agent_id` 的低基数 +#### 保持 `agent_id` 低基数 -它是每个 dashboard 界面的主要维度，对应一个 `LowCardinality(String)` 列。每次运行一个值会降低该列的效能，并使过滤下拉菜单中充斥着每次运行的单独条目。 +它是每个 dashboard 视图的主要维度，也是 `LowCardinality(String)` 列。使用每次运行唯一的值会降低该列的效用，并在筛选下拉框中填满每次运行对应的条目。 -适配器会为你维护这个列： +适配器会为您维护该列： -| 框架传入的值 | 记录为 | 原因 | +| 框架提供的值 | 记录为 | 原因 | | --- | --- | --- | | `3f9a1c2b-…`（UUID） | `main` | 没有可保留的可读内容 | -| 长的纯十六进制字符串 | `main` | 同上 | -| `agent-3f9a1c2b-…` | `agent` | 剥离每次运行的 id，保留可读部分 | +| 较长的纯十六进制字符串 | `main` | 同上 | +| `agent-3f9a1c2b-…` | `agent` | 去除每次运行的 id，保留可读部分 | | `agent-v2` | `agent-v2` | 短片段保持不变 | | `step-3` | `step-3` | 同上 | -真实 id 保存在 `fw_agent_id` / `fw_run_id` 上，在那里仍可查询，但不作为维度。 +真实 id 保存在 `fw_agent_id` / `fw_run_id` 上，在那里仍可查询，但不会作为维度。 - **此保护仅作用于框架自动选择的标签。** 你自己传入的 `agent_id`——无论是传给 `event.*` 还是 `failproofai_sdk.agent(...)`——都会原样记录。静默改写显式参数带来的危害比它所防止的基数问题更大，因此请自行为 span 命名。 + **此保护仅针对框架自动选择的标签。** 您自行传入的 `agent_id`——无论是传给 `event.*` 还是 `failproofai_sdk.agent(...)`——都会原样记录。静默改写显式参数比它所防止的基数问题更糟糕，因此请自行为 span 命名时注意命名规范。 - + | 分组 | 事件 | | --- | --- | | Agents | `agent_start`、`agent_end`、`agent_pause`、`agent_resume` | -| 模型 | `model_request`、`model_response` | -| 工具 | `tool_use`、`tool_result` | +| Models | `model_request`、`model_response` | +| Tools | `tool_use`、`tool_result` | | Hooks | `hook_triggered`、`hook_completed` | -| 人工 | `human_wait`、`human_input`、`human_pause`、`human_interrupt` | -| 失败 | `error` | +| Humans | `human_wait`、`human_input`、`human_pause`、`human_interrupt` | +| Failures | `error` | -基于上述运行数据，各框架记录的事件： +各框架记录的内容（基于上述运行示例）： -| 事件 | LangGraph | CrewAI | LlamaIndex | Pydantic AI | 自定义 | +| 事件 | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | -| Agent 开始和结束 | 是 | 是 | 是 | 是 | 你 | -| 模型请求和响应 | 是 | 是 | 是 | 是 | 你 | -| 工具使用和结果 | 是 | 是 | 是 | 是 | 你 | -| Hook 触发和完成 | 节点 | 任务 | 步骤 | — | 你 | +| Agent 开始和结束 | 是 | 是 | 是 | 是 | 您 | +| 模型请求和响应 | 是 | 是 | 是 | 是 | 您 | +| 工具使用和结果 | 是 | 是 | 是 | 是 | 您 | +| Hook 触发和完成 | 节点 | 任务 | 步骤 | — | 您 | | 错误 | 是 | 是 | 是 | 是 | 自动 | -| 人工等待和输入 | 是 | 是 | 是 | — | 你 | -| Agent 暂停和恢复 | 是 | 是 | 是 | — | 你 | +| 人员等待和输入 | 是 | 是 | 是 | — | 您 | +| Agent 暂停和恢复 | 是 | 是 | 是 | — | 您 | -横线表示该框架没有此概念。`human_pause` 和 `human_interrupt` 描述的是人对 agent 采取操作，没有任何框架会发出这类信号——需要你自己发出。 +破折号表示该框架没有此概念。`human_pause` 和 `human_interrupt` 描述的是*人员*对 agent 的操作，没有任何框架会发出这些事件——需要您自行发送。 -事件从不单独出现。一个开启，一个关闭，关闭事件携带 SDK 从开启事件起测量的持续时间。 +事件从不单独出现。一个开始，一个结束，结束事件携带 SDK 从开始事件起计算的持续时间。 -| 开启 | 关闭 | 关闭事件携带的内容 | +| 开始 | 结束 | 结束事件携带 | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`、`summary` | | `model_request` | `model_response` | token 数、`stop_reason`、延迟 | | `tool_use` | `tool_result` | `output` 或 `error`、持续时间 | | `hook_triggered` | `hook_completed` | `outcome`、持续时间 | -| `agent_pause` | `agent_resume` | 暂停持续时长 | -| `human_wait` | `human_input` | 答复内容及人的响应时长 | +| `agent_pause` | `agent_resume` | 暂停持续时间 | +| `human_wait` | `human_input` | 答案，以及人员响应所用时间 | - 有开启事件但没有对应关闭事件，意味着一个永远不会结束的 span。session 会显示为仍在运行，且活跃时长持续增长。这是手动埋点时需要注意的失败模式。 + 有开始事件但没有结束事件，就是一个永不结束的 span。Session 会一直显示为运行中，其活动时长持续增长。这是手动接入时需要特别注意的失败模式。 #### 关联规则 -- 在匹配的完成事件中复用相同的 `tool_call_id`、`hook_id`、`pause_id` 或 `input_id`。 -- SDK 为 `tool_result`、`hook_completed`、`agent_resume` 和 `human_input` 计算 `duration_ms`。向这些方法传入 `duration_ms` 会抛出 `ValueError`。 -- `duration_ms` **可以**传给 `model_response`，因为只有调用方才知道真实的提供商延迟。它必须是整数——浮点数会在调用处抛出 `ValueError`，因为服务端将该列读取为无符号 32 位整数，其他类型会存储为 NULL。 -- 关联键按类型和 session 作用域，因此工具调用和 hook 可以安全地共享 id，两个并发 session 也可以复用相同的 id 而不冲突。关联键不按 agent 作用域：在一个 agent 下开启、在另一个 agent 下关闭的事件对仍然能正确关联，这在多 agent 框架中是常见情况。 -- `request_id` 将 `model_request` 与 `model_response` 配对。若不传，模型事件按每个 agent 的顺序配对，并发调用会错配。 -- 跨进程拆分的事件对在下游仍能关联，但 SDK 无法计算其进程内持续时间。 -- 待匹配映射最多保存 10,000 个开启事件，满后会驱逐最旧的条目。 +- 在对应的完成事件中复用相同的 `tool_call_id`、`hook_id`、`pause_id` 或 `input_id`。 +- SDK 会自动计算 `tool_result`、`hook_completed`、`agent_resume` 和 `human_input` 的 `duration_ms`。向这些方法传入该参数会抛出 `ValueError`。 +- `duration_ms` **可以**传给 `model_response`，因为只有调用方才知道真实的提供商延迟。必须为整数——浮点数会在调用处抛出 `ValueError`，因为服务器将该列读取为无符号 32 位整数，其他类型会存储 NULL。 +- 关联键按类型和 session 限定范围，因此工具调用和 hook 可以安全地共用同一个 id，两个并发 session 也可以复用相同的 id 而不冲突。关联键不按 agent 限定范围：在一个 agent 下开始、在另一个 agent 下关闭的事件对仍能正确关联，这在多 agent 框架中是常见情况。 +- `request_id` 用于配对 `model_request` 和 `model_response`。不传时，模型事件按每个 agent 的顺序配对，并发调用会导致错误配对。 +- 跨进程的事件对在下游仍能关联，但 SDK 无法计算其进程内持续时间。 +- 待处理映射最多保存 10,000 个开始事件，满时驱逐最旧的条目。 - + -安装 `failproofai-sdk` 会安装全部内容，包含四个适配器。extras 拉取的是**框架**，而不是适配器。 +安装 `failproofai-sdk` 会安装所有内容，包含全部四个适配器。extras 安装的是**框架**本身，而不是适配器。 ```python import failproofai_sdk # 不加载标准库以外的任何内容 -failproofai_sdk.instrument() # 仅导入你实际需要的适配器 +failproofai_sdk.instrument() # 仅导入您实际需要的适配器 ``` -`import failproofai_sdk` 承诺零依赖，通过以下测试强制保证：一个在不带 `--no-deps` 的情况下安装构建 wheel 的测试，以及另一个证明没有框架进入 `sys.modules` 的测试。 +`import failproofai_sdk` 在契约上是零依赖的，通过两个测试强制保证：一个测试使用 `--no-deps` 安装构建好的 wheel，另一个测试确认没有任何框架出现在 `sys.modules` 中。 - 不存在 `failproofai_sdk.crewai` 属性。适配器故意不在顶层包上暴露：访问它会作为属性访问的副作用导入框架，破坏零依赖承诺。请使用 `instrument()`。 + 不存在 `failproofai_sdk.crewai` 属性。适配器有意不暴露在顶层包上：访问它会作为属性访问的副作用导入框架，破坏零依赖承诺。请使用 `instrument()`。 ```python failproofai_sdk.instrument() # 所有已导入的框架 -failproofai_sdk.instrument("crewai") # 按名称指定单个框架 +failproofai_sdk.instrument("crewai") # 指定一个，按名称 failproofai_sdk.uninstrument("crewai") # 还原 ``` @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # 还原 | `llama_index` | `llamaindex`、`llama-index` | | `pydantic_ai` | `pydantic-ai`、`pydanticai` | -自动检测读取 `sys.modules` 而不是已安装的包列表，因此已安装但从未导入的框架不会被埋点，也不会被代为导入。查看已连接的内容： +自动检测读取 `sys.modules`，而不是已安装的包列表，因此已安装但从未导入的框架不会被接入，也不会被代为导入。要查看当前已接入的内容： ```python from failproofai_sdk.integrations import active, available @@ -567,20 +567,20 @@ active() # ('langchain',) ``` - **在没有安装 CrewAI 的机器上调用 `instrument("crewai")` 不会抛出异常。** 它会记录一条警告并返回 `()`，因此一个缺失的框架不会拖垮同时埋点其他框架的进程。 + **在未安装 CrewAI 的机器上调用 `instrument("crewai")` 不会抛出异常。** 它会记录一条警告并返回 `()`，因此缺少一个框架不会导致同时接入其他框架的进程崩溃。 - 警告中包含底层的 `ImportError`，该消息会指出确切的安装命令——修复方法在你的日志里，不会被隐藏。 + 警告中包含底层的 `ImportError`，该消息会给出准确的安装命令——修复方法就在您的日志中，不会被隐藏。 ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - 设置 `FAILPROOFAI_SDK_STRICT=1` 可改为抛出异常。该标志**只读取一次并缓存**，因此请在进程启动前导出它，而不是在运行途中设置。 + 设置 `FAILPROOFAI_SDK_STRICT=1` 可改为抛出异常。该标志**只读取一次并缓存**，因此请在进程启动前导出，而不是在运行中途设置。 - **`instrument()` 必须在框架导入**之后**调用。** 自动检测读取 `sys.modules`，因此在导入之前的裸调用什么都找不到，不会安装任何内容，并返回 `()`。 + **`instrument()` 必须在框架导入*之后*调用。** 自动检测读取 `sys.modules`，因此在导入之前裸调用什么也找不到，不会安装任何内容，并返回 `()`。 @@ -588,7 +588,7 @@ active() # ('langchain',) import failproofai_sdk failproofai_sdk.instrument() # sys.modules 中还没有 langchain -> () -import langchain # 太晚了，什么都没被连接 +import langchain # 太晚了，什么都没有接入 ``` ```python Right @@ -606,7 +606,7 @@ failproofai_sdk.instrument("langchain") ``` -如果出错，进程会在 SDK 已导入、适配器看似已安装的情况下运行，但**不会发出任何事件**。它会记录一条明确说明此情况的警告——因此当某次运行没有记录任何内容时，请先检查日志。 +操作有误时，进程会在 SDK 已导入、适配器看似已安装的情况下运行，但**一个事件都不会发出**。SDK 会记录一条明确说明此情况的警告——当运行没有记录任何内容时，请先检查日志。 @@ -614,7 +614,7 @@ failproofai_sdk.instrument("langchain") ```mermaid flowchart LR - A["你的 agent"] --> B["适配器"] + A["您的 agent"] --> B["适配器"] B --> C["Writer
内存队列"] C -->|"每 0.5 秒"| D["Spool
磁盘上的 JSONL"] D --> E["Failproof 守护进程"] @@ -623,76 +623,74 @@ flowchart LR | 阶段 | 职责 | 运行位置 | | --- | --- | --- | -| 适配器 | 将框架回调转换为 15 种事件类型之一 | 你的进程 | -| Writer | 排队、批处理、原子写入 JSONL | 你的进程，后台线程 | -| Spool | 持久交接，在你的进程退出后仍然存在 | 本地磁盘 | -| 守护进程 | 监视 spool，发送批次，删除已发送内容 | 你的机器 | -| 摄入 | 分配行 id 和去重键，提升可查询列 | Cloud | +| 适配器 | 将框架回调转换为 15 种事件类型之一 | 您的进程 | +| Writer | 队列、批处理、原子写入 JSONL | 您的进程，后台线程 | +| Spool | 持久化交接，进程退出后仍存在 | 本地磁盘 | +| 守护进程 | 监视 spool，发送批次，删除已发送内容 | 您的机器 | +| Ingest | 分配行 id 和去重键，提升可查询列 | Cloud | -spool 是确保安全的关键：你的 agent 永远不会因网络而阻塞，Cloud 故障只会导致目录增大，而不是事件丢失。 +Spool 是安全保障：您的 agent 永远不会因网络而阻塞，Cloud 故障只会导致目录增大，而不是事件丢失。 -每次刷新写入一个批次文件，先写 `.tmp`，然后 `fsync`，再原子重命名： +每次刷新写入一个批次文件，先写 `.tmp`，然后 `fsync`，最后原子重命名： ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -守护进程只处理 `.jsonl` 文件，因此永远不会读到写入一半的文件。文件名包含时间戳、进程 id 和序列号，因此两个进程在同一毫秒内刷新也不会冲突。队列最多容纳 10,000 个事件，超出后会丢弃最旧的并记录日志。 +守护进程只读取 `.jsonl`，因此永远不会读到写了一半的文件。文件名包含时间戳、进程 id 和序列号，因此两个进程在同一毫秒内刷新也不会冲突。队列上限为 10,000 个事件；超过后会丢弃最旧的事件并记录日志。 - **`collector.redact` 不适用于你的 SDK 事件。** 它根本看不到这些事件。 + **`collector.redact` 对 SDK 事件也默认为 `minimal`。** SDK 在将批次写入磁盘前进行脱敏，守护进程在上传前对相同内容执行同样的确定性处理，以确保来自旧版 SDK 的批次也受到保护。 -守护进程**发送**你的批次。它不打开也不重写这些批次。 +守护进程在内存中对每个批次进行脱敏后再上传，不会重写已读取的 spool 文件。 -| 事件 | 写入者 | 是否受 `collector.redact` 处理 | +| 事件 | 由谁写入 | minimal 脱敏在何处执行 | | --- | --- | --- | -| CLI 会话记录 | 守护进程 | 是 | -| Hook 活动 | 守护进程 | 是 | -| **SDK 发出的所有事件** | **你的进程** | **否** | +| CLI 会话记录 | 守护进程 | 守护进程写入批次之前 | +| Hook 活动 | 守护进程 | 守护进程写入批次之前 | +| **SDK 发出的所有内容** | **您的进程** | **SDK 写入批次之前，以及守护进程上传之前** | -脱敏在守护进程**写入**自身事件的地方运行——而不是在批次**发送**的地方。因此，包含 API 密钥的 prompt 或工具参数在到达时仍然包含该密钥。 - -这是有意为之。这些是你自己的埋点调用，在传输过程中改写它们意味着你收到的事件与你发出的不一致。 +仅当明确要求原始 payload 时才将 `collector.redact` 设为 `off`；SDK 和守护进程都遵循该设置。minimal 脱敏可识别常见的 API 密钥、bearer token、JWT 和密钥赋值，但无法识别任意敏感文本。 - **你在源头控制载荷，有两种方式：** + **您可以在源头控制 payload，有两种方式：** - - 在适配器上关闭内容捕获。**选项名称各不相同，且有一个适配器没有此选项**——这不是一个统一的开关： - - LangChain / LangGraph、Pydantic AI——`capture_content=False` - - LlamaIndex——`capture_messages=False` - - CrewAI——**完全没有内容开关**；它只读取 `session_id` 选项，因此 prompt 和补全内容始终会被记录。 + - 在适配器上关闭内容捕获。**选项名称各不相同，且有一个适配器没有此选项**——这不是一个通用开关： + - LangChain / LangGraph、Pydantic AI — `capture_content=False` + - LlamaIndex — `capture_messages=False` + - CrewAI — **完全没有内容开关**；它只读取 `session_id` 选项，因此提示词和补全内容始终会被记录。 - `instrument()` 会丢弃适配器不读取的选项，因此传入错误的名称不会报错，也不会有任何效果。 - - 一开始就不要将敏感信息传给 `input=`。 + `instrument()` 会忽略适配器不支持的选项，因此传入错误的名称不会报错，也不会有任何效果。 + - 一开始就不要将密钥传给 `input=`。 - `collector.redact` 不能替代上述两种方式。 + `collector.redact` 是纵深防御，而不是上述两者的替代方案。 - **spool 目录为空才是健康状态。** 不要用它来检查事件是否已送达。 + **spool 目录为空是正常状态。** 不要用它来确认投递情况。 -守护进程在发送批次后的毫秒内就会将其删除，因此 `ls` 命令会与收集器产生竞争，只能看到你实际发出内容的一小部分——与 SDK 什么都没记录的情况无法区分。 +守护进程在发送后的毫秒内删除每个批次文件，因此 `ls` 会与收集器竞争，只能看到您发送内容的一小部分——与 SDK 什么都没记录的情况无法区分。 -要确认事件已成功落地，请检查 dashboard。要观察 spool 的填充过程，请先停止守护进程。 +要确认事件是否真正送达，请查看 dashboard。要观察 spool 填充过程，请先停止守护进程。 - + -每个回调都运行在一个包装器内，其唯一职责是重新抛出异常，因此你的调用恰好位于一个 `try` 中，SDK 的所有操作都在其外部进行。 +每个回调都运行在一个包装器内，该包装器的唯一职责是重新抛出异常，因此您的调用恰好位于一个 `try` 中，SDK 所做的一切都在其外部。 -| 发生了什么 | 结果 | +| 发生情况 | 结果 | | --- | --- | -| 一个 hook 抛出异常 | 记录一次带有堆栈跟踪的日志。你的调用不受影响 | -| 同一个 hook 抛出三次异常 | 该 hook 在进程剩余生命周期内被禁用，记录一行错误 | -| 设置了 `FAILPROOFAI_SDK_STRICT=1` | 异常被重新抛出 | -| 框架版本不在测试范围内 | 发出一次警告，仍然进行埋点 | -| 单个功能缺失 | 仅禁用该 hook，不影响整个适配器 | +| 某个 hook 抛出异常 | 记录一次并附带 traceback，您的调用不受影响 | +| 同一个 hook 抛出三次 | 该 hook 在进程剩余时间内被禁用，并记录一行错误 | +| 设置了 `FAILPROOFAI_SDK_STRICT=1` | 异常会被重新抛出 | +| 框架版本超出测试范围 | 警告一次，但仍继续接入 | +| 某个功能缺失 | 仅禁用该 hook，不影响整个适配器 | -默认行为在生产环境中是正确的，在调试时是错误的，因为它只能证明"没有崩溃"。设置 `FAILPROOFAI_SDK_STRICT=1` 可让被吞掉的失败变得明显。 +默认行为在生产环境中是正确的，但在调试时是错误的，因为它只能证明"没有崩溃"。设置 `FAILPROOFAI_SDK_STRICT=1` 可让被吞掉的失败变得明显。 @@ -701,24 +699,24 @@ spool 是确保安全的关键：你的 agent 永远不会因网络而阻塞，C ## 常见问题 - - 某个开启事件没有对应的关闭事件：`model_request` 没有 `model_response`，或 `tool_use` 没有 `tool_result`。请使用作用域，它们能保证即使函数体抛出异常也会发出事件对。如果直接调用事件方法，请使用 `try` 和 `finally`。 + + 开始事件没有对应的结束事件：`model_request` 没有 `model_response`，或 `tool_use` 没有 `tool_result`。请使用作用域，即使主体代码抛出异常也能保证事件对完整。如果直接调用事件方法，请使用 `try` 和 `finally`。 - 持续时间由对应的开启事件测量，因此在 `tool_result`、`hook_completed`、`agent_resume` 和 `human_input` 上传入 `duration_ms` 会被拒绝。在 `model_response` 上可以接受，因为只有你知道真实的提供商延迟，且必须是整数。 + 持续时间由对应的开始事件起计算，因此在 `tool_result`、`hook_completed`、`agent_resume` 和 `human_input` 上传入该参数会被拒绝。在 `model_response` 上可以接受，因为只有您才知道真实的提供商延迟，且必须为整数。 - - 该线程从未继承上下文。请将可调用对象包裹在 `failproofai_sdk.propagate()` 中。参见[线程与异步](#threads-and-async)。 + + 该线程从未继承上下文。请用 `failproofai_sdk.propagate()` 包裹可调用对象。参见[线程与异步](#threads-and-async)。 - - 额外字段最后合并，因此与真实字段（如 `model` 或 `outcome`）同名的字段会覆盖它，改变存储的列值。请为你的字段加命名空间前缀；适配器使用 `fw_` 前缀。 + + 额外字段最后合并，因此与真实字段（如 `model` 或 `outcome`）同名的字段会覆盖它并改变存储列。请为您的字段加上命名空间；适配器使用 `fw_` 前缀。 - - `agent_id` 是低基数维度，而你在其中放入了运行 id。请使用角色或节点名称，将真实 id 放入载荷字段。 + + `agent_id` 是低基数维度，而您将运行 id 放入了其中。请使用角色或节点名称，将真实 id 放在 payload 字段中。 @@ -726,10 +724,10 @@ spool 是确保安全的关键：你的 agent 永远不会因网络而阻塞，C - 事件对、id、session 生命周期与事件投递。 + 事件对、id、session 生命周期与投递机制。 - - 在刚捕获的 session 中沿因果链路追溯。 + + 在刚捕获的 session 中跟踪因果关系。 LangGraph、CrewAI、LlamaIndex 和 Pydantic AI。 From 8885fe6aa1f7c9c2304db02e76fdc8ce77ff599b Mon Sep 17 00:00:00 2001 From: "failproofai-canary[bot]" Date: Mon, 14 Sep 2026 20:48:11 +0000 Subject: [PATCH 2/8] docs: update translations for changed English sources --- docs/ar/admin/keys-and-permissions.mdx | 48 +- docs/ar/evaluations/deploy.mdx | 55 ++ docs/ar/evaluations/overview.mdx | 44 ++ docs/ar/evaluations/test.mdx | 29 ++ docs/ar/evaluations/write.mdx | 76 +++ docs/ar/policies/deploy.mdx | 87 +++- docs/ar/policies/editor.mdx | 103 +++- docs/ar/policies/failure-behavior.mdx | 54 +- docs/ar/policies/local-configuration.mdx | 92 ++-- docs/ar/policies/overview.mdx | 79 ++- docs/ar/policies/packs.mdx | 115 ++-- docs/ar/policies/publish-a-pack.mdx | 107 ++-- docs/ar/policies/rollback.mdx | 72 ++- docs/ar/policies/test.mdx | 60 +++ docs/ar/reference/cloud-cli.mdx | 376 ++++++------- docs/ar/reference/custom-agents.mdx | 154 +++--- docs/ar/reference/evaluator-sdk.mdx | 252 ++++----- docs/ar/reference/failproof-cli.mdx | 182 ++++--- docs/ar/reference/harnesses.mdx | 112 ++-- docs/ar/reference/overview.mdx | 59 ++- docs/ar/reference/policy-sdk.mdx | 142 ++--- docs/ar/sessions/evaluations.mdx | 52 +- docs/ar/start/integrations/custom-agents.mdx | 371 ++++++------- docs/ar/start/quickstart.mdx | 61 ++- docs/ar/start/setup.mdx | 71 ++- docs/de/admin/keys-and-permissions.mdx | 28 +- docs/de/evaluations/deploy.mdx | 55 ++ docs/de/evaluations/overview.mdx | 44 ++ docs/de/evaluations/test.mdx | 29 ++ docs/de/evaluations/write.mdx | 76 +++ docs/de/policies/deploy.mdx | 87 +++- docs/de/policies/editor.mdx | 101 +++- docs/de/policies/failure-behavior.mdx | 46 +- docs/de/policies/local-configuration.mdx | 92 ++-- docs/de/policies/overview.mdx | 77 ++- docs/de/policies/packs.mdx | 121 +++-- docs/de/policies/publish-a-pack.mdx | 105 ++-- docs/de/policies/rollback.mdx | 68 ++- docs/de/policies/test.mdx | 60 +++ docs/de/reference/cloud-cli.mdx | 202 +++---- docs/de/reference/custom-agents.mdx | 102 ++-- docs/de/reference/evaluator-sdk.mdx | 252 ++++----- docs/de/reference/failproof-cli.mdx | 130 +++-- docs/de/reference/harnesses.mdx | 84 +-- docs/de/reference/overview.mdx | 47 +- docs/de/reference/policy-sdk.mdx | 108 ++-- docs/de/sessions/evaluations.mdx | 54 +- docs/de/start/integrations/custom-agents.mdx | 276 +++++----- docs/de/start/quickstart.mdx | 57 +- docs/de/start/setup.mdx | 69 ++- docs/docs.json | 70 +++ docs/es/admin/keys-and-permissions.mdx | 30 +- docs/es/evaluations/deploy.mdx | 55 ++ docs/es/evaluations/overview.mdx | 44 ++ docs/es/evaluations/test.mdx | 29 ++ docs/es/evaluations/write.mdx | 76 +++ docs/es/policies/deploy.mdx | 87 +++- docs/es/policies/editor.mdx | 101 +++- docs/es/policies/failure-behavior.mdx | 44 +- docs/es/policies/local-configuration.mdx | 84 +-- docs/es/policies/overview.mdx | 75 ++- docs/es/policies/packs.mdx | 113 ++-- docs/es/policies/publish-a-pack.mdx | 103 ++-- docs/es/policies/rollback.mdx | 60 ++- docs/es/policies/test.mdx | 60 +++ docs/es/reference/cloud-cli.mdx | 202 +++---- docs/es/reference/custom-agents.mdx | 92 ++-- docs/es/reference/evaluator-sdk.mdx | 254 ++++----- docs/es/reference/failproof-cli.mdx | 188 ++++--- docs/es/reference/harnesses.mdx | 90 ++-- docs/es/reference/overview.mdx | 49 +- docs/es/reference/policy-sdk.mdx | 116 ++--- docs/es/sessions/evaluations.mdx | 54 +- docs/es/start/integrations/custom-agents.mdx | 242 ++++----- docs/es/start/quickstart.mdx | 65 ++- docs/es/start/setup.mdx | 71 ++- docs/fr/admin/keys-and-permissions.mdx | 26 +- docs/fr/evaluations/deploy.mdx | 55 ++ docs/fr/evaluations/overview.mdx | 44 ++ docs/fr/evaluations/test.mdx | 29 ++ docs/fr/evaluations/write.mdx | 76 +++ docs/fr/policies/deploy.mdx | 87 +++- docs/fr/policies/editor.mdx | 101 +++- docs/fr/policies/failure-behavior.mdx | 40 +- docs/fr/policies/local-configuration.mdx | 82 +-- docs/fr/policies/overview.mdx | 79 ++- docs/fr/policies/packs.mdx | 109 ++-- docs/fr/policies/publish-a-pack.mdx | 103 ++-- docs/fr/policies/rollback.mdx | 68 ++- docs/fr/policies/test.mdx | 60 +++ docs/fr/reference/cloud-cli.mdx | 174 +++---- docs/fr/reference/custom-agents.mdx | 106 ++-- docs/fr/reference/evaluator-sdk.mdx | 252 ++++----- docs/fr/reference/failproof-cli.mdx | 152 +++--- docs/fr/reference/harnesses.mdx | 68 +-- docs/fr/reference/overview.mdx | 45 +- docs/fr/reference/policy-sdk.mdx | 104 ++-- docs/fr/sessions/evaluations.mdx | 56 +- docs/fr/start/integrations/custom-agents.mdx | 250 ++++----- docs/fr/start/quickstart.mdx | 53 +- docs/fr/start/setup.mdx | 65 ++- docs/he/admin/keys-and-permissions.mdx | 66 +-- docs/he/evaluations/deploy.mdx | 55 ++ docs/he/evaluations/overview.mdx | 44 ++ docs/he/evaluations/test.mdx | 29 ++ docs/he/evaluations/write.mdx | 76 +++ docs/he/policies/deploy.mdx | 87 +++- docs/he/policies/editor.mdx | 103 +++- docs/he/policies/failure-behavior.mdx | 56 +- docs/he/policies/local-configuration.mdx | 96 ++-- docs/he/policies/overview.mdx | 77 ++- docs/he/policies/packs.mdx | 119 +++-- docs/he/policies/publish-a-pack.mdx | 111 ++-- docs/he/policies/rollback.mdx | 66 ++- docs/he/policies/test.mdx | 60 +++ docs/he/reference/cloud-cli.mdx | 404 +++++++------- docs/he/reference/custom-agents.mdx | 132 ++--- docs/he/reference/evaluator-sdk.mdx | 260 ++++----- docs/he/reference/failproof-cli.mdx | 158 +++--- docs/he/reference/harnesses.mdx | 106 ++-- docs/he/reference/overview.mdx | 69 +-- docs/he/reference/policy-sdk.mdx | 156 +++--- docs/he/sessions/evaluations.mdx | 54 +- docs/he/start/integrations/custom-agents.mdx | 416 +++++++-------- docs/he/start/quickstart.mdx | 65 ++- docs/he/start/setup.mdx | 83 +-- docs/hi/admin/keys-and-permissions.mdx | 44 +- docs/hi/evaluations/deploy.mdx | 55 ++ docs/hi/evaluations/overview.mdx | 44 ++ docs/hi/evaluations/test.mdx | 29 ++ docs/hi/evaluations/write.mdx | 76 +++ docs/hi/policies/deploy.mdx | 85 ++- docs/hi/policies/editor.mdx | 103 +++- docs/hi/policies/failure-behavior.mdx | 52 +- docs/hi/policies/local-configuration.mdx | 92 ++-- docs/hi/policies/overview.mdx | 81 ++- docs/hi/policies/packs.mdx | 127 ++--- docs/hi/policies/publish-a-pack.mdx | 105 ++-- docs/hi/policies/rollback.mdx | 68 ++- docs/hi/policies/test.mdx | 60 +++ docs/hi/reference/cloud-cli.mdx | 492 +++++++++--------- docs/hi/reference/custom-agents.mdx | 150 +++--- docs/hi/reference/evaluator-sdk.mdx | 260 ++++----- docs/hi/reference/failproof-cli.mdx | 164 +++--- docs/hi/reference/harnesses.mdx | 100 ++-- docs/hi/reference/overview.mdx | 65 +-- docs/hi/reference/policy-sdk.mdx | 210 ++++---- docs/hi/sessions/evaluations.mdx | 54 +- docs/hi/start/integrations/custom-agents.mdx | 450 ++++++++-------- docs/hi/start/quickstart.mdx | 63 ++- docs/hi/start/setup.mdx | 83 +-- docs/i18n/README.ar.md | 112 ++-- docs/i18n/README.de.md | 73 +-- docs/i18n/README.es.md | 76 +-- docs/i18n/README.fr.md | 63 +-- docs/i18n/README.he.md | 103 ++-- docs/i18n/README.hi.md | 143 +++-- docs/i18n/README.it.md | 80 +-- docs/i18n/README.ja.md | 71 +-- docs/i18n/README.ko.md | 96 ++-- docs/i18n/README.pt-br.md | 93 ++-- docs/i18n/README.ru.md | 98 ++-- docs/i18n/README.tr.md | 113 ++-- docs/i18n/README.vi.md | 88 ++-- docs/i18n/README.zh.md | 93 ++-- docs/it/admin/keys-and-permissions.mdx | 68 +-- docs/it/evaluations/deploy.mdx | 55 ++ docs/it/evaluations/overview.mdx | 44 ++ docs/it/evaluations/test.mdx | 29 ++ docs/it/evaluations/write.mdx | 76 +++ docs/it/policies/deploy.mdx | 87 +++- docs/it/policies/editor.mdx | 101 +++- docs/it/policies/failure-behavior.mdx | 46 +- docs/it/policies/local-configuration.mdx | 82 +-- docs/it/policies/overview.mdx | 79 ++- docs/it/policies/packs.mdx | 119 +++-- docs/it/policies/publish-a-pack.mdx | 107 ++-- docs/it/policies/rollback.mdx | 64 ++- docs/it/policies/test.mdx | 60 +++ docs/it/reference/cloud-cli.mdx | 222 ++++---- docs/it/reference/custom-agents.mdx | 114 ++-- docs/it/reference/evaluator-sdk.mdx | 252 ++++----- docs/it/reference/failproof-cli.mdx | 152 +++--- docs/it/reference/harnesses.mdx | 108 ++-- docs/it/reference/overview.mdx | 53 +- docs/it/reference/policy-sdk.mdx | 154 +++--- docs/it/sessions/evaluations.mdx | 54 +- docs/it/start/integrations/custom-agents.mdx | 326 ++++++------ docs/it/start/quickstart.mdx | 61 ++- docs/it/start/setup.mdx | 71 ++- docs/ja/admin/keys-and-permissions.mdx | 58 +-- docs/ja/evaluations/deploy.mdx | 55 ++ docs/ja/evaluations/overview.mdx | 44 ++ docs/ja/evaluations/test.mdx | 29 ++ docs/ja/evaluations/write.mdx | 76 +++ docs/ja/policies/deploy.mdx | 85 ++- docs/ja/policies/editor.mdx | 103 +++- docs/ja/policies/failure-behavior.mdx | 48 +- docs/ja/policies/local-configuration.mdx | 88 ++-- docs/ja/policies/overview.mdx | 79 ++- docs/ja/policies/packs.mdx | 119 +++-- docs/ja/policies/publish-a-pack.mdx | 113 ++-- docs/ja/policies/rollback.mdx | 68 ++- docs/ja/policies/test.mdx | 60 +++ docs/ja/reference/cloud-cli.mdx | 378 +++++++------- docs/ja/reference/custom-agents.mdx | 124 ++--- docs/ja/reference/evaluator-sdk.mdx | 252 ++++----- docs/ja/reference/failproof-cli.mdx | 128 +++-- docs/ja/reference/harnesses.mdx | 98 ++-- docs/ja/reference/overview.mdx | 55 +- docs/ja/reference/policy-sdk.mdx | 144 ++--- docs/ja/sessions/evaluations.mdx | 54 +- docs/ja/start/integrations/custom-agents.mdx | 374 ++++++------- docs/ja/start/quickstart.mdx | 61 ++- docs/ja/start/setup.mdx | 77 ++- docs/ko/admin/keys-and-permissions.mdx | 26 +- docs/ko/evaluations/deploy.mdx | 55 ++ docs/ko/evaluations/overview.mdx | 44 ++ docs/ko/evaluations/test.mdx | 29 ++ docs/ko/evaluations/write.mdx | 76 +++ docs/ko/policies/deploy.mdx | 87 +++- docs/ko/policies/editor.mdx | 103 +++- docs/ko/policies/failure-behavior.mdx | 42 +- docs/ko/policies/local-configuration.mdx | 82 +-- docs/ko/policies/overview.mdx | 85 ++- docs/ko/policies/packs.mdx | 117 +++-- docs/ko/policies/publish-a-pack.mdx | 109 ++-- docs/ko/policies/rollback.mdx | 70 ++- docs/ko/policies/test.mdx | 60 +++ docs/ko/reference/cloud-cli.mdx | 226 ++++---- docs/ko/reference/custom-agents.mdx | 114 ++-- docs/ko/reference/evaluator-sdk.mdx | 252 ++++----- docs/ko/reference/failproof-cli.mdx | 136 ++--- docs/ko/reference/harnesses.mdx | 96 ++-- docs/ko/reference/overview.mdx | 47 +- docs/ko/reference/policy-sdk.mdx | 138 ++--- docs/ko/sessions/evaluations.mdx | 54 +- docs/ko/start/integrations/custom-agents.mdx | 344 ++++++------ docs/ko/start/quickstart.mdx | 59 ++- docs/ko/start/setup.mdx | 73 ++- docs/pt-br/admin/keys-and-permissions.mdx | 30 +- docs/pt-br/evaluations/deploy.mdx | 55 ++ docs/pt-br/evaluations/overview.mdx | 44 ++ docs/pt-br/evaluations/test.mdx | 29 ++ docs/pt-br/evaluations/write.mdx | 76 +++ docs/pt-br/policies/deploy.mdx | 87 +++- docs/pt-br/policies/editor.mdx | 101 +++- docs/pt-br/policies/failure-behavior.mdx | 32 +- docs/pt-br/policies/local-configuration.mdx | 92 ++-- docs/pt-br/policies/overview.mdx | 75 ++- docs/pt-br/policies/packs.mdx | 111 ++-- docs/pt-br/policies/publish-a-pack.mdx | 105 ++-- docs/pt-br/policies/rollback.mdx | 64 ++- docs/pt-br/policies/test.mdx | 60 +++ docs/pt-br/reference/cloud-cli.mdx | 353 ++++++------- docs/pt-br/reference/custom-agents.mdx | 100 ++-- docs/pt-br/reference/evaluator-sdk.mdx | 252 ++++----- docs/pt-br/reference/failproof-cli.mdx | 168 +++--- docs/pt-br/reference/harnesses.mdx | 64 +-- docs/pt-br/reference/overview.mdx | 41 +- docs/pt-br/reference/policy-sdk.mdx | 102 ++-- docs/pt-br/sessions/evaluations.mdx | 54 +- .../start/integrations/custom-agents.mdx | 228 ++++---- docs/pt-br/start/quickstart.mdx | 59 ++- docs/pt-br/start/setup.mdx | 55 +- docs/ru/admin/keys-and-permissions.mdx | 38 +- docs/ru/evaluations/deploy.mdx | 55 ++ docs/ru/evaluations/overview.mdx | 44 ++ docs/ru/evaluations/test.mdx | 29 ++ docs/ru/evaluations/write.mdx | 76 +++ docs/ru/policies/deploy.mdx | 85 ++- docs/ru/policies/editor.mdx | 103 +++- docs/ru/policies/failure-behavior.mdx | 52 +- docs/ru/policies/local-configuration.mdx | 86 +-- docs/ru/policies/overview.mdx | 81 ++- docs/ru/policies/packs.mdx | 115 ++-- docs/ru/policies/publish-a-pack.mdx | 113 ++-- docs/ru/policies/rollback.mdx | 70 ++- docs/ru/policies/test.mdx | 60 +++ docs/ru/reference/cloud-cli.mdx | 312 +++++------ docs/ru/reference/custom-agents.mdx | 114 ++-- docs/ru/reference/evaluator-sdk.mdx | 252 ++++----- docs/ru/reference/failproof-cli.mdx | 160 +++--- docs/ru/reference/harnesses.mdx | 98 ++-- docs/ru/reference/overview.mdx | 75 +-- docs/ru/reference/policy-sdk.mdx | 140 ++--- docs/ru/sessions/evaluations.mdx | 54 +- docs/ru/start/integrations/custom-agents.mdx | 404 +++++++------- docs/ru/start/quickstart.mdx | 63 ++- docs/ru/start/setup.mdx | 77 ++- docs/tr/admin/keys-and-permissions.mdx | 68 +-- docs/tr/evaluations/deploy.mdx | 55 ++ docs/tr/evaluations/overview.mdx | 44 ++ docs/tr/evaluations/test.mdx | 29 ++ docs/tr/evaluations/write.mdx | 76 +++ docs/tr/policies/deploy.mdx | 83 ++- docs/tr/policies/editor.mdx | 101 +++- docs/tr/policies/failure-behavior.mdx | 52 +- docs/tr/policies/local-configuration.mdx | 88 ++-- docs/tr/policies/overview.mdx | 85 ++- docs/tr/policies/packs.mdx | 111 ++-- docs/tr/policies/publish-a-pack.mdx | 111 ++-- docs/tr/policies/rollback.mdx | 70 ++- docs/tr/policies/test.mdx | 60 +++ docs/tr/reference/cloud-cli.mdx | 260 ++++----- docs/tr/reference/custom-agents.mdx | 124 ++--- docs/tr/reference/evaluator-sdk.mdx | 252 ++++----- docs/tr/reference/failproof-cli.mdx | 188 ++++--- docs/tr/reference/harnesses.mdx | 104 ++-- docs/tr/reference/overview.mdx | 55 +- docs/tr/reference/policy-sdk.mdx | 146 +++--- docs/tr/sessions/evaluations.mdx | 54 +- docs/tr/start/integrations/custom-agents.mdx | 408 +++++++-------- docs/tr/start/quickstart.mdx | 63 ++- docs/tr/start/setup.mdx | 69 ++- docs/vi/admin/keys-and-permissions.mdx | 40 +- docs/vi/evaluations/deploy.mdx | 55 ++ docs/vi/evaluations/overview.mdx | 44 ++ docs/vi/evaluations/test.mdx | 29 ++ docs/vi/evaluations/write.mdx | 76 +++ docs/vi/policies/deploy.mdx | 87 +++- docs/vi/policies/editor.mdx | 101 +++- docs/vi/policies/failure-behavior.mdx | 46 +- docs/vi/policies/local-configuration.mdx | 74 ++- docs/vi/policies/overview.mdx | 79 ++- docs/vi/policies/packs.mdx | 125 ++--- docs/vi/policies/publish-a-pack.mdx | 109 ++-- docs/vi/policies/rollback.mdx | 70 ++- docs/vi/policies/test.mdx | 60 +++ docs/vi/reference/cloud-cli.mdx | 372 ++++++------- docs/vi/reference/custom-agents.mdx | 114 ++-- docs/vi/reference/evaluator-sdk.mdx | 260 ++++----- docs/vi/reference/failproof-cli.mdx | 144 ++--- docs/vi/reference/harnesses.mdx | 98 ++-- docs/vi/reference/overview.mdx | 57 +- docs/vi/reference/policy-sdk.mdx | 156 +++--- docs/vi/sessions/evaluations.mdx | 54 +- docs/vi/start/integrations/custom-agents.mdx | 352 ++++++------- docs/vi/start/quickstart.mdx | 57 +- docs/vi/start/setup.mdx | 79 +-- docs/zh/admin/keys-and-permissions.mdx | 56 +- docs/zh/evaluations/deploy.mdx | 55 ++ docs/zh/evaluations/overview.mdx | 44 ++ docs/zh/evaluations/test.mdx | 29 ++ docs/zh/evaluations/write.mdx | 76 +++ docs/zh/policies/deploy.mdx | 83 ++- docs/zh/policies/editor.mdx | 101 +++- docs/zh/policies/failure-behavior.mdx | 56 +- docs/zh/policies/local-configuration.mdx | 90 ++-- docs/zh/policies/overview.mdx | 81 ++- docs/zh/policies/packs.mdx | 119 +++-- docs/zh/policies/publish-a-pack.mdx | 109 ++-- docs/zh/policies/rollback.mdx | 68 ++- docs/zh/policies/test.mdx | 60 +++ docs/zh/reference/cloud-cli.mdx | 260 ++++----- docs/zh/reference/custom-agents.mdx | 112 ++-- docs/zh/reference/evaluator-sdk.mdx | 252 ++++----- docs/zh/reference/failproof-cli.mdx | 162 +++--- docs/zh/reference/harnesses.mdx | 92 ++-- docs/zh/reference/overview.mdx | 49 +- docs/zh/reference/policy-sdk.mdx | 150 +++--- docs/zh/sessions/evaluations.mdx | 54 +- docs/zh/start/integrations/custom-agents.mdx | 358 ++++++------- docs/zh/start/quickstart.mdx | 63 ++- docs/zh/start/setup.mdx | 73 ++- 365 files changed, 22456 insertions(+), 16084 deletions(-) create mode 100644 docs/ar/evaluations/deploy.mdx create mode 100644 docs/ar/evaluations/overview.mdx create mode 100644 docs/ar/evaluations/test.mdx create mode 100644 docs/ar/evaluations/write.mdx create mode 100644 docs/ar/policies/test.mdx create mode 100644 docs/de/evaluations/deploy.mdx create mode 100644 docs/de/evaluations/overview.mdx create mode 100644 docs/de/evaluations/test.mdx create mode 100644 docs/de/evaluations/write.mdx create mode 100644 docs/de/policies/test.mdx create mode 100644 docs/es/evaluations/deploy.mdx create mode 100644 docs/es/evaluations/overview.mdx create mode 100644 docs/es/evaluations/test.mdx create mode 100644 docs/es/evaluations/write.mdx create mode 100644 docs/es/policies/test.mdx create mode 100644 docs/fr/evaluations/deploy.mdx create mode 100644 docs/fr/evaluations/overview.mdx create mode 100644 docs/fr/evaluations/test.mdx create mode 100644 docs/fr/evaluations/write.mdx create mode 100644 docs/fr/policies/test.mdx create mode 100644 docs/he/evaluations/deploy.mdx create mode 100644 docs/he/evaluations/overview.mdx create mode 100644 docs/he/evaluations/test.mdx create mode 100644 docs/he/evaluations/write.mdx create mode 100644 docs/he/policies/test.mdx create mode 100644 docs/hi/evaluations/deploy.mdx create mode 100644 docs/hi/evaluations/overview.mdx create mode 100644 docs/hi/evaluations/test.mdx create mode 100644 docs/hi/evaluations/write.mdx create mode 100644 docs/hi/policies/test.mdx create mode 100644 docs/it/evaluations/deploy.mdx create mode 100644 docs/it/evaluations/overview.mdx create mode 100644 docs/it/evaluations/test.mdx create mode 100644 docs/it/evaluations/write.mdx create mode 100644 docs/it/policies/test.mdx create mode 100644 docs/ja/evaluations/deploy.mdx create mode 100644 docs/ja/evaluations/overview.mdx create mode 100644 docs/ja/evaluations/test.mdx create mode 100644 docs/ja/evaluations/write.mdx create mode 100644 docs/ja/policies/test.mdx create mode 100644 docs/ko/evaluations/deploy.mdx create mode 100644 docs/ko/evaluations/overview.mdx create mode 100644 docs/ko/evaluations/test.mdx create mode 100644 docs/ko/evaluations/write.mdx create mode 100644 docs/ko/policies/test.mdx create mode 100644 docs/pt-br/evaluations/deploy.mdx create mode 100644 docs/pt-br/evaluations/overview.mdx create mode 100644 docs/pt-br/evaluations/test.mdx create mode 100644 docs/pt-br/evaluations/write.mdx create mode 100644 docs/pt-br/policies/test.mdx create mode 100644 docs/ru/evaluations/deploy.mdx create mode 100644 docs/ru/evaluations/overview.mdx create mode 100644 docs/ru/evaluations/test.mdx create mode 100644 docs/ru/evaluations/write.mdx create mode 100644 docs/ru/policies/test.mdx create mode 100644 docs/tr/evaluations/deploy.mdx create mode 100644 docs/tr/evaluations/overview.mdx create mode 100644 docs/tr/evaluations/test.mdx create mode 100644 docs/tr/evaluations/write.mdx create mode 100644 docs/tr/policies/test.mdx create mode 100644 docs/vi/evaluations/deploy.mdx create mode 100644 docs/vi/evaluations/overview.mdx create mode 100644 docs/vi/evaluations/test.mdx create mode 100644 docs/vi/evaluations/write.mdx create mode 100644 docs/vi/policies/test.mdx create mode 100644 docs/zh/evaluations/deploy.mdx create mode 100644 docs/zh/evaluations/overview.mdx create mode 100644 docs/zh/evaluations/test.mdx create mode 100644 docs/zh/evaluations/write.mdx create mode 100644 docs/zh/policies/test.mdx diff --git a/docs/ar/admin/keys-and-permissions.mdx b/docs/ar/admin/keys-and-permissions.mdx index fc3ef8cb..43a40efc 100644 --- a/docs/ar/admin/keys-and-permissions.mdx +++ b/docs/ar/admin/keys-and-permissions.mdx @@ -1,29 +1,29 @@ --- title: "المفاتيح والأذونات" -description: "إنشاء مفاتيح API ذات نطاق محدد للآلات والأتمتة والمشغلين." +description: "أنشئ مفاتيح API محدودة النطاق للآلات والأتمتة والمشغلين." icon: "key-round" --- -تنتمي مفاتيح API إلى منظمة وتحمل أذونات صريحة. استخدم مفاتيح منفصلة لإدراج العوامل وتسليم السياسات والمقيمين والأتمتة في CI والنصوص الإدارية. +تنتمي مفاتيح API إلى مؤسسة وتحمل أذونات صريحة. استخدم مفاتيح منفصلة لاستقبال الوكيل وتسليم السياسة والمقيّمون والأتمتة المستمرة والبرامج الإدارية. -## إنشاء وتدوير المفتاح +## إنشاء وتدوير مفتاح - - 1. انتقل إلى **Administration → Keys**، وحدد **new key**، وأدخل اسم الحمل الكروي. - 2. اختر مجموعة أذونات واضبط الأذونات الفردية فقط عندما تكون المجموعة المعرفة مسبقًا غير كافية. - 3. أنشئ المفتاح وانسخ سره لمرة واحدة فورًا. - 4. افتح المفتاح لاحقًا لتحديث المنح أو تعطيله أو إعادة إنشاء السر. + + 1. انتقل إلى **الإدارة → المفاتيح**، اختر **مفتاح جديد**، وأدخل اسم حمل العمل. + 2. اختر مجموعة أذونات واضبط الأذونات الفردية فقط عندما تكون القائمة المحددة غير كافية. + 3. أنشئ المفتاح وانسخ سره لمرة واحدة فوراً. + 4. افتح المفتاح لاحقاً لتحديث الأذونات أو تعطيله أو إعادة تعيين السر. - درج الإنشاء هو المكان الذي تختار فيه أضيق المنح المطلوبة من قبل الحمل الكروي. + درج الإنشاء هو المكان الذي تختار فيه أضيق الأذونات المطلوبة من قبل حمل العمل. - ![درج مفتاح API جديد يحتوي على مجموعات أذونات مسبقة الصنع والمنح الفردية.](/images/dashboard/key-create.png) + ![درج مفتاح API جديد يعرض قوائم الأذونات المحددة والأذونات الفردية.](/images/dashboard/key-create.png) - بعد الإنشاء، تعرض صفحة المفاتيح البيانات الوصفية الثابتة وإجراءات الإدارة. لا يتم عرض السر لمرة واحدة مرة أخرى. + بعد الإنشاء، تعرض صفحة المفاتيح البيانات الوصفية الدائمة وإجراءات الإدارة. السر لمرة واحدة لن يتم عرضه مرة أخرى. - ![صفحة مفاتيح API تعرض أذونات المفتاح ووقت الإنشاء وإجراءات إعادة الإنشاء والتعطيل.](/images/dashboard/api-keys.png) + ![صفحة مفاتيح API تعرض أذونات المفتاح ووقت الإنشاء وإجراءات إعادة التعيين والتعطيل.](/images/dashboard/api-keys.png) - استخدم هذه القائمة لمراجعة المنح بانتظام وتعطيل المفاتيح التي لم تعد تتطابق مع حمل كروي نشط. + استخدم هذه القائمة لمراجعة الأذونات بانتظام وتعطيل المفاتيح التي لا تعود تعيّن إلى حمل عمل نشط. ```bash @@ -36,39 +36,39 @@ icon: "key-round" fp keys disable production-agents ``` - أعد توجيه أو احتفظ بإخراج الإنشاء/إعادة الإنشاء بأمان؛ يتم إرجاع السر مرة واحدة. + أعد توجيه أو التقط مخرجات الإنشاء/إعادة التعيين بشكل آمن؛ يتم إرجاع السر مرة واحدة فقط. -الأذونان المطلوبان لآلة Failproof AI متصلة مستقلان: +الأذونتان المطلوبتان من قبل آلة Failproof AI المتصلة مستقلتان: - `events:add` يرسل الأحداث وبيانات الجلسة. - `policies:pull` يسترجع نشرات السياسة المعينة. -يتم عرض أسرار المفاتيح عند إنشاؤها أو إعادة إنشاؤها. قم بتخزينها في مدير السر وقم بتدويرها دون إعادة استخدام بيانات المشغل التفاعلية. +يتم عرض أسرار المفاتيح عند إنشاؤها أو إعادة تعيينها. قم بتخزينها في مدير الأسرار وأدرها دون إعادة استخدام بيانات اعتماد المشغل التفاعلية. -## فهرس الأذونات +## كتالوج الأذونات | المنطقة | الأذونات | | --- | --- | | الأحداث | `events:add`, `events:read` | -| المفاتيح | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` للجلسات البشرية فقط | +| المفاتيح | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`؛ `keys:update` للجلسات البشرية فقط | | المستخدمون | `users:create`, `users:read`, `users:update`, `users:delete` | -| التقييمات | `evaluations:read`, `evaluations:trigger` | -| لوحات المعلومات | `dashboards:read`, `dashboards:write`, `dashboards:delete` | +| التقييمات | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | +| لوحات التحكم | `dashboards:read`, `dashboards:write`, `dashboards:delete` | | الاستعلامات | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | | المساعد | `agent:use` | | الإعدادات | `settings:read`, `settings:write` | | التنبيهات | `alerts:read`, `alerts:write` | | المشاكل | `issues:read`, `issues:create`, `issues:close` | -| التدقيق | `audits:read`, `audits:write` | +| عمليات التدقيق | `audits:read`, `audits:write` | | السياسات | `policies:read`, `policies:write`, `policies:pull` | | الاستخدام | `usage:read` | -`orgs:admin` محجوز لمشغل المثيل ولا يمكن منحه لمفتاح منظمة أو عضو عادي. يتم قبول رموز `incidents:*` و `alerts:ack` المتقاعدة للتوافقية وتطبيع الأذونات `issues:*` الحالية. +`orgs:admin` محجوز لمشغل المثيل ولا يمكن منحه لمفتاح تنظيمي أو عضو عادي. يتم قبول الرموز المتقاعدة `incidents:*` و `alerts:ack` للتوافق وتطبيعها على أذونات `issues:*` الحالية. -مجموعات الأذونات المدمجة هي `read-only` و `standard` و `admin`. يضيف `standard` تشغيل التقييم وتنفيذ الاستعلامات والاستجابة للمشاكل واستخدام المساعد إلى أذونات القراءة. يؤدي إنشاء المفتاح إلى إزالة المنح التي تقتصر على البشر حتى عندما تحتوي مجموعة الأذونات عليها. +مجموعات الأذونات المدمجة هي `read-only` و `standard` و `admin`. يضيف `standard` تفعيل التقييم وتنفيذ الاستعلام والاستجابة للمشاكل واستخدام المساعد إلى أذونات القراءة. ينزع إنشاء المفتاح الأذونات الخاصة بالبشر فقط حتى عندما تحتوي مجموعة الأذونات عليها. - يمكن لمفاتيح النطاق على مستوى المثيل تحديد منظمة باستخدام رأس `X-AgentEye-Org`. قم بتعيينه بشكل صريح على النشرات متعددة المنظمات؛ قد يؤدي حذفه إلى تحديد المنظمة الافتراضية. + يمكن لمفاتيح النطاق الموسع اختيار منظمة من خلال رأس `X-AgentEye-Org`. اضبطه بصراحة في النشرات متعددة المنظمات؛ قد يؤدي الإغفال إلى تحديد المنظمة الافتراضية. \ No newline at end of file diff --git a/docs/ar/evaluations/deploy.mdx b/docs/ar/evaluations/deploy.mdx new file mode 100644 index 00000000..7bff943f --- /dev/null +++ b/docs/ar/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "نشر وإصدار تقييم" +description: "نشر نسخة ثابتة، اطلع على ما هو مباشر، انشر نسخ جديدة، استعد للإصدار السابق، وسجل الجلسات التي لديك بالفعل." +icon: "cloud-upload" +--- + +## نشره + +حدد **نشر `@`** في أسفل صفحة التأليف. تصبح النسخة ثابتة بمجرد نشرها: من ذلك الحين فصاعداً، كل جلسة تنتهي وينطبق عليها الشرط يتم تسجيلها بها. + +## اطلع على ما هو مباشر + +**تحليل → تأليف التقييم** يسرد تعريفات المؤسسة المستضافة، التقييمات التي يقوم بها مُقيّم الإدارة. يعرض كل صف: + +- اسمه ومفتاحه وإصداره ونوع النتيجة +- مجموع اختياره المصدر، الذي يميز الإصدارات المنشورة عن بعضها دون فتح الكود +- ما إذا كان **شرطياً** أو يعمل على **جميع الجلسات المكتملة** — الشرط هو ما يحصر التقييم على وكلاء أو بيئات معينة +- المهلة الزمنية والعلامات ووقت آخر تغيير له + +![قائمة التعريفات المستضافة: اسم كل تقييم ومفتاحه وإصداره ونوع النتيجة والمجموع والمهلة الزمنية والنطاق، مع نسخة جديدة وتفعيل أو تعطيل.](/images/dashboard/eval-definitions.png) + +ابحث في القائمة أو صفّيها حسب الحالة. التقييمات التي يسجلها عامل العمل الخاص بك لا تُدرج هنا؛ النتائج الخاصة بها تحمل علامة **عميل** على [صفحة التقييمات](/ar/sessions/evaluations)، والتقييمات المستضافة تحمل **إدارة**. + +يمكن للمؤسسة أن تمتلك ما يصل إلى 100 تقييم مستضاف مختلف مفعل في المرة الواحدة. + +## نشر نسخة جديدة + +حدد **نسخة جديدة** على صف. تفتح صفحة التأليف مع كود تلك النسخة؛ غيّره واختبره ونشره. ينتقل المفتاح ونوع النتيجة ولا يمكن أن يتغيرا. + +نشر خليفة يعطّل سابقه ويبقيه على القائمة. تحتفظ النتائج بالنسخة التي أنتجتها، لذا يوضح الرسم البياني بالضبط متى تولت المنطق الجديد. + +## استعد للإصدار السابق + +حدد **تعطيل** على النسخة الحالية و**تفعيل** على الإصدار الذي تريده مرة أخرى. لا يتم حذف أي شيء، وكل نتيجة تبقى كما هي. + +## إيقاف التقييم + +حدد **تعطيل**. بدون نسخة مفعلة، يتوقف عن العمل على الجلسات الجديدة. لإيقاف تقييم يقوم به عامل العمل الخاص بك، توقف عن تسجيله: أزله من العامل أو أوقف العامل. + +## تسجيل الجلسات التي لديك بالفعل + +التقييم يعمل للأمام: نسخة تُنشر الآن لا تسجل جلسة انتهت قبلها. لتسجيل السجل، افتح **تسجيل الجلسات التي لديك بالفعل** على صفحة تأليف التقييم، واختر نافذة تصل إلى 90 يوم وبشكل اختياري تقييم واحد فقط، وعد قبل أن تعمل. العدد هو بالضبط ما سيعمل، وكل زوج جلسة وتقييم فيه قابل للفواتير. + +يملأ الفجوات فقط. جلسة لديها بالفعل نتيجة لذلك التقييم تحتفظ بها، والعمل على نفس النافذة مرتين لا يسجل شيئاً جديداً. + +لتسجيل جلسة واحدة مرة أخرى — بعد إصلاح أو لجلسة لم تنته بنظافة — حدد **إعادة تقييم** على صفحتها. تُضاف النتيجة الجديدة إلى سجل الجلسة؛ تبقى الأولى. + +## الأذونات + +| الإذن | يتيح لك | +| --- | --- | +| `evaluations:read` | مشاهدة النتائج وفتح صفحة تأليف التقييم | +| `evaluations:trigger` | مشاهدة ونشر وإصدار وتفعيل وتعطيل التعريفات المستضافة؛ اختبارها؛ تسجيل السجل؛ إعادة تقييم جلسة | +| `events:read` | الاختبار على جلسات حقيقية وتأسيس المسودات في مفاتيح البيانات الخاصة بك، بالإضافة إلى `evaluations:trigger` | +| `evaluations:run` | تشغيل عامل المقيّم الخاص بك | \ No newline at end of file diff --git a/docs/ar/evaluations/overview.mdx b/docs/ar/evaluations/overview.mdx new file mode 100644 index 00000000..4d3a2035 --- /dev/null +++ b/docs/ar/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "تقييم الوكلاء" +description: "قيّم كل جلسة منتهية باستخدام التقييمات التي تحددها: فحوصات Python مستضافة، أو حكام LLM في العامل الخاص بك." +icon: "gauge" +--- + +يسجل التقييم جلسة وكيل منتهية. عند انتهاء جلسة، يتم تشغيل كل تقييم مفعّل ينطبق عليها وتسجيل ما وجدته، مع التفاصيل التي يمكنك قراءتها بجانب التتبع: + +- **درجة** من 0 إلى 1، مع إمكانية تحديدها كناجحة أو فاشلة +- **مقياس**، مثل عدد، أو مدة، أو تكلفة، مع وحدتها +- **تأكيد**، إما أنه نجح أو لم ينجح + +## نوعان من المقيّمين + +| | Python مستضاف | العامل الخاص بك | +| --- | --- | --- | +| مكتوب | في لوحة التحكم، تحت **Analyze → eval authoring** | في Python، باستخدام [Evaluator SDK](/ar/reference/evaluator-sdk) | +| يعمل | على مقيّم Failproof AI المُدار، في بيئة معزولة | على البنية التحتية الخاصة بك | +| الأفضل لـ | الفحوصات الحتمية المستندة إلى الكود | حكام LLM، استدعاءات النماذج، الحزم، الأسرار، الوصول إلى الشبكة، المعالجة الثقيلة | + +Python المستضاف متعمد الصغر: تعبير واحد، بدون استيرادات، بدون شبكة. أي شيء يتطلب نموذج — مثل حكم LLM يسجل ما إذا كانت الإجابة ذات صلة — يعمل في العامل الخاص بك بدلاً من ذلك. لا يحتاج أي من النوعين إلى اتصال واردة: يطالب العمال بالجلسات المنتهية ويقدمون النتائج عبر HTTPS الصادرة. + +## كل منظمة تقيّم وكلاءها الخاصة + +التقييمات تنتمي إلى المنظمة التي تحددها. تكتب كل منظمة في النسخة الخاصة بها — فحوصاتها الخاصة، وشروطها، وحدودها، وتسمياتها — وتصدر نسخًا وتنشرها دون التأثير على أي نسخة أخرى، وترى النتائج الخاصة بها فقط. صفّ تلك النتائج حسب الوكيل والبيئة والتقييم والوقت، أو اسأل المساعد عنها. + +## من المسودة الأولى إلى الدرجات المباشرة + + + + اشرح ما يجب قياسه واترك للمساعد صياغة مسودة، أو اكتبها بنفسك. انظر [كتابة التقييم](/ar/evaluations/write). + + + قم بتشغيلها على جلسات حقيقية قبل إطلاقها مباشرة؛ لا يتم حفظ أي شيء. انظر [اختبار التقييم](/ar/evaluations/test). + + + انشر نسخة ثابتة، ونشر نسخًا جديدة مع تطورها، والعودة إلى نسخة سابقة. انظر [النشر والإصدار](/ar/evaluations/deploy). + + + مثّل الدرجات بيانيًا على مدار الوقت، وقارن بين الوكلاء والبيئات، واسأل المساعد. انظر [قراءة نتائج التقييم](/ar/sessions/evaluations). + + + +التقييم يعمل للأمام: نسخة تم نشرها الآن تسجل الجلسات التي تنتهي من الآن فصاعدًا. لتسجيل الجلسات التي لديك بالفعل، [املأ الفجوات](/ar/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file diff --git a/docs/ar/evaluations/test.mdx b/docs/ar/evaluations/test.mdx new file mode 100644 index 00000000..4331e988 --- /dev/null +++ b/docs/ar/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "اختبار التقييم" +description: "قم بتشغيل التقييم على جلساتك الحقيقية قبل نشره. لا يتم حفظ أي شيء." +icon: "flask-conical" +--- + +**اختبار هذا التقييم**، في صفحة التأليف، يقوم بتشغيل الكود مقابل جلساتك الحقيقية على مجموعة المقيّمين دون نشره. لا يتم حفظ أي شيء: الفشل هنا هو معاينة فقط، والنشر مسموح به دائماً. + + + + حدد **تحقق** لترجمة الكود والشرط مقابل قواعد الحماية الرملية دون تشغيلهما على أي جلسة. + + + ضيّق نطاق الجلسات المطابقة حسب الوكيل أو البيئة أو الوقت أو معرّف الجلسة، وحدد ما يصل إلى 10 جلسات. أدرج الجلسات التي يجب أن يفشل فيها التقييم وكذلك تلك التي يجب أن ينجح فيها. + + + حدد **تشغيل مقابل N جلسة**، واقرأ كل صف. + + + +| الصف | المعنى | +| --- | --- | +| **حسناً** | تم تشغيله. يسرد الصف كل درجة ومقياس وتأكيد أعاده، وكم من الوقت استغرق. | +| **تم تخطيه** | عادت الشرط `False`، لذلك لم يتم تشغيل التقييم. هذا تخطي، وليس فشلاً. | +| فشل | رفع استثناء أو انتهت مهلة الوقت أو استخدم شيئاً ترفضه الحماية الرملية. يوضح الصف أي منها، و**أصلحه** يسلم الخطأ للمساعد عندما يمكنه المساعدة. | + +![لوحة اختبار هذا التقييم: ثلاث جلسات تم اختيارها حسب الوكيل، جلستان حسناً وواحدة تم تخطيها لأن شرطها أعاد False.](/images/dashboard/eval-test.png) + +تتوقف النتيجة عن كونها حالية في اللحظة التي تقوم فيها بتحرير الكود؛ يتم تلميعها بدلاً من إعادة استخدامها. \ No newline at end of file diff --git a/docs/ar/evaluations/write.mdx b/docs/ar/evaluations/write.mdx new file mode 100644 index 00000000..19400fac --- /dev/null +++ b/docs/ar/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "كتابة تقييم" +description: "صف ما تريد قياسه واترك للمساعد صياغة تقييم Python مستضاف، أو اكتب الكود بنفسك. تعمل حكام LLM في عاملك الخاص." +icon: "file-pen-line" +--- + +التقييمات المستضافة عبارة عن أكواد Python صغيرة وحتمية، مكتوبة في لوحة التحكم وتعمل على أسطول تقييم Failproof AI. المنطق الأثقل — حكم LLM، أو حزمة، أو سر، أو استدعاء شبكة — يعمل في [عاملك الخاص](#write-it-in-your-own-worker) بدلاً من ذلك. + +## صغه من وصف + +1. اذهب إلى **Analyze → eval authoring** واختر **new eval**. +2. صف ما تريد قياسه بالإنجليزية العادية، أو اختر من **start from an example…**، ثم اختر **draft**. +3. راجع الحقول والكود الذي يملأها، ثم [اختبره](/ar/evaluations/test) و[انشره](/ar/evaluations/deploy). + +![صفحة تأليف التقييم مع تقييم مسودة: الوصف، وملاحظات المساعد حول المسودة، واسم وأساس ونسخة ونتيجة وانقطاع وتسميات وشروط الحقول.](/images/dashboard/eval-authoring-draft.png) + +المسودة مبنية على الأحداث الخاصة بمؤسستك: تقرأ الصفحة مفاتيح الحمولة التي حملتها جلساتك على مدار السبعة أيام الماضية، لذا يقرأ الكود المفاتيح الموجودة بدلاً من التخمين. قبل تسليم المسودة، يختبرها المساعد مقابل ما يصل إلى خمس من جلساتك الأخيرة، ويصلح كل ما يمكنه إثبات أنه معطوب — لمدة تصل إلى ثلاث جولات — وفحص مرة واحدة أن الكود يقيس ما طلبته. احتفظ بالوصف محددًا: الطلبات العامة أبطأ ويمكن أن تنقطع. راجع الكود على أي حال؛ النشر لا يتم حظره أبدًا. + +## تعيين الحقول + +| حقل | ما هو | +| --- | --- | +| name | ما يراه الناس. قابل للتعديل لاحقًا | +| key | المعرف المستقر الذي تخطط تحته النتائج، مثل `code_assistant_quality_gate` | +| version | أي سلسلة إصدار بدون مسافات، مثل `1.0.0` | +| result | **score** (من 0 إلى 1)، **metric** (رقم بوحدة)، أو **assertion** (نجح أو لا) | +| timeout seconds | افتراضي 30. يوقف الحماية أي تشغيل فردي عند 60 | +| labels | حتى 20، مفصولة بفواصل. قابلة للتعديل لاحقًا | +| condition | اختياري. تعبير Python؛ يعمل التقييم فقط على الجلسات حيث يكون `True` | + +استخدم الشرط لتحديد نطاق التقييم للعوامل والبيئات المخصصة له: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +المفتاح والإصدار ونوع النتيجة والشرط والكود ثابتة بمجرد النشر: لتغيير أي منها، انشر إصدارًا جديدًا. الاسم والتسميات وما إذا كانت مفعلة تبقى قابلة للتعديل. + +## اكتب الكود بنفسك + +**كود المقيّم** هو تعبير Python واحد يُرجع `EvalResult(...)`، مع وجود `session` في النطاق. هذا الواحد يسجل حصة نتائج الأداة التي عادت بشكل صحيح: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +تبدأ النتيجة بمفتاح التقييم الخاص به، في نوعه المعلن: `score=` لتقييم النقاط، أو إدخال `metrics` أو `assertions` باسم المفتاح لتقييم متري أو مؤكدة. تأتي المقاييس والمؤكدات الأخرى معها، حتى 25 نتيجة في التشغيل. + +| في النطاق | يعطيك | +| --- | --- | +| `session` | `session_id`، `agent_id`، `environment`، `started_at`، `ended_at`، `event_count`، و`events`، بالإضافة إلى `count(event_type)` و`events_of_type(event_type)` | +| كل حدث | `id`، `ts`، `event_type`، و`payload` | +| أنواع النتائج | `EvalResult`، `Score`، `Metric`، `Assertion`، و`ConditionResult` للشرط | +| Builtins | `abs`، `all`، `any`، `bool`، `dict`، `float`، `int`، `len`، `list`، `max`، `min`، `range`، `round`، `set`، `sorted`، `str`، `sum`، `tuple` | + +لا شيء آخر قابل للوصول: لا استيراد، ولا سمات تتجاوز بيانات الجلسة وطرق السلسلة والقاموس البسيطة مثل `get` و`lower` و`split`، والتي يجب استدعاؤها بدلاً من الإشارة إليها. مفاتيح الحمولة هي كل ما يرسله وكلاء عملك — `status` أعلاه مثال فقط — لذا اقرأها من جلسة حقيقية. **format** يرتب الكود و**fix** يطلب من المساعد إصلاحه. يمكن أن يكون الكود حتى 128 KiB، والشرط حتى 16 KiB. + +![محرر كود المقيّم، مع format و fix، يعرض التأكيدات لتقييم مسودة.](/images/dashboard/eval-authoring-code.png) + +## اكتبه في عاملك الخاص + +عندما يحتاج التقييم إلى نموذج أو حزمة أو سر أو شبكة، اكتبه باستخدام [Evaluator SDK](/ar/reference/evaluator-sdk) وشغّله على البنية التحتية الخاصة بك. يستخدم نفس أنواع النتائج، وتظهر نتائجه بجانب النتائج المستضافة، موسومة **customer**: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/ar/policies/deploy.mdx b/docs/ar/policies/deploy.mdx index 55b293fb..6d13da67 100644 --- a/docs/ar/policies/deploy.mdx +++ b/docs/ar/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "نشر السياسات" -description: "طرح نسخة سياسة تمت مراجعتها على الأجهزة المخطط لها." +title: "نشر سياسة" +description: "ضع نسخة سياسة مختبرة على الآلات في وضع المراقبة، وفرضها، وتأكد من أن كل آلة التقطتها." icon: "cloud-upload" --- -يربط النشر نسخة واحدة أو أكثر من السياسات بمجموعة مستهدفة من الأجهزة المسجلة. +يضع النشر نسخ السياسات المنشورة على آلة، كل منها بأحد التأثيرين: -## تطبيق النشر +- **المراقبة** تسجل ما كانت السياسة ستفعله، ولا تحجب أي شيء. +- **الإنفاذ** يتصرف بناءً على القرار: `deny` يحجب الاستدعاء و`instruct` يوجه الوكيل. + +## إضافة آلة + +تظهر الآلة ضمن **Admin → enforcement** بمجرد اتصالها بـ Cloud. إذا لم تكن موجودة بعد: - 1. انتقل إلى **Admin → enforcement**، ابحث عن الجهاز، وقم بتوسيع صفه. - 2. حدد **edit**، أضف نسخة السياسة المراجعة، واختر **observe** أو تأثيرها المفروض. - 3. طبق التغيير، ثم انتظر الفحص التالي للجهاز وأكد حالة نشره وتغطيته. - 4. انتقل إلى **Observe → policy** لفحص القرارات المباشرة. + 1. انتقل إلى **Administration → Keys** وأنشئ مفتاحًا باستخدام `policies:pull`، حتى تتمكن الآلة من استقبال النشرات، و`events:add`، حتى تصل قراراتها إلى Cloud. + 2. اتصل بالآلة باستخدام هذا المفتاح — [ربط آلة بـ Cloud](/ar/start/setup#connect-a-machine-to-cloud) يشرح ذلك. + 3. تأكد من ظهورها ضمن **Admin → enforcement**. + + + على الآلة: - ![محرر نشر الجهاز مع نسخ السياسات وتأثيرات enforce و observe وإجراء تطبيق النشر.](/images/dashboard/enforcement-editor.png) + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + في محطة طرفية، يطلب `failproofai config` ما إذا كان يجب الاتصال بـ Cloud ويأخذ المفتاح عند موجه مخفي. ثم تأكد من تسجيل الآلة باستخدام `fp fleet list` من أي مكان. - - انشر من واجهة سطر الأوامر باستخدام `fp fleet`. راجع المجموعة الناتجة قبل تطبيقها — `deploy` يطبع الخطة الكاملة ويطلب **فقط على طرفية تفاعلية بدون `--json`**. تحت `--json`، أو مع `--yes`، أو مع إعادة توجيه stdin (خطوة CI، نص برمجي، وكيل يقوم بتنفيذ شيء ما) يتم التطبيق فوراً بدون خطة وبدون طلب — لذا قم بتشغيل `fp fleet show ` أولاً إذا كنت تريد مراجعة: + + +## نشر في وضع المراقبة + + + 1. انتقل إلى **Admin → enforcement**، وجد الآلة، وأوسّع صفها. + 2. حدد **edit**، أضف نسخة السياسة المختبرة، واختر **observe**. + 3. طبق التغيير، ثم انتظر الفحص التالي للآلة وتأكد من حالة نشرها والتغطية. + 4. انتقل إلى **Observe → policy** لفحص القرارات المباشرة. + + ![محرر نشر الآلة مع نسخ السياسات وتأثيرات الإنفاذ والمراقبة وإجراء تطبيق النشر.](/images/dashboard/enforcement-editor.png) + + ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - يعرض `fp fleet diff ` القصد مقابل التسليم (يقرأ الجهاز على أنه `behind` حتى يستقصي مرة أخرى)، و`fp fleet history ` يسرد الأجيال، و`fp fleet rollback ` يعيد تطبيق واحد — يرفض إذا كان هذا الجيل يسمي سياسة تم تعطيلها أو حذفها منذ ذلك الحين. + اللاحقة `:observe` هي ما يجعلها في وضع المراقبة: `--add no-force-push` بدون لاحقة يحافظ على التأثير الذي تمتلكه الآلة بالفعل لتلك السياسة، وخلاف ذلك ينفذ. غيّره لاحقًا إلى الإنفاذ باستخدام `--add no-force-push:enforce`. - افحص الجهاز نفسه باستخدام `failproofai config --status`، واستخدم `fp sessions --env production --since 24h` و`fp events --event-type hook_completed` بعد النشر للتحقق من وصول النشاط إلى Cloud. + `deploy` **يستبدل مجموعة السياسات الكاملة للآلة** بالنتيجة. يطبع الخطة، ثم يطلب التأكيد — لكن فقط على محطة طرفية تفاعلية. باستخدام `--yes`، ضمن `fp --json`، أو مع إعادة توجيه stdin (خطوة CI، نص برمجي، وكيل ينفذ أوامر) يتم التطبيق دون طلب؛ الخطة لا تزال مطبوعة أو مُرجعة كـ `plan` ضمن `--json`. + + على الآلة، `failproofai policies` تدرج السياسات المُدارة بواسطة Cloud التي تعمل و`failproofai config --status` يعرض اتصالها. استخدم `fp sessions --env production --since 24h` و`fp events --event-type hook_completed` لتأكيد وصول نشاطها إلى Cloud. - - انشر نسخة تمت مراجعتها، وليس مسودة قابلة للتغيير، بدءاً من جهاز غير إنتاجي أو مجموعة صغيرة يمكنك فحص جلساتها. + + اختر النسخة المنشورة والآلات التي يجب تشغيلها عليها. - - راجع المطابقات والأسباب والأدوات المتأثرة والإيجابيات الكاذبة دون حجب العمل. + + راجع التطابقات والأسباب والأدوات المتأثرة والإيجابيات الخاطئة بينما لا يتم حجب أي شيء. - - قم بالترقية بعد ملاحظة المطابقات التي تفصل الإجراءات غير الآمنة عن الإجراءات الصحيحة، ثم تأكد من أن كل جهاز مقصود قد سحب النشر ويقوم بالإبلاغ عن القرارات. + + غيّر التأثير إلى الإنفاذ بمجرد فصل التطابقات المراقبة للإجراءات غير الآمنة عن الإجراءات الصحيحة، ثم تأكد من أن كل آلة مقصودة انسحبت التغيير وتقدم القرارات. -تحتاج الأجهزة إلى إمكانية `policies:pull`. يتم التحكم في الإبلاغ عن الأحداث بشكل منفصل بواسطة `events:add`؛ تحقق من كليهما عندما تتوقع تحليل Cloud وفرض. +## التحقق من التغطية + +التغطية تجيب على ما إذا كانت السياسة تعمل حيث توجد المخاطرة. + +1. انتقل إلى **Admin → enforcement** واستعرض إجماليات الإنفاذ والمراقبة. +2. ابحث عن آلة بالمعرف أو الملصق، أو قم بالتصفية للآلات التي تفتقد سياسة. +3. وسّع الصف لمقارنة السياسات المعينة والنشر المبلّغ عنه والفحص الأخير والسجل. +4. أحدّث بعد فترة الاستطلاع للآلة عندما يكون النشر المطبق لا يزال معلقًا. + +![أسطول الإنفاذ يعرض تغطية السياسة وحالة نشر الآلة وتعيينات المراقبة والإنفاذ.](/images/dashboard/enforcement-fleet.png) + +ابحث عن الآلات التي لم تسحب النشر الأخير، والآلات المسجلة التي توقفت عن الإبلاغ، والسياسة المعينة للبيئة الخاطئة، وانجراف الإصدار بعد تحديث متقطع. + +ضع تسميات للآلات حسب الحمل والبيئة — أسماء المضيفين وحدها نادراً ما تستمر بعد الزيادة التلقائية أو الاستبدال: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - إدارة الفرض هي سير عمل إداري سحابي. لا تتعامل مع مسارات الفرض الحصرية للجذر على أنها نقاط نهاية API عادية من `/v1`. + إدارة الإنفاذ هي سير عمل إداري بـ Cloud. لا تتعامل مع مسارات الإنفاذ الحصرية للـ root كنقاط نهاية عادية `/v1` API للعملاء. \ No newline at end of file diff --git a/docs/ar/policies/editor.mdx b/docs/ar/policies/editor.mdx index 9668f9c0..e0e24433 100644 --- a/docs/ar/policies/editor.mdx +++ b/docs/ar/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "محرر السياسات" -description: "إنشاء ومراجعة السياسات ذات الإصدارات من نمط فشل مؤكد." +title: "كتابة سياسة" +description: "دع Failproof AI يصيغ سياسة من نتيجة تدقيق، أو اكتبها بنفسك، ثم راجعها واختبرها ونشرها." icon: "file-pen-line" --- -استخدم محرر السياسات لتحويل نتيجة بحث أو مشكلة إلى قاعدة قابلة للنشر. احتفظ بالتأليف منفصلاً عن النشر بحيث لا يمكن لمسودة أن تغيّر السلوك الحي بصمت. +هناك طريقتان لكتابة سياسة: السماح لـ Failproof AI بصياغتها من نتيجة تدقيق، أو كتابة الكود بنفسك. لا يتم نشر أو نشر أي شيء حتى تختار القيام بذلك. -عندما تكون لديك مشكلة بها نمط إجراء قابل للتكرار، افتحها تحت **Analyze → issues** واختر **generate policy**. يشرح Failproof AI أولاً ما إذا كانت السياسة يمكنها التعبير عن المشكلة، ثم تنقل النية المراجعة وسياق النتيجة إلى المحرر. يبقى المصدر المُنتج كمسودة حتى تنشره. +## كتابة سياسة من تدقيق -## نشر إصدار السياسة +يكتشف التدقيق عطلاً؛ والسياسة توقف حدوثها مرة أخرى. يصيغ Failproof AI السياسة من أدلة النتيجة نفسها. + +### 1. تشغيل تدقيق + +[شغّل تدقيق](/ar/audits/run) على الجلسات التي يحدث فيها الفشل. تحمل كل نتيجة جلسات الأدلة الخاصة بها والسبب الجذري ومسار الوقاية المقترح. ابدأ من نتيجة لها **نمط إجراء قابل للتكرار** — يمكن للسياسة فقط إيقاف ما يمكنها التعرف عليه في حدث الخطاف. + +### 2. إنشاء المسودة - - 1. انتقل إلى **Admin → policy editor** وفي **compose**، وصف نمط الفشل أو الصق مصدر سياسة JavaScript. - 2. تحقق من صحة المصدر وأصلح كل خطأ يتم الإبلاغ عنه. - 3. أدخل هوية السياسة وانشرها، ثم استخدم **library** للمقارنة أو تعطيل الإصدارات. - 4. اختر **enforcement** عندما يكون الإصدار جاهزاً لنشر الآلة. + + 1. افتح مشكلة النتيجة ضمن **Analyze → issues** وتحقق من الجلسات المقتبسة والسبب الجذري والتوصية. + 2. اختر **generate policy**. يخبرك Failproof AI أولاً ما إذا كانت السياسة يمكن أن تعبر عن المشكلة على الإطلاق. تعني نتيجة **no policy** أن الحل هو تنبيه أو تغيير سير عمل أو شخص — وليس سياسة. + 3. اختر **write this policy**. يصبح عنوان المشكلة والنتيجة والسبب الجذري والتوصية والنية الإنفاذ المقترحة مسودة في **Admin → policy editor**. استخدم **open the editor anyway** عندما تختلف مع فحص الصلاحية. - ![عرض compose في محرر السياسات يتضمن هوية السياسة والتأليف بمساعدة الذكاء الاصطناعي والتحقق من المصدر وعناصر التحكم في النشر.](/images/dashboard/policy-editor.png) + ![محرر السياسة مع هوية السياسة والصياغة بمساعدة الذكاء الاصطناعي والتحقق من المصدر وعناصر التحكم في النشر.](/images/dashboard/policy-editor.png) - انشر من واجهة سطر الأوامر باستخدام `fp policies publish`. تُنشئ **إصدار جديد** ولا تحرر واحداً موجوداً، وتتحقق من المصدر باستخدام node قبل الإرسال — لا يفعل ذلك شيء آخر في المراحل اللاحقة، لذا كان خطأ بناء الجملة قد يظهر على الآلة في وقت الفرض: + اقرأ الأدلة، ثم صِغ مع المساعد. يطبع `compose` المصدر لمراجعتك ولا ينشر شيئاً: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - النشر لا ينشر أي شيء — يبقى إصدار جديد غير مستخدم حتى يضعه `fp fleet deploy` على آلة. يقوم `fp policies compose ""` بصياغة المصدر بمساعدة مساعد Cloud ويطبعه للمراجعة بدلاً من نشره. - - لتثبيت سياسة في وكيل CLI محلي بدلاً من ذلك (وليس Cloud)، استخدم `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. + يتطلب `compose` جلسة موقعة (`fp login`) دورها لديه `policies:write`؛ يرفض مفاتيح API. -## قائمة التحقق من التأليف +### 3. مراجعة المسودة + +المسودة نقطة انطلاق وليست حكماً. قبل النشر، تحقق من أنها: + +1. تسمي وضع الفشل باللغة التشغيلية. +2. تطابق فقط أحداث الخطاف والأدوات التي تحمل أدلة كافية للقرار. +3. تستخدم أضيق شرط يمسك الإجراء غير الآمن. +4. تعيد سبباً يخبر الوكيل ما يجب فعله بدلاً من ذلك. +5. تستخدم `instruct` حيث يمكن للوكيل تصحيح المسار بأمان، و `deny` فقط حيث السماح بالإجراء غير مقبول أو لا رجعة فيه. + +تحقق من المصدر في المحرر وأصلح كل خطأ تم الإبلاغ عنه. + +### 4. اختبره، ثم انشره + +شغّل **backtest** تحت المصدر قبل النشر: يعيد تشغيل المسودة مقابل الاستدعاءات التي قامت بها أسطولك بالفعل ويحسب الاستدعاءات الفعالة التي كانت ستقاطعها. [Test a policy](/ar/policies/test) يغطي ذلك والفحوصات الأخرى. + +عندما تتصرف بشكل صحيح، أدخل هوية السياسة واختر **publish version**. يؤدي النشر إلى إنشاء نسخة ثابتة وعدم نشر أي شيء: فهو يبقى غير مستخدم حتى [تنشره](/ar/policies/deploy). من محطة نهائية: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +يتحقق `publish` من المصدر قبل إرساله، لذا تظهر أخطاء بناء الجملة هنا بدلاً من الماكينة وقت الإنفاذ. + +## اكتبه بنفسك + +السياسة هي JavaScript أو TypeScript ضد API `failproofai`: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +هذا يطابق `production/config.yml` و `/srv/production/config.yml` و `/srv/production` و `C:\\production\\config.yml` لكل من `Write` و `Edit`، لكن ليس `production-backup`: يجب أن تكون `production` جزءاً كاملاً من المسار. السياق يحمل أيضاً نوع الحدث والحمول المُعاد تنسيقه وبيانات وصفية الجلسة والمعاملات والمصدر CLI عند توفره — انظر [policy SDK](/ar/reference/policy-sdk). + +لنشره كنسخة، ألصق المصدر في **compose** في **Admin → policy editor** واتبع الخطوات 3 و 4 أعلاه، أو انشر الملف من محطة نهائية باستخدام `fp policies publish`. -1. سمّ نمط الفشل باللغة التشغيلية. -2. اختر أحداث الخطاف والأدوات التي تحتوي على أدلة كافية للقرار. -3. اكتب أضيق شرط يطابق السلوك غير الآمن. -4. أرجع سبباً يخبر الوكيل أو المشغل ما يجب فعله بعد ذلك. -5. أضف أمثلة يجب أن تطابق وأمثلة يجب أن تبقى مسموحة. -6. احفظ إصدار جديد واطلب مراجعة. +لتشغيله على ماكينة بدون Cloud، احفظه تحت `.failproofai/policies/` باسم ينتهي بـ `policies.js` أو `policies.mjs` أو `policies.ts` — تلك تحمل تلقائياً في نطاق المشروع والمستخدم — أو ثبّته بالمسار: -استخدم `instruct` عندما يمكن للوكيل تصحيح المسار بأمان. استخدم `deny` عندما يؤدي السماح بالإجراء إلى خلق خطر غير مقبول أو غير قابل للعكس. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - إصدارات السياسة هي مدخلات نشر غير قابلة للتغيير. يؤدي تحرير مسودة إلى إنشاء إصدار جديد؛ لا ينبغي أن يعيد كتابة الإصدار المعين بالفعل للآلات. - \ No newline at end of file +أعط كل سياسة اسماً فريداً عبر الاتفاقية والسياسات المخصصة والحزمة والسياسات المدارة من قبل Cloud. \ No newline at end of file diff --git a/docs/ar/policies/failure-behavior.mdx b/docs/ar/policies/failure-behavior.mdx index e666f018..6e590601 100644 --- a/docs/ar/policies/failure-behavior.mdx +++ b/docs/ar/policies/failure-behavior.mdx @@ -1,67 +1,69 @@ --- title: "سلوك الفشل" -description: "فهم ما يحدث عند عدم توفر تقييم السياسة أو مُحقِّق محلي." +description: "افهم ما يحدث عندما يكون تقييم السياسة أو مشترك الأداة المحلي غير متاح." icon: "shield-alert" --- -تم تصميم Failproof AI بحيث يكون فشل الإنفاذ مرئياً بدلاً من السماح الصامت بالعمل المحفوف بالمخاطر. +تم تصميم Failproof AI بحيث يكون فشل الإنفاذ مرئيًا بدلاً من السماح صامتًا بعمل محفوف بالمخاطر. -## تشخيص كتلة فشل مغلقة +## تشخيص كتلة الفشل المغلقة - + 1. انتقل إلى **Admin → enforcement** وافتح الجهاز. - 2. تحقق من آخر تسجيل دخول له والنشر المعين والنشر المُبلغ عنه. + 2. تحقق من آخر فحص له والنشر المعين والنشر المبلغ عنه. 3. انتقل إلى **Observe → policy** وافتح جلسة القرار المرفوض. - 4. تأكد مما إذا كان السبب يُبلغ عن إمكانية الوصول إلى مُحقِّق أو عدم توافق الإصدار أو السياسة نفسها. + 4. أكد ما إذا كان السبب يشير إلى إمكانية الوصول إلى مشترك الأداة أو عدم التطابق الإصدار أو السياسة نفسها. - + ```bash failproofai config --status npm install -g failproofai@latest failproofai config ``` - إعادة تشغيل `failproofai config` يحدّث ويعيد تشغيل مُحقِّق بعد ترقية الحزمة. + إعادة تشغيل `failproofai config` يحدّث ويعيد تشغيل مشترك الأداة بعد ترقية الحزمة. -على جهاز تم تكوينه لاستخدام `failproofaid`، يكون المُحقِّق هو المُقيّم الوحيد. إذا كان غير قابل للوصول أو لم تطابق نسخة البروتوكول الخاصة به CLI، يفشل تقييم الخطاف بشكل مغلق. يتم رفض الإجراء برسالة توجه المشغّل إلى فحص مُحقِّق أو تحديثه. +على جهاز تم تكوينه لاستخدام `failproofaid`، مشترك الأداة هو المقيّم الوحيد. إذا كان غير قابل للوصول أو إصدار البروتوكول الخاص به لا يطابق واجهة سطر الأوامر، فإن تقييم hook يفشل بشكل مغلق. يتم رفض الإجراء مع سبب يوجه المشغل للتحقق من مشترك الأداة أو تحديثه. -قبل تكوين المُحقِّق، تقيّم الخطافات السياسات في العملية. بمجرد تسجيل تكوين المُحقِّق، لا يعود Failproof AI يرجع بصمت إلى مُقيّم ثانٍ عند فشل المُحقِّق. +قبل تكوين مشترك الأداة، يتم تقييم hooks للسياسات داخل العملية. بمجرد تسجيل تكوين مشترك الأداة، لا يعود Failproof AI يعود صامتًا إلى مقيّم ثاني عند فشل مشترك الأداة. -## الرد على قرار فشل مغلق +## الاستجابة لقرار الفشل المغلق 1. شغّل `failproofai config --status`. 2. إذا اختلفت الإصدارات، أعد تشغيل `failproofai config` بعد تحديث الحزمة. -3. إذا كان المُحقِّق غير قابل للوصول، افحص حالة الخدمة والسجلات المحلية. -4. استأنف عمل الوكيل فقط بعد التأكد من أن مسار تقييم السياسة معروف وسليم. +3. إذا كان مشترك الأداة غير قابل للوصول، تفقد حالة خدمته والسجلات المحلية. +4. استأنف عمل الوكيل فقط بعد التأكد من صحة مسار تقييم السياسة المعروف. - لا تُعد محاولة الإجراء المحظور بشكل متكرر. رد فشل مغلق يعني أن النظام لم يتمكن من إثبات أن الإجراء كان آمناً. + لا تحاول بشكل متكرر الإجراء المحظور. استجابة الفشل المغلق تعني أن النظام لم يتمكن من تأكيد أن الإجراء كان آمنًا. -## حزمة لن يتم تحميلها +## لن تحميل حزمة -الجهاز الذي تم إخباره بإنفاذ حزمة، ولا يستطيع تشغيلها، يرفضها بدلاً من المتابعة بصمت. المُحفّز هو **توقع مُسجّل**، وليس توقع فارغ أبداً: جهاز بدون حزم مثبتة يكون صامتاً، بينما حزمة تم إعلانها ولن يتم حلها — أو التي تسجل أقل مما يُعلنه البيان — ترفضها. +جهاز تم إخباره بفرض حزمة ولا يمكنه تشغيلها يرفض بدلاً من المتابعة بصمت. المحفّز هو **توقع مسجل**، وليس توقع فارغ أبدًا: جهاز لا يحتوي على حزم مثبتة يكون صامتًا، في حين أن حزمة يتم التصريح بها ولن يتم حلها - أو التي تسجل أقل مما يصرح به البيان - ترفض. -الرفض **ضيق**، بخلاف مُحقِّق غير قابل للوصول. مُحقِّق لا يمكن الوصول إليه يعني عدم حدوث أي تقييم على الإطلاق، لذا لا يمكن معرفة شيء آمن. حزمة لن يتم تحميلها لها مجموعة قابلة للعد من الحراسات المفقودة، لأن كل سياسة معلنة تحمل `match` خاصة بها — لذا ترفض فقط الأحداث والأدوات التي غطتها تلك السياسات، وكل شيء آخر يتقدم. +الرفض **محدود**، بخلاف مشترك أداة غير قابل للوصول. مشترك أداة لا يمكن الوصول إليه يعني عدم حدوث أي تقييم على الإطلاق، لذا لا يمكن معرفة شيء آمن. حزمة لن تحميل لها مجموعة معددة من الحراس المفقودين، لأن كل سياسة معلنة تحمل الخاص بها `match` - لذا فهي ترفض فقط الأحداث والأدوات التي غطتها تلك السياسات، وكل شيء آخر يستمر. -لا تحدث من أجل: +لا يتم تشغيله لـ: -- حزمة `observe`، التي تقيّم وتتجاهل بالبناء -- السياسات التي لم تأخذها أبداً، أو أطفأتها بشكل صريح -- حزمة لم يستقبلها المحمّل، حيث لا يمكن التمييز بين "لا تسجيلات" وتخطي مقصود +- حزمة `observe`، التي تقيّم وتتجاهل حسب البناء +- السياسات التي لم تأخذها أبدًا، أو أيقفتها بشكل صريح +- حزمة لم يستقبلها المحمل، حيث لا يمكن التمييز بين "لا توجد تسجيلات" وتخطي متعمد - توقف جلسة نشط -- انتهاء مهلة زمنية للتحميل، وهي عابرة — يجب ألا يؤدي لحظة واحدة من البطء إلى الرفض حتى يتدخل إنسان +- مهلة زمنية للتحميل، وهي مؤقتة - لا يجب أن لحظة واحدة بطيئة على القرص ترفض حتى يتدخل الإنسان -`UserPromptSubmit` **توجيهات** بدلاً من الرفض، بغض النظر عما أعلنته السياسة المفقودة. سيؤدي الرفض الشامل إلى أخذها معه وقفل الوكيل الذي يمكنه إصلاح المشكلة. +`UserPromptSubmit` **يأمر** بدلاً من الرفض، مهما كانت السياسة المفقودة تصرح به. الرفض الشامل سيأخذها معه ويقفلك خارج الوكيل الذي يمكنه إصلاح المشكلة. -### ماذا تفعل +### ما يجب فعله ```bash -failproofai pack list +failproofai policies ``` -يسمي أي حزمة مثبتة لن يتم تحميلها، ويقول السبب، والخروج بقيمة غير صفر. ثم أعد تثبيتها (`failproofai pack add `) أو أزلها (`failproofai pack remove `) — إزالتها تسحب التوقع، والرفض يتوقف معها. \ No newline at end of file +يعلم القائمة حزمة مثبتة يتم تسجيل تثبيتها أو digest يتحقق لم يعد صحيحًا، وتقول السبب. لا تستورد الحزمة، لذا واحدة التي تفشل فقط بمجرد تحميلها - تسجيل أقل مما يصرح به البيان - تُدرج كالمعتاد؛ الرفض أدناه هو ما يسمي ذاك. كلا الطريقتين، أعد تثبيتها (`failproofai policies add `) أو أزلها (`failproofai policies remove `) - إزالتها تسحب التوقع، والرفض يتوقف معها. + +ينسب الرفض نفسه إلى `pack/failproofai-pack-unavailable`، الذي يتفوق على السياسات التي تم تحميلها، لذا فإن استدعاء أداة محظور يسمي الحزمة المفقودة بدلاً من أي حارس باقٍ حدث لينطلق أولاً. \ No newline at end of file diff --git a/docs/ar/policies/local-configuration.mdx b/docs/ar/policies/local-configuration.mdx index f8144b95..50592799 100644 --- a/docs/ar/policies/local-configuration.mdx +++ b/docs/ar/policies/local-configuration.mdx @@ -1,55 +1,49 @@ --- title: "التكوين المحلي" -description: "التحكم في نطاق السياسة والمعاملات والملفات المخصصة وإعدادات Failproof AI على مستوى الجهاز." +description: "تحكم في نطاق السياسة والمعاملات والملفات المخصصة وإعدادات Failproof AI على مستوى الجهاز." icon: "file-cog" --- -يفصل Failproof AI بين اختيار السياسة وإعدادات الجهاز والخادم. يحافظ هذا على قابلية مراجعة اختيارات سياسة المستودع بينما تبقى بيانات الاعتماد وحالة الخادم خارج المستودع. +يحافظ Failproof AI على فصل ما يمكن للمستودع أن يلتزم به — توصيل الخطافات ومعاملات السياسة والسياسات المخصصة — عن حالة الجهاز مثل بيانات الاعتماد والحزم المثبتة والخادم. -## اختر نطاق السياسة +## اختر نطاقًا - - - شغّل `failproofai` بدون معاملات لفتح لوحة معلومات السياسة المحلية. اختر نطاق المستخدم أو المشروع أو المحلي قبل تفعيل سياسة بحيث يتم كتابة التغيير إلى ملف التكوين المقصود. +يقرر النطاق مكان توصيل الخطافات وملف التكوين الذي تكتب فيه المعاملات ومسارات السياسات المخصصة: - - **المستخدم** ينطبق على جميع المشاريع على هذا الجهاز. - - **المشروع** ينتمي إلى المستودع ويمكن إرساله. - - **محلي** يتجاوز مشروعًا واحدًا لمستخدم واحد ويجب أن يبقى في gitignore. +- **المستخدم** ينطبق على جميع المشاريع على هذا الجهاز. +- **المشروع** ينتمي إلى المستودع ويمكن الالتزام به. +- **محلي** يتجاوز مشروعًا واحدًا لمستخدم واحد ويجب أن يبقى معاملاً من قبل gitignore. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # wire hooks for this repository +failproofai policies --install --cli claude --scope user # or for every project on this machine +failproofai policies +``` - لا يدعم كل محرك النطاق المحلي. يرفض CLI نطاقًا لا يستطيع المحرك المختار تمثيله. - - +لا يدعم كل جهاز النطاق المحلي؛ يرفض CLI نطاقًا لا يمكن لجهاز التشغيل المختار تمثيله. + +سياسات الحزم التي تعمل **لا** تُحدد النطاق. يتم تسجيل المفتاح مع الحزمة المثبتة، لذا فإن `failproofai policies add ` يشغل سياسة على كامل الجهاز، مهما قال `--scope`. | النطاق | ملف تكوين السياسة | | --- | --- | -| مشروع | `/.failproofai/policies-config.json` | +| المشروع | `/.failproofai/policies-config.json` | | محلي | `/.failproofai/policies-config.local.json` | -| مستخدم | `~/.failproofai/policies-config.json` | +| المستخدم | `~/.failproofai/policies-config.json` | -يتم دمج السياسات المفعلة كاتحاد. معاملات السياسة تستخدم النطاق الأول الذي يحدد المعاملات لتلك السياسة، بالترتيب: مشروع → محلي → مستخدم. تستخدم مسارات السياسات المخصصة الصريحة النطاق الأول الذي يحددها. +معاملات السياسة تستخدم أول نطاق يحدد معاملات لتلك السياسة، بترتيب المشروع → محلي → المستخدم. مسارات السياسات المخصصة الصريحة تستخدم أول نطاق يحددها. -## كوّن معاملات السياسة +## قم بتكوين معاملات السياسة - - افتح السياسة في لوحة معلومات محلية، حرّر المعاملات المدعومة، وحفظ في النطاق المختار. شغّل إجراء وكيل يطابق وآخر لا يطابق، ثم افحص القرار في **Observe → policy**. + + افتح السياسة في لوحة التحكم المحلية وعدّل معاملاتها المدعومة وحفظ في النطاق المختار. قم بتشغيل إجراء وكيل متطابق وغير متطابق، ثم افحص القرار في **Observe → policy**. - حرّر `policies-config.json` للنطاق المختار، ثم شغّل `failproofai policies` لتسطيح أسماء السياسات أو مفاتيح المعاملات غير المعروفة. + عدّل `policies-config.json` للنطاق المختار، ثم قم بتشغيل `failproofai policies`: سيحذرك عن إدخال `policyParams` يسمي سياسة لا تحملها أي حزمة مثبتة. لا يفحص المفاتيح داخل الإدخال، لذا تحقق من تهجئتها مقابل الجدول أدناه. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ icon: "file-cog" +### المعاملات التي تقبلها سياسات Failproof AI + +تتحقق كل سياسة من أنواع معاملاتها الخاصة. + +| السياسة | المعامل | النوع والإفتراضي | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`؛ الإدخالات تحتوي على `regex` و `label` | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| محجوبات البنية التحتية | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`؛ `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + نمط السماح يوسع ما قد يفعله الوكيل. اختبر التجزئة الدقيقة وتباينات الأوامر على جهاز التشغيل الهدف قبل نشره عبر أسطول. + + ## افهم ملفات الجهاز -يحتوي `~/.failproofai` على ملفات منفصلة لحدود ثقة منفصلة: +`~/.failproofai` يحتوي على ملفات منفصلة لحدود الثقة المختلفة: | المسار | الغرض | | --- | --- | -| `config.json` | إعدادات الخادم والتدقيق والقياس عن بُعد غير السرية | -| `credentials.json` | بيانات اعتماد السحابة؛ مخزنة برمز إذن المالك فقط | -| `policies-config.json` | اختيار نطاق المستخدم المدمج والمعاملات والمسارات المخصصة الصريحة | -| `policies/` | سياسات اتفاقية المستخدم وتحفظات السياسة المدارة من السحابة | -| `hook-activity/` | سجل قرار السياسة المحلية | -| `state/` | ملف الخادم والصحة والإيقاف المؤقت وحالة وقت التشغيل | +| `config.json` | إعدادات الخادم وعدم السرية والتدقيق والقياس عن بعد | +| `credentials.json` | بيانات اعتماد السحابة؛ مخزنة بأذونات المالك فقط | +| `policies-config.json` | معاملات نطاق المستخدم ومسارات السياسات المخصصة الصريحة | +| `policies/` | سياسات اتفاقية المستخدم والحزم المثبتة وأي من سياساتها مشغلة وتخطيطات السياسة المدارة من السحابة | +| `hook-activity/` | سجل قرارات السياسة المحلية | +| `state/` | حالة الخادم والصحة والإيقاف المؤقت وحالة التشغيل | -استخدم `FAILPROOFAI_HOME` لنقل تخطيط الجهاز الكامل لحاوية أو اختبار معزول. لا تنقل دلائل الحالة الفردية بشكل مستقل. +استخدم `FAILPROOFAI_HOME` لنقل تخطيط الجهاز الكامل لحاوية أو اختبار معزول. لا تنقل مجلدات الحالة الفردية بشكل مستقل. - لا تُرسل `credentials.json`. أرسل تكوين سياسة المشروع وسياسات اتفاقية المشروع فقط بعد مراجعتها كرمز فرض. + لا تلتزم أبدًا بـ `credentials.json`. التزم بتكوين السياسة على مستوى المشروع وسياسات اتفاقية المشروع فقط بعد مراجعتها كرمز إنفاذ. \ No newline at end of file diff --git a/docs/ar/policies/overview.mdx b/docs/ar/policies/overview.mdx index 9be3a2c1..d33c2f97 100644 --- a/docs/ar/policies/overview.mdx +++ b/docs/ar/policies/overview.mdx @@ -1,63 +1,54 @@ --- title: "السياسات" -description: "راقب أو وجّه أو احجب إجراءات الوكيل قبل أن تتكرر حالة فشل معروفة." +description: "راقب أو وجّه أو احجب إجراءات الوكيل قبل تكرار فشل معروف." icon: "shield-check" --- -تقيّم السياسة حدث خطاف الوكيل وتُرجع أحد ثلاثة قرارات: +تقيّم السياسة حدث خطاف الوكيل وتعيد أحد ثلاثة قرارات: - `allow` يسمح بمتابعة الإجراء. -- `instruct` يعطي الوكيل توجيهات تصحيحية. +- `instruct` يعطي الوكيل إرشادات تصحيحية. - `deny` يحجب الإجراء مع سبب. -## استخدم أسطح السياسة الثلاثة +## مكان وجود السياسات - - - 1. انتقل إلى **Observe → policy** لتصفية وفحص قرارات السياسة من الجلسات. - 2. انتقل إلى **Admin → policy editor** لإنشاء وتحقق من صحة ونشر أو تعطيل أو فحص إصدارات غير قابلة للتغيير. - 3. انتقل إلى **Admin → enforcement** لتعيين الإصدارات والتأثيرات على الأجهزة. +| في لوحة التحكم | ما تفعله هناك | +| --- | --- | +| **Observe → policy** | راجع القرارات من جلسات حقيقية: أي سياسة طابقت، على أي جهاز، ولماذا | +| **Admin → policy editor** | اكتب سياسة، واختبرها بأثر رجعي ضد حركة المرور السابقة، وانشر نسخة غير قابلة للتغيير، وقارن الإصدارات في **library** | +| **Admin → enforcement** | ضع الإصدارات على الأجهزة في وضع المراقبة أو الفرض | - استخدم صفحة السياسة لفهم ما يطابق بالفعل قبل تأليف أو تغيير الإنفاذ. +محرر السياسة هو حيث يصبح الفشل قاعدة. صف وضع الفشل أو الصق مصدر السياسة في **compose**، واختبر المسودة بأثر رجعي ضد حركة المرور التي لديك بالفعل، ثم انشر نسخة: - ![صفحة السياسة تعرض مجاميع القرارات والسياسات المدارة محليًا والمدارة بواسطة السحابة.](/images/dashboard/policy-observe.png) +![عرض محرر السياسة مع هوية السياسة والصياغة بمساعدة الذكاء الاصطناعي والتحقق من الصحة والنشر والضوابط.](/images/dashboard/policy-editor.png) - محرر السياسة هو حيث تحول حالة الفشل إلى كود، وتتحقق منها، وتنشر إصدارًا غير قابل للتغيير. +على جهاز، `failproofai policies` يسرد كل شيء يفرضه هناك. `fp policies` و `fp fleet` يغطيان المحرر والفرض من محطة طرفية — انظر [Cloud CLI reference](/ar/reference/cloud-cli). - ![محرر السياسة المستخدم لإنشاء ونشر إصدار سياسة غير قابل للتغيير.](/images/dashboard/policy-editor.png) +## احصل على سياسة - يقوم الإنفاذ بعد ذلك بتعيين الإصدار المنشور وتأثيره (المراقبة أو الإنفاذ) للأجهزة. - - ![أسطول الإنفاذ الذي يعرض تغطية الأجهزة وإصدارات السياسة المعينة.](/images/dashboard/enforcement-fleet.png) - - تحقق من القرارات على صفحة السياسة بعد النشر بحيث تكون عروض التأليف والأسطول مرتبطة بنشاط الوكيل الفعلي. - - - استخدم `failproofai` لتثبيت التحقق من السياسة محليًا: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - استخدم `fp` للعثور على جلسات السحابة والأحداث التي تحتوي على قرارات السياسة. يبقى التأليف بواسطة السحابة ونشر الأسطول من سير عمل لوحة التحكم. - - - -للسياسات ثلاثة أسطح مميزة في Failproof AI: - -1. **حلل القرارات** في الجلسات والآلات الحسابية والتدقيقات. -2. **ألّف الإصدارات** باستخدام القواعد المدمجة أو الكود أو محرر السياسة. -3. **انشر وأنفذ** الإصدارات عبر الأجهزة المختارة. - -ابدأ من حالة فشل مؤكدة. عرّف أصغر حدث ومطابقة أداة تحددها، واختبر الأمثلة الشرعية وغير الآمنة، ثم راقب قبل الإنفاذ. +هناك طريقتان للحصول على واحدة. - - فعّل قاعدة تمت مراجعتها للمخاطر الشائعة المتعلقة بالأسرار والأصداف و Git والسحابة وسير العمل. + + دع Failproof AI يصيغ واحدة من نتيجة تدقيق، أو اكتب المصدر بنفسك، ثم راجع واحشره في المحرر. - - عبّر عن قرار خاص بسير العمل في JavaScript أو TypeScript. + + ركب حزمة سياسات Failproof AI لحالتك، أو حزمة مجتمعية من مركز السياسات، في أمر واحد. - \ No newline at end of file + + +## ثم شحنها + + + + اختبر المسودة بأثر رجعي ضد حركة المرور التي لديك بالفعل، وقم بتشغيلها ضد إجراء يجب أن توقفه وواحد يجب أن تسمح به — كل ذلك قبل النشر. انظر [Test a policy](/ar/policies/test). + + + ضع الإصدار على الأجهزة في وضع **observe**، اقرأ قراراتها، ثم افرضها. انظر [Deploy a policy](/ar/policies/deploy). + + + كل نشر هو نسخة جديدة غير قابلة للتغيير، لذا فإن النشر الذي يحجب العمل الصحيح يتم التراجع عنه بإعادة نشر الإصدار الجيد الأخير. انظر [Versions and rollback](/ar/policies/rollback). + + + +لمشاركة السياسات الخاصة بك مع فريق آخر، [انشرها كحزمة](/ar/policies/publish-a-pack). لمعرفة ما يحدث عندما لا يمكن تقييم السياسة على الإطلاق، انظر [Failure behavior](/ar/policies/failure-behavior). \ No newline at end of file diff --git a/docs/ar/policies/packs.mdx b/docs/ar/policies/packs.mdx index ffc55304..1c716360 100644 --- a/docs/ar/policies/packs.mdx +++ b/docs/ar/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "حزم السياسات" -description: "ثبّت مجموعة سياسات منشورة كإصدار GitHub، وأدِر ما تفرضه." +title: "استخدم حزمة سياسة" +description: "ادمج حزمة سياسة من Failproof AI لحالتك، أو حزمة مجتمع من مركز السياسات، واختر ما تفرضه." icon: "package" --- -الحزمة عبارة عن مجموعة سياسات منشورة كإصدار GitHub. أمر واحد يثبتها، يتم التحقق من قيم التجزئة الخاصة بالإصدار قبل تشغيل أي شيء، ويتم تسجيل الخلاصة حتى لا تتمكن الحزمة من التغيير على جهازك بعد ذلك. +الحزمة عبارة عن مجموعة من السياسات يتم نشرها كإصدار GitHub. أمر واحد يثبتها: يتم التحقق من قيم اختيار الإصدار قبل تشغيل أي شيء، ويتم تسجيل الخلاصة الخاصة بها بحيث لا يمكن أن تتغير الحزمة على جهازك فيما بعد. -## ثبّت سياسات Failproof AI +استعرض كل حزمة وكل سياسة في كل منها على [مركز السياسات](https://befailproof.ai/policy-hub/). هناك نوعان: + +- **حزم سياسة Failproof AI** — حزم جاهزة لحالات الاستخدام المحددة مسبقاً: ادمج واحدة وتعمل. [حزمة سياسة وكيل الترميز](https://befailproof.ai/policy-hub/failproofai/policies/) متاحة الآن، وستأتي حزم لحالات استخدام أخرى قريباً. +- **حزم السياسة المجتمعية** — سياسات كتبها المطورون لحالات الاستخدام الخاصة بهم ونشروها ليستخدمها أي شخص. + +## حزم سياسة Failproof AI + +### حزمة سياسة وكيل الترميز ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -هذا يثبت المجموعة التي ننشرها، من النسخة الموجودة داخل الحزمة — لذا فهي لا تحتاج إلى شبكة ولا يمكن أن تفشل خلف وكيل. خذ جزءًا منها: +تحتوي الحزمة على 38 سياسة وتشغل 10 منها التي يميزها البيان كآمنة للتفعيل دون إشراف؛ يتم إدراج الباقي لاختيارك. بعض الأكثر استخداماً، وما إذا كان `policies add` بسيطاً يشغلها: + +| السياسة | ما تفعله | مفعّلة افتراضياً | +| --- | --- | --- | +| `block-push-master` | يحجب الدفع المباشر للفروع المحمية | نعم | +| `block-env-files` | يحجب قراءة وكتابة ملفات `.env` | نعم | +| `protect-env-vars` | يحجب الأوامر التي تفرغ متغيرات البيئة | نعم | +| `block-sudo` | يحجب `sudo` ما لم تطابق نمط سماح | نعم | +| `block-curl-pipe-sh` | يحجب السكريبتات المنزلة الموجهة مباشرة إلى shell | نعم | +| `sanitize-*` (خمس سياسات) | الإبلاغ عن مفاتيح API، رموز Bearer، JWTs، المفاتيح الخاصة، وسلاسل الاتصال الموجودة في مخرجات الأداة | نعم | +| `block-rm-rf` | يحجب عمليات الحذف العودية الكارثية | لا | +| `block-force-push` | يحجب الدفع القسري | لا | +| `block-secrets-write` | يحجب عمليات الكتابة إلى ملفات بيانات الاعتماد والمفاتيح السرية | لا | +| `warn-destructive-sql` | ينبه على `DROP`، `TRUNCATE`، و`DELETE` بدون `WHERE` | لا | + +شغّل أي منها مطفأة بالاسم — `failproofai policies add block-rm-rf` — أو خذ الحزمة بأكملها باستخدام `--all`. انظر كل سياسة فيها، مجمعة حسب الفئة: ```bash -failproofai pack add core --policy block-rm-rf # واحدة أو عدة مفصولة بفواصل -failproofai pack add core --category dangerous-commands # فئة كاملة -failproofai pack add core --all # كل شيء فيها +failproofai policies show FailproofAI/policies ``` -يسرد `failproofai pack list` كل فئة توفرها الحزمة. +## حزم السياسة المجتمعية -## شاهد ما تحتويه الحزمة، قبل تثبيتها +ينشر المطورون حزماً لحالات الاستخدام التي واجهوها، و[مركز السياسات](https://befailproof.ai/policy-hub/) يسردها. حزمة السياسة المجتمعية منشورة من قبل مؤلفها، وليست مراجعة من قبل Failproof AI، لذا اقرأ ما تحتويه قبل تثبيتها: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -يسرد كل سياسة تحملها الحزمة، مجمعة حسب الفئة، يحدد أيها يقوم مؤلفها بتشغيلها افتراضيًا وأيها اختياري. يقرأ **البيان فقط** — القطعة الأساسية لا يتم تنزيلها أبدًا ولا يتم استيرادها، لذلك فإن الاطلاع على حزمة غريبة لا يمكنه تشغيل كود غريب. البيان لا يزال يتم التحقق منه مقابل `SHA256SUMS` الخاص بالإصدار، لذا فإن ما تقرأه هو ما سيتم تثبيته. - -`failproofai pack list` بدون مصدر يسرد الحزم المثبتة بالفعل هنا. +يسرد هذا كل سياسة تحتويها، مجمعة حسب الفئة، ويميز أي منها يشغلها المؤلف افتراضياً. يقرأ **فقط البيان** — لا يتم تنزيل أو استيراد الأداة الأساسية، لذا النظر إلى حزمة الغريب لا يمكن أن يشغل كود الغريب. يتم التحقق من البيان لا يزال ضد `SHA256SUMS` الخاص بالإصدار، لذا ما تقرأه هو ما سيتم تثبيته. -## ثبّت حزمة شخص آخر +ثم ثبتها: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -أي من هذه يعمل — الصق أيهما لديك: +أي من هذه تعمل — الصق أيهما لديك: | المصدر | النتيجة | | --- | --- | -| `acme/support-agent` | أحدث إصدار، **مثبت** على الوسم الدقيق الذي تم حله | +| `acme/support-agent` | أحدث إصدار، **مثبتة** على الوسم الدقيق الذي تم حله | | `acme/support-agent@v2.1.0` | هذا الإصدار | -| `github:acme/support-agent@v2.1.0` | نفسه، مكتوب صراحة | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | نفسه، منسوخ من متصفح | +| `github:acme/support-agent@v2.1.0` | نفس الشيء، مكتوب بصراحة | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | نفس الشيء، منسوخ من المتصفح | -عدم تسمية وسم يثبت أحدث إصدار **ويثبته**، ثم يخبرك بالوسم الذي اختاره. ما يتم تسجيله يسمي دائمًا إصدارًا واحدًا بالضبط، لذا فإن إعادة التثبيت لا يمكنها الانحراف. +عدم تسمية وسم يثبت أحدث إصدار **ويثبته**، ثم يخبرك بأي وسم اختاره. ما يتم تسجيله يسمي دائماً إصدار واحد بالضبط، لذا لا يمكن للإعادة أن تنجرف. -## خذ جزءًا من حزمة +## خذ جزءاً من الحزمة -افتراضيًا تحصل على الإعدادات **الخاصة** بالحزمة — السياسات التي وضع علامة عليها مؤلفها كآمنة للتشغيل دون مراقبة — وليس كل ما تحتويه. +افتراضياً، تحصل على **الافتراضيات الخاصة** بالحزمة — السياسات التي وضع علامة عليها المؤلف كآمنة للتفعيل دون إشراف — وليس كل ما تحتويه. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # واحدة أو عدة مفصولة بفواصل +failproofai policies add FailproofAI/policies --category dangerous-commands # فئة كاملة +failproofai policies add FailproofAI/policies --all # كل شيء فيها ``` -يتم دمج `--category` و `--policy` كاتحاد (`--only` يُقبل كمرادف لـ `--policy`). إعادة التثبيت بإصدار أحدث تحافظ على اختيارك بدلاً من إعادة تشغيل الباقي. +`--category` و `--policy` يجتمعان كاتحاد (`--only` يُقبل كمرادف لـ `--policy`). عندما تكون الحزمة مثبتة بالفعل، تضيف العلامات إلى ما لديك، وإعادة إضافتها بدون علامة وبدون طرفية — للترقية، مثلاً — تحافظ على اختيارك كما هو. في طرفية بدون علامة، `add` يفتح المنتقي بدلاً من ذلك، مع وضع علامة مسبقة بافتراضيات المؤلف، وما تضع عليه علامة يستبدل اختيارك. -## أدِر ما هو مشغّل +## أدر ما هو مشغول ```bash -failproofai policies # كل مصدر في قائمة واحدة، الحزم مضمنة -failproofai pack list # الحزم فقط، مجمعة حسب الفئة +failproofai policies # كل مصدر في قائمة واحدة، الحزم مشمولة +failproofai policies add block-rm-rf # شغّل سياسة واحدة failproofai policies --uninstall block-refunds # أطفئ سياسة حزمة واحدة -failproofai policies --install block-refunds # وأعدها للتشغيل -failproofai pack remove acme/support-agent +failproofai policies --install block-refunds # وعودة +failproofai policies remove acme/support-agent # أزل الحزمة ``` -الاسم الحر يعني **المدمج** عندما يكون موجودًا بهذا الاسم. اسم نسخة الحزمة صراحة عندما تحتاج إلى: +تشغيل سياسة حزمة أو إطفاؤها ينطبق على الجهاز بأكمله: يتم تسجيل المفتاح مع الحزمة المثبتة، وليس في تكوين المشروع، مهما قال `--scope`. + +الاسم بدون شرطة مائلة هو سياسة؛ أي شيء يحتوي على واحدة هو مصدر حزمة. الاسم العاري يحل إلى الحزمة المثبتة التي تعلنها. عندما تعلن حزمتان مثبتتان نفس الاسم، اسم الاسم الذي تقصده: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -إذا كانت حزمة تشحن سياسة يكون اسمها أيضًا **مدمج مُفعّل**، يعمل المدمج ويتم تخطي نسخة الحزمة — وإلا سيتم تقييم نفس الحماية مرتين. أطفئ المدمج لاستخدام نسخة الحزمة بدلاً من ذلك. - - -## من أين تأتي سياسات Failproof AI - -`core` يقرأ النسخة المُدرجة في حزمة npm. نفس المجموعة منشورة كإصدار GitHub، وهو ما تثبتها إذا كنت تريد إصدارًا معينًا: - -```bash -failproofai pack add core # من هذه الحزمة، بدون شبكة -failproofai pack add FailproofAI/policies # نفس المجموعة، من إصدار GitHub الخاص بها -``` +الأنطاقات والمعاملات والملفات التي تكتبها هذه الأوامر مغطاة في [التكوين المحلي](/ar/policies/local-configuration). -## ما الذي يوفره التحقق من السلامة وما لا يوفره +## ما تشتريه سلامة التكامل وما لا تشتريه -`SHA256SUMS` يشحن في نفس الإصدار مع القطعة، لذا فهو **ليس** توقيعًا ولا يثبت أي شيء عن من نشره. ما يثبته هو أن البايتات هي تلك التي نشرها هذا الإصدار — وبسبب تسجيل الخلاصة عند إضافة الحزمة والتحقق منها مجددًا قبل كل استيراد، لا يمكن للحزمة تغيير ما تحته على جهازك. مستودع يعيد وضع علامات أو يستبدل أصلًا يتوقف عن التحميل بدلاً من تشغيل شيء آخر بصمت. +`SHA256SUMS` يأتي في نفس الإصدار مثل الأداة، لذا فهو **ليس** توقيعاً ولا يثبت أي شيء عن من نشره. ما يثبته هو أن البايتات هي التي نشرها هذا الإصدار — وبسبب تسجيل الخلاصة عند إضافة الحزمة وإعادة التحقق منها قبل كل استيراد، لا يمكن لحزمة أن تتغير على جهازك فيما بعد. مستودع يعيد وسم أو يستبدل أصلاً يتوقف عن التحميل بدلاً من تشغيل شيء آخر بهدوء. -في وقت التثبيت، يتم أيضًا **استيراد الحزمة مرة واحدة** والتحقق من بيانها. تُرفض حزمة لا يمكن تحليل قطعتها أو التي تسجل شيئًا غير ما تعلنه قبل تفعيل أي شيء — بدلاً من التثبيت بنظافة والفشل في استدعاء أداتك التالي. +في وقت التثبيت، يتم أيضاً **استيراد الحزمة مرة واحدة** والتحقق منها ضد بيانها الخاص. تُرفض حزمة لا يحلل أداتها أو التي تسجل شيئاً آخر غير ما تعلنه قبل تفعيل أي شيء — بدلاً من التثبيت بنظافة والفشل في استدعاء الأداة التالي. -## عندما لن تحمل الحزمة +## عندما لن تُحمّل حزمة -حزمة أُخبرت هذه الآلة بفرضها ولا يمكنها التشغيل **ترفض** الأحداث التي غطتها سياساتها المفقودة، بدلاً من السماح بها بصمت. انظر [سلوك الفشل](/ar/policies/failure-behavior). `failproofai pack list` يسمي أي حزمة في تلك الحالة ويخرج برقم غير صفري. +حزمة أُخبر هذا الجهاز بفرضها ولا يمكن تشغيلها **تنكر** الأحداث التي غطتها سياساتها المفقودة، بدلاً من السماح بها بهدوء — مثل `pack/failproofai-pack-unavailable`، والذي يتفوق على السياسات التي تحملت بحيث يُعزى الإنكار إلى الحزمة المفقودة بدلاً من أي حارس يحدث أن يطلق أولاً. الاستثناء هو `UserPromptSubmit`، الذي يوجه بدلاً من ذلك: الإنكار هناك قد يقفلك من الوكيل الذي تحتاجه لإصلاحه. انظر [سلوك الفشل](/ar/policies/failure-behavior). ## غير متصل والمرايا | المتغير | التأثير | | --- | --- | | `FAILPROOFAI_NO_DOWNLOAD=1` | يرفض الجلب؛ الحزم المثبتة بالفعل تستمر في الفرض | -| `FAILPROOFAI_PACK_BASE_URL` | يوجه جلب الحزم إلى مرآة بدلاً من `github.com` | +| `FAILPROOFAI_PACK_BASE_URL` | يوجه جلب الحزمة إلى مرآة بدلاً من `github.com` | -نشر حزمتك الخاصة: انظر [انشر حزمة](/ar/policies/publish-a-pack). \ No newline at end of file +لمشاركة سياساتك الخاصة بهذه الطريقة، انظر [نشر حزمة سياسة](/ar/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/ar/policies/publish-a-pack.mdx b/docs/ar/policies/publish-a-pack.mdx index 048637e7..31033955 100644 --- a/docs/ar/policies/publish-a-pack.mdx +++ b/docs/ar/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "نشر حزمة" -description: "شحن سياساتك الخاصة كإصدار GitHub يمكن لأي شخص تثبيته." +title: "نشر مجموعة سياسات" +description: "شحن سياساتك الخاصة كإصدار GitHub يمكن لأي شخص تثبيتها." icon: "upload" --- -الحزمة عبارة عن ثلاثة ملفات مرفقة بإصدار GitHub. يكتب `failproofai pack build` جميعها الثلاثة من ملف سياسة لديك بالفعل. +مجموعة السياسات تتكون من ثلاث ملفات مرفقة بإصدار GitHub. أمر `failproofai publish` يكتب جميع الملفات الثلاث من ملفات السياسات أمامه، ينشئ الإصدار، ويرفعها. ## 1. اكتب السياسات -ملف واحد، باستخدام نفس واجهة برمجية التطبيقات كأي سياسة مخصصة. هناك حقلان إضافيان مهمان للحزمة: +ابدأ من شيء يعمل بالفعل بدلاً من قالب فارغ: + +```bash +failproofai publish --init +``` + +هذا يسأل عن اسم المجموعة، يكتب `.mjs`، ثم يتوقف — لا شبكة، لا git، لا شيء منشور. الملف الذي يكتبه هو سياسة واحدة تحجب بالفعل `git push --force`. يرفض استبدال الملف الموجود. + +السياسات تستخدم نفس واجهة برمجية التطبيقات مثل أي سياسة مخصصة. حقلان إضافيان مهمان للمجموعة: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` افتراضيًا **false** عند حذفه. يؤدي `failproofai pack add` بسيط إلى تشغيل فقط ما حددته — تثبيت كل سياسة من شخص غريب دون مراقبة ليس قرارًا يجب على المثبِّت أن يتخذه نيابة عن مستخدمه. +`defaultEnabled` يُعيّن افتراضياً إلى **false** عندما تحذفه. أمر `failproofai policies add` البسيط يفعّل فقط ما وسّمته — تثبيت كل السياسات من غريب بدون مراقبة ليس قراراً يجب على المثبّت أن يتخذه نيابة عن المستخدم. + +اكتب أي عدد من الملفات تريده؛ ملف واحد لكل فئة يبدو جيداً. كل ملف في المجلد الذي يسجل السياسات سيتم دمجه في الحزمة الوحيدة التي تحتاجها. -يجب أن يكون الإدخال **ملف واحد مكتفٍ بذاته**. يتم تثبيت الإدخال فقط برقم معالجة التلخيص، لذا فإن الحزمة التي تستورد ملفات محلية لا يمكنها بصدق المطالبة بأن المعالجة تغطي ما يعمل. قم بالدمج أولاً (`esbuild` أو `bun build` أو `rollup`) وأنشئ الحزمة من الحزمة المدمجة — يرفض `pack build` الاستيراد المحلي بدلاً من شحن وعد لا يمكنه الوفاء به. + التجميع يتطلب **bun**. بدونه، استمر مع ملف مستقل واحد. على أي حال، الملف المدخل المنشور يجب ألا يستورد ملفات محلية في وقت التثبيت: فقط الملف المدخل له digest مثبت، لذا المجموعة التي تصل إلى أشقاء لا تستطيع بصراحة المطالبة بأن الـ digest يغطي ما يعمل — و `publish` يرفضها بدلاً من شحن وعد لا تستطيع الوفاء به. -## 2. بناء أصول الإصدار +## 2. جرّبها هنا أولاً + +قبل أن يراها أي شخص آخر، فرّض الملف على هذا الجهاز: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +أي مسار، أي اسم ملف. اطلب من وكيلك أن يفعل الشيء الذي حجبته وشاهده يتم رفضه. لا شيء منشور وأحد آخر لا يتأثر. يغطي [اختبار سياسة](/ar/policies/test) الباقي: الحالة الشرعية التي يجب أن تسمح بها، والمدخلات التي تكسرها. + +## 3. انشرها + +```bash +failproofai publish ``` -يكتب ثلاثة ملفات، ويتحقق من صحة كل سياسة باستخدام **قواعد محمل التحميل الخاصة به** أولاً — بحيث تفشل الحزمة التي قد لا تثبت أبدًا هنا، حيث يمكنك إصلاحها: +يعرّف حيث ينشر، ما يجب دمجه وما إصدار لتسميته، ويسأل فقط عندما لا شيء في المستودع يخبره. بالترتيب، توقف قبل إنشاء إصدار إذا كان هناك خطأ: + +1. يجد ملفات السياسات هنا بـ **المحتوى** — تلك التي تستورد `failproofai` وتستدعي `customPolicies.add` — بدلاً من اسم الملف، لذا يجد `guards.mjs` ويتجاهل `policies.mjs` غير الصلة. لا ينحدر إلى المجلدات الفرعية، لذا لا يتم التقاط fixture اختبار بالصدفة. +2. يقرأ المستودع من `git remote get-url origin`، في **مجلد الملف** بدلاً من مجلدك، ويحدد الإصدار. +3. يجد بيانات اعتمادك: `GITHUB_TOKEN`، `GH_TOKEN`، أو `gh auth login`. يحتاج إلى كتابة الإصدار وليس أكثر، ولا يتم طباعته أبداً. +4. ينشئ المستودع إذا لم يكن موجوداً. هذا يحدث قبل البناء، لذا المجموعة المرفوضة في الخطوة التالية يمكن أن تترك مستودع جديد بدون إصدار فيه. +5. يبني الأصول الثلاثة، يتحقق منها مع **قواعد محمّل السياسات الخاصة** — نفس الكود الذي يقرر ما قد يثبّت على جهاز الغريب — لذا المجموعة التي لا تستطيع التثبيت أبداً تفشل هنا، حيث تستطيع إصلاحها. +6. ينشئ أو يعيد استخدام الإصدار ويرفع، يستبدل الأصول بنفس الاسم. | الملف | ما هو | | --- | --- | -| `failproofai-pack.json` | البيان: المعرّف والإصدار والتأثير وإدخال واحد لكل سياسة | -| `failproofai-pack.mjs` | إدخالك، كما هو | -| `SHA256SUMS` | ` ` للآخريْن | +| `failproofai-pack.json` | البيان: المعرّف، الإصدار، التأثير، وإدخال واحد لكل سياسة | +| `failproofai-pack.mjs` | الملف المدخل المجمّع لديك | +| `SHA256SUMS` | ` ` للاثنين الآخرين | -مرفوضة في وقت البناء: معرّف ليس `publisher/name`، اسم سياسة يحتوي على `/`، سياسة تصرح `alwaysOn`، `description` أو `category` أو `match` مفقودة، إدخال لا يسجل أي شيء، وإدخال يستورد ملفات محلية. +أسماء الأصول ثابتة — إنها ما يبني واجهة سطر أوامر المستهلك عناوين URL منها، بدون استدعاء واجهة برمجية وبدون اكتشاف. -## 3. أرفقها بإصدار +مرفوضة في وقت البناء: معرّف ليس `publisher/name`، اسم سياسة يحتوي على `/`، سياسة تعلن `alwaysOn`، `description`، `category` أو `match` مفقودة، ملف مدخل لا يسجل شيئاً، وملف مدخل يستورد ملفات محلية. -ضع علامة على الإصدار بنفس الإصدار الذي أنشأته، وأرفق جميع الملفات الثلاثة كأصول إصدار: +تجاوز أي شيء قررته: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -يمكن لأي شخص الآن تثبيته: +`--id` يحدد معرّف المجموعة عندما يجب أن يختلف عن المستودع، `--tag` يحدد علامة الإصدار، `--notes` يستبدل ملاحظات الإصدار المُنتجة — وهي حيث `policies show --releases` تقرأ أعداد كل إصدار والتزام من — `--out` يختار حيث الأصول مكتوبة (افتراضي `dist-pack`)، و `--dry-run` يبنيها بدون نشر ولا يحتاج بيانات اعتماد. -```bash -failproofai pack add acme/support-agent -``` +يمكن لأي شخص الآن تثبيتها مع `failproofai policies add acme/support-agent`. انظر [مجموعات السياسات](/ar/policies/packs) لتثبيت إصدار والأخذ بجزء فقط من واحدة. + +### أدرجها في مركز السياسات -أسماء الأصول ثابتة — وهي ما ينشئه CLI المستهلك من عناوين URL، بدون استدعاء API وبدون اكتشاف. +أضف موضوع `failproofai-policies` إلى المستودع على GitHub. لا توجد نموذج تقديم ولا قائمة انتظار موافقة: زاحف [مركز السياسات](https://befailproof.ai/policy-hub/) يلتقط المستودع في الممر التالي. الموضوع يضعه فقط قيد الدراسة — ما يدرجه هو إصدار بيانه يتحقق ضد `SHA256SUMS` الخاص به ويُحلل تحت نفس القواعد التي تستخدمها واجهة سطر الأوامر، وهو بالضبط ما `failproofai publish` ينتجه. + +## كيفية تحديد الإصدار + +الإصدار هو **الـ commit الذي تنشر منه** — SHA القصير له، اثنا عشر حرفاً: `a1b2c3d4e5f6`. لا شيء لاختياره ولا شيء للزيادة، والإصدار يسمي بالضبط حيث جاءت البايتات، لذا نشر نفس المصدر مرتين يعطي نفس الإصدار. + +يتم قراءته من الشجرة أمامك، ليس أبداً من إصدارات المستودع، لذا نسخة طازجة وجهاز معزول الهواء يحسبان نفس الإجابة بدون السؤال GitHub عما حدث قبل. + +لأن الإصدار يسمي commit، هذا commit يجب أن يكون موجوداً. في محطة طرفية، `publish` يصنعه لك: يهيئ مستودع عندما لا يكون هناك واحد، والتزامات ملفات السياسات المتغيّرة قبل البناء. يرفض بدلاً من ذلك — يسمي `--version` كطريقة للخروج — عندما يعمل بدون محطة طرفية (التزام مصنوع على عداء CI لن يكون موجوداً في مكان آخر)، عندما ملفات أخرى غير السياسات لم تُلتزم، أو في checkout بدون التزامات بعد. علامة على `HEAD` تفوز على SHA — شخص وسّم `v1.2.0` قال ما هذا الإصدار. + +SHA لا يحمل ترتيباً من تلقاء نفسه، لذا استخدم `failproofai policies show / --releases` لرؤية أي إصدار جاء أولاً — الأحدث في الأعلى. ## شحن إصدار جديد -قم بالبناء باستخدام `--version` الجديد، ضع علامة على إصدار جديد، وأرفق الأصول الثلاثة مرة أخرى. يقوم المستهلكون بتشغيل نفس `pack add` والاحتفاظ بأي مجموعة فرعية اختاروها؛ السياسة التي أوقفوها تبقى معطلة عبر الترقية. +التزم التغيير وشغّل `failproofai publish` مرة أخرى — الالتزام الجديد هو الإصدار الجديد. المستهلكون يشغّلون نفس `failproofai policies add`. بدون محطة طرفية، أو مع علامة اختيار، يبقون على المجموعة الجزئية التي اختاروها وسياسة أطفأوها تبقى مطفأة؛ في محطة طرفية بدون علامة، يفتح المختار مع تحديد مسبق بقيمك الافتراضية وإجابتهم تستبدل اختيارهم. -تغيير **اسم** السياسة هو تغيير كبير: الجهاز الذي أوقفها يوقف اسمًا لم يعد موجودًا، والاسم الجديد يأتي في أي `defaultEnabled` يقول. +تغيير **اسم** سياسة هو تغيير كسر: جهاز كان قد أطفأه يطفئ اسماً لا يعود موجوداً، والاسم الجديد يصل بأي `defaultEnabled` يقول. ## ما يثق به مستخدموك -`SHA256SUMS` يعيش في نفس الإصدار مثل الأصل، لذا فإنه يثبت أن البايتات هي تلك التي نشرتها — وليس من أنت. أي شخص يمكنه الكتابة إلى المستودع يمكنه كتابة كلا الملفين. حماية مستخدميك هي أن المعالجة يتم تثبيتها عند التثبيت، بحيث لا يمكن تغيير ما شحنته من تحتهم بعد ذلك. +`SHA256SUMS` يعيش في نفس الإصدار مثل الأصل، لذا يثبت البايتات هي تلك التي نشرتها — ليس من أنت. أي شخص يمكنه الكتابة إلى المستودع يمكنه كتابة كلا الملفات. حماية مستخدميك هي أن الـ digest مثبت عند التثبيت، لذا ما شحنته لا يمكنه التغيير تحتهم بعد ذلك. + +انشر من مستودع تتحكم في الوصول للكتابة فيه، وتعامل مع إصدار مجموعة مثل نشر حزمة. -انشر من مستودع يتحكم في الوصول الكتابي إليه، وتعامل مع إصدار حزمة مثل نشر حزمة. +المستودع يجب أن يكون أيضاً **عام**. عمليات التثبيت HTTPS مجهولة بدون بيانات اعتماد لتقديمها، لذا مستودع خاص موجود يتم رفضه قبل أي شيء مبني أو مرفوع، وواحد `publish` ينشئ عام لنفس السبب. `--allow-private` يتجاوز ذلك لشخص يسلّم الملفات الثلاثة بطريقة أخرى، ويقول بصراحة أن لا `policies add` يمكنه الوصول إليها. فقط الإصدار يهم: عمليات التثبيت تقرأ `releases/download//` ولا تلمس شجرة git الخاصة بك. -## لاحظ قبل أن تفرض +## لاحظ قبل أن تفرّض -قد يصرح البيان `"effect": "observe"`. هذه السياسات تعمل ويتم **تسجيل أحكامها والتخلص منها** — لا شيء مسدود. إنها الطريقة لقياس قاعدة جديدة مقابل حركة المرور الحقيقية قبل أن تتمكن من مقاطعة عمل أي شخص. +البيان قد يعلن `"effect": "observe"` — `failproofai publish --effect observe` هو ما يحدده. تلك السياسات تعمل وأحكامها **مسجلة ومرفوضة** — لا شيء محجوب. إنها الطريقة لقياس قاعدة جديدة ضد حركة حقيقية قبل أن تستطيع قطع عمل أي شخص. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/ar/policies/rollback.mdx b/docs/ar/policies/rollback.mdx index acecf62b..c8bcfa14 100644 --- a/docs/ar/policies/rollback.mdx +++ b/docs/ar/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "التراجع عن النشر" -description: "استعادة نشر سياسة معروف عند حدوث اضطراب في عمل الوكيل الصحيح." +title: "الإصدارات والعودة للإصدار السابق" +description: "كل نشر هو إصدار ثابت، لذا يمكن التراجع عن أي نشر يعطل عمل الوكلاء الصحيح بإعادة نشر آخر إصدار جيد." icon: "rotate-ccw" --- -يغيّر التراجع عن النشر النسخة المنشورة أو يزيل تعيين السياسة؛ لكنه لا يمحو سجل القرارات الذي يشرح الحادثة. +إصدار السياسة المنشور لا يتغير أبداً. عند تعديل السياسة والنشر مرة أخرى، يتم إنشاء إصدار جديد؛ لا يتم إعادة كتابة الإصدار الموجود بالفعل على الأجهزة. هذا ما يجعل العودة للإصدار السابق آمنة: آخر إصدار جيد لا يزال موجوداً، بكل بايت منه، والعودة للإصدار السابق لا تمحو سجل القرارات الذي يشرح ما حدث خطأ. -## التراجع عن نشر على آلة +## البحث عن إصدار - 1. انتقل إلى **Admin → enforcement**، وقم بتوسيع الآلة المتأثرة، وحدد مجموعة السياسات الموثوقة الأخيرة لها. - 2. اختر **edit**، واستعد تلك الإصدارات والتأثيرات، وطبّق النشر الجديد. - 3. انتظر تسجيل الدخول للآلة، ثم تحقق من النشر المبلّغ عنه. - 4. افتح **Observe → policy** والجلسات المتأثرة لتأكيد عدم حجب العمل الصحيح. + انتقل إلى **Admin → policy editor** وافتح **library** لمقارنة إصدارات السياسة أو تعطيل أحدها. + + + ```bash + fp policies list # كل إصدار سياسة + fp policies show # إصدار واحد، مع مصدره + ``` + + + +## العودة للإصدار السابق على جهاز + + + 1. انتقل إلى **Admin → enforcement**، وقم بتوسيع الجهاز المتأثر، وحدد آخر مجموعة سياسات معروفة الجودة. + 2. اختر **edit**، استعد تلك الإصدارات والمزايا، وطبق النشر الجديد. + 3. انتظر تحديث الجهاز، ثم تحقق من النشر المُبلَّغ عنه. + 4. افتح **Observe → policy** والجلسات المتأثرة للتأكد من أن العمل الصحيح لم يعد محظوراً. - - التراجع عن نشر السحابة هو سير عمل لوحة تحكم. استخدم الحالة المحلية للتأكد من وصول النشر المصحح إلى الآلة: + + كل نشر لجهاز هو جيل مرقّم. اعرض قائمتها، ثم أعد تفعيل واحد: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - يوقف `failproofai config --pause` السياسات المدمجة والمخصصة وسياسات الاتفاقية لجلسة محلية واحدة. لا يوقف السياسات المدارة من قبل السحابة، لذا فهو ليس حلاً بديلاً لنشر سحابة سيء. + `rollback` ينشئ جيلاً جديداً يحمل المجموعة القديمة بدلاً من إعادة تعيين العداد، لذا يبقى السجل إضافياً فقط، ويرفض جيلاً يسمي سياسة تم تعطيلها أو حذفها. يحتاج إلى جلسة موقعة بـ `policies:write`. `fp fleet diff ` يعرض ما كان مقصوداً مقابل ما طبقه الجهاز — يقرأ كـ `behind` حتى يستفسر الجهاز مرة أخرى — وعلى الجهاز نفسه، `failproofai policies` يعرج النشر الذي يعمل عليه. -## متى يتم التراجع عن النشر +## إزالة سياسة واحدة من كل جهاز + +```bash +fp policies disable # إزالتها من كل نشر يحملها +fp policies enable # إعادتها +``` + +كل واحدة تنشئ جيلاً جديداً على كل نشر تلمسه. العودة للإصدار السابق لأحد هذه الأجيال ليس كيف تتراجع عن `disable`، على الرغم من — `rollback` يرفض جيلاً يسمي سياسة معطلة، وكل جيل من قبل تعطيل السياسة يسمي هذه. `fp policies enable` هو الطريق للعودة، وينشئ جيله الخاص بدوره. + +## العودة إلى حزمة + +الحزمة مثبتة في الإصدار الذي قمت بتثبيته، لذا العودة للإصدار السابق تعني تثبيت إصدار سابق: + +```bash +failproofai policies show FailproofAI/policies --releases # كل إصدار نشره، وأيها موجود هنا +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # دبّس هذا +``` + +بدون طرفية، أو مع `--policy` أو `--category` أو `--all`، إعادة الإضافة تحافظ على المجموعة الفرعية التي اخترتها. في طرفية بدون أي منها، تفتح محدد التحديد مع إزالة اختيار إعدادات المؤلف الافتراضية، وما تختاره يحل محل اختيارك — لذا أعد اختيار ما كان لديك. + +## متى تعود للإصدار السابق -- تحجب السياسة إجراء إنتاج متوقع. -- حجم التطابق أعلى بشكل ملموس مما توقعه الانتشار المرصود. -- تعتمد السياسة على حقول لا توفرها عملية التكامل. -- تغيّر النسخة الجديدة السلوك خارج نطاق وضع الفشل المقصود. +- سياسة تحظر إجراءً إنتاجياً متوقعاً. +- حجم المطابقة أعلى بشكل ملموس من ما تنبأت به عملية النشر المرصودة. +- سياسة تعتمد على حقول لا توفرها التكامل. +- نسخة جديدة تغير السلوك خارج وضع الفشل المقصود. -بعد التراجع عن النشر، افتح الجلسات المتأثرة وحدد الحالة التي تسببت في الإيجابية الخاطئة. أنشئ نسخة جديدة، واختبر الحالات غير الآمنة والمشروعة، ثم كرر مرحلة المراقبة. +بعد العودة للإصدار السابق، افتح الجلسات المتأثرة وجد الشرط وراء الإيجابية الخاطئة. نشر نسخة جديدة، [اختبر](/ar/policies/test) الحالة غير الآمنة والشرعية، وراقبها مرة أخرى قبل الإنفاذ. - يمكن أن يكون إيقاف التطبيق مناسباً أثناء حادثة، لكنه يوسع التعرض لكل سياسة نشطة في هذا النطاق. فضّل التراجع عن نسخة السياسة المحددة عند الإمكان. + `failproofai config --pause` توقف السياسات المحلية لجلسة واحدة وليس أبداً التي يديرها Cloud، لذا ليست طريقة للخروج من نشر Cloud سيء. الإيقاف المؤقت أيضاً يوسع التعرض لكل سياسة في نطاقه؛ فضّل العودة للإصدار السابق من الإصدار الوحيد الذي يسيء التصرف. \ No newline at end of file diff --git a/docs/ar/policies/test.mdx b/docs/ar/policies/test.mdx new file mode 100644 index 00000000..26bd7dcd --- /dev/null +++ b/docs/ar/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "اختبار سياسة" +description: "قم بالاختبار العكسي لمسودة ضد حركة المرور التي لديك بالفعل، وأثبت أنها توقف ما يجب إيقافه وتسمح بما يجب السماح به، قبل أن تفرضها أي آلة." +icon: "flask-conical" +--- + +اختبر كل سياسة بطريقتين: ضد حركة المرور التي أنتجتها وكلاؤك بالفعل، وضد إجراء شرعي يجب أن تسمح به. السياسة التي لم ترَ سوى الحالة غير الآمنة لم تُختبر. + +## الاختبار العكسي للمسودة + + + + محرر السياسة يعيد تشغيل مسودة ضد الاستدعاءات التي أجرتها أسطولك بالفعل، قبل نشرها. + + 1. افتح المسودة في **Admin → policy editor**. يؤكد المحرر أنها تحلل كـ JavaScript. + 2. في **backtest**، اختر الوكلاء ونطاق الوقت الذي تريد إعادة تشغيله — **كل الوكلاء** و**30d** بشكل افتراضي — واترك آخر مرشح على **everything** ما لم تريد تضييقه. + 3. اختر **run backtest**. + + ![لوحة الاختبار العكسي أسفل مسودة تحلل كـ JavaScript، مع مرشحاتها الثلاثة وإجراء تشغيل الاختبار العكسي، أعلى إصدار النشر.](/images/dashboard/policy-backtest.png) + + النتيجة هي ما كانت ستفعله المسودة لتلك الاستدعاءات — بما في ذلك عدد استدعاءات **working** التي كانت ستقاطع. هذه إيجابيات خاطئة تم العثور عليها قبل أن يواجهها أي وكيل: أحكم المسودة وشغلها مرة أخرى حتى يصبح هذا الرقم مقبولاً. + + + الاختبار العكسي هو ميزة لوحة التحكم. من الطرفية، شغل السياسة ضد الأحداث التي تصفها بدلاً من ذلك، أدناه. + + + +## شغله ضد حدث تصفه + +`fp policies test` يشغل ملف السياسة على جهازك ضد حدث اصطناعي ويتحقق من القرار. لا يتم نشر أي شيء ولا يصل أي شيء إلى Cloud: + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +شكّل الحدث باستخدام `--event` و `--tool` و `--command` و `--file`. مرشح `match` الخاص بالسياسة نفسها ينطبق أيضاً، لذا فإن السياسة التي لا تغطي الحدث الذي وصفته تُرجع `skipped` بدلاً من قرار — عادة ما يكون علامة على أن `match` أضيق مما قصدت. + +## شغله على جهاز واحد + +بعد ذلك، فرضه حقاً على جهازك الخاص، ضد وكيلك الخاص: + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +الأمر الأول يتحقق من صحة الملف وينصبه؛ والثاني يؤكد أنه تم تحميله، إلى جانب كل شيء آخر يفرضه هنا. اطلب من الوكيل أن يفعل ما تحقفه السياسة وشاهده يتم رفضه، ثم قم بالإصدار الشرعي وشاهده يمر. لا أحد آخر يتأثر. + +على جهاز متصل بـ Cloud، تحقق من كلا القرارين تحت **Observe → policy**: قم بالتصفية حسب اسم السياسة، ثم افتح كل جلسة مرتبطة لتأكيد إدخال الأداة التي طابقتها والسبب في عودتها. + +## اختبر ما ينكسر + +التثبيت يرفض ملف مفقود، أو خطأ في بناء الجملة، أو استيراد لم يتم حله، أو استثناء على المستوى الأعلى، أو وحدة تتجاوز المهلة الزمنية أثناء التحميل — لذا أعد تشغيله بعد كل تغيير على الملف أو أي شيء يستورده. في وقت الفرض، يتم تسجيل نفس الملف المكسور و **skipped** بحيث تستمر كل سياسة أخرى في العمل: تعامل مع تحذير التحميل في سجلات الإنتاج كفرض مفقود. ملفات الاتفاقية يتم تحميلها بدون أمر التثبيت، لذا احتفظ بخطوة `failproofai policies --install --custom ` صريحة في CI — هذا ما يفشل البناء على سياسة مكسورة. + +ثم أطعمه ما يرسله الوكلاء فعلاً، ليس فقط الإدخال الذي تتوقعه: الحقول المفقودة، أسماء الأدوات البديلة مثل `Write` و `Edit`، مسارات Windows، إدخال مشوه. أرجع `allow` أو `instruct` أو `deny` متعمد على كل مسار، اجعل الدالة حتمية، واربط أي استدعاء خارجي برصيد زمني قصير. + +## ثم انشره وراقبه + +يُظهر الاختبار العكسي ما كانت ستفعله السياسة لحركة المرور التي كانت لديك؛ لا يمكن أن يُظهر ما ستفعله حركة المرور التي لم تشهدها حتى الآن. اختر **publish version** في المحرر (أو شغل `fp policies publish`)، ثم [نشّرها](/ar/policies/deploy) في وضع **observe** أولاً — يتم تسجيل أحكامها ولا يتم حظر أي شيء — وفرضها بمجرد أن تفصل مطابقاتها الإجراءات غير الآمنة عن الإجراءات الصحيحة. \ No newline at end of file diff --git a/docs/ar/reference/cloud-cli.mdx b/docs/ar/reference/cloud-cli.mdx index 42b2069c..77ffc250 100644 --- a/docs/ar/reference/cloud-cli.mdx +++ b/docs/ar/reference/cloud-cli.mdx @@ -1,12 +1,12 @@ --- -title: "Failproof Cloud CLI" -description: "مرجع شامل للاستعلام عن وإدارة Failproof AI Cloud باستخدام fp." +title: "واجهة سطر الأوامر Failproof Cloud" +description: "مرجع شامل للاستعلام عن Failproof AI Cloud والإشراف على fp." icon: "cloud-cog" --- -استخدم `fp` للاطلاع على بيانات السحابة (telemetry)، وإدارة الإنفاذ المُدار بواسطة السحابة (السياسات ونشرات الأسطول وقرارات الحماية)، وإدارة عمليات التدقيق والنتائج والمشاكل والتنبيهات والمفاتيح والمستخدمين والاستعلامات والإعدادات. استخدم [`failproofai`](/ar/reference/failproof-cli) للخطافات المحلية والسياسات والالتقاط وتسجيل الآلات. +استخدم `fp` للتفتيش على بيانات telemetry السحابة، وإدارة فرض العمل المدار بواسطة السحابة (السياسات، نشرات الأسطول، قرارات guardrail)، والإشراف على عمليات التدقيق والنتائج والمشاكل والتنبيهات والمفاتيح والمستخدمين والاستعلامات والإعدادات. استخدم [`failproofai`](/ar/reference/failproof-cli) للخطافات المحلية والسياسات والالتقاط وتسجيل الماكينة. -ثبّت واجهة سطر أوامر السحابة المُصدرة كأداة مستقلة: +ثبّت واجهة سطر الأوامر السحابية المُصدرة كأداة معزولة: ```bash uv tool install fp-cloud-cli @@ -32,19 +32,19 @@ fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] fp --json sessions --since 24h ``` -نفّذ `fp COMMAND --help` أو `fp COMMAND SUBCOMMAND --help` للحصول على المساعدة في الطرفية. +شغّل `fp COMMAND --help` أو `fp COMMAND SUBCOMMAND --help` للحصول على مساعدة من المحطة الطرفية. -## أوامر واجهة سطر الأوامر +## أوامر CLI ### المصادقة | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp login` | سجّل الدخول برمز لمرة واحدة يُرسل عبر البريد الإلكتروني واختر مؤسسة. | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | ألغِ وأزل جلسة المستخدم المحفوظة. | — | -| `fp whoami` | اعرض الهوية الحالية ووضع المصادقة والمؤسسة والأذونات. | — | -| `fp version` | اعرض إصدار واجهة سطر الأوامر المثبتة. | — | -| `fp help` | اعرض مساعدة الأمر على المستوى الأعلى. | — | +| `fp login` | تسجيل الدخول برمز أحادي المرة مرسل عبر البريد الإلكتروني واختر مؤسسة. | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | إلغاء وإزالة جلسة المستخدم المحفوظة. | — | +| `fp whoami` | عرض الهوية الحالية وطريقة المصادقة والمؤسسة والأذونات. | — | +| `fp version` | عرض إصدار CLI المثبتة. | — | +| `fp help` | عرض مساعدة الأمر على المستوى الأعلى. | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,24 +57,24 @@ fp whoami fp events [OPTIONS] ``` -يسرد أحداث الوكيل الفردية. يستبعد التغذية الخفيفة الافتراضية الحمولات الأولية؛ استخدم `--full` فقط للتحقيق المحدود. +تسرد أحداث الوكيل الفردية. يستبعد التغذية الخفيفة الافتراضية الحمولات الأولية؛ استخدم `--full` فقط للتحقيق المحدود. | الخيار | الوصف | | --- | --- | -| `--limit`, `-n ` | أقصى إجمالي للصفوف. الافتراضي: `50`. | +| `--limit`, `-n ` | الحد الأقصى للصفوف الكلية. الافتراضي: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, أو `7d`. | | `--from ` / `--to ` | نطاق ISO 8601 UTC؛ يتجاوز `--since`. | -| `--env ` | تصفية البيئة؛ كرّر أو افصل القيم بفواصل. | -| `--event-type ` | تصفية نوع الحدث؛ كرّر أو افصل القيم بفواصل. | -| `--agent-id ` | تصفية الوكيل؛ كرّر أو افصل القيم بفواصل. | -| `--session-id ` | تصفية الجلسة؛ كرّر أو افصل القيم بفواصل. | -| `--search ` | بحث نص الحمولة؛ قابل للتكرار، مع تطابق أي مصطلح. | -| `--order asc\|desc` | ترتيب الوقت. الافتراضي: الأحدث أولاً. | -| `--all` | ترقيم تلقائي حتى `--limit`. | -| `--cursor ` | استأنف من مؤشر معتم. | -| `--page-size ` | صفوف لكل طلب مع `--all`؛ أقصى `200`. | -| `--full` | أدرج الحمولات الأولية عبر نقطة نهاية الحدث الأثقل. | -| `--fields ` | أرجع الحقول المحددة فقط؛ طلب `payload` يفعّل الوضع الكامل. | +| `--env ` | تصفية البيئة؛ كرر أو افصل القيم بفواصل. | +| `--event-type ` | تصفية نوع الحدث؛ كرر أو افصل القيم بفواصل. | +| `--agent-id ` | تصفية الوكيل؛ كرر أو افصل القيم بفواصل. | +| `--session-id ` | تصفية الجلسة؛ كرر أو افصل القيم بفواصل. | +| `--search ` | بحث نصي عن الحمولة؛ قابل للتكرار، مع مطابقة أي حد. | +| `--order asc\|desc` | ترتيب زمني. الافتراضي: الأحدث أولاً. | +| `--all` | ترحيل تلقائي حتى `--limit`. | +| `--cursor ` | استئناف من مؤشر معتم. | +| `--page-size ` | صفوف لكل طلب مع `--all`؛ الحد الأقصى `200`. | +| `--full` | تضمين الحمولات الأولية من خلال نقطة نهاية الحدث الأثقل. | +| `--fields ` | إرجاع الحقول المحددة فقط؛ طلب `payload` يفعّل الوضع الكامل. | ```bash fp events --session-id --order asc --all --limit 10000 @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` يرقّم حتى `--limit`، التي تبلغ افتراضياً **50** — لذا `--all` وحده يتوقف عند 50 صف. عندما يتوقف مبكراً، تحمل الاستجابة `next_cursor` للاستئناف منه؛ `"next_cursor": null` تعني أن التغذية استُنفدت فعلاً. + `--all` يرحّل **حتى `--limit`**، والذي يبلغ افتراضياً **50** — لذا `--all` بمفرده يتوقف عند 50 صف. عندما يتوقف مبكراً، تحمل الاستجابة `next_cursor` للاستئناف منه؛ `"next_cursor": null` يعني أن التغذية كانت مستنفدة فعلاً. ### الجلسات @@ -93,19 +93,19 @@ fp sessions [OPTIONS] | الخيار | الوصف | | --- | --- | -| `--limit`, `-n ` | أقصى إجمالي للصفوف. الافتراضي: `50`. | +| `--limit`, `-n ` | الحد الأقصى للصفوف الكلية. الافتراضي: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, أو `7d`. | | `--from ` / `--to ` | نطاق ISO 8601 UTC؛ يتجاوز `--since`. | -| `--env ` | تصفية البيئة؛ كرّر أو افصل القيم بفواصل. | -| `--status ` | `done`, `error`, أو `timeout`؛ كرّر أو افصل القيم بفواصل. | -| `--agent-id ` | طابق الجلسات التي تتضمن أي وكيل مختار. | -| `--session-id ` | تصفية الجلسة؛ كرّر أو افصل القيم بفواصل. | -| `--all` | ترقيم تلقائي حتى `--limit`. | -| `--cursor ` | استأنف من مؤشر معتم. | -| `--page-size ` | صفوف لكل طلب مع `--all`؛ أقصى `200`. | -| `--fields ` | أرجع الحقول المحددة فقط. | -| `--full-ids` | لا تقصّر معرّفات الجلسات في مخرجات الطرفية. | -| `--agents` | وسّع قائمة الوكلاء لجلسات متعددة الوكلاء. | +| `--env ` | تصفية البيئة؛ كرر أو افصل القيم بفواصل. | +| `--status ` | `done`, `error`, أو `timeout`؛ كرر أو افصل القيم بفواصل. | +| `--agent-id ` | طابق الجلسات التي تتضمن أي وكيل محدد. | +| `--session-id ` | تصفية الجلسة؛ كرر أو افصل القيم بفواصل. | +| `--all` | ترحيل تلقائي حتى `--limit`. | +| `--cursor ` | استئناف من مؤشر معتم. | +| `--page-size ` | صفوف لكل طلب مع `--all`؛ الحد الأقصى `200`. | +| `--fields ` | إرجاع الحقول المحددة فقط. | +| `--full-ids` | لا تقصّر معرفات الجلسات في إخراج المحطة الطرفية. | +| `--agents` | توسيع قائمة الوكلاء للجلسات متعددة الوكلاء. | ### التقييمات @@ -115,15 +115,15 @@ fp evals [OPTIONS] | الخيار | الوصف | | --- | --- | -| `--aggregate` | اعرض الإجماليات والإحصائيات لكل درجة بدلاً من التقييمات الفردية. | -| `--limit`, `-n ` | أقصى صفوف قائمة. الافتراضي: `50`. | -| `--since`, `--from`, `--to` | اختر نطاق الوقت. | -| `--env`, `--status`, `--agent-id`, `--session-id` | ضيّق إلى قيمة واحدة دقيقة لكل مرشح. | +| `--aggregate` | عرض الإجماليات والإحصائيات لكل درجة بدلاً من التقييمات الفردية. | +| `--limit`, `-n ` | الحد الأقصى لصفوف القائمة. الافتراضي: `50`. | +| `--since`, `--from`, `--to` | حدد نطاق الوقت. | +| `--env`, `--status`, `--agent-id`, `--session-id` | ضيّق على قيمة واحدة محددة لكل تصفية. | | `--score KEY:MIN..MAX` | نطاق الدرجات؛ قابل للتكرار ويجب أن تطابق جميع النطاقات. | -| `--all`, `--cursor`, `--page-size` | تحكم بترقيم القائمة. | -| `--fields ` | أرجع الحقول المحددة فقط. | -| `--full-ids` | اعرض معرّفات الجلسات الكاملة. | -| `--scores-full` | اعرض كل درجة في مخرجات الطرفية. | +| `--all`, `--cursor`, `--page-size` | تحكم في ترحيل القائمة. | +| `--fields ` | إرجاع الحقول المحددة فقط. | +| `--full-ids` | عرض معرفات الجلسات الكاملة. | +| `--scores-full` | عرض كل درجة في إخراج المحطة الطرفية. | ### الأخطاء @@ -133,120 +133,120 @@ fp errors [OPTIONS] | الخيار | الوصف | | --- | --- | -| `--aggregate` | لخّص الأخطاء المطابقة بدلاً من سرد الصفوف. | -| `--limit`, `-n ` | أقصى صفوف قائمة. الافتراضي: `50`. | -| `--since`, `--from`, `--to` | اختر نطاق الوقت. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | ضيّق مجموعة الأخطاء. | -| `--search ` | ابحث في نص الحمولة؛ قابل للتكرار. | -| `--order asc\|desc` | ترتيب الوقت. | -| `--all`, `--cursor`, `--page-size` | تحكم بترقيم القائمة. | -| `--fields ` | أرجع الحقول المحددة فقط. | -| `--full-ids` | اعرض معرّفات الجلسات الكاملة. | +| `--aggregate` | ملخص الأخطاء المطابقة بدلاً من عرض الصفوف. | +| `--limit`, `-n ` | الحد الأقصى لصفوف القائمة. الافتراضي: `50`. | +| `--since`, `--from`, `--to` | حدد نطاق الوقت. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | ضيّق من مجموعة الأخطاء. | +| `--search ` | بحث نصي عن الحمولة؛ قابل للتكرار. | +| `--order asc\|desc` | ترتيب زمني. | +| `--all`, `--cursor`, `--page-size` | تحكم في ترحيل القائمة. | +| `--fields ` | إرجاع الحقول المحددة فقط. | +| `--full-ids` | عرض معرفات الجلسات الكاملة. | ### الاستخدام وقيم التصفية | الأمر | الغرض | | --- | --- | -| `fp usage` | اعرض الاستخدام لنافذة التقييس الحالية. | -| `fp list envs` | اسرد البيئات المرصودة. | -| `fp list agents` | اسرد معرّفات الوكلاء المرصودة. | -| `fp list event_types` | اسرد أنواع الأحداث. | -| `fp list score_filters` | اسرد مفاتيح درجات التقييم. | -| `fp list models` | اسرد أسماء النماذج. | -| `fp list hooks` | اسرد أسماء الخطافات. | -| `fp list tools` | اسرد أسماء الأدوات. | -| `fp list error_types` | اسرد أنواع الأخطاء. | +| `fp usage` | عرض الاستخدام لنافذة التقسيم الحالية. | +| `fp list envs` | عرض قائمة البيئات المراقبة. | +| `fp list agents` | عرض قائمة معرفات الوكلاء المراقبة. | +| `fp list event_types` | عرض قائمة أنواع الأحداث. | +| `fp list score_filters` | عرض قائمة مفاتيح درجات التقييم. | +| `fp list models` | عرض قائمة أسماء النماذج. | +| `fp list hooks` | عرض قائمة أسماء الخطافات. | +| `fp list tools` | عرض قائمة أسماء الأدوات. | +| `fp list error_types` | عرض قائمة أنواع الأخطاء. | ### المؤسسات | الأمر | الغرض | | --- | --- | -| `fp orgs list` | اسرد المؤسسات المتاحة. | -| `fp orgs switch [SLUG]` | احفظ مؤسسة نشطة؛ يطلب عند الحذف. | -| `fp orgs current` | اعرض المؤسسة النشطة. | -| `fp orgs perms` | اعرض أذوناتك في المؤسسة النشطة. | +| `fp orgs list` | عرض قائمة المؤسسات القابلة للوصول. | +| `fp orgs switch [SLUG]` | احفظ مؤسسة نشطة؛ يُطلب عند الحذف. | +| `fp orgs current` | عرض المؤسسة النشطة. | +| `fp orgs perms` | عرض أذوناتك في المؤسسة النشطة. | ### مفاتيح API | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp keys list` | اسرد مفاتيح المؤسسة. | `--show-id`; `--fields ` | -| `fp keys show NAME` | اعرض مفتاح واحد ومنحه. | — | -| `fp keys create NAME` | أنشئ مفتاح واكشف سره مرة واحدة. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | استبدل مجموعة الأذونات أو اضبط المنح. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | أدِر السر واكشف البديل مرة واحدة. | `--yes`, `-y` | -| `fp keys disable NAME` | ألغِ مفتاح بشكل دائم. | `--yes`, `-y` | +| `fp keys list` | عرض قائمة مفاتيح المؤسسة. | `--show-id`; `--fields ` | +| `fp keys show NAME` | عرض مفتاح واحد ومنحاته. | — | +| `fp keys create NAME` | إنشاء مفتاح وكشف سره مرة واحدة. | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | استبدال مجموعة الأذونات أو ضبط المنح. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | تدوير السر واكشف الاستبدال مرة واحدة. | `--yes`, `-y` | +| `fp keys disable NAME` | إلغاء مفتاح بشكل دائم. | `--yes`, `-y` | -تستخدم رموز الأذونات `resource:action`، مثل `events:add`. كرّر `--add`، افصل الرموز بفواصل، أو استخدم إجراءات منقوطة مثل `events:read.add`. +تستخدم رموز الأذونات `resource:action`، مثل `events:add`. كرر `--add`، افصل الرموز بفواصل، أو استخدم إجراءات مفصولة بنقاط مثل `events:read.add`. ### الاستعلامات | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp query list` | اسرد الاستعلامات المحفوظة. | `--show-id`; `--fields ` | -| `fp query show NAME` | اعرض استعلام واحد. | — | -| `fp query create NAME` | احفظ استعلام. | `--sql `; `--description` | -| `fp query update NAME` | حدّث أو أعد تسمية استعلام. | `--name`; `--sql`; `--description`; `--yes`, `-y` | -| `fp query delete NAME` | احذف استعلام محفوظ. | `--yes`, `-y` | -| `fp query run [NAME]` | نفّذ استعلام محفوظ أو SQL مخصص. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | اسرد الجداول القابلة للاستعلام أو افحص جدول واحد. | — | +| `fp query list` | عرض قائمة الاستعلامات المحفوظة. | `--show-id`; `--fields ` | +| `fp query show NAME` | عرض استعلام واحد. | — | +| `fp query create NAME` | حفظ استعلام. | `--sql `; `--description` | +| `fp query update NAME` | تحديث أو إعادة تسمية استعلام. | `--name`; `--sql`; `--description`; `--yes`, `-y` | +| `fp query delete NAME` | حذف استعلام محفوظ. | `--yes`, `-y` | +| `fp query run [NAME]` | شغّل استعلاماً محفوظاً أو SQL فوري. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query schema [TABLE]` | عرض قائمة الجداول القابلة للاستعلام أو فحص جدول واحد. | — | ### المستخدمون | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp users list` | اسرد أعضاء المؤسسة. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | اعرض عضو ومنحه. | — | -| `fp users create EMAIL` | أضف عضو. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | غيّر منح العضو. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp users disable EMAIL` | عطّل تسجيل الدخول. | `--yes`, `-y` | -| `fp users enable EMAIL` | أعد تفعيل تسجيل الدخول. | `--yes`, `-y` | +| `fp users list` | عرض قائمة أعضاء المؤسسة. | `--active-only`; `--show-id` | +| `fp users show EMAIL` | عرض عضو ومنحاه. | — | +| `fp users create EMAIL` | إضافة عضو. | `--permission-set`; `--add`; `--remove` | +| `fp users update EMAIL` | تغيير منح العضو. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users disable EMAIL` | تعطيل تسجيل الدخول. | `--yes`, `-y` | +| `fp users enable EMAIL` | إعادة تفعيل تسجيل الدخول. | `--yes`, `-y` | ### الإعدادات | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp settings list` | اسرد إعدادات المؤسسة والقيم الحالية. | — | -| `fp settings schema` | اعرض القيم المقبولة والأوصاف. | — | -| `fp settings set KEY` | غيّر إعداد موجود. | واحد بالضبط من `--value`, `--json-value`, `--file`; `--yes`, `-y` اختياري | +| `fp settings list` | عرض قائمة إعدادات المؤسسة والقيم الحالية. | — | +| `fp settings schema` | عرض القيم المقبولة والأوصاف. | — | +| `fp settings set KEY` | تغيير إعداد موجود. | واحد فقط من `--value`, `--json-value`, `--file`؛ اختياري `--yes`, `-y` | ### التنبيهات | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp alerts list` | اسرد قواعد التنبيهات. | `--show-id` | -| `fp alerts show NAME` | اعرض تنبيه واحد. | — | -| `fp alerts create NAME` | أنشئ تنبيه. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | حدّث أو أعد تسمية تنبيه. | خيارات الإنشاء بالإضافة إلى `--name`; `--yes`, `-y` | -| `fp alerts delete NAME` | احذف تنبيه. | `--yes`, `-y` | -| `fp alerts test NAME` | أرسل إخطار اختبار. | `--channels`; `--yes`, `-y` | +| `fp alerts list` | عرض قائمة قواعد التنبيه. | `--show-id` | +| `fp alerts show NAME` | عرض تنبيه واحد. | — | +| `fp alerts create NAME` | إنشاء تنبيه. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | +| `fp alerts update NAME` | تحديث أو إعادة تسمية تنبيه. | خيارات الإنشاء بالإضافة إلى `--name`; `--yes`, `-y` | +| `fp alerts delete NAME` | حذف تنبيه. | `--yes`, `-y` | +| `fp alerts test NAME` | إرسال إخطار اختبار. | `--channels`; `--yes`, `-y` | -درجات التنبيهات هي `info`, `warning`, و `critical`. أنواع المشغلات هي `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound`, و `per_event`. يجب أن تكون فترات التقييم بين 30 و 86,400 ثانية. +شدات التنبيه هي `info`, `warning`, و `critical`. أنواع المشغلات هي `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound`, و `per_event`. يجب أن تكون فترات التقييم بين 30 و 86400 ثانية. -### عمليات التدقيق +### التدقيق | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp audits list` | اسرد عمليات التدقيق. | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | اعرض تعريف التدقيق الواحد والحالة. | — | -| `fp audits create NAME` | أنشئ تدقيق وأدرج تشغيله الأول فوراً. | انظر [خيارات الإنشاء](#audit-create-options). | -| `fp audits edit NAME` | استبدل إعدادات التدقيق مع الاحتفاظ بالقيم غير المحددة. | خيارات تعريف الإنشاء; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | احذف تدقيق ونتائجه وسجل التشغيل. | `--yes`, `-y` | -| `fp audits run NAME` | أدرج تشغيل يدوي. | — | -| `fp audits runs NAME` | اسرد سجل التشغيل. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | اعرض الملخص وحالة جلب رابط المرجع. | — | -| `fp audits context-set NAME` | غيّر الملخص أو روابط المرجع. | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | أعد جلب روابط المرجع. | — | -| `fp audits findings` | اسرد النتائج. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | اعرض نتيجة واحدة وأدلتها. | — | -| `fp audits ack FINDING_ID` | اعترف بنتيجة. | `--reason` | -| `fp audits mute FINDING_ID` | اكتم نمط متكرر. | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | ضع علامة على نمط غير قابل للتنفيذ واكتمه. | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | ضع علامة على نتيجة محلولة بدون كتم مستقبلي. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | أعد نتيجة إلى قائمة الانتظار المباشرة ومسح الكتم. | — | -| `fp audits assign FINDING_ID` | عيّن مالك النتيجة. | `--to ` مطلوب | - -#### خيارات إنشاء التدقيق +| `fp audits list` | عرض قائمة المراجعات. | `--enabled-only`; `--show-id` | +| `fp audits show NAME` | عرض تعريف المراجعة واحدة وحالتها. | — | +| `fp audits create NAME` | إنشاء مراجعة وطلب تشغيلها الأول على الفور. | انظر [خيارات الإنشاء](#audit-create-options). | +| `fp audits edit NAME` | استبدل إعدادات المراجعة مع الاحتفاظ بالقيم غير المحددة. | خيارات تعريف الإنشاء؛ `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | حذف مراجعة ونتائجها وسجل التشغيل. | `--yes`, `-y` | +| `fp audits run NAME` | طلب تشغيل يدوي. | — | +| `fp audits runs NAME` | عرض قائمة سجل التشغيل. | `--limit`, `-n`; `--show-id` | +| `fp audits context-show NAME` | عرض الملخص وحالة جلب عنوان URL المرجعي. | — | +| `fp audits context-set NAME` | تغيير الملخص أو عناوين URL المرجعية. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-refresh NAME` | إعادة جلب عناوين URL المرجعية. | — | +| `fp audits findings` | عرض قائمة النتائج. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | +| `fp audits finding FINDING_ID` | عرض نتيجة واحدة وأدلتها. | — | +| `fp audits ack FINDING_ID` | الإقرار بنتيجة. | `--reason` | +| `fp audits mute FINDING_ID` | قمع نمط متكرر. | `--reason`; `--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | وضع علامة على النمط غير قابل للتنفيذ وقمعه. | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | وضع علامة على إصلاح النتيجة بدون قمع مستقبلي. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | إرجاع نتيجة إلى قائمة الانتظار المباشرة ومسح القمع. | — | +| `fp audits assign FINDING_ID` | تعيين مالك النتيجة. | `--to ` مطلوب | + +#### خيارات إنشاء المراجعة ```bash fp audits create checkout-reliability \ @@ -261,120 +261,120 @@ fp audits create checkout-reliability \ | الخيار | الوصف | | --- | --- | -| `--file ` | أسّس التعريف على JSON، أو استخدم `-` للإدخال القياسي. تتجاوز الأعلام الصريحة قيم الملف. | -| `--description ` | اذكر سؤال الفشل أو الغرض. | -| `--enabled` / `--disabled` | ابدأ الجدولة بتشغيل أو إيقاف. الافتراضي: مفعّل. | +| `--file ` | بناء التعريف على JSON، أو استخدم `-` للإدخال القياسي. الأعلام الصريحة تتجاوز قيم الملف. | +| `--description ` | حدد سؤال الفشل أو الغرض. | +| `--enabled` / `--disabled` | ابدأ الجدولة على أو بـ إيقاف. الافتراضي: مفعّل. | | `--schedule-interval-secs ` | `3600`–`604800`. الافتراضي: `86400`. | -| `--schedule-anchor ` | مرحلة UTC ثابتة في شكل ISO 8601. الافتراضي: 09:00 UTC التالية. | -| `--window-mode since_last\|fixed` | استمرّ بعد آخر نافذة محللة بالكامل أو افحص نافذة دوارة بشكل متكرر. الافتراضي: `since_last`. | +| `--schedule-anchor ` | المرحلة UTC الثابتة بصيغة ISO 8601. الافتراضي: 09:00 UTC التالية. | +| `--window-mode since_last\|fixed` | متابعة بعد آخر نافذة تم تحليلها بالكامل أو فحص نافذة متداخلة بشكل متكرر. الافتراضي: `since_last`. | | `--lookback-window-secs ` | `3600`–`7776000`. الافتراضي: `604800`. | -| `--scope ''` | صفّي حسب `environments`, `agent_ids`, أو حقول النطاق الأخرى المدعومة. | -| `--ignore-error-type ` | استبعد أنواع الأخطاء؛ كرّر أو افصل بفواصل. | -| `--llm` / `--no-llm` | فعّل أو عطّل التحليل الموجه بالوكيل. الافتراضي: مفعّل. | +| `--scope ''` | التصفية حسب `environments`, `agent_ids`, أو حقول نطاق أخرى مدعومة. | +| `--ignore-error-type ` | استبعد أنواع الأخطاء؛ كرر أو افصل بفواصل. | +| `--llm` / `--no-llm` | فعّل أو عطّل التحليل الذي يحركه الوكيل. الافتراضي: مفعّل. | | `--top-k ` | احتفظ بـ `1`–`500` نتيجة. الافتراضي: `50`. | | `--sensitivity low\|medium\|high` | اضبط حساسية الإبلاغ. الافتراضي: `medium`. | | `--channels ''` | مصفوفة قنوات الإخطار. | -| `--text ` | ملخص مضمّن، أقصى 8,192 حرف. | -| `--text-file ` | اقرأ الملخص من ملف؛ حصري متبادل مع `--text`. | -| `--url ` | أضف مرجع HTTPS عام؛ كرّر حتى خمس مرات. | +| `--text ` | ملخص مضمن، بحد أقصى 8192 حرف. | +| `--text-file ` | اقرأ الملخص من ملف؛ متعارض مع `--text`. | +| `--url ` | أضف مرجعاً عام HTTPS؛ كرر حتى خمس مرات. | -أدرج السياق أثناء الإنشاء عندما يحتاجه التشغيل الأول. يلتزم الإنشاء بالتعريف والسياق معاً قبل بدء التشغيل المصفوف. +أدرج السياق أثناء الإنشاء عندما يحتاجه التشغيل الأول. الإنشاء ينفذ التعريف والسياق معاً قبل بدء التشغيل المطلوب. - `fp audits run` غير متزامن. صوّت `fp audits runs NAME` حتى يحقق آخر تشغيل النجاح أو الفشل قبل قراءة نتائجه. + `fp audits run` غير متزامن. استطلع `fp audits runs NAME` حتى ينجح التشغيل الأخير أو يفشل قبل قراءة نتائجه. ### المشاكل | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp issues list` | اسرد المشاكل. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | احسب المشاكل المفتوحة أو حالات المشاكل المختارة. | `--state` | -| `fp issues show INCIDENT_ID` | اعرض تفاصيل المشكلة والتعليقات والمشتركين والنشاط. | — | -| `fp issues open` | افتح مشكلة يدوية أو مرتبطة بتنبيه. | `--summary` مطلوب؛ `--title`, `--alert-id`, `--severity` اختياري | -| `fp issues ack INCIDENT_ID` | اعترف بمشكلة. | — | -| `fp issues assign INCIDENT_ID` | استبدل المعينين؛ احذف الخيار لمسحهم. | `--assignee` قابل للتكرار | -| `fp issues resolve INCIDENT_ID` | حلّ مشكلة. | `--yes`, `-y` | -| `fp issues comment-list INCIDENT_ID` | اسرد التعليقات. | — | -| `fp issues comment-add INCIDENT_ID` | أضف تعليق. | واحد بالضبط من `--body`, `--file` | -| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | احذف تعليق. | `--yes`, `-y` | -| `fp issues subscribers INCIDENT_ID` | اسرد المشتركين. | — | -| `fp issues subscribe INCIDENT_ID` | اشترك بنفسك أو مع مشغّل آخر. | `--email` | -| `fp issues unsubscribe INCIDENT_ID` | أزل اشتراك. | `--email` | - -حالات المشاكل الصالحة هي `firing`, `acknowledged`, و `resolved`. درجات المشاكل المستقلة هي `info`, `warning`, و `critical`. +| `fp issues list` | عرض قائمة المشاكل. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | عدّ المشاكل المفتوحة أو حالات المشاكل المحددة. | `--state` | +| `fp issues show INCIDENT_ID` | عرض تفاصيل المشكلة والتعليقات والمشتركين والنشاط. | — | +| `fp issues open` | افتح مشكلة يدوية أو مرتبطة بتنبيه. | `--summary` مطلوب؛ اختياري `--title`, `--alert-id`, `--severity` | +| `fp issues ack INCIDENT_ID` | الإقرار بمشكلة. | — | +| `fp issues assign INCIDENT_ID` | استبدل المكلفين؛ حذف الخيار لمسحهم. | `--assignee` قابل للتكرار | +| `fp issues resolve INCIDENT_ID` | حل مشكلة. | `--yes`, `-y` | +| `fp issues comment-list INCIDENT_ID` | عرض قائمة التعليقات. | — | +| `fp issues comment-add INCIDENT_ID` | إضافة تعليق. | واحد فقط من `--body`, `--file` | +| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | حذف تعليق. | `--yes`, `-y` | +| `fp issues subscribers INCIDENT_ID` | عرض قائمة المشتركين. | — | +| `fp issues subscribe INCIDENT_ID` | اشترك بنفسك أو بمشغل آخر. | `--email` | +| `fp issues unsubscribe INCIDENT_ID` | إزالة اشتراك. | `--email` | + +حالات المشاكل الصحيحة هي `firing`, `acknowledged`, و `resolved`. شدات المشاكل المستقلة هي `info`, `warning`, و `critical`. ### مساعد السحابة | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp agent health` | تحقق من توفر والمساعد والتكوين. | — | -| `fp agent models` | اسرد نماذج المساعد المتاحة. | — | -| `fp agent chats` | اسرد الدردشات المحفوظة. | — | -| `fp agent ask [MESSAGE]` | ابدأ أو استمرّ في دردشة؛ اقرأ من الإدخال القياسي عند حذف الرسالة. | `--chat`; `--model`; `--page-context` | -| `fp agent show CHAT_ID` | اعرض محادثة محفوظة. | — | +| `fp agent health` | تحقق من توفر وتكوين المساعد. | — | +| `fp agent models` | عرض قائمة نماذج المساعد المتاحة. | — | +| `fp agent chats` | عرض قائمة المحادثات المحفوظة. | — | +| `fp agent ask [MESSAGE]` | ابدأ أو استمر في محادثة؛ اقرأ من الإدخال القياسي عند حذف الرسالة. | `--chat`; `--model`; `--page-context` | +| `fp agent show CHAT_ID` | عرض محادثة محفوظة. | — | | `fp agent rename CHAT_ID` | أعد تسمية محادثة. | `--title` مطلوب | -| `fp agent delete CHAT_ID` | احذف محادثة. | `--yes`, `-y` | +| `fp agent delete CHAT_ID` | حذف محادثة. | `--yes`, `-y` | ### السياسات -إصدارات السياسة المُدارة بواسطة السحابة. **جلسة فقط** — يخرج كل أمر هنا بـ `2` تحت مفتاح API، قبل أي طلب، لأن هذه مسارات كتابة جذر مقصودة غائبة عن `/v1`. +إصدارات السياسة المدارة بواسطة السحابة. **جلسة فقط** — كل أمر هنا يُخرج `2` تحت مفتاح API، قبل أي طلب، لأن هذه مسارات كتابة جذرية محذوفة عن قصد من `/v1`. | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp policies list` | اسرد إصدارات السياسات. | `--json` | -| `fp policies show POLICY_ID` | اعرض سياسة واحدة، مع مصدرها. | — | -| `fp policies publish NAME PATH` | ألّف إصدار من `.mjs` محلي. | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | أضفها مرة أخرى إلى كل نشر أُزيلت منه، مما يخلق جيل جديد على كل واحد. | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | أزلها من كل نشر يحملها، مما يخلق جيل جديد على كل واحد. | `--yes`, `-y` | -| `fp policies delete POLICY_ID` | احذف إصدار سياسة. | `--yes`, `-y` | -| `fp policies test PATH` | شغّل سياسة محلياً مقابل سياق تركيبي. يطبّق مرشح `match` لكل سياسة، لذا يُبلَّغ عن سياسة لا تغطي الحدث/الأداة المعطاة `skipped` بدلاً من التشغيل. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | صغ سياسة مع المساعد. تحتاج `policies:write`. | — | +| `fp policies list` | عرض قائمة إصدارات السياسة. | `--json` | +| `fp policies show POLICY_ID` | عرض سياسة واحدة، مع مصدرها. | — | +| `fp policies publish NAME PATH` | نقيب إصدار من `.mjs` محلي. | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | أضفها مرة أخرى إلى كل نشر تم إزالتها منه، نقيب جيل جديد على كل واحد. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | أزلها من كل نشر تحملها، نقيب جيل جديد على كل واحد. | `--yes`, `-y` | +| `fp policies delete POLICY_ID` | حذف إصدار سياسة. | `--yes`, `-y` | +| `fp policies test PATH` | شغّل سياسة محلياً مقابل سياق تركيبي. تطبق تصفية `match` لكل سياسة، لذلك التي لا تغطي الحدث/الأداة المحددة يتم الإبلاغ عنها `skipped` بدلاً من التشغيل. | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | صيغ سياسة مع المساعد. يحتاج `policies:write`. | — | ### الأسطول -أي آلات تشغّل أي سياسات. **جلسة فقط**، السبب نفسه أعلاه. +أي ماكينات تشغل أي سياسات. **جلسة فقط**، نفس السبب أعلاه. | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp fleet list` | اسرد الآلات المسجلة وجيل نشرها. | — | -| `fp fleet show MACHINE_ID` | مجموعة السياسات التي تشغّلها آلة حالياً. | — | -| `fp fleet deploy MACHINE_ID` | **استبدل مجموعة السياسات كاملة للآلة.** اطبع الخطة واسأل فقط على طرفية تفاعلية بدون `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | قارن آلة مقابل نشر آخر. | — | -| `fp fleet history MACHINE_ID` | النشرات السابقة لآلة. | — | -| `fp fleet rollback MACHINE_ID` | استعد نشراً سابقاً. | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | أعط آلة اسماً قابلاً للقراءة. | `--name` مطلوب | +| `fp fleet list` | عرض قائمة الماكينات المسجلة وجيل النشر الخاص بها. | — | +| `fp fleet show MACHINE_ID` | مجموعة السياسات التي تشغلها ماكينة حالياً. | — | +| `fp fleet deploy MACHINE_ID` | **استبدل مجموعة السياسات الكاملة للماكينة.** اطبع الخطة واسأل فقط على محطة طرفية تفاعلية بدون `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | قارن ماكينة مقابل نشر آخر. | — | +| `fp fleet history MACHINE_ID` | النشريات السابقة لماكينة. | — | +| `fp fleet rollback MACHINE_ID GENERATION` | أعد تثبيت مجموعة السياسات لجيل سابق، كجيل جديد. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | أعط ماكينة اسماً قابلاً للقراءة. | `--name` مطلوب | -### الحماية +### guardrails -ما فعله الإنفاذ فعلياً. **جلسة فقط**، السبب نفسه أعلاه. +ما فعله الفرض فعلاً. **جلسة فقط**، نفس السبب أعلاه. | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp guardrails summary` | التغطية والمجاميع المحظورة/المقيّمة وخطأ رفض وجدول السياسة. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | القرارات المجمّعة على النافذة، مجموعة عبر كل مصدر سياسة. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | التغطية والإجماليات المحجوبة/المقيّمة وخط رفض وجدول لكل سياسة. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | القرارات المجمعة على النافذة، مجموعة على كل مصدر سياسة. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | ## الأعلام العامة | العلم | الوصف | | --- | --- | -| `--json` | أصدر JSON قابل لقراءة الآلة. | -| `--base-url ` | استخدم لوحة معلومات مستقلة أو تطوير. | -| `--org ` | اختر مؤسسة لهذا التشغيل. | +| `--json` | بث JSON قابل للقراءة من الآلة. | +| `--base-url ` | استخدم لوحة تحكم ذاتية الاستضافة أو التطوير. | +| `--org ` | حدد مؤسسة لهذا الاستدعاء. | | `--token ` | تجاوز رمز جلسة المستخدم المحفوظ. | -| `--api-key ` | صادق الأتمتة برمز API؛ لا يُحفظ أبداً. | +| `--api-key ` | المصادقة الأتمتة برمز API؛ لا تُحفظ أبداً. | | `--timeout ` | مهلة HTTP؛ يجب أن تكون موجبة. الافتراضي: `30`. | -| `--quiet`, `-q` | اكتم مخرجات الحالة على stderr. | -| `--no-color` | عطّل الإخراج الملون. | -| `--insecure` / `--secure` | عطّل أو استعد التحقق من شهادة TLS. | -| `--version` | اطبع الإصدار غير المجاور وخرج. | -| `--help`, `-h` | اعرض المساعدة. | +| `--quiet`, `-q` | قمع إخراج الحالة على stderr. | +| `--no-color` | تعطيل الإخراج الملون. | +| `--insecure` / `--secure` | تعطيل أو استعادة التحقق من شهادة TLS. | +| `--version` | طباعة الإصدار المفتوح والخروج. | +| `--help`, `-h` | عرض المساعدة. | -`--api-key` مقصود للأتمتة. تسجيل الدخول وتبديل المؤسسة وأوامر المساعد تتطلب جلسة مستخدم. +`--api-key` مخصصة للأتمتة. تسجيل الدخول وتبديل المؤسسة وأوامر المساعد تتطلب جلسة مستخدم. ## متغيرات البيئة -| المتغير | ما يعادله أو الغرض | +| المتغير | المكافئ أو الغرض | | --- | --- | | `FP_DASHBOARD_URL` | `--base-url` | | `FP_ORG` | `--org` | @@ -382,18 +382,18 @@ fp audits create checkout-reliability \ | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | أعد توضيع دليل تكوين CLI (الافتراضي `~/.failproofai/fpcli`). | +| `FP_HOME` | أعد وضع مجلد تكوين CLI (الافتراضي `~/.failproofai/fpcli`). | | `FP_ANALYTICS_DISABLED` أو `DO_NOT_TRACK` | عطّل تحليلات CLI المجهولة. | | `NO_COLOR` | عطّل الإخراج الملون. | -تتجاوز الأعلام الصريحة متغيرات البيئة، التي تتجاوز التكوين المحفوظ. في وضع مفتاح API، اختر المستأجر بوضوح مع `--org` أو `FP_ORG`. +الأعلام الصريحة تتجاوز متغيرات البيئة، التي تتجاوز التكوين المحفوظ. في وضع مفتاح API، حدد المستأجر بشكل صريح مع `--org` أو `FP_ORG`. - تهجئات `AGENTEYE_*` من هذه **لا تُقرأ بواسطة `fp`** ولم تكن أبداً — يعلن CLI `FP_*` (`fp_cli/app.py`)، ومتغير غير معروف ليس خطأ. ضبط `AGENTEYE_DASHBOARD_URL` لا يستهدف CLI؛ يُتجاهل والأمر يعمل بصمت ضد لوحة المعلومات المحفوظة بدلاً من ذلك. + تهجئات `AGENTEYE_*` لهذه **لا تُقرأ بواسطة `fp`** وأبداً لم تكن — يعلن CLI عن `FP_*` (`fp_cli/app.py`)، وحتى متغير غير معروف ليس خطأ. تعيين `AGENTEYE_DASHBOARD_URL` لا يعيد تحديد هدف CLI؛ يتم تجاهله والأمر يعمل بصمت مقابل لوحة التحكم المحفوظة بدلاً منه. - `AGENTEYE_HOME` و `AGENTEYE_ENVIRONMENT` موجودة لا تزال، لكنها تنتمي إلى **جامع والتطبيق الكلينوميتري**، وليس إلى CLI هذا. + `AGENTEYE_HOME` و `AGENTEYE_ENVIRONMENT` لا تزال موجودة، لكنها تتعلق بـ **المجمع و telemetry SDK**، وليس بـ CLI هذا. - الأوامر التي تحذف أو تلغي أو تكتم أو تحلّ أو تستبدل التكوين تطالب افتراضياً. استخدم `--yes` فقط بعد التحقق من المؤسسة النشطة والهدف. + الأوامر التي تحذف أو تلغي أو تقمع أو تحل أو تستبدل التكوين تطالب بشكل افتراضي. استخدم `--yes` فقط بعد التحقق من المؤسسة النشطة والهدف. \ No newline at end of file diff --git a/docs/ar/reference/custom-agents.mdx b/docs/ar/reference/custom-agents.mdx index 5a7630a2..5ca2384f 100644 --- a/docs/ar/reference/custom-agents.mdx +++ b/docs/ar/reference/custom-agents.mdx @@ -1,17 +1,17 @@ --- -title: "وكلاء مخصصون" -description: "الإعدادات والفهرس الكامل للأحداث وقواعد الربط والتسليم لـ failproofai-sdk." +title: "وكلاء مخصصة" +description: "الإعدادات وفهرس الأحداث وقواعد الارتباط والتسليم لـ failproofai-sdk." icon: "python" --- -شرح لكل إعداد وطريقة وحقل. إذا كنت تقوم بالقياس للمرة الأولى، ابدأ بالدليل — هذه الصفحة مخصصة للبحث عن الأشياء. +شرح لكل إعداد وطريقة وحقل ويعمل. إذا كنت تقوم بالتجهيز للمرة الأولى، ابدأ بالدليل — هذه الصفحة مخصصة للبحث. - - التثبيت والقياس وطرق الأحداث ومثال عملي والمشاكل الشائعة. + + التثبيت والتجهيز وطرق الأحداث ومثال عملي ومشاكل شائعة. - LangChain و CrewAI و LlamaIndex و Pydantic AI تقيس نفسها بنفسها باستدعاء واحد. + تجهز LangChain و CrewAI و LlamaIndex و Pydantic AI نفسها بمكالمة واحدة. @@ -23,24 +23,30 @@ Python 3.10 أو أحدث. بدون متطلبات وقت التشغيل. pip install failproofai-sdk ``` -يتم تثبيت الحزمة باسم `failproofai-sdk` واستيرادها في Python باسم `failproofai_sdk`. إضافات الإطار مثل `failproofai-sdk[langgraph]` تثبت الإطار نفسه؛ المحولات دائماً مدرجة في العجلة الأساسية. +يتم تثبيت الحزمة باسم `failproofai-sdk` واستيرادها في Python كـ `failproofai_sdk`. الإضافات الإطار مثل `failproofai-sdk[langgraph]` تثبت الإطار نفسه؛ تأتي المحولات دائماً في الحزمة الأساسية. -## ربط مراقب Failproof +## توصيل مُراقب Failproof - 1. انتقل إلى **Admin → Keys** وأنشئ مفتاحاً بصلاحية `events:add`. - 2. [ربط مراقب Failproof بـ Cloud](/ar/start/setup#connect-a-machine-to-cloud) على جهاز الوكيل. - 3. قم بتشغيل جلسة واحدة مع القياس، ثم ابحث عن معرّفها الدقيق تحت **Observe → Events**. - 4. انتقل إلى **Observe → Sessions**، اختر نفس البيئة، وافتح الأثر المعاد بناؤه. + 1. انتقل إلى **Admin → Keys** وأنشئ مفتاحاً بـ `events:add`. + 2. [وصّل مُراقب Failproof إلى Cloud](/ar/start/setup#connect-a-machine-to-cloud) على جهاز الوكيل. + 3. قم بتشغيل جلسة واحدة مجهزة، ثم ابحث عن معرّفها الدقيق ضمن **Observe → Events**. + 4. انتقل إلى **Observe → Sessions** واختر نفس البيئة وافتح الأثر المعاد بناؤه. - ![جلسة وكيل Python مخصص معاد بناؤها كرسم بياني للتنفيذ وتسلسل حدث مرتب.](/images/dashboard/session-detail.png) + ![جلسة وكيل Python مخصصة معاد بناؤها كرسم بياني للتنفيذ وتتبع الأحداث المرتبة.](/images/dashboard/session-detail.png) - + + اقرأ مفتاح `events:add` إلى الـ shell. `read -s` يأخذها عند نص لا يتكرر، لذا لا تظهر أبداً في أمر أو في سجل shell: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + ثم جهز الجهاز وتحقق من أنه متصل: + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -58,32 +64,32 @@ failproofai_sdk.configure( ) ``` -| الحجة | ما تفعله | +| الوسيط | ما يفعله | | --- | --- | -| `environment` | العلامة على كل حدث — `production` أو `staging` أو `prod-eu`. القيمة الافتراضية `dev`. | -| `flush_interval` | عدد مرات كتابة الخيط الخلفي إلى القرص بالثواني. القيمة الافتراضية `0.5`. | -| `base_dir` | مكان الكتابة. القيمة الافتراضية سبول المراقب، وهذا ما تريده ما لم تكن تعرف خلاف ذلك. | +| `environment` | التسمية على كل حدث — `production` أو `staging` أو `prod-eu`. الافتراضي هو `dev`. | +| `flush_interval` | عدد مرات كتابة الـ thread في الخلفية إلى القرص، بالثواني. الافتراضي هو `0.5`. | +| `base_dir` | مكان الكتابة. الافتراضي هو spool المُراقب، وهو ما تريده إلا إذا كنت تعرف خلاف ذلك. | -اضبط عن طريق متغير البيئة بدلاً من ذلك: +عيّن من خلال متغير البيئة بدلاً من ذلك: -| متغير | ما يفعله | +| المتغير | ما يفعله | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | يضبط `environment` بدون تغيير الكود، لعندما تكون العلامة تابعة للنشر وليس التطبيق. حجة `configure()` تتفوق عليها. | -| `FAILPROOFAI_HOME` | ينقل جذر Failproof AI الذي يحتفظ بالسبول. | -| `FAILPROOFAI_SDK_STRICT` | قيمة `1` تجعل أخطاء القياس ترفع بدلاً من تسجيلها. | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | قيمة `1` تجعل مشكلة توافق الإطار ترفع بدلاً من التحذير والمتابعة. | +| `AGENTEYE_ENVIRONMENT` | يضبط `environment` بدون تغيير في الكود، لما تكون التسمية تخص النشر وليس التطبيق. وسيط `configure()` يفوز عليه. | +| `FAILPROOFAI_HOME` | ينقل جذر Failproof AI الذي يحتفظ بـ spool. | +| `FAILPROOFAI_SDK_STRICT` | `1` يجعل أخطاء التجهيز ترفع بدلاً من أن تُسجل. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` يجعل مشكلة توافق الإطار ترفع بدلاً من التحذير والمتابعة. | - **لا توجد فواصل في `environment`.** تقسم وحدة الاستيعاب هذا الحقل على الفواصل لبناء المرشحات، وتتخطى أي حدث تحتوي علامته على واحدة — لذلك يختفي التشغيل كله بصمت. اكتب `prod-eu` وليس `prod,eu`. + **لا فواصل في `environment`.** يقسم Ingest هذا الحقل على الفواصل لبناء عوامل تصفيتها، وتخطي أي حدث تحتوي تسميته على واحدة — لذا يختفي التشغيل الكامل بصمت. اكتب `prod-eu` وليس `prod,eu`. - `configure(environment="prod,eu")` ترفع لذلك تكتشفها فوراً. `AGENTEYE_ENVIRONMENT` لا يمكنها أن ترفع — لا أحد يناديك — لذلك تحذر مرة واحدة وتعود إلى `dev`. + `configure(environment="prod,eu")` ترفع لذا تكتشف على الفور. `AGENTEYE_ENVIRONMENT` لا يمكن أن ترفع — لا أحد يناديك — لذا تحذر مرة واحدة وتعود إلى `dev`. -يتم صف الأحداث في الذاكرة والكتابة في الخلفية كل `flush_interval` ثانية، مع كتابة نهائية عند خروج المترجم. تفقد العملية المقتولة مباشرة أي شيء لم يتم كتابته بعد. +يتم وضع الأحداث في قائمة الانتظار في الذاكرة والكتابة في الخلفية كل `flush_interval` ثانية، مع كتابة نهائية عند خروج المفسّر. تخسر العملية المقتولة بشكل مباشر كل ما لم يتم كتابته بعد. ## الهوية -كل حدث ينتمي إلى جلسة ووكيل. **النطاقات تملأ كليهما**، لذا نادراً ما تمرر هما: +ينتمي كل حدث إلى جلسة ووكيل. **النطاقات تملأ كليهما**، لذا نادراً ما تمررهما: ```python with failproofai_sdk.session(): @@ -91,15 +97,15 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -تمرير `session_id` أو `agent_id` بشكل صريح لا يزال يعمل ويتفوق عليه. بدون ربط أو تمرير، يرفع الاستدعاء `TypeError` بدلاً من إصدار حدث قد تتجاهله Cloud بصمت. +لا يزال تمرير `session_id` أو `agent_id` بشكل صريح يعمل ويفوز. بدون ربط أو تمرير، تطرح المكالمة `TypeError` بدلاً من إصدار حدث سيتجاهله Cloud بصمت. - تركب الهوية على متغيرات السياق. تتابع مهام `asyncio` تلقائياً، لكن **ليس** الخيوط الجديدة — غلف العامل بـ `failproofai_sdk.propagate()` أو أحداثه تهبط بدون تعلق. + الهوية تركب على متغيرات السياق. تتبع مهام `asyncio` تلقائياً، لكن **ليس** الـ threads الجديدة — لف عامل في `failproofai_sdk.propagate()` أو أحداثه تهبط غير مرتبطة. ## فهرس الأحداث -خمسة عشر طريقة. معظمها يأتي في **أزواج** — تستدعي الفتاح، ثم الإغلاق، والمراقب يوقت الفجوة. +خمسة عشر طريقة. معظمها يأتي في **أزواج** — تستدعي الفاتح، ثم الإغلاق، وتوقيت الـ SDK الفجوة. | | يفتح | يغلق | | --- | --- | --- | @@ -110,39 +116,39 @@ with failproofai_sdk.session(): | **الخطافات** | `hook_triggered` | `hook_completed` | | **البشر** | `human_wait` | `human_input` | -ثلاثة تقف بمفردها: `error` و `human_pause` و `human_interrupt`. +ثلاثة تقف وحدها: `error` و `human_pause` و `human_interrupt`. -كل طريقة تأخذ أيضاً `session_id` و `agent_id`، والتي تملأها النطاقات لك. أي شيء يُترك كـ `None` يُسقط بدلاً من إرساله كـ JSON `null`، وكل طريقة ترجع `None`. +كل طريقة تأخذ أيضاً `session_id` و `agent_id`، التي تملأها النطاقات لك. أي شيء متروك كـ `None` يتم حذفه بدلاً من إرساله كـ JSON `null`، وكل طريقة تعود `None`. -| الطريقة | مطلوب | اختياري | +| الطريقة | مطلوبة | اختيارية | | --- | --- | --- | -| `agent_start` | — | `goal` و `parent_id` | -| `agent_end` | — | `outcome` و `summary` | -| `agent_pause` | `pause_id` | `reason` و `user_id` | -| `agent_resume` | `pause_id` | `reason` و `user_id` | -| `model_request` | — | `model` و `messages` و `system` و `tools` و `request_id` | -| `model_response` | — | `model` و `stop_reason` و `input_tokens` و `output_tokens` و `content` و `role` و `request_id` و `duration_ms` | -| `tool_use` | `tool_name` و `tool_call_id` | `input` | -| `tool_result` | `tool_name` و `tool_call_id` | `output` و `error` | -| `hook_triggered` | `hook_name` و `hook_id` | `trigger_event` و `input` | -| `hook_completed` | `hook_name` و `hook_id` | `outcome` و `output` و `error` | -| `error` | `error_type` و `message` | `traceback` | -| `human_wait` | `input_id` | `prompt` و `options` و `reason` | +| `agent_start` | — | `goal`, `parent_id` | +| `agent_end` | — | `outcome`, `summary` | +| `agent_pause` | `pause_id` | `reason`, `user_id` | +| `agent_resume` | `pause_id` | `reason`, `user_id` | +| `model_request` | — | `model`, `messages`, `system`, `tools`, `request_id` | +| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms` | +| `tool_use` | `tool_name`, `tool_call_id` | `input` | +| `tool_result` | `tool_name`, `tool_call_id` | `output`, `error` | +| `hook_triggered` | `hook_name`, `hook_id` | `trigger_event`, `input` | +| `hook_completed` | `hook_name`, `hook_id` | `outcome`, `output`, `error` | +| `error` | `error_type`, `message` | `traceback` | +| `human_wait` | `input_id` | `prompt`, `options`, `reason` | | `human_input` | `input_id` | `response` | -| `human_pause` | — | `reason` و `user_id` | -| `human_interrupt` | — | `reason` و `user_id` و `at_step` | +| `human_pause` | — | `reason`, `user_id` | +| `human_interrupt` | — | `reason`, `user_id`, `at_step` | - لتحديد تشغيل كفاشل، يجب أن تكون `outcome` واحدة من `failed` أو `error` أو `timeout` أو `rejected`. أي شيء آخر — بما في ذلك الحالة القريبة الفائتة `"failure"` — يُحسب كنجاح. + لوضع علامة على التشغيل كفاشل، يجب أن يكون `outcome` أحد `failed` أو `error` أو `timeout` أو `rejected`. أي شيء آخر — بما في ذلك `"failure"` القريب جداً — يعتبر نجاحاً. ## الاقتران والمدة -**قاعدة واحدة: أعط حدث الإغلاق نفس المعرّف مثل فاتحه.** هذا ما يقرنهما، وما يسمح للمراقب بتوقيت الفجوة. +**قاعدة واحدة: أعط حدث الإغلاق نفس معرّف الفاتح.** هذا هو ما يقرنهما، وما يسمح للـ SDK بتوقيت الفجوة. | الزوج | مطابقة على | | --- | --- | @@ -152,48 +158,48 @@ with failproofai_sdk.session(): | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**لا تمرر `duration_ms` بنفسك.** المراقب يقيسه، وتمريره يرفع `ValueError`. +**لا تمرر `duration_ms` بنفسك.** الـ SDK يقيسها، ومررها يرفع `ValueError`. -الاستثناء الوحيد هو `model_response`، حيث أنت فقط تعرف كمون المزود الحقيقي. مرر عدداً صحيحاً من الميلي ثانية — تمرير عدد عشري يرفع، لأن العمود عدد صحيح 32 بت وسيهبط فارغاً وإلا. +الاستثناء الوحيد هو `model_response`، حيث فقط أنت تعرف زمن انتظار المزود الحقيقي. مرّر عدداً صحيحاً من الملي ثواني — عائم يرفع، لأن العمود عدد صحيح 32 بت وسيهبط فارغاً وإلا. - + -- **المعرّفات لا تحتاج فقط أن تكون فريدة حسب النوع لكل جلسة.** استدعاء أداة وخطاف يمكنهما مشاركة واحد؛ جلستان تعمل مرة واحدة يمكنهما إعادة استخدام نفس المعرّفات بدون تصادم. -- **لا تقتصر على وكيل.** زوج مفتوح تحت وكيل واحد ومغلق تحت آخر لا يزال يطابق — وهي الحالة الطبيعية في الكود متعدد الوكلاء. -- **`request_id` اختياري لكن موصى به.** بدونه، أحداث النموذج تقترن بالترتيب الذي تصل به، لذا استدعاءان متزامنان في نفس الوكيل يمكنهما عدم الاقتران بشكل صحيح. -- **زوج منقسم عبر العمليات** لا يزال يطابق في Cloud، لكن المراقب لا يمكنه توقيت ذلك — لا شيء في أي عملية رأى كلا النصفين. -- **بحد أقصى 10،000 فاتح ينتظرون إغلاق في وقت واحد.** بعد ذلك الأقدم يُسقط، لذا تسرب لا يمكن أن ينمو بدون حد. +- **المعرّفات تحتاج فقط أن تكون فريدة لكل نوع، لكل جلسة.** يمكن لاستدعاء أداة وخطاف أن يشاركا واحداً؛ جلستان تعملان في نفس الوقت يمكن أن تعيد استخدام نفس المعرّفات بدون اصطدام. +- **لم يتم نطاقها لوكيل.** زوج مفتوح تحت وكيل واحد ومغلق تحت آخر لا يزال يطابق — وهي الحالة الطبيعية في كود متعدد الوكلاء. +- **`request_id` اختياري ولكن موصى به.** بدونه، تقترن أحداث النموذج بترتيب وصولها، لذا يمكن لمكالمتي متزامنة في نفس الوكيل أن تخطئا في الاقتران. +- **زوج مقسوم عبر العمليات** لا يزال يطابق في Cloud، لكن الـ SDK لا يمكنه توقيته — لم تر أي عملية كلا النصفين. +- **على الأكثر 10,000 فاتح ينتظر إغلاقاً في نفس الوقت.** بعد ذلك الأقدم يتم حذفه، لذا التسريب لا يمكن أن ينمو بدون حد. ## حقولك الخاصة -أي كلمة أساسية إضافية تمررها يتم تخزينها مع الحدث: +أي كلمة مفتاحية إضافية تمررها يتم تخزينها مع الحدث: ```python failproofai_sdk.event.tool_use( tool_name="search", tool_call_id="c1", - fw_tenant="acme", fw_region="eu-west-1", # خاصتك + fw_tenant="acme", fw_region="eu-west-1", # حقولك الخاصة ) ``` -فضّل أنواع JSON إذا كنت تريد الاستعلام عنها لاحقاً. أي شيء آخر — UUID أو datetime أو `Decimal` أو set أو bytes أو كائن نموذج — يتم تخزينه كسلسلة. +فضّل أنواع JSON إذا كنت تريد الاستعلام عنها لاحقاً. أي شيء آخر — UUID أو datetime أو `Decimal` أو مجموعة أو bytes أو كائن نموذج — يتم تخزينه كسلسلة. - **ضع بادئة لأسماء حقولك.** الإضافات يتم تطبيقها أخيراً، لذا حقل يسمى `model` أو `tool_name` أو `outcome` يستبدل الحقيقي بصمت. محولات الإطار تستخدم `fw_`؛ افعل الشيء نفسه والشيء الوحيد الذي يمكن أن يتصادم. + **أضف بادئة لأسماء الحقول الخاصة بك.** يتم تطبيق الإضافات أخيراً، لذا حقل يسمى `model` أو `tool_name` أو `outcome` سيكتب فوق الحقل الحقيقي بصمت. المحولات الإطار تستخدم `fw_`؛ افعل الشيء ذاته ولا شيء يمكن أن يصطدم. - هذا هو أيضاً السبب في أن حقل اختياري مكتوب بخطأ لا يخطئ أبداً — إنه ببساطة يصبح حقل مخصص جديد. إذا كان حقل قياسي مفقوداً في Cloud، تحقق من الإملاء أولاً. + هذا هو أيضاً لماذا حقل اختياري مكتوب بشكل خاطئ لا ينتج خطأ — فقط يصبح حقل مخصص جديد. إذا كان حقل قياسي غائب في Cloud، تحقق من الإملاء أولاً. -هذه الأسماء الخمسة محجوزة ومرفوضة بشكل مباشر: `timestamp` و `session_id` و `agent_id` و `type` و `environment`. +هذه خمسة أسماء محجوزة ومرفوضة بشكل مباشر: `timestamp` و `session_id` و `agent_id` و `type` و `environment`. ## التسليم والتحقق - في **Observe → Events**، تحقق من وجود `agent_start` أولاً و `agent_end` أخيراً. ثم افتح **Observe → Sessions** وأكّد ظهور أحداث النموذج والأداة والبشر والخطاف والخطأ بالترتيب المقصود. استخدم معرّف الجلسة كمفتاح استكشاف الأخطاء الأساسي. + في **Observe → Events**، تحقق من وجود `agent_start` أولاً و `agent_end` موجود أخيراً. ثم افتح **Observe → Sessions** وأكد ظهور نموذج وأداة وإنسان وخطاف وأحداث خطأ بالترتيب المقصود. استخدم معرّف الجلسة كمفتاح استكشاف أخطاء أساسي. - + ```bash failproofai flush --wait --timeout 60 failproofai config --status @@ -203,14 +209,14 @@ failproofai_sdk.event.tool_use( -إذا كانت Cloud فارغة، افحص `$FAILPROOFAI_HOME/custom-agents/events`، وإلا `~/.failproofai/custom-agents/events`. ملفات JSONL تثبت إصدار المراقب؛ سبول متنام يشير إلى إعدادات المراقب أو التسليم، بينما سبول فارغ يشير إلى القياس أو عمر العملية. +إذا كانت Cloud فارغة، افحص `$FAILPROOFAI_HOME/custom-agents/events`، وإلا `~/.failproofai/custom-agents/events`. ملفات JSONL تثبت إصدار SDK؛ تشير مخزونة متنامية إلى إعدادات المُراقب أو التسليم، بينما تشير مخزونة فارغة إلى التجهيز أو عمر العملية. - افحص السبول فقط عندما يكون المراقب متوقفاً. بينما يعمل، يجمع ويحذف كل دفعة في ميلي ثانية، لذا قائمة الدليل تتسابق مع المجمع وتظهر أحداث أقل بكثير مما تم إصدارها. + افحص المخزن فقط عند توقف المُراقب. بينما يعمل، يجمع ويحذف كل دفعة خلال ملي ثانية، لذا قائمة الدليل تتنافس مع المجمّع وتظهر أحداثاً أقل بكثير مما تم إصدارها. -## منع الإخفاقات في وقت تشغيل مخصص +## منع الأخطاء في وقت تشغيل مخصص -استخدم النتائج القابلة للتدقيق والآثار المرتبطة لتعريف الإجراء غير الآمن والأدلة المطلوبة والاستجابة المقصودة. يجب أن تعريض تكامل الإنفاذ المخصص الإجراء قبل التنفيذ، وتمرير إدخاله المنظم إلى محرك السياسة، وتطبيق قرار allow أو instruct أو deny الناتج. +استخدم نتائج التدقيق والأثار المرتبطة لتحديد الإجراء غير الآمن والدليل المطلوب والرد المقصود. يجب أن يكشف التكامل الإنفاذ المخصص الإجراء قبل التنفيذ، ومرّر مدخلاته المنظمة إلى محرك السياسة، وطبّق قرار allow أو instruct أو deny الناتج. -[اتصل بـ Failproof AI](mailto:support@befailproof.ai) وسنساعدك على ربط نموذج وقت التشغيل الخاص بك وحدود الأداة والدورة الحياتية بخطافات السياسة، ثم التحقق من التكامل معك. \ No newline at end of file +[تواصل مع Failproof AI](mailto:support@befailproof.ai) وسيساعدك في ربط نموذج وقت التشغيل المخصص وحدود الأداة والدورة الحياة إلى خطافات السياسة، ثم التحقق من التكامل معك. \ No newline at end of file diff --git a/docs/ar/reference/evaluator-sdk.mdx b/docs/ar/reference/evaluator-sdk.mdx index 2084d110..14f02230 100644 --- a/docs/ar/reference/evaluator-sdk.mdx +++ b/docs/ar/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "أنشئ خدمة تقيّم جلسات Failproof AI بشكل متزامن أو غير متزامن." +description: "شغّل عامل التقييم الخاص بك، لقضاة LLM وأي شيء آخر لا يمكن لـ Python المستضاف القيام به." icon: "gauge" --- -يستقبل المقيّم جلسة وكيل مكتملة ويرجع إشارات الجودة التي تهمك: درجات رقمية، وتفسير لكل درجة، وملخص اختياري. يخزّن Failproof AI هذه النتائج بجانب التتبع ويرسمها عبر الوكلاء والبيئات. +يقوم Evaluator SDK بتشغيل التقييمات على بنيتك التحتية الخاصة. يسجّل عاملك التقييمات لديه في Failproof AI، ويستحوذ على الجلسات عند انتهائها، ويسجّلها، ويرسل النتائج، كل ذلك عبر HTTPS الصادرة: لا شيء يتصل بها. استخدمه فيما لا يمكن [لـ Python المستضاف](/ar/evaluations/write) القيام به — قضاة LLM ، استدعاءات النموذج، الحزم، الأسرار، والوصول إلى الشبكة. تظهر نتائجه بجانب النتائج المستضافة على [صفحة التقييمات](/ar/sessions/evaluations)، موسومة بـ **customer**. -## إعداد مقيّم +يتم شحنه في `failproofai-sdk`، تحت `failproofai_sdk.evaluator`؛ استيراد SDK التتبع لا يحمّله. - - - ثبّت SDK والخادم المستخدم لتشغيله. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - أنشئ ملف `evaluator.py`. يتحقق هذا المثال مما إذا كانت الجلسة تحتوي على أي استدعاءات أداة فاشلة. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - عيّن رمزًا مشتركًا، شغّل المقيّم، وتأكد من استجابة نقطة نهاية الصحة. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - في محطة طرفية أخرى: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## ربط المقيّم بـ Failproof AI +```bash +pip install failproofai-sdk +``` -1. انشر المقيّم على عنوان URL بروتوكول HTTPS يمكن الوصول إليه بواسطة Failproof AI Cloud. -2. كوّن `EVALUATOR_ENDPOINT` باستخدام هذا العنوان وعيّن `EVALUATOR_TOKEN` للرمز نفسه الذي يستخدمه المقيّم. بالنسبة للسحابة المُدارة، اتصل بـ [support@befailproof.ai](mailto:support@befailproof.ai) لتكوين الاتصال. -3. شغّل عملية تقييم وتأكد من ظهور درجاتها في Failproof AI. +## اكتب التقييمات - - - افتح جلسة مكتملة ضمن **Observe → Sessions** وحدّد **Run evaluation** إذا لم يتم تقييمها تلقائيًا. راجع الحالة والدرجات والتفسير والملخص في لوحة **Evaluation** الخاصة بالجلسة. +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - استخدم **Observe → Evaluations** لمقارنة الدرجات عبر الوكلاء أو البيئات. استخدم **Observe → Metrics** لقياسات الكمون والتكلفة والرمز وغيرها من المقاييس الرقمية. - ابدأ بجلسة واحدة للتأكد من أن المقيّم أرجع مفاتيح الدرجات المتوقعة وتفسيرًا مفيدًا لهذا التشغيل المحدد. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![عرض تفاصيل جلسة يعرض درجات التقييم والتفسير بجانب تتبعها.](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` يسجّل تقييماً. المفتاح هو ما تتخطط نتائجه تحته؛ غيّر الإصدار كلما تغيرت المنطق، وكل نتيجة تحتفظ بالإصدار الذي أنتجها. عامل واحد يحمل ما يصل إلى 100 تقييم. +- `result_kind` هو `"score"` ما لم تقل خلاف ذلك. للتقييم `"metric"` أو `"assertion"`، سمّ إدخال `metrics` أو `assertions` واحد باسم المفتاح: هذا الإدخال هو نتيجته. +- `when` يقرر ما إذا كانت جلسة قابلة للتطبيق. أرجع `ConditionResult(False, "")` لتخطي واحدة، والسبب يتم تسجيله. +- يمكن أن يكون التقييم دالة عادية أو `async`، و `timeout_seconds` يحدده. +- مفاتيح الحمل الجديد — `tool_name` و `response` و `content` أعلاه — هي ما ترسله وكلاؤك، لذا اقرأها من جلسة حقيقية. - عندما تبدو النتائج الفردية صحيحة، استخدم لوحة تحكم التقييم لمقارنة تلك الدرجات عبر الزمن وعبر الوكلاء أو البيئات. +## شغّل العامل - ![لوحة تحكم الجودة ترسم درجات المقيّم عبر الزمن.](/images/dashboard/dashboard-quality.png) +ضع مفتاحاً بإذن `evaluations:run`، تم إنشاؤه تحت **Administration → Keys**، في `FAILPROOFAI_EVALUATOR_TOKEN` — اضبطه من متجر الأسرار بدلاً من كتابته في أمر — وابدأ العامل: - يجب أن تستخدم الرسم البياني الصحي أسماء درجات مستقرة؛ تغيير مفتاح ينشئ سلسلة منفصلة. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -بالنسبة لنسخة السحابة المُستضافة ذاتيًا، يتم تعطيل التقييم التلقائي حتى يتم تعيين `EVALUATOR_ENDPOINT` على عملية الخادم. أعد تشغيل الخادم بعد تغيير متغيرات بيئة المقيّم. +بدون كتلة `__main__`، `python -m failproofai_sdk.evaluator evaluator:app` يفعل الشيء نفسه. -تعرّض الخدمة `GET /health` و`GET /config` و`POST /evaluate` وبشكل اختياري `GET /evaluate/{job_id}`. أرجع `JobPending` للعمل غير المتزامن وسجّل `@app.job_lookup` لكي يتمكن Failproof AI من الاستقصاء عنه. +| المتغير | الافتراضي | الغرض | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | مطلوب | حيث يوجد Failproof AI: `https://app.befailproof.ai` للسحابة. HTTPS ما لم يشير إلى loopback | +| `FAILPROOFAI_EVALUATOR_TOKEN` | مطلوب | مفتاح بـ `evaluations:run` | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | يسمّي هذا العامل | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | الجلسات التي يسجّلها هذا العامل في وقت واحد | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | المهلة الزمنية لكل طلب إلى Failproof AI | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | المدة التي ينتظرها العامل المتوقف عن التشغيل للتشغيل قيد الطيران | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | السماح بـ HTTP عادي لعنوان URL ليس loopback — انظر التحذير أدناه | +| `FAILPROOFAI_EVALUATOR_MODULE` | لا شيء | `module:attribute` لـ `python -m failproofai_sdk.evaluator` | -عند تكوين رمز، جميع المسارات ما عدا الصحة تتطلب الرمز المشفر نفسه الذي يرسله Failproof AI باعتباره `EVALUATOR_TOKEN`. + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` يرسل كل شيء بنص واضح. يحمل العامل `FAILPROOFAI_EVALUATOR_TOKEN` كرأس `Authorization: Bearer` في كل طلب، والنسخ المرسلة التي يجلبها هي الجلسات نفسها — لذا يقرأ أي شخص على المسار كلاهما، والمفتاح الذي يقرؤونه يشغّل التقييمات حتى تقوم بتدويره. استخدمه فقط على شبكة تطوير معزولة. في كل مكان آخر، يجب أن يكون العنوان HTTPS؛ loopback لا يحتاج إلى أي علم. + -## أنواع SDK +## أنواع النتائج | النوع | الحقول | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## المزخرفات والمسارات +| `Score` | `value` (0 إلى 1)، `passed`، `unit` (الافتراضي `ratio`)، `display_value`، `description` | +| `Metric` | `value`، `unit`، `display_value`، `description` | +| `Assertion` | `passed`، `description` | +| `EvalResult` | `score`، `metrics`، `assertions`، `reasoning`، `summary`، `labels` | +| `ConditionResult` | `applicable`، `reason_code` | -| المزخرف | المسار | مطلوب | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | نعم | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | عند إرجاع `JobPending` | -| `@app.config` | `GET /config` | لا | - -يحدّ SDK أجسام طلبات التقييم بـ 25 ميجابايت. يتم تجاهل حقول الطلب غير المعروفة بحيث تبقى الخدمات متوافقة عند نمو عقد الحدث. +يحمل `EvalResult` على الأقل درجة واحدة أو متري أو تأكيد، وبحد أقصى 25، كل واحد تحت مفتاح فريد. -## إرجاع العمل غير المتزامن +## الجلسة -استخدم `JobPending` عندما لا يمكن إنهاء التقييم داخل طلب واحد. معرّف الوظيفة معتم لـ Failproof AI ويجب أن يبقى قابلًا للحل بواسطة خدمتك حتى يتم جمع النتيجة أو انتهاء انتظار الخادم. - -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| الحقل أو الطريقة | يعطيك | +| --- | --- | +| `session_id` و `agent_id` و `environment` | هوية الجلسة | +| `started_at` و `ended_at` | متى بدأت وانتهت | +| `event_count` و `events` | النسخة المرسلة الكاملة والمرتبة | +| `count(event_type)` | عدد الأحداث من ذلك النوع التي تحتويها | +| `events_of_type(event_type)` | تلك الأحداث، بالترتيب | -يتم اختيار وتيرة الاستقصاء بهذا الترتيب: `JobPending.next_poll_secs` و`EvaluatorConfig.default_poll_interval_secs` ثم `EVALUATOR_POLLING_INTERVAL_SECS` الخاص بالخادم. يتم كبح القيم بين ثانية واحدة وساعة واحدة. الحد الأقصى الافتراضي لساعة الحائط للخادم هو ساعة واحدة. +يحمل كل حدث `id` و `ts` و `event_type` و `payload`. -## حقول الطلب والاستجابة +## مقيّم الإرث -| الحقل | النوع | ملاحظات | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | حاليًا `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | هوية الجلسة والبيئة. | -| `started_at` | `datetime` | طابع زمني للحدث الأول. | -| `ended_at` | `datetime \| None` | موجود عند بث الجلسة حدث نهاية. | -| `events` | `list[AgentEvent]` | تدفق الحدث المكتمل والمرتب. | -| `AgentEvent.id` | `int` | معرّف صف حدث النظام الخلفي. | -| `AgentEvent.ts` | `datetime` | طابع زمني للحدث. | -| `AgentEvent.event_type` | `str` | عائلة الحدث مثل `tool_use`. | -| `AgentEvent.payload` | `dict[str, Any]` | حمولة الحدث الكاملة. | -| `EvalResponse.scores` | `dict[str, float] \| None` | الأبعاد الرقمية المرسومة في التقييمات. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | تفسيرات لكل درجة؛ يجب أن تعكس المفاتيح `scores`. | -| `EvalResponse.summary` | `str \| None` | السرد التقييمي الشامل. | - -## إعدادات مشغّل الخادم - -التقييم التلقائي يشمل الانتشار كله ويبقى معطلًا عند غياب `EVALUATOR_ENDPOINT`. - -| المتغير | الافتراضي | الغرض | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | غير معيّن | عنوان URL الأساسي لخدمة المقيّم. | -| `EVALUATOR_TOKEN` | غير معيّن | الرمز المشفر المشترك مع `Evaluator(token=...)`. | -| `EVALUATOR_WORKERS` | `2` | عمال المُرسل المتزامنون. | -| `EVALUATOR_CLAIM_BATCH` | `4` | الجلسات المطالب بها لكل تمرير مُرسل. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | وتيرة الاستقصاء غير المتزامن الاحتياطية. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | انتظار الطلب لكل مقيّم. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | محاولات التسليم قبل الفشل النهائي. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | وتيرة التحديث لـ `/config`. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | الحد الأقصى لوقت ساعة الحائط للاستقصاء غير المتزامن. | - -يمكن للخادم أيضًا تقييد المؤسسات التي تستخدم المقيّم العام لنشر شامل. تعامل مع تغييرات نقطة النهاية والرمز والمحاولة والبوابة التنظيمية كتكوين مشغّل وأعد تشغيل أو نشر الخادم بعد تغييرها. - -## الأمان والعمليات - -- ضع المقيّم خلف HTTPS عندما تعبر حركة المرور حدود الشبكة الموثوقة. -- كوّن رمزًا مشفرًا غير فارغ واحفظه متطابقًا على كلا الخدمتين. -- لا تسجّل الرمز أو المحفوظات الحساسة الكاملة من حمولات الطلبات. -- اجعل معالجات المتزامن قابلة للإدراك؛ قد تكرر المحاولات مرة أخرى الطلب. -- احفظ حالة الوظيفة غير المتزامنة خارج ذاكرة العملية في الإنتاج. -- أرجع مفاتيح درجات مستقرة. إعادة تسمية مفتاح تنشئ سلسلة رسم بياني جديدة بدلاً من تغيير القديم. - -ينبعث SDK من السجلات البنيوية لدورة الحياة مثل `eval received` و`eval responded` و`job lookup` و`config returned` و`auth rejected` واستثناءات المعالج. لا يكوّن معالجات السجلات؛ استخدم تكوين السجلات لتطبيق المضيف. \ No newline at end of file +يتم إيقاف Evaluator SDK السابق — خدمة HTTP استدعاها Failproof AI على `EVALUATOR_ENDPOINT`، والإجابة على `/evaluate` والتحقيق من خلال `JobPending` —. قم ببناء مقيّمين جدد على هذا العامل؛ يمكن لمشغلي مثيل ذاتي الاستضافة الذي يقوم بتشغيل خدمة قديمة أن يحتفظوا بها خلال الانتقال. \ No newline at end of file diff --git a/docs/ar/reference/failproof-cli.mdx b/docs/ar/reference/failproof-cli.mdx index 1339a14c..2de3a992 100644 --- a/docs/ar/reference/failproof-cli.mdx +++ b/docs/ar/reference/failproof-cli.mdx @@ -1,86 +1,104 @@ --- -title: "واجهة أوامر Failproof AI" -description: "ثبّت الخطافات، أدِر السياسات المحلية، اتصل بالسحابة، وشغّل مراقب الخادم المحلي." +title: "Failproof AI CLI" +description: "تثبيت الخطافات، وإدارة السياسات المحلية، والاتصال بـ Cloud، وتشغيل مستند الخدمة المحلي." icon: "terminal" --- -ثبّت واجهة الأوامر المحلية باستخدام `npm install -g failproofai`. شغّلها بدون معاملات لفتح لوحة تحكم السياسات المحلية. +ثبّت واجهة سطر الأوامر المحلية باستخدام `npm install -g failproofai`. قم بتشغيلها بدون معاملات لفتح لوحة معلومات السياسة المحلية. -تتطلب الحزمة Node.js 20.9 أو إصدار أحدث. يدعم Bun 1.3 أو إصدار أحدث للتطوير وتثبيتات المصدر. `failproofai configure` و`failproofai setup` هما أسماء مستعارة لـ `failproofai config`؛ `failproofai p` اسم مستعار لـ `failproofai policies`. +تتطلب الحزمة Node.js 20.9 أو أحدث. يتم دعم Bun 1.3 أو أحدث للتطوير والتثبيتات من المصدر. `failproofai configure` و `failproofai setup` هما اسمان مستعاران لـ `failproofai config`. `failproofai policy` و `failproofai pack` و `failproofai p` هي جميعاً تهجئات لـ `failproofai policies` — كانت الحزم والسياسات الفردية ثلاث أوامر لفكرة واحدة وهي الآن واحدة. التهجئات الأقدم لا تزال تعمل، مع استثناءين: `pack list ` أصبحت الآن `policies show `، و `pack build` أصبحت الآن `publish`. ## إعداد جهاز +ثبّت واجهة سطر الأوامر، ثم اقرأ مفتاح الجهاز في قذيفة النظام. `read -s` يأخذها عند مطالبة لا تصدر صدى، لذا لا تظهر أبداً في أمر: + ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +ثم أعد إعداد الجهاز واختر ما يفرضه: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` -شغّل `failproofai` بدون معاملات لفتح لوحة تحكم السياسات المحلية. +`failproofai config` هو كل الإعداد: يثبّت خدمة `failproofaid` (الجذر مرة واحدة، عبر `sudo -n` — لا يوجد أبداً مطالبة كلمة مرور تفاعلية)، ويربط الخطافات في كل واجهة سطر أوامر وكيل يجدها، ويتصل بـ Cloud عند توفر مفتاح. بدون terminal — CI، حاوية، وكيل يقودها — يطبق بدلاً من السؤال، ويخرج 1 إذا لم يحدث أي شيء طُلب منه القيام به. + +لا يختار أي سياسات. هذه هي وظيفة الأمر الثاني، وبدونها لا يفرض جهاز تم تكوينه حديثاً سوى الحارس الذي يعمل دائماً. + +فضّل متغير البيئة على `--token`: معامل سطر أوامر قابل للقراءة من `ps` بواسطة كل مستخدم على الصندوق. هذا كل ما يحميه المتغير — مفتاح يُكتب في أي أمر، بما في ذلك `export`، لا يزال ينتهي به الحال في سجل shell، ولهذا السبب يتم قراءته باستخدام `read -s` أعلاه. في CI، اضبطه من مخزن السرية واحتفظ بتتبع shell (`set -x`) مُيقِّفاً، أو سيطبع التتبع المفتاح. + + + `--connect ` يسجل جهاز **تم إعداده بالفعل**. يعود بمجرد نجاح التسجيل — لا يثبّت مستند الخدمة ولا يربط أي خطافات. استخدم `failproofai config` البسيط (أو `failproofai config --token `) على جهاز لم يتم إعداده بعد، أو سيبدو كمتصل أثناء جمع وعدم فرض أي شيء. + + +قم بتشغيل `failproofai` بدون معاملات لفتح لوحة معلومات السياسة المحلية. | الأمر | النتيجة | | --- | --- | -| `failproofai config` | شغّل إعداد الجهاز بشكل تفاعلي | -| `failproofai config --connect --token ` | اتصل بسحابة الاستقبال وتسليم السياسات | -| `failproofai config --status` | أظهر حالة الاتصال والمراقب والتسليم والإيقاف المؤقت | -| `failproofai policies` | اسرد السياسات المدمجة والمخصصة والاتفاقية والحزمة والمُدارة من السحابة | -| `failproofai policies --install` | ثبّت الخطافات وفعّل السياسات | -| `failproofai policy add ` | فعّل سياسة واحدة — مدمجة أو `:` من حزمة مثبّتة | -| `failproofai policy remove ` | عطّل سياسة واحدة، نفس الأسماء | -| `failproofai policies --uninstall` | عطّل السياسات أو أزل خطافات الأجهزة | -| `failproofai pack list` | اسرد حزم السياسات المثبّتة وكل سياسة تحملها | -| `failproofai pack add ` | ثبّت حزمة سياسات من إصدار GitHub؛ عدم وجود وسم يأخذ الأحدث ويثبّته | -| `failproofai pack add --bundled` | ثبّت السياسات المدمجة كحزمة، من هذه الحزمة، بدون شبكة | -| `failproofai pack build ` | أنشئ الأصول الثلاثة للإصدار لحزمة خاصة بك | -| `failproofai pack remove ` | عطّل حزمة مثبّتة | -| `failproofai audit` | امسح السجل المحلي للوكيل وافتح طريقة العرض المحلية للتدقيق | -| `failproofai audit --schedule [days] --email
` | جدولة عمليات الفحص المحلية المتكررة وأرسل النتائج بالبريد الإلكتروني | -| `failproofai audit --status` | أظهر عنوان التقرير والفاصل الزمني والفحص المجدول التالي | -| `failproofai audit --no-schedule` | أوقف الفحوصات المتكررة دون حذف سجل التدقيق | -| `failproofai harness list` | اسرد مسارات الالتقاط الإضافية | -| `failproofai flush --wait` | اسلم ملف الأحداث الحالي | -| `failproofai backfill --since 30d` | أعد قراءة السجل المُمرر مسبقاً | -| `failproofai config --pause [duration]` | أوقف جلسة محلية واحدة مؤقتاً لمدة 30 دقيقة بشكل افتراضي، حتى 8 ساعات | -| `failproofai config --resume` | استئنف جلسة محلية موقوفة مؤقتاً؛ أضف `--all` لمسح جميع الإيقافات المؤقتة | -| `failproofai update` | أنهِ ترحيلات الحزمة وحدّث المراقب | -| `failproofai migrate --dry-run` | معاينة أو تشغيل ترحيلات تخطيط الصفحة الرئيسية المعلقة | -| `failproofai uninstall` | أزل الخطافات والمراقب قبل إزالة الحزمة | -| `failproofai --version` | اطبع إصدار الحزمة المثبّتة | -| `failproofai --help` | أظهر الأوامر والاستخدام العام | - -## أعلام الإعدادات +| `failproofai config` | إعداد الجهاز: الوكلاء، مستند الخدمة، وCloud عند وجود مفتاح | +| `failproofai config --token ` | الإعداد والاتصال في مرة واحدة، بدون السؤال عن أي شيء | +| `failproofai config --connect ` | تسجيل جهاز **تم إعداده بالفعل** — بدون مستند خدمة، بدون خطافات | +| `failproofai config --status` | عرض حالة الاتصال، مستند الخدمة، الإيصال، والتعليق | +| `failproofai policies` | قائمة السياسات المدمجة، المخصصة، الاتفاقية، الحزمة، والمدارة بواسطة Cloud | +| `failproofai policies --install` | ربط الخطافات في واجهات سطر أوامر الوكيل. لا يفعّل أي سياسة بمفردها | +| `failproofai policies add ` | تفعيل سياسة واحدة — مدمجة، أو `:` من حزمة مثبتة | +| `failproofai policies remove ` | تعطيل سياسة واحدة، نفس التسمية | +| `failproofai policies --uninstall` | تعطيل السياسات أو إزالة خطافات الهيكل | +| `failproofai policies show /` | ما تحمله حزمة، المقروءة من بيانات التعريف الخاصة بها، قبل أخذها | +| `failproofai policies show / --releases` | كل إصدار نُشر، وأيها موجود هنا | +| `failproofai policies add ` | تثبيت حزمة سياسة من إصدار GitHub؛ بدون علامة تأخذ الأحدث وتثبتها | +| `failproofai publish` | شحن سياساتك الخاصة كحزمة؛ `--init` يكتب واحدة للبدء منها | +| `failproofai policies remove ` | إلغاء تثبيت حزمة | +| `failproofai audit` | مسح سجل الوكيل المحلي وفتح عرض التدقيق المحلي | +| `failproofai audit --schedule [days] --email
` | جدولة الفحوصات المحلية المتكررة وإرسال نتائجها عبر البريد الإلكتروني | +| `failproofai audit --status` | عرض عنوان التقرير والفاصل الزمني والفحص المجدول التالي | +| `failproofai audit --no-schedule` | إيقاف الفحوصات المتكررة بدون حذف سجل التدقيق | +| `failproofai harness list` | قائمة مسارات الالتقاط الإضافية | +| `failproofai flush --wait` | تسليم ملف الحدث الحالي | +| `failproofai backfill --since 30d` | إعادة قراءة السجل الذي تم تمريره مسبقاً | +| `failproofai config --pause [duration]` | إيقاف جلسة محلية واحدة لمدة 30 دقيقة افتراضياً، حتى 8 ساعات | +| `failproofai config --resume` | استئناف جلسة محلية مُعلقة واحدة؛ أضف `--all` لمسح جميع الإيقافات | +| `failproofai update` | إنهاء عمليات ترحيل الحزم وتحديث مستند الخدمة | +| `failproofai migrate --dry-run` | معاينة أو تشغيل عمليات ترحيل التخطيط المنزلي المعلقة | +| `failproofai uninstall` | إزالة الخطافات ومستند الخدمة قبل إزالة الحزمة | +| `failproofai --version` | طباعة إصدار الحزمة المثبتة | +| `failproofai --help` | عرض الأوامر والاستخدام العام | + +## أعلام التكوين | العلم | الاستخدام | | --- | --- | -| `--connect --token ` | اتصل بشكل غير تفاعلي | -| `--machine-id ` | عيّن معرّف الجهاز الثابت | -| `--machine-label ` | عيّن أو غيّر تسمية لوحة التحكم | -| `--no-transcripts` | أرسل القرارات بدون محتوى النسخة | -| `--disconnect` | أوقف سحب سياسة السحابة وتسليم الأحداث | -| `--status` | أظهر حالة الجهاز الحالية | -| `--pause [duration]` | أوقف أحدث جلسة في الدليل الحالي مؤقتاً؛ يقبل الثواني أو الدقائق أو الساعات ويستخدم 30 دقيقة بشكل افتراضي | -| `--resume` | أنهِ إيقاف مطابق مبكراً | -| `--session ` | استهدِف جلسة صريحة للإيقاف المؤقت أو الاستئناف | +| `--token ` | الإعداد والاتصال بدون تفاعل؛ اقرأ أيضاً من `FAILPROOFAI_CLOUD_TOKEN` | +| `--url ` | الاتصال بمكان آخر غير `app.befailproof.ai`؛ اقرأ أيضاً من `FAILPROOFAI_CLOUD_URL` | +| `--connect ` | التسجيل فقط، على جهاز تم إعداده بالفعل. يتجاوز مستند الخدمة وكل خطاف | +| `--machine-id ` | ضبط معرّف الجهاز المستقر | +| `--machine-label ` | إعادة تسمية جهاز **مرتبط بالفعل**. بمفردها لا تشغّل أبداً الإعداد، لذا أضفها بعد `failproofai config`، وليس أثناء | +| `--no-transcripts` | إرسال القرارات بدون محتوى النصوص | +| `--disconnect` | إيقاف سحب سياسات Cloud وإيصال الأحداث | +| `--status` | عرض حالة الجهاز الحالية | +| `--pause [duration]` | إيقاف أحدث جلسة في الدليل الحالي؛ يقبل ثواني أو دقائق أو ساعات ويتعطل إلى 30 دقيقة | +| `--resume` | إنهاء الإيقاف المطابق مبكراً | +| `--session ` | استهدف جلسة صريحة للإيقاف أو الاستئناف | | `--all` | مع `--resume`، أنهِ كل إيقاف نشط | -تعليق الجلسات المحلية يوقف السياسات المدمجة والمخصصة والاتفاقية والحزمة لجلسة واحدة. تنتهي دائماً ولا تعطّل السياسات المُدارة من السحابة. `block-failproofai-commands` — والتي تكون مفعّلة دائماً ولا يمكن تعطيلها أو إيقافها مؤقتاً بنفسها — تمنع وكيلاً مزوداً بأجهزة استشعار من استخدام هذا الثغرة بنفسها. +تعليقات الإيقاف المحلية تعلق السياسات المدمجة والمخصصة والاتفاقية والحزمة لجلسة واحدة. تنتهي دائماً ولا تعطّل سياسات Cloud المدارة. `block-failproofai-commands` — التي تكون قيد التشغيل دائماً ولا يمكن تعطيلها أو إيقافها بمفردها — تمنع وكيل معدّ من استخدام هذه الفتحة الخلفية بنفسه. -## أعلام السياسات +## أعلام السياسة | العلم | الاستخدام | | --- | --- | -| `--install`, `-i` | فعّل السياسات وثبّت خطافات الأجهزة | -| `--uninstall`, `-u` | عطّل السياسات أو أزل الخطافات | -| `--cli ` | استهدِف جهاز أو أكثر من الأجهزة المدعومة | -| `--scope user\|project\|local\|all` | اختر نطاق الإعدادات؛ `all` للإلغاء | -| `--beta` | اشمل سياسات تجريبية | -| `--custom`, `-c ` | تحقق وحمّل ملف سياسة مخصص؛ قابل للتكرار | +| `--install`, `-i` | تثبيت خطافات الهيكل. الأسماء بعده تفعّل تلك السياسات؛ بدونها، لا تغييرات السياسة | +| `--uninstall`, `-u` | تعطيل السياسات أو إزالة الخطافات | +| `--cli ` | استهدف هيكل واحد أو أكثر مدعوم | +| `--scope user\|project\|local\|all` | اختر نطاق التكوين؛ `all` للإلغاء | +| `--beta` | تضمين السياسات التجريبية | +| `--custom`, `-c ` | التحقق من صحة وتحميل ملف سياسة مخصص؛ قابل للتكرار | -## أعلام التسليم والصيانة +## أعلام الإيصال والصيانة | الأمر | الأعلام | | --- | --- | @@ -90,9 +108,9 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -يجب تشغيل `failproofai update` بعد `npm install -g failproofai@latest`؛ تقوم بإجراء ترحيلات تخطيط الصفحة الرئيسية وتثبيت ثنائي المراقب المطابق وإعادة تشغيل الخدمة. `--no-daemon` ينفذ فقط ترحيل التخطيط. +يجب تشغيل `failproofai update` بعد `npm install -g failproofai@latest`؛ يُجري ترحيلات التخطيط المنزلي، وينصّب الثنائي مستند الخدمة المطابق، ويعيد تشغيل الخدمة. `--no-daemon` يؤدي فقط ترحيل التخطيط. -## مسارات الأجهزة +## مسارات الهيكل ```text failproofai harness list [harness] @@ -100,11 +118,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -أسماء الأجهزة المدعومة هي `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, و`goose`. +أسماء الهيكل المدعومة هي `claude`، `codex`، `copilot`، `cursor`، `opencode`، `pi`، `hermes`، `openclaw`، `factory`، `devin`، `antigravity`، و `goose`. -تضع التسميات مساحة أسماء معرّفات الوكيل المشتقة عند احتواء جذرين على نسخ من نفس المشروع. يتم رفض الجذور المتداخلة والتسميات المكررة لمنع الجمع المكرر أو فساد المؤشر. إعادة تحميل إعدادات المسارات الإضافية بدون إعادة تشغيل المراقب. +معاملات مساحات أسماء معرّفات الوكيل المشتقة عندما يحتوي جذران على نسخ من نفس المشروع. يتم رفض الجذور المتداخلة والتسميات المكررة لمنع الجمع المكرر أو تلف المؤشر. إعادة تحميل تكوين المسار الإضافي بدون إعادة تشغيل مستند الخدمة. -يمكن لبيئات الحاويات استبدال المسارات الإضافية المكونة بملف بمتغير مفصول بفواصل يُسمى `FAILPROOFAI__EXTRA_PATHS`، على سبيل المثال: +يمكن لبيئات الحاويات استبدال المسارات الإضافية المكوّنة بملف بمتغير فاصل بفواصل يُسمى `FAILPROOFAI__EXTRA_PATHS`، على سبيل المثال: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -112,26 +130,28 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## متغيرات البيئة -استخدم ملفات الإعدادات للسلوك الدائم للجهاز. متغيرات البيئة مفيدة للغاية للحاويات والاختبارات والعملية الواحدة. +استخدم ملفات التكوين لسلوك الجهاز المستمر. متغيرات البيئة مفيدة بشكل أساسي للحاويات والاختبارات والعملية الواحدة. | المتغير | الاستخدام | | --- | --- | -| `FAILPROOFAI_HOME` | إعادة تحديد موقع تخطيط `~/.failproofai` الكامل | -| `FAILPROOFAI_LOG_LEVEL` | عيّن مستوى تفاصيل السجل المحلي | -| `FAILPROOFAI_HOOK_LOG_FILE` | اكتب تشخيصات الخطافات إلى ملف محدد | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | عطّل قياس الاستخدام المجهول لهذه العملية | -| `FAILPROOFAI_NO_FIRST_RUN=1` | تخطّ إعداد التشغيل الأول التفاعلي | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | تخطّ التدقيق المحلي بعد الإعداد | -| `FAILPROOFAI_LLM_BASE_URL` | جاوز نقطة نهاية متوافقة مع OpenAI يستخدمها سياسات LLM | -| `FAILPROOFAI_LLM_API_KEY` | وفّر مفتاح API الذي تستخدمه سياسات LLM | -| `FAILPROOFAI_LLM_MODEL` | اختر النموذج الذي تستخدمه سياسات LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | حدّد تحميل وحدة السياسة المخصصة | -| `FAILPROOFAI_NO_DOWNLOAD=1` | رفض جلب الحزم والملفات الثنائية للمراقب؛ ما هو مثبّت يستمر في الإنفاذ | +| `FAILPROOFAI_CLOUD_TOKEN` | مفتاح Cloud، بدلاً من `--token`. فضّل هذا: معامل قابل للقراءة من `ps` بواسطة كل مستخدم. اضبطه باستخدام `read -s` أو من مخزن سرية CI، لا بطريقة كتابة المفتاح في أمر، الذي ينتهي به الحال في سجل shell في كلا الحالتين | +| `FAILPROOFAI_CLOUD_URL` | عنوان URL لـ Cloud، بدلاً من `--url`. نفس المتغير الذي يقرأه مستند الخدمة | +| `FAILPROOFAI_HOME` | نقل التخطيط `~/.failproofai` الكامل | +| `FAILPROOFAI_LOG_LEVEL` | ضبط حجم السجل المحلي | +| `FAILPROOFAI_HOOK_LOG_FILE` | كتابة تشخيصات الخطاف إلى ملف محدد | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | تعطيل القياس عن بُعد المجهول لهذه العملية | +| `FAILPROOFAI_NO_FIRST_RUN=1` | تخطي إعداد التشغيل الأول التفاعلي | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | تخطي التدقيق المحلي بعد الإعداد | +| `FAILPROOFAI_LLM_BASE_URL` | تجاوز نقطة نهاية محتملة OpenAI المستخدمة بواسطة سياسات LLM | +| `FAILPROOFAI_LLM_API_KEY` | توفير مفتاح API المستخدم بواسطة سياسات LLM | +| `FAILPROOFAI_LLM_MODEL` | اختر النموذج المستخدم بواسطة سياسات LLM | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | ربط تحميل وحدة السياسة المخصصة | +| `FAILPROOFAI_NO_DOWNLOAD=1` | رفض جلب الحزم والثنائيات مستند الخدمة؛ ما تم تثبيته يستمر في الفرض | | `FAILPROOFAI_PACK_BASE_URL` | جلب الحزم من مرآة بدلاً من `github.com` | -| `FAILPROOFAI__EXTRA_PATHS` | استبدل مسارات التقاط إضافية مكونة لجهاز واحد | -| `NO_COLOR` | عطّل مخرجات المحطة الملونة | +| `FAILPROOFAI__EXTRA_PATHS` | استبدال مسارات الالتقاط الإضافية المكوّنة لهيكل واحد | +| `NO_COLOR` | تعطيل مخرجات الطرفية الملونة | -متغيرات الصفحة الرئيسية الخاصة بالوكيل مثل `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, و`OPENCLAW_HOME` تتجاوز حيث يكتشف Failproof AI جلسات محلية لذلك الجهاز. +متغيرات المنزل الخاصة بالوكيل مثل `CLAUDE_PROJECTS_PATH` و `CURSOR_HOME` و `HERMES_HOME` و `OPENCLAW_HOME` تتجاوز حيث يكتشف Failproof AI جلسات محلية لذلك الهيكل. ## إيقاف أو إزالة جهاز بأمان @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -لا يعطّل إيقاف الجلسة المحلية المؤقت السياسات المُدارة من السحابة. استعد نشرات السحابة من خلال سير عمل إنفاذ السحابة عند كون الطرح نفسه هو المشكلة. +إيقاف جلسة محلية لا يعطّل سياسات Cloud المدارة. استعد نشرات Cloud من خلال سير عمل فرض Cloud عندما يكون الطرح نفسه هو المشكلة. -قبل إزالة حزمة npm، أزل الخطافات والمراقب المثبّتين: +قبل إزالة حزمة npm، أزل الخطافات المثبتة ومستند الخدمة: ```bash failproofai uninstall --dry-run @@ -151,8 +171,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -شغّل `failproofai --help` للحصول على تفاصيل خاصة بالإصدار. +قم بتشغيل `failproofai --help` للحصول على تفاصيل خاصة بالإصدار. - شغّل `failproofai uninstall` قبل `npm rm -g failproofai`؛ npm لا يزيل خطافات الوكيل المثبّتة أو خدمة المراقب. + قم بتشغيل `failproofai uninstall` قبل `npm rm -g failproofai`؛ npm لا تزيل خطافات الوكيل المثبتة أو خدمة مستند الخدمة. \ No newline at end of file diff --git a/docs/ar/reference/harnesses.mdx b/docs/ar/reference/harnesses.mdx index 42d4bc66..e11d15a6 100644 --- a/docs/ar/reference/harnesses.mdx +++ b/docs/ar/reference/harnesses.mdx @@ -1,80 +1,86 @@ --- title: "وسائط الوكيل" -description: "التقط الجلسات وفرض السياسات عبر جميع وسائط الوكيل الـ 12 المدعومة." +description: "التقط الجلسات وطبق السياسات عبر جميع وسائط الوكيل المدعومة البالغ عددها 12." icon: "plug-zap" --- -الوسيط هو أي شيء يعمل الوكيل الخاص بك بداخله فعليًا. Failproof AI يدعم اثني عشر منها، في فئتين: +الوسيط هو كل شيء يعمل الوكيل بداخله فعليًا. Failproof AI يدعم اثنا عشر منها، في فئتين: -- **أدوات سطر أوامر الترميز** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **بوابات الدردشة والمساعد** (2) — Hermes (Slack, Telegram, cron), OpenClaw (مساعد يستضيفه الذات) +- **واجهات سطر أوامر البرمجة** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **بوابات الدردشة والمساعدين** (2) — Hermes (Slack, Telegram, cron), OpenClaw (مساعد ذاتي الاستضافة) -تنطبق السياسات ذاتها وسجل الجلسة ذاته على أي وسيط يعمل الوكيل فيه. تعكس طبقة محول واحدة أسماء الأحداث الأصلية لكل وسيط وأسماء الأدوات وحقول إدخال الأدوات إلى 29 حدثًا قانونيًا قبل تشغيل أي سياسة. +نفس السياسات وسجل الجلسة نفسه ينطبق مهما كان الوكيل يعمل فيه. تقوم طبقة محول واحدة بتعيين أسماء الأحداث الأصلية لكل وسيط، وأسماء الأدوات، وحقول مدخلات الأدوات على 29 حدثًا قانونيًا قبل تشغيل أي سياسة. -وكيل يعمل في **لا شيء** من الاثني عشر يتم تجهيزه مباشرة باستخدام [Python SDK](/ar/reference/custom-agents). هذا عقد مختلف، ويستحق التأكيد بصراحة: SDK توفر التتبع والجلسات والتقييمات والتدقيق — **لا تفرض السياسات بمفردها.** منع إجراء غير آمن قبل تنفيذه يحتاج إلى ربط إنفاذ في حد أداة وقتك؛ [اتصل بنا](mailto:support@befailproof.ai) وسنقوم بتعيينه. +وكيل يعمل في **لا شيء** من الاثني عشر يتم جهزه مباشرة باستخدام [Python SDK](/ar/reference/custom-agents). هذا عقد مختلف، ويستحق التوضيح بصراحة: SDK يوفر التتبع والجلسات والتقييمات والتدقيق — **لا يفرض السياسات بمفرده.** منع الإجراء غير الآمن قبل تنفيذه يحتاج إلى هوك إنفاذ عند حدود أداة وقت التشغيل الخاص بك؛ [تواصل معنا](mailto:support@befailproof.ai) وسنقوم بتعيينه. -| الوسيط | نطاقات الربط المدعومة | +| الوسيط | نطاقات الهوك المدعومة | | --- | --- | -| Claude Code | المستخدم, المشروع, محلي | -| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | المستخدم, المشروع | -| Factory Droid, Devin CLI, Antigravity CLI, Goose | المستخدم, المشروع | -| Hermes, OpenClaw | المستخدم | +| Claude Code | User, project, local | +| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | +| Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | +| Hermes, OpenClaw | User | -تقوم كل تكامل بتطبيع أسماء أحداث الربط الأصلية وأسماء الأدوات وحقول إدخال الأدوات قبل تشغيل السياسات. لا يمكن للسياسة أن تتصرف إلا على الأحداث التي يعرضها الوسيط؛ اختبر سلوك نهاية الدور والتعليمات على الوسيط والإصدار الدقيق الذي تنشره. +كل تكامل يوحد أسماء أحداث الهوك الأصلية والأداة وحقول مدخلات الأدوات قبل تشغيل السياسات. لا يمكن للسياسة أن تعمل إلا على الأحداث التي يكشفها الوسيط؛ اختبر السلوك في نهاية الدوران والتعليمات على الوسيط والإصدار الدقيق الذي تنشره. ## قدرة الإنفاذ -"منع" يعني أن الحكم الذي أرجعه محول المحول الحالي يتم استهلاكه بواسطة الوسيط المسمى. قد يحل منع ما بعد الأداة محل النتيجة المعروضة للنموذج ولكن لا يمكنه التراجع عن تأثير جانبي للأداة حدث بالفعل. +"منع" يعني أن الحكم الذي يعيده محول التكيف الحالي يتم استهلاكه بواسطة الوسيط المسمى. قد يعدل الحجب بعد الأداة النتيجة المعروضة للنموذج ولكن لا يمكنه التراجع عن تأثير جانبي للأداة قد حدث بالفعل. -| الوسيط | أحداث الحجب المتحققة | تحذيرات المراقبة فقط أو عدم الحجب | +| الوسيط | أحداث الحجب المتحقق منها | التحفظات التي لا يمكن ملاحظتها أو غير حاجزة | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, وعدة أحداث المهمة/الإعدادات | `PostToolUse`, دورة حياة الجلسة, الإخطارات, وأحداث ما بعد الفشل قابلة للمراقبة فقط. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | يحل منع ما بعد الأداة محل النتيجة بعد التنفيذ؛ بدء الجلسة وأحداث الضغط قابلة للمراقبة في المحول الحالي. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | يحل منع ما بعد الأداة محل النتيجة بعد التنفيذ؛ أحداث الجلسة والإخطار قابلة للمراقبة فقط. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` وأحداث الجلسة قابلة للمراقبة فقط. | -| OpenCode | `PreToolUse` | أحداث ما بعد الأداة ودورة الحياة قابلة للمراقبة؛ معالجة الإيقاف الحالية هي إرشادات لدور لاحق وليست بوابة محققة. | -| Pi | `PreToolUse`, `UserPromptSubmit` | أحداث ما بعد الأداة ودورة الحياة قابلة للمراقبة؛ إرشادات الإيقاف تنطبق على دور لاحق. | -| Hermes | `PreToolUse` | أحكام ما بعد الأداة والجلسة وإيقاف الوكيل الفرعي ليست بوابات. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | أحداث ما بعد الأداة والجلسة وإيقاف الوكيل الفرعي والضغط قابلة للمراقبة فقط. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | أحكام ما بعد الأداة وإيقاف الوكيل الفرعي قابلة للمراقبة فقط. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` المشروط | لا تعمل ربطات الإذن في كل وضع إذن؛ أحداث ما بعد الأداة والجلسة قابلة للمراقبة فقط. | -| Antigravity CLI | `PreToolUse`, `Stop` | أحكام طلب المستخدم وما بعد الأداة قابلة للمراقبة؛ يمكن لا تزال حقن تعليمات المطالبة. | -| Goose | `PreToolUse` | أحداث طلب المستخدم وما بعد الأداة والجلسة قابلة للمراقبة فقط. يوجد ربط إيقاف أصلي للحجب في المنطقة السابقة لكن لا يتم تثبيته بواسطة المحول الحالي. | - -القدرات حساسة للإصدار. أعد الاختبار بعد ترقية CLI الوكيل، خاصة عندما تعتمد السياسة على سلوك المطالبة أو الإيقاف أو الإذن أو ما بعد الأداة بدلاً من بوابة ما قبل الأداة الشائعة. - -## تثبيت الالتقاط وربطات السياسة +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`، وعدة أحداث المهمة/الإعدادات | `PostToolUse`، دورة حياة الجلسة، الإخطارات، وأحداث ما بعد الفشل هي ملاحظة فقط. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | يعدل الحجب بعد الأداة النتيجة بعد التنفيذ؛ أحداث بداية الجلسة والضغط كبير هي ملاحظة فقط في محول التكيف الحالي. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | يعدل الحجب بعد الأداة النتيجة بعد التنفيذ؛ أحداث الجلسة والإخطارات هي ملاحظة فقط. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` وأحداث الجلسة هي ملاحظة فقط. | +| OpenCode | `PreToolUse` | أحداث ما بعد الأداة ودورة الحياة هي ملاحظة فقط؛ معالجة الإيقاف الحالية هي إرشادات للدوران اللاحق بدلاً من أن تكون بوابة تم التحقق منها. | +| Pi | `PreToolUse`, `UserPromptSubmit` | أحداث ما بعد الأداة ودورة الحياة هي ملاحظة فقط؛ تنطبق إرشادات الإيقاف على دوران لاحق. | +| Hermes | `PreToolUse` | حكومات ما بعد الأداة والجلسة والإيقاف الفرعي ليست بوابات. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | أحداث ما بعد الأداة والجلسة والإيقاف الفرعي والضغط كبير هي ملاحظة فقط. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | حكومات ما بعد الأداة والإيقاف الفرعي هي ملاحظة فقط. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, مشروط `PermissionRequest` | لا تعمل هوكات الإذن في كل وضع إذن؛ أحداث ما بعد الأداة والجلسة هي ملاحظة فقط. | +| Antigravity CLI | `PreToolUse`, `Stop` | حكومات موجز المستخدم وما بعد الأداة هي ملاحظة فقط؛ لا يزال يمكن حقن تعليمات الموجز. | +| Goose | `PreToolUse` | أحداث موجز المستخدم وما بعد الأداة والجلسة هي ملاحظة فقط. يوجد هوك إيقاف حجب أصلي في المنطقة الأعلى ولكن لا يتم تثبيته بواسطة محول التكيف الحالي. | + +القدرات حساسة للإصدار. أعد الاختبار بعد ترقية CLI الوكيل، خاصة عندما تعتمد السياسة على سلوك الموجز أو الإيقاف أو الإذن أو ما بعد الأداة بدلاً من بوابة ما قبل الأداة الشائعة. + +## تثبيت الالتقاط وهوكات السياسة - 1. افتح **الإدارة → المفاتيح** وأنشئ مفتاحًا يحتوي على `events:add` و `policies:pull`، مع تسميته للجهاز أو البيئة. - 2. على الجهاز المستهدف، اربط CLI المحلي بالمفتاح المعروض وثبت ربطات الوسيط. - 3. ابدأ جلسة وكيل جديدة، ثم أكد أحداث الربط والجلسة الخاصة بها في **المراقبة → الأحداث**. - 4. افتح **المراقبة → السياسة** لنفس الإطار الزمني وأكد أن قرار السياسة ينسب إلى الجهاز. + 1. افتح **الإدارة → المفاتيح** وأنشئ مفتاحًا بـ `events:add` و `policies:pull`، باسم الجهاز أو البيئة. + 2. على الجهاز الهدف، اربط CLI المحلي بالمفتاح المعروض وثبّت هوكات الوسيط. + 3. ابدأ جلسة وكيل جديدة، ثم تأكد من أحداث الهوك والجلسة الخاصة بها تحت **المراقبة → الأحداث**. + 4. افتح **المراقبة → السياسة** لنفس نطاق الوقت وتأكد من أن قرار السياسة نُسب إلى الجهاز. - يبدأ الاتصال بمفتاح الجهاز. أكد أنه يتضمن كل من أذونات الالتقاط وتسليم السياسة قبل نسخ سره. + يبدأ الاتصال بمفتاح الجهاز. تأكد من أنه يتضمن أذونات الاستيعاب وتسليم السياسة قبل نسخ سره. - ![درج مفتاح API الجديد المستخدم لمنح أذونات التقاط الأحداث وتسليم السياسة.](/images/dashboard/key-create.png) + ![درج مفتاح API جديد يستخدم لمنح أذونات استيعاب الأحداث وتسليم السياسة.](/images/dashboard/key-create.png) - بعد تثبيت الربطات، يجب أن يعرض دفق الأحداث أحداثًا جديدة من الجهاز والبيئة التي اتصلت بها. + بعد تثبيت الهوكات، يجب أن يعرض تدفق الأحداث أحداثًا جديدة من الجهاز والبيئة التي اتصلت بها. - ![دفق الأحداث المباشر المستخدم للتأكد من أن وسيط جديد مثبت يقوم بالإبلاغ.](/images/dashboard/events-stream.png) + ![تدفق الأحداث المباشر المستخدم لتأكيد أن وسيط جديد مثبت يقدم تقارير.](/images/dashboard/events-stream.png) - أخيرًا، تحقق من أن قرارات السياسة ينسب إلى نفس الجهاز. هذا يؤكد أن الوسيط يقوم بالإبلاغ عن نشاط السياسة بالإضافة إلى أحداث التتبع. + أخيرًا، تحقق من نسبة قرارات السياسة إلى نفس الجهاز. هذا يؤكد أن الوسيط يقدم تقارير عن نشاط السياسة وكذلك أحداث التتبع. - ![صفحة السياسة المستخدمة للتحقق من قرارات السياسة من وسيط مرتبط حديثًا.](/images/dashboard/policy-observe.png) + ![صفحة السياسة المستخدمة للتحقق من قرارات السياسة من وسيط متصل حديثًا.](/images/dashboard/policy-observe.png) - ثبت ربطات لكل وسيط يتم اكتشافه: + اقرأ مفتاح الجهاز في الشل. `read -s` يأخذه في موجه لا يعكس، حتى لا يظهر أبدًا في أمر أو في سجل الشل: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - أو استهدف وسائط محددة ونطاق التكوين: + ثم قم بإعداد الجهاز — يربط هذا هوكات لكل وسيط مكتشف، ويثبت المعالج، ويتصل بـ Cloud: + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + الإعداد لا يفعل أي سياسة بمفرده، وهذا ما الأمر الثاني موجود له. + + أو استهدف وسائط سميت ونطاق تكوين: ```bash failproofai policies --install \ @@ -82,7 +88,7 @@ icon: "plug-zap" --scope user ``` - نطاق المشروع يحتفظ بتكوين الربط مع مستودع. يغطي النطاق المستخدم العمل عبر المستودعات. Claude Code يدعم أيضًا النطاق المحلي؛ الدعم يختلف حسب الوسيط و CLI يرفض المجموعات غير المدعومة. + نطاق المشروع يحافظ على تكوين الهوك مع مستودع. نطاق المستخدم يغطي العمل عبر المستودعات. Claude Code يدعم أيضًا نطاق محلي؛ يختلف الدعم حسب الوسيط و CLI يرفض المجموعات غير المدعومة. تحقق من الجهاز وأحداثه: @@ -94,16 +100,16 @@ icon: "plug-zap" -## إضافة مسار جلسة غير افتراضي +## أضف مسار جلسة غير افتراضي - المسارات الإضافية مسجلة على الجهاز، وليس في السحابة. بعد إضافة واحد، افتح **المراقبة → الجلسات**، صفي حسب بيئة الجهاز، وأكد أن الجلسات من المسار الجديد تظهر. افتح جلسة وتحقق من الوكيل والوسيط وطوابع زمن الأحداث قبل الاعتماد عليها في التدقيق. + يتم تسجيل المسارات الإضافية على الجهاز، وليس في Cloud. بعد إضافة واحد، افتح **المراقبة → الجلسات**، وقم بالتصفية لبيئة الجهاز، وتأكد من ظهور الجلسات من المسار الجديد. افتح جلسة وتحقق من الوكيل والوسيط وطوابع أوقات الأحداث قبل الاعتماد عليها في التدقيق. - ![قائمة الجلسات مصفاة حسب البيئة التي تتلقى البيانات من مسار الالتقاط الإضافي.](/images/dashboard/sessions-list.png) + ![قائمة الجلسات المصفاة لبيئة استقبال البيانات من مسار الالتقاط الإضافي.](/images/dashboard/sessions-list.png) - أضف مسارًا برنامج تسمية اختياري، ثم افحص المسارات المكونة: + أضف مسارًا مع تسمية اختيارية، ثم افحص المسارات المكونة: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -112,10 +118,10 @@ icon: "plug-zap" failproofai backfill --since 7d ``` - إزالة مسار مع `failproofai harness remove-path claude checkout`. + أزل مسارًا باستخدام `failproofai harness remove-path claude checkout`. - قم بتشغيل جلسة جديدة واحدة بعد التثبيت. تحقق من كل من دفق الأحداث المباشر وقرار السياسة الفعلي قبل توسيع التجميع. + شغّل جلسة جديدة واحدة بعد التثبيت. تحقق من تدفق الأحداث المباشر وقرار السياسة الفعلي قبل توسيع الإطلاق. \ No newline at end of file diff --git a/docs/ar/reference/overview.mdx b/docs/ar/reference/overview.mdx index 56c29a85..d673bfcb 100644 --- a/docs/ar/reference/overview.mdx +++ b/docs/ar/reference/overview.mdx @@ -1,73 +1,76 @@ --- title: "التكاملات والمراجع" -description: "اتصل بأدوات الوكلاء المدعومة والمكتبات البرمجية والواجهات سطر الأوامر والواجهة HTTP." +description: "قم بتوصيل حزم الوكلاء المدعومة وأدوات SDK والمتصفحات والواجهة البرمجية HTTP." icon: "braces" --- -اختر التكامل الأقرب إلى مكان تشغيل الوكيل الخاص بك بالفعل. +اختر التكامل الأقرب إلى المكان الذي يعمل فيه وكيلك بالفعل. - - ثبّت الخطاطيف للأدوات المدعومة للترميز والوكلاء المستقلين. + + قم بتثبيت الخطافات للمتصفحات والوكلاء المستقلين المدعومة. - - قم بتكامل LangGraph أو CrewAI أو LlamaIndex أو Pydantic AI أو وكيل مخصص. + + قم بأداة LangGraph أو CrewAI أو LlamaIndex أو Pydantic AI أو وكيل مخصص. - التكوين وكتالوج الأحداث وقواعد الربط والتسليم. + الإعدادات وفهرس الأحداث وقواعد الارتباط والتسليم. - استعرض المشاريع المحلية والجلسات وأنشطة السياسات والتدقيق غير المتصل. + راجع المشاريع المحلية والجلسات ونشاط السياسة والتدقيق دون الاتصال. - قم بتكوين الالتقاط المحلي والخطاطيف والسياسات والتدقيق والتسليم وحالة الجهاز. + قم بتكوين الالتقاط المحلي والخطافات والسياسات والتدقيق والتسليم وحالة الجهاز. - ابحث في جلسات Cloud والتدقيق والمشاكل والتنبيهات والمفاتيح والمستخدمين والإعدادات وأدرها. + الاستعلام والإدارة لجلسات Cloud والتدقيق والمشاكل والتنبيهات والمفاتيح والمستخدمين والإعدادات. - قيّم الجلسات المكتملة أو غير النشطة باستخدام خدمة FastAPI. + قم بتقييم الجلسات الكاملة أو غير النشطة باستخدام خدمة FastAPI. - قم بكتابة واختبار قرارات السماح والتعليمات والرفض الخاصة بسير العمل. + قم بإنشاء واختبار قرارات السماح والتعليمات والرفض الخاصة بسير العمل. - نشّر مستوى التحكم في Cloud على مجموعة Kubernetes التي تديرها. + قم بنشر مستوى التحكم في Cloud على مجموعة Kubernetes المدارة من قبل العميل. -تغطي [مرجع HTTP API](/ar/reference/http-api) المُنشأة سطح `/v1` العام. تشرح الصفحات المكتوبة يدويًا سير العمل الذي يتجاوز عدة نقاط نهاية أو يستخدم واجهات إدارية خارج هذا السطح العام. +يغطي [مرجع HTTP API](/ar/reference/http-api) المُنشأ سطح `/v1` العام. تشرح الصفحات المكتوبة يدويًا سير العمل الذي يمتد عبر نقاط نهاية متعددة أو يستخدم واجهات إدارية خارج هذا السطح العام. -## اتصل بوكيل والتحقق من البيانات +## قم بتوصيل وكيل والتحقق من البيانات - 1. افتح **Administration → Keys**، أنشئ مفتاحًا باستخدام `events:add` و `policies:pull`، وانسخ السر. + 1. افتح **الإدارة → المفاتيح**، وأنشئ مفتاحًا باستخدام `events:add` و `policies:pull`، وانسخ السر. 2. قم بتكوين التكامل باستخدام الصفحة المطابقة أعلاه. - 3. افتح **Observe → Events** للتأكد من وصول الأحداث، ثم **Observe → Sessions** للتأكد من تشكيلها لعمليات تشغيل كاملة. - 4. قم بالتصفية حسب بيئة التكامل وافحص جلسة واحدة للحصول على النموذج والأداة والخطأ وحقول السياسة المطلوبة من قبل التدقيقات. + 3. افتح **المراقبة → الأحداث** للتأكد من وصول الأحداث، ثم **المراقبة → الجلسات** للتأكد من تكوين عمليات تشغيل كاملة. + 4. صفّي حسب بيئة التكامل وافحص جلسة واحدة للحصول على حقول النموذج والأداة والخطأ والسياسة المطلوبة من قبل عمليات التدقيق. - ابدأ بدرج المفاتيح. تحدد الامتيازات المختارة ما إذا كان بإمكان الجهاز إرسال الأحداث واستقبال السياسات المُدارة من Cloud. + ابدأ بدرج المفاتيح. تحدد المنح المحددة ما إذا كان يمكن للجهاز إرسال الأحداث واستقبال السياسات المُدارة بواسطة Cloud. - ![درج مفتاح API الجديد المستخدم لمنح أذونات دخول الأحداث وتسليم السياسة.](/images/dashboard/key-create.png) + ![درج مفتاح API الجديد المستخدم لمنح أذونات بيانات الأحداث وتسليم السياسة.](/images/dashboard/key-create.png) - بعد توصيل التكامل، استخدم قائمة الجلسات للتأكد من أن أحداثها يتم تجميعها في عمليات تشغيل كاملة في البيئة المتوقعة. + بعد توصيل التكامل، استخدم قائمة الجلسات للتأكد من تجميع أحداثها في عمليات تشغيل كاملة في البيئة المتوقعة. - ![قائمة الجلسات المستخدمة للتحقق من أن التكامل المتصل حديثًا يقدم عمليات تشغيل وكيل كاملة.](/images/dashboard/sessions-list.png) + ![قائمة الجلسات المستخدمة للتحقق من أن التكامل المتصل حديثًا يُبلغ عن عمليات تشغيل الوكيل الكاملة.](/images/dashboard/sessions-list.png) - افتح إحدى هذه الجلسات قبل اعتبار التكامل مكتملاً؛ يجب أن تحتوي التتبع على نموذج وأداة وخطأ وأدلة السياسة التي يحتاجها التدقيق. + افتح إحدى هذه الجلسات قبل اعتبار التكامل مكتملاً؛ يجب أن يحتوي التتبع على دليل النموذج والأداة والخطأ والسياسة التي يحتاجها التدقيق. - أنشئ مفتاح جهاز وقم بتوصيل مراقب Failproof والتحقق من الجلسة الأولى. + أنشئ مفتاح جهاز، ثم اقرأ السر الذي يطبعه في shell. `read -s` يأخذه في موجه لا يعكس، لذلك لا يظهر أبدًا في أمر أو في سجل shell: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + قم بتوصيل خيط Failproof والتحقق من الجلسة الأولى: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production @@ -76,6 +79,6 @@ icon: "braces" استخدم `fp --json sessions ...` عندما تستهلك أداة أخرى النتيجة. يجب أن تأتي الأعلام العامة مثل `--json` و `--org` و `--base-url` قبل الأمر. - انظر إلى [مرجع Failproof AI CLI](/ar/reference/failproof-cli) للأوامر المحلية و [مرجع Failproof Cloud CLI](/ar/reference/cloud-cli#cli-commands) لأوامر `fp`. + انظر إلى [مرجع Failproof AI CLI](/ar/reference/failproof-cli) لأوامر محلية و [مرجع Failproof Cloud CLI](/ar/reference/cloud-cli#cli-commands) لأوامر `fp`. \ No newline at end of file diff --git a/docs/ar/reference/policy-sdk.mdx b/docs/ar/reference/policy-sdk.mdx index 1a433f1a..0176d5e6 100644 --- a/docs/ar/reference/policy-sdk.mdx +++ b/docs/ar/reference/policy-sdk.mdx @@ -1,35 +1,35 @@ --- title: "السياسات المخصصة" -description: "قم بتأليف واختبار ونشر سياسات JavaScript أو TypeScript لحالات الفشل الخاصة بوكلائك." +description: "قم بكتابة واختبار ونشر سياسات JavaScript أو TypeScript لحالات الفشل المحددة لوكلائك." icon: "shield-plus" --- -تحول السياسات المخصصة نمط فشل من آثارك أو تدقيقاتك إلى قرار يعمل أثناء عمل الوكيل. يمكن للسياسة السماح بإجراء أو توجيه الوكيل أو رفض الإجراء قبل أن يسبب حادثة أخرى. +تحول السياسات المخصصة نمط فشل من آثارك أو عمليات التدقيق إلى قرار يتم تنفيذه أثناء عمل الوكيل. يمكن للسياسة السماح بإجراء ما، أو إرشاد الوكيل، أو منع الإجراء قبل أن يسبب حادثة أخرى. -استخدم سياسة مخصصة عندما يعتمد السلوك على أدواتك أو مساراتك أو أوامرك أو بيئاتك أو قواعد التشغيل. تحقق من [فهرس السياسات المدمجة](/ar/policies/builtin-catalog) أولاً حتى لا تعيد إنشاء عنصر تحكم موجود. +استخدم سياسة مخصصة عندما يعتمد السلوك على أدواتك أو مساراتك أو أوامرك أو بيئاتك أو قواعد التشغيل. تحقق من [حزمة سياسات Failproof AI](/ar/policies/packs) أولاً حتى لا تعيد إنشاء عنصر تحكم موجود. -## تأليف سياسة مخصصة +## كتابة سياسة مخصصة - 1. انتقل إلى **Admin → policy editor**، وحدد **New policy**، واشرح الفشل الذي تريد منعه. - 2. أضف مصدر السياسة، ثم اختبر المطابقات المتوقعة وعدم المطابقات الآمنة في المحرر. حل كل خطأ تحقق. - 3. احفظ المسودة وحدد **Publish version** لإنشاء نسخة ثابتة. - 4. انتقل إلى **Admin → enforcement**، ثم نشر النسخة إلى جهاز اختبار في وضع **observe**، والتحقق من قراراتها ضمن **Observe → policy** قبل فرضها. + 1. انتقل إلى **Admin → محرر السياسات**، حدد **سياسة جديدة**، وصف حالة الفشل التي تريد منعها. + 2. أضف مصدر السياسة، ثم اختبر المطابقات المتوقعة والمطابقات الآمنة غير المطابقة في المحرر. حل كل خطأ تحقق. + 3. احفظ المسودة وحدد **نشر النسخة** لإنشاء نسخة غير قابلة للتغيير. + 4. انتقل إلى **Admin → الفرض**، وأنشر النسخة على جهاز اختبار في وضع **المراقبة**، وتحقق من قراراتها تحت **المراقبة → السياسة** قبل فرضها. - ![محرر السياسة المستخدم لتأليف ونشر سياسة مخصصة.](/images/dashboard/policy-editor.png) + ![محرر السياسات المستخدم لكتابة ونشر سياسة مخصصة.](/images/dashboard/policy-editor.png) 1. أنشئ `.failproofai/policies/checkout-policies.ts`. يجب أن ينتهي اسم الملف بـ `policies.js` أو `policies.mjs` أو `policies.ts`. 2. سجل سياسة واحدة أو أكثر باستخدام `customPolicies.add()`. 3. تحقق وثبت الملف باستخدام `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. - 4. اطلق إجراء واحد متطابق وإجراء واحد آمن. قم بتشغيل `failproofai policies`، ثم افحص القرارات المنسوبة ضمن **Observe → policy**. + 4. فعّل إجراء واحد مطابق وإجراء آمن واحد. شغّل `failproofai policies`، ثم افحص القرارات المنسوبة تحت **المراقبة → السياسة**. ## ابدأ بقاعدة ضيقة -تحظر هذه السياسة أوامر Kubernetes المدمرة فقط عندما يستهدف الأمر الإنتاج. كل شيء خارج نمط الفشل الدقيق هذا يُرجع `allow()`. +تحظر هذه السياسة أوامر Kubernetes المدمرة فقط عندما يستهدف الأمر الإنتاج. كل شيء خارج نمط الفشل هذا بالضبط يرجع `allow()`. ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,20 +55,20 @@ customPolicies.add({ }); ``` -السياسات الجيدة ضيقة بما يكفي لشرحها في جملة واحدة. طابق الإجراء القابل للمراقبة—وليس النية التي تأمل أن يكون لدى الوكيل—وأرجع `allow()` بمجرد عدم تطبيق القاعدة. +السياسات الجيدة ضيقة بما يكفي للشرح في جملة واحدة. طابق الإجراء الملاحظ — وليس النية التي تأمل أن يكون لدى الوكيل — وارجع `allow()` بمجرد عدم تطبيق القاعدة. -## اختر قرارًا +## اختر قراراً -| المساعد | النتيجة | استخدمه عندما | +| مساعد | النتيجة | استخدمه عندما | | --- | --- | --- | -| `allow(reason?)` | تستمر العملية. | السياسة لا تنطبق أو الإجراء آمن. | -| `instruct(reason)` | تستمر العملية مع إرشادات حيث يدعمها التوقيع. | تريد توجيه الوكيل نحو نهج أفضل دون فرض ثابت. | -| `deny(reason)` | يتم حظر العملية عندما يدعم الحدث والتوقيع الحظر. | يجب ألا يمضي الإجراء قدمًا. | +| `allow(reason?)` | تستمر العملية. | لا تنطبق السياسة أو الإجراء آمن. | +| `instruct(reason)` | تستمر العملية مع إرشادات حيث يدعمها الحزام. | تريد توجيه الوكيل نحو نهج أفضل دون فرض ثابت. | +| `deny(reason)` | يتم حظر العملية عندما يدعمها الحدث والحزام. | يجب أن لا تستمر العملية. | اكتب السبب للوكيل الذي يجب أن يتعافى. اشرح ما تم اكتشافه وما يجب أن يفعله بدلاً من ذلك. - لا تستخدم `instruct()` لحد أمان. يختلف توصيل الإرشادات حسب توقيع الوكيل. استخدم `deny()` عندما يجب منع الإجراء. + لا تستخدم `instruct()` لحد أمان. يختلف توصيل الإرشادات حسب حزام الوكيل. استخدم `deny()` عندما يجب منع الإجراء. ## كائن السياسة @@ -84,12 +84,12 @@ customPolicies.add({ | الحقل | مطلوب | الوصف | | --- | --- | --- | -| `name` | نعم | معرّف مستقر للسياسة. احفظ الأسماء فريدة عبر الملفات. | +| `name` | نعم | معرّف ثابت للسياسة. ابق أسماء فريدة عبر الملفات. | | `description` | لا | الغرض القابل للقراءة البشرية الموضح في قوائم السياسات والقرارات. | | `match.events` | لا | أنواع الأحداث التي تستدعي السياسة. حذف `match` يستدعيها لكل حدث متاح. | | `fn` | نعم | دالة متزامنة أو غير متزامنة ترجع نتيجة `allow` أو `instruct` أو `deny`. | -فلتر الأدوات داخل `fn`. `match.toolNames` ليست جزءًا من نوع السياسة المخصصة العام. +قم بتصفية الأدوات داخل `fn`. `match.toolNames` ليس جزءاً من نوع السياسة المخصصة العام. ## سياق السياسة @@ -97,19 +97,19 @@ customPolicies.add({ | الحقل | النوع | ما يحتويه | | --- | --- | --- | -| `eventType` | `HookEventType` | حدث معياري يتم تقييمه حاليًا. | -| `toolName` | `string \| undefined` | اسم الأداة الأساسي مثل `Bash` أو `Read` أو `Write` أو `Edit`. | -| `toolInput` | `Record \| undefined` | الإدخال الأساسي لاستدعاء الأداة الحالية. | -| `payload` | `Record` | حمولة الحدث المعياري الكاملة. | -| `session` | `SessionMetadata \| undefined` | معرّف الجلسة والدليل العامل ومسار النسخة ونمط الإذن وبيانات التوقيع عند توفرها. | -| `cli` | `string \| undefined` | توقيع وكيل المصدر، مثل `claude` أو `codex` أو `cursor`. | -| `params` | `Record` | معاملات السياسة المدمجة. السياسات المخصصة حاليًا تتلقى كائنًا فارغًا. | +| `eventType` | `HookEventType` | الحدث المعياري قيد التقييم حالياً. | +| `toolName` | `string \| undefined` | اسم الأداة القياسي مثل `Bash` أو `Read` أو `Write` أو `Edit`. | +| `toolInput` | `Record \| undefined` | المدخل القياسي لاستدعاء الأداة الحالية. | +| `payload` | `Record` | حمولة الحدث المعيارية الكاملة. | +| `session` | `SessionMetadata \| undefined` | معرّف الجلسة والدليل العامل ومسار النسخة والوضع المسموح وبيانات الحزام عند توفرها. | +| `cli` | `string \| undefined` | حزام الوكيل المصدر، مثل `claude` أو `codex` أو `cursor`. | +| `params` | `Record` | معاملات السياسة المدمجة. تتلقى السياسات المخصصة حالياً كائناً فارغاً. | -تعامل مع كل قيمة اختيارية على أنها اختيارية حقيقية. لا توفر نسخ الوكيل وأنواع الأحداث نفس الحقول. +اعامل كل قيمة اختيارية على أنها اختيارية حقاً. إصدارات الوكيل وأنواع الأحداث لا توفر جميعها نفس الحقول. ### مدخلات الأدوات الشائعة -يوحد Failproof AI الأدوات الشائعة عبر التوقيعات المدعومة حتى تتمكن السياسة عادة من استخدام شكل إدخال واحد. +يقوم Failproof AI بتوحيد الأدوات الشائعة عبر الأحزمة المدعومة بحيث يمكن لسياسة عادة استخدام شكل مدخل واحد. | الأداة | الحقول الشائعة | | --- | --- | @@ -119,7 +119,7 @@ customPolicies.add({ | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | -استخدم الإجبار الدفاعي لأن قيم مدخلات الأدوات يتم طبعها كـ `unknown`: +استخدم الإكراه الدفاعي لأن قيم مدخلات الأداة مكتوبة كـ `unknown`: ```ts const command = String(ctx.toolInput?.command ?? ""); @@ -128,25 +128,25 @@ const filePath = String(ctx.toolInput?.file_path ?? ""); ## اختر الحدث -| الحدث | متى يعمل | الاستخدام النموذجي | +| الحدث | متى يتم تشغيله | الاستخدام النموذجي | | --- | --- | --- | | `PreToolUse` | قبل تنفيذ أداة. | حظر أو توجيه الأوامر والكتابات والقراءات والإجراءات الخارجية. | -| `PostToolUse` | بعد إرجاع أداة. | افحص النتائج قبل أن تصل إلى الوكيل. ينتج الحظر النتيجة بأكملها؛ لا يحرر الحقول المختارة. | -| `PermissionRequest` | عندما يطلب الوكيل إذنًا. | تطبيق قواعد الأذن الخاصة بالمنظمة. | -| `UserPromptSubmit` | قبل استمرار مطالبة مرسلة. | رفض التعليمات المحظورة أو إضافة إرشادات سير العمل. | -| `Stop` | عندما يحاول الوكيل الانتهاء. | اطلب شرط إنهاء قابل للوصول، مثل خطوة التحقق المحلية. | -| `SubagentStop` | عندما يحاول الوكيل الفرعي الانتهاء. | بوابة العمل المفوض قبل عودته إلى الأب. | -| `SessionStart` / `SessionEnd` | على حدود الجلسة. | سجل أو افحص حالة مستوى الجلسة. | +| `PostToolUse` | بعد إرجاع أداة. | افحص النتائج قبل وصولها إلى الوكيل. يحظر الرفض النتيجة بالكامل؛ لا يحرر الحقول المحددة. | +| `PermissionRequest` | عندما يطلب الوكيل إذناً. | تطبيق قواعد الأذونات الخاصة بالمنظمة. | +| `UserPromptSubmit` | قبل استمرار المطالبة المرسلة. | رفض التعليمات المحظورة أو إضافة إرشادات سير العمل. | +| `Stop` | عندما يحاول الوكيل الإنهاء. | تطلب شرط إنهاء قابل للوصول، مثل خطوة التحقق المحلية. | +| `SubagentStop` | عندما يحاول وكيل فرعي الإنهاء. | إغلاق العمل المفوض قبل عودته إلى الوالد. | +| `SessionStart` / `SessionEnd` | في حدود الجلسة. | تسجيل أو فحص حالة مستوى الجلسة. | -يعتمد توفر الحدث والسلوك الحظر على توقيع الوكيل. انظر [توقيعات الوكيل](/ar/reference/harnesses) قبل الاعتماد على حدث عبر أسطول مختلط. +توفر الحدث والسلوك الحظري يعتمد على حزام الوكيل. انظر [أحزمة الوكيل](/ar/reference/harnesses) قبل الاعتماد على حدث عبر أسطول مختلط. `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch`, و `Setup`. -## تأليف أنماط السياسات الشائعة +## كتابة أنماط السياسة الشائعة -### حظر الكتابات إلى المسارات المحمية +### حظر الكتابات في المسارات المحمية ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -166,7 +166,7 @@ customPolicies.add({ }); ``` -### تقديم إرشادات غير محظورة +### إعطاء إرشادات غير حظرية ```ts import { customPolicies, allow, instruct } from "failproofai"; @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### بوابة إكمال الجلسة +### إغلاق إنهاء الجلسة ```ts import { execFileSync } from "node:child_process"; @@ -215,30 +215,30 @@ customPolicies.add({ ``` - حدث `Stop` المرفوض يمكن أن يجعل الوكيل يحاول مجددًا. قم بالبوابة فقط على شرط يمكن للوكيل تلبيته في البيئة الحالية، وقيد كل استدعاء عملية فرعية أو شبكة. + يمكن لحدث `Stop` المرفوض أن يجعل الوكيل يعيد المحاولة. قم بالإغلاق فقط على شرط يمكن للوكيل تلبيته في البيئة الحالية، وحدّ كل استدعاء عملية فرعية أو شبكة. ## تحميل ملفات السياسة ### ملفات الاتفاقية -تحميل ملفات الاتفاقية تلقائيًا: +تحميل ملفات الاتفاقية تلقائياً: ```text /.failproofai/policies/security-policies.ts ~/.failproofai/policies/personal-policies.mjs ``` -- يتم تحميل أدلة السياسة للمشروع والمستخدم معًا. -- الملفات تحميل أبجديًا داخل كل دليل. +- يتم تحميل أدلة السياسات للمشروع والمستخدم معاً. +- يتم تحميل الملفات أبجدياً داخل كل دليل. - يجب أن ينتهي الملف بـ `policies.js` أو `policies.mjs` أو `policies.ts`. -- يتم دعم استدعاءات متعددة `customPolicies.add()` في ملف واحد. -- الاستيراد النسبي من الوحدات المحلية مدعوم. -- يمكن التزام سياسات المشروع بحيث تتبع نفس القواعد المستودع. +- تدعم استدعاءات متعددة `customPolicies.add()` في ملف واحد. +- الواردات النسبية من الوحدات المحلية مدعومة. +- يمكن التزام سياسات المشروع بحيث تتبع نفس القواعد الدقيقة المستودع. ### ملفات صريحة -استخدم مسارات صريحة عندما يجب أن تسمي التحقق أو التكوين ملف الإدخال مباشرة: +استخدم المسارات الصريحة عندما يجب أن يسمي التحقق أو التكوين ملف الدخول مباشرة: ```bash failproofai policies --install \ @@ -247,7 +247,7 @@ failproofai policies --install \ --scope project ``` -تحميل الملفات الصريحة أولاً، تليها ملفات اتفاقية المشروع ثم ملفات اتفاقية المستخدم. يتم تحميل الملف المكتشف من خلال كلا المسارين مرة واحدة. +تحميل الملفات الصريحة أولاً، تليها ملفات اتفاقية المشروع ثم ملفات اتفاقية المستخدم. الملف المكتشف من خلال كلا المسارين يتم تحميله مرة واحدة. ## التحقق والاختبار @@ -260,30 +260,30 @@ failproofai policies --install \ failproofai policies ``` -يلتقط التحقق الملفات المفقودة وأخطاء بناء الجملة والاستيرادات غير المحلولة والاستثناءات على مستوى أعلى وحدود انتظار تحميل الوحدة. لا يثبت أن منطق المطابقة صحيح. +يعترض التحقق على الملفات المفقودة وأخطاء بناء الجملة والواردات غير المحلولة والاستثناءات من المستوى الأعلى والمهل الزمنية لتحميل الوحدة. لا يثبت أن منطق المطابقة صحيح. اختبر على الأقل هذه الحالات: -- إجراء واحد يجب أن يطابق وينتج عن سبب السياسة المقصود. -- إجراء واحد قريب لكنه آمن يجب أن يعيد `allow()`. -- حقول أداة مفقودة أو مشوهة. -- بناء جملة أوامر بديل والمسارات والاقتباسات والحالة والمسافة البيضاء. +- إجراء واحد يجب أن يتطابق وينتج السبب السياسي المقصود. +- إجراء آمن واحد قريب يجب أن يرجع `allow()`. +- حقول الأداة المفقودة أو غير المشكلة بشكل صحيح. +- بناء جملة الأمر البديل والمسارات والعروض والهيكل وسقوط المسافات البيضاء. - عملية فرعية أو اعتماد شبكة غير متاح. -نسب النتيجة إلى سياستك المخصصة ضمن **Observe → policy**. الاختبار المحظور غير كافٍ إذا كانت سياسة مدمجة أخرى هي التي اتخذت القرار. +انسب النتيجة إلى السياسة المخصصة تحت **المراقبة → السياسة**. الاختبار المحظور غير كافٍ إذا اتخذت سياسة مدمجة أخرى القرار. ## سلوك وقت التشغيل -- السياسات المدمجة تقيّم قبل السياسات المخصصة. -- أول `deny` توقف مزيد من تقييم السياسة. +- تقيّم السياسات المدمجة قبل السياسات المخصصة. +- أول `deny` يوقف مزيد من تقييم السياسة. - يمكن دمج نتائج `instruct` متعددة عندما لا ترفض أي سياسة الحدث. -- لدالة السياسة موعد نهائي تنفيذ 10 ثواني. -- الاستثناء المرمى أو انتهاء المهلة الزمنية تم تسجيله ومعاملته كـ `allow()`. -- ملف اتفاقية يفشل في التحميل يتم تخطيه؛ ملفات مخصصة أخرى والسياسات المدمجة تستمر. -- تحميل الوحدة على مستوى أعلى لديه أيضًا موعد نهائي 10 ثواني. -- وضع الملاحظة السحابية يقوم بتشغيل السياسة لكن يسجل قرارًا غير متاح دون فرضه. +- دالة السياسة لها موعد نهائي لتنفيذ مدته 10 ثوان. +- يتم تسجيل الاستثناء المرفوع أو المهلة الزمنية والتعامل معها كـ `allow()`. +- ملف اتفاقية فشل التحميل يتم تخطيه؛ تستمر الملفات المخصصة الأخرى والسياسات المدمجة. +- تحميل الوحدة من المستوى الأعلى أيضاً له مهلة زمنية مدتها 10 ثوان. +- وضع الملاحظة السحابية يقوم بتشغيل السياسة لكن يسجل قراراً غير سماح دون فرضه. -احفظ وحدات السياسة حتمية وسريعة. تجنب استدعاءات الشبكة على مستوى أعلى أو بدء الخادم. قيد العمل داخل `fn`، تمسك بفشل الاعتماد، واختر عن قصد ما إذا كان هذا الفشل يجب أن يسمح أو يرفض العملية. +اجعل وحدات السياسة حتمية وسريعة. تجنب استدعاءات الشبكة من المستوى الأعلى أو بدء الخادم. ربط العمل داخل `fn`، اقبض فشل الاعتماد، واختر عن قصد ما إذا كان هذا الفشل يجب أن يسمح أو ينكر العملية. ## تصدير API @@ -291,13 +291,13 @@ failproofai policies | --- | --- | | `customPolicies.add(policy)` | سجل سياسة مخصصة عند تحميل الوحدة. | | `allow(reason?)` | السماح بالعملية. | -| `instruct(reason)` | السماح بالعملية وتقديم إرشادات حيث مدعومة. | -| `deny(reason)` | حظر العملية حيث مدعومة. | -| `getCustomHooks()` | إرجاع السياسات المسجلة حاليًا في سجل الوحدة. | -| `clearCustomHooks()` | امسح هذا السجل، في المقام الأول للاختبارات والمحملات. | +| `instruct(reason)` | السماح بالعملية وتوفير إرشادات حيث يدعمها. | +| `deny(reason)` | حظر العملية حيث يدعمها. | +| `getCustomHooks()` | إرجاع السياسات المسجلة حالياً في سجل وحدة. | +| `clearCustomHooks()` | امسح هذا السجل، بشكل أساسي للاختبارات والمحملات. | -TypeScript تصدر `PolicyContext` و `PolicyResult` و `CustomHook` و `PolicyDecision` و `PolicyFunction`. +تُصدّر TypeScript `PolicyContext` و `PolicyResult` و `CustomHook` و `PolicyDecision` و `PolicyFunction`. - انشر نسخة، انشرها في وضع الملاحظة، تحقق من القرارات، وانتقل إلى الإنفاذ. + انشر نسخة، انشرها في وضع المراقبة، تحقق من القرارات، وانتقل إلى الفرض. \ No newline at end of file diff --git a/docs/ar/sessions/evaluations.mdx b/docs/ar/sessions/evaluations.mdx index 8d5168a1..e9ac39b1 100644 --- a/docs/ar/sessions/evaluations.mdx +++ b/docs/ar/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "التقييمات المباشرة" -description: "قيّم الجلسات المباشرة والمكتملة من حيث الجودة والامتثال والتكلفة والكمون." +title: "قراءة نتائج التقييم" +description: "رسم بياني لدرجات التقييم عبر الوقت، ومقارنة الوكلاء والبيئات، ورؤية سبب حصول الجلسة على درجة منخفضة، وطلب المساعدة من المساعد." icon: "gauge" --- -تطبق التقييمات المباشرة أحكامًا متسقة على جلسات الوكيل. استخدمها للإشارات التي يجب قياسها بشكل مستمر بدلاً من التحقيق فيها فقط أثناء التدقيق. +تصل النتائج من كل تقييم، سواء كان مستضافًا أو من العامل الخاص بك، إلى نفس الأماكن. -## مراجعة جودة التقييم +## مقارنة الدرجات عبر الوقت - 1. انتقل إلى **Observe → Evaluations**. - 2. أضف سلسلة واختر الوكيل والبيئة ودرجة التقييم والإحصائية والمنحنى. - 3. أضف سلسلًا لمقارنة البيئات أو الوكلاء أو مفاتيح الدرجات. - 4. حدد النتيجة لفتح الجلسات المطابقة أو مشاركة العرض المُرشح. استخدم **Observe → Metrics** للكمون والرموز والتكلفة وقيم الحجم الأخرى. + انتقل إلى **Observe → evaluations**. - ![لوحة تحكم الجودة تعرض متوسط درجات التقييم والاتجاهات بمرور الوقت.](/images/dashboard/dashboard-quality.png) + - **Recent runs** يسرد كل تقييم عند وصوله: سواء جاء من المقيّم المستضاف (**managed**) أو الخاص بك (**customer**)، والوكيل والجلسة، والتقييم وإصداره، وحالته، ودرجته أو مقاييسه. + - **Score over time** يرسم ما تطلبه. اختر **add series** واختر وكيلاً وبيئة وتقييمًا وإحصائية: avg أو min أو max أو p50 أو p75 أو p90 أو p95 أو p99 أو stddev أو mode. كل سلسلة هي خط واحد؛ امنحها **curve** الخاص بها لرسمها على مخطط منفصل. - افتح جلسة من التنقيب لفحص الاستدلال لكل درجة: + ![صفحة التقييمات: تقييمات حديثة موسومة بـ customer، ومخطط درجة عبر الوقت مع خطوط مرجعية عند 0.5 و 0.8، وسلسلة واحدة تحسب متوسط finished_clean عبر جميع الوكلاء والبيئات.](/images/dashboard/evaluations-chart.png) - ![عرض تفاصيل الجلسة يعرض درجات التقييم والاستدلال بجانب المسار الكامل.](/images/dashboard/session-detail.png) + نطاق زمني واحد وحجم صندوق واحد ينطبقان على كل سلسلة. الصندوق الدقيق يجد حادثة؛ الصندوق الخشن يظهر الاتجاه، ويمكن أن يخفي الارتفاعات التي تبحث عنها. الجرافة حيث لم يتم تسجيل شيء هي فجوة في الخط، وليس صفرًا أبدًا، والخطوط المرجعية تحدد 0.5 و 0.8. + + كل جزء من العرض يعيش في عنوان URL: **share** ينسخه، ومن يفتحه يرى المقارنة التي بنيتها بالضبط. ```bash @@ -32,21 +32,25 @@ icon: "gauge" -يتلقى المقيّم هوية الجلسة والبيئة والطوابع الزمنية والأحداث المرتبة. يمكنه إرجاع مفاتيح درجات رقمية مع استدلال اختياري وملخص. يمكن للمقيّمين طويلي المدى إرجاع وظيفة قيد الانتظار والاستعلام عنها لاحقًا. +رسم **avg** و **p90** لنفس التقييم لترى ما إذا كان المتوسط الجيد يخفي ذيلاً سيئًا، أو نفس التقييم لوكيلين، أو للإنتاج والتدريج، لمقارنتهما على محور واحد. تقاس التكاليف والكمون وعدد الرموز، التي تحمل وحدات، في الرسم البياني تحت **Observe → metrics**، رسم بياني واحد لكل وحدة. + +## معرفة سبب حصول الجلسة على درجة منخفضة + +افتح جلسة من **Observe → sessions**؛ الشبكة تحمل درجات كل جلسة وتصفيها حسب نطاق الدرجات. يقود السكة اليمنى للجلسة بملخص التقييم، ثم شريط لكل درجة مع تفكير المقيّم تحتها. + +![عرض تفاصيل جلسة يعرض درجات التقييم والتفكير بجانب التتبع الكامل.](/images/dashboard/session-detail.png) + +## اطلب من المساعد + +اطرح أسئلة عن بيانات التقييم باللغة الإنجليزية البسيطة: "أخبرني عن بعض التقييمات الحديثة"، أو أي وكلاء تنخفض درجاتهم. يقرأ [المساعد](/ar/sessions/assistant) وينحل نتائج ويجيب بجداول يمكنك المتابعة عليها، والسؤال الذي يستحق الاحتفاظ به يمكن أن يصبح [استعلام](/ar/sessions/queries) أو [لوحة تحكم](/ar/sessions/dashboards). -## أهداف التقييم الجيدة +![صفحة التقييمات بجانب المساعد، الذي يجيب على "أخبرني عن بعض التقييمات الحديثة" بملخص للإجماليات والحالات والدرجات.](/images/dashboard/evaluations-assistant.png) -- إكمال المهمة أو الصحة -- التأصيل وخطر الهلوسة -- اختيار الأداة وكفاءة الأداة -- امتثال السياسة أو العملية -- ميزانيات التكلفة والكمون -- تصعيد بشري مطلوب +## راقب وتصرف -## من الدرجة إلى الاستجابة +- **Dashboards**، تحت **Analyze → dashboards**، اتجاه الدرجات التي تميز، لكل وكيل وبيئة، للمنظمة بأكملها. -أظهر الدرجات في لوحات التحكم لتتبع الاتجاهات. أنشئ تنبيهات للحدود أو الشروط المركبة. عندما تنخفض الدرجة عبر مجموعة سكانية، قم بإجراء تدقيق للتحقيق في السبب؛ وعندما يكون السبب إجراءً قابلاً للتكرار، نشّر سياسة. + ![لوحة تحكم الجودة تعرض درجات التقييم المتوسطة والاتجاهات عبر الوقت.](/images/dashboard/dashboard-quality.png) - - قم بتطبيق التقييم المتزامن أو غير المتزامن باستخدام Python evaluator SDK. - \ No newline at end of file +- **Alerts** تخطرك عندما تتجاوز درجة ما عتبة. انظر [alerts](/ar/audits/alerts). +- عندما تنخفض درجة عبر جلسات عديدة، [قم بتشغيل تدقيق](/ar/audits/run) لاكتشاف السبب؛ عندما تكون السبب إجراءً قابلاً للتكرار، [اكتب سياسة](/ar/policies/editor). \ No newline at end of file diff --git a/docs/ar/start/integrations/custom-agents.mdx b/docs/ar/start/integrations/custom-agents.mdx index 088cdb6c..6e5db3c2 100644 --- a/docs/ar/start/integrations/custom-agents.mdx +++ b/docs/ar/start/integrations/custom-agents.mdx @@ -1,14 +1,13 @@ --- ---- title: "الوكلاء المخصصون" sidebarTitle: "الوكلاء المخصصون" -description: "أدرج وكيلًا كتبته بنفسك، أو إطار عمل لا يتوفر له محول." +description: "أدرج وكيلاً كتبته بنفسك، أو إطار عمل لا يوجد له محول في Failproof AI." icon: "code" --- -لوكيل كتبته بنفسك، أو إطار عمل لا يتوفر له محول من Failproof AI. لا يوجد شيء لإدراجه: أنت تُصدر الأحداث. +لوكيل كتبته بنفسك، أو إطار عمل لا يوجد له محول في Failproof AI. لا شيء يجب إدراجه: أنت تصدر الأحداث. -هذا هو نفس الواجهة البرمجية التي تستدعيها محولات الإطارات الأربعة. وهي جداول ترجمة فوقها. +هذا هو نفس API الذي يستدعيه محولات الأطر الأربعة. وهي جداول ترجمة فوقه. ## التثبيت @@ -33,25 +32,25 @@ with failproofai_sdk.session(): # one run اقرأه من الأعلى إلى الأسفل وسيخبرك بما يعنيه: -| لف فيه | لتقول | +| غلف فيه | للقول | | --- | --- | | `session()` | هذه الأحداث تنتمي إلى نفس التشغيل | -| `agent()` | شيء ما يقوم بعمل — أعطه اسمًا ستتعرف عليه في القائمة | +| `agent()` | شيء ما يقوم بالعمل — أعطه اسماً ستتعرف عليه في القائمة | | `tool_call()` | هذه أداة واحدة، وإليك ما أرجعته | -وما يصدره كل واحد بالفعل: +وما يصدره كل واحد فعلياً: | النطاق | يصدر | الغرض | | --- | --- | --- | -| `session()` | لا شيء | يربط معرف الجلسة، ويجمع تشغيلًا واحدًا | -| `agent()` | `agent_start`, `agent_end` | يحيط بوحدة عمل | +| `session()` | لا شيء | يربط معرف الجلسة، مجموعة تشغيل واحدة | +| `agent()` | `agent_start`, `agent_end` | يحيط بوحدة عمل واحدة | | `tool_call()` | `tool_use`, `tool_result` | يحيط بأداة واحدة ويقيسها | -كل شيء بداخله يمكن حذف `session_id` و `agent_id`. تربط النطاقات الهوية على متغيرات السياق وكل استدعاء حدث يقرأها مرة أخرى، لذا لا تمرر المعرفات عبر وظائفك أبدًا. +كل شيء بالداخل يمكن أن يحذف `session_id` و `agent_id`. تربط النطاقات الهوية على متغيرات السياق وكل نداء حدث يقرأها مرة أخرى، لذلك لا تمرر أبداً المعرفات من خلال وظائفك. -جميعها تعمل تحت `async with` وكذلك `with`. +تعمل الثلاثة جميعاً مع `async with` وكذلك مع `with`. -وضع الوكلاء المتداخل يبني الشجرة. يتم حساب `parent_id` والعمق من المكدس: +يبني التداخل للوكلاء الشجرة. يتم حساب `parent_id` والعمق من المكدس: ```python with failproofai_sdk.session(): @@ -62,44 +61,44 @@ with failproofai_sdk.session(): ## كيف يغلق النطاق -`agent()` يتعامل مع الاستثناءات نيابة عنك: +`agent()` يتعامل مع الاستثناءات لك: | ما حدث | الأحداث | النتيجة | | --- | --- | --- | -| لا شيء تم رفعه | `agent_end` | `success` | +| لم يحدث شيء | `agent_end` | `success` | | `Exception` | `error`، ثم `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`، ثم `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | `agent_end` فقط | `cancelled` | -يتم إصدار الخطأ قبل `agent_end`، لأن لوحة المعلومات تغلق الامتداد في `agent_end` وأي شيء بعده ينسب إلى لا شيء. الإلغاء ليس فشلًا، لذا لا تلوث عمليات التشغيل الملغاة سطح الأخطاء. يتم إعادة رفع الاستثناء دائمًا: لا يبتلع نطاق أبدًا. +يتم إصدار الخطأ قبل `agent_end`، لأن لوحة التحكم تغلق الامتداد في `agent_end` وأي شيء بعده يُنسب إلى لا شيء. الإلغاء ليس فشلاً، لذلك لا تلوث التشغيلات الملغاة سطح الأخطاء. يتم إعادة رفع الاستثناء دائماً: النطاق لا يبتلعه أبداً. -## طرق الأحداث +## طرق الحدث -خمسة عشر طريقة في ست عائلات. معظمها يأتي على شكل أزواج — تصدر الفتاحة، ثم الأغلقة، وتقيس SDK الامتداد بينهما. +خمسة عشر طريقة في ست عائلات. معظمها يأتي في أزواج — تصدر الفاتحة، ثم الأغلق، و SDK يقيس الامتداد بينهما. -| العائلة | يفتح | يغلق | مستقل | +| العائلة | فتح | إغلاق | مستقل | | --- | --- | --- | --- | | **الوكلاء** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | | **النماذج** | `model_request` | `model_response` | — | | **الأدوات** | `tool_use` | `tool_result` | — | -| **الخطاطيف** | `hook_triggered` | `hook_completed` | — | +| **الخطافات** | `hook_triggered` | `hook_completed` | — | | **البشر** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | -| **الأخطاء** | — | — | `error` | +| **الأعطال** | — | — | `error` | - فضّل النطاقات — `agent()` و `tool_call()` — حيثما تناسب. تضمن حدث الإغلاق حتى عندما يرفع الجسم استثناءً. وصل إلى هذه الطرق مباشرة عندما لا يتداخل تدفق التحكم، مثل استدعاء نموذج داخل دالة مساعدة. + فضّل النطاقات — `agent()` و `tool_call()` — أينما كانت مناسبة. إنها تضمن حدث الإغلاق حتى عندما يرفع الجسم. تصل إلى هذه الطرق مباشرة عندما لا يتداخل تدفق التحكم، مثل نداء نموذج داخل مساعد. -```python Agents +```python الوكلاء failproofai_sdk.event.agent_start(agent_id="planner", goal="find the cheapest flight") failproofai_sdk.event.agent_end(agent_id="planner", outcome="success", summary="...") failproofai_sdk.event.agent_pause(pause_id="p1", reason="awaiting approval") failproofai_sdk.event.agent_resume(pause_id="p1") ``` -```python Models +```python النماذج failproofai_sdk.event.model_request( model="gpt-4o-mini", messages=[{"role": "user", "content": "..."}], @@ -115,24 +114,24 @@ failproofai_sdk.event.model_response( ) ``` -```python Tools +```python الأدوات failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1", input={"q": "..."}) failproofai_sdk.event.tool_result(tool_name="search", tool_call_id="c1", output="...") ``` -```python Hooks +```python الخطافات failproofai_sdk.event.hook_triggered(hook_name="retrieve", hook_id="h1", trigger_event="node") failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome="success") ``` -```python Humans +```python البشر failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") failproofai_sdk.event.human_interrupt(reason="operator stopped the run", at_step="step_3") ``` -```python Failures +```python الأعطال failproofai_sdk.event.error( error_type="TimeoutError", message="provider timed out after 30s", @@ -142,23 +141,23 @@ failproofai_sdk.event.error( - **عائلتا البشر تشيران في الاتجاهات المعاكسة.** + **العائلتان البشريتان تشير في اتجاهين متعاكسين.** | الطرق | المعنى | | --- | --- | - | `human_wait` / `human_input` | **طلب الوكيل من شخص** — بوابة موافقة، سؤال توضيحي | - | `human_pause` / `human_interrupt` | **شخص تصرف على الوكيل** — زر إيقاف، إيقاف مؤقت من المشغل | + | `human_wait` / `human_input` | **الوكيل طلب من شخص** — بوابة موافقة، سؤال توضيحي | + | `human_pause` / `human_interrupt` | **شخص تصرف على الوكيل** — زر إيقاف، توقف المشغل | - لا يشير أي إطار عمل الزوج الثاني، لذا فهو دائمًا لك لإصداره. + لا يشير أي إطار عمل إلى الزوج الثاني، لذا فهو دائماً لك لإصداره. - **مرر `request_id` عندما تعمل استدعاءات النموذج بالتزامن.** بدونه، يتم إقران الطلبات والردود بترتيب الوصول لكل وكيل — والمكالمات المتزامنة تقترن بشكل خاطئ، وتوصل كل رد إلى الطلب الخاطئ. + **مرر `request_id` عندما تعمل نداءات النموذج بالتزامن.** بدونه، تتزاوج طلبات الاستجابات بترتيب الوصول لكل وكيل — والنداءات المتزامنة تتزاوج بشكل خاطئ، مرفقة كل استجابة بالطلب الخاطئ. ## مثال -حلقة استدعاء أدوات ضد OpenAI API، بدون إطار عمل للوكيل: +حلقة استدعاء الأداة مقابل OpenAI API، بدون إطار عمل وكيل: ```python import json @@ -205,11 +204,11 @@ with failproofai_sdk.session(): }) ``` -ينتج عن هذا نفس أنواع الأحداث الستة التي يعطيك محول. تشحن النسخة الكاملة القابلة للتشغيل، مع تعريفات الأداة، في مستودع SDK تحت `docs/manual/examples/`. +ينتج عن هذا نفس أنواع الأحداث الستة التي سيعطيك المحول. الإصدار الكامل القابل للتشغيل، مع تعريفات الأداة، يأتي في مستودع SDK تحت `docs/manual/examples/`. -## الخيوط والعمليات غير المتزامنة +## الخيوط و async -تنتشر متغيرات السياق في مهام asyncio تلقائيًا. لا تنتشر في الخيوط الجديدة، لأن الخيط يبدأ بسياق فارغ. +تنتشر متغيرات السياق في مهام asyncio تلقائياً. لا تنتشر في خيوط جديدة، لأن الخيط يبدأ بسياق فارغ. ```python # asyncio: nothing to do @@ -222,35 +221,35 @@ threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -بدون `propagate()`، تثير أحداث العامل `TypeError` تسمي الإصلاح بدلاً من الهبوط بدون جلسة. هذا مقصود: حدث بدون جلسة يتم تخطيه بواسطة الاستيعاب والإجابة `200`، وهو الفشل الصامت الذي تم تصميم طبقة الهوية لمنعه. +بدون `propagate()`، تثير أحداث العامل `TypeError` تسمي الإصلاح بدلاً من الهبوط على جلسة لا شيء. هذا متعمد: حدث بدون جلسة يتم تخطيه بواسطة ingest والإجابة `200`، وهو الفشل الصامت الذي توجد طبقة الهوية لمنعه. ## أدرج إطار عمل بدون محول -يعطيك كل إطار عمل للوكيل نفس ثلاثة طبقات. مرّرها ولديك تتبع كامل — لا تفعل المحولات الأربعة المشحونة أكثر من هذا. +كل إطار عمل وكيل يعطيك نفس الفتحات الثلاثة. اربطها وسيكون لديك تتبع كامل — المحولات الأربعة المشحونة لا تفعل أكثر من هذا. -| الطبقة | ما تكتبه | ما يصل | +| الفتحة | ما تكتبه | ما يهبط | | --- | --- | --- | | التشغيل | `session()` + `agent()` | `agent_start`, `agent_end` | | كل أداة | `tool_call()` | `tool_use`, `tool_result` | -| كل استدعاء نموذج | زوج `model_*` | `model_request`, `model_response` | +| كل نداء نموذج | زوج `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - في أياً كان ما يسميه الإطار غلافًا للأداة أو وسيطًا. + + في أي مكان يستدعيه الإطار غلاف أداة أو برنامج وسيط. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -265,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **هل لديك عقدة أو حدود خطوة أو وسيط يستحق الرؤية؟** لفّه في زوج خطاطيف — `hook_triggered` / `hook_completed` — وليس وكيل `agent()` متداخل. `agent_id` هو جانب منخفض الأساسية، وإدخال واحد لكل عقدة يغرقه. تُعرض امتدادات الخطاطيف بنفس الطريقة وتعطيك كمون لكل عقدة. + **لديك عقدة أو خطوة أو حدود برنامج وسيط تستحق الرؤية؟** غلفها في زوج خطاف — `hook_triggered` / `hook_completed` — وليس `agent()` متداخل. `agent_id` هو جانب cardinality منخفض، وإدخال واحد لكل عقدة يغرقه. تُعرض امتدادات الخطاف بنفس الطريقة وتمنحك زمن الكمون لكل عقدة. - **اليدوي والتلقائي يتكونان.** محول يعمل داخل نطاق مكتوب يدويًا ينضم إلى تلك الجلسة والآباء لهذا الوكيل، لذا تحصل على شجرة واحدة بدلاً من اثنتين — مفيد عندما تدرج إطار عمل واحد بنفسك إلى جانب واحد مدعوم. + **اليدوي والتلقائي يتكونان.** يدخل محول يعمل داخل نطاق مكتوب يدوياً تلك الجلسة والآباء إلى ذلك الوكيل، حتى تحصل على شجرة واحدة بدلاً من شجرتين — مفيد عندما تدرج إطار عمل بنفسك إلى جانب واحد مدعوم. - سببان، والطبقات الثلاث أعلاه هي الإجابة على كليهما: + سببان، والفتحات الثلاثة أعلاه هي الإجابة على كليهما: - `autogen-core` لم يتم صيانته منذ سبتمبر 2025. - - لا تفضح AG2 نقطة تسجيل على مستوى العملية معادلة لخطاطيف أطر العمل الأخرى، لذا فإن إدراجها يعني لف كل وكيل في كل موقع بناء. + - AG2 لا يعرض نقطة تسجيل على مستوى العملية تعادل خطافات أطر العمل الأخرى، لذا فإن إدراجها يعني تغليف كل وكيل في كل موقع البناء. - يسجل تخطيط الطبقات اليدوية نفس الأحداث، بنفس الدقة، كما سيفعل محول مشحون. + يسجل رسم الفتحات يدوياً نفس الأحداث، بنفس الدقة، كما سيفعل محول مشحون. ## الذهاب أعمق -كيف يعمل التسجيل بالفعل. لا شيء من هذا مطلوب للبدء. +كيف يعمل التسجيل فعلياً. لا شيء من هذا مطلوب للبدء. - + -كل تسجيل له نفس الشكل: يفتح امتداد، يتداخل العمل داخله، وكل حدث فتح يحصل على حدث إغلاق. +كل تسجيل له نفس الشكل: يفتح امتداد، يتداخل العمل بداخله، وكل حدث افتتاحي يحصل على حدث إغلاق. ```mermaid flowchart LR @@ -301,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -**الزوج** هو الوحدة. كل حدث إغلاق يحمل مدة تقيسها SDK من حدثها الافتتاحي. +**الزوج** هو الوحدة. كل حدث إغلاق يحمل مدة يقيسها SDK من الحدث الافتتاحي الخاص به. -فيما يلي تشغيل حقيقي واحد لكل إطار عمل — تم التقاطه من الأمثلة التي تشحن مع SDK، اسم النموذج معياري. لاحظ كم يعود من استدعاء واحد. +فيما يلي تشغيل واحد حقيقي لكل إطار عمل — مأخوذ من الأمثلة المشحونة مع SDK، اسم النموذج معياري. لاحظ كم يعود من نداء واحد. @@ -324,7 +323,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - تصبح العقد أزواج خطاطيف، لذا تحصل على كمون لكل عقدة دون أن تملأ قائمة الوكيل. + تصبح العقد أزواج خطاف، لذا تحصل على زمن الكمون لكل عقدة بدون أن تزحمها قائمة الوكيل. @@ -341,7 +340,7 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - يصبح `role` لكل وكيل اسم امتداده، لذا ينقسم الكمون ومصروف التوكن حسب الدور. + يصبح `role` لكل وكيل اسم امتداده، لذا ينقسم زمن الكمون ومصروف الرمز حسب الدور. @@ -361,7 +360,7 @@ flowchart LR 26 +7.038s agent_end Agent · success ``` - حلقة الوكيل نفسها مرئية، وليس فقط استدعاءات النموذج الخاصة به. + حلقة الوكيل نفسها مرئية، ليس فقط نداءاته النموذجية. @@ -376,10 +375,10 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - لا توجد أزواج خطاطيف: Pydantic AI ليس لديه حد عقدة أو خطوة لحيط. + لا توجد أزواج خطاف: Pydantic AI لا يملك حد عقدة أو خطوة للإحاطة به. - + ```text 6 events 1 +0.000s agent_start main 2 +0.000s tool_use population @@ -389,7 +388,7 @@ flowchart LR 6 +0.000s agent_end main · success ``` - تصدر هذه بنفسك. نفس أنواع الأحداث، نفس الدقة — تكلفك مواقع المكالمة. + أنت تصدر هذه بنفسك. نفس أنواع الأحداث، نفس الدقة — إنه يكلفك مواقع الاستدعاء. @@ -397,28 +396,28 @@ flowchart LR -**لا يوجد حدث نهاية جلسة.** الجلسة ليست شيئًا تغلقه — إنها مجموعة من الأحداث التي تشارك `session_id`. +**لا توجد حدث نهاية الجلسة.** الجلسة ليست شيء تغلقه — إنها مجموعة من الأحداث تشترك في `session_id`. -يتم استنتاج الحالة من شكل التتبع: +يتم استخلاص الحالة من شكل التتبع: | الحالة | متى | | --- | --- | -| `ongoing` | لا يزال امتداد واحد على الأقل مفتوحًا | -| `paused` | `agent_pause` ليس له عنوان `agent_resume` المطابق | -| `error` | لا شيء مفتوح، وفشل حدث واحد على الأقل | -| `done` | لا شيء مفتوح، وفشل لا شيء | +| `ongoing` | لا يزال امتداد واحد على الأقل مفتوحاً | +| `paused` | `agent_pause` بدون `agent_resume` مطابقة | +| `error` | لا شيء مفتوح، وحدث واحد على الأقل فشل | +| `done` | لا شيء مفتوح، وشيء فشل | -لذا تنتهي الجلسة عندما يتم إغلاق كل زوج. تصدر المحولات `agent_end` نيابة عنك، وعند الهدم تغلق أي شيء لا يزال مفتوحًا وتصرفه كناقص — تستقر عملية تشغيل منهارة كـ `done` مع فجوة مرئية بدلاً من التعليق. +لذلك تنتهي الجلسة عندما يتم إغلاق كل زوج. يصدر المحولات `agent_end` لك، وعند الهدم يغلقون أي شيء لا يزال مفتوحاً ويوقعونه كغير كامل — يستقر التشغيل المتعطل كـ `done` بفجوة مرئية بدلاً من التعليق. - هذا هو السبب في أن الجلسة يمكن أن تمتد على استدعاءين. يوقف `interrupt()` من LangGraph التشغيل، وامتداد الجذر يبقى مفتوحًا متعمدًا، واستدعاء الاستئناف يغلقه. كلا الاستدعاءين جلسة واحدة. + هذا هو السبب في أن الجلسة يمكن أن تمتد على نداءين. يوقف `interrupt()` في LangGraph التشغيل، يبقى الامتداد الجذري مفتوحاً عن قصد، والنداء المستأنف يغلقه. كلا النداءين جلسة واحدة. - + -`session_id` و `agent_id` اختياريان على كل طريقة حدث. محذوف، يتم حلهما من النطاق المحيط: +`session_id` و `agent_id` اختياريان في كل طريقة حدث. محذوفاً، يحلان من النطاق المرفق: ```python with failproofai_sdk.session(): @@ -426,123 +425,123 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -تمريرها بشكل صريح لا يزال يعمل ويأخذ الأسبقية. بدون شيء مرتبط وبدون تمرير، يرفع الاستدعاء `TypeError` تسمي الإصلاح بدلاً من إصدار حدث بدون جلسة، والذي ستتخطاه الاستيعاب أثناء الإجابة `200`. +تمريرهما بشكل صريح يعمل بعد ذلك ويأخذ الأسبقية. بدون شيء مرتبط وبدون شيء تم تمريره، يرفع الاستدعاء `TypeError` تسمية الإصلاح بدلاً من إصدار حدث بدون جلسة، والتي ستقفزها ingest مع الإجابة `200`. -تربط النطاقات الهوية على متغيرات السياق. تنتشر تلك إلى مهام asyncio تلقائيًا ولكن ليس إلى خيوط جديدة — لف العامل في `failproofai_sdk.propagate()`. +تربط النطاقات الهوية على متغيرات السياق. تلك تنتشر في مهام asyncio تلقائياً لكن ليس في خيوط جديدة — غلف عامل في `failproofai_sdk.propagate()`. #### من يضرب أي معرف -| المعرف | يضرب بواسطة | ملاحظات | +| المعرف | تم ضربه بواسطة | ملاحظات | | --- | --- | --- | -| `session_id` | أنت، أو SDK | `session("chat-42")` يُستخدم حرفيًا؛ محذوف، SDK يُنشئ `uuid4().hex` | -| `agent_id` | أنت، أو الإطار | من `agent("analyst")`، أو `role` من CrewAI، أو `FunctionAgent.name`. تُرفض القيمة التي تبدو مثل UUID وتُستبدل | -| `tool_call_id`, `hook_id`, `request_id` | أنت، أو الإطار | تعيد المحولات استخدام معرفات التشغيل الخاصة بالإطار، وهذا هو السبب في بقاء الأزواج بعد قفزات الخيط | -| **معرف الحدث** | **السحابة، عند الاستيعاب** | SDK لا يصدر أي شيء | -| **`dedup_key`** | **السحابة، عند الاستيعاب** | بصمة تجزئة من org والجلسة والطابع الزمني والنوع والحمل. هذه هي الهوية الحقيقية — فهي تجعل دفعة معاد محاولتها تنهار بدلاً من التكرار | +| `session_id` | أنت، أو SDK | `session("chat-42")` يُستخدم حرفياً؛ محذوفاً، ينشئ SDK `uuid4().hex` | +| `agent_id` | أنت، أو الإطار | من `agent("analyst")`، `role` في CrewAI، `FunctionAgent.name`. يتم رفض قيمة تبدو مثل UUID واستبدالها | +| `tool_call_id`, `hook_id`, `request_id` | أنت، أو الإطار | تعيد المحولات استخدام معرفات التشغيل الخاصة بالإطار، وهذا هو السبب في أن الأزواج تبقى نقافز الخيط | +| **معرف الحدث** | **السحابة، عند الاستقبال** | SDK لا ينبعث أي | +| **`dedup_key`** | **السحابة، عند الاستقبال** | تجزئة org و session و timestamp و type و payload. هذه هي الهوية الحقيقية — إنها تجعل دفعة أعيد محاولتها تنهار بدلاً من التكرار | #### كيف تحل المحولات `session_id` -المباراة الأولى تفوز: +أول تطابق يفوز: -1. `session_id` صريح خيار -2. البيانات الوصفية لكل استدعاء -3. نطاق `session()` المحيط -4. البيانات الوصفية للإطار -5. معرف التشغيل الخاص بالإطار +1. `session_id` خيار صريح +2. البيانات الوصفية لكل نداء +3. نطاق `session()` المرفق +4. بيانات إطار العمل الوصفية +5. معرف التشغيل الخاص بإطار العمل -لا يتم اختراعه أثناء وجود أحد هؤلاء — سيؤدي معرف مركب إلى تقسيم تشغيل واحد عبر عدة جلسات. +لا يتم اختراعه أبداً مع وجود أحد تلك — معرف مركب سيقسم تشغيل واحد عبر عدة جلسات. -#### احتفظ بـ `agent_id` منخفض الأساسية +#### حافظ على `agent_id` على cardinality منخفضة -إنه الجانب الأساسي على كل سطح لوحة معلومات، وعمود `LowCardinality(String)`. قيمة لكل تشغيل تضعف العمود وتملأ منتقي التصفية بإدخال واحد لكل تشغيل. +إنه الجانب الأساسي على كل سطح لوحة تحكم، وعمود `LowCardinality(String)`. تقلل القيمة لكل تشغيل العمود وتملأ قائمة القائمة المنسدلة بإدخال واحد لكل تشغيل. -تدافع المحولات عن هذا العمود نيابة عنك: +تحافظ المحولات على هذا العمود لك: -| الإطار يسلّم | مسجل باسم | لماذا | +| يسلم الإطار | مسجل باسم | لماذا | | --- | --- | --- | -| `3f9a1c2b-…` (UUID) | `main` | لا شيء قابل للقراءة للحفظ | -| سلسلة سداسية عشرية عارية طويلة | `main` | نفس الشيء | -| `agent-3f9a1c2b-…` | `agent` | معرف كل تشغيل مقطوع، الجزء القابل للقراءة محفوظ | -| `agent-v2` | `agent-v2` | يتم ترك الأجزاء القصيرة وحدها | -| `step-3` | `step-3` | نفس الشيء | +| `3f9a1c2b-…` (معرف فريد) | `main` | لا شيء يمكن قراءته للاحتفاظ به | +| سلسلة سادسة عشرية طويلة عارية | `main` | نفس | +| `agent-3f9a1c2b-…` | `agent` | تم تجريد معرف لكل تشغيل، تم الاحتفاظ بالجزء القابل للقراءة | +| `agent-v2` | `agent-v2` | تُترك الأجزاء القصيرة وحدها | +| `step-3` | `step-3` | نفس | -معرف حقيقي محفوظ على `fw_agent_id` / `fw_run_id`، حيث يبقى قابلًا للاستعلام بدون أن يكون جانبًا. +المعرف الحقيقي يبقى على `fw_agent_id` / `fw_run_id`، حيث يبقى قابلاً للاستعلام بدون أن يكون جانباً. - **هذا الحارس يلمس فقط التسميات التي **اختارها الإطار**. `agent_id` تمرره بنفسك — إلى `event.*`، أو إلى `failproofai_sdk.agent(...)` — يتم تسجيله بالضبط كما هو معطى. إعادة كتابة حجة صريحة بصمت ستكون أسوأ من الأساسية التي تمنعها، لذا سمّ امتداداتك وفقًا لذلك. + **هذا الحراس يلمس فقط التسميات التي اختارها *الإطار*.** `agent_id` تمرره بنفسك — إلى `event.*`، أو إلى `failproofai_sdk.agent(...)` — مسجل تماماً كما هو محدد. إعادة كتابة صريحة لحجة صريحة ستكون أسوأ من cardinality التي تمنعها، لذا سمِّ امتدادات خاصة بك وفقاً لذلك. - + | المجموعة | الأحداث | | --- | --- | | الوكلاء | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | | النماذج | `model_request`, `model_response` | | الأدوات | `tool_use`, `tool_result` | -| الخطاطيف | `hook_triggered`, `hook_completed` | +| الخطافات | `hook_triggered`, `hook_completed` | | البشر | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | -| الأخطاء | `error` | +| الأعطال | `error` | -أي إطار عمل يسجل ما، المقاس من التشغيلات أعلاه: +أي إطار عمل يسجل ماذا، مقاس من التشغيلات أعلاه: -| الحدث | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | +| الحدث | LangGraph | CrewAI | LlamaIndex | Pydantic AI | مخصص | | --- | :--: | :--: | :--: | :--: | :--: | -| بدء الوكيل ونهايته | Yes | Yes | Yes | Yes | You | -| طلب النموذج والرد | Yes | Yes | Yes | Yes | You | -| استخدام الأداة والنتيجة | Yes | Yes | Yes | Yes | You | -| تم تشغيل الخطاف واكتمل | Node | Task | Step | — | You | -| خطأ | Yes | Yes | Yes | Yes | Automatic | -| انتظار الإنسان والإدخال | Yes | Yes | Yes | — | You | -| إيقاف الوكيل واستئنافه | Yes | Yes | Yes | — | You | +| بداية الوكيل والنهاية | نعم | نعم | نعم | نعم | أنت | +| نموذج الطلب والاستجابة | نعم | نعم | نعم | نعم | أنت | +| استخدام الأداة والنتيجة | نعم | نعم | نعم | نعم | أنت | +| تم تشغيل الخطاف واكتمل | عقدة | مهمة | خطوة | — | أنت | +| خطأ | نعم | نعم | نعم | نعم | تلقائي | +| الانتظار البشري والمدخلات | نعم | نعم | نعم | — | أنت | +| الوكيل يوقف ويستأنف | نعم | نعم | نعم | — | أنت | -شرطة تعني الإطار ليس لديه مثل هذا المفهوم. `human_pause` و `human_interrupt` يصفان **شخصًا** يتصرف على الوكيل، والذي لا يشير إليه أي إطار عمل — أصدر هؤلاء بنفسك. +الشرطة تعني أن الإطار ليس لديه مثل هذا المفهوم. `human_pause` و `human_interrupt` تصف *شخص* يتصرف على الوكيل، الذي لا يشير إليه أي إطار — انبعث بنفسك. -حدث أبدًا لا يصل وحده. يفتح امتداد واحد، يغلق واحد، وحدث الإغلاق يحمل مدة تقيسها SDK من الحدث الافتتاحي. +حدث لا يصل وحده أبداً. يفتح أحدهما امتداد، يغلقه الآخر، والحدث الإغلاق يحمل مدة يقيسها SDK من الحدث الافتتاحي. -| يفتح | يغلق | حدث الإغلاق يحمل | +| يفتح | يغلق | الحدث الإغلاق يحمل | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | -| `model_request` | `model_response` | توكنات، `stop_reason`، الكمون | +| `model_request` | `model_response` | الرموز، `stop_reason`، زمن الكمون | | `tool_use` | `tool_result` | `output` أو `error`، المدة | | `hook_triggered` | `hook_completed` | `outcome`، المدة | -| `agent_pause` | `agent_resume` | كم دامت الإيقافة | -| `human_wait` | `human_input` | الإجابة، وكم من الوقت استغرق الشخص | +| `agent_pause` | `agent_resume` | كم دامت الوقفة | +| `human_wait` | `human_input` | الإجابة، وكم استغرق الشخص | - حدث افتتاح بدون إغلاق هو امتداد لا ينتهي. الجلسة تُعرض كما لو كانت لا تزال قيد التشغيل، إلى الأبد، ومدة نشاطها الفعلية تستمر في الزيادة. هذا هو وضع الفشل الذي يجب الحذر منه عندما تدرج يدويًا. + حدث افتتاحي بدون حدث إغلاق هو امتداد لا ينتهي أبداً. تُرسّم الجلسة كما لا تزال قيد التشغيل، إلى الأبد، ومدتها النشطة تستمر في النمو. هذا هو فشل العرض الذي يجب مراقبته عند الإدراج يدوياً. #### قواعد الارتباط -- أعد استخدام نفس `tool_call_id`, `hook_id`, `pause_id`, أو `input_id` لحدث الإكمال المطابق. -- SDK يحسب `duration_ms` لـ `tool_result`, `hook_completed`, `agent_resume`, و `human_input`. تمريره إلى تلك الطرق يرفع `ValueError`. -- يتم قبول `duration_ms` **في** `model_response`، لأن المتصل فقط يعرف الكمون الحقيقي للمزود. يجب أن يكون عددًا صحيحًا — عدد عشري يرفع `ValueError` في موقع الاستدعاء، لأن الخادم يقرأ العمود كعدد صحيح بدون إشارة 32 بت وسيخزن NULL لأي شيء آخر. -- مفاتيح الارتباط محدودة حسب النوع والجلسة، لذا قد تشارك أداة وخطاف معرفًا بأمان، وقد تعيد جلستان متزامنتان استخدام نفس المعرفات بدون تضارب. لا تقتصر على الوكيل: الزوج الذي يُفتح تحت وكيل واحد ويُغلق تحت وكيل آخر لا يزال يرتبط، وهي الحالة العادية في أطر العمل متعددة الوكلاء. -- `request_id` يقترن `model_request` مع `model_response`. بدونه، تُقرن أحداث النموذج بالترتيب لكل وكيل، لذا تقترن المكالمات المتزامنة بشكل خاطئ. -- الزوج المقسم عبر العمليات لا يزال يرتبط باتجاه مصب النهر، لكن SDK لا يمكنه حساب مدته داخل العملية. -- خريطة قيد الانتظار تحتوي على 000 بداية على الأكثر، وتطرد الإدخال الأقدم عندما تكون ممتلئة. +- أعد استخدام نفس `tool_call_id` أو `hook_id` أو `pause_id` أو `input_id` لحدث الإكمال المطابق. +- حسابات SDK `duration_ms` لـ `tool_result` و `hook_completed` و `agent_resume` و `human_input`. تمريره إلى تلك الطرق يرفع `ValueError`. +- `duration_ms` **يُقبل** على `model_response`، لأن فقط المتصل يعرف زمن المزود الحقيقي. يجب أن يكون عدداً صحيحاً — عدد عشري يرفع `ValueError` في موقع الاستدعاء، لأن الخادم يقرأ العمود كعدد صحيح بدون إشارة 32 بت ويخزن NULL لأي شيء آخر. +- مفاتيح الارتباط مجالها حسب النوع والجلسة، لذا يمكن لاستدعاء أداة وخطاف مشاركة معرف بأمان، ويمكن لجلستين متزامنتين إعادة استخدام نفس المعرفات بدون تصادم. لا تكون مجالاً بواسطة وكيل: زوج مفتوح تحت وكيل واحد ومغلق تحت آخر لا يزال يرتبط، وهي الحالة العادية في الأطر متعددة الوكلاء. +- `request_id` يزاوج `model_request` مع `model_response`. بدونه، أحداث النموذج تتزاوج بالترتيب لكل وكيل، لذا تتزاوج النداءات المتزامنة بشكل خاطئ. +- زوج مقسم عبر العمليات لا يزال يرتبط في المصب، لكن SDK لا يمكنه حساب مدته في العملية. +- تمسك الخريطة المعلقة بـ 10,000 ابدأ كحد أقصى وتطرد الإدخال الأقدم عندما تكون ممتلئة. - + -تثبيت `failproofai-sdk` يثبت كل شيء، جميع محولات الأربعة مضمنة. تسحب الإضافات **الإطار**، وليس المحول. +تثبيت `failproofai-sdk` يثبت كل شيء، كل المحولات الأربعة مضمونة. تسحب الإضافات **الإطار**، وليس المحول. ```python import failproofai_sdk # loads nothing outside the standard library failproofai_sdk.instrument() # imports only the adapters you actually need ``` -`import failproofai_sdk` منطقيًا بدون تبعيات، يتم إنفاذه بواسطة اختبار يثبت الـ wheel المبني مع `--no-deps` وآخر يثبت عدم وصول أي إطار عمل إلى `sys.modules`. +`import failproofai_sdk` هو بدون تبعيات بموجب العقد، مفروض بواسطة اختبار يثبت العجلة المدمجة بـ `--no-deps` وآخر يثبت عدم وصول أي إطار إلى `sys.modules`. - لا يوجد `failproofai_sdk.crewai` attribute. المحولات متعمدة غير معروضة على حزمة المستوى الأعلى: لمس واحد كان سيستورد الإطار كأثر جانبي لوصول الخاصية، مكسرًا وعد عدم التبعية. استخدم `instrument()`. + لا يوجد `failproofai_sdk.crewai` تصريح. المحولات مقصودة عن قصد ألا تُعرّض على حزمة المستوى الأعلى: لمس أحدها سيستورد الإطار كتأثير جانبي لوصول السمة، مما يكسر وعد عدم التبعيات. استخدم `instrument()`. ```python @@ -551,14 +550,14 @@ failproofai_sdk.instrument("crewai") # exactly one, by name failproofai_sdk.uninstrument("crewai") # put it back ``` -| الاسم | يقبل أيضًا | +| الاسم | يقبل أيضاً | | --- | --- | | `langchain` | `langgraph`, `langchain_core` | | `crewai` | — | | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -يقرأ الكشف التلقائي `sys.modules`، وليس قائمة الحزمة المثبتة، لذا الإطار الذي لديك مثبت لكن لم تستورده أبدًا لا يتم إدراجه ولا يتم استيراده بالنيابة عنك. لترى ما يتم وضعه: +قراءة الكشف التلقائي `sys.modules`، وليس قائمة الحزمة المثبتة، لذا فإن إطار عمل لديك مثبت لكن لم تستورده أبداً لا يتم إدراجه ولا يتم استيراده نيابة عنك. لرؤية ما هو موصول: ```python from failproofai_sdk.integrations import active, available @@ -568,38 +567,38 @@ active() # ('langchain',) ``` - **`instrument("crewai")` على آلة بدون CrewAI لا يرفع.** إنه يسجل تحذيرًا ويعود `()`، لذا إطار واحد مفقود لا يأخذ عملية تدرج الآخرين. + **`instrument("crewai")` على جهاز بدون CrewAI لا يرفع.** يسجل تحذيراً ويرجع `()`، حتى أحد إطر العمل المفقودة لا تأخذ عملية تدرج أيضاً آخرين. - التحذير يحمل `ImportError` الأساسي، وتلك الرسالة تسمي أمر التثبيت الدقيق — لذا الإصلاح في سجلاتك، وليس مخفيًا. + التحذير يحمل `ImportError` الأساسي، وتلك الرسالة تسمي أمر التثبيت الدقيق — لذا الإصلاح يكون في سجلاتك، ليس مختبئاً. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - اضبط `FAILPROOFAI_SDK_STRICT=1` لجعله يرفع بدلاً من ذلك. يتم قراءة هذا الرايز **مرة واحدة وتخزينه مؤقتًا**، لذا صدّره قبل أن تبدأ عمليتك بدلاً من تعيينه في منتصف التشغيل. + اضبط `FAILPROOFAI_SDK_STRICT=1` لإرفاعه بدلاً من ذلك. تُقرأ تلك العلم **مرة واحدة وتُخزن مؤقتاً**، لذا يصدرها قبل بدء العملية بدلاً من تعيينها في منتصف التشغيل. - **`instrument()` يجب أن يأتي *بعد* استيراد إطار العمل الخاص بك.** الكشف التلقائي يقرأ `sys.modules`، لذا استدعاء عاري فوق الاستيراد يجد لا شيء، ويثبت لا شيء، ويعود `()`. + **`instrument()` يجب أن يأتي *بعد* استيراد إطار العمل الخاص بك.** قراءة الكشف التلقائي `sys.modules`، لذا نداء عارٍ فوق الاستيراد يجد لا شيء، يثبت لا شيء، ويرجع `()`. -```python Wrong +```python خطأ import failproofai_sdk failproofai_sdk.instrument() # sys.modules has no langchain yet -> () import langchain # too late, nothing is wired ``` -```python Right +```python صحيح import langchain # import the framework first import failproofai_sdk failproofai_sdk.instrument() # finds it -> ('langchain',) ``` -```python Right, order-proof +```python صحيح، مستقل الترتيب import failproofai_sdk # Naming it imports the adapter on request, so this works from anywhere. @@ -607,7 +606,7 @@ failproofai_sdk.instrument("langchain") ``` -أخطئ في هذا والعملية تعمل مع SDK مستوردة، والمحول يبدو منصبًا، و **لم يصدر حدث واحد**. إنه يسجل تحذيرًا يقول بالضبط ذلك — لذا تحقق من سجلاتك أولاً عندما لا يسجل التشغيل شيئًا. +احصل على هذا خطأ والعملية تعمل مع SDK مستوردة، المحول يبدو مثبتاً، و **حدث واحد لم يُصدر**. يسجل تحذيراً يقول بالضبط ذلك — لذا تحقق من السجلات أولاً عندما لا يسجل التشغيل شيئاً. @@ -615,83 +614,85 @@ failproofai_sdk.instrument("langchain") ```mermaid flowchart LR - A["Your agent"] --> B["Adapter"] - B --> C["Writer
in-memory queue"] - C -->|"every 0.5s"| D["Spool
JSONL on disk"] - D --> E["Failproof daemon"] - E -->|"HTTPS"| F["Cloud"] + A["وكيلك"] --> B["محول"] + B --> C["كاتب
قائمة الذاكرة"] + C -->|"كل 0.5s"| D["ملف
JSONL على القرص"] + D --> E["مراقب Failproof"] + E -->|"HTTPS"| F["السحابة"] ``` | المرحلة | الوظيفة | يعمل في | | --- | --- | --- | -| المحول | يترجم استدعاء استدعاء الإطار إلى أحد أنواع الأحداث الـ 15 | عمليتك | -| الكاتب | يصف قائمة، دفعات، يكتب JSONL بذرية | عمليتك، خيط خلفي | -| البكرة | نقل متين، يبقى بعد خروج عمليتك | قرص محلي | -| الشيطان | يراقب البكرة، يشحن الدفعات، يحذف ما شحنه | آلتك | -| الاستيعاب | يعين معرف الصف ومفتاح dedup، ينقل الأعمدة القابلة للاستعلام | السحابة | +| محول | ترجمة رد اتصال الإطار إلى أحد أنواع الأحداث 15 | عمليتك | +| كاتب | طوابير، دفعات، كتابة JSONL ذرية | عمليتك، خيط الخلفية | +| ملف | نقل دائم، ينجو من خروج عملية | القرص المحلي | +| مراقب | يراقب الملف، سفن دفعات، حذف ما ينقله | آلتك | +| استقبال | يعين معرف صف و dedup key، يرقي أعمدة قابلة للاستعلام | السحابة | -البكرة هي ما يجعل هذا آمنًا: وكيلك لا ينتظر أبدًا الشبكة، وانقطاع السحابة يعني ديريتوري متنامي بدلاً من فقدان الأحداث. +الملف هو ما يجعل هذا آمناً: وكيلك لا يسد أبداً على الشبكة، وانقطاع السحابة يعني دليل ينمو بدلاً من فقدان الأحداث. -كل تصريف يكتب ملف دفعة واحدة، `.tmp` أولاً، ثم `fsync`، ثم إعادة تسمية ذرية: +كل تنظيف يكتب ملف دفعة واحدة، `.tmp` أولاً، ثم `fsync`، ثم إعادة تسمية ذرية: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -الشيطان يلتقط `.jsonl` فقط، لذا لا يمكنه أبدًا قراءة ملف نصف مكتوب. الساق يحمل طابعًا زمنيًا ومعرف عملية ورقم تسلسل، لذا عمليتان تصريفتان في نفس الميلي ثانية لا يمكن أن تصطدما. يتم تغطية قائمة الانتظار بـ 000 حدث؛ بعد ذلك يسقط الأقدم ويسجل. +يختار المراقب فقط `.jsonl`، لذا لا يمكن أبداً قراءة ملف نصف مكتوب. الجذع يحمل طابع زمني، معرف العملية ورقم التسلسل، لذا لا يمكن لعمليتين تنظيف في نفس الميلي ثانية أن تصطدما. تُغطى القائمة بـ 10,000 حدث؛ بعد ذلك تسقط الأقدم وتسجل. - **`collector.redact` يافتراضي إلى `minimal` لأحداث SDK أيضًا.** يكشط SDK قبل كتابة دفعة على القرص، ويكرر الشيطان نفس المسار الحتمي قبل التحميل بحيث تكون الدفعات من SDKs الأقدم محمية. + **`collector.redact` لا ينطبق على أحداث SDK الخاصة بك.** لا يراها أبداً. -يقرأ الشيطان كل دفعة ويطبق الكشط في الذاكرة قبل التحميل. لا يعيد كتابة ملف البكرة الذي قرأه. +المراقب **ينقل** دفعاتك. إنه لا يفتحها أو يعيد كتابتها. -| الأحداث | مكتوب بواسطة | أين يعمل الكشط الحد الأدنى | +| الأحداث | مكتوب بواسطة | معاد بواسطة `collector.redact`؟ | | --- | --- | --- | -| نصوص جلسات CLI | الشيطان | قبل كتابة الشيطان للدفعة | -| نشاط الخطاطيف | الشيطان | قبل كتابة الشيطان للدفعة | -| **كل شيء يصدره SDK** | **عمليتك** | **قبل كتابة SDK للدفعة وقبل تحميل الشيطان مرة أخرى** | +| نصوص جلسة CLI | المراقب | نعم | +| نشاط الخطاف | المراقب | نعم | +| **كل ما يصدره SDK** | **عمليتك** | **لا** | + +التعديل يعمل حيث **يكتب** المراقب أحداثه الخاصة — وليس حيث تُنقل الدفعات. لذا طلب أو حجة أداة تحمل مفتاح API لا تزال تحمله عند الوصول. -اضبط `collector.redact` على `off` فقط عندما تكون الحمولات الحرفية متطلبًا صريحًا؛ SDK والشيطان كلاهما يحترم هذا الإعداد. يمسك الكشط الحد الأدنى مفاتيح API الشائعة والتوكنات الحاملة و JWTs والتنازلات السرية. لا يمكنها تحديد نثر حساس تعسفي. +هذا مقصود. هذه هي نداءات الإدراج الخاصة بك، وإعادة الكتابة في الحركة ستعني أن الأحداث التي تستقبلها ليست الأحداث التي أصدرتها. - **تتحكم في الحمولات في المصدر، في مكانين:** + **أنت تتحكم في الحمولات من المصدر، في مكانين:** - - أطفئ التقاط المحتوى على المحول. **اسم الخيار يختلف، وأحد المحولات ليس لديه** — هذا ليس مفتاحًا عامًا واحدًا: - - LangChain / LangGraph، Pydantic AI — `capture_content=False` + - أوقف التقاط المحتوى على المحول. **اسم الخيار يختلف، ومحول واحد لا يملك أي** — هذا ليس مفتاح عام واحد: + - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **لا توجد مفاتيح محتوى على الإطلاق**؛ `session_id` هو الخيار الوحيد الذي تقرأه، لذا يتم تسجيل المطالبات والإكمالات دائمًا. + - CrewAI — **لا مفتاح محتوى على الإطلاق**؛ `session_id` هو الخيار الوحيد الذي يقرأه، لذا يتم تسجيل الطلبات والإكمالات دائماً. - `instrument()` يسقط الخيارات التي لا يقرأها محول، لذا تمرير الاسم الخاطئ لا يرفع شيئًا ولا يغير شيئًا. - - لا تسلم السر `input=` في المقام الأول. + `instrument()` يسقط الخيارات التي لا يقرأها محول، لذا تمرير الاسم الخاطئ لا يرفع شيء ولا يغير شيء. + - لا تسلم السر إلى `input=` في المقام الأول. - `collector.redact` دفاع متعمق، وليس بديلاً لأي منهما. + `collector.redact` ليس بديلاً عن أي منهما. - **ديريتوري بكرة فارغ هو الحالة الصحية.** لا تستخدمه للتحقق من التسليم. + **دليل ملف فارغ هو الحالة الصحية.** لا تستخدمه للتحقق من التسليم. -يحذف الشيطان كل دفعة في ميلي ثانية من شحنها، لذا `ls` يتسابق مع جامع البيانات ويُظهر جزءًا من ما أصدرته — لا يمكن تمييزه عن SDK لم يسجل شيئًا. +يحذف المراقب كل دفعة في غضون ميلي ثانية من نقلها، لذا فإن `ls` يتسابق المجمع ويظهر جزء من ما أصدرته — لا يمكن تمييزه عن SDK لم يسجل شيء. -لتأكيد وصول الأحداث بالفعل، تحقق من لوحة المعلومات. لمراقبة ملء البكرة، توقف الشيطان أولاً. +للتأكد من أن الأحداث هبطت فعلاً، تحقق من لوحة التحكم. لمراقبة امتلاء الملف، توقف المراقب أولاً. - + -كل استدعاء يعمل داخل غلاف وظيفته الوحيدة إعادة الرفع، لذا استدعاؤك يجلس في `try` واحد تمامًا وكل ما يفعله SDK يحدث خارجه. +كل رد اتصال يعمل داخل غلاف وظيفته الوحيدة هي إعادة الرفع، لذا استدعاؤك يجلس في `try` واحدة بالضبط وكل شيء SDK يحدث خارجها. | ما يحدث | النتيجة | | --- | --- | -| خطاف يرفع | مسجل مرة واحدة مع التتبع الخاص به. استدعاؤك لم يتأثر | -| نفس الخطاف يرفع ثلاث مرات | يتم تعطيل هذا الخطاف الواحد لبقية العملية، بسطر خطأ واحد | -| `FAILPROOFAI_SDK_STRICT=1` تم تعيينه | يتم إعادة رفع الاستثناء بدلاً من ذلك | +| خطاف يرفع | مسجل مرة واحدة مع traceback الخاص به. استدعاؤك غير متأثر | +| نفس الخطاف يرفع ثلاث مرات | يتم تعطيل ذاك الخطاف للعملية المتبقية، مع سطر خطأ واحد | +| `FAILPROOFAI_SDK_STRICT=1` معين | يتم إعادة رفع الاستثناء بدلاً من ذلك | | إصدار إطار عمل خارج النطاق المختبر | يحذر مرة واحدة، يدرج على أي حال | -| قدرة واحدة مفقودة | يتم تعطيل هذا الخطاف الواحد، ليس المحول كله | +| قدرة واحدة مفقودة | يتم تعطيل ذاك الخطاف فقط، لا أبداً محول كامل | -الافتراضي صحيح في الإنتاج وخاطئ أثناء التصحيح، لأنه يمكن فقط إثبات أنه لم ينهار. اضبط `FAILPROOFAI_SDK_STRICT=1` لجعل الفشل المبلل عالي الصوت. +الافتراضي صحيح في الإنتاج وخاطئ أثناء التصحيح، لأنه لا يمكن أبداً إثبات أنه لم يتعطل. اضبط `FAILPROOFAI_SDK_STRICT=1` لإسكات الفشل المبتلع. @@ -700,24 +701,24 @@ flowchart LR ## مشاكل شائعة - - حدث افتتاح بدون إغلاق: `model_request` بدون `model_response`، أو `tool_use` بدون `tool_result`. استخدم النطاقات، التي تضمن الزوج حتى عندما يرفع الجسم. إذا استدعيت طرق الحدث مباشرة، استخدم `try` و `finally`. + + حدث افتتاحي بدون حدث إغلاق: `model_request` بدون `model_response`، أو `tool_use` بدون `tool_result`. استخدم النطاقات، التي تضمن الزوج حتى عندما يرفع الجسم. إذا استدعيت طرق الحدث مباشرة، استخدم `try` و `finally`. - يتم قياسه من حدث الفتح المطابق، لذا يتم رفضه على `tool_result`, `hook_completed`, `agent_resume`, و `human_input`. يتم قبوله على `model_response`، لأن فقط أنت تعرف كمون المزود الحقيقي، ويجب أن يكون عددًا صحيحًا. + يتم قياسه من حدث الافتتاح المطابق، لذا يتم رفضه على `tool_result` و `hook_completed` و `agent_resume` و `human_input`. يتم قبوله على `model_response`، لأن فقط أنت تعرف زمن المزود الحقيقي، ويجب أن يكون عدداً صحيحاً. - - الخيط لم يرث السياق أبدًا. لف الاستدعاء في `failproofai_sdk.propagate()`. انظر [الخيوط والعمليات غير المتزامنة](#threads-and-async). + + الخيط لم يرث السياق أبداً. غلف الدالة في `failproofai_sdk.propagate()`. انظر [الخيوط و async](#threads-and-async). - - الحقول الإضافية تدمج أخيرًا، لذا الحقل المسمى مثل حقل حقيقي مثل `model` أو `outcome` كان سيستبدله ويغير عمودًا مخزنًا. مساحة الأسماء لك؛ المحولات تستخدم بادئة `fw_`. + + الحقول الإضافية تدمج آخراً، لذا أحد باسم مثل حقل حقيقي مثل `model` أو `outcome` سيكتب فوقه ويغير عمود مخزن. مساحة أسماء لك؛ المحولات تستخدم بادئة `fw_`. - - `agent_id` هو جانب منخفض الأساسية وأدخلت معرف التشغيل. استخدم اسم دور أو عقدة وضع المعرف الحقيقي في حقل حمولة. + + `agent_id` هو جانب cardinality منخفض وأنت وضعت معرف تشغيل فيه. استخدم دوراً أو اسم عقدة وضع المعرف الحقيقي في حقل الحمولة. @@ -727,10 +728,10 @@ flowchart LR الأزواج والمعرفات ودورة حياة الجلسة والتسليم. - - اتبع السببية عبر الجلسة التي استعرتها للتو. + + اتبع السببية عبر الجلسة التي التقطتها للتو. - LangGraph، CrewAI، LlamaIndex، و Pydantic AI. + LangGraph و CrewAI و LlamaIndex و Pydantic AI. \ No newline at end of file diff --git a/docs/ar/start/quickstart.mdx b/docs/ar/start/quickstart.mdx index 1daebeea..bdd1425f 100644 --- a/docs/ar/start/quickstart.mdx +++ b/docs/ar/start/quickstart.mdx @@ -1,12 +1,12 @@ --- title: "البدء السريع" -description: "التقط جلسة وكيل، ابحث عن عطل، وابدأ في منعه." +description: "التقط جلسة وكيل، وابحث عن عطل، وابدأ في منعه." icon: "zap" --- -يساعدك هذا البدء السريع في إعداد جهاز واحد للإبلاغ عن الجلسات، وتشغيل تدقيق، ونشر سياسة. استخدم المهارة لإعداد Failproof AI، أو اتبع الخطوات اليدوية. +يساعدك هذا البدء السريع في جعل جهاز واحد يرسل الجلسات، وتشغيل تدقيق، ونشر سياسة. استخدم المهارة لإعداد Failproof AI، أو اتبع الخطوات اليدوية. -**أي مسار هو مسارك؟** إذا كان وكيلك يعمل في أحد [الأطر](/ar/reference/harnesses) الـ 12 المدعومة — وهي واجهة سطر أوامر لترميز الأكواد، أو بوابة مثل Hermes أو OpenClaw — اتبع الخطوات أدناه؛ تحتاج إلى Node.js 20.9 أو إصدار أحدث. إذا لم يكن لدى وكيلك إطار عمل، فقم بتجهيزه باستخدام [Python SDK](/ar/reference/custom-agents) للتتبع والتدقيق، ثم عد إلى [تشغيل أول فحص فشل](/ar/start/first-audit)؛ الإنفاذ على هذا المسار يتطلب hook في وقت التشغيل. +**أي مسار هو مسارك؟** إذا كان وكيلك يعمل في أحد [الأنظمة](/ar/reference/harnesses) المدعومة الـ 12 — واجهة سطر أوامر للترميز، أو بوابة مثل Hermes أو OpenClaw — اتبع الخطوات أدناه؛ تحتاج إلى Node.js 20.9 أو أحدث. إذا لم يكن لدى وكيلك نظام، فقم بتجهيزه باستخدام [Python SDK](/ar/reference/custom-agents) للتتبع والتدقيق، ثم عاود الانضمام في [تشغيل أول فحص فشل](/ar/start/first-audit)؛ الإنفاذ على هذا المسار يتطلب خطاف في وقت التشغيل. @@ -21,19 +21,19 @@ icon: "zap" Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - يفحص وكيلك المشروع، ويختار التكامل ذي الصلة، وينفذ الإعداد، ويتحقق منه. راجع [مستودع مهارات FailproofAI](https://github.com/FailproofAI/skills) للاطلاع على المهارات الفردية وخيارات التثبيت المتقدمة. + يفحص وكيلك المشروع، ويختار التكامل ذي الصلة، ويجري الإعداد، ويتحقق منه. انظر [مستودع مهارات FailproofAI](https://github.com/FailproofAI/skills) للاطلاع على المهارات الفردية وخيارات التثبيت المتقدمة. - ## قبل أن تبدأ + ## قبل البدء -1. افتح [لوحة معلومات Failproof AI](https://app.befailproof.ai) وأنشئ حسابًا أو سجل الدخول باستخدام بريدك الإلكتروني للعمل. -2. انتقل إلى **Administration → Keys** وأنشئ مفتاحًا باستخدام `events:add` و `policies:pull`. -3. انسخ السر لمرة واحدة وخزنه على الجهاز المستهدف: +1. افتح [لوحة تحكم Failproof AI](https://app.befailproof.ai) وأنشئ حسابًا أو سجل دخولك باستخدام بريدك الإلكتروني للعمل. +2. انتقل إلى **Administration → Keys** وأنشئ مفتاحًا بصلاحيات `events:add` و `policies:pull`. +3. انسخ السر لمرة واحدة، ثم اقرأه في shell على الجهاز الهدف. `read -s` يأخذه في موجه لا يتم طباعته، لذا لا يظهر أبدًا في أمر: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## التثبيت @@ -42,12 +42,18 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - يتم إرسال نسخ الجلسات بشكل افتراضي. أضف `--no-transcripts` للإبلاغ عن نشاط hook وقرارات السياسة دون محتوى النسخة. + هذا الأمر الواحد هو كل الإعداد: يثبت daemon المحلي (root مرة واحدة)، ويربط الخطافات في كل agent CLI يجده، ويربط هذا الجهاز بـ Cloud. تمرير المفتاح عبر البيئة بدلاً من `--token` يبقيه خارج `ps`، حيث يمكن لكل مستخدم على الجهاز قراءة معاملات الأمر. لكنه لا يبقيه خارج سجل shell — قراءته باستخدام `read -s` هو ما يفعل ذلك. في CI، أدخله كسر مخفي وأبقِ تتبع shell (`set -x`) معطلاً، وإلا فإن التتبع سيطبعه. - إذا كان لدى هذا الجهاز بالفعل سجل وكيل، فقم بمعاينة واستيراد آخر سبعة أيام، ثم انتظر انتهاء التسليم. تخطَّ هذه الخطوة على جهاز جديد. + يتم إرسال نصوص الجلسات افتراضيًا. أضف `--no-transcripts` للإبلاغ عن نشاط الخطاف وقرارات السياسة بدون محتوى النسخة. + + + لا تلجأ إلى `failproofai config --connect ` هنا. هذا العلم ينضم إلى جهاز **بالفعل** معد ويعود مباشرة — بدون daemon أو خطافات — لذا قد يظهر الجهاز في Cloud بينما لا يجمع ولا ينفذ أي شيء. + + + إذا كان لدى هذا الجهاز سجل وكيل بالفعل، معاينة واستيراد آخر سبعة أيام، ثم انتظر انتهاء التسليم. تخطّ هذه الخطوة على جهاز جديد. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +61,41 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - افتح **Sessions** في Failproof AI واختر جلسة مستوردة. + افتح **Sessions** في Failproof AI وحدد جلسة مستوردة. - - يرفع هذا Failproof AI إلى إطار العمل الخاص بك ويثبت 39 سياسة مدمجة. استخدمها لرؤية قرارات السياسة المحلية وتجربة الإنفاذ قبل أن يدقق Failproof AI جلساتك ويكتب سياسات لوكلائك. - - دع المثبت يكتشف إطار العمل الخاص بك، أو حدد واحدًا بوضوح. كل واحد من الـ 12 هو قيمة `--cli` صالحة — `claude`، `codex`، `copilot`، `cursor`، `opencode`، `pi`، `hermes`، `openclaw`، `factory`، `devin`، `antigravity`، `goose`. + + الخطوة السابقة قد ربطت بالفعل كل agent CLI تم اكتشافه. أعد تشغيلها لنظام واحد بشكل واضح عند الحاجة، أو لإضافة نظام تم تثبيته لاحقًا. كل واحد من الـ 12 هو قيمة `--cli` صحيحة — `claude`، `codex`، `copilot`، `cursor`، `opencode`، `pi`، `hermes`، `openclaw`، `factory`، `devin`، `antigravity`، `goose`. ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - يتم التحقق من حظر استدعاء أداة قبل تشغيلها على جميع الـ 12. يتم التحقق من بوابات نهاية الدور على 8 — راجع [قدرة الإنفاذ](/ar/reference/harnesses#enforcement-capability) للحصول على مصفوفة لكل إطار عمل. + يتم التحقق من حظر استدعاء الأداة قبل تشغيلها على الـ 12 جميعًا. يتم التحقق من بوابات نهاية الدوران على 8 — انظر [قدرة الإنفاذ](/ar/reference/harnesses#enforcement-capability) لمصفوفة كل نظام. + + + ربط الخطافات لا يفعل أي سياسة. الإعداد يختار عن قصد لا شيء — هذا قرارك — لذا خذ حزمة: + + ```bash + failproofai policies add FailproofAI/policies + ``` + + يتم جلب الحزمة من إصدار GitHub الخاص بها، التحقق من المجموع الاختباري، وتثبيتها إلى العلامة المحددة التي تم حلها. تحمل 38 سياسة وتشغل 10 منها التي يشير بيانها الوصفية إلى أنها آمنة للتفعيل بدون إشراف. استخدمها لرؤية قرارات السياسة المحلية وتجربة الإنفاذ قبل أن يدقق Failproof AI جلساتك وكتابة السياسات للوكلاء. + + اقرأ أي حزمة قبل أخذها باستخدام `failproofai policies show /`، وانظر [حزم السياسات](/ar/policies/packs) لأخذ جزء فقط من واحدة. + + حتى يتم تشغيل هذا، الشيء الوحيد الذي ينفذ هو `block-failproofai-commands` — الحارس الذي يعمل دائمًا والذي يوقف وكيل من إيقاف Failproof AI. `failproofai policies` يسرد ما هو مشغل. - - اتبع [تشغيل أول فحص فشل](/ar/start/first-audit). استخدم هدفًا محددًا مثل "البحث عن جلسات أعاد فيها الوكيل محاولة استدعاء أداة فاشل دون تغيير نهجه". + + اتبع [تشغيل أول فحص فشل](/ar/start/first-audit). استخدم هدفًا محددًا مثل بحث الجلسات حيث أعاد الوكيل محاولة أداة فاشلة دون تغيير نهجه. - اتبع [منع أول فشل باستخدام سياسة](/ar/start/first-policy). ابدأ بوضع المراقبة، وافحص المطابقات، ثم فعّل النسخة المراجعة. + اتبع [منع أول فشل بسياسة](/ar/start/first-policy). ابدأ في وضع المراقبة، افحص المطابقات، ثم نفذ النسخة المراجعة. - شغّل `failproofai config --status`. يبلغ الإعداد الصحي عن اتصال السحابة، وحالة daemon، وما إذا كان الإنفاذ موقوفًا. + قم بتشغيل `failproofai config --status`. يُبلّغ الإعداد الصحي عن اتصال السحابة وحالة daemon وما إذا كان الإنفاذ موقوفًا. \ No newline at end of file diff --git a/docs/ar/start/setup.mdx b/docs/ar/start/setup.mdx index 3ba31a76..6e79eb8f 100644 --- a/docs/ar/start/setup.mdx +++ b/docs/ar/start/setup.mdx @@ -1,68 +1,89 @@ --- title: "اختر إعدادك" -description: "اختر بين الفرض المحلي أو Failproof AI Cloud أو نشر موجه للمؤسسات." +description: "اختر الفرض المحلي أو Failproof AI Cloud أو نشر المؤسسات." icon: "waypoints" --- - ثبّت الـ hooks والسياسات على جهاز. استخدم هذا عندما تحتاج إلى حماية فورية دون إرسال بيانات الجلسة إلى Cloud. + قم بإعداد جهاز بدون مفتاح Cloud واختر حزمة سياسة. استخدم هذا عندما تحتاج إلى حماية فورية دون إرسال بيانات الجلسة إلى Cloud. - أضف جلسات مركزية وعمليات تدقيق وتقييمات عبر الإنترنت ولوحات معلومات ونبهات ونشر سياسة للأسطول. + أضف الجلسات المركزية والتدقيقات والتقييمات عبر الإنترنت والحسابات الشخصية والتنبيهات ونشر سياسات الأسطول. - - استخدم عناصر التحكم في المؤسسة والمفاتيح ذات النطاق والبنية الأساسية الخاصة ومتطلبات الأمان الخاصة بالنشر. + + استخدم عناصر التحكم التنظيمية والمفاتيح المحدودة النطاق والبنية الأساسية الخاصة ومتطلبات الأمان الخاصة بالنشر. +## الفرض المحلي + +شغّل `failproofai config` بدون مفتاح، ثم خذ حزمة باستخدام `failproofai policies add FailproofAI/policies`. في الطرفية، اختر **Not now — stay local** عندما يطلب الإعداد الاتصال بـ Cloud؛ بدون طرفية وبدون `FAILPROOFAI_CLOUD_TOKEN`، يبقى محليًا من تلقاء نفسه. يفرض الخيط الخلفي والخطافات على الجهاز، ولا يتم إرسال بيانات الجلسة إلى Cloud. للاتصال لاحقًا، اتبع الخطوات أدناه. + ## مسار الإنتاج الموصى به -1. قم بتوصيل جهاز غير موجه للإنتاج مع تفعيل التقاط النصوص. +1. قم بتوصيل جهاز غير إنتاجي مع تمكين التقاط النصوص. 2. تحقق من الجلسات والتقييمات في Cloud. -3. أنشئ عملية تدقيق لحالة فشل معروفة. -4. نشّر السياسة الأولى في وضع المراقبة. +3. أنشئ تدقيقًا لحالة فشل معروفة. +4. انشر السياسة الأولى في وضع المراقبة. 5. قم بالتوسع إلى الإنتاج بعد مراجعة المطابقات والإيجابيات الكاذبة. ## توصيل جهاز بـ Cloud - - 1. انتقل إلى **الإدارة → المفاتيح** وأنشئ مفتاحًا يتمتع بصلاحيات `events:add` و `policies:pull`. - 2. انسخ السر لمرة واحدة إلى الجهاز المستهدف. - 3. بعد تشغيل أمر اتصال CLI، انتقل إلى **الإدارة → الفرض** وتأكد من ظهور الجهاز. - 4. انتقل إلى **المراقبة → الأحداث** وتأكد من وصول حدثه الأول. + + 1. انتقل إلى **Administration → Keys** وأنشئ مفتاحًا باستخدام `events:add` و `policies:pull`. + 2. انسخ السر لمرة واحدة إلى الجهاز الهدف. + 3. بعد تشغيل أمر اتصال CLI، انتقل إلى **Admin → enforcement** وأكد ظهور الجهاز. + 4. انتقل إلى **Observe → Events** وأكد وصول حدثه الأول. - درج المفتاح يعرض الصلاحيتين المطلوبتين بواسطة جهاز موصول: استقبال الأحداث وتسليم السياسة. + يعرض درج المفتاح المنحتين اللذين يحتاجهما جهاز متصل: استيعاب الأحداث وتوصيل السياسة. - ![درج مفتاح API الجديد المستخدم لمنح صلاحيات استقبال الأحداث وتسليم السياسة.](/images/dashboard/key-create.png) + ![درج مفتاح API الجديد المستخدم لمنح أذونات استيعاب الأحداث وتوصيل السياسة.](/images/dashboard/key-create.png) - بعد الاتصال، يجب أن يظهر الجهاز في الفرض مع حالة السياسة المطلوبة والمبلغ عنها. + بعد الاتصال، يجب أن يظهر الجهاز في الفرض مع حالة السياسة المرغوبة وحالة النشر. - ![أسطول الفرض مع جهاز مسجل موسع لعرض حالة السياسة المطلوبة وحالة النشر.](/images/dashboard/enforcement-fleet.png) + ![أسطول الفرض مع جهاز مسجل موسع لإظهار حالة السياسة المرغوبة وحالة النشر.](/images/dashboard/enforcement-fleet.png) - يؤكد الحدث الأول الوارد أن الخادم يمكنه توصيل البيانات إلى Cloud، بشكل مستقل عن نشر السياسة. + يؤكد الحدث الأول الذي يصل على أن الخيط الخلفي يمكنه تسليم البيانات إلى Cloud، بشكل مستقل عن نشر السياسة. ![دفق الأحداث المباشر يعرض أحداث الوكيل والنموذج والأداة الأخيرة.](/images/dashboard/events-stream-current.png) - استمر فقط بعد رؤية الجهاز وحدثه الأول. + تابع فقط بعد أن يكون الجهاز وحدثه الأول مرئيين. + اقرأ السر لمرة واحدة في الشل. `read -s` يأخذه في موجه لا يتم صداه، لذلك لا يظهر أبدًا في أمر أو في سجل الشل: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + ثم قم بإعداد الجهاز واختر سياساته وسمّه: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` + `failproofai config` يقوم بالإعداد بالكامل — الخيط الخلفي والخطافات لكل CLI وكيل يجده والاتصال بـ Cloud — ثم لا يختار أي سياسات، وهو ما الأمر الثاني موجود له. + + يأتي التسمية **بعد** الاتصال وليس أثناء: `failproofai config --machine-label ` يعيد تسمية جهاز متصل بالفعل، وعلى جهاز غير متصل فإنه لا يفعل شيئًا سوى قول ذلك. + أضف `--no-transcripts` عندما يجب أن تبقى محتويات النصوص محلية. + + في CI، قم بتعيين `FAILPROOFAI_CLOUD_TOKEN` من مخزن الأسرار بدلاً من `read -s`، واحتفظ بتتبع الشل (`set -x`) إيقاف، أو التتبع يطبع المفتاح. + + + على جهاز **بالفعل** تم إعداده، `failproofai config --connect ` يسجله وشيء آخر فقط. لا تستخدم هذا النموذج للتثبيت الأول: يعود قبل وجود الخيط الخلفي أو أي خطاف، تاركًا جهازًا يظهر في Cloud لكن لا يجمع أو يفرض شيئًا. + -يتحقق الاتصال بـ Cloud من استقبال الأحداث وتسليم السياسة بشكل مستقل. قد يكون المفتاح صالحًا لذلك لكنه ينقصه إحدى الصلاحيات المطلوبة. استخدم `failproofai config --status` لمعرفة الإمكانية المكونة. +يتحقق الاتصال بـ Cloud من استيعاب الأحداث وتوصيل السياسة بشكل مستقل. قد يكون المفتاح صحيحًا إذن لكن ينقصه إذن واحد مطلوب. استخدم `failproofai config --status` لمعرفة القدرة المكونة. - كتابة إعداد Cloud للبيانات الاعتماد المحلية فقط بعد نجاح الإمكانية ذات الصلة. لا تترك عملية التحقق الفاشلة جهازًا يبدو موصولًا عندما لا يكون كذلك. + يكتب إعداد Cloud بيانات اعتماد محلية فقط بعد نجاح القدرة ذات الصلة. التحقق الفاشل لا يترك جهازًا يبدو متصلاً عندما لا يكون كذلك. \ No newline at end of file diff --git a/docs/de/admin/keys-and-permissions.mdx b/docs/de/admin/keys-and-permissions.mdx index 638bc6ac..99ed8d81 100644 --- a/docs/de/admin/keys-and-permissions.mdx +++ b/docs/de/admin/keys-and-permissions.mdx @@ -4,26 +4,26 @@ description: "Erstellen Sie bereichsbegrenzte API-Schlüssel für Maschinen, Aut icon: "key-round" --- -API-Schlüssel gehören zu einer Organisation und tragen explizite Berechtigungen. Verwenden Sie separate Schlüssel für Agent-Ingestion, Policy-Auslieferung, Evaluatoren, CI-Automatisierung und administrative Skripte. +API-Schlüssel gehören einer Organisation und tragen explizite Berechtigungen. Verwenden Sie separate Schlüssel für Agent-Ingestion, Policy-Auslieferung, Evaluatoren, CI-Automatisierung und administrative Skripte. ## Schlüssel erstellen und rotieren - 1. Gehen Sie zu **Administration → Keys**, wählen Sie **Neuer Schlüssel** und geben Sie einen Workload-Namen ein. + 1. Gehen Sie zu **Administration → Keys**, wählen Sie **new key** und geben Sie einen Workload-Namen ein. 2. Wählen Sie ein Berechtigungs-Preset und passen Sie einzelne Berechtigungen nur dann an, wenn das Preset nicht ausreicht. - 3. Erstellen Sie den Schlüssel und kopieren Sie das einmalige Secret sofort. + 3. Erstellen Sie den Schlüssel und kopieren Sie sein einmalig angezeigtes Secret sofort. 4. Öffnen Sie den Schlüssel später, um Berechtigungen zu aktualisieren, ihn zu deaktivieren oder das Secret neu zu generieren. - Im Erstellungs-Drawer wählen Sie die minimal erforderlichen Berechtigungen für den Workload aus. + Im Erstellungs-Drawer wählen Sie die minimal erforderlichen Berechtigungen für den jeweiligen Workload. ![Der Drawer zum Erstellen eines neuen API-Schlüssels mit Berechtigungs-Presets und individuellen Grants.](/images/dashboard/key-create.png) Nach der Erstellung zeigt die Keys-Seite die dauerhaften Metadaten und Verwaltungsaktionen. Das einmalige Secret wird nicht erneut angezeigt. - ![Die API-Keys-Seite mit Schlüsselberechtigungen, Erstellungszeit sowie Aktionen zum Neu-Generieren und Deaktivieren.](/images/dashboard/api-keys.png) + ![Die API-Keys-Seite mit Schlüsselberechtigungen, Erstellungszeitpunkt sowie Aktionen zum Regenerieren und Deaktivieren.](/images/dashboard/api-keys.png) - Nutzen Sie diese Liste, um Berechtigungen regelmäßig zu überprüfen und Schlüssel zu deaktivieren, die keinem aktiven Workload mehr zugeordnet sind. + Nutzen Sie diese Liste, um Berechtigungen regelmäßig zu prüfen und Schlüssel zu deaktivieren, die keinem aktiven Workload mehr zugeordnet sind. ```bash @@ -36,25 +36,25 @@ API-Schlüssel gehören zu einer Organisation und tragen explizite Berechtigunge fp keys disable production-agents ``` - Leiten Sie die Ausgabe von create/regenerate sicher um oder erfassen Sie diese; das Secret wird nur einmal zurückgegeben. + Leiten Sie die Ausgabe von create/regenerate sicher um oder erfassen Sie sie; das Secret wird nur einmal zurückgegeben. -Die zwei Berechtigungen, die eine verbundene Failproof AI-Maschine benötigt, sind unabhängig voneinander: +Die beiden Berechtigungen, die eine verbundene Failproof AI-Maschine benötigt, sind unabhängig voneinander: - `events:add` sendet Events und Session-Daten. - `policies:pull` ruft zugewiesene Policy-Deployments ab. -Schlüssel-Secrets werden bei der Erstellung oder Neu-Generierung angezeigt. Speichern Sie sie in einem Secret-Manager und rotieren Sie sie, ohne die interaktiven Zugangsdaten eines Operators wiederzuverwenden. +Schlüssel-Secrets werden bei der Erstellung oder Regenerierung angezeigt. Speichern Sie sie in einem Secret-Manager und rotieren Sie sie, ohne dabei die interaktiven Anmeldedaten eines Operators wiederzuverwenden. ## Berechtigungskatalog | Bereich | Berechtigungen | | --- | --- | | Events | `events:add`, `events:read` | -| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` ist nur für menschliche Sitzungen | +| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` ist nur für menschliche Sitzungen verfügbar | | Users | `users:create`, `users:read`, `users:update`, `users:delete` | -| Evaluations | `evaluations:read`, `evaluations:trigger` | +| Evaluations | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | | Dashboards | `dashboards:read`, `dashboards:write`, `dashboards:delete` | | Queries | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | | Assistant | `agent:use` | @@ -65,10 +65,10 @@ Schlüssel-Secrets werden bei der Erstellung oder Neu-Generierung angezeigt. Spe | Policies | `policies:read`, `policies:write`, `policies:pull` | | Usage | `usage:read` | -`orgs:admin` ist dem Instanz-Operator vorbehalten und kann keinem Organisations-Schlüssel oder gewöhnlichen Mitglied gewährt werden. Veraltete `incidents:*`- und `alerts:ack`-Tokens werden aus Kompatibilitätsgründen akzeptiert und auf aktuelle `issues:*`-Berechtigungen normalisiert. +`orgs:admin` ist dem Instanz-Operator vorbehalten und kann weder einem Organisations-Schlüssel noch einem gewöhnlichen Mitglied gewährt werden. Veraltete `incidents:*`- und `alerts:ack`-Token werden aus Kompatibilitätsgründen akzeptiert und auf die aktuellen `issues:*`-Berechtigungen normalisiert. -Die eingebauten Berechtigungs-Presets sind `read-only`, `standard` und `admin`. `standard` ergänzt die Leseberechtigungen um das Auslösen von Evaluierungen, die Ausführung von Abfragen, die Bearbeitung von Issues und die Nutzung des Assistenten. Bei der Schlüsselerstellung werden menschliche Berechtigungen entfernt, auch wenn ein Berechtigungs-Preset diese enthält. +Die integrierten Berechtigungs-Presets sind `read-only`, `standard` und `admin`. `standard` ergänzt die Leseberechtigungen um das Auslösen von Evaluierungen, die Ausführung von Queries, die Bearbeitung von Issues und die Nutzung des Assistenten. Bei der Schlüsselerstellung werden rein menschliche Berechtigungen entfernt, auch wenn ein Preset diese enthält. - Instanz-bezogene Schlüssel können eine Organisation über den Header `X-AgentEye-Org` auswählen. Setzen Sie diesen bei Multi-Organisations-Deployments explizit; wird er weggelassen, kann die Standardorganisation ausgewählt werden. + Instanz-bezogene Schlüssel können eine Organisation über den `X-AgentEye-Org`-Header auswählen. Setzen Sie diesen bei Multi-Organisations-Deployments explizit; wird er weggelassen, wird möglicherweise die Standardorganisation ausgewählt. \ No newline at end of file diff --git a/docs/de/evaluations/deploy.mdx b/docs/de/evaluations/deploy.mdx new file mode 100644 index 00000000..ee291fc0 --- /dev/null +++ b/docs/de/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "Eine Evaluation deployen und versionieren" +description: "Eine unveränderliche Version deployen, den aktiven Stand einsehen, neue Versionen veröffentlichen, zurückrollen und bereits vorhandene Sessions bewerten." +icon: "cloud-upload" +--- + +## Deployment + +Wähle unten auf der Authoring-Seite **deploy `@`** aus. Die Version ist nach der Veröffentlichung unveränderlich: Ab diesem Zeitpunkt wird jede abgeschlossene Session, auf die die Bedingung zutrifft, damit bewertet. + +## Den aktiven Stand einsehen + +**Analyze → eval authoring** listet die gehosteten Definitionen deiner Organisation – also die Evaluationen, die der verwaltete Evaluator dafür ausführt. Jede Zeile zeigt: + +- Name, Key, Version und Ergebnistyp +- die Quell-Prüfsumme, anhand derer sich deployte Revisionen unterscheiden lassen, ohne den Code öffnen zu müssen +- ob die Evaluation **konditionell** ist oder für **alle abgeschlossenen Sessions** läuft – die Bedingung schränkt eine Evaluation auf bestimmte Agents oder Umgebungen ein +- Timeout, Labels und den Zeitpunkt der letzten Änderung + +![Die Liste gehosteter Definitionen: Name, Key, Version, Ergebnistyp, Prüfsumme, Timeout und Geltungsbereich jeder Evaluation, mit Optionen für neue Version sowie Aktivieren oder Deaktivieren.](/images/dashboard/eval-definitions.png) + +Du kannst die Liste durchsuchen oder nach Status filtern. Evaluationen, die dein eigener Worker registriert, werden hier nicht aufgeführt; ihre Ergebnisse tragen auf der [Evaluations-Seite](/de/sessions/evaluations) das Tag **customer**, gehostete dagegen **managed**. + +Eine Organisation kann gleichzeitig bis zu 100 verschiedene gehostete Evaluationen aktiviert haben. + +## Eine neue Version veröffentlichen + +Wähle in einer Zeile **new version** aus. Die Authoring-Seite öffnet sich mit dem Code dieser Version; ändere ihn, teste ihn und deploye ihn. Key und Ergebnistyp werden übernommen und können nicht geändert werden. + +Die Veröffentlichung einer Nachfolgeversion deaktiviert die Vorgängerversion, die jedoch in der Liste verbleibt. Ergebnisse behalten die Version, die sie erzeugt hat – ein Diagramm zeigt also genau, wann die neue Logik übernommen hat. + +## Zurückrollen + +Wähle bei der aktuellen Version **disable** und bei der gewünschten Version **enable** aus. Es wird nichts gelöscht, und alle Ergebnisse bleiben unverändert erhalten. + +## Eine Evaluation stoppen + +Wähle **disable** aus. Ohne aktivierte Version läuft die Evaluation für neue Sessions nicht mehr. Um eine Evaluation zu stoppen, die dein eigener Worker ausführt, registriere sie nicht mehr: Entferne sie aus dem Worker oder stoppe den Worker. + +## Bereits vorhandene Sessions bewerten + +Evaluationen laufen vorwärts: Eine jetzt deployte Version bewertet niemals eine Session, die davor geendet hat. Um historische Daten zu bewerten, öffne auf der Eval-Authoring-Seite **score sessions you already have**, wähle ein Zeitfenster von bis zu 90 Tagen und optional eine einzelne Evaluation aus, und zähle vor dem Ausführen nach. Die Anzahl entspricht genau dem, was ausgeführt wird – jedes Session-Evaluations-Paar darin ist eine abrechenbare Evaluation. + +Dabei werden nur Lücken gefüllt. Eine Session, für die bereits ein Ergebnis dieser Evaluation vorliegt, behält es, und das zweifache Ausführen desselben Zeitfensters bewertet nichts Neues. + +Um eine Session erneut zu bewerten – nach einer Korrektur oder für eine Session, die nicht sauber beendet wurde – wähle auf der Session-Seite **re-evaluate** aus. Das neue Ergebnis wird der Verlaufshistorie der Session hinzugefügt; frühere Ergebnisse bleiben erhalten. + +## Berechtigungen + +| Berechtigung | Ermöglicht | +| --- | --- | +| `evaluations:read` | Ergebnisse einsehen und die Eval-Authoring-Seite öffnen | +| `evaluations:trigger` | Gehostete Definitionen einsehen, deployen, versionieren, aktivieren und deaktivieren; testen; Verlauf bewerten; eine Session neu bewerten | +| `events:read` | Gegen echte Sessions testen und Entwürfe auf Payload-Keys stützen, zusätzlich zu `evaluations:trigger` | +| `evaluations:run` | Einen eigenen Evaluator-Worker betreiben | \ No newline at end of file diff --git a/docs/de/evaluations/overview.mdx b/docs/de/evaluations/overview.mdx new file mode 100644 index 00000000..6afd23c4 --- /dev/null +++ b/docs/de/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "Agenten evaluieren" +description: "Bewerte jede abgeschlossene Sitzung mit selbst definierten Evaluierungen: gehostete Python-Prüfungen oder LLM-Richter in deinem eigenen Worker." +icon: "gauge" +--- + +Eine Evaluierung bewertet eine abgeschlossene Agenten-Sitzung. Wenn eine Sitzung endet, wird jede aktivierte Evaluierung, die auf sie zutrifft, ausgeführt und zeichnet die Ergebnisse auf – mit einer Begründung, die du direkt neben dem Trace lesen kannst: + +- ein **Score** von 0 bis 1, optional als bestanden oder nicht bestanden markiert +- eine **Metrik**, z. B. eine Anzahl, eine Dauer oder Kosten, mit ihrer Einheit +- eine **Assertion**, die bestanden hat oder nicht + +## Zwei Arten von Evaluatoren + +| | Gehostetes Python | Eigener Worker | +| --- | --- | --- | +| Geschrieben | Im Dashboard unter **Analyze → eval authoring** | In Python, mit dem [Evaluator SDK](/de/reference/evaluator-sdk) | +| Läuft | Auf dem verwalteten Evaluator von Failproof AI, in einer Sandbox | Auf deiner eigenen Infrastruktur | +| Am besten für | Deterministische, codebasierte Prüfungen | LLM-Richter, Modellaufrufe, Pakete, Secrets, Netzwerkzugriff, rechenintensive Verarbeitung | + +Gehostetes Python ist bewusst schlank gehalten: ein Ausdruck, keine Imports, kein Netzwerk. Alles, was ein Modell erfordert – etwa ein LLM-Richter, der bewertet, ob eine Antwort relevant war – läuft stattdessen in deinem eigenen Worker. Keine der beiden Varianten benötigt eine eingehende Verbindung: Worker holen abgeschlossene Sitzungen ab und übermitteln Ergebnisse über ausgehendes HTTPS. + +## Jede Organisation evaluiert ihre eigenen Agenten + +Evaluierungen gehören der Organisation, die sie definiert. Jede Organisation auf einer Instanz schreibt ihre eigenen – eigene Prüfungen, Bedingungen, Schwellenwerte und Labels – versioniert und deployt sie, ohne andere Organisationen zu beeinflussen, und sieht nur ihre eigenen Ergebnisse. Diese Ergebnisse lassen sich nach Agent, Umgebung, Evaluierung und Zeitraum filtern oder per Assistent abfragen. + +## Vom ersten Entwurf zu Live-Scores + + + + Beschreibe, was gemessen werden soll, und lass den Assistenten einen Entwurf erstellen – oder schreibe sie selbst. Siehe [Eine Evaluierung schreiben](/de/evaluations/write). + + + Führe sie gegen echte Sitzungen aus, bevor sie live geht; nichts wird gespeichert. Siehe [Eine Evaluierung testen](/de/evaluations/test). + + + Deploye eine unveränderliche Version, veröffentliche neue Versionen bei Weiterentwicklung und kehre bei Bedarf zu einer früheren zurück. Siehe [Deployen und versionieren](/de/evaluations/deploy). + + + Visualisiere Scores über die Zeit, vergleiche Agenten und Umgebungen, und stelle Fragen an den Assistenten. Siehe [Evaluierungsergebnisse lesen](/de/sessions/evaluations). + + + +Evaluierungen wirken vorwärts: Eine jetzt deployete Version bewertet die Sitzungen, die ab sofort abgeschlossen werden. Um bereits vorhandene Sitzungen zu bewerten, [fülle sie nach](/de/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file diff --git a/docs/de/evaluations/test.mdx b/docs/de/evaluations/test.mdx new file mode 100644 index 00000000..a27491e4 --- /dev/null +++ b/docs/de/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "Eine Evaluation testen" +description: "Führen Sie eine Evaluation gegen Ihre echten Sitzungen aus, bevor Sie sie deployen. Es wird nichts gespeichert." +icon: "flask-conical" +--- + +**Diese Evaluation testen** führt auf der Autorenseite den Code gegen Ihre echten Sitzungen auf der Evaluator-Flotte aus, ohne sie zu deployen. Es wird nichts gespeichert: Ein Fehler hier ist lediglich eine Vorschau, und das Deployen ist immer möglich. + + + + Wählen Sie **check**, um den Code und die Bedingung gegen die Regeln der Sandbox zu kompilieren, ohne sie auf einer Sitzung auszuführen. + + + Grenzen Sie die übereinstimmenden Sitzungen nach Agent, Umgebung, Zeitraum oder Sitzungs-ID ein und wählen Sie bis zu 10 aus. Nehmen Sie sowohl Sitzungen auf, bei denen die Evaluation fehlschlagen soll, als auch solche, bei denen sie bestehen soll. + + + Wählen Sie **run against N sessions** und lesen Sie jede Zeile. + + + +| Zeile | Bedeutung | +| --- | --- | +| **ok** | Sie wurde ausgeführt. Die Zeile listet jeden Score, jede Metrik und jede zurückgegebene Assertion sowie die benötigte Zeit auf. | +| **skipped** | Die Bedingung hat `False` zurückgegeben, sodass die Evaluation nicht ausgeführt wurde. Das ist ein Skip, kein Fehler. | +| Failed | Sie hat einen Fehler ausgelöst, ist abgelaufen oder hat etwas verwendet, das die Sandbox ablehnt. Die Zeile gibt an, was passiert ist, und **Fix it** übergibt den Fehler an den Assistenten, wenn dieser helfen kann. | + +![Das Panel „Diese Evaluation testen": Drei Sitzungen, nach Agent ausgewählt – zwei ok und eine übersprungen, weil ihre Bedingung False zurückgegeben hat.](/images/dashboard/eval-test.png) + +Ein Ergebnis verliert seine Aktualität in dem Moment, in dem Sie den Code bearbeiten; es wird abgeblendet statt wiederverwendet. \ No newline at end of file diff --git a/docs/de/evaluations/write.mdx b/docs/de/evaluations/write.mdx new file mode 100644 index 00000000..8d49af3a --- /dev/null +++ b/docs/de/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "Eine Evaluierung schreiben" +description: "Beschreibe, was gemessen werden soll, und lass den Assistenten eine gehostete Python-Evaluierung entwerfen, oder schreibe den Code selbst. LLM-Richter laufen in deinem eigenen Worker." +icon: "file-pen-line" +--- + +Gehostete Evaluierungen sind kleine, deterministische Python-Programme, die im Dashboard geschrieben und auf der Evaluator-Flotte von Failproof AI ausgeführt werden. Aufwendigere Logik — ein LLM-Richter, ein Paket, ein Secret, ein Netzwerkaufruf — läuft stattdessen [in deinem eigenen Worker](#write-it-in-your-own-worker). + +## Aus einer Beschreibung entwerfen + +1. Gehe zu **Analyze → eval authoring** und wähle **new eval**. +2. Beschreibe auf Englisch, was gemessen werden soll, oder wähle unter **start from an example…** ein Beispiel aus, und klicke auf **draft**. +3. Überprüfe die Felder und den generierten Code, [teste die Evaluierung](/de/evaluations/test) und [stelle sie bereit](/de/evaluations/deploy). + +![Die eval-authoring-Seite mit einer entworfenen Evaluierung: die Beschreibung, die Anmerkungen des Assistenten zum Entwurf sowie die Felder name, key, version, result, timeout, labels und condition.](/images/dashboard/eval-authoring-draft.png) + +Der Entwurf basiert auf den eigenen Events deiner Organisation: Die Seite liest aus, welche Payload-Schlüssel deine Sessions in den letzten sieben Tagen verwendet haben, sodass der Code auf tatsächlich vorhandene Schlüssel zugreift und nicht rät. Bevor der Entwurf übergeben wird, testet der Assistent ihn gegen bis zu fünf deiner neuesten Sessions, behebt nachweisbare Fehler — in bis zu drei Runden — und prüft einmalig, ob der Code das misst, was du angefragt hast. Formuliere die Beschreibung möglichst präzise: Zu allgemeine Prompts sind langsamer und können zu Timeouts führen. Überprüfe den Code in jedem Fall; das Deployment wird dadurch nicht blockiert. + +## Die Felder befüllen + +| Feld | Bedeutung | +| --- | --- | +| name | Anzeigename. Kann später geändert werden | +| key | Der stabile Bezeichner, unter dem die Ergebnisse angezeigt werden, z. B. `code_assistant_quality_gate` | +| version | Eine beliebige Versionszeichenkette ohne Leerzeichen, z. B. `1.0.0` | +| result | **score** (0 bis 1), **metric** (eine Zahl mit Einheit) oder **assertion** (bestanden oder nicht) | +| timeout seconds | Standard: 30. Die Sandbox bricht einzelne Läufe nach 60 Sekunden ab | +| labels | Bis zu 20, kommagetrennt. Können später geändert werden | +| condition | Optional. Ein Python-Ausdruck; die Evaluierung läuft nur für Sessions, bei denen er `True` ergibt | + +Verwende die Bedingung, um eine Evaluierung auf die dafür vorgesehenen Agents und Umgebungen einzuschränken: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +Key, Version, Ergebnistyp, Bedingung und Code sind nach dem Deployment unveränderlich: Um sie zu ändern, muss eine neue Version veröffentlicht werden. Name, Labels und der Aktivierungsstatus bleiben bearbeitbar. + +## Den Code selbst schreiben + +Der **evaluator code** ist ein einzelner Python-Ausdruck, der `EvalResult(...)` zurückgibt, wobei `session` im Scope verfügbar ist. Dieses Beispiel bewertet den Anteil der Tool-Ergebnisse, die mit ok zurückgekehrt sind: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +Ein Ergebnis beginnt mit dem eigenen Key der Evaluierung, im deklarierten Typ: `score=` für eine Score-Evaluierung, oder ein `metrics`- bzw. `assertions`-Eintrag mit dem Namen des Keys für eine Metrik- oder Assertion-Evaluierung. Weitere Metriken und Assertions können mitsenden — bis zu 25 Ergebnisse pro Lauf. + +| Im Scope | Stellt bereit | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count` und `events`, sowie `count(event_type)` und `events_of_type(event_type)` | +| Jedes Event | `id`, `ts`, `event_type` und `payload` | +| Ergebnistypen | `EvalResult`, `Score`, `Metric`, `Assertion` und `ConditionResult` für eine Bedingung | +| Builtins | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +Nichts anderes ist erreichbar: keine Imports und keine Attribute über die Session-Daten sowie einfache String- und Dictionary-Methoden wie `get`, `lower` und `split` hinaus, die aufgerufen werden müssen anstatt nur referenziert zu werden. Payload-Schlüssel sind das, was deine Agents senden — `status` oben ist nur ein Beispiel — lies sie daher von einer echten Session ab. **format** formatiert den Code, **fix** beauftragt den Assistenten, ihn zu reparieren. Der Code kann bis zu 128 KiB groß sein, die Bedingung bis zu 16 KiB. + +![Der evaluator-Code-Editor mit format und fix, der die Assertions einer entworfenen Evaluierung zeigt.](/images/dashboard/eval-authoring-code.png) + +## Im eigenen Worker schreiben + +Wenn eine Evaluierung ein Modell, ein Paket, ein Secret oder das Netzwerk benötigt, schreibe sie mit dem [Evaluator SDK](/de/reference/evaluator-sdk) und führe sie auf deiner eigenen Infrastruktur aus. Sie verwendet dieselben Ergebnistypen, und ihre Ergebnisse erscheinen neben gehosteten Evaluierungen, gekennzeichnet mit **customer**: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/de/policies/deploy.mdx b/docs/de/policies/deploy.mdx index 7093b5ab..42209a55 100644 --- a/docs/de/policies/deploy.mdx +++ b/docs/de/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "Richtlinien deployen" -description: "Eine geprüfte Richtlinienversion auf den vorgesehenen Maschinen ausrollen." +title: "Eine Richtlinie bereitstellen" +description: "Eine getestete Richtlinienversion im Beobachtungsmodus auf Maschinen ausrollen, durchsetzen und bestätigen, dass alle Maschinen sie erhalten haben." icon: "cloud-upload" --- -Ein Deployment verbindet eine oder mehrere Richtlinienversionen mit einer Zielgruppe eingeschriebener Maschinen. +Eine Bereitstellung überträgt veröffentlichte Richtlinienversionen auf eine Maschine, jeweils mit einem von zwei Effekten: -## Deployment anwenden +- **Beobachten** zeichnet auf, was die Richtlinie getan hätte, blockiert jedoch nichts. +- **Durchsetzen** handelt gemäß der Entscheidung: ein `deny` blockiert den Aufruf und ein `instruct` lenkt den Agenten. + +## Eine Maschine hinzufügen + +Eine Maschine erscheint unter **Admin → enforcement**, sobald sie mit Cloud verbunden ist. Falls die gewünschte noch nicht dort angezeigt wird: - 1. Gehe zu **Admin → Durchsetzung**, finde die Maschine und klappe ihre Zeile auf. - 2. Wähle **Bearbeiten**, füge die geprüfte Richtlinienversion hinzu und wähle **Beobachten** oder eine durchsetzende Wirkung. - 3. Wende die Änderung an, warte dann auf den nächsten Check-in der Maschine und bestätige deren Deployment- und Coverage-Status. - 4. Gehe zu **Beobachten → Richtlinie**, um Live-Entscheidungen einzusehen. - - ![Der Maschinen-Deployment-Editor mit Richtlinienversionen, Durchsetzungs- und Beobachtungseffekten sowie der Aktion zum Anwenden des Deployments.](/images/dashboard/enforcement-editor.png) + 1. Gehen Sie zu **Administration → Keys** und erstellen Sie einen Schlüssel mit `policies:pull`, damit die Maschine Bereitstellungen empfangen kann, und `events:add`, damit ihre Entscheidungen Cloud erreichen. + 2. Verbinden Sie die Maschine mit diesem Schlüssel — [Eine Maschine mit Cloud verbinden](/de/start/setup#connect-a-machine-to-cloud) führt Sie durch den Vorgang. + 3. Bestätigen Sie, dass sie unter **Admin → enforcement** angezeigt wird. - Deploye über die CLI mit `fp fleet`. Überprüfe das resultierende Set, bevor du es anwendest — `deploy` gibt den vollständigen Plan aus und fragt **nur in einem interaktiven Terminal ohne `--json`**. Mit `--json`, mit `--yes` oder bei umgeleitetem stdin (ein CI-Schritt, ein Skript, ein Agent der eine Shell aufruft) wird der Plan sofort ohne Ausgabe und ohne Abfrage angewendet — führe daher zuerst `fp fleet show ` aus, wenn du den Plan prüfen möchtest: + Auf der Maschine: + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + Im Terminal fragt `failproofai config`, ob eine Verbindung zu Cloud hergestellt werden soll, und fordert den Schlüssel an einer maskierten Eingabeaufforderung an. Bestätigen Sie anschließend von überall, dass die Maschine registriert ist, mit `fp fleet list`. + + + +## Im Beobachtungsmodus bereitstellen + + + + 1. Gehen Sie zu **Admin → enforcement**, suchen Sie die Maschine und klappen Sie deren Zeile auf. + 2. Wählen Sie **Bearbeiten**, fügen Sie die getestete Richtlinienversion hinzu und wählen Sie **Beobachten**. + 3. Übernehmen Sie die Änderung, warten Sie dann auf den nächsten Check-in der Maschine und bestätigen Sie deren Bereitstellungs- und Abdeckungsstatus. + 4. Gehen Sie zu **Observe → policy**, um Live-Entscheidungen zu prüfen. + ![Der Bereitstellungseditor für Maschinen mit Richtlinienversionen, Durchsetzen- und Beobachten-Effekten sowie der Aktion zum Anwenden der Bereitstellung.](/images/dashboard/enforcement-editor.png) + + ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` zeigt Absicht vs. Lieferung (eine Maschine wird als `behind` angezeigt, bis sie das nächste Mal abfragt), `fp fleet history ` listet die Generationen auf und `fp fleet rollback ` stellt eine davon wieder her — dies schlägt fehl, wenn diese Generation eine inzwischen deaktivierte oder gelöschte Richtlinie benennt. + Das Suffix `:observe` sorgt für den Beobachtungsmodus: ein einfaches `--add no-force-push` ohne Suffix behält den Effekt bei, den die Maschine für diese Richtlinie bereits hat, und setzt andernfalls durch. Wechseln Sie später mit `--add no-force-push:enforce` zum Durchsetzungsmodus. + + `deploy` **ersetzt den gesamten Richtliniensatz der Maschine** mit dem Ergebnis. Es gibt den Plan aus und fragt vor der Anwendung nach — jedoch nur bei einem interaktiven Terminal. Mit `--yes`, unter `fp --json` oder bei umgeleiteter stdin (ein CI-Schritt, ein Skript, ein Agent, der ausführt) wird ohne Rückfrage angewendet; der Plan wird dennoch ausgegeben oder als `plan` unter `--json` zurückgegeben. - Überprüfe die Maschine selbst mit `failproofai config --status` und verwende nach dem Deployment `fp sessions --env production --since 24h` sowie `fp events --event-type hook_completed`, um zu verifizieren, dass Aktivität die Cloud erreicht. + Auf der Maschine listet `failproofai policies` die von Cloud verwalteten Richtlinien auf, die ausgeführt werden, und `failproofai config --status` zeigt deren Verbindung an. Verwenden Sie `fp sessions --env production --since 24h` und `fp events --event-type hook_completed`, um zu bestätigen, dass die Aktivität die Cloud erreicht. - - Deploye eine geprüfte Version, kein veränderliches Draft, beginnend mit einer Nicht-Produktionsmaschine oder einer kleinen Gruppe, deren Sessions du einsehen kannst. + + Wählen Sie die veröffentlichte Version und die Maschinen aus, auf denen sie ausgeführt werden soll. - - Überprüfe Treffer, Begründungen, betroffene Tools und False Positives, ohne die Arbeit zu blockieren. + + Überprüfen Sie Übereinstimmungen, Begründungen, betroffene Tools und Falschmeldungen, während nichts blockiert wird. - - Stelle nach dem Deployment auf Durchsetzung um, wenn beobachtete Treffer unsichere Aktionen von gültigen trennen, und bestätige dann, dass jede vorgesehene Maschine das Deployment abgerufen hat und Entscheidungen meldet. + + Wechseln Sie den Effekt zum Durchsetzen, sobald die beobachteten Übereinstimmungen unsichere Aktionen von gültigen trennen, und bestätigen Sie dann, dass jede vorgesehene Maschine die Änderung abgerufen hat und Entscheidungen meldet. -Maschinen benötigen die Berechtigung `policies:pull`. Die Ereignismeldung wird separat über `events:add` gesteuert; überprüfe beides, wenn du Cloud-Analyse und Durchsetzung erwartest. +## Abdeckung prüfen + +Die Abdeckung zeigt, ob eine Richtlinie dort ausgeführt wird, wo das Risiko besteht. + +1. Gehen Sie zu **Admin → enforcement** und überprüfen Sie die Summen für Durchsetzen und Beobachten. +2. Suchen Sie eine Maschine nach ID oder Label, oder filtern Sie nach Maschinen, bei denen eine Richtlinie fehlt. +3. Klappen Sie eine Zeile auf, um zugewiesene Richtlinien, gemeldete Bereitstellung, letzten Check-in und Verlauf zu vergleichen. +4. Aktualisieren Sie nach dem Abrufintervall der Maschine, wenn eine angewendete Bereitstellung noch aussteht. + +![Die Enforcement-Flotte mit Richtlinienabdeckung, Bereitstellungsstatus der Maschine sowie Beobachten- und Durchsetzen-Zuweisungen.](/images/dashboard/enforcement-fleet.png) + +Achten Sie auf Maschinen, die die neueste Bereitstellung nie abgerufen haben, registrierte Maschinen, die keine Meldungen mehr senden, eine Richtlinie, die der falschen Umgebung zugewiesen ist, und Versionsabweichungen nach einem unterbrochenen Update. + +Kennzeichnen Sie Maschinen nach Workload und Umgebung — Hostnamen allein überleben Autoskalierung oder Austausch selten: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - Die Verwaltung der Durchsetzung ist ein administrativer Cloud-Workflow. Behandle rein root-basierte Durchsetzungsrouten nicht als gewöhnliche Kunden-`/v1`-API-Endpunkte. + Die Durchsetzungsverwaltung ist ein administrativer Cloud-Workflow. Behandeln Sie root-exklusive Durchsetzungsrouten nicht als gewöhnliche Kunden-`/v1`-API-Endpunkte. \ No newline at end of file diff --git a/docs/de/policies/editor.mdx b/docs/de/policies/editor.mdx index 77ab4898..e14bf1d0 100644 --- a/docs/de/policies/editor.mdx +++ b/docs/de/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "Policy-Editor" -description: "Erstelle und überarbeite versionierte Richtlinien auf Basis eines bestätigten Fehlermusters." +title: "Eine Richtlinie schreiben" +description: "Lass Failproof AI eine Richtlinie aus einem Audit-Befund entwerfen, oder schreibe die Quelle selbst – dann überprüfen, testen und veröffentlichen." icon: "file-pen-line" --- -Verwende den Policy-Editor, um einen Fund oder ein Problem in eine einsetzbare Regel umzuwandeln. Halte Erstellung und Deployment getrennt, damit ein Entwurf das Live-Verhalten nicht stillschweigend verändern kann. +Es gibt zwei Möglichkeiten, eine Richtlinie zu schreiben: Failproof AI entwirft sie aus einem Audit-Befund, oder du schreibst die Quelle selbst. Nichts wird veröffentlicht oder bereitgestellt, bis du es entscheidest. -Wenn ein Problem ein wiederholbares Aktionsmuster aufweist, öffne es unter **Analyze → issues** und wähle **generate policy**. Failproof AI erklärt zunächst, ob eine Richtlinie das Problem abbilden kann, und überführt dann den geprüften Intent sowie den Fundkontext in den Editor. Die generierte Quelle bleibt so lange ein Entwurf, bis du sie veröffentlichst. +## Eine Richtlinie aus einem Audit schreiben -## Eine Richtlinienversion veröffentlichen +Ein Audit findet einen Fehler; eine Richtlinie verhindert, dass er sich wiederholt. Failproof AI entwirft die Richtlinie anhand der Belege des Befunds. + +### 1. Audit durchführen + +Führe einen [Audit](/de/audits/run) über die Sitzungen durch, in denen der Fehler auftritt. Jeder Befund enthält seine Belege, eine Grundursache und einen vorgeschlagenen Präventionspfad. Arbeite mit einem Befund, der ein **wiederholbares Aktionsmuster** aufweist – eine Richtlinie kann nur das stoppen, was sie in einem Hook-Ereignis erkennen kann. + +### 2. Den Entwurf generieren - 1. Gehe zu **Admin → policy editor** und beschreibe im Bereich **compose** das Fehlermuster, oder füge den JavaScript-Richtlinienquellcode ein. - 2. Validiere den Quellcode und behebe alle gemeldeten Fehler. - 3. Trage die Richtlinienidentität ein und veröffentliche sie. Nutze anschließend **library**, um Versionen zu vergleichen oder zu deaktivieren. - 4. Wähle **enforcement**, sobald die Version für ein maschinelles Rollout bereit ist. + 1. Öffne das Problem des Befunds unter **Analyze → issues** und überprüfe die zitierten Sitzungen, die Grundursache und die Empfehlung. + 2. Wähle **generate policy**. Failproof AI beurteilt zunächst, ob eine Richtlinie das Problem überhaupt ausdrücken kann. Ein **no policy**-Ergebnis bedeutet, dass die Lösung eine Benachrichtigung, eine Workflow-Änderung oder eine Person erfordert – keine Richtlinie. + 3. Wähle **write this policy**. Der Titel des Problems, der Befund, die Grundursache, die Empfehlung und die vorgeschlagene Durchsetzungsabsicht werden als Entwurf in **Admin → policy editor** übernommen. Verwende **open the editor anyway**, wenn du mit der Eignungsprüfung nicht einverstanden bist. - ![Die Compose-Ansicht des Policy-Editors mit Richtlinienidentität, KI-gestützter Erstellung, Quellvalidierung und Veröffentlichungssteuerung.](/images/dashboard/policy-editor.png) + ![Die Compose-Ansicht des Policy-Editors mit Richtlinienidentität, KI-gestütztem Entwurf, Quellvalidierung und Veröffentlichungssteuerung.](/images/dashboard/policy-editor.png) - Veröffentliche über die CLI mit `fp policies publish`. Dieser Befehl erstellt eine **neue Version** und bearbeitet keine bestehende in-place. Außerdem prüft er den Quellcode syntaktisch mit node, bevor er ihn überträgt – da nachgelagerte Schritte dies nicht tun, würde ein Syntaxfehler sonst erst zur Enforcement-Zeit auf dem Zielsystem auftreten: + Lies die Belege und erstelle dann einen Entwurf mit dem Assistenten. `compose` gibt die Quelle zur Überprüfung aus und veröffentlicht nichts: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - Das Veröffentlichen deployt nichts – eine neue Version liegt ungenutzt vor, bis `fp fleet deploy` sie auf einem Gerät aktiviert. `fp policies compose ""` entwirft Quellcode mithilfe des Cloud-Assistenten und gibt ihn zur Überprüfung aus, anstatt ihn direkt zu veröffentlichen. - - Um eine Richtlinie stattdessen in eine lokale Agenten-CLI (nicht Cloud) zu installieren, verwende `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. + `compose` benötigt eine angemeldete Sitzung (`fp login`), deren Rolle `policies:write` besitzt; API-Keys werden abgelehnt. -## Checkliste für die Erstellung +### 3. Den Entwurf überprüfen + +Ein Entwurf ist ein Ausgangspunkt, kein Urteil. Überprüfe vor der Veröffentlichung, ob er: + +1. Den Fehlermodus in operativer Sprache benennt. +2. Nur die Hook-Ereignisse und Tools abgleicht, die genug Belege für eine Entscheidung liefern. +3. Die engste Bedingung verwendet, die die unsichere Aktion erfasst. +4. Eine Begründung zurückgibt, die dem Agenten mitteilt, was er stattdessen tun soll. +5. `instruct` verwendet, wenn der Agent den Kurs sicher korrigieren kann, und `deny` nur dann, wenn das Zulassen der Aktion inakzeptabel oder irreversibel ist. + +Validiere die Quelle im Editor und behebe jeden gemeldeten Fehler. + +### 4. Testen und dann veröffentlichen + +Führe **backtest** unter der Quelle durch, bevor du veröffentlichst: Es spielt den Entwurf gegen Aufrufe ab, die deine Agenten bereits gemacht haben, und zählt die funktionierenden Aufrufe, die unterbrochen worden wären. [Eine Richtlinie testen](/de/policies/test) behandelt das sowie die anderen Prüfungen. + +Wenn sie sich korrekt verhält, gib die Richtlinienidentität ein und wähle **publish version**. Das Veröffentlichen erstellt eine unveränderliche Version und stellt nichts bereit: Sie liegt ungenutzt, bis du sie [bereitstellst](/de/policies/deploy). Über ein Terminal: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` prüft die Quelle syntaktisch, bevor sie gesendet wird – ein Syntaxfehler wird also hier aufgedeckt und nicht zur Laufzeit auf einem Gerät. + +## Selbst schreiben + +Eine Richtlinie ist JavaScript oder TypeScript gegen die `failproofai`-API: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +Dies trifft auf `production/config.yml`, `/srv/production/config.yml`, `/srv/production` und `C:\\production\\config.yml` für sowohl `Write` als auch `Edit` zu, jedoch nicht auf `production-backup`: `production` muss ein vollständiges Pfadsegment sein. Der Kontext enthält außerdem den Ereignistyp, normalisierte Nutzdaten, Sitzungsmetadaten, Parameter und die Quell-CLI, sofern verfügbar – siehe das [Policy SDK](/de/reference/policy-sdk). + +Um es als Version zu veröffentlichen, füge die Quelle in **compose** unter **Admin → policy editor** ein und folge den Schritten 3 und 4 oben, oder veröffentliche die Datei über ein Terminal mit `fp policies publish`. -1. Benenne das Fehlermuster in operativer Sprache. -2. Wähle die Hook-Events und Tools aus, die ausreichend Kontext für eine Entscheidung liefern. -3. Formuliere die engstmögliche Bedingung, die unsicheres Verhalten trifft. -4. Gib eine Begründung zurück, die dem Agenten oder Operator mitteilt, wie weiter vorzugehen ist. -5. Füge Beispiele hinzu, die übereinstimmen sollen, sowie Beispiele, die weiterhin erlaubt bleiben müssen. -6. Speichere eine neue Version und fordere eine Überprüfung an. +Um sie ohne Cloud auf einem Gerät auszuführen, speichere sie unter `.failproofai/policies/` mit einem Namen, der auf `policies.js`, `policies.mjs` oder `policies.ts` endet – diese werden automatisch im Projekt- und Benutzerbereich geladen – oder installiere sie über den Pfad: -Verwende `instruct`, wenn der Agent den Kurs sicher korrigieren kann. Verwende `deny`, wenn das Zulassen der Aktion ein inakzeptables oder irreversibles Risiko darstellen würde. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - Richtlinienversionen sind unveränderliche Deployment-Eingaben. Das Bearbeiten eines Entwurfs erstellt eine neue Version; bestehende Versionen, die bereits Maschinen zugewiesen sind, sollten nicht überschrieben werden. - \ No newline at end of file +Gib jeder Richtlinie einen Namen, der über Konventions-, benutzerdefinierte, Paket- und Cloud-verwaltete Richtlinien hinweg eindeutig ist. \ No newline at end of file diff --git a/docs/de/policies/failure-behavior.mdx b/docs/de/policies/failure-behavior.mdx index 7a325c14..551195f3 100644 --- a/docs/de/policies/failure-behavior.mdx +++ b/docs/de/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- title: "Fehlerverhalten" -description: "Verstehen Sie, was passiert, wenn die Policy-Auswertung oder der lokale Daemon nicht erreichbar ist." +description: "Verstehen Sie, was passiert, wenn die Policy-Auswertung oder der lokale Daemon nicht verfügbar ist." icon: "shield-alert" --- -Failproof AI ist so konzipiert, dass ein Durchsetzungsfehler sichtbar wird, anstatt riskante Aktionen stillschweigend zuzulassen. +Failproof AI ist so konzipiert, dass ein Erzwingungsfehler sichtbar wird, anstatt riskante Aktionen stillschweigend zuzulassen. ## Einen Failure-Closed-Block diagnostizieren - 1. Gehen Sie zu **Admin → enforcement** und öffnen Sie den Rechner. - 2. Prüfen Sie dessen letzten Check-in, zugewiesene Deployment und gemeldetes Deployment. - 3. Gehen Sie zu **Observe → policy** und öffnen Sie die Sitzung der abgelehnten Entscheidung. - 4. Überprüfen Sie, ob der Grund auf Daemon-Erreichbarkeit, Versionsabweichung oder die Policy selbst hinweist. + 1. Gehen Sie zu **Admin → Enforcement** und öffnen Sie die Maschine. + 2. Prüfen Sie das letzte Check-in, das zugewiesene Deployment und das gemeldete Deployment. + 3. Gehen Sie zu **Observe → Policy** und öffnen Sie die Sitzung der abgelehnten Entscheidung. + 4. Prüfen Sie, ob der Grund auf Daemon-Erreichbarkeit, Versionsunterschiede oder die Policy selbst hinweist. @@ -23,45 +23,47 @@ Failproof AI ist so konzipiert, dass ein Durchsetzungsfehler sichtbar wird, anst failproofai config ``` - Ein erneutes Ausführen von `failproofai config` aktualisiert und startet den Daemon nach einem Paket-Upgrade neu. + Das erneute Ausführen von `failproofai config` aktualisiert und startet den Daemon nach einem Paket-Upgrade neu. -Auf einem Rechner, der für die Verwendung von `failproofaid` konfiguriert ist, ist der Daemon der einzige Auswerter. Wenn er nicht erreichbar ist oder seine Protokollversion nicht mit der CLI übereinstimmt, schlägt die Hook-Auswertung geschlossen fehl. Die Aktion wird mit einem Hinweis abgelehnt, der den Operator auffordert, den Daemon zu überprüfen oder zu aktualisieren. +Auf einer Maschine, die für die Verwendung von `failproofaid` konfiguriert ist, ist der Daemon der einzige Auswertende. Wenn er nicht erreichbar ist oder seine Protokollversion nicht mit der CLI übereinstimmt, schlägt die Hook-Auswertung geschlossen fehl. Die Aktion wird mit einem Hinweis abgelehnt, der den Operator anweist, den Daemon zu überprüfen oder zu aktualisieren. -Vor der Daemon-Konfiguration werten Hooks Policies prozessintern aus. Sobald die Daemon-Konfiguration gespeichert ist, fällt Failproof AI bei einem Daemon-Ausfall nicht stillschweigend auf einen zweiten Auswerter zurück. +Vor der Daemon-Konfiguration werten Hooks Policies in-process aus. Sobald die Daemon-Konfiguration gespeichert ist, fällt Failproof AI bei einem Daemon-Fehler nicht stillschweigend auf einen zweiten Auswertenden zurück. ## Auf eine Failure-Closed-Entscheidung reagieren 1. Führen Sie `failproofai config --status` aus. -2. Wenn sich die Versionen unterscheiden, führen Sie `failproofai config` nach dem Paket-Update erneut aus. -3. Wenn der Daemon nicht erreichbar ist, prüfen Sie dessen Dienststatus und lokale Logs. -4. Setzen Sie die Agenten-Arbeit erst fort, wenn ein bekannter Policy-Auswertungspfad wieder funktioniert. +2. Wenn sich die Versionen unterscheiden, führen Sie `failproofai config` nach dem Aktualisieren des Pakets erneut aus. +3. Wenn der Daemon nicht erreichbar ist, prüfen Sie seinen Service-Status und die lokalen Logs. +4. Setzen Sie die Agent-Arbeit erst fort, wenn ein bekannter Policy-Auswertungspfad fehlerfrei funktioniert. - Wiederholen Sie die blockierte Aktion nicht wiederholt. Eine Failure-Closed-Antwort bedeutet, dass das System nicht feststellen konnte, ob die Aktion sicher war. + Versuchen Sie nicht wiederholt, die blockierte Aktion erneut auszuführen. Eine Failure-Closed-Antwort bedeutet, dass das System nicht feststellen konnte, ob die Aktion sicher war. ## Ein Pack lässt sich nicht laden -Ein Rechner, der angewiesen wurde, ein Pack durchzusetzen, und es nicht ausführen kann, lehnt ab, anstatt stillschweigend fortzufahren. Der Auslöser ist eine **aufgezeichnete Erwartung**, niemals eine leere: Ein Rechner ohne installierte Packs ist still, während ein Pack, das deklariert wurde und sich nicht auflösen lässt – oder das weniger registriert als sein Manifest angibt – ablehnt. +Eine Maschine, die angewiesen wurde, ein Pack durchzusetzen, und es nicht ausführen kann, lehnt ab, anstatt still weiterzumachen. Der Auslöser ist eine **aufgezeichnete Erwartung**, niemals eine leere: Eine Maschine ohne installierte Packs ist still, während ein Pack, das deklariert ist und sich nicht auflösen lässt – oder das weniger registriert, als sein Manifest deklariert – ablehnt. -Die Ablehnung ist **eng gefasst**, anders als bei einem nicht erreichbaren Daemon. Ein Daemon, der nicht erreicht werden kann, bedeutet, dass überhaupt keine Auswertung stattgefunden hat und daher nichts als sicher eingestuft werden kann. Ein Pack, das sich nicht laden lässt, hat eine aufzählbare Menge fehlender Guards, da jede deklarierte Policy ihren eigenen `match` mitbringt – es lehnt daher nur die Ereignisse und Tools ab, die diese Policies abdeckten, während alles andere weiterläuft. +Die Ablehnung ist **eng gefasst**, anders als bei einem nicht erreichbaren Daemon. Ein Daemon, der nicht erreichbar ist, bedeutet, dass überhaupt keine Auswertung stattgefunden hat, sodass nichts als sicher eingestuft werden kann. Ein Pack, das sich nicht laden lässt, hat einen aufzählbaren Satz fehlender Guards, da jede deklarierte Policy ihren eigenen `match` trägt – es lehnt also nur die Ereignisse und Tools ab, die diese Policies abdeckten, und alles andere wird fortgesetzt. Es wird nicht ausgelöst bei: - einem `observe`-Pack, das konstruktionsbedingt auswertet und verwirft -- Policies, die nie übernommen oder explizit deaktiviert wurden -- einem Pack, das der Loader nie erhalten hat, wo sich „keine Registrierungen" nicht von einem bewussten Überspringen unterscheiden lässt -- einer Pause einer aktiven Sitzung -- einem Load-Timeout, das vorübergehend ist – ein kurzer langsamer Festplattenmoment darf nicht ablehnen, bis ein Mensch eingreift +- Policies, die Sie nie übernommen oder explizit deaktiviert haben +- einem Pack, das der Loader nie erhalten hat und bei dem „keine Registrierungen" nicht von einem bewussten Überspringen unterschieden werden kann +- einer aktiven Sitzungspause +- einem Lade-Timeout, das vorübergehend ist – ein einzelner langsamer Festplattenmoment darf nicht ablehnen, bis ein Mensch eingreift -`UserPromptSubmit` **instruiert** statt abzulehnen, unabhängig davon, was die fehlende Policy deklariert hat. Eine pauschale Ablehnung würde dies einschließen und Sie vom Agenten aussperren, der das Problem beheben könnte. +`UserPromptSubmit` **weist an**, anstatt abzulehnen, unabhängig davon, was die fehlende Policy deklariert hat. Eine pauschale Ablehnung würde auch diesen Eintrag erfassen und Sie von dem Agent aussperren, der das Problem beheben könnte. ### Vorgehensweise ```bash -failproofai pack list +failproofai policies ``` -Der Befehl nennt alle installierten Packs, die sich nicht laden lassen, gibt den Grund an und beendet sich mit einem Nicht-Null-Exit-Code. Installieren Sie das Pack anschließend entweder neu (`failproofai pack add `) oder entfernen Sie es (`failproofai pack remove `) – durch das Entfernen wird die Erwartung zurückgezogen, und die Ablehnung endet damit. \ No newline at end of file +Die Auflistung markiert ein installiertes Pack, dessen Installationseintrag oder Digest nicht mehr verifiziert werden kann, und gibt den Grund an. Das Pack wird dabei nicht importiert, sodass eines, das erst beim Laden fehlschlägt – indem es weniger als sein Manifest deklariert registriert – normal aufgelistet wird; die nachfolgende Ablehnung ist das, was dieses Pack benennt. In jedem Fall installieren Sie es neu (`failproofai policies add `) oder entfernen Sie es (`failproofai policies remove `) – das Entfernen zieht die Erwartung zurück, und die Ablehnung hört damit auf. + +Die Ablehnung selbst wird `pack/failproofai-pack-unavailable` zugeschrieben, was die geladenen Policies überrangt, sodass ein blockierter Tool-Aufruf das fehlende Pack benennt und nicht den zufällig zuerst ausgelösten verbleibenden Guard. \ No newline at end of file diff --git a/docs/de/policies/local-configuration.mdx b/docs/de/policies/local-configuration.mdx index 7e14fbb3..71a8e7e1 100644 --- a/docs/de/policies/local-configuration.mdx +++ b/docs/de/policies/local-configuration.mdx @@ -1,55 +1,49 @@ --- title: "Lokale Konfiguration" -description: "Richtlinienbereich, Parameter, benutzerdefinierte Dateien und maschinenspezifische Failproof AI-Einstellungen verwalten." +description: "Steuern Sie Policy-Scope, Parameter, benutzerdefinierte Dateien und maschinenweite Failproof AI-Einstellungen." icon: "file-cog" --- -Failproof AI trennt die Richtlinienauswahl von Maschinen- und Daemon-Einstellungen. Dadurch bleiben die Repository-Richtlinienentscheidungen überprüfbar, während Anmeldedaten und Daemon-Zustand außerhalb des Repositorys gespeichert werden. +Failproof AI trennt, was ein Repository committen kann – Hook-Verdrahtung, Policy-Parameter, benutzerdefinierte Policies – von Maschinenzustand wie Anmeldedaten, installierten Packs und dem Daemon. -## Einen Richtlinienbereich wählen +## Scope auswählen - - - Führen Sie `failproofai` ohne Argumente aus, um das lokale Richtlinien-Dashboard zu öffnen. Wählen Sie den Benutzer-, Projekt- oder lokalen Bereich, bevor Sie eine Richtlinie aktivieren, damit die Änderung in die gewünschte Konfigurationsdatei geschrieben wird. +Ein Scope legt fest, wo die Hooks verdrahtet werden und in welche Konfigurationsdatei Sie Parameter und benutzerdefinierte Policy-Pfade schreiben: - - **Benutzer** gilt projektübergreifend auf dieser Maschine. - - **Projekt** gehört zum Repository und kann eingecheckt werden. - - **Lokal** überschreibt ein Projekt für einen Benutzer und sollte in der .gitignore bleiben. +- **User** gilt projektübergreifend auf dieser Maschine. +- **Project** gehört zum Repository und kann committet werden. +- **Local** überschreibt ein Projekt für einen Benutzer und sollte gitignoriert bleiben. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # Hooks für dieses Repository verdrahten +failproofai policies --install --cli claude --scope user # oder für jedes Projekt auf dieser Maschine +failproofai policies +``` - Nicht jedes Harness unterstützt den lokalen Bereich. Die CLI lehnt einen Bereich ab, den das ausgewählte Harness nicht abbilden kann. - - +Nicht jedes Harness unterstützt den Local-Scope; die CLI lehnt einen Scope ab, den das gewählte Harness nicht abbilden kann. + +Welche Pack-Policies aktiviert sind, ist **nicht** scoped. Die Einstellung wird beim installierten Pack gespeichert, sodass `failproofai policies add ` eine Policy für die gesamte Maschine aktiviert, unabhängig von `--scope`. -| Bereich | Richtlinien-Konfigurationsdatei | +| Scope | Policy-Konfigurationsdatei | | --- | --- | -| Projekt | `/.failproofai/policies-config.json` | -| Lokal | `/.failproofai/policies-config.local.json` | -| Benutzer | `~/.failproofai/policies-config.json` | +| Project | `/.failproofai/policies-config.json` | +| Local | `/.failproofai/policies-config.local.json` | +| User | `~/.failproofai/policies-config.json` | -Aktivierte Richtlinien werden als Vereinigung zusammengeführt. Für Richtlinienparameter wird der erste Bereich verwendet, der Parameter für die jeweilige Richtlinie definiert – in der Reihenfolge Projekt → Lokal → Benutzer. Bei expliziten benutzerdefinierten Richtlinienpfaden wird ebenfalls der erste Bereich verwendet, der diese definiert. +Policy-Parameter verwenden den ersten Scope, der Parameter für diese Policy definiert, in der Reihenfolge Project → Local → User. Explizite benutzerdefinierte Policy-Pfade verwenden den ersten Scope, der sie definiert. -## Richtlinienparameter konfigurieren +## Policy-Parameter konfigurieren - Öffnen Sie die Richtlinie im lokalen Dashboard, bearbeiten Sie die unterstützten Parameter und speichern Sie im gewählten Bereich. Führen Sie dann eine passende und eine nicht passende Agentenaktion aus und überprüfen Sie die Entscheidung unter **Beobachten → Richtlinie**. + Öffnen Sie die Policy im lokalen Dashboard, bearbeiten Sie die unterstützten Parameter und speichern Sie im gewählten Scope. Führen Sie eine passende und eine nicht passende Agent-Aktion aus und prüfen Sie die Entscheidung unter **Observe → policy**. - Bearbeiten Sie die `policies-config.json` des gewählten Bereichs und führen Sie anschließend `failproofai policies` aus, um unbekannte Richtliniennamen oder Parameterschlüssel anzuzeigen. + Bearbeiten Sie die `policies-config.json` des gewählten Scopes und führen Sie anschließend `failproofai policies` aus: Es warnt vor einem `policyParams`-Eintrag, der eine Policy benennt, die kein installiertes Pack enthält. Die Schlüssel innerhalb eines Eintrags werden nicht geprüft – vergleichen Sie daher deren Schreibweise mit der nachfolgenden Tabelle. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ Aktivierte Richtlinien werden als Vereinigung zusammengeführt. Für Richtlinien +### Parameter, die die Failproof AI-Policies akzeptieren + +Jede Policy validiert ihre eigenen Parametertypen. + +| Policy | Parameter | Typ und Standard | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; Einträge enthalten `regex` und `label` | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| Infrastructure blockers | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + Ein Allow-Pattern erweitert, was ein Agent tun darf. Testen Sie die genaue Tokenisierung und Befehlsvarianten auf dem Ziel-Harness, bevor Sie es flächendeckend einsetzen. + + ## Die Maschinendateien verstehen -`~/.failproofai` enthält separate Dateien für separate Vertrauensbereiche: +`~/.failproofai` enthält separate Dateien für separate Vertrauensgrenzen: | Pfad | Zweck | | --- | --- | | `config.json` | Nicht-geheime Daemon-, Audit- und Telemetrie-Einstellungen | -| `credentials.json` | Cloud-Anmeldedaten; mit ausschließlichen Eigentümerberechtigungen gespeichert | -| `policies-config.json` | Benutzerbereich: integrierte Auswahl, Parameter und explizite benutzerdefinierte Pfade | -| `policies/` | Benutzerkonventions-Richtlinien und Cloud-verwaltete Richtlinien-Artefakte | -| `hook-activity/` | Lokales Protokoll der Richtlinienentscheidungen | -| `state/` | Daemon-Spool, Zustand für Gesundheit, Pause und Laufzeit | +| `credentials.json` | Cloud-Anmeldedaten; gespeichert mit Nur-Eigentümer-Berechtigungen | +| `policies-config.json` | User-Scope-Parameter und explizite benutzerdefinierte Policy-Pfade | +| `policies/` | Benutzer-Konventions-Policies, installierte Packs und welche ihrer Policies aktiv sind, sowie Cloud-verwaltete Policy-Artefakte | +| `hook-activity/` | Lokales Policy-Entscheidungsprotokoll | +| `state/` | Daemon-Spool, Zustand, Pause und Laufzeitstatus | -Verwenden Sie `FAILPROOFAI_HOME`, um das vollständige Maschinenverzeichnis für einen Container oder isolierten Test an einen anderen Ort zu verschieben. Verschieben Sie einzelne Zustandsverzeichnisse nicht unabhängig voneinander. +Verwenden Sie `FAILPROOFAI_HOME`, um das gesamte Maschinen-Layout für einen Container oder einen isolierten Test zu verlagern. Verlegen Sie keine einzelnen Statusverzeichnisse unabhängig voneinander. - Checken Sie `credentials.json` niemals ein. Checken Sie Projekt-Richtlinienkonfigurationen und Projektkonventions-Richtlinien erst ein, nachdem Sie diese als Durchsetzungscode überprüft haben. + Committen Sie niemals `credentials.json`. Committen Sie Projekt-Policy-Konfigurationen und Projekt-Konventions-Policies nur, nachdem Sie diese als Durchsetzungscode geprüft haben. \ No newline at end of file diff --git a/docs/de/policies/overview.mdx b/docs/de/policies/overview.mdx index 582baf46..ef10a9f0 100644 --- a/docs/de/policies/overview.mdx +++ b/docs/de/policies/overview.mdx @@ -1,63 +1,54 @@ --- title: "Policies" -description: "Beobachte, steuere oder blockiere Agentenaktionen, bevor ein bekannter Fehler erneut auftritt." +description: "Agent-Aktionen beobachten, steuern oder blockieren, bevor ein bekannter Fehler sich wiederholt." icon: "shield-check" --- -Eine Policy wertet ein Agenten-Hook-Ereignis aus und gibt eine von drei Entscheidungen zurück: +Eine Policy wertet ein Agent-Hook-Ereignis aus und gibt eine von drei Entscheidungen zurück: - `allow` lässt die Aktion fortfahren. - `instruct` gibt dem Agenten korrigierende Hinweise. - `deny` blockiert die Aktion mit einer Begründung. -## Die drei Policy-Oberflächen nutzen +## Wo Policies gespeichert sind - - - 1. Gehe zu **Observe → policy**, um Policy-Entscheidungen aus Sitzungen zu filtern und zu untersuchen. - 2. Gehe zu **Admin → policy editor**, um Policies zu erstellen, zu validieren, zu veröffentlichen, zu deaktivieren oder unveränderliche Versionen einzusehen. - 3. Gehe zu **Admin → enforcement**, um Versionen und Effekte Maschinen zuzuweisen. +| Im Dashboard | Was Sie dort tun | +| --- | --- | +| **Observe → policy** | Entscheidungen aus echten Sitzungen überprüfen: welche Policy übereinstimmte, auf welcher Maschine und warum | +| **Admin → policy editor** | Eine Policy schreiben, gegen vergangenen Traffic backtesten, eine unveränderliche Version veröffentlichen und Versionen in der **library** vergleichen | +| **Admin → enforcement** | Versionen auf Maschinen in Observe- oder Enforce-Modus einsetzen | - Nutze die Policy-Seite, um zu verstehen, was bereits greift, bevor du Enforcement erstellst oder änderst. +Der Policy-Editor ist der Ort, an dem ein Fehler zur Regel wird. Beschreiben Sie den Fehlerfall oder fügen Sie Policy-Quellcode in **compose** ein, testen Sie den Entwurf gegen bereits vorhandenen Traffic und veröffentlichen Sie eine Version: - ![Die Policy-Seite mit Entscheidungszahlen und lokalen sowie Cloud-verwalteten Policy-Zuordnungen.](/images/dashboard/policy-observe.png) +![Die Compose-Ansicht des Policy-Editors mit Policy-Identität, KI-gestütztem Entwurf, Quellvalidierung und Veröffentlichungskontrollen.](/images/dashboard/policy-editor.png) - Im Editor wandelst du eine Fehlerbedingung in Quellcode um, validierst ihn und veröffentlichst eine unveränderliche Version. +Auf einer Maschine listet `failproofai policies` alles auf, was dort durchgesetzt wird. `fp policies` und `fp fleet` decken Editor und Enforcement vom Terminal aus ab — siehe die [Cloud-CLI-Referenz](/de/reference/cloud-cli). - ![Der Policy-Editor zum Erstellen und Veröffentlichen einer unveränderlichen Policy-Version.](/images/dashboard/policy-editor.png) +## Eine Policy erhalten - Enforcement weist dann diese veröffentlichte Version und ihren Beobachtungs- oder Durchsetzungseffekt Maschinen zu. - - ![Die Enforcement-Flotte mit Maschinenabdeckung und zugewiesenen Policy-Versionen.](/images/dashboard/enforcement-fleet.png) - - Überprüfe die Entscheidungen nach der Bereitstellung erneut auf der Policy-Seite, damit die Authoring- und Flottenansichten mit der tatsächlichen Agentenaktivität verknüpft sind. - - - Verwende `failproofai` für lokale Policy-Installation und -Validierung: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - Verwende `fp`, um Cloud-Sitzungen und -Ereignisse mit Policy-Entscheidungen zu finden. Das Erstellen von Policies in der Cloud und die Flottenbereitstellung bleiben Dashboard-Workflows. - - - -Policies haben drei eigenständige Bereiche in Failproof AI: - -1. **Entscheidungen analysieren** in Sitzungen, Dashboards und Audits. -2. **Versionen erstellen** mit eingebauten Regeln, Code oder dem Policy-Editor. -3. **Versionen bereitstellen und durchsetzen** auf ausgewählten Maschinen. - -Beginne mit einem bestätigten Fehlermodus. Definiere die kleinstmögliche Ereignis- und Tool-Übereinstimmung, die ihn identifiziert, teste legitime und unsichere Beispiele, und beobachte zunächst, bevor du durchsetzt. +Es gibt zwei Möglichkeiten. - - Aktiviere eine geprüfte Regel für häufige Risiken bei Secrets, Shell, Git, Cloud und Workflows. + + Lassen Sie Failproof AI einen Entwurf aus einem Audit-Befund erstellen, oder schreiben Sie den Quellcode selbst, überprüfen und veröffentlichen Sie ihn dann im Editor. - - Formuliere eine workflow-spezifische Entscheidung in JavaScript oder TypeScript. + + Binden Sie ein Failproof AI Policy-Pack für Ihren Anwendungsfall oder ein Community-Pack aus dem Policy-Hub mit einem einzigen Befehl ein. - \ No newline at end of file + + +## Dann ausrollen + + + + Testen Sie den Entwurf gegen bereits vorhandenen Traffic und führen Sie ihn gegen eine Aktion aus, die er stoppen muss, und eine, die er zulassen muss — alles vor der Veröffentlichung. Siehe [Eine Policy testen](/de/policies/test). + + + Setzen Sie die Version auf Maschinen im **Observe**-Modus ein, lesen Sie ihre Entscheidungen, und erzwingen Sie sie dann. Siehe [Eine Policy deployen](/de/policies/deploy). + + + Jede Veröffentlichung ist eine neue, unveränderliche Version, sodass ein Rollout, der gültige Arbeit blockiert, durch erneutes Deployen der letzten funktionierenden Version rückgängig gemacht werden kann. Siehe [Versionen und Rollback](/de/policies/rollback). + + + +Um Ihre Policies mit anderen Teams zu teilen, [veröffentlichen Sie sie als Pack](/de/policies/publish-a-pack). Was passiert, wenn eine Policy überhaupt nicht ausgewertet werden kann, erfahren Sie unter [Fehlerverhalten](/de/policies/failure-behavior). \ No newline at end of file diff --git a/docs/de/policies/packs.mdx b/docs/de/policies/packs.mdx index f5e68cff..6465a214 100644 --- a/docs/de/policies/packs.mdx +++ b/docs/de/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "Policy-Pakete" -description: "Installiere einen Satz von Richtlinien, der als GitHub-Release veröffentlicht wurde, und verwalte dessen Durchsetzung." +title: "Ein Policy-Pack verwenden" +description: "Binden Sie ein Failproof AI Policy-Pack für Ihren Anwendungsfall ein – oder ein Community-Pack aus dem Policy-Hub – und wählen Sie, was es durchsetzen soll." icon: "package" --- -Ein Paket ist ein Satz von Richtlinien, der als GitHub-Release veröffentlicht wird. Ein einziger Befehl installiert es, die eigenen Prüfsummen des Releases werden vor der Ausführung verifiziert, und der Digest wird gespeichert, damit das Paket danach nicht unbemerkt verändert werden kann. +Ein Pack ist eine Sammlung von Policies, die als GitHub-Release veröffentlicht werden. Ein einziger Befehl installiert es: Die Prüfsummen des Releases werden vor der Ausführung verifiziert, und der Digest wird gespeichert, damit das Pack danach auf Ihrem Rechner nicht unbemerkt verändert werden kann. -## Die Failproof AI-Richtlinien installieren +Alle Packs und alle darin enthaltenen Policies finden Sie im [Policy-Hub](https://befailproof.ai/policy-hub/). Es gibt zwei Arten: + +- **Failproof AI Policy-Packs** — fertig konfigurierte Packs für vordefinierte Anwendungsfälle: einfach einbinden und es funktioniert. Das [Coding-Agent-Policy-Pack](https://befailproof.ai/policy-hub/failproofai/policies/) ist bereits verfügbar, weitere Packs für andere Anwendungsfälle folgen in Kürze. +- **Community-Policy-Packs** — Policies, die Entwickler für ihre eigenen Anwendungsfälle geschrieben und für alle veröffentlicht haben. + +## Failproof AI Policy-Packs + +### Coding-Agent-Policy-Pack ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -Damit wird der von uns veröffentlichte Satz installiert – aus der im Paket enthaltenen Kopie. Es ist also keine Netzwerkverbindung erforderlich und es kann auch hinter einem Proxy nicht fehlschlagen. Einen Teil davon installieren: +Das Pack enthält 38 Policies und aktiviert die 10, die sein Manifest als sicher für den unbeaufsichtigten Betrieb markiert; die übrigen werden Ihnen zur Auswahl angezeigt. Einige der am häufigsten verwendeten und ob ein einfaches `policies add` sie aktiviert: + +| Policy | Was sie bewirkt | Standardmäßig aktiv | +| --- | --- | --- | +| `block-push-master` | Blockiert direkte Pushes auf geschützte Branches | Ja | +| `block-env-files` | Blockiert das Lesen und Schreiben von `.env`-Dateien | Ja | +| `protect-env-vars` | Blockiert Befehle, die Umgebungsvariablen ausgeben | Ja | +| `block-sudo` | Blockiert `sudo`, sofern kein Allow-Muster zutrifft | Ja | +| `block-curl-pipe-sh` | Blockiert heruntergeladene Skripte, die direkt in eine Shell geleitet werden | Ja | +| `sanitize-*` (fünf Policies) | Meldet API-Schlüssel, Bearer-Tokens, JWTs, private Schlüssel und Verbindungsstrings in der Tool-Ausgabe | Ja | +| `block-rm-rf` | Blockiert katastrophale rekursive Löschvorgänge | Nein | +| `block-force-push` | Blockiert Force-Pushes | Nein | +| `block-secrets-write` | Blockiert Schreibzugriffe auf Credential- und Secret-Key-Dateien | Nein | +| `warn-destructive-sql` | Warnt bei `DROP`, `TRUNCATE` und `DELETE` ohne `WHERE` | Nein | + +Aktivieren Sie einzelne deaktivierte Policies namentlich – `failproofai policies add block-rm-rf` – oder nehmen Sie das gesamte Pack mit `--all`. Alle enthaltenen Policies nach Kategorie gruppiert anzeigen: ```bash -failproofai pack add core --policy block-rm-rf # eine oder einige, kommagetrennt -failproofai pack add core --category dangerous-commands # eine ganze Kategorie -failproofai pack add core --all # alles darin +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` listet alle Kategorien auf, die das Paket enthält. +## Community-Policy-Packs -## Den Inhalt eines Pakets vor der Installation einsehen +Entwickler veröffentlichen Packs für ihre eigenen Anwendungsfälle, der [Policy-Hub](https://befailproof.ai/policy-hub/) listet sie auf. Ein Community-Pack wird vom jeweiligen Autor veröffentlicht und nicht von Failproof AI geprüft – lesen Sie daher den Inhalt, bevor Sie es installieren: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -Listet alle Richtlinien des Pakets auf, gruppiert nach Kategorie, und zeigt an, welche vom Autor standardmäßig aktiviert und welche optional sind. Es wird **ausschließlich das Manifest** gelesen – das Einstiegs-Artefakt wird weder heruntergeladen noch importiert. Das Anzeigen eines fremden Pakets führt also keinen fremden Code aus. Das Manifest wird dennoch gegen die `SHA256SUMS` des Releases geprüft, sodass das Angezeigte dem entspricht, was installiert werden würde. - -`failproofai pack list` ohne Quelle listet die hier bereits installierten Pakete auf. +Dies listet alle enthaltenen Policies nach Kategorie gruppiert auf und markiert, welche der Autor standardmäßig aktiviert. Es wird **ausschließlich das Manifest** gelesen – das Entry-Artefakt wird weder heruntergeladen noch importiert, sodass das Anzeigen eines fremden Packs keinen fremden Code ausführen kann. Das Manifest wird dennoch gegen die `SHA256SUMS` des Releases geprüft, sodass das, was Sie lesen, auch das ist, was installiert werden würde. -## Ein fremdes Paket installieren +Anschließend installieren: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -Alle dieser Varianten funktionieren – verwende einfach die, die du zur Hand hast: +Alle folgenden Formate werden akzeptiert – verwenden Sie das, das Ihnen vorliegt: | Quelle | Ergebnis | | --- | --- | -| `acme/support-agent` | Neuestes Release, **angeheftet** am aufgelösten genauen Tag | -| `acme/support-agent@v2.1.0` | Dieses Release | -| `github:acme/support-agent@v2.1.0` | Dasselbe, explizit angegeben | +| `acme/support-agent` | Neuestes Release, **gepinnt** auf den exakten aufgelösten Tag | +| `acme/support-agent@v2.1.0` | Genau dieses Release | +| `github:acme/support-agent@v2.1.0` | Dasselbe, explizit geschrieben | | `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Dasselbe, aus dem Browser kopiert | -Wird kein Tag angegeben, wird das neueste Release installiert **und angeheftet**; anschließend wird der gewählte Tag ausgegeben. Was gespeichert wird, benennt immer genau ein Release, sodass eine Neuinstallation nicht abweichen kann. +Wird kein Tag angegeben, wird das neueste Release installiert und **gepinnt**; anschließend wird Ihnen mitgeteilt, welcher Tag gewählt wurde. Was aufgezeichnet wird, benennt immer genau ein Release, sodass eine Neuinstallation nicht zu Abweichungen führen kann. -## Nur einen Teil eines Pakets übernehmen +## Nur einen Teil eines Packs verwenden -Standardmäßig erhältst du die **eigenen** Standardwerte des Pakets – die Richtlinien, die der Autor als sicher für den unbeaufsichtigten Betrieb markiert hat – nicht alles, was es enthält. +Standardmäßig erhalten Sie die **eigenen** Standardwerte des Packs – die Policies, die der Autor als sicher für den unbeaufsichtigten Betrieb markiert hat –, nicht alles, was es enthält. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # eine oder mehrere, kommagetrennt +failproofai policies add FailproofAI/policies --category dangerous-commands # eine ganze Kategorie +failproofai policies add FailproofAI/policies --all # alles darin ``` -`--category` und `--policy` werden als Vereinigung kombiniert (`--only` wird als Synonym für `--policy` akzeptiert). Das erneute Hinzufügen in einer neueren Version behält deine getroffene Auswahl bei, anstatt den Rest wieder einzuschalten. +`--category` und `--policy` werden als Vereinigung kombiniert (`--only` wird als Synonym für `--policy` akzeptiert). Wenn das Pack bereits installiert ist, ergänzen die Flags das Vorhandene; wenn es ohne Flag und ohne Terminal erneut hinzugefügt wird – etwa für ein Upgrade –, bleibt die bisherige Auswahl erhalten. An einem Terminal ohne Flag öffnet `add` stattdessen die Auswahlmaske, vorausgefüllt mit den Standardwerten des Autors; was Sie auswählen, ersetzt Ihre bisherige Auswahl. -## Aktive Richtlinien verwalten +## Den aktivierten Zustand verwalten ```bash -failproofai policies # alle Quellen in einer Liste, inkl. Pakete -failproofai pack list # nur Pakete, nach Kategorie gruppiert -failproofai policies --uninstall block-refunds # eine Paketrichtlinie deaktivieren +failproofai policies # alle Quellen in einer Liste, inklusive Packs +failproofai policies add block-rm-rf # eine Policy aktivieren +failproofai policies --uninstall block-refunds # eine Pack-Policy deaktivieren failproofai policies --install block-refunds # und wieder aktivieren -failproofai pack remove acme/support-agent +failproofai policies remove acme/support-agent # das Pack deinstallieren ``` -Ein einfacher Name bezieht sich auf die **eingebaute** Richtlinie, sofern eine mit diesem Namen existiert. Benutze den vollqualifizierten Namen eines Pakets, wenn du explizit auf die Paketkopie verweisen möchtest: +Das Aktivieren oder Deaktivieren einer Pack-Policy gilt für den gesamten Rechner: Der Status wird zusammen mit dem installierten Pack gespeichert, nicht in der Projektkonfiguration – unabhängig davon, was `--scope` besagt. + +Ein Name ohne Schrägstrich ist eine Policy; alles mit einem Schrägstrich ist eine Pack-Quelle. Ein einfacher Name wird dem installierten Pack zugeordnet, das ihn deklariert. Wenn zwei installierte Packs denselben Namen deklarieren, geben Sie explizit an, welches gemeint ist: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -Wenn ein Paket eine Richtlinie enthält, deren Name auch einer **aktivierten eingebauten** Richtlinie entspricht, wird die eingebaute Richtlinie ausgeführt und die Paketkopie übersprungen – andernfalls würde dieselbe Prüfung doppelt ausgewertet. Deaktiviere die eingebaute Richtlinie, um stattdessen die Paketversion zu verwenden. - - -## Woher die Failproof AI-Richtlinien stammen - -`core` liest die im npm-Paket enthaltene Kopie. Derselbe Satz wird auch als GitHub-Release veröffentlicht, und genau dieses installierst du, wenn du eine bestimmte Version möchtest: - -```bash -failproofai pack add core # aus diesem Paket, ohne Netzwerk -failproofai pack add FailproofAI/policies # derselbe Satz, aus dem GitHub-Release -``` +Scopes, Parameter und die Dateien, die diese Befehle schreiben, sind unter [Lokale Konfiguration](/de/policies/local-configuration) beschrieben. -## Was Integritätsprüfungen leisten – und was nicht +## Was Integritätsprüfung leistet und was nicht -`SHA256SUMS` wird im selben Release wie das Artefakt ausgeliefert und ist daher **keine** Signatur und beweist nichts über den Herausgeber. Was sie beweist, ist, dass die Bytes genau die sind, die dieses Release veröffentlicht hat – und da der Digest beim Hinzufügen des Pakets gespeichert und vor jedem Import erneut geprüft wird, kann ein Paket danach nicht unbemerkt verändert werden. Ein Repository, das einen Asset neu taggt oder ersetzt, wird nicht mehr geladen, anstatt still etwas anderes auszuführen. +`SHA256SUMS` wird im selben Release wie das Artefakt ausgeliefert und ist daher **keine** Signatur – sie beweist nichts über den Urheber. Was sie beweist: Die Bytes sind genau die, die in diesem Release veröffentlicht wurden. Da der Digest beim Hinzufügen des Packs aufgezeichnet und vor jedem Import erneut geprüft wird, kann ein Pack auf Ihrem Rechner nachträglich nicht unbemerkt verändert werden. Ein Repository, das einen Tag neu setzt oder ein Asset ersetzt, wird nicht mehr geladen, anstatt still etwas anderes auszuführen. -Bei der Installation wird das Paket außerdem **einmal importiert** und gegen sein eigenes Manifest geprüft. Ein Paket, dessen Artefakt sich nicht parsen lässt oder das etwas anderes registriert als deklariert, wird abgelehnt, bevor irgendetwas aktiviert wird – anstatt sauber zu installieren und beim nächsten Tool-Aufruf zu versagen. +Bei der Installation wird das Pack außerdem **einmalig importiert** und gegen sein eigenes Manifest geprüft. Ein Pack, dessen Artefakt nicht geparst werden kann oder das etwas anderes registriert als deklariert, wird abgelehnt, bevor irgendetwas aktiviert wird – anstatt sauber zu installieren und beim nächsten Tool-Aufruf zu versagen. -## Wenn ein Paket nicht geladen werden kann +## Wenn ein Pack nicht geladen werden kann -Ein Paket, dessen Durchsetzung auf diesem Rechner konfiguriert ist, aber nicht ausgeführt werden kann, **verweigert** die Ereignisse, die seine fehlenden Richtlinien abgedeckt hätten, anstatt sie stillschweigend zuzulassen. Siehe [Fehlerverhalten](/de/policies/failure-behavior). `failproofai pack list` benennt jedes Paket in diesem Zustand und beendet sich mit einem Fehlercode. +Ein Pack, das dieser Rechner durchsetzen soll, aber nicht ausführen kann, **verweigert** die Ereignisse, die seine fehlenden Policies abgedeckt hätten, anstatt sie still zu erlauben – als `pack/failproofai-pack-unavailable`, das den Policies, die geladen wurden, vorrangig ist, sodass die Ablehnung dem fehlenden Pack zugeordnet wird und nicht dem zufällig zuerst ausgelösten Guard. Ausnahme ist `UserPromptSubmit`, das stattdessen instruiert: Eine Ablehnung dort würde Sie vom Agenten aussperren, den Sie zur Behebung benötigen. Siehe [Fehlerverhalten](/de/policies/failure-behavior). -## Offline-Betrieb und Mirrors +## Offline und Mirrors -| Variable | Auswirkung | +| Variable | Effekt | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Verweigert das Abrufen; bereits installierte Pakete werden weiter durchgesetzt | -| `FAILPROOFAI_PACK_BASE_URL` | Leitet den Paketabruf auf einen Mirror statt auf `github.com` um | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Verweigert Downloads; bereits installierte Packs setzen weiterhin durch | +| `FAILPROOFAI_PACK_BASE_URL` | Leitet das Abrufen von Packs auf einen Mirror statt `github.com` um | -Eigenes Paket veröffentlichen: siehe [Ein Paket veröffentlichen](/de/policies/publish-a-pack). \ No newline at end of file +Informationen zur Veröffentlichung eigener Policies auf diese Weise finden Sie unter [Ein Policy-Pack veröffentlichen](/de/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/de/policies/publish-a-pack.mdx b/docs/de/policies/publish-a-pack.mdx index df8e320e..71f97a24 100644 --- a/docs/de/policies/publish-a-pack.mdx +++ b/docs/de/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "Ein Pack veröffentlichen" +title: "Ein Policy-Pack veröffentlichen" description: "Eigene Policies als GitHub-Release bereitstellen, das jeder installieren kann." icon: "upload" --- -Ein Pack besteht aus drei Dateien, die an ein GitHub-Release angehängt werden. `failproofai pack build` erzeugt alle drei aus einer bereits vorhandenen Policy-Datei. +Ein Pack besteht aus drei Dateien, die einem GitHub-Release angehängt werden. `failproofai publish` schreibt alle drei aus den vorliegenden Policy-Dateien, erstellt das Release und lädt sie hoch. ## 1. Die Policies schreiben -Eine Datei, mit derselben API wie jede andere Custom Policy. Zwei zusätzliche Felder sind für ein Pack relevant: +Fang mit etwas Funktionierendem an, nicht mit einer Vorlage voller Lücken: + +```bash +failproofai publish --init +``` + +Dieser Befehl fragt nach dem Namen des Packs, schreibt `.mjs` und hört auf — kein Netzwerk, kein Git, nichts wird veröffentlicht. Die erzeugte Datei enthält eine Policy, die `git push --force` bereits blockiert. Eine vorhandene Datei wird nicht überschrieben. + +Policies verwenden dieselbe API wie jede benutzerdefinierte Policy. Zwei zusätzliche Felder sind für ein Pack relevant: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` ist standardmäßig **false**, wenn es weggelassen wird. Ein einfaches `failproofai pack add` aktiviert nur die Policies, die du als solche markiert hast — alle Policies eines unbekannten Packs unbeaufsichtigt zu installieren ist eine Entscheidung, die der Installer nicht für seinen Nutzer treffen sollte. +`defaultEnabled` ist standardmäßig **false**, wenn es weggelassen wird. Ein einfaches `failproofai policies add` aktiviert nur die Policies, die du entsprechend markiert hast — alle Policies eines Fremden unbeaufsichtigt zu installieren ist keine Entscheidung, die der Installer für den Benutzer treffen sollte. + +Schreib so viele Dateien wie nötig; eine pro Kategorie ist gut lesbar. Jede Datei im Verzeichnis, die Policies registriert, wird in das einzelne Artefakt gebündelt, das ein Pack sein muss. -Der Eintrag muss eine **in sich geschlossene Datei** sein. Nur der Eintrag wird per Digest gesichert, daher könnte ein Pack, das lokale Dateien importiert, nicht ernsthaft behaupten, der Digest decke das ab, was tatsächlich ausgeführt wird. Bündele die Dateien zuerst (`esbuild`, `bun build`, `rollup`) und baue das Pack aus dem Bundle — `pack build` lehnt einen lokalen Import ab, anstatt ein Versprechen zu liefern, das es nicht einhalten kann. + Für das Bündeln wird **bun** benötigt. Ohne bun bleib bei einer einzigen, in sich geschlossenen Datei. In jedem Fall darf der veröffentlichte Einstiegspunkt zur Installationszeit keine lokalen Dateien importieren: Nur der Einstiegspunkt wird per Digest gesichert. Ein Pack, der auf Geschwisterdateien zugreift, könnte nicht ehrlich behaupten, der Digest decke das ab, was ausgeführt wird — und `publish` lehnt ein solches Pack ab, anstatt ein Versprechen zu liefern, das es nicht halten kann. -## 2. Die Release-Assets bauen +## 2. Erst hier testen + +Bevor es jemand anderes sehen kann, die Datei auf diesem Rechner erzwingen: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +Beliebiger Pfad, beliebiger Dateiname. Lass deinen Agenten das tun, was du blockiert hast, und beobachte, wie es abgelehnt wird. Es wird nichts veröffentlicht und niemand sonst ist betroffen. [Eine Policy testen](/de/policies/test) behandelt den Rest: den legitimen Fall, den sie erlauben muss, und die Eingaben, die sie brechen. + +## 3. Veröffentlichen + +```bash +failproofai publish ``` -Der Befehl schreibt drei Dateien und validiert jede Policy zunächst mit den **eigenen Regeln des Loaders** — damit schlägt ein Pack, das sich nie installieren ließe, hier fehl, wo du es noch beheben kannst: +Der Befehl ermittelt selbst, wo veröffentlicht werden soll, was gebündelt wird und welche Versionsnummer vergeben wird — und fragt nur nach, wenn das Repository keine Informationen liefert. Der Ablauf, der abbricht, bevor ein Release erstellt wird, wenn etwas nicht stimmt: + +1. Findet die Policy-Dateien hier nach **Inhalt** — solche, die `failproofai` importieren und `customPolicies.add` aufrufen — anstatt nach Dateiname. So findet es `guards.mjs` und ignoriert ein unverwandtes `policies.mjs`. Es steigt nicht in Unterverzeichnisse hinab, sodass ein Test-Fixture nie versehentlich erfasst wird. +2. Liest das Repo aus `git remote get-url origin` — im Verzeichnis der **Datei**, nicht in deinem — und bestimmt die Version. +3. Findet deine Zugangsdaten: `GITHUB_TOKEN`, `GH_TOKEN` oder `gh auth login`. Release-Schreibzugriff wird benötigt und nichts weiter; die Zugangsdaten werden nie ausgegeben. +4. Erstellt das Repository, falls es nicht existiert. Das geschieht vor dem Build, sodass ein im nächsten Schritt abgelehntes Pack ein neues Repository ohne Release hinterlassen kann. +5. Baut die drei Assets und validiert sie mit den **eigenen Regeln des Loaders** — demselben Code, der entscheidet, was auf einer fremden Maschine installiert werden darf — sodass ein Pack, das sich nie installieren ließe, hier scheitert, wo du es noch beheben kannst. +6. Erstellt oder verwendet das Release erneut und lädt hoch, wobei Assets gleichen Namens ersetzt werden. -| Datei | Beschreibung | +| Datei | Inhalt | | --- | --- | | `failproofai-pack.json` | Das Manifest: ID, Version, Effekt und ein Eintrag pro Policy | -| `failproofai-pack.mjs` | Dein Eintrag, unverändert | -| `SHA256SUMS` | ` ` für die anderen beiden Dateien | +| `failproofai-pack.mjs` | Dein gebündelter Einstiegspunkt | +| `SHA256SUMS` | ` ` für die anderen beiden | -Beim Build abgelehnt werden: eine ID, die nicht dem Format `publisher/name` entspricht, ein Policy-Name mit `/`, eine Policy, die `alwaysOn` deklariert, eine fehlende `description`, `category` oder `match`, ein Eintrag, der nichts registriert, und ein Eintrag, der lokale Dateien importiert. +Die Asset-Namen sind fest vorgegeben — sie sind das, woraus die CLI eines Verbrauchers seine URLs konstruiert, ohne API-Aufruf und ohne Discovery. -## 3. An ein Release anhängen +Beim Build abgelehnt wird: eine ID, die nicht `publisher/name` entspricht, ein Policy-Name mit `/`, eine Policy, die `alwaysOn` deklariert, eine fehlende `description`, `category` oder `match`, ein Einstiegspunkt, der nichts registriert, und ein Einstiegspunkt, der lokale Dateien importiert. -Tagge das Release mit derselben Version, die du beim Build angegeben hast, und füge alle drei Dateien als Release-Assets hinzu: +Alles Entschiedene lässt sich überschreiben: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -Jetzt kann jeder das Pack installieren: +`--id` setzt die Pack-ID, wenn sie vom Repo abweichen soll; `--tag` setzt den Tag des Releases; `--notes` ersetzt die generierten Release-Notes — aus denen `policies show --releases` die Anzahl und den Commit jedes Releases liest; `--out` legt fest, wohin die Assets geschrieben werden (Standard: `dist-pack`); und `--dry-run` baut sie, ohne zu veröffentlichen, und benötigt keine Zugangsdaten. -```bash -failproofai pack add acme/support-agent -``` +Jetzt kann jeder es mit `failproofai policies add acme/support-agent` installieren. Siehe [Policy-Packs](/de/policies/packs) zum Pinnen einer Version und zum Übernehmen nur eines Teils davon. + +### Im Policy-Hub listen -Die Asset-Namen sind fest vorgegeben — aus ihnen baut die CLI des Consumers die URLs, ohne API-Aufruf und ohne Erkennung. +Füge dem Repository auf GitHub das Topic `failproofai-policies` hinzu. Es gibt kein Einreichungsformular und keine Genehmigungswarteschlange: Der Crawler des [Policy-Hubs](https://befailproof.ai/policy-hub/) nimmt das Repository beim nächsten Durchlauf auf. Das Topic stellt es nur zur Aufnahme bereit — was es listet, ist ein Release, dessen Manifest gegen seine eigene `SHA256SUMS` verifiziert und nach denselben Regeln geparst wird, die die CLI verwendet — genau das, was `failproofai publish` erzeugt. -## Eine neue Version veröffentlichen +## Wie die Version bestimmt wird -Baue mit der neuen `--version`, tagge ein neues Release und hänge die drei Assets erneut an. Consumers führen dasselbe `pack add` aus und behalten die Auswahl, die sie getroffen hatten; eine deaktivierte Policy bleibt auch nach dem Upgrade deaktiviert. +Die Version ist der **Commit, von dem aus veröffentlicht wird** — sein kurzes SHA, zwölf Zeichen: `a1b2c3d4e5f6`. Es gibt nichts auszuwählen und nichts zu inkrementieren, und die Version benennt genau, woher die Bytes stammen — dasselbe Quell-Commit zweimal zu veröffentlichen ergibt dieselbe Version. -Den **Namen** einer Policy zu ändern ist ein Breaking Change: Eine Maschine, die ihn deaktiviert hatte, deaktiviert nun einen Namen, der nicht mehr existiert — und der neue Name wird mit dem Wert aus `defaultEnabled` aktiviert. +Sie wird aus dem aktuellen Verzeichnisbaum gelesen, nie aus den Releases des Repositories, sodass ein frischer Clone und eine Air-Gapped-Maschine dieselbe Antwort berechnen, ohne GitHub nach dem Vorherigen zu fragen. + +Da die Version einen Commit benennt, muss dieser Commit existieren. An einem Terminal erstellt `publish` ihn für dich: Es initialisiert ein Repository, wenn keines vorhanden ist, und committet geänderte Policy-Dateien, bevor es baut. Es **verweigert** die Aktion stattdessen — mit `--version` als Ausweg — wenn es ohne Terminal läuft (ein auf einem CI-Runner erstellter Commit würde sonst nirgendwo anders existieren), wenn andere Dateien als die Policies uncommitted sind oder in einem Checkout ohne Commits. Ein Tag auf `HEAD` hat Vorrang vor dem SHA — wer `v1.2.0` getaggt hat, hat gesagt, was dieses Release ist. + +Ein SHA trägt keine eigene Reihenfolge, also verwende `failproofai policies show / --releases`, um zu sehen, welches Release zuerst kam — neuestes oben. + +## Eine neue Version liefern + +Die Änderung committen und `failproofai publish` erneut ausführen — der neue Commit ist die neue Version. Verbraucher führen dasselbe `failproofai policies add` aus. Ohne Terminal oder mit einem Auswahlparameter behalten sie die Teilmenge, die sie gewählt hatten, und eine deaktivierte Policy bleibt deaktiviert; an einem Terminal ohne Parameter öffnet sich der Picker mit deinen Standardwerten vorausgewählt, und ihre Antwort ersetzt ihre bisherige Auswahl. + +Das **Umbenennen** einer Policy ist eine Breaking Change: Eine Maschine, die sie deaktiviert hatte, deaktiviert nun einen Namen, der nicht mehr existiert, und der neue Name wird mit dem Wert von `defaultEnabled` übernommen. ## Was deine Nutzer vertrauen -`SHA256SUMS` liegt im selben Release wie das Artefakt und beweist damit, dass die Bytes genau die sind, die du veröffentlicht hast — nicht wer du bist. Wer Schreibzugriff auf das Repository hat, kann beide Dateien schreiben. Der Schutz für deine Nutzer besteht darin, dass der Digest beim Installieren fest eingespeichert wird — was du geliefert hast, kann sich danach nicht mehr unter ihnen ändern. +`SHA256SUMS` liegt im selben Release wie das Artefakt und beweist damit, dass die Bytes die sind, die du veröffentlicht hast — nicht wer du bist. Wer Schreibzugriff auf das Repository hat, kann beide Dateien schreiben. Der Schutz deiner Nutzer liegt darin, dass der Digest beim Installieren gepinnt wird — was du geliefert hast, kann sich danach nicht unter ihnen ändern. + +Veröffentliche aus einem Repository, dessen Schreibzugriff du kontrollierst, und behandle ein Pack-Release wie das Veröffentlichen eines Pakets. -Veröffentliche aus einem Repository, dessen Schreibzugriff du kontrollierst, und behandle ein Pack-Release wie die Veröffentlichung eines Pakets. +Das Repository muss außerdem **öffentlich** sein. Installationen sind anonymes HTTPS ohne Zugangsdaten, daher wird ein bestehendes privates Repo abgelehnt, bevor etwas gebaut oder hochgeladen wird — und ein von `publish` erstelltes Repository ist aus demselben Grund öffentlich. `--allow-private` überschreibt das für jemanden, der die drei Assets auf anderem Weg weitergibt, und macht deutlich, dass kein `policies add` sie erreichen kann. Nur das Release ist relevant: Installationen lesen `releases/download//` und berühren deinen Git-Tree nie. ## Beobachten, bevor du durchsetzt -Ein Manifest kann `"effect": "observe"` deklarieren. Diese Policies laufen, und ihre Urteile werden **aufgezeichnet und verworfen** — es wird nichts blockiert. Das ist der Weg, eine neue Regel gegen echten Traffic zu messen, bevor sie die Arbeit von jemandem unterbrechen kann. +Ein Manifest kann `"effect": "observe"` deklarieren — gesetzt wird das mit `failproofai publish --effect observe`. Diese Policies laufen und ihre Urteile werden **aufgezeichnet und verworfen** — nichts wird blockiert. So lässt sich eine neue Regel gegen echten Traffic messen, bevor sie die Arbeit irgendjemanden unterbrechen kann. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/de/policies/rollback.mdx b/docs/de/policies/rollback.mdx index 8bb5bee0..5be42ad0 100644 --- a/docs/de/policies/rollback.mdx +++ b/docs/de/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "Rollback" -description: "Einen bekannten Policy-Deployment-Zustand wiederherstellen, wenn ein Rollout gültige Agent-Arbeit unterbricht." +title: "Versionen und Rollback" +description: "Jede Veröffentlichung ist eine unveränderliche Version, sodass ein Rollout, der gültige Agenten-Arbeit beeinträchtigt, durch erneutes Bereitstellen der letzten funktionierenden Version rückgängig gemacht werden kann." icon: "rotate-ccw" --- -Rollback ändert die bereitgestellte Version oder entfernt eine Policy-Zuweisung; die Entscheidungshistorie, die den Vorfall erklärt, wird dabei nicht gelöscht. +Eine veröffentlichte Richtlinienversion ändert sich nie. Das Bearbeiten einer Richtlinie und erneute Veröffentlichen erstellt eine neue Version; die bereits auf Maschinen vorhandene Version wird dabei nie überschrieben. Das macht Rollbacks sicher: Die letzte funktionierende Version ist noch vorhanden, Byte für Byte, und ein Rollback löscht nicht den Entscheidungsverlauf, der erklärt, was schiefgelaufen ist. -## Eine Maschine zurücksetzen +## Eine Version finden - 1. Gehen Sie zu **Admin → enforcement**, erweitern Sie die betroffene Maschine und identifizieren Sie das zuletzt bekannte funktionierende Policy-Set. - 2. Wählen Sie **edit**, stellen Sie die entsprechenden Versionen und Effekte wieder her und wenden Sie das neue Deployment an. - 3. Warten Sie auf den Check-in der Maschine und überprüfen Sie dann das gemeldete Deployment. - 4. Öffnen Sie **Observe → policy** und die betroffenen Sessions, um zu bestätigen, dass gültige Arbeit nicht länger blockiert wird. + Gehe zu **Admin → Richtlinien-Editor** und öffne die **Bibliothek**, um Versionen einer Richtlinie zu vergleichen oder eine zu deaktivieren. + + + ```bash + fp policies list # every policy version + fp policies show # one version, with its source + ``` + + +## Rollback einer Maschine + + + + 1. Gehe zu **Admin → Durchsetzung**, erweitere die betroffene Maschine und identifiziere ihren zuletzt als gut bekannten Richtliniensatz. + 2. Wähle **Bearbeiten**, stelle diese Versionen und Effekte wieder her und wende das neue Deployment an. + 3. Warte auf den Check-in der Maschine und verifiziere dann das gemeldete Deployment. + 4. Öffne **Beobachten → Richtlinie** und die betroffenen Sitzungen, um zu bestätigen, dass gültige Arbeit nicht länger blockiert wird. - Der Rollback eines Cloud-Deployments ist ein Dashboard-Workflow. Verwenden Sie den lokalen Status, um zu bestätigen, dass das korrigierte Deployment die Maschine erreicht hat: + Jedes Deployment auf einer Maschine ist eine nummerierte Generation. Liste sie auf und stelle dann eine davon wieder her: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` pausiert eingebaute, benutzerdefinierte und konventionsbasierte Policies für eine lokale Session. Cloud-verwaltete Policies werden dadurch nicht pausiert – es handelt sich also nicht um eine Umgehungslösung für ein fehlerhaftes Cloud-Deployment. + `rollback` erstellt eine neue Generation mit dem alten Satz, anstatt den Zähler zurückzusetzen, sodass der Verlauf nur erweiterbar bleibt. Es lehnt eine Generation ab, die eine inzwischen deaktivierte oder gelöschte Richtlinie benennt. Der Befehl benötigt eine angemeldete Sitzung mit `policies:write`. `fp fleet diff ` zeigt den Unterschied zwischen dem Beabsichtigten und dem, was die Maschine tatsächlich angewendet hat — der Status erscheint als `behind`, bis die Maschine das nächste Mal abfragt. Auf der Maschine selbst listet `failproofai policies` das aktuell laufende Deployment auf. +## Eine Richtlinie von allen Maschinen entfernen + +```bash +fp policies disable # remove it from every deployment carrying it +fp policies enable # add it back +``` + +Jeder dieser Befehle erstellt eine neue Generation für jedes betroffene Deployment. Das Zurückrollen einer dieser Generationen ist jedoch nicht der Weg, ein `disable` rückgängig zu machen — `rollback` lehnt eine Generation ab, die eine deaktivierte Richtlinie benennt, und jede Generation vor dem Deaktivieren verweist auf diese. `fp policies enable` ist der richtige Weg zurück, und er erstellt seinerseits eine eigene neue Generation. + +## Rollback eines Pakets + +Ein Paket ist an das installierte Release gebunden; ein Rollback bedeutet daher die Installation eines früheren Releases: + +```bash +failproofai policies show FailproofAI/policies --releases # every version it has published, and which one is here +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # pin that one +``` + +Ohne Terminal oder mit `--policy`, `--category` oder `--all` behält das erneute Hinzufügen die zuvor gewählte Teilmenge. Im Terminal ohne diese Optionen öffnet sich die Auswahl mit den Standardeinstellungen des Autors vorausgewählt, und die getroffene Auswahl ersetzt die vorherige — daher die bisherige Auswahl erneut bestätigen. + ## Wann ein Rollback sinnvoll ist -- Eine Policy blockiert eine erwartete Produktionsaktion. -- Das Match-Volumen ist deutlich höher als beim beobachteten Rollout prognostiziert. -- Eine Policy ist von Feldern abhängig, die eine Integration nicht bereitstellt. -- Eine neue Version ändert das Verhalten außerhalb des beabsichtigten Failure-Modes. +- Eine Richtlinie blockiert eine erwartete Produktionsaktion. +- Das Übereinstimmungsvolumen ist erheblich höher als der beobachtete Rollout vorhergesagt hat. +- Eine Richtlinie ist abhängig von Feldern, die eine Integration nicht bereitstellt. +- Eine neue Version ändert das Verhalten außerhalb des vorgesehenen Fehlerfalls. -Öffnen Sie nach dem Rollback die betroffenen Sessions und identifizieren Sie die Bedingung, die das False Positive verursacht hat. Erstellen Sie eine neue Version, testen Sie sowohl den unsicheren als auch den legitimen Fall und wiederholen Sie anschließend die Observe-Phase. +Nach einem Rollback die betroffenen Sitzungen öffnen und die Ursache des False Positives ermitteln. Eine neue Version veröffentlichen, [testen](/de/policies/test) — sowohl den unsicheren als auch den legitimen Fall — und erneut beobachten, bevor die Durchsetzung aktiviert wird. - Das Pausieren der Enforcement kann bei einem Vorfall angebracht sein, weitet jedoch die Angriffsfläche für jede aktive Policy in diesem Scope aus. Bevorzugen Sie nach Möglichkeit den Rollback der spezifischen Policy-Version. + `failproofai config --pause` pausiert lokale Richtlinien für eine Sitzung, jedoch niemals Cloud-verwaltete. Es ist daher kein Ausweg aus einem fehlerhaften Cloud-Deployment. Eine Pause weitet außerdem die Angriffsfläche für alle Richtlinien in ihrem Geltungsbereich aus; es ist vorzuziehen, die eine fehlerhafte Version zurückzurollen. \ No newline at end of file diff --git a/docs/de/policies/test.mdx b/docs/de/policies/test.mdx new file mode 100644 index 00000000..a27fa4fe --- /dev/null +++ b/docs/de/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "Eine Policy testen" +description: "Führe einen Backtest eines Entwurfs gegen vorhandenen Traffic durch und beweise, dass er stoppt, was gestoppt werden soll, und zulässt, was durchgehen muss – bevor eine Maschine ihn durchsetzt." +icon: "flask-conical" +--- + +Teste jede Policy auf zwei Arten: gegen den Traffic, den deine Agents bereits erzeugt haben, und gegen eine legitime Aktion, die durchgelassen werden muss. Eine Policy, die nur den unsicheren Fall gesehen hat, wurde nicht ausreichend getestet. + +## Den Entwurf einem Backtest unterziehen + + + + Der Policy-Editor spielt einen Entwurf gegen Aufrufe zurück, die deine Flotte bereits gemacht hat – bevor du ihn veröffentlichst. + + 1. Öffne den Entwurf unter **Admin → Policy-Editor**. Der Editor bestätigt, dass er als JavaScript geparst wird. + 2. Wähle im Bereich **Backtest** die Agents und das Zeitfenster für die Wiedergabe – standardmäßig **alle Agents** und **30 Tage** – und lasse den letzten Filter auf **alles**, es sei denn, du möchtest die Auswahl eingrenzen. + 3. Wähle **Backtest ausführen**. + + ![Das Backtest-Panel unter einem Entwurf, der als JavaScript geparst wird, mit den drei Filtern und der Aktion „Backtest ausführen", oberhalb von „Version veröffentlichen".](/images/dashboard/policy-backtest.png) + + Das Ergebnis zeigt, was der Entwurf mit diesen Aufrufen gemacht hätte – einschließlich der Anzahl **funktionierender** Aufrufe, die er unterbrochen hätte. Das sind False Positives, die gefunden werden, bevor ein Agent auf sie trifft: Verfeinere den Entwurf und führe den Test erneut aus, bis diese Zahl akzeptabel ist. + + + Backtesting ist eine Dashboard-Funktion. Führe die Policy stattdessen über ein Terminal gegen selbst beschriebene Events aus (siehe unten). + + + +## Gegen ein selbst beschriebenes Event ausführen + +`fp policies test` führt eine Policy-Datei auf deinem Rechner gegen ein synthetisches Event aus und prüft die Entscheidung. Es wird nichts veröffentlicht und nichts erreicht die Cloud: + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +Forme das Event mit `--event`, `--tool`, `--command` und `--file`. Der eigene `match`-Filter der Policy greift weiterhin, sodass eine Policy, die das beschriebene Event nicht abdeckt, `skipped` statt einer Entscheidung zurückgibt – in der Regel ein Zeichen dafür, dass ihr `match` enger ist als beabsichtigt. + +## Auf einem Rechner ausführen + +Setze sie als Nächstes auf deinem eigenen Rechner gegen deinen eigenen Agent durch: + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +Der erste Befehl validiert und installiert die Datei; der zweite bestätigt, dass sie geladen wurde – zusammen mit allem anderen, was hier durchgesetzt wird. Bitte den Agent, das zu tun, was die Policy stoppt, und beobachte, wie es abgelehnt wird; führe dann die legitime Version durch und beobachte, wie sie durchgeht. Niemand sonst wird beeinträchtigt. + +Prüfe auf einem mit der Cloud verbundenen Rechner beide Entscheidungen unter **Observe → Policy**: Filtere nach dem Policy-Namen und öffne dann jede verknüpfte Session, um den übereinstimmenden Tool-Input und den zurückgegebenen Grund zu bestätigen. + +## Testen, was Fehler verursacht + +Die Installation verweigert eine fehlende Datei, einen Syntaxfehler, einen unaufgelösten Import, eine Ausnahme auf oberster Ebene oder ein Modul, das beim Laden das Zeitlimit überschreitet – führe die Installation daher nach jeder Änderung an der Datei oder allem, was sie importiert, erneut aus. Zum Zeitpunkt der Durchsetzung wird dieselbe fehlerhafte Datei protokolliert und **übersprungen**, sodass alle anderen Policies weiter ausgeführt werden: Behandle eine Load-Warnung in Produktions-Logs als verlorene Durchsetzung. Convention-Dateien laden ohne den Installationsbefehl, daher füge in CI einen expliziten `failproofai policies --install --custom `-Schritt ein – dieser lässt den Build bei einer fehlerhaften Policy fehlschlagen. + +Speise danach das ein, was Agents tatsächlich senden, nicht nur den erwarteten Input: fehlende Felder, alternative Tool-Namen wie `Write` und `Edit`, Windows-Pfade, fehlerhaften Input. Gib auf jedem Pfad ein bewusstes `allow`, `instruct` oder `deny` zurück, halte die Funktion deterministisch und begrenze jeden externen Aufruf mit einem kurzen Timeout. + +## Dann veröffentlichen und beobachten + +Ein Backtest zeigt, was die Policy mit dem vorhandenen Traffic gemacht hätte; er kann nicht zeigen, was noch nicht gesehener Traffic auslösen wird. Wähle **Version veröffentlichen** im Editor (oder führe `fp policies publish` aus), dann [stelle sie](/de/policies/deploy) zunächst im **Observe**-Modus bereit – ihre Urteile werden aufgezeichnet und nichts wird blockiert – und setze sie durch, sobald ihre Treffer unsichere Aktionen von gültigen trennen. \ No newline at end of file diff --git a/docs/de/reference/cloud-cli.mdx b/docs/de/reference/cloud-cli.mdx index 45b4e853..25d68abb 100644 --- a/docs/de/reference/cloud-cli.mdx +++ b/docs/de/reference/cloud-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof Cloud CLI" -description: "Vollständige Referenz für Abfragen und Verwaltung von Failproof AI Cloud mit fp." +description: "Vollständige Referenz zur Abfrage und Verwaltung von Failproof AI Cloud mit fp." icon: "cloud-cog" --- -Verwende `fp`, um Cloud-Telemetrie einzusehen, cloud-verwaltete Durchsetzung (Richtlinien, Fleet-Deployments, Guardrail-Entscheidungen) zu verwalten sowie Audits, Befunde, Issues, Warnungen, Schlüssel, Benutzer, Abfragen und Einstellungen zu administrieren. Verwende [`failproofai`](/de/reference/failproof-cli) für lokale Hooks, Richtlinien, Erfassung und Machine-Enrollment. +Verwende `fp` zum Überprüfen von Cloud-Telemetrie, zur Verwaltung von cloud-gesteuerter Durchsetzung (Richtlinien, Fleet-Deployments, Guardrail-Entscheidungen) sowie zur Verwaltung von Audits, Findings, Issues, Alerts, Schlüsseln, Benutzern, Abfragen und Einstellungen. Verwende [`failproofai`](/de/reference/failproof-cli) für lokale Hooks, Richtlinien, Capture und Machine-Enrollment. -Installiere die veröffentlichte Cloud CLI als isoliertes Werkzeug: +Installiere das veröffentlichte Cloud CLI als isoliertes Tool: ```bash uv tool install fp-cloud-cli @@ -26,13 +26,13 @@ fp whoami fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` -Globale Optionen müssen vor dem Befehl stehen: +Globale Optionen müssen vor dem Befehl angegeben werden: ```bash fp --json sessions --since 24h ``` -Führe `fp COMMAND --help` oder `fp COMMAND SUBCOMMAND --help` für Hilfe im Terminal aus. +Führe `fp COMMAND --help` oder `fp COMMAND SUBCOMMAND --help` aus, um die Terminalhi­lfe anzuzeigen. ## CLI-Befehle @@ -40,11 +40,11 @@ Führe `fp COMMAND --help` oder `fp COMMAND SUBCOMMAND --help` für Hilfe im Ter | Befehl | Zweck | Optionen | | --- | --- | --- | -| `fp login` | Anmelden mit einem per E-Mail zugesandten Einmalcode und Auswahl einer Organisation. | `--email`, `-e`; `--org`; `--force` | +| `fp login` | Anmeldung mit einem per E-Mail zugesandten Einmalcode und Auswahl einer Organisation. | `--email`, `-e`; `--org`; `--force` | | `fp logout` | Gespeicherte Benutzersitzung widerrufen und entfernen. | — | | `fp whoami` | Aktuelle Identität, Authentifizierungsmodus, Organisation und Berechtigungen anzeigen. | — | | `fp version` | Installierte CLI-Version anzeigen. | — | -| `fp help` | Hilfe zu Befehlen der obersten Ebene anzeigen. | — | +| `fp help` | Hilfe zu den Befehlen der obersten Ebene anzeigen. | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,23 +57,23 @@ fp whoami fp events [OPTIONS] ``` -Listet einzelne Agent-Events auf. Der standardmäßige Light-Feed schließt rohe Payloads aus; verwende `--full` nur für eine eingegrenzte Untersuchung. +Listet einzelne Agent-Events auf. Der Standard-Light-Feed schließt rohe Payloads aus; verwende `--full` nur für abgegrenzte Untersuchungen. | Option | Beschreibung | | --- | --- | -| `--limit`, `-n ` | Maximale Gesamtzahl an Zeilen. Standard: `50`. | +| `--limit`, `-n ` | Maximale Gesamtanzahl an Zeilen. Standard: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` oder `7d`. | | `--from ` / `--to ` | ISO 8601 UTC-Bereich; überschreibt `--since`. | -| `--env ` | Umgebungsfilter; Werte wiederholen oder kommagetrennt angeben. | -| `--event-type ` | Event-Typ-Filter; Werte wiederholen oder kommagetrennt angeben. | -| `--agent-id ` | Agent-Filter; Werte wiederholen oder kommagetrennt angeben. | -| `--session-id ` | Sitzungsfilter; Werte wiederholen oder kommagetrennt angeben. | -| `--search ` | Volltextsuche in Payloads; wiederholbar, ein beliebiger Begriff muss übereinstimmen. | -| `--order asc\|desc` | Zeitreihenfolge. Standard: neueste zuerst. | -| `--all` | Automatisch bis zu `--limit` paginieren. | -| `--cursor ` | Von einem undurchsichtigen Cursor fortsetzen. | -| `--page-size ` | Zeilen pro Anfrage bei `--all`; maximal `200`. | -| `--full` | Rohe Payloads über den schwereren Event-Endpunkt einschließen. | +| `--env ` | Umgebungsfilter; wiederholbar oder durch Komma getrennt. | +| `--event-type ` | Event-Typ-Filter; wiederholbar oder durch Komma getrennt. | +| `--agent-id ` | Agent-Filter; wiederholbar oder durch Komma getrennt. | +| `--session-id ` | Session-Filter; wiederholbar oder durch Komma getrennt. | +| `--search ` | Payload-Textsuche; wiederholbar, ein beliebiger Begriff reicht für einen Treffer. | +| `--order asc\|desc` | Zeitliche Sortierung. Standard: neueste zuerst. | +| `--all` | Automatische Paginierung bis zu `--limit`. | +| `--cursor ` | Fortsetzung ab einem opaken Cursor. | +| `--page-size ` | Zeilen pro Anfrage mit `--all`; maximal `200`. | +| `--full` | Rohe Payloads über den aufwändigeren Event-Endpunkt einbeziehen. | | `--fields ` | Nur ausgewählte Felder zurückgeben; bei Anforderung von `payload` wird der Full-Modus aktiviert. | ```bash @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` paginiert **bis zu `--limit`**, was standardmäßig **50** beträgt — `--all` allein stoppt also bei 50 Zeilen. Wenn es vorzeitig stoppt, enthält die Antwort einen `next_cursor` zum Fortsetzen; `"next_cursor": null` bedeutet, dass der Feed tatsächlich erschöpft war. + `--all` paginiert **bis zu `--limit`**, was standardmäßig **50** ist — `--all` allein stoppt also bei 50 Zeilen. Wenn es vorzeitig stoppt, enthält die Antwort einen `next_cursor` zum Fortsetzen; `"next_cursor": null` bedeutet, dass der Feed tatsächlich vollständig verarbeitet wurde. ### Sessions @@ -93,19 +93,19 @@ fp sessions [OPTIONS] | Option | Beschreibung | | --- | --- | -| `--limit`, `-n ` | Maximale Gesamtzahl an Zeilen. Standard: `50`. | +| `--limit`, `-n ` | Maximale Gesamtanzahl an Zeilen. Standard: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` oder `7d`. | | `--from ` / `--to ` | ISO 8601 UTC-Bereich; überschreibt `--since`. | -| `--env ` | Umgebungsfilter; Werte wiederholen oder kommagetrennt angeben. | -| `--status ` | `done`, `error` oder `timeout`; Werte wiederholen oder kommagetrennt angeben. | -| `--agent-id ` | Sitzungen mit einem der ausgewählten Agenten abgleichen. | -| `--session-id ` | Sitzungsfilter; Werte wiederholen oder kommagetrennt angeben. | -| `--all` | Automatisch bis zu `--limit` paginieren. | -| `--cursor ` | Von einem undurchsichtigen Cursor fortsetzen. | -| `--page-size ` | Zeilen pro Anfrage bei `--all`; maximal `200`. | +| `--env ` | Umgebungsfilter; wiederholbar oder durch Komma getrennt. | +| `--status ` | `done`, `error` oder `timeout`; wiederholbar oder durch Komma getrennt. | +| `--agent-id ` | Sessions mit einem der ausgewählten Agents abgleichen. | +| `--session-id ` | Session-Filter; wiederholbar oder durch Komma getrennt. | +| `--all` | Automatische Paginierung bis zu `--limit`. | +| `--cursor ` | Fortsetzung ab einem opaken Cursor. | +| `--page-size ` | Zeilen pro Anfrage mit `--all`; maximal `200`. | | `--fields ` | Nur ausgewählte Felder zurückgeben. | -| `--full-ids` | Sitzungs-IDs in der Terminalausgabe nicht kürzen. | -| `--agents` | Agentenliste für Multi-Agenten-Sitzungen erweitern. | +| `--full-ids` | Session-IDs in der Terminalausgabe nicht kürzen. | +| `--agents` | Die Agentenliste für Multi-Agent-Sessions erweitern. | ### Evaluierungen @@ -122,7 +122,7 @@ fp evals [OPTIONS] | `--score KEY:MIN..MAX` | Score-Bereich; wiederholbar, alle Bereiche müssen übereinstimmen. | | `--all`, `--cursor`, `--page-size` | Listenpaginierung steuern. | | `--fields ` | Nur ausgewählte Felder zurückgeben. | -| `--full-ids` | Vollständige Sitzungs-IDs anzeigen. | +| `--full-ids` | Vollständige Session-IDs anzeigen. | | `--scores-full` | Alle Scores in der Terminalausgabe anzeigen. | ### Fehler @@ -133,15 +133,15 @@ fp errors [OPTIONS] | Option | Beschreibung | | --- | --- | -| `--aggregate` | Übereinstimmende Fehler zusammenfassen statt Zeilen aufzulisten. | +| `--aggregate` | Übereinstimmende Fehler zusammenfassen anstatt Zeilen aufzulisten. | | `--limit`, `-n ` | Maximale Listenzeilen. Standard: `50`. | | `--since`, `--from`, `--to` | Zeitbereich auswählen. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Fehlermenge einschränken. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Die Fehlermenge eingrenzen. | | `--search ` | Payload-Text durchsuchen; wiederholbar. | -| `--order asc\|desc` | Zeitreihenfolge. | +| `--order asc\|desc` | Zeitliche Sortierung. | | `--all`, `--cursor`, `--page-size` | Listenpaginierung steuern. | | `--fields ` | Nur ausgewählte Felder zurückgeben. | -| `--full-ids` | Vollständige Sitzungs-IDs anzeigen. | +| `--full-ids` | Vollständige Session-IDs anzeigen. | ### Nutzung und Filterwerte @@ -151,7 +151,7 @@ fp errors [OPTIONS] | `fp list envs` | Beobachtete Umgebungen auflisten. | | `fp list agents` | Beobachtete Agent-IDs auflisten. | | `fp list event_types` | Event-Typen auflisten. | -| `fp list score_filters` | Evaluierungsscore-Schlüssel auflisten. | +| `fp list score_filters` | Evaluierungs-Score-Schlüssel auflisten. | | `fp list models` | Modellnamen auflisten. | | `fp list hooks` | Hook-Namen auflisten. | | `fp list tools` | Tool-Namen auflisten. | @@ -162,7 +162,7 @@ fp errors [OPTIONS] | Befehl | Zweck | | --- | --- | | `fp orgs list` | Zugängliche Organisationen auflisten. | -| `fp orgs switch [SLUG]` | Aktive Organisation speichern; bei Auslassung wird nachgefragt. | +| `fp orgs switch [SLUG]` | Aktive Organisation speichern; fragt nach, wenn weggelassen. | | `fp orgs current` | Aktive Organisation anzeigen. | | `fp orgs perms` | Eigene Berechtigungen in der aktiven Organisation anzeigen. | @@ -171,13 +171,13 @@ fp errors [OPTIONS] | Befehl | Zweck | Optionen | | --- | --- | --- | | `fp keys list` | Organisationsschlüssel auflisten. | `--show-id`; `--fields ` | -| `fp keys show NAME` | Einen Schlüssel und seine Berechtigungen anzeigen. | — | -| `fp keys create NAME` | Einen Schlüssel erstellen und sein Geheimnis einmalig anzeigen. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | Das Berechtigungs-Set ersetzen oder Berechtigungen anpassen. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | Das Geheimnis rotieren und den Ersatz einmalig anzeigen. | `--yes`, `-y` | +| `fp keys show NAME` | Einen Schlüssel und seine Grants anzeigen. | — | +| `fp keys create NAME` | Einen Schlüssel erstellen und sein Secret einmalig anzeigen. | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | Den Permission-Set ersetzen oder Grants anpassen. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | Das Secret rotieren und den Ersatz einmalig anzeigen. | `--yes`, `-y` | | `fp keys disable NAME` | Einen Schlüssel dauerhaft widerrufen. | `--yes`, `-y` | -Berechtigungs-Tokens verwenden `resource:action`, z. B. `events:add`. Wiederhole `--add`, trenne Tokens durch Kommas oder verwende gepunktete Aktionen wie `events:read.add`. +Berechtigungs-Tokens verwenden `resource:action`, z. B. `events:add`. Wiederhole `--add`, trenne Tokens durch Komma, oder verwende gepunktete Aktionen wie `events:read.add`. ### Abfragen @@ -189,16 +189,16 @@ Berechtigungs-Tokens verwenden `resource:action`, z. B. `events:add`. Wiederhole | `fp query update NAME` | Eine Abfrage aktualisieren oder umbenennen. | `--name`; `--sql`; `--description`; `--yes`, `-y` | | `fp query delete NAME` | Eine gespeicherte Abfrage löschen. | `--yes`, `-y` | | `fp query run [NAME]` | Eine gespeicherte Abfrage oder Ad-hoc-SQL ausführen. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | Abfragbare Tabellen auflisten oder eine Tabelle untersuchen. | — | +| `fp query schema [TABLE]` | Abfragbare Tabellen auflisten oder eine Tabelle inspizieren. | — | ### Benutzer | Befehl | Zweck | Optionen | | --- | --- | --- | | `fp users list` | Organisationsmitglieder auflisten. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | Ein Mitglied und seine Berechtigungen anzeigen. | — | +| `fp users show EMAIL` | Ein Mitglied und seine Grants anzeigen. | — | | `fp users create EMAIL` | Ein Mitglied hinzufügen. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | Die Berechtigungen eines Mitglieds ändern. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users update EMAIL` | Grants eines Mitglieds ändern. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | | `fp users disable EMAIL` | Anmeldung deaktivieren. | `--yes`, `-y` | | `fp users enable EMAIL` | Anmeldung wieder aktivieren. | `--yes`, `-y` | @@ -210,41 +210,41 @@ Berechtigungs-Tokens verwenden `resource:action`, z. B. `events:add`. Wiederhole | `fp settings schema` | Akzeptierte Werte und Beschreibungen anzeigen. | — | | `fp settings set KEY` | Eine vorhandene Einstellung ändern. | genau eine von `--value`, `--json-value`, `--file`; optional `--yes`, `-y` | -### Warnungen +### Alerts | Befehl | Zweck | Optionen | | --- | --- | --- | -| `fp alerts list` | Warnungsregeln auflisten. | `--show-id` | -| `fp alerts show NAME` | Eine Warnung anzeigen. | — | -| `fp alerts create NAME` | Eine Warnung erstellen. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | Eine Warnung aktualisieren oder umbenennen. | Erstellungsoptionen plus `--name`; `--yes`, `-y` | -| `fp alerts delete NAME` | Eine Warnung löschen. | `--yes`, `-y` | +| `fp alerts list` | Alert-Regeln auflisten. | `--show-id` | +| `fp alerts show NAME` | Einen Alert anzeigen. | — | +| `fp alerts create NAME` | Einen Alert erstellen. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | +| `fp alerts update NAME` | Einen Alert aktualisieren oder umbenennen. | Erstellungsoptionen plus `--name`; `--yes`, `-y` | +| `fp alerts delete NAME` | Einen Alert löschen. | `--yes`, `-y` | | `fp alerts test NAME` | Eine Testbenachrichtigung senden. | `--channels`; `--yes`, `-y` | -Warnungsschweregrade sind `info`, `warning` und `critical`. Trigger-Arten sind `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` und `per_event`. Evaluierungsintervalle müssen zwischen 30 und 86.400 Sekunden liegen. +Alert-Schweregrade sind `info`, `warning` und `critical`. Trigger-Arten sind `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` und `per_event`. Evaluierungsintervalle müssen zwischen 30 und 86.400 Sekunden liegen. ### Audits | Befehl | Zweck | Optionen | | --- | --- | --- | | `fp audits list` | Audits auflisten. | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | Eine Audit-Definition und ihren Zustand anzeigen. | — | -| `fp audits create NAME` | Ein Audit erstellen und sofort dessen ersten Lauf in die Warteschlange stellen. | Siehe [Erstellungsoptionen](#audit-create-options). | -| `fp audits edit NAME` | Audit-Einstellungen ersetzen, wobei nicht angegebene Werte beibehalten werden. | Definitionsoptionen zur Erstellung; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | Ein Audit, seine Befunde und den Ausführungsverlauf löschen. | `--yes`, `-y` | -| `fp audits run NAME` | Einen manuellen Lauf in die Warteschlange stellen. | — | +| `fp audits show NAME` | Eine Audit-Definition und ihren Status anzeigen. | — | +| `fp audits create NAME` | Einen Audit erstellen und sofort seinen ersten Durchlauf einreihen. | Siehe [Erstellungsoptionen](#audit-create-options). | +| `fp audits edit NAME` | Audit-Einstellungen ersetzen, ohne nicht angegebene Werte zu verändern. | Definitionsoptionen für die Erstellung; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | Einen Audit, seine Findings und den Ausführungsverlauf löschen. | `--yes`, `-y` | +| `fp audits run NAME` | Einen manuellen Durchlauf einreihen. | — | | `fp audits runs NAME` | Ausführungsverlauf auflisten. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | Den Kurztext und den URL-Abrufstatus der Referenz anzeigen. | — | -| `fp audits context-set NAME` | Den Kurztext oder die Referenz-URLs ändern. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-show NAME` | Den Brief und den Status des URL-Abrufs anzeigen. | — | +| `fp audits context-set NAME` | Den Brief oder Referenz-URLs ändern. | `--text`; `--text-file`; `--url`; `--clear-urls` | | `fp audits context-refresh NAME` | Referenz-URLs erneut abrufen. | — | -| `fp audits findings` | Befunde auflisten. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | Einen Befund und seine Belege anzeigen. | — | -| `fp audits ack FINDING_ID` | Einen Befund bestätigen. | `--reason` | +| `fp audits findings` | Findings auflisten. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | +| `fp audits finding FINDING_ID` | Ein Finding und seine Belege anzeigen. | — | +| `fp audits ack FINDING_ID` | Ein Finding bestätigen. | `--reason` | | `fp audits mute FINDING_ID` | Ein wiederkehrendes Muster unterdrücken. | `--reason`; `--yes`, `-y` | | `fp audits dismiss FINDING_ID` | Ein Muster als nicht handlungsrelevant markieren und unterdrücken. | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | Einen Befund als behoben markieren, ohne künftige Unterdrückung. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | Einen Befund in die aktive Warteschlange zurückgeben und die Unterdrückung aufheben. | — | -| `fp audits assign FINDING_ID` | Den Eigentümer eines Befunds festlegen. | erforderlich: `--to ` | +| `fp audits resolve FINDING_ID` | Ein Finding als behoben markieren, ohne künftige Unterdrückung. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | Ein Finding in die aktive Warteschlange zurückstellen und die Unterdrückung aufheben. | — | +| `fp audits assign FINDING_ID` | Den Eigentümer eines Findings festlegen. | erforderlich: `--to ` | #### Audit-Erstellungsoptionen @@ -261,27 +261,27 @@ fp audits create checkout-reliability \ | Option | Beschreibung | | --- | --- | -| `--file ` | Definition auf JSON basieren oder `-` für stdin verwenden. Explizite Flags überschreiben Dateiwerte. | +| `--file ` | Definition auf JSON basieren, oder `-` für stdin verwenden. Explizite Flags überschreiben Dateiwerte. | | `--description ` | Die Fehlerfrage oder den Zweck beschreiben. | | `--enabled` / `--disabled` | Planung ein- oder ausschalten. Standard: aktiviert. | | `--schedule-interval-secs ` | `3600`–`604800`. Standard: `86400`. | -| `--schedule-anchor ` | Fester UTC-Zeitpunkt im ISO 8601-Format. Standard: nächste 09:00 UTC. | -| `--window-mode since_last\|fixed` | Nach dem letzten vollständig analysierten Fenster fortfahren oder ein rollierendes Fenster wiederholt untersuchen. Standard: `since_last`. | +| `--schedule-anchor ` | Fester UTC-Zeitpunkt in ISO 8601-Form. Standard: nächstes 09:00 UTC. | +| `--window-mode since_last\|fixed` | Nach dem letzten vollständig analysierten Fenster fortsetzen oder ein gleitendes Fenster wiederholt untersuchen. Standard: `since_last`. | | `--lookback-window-secs ` | `3600`–`7776000`. Standard: `604800`. | | `--scope ''` | Nach `environments`, `agent_ids` oder anderen unterstützten Scope-Feldern filtern. | -| `--ignore-error-type ` | Fehlertypen ausschließen; wiederholen oder kommagetrennt angeben. | +| `--ignore-error-type ` | Fehlertypen ausschließen; wiederholbar oder durch Komma getrennt. | | `--llm` / `--no-llm` | Agentische Analyse aktivieren oder deaktivieren. Standard: aktiviert. | -| `--top-k ` | `1`–`500` Befunde beibehalten. Standard: `50`. | +| `--top-k ` | `1`–`500` Findings behalten. Standard: `50`. | | `--sensitivity low\|medium\|high` | Berichtssensitivität festlegen. Standard: `medium`. | | `--channels ''` | Benachrichtigungskanal-Array. | -| `--text ` | Inline-Kurztext, maximal 8.192 Zeichen. | -| `--text-file ` | Kurztext aus einer Datei lesen; schließt sich gegenseitig mit `--text` aus. | +| `--text ` | Inline-Brief, maximal 8.192 Zeichen. | +| `--text-file ` | Brief aus einer Datei lesen; schließt sich gegenseitig mit `--text` aus. | | `--url ` | Eine öffentliche HTTPS-Referenz hinzufügen; bis zu fünfmal wiederholbar. | -Kontext während der Erstellung einschließen, wenn der erste Lauf ihn benötigt. Die Erstellung schreibt Definition und Kontext gemeinsam fest, bevor der geplante Lauf beginnt. +Kontext bei der Erstellung einbeziehen, wenn der erste Durchlauf ihn benötigt. Die Erstellung übergibt Definition und Kontext gemeinsam, bevor der eingereihte Durchlauf beginnt. - `fp audits run` ist asynchron. Rufe `fp audits runs NAME` so lange ab, bis der letzte Lauf erfolgreich abgeschlossen ist oder fehlschlägt, bevor du seine Befunde liest. + `fp audits run` ist asynchron. Rufe `fp audits runs NAME` ab, bis der neueste Durchlauf erfolgreich abgeschlossen ist oder fehlschlägt, bevor du dessen Findings liest. ### Issues @@ -291,18 +291,18 @@ Kontext während der Erstellung einschließen, wenn der erste Lauf ihn benötigt | `fp issues list` | Issues auflisten. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | | `fp issues count` | Offene oder ausgewählte Issue-Zustände zählen. | `--state` | | `fp issues show INCIDENT_ID` | Issue-Details, Kommentare, Abonnenten und Aktivitäten anzeigen. | — | -| `fp issues open` | Ein manuelles oder warnungsverknüpftes Issue öffnen. | erforderlich: `--summary`; optional: `--title`, `--alert-id`, `--severity` | +| `fp issues open` | Ein manuelles oder alert-verknüpftes Issue öffnen. | erforderlich: `--summary`; optional: `--title`, `--alert-id`, `--severity` | | `fp issues ack INCIDENT_ID` | Ein Issue bestätigen. | — | -| `fp issues assign INCIDENT_ID` | Zugewiesene Personen ersetzen; Option weglassen, um sie zu entfernen. | wiederholbar: `--assignee` | +| `fp issues assign INCIDENT_ID` | Zugewiesene Personen ersetzen; Option weglassen zum Löschen. | wiederholbar: `--assignee` | | `fp issues resolve INCIDENT_ID` | Ein Issue auflösen. | `--yes`, `-y` | | `fp issues comment-list INCIDENT_ID` | Kommentare auflisten. | — | -| `fp issues comment-add INCIDENT_ID` | Einen Kommentar hinzufügen. | genau eine von `--body`, `--file` | +| `fp issues comment-add INCIDENT_ID` | Einen Kommentar hinzufügen. | genau eines von `--body`, `--file` | | `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Einen Kommentar löschen. | `--yes`, `-y` | | `fp issues subscribers INCIDENT_ID` | Abonnenten auflisten. | — | | `fp issues subscribe INCIDENT_ID` | Sich selbst oder einen anderen Operator abonnieren. | `--email` | | `fp issues unsubscribe INCIDENT_ID` | Ein Abonnement entfernen. | `--email` | -Gültige Issue-Zustände sind `firing`, `acknowledged` und `resolved`. Schweregrade für eigenständige Issues sind `info`, `warning` und `critical`. +Gültige Issue-Zustände sind `firing`, `acknowledged` und `resolved`. Eigenständige Issue-Schweregrade sind `info`, `warning` und `critical`. ### Cloud-Assistent @@ -312,47 +312,47 @@ Gültige Issue-Zustände sind `firing`, `acknowledged` und `resolved`. Schweregr | `fp agent models` | Verfügbare Assistentenmodelle auflisten. | — | | `fp agent chats` | Gespeicherte Chats auflisten. | — | | `fp agent ask [MESSAGE]` | Einen Chat starten oder fortsetzen; liest stdin, wenn die Nachricht weggelassen wird. | `--chat`; `--model`; `--page-context` | -| `fp agent show CHAT_ID` | Eine gespeicherte Unterhaltung anzeigen. | — | -| `fp agent rename CHAT_ID` | Eine Unterhaltung umbenennen. | erforderlich: `--title` | -| `fp agent delete CHAT_ID` | Eine Unterhaltung löschen. | `--yes`, `-y` | +| `fp agent show CHAT_ID` | Eine gespeicherte Konversation anzeigen. | — | +| `fp agent rename CHAT_ID` | Eine Konversation umbenennen. | erforderlich: `--title` | +| `fp agent delete CHAT_ID` | Eine Konversation löschen. | `--yes`, `-y` | ### Policies -Cloud-verwaltete Richtlinienversionen. **Nur für Sitzungen** — jeder Befehl hier gibt `2` zurück, wenn ein API-Schlüssel verwendet wird, noch vor jeder Anfrage, da es sich um Root-only-Schreibrouten handelt, die absichtlich nicht unter `/v1` verfügbar sind. +Cloud-verwaltete Richtlinienversionen. **Nur Sitzung** — jeder Befehl hier beendet sich mit `2` unter einem API-Schlüssel, noch vor jeder Anfrage, da es sich um reine Root-Schreibrouten handelt, die in `/v1` absichtlich fehlen. | Befehl | Zweck | Optionen | | --- | --- | --- | | `fp policies list` | Richtlinienversionen auflisten. | `--json` | | `fp policies show POLICY_ID` | Eine Richtlinie mit ihrer Quelle anzeigen. | — | | `fp policies publish NAME PATH` | Eine Version aus einer lokalen `.mjs`-Datei erstellen. | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | Sie zu jedem Deployment wieder hinzufügen, aus dem sie entfernt wurde, wobei auf jedem eine neue Generation erstellt wird. | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | Sie aus jedem Deployment entfernen, das sie enthält, wobei auf jedem eine neue Generation erstellt wird. | `--yes`, `-y` | +| `fp policies enable POLICY_ID` | Zu jedem Deployment, aus dem sie entfernt wurde, wieder hinzufügen und dabei jeweils eine neue Generation erstellen. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | Aus jedem Deployment entfernen, das sie enthält, und dabei jeweils eine neue Generation erstellen. | `--yes`, `-y` | | `fp policies delete POLICY_ID` | Eine Richtlinienversion löschen. | `--yes`, `-y` | -| `fp policies test PATH` | Eine Richtlinie lokal gegen einen synthetischen Kontext ausführen. Wendet den `match`-Filter jeder Richtlinie an, sodass eine Richtlinie, die das angegebene Event/Tool nicht abdeckt, als `skipped` gemeldet wird, anstatt ausgeführt zu werden. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | Eine Richtlinie mit dem Assistenten entwerfen. Benötigt `policies:write`. | — | +| `fp policies test PATH` | Eine Richtlinie lokal gegen einen synthetischen Kontext testen. Wendet den `match`-Filter jeder Richtlinie an; eine Richtlinie, die das angegebene Event/Tool nicht abdeckt, wird als `skipped` gemeldet statt ausgeführt. | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | Eine Richtlinie mit dem Assistenten entwerfen. Erfordert `policies:write`. | — | ### Fleet -Welche Maschinen welche Richtlinien ausführen. **Nur für Sitzungen**, aus dem gleichen Grund wie oben. +Welche Maschinen welche Richtlinien ausführen. **Nur Sitzung**, aus demselben Grund wie oben. | Befehl | Zweck | Optionen | | --- | --- | --- | -| `fp fleet list` | Eingetragene Maschinen und ihre Deployment-Generation auflisten. | — | -| `fp fleet show MACHINE_ID` | Den Richtliniensatz anzeigen, den eine Maschine aktuell ausführt. | — | -| `fp fleet deploy MACHINE_ID` | **Ersetzt den gesamten Richtliniensatz der Maschine.** Gibt den Plan aus und fragt nur auf einem interaktiven Terminal ohne `--json` nach. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet list` | Registrierte Maschinen und ihre Deployment-Generation auflisten. | — | +| `fp fleet show MACHINE_ID` | Den Richtlinien-Set, den eine Maschine aktuell ausführt, anzeigen. | — | +| `fp fleet deploy MACHINE_ID` | **Ersetzt den gesamten Richtlinien-Set der Maschine.** Gibt den Plan aus und fragt nur in einem interaktiven Terminal ohne `--json` nach. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | | `fp fleet diff MACHINE_ID` | Eine Maschine mit einem anderen Deployment vergleichen. | — | -| `fp fleet history MACHINE_ID` | Vergangene Deployments für eine Maschine anzeigen. | — | -| `fp fleet rollback MACHINE_ID` | Ein vorheriges Deployment wiederherstellen. | `--yes`, `-y` | +| `fp fleet history MACHINE_ID` | Vergangene Deployments einer Maschine anzeigen. | — | +| `fp fleet rollback MACHINE_ID GENERATION` | Den Richtlinien-Set einer vergangenen Generation als neue Generation wiederherstellen. | `--yes`, `-y` | | `fp fleet rename MACHINE_ID` | Einer Maschine einen lesbaren Namen geben. | erforderlich: `--name` | ### Guardrails -Was die Durchsetzung tatsächlich getan hat. **Nur für Sitzungen**, aus dem gleichen Grund wie oben. +Was die Durchsetzung tatsächlich getan hat. **Nur Sitzung**, aus demselben Grund wie oben. | Befehl | Zweck | Optionen | | --- | --- | --- | -| `fp guardrails summary` | Abdeckung, gesperrte/ausgewertete Gesamtwerte, eine Deny-Sparkline und die Tabelle pro Richtlinienquelle. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | Entscheidungen im Zeitfenster zusammengefasst, über alle Richtlinienquellen summiert. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | Abdeckung, Gesamtwerte für blockierte/evaluierte Anfragen, einen Deny-Sparkline und die Tabelle pro Richtlinie. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Entscheidungen in Zeitbuckets über das Fenster, summiert über alle Richtlinienquellen. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | ## Globale Flags @@ -366,11 +366,11 @@ Was die Durchsetzung tatsächlich getan hat. **Nur für Sitzungen**, aus dem gle | `--timeout ` | HTTP-Timeout; muss positiv sein. Standard: `30`. | | `--quiet`, `-q` | Statusausgabe auf stderr unterdrücken. | | `--no-color` | Farbige Ausgabe deaktivieren. | -| `--insecure` / `--secure` | TLS-Zertifikatsprüfung deaktivieren oder wiederherstellen. | -| `--version` | Version ausgeben und beenden. | +| `--insecure` / `--secure` | TLS-Zertifikatsüberprüfung deaktivieren oder wiederherstellen. | +| `--version` | Die ungekapselte Version ausgeben und beenden. | | `--help`, `-h` | Hilfe anzeigen. | -`--api-key` ist für Automatisierung gedacht. Anmeldung, Organisationswechsel und Assistentenbefehle erfordern eine Benutzersitzung. +`--api-key` ist für die Automatisierung gedacht. Anmeldung, Organisationswechsel und Assistentenbefehle erfordern eine Benutzersitzung. ## Umgebungsvariablen @@ -382,16 +382,16 @@ Was die Durchsetzung tatsächlich getan hat. **Nur für Sitzungen**, aus dem gle | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | CLI-Konfigurationsverzeichnis verschieben (Standard: `~/.failproofai/fpcli`). | +| `FP_HOME` | Das CLI-Konfigurationsverzeichnis verschieben (Standard: `~/.failproofai/fpcli`). | | `FP_ANALYTICS_DISABLED` oder `DO_NOT_TRACK` | Anonyme CLI-Analysen deaktivieren. | | `NO_COLOR` | Farbige Ausgabe deaktivieren. | Explizite Flags überschreiben Umgebungsvariablen, die wiederum die gespeicherte Konfiguration überschreiben. Im API-Schlüssel-Modus den Mandanten explizit mit `--org` oder `FP_ORG` auswählen. - Die `AGENTEYE_*`-Schreibweisen dieser Variablen werden von `fp` **nicht gelesen** und wurden es auch nie — die CLI deklariert `FP_*` (`fp_cli/app.py`), und eine unbekannte Variable ist kein Fehler. Das Setzen von `AGENTEYE_DASHBOARD_URL` leitet die CLI nicht um; es wird ignoriert, und der Befehl läuft stillschweigend gegen das gespeicherte Dashboard. + Die `AGENTEYE_*`-Varianten dieser Variablen werden von `fp` **nicht gelesen** und waren es nie — das CLI deklariert `FP_*` (`fp_cli/app.py`), und eine unbekannte Variable ist kein Fehler. Das Setzen von `AGENTEYE_DASHBOARD_URL` ändert das Ziel des CLI nicht; es wird ignoriert, und der Befehl läuft stillschweigend gegen das gespeicherte Dashboard. - `AGENTEYE_HOME` und `AGENTEYE_ENVIRONMENT` existieren noch, gehören jedoch zum **Collector und dem Telemetrie-SDK**, nicht zu dieser CLI. + `AGENTEYE_HOME` und `AGENTEYE_ENVIRONMENT` existieren noch, gehören aber zum **Collector und dem Telemetrie-SDK**, nicht zu diesem CLI. diff --git a/docs/de/reference/custom-agents.mdx b/docs/de/reference/custom-agents.mdx index a38a4b48..b66cb4dd 100644 --- a/docs/de/reference/custom-agents.mdx +++ b/docs/de/reference/custom-agents.mdx @@ -4,18 +4,18 @@ description: "Konfiguration, der Event-Katalog, Korrelationsregeln und Zustellun icon: "python" --- -Was jede Einstellung, Methode und jedes Feld bewirkt. Wenn Sie zum ersten Mal instrumentieren, beginnen Sie mit dem Leitfaden — diese Seite dient zum Nachschlagen. +Was jede Einstellung, Methode und jedes Feld bewirkt. Wenn Sie zum ersten Mal instrumentieren, beginnen Sie mit dem Leitfaden – diese Seite dient als Nachschlagewerk. - Installation, Instrumentierung, die Event-Methoden, ein durchgearbeitetes Beispiel und häufige Probleme. + Installation, Instrumentierung, die Event-Methoden, ein ausgearbeitetes Beispiel und häufige Probleme. - - LangChain, CrewAI, LlamaIndex und Pydantic AI instrumentieren sich selbst mit einem einzigen Aufruf. + + LangChain, CrewAI, LlamaIndex und Pydantic AI instrumentieren sich mit einem einzigen Aufruf selbst. -Python 3.10 oder neuer. Keine Laufzeit-Abhängigkeiten. +Python 3.10 oder neuer. Keine Laufzeitabhängigkeiten. ## Installation @@ -23,24 +23,30 @@ Python 3.10 oder neuer. Keine Laufzeit-Abhängigkeiten. pip install failproofai-sdk ``` -Das Paket wird als `failproofai-sdk` installiert und in Python als `failproofai_sdk` importiert. Framework-Extras wie `failproofai-sdk[langgraph]` installieren das Framework selbst; die Adapter werden immer im Basis-Wheel mitgeliefert. +Das Paket wird als `failproofai-sdk` installiert und in Python als `failproofai_sdk` importiert. Framework-Extras wie `failproofai-sdk[langgraph]` installieren das Framework selbst; die Adapter werden stets im Basis-Wheel mitgeliefert. ## Verbindung zum Failproof-Daemon herstellen - 1. Gehen Sie zu **Admin → Schlüssel** und erstellen Sie einen Schlüssel mit `events:add`. + 1. Gehen Sie zu **Admin → Keys** und erstellen Sie einen Schlüssel mit `events:add`. 2. [Verbinden Sie den Failproof-Daemon mit Cloud](/de/start/setup#connect-a-machine-to-cloud) auf der Agent-Maschine. - 3. Führen Sie eine instrumentierte Sitzung aus und suchen Sie deren genaue ID unter **Observe → Events**. + 3. Führen Sie eine instrumentierte Sitzung aus und suchen Sie die genaue ID unter **Observe → Events**. 4. Gehen Sie zu **Observe → Sessions**, wählen Sie dieselbe Umgebung und öffnen Sie den rekonstruierten Trace. ![Eine benutzerdefinierte Python-Agent-Sitzung, rekonstruiert als Ausführungsgraph und geordneter Event-Trace.](/images/dashboard/session-detail.png) + Lesen Sie den `events:add`-Schlüssel in die Shell ein. `read -s` nimmt ihn über eine Eingabeaufforderung entgegen, die nicht angezeigt wird – er erscheint daher weder in einem Befehl noch im Shell-Verlauf: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Richten Sie anschließend die Maschine ein und prüfen Sie die Verbindung: + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -60,30 +66,30 @@ failproofai_sdk.configure( | Argument | Funktion | | --- | --- | -| `environment` | Das Label für jeden Event — `production`, `staging`, `prod-eu`. Standardmäßig `dev`. | -| `flush_interval` | Wie oft der Hintergrund-Thread auf die Festplatte schreibt, in Sekunden. Standard: `0.5`. | -| `base_dir` | Wohin geschrieben wird. Standardmäßig der Daemon-Spool — das ist in der Regel das Richtige, sofern Sie es nicht bewusst ändern möchten. | +| `environment` | Die Bezeichnung für jeden Event – `production`, `staging`, `prod-eu`. Standardwert: `dev`. | +| `flush_interval` | Wie oft der Hintergrundthread auf die Festplatte schreibt, in Sekunden. Standardwert: `0.5`. | +| `base_dir` | Speicherort für Ausgaben. Standardmäßig wird der Daemon-Spool verwendet, was in der Regel das Richtige ist. | Alternativ per Umgebungsvariable setzen: | Variable | Funktion | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | Setzt `environment` ohne Code-Änderung — geeignet, wenn das Label zur Deployment-Umgebung statt zur App gehört. Ein `configure()`-Argument hat Vorrang. | +| `AGENTEYE_ENVIRONMENT` | Setzt `environment` ohne Codeänderung – sinnvoll, wenn die Bezeichnung zum Deployment und nicht zur App gehört. Ein `configure()`-Argument hat Vorrang. | | `FAILPROOFAI_HOME` | Verschiebt das Failproof AI-Stammverzeichnis, das den Spool enthält. | -| `FAILPROOFAI_SDK_STRICT` | `1` lässt Instrumentierungsfehler eine Ausnahme auslösen, statt sie nur zu protokollieren. | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` lässt ein Framework-Kompatibilitätsproblem eine Ausnahme auslösen, statt nur zu warnen und fortzufahren. | +| `FAILPROOFAI_SDK_STRICT` | `1` lässt Instrumentierungsfehler als Exception aufsteigen, anstatt sie zu protokollieren. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` lässt Framework-Kompatibilitätsprobleme als Exception aufsteigen, anstatt zu warnen und fortzufahren. | - **Keine Kommas in `environment`.** Die Ingest-Schicht teilt dieses Feld an Kommas auf, um Filter zu erstellen, und überspringt jeden Event, dessen Label ein Komma enthält — eine ganze Ausführung verschwindet damit lautlos. Schreiben Sie `prod-eu`, nicht `prod,eu`. + **Keine Kommas in `environment`.** Die Verarbeitungspipeline teilt dieses Feld an Kommas auf, um Filter zu erstellen, und verwirft jeden Event, dessen Bezeichnung ein Komma enthält – ein ganzer Durchlauf verschwindet dabei lautlos. Schreiben Sie `prod-eu`, nicht `prod,eu`. - `configure(environment="prod,eu")` löst sofort eine Ausnahme aus, damit Sie es sofort bemerken. `AGENTEYE_ENVIRONMENT` kann keine Ausnahme auslösen — niemand ruft Sie zurück — daher wird einmal gewarnt und auf `dev` zurückgefallen. + `configure(environment="prod,eu")` löst eine Exception aus, damit Sie es sofort bemerken. `AGENTEYE_ENVIRONMENT` kann keine Exception auslösen – niemand ruft Sie auf – daher wird einmal gewarnt und auf `dev` zurückgefallen. -Events werden im Speicher in eine Warteschlange gestellt und alle `flush_interval` Sekunden im Hintergrund geschrieben, mit einem abschließenden Flush beim Beenden des Interpreters. Ein abrupt beendeter Prozess verliert alles, was noch nicht geschrieben wurde. +Events werden im Arbeitsspeicher gepuffert und im Hintergrund alle `flush_interval` Sekunden geschrieben, mit einem abschließenden Flush beim Beenden des Interpreters. Ein abrupt beendeter Prozess verliert alle noch nicht geschriebenen Events. ## Identität -Jeder Event gehört zu einer Sitzung und einem Agent. **Die Scopes füllen beides aus**, sodass Sie sie selten manuell übergeben müssen: +Jeder Event gehört zu einer Sitzung und einem Agent. **Die Scopes füllen beides aus**, sodass Sie sie selten selbst übergeben müssen: ```python with failproofai_sdk.session(): @@ -91,15 +97,15 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Die explizite Übergabe von `session_id` oder `agent_id` funktioniert weiterhin und hat Vorrang. Wenn weder gebunden noch übergeben, löst der Aufruf `TypeError` aus, statt einen Event zu senden, den Cloud still verwerfen würde. +`session_id` oder `agent_id` explizit zu übergeben funktioniert weiterhin und hat Vorrang. Wenn weder ein Scope gebunden noch ein Wert übergeben wird, löst der Aufruf einen `TypeError` aus, anstatt einen Event zu senden, den Cloud stillschweigend verwerfen würde. - Die Identität wird über Context-Variablen weitergegeben. Sie folgt `asyncio`-Tasks automatisch, aber **nicht** neuen Threads — kapseln Sie einen Worker in `failproofai_sdk.propagate()`, sonst landen seine Events ohne Zuordnung. + Die Identität wird über Kontextvariablen weitergegeben. Sie folgt `asyncio`-Tasks automatisch, jedoch **nicht** neuen Threads – umschließen Sie einen Worker mit `failproofai_sdk.propagate()`, sonst landen seine Events ohne Zuordnung. ## Event-Katalog -Fünfzehn Methoden. Die meisten kommen in **Paaren** — Sie rufen den Öffner auf, dann den Schließer, und das SDK misst die Zeitspanne dazwischen. +Fünfzehn Methoden. Die meisten kommen in **Paaren** – Sie rufen den Öffner auf, dann den Schließer, und das SDK misst den Zeitraum dazwischen. | | Öffnet | Schließt | | --- | --- | --- | @@ -110,13 +116,13 @@ Fünfzehn Methoden. Die meisten kommen in **Paaren** — Sie rufen den Öffner a | **Hooks** | `hook_triggered` | `hook_completed` | | **Menschen** | `human_wait` | `human_input` | -Drei stehen allein: `error`, `human_pause`, `human_interrupt`. +Drei stehen für sich allein: `error`, `human_pause`, `human_interrupt`. - + -Jede Methode akzeptiert außerdem `session_id` und `agent_id`, die von den Scopes automatisch befüllt werden. Alles, was `None` bleibt, wird weggelassen statt als JSON `null` gesendet, und jede Methode gibt `None` zurück. +Jede Methode akzeptiert außerdem `session_id` und `agent_id`, die die Scopes für Sie befüllen. Alles, was als `None` belassen wird, wird weggelassen und nicht als JSON `null` gesendet; jede Methode gibt `None` zurück. -| Methode | Pflichtfelder | Optionale Felder | +| Methode | Erforderlich | Optional | | --- | --- | --- | | `agent_start` | — | `goal`, `parent_id` | | `agent_end` | — | `outcome`, `summary` | @@ -137,12 +143,12 @@ Jede Methode akzeptiert außerdem `session_id` und `agent_id`, die von den Scope - Um eine Ausführung als fehlgeschlagen zu markieren, muss `outcome` einen der folgenden Werte haben: `failed`, `error`, `timeout` oder `rejected`. Alles andere — einschließlich des ähnlichen `"failure"` — wird als Erfolg gewertet. + Um einen Durchlauf als fehlgeschlagen zu markieren, muss `outcome` einen der folgenden Werte haben: `failed`, `error`, `timeout` oder `rejected`. Alles andere – einschließlich des ähnlichen `"failure"` – wird als Erfolg gewertet. ## Paarung und Dauer -**Eine Regel: Geben Sie dem schließenden Event dieselbe ID wie dem öffnenden.** Das ist es, was sie verknüpft und was dem SDK ermöglicht, die Zeitspanne zu messen. +**Eine Regel: Geben Sie dem schließenden Event dieselbe ID wie dem öffnenden.** Damit werden sie verknüpft, und das SDK kann den Zeitraum dazwischen messen. | Paar | Abgeglichen über | | --- | --- | @@ -152,23 +158,23 @@ Jede Methode akzeptiert außerdem `session_id` und `agent_id`, die von den Scope | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**Übergeben Sie `duration_ms` nicht selbst.** Das SDK misst es, und die Übergabe löst `ValueError` aus. +**Übergeben Sie `duration_ms` nicht selbst.** Das SDK misst den Wert, und eine eigene Übergabe löst einen `ValueError` aus. -Die einzige Ausnahme ist `model_response`, wo nur Sie die tatsächliche Provider-Latenz kennen. Übergeben Sie eine ganzzahlige Anzahl von Millisekunden — ein Float löst eine Ausnahme aus, da die Spalte ein 32-Bit-Integer ist und sonst leer bleibt. +Die einzige Ausnahme ist `model_response`, wo nur Sie die tatsächliche Provider-Latenz kennen. Übergeben Sie eine ganze Anzahl von Millisekunden – ein Float löst eine Exception aus, da die Spalte eine 32-Bit-Ganzzahl ist und der Wert sonst leer gespeichert würde. -- **IDs müssen nur pro Art und pro Sitzung eindeutig sein.** Ein Tool-Aufruf und ein Hook können dieselbe ID teilen; zwei gleichzeitig laufende Sitzungen können dieselben IDs wiederverwenden, ohne zu kollidieren. -- **Sie sind nicht auf einen Agent beschränkt.** Ein Paar, das unter einem Agent geöffnet und unter einem anderen geschlossen wird, wird trotzdem korrekt zugeordnet — was in Multi-Agent-Code der Normalfall ist. -- **`request_id` ist optional, wird aber empfohlen.** Ohne sie werden Model-Events in der Reihenfolge ihres Eingangs gepaart, sodass zwei gleichzeitige Aufrufe im selben Agent falsch zugeordnet werden können. -- **Ein Paar, das sich über Prozesse erstreckt**, wird in Cloud trotzdem abgeglichen, aber das SDK kann es nicht zeitlich messen — kein Prozess hat beide Hälften gesehen. -- **Maximal 10.000 Öffner warten gleichzeitig auf einen Schließer.** Darüber hinaus wird der älteste verworfen, damit ein Leck nicht unbegrenzt wachsen kann. +- **IDs müssen nur pro Typ und pro Sitzung eindeutig sein.** Ein Tool-Aufruf und ein Hook können dieselbe ID teilen; zwei gleichzeitig laufende Sitzungen können dieselben IDs ohne Kollision wiederverwenden. +- **Sie sind nicht auf einen Agent beschränkt.** Ein Paar, das unter einem Agent geöffnet und unter einem anderen geschlossen wird, wird dennoch korrekt zugeordnet – was bei Multi-Agent-Code der Normalfall ist. +- **`request_id` ist optional, wird aber empfohlen.** Ohne sie werden Model-Events in der Reihenfolge ihres Eintreffens gepaart, sodass zwei gleichzeitige Aufrufe im selben Agent falsch zugeordnet werden können. +- **Ein Paar, das sich über mehrere Prozesse erstreckt,** wird in Cloud weiterhin abgeglichen, aber das SDK kann die Zeit nicht messen – kein Prozess hat beide Hälften gesehen. +- **Höchstens 10.000 Öffner warten gleichzeitig auf einen Schließer.** Darüber hinaus wird der älteste verworfen, damit ein Speicherleck nicht unbegrenzt wachsen kann. ## Eigene Felder -Jedes zusätzliche Schlüsselwortargument, das Sie übergeben, wird mit dem Event gespeichert: +Jedes zusätzliche Schlüsselwort, das Sie übergeben, wird zusammen mit dem Event gespeichert: ```python failproofai_sdk.event.tool_use( @@ -177,21 +183,21 @@ failproofai_sdk.event.tool_use( ) ``` -Bevorzugen Sie JSON-Typen, wenn Sie sie später abfragen möchten. Alles andere — eine UUID, ein Datetime-Objekt, ein `Decimal`, ein Set, Bytes, ein Modell-Objekt — wird als Zeichenkette gespeichert. +Verwenden Sie nach Möglichkeit JSON-Typen, wenn Sie die Werte später abfragen möchten. Alles andere – eine UUID, ein Datetime-Objekt, ein `Decimal`, ein Set, Bytes, ein Modellobjekt – wird als Zeichenkette gespeichert. - **Präfigieren Sie Ihre Feldnamen.** Extras werden zuletzt angewendet, sodass ein Feld namens `model`, `tool_name` oder `outcome` das echte Feld stillschweigend überschreibt. Die Framework-Adapter verwenden `fw_`; tun Sie dasselbe, und es kann keine Kollision auftreten. + **Präfixieren Sie Ihre Feldnamen.** Zusätzliche Felder werden zuletzt angewendet, sodass ein Feld mit dem Namen `model`, `tool_name` oder `outcome` den eigentlichen Wert stillschweigend überschreibt. Die Framework-Adapter verwenden `fw_`; tun Sie dasselbe, und es kann zu keinen Kollisionen kommen. - Das ist auch der Grund, warum ein falsch geschriebenes optionales Feld keinen Fehler erzeugt — es wird einfach zu einem neuen benutzerdefinierten Feld. Wenn ein Standardfeld in Cloud fehlt, prüfen Sie zuerst die Schreibweise. + Aus diesem Grund führt ein falsch geschriebenes optionales Feld auch nie zu einem Fehler – es wird einfach zu einem neuen benutzerdefinierten Feld. Wenn ein Standardfeld in Cloud fehlt, prüfen Sie zuerst die Schreibweise. -Diese fünf Namen sind reserviert und werden grundsätzlich abgelehnt: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. +Diese fünf Namen sind reserviert und werden direkt abgelehnt: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. ## Zustellung und Überprüfung - Überprüfen Sie unter **Observe → Events**, ob `agent_start` als erster und `agent_end` als letzter Event vorhanden ist. Öffnen Sie dann **Observe → Sessions** und bestätigen Sie, dass Model-, Tool-, Human-, Hook- und Error-Events in der vorgesehenen Reihenfolge erscheinen. Verwenden Sie die Sitzungs-ID als primären Troubleshooting-Schlüssel. + Überprüfen Sie unter **Observe → Events**, ob `agent_start` als erster und `agent_end` als letzter Event vorhanden ist. Öffnen Sie dann **Observe → Sessions** und stellen Sie sicher, dass Model-, Tool-, Human-, Hook- und Error-Events in der vorgesehenen Reihenfolge erscheinen. Verwenden Sie die Sitzungs-ID als primären Schlüssel zur Fehlersuche. ```bash @@ -203,14 +209,14 @@ Diese fünf Namen sind reserviert und werden grundsätzlich abgelehnt: `timestam -Wenn Cloud leer ist, prüfen Sie `$FAILPROOFAI_HOME/custom-agents/events`, andernfalls `~/.failproofai/custom-agents/events`. JSONL-Dateien belegen die SDK-Emission; ein wachsender Spool deutet auf ein Problem bei der Daemon-Konfiguration oder Zustellung hin, während ein leerer Spool auf ein Instrumentierungs- oder Prozesslebenszyklusproblem hindeutet. +Wenn Cloud leer ist, prüfen Sie `$FAILPROOFAI_HOME/custom-agents/events`, andernfalls `~/.failproofai/custom-agents/events`. JSONL-Dateien belegen die Emission durch das SDK; ein wachsender Spool deutet auf ein Daemon-Konfigurations- oder Zustellungsproblem hin, während ein leerer Spool auf ein Instrumentierungs- oder Prozesslebensdauerproblem hindeutet. - Prüfen Sie den Spool nur, wenn der Daemon gestoppt ist. Während er läuft, sammelt und löscht er jeden Batch innerhalb von Millisekunden — eine Verzeichnisauflistung konkurriert mit dem Collector und zeigt weit weniger Events als tatsächlich emittiert wurden. + Prüfen Sie den Spool nur, wenn der Daemon gestoppt ist. Während er läuft, erfasst und löscht er jede Charge innerhalb von Millisekunden – eine Verzeichnisauflistung steht dann im Wettbewerb mit dem Collector und zeigt weit weniger Events als tatsächlich emittiert wurden. -## Fehler in einer benutzerdefinierten Laufzeit verhindern +## Fehler in einer benutzerdefinierten Laufzeitumgebung verhindern -Nutzen Sie Audit-Ergebnisse und verknüpfte Traces, um die unsichere Aktion, den erforderlichen Nachweis und die vorgesehene Reaktion zu definieren. Eine benutzerdefinierte Enforcement-Integration muss die Aktion vor der Ausführung offenlegen, ihre strukturierte Eingabe an die Policy-Engine übergeben und die resultierende allow-, instruct- oder deny-Entscheidung anwenden. +Nutzen Sie Audit-Befunde und verknüpfte Traces, um die unsichere Aktion, den erforderlichen Nachweis und die beabsichtigte Reaktion zu definieren. Eine benutzerdefinierte Enforcement-Integration muss die Aktion vor der Ausführung offenlegen, ihre strukturierte Eingabe an die Policy-Engine weiterleiten und die daraus resultierende allow-, instruct- oder deny-Entscheidung anwenden. -[Kontaktieren Sie Failproof AI](mailto:support@befailproof.ai) und wir helfen Ihnen, die Modell-, Tool- und Lebenszyklus-Grenzen Ihrer Laufzeit auf Policy-Hooks abzubilden und die Integration gemeinsam mit Ihnen zu validieren. \ No newline at end of file +[Kontaktieren Sie Failproof AI](mailto:support@befailproof.ai) – wir helfen Ihnen dabei, die Modell-, Tool- und Lebenszyklus-Grenzen Ihrer Laufzeitumgebung auf Policy-Hooks abzubilden, und validieren die Integration gemeinsam mit Ihnen. \ No newline at end of file diff --git a/docs/de/reference/evaluator-sdk.mdx b/docs/de/reference/evaluator-sdk.mdx index 3b346ddd..9b146abb 100644 --- a/docs/de/reference/evaluator-sdk.mdx +++ b/docs/de/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "Erstelle einen Dienst, der Failproof AI-Sitzungen synchron oder asynchron bewertet." +description: "Führen Sie Ihren eigenen Evaluierungs-Worker aus, für LLM-Richter und alles, was gehostetes Python nicht kann." icon: "gauge" --- -Ein Evaluator empfängt eine abgeschlossene Agent-Sitzung und gibt die gewünschten Qualitätssignale zurück: numerische Bewertungen, eine Erklärung für jede Bewertung und eine optionale Zusammenfassung. Failproof AI speichert diese Ergebnisse neben dem Trace und stellt sie agenten- und umgebungsübergreifend in Diagrammen dar. +Das Evaluator SDK führt Evaluierungen auf Ihrer eigenen Infrastruktur durch. Ihr Worker registriert seine Evaluierungen bei Failproof AI, beansprucht abgeschlossene Sessions, bewertet sie und übermittelt die Ergebnisse – alles über ausgehende HTTPS-Verbindungen: Es werden keine eingehenden Verbindungen benötigt. Verwenden Sie es für das, was [gehostetes Python](/de/evaluations/write) nicht kann – LLM-Richter, Modellaufrufe, Pakete, Geheimnisse und Netzwerkzugriff. Die Ergebnisse erscheinen neben den gehosteten Ergebnissen auf der [Evaluierungsseite](/de/sessions/evaluations) und sind mit **customer** gekennzeichnet. -## Evaluator einrichten +Es wird mit `failproofai-sdk` unter `failproofai_sdk.evaluator` ausgeliefert; der Import des Tracing-SDKs lädt es nicht. - - - Installiere das SDK und den Server, der es ausführt. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - Erstelle `evaluator.py`. Dieses Beispiel prüft, ob eine Sitzung fehlgeschlagene Tool-Aufrufe enthält. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - Setze ein gemeinsames Token, starte den Evaluator und bestätige, dass der Health-Endpunkt antwortet. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - In einem anderen Terminal: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## Evaluator mit Failproof AI verbinden +```bash +pip install failproofai-sdk +``` -1. Stelle den Evaluator unter einer HTTPS-URL bereit, die von Failproof AI Cloud erreichbar ist. -2. Konfiguriere `EVALUATOR_ENDPOINT` mit dieser URL und setze `EVALUATOR_TOKEN` auf dasselbe Token, das der Evaluator verwendet. Für verwaltete Cloud-Instanzen wende dich an [support@befailproof.ai](mailto:support@befailproof.ai), um die Verbindung einzurichten. -3. Führe eine Bewertung durch und bestätige, dass die Scores in Failproof AI erscheinen. +## Evaluierungen schreiben - - - Öffne eine abgeschlossene Sitzung unter **Observe → Sessions** und wähle **Run evaluation**, falls sie nicht automatisch bewertet wurde. Überprüfe Status, Scores, Begründungen und Zusammenfassung im **Evaluation**-Panel der Sitzung. +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - Verwende **Observe → Evaluations**, um Scores über Agenten oder Umgebungen hinweg zu vergleichen. Nutze **Observe → Metrics** für Latenz, Kosten, Token und andere numerische Messungen. - Beginne mit einer einzelnen Sitzung, um zu bestätigen, dass der Evaluator die erwarteten Score-Schlüssel und nützliche Begründungen für diesen spezifischen Durchlauf zurückgegeben hat. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![Eine Sitzungsdetailansicht, die Bewertungsscores und Begründungen neben dem Trace zeigt.](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` registriert eine Evaluierung. Der Schlüssel bestimmt, unter welchem Namen die Ergebnisse aufgeführt werden. Ändern Sie die Version bei jeder Änderung der Logik – jedes Ergebnis behält die Version, mit der es erzeugt wurde. Ein Worker kann bis zu 100 Evaluierungen halten. +- `result_kind` ist `"score"`, sofern nichts anderes angegeben wird. Für eine `"metric"`- oder `"assertion"`-Evaluierung benennen Sie einen `metrics`- oder `assertions`-Eintrag nach dem Schlüssel: Dieser Eintrag ist ihr Ergebnis. +- `when` entscheidet, ob eine Session anwendbar ist. Geben Sie `ConditionResult(False, "")` zurück, um eine Session zu überspringen – der Grund wird dabei gespeichert. +- Eine Evaluierung kann eine normale Funktion oder `async` sein, und `timeout_seconds` begrenzt ihre Laufzeit. +- Payload-Schlüssel – `tool_name`, `response` und `content` oben – sind das, was Ihre Agents senden; lesen Sie sie daher aus einer echten Session ab. - Sobald die Einzelergebnisse korrekt aussehen, verwende das Evaluierungs-Dashboard, um diese Scores über Zeit und über Agenten oder Umgebungen hinweg zu vergleichen. +## Den Worker starten - ![Ein Qualitäts-Dashboard mit Evaluator-Scores über die Zeit.](/images/dashboard/dashboard-quality.png) +Legen Sie einen Schlüssel mit der Berechtigung `evaluations:run`, der unter **Administration → Keys** erstellt wurde, in `FAILPROOFAI_EVALUATOR_TOKEN` ab – setzen Sie ihn aus Ihrem Secret-Store, anstatt ihn direkt in einen Befehl einzutippen – und starten Sie den Worker: - Ein gesundes Diagramm sollte stabile Score-Namen verwenden; das Ändern eines Schlüssels erstellt eine separate Reihe. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -Bei einer selbst gehosteten Cloud-Instanz ist die automatische Bewertung deaktiviert, bis `EVALUATOR_ENDPOINT` im Serverprozess gesetzt ist. Starte den Server nach dem Ändern von Evaluator-Umgebungsvariablen neu. +Ohne den `__main__`-Block bewirkt `python -m failproofai_sdk.evaluator evaluator:app` dasselbe. -Der Dienst stellt `GET /health`, `GET /config`, `POST /evaluate` und optional `GET /evaluate/{job_id}` bereit. Gib `JobPending` für asynchrone Aufgaben zurück und registriere `@app.job_lookup`, damit Failproof AI abfragen kann. +| Variable | Standard | Zweck | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | erforderlich | Adresse von Failproof AI: `https://app.befailproof.ai` für Cloud. HTTPS, außer bei Loopback-Adressen | +| `FAILPROOFAI_EVALUATOR_TOKEN` | erforderlich | Ein Schlüssel mit `evaluations:run` | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | Benennt diesen Worker | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | Sessions, die dieser Worker gleichzeitig bewertet | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Timeout für jede Anfrage an Failproof AI | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | Wie lange ein stoppender Worker auf laufende Prozesse wartet | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | Erlaubt einfaches HTTP zu einer URL, die kein Loopback ist – siehe Warnung unten | +| `FAILPROOFAI_EVALUATOR_MODULE` | keiner | Das `module:attribute` für `python -m failproofai_sdk.evaluator` | -Wenn ein Token konfiguriert ist, erfordern alle Routen außer health dasselbe Bearer-Token, das Failproof AI als `EVALUATOR_TOKEN` sendet. + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` sendet alles im Klartext. Der Worker übermittelt `FAILPROOFAI_EVALUATOR_TOKEN` als `Authorization: Bearer`-Header bei jeder Anfrage, und die abgerufenen Transkripte sind die Sessions selbst – jeder auf dem Übertragungsweg kann beides lesen, und mit dem ausgelesenen Token können Evaluierungen ausgeführt werden, bis Sie ihn rotieren. Verwenden Sie diese Option nur in einem isolierten Entwicklungsnetzwerk. Überall sonst muss die URL HTTPS verwenden; Loopback-Adressen benötigen kein Flag. + -## SDK-Typen +## Ergebnistypen | Typ | Felder | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## Dekoratoren und Routen +| `Score` | `value` (0 bis 1), `passed`, `unit` (Standard `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -| Dekorator | Route | Erforderlich | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | Ja | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | Bei Rückgabe von `JobPending` | -| `@app.config` | `GET /config` | Nein | - -Das SDK begrenzt den Anfragekörper für Bewertungsanfragen auf 25 MiB. Unbekannte Anforderungsfelder werden ignoriert, sodass Dienste kompatibel bleiben, wenn der Event-Vertrag erweitert wird. +Ein `EvalResult` enthält mindestens einen Score, eine Metrik oder eine Assertion und höchstens 25, jeweils unter einem eindeutigen Schlüssel. -## Asynchrone Arbeit zurückgeben +## Die Session -Verwende `JobPending`, wenn die Bewertung nicht innerhalb einer Anfrage abgeschlossen werden kann. Die Job-ID ist für Failproof AI undurchsichtig und muss von deinem Dienst auflösbar bleiben, bis das Ergebnis abgerufen oder der Server-Timeout abgelaufen ist. - -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| Feld oder Methode | Liefert | +| --- | --- | +| `session_id`, `agent_id`, `environment` | Die Identität der Session | +| `started_at`, `ended_at` | Start- und Endzeitpunkt | +| `event_count`, `events` | Das vollständige, geordnete Transkript | +| `count(event_type)` | Anzahl der Events dieses Typs | +| `events_of_type(event_type)` | Diese Events in der richtigen Reihenfolge | -Die Abfragereihenfolge wird in dieser Reihenfolge ausgewählt: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs`, dann `EVALUATOR_POLLING_INTERVAL_SECS` des Servers. Werte werden zwischen 1 Sekunde und 1 Stunde begrenzt. Die standardmäßige Wanduhr-Abfrageobergrenze des Servers beträgt eine Stunde. +Jedes Event enthält `id`, `ts`, `event_type` und `payload`. -## Anfrage- und Antwortfelder +## Der Legacy-Evaluator -| Feld | Typ | Hinweise | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | Aktuell `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | Sitzungsidentität und Umgebung. | -| `started_at` | `datetime` | Zeitstempel des ersten Events. | -| `ended_at` | `datetime \| None` | Vorhanden, wenn die Sitzung ein End-Event ausgelöst hat. | -| `events` | `list[AgentEvent]` | Vollständiger geordneter Event-Stream. | -| `AgentEvent.id` | `int` | Backend-Event-Zeilenkennung. | -| `AgentEvent.ts` | `datetime` | Event-Zeitstempel. | -| `AgentEvent.event_type` | `str` | Event-Familie wie `tool_use`. | -| `AgentEvent.payload` | `dict[str, Any]` | Vollständige Event-Nutzlast. | -| `EvalResponse.scores` | `dict[str, float] \| None` | Numerische Dimensionen, die in Bewertungen dargestellt werden. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | Erklärungen pro Score; Schlüssel sollten `scores` spiegeln. | -| `EvalResponse.summary` | `str \| None` | Gesamtbewertungsnarrativ. | - -## Einstellungen für Server-Betreiber - -Die automatische Bewertung gilt für die gesamte Bereitstellung und bleibt deaktiviert, wenn `EVALUATOR_ENDPOINT` nicht gesetzt ist. - -| Variable | Standard | Zweck | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | nicht gesetzt | Basis-URL des Evaluator-Dienstes. | -| `EVALUATOR_TOKEN` | nicht gesetzt | Bearer-Token, das mit `Evaluator(token=...)` geteilt wird. | -| `EVALUATOR_WORKERS` | `2` | Gleichzeitige Dispatcher-Worker. | -| `EVALUATOR_CLAIM_BATCH` | `4` | Sitzungen, die pro Dispatcher-Durchlauf beansprucht werden. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Fallback-Abfradetakt für asynchrone Vorgänge. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Evaluator-Timeout pro Anfrage. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | Zustellversuche vor terminalem Fehler. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | Aktualisierungstakt für `/config`. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Maximale Wanduhr-Zeit für asynchrones Polling. | - -Der Server kann auch einschränken, welche Organisationen den deployment-globalen Evaluator verwenden. Behandle Änderungen an Endpunkt, Token, Wiederholungsversuchen und Organisations-Gates als Betreiberkonfiguration und starte den Server nach Änderungen neu oder führe ein Rolling-Restart durch. - -## Sicherheit und Betrieb - -- Stelle den Evaluator hinter HTTPS, wenn der Datenverkehr eine vertrauenswürdige Netzwerkgrenze überschreitet. -- Konfiguriere ein nicht-leeres Bearer-Token und halte es auf beiden Diensten identisch. -- Protokolliere nicht das Token oder vollständige sensible Prompts aus Anfrage-Nutzlasten. -- Gestalte synchrone Handler idempotent; Wiederholungsversuche können eine Anfrage wiederholen. -- Speichere den Status asynchroner Jobs in der Produktion außerhalb des Prozessspeichers. -- Verwende stabile Score-Schlüssel. Das Umbenennen eines Schlüssels erstellt eine neue Diagrammreihe, anstatt die alte zu ändern. - -Das SDK gibt strukturierte Lifecycle-Logs aus, wie `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` und Handler-Ausnahmen. Es konfiguriert keine Logging-Handler; verwende die Logging-Konfiguration der Host-Anwendung. \ No newline at end of file +Das frühere Evaluator SDK – ein HTTP-Dienst, den Failproof AI unter `EVALUATOR_ENDPOINT` aufrief, der `/evaluate` beantwortete und über `JobPending` abgefragt wurde – wurde eingestellt. Erstellen Sie neue Evaluatoren mit diesem Worker; Betreiber einer selbst gehosteten Instanz, die einen Legacy-Dienst betreiben, können ihn während der Übergangszeit weiter verwenden. \ No newline at end of file diff --git a/docs/de/reference/failproof-cli.mdx b/docs/de/reference/failproof-cli.mdx index ed993dd0..0cffd242 100644 --- a/docs/de/reference/failproof-cli.mdx +++ b/docs/de/reference/failproof-cli.mdx @@ -4,51 +4,67 @@ description: "Hooks installieren, lokale Richtlinien verwalten, Cloud verbinden icon: "terminal" --- -Installieren Sie die lokale CLI mit `npm install -g failproofai`. Ohne Argumente aufgerufen öffnet sie das lokale Richtlinien-Dashboard. +Installiere die lokale CLI mit `npm install -g failproofai`. Ohne Argumente aufgerufen öffnet sie das lokale Richtlinien-Dashboard. -Das Paket erfordert Node.js 20.9 oder neuer. Bun 1.3 oder neuer wird für Entwicklungs- und Quellinstallationen unterstützt. `failproofai configure` und `failproofai setup` sind Aliase für `failproofai config`; `failproofai p` ist ein Alias für `failproofai policies`. +Das Paket erfordert Node.js 20.9 oder neuer. Bun 1.3 oder neuer wird für Entwicklung und Quellinstallationen unterstützt. `failproofai configure` und `failproofai setup` sind Aliase für `failproofai config`. `failproofai policy`, `failproofai pack` und `failproofai p` sind allesamt Schreibweisen von `failproofai policies` — Packs und einzelne Richtlinien waren drei Befehle für eine Idee und sind jetzt einer. Die älteren Schreibweisen funktionieren weiterhin, mit zwei Ausnahmen: `pack list ` heißt jetzt `policies show `, und `pack build` ist jetzt `publish`. ## Eine Maschine einrichten +Installiere die CLI und lese dann den Maschinenschlüssel in die Shell ein. `read -s` nimmt ihn an einer Eingabeaufforderung entgegen, die nicht echot, sodass er nie in einem Befehl erscheint: + ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +Richte dann die Maschine ein und lege fest, was sie durchsetzt: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` -Führen Sie `failproofai` ohne Argumente aus, um das lokale Richtlinien-Dashboard zu öffnen. +`failproofai config` umfasst die gesamte Einrichtung: Es installiert den `failproofaid`-Dienst (einmalig als Root via `sudo -n` — niemals eine interaktive Passwortabfrage), verdrahtet Hooks in jede gefundene Agent-CLI und verbindet sich mit Cloud, wenn ein Schlüssel verfügbar ist. Ohne Terminal — CI, ein Container, ein steuernder Agent — wendet es Einstellungen an, anstatt zu fragen, und beendet sich mit 1, wenn etwas, das es tun sollte, nicht stattgefunden hat. + +Es wählt **keine** Richtlinien. Das ist die Aufgabe des zweiten Befehls, und ohne ihn setzt eine frisch konfigurierte Maschine nichts außer dem immer aktiven Guard durch. + +Bevorzuge die Umgebungsvariable gegenüber `--token`: Ein Befehlszeilenargument ist über `ps` für jeden Benutzer auf der Maschine lesbar. Das ist alles, wogegen die Variable schützt — ein in einen Befehl eingetippter Schlüssel, einschließlich `export`, landet trotzdem in der Shell-History, weshalb er oben mit `read -s` eingelesen wird. In CI setze ihn aus dem Secret Store und halte Shell-Tracing (`set -x`) deaktiviert, sonst gibt die Ausgabe ihn preis. + + + `--connect ` registriert eine Maschine, die **bereits eingerichtet** ist. Es kehrt zurück, sobald die Registrierung erfolgreich ist — es installiert weder den Daemon noch verdrahtet es irgendwelche Hooks. Verwende das einfache `failproofai config` (oder `failproofai config --token `) auf einer Maschine, die noch nicht eingerichtet wurde, da sie sonst als verbunden erscheint, während sie weder sammelt noch durchsetzt. + + +Führe `failproofai` ohne Argumente aus, um das lokale Richtlinien-Dashboard zu öffnen. | Befehl | Ergebnis | | --- | --- | -| `failproofai config` | Interaktive Maschineneinrichtung starten | -| `failproofai config --connect --token ` | Cloud-Erfassung und Richtlinienverteilung verbinden | -| `failproofai config --status` | Verbindungs-, Daemon-, Liefer- und Pausenstatus anzeigen | -| `failproofai policies` | Eingebaute, benutzerdefinierte, konventionelle, Pack- und Cloud-verwaltete Richtlinien auflisten | -| `failproofai policies --install` | Hooks installieren und Richtlinien aktivieren | -| `failproofai policy add ` | Eine Richtlinie aktivieren – eine eingebaute oder `:` aus einem installierten Pack | -| `failproofai policy remove ` | Eine Richtlinie deaktivieren, gleiche Benennung | +| `failproofai config` | Maschine einrichten: Agents, Daemon und Cloud, wenn ein Schlüssel vorhanden ist | +| `failproofai config --token ` | Einrichten und verbinden in einem Schritt, ohne Rückfragen | +| `failproofai config --connect ` | Eine **bereits** eingerichtete Maschine registrieren — kein Daemon, keine Hooks | +| `failproofai config --status` | Verbindungs-, Daemon-, Zustellungs- und Pausenstatus anzeigen | +| `failproofai policies` | Integrierte, benutzerdefinierte, konventionelle, Pack- und Cloud-verwaltete Richtlinien auflisten | +| `failproofai policies --install` | Hooks in Agent-CLIs verdrahten. Aktiviert von sich aus keine Richtlinie | +| `failproofai policies add ` | Eine Richtlinie aktivieren — eine integrierte oder `:` aus einem installierten Pack | +| `failproofai policies remove ` | Eine Richtlinie deaktivieren, gleiche Benennung | | `failproofai policies --uninstall` | Richtlinien deaktivieren oder Harness-Hooks entfernen | -| `failproofai pack list` | Installierte Richtlinien-Packs und alle enthaltenen Richtlinien auflisten | -| `failproofai pack add ` | Ein Richtlinien-Pack von einem GitHub-Release installieren; ohne Tag wird die neueste Version genommen und angeheftet | -| `failproofai pack add --bundled` | Die eingebauten Richtlinien als Pack installieren, aus diesem Paket, ohne Netzwerk | -| `failproofai pack build ` | Die drei Release-Assets für ein eigenes Pack erstellen | -| `failproofai pack remove ` | Ein installiertes Pack deaktivieren | -| `failproofai audit` | Lokalen Agent-Verlauf scannen und die lokale Audit-Ansicht öffnen | -| `failproofai audit --schedule [days] --email
` | Wiederkehrende lokale Scans planen und deren Ergebnisse per E-Mail versenden | +| `failproofai policies show /` | Was ein Pack enthält, aus seinem Manifest gelesen, bevor man es übernimmt | +| `failproofai policies show / --releases` | Alle veröffentlichten Versionen und welche lokal vorhanden ist | +| `failproofai policies add ` | Ein Richtlinien-Pack von einem GitHub-Release installieren; ohne Tag wird das neueste genommen und angeheftet | +| `failproofai publish` | Eigene Richtlinien als Pack veröffentlichen; `--init` erstellt eine Vorlage | +| `failproofai policies remove ` | Ein Pack deinstallieren | +| `failproofai audit` | Lokale Agent-History scannen und die lokale Audit-Ansicht öffnen | +| `failproofai audit --schedule [days] --email
` | Wiederkehrende lokale Scans planen und deren Ergebnisse per E-Mail senden | | `failproofai audit --status` | Berichtsadresse, Intervall und nächsten geplanten Scan anzeigen | -| `failproofai audit --no-schedule` | Wiederkehrende Scans stoppen, ohne den Audit-Verlauf zu löschen | +| `failproofai audit --no-schedule` | Wiederkehrende Scans stoppen, ohne die Audit-History zu löschen | | `failproofai harness list` | Zusätzliche Erfassungspfade auflisten | -| `failproofai flush --wait` | Die aktuelle Ereigniswarteschlange übertragen | -| `failproofai backfill --since 30d` | Zuvor verarbeiteten Verlauf erneut einlesen | -| `failproofai config --pause [duration]` | Eine lokale Sitzung für standardmäßig 30 Minuten pausieren, bis zu 8 Stunden | -| `failproofai config --resume` | Eine pausierte lokale Sitzung fortsetzen; `--all` hinzufügen, um alle Pausen aufzuheben | +| `failproofai flush --wait` | Den aktuellen Ereignis-Spool zustellen | +| `failproofai backfill --since 30d` | Zuvor übergangene History erneut einlesen | +| `failproofai config --pause [duration]` | Eine lokale Sitzung standardmäßig für 30 Minuten pausieren, bis zu 8 Stunden | +| `failproofai config --resume` | Eine pausierte lokale Sitzung fortsetzen; `--all` hebt alle Pausen auf | | `failproofai update` | Paket-Migrationen abschließen und den Daemon aktualisieren | | `failproofai migrate --dry-run` | Ausstehende Home-Layout-Migrationen in der Vorschau anzeigen oder ausführen | -| `failproofai uninstall` | Hooks und den Daemon entfernen, bevor das Paket deinstalliert wird | +| `failproofai uninstall` | Hooks und Daemon entfernen, bevor das Paket entfernt wird | | `failproofai --version` | Die installierte Paketversion ausgeben | | `failproofai --help` | Befehle und allgemeine Nutzung anzeigen | @@ -56,31 +72,33 @@ Führen Sie `failproofai` ohne Argumente aus, um das lokale Richtlinien-Dashboar | Flag | Verwendung | | --- | --- | -| `--connect --token ` | Nicht-interaktiv verbinden | +| `--token ` | Nicht-interaktiv einrichten und verbinden; wird auch aus `FAILPROOFAI_CLOUD_TOKEN` gelesen | +| `--url ` | Mit einem anderen Ort als `app.befailproof.ai` verbinden; wird auch aus `FAILPROOFAI_CLOUD_URL` gelesen | +| `--connect ` | Nur registrieren, auf einer bereits eingerichteten Maschine. Überspringt Daemon und alle Hooks | | `--machine-id ` | Die stabile Maschinen-ID festlegen | -| `--machine-label ` | Das Dashboard-Label setzen oder ändern | +| `--machine-label ` | Eine **bereits verbundene** Maschine umbenennen. Allein führt es niemals Setup aus — also nach `failproofai config` angeben, nicht währenddessen | | `--no-transcripts` | Entscheidungen ohne Transkriptinhalt senden | -| `--disconnect` | Cloud-Richtlinienabfragen und Ereignisübertragung stoppen | +| `--disconnect` | Cloud-Richtlinien-Pulls und Ereigniszustellung stoppen | | `--status` | Aktuellen Maschinenstatus anzeigen | -| `--pause [duration]` | Die neueste Sitzung im aktuellen Verzeichnis pausieren; akzeptiert Sekunden, Minuten oder Stunden, Standardwert 30 Minuten | +| `--pause [duration]` | Die neueste Sitzung im aktuellen Verzeichnis pausieren; akzeptiert Sekunden, Minuten oder Stunden und verwendet standardmäßig 30 Minuten | | `--resume` | Eine passende Pause vorzeitig beenden | -| `--session ` | Eine explizite Sitzung für Pause oder Fortsetzen auswählen | -| `--all` | Mit `--resume`: alle aktiven Pausen beenden | +| `--session ` | Eine explizite Sitzung für Pause oder Fortsetzen angeben | +| `--all` | Mit `--resume` alle aktiven Pausen beenden | -Lokale Pausen setzen eingebaute, benutzerdefinierte, konventionelle und Pack-Richtlinien für eine Sitzung aus. Sie laufen immer ab und deaktivieren keine Cloud-verwalteten Richtlinien. `block-failproofai-commands` – das immer aktiv ist und selbst weder deaktiviert noch pausiert werden kann – verhindert, dass ein instrumentierter Agent diesen Ausweg selbst nutzt. +Lokale Pausen setzen integrierte, benutzerdefinierte, konventionelle und Pack-Richtlinien für eine Sitzung aus. Sie laufen immer ab und deaktivieren keine Cloud-verwalteten Richtlinien. `block-failproofai-commands` — das immer aktiv ist und selbst nicht deaktiviert oder pausiert werden kann — verhindert, dass ein instrumentierter Agent diesen Ausweg selbst nutzt. -## Richtlinienflags +## Richtlinien-Flags | Flag | Verwendung | | --- | --- | -| `--install`, `-i` | Richtlinien aktivieren und Harness-Hooks installieren | +| `--install`, `-i` | Harness-Hooks installieren. Nachfolgende Namen aktivieren diese Richtlinien; ohne Namen keine Richtlinienänderungen | | `--uninstall`, `-u` | Richtlinien deaktivieren oder Hooks entfernen | -| `--cli ` | Einen oder mehrere unterstützte Harnesses auswählen | +| `--cli ` | Einen oder mehrere unterstützte Harnesses ansprechen | | `--scope user\|project\|local\|all` | Den Konfigurationsbereich wählen; `all` ist für die Deinstallation | | `--beta` | Beta-Richtlinien einschließen | | `--custom`, `-c ` | Eine benutzerdefinierte Richtliniendatei validieren und laden; wiederholbar | -## Übertragungs- und Wartungsflags +## Zustellungs- und Wartungs-Flags | Befehl | Flags | | --- | --- | @@ -102,9 +120,9 @@ failproofai harness remove-path Unterstützte Harness-Namen sind `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` und `goose`. -Labels vergeben Namensräume für abgeleitete Agent-IDs, wenn zwei Wurzeln Kopien desselben Projekts enthalten. Überlappende Wurzeln und doppelte Labels werden abgelehnt, um doppelte Erfassung oder Cursor-Beschädigung zu verhindern. Die Konfiguration von Extra-Pfaden wird ohne Daemon-Neustart neu geladen. +Labels geben abgeleiteten Agent-IDs einen Namensraum, wenn zwei Wurzeln Kopien desselben Projekts enthalten. Überlappende Wurzeln und doppelte Labels werden abgelehnt, um doppelte Erfassung oder Cursor-Beschädigung zu verhindern. Konfigurationen für zusätzliche Pfade werden ohne Daemon-Neustart neu geladen. -Container-Umgebungen können dateibasierte Extra-Pfade durch eine kommagetrennte Variable namens `FAILPROOFAI__EXTRA_PATHS` ersetzen, zum Beispiel: +Container-Umgebungen können datei-konfigurierte zusätzliche Pfade durch eine kommagetrennte Variable namens `FAILPROOFAI__EXTRA_PATHS` ersetzen, zum Beispiel: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -112,26 +130,28 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Umgebungsvariablen -Verwenden Sie Konfigurationsdateien für dauerhaftes Maschinenverhalten. Umgebungsvariablen sind am nützlichsten für Container, Tests und einzelne Prozesse. +Verwende Konfigurationsdateien für dauerhaftes Maschinenverhalten. Umgebungsvariablen sind am nützlichsten für Container, Tests und einzelne Prozesse. | Variable | Verwendung | | --- | --- | +| `FAILPROOFAI_CLOUD_TOKEN` | Der Cloud-Schlüssel, anstelle von `--token`. Bevorzuge dies: Ein Argument ist über `ps` für jeden Benutzer lesbar. Mit `read -s` oder aus einem CI-Secret-Store setzen, niemals durch Eintippen des Schlüssels in einen Befehl, was so oder so in der Shell-History landet | +| `FAILPROOFAI_CLOUD_URL` | Die Cloud-URL, anstelle von `--url`. Dieselbe Variable, die der Daemon liest | | `FAILPROOFAI_HOME` | Das vollständige `~/.failproofai`-Layout verschieben | | `FAILPROOFAI_LOG_LEVEL` | Lokale Logging-Ausführlichkeit festlegen | -| `FAILPROOFAI_HOOK_LOG_FILE` | Hook-Diagnosemeldungen in eine ausgewählte Datei schreiben | +| `FAILPROOFAI_HOOK_LOG_FILE` | Hook-Diagnosen in eine ausgewählte Datei schreiben | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | Anonyme Telemetrie für diesen Prozess deaktivieren | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Interaktive Ersteinrichtung überspringen | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Lokalen Audit nach der Einrichtung überspringen | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Interaktives Ersteinrichtungs-Setup überspringen | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Lokales Audit nach der Einrichtung überspringen | | `FAILPROOFAI_LLM_BASE_URL` | Den von LLM-Richtlinien verwendeten OpenAI-kompatiblen Endpunkt überschreiben | | `FAILPROOFAI_LLM_API_KEY` | Den von LLM-Richtlinien verwendeten API-Schlüssel bereitstellen | | `FAILPROOFAI_LLM_MODEL` | Das von LLM-Richtlinien verwendete Modell auswählen | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Ladezeit benutzerdefinierter Richtlinien-Module begrenzen | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Abruf von Packs und Daemon-Binaries verweigern; bereits Installiertes bleibt aktiv | -| `FAILPROOFAI_PACK_BASE_URL` | Packs von einem Mirror statt von `github.com` abrufen | -| `FAILPROOFAI__EXTRA_PATHS` | Konfigurierte Extra-Erfassungspfade für einen Harness ersetzen | -| `NO_COLOR` | Farbige Terminalausgabe deaktivieren | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Das Laden benutzerdefinierter Richtlinienmodule zeitlich begrenzen | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Das Abrufen von Packs und Daemon-Binaries verweigern; was installiert ist, setzt weiterhin durch | +| `FAILPROOFAI_PACK_BASE_URL` | Packs von einem Spiegel statt von `github.com` abrufen | +| `FAILPROOFAI__EXTRA_PATHS` | Konfigurierte zusätzliche Erfassungspfade für einen Harness ersetzen | +| `NO_COLOR` | Farbige Terminal-Ausgabe deaktivieren | -Agent-spezifische Home-Variablen wie `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` und `OPENCLAW_HOME` überschreiben, wo Failproof AI lokale Sitzungen für den jeweiligen Harness erkennt. +Agent-spezifische Home-Variablen wie `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` und `OPENCLAW_HOME` überschreiben, wo Failproof AI lokale Sitzungen für diesen Harness erkennt. ## Eine Maschine sicher pausieren oder entfernen @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -Eine lokale Sitzungspause deaktiviert keine Cloud-verwalteten Richtlinien. Stellen Sie Cloud-Deployments über den Cloud-Durchsetzungs-Workflow wieder her, wenn das Rollout selbst das Problem ist. +Eine lokale Sitzungspause deaktiviert keine Cloud-verwalteten Richtlinien. Cloud-Deployments über den Cloud-Enforcement-Workflow wiederherstellen, wenn der Rollout selbst das Problem ist. -Bevor Sie das npm-Paket entfernen, deinstallieren Sie installierte Hooks und den Daemon: +Vor dem Entfernen des npm-Pakets installierte Hooks und den Daemon entfernen: ```bash failproofai uninstall --dry-run @@ -151,8 +171,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -Führen Sie `failproofai --help` aus, um versionsspezifische Details zu erhalten. +Führe `failproofai --help` für versionsspezifische Details aus. - Führen Sie `failproofai uninstall` vor `npm rm -g failproofai` aus; npm entfernt weder installierte Agent-Hooks noch den Daemon-Dienst. + Führe `failproofai uninstall` vor `npm rm -g failproofai` aus; npm entfernt weder installierte Agent-Hooks noch den Daemon-Dienst. \ No newline at end of file diff --git a/docs/de/reference/harnesses.mdx b/docs/de/reference/harnesses.mdx index 3779e8a9..ddc0a8f0 100644 --- a/docs/de/reference/harnesses.mdx +++ b/docs/de/reference/harnesses.mdx @@ -4,14 +4,14 @@ description: "Sitzungen erfassen und Richtlinien für alle 12 unterstützten Age icon: "plug-zap" --- -Ein Harness ist die Umgebung, in der Ihr Agent tatsächlich ausgeführt wird. Failproof AI unterstützt zwölf davon, in zwei Klassen: +Ein Harness ist die Umgebung, in der Ihr Agent tatsächlich ausgeführt wird. Failproof AI unterstützt zwölf davon, in zwei Kategorien: - **Coding-CLIs** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose - **Chat- und Assistant-Gateways** (2) — Hermes (Slack, Telegram, Cron), OpenClaw (selbst gehosteter Assistent) -Dieselben Richtlinien und dieselbe Sitzungshistorie gelten unabhängig davon, in welchem Harness ein Agent läuft. Eine Adapter-Schicht bildet die nativen Ereignisnamen, Tool-Namen und Tool-Eingabefelder jedes Harness auf 29 kanonische Ereignisse ab, bevor eine Richtlinie ausgeführt wird. +Dieselben Richtlinien und dieselbe Sitzungshistorie gelten unabhängig davon, in welchem Harness ein Agent läuft. Eine Adapterschicht bildet die nativen Event-Namen, Tool-Namen und Tool-Input-Felder jedes Harness auf 29 kanonische Events ab, bevor eine Richtlinie ausgewertet wird. -Ein Agent, der in **keinem** der zwölf Harnesses läuft, wird direkt mit dem [Python SDK](/de/reference/custom-agents) instrumentiert. Das ist ein anderer Vertrag, und das sollte klar gesagt werden: Das SDK liefert Tracing, Sitzungen, Evaluierungen und Audits — **es setzt Richtlinien nicht eigenständig durch.** Das Blockieren einer unsicheren Aktion vor ihrer Ausführung erfordert einen Enforcement-Hook an der Tool-Grenze Ihrer Laufzeitumgebung; [kontaktieren Sie uns](mailto:support@befailproof.ai) und wir werden es abbilden. +Ein Agent, der in **keinem** der zwölf Harnesses läuft, wird direkt mit dem [Python SDK](/de/reference/custom-agents) instrumentiert. Das ist ein anderer Vertrag, den es klar zu benennen gilt: Das SDK liefert Tracing, Sitzungen, Evaluierungen und Audits — **es setzt Richtlinien nicht eigenständig durch.** Um eine unsichere Aktion vor der Ausführung zu blockieren, wird ein Enforcement-Hook an der Tool-Grenze Ihrer Laufzeitumgebung benötigt; [kontaktieren Sie uns](mailto:support@befailproof.ai) und wir werden es einrichten. | Harness | Unterstützte Hook-Scopes | | --- | --- | @@ -20,28 +20,28 @@ Ein Agent, der in **keinem** der zwölf Harnesses läuft, wird direkt mit dem [P | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -Jede Integration normalisiert ihre nativen Hook-Ereignisnamen, Tool-Namen und Tool-Eingabefelder, bevor Richtlinien ausgeführt werden. Eine Richtlinie kann nur auf Ereignisse reagieren, die der Harness bereitstellt; testen Sie das Verhalten am Sitzungsende und bei Anweisungen mit dem genauen Harness und der Version, die Sie einsetzen. +Jede Integration normalisiert ihre nativen Hook-Event-Namen, Tool-Namen und Tool-Input-Felder, bevor Richtlinien ausgewertet werden. Eine Richtlinie kann nur auf Events reagieren, die der Harness exponiert; testen Sie das End-of-Turn- und Instruction-Verhalten auf genau dem Harness und der Version, die Sie einsetzen. ## Enforcement-Fähigkeiten -„Blockieren" bedeutet, dass das vom aktuellen Adapter zurückgegebene Urteil vom genannten Harness verarbeitet wird. Post-Tool-Blockierung kann das dem Modell angezeigte Ergebnis ersetzen, kann jedoch einen bereits eingetretenen Tool-Seiteneffekt nicht rückgängig machen. +„Blockieren" bedeutet, dass das vom aktuellen Adapter zurückgegebene Urteil vom genannten Harness verarbeitet wird. Post-Tool-Blockierung kann das dem Modell angezeigte Ergebnis ersetzen, aber keine Tool-Nebenwirkung rückgängig machen, die bereits eingetreten ist. -| Harness | Verifizierte Blocking-Ereignisse | Nur-Beobachtungs- oder nicht-blockierende Einschränkungen | +| Harness | Verifizierte Blocking-Events | Nur-Beobachtungs- oder Nicht-Blocking-Einschränkungen | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` und mehrere Task-/Konfigurations-Ereignisse | `PostToolUse`, Sitzungs-Lifecycle, Benachrichtigungen und Post-Failure-Ereignisse sind rein beobachtend. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blockierung ersetzt das Ergebnis nach der Ausführung; Sitzungsstart- und Compact-Ereignisse sind im aktuellen Adapter rein beobachtend. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blockierung ersetzt das Ergebnis nach der Ausführung; Sitzungs- und Benachrichtigungsereignisse sind rein beobachtend. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` und Sitzungsereignisse sind rein beobachtend. | -| OpenCode | `PreToolUse` | Post-Tool- und Lifecycle-Ereignisse sind rein beobachtend; die aktuelle Stop-Behandlung ist eine Empfehlung für einen späteren Turn, kein verifiziertes Gate. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Post-Tool- und Lifecycle-Ereignisse sind rein beobachtend; Stop-Empfehlungen gelten für einen späteren Turn. | +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` und mehrere Task/Config-Events | `PostToolUse`, Sitzungs-Lifecycle, Benachrichtigungen und Post-Failure-Events sind beobachtend. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blockierung ersetzt das Ergebnis nach der Ausführung; Session-Start- und Compact-Events sind im aktuellen Adapter beobachtend. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blockierung ersetzt das Ergebnis nach der Ausführung; Sitzungs- und Benachrichtigungs-Events sind beobachtend. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` und Sitzungs-Events sind beobachtend. | +| OpenCode | `PreToolUse` | Post-Tool- und Lifecycle-Events sind beobachtend; die aktuelle Stop-Behandlung ist eine Anleitung für eine spätere Runde, kein verifiziertes Gate. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Post-Tool- und Lifecycle-Events sind beobachtend; Stop-Anleitung gilt für eine spätere Runde. | | Hermes | `PreToolUse` | Post-Tool-, Sitzungs- und Subagent-Stop-Urteile sind keine Gates. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Post-Tool-, Sitzungs-, Subagent-Stop- und Compaction-Ereignisse sind rein beobachtend. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Post-Tool- und Subagent-Stop-Urteile sind rein beobachtend. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, bedingtes `PermissionRequest` | Permission-Hooks laufen nicht in jedem Permission-Modus; Post-Tool- und Sitzungsereignisse sind rein beobachtend. | -| Antigravity CLI | `PreToolUse`, `Stop` | User-Prompt- und Post-Tool-Urteile sind rein beobachtend; Prompt-Anweisungen können dennoch injiziert werden. | -| Goose | `PreToolUse` | User-Prompt-, Post-Tool- und Sitzungsereignisse sind rein beobachtend. Ein nativer blockierender Stop-Hook existiert upstream, wird jedoch vom aktuellen Adapter nicht installiert. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Post-Tool-, Sitzungs-, Subagent-Stop- und Compaction-Events sind beobachtend. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Post-Tool- und Subagent-Stop-Urteile sind beobachtend. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, bedingtes `PermissionRequest` | Permission-Hooks laufen nicht in jedem Permission-Modus; Post-Tool- und Sitzungs-Events sind beobachtend. | +| Antigravity CLI | `PreToolUse`, `Stop` | User-Prompt- und Post-Tool-Urteile sind beobachtend; Prompt-Instruktionen können dennoch injiziert werden. | +| Goose | `PreToolUse` | User-Prompt-, Post-Tool- und Sitzungs-Events sind beobachtend. Ein nativer blockierender Stop-Hook existiert vorgelagert, wird aber vom aktuellen Adapter nicht installiert. | -Fähigkeiten sind versionsabhängig. Führen Sie nach dem Upgrade einer Agent-CLI erneut Tests durch, insbesondere wenn eine Richtlinie auf Prompt-, Stop-, Permission- oder Post-Tool-Verhalten anstelle des üblichen Pre-Tool-Gates angewiesen ist. +Fähigkeiten sind versionsabhängig. Testen Sie nach dem Upgrade einer Agent-CLI erneut, insbesondere wenn eine Richtlinie auf Prompt-, Stop-, Permission- oder Post-Tool-Verhalten statt auf das übliche Pre-Tool-Gate angewiesen ist. ## Capture- und Policy-Hooks installieren @@ -49,32 +49,38 @@ Fähigkeiten sind versionsabhängig. Führen Sie nach dem Upgrade einer Agent-CL 1. Öffnen Sie **Administration → Keys** und erstellen Sie einen Schlüssel mit `events:add` und `policies:pull`, benannt nach der Maschine oder Umgebung. 2. Verbinden Sie auf der Zielmaschine die lokale CLI mit dem angezeigten Schlüssel und installieren Sie die Harness-Hooks. - 3. Starten Sie eine neue Agent-Sitzung und bestätigen Sie deren Hook- und Sitzungsereignisse unter **Observe → Events**. - 4. Öffnen Sie **Observe → policy** für dasselbe Zeitfenster und bestätigen Sie, dass eine Richtlinienentscheidung der Maschine zugeordnet wird. + 3. Starten Sie eine neue Agent-Sitzung und bestätigen Sie deren Hook- und Sitzungs-Events unter **Observe → Events**. + 4. Öffnen Sie **Observe → policy** für dasselbe Zeitfenster und bestätigen Sie, dass eine Richtlinienentscheidung der Maschine zugeordnet ist. - Die Verbindung beginnt mit einem Maschinenschlüssel. Stellen Sie sicher, dass er sowohl Ingestion- als auch Policy-Delivery-Berechtigungen enthält, bevor Sie das Secret kopieren. + Die Verbindung beginnt mit einem Maschinenschlüssel. Vergewissern Sie sich, dass er sowohl Ingestion- als auch Policy-Delivery-Berechtigungen enthält, bevor Sie sein Secret kopieren. - ![Die neue API-Schlüssel-Schublade zum Gewähren von Ereignis-Ingestion- und Policy-Delivery-Berechtigungen.](/images/dashboard/key-create.png) + ![Die Drawer-Ansicht für neue API-Schlüssel zum Erteilen von Event-Ingestion- und Policy-Delivery-Berechtigungen.](/images/dashboard/key-create.png) - Nach der Installation der Hooks sollte der Events-Stream neue Ereignisse von der verbundenen Maschine und Umgebung anzeigen. + Nach der Installation der Hooks sollte der Events-Stream neue Events von der verbundenen Maschine und Umgebung anzeigen. ![Der Live-Events-Stream zur Bestätigung, dass ein neu installierter Harness Berichte sendet.](/images/dashboard/events-stream.png) - Überprüfen Sie abschließend, ob Richtlinienentscheidungen derselben Maschine zugeordnet werden. Dies bestätigt, dass der Harness sowohl Richtlinienaktivitäten als auch Trace-Ereignisse meldet. + Überprüfen Sie abschließend, ob Richtlinienentscheidungen derselben Maschine zugeordnet sind. Dies bestätigt, dass der Harness sowohl Richtlinienaktivität als auch Trace-Events meldet. - ![Die Policy-Seite zur Überprüfung von Richtlinienentscheidungen eines neu verbundenen Harness.](/images/dashboard/policy-observe.png) + ![Die Policy-Seite zur Verifizierung von Richtlinienentscheidungen eines neu verbundenen Harness.](/images/dashboard/policy-observe.png) - Hooks für alle erkannten Harnesses installieren: + Lesen Sie den Maschinenschlüssel in die Shell ein. `read -s` nimmt ihn über eine Eingabeaufforderung entgegen, die nicht angezeigt wird, sodass er nie in einem Befehl oder der Shell-History erscheint: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Oder bestimmte Harnesses und einen Konfigurationsscope angeben: + Richten Sie dann die Maschine ein — dieser Schritt verdrahtet Hooks für jeden erkannten Harness, installiert den Daemon und verbindet sich mit Cloud: + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + Das Setup aktiviert keine Richtlinie von sich aus — dafür ist der zweite Befehl gedacht. + + Oder wählen Sie gezielt bestimmte Harnesses und einen Konfigurationsscope: ```bash failproofai policies --install \ @@ -82,9 +88,9 @@ Fähigkeiten sind versionsabhängig. Führen Sie nach dem Upgrade einer Agent-CL --scope user ``` - Der Project-Scope speichert die Hook-Konfiguration bei einem Repository. Der User-Scope deckt die Arbeit über mehrere Repositories hinweg ab. Claude Code unterstützt zusätzlich den Local-Scope; die Unterstützung variiert je nach Harness, und die CLI lehnt nicht unterstützte Kombinationen ab. + Der Project-Scope speichert die Hook-Konfiguration zusammen mit einem Repository. Der User-Scope deckt die Arbeit über mehrere Repositories hinweg ab. Claude Code unterstützt zusätzlich den Local-Scope; die Unterstützung variiert je nach Harness, und die CLI weist nicht unterstützte Kombinationen ab. - Maschine und ihre Ereignisse überprüfen: + Überprüfen Sie die Maschine und ihre Events: ```bash failproofai config --status @@ -94,16 +100,16 @@ Fähigkeiten sind versionsabhängig. Führen Sie nach dem Upgrade einer Agent-CL -## Nicht-standardmäßigen Sitzungspfad hinzufügen +## Einen nicht-standardmäßigen Sitzungspfad hinzufügen - Zusätzliche Pfade werden auf der Maschine registriert, nicht in der Cloud. Nachdem Sie einen hinzugefügt haben, öffnen Sie **Observe → Sessions**, filtern Sie nach der Umgebung der Maschine und bestätigen Sie, dass Sitzungen aus dem neuen Pfad erscheinen. Öffnen Sie eine Sitzung und überprüfen Sie Agent, Harness und Ereignis-Zeitstempel, bevor Sie diese in einem Audit verwenden. + Zusätzliche Pfade werden auf der Maschine registriert, nicht in Cloud. Nach dem Hinzufügen öffnen Sie **Observe → Sessions**, filtern nach der Umgebung der Maschine und bestätigen, dass Sitzungen vom neuen Pfad erscheinen. Öffnen Sie eine Sitzung und prüfen Sie den Agenten, den Harness und die Event-Zeitstempel, bevor Sie ihn für ein Audit verwenden. - ![Die Sitzungsliste, gefiltert nach der Umgebung, die Daten vom zusätzlichen Capture-Pfad empfängt.](/images/dashboard/sessions-list.png) + ![Die Sitzungsliste gefiltert nach der Umgebung, die Daten vom zusätzlichen Capture-Pfad empfängt.](/images/dashboard/sessions-list.png) - Einen Pfad mit optionalem Label hinzufügen und die konfigurierten Pfade anzeigen: + Fügen Sie einen Pfad mit einem optionalen Label hinzu und prüfen Sie die konfigurierten Pfade: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -112,10 +118,10 @@ Fähigkeiten sind versionsabhängig. Führen Sie nach dem Upgrade einer Agent-CL failproofai backfill --since 7d ``` - Einen Pfad entfernen mit `failproofai harness remove-path claude checkout`. + Entfernen Sie einen Pfad mit `failproofai harness remove-path claude checkout`. - Führen Sie nach der Installation eine neue Sitzung aus. Überprüfen Sie sowohl den Live-Event-Stream als auch eine tatsächliche Richtlinienentscheidung, bevor Sie den Rollout ausweiten. + Führen Sie nach der Installation eine neue Sitzung durch. Überprüfen Sie sowohl den Live-Event-Stream als auch eine tatsächliche Richtlinienentscheidung, bevor Sie den Rollout ausweiten. \ No newline at end of file diff --git a/docs/de/reference/overview.mdx b/docs/de/reference/overview.mdx index 01cfe047..0779bbc7 100644 --- a/docs/de/reference/overview.mdx +++ b/docs/de/reference/overview.mdx @@ -4,7 +4,7 @@ description: "Unterstützte Agent-Harnesses, SDKs, CLIs und die HTTP-API verbind icon: "braces" --- -Wählen Sie die Integration, die am nächsten an der Umgebung liegt, in der Ihr Agent bereits läuft. +Wähle die Integration, die am besten zu deiner bestehenden Agent-Umgebung passt. @@ -17,65 +17,68 @@ Wählen Sie die Integration, die am nächsten an der Umgebung liegt, in der Ihr Konfiguration, der Event-Katalog, Korrelationsregeln und Zustellung. - Lokale Projekte, Sessions, Policy-Aktivität und Offline-Audits einsehen. + Lokale Projekte, Sessions, Policy-Aktivitäten und Offline-Audits einsehen. Lokale Erfassung, Hooks, Policies, Audits, Zustellung und Maschinenzustand konfigurieren. - Cloud-Sessions, Audits, Issues, Alerts, Keys, Benutzer und Einstellungen abfragen und verwalten. + Cloud-Sessions, Audits, Issues, Alerts, Schlüssel, Benutzer und Einstellungen abfragen und verwalten. - Abgeschlossene oder inaktive Sessions mit einem FastAPI-Dienst bewerten. + Abgeschlossene oder inaktive Sessions mit einem FastAPI-Service bewerten. Workflow-spezifische allow-, instruct- und deny-Entscheidungen erstellen und testen. - Die Cloud-Steuerungsebene auf einem kundenseitig verwalteten Kubernetes-Cluster deployen. + Die Cloud-Steuerungsebene auf einem kundenverwalteten Kubernetes-Cluster bereitstellen. -Die generierte [HTTP-API-Referenz](/de/reference/http-api) deckt die öffentliche `/v1`-Oberfläche ab. Manuell verfasste Seiten erläutern Workflows, die mehrere Endpunkte umspannen oder administrative Schnittstellen außerhalb dieser öffentlichen Oberfläche nutzen. +Die generierte [HTTP-API-Referenz](/de/reference/http-api) deckt die öffentliche `/v1`-Oberfläche ab. Manuell erstellte Seiten erläutern Workflows, die mehrere Endpunkte umfassen oder administrative Schnittstellen außerhalb dieser öffentlichen Oberfläche nutzen. -## Einen Agenten verbinden und Daten prüfen +## Einen Agenten verbinden und Daten überprüfen - 1. Öffnen Sie **Administration → Keys**, erstellen Sie einen Key mit `events:add` und `policies:pull`, und kopieren Sie das Secret. - 2. Konfigurieren Sie die Integration mithilfe der passenden Seite oben. - 3. Öffnen Sie **Observe → Events**, um zu bestätigen, dass Events ankommen, und dann **Observe → Sessions**, um zu prüfen, ob diese vollständige Runs bilden. - 4. Filtern Sie nach der Umgebung der Integration und prüfen Sie eine Session auf die Felder für Modell, Tool, Fehler und Policy, die für Audits benötigt werden. + 1. Öffne **Administration → Keys**, erstelle einen Schlüssel mit `events:add` und `policies:pull` und kopiere das Secret. + 2. Konfiguriere die Integration mithilfe der entsprechenden Seite oben. + 3. Öffne **Observe → Events**, um zu bestätigen, dass Events ankommen, dann **Observe → Sessions**, um zu bestätigen, dass sie vollständige Runs bilden. + 4. Filtere nach der Umgebung der Integration und prüfe eine Session auf die Modell-, Tool-, Fehler- und Policy-Felder, die für Audits benötigt werden. - Beginnen Sie mit der Key-Seitenleiste. Die gewählten Berechtigungen bestimmen, ob die Maschine Events senden und Cloud-verwaltete Policies empfangen darf. + Beginne mit dem Key-Drawer. Die ausgewählten Berechtigungen bestimmen, ob die Maschine Events senden und Cloud-verwaltete Policies empfangen kann. - ![Die Seitenleiste zum Erstellen neuer API-Keys, mit der Event-Ingestion- und Policy-Zustellungsberechtigungen vergeben werden.](/images/dashboard/key-create.png) + ![Der neue API-Key-Drawer zum Erteilen von Berechtigungen für Event-Ingestion und Policy-Zustellung.](/images/dashboard/key-create.png) - Nach dem Verbinden der Integration können Sie über die Sessions-Liste prüfen, ob die zugehörigen Events in der erwarteten Umgebung zu vollständigen Runs zusammengefasst werden. + Nutze nach dem Verbinden der Integration die Sessions-Liste, um zu bestätigen, dass ihre Events in der erwarteten Umgebung zu vollständigen Runs zusammengefasst werden. - ![Die Sessions-Liste, mit der überprüft wird, ob eine neu verbundene Integration vollständige Agent-Runs meldet.](/images/dashboard/sessions-list.png) + ![Die Sessions-Liste zur Überprüfung, dass eine neu verbundene Integration vollständige Agent-Runs meldet.](/images/dashboard/sessions-list.png) - Öffnen Sie eine dieser Sessions, bevor Sie die Integration als abgeschlossen betrachten – der Trace sollte das Modell, das Tool, den Fehler sowie die Policy-Nachweise enthalten, die Ihre Audits benötigen. + Öffne eine dieser Sessions, bevor du die Integration als abgeschlossen betrachtest; der Trace sollte das Modell, das Tool, den Fehler und die Policy-Nachweise enthalten, die deine Audits benötigen. - Erstellen Sie einen Machine-Key, verbinden Sie den Failproof-Daemon und überprüfen Sie die erste Session. + Erstelle einen Maschinenschlüssel und lies das ausgegebene Secret in die Shell ein. `read -s` nimmt es an einer Eingabeaufforderung entgegen, die keine Ausgabe anzeigt, sodass es weder in einem Befehl noch im Shell-Verlauf erscheint: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Verbinde den Failproof-Daemon und überprüfe die erste Session: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - Verwenden Sie `fp --json sessions ...`, wenn das Ergebnis von einem anderen Tool verarbeitet werden soll. Globale Flags wie `--json`, `--org` und `--base-url` müssen vor dem Befehl angegeben werden. + Verwende `fp --json sessions ...`, wenn das Ergebnis von einem anderen Tool weiterverarbeitet wird. Globale Flags wie `--json`, `--org` und `--base-url` müssen vor dem Befehl stehen. - Weitere Informationen zu lokalen Befehlen finden Sie in der [Failproof AI CLI-Referenz](/de/reference/failproof-cli) und zu `fp`-Befehlen in der [Failproof Cloud CLI-Referenz](/de/reference/cloud-cli#cli-commands). + Siehe die [Failproof AI CLI-Referenz](/de/reference/failproof-cli) für lokale Befehle und die [Failproof Cloud CLI-Referenz](/de/reference/cloud-cli#cli-commands) für `fp`-Befehle. \ No newline at end of file diff --git a/docs/de/reference/policy-sdk.mdx b/docs/de/reference/policy-sdk.mdx index 8e1f48b4..4c53917e 100644 --- a/docs/de/reference/policy-sdk.mdx +++ b/docs/de/reference/policy-sdk.mdx @@ -1,29 +1,29 @@ --- title: "Benutzerdefinierte Richtlinien" -description: "JavaScript- oder TypeScript-Richtlinien für agentenspezifische Fehler erstellen, testen und bereitstellen." +description: "JavaScript- oder TypeScript-Richtlinien für Fehler spezifisch für Ihre Agenten erstellen, testen und bereitstellen." icon: "shield-plus" --- -Benutzerdefinierte Richtlinien wandeln ein Fehlermuster aus Ihren Traces oder Audits in eine Entscheidung um, die während der Arbeit eines Agenten ausgeführt wird. Eine Richtlinie kann eine Aktion erlauben, dem Agenten Anleitung geben oder die Aktion blockieren, bevor sie zu einem weiteren Vorfall führt. +Benutzerdefinierte Richtlinien verwandeln ein Fehlermuster aus Ihren Traces oder Audits in eine Entscheidung, die während der Arbeit eines Agenten ausgeführt wird. Eine Richtlinie kann eine Aktion erlauben, dem Agenten Hinweise geben oder die Aktion blockieren, bevor sie einen weiteren Vorfall verursacht. -Verwenden Sie eine benutzerdefinierte Richtlinie, wenn das Verhalten von Ihren Tools, Pfaden, Befehlen, Umgebungen oder Betriebsregeln abhängt. Prüfen Sie zunächst den [integrierten Richtlinienkatalog](/de/policies/builtin-catalog), um keine bestehende Kontrolle neu zu erstellen. +Verwenden Sie eine benutzerdefinierte Richtlinie, wenn das Verhalten von Ihren Tools, Pfaden, Befehlen, Umgebungen oder Betriebsregeln abhängt. Prüfen Sie zunächst das [Failproof AI Policy-Paket](/de/policies/packs), damit Sie keine vorhandene Kontrolle neu erstellen. ## Benutzerdefinierte Richtlinie erstellen - 1. Gehen Sie zu **Admin → Richtlinieneditor**, wählen Sie **Neue Richtlinie** und beschreiben Sie den Fehler, den Sie verhindern möchten. - 2. Fügen Sie den Richtliniencode hinzu und testen Sie erwartete Übereinstimmungen sowie sichere Nicht-Übereinstimmungen im Editor. Beheben Sie alle Validierungsfehler. + 1. Gehen Sie zu **Admin → Policy-Editor**, wählen Sie **Neue Richtlinie** und beschreiben Sie den Fehler, den Sie verhindern möchten. + 2. Fügen Sie den Richtlinienquellcode hinzu und testen Sie im Editor erwartete Treffer sowie sichere Nicht-Treffer. Beheben Sie jeden Validierungsfehler. 3. Speichern Sie den Entwurf und wählen Sie **Version veröffentlichen**, um eine unveränderliche Version zu erstellen. - 4. Gehen Sie zu **Admin → Durchsetzung**, stellen Sie die Version auf einem Testgerät im **Beobachtungs**-Modus bereit und überprüfen Sie die Entscheidungen unter **Beobachten → Richtlinie**, bevor Sie sie durchsetzen. + 4. Gehen Sie zu **Admin → Durchsetzung**, stellen Sie die Version auf einem Testrechner im **Beobachtungs**-Modus bereit, und überprüfen Sie die Entscheidungen unter **Beobachten → Richtlinie**, bevor Sie sie durchsetzen. - ![Der Richtlinieneditor zum Erstellen und Veröffentlichen einer benutzerdefinierten Richtlinie.](/images/dashboard/policy-editor.png) + ![Der Policy-Editor zum Erstellen und Veröffentlichen einer benutzerdefinierten Richtlinie.](/images/dashboard/policy-editor.png) 1. Erstellen Sie `.failproofai/policies/checkout-policies.ts`. Der Dateiname muss auf `policies.js`, `policies.mjs` oder `policies.ts` enden. 2. Registrieren Sie eine oder mehrere Richtlinien mit `customPolicies.add()`. 3. Validieren und installieren Sie die Datei mit `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. - 4. Lösen Sie eine passende und eine sichere Aktion aus. Führen Sie `failproofai policies` aus und prüfen Sie die zugeordneten Entscheidungen unter **Beobachten → Richtlinie**. + 4. Lösen Sie eine passende Aktion und eine sichere Aktion aus. Führen Sie `failproofai policies` aus und prüfen Sie die zugeordneten Entscheidungen unter **Beobachten → Richtlinie**. @@ -55,23 +55,23 @@ customPolicies.add({ }); ``` -Gute Richtlinien sind eng genug, um sie in einem Satz zu erklären. Prüfen Sie die beobachtbare Aktion – nicht die vermutete Absicht des Agenten – und geben Sie `allow()` zurück, sobald die Regel nicht zutrifft. +Gute Richtlinien sind eng genug, um sie in einem Satz zu erklären. Treffen Sie die beobachtbare Aktion – nicht die Absicht, die Sie dem Agenten zuschreiben – und geben Sie `allow()` zurück, sobald die Regel nicht zutrifft. -## Entscheidung wählen +## Eine Entscheidung auswählen -| Hilfsfunktion | Ergebnis | Verwendung | +| Hilfsfunktion | Ergebnis | Verwenden, wenn | | --- | --- | --- | | `allow(reason?)` | Die Operation wird fortgesetzt. | Die Richtlinie gilt nicht oder die Aktion ist sicher. | -| `instruct(reason)` | Die Operation wird mit Anleitung fortgesetzt, wo die Umgebung dies unterstützt. | Sie möchten den Agenten zu einem besseren Ansatz leiten, ohne eine Invariante zu erzwingen. | -| `deny(reason)` | Die Operation wird blockiert, wenn das Ereignis und die Umgebung das Blockieren unterstützen. | Die Aktion darf nicht fortgesetzt werden. | +| `instruct(reason)` | Die Operation wird mit Hinweisen fortgesetzt, sofern der Harness dies unterstützt. | Sie den Agenten zu einem besseren Vorgehen lenken möchten, ohne eine Invariante zu erzwingen. | +| `deny(reason)` | Die Operation wird blockiert, wenn Ereignis und Harness das Blockieren unterstützen. | Die Aktion darf nicht fortgesetzt werden. | -Formulieren Sie den Grund für den Agenten, der sich erholen muss. Erklären Sie, was erkannt wurde und was stattdessen getan werden soll. +Schreiben Sie die Begründung für den Agenten, der sich erholen muss. Erklären Sie, was erkannt wurde und was stattdessen getan werden sollte. - Verwenden Sie `instruct()` nicht für eine Sicherheitsgrenze. Die Zustellung von Anleitungen variiert je nach Agent-Umgebung. Verwenden Sie `deny()`, wenn die Aktion verhindert werden muss. + Verwenden Sie `instruct()` nicht für eine Sicherheitsgrenze. Die Zustellung von Hinweisen variiert je nach Agent-Harness. Verwenden Sie `deny()`, wenn die Aktion verhindert werden muss. -## Richtlinienobjekt +## Policy-Objekt ```ts customPolicies.add({ @@ -84,32 +84,32 @@ customPolicies.add({ | Feld | Erforderlich | Beschreibung | | --- | --- | --- | -| `name` | Ja | Stabiler Bezeichner für die Richtlinie. Namen müssen dateiübergreifend eindeutig sein. | -| `description` | Nein | Lesbare Beschreibung, die in Richtlinienübersichten und Entscheidungen angezeigt wird. | -| `match.events` | Nein | Ereignistypen, die die Richtlinie aufrufen. Ohne `match` wird sie für jedes verfügbare Ereignis aufgerufen. | +| `name` | Ja | Stabiler Bezeichner für die Richtlinie. Namen über Dateien hinweg eindeutig halten. | +| `description` | Nein | Menschenlesbare Beschreibung, die in Richtlinienübersichten und Entscheidungen angezeigt wird. | +| `match.events` | Nein | Ereignistypen, die die Richtlinie aufrufen. Wenn `match` weggelassen wird, wird sie für jedes verfügbare Ereignis aufgerufen. | | `fn` | Ja | Synchrone oder asynchrone Funktion, die ein `allow`-, `instruct`- oder `deny`-Ergebnis zurückgibt. | -Filtern Sie Tools innerhalb von `fn`. `match.toolNames` ist kein Bestandteil des öffentlichen Typs für benutzerdefinierte Richtlinien. +Tools innerhalb von `fn` filtern. `match.toolNames` ist nicht Teil des öffentlichen benutzerdefinierten Richtlinientyps. ## Richtlinienkontext -Jede Richtlinie erhält einen `PolicyContext`. +Jede Richtlinie empfängt einen `PolicyContext`. | Feld | Typ | Inhalt | | --- | --- | --- | | `eventType` | `HookEventType` | Normalisiertes Ereignis, das aktuell ausgewertet wird. | | `toolName` | `string \| undefined` | Kanonischer Tool-Name wie `Bash`, `Read`, `Write` oder `Edit`. | | `toolInput` | `Record \| undefined` | Kanonische Eingabe für den aktuellen Tool-Aufruf. | -| `payload` | `Record` | Vollständige normalisierte Ereignisnutzlast. | -| `session` | `SessionMetadata \| undefined` | Sitzungs-ID, Arbeitsverzeichnis, Transcript-Pfad, Berechtigungsmodus und Umgebungsmetadaten, sofern verfügbar. | -| `cli` | `string \| undefined` | Quell-Agent-Umgebung, z. B. `claude`, `codex` oder `cursor`. | -| `params` | `Record` | Parameter für integrierte Richtlinien. Benutzerdefinierte Richtlinien erhalten derzeit ein leeres Objekt. | +| `payload` | `Record` | Vollständige normalisierte Ereignis-Nutzlast. | +| `session` | `SessionMetadata \| undefined` | Sitzungs-ID, Arbeitsverzeichnis, Transcript-Pfad, Berechtigungsmodus und Harness-Metadaten, sofern verfügbar. | +| `cli` | `string \| undefined` | Quell-Agent-Harness, z. B. `claude`, `codex` oder `cursor`. | +| `params` | `Record` | Eingebaute Richtlinienparameter. Benutzerdefinierte Richtlinien erhalten aktuell ein leeres Objekt. | -Behandeln Sie jeden optionalen Wert als tatsächlich optional. Nicht alle Agent-Versionen und Ereignistypen liefern dieselben Felder. +Jeden optionalen Wert als tatsächlich optional behandeln. Agent-Versionen und Ereignistypen stellen nicht alle dieselben Felder bereit. ### Häufige Tool-Eingaben -Failproof AI normalisiert gängige Tools über unterstützte Umgebungen hinweg, sodass eine Richtlinie in der Regel eine einheitliche Eingabeform verwenden kann. +Failproof AI normalisiert gängige Tools über unterstützte Harnesses hinweg, sodass eine Richtlinie in der Regel eine einheitliche Eingabeform verwenden kann. | Tool | Häufige Felder | | --- | --- | @@ -119,26 +119,26 @@ Failproof AI normalisiert gängige Tools über unterstützte Umgebungen hinweg, | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | -Verwenden Sie defensive Typumwandlung, da Tool-Eingabewerte als `unknown` typisiert sind: +Defensive Typumwandlung verwenden, da Tool-Eingabewerte als `unknown` typisiert sind: ```ts const command = String(ctx.toolInput?.command ?? ""); const filePath = String(ctx.toolInput?.file_path ?? ""); ``` -## Ereignis wählen +## Ereignis auswählen | Ereignis | Zeitpunkt | Typische Verwendung | | --- | --- | --- | | `PreToolUse` | Vor der Ausführung eines Tools. | Befehle, Schreibvorgänge, Lesevorgänge und externe Aktionen blockieren oder steuern. | -| `PostToolUse` | Nachdem ein Tool zurückgekehrt ist. | Ergebnisse prüfen, bevor sie den Agenten erreichen. Ein deny blockiert das gesamte Ergebnis; einzelne Felder werden nicht geschwärzt. | +| `PostToolUse` | Nachdem ein Tool zurückgekehrt ist. | Ergebnisse prüfen, bevor sie den Agenten erreichen. Ein Deny blockiert das gesamte Ergebnis; es schwärzt keine einzelnen Felder. | | `PermissionRequest` | Wenn der Agent eine Berechtigung anfordert. | Organisationsspezifische Berechtigungsregeln anwenden. | -| `UserPromptSubmit` | Bevor ein gesendeter Prompt fortgesetzt wird. | Verbotene Anweisungen ablehnen oder Workflow-Anleitungen hinzufügen. | -| `Stop` | Wenn der Agent versucht, abzuschließen. | Eine erreichbare Abschlussbedingung erfordern, z. B. einen lokalen Verifikationsschritt. | +| `UserPromptSubmit` | Bevor ein eingereichter Prompt fortgesetzt wird. | Verbotene Anweisungen ablehnen oder Workflow-Hinweise hinzufügen. | +| `Stop` | Wenn der Agent versucht, abzuschließen. | Eine erreichbare Abschlussbedingung erfordern, z. B. einen lokalen Verifizierungsschritt. | | `SubagentStop` | Wenn ein Subagent versucht, abzuschließen. | Delegierte Arbeit prüfen, bevor sie an den übergeordneten Agenten zurückgegeben wird. | | `SessionStart` / `SessionEnd` | An Sitzungsgrenzen. | Sitzungsweiten Zustand aufzeichnen oder prüfen. | -Ereignisverfügbarkeit und Blockierungsverhalten hängen von der Agent-Umgebung ab. Lesen Sie [Agent-Umgebungen](/de/reference/harnesses), bevor Sie sich auf ein Ereignis über eine gemischte Flotte hinweg verlassen. +Die Verfügbarkeit von Ereignissen und das Blockierverhalten hängen vom Agent-Harness ab. Lesen Sie [Agent-Harnesses](/de/reference/harnesses), bevor Sie sich auf ein Ereignis über eine gemischte Flotte hinweg verlassen. `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` und `Setup`. @@ -166,7 +166,7 @@ customPolicies.add({ }); ``` -### Nicht-blockierende Anleitung geben +### Nicht-blockierende Hinweise geben ```ts import { customPolicies, allow, instruct } from "failproofai"; @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### Sitzungsabschluss kontrollieren +### Sitzungsabschluss prüfen ```ts import { execFileSync } from "node:child_process"; @@ -215,7 +215,7 @@ customPolicies.add({ ``` - Ein abgelehntes `Stop`-Ereignis kann dazu führen, dass der Agent es erneut versucht. Stellen Sie die Bedingung nur dann auf, wenn der Agent sie in der aktuellen Umgebung erfüllen kann, und begrenzen Sie jeden Subprozess oder Netzwerkaufruf. + Ein abgelehntes `Stop`-Ereignis kann dazu führen, dass der Agent es erneut versucht. Prüfen Sie nur eine Bedingung, die der Agent in der aktuellen Umgebung erfüllen kann, und begrenzen Sie jeden Unterprozess oder Netzwerkaufruf. ## Richtliniendateien laden @@ -229,7 +229,7 @@ Konventionsdateien werden automatisch geladen: ~/.failproofai/policies/personal-policies.mjs ``` -- Projekt- und Benutzerrichtlinienverzeichnisse werden beide geladen. +- Projekt- und Benutzer-Richtlinienverzeichnisse werden beide geladen. - Dateien werden alphabetisch innerhalb jedes Verzeichnisses geladen. - Eine Datei muss auf `policies.js`, `policies.mjs` oder `policies.ts` enden. - Mehrere `customPolicies.add()`-Aufrufe in einer Datei werden unterstützt. @@ -238,7 +238,7 @@ Konventionsdateien werden automatisch geladen: ### Explizite Dateien -Verwenden Sie explizite Pfade, wenn Validierung oder Konfiguration die Einstiegsdatei direkt benennen sollen: +Verwenden Sie explizite Pfade, wenn Validierung oder Konfiguration die Einstiegsdatei direkt benennen soll: ```bash failproofai policies --install \ @@ -251,7 +251,7 @@ Explizite Dateien werden zuerst geladen, gefolgt von Projekt-Konventionsdateien ## Validieren und testen -Die Validierung führt das Modul über den Produktions-Loader aus und bestätigt, dass es mindestens eine Richtlinie registriert. +Die Validierung führt das Modul durch den Produktionslader aus und bestätigt, dass es mindestens eine Richtlinie registriert. ```bash failproofai policies --install \ @@ -260,41 +260,41 @@ failproofai policies --install \ failproofai policies ``` -Die Validierung erkennt fehlende Dateien, Syntaxfehler, nicht aufgelöste Importe, Ausnahmen auf oberster Ebene und Modul-Lade-Timeouts. Sie beweist nicht, dass Ihre Match-Logik korrekt ist. +Die Validierung erkennt fehlende Dateien, Syntaxfehler, ungelöste Importe, Top-Level-Ausnahmen und Modul-Lade-Timeouts. Sie beweist nicht, dass Ihre Match-Logik korrekt ist. Testen Sie mindestens diese Fälle: -- Eine Aktion, die übereinstimmen und den beabsichtigten Richtliniengrund erzeugen muss. +- Eine Aktion, die treffen muss und den vorgesehenen Richtliniengrund erzeugt. - Eine ähnliche, aber sichere Aktion, die `allow()` zurückgeben muss. - Fehlende oder fehlerhafte Tool-Felder. - Alternative Befehlssyntax, Pfade, Anführungszeichen, Groß-/Kleinschreibung und Leerzeichen. -- Ein nicht verfügbarer Subprozess oder eine Netzwerkabhängigkeit. +- Ein nicht verfügbarer Unterprozess oder eine Netzwerkabhängigkeit. -Ordnen Sie das Ergebnis Ihrer benutzerdefinierten Richtlinie unter **Beobachten → Richtlinie** zu. Ein blockierter Test reicht nicht aus, wenn eine andere integrierte Richtlinie die Entscheidung getroffen hat. +Ordnen Sie das Ergebnis unter **Beobachten → Richtlinie** Ihrer benutzerdefinierten Richtlinie zu. Ein blockierter Test reicht nicht aus, wenn eine andere eingebaute Richtlinie die Entscheidung getroffen hat. ## Laufzeitverhalten -- Integrierte Richtlinien werden vor benutzerdefinierten Richtlinien ausgewertet. +- Eingebaute Richtlinien werden vor benutzerdefinierten Richtlinien ausgewertet. - Das erste `deny` stoppt die weitere Richtlinienauswertung. - Mehrere `instruct`-Ergebnisse können kombiniert werden, wenn keine Richtlinie das Ereignis ablehnt. - Eine Richtlinienfunktion hat eine Ausführungsfrist von 10 Sekunden. - Eine ausgelöste Ausnahme oder ein Timeout wird protokolliert und als `allow()` behandelt. -- Eine Konventionsdatei, die nicht geladen werden kann, wird übersprungen; andere benutzerdefinierte Dateien und integrierte Richtlinien werden weiter ausgeführt. -- Das Laden von Modulen auf oberster Ebene hat ebenfalls eine Frist von 10 Sekunden. -- Der Cloud-Beobachtungsmodus führt die Richtlinie aus, zeichnet jedoch eine Nicht-allow-Entscheidung auf, ohne sie durchzusetzen. +- Eine Konventionsdatei, die nicht geladen werden kann, wird übersprungen; andere benutzerdefinierte Dateien und eingebaute Richtlinien werden weiter ausgeführt. +- Das Top-Level-Modulladen hat ebenfalls eine Frist von 10 Sekunden. +- Der Cloud-Beobachtungsmodus führt die Richtlinie aus, zeichnet aber eine Nicht-allow-Entscheidung auf, ohne sie durchzusetzen. -Halten Sie Richtlinienmodule deterministisch und schnell. Vermeiden Sie Netzwerkaufrufe oder Server-Starts auf oberster Ebene. Begrenzen Sie die Arbeit innerhalb von `fn`, fangen Sie Abhängigkeitsfehler ab und entscheiden Sie bewusst, ob dieser Fehler die Operation erlauben oder verweigern soll. +Richtlinienmodule deterministisch und schnell halten. Top-Level-Netzwerkaufrufe oder Server-Starts vermeiden. Arbeit innerhalb von `fn` begrenzen, Abhängigkeitsfehler abfangen und bewusst entscheiden, ob dieser Fehler die Operation erlauben oder blockieren soll. ## API-Exporte | Export | Zweck | | --- | --- | -| `customPolicies.add(policy)` | Eine benutzerdefinierte Richtlinie registrieren, wenn das Modul geladen wird. | -| `allow(reason?)` | Die Operation erlauben. | -| `instruct(reason)` | Die Operation erlauben und Anleitung bereitstellen, wo unterstützt. | -| `deny(reason)` | Die Operation blockieren, wo unterstützt. | -| `getCustomHooks()` | Die aktuell im Modul-Registry registrierten Richtlinien zurückgeben. | -| `clearCustomHooks()` | Dieses Registry leeren, hauptsächlich für Tests und Loader. | +| `customPolicies.add(policy)` | Benutzerdefinierte Richtlinie beim Laden des Moduls registrieren. | +| `allow(reason?)` | Operation erlauben. | +| `instruct(reason)` | Operation erlauben und Hinweise bereitstellen, sofern unterstützt. | +| `deny(reason)` | Operation blockieren, sofern unterstützt. | +| `getCustomHooks()` | Die aktuell im Modulregister registrierten Richtlinien zurückgeben. | +| `clearCustomHooks()` | Dieses Register leeren, hauptsächlich für Tests und Lader. | TypeScript exportiert `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` und `PolicyFunction`. diff --git a/docs/de/sessions/evaluations.mdx b/docs/de/sessions/evaluations.mdx index 039508f3..cc93f684 100644 --- a/docs/de/sessions/evaluations.mdx +++ b/docs/de/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "Online-Evaluierungen" -description: "Bewerten Sie aktive und abgeschlossene Sitzungen nach Qualität, Compliance, Kosten und Latenz." +title: "Evaluierungsergebnisse lesen" +description: "Evaluierungspunkte im Zeitverlauf darstellen, Agenten und Umgebungen vergleichen, verstehen warum eine Sitzung niedrig bewertet wurde, und den Assistenten befragen." icon: "gauge" --- -Online-Evaluierungen wenden konsistente Beurteilungen auf Agentensitzungen an. Verwenden Sie sie für Signale, die kontinuierlich gemessen werden sollten, anstatt nur bei einem Audit untersucht zu werden. +Ergebnisse aus jeder Evaluierung – ob gehostet oder aus deinem eigenen Worker – landen an denselben Stellen. -## Evaluierungsqualität überprüfen +## Punkte im Zeitverlauf vergleichen - 1. Gehen Sie zu **Observe → Evaluations**. - 2. Fügen Sie eine Datenreihe hinzu und wählen Sie den Agenten, die Umgebung, den Evaluierungswert, die Statistik und die Kurve. - 3. Fügen Sie Datenreihen hinzu, um Umgebungen, Agenten oder Score-Schlüssel zu vergleichen. - 4. Wählen Sie ein Ergebnis aus, um passende Sitzungen zu öffnen oder die gefilterte Ansicht zu teilen. Verwenden Sie **Observe → Metrics** für Latenz, Tokens, Kosten und andere Größenwerte. + Gehe zu **Observe → evaluations**. - ![Ein Qualitäts-Dashboard mit durchschnittlichen Evaluierungswerten und Trends über die Zeit.](/images/dashboard/dashboard-quality.png) + - **Recent runs** listet jede Evaluierung auf, sobald sie eingeht: ob sie von einem gehosteten (**managed**) oder deinem eigenen (**customer**) Evaluator stammt, den Agenten und die Sitzung, die Evaluierung und ihre Version, ihren Status sowie ihren Punktestand oder ihre Metriken. + - **Score over time** stellt das dar, was du auswählst. Wähle **add series** und gib einen Agenten, eine Umgebung, eine Evaluierung und eine Statistik an: avg, min, max, p50, p75, p90, p95, p99, stddev oder mode. Jede Reihe ist eine Linie; weise ihr eine eigene **curve** zu, um sie in einem separaten Diagramm darzustellen. - Öffnen Sie eine Sitzung aus der Detailansicht, um ihre sitzungsbezogene Begründung zu untersuchen: + ![Die Evaluierungsseite: kürzliche Ausführungen mit dem Tag „customer", ein Score-over-time-Diagramm mit Referenzlinien bei 0,5 und 0,8 sowie eine Reihe, die finished_clean über alle Agenten und Umgebungen mittelt.](/images/dashboard/evaluations-chart.png) - ![Eine Sitzungsdetailansicht mit Evaluierungswerten und Begründungen neben dem vollständigen Trace.](/images/dashboard/session-detail.png) + Ein Zeitbereich und eine Bucket-Größe gelten für alle Reihen. Ein feiner Bucket findet einen Vorfall; ein grober zeigt einen Trend, kann aber die gesuchten Ausreißer verbergen. Ein Bucket ohne Bewertungen erscheint als Lücke in der Linie – niemals als Null –, und Referenzlinien markieren 0,5 und 0,8. + + Jeder Teil der Ansicht ist in der URL enthalten: **share** kopiert sie, und wer sie öffnet, sieht genau den Vergleich, den du erstellt hast. ```bash @@ -28,25 +28,29 @@ Online-Evaluierungen wenden konsistente Beurteilungen auf Agentensitzungen an. V fp evals --score helpfulness:0.8.. --since 7d ``` - Fügen Sie globales `--json` vor `evals` für die Automatisierung hinzu, zum Beispiel `fp --json evals --aggregate --env production`. + Füge das globale `--json` vor `evals` hinzu, um die Ausgabe zu automatisieren, z. B. `fp --json evals --aggregate --env production`. -Ein Evaluator erhält die Sitzungsidentität, Umgebung, Zeitstempel und geordnete Ereignisse. Er kann numerische Score-Schlüssel mit optionaler Begründung und einer Zusammenfassung zurückgeben. Langläufige Evaluatoren können einen ausstehenden Job zurückgeben und später abgefragt werden. +Stelle **avg** und **p90** für dieselbe Evaluierung dar, um zu sehen, ob ein guter Durchschnitt einen schlechten Ausreißerbereich verdeckt – oder dieselbe Evaluierung für zwei Agenten oder für Produktion und Staging, um sie auf einer Achse zu vergleichen. Kosten, Latenzen und Token-Anzahlen, die Einheiten tragen, werden unter **Observe → metrics** dargestellt, ein Diagramm pro Einheit. + +## Verstehen, warum eine Sitzung niedrig bewertet wurde + +Öffne eine Sitzung unter **Observe → sessions**; das Raster zeigt die Punktestände jeder Sitzung und lässt sich nach Punktebereich filtern. Die rechte Leiste der Sitzung beginnt mit der Evaluierungszusammenfassung, gefolgt von einem Balken pro Punktestand mit der Begründung des Evaluators darunter. + +![Eine Sitzungsdetailansicht mit Evaluierungspunkten und Begründungen neben dem vollständigen Trace.](/images/dashboard/session-detail.png) + +## Den Assistenten befragen + +Stelle Fragen zu Evaluierungsdaten auf normalem Englisch: „tell me about some of the recent evaluations" oder welche Agenten-Punktestände nachlassen. Der [Assistent](/de/sessions/assistant) liest und analysiert die Ergebnisse und antwortet mit Tabellen, auf die du weiter eingehen kannst. Eine Frage, die sich lohnt zu behalten, kann zu einer [Abfrage](/de/sessions/queries) oder einem [Dashboard](/de/sessions/dashboards) werden. -## Geeignete Evaluierungsziele +![Die Evaluierungsseite neben dem Assistenten, der auf „tell me about some of the recent evaluations" mit einer Zusammenfassung von Gesamtzahlen, Status und Punkteständen antwortet.](/images/dashboard/evaluations-assistant.png) -- Aufgabenerfüllung oder Korrektheit -- Faktentreue und Halluzinationsrisiko -- Tool-Auswahl und Tool-Effizienz -- Richtlinien- oder Prozess-Compliance -- Kosten- und Latenzbudgets -- Erforderliche Eskalation an Menschen +## Beobachten und handeln -## Vom Score zur Reaktion +- **Dashboards** unter **Analyze → dashboards** zeigen die Entwicklung der hervorgehobenen Punktestände pro Agent und Umgebung für die gesamte Organisation. -Zeigen Sie Scores in Dashboards an, um Trends zu verfolgen. Erstellen Sie Warnmeldungen für Schwellenwerte oder zusammengesetzte Bedingungen. Wenn ein Score über eine Population hinweg abnimmt, führen Sie ein Audit durch, um die Ursache zu untersuchen; wenn die Ursache eine wiederholbare Aktion ist, stellen Sie eine Richtlinie bereit. + ![Ein Qualitäts-Dashboard mit durchschnittlichen Evaluierungspunkten und Trends im Zeitverlauf.](/images/dashboard/dashboard-quality.png) - - Implementieren Sie synchrone oder asynchrone Evaluierungen mit dem Python-Evaluator-SDK. - \ No newline at end of file +- **Alerts** benachrichtigen dich, wenn ein Punktestand einen Schwellenwert überschreitet. Siehe [alerts](/de/audits/alerts). +- Wenn ein Punktestand über viele Sitzungen hinweg sinkt, [führe ein Audit durch](/de/audits/run), um die Ursache zu finden; wenn diese auf einer wiederholbaren Aktion beruht, [schreibe eine Policy](/de/policies/editor). \ No newline at end of file diff --git a/docs/de/start/integrations/custom-agents.mdx b/docs/de/start/integrations/custom-agents.mdx index 9e643a29..824fb42f 100644 --- a/docs/de/start/integrations/custom-agents.mdx +++ b/docs/de/start/integrations/custom-agents.mdx @@ -5,9 +5,9 @@ description: "Instrumentiere einen selbst geschriebenen Agenten oder ein Framewo icon: "code" --- -Für selbst geschriebene Agenten oder Frameworks, für die Failproof AI keinen Adapter bereitstellt. Es gibt nichts zu instrumentieren: Du sendest die Events selbst. +Für einen selbst geschriebenen Agenten oder ein Framework, für das Failproof AI keinen Adapter hat. Es ist nichts zu instrumentieren: Du sendest die Events selbst. -Das ist dieselbe API, die auch die vier Framework-Adapter intern verwenden. Sie sind lediglich Übersetzungstabellen darüber. +Das ist dieselbe API, die die vier Framework-Adapter im Hintergrund nutzen. Sie sind lediglich Übersetzungsschichten darüber. ## Installation @@ -30,23 +30,23 @@ with failproofai_sdk.session(): # ein Durchlauf t.output = search(q) # ein Tool-Aufruf ``` -Von oben nach unten gelesen erklärt sich der Code von selbst: +Von oben nach unten gelesen, sagt es genau das, was es bedeutet: -| Einschließen mit | Bedeutung | +| Umschließen mit | Bedeutet | | --- | --- | | `session()` | Diese Events gehören zum selben Durchlauf | -| `agent()` | Etwas verrichtet Arbeit – gib ihm einen erkennbaren Namen | -| `tool_call()` | Das ist ein Tool-Aufruf, und das ist sein Ergebnis | +| `agent()` | Etwas erledigt Arbeit – gib ihm einen Namen, den du in einer Liste erkennen würdest | +| `tool_call()` | Das ist ein Tool, und hier ist sein Rückgabewert | -Und was jedes davon tatsächlich sendet: +Und was jeder Scope tatsächlich sendet: | Scope | Sendet | Zweck | | --- | --- | --- | -| `session()` | Nichts | Bindet eine Session-ID und gruppiert einen Durchlauf | -| `agent()` | `agent_start`, `agent_end` | Klammert eine Arbeitseinheit | -| `tool_call()` | `tool_use`, `tool_result` | Klammert einen Tool-Aufruf und misst ihn | +| `session()` | Nichts | Bindet eine Session-ID, gruppiert einen Durchlauf | +| `agent()` | `agent_start`, `agent_end` | Klammert eine Arbeitseinheit ein | +| `tool_call()` | `tool_use`, `tool_result` | Klammert ein Tool ein und misst es | -Alles im Inneren kann `session_id` und `agent_id` weglassen. Die Scopes binden die Identität an Kontextvariablen, und jeder Event-Aufruf liest sie von dort – du musst keine IDs durch deine Funktionen durchreichen. +Alles darin kann `session_id` und `agent_id` weglassen. Die Scopes binden die Identität auf Kontextvariablen, und jeder Event-Aufruf liest sie zurück – du musst IDs nie durch deine Funktionen durchreichen. Alle drei funktionieren sowohl mit `async with` als auch mit `with`. @@ -61,20 +61,20 @@ with failproofai_sdk.session(): ## Wie ein Scope schließt -`agent()` behandelt Ausnahmen für dich: +`agent()` behandelt Exceptions für dich: -| Was passiert | Events | Ergebnis | +| Was passiert ist | Events | Ergebnis | | --- | --- | --- | -| Keine Ausnahme | `agent_end` | `success` | +| Keine Exception | `agent_end` | `success` | | `Exception` | `error`, dann `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, dann `agent_end` | `failed` | -| `CancelledError`, `GeneratorExit` | Nur `agent_end` | `cancelled` | +| `CancelledError`, `GeneratorExit` | nur `agent_end` | `cancelled` | -Der Fehler wird vor `agent_end` gesendet, weil das Dashboard den Span bei `agent_end` schließt und alles Spätere keinem Span mehr zugeordnet wird. Ein Abbruch ist kein Fehler, daher verschmutzen abgebrochene Durchläufe die Fehleransicht nicht. Die Ausnahme wird immer weitergeleitet – ein Scope schluckt niemals. +Der Fehler wird vor `agent_end` gesendet, weil das Dashboard den Span bei `agent_end` schließt und alles danach keinem Span mehr zugeordnet wird. Eine Stornierung ist kein Fehler, daher verschmutzen abgebrochene Durchläufe die Fehlerübersicht nicht. Die Exception wird immer erneut ausgelöst: Ein Scope verschluckt sie nie. ## Die Event-Methoden -Fünfzehn Methoden in sechs Familien. Die meisten kommen paarweise – du sendest den Öffner, dann den Schließer, und das SDK misst die Zeitspanne dazwischen. +Fünfzehn Methoden in sechs Familien. Die meisten kommen paarweise – du sendest den Öffner, dann den Schließer, und das SDK misst den Span dazwischen. | Familie | Öffnet | Schließt | Eigenständig | | --- | --- | --- | --- | @@ -87,7 +87,7 @@ Fünfzehn Methoden in sechs Familien. Die meisten kommen paarweise – du sendes | **Fehler** | — | — | `error` | - Bevorzuge die Scopes – `agent()` und `tool_call()` – wo immer sie passen. Sie garantieren das schließende Event auch dann, wenn der Rumpf eine Ausnahme wirft. Greife direkt auf diese Methoden zurück, wenn dein Kontrollfluss nicht schachtelt, etwa bei einem Modellaufruf innerhalb einer Hilfsfunktion. + Bevorzuge die Scopes – `agent()` und `tool_call()` – wo immer sie passen. Sie garantieren das schließende Event, auch wenn der Body eine Exception wirft. Greife direkt auf diese Methoden zurück, wenn dein Kontrollfluss nicht verschachtelt ist, z. B. bei einem Modellaufruf innerhalb eines Hilfsfunktions. @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **Die zwei Human-Familien zeigen in entgegengesetzte Richtungen.** + **Die beiden Human-Familien zeigen in entgegengesetzte Richtungen.** | Methoden | Bedeutung | | --- | --- | | `human_wait` / `human_input` | Der **Agent hat eine Person gefragt** – ein Freigabe-Gate, eine Rückfrage | | `human_pause` / `human_interrupt` | Eine **Person hat auf den Agenten eingewirkt** – ein Stopp-Button, eine Operator-Pause | - Kein Framework signalisiert das zweite Paar – es liegt immer an dir, diese Events zu senden. + Kein Framework signalisiert das zweite Paar – das musst du immer selbst senden. - **Übergib `request_id`, wenn Modellaufrufe gleichzeitig laufen.** Ohne sie werden Anfragen und Antworten in Empfangsreihenfolge pro Agent zugeordnet – bei gleichzeitigen Aufrufen entstehen so falsche Paarungen, bei denen jede Antwort der falschen Anfrage zugewiesen wird. + **Übergib `request_id`, wenn Modellaufrufe parallel laufen.** Ohne sie werden Anfragen und Antworten in Eingangsreihenfolge pro Agent gepaart – und parallele Aufrufe werden falsch gepaart, sodass jede Antwort der falschen Anfrage zugeordnet wird. ## Beispiel -Eine Tool-Calling-Schleife gegen die OpenAI-API, ohne Agent-Framework: +Eine Tool-Calling-Schleife gegen die OpenAI API, ohne Agent-Framework: ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """Ein Modellaufruf, eingeklammert durch das Paar.""" + """Ein Modellaufruf, eingerahmt durch das Paar.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # begrenzt; eine unbegrenzte Agentenschleife ist ein eigener Fehler + for _ in range(4): # begrenzt; eine unbegrenzte Agent-Schleife ist ein eigener Fehler message = turn(messages) if not message.tool_calls: break @@ -204,45 +204,47 @@ with failproofai_sdk.session(): }) ``` -Das erzeugt dieselben sechs Event-Typen, die auch ein Adapter liefern würde. Die vollständige, ausführbare Version mit den Tool-Definitionen liegt im SDK-Repository unter `docs/manual/examples/`. +Das erzeugt dieselben sechs Event-Typen, die ein Adapter liefern würde. Die vollständige +ausführbare Version inklusive Tool-Definitionen liegt im SDK-Repository unter +`docs/manual/examples/`. -## Threads und async +## Threads und Async -Kontextvariablen werden automatisch in asyncio-Tasks weitergegeben. In neue Threads werden sie nicht weitergegeben, da ein Thread mit einem leeren Kontext startet. +Kontextvariablen werden automatisch in asyncio-Tasks übertragen. In neue Threads werden sie nicht übertragen, da ein Thread mit einem leeren Kontext startet. ```python # asyncio: nichts zu tun async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# Threads: das Callable einwickeln +# Threads: Callable einwickeln pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Ohne `propagate()` werfen die Events des Workers einen `TypeError`, der den Fix benennt, anstatt auf keiner Session zu landen. Das ist beabsichtigt: Ein Event ohne Session wird bei der Verarbeitung übersprungen und mit `200` beantwortet – genau der stille Fehler, den die Identitätsschicht verhindern soll. +Ohne `propagate()` wirft das Worker-Event einen `TypeError`, der den Fix benennt, anstatt auf keiner Session zu landen. Das ist beabsichtigt: Ein Event ohne Session wird beim Ingest übersprungen und mit `200` beantwortet – das ist genau der stille Fehler, den die Identitätsschicht verhindern soll. ## Ein Framework ohne Adapter instrumentieren -Jedes Agent-Framework bietet dieselben drei Ansatzpunkte. Bilde sie ab und du hast einen vollständigen Trace – die vier mitgelieferten Adapter tun nichts weiter als das. +Jedes Agent-Framework gibt dir dieselben drei Nahtpunkte. Mappe sie und du hast eine vollständige Trace – die vier mitgelieferten Adapter tun nichts anderes. -| Der Ansatzpunkt | Was du schreibst | Was landet | +| Der Nahtpunkt | Was du schreibst | Was landet | | --- | --- | --- | | Der Durchlauf | `session()` + `agent()` | `agent_start`, `agent_end` | -| Jeder Tool-Aufruf | `tool_call()` | `tool_use`, `tool_result` | +| Jedes Tool | `tool_call()` | `tool_use`, `tool_result` | | Jeder Modellaufruf | Das `model_*`-Paar | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - In dem, was das Framework als Tool-Wrapper oder Middleware bezeichnet. + + In was auch immer das Framework als Tool-Wrapper oder Middleware bezeichnet. ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -264,20 +266,20 @@ Jedes Agent-Framework bietet dieselben drei Ansatzpunkte. Bilde sie ab und du ha - **Gibt es eine Node-, Step- oder Middleware-Grenze, die sichtbar sein soll?** Wickle sie in ein Hook-Paar – `hook_triggered` / `hook_completed` – nicht in ein verschachteltes `agent()`. `agent_id` ist eine Facette mit niedriger Kardinalität, und ein Eintrag pro Node würde sie überfluten. Hook-Spans werden genauso gerendert und liefern dir die Latenz pro Node. + **Hast du eine Node-, Step- oder Middleware-Grenze, die es wert ist, sichtbar zu sein?** Wickle sie in ein Hook-Paar – `hook_triggered` / `hook_completed` – und nicht in ein verschachteltes `agent()`. `agent_id` ist eine Facette mit niedriger Kardinalität, und ein Eintrag pro Node überfüllt sie. Hook-Spans werden genauso dargestellt und geben dir Latenz pro Node. - **Manuelle und automatische Instrumentierung ergänzen sich.** Ein Adapter, der innerhalb eines handgeschriebenen Scopes läuft, tritt der Session bei und wird dem Agenten untergeordnet – du erhältst einen einzigen Baum statt zwei. Das ist nützlich, wenn du ein Framework selbst instrumentierst und gleichzeitig ein unterstütztes verwendest. + **Manuell und automatisch komponieren.** Ein Adapter, der innerhalb eines manuell erstellten Scopes läuft, schließt sich dieser Session an und wird dem Agenten als übergeordnet zugeordnet – du bekommst einen Baum statt zwei. Das ist nützlich, wenn du ein Framework selbst instrumentierst, das neben einem unterstützten läuft. - Zwei Gründe, und die drei Ansatzpunkte oben sind die Antwort auf beide: + Zwei Gründe, und die drei Nahtpunkte oben sind die Antwort auf beide: - `autogen-core` wird seit September 2025 nicht mehr gepflegt. - - AG2 bietet keinen prozessweiten Registrierungspunkt, der den Hooks anderer Frameworks entspricht, sodass die Instrumentierung bedeutet, jeden Agenten an jeder Konstruktionsstelle zu wrappen. + - AG2 bietet keinen prozessweiten Registrierungspunkt, der dem Hook-System der anderen Frameworks entspricht – die Instrumentierung erfordert daher das Einwickeln jedes Agenten an jeder Konstruktionsstelle. - Durch manuelles Abbilden der Ansatzpunkte werden dieselben Events mit derselben Genauigkeit aufgezeichnet wie durch einen mitgelieferten Adapter. + Das manuelle Mappen der Nahtpunkte zeichnet dieselben Events mit derselben Genauigkeit auf wie ein mitgelieferter Adapter. ## Tiefer eintauchen @@ -286,9 +288,9 @@ Wie die Aufzeichnung tatsächlich funktioniert. Nichts davon ist nötig, um losz - + -Jede Aufzeichnung hat dieselbe Form: Ein Span öffnet sich, Arbeit schachtelt sich hinein, und jeder öffnende Event erhält einen schließenden. +Jede Aufzeichnung hat dieselbe Form: Ein Span öffnet sich, Arbeit wird darin verschachtelt, und jedes öffnende Event bekommt ein schließendes. ```mermaid flowchart LR @@ -300,9 +302,9 @@ flowchart LR C --> E(["agent_end"]) ``` -Das **Paar** ist die Grundeinheit. Jeder schließende Event trägt eine Dauer, die das SDK vom öffnenden Event an gemessen hat. +Das **Paar** ist die Einheit. Jedes schließende Event trägt eine Dauer, die das SDK vom öffnenden Event an misst. -Unten ist je ein echter Durchlauf pro Framework – aufgezeichnet aus den Beispielen, die mit dem SDK geliefert werden, Modellname normalisiert. Beachte, wie viel ein einzelner Aufruf zurückliefert. +Unten ist ein realer Durchlauf pro Framework – aufgenommen aus den Beispielen, die mit dem SDK mitgeliefert werden, Modellname normalisiert. Beachte, wie viel von einem einzigen Aufruf zurückkommt. @@ -323,7 +325,7 @@ Unten ist je ein echter Durchlauf pro Framework – aufgezeichnet aus den Beispi 14 +5.721s agent_end LangGraph · success ``` - Nodes werden zu Hook-Paaren, sodass du die Latenz pro Node erhältst, ohne die Agentenliste zu überfüllen. + Nodes werden zu Hook-Paaren, sodass du Latenz pro Node erhältst, ohne die Agentenliste zu überfüllen. @@ -340,7 +342,7 @@ Unten ist je ein echter Durchlauf pro Framework – aufgezeichnet aus den Beispi 10 +5.739s agent_end crew · success ``` - Die `role` jedes Agenten wird zu seinem Span-Namen, sodass Latenz und Token-Verbrauch nach Rolle aufgeschlüsselt werden. + Die `role` jedes Agenten wird zu seinem Span-Namen, sodass Latenz und Token-Verbrauch pro Rolle aufgeschlüsselt werden. @@ -360,7 +362,7 @@ Unten ist je ein echter Durchlauf pro Framework – aufgezeichnet aus den Beispi 26 +7.038s agent_end Agent · success ``` - Die Agentenschleife selbst ist sichtbar, nicht nur ihre Modellaufrufe. + Die Agent-Schleife selbst ist sichtbar, nicht nur ihre Modellaufrufe. @@ -375,7 +377,7 @@ Unten ist je ein echter Durchlauf pro Framework – aufgezeichnet aus den Beispi 8 +8.119s agent_end agent · success ``` - Keine Hook-Paare: Pydantic AI hat keine Node- oder Step-Grenze zum Einklammern. + Keine Hook-Paare: Pydantic AI hat keine Node- oder Step-Grenzen zum Einrahmen. @@ -388,17 +390,17 @@ Unten ist je ein echter Durchlauf pro Framework – aufgezeichnet aus den Beispi 6 +0.000s agent_end main · success ``` - Diese sendest du selbst. Dieselben Event-Typen, dieselbe Genauigkeit – es kostet dich die Aufrufstellen. + Du sendest diese selbst. Dieselben Event-Typen, dieselbe Genauigkeit – es kostet dich die Aufrufstellen. - + -**Es gibt kein Session-End-Event.** Eine Session ist nichts, das man schließt – sie ist eine Gruppe von Events, die dieselbe `session_id` teilen. +**Es gibt kein Session-End-Event.** Eine Session ist nichts, das du schließt – sie ist eine Gruppe von Events, die eine `session_id` teilen. -Der Status wird aus der Form des Traces abgeleitet: +Der Status wird aus der Form der Trace abgeleitet: | Status | Wann | | --- | --- | @@ -407,10 +409,10 @@ Der Status wird aus der Form des Traces abgeleitet: | `error` | Nichts ist offen, und mindestens ein Event ist fehlgeschlagen | | `done` | Nichts ist offen, und nichts ist fehlgeschlagen | -Eine Session endet also, wenn jedes Paar geschlossen wurde. Die Adapter senden `agent_end` für dich und schließen beim Beenden alles noch Offene, markiert als unvollständig – ein abgestürzter Durchlauf endet als `done` mit einer sichtbaren Lücke, statt hängenzubleiben. +Eine Session endet also, wenn jedes Paar geschlossen ist. Die Adapter senden `agent_end` für dich, und beim Teardown schließen sie alles noch Offene und markieren es als unvollständig – ein abgestürzter Durchlauf wird als `done` mit einer sichtbaren Lücke abgeschlossen, statt hängen zu bleiben. - Deshalb kann eine Session zwei Aufrufe überspannen. Ein LangGraph `interrupt()` pausiert den Durchlauf, der Root-Span bleibt absichtlich offen, und der wiederaufnehmende Aufruf schließt ihn. Beide Aufrufe sind eine Session. + Deshalb kann eine Session zwei Aufrufe umspannen. Ein LangGraph `interrupt()` pausiert den Durchlauf, der Root-Span bleibt absichtlich offen, und der fortsetzende Aufruf schließt ihn. Beide Aufrufe gehören zu einer Session. @@ -425,23 +427,23 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Sie explizit zu übergeben funktioniert ebenfalls und hat Vorrang. Ist nichts gebunden und nichts übergeben, wirft der Aufruf einen `TypeError`, der den Fix benennt, statt ein Event ohne Session zu senden, das die Verarbeitung überspringen und mit `200` antworten würde. +Sie explizit zu übergeben funktioniert weiterhin und hat Vorrang. Wenn nichts gebunden und nichts übergeben wurde, wirft der Aufruf einen `TypeError`, der den Fix benennt, anstatt ein Event ohne Session zu senden, das beim Ingest übersprungen und mit `200` beantwortet werden würde. -Scopes binden Identität an Kontextvariablen. Diese werden automatisch in asyncio-Tasks weitergegeben, aber nicht in neue Threads – wickle einen Worker in `failproofai_sdk.propagate()`. +Scopes binden die Identität auf Kontextvariablen. Diese werden automatisch in asyncio-Tasks übertragen, aber nicht in neue Threads – wickle einen Worker in `failproofai_sdk.propagate()` ein. #### Wer welche ID vergibt | ID | Vergeben von | Hinweise | | --- | --- | --- | -| `session_id` | Dir oder dem SDK | `session("chat-42")` wird unverändert verwendet; wird sie weggelassen, generiert das SDK ein `uuid4().hex` | +| `session_id` | Dir oder dem SDK | `session("chat-42")` wird direkt verwendet; weggelassen generiert das SDK ein `uuid4().hex` | | `agent_id` | Dir oder dem Framework | Aus `agent("analyst")`, einer CrewAI-`role`, einem `FunctionAgent.name`. Ein UUID-ähnlicher Wert wird abgelehnt und ersetzt | -| `tool_call_id`, `hook_id`, `request_id` | Dir oder dem Framework | Adapter verwenden die eigenen Run-IDs des Frameworks, weshalb Paare auch Thread-Wechsel überleben | -| **Event-ID** | **Cloud, bei der Verarbeitung** | Das SDK sendet keine | -| **`dedup_key`** | **Cloud, bei der Verarbeitung** | Ein Hash aus Org, Session, Zeitstempel, Typ und Payload. Das ist die echte Identität – sie lässt einen wiederholten Batch zusammenfallen statt zu duplizieren | +| `tool_call_id`, `hook_id`, `request_id` | Dir oder dem Framework | Adapter verwenden die eigenen Run-IDs des Frameworks wieder, weshalb Paare Thread-Wechsel überleben | +| **Event-ID** | **Cloud beim Ingest** | Das SDK sendet keine | +| **`dedup_key`** | **Cloud beim Ingest** | Ein Hash aus Org, Session, Timestamp, Typ und Payload. Das ist die echte Identität – sie sorgt dafür, dass ein wiederholter Batch zusammengefasst statt dupliziert wird | #### Wie Adapter `session_id` auflösen -Erste Übereinstimmung gewinnt: +Der erste Treffer gewinnt: 1. Eine explizite `session_id`-Option 2. Metadaten pro Aufruf @@ -449,11 +451,11 @@ Erste Übereinstimmung gewinnt: 4. Framework-Metadaten 5. Die eigene Run-ID des Frameworks -Sie wird nie erfunden, solange eine dieser Quellen vorhanden ist – eine synthetisierte ID würde einen Durchlauf auf mehrere Sessions aufteilen. +Sie wird nie erfunden, solange eines davon existiert – eine synthetisierte ID würde einen Durchlauf auf mehrere Sessions aufteilen. -#### `agent_id` niedrig-kardinal halten +#### `agent_id` niedrig halten -Es ist die primäre Facette auf jeder Dashboard-Ansicht und eine `LowCardinality(String)`-Spalte. Ein per-Run-Wert verschlechtert die Spalte und füllt das Filter-Dropdown mit einem Eintrag pro Durchlauf. +Sie ist die primäre Facette auf jeder Dashboard-Ansicht und eine `LowCardinality(String)`-Spalte. Ein Wert pro Durchlauf degradiert die Spalte und füllt das Filter-Dropdown mit einem Eintrag pro Durchlauf. Adapter schützen diese Spalte für dich: @@ -461,19 +463,19 @@ Adapter schützen diese Spalte für dich: | --- | --- | --- | | `3f9a1c2b-…` (eine UUID) | `main` | Nichts Lesbares zu behalten | | Ein langer reiner Hex-String | `main` | Dasselbe | -| `agent-3f9a1c2b-…` | `agent` | Per-Run-ID entfernt, lesbarer Teil behalten | +| `agent-3f9a1c2b-…` | `agent` | Pro-Durchlauf-ID entfernt, lesbarer Teil behalten | | `agent-v2` | `agent-v2` | Kurze Segmente werden unverändert gelassen | | `step-3` | `step-3` | Dasselbe | -Die echte ID wird auf `fw_agent_id` / `fw_run_id` gespeichert, wo sie abfragbar bleibt, ohne eine Facette zu sein. +Die echte ID wird auf `fw_agent_id` / `fw_run_id` behalten, wo sie abfragbar bleibt, ohne eine Facette zu sein. - **Dieser Schutz betrifft nur Labels, die das *Framework* gewählt hat.** Eine `agent_id`, die du selbst übergibst – an `event.*` oder an `failproofai_sdk.agent(...)` – wird exakt so aufgezeichnet. Ein explizites Argument stillschweigend umzuschreiben wäre schlimmer als die Kardinalität, die es verhindert – benenne deine eigenen Spans entsprechend. + **Diese Schutzmaßnahme betrifft nur Labels, die das *Framework* gewählt hat.** Eine `agent_id`, die du selbst übergibst – an `event.*` oder an `failproofai_sdk.agent(...)` – wird genau so aufgezeichnet. Ein explizites Argument stillschweigend umzuschreiben wäre schlimmer als die Kardinalität, die es verhindert – benenne deine eigenen Spans entsprechend. - + | Gruppe | Events | | --- | --- | @@ -486,23 +488,23 @@ Die echte ID wird auf `fw_agent_id` / `fw_run_id` gespeichert, wo sie abfragbar Welches Framework was aufzeichnet, gemessen aus den obigen Durchläufen: -| Event | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Eigene | +| Event | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | -| Agent start und end | Ja | Ja | Ja | Ja | Du | -| Model request und response | Ja | Ja | Ja | Ja | Du | -| Tool use und result | Ja | Ja | Ja | Ja | Du | -| Hook triggered und completed | Node | Task | Step | — | Du | +| Agent Start und End | Ja | Ja | Ja | Ja | Du | +| Model Request und Response | Ja | Ja | Ja | Ja | Du | +| Tool Use und Result | Ja | Ja | Ja | Ja | Du | +| Hook Triggered und Completed | Node | Task | Step | — | Du | | Error | Ja | Ja | Ja | Ja | Automatisch | -| Human wait und input | Ja | Ja | Ja | — | Du | -| Agent pause und resume | Ja | Ja | Ja | — | Du | +| Human Wait und Input | Ja | Ja | Ja | — | Du | +| Agent Pause und Resume | Ja | Ja | Ja | — | Du | -Ein Strich bedeutet, das Framework kennt dieses Konzept nicht. `human_pause` und `human_interrupt` beschreiben eine *Person*, die auf den Agenten einwirkt – kein Framework signalisiert das, sende diese Events selbst. +Ein Strich bedeutet, das Framework kennt dieses Konzept nicht. `human_pause` und `human_interrupt` beschreiben eine *Person*, die auf den Agenten einwirkt – das signalisiert kein Framework. Diese musst du selbst senden. -Ein Event kommt nie allein. Eines öffnet einen Span, eines schließt ihn, und das schließende Event trägt eine Dauer, die das SDK vom öffnenden Event an gemessen hat. +Ein Event kommt nie allein. Eines öffnet einen Span, eines schließt ihn, und das schließende Event trägt eine Dauer, die das SDK vom öffnenden Event an misst. | Öffnet | Schließt | Das schließende Event trägt | | --- | --- | --- | @@ -510,28 +512,28 @@ Ein Event kommt nie allein. Eines öffnet einen Span, eines schließt ihn, und d | `model_request` | `model_response` | Tokens, `stop_reason`, Latenz | | `tool_use` | `tool_result` | `output` oder `error`, Dauer | | `hook_triggered` | `hook_completed` | `outcome`, Dauer | -| `agent_pause` | `agent_resume` | Wie lange die Pause dauerte | -| `human_wait` | `human_input` | Die Antwort und wie lange die Person brauchte | +| `agent_pause` | `agent_resume` | Wie lange die Pause gedauert hat | +| `human_wait` | `human_input` | Die Antwort und wie lange die Person gebraucht hat | - Ein öffnendes Event ohne schließendes ist ein Span, der nie endet. Die Session wird als noch laufend angezeigt, für immer, und ihre aktive Dauer wächst weiter. Das ist der Fehlerfall, auf den man achten muss, wenn man manuell instrumentiert. + Ein öffnendes Event ohne schließendes ist ein Span, der nie endet. Die Session wird als noch laufend angezeigt, für immer, und ihre aktive Dauer wächst weiter. Das ist der Fehlerfall, auf den du achten musst, wenn du manuell instrumentierst. #### Korrelationsregeln -- Verwende dieselbe `tool_call_id`, `hook_id`, `pause_id` oder `input_id` für das passende Abschluss-Event. -- Das SDK berechnet `duration_ms` für `tool_result`, `hook_completed`, `agent_resume` und `human_input`. Diese Methoden werfen einen `ValueError`, wenn du es übergibst. -- `duration_ms` **wird** bei `model_response` akzeptiert, weil nur der Aufrufer die echte Provider-Latenz kennt. Es muss ein Integer sein – ein Float wirft am Aufrufpunkt einen `ValueError`, weil der Server die Spalte als vorzeichenlose 32-Bit-Ganzzahl liest und für alles andere NULL speichern würde. -- Korrelationsschlüssel sind nach Art und Session begrenzt, sodass ein Tool-Aufruf und ein Hook gefahrlos dieselbe ID teilen dürfen, und zwei gleichzeitige Sessions können dieselben IDs ohne Kollision wiederverwenden. Sie sind nicht nach Agent begrenzt: Ein Paar, das unter einem Agenten geöffnet und unter einem anderen geschlossen wird, korreliert trotzdem – das ist der normale Fall in Multi-Agenten-Frameworks. -- `request_id` paart `model_request` mit `model_response`. Ohne sie werden Model-Events pro Agent der Reihe nach gepaart, sodass gleichzeitige Aufrufe falsch zugeordnet werden. -- Ein über Prozesse hinweg gespaltenes Paar korreliert nachgelagert noch, aber das SDK kann seine In-Process-Dauer nicht berechnen. -- Die Pending-Map hält höchstens 10.000 Starts und verdrängt den ältesten Eintrag, wenn sie voll ist. +- Verwende dieselbe `tool_call_id`, `hook_id`, `pause_id` oder `input_id` für das passende Abschlussevent. +- Das SDK berechnet `duration_ms` für `tool_result`, `hook_completed`, `agent_resume` und `human_input`. Es an diese Methoden zu übergeben wirft einen `ValueError`. +- `duration_ms` **wird** bei `model_response` akzeptiert, weil nur der Aufrufer die echte Provider-Latenz kennt. Es muss ein Integer sein – ein Float wirft am Aufrufpunkt einen `ValueError`, da der Server die Spalte als vorzeichenlosen 32-Bit-Integer liest und sonst NULL speichern würde. +- Korrelationsschlüssel sind nach Art und Session begrenzt, sodass ein Tool-Aufruf und ein Hook sicher dieselbe ID teilen dürfen, und zwei parallele Sessions dieselben IDs wiederverwenden können, ohne zu kollidieren. Sie sind nicht nach Agent begrenzt: Ein Paar, das unter einem Agenten geöffnet und unter einem anderen geschlossen wird, korreliert trotzdem – das ist der Normalfall in Multi-Agent-Frameworks. +- `request_id` paart `model_request` mit `model_response`. Ohne sie werden Model-Events in Reihenfolge pro Agent gepaart, sodass parallele Aufrufe falsch gepaart werden. +- Ein über Prozesse hinweg aufgeteiltes Paar korreliert noch auf der Serverseite, aber das SDK kann seine In-Process-Dauer nicht berechnen. +- Die Pending-Map hält maximal 10.000 Starts und entfernt den ältesten Eintrag, wenn sie voll ist. -Die Installation von `failproofai-sdk` installiert alles, alle vier Adapter inklusive. Die Extras holen das **Framework**, nicht den Adapter. +Die Installation von `failproofai-sdk` installiert alles, alle vier Adapter inklusive. Die Extras ziehen das **Framework** nach, nicht den Adapter. ```python import failproofai_sdk # lädt nichts außerhalb der Standardbibliothek @@ -541,7 +543,7 @@ failproofai_sdk.instrument() # importiert nur die Adapter, die du tatsächlich `import failproofai_sdk` ist vertraglich abhängigkeitsfrei, erzwungen durch einen Test, der das gebaute Wheel mit `--no-deps` installiert, und einen weiteren, der beweist, dass kein Framework `sys.modules` erreicht. - Es gibt kein `failproofai_sdk.crewai`-Attribut. Adapter werden bewusst nicht im Top-Level-Paket exponiert: Das Berühren eines Adapters würde das Framework als Nebeneffekt eines Attributzugriffs importieren und das Versprechen der Abhängigkeitsfreiheit brechen. Verwende `instrument()`. + Es gibt kein `failproofai_sdk.crewai`-Attribut. Adapter werden absichtlich nicht am Top-Level-Paket exponiert: Darauf zuzugreifen würde das Framework als Nebeneffekt des Attributzugriffs importieren und das Null-Abhängigkeits-Versprechen brechen. Verwende `instrument()`. ```python @@ -557,7 +559,7 @@ failproofai_sdk.uninstrument("crewai") # rückgängig machen | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -Die automatische Erkennung liest `sys.modules`, nicht die installierte Paketliste – ein Framework, das installiert, aber nie importiert wurde, wird nicht instrumentiert und nie in deinem Namen importiert. Um zu sehen, was verdrahtet ist: +Die Auto-Erkennung liest `sys.modules`, nicht die Liste installierter Pakete – ein installiertes, aber nie importiertes Framework wird nicht instrumentiert und nie in deinem Namen importiert. Um zu sehen, was verdrahtet ist: ```python from failproofai_sdk.integrations import active, available @@ -567,20 +569,20 @@ active() # ('langchain',) ``` - **`instrument("crewai")` auf einem Rechner ohne CrewAI wirft keine Exception.** Es protokolliert eine Warnung und gibt `()` zurück, sodass ein fehlendes Framework nie einen Prozess beendet, der auch andere instrumentiert. + **`instrument("crewai")` auf einer Maschine ohne CrewAI wirft keine Exception.** Es loggt eine Warnung und gibt `()` zurück, sodass ein fehlendes Framework nie einen Prozess zum Absturz bringt, der auch andere instrumentiert. - Die Warnung enthält den zugrundeliegenden `ImportError`, und diese Meldung nennt den genauen Installationsbefehl – der Fix steckt also in deinen Logs, nicht versteckt. + Die Warnung enthält den zugrunde liegenden `ImportError`, und diese Meldung nennt den genauen Installationsbefehl – die Lösung steht also in deinen Logs, nicht versteckt. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Setze `FAILPROOFAI_SDK_STRICT=1`, um stattdessen eine Exception zu werfen. Dieses Flag wird **einmal gelesen und gecacht**, also setze es vor dem Prozessstart, nicht mittendrin. + Setze `FAILPROOFAI_SDK_STRICT=1`, damit stattdessen eine Exception ausgelöst wird. Dieses Flag wird **einmal gelesen und gecacht**, also exportiere es vor dem Start deines Prozesses, statt es mittendrin zu setzen. - **`instrument()` muss *nach* dem Framework-Import aufgerufen werden.** Die automatische Erkennung liest `sys.modules`, ein nackter Aufruf vor dem Import findet nichts, installiert nichts und gibt `()` zurück. + **`instrument()` muss *nach* deinem Framework-Import kommen.** Die Auto-Erkennung liest `sys.modules`, also findet ein bloßer Aufruf vor dem Import nichts, installiert nichts und gibt `()` zurück. @@ -592,7 +594,7 @@ import langchain # zu spät, nichts ist verdrahtet ``` ```python Right -import langchain # erst das Framework importieren +import langchain # Framework zuerst importieren import failproofai_sdk failproofai_sdk.instrument() # findet es -> ('langchain',) @@ -601,12 +603,12 @@ failproofai_sdk.instrument() # findet es -> ('langchain',) ```python Right, order-proof import failproofai_sdk -# Den Namen anzugeben importiert den Adapter auf Anfrage, funktioniert also von überall. +# Den Namen anzugeben importiert den Adapter auf Anfrage, also funktioniert das überall. failproofai_sdk.instrument("langchain") ``` -Machst du das falsch, läuft der Prozess mit importiertem SDK, scheinbar installiertem Adapter und **keinem einzigen gesendeten Event**. Es protokolliert eine Warnung, die genau das sagt – prüfe also zuerst deine Logs, wenn ein Durchlauf nichts aufzeichnet. +Machst du das falsch, läuft der Prozess mit importiertem SDK, scheinbar installiertem Adapter und **keinem einzigen gesendeten Event**. Es loggt eine Warnung, die genau das sagt – also prüfe zuerst deine Logs, wenn ein Durchlauf nichts aufzeichnet. @@ -616,81 +618,83 @@ Machst du das falsch, läuft der Prozess mit importiertem SDK, scheinbar install flowchart LR A["Dein Agent"] --> B["Adapter"] B --> C["Writer
In-Memory-Queue"] - C -->|"alle 0,5 s"| D["Spool
JSONL auf Disk"] - D --> E["Failproof-Daemon"] + C -->|"alle 0,5s"| D["Spool
JSONL auf Disk"] + D --> E["Failproof Daemon"] E -->|"HTTPS"| F["Cloud"] ``` | Stufe | Aufgabe | Läuft in | | --- | --- | --- | | Adapter | Übersetzt einen Framework-Callback in einen von 15 Event-Typen | Dein Prozess | -| Writer | Reiht Events ein, bündelt sie, schreibt JSONL atomar | Dein Prozess, Hintergrund-Thread | +| Writer | Reiht in Warteschlange, bündelt, schreibt JSONL atomar | Dein Prozess, Hintergrund-Thread | | Spool | Dauerhafter Übergabepunkt, überlebt den Prozessabbruch | Lokale Disk | -| Daemon | Überwacht den Spool, sendet Batches, löscht Versendetes | Deine Maschine | -| Ingest | Vergibt Row-ID und Dedup-Schlüssel, befördert abfragbare Spalten | Cloud | +| Daemon | Beobachtet den Spool, verschickt Batches, löscht Versendetes | Deine Maschine | +| Ingest | Weist Row-ID und Dedup-Key zu, befördert abfragbare Spalten | Cloud | -Der Spool macht das sicher: Dein Agent blockiert nie auf das Netzwerk, und ein Cloud-Ausfall bedeutet ein wachsendes Verzeichnis statt verlorene Events. +Der Spool macht das Ganze sicher: Dein Agent blockiert nie auf das Netzwerk, und ein Cloud-Ausfall bedeutet ein wachsendes Verzeichnis statt verlorener Events. -Jeder Flush schreibt eine Batch-Datei, zuerst `.tmp`, dann `fsync`, dann ein atomares Umbenennen: +Jeder Flush schreibt eine Batch-Datei: zuerst `.tmp`, dann `fsync`, dann ein atomares Umbenennen: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Der Daemon liest nur `.jsonl`, kann also nie eine halb geschriebene Datei lesen. Der Dateiname enthält Zeitstempel, Prozess-ID und Sequenznummer, sodass zwei Prozesse, die in derselben Millisekunde flushen, nicht kollidieren können. Die Queue ist auf 10.000 Events begrenzt; darüber hinaus werden die ältesten verworfen und protokolliert. +Der Daemon liest nur `.jsonl`, kann also nie eine halb geschriebene Datei lesen. Der Dateiname trägt Timestamp, Prozess-ID und Sequenznummer, sodass zwei Prozesse, die in derselben Millisekunde flushen, nicht kollidieren können. Die Queue ist auf 10.000 Events begrenzt; darüber hinaus werden die ältesten gelöscht und geloggt. - **`collector.redact` ist auch für SDK-Events standardmäßig auf `minimal` gesetzt.** Das SDK bereinigt, bevor es einen Batch auf Disk schreibt, und der Daemon wiederholt denselben deterministischen Durchlauf vor dem Upload, sodass Batches älterer SDKs geschützt sind. + **`collector.redact` gilt nicht für deine SDK-Events.** Es sieht sie nie. -Der Daemon liest jeden Batch und wendet die Bereinigung im Speicher vor dem Upload an. Er schreibt die gelesene Spool-Datei nicht neu. +Der Daemon **versendet** deine Batches. Er öffnet oder überschreibt sie nicht. -| Events | Geschrieben von | Wo minimale Bereinigung läuft | +| Events | Geschrieben von | Durch `collector.redact` bereinigt? | | --- | --- | --- | -| CLI-Session-Transkripte | Der Daemon | Bevor der Daemon den Batch schreibt | -| Hook-Aktivität | Der Daemon | Bevor der Daemon den Batch schreibt | -| **Alles, was das SDK sendet** | **Dein Prozess** | **Bevor das SDK den Batch schreibt und erneut vor dem Daemon-Upload** | +| CLI-Session-Transkripte | Dem Daemon | Ja | +| Hook-Aktivität | Dem Daemon | Ja | +| **Alles, was das SDK sendet** | **Deinem Prozess** | **Nein** | -Setze `collector.redact` nur auf `off`, wenn verbatim Payloads eine explizite Anforderung sind; SDK und Daemon beachten diese Einstellung beide. Minimale Bereinigung erkennt gängige API-Schlüssel, Bearer-Tokens, JWTs und Secret-Zuweisungen. Sie kann keine beliebig sensiblen Freitexte erkennen. +Bereinigung läuft dort, wo der Daemon seine *eigenen* Events schreibt – nicht wo Batches *versendet* werden. Ein Prompt oder ein Tool-Argument mit einem API-Key enthält ihn also noch beim Ankommen. + +Das ist beabsichtigt. Das sind deine eigenen Instrumentierungsaufrufe, und sie im Transit umzuschreiben würde bedeuten, dass die Events, die du empfängst, nicht die Events sind, die du gesendet hast. **Du kontrollierst Payloads an der Quelle, an zwei Stellen:** - - Deaktiviere die Content-Erfassung im Adapter. **Der Optionsname unterscheidet sich, und ein Adapter hat keinen** – das ist kein universeller Schalter: + - Schalte Content-Capture am Adapter aus. **Der Optionsname unterscheidet sich, und ein Adapter hat keinen** – das ist kein universeller Schalter: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **kein Content-Schalter**; `session_id` ist die einzige Option, die es liest, also werden Prompts und Completions immer aufgezeichnet. + - CrewAI — **kein Content-Schalter**; `session_id` ist die einzige Option, die es liest – Prompts und Completions werden also immer aufgezeichnet. - `instrument()` ignoriert Optionen, die ein Adapter nicht liest, sodass ein falscher Name nichts auslöst und nichts ändert. - - Übergib das Geheimnis erst gar nicht an `input=`. + `instrument()` ignoriert Optionen, die ein Adapter nicht liest, sodass das Übergeben des falschen Namens nichts auslöst und nichts ändert. + - Gib das Geheimnis von vornherein nicht an `input=` weiter. - `collector.redact` ist Defense-in-Depth, kein Ersatz für beides. + `collector.redact` ist kein Ersatz für beides. - **Ein leeres Spool-Verzeichnis ist der gesunde Zustand.** Verwende es nicht zur Lieferkontrolle. + **Ein leeres Spool-Verzeichnis ist der gesunde Zustand.** Verwende es nicht zur Lieferungsüberprüfung. -Der Daemon löscht jeden Batch innerhalb von Millisekunden nach dem Versand, sodass ein `ls` mit dem Collector konkurriert und nur einen Bruchteil des Gesendeten zeigt – nicht zu unterscheiden von einem SDK, das nichts aufgezeichnet hat. +Der Daemon löscht jeden Batch innerhalb von Millisekunden nach dem Versenden, sodass ein `ls` mit dem Collector um die Wette läuft und nur einen Bruchteil der gesendeten Events zeigt – nicht zu unterscheiden von einem SDK, das nichts aufgezeichnet hat. -Um zu bestätigen, dass Events tatsächlich angekommen sind, prüfe das Dashboard. Um den Spool beim Füllen zu beobachten, stoppe zuerst den Daemon. +Um zu bestätigen, dass Events tatsächlich angekommen sind, prüfe das Dashboard. Um den Spool beim Füllen zu beobachten, stoppe den Daemon zuerst. -Jeder Callback läuft in einem Wrapper, dessen einzige Aufgabe das Weiterleiten ist, sodass dein Aufruf in genau einem `try` sitzt und alles, was das SDK tut, außerhalb davon passiert. +Jeder Callback läuft innerhalb eines Wrappers, dessen einzige Aufgabe es ist, weiterzuwerfen – dein Aufruf sitzt also in genau einem `try`, und alles, was das SDK tut, geschieht außerhalb davon. | Was passiert | Ergebnis | | --- | --- | -| Ein Hook wirft eine Exception | Einmal mit Traceback protokolliert. Dein Aufruf ist unberührt | -| Derselbe Hook wirft dreimal | Dieser eine Hook wird für den Rest des Prozesses deaktiviert, mit einer Fehlerzeile | -| `FAILPROOFAI_SDK_STRICT=1` ist gesetzt | Die Exception wird stattdessen weitergeleitet | -| Eine Framework-Version liegt außerhalb des getesteten Bereichs | Einmalige Warnung, wird trotzdem instrumentiert | -| Eine einzelne Fähigkeit fehlt | Genau dieser Hook wird deaktiviert, nie der gesamte Adapter | +| Ein Hook wirft | Einmalig mit Traceback geloggt. Dein Aufruf ist nicht betroffen | +| Derselbe Hook wirft dreimal | Dieser eine Hook ist für den Rest des Prozesses deaktiviert, mit einer Fehlerzeile | +| `FAILPROOFAI_SDK_STRICT=1` ist gesetzt | Die Exception wird stattdessen weitergegeben | +| Eine Framework-Version liegt außerhalb des getesteten Bereichs | Einmalige Warnung, Instrumentierung trotzdem | +| Eine einzelne Fähigkeit fehlt | Nur dieser eine Hook ist deaktiviert, nie der gesamte Adapter | -Der Standard ist in Produktion richtig und beim Debuggen falsch, weil er nur beweisen kann, dass es nicht abgestürzt ist. Setze `FAILPROOFAI_SDK_STRICT=1`, um einen geschluckten Fehler laut zu machen. +Der Standard ist in Produktion richtig und beim Debuggen falsch, weil er nur beweisen kann „es ist nicht abgestürzt". Setze `FAILPROOFAI_SDK_STRICT=1`, um einen verschluckten Fehler laut zu machen. @@ -700,34 +704,34 @@ Der Standard ist in Produktion richtig und beim Debuggen falsch, weil er nur bew - Ein öffnendes Event hat kein schließendes: ein `model_request` ohne `model_response` oder ein `tool_use` ohne `tool_result`. Verwende die Scopes, die das Paar auch dann garantieren, wenn der Rumpf eine Exception wirft. Rufst du die Event-Methoden direkt auf, verwende `try` und `finally`. + Ein öffnendes Event hat kein schließendes: ein `model_request` ohne `model_response` oder ein `tool_use` ohne `tool_result`. Verwende die Scopes, die das Paar auch dann garantieren, wenn der Body eine Exception wirft. Wenn du die Event-Methoden direkt aufrufst, verwende `try` und `finally`. - Es wird vom passenden öffnenden Event aus gemessen und daher bei `tool_result`, `hook_completed`, `agent_resume` und `human_input` abgelehnt. Bei `model_response` wird es akzeptiert, weil nur du die echte Provider-Latenz kennst, und es muss ein Integer sein. + Es wird vom passenden öffnenden Event an gemessen und wird daher bei `tool_result`, `hook_completed`, `agent_resume` und `human_input` abgelehnt. Bei `model_response` wird es akzeptiert, weil nur du die echte Provider-Latenz kennst, und es muss ein Integer sein. - Der Thread hat den Kontext nie geerbt. Wickle das Callable in `failproofai_sdk.propagate()`. Siehe [Threads und async](#threads-and-async). + Der Thread hat den Kontext nie geerbt. Wickle das Callable in `failproofai_sdk.propagate()` ein. Siehe [Threads und Async](#threads-und-async). - Zusätzliche Felder werden zuletzt zusammengeführt, sodass eines mit dem Namen eines echten Felds wie `model` oder `outcome` dieses überschreiben und eine gespeicherte Spalte verändern würde. Verwende eigene Namespaces; die Adapter nutzen ein `fw_`-Präfix. + Zusätzliche Felder werden zuletzt zusammengeführt, sodass eines mit dem Namen eines echten Feldes wie `model` oder `outcome` dieses überschreiben und eine gespeicherte Spalte verändern würde. Verwende einen Namespace; die Adapter nutzen das Präfix `fw_`. - - `agent_id` ist eine Facette mit niedriger Kardinalität, und du hast eine Run-ID hineingesteckt. Verwende eine Rollen- oder Node-Bezeichnung und lege die echte ID in ein Payload-Feld. + + `agent_id` ist eine Facette mit niedriger Kardinalität, und du hast eine Run-ID hineingespeichert. Verwende eine Rolle oder einen Node-Namen und leg die echte ID in ein Payload-Feld. ## Weiter - + Paare, IDs, Session-Lebenszyklus und Zustellung. - - Verfolge die Kausalität durch die soeben erfasste Session. + + Folge der Kausalität durch die soeben aufgezeichnete Session. LangGraph, CrewAI, LlamaIndex und Pydantic AI. diff --git a/docs/de/start/quickstart.mdx b/docs/de/start/quickstart.mdx index 53393acf..95748629 100644 --- a/docs/de/start/quickstart.mdx +++ b/docs/de/start/quickstart.mdx @@ -1,15 +1,15 @@ --- title: "Quickstart" -description: "Agentensitzung aufzeichnen, einen Fehler finden und dessen Verhinderung einrichten." +description: "Eine Agentensitzung aufzeichnen, einen Fehler finden und mit der Prävention beginnen." icon: "zap" --- -Dieser Quickstart verbindet eine Maschine mit der Sitzungserfassung, führt ein Audit durch und stellt eine Richtlinie bereit. Nutze die Skill-basierte Einrichtung oder folge den manuellen Schritten. +Dieser Quickstart verbindet eine Maschine mit der Berichterstattung, führt ein Audit durch und setzt eine Richtlinie ein. Verwende die Skill-Methode oder folge den manuellen Schritten. -**Welcher Weg passt zu dir?** Wenn dein Agent in einem der 12 unterstützten [Harnesses](/de/reference/harnesses) läuft — einer Coding-CLI oder einem Gateway wie Hermes oder OpenClaw — folge den nachstehenden Schritten; du benötigst Node.js 20.9 oder höher. Wenn dein Agent kein Harness hat, instrumentiere ihn mit dem [Python SDK](/de/reference/custom-agents) für Tracing und Audits, und steige dann bei [Ersten Fehlercheck ausführen](/de/start/first-audit) wieder ein; die Durchsetzung erfordert auf diesem Weg einen Hook in deiner Laufzeitumgebung. +**Welcher Weg passt zu dir?** Wenn dein Agent in einem der 12 unterstützten [Harnesses](/de/reference/harnesses) läuft – einer Coding-CLI oder einem Gateway wie Hermes oder OpenClaw – folge den Schritten unten; du benötigst Node.js 20.9 oder höher. Wenn dein Agent kein Harness hat, instrumentiere ihn mit dem [Python SDK](/de/reference/custom-agents) für Tracing und Audits, und steige dann bei [Erste Fehlerprüfung ausführen](/de/start/first-audit) wieder ein; die Durchsetzung auf diesem Weg erfordert einen Hook in deiner Runtime. - + ```bash @@ -21,19 +21,19 @@ Dieser Quickstart verbindet eine Maschine mit der Sitzungserfassung, führt ein Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Dein Agent analysiert das Projekt, wählt die passende Integration, führt die Einrichtung durch und verifiziert sie. Einzelne Skills und erweiterte Installationsoptionen findest du im [FailproofAI Skills-Repository](https://github.com/FailproofAI/skills). + Dein Agent untersucht das Projekt, wählt die passende Integration, führt das Setup durch und verifiziert es. Einzelne Skills und erweiterte Installationsoptionen findest du im [FailproofAI Skills-Repository](https://github.com/FailproofAI/skills). - - ## Bevor du beginnst + + ## Vorbereitung 1. Öffne das [Failproof AI Dashboard](https://app.befailproof.ai) und erstelle ein Konto oder melde dich mit deiner Arbeits-E-Mail an. 2. Gehe zu **Administration → Keys** und erstelle einen Schlüssel mit `events:add` und `policies:pull`. -3. Kopiere das einmalige Secret und speichere es auf der Zielmaschine: +3. Kopiere das einmalige Secret und lies es dann in eine Shell auf der Zielmaschine ein. `read -s` liest es über eine Eingabeaufforderung ohne Echo, sodass es nie in einem Befehl erscheint: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## Installation @@ -42,12 +42,18 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - Sitzungstranskripte werden standardmäßig übertragen. Füge `--no-transcripts` hinzu, um nur Hook-Aktivitäten und Richtlinienentscheidungen ohne Transkriptinhalt zu melden. + Dieser eine Befehl erledigt das gesamte Setup: Er installiert den lokalen Daemon (einmalig als root), verbindet Hooks mit jeder gefundenen Agent-CLI und verbindet diese Maschine mit der Cloud. Den Schlüssel über die Umgebungsvariable statt mit `--token` zu übergeben hält ihn aus `ps` heraus, wo alle Benutzer der Maschine die Argumente eines Befehls lesen können. Aus dem Shell-Verlauf hält ihn das nicht heraus – dafür ist das Einlesen mit `read -s` zuständig. In CI sollte er als maskiertes Secret injiziert werden, und Shell-Tracing (`set -x`) sollte deaktiviert sein, da der Trace sonst den Schlüssel ausgibt. - Wenn diese Maschine bereits einen Agentenverlauf hat, kannst du die letzten sieben Tage vorab anzeigen und importieren — warte anschließend, bis die Übertragung abgeschlossen ist. Überspringe diesen Schritt bei einer neuen Maschine. + Sitzungstranskripte werden standardmäßig gesendet. Füge `--no-transcripts` hinzu, um nur Hook-Aktivitäten und Richtlinienentscheidungen ohne Transkriptinhalt zu melden. + + + Verwende hier nicht `failproofai config --connect `. Dieses Flag meldet eine Maschine an, die **bereits** eingerichtet ist, und kehrt sofort zurück – ohne Daemon, ohne Hooks – die Maschine würde in der Cloud erscheinen, ohne etwas zu erfassen oder durchzusetzen. + + + Wenn diese Maschine bereits einen Agent-Verlauf hat, zeige die letzten sieben Tage in der Vorschau an, importiere sie und warte auf den Abschluss der Übertragung. Überspringe diesen Schritt auf einer neuen Maschine. ```bash failproofai backfill --since 7d --dry-run @@ -57,28 +63,39 @@ export FAILPROOFAI_KEY="" Öffne **Sessions** in Failproof AI und wähle eine importierte Sitzung aus. - - Damit wird Failproof AI an dein Harness angebunden und die 39 integrierten Richtlinien werden installiert. Nutze sie, um lokale Richtlinienentscheidungen einzusehen und die Durchsetzung auszuprobieren, bevor Failproof AI deine Sitzungen auditiert und Richtlinien für deine Agenten erstellt. - - Lass den Installer dein Harness automatisch erkennen oder gib eines explizit an. Alle 12 sind gültige `--cli`-Werte — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + Der vorherige Schritt hat bereits alle erkannten Agent-CLIs verbunden. Führe ihn für ein einzelnes Harness explizit erneut aus, wenn nötig, oder um ein nachträglich installiertes Harness hinzuzufügen. Alle 12 sind gültige `--cli`-Werte — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # eine Coding-CLI failproofai policies --install --cli hermes --scope user # ein Slack/Telegram-Gateway ``` - Das Blockieren eines Tool-Aufrufs vor dessen Ausführung ist auf allen 12 verifiziert. Turn-End-Gates sind auf 8 verifiziert — die harness-spezifische Matrix findest du unter [Durchsetzungsfähigkeit](/de/reference/harnesses#enforcement-capability). + Das Blockieren eines Tool-Aufrufs vor seiner Ausführung ist auf allen 12 verifiziert. Turn-End-Gates sind auf 8 verifiziert — die harness-spezifische Matrix ist unter [Durchsetzungsfähigkeit](/de/reference/harnesses#enforcement-capability) zu finden. + + + Das Verbinden der Hooks aktiviert keine Richtlinie. Das Setup wählt bewusst keine aus – diese Entscheidung liegt bei dir – nimm daher ein Paket: + + ```bash + failproofai policies add FailproofAI/policies + ``` + + Das Paket wird von seinem GitHub-Release abgerufen, per Prüfsumme verifiziert und auf den exakt aufgelösten Tag festgelegt. Es enthält 38 Richtlinien und aktiviert die 10, die sein Manifest als sicher für den unbeaufsichtigten Betrieb markiert. Nutze sie, um lokale Richtlinienentscheidungen zu sehen und die Durchsetzung auszuprobieren, bevor Failproof AI deine Sitzungen auditiert und Richtlinien für deine Agenten erstellt. + + Lies ein Paket vor der Übernahme mit `failproofai policies show /`, und informiere dich unter [Richtlinienpakete](/de/policies/packs) darüber, wie du nur einen Teil davon übernimmst. + + Bis dieser Schritt ausgeführt wird, ist das einzige aktive Element `block-failproofai-commands` – der immer aktive Schutz, der verhindert, dass ein Agent Failproof AI deaktiviert. `failproofai policies` listet auf, was aktiv ist. - Folge [Ersten Fehlercheck ausführen](/de/start/first-audit). Verwende ein konkretes Ziel, z. B. „Sitzungen finden, in denen der Agent ein fehlschlagendes Tool ohne Änderung des Ansatzes erneut versucht hat." + Folge [Erste Fehlerprüfung ausführen](/de/start/first-audit). Verwende ein konkretes Ziel, zum Beispiel: „Sitzungen finden, in denen der Agent ein fehlgeschlagenes Tool ohne Änderung seines Ansatzes erneut versucht hat." - Folge [Ersten Fehler mit einer Richtlinie verhindern](/de/start/first-policy). Beginne im Beobachtungsmodus, prüfe Treffer und erzwinge dann die überprüfte Version. + Folge [Ersten Fehler mit einer Richtlinie verhindern](/de/start/first-policy). Beginne im Beobachtungsmodus, überprüfe Treffer und setze dann die geprüfte Version durch. - Führe `failproofai config --status` aus. Eine funktionierende Einrichtung meldet die Cloud-Verbindung, den Daemon-Status und ob die Durchsetzung pausiert ist. + Führe `failproofai config --status` aus. Ein fehlerfreies Setup meldet die Cloud-Verbindung, den Daemon-Zustand und ob die Durchsetzung pausiert ist. \ No newline at end of file diff --git a/docs/de/start/setup.mdx b/docs/de/start/setup.mdx index 22c63789..6e4d29fb 100644 --- a/docs/de/start/setup.mdx +++ b/docs/de/start/setup.mdx @@ -6,63 +6,84 @@ icon: "waypoints" - Installieren Sie Hooks und Richtlinien auf einem Rechner. Verwenden Sie diese Option, wenn Sie sofortige Sicherheitsmechanismen benötigen, ohne Sitzungsdaten in die Cloud zu senden. + Richten Sie eine Maschine ohne Cloud-Key ein und verwenden Sie ein Policy-Pack. Nutzen Sie diese Option, wenn Sie sofortige Sicherheitsmechanismen benötigen, ohne Sitzungsdaten an die Cloud zu senden. - Fügen Sie zentrale Sitzungen, Audits, Online-Auswertungen, Dashboards, Warnmeldungen und Fleet-Richtlinienverteilung hinzu. + Fügen Sie zentralisierte Sitzungen, Audits, Online-Auswertungen, Dashboards, Benachrichtigungen und Fleet-Policy-Deployment hinzu. - Nutzen Sie Organisationskontrollen, bereichsbezogene Schlüssel, private Infrastruktur und deploymentspezifische Sicherheitsanforderungen. + Nutzen Sie Organisationssteuerung, bereichsbezogene Keys, private Infrastruktur und deployment-spezifische Sicherheitsanforderungen. +## Lokal durchsetzen + +Führen Sie `failproofai config` ohne Key aus und installieren Sie anschließend ein Pack mit `failproofai policies add FailproofAI/policies`. Wählen Sie im Terminal **Not now — stay local**, wenn der Setup-Assistent fragt, ob eine Verbindung zur Cloud hergestellt werden soll. Ohne Terminal und ohne `FAILPROOFAI_CLOUD_TOKEN` bleibt die Konfiguration automatisch lokal. Der Daemon und die Hooks greifen auf der Maschine, und es werden keine Sitzungsdaten an die Cloud gesendet. Um die Verbindung später herzustellen, folgen Sie den nachstehenden Schritten. + ## Empfohlener Produktionspfad -1. Verbinden Sie einen Nicht-Produktionsrechner mit aktivierter Transkripterfassung. +1. Verbinden Sie eine Nicht-Produktionsmaschine mit aktivierter Transkripterfassung. 2. Überprüfen Sie Sitzungen und Auswertungen in der Cloud. 3. Erstellen Sie ein Audit für einen bekannten Fehlerfall. -4. Stellen Sie die erste Richtlinie im Beobachtungsmodus bereit. -5. Weiten Sie die Nutzung auf die Produktion aus, nachdem Sie Treffer und falsch positive Ergebnisse geprüft haben. +4. Deployen Sie die erste Policy im Beobachtungsmodus. +5. Weiten Sie das Deployment auf die Produktion aus, nachdem Sie Treffer und False Positives geprüft haben. -## Rechner mit der Cloud verbinden +## Eine Maschine mit der Cloud verbinden - 1. Gehen Sie zu **Administration → Schlüssel** und erstellen Sie einen Schlüssel mit `events:add` und `policies:pull`. - 2. Kopieren Sie das einmalig verwendbare Secret auf den Zielrechner. - 3. Führen Sie den CLI-Verbindungsbefehl aus, wechseln Sie dann zu **Admin → Durchsetzung** und bestätigen Sie, dass der Rechner dort erscheint. - 4. Gehen Sie zu **Beobachten → Ereignisse** und bestätigen Sie, dass das erste Ereignis des Rechners ankommt. + 1. Gehen Sie zu **Administration → Keys** und erstellen Sie einen Key mit den Berechtigungen `events:add` und `policies:pull`. + 2. Kopieren Sie das Einmal-Secret auf die Zielmaschine. + 3. Führen Sie den CLI-Verbindungsbefehl aus, gehen Sie dann zu **Admin → Enforcement** und bestätigen Sie, dass die Maschine angezeigt wird. + 4. Gehen Sie zu **Observe → Events** und bestätigen Sie, dass das erste Event ankommt. - Die Schlüsselansicht zeigt die zwei Berechtigungen, die ein verbundener Rechner benötigt: Ereignisaufnahme und Richtlinienbereitstellung. + Die Key-Schublade zeigt die zwei Berechtigungen, die eine verbundene Maschine benötigt: Event-Ingestion und Policy-Auslieferung. - ![Die neue API-Schlüssel-Ansicht zum Erteilen von Ereignisaufnahme- und Richtlinienbereitstellungsberechtigungen.](/images/dashboard/key-create.png) + ![Die neue API-Key-Schublade zum Vergeben von Berechtigungen für Event-Ingestion und Policy-Auslieferung.](/images/dashboard/key-create.png) - Nach der Verbindung sollte der Rechner in der Durchsetzungsübersicht mit seinem gewünschten und gemeldeten Richtlinienstatus erscheinen. + Nach der Verbindung sollte die Maschine im Enforcement-Bereich mit ihrem gewünschten und gemeldeten Policy-Status erscheinen. - ![Die Enforcement-Fleet mit einem eingetragenen Rechner, der seinen gewünschten Richtlinienstatus und Bereitstellungsstatus anzeigt.](/images/dashboard/enforcement-fleet.png) + ![Die Enforcement-Fleet mit einer eingetragenen Maschine, die ihren gewünschten Policy-Status und Deployment-Status anzeigt.](/images/dashboard/enforcement-fleet.png) - Das erste eingehende Ereignis bestätigt, dass der Daemon Daten unabhängig von der Richtlinienbereitstellung an die Cloud übermitteln kann. + Das erste eintreffende Event bestätigt, dass der Daemon Daten an die Cloud liefern kann – unabhängig vom Policy-Deployment. - ![Der Live-Ereignisstrom mit aktuellen Agent-, Modell- und Tool-Ereignissen.](/images/dashboard/events-stream-current.png) + ![Der Live-Eventstream mit aktuellen Agent-, Modell- und Tool-Events.](/images/dashboard/events-stream-current.png) - Fahren Sie erst fort, wenn sowohl der Rechner als auch sein erstes Ereignis sichtbar sind. + Fahren Sie erst fort, wenn sowohl die Maschine als auch ihr erstes Event sichtbar sind. + Lesen Sie das Einmal-Secret in die Shell ein. `read -s` nimmt es über eine Eingabeaufforderung ohne Echo entgegen, sodass es weder in einem Befehl noch im Shell-Verlauf erscheint: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Richten Sie die Maschine anschließend ein, wählen Sie ihre Policies und vergeben Sie einen Namen: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` + `failproofai config` übernimmt die gesamte Einrichtung – Daemon, Hooks für alle gefundenen Agent-CLIs und die Cloud-Verbindung – und wählt dabei keine Policies aus; dafür ist der zweite Befehl zuständig. + + Das Label wird **nach** der Verbindung gesetzt, nicht davor: `failproofai config --machine-label ` benennt eine bereits verbundene Maschine um; bei einer noch nicht verbundenen Maschine tut der Befehl nichts außer darauf hinzuweisen. + Fügen Sie `--no-transcripts` hinzu, wenn Transkriptinhalte lokal verbleiben müssen. + + Setzen Sie in CI-Umgebungen `FAILPROOFAI_CLOUD_TOKEN` aus dem Secret-Store anstelle von `read -s` und deaktivieren Sie Shell-Tracing (`set -x`), da andernfalls der Key im Trace ausgegeben wird. + + + Auf einer Maschine, die **bereits** eingerichtet ist, registriert `failproofai config --connect ` diese ausschließlich in der Cloud und tut nichts weiter. Verwenden Sie diese Form nicht für eine Erstinstallation: Der Befehl kehrt zurück, bevor Daemon oder Hooks eingerichtet sind, und hinterlässt eine Maschine, die in der Cloud erscheint, aber weder Daten erfasst noch Policies durchsetzt. + -Die Verbindung mit der Cloud überprüft Ereignisaufnahme und Richtlinienbereitstellung unabhängig voneinander. Ein Schlüssel kann daher gültig sein, aber eine erforderliche Berechtigung fehlen. Verwenden Sie `failproofai config --status`, um zu sehen, welche Funktion konfiguriert ist. +Die Verbindung zur Cloud prüft Event-Ingestion und Policy-Auslieferung unabhängig voneinander. Ein Key kann daher gültig sein, aber eine erforderliche Berechtigung fehlen. Verwenden Sie `failproofai config --status`, um zu sehen, welche Funktion konfiguriert ist. - Das Cloud-Setup schreibt lokale Anmeldedaten nur dann, wenn die jeweilige Funktion erfolgreich verifiziert wurde. Eine fehlgeschlagene Verifizierung lässt einen Rechner nicht fälschlicherweise als verbunden erscheinen. + Das Cloud-Setup schreibt lokale Anmeldedaten erst dann, wenn die jeweilige Funktion erfolgreich verifiziert wurde. Eine fehlgeschlagene Verifizierung hinterlässt keine Maschine, die als verbunden erscheint, obwohl sie es nicht ist. \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index 2c90430a..9812fb6d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -316,6 +316,10 @@ { "group": "Evaluate agents", "pages": [ + "zh/evaluations/overview", + "zh/evaluations/write", + "zh/evaluations/test", + "zh/evaluations/deploy", "zh/sessions/evaluations" ] }, @@ -355,6 +359,7 @@ { "group": "Ship a policy", "pages": [ + "zh/policies/test", "zh/policies/deploy", "zh/policies/rollback", "zh/policies/publish-a-pack", @@ -484,6 +489,10 @@ { "group": "Evaluate agents", "pages": [ + "ja/evaluations/overview", + "ja/evaluations/write", + "ja/evaluations/test", + "ja/evaluations/deploy", "ja/sessions/evaluations" ] }, @@ -523,6 +532,7 @@ { "group": "Ship a policy", "pages": [ + "ja/policies/test", "ja/policies/deploy", "ja/policies/rollback", "ja/policies/publish-a-pack", @@ -652,6 +662,10 @@ { "group": "Evaluate agents", "pages": [ + "ko/evaluations/overview", + "ko/evaluations/write", + "ko/evaluations/test", + "ko/evaluations/deploy", "ko/sessions/evaluations" ] }, @@ -691,6 +705,7 @@ { "group": "Ship a policy", "pages": [ + "ko/policies/test", "ko/policies/deploy", "ko/policies/rollback", "ko/policies/publish-a-pack", @@ -820,6 +835,10 @@ { "group": "Evaluate agents", "pages": [ + "es/evaluations/overview", + "es/evaluations/write", + "es/evaluations/test", + "es/evaluations/deploy", "es/sessions/evaluations" ] }, @@ -859,6 +878,7 @@ { "group": "Ship a policy", "pages": [ + "es/policies/test", "es/policies/deploy", "es/policies/rollback", "es/policies/publish-a-pack", @@ -988,6 +1008,10 @@ { "group": "Evaluate agents", "pages": [ + "pt-br/evaluations/overview", + "pt-br/evaluations/write", + "pt-br/evaluations/test", + "pt-br/evaluations/deploy", "pt-br/sessions/evaluations" ] }, @@ -1027,6 +1051,7 @@ { "group": "Ship a policy", "pages": [ + "pt-br/policies/test", "pt-br/policies/deploy", "pt-br/policies/rollback", "pt-br/policies/publish-a-pack", @@ -1156,6 +1181,10 @@ { "group": "Evaluate agents", "pages": [ + "de/evaluations/overview", + "de/evaluations/write", + "de/evaluations/test", + "de/evaluations/deploy", "de/sessions/evaluations" ] }, @@ -1195,6 +1224,7 @@ { "group": "Ship a policy", "pages": [ + "de/policies/test", "de/policies/deploy", "de/policies/rollback", "de/policies/publish-a-pack", @@ -1324,6 +1354,10 @@ { "group": "Evaluate agents", "pages": [ + "fr/evaluations/overview", + "fr/evaluations/write", + "fr/evaluations/test", + "fr/evaluations/deploy", "fr/sessions/evaluations" ] }, @@ -1363,6 +1397,7 @@ { "group": "Ship a policy", "pages": [ + "fr/policies/test", "fr/policies/deploy", "fr/policies/rollback", "fr/policies/publish-a-pack", @@ -1492,6 +1527,10 @@ { "group": "Evaluate agents", "pages": [ + "ru/evaluations/overview", + "ru/evaluations/write", + "ru/evaluations/test", + "ru/evaluations/deploy", "ru/sessions/evaluations" ] }, @@ -1531,6 +1570,7 @@ { "group": "Ship a policy", "pages": [ + "ru/policies/test", "ru/policies/deploy", "ru/policies/rollback", "ru/policies/publish-a-pack", @@ -1660,6 +1700,10 @@ { "group": "Evaluate agents", "pages": [ + "hi/evaluations/overview", + "hi/evaluations/write", + "hi/evaluations/test", + "hi/evaluations/deploy", "hi/sessions/evaluations" ] }, @@ -1699,6 +1743,7 @@ { "group": "Ship a policy", "pages": [ + "hi/policies/test", "hi/policies/deploy", "hi/policies/rollback", "hi/policies/publish-a-pack", @@ -1828,6 +1873,10 @@ { "group": "Evaluate agents", "pages": [ + "tr/evaluations/overview", + "tr/evaluations/write", + "tr/evaluations/test", + "tr/evaluations/deploy", "tr/sessions/evaluations" ] }, @@ -1867,6 +1916,7 @@ { "group": "Ship a policy", "pages": [ + "tr/policies/test", "tr/policies/deploy", "tr/policies/rollback", "tr/policies/publish-a-pack", @@ -1996,6 +2046,10 @@ { "group": "Evaluate agents", "pages": [ + "vi/evaluations/overview", + "vi/evaluations/write", + "vi/evaluations/test", + "vi/evaluations/deploy", "vi/sessions/evaluations" ] }, @@ -2035,6 +2089,7 @@ { "group": "Ship a policy", "pages": [ + "vi/policies/test", "vi/policies/deploy", "vi/policies/rollback", "vi/policies/publish-a-pack", @@ -2164,6 +2219,10 @@ { "group": "Evaluate agents", "pages": [ + "it/evaluations/overview", + "it/evaluations/write", + "it/evaluations/test", + "it/evaluations/deploy", "it/sessions/evaluations" ] }, @@ -2203,6 +2262,7 @@ { "group": "Ship a policy", "pages": [ + "it/policies/test", "it/policies/deploy", "it/policies/rollback", "it/policies/publish-a-pack", @@ -2332,6 +2392,10 @@ { "group": "Evaluate agents", "pages": [ + "ar/evaluations/overview", + "ar/evaluations/write", + "ar/evaluations/test", + "ar/evaluations/deploy", "ar/sessions/evaluations" ] }, @@ -2371,6 +2435,7 @@ { "group": "Ship a policy", "pages": [ + "ar/policies/test", "ar/policies/deploy", "ar/policies/rollback", "ar/policies/publish-a-pack", @@ -2500,6 +2565,10 @@ { "group": "Evaluate agents", "pages": [ + "he/evaluations/overview", + "he/evaluations/write", + "he/evaluations/test", + "he/evaluations/deploy", "he/sessions/evaluations" ] }, @@ -2539,6 +2608,7 @@ { "group": "Ship a policy", "pages": [ + "he/policies/test", "he/policies/deploy", "he/policies/rollback", "he/policies/publish-a-pack", diff --git a/docs/es/admin/keys-and-permissions.mdx b/docs/es/admin/keys-and-permissions.mdx index 4ffbd986..c49df193 100644 --- a/docs/es/admin/keys-and-permissions.mdx +++ b/docs/es/admin/keys-and-permissions.mdx @@ -1,29 +1,29 @@ --- title: "Claves y permisos" -description: "Crea claves de API con alcance definido para máquinas, automatización y operadores." +description: "Crea claves API con alcance definido para máquinas, automatización y operadores." icon: "key-round" --- -Las claves de API pertenecen a una organización y llevan permisos explícitos. Usa claves separadas para la ingesta de agentes, entrega de políticas, evaluadores, automatización de CI y scripts administrativos. +Las claves API pertenecen a una organización y llevan permisos explícitos. Usa claves separadas para la ingesta de agentes, la entrega de políticas, los evaluadores, la automatización de CI y los scripts administrativos. ## Crear y rotar una clave - 1. Ve a **Administración → Claves**, selecciona **nueva clave** e introduce un nombre de carga de trabajo. - 2. Elige un conjunto de permisos y ajusta los permisos individuales solo cuando el preset no sea suficiente. + 1. Ve a **Administración → Claves**, selecciona **nueva clave** e introduce un nombre para la carga de trabajo. + 2. Elige un conjunto de permisos y ajusta los permisos individuales solo cuando el conjunto predefinido sea insuficiente. 3. Crea la clave y copia su secreto de un solo uso de inmediato. - 4. Abre la clave más adelante para actualizar permisos, deshabilitarla o regenerar el secreto. + 4. Abre la clave más tarde para actualizar los permisos, desactivarla o regenerar el secreto. - El panel de creación es donde eliges los permisos mínimos necesarios para la carga de trabajo. + El panel de creación es donde eliges los permisos mínimos que requiere la carga de trabajo. - ![El panel de nueva clave de API con presets de permisos y permisos individuales.](/images/dashboard/key-create.png) + ![El panel de nueva clave API con presets de permisos y permisos individuales.](/images/dashboard/key-create.png) - Después de la creación, la página de Claves muestra los metadatos persistentes y las acciones de gestión. El secreto de un solo uso no se vuelve a mostrar. + Tras la creación, la página de Claves muestra los metadatos persistentes y las acciones de gestión. El secreto de un solo uso no vuelve a mostrarse. - ![La página de claves de API que muestra los permisos de la clave, la fecha de creación y las acciones de regenerar y deshabilitar.](/images/dashboard/api-keys.png) + ![La página de claves API con los permisos, la fecha de creación y las acciones de regenerar y desactivar.](/images/dashboard/api-keys.png) - Usa esta lista para revisar los permisos regularmente y deshabilitar las claves que ya no correspondan a una carga de trabajo activa. + Usa esta lista para revisar los permisos regularmente y desactivar las claves que ya no correspondan a una carga de trabajo activa. ```bash @@ -40,7 +40,7 @@ Las claves de API pertenecen a una organización y llevan permisos explícitos. -Los dos permisos necesarios para una máquina Failproof AI conectada son independientes: +Los dos permisos que requiere una máquina Failproof AI conectada son independientes: - `events:add` envía eventos y datos de sesión. - `policies:pull` recupera los despliegues de políticas asignados. @@ -54,7 +54,7 @@ Los secretos de las claves se muestran al crearlas o regenerarlas. Guárdalos en | Eventos | `events:add`, `events:read` | | Claves | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` es exclusivo de sesión humana | | Usuarios | `users:create`, `users:read`, `users:update`, `users:delete` | -| Evaluaciones | `evaluations:read`, `evaluations:trigger` | +| Evaluaciones | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | | Paneles | `dashboards:read`, `dashboards:write`, `dashboards:delete` | | Consultas | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | | Asistente | `agent:use` | @@ -65,10 +65,10 @@ Los secretos de las claves se muestran al crearlas o regenerarlas. Guárdalos en | Políticas | `policies:read`, `policies:write`, `policies:pull` | | Uso | `usage:read` | -`orgs:admin` está reservado para el operador de la instancia y no puede otorgarse a una clave de organización ni a un miembro ordinario. Los tokens obsoletos `incidents:*` y `alerts:ack` se aceptan por compatibilidad y se normalizan a los permisos actuales de `issues:*`. +`orgs:admin` está reservado para el operador de la instancia y no puede concederse a una clave de organización ni a un miembro ordinario. Los tokens retirados `incidents:*` y `alerts:ack` se aceptan por compatibilidad y se normalizan a los permisos actuales `issues:*`. -Los conjuntos de permisos integrados son `read-only`, `standard` y `admin`. `standard` añade a los permisos de lectura la capacidad de activar evaluaciones, ejecutar consultas, gestionar incidencias y usar el asistente. La creación de claves elimina los permisos exclusivos de sesión humana aunque el conjunto de permisos los incluya. +Los conjuntos de permisos integrados son `read-only`, `standard` y `admin`. `standard` añade la activación de evaluaciones, la ejecución de consultas, la gestión de incidencias y el uso del asistente a los permisos de lectura. La creación de claves elimina los permisos exclusivos de sesión humana aunque el conjunto de permisos los contenga. - Las claves con alcance de instancia pueden seleccionar una organización mediante el encabezado `X-AgentEye-Org`. Establécelo explícitamente en despliegues con múltiples organizaciones; si se omite, puede seleccionarse la organización predeterminada. + Las claves con alcance de instancia pueden seleccionar una organización mediante la cabecera `X-AgentEye-Org`. Establécela explícitamente en despliegues con múltiples organizaciones; omitirla puede seleccionar la organización predeterminada. \ No newline at end of file diff --git a/docs/es/evaluations/deploy.mdx b/docs/es/evaluations/deploy.mdx new file mode 100644 index 00000000..f4b4e87c --- /dev/null +++ b/docs/es/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "Desplegar y versionar una evaluación" +description: "Despliega una versión inmutable, consulta lo que está activo, publica nuevas versiones, revierte cambios y puntúa sesiones que ya tienes." +icon: "cloud-upload" +--- + +## Desplegarlo + +Selecciona **deploy `@`** en la parte inferior de la página de creación. La versión es inmutable una vez publicada: a partir de ese momento, cada sesión que finalice y a la que aplique su condición será puntuada por ella. + +## Ver qué está activo + +**Analyze → eval authoring** lista las definiciones alojadas de tu organización: las evaluaciones que el evaluador gestionado ejecuta para ella. Cada fila muestra: + +- su nombre, clave, versión y tipo de resultado +- su checksum de fuente, que distingue las revisiones desplegadas sin necesidad de abrir el código +- si es **condicional** o se ejecuta en **todas las sesiones completadas** — la condición es lo que delimita una evaluación a agentes o entornos concretos +- su tiempo de espera máximo, sus etiquetas y cuándo se modificó por última vez + +![La lista de definiciones alojadas: nombre, clave, versión, tipo de resultado, checksum, tiempo de espera y alcance de cada evaluación, con opciones para nueva versión y habilitar o deshabilitar.](/images/dashboard/eval-definitions.png) + +Busca en la lista o filtrala por estado. Las evaluaciones que registra tu propio worker no aparecen aquí; sus resultados llevan la etiqueta **customer** en la [página de evaluaciones](/es/sessions/evaluations), mientras que las alojadas llevan **managed**. + +Una organización puede tener hasta 100 evaluaciones alojadas distintas habilitadas al mismo tiempo. + +## Publicar una nueva versión + +Selecciona **new version** en una fila. La página de creación se abre con el código de esa versión; modifícalo, pruébalo y despliégalo. Su clave y tipo de resultado se mantienen y no pueden cambiarse. + +Publicar una versión sucesora deshabilita la anterior y la conserva en la lista. Los resultados mantienen la versión que los produjo, por lo que un gráfico muestra exactamente cuándo entró en vigor la nueva lógica. + +## Revertir cambios + +Selecciona **disable** en la versión actual y **enable** en la que quieras restaurar. Nada se elimina y todos los resultados permanecen tal como estaban. + +## Detener una evaluación + +Selecciona **disable**. Sin ninguna versión habilitada, dejará de ejecutarse en nuevas sesiones. Para detener una evaluación que ejecuta tu propio worker, deja de registrarla: elimínala del worker o detén el worker. + +## Puntuar sesiones que ya tienes + +La ejecución de evaluaciones avanza hacia adelante: una versión desplegada ahora nunca puntúa una sesión que terminó antes de su despliegue. Para puntuar el historial, abre **score sessions you already have** en la página de creación de evaluaciones, elige una ventana de hasta 90 días y, opcionalmente, una evaluación concreta, y cuenta antes de ejecutar. El recuento es exactamente lo que se ejecutará, y cada par sesión-evaluación que contenga es una evaluación facturable. + +Solo rellena huecos. Una sesión que ya tiene un resultado para esa evaluación lo conserva, y ejecutar la misma ventana dos veces no puntúa nada nuevo. + +Para puntuar una sesión de nuevo — tras una corrección, o para una sesión que nunca terminó correctamente — selecciona **re-evaluate** en su página. El nuevo resultado se añade al historial de la sesión; los anteriores se conservan. + +## Permisos + +| Permiso | Te permite | +| --- | --- | +| `evaluations:read` | Ver resultados y abrir la página de creación de evaluaciones | +| `evaluations:trigger` | Ver, desplegar, versionar, habilitar y deshabilitar definiciones alojadas; probarlas; puntuar el historial; re-evaluar una sesión | +| `events:read` | Probar con sesiones reales y basar los borradores en tus claves de payload, además de `evaluations:trigger` | +| `evaluations:run` | Ejecutar tu propio worker evaluador | \ No newline at end of file diff --git a/docs/es/evaluations/overview.mdx b/docs/es/evaluations/overview.mdx new file mode 100644 index 00000000..a23aec25 --- /dev/null +++ b/docs/es/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "Evaluar agentes" +description: "Puntúa cada sesión finalizada con evaluaciones que tú defines: checks Python alojados o jueces LLM en tu propio worker." +icon: "gauge" +--- + +Una evaluación puntúa una sesión de agente finalizada. Cuando una sesión termina, todas las evaluaciones habilitadas que le aplican se ejecutan y registran lo que encontraron, con un razonamiento que puedes leer junto a la traza: + +- una **puntuación** de 0 a 1, opcionalmente marcada como aprobada o fallida +- una **métrica**, como un conteo, una duración o un costo, con su unidad +- una **aserción**, que aprobó o no + +## Dos tipos de evaluador + +| | Python alojado | Tu propio worker | +| --- | --- | --- | +| Se escribe | En el dashboard, bajo **Analyze → eval authoring** | En Python, con el [SDK de evaluadores](/es/reference/evaluator-sdk) | +| Se ejecuta | En el evaluador gestionado de Failproof AI, en un sandbox | En tu infraestructura | +| Ideal para | Checks deterministas basados en código | Jueces LLM, llamadas a modelos, paquetes, secretos, acceso a red, procesamiento pesado | + +El Python alojado es deliberadamente simple: una expresión, sin imports, sin red. Todo lo que necesite un modelo —un juez LLM que evalúe si una respuesta fue relevante, por ejemplo— se ejecuta en tu propio worker. Ninguno de los dos tipos necesita una conexión entrante: los workers toman las sesiones finalizadas y envían los resultados mediante HTTPS saliente. + +## Cada organización evalúa sus propios agentes + +Las evaluaciones pertenecen a la organización que las define. Cada organización en una instancia escribe las suyas propias —sus propios checks, condiciones, umbrales y etiquetas—, las versiona y despliega sin afectar a ninguna otra, y solo ve sus propios resultados. Filtra esos resultados por agente, entorno, evaluación y tiempo, o consúltale al asistente sobre ellos. + +## Del primer borrador a puntuaciones en producción + + + + Describe qué medir y deja que el asistente haga el borrador, o escríbela tú mismo. Ver [Escribir una evaluación](/es/evaluations/write). + + + Ejecútala contra sesiones reales antes de publicarla; nada se almacena. Ver [Probar una evaluación](/es/evaluations/test). + + + Despliega una versión inmutable, publica nuevas versiones a medida que evoluciona, y vuelve a una versión anterior si es necesario. Ver [Desplegar y versionar](/es/evaluations/deploy). + + + Visualiza las puntuaciones a lo largo del tiempo, compara agentes y entornos, y consulta al asistente. Ver [Leer resultados de evaluaciones](/es/sessions/evaluations). + + + +Las evaluaciones avanzan hacia adelante: una versión desplegada ahora puntúa las sesiones que finalicen a partir de ese momento. Para puntuar sesiones que ya tienes, [rellena los datos anteriores](/es/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file diff --git a/docs/es/evaluations/test.mdx b/docs/es/evaluations/test.mdx new file mode 100644 index 00000000..1de62ea1 --- /dev/null +++ b/docs/es/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "Probar una evaluación" +description: "Ejecuta una evaluación contra tus sesiones reales antes de desplegarla. Nada se almacena." +icon: "flask-conical" +--- + +**Probar esta evaluación**, en la página de creación, ejecuta el código contra tus sesiones reales en la flota de evaluadores sin desplegarla. Nada se almacena: un fallo aquí es solo una vista previa, y desplegar siempre está permitido. + + + + Selecciona **verificar** para compilar el código y la condición contra las reglas del sandbox sin ejecutarlos en ninguna sesión. + + + Filtra las sesiones coincidentes por agente, entorno, tiempo o ID de sesión, y marca hasta 10. Incluye tanto sesiones en las que la evaluación debería fallar como otras en las que debería pasar. + + + Selecciona **ejecutar contra N sesiones** y lee cada fila. + + + +| Fila | Qué significa | +| --- | --- | +| **ok** | Se ejecutó. La fila muestra cada puntuación, métrica y aserción que devolvió, y cuánto tardó. | +| **omitida** | La condición devolvió `False`, por lo que la evaluación no se ejecutó. Eso es una omisión, no un fallo. | +| Fallida | Se produjo una excepción, se agotó el tiempo de espera o se usó algo que el sandbox rechaza. La fila indica cuál fue el problema, y **Corregir** entrega el error al asistente cuando puede ayudar. | + +![El panel de prueba de evaluación: tres sesiones seleccionadas por agente, dos ok y una omitida porque su condición devolvió False.](/images/dashboard/eval-test.png) + +Un resultado deja de estar vigente en el momento en que editas el código; se atenúa en lugar de reutilizarse. \ No newline at end of file diff --git a/docs/es/evaluations/write.mdx b/docs/es/evaluations/write.mdx new file mode 100644 index 00000000..8cf2cedc --- /dev/null +++ b/docs/es/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "Escribir una evaluación" +description: "Describe qué medir y deja que el asistente genere una evaluación Python alojada, o escribe el código tú mismo. Los jueces LLM se ejecutan en tu propio worker." +icon: "file-pen-line" +--- + +Las evaluaciones alojadas son pequeñas piezas de Python deterministas, escritas en el dashboard y ejecutadas en la flota de evaluadores de Failproof AI. La lógica más pesada — un juez LLM, un paquete, un secreto, una llamada de red — se ejecuta en [tu propio worker](#write-it-in-your-own-worker). + +## Generar a partir de una descripción + +1. Ve a **Analyze → eval authoring** y selecciona **new eval**. +2. Describe qué medir en lenguaje natural, o elige entre **start from an example…**, y selecciona **draft**. +3. Revisa los campos y el código que se rellena automáticamente, luego [pruébalo](/es/evaluations/test) y [despliégalo](/es/evaluations/deploy). + +![La página de creación de evaluaciones con una evaluación generada: la descripción, las notas del asistente sobre el borrador y los campos de nombre, clave, versión, resultado, timeout, etiquetas y condición.](/images/dashboard/eval-authoring-draft.png) + +El borrador se basa en los eventos propios de tu organización: la página lee qué claves de payload llevaban tus sesiones durante los últimos siete días, de modo que el código usa claves que existen en lugar de suposiciones. Antes de entregar el borrador, el asistente lo prueba contra hasta cinco de tus sesiones recientes, corrige todo lo que pueda demostrar que está roto — hasta tres rondas — y verifica una vez que el código mide lo que pediste. Mantén la descripción específica: los prompts amplios son más lentos y pueden agotar el tiempo de espera. Revisa el código de todas formas; el despliegue nunca está bloqueado. + +## Configurar los campos + +| Campo | Descripción | +| --- | --- | +| name | Lo que ven las personas. Editable más adelante | +| key | El identificador estable bajo el que se agrupan sus resultados, como `code_assistant_quality_gate` | +| version | Cualquier cadena de versión sin espacios, como `1.0.0` | +| result | **score** (de 0 a 1), **metric** (un número con unidad) o **assertion** (aprobado o no) | +| timeout seconds | Por defecto 30. El sandbox detiene cualquier ejecución individual a los 60 | +| labels | Hasta 20, separadas por comas. Editable más adelante | +| condition | Opcional. Una expresión Python; la evaluación solo se ejecuta en sesiones donde sea `True` | + +Usa la condición para limitar el alcance de una evaluación a los agentes y entornos para los que está pensada: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +La clave, la versión, el tipo de resultado, la condición y el código son inmutables una vez desplegados: para cambiar cualquiera de ellos, publica una nueva versión. El nombre, las etiquetas y si está habilitada siguen siendo editables. + +## Escribir el código tú mismo + +El **evaluator code** es una expresión Python que devuelve `EvalResult(...)`, con `session` en el ámbito. Esta expresión calcula la proporción de resultados de herramientas que volvieron correctamente: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +Un resultado encabeza con la propia clave de la evaluación, en su tipo declarado: `score=` para una evaluación de puntuación, o una entrada `metrics` o `assertions` con el nombre de la clave para una métrica o una aserción. Otras métricas y aserciones se incluyen junto a ella, con hasta 25 resultados por ejecución. + +| En el ámbito | Te proporciona | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count` y `events`, más `count(event_type)` y `events_of_type(event_type)` | +| Cada evento | `id`, `ts`, `event_type` y `payload` | +| Tipos de resultado | `EvalResult`, `Score`, `Metric`, `Assertion` y `ConditionResult` para una condición | +| Builtins | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +No hay nada más accesible: sin imports y sin atributos más allá de los datos de sesión y los métodos simples de cadenas y diccionarios como `get`, `lower` y `split`, que deben invocarse en lugar de referenciarse. Las claves de payload son las que envíen tus agentes — `status` más arriba es solo un ejemplo — así que léelas desde una sesión real. **format** ordena el código y **fix** le pide al asistente que lo repare. El código puede tener hasta 128 KiB, y la condición hasta 16 KiB. + +![El editor de código del evaluador, con format y fix, mostrando las aserciones de una evaluación generada.](/images/dashboard/eval-authoring-code.png) + +## Escribirlo en tu propio worker + +Cuando una evaluación necesita un modelo, un paquete, un secreto o la red, escríbela con el [Evaluator SDK](/es/reference/evaluator-sdk) y ejecútala en tu propia infraestructura. Usa los mismos tipos de resultado, y sus resultados aparecen junto a los alojados, etiquetados como **customer**: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/es/policies/deploy.mdx b/docs/es/policies/deploy.mdx index c399317d..61bdf7b6 100644 --- a/docs/es/policies/deploy.mdx +++ b/docs/es/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "Desplegar políticas" -description: "Distribuye una versión de política revisada a las máquinas de destino." +title: "Desplegar una política" +description: "Pon una versión de política probada en máquinas en modo observación, aplícala y confirma que todas las máquinas la han recibido." icon: "cloud-upload" --- -Un despliegue conecta una o más versiones de política con un conjunto de máquinas inscritas como objetivo. +Un despliegue coloca versiones de política publicadas en una máquina, cada una con uno de dos efectos: -## Aplicar un despliegue +- **Observar** registra lo que la política habría hecho, sin bloquear nada. +- **Aplicar** actúa sobre la decisión: un `deny` bloquea la llamada y un `instruct` orienta al agente. + +## Agregar una máquina + +Una máquina aparece en **Admin → enforcement** una vez que está conectada a Cloud. Si la que necesitas aún no aparece: - + + 1. Ve a **Administración → Claves** y crea una clave con `policies:pull`, para que la máquina pueda recibir despliegues, y `events:add`, para que sus decisiones lleguen a Cloud. + 2. Conecta la máquina con esa clave — [Conectar una máquina a Cloud](/es/start/setup#connect-a-machine-to-cloud) te guía paso a paso. + 3. Confirma que aparece en **Admin → enforcement**. + + + En la máquina: + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + En una terminal, `failproofai config` pregunta si conectarse a Cloud y solicita la clave mediante un prompt enmascarado. Luego confirma que la máquina está registrada, desde cualquier lugar, con `fp fleet list`. + + + +## Desplegar en modo observación + + + 1. Ve a **Admin → enforcement**, encuentra la máquina y expande su fila. - 2. Selecciona **edit**, añade la versión de política revisada y elige el efecto **observe** o su efecto de aplicación. - 3. Aplica el cambio, luego espera el próximo registro de la máquina y confirma el estado de despliegue y cobertura. - 4. Ve a **Observe → policy** para inspeccionar las decisiones en tiempo real. + 2. Selecciona **editar**, agrega la versión de política probada y elige **observar**. + 3. Aplica el cambio, espera al siguiente check-in de la máquina y confirma su estado de despliegue y cobertura. + 4. Ve a **Observar → política** para inspeccionar las decisiones en tiempo real. - ![El editor de despliegue de máquinas con versiones de política, efectos enforce y observe, y la acción de aplicar despliegue.](/images/dashboard/enforcement-editor.png) + ![El editor de despliegue de máquina con versiones de política, efectos de aplicar y observar, y la acción de aplicar despliegue.](/images/dashboard/enforcement-editor.png) - Despliega desde la CLI con `fp fleet`. Revisa el conjunto resultante antes de aplicarlo — `deploy` imprime el plan completo y pregunta **solo en una terminal interactiva sin `--json`**. Con `--json`, con `--yes`, o con stdin redirigido (un paso de CI, un script, un agente ejecutando comandos de shell) se aplica de inmediato sin plan ni confirmación — así que ejecuta `fp fleet show ` primero si deseas revisar: - ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` muestra la intención vs. la entrega (una máquina aparece como `behind` hasta su próximo sondeo), `fp fleet history ` lista las generaciones, y `fp fleet rollback ` restablece una — se rechaza si esa generación nombra una política que ha sido desactivada o eliminada. + El sufijo `:observe` es lo que activa el modo observación: usar `--add no-force-push` sin sufijo mantiene el efecto que la máquina ya tiene para esa política y, en caso contrario, aplica. Cámbialo a aplicar más tarde con `--add no-force-push:enforce`. - Verifica la máquina con `failproofai config --status`, y usa `fp sessions --env production --since 24h` y `fp events --event-type hook_completed` tras el despliegue para confirmar que la actividad llega a Cloud. + `deploy` **reemplaza todo el conjunto de políticas de la máquina** con el resultado. Muestra el plan y pide confirmación antes de aplicar — pero solo en una terminal interactiva. Con `--yes`, bajo `fp --json`, o con stdin redirigido (un paso de CI, un script, un agente ejecutando comandos shell) se aplica sin preguntar; el plan sigue mostrándose, o se devuelve como `plan` bajo `--json`. + + En la máquina, `failproofai policies` lista las políticas administradas por Cloud que está ejecutando y `failproofai config --status` muestra su conexión. Usa `fp sessions --env production --since 24h` y `fp events --event-type hook_completed` para confirmar que su actividad llega a Cloud. - - Despliega una versión revisada, no un borrador mutable, comenzando con una máquina fuera de producción o un grupo pequeño cuyas sesiones puedas inspeccionar. + + Selecciona la versión publicada y las máquinas en las que debe ejecutarse. - - Revisa coincidencias, razones, herramientas afectadas y falsos positivos sin bloquear el trabajo. + + Revisa las coincidencias, los motivos, las herramientas afectadas y los falsos positivos mientras no se bloquea nada. - - Promueve tras verificar que las coincidencias observadas separan las acciones no seguras de las válidas, luego confirma que cada máquina prevista ha obtenido el despliegue y está reportando decisiones. + + Cambia el efecto a aplicar una vez que las coincidencias observadas separen las acciones inseguras de las válidas, y confirma que todas las máquinas previstas recibieron el cambio y están reportando decisiones. -Las máquinas necesitan la capacidad `policies:pull`. El reporte de eventos está controlado de forma independiente por `events:add`; verifica ambos cuando esperes análisis y aplicación en Cloud. +## Verificar la cobertura + +La cobertura indica si una política está activa donde existe el riesgo. + +1. Ve a **Admin → enforcement** y revisa los totales de aplicación y observación. +2. Busca una máquina por ID o etiqueta, o filtra las máquinas que no tienen una política asignada. +3. Expande una fila para comparar las políticas asignadas, el despliegue reportado, el último check-in y el historial. +4. Actualiza después del intervalo de sondeo de la máquina cuando un despliegue aplicado aún esté pendiente. + +![La flota de Enforcement mostrando la cobertura de políticas, el estado de despliegue de la máquina y las asignaciones de observar y aplicar.](/images/dashboard/enforcement-fleet.png) + +Busca máquinas que nunca descargaron el último despliegue, máquinas registradas que dejaron de reportar, una política asignada al entorno incorrecto y desvíos de versión después de una actualización interrumpida. + +Etiqueta las máquinas por carga de trabajo y entorno — los nombres de host por sí solos raramente sobreviven al autoescalado o la sustitución: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - La gestión de aplicación es un flujo de trabajo administrativo de Cloud. No trates las rutas de aplicación exclusivas para root como endpoints ordinarios de la API `/v1` para clientes. + La gestión de aplicación es un flujo de trabajo administrativo de Cloud. No trates las rutas de aplicación exclusivas de root como endpoints ordinarios de la API `/v1` para clientes. \ No newline at end of file diff --git a/docs/es/policies/editor.mdx b/docs/es/policies/editor.mdx index 750c1653..07b02f37 100644 --- a/docs/es/policies/editor.mdx +++ b/docs/es/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "Editor de políticas" -description: "Crea y revisa políticas versionadas a partir de un modo de fallo confirmado." +title: "Escribir una política" +description: "Deja que Failproof AI redacte una política a partir de un hallazgo de auditoría, o escribe el código tú mismo; luego revísala, pruébala y publícala." icon: "file-pen-line" --- -Usa el editor de políticas para convertir un hallazgo o incidencia en una regla desplegable. Mantén la autoría separada del despliegue para que un borrador no pueda modificar silenciosamente el comportamiento en producción. +Hay dos formas de escribir una política: dejar que Failproof AI la redacte a partir de un hallazgo de auditoría, o escribir el código tú mismo. Nada se publica ni se despliega hasta que tú lo decidas. -Cuando una incidencia tiene un patrón de acción repetible, ábrela en **Analyze → issues** y selecciona **generate policy**. Failproof AI primero explica si una política puede expresar el problema y luego traslada la intención revisada y el contexto del hallazgo al editor. El código fuente generado permanece como borrador hasta que lo publiques. +## Escribir una política a partir de una auditoría -## Publicar una versión de política +Una auditoría detecta un fallo; una política evita que vuelva a ocurrir. Failproof AI redacta la política a partir de la evidencia del propio hallazgo. + +### 1. Ejecutar una auditoría + +[Ejecuta una auditoría](/es/audits/run) sobre las sesiones donde ocurre el fallo. Cada hallazgo contiene sus sesiones de evidencia, una causa raíz y una ruta de prevención sugerida. Trabaja a partir de un hallazgo con un **patrón de acción repetible** — una política solo puede detener aquello que puede reconocer en un evento de hook. + +### 2. Generar el borrador - 1. Ve a **Admin → policy editor** y, en **compose**, describe el modo de fallo o pega el código fuente de la política en JavaScript. - 2. Valida el código fuente y corrige cada error reportado. - 3. Introduce la identidad de la política y publícala; luego usa **library** para comparar o deshabilitar versiones. - 4. Selecciona **enforcement** cuando la versión esté lista para un despliegue en máquinas. + 1. Abre el issue del hallazgo en **Analyze → issues** y revisa las sesiones citadas, la causa raíz y la recomendación. + 2. Selecciona **generate policy**. Failproof AI primero indica si una política puede expresar el problema en absoluto. Un resultado **no policy** significa que la solución es una alerta, un cambio de flujo de trabajo o una persona — no una política. + 3. Selecciona **write this policy**. El título del issue, el hallazgo, la causa raíz, la recomendación y la intención de aplicación propuesta se convierten en un borrador en **Admin → policy editor**. Usa **open the editor anyway** cuando no estés de acuerdo con la verificación de candidatura. - ![Vista de composición del editor de políticas con identidad de política, redacción asistida por IA, validación del código fuente y controles de publicación.](/images/dashboard/policy-editor.png) + ![La vista de redacción del editor de políticas con identidad de política, redacción asistida por IA, validación de código fuente y controles de publicación.](/images/dashboard/policy-editor.png) - Publica desde la CLI con `fp policies publish`. Esto genera una **nueva versión** y nunca edita una existente en su lugar, además comprueba la sintaxis del código con node antes de enviarlo — los pasos posteriores no lo hacen, por lo que un error de sintaxis se manifestaría en la máquina en el momento de la aplicación: + Lee la evidencia y luego redacta con el asistente. `compose` imprime el código fuente para que lo revises y no publica nada: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - Publicar no despliega nada: una nueva versión queda sin usar hasta que `fp fleet deploy` la instala en una máquina. `fp policies compose ""` redacta el código con el asistente Cloud y lo imprime para revisión en lugar de publicarlo. - - Para instalar una política directamente en una CLI de agente local (no en Cloud), usa `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. + `compose` requiere una sesión con sesión iniciada (`fp login`) cuyo rol tenga `policies:write`; rechaza las claves de API. -## Lista de verificación para la autoría +### 3. Revisar el borrador + +Un borrador es un punto de partida, no un veredicto. Antes de publicar, verifica que: + +1. Nombra el modo de fallo en lenguaje operativo. +2. Coincide solo con los eventos de hook y las herramientas que contienen suficiente evidencia para decidir. +3. Usa la condición más restrictiva posible que detecte la acción no segura. +4. Devuelve un motivo que indique al agente qué hacer en su lugar. +5. Usa `instruct` cuando el agente pueda corregir el curso de forma segura, y `deny` solo cuando permitir la acción sea inaceptable o irreversible. + +Valida el código fuente en el editor y corrige cada error reportado. + +### 4. Probarlo y luego publicarlo + +Ejecuta **backtest** sobre el código fuente antes de publicar: repite el borrador contra las llamadas que tu flota ya realizó y cuenta las llamadas correctas que habría interrumpido. [Probar una política](/es/policies/test) cubre ese proceso y las demás comprobaciones. + +Cuando se comporte como se espera, introduce la identidad de la política y selecciona **publish version**. Publicar genera una versión inmutable y no despliega nada: permanece inactiva hasta que la [despliegues](/es/policies/deploy). Desde un terminal: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` verifica la sintaxis del código fuente antes de enviarlo, por lo que un error de sintaxis se detecta aquí en lugar de en una máquina durante la aplicación. + +## Escribirla tú mismo + +Una política es JavaScript o TypeScript sobre la API de `failproofai`: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +Esto coincide con `production/config.yml`, `/srv/production/config.yml`, `/srv/production` y `C:\\production\\config.yml` tanto para `Write` como para `Edit`, pero no con `production-backup`: `production` tiene que ser un segmento de ruta completo. El contexto también contiene el tipo de evento, el payload normalizado, los metadatos de sesión, los parámetros y la CLI de origen cuando están disponibles — consulta el [SDK de políticas](/es/reference/policy-sdk). + +Para publicarlo como una versión, pega el código fuente en **compose** en **Admin → policy editor** y sigue los pasos 3 y 4 anteriores, o publica el archivo desde un terminal con `fp policies publish`. -1. Nombra el modo de fallo en lenguaje operacional. -2. Selecciona los eventos de hook y las herramientas que contengan suficiente evidencia para decidir. -3. Escribe la condición más específica posible que identifique el comportamiento inseguro. -4. Devuelve un motivo que indique al agente u operador qué hacer a continuación. -5. Añade ejemplos que deben coincidir y ejemplos que deben seguir siendo permitidos. -6. Guarda una nueva versión y solicita revisión. +Para ejecutarlo en una máquina sin Cloud, guárdalo en `.failproofai/policies/` con un nombre que termine en `policies.js`, `policies.mjs` o `policies.ts` — estos se cargan automáticamente en el ámbito de proyecto y de usuario — o instálalo por ruta: -Usa `instruct` cuando el agente pueda corregir el rumbo de forma segura. Usa `deny` cuando permitir la acción suponga un riesgo inaceptable o irreversible. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - Las versiones de política son entradas de despliegue inmutables. Editar un borrador crea una nueva versión; no debe reescribir la versión ya asignada a las máquinas. - \ No newline at end of file +Dale a cada política un nombre único entre las políticas de convención, personalizadas, de paquete y gestionadas por Cloud. \ No newline at end of file diff --git a/docs/es/policies/failure-behavior.mdx b/docs/es/policies/failure-behavior.mdx index f0900379..12ab08aa 100644 --- a/docs/es/policies/failure-behavior.mdx +++ b/docs/es/policies/failure-behavior.mdx @@ -4,16 +4,16 @@ description: "Comprende qué ocurre cuando la evaluación de políticas o el dae icon: "shield-alert" --- -Failproof AI está diseñado para que un fallo de aplicación sea visible en lugar de permitir silenciosamente trabajo de riesgo. +Failproof AI está diseñado para que un fallo de aplicación sea visible en lugar de permitir silenciosamente trabajo arriesgado. ## Diagnosticar un bloqueo por fallo cerrado - + 1. Ve a **Admin → enforcement** y abre la máquina. - 2. Comprueba su último registro de actividad, el despliegue asignado y el despliegue reportado. + 2. Comprueba su último check-in, el despliegue asignado y el despliegue reportado. 3. Ve a **Observe → policy** y abre la sesión de la decisión denegada. - 4. Confirma si el motivo indica inaccesibilidad del daemon, diferencia de versión o la propia política. + 4. Confirma si la razón reporta inaccesibilidad del daemon, desfase de versión o la propia política. @@ -23,45 +23,47 @@ Failproof AI está diseñado para que un fallo de aplicación sea visible en lug failproofai config ``` - Volver a ejecutar `failproofai config` actualiza y reinicia el daemon tras actualizar el paquete. + Volver a ejecutar `failproofai config` actualiza y reinicia el daemon tras una actualización del paquete. -En una máquina configurada para usar `failproofaid`, el daemon es el único evaluador. Si no es accesible o su versión de protocolo no coincide con la del CLI, la evaluación del hook falla de forma cerrada. La acción se deniega con un motivo que indica al operador que revise o actualice el daemon. +En una máquina configurada para usar `failproofaid`, el daemon es el único evaluador. Si no es accesible o su versión de protocolo no coincide con la del CLI, la evaluación del hook falla de forma cerrada. La acción se deniega con un motivo que indica al operador que compruebe o actualice el daemon. -Antes de configurar el daemon, los hooks evalúan las políticas en proceso. Una vez que la configuración del daemon queda registrada, Failproof AI no vuelve silenciosamente a un segundo evaluador cuando el daemon falla. +Antes de la configuración del daemon, los hooks evalúan las políticas en proceso. Una vez que la configuración del daemon queda registrada, Failproof AI no recurre silenciosamente a un segundo evaluador cuando el daemon falla. -## Responder a una decisión de fallo cerrado +## Responder a una decisión por fallo cerrado 1. Ejecuta `failproofai config --status`. -2. Si las versiones difieren, vuelve a ejecutar `failproofai config` tras actualizar el paquete. -3. Si el daemon no es accesible, inspecciona el estado de su servicio y los registros locales. -4. Reanuda el trabajo del agente solo después de verificar que la ruta de evaluación de políticas conocida está en buen estado. +2. Si las versiones difieren, vuelve a ejecutar `failproofai config` después de actualizar el paquete. +3. Si el daemon no es accesible, inspecciona su estado de servicio y los registros locales. +4. Reanuda el trabajo del agente solo cuando se haya verificado que la ruta de evaluación de políticas está operativa. - No reintentar repetidamente la acción bloqueada. Una respuesta de fallo cerrado significa que el sistema no pudo determinar que la acción era segura. + No reintentes repetidamente la acción bloqueada. Una respuesta por fallo cerrado significa que el sistema no pudo determinar que la acción era segura. ## Un pack no carga -Una máquina que tenía instrucciones de aplicar un pack y no puede ejecutarlo, deniega en lugar de continuar silenciosamente. El desencadenante es una **expectativa registrada**, nunca una vacía: una máquina sin packs instalados permanece en silencio, mientras que un pack declarado que no puede resolverse — o que registra menos de lo que declara su manifiesto — deniega. +Una máquina a la que se le indicó que aplicara un pack y no puede ejecutarlo deniega la operación en lugar de continuar silenciosamente. El desencadenante es una **expectativa registrada**, nunca una vacía: una máquina sin packs instalados permanece silenciosa, mientras que un pack declarado que no puede resolverse —o que registra menos de lo que declara su manifiesto— deniega. -La denegación es **restringida**, a diferencia de un daemon inaccesible. Un daemon al que no se puede llegar significa que no se realizó ninguna evaluación, por lo que nada puede considerarse seguro. Un pack que no carga tiene un conjunto enumerable de guardas faltantes, ya que cada política declarada tiene su propio `match` — así que deniega únicamente los eventos y herramientas que esas políticas cubrían, y todo lo demás continúa. +La denegación es **acotada**, a diferencia de un daemon inaccesible. Un daemon que no puede alcanzarse significa que no se realizó ninguna evaluación, por lo que nada puede considerarse seguro. Un pack que no carga tiene un conjunto enumerable de guardas ausentes, porque cada política declarada lleva su propio `match`; por tanto, solo deniega los eventos y herramientas que esas políticas cubrían, y todo lo demás continúa. -No se activa para: +No se activa en los siguientes casos: -- un pack de `observe`, que evalúa y descarta por construcción -- políticas que nunca adoptaste, o que desactivaste explícitamente -- un pack que el cargador nunca recibió, donde no es posible distinguir "sin registros" de una omisión deliberada +- un pack `observe`, que evalúa y descarta por construcción +- políticas que nunca adoptaste o desactivaste explícitamente +- un pack que el cargador nunca recibió, donde no es posible distinguir entre «sin registros» y un salto deliberado - una pausa de sesión activa - un timeout de carga, que es transitorio — un momento de disco lento no debe denegar hasta que intervenga un humano -`UserPromptSubmit` **instruye** en lugar de denegar, independientemente de lo que declarara la política faltante. Una denegación general lo incluiría y te bloquearía el acceso al agente que podría solucionar el problema. +`UserPromptSubmit` **instruye** en lugar de denegar, independientemente de lo que declarara la política ausente. Una denegación general también lo afectaría y te bloquearía el acceso al agente que podría resolver el problema. ### Qué hacer ```bash -failproofai pack list +failproofai policies ``` -Muestra cualquier pack instalado que no cargue, indica el motivo y termina con código de error no cero. A continuación, reinstálalo (`failproofai pack add `) o elimínalo (`failproofai pack remove `) — eliminarlo retira la expectativa y con ello cesa la denegación. \ No newline at end of file +El listado marca un pack instalado cuyo registro de instalación o digest ya no es válido, e indica el motivo. No importa el pack, por lo que uno que falla solo al cargarse —registrando menos de lo que declara su manifiesto— aparece como normal; la denegación descrita a continuación es la que identifica ese caso. En cualquier caso, reinstálalo (`failproofai policies add `) o elimínalo (`failproofai policies remove `) — eliminarlo retira la expectativa y la denegación cesa con ello. + +La propia denegación se atribuye a `pack/failproofai-pack-unavailable`, que tiene prioridad sobre las políticas que sí cargaron, de modo que una llamada a herramienta bloqueada nombra el pack ausente en lugar de la guarda superviviente que haya disparado primero. \ No newline at end of file diff --git a/docs/es/policies/local-configuration.mdx b/docs/es/policies/local-configuration.mdx index 220123fb..d9029c28 100644 --- a/docs/es/policies/local-configuration.mdx +++ b/docs/es/policies/local-configuration.mdx @@ -1,55 +1,49 @@ --- title: "Configuración local" -description: "Controla el alcance de las políticas, los parámetros, los archivos personalizados y la configuración de Failproof AI a nivel de máquina." +description: "Controla el alcance de las políticas, los parámetros, los archivos personalizados y los ajustes de Failproof AI a nivel de máquina." icon: "file-cog" --- -Failproof AI separa la selección de políticas de la configuración de la máquina y del daemon. Esto permite que las políticas del repositorio sean auditables, mientras que las credenciales y el estado del daemon permanecen fuera del repositorio. +Failproof AI separa lo que un repositorio puede confirmar —el cableado de hooks, los parámetros de políticas y las políticas personalizadas— del estado de la máquina, como las credenciales, los paquetes instalados y el daemon. -## Elige un alcance de política +## Elige un alcance - - - Ejecuta `failproofai` sin argumentos para abrir el panel de políticas local. Elige el alcance de usuario, proyecto o local antes de activar una política, de modo que el cambio se escriba en el archivo de configuración correspondiente. +El alcance determina dónde se conectan los hooks y en qué archivo de configuración se escriben los parámetros y las rutas de políticas personalizadas: - - **Usuario** aplica en todos los proyectos de esta máquina. - - **Proyecto** pertenece al repositorio y puede confirmarse en el control de versiones. - - **Local** sobrescribe un proyecto para un usuario específico y debería mantenerse en gitignore. +- **User** se aplica a todos los proyectos de esta máquina. +- **Project** pertenece al repositorio y puede confirmarse. +- **Local** sobreescribe un proyecto para un usuario específico y debería mantenerse en el gitignore. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # wire hooks for this repository +failproofai policies --install --cli claude --scope user # or for every project on this machine +failproofai policies +``` - No todos los adaptadores admiten el alcance local. El CLI rechaza un alcance que el adaptador seleccionado no pueda representar. - - +No todos los arneses admiten el alcance local; el CLI rechaza un alcance que el arnés seleccionado no puede representar. + +El estado de activación de las políticas de un paquete **no** está limitado por el alcance. El cambio se registra junto con el paquete instalado, por lo que `failproofai policies add ` activa una política para toda la máquina, independientemente de lo que indique `--scope`. | Alcance | Archivo de configuración de políticas | | --- | --- | -| Proyecto | `/.failproofai/policies-config.json` | +| Project | `/.failproofai/policies-config.json` | | Local | `/.failproofai/policies-config.local.json` | -| Usuario | `~/.failproofai/policies-config.json` | +| User | `~/.failproofai/policies-config.json` | -Las políticas habilitadas se combinan como una unión. Los parámetros de política utilizan el primer alcance que define parámetros para esa política, en orden proyecto → local → usuario. Las rutas de políticas personalizadas explícitas utilizan el primer alcance que las defina. +Los parámetros de políticas utilizan el primer alcance que define parámetros para esa política, en el orden project → local → user. Las rutas de políticas personalizadas explícitas utilizan el primer alcance que las define. -## Configura los parámetros de política +## Configura los parámetros de políticas - Abre la política en el panel local, edita sus parámetros admitidos y guarda los cambios en el alcance seleccionado. Ejecuta una acción del agente que coincida y otra que no coincida, luego inspecciona la decisión en **Observar → política**. + Abre la política en el panel de control local, edita sus parámetros compatibles y guárdalos en el alcance seleccionado. Ejecuta una acción del agente que coincida y otra que no coincida, luego inspecciona la decisión en **Observe → policy**. - Edita el archivo `policies-config.json` del alcance seleccionado y luego ejecuta `failproofai policies` para detectar nombres de política o claves de parámetros desconocidos. + Edita el archivo `policies-config.json` del alcance seleccionado y luego ejecuta `failproofai policies`: este advierte sobre una entrada `policyParams` que nombra una política que ningún paquete instalado incluye. No verifica las claves dentro de una entrada, así que comprueba su ortografía en la tabla a continuación. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,6 +58,30 @@ Las políticas habilitadas se combinan como una unión. Los parámetros de polí +### Parámetros que aceptan las políticas de Failproof AI + +Cada política valida sus propios tipos de parámetros. + +| Política | Parámetro | Tipo y valor predeterminado | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; las entradas contienen `regex` y `label` | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| Bloqueadores de infraestructura | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + Un patrón de permiso amplía lo que un agente puede hacer. Prueba la tokenización exacta y las variantes de comandos en el arnés de destino antes de desplegarlo en toda una flota. + + ## Comprende los archivos de la máquina `~/.failproofai` contiene archivos separados para distintos límites de confianza: @@ -72,13 +90,13 @@ Las políticas habilitadas se combinan como una unión. Los parámetros de polí | --- | --- | | `config.json` | Configuración del daemon, auditoría y telemetría (sin secretos) | | `credentials.json` | Credenciales de la nube; almacenadas con permisos solo para el propietario | -| `policies-config.json` | Selección de funciones integradas en el alcance de usuario, parámetros y rutas personalizadas explícitas | -| `policies/` | Políticas de convención del usuario y artefactos de políticas gestionados por la nube | -| `hook-activity/` | Registro local de decisiones de política | -| `state/` | Cola del daemon, estado de salud, pausa y estado de ejecución | +| `policies-config.json` | Parámetros de alcance de usuario y rutas de políticas personalizadas explícitas | +| `policies/` | Políticas de convención del usuario, paquetes instalados con el estado de activación de sus políticas, y artefactos de políticas gestionadas en la nube | +| `hook-activity/` | Registro local de decisiones de políticas | +| `state/` | Spool del daemon, estado de salud, pausa y tiempo de ejecución | -Usa `FAILPROOFAI_HOME` para reubicar el diseño completo de la máquina en un contenedor o prueba aislada. No reubiques directorios de estado individuales de forma independiente. +Usa `FAILPROOFAI_HOME` para reubicar el esquema completo de la máquina en un contenedor o prueba aislada. No reubiques directorios de estado individuales de forma independiente. - Nunca confirmes `credentials.json` en el control de versiones. Confirma la configuración de políticas del proyecto y las políticas de convención del proyecto solo después de revisarlas como código de aplicación. + Nunca confirmes `credentials.json`. Confirma la configuración de políticas del proyecto y las políticas de convención del proyecto solo después de revisarlas como código de cumplimiento. \ No newline at end of file diff --git a/docs/es/policies/overview.mdx b/docs/es/policies/overview.mdx index f713008f..d8850c11 100644 --- a/docs/es/policies/overview.mdx +++ b/docs/es/policies/overview.mdx @@ -1,6 +1,6 @@ --- title: "Políticas" -description: "Observa, guía o bloquea las acciones del agente antes de que se repita un fallo conocido." +description: "Observa, guía o bloquea acciones del agente antes de que un fallo conocido vuelva a repetirse." icon: "shield-check" --- @@ -10,54 +10,45 @@ Una política evalúa un evento de hook del agente y devuelve una de tres decisi - `instruct` proporciona orientación correctiva al agente. - `deny` bloquea la acción con una razón. -## Usa las tres superficies de política +## Dónde viven las políticas - - - 1. Ve a **Observe → policy** para filtrar e inspeccionar las decisiones de política de las sesiones. - 2. Ve a **Admin → policy editor** para redactar, validar, publicar, deshabilitar o inspeccionar versiones inmutables. - 3. Ve a **Admin → enforcement** para asignar versiones y efectos a las máquinas. +| En el dashboard | Qué haces allí | +| --- | --- | +| **Observe → policy** | Revisa las decisiones de sesiones reales: qué política coincidió, en qué máquina y por qué | +| **Admin → policy editor** | Escribe una política, pruébala contra tráfico pasado, publica una versión inmutable y compara versiones en **library** | +| **Admin → enforcement** | Asigna versiones a máquinas, en modo observe o enforce | - Usa la página de política para entender qué está coincidiendo antes de crear o cambiar el enforcement. +El editor de políticas es donde un fallo se convierte en una regla. Describe el modo de fallo o pega el código fuente de la política en **compose**, prueba el borrador contra el tráfico que ya tienes y publica una versión: - ![La página de política mostrando totales de decisiones y los mapeos de políticas locales y gestionadas en la nube.](/images/dashboard/policy-observe.png) +![La vista de composición del editor de políticas con identidad de política, redacción asistida por IA, validación del código fuente y controles de publicación.](/images/dashboard/policy-editor.png) - El editor es donde conviertes una condición de fallo en código fuente, la validas y publicas una versión inmutable. +En una máquina, `failproofai policies` lista todo lo que se está aplicando. `fp policies` y `fp fleet` cubren el editor y la aplicación desde un terminal — consulta la [referencia de Cloud CLI](/es/reference/cloud-cli). - ![El editor de política usado para redactar y publicar una versión inmutable de política.](/images/dashboard/policy-editor.png) +## Obtener una política - Enforcement luego asigna esa versión publicada y su efecto de observación o aplicación a las máquinas. - - ![La flota de Enforcement mostrando la cobertura de máquinas y las versiones de política asignadas.](/images/dashboard/enforcement-fleet.png) - - Verifica las decisiones de vuelta en la página de política después del despliegue para que las vistas de creación y flota estén vinculadas a la actividad real del agente. - - - Usa `failproofai` para la instalación y validación de políticas locales: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - Usa `fp` para encontrar las sesiones y eventos en la nube que contienen decisiones de política. La creación de políticas en la nube y el despliegue en flota siguen siendo flujos de trabajo del dashboard. - - - -Las políticas tienen tres superficies distintas en Failproof AI: - -1. **Analizar decisiones** en sesiones, dashboards y auditorías. -2. **Crear versiones** con reglas integradas, código o el editor de políticas. -3. **Desplegar y aplicar** versiones en las máquinas seleccionadas. - -Comienza desde un modo de fallo confirmado. Define la coincidencia mínima de evento y herramienta que lo identifique, prueba ejemplos legítimos e inseguros, y luego observa antes de aplicar. +Hay dos formas de conseguir una. - - Habilita una regla revisada para riesgos comunes de secretos, shell, Git, nube y flujos de trabajo. + + Deja que Failproof AI redacte una a partir de un hallazgo de auditoría, o escribe el código fuente tú mismo, luego revísala y publícala en el editor. - - Expresa una decisión específica del flujo de trabajo en JavaScript o TypeScript. + + Conecta un pack de políticas de Failproof AI para tu caso de uso, o un pack de la comunidad desde el hub de políticas, con un solo comando. - \ No newline at end of file + + +## Luego despliégala + + + + Prueba el borrador contra el tráfico que ya tienes, y ejecútala contra una acción que debe detener y otra que debe permitir — todo antes de publicar. Consulta [Probar una política](/es/policies/test). + + + Asigna la versión a las máquinas en modo **observe**, lee sus decisiones y luego aplícala. Consulta [Desplegar una política](/es/policies/deploy). + + + Cada publicación crea una versión nueva e inmutable, por lo que un despliegue que bloquea trabajo válido se deshace volviendo a desplegar la última versión correcta. Consulta [Versiones y rollback](/es/policies/rollback). + + + +Para compartir tus políticas con otros equipos, [publícalas como un pack](/es/policies/publish-a-pack). Para saber qué ocurre cuando una política no puede evaluarse en absoluto, consulta [Comportamiento ante fallos](/es/policies/failure-behavior). \ No newline at end of file diff --git a/docs/es/policies/packs.mdx b/docs/es/policies/packs.mdx index 6937362d..7bb1a793 100644 --- a/docs/es/policies/packs.mdx +++ b/docs/es/policies/packs.mdx @@ -1,104 +1,113 @@ --- -title: "Paquetes de políticas" -description: "Instala un conjunto de políticas publicadas como una versión de GitHub y gestiona lo que aplica." +title: "Usar un paquete de políticas" +description: "Conecta un paquete de políticas de Failproof AI para tu caso de uso, o un paquete de la comunidad desde el hub de políticas, y elige qué aplica." icon: "package" --- -Un paquete es un conjunto de políticas publicadas como una versión de GitHub. Un solo comando lo instala, las sumas de verificación propias de la versión se comprueban antes de ejecutar nada, y el resumen se registra para que el paquete no pueda cambiar en tu máquina después. +Un paquete es un conjunto de políticas publicadas como una versión de GitHub. Un solo comando lo instala: los checksums de la versión se verifican antes de que se ejecute nada, y su digest se registra para que el paquete no pueda cambiar en tu máquina después de la instalación. -## Instalar las políticas de Failproof AI +Explora todos los paquetes, y cada política en cada uno, en el [hub de políticas](https://befailproof.ai/policy-hub/). Hay dos tipos: + +- **Paquetes de políticas de Failproof AI** — paquetes listos para usar en casos de uso predefinidos: conéctalos y funcionan. El [paquete de políticas para agente de codificación](https://befailproof.ai/policy-hub/failproofai/policies/) está disponible ahora, y pronto llegarán paquetes para más casos de uso. +- **Paquetes de políticas de la comunidad** — políticas que los desarrolladores han escrito para sus propios casos de uso y publicado para que cualquiera pueda utilizarlas. + +## Paquetes de políticas de Failproof AI + +### Paquete de políticas para agente de codificación ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -Esto instala el conjunto que publicamos, desde la copia incluida en el paquete npm, por lo que no necesita red y no puede fallar detrás de un proxy. Toma una parte de él: +El paquete incluye 38 políticas y activa las 10 que su manifiesto marca como seguras para habilitar de forma desatendida; el resto se lista para que elijas entre ellas. Algunas de las más utilizadas, y si un simple `policies add` las activa: + +| Política | Qué hace | Activa por defecto | +| --- | --- | --- | +| `block-push-master` | Bloquea los pushes directos a ramas protegidas | Sí | +| `block-env-files` | Bloquea la lectura y escritura de archivos `.env` | Sí | +| `protect-env-vars` | Bloquea comandos que exponen variables de entorno | Sí | +| `block-sudo` | Bloquea `sudo` a menos que coincida un patrón de permiso | Sí | +| `block-curl-pipe-sh` | Bloquea scripts descargados y enviados directamente a un shell | Sí | +| `sanitize-*` (cinco políticas) | Detecta claves de API, tokens bearer, JWTs, claves privadas y cadenas de conexión en la salida de herramientas | Sí | +| `block-rm-rf` | Bloquea eliminaciones recursivas catastróficas | No | +| `block-force-push` | Bloquea los force-pushes | No | +| `block-secrets-write` | Bloquea escrituras en archivos de credenciales y claves secretas | No | +| `warn-destructive-sql` | Advierte sobre `DROP`, `TRUNCATE` y `DELETE` sin `WHERE` | No | + +Activa las que estén desactivadas por nombre — `failproofai policies add block-rm-rf` — o toma el paquete completo con `--all`. Consulta todas las políticas agrupadas por categoría: ```bash -failproofai pack add core --policy block-rm-rf # una, o varias separadas por comas -failproofai pack add core --category dangerous-commands # una categoría completa -failproofai pack add core --all # todo lo que contiene +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` muestra cada categoría que ofrece el paquete. +## Paquetes de políticas de la comunidad -## Ver qué contiene un paquete antes de instalarlo +Los desarrolladores publican paquetes para los casos de uso que han encontrado, y el [hub de políticas](https://befailproof.ai/policy-hub/) los lista. Un paquete de la comunidad es publicado por su autor, no auditado por Failproof AI, así que lee lo que contiene antes de instalarlo: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -Lista todas las políticas que contiene el paquete, agrupadas por categoría, indicando cuáles el autor activa por defecto y cuáles son opcionales. Solo lee el **manifiesto** — el artefacto de entrada nunca se descarga ni se importa, por lo que consultar el paquete de alguien desconocido no puede ejecutar código ajeno. El manifiesto se verifica igualmente contra el `SHA256SUMS` de la versión, así que lo que estás leyendo es exactamente lo que se instalaría. - -`failproofai pack list` sin argumento lista los paquetes ya instalados en este equipo. +Esto lista todas las políticas que incluye, agrupadas por categoría, y marca cuáles activa el autor por defecto. Lee **únicamente el manifiesto** — el artefacto de entrada nunca se descarga ni importa, por lo que consultar el paquete de un desconocido no puede ejecutar código ajeno. El manifiesto sigue siendo verificado contra el propio `SHA256SUMS` de la versión, de modo que lo que lees es exactamente lo que se instalaría. -## Instalar el paquete de otra persona +Luego instálalo: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -Cualquiera de estas formas funciona — pega la que tengas a mano: +Cualquiera de estas formas funciona — pega la que tengas: -| Fuente | Resultado | +| Origen | Resultado | | --- | --- | -| `acme/support-agent` | La versión más reciente, **fijada** a la etiqueta exacta que resolvió | -| `acme/support-agent@v2.1.0` | Esa versión concreta | -| `github:acme/support-agent@v2.1.0` | Lo mismo, escrito explícitamente | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Lo mismo, copiado del navegador | +| `acme/support-agent` | La versión más reciente, **fijada** a la etiqueta exacta que se resolvió | +| `acme/support-agent@v2.1.0` | Esa versión | +| `github:acme/support-agent@v2.1.0` | Lo mismo, escrito de forma explícita | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Lo mismo, copiado desde un navegador | -Si no se especifica etiqueta, se instala la versión más reciente **y se fija**, indicándote qué etiqueta eligió. Lo que se registra siempre nombra exactamente una versión, por lo que una reinstalación no puede derivar. +No indicar ninguna etiqueta instala la versión más reciente **y la fija**, luego te indica qué etiqueta eligió. Lo que se registra siempre nombra exactamente una versión, por lo que una reinstalación no puede derivar. -## Tomar una parte de un paquete +## Tomar solo parte de un paquete -Por defecto obtienes los **propios** valores predeterminados del paquete — las políticas que el autor marcó como seguras para activar de forma desatendida — no todo lo que contiene. +Por defecto obtienes los valores predeterminados **propios** del paquete — las políticas que su autor marcó como seguras para activar de forma desatendida — no todo lo que contiene. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # una, o varias separadas por comas +failproofai policies add FailproofAI/policies --category dangerous-commands # una categoría completa +failproofai policies add FailproofAI/policies --all # todo lo que contiene ``` -`--category` y `--policy` se combinan como unión (`--only` se acepta como sinónimo de `--policy`). Volver a añadir el paquete con una versión más nueva conserva lo que elegiste en lugar de volver a activar el resto. +`--category` y `--policy` se combinan como una unión (`--only` se acepta como sinónimo de `--policy`). Cuando el paquete ya está instalado, los flags se suman a lo que tenías, y volver a añadirlo sin flag ni terminal — para actualizar, por ejemplo — mantiene tu selección tal como está. En una terminal sin flag, `add` abre el selector en su lugar, con los valores predeterminados del autor preseleccionados, y lo que marques reemplaza tu selección. ## Gestionar lo que está activo ```bash -failproofai policies # todas las fuentes en una sola lista, paquetes incluidos -failproofai pack list # solo paquetes, agrupados por categoría +failproofai policies # todas las fuentes en una lista, paquetes incluidos +failproofai policies add block-rm-rf # activar una política failproofai policies --uninstall block-refunds # desactivar una política de paquete -failproofai policies --install block-refunds # volver a activarla -failproofai pack remove acme/support-agent +failproofai policies --install block-refunds # y volver a activarla +failproofai policies remove acme/support-agent # desinstalar el paquete ``` -Un nombre sin prefijo se refiere a la política **integrada** cuando existe una con ese nombre. Nombra explícitamente la copia de un paquete cuando lo necesites: +Activar o desactivar una política de paquete se aplica a toda la máquina: el cambio se registra junto con el paquete instalado, no en la configuración de un proyecto, independientemente de lo que indique `--scope`. + +Un nombre sin barra es una política; cualquier cosa con una barra es una fuente de paquete. Un nombre simple se resuelve al paquete instalado que lo declara. Cuando dos paquetes instalados declaran el mismo nombre, especifica el que quieres decir: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -Si un paquete incluye una política cuyo nombre coincide con una **política integrada habilitada**, la integrada se ejecuta y la copia del paquete se omite — de lo contrario, la misma guarda se evaluaría dos veces. Desactiva la política integrada para usar la del paquete en su lugar. - - -## De dónde vienen las políticas de Failproof AI - -`core` lee la copia incluida en el paquete npm. El mismo conjunto se publica como versión de GitHub, que es lo que instalas si quieres una versión específica: - -```bash -failproofai pack add core # desde este paquete, sin red -failproofai pack add FailproofAI/policies # el mismo conjunto, desde su versión de GitHub -``` +Los ámbitos, parámetros y los archivos que escriben estos comandos se tratan en [configuración local](/es/policies/local-configuration). ## Qué garantiza y qué no garantiza la integridad -`SHA256SUMS` se distribuye en la misma versión que el artefacto, por lo que **no** es una firma y no demuestra nada sobre quién lo publicó. Lo que sí demuestra es que los bytes son exactamente los que esa versión publicó — y como el resumen se registra al añadir el paquete y se vuelve a verificar antes de cada importación, un paquete no puede cambiar en tu máquina después. Un repositorio que cambia la etiqueta o reemplaza un artefacto deja de cargarse en lugar de ejecutar silenciosamente algo diferente. +`SHA256SUMS` se incluye en la misma versión que el artefacto, por lo que **no** es una firma y no prueba nada sobre quién lo publicó. Lo que sí prueba es que los bytes son los que esa versión publicó — y como el digest se registra al añadir el paquete y se re-verifica antes de cada importación, un paquete no puede cambiar en tu máquina después de la instalación. Un repositorio que reetiqueta o reemplaza un asset deja de cargarse en lugar de ejecutar silenciosamente algo diferente. -En el momento de la instalación, el paquete también se **importa una vez** y se comprueba contra su propio manifiesto. Un paquete cuyo artefacto no se puede analizar, o que registra algo distinto de lo que declara, es rechazado antes de que se active cualquier cosa — en lugar de instalarse sin problemas y fallar en la siguiente llamada a una herramienta. +En el momento de la instalación, el paquete también se **importa una vez** y se verifica contra su propio manifiesto. Un paquete cuyo artefacto no se puede parsear, o que registra algo distinto a lo que declara, se rechaza antes de que se active nada — en lugar de instalarse correctamente y fallar en tu próxima llamada a herramienta. -## Cuándo un paquete no se carga +## Cuando un paquete no carga -Un paquete que este equipo tiene instrucciones de aplicar y no puede ejecutar **deniega** los eventos que cubrían sus políticas faltantes, en lugar de permitirlos silenciosamente. Consulta [Comportamiento ante fallos](/es/policies/failure-behavior). `failproofai pack list` identifica cualquier paquete en ese estado y termina con código de salida no cero. +Un paquete que esta máquina debe aplicar y no puede ejecutar **deniega** los eventos que cubrían sus políticas faltantes, en lugar de permitirlos silenciosamente — como `pack/failproofai-pack-unavailable`, que tiene prioridad sobre las políticas que sí se cargaron, de modo que la denegación se atribuye al paquete faltante y no al guardia que haya disparado primero. La excepción es `UserPromptSubmit`, que instruye en su lugar: denegar ahí te dejaría bloqueado del agente que necesitas para solucionarlo. Consulta [Comportamiento ante fallos](/es/policies/failure-behavior). ## Sin conexión y espejos @@ -107,4 +116,4 @@ Un paquete que este equipo tiene instrucciones de aplicar y no puede ejecutar ** | `FAILPROOFAI_NO_DOWNLOAD=1` | Rechaza descargas; los paquetes ya instalados siguen aplicándose | | `FAILPROOFAI_PACK_BASE_URL` | Redirige las descargas de paquetes a un espejo en lugar de `github.com` | -Para publicar tu propio paquete, consulta [Publicar un paquete](/es/policies/publish-a-pack). \ No newline at end of file +Para compartir tus propias políticas de esta forma, consulta [Publicar un paquete de políticas](/es/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/es/policies/publish-a-pack.mdx b/docs/es/policies/publish-a-pack.mdx index b9be5a64..edf86525 100644 --- a/docs/es/policies/publish-a-pack.mdx +++ b/docs/es/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "Publicar un pack" -description: "Distribuye tus propias políticas como una release de GitHub que cualquiera puede instalar." +title: "Publicar un pack de políticas" +description: "Publica tus propias políticas como una release de GitHub que cualquiera puede instalar." icon: "upload" --- -Un pack son tres archivos adjuntos a una release de GitHub. `failproofai pack build` genera los tres a partir de un archivo de políticas que ya tienes. +Un pack consiste en tres archivos adjuntos a una release de GitHub. `failproofai publish` genera los tres a partir de los archivos de políticas que tiene delante, crea la release y los sube. ## 1. Escribe las políticas -Un solo archivo, usando la misma API que cualquier política personalizada. Dos campos adicionales son importantes para un pack: +Comienza desde algo que ya funcione en lugar de una plantilla en blanco: + +```bash +failproofai publish --init +``` + +Esto pregunta cómo se llama el pack, escribe `.mjs` y se detiene — sin red, sin git, sin nada publicado. El archivo que genera contiene una única política que ya bloquea `git push --force`. Se niega a sobreescribir un archivo que ya existe. + +Las políticas usan la misma API que cualquier política personalizada. Dos campos adicionales importan para un pack: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` es **false** por defecto cuando se omite. Un `failproofai pack add` sin parámetros adicionales activa únicamente lo que marcaste — instalar silenciosamente todas las políticas de un desconocido no es una decisión que el instalador deba tomar por su usuario. +`defaultEnabled` tiene valor **false** por defecto si se omite. Un `failproofai policies add` simple activa únicamente lo que hayas marcado — instalar todas las políticas de un desconocido de forma desatendida no es una decisión que el instalador deba tomar por el usuario. + +Escribe todos los archivos que quieras; uno por categoría resulta fácil de leer. Cada archivo del directorio que registre políticas se empaqueta en el único artefacto que debe tener un pack. -La entrada debe ser **un único archivo autocontenido**. Solo la entrada tiene el digest anclado, por lo que un pack que importe archivos locales no podría afirmar honestamente que el digest cubre lo que se ejecuta. Empaqueta primero (`esbuild`, `bun build`, `rollup`) y construye el pack desde el bundle — `pack build` rechaza una importación local en lugar de hacer una promesa que no puede cumplir. + El empaquetado requiere **bun**. Sin él, limítate a un único archivo autocontenido. En cualquier caso, la entrada publicada no debe importar archivos locales en tiempo de instalación: solo la entrada tiene el digest fijado, por lo que un pack que accediera a archivos hermanos no podría afirmar honestamente que el digest cubre lo que se ejecuta — y `publish` lo rechaza en lugar de publicar una promesa que no puede cumplir. -## 2. Construye los archivos de la release +## 2. Pruébalo primero aquí + +Antes de que nadie más pueda verlo, aplica el archivo en esta máquina: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +Cualquier ruta, cualquier nombre de archivo. Pide a tu agente que haga lo que bloqueaste y observa cómo es rechazado. Nada se publica y nadie más se ve afectado. [Probar una política](/es/policies/test) cubre el resto: el caso legítimo que debe permitir, y las entradas que la rompen. + +## 3. Publícalo + +```bash +failproofai publish ``` -Genera tres archivos y valida cada política con las **reglas propias del cargador** primero — así, un pack que nunca podría instalarse falla aquí, donde puedes corregirlo: +Determina dónde publicar, qué empaquetar y qué versión asignarle, y solo pregunta cuando nada en el repositorio se lo indica. En orden, deteniéndose antes de crear una release si algo está mal: + +1. Encuentra los archivos de políticas aquí por **contenido** — los que importan `failproofai` y llaman a `customPolicies.add` — en lugar de por nombre, por lo que encuentra `guards.mjs` e ignora un `policies.mjs` no relacionado. No desciende a subdirectorios, así que un fixture de pruebas nunca es recogido por accidente. +2. Lee el repositorio desde `git remote get-url origin`, en el directorio **del archivo** en lugar del tuyo, y decide la versión. +3. Busca tus credenciales: `GITHUB_TOKEN`, `GH_TOKEN` o `gh auth login`. Solo necesita permiso de escritura sobre releases, y nunca se imprime. +4. Crea el repositorio si no existe. Esto ocurre antes de la compilación, por lo que un pack rechazado en el siguiente paso puede dejar un repositorio nuevo sin ninguna release. +5. Compila los tres assets, validándolos con **las propias reglas del loader** — el mismo código que decide qué puede instalarse en la máquina de un desconocido — de modo que un pack que nunca podría instalarse falla aquí, donde todavía puedes corregirlo. +6. Crea o reutiliza la release y sube los archivos, reemplazando assets con el mismo nombre. -| Archivo | Qué es | +| Archivo | Descripción | | --- | --- | | `failproofai-pack.json` | El manifiesto: id, versión, efecto y una entrada por política | -| `failproofai-pack.mjs` | Tu entrada, tal cual | +| `failproofai-pack.mjs` | Tu entrada empaquetada | | `SHA256SUMS` | ` ` para los otros dos | -Se rechaza en tiempo de construcción: un id que no sea `publisher/name`, un nombre de política que contenga `/`, una política que declare `alwaysOn`, una `description`, `category` o `match` ausente, una entrada que no registre nada, y una entrada que importe archivos locales. +Los nombres de los assets son fijos — son los que la CLI del consumidor usa para construir sus URLs, sin llamadas a la API y sin descubrimiento. -## 3. Adjúntalos a una release +Rechazado en tiempo de compilación: un id que no sea `publisher/name`, un nombre de política que contenga `/`, una política que declare `alwaysOn`, una `description`, `category` o `match` ausentes, una entrada que no registre nada, y una entrada que importe archivos locales. -Etiqueta la release con la misma versión que construiste y adjunta los tres archivos como assets de la release: +Sobreescribe cualquier decisión tomada automáticamente: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -Ahora cualquiera puede instalarlo: +`--id` establece el id del pack cuando debe diferir del repositorio, `--tag` establece la etiqueta de la release, `--notes` reemplaza las notas de release generadas automáticamente — que es donde `policies show --releases` lee los recuentos y el commit de cada release — `--out` elige dónde se escriben los assets (por defecto `dist-pack`), y `--dry-run` los compila sin publicar y no necesita credenciales. -```bash -failproofai pack add acme/support-agent -``` +Ahora cualquiera puede instalarlo con `failproofai policies add acme/support-agent`. Consulta [packs de políticas](/es/policies/packs) para fijar una versión o instalar solo una parte. + +### Listarlo en el hub de políticas -Los nombres de los assets son fijos — son los que usa la CLI del consumidor para construir sus URLs, sin ninguna llamada a la API ni proceso de descubrimiento. +Añade el topic `failproofai-policies` al repositorio en GitHub. No hay formulario de envío ni cola de aprobación: el rastreador del [policy hub](https://befailproof.ai/policy-hub/) recoge el repositorio en su próxima pasada. El topic solo lo propone para consideración — lo que lo lista es una release cuyo manifiesto se verifica contra su propio `SHA256SUMS` y se analiza bajo las mismas reglas que usa la CLI, que es exactamente lo que produce `failproofai publish`. + +## Cómo se decide la versión + +La versión es el **commit desde el que estás publicando** — su sha corto, doce caracteres: `a1b2c3d4e5f6`. No hay nada que elegir ni incrementar, y la versión nombra exactamente de dónde provienen los bytes, por lo que publicar la misma fuente dos veces produce la misma versión. + +Se lee del árbol que tienes delante, nunca de las releases del repositorio, por lo que un clon reciente y una máquina sin conexión calculan la misma respuesta sin necesidad de consultar a GitHub qué ocurrió antes. + +Dado que la versión nombra un commit, ese commit debe existir. En una terminal, `publish` lo crea por ti: inicializa un repositorio cuando no hay ninguno, y hace commit de los archivos de políticas modificados antes de compilar. Se **niega** — indicando `--version` como salida — cuando se ejecuta sin terminal (un commit hecho en un runner de CI no existiría en ningún otro lugar), cuando hay archivos distintos de las políticas sin commitear, o en un checkout que aún no tiene commits. Una etiqueta en `HEAD` tiene prioridad sobre el sha — quien etiquetó `v1.2.0` ha declarado qué es esta release. + +Un sha no tiene ordenación propia, así que usa `failproofai policies show / --releases` para ver qué release llegó primero — la más reciente en la parte superior. ## Publicar una nueva versión -Construye con el nuevo `--version`, etiqueta una nueva release y adjunta los tres assets de nuevo. Los consumidores ejecutan el mismo `pack add` y conservan el subconjunto que habían elegido; una política que desactivaron permanece desactivada tras la actualización. +Haz commit del cambio y ejecuta `failproofai publish` de nuevo — el nuevo commit es la nueva versión. Los consumidores ejecutan el mismo `failproofai policies add`. Sin terminal, o con un flag de selección, conservan el subconjunto que habían elegido y una política que desactivaron permanece desactivada; en una terminal sin flag, el selector se abre pre-marcado con tus valores por defecto y su respuesta reemplaza su selección. -Cambiar el **nombre** de una política es un cambio incompatible: una máquina que la había desactivado está desactivando un nombre que ya no existe, y el nuevo nombre llega con lo que diga `defaultEnabled`. +Cambiar el **nombre** de una política es un cambio que rompe la compatibilidad: una máquina que la había desactivado estará desactivando un nombre que ya no existe, y el nuevo nombre llega con el valor que diga `defaultEnabled`. ## En qué confían tus usuarios -`SHA256SUMS` vive en la misma release que el artefacto, por lo que prueba que los bytes son los que publicaste — no quién eres. Cualquiera que pueda escribir en el repositorio puede modificar ambos archivos. La protección de tus usuarios radica en que el digest queda anclado cuando instalan, de modo que lo que publicaste no puede cambiar posteriormente para ellos. +`SHA256SUMS` vive en la misma release que el artefacto, por lo que prueba que los bytes son los que publicaste — no quién eres. Quien tenga acceso de escritura al repositorio puede escribir ambos archivos. La protección de tus usuarios es que el digest queda fijado en el momento de la instalación, por lo que lo que publicaste no puede cambiar después bajo sus pies. + +Publica desde un repositorio cuyo acceso de escritura controles, y trata una release de pack como si publicaras un paquete. -Publica desde un repositorio cuyo acceso de escritura controles y trata una release de pack como si fuera la publicación de un paquete. +El repositorio también debe ser **público**. Las instalaciones son HTTPS anónimas sin credenciales que ofrecer, por lo que un repositorio privado existente se rechaza antes de compilar o subir nada, y uno que `publish` crea es público por la misma razón. `--allow-private` anula esto para quien entregue los tres assets por otra vía, e indica claramente que ningún `policies add` puede acceder a ellos. Solo importa la release: las instalaciones leen `releases/download//` y nunca tocan tu árbol git. ## Observar antes de aplicar -Un manifiesto puede declarar `"effect": "observe"`. Esas políticas se ejecutan y sus veredictos se **registran y descartan** — nada queda bloqueado. Es la manera de medir una nueva regla frente al tráfico real antes de que pueda interrumpir el trabajo de alguien. +Un manifiesto puede declarar `"effect": "observe"` — `failproofai publish --effect observe` es lo que lo establece. Esas políticas se ejecutan y sus veredictos son **registrados y descartados** — nada es bloqueado. Es la forma de medir una nueva regla contra tráfico real antes de que pueda interrumpir el trabajo de alguien. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/es/policies/rollback.mdx b/docs/es/policies/rollback.mdx index f1ed355b..0a002162 100644 --- a/docs/es/policies/rollback.mdx +++ b/docs/es/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "Reversión" -description: "Restaura una implementación de políticas conocida cuando un despliegue interrumpe el trabajo válido del agente." +title: "Versiones y reversión" +description: "Cada publicación es una versión inmutable, por lo que una implementación que interrumpa el trabajo válido de un agente se deshace volviendo a desplegar la última versión correcta." icon: "rotate-ccw" --- -La reversión cambia la versión desplegada o elimina una asignación de política; no borra el historial de decisiones que explica el incidente. +Una versión de política publicada nunca cambia. Editar una política y volver a publicarla genera una nueva versión; nunca sobreescribe la que ya está en las máquinas. Eso es lo que hace que la reversión sea segura: la última versión correcta sigue ahí, byte a byte, y revertir no borra el historial de decisiones que explica qué salió mal. + +## Encontrar una versión + + + + Ve a **Admin → editor de políticas** y abre la **biblioteca** para comparar las versiones de una política o desactivar una. + + + ```bash + fp policies list # every policy version + fp policies show # one version, with its source + ``` + + ## Revertir una máquina 1. Ve a **Admin → enforcement**, expande la máquina afectada e identifica su último conjunto de políticas conocido como correcto. - 2. Selecciona **edit**, restaura esas versiones y efectos, y aplica el nuevo despliegue. - 3. Espera a que la máquina haga check-in y luego verifica el despliegue reportado. + 2. Selecciona **editar**, restaura esas versiones y efectos, y aplica el nuevo despliegue. + 3. Espera el registro de conexión de la máquina y verifica el despliegue reportado. 4. Abre **Observe → policy** y las sesiones afectadas para confirmar que el trabajo válido ya no está bloqueado. - - La reversión de un despliegue en la nube es un flujo de trabajo del panel de control. Usa el estado local para confirmar que el despliegue corregido ha llegado a la máquina: + Cada despliegue en una máquina es una generación numerada. Listarlas y luego restablecer una: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` pausa las políticas integradas, personalizadas y de convención para una sesión local. No pausa las políticas gestionadas por la nube, por lo que no es una solución alternativa para un despliegue incorrecto en la nube. + `rollback` genera una nueva generación que contiene el conjunto anterior en lugar de retroceder el contador, por lo que el historial permanece solo de adición, y rechaza una generación que nombre una política desactivada o eliminada. Requiere una sesión iniciada con `policies:write`. `fp fleet diff ` muestra lo que se pretendía aplicar frente a lo que la máquina efectivamente aplicó — aparece como `behind` hasta que la máquina vuelva a sondear — y en la propia máquina, `failproofai policies` lista el despliegue que está ejecutando. -## Cuándo hacer una reversión +## Quitar una política de todas las máquinas + +```bash +fp policies disable # remove it from every deployment carrying it +fp policies enable # add it back +``` + +Cada comando genera una nueva generación en cada despliegue que afecta. Revertir una de esas generaciones no es la forma de deshacer un `disable`, sin embargo — `rollback` rechaza una generación que nombre una política desactivada, y cada generación anterior a la desactivación nombra esta política. `fp policies enable` es el camino de regreso, y genera su propia generación a su vez. + +## Revertir un paquete + +Un paquete está anclado a la versión que instalaste, por lo que revertirlo implica instalar una anterior: + +```bash +failproofai policies show FailproofAI/policies --releases # every version it has published, and which one is here +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # pin that one +``` + +Sin una terminal, o con `--policy`, `--category` o `--all`, volver a agregar conserva el subconjunto que habías elegido. En una terminal sin ninguna de esas opciones, abre el selector con las selecciones predeterminadas del autor ya marcadas, y lo que marques reemplaza tu selección — así que vuelve a marcar lo que tenías. + +## Cuándo revertir - Una política bloquea una acción de producción esperada. -- El volumen de coincidencias es materialmente mayor que el predicho durante el despliegue observado. +- El volumen de coincidencias es materialmente superior al que predijo el despliegue observado. - Una política depende de campos que una integración no proporciona. - Una nueva versión cambia el comportamiento fuera del modo de fallo previsto. -Tras la reversión, abre las sesiones afectadas e identifica la condición que causó el falso positivo. Crea una nueva versión, prueba tanto los casos inseguros como los legítimos y repite la fase de observación. +Después de revertir, abre las sesiones afectadas y encuentra la condición detrás del falso positivo. Publica una nueva versión, [prueba](/es/policies/test) tanto el caso inseguro como el legítimo, y vuelve a observarla antes de aplicarla. - Pausar la aplicación de políticas puede ser apropiado durante un incidente, pero amplía la exposición para todas las políticas activas en ese ámbito. Siempre que sea posible, prefiere revertir la versión de política específica. + `failproofai config --pause` suspende las políticas locales durante una sesión y nunca las gestionadas por Cloud, por lo que no es una salida ante un despliegue en Cloud defectuoso. Una pausa también amplía la exposición para todas las políticas en su alcance; es preferible revertir la versión concreta que se está comportando incorrectamente. \ No newline at end of file diff --git a/docs/es/policies/test.mdx b/docs/es/policies/test.mdx new file mode 100644 index 00000000..0e014198 --- /dev/null +++ b/docs/es/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "Probar una política" +description: "Realiza backtesting de un borrador con el tráfico que ya tienes, y comprueba que bloquea lo que debe y permite lo que es necesario, antes de que ninguna máquina la aplique." +icon: "flask-conical" +--- + +Prueba cada política de dos formas: con el tráfico que tus agentes ya generaron, y con una acción legítima que debe permitir pasar. Una política que solo ha visto el caso inseguro no ha sido probada. + +## Backtest del borrador + + + + El editor de políticas reproduce un borrador contra las llamadas que tu flota ya realizó, antes de publicarlo. + + 1. Abre el borrador en **Admin → policy editor**. El editor confirma que se analiza como JavaScript. + 2. En **backtest**, elige los agentes y la ventana de tiempo a reproducir — **every agent** y **30d** por defecto — y deja el último filtro en **everything** salvo que quieras reducir el alcance. + 3. Selecciona **run backtest**. + + ![El panel de backtest bajo un borrador que se analiza como JavaScript, con sus tres filtros y la acción run backtest, encima de publish version.](/images/dashboard/policy-backtest.png) + + El resultado muestra lo que el borrador habría hecho con esas llamadas — incluido cuántas llamadas **working** habría interrumpido. Son falsos positivos encontrados antes de que ningún agente los encuentre: ajusta el borrador y ejecútalo de nuevo hasta que ese número sea aceptable. + + + El backtest es una función del dashboard. Desde un terminal, ejecuta la política contra eventos que describas tú mismo, como se indica a continuación. + + + +## Ejecútala contra un evento que describes tú + +`fp policies test` ejecuta un archivo de política en tu máquina contra un evento sintético y comprueba la decisión. No se publica nada y nada llega a Cloud: + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +Da forma al evento con `--event`, `--tool`, `--command` y `--file`. El propio filtro `match` de la política sigue aplicándose, por lo que una política que no cubre el evento descrito reporta `skipped` en lugar de una decisión — normalmente es señal de que su `match` es más restrictivo de lo que pretendías. + +## Ejecútala en una sola máquina + +A continuación, aplícala de verdad en tu propia máquina, contra tu propio agente: + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +El primer comando valida e instala el archivo; el segundo confirma que se ha cargado, junto con todo lo demás que se aplica aquí. Pide al agente que haga lo que la política bloquea y observa cómo lo rechaza; luego haz la versión legítima y observa cómo pasa. Nadie más se ve afectado. + +En una máquina conectada a Cloud, comprueba ambas decisiones en **Observe → policy**: filtra por el nombre de la política, luego abre cada sesión vinculada para confirmar la entrada de la herramienta que coincidió y el motivo que devolvió. + +## Prueba qué falla + +La instalación rechaza un archivo inexistente, un error de sintaxis, una importación no resuelta, una excepción a nivel superior o un módulo que agota el tiempo de carga — así que vuelve a ejecutarlo después de cada cambio en el archivo o en cualquier cosa que importe. En el momento de la aplicación, el mismo archivo defectuoso se registra y se marca como **skipped** para que el resto de políticas sigan ejecutándose: trata una advertencia de carga en los logs de producción como una aplicación perdida. Los archivos de convención se cargan sin el comando de instalación, así que mantén un paso explícito de `failproofai policies --install --custom ` en CI — es lo que hace fallar la build cuando una política está rota. + +Luego aliméntala con lo que los agentes realmente envían, no solo con la entrada que esperas: campos faltantes, nombres alternativos de herramientas como `Write` y `Edit`, rutas de Windows, entradas mal formadas. Devuelve un `allow`, `instruct` o `deny` intencional en cada ruta, mantén la función determinista y limita cualquier llamada externa con un timeout corto. + +## Luego publícala y obsérvala + +Un backtest muestra lo que la política habría hecho con el tráfico que tenías; no puede mostrar qué hará el tráfico que aún no has visto. Selecciona **publish version** en el editor (o ejecuta `fp policies publish`), luego [despliégala](/es/policies/deploy) primero en modo **observe** — sus veredictos se registran y nada se bloquea — y aplica la ejecución una vez que sus coincidencias separen las acciones inseguras de las válidas. \ No newline at end of file diff --git a/docs/es/reference/cloud-cli.mdx b/docs/es/reference/cloud-cli.mdx index 226d0b37..d63fe3bb 100644 --- a/docs/es/reference/cloud-cli.mdx +++ b/docs/es/reference/cloud-cli.mdx @@ -4,9 +4,9 @@ description: "Referencia completa para consultar y administrar Failproof AI Clou icon: "cloud-cog" --- -Usa `fp` para inspeccionar la telemetría de Cloud, gestionar la aplicación administrada en la nube (políticas, despliegues de flota, decisiones de guardarraíles) y administrar auditorías, hallazgos, incidencias, alertas, claves, usuarios, consultas y configuraciones. Usa [`failproofai`](/es/reference/failproof-cli) para hooks locales, políticas, captura e inscripción de máquinas. +Use `fp` para inspeccionar la telemetría de Cloud, gestionar la aplicación administrada en la nube (políticas, despliegues de flota, decisiones de guardrail) y administrar auditorías, hallazgos, incidencias, alertas, claves, usuarios, consultas y configuración. Use [`failproofai`](/es/reference/failproof-cli) para hooks locales, políticas, captura e inscripción de máquinas. -Instala el Cloud CLI publicado como herramienta aislada: +Instale el Cloud CLI publicado como herramienta aislada: ```bash uv tool install fp-cloud-cli @@ -23,7 +23,7 @@ fp whoami ## Sintaxis ```text -fp [OPCIONES_GLOBALES] COMANDO [SUBCOMANDO] [ARGUMENTOS] [OPCIONES] +fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` Las opciones globales deben ir antes del comando: @@ -32,7 +32,7 @@ Las opciones globales deben ir antes del comando: fp --json sessions --since 24h ``` -Ejecuta `fp COMANDO --help` o `fp COMANDO SUBCOMANDO --help` para ver la ayuda en el terminal. +Ejecute `fp COMMAND --help` o `fp COMMAND SUBCOMMAND --help` para obtener ayuda en la terminal. ## Comandos de la CLI @@ -44,10 +44,10 @@ Ejecuta `fp COMANDO --help` o `fp COMANDO SUBCOMANDO --help` para ver la ayuda e | `fp logout` | Revoca y elimina la sesión de usuario guardada. | — | | `fp whoami` | Muestra la identidad actual, el modo de autenticación, la organización y los permisos. | — | | `fp version` | Muestra la versión instalada de la CLI. | — | -| `fp help` | Muestra la ayuda de los comandos principales. | — | +| `fp help` | Muestra la ayuda de los comandos de nivel superior. | — | ```bash -fp login --email tu@ejemplo.com --org equipo-fiabilidad +fp login --email you@example.com --org reliability-team fp whoami ``` @@ -57,23 +57,23 @@ fp whoami fp events [OPTIONS] ``` -Lista eventos individuales de agentes. El feed ligero predeterminado excluye los payloads sin procesar; usa `--full` únicamente para una investigación acotada. +Lista los eventos individuales de agentes. El feed ligero predeterminado excluye los payloads sin procesar; use `--full` solo para una investigación acotada. | Opción | Descripción | | --- | --- | -| `--limit`, `-n ` | Máximo total de filas. Predeterminado: `50`. | +| `--limit`, `-n ` | Máximo total de filas. Por defecto: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` o `7d`. | -| `--from ` / `--to ` | Rango UTC en ISO 8601; sustituye a `--since`. | -| `--env ` | Filtro de entorno; repite o separa valores con comas. | -| `--event-type ` | Filtro de tipo de evento; repite o separa valores con comas. | -| `--agent-id ` | Filtro de agente; repite o separa valores con comas. | -| `--session-id ` | Filtro de sesión; repite o separa valores con comas. | +| `--from ` / `--to ` | Rango UTC en ISO 8601; reemplaza a `--since`. | +| `--env ` | Filtro de entorno; repita o separe con comas. | +| `--event-type ` | Filtro de tipo de evento; repita o separe con comas. | +| `--agent-id ` | Filtro de agente; repita o separe con comas. | +| `--session-id ` | Filtro de sesión; repita o separe con comas. | | `--search ` | Búsqueda de texto en el payload; repetible, coincide con cualquier término. | -| `--order asc\|desc` | Orden temporal. Predeterminado: más reciente primero. | -| `--all` | Paginación automática hasta `--limit`. | +| `--order asc\|desc` | Orden temporal. Por defecto: más reciente primero. | +| `--all` | Pagina automáticamente hasta `--limit`. | | `--cursor ` | Reanuda desde un cursor opaco. | | `--page-size ` | Filas por solicitud con `--all`; máximo `200`. | -| `--full` | Incluye los payloads sin procesar a través del endpoint de eventos más pesado. | +| `--full` | Incluye payloads sin procesar a través del endpoint de eventos más pesado. | | `--fields ` | Devuelve solo los campos seleccionados; solicitar `payload` activa el modo completo. | ```bash @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` pagina **hasta `--limit`**, cuyo valor predeterminado es **50**, por lo que `--all` solo se detiene en 50 filas. Cuando se detiene antes de tiempo, la respuesta incluye un `next_cursor` para reanudar; `"next_cursor": null` indica que el feed realmente se agotó. + `--all` pagina **hasta `--limit`**, que por defecto es **50** — por lo que `--all` solo se detiene en 50 filas. Cuando se detiene antes de tiempo, la respuesta incluye un `next_cursor` para reanudar desde allí; `"next_cursor": null` significa que el feed realmente se agotó. ### Sesiones @@ -93,18 +93,18 @@ fp sessions [OPTIONS] | Opción | Descripción | | --- | --- | -| `--limit`, `-n ` | Máximo total de filas. Predeterminado: `50`. | +| `--limit`, `-n ` | Máximo total de filas. Por defecto: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` o `7d`. | -| `--from ` / `--to ` | Rango UTC en ISO 8601; sustituye a `--since`. | -| `--env ` | Filtro de entorno; repite o separa valores con comas. | -| `--status ` | `done`, `error` o `timeout`; repite o separa valores con comas. | -| `--agent-id ` | Busca sesiones que involucren cualquier agente seleccionado. | -| `--session-id ` | Filtro de sesión; repite o separa valores con comas. | -| `--all` | Paginación automática hasta `--limit`. | +| `--from ` / `--to ` | Rango UTC en ISO 8601; reemplaza a `--since`. | +| `--env ` | Filtro de entorno; repita o separe con comas. | +| `--status ` | `done`, `error` o `timeout`; repita o separe con comas. | +| `--agent-id ` | Coincide con sesiones que involucren algún agente seleccionado. | +| `--session-id ` | Filtro de sesión; repita o separe con comas. | +| `--all` | Pagina automáticamente hasta `--limit`. | | `--cursor ` | Reanuda desde un cursor opaco. | | `--page-size ` | Filas por solicitud con `--all`; máximo `200`. | | `--fields ` | Devuelve solo los campos seleccionados. | -| `--full-ids` | No acorta los IDs de sesión en la salida del terminal. | +| `--full-ids` | No abrevia los IDs de sesión en la salida de la terminal. | | `--agents` | Expande el listado de agentes para sesiones multiagente. | ### Evaluaciones @@ -116,14 +116,14 @@ fp evals [OPTIONS] | Opción | Descripción | | --- | --- | | `--aggregate` | Muestra totales y estadísticas por puntuación en lugar de evaluaciones individuales. | -| `--limit`, `-n ` | Máximo de filas en el listado. Predeterminado: `50`. | -| `--since`, `--from`, `--to` | Selecciona el rango temporal. | -| `--env`, `--status`, `--agent-id`, `--session-id` | Restringe a un único valor exacto por filtro. | +| `--limit`, `-n ` | Máximo de filas en la lista. Por defecto: `50`. | +| `--since`, `--from`, `--to` | Selecciona el rango de tiempo. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Limita a un valor exacto por filtro. | | `--score KEY:MIN..MAX` | Rango de puntuación; repetible y todos los rangos deben coincidir. | -| `--all`, `--cursor`, `--page-size` | Controla la paginación del listado. | +| `--all`, `--cursor`, `--page-size` | Controla la paginación de la lista. | | `--fields ` | Devuelve solo los campos seleccionados. | | `--full-ids` | Muestra los IDs de sesión completos. | -| `--scores-full` | Muestra todas las puntuaciones en la salida del terminal. | +| `--scores-full` | Muestra todas las puntuaciones en la salida de la terminal. | ### Errores @@ -134,12 +134,12 @@ fp errors [OPTIONS] | Opción | Descripción | | --- | --- | | `--aggregate` | Resume los errores coincidentes en lugar de listar filas. | -| `--limit`, `-n ` | Máximo de filas en el listado. Predeterminado: `50`. | -| `--since`, `--from`, `--to` | Selecciona el rango temporal. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Restringe la población de errores. | +| `--limit`, `-n ` | Máximo de filas en la lista. Por defecto: `50`. | +| `--since`, `--from`, `--to` | Selecciona el rango de tiempo. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Reduce el conjunto de errores. | | `--search ` | Busca texto en el payload; repetible. | | `--order asc\|desc` | Orden temporal. | -| `--all`, `--cursor`, `--page-size` | Controla la paginación del listado. | +| `--all`, `--cursor`, `--page-size` | Controla la paginación de la lista. | | `--fields ` | Devuelve solo los campos seleccionados. | | `--full-ids` | Muestra los IDs de sesión completos. | @@ -147,9 +147,9 @@ fp errors [OPTIONS] | Comando | Propósito | | --- | --- | -| `fp usage` | Muestra el uso para la ventana de medición actual. | +| `fp usage` | Muestra el uso en la ventana de medición actual. | | `fp list envs` | Lista los entornos observados. | -| `fp list agents` | Lista los IDs de agente observados. | +| `fp list agents` | Lista los IDs de agentes observados. | | `fp list event_types` | Lista los tipos de evento. | | `fp list score_filters` | Lista las claves de puntuación de evaluación. | | `fp list models` | Lista los nombres de modelos. | @@ -162,7 +162,7 @@ fp errors [OPTIONS] | Comando | Propósito | | --- | --- | | `fp orgs list` | Lista las organizaciones accesibles. | -| `fp orgs switch [SLUG]` | Guarda una organización activa; muestra un prompt si se omite. | +| `fp orgs switch [SLUG]` | Guarda una organización activa; solicita selección si se omite. | | `fp orgs current` | Muestra la organización activa. | | `fp orgs perms` | Muestra tus permisos en la organización activa. | @@ -171,13 +171,13 @@ fp errors [OPTIONS] | Comando | Propósito | Opciones | | --- | --- | --- | | `fp keys list` | Lista las claves de la organización. | `--show-id`; `--fields ` | -| `fp keys show NAME` | Muestra una clave y sus concesiones. | — | -| `fp keys create NAME` | Crea una clave y muestra su secreto una única vez. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | Reemplaza el conjunto de permisos o ajusta las concesiones. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | Rota el secreto y muestra el reemplazo una única vez. | `--yes`, `-y` | +| `fp keys show NAME` | Muestra una clave y sus permisos. | — | +| `fp keys create NAME` | Crea una clave y revela su secreto una sola vez. | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | Reemplaza el conjunto de permisos o ajusta los permisos concedidos. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | Rota el secreto y revela el reemplazo una sola vez. | `--yes`, `-y` | | `fp keys disable NAME` | Revoca permanentemente una clave. | `--yes`, `-y` | -Los tokens de permiso usan el formato `recurso:acción`, por ejemplo `events:add`. Repite `--add`, separa tokens con comas o usa acciones con puntos como `events:read.add`. +Los tokens de permiso usan el formato `recurso:acción`, como `events:add`. Repita `--add`, separe los tokens con comas o use acciones con puntos como `events:read.add`. ### Consultas @@ -196,9 +196,9 @@ Los tokens de permiso usan el formato `recurso:acción`, por ejemplo `events:add | Comando | Propósito | Opciones | | --- | --- | --- | | `fp users list` | Lista los miembros de la organización. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | Muestra un miembro y sus concesiones. | — | -| `fp users create EMAIL` | Añade un miembro. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | Cambia las concesiones de un miembro. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users show EMAIL` | Muestra un miembro y sus permisos. | — | +| `fp users create EMAIL` | Agrega un miembro. | `--permission-set`; `--add`; `--remove` | +| `fp users update EMAIL` | Modifica los permisos de un miembro. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | | `fp users disable EMAIL` | Deshabilita el inicio de sesión. | `--yes`, `-y` | | `fp users enable EMAIL` | Vuelve a habilitar el inicio de sesión. | `--yes`, `-y` | @@ -206,9 +206,9 @@ Los tokens de permiso usan el formato `recurso:acción`, por ejemplo `events:add | Comando | Propósito | Opciones | | --- | --- | --- | -| `fp settings list` | Lista las configuraciones de la organización y sus valores actuales. | — | +| `fp settings list` | Lista la configuración de la organización y sus valores actuales. | — | | `fp settings schema` | Muestra los valores aceptados y sus descripciones. | — | -| `fp settings set KEY` | Cambia una configuración existente. | exactamente uno de `--value`, `--json-value`, `--file`; `--yes`, `-y` opcional | +| `fp settings set KEY` | Modifica una configuración existente. | exactamente uno de `--value`, `--json-value`, `--file`; `--yes`, `-y` opcional | ### Alertas @@ -221,7 +221,7 @@ Los tokens de permiso usan el formato `recurso:acción`, por ejemplo `events:add | `fp alerts delete NAME` | Elimina una alerta. | `--yes`, `-y` | | `fp alerts test NAME` | Envía una notificación de prueba. | `--channels`; `--yes`, `-y` | -Las gravedades de alerta son `info`, `warning` y `critical`. Los tipos de disparador son `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` y `per_event`. Los intervalos de evaluación deben estar entre 30 y 86 400 segundos. +Las severidades de alerta son `info`, `warning` y `critical`. Los tipos de disparador son `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` y `per_event`. Los intervalos de evaluación deben estar entre 30 y 86 400 segundos. ### Auditorías @@ -229,22 +229,22 @@ Las gravedades de alerta son `info`, `warning` y `critical`. Los tipos de dispar | --- | --- | --- | | `fp audits list` | Lista las auditorías. | `--enabled-only`; `--show-id` | | `fp audits show NAME` | Muestra una definición de auditoría y su estado. | — | -| `fp audits create NAME` | Crea una auditoría y pone en cola su primera ejecución de inmediato. | Consulta las [opciones de creación](#audit-create-options). | +| `fp audits create NAME` | Crea una auditoría y pone en cola su primera ejecución inmediatamente. | Ver [opciones de creación](#audit-create-options). | | `fp audits edit NAME` | Reemplaza la configuración de la auditoría conservando los valores no especificados. | opciones de definición de creación; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | Elimina una auditoría, sus hallazgos y el historial de ejecuciones. | `--yes`, `-y` | | `fp audits run NAME` | Pone en cola una ejecución manual. | — | | `fp audits runs NAME` | Lista el historial de ejecuciones. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | Muestra el resumen y el estado de obtención de URLs de referencia. | — | -| `fp audits context-set NAME` | Cambia el resumen o las URLs de referencia. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-show NAME` | Muestra el resumen y el estado de obtención de las URLs de referencia. | — | +| `fp audits context-set NAME` | Modifica el resumen o las URLs de referencia. | `--text`; `--text-file`; `--url`; `--clear-urls` | | `fp audits context-refresh NAME` | Vuelve a obtener las URLs de referencia. | — | | `fp audits findings` | Lista los hallazgos. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | | `fp audits finding FINDING_ID` | Muestra un hallazgo y su evidencia. | — | -| `fp audits ack FINDING_ID` | Reconoce un hallazgo. | `--reason` | +| `fp audits ack FINDING_ID` | Confirma un hallazgo. | `--reason` | | `fp audits mute FINDING_ID` | Suprime un patrón recurrente. | `--reason`; `--yes`, `-y` | | `fp audits dismiss FINDING_ID` | Marca un patrón como no accionable y lo suprime. | `--reason`; `--yes`, `-y` | | `fp audits resolve FINDING_ID` | Marca un hallazgo como resuelto sin supresión futura. | `--yes`, `-y` | | `fp audits reopen FINDING_ID` | Devuelve un hallazgo a la cola activa y elimina la supresión. | — | -| `fp audits assign FINDING_ID` | Establece el responsable del hallazgo. | `--to ` requerido | +| `fp audits assign FINDING_ID` | Establece el responsable del hallazgo. | `--to ` obligatorio | #### Opciones de creación de auditorías @@ -261,27 +261,27 @@ fp audits create checkout-reliability \ | Opción | Descripción | | --- | --- | -| `--file ` | Basa la definición en JSON o usa `-` para stdin. Los flags explícitos sobrescriben los valores del archivo. | -| `--description ` | Indica la pregunta de fallo o el propósito. | -| `--enabled` / `--disabled` | Inicia la programación activada o desactivada. Predeterminado: habilitada. | -| `--schedule-interval-secs ` | `3600`–`604800`. Predeterminado: `86400`. | -| `--schedule-anchor ` | Fase UTC fija en formato ISO 8601. Predeterminado: próximas 09:00 UTC. | -| `--window-mode since_last\|fixed` | Continúa tras la última ventana completamente analizada o inspecciona repetidamente una ventana deslizante. Predeterminado: `since_last`. | -| `--lookback-window-secs ` | `3600`–`7776000`. Predeterminado: `604800`. | -| `--scope ''` | Filtra por `environments`, `agent_ids` u otros campos de alcance compatibles. | -| `--ignore-error-type ` | Excluye tipos de error; repite o separa con comas. | -| `--llm` / `--no-llm` | Habilita o deshabilita el análisis agéntico. Predeterminado: habilitado. | -| `--top-k ` | Retiene entre `1` y `500` hallazgos. Predeterminado: `50`. | -| `--sensitivity low\|medium\|high` | Establece la sensibilidad de los informes. Predeterminado: `medium`. | +| `--file ` | Basa la definición en JSON, o use `-` para stdin. Los flags explícitos reemplazan los valores del archivo. | +| `--description ` | Describe la pregunta de fallo o el propósito. | +| `--enabled` / `--disabled` | Inicia la programación activada o desactivada. Por defecto: activada. | +| `--schedule-interval-secs ` | `3600`–`604800`. Por defecto: `86400`. | +| `--schedule-anchor ` | Fase UTC fija en formato ISO 8601. Por defecto: próximas 09:00 UTC. | +| `--window-mode since_last\|fixed` | Continúa tras la última ventana completamente analizada o inspecciona repetidamente una ventana deslizante. Por defecto: `since_last`. | +| `--lookback-window-secs ` | `3600`–`7776000`. Por defecto: `604800`. | +| `--scope ''` | Filtra por `environments`, `agent_ids` u otros campos de alcance admitidos. | +| `--ignore-error-type ` | Excluye tipos de error; repita o separe con comas. | +| `--llm` / `--no-llm` | Activa o desactiva el análisis agéntico. Por defecto: activado. | +| `--top-k ` | Retiene entre `1` y `500` hallazgos. Por defecto: `50`. | +| `--sensitivity low\|medium\|high` | Establece la sensibilidad de los informes. Por defecto: `medium`. | | `--channels ''` | Array de canales de notificación. | | `--text ` | Resumen en línea, máximo 8 192 caracteres. | -| `--text-file ` | Lee el resumen desde un archivo; mutuamente exclusivo con `--text`. | -| `--url ` | Añade una referencia HTTPS pública; repite hasta cinco veces. | +| `--text-file ` | Lee el resumen desde un archivo; excluyente con `--text`. | +| `--url ` | Agrega una referencia HTTPS pública; repita hasta cinco veces. | -Incluye el contexto durante la creación cuando la primera ejecución lo necesite. La creación confirma la definición y el contexto juntos antes de que comience la ejecución en cola. +Incluya el contexto durante la creación cuando la primera ejecución lo necesite. La creación confirma la definición y el contexto juntos antes de que comience la ejecución en cola. - `fp audits run` es asíncrono. Sondea `fp audits runs NAME` hasta que la última ejecución tenga éxito o falle antes de leer sus hallazgos. + `fp audits run` es asíncrono. Consulte `fp audits runs NAME` hasta que la última ejecución tenga éxito o falle antes de leer sus hallazgos. ### Incidencias @@ -290,87 +290,87 @@ Incluye el contexto durante la creación cuando la primera ejecución lo necesit | --- | --- | --- | | `fp issues list` | Lista las incidencias. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | | `fp issues count` | Cuenta las incidencias abiertas o en los estados seleccionados. | `--state` | -| `fp issues show INCIDENT_ID` | Muestra los detalles, comentarios, suscriptores y actividad de una incidencia. | — | -| `fp issues open` | Abre una incidencia manual o vinculada a una alerta. | `--summary` requerido; `--title`, `--alert-id`, `--severity` opcionales | -| `fp issues ack INCIDENT_ID` | Reconoce una incidencia. | — | -| `fp issues assign INCIDENT_ID` | Reemplaza los responsables asignados; omite la opción para borrarlos. | `--assignee` repetible | +| `fp issues show INCIDENT_ID` | Muestra los detalles de la incidencia, comentarios, suscriptores y actividad. | — | +| `fp issues open` | Abre una incidencia manual o vinculada a una alerta. | `--summary` obligatorio; `--title`, `--alert-id`, `--severity` opcionales | +| `fp issues ack INCIDENT_ID` | Confirma una incidencia. | — | +| `fp issues assign INCIDENT_ID` | Reemplaza los responsables; omita la opción para eliminarlos. | `--assignee` repetible | | `fp issues resolve INCIDENT_ID` | Resuelve una incidencia. | `--yes`, `-y` | | `fp issues comment-list INCIDENT_ID` | Lista los comentarios. | — | -| `fp issues comment-add INCIDENT_ID` | Añade un comentario. | exactamente uno de `--body`, `--file` | +| `fp issues comment-add INCIDENT_ID` | Agrega un comentario. | exactamente uno de `--body`, `--file` | | `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Elimina un comentario. | `--yes`, `-y` | | `fp issues subscribers INCIDENT_ID` | Lista los suscriptores. | — | -| `fp issues subscribe INCIDENT_ID` | Te suscribe a ti mismo u otro operador. | `--email` | +| `fp issues subscribe INCIDENT_ID` | Suscribe al operador actual u otro operador. | `--email` | | `fp issues unsubscribe INCIDENT_ID` | Elimina una suscripción. | `--email` | -Los estados válidos de una incidencia son `firing`, `acknowledged` y `resolved`. Las gravedades de incidencias independientes son `info`, `warning` y `critical`. +Los estados de incidencia válidos son `firing`, `acknowledged` y `resolved`. Las severidades de incidencias independientes son `info`, `warning` y `critical`. ### Asistente en la nube | Comando | Propósito | Opciones | | --- | --- | --- | -| `fp agent health` | Comprueba la disponibilidad y configuración del asistente. | — | +| `fp agent health` | Verifica la disponibilidad y configuración del asistente. | — | | `fp agent models` | Lista los modelos de asistente disponibles. | — | | `fp agent chats` | Lista los chats guardados. | — | | `fp agent ask [MESSAGE]` | Inicia o continúa un chat; lee stdin cuando se omite el mensaje. | `--chat`; `--model`; `--page-context` | | `fp agent show CHAT_ID` | Muestra una conversación guardada. | — | -| `fp agent rename CHAT_ID` | Renombra una conversación. | `--title` requerido | +| `fp agent rename CHAT_ID` | Renombra una conversación. | `--title` obligatorio | | `fp agent delete CHAT_ID` | Elimina una conversación. | `--yes`, `-y` | ### Políticas -Versiones de políticas administradas en la nube. **Solo para sesión** — todos los comandos aquí salen con código `2` bajo una clave de API, antes de cualquier solicitud, porque estas son rutas de escritura de nivel raíz deliberadamente ausentes de `/v1`. +Versiones de políticas administradas en la nube. **Solo de sesión** — cada comando aquí termina con código `2` bajo una clave de API, antes de cualquier solicitud, porque estas son rutas de escritura solo para root deliberadamente ausentes de `/v1`. | Comando | Propósito | Opciones | | --- | --- | --- | | `fp policies list` | Lista las versiones de políticas. | `--json` | | `fp policies show POLICY_ID` | Muestra una política con su fuente. | — | | `fp policies publish NAME PATH` | Crea una versión a partir de un archivo `.mjs` local. | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | La vuelve a añadir a todos los despliegues de los que fue eliminada, creando una nueva generación en cada uno. | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | La elimina de todos los despliegues que la contienen, creando una nueva generación en cada uno. | `--yes`, `-y` | +| `fp policies enable POLICY_ID` | La vuelve a agregar a cada despliegue del que fue eliminada, creando una nueva generación en cada uno. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | La elimina de cada despliegue que la contiene, creando una nueva generación en cada uno. | `--yes`, `-y` | | `fp policies delete POLICY_ID` | Elimina una versión de política. | `--yes`, `-y` | -| `fp policies test PATH` | Ejecuta una política localmente contra un contexto sintético. Aplica el filtro `match` de cada política, por lo que una que no cubra el evento/herramienta dado se notifica como `skipped` en lugar de ejecutarse. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | +| `fp policies test PATH` | Ejecuta una política localmente contra un contexto sintético. Aplica el filtro `match` de cada política, por lo que una que no cubra el evento/herramienta dado se reporta como `skipped` en lugar de ejecutarse. | `--event`; `--tool`; `--command`; `--file`; `--expect` | | `fp policies compose PROMPT` | Redacta una política con el asistente. Requiere `policies:write`. | — | ### Flota -Qué máquinas ejecutan qué políticas. **Solo para sesión**, por la misma razón que lo anterior. +Qué máquinas ejecutan qué políticas. **Solo de sesión**, por el mismo motivo anterior. | Comando | Propósito | Opciones | | --- | --- | --- | | `fp fleet list` | Lista las máquinas inscritas y su generación de despliegue. | — | | `fp fleet show MACHINE_ID` | El conjunto de políticas que ejecuta actualmente una máquina. | — | -| `fp fleet deploy MACHINE_ID` | **Reemplaza el conjunto completo de políticas de la máquina.** Muestra el plan y solicita confirmación solo en un terminal interactivo sin `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet deploy MACHINE_ID` | **Reemplaza todo el conjunto de políticas de la máquina.** Muestra el plan y solicita confirmación solo en una terminal interactiva sin `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | | `fp fleet diff MACHINE_ID` | Compara una máquina con otro despliegue. | — | | `fp fleet history MACHINE_ID` | Despliegues anteriores de una máquina. | — | -| `fp fleet rollback MACHINE_ID` | Restaura un despliegue anterior. | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | Asigna un nombre legible a una máquina. | `--name` requerido | +| `fp fleet rollback MACHINE_ID GENERATION` | Reinstala el conjunto de políticas de una generación anterior como una nueva generación. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | Asigna un nombre legible a una máquina. | `--name` obligatorio | -### Guardarraíles +### Guardrails -Lo que la aplicación realmente hizo. **Solo para sesión**, por la misma razón que lo anterior. +Lo que la aplicación realmente hizo. **Solo de sesión**, por el mismo motivo anterior. | Comando | Propósito | Opciones | | --- | --- | --- | -| `fp guardrails summary` | Cobertura, totales bloqueados/evaluados, un gráfico de chispas de denegaciones y la tabla por política. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | Decisiones agrupadas en intervalos sobre la ventana, sumadas entre todas las fuentes de políticas. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | Cobertura, totales bloqueados/evaluados, un sparkline de denegaciones y la tabla por política. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Decisiones agrupadas en la ventana temporal, sumadas en todas las fuentes de políticas. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | ## Flags globales | Flag | Descripción | | --- | --- | -| `--json` | Emite JSON legible por máquinas. | -| `--base-url ` | Usa un dashboard autohospedado o de desarrollo. | +| `--json` | Emite JSON legible por máquina. | +| `--base-url ` | Usa un dashboard autoalojado o de desarrollo. | | `--org ` | Selecciona una organización para esta invocación. | -| `--token ` | Sobrescribe el token de sesión de usuario guardado. | +| `--token ` | Reemplaza el token de sesión de usuario guardado. | | `--api-key ` | Autentica la automatización con una clave de API; nunca se guarda. | -| `--timeout ` | Tiempo de espera HTTP; debe ser positivo. Predeterminado: `30`. | +| `--timeout ` | Tiempo de espera HTTP; debe ser positivo. Por defecto: `30`. | | `--quiet`, `-q` | Suprime la salida de estado en stderr. | | `--no-color` | Deshabilita la salida con colores. | | `--insecure` / `--secure` | Deshabilita o restaura la verificación del certificado TLS. | -| `--version` | Imprime la versión instalada y sale. | +| `--version` | Imprime la versión y termina. | | `--help`, `-h` | Muestra la ayuda. | -`--api-key` está pensado para automatización. Los comandos de inicio de sesión, cambio de organización y asistente requieren una sesión de usuario. +`--api-key` está destinado a la automatización. Los comandos de inicio de sesión, cambio de organización y asistente requieren una sesión de usuario. ## Variables de entorno @@ -382,18 +382,18 @@ Lo que la aplicación realmente hizo. **Solo para sesión**, por la misma razón | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | Reubica el directorio de configuración de la CLI (predeterminado: `~/.failproofai/fpcli`). | +| `FP_HOME` | Reubica el directorio de configuración de la CLI (por defecto `~/.failproofai/fpcli`). | | `FP_ANALYTICS_DISABLED` o `DO_NOT_TRACK` | Deshabilita las analíticas anónimas de la CLI. | | `NO_COLOR` | Deshabilita la salida con colores. | -Los flags explícitos sobrescriben las variables de entorno, que a su vez sobrescriben la configuración guardada. En el modo de clave de API, selecciona el tenant explícitamente con `--org` o `FP_ORG`. +Los flags explícitos reemplazan las variables de entorno, que a su vez reemplazan la configuración guardada. En el modo de clave de API, seleccione el tenant explícitamente con `--org` o `FP_ORG`. - Los equivalentes `AGENTEYE_*` de estas variables **no son leídos por `fp`** ni nunca lo fueron — la CLI declara `FP_*` (`fp_cli/app.py`), y una variable desconocida no es un error. Establecer `AGENTEYE_DASHBOARD_URL` no redirige la CLI; se ignora y el comando se ejecuta silenciosamente contra el dashboard guardado. + Las versiones `AGENTEYE_*` de estas variables **no son leídas por `fp`** y nunca lo fueron — la CLI declara `FP_*` (`fp_cli/app.py`), y una variable desconocida no es un error. Establecer `AGENTEYE_DASHBOARD_URL` no redirige la CLI; se ignora y el comando se ejecuta silenciosamente contra el dashboard guardado. - `AGENTEYE_HOME` y `AGENTEYE_ENVIRONMENT` siguen existiendo, pero pertenecen al **colector y al SDK de telemetría**, no a esta CLI. + `AGENTEYE_HOME` y `AGENTEYE_ENVIRONMENT` todavía existen, pero pertenecen al **recolector y al SDK de telemetría**, no a esta CLI. - Los comandos que eliminan, revocan, suprimen, resuelven o reemplazan configuraciones muestran un prompt de confirmación por defecto. Usa `--yes` solo después de verificar la organización activa y el objetivo. + Los comandos que eliminan, revocan, suprimen, resuelven o reemplazan configuración solicitan confirmación por defecto. Use `--yes` solo después de verificar la organización activa y el objetivo. \ No newline at end of file diff --git a/docs/es/reference/custom-agents.mdx b/docs/es/reference/custom-agents.mdx index 88b443a5..5dcdfc58 100644 --- a/docs/es/reference/custom-agents.mdx +++ b/docs/es/reference/custom-agents.mdx @@ -1,14 +1,14 @@ --- title: "Agentes personalizados" -description: "Configuración, el catálogo de eventos, reglas de correlación y entrega para failproofai-sdk." +description: "Configuración, catálogo de eventos, reglas de correlación y entrega para failproofai-sdk." icon: "python" --- -Qué hace cada ajuste, método y campo. Si estás instrumentando por primera vez, comienza con la guía — esta página es para consultas de referencia. +Qué hace cada configuración, método y campo. Si es la primera vez que instrumentas, empieza por la guía — esta página es solo de referencia. - Instalación, instrumentación, los métodos de eventos, un ejemplo práctico y problemas comunes. + Instalación, instrumentación, métodos de evento, un ejemplo completo y problemas frecuentes. LangChain, CrewAI, LlamaIndex y Pydantic AI se instrumentan solos con una sola llamada. @@ -17,13 +17,13 @@ Qué hace cada ajuste, método y campo. Si estás instrumentando por primera vez Python 3.10 o superior. Sin dependencias en tiempo de ejecución. -## Instalación +## Instalar ```bash pip install failproofai-sdk ``` -El paquete se instala como `failproofai-sdk` y se importa en Python como `failproofai_sdk`. Los extras de framework como `failproofai-sdk[langgraph]` instalan el framework en sí; los adaptadores siempre se incluyen en el wheel base. +El paquete se instala como `failproofai-sdk` y se importa en Python como `failproofai_sdk`. Los extras de framework como `failproofai-sdk[langgraph]` instalan el propio framework; los adaptadores siempre vienen incluidos en el wheel base. ## Conectar el daemon de Failproof @@ -31,16 +31,22 @@ El paquete se instala como `failproofai-sdk` y se importa en Python como `failpr 1. Ve a **Admin → Keys** y crea una clave con `events:add`. 2. [Conecta el daemon de Failproof a Cloud](/es/start/setup#connect-a-machine-to-cloud) en la máquina del agente. - 3. Ejecuta una sesión instrumentada y luego encuentra su ID exacto en **Observe → Events**. - 4. Ve a **Observe → Sessions**, selecciona el mismo entorno y abre la traza reconstruida. + 3. Ejecuta una sesión instrumentada y luego busca su ID exacto en **Observe → Events**. + 4. Ve a **Observe → Sessions**, selecciona el mismo entorno y abre el trace reconstruido. ![Una sesión de agente Python personalizado reconstruida como grafo de ejecución y traza de eventos ordenada.](/images/dashboard/session-detail.png) + Lee la clave `events:add` en el shell. `read -s` la solicita en un prompt que no la muestra en pantalla, por lo que nunca aparece en un comando ni en el historial del shell: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Luego configura la máquina y verifica que se haya conectado: + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -60,30 +66,30 @@ failproofai_sdk.configure( | Argumento | Qué hace | | --- | --- | -| `environment` | La etiqueta en cada evento — `production`, `staging`, `prod-eu`. Por defecto es `dev`. | +| `environment` | La etiqueta en cada evento: `production`, `staging`, `prod-eu`. Por defecto es `dev`. | | `flush_interval` | Con qué frecuencia el hilo en segundo plano escribe en disco, en segundos. Por defecto es `0.5`. | -| `base_dir` | Dónde escribir. Por defecto es el spool del daemon, que es lo que quieres a menos que sepas lo contrario. | +| `base_dir` | Dónde escribir. Por defecto usa el spool del daemon, que es lo que necesitas salvo que sepas exactamente lo que haces. | -También se puede configurar mediante variables de entorno: +Configurable también mediante variables de entorno: | Variable | Qué hace | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | Establece `environment` sin cambiar el código, para cuando la etiqueta pertenece al despliegue más que a la aplicación. Un argumento de `configure()` tiene prioridad sobre ella. | +| `AGENTEYE_ENVIRONMENT` | Establece `environment` sin modificar el código, para cuando la etiqueta pertenece al despliegue y no a la aplicación. Un argumento de `configure()` tiene prioridad sobre ella. | | `FAILPROOFAI_HOME` | Mueve la raíz de Failproof AI que contiene el spool. | -| `FAILPROOFAI_SDK_STRICT` | `1` hace que los errores de instrumentación lancen una excepción en lugar de registrarse en el log. | +| `FAILPROOFAI_SDK_STRICT` | `1` hace que los errores de instrumentación lancen una excepción en lugar de registrarse. | | `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` hace que un problema de compatibilidad con el framework lance una excepción en lugar de advertir y continuar. | - **Sin comas en `environment`.** La ingesta divide ese campo por comas para construir sus filtros, y omite cualquier evento cuya etiqueta contenga una — así una ejecución entera desaparece silenciosamente. Escribe `prod-eu`, no `prod,eu`. + **Sin comas en `environment`.** La ingesta divide ese campo por comas para construir sus filtros y descarta cualquier evento cuya etiqueta contenga una, por lo que una ejecución entera desaparece silenciosamente. Escribe `prod-eu`, no `prod,eu`. - `configure(environment="prod,eu")` lanza una excepción para que lo detectes de inmediato. `AGENTEYE_ENVIRONMENT` no puede lanzar excepciones — nadie te está llamando — por lo que advierte una vez y recurre a `dev`. + `configure(environment="prod,eu")` lanza una excepción para que te enteres de inmediato. `AGENTEYE_ENVIRONMENT` no puede lanzar excepciones — nadie te está llamando — así que advierte una vez y vuelve a `dev`. -Los eventos se encolan en memoria y se escriben en segundo plano cada `flush_interval` segundos, con un flush final al salir del intérprete. Un proceso que se mata bruscamente pierde lo que aún no se había escrito. +Los eventos se encolan en memoria y se escriben en segundo plano cada `flush_interval` segundos, con un flush final al salir del intérprete. Un proceso que se cierra abruptamente pierde todo lo que no se había escrito todavía. ## Identidad -Cada evento pertenece a una sesión y a un agente. **Los scopes rellenan ambos**, por lo que rara vez necesitas pasarlos: +Cada evento pertenece a una sesión y a un agente. **Los scopes rellenan ambos automáticamente**, así que raramente necesitas pasarlos: ```python with failproofai_sdk.session(): @@ -94,12 +100,12 @@ with failproofai_sdk.session(): Pasar `session_id` o `agent_id` explícitamente sigue funcionando y tiene prioridad. Si no hay ninguno vinculado ni pasado, la llamada lanza `TypeError` en lugar de emitir un evento que Cloud descartaría silenciosamente. - La identidad viaja en variables de contexto. Sigue las tareas de `asyncio` automáticamente, pero **no** los nuevos hilos — envuelve un worker con `failproofai_sdk.propagate()` o sus eventos quedarán sin adjuntar. + La identidad viaja en variables de contexto. Sigue las tareas de `asyncio` automáticamente, pero **no** los hilos nuevos — envuelve un worker con `failproofai_sdk.propagate()` o sus eventos quedarán sin asociar. ## Catálogo de eventos -Quince métodos. La mayoría vienen en **pares** — llamas al abridor y luego al cierre, y el SDK mide el tiempo entre ambos. +Quince métodos. La mayoría vienen en **pares** — llamas al de apertura, luego al de cierre, y el SDK mide el tiempo entre ambos. | | Abre | Cierra | | --- | --- | --- | @@ -114,9 +120,9 @@ Tres son independientes: `error`, `human_pause`, `human_interrupt`. -Cada método también acepta `session_id` y `agent_id`, que los scopes rellenan por ti. Cualquier campo que quede como `None` se descarta en lugar de enviarse como JSON `null`, y cada método devuelve `None`. +Cada método también acepta `session_id` y `agent_id`, que los scopes rellenan por ti. Todo lo que quede como `None` se omite en lugar de enviarse como JSON `null`, y todos los métodos devuelven `None`. -| Método | Requerido | Opcional | +| Método | Obligatorio | Opcional | | --- | --- | --- | | `agent_start` | — | `goal`, `parent_id` | | `agent_end` | — | `outcome`, `summary` | @@ -137,14 +143,14 @@ Cada método también acepta `session_id` y `agent_id`, que los scopes rellenan - Para marcar una ejecución como fallida, `outcome` debe ser uno de `failed`, `error`, `timeout` o `rejected`. Cualquier otro valor — incluido el parecido `"failure"` — se cuenta como éxito. + Para marcar una ejecución como fallida, `outcome` debe ser uno de: `failed`, `error`, `timeout` o `rejected`. Cualquier otro valor — incluido el parecido `"failure"` — se cuenta como éxito. ## Emparejamiento y duración -**Una regla: dale al evento de cierre el mismo id que al de apertura.** Eso es lo que los empareja y lo que permite al SDK medir el tiempo transcurrido. +**Una sola regla: dale al evento de cierre el mismo ID que al de apertura.** Eso es lo que los empareja y lo que permite al SDK medir el tiempo transcurrido. -| Par | Emparejado por | +| Par | Se empareja por | | --- | --- | | `tool_use` → `tool_result` | `tool_call_id` | | `hook_triggered` → `hook_completed` | `hook_id` | @@ -152,37 +158,37 @@ Cada método también acepta `session_id` y `agent_id`, que los scopes rellenan | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**No pases `duration_ms` tú mismo.** El SDK lo mide, y pasarlo lanza un `ValueError`. +**No pases `duration_ms` tú mismo.** El SDK lo mide, y pasarlo lanza `ValueError`. -La única excepción es `model_response`, donde solo tú conoces la latencia real del proveedor. Pasa un número entero de milisegundos — un float lanza una excepción, porque la columna es un entero de 32 bits y de lo contrario quedaría vacía. +La única excepción es `model_response`, donde solo tú conoces la latencia real del proveedor. Pasa un número entero de milisegundos — un float lanza una excepción, porque la columna es un entero de 32 bits y de otro modo quedaría vacía. -- **Los ids solo necesitan ser únicos por tipo y por sesión.** Una llamada a herramienta y un hook pueden compartir el mismo id; dos sesiones que se ejecuten a la vez pueden reutilizar los mismos ids sin colisionar. -- **No están limitados al ámbito de un agente.** Un par abierto bajo un agente y cerrado bajo otro sigue emparejándose — que es el caso habitual en código multiagente. -- **`request_id` es opcional pero recomendado.** Sin él, los eventos de modelo se emparejan en el orden en que llegan, por lo que dos llamadas concurrentes en el mismo agente pueden emparejarse incorrectamente. -- **Un par dividido entre procesos** sigue emparejándose en Cloud, pero el SDK no puede cronometrarlo — ninguno de los dos procesos vio ambas mitades. -- **Como máximo 10.000 aperturas pueden esperar un cierre a la vez.** Pasado ese límite se descarta la más antigua, de modo que una fuga no puede crecer sin límite. +- **Los IDs solo necesitan ser únicos por tipo y por sesión.** Una llamada a una herramienta y un hook pueden compartir el mismo ID; dos sesiones que se ejecuten a la vez pueden reutilizar los mismos IDs sin colisionar. +- **No están vinculados a un agente.** Un par abierto bajo un agente y cerrado bajo otro sigue emparejándose, que es el caso habitual en código multi-agente. +- **`request_id` es opcional pero recomendable.** Sin él, los eventos de modelo se emparejan en el orden en que llegan, por lo que dos llamadas concurrentes en el mismo agente pueden emparejarse incorrectamente. +- **Un par dividido entre procesos** sigue emparejándose en Cloud, pero el SDK no puede medirlo — ningún proceso vio ambas mitades. +- **Como máximo 10 000 aperturas pueden esperar un cierre a la vez.** A partir de ahí, se descarta la más antigua, de modo que una fuga no puede crecer sin límite. ## Tus propios campos -Cualquier palabra clave adicional que pases se almacena junto al evento: +Cualquier argumento adicional que pases se almacena junto al evento: ```python failproofai_sdk.event.tool_use( tool_name="search", tool_call_id="c1", - fw_tenant="acme", fw_region="eu-west-1", # tus propios campos + fw_tenant="acme", fw_region="eu-west-1", # los tuyos propios ) ``` -Prefiere tipos JSON si quieres consultarlos más adelante. Cualquier otra cosa — un UUID, un datetime, un `Decimal`, un set, bytes, un objeto de modelo — se almacena como cadena de texto. +Usa tipos JSON si quieres consultarlos después. Cualquier otro tipo — un UUID, un datetime, un `Decimal`, un set, bytes, un objeto de modelo — se almacena como cadena de texto. - **Usa un prefijo en los nombres de tus campos.** Los extras se aplican al final, por lo que un campo llamado `model`, `tool_name` o `outcome` sobreescribirá silenciosamente el valor real. Los adaptadores de framework usan `fw_`; haz lo mismo y nada podrá colisionar. + **Usa un prefijo en los nombres de tus campos.** Los extras se aplican al final, por lo que un campo llamado `model`, `tool_name` o `outcome` sobreescribirá silenciosamente el real. Los adaptadores de framework usan `fw_`; haz lo mismo y nada podrá colisionar. - Esta es también la razón por la que un campo opcional mal escrito nunca genera un error — simplemente se convierte en un nuevo campo personalizado. Si falta un campo estándar en Cloud, revisa primero la ortografía. + También es por eso que un campo opcional mal escrito nunca produce un error — simplemente se convierte en un nuevo campo personalizado. Si falta un campo estándar en Cloud, comprueba primero la ortografía. Estos cinco nombres están reservados y se rechazan directamente: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. @@ -191,7 +197,7 @@ Estos cinco nombres están reservados y se rechazan directamente: `timestamp`, ` - En **Observe → Events**, verifica que `agent_start` existe primero y `agent_end` existe al final. Luego abre **Observe → Sessions** y confirma que los eventos de modelo, herramienta, humanos, hooks y errores aparecen en el orden previsto. Usa el ID de sesión como clave principal para la resolución de problemas. + En **Observe → Events**, verifica que `agent_start` existe primero y `agent_end` existe al final. Luego abre **Observe → Sessions** y confirma que los eventos de modelo, herramienta, humano, hook y error aparecen en el orden esperado. Usa el ID de sesión como clave principal para depurar. ```bash @@ -203,14 +209,14 @@ Estos cinco nombres están reservados y se rechazan directamente: `timestamp`, ` -Si Cloud está vacío, inspecciona `$FAILPROOFAI_HOME/custom-agents/events`, o en su defecto `~/.failproofai/custom-agents/events`. Los archivos JSONL prueban la emisión del SDK; un spool en crecimiento apunta a la configuración del daemon o a la entrega, mientras que un spool vacío apunta a la instrumentación o al ciclo de vida del proceso. +Si Cloud está vacío, inspecciona `$FAILPROOFAI_HOME/custom-agents/events`; de lo contrario, `~/.failproofai/custom-agents/events`. Los archivos JSONL confirman la emisión por parte del SDK; un spool que crece apunta a un problema de configuración o entrega del daemon, mientras que un spool vacío apunta a la instrumentación o al ciclo de vida del proceso. - Inspecciona el spool solo cuando el daemon esté detenido. Mientras está en ejecución, recopila y elimina cada lote en milisegundos, por lo que un listado del directorio compite con el colector y mostrará muchos menos eventos de los que se emitieron. + Inspecciona el spool solo cuando el daemon esté detenido. Mientras está en ejecución, recoge y elimina cada lote en milisegundos, por lo que un listado del directorio compite con el colector y mostrará muchos menos eventos de los que realmente se emitieron. ## Prevenir fallos en un runtime personalizado -Usa los hallazgos de auditoría y las trazas vinculadas para definir la acción no segura, la evidencia requerida y la respuesta prevista. Una integración de aplicación de políticas personalizada debe exponer la acción antes de su ejecución, pasar su entrada estructurada al motor de políticas y aplicar la decisión resultante de allow, instruct o deny. +Usa los hallazgos de auditoría y las trazas enlazadas para definir la acción insegura, la evidencia requerida y la respuesta prevista. Una integración de aplicación de políticas personalizada debe exponer la acción antes de ejecutarla, pasar su entrada estructurada al motor de políticas y aplicar la decisión resultante: allow, instruct o deny. -[Contacta con Failproof AI](mailto:support@befailproof.ai) y te ayudaremos a mapear los límites de modelo, herramienta y ciclo de vida de tu runtime a los hooks de política, y luego validaremos la integración contigo. \ No newline at end of file +[Contacta con Failproof AI](mailto:support@befailproof.ai) y te ayudaremos a mapear los límites de modelo, herramienta y ciclo de vida de tu runtime a hooks de política, y luego validaremos la integración contigo. \ No newline at end of file diff --git a/docs/es/reference/evaluator-sdk.mdx b/docs/es/reference/evaluator-sdk.mdx index d7667187..81380819 100644 --- a/docs/es/reference/evaluator-sdk.mdx +++ b/docs/es/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- -title: "SDK de evaluador" -description: "Construye un servicio que puntúe sesiones de Failproof AI de forma síncrona o asíncrona." +title: "SDK de Evaluación" +description: "Ejecuta tu propio worker de evaluación para jueces LLM y todo lo que Python alojado no puede hacer." icon: "gauge" --- -Un evaluador recibe una sesión de agente completada y devuelve las señales de calidad que te interesan: puntuaciones numéricas, una explicación para cada puntuación y un resumen opcional. Failproof AI almacena estos resultados junto al rastreo y los representa gráficamente a través de agentes y entornos. +El SDK de Evaluación ejecuta evaluaciones en tu propia infraestructura. Tu worker registra sus evaluaciones en Failproof AI, reclama sesiones a medida que finalizan, las puntúa y envía los resultados, todo mediante HTTPS saliente: nada se conecta hacia él. Úsalo para lo que [Python alojado](/es/evaluations/write) no puede hacer: jueces LLM, llamadas a modelos, paquetes, secretos y acceso a red. Sus resultados aparecen junto a los alojados en la [página de evaluaciones](/es/sessions/evaluations), etiquetados como **customer**. -## Configurar un evaluador +Se incluye en `failproofai-sdk`, bajo `failproofai_sdk.evaluator`; importar el SDK de trazado no lo carga. - - - Instala el SDK y el servidor necesario para ejecutarlo. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - Crea `evaluator.py`. Este ejemplo comprueba si una sesión contiene llamadas a herramientas fallidas. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - Establece un token compartido, inicia el evaluador y confirma que el endpoint de salud responde. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - En otra terminal: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## Conectar el evaluador a Failproof AI +```bash +pip install failproofai-sdk +``` -1. Despliega el evaluador en una URL HTTPS accesible por Failproof AI Cloud. -2. Configura `EVALUATOR_ENDPOINT` con esa URL y establece `EVALUATOR_TOKEN` con el mismo token utilizado por el evaluador. Para Cloud gestionado, contacta con [support@befailproof.ai](mailto:support@befailproof.ai) para configurar la conexión. -3. Ejecuta una evaluación y confirma que las puntuaciones aparecen en Failproof AI. +## Escribe evaluaciones - - - Abre una sesión completada en **Observar → Sesiones** y selecciona **Ejecutar evaluación** si no se evaluó automáticamente. Revisa el estado, las puntuaciones, el razonamiento y el resumen en el panel de **Evaluación** de la sesión. +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - Usa **Observar → Evaluaciones** para comparar puntuaciones entre agentes o entornos. Usa **Observar → Métricas** para latencia, coste, tokens y otras mediciones numéricas. - Comienza con una sesión para confirmar que el evaluador devolvió las claves de puntuación esperadas y un razonamiento útil para esa ejecución específica. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![Vista detallada de una sesión mostrando puntuaciones de evaluación y razonamiento junto a su rastreo.](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` registra una evaluación. La clave es el nombre bajo el que aparecen sus resultados; cambia la versión cada vez que cambie la lógica, y cada resultado conserva la versión que lo generó. Un worker puede contener hasta 100 evaluaciones. +- `result_kind` es `"score"` salvo que se indique lo contrario. Para una evaluación de tipo `"metric"` o `"assertion"`, nombra una entrada de `metrics` o `assertions` con la misma clave: esa entrada es su resultado. +- `when` determina si una sesión aplica. Devuelve `ConditionResult(False, "")` para omitirla, y el motivo queda registrado. +- Una evaluación puede ser una función normal o `async`, y `timeout_seconds` la acota en el tiempo. +- Las claves de payload — `tool_name`, `response` y `content` en el ejemplo — son las que envíen tus agentes, así que léelas de una sesión real. - Una vez que los resultados individuales se vean correctos, usa el panel de evaluación para comparar esas puntuaciones a lo largo del tiempo y entre agentes o entornos. +## Ejecuta el worker - ![Panel de calidad con gráficas de puntuaciones del evaluador a lo largo del tiempo.](/images/dashboard/dashboard-quality.png) +Coloca una clave con el permiso `evaluations:run`, creada en **Administration → Keys**, en `FAILPROOFAI_EVALUATOR_TOKEN` — establécela desde tu almacén de secretos en lugar de escribirla directamente en un comando — y arranca el worker: - Un gráfico saludable debe usar nombres de puntuación estables; cambiar una clave crea una serie separada. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -Para una instancia de Cloud auto-alojada, la evaluación automática está deshabilitada hasta que se establezca `EVALUATOR_ENDPOINT` en el proceso del servidor. Reinicia el servidor después de cambiar las variables de entorno del evaluador. +Sin el bloque `__main__`, `python -m failproofai_sdk.evaluator evaluator:app` hace lo mismo. -El servicio expone `GET /health`, `GET /config`, `POST /evaluate` y opcionalmente `GET /evaluate/{job_id}`. Devuelve `JobPending` para trabajo asíncrono y registra `@app.job_lookup` para que Failproof AI pueda consultarlo periódicamente. +| Variable | Valor por defecto | Propósito | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | requerida | Dirección de Failproof AI: `https://app.befailproof.ai` para Cloud. HTTPS salvo que apunte a loopback | +| `FAILPROOFAI_EVALUATOR_TOKEN` | requerida | Una clave con `evaluations:run` | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | Nombre de este worker | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | Sesiones que este worker puntúa simultáneamente | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Tiempo de espera para cada solicitud a Failproof AI | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | Tiempo que espera un worker al detenerse para que finalicen las ejecuciones en curso | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | Permite HTTP plano a una URL que no sea loopback — ver la advertencia a continuación | +| `FAILPROOFAI_EVALUATOR_MODULE` | ninguno | El `module:attribute` para `python -m failproofai_sdk.evaluator` | -Cuando se configura un token, todas las rutas excepto health requieren el mismo token bearer que Failproof AI envía como `EVALUATOR_TOKEN`. + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` envía todo en texto claro. El worker transmite `FAILPROOFAI_EVALUATOR_TOKEN` como cabecera `Authorization: Bearer` en cada solicitud, y las transcripciones que obtiene son las sesiones en sí — por lo que cualquiera en la ruta puede leer ambas cosas, y el token que lean permitirá ejecutar evaluaciones hasta que lo rotes. Úsalo únicamente en una red de desarrollo aislada. En cualquier otro entorno, la URL debe ser HTTPS; loopback no requiere ningún indicador. + -## Tipos del SDK +## Tipos de resultado | Tipo | Campos | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## Decoradores y rutas - -| Decorador | Ruta | Requerido | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | Sí | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | Al devolver `JobPending` | -| `@app.config` | `GET /config` | No | - -El SDK limita los cuerpos de las solicitudes de evaluación a 25 MiB. Los campos desconocidos en las solicitudes se ignoran para que los servicios permanezcan compatibles a medida que crece el contrato de eventos. +| `Score` | `value` (de 0 a 1), `passed`, `unit` (por defecto `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -## Devolver trabajo asíncrono +Un `EvalResult` contiene al menos una puntuación, métrica o aserción, y como máximo 25, cada una bajo una clave única. -Usa `JobPending` cuando la evaluación no pueda completarse dentro de una sola solicitud. El ID del trabajo es opaco para Failproof AI y debe permanecer resoluble por tu servicio hasta que el resultado sea recogido o expire el tiempo de espera del servidor. +## La sesión -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| Campo o método | Te proporciona | +| --- | --- | +| `session_id`, `agent_id`, `environment` | La identidad de la sesión | +| `started_at`, `ended_at` | Cuándo comenzó y cuándo terminó | +| `event_count`, `events` | La transcripción completa y ordenada | +| `count(event_type)` | Cuántos eventos de ese tipo contiene | +| `events_of_type(event_type)` | Esos eventos, en orden | -La cadencia de sondeo se selecciona en este orden: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs` y luego el `EVALUATOR_POLLING_INTERVAL_SECS` del servidor. Los valores se limitan entre 1 segundo y 1 hora. El límite de sondeo en tiempo real predeterminado del servidor es de una hora. +Cada evento contiene `id`, `ts`, `event_type` y `payload`. -## Campos de solicitud y respuesta +## El evaluador heredado -| Campo | Tipo | Notas | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | Actualmente `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | Identidad de la sesión y entorno. | -| `started_at` | `datetime` | Marca de tiempo del primer evento. | -| `ended_at` | `datetime \| None` | Presente cuando la sesión emitió un evento de finalización. | -| `events` | `list[AgentEvent]` | Flujo de eventos completo y ordenado. | -| `AgentEvent.id` | `int` | Identificador de fila del evento en el backend. | -| `AgentEvent.ts` | `datetime` | Marca de tiempo del evento. | -| `AgentEvent.event_type` | `str` | Familia del evento, como `tool_use`. | -| `AgentEvent.payload` | `dict[str, Any]` | Payload completo del evento. | -| `EvalResponse.scores` | `dict[str, float] \| None` | Dimensiones numéricas representadas en evaluaciones. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | Explicaciones por puntuación; las claves deben reflejar `scores`. | -| `EvalResponse.summary` | `str \| None` | Narrativa general de la evaluación. | - -## Configuración para operadores del servidor - -La evaluación automática aplica a todo el despliegue y permanece deshabilitada cuando `EVALUATOR_ENDPOINT` está ausente. - -| Variable | Valor predeterminado | Propósito | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | no configurado | URL base del servicio evaluador. | -| `EVALUATOR_TOKEN` | no configurado | Token bearer compartido con `Evaluator(token=...)`. | -| `EVALUATOR_WORKERS` | `2` | Trabajadores del despachador concurrentes. | -| `EVALUATOR_CLAIM_BATCH` | `4` | Sesiones reclamadas por pasada del despachador. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Cadencia de sondeo asíncrono de reserva. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Tiempo de espera del evaluador por solicitud. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | Intentos de entrega antes de fallo terminal. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | Cadencia de actualización para `/config`. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Tiempo máximo de sondeo asíncrono en tiempo real. | - -El servidor también puede restringir qué organizaciones utilizan el evaluador global del despliegue. Trata los cambios en el endpoint, token, reintentos y restricciones de organización como configuración del operador y reinicia o renueva el servidor tras modificarlos. - -## Seguridad y operaciones - -- Pon el evaluador detrás de HTTPS cuando el tráfico cruce un límite de red de confianza. -- Configura un token bearer no vacío y mantenlo idéntico en ambos servicios. -- No registres el token ni los prompts sensibles completos de los payloads de las solicitudes. -- Haz que los manejadores síncronos sean idempotentes; los reintentos pueden repetir una solicitud. -- Persiste el estado de los trabajos asíncronos fuera de la memoria del proceso en producción. -- Devuelve claves de puntuación estables. Renombrar una clave crea una nueva serie en el gráfico en lugar de modificar la anterior. - -El SDK emite registros de ciclo de vida estructurados como `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` y excepciones de manejadores. No configura manejadores de registro; utiliza la configuración de registro de la aplicación anfitriona. \ No newline at end of file +El SDK de Evaluación anterior — un servicio HTTP al que Failproof AI llamaba en `EVALUATOR_ENDPOINT`, que respondía en `/evaluate` y se sondeaba mediante `JobPending` — ha sido retirado. Crea nuevos evaluadores con este worker; los operadores de una instancia autohospedada que ejecute un servicio heredado pueden mantenerlo durante la transición. \ No newline at end of file diff --git a/docs/es/reference/failproof-cli.mdx b/docs/es/reference/failproof-cli.mdx index 7885f102..670afbac 100644 --- a/docs/es/reference/failproof-cli.mdx +++ b/docs/es/reference/failproof-cli.mdx @@ -1,88 +1,106 @@ --- title: "Failproof AI CLI" -description: "Instala hooks, gestiona políticas locales, conecta Cloud y opera el daemon local." +description: "Instala hooks, gestiona políticas locales, conecta con Cloud y opera el daemon local." icon: "terminal" --- Instala el CLI local con `npm install -g failproofai`. Ejecútalo sin argumentos para abrir el panel de políticas local. -El paquete requiere Node.js 20.9 o superior. Bun 1.3 o superior es compatible para desarrollo e instalaciones desde código fuente. `failproofai configure` y `failproofai setup` son alias de `failproofai config`; `failproofai p` es un alias de `failproofai policies`. +El paquete requiere Node.js 20.9 o superior. Bun 1.3 o superior es compatible para desarrollo e instalaciones desde fuente. `failproofai configure` y `failproofai setup` son alias de `failproofai config`. `failproofai policy`, `failproofai pack` y `failproofai p` son todas las formas de escribir `failproofai policies` — los packs y las políticas individuales eran tres comandos para una misma idea y ahora son uno solo. Las formas antiguas siguen funcionando, con dos excepciones: `pack list ` ahora es `policies show `, y `pack build` ahora es `publish`. ## Configurar una máquina +Instala el CLI y luego lee la clave de máquina en el shell. `read -s` la solicita en un prompt que no hace eco, de modo que nunca aparece en un comando: + ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +Luego configura la máquina y elige qué debe aplicar: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` +`failproofai config` es todo el proceso de configuración: instala el servicio `failproofaid` (una vez como root, mediante `sudo -n` — nunca solicita contraseña de forma interactiva), conecta los hooks en cada CLI de agente que encuentra, y se conecta a Cloud cuando hay una clave disponible. Sin terminal — CI, un contenedor, un agente que lo gestiona — aplica en lugar de preguntar, y sale con código 1 si algo que se le pidió hacer no ocurrió. + +Elige **ninguna** política. Esa es la tarea del segundo comando; sin él, una máquina recién configurada no aplica nada salvo el guardián que siempre está activo. + +Prefiere la variable de entorno frente a `--token`: un argumento de línea de comandos es legible desde `ps` por cualquier usuario de la máquina. Eso es lo único que protege la variable — una clave tecleada en cualquier comando, incluido `export`, sigue quedando en el historial del shell, por eso se lee con `read -s` arriba. En CI, configúrala desde el almacén de secretos y mantén el rastreo del shell (`set -x`) desactivado, o el rastreo la imprimirá. + + + `--connect ` inscribe una máquina que **ya está configurada**. Retorna en cuanto la inscripción tiene éxito — no instala el daemon ni conecta ningún hook. Usa `failproofai config` (o `failproofai config --token `) en una máquina que aún no se ha configurado; de lo contrario, aparecerá como conectada sin recopilar ni aplicar nada. + + Ejecuta `failproofai` sin argumentos para abrir el panel de políticas local. | Comando | Resultado | | --- | --- | -| `failproofai config` | Ejecutar la configuración interactiva de la máquina | -| `failproofai config --connect --token ` | Conectar la ingesta Cloud y la entrega de políticas | -| `failproofai config --status` | Mostrar el estado de la conexión, el daemon, la entrega y la pausa | -| `failproofai policies` | Listar políticas integradas, personalizadas, de convención, de paquete y gestionadas por Cloud | -| `failproofai policies --install` | Instalar hooks y habilitar políticas | -| `failproofai policy add ` | Habilitar una política: una integrada o `:` de un paquete instalado | -| `failproofai policy remove ` | Deshabilitar una política, con la misma nomenclatura | -| `failproofai policies --uninstall` | Deshabilitar políticas o eliminar los hooks del harness | -| `failproofai pack list` | Listar los paquetes de políticas instalados y todas las políticas que contienen | -| `failproofai pack add ` | Instalar un paquete de políticas desde una release de GitHub; sin etiqueta toma la más reciente y la fija | -| `failproofai pack add --bundled` | Instalar las políticas integradas como paquete, desde este package, sin red | -| `failproofai pack build ` | Construir los tres activos de release para un paquete propio | -| `failproofai pack remove ` | Desactivar un paquete instalado | -| `failproofai audit` | Analizar el historial local del agente y abrir la vista de auditoría local | -| `failproofai audit --schedule [days] --email
` | Programar análisis locales periódicos y enviar sus resultados por correo | -| `failproofai audit --status` | Mostrar la dirección del informe, el intervalo y el próximo análisis programado | -| `failproofai audit --no-schedule` | Detener los análisis periódicos sin eliminar el historial de auditoría | -| `failproofai harness list` | Listar rutas de captura adicionales | -| `failproofai flush --wait` | Entregar el spool de eventos actual | -| `failproofai backfill --since 30d` | Releer el historial previamente procesado | -| `failproofai config --pause [duration]` | Pausar una sesión local durante 30 minutos por defecto, hasta 8 horas | -| `failproofai config --resume` | Reanudar una sesión local pausada; añade `--all` para eliminar todas las pausas | -| `failproofai update` | Completar las migraciones del paquete y actualizar el daemon | -| `failproofai migrate --dry-run` | Previsualizar o ejecutar migraciones pendientes del layout del home | -| `failproofai uninstall` | Eliminar los hooks y el daemon antes de desinstalar el paquete | -| `failproofai --version` | Mostrar la versión del paquete instalado | -| `failproofai --help` | Mostrar los comandos y el uso global | - -## Opciones de configuración - -| Opción | Uso | +| `failproofai config` | Configura la máquina: agentes, daemon y Cloud cuando hay una clave presente | +| `failproofai config --token ` | Configura y conecta en un solo paso, sin preguntar nada | +| `failproofai config --connect ` | Inscribe una máquina que **ya está** configurada — sin daemon, sin hooks | +| `failproofai config --status` | Muestra el estado de conexión, daemon, entrega y pausa | +| `failproofai policies` | Lista las políticas integradas, personalizadas, de convención, de pack y gestionadas por Cloud | +| `failproofai policies --install` | Conecta hooks en los CLIs de tus agentes. Por sí solo no habilita ninguna política | +| `failproofai policies add ` | Habilita una política — una integrada, o `:` de un pack instalado | +| `failproofai policies remove ` | Deshabilita una política, con la misma nomenclatura | +| `failproofai policies --uninstall` | Deshabilita políticas o elimina los hooks del harness | +| `failproofai policies show /` | Lo que contiene un pack, leído de su manifiesto, antes de instalarlo | +| `failproofai policies show / --releases` | Cada versión publicada y cuál está instalada | +| `failproofai policies add ` | Instala un pack de políticas desde una release de GitHub; sin etiqueta toma la más reciente y la fija | +| `failproofai publish` | Publica tus propias políticas como un pack; `--init` genera uno inicial | +| `failproofai policies remove ` | Desinstala un pack | +| `failproofai audit` | Escanea el historial local de agentes y abre la vista de auditoría local | +| `failproofai audit --schedule [days] --email
` | Programa escaneos locales periódicos y envía sus resultados por correo | +| `failproofai audit --status` | Muestra la dirección de informe, el intervalo y el próximo escaneo programado | +| `failproofai audit --no-schedule` | Detiene los escaneos periódicos sin eliminar el historial de auditoría | +| `failproofai harness list` | Lista rutas de captura adicionales | +| `failproofai flush --wait` | Entrega la cola de eventos actual | +| `failproofai backfill --since 30d` | Relee el historial previamente procesado | +| `failproofai config --pause [duration]` | Pausa una sesión local durante 30 minutos por defecto, hasta 8 horas | +| `failproofai config --resume` | Reanuda una sesión local pausada; añade `--all` para limpiar todas las pausas | +| `failproofai update` | Completa las migraciones de paquetes y actualiza el daemon | +| `failproofai migrate --dry-run` | Previsualiza o ejecuta las migraciones de diseño del directorio home pendientes | +| `failproofai uninstall` | Elimina los hooks y el daemon antes de desinstalar el paquete | +| `failproofai --version` | Imprime la versión del paquete instalado | +| `failproofai --help` | Muestra los comandos y el uso global | + +## Flags de configuración + +| Flag | Uso | | --- | --- | -| `--connect --token ` | Conectar de forma no interactiva | -| `--machine-id ` | Establecer el ID estable de la máquina | -| `--machine-label ` | Establecer o cambiar la etiqueta del panel | -| `--no-transcripts` | Enviar decisiones sin el contenido de la transcripción | -| `--disconnect` | Detener las extracciones de políticas Cloud y la entrega de eventos | -| `--status` | Mostrar el estado actual de la máquina | -| `--pause [duration]` | Pausar la sesión más reciente en el directorio actual; acepta segundos, minutos u horas y por defecto son 30 minutos | -| `--resume` | Terminar una pausa coincidente antes de tiempo | -| `--session ` | Apuntar a una sesión específica para pausar o reanudar | -| `--all` | Con `--resume`, terminar todas las pausas activas | - -Las pausas locales suspenden las políticas integradas, personalizadas, de convención y de paquete para una sesión. Siempre expiran y no deshabilitan las políticas gestionadas por Cloud. `block-failproofai-commands` — que siempre está activo y no puede deshabilitarse ni pausarse — impide que un agente instrumentado utilice esta vía de escape por sí mismo. - -## Opciones de políticas - -| Opción | Uso | +| `--token ` | Configura y conecta de forma no interactiva; también se lee desde `FAILPROOFAI_CLOUD_TOKEN` | +| `--url ` | Conecta a un destino distinto de `app.befailproof.ai`; también se lee desde `FAILPROOFAI_CLOUD_URL` | +| `--connect ` | Solo inscribe, en una máquina ya configurada. Omite el daemon y todos los hooks | +| `--machine-id ` | Establece el ID estable de la máquina | +| `--machine-label ` | Renombra una máquina que **ya está conectada**. Por sí solo nunca ejecuta la configuración, así que úsalo después de `failproofai config`, no durante | +| `--no-transcripts` | Envía decisiones sin el contenido de la transcripción | +| `--disconnect` | Detiene la descarga de políticas de Cloud y la entrega de eventos | +| `--status` | Muestra el estado actual de la máquina | +| `--pause [duration]` | Pausa la sesión más reciente en el directorio actual; acepta segundos, minutos u horas y tiene como valor predeterminado 30 minutos | +| `--resume` | Termina anticipadamente una pausa coincidente | +| `--session ` | Apunta a una sesión específica para pausar o reanudar | +| `--all` | Con `--resume`, termina todas las pausas activas | + +Las pausas locales suspenden las políticas integradas, personalizadas, de convención y de pack para una sesión. Siempre expiran y no deshabilitan las políticas gestionadas por Cloud. `block-failproofai-commands` — que siempre está activo y no puede deshabilitarse ni pausarse — impide que un agente instrumentado use esta vía de escape por sí mismo. + +## Flags de política + +| Flag | Uso | | --- | --- | -| `--install`, `-i` | Habilitar políticas e instalar los hooks del harness | -| `--uninstall`, `-u` | Deshabilitar políticas o eliminar hooks | -| `--cli ` | Apuntar a uno o más harnesses compatibles | -| `--scope user\|project\|local\|all` | Elegir el ámbito de configuración; `all` es para desinstalar | -| `--beta` | Incluir políticas beta | -| `--custom`, `-c ` | Validar y cargar un archivo de política personalizado; repetible | +| `--install`, `-i` | Instala los hooks del harness. Los nombres que le siguen habilitan esas políticas; sin ninguno, no hay cambios de política | +| `--uninstall`, `-u` | Deshabilita políticas o elimina hooks | +| `--cli ` | Apunta a uno o más harnesses compatibles | +| `--scope user\|project\|local\|all` | Elige el alcance de configuración; `all` es para desinstalar | +| `--beta` | Incluye políticas beta | +| `--custom`, `-c ` | Valida y carga un archivo de política personalizado; se puede repetir | -## Opciones de entrega y mantenimiento +## Flags de entrega y mantenimiento -| Comando | Opciones | +| Comando | Flags | | --- | --- | | `backfill` | `--since <30d\|6m\|YYYY-MM-DD>`, `--dry-run` | | `flush` | `--wait`, `--timeout ` | @@ -90,7 +108,7 @@ Las pausas locales suspenden las políticas integradas, personalizadas, de conve | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` debe ejecutarse después de `npm install -g failproofai@latest`; realiza las migraciones del layout del home, instala el binario del daemon correspondiente y reinicia el servicio. `--no-daemon` realiza únicamente la migración del layout. +`failproofai update` debe ejecutarse después de `npm install -g failproofai@latest`; realiza las migraciones del diseño del directorio home, instala el binario del daemon correspondiente y reinicia el servicio. `--no-daemon` realiza únicamente la migración del diseño. ## Rutas del harness @@ -102,9 +120,9 @@ failproofai harness remove-path Los nombres de harness compatibles son `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` y `goose`. -Las etiquetas dan espacio de nombres a los IDs de agente derivados cuando dos raíces contienen copias del mismo proyecto. Las raíces superpuestas y las etiquetas duplicadas se rechazan para evitar colecciones duplicadas o corrupción del cursor. La configuración de rutas adicionales se recarga sin necesidad de reiniciar el daemon. +Las etiquetas definen el espacio de nombres de los IDs de agente derivados cuando dos raíces contienen copias del mismo proyecto. Las raíces superpuestas y las etiquetas duplicadas se rechazan para evitar recopilación duplicada o corrupción del cursor. La configuración de rutas adicionales se recarga sin necesidad de reiniciar el daemon. -Los entornos de contenedor pueden reemplazar las rutas adicionales configuradas en archivos con una variable separada por comas llamada `FAILPROOFAI__EXTRA_PATHS`, por ejemplo: +Los entornos de contenedor pueden reemplazar las rutas de captura adicionales configuradas en archivos con una variable separada por comas llamada `FAILPROOFAI__EXTRA_PATHS`, por ejemplo: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -112,26 +130,28 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Variables de entorno -Usa archivos de configuración para el comportamiento persistente de la máquina. Las variables de entorno son más útiles para contenedores, pruebas y procesos individuales. +Usa archivos de configuración para el comportamiento persistente de la máquina. Las variables de entorno son más útiles para contenedores, pruebas y un único proceso. | Variable | Uso | | --- | --- | -| `FAILPROOFAI_HOME` | Reubicar el layout completo de `~/.failproofai` | -| `FAILPROOFAI_LOG_LEVEL` | Establecer la verbosidad del registro local | -| `FAILPROOFAI_HOOK_LOG_FILE` | Escribir diagnósticos de hooks en un archivo seleccionado | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Deshabilitar la telemetría anónima para este proceso | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Omitir la configuración interactiva del primer inicio | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Omitir la auditoría local posterior a la configuración | -| `FAILPROOFAI_LLM_BASE_URL` | Reemplazar el endpoint compatible con OpenAI usado por las políticas LLM | -| `FAILPROOFAI_LLM_API_KEY` | Proporcionar la clave API utilizada por las políticas LLM | -| `FAILPROOFAI_LLM_MODEL` | Seleccionar el modelo utilizado por las políticas LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limitar el tiempo de carga de módulos de políticas personalizadas | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Rechazar la descarga de paquetes y binarios del daemon; lo que está instalado sigue aplicándose | -| `FAILPROOFAI_PACK_BASE_URL` | Obtener paquetes desde un mirror en lugar de `github.com` | -| `FAILPROOFAI__EXTRA_PATHS` | Reemplazar las rutas de captura adicionales configuradas para un harness | -| `NO_COLOR` | Deshabilitar la salida de terminal en color | - -Las variables de home específicas del agente, como `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` y `OPENCLAW_HOME`, sobreescriben el lugar donde Failproof AI descubre las sesiones locales para ese harness. +| `FAILPROOFAI_CLOUD_TOKEN` | La clave de Cloud, en lugar de `--token`. Prefiere esta opción: un argumento es legible desde `ps` por cualquier usuario. Configúrala con `read -s` o desde un almacén de secretos de CI, nunca tecleando la clave en un comando, que de todos modos queda en el historial del shell | +| `FAILPROOFAI_CLOUD_URL` | La URL de Cloud, en lugar de `--url`. La misma variable que lee el daemon | +| `FAILPROOFAI_HOME` | Reubica el diseño completo de `~/.failproofai` | +| `FAILPROOFAI_LOG_LEVEL` | Establece la verbosidad del registro local | +| `FAILPROOFAI_HOOK_LOG_FILE` | Escribe diagnósticos de hooks en un archivo seleccionado | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Deshabilita la telemetría anónima para este proceso | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Omite la configuración interactiva del primer inicio | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Omite la auditoría local posterior a la configuración | +| `FAILPROOFAI_LLM_BASE_URL` | Anula el endpoint compatible con OpenAI usado por las políticas LLM | +| `FAILPROOFAI_LLM_API_KEY` | Proporciona la clave de API usada por las políticas LLM | +| `FAILPROOFAI_LLM_MODEL` | Selecciona el modelo usado por las políticas LLM | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limita el tiempo de carga de módulos de políticas personalizadas | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Rechaza descargar packs y binarios del daemon; lo que está instalado sigue aplicándose | +| `FAILPROOFAI_PACK_BASE_URL` | Descarga packs desde un espejo en lugar de `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | Reemplaza las rutas de captura adicionales configuradas para un harness | +| `NO_COLOR` | Deshabilita la salida de terminal con color | + +Las variables de directorio home específicas de cada agente, como `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` y `OPENCLAW_HOME`, anulan el lugar donde Failproof AI descubre las sesiones locales para ese harness. ## Pausar o eliminar una máquina de forma segura @@ -141,7 +161,7 @@ failproofai config --status failproofai config --resume ``` -Una pausa de sesión local no deshabilita las políticas gestionadas por Cloud. Restaura los despliegues Cloud a través del flujo de trabajo de aplicación de Cloud cuando el propio despliegue es el problema. +Una pausa de sesión local no deshabilita las políticas gestionadas por Cloud. Restaura los despliegues de Cloud a través del flujo de trabajo de aplicación de Cloud cuando el problema es el propio despliegue. Antes de eliminar el paquete npm, elimina los hooks instalados y el daemon: @@ -154,5 +174,5 @@ npm rm -g failproofai Ejecuta `failproofai --help` para obtener detalles específicos de la versión. - Ejecuta `failproofai uninstall` antes de `npm rm -g failproofai`; npm no elimina los hooks del agente instalados ni el servicio del daemon. + Ejecuta `failproofai uninstall` antes de `npm rm -g failproofai`; npm no elimina los hooks de agentes instalados ni el servicio del daemon. \ No newline at end of file diff --git a/docs/es/reference/harnesses.mdx b/docs/es/reference/harnesses.mdx index fd312adf..df47004a 100644 --- a/docs/es/reference/harnesses.mdx +++ b/docs/es/reference/harnesses.mdx @@ -1,80 +1,86 @@ --- -title: "Entornos de ejecución de agentes" -description: "Captura sesiones y aplica políticas en los 12 entornos de ejecución compatibles." +title: "Agentes soportados" +description: "Captura sesiones y aplica políticas en los 12 agentes compatibles." icon: "plug-zap" --- -Un entorno de ejecución (*harness*) es el entorno dentro del cual corre tu agente. Failproof AI admite doce de ellos, en dos categorías: +Un harness es el entorno en el que realmente se ejecuta tu agente. Failproof AI soporta doce de ellos, en dos categorías: - **CLIs de programación** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Pasarelas de chat y asistente** (2) — Hermes (Slack, Telegram, cron), OpenClaw (asistente auto-alojado) +- **Gateways de chat y asistentes** (2) — Hermes (Slack, Telegram, cron), OpenClaw (asistente autoalojado) -Las mismas políticas y el mismo historial de sesiones se aplican independientemente del entorno en que corra un agente. Una capa de adaptador unifica los nombres de eventos nativos, nombres de herramientas y campos de entrada de herramientas de cada entorno sobre 29 eventos canónicos antes de que se ejecute cualquier política. +Las mismas políticas y el mismo historial de sesiones se aplican independientemente del entorno en que se ejecute el agente. Una capa de adaptador mapea los nombres de eventos nativos, nombres de herramientas y campos de entrada de cada harness en 29 eventos canónicos antes de que se ejecute cualquier política. -Un agente que no corre en **ninguno** de los doce se instrumenta directamente con el [SDK de Python](/es/reference/custom-agents). Este es un contrato diferente, y vale la pena dejarlo claro: el SDK proporciona trazabilidad, sesiones, evaluaciones y auditorías — **pero no aplica políticas por sí solo.** Bloquear una acción insegura antes de que se ejecute requiere un hook de enforcement en el límite de herramientas de tu runtime; [contáctanos](mailto:support@befailproof.ai) y lo mapeamos. +Un agente que no se ejecute en **ninguno** de los doce se instrumenta directamente con el [SDK de Python](/es/reference/custom-agents). Ese es un contrato distinto, y vale la pena dejarlo claro: el SDK proporciona trazabilidad, sesiones, evaluaciones y auditorías — **no aplica políticas por sí solo.** Para bloquear una acción insegura antes de que se ejecute se necesita un hook de aplicación en el límite de herramientas de tu runtime; [contáctanos](mailto:support@befailproof.ai) y lo mapearemos. -| Entorno | Ámbitos de hook compatibles | +| Harness | Ámbitos de hook soportados | | --- | --- | -| Claude Code | User, project, local | -| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | -| Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | -| Hermes, OpenClaw | User | +| Claude Code | Usuario, proyecto, local | +| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | Usuario, proyecto | +| Factory Droid, Devin CLI, Antigravity CLI, Goose | Usuario, proyecto | +| Hermes, OpenClaw | Usuario | -Cada integración normaliza sus nombres de eventos de hook nativos, nombres de herramientas y campos de entrada de herramientas antes de que se ejecuten las políticas. Una política solo puede actuar sobre los eventos que el entorno expone; prueba el comportamiento al final de turno y de instrucciones en el entorno y versión exactos que despliegues. +Cada integración normaliza los nombres de eventos nativos, nombres de herramientas y campos de entrada antes de que se ejecuten las políticas. Una política solo puede actuar sobre los eventos que el harness expone; prueba el comportamiento al final del turno y las instrucciones en el harness y versión exactos que vayas a desplegar. -## Capacidad de enforcement +## Capacidades de aplicación -«Bloquear» significa que el veredicto devuelto por el adaptador actual es consumido por el entorno indicado. El bloqueo post-herramienta puede reemplazar el resultado mostrado al modelo, pero no puede deshacer un efecto secundario de herramienta que ya ocurrió. +"Bloquear" significa que el veredicto devuelto por el adaptador actual es consumido por el harness indicado. El bloqueo post-herramienta puede reemplazar el resultado mostrado al modelo, pero no puede deshacer un efecto secundario de la herramienta que ya ocurrió. -| Entorno | Eventos de bloqueo verificados | Advertencias de solo observación o sin bloqueo | +| Harness | Eventos de bloqueo verificados | Advertencias de solo observación o no bloqueantes | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` y varios eventos de tarea/configuración | `PostToolUse`, ciclo de vida de sesión, notificaciones y eventos post-fallo son solo observacionales. | +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` y varios eventos de tarea/configuración | `PostToolUse`, el ciclo de vida de sesión, las notificaciones y los eventos post-fallo son observacionales. | | Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | El bloqueo post-herramienta reemplaza el resultado tras la ejecución; los eventos de inicio de sesión y compactación son observacionales en el adaptador actual. | | GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | El bloqueo post-herramienta reemplaza el resultado tras la ejecución; los eventos de sesión y notificación son observacionales. | | Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` y los eventos de sesión son observacionales. | -| OpenCode | `PreToolUse` | Los eventos post-herramienta y de ciclo de vida son observacionales; el manejo de stop actual es orientativo para un turno posterior, no una barrera verificada. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Los eventos post-herramienta y de ciclo de vida son observacionales; la orientación de stop aplica a un turno posterior. | -| Hermes | `PreToolUse` | Los veredictos post-herramienta, de sesión y subagent-stop no son barreras. | +| OpenCode | `PreToolUse` | Los eventos post-herramienta y de ciclo de vida son observacionales; el manejo actual de stop es una guía para un turno posterior, no una puerta verificada. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Los eventos post-herramienta y de ciclo de vida son observacionales; la guía de stop se aplica a un turno posterior. | +| Hermes | `PreToolUse` | Los veredictos post-herramienta, de sesión y de subagent-stop no son puertas de control. | | OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Los eventos post-herramienta, de sesión, subagent-stop y compactación son observacionales. | | Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Los veredictos post-herramienta y subagent-stop son observacionales. | | Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condicional | Los hooks de permiso no se ejecutan en todos los modos de permiso; los eventos post-herramienta y de sesión son observacionales. | | Antigravity CLI | `PreToolUse`, `Stop` | Los veredictos de user-prompt y post-herramienta son observacionales; las instrucciones de prompt aún pueden inyectarse. | -| Goose | `PreToolUse` | Los eventos de user-prompt, post-herramienta y de sesión son observacionales. Existe un hook de stop nativo de bloqueo en upstream, pero no está instalado por el adaptador actual. | +| Goose | `PreToolUse` | Los eventos de user-prompt, post-herramienta y de sesión son observacionales. Existe un hook de stop nativo bloqueante en la capa superior, pero el adaptador actual no lo instala. | -Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI de agente, especialmente cuando una política depende del comportamiento de prompt, stop, permiso o post-herramienta en lugar de la barrera común pre-herramienta. +Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI de agente, especialmente cuando una política dependa del comportamiento de prompt, stop, permiso o post-herramienta en lugar de la puerta pre-herramienta habitual. -## Instalar hooks de captura y de políticas +## Instalar hooks de captura y políticas - 1. Abre **Administración → Claves** y crea una clave con `events:add` y `policies:pull`, con un nombre identificativo para la máquina o entorno. - 2. En la máquina de destino, conecta el CLI local con la clave mostrada e instala los hooks del entorno. + 1. Abre **Administración → Claves** y crea una clave con `events:add` y `policies:pull`, con un nombre que identifique la máquina o el entorno. + 2. En la máquina de destino, conecta el CLI local con la clave mostrada e instala los hooks del harness. 3. Inicia una nueva sesión de agente y confirma sus eventos de hook y sesión en **Observar → Eventos**. - 4. Abre **Observar → política** para la misma ventana temporal y confirma que una decisión de política está atribuida a la máquina. + 4. Abre **Observar → Política** para el mismo intervalo de tiempo y confirma que una decisión de política está atribuida a la máquina. - La conexión comienza con una clave de máquina. Confirma que incluye permisos tanto de ingesta como de entrega de políticas antes de copiar su secreto. + La conexión comienza con una clave de máquina. Confirma que incluye permisos de ingesta y entrega de políticas antes de copiar su secreto. - ![El panel de creación de claves API utilizado para conceder permisos de ingesta de eventos y entrega de políticas.](/images/dashboard/key-create.png) + ![El panel para crear una nueva clave de API, utilizado para otorgar permisos de ingesta de eventos y entrega de políticas.](/images/dashboard/key-create.png) - Tras instalar los hooks, el flujo de Eventos debería mostrar nuevos eventos de la máquina y entorno conectados. + Tras instalar los hooks, el flujo de Eventos debería mostrar nuevos eventos desde la máquina y el entorno que conectaste. - ![El flujo de Eventos en vivo utilizado para confirmar que un entorno recién instalado está reportando.](/images/dashboard/events-stream.png) + ![El flujo de Eventos en tiempo real utilizado para confirmar que un harness recién instalado está reportando.](/images/dashboard/events-stream.png) - Por último, verifica que las decisiones de política estén atribuidas a la misma máquina. Esto confirma que el entorno está reportando tanto actividad de políticas como eventos de traza. + Por último, verifica que las decisiones de política están atribuidas a la misma máquina. Esto confirma que el harness está reportando tanto la actividad de políticas como los eventos de traza. - ![La página de Política utilizada para verificar las decisiones de política de un entorno recién conectado.](/images/dashboard/policy-observe.png) + ![La página de Política utilizada para verificar las decisiones de política de un harness recién conectado.](/images/dashboard/policy-observe.png) - Instala hooks para todos los entornos detectados: + Lee la clave de máquina en el shell. `read -s` la solicita en un prompt que no hace eco, por lo que nunca aparece en un comando ni en el historial del shell: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - O apunta a entornos específicos y un ámbito de configuración: + Luego configura la máquina — esto conecta hooks para cada harness detectado, instala el daemon y se conecta a Cloud: + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + La configuración no habilita ninguna política por sí sola; para eso sirve el segundo comando. + + También puedes apuntar a harnesses específicos y un ámbito de configuración: ```bash failproofai policies --install \ @@ -82,7 +88,7 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI --scope user ``` - El ámbito de proyecto mantiene la configuración de hooks junto al repositorio. El ámbito de usuario cubre el trabajo entre repositorios. Claude Code también admite ámbito local; la compatibilidad varía según el entorno y el CLI rechaza combinaciones no admitidas. + El ámbito de proyecto mantiene la configuración de hooks junto al repositorio. El ámbito de usuario cubre el trabajo en múltiples repositorios. Claude Code también soporta el ámbito local; el soporte varía según el harness y el CLI rechaza las combinaciones no soportadas. Verifica la máquina y sus eventos: @@ -94,16 +100,16 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI -## Añadir una ruta de sesión no predeterminada +## Agregar una ruta de sesión no predeterminada - Las rutas adicionales se registran en la máquina, no en la nube. Tras añadir una, abre **Observar → Sesiones**, filtra por el entorno de la máquina y confirma que aparecen sesiones de la nueva ruta. Abre una sesión y revisa el agente, el entorno y las marcas de tiempo de los eventos antes de usarla en una auditoría. + Las rutas adicionales se registran en la máquina, no en Cloud. Después de agregar una, abre **Observar → Sesiones**, filtra por el entorno de la máquina y confirma que aparecen sesiones desde la nueva ruta. Abre una sesión y comprueba el agente, el harness y las marcas de tiempo de los eventos antes de utilizarla en una auditoría. ![La lista de Sesiones filtrada al entorno que recibe datos de la ruta de captura adicional.](/images/dashboard/sessions-list.png) - Añade una ruta con una etiqueta opcional y luego inspecciona las rutas configuradas: + Agrega una ruta con una etiqueta opcional y luego inspecciona las rutas configuradas: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -117,5 +123,5 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI - Ejecuta una sesión nueva tras la instalación. Verifica tanto el flujo de eventos en vivo como una decisión de política real antes de ampliar el despliegue. + Ejecuta una sesión nueva tras la instalación. Verifica tanto el flujo de eventos en tiempo real como una decisión de política real antes de ampliar el despliegue. \ No newline at end of file diff --git a/docs/es/reference/overview.mdx b/docs/es/reference/overview.mdx index 1475e1e7..3022badd 100644 --- a/docs/es/reference/overview.mdx +++ b/docs/es/reference/overview.mdx @@ -1,29 +1,29 @@ --- title: "Integraciones y referencia" -description: "Conecta harnesses de agentes compatibles, SDKs, CLIs y la API HTTP." +description: "Conecta agentes compatibles, SDKs, CLIs y la API HTTP." icon: "braces" --- -Elige la integración más cercana al entorno donde ya ejecutas tu agente. +Elige la integración más adecuada para donde ya se ejecuta tu agente. - + Instala hooks para CLIs de agentes de codificación y autónomos compatibles. Instrumenta LangGraph, CrewAI, LlamaIndex, Pydantic AI o un agente personalizado. - Configuración, el catálogo de eventos, reglas de correlación y entrega. + Configuración, catálogo de eventos, reglas de correlación y entrega. Revisa proyectos locales, sesiones, actividad de políticas y auditorías sin conexión. - - Configura captura local, hooks, políticas, auditorías, entrega y estado de la máquina. + + Configura la captura local, hooks, políticas, auditorías, entrega y estado de la máquina. - - Consulta y administra sesiones, auditorías, incidencias, alertas, claves, usuarios y configuraciones de Cloud. + + Consulta y administra sesiones, auditorías, incidencias, alertas, claves, usuarios y configuración en la nube. Puntúa sesiones completas o inactivas con un servicio FastAPI. @@ -31,43 +31,46 @@ Elige la integración más cercana al entorno donde ya ejecutas tu agente. Crea y prueba decisiones allow, instruct y deny específicas para tu flujo de trabajo. - - Despliega el plano de control de Cloud en un clúster Kubernetes administrado por el cliente. + + Despliega el plano de control en la nube en un clúster Kubernetes gestionado por el cliente. -La [referencia de la API HTTP](/es/reference/http-api) generada cubre la superficie pública `/v1`. Las páginas escritas manualmente explican flujos de trabajo que abarcan múltiples endpoints o utilizan interfaces administrativas fuera de esa superficie pública. +La [referencia de la API HTTP](/es/reference/http-api) generada cubre la superficie pública `/v1`. Las páginas escritas a mano explican flujos de trabajo que abarcan múltiples endpoints o utilizan interfaces administrativas fuera de esa superficie pública. -## Conecta un agente y verifica los datos +## Conectar un agente y verificar los datos 1. Abre **Administración → Claves**, crea una clave con `events:add` y `policies:pull`, y copia el secreto. 2. Configura la integración usando la página correspondiente indicada arriba. - 3. Abre **Observar → Eventos** para confirmar que llegan los eventos y, luego, **Observar → Sesiones** para confirmar que forman ejecuciones completas. + 3. Abre **Observar → Eventos** para confirmar que los eventos llegan correctamente, luego **Observar → Sesiones** para confirmar que forman ejecuciones completas. 4. Filtra por el entorno de la integración e inspecciona una sesión para verificar los campos de modelo, herramienta, error y política que necesitan las auditorías. - Comienza con el panel de claves. Los permisos seleccionados determinan si la máquina puede enviar eventos y recibir políticas administradas desde Cloud. + Comienza con el panel de claves. Los permisos seleccionados determinan si la máquina puede enviar eventos y recibir políticas gestionadas en la nube. - ![El panel de nueva clave de API usado para otorgar permisos de ingesta de eventos y entrega de políticas.](/images/dashboard/key-create.png) + ![El panel de nueva clave API utilizado para conceder permisos de ingesta de eventos y entrega de políticas.](/images/dashboard/key-create.png) - Después de conectar la integración, usa la lista de Sesiones para confirmar que sus eventos se están agrupando en ejecuciones completas en el entorno esperado. + Tras conectar la integración, usa la lista de Sesiones para confirmar que sus eventos se están agrupando en ejecuciones completas en el entorno esperado. - ![La lista de Sesiones usada para verificar que una integración recién conectada está reportando ejecuciones completas del agente.](/images/dashboard/sessions-list.png) + ![La lista de Sesiones utilizada para verificar que una integración recién conectada está reportando ejecuciones completas del agente.](/images/dashboard/sessions-list.png) - Abre una de estas sesiones antes de considerar la integración completa; el trazado debe contener el modelo, la herramienta, el error y las evidencias de política que necesitan tus auditorías. + Abre una de estas sesiones antes de dar la integración por completada; la traza debe contener el modelo, la herramienta, el error y la evidencia de política que necesitan tus auditorías. - Crea una clave de máquina, conecta el daemon de Failproof y verifica la primera sesión. + Crea una clave de máquina y luego lee el secreto que imprime en el shell. `read -s` lo captura en un prompt que no muestra el texto, de modo que nunca aparece en un comando ni en el historial del shell: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Conecta el daemon de Failproof y verifica la primera sesión: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production @@ -76,6 +79,6 @@ La [referencia de la API HTTP](/es/reference/http-api) generada cubre la superfi Usa `fp --json sessions ...` cuando otra herramienta vaya a consumir el resultado. Los flags globales como `--json`, `--org` y `--base-url` deben ir antes del comando. - Consulta la [referencia de la CLI de Failproof AI](/es/reference/failproof-cli) para los comandos locales y la [referencia de la CLI de Failproof Cloud](/es/reference/cloud-cli#cli-commands) para los comandos `fp`. + Consulta la [referencia del Failproof AI CLI](/es/reference/failproof-cli) para los comandos locales y la [referencia del Failproof Cloud CLI](/es/reference/cloud-cli#cli-commands) para los comandos `fp`. \ No newline at end of file diff --git a/docs/es/reference/policy-sdk.mdx b/docs/es/reference/policy-sdk.mdx index 12dfb99e..6157fa92 100644 --- a/docs/es/reference/policy-sdk.mdx +++ b/docs/es/reference/policy-sdk.mdx @@ -4,26 +4,26 @@ description: "Crea, prueba e implementa políticas en JavaScript o TypeScript pa icon: "shield-plus" --- -Las políticas personalizadas convierten un patrón de fallos de tus trazas o auditorías en una decisión que se ejecuta mientras un agente trabaja. Una política puede permitir una acción, proporcionar orientación al agente o denegar la acción antes de que provoque otro incidente. +Las políticas personalizadas convierten un patrón de fallos de tus trazas o auditorías en una decisión que se ejecuta mientras trabaja un agente. Una política puede permitir una acción, proporcionar orientación al agente o bloquear la acción antes de que cause otro incidente. -Usa una política personalizada cuando el comportamiento depende de tus herramientas, rutas, comandos, entornos o reglas operativas. Consulta primero el [catálogo de políticas integradas](/es/policies/builtin-catalog) para no recrear un control existente. +Usa una política personalizada cuando el comportamiento dependa de tus herramientas, rutas, comandos, entornos o reglas de operación. Consulta primero el [paquete de políticas de Failproof AI](/es/policies/packs) para no recrear un control que ya existe. ## Crear una política personalizada - - 1. Ve a **Admin → editor de políticas**, selecciona **Nueva política** y describe el fallo que quieres prevenir. + + 1. Ve a **Admin → editor de políticas**, selecciona **Nueva política** y describe el fallo que deseas prevenir. 2. Añade el código fuente de la política, luego prueba coincidencias esperadas y no coincidencias seguras en el editor. Resuelve todos los errores de validación. 3. Guarda el borrador y selecciona **Publicar versión** para crear una versión inmutable. - 4. Ve a **Admin → cumplimiento**, despliega la versión en una máquina de prueba en modo **observación** y verifica sus decisiones en **Observar → política** antes de aplicarla. + 4. Ve a **Admin → enforcement**, despliega la versión en una máquina de prueba en modo **observe** y verifica sus decisiones en **Observe → policy** antes de aplicarla. - ![El editor de políticas usado para crear y publicar una política personalizada.](/images/dashboard/policy-editor.png) + ![El editor de políticas utilizado para crear y publicar una política personalizada.](/images/dashboard/policy-editor.png) 1. Crea `.failproofai/policies/checkout-policies.ts`. El nombre del archivo debe terminar en `policies.js`, `policies.mjs` o `policies.ts`. 2. Registra una o más políticas con `customPolicies.add()`. 3. Valida e instala el archivo con `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. - 4. Activa una acción que coincida y una acción segura. Ejecuta `failproofai policies` e inspecciona las decisiones atribuidas en **Observar → política**. + 4. Activa una acción que coincida y una acción segura. Ejecuta `failproofai policies` y luego examina las decisiones atribuidas en **Observe → policy**. @@ -55,20 +55,20 @@ customPolicies.add({ }); ``` -Las buenas políticas son lo suficientemente específicas como para explicarse en una sola frase. Evalúa la acción observable —no la intención que esperas que haya tenido el agente— y devuelve `allow()` en cuanto la regla no sea aplicable. +Las buenas políticas son lo suficientemente específicas como para explicarlas en una sola frase. Evalúa la acción observable —no la intención que esperas que el agente tuviera— y devuelve `allow()` en cuanto la regla no aplique. ## Elige una decisión -| Función | Resultado | Úsala cuando | +| Helper | Resultado | Úsalo cuando | | --- | --- | --- | | `allow(reason?)` | La operación continúa. | La política no aplica o la acción es segura. | -| `instruct(reason)` | La operación continúa con orientación donde el harness lo admita. | Quieres guiar al agente hacia un mejor enfoque sin imponer una restricción estricta. | -| `deny(reason)` | La operación se bloquea cuando el evento y el harness admiten el bloqueo. | La acción no debe ejecutarse. | +| `instruct(reason)` | La operación continúa con orientación cuando el harness lo soporta. | Quieres guiar al agente hacia un mejor enfoque sin imponer una restricción. | +| `deny(reason)` | La operación se bloquea cuando el evento y el harness admiten el bloqueo. | La acción no debe continuar. | -Escribe la razón pensando en el agente que debe recuperarse. Explica qué se detectó y qué debería hacer en su lugar. +Escribe el motivo pensando en el agente que debe recuperarse. Explica qué se detectó y qué debe hacer en su lugar. - No uses `instruct()` como límite de seguridad. La entrega de orientación varía según el harness del agente. Usa `deny()` cuando la acción deba ser prevenida. + No uses `instruct()` como límite de seguridad. La entrega de orientación varía según el harness del agente. Usa `deny()` cuando la acción deba prevenirse. ## Objeto de política @@ -82,34 +82,34 @@ customPolicies.add({ }); ``` -| Campo | Requerido | Descripción | +| Campo | Obligatorio | Descripción | | --- | --- | --- | -| `name` | Sí | Identificador estable para la política. Mantén los nombres únicos entre archivos. | -| `description` | No | Propósito legible por humanos, mostrado en los listados de políticas y decisiones. | +| `name` | Sí | Identificador estable de la política. Mantén los nombres únicos entre archivos. | +| `description` | No | Propósito legible que se muestra en los listados de políticas y en las decisiones. | | `match.events` | No | Tipos de eventos que invocan la política. Omitir `match` la invoca para todos los eventos disponibles. | | `fn` | Sí | Función síncrona o asíncrona que devuelve un resultado `allow`, `instruct` o `deny`. | -Filtra herramientas dentro de `fn`. `match.toolNames` no forma parte del tipo público de política personalizada. +Filtra las herramientas dentro de `fn`. `match.toolNames` no forma parte del tipo público de política personalizada. -## Contexto de la política +## Contexto de política -Toda política recibe un `PolicyContext`. +Cada política recibe un `PolicyContext`. -| Campo | Tipo | Contenido | +| Campo | Tipo | Qué contiene | | --- | --- | --- | | `eventType` | `HookEventType` | Evento normalizado que se está evaluando actualmente. | | `toolName` | `string \| undefined` | Nombre canónico de la herramienta, como `Bash`, `Read`, `Write` o `Edit`. | -| `toolInput` | `Record \| undefined` | Entrada canónica para la llamada a la herramienta actual. | +| `toolInput` | `Record \| undefined` | Entrada canónica para la llamada de herramienta actual. | | `payload` | `Record` | Carga útil completa del evento normalizado. | -| `session` | `SessionMetadata \| undefined` | ID de sesión, directorio de trabajo, ruta de transcripción, modo de permisos y metadatos del harness cuando estén disponibles. | +| `session` | `SessionMetadata \| undefined` | ID de sesión, directorio de trabajo, ruta del transcript, modo de permisos y metadatos del harness cuando están disponibles. | | `cli` | `string \| undefined` | Harness del agente de origen, como `claude`, `codex` o `cursor`. | -| `params` | `Record` | Parámetros de políticas integradas. Las políticas personalizadas reciben actualmente un objeto vacío. | +| `params` | `Record` | Parámetros de política integrados. Las políticas personalizadas reciben actualmente un objeto vacío. | -Trata cada valor opcional como genuinamente opcional. Las versiones de agentes y los tipos de eventos no siempre proporcionan los mismos campos. +Trata cada valor opcional como genuinamente opcional. Las versiones de agentes y los tipos de eventos no proporcionan siempre los mismos campos. ### Entradas comunes de herramientas -Failproof AI normaliza las herramientas más comunes entre los harnesses compatibles, de modo que una política generalmente puede usar una sola forma de entrada. +Failproof AI normaliza las herramientas comunes entre los harnesses compatibles para que una política pueda usar generalmente una única forma de entrada. | Herramienta | Campos comunes | | --- | --- | @@ -131,11 +131,11 @@ const filePath = String(ctx.toolInput?.file_path ?? ""); | Evento | Cuándo se ejecuta | Uso típico | | --- | --- | --- | | `PreToolUse` | Antes de que se ejecute una herramienta. | Bloquear o guiar comandos, escrituras, lecturas y acciones externas. | -| `PostToolUse` | Después de que una herramienta retorna. | Inspeccionar resultados antes de que lleguen al agente. Un deny bloquea el resultado completo; no redacta campos seleccionados. | +| `PostToolUse` | Después de que una herramienta devuelva resultado. | Inspeccionar resultados antes de que lleguen al agente. Un deny bloquea todo el resultado; no redacta campos seleccionados. | | `PermissionRequest` | Cuando el agente solicita permiso. | Aplicar reglas de permisos específicas de la organización. | -| `UserPromptSubmit` | Antes de que continúe un prompt enviado. | Rechazar instrucciones prohibidas o añadir orientación de flujo de trabajo. | -| `Stop` | Cuando el agente intenta finalizar. | Exigir una condición de finalización alcanzable, como un paso de verificación local. | -| `SubagentStop` | Cuando un subagente intenta finalizar. | Controlar el trabajo delegado antes de que retorne al padre. | +| `UserPromptSubmit` | Antes de que continúe un prompt enviado. | Rechazar instrucciones prohibidas o añadir orientación sobre el flujo de trabajo. | +| `Stop` | Cuando el agente intenta finalizar. | Requerir una condición de finalización alcanzable, como un paso de verificación local. | +| `SubagentStop` | Cuando un subagente intenta finalizar. | Supervisar el trabajo delegado antes de que vuelva al agente padre. | | `SessionStart` / `SessionEnd` | En los límites de sesión. | Registrar o verificar el estado a nivel de sesión. | La disponibilidad de eventos y el comportamiento de bloqueo dependen del harness del agente. Consulta [Harnesses de agentes](/es/reference/harnesses) antes de depender de un evento en una flota mixta. @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### Controlar la finalización de sesión +### Controlar la finalización de la sesión ```ts import { execFileSync } from "node:child_process"; @@ -215,30 +215,30 @@ customPolicies.add({ ``` - Un evento `Stop` denegado puede hacer que el agente reintente. Solo impone condiciones que el agente pueda satisfacer en el entorno actual, y limita el tiempo de todo subproceso o llamada de red. + Un evento `Stop` denegado puede hacer que el agente reintente. Solo condiciona la finalización a una condición que el agente pueda satisfacer en el entorno actual, y limita el tiempo de ejecución de cada subproceso o llamada de red. -## Cargar archivos de políticas +## Cargar archivos de política -### Archivos de convención +### Archivos por convención -Los archivos de convención se cargan automáticamente: +Los archivos por convención se cargan automáticamente: ```text /.failproofai/policies/security-policies.ts ~/.failproofai/policies/personal-policies.mjs ``` -- Se cargan tanto el directorio de políticas del proyecto como el del usuario. -- Los archivos se cargan alfabéticamente dentro de cada directorio. -- El nombre del archivo debe terminar en `policies.js`, `policies.mjs` o `policies.ts`. +- Los directorios de políticas del proyecto y del usuario se cargan ambos. +- Los archivos se cargan en orden alfabético dentro de cada directorio. +- Un archivo debe terminar en `policies.js`, `policies.mjs` o `policies.ts`. - Se admiten múltiples llamadas a `customPolicies.add()` en un mismo archivo. - Se admiten importaciones relativas desde módulos locales. -- Las políticas del proyecto pueden incluirse en el repositorio para que las mismas reglas sigan al código. +- Las políticas del proyecto pueden incluirse en el repositorio para que las mismas reglas acompañen al código. ### Archivos explícitos -Usa rutas explícitas cuando la validación o la configuración deba nombrar el archivo de entrada directamente: +Usa rutas explícitas cuando la validación o la configuración deba nombrar directamente el archivo de entrada: ```bash failproofai policies --install \ @@ -260,44 +260,44 @@ failproofai policies --install \ failproofai policies ``` -La validación detecta archivos faltantes, errores de sintaxis, importaciones sin resolver, excepciones en el nivel superior y tiempos de espera de carga del módulo. No verifica que tu lógica de coincidencia sea correcta. +La validación detecta archivos faltantes, errores de sintaxis, importaciones no resueltas, excepciones en el nivel superior y tiempos de espera en la carga del módulo. No verifica que tu lógica de coincidencia sea correcta. Prueba al menos estos casos: -- Una acción que deba coincidir y producir el motivo de política esperado. +- Una acción que deba coincidir y producir el motivo de política previsto. - Una acción cercana pero segura que deba devolver `allow()`. -- Campos de herramienta faltantes o malformados. -- Sintaxis de comandos alternativa, rutas, comillas, mayúsculas/minúsculas y espacios en blanco. +- Campos de herramienta faltantes o mal formados. +- Sintaxis de comando alternativa, rutas, comillas, mayúsculas/minúsculas y espacios en blanco. - Un subproceso o dependencia de red no disponible. -Atribuye el resultado a tu política personalizada en **Observar → política**. Una prueba bloqueada no es suficiente si fue una política integrada diferente la que tomó la decisión. +Atribuye el resultado a tu política personalizada en **Observe → policy**. Un test bloqueado no es suficiente si fue una política integrada diferente la que tomó la decisión. ## Comportamiento en tiempo de ejecución - Las políticas integradas se evalúan antes que las políticas personalizadas. -- El primer `deny` detiene la evaluación de políticas posteriores. +- El primer `deny` detiene la evaluación de las políticas restantes. - Múltiples resultados `instruct` pueden combinarse cuando ninguna política deniega el evento. -- Una función de política tiene un plazo de ejecución de 10 segundos. -- Una excepción lanzada o un tiempo de espera agotado se registra y se trata como `allow()`. -- Un archivo de convención que falla al cargar se omite; los demás archivos personalizados y las políticas integradas continúan. -- La carga del módulo en el nivel superior también tiene un plazo de 10 segundos. -- El modo de observación en la nube ejecuta la política pero registra una decisión que no es allow sin aplicarla. +- Una función de política tiene un límite de ejecución de 10 segundos. +- Una excepción lanzada o un tiempo de espera agotado se registran y se tratan como `allow()`. +- Un archivo de convención que no se carga correctamente se omite; los demás archivos personalizados y las políticas integradas continúan. +- La carga del módulo en el nivel superior también tiene un límite de 10 segundos. +- El modo observe en la nube ejecuta la política pero registra una decisión que no sea allow sin aplicarla. -Mantén los módulos de políticas deterministas y rápidos. Evita llamadas de red en el nivel superior o el inicio de servidores. Limita el trabajo dentro de `fn`, captura los fallos de dependencias y decide deliberadamente si ese fallo debe permitir o denegar la operación. +Mantén los módulos de política deterministas y rápidos. Evita llamadas de red o inicios de servidor en el nivel superior. Limita el trabajo dentro de `fn`, captura los fallos de dependencias y decide deliberadamente si ese fallo debe permitir o bloquear la operación. ## Exportaciones de la API | Exportación | Propósito | | --- | --- | -| `customPolicies.add(policy)` | Registra una política personalizada cuando se carga el módulo. | -| `allow(reason?)` | Permite la operación. | -| `instruct(reason)` | Permite la operación y proporciona orientación donde sea compatible. | -| `deny(reason)` | Bloquea la operación donde sea compatible. | -| `getCustomHooks()` | Devuelve las políticas actualmente registradas en el registro del módulo. | -| `clearCustomHooks()` | Limpia ese registro, principalmente para pruebas y cargadores. | +| `customPolicies.add(policy)` | Registrar una política personalizada al cargar el módulo. | +| `allow(reason?)` | Permitir la operación. | +| `instruct(reason)` | Permitir la operación y proporcionar orientación donde se admita. | +| `deny(reason)` | Bloquear la operación donde se admita. | +| `getCustomHooks()` | Devolver las políticas actualmente registradas en el registro del módulo. | +| `clearCustomHooks()` | Limpiar ese registro, principalmente para pruebas y cargadores. | TypeScript exporta `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` y `PolicyFunction`. - Publica una versión, impleméntala en modo observación, verifica las decisiones y pasa a la aplicación. + Publica una versión, impleméntala en modo observe, verifica las decisiones y pasa a la aplicación. \ No newline at end of file diff --git a/docs/es/sessions/evaluations.mdx b/docs/es/sessions/evaluations.mdx index a69a52a8..4b73e6a5 100644 --- a/docs/es/sessions/evaluations.mdx +++ b/docs/es/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "Evaluaciones en línea" -description: "Puntúa sesiones activas y completadas por calidad, cumplimiento, costo y latencia." +title: "Leer resultados de evaluaciones" +description: "Visualiza puntuaciones a lo largo del tiempo, compara agentes y entornos, descubre por qué una sesión obtuvo una puntuación baja y consulta al asistente." icon: "gauge" --- -Las evaluaciones en línea aplican criterios consistentes a las sesiones de agentes. Úsalas para señales que deban medirse continuamente, en lugar de investigarse únicamente durante una auditoría. +Los resultados de cada evaluación, ya sea alojada o de tu propio worker, llegan a los mismos lugares. -## Revisar la calidad de las evaluaciones +## Comparar puntuaciones a lo largo del tiempo - - 1. Ve a **Observe → Evaluations**. - 2. Agrega una serie y elige el agente, el entorno, la puntuación de evaluación, la estadística y la curva. - 3. Agrega series para comparar entornos, agentes o claves de puntuación. - 4. Selecciona un resultado para abrir las sesiones correspondientes o compartir la vista filtrada. Usa **Observe → Metrics** para latencia, tokens, costo y otros valores de magnitud. + + Ve a **Observe → evaluations**. - ![Un panel de calidad que muestra las puntuaciones de evaluación promedio y las tendencias a lo largo del tiempo.](/images/dashboard/dashboard-quality.png) + - **Recent runs** lista cada evaluación a medida que llega: si proviene de un evaluador alojado (**managed**) o del tuyo propio (**customer**), el agente y la sesión, la evaluación y su versión, su estado, y su puntuación o métricas. + - **Score over time** grafica lo que solicites. Selecciona **add series** y elige un agente, un entorno, una evaluación y una estadística: avg, min, max, p50, p75, p90, p95, p99, stddev o mode. Cada serie es una línea; asígnale su propia **curve** para mostrarla en un gráfico separado. - Abre una sesión desde el desglose para inspeccionar el razonamiento por puntuación: + ![La página de evaluaciones: ejecuciones recientes etiquetadas como customer, un gráfico de puntuación a lo largo del tiempo con líneas de referencia en 0.5 y 0.8, y una serie que promedia finished_clean en todos los agentes y entornos.](/images/dashboard/evaluations-chart.png) - ![Una vista de detalle de sesión que muestra las puntuaciones de evaluación y el razonamiento junto a la traza completa.](/images/dashboard/session-detail.png) + Un único rango de tiempo y un tamaño de intervalo se aplican a todas las series. Un intervalo fino detecta un incidente; uno más amplio muestra una tendencia y puede ocultar los picos que estás buscando. Un intervalo donde no se registró ninguna puntuación aparece como una brecha en la línea, nunca como un cero; las líneas de referencia marcan 0.5 y 0.8. + + Cada parte de la vista vive en la URL: **share** la copia, y quien la abra verá exactamente la comparación que construiste. ```bash @@ -32,21 +32,25 @@ Las evaluaciones en línea aplican criterios consistentes a las sesiones de agen -Un evaluador recibe la identidad de la sesión, el entorno, las marcas de tiempo y los eventos ordenados. Puede devolver claves de puntuación numéricas con razonamiento opcional y un resumen. Los evaluadores de larga duración pueden devolver un trabajo pendiente y ser consultados posteriormente. +Grafica **avg** y **p90** para la misma evaluación y comprueba si un buen promedio está ocultando una cola deficiente, o grafica la misma evaluación para dos agentes distintos, o para producción y staging, y compáralos en un mismo eje. Los costos, las latencias y los conteos de tokens, que llevan unidades, se grafican en **Observe → metrics**, un gráfico por unidad. + +## Ver por qué una sesión obtuvo una puntuación baja + +Abre una sesión desde **Observe → sessions**; la cuadrícula muestra las puntuaciones de cada sesión y permite filtrar por rango de puntuación. El panel derecho de la sesión comienza con el resumen de la evaluación, seguido de una barra por puntuación con el razonamiento del evaluador debajo. + +![Vista detallada de una sesión con puntuaciones de evaluación y razonamiento junto al trazado completo.](/images/dashboard/session-detail.png) + +## Consultar al asistente + +Pregunta sobre datos de evaluación en lenguaje natural: "cuéntame sobre algunas de las evaluaciones recientes", o qué agentes están viendo sus puntuaciones caer. El [asistente](/es/sessions/assistant) lee y analiza los resultados, y responde con tablas sobre las que puedes hacer seguimiento; una pregunta que valga la pena conservar puede convertirse en una [consulta](/es/sessions/queries) o un [dashboard](/es/sessions/dashboards). -## Buenos objetivos de evaluación +![La página de evaluaciones junto al asistente, que responde a "cuéntame sobre algunas de las evaluaciones recientes" con un resumen de totales, estados y puntuaciones.](/images/dashboard/evaluations-assistant.png) -- Completitud o corrección de tareas -- Fundamentación y riesgo de alucinaciones -- Selección de herramientas y eficiencia de herramientas -- Cumplimiento de políticas o procesos -- Presupuestos de costo y latencia -- Escalado humano requerido +## Monitorear y actuar -## De la puntuación a la respuesta +- Los **Dashboards**, en **Analyze → dashboards**, muestran la tendencia de las puntuaciones que destacas, por agente y entorno, para toda la organización. -Muestra las puntuaciones en paneles para rastrear tendencias. Crea alertas para umbrales o condiciones compuestas. Cuando una puntuación disminuye en una población, ejecuta una auditoría para investigar el motivo; cuando la causa es una acción repetible, despliega una política. + ![Un dashboard de calidad que muestra puntuaciones de evaluación promedio y tendencias a lo largo del tiempo.](/images/dashboard/dashboard-quality.png) - - Implementa evaluaciones síncronas o asíncronas con el SDK de evaluadores de Python. - \ No newline at end of file +- Las **Alerts** te notifican cuando una puntuación supera un umbral. Consulta [alerts](/es/audits/alerts). +- Cuando una puntuación decae en muchas sesiones, [ejecuta una auditoría](/es/audits/run) para averiguar por qué; cuando la causa es una acción repetible, [escribe una política](/es/policies/editor). \ No newline at end of file diff --git a/docs/es/start/integrations/custom-agents.mdx b/docs/es/start/integrations/custom-agents.mdx index c1241eff..09d79215 100644 --- a/docs/es/start/integrations/custom-agents.mdx +++ b/docs/es/start/integrations/custom-agents.mdx @@ -7,7 +7,7 @@ icon: "code" Para un agente que escribiste tú mismo, o un framework para el que Failproof AI no tiene adaptador. No hay nada que instrumentar: tú emites los eventos. -Esta es la misma API que utilizan internamente los cuatro adaptadores de frameworks. Son tablas de traducción sobre ella. +Esta es la misma API que los cuatro adaptadores de framework utilizan internamente. Son tablas de traducción sobre ella. ## Instalación @@ -15,7 +15,7 @@ Esta es la misma API que utilizan internamente los cuatro adaptadores de framewo pip install failproofai-sdk ``` -Sin extras y sin dependencias. +Sin extras ni dependencias. ## Instrumentación @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # una ejecución t.output = search(q) # una llamada a herramienta ``` -Léelo de arriba a abajo y dice exactamente lo que significa: +Léelo de arriba a abajo y verás lo que significa: | Envuélvelo en | Para indicar | | --- | --- | | `session()` | Estos eventos pertenecen a la misma ejecución | -| `agent()` | Algo está realizando trabajo — dale un nombre que reconocerías en una lista | -| `tool_call()` | Esta es una herramienta y esto fue lo que devolvió | +| `agent()` | Algo está haciendo trabajo — dale un nombre que reconocerías en una lista | +| `tool_call()` | Esta es una herramienta, y esto es lo que devolvió | -Y lo que emite cada uno realmente: +Y lo que cada uno emite realmente: | Ámbito | Emite | Propósito | | --- | --- | --- | -| `session()` | Nada | Vincula un session id, agrupando una ejecución | +| `session()` | Nada | Vincula un id de sesión, agrupando una ejecución | | `agent()` | `agent_start`, `agent_end` | Delimita una unidad de trabajo | | `tool_call()` | `tool_use`, `tool_result` | Delimita una herramienta y la mide | -Todo lo que está dentro puede omitir `session_id` y `agent_id`. Los ámbitos vinculan la identidad en variables de contexto y cada llamada a evento la recupera, de modo que nunca necesitas pasar ids a través de tus funciones. +Todo lo que esté dentro puede omitir `session_id` y `agent_id`. Los ámbitos vinculan la identidad en variables de contexto y cada llamada a evento la lee de vuelta, por lo que nunca necesitas pasar ids a través de tus funciones. -Los tres también funcionan con `async with` además de `with`. +Los tres funcionan tanto con `async with` como con `with`. -Anidar agentes construye el árbol. `parent_id` y la profundidad se calculan a partir de la pila: +Anidar agentes construye el árbol. `parent_id` y la profundidad se calculan desde la pila: ```python with failproofai_sdk.session(): @@ -61,7 +61,7 @@ with failproofai_sdk.session(): ## Cómo se cierra un ámbito -`agent()` maneja las excepciones por ti: +`agent()` gestiona las excepciones por ti: | Qué ocurrió | Eventos | Resultado | | --- | --- | --- | @@ -70,11 +70,11 @@ with failproofai_sdk.session(): | `KeyboardInterrupt`, `SystemExit` | `error`, luego `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | solo `agent_end` | `cancelled` | -El error se emite antes de `agent_end`, porque el dashboard cierra el span en `agent_end` y cualquier cosa después no se atribuye a nada. Una cancelación no es un fallo, por lo que las ejecuciones canceladas no contaminan la superficie de errores. La excepción siempre se vuelve a lanzar: un ámbito nunca la suprime. +El error se emite antes de `agent_end`, porque el panel cierra el span en `agent_end` y cualquier cosa posterior no se atribuye a nada. Una cancelación no es un fallo, por lo que las ejecuciones canceladas no contaminan la superficie de errores. La excepción siempre se relanza: un ámbito nunca la suprime. ## Los métodos de evento -Quince métodos en seis familias. La mayoría vienen en pares — emites el apertura, luego el cierre, y el SDK mide el span entre ambos. +Quince métodos en seis familias. La mayoría vienen en pares: emites el abridor, luego el cierre, y el SDK mide el span entre ellos. | Familia | Abre | Cierra | Independiente | | --- | --- | --- | --- | @@ -87,7 +87,7 @@ Quince métodos en seis familias. La mayoría vienen en pares — emites el aper | **Fallos** | — | — | `error` | - Prefiere los ámbitos — `agent()` y `tool_call()` — siempre que encajen. Garantizan el evento de cierre incluso cuando el cuerpo lanza una excepción. Recurre a estos métodos directamente cuando tu flujo de control no anida, como una llamada a modelo dentro de una función auxiliar. + Prefiere los ámbitos — `agent()` y `tool_call()` — donde encajen. Garantizan el evento de cierre incluso cuando el cuerpo lanza una excepción. Recurre a estos métodos directamente cuando tu flujo de control no se anida, como una llamada a modelo dentro de un helper. @@ -146,13 +146,13 @@ failproofai_sdk.event.error( | Métodos | Significado | | --- | --- | | `human_wait` / `human_input` | El **agente le preguntó a una persona** — una puerta de aprobación, una pregunta aclaratoria | - | `human_pause` / `human_interrupt` | **Una persona actuó sobre el agente** — un botón de parada, una pausa del operador | + | `human_pause` / `human_interrupt` | Una **persona actuó sobre el agente** — un botón de parada, una pausa de operador | - Ningún framework señaliza el segundo par, por lo que siempre te corresponde a ti emitirlo. + Ningún framework señaliza el segundo par, por lo que siempre es tuya la responsabilidad de emitirlo. - **Pasa `request_id` cuando las llamadas a modelos se ejecutan concurrentemente.** Sin él, las solicitudes y respuestas se emparejan en orden de llegada por agente — y las llamadas concurrentes se desemparejan, asociando cada respuesta con la solicitud equivocada. + **Pasa `request_id` cuando las llamadas al modelo se ejecuten de forma concurrente.** Sin él, las solicitudes y respuestas se emparejan en orden de llegada por agente, y las llamadas concurrentes se emparejan incorrectamente, asociando cada respuesta con la solicitud equivocada. ## Ejemplo @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # acotado; un bucle de agente sin límite es un bug en sí mismo + for _ in range(4): # acotado; un bucle de agente sin límite es un bug propio message = turn(messages) if not message.tool_calls: break @@ -204,8 +204,8 @@ with failproofai_sdk.session(): }) ``` -Eso produce los mismos seis tipos de eventos que te daría un adaptador. La versión -completa y ejecutable, con las definiciones de herramientas, se incluye en el repositorio del SDK bajo +Esto produce los mismos seis tipos de eventos que te daría un adaptador. La versión +ejecutable completa, con las definiciones de herramientas, se incluye en el repositorio del SDK bajo `docs/manual/examples/`. ## Hilos y async @@ -223,13 +223,13 @@ threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Sin `propagate()`, los eventos del worker lanzan un `TypeError` que indica la solución en lugar de llegar a ninguna sesión. Esto es deliberado: un evento sin sesión es omitido por la ingesta y respondido con `200`, que es el fallo silencioso que la capa de identidad existe para prevenir. +Sin `propagate()`, los eventos del worker lanzan un `TypeError` que indica la corrección en lugar de terminar sin sesión. Esto es deliberado: un evento sin sesión es omitido por el ingest y respondido con `200`, que es el fallo silencioso que la capa de identidad existe para prevenir. ## Instrumentar un framework sin adaptador -Todo framework de agentes te da los mismos tres puntos de enganche. Mapéalos y tendrás un trace completo — los cuatro adaptadores incluidos no hacen nada más que esto. +Cada framework de agentes te ofrece los mismos tres puntos de enganche. Mapéalos y tendrás una traza completa — los cuatro adaptadores incluidos no hacen nada más que esto. -| El punto de enganche | Lo que escribes | Lo que llega | +| El punto de enganche | Lo que escribes | Lo que resulta | | --- | --- | --- | | La ejecución | `session()` + `agent()` | `agent_start`, `agent_end` | | Cada herramienta | `tool_call()` | `tool_use`, `tool_result` | @@ -244,7 +244,7 @@ Todo framework de agentes te da los mismos tres puntos de enganche. Mapéalos y ``` - En lo que sea que el framework llame wrapper de herramienta o middleware. + En lo que el framework llame wrapper de herramienta o middleware. ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -270,27 +270,27 @@ Todo framework de agentes te da los mismos tres puntos de enganche. Mapéalos y - **Lo manual y lo automático se componen.** Un adaptador ejecutándose dentro de un ámbito escrito a mano se une a esa sesión y toma ese agente como padre, de modo que obtienes un solo árbol en lugar de dos — útil cuando instrumentas un framework tú mismo junto a uno compatible. + **Manual y automático se combinan.** Un adaptador que se ejecuta dentro de un ámbito escrito a mano se une a esa sesión y se convierte en hijo de ese agente, de modo que obtienes un único árbol en lugar de dos — útil cuando instrumentas un framework tú mismo junto a uno soportado. - + Dos razones, y los tres puntos de enganche anteriores son la respuesta a ambas: - - `autogen-core` no ha tenido mantenimiento desde septiembre de 2025. - - AG2 no expone ningún punto de registro a nivel de proceso equivalente a los hooks de los otros frameworks, por lo que instrumentarlo implica envolver cada agente en cada lugar donde se construye. + - `autogen-core` no tiene mantenimiento desde septiembre de 2025. + - AG2 no expone ningún punto de registro a nivel de proceso equivalente a los hooks de los otros frameworks, por lo que instrumentarlo significa envolver cada agente en cada punto de construcción. Mapear los puntos de enganche a mano registra los mismos eventos, con la misma fidelidad, que un adaptador incluido. -## Más a fondo +## Profundizando -Cómo funciona realmente el registro. Nada de esto es necesario para empezar. +Cómo funciona la grabación realmente. Nada de esto es necesario para empezar. - + -Cada registro tiene la misma forma: se abre un span, el trabajo se anida dentro de él, y cada evento de apertura recibe uno de cierre. +Toda grabación tiene la misma forma: un span se abre, el trabajo se anida dentro, y cada evento de apertura recibe uno de cierre. ```mermaid flowchart LR @@ -302,9 +302,9 @@ flowchart LR C --> E(["agent_end"]) ``` -El **par** es la unidad. Cada evento de cierre lleva una duración que el SDK mide desde el evento de apertura correspondiente. +El **par** es la unidad. Cada evento de cierre lleva una duración que el SDK mide desde el de apertura. -A continuación se muestra una ejecución real por framework — capturada de los ejemplos incluidos con el SDK, con el nombre del modelo normalizado. Observa cuánto se obtiene de una sola llamada. +A continuación se muestra una ejecución real por framework — capturada de los ejemplos que se incluyen con el SDK, con el nombre del modelo normalizado. Fíjate en cuánto se obtiene de una sola llamada. @@ -342,7 +342,7 @@ A continuación se muestra una ejecución real por framework — capturada de lo 10 +5.739s agent_end crew · success ``` - El `role` de cada agente se convierte en el nombre de su span, de modo que la latencia y el consumo de tokens se desglosan por rol. + El `role` de cada agente se convierte en su nombre de span, por lo que la latencia y el gasto en tokens se desglosan por rol. @@ -390,34 +390,34 @@ A continuación se muestra una ejecución real por framework — capturada de lo 6 +0.000s agent_end main · success ``` - Tú emites estos tú mismo. Los mismos tipos de eventos, la misma fidelidad — a cambio de los puntos de llamada. + Los emites tú mismo. Los mismos tipos de eventos, la misma fidelidad — te cuesta los puntos de llamada. - + **No existe un evento de fin de sesión.** Una sesión no es algo que cierras — es un grupo de eventos que comparten un `session_id`. -El estado se deriva de la forma del trace: +El estado se deriva de la forma de la traza: | Estado | Cuándo | | --- | --- | | `ongoing` | Al menos un span sigue abierto | -| `paused` | Un `agent_pause` no tiene `agent_resume` correspondiente | +| `paused` | Un `agent_pause` no tiene un `agent_resume` correspondiente | | `error` | Nada está abierto y al menos un evento falló | | `done` | Nada está abierto y nada falló | -Por tanto, una sesión termina cuando todos los pares están cerrados. Los adaptadores emiten `agent_end` por ti, y al desmontar cierran cualquier cosa que siga abierta y la marcan como incompleta — una ejecución con crash se resuelve como `done` con una brecha visible en lugar de quedarse colgada. +Por tanto, una sesión termina cuando todos los pares están cerrados. Los adaptadores emiten `agent_end` por ti, y al finalizar cierran todo lo que siga abierto y lo marcan como incompleto — una ejecución que se interrumpió se resuelve como `done` con un hueco visible en lugar de quedar colgada. - Por esto una sesión puede abarcar dos llamadas. Un `interrupt()` de LangGraph pausa la ejecución, el span raíz permanece deliberadamente abierto, y la llamada de reanudación lo cierra. Ambas llamadas son una sola sesión. + Por eso una sesión puede abarcar dos llamadas. Un `interrupt()` de LangGraph pausa la ejecución, el span raíz permanece deliberadamente abierto, y la llamada de reanudación lo cierra. Ambas llamadas son una sola sesión. - + `session_id` y `agent_id` son opcionales en todos los métodos de evento. Si se omiten, se resuelven desde el ámbito que los contiene: @@ -427,19 +427,19 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Pasarlos explícitamente también funciona y tiene precedencia. Sin nada vinculado y sin nada pasado, la llamada lanza un `TypeError` que indica la solución en lugar de emitir un evento sin sesión, que la ingesta omitiría respondiendo `200`. +Pasarlos explícitamente también funciona y tiene precedencia. Si no hay nada vinculado ni nada pasado, la llamada lanza un `TypeError` que indica la corrección en lugar de emitir un evento sin sesión, que el ingest omitiría respondiendo con `200`. -Los ámbitos vinculan la identidad en variables de contexto. Estas se propagan automáticamente a las tareas de asyncio pero no a nuevos hilos — envuelve un worker en `failproofai_sdk.propagate()`. +Los ámbitos vinculan la identidad en variables de contexto. Estas se propagan automáticamente a las tareas de asyncio pero no a los nuevos hilos — envuelve un worker en `failproofai_sdk.propagate()`. #### Quién genera cada id | Id | Generado por | Notas | | --- | --- | --- | -| `session_id` | Tú, o el SDK | `session("chat-42")` se usa literalmente; si se omite, el SDK genera un `uuid4().hex` | +| `session_id` | Tú, o el SDK | `session("chat-42")` se usa tal cual; si se omite, el SDK genera un `uuid4().hex` | | `agent_id` | Tú, o el framework | De `agent("analyst")`, un `role` de CrewAI, un `FunctionAgent.name`. Un valor con aspecto de UUID es rechazado y reemplazado | -| `tool_call_id`, `hook_id`, `request_id` | Tú, o el framework | Los adaptadores reutilizan los ids de ejecución propios del framework, razón por la que los pares sobreviven a los cambios de hilo | -| **Event id** | **Cloud, en la ingesta** | El SDK no emite ninguno | -| **`dedup_key`** | **Cloud, en la ingesta** | Un hash de org, sesión, timestamp, tipo y payload. Esta es la identidad real — hace que un batch reintentado se colapse en lugar de duplicarse | +| `tool_call_id`, `hook_id`, `request_id` | Tú, o el framework | Los adaptadores reutilizan los ids de ejecución propios del framework, por eso los pares sobreviven a los saltos entre hilos | +| **Id de evento** | **Cloud, en el ingest** | El SDK no emite ninguno | +| **`dedup_key`** | **Cloud, en el ingest** | Un hash de org, sesión, timestamp, tipo y payload. Esta es la identidad real — hace que un lote reintentado colapse en lugar de duplicarse | #### Cómo los adaptadores resuelven `session_id` @@ -451,31 +451,31 @@ Gana la primera coincidencia: 4. Metadatos del framework 5. El id de ejecución propio del framework -Nunca se inventa mientras exista alguna de esas fuentes — un id sintetizado dividiría una ejecución entre varias sesiones. +Nunca se inventa mientras exista alguna de esas — un id sintetizado dividiría una ejecución en varias sesiones. #### Mantén `agent_id` con baja cardinalidad -Es la faceta principal en todas las vistas del dashboard, y una columna `LowCardinality(String)`. Un valor por ejecución degrada la columna y llena el desplegable de filtros con una entrada por ejecución. +Es la faceta principal en todas las superficies del panel, y una columna `LowCardinality(String)`. Un valor por ejecución degrada la columna y llena el desplegable de filtros con una entrada por ejecución. Los adaptadores protegen esa columna por ti: -| El framework entrega | Se registra como | Por qué | +| Lo que entrega el framework | Registrado como | Por qué | | --- | --- | --- | | `3f9a1c2b-…` (un UUID) | `main` | No hay nada legible que conservar | | Una cadena hexadecimal larga | `main` | Igual | | `agent-3f9a1c2b-…` | `agent` | Se elimina el id por ejecución, se conserva la parte legible | -| `agent-v2` | `agent-v2` | Los segmentos cortos se dejan como están | +| `agent-v2` | `agent-v2` | Los segmentos cortos se dejan tal cual | | `step-3` | `step-3` | Igual | El id real se conserva en `fw_agent_id` / `fw_run_id`, donde sigue siendo consultable sin ser una faceta. - **Esta protección solo afecta a las etiquetas que eligió el *framework*.** Un `agent_id` que pasas tú mismo — a `event.*` o a `failproofai_sdk.agent(...)` — se registra exactamente como se da. Reescribir silenciosamente un argumento explícito sería peor que la cardinalidad que previene, así que ponle nombres apropiados a tus propios spans. + **Esta protección solo afecta a las etiquetas que eligió el *framework*.** Un `agent_id` que pasas tú mismo — a `event.*`, o a `failproofai_sdk.agent(...)` — se registra exactamente como se dio. Reescribir silenciosamente un argumento explícito sería peor que la cardinalidad que previene, así que nombra tus propios spans en consecuencia. - + | Grupo | Eventos | | --- | --- | @@ -486,25 +486,25 @@ El id real se conserva en `fw_agent_id` / `fw_run_id`, donde sigue siendo consul | Humanos | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | Fallos | `error` | -Qué registra cada framework, medido a partir de las ejecuciones anteriores: +Qué registra cada framework, medido desde las ejecuciones anteriores: | Evento | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | -| Agent start y end | Sí | Sí | Sí | Sí | Tú | -| Model request y response | Sí | Sí | Sí | Sí | Tú | -| Tool use y result | Sí | Sí | Sí | Sí | Tú | -| Hook triggered y completed | Nodo | Tarea | Paso | — | Tú | +| Inicio y fin de agente | Sí | Sí | Sí | Sí | Tú | +| Solicitud y respuesta de modelo | Sí | Sí | Sí | Sí | Tú | +| Uso y resultado de herramienta | Sí | Sí | Sí | Sí | Tú | +| Hook disparado y completado | Nodo | Tarea | Paso | — | Tú | | Error | Sí | Sí | Sí | Sí | Automático | -| Human wait y input | Sí | Sí | Sí | — | Tú | -| Agent pause y resume | Sí | Sí | Sí | — | Tú | +| Espera e input humano | Sí | Sí | Sí | — | Tú | +| Pausa y reanudación de agente | Sí | Sí | Sí | — | Tú | -Un guión significa que el framework no tiene ese concepto. `human_pause` y `human_interrupt` describen a una *persona* actuando sobre el agente, lo que ningún framework señaliza — emítelos tú mismo. +Un guion indica que el framework no tiene ese concepto. `human_pause` y `human_interrupt` describen a una *persona* actuando sobre el agente, algo que ningún framework señaliza — emítelos tú mismo. -Un evento nunca llega solo. Uno abre un span, otro lo cierra, y el evento de cierre lleva una duración que el SDK mide desde el evento de apertura. +Un evento nunca llega solo. Uno abre un span, otro lo cierra, y el evento de cierre lleva una duración que el SDK mide desde el de apertura. | Abre | Cierra | El evento de cierre lleva | | --- | --- | --- | @@ -516,40 +516,40 @@ Un evento nunca llega solo. Uno abre un span, otro lo cierra, y el evento de cie | `human_wait` | `human_input` | la respuesta y cuánto tardó la persona | - Un evento de apertura sin evento de cierre es un span que nunca termina. La sesión se muestra como aún en ejecución, para siempre, y su duración activa sigue creciendo. Este es el modo de fallo a vigilar cuando instrumentas a mano. + Un evento de apertura sin uno de cierre es un span que nunca termina. La sesión se muestra como aún en ejecución, para siempre, y su duración activa sigue creciendo. Este es el modo de fallo que hay que vigilar cuando se instrumenta a mano. #### Reglas de correlación -- Reutiliza el mismo `tool_call_id`, `hook_id`, `pause_id` o `input_id` para el evento de completación correspondiente. +- Reutiliza el mismo `tool_call_id`, `hook_id`, `pause_id` o `input_id` para el evento de completado correspondiente. - El SDK calcula `duration_ms` para `tool_result`, `hook_completed`, `agent_resume` y `human_input`. Pasarlo a esos métodos lanza `ValueError`. -- `duration_ms` **sí** se acepta en `model_response`, porque solo el llamador conoce la latencia real del proveedor. Debe ser un entero — un float lanza `ValueError` en el punto de llamada, porque el servidor lee la columna como un entero sin signo de 32 bits y almacenaría NULL para cualquier otro tipo. -- Las claves de correlación tienen como ámbito el tipo y la sesión, por lo que una llamada a herramienta y un hook pueden compartir un id de forma segura, y dos sesiones concurrentes pueden reutilizar los mismos ids sin colisiones. No tienen como ámbito el agente: un par abierto bajo un agente y cerrado bajo otro sigue correlacionándose, que es el caso habitual en frameworks multi-agente. -- `request_id` empareja `model_request` con `model_response`. Sin él, los eventos de modelo se emparejan en orden por agente, de modo que las llamadas concurrentes se desemparejan. -- Un par dividido entre procesos sigue correlacionándose en destino, pero el SDK no puede calcular su duración en proceso. -- El mapa de pendientes admite como máximo 10.000 inicios y desaloja la entrada más antigua cuando se llena. +- `duration_ms` **sí** se acepta en `model_response`, porque solo el llamador conoce la latencia real del proveedor. Debe ser un entero — un float lanza `ValueError` en el punto de llamada, porque el servidor lee la columna como un entero de 32 bits sin signo y almacenaría NULL para cualquier otro valor. +- Las claves de correlación tienen ámbito por tipo y sesión, por lo que una llamada a herramienta y un hook pueden compartir un id sin problemas, y dos sesiones concurrentes pueden reutilizar los mismos ids sin colisionar. No tienen ámbito por agente: un par abierto bajo un agente y cerrado bajo otro sigue correlacionando, que es el caso habitual en frameworks multi-agente. +- `request_id` empareja `model_request` con `model_response`. Sin él, los eventos de modelo se emparejan en orden por agente, por lo que las llamadas concurrentes se emparejan incorrectamente. +- Un par dividido entre procesos sigue correlacionando en destino, pero el SDK no puede calcular su duración en proceso. +- El mapa de pendientes almacena como máximo 10.000 inicios y desaloja la entrada más antigua cuando se llena. - + -Instalar `failproofai-sdk` instala todo, incluyendo los cuatro adaptadores. Los extras instalan el **framework**, no el adaptador. +Instalar `failproofai-sdk` instala todo, los cuatro adaptadores incluidos. Los extras incorporan el **framework**, no el adaptador. ```python import failproofai_sdk # no carga nada fuera de la biblioteca estándar failproofai_sdk.instrument() # importa solo los adaptadores que realmente necesitas ``` -`import failproofai_sdk` es contractualmente de cero dependencias, verificado por una prueba que instala la wheel construida con `--no-deps` y otra que demuestra que ningún framework llega a `sys.modules`. +`import failproofai_sdk` es contractualmente sin dependencias, verificado por un test que instala la wheel compilada con `--no-deps` y otro que demuestra que ningún framework llega a `sys.modules`. - No existe el atributo `failproofai_sdk.crewai`. Los adaptadores no están expuestos deliberadamente en el paquete de nivel superior: acceder a uno importaría el framework como efecto secundario del acceso al atributo, rompiendo la promesa de cero dependencias. Usa `instrument()`. + No existe el atributo `failproofai_sdk.crewai`. Los adaptadores no se exponen deliberadamente en el paquete de nivel superior: acceder a uno importaría el framework como efecto secundario del acceso al atributo, rompiendo la promesa de cero dependencias. Usa `instrument()`. ```python failproofai_sdk.instrument() # todos los frameworks ya importados failproofai_sdk.instrument("crewai") # exactamente uno, por nombre -failproofai_sdk.uninstrument("crewai") # restaurarlo +failproofai_sdk.uninstrument("crewai") # deshacerlo ``` | Nombre | También acepta | @@ -559,7 +559,7 @@ failproofai_sdk.uninstrument("crewai") # restaurarlo | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -La detección automática lee `sys.modules`, no la lista de paquetes instalados, por lo que un framework que tienes instalado pero que nunca importaste no se instrumenta y nunca se importa en tu nombre. Para ver qué está conectado: +La detección automática lee `sys.modules`, no la lista de paquetes instalados, por lo que un framework que tienes instalado pero nunca has importado no se instrumenta y nunca se importa en tu nombre. Para ver qué está conectado: ```python from failproofai_sdk.integrations import active, available @@ -569,20 +569,20 @@ active() # ('langchain',) ``` - **`instrument("crewai")` en una máquina sin CrewAI no lanza una excepción.** Registra una advertencia y devuelve `()`, de modo que un framework que falta nunca derriba un proceso que también instrumenta otros. + **`instrument("crewai")` en una máquina sin CrewAI no lanza una excepción.** Registra una advertencia y devuelve `()`, por lo que un framework faltante nunca derrumba un proceso que también instrumenta otros. - La advertencia lleva el `ImportError` subyacente, y ese mensaje indica el comando de instalación exacto — así que la solución está en tus logs, no oculta. + La advertencia incluye el `ImportError` subyacente, y ese mensaje indica el comando de instalación exacto — así que la corrección está en tus logs, no oculta. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Establece `FAILPROOFAI_SDK_STRICT=1` para que lance una excepción en su lugar. Ese flag se lee **una vez y se cachea**, así que expórtalo antes de que tu proceso inicie en lugar de establecerlo a mitad de la ejecución. + Establece `FAILPROOFAI_SDK_STRICT=1` para que lance una excepción en su lugar. Ese flag se **lee una vez y se cachea**, así que expórtalo antes de que inicie tu proceso, no lo establezcas a mitad de ejecución. - **`instrument()` debe ir *después* de la importación de tu framework.** La detección automática lee `sys.modules`, por lo que una llamada vacía antes de la importación no encuentra nada, no instala nada y devuelve `()`. + **`instrument()` debe llamarse *después* de importar tu framework.** La detección automática lee `sys.modules`, por lo que una llamada sin argumentos antes del import no encuentra nada, no instala nada y devuelve `()`. @@ -594,7 +594,7 @@ import langchain # demasiado tarde, nada está conectado ``` ```python Right -import langchain # primero importa el framework +import langchain # importa el framework primero import failproofai_sdk failproofai_sdk.instrument() # lo encuentra -> ('langchain',) @@ -608,53 +608,55 @@ failproofai_sdk.instrument("langchain") ``` -Si te equivocas, el proceso se ejecuta con el SDK importado, el adaptador aparentemente instalado y **sin emitir ni un solo evento**. Registra una advertencia que dice exactamente eso — así que comprueba tus logs primero cuando una ejecución no registra nada. +Si te equivocas, el proceso se ejecuta con el SDK importado, el adaptador aparentemente instalado, y **sin emitir un solo evento**. Registra una advertencia que lo indica exactamente — así que comprueba tus logs primero cuando una ejecución no registra nada. - + ```mermaid flowchart LR A["Tu agente"] --> B["Adaptador"] B --> C["Writer
cola en memoria"] C -->|"cada 0.5s"| D["Spool
JSONL en disco"] - D --> E["Failproof daemon"] + D --> E["Daemon de Failproof"] E -->|"HTTPS"| F["Cloud"] ``` | Etapa | Función | Se ejecuta en | | --- | --- | --- | -| Adaptador | Traduce un callback del framework a uno de los 15 tipos de eventos | Tu proceso | -| Writer | Encola, agrupa y escribe JSONL atómicamente | Tu proceso, hilo en segundo plano | -| Spool | Handoff duradero, sobrevive a la salida de tu proceso | Disco local | -| Daemon | Vigila el spool, envía batches, elimina lo que envió | Tu máquina | -| Ingest | Asigna id de fila y clave de deduplicación, promueve columnas consultables | Cloud | +| Adaptador | Traduce un callback del framework en uno de los 15 tipos de evento | Tu proceso | +| Writer | Encola, agrupa y escribe JSONL atómicamente | Tu proceso, hilo de fondo | +| Spool | Transferencia durable, sobrevive a que tu proceso termine | Disco local | +| Daemon | Vigila el spool, envía lotes y elimina los enviados | Tu máquina | +| Ingest | Asigna un id de fila y clave de dedup, promueve columnas consultables | Cloud | -El spool es lo que hace esto seguro: tu agente nunca se bloquea en la red, y una interrupción de Cloud significa un directorio creciente en lugar de eventos perdidos. +El spool es lo que hace esto seguro: tu agente nunca bloquea esperando la red, y una interrupción de Cloud significa un directorio en crecimiento en lugar de eventos perdidos. -Cada flush escribe un archivo de batch, primero `.tmp`, luego `fsync`, luego un rename atómico: +Cada flush escribe un archivo de lote, primero como `.tmp`, luego `fsync`, luego un renombrado atómico: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -El daemon solo recoge `.jsonl`, por lo que nunca puede leer un archivo escrito a medias. El nombre lleva timestamp, id de proceso y número de secuencia, de modo que dos procesos que hagan flush en el mismo milisegundo no pueden colisionar. La cola tiene un límite de 10.000 eventos; a partir de ahí descarta el más antiguo y lo registra. +El daemon solo recoge `.jsonl`, por lo que nunca puede leer un archivo a medio escribir. El nombre lleva un timestamp, id de proceso y número de secuencia, por lo que dos procesos que hagan flush en el mismo milisegundo no colisionan. La cola tiene un límite de 10.000 eventos; a partir de ahí descarta los más antiguos y lo registra en el log. - **`collector.redact` tiene por defecto `minimal` también para los eventos del SDK.** El SDK limpia antes de escribir un batch en disco, y el daemon repite el mismo paso determinista antes de subir para que los batches de SDKs más antiguos estén protegidos. + **`collector.redact` no se aplica a los eventos de tu SDK.** Nunca los ve. -El daemon lee cada batch y aplica redacción en memoria antes de subir. No reescribe el archivo del spool que leyó. +El daemon **envía** tus lotes. No los abre ni los reescribe. -| Eventos | Escritos por | Dónde se ejecuta la redacción minimal | +| Eventos | Escritos por | ¿Redactados por `collector.redact`? | | --- | --- | --- | -| Transcripciones de sesión CLI | El daemon | Antes de que el daemon escriba el batch | -| Actividad de hooks | El daemon | Antes de que el daemon escriba el batch | -| **Todo lo que emite el SDK** | **Tu proceso** | **Antes de que el SDK escriba el batch y de nuevo antes de la subida del daemon** | +| Transcripciones de sesión CLI | El daemon | Sí | +| Actividad de hooks | El daemon | Sí | +| **Todo lo que emite el SDK** | **Tu proceso** | **No** | -Establece `collector.redact` en `off` solo cuando los payloads literales sean un requisito explícito; tanto el SDK como el daemon respetan esa configuración. La redacción minimal detecta claves de API comunes, tokens bearer, JWTs y asignaciones de secretos. No puede identificar texto sensible arbitrario. +La redacción se ejecuta donde el daemon *escribe* sus propios eventos — no donde se *envían* los lotes. Así que un prompt o un argumento de herramienta que contenga una clave API la conservará al llegar. + +Esto es deliberado. Estas son tus propias llamadas de instrumentación, y reescribirlas en tránsito significaría que los eventos que recibes no son los que emitiste. **Controlas los payloads en el origen, en dos lugares:** @@ -662,37 +664,37 @@ Establece `collector.redact` en `off` solo cuando los payloads literales sean un - Desactiva la captura de contenido en el adaptador. **El nombre de la opción varía, y un adaptador no tiene ninguna** — no es un único interruptor universal: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **sin interruptor de contenido**; `session_id` es la única opción que lee, por lo que prompts y completaciones siempre se registran. + - CrewAI — **sin interruptor de contenido en absoluto**; `session_id` es la única opción que lee, por lo que los prompts y las respuestas siempre se registran. - `instrument()` descarta las opciones que un adaptador no lee, por lo que pasar un nombre incorrecto no lanza nada ni cambia nada. - - Simplemente no pases el secreto a `input=` desde el principio. + `instrument()` descarta las opciones que un adaptador no lee, por lo que pasar el nombre incorrecto no lanza nada ni cambia nada. + - No pases el secreto a `input=` desde el principio. - `collector.redact` es defensa en profundidad, no un sustituto de ninguno de los dos. + `collector.redact` no es un sustituto de ninguna de las dos opciones. **Un directorio de spool vacío es el estado saludable.** No lo uses para verificar la entrega. -El daemon elimina cada batch en milisegundos tras enviarlo, por lo que un `ls` compite con el colector y muestra una fracción de lo que emitiste — indistinguible de un SDK que no registró nada. +El daemon elimina cada lote en milisegundos después de enviarlo, por lo que un `ls` compite con el collector y muestra una fracción de lo que emitiste — indistinguible de un SDK que no registró nada. -Para confirmar que los eventos realmente llegaron, comprueba el dashboard. Para ver cómo se llena el spool, detén primero el daemon. +Para confirmar que los eventos realmente llegaron, comprueba el panel. Para ver cómo se llena el spool, detén el daemon primero. - + -Cada callback se ejecuta dentro de un wrapper cuya única función es volver a lanzar, de modo que tu llamada está en exactamente un `try` y todo lo que hace el SDK ocurre fuera de él. +Cada callback se ejecuta dentro de un wrapper cuyo único trabajo es relanzar, por lo que tu llamada está en exactamente un `try` y todo lo que hace el SDK ocurre fuera de él. | Qué ocurre | Resultado | | --- | --- | | Un hook lanza una excepción | Se registra una vez con su traceback. Tu llamada no se ve afectada | -| El mismo hook lanza tres veces | Ese hook se desactiva para el resto del proceso, con una línea de error | -| Se establece `FAILPROOFAI_SDK_STRICT=1` | La excepción se vuelve a lanzar en su lugar | -| Una versión de framework está fuera del rango probado | Avisa una vez e instrumenta de todas formas | -| Falta una capacidad individual | Solo ese hook se desactiva, nunca el adaptador completo | +| El mismo hook lanza tres veces | Ese hook se deshabilita para el resto del proceso, con una línea de error | +| `FAILPROOFAI_SDK_STRICT=1` está establecido | La excepción se relanza en su lugar | +| Una versión del framework está fuera del rango probado | Avisa una vez, instrumenta de todas formas | +| Falta una sola capacidad | Ese hook se deshabilita, nunca el adaptador completo | -El comportamiento por defecto es el correcto en producción y el incorrecto al depurar, porque solo puede demostrar "no falló". Establece `FAILPROOFAI_SDK_STRICT=1` para que un fallo suprimido sea ruidoso. +El comportamiento por defecto es correcto en producción e incorrecto al depurar, porque solo puede demostrar que no se produjo un crash. Establece `FAILPROOFAI_SDK_STRICT=1` para hacer visible un fallo suprimido. @@ -702,7 +704,7 @@ El comportamiento por defecto es el correcto en producción y el incorrecto al d - Un evento de apertura no tiene cierre correspondiente: un `model_request` sin `model_response`, o un `tool_use` sin `tool_result`. Usa los ámbitos, que garantizan el par incluso cuando el cuerpo lanza una excepción. Si llamas a los métodos de evento directamente, usa `try` y `finally`. + Un evento de apertura no tiene uno de cierre: un `model_request` sin `model_response`, o un `tool_use` sin `tool_result`. Usa los ámbitos, que garantizan el par incluso cuando el cuerpo lanza una excepción. Si llamas a los métodos de evento directamente, usa `try` y `finally`. @@ -710,28 +712,28 @@ El comportamiento por defecto es el correcto en producción y el incorrecto al d - El hilo nunca heredó el contexto. Envuelve el callable en `failproofai_sdk.propagate()`. Ver [Hilos y async](#threads-and-async). + El hilo nunca heredó el contexto. Envuelve el callable en `failproofai_sdk.propagate()`. Consulta [Hilos y async](#threads-and-async). - Los campos extra se fusionan al final, por lo que uno con el nombre de un campo real como `model` o `outcome` lo sobreescribiría y cambiaría una columna almacenada. Ponle un namespace al tuyo; los adaptadores usan el prefijo `fw_`. + Los campos extra se fusionan al final, por lo que uno con el nombre de un campo real como `model` o `outcome` lo sobreescribiría y cambiaría una columna almacenada. Usa un espacio de nombres propio; los adaptadores utilizan el prefijo `fw_`. - `agent_id` es una faceta de baja cardinalidad y pusiste un id de ejecución en ella. Usa un nombre de rol o nodo y pon el id real en un campo del payload. + `agent_id` es una faceta de baja cardinalidad y pusiste un id de ejecución en ella. Usa un rol o nombre de nodo y guarda el id real en un campo del payload. -## Siguientes pasos +## Siguiente paso - Pares, ids, ciclo de vida de la sesión y entrega. + Pares, ids, ciclo de vida de sesión y entrega. - + Sigue la causalidad a través de la sesión que acabas de capturar. - + LangGraph, CrewAI, LlamaIndex y Pydantic AI. \ No newline at end of file diff --git a/docs/es/start/quickstart.mdx b/docs/es/start/quickstart.mdx index 862117a4..dc6de9f1 100644 --- a/docs/es/start/quickstart.mdx +++ b/docs/es/start/quickstart.mdx @@ -1,17 +1,17 @@ --- title: "Inicio rápido" -description: "Captura una sesión de agente, encuentra un fallo y empieza a prevenirlo." +description: "Captura una sesión del agente, encuentra un fallo y empieza a prevenirlo." icon: "zap" --- -Esta guía de inicio rápido permite que una máquina reporte sesiones, ejecuta una auditoría y despliega una política. Usa la habilidad para configurar Failproof o sigue los pasos manuales. +Este inicio rápido conecta una máquina para reportar sesiones, ejecuta una auditoría e implementa una política. Usa la skill para configurar Failproof, o sigue los pasos manuales. -**¿Cuál es tu camino?** Si tu agente corre en uno de los 12 [harnesses](/es/reference/harnesses) soportados — una CLI de codificación o una pasarela como Hermes u OpenClaw — sigue los pasos a continuación; necesitas Node.js 20.9 o superior. Si tu agente no tiene harness, instrumenta con el [SDK de Python](/es/reference/custom-agents) para trazabilidad y auditorías, y luego continúa en [Ejecuta tu primera verificación de fallos](/es/start/first-audit); la aplicación de políticas en esa ruta requiere un hook en tu entorno de ejecución. +**¿Cuál es tu camino?** Si tu agente se ejecuta en uno de los 12 [harnesses](/es/reference/harnesses) compatibles — una CLI de programación, o una gateway como Hermes o OpenClaw — sigue los pasos a continuación; necesitas Node.js 20.9 o posterior. Si tu agente no tiene harness, instrumentalo con el [SDK de Python](/es/reference/custom-agents) para trazas y auditorías, y luego únete en [Ejecuta tu primera comprobación de fallos](/es/start/first-audit); la aplicación de políticas en esa ruta requiere un hook en tu runtime. - + - + ```bash npx skills add FailproofAI/skills ``` @@ -21,7 +21,7 @@ Esta guía de inicio rápido permite que una máquina reporte sesiones, ejecuta Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Tu agente inspecciona el proyecto, elige la integración relevante, realiza la configuración y la verifica. Consulta el [repositorio de habilidades de FailproofAI](https://github.com/FailproofAI/skills) para ver habilidades individuales y opciones de instalación avanzadas. + Tu agente inspecciona el proyecto, elige la integración adecuada, realiza la configuración y la verifica. Consulta el [repositorio de skills de FailproofAI](https://github.com/FailproofAI/skills) para ver skills individuales y opciones de instalación avanzadas. @@ -29,25 +29,31 @@ Esta guía de inicio rápido permite que una máquina reporte sesiones, ejecuta ## Antes de empezar 1. Abre el [panel de Failproof AI](https://app.befailproof.ai) y crea una cuenta o inicia sesión con tu correo de trabajo. -2. Ve a **Administration → Keys** y crea una clave con `events:add` y `policies:pull`. -3. Copia el secreto de un solo uso y guárdalo en la máquina de destino: +2. Ve a **Administración → Claves** y crea una clave con `events:add` y `policies:pull`. +3. Copia el secreto de un solo uso, luego léelo en una shell en la máquina de destino. `read -s` lo captura en un prompt que no muestra lo que escribes, así nunca aparece en un comando: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` - ## Instalación + ## Instalar ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - Las transcripciones de sesiones se envían por defecto. Añade `--no-transcripts` para reportar actividad de hooks y decisiones de políticas sin el contenido de las transcripciones. + Ese único comando es toda la configuración: instala el daemon local (una vez como root), conecta los hooks en cada CLI de agente que encuentre, y conecta esta máquina a Cloud. Pasar la clave a través del entorno en lugar de `--token` evita que aparezca en `ps`, donde cualquier usuario de la máquina puede leer los argumentos de un comando. Eso no evita que quede en el historial de la shell — leerla con `read -s` es lo que hace eso. En CI, inyéctala como un secreto enmascarado y mantén el rastreo de shell (`set -x`) desactivado, o la traza la imprimirá. - Si esta máquina ya tiene historial de agente, previsualiza e importa los últimos siete días, luego espera a que finalice la entrega. Omite este paso en una máquina nueva. + Los transcritos de sesión se envían por defecto. Agrega `--no-transcripts` para reportar la actividad de hooks y las decisiones de políticas sin el contenido de los transcritos. + + + No uses `failproofai config --connect ` aquí. Esa opción registra una máquina que **ya** está configurada y retorna inmediatamente — sin daemon, sin hooks — por lo que la máquina aparecería en Cloud sin recopilar ni aplicar nada. + + + Si esta máquina ya tiene historial de agentes, previsualiza e importa los últimos siete días, luego espera a que finalice la entrega. Omite este paso en una máquina nueva. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +61,41 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Abre **Sessions** en Failproof AI y selecciona una sesión importada. + Abre **Sesiones** en Failproof AI y selecciona una sesión importada. - - Esto conecta Failproof AI a tu harness e instala las 39 políticas integradas. Úsalas para ver las decisiones de políticas locales y probar la aplicación antes de que Failproof AI audite tus sesiones y escriba políticas para tus agentes. + + El paso anterior ya conectó los hooks en cada CLI de agente que detectó. Vuelve a ejecutarlo para un harness específico cuando lo necesites, o para agregar un harness instalado después. Cada uno de los 12 es un valor válido para `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + ```bash + failproofai policies --install --cli claude --scope user # una CLI de programación + failproofai policies --install --cli hermes --scope user # una gateway de Slack/Telegram + ``` - Deja que el instalador detecte tu harness, o especifica uno explícitamente. Cualquiera de los 12 es un valor válido para `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + El bloqueo de una llamada de herramienta antes de ejecutarse está verificado en los 12. Las compuertas al final del turno están verificadas en 8 — consulta la [capacidad de aplicación](/es/reference/harnesses#enforcement-capability) para ver la matriz por harness. + + + Conectar los hooks no habilita ninguna política. La configuración no elige ninguna deliberadamente — esa decisión es tuya — así que toma un pack: ```bash - failproofai policies --install --cli claude --scope user # una CLI de codificación - failproofai policies --install --cli hermes --scope user # una pasarela de Slack/Telegram + failproofai policies add FailproofAI/policies ``` - Bloquear una llamada a herramienta antes de que se ejecute está verificado en los 12. Las compuertas de fin de turno están verificadas en 8 — consulta la [capacidad de aplicación](/es/reference/harnesses#enforcement-capability) para ver la matriz por harness. + El pack se obtiene desde su release de GitHub, se verifica su checksum y se fija al tag exacto que resolvió. Incluye 38 políticas y activa las 10 que su manifiesto marca como seguras para habilitar sin supervisión. Úsalas para ver las decisiones de políticas locales y probar la aplicación antes de que Failproof AI audite tus sesiones y escriba políticas para tus agentes. + + Lee cualquier pack antes de tomarlo con `failproofai policies show /`, y consulta [packs de políticas](/es/policies/packs) para tomar solo una parte de uno. + + Hasta que esto se ejecute, lo único que se aplica es `block-failproofai-commands` — el guard siempre activo que impide que un agente desactive Failproof AI. `failproofai policies` lista lo que está activo. - Sigue [Ejecuta tu primera verificación de fallos](/es/start/first-audit). Usa un objetivo concreto como "encuentra sesiones donde el agente reintentó una herramienta fallida sin cambiar su enfoque". + Sigue [Ejecuta tu primera comprobación de fallos](/es/start/first-audit). Usa un objetivo concreto como "encontrar sesiones donde el agente reintentó una herramienta fallida sin cambiar su enfoque". - - Sigue [Previene tu primer fallo con una política](/es/start/first-policy). Comienza en modo de observación, inspecciona las coincidencias y luego aplica la versión revisada. + + Sigue [Prevén tu primer fallo con una política](/es/start/first-policy). Comienza en modo de observación, inspecciona las coincidencias, luego aplica la versión revisada. - Ejecuta `failproofai config --status`. Una configuración saludable reporta la conexión a la nube, el estado del daemon y si la aplicación de políticas está en pausa. + Ejecuta `failproofai config --status`. Una configuración saludable reporta la conexión a cloud, el estado del daemon y si la aplicación está pausada. \ No newline at end of file diff --git a/docs/es/start/setup.mdx b/docs/es/start/setup.mdx index 78eb6afb..d65d55ec 100644 --- a/docs/es/start/setup.mdx +++ b/docs/es/start/setup.mdx @@ -6,63 +6,84 @@ icon: "waypoints" - Instala hooks y políticas en una máquina. Úsalo cuando necesites controles inmediatos sin enviar datos de sesión a la nube. + Configura una máquina sin clave de Cloud y aplica un paquete de políticas. Úsalo cuando necesites protecciones inmediatas sin enviar datos de sesión a Cloud. - Añade sesiones centralizadas, auditorías, evaluaciones en línea, paneles de control, alertas e implementación de políticas para toda la flota. + Agrega sesiones centralizadas, auditorías, evaluaciones en línea, paneles de control, alertas y despliegue de políticas para toda la flota. - Usa controles organizativos, claves con ámbito restringido, infraestructura privada y requisitos de seguridad específicos de cada implementación. + Usa controles organizacionales, claves con alcance restringido, infraestructura privada y requisitos de seguridad específicos del despliegue. -## Ruta de producción recomendada +## Aplicar localmente + +Ejecuta `failproofai config` sin una clave y luego aplica un paquete con `failproofai policies add FailproofAI/policies`. En una terminal, selecciona **Not now — stay local** cuando la configuración pregunte si deseas conectarte a Cloud; si no hay terminal y no existe `FAILPROOFAI_CLOUD_TOKEN`, el sistema permanece en modo local automáticamente. El demonio y los hooks aplican las políticas en la máquina y no se envían datos de sesión a Cloud. Para conectarte más adelante, sigue los pasos a continuación. + +## Ruta recomendada para producción 1. Conecta una máquina que no sea de producción con la captura de transcripciones habilitada. -2. Verifica sesiones y evaluaciones en Cloud. -3. Crea una auditoría para un modo de fallo conocido. -4. Implementa la primera política en modo de observación. -5. Amplía a producción tras revisar coincidencias y falsos positivos. +2. Verifica las sesiones y evaluaciones en Cloud. +3. Crea una auditoría para un caso de fallo conocido. +4. Despliega la primera política en modo de observación. +5. Extiende a producción después de revisar las coincidencias y los falsos positivos. ## Conectar una máquina a Cloud - 1. Ve a **Administración → Claves** y crea una clave con `events:add` y `policies:pull`. + 1. Ve a **Administración → Claves** y crea una clave con los permisos `events:add` y `policies:pull`. 2. Copia el secreto de un solo uso en la máquina de destino. - 3. Tras ejecutar el comando de conexión de la CLI, ve a **Admin → aplicación** y confirma que la máquina aparece. - 4. Ve a **Observar → Eventos** y confirma que llega su primer evento. + 3. Después de ejecutar el comando de conexión de la CLI, ve a **Admin → enforcement** y confirma que la máquina aparece. + 4. Ve a **Observe → Events** y confirma que llega su primer evento. - El panel de clave muestra los dos permisos que necesita una máquina conectada: ingesta de eventos y entrega de políticas. + El panel de claves muestra los dos permisos necesarios para una máquina conectada: ingesta de eventos y entrega de políticas. - ![El panel de nueva clave de API utilizado para conceder permisos de ingesta de eventos y entrega de políticas.](/images/dashboard/key-create.png) + ![El panel de nueva clave API utilizado para otorgar permisos de ingesta de eventos y entrega de políticas.](/images/dashboard/key-create.png) - Tras la conexión, la máquina debería aparecer en la sección de aplicación con el estado de política deseado y el estado de implementación. + Tras la conexión, la máquina debería aparecer en enforcement con su estado de política deseado y reportado. - ![La flota de aplicación con una máquina registrada desplegada para mostrar su estado de política deseado y el estado de implementación.](/images/dashboard/enforcement-fleet.png) + ![La flota de Enforcement con una máquina inscrita expandida para mostrar su estado de política deseado y el estado del despliegue.](/images/dashboard/enforcement-fleet.png) - El primer evento que llega confirma que el daemon puede enviar datos a Cloud, independientemente de la implementación de políticas. + El primer evento que llega confirma que el demonio puede enviar datos a Cloud, de forma independiente al despliegue de políticas. - ![El flujo de eventos en directo que muestra eventos recientes de agente, modelo y herramienta.](/images/dashboard/events-stream-current.png) + ![El flujo de eventos en vivo que muestra los eventos recientes de agentes, modelos y herramientas.](/images/dashboard/events-stream-current.png) - Continúa solo cuando tanto la máquina como su primer evento sean visibles. + Continúa solo después de que tanto la máquina como su primer evento sean visibles. + Lee el secreto de un solo uso en el shell. `read -s` lo solicita en un prompt que no muestra el texto, por lo que nunca aparece en un comando ni en el historial del shell: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Luego configura la máquina, elige sus políticas y asígnale un nombre: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` - Añade `--no-transcripts` cuando el contenido de las transcripciones deba permanecer en local. + `failproofai config` realiza toda la configuración: el demonio, los hooks para cada CLI de agente que encuentre y la conexión a Cloud; luego no selecciona ninguna política, que es para lo que sirve el segundo comando. + + La etiqueta se asigna **después** de conectarse, no durante el proceso: `failproofai config --machine-label ` renombra una máquina que ya está conectada; en una que no lo está, no hace nada salvo informarlo. + + Agrega `--no-transcripts` cuando el contenido de las transcripciones deba permanecer local. + + En CI, establece `FAILPROOFAI_CLOUD_TOKEN` desde el almacén de secretos en lugar de usar `read -s`, y mantén el rastreo del shell (`set -x`) desactivado; de lo contrario, el rastreo imprimirá la clave. + + + En una máquina que **ya** está configurada, `failproofai config --connect ` solo la inscribe y nada más. No uses esa forma para una instalación inicial: retorna antes de que el demonio o cualquier hook estén en funcionamiento, dejando una máquina que aparece en Cloud pero que no recopila ni aplica nada. + -La conexión a Cloud verifica la ingesta de eventos y la entrega de políticas de forma independiente. Por ello, una clave puede ser válida pero carecer de algún permiso requerido. Usa `failproofai config --status` para ver qué capacidad está configurada. +La conexión a Cloud verifica la ingesta de eventos y la entrega de políticas de forma independiente. Por lo tanto, una clave puede ser válida pero carecer de uno de los permisos necesarios. Usa `failproofai config --status` para ver qué capacidades están configuradas. - La configuración de Cloud escribe las credenciales locales solo después de que la capacidad correspondiente se complete correctamente. Una verificación fallida no deja una máquina con apariencia de conectada cuando no lo está. + La configuración de Cloud escribe las credenciales locales solo después de que la capacidad correspondiente se verifica correctamente. Una verificación fallida no deja la máquina con apariencia de estar conectada cuando no lo está. \ No newline at end of file diff --git a/docs/fr/admin/keys-and-permissions.mdx b/docs/fr/admin/keys-and-permissions.mdx index 9f384110..7deb3521 100644 --- a/docs/fr/admin/keys-and-permissions.mdx +++ b/docs/fr/admin/keys-and-permissions.mdx @@ -4,26 +4,26 @@ description: "Créez des clés API à portée limitée pour les machines, l'auto icon: "key-round" --- -Les clés API appartiennent à une organisation et disposent de permissions explicites. Utilisez des clés séparées pour l'ingestion des agents, la distribution des politiques, les évaluateurs, l'automatisation CI et les scripts d'administration. +Les clés API appartiennent à une organisation et portent des permissions explicites. Utilisez des clés distinctes pour l'ingestion des agents, la distribution des politiques, les évaluateurs, l'automatisation CI et les scripts d'administration. -## Créer et faire tourner une clé +## Créer et renouveler une clé - 1. Accédez à **Administration → Clés**, sélectionnez **nouvelle clé** et saisissez un nom de charge de travail. + 1. Allez dans **Administration → Clés**, sélectionnez **nouvelle clé** et entrez un nom de charge de travail. 2. Choisissez un ensemble de permissions et ajustez les permissions individuelles uniquement si le préréglage est insuffisant. 3. Créez la clé et copiez immédiatement son secret à usage unique. 4. Ouvrez la clé ultérieurement pour mettre à jour les autorisations, la désactiver ou régénérer le secret. - Le panneau de création vous permet de choisir les autorisations les plus restreintes requises par la charge de travail. + Le panneau de création est l'endroit où vous choisissez les autorisations les plus restreintes requises par la charge de travail. ![Le panneau de création de clé API avec les préréglages de permissions et les autorisations individuelles.](/images/dashboard/key-create.png) - Après la création, la page Clés affiche les métadonnées persistantes et les actions de gestion. Le secret à usage unique n'est plus affiché ensuite. + Après la création, la page Clés affiche les métadonnées persistantes et les actions de gestion. Le secret à usage unique n'est plus affiché. - ![La page Clés API affichant les permissions, la date de création, ainsi que les actions de régénération et de désactivation.](/images/dashboard/api-keys.png) + ![La page Clés API affichant les permissions des clés, l'heure de création, ainsi que les actions de régénération et de désactivation.](/images/dashboard/api-keys.png) - Utilisez cette liste pour examiner régulièrement les autorisations et désactiver les clés qui ne correspondent plus à une charge de travail active. + Utilisez cette liste pour revoir régulièrement les autorisations et désactiver les clés qui ne correspondent plus à une charge de travail active. ```bash @@ -36,16 +36,16 @@ Les clés API appartiennent à une organisation et disposent de permissions expl fp keys disable production-agents ``` - Redirigez ou capturez de manière sécurisée la sortie des commandes create/regenerate ; le secret n'est retourné qu'une seule fois. + Redirigez ou capturez de manière sécurisée la sortie des commandes create/regenerate ; le secret est retourné une seule fois. Les deux permissions requises par une machine Failproof AI connectée sont indépendantes : -- `events:add` envoie les événements et les données de session. +- `events:add` envoie des événements et des données de session. - `policies:pull` récupère les déploiements de politiques assignés. -Les secrets de clé sont affichés lors de leur création ou régénération. Stockez-les dans un gestionnaire de secrets et faites-les tourner sans réutiliser les identifiants interactifs d'un opérateur. +Les secrets de clé sont affichés lors de leur création ou régénération. Stockez-les dans un gestionnaire de secrets et renouvelez-les sans réutiliser les identifiants interactifs d'un opérateur. ## Catalogue des permissions @@ -54,7 +54,7 @@ Les secrets de clé sont affichés lors de leur création ou régénération. St | Événements | `events:add`, `events:read` | | Clés | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate` ; `keys:update` est réservé aux sessions humaines | | Utilisateurs | `users:create`, `users:read`, `users:update`, `users:delete` | -| Évaluations | `evaluations:read`, `evaluations:trigger` | +| Évaluations | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | | Tableaux de bord | `dashboards:read`, `dashboards:write`, `dashboards:delete` | | Requêtes | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | | Assistant | `agent:use` | @@ -65,9 +65,9 @@ Les secrets de clé sont affichés lors de leur création ou régénération. St | Politiques | `policies:read`, `policies:write`, `policies:pull` | | Utilisation | `usage:read` | -`orgs:admin` est réservé à l'opérateur de l'instance et ne peut pas être accordé à une clé d'organisation ni à un membre ordinaire. Les jetons `incidents:*` et `alerts:ack` retirés sont acceptés par compatibilité et sont normalisés vers les permissions `issues:*` actuelles. +`orgs:admin` est réservé à l'opérateur de l'instance et ne peut pas être accordé à une clé d'organisation ou à un membre ordinaire. Les jetons `incidents:*` et `alerts:ack` retirés sont acceptés pour des raisons de compatibilité et sont normalisés vers les permissions `issues:*` actuelles. -Les ensembles de permissions intégrés sont `read-only`, `standard` et `admin`. `standard` ajoute le déclenchement des évaluations, l'exécution des requêtes, la gestion des problèmes et l'utilisation de l'assistant aux permissions de lecture. La création d'une clé supprime les autorisations réservées aux humains, même si un ensemble de permissions en contient. +Les ensembles de permissions intégrés sont `read-only`, `standard` et `admin`. `standard` ajoute aux permissions de lecture le déclenchement d'évaluations, l'exécution de requêtes, la gestion des problèmes et l'utilisation de l'assistant. La création d'une clé supprime les autorisations réservées aux humains, même si un ensemble de permissions les contient. Les clés à portée d'instance peuvent sélectionner une organisation via l'en-tête `X-AgentEye-Org`. Définissez-le explicitement sur les déploiements multi-organisations ; son omission peut entraîner la sélection de l'organisation par défaut. diff --git a/docs/fr/evaluations/deploy.mdx b/docs/fr/evaluations/deploy.mdx new file mode 100644 index 00000000..2d223ec2 --- /dev/null +++ b/docs/fr/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "Déployer et versionner une évaluation" +description: "Déployez une version immuable, consultez ce qui est en production, publiez de nouvelles versions, effectuez un rollback et notez des sessions existantes." +icon: "cloud-upload" +--- + +## Déployer + +Sélectionnez **deploy `@`** en bas de la page d'authoring. La version est immuable une fois publiée : à partir de ce moment, chaque session terminée à laquelle sa condition s'applique est notée par elle. + +## Voir ce qui est en production + +**Analyze → eval authoring** liste les définitions hébergées de votre organisation, c'est-à-dire les évaluations que l'évaluateur géré exécute pour elle. Chaque ligne affiche : + +- son nom, sa clé, sa version et son type de résultat +- son checksum source, qui permet de distinguer les révisions déployées sans ouvrir le code +- si elle est **conditionnelle** ou s'exécute sur **toutes les sessions terminées** — la condition est ce qui restreint une évaluation à des agents ou des environnements particuliers +- son timeout, ses labels et la date de sa dernière modification + +![La liste des définitions hébergées : nom, clé, version, type de résultat, checksum, timeout et périmètre de chaque évaluation, avec les options nouvelle version et activer ou désactiver.](/images/dashboard/eval-definitions.png) + +Recherchez dans la liste ou filtrez-la par état. Les évaluations enregistrées par votre propre worker ne sont pas listées ici ; leurs résultats portent un tag **customer** sur la [page des évaluations](/fr/sessions/evaluations), tandis que celles hébergées portent le tag **managed**. + +Une organisation peut avoir jusqu'à 100 évaluations hébergées différentes activées simultanément. + +## Publier une nouvelle version + +Sélectionnez **new version** sur une ligne. La page d'authoring s'ouvre avec le code de cette version ; modifiez-le, testez-le et déployez-le. Sa clé et son type de résultat sont conservés et ne peuvent pas être modifiés. + +La publication d'une version successeur désactive la version précédente et la conserve dans la liste. Les résultats gardent la version qui les a produits, de sorte qu'un graphique indique précisément quand la nouvelle logique a pris effet. + +## Effectuer un rollback + +Sélectionnez **disable** sur la version actuelle et **enable** sur celle que vous souhaitez restaurer. Rien n'est supprimé et chaque résultat reste tel qu'il était. + +## Arrêter une évaluation + +Sélectionnez **disable**. Sans version activée, l'évaluation cesse de s'exécuter sur les nouvelles sessions. Pour arrêter une évaluation que votre propre worker exécute, cessez de l'enregistrer : supprimez-la du worker ou arrêtez le worker. + +## Noter des sessions existantes + +L'exécution des évaluations se fait vers l'avant : une version déployée maintenant ne notera jamais une session qui s'est terminée avant son déploiement. Pour noter l'historique, ouvrez **score sessions you already have** sur la page d'authoring des évaluations, choisissez une fenêtre allant jusqu'à 90 jours et, optionnellement, une seule évaluation, puis comptez avant d'exécuter. Le comptage correspond exactement à ce qui sera exécuté, et chaque paire session-évaluation qu'il contient est une évaluation facturable. + +Ce mécanisme comble uniquement les lacunes. Une session qui possède déjà un résultat pour cette évaluation le conserve, et exécuter la même fenêtre deux fois ne note rien de nouveau. + +Pour noter à nouveau une session — après un correctif, ou pour une session qui ne s'est jamais terminée proprement — sélectionnez **re-evaluate** sur sa page. Le nouveau résultat est ajouté à l'historique de la session ; les résultats précédents sont conservés. + +## Permissions + +| Permission | Vous permet de | +| --- | --- | +| `evaluations:read` | Voir les résultats et ouvrir la page d'authoring des évaluations | +| `evaluations:trigger` | Voir, déployer, versionner, activer et désactiver les définitions hébergées ; les tester ; noter l'historique ; réévaluer une session | +| `events:read` | Tester sur des sessions réelles et ancrer les brouillons dans vos clés de payload, en complément de `evaluations:trigger` | +| `evaluations:run` | Exécuter votre propre worker d'évaluateur | \ No newline at end of file diff --git a/docs/fr/evaluations/overview.mdx b/docs/fr/evaluations/overview.mdx new file mode 100644 index 00000000..000cb875 --- /dev/null +++ b/docs/fr/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "Évaluer les agents" +description: "Notez chaque session terminée avec des évaluations que vous définissez : vérifications Python hébergées, ou juges LLM dans votre propre worker." +icon: "gauge" +--- + +Une évaluation attribue une note à une session d'agent terminée. Lorsqu'une session se termine, chaque évaluation activée qui lui est applicable s'exécute et enregistre ses résultats, avec un raisonnement que vous pouvez consulter à côté de la trace : + +- un **score** de 0 à 1, éventuellement marqué comme réussi ou échoué +- une **métrique**, telle qu'un comptage, une durée ou un coût, avec son unité +- une **assertion**, qui a réussi ou non + +## Deux types d'évaluateur + +| | Python hébergé | Votre propre worker | +| --- | --- | --- | +| Rédigé | Dans le tableau de bord, sous **Analyze → eval authoring** | En Python, avec le [SDK Évaluateur](/fr/reference/evaluator-sdk) | +| S'exécute | Sur l'évaluateur géré de Failproof AI, dans un bac à sable | Sur votre infrastructure | +| Idéal pour | Vérifications déterministes basées sur du code | Juges LLM, appels de modèles, packages, secrets, accès réseau, traitement intensif | + +Le Python hébergé est volontairement minimaliste : une seule expression, sans imports, sans réseau. Tout ce qui nécessite un modèle — un juge LLM évaluant la pertinence d'une réponse, par exemple — s'exécute dans votre propre worker à la place. Aucun des deux types ne nécessite de connexion entrante : les workers récupèrent les sessions terminées et soumettent les résultats via HTTPS sortant. + +## Chaque organisation évalue ses propres agents + +Les évaluations appartiennent à l'organisation qui les définit. Chaque organisation sur une instance rédige les siennes — ses propres vérifications, conditions, seuils et libellés — les versionne et les déploie sans affecter les autres, et ne consulte que ses propres résultats. Filtrez ces résultats par agent, environnement, évaluation et période, ou interrogez l'assistant à leur sujet. + +## Du premier brouillon aux scores en production + + + + Décrivez ce que vous souhaitez mesurer et laissez l'assistant en rédiger une ébauche, ou écrivez-la vous-même. Voir [Rédiger une évaluation](/fr/evaluations/write). + + + Exécutez-la sur de vraies sessions avant sa mise en production ; rien n'est enregistré. Voir [Tester une évaluation](/fr/evaluations/test). + + + Déployez une version immuable, publiez de nouvelles versions à mesure qu'elle évolue, et revenez à une version antérieure si nécessaire. Voir [Déployer et versionner](/fr/evaluations/deploy). + + + Visualisez les scores dans le temps, comparez les agents et les environnements, et interrogez l'assistant. Voir [Consulter les résultats des évaluations](/fr/sessions/evaluations). + + + +L'évaluation s'applique en avance : une version déployée maintenant notera les sessions qui se termineront à partir de ce moment. Pour noter les sessions déjà existantes, [effectuez un remplissage rétrospectif](/fr/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file diff --git a/docs/fr/evaluations/test.mdx b/docs/fr/evaluations/test.mdx new file mode 100644 index 00000000..b72ad49e --- /dev/null +++ b/docs/fr/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "Tester une évaluation" +description: "Exécutez une évaluation sur vos vraies sessions avant de la déployer. Rien n'est enregistré." +icon: "flask-conical" +--- + +**Tester cette évaluation**, depuis la page de création, exécute le code sur vos vraies sessions dans la flotte d'évaluateurs sans le déployer. Rien n'est enregistré : un échec ici n'est qu'un aperçu, et le déploiement reste toujours possible. + + + + Sélectionnez **vérifier** pour compiler le code et la condition en tenant compte des règles du bac à sable, sans les exécuter sur aucune session. + + + Filtrez les sessions correspondantes par agent, environnement, période ou identifiant de session, puis sélectionnez jusqu'à 10. Incluez des sessions sur lesquelles l'évaluation devrait échouer ainsi que des sessions sur lesquelles elle devrait réussir. + + + Sélectionnez **exécuter sur N sessions**, puis lisez chaque ligne. + + + +| Ligne | Signification | +| --- | --- | +| **ok** | L'exécution s'est terminée. La ligne liste chaque score, métrique et assertion retournés, ainsi que la durée. | +| **ignorée** | La condition a retourné `False`, donc l'évaluation n'a pas été exécutée. Il s'agit d'un saut, pas d'un échec. | +| Échec | Elle a levé une exception, dépassé le délai ou utilisé quelque chose que le bac à sable refuse. La ligne l'indique, et **Corriger** transmet l'erreur à l'assistant lorsqu'il peut aider. | + +![Le panneau tester cette évaluation : trois sessions choisies par agent, deux ok et une ignorée car sa condition a retourné False.](/images/dashboard/eval-test.png) + +Un résultat cesse d'être à jour dès que vous modifiez le code ; il est alors grisé plutôt que réutilisé. \ No newline at end of file diff --git a/docs/fr/evaluations/write.mdx b/docs/fr/evaluations/write.mdx new file mode 100644 index 00000000..80b533af --- /dev/null +++ b/docs/fr/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "Écrire une évaluation" +description: "Décrivez ce que vous souhaitez mesurer et laissez l'assistant générer une évaluation Python hébergée, ou écrivez le code vous-même. Les juges LLM s'exécutent dans votre propre worker." +icon: "file-pen-line" +--- + +Les évaluations hébergées sont de petits scripts Python déterministes, écrits dans le tableau de bord et exécutés sur la flotte d'évaluateurs de Failproof AI. La logique plus lourde — un juge LLM, un package, un secret, un appel réseau — s'exécute plutôt dans [votre propre worker](#write-it-in-your-own-worker). + +## Générer une ébauche à partir d'une description + +1. Accédez à **Analyze → eval authoring** et sélectionnez **new eval**. +2. Décrivez ce que vous souhaitez mesurer en langage courant, ou choisissez **start from an example…**, puis sélectionnez **draft**. +3. Examinez les champs et le code généré, puis [testez-le](/fr/evaluations/test) et [déployez-le](/fr/evaluations/deploy). + +![La page d'authoring d'évaluation avec une ébauche générée : la description, les notes de l'assistant sur l'ébauche, ainsi que les champs name, key, version, result, timeout, labels et condition.](/images/dashboard/eval-authoring-draft.png) + +L'ébauche s'appuie sur les événements propres à votre organisation : la page lit les clés de payload que vos sessions ont transportées au cours des sept derniers jours, de sorte que le code utilise des clés qui existent réellement plutôt que des suppositions. Avant de vous remettre l'ébauche, l'assistant la teste sur jusqu'à cinq de vos sessions récentes, corrige tout ce qu'il peut prouver être cassé — jusqu'à trois itérations — et vérifie une fois que le code mesure bien ce que vous avez demandé. Soyez précis dans votre description : les prompts trop larges sont plus lents et peuvent expirer. Examinez le code dans tous les cas ; le déploiement n'est jamais bloqué. + +## Configurer les champs + +| Champ | Description | +| --- | --- | +| name | Ce que les utilisateurs voient. Modifiable ultérieurement | +| key | L'identifiant stable sous lequel ses résultats sont regroupés, par exemple `code_assistant_quality_gate` | +| version | Toute chaîne de version sans espaces, par exemple `1.0.0` | +| result | **score** (0 à 1), **metric** (un nombre avec une unité), ou **assertion** (réussie ou non) | +| timeout seconds | 30 par défaut. Le bac à sable arrête toute exécution individuelle à 60 secondes | +| labels | Jusqu'à 20, séparées par des virgules. Modifiable ultérieurement | +| condition | Facultatif. Une expression Python ; l'évaluation ne s'exécute que sur les sessions où elle vaut `True` | + +Utilisez la condition pour cibler une évaluation sur les agents et environnements auxquels elle est destinée : + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +La clé, la version, le type de résultat, la condition et le code sont immuables une fois déployés : pour en modifier l'un d'eux, publiez une nouvelle version. Le nom, les labels et l'état d'activation restent modifiables. + +## Écrire le code vous-même + +Le **evaluator code** est une expression Python unique qui retourne `EvalResult(...)`, avec `session` dans la portée. Celle-ci calcule la proportion de résultats d'outils retournés avec le statut ok : + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +Un résultat commence par la clé propre à l'évaluation, dans son type déclaré : `score=` pour une évaluation de score, ou une entrée `metrics` ou `assertions` portant le nom de la clé pour une évaluation de métrique ou d'assertion. D'autres métriques et assertions peuvent l'accompagner, jusqu'à 25 résultats par exécution. + +| Dans la portée | Vous donne accès à | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count`, et `events`, ainsi que `count(event_type)` et `events_of_type(event_type)` | +| Chaque événement | `id`, `ts`, `event_type`, et `payload` | +| Types de résultats | `EvalResult`, `Score`, `Metric`, `Assertion`, et `ConditionResult` pour une condition | +| Builtins | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +Rien d'autre n'est accessible : pas d'imports, et aucun attribut au-delà des données de session et des méthodes de chaînes et de dictionnaires courantes comme `get`, `lower` et `split`, qui doivent être appelées et non simplement référencées. Les clés de payload correspondent à ce que vos agents envoient — `status` ci-dessus n'est qu'un exemple — lisez-les donc depuis une vraie session. **format** met en forme le code et **fix** demande à l'assistant de le corriger. Le code peut faire jusqu'à 128 Kio, et la condition jusqu'à 16 Kio. + +![L'éditeur de code de l'évaluateur, avec les boutons format et fix, affichant les assertions d'une évaluation générée.](/images/dashboard/eval-authoring-code.png) + +## L'exécuter dans votre propre worker + +Lorsqu'une évaluation nécessite un modèle, un package, un secret ou le réseau, écrivez-la avec l'[Evaluator SDK](/fr/reference/evaluator-sdk) et exécutez-la sur votre propre infrastructure. Elle utilise les mêmes types de résultats, et ses résultats apparaissent à côté des évaluations hébergées, avec le tag **customer** : + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/fr/policies/deploy.mdx b/docs/fr/policies/deploy.mdx index 9a3fc5a4..78a4a019 100644 --- a/docs/fr/policies/deploy.mdx +++ b/docs/fr/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "Déployer des politiques" -description: "Déployez une version de politique approuvée sur les machines concernées." +title: "Déployer une politique" +description: "Mettez une version de politique testée sur des machines en mode observation, appliquez-la, et confirmez que chaque machine l'a bien récupérée." icon: "cloud-upload" --- -Un déploiement associe une ou plusieurs versions de politique à un ensemble cible de machines enrôlées. +Un déploiement place des versions de politique publiées sur une machine, chacune avec l'un de deux effets possibles : -## Appliquer un déploiement +- **Observer** enregistre ce que la politique aurait fait, sans rien bloquer. +- **Appliquer** agit sur la décision : un `deny` bloque l'appel et un `instruct` guide l'agent. + +## Ajouter une machine + +Une machine apparaît sous **Admin → enforcement** dès qu'elle est connectée au Cloud. Si celle que vous souhaitez n'y figure pas encore : - 1. Accédez à **Admin → enforcement**, trouvez la machine et développez sa ligne. - 2. Sélectionnez **edit**, ajoutez la version de politique approuvée et choisissez l'effet **observe** ou un effet d'application. - 3. Appliquez la modification, puis attendez le prochain check-in de la machine et confirmez son état de déploiement et de couverture. - 4. Accédez à **Observe → policy** pour inspecter les décisions en temps réel. - - ![L'éditeur de déploiement machine avec les versions de politique, les effets enforce et observe, et l'action d'application du déploiement.](/images/dashboard/enforcement-editor.png) + 1. Allez dans **Administration → Keys** et créez une clé avec `policies:pull`, pour que la machine puisse recevoir les déploiements, et `events:add`, pour que ses décisions parviennent au Cloud. + 2. Connectez la machine avec cette clé — [Connecter une machine au Cloud](/fr/start/setup#connect-a-machine-to-cloud) vous guide pas à pas. + 3. Confirmez qu'elle apparaît bien sous **Admin → enforcement**. - Déployez depuis la CLI avec `fp fleet`. Examinez le plan résultant avant de l'appliquer — `deploy` affiche le plan complet et demande confirmation **uniquement sur un terminal interactif sans `--json`**. Avec `--json`, avec `--yes`, ou lorsque stdin est redirigé (une étape CI, un script, un agent exécutant un sous-shell), la commande s'applique immédiatement sans plan ni confirmation — exécutez donc `fp fleet show ` au préalable si vous souhaitez vérifier : + Sur la machine : + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + Dans un terminal, `failproofai config` demande si vous souhaitez vous connecter au Cloud et saisit la clé via une invite masquée. Confirmez ensuite que la machine est enrôlée, depuis n'importe quel endroit, avec `fp fleet list`. + + + +## Déployer en mode observation + + + + 1. Allez dans **Admin → enforcement**, trouvez la machine et développez sa ligne. + 2. Sélectionnez **edit**, ajoutez la version de politique testée et choisissez **observe**. + 3. Appliquez la modification, puis attendez le prochain enregistrement de la machine et confirmez son état de déploiement et de couverture. + 4. Allez dans **Observe → policy** pour inspecter les décisions en direct. + ![L'éditeur de déploiement de machine avec les versions de politique, les effets d'application et d'observation, et l'action d'application du déploiement.](/images/dashboard/enforcement-editor.png) + + ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` affiche l'écart entre l'intention et la livraison (une machine apparaît comme `behind` jusqu'à sa prochaine interrogation), `fp fleet history ` liste les générations, et `fp fleet rollback ` en restaure une — la commande échoue si cette génération référence une politique désactivée ou supprimée depuis. + Le suffixe `:observe` est ce qui active le mode observation : un simple `--add no-force-push` sans suffixe conserve l'effet que la machine a déjà pour cette politique, et applique sinon. Basculez vers l'application plus tard avec `--add no-force-push:enforce`. + + `deploy` **remplace l'ensemble des politiques de la machine** par le résultat. Il affiche le plan, puis demande confirmation avant d'appliquer — mais uniquement sur un terminal interactif. Avec `--yes`, sous `fp --json`, ou avec stdin redirigé (une étape CI, un script, un agent exécutant un shell), il s'applique sans demander ; le plan est tout de même affiché, ou retourné sous la clé `plan` avec `--json`. - Vérifiez la machine elle-même avec `failproofai config --status`, et utilisez `fp sessions --env production --since 24h` et `fp events --event-type hook_completed` après le déploiement pour confirmer que l'activité remonte bien vers Cloud. + Sur la machine, `failproofai policies` liste les politiques gérées par le Cloud en cours d'exécution et `failproofai config --status` affiche l'état de la connexion. Utilisez `fp sessions --env production --since 24h` et `fp events --event-type hook_completed` pour confirmer que son activité parvient au Cloud. - - Déployez une version approuvée, et non un brouillon modifiable, en commençant par une machine hors production ou un petit groupe de machines dont vous pouvez inspecter les sessions. + + Sélectionnez la version publiée et les machines sur lesquelles elle doit s'exécuter. - - Examinez les correspondances, les raisons, les outils concernés et les faux positifs sans bloquer le travail. + + Examinez les correspondances, les raisons, les outils concernés et les faux positifs pendant qu'aucun blocage n'est actif. - - Passez en mode d'application une fois que les correspondances observées distinguent clairement les actions non sécurisées des actions valides, puis confirmez que chaque machine concernée a bien récupéré le déploiement et remonte ses décisions. + + Basculez l'effet sur enforce une fois que les correspondances observées distinguent les actions non sécurisées des actions valides, puis confirmez que chaque machine concernée a bien récupéré la modification et signale ses décisions. -Les machines doivent disposer de la capacité `policies:pull`. Le reporting des événements est contrôlé séparément par `events:add` ; vérifiez les deux lorsque vous attendez une analyse et une application Cloud. +## Vérifier la couverture + +La couverture indique si une politique s'exécute là où le risque est présent. + +1. Allez dans **Admin → enforcement** et consultez les totaux en mode application et en mode observation. +2. Recherchez une machine par ID ou par label, ou filtrez les machines auxquelles il manque une politique. +3. Développez une ligne pour comparer les politiques assignées, le déploiement signalé, le dernier enregistrement et l'historique. +4. Actualisez après l'intervalle de polling de la machine si un déploiement appliqué est encore en attente. + +![La flotte d'application montrant la couverture des politiques, l'état de déploiement des machines, et les assignations d'observation et d'application.](/images/dashboard/enforcement-fleet.png) + +Repérez les machines qui n'ont jamais récupéré le dernier déploiement, les machines enrôlées qui ont cessé de signaler leur activité, une politique assignée au mauvais environnement, et la dérive de version après une mise à jour interrompue. + +Étiquetez les machines par charge de travail et par environnement — les noms d'hôte seuls survivent rarement à un autoscaling ou à un remplacement : + +```bash +failproofai config --machine-label checkout-runner-03 +``` - La gestion de l'application est un flux de travail Cloud administratif. Ne traitez pas les routes d'application réservées à root comme des points de terminaison API `/v1` ordinaires destinés aux clients. + La gestion de l'application est un flux de travail administratif Cloud. Ne traitez pas les routes d'application réservées à root comme des points de terminaison API `/v1` ordinaires destinés aux clients. \ No newline at end of file diff --git a/docs/fr/policies/editor.mdx b/docs/fr/policies/editor.mdx index 644a8ec7..7da36da5 100644 --- a/docs/fr/policies/editor.mdx +++ b/docs/fr/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "Éditeur de politiques" -description: "Créez et révisez des politiques versionnées à partir d'un mode de défaillance confirmé." +title: "Écrire une politique" +description: "Laissez Failproof AI rédiger une politique à partir d'un résultat d'audit, ou écrivez la source vous-même, puis révisez, testez et publiez-la." icon: "file-pen-line" --- -Utilisez l'éditeur de politiques pour transformer un constat ou un problème en règle déployable. Maintenez la rédaction séparée du déploiement afin qu'un brouillon ne puisse pas modifier silencieusement le comportement en production. +Il existe deux façons d'écrire une politique : laisser Failproof AI la rédiger à partir d'un résultat d'audit, ou écrire la source vous-même. Rien n'est publié ni déployé tant que vous ne le décidez pas. -Lorsqu'un problème présente un schéma d'action reproductible, ouvrez-le sous **Analyze → issues** et sélectionnez **generate policy**. Failproof AI explique d'abord si une politique peut exprimer le problème, puis intègre l'intention validée et le contexte du constat dans l'éditeur. La source générée reste un brouillon jusqu'à sa publication. +## Écrire une politique à partir d'un audit -## Publier une version de politique +Un audit détecte une défaillance ; une politique empêche qu'elle se reproduise. Failproof AI rédige la politique à partir des preuves propres au résultat. + +### 1. Lancer un audit + +[Lancez un audit](/fr/audits/run) sur les sessions où la défaillance se produit. Chaque résultat contient ses sessions de preuves, une cause racine et un chemin de prévention suggéré. Partez d'un résultat avec un **schéma d'action répétable** — une politique ne peut bloquer que ce qu'elle peut reconnaître dans un événement de hook. + +### 2. Générer le brouillon - 1. Accédez à **Admin → policy editor** et, dans **compose**, décrivez le mode de défaillance ou collez la source JavaScript de la politique. - 2. Validez la source et corrigez chaque erreur signalée. - 3. Saisissez l'identité de la politique et publiez-la, puis utilisez **library** pour comparer ou désactiver des versions. - 4. Sélectionnez **enforcement** lorsque la version est prête pour un déploiement sur les machines. + 1. Ouvrez le problème du résultat sous **Analyze → issues** et vérifiez ses sessions citées, sa cause racine et sa recommandation. + 2. Sélectionnez **generate policy**. Failproof AI indique d'abord si une politique peut exprimer le problème. Un résultat **no policy** signifie que la correction passe par une alerte, un changement de flux de travail ou une intervention humaine — pas une politique. + 3. Sélectionnez **write this policy**. Le titre du problème, le résultat, la cause racine, la recommandation et l'intention d'application proposée deviennent un brouillon dans **Admin → policy editor**. Utilisez **open the editor anyway** si vous n'êtes pas d'accord avec la vérification de candidature. - ![La vue compose de l'éditeur de politiques avec l'identité de la politique, la rédaction assistée par IA, la validation de la source et les contrôles de publication.](/images/dashboard/policy-editor.png) + ![La vue de composition de l'éditeur de politique avec l'identité de la politique, la rédaction assistée par IA, la validation de la source et les contrôles de publication.](/images/dashboard/policy-editor.png) - Publiez depuis le CLI avec `fp policies publish`. Cette commande crée une **nouvelle version** et ne modifie jamais une version existante en place ; elle vérifie également la syntaxe de la source avec node avant l'envoi — aucune étape ultérieure ne le fait, donc une erreur de syntaxe se manifesterait autrement sur la machine au moment de l'application : + Lisez les preuves, puis rédigez avec l'assistant. `compose` affiche la source pour que vous la révisiez et ne publie rien : ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - La publication ne déploie rien — une nouvelle version reste inutilisée jusqu'à ce que `fp fleet deploy` la place sur une machine. `fp policies compose ""` rédige une source avec l'assistant Cloud et l'affiche pour révision sans la publier. - - Pour installer une politique dans un CLI d'agent local (et non dans Cloud), utilisez `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. + `compose` nécessite une session connectée (`fp login`) dont le rôle dispose de `policies:write` ; il refuse les clés API. -## Liste de contrôle pour la rédaction +### 3. Réviser le brouillon + +Un brouillon est un point de départ, pas un verdict. Avant de publier, vérifiez qu'il : + +1. Nomme le mode de défaillance dans un langage opérationnel. +2. Ne correspond qu'aux événements de hook et aux outils qui contiennent suffisamment de preuves pour décider. +3. Utilise la condition la plus étroite possible pour intercepter l'action non sécurisée. +4. Retourne une raison indiquant à l'agent ce qu'il doit faire à la place. +5. Utilise `instruct` lorsque l'agent peut corriger sa trajectoire en toute sécurité, et `deny` uniquement lorsque autoriser l'action est inacceptable ou irréversible. + +Validez la source dans l'éditeur et corrigez chaque erreur signalée. + +### 4. Tester, puis publier + +Exécutez **backtest** sous la source avant de publier : cela rejoue le brouillon contre les appels déjà effectués par votre flotte et compte les appels en cours de fonctionnement qui auraient été interrompus. [Tester une politique](/fr/policies/test) couvre cela ainsi que les autres vérifications. + +Une fois qu'elle se comporte correctement, saisissez l'identité de la politique et sélectionnez **publish version**. La publication crée une version immuable et ne déploie rien : elle reste inutilisée jusqu'à ce que vous la [déployiez](/fr/policies/deploy). Depuis un terminal : + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` vérifie la syntaxe de la source avant de l'envoyer, de sorte qu'une erreur de syntaxe apparaît ici plutôt que sur une machine au moment de l'application. + +## L'écrire vous-même + +Une politique est du JavaScript ou du TypeScript utilisant l'API `failproofai` : + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +Cela correspond à `production/config.yml`, `/srv/production/config.yml`, `/srv/production` et `C:\\production\\config.yml` pour `Write` et `Edit`, mais pas à `production-backup` : `production` doit être un segment de chemin complet. Le contexte contient également le type d'événement, la charge utile normalisée, les métadonnées de session, les paramètres et la CLI source lorsqu'elle est disponible — consultez le [SDK de politique](/fr/reference/policy-sdk). + +Pour la publier en tant que version, collez la source dans **compose** sous **Admin → policy editor** et suivez les étapes 3 et 4 ci-dessus, ou publiez le fichier depuis un terminal avec `fp policies publish`. -1. Nommez le mode de défaillance dans un langage opérationnel. -2. Sélectionnez les événements de hook et les outils qui contiennent suffisamment d'informations pour décider. -3. Rédigez la condition la plus restrictive qui correspond au comportement non sécurisé. -4. Retournez une raison indiquant à l'agent ou à l'opérateur quoi faire ensuite. -5. Ajoutez des exemples qui doivent correspondre et des exemples qui doivent rester autorisés. -6. Enregistrez une nouvelle version et demandez une révision. +Pour l'exécuter sur une machine sans Cloud, enregistrez-la sous `.failproofai/policies/` avec un nom se terminant par `policies.js`, `policies.mjs` ou `policies.ts` — ces fichiers se chargent automatiquement aux portées projet et utilisateur — ou installez-la par chemin : -Utilisez `instruct` lorsque l'agent peut corriger sa trajectoire en toute sécurité. Utilisez `deny` lorsqu'autoriser l'action créerait un risque inacceptable ou irréversible. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - Les versions de politique sont des entrées de déploiement immuables. La modification d'un brouillon crée une nouvelle version ; elle ne doit pas réécrire la version déjà assignée aux machines. - \ No newline at end of file +Donnez à chaque politique un nom unique parmi les politiques conventionnelles, personnalisées, en pack et gérées par Cloud. \ No newline at end of file diff --git a/docs/fr/policies/failure-behavior.mdx b/docs/fr/policies/failure-behavior.mdx index 412bb4c2..68f203af 100644 --- a/docs/fr/policies/failure-behavior.mdx +++ b/docs/fr/policies/failure-behavior.mdx @@ -4,16 +4,16 @@ description: "Comprendre ce qui se passe lorsque l'évaluation des politiques ou icon: "shield-alert" --- -Failproof AI est conçu de façon à ce qu'un échec d'application soit visible plutôt que de permettre silencieusement des opérations risquées. +Failproof AI est conçu de sorte qu'un échec d'application soit visible plutôt que de permettre silencieusement des opérations risquées. -## Diagnostiquer un blocage en mode fermé +## Diagnostiquer un blocage en mode échec-fermé - 1. Allez dans **Admin → enforcement** et ouvrez la machine. - 2. Vérifiez sa dernière connexion, le déploiement assigné et le déploiement reporté. - 3. Allez dans **Observe → policy** et ouvrez la session de la décision refusée. - 4. Confirmez si la raison indique l'accessibilité du daemon, un décalage de version ou la politique elle-même. + 1. Accédez à **Admin → enforcement** et ouvrez la machine. + 2. Vérifiez sa dernière connexion, le déploiement attribué et le déploiement signalé. + 3. Accédez à **Observe → policy** et ouvrez la session de la décision refusée. + 4. Confirmez si la raison indique une inaccessibilité du daemon, un écart de version, ou la politique elle-même. @@ -23,7 +23,7 @@ Failproof AI est conçu de façon à ce qu'un échec d'application soit visible failproofai config ``` - Relancer `failproofai config` met à jour et redémarre le daemon après une mise à jour du paquet. + Relancer `failproofai config` met à jour et redémarre le daemon après une mise à jour du package. @@ -31,37 +31,39 @@ Sur une machine configurée pour utiliser `failproofaid`, le daemon est le seul Avant la configuration du daemon, les hooks évaluent les politiques en cours de processus. Une fois la configuration du daemon enregistrée, Failproof AI ne bascule pas silencieusement vers un second évaluateur en cas de défaillance du daemon. -## Répondre à une décision en mode fermé +## Réagir à une décision en mode échec-fermé 1. Exécutez `failproofai config --status`. -2. Si les versions diffèrent, relancez `failproofai config` après avoir mis à jour le paquet. +2. Si les versions diffèrent, relancez `failproofai config` après avoir mis à jour le package. 3. Si le daemon est inaccessible, inspectez l'état de son service et les journaux locaux. -4. Ne reprenez le travail de l'agent qu'après avoir confirmé qu'un chemin d'évaluation des politiques connu est opérationnel. +4. Ne reprenez le travail de l'agent qu'après avoir vérifié qu'un chemin d'évaluation des politiques connu est opérationnel. - Ne réessayez pas l'action bloquée de manière répétée. Une réponse en mode fermé signifie que le système n'a pas pu établir que l'action était sûre. + Ne réessayez pas l'action bloquée de manière répétée. Une réponse en mode échec-fermé signifie que le système n'a pas pu établir que l'action était sûre. ## Un pack ne se charge pas -Une machine à qui l'on a demandé d'appliquer un pack, et qui ne peut pas l'exécuter, refuse plutôt que de continuer silencieusement. Le déclencheur est une **attente enregistrée**, jamais une attente vide : une machine sans pack installé reste silencieuse, tandis qu'un pack déclaré qui ne peut pas se résoudre — ou qui enregistre moins que ce que son manifeste déclare — est refusé. +Une machine à qui l'on a demandé d'appliquer un pack, et qui ne peut pas l'exécuter, refuse plutôt que de continuer silencieusement. Le déclencheur est une **attente enregistrée**, jamais une attente vide : une machine sans pack installé reste silencieuse, tandis qu'un pack déclaré qui ne peut pas se résoudre — ou qui enregistre moins que ce que son manifeste déclare — entraîne un refus. -Le refus est **ciblé**, contrairement à un daemon inaccessible. Un daemon injoignable signifie qu'aucune évaluation n'a eu lieu, donc rien ne peut être considéré comme sûr. Un pack qui ne se charge pas possède un ensemble dénombrable de gardes manquants, car chaque politique déclarée porte son propre `match` — il ne refuse donc que les événements et outils couverts par ces politiques, tout le reste continuant normalement. +Le refus est **ciblé**, contrairement à un daemon inaccessible. Un daemon inaccessible signifie qu'aucune évaluation n'a eu lieu, et donc que rien ne peut être considéré comme sûr. Un pack qui ne se charge pas dispose d'un ensemble énumérable de guards manquants, car chaque politique déclarée porte son propre `match` — il refuse donc uniquement les événements et outils couverts par ces politiques, et tout le reste continue normalement. Il ne se déclenche pas pour : -- un pack `observe`, qui évalue et rejette par construction -- des politiques que vous n'avez jamais adoptées ou explicitement désactivées +- un pack `observe`, qui évalue et écarte par construction +- des politiques que vous n'avez jamais adoptées, ou explicitement désactivées - un pack que le chargeur n'a jamais reçu, où « aucun enregistrement » ne peut être distingué d'un saut délibéré - une pause de session active -- un délai de chargement dépassé, qui est transitoire — un instant de disque lent ne doit pas déclencher un refus jusqu'à ce qu'un humain intervienne +- un délai d'expiration de chargement, qui est transitoire — un moment de disque lent ne doit pas entraîner un refus jusqu'à ce qu'un humain intervienne -`UserPromptSubmit` **instruit** plutôt que de refuser, quelle que soit la politique manquante déclarée. Un refus global l'emporterait avec lui et vous bloquerait hors de l'agent qui pourrait résoudre le problème. +`UserPromptSubmit` **instruis** plutôt que de refuser, quelle que soit la politique manquante déclarée. Un refus général l'inclurait et vous bloquerait hors de l'agent qui pourrait résoudre le problème. ### Que faire ```bash -failproofai pack list +failproofai policies ``` -Cette commande identifie tout pack installé qui ne se charge pas, en explique la raison, et se termine avec un code de sortie non nul. Réinstallez-le ensuite (`failproofai pack add `) ou supprimez-le (`failproofai pack remove `) — le supprimer retire l'attente enregistrée, et le refus cesse avec elle. \ No newline at end of file +La liste signale un pack installé dont l'enregistrement d'installation ou le condensé ne correspond plus, et en indique la raison. Elle n'importe pas le pack, donc un pack qui échoue uniquement au chargement — en enregistrant moins que ce que son manifeste déclare — apparaît normalement dans la liste ; le refus ci-dessous est ce qui identifie ce cas. Dans tous les cas, réinstallez-le (`failproofai policies add `) ou supprimez-le (`failproofai policies remove `) — le supprimer retire l'attente, et le refus s'arrête avec elle. + +Le refus lui-même est attribué à `pack/failproofai-pack-unavailable`, ce qui prend le dessus sur les politiques qui ont bien chargé, de sorte qu'un appel d'outil bloqué nomme le pack manquant plutôt que le guard survivant qui se serait déclenché en premier. \ No newline at end of file diff --git a/docs/fr/policies/local-configuration.mdx b/docs/fr/policies/local-configuration.mdx index 02581ce3..73c9354b 100644 --- a/docs/fr/policies/local-configuration.mdx +++ b/docs/fr/policies/local-configuration.mdx @@ -4,52 +4,46 @@ description: "Contrôlez la portée des politiques, les paramètres, les fichier icon: "file-cog" --- -Failproof AI sépare la sélection des politiques des paramètres de la machine et du daemon. Cela permet de garder les choix de politiques du dépôt lisibles et révisables, tandis que les identifiants et l'état du daemon restent en dehors du dépôt. +Failproof AI sépare ce qu'un dépôt peut committer — câblage des hooks, paramètres des politiques, politiques personnalisées — de l'état machine tel que les identifiants, les packs installés et le daemon. -## Choisir une portée de politique +## Choisir une portée - - - Exécutez `failproofai` sans arguments pour ouvrir le tableau de bord des politiques locales. Choisissez la portée utilisateur, projet ou locale avant d'activer une politique, afin que la modification soit écrite dans le fichier de configuration approprié. +La portée détermine l'endroit où les hooks sont câblés, ainsi que le fichier de configuration dans lequel vous saisissez les paramètres et les chemins de politiques personnalisées : - - **Utilisateur** s'applique à tous les projets sur cette machine. - - **Projet** appartient au dépôt et peut être versionné. - - **Local** remplace un projet pour un utilisateur donné et doit rester dans le gitignore. +- **User** s'applique à tous les projets sur cette machine. +- **Project** appartient au dépôt et peut être committé. +- **Local** remplace un projet pour un utilisateur donné et doit rester dans le gitignore. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # wire hooks for this repository +failproofai policies --install --cli claude --scope user # or for every project on this machine +failproofai policies +``` - Tous les harnais ne prennent pas en charge la portée locale. Le CLI rejette une portée que le harnais sélectionné ne peut pas représenter. - - +Tous les harnais ne prennent pas en charge la portée locale ; la CLI rejette une portée que le harnais sélectionné ne peut pas représenter. + +L'activation ou la désactivation des politiques d'un pack **n'est pas** délimitée par une portée. Ce réglage est enregistré avec le pack installé, de sorte que `failproofai policies add ` active une politique pour toute la machine, quelle que soit la valeur de `--scope`. | Portée | Fichier de configuration des politiques | | --- | --- | -| Projet | `/.failproofai/policies-config.json` | +| Project | `/.failproofai/policies-config.json` | | Local | `/.failproofai/policies-config.local.json` | -| Utilisateur | `~/.failproofai/policies-config.json` | +| User | `~/.failproofai/policies-config.json` | -Les politiques activées sont fusionnées en une union. Les paramètres des politiques utilisent la première portée qui définit des paramètres pour cette politique, dans l'ordre projet → local → utilisateur. Les chemins de politiques personnalisées explicites utilisent la première portée qui les définit. +Les paramètres des politiques utilisent la première portée qui définit des paramètres pour cette politique, dans l'ordre project → local → user. Les chemins de politiques personnalisées explicites utilisent la première portée qui les définit. ## Configurer les paramètres des politiques - Ouvrez la politique dans le tableau de bord local, modifiez ses paramètres pris en charge, puis enregistrez dans la portée sélectionnée. Exécutez une action agent correspondante et une non correspondante, puis inspectez la décision dans **Observer → politique**. + Ouvrez la politique dans le tableau de bord local, modifiez ses paramètres pris en charge et enregistrez dans la portée sélectionnée. Exécutez une action d'agent correspondante et non correspondante, puis inspectez la décision dans **Observer → politique**. - Modifiez le fichier `policies-config.json` de la portée sélectionnée, puis exécutez `failproofai policies` pour détecter les noms de politique ou les clés de paramètre inconnus. + Modifiez le fichier `policies-config.json` de la portée sélectionnée, puis exécutez `failproofai policies` : cette commande avertit si une entrée `policyParams` désigne une politique qu'aucun pack installé ne contient. Elle ne vérifie pas les clés à l'intérieur d'une entrée, vérifiez donc leur orthographe par rapport au tableau ci-dessous. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ Les politiques activées sont fusionnées en une union. Les paramètres des poli +### Paramètres acceptés par les politiques Failproof AI + +Chaque politique valide ses propres types de paramètres. + +| Politique | Paramètre | Type et valeur par défaut | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]` ; les entrées contiennent `regex` et `label` | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| Bloqueurs d'infrastructure | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"` ; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + Un motif d'autorisation élargit ce qu'un agent peut faire. Testez la tokenisation exacte et les variantes de commandes sur le harnais cible avant de le déployer sur un parc de machines. + + ## Comprendre les fichiers machine -`~/.failproofai` contient des fichiers distincts pour des périmètres de confiance distincts : +`~/.failproofai` contient des fichiers distincts pour des périmètres de confiance séparés : | Chemin | Rôle | | --- | --- | -| `config.json` | Paramètres du daemon, de l'audit et de la télémétrie (non sensibles) | +| `config.json` | Paramètres du daemon, de l'audit et de la télémétrie (sans secrets) | | `credentials.json` | Identifiants cloud ; stockés avec des permissions réservées au propriétaire | -| `policies-config.json` | Sélection des politiques intégrées, paramètres et chemins personnalisés explicites pour la portée utilisateur | -| `policies/` | Politiques de convention utilisateur et artefacts de politique gérés par le cloud | +| `policies-config.json` | Paramètres de portée utilisateur et chemins de politiques personnalisées explicites | +| `policies/` | Politiques de convention utilisateur, packs installés avec indication des politiques activées, et artefacts de politiques gérés par le cloud | | `hook-activity/` | Journal local des décisions de politique | -| `state/` | Spool du daemon, santé, pause et état d'exécution | +| `state/` | File d'attente du daemon, état de santé, pause et état d'exécution | -Utilisez `FAILPROOFAI_HOME` pour déplacer l'ensemble de la structure machine vers un conteneur ou un environnement de test isolé. Ne déplacez pas des répertoires d'état individuels de façon indépendante. +Utilisez `FAILPROOFAI_HOME` pour déplacer l'intégralité de l'organisation machine vers un conteneur ou un environnement de test isolé. Ne déplacez pas des répertoires d'état individuels de manière indépendante. - Ne commitez jamais `credentials.json`. Ne committez la configuration des politiques du projet et les politiques de convention du projet qu'après les avoir examinées en tant que code d'application des règles. + Ne committez jamais `credentials.json`. Ne committez la configuration des politiques du projet et les politiques de convention du projet qu'après les avoir examinées en tant que code d'application. \ No newline at end of file diff --git a/docs/fr/policies/overview.mdx b/docs/fr/policies/overview.mdx index 7b8f633a..1562dc18 100644 --- a/docs/fr/policies/overview.mdx +++ b/docs/fr/policies/overview.mdx @@ -1,63 +1,54 @@ --- title: "Politiques" -description: "Observez, guidez ou bloquez les actions des agents avant qu'une défaillance connue se reproduise." +description: "Observez, guidez ou bloquez les actions des agents avant qu'une défaillance connue ne se reproduise." icon: "shield-check" --- -Une politique évalue un événement de hook d'agent et retourne l'une des trois décisions suivantes : +Une politique évalue un événement de hook d'agent et renvoie l'une des trois décisions suivantes : - `allow` laisse l'action se poursuivre. - `instruct` fournit des conseils correctifs à l'agent. -- `deny` bloque l'action avec une justification. +- `deny` bloque l'action en indiquant un motif. -## Utiliser les trois surfaces de politique +## Où vivent les politiques - - - 1. Accédez à **Observer → politique** pour filtrer et inspecter les décisions de politique issues des sessions. - 2. Accédez à **Admin → éditeur de politique** pour composer, valider, publier, désactiver ou inspecter des versions immuables. - 3. Accédez à **Admin → application** pour assigner des versions et des effets aux machines. +| Dans le tableau de bord | Ce que vous y faites | +| --- | --- | +| **Observe → policy** | Consulter les décisions issues de sessions réelles : quelle politique a correspondu, sur quelle machine, et pourquoi | +| **Admin → policy editor** | Rédiger une politique, la backtester sur du trafic passé, publier une version immuable, et comparer les versions dans la **bibliothèque** | +| **Admin → enforcement** | Déployer des versions sur des machines, en mode observe ou enforce | - Utilisez la page Politique pour comprendre ce qui correspond déjà avant de créer ou de modifier l'application. +L'éditeur de politique est l'endroit où une défaillance devient une règle. Décrivez le mode de défaillance ou collez le code source de la politique dans **compose**, backtestez le brouillon sur le trafic que vous avez déjà, puis publiez une version : - ![La page Politique affichant les totaux de décisions et les mappages de politiques locales et gérées par le Cloud.](/images/dashboard/policy-observe.png) +![La vue compose de l'éditeur de politique, avec l'identité de la politique, la rédaction assistée par IA, la validation du code source et les contrôles de publication.](/images/dashboard/policy-editor.png) - L'éditeur est l'endroit où vous transformez une condition d'échec en code source, la validez et publiez une version immuable. +Sur une machine, `failproofai policies` liste tout ce qui y est appliqué. `fp policies` et `fp fleet` couvrent l'éditeur et l'application depuis un terminal — consultez la [référence Cloud CLI](/fr/reference/cloud-cli). - ![L'éditeur de politique utilisé pour composer et publier une version de politique immuable.](/images/dashboard/policy-editor.png) +## Obtenir une politique - L'application assigne ensuite cette version publiée et son effet d'observation ou d'application aux machines. - - ![La flotte d'application affichant la couverture des machines et les versions de politique assignées.](/images/dashboard/enforcement-fleet.png) - - Vérifiez les décisions sur la page Politique après le déploiement afin que les vues de création et de flotte soient liées à l'activité réelle des agents. - - - Utilisez `failproofai` pour l'installation et la validation de politiques locales : - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - Utilisez `fp` pour trouver les sessions Cloud et les événements contenant des décisions de politique. La création et le déploiement en flotte dans le Cloud restent des workflows du tableau de bord. - - - -Les politiques disposent de trois surfaces distinctes dans Failproof AI : - -1. **Analyser les décisions** dans les sessions, les tableaux de bord et les audits. -2. **Créer des versions** avec des règles intégrées, du code ou l'éditeur de politique. -3. **Déployer et appliquer** des versions sur les machines sélectionnées. - -Partez d'un mode de défaillance confirmé. Définissez la correspondance d'événement et d'outil la plus restreinte qui l'identifie, testez des exemples légitimes et non sécurisés, puis observez avant d'appliquer. +Il existe deux façons d'en obtenir une. - - Activez une règle vérifiée pour les risques courants liés aux secrets, au shell, à Git, au cloud et aux workflows. + + Laissez Failproof AI en rédiger une à partir d'un résultat d'audit, ou écrivez vous-même le code source, puis relisez-le et publiez-le dans l'éditeur. - - Exprimez une décision spécifique à un workflow en JavaScript ou TypeScript. + + Intégrez un pack de politiques Failproof AI adapté à votre cas d'usage, ou un pack communautaire depuis le hub de politiques, en une seule commande. - \ No newline at end of file + + +## Puis déployez + + + + Backtestez le brouillon sur le trafic existant, et exécutez-le contre une action qu'il doit bloquer et une qu'il doit autoriser — tout cela avant de publier. Voir [Tester une politique](/fr/policies/test). + + + Déployez la version sur des machines en mode **observe**, lisez ses décisions, puis appliquez-la. Voir [Déployer une politique](/fr/policies/deploy). + + + Chaque publication crée une nouvelle version immuable, de sorte qu'un déploiement qui bloque du travail légitime peut être annulé en redéployant la dernière version correcte. Voir [Versions et retour arrière](/fr/policies/rollback). + + + +Pour partager vos politiques avec d'autres équipes, [publiez-les sous forme de pack](/fr/policies/publish-a-pack). Pour savoir ce qui se passe lorsqu'une politique ne peut pas être évaluée du tout, consultez [Comportement en cas d'échec](/fr/policies/failure-behavior). \ No newline at end of file diff --git a/docs/fr/policies/packs.mdx b/docs/fr/policies/packs.mdx index b5383e5c..1cd2dcbc 100644 --- a/docs/fr/policies/packs.mdx +++ b/docs/fr/policies/packs.mdx @@ -1,41 +1,59 @@ --- -title: "Packs de politiques" -description: "Installez un ensemble de politiques publiées en tant que release GitHub et gérez ce qu'elles appliquent." +title: "Utiliser un pack de politiques" +description: "Intégrez un pack de politiques Failproof AI adapté à votre cas d'usage, ou un pack communautaire depuis le hub de politiques, et choisissez ce qu'il applique." icon: "package" --- -Un pack est un ensemble de politiques publié sous forme de release GitHub. Une seule commande suffit pour l'installer, les sommes de contrôle de la release sont vérifiées avant toute exécution, et le digest est enregistré pour garantir que le pack ne peut pas changer sur votre machine par la suite. +Un pack est un ensemble de politiques publié sous forme de release GitHub. Une seule commande suffit pour l'installer : les checksums de la release sont vérifiés avant toute exécution, et le condensé est enregistré afin que le pack ne puisse pas être modifié sur votre machine par la suite. -## Installer les politiques Failproof AI +Parcourez tous les packs et toutes les politiques qu'ils contiennent sur le [hub de politiques](https://befailproof.ai/policy-hub/). Il en existe deux types : + +- **Packs de politiques Failproof AI** — des packs prêts à l'emploi pour des cas d'usage prédéfinis : branchez-en un et il fonctionne immédiatement. Le [pack de politiques pour agent de développement](https://befailproof.ai/policy-hub/failproofai/policies/) est déjà disponible, et des packs pour d'autres cas d'usage arrivent bientôt. +- **Packs de politiques communautaires** — des politiques que des développeurs ont créées pour leurs propres cas d'usage et publiées à disposition de tous. + +## Packs de politiques Failproof AI + +### Pack de politiques pour agent de développement ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -Cette commande installe l'ensemble que nous publions, depuis la copie incluse dans le package — aucune connexion réseau n'est nécessaire et l'installation ne peut pas échouer derrière un proxy. Pour n'en prendre qu'une partie : +Le pack contient 38 politiques et active les 10 que son manifeste marque comme sûres à activer sans supervision ; les autres vous sont présentées pour que vous puissiez en choisir. Voici certaines des plus utilisées, avec l'indication de si un simple `policies add` les active : + +| Politique | Ce qu'elle fait | Activée par défaut | +| --- | --- | --- | +| `block-push-master` | Bloque les push directs vers les branches protégées | Oui | +| `block-env-files` | Bloque la lecture et l'écriture des fichiers `.env` | Oui | +| `protect-env-vars` | Bloque les commandes qui exposent les variables d'environnement | Oui | +| `block-sudo` | Bloque `sudo` sauf si un motif d'autorisation correspond | Oui | +| `block-curl-pipe-sh` | Bloque les scripts téléchargés puis envoyés directement dans un shell | Oui | +| `sanitize-*` (cinq politiques) | Signale les clés API, tokens bearer, JWT, clés privées et chaînes de connexion trouvées dans la sortie des outils | Oui | +| `block-rm-rf` | Bloque les suppressions récursives catastrophiques | Non | +| `block-force-push` | Bloque les force-push | Non | +| `block-secrets-write` | Bloque les écritures dans les fichiers de credentials et de clés secrètes | Non | +| `warn-destructive-sql` | Avertit en cas de `DROP`, `TRUNCATE` et `DELETE` sans `WHERE` | Non | + +Activez celles qui sont désactivées par leur nom — `failproofai policies add block-rm-rf` — ou prenez tout le pack avec `--all`. Affichez toutes les politiques du pack, regroupées par catégorie : ```bash -failproofai pack add core --policy block-rm-rf # une seule, ou quelques-unes séparées par des virgules -failproofai pack add core --category dangerous-commands # toute une catégorie -failproofai pack add core --all # tout ce qu'il contient +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` affiche toutes les catégories proposées par le pack. +## Packs de politiques communautaires -## Voir le contenu d'un pack avant de l'installer +Les développeurs publient des packs pour les cas d'usage qu'ils ont rencontrés, et le [hub de politiques](https://befailproof.ai/policy-hub/) les répertorie. Un pack communautaire est publié par son auteur, sans audit de la part de Failproof AI — lisez donc ce qu'il contient avant de l'installer : ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -Liste toutes les politiques du pack, regroupées par catégorie, en indiquant lesquelles son auteur active par défaut et lesquelles sont optionnelles. Seul le **manifeste** est lu — l'artefact d'entrée n'est jamais téléchargé ni importé, de sorte que consulter le pack d'un inconnu ne peut pas exécuter son code. Le manifeste est tout de même vérifié par rapport au fichier `SHA256SUMS` de la release, ce qui garantit que ce que vous lisez correspond à ce qui serait installé. - -`failproofai pack list` sans argument liste les packs déjà installés sur cette machine. +Cette commande liste toutes les politiques du pack, regroupées par catégorie, et indique celles que l'auteur active par défaut. Elle ne lit **que le manifeste** — l'artefact d'entrée n'est jamais téléchargé ni importé, de sorte que consulter le pack d'un inconnu ne peut pas exécuter le code d'un inconnu. Le manifeste est tout de même vérifié par rapport au `SHA256SUMS` de la release, donc ce que vous lisez correspond exactement à ce qui serait installé. -## Installer le pack de quelqu'un d'autre +Installez-le ensuite : ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` L'une ou l'autre de ces formes fonctionne — collez celle que vous avez : @@ -43,68 +61,59 @@ L'une ou l'autre de ces formes fonctionne — collez celle que vous avez : | Source | Résultat | | --- | --- | | `acme/support-agent` | Dernière release, **épinglée** au tag exact résolu | -| `acme/support-agent@v2.1.0` | Cette release spécifique | -| `github:acme/support-agent@v2.1.0` | Identique, écrit explicitement | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Identique, copié depuis un navigateur | +| `acme/support-agent@v2.1.0` | Cette release | +| `github:acme/support-agent@v2.1.0` | La même, écrite explicitement | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | La même, copiée depuis un navigateur | -Ne pas préciser de tag installe la dernière release **et l'épingle**, puis vous indique le tag choisi. Ce qui est enregistré identifie toujours exactement une release, de sorte qu'une réinstallation ne peut pas dériver. +Ne pas préciser de tag installe la release la plus récente **et l'épingle**, puis indique le tag choisi. Ce qui est enregistré nomme toujours exactement une release, de sorte qu'une réinstallation ne peut pas entraîner de dérive. -## Ne prendre qu'une partie d'un pack +## Prendre une partie d'un pack -Par défaut, vous obtenez les **propres** valeurs par défaut du pack — les politiques que son auteur a jugées sûres à activer sans surveillance — et non tout ce qu'il contient. +Par défaut, vous obtenez les **propres** valeurs par défaut du pack — les politiques que son auteur a marquées comme sûres à activer sans supervision — et non l'intégralité de son contenu. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # une seule, ou quelques-unes séparées par des virgules +failproofai policies add FailproofAI/policies --category dangerous-commands # toute une catégorie +failproofai policies add FailproofAI/policies --all # tout ce qu'il contient ``` -`--category` et `--policy` se combinent en union (`--only` est accepté comme synonyme de `--policy`). Réajouter le pack à une version plus récente conserve vos choix plutôt que de réactiver le reste. +`--category` et `--policy` se combinent en union (`--only` est accepté comme synonyme de `--policy`). Lorsque le pack est déjà installé, les flags s'ajoutent à votre sélection existante, et le réinstaller sans flag ni terminal — pour une mise à jour, par exemple — conserve votre sélection telle quelle. Dans un terminal sans flag, `add` ouvre le sélecteur à la place, avec les valeurs par défaut de l'auteur pré-cochées, et ce que vous cochez remplace votre sélection. ## Gérer ce qui est activé ```bash -failproofai policies # toutes les sources dans une seule liste, packs inclus -failproofai pack list # packs uniquement, regroupés par catégorie +failproofai policies # toutes les sources en une seule liste, packs inclus +failproofai policies add block-rm-rf # activer une politique failproofai policies --uninstall block-refunds # désactiver une politique du pack failproofai policies --install block-refunds # la réactiver -failproofai pack remove acme/support-agent +failproofai policies remove acme/support-agent # désinstaller le pack ``` -Un nom seul désigne le **builtin** lorsqu'il en existe un portant ce nom. Nommez explicitement la copie d'un pack lorsque c'est nécessaire : +Activer ou désactiver une politique de pack s'applique à toute la machine : le changement est enregistré avec le pack installé, et non dans la configuration d'un projet, quoi qu'en dise `--scope`. + +Un nom sans barre oblique est une politique ; tout ce qui en contient une est une source de pack. Un nom simple est résolu vers le pack installé qui le déclare. Lorsque deux packs installés déclarent le même nom, précisez celui que vous visez : ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -Si un pack embarque une politique dont le nom correspond également à un **builtin activé**, c'est le builtin qui s'exécute et la copie du pack est ignorée — sinon la même protection serait évaluée deux fois. Désactivez le builtin pour utiliser la copie du pack à la place. - - -## D'où viennent les politiques Failproof AI - -`core` lit la copie intégrée dans le package npm. Le même ensemble est publié en tant que release GitHub, ce qui vous permet d'installer une version spécifique : - -```bash -failproofai pack add core # depuis ce package, sans réseau -failproofai pack add FailproofAI/policies # le même ensemble, depuis sa release GitHub -``` +Les scopes, les paramètres et les fichiers écrits par ces commandes sont décrits dans la [configuration locale](/fr/policies/local-configuration). -## Ce que l'intégrité garantit ou non +## Ce que l'intégrité garantit — et ce qu'elle ne garantit pas -`SHA256SUMS` est livré dans la même release que l'artefact, ce n'est donc **pas** une signature et cela ne prouve rien sur l'identité de l'auteur de la publication. Ce que cela prouve, en revanche, c'est que les octets sont bien ceux publiés dans cette release — et parce que le digest est enregistré lors de l'ajout du pack et revérifié avant chaque import, un pack ne peut pas changer sur votre machine par la suite. Un dépôt qui retague ou remplace un asset cessera de se charger plutôt que d'exécuter silencieusement autre chose. +Le fichier `SHA256SUMS` est livré dans la même release que l'artefact, donc il ne constitue **pas** une signature et ne prouve rien sur l'identité de l'auteur. Ce qu'il prouve, en revanche, c'est que les octets sont bien ceux que cette release a publiés — et parce que le condensé est enregistré lors de l'ajout du pack et revérifié avant chaque import, un pack ne peut pas être modifié sur votre machine après coup. Un dépôt qui re-tague ou remplace un asset cesse de se charger au lieu d'exécuter silencieusement autre chose. -Au moment de l'installation, le pack est également **importé une fois** et vérifié par rapport à son propre manifeste. Un pack dont l'artefact ne peut pas être analysé, ou qui enregistre autre chose que ce qu'il déclare, est refusé avant toute activation — plutôt que de s'installer proprement et d'échouer au prochain appel d'outil. +Au moment de l'installation, le pack est également **importé une fois** et vérifié par rapport à son propre manifeste. Un pack dont l'artefact ne se parse pas, ou qui enregistre autre chose que ce qu'il déclare, est refusé avant toute activation — plutôt que de s'installer normalement et d'échouer lors du prochain appel d'outil. ## Quand un pack ne se charge pas -Un pack que cette machine a été configurée pour appliquer et qui ne peut pas s'exécuter **refuse** les événements couverts par ses politiques manquantes, plutôt que de les autoriser silencieusement. Voir [Comportement en cas d'échec](/fr/policies/failure-behavior). `failproofai pack list` indique tout pack dans cet état et se termine avec un code d'erreur non nul. +Un pack que cette machine a été configurée pour appliquer mais qu'elle ne peut pas exécuter **refuse** les événements couverts par ses politiques manquantes, plutôt que de les autoriser silencieusement — en tant que `pack/failproofai-pack-unavailable`, qui prime sur les politiques chargées afin que le refus soit attribué au pack manquant plutôt qu'au garde qui a déclenché en premier. L'exception est `UserPromptSubmit`, qui instruit à la place : refuser à cet endroit vous bloquerait hors de l'agent dont vous avez besoin pour corriger le problème. Consultez [Comportement en cas d'échec](/fr/policies/failure-behavior). ## Hors ligne et miroirs | Variable | Effet | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Refuse tout téléchargement ; les packs déjà installés continuent de s'appliquer | -| `FAILPROOFAI_PACK_BASE_URL` | Redirige les téléchargements de packs vers un miroir au lieu de `github.com` | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Refuse tout téléchargement ; les packs déjà installés continuent d'être appliqués | +| `FAILPROOFAI_PACK_BASE_URL` | Redirige le téléchargement des packs vers un miroir à la place de `github.com` | -Pour publier votre propre pack, consultez [Publier un pack](/fr/policies/publish-a-pack). \ No newline at end of file +Pour partager vos propres politiques de cette façon, consultez [Publier un pack de politiques](/fr/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/fr/policies/publish-a-pack.mdx b/docs/fr/policies/publish-a-pack.mdx index a0a7fb27..832e12f9 100644 --- a/docs/fr/policies/publish-a-pack.mdx +++ b/docs/fr/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "Publier un pack" +title: "Publier un pack de politiques" description: "Distribuez vos propres politiques sous forme de release GitHub que n'importe qui peut installer." icon: "upload" --- -Un pack se compose de trois fichiers joints à une release GitHub. `failproofai pack build` génère ces trois fichiers à partir d'un fichier de politiques existant. +Un pack est composé de trois fichiers attachés à une release GitHub. `failproofai publish` génère ces trois fichiers à partir des fichiers de politiques qui lui sont fournis, crée la release et les téléverse. ## 1. Écrire les politiques -Un seul fichier, utilisant la même API que n'importe quelle politique personnalisée. Deux champs supplémentaires sont importants pour un pack : +Partez de quelque chose qui fonctionne déjà plutôt que d'un modèle vide : + +```bash +failproofai publish --init +``` + +Cette commande demande le nom du pack, crée `.mjs` et s'arrête — pas de réseau, pas de git, rien n'est publié. Le fichier généré contient une politique qui bloque déjà `git push --force`. Il refuse d'écraser un fichier existant. + +Les politiques utilisent la même API que toute politique personnalisée. Deux champs supplémentaires sont importants pour un pack : ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` vaut **false** par défaut si vous l'omettez. Un simple `failproofai pack add` n'active que ce que vous avez marqué — activer silencieusement toutes les politiques d'un inconnu est une décision que l'installateur ne devrait pas prendre à la place de l'utilisateur. +`defaultEnabled` vaut **false** par défaut si vous l'omettez. Un simple `failproofai policies add` n'active que ce que vous avez marqué — installer en masse toutes les politiques d'un inconnu sans supervision n'est pas une décision que l'installateur devrait prendre à la place de l'utilisateur. + +Créez autant de fichiers que vous le souhaitez ; un fichier par catégorie est lisible. Chaque fichier du répertoire qui enregistre des politiques est intégré dans l'artefact unique que doit constituer un pack. -L'entrée doit être **un fichier unique et autonome**. Seule l'entrée est épinglée par son condensé, donc un pack qui importe des fichiers locaux ne pourrait pas honnêtement prétendre que le condensé couvre ce qui s'exécute. Regroupez d'abord vos sources (`esbuild`, `bun build`, `rollup`) et construisez le pack à partir du bundle — `pack build` refuse une importation locale plutôt que de livrer une promesse qu'il ne peut pas tenir. + Le bundling nécessite **bun**. Sans lui, limitez-vous à un seul fichier autonome. Dans tous les cas, l'entrée publiée ne doit pas importer de fichiers locaux au moment de l'installation : seule l'entrée est épinglée par son empreinte, donc un pack qui accède à des fichiers adjacents ne peut pas honnêtement affirmer que l'empreinte couvre ce qui s'exécute — et `publish` refuse de le distribuer plutôt que de tenir une promesse qu'il ne peut pas tenir. -## 2. Construire les fichiers de release +## 2. Testez-le d'abord localement + +Avant que quiconque puisse le voir, appliquez le fichier sur cette machine : ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +N'importe quel chemin, n'importe quel nom de fichier. Demandez à votre agent d'effectuer l'action que vous avez bloquée et observez le refus. Rien n'est publié et personne d'autre n'est affecté. [Tester une politique](/fr/policies/test) couvre le reste : le cas légitime qui doit être autorisé, et les entrées qui la font échouer. + +## 3. Publier + +```bash +failproofai publish ``` -Cette commande génère trois fichiers et valide chaque politique avec les **règles propres au chargeur** en premier — ainsi, un pack qui ne pourrait jamais s'installer échoue ici, là où vous pouvez corriger le problème : +La commande détermine où publier, ce qu'il faut bundler, et quelle version attribuer, en ne posant des questions que lorsque le dépôt ne lui fournit pas l'information. Dans l'ordre, elle s'arrête avant de créer une release si quoi que ce soit pose problème : + +1. Trouve les fichiers de politiques par **contenu** — ceux qui importent `failproofai` et appellent `customPolicies.add` — plutôt que par nom de fichier ; elle trouve donc `guards.mjs` et ignore un `policies.mjs` sans rapport. Elle ne descend pas dans les sous-répertoires, ce qui évite d'embarquer accidentellement une fixture de test. +2. Lit le dépôt depuis `git remote get-url origin`, dans le répertoire du **fichier** plutôt que le vôtre, et détermine la version. +3. Trouve vos identifiants : `GITHUB_TOKEN`, `GH_TOKEN`, ou `gh auth login`. Seul le droit d'écriture sur les releases est requis, et ils ne sont jamais affichés. +4. Crée le dépôt s'il n'existe pas. Cela se produit avant la construction, donc un pack refusé à l'étape suivante peut laisser un nouveau dépôt vide sans aucune release. +5. Construit les trois assets en les validant avec les **propres règles du loader** — le même code qui décide ce qui peut s'installer sur la machine d'un inconnu — de sorte qu'un pack qui ne pourrait jamais s'installer échoue ici, là où vous pouvez encore le corriger. +6. Crée ou réutilise la release et téléverse les fichiers, en remplaçant les assets portant le même nom. | Fichier | Description | | --- | --- | | `failproofai-pack.json` | Le manifeste : id, version, effet, et une entrée par politique | -| `failproofai-pack.mjs` | Votre entrée, telle quelle | -| `SHA256SUMS` | ` ` pour les deux autres fichiers | +| `failproofai-pack.mjs` | Votre entrée bundlée | +| `SHA256SUMS` | ` ` pour les deux autres | -Refusé à la construction : un id qui n'est pas au format `publisher/name`, un nom de politique contenant `/`, une politique déclarant `alwaysOn`, une `description`, une `category` ou un `match` manquant, une entrée qui n'enregistre rien, et une entrée qui importe des fichiers locaux. +Les noms des assets sont fixes — ce sont ceux qu'utilise le CLI d'un consommateur pour construire ses URLs, sans appel API ni découverte. -## 3. Joindre les fichiers à une release +Refusé à la construction : un id qui n'est pas de la forme `publisher/name`, un nom de politique contenant `/`, une politique déclarant `alwaysOn`, une `description`, une `category` ou un `match` manquant, une entrée qui n'enregistre rien, et une entrée qui importe des fichiers locaux. -Étiquetez la release avec la même version que celle utilisée lors de la construction, et joignez les trois fichiers en tant qu'assets de release : +Surchargez les valeurs décidées automatiquement : ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -N'importe qui peut désormais l'installer : +`--id` définit l'id du pack lorsqu'il doit différer du dépôt, `--tag` définit le tag de la release, `--notes` remplace les notes de release générées automatiquement — là où `policies show --releases` lit le nombre de politiques et le commit de chaque release —, `--out` choisit l'emplacement d'écriture des assets (par défaut `dist-pack`), et `--dry-run` les construit sans publier et ne nécessite aucune identifiant. -```bash -failproofai pack add acme/support-agent -``` +N'importe qui peut désormais l'installer avec `failproofai policies add acme/support-agent`. Consultez [les packs de politiques](/fr/policies/packs) pour épingler une version ou n'en prendre qu'une partie. + +### Le référencer sur le hub de politiques -Les noms des assets sont fixes — c'est à partir d'eux que le CLI consommateur construit ses URLs, sans appel API ni découverte automatique. +Ajoutez le topic `failproofai-policies` au dépôt sur GitHub. Il n'y a pas de formulaire de soumission ni de file d'approbation : le crawler du [hub de politiques](https://befailproof.ai/policy-hub/) détectera le dépôt lors de son prochain passage. Le topic ne fait que le soumettre à considération — ce qui le liste est une release dont le manifeste se vérifie contre son propre `SHA256SUMS` et se parse selon les mêmes règles que le CLI utilise, ce qui est exactement ce que `failproofai publish` produit. -## Publier une nouvelle version +## Comment la version est déterminée -Construisez avec le nouveau `--version`, créez une nouvelle release, joignez à nouveau les trois assets. Les utilisateurs exécutent le même `pack add` et conservent le sous-ensemble de politiques qu'ils avaient choisi ; une politique qu'ils avaient désactivée reste désactivée après la mise à jour. +La version correspond au **commit depuis lequel vous publiez** — son sha court, douze caractères : `a1b2c3d4e5f6`. Il n'y a rien à choisir ni à incrémenter, et la version nomme exactement l'origine des octets, de sorte que publier deux fois la même source donne la même version. -Changer le **nom** d'une politique est un changement cassant : une machine qui l'avait désactivée désactive un nom qui n'existe plus, et le nouveau nom arrive avec ce que `defaultEnabled` indique. +Elle est lue depuis l'arbre qui se trouve devant vous, jamais depuis les releases du dépôt, ce qui permet à un clone fraîchement créé et à une machine isolée de calculer la même réponse sans interroger GitHub. -## Ce à quoi vos utilisateurs font confiance +Comme la version nomme un commit, ce commit doit exister. Dans un terminal, `publish` le crée pour vous : il initialise un dépôt s'il n'en existe pas, et commite les fichiers de politiques modifiés avant la construction. Il **refuse** en revanche — en indiquant `--version` comme solution de contournement — lorsqu'il s'exécute sans terminal (un commit créé sur un runner CI n'existerait nulle part ailleurs), lorsque des fichiers autres que les politiques ne sont pas commités, ou dans un checkout qui n'a encore aucun commit. Un tag sur `HEAD` prend la priorité sur le sha — quelqu'un qui a tagué `v1.2.0` a déclaré ce qu'est cette release. -`SHA256SUMS` réside dans la même release que l'artefact, ce qui prouve que les octets sont bien ceux que vous avez publiés — pas votre identité. Quiconque peut écrire dans le dépôt peut modifier les deux fichiers. La protection des utilisateurs tient au fait que le condensé est épinglé lors de l'installation, de sorte que ce que vous avez publié ne peut pas changer sous leurs pieds par la suite. +Un sha ne porte pas d'ordre intrinsèque ; utilisez `failproofai policies show / --releases` pour voir quelle release est arrivée en premier — la plus récente en haut. + +## Distribuer une nouvelle version + +Commitez la modification et relancez `failproofai publish` — le nouveau commit est la nouvelle version. Les consommateurs exécutent le même `failproofai policies add`. Sans terminal, ou avec un flag de sélection, ils conservent le sous-ensemble qu'ils avaient choisi et une politique désactivée reste désactivée ; dans un terminal sans flag, le sélecteur s'ouvre pré-coché avec vos valeurs par défaut et leur réponse remplace leur sélection. + +Modifier le **nom** d'une politique est un changement cassant : une machine qui l'avait désactivée désactive un nom qui n'existe plus, et le nouveau nom arrive avec ce que dit `defaultEnabled`. + +## Ce à quoi font confiance vos utilisateurs + +`SHA256SUMS` se trouve dans la même release que l'artefact, ce qui prouve que les octets sont bien ceux que vous avez publiés — pas qui vous êtes. Quiconque peut écrire dans le dépôt peut écrire les deux fichiers. La protection de vos utilisateurs repose sur le fait que l'empreinte est épinglée au moment de l'installation, ce qui empêche ce que vous avez distribué de changer ultérieurement à leur insu. Publiez depuis un dépôt dont vous contrôlez les accès en écriture, et traitez une release de pack comme la publication d'un package. +Le dépôt doit également être **public**. Les installations se font en HTTPS anonyme sans identifiant à fournir, donc un dépôt privé existant est refusé avant que quoi que ce soit ne soit construit ou téléversé, et un dépôt créé par `publish` est public pour la même raison. `--allow-private` outrepasse cela pour quelqu'un qui transmet les trois assets par un autre moyen, et indique clairement qu'aucun `policies add` ne peut les atteindre. Seule la release compte : les installations lisent `releases/download//` et n'accèdent jamais à votre arbre git. + ## Observer avant d'appliquer -Un manifeste peut déclarer `"effect": "observe"`. Ces politiques s'exécutent et leurs verdicts sont **enregistrés puis ignorés** — rien n'est bloqué. C'est la façon de mesurer une nouvelle règle sur du trafic réel avant qu'elle ne puisse interrompre le travail de quiconque. +Un manifeste peut déclarer `"effect": "observe"` — c'est `failproofai publish --effect observe` qui le définit. Ces politiques s'exécutent et leurs verdicts sont **enregistrés puis ignorés** — rien n'est bloqué. C'est le moyen de mesurer une nouvelle règle face au trafic réel avant qu'elle puisse interrompre le travail de quiconque. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/fr/policies/rollback.mdx b/docs/fr/policies/rollback.mdx index 97d6d992..6c7f43f4 100644 --- a/docs/fr/policies/rollback.mdx +++ b/docs/fr/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "Rollback" -description: "Restaurer un déploiement de politique connu lorsqu'un rollout perturbe le travail valide des agents." +title: "Versions et retour arrière" +description: "Chaque publication est une version immuable, ce qui permet d'annuler un déploiement perturbant le travail valide d'un agent en redéployant la dernière version fonctionnelle." icon: "rotate-ccw" --- -Le rollback modifie la version déployée ou supprime une affectation de politique ; il n'efface pas l'historique des décisions qui explique l'incident. +Une version de politique publiée ne change jamais. Modifier une politique et la republier crée une nouvelle version ; elle ne réécrit jamais celle déjà déployée sur les machines. C'est ce qui rend le retour arrière sûr : la dernière bonne version est toujours là, octet pour octet, et revenir en arrière n'efface pas l'historique des décisions qui explique ce qui s'est mal passé. -## Effectuer un rollback sur une machine +## Trouver une version - - 1. Accédez à **Admin → enforcement**, développez la machine concernée et identifiez son dernier ensemble de politiques connu comme fonctionnel. - 2. Sélectionnez **edit**, restaurez ces versions et effets, puis appliquez le nouveau déploiement. - 3. Attendez que la machine se reconnecte, puis vérifiez le déploiement signalé. - 4. Ouvrez **Observe → policy** ainsi que les sessions concernées pour confirmer que le travail valide n'est plus bloqué. + + Allez dans **Admin → éditeur de politiques** et ouvrez la **bibliothèque** pour comparer les versions d'une politique ou en désactiver une. + + + ```bash + fp policies list # toutes les versions de politique + fp policies show # une version, avec son code source + ``` + + +## Effectuer un retour arrière sur une machine + + + + 1. Allez dans **Admin → application**, développez la machine concernée et identifiez son dernier ensemble de politiques connu comme fonctionnel. + 2. Sélectionnez **modifier**, restaurez ces versions et leurs effets, puis appliquez le nouveau déploiement. + 3. Attendez l'enregistrement de la machine, puis vérifiez le déploiement signalé. + 4. Ouvrez **Observer → politique** ainsi que les sessions concernées pour confirmer que le travail valide n'est plus bloqué. - Le rollback d'un déploiement Cloud s'effectue via le tableau de bord. Utilisez le statut local pour confirmer que le déploiement corrigé a bien atteint la machine : + Chaque déploiement sur une machine correspond à une génération numérotée. Listez-les, puis réinstaurez-en une : ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` suspend les politiques intégrées, personnalisées et de convention pour une session locale. Il ne suspend pas les politiques gérées par Cloud, il ne constitue donc pas une solution de contournement pour un mauvais déploiement Cloud. + `rollback` crée une nouvelle génération portant l'ancien ensemble plutôt que de rembobiner le compteur, de sorte que l'historique reste en ajout uniquement. Cette commande refuse une génération faisant référence à une politique désactivée ou supprimée. Elle nécessite une session connectée avec `policies:write`. `fp fleet diff ` montre ce qui était prévu par rapport à ce que la machine a appliqué — il s'affiche comme `behind` jusqu'au prochain sondage de la machine — et sur la machine elle-même, `failproofai policies` liste le déploiement en cours d'exécution. -## Quand effectuer un rollback +## Retirer une politique de toutes les machines + +```bash +fp policies disable # la retirer de chaque déploiement qui la contient +fp policies enable # la réintégrer +``` + +Chaque commande crée une nouvelle génération sur chaque déploiement qu'elle touche. Revenir en arrière sur l'une de ces générations n'est toutefois pas la bonne façon d'annuler un `disable` — `rollback` refuse une génération faisant référence à une politique désactivée, et toutes les générations antérieures à la désactivation mentionnent celle-ci. `fp policies enable` est le chemin de retour, et il crée sa propre génération à son tour. + +## Retour arrière sur un pack + +Un pack est épinglé à la version que vous avez installée ; revenir en arrière signifie donc installer une version antérieure : + +```bash +failproofai policies show FailproofAI/policies --releases # toutes les versions publiées et celle actuellement installée +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # épingler cette version +``` + +Sans terminal, ou avec `--policy`, `--category` ou `--all`, le ré-ajout conserve le sous-ensemble que vous aviez choisi. Dans un terminal sans aucune de ces options, le sélecteur s'ouvre avec les sélections par défaut de l'auteur pré-cochées, et ce que vous cochez remplace votre sélection — pensez donc à recocher ce que vous aviez. + +## Quand effectuer un retour arrière - Une politique bloque une action de production attendue. -- Le volume de correspondances est significativement plus élevé que ce que le rollout observé avait prédit. +- Le volume de correspondances est sensiblement plus élevé que ce que le déploiement observé avait prédit. - Une politique dépend de champs qu'une intégration ne fournit pas. -- Une nouvelle version modifie le comportement en dehors du mode d'échec prévu. +- Une nouvelle version modifie un comportement en dehors du mode d'échec prévu. -Après le rollback, ouvrez les sessions concernées et identifiez la condition ayant provoqué le faux positif. Créez une nouvelle version, testez les cas non sécurisés et légitimes, puis recommencez la phase d'observation. +Après un retour arrière, ouvrez les sessions concernées et identifiez la condition à l'origine du faux positif. Publiez une nouvelle version, [testez](/fr/policies/test) aussi bien le cas non sécurisé que le cas légitime, puis observez-la à nouveau avant de l'appliquer. - Suspendre l'application des politiques peut être approprié lors d'un incident, mais cela élargit l'exposition pour toutes les politiques actives dans ce périmètre. Privilégiez le rollback de la version spécifique de la politique lorsque c'est possible. + `failproofai config --pause` suspend les politiques locales pour une session uniquement et n'affecte jamais les politiques gérées dans le cloud — ce n'est donc pas une solution pour sortir d'un mauvais déploiement cloud. Une pause élargit également l'exposition pour toutes les politiques dans son périmètre ; préférez revenir en arrière sur la seule version qui se comporte mal. \ No newline at end of file diff --git a/docs/fr/policies/test.mdx b/docs/fr/policies/test.mdx new file mode 100644 index 00000000..0eef00aa --- /dev/null +++ b/docs/fr/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "Tester une politique" +description: "Rétrotestez un brouillon sur le trafic que vous possédez déjà, et prouvez qu'il bloque ce qu'il doit et autorise ce qu'il doit, avant qu'une machine ne l'applique." +icon: "flask-conical" +--- + +Testez chaque politique de deux façons : contre le trafic que vos agents ont déjà produit, et contre une action légitime qu'elle doit laisser passer. Une politique qui n'a été confrontée qu'aux cas dangereux n'a pas été correctement testée. + +## Rétrotester le brouillon + + + + L'éditeur de politique rejoue un brouillon sur les appels déjà effectués par votre flotte, avant que vous ne le publiiez. + + 1. Ouvrez le brouillon dans **Admin → éditeur de politique**. L'éditeur confirme qu'il est analysé en tant que JavaScript. + 2. Dans **backtest**, sélectionnez les agents et la fenêtre temporelle à rejouer — **tous les agents** et **30j** par défaut — et laissez le dernier filtre sur **tout** sauf si vous souhaitez affiner la sélection. + 3. Cliquez sur **lancer le backtest**. + + ![Le panneau de backtest sous un brouillon analysé en JavaScript, avec ses trois filtres et l'action de lancement du backtest, au-dessus de la publication de version.](/images/dashboard/policy-backtest.png) + + Le résultat indique ce que le brouillon aurait fait à ces appels — y compris le nombre d'appels **opérationnels** qu'il aurait interrompus. Ce sont des faux positifs détectés avant qu'un agent ne les rencontre : affinez le brouillon et relancez-le jusqu'à ce que ce nombre soit acceptable. + + + Le backtest est une fonctionnalité du tableau de bord. Depuis un terminal, exécutez plutôt la politique sur des événements que vous décrivez vous-même, comme indiqué ci-dessous. + + + +## L'exécuter sur un événement que vous décrivez + +`fp policies test` exécute un fichier de politique sur votre machine contre un événement synthétique et vérifie la décision. Rien n'est publié et rien n'atteint Cloud : + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +Modelez l'événement avec `--event`, `--tool`, `--command` et `--file`. Le filtre `match` propre à la politique s'applique toujours ; ainsi, une politique qui ne couvre pas l'événement décrit rapporte `skipped` plutôt qu'une décision — ce qui indique généralement que son `match` est plus restrictif que prévu. + +## L'exécuter sur une seule machine + +Ensuite, appliquez-la réellement sur votre propre machine, contre votre propre agent : + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +La première commande valide et installe le fichier ; la seconde confirme qu'il est chargé, aux côtés de tout ce qui s'applique ici. Demandez à l'agent d'effectuer ce que la politique bloque et observez le refus, puis effectuez la version légitime et observez qu'elle passe. Personne d'autre n'est affecté. + +Sur une machine connectée à Cloud, vérifiez les deux décisions sous **Observer → politique** : filtrez par nom de politique, puis ouvrez chaque session liée pour confirmer l'entrée d'outil qu'elle a correspondée et la raison renvoyée. + +## Tester ce qui échoue + +L'installation refuse un fichier manquant, une erreur de syntaxe, une importation non résolue, une exception au niveau supérieur ou un module qui expire pendant le chargement — relancez-la donc après chaque modification du fichier ou de tout ce qu'il importe. Au moment de l'application, le même fichier défectueux est journalisé et **ignoré** afin que toutes les autres politiques continuent de s'exécuter : traitez un avertissement de chargement dans les journaux de production comme une application perdue. Les fichiers de convention se chargent sans la commande d'installation, c'est pourquoi il faut conserver une étape explicite `failproofai policies --install --custom ` en CI — c'est ce qui fait échouer le build en cas de politique défectueuse. + +Ensuite, alimentez-la avec ce que les agents envoient réellement, pas seulement l'entrée attendue : champs manquants, noms d'outils alternatifs tels que `Write` et `Edit`, chemins Windows, entrées malformées. Renvoyez un `allow`, `instruct` ou `deny` intentionnel sur chaque chemin d'exécution, gardez la fonction déterministe et limitez tout appel externe par un délai d'expiration court. + +## Ensuite, publiez-la et observez-la + +Un backtest montre ce que la politique aurait fait au trafic passé ; il ne peut pas montrer ce que le trafic futur encore inconnu produira. Sélectionnez **publier la version** dans l'éditeur (ou exécutez `fp policies publish`), puis [déployez-la](/fr/policies/deploy) d'abord en mode **observe** — ses verdicts sont enregistrés sans rien bloquer — et appliquez-la une fois que ses correspondances distinguent clairement les actions dangereuses des actions valides. \ No newline at end of file diff --git a/docs/fr/reference/cloud-cli.mdx b/docs/fr/reference/cloud-cli.mdx index c678efa4..a9137ce4 100644 --- a/docs/fr/reference/cloud-cli.mdx +++ b/docs/fr/reference/cloud-cli.mdx @@ -4,7 +4,7 @@ description: "Référence complète pour interroger et administrer Failproof AI icon: "cloud-cog" --- -Utilisez `fp` pour inspecter la télémétrie Cloud, gérer l'application des règles cloud (politiques, déploiements de flotte, décisions de garde-fous), et gérer les audits, constatations, problèmes, alertes, clés, utilisateurs, requêtes et paramètres. Utilisez [`failproofai`](/fr/reference/failproof-cli) pour les hooks locaux, les politiques, la capture et l'enrôlement des machines. +Utilisez `fp` pour inspecter la télémétrie Cloud, gérer l'application gérée depuis le cloud (politiques, déploiements de flotte, décisions de garde-fous), ainsi que les audits, résultats, problèmes, alertes, clés, utilisateurs, requêtes et paramètres. Utilisez [`failproofai`](/fr/reference/failproof-cli) pour les hooks locaux, les politiques, la capture et l'enrôlement des machines. Installez la Cloud CLI publiée comme outil isolé : @@ -13,7 +13,7 @@ uv tool install fp-cloud-cli fp version ``` -## Connexion +## Se connecter ```bash fp login @@ -43,7 +43,7 @@ Exécutez `fp COMMAND --help` ou `fp COMMAND SUBCOMMAND --help` pour obtenir l'a | `fp login` | Se connecter avec un code à usage unique envoyé par e-mail et sélectionner une organisation. | `--email`, `-e` ; `--org` ; `--force` | | `fp logout` | Révoquer et supprimer la session utilisateur enregistrée. | — | | `fp whoami` | Afficher l'identité actuelle, le mode d'authentification, l'organisation et les permissions. | — | -| `fp version` | Afficher la version CLI installée. | — | +| `fp version` | Afficher la version de la CLI installée. | — | | `fp help` | Afficher l'aide des commandes de premier niveau. | — | ```bash @@ -57,21 +57,21 @@ fp whoami fp events [OPTIONS] ``` -Liste les événements d'agent individuels. Le flux léger par défaut exclut les charges utiles brutes ; utilisez `--full` uniquement pour une investigation délimitée. +Liste les événements agents individuels. Le flux léger par défaut exclut les charges utiles brutes ; utilisez `--full` uniquement pour une investigation bornée. | Option | Description | | --- | --- | -| `--limit`, `-n ` | Nombre maximal de lignes. Défaut : `50`. | +| `--limit`, `-n ` | Nombre maximum total de lignes. Par défaut : `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, ou `7d`. | | `--from ` / `--to ` | Plage UTC ISO 8601 ; remplace `--since`. | -| `--env ` | Filtre d'environnement ; répétable ou valeurs séparées par des virgules. | -| `--event-type ` | Filtre de type d'événement ; répétable ou valeurs séparées par des virgules. | -| `--agent-id ` | Filtre d'agent ; répétable ou valeurs séparées par des virgules. | -| `--session-id ` | Filtre de session ; répétable ou valeurs séparées par des virgules. | -| `--search ` | Recherche textuelle dans la charge utile ; répétable, avec correspondance sur n'importe quel terme. | -| `--order asc\|desc` | Ordre temporel. Défaut : les plus récents en premier. | +| `--env ` | Filtre d'environnement ; répétable ou séparé par des virgules. | +| `--event-type ` | Filtre par type d'événement ; répétable ou séparé par des virgules. | +| `--agent-id ` | Filtre par agent ; répétable ou séparé par des virgules. | +| `--session-id ` | Filtre par session ; répétable ou séparé par des virgules. | +| `--search ` | Recherche textuelle dans la charge utile ; répétable, correspondance sur n'importe quel terme. | +| `--order asc\|desc` | Ordre chronologique. Par défaut : du plus récent au plus ancien. | | `--all` | Pagination automatique jusqu'à `--limit`. | -| `--cursor ` | Reprendre à partir d'un curseur opaque. | +| `--cursor ` | Reprendre depuis un curseur opaque. | | `--page-size ` | Lignes par requête avec `--all` ; maximum `200`. | | `--full` | Inclure les charges utiles brutes via l'endpoint d'événements plus lourd. | | `--fields ` | Retourner uniquement les champs sélectionnés ; demander `payload` active le mode complet. | @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` pagine **jusqu'à `--limit`**, dont la valeur par défaut est **50** — ainsi `--all` seul s'arrête à 50 lignes. Lorsqu'il s'arrête prématurément, la réponse contient un `next_cursor` pour reprendre ; `"next_cursor": null` signifie que le flux a réellement été épuisé. + `--all` pagine **jusqu'à `--limit`**, dont la valeur par défaut est **50** — ainsi `--all` seul s'arrête à 50 lignes. Quand il s'arrête prématurément, la réponse contient un `next_cursor` pour reprendre ; `"next_cursor": null` signifie que le flux était réellement épuisé. ### Sessions @@ -93,19 +93,19 @@ fp sessions [OPTIONS] | Option | Description | | --- | --- | -| `--limit`, `-n ` | Nombre maximal de lignes. Défaut : `50`. | +| `--limit`, `-n ` | Nombre maximum total de lignes. Par défaut : `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, ou `7d`. | | `--from ` / `--to ` | Plage UTC ISO 8601 ; remplace `--since`. | -| `--env ` | Filtre d'environnement ; répétable ou valeurs séparées par des virgules. | -| `--status ` | `done`, `error`, ou `timeout` ; répétable ou valeurs séparées par des virgules. | -| `--agent-id ` | Correspondre aux sessions impliquant l'agent sélectionné. | -| `--session-id ` | Filtre de session ; répétable ou valeurs séparées par des virgules. | +| `--env ` | Filtre d'environnement ; répétable ou séparé par des virgules. | +| `--status ` | `done`, `error`, ou `timeout` ; répétable ou séparé par des virgules. | +| `--agent-id ` | Correspond aux sessions impliquant l'un des agents sélectionnés. | +| `--session-id ` | Filtre par session ; répétable ou séparé par des virgules. | | `--all` | Pagination automatique jusqu'à `--limit`. | -| `--cursor ` | Reprendre à partir d'un curseur opaque. | +| `--cursor ` | Reprendre depuis un curseur opaque. | | `--page-size ` | Lignes par requête avec `--all` ; maximum `200`. | | `--fields ` | Retourner uniquement les champs sélectionnés. | | `--full-ids` | Ne pas raccourcir les identifiants de session dans la sortie terminal. | -| `--agents` | Développer la liste des agents pour les sessions multi-agents. | +| `--agents` | Développer le registre des agents pour les sessions multi-agents. | ### Évaluations @@ -116,14 +116,14 @@ fp evals [OPTIONS] | Option | Description | | --- | --- | | `--aggregate` | Afficher les totaux et les statistiques par score au lieu des évaluations individuelles. | -| `--limit`, `-n ` | Nombre maximal de lignes dans la liste. Défaut : `50`. | +| `--limit`, `-n ` | Nombre maximum de lignes dans la liste. Par défaut : `50`. | | `--since`, `--from`, `--to` | Sélectionner la plage temporelle. | | `--env`, `--status`, `--agent-id`, `--session-id` | Restreindre à une valeur exacte par filtre. | -| `--score KEY:MIN..MAX` | Plage de score ; répétable et toutes les plages doivent correspondre. | +| `--score KEY:MIN..MAX` | Plage de score ; répétable, toutes les plages doivent correspondre. | | `--all`, `--cursor`, `--page-size` | Contrôler la pagination de la liste. | | `--fields ` | Retourner uniquement les champs sélectionnés. | | `--full-ids` | Afficher les identifiants de session complets. | -| `--scores-full` | Afficher chaque score dans la sortie terminal. | +| `--scores-full` | Afficher tous les scores dans la sortie terminal. | ### Erreurs @@ -134,11 +134,11 @@ fp errors [OPTIONS] | Option | Description | | --- | --- | | `--aggregate` | Résumer les erreurs correspondantes au lieu de lister les lignes. | -| `--limit`, `-n ` | Nombre maximal de lignes dans la liste. Défaut : `50`. | +| `--limit`, `-n ` | Nombre maximum de lignes dans la liste. Par défaut : `50`. | | `--since`, `--from`, `--to` | Sélectionner la plage temporelle. | | `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Restreindre la population d'erreurs. | | `--search ` | Rechercher dans le texte de la charge utile ; répétable. | -| `--order asc\|desc` | Ordre temporel. | +| `--order asc\|desc` | Ordre chronologique. | | `--all`, `--cursor`, `--page-size` | Contrôler la pagination de la liste. | | `--fields ` | Retourner uniquement les champs sélectionnés. | | `--full-ids` | Afficher les identifiants de session complets. | @@ -147,7 +147,7 @@ fp errors [OPTIONS] | Commande | Objectif | | --- | --- | -| `fp usage` | Afficher l'utilisation pour la fenêtre de comptage actuelle. | +| `fp usage` | Afficher l'utilisation pour la fenêtre de mesure actuelle. | | `fp list envs` | Lister les environnements observés. | | `fp list agents` | Lister les identifiants d'agents observés. | | `fp list event_types` | Lister les types d'événements. | @@ -162,7 +162,7 @@ fp errors [OPTIONS] | Commande | Objectif | | --- | --- | | `fp orgs list` | Lister les organisations accessibles. | -| `fp orgs switch [SLUG]` | Enregistrer une organisation active ; invite si omis. | +| `fp orgs switch [SLUG]` | Enregistrer une organisation active ; invite lorsqu'omis. | | `fp orgs current` | Afficher l'organisation active. | | `fp orgs perms` | Afficher vos permissions dans l'organisation active. | @@ -171,13 +171,13 @@ fp errors [OPTIONS] | Commande | Objectif | Options | | --- | --- | --- | | `fp keys list` | Lister les clés de l'organisation. | `--show-id` ; `--fields ` | -| `fp keys show NAME` | Afficher une clé et ses permissions. | — | +| `fp keys show NAME` | Afficher une clé et ses autorisations. | — | | `fp keys create NAME` | Créer une clé et révéler son secret une seule fois. | `--permission-set` ; `--add` ; `--remove` | -| `fp keys update NAME` | Remplacer le jeu de permissions ou ajuster les permissions. | `--permission-set` ; `--add` ; `--remove` ; `--yes`, `-y` | +| `fp keys update NAME` | Remplacer le jeu de permissions ou ajuster les autorisations. | `--permission-set` ; `--add` ; `--remove` ; `--yes`, `-y` | | `fp keys regenerate NAME` | Faire tourner le secret et révéler le remplacement une seule fois. | `--yes`, `-y` | | `fp keys disable NAME` | Révoquer définitivement une clé. | `--yes`, `-y` | -Les jetons de permission utilisent le format `resource:action`, par exemple `events:add`. Répétez `--add`, séparez les jetons par des virgules, ou utilisez des actions pointées comme `events:read.add`. +Les jetons de permission utilisent le format `resource:action`, par exemple `events:add`. Répétez `--add`, séparez les jetons par des virgules, ou utilisez des actions avec point comme `events:read.add`. ### Requêtes @@ -196,9 +196,9 @@ Les jetons de permission utilisent le format `resource:action`, par exemple `eve | Commande | Objectif | Options | | --- | --- | --- | | `fp users list` | Lister les membres de l'organisation. | `--active-only` ; `--show-id` | -| `fp users show EMAIL` | Afficher un membre et ses permissions. | — | +| `fp users show EMAIL` | Afficher un membre et ses autorisations. | — | | `fp users create EMAIL` | Ajouter un membre. | `--permission-set` ; `--add` ; `--remove` | -| `fp users update EMAIL` | Modifier les permissions d'un membre. | `--permission-set` ; `--add` ; `--remove` ; `--yes`, `-y` | +| `fp users update EMAIL` | Modifier les autorisations d'un membre. | `--permission-set` ; `--add` ; `--remove` ; `--yes`, `-y` | | `fp users disable EMAIL` | Désactiver la connexion. | `--yes`, `-y` | | `fp users enable EMAIL` | Réactiver la connexion. | `--yes`, `-y` | @@ -207,8 +207,8 @@ Les jetons de permission utilisent le format `resource:action`, par exemple `eve | Commande | Objectif | Options | | --- | --- | --- | | `fp settings list` | Lister les paramètres de l'organisation et leurs valeurs actuelles. | — | -| `fp settings schema` | Afficher les valeurs acceptées et les descriptions. | — | -| `fp settings set KEY` | Modifier un paramètre existant. | exactement l'une de ces options : `--value`, `--json-value`, `--file` ; `--yes`, `-y` en option | +| `fp settings schema` | Afficher les valeurs acceptées et leurs descriptions. | — | +| `fp settings set KEY` | Modifier un paramètre existant. | exactement l'un de `--value`, `--json-value`, `--file` ; `--yes`, `-y` optionnel | ### Alertes @@ -230,21 +230,21 @@ Les niveaux de gravité des alertes sont `info`, `warning` et `critical`. Les ty | `fp audits list` | Lister les audits. | `--enabled-only` ; `--show-id` | | `fp audits show NAME` | Afficher une définition d'audit et son état. | — | | `fp audits create NAME` | Créer un audit et mettre immédiatement en file d'attente sa première exécution. | Voir [options de création](#audit-create-options). | -| `fp audits edit NAME` | Remplacer les paramètres d'audit tout en conservant les valeurs non spécifiées. | options de définition de création ; `--name` ; `--yes`, `-y` | -| `fp audits delete NAME` | Supprimer un audit, ses constatations et l'historique d'exécution. | `--yes`, `-y` | +| `fp audits edit NAME` | Remplacer les paramètres d'audit en conservant les valeurs non spécifiées. | options de définition de création ; `--name` ; `--yes`, `-y` | +| `fp audits delete NAME` | Supprimer un audit, ses résultats et son historique d'exécution. | `--yes`, `-y` | | `fp audits run NAME` | Mettre en file d'attente une exécution manuelle. | — | -| `fp audits runs NAME` | Lister l'historique d'exécution. | `--limit`, `-n` ; `--show-id` | +| `fp audits runs NAME` | Lister l'historique des exécutions. | `--limit`, `-n` ; `--show-id` | | `fp audits context-show NAME` | Afficher le résumé et l'état de récupération des URL de référence. | — | | `fp audits context-set NAME` | Modifier le résumé ou les URL de référence. | `--text` ; `--text-file` ; `--url` ; `--clear-urls` | | `fp audits context-refresh NAME` | Récupérer à nouveau les URL de référence. | — | -| `fp audits findings` | Lister les constatations. | `--audit` ; `--run-id` ; `--status` ; `--limit`, `-n` ; `--offset` ; `--show-id` | -| `fp audits finding FINDING_ID` | Afficher une constatation et ses preuves. | — | -| `fp audits ack FINDING_ID` | Accuser réception d'une constatation. | `--reason` | -| `fp audits mute FINDING_ID` | Supprimer un schéma récurrent. | `--reason` ; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | Marquer un schéma comme non actionnable et le supprimer. | `--reason` ; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | Marquer une constatation comme résolue sans suppression future. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | Remettre une constatation dans la file active et effacer la suppression. | — | -| `fp audits assign FINDING_ID` | Définir le propriétaire de la constatation. | `--to ` obligatoire | +| `fp audits findings` | Lister les résultats. | `--audit` ; `--run-id` ; `--status` ; `--limit`, `-n` ; `--offset` ; `--show-id` | +| `fp audits finding FINDING_ID` | Afficher un résultat et ses preuves. | — | +| `fp audits ack FINDING_ID` | Accuser réception d'un résultat. | `--reason` | +| `fp audits mute FINDING_ID` | Supprimer un motif récurrent. | `--reason` ; `--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | Marquer un motif comme non exploitable et le supprimer. | `--reason` ; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | Marquer un résultat comme corrigé sans suppression future. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | Remettre un résultat dans la file active et effacer la suppression. | — | +| `fp audits assign FINDING_ID` | Définir le responsable du résultat. | `--to ` obligatoire | #### Options de création d'audit @@ -261,27 +261,27 @@ fp audits create checkout-reliability \ | Option | Description | | --- | --- | -| `--file ` | Baser la définition sur du JSON, ou utiliser `-` pour stdin. Les drapeaux explicites remplacent les valeurs du fichier. | +| `--file ` | Baser la définition sur du JSON, ou utiliser `-` pour stdin. Les indicateurs explicites remplacent les valeurs du fichier. | | `--description ` | Énoncer la question d'échec ou l'objectif. | -| `--enabled` / `--disabled` | Démarrer la planification activée ou désactivée. Défaut : activée. | -| `--schedule-interval-secs ` | `3600`–`604800`. Défaut : `86400`. | -| `--schedule-anchor ` | Phase UTC fixe en format ISO 8601. Défaut : prochain 09:00 UTC. | -| `--window-mode since_last\|fixed` | Continuer après la dernière fenêtre entièrement analysée ou inspecter de façon répétée une fenêtre glissante. Défaut : `since_last`. | -| `--lookback-window-secs ` | `3600`–`7776000`. Défaut : `604800`. | +| `--enabled` / `--disabled` | Démarrer la planification activée ou désactivée. Par défaut : activée. | +| `--schedule-interval-secs ` | `3600`–`604800`. Par défaut : `86400`. | +| `--schedule-anchor ` | Phase UTC fixe au format ISO 8601. Par défaut : prochain 09:00 UTC. | +| `--window-mode since_last\|fixed` | Continuer après la dernière fenêtre entièrement analysée ou inspecter répétitivement une fenêtre glissante. Par défaut : `since_last`. | +| `--lookback-window-secs ` | `3600`–`7776000`. Par défaut : `604800`. | | `--scope ''` | Filtrer par `environments`, `agent_ids`, ou d'autres champs de portée pris en charge. | -| `--ignore-error-type ` | Exclure des types d'erreurs ; répétable ou séparés par des virgules. | -| `--llm` / `--no-llm` | Activer ou désactiver l'analyse agentique. Défaut : activée. | -| `--top-k ` | Conserver `1`–`500` constatations. Défaut : `50`. | -| `--sensitivity low\|medium\|high` | Définir la sensibilité des rapports. Défaut : `medium`. | +| `--ignore-error-type ` | Exclure des types d'erreurs ; répétable ou séparé par des virgules. | +| `--llm` / `--no-llm` | Activer ou désactiver l'analyse agentique. Par défaut : activée. | +| `--top-k ` | Conserver `1`–`500` résultats. Par défaut : `50`. | +| `--sensitivity low\|medium\|high` | Définir la sensibilité des rapports. Par défaut : `medium`. | | `--channels ''` | Tableau de canaux de notification. | | `--text ` | Résumé en ligne, maximum 8 192 caractères. | | `--text-file ` | Lire le résumé depuis un fichier ; mutuellement exclusif avec `--text`. | | `--url ` | Ajouter une référence HTTPS publique ; répétable jusqu'à cinq fois. | -Incluez le contexte lors de la création lorsque la première exécution en a besoin. La création valide la définition et le contexte ensemble avant que l'exécution mise en file d'attente ne commence. +Incluez le contexte lors de la création si la première exécution en a besoin. La création valide la définition et le contexte ensemble avant le début de l'exécution mise en file d'attente. - `fp audits run` est asynchrone. Interrogez `fp audits runs NAME` jusqu'à ce que la dernière exécution réussisse ou échoue avant de lire ses constatations. + `fp audits run` est asynchrone. Interrogez `fp audits runs NAME` jusqu'à ce que la dernière exécution réussisse ou échoue avant de lire ses résultats. ### Problèmes @@ -289,14 +289,14 @@ Incluez le contexte lors de la création lorsque la première exécution en a be | Commande | Objectif | Options | | --- | --- | --- | | `fp issues list` | Lister les problèmes. | `--state` ; `--alert-id` ; `--limit`, `-n` ; `--show-id` | -| `fp issues count` | Compter les problèmes ouverts ou les états de problèmes sélectionnés. | `--state` | -| `fp issues show INCIDENT_ID` | Afficher les détails d'un problème, les commentaires, les abonnés et l'activité. | — | -| `fp issues open` | Ouvrir un problème manuel ou lié à une alerte. | `--summary` obligatoire ; `--title`, `--alert-id`, `--severity` en option | +| `fp issues count` | Compter les problèmes ouverts ou les états de problème sélectionnés. | `--state` | +| `fp issues show INCIDENT_ID` | Afficher les détails d'un problème, ses commentaires, abonnés et activité. | — | +| `fp issues open` | Ouvrir un problème manuel ou lié à une alerte. | `--summary` obligatoire ; `--title`, `--alert-id`, `--severity` optionnels | | `fp issues ack INCIDENT_ID` | Accuser réception d'un problème. | — | -| `fp issues assign INCIDENT_ID` | Remplacer les assignés ; omettre l'option pour les effacer. | `--assignee` répétable | +| `fp issues assign INCIDENT_ID` | Remplacer les assignés ; omettez l'option pour les effacer. | `--assignee` répétable | | `fp issues resolve INCIDENT_ID` | Résoudre un problème. | `--yes`, `-y` | | `fp issues comment-list INCIDENT_ID` | Lister les commentaires. | — | -| `fp issues comment-add INCIDENT_ID` | Ajouter un commentaire. | exactement l'une de ces options : `--body`, `--file` | +| `fp issues comment-add INCIDENT_ID` | Ajouter un commentaire. | exactement l'un de `--body`, `--file` | | `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Supprimer un commentaire. | `--yes`, `-y` | | `fp issues subscribers INCIDENT_ID` | Lister les abonnés. | — | | `fp issues subscribe INCIDENT_ID` | S'abonner soi-même ou un autre opérateur. | `--email` | @@ -311,63 +311,63 @@ Les états de problème valides sont `firing`, `acknowledged` et `resolved`. Les | `fp agent health` | Vérifier la disponibilité et la configuration de l'assistant. | — | | `fp agent models` | Lister les modèles d'assistant disponibles. | — | | `fp agent chats` | Lister les conversations enregistrées. | — | -| `fp agent ask [MESSAGE]` | Démarrer ou poursuivre une conversation ; lit depuis stdin lorsque le message est omis. | `--chat` ; `--model` ; `--page-context` | +| `fp agent ask [MESSAGE]` | Démarrer ou poursuivre une conversation ; lit stdin lorsque le message est omis. | `--chat` ; `--model` ; `--page-context` | | `fp agent show CHAT_ID` | Afficher une conversation enregistrée. | — | | `fp agent rename CHAT_ID` | Renommer une conversation. | `--title` obligatoire | | `fp agent delete CHAT_ID` | Supprimer une conversation. | `--yes`, `-y` | ### Politiques -Versions de politiques gérées dans le cloud. **Session uniquement** — chaque commande ici se termine avec le code `2` sous une clé API, avant toute requête, car ce sont des routes d'écriture réservées aux root délibérément absentes de `/v1`. +Versions de politiques gérées depuis le cloud. **Session uniquement** — chaque commande ici sort avec le code `2` sous une clé API, avant toute requête, car ce sont des routes d'écriture réservées aux root délibérément absentes de `/v1`. | Commande | Objectif | Options | | --- | --- | --- | | `fp policies list` | Lister les versions de politiques. | `--json` | | `fp policies show POLICY_ID` | Afficher une politique avec sa source. | — | -| `fp policies publish NAME PATH` | Créer une version à partir d'un fichier `.mjs` local. | `--description` ; `--no-verify` | -| `fp policies enable POLICY_ID` | La rajouter à chaque déploiement dont elle avait été retirée, en créant une nouvelle génération à chaque fois. | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | La retirer de chaque déploiement qui la porte, en créant une nouvelle génération à chaque fois. | `--yes`, `-y` | +| `fp policies publish NAME PATH` | Créer une version à partir d'un `.mjs` local. | `--description` ; `--no-verify` | +| `fp policies enable POLICY_ID` | La rajouter à chaque déploiement dont elle avait été retirée, en créant une nouvelle génération sur chacun. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | La retirer de chaque déploiement qui la porte, en créant une nouvelle génération sur chacun. | `--yes`, `-y` | | `fp policies delete POLICY_ID` | Supprimer une version de politique. | `--yes`, `-y` | -| `fp policies test PATH` | Exécuter une politique localement contre un contexte synthétique. Applique le filtre `match` de chaque politique, de sorte qu'une politique ne couvrant pas l'événement/outil donné est signalée comme `skipped` plutôt qu'exécutée. | `--event` ; `--tool` ; `--command` ; `--file-path` ; `--expect` | +| `fp policies test PATH` | Exécuter une politique localement contre un contexte synthétique. Applique le filtre `match` de chaque politique, donc une politique qui ne couvre pas l'événement/outil donné est signalée comme `skipped` plutôt qu'exécutée. | `--event` ; `--tool` ; `--command` ; `--file` ; `--expect` | | `fp policies compose PROMPT` | Rédiger une politique avec l'assistant. Nécessite `policies:write`. | — | ### Flotte -Quelles machines exécutent quelles politiques. **Session uniquement**, même raison que ci-dessus. +Quelles machines exécutent quelles politiques. **Session uniquement**, pour la même raison que ci-dessus. | Commande | Objectif | Options | | --- | --- | --- | | `fp fleet list` | Lister les machines enrôlées et leur génération de déploiement. | — | | `fp fleet show MACHINE_ID` | L'ensemble de politiques qu'une machine exécute actuellement. | — | -| `fp fleet deploy MACHINE_ID` | **Remplace l'ensemble complet des politiques de la machine.** Affiche le plan et demande confirmation uniquement sur un terminal interactif sans `--json`. | `--add` ; `--remove` ; `--set` ; `--create` ; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | Comparer une machine avec un autre déploiement. | — | -| `fp fleet history MACHINE_ID` | Déploiements passés d'une machine. | — | -| `fp fleet rollback MACHINE_ID` | Restaurer un déploiement précédent. | `--yes`, `-y` | +| `fp fleet deploy MACHINE_ID` | **Remplace l'ensemble complet de politiques de la machine.** Affiche le plan et demande confirmation uniquement sur un terminal interactif sans `--json`. | `--add` ; `--remove` ; `--set` ; `--create` ; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | Comparer une machine à un autre déploiement. | — | +| `fp fleet history MACHINE_ID` | Déploiements passés pour une machine. | — | +| `fp fleet rollback MACHINE_ID GENERATION` | Rétablir l'ensemble de politiques d'une génération passée, comme nouvelle génération. | `--yes`, `-y` | | `fp fleet rename MACHINE_ID` | Donner un nom lisible à une machine. | `--name` obligatoire | ### Garde-fous -Ce que l'application a réellement fait. **Session uniquement**, même raison que ci-dessus. +Ce que l'application a réellement fait. **Session uniquement**, pour la même raison que ci-dessus. | Commande | Objectif | Options | | --- | --- | --- | -| `fp guardrails summary` | Couverture, totaux bloqués/évalués, une courbe sparkline des refus, et le tableau par politique. | `--since` (`1h`, `6h`, `24h`, `7d`) ; `--machine` | -| `fp guardrails timeline` | Décisions regroupées par intervalles sur la fenêtre, totalisées sur toutes les sources de politiques. | `--since` (`1h`, `6h`, `24h`, `7d`) ; `--machine` | +| `fp guardrails summary` | Couverture, totaux bloqués/évalués, sparkline des refus et tableau par politique. | `--since` (`1h`, `6h`, `24h`, `7d`) ; `--machine` | +| `fp guardrails timeline` | Décisions regroupées sur la fenêtre, totalisées pour toutes les sources de politique. | `--since` (`1h`, `6h`, `24h`, `7d`) ; `--machine` | -## Drapeaux globaux +## Indicateurs globaux -| Drapeau | Description | +| Indicateur | Description | | --- | --- | | `--json` | Émettre du JSON lisible par machine. | | `--base-url ` | Utiliser un tableau de bord auto-hébergé ou de développement. | | `--org ` | Sélectionner une organisation pour cette invocation. | | `--token ` | Remplacer le jeton de session utilisateur enregistré. | | `--api-key ` | Authentifier l'automatisation avec une clé API ; jamais enregistrée. | -| `--timeout ` | Délai d'expiration HTTP ; doit être positif. Défaut : `30`. | +| `--timeout ` | Délai HTTP ; doit être positif. Par défaut : `30`. | | `--quiet`, `-q` | Supprimer la sortie de statut sur stderr. | | `--no-color` | Désactiver la sortie colorée. | -| `--insecure` / `--secure` | Désactiver ou restaurer la vérification du certificat TLS. | -| `--version` | Afficher la version installée et quitter. | +| `--insecure` / `--secure` | Désactiver ou restaurer la vérification des certificats TLS. | +| `--version` | Afficher la version non emballée et quitter. | | `--help`, `-h` | Afficher l'aide. | `--api-key` est destiné à l'automatisation. La connexion, le changement d'organisation et les commandes d'assistant nécessitent une session utilisateur. @@ -382,18 +382,18 @@ Ce que l'application a réellement fait. **Session uniquement**, même raison qu | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | Déplacer le répertoire de configuration CLI (défaut `~/.failproofai/fpcli`). | -| `FP_ANALYTICS_DISABLED` ou `DO_NOT_TRACK` | Désactiver l'analyse CLI anonyme. | +| `FP_HOME` | Déplacer le répertoire de configuration de la CLI (par défaut `~/.failproofai/fpcli`). | +| `FP_ANALYTICS_DISABLED` ou `DO_NOT_TRACK` | Désactiver les analyses CLI anonymes. | | `NO_COLOR` | Désactiver la sortie colorée. | -Les drapeaux explicites remplacent les variables d'environnement, qui remplacent la configuration enregistrée. En mode clé API, sélectionnez explicitement le tenant avec `--org` ou `FP_ORG`. +Les indicateurs explicites remplacent les variables d'environnement, qui remplacent la configuration enregistrée. En mode clé API, sélectionnez le tenant explicitement avec `--org` ou `FP_ORG`. - Les variantes `AGENTEYE_*` de ces variables **ne sont pas lues par `fp`** et ne l'ont jamais été — la CLI déclare `FP_*` (`fp_cli/app.py`), et une variable inconnue n'est pas une erreur. Définir `AGENTEYE_DASHBOARD_URL` ne redirige pas la CLI ; elle est ignorée et la commande s'exécute silencieusement contre le tableau de bord enregistré. + Les orthographes `AGENTEYE_*` de ces variables **ne sont pas lues par `fp`** et ne l'ont jamais été — la CLI déclare `FP_*` (`fp_cli/app.py`), et une variable inconnue n'est pas une erreur. Définir `AGENTEYE_DASHBOARD_URL` ne redirige pas la CLI ; elle est ignorée et la commande s'exécute silencieusement contre le tableau de bord enregistré. - `AGENTEYE_HOME` et `AGENTEYE_ENVIRONMENT` existent toujours, mais ils appartiennent au **collecteur et au SDK de télémétrie**, et non à cette CLI. + `AGENTEYE_HOME` et `AGENTEYE_ENVIRONMENT` existent toujours, mais ils appartiennent au **collecteur et au SDK de télémétrie**, pas à cette CLI. - Les commandes qui suppriment, révoquent, masquent, résolvent ou remplacent une configuration demandent une confirmation par défaut. N'utilisez `--yes` qu'après avoir vérifié l'organisation active et la cible. + Les commandes qui suppriment, révoquent, inhibent, résolvent ou remplacent une configuration demandent confirmation par défaut. N'utilisez `--yes` qu'après avoir vérifié l'organisation active et la cible. \ No newline at end of file diff --git a/docs/fr/reference/custom-agents.mdx b/docs/fr/reference/custom-agents.mdx index 6edb8bdc..ce2feca0 100644 --- a/docs/fr/reference/custom-agents.mdx +++ b/docs/fr/reference/custom-agents.mdx @@ -1,17 +1,17 @@ --- title: "Agents personnalisés" -description: "Configuration, catalogue d'événements, règles de corrélation et livraison pour failproofai-sdk." +description: "Configuration, le catalogue d'événements, les règles de corrélation et la livraison pour failproofai-sdk." icon: "python" --- -Tout ce que font chaque paramètre, méthode et champ. Si vous instrumentez pour la première fois, commencez par le guide — cette page sert de référence. +Ce que font chaque paramètre, méthode et champ. Si vous instrumentez pour la première fois, commencez par le guide — cette page sert de référence. - Installation, instrumentation, méthodes d'événements, exemple complet et problèmes courants. + Installation, instrumentation, les méthodes d'événements, un exemple concret et les problèmes courants. - LangChain, CrewAI, LlamaIndex et Pydantic AI s'instrumentent automatiquement en un seul appel. + LangChain, CrewAI, LlamaIndex et Pydantic AI s'instrumentent eux-mêmes en un seul appel. @@ -23,24 +23,30 @@ Python 3.10 ou supérieur. Aucune dépendance d'exécution. pip install failproofai-sdk ``` -Le package s'installe sous le nom `failproofai-sdk` et s'importe en Python sous `failproofai_sdk`. Les extras de framework tels que `failproofai-sdk[langgraph]` installent le framework lui-même ; les adaptateurs sont toujours inclus dans la roue de base. +Le paquet est installé sous le nom `failproofai-sdk` et importé en Python sous `failproofai_sdk`. Les extras de framework tels que `failproofai-sdk[langgraph]` installent le framework lui-même ; les adaptateurs sont toujours inclus dans le wheel de base. -## Connecter le démon Failproof +## Connexion au daemon Failproof - - 1. Allez dans **Admin → Clés** et créez une clé avec `events:add`. - 2. [Connectez le démon Failproof au Cloud](/fr/start/setup#connect-a-machine-to-cloud) sur la machine de l'agent. - 3. Lancez une session instrumentée, puis trouvez son identifiant exact dans **Observer → Événements**. - 4. Allez dans **Observer → Sessions**, sélectionnez le même environnement et ouvrez la trace reconstruite. + + 1. Accédez à **Admin → Keys** et créez une clé avec `events:add`. + 2. [Connectez le daemon Failproof au Cloud](/fr/start/setup#connect-a-machine-to-cloud) sur la machine de l'agent. + 3. Lancez une session instrumentée, puis retrouvez son ID exact sous **Observe → Events**. + 4. Allez dans **Observe → Sessions**, sélectionnez le même environnement et ouvrez la trace reconstruite. - ![Session d'un agent Python personnalisé reconstruite sous forme de graphe d'exécution et de trace d'événements ordonnée.](/images/dashboard/session-detail.png) + ![Une session d'agent Python personnalisé reconstruite sous forme de graphe d'exécution et de trace d'événements ordonnée.](/images/dashboard/session-detail.png) + Lisez la clé `events:add` dans le shell. `read -s` la saisit via une invite qui n'affiche pas la saisie, de sorte qu'elle n'apparaît jamais dans une commande ni dans l'historique du shell : + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Configurez ensuite la machine et vérifiez qu'elle est bien connectée : + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -58,32 +64,32 @@ failproofai_sdk.configure( ) ``` -| Argument | Rôle | +| Argument | Ce qu'il fait | | --- | --- | -| `environment` | Le libellé apposé sur chaque événement — `production`, `staging`, `prod-eu`. Par défaut `dev`. | +| `environment` | Le label apposé sur chaque événement — `production`, `staging`, `prod-eu`. Par défaut `dev`. | | `flush_interval` | Fréquence à laquelle le thread en arrière-plan écrit sur le disque, en secondes. Par défaut `0.5`. | -| `base_dir` | Répertoire d'écriture. Par défaut le spool du démon, ce qui convient sauf si vous savez ce que vous faites. | +| `base_dir` | Où écrire. Par défaut dans le spool du daemon, ce qui convient sauf si vous savez ce que vous faites. | -Définition par variable d'environnement : +Configurable via variable d'environnement : -| Variable | Rôle | +| Variable | Ce qu'elle fait | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | Définit `environment` sans modifier le code, pour les cas où le libellé appartient au déploiement plutôt qu'à l'application. Un argument `configure()` a la priorité. | -| `FAILPROOFAI_HOME` | Déplace la racine Failproof AI qui contient le spool. | -| `FAILPROOFAI_SDK_STRICT` | `1` fait lever une exception en cas d'erreur d'instrumentation au lieu de la journaliser. | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` fait lever une exception en cas de problème de compatibilité avec un framework, au lieu d'un avertissement. | +| `AGENTEYE_ENVIRONMENT` | Définit `environment` sans modification du code, pour que le label appartienne au déploiement plutôt qu'à l'application. Un argument `configure()` a la priorité sur elle. | +| `FAILPROOFAI_HOME` | Déplace la racine de Failproof AI qui contient le spool. | +| `FAILPROOFAI_SDK_STRICT` | `1` fait lever une exception sur les erreurs d'instrumentation au lieu de les journaliser. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` fait lever une exception sur un problème de compatibilité de framework au lieu d'avertir et de continuer. | - **Pas de virgules dans `environment`.** L'ingest découpe ce champ sur les virgules pour construire ses filtres, et ignore tout événement dont le libellé en contient une — toute une exécution disparaît silencieusement. Écrivez `prod-eu`, et non `prod,eu`. + **Pas de virgules dans `environment`.** L'ingestion divise ce champ sur les virgules pour construire ses filtres, et ignore tout événement dont le label en contient une — une exécution entière disparaît silencieusement. Écrivez `prod-eu`, pas `prod,eu`. - `configure(environment="prod,eu")` lève une exception immédiatement. `AGENTEYE_ENVIRONMENT` ne peut pas lever d'exception — personne ne vous appelle — il émet donc un avertissement une seule fois et revient à `dev`. + `configure(environment="prod,eu")` lève une exception pour que vous le sachiez immédiatement. `AGENTEYE_ENVIRONMENT` ne peut pas lever d'exception — rien ne vous appelle — donc il émet un avertissement une seule fois et revient à `dev`. -Les événements sont mis en file d'attente en mémoire et écrits en arrière-plan toutes les `flush_interval` secondes, avec un vidage final à la sortie de l'interpréteur. Un processus tué brutalement perd ce qui n'avait pas encore été écrit. +Les événements sont mis en file d'attente en mémoire et écrits en arrière-plan toutes les `flush_interval` secondes, avec un flush final à la sortie de l'interpréteur. Un processus tué brutalement perd tout ce qui n'avait pas encore été écrit. ## Identité -Chaque événement appartient à une session et un agent. **Les contextes renseignent les deux**, vous n'avez donc rarement besoin de les passer explicitement : +Chaque événement appartient à une session et à un agent. **Les scopes remplissent les deux**, vous n'avez donc rarement besoin de les passer : ```python with failproofai_sdk.session(): @@ -91,15 +97,15 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Passer `session_id` ou `agent_id` explicitement fonctionne toujours et a la priorité. Si ni l'un ni l'autre n'est lié ou passé, l'appel lève `TypeError` plutôt que d'émettre un événement que Cloud ignorerait silencieusement. +Passer `session_id` ou `agent_id` explicitement fonctionne toujours et a la priorité. Si ni l'un ni l'autre n'est lié ou passé, l'appel lève une `TypeError` plutôt que d'émettre un événement que Cloud ignorerait silencieusement. - L'identité repose sur des variables de contexte. Elle suit les tâches `asyncio` automatiquement, mais **pas** les nouveaux threads — encapsulez un worker dans `failproofai_sdk.propagate()` ou ses événements seront non rattachés. + L'identité est portée par des variables de contexte. Elle suit automatiquement les tâches `asyncio`, mais **pas** les nouveaux threads — enveloppez un worker dans `failproofai_sdk.propagate()` sinon ses événements se retrouvent sans rattachement. ## Catalogue d'événements -Quinze méthodes. La plupart viennent par **paires** — vous appelez l'ouvrante, puis la fermante, et le SDK mesure l'écart. +Quinze méthodes. La plupart se présentent en **paires** — vous appelez l'ouvreur, puis le fermeur, et le SDK mesure l'intervalle. | | Ouvre | Ferme | | --- | --- | --- | @@ -114,9 +120,9 @@ Trois sont autonomes : `error`, `human_pause`, `human_interrupt`. -Chaque méthode accepte également `session_id` et `agent_id`, que les contextes renseignent pour vous. Tout ce qui est laissé à `None` est abandonné plutôt qu'envoyé comme `null` JSON, et chaque méthode retourne `None`. +Chaque méthode accepte également `session_id` et `agent_id`, que les scopes remplissent pour vous. Tout ce qui est laissé à `None` est omis plutôt qu'envoyé en JSON `null`, et chaque méthode retourne `None`. -| Méthode | Obligatoire | Optionnel | +| Méthode | Requis | Optionnel | | --- | --- | --- | | `agent_start` | — | `goal`, `parent_id` | | `agent_end` | — | `outcome`, `summary` | @@ -137,14 +143,14 @@ Chaque méthode accepte également `session_id` et `agent_id`, que les contextes - Pour marquer une exécution comme échouée, `outcome` doit être l'une des valeurs suivantes : `failed`, `error`, `timeout` ou `rejected`. Toute autre valeur — y compris la proche variante `"failure"` — est comptée comme un succès. + Pour marquer une exécution comme échouée, `outcome` doit être l'une des valeurs suivantes : `failed`, `error`, `timeout` ou `rejected`. Toute autre valeur — y compris la quasi-correspondance `"failure"` — est considérée comme un succès. ## Appariement et durée -**Une seule règle : donnez à l'événement de fermeture le même identifiant que son ouvreur.** C'est ce qui les apparie et ce qui permet au SDK de mesurer l'écart. +**Une seule règle : donnez à l'événement fermant le même id que son ouvreur.** C'est ce qui les apparie et ce qui permet au SDK de mesurer l'intervalle. -| Paire | Appariée sur | +| Paire | Mise en correspondance sur | | --- | --- | | `tool_use` → `tool_result` | `tool_call_id` | | `hook_triggered` → `hook_completed` | `hook_id` | @@ -154,15 +160,15 @@ Chaque méthode accepte également `session_id` et `agent_id`, que les contextes **Ne passez pas `duration_ms` vous-même.** Le SDK le mesure, et le passer lève une `ValueError`. -La seule exception est `model_response`, où seul vous connaissez la vraie latence du fournisseur. Passez un nombre entier de millisecondes — un float lève une exception, car la colonne est un entier 32 bits et resterait sinon vide. +La seule exception est `model_response`, où seul vous connaissez la latence réelle du fournisseur. Passez un nombre entier de millisecondes — un float lève une exception, car la colonne est un entier 32 bits et serait sinon vide. -- **Les identifiants doivent seulement être uniques par type et par session.** Un appel d'outil et un hook peuvent partager le même ; deux sessions simultanées peuvent réutiliser les mêmes identifiants sans collision. -- **Ils ne sont pas limités à un agent.** Une paire ouverte sous un agent et fermée sous un autre est quand même appariée — ce qui est le cas normal dans le code multi-agents. -- **`request_id` est optionnel mais recommandé.** Sans lui, les événements de modèle sont appariés dans l'ordre d'arrivée, ce qui peut mener à des erreurs d'appariement entre deux appels simultanés dans le même agent. -- **Une paire répartie sur plusieurs processus** est quand même appariée dans Cloud, mais le SDK ne peut pas la chronométrer — aucun des processus n'a vu les deux moitiés. -- **Au maximum 10 000 ouvreurs peuvent attendre un fermant simultanément.** Au-delà, le plus ancien est supprimé, ce qui empêche une fuite de croître indéfiniment. +- **Les ids n'ont besoin d'être uniques que par type et par session.** Un appel d'outil et un hook peuvent partager le même ; deux sessions s'exécutant simultanément peuvent réutiliser les mêmes ids sans collision. +- **Ils ne sont pas limités à un agent.** Une paire ouverte sous un agent et fermée sous un autre est quand même mise en correspondance — ce qui est le cas normal dans du code multi-agents. +- **`request_id` est optionnel mais recommandé.** Sans lui, les événements de modèle sont appariés dans l'ordre d'arrivée, donc deux appels concurrents dans le même agent peuvent être mal appariés. +- **Une paire répartie sur plusieurs processus** est toujours mise en correspondance dans Cloud, mais le SDK ne peut pas la chronométrer — aucun processus n'a vu les deux moitiés. +- **Au maximum 10 000 ouvreurs attendent un fermeur à la fois.** Au-delà, le plus ancien est abandonné, de sorte qu'une fuite ne peut pas croître indéfiniment. @@ -180,18 +186,18 @@ failproofai_sdk.event.tool_use( Préférez les types JSON si vous souhaitez les interroger ultérieurement. Tout le reste — un UUID, un datetime, un `Decimal`, un set, des bytes, un objet modèle — est stocké sous forme de chaîne. - **Préfixez vos noms de champs.** Les extras sont appliqués en dernier, donc un champ nommé `model`, `tool_name` ou `outcome` écrasera silencieusement le vrai champ. Les adaptateurs de framework utilisent `fw_` ; faites de même et aucune collision ne sera possible. + **Préfixez vos noms de champs.** Les extras sont appliqués en dernier, donc un champ nommé `model`, `tool_name` ou `outcome` écrase silencieusement le vrai. Les adaptateurs de framework utilisent `fw_` ; faites de même et rien ne peut entrer en collision. - C'est également pourquoi un champ optionnel mal orthographié ne génère jamais d'erreur — il devient simplement un nouveau champ personnalisé. Si un champ standard est absent dans Cloud, vérifiez d'abord l'orthographe. + C'est aussi pourquoi un champ optionnel mal orthographié ne génère jamais d'erreur — il devient simplement un nouveau champ personnalisé. Si un champ standard est manquant dans Cloud, vérifiez l'orthographe en premier. -Ces cinq noms sont réservés et systématiquement rejetés : `timestamp`, `session_id`, `agent_id`, `type`, `environment`. +Ces cinq noms sont réservés et rejetés d'emblée : `timestamp`, `session_id`, `agent_id`, `type`, `environment`. ## Livraison et vérification - - Dans **Observer → Événements**, vérifiez que `agent_start` existe en premier et `agent_end` en dernier. Ensuite, ouvrez **Observer → Sessions** et confirmez que les événements de modèle, d'outil, humains, de hook et d'erreur apparaissent dans l'ordre prévu. Utilisez l'identifiant de session comme clé principale de dépannage. + + Dans **Observe → Events**, vérifiez que `agent_start` existe en premier et `agent_end` en dernier. Ouvrez ensuite **Observe → Sessions** et confirmez que les événements de modèle, d'outil, humains, de hook et d'erreur apparaissent dans l'ordre prévu. Utilisez l'ID de session comme clé principale de dépannage. ```bash @@ -203,14 +209,14 @@ Ces cinq noms sont réservés et systématiquement rejetés : `timestamp`, `sess -Si Cloud est vide, inspectez `$FAILPROOFAI_HOME/custom-agents/events`, sinon `~/.failproofai/custom-agents/events`. Les fichiers JSONL prouvent l'émission par le SDK ; un spool qui grossit indique un problème de configuration du démon ou de livraison, tandis qu'un spool vide pointe vers l'instrumentation ou la durée de vie du processus. +Si Cloud est vide, inspectez `$FAILPROOFAI_HOME/custom-agents/events`, sinon `~/.failproofai/custom-agents/events`. Les fichiers JSONL prouvent l'émission par le SDK ; un spool en croissance indique un problème de configuration du daemon ou de livraison, tandis qu'un spool vide indique un problème d'instrumentation ou de durée de vie du processus. - N'inspectez le spool que lorsque le démon est arrêté. Pendant son fonctionnement, il collecte et supprime chaque lot en quelques millisecondes, de sorte qu'un listage du répertoire sera en compétition avec le collecteur et affichera bien moins d'événements que ceux émis. + N'inspectez le spool que lorsque le daemon est arrêté. Pendant son fonctionnement, il collecte et supprime chaque lot en quelques millisecondes, donc un listage de répertoire est en concurrence avec le collecteur et affiche bien moins d'événements que ce qui a été émis. ## Prévenir les défaillances dans un runtime personnalisé -Utilisez les résultats d'audit et les traces liées pour définir l'action non sécurisée, les preuves requises et la réponse attendue. Une intégration d'application des politiques personnalisée doit exposer l'action avant son exécution, transmettre son entrée structurée au moteur de politique, et appliquer la décision allow, instruct ou deny qui en résulte. +Utilisez les résultats d'audit et les traces liées pour définir l'action non sécurisée, les preuves requises et la réponse attendue. Une intégration d'application des politiques personnalisée doit exposer l'action avant son exécution, transmettre son entrée structurée au moteur de politiques et appliquer la décision allow, instruct ou deny qui en résulte. [Contactez Failproof AI](mailto:support@befailproof.ai) et nous vous aiderons à mapper les frontières de modèle, d'outil et de cycle de vie de votre runtime aux hooks de politique, puis à valider l'intégration avec vous. \ No newline at end of file diff --git a/docs/fr/reference/evaluator-sdk.mdx b/docs/fr/reference/evaluator-sdk.mdx index d97c5575..46744e76 100644 --- a/docs/fr/reference/evaluator-sdk.mdx +++ b/docs/fr/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "Créez un service qui évalue les sessions Failproof AI de manière synchrone ou asynchrone." +description: "Exécutez votre propre worker d'évaluation, pour les juges LLM et tout ce qu'un environnement Python hébergé ne peut pas faire." icon: "gauge" --- -Un évaluateur reçoit une session d'agent terminée et renvoie les signaux de qualité qui vous importent : des scores numériques, une explication pour chaque score et un résumé optionnel. Failproof AI stocke ces résultats à côté de la trace et les représente graphiquement à travers les agents et les environnements. +L'Evaluator SDK exécute des évaluations sur votre propre infrastructure. Votre worker enregistre ses évaluations auprès de Failproof AI, récupère les sessions à leur clôture, les note et soumet les résultats — le tout via HTTPS sortant : aucune connexion entrante n'est nécessaire. Utilisez-le pour ce que [Python hébergé](/fr/evaluations/write) ne peut pas faire : juges LLM, appels de modèles, packages, secrets et accès réseau. Ses résultats apparaissent aux côtés des résultats hébergés sur la [page des évaluations](/fr/sessions/evaluations), avec le tag **customer**. -## Configurer un évaluateur +Il est inclus dans `failproofai-sdk`, sous `failproofai_sdk.evaluator` ; l'importation du SDK de traçage ne le charge pas. - - - Installez le SDK et le serveur nécessaire pour l'exécuter. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - Créez `evaluator.py`. Cet exemple vérifie si une session contient des appels d'outils ayant échoué. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - Définissez un token partagé, démarrez l'évaluateur et vérifiez que son endpoint de santé répond. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - Dans un autre terminal : - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## Connecter l'évaluateur à Failproof AI +```bash +pip install failproofai-sdk +``` -1. Déployez l'évaluateur à une URL HTTPS accessible par Failproof AI Cloud. -2. Configurez `EVALUATOR_ENDPOINT` avec cette URL et définissez `EVALUATOR_TOKEN` avec le même token que celui utilisé par l'évaluateur. Pour le Cloud géré, contactez [support@befailproof.ai](mailto:support@befailproof.ai) afin de configurer la connexion. -3. Lancez une évaluation et confirmez que les scores apparaissent dans Failproof AI. +## Écrire des évaluations - - - Ouvrez une session terminée sous **Observe → Sessions** et sélectionnez **Run evaluation** si elle n'a pas été évaluée automatiquement. Consultez le statut, les scores, le raisonnement et le résumé dans le panneau **Evaluation** de la session. +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - Utilisez **Observe → Evaluations** pour comparer les scores entre agents ou environnements. Utilisez **Observe → Metrics** pour la latence, les coûts, les tokens et d'autres mesures numériques. - Commencez par une seule session pour confirmer que l'évaluateur a renvoyé les clés de scores attendues et un raisonnement pertinent pour cette exécution spécifique. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![Vue détaillée d'une session affichant les scores d'évaluation et le raisonnement à côté de sa trace.](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` enregistre une évaluation. La clé détermine sous quel nom ses résultats sont regroupés ; changez la version à chaque modification de la logique, et chaque résultat conserve la version qui l'a produit. Un seul worker peut contenir jusqu'à 100 évaluations. +- `result_kind` vaut `"score"` par défaut. Pour une évaluation de type `"metric"` ou `"assertion"`, nommez une entrée `metrics` ou `assertions` d'après la clé : c'est cette entrée qui constitue son résultat. +- `when` détermine si une session est applicable. Retournez `ConditionResult(False, "")` pour ignorer une session ; la raison est enregistrée. +- Une évaluation peut être une fonction ordinaire ou `async`, et `timeout_seconds` en limite la durée. +- Les clés de payload — `tool_name`, `response` et `content` ci-dessus — correspondent à ce que vos agents envoient ; lisez-les depuis une vraie session. - Une fois que les résultats individuels semblent corrects, utilisez le tableau de bord d'évaluation pour comparer ces scores dans le temps et entre agents ou environnements. +## Démarrer le worker - ![Tableau de bord qualité représentant graphiquement les scores de l'évaluateur au fil du temps.](/images/dashboard/dashboard-quality.png) +Placez une clé avec la permission `evaluations:run`, créée sous **Administration → Keys**, dans `FAILPROOFAI_EVALUATOR_TOKEN` — configurez-la depuis votre gestionnaire de secrets plutôt qu'en la saisissant directement dans une commande — puis démarrez le worker : - Un graphique sain doit utiliser des noms de scores stables ; le changement d'une clé crée une série distincte. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -Pour une instance Cloud auto-hébergée, l'évaluation automatique est désactivée jusqu'à ce que `EVALUATOR_ENDPOINT` soit défini sur le processus serveur. Redémarrez le serveur après avoir modifié les variables d'environnement de l'évaluateur. +Sans le bloc `__main__`, `python -m failproofai_sdk.evaluator evaluator:app` produit le même résultat. -Le service expose `GET /health`, `GET /config`, `POST /evaluate` et optionnellement `GET /evaluate/{job_id}`. Renvoyez `JobPending` pour les traitements asynchrones et enregistrez `@app.job_lookup` afin que Failproof AI puisse interroger périodiquement le service. +| Variable | Valeur par défaut | Rôle | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | obligatoire | Adresse de Failproof AI : `https://app.befailproof.ai` pour le Cloud. HTTPS sauf si elle pointe vers le loopback | +| `FAILPROOFAI_EVALUATOR_TOKEN` | obligatoire | Une clé avec `evaluations:run` | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | Identifie ce worker | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | Nombre de sessions notées simultanément par ce worker | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Délai d'attente pour chaque requête vers Failproof AI | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | Durée d'attente d'un worker en cours d'arrêt pour les exécutions en cours | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | Autorise le HTTP non chiffré vers une URL qui n'est pas le loopback — voir l'avertissement ci-dessous | +| `FAILPROOFAI_EVALUATOR_MODULE` | aucune | Le `module:attribute` pour `python -m failproofai_sdk.evaluator` | -Lorsqu'un token est configuré, toutes les routes sauf celle de santé nécessitent le même bearer token que Failproof AI envoie en tant que `EVALUATOR_TOKEN`. + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` envoie tout en clair. Le worker transmet `FAILPROOFAI_EVALUATOR_TOKEN` en tant qu'en-tête `Authorization: Bearer` à chaque requête, et les transcripts qu'il récupère sont les sessions elles-mêmes — toute personne sur le chemin réseau peut donc lire les deux, et le token ainsi obtenu permet d'exécuter des évaluations jusqu'à sa rotation. À n'utiliser que sur un réseau de développement isolé. Partout ailleurs, l'URL doit être en HTTPS ; le loopback ne nécessite aucun flag. + -## Types du SDK +## Types de résultats | Type | Champs | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## Décorateurs et routes - -| Décorateur | Route | Requis | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | Oui | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | Lors du renvoi de `JobPending` | -| `@app.config` | `GET /config` | Non | - -Le SDK limite la taille des corps de requêtes d'évaluation à 25 Mio. Les champs de requête inconnus sont ignorés afin que les services restent compatibles au fur et à mesure que le contrat d'événements évolue. +| `Score` | `value` (0 à 1), `passed`, `unit` (défaut `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -## Retourner un travail asynchrone +Un `EvalResult` contient au moins un score, une métrique ou une assertion, et au plus 25, chacun sous une clé unique. -Utilisez `JobPending` lorsque l'évaluation ne peut pas se terminer dans une seule requête. L'identifiant de tâche est opaque pour Failproof AI et doit rester résolvable par votre service jusqu'à ce que le résultat soit collecté ou que le délai d'expiration du serveur soit atteint. +## La session -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| Champ ou méthode | Ce qu'il fournit | +| --- | --- | +| `session_id`, `agent_id`, `environment` | L'identité de la session | +| `started_at`, `ended_at` | Dates de début et de fin | +| `event_count`, `events` | La transcription complète et ordonnée | +| `count(event_type)` | Le nombre d'événements de ce type | +| `events_of_type(event_type)` | Ces événements, dans l'ordre | -La cadence d'interrogation est sélectionnée dans cet ordre : `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs`, puis `EVALUATOR_POLLING_INTERVAL_SECS` du serveur. Les valeurs sont limitées entre 1 seconde et 1 heure. Le plafond d'interrogation horloge murale par défaut du serveur est d'une heure. +Chaque événement contient `id`, `ts`, `event_type` et `payload`. -## Champs de requête et de réponse +## L'evaluator historique -| Champ | Type | Notes | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | Actuellement `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | Identité de session et environnement. | -| `started_at` | `datetime` | Horodatage du premier événement. | -| `ended_at` | `datetime \| None` | Présent lorsque la session a émis un événement de fin. | -| `events` | `list[AgentEvent]` | Flux d'événements ordonné complet. | -| `AgentEvent.id` | `int` | Identifiant de ligne d'événement backend. | -| `AgentEvent.ts` | `datetime` | Horodatage de l'événement. | -| `AgentEvent.event_type` | `str` | Famille d'événements, par exemple `tool_use`. | -| `AgentEvent.payload` | `dict[str, Any]` | Charge utile complète de l'événement. | -| `EvalResponse.scores` | `dict[str, float] \| None` | Dimensions numériques représentées dans les évaluations. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | Explications par score ; les clés doivent correspondre à `scores`. | -| `EvalResponse.summary` | `str \| None` | Récit global de l'évaluation. | - -## Paramètres de l'opérateur serveur - -L'évaluation automatique s'applique à l'ensemble du déploiement et reste désactivée lorsque `EVALUATOR_ENDPOINT` est absent. - -| Variable | Défaut | Rôle | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | non défini | URL de base du service évaluateur. | -| `EVALUATOR_TOKEN` | non défini | Bearer token partagé avec `Evaluator(token=...)`. | -| `EVALUATOR_WORKERS` | `2` | Workers du répartiteur concurrents. | -| `EVALUATOR_CLAIM_BATCH` | `4` | Sessions réclamées par passe du répartiteur. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Cadence d'interrogation asynchrone de secours. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Délai d'expiration de l'évaluateur par requête. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | Tentatives de livraison avant échec terminal. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | Cadence de rafraîchissement pour `/config`. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Durée maximale d'interrogation asynchrone horloge murale. | - -Le serveur peut également restreindre les organisations qui utilisent l'évaluateur global du déploiement. Traitez les modifications de l'endpoint, du token, des tentatives et du filtrage par organisation comme une configuration opérateur, et redémarrez ou rechargez le serveur après les avoir appliquées. - -## Sécurité et exploitation - -- Placez l'évaluateur derrière HTTPS lorsque le trafic traverse une frontière réseau non approuvée. -- Configurez un bearer token non vide et maintenez-le identique sur les deux services. -- Ne journalisez pas le token ni les prompts sensibles complets des charges utiles de requêtes. -- Rendez les handlers synchrones idempotents ; les tentatives peuvent répéter une requête. -- Persistez l'état des tâches asynchrones en dehors de la mémoire du processus en production. -- Utilisez des clés de scores stables. Renommer une clé crée une nouvelle série de graphique plutôt que de modifier l'ancienne. - -Le SDK émet des logs de cycle de vie structurés tels que `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` et les exceptions des handlers. Il ne configure pas les handlers de journalisation ; utilisez la configuration de journalisation de l'application hôte. \ No newline at end of file +L'Evaluator SDK précédent — un service HTTP que Failproof AI appelait à `EVALUATOR_ENDPOINT`, répondant sur `/evaluate` et interrogé via `JobPending` — est désormais retiré. Construisez vos nouveaux evaluators sur ce worker ; les opérateurs d'une instance auto-hébergée utilisant encore un service historique peuvent le maintenir le temps de la transition. \ No newline at end of file diff --git a/docs/fr/reference/failproof-cli.mdx b/docs/fr/reference/failproof-cli.mdx index 76677dae..45a6b01a 100644 --- a/docs/fr/reference/failproof-cli.mdx +++ b/docs/fr/reference/failproof-cli.mdx @@ -1,83 +1,101 @@ --- title: "Failproof AI CLI" -description: "Installez des hooks, gérez les politiques locales, connectez le Cloud et opérez le daemon local." +description: "Installez les hooks, gérez les politiques locales, connectez Cloud et pilotez le daemon local." icon: "terminal" --- -Installez le CLI local avec `npm install -g failproofai`. Lancez-le sans arguments pour ouvrir le tableau de bord des politiques locales. +Installez le CLI local avec `npm install -g failproofai`. Lancez-le sans argument pour ouvrir le tableau de bord des politiques locales. -Le paquet nécessite Node.js 20.9 ou une version plus récente. Bun 1.3 ou une version plus récente est pris en charge pour le développement et les installations depuis les sources. `failproofai configure` et `failproofai setup` sont des alias de `failproofai config` ; `failproofai p` est un alias de `failproofai policies`. +Le package nécessite Node.js 20.9 ou une version plus récente. Bun 1.3 ou une version plus récente est pris en charge pour le développement et les installations depuis les sources. `failproofai configure` et `failproofai setup` sont des alias de `failproofai config`. `failproofai policy`, `failproofai pack` et `failproofai p` sont tous des variantes de `failproofai policies` — les packs et les politiques individuelles constituaient trois commandes pour une même idée et n'en forment désormais plus qu'une. Les anciennes variantes fonctionnent toujours, à deux exceptions près : `pack list ` est désormais `policies show `, et `pack build` est désormais `publish`. ## Configurer une machine +Installez le CLI, puis lisez la clé machine dans le shell. `read -s` la saisit via une invite qui n'affiche pas les caractères, de sorte qu'elle n'apparaît jamais dans une commande : + ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +Configurez ensuite la machine et choisissez ce qu'elle doit appliquer : + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` -Lancez `failproofai` sans arguments pour ouvrir le tableau de bord des politiques locales. +`failproofai config` prend en charge l'intégralité de la configuration : il installe le service `failproofaid` (une seule fois en root, via `sudo -n` — jamais de saisie de mot de passe interactive), branche les hooks sur chaque CLI d'agent trouvé, et se connecte à Cloud lorsqu'une clé est disponible. Sans terminal — CI, conteneur, agent qui le pilote — il applique plutôt que de demander, et quitte avec le code 1 si une action demandée n'a pas eu lieu. + +Il ne choisit **aucune** politique. C'est le rôle de la deuxième commande : sans elle, une machine fraîchement configurée n'applique rien d'autre que la protection toujours active. + +Préférez la variable d'environnement à `--token` : un argument de ligne de commande est lisible depuis `ps` par tous les utilisateurs de la machine. C'est la seule protection qu'offre la variable — une clé saisie dans n'importe quelle commande, `export` inclus, finit quand même dans l'historique du shell, c'est pourquoi elle est lue avec `read -s` ci-dessus. En CI, définissez-la depuis le gestionnaire de secrets et désactivez la trace shell (`set -x`), sans quoi la trace l'affichera. + + + `--connect ` enrôle une machine **déjà configurée**. La commande retourne dès que l'enrôlement réussit — elle n'installe pas le daemon et ne branche aucun hook. Utilisez `failproofai config` (ou `failproofai config --token `) sur une machine qui n'a pas encore été configurée, sinon elle apparaîtra comme connectée alors qu'elle ne collecte et n'applique rien. + + +Exécutez `failproofai` sans argument pour ouvrir le tableau de bord des politiques locales. | Commande | Résultat | | --- | --- | -| `failproofai config` | Lance la configuration interactive de la machine | -| `failproofai config --connect --token ` | Connecte l'ingestion Cloud et la distribution des politiques | -| `failproofai config --status` | Affiche l'état de la connexion, du daemon, de la distribution et de la pause | -| `failproofai policies` | Liste les politiques intégrées, personnalisées, conventionnelles, de pack et gérées par le Cloud | -| `failproofai policies --install` | Installe les hooks et active les politiques | -| `failproofai policy add ` | Active une politique — intégrée, ou `:` depuis un pack installé | -| `failproofai policy remove ` | Désactive une politique, même convention de nommage | -| `failproofai policies --uninstall` | Désactive les politiques ou supprime les hooks du harnais | -| `failproofai pack list` | Liste les packs de politiques installés et toutes les politiques qu'ils contiennent | -| `failproofai pack add ` | Installe un pack de politiques depuis une release GitHub ; sans tag, prend la plus récente et l'épingle | -| `failproofai pack add --bundled` | Installe les politiques intégrées en tant que pack, depuis ce paquet, sans réseau | -| `failproofai pack build ` | Construit les trois fichiers de release pour un pack personnalisé | -| `failproofai pack remove ` | Désactive un pack installé | -| `failproofai audit` | Analyse l'historique local de l'agent et ouvre la vue d'audit locale | -| `failproofai audit --schedule [days] --email
` | Planifie des analyses locales récurrentes et envoie leurs résultats par e-mail | -| `failproofai audit --status` | Affiche l'adresse de rapport, l'intervalle et la prochaine analyse planifiée | +| `failproofai config` | Configure la machine : agents, daemon et Cloud si une clé est présente | +| `failproofai config --token ` | Configure et connecte en une seule passe, sans rien demander | +| `failproofai config --connect ` | Enrôle une machine **déjà** configurée — sans daemon ni hooks | +| `failproofai config --status` | Affiche l'état de la connexion, du daemon, de la livraison et des pauses | +| `failproofai policies` | Liste les politiques intégrées, personnalisées, conventionnelles, de packs et gérées par Cloud | +| `failproofai policies --install` | Branche les hooks sur vos CLIs d'agents. N'active aucune politique en soi | +| `failproofai policies add ` | Active une politique — intégrée, ou `:` depuis un pack installé | +| `failproofai policies remove ` | Désactive une politique, même convention de nommage | +| `failproofai policies --uninstall` | Désactive des politiques ou supprime les hooks du harness | +| `failproofai policies show /` | Contenu d'un pack, lu depuis son manifeste, avant installation | +| `failproofai policies show / --releases` | Toutes les versions publiées et celle actuellement installée | +| `failproofai policies add ` | Installe un pack de politiques depuis une release GitHub ; sans tag, prend la plus récente et l'épingle | +| `failproofai publish` | Publie vos propres politiques sous forme de pack ; `--init` en génère un pour démarrer | +| `failproofai policies remove ` | Désinstalle un pack | +| `failproofai audit` | Analyse l'historique local des agents et ouvre la vue d'audit locale | +| `failproofai audit --schedule [days] --email
` | Planifie des analyses locales récurrentes et envoie les résultats par e-mail | +| `failproofai audit --status` | Affiche l'adresse du rapport, l'intervalle et la prochaine analyse planifiée | | `failproofai audit --no-schedule` | Arrête les analyses récurrentes sans supprimer l'historique d'audit | | `failproofai harness list` | Liste les chemins de capture supplémentaires | | `failproofai flush --wait` | Livre le spool d'événements courant | -| `failproofai backfill --since 30d` | Relit l'historique précédemment parcouru | +| `failproofai backfill --since 30d` | Relit l'historique précédemment traité | | `failproofai config --pause [duration]` | Met en pause une session locale pendant 30 minutes par défaut, jusqu'à 8 heures | -| `failproofai config --resume` | Reprend une session locale en pause ; ajoutez `--all` pour effacer toutes les pauses | -| `failproofai update` | Finalise les migrations de paquet et met à jour le daemon | -| `failproofai migrate --dry-run` | Prévisualise ou exécute les migrations de disposition du répertoire personnel en attente | -| `failproofai uninstall` | Supprime les hooks et le daemon avant de désinstaller le paquet | -| `failproofai --version` | Affiche la version du paquet installé | -| `failproofai --help` | Affiche les commandes et l'utilisation globale | +| `failproofai config --resume` | Reprend une session locale en pause ; ajoutez `--all` pour lever toutes les pauses | +| `failproofai update` | Finalise les migrations de packages et met à jour le daemon | +| `failproofai migrate --dry-run` | Prévisualise ou exécute les migrations de structure du répertoire personnel en attente | +| `failproofai uninstall` | Supprime les hooks et le daemon avant de désinstaller le package | +| `failproofai --version` | Affiche la version du package installé | +| `failproofai --help` | Affiche les commandes et l'aide générale | ## Options de configuration -| Option | Utilisation | +| Option | Usage | | --- | --- | -| `--connect --token ` | Connexion non interactive | +| `--token ` | Configure et connecte de manière non interactive ; également lu depuis `FAILPROOFAI_CLOUD_TOKEN` | +| `--url ` | Connecte à une URL autre que `app.befailproof.ai` ; également lu depuis `FAILPROOFAI_CLOUD_URL` | +| `--connect ` | Enrôle uniquement, sur une machine déjà configurée. Ignore le daemon et tous les hooks | | `--machine-id ` | Définit l'identifiant stable de la machine | -| `--machine-label ` | Définit ou modifie le libellé du tableau de bord | +| `--machine-label ` | Renomme une machine **déjà connectée**. Seul, il n'exécute jamais la configuration ; à utiliser après `failproofai config`, pas pendant | | `--no-transcripts` | Envoie les décisions sans le contenu des transcripts | | `--disconnect` | Arrête les téléchargements de politiques Cloud et la livraison d'événements | -| `--status` | Affiche l'état courant de la machine | +| `--status` | Affiche l'état actuel de la machine | | `--pause [duration]` | Met en pause la session la plus récente dans le répertoire courant ; accepte des secondes, minutes ou heures, par défaut 30 minutes | | `--resume` | Termine une pause correspondante avant son expiration | -| `--session ` | Cible une session explicite pour la pause ou la reprise | +| `--session ` | Cible une session explicite pour la mise en pause ou la reprise | | `--all` | Avec `--resume`, termine toutes les pauses actives | -Les pauses locales suspendent les politiques intégrées, personnalisées, conventionnelles et de pack pour une session. Elles expirent toujours et ne désactivent pas les politiques gérées par le Cloud. `block-failproofai-commands` — toujours activé et ne pouvant lui-même être désactivé ni mis en pause — empêche un agent instrumenté d'utiliser cette échappatoire. +Les pauses locales suspendent les politiques intégrées, personnalisées, conventionnelles et de packs pour une session. Elles expirent toujours et ne désactivent pas les politiques gérées par Cloud. `block-failproofai-commands` — toujours active et ne pouvant être désactivée ni mise en pause — empêche un agent instrumenté d'utiliser cette échappatoire lui-même. ## Options des politiques -| Option | Utilisation | +| Option | Usage | | --- | --- | -| `--install`, `-i` | Active les politiques et installe les hooks du harnais | -| `--uninstall`, `-u` | Désactive les politiques ou supprime les hooks | -| `--cli ` | Cible un ou plusieurs harnais pris en charge | +| `--install`, `-i` | Installe les hooks du harness. Les noms qui suivent activent ces politiques ; sans nom, aucune politique n'est modifiée | +| `--uninstall`, `-u` | Désactive des politiques ou supprime les hooks | +| `--cli ` | Cible un ou plusieurs harnesses pris en charge | | `--scope user\|project\|local\|all` | Choisit la portée de configuration ; `all` est réservé à la désinstallation | -| `--beta` | Inclut les politiques en version bêta | +| `--beta` | Inclut les politiques en bêta | | `--custom`, `-c ` | Valide et charge un fichier de politique personnalisé ; répétable | ## Options de livraison et de maintenance @@ -90,9 +108,9 @@ Les pauses locales suspendent les politiques intégrées, personnalisées, conve | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` doit être exécuté après `npm install -g failproofai@latest` ; il effectue les migrations de disposition du répertoire personnel, installe le binaire daemon correspondant et redémarre le service. `--no-daemon` effectue uniquement la migration de disposition. +`failproofai update` doit être exécuté après `npm install -g failproofai@latest` ; il effectue les migrations de structure du répertoire personnel, installe le binaire daemon correspondant et redémarre le service. `--no-daemon` effectue uniquement la migration de structure. -## Chemins du harnais +## Chemins du harness ```text failproofai harness list [harness] @@ -100,11 +118,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -Les noms de harnais pris en charge sont `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` et `goose`. +Les noms de harness pris en charge sont `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` et `goose`. -Les libellés permettent d'identifier les IDs d'agents dérivés lorsque deux racines contiennent des copies du même projet. Les racines qui se chevauchent et les libellés en double sont rejetés pour éviter les collectes en double ou la corruption du curseur. La configuration des chemins supplémentaires se recharge sans redémarrage du daemon. +Les labels définissent des espaces de noms pour les identifiants d'agents dérivés lorsque deux racines contiennent des copies du même projet. Les racines qui se chevauchent et les labels dupliqués sont rejetés pour éviter les doublons de collecte ou la corruption du curseur. La configuration des chemins supplémentaires se recharge sans redémarrage du daemon. -Les environnements conteneurisés peuvent remplacer les chemins supplémentaires configurés dans les fichiers par une variable séparée par des virgules nommée `FAILPROOFAI__EXTRA_PATHS`, par exemple : +Les environnements conteneurisés peuvent remplacer les chemins de capture supplémentaires configurés par fichier par une variable séparée par des virgules nommée `FAILPROOFAI__EXTRA_PATHS`, par exemple : ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -112,28 +130,30 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Variables d'environnement -Utilisez les fichiers de configuration pour le comportement persistant de la machine. Les variables d'environnement sont surtout utiles pour les conteneurs, les tests et un seul processus. +Utilisez les fichiers de configuration pour le comportement persistant de la machine. Les variables d'environnement sont particulièrement utiles pour les conteneurs, les tests et les processus uniques. -| Variable | Utilisation | +| Variable | Usage | | --- | --- | -| `FAILPROOFAI_HOME` | Déplace l'ensemble de la disposition `~/.failproofai` | -| `FAILPROOFAI_LOG_LEVEL` | Définit le niveau de verbosité des journaux locaux | -| `FAILPROOFAI_HOOK_LOG_FILE` | Écrit les diagnostics des hooks dans le fichier sélectionné | +| `FAILPROOFAI_CLOUD_TOKEN` | La clé Cloud, à la place de `--token`. À préférer : un argument est lisible depuis `ps` par tous les utilisateurs. Définissez-la avec `read -s` ou depuis un gestionnaire de secrets CI, jamais en tapant la clé dans une commande, qui finit de toute façon dans l'historique du shell | +| `FAILPROOFAI_CLOUD_URL` | L'URL Cloud, à la place de `--url`. La même variable que lit le daemon | +| `FAILPROOFAI_HOME` | Déplace l'ensemble de la structure `~/.failproofai` | +| `FAILPROOFAI_LOG_LEVEL` | Définit la verbosité de la journalisation locale | +| `FAILPROOFAI_HOOK_LOG_FILE` | Écrit les diagnostics des hooks dans un fichier sélectionné | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | Désactive la télémétrie anonyme pour ce processus | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignore la configuration interactive au premier lancement | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignore la configuration interactive au premier démarrage | | `FAILPROOFAI_NO_AUTO_AUDIT=1` | Ignore l'audit local post-configuration | -| `FAILPROOFAI_LLM_BASE_URL` | Remplace le point de terminaison compatible OpenAI utilisé par les politiques LLM | +| `FAILPROOFAI_LLM_BASE_URL` | Remplace l'endpoint compatible OpenAI utilisé par les politiques LLM | | `FAILPROOFAI_LLM_API_KEY` | Fournit la clé API utilisée par les politiques LLM | | `FAILPROOFAI_LLM_MODEL` | Sélectionne le modèle utilisé par les politiques LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limite le temps de chargement des modules de politique personnalisés | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Refuse de télécharger des packs et des binaires daemon ; ce qui est installé continue à s'appliquer | -| `FAILPROOFAI_PACK_BASE_URL` | Télécharge les packs depuis un miroir au lieu de `github.com` | -| `FAILPROOFAI__EXTRA_PATHS` | Remplace les chemins de capture supplémentaires configurés pour un harnais | -| `NO_COLOR` | Désactive la sortie terminal en couleur | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limite le temps de chargement des modules de politiques personnalisées | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Refuse de télécharger des packs et des binaires daemon ; ce qui est installé continue d'être appliqué | +| `FAILPROOFAI_PACK_BASE_URL` | Télécharge les packs depuis un miroir plutôt que depuis `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | Remplace les chemins de capture supplémentaires configurés pour un harness | +| `NO_COLOR` | Désactive la sortie colorée dans le terminal | -Les variables de répertoire personnel spécifiques à un agent, telles que `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` et `OPENCLAW_HOME`, remplacent l'emplacement où Failproof AI découvre les sessions locales pour ce harnais. +Les variables de répertoire personnel spécifiques aux agents, telles que `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` et `OPENCLAW_HOME`, remplacent l'emplacement où Failproof AI découvre les sessions locales pour ce harness. -## Mettre en pause ou retirer une machine en toute sécurité +## Mettre en pause ou supprimer une machine en toute sécurité ```bash failproofai config --pause @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -La mise en pause d'une session locale ne désactive pas les politiques gérées par le Cloud. Restaurez les déploiements Cloud via le workflow d'application Cloud lorsque le déploiement lui-même pose problème. +La mise en pause d'une session locale ne désactive pas les politiques gérées par Cloud. Restaurez les déploiements Cloud via le workflow d'application Cloud lorsque le problème vient du déploiement lui-même. -Avant de supprimer le paquet npm, supprimez les hooks installés et le daemon : +Avant de supprimer le package npm, supprimez les hooks installés et le daemon : ```bash failproofai uninstall --dry-run @@ -151,8 +171,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -Lancez `failproofai --help` pour des détails spécifiques à votre version. +Exécutez `failproofai --help` pour des détails spécifiques à la version installée. - Exécutez `failproofai uninstall` avant `npm rm -g failproofai` ; npm ne supprime pas les hooks d'agent installés ni le service daemon. + Exécutez `failproofai uninstall` avant `npm rm -g failproofai` ; npm ne supprime pas les hooks d'agents installés ni le service daemon. \ No newline at end of file diff --git a/docs/fr/reference/harnesses.mdx b/docs/fr/reference/harnesses.mdx index 82d1f2c0..be68d7fd 100644 --- a/docs/fr/reference/harnesses.mdx +++ b/docs/fr/reference/harnesses.mdx @@ -1,80 +1,86 @@ --- title: "Harnais d'agents" -description: "Capturez les sessions et appliquez des politiques sur l'ensemble des 12 harnais d'agents pris en charge." +description: "Capturez les sessions et appliquez les politiques sur l'ensemble des 12 harnais d'agents supportés." icon: "plug-zap" --- -Un harnais est l'environnement dans lequel votre agent s'exécute réellement. Failproof AI en prend en charge douze, regroupés en deux catégories : +Un harnais désigne l'environnement dans lequel votre agent s'exécute réellement. Failproof AI en supporte douze, répartis en deux catégories : -- **CLI de codage** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Passerelles de chat et d'assistants** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistant auto-hébergé) +- **CLIs de développement** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **Passerelles de chat et d'assistant** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistant auto-hébergé) -Les mêmes politiques et le même historique de sessions s'appliquent quel que soit le harnais utilisé par un agent. Une couche d'adaptation unique mappe les noms d'événements natifs, les noms d'outils et les champs d'entrée d'outils de chaque harnais vers 29 événements canoniques avant l'exécution de toute politique. +Les mêmes politiques et le même historique de sessions s'appliquent quel que soit le harnais utilisé par l'agent. Une couche d'adaptation unifie les noms d'événements natifs, les noms d'outils et les champs d'entrée de chaque harnais en 29 événements canoniques avant qu'une politique ne s'exécute. -Un agent qui ne s'exécute dans **aucun** des douze harnais est instrumenté directement avec le [SDK Python](/fr/reference/custom-agents). Il s'agit d'un contrat différent, qu'il convient d'énoncer clairement : le SDK fournit le traçage, les sessions, les évaluations et les audits — **il n'applique pas les politiques de lui-même.** Bloquer une action non sécurisée avant son exécution nécessite un hook d'application à la limite des outils de votre runtime ; [contactez-nous](mailto:support@befailproof.ai) et nous l'adapterons. +Un agent qui ne s'exécute dans **aucun** des douze est instrumenté directement avec le [SDK Python](/fr/reference/custom-agents). Il s'agit d'un contrat différent, qu'il convient d'énoncer clairement : le SDK fournit le traçage, les sessions, les évaluations et les audits — **il n'applique pas les politiques de lui-même.** Bloquer une action non sécurisée avant son exécution nécessite un hook d'application au niveau de la frontière des outils de votre runtime ; [contactez-nous](mailto:support@befailproof.ai) et nous l'adapterons. -| Harnais | Portées de hook prises en charge | +| Harnais | Portées de hook supportées | | --- | --- | | Claude Code | Utilisateur, projet, local | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | Utilisateur, projet | | Factory Droid, Devin CLI, Antigravity CLI, Goose | Utilisateur, projet | | Hermes, OpenClaw | Utilisateur | -Chaque intégration normalise les noms d'événements de hook natifs, les noms d'outils et les champs d'entrée d'outils avant l'exécution des politiques. Une politique ne peut agir que sur les événements exposés par le harnais ; testez le comportement en fin de tour et les instructions sur le harnais et la version exacts que vous déployez. +Chaque intégration normalise ses noms d'événements de hook natifs, ses noms d'outils et ses champs d'entrée d'outils avant l'exécution des politiques. Une politique ne peut agir que sur les événements exposés par le harnais ; testez le comportement en fin de tour et les instructions sur le harnais et la version exacts que vous déployez. ## Capacités d'application -« Bloquer » signifie que le verdict retourné par l'adaptateur actuel est consommé par le harnais concerné. Le blocage post-outil peut remplacer le résultat présenté au modèle, mais ne peut pas annuler un effet de bord d'outil déjà produit. +« Bloquer » signifie que le verdict renvoyé par l'adaptateur actuel est consommé par le harnais concerné. Le blocage post-outil peut remplacer le résultat présenté au modèle, mais ne peut pas annuler un effet secondaire d'outil déjà survenu. -| Harnais | Événements de blocage vérifiés | Remarques sur l'observation seule ou le non-blocage | +| Harnais | Événements de blocage vérifiés | Observations ou mises en garde sur le non-blocage | | --- | --- | --- | | Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, et plusieurs événements de tâche/configuration | `PostToolUse`, le cycle de vie de session, les notifications et les événements post-échec sont observationnels. | | Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Le blocage post-outil remplace le résultat après exécution ; les événements de démarrage de session et de compaction sont observationnels dans l'adaptateur actuel. | | GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Le blocage post-outil remplace le résultat après exécution ; les événements de session et de notification sont observationnels. | | Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` et les événements de session sont observationnels. | -| OpenCode | `PreToolUse` | Les événements post-outil et de cycle de vie sont observationnels ; la gestion actuelle des arrêts constitue une orientation pour un tour ultérieur plutôt qu'une barrière vérifiée. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Les événements post-outil et de cycle de vie sont observationnels ; l'orientation d'arrêt s'applique à un tour ultérieur. | -| Hermes | `PreToolUse` | Les verdicts post-outil, de session et d'arrêt de sous-agent ne sont pas des barrières. | +| OpenCode | `PreToolUse` | Les événements post-outil et de cycle de vie sont observationnels ; la gestion actuelle des arrêts est une instruction pour un tour ultérieur plutôt qu'une vérification garantie. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Les événements post-outil et de cycle de vie sont observationnels ; l'instruction d'arrêt s'applique à un tour ultérieur. | +| Hermes | `PreToolUse` | Les verdicts post-outil, de session et d'arrêt de sous-agent ne sont pas des verrous. | | OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Les événements post-outil, de session, d'arrêt de sous-agent et de compaction sont observationnels. | | Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Les verdicts post-outil et d'arrêt de sous-agent sont observationnels. | | Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` conditionnel | Les hooks de permission ne s'exécutent pas dans tous les modes de permission ; les événements post-outil et de session sont observationnels. | -| Antigravity CLI | `PreToolUse`, `Stop` | Les verdicts sur les prompts utilisateur et post-outil sont observationnels ; les instructions de prompt peuvent néanmoins être injectées. | -| Goose | `PreToolUse` | Les événements de prompt utilisateur, post-outil et de session sont observationnels. Un hook d'arrêt de blocage natif existe en amont, mais n'est pas installé par l'adaptateur actuel. | +| Antigravity CLI | `PreToolUse`, `Stop` | Les verdicts d'invite utilisateur et post-outil sont observationnels ; des instructions d'invite peuvent néanmoins être injectées. | +| Goose | `PreToolUse` | Les événements d'invite utilisateur, post-outil et de session sont observationnels. Un hook d'arrêt natif bloquant existe en amont mais n'est pas installé par l'adaptateur actuel. | -Les capacités sont sensibles à la version. Effectuez de nouveaux tests après la mise à niveau d'un CLI d'agent, en particulier lorsqu'une politique repose sur le comportement des prompts, des arrêts, des permissions ou post-outil plutôt que sur la barrière pré-outil commune. +Les capacités dépendent de la version. Effectuez de nouveaux tests après la mise à jour d'un CLI d'agent, notamment lorsqu'une politique s'appuie sur le comportement d'invite, d'arrêt, de permission ou post-outil plutôt que sur la vérification pré-outil habituelle. ## Installer les hooks de capture et de politique - 1. Ouvrez **Administration → Clés** et créez une clé avec `events:add` et `policies:pull`, nommée selon la machine ou l'environnement. + 1. Ouvrez **Administration → Clés** et créez une clé avec `events:add` et `policies:pull`, nommée d'après la machine ou l'environnement. 2. Sur la machine cible, connectez le CLI local avec la clé affichée et installez les hooks du harnais. 3. Démarrez une nouvelle session d'agent, puis confirmez ses événements de hook et de session sous **Observer → Événements**. - 4. Ouvrez **Observer → Politique** pour la même fenêtre temporelle et confirmez qu'une décision de politique est attribuée à la machine. + 4. Ouvrez **Observer → politique** pour la même plage horaire et confirmez qu'une décision de politique est attribuée à la machine. - La connexion commence par une clé machine. Vérifiez qu'elle inclut les permissions d'ingestion et de distribution des politiques avant de copier son secret. + La connexion démarre avec une clé machine. Vérifiez qu'elle inclut les permissions d'ingestion et de livraison de politique avant de copier son secret. - ![Le tiroir de création de clé API permettant d'accorder les permissions d'ingestion d'événements et de distribution des politiques.](/images/dashboard/key-create.png) + ![Le panneau de création de clé API permettant d'accorder les permissions d'ingestion d'événements et de livraison de politique.](/images/dashboard/key-create.png) Après l'installation des hooks, le flux d'événements devrait afficher de nouveaux événements provenant de la machine et de l'environnement connectés. - ![Le flux d'événements en direct permettant de confirmer qu'un harnais nouvellement installé envoie des données.](/images/dashboard/events-stream.png) + ![Le flux d'événements en direct permettant de confirmer qu'un harnais nouvellement installé envoie bien des données.](/images/dashboard/events-stream.png) - Enfin, vérifiez que les décisions de politique sont attribuées à la même machine. Cela confirme que le harnais rapporte bien l'activité des politiques ainsi que les événements de trace. + Enfin, vérifiez que les décisions de politique sont attribuées à la même machine. Cela confirme que le harnais signale bien l'activité de politique ainsi que les événements de trace. ![La page Politique permettant de vérifier les décisions de politique d'un harnais nouvellement connecté.](/images/dashboard/policy-observe.png) - Installez les hooks pour tous les harnais détectés : + Lisez la clé machine dans le shell. `read -s` la saisit via une invite qui n'affiche pas la saisie, de sorte qu'elle n'apparaît jamais dans une commande ni dans l'historique du shell : ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Ou ciblez des harnais spécifiques et une portée de configuration : + Configurez ensuite la machine — cette opération câble les hooks pour chaque harnais détecté, installe le daemon et se connecte au Cloud : + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + La configuration n'active aucune politique par elle-même, c'est à cela que sert la seconde commande. + + Ou ciblez des harnais nommés et une portée de configuration : ```bash failproofai policies --install \ @@ -82,7 +88,7 @@ Les capacités sont sensibles à la version. Effectuez de nouveaux tests après --scope user ``` - La portée projet maintient la configuration des hooks avec un dépôt. La portée utilisateur couvre le travail sur l'ensemble des dépôts. Claude Code prend également en charge la portée locale ; la prise en charge varie selon le harnais et le CLI rejette les combinaisons non supportées. + La portée projet conserve la configuration des hooks avec un dépôt. La portée utilisateur couvre le travail sur plusieurs dépôts. Claude Code supporte également la portée locale ; la prise en charge varie selon le harnais et le CLI rejette les combinaisons non supportées. Vérifiez la machine et ses événements : @@ -98,9 +104,9 @@ Les capacités sont sensibles à la version. Effectuez de nouveaux tests après - Les chemins supplémentaires sont enregistrés sur la machine, pas dans le Cloud. Après en avoir ajouté un, ouvrez **Observer → Sessions**, filtrez par environnement de la machine et confirmez que les sessions issues du nouveau chemin apparaissent. Ouvrez une session et vérifiez l'agent, le harnais et les horodatages des événements avant de vous en servir dans un audit. + Les chemins supplémentaires sont enregistrés sur la machine, et non dans le Cloud. Après en avoir ajouté un, ouvrez **Observer → Sessions**, filtrez sur l'environnement de la machine et confirmez que les sessions issues du nouveau chemin apparaissent. Ouvrez une session et vérifiez l'agent, le harnais et les horodatages des événements avant de vous y fier dans un audit. - ![La liste des sessions filtrée par environnement recevant les données du chemin de capture supplémentaire.](/images/dashboard/sessions-list.png) + ![La liste des sessions filtrée sur l'environnement recevant des données du chemin de capture supplémentaire.](/images/dashboard/sessions-list.png) Ajoutez un chemin avec un libellé optionnel, puis inspectez les chemins configurés : diff --git a/docs/fr/reference/overview.mdx b/docs/fr/reference/overview.mdx index 507b26f7..156428cf 100644 --- a/docs/fr/reference/overview.mdx +++ b/docs/fr/reference/overview.mdx @@ -1,80 +1,83 @@ --- title: "Intégrations et référence" -description: "Connectez les harnais d'agents, SDK, CLI et l'API HTTP supportés." +description: "Connectez les harnais d'agents, SDKs, CLIs et l'API HTTP pris en charge." icon: "braces" --- -Choisissez l'intégration la plus proche de l'environnement où votre agent s'exécute déjà. +Choisissez l'intégration la plus proche de l'environnement dans lequel votre agent s'exécute déjà. - Installez des hooks pour les CLI d'agents de codage et autonomes supportés. + Installez des hooks pour les CLIs d'agents de codage et autonomes pris en charge. - + Instrumentez LangGraph, CrewAI, LlamaIndex, Pydantic AI, ou un agent personnalisé. - Configuration, le catalogue d'événements, les règles de corrélation et la livraison. + Configuration, catalogue d'événements, règles de corrélation et livraison. - Consultez les projets locaux, sessions, activités de politique et audits hors ligne. + Consultez les projets locaux, sessions, activité des politiques et audits hors ligne. - Configurez la capture locale, les hooks, les politiques, les audits, la livraison et l'état de la machine. + Configurez la capture locale, les hooks, les politiques, les audits, la livraison et l'état machine. Interrogez et administrez les sessions, audits, problèmes, alertes, clés, utilisateurs et paramètres Cloud. - - Notez des sessions complètes ou inactives avec un service FastAPI. + + Évaluez des sessions complètes ou inactives avec un service FastAPI. - Rédigez et testez des décisions allow, instruct et deny spécifiques à votre flux de travail. + Créez et testez des décisions allow, instruct et deny spécifiques à votre workflow. Déployez le plan de contrôle Cloud sur un cluster Kubernetes géré par le client. -La [référence de l'API HTTP](/fr/reference/http-api) générée couvre la surface publique `/v1`. Des pages rédigées manuellement expliquent les flux de travail qui s'étendent sur plusieurs endpoints ou utilisent des interfaces d'administration en dehors de cette surface publique. +La [référence de l'API HTTP](/fr/reference/http-api) générée couvre la surface publique `/v1`. Des pages rédigées manuellement expliquent les workflows qui s'étendent sur plusieurs endpoints ou utilisent des interfaces d'administration en dehors de cette surface publique. ## Connecter un agent et vérifier les données - 1. Ouvrez **Administration → Clés**, créez une clé avec `events:add` et `policies:pull`, et copiez le secret. + 1. Ouvrez **Administration → Clés**, créez une clé avec `events:add` et `policies:pull`, puis copiez le secret. 2. Configurez l'intégration en utilisant la page correspondante ci-dessus. 3. Ouvrez **Observer → Événements** pour confirmer que les événements arrivent, puis **Observer → Sessions** pour confirmer qu'ils forment des exécutions complètes. - 4. Filtrez selon l'environnement de l'intégration et inspectez une session pour vérifier les champs modèle, outil, erreur et politique nécessaires aux audits. + 4. Filtrez selon l'environnement de l'intégration et inspectez une session pour vérifier les champs modèle, outil, erreur et politique requis par les audits. - Commencez par le panneau de clés. Les autorisations sélectionnées déterminent si la machine peut envoyer des événements et recevoir des politiques gérées par Cloud. + Commencez par le tiroir de clé. Les droits sélectionnés déterminent si la machine peut envoyer des événements et recevoir des politiques gérées par le Cloud. - ![Le panneau de création de clé API utilisé pour accorder les permissions d'ingestion d'événements et de livraison de politiques.](/images/dashboard/key-create.png) + ![Le tiroir de création de clé API utilisé pour accorder les permissions d'ingestion d'événements et de livraison de politiques.](/images/dashboard/key-create.png) Après avoir connecté l'intégration, utilisez la liste des sessions pour confirmer que ses événements sont regroupés en exécutions complètes dans l'environnement attendu. - ![La liste des sessions utilisée pour vérifier qu'une intégration nouvellement connectée signale des exécutions d'agents complètes.](/images/dashboard/sessions-list.png) + ![La liste des sessions utilisée pour vérifier qu'une intégration nouvellement connectée signale des exécutions d'agent complètes.](/images/dashboard/sessions-list.png) Ouvrez l'une de ces sessions avant de considérer l'intégration comme terminée ; la trace doit contenir le modèle, l'outil, l'erreur et les preuves de politique dont vos audits ont besoin. - Créez une clé machine, connectez le démon Failproof et vérifiez la première session. + Créez une clé machine, puis lisez le secret qu'elle affiche dans le shell. `read -s` le capture via une invite qui n'affiche pas l'entrée, de sorte qu'il n'apparaît jamais dans une commande ni dans l'historique du shell : ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Connectez le démon Failproof et vérifiez la première session : - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - Utilisez `fp --json sessions ...` lorsqu'un autre outil doit consommer le résultat. Les indicateurs globaux tels que `--json`, `--org` et `--base-url` doivent être placés avant la commande. + Utilisez `fp --json sessions ...` lorsqu'un autre outil doit consommer le résultat. Les drapeaux globaux tels que `--json`, `--org` et `--base-url` doivent être placés avant la commande. Consultez la [référence du CLI Failproof AI](/fr/reference/failproof-cli) pour les commandes locales et la [référence du CLI Failproof Cloud](/fr/reference/cloud-cli#cli-commands) pour les commandes `fp`. diff --git a/docs/fr/reference/policy-sdk.mdx b/docs/fr/reference/policy-sdk.mdx index 41ffe6a1..31194c82 100644 --- a/docs/fr/reference/policy-sdk.mdx +++ b/docs/fr/reference/policy-sdk.mdx @@ -4,18 +4,18 @@ description: "Créez, testez et déployez des politiques JavaScript ou TypeScrip icon: "shield-plus" --- -Les politiques personnalisées transforment un schéma de défaillance issu de vos traces ou audits en une décision qui s'exécute pendant qu'un agent travaille. Une politique peut autoriser une action, fournir des instructions à l'agent, ou bloquer l'action avant qu'elle ne provoque un nouvel incident. +Les politiques personnalisées transforment un schéma de défaillance issu de vos traces ou audits en une décision exécutée pendant qu'un agent travaille. Une politique peut autoriser une action, fournir des conseils à l'agent ou bloquer l'action avant qu'elle ne provoque un nouvel incident. -Utilisez une politique personnalisée lorsque le comportement dépend de vos outils, chemins, commandes, environnements ou règles de fonctionnement. Consultez d'abord le [catalogue de politiques intégrées](/fr/policies/builtin-catalog) pour ne pas recréer un contrôle existant. +Utilisez une politique personnalisée lorsque le comportement dépend de vos outils, chemins, commandes, environnements ou règles de fonctionnement. Consultez d'abord le [pack de politiques Failproof AI](/fr/policies/packs) pour ne pas recréer un contrôle existant. ## Créer une politique personnalisée - 1. Accédez à **Admin → éditeur de politiques**, sélectionnez **Nouvelle politique** et décrivez la défaillance que vous souhaitez prévenir. + 1. Allez dans **Admin → éditeur de politiques**, sélectionnez **Nouvelle politique** et décrivez la défaillance que vous souhaitez prévenir. 2. Ajoutez le code source de la politique, puis testez les correspondances attendues et les non-correspondances sûres dans l'éditeur. Résolvez toutes les erreurs de validation. 3. Enregistrez le brouillon et sélectionnez **Publier la version** pour créer une version immuable. - 4. Accédez à **Admin → application**, déployez la version sur une machine de test en mode **observe**, puis vérifiez ses décisions sous **Observe → politique** avant de l'appliquer. + 4. Allez dans **Admin → application**, déployez la version sur une machine de test en mode **observation** et vérifiez ses décisions sous **Observer → politique** avant de l'appliquer. ![L'éditeur de politiques utilisé pour créer et publier une politique personnalisée.](/images/dashboard/policy-editor.png) @@ -23,13 +23,13 @@ Utilisez une politique personnalisée lorsque le comportement dépend de vos out 1. Créez `.failproofai/policies/checkout-policies.ts`. Le nom de fichier doit se terminer par `policies.js`, `policies.mjs` ou `policies.ts`. 2. Enregistrez une ou plusieurs politiques avec `customPolicies.add()`. 3. Validez et installez le fichier avec `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. - 4. Déclenchez une action correspondante et une action sûre. Exécutez `failproofai policies`, puis inspectez les décisions attribuées sous **Observe → politique**. + 4. Déclenchez une action correspondante et une action sûre. Exécutez `failproofai policies`, puis inspectez les décisions attribuées sous **Observer → politique**. ## Commencer par une règle ciblée -Cette politique bloque les commandes Kubernetes destructrices uniquement lorsque la commande cible la production. Tout ce qui se trouve en dehors de ce schéma de défaillance précis retourne `allow()`. +Cette politique bloque les commandes Kubernetes destructives uniquement lorsque la commande cible la production. Tout ce qui se situe en dehors de ce cas de défaillance précis renvoie `allow()`. ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,23 +55,23 @@ customPolicies.add({ }); ``` -Les bonnes politiques sont suffisamment ciblées pour être expliquées en une seule phrase. Correspondez à l'action observable — pas à l'intention que vous espérez que l'agent avait — et retournez `allow()` dès que la règle ne s'applique pas. +Les bonnes politiques sont suffisamment ciblées pour pouvoir être expliquées en une seule phrase. Ciblez l'action observable — pas l'intention que vous espérez de l'agent — et renvoyez `allow()` dès que la règle ne s'applique pas. ## Choisir une décision -| Aide | Résultat | À utiliser quand | +| Aide | Résultat | Quand l'utiliser | | --- | --- | --- | | `allow(reason?)` | L'opération continue. | La politique ne s'applique pas ou l'action est sûre. | -| `instruct(reason)` | L'opération continue avec des instructions là où le harnais le permet. | Vous souhaitez orienter l'agent vers une meilleure approche sans appliquer une contrainte. | -| `deny(reason)` | L'opération est bloquée lorsque l'événement et le harnais prennent en charge le blocage. | L'action ne doit pas se poursuivre. | +| `instruct(reason)` | L'opération continue avec des conseils lorsque l'environnement d'exécution le permet. | Vous souhaitez orienter l'agent vers une meilleure approche sans appliquer une invariante. | +| `deny(reason)` | L'opération est bloquée lorsque l'événement et l'environnement d'exécution prennent en charge le blocage. | L'action ne doit pas être effectuée. | -Rédigez la raison à l'intention de l'agent qui doit se rétablir. Expliquez ce qui a été détecté et ce qu'il devrait faire à la place. +Rédigez la raison à l'intention de l'agent qui doit récupérer la situation. Expliquez ce qui a été détecté et ce qu'il devrait faire à la place. - N'utilisez pas `instruct()` pour une limite de sécurité. La remise des instructions varie selon le harnais d'agent. Utilisez `deny()` lorsque l'action doit être empêchée. + N'utilisez pas `instruct()` pour délimiter une frontière de sécurité. La livraison des conseils varie selon l'environnement d'exécution de l'agent. Utilisez `deny()` lorsque l'action doit être empêchée. -## Objet politique +## Objet de politique ```ts customPolicies.add({ @@ -82,34 +82,34 @@ customPolicies.add({ }); ``` -| Champ | Obligatoire | Description | +| Champ | Requis | Description | | --- | --- | --- | -| `name` | Oui | Identifiant stable de la politique. Conservez des noms uniques entre les fichiers. | +| `name` | Oui | Identifiant stable pour la politique. Assurez-vous que les noms sont uniques entre les fichiers. | | `description` | Non | Objectif lisible par l'humain, affiché dans les listes de politiques et les décisions. | | `match.events` | Non | Types d'événements qui invoquent la politique. Omettre `match` l'invoque pour chaque événement disponible. | -| `fn` | Oui | Fonction synchrone ou asynchrone qui retourne un résultat `allow`, `instruct` ou `deny`. | +| `fn` | Oui | Fonction synchrone ou asynchrone qui renvoie un résultat `allow`, `instruct` ou `deny`. | -Filtrez les outils à l'intérieur de `fn`. `match.toolNames` ne fait pas partie du type public de politique personnalisée. +Filtrez les outils à l'intérieur de `fn`. `match.toolNames` ne fait pas partie du type de politique personnalisée public. -## Contexte de la politique +## Contexte de politique Chaque politique reçoit un `PolicyContext`. | Champ | Type | Ce qu'il contient | | --- | --- | --- | | `eventType` | `HookEventType` | Événement normalisé en cours d'évaluation. | -| `toolName` | `string \| undefined` | Nom canonique de l'outil, par exemple `Bash`, `Read`, `Write` ou `Edit`. | +| `toolName` | `string \| undefined` | Nom canonique de l'outil, tel que `Bash`, `Read`, `Write` ou `Edit`. | | `toolInput` | `Record \| undefined` | Entrée canonique pour l'appel d'outil actuel. | -| `payload` | `Record` | Charge utile complète de l'événement normalisé. | -| `session` | `SessionMetadata \| undefined` | ID de session, répertoire de travail, chemin du transcript, mode de permission et métadonnées du harnais lorsque disponibles. | -| `cli` | `string \| undefined` | Harnais d'agent source, tel que `claude`, `codex` ou `cursor`. | +| `payload` | `Record` | Charge utile d'événement normalisée complète. | +| `session` | `SessionMetadata \| undefined` | ID de session, répertoire de travail, chemin de la transcription, mode de permission et métadonnées de l'environnement d'exécution lorsqu'ils sont disponibles. | +| `cli` | `string \| undefined` | Environnement d'exécution de l'agent source, tel que `claude`, `codex` ou `cursor`. | | `params` | `Record` | Paramètres de politique intégrés. Les politiques personnalisées reçoivent actuellement un objet vide. | -Traitez chaque valeur optionnelle comme réellement optionnelle. Les versions d'agents et les types d'événements ne fournissent pas tous les mêmes champs. +Traitez chaque valeur optionnelle comme réellement optionnelle. Les versions d'agent et les types d'événements ne fournissent pas tous les mêmes champs. ### Entrées d'outils courantes -Failproof AI normalise les outils courants à travers les harnais pris en charge, de sorte qu'une politique peut généralement utiliser une seule forme d'entrée. +Failproof AI normalise les outils courants entre les environnements d'exécution pris en charge, de sorte qu'une politique peut généralement utiliser une seule forme d'entrée. | Outil | Champs courants | | --- | --- | @@ -130,21 +130,21 @@ const filePath = String(ctx.toolInput?.file_path ?? ""); | Événement | Quand il s'exécute | Utilisation typique | | --- | --- | --- | -| `PreToolUse` | Avant l'exécution d'un outil. | Bloquer ou orienter les commandes, écritures, lectures et actions externes. | -| `PostToolUse` | Après le retour d'un outil. | Inspecter les résultats avant qu'ils n'atteignent l'agent. Un deny bloque l'intégralité du résultat ; il ne rédacte pas les champs sélectionnés. | -| `PermissionRequest` | Lorsque l'agent demande une permission. | Appliquer des règles de permission propres à l'organisation. | -| `UserPromptSubmit` | Avant qu'une invite soumise ne continue. | Rejeter les instructions interdites ou ajouter des instructions de flux de travail. | -| `Stop` | Lorsque l'agent tente de terminer. | Exiger une condition d'achèvement atteignable, comme une étape de vérification locale. | -| `SubagentStop` | Lorsqu'un sous-agent tente de terminer. | Contrôler le travail délégué avant qu'il ne retourne au parent. | +| `PreToolUse` | Avant l'exécution d'un outil. | Bloquer ou guider les commandes, les écritures, les lectures et les actions externes. | +| `PostToolUse` | Après le retour d'un outil. | Inspecter les résultats avant qu'ils n'atteignent l'agent. Un deny bloque l'intégralité du résultat ; il ne rédige pas les champs sélectionnés. | +| `PermissionRequest` | Lorsque l'agent demande une autorisation. | Appliquer des règles d'autorisation spécifiques à l'organisation. | +| `UserPromptSubmit` | Avant qu'une invite soumise ne continue. | Rejeter les instructions interdites ou ajouter des conseils de flux de travail. | +| `Stop` | Lorsque l'agent tente de terminer. | Exiger une condition de complétion accessible, telle qu'une étape de vérification locale. | +| `SubagentStop` | Lorsqu'un sous-agent tente de terminer. | Valider le travail délégué avant qu'il ne retourne au parent. | | `SessionStart` / `SessionEnd` | Aux limites de session. | Enregistrer ou vérifier l'état au niveau de la session. | -La disponibilité des événements et le comportement de blocage dépendent du harnais d'agent. Consultez [Harnais d'agents](/fr/reference/harnesses) avant de vous appuyer sur un événement dans une flotte mixte. +La disponibilité des événements et le comportement de blocage dépendent de l'environnement d'exécution de l'agent. Consultez [Environnements d'exécution des agents](/fr/reference/harnesses) avant de vous appuyer sur un événement dans une flotte mixte. - `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` et `Setup`. + `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch`, et `Setup`. -## Créer des schémas de politiques courants +## Créer des modèles de politiques courants ### Bloquer les écritures vers des chemins protégés @@ -166,7 +166,7 @@ customPolicies.add({ }); ``` -### Fournir des instructions non bloquantes +### Fournir des conseils non bloquants ```ts import { customPolicies, allow, instruct } from "failproofai"; @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### Contrôler l'achèvement de session +### Conditionner la fin de session ```ts import { execFileSync } from "node:child_process"; @@ -215,10 +215,10 @@ customPolicies.add({ ``` - Un événement `Stop` refusé peut amener l'agent à réessayer. Ne conditionnez l'achèvement qu'à une condition que l'agent peut satisfaire dans l'environnement actuel, et limitez chaque sous-processus ou appel réseau. + Un événement `Stop` refusé peut amener l'agent à réessayer. Ne conditionnez qu'à une condition que l'agent peut satisfaire dans l'environnement actuel, et limitez chaque sous-processus ou appel réseau. -## Charger des fichiers de politiques +## Charger des fichiers de politique ### Fichiers de convention @@ -232,9 +232,9 @@ Les fichiers de convention se chargent automatiquement : - Les répertoires de politiques du projet et de l'utilisateur sont tous deux chargés. - Les fichiers se chargent par ordre alphabétique dans chaque répertoire. - Un fichier doit se terminer par `policies.js`, `policies.mjs` ou `policies.ts`. -- Plusieurs appels `customPolicies.add()` dans un seul fichier sont pris en charge. +- Plusieurs appels `customPolicies.add()` dans un même fichier sont pris en charge. - Les imports relatifs depuis des modules locaux sont pris en charge. -- Les politiques de projet peuvent être committées afin que les mêmes règles suivent le dépôt. +- Les politiques de projet peuvent être archivées afin que les mêmes règles suivent le dépôt. ### Fichiers explicites @@ -247,7 +247,7 @@ failproofai policies --install \ --scope project ``` -Les fichiers explicites se chargent en premier, suivis des fichiers de convention du projet puis des fichiers de convention utilisateur. Un fichier découvert par les deux chemins n'est chargé qu'une seule fois. +Les fichiers explicites se chargent en premier, suivis des fichiers de convention du projet puis des fichiers de convention utilisateur. Un fichier découvert via les deux chemins n'est chargé qu'une seule fois. ## Valider et tester @@ -262,15 +262,15 @@ failproofai policies La validation détecte les fichiers manquants, les erreurs de syntaxe, les imports non résolus, les exceptions de niveau supérieur et les délais d'expiration de chargement de module. Elle ne prouve pas que votre logique de correspondance est correcte. -Testez au minimum ces cas : +Testez au moins ces cas : - Une action qui doit correspondre et produire la raison de politique prévue. -- Une action proche mais sûre qui doit retourner `allow()`. +- Une action proche mais sûre qui doit renvoyer `allow()`. - Des champs d'outil manquants ou malformés. -- Une syntaxe de commande alternative, des chemins, des guillemets, des casses et des espaces blancs. -- Un sous-processus ou une dépendance réseau non disponible. +- Une syntaxe de commande alternative, des chemins, des guillemets, des casses et des espaces blancs variés. +- Un sous-processus ou une dépendance réseau indisponible. -Attribuez le résultat à votre politique personnalisée sous **Observe → politique**. Un test bloqué n'est pas suffisant si c'est une autre politique intégrée qui a pris la décision. +Attribuez le résultat à votre politique personnalisée sous **Observer → politique**. Un test bloqué n'est pas suffisant si c'est une politique intégrée différente qui a pris la décision. ## Comportement à l'exécution @@ -278,26 +278,26 @@ Attribuez le résultat à votre politique personnalisée sous **Observe → poli - Le premier `deny` arrête l'évaluation des politiques suivantes. - Plusieurs résultats `instruct` peuvent être combinés lorsqu'aucune politique ne refuse l'événement. - Une fonction de politique dispose d'un délai d'exécution de 10 secondes. -- Une exception levée ou un délai d'expiration est journalisé et traité comme `allow()`. +- Une exception levée ou un délai d'expiration est enregistré et traité comme `allow()`. - Un fichier de convention qui échoue au chargement est ignoré ; les autres fichiers personnalisés et les politiques intégrées continuent. - Le chargement de module de niveau supérieur dispose également d'un délai de 10 secondes. -- Le mode observe cloud exécute la politique mais enregistre une décision non-allow sans l'appliquer. +- Le mode observation cloud exécute la politique mais enregistre une décision non-allow sans l'appliquer. -Conservez les modules de politiques déterministes et rapides. Évitez les appels réseau de niveau supérieur ou le démarrage de serveur. Limitez le travail à l'intérieur de `fn`, gérez les échecs de dépendances, et choisissez délibérément si cet échec doit autoriser ou refuser l'opération. +Gardez les modules de politique déterministes et rapides. Évitez les appels réseau de niveau supérieur ou le démarrage de serveur. Limitez le travail à l'intérieur de `fn`, gérez les échecs de dépendance et choisissez délibérément si cet échec doit autoriser ou bloquer l'opération. -## Exports API +## Exports de l'API | Export | Objectif | | --- | --- | | `customPolicies.add(policy)` | Enregistrer une politique personnalisée lors du chargement du module. | | `allow(reason?)` | Autoriser l'opération. | -| `instruct(reason)` | Autoriser l'opération et fournir des instructions là où c'est pris en charge. | +| `instruct(reason)` | Autoriser l'opération et fournir des conseils là où c'est pris en charge. | | `deny(reason)` | Bloquer l'opération là où c'est pris en charge. | -| `getCustomHooks()` | Retourner les politiques actuellement enregistrées dans le registre de modules. | +| `getCustomHooks()` | Retourner les politiques actuellement enregistrées dans le registre du module. | | `clearCustomHooks()` | Effacer ce registre, principalement pour les tests et les chargeurs. | TypeScript exporte `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` et `PolicyFunction`. - Publiez une version, déployez-la en mode observe, vérifiez les décisions et passez à l'application. + Publiez une version, déployez-la en mode observation, vérifiez les décisions et passez à l'application. \ No newline at end of file diff --git a/docs/fr/sessions/evaluations.mdx b/docs/fr/sessions/evaluations.mdx index 0a3eb574..b336ebac 100644 --- a/docs/fr/sessions/evaluations.mdx +++ b/docs/fr/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "Évaluations en ligne" -description: "Évaluez la qualité, la conformité, le coût et la latence des sessions en cours et terminées." +title: "Lire les résultats d'évaluation" +description: "Suivez les scores d'évaluation dans le temps, comparez agents et environnements, identifiez pourquoi une session a obtenu un score faible, et interrogez l'assistant." icon: "gauge" --- -Les évaluations en ligne appliquent des jugements cohérents aux sessions d'agent. Utilisez-les pour les signaux qui doivent être mesurés en continu plutôt qu'examinés uniquement lors d'un audit. +Les résultats de chaque évaluation, qu'elle soit hébergée ou issue de votre propre worker, arrivent aux mêmes endroits. -## Examiner la qualité des évaluations +## Comparer les scores dans le temps - - 1. Accédez à **Observe → Evaluations**. - 2. Ajoutez une série et choisissez l'agent, l'environnement, le score d'évaluation, la statistique et la courbe. - 3. Ajoutez des séries pour comparer des environnements, des agents ou des clés de score. - 4. Sélectionnez un résultat pour ouvrir les sessions correspondantes ou partager la vue filtrée. Utilisez **Observe → Metrics** pour la latence, les tokens, le coût et autres valeurs de magnitude. + + Accédez à **Observe → evaluations**. - ![Un tableau de bord qualité affichant les scores d'évaluation moyens et les tendances dans le temps.](/images/dashboard/dashboard-quality.png) + - **Recent runs** liste chaque évaluation dès qu'elle arrive : qu'elle provienne d'un évaluateur hébergé (**managed**) ou du vôtre (**customer**), l'agent et la session, l'évaluation et sa version, son statut, ainsi que son score ou ses métriques. + - **Score over time** trace ce que vous demandez. Sélectionnez **add series** et choisissez un agent, un environnement, une évaluation et une statistique : avg, min, max, p50, p75, p90, p95, p99, stddev ou mode. Chaque série correspond à une ligne ; attribuez-lui sa propre **curve** pour l'afficher sur un graphique séparé. - Ouvrez une session depuis l'exploration détaillée pour inspecter le raisonnement par score : + ![La page evaluations : des exécutions récentes étiquetées customer, un graphique Score over time avec des lignes de référence à 0,5 et 0,8, et une série calculant la moyenne de finished_clean sur tous les agents et environnements.](/images/dashboard/evaluations-chart.png) - ![Une vue détaillée de session affichant les scores d'évaluation et le raisonnement à côté de la trace complète.](/images/dashboard/session-detail.png) + Une plage temporelle et une taille de bin s'appliquent à toutes les séries. Un bin fin permet de détecter un incident ; un bin grossier révèle une tendance, mais peut masquer les pics que vous recherchez. Un bucket sans aucun score correspond à un vide dans la courbe, jamais à un zéro, et des lignes de référence sont placées à 0,5 et 0,8. + + Chaque élément de la vue est encodé dans l'URL : **share** la copie, et quiconque l'ouvre voit exactement la comparaison que vous avez construite. ```bash @@ -28,25 +28,29 @@ Les évaluations en ligne appliquent des jugements cohérents aux sessions d'age fp evals --score helpfulness:0.8.. --since 7d ``` - Ajoutez le flag global `--json` avant `evals` pour l'automatisation, par exemple `fp --json evals --aggregate --env production`. + Ajoutez l'option globale `--json` avant `evals` pour l'automatisation, par exemple `fp --json evals --aggregate --env production`. -Un évaluateur reçoit l'identité de la session, l'environnement, les horodatages et les événements ordonnés. Il peut retourner des clés de score numériques avec un raisonnement optionnel et un résumé. Les évaluateurs à longue durée d'exécution peuvent retourner un job en attente et être interrogés ultérieurement. +Tracez **avg** et **p90** pour la même évaluation afin de vérifier si une bonne moyenne cache une queue problématique, ou comparez la même évaluation pour deux agents, ou pour la production et le staging, sur un même axe. Les coûts, latences et nombres de tokens, qui ont des unités, sont représentés sous **Observe → metrics**, avec un graphique par unité. + +## Comprendre pourquoi une session a obtenu un score faible + +Ouvrez une session depuis **Observe → sessions** ; la grille affiche les scores de chaque session et permet de filtrer par plage de score. Le panneau latéral droit de la session présente d'abord le résumé de l'évaluation, puis une barre par score avec le raisonnement de l'évaluateur en dessous. + +![Une vue détaillée de session affichant les scores d'évaluation et leur justification à côté de la trace complète.](/images/dashboard/session-detail.png) + +## Interroger l'assistant + +Posez vos questions sur les données d'évaluation en langage naturel : « parle-moi de quelques évaluations récentes », ou demandez quels agents voient leurs scores baisser. L'[assistant](/fr/sessions/assistant) lit et analyse les résultats, puis répond avec des tableaux sur lesquels vous pouvez rebondir ; une question pertinente peut devenir une [requête](/fr/sessions/queries) ou un [dashboard](/fr/sessions/dashboards). -## Bonnes cibles d'évaluation +![La page evaluations à côté de l'assistant, qui répond à « parle-moi de quelques évaluations récentes » avec un résumé des totaux, statuts et scores.](/images/dashboard/evaluations-assistant.png) -- Complétion ou exactitude des tâches -- Ancrage factuel et risque d'hallucination -- Sélection et efficacité des outils -- Conformité aux politiques ou aux processus -- Budgets de coût et de latence -- Escalade humaine requise +## Surveiller et agir -## Du score à la réponse +- **Dashboards**, sous **Analyze → dashboards**, suivent l'évolution des scores que vous mettez en avant, par agent et environnement, pour toute l'organisation. -Affichez les scores dans des tableaux de bord pour suivre les tendances. Créez des alertes pour des seuils ou des conditions composées. Lorsqu'un score décline sur une population, lancez un audit pour en comprendre la cause ; lorsque la cause est une action répétable, déployez une politique. + ![Un dashboard qualité affichant les scores d'évaluation moyens et leur évolution dans le temps.](/images/dashboard/dashboard-quality.png) - - Implémentez une évaluation synchrone ou asynchrone avec le SDK Python d'évaluateur. - \ No newline at end of file +- **Alerts** vous notifient lorsqu'un score franchit un seuil. Consultez [alerts](/fr/audits/alerts). +- Lorsqu'un score baisse sur de nombreuses sessions, [lancez un audit](/fr/audits/run) pour en comprendre la cause ; si la cause est une action reproductible, [rédigez une policy](/fr/policies/editor). \ No newline at end of file diff --git a/docs/fr/start/integrations/custom-agents.mdx b/docs/fr/start/integrations/custom-agents.mdx index b122924e..0fd0f1cd 100644 --- a/docs/fr/start/integrations/custom-agents.mdx +++ b/docs/fr/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "Agents personnalisés" sidebarTitle: "Agents personnalisés" -description: "Instrumentez un agent que vous avez développé vous-même, ou un framework sans adaptateur." +description: "Instrumentez un agent que vous avez écrit vous-même, ou un framework sans adaptateur." icon: "code" --- -Pour un agent que vous avez développé vous-même, ou un framework pour lequel Failproof AI ne dispose pas d'adaptateur. Il n'y a rien à instrumenter : vous émettez les événements. +Pour un agent que vous avez écrit vous-même, ou un framework pour lequel Failproof AI ne dispose pas d'adaptateur. Il n'y a rien à instrumenter : vous émettez les événements. -C'est la même API qu'appellent les quatre adaptateurs de framework en coulisses. Ce sont des tables de correspondance au-dessus d'elle. +C'est la même API que les quatre adaptateurs de framework utilisent en interne. Ils ne sont que des tables de traduction par-dessus. ## Installation @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # une exécution t.output = search(q) # un appel d'outil ``` -En lisant de haut en bas, le sens est explicite : +Lisez-le de haut en bas et il dit ce qu'il signifie : -| Envelopper dans | Pour indiquer | +| À encadrer | Pour indiquer | | --- | --- | | `session()` | Ces événements appartiennent à la même exécution | -| `agent()` | Quelque chose effectue un travail — donnez-lui un nom que vous reconnaîtriez dans une liste | -| `tool_call()` | Il s'agit d'un outil, et voici ce qu'il a retourné | +| `agent()` | Quelque chose effectue un travail — donnez-lui un nom reconnaissable dans une liste | +| `tool_call()` | Ceci est un outil, et voici ce qu'il a retourné | Et ce que chacun émet réellement : -| Portée | Émet | Rôle | +| Portée | Émet | Objectif | | --- | --- | --- | | `session()` | Rien | Lie un identifiant de session, regroupant une exécution | -| `agent()` | `agent_start`, `agent_end` | Délimite une unité de travail | -| `tool_call()` | `tool_use`, `tool_result` | Délimite un outil et le mesure | +| `agent()` | `agent_start`, `agent_end` | Encadre une unité de travail | +| `tool_call()` | `tool_use`, `tool_result` | Encadre un outil et le mesure | -Tout ce qui se trouve à l'intérieur peut omettre `session_id` et `agent_id`. Les portées lient l'identité sur des variables de contexte, et chaque appel d'événement la relit — vous n'avez donc jamais à propager des identifiants dans vos fonctions. +Tout ce qui se trouve à l'intérieur peut omettre `session_id` et `agent_id`. Les portées lient l'identité sur des variables de contexte et chaque appel d'événement la récupère, vous n'avez donc jamais besoin de propager les ids à travers vos fonctions. -Les trois fonctionnent aussi bien avec `async with` qu'avec `with`. +Les trois fonctionnent avec `async with` comme avec `with`. -L'imbrication d'agents construit l'arbre. `parent_id` et la profondeur sont calculés depuis la pile : +L'imbrication d'agents construit l'arbre. `parent_id` et la profondeur sont calculés à partir de la pile : ```python with failproofai_sdk.session(): @@ -59,7 +59,7 @@ with failproofai_sdk.session(): ... ``` -## Fermeture d'une portée +## Comment une portée se ferme `agent()` gère les exceptions pour vous : @@ -70,11 +70,11 @@ with failproofai_sdk.session(): | `KeyboardInterrupt`, `SystemExit` | `error`, puis `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | `agent_end` uniquement | `cancelled` | -L'erreur est émise avant `agent_end`, car le tableau de bord ferme le span à `agent_end` et tout ce qui suit n'est attribué à rien. Une annulation n'est pas un échec, donc les exécutions annulées ne polluent pas la surface des erreurs. L'exception est toujours re-levée : une portée n'avale jamais. +L'erreur est émise avant `agent_end`, car le tableau de bord ferme le span à `agent_end` et tout ce qui suit ne serait attribué à rien. Une annulation n'est pas un échec, donc les exécutions annulées ne polluent pas la surface des erreurs. L'exception est toujours re-levée : une portée n'avale jamais les exceptions. ## Les méthodes d'événements -Quinze méthodes en six familles. La plupart vont par paires — vous émettez l'ouverture, puis la fermeture, et le SDK mesure l'intervalle entre les deux. +Quinze méthodes en six familles. La plupart vont par paires — vous émettez l'ouverture, puis la fermeture, et le SDK mesure le span entre les deux. | Famille | Ouvre | Ferme | Autonome | | --- | --- | --- | --- | @@ -87,7 +87,7 @@ Quinze méthodes en six familles. La plupart vont par paires — vous émettez l | **Échecs** | — | — | `error` | - Préférez les portées — `agent()` et `tool_call()` — partout où elles s'appliquent. Elles garantissent l'événement de fermeture même lorsque le corps lève une exception. Utilisez ces méthodes directement lorsque votre flux de contrôle ne s'imbrique pas, par exemple un appel de modèle dans une fonction auxiliaire. + Préférez les portées — `agent()` et `tool_call()` — partout où elles s'adaptent. Elles garantissent l'événement de fermeture même si le corps lève une exception. Recourez à ces méthodes directement quand votre flux de contrôle ne se prête pas à l'imbrication, comme un appel de modèle dans une fonction auxiliaire. @@ -148,16 +148,16 @@ failproofai_sdk.event.error( | `human_wait` / `human_input` | **L'agent a sollicité une personne** — une porte d'approbation, une question de clarification | | `human_pause` / `human_interrupt` | **Une personne a agi sur l'agent** — un bouton d'arrêt, une pause opérateur | - Aucun framework ne signale la deuxième paire, donc c'est toujours à vous de l'émettre. + Aucun framework ne signale la seconde paire, c'est donc toujours à vous de l'émettre. - **Passez `request_id` lorsque des appels de modèle s'exécutent en parallèle.** Sans lui, les requêtes et les réponses sont appariées dans l'ordre d'arrivée par agent — et les appels concurrents sont mal appariés, associant chaque réponse à la mauvaise requête. + **Passez `request_id` lorsque des appels de modèles s'exécutent en parallèle.** Sans lui, les requêtes et les réponses sont appariées dans l'ordre d'arrivée par agent — et les appels concurrents sont mal appariés, associant chaque réponse à la mauvaise requête. ## Exemple -Une boucle d'appels d'outils contre l'API OpenAI, sans framework d'agent : +Une boucle d'appel d'outils contre l'API OpenAI, sans framework d'agent : ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """Un appel de modèle, délimité par la paire.""" + """Un appel de modèle, encadré par la paire.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # borné ; une boucle d'agent non bornée est un bug en soi + for _ in range(4): # borné ; une boucle non bornée est un bug en soi message = turn(messages) if not message.tool_calls: break @@ -204,7 +204,7 @@ with failproofai_sdk.session(): }) ``` -Cela produit les six mêmes types d'événements qu'un adaptateur vous donnerait. La version exécutable complète, avec les définitions d'outils, est incluse dans le dépôt du SDK sous `docs/manual/examples/`. +Cela produit les mêmes six types d'événements qu'un adaptateur vous fournirait. La version exécutable complète, avec les définitions d'outils, est incluse dans le dépôt du SDK sous `docs/manual/examples/`. ## Threads et async @@ -215,33 +215,33 @@ Les variables de contexte se propagent automatiquement dans les tâches asyncio. async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads : enveloppez le callable +# threads : enveloppez l'appelable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Sans `propagate()`, les événements du worker lèvent un `TypeError` indiquant le correctif à apporter plutôt que d'atterrir sur aucune session. C'est intentionnel : un événement sans session est ignoré par l'ingest et reçoit une réponse `200`, ce qui est l'échec silencieux que la couche d'identité existe précisément pour prévenir. +Sans `propagate()`, les événements du worker lèvent une `TypeError` indiquant le correctif plutôt que d'atterrir sans session. C'est délibéré : un événement sans session est ignoré à l'ingestion avec une réponse `200`, ce qui constitue l'échec silencieux que la couche d'identité existe précisément pour éviter. ## Instrumenter un framework sans adaptateur -Chaque framework d'agent vous offre les mêmes trois points d'ancrage. Mappez-les et vous obtenez une trace complète — les quatre adaptateurs livrés ne font rien de plus que cela. +Tout framework d'agent vous expose les mêmes trois points d'insertion. Mappez-les et vous avez une trace complète — les quatre adaptateurs fournis ne font rien de plus que cela. -| Le point d'ancrage | Ce que vous écrivez | Ce qui est enregistré | +| Le point d'insertion | Ce que vous écrivez | Ce qui est enregistré | | --- | --- | --- | | L'exécution | `session()` + `agent()` | `agent_start`, `agent_end` | | Chaque outil | `tool_call()` | `tool_use`, `tool_result` | | Chaque appel de modèle | La paire `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - + Dans ce que le framework appelle un wrapper d'outil ou un middleware. ```python @@ -264,23 +264,23 @@ Chaque framework d'agent vous offre les mêmes trois points d'ancrage. Mappez-le - **Vous avez un nœud, une étape ou une frontière de middleware qui mérite d'être visible ?** Enveloppez-le dans une paire de hooks — `hook_triggered` / `hook_completed` — et non dans un `agent()` imbriqué. `agent_id` est une facette à faible cardinalité, et une entrée par nœud la noie. Les spans de hooks s'affichent de la même façon et vous donnent la latence par nœud. + **Vous avez un nœud, une étape ou une frontière de middleware qui mérite d'être visible ?** Enveloppez-le dans une paire de hooks — `hook_triggered` / `hook_completed` — et non dans un `agent()` imbriqué. `agent_id` est une facette à faible cardinalité, et une entrée par nœud la sature. Les spans de hooks s'affichent de la même façon et vous donnent la latence par nœud. - **Le manuel et l'automatique se composent.** Un adaptateur s'exécutant dans une portée écrite à la main rejoint cette session et se rattache à cet agent, vous donnant un seul arbre plutôt que deux — utile lorsque vous instrumentez vous-même un framework en parallèle d'un framework supporté. + **Manuel et automatique se combinent.** Un adaptateur s'exécutant dans une portée écrite à la main rejoint cette session et se parenté à cet agent, vous obtenez donc un seul arbre plutôt que deux — utile quand vous instrumentez vous-même un framework aux côtés d'un framework supporté. - - Deux raisons, et les trois points d'ancrage ci-dessus sont la réponse aux deux : + + Deux raisons, et les trois points d'insertion ci-dessus sont la réponse aux deux : - `autogen-core` n'est plus maintenu depuis septembre 2025. - - AG2 n'expose aucun point d'enregistrement global équivalent aux hooks des autres frameworks, donc l'instrumenter signifie envelopper chaque agent à chaque site de construction. + - AG2 n'expose aucun point d'enregistrement global équivalent aux hooks des autres frameworks, ce qui fait qu'instrumenter AG2 implique d'envelopper chaque agent à chaque site de construction. - Mapper les points d'ancrage à la main enregistre les mêmes événements, avec la même fidélité, qu'un adaptateur livré le ferait. + Mapper les points d'insertion à la main enregistre les mêmes événements, avec la même fidélité, qu'un adaptateur fourni. -## Approfondir +## Aller plus loin Comment l'enregistrement fonctionne réellement. Rien de tout cela n'est nécessaire pour démarrer. @@ -288,7 +288,7 @@ Comment l'enregistrement fonctionne réellement. Rien de tout cela n'est nécess -Chaque enregistrement a la même forme : un span s'ouvre, le travail s'imbrique à l'intérieur, et chaque événement d'ouverture reçoit un événement de fermeture. +Chaque enregistrement a la même forme : un span s'ouvre, le travail s'imbrique à l'intérieur, et chaque événement d'ouverture reçoit un événement de fermeture correspondant. ```mermaid flowchart LR @@ -300,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -La **paire** est l'unité. Chaque événement de fermeture porte une durée mesurée par le SDK depuis son événement d'ouverture. +La **paire** est l'unité. Chaque événement de fermeture porte une durée que le SDK mesure depuis l'événement d'ouverture correspondant. -Voici une exécution réelle par framework — capturée depuis les exemples livrés avec le SDK, nom du modèle normalisé. Notez la quantité d'informations retournées par un seul appel. +Voici une vraie exécution par framework — capturée à partir des exemples fournis avec le SDK, nom de modèle normalisé. Notez tout ce qu'un seul appel renvoie. @@ -323,7 +323,7 @@ Voici une exécution réelle par framework — capturée depuis les exemples liv 14 +5.721s agent_end LangGraph · success ``` - Les nœuds deviennent des paires de hooks, vous obtenez donc la latence par nœud sans qu'ils encombrent la liste des agents. + Les nœuds deviennent des paires de hooks, vous obtenez donc la latence par nœud sans encombrer la liste des agents. @@ -360,7 +360,7 @@ Voici une exécution réelle par framework — capturée depuis les exemples liv 26 +7.038s agent_end Agent · success ``` - La boucle de l'agent elle-même est visible, pas seulement ses appels de modèle. + La boucle de l'agent elle-même est visible, pas seulement ses appels de modèles. @@ -375,7 +375,7 @@ Voici une exécution réelle par framework — capturée depuis les exemples liv 8 +8.119s agent_end agent · success ``` - Pas de paires de hooks : Pydantic AI n'a pas de frontière de nœud ou d'étape à délimiter. + Pas de paires de hooks : Pydantic AI n'a pas de frontière de nœud ou d'étape à encadrer. @@ -394,11 +394,11 @@ Voici une exécution réelle par framework — capturée depuis les exemples liv - + -**Il n'y a pas d'événement de fin de session.** Une session n'est pas quelque chose que vous fermez — c'est un groupe d'événements partageant un `session_id`. +**Il n'y a pas d'événement de fin de session.** Une session n'est pas quelque chose que vous fermez — c'est un groupe d'événements partageant un même `session_id`. -Le statut est déduit de la forme de la trace : +Le statut est dérivé de la forme de la trace : | Statut | Quand | | --- | --- | @@ -407,17 +407,17 @@ Le statut est déduit de la forme de la trace : | `error` | Rien n'est ouvert, et au moins un événement a échoué | | `done` | Rien n'est ouvert, et rien n'a échoué | -Une session se termine donc quand toutes les paires sont fermées. Les adaptateurs émettent `agent_end` pour vous, et au démontage ils ferment tout ce qui est encore ouvert et le marquent comme incomplet — une exécution plantée se règle en `done` avec un écart visible plutôt qu'en restant bloquée. +Une session se termine donc quand chaque paire est fermée. Les adaptateurs émettent `agent_end` pour vous, et au moment du teardown ils ferment tout ce qui est encore ouvert en le marquant incomplet — une exécution ayant planté se stabilise en `done` avec un écart visible plutôt que de rester suspendue. - C'est pourquoi une session peut s'étendre sur deux appels. Un `interrupt()` LangGraph met l'exécution en pause, le span racine reste délibérément ouvert, et l'appel de reprise le ferme. Les deux appels constituent une seule session. + C'est pourquoi une session peut s'étendre sur deux appels. Un `interrupt()` LangGraph met l'exécution en pause, le span racine reste délibérément ouvert, et l'appel de reprise le ferme. Les deux appels forment une seule session. - + -`session_id` et `agent_id` sont optionnels sur chaque méthode d'événement. Omis, ils sont résolus depuis la portée englobante : +`session_id` et `agent_id` sont optionnels sur chaque méthode d'événement. S'ils sont omis, ils sont résolus depuis la portée englobante : ```python with failproofai_sdk.session(): @@ -425,55 +425,55 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Les passer explicitement fonctionne toujours et prend la priorité. Sans rien de lié ni passé, l'appel lève un `TypeError` indiquant le correctif plutôt que d'émettre un événement sans session, que l'ingest ignorerait tout en répondant `200`. +Les passer explicitement fonctionne toujours et prend la priorité. Si rien n'est lié et rien n'est passé, l'appel lève une `TypeError` indiquant le correctif plutôt que d'émettre un événement sans session, que l'ingestion ignorerait tout en répondant `200`. Les portées lient l'identité sur des variables de contexte. Celles-ci se propagent automatiquement dans les tâches asyncio mais pas dans les nouveaux threads — enveloppez un worker dans `failproofai_sdk.propagate()`. -#### Qui génère quel identifiant +#### Qui crée quel identifiant -| Identifiant | Généré par | Notes | +| Id | Créé par | Notes | | --- | --- | --- | -| `session_id` | Vous, ou le SDK | `session("chat-42")` est utilisé tel quel ; omis, le SDK génère un `uuid4().hex` | +| `session_id` | Vous, ou le SDK | `session("chat-42")` est utilisé tel quel ; si omis, le SDK génère un `uuid4().hex` | | `agent_id` | Vous, ou le framework | Depuis `agent("analyst")`, un `role` CrewAI, un `FunctionAgent.name`. Une valeur ressemblant à un UUID est refusée et remplacée | -| `tool_call_id`, `hook_id`, `request_id` | Vous, ou le framework | Les adaptateurs réutilisent les identifiants d'exécution propres au framework, ce qui explique pourquoi les paires survivent aux sauts de threads | -| **Identifiant d'événement** | **Cloud, à l'ingest** | Le SDK n'en émet aucun | -| **`dedup_key`** | **Cloud, à l'ingest** | Un hash de l'organisation, de la session, du timestamp, du type et du payload. C'est la véritable identité — elle fait qu'un lot réessayé se compresse plutôt que de se dupliquer | +| `tool_call_id`, `hook_id`, `request_id` | Vous, ou le framework | Les adaptateurs réutilisent les propres ids d'exécution du framework, ce qui permet aux paires de survivre aux sauts de threads | +| **Id d'événement** | **Cloud, à l'ingestion** | Le SDK n'en émet aucun | +| **`dedup_key`** | **Cloud, à l'ingestion** | Un hash de l'org, de la session, du timestamp, du type et du payload. C'est la vraie identité — elle fait qu'un batch réessayé s'effondre en un seul plutôt que de se dupliquer | #### Comment les adaptateurs résolvent `session_id` -La première correspondance gagne : +Le premier match gagne : 1. Une option `session_id` explicite 2. Des métadonnées par appel 3. La portée `session()` englobante -4. Des métadonnées du framework -5. L'identifiant d'exécution propre au framework +4. Les métadonnées du framework +5. Le propre id d'exécution du framework -Il n'est jamais inventé tant que l'une de ces sources existe — un identifiant synthétisé fragmenterait une exécution sur plusieurs sessions. +Il n'est jamais inventé tant qu'un de ces éléments existe — un id synthétisé fractionnerait une exécution en plusieurs sessions. #### Gardez `agent_id` à faible cardinalité -C'est la facette principale sur toutes les surfaces du tableau de bord, et une colonne `LowCardinality(String)`. Une valeur par exécution dégrade la colonne et remplit le menu déroulant de filtres avec une entrée par exécution. +C'est la facette principale sur chaque surface du tableau de bord, et une colonne `LowCardinality(String)`. Une valeur par exécution dégrade la colonne et remplit le menu déroulant de filtre avec une entrée par exécution. Les adaptateurs défendent cette colonne pour vous : | Ce que le framework fournit | Enregistré comme | Pourquoi | | --- | --- | --- | | `3f9a1c2b-…` (un UUID) | `main` | Rien de lisible à conserver | -| Une longue chaîne hexadécimale brute | `main` | Même raison | -| `agent-3f9a1c2b-…` | `agent` | Identifiant par exécution supprimé, partie lisible conservée | +| Une longue chaîne hexadécimale brute | `main` | Idem | +| `agent-3f9a1c2b-…` | `agent` | Id par exécution supprimé, partie lisible conservée | | `agent-v2` | `agent-v2` | Les segments courts sont laissés tels quels | -| `step-3` | `step-3` | Même chose | +| `step-3` | `step-3` | Idem | -Le véritable identifiant est conservé dans `fw_agent_id` / `fw_run_id`, où il reste interrogeable sans être une facette. +Le vrai id est conservé dans `fw_agent_id` / `fw_run_id`, où il reste interrogeable sans être une facette. - **Cette protection ne touche que les libellés choisis par le *framework*.** Un `agent_id` que vous passez vous-même — à `event.*`, ou à `failproofai_sdk.agent(...)` — est enregistré exactement tel que fourni. Réécrire silencieusement un argument explicite serait pire que la cardinalité qu'il prévient, donc nommez vos propres spans en conséquence. + **Cette protection ne touche que les labels choisis par le *framework*.** Un `agent_id` que vous passez vous-même — à `event.*`, ou à `failproofai_sdk.agent(...)` — est enregistré exactement tel quel. Réécrire silencieusement un argument explicite serait pire que la cardinalité qu'il évite, nommez donc vos propres spans en conséquence. - + | Groupe | Événements | | --- | --- | @@ -484,7 +484,7 @@ Le véritable identifiant est conservé dans `fw_agent_id` / `fw_run_id`, où il | Humains | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | Échecs | `error` | -Ce que chaque framework enregistre, mesuré depuis les exécutions ci-dessus : +Quel framework enregistre quoi, mesuré depuis les exécutions ci-dessus : | Événement | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | @@ -493,7 +493,7 @@ Ce que chaque framework enregistre, mesuré depuis les exécutions ci-dessus : | Utilisation et résultat d'outil | Oui | Oui | Oui | Oui | Vous | | Hook déclenché et complété | Nœud | Tâche | Étape | — | Vous | | Erreur | Oui | Oui | Oui | Oui | Automatique | -| Attente humaine et saisie | Oui | Oui | Oui | — | Vous | +| Attente et saisie humaine | Oui | Oui | Oui | — | Vous | | Pause et reprise d'agent | Oui | Oui | Oui | — | Vous | Un tiret signifie que le framework n'a pas ce concept. `human_pause` et `human_interrupt` décrivent une *personne* agissant sur l'agent, ce qu'aucun framework ne signale — émettez-les vous-même. @@ -510,44 +510,44 @@ Un événement n'arrive jamais seul. Un ouvre un span, un le ferme, et l'événe | `model_request` | `model_response` | tokens, `stop_reason`, latence | | `tool_use` | `tool_result` | `output` ou `error`, durée | | `hook_triggered` | `hook_completed` | `outcome`, durée | -| `agent_pause` | `agent_resume` | la durée de la pause | -| `human_wait` | `human_input` | la réponse, et le temps que la personne a mis | +| `agent_pause` | `agent_resume` | combien de temps a duré la pause | +| `human_wait` | `human_input` | la réponse, et combien de temps la personne a mis | - Un événement d'ouverture sans événement de fermeture est un span qui ne se termine jamais. La session s'affiche comme toujours en cours, à l'infini, et sa durée active continue de croître. C'est le mode d'échec à surveiller lorsque vous instrumentez manuellement. + Un événement d'ouverture sans événement de fermeture correspondant est un span qui ne se termine jamais. La session s'affiche comme toujours en cours, indéfiniment, et sa durée active ne cesse de croître. C'est le mode d'échec à surveiller quand vous instrumentez à la main. #### Règles de corrélation -- Réutilisez le même `tool_call_id`, `hook_id`, `pause_id`, ou `input_id` pour l'événement de complétion correspondant. -- Le SDK calcule `duration_ms` pour `tool_result`, `hook_completed`, `agent_resume`, et `human_input`. Le passer à ces méthodes lève un `ValueError`. -- `duration_ms` **est** accepté sur `model_response`, car seul l'appelant connaît la vraie latence du fournisseur. Il doit être un entier — un float lève un `ValueError` au site d'appel, car le serveur lit la colonne comme un entier non signé 32 bits et stockerait NULL pour toute autre valeur. -- Les clés de corrélation sont délimitées par type et session, donc un appel d'outil et un hook peuvent partager un identifiant en toute sécurité, et deux sessions concurrentes peuvent réutiliser les mêmes identifiants sans collision. Elles ne sont pas délimitées par agent : une paire ouverte sous un agent et fermée sous un autre est toujours corrélée, ce qui est le cas ordinaire dans les frameworks multi-agents. +- Réutilisez le même `tool_call_id`, `hook_id`, `pause_id` ou `input_id` pour l'événement de complétion correspondant. +- Le SDK calcule `duration_ms` pour `tool_result`, `hook_completed`, `agent_resume` et `human_input`. Le passer à ces méthodes lève une `ValueError`. +- `duration_ms` **est** accepté sur `model_response`, car seul l'appelant connaît la vraie latence du fournisseur. Il doit être un entier — un flottant lève une `ValueError` au site d'appel, car le serveur lit la colonne comme un entier non signé 32 bits et stockerait NULL pour tout autre valeur. +- Les clés de corrélation sont délimitées par type et session, donc un appel d'outil et un hook peuvent partager un id en toute sécurité, et deux sessions concurrentes peuvent réutiliser les mêmes ids sans collision. Elles ne sont pas délimitées par agent : une paire ouverte sous un agent et fermée sous un autre se corrèle quand même, ce qui est le cas ordinaire dans les frameworks multi-agents. - `request_id` apparie `model_request` avec `model_response`. Sans lui, les événements de modèle sont appariés dans l'ordre par agent, donc les appels concurrents sont mal appariés. -- Une paire répartie entre plusieurs processus est toujours corrélée en aval, mais le SDK ne peut pas calculer sa durée intra-processus. -- La table des opérations en attente contient au maximum 10 000 démarrages et expulse l'entrée la plus ancienne quand elle est pleine. +- Une paire répartie sur plusieurs processus se corrèle toujours en aval, mais le SDK ne peut pas calculer sa durée en cours de processus. +- La map des événements en attente contient au maximum 10 000 entrées et expulse la plus ancienne quand elle est pleine. - + -Installer `failproofai-sdk` installe tout, les quatre adaptateurs inclus. Les extras récupèrent le **framework**, pas l'adaptateur. +L'installation de `failproofai-sdk` installe tout, les quatre adaptateurs inclus. Les extras tirent le **framework**, pas l'adaptateur. ```python import failproofai_sdk # ne charge rien en dehors de la bibliothèque standard failproofai_sdk.instrument() # importe uniquement les adaptateurs dont vous avez besoin ``` -`import failproofai_sdk` est contractuellement sans dépendance, imposé par un test qui installe le wheel construit avec `--no-deps` et un autre qui prouve qu'aucun framework n'atteint `sys.modules`. +`import failproofai_sdk` est contractuellement sans dépendance, vérifié par un test qui installe la wheel construite avec `--no-deps` et un autre qui prouve qu'aucun framework n'atteint `sys.modules`. - Il n'y a pas d'attribut `failproofai_sdk.crewai`. Les adaptateurs ne sont délibérément pas exposés sur le package de niveau supérieur : y accéder importerait le framework comme effet secondaire d'un accès à un attribut, brisant la promesse zéro-dépendance. Utilisez `instrument()`. + Il n'existe pas d'attribut `failproofai_sdk.crewai`. Les adaptateurs ne sont délibérément pas exposés sur le package de premier niveau : y accéder importerait le framework comme effet de bord d'un accès d'attribut, rompant la promesse de zéro dépendance. Utilisez `instrument()`. ```python -failproofai_sdk.instrument() # tout framework déjà importé +failproofai_sdk.instrument() # tous les frameworks déjà importés failproofai_sdk.instrument("crewai") # exactement un, par nom -failproofai_sdk.uninstrument("crewai") # le remettre en place +failproofai_sdk.uninstrument("crewai") # le remettre comme avant ``` | Nom | Accepte aussi | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # le remettre en place | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -La détection automatique lit `sys.modules`, pas la liste des packages installés, donc un framework installé mais jamais importé n'est pas instrumenté et n'est jamais importé en votre nom. Pour voir ce qui est connecté : +La détection automatique lit `sys.modules`, pas la liste des packages installés, donc un framework installé mais jamais importé n'est pas instrumenté et n'est jamais importé à votre place. Pour voir ce qui est câblé : ```python from failproofai_sdk.integrations import active, available @@ -567,20 +567,20 @@ active() # ('langchain',) ``` - **`instrument("crewai")` sur une machine sans CrewAI ne lève pas d'exception.** Il enregistre un avertissement et retourne `()`, donc un framework manquant ne fait jamais tomber un processus qui instrumente aussi d'autres frameworks. + **`instrument("crewai")` sur une machine sans CrewAI ne lève pas d'exception.** Il enregistre un avertissement et retourne `()`, donc un framework manquant ne fait jamais tomber un processus qui instrumente d'autres frameworks. - L'avertissement contient l'`ImportError` sous-jacent, et ce message nomme la commande d'installation exacte — le correctif est donc dans vos logs, pas caché. + L'avertissement porte l'`ImportError` sous-jacent, et ce message indique la commande d'installation exacte — le correctif est donc dans vos logs, pas caché. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Définissez `FAILPROOFAI_SDK_STRICT=1` pour qu'il lève une exception à la place. Ce drapeau est lu **une seule fois et mis en cache**, donc exportez-le avant le démarrage de votre processus plutôt que de le définir en cours d'exécution. + Définissez `FAILPROOFAI_SDK_STRICT=1` pour qu'il lève une exception à la place. Ce flag est lu **une seule fois et mis en cache**, exportez-le donc avant le démarrage de votre processus plutôt que de le définir en cours d'exécution. - **`instrument()` doit être appelé *après* l'import de votre framework.** La détection automatique lit `sys.modules`, donc un appel nu avant l'import ne trouve rien, n'installe rien, et retourne `()`. + **`instrument()` doit venir *après* l'import de votre framework.** La détection automatique lit `sys.modules`, donc un appel nu avant l'import ne trouve rien, n'installe rien et retourne `()`. @@ -588,11 +588,11 @@ active() # ('langchain',) import failproofai_sdk failproofai_sdk.instrument() # sys.modules n'a pas encore langchain -> () -import langchain # trop tard, rien n'est connecté +import langchain # trop tard, rien n'est câblé ``` ```python Right -import langchain # importez d'abord le framework +import langchain # importer le framework en premier import failproofai_sdk failproofai_sdk.instrument() # le trouve -> ('langchain',) @@ -601,61 +601,63 @@ failproofai_sdk.instrument() # le trouve -> ('langchain',) ```python Right, order-proof import failproofai_sdk -# Le nommer importe l'adaptateur à la demande, donc cela fonctionne depuis n'importe où. +# Le nommer importe l'adaptateur à la demande, donc cela fonctionne de n'importe où. failproofai_sdk.instrument("langchain") ``` -Faites une erreur ici et le processus s'exécute avec le SDK importé, l'adaptateur apparemment installé, et **pas un seul événement émis**. Il enregistre un avertissement qui l'indique explicitement — vérifiez donc vos logs en premier lorsqu'une exécution n'enregistre rien. +Faites cette erreur et le processus s'exécute avec le SDK importé, l'adaptateur apparemment installé, **et pas un seul événement émis**. Cela enregistre un avertissement qui le dit explicitement — vérifiez donc vos logs en premier quand une exécution n'enregistre rien. - + ```mermaid flowchart LR A["Votre agent"] --> B["Adaptateur"] B --> C["Writer
file d'attente en mémoire"] C -->|"toutes les 0,5s"| D["Spool
JSONL sur disque"] - D --> E["Failproof daemon"] + D --> E["Daemon Failproof"] E -->|"HTTPS"| F["Cloud"] ``` | Étape | Rôle | S'exécute dans | | --- | --- | --- | -| Adaptateur | Traduit un callback du framework en l'un des 15 types d'événements | Votre processus | -| Writer | Met en file d'attente, regroupe, écrit le JSONL de façon atomique | Votre processus, thread d'arrière-plan | -| Spool | Transfert durable, survit à la sortie de votre processus | Disque local | -| Daemon | Surveille le spool, envoie les lots, supprime ce qui a été envoyé | Votre machine | -| Ingest | Assigne un identifiant de ligne et une clé de déduplication, promeut les colonnes interrogeables | Cloud | +| Adaptateur | Traduit un callback framework en un des 15 types d'événements | Votre processus | +| Writer | Met en file d'attente, regroupe, écrit du JSONL atomiquement | Votre processus, thread en arrière-plan | +| Spool | Transfert durable, survit à la fermeture de votre processus | Disque local | +| Daemon | Surveille le spool, envoie les batches, supprime ce qui a été envoyé | Votre machine | +| Ingest | Attribue un id de ligne et une clé de déduplication, promeut les colonnes interrogeables | Cloud | -Le spool est ce qui rend cela sûr : votre agent ne se bloque jamais sur le réseau, et une panne Cloud signifie un répertoire qui grossit plutôt que des événements perdus. +Le spool est ce qui rend cela sûr : votre agent ne bloque jamais sur le réseau, et une panne Cloud signifie un répertoire qui grossit plutôt que des événements perdus. -Chaque flush écrit un fichier de lot, `.tmp` d'abord, puis `fsync`, puis un renommage atomique : +Chaque flush écrit un fichier batch, `.tmp` d'abord, puis `fsync`, puis un renommage atomique : ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Le daemon ne récupère que les `.jsonl`, il ne peut donc jamais lire un fichier partiellement écrit. Le nom du fichier contient un timestamp, un identifiant de processus et un numéro de séquence, de sorte que deux processus flushing dans la même milliseconde ne peuvent pas entrer en collision. La file d'attente est limitée à 10 000 événements ; au-delà, elle abandonne les plus anciens et enregistre un log. +Le daemon ne prend que les `.jsonl`, il ne peut donc jamais lire un fichier à moitié écrit. Le nom de fichier porte un timestamp, un id de processus et un numéro de séquence, donc deux processus flushing dans la même milliseconde ne peuvent pas entrer en collision. La file d'attente est limitée à 10 000 événements ; au-delà, elle supprime les plus anciens et enregistre un log. - **`collector.redact` est à `minimal` par défaut pour les événements SDK également.** Le SDK expurge avant d'écrire un lot sur disque, et le daemon répète le même passage déterministe avant l'upload afin que les lots d'anciens SDK soient protégés. + **`collector.redact` ne s'applique pas à vos événements SDK.** Il ne les voit jamais. -Le daemon lit chaque lot et applique la rédaction en mémoire avant l'upload. Il ne réécrit pas le fichier spool qu'il a lu. +Le daemon **envoie** vos batches. Il ne les ouvre ni ne les réécrit. -| Événements | Écrits par | Où la rédaction minimale s'exécute | +| Événements | Écrits par | Traités par `collector.redact` ? | | --- | --- | --- | -| Transcriptions de sessions CLI | Le daemon | Avant que le daemon écrive le lot | -| Activité de hooks | Le daemon | Avant que le daemon écrive le lot | -| **Tout ce que le SDK émet** | **Votre processus** | **Avant que le SDK écrive le lot et à nouveau avant l'upload par le daemon** | +| Transcriptions de sessions CLI | Le daemon | Oui | +| Activité des hooks | Le daemon | Oui | +| **Tout ce que le SDK émet** | **Votre processus** | **Non** | -Mettez `collector.redact` à `off` uniquement lorsque des payloads verbatim sont une exigence explicite ; le SDK et le daemon honorent tous les deux ce paramètre. La rédaction minimale attrape les clés d'API courantes, les tokens bearer, les JWT et les affectations de secrets. Elle ne peut pas identifier une prose sensible arbitraire. +La rédaction s'exécute là où le daemon *écrit* ses propres événements — pas là où les batches sont *envoyés*. Donc un prompt ou un argument d'outil contenant une clé API la conserve à l'arrivée. + +C'est délibéré. Ce sont vos propres appels d'instrumentation, et réécrire les événements en transit signifierait que les événements que vous recevez ne sont pas ceux que vous avez émis. - **Vous contrôlez les payloads à la source, à deux endroits :** + **Vous contrôlez les payloads à la source, en deux endroits :** - Désactivez la capture de contenu sur l'adaptateur. **Le nom de l'option diffère, et un adaptateur n'en a aucune** — ce n'est pas un interrupteur universel unique : - LangChain / LangGraph, Pydantic AI — `capture_content=False` @@ -663,16 +665,16 @@ Mettez `collector.redact` à `off` uniquement lorsque des payloads verbatim sont - CrewAI — **aucun interrupteur de contenu du tout** ; `session_id` est la seule option qu'il lit, donc les prompts et les complétions sont toujours enregistrés. `instrument()` ignore les options qu'un adaptateur ne lit pas, donc passer le mauvais nom ne lève rien et ne change rien. - - Ne donnez pas le secret à `input=` en premier lieu. + - Ne transmettez pas le secret à `input=` en premier lieu. - `collector.redact` est une défense en profondeur, pas un substitut à l'un ou l'autre. + `collector.redact` ne remplace ni l'un ni l'autre. **Un répertoire spool vide est l'état sain.** Ne l'utilisez pas pour vérifier la livraison. -Le daemon supprime chaque lot dans les millisecondes suivant son envoi, donc un `ls` est en compétition avec le collecteur et ne montre qu'une fraction de ce que vous avez émis — impossible à distinguer d'un SDK qui n'a rien enregistré. +Le daemon supprime chaque batch dans les millisecondes qui suivent son envoi, donc un `ls` est en concurrence avec le collecteur et ne montre qu'une fraction de ce que vous avez émis — impossible à distinguer d'un SDK qui n'a rien enregistré. Pour confirmer que les événements sont bien arrivés, consultez le tableau de bord. Pour observer le remplissage du spool, arrêtez d'abord le daemon. @@ -680,7 +682,7 @@ Pour confirmer que les événements sont bien arrivés, consultez le tableau de -Chaque callback s'exécute dans un wrapper dont le seul rôle est de re-lever, donc votre appel se trouve dans exactement un `try` et tout ce que fait le SDK se passe en dehors. +Chaque callback s'exécute dans un wrapper dont le seul rôle est de re-lever les exceptions, votre appel se trouve donc dans exactement un `try` et tout ce que fait le SDK se passe en dehors. | Ce qui se passe | Résultat | | --- | --- | @@ -690,7 +692,7 @@ Chaque callback s'exécute dans un wrapper dont le seul rôle est de re-lever, d | Une version de framework est hors de la plage testée | Avertit une fois, instrumente quand même | | Une seule capacité est manquante | Ce hook est désactivé, jamais l'adaptateur entier | -Le comportement par défaut est correct en production et incorrect lors du débogage, car il ne peut que prouver « ça n'a pas planté ». Définissez `FAILPROOFAI_SDK_STRICT=1` pour rendre bruyant un échec silencieux. +Le comportement par défaut est correct en production et problématique lors du débogage, car il ne peut que prouver que ça n'a pas planté. Définissez `FAILPROOFAI_SDK_STRICT=1` pour rendre visible un échec avalé. @@ -700,23 +702,23 @@ Le comportement par défaut est correct en production et incorrect lors du débo - Un événement d'ouverture n'a pas d'événement de fermeture : un `model_request` sans `model_response`, ou un `tool_use` sans `tool_result`. Utilisez les portées, qui garantissent la paire même lorsque le corps lève une exception. Si vous appelez les méthodes d'événements directement, utilisez `try` et `finally`. + Un événement d'ouverture n'a pas d'événement de fermeture correspondant : un `model_request` sans `model_response`, ou un `tool_use` sans `tool_result`. Utilisez les portées, qui garantissent la paire même si le corps lève une exception. Si vous appelez les méthodes d'événements directement, utilisez `try` et `finally`. - - Il est mesuré depuis l'événement d'ouverture correspondant, donc il est refusé sur `tool_result`, `hook_completed`, `agent_resume`, et `human_input`. Il est accepté sur `model_response`, car seul vous connaissez la vraie latence du fournisseur, et il doit être un entier. + + Il est mesuré depuis l'événement d'ouverture correspondant, il est donc refusé sur `tool_result`, `hook_completed`, `agent_resume` et `human_input`. Il est accepté sur `model_response`, car seul vous connaissez la vraie latence du fournisseur, et il doit être un entier. - - Le thread n'a jamais hérité du contexte. Enveloppez le callable dans `failproofai_sdk.propagate()`. Voir [Threads et async](#threads-and-async). + + Le thread n'a jamais hérité du contexte. Enveloppez l'appelable dans `failproofai_sdk.propagate()`. Voir [Threads et async](#threads-and-async). Les champs supplémentaires sont fusionnés en dernier, donc un champ nommé comme un vrai champ tel que `model` ou `outcome` l'écraserait et modifierait une colonne stockée. Préfixez les vôtres ; les adaptateurs utilisent le préfixe `fw_`. - - `agent_id` est une facette à faible cardinalité et vous y avez mis un identifiant d'exécution. Utilisez un nom de rôle ou de nœud et placez le vrai identifiant dans un champ de payload. + + `agent_id` est une facette à faible cardinalité et vous y avez mis un id d'exécution. Utilisez un nom de rôle ou de nœud et mettez le vrai id dans un champ de payload. @@ -724,7 +726,7 @@ Le comportement par défaut est correct en production et incorrect lors du débo - Paires, identifiants, cycle de vie de session et livraison. + Paires, ids, cycle de vie des sessions et livraison. Suivez la causalité à travers la session que vous venez de capturer. diff --git a/docs/fr/start/quickstart.mdx b/docs/fr/start/quickstart.mdx index 88d91c9c..f8aa4d75 100644 --- a/docs/fr/start/quickstart.mdx +++ b/docs/fr/start/quickstart.mdx @@ -4,24 +4,24 @@ description: "Capturez une session d'agent, identifiez un échec et commencez à icon: "zap" --- -Ce guide de démarrage rapide vous permet de configurer une machine pour envoyer des sessions, d'effectuer un audit et de déployer une politique. Utilisez le skill pour configurer Failproof, ou suivez les étapes manuelles. +Ce démarrage rapide vous permet de connecter une machine pour qu'elle rapporte des sessions, d'effectuer un audit et de déployer une politique. Utilisez la compétence pour configurer Failproof AI, ou suivez les étapes manuelles. -**Quelle est votre situation ?** Si votre agent s'exécute dans l'un des 12 [harnais](/fr/reference/harnesses) pris en charge — une CLI de codage, ou une passerelle comme Hermes ou OpenClaw — suivez les étapes ci-dessous ; vous avez besoin de Node.js 20.9 ou ultérieur. Si votre agent n'a pas de harnais, instrumentez-le avec le [SDK Python](/fr/reference/custom-agents) pour le traçage et les audits, puis rejoignez la section [Exécuter votre premier contrôle d'échec](/fr/start/first-audit) ; l'application des politiques sur ce chemin nécessite un hook dans votre runtime. +**Quelle est votre situation ?** Si votre agent s'exécute dans l'un des 12 [harnais](/fr/reference/harnesses) pris en charge — une CLI de codage, ou une passerelle comme Hermes ou OpenClaw — suivez les étapes ci-dessous ; vous aurez besoin de Node.js 20.9 ou version ultérieure. Si votre agent n'a pas de harnais, instrumentez-le avec le [SDK Python](/fr/reference/custom-agents) pour le traçage et les audits, puis rejoignez la section [Exécuter votre premier contrôle d'échec](/fr/start/first-audit) ; l'application des politiques sur cette voie nécessite un hook dans votre runtime. - + - + ```bash npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Votre agent inspecte le projet, choisit l'intégration appropriée, effectue la configuration et vérifie le bon fonctionnement. Consultez le [dépôt de skills FailproofAI](https://github.com/FailproofAI/skills) pour les skills individuels et les options d'installation avancées. + Votre agent inspecte le projet, choisit l'intégration appropriée, effectue la configuration et la vérifie. Consultez le [dépôt de compétences FailproofAI](https://github.com/FailproofAI/skills) pour les compétences individuelles et les options d'installation avancées. @@ -29,11 +29,11 @@ Ce guide de démarrage rapide vous permet de configurer une machine pour envoyer ## Avant de commencer 1. Ouvrez le [tableau de bord Failproof AI](https://app.befailproof.ai) et créez un compte ou connectez-vous avec votre adresse e-mail professionnelle. -2. Allez dans **Administration → Keys** et créez une clé avec les droits `events:add` et `policies:pull`. -3. Copiez le secret à usage unique et stockez-le sur la machine cible : +2. Accédez à **Administration → Keys** et créez une clé avec `events:add` et `policies:pull`. +3. Copiez le secret à usage unique, puis lisez-le dans un shell sur la machine cible. `read -s` le reçoit via une invite qui n'affiche pas les caractères saisis, de sorte qu'il n'apparaît jamais dans une commande : ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## Installation @@ -42,10 +42,16 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - Les transcripts de session sont envoyés par défaut. Ajoutez `--no-transcripts` pour signaler l'activité des hooks et les décisions de politique sans le contenu des transcripts. + Cette seule commande constitue l'intégralité de la configuration : elle installe le démon local (une seule fois en root), câble les hooks dans chaque CLI d'agent détectée et connecte cette machine au Cloud. Passer la clé via l'environnement plutôt que par `--token` l'empêche d'apparaître dans `ps`, où tous les utilisateurs de la machine peuvent lire les arguments d'une commande. Cela ne la protège pas de l'historique du shell — c'est la lecture avec `read -s` qui s'en charge. En CI, injectez-la comme secret masqué et désactivez le traçage shell (`set -x`), sinon la trace l'affichera. + + Les transcriptions de session sont envoyées par défaut. Ajoutez `--no-transcripts` pour rapporter l'activité des hooks et les décisions de politique sans le contenu des transcriptions. + + + N'utilisez pas `failproofai config --connect ` ici. Ce flag enrôle une machine **déjà** configurée et retourne immédiatement — sans démon, sans hooks — de sorte que la machine apparaîtrait dans le Cloud sans rien collecter ni appliquer. + Si cette machine possède déjà un historique d'agent, prévisualisez et importez les sept derniers jours, puis attendez la fin de la livraison. Ignorez cette étape sur une nouvelle machine. @@ -57,20 +63,31 @@ export FAILPROOFAI_KEY="" Ouvrez **Sessions** dans Failproof AI et sélectionnez une session importée. - - Cette étape attache Failproof AI à votre harnais et installe les 39 politiques intégrées. Utilisez-les pour visualiser les décisions de politique locales et tester l'application avant que Failproof AI n'audite vos sessions et n'écrive des politiques pour vos agents. - - Laissez l'installateur détecter votre harnais, ou nommez-en un explicitement. Chacune des 12 valeurs est valide pour `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + L'étape précédente a déjà câblé chaque CLI d'agent détectée. Réexécutez-la explicitement pour un harnais particulier si nécessaire, ou pour ajouter un harnais installé ultérieurement. Chacun des 12 est une valeur `--cli` valide — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # une CLI de codage failproofai policies --install --cli hermes --scope user # une passerelle Slack/Telegram ``` - Le blocage d'un appel d'outil avant son exécution est vérifié sur les 12 harnais. Les barrières de fin de tour sont vérifiées sur 8 — consultez la [capacité d'application](/fr/reference/harnesses#enforcement-capability) pour la matrice par harnais. + Le blocage d'un appel d'outil avant son exécution est vérifié sur les 12. Les points de contrôle en fin de tour sont vérifiés sur 8 — consultez la [capacité d'application](/fr/reference/harnesses#enforcement-capability) pour la matrice par harnais. + + + Le câblage des hooks n'active aucune politique. La configuration n'en choisit délibérément aucune — cette décision vous appartient — alors prenez un pack : + + ```bash + failproofai policies add FailproofAI/policies + ``` + + Le pack est récupéré depuis sa release GitHub, vérifié par somme de contrôle et épinglé au tag exact résolu. Il contient 38 politiques et active les 10 que son manifeste marque comme sûres à activer sans surveillance. Utilisez-les pour observer les décisions de politique locales et tester l'application avant que Failproof AI n'audite vos sessions et rédige des politiques pour vos agents. + + Lisez n'importe quel pack avant de l'adopter avec `failproofai policies show /`, et consultez les [packs de politiques](/fr/policies/packs) pour n'en prendre qu'une partie. + + Tant que cela n'est pas exécuté, la seule chose appliquée est `block-failproofai-commands` — le garde toujours actif qui empêche un agent de désactiver Failproof AI. `failproofai policies` liste ce qui est activé. - Suivez [Exécuter votre premier contrôle d'échec](/fr/start/first-audit). Utilisez un objectif concret, par exemple : « trouver les sessions où l'agent a réessayé un outil défaillant sans changer d'approche. » + Suivez [Exécuter votre premier contrôle d'échec](/fr/start/first-audit). Utilisez un objectif concret tel que « trouver les sessions où l'agent a réessayé un outil défaillant sans modifier son approche ». Suivez [Prévenir votre premier échec avec une politique](/fr/start/first-policy). Commencez en mode observation, inspectez les correspondances, puis appliquez la version révisée. @@ -78,7 +95,7 @@ export FAILPROOFAI_KEY="" - Exécutez `failproofai config --status`. Une configuration saine indique la connexion cloud, l'état du daemon et si l'application des politiques est en pause. + Exécutez `failproofai config --status`. Une configuration saine rapporte la connexion au cloud, l'état du démon et si l'application est en pause. \ No newline at end of file diff --git a/docs/fr/start/setup.mdx b/docs/fr/start/setup.mdx index 5ae19ac4..1d741faf 100644 --- a/docs/fr/start/setup.mdx +++ b/docs/fr/start/setup.mdx @@ -1,26 +1,30 @@ --- -title: "Choisissez votre configuration" -description: "Choisissez entre l'application locale, Failproof AI Cloud ou un déploiement en entreprise." +title: "Choisir votre configuration" +description: "Optez pour une application locale, Failproof AI Cloud, ou un déploiement en entreprise." icon: "waypoints" --- - Installez des hooks et des politiques sur une machine. Utilisez cette option lorsque vous avez besoin de garde-fous immédiats sans envoyer de données de session vers le Cloud. + Configurez une machine sans clé Cloud et appliquez un pack de politiques. À utiliser lorsque vous avez besoin de garde-fous immédiats sans envoyer de données de session vers le Cloud. - Ajoutez des sessions centralisées, des audits, des évaluations en ligne, des tableaux de bord, des alertes et le déploiement de politiques pour l'ensemble de votre parc. + Ajoutez des sessions centralisées, des audits, des évaluations en ligne, des tableaux de bord, des alertes et le déploiement de politiques sur votre flotte. - Utilisez les contrôles organisationnels, les clés scopées, l'infrastructure privée et les exigences de sécurité propres à chaque déploiement. + Utilisez des contrôles organisationnels, des clés à portée restreinte, une infrastructure privée et des exigences de sécurité propres à votre déploiement. -## Chemin recommandé vers la production +## Appliquer localement + +Exécutez `failproofai config` sans clé, puis appliquez un pack avec `failproofai policies add FailproofAI/policies`. Dans un terminal, choisissez **Not now — stay local** lorsque la configuration vous demande de vous connecter au Cloud ; sans terminal et sans `FAILPROOFAI_CLOUD_TOKEN`, le mode local est automatiquement conservé. Le daemon et les hooks s'appliquent sur la machine, et aucune donnée de session n'est envoyée au Cloud. Pour vous connecter ultérieurement, suivez les étapes ci-dessous. + +## Chemin recommandé en production 1. Connectez une machine hors production avec la capture de transcripts activée. -2. Vérifiez les sessions et les évaluations dans le Cloud. -3. Créez un audit pour un mode de défaillance connu. +2. Vérifiez les sessions et les évaluations dans Cloud. +3. Créez un audit pour un mode d'échec connu. 4. Déployez la première politique en mode observation. 5. Étendez à la production après avoir examiné les correspondances et les faux positifs. @@ -28,41 +32,58 @@ icon: "waypoints" - 1. Allez dans **Administration → Clés** et créez une clé avec les permissions `events:add` et `policies:pull`. + 1. Accédez à **Administration → Clés** et créez une clé avec `events:add` et `policies:pull`. 2. Copiez le secret à usage unique sur la machine cible. - 3. Après avoir exécuté la commande de connexion CLI, allez dans **Admin → application** et confirmez que la machine apparaît. - 4. Allez dans **Observer → Événements** et confirmez que son premier événement arrive. + 3. Après avoir exécuté la commande de connexion CLI, accédez à **Admin → application** et confirmez que la machine apparaît. + 4. Accédez à **Observe → Événements** et confirmez l'arrivée de son premier événement. - Le panneau de clé affiche les deux autorisations nécessaires pour une machine connectée : l'ingestion d'événements et la livraison de politiques. + Le panneau de la clé affiche les deux autorisations nécessaires à une machine connectée : l'ingestion d'événements et la distribution des politiques. - ![Le panneau de création de clé API utilisé pour accorder les permissions d'ingestion d'événements et de livraison de politiques.](/images/dashboard/key-create.png) + ![Le panneau de création de clé API utilisé pour accorder les autorisations d'ingestion d'événements et de distribution des politiques.](/images/dashboard/key-create.png) - Après la connexion, la machine doit apparaître dans la section application avec son état de politique souhaité et son état de déploiement. + Après la connexion, la machine doit apparaître dans la section application avec l'état souhaité et l'état rapporté de ses politiques. - ![Le parc dans la section application avec une machine enrôlée développée pour afficher son état de politique souhaité et son statut de déploiement.](/images/dashboard/enforcement-fleet.png) + ![La flotte d'application avec une machine inscrite développée pour afficher l'état souhaité de ses politiques et le statut de déploiement.](/images/dashboard/enforcement-fleet.png) Le premier événement reçu confirme que le daemon peut transmettre des données au Cloud, indépendamment du déploiement des politiques. - ![Le flux d'événements en direct affichant les événements récents d'agent, de modèle et d'outil.](/images/dashboard/events-stream-current.png) + ![Le flux d'événements en direct affichant les événements récents d'agents, de modèles et d'outils.](/images/dashboard/events-stream-current.png) Ne continuez qu'une fois que la machine et son premier événement sont tous deux visibles. + Lisez le secret à usage unique dans le shell. `read -s` le saisit via une invite sans écho, de sorte qu'il n'apparaît jamais dans une commande ni dans l'historique du shell : + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Configurez ensuite la machine, choisissez ses politiques et nommez-la : - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` + `failproofai config` effectue l'intégralité de la configuration — daemon, hooks pour chaque CLI d'agent trouvé, et connexion au Cloud — puis n'applique aucune politique, ce à quoi sert la deuxième commande. + + Le label s'attribue **après** la connexion, pas pendant : `failproofai config --machine-label ` renomme une machine déjà connectée ; sur une machine non connectée, il ne fait que l'indiquer. + Ajoutez `--no-transcripts` lorsque le contenu des transcripts doit rester local. + + En CI, définissez `FAILPROOFAI_CLOUD_TOKEN` depuis le coffre-fort de secrets plutôt qu'avec `read -s`, et désactivez le traçage shell (`set -x`), sinon la trace affiche la clé. + + + Sur une machine **déjà** configurée, `failproofai config --connect ` l'inscrit et ne fait rien d'autre. N'utilisez pas cette forme pour une première installation : elle retourne avant que le daemon ou tout hook soit en place, laissant une machine qui apparaît dans Cloud mais ne collecte ni n'applique rien. + -La connexion au Cloud vérifie l'ingestion d'événements et la livraison de politiques de manière indépendante. Une clé peut donc être valide tout en manquant une permission requise. Utilisez `failproofai config --status` pour voir quelle capacité est configurée. +La connexion au Cloud vérifie indépendamment l'ingestion d'événements et la distribution des politiques. Une clé peut donc être valide mais manquer d'une permission requise. Utilisez `failproofai config --status` pour voir quelle capacité est configurée. - La configuration Cloud n'écrit les identifiants locaux qu'après le succès de la capacité concernée. Un échec de vérification ne laisse pas une machine apparaître comme connectée alors qu'elle ne l'est pas. + La configuration Cloud n'écrit les identifiants locaux qu'après le succès de la capacité concernée. Un échec de vérification ne laisse pas une machine paraître connectée alors qu'elle ne l'est pas. \ No newline at end of file diff --git a/docs/he/admin/keys-and-permissions.mdx b/docs/he/admin/keys-and-permissions.mdx index 41e427ba..8c2064a7 100644 --- a/docs/he/admin/keys-and-permissions.mdx +++ b/docs/he/admin/keys-and-permissions.mdx @@ -1,29 +1,29 @@ --- title: "מפתחות והרשאות" -description: "יצירת מפתחות API בהיקף מוגבל עבור מכונות, אוטומציה ואופרטורים." +description: "צור מפתחות API בהיקף מוגדר למכונות, אוטומציה ומפעילים." icon: "key-round" --- -מפתחות API שייכים לארגון ונושאים הרשאות מפורשות. השתמשו במפתחות נפרדים עבור ספיגת סוכנים, משלוח מדיניות, מעריכים, אוטומציה של CI וסקריפטים ניהוליים. +מפתחות API שייכים לארגון ונושאים הרשאות מפורשות. השתמש במפתחות נפרדים לספיגת סוכנים, משלוח מדיניות, מעריכים, אוטומציית CI וסקריפטים ניהוליים. -## יצירה והחלפה של מפתח +## יצירה וסיבוב של מפתח - 1. עברו ל-**Administration → Keys**, בחרו **new key** והזינו שם של עומס עבודה. - 2. בחרו קבוצת הרשאות והתאימו הרשאות בודדות רק כאשר ההגדרה המוכנה מראש אינה מספיקה. - 3. יצרו את המפתח והעתיקו את הסוד החד-פעמי שלו מיד. - 4. פתחו את המפתח מאוחר יותר כדי לעדכן הקצאות, להשבית אותו או ליצור מחדש את הסוד. + 1. עבור אל **Administration → Keys**, בחר **new key**, והזן שם עומס עבודה. + 2. בחר סט הרשאות והתאם הרשאות בודדות רק כאשר הקבוע אינו מספיק. + 3. צור את המפתח והעתק את הסוד החד-פעמי שלו מיד. + 4. פתח את המפתח מאוחר יותר כדי לעדכן הענקות, להשבית אותו או ליצור מחדש את הסוד. - תיבת הכלים של יצירה היא המקום שבו תבחרו בהקצאות הצרות ביותר הנדרשות על ידי עומס העבודה. + תיקיית היצירה היא המקום בו אתה בוחר בהענקות הצרות ביותר הנדרשות על ידי עומס העבודה. - ![תיבת המפתח API החדש עם ערכות הרשאות מוכנות מראש והקצאות בודדות.](/images/dashboard/key-create.png) + ![תיקיית מפתח ה-API החדשה עם הגדרות הרשאות והענקות בודדות.](/images/dashboard/key-create.png) - לאחר יצירה, דף Keys מציג את המטא-דאטה הקבוע וקצר אפשרויות הניהול. הסוד החד-פעמי אינו מוצג שוב. + לאחר יצירה, דף Keys מציג את המטא-נתונים הקבועים וכללי ניהול. הסוד החד-פעמי לא יוצג שוב. - ![דף API Keys המציג הרשאות מפתח, זמן יצירה וקצוות לשיחזור והשבתה.](/images/dashboard/api-keys.png) + ![דף API Keys המציג הרשאות מפתח, זמן יצירה וכללי Regenerate וDisable.](/images/dashboard/api-keys.png) - השתמשו ברשימה זו כדי לבדוק הקצאות בקביעות והשבתו מפתחות שאינם עוד תואמים לעומס עבודה פעיל. + השתמש ברשימה זו כדי לבדוק הענקות בעיתוי קבוע והשבת מפתחות שלא עוד תואמים עומס עבודה פעיל. ```bash @@ -36,39 +36,39 @@ icon: "key-round" fp keys disable production-agents ``` - הפנו או תפסו את פלט יצירה/שיחזור בצורה מאובטחת; הסוד מוחזר פעם אחת. + הפנה או תפוס פלט יצירה/יצירה מחדש בצורה מאובטחת; הסוד מוחזר פעם אחת. שתי ההרשאות הנדרשות על ידי מכונת Failproof AI מחוברת הן עצמאיות: - `events:add` שולח אירועים ונתוני הפעלה. -- `policies:pull` אחזור הקצאות מדיניות שהוקצו. +- `policies:pull` משחזר פריסות מדיניות משויכות. -סודות מפתח מוצגים כאשר נוצרים או משוחזרים. אחסנו אותם במנהל סודות והחליפו אותם ללא שימוש חוזר בעיות אישיות של אופרטור. +סודות המפתח מוצגים כאשר נוצרים או נוצרים מחדש. אחסן אותם במנהל סודות וסובב אותם מבלי להשתמש בחדשות הקלט האינטראקטיביות של מפעיל. ## קטלוג הרשאות | אזור | הרשאות | | --- | --- | -| אירועים | `events:add`, `events:read` | -| מפתחות | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` הוא רק עבור הפעלה אישית | -| משתמשים | `users:create`, `users:read`, `users:update`, `users:delete` | -| הערכות | `evaluations:read`, `evaluations:trigger` | -| לוחות בקרה | `dashboards:read`, `dashboards:write`, `dashboards:delete` | -| שאילתות | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | -| עוזר | `agent:use` | -| הגדרות | `settings:read`, `settings:write` | -| התראות | `alerts:read`, `alerts:write` | -| בעיות | `issues:read`, `issues:create`, `issues:close` | -| ביקורות | `audits:read`, `audits:write` | -| מדיניות | `policies:read`, `policies:write`, `policies:pull` | -| שימוש | `usage:read` | - -`orgs:admin` שמור עבור אופרטור ההתקנה ולא ניתן להעניק למפתח ארגוני או לחבר רגיל. אסימוני `incidents:*` ו-`alerts:ack` בדימוס מתקבלים לצורך תאימות ומתקנדים להרשאות `issues:*` הנוכחיות. - -ערכות הרשאות מובנות הן `read-only`, `standard` ו-`admin`. `standard` מוסיף הפעלת הערכה, ביצוע שאילתה, תגובה לבעיות והשימוש בעוזר להרשאות קריאה. יצירת מפתח מסיר הקצאות-רק-לאנשים גם כאשר קבוצת הרשאות מכילה אותן. +| Events | `events:add`, `events:read` | +| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` הוא רק הפעלת אדם | +| Users | `users:create`, `users:read`, `users:update`, `users:delete` | +| Evaluations | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | +| Dashboards | `dashboards:read`, `dashboards:write`, `dashboards:delete` | +| Queries | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | +| Assistant | `agent:use` | +| Settings | `settings:read`, `settings:write` | +| Alerts | `alerts:read`, `alerts:write` | +| Issues | `issues:read`, `issues:create`, `issues:close` | +| Audits | `audits:read`, `audits:write` | +| Policies | `policies:read`, `policies:write`, `policies:pull` | +| Usage | `usage:read` | + +`orgs:admin` שמור למפעיל המופע ולא ניתן להעניק למפתח ארגוני או לחבר רגיל. אסימונים `incidents:*` ו-`alerts:ack` מיושנים מתקבלים לתאימות ומנורמלים להרשאות `issues:*` עדכניות. + +סטי הרשאות מובנים הם `read-only`, `standard` ו-`admin`. `standard` מוסיף השראת הערכה, ביצוע שאילתה, תגובה בנושא והשתמשות בעוזר להרשאות קריאה. יצירת מפתח מסיר הענקות שרק לאדם גם כאשר סט הרשאות מכיל אותן. - מפתחות בהיקף התקנה יכולים לבחור ארגון עם הכותרת `X-AgentEye-Org`. הגדרו אותה במפורש בהפצות מרובות-ארגוניות; השמטה עלולה לבחור בארגון ברירת המחדל. + מפתחות בהיקף מופע יכולים לבחור ארגון עם כותרת `X-AgentEye-Org`. קבע זאת במפורש בפריסות ארגוניות מרובות; השמטה עשויה לבחור בארגון ברירת המחדל. \ No newline at end of file diff --git a/docs/he/evaluations/deploy.mdx b/docs/he/evaluations/deploy.mdx new file mode 100644 index 00000000..cc9cec33 --- /dev/null +++ b/docs/he/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "פרסום וגרסאה של הערכה" +description: "פרסום גרסה בלתי-משתנה, צפייה במה שפעיל, פרסום גרסאות חדשות, חזרה לאחור, והערכת הפעילויות שכבר יש לך." +icon: "cloud-upload" +--- + +## פרסום + +בחר **deploy `@`** בתחתית עמוד הכתיבה. הגרסה בלתי-משתנה לאחר הפרסום: מכאן והלאה, כל פעילות שמסתיימת, והתנאי שלה חל עליה, תהיה מדורגת על ידה. + +## צפייה במה שפעיל + +**Analyze → eval authoring** מציגה את ההגדרות המארחות של הארגון שלך, ההערכות שמעריך מנוהל מריץ עבורן. כל שורה מציגה: + +- את השם, המפתח, הגרסה וסוג התוצאה שלה +- את checksum המקור שלה, המספר את הגרסאות המפורסמות ללא צורך בפתיחת הקוד +- האם היא **מותנית** או פועלת על **כל הפעילויות ההשלומות** — התנאי הוא מה שמכוון הערכה לסוכנים או סביבות מסוימות +- timeout שלה, התוויות שלה, ומתי היא השתנתה לאחרונה + +![רשימת ההגדרות המארחות: שם, מפתח, גרסה, סוג תוצאה, checksum, timeout וטווח של כל הערכה, עם גרסה חדשה ואפשרות להפעלה או השבתה.](/images/dashboard/eval-definitions.png) + +חפש ברשימה, או סנן אותה לפי מצב. הערכות שעובד משלך רושם אינן רשומות כאן; התוצאות שלהן נושאות תג **customer** בעמוד [הערכות](/he/sessions/evaluations), והמארחות נושאות **managed**. + +ארגון יכול להיות לו עד 100 הערכות מארחות שונות בחסימה בו-זמנית. + +## פרסום גרסה חדשה + +בחר **new version** בשורה. עמוד הכתיבה נפתח עם הקוד של הגרסה הזאת; שנה אותו, בדוק אותו, ופרסם אותו. המפתח וסוג התוצאה שלו עוברים והם לא יכולים להשתנות. + +פרסום יוצר משביתה את קודמתה ושומר אותה ברשימה. תוצאות שומרות את הגרסה שייצרה אותן, כך שתרשים מראה בדיוק מתי ההיגיון החדש השתלט. + +## חזרה לאחור + +בחר **disable** בגרסה הנוכחית ו**enable** בזו שאתה רוצה בחזרה. שום דבר לא נמחק, וכל תוצאה נשארת כמו שהיתה. + +## עצירת הערכה + +בחר **disable**. ללא גרסה בחסימה, היא תפסיק להריץ בפעילויות חדשות. כדי לעצור הערכה שעובד משלך מריץ, הפסק לרשום אותה: הסר אותה מהעובד, או עצור את העובד. + +## הערכת פעילויות שכבר יש לך + +הערכה רצה קדימה: גרסה המפורסמת עכשיו לעולם לא מדרגת פעילות שהסתיימה לפניה. כדי להעריך היסטוריה, פתח **score sessions you already have** בעמוד authoring של ההערכה, בחר חלון של עד 90 ימים ובאופן אופציונלי, הערכה יחידה, וחשב לפני שאתה מריץ. הספירה היא בדיוק מה שיריץ, וכל זוג פעילות-והערכה בה הוא הערכה ניתנת לחיוב. + +זה ממלא רווחים בלבד. פעילות שכבר יש לה תוצאה לאותה הערכה שומרת אותה, והרצה של אותו החלון פעמיים לא מדרגת שום דבר חדש. + +כדי להעריך פעילות אחת שוב — לאחר תיקון, או לפעילות שלעולם לא הסתיימה בנקיון — בחר **re-evaluate** בעמוד שלה. התוצאה החדשה מתווספת להיסטוריית הפעילות; הקודמות נשארות. + +## הרשאות + +| הרשאה | מאפשרת לך | +| --- | --- | +| `evaluations:read` | צפייה בתוצאות, ופתיחת עמוד authoring של ההערכה | +| `evaluations:trigger` | צפייה, פרסום, גרסאה, הפעלה והשבתה של הגדרות מארחות; בדיקתן; הערכת היסטוריה; הערכה מחדש של פעילות | +| `events:read` | בדיקה מול פעילויות אמתיות, וטביעת טיוטות בקלידי payload שלך, על גבי `evaluations:trigger` | +| `evaluations:run` | הרצת עובד המעריך משלך | \ No newline at end of file diff --git a/docs/he/evaluations/overview.mdx b/docs/he/evaluations/overview.mdx new file mode 100644 index 00000000..ec0b421f --- /dev/null +++ b/docs/he/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "הערכת סוכנים" +description: "הוסף ניקוד לכל סשן שהסתיים עם הערכות שאתה מגדיר: בדיקות Python מתארחות, או שופטים LLM בעובד שלך." +icon: "gauge" +--- + +הערכה מוסיפה ניקוד לסשן סוכן שהסתיים. כאשר סשן מסתיים, כל הערכה שאופשרה החלה ותרשום את מה שהיא מצאה, עם נימוק שאתה יכול לקרוא לצד העקבות: + +- **ניקוד** מ-0 ל-1, שניתן לסמן כהצליח או נכשל +- **מטריקה**, כגון ספירה, משך זמן או עלות, עם היחידה שלה +- **אישור**, שעבר או לא עבר + +## שני סוגי מעריכים + +| | Python מתארח | עובד שלך | +| --- | --- | --- | +| כתוב | בלוח הבקרה, תחת **Analyze → eval authoring** | ב-Python, עם [Evaluator SDK](/he/reference/evaluator-sdk) | +| רץ | במעריך המנוהל של Failproof AI, בחממה | בתשתית שלך | +| הטוב ביותר ל | בדיקות דטרמיניסטיות מבוססות קוד | שופטי LLM, קריאות מודל, חבילות, סודות, גישה לרשת, עיבוד כבד | + +Python מתארח הוא בכוונה קטן: ביטוי אחד, אין יבוא, אין רשת. כל דבר שצריך מודל — שופט LLM שמעריך אם תשובה הייתה רלוונטית, למשל — רץ בעובד שלך במקום זאת. שום סוג לא צריך חיבור פנימי: עובדים טוענים סשנים שהסתיימו ומגישים תוצאות על פני HTTPS יוצא. + +## כל ארגון מעריך את הסוכנים שלו + +הערכות שייכות לארגון שמגדיר אותן. כל ארגון בחזקה כותב שלו — הבדיקות שלו, התנאים, הסף וההתויות — גרסאות וגיבוש ללא השפעה על אחר כלשהו, וראה רק את התוצאות שלו. סנן את התוצאות הללו לפי סוכן, סביבה, הערכה וזמן, או שאל את העוזר עליהן. + +## מהטיוטה הראשונה ל-scores חי + + + + תאר מה למדוד והנח לעוזר לטיוטה אותו, או כתוב אותו בעצמך. ראה [כתוב הערכה](/he/evaluations/write). + + + הרץ אותו נגד סשנים אמיתיים לפני שהוא עולה לשידור; שום דבר לא מאוחסן. ראה [בדוק הערכה](/he/evaluations/test). + + + גיבוש גרסה בלתי משתנה, פרסם חדשות כשהיא משתנה, וחזור לאחת מוקדמת. ראה [גיבוש וגרסה](/he/evaluations/deploy). + + + תרשים ניקוד לאורך זמן, השווה סוכנים וסביבות, ושאל את העוזר. ראה [קרא תוצאות הערכה](/he/sessions/evaluations). + + + +הערכה רצה קדימה: גרסה שגובשה כעת משנה את הסשנים שמסתיימים מעכשיו ואילך. כדי לשנות סשנים שכבר יש לך, [מלא אותם](/he/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file diff --git a/docs/he/evaluations/test.mdx b/docs/he/evaluations/test.mdx new file mode 100644 index 00000000..11882773 --- /dev/null +++ b/docs/he/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "בדיקת הערכה" +description: "הפעל הערכה מול הסשנים האמיתיים שלך לפני פריסה. כלום לא נשמר." +icon: "flask-conical" +--- + +**בדיקת הערכה זו**, בדף התיקייה, מריצה את הקוד מול סשנים אמיתיים שלך בצי ההערכה ללא פריסה. כלום לא נשמר: כשל כאן הוא תצוגה מקדימה, והפריסה תמיד מותרת. + + + + בחר **check** כדי לקמפל את הקוד והתנאי מול כללי החול ללא הרצתם על אף סשן. + + + הצר את הסשנים התואמים לפי סוכן, סביבה, זמן או מזהה סשן, ובחר עד 10. כלול סשנים שההערכה צריכה להיכשל בהם וגם אלה שהיא צריכה לעבור בהם. + + + בחר **run against N sessions**, וקרא כל שורה. + + + +| שורה | משמעות | +| --- | --- | +| **ok** | הוא הרץ. השורה מפרטת כל ניקוד, מדד והצהרה שהוחזרו, וכמה זמן זה לקח. | +| **skipped** | התנאי החזיר `False`, כך שההערכה לא הרצה. זה דילוג, לא כשל. | +| Failed | זה העלה שגיאה, פג זמן, או השתמש במשהו שהחול מסרב. השורה אומרת איזה, ו**Fix it** מוסר את השגיאה לעוזר כשהוא יכול לעזור. | + +![לוח בדיקת הערכה זו: שלושה סשנים שנבחרו לפי סוכן, שניים בסדר ואחד דולג מכיוון שהתנאי שלו החזיר False.](/images/dashboard/eval-test.png) + +תוצאה מפסיקה להיות עדכנית ברגע שאתה עורך את הקוד; היא מוצלת במקום להיות בשימוש חוזר. \ No newline at end of file diff --git a/docs/he/evaluations/write.mdx b/docs/he/evaluations/write.mdx new file mode 100644 index 00000000..74224bef --- /dev/null +++ b/docs/he/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "כתוב הערכה" +description: "תאר מה למדוד והנח לעוזר לעצב הערכת Python מתארחת, או כתוב את הקוד בעצמך. שופטי LLM פועלים בעובד שלך." +icon: "file-pen-line" +--- + +הערכות מתארחות הן Python קטנות וקביעות, שנכתבות בלוח הבקרה ופועלות בחfleet המעריכים של Failproof AI. לוגיקה כבדה יותר — שופט LLM, חבילה, סוד, קריאת רשת — פועלת ב[עובד שלך](#write-it-in-your-own-worker) במקום זאת. + +## ערוך זאת מתיאור + +1. עבור ל**Analyze → eval authoring** ובחר **new eval**. +2. תאר מה למדוד באנגלית פשוטה, או בחר מ**start from an example…**, ובחר **draft**. +3. בדוק את השדות ואת הקוד שהוא ממלא, ואז [בדוק אותו](/he/evaluations/test) ו[פרוס אותו](/he/evaluations/deploy). + +![עמוד authored הערכה עם הערכה שעוצבה: התיאור, הערות העוזר בעיצוב, ושדות שם, מפתח, גרסה, תוצאה, זמן קצוב, תוויות ותנאי.](/images/dashboard/eval-authoring-draft.png) + +העיצוב מעוגן באירועי הארגון שלך: הדף קורא אילו מפתחות payload הנשיאות שלך נשאו במהלך שבעת הימים האחרונים, כך שהקוד קורא מפתחות שקיימים במקום לנחש. לפני מסירת העיצוב, העוזר בוחן אותו מול עד חמש מהסשנים האחרונים שלך, מתקן כל דבר שהוא יכול להוכיח שהוא שבור — עד שלוש סבבים — ובודק פעם אחת שהקוד מודד מה ביקשת. שמור על התיאור ספציפי: הנושאים הרחבים איטיים יותר ויכולים להיתקע. בדוק את הקוד כך או כך; הפריסה לעולם לא חסומה. + +## הגדר את השדות + +| שדה | מה זה | +| --- | --- | +| name | מה אנשים רואים. ניתן לעריכה מאוחר יותר | +| key | המזהה היציב שתוצאותיו מתוכננות תחתיו, כגון `code_assistant_quality_gate` | +| version | כל מחרוזת גרסה ללא רווחים, כגון `1.0.0` | +| result | **score** (0 עד 1), **metric** (מספר עם יחידה), או **assertion** (עבר או לא) | +| timeout seconds | ברירת מחדל 30. ה-sandbox עוצר כל ריצה יחידה ב-60 | +| labels | עד 20, מופרדים בפסיקים. ניתן לעריכה מאוחר יותר | +| condition | אופציונלי. ביטוי Python; ההערכה פועלת רק בסשנים שבהם היא `True` | + +השתמש בתנאי כדי להגביל הערכה לעוזרים וסביבות המיועדות לה: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +המפתח, הגרסה, סוג התוצאה, התנאי והקוד אינם ניתנים לשינוי לאחר הפריסה: כדי לשנות כל אחד מהם, פרסם גרסה חדשה. השם, התוויות, והאם היא מופעלת יישארו ניתנים לעריכה. + +## כתוב את הקוד בעצמך + +**קוד ה-evaluator** הוא ביטוי Python אחד שמחזיר `EvalResult(...)`, עם `session` בהיקף. זה מדרג את חלק תוצאות הכלים שחזרו בסדר: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +תוצאה מובילה עם מפתח ההערכה שלה, בסוג המוצהר שלו: `score=` להערכת ניקוד, או ערך `metrics` או `assertions` בשם המפתח להערכת מטרי או קביעה. מטריקות ותביעות אחרות רוכבות איתו, עד 25 תוצאות בריצה. + +| בהיקף | נותן לך | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count`, ו-`events`, בתוספת `count(event_type)` ו-`events_of_type(event_type)` | +| כל אירוע | `id`, `ts`, `event_type`, ו-`payload` | +| סוגי תוצאה | `EvalResult`, `Score`, `Metric`, `Assertion`, ו-`ConditionResult` לתנאי | +| Builtins | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +כלום אחר אינו זמין: אין ייבואים, וללא תכונות מעבר לנתוני הסשן וטופל טקסט ושיטות מילון רגילות כמו `get`, `lower`, ו-`split`, שיש להם להיקרא במקום להיות מופנים. מפתחות payload הם כל מה שהעוזרים שלך שולחים — `status` לעיל הוא רק דוגמה — אז קרא אותם מסשן אמיתי. **format** מסדר את הקוד ו-**fix** מבקש מהעוזר לתקן אותו. הקוד יכול להיות עד 128 KiB, והתנאי עד 16 KiB. + +![עורך קוד ה-evaluator, עם format ו-fix, המציג את הקביעות של הערכה שעוצבה.](/images/dashboard/eval-authoring-code.png) + +## כתוב זאת בעובד שלך + +כאשר הערכה צריכה מודל, חבילה, סוד, או רשת, כתוב אותה עם ה-[Evaluator SDK](/he/reference/evaluator-sdk) והפעל אותה בתשתית שלך. היא משתמשת באותם סוגי תוצאה, ותוצאותיה מופיעות לצד אלו המתארחות, מתויגות **customer**: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/he/policies/deploy.mdx b/docs/he/policies/deploy.mdx index 59629ac9..3794c7a9 100644 --- a/docs/he/policies/deploy.mdx +++ b/docs/he/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "פריסת מדיניויות" -description: "הפעל גרסת מדיניות שנבדקה במכונות המיועדות." +title: "פריסת מדיניות" +description: "הצבת גרסת מדיניות שנבדקה על מכונות במצב צפייה, אכיפה שלה והשגת אישור שכל מכונה קיבלה אותה." icon: "cloud-upload" --- -פריסה מחברת גרסה אחת או יותר של מדיניות לקבוצת מטרה של מכונות רשומות. +פריסה מציבה גרסאות מדיניות שפורסמו על מכונה, כל אחת עם אחת משתי השפעות: -## החל פריסה +- **צפייה** (Observe) רושמת מה המדיניות הייתה עושה, ואינה חוסמת כלום. +- **אכיפה** (Enforce) פועלת על ההחלטה: `deny` חוסם את הקריאה ו־`instruct` מנחה את ה־agent. + +## הוספת מכונה + +מכונה מופיעה תחת **Admin → enforcement** ברגע שהיא מחוברת ל־Cloud. אם זו שאתה רוצה עדיין לא שם: - 1. עבור אל **Admin → enforcement**, חפש את המכונה והרחב את השורה שלה. - 2. בחר **edit**, הוסף את גרסת המדיניות שנבדקה, ובחר **observe** או את אפקט האכיפה שלה. - 3. החל את השינוי, ואז המתן לבדיקת הבאה של המכונה ואשר את מצב הפריסה והכיסוי שלה. - 4. עבור אל **Observe → policy** כדי לבדוק החלטות חיות. - - ![עורך פריסת המכונה עם גרסאות מדיניות, אפקטי enforce ו-observe, וקטע הפעולה של החלת פריסה.](/images/dashboard/enforcement-editor.png) + 1. לך ל־**Administration → Keys** וצור מפתח עם `policies:pull`, כדי שהמכונה תוכל לקבל פריסות, ו־`events:add`, כדי שההחלטות שלה יגיעו ל־Cloud. + 2. חבר את המכונה עם המפתח הזה — [Connect a machine to Cloud](/he/start/setup#connect-a-machine-to-cloud) מנחה דרך זה. + 3. אשר שזו מופיעה תחת **Admin → enforcement**. - בצע פריסה מהשורת הפקודה באמצעות `fp fleet`. בדוק את הסט המתקבל לפני החלתו — `deploy` מדפיס את התוכנית המלאה וביקשת **רק בטרמינל אינטראקטיבי ללא `--json`**. תחת `--json`, עם `--yes`, או עם stdin מועבר (שלב CI, סקריפט, agent המריץ פקודות) היא מיושמת מיד ללא תוכנית ללא הודעה — אז הרץ תחילה `fp fleet show ` אם אתה רוצה בדיקה: + על המכונה: + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + בטרמינל, `failproofai config` שואל אם להתחבר ל־Cloud ומקבל את המפתח בהודעה מוסווה. לאחר מכן אשר שהמכונה נרשמה, מכל מקום, עם `fp fleet list`. + + + +## פריסה במצב צפייה + + + + 1. לך ל־**Admin → enforcement**, מצא את המכונה והרחב את השורה שלה. + 2. בחר **edit**, הוסף את גרסת המדיניות שנבדקה, ובחר **observe**. + 3. החל את השינוי, ואז חכה להזדקפות הבאה של המכונה ואשר את מצב הפריסה והכיסוי שלה. + 4. לך ל־**Observe → policy** לבדיקת החלטות חיות. + ![עורך פריסת המכונה עם גרסאות מדיניות, השפעות אכיפה וצפייה, ופעולת הפעלת פריסה.](/images/dashboard/enforcement-editor.png) + + ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` מציג כוונה לעומת הובלה (מכונה קוראת כ-`behind` עד שהיא תשאול בפעם הבאה), `fp fleet history ` מפרט את הדורות, ו-`fp fleet rollback ` משחזר אחד — היא מסרבת אם אותו דור שם מדיניות מאז משוקללת או מחוקה. + הסיומת `:observe` היא מה שהופכת אותה לצפייה: `--add no-force-push` בלבד שומרת על ההשפעה שיש כבר למכונה עבור המדיניות הזו, ואחרת מאכיפה. החלף אותה לאכיפה מאוחר יותר עם `--add no-force-push:enforce`. + + `deploy` **מחליף את כל קבוצת המדיניות של המכונה** בתוצאה. זה מדפיס את התוכנית, ואז שואל לפני יישום — אך רק בטרמינל אינטראקטיבי. עם `--yes`, תחת `fp --json`, או עם stdin מופנה (שלב CI, סקריפט, agent שבורח החוצה) הוא מיישם ללא שאלה; התוכנית עדיין מודפסת, או מוחזרת כ־`plan` תחת `--json`. - בדוק את המכונה עצמה באמצעות `failproofai config --status`, והשתמש ב-`fp sessions --env production --since 24h` ו-`fp events --event-type hook_completed` לאחר הפריסה כדי לאמת שפעילות מגיעה ל-Cloud. + על המכונה, `failproofai policies` מפרט את המדיניויות המנוהלות על ידי Cloud שהיא מריצה ו־`failproofai config --status` מציגה את החיבור שלה. השתמש ב־`fp sessions --env production --since 24h` ו־`fp events --event-type hook_completed` כדי לאשר שהפעילות שלה מגיעה ל־Cloud. - - בצע פריסה של גרסה שנבדקה, לא טיוטה הניתנת לשינוי, החל ממכונה שאינה בייצור או קוהורטה קטנה שאת ההפעלות שלה אתה יכול לבדוק. + + בחר את הגרסה המפורסמת והמכונות שעליהן היא צריכה לרוץ. - - בדוק התאמות, סיבות, כלים המושפעים והחיוביים שליליים ללא חסימת עבודה. + + בדוק התאמות, סיבות, כלים משפעים והתנגדויות שווא בעוד שכלום אינו חסום. - - קדם לאחר התאמות שנצפו להפריד פעולות בלתי בטוחות מעשויות תקפות, ואז אשר שכל מכונה מיועדת משכה את הפריסה ודיווחת על החלטות. + + החלף את ההשפעה לאכיפה ברגע שההתאמות שנצפו מפרידות בין פעולות לא בטוחות לפעולות תקפות, ואז אשר שכל מכונה מיועדת משכה את השינוי ודיווחה על החלטות. -מכונות זקוקות ליכולת `policies:pull`. דיווח אירועים נשלט בנפרד על ידי `events:add`; אמת את שניהם כאשר אתה מצפה לניתוח Cloud ואכיפה. +## בדוק כיסוי + +כיסוי משיב אם מדיניות רצה במקום שבו הסיכון נמצא. + +1. לך ל־**Admin → enforcement** ובדוק את סכומי האכיפה והצפייה. +2. חפש מכונה לפי ID או תוויות, או סנן למכונות חסרות מדיניות. +3. הרחב שורה כדי להשוות מדיניויות שהוקצו, פריסה שדווחה, זדקפות אחרון והיסטוריה. +4. רענן אחרי מרווח הסקר של המכונה כאשר פריסה מיושמת עדיין תלויה. + +![הצי אכיפה המציג כיסוי מדיניות, מצב פריסת מכונה, וקצאות צפייה ואכיפה.](/images/dashboard/enforcement-fleet.png) + +חפש מכונות שלעולם לא משכו את הפריסה העדכנית ביותר, מכונות רשומות שהפסיקו לדווח, מדיניות שהוקצתה לסביבה הלא נכונה, וסחיפת גרסה לאחר עדכון מופרע. + +תייג מכונות לפי עומס עבודה וסביבה — שמות מארחים בלבד נדירים שמחזיקים בקנה מידה או החלפה אוטומטית: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - ניהול אכיפה הוא זרימת עבודה מנהלית של Cloud. אל תתייחס לנתיבי אכיפה רק-שורש כנקודות קצה API רגילות של `/v1` הלקוח. + ניהול אכיפה הוא זרימת עבודה מנהלת ב־Cloud. אל תתייחס לנתיבי אכיפה בלבד שרש כנקודות קצה רגילות של API `/v1` של הלקוח. \ No newline at end of file diff --git a/docs/he/policies/editor.mdx b/docs/he/policies/editor.mdx index d6b917ad..6ea4236a 100644 --- a/docs/he/policies/editor.mdx +++ b/docs/he/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "עורך המדיניויות" -description: "יצירה ותיקון של מדיניויות גרסאות מתוך מצב כשל מאושר." +title: "כתיבת מדיניות" +description: "תן ל-Failproof AI לנסח מדיניות מממצא ביקורת, או כתוב את המקור בעצמך, ואז בדוק, תקדד ופרסם אותה." icon: "file-pen-line" --- -השתמש בעורך המדיניויות כדי להפוך ממצא או בעיה לכלל הניתן להטמעה. שמור על הפרדה בין יצירת מדיניות להטמעה כך שטיוטה לא תוכל שינוי שקט בהתנהגות בתחום הפעול. +ישנן שתי דרכים לכתוב מדיניות: לתת ל-Failproof AI לנסח אותה מממצא ביקורת, או לכתוב את המקור בעצמך. שום דבר לא מפורסם או נפרס עד שתבחר לעשות זאת. -כאשר לבעיה יש דפוס פעולה חוזר, פתח אותה תחת **Analyze → issues** ובחר **generate policy**. Failproof AI מסביר תחילה האם מדיניות יכולה להביע את הבעיה, ואז מעביר את הכוונה המתוקנת והקשר המציאות לעורך. המקור שנוצר נשאר טיוטה עד שתפרסם אותו. +## כתיבת מדיניות מביקורת -## פרסום גרסת מדיניות +ביקורת מגלה כשל; מדיניות עוצרת אותו מהתרחשות שוב. Failproof AI משרטטת את המדיניות מהראיות של הממצא עצמו. + +### 1. הרץ ביקורת + +[הרץ ביקורת](/he/audits/run) על התקופות שבהן ההכשל מתרחש. כל ממצא נושא את התקופות שלו, סיבה שורש, ודרך מניעה מוצעת. עבד מממצא עם **דפוס פעולה החוזר על עצמו** — מדיניות יכולה רק לעצור את מה שהיא יכולה להכיר בהתרחשות ווקט. + +### 2. צור את הטיוטה - - 1. עבור אל **Admin → policy editor** ובעמודת **compose**, תאר את מצב הכשל או הדבק את מקור ה-JavaScript policy. - 2. אמת את המקור ותקן כל שגיאה שדווחה. - 3. הזן את זהות המדיניות ופרסם אותה, לאחר מכן השתמש ב-**library** כדי להשוות או להשבית גרסאות. - 4. בחר **enforcement** כאשר הגרסה מוכנה לפרישה בתוך המכונה. + + 1. פתח את בעיית הממצא תחת **Analyze → issues** ובדוק את התקופות המצוטטות שלה, הסיבה השורש, וההמלצה. + 2. בחר **generate policy**. Failproof AI תגיד תחילה אם מדיניות יכולה בכלל להביע את הבעיה. תוצאה של **no policy** אומרת שהתיקון הוא התראה, שינוי זרימת עבודה, או אדם — לא מדיניות. + 3. בחר **write this policy**. כותרת הבעיה, הממצא, הסיבה השורש, ההמלצה, וכוונת האכיפה המוצעת הופכות לטיוטה ב-**Admin → policy editor**. השתמש ב-**open the editor anyway** כשאתה לא מסכים עם בדיקת המועמדות. - ![תצוגת הרכבה של עורך המדיניויות עם זהות מדיניות, טיוטה בסיוע AI, אימות מקור, ובקרי פרסום.](/images/dashboard/policy-editor.png) + ![תצוגת הרכבה של עורך המדיניות עם זהות מדיניות, טיוטה בעזרת AI, אימות מקור, ובקרות פרסום.](/images/dashboard/policy-editor.png) - פרסם מ-CLI באמצעות `fp policies publish`. זה יוצר **גרסה חדשה** ולעולם לא עורך אחת במקום, והוא בודק ניתוח מקור עם node לפני השליחה — שום דבר בהמשך לא עושה זאת, כך ששגיאת תחביר הייתה מופיעה אחרת במכונה בזמן הטמעה: + קרא את הראיות, ואז שרטט עם העוזר. `compose` מדפיס מקור לך לבדיקה ולא מפרסם כלום: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - פרסום לא מטמיע דבר — גרסה חדשה יושבת ללא שימוש עד ש-`fp fleet deploy` מניחה אותה במכונה. `fp policies compose ""` יוצרת טיוטת מקור בעזרת Cloud assistant והדפסה אותה לבדיקה ולא מפרסמת אותה. - - כדי להתקין מדיניות לתוך agent CLI מקומי במקום זאת (לא Cloud), השתמש ב-`failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. + `compose` זקוק לתקופה שנכנסה (fp login) שתפקידה יש `policies:write`; היא מסרבת מפתחות API. -## רשימת בדיקה של יצירה +### 3. בדוק את הטיוטה + +טיוטה היא נקודת התחלה, לא פסק דין. לפני פרסום, בדוק כי היא: + +1. קוראת למצב הכשל בשפה תפעולית. +2. מתאימה רק להתרחשויות ווקט וכלים שנושאים מספיק ראיות להחלטה. +3. משתמשת בתנאי הצר ביותר שתופס את הפעולה הלא בטוחה. +4. מחזירה סיבה שאומרת לסוכן מה לעשות במקום זאת. +5. משתמשת ב-`instruct` כאשר הסוכן יכול בבטחה לתקן את הקורס, ו-`deny` רק היכן שאפשר את הפעולה היא בלתי קבילה או בלתי הפיכה. + +אמת את המקור בעורך ותקן כל שגיאה שדווחה. + +### 4. תקדד וערך פרסום + +הרץ **backtest** תחת המקור לפני שאתה מפרסם: היא משדרת מחדש את הטיוטה בעומת קריאות שהצי שלך כבר ביצע ותספר את הקריאות העובדות שהיא הייתה מפריעה. [בדיקת מדיניות](/he/policies/test) מכסה את זה ואת הבדיקות האחרות. + +כשהיא מתנהגת, הכנס את זהות המדיניות ובחר **publish version**. פרסום יוצר גרסה בלתי הפיכה ולא פורס כלום: היא יושבת לא בשימוש עד שאתה [פורסום אותה](/he/policies/deploy). מסוף: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` בדוקת ניתוח את המקור לפני שליחתו, כדי שגיאת תחביר משטחים כאן במקום על מכונה בזמן אכיפה. + +## כתוב זאת בעצמך + +מדיניות היא JavaScript או TypeScript בעומת ה-API של `failproofai`: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +זה תואם `production/config.yml`, `/srv/production/config.yml`, `/srv/production`, ו-`C:\\production\\config.yml` עבור both `Write` ו-`Edit`, אך לא `production-backup`: `production` צריך להיות קטע נתיב שלם. הקשר גם נושא את סוג ההתרחשות, העומס הנורמלי, מטא נתוני תקופה, פרמטרים, וCLI מקור כשזמין — ראה את [SDK מדיניות](/he/reference/policy-sdk). + +כדי לפרסם זאת כגרסה, הדבק את המקור לתוך **compose** ב-**Admin → policy editor** ובצע שלבים 3 ו-4 לעיל, או פרסם את הקובץ מסוף עם `fp policies publish`. -1. שם את מצב הכשל בשפה תפעולית. -2. בחר את אירועי ה-hook והכלים המכילים ראיות מספיקות להחלטה. -3. כתוב את התנאי הצר ביותר התואם להתנהגות לא בטוחה. -4. החזר סיבה שמספרת לסוכן או למפעיל מה לעשות בשלב הבא. -5. הוסף דוגמאות שצריכות להתאים ודוגמאות שחייבות להישאר מותרות. -6. שמור גרסה חדשה וביקש ביקורת. +כדי להריץ אותו על מכונה ללא Cloud, שמור אותו תחת `.failproofai/policies/` עם שם המסתיים ב-`policies.js`, `policies.mjs` או `policies.ts` — אלה טוענים באופן אוטומטי בתחום פרויקט ומשתמש — או התקן אותו לפי נתיב: -השתמש ב-`instruct` כאשר הסוכן יכול בתוקף תיקון הקורס. השתמש ב-`deny` כאשר ההתרת הפעולה תיצור סיכון בלתי קביל או בלתי הפיך. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - גרסאות מדיניות הן קלטי פריסה בלתי שינויים. עריכת טיוטה יוצרת גרסה חדשה; היא לא צריכה לשכתב את הגרסה שכבר הוקצתה למכונות. - \ No newline at end of file +תן לכל מדיניות שם שהוא ייחודי על פני כנס, מותאם אישית, חבילה, ומדיניות מנוהלת בענן. \ No newline at end of file diff --git a/docs/he/policies/failure-behavior.mdx b/docs/he/policies/failure-behavior.mdx index 3a9e64bd..a88ae8da 100644 --- a/docs/he/policies/failure-behavior.mdx +++ b/docs/he/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- -title: "התנהגות כשלון" -description: "הבן מה קורה כאשר הערכת מדיניות או ה-daemon המקומי אינם זמינים." +title: "התנהגות כישל" +description: "הבן מה קורה כאשר הערכת המדיניות או ה-daemon המקומי אינם זמינים." icon: "shield-alert" --- -Failproof AI מעוצב כך שכשל בהאכיפה יהיה גלוי במקום לאפשר בשתיקה עבודה מסוכנת. +Failproof AI מעוצב כך שכשל באכיפה יהיה גלוי ולא יאפשר בשקט עבודה סיכונית. -## אבחן בלוק סגור כשל +## אתר בלוק סגור כישל - 1. עבור אל **Admin → enforcement** ופתח את המכונה. - 2. בדוק את ה-check-in האחרון שלה, ההטמעה שהוקצתה, וההטמעה המדווחת. - 3. עבור אל **Observe → policy** ופתח את ההפעלה של החלטת ההכחשה. - 4. אשר האם הסיבה מדווחת על נגישות daemon, סטיית גרסה, או המדיניות עצמה. + 1. עבור ל-**Admin → enforcement** ופתח את המכונה. + 2. בדוק את ה-check-in האחרון שלה, ההטמעה שהוקצתה וההטמעה שדווחה. + 3. עבור ל-**Observe → policy** ופתח את הסשן של החלטת ההכחשה. + 4. אשר אם הסיבה דווחה על נגישות daemon, חוסר התאמה גרסה או המדיניות עצמה. @@ -23,45 +23,47 @@ Failproof AI מעוצב כך שכשל בהאכיפה יהיה גלוי במקו failproofai config ``` - הפעלה חוזרת של `failproofai config` מעדכנת ומפעילה מחדש את ה-daemon לאחר שדרוג חבילה. + הרצה חוזרת של `failproofai config` מעדכנת ומפעילה מחדש את ה-daemon לאחר שדרוג חבילה. -על מכונה המוגדרת לשימוש ב-`failproofaid`, ה-daemon הוא המעריך היחיד. אם הוא אינו נגיש או שגרסת הפרוטוקול שלו אינה תואמת ל-CLI, הערכת ה-hook נכשלת בצורה סגורה. הפעולה נדחית עם סיבה שמכוונת את מפעיל המערכת לבדוק או לעדכן את ה-daemon. +במכונה המוגדרת להשתמש ב-`failproofaid`, ה-daemon הוא המעריך היחיד. אם הוא אינו נגיש או שגרסת הפרוטוקול שלו אינה תואמת את ה-CLI, הערכת hook נכשלת בהחלטה סגורה. הפעולה מוכחשת עם סיבה המנחה את המפעיל לבדוק או לעדכן את ה-daemon. -לפני תצורת daemon, ה-hooks מעריכים מדיניות בתהליך. לאחר שתצורת daemon מתועדת, Failproof AI לא חוזר בשתיקה למעריך שני כאשר ה-daemon נכשל. +לפני הגדרת daemon, hooks מעריכים מדיניות בתוך התהליך. ברגע שהגדרת daemon נרשמה, Failproof AI לא חוזרת בשקט למעריך שני כאשר ה-daemon נכשל. -## הגב להחלטה סגורה כשל +## התגובה להחלטה סגורה כישל 1. הרץ `failproofai config --status`. -2. אם הגרסאות שונות, הרץ `failproofai config` חוזר לאחר עדכון החבילה. +2. אם גרסאות שונות, הרץ שוב `failproofai config` לאחר עדכון החבילה. 3. אם ה-daemon אינו נגיש, בדוק את מצב השירות שלו ויומנים מקומיים. -4. התחל את עבודת הסוכן רק לאחר שנתיב הערכת מדיניות ידוע הוא בריא. +4. המשך בעבודת agent רק לאחר שנתיב הערכת מדיניות ידוע הוא בריא. - אל תנסה שוב ושוב את הפעולה המחסומה. תגובה סגורה כשל פירושה שהמערכת לא יכלה לקבוע שהפעולה הייתה בטוחה. + אל תנסה שוב בעלבון את הפעולה החסומה. תגובה סגורה כישל פירושה שהמערכת לא יכלה לקבוע שהפעולה הייתה בטוחה. -## חבילה לא תיטען +## pack לא יטען -מכונה שנאמר לה להטיל כוח על חבילה, ולא יכולה להריצ אותה, דוחה במקום להמשיך בשקט. התנעה היא **הצפיית מתועדת**, לא עומדת ריקה: מכונה ללא חבילות מותקנות היא שקטה, בעוד שחבילה שהוכרזה ולא תיפתר — או שתרשום פחות ממה שמניפסט שלה מכריז — דוחה. +מכונה שנאמרה לה להטיל מדיניות על pack, ולא יכולה להפעיל אותו, מכחשת ולא ממשיכה בשקט. הטריגר הוא **ציפייה רשומה**, לעולם לא ציפייה ריקה: מכונה ללא packs מותקנים היא שקטה, בעוד ש-pack שהוצהר ולא יתחקה — או שמרשם פחות מהמניפסט שלו — מכחש. -ההכחשה **צרה**, בניגוד ל-daemon אינו נגיש. daemon שלא ניתן להגיע אליו פירושו שלא התרחשה הערכה כלל, כך שלא ניתן לדעת שום דבר בטוח. חבילה שלא תיטען יש לה קבוצה ספירה של שומרות חסרות, מכיוון שכל מדיניות שהוכרזה נושאת את שלה `match` — כך שהיא דוחה רק את האירועים והכלים שמדיניויות אלו כיסו, והכל האחר ממשיך. +ההכחשה היא **צרה**, בניגוד ל-daemon אינו נגיש. ה-daemon שלא ניתן להגיע אליו פירושו שלא התרחשה הערכה בכלל, כך שלא ניתן לדעת שום דבר בטוח. pack שלא יטען יש קבוצה ניתנת לספירה של שומרים חסרים, מכיוון שכל מדיניות מוצהרת נושאת את `match` שלה — כך היא מכחשת רק את האירועים והכלים שמדיניויות אלה כיסו, והכל האחר ממשיך. -זה לא יורה ל: +זה לא בוער עבור: -- חבילת `observe`, שמעריכה והשלכה על ידי קונסטרוקציה -- מדיניויות שלא לקחת, או שכיבית בהצהיר -- חבילה שלא קיבל הטוען, כאשר "אין רישומים" לא יכול להיות מובחן מדלג מכוון -- השהיית הפעלה פעילה -- פסק זמן טעינה, שהוא זמני — רגע דיסק אחד איטי חייב לא להכחיש עד שאדם מתערב +- `observe` pack, שמעריך ומשליך בבנייה +- מדיניויות שלעולם לא לקחת, או כיבית במפורש +- pack שהטוען לעולם לא קיבל, כאשר "אין רישומים" לא יכול להיות מובחן מדילוג מכוון +- השהיית סשן פעילה +- timeout טעינה, שהוא זמני — רגע דיסק איטי אחד לא חייב להכחיש עד שאדם מתערב -`UserPromptSubmit` **משקיע** במקום להכחיש, כל מה שהמדיניות החסרה הכריזה. הכחשה כוללת תיקח אותה יחד ותנעל אתכם מן הסוכן שיכול לתקן את הבעיה. +`UserPromptSubmit` **מורה** במקום להכחיש, כל מה שהמדיניות החסרה הצהירה. כחיוב כולל היה לוקח אותו ולנעל אותך מה-agent שיכול לתקן את הבעיה. ### מה לעשות ```bash -failproofai pack list +failproofai policies ``` -זה מוציא שם כל חבילה מותקנת שלא תיטען, אומר למה, יוצא שאינו אפס. ואז או התקן אותה מחדש (`failproofai pack add `) או הסר אותה (`failproofai pack remove `) — הסרתה משוך את ההצפיה, וההכחשה מפסיקה איתה. \ No newline at end of file +הרשימה מדגילה pack מותקן שרשומת ההתקנה שלו או digest כבר לא חוקק, ואומר למה. זה לא מייבא את ה-pack, כך שזה שנכשל רק לאחר שהוא טוען — נרשום פחות מהמניפסט שלו — מופיע כנורמלי; ההכחשה למטה היא מה שמזהה את זה. בכל מקרה, התקן אותו מחדש (`failproofai policies add `) או הסר אותו (`failproofai policies remove `) — הסרתו חוקרת את הציפייה, וההכחשה עוצרת איתו. + +ההכחשה עצמה מיוחסת ל-`pack/failproofai-pack-unavailable`, אשר עדיף על המדיניויות שעלו, כך שקריאת כלי חסומה משמה את ה-pack החסר ולא איזה שומר שרד שקרה לטלוח ראשון. \ No newline at end of file diff --git a/docs/he/policies/local-configuration.mdx b/docs/he/policies/local-configuration.mdx index e7887e94..04531b53 100644 --- a/docs/he/policies/local-configuration.mdx +++ b/docs/he/policies/local-configuration.mdx @@ -1,55 +1,49 @@ --- -title: "הגדרות מקומיות" -description: "שלוט בטווח המדיניות, בפרמטרים, בקבצים מותאמים אישית והגדרות Failproof AI ברמת המכונה." +title: "תצורה מקומית" +description: "שלוט בטווח המדיניות, בפרמטרים, בקבצים מותאמים אישית, והגדרות Failproof AI ברמת המכונה." icon: "file-cog" --- -Failproof AI מפריד בין בחירת מדיניות לבין הגדרות מכונה ו-daemon. זה שומר על בחירות מדיניות במאגר בהיקף ניתן לבדיקה בעוד שאישורים ומצב daemon נשארים מחוץ למאגר. +Failproof AI שומר על הפרדה בין מה שמאגר יכול לבצע commit — חיווט hook, פרמטרי מדיניות, מדיניויות מותאמות אישית — לבין מצב המכונה כגון אישורים, חבילות מותקנות, והדימון. -## בחר טווח מדיניות +## בחר טווח - - - הרץ `failproofai` ללא ארגומנטים כדי לפתוח את לוח הבקרה של המדיניות המקומית. בחר בטווח משתמש, פרויקט או מקומי לפני הפעלת מדיניות כך שהשינוי יכתב לקובץ התצורה המיועד. +טווח קובע היכן מחוברים ה-hook, ואיזה קובץ תצורה אתה כותב פרמטרים ונתיבי מדיניויות מותאמים אישית אליו: - - **משתמש** חל על פני פרויקטים במכונה זו. - - **פרויקט** שייך למאגר וניתן לביצוע commit. - - **מקומי** דורס פרויקט אחד עבור משתמש אחד ויש להישאר gitignored. +- **User** חל על כל הפרויקטים במכונה זו. +- **Project** שייך למאגר וניתן לבצע עליו commit. +- **Local** מחליף פרויקט אחד לרמת משתמש אחד ויש להישאיר אותו ב-gitignore. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # wire hooks for this repository +failproofai policies --install --cli claude --scope user # or for every project on this machine +failproofai policies +``` - לא כל harness תומך בטווח מקומי. ה-CLI דוחה טווח שה-harness הנבחר לא יכול לייצג. - - +לא כל harness תומך בטווח מקומי; ה-CLI דוחה טווח שה-harness הנבחר לא יכול לייצג. + +איזו מדיניויות חבילה מופעלות **אינו** בתחום הטווח. המתג מתועד עם החבילה המותקנת, לכן `failproofai policies add ` מפעיל מדיניות עבור כל המכונה, ללא קשר למה `--scope` אומר. -| טווח | קובץ תצורת מדיניות | +| Scope | קובץ תצורת מדיניות | | --- | --- | -| פרויקט | `/.failproofai/policies-config.json` | -| מקומי | `/.failproofai/policies-config.local.json` | -| משתמש | `~/.failproofai/policies-config.json` | +| Project | `/.failproofai/policies-config.json` | +| Local | `/.failproofai/policies-config.local.json` | +| User | `~/.failproofai/policies-config.json` | -מדיניויות מופעלות מתמזגות כאיחוד. פרמטרים של מדיניות משתמשים בטווח הראשון המגדיר פרמטרים עבור אותה מדיניות, בסדר project → local → user. נתיבי מדיניות מותאמים אישית ממפורשים משתמשים בטווח הראשון המגדיר אותם. +פרמטרי מדיניות משתמשים בטווח הראשון המגדיר פרמטרים לאותה מדיניות, בסדר project → local → user. נתיבי מדיניות מותאמים אישית מפורשים משתמשים בטווח הראשון המגדיר אותם. -## הגדר פרמטרים של מדיניות +## הגדר פרמטרי מדיניות - פתח את המדיניות בלוח הבקרה המקומי, ערוך את הפרמטרים הנתמכים שלה, והשמור בטווח הנבחר. הרץ פעולת agent תואמת ולא תואמת, ואז בדוק את ההחלטה ב-**Observe → policy**. + פתח את המדיניות בדוח הבקרה המקומי, ערוך את הפרמטרים הנתמכים שלה, ושמור בטווח שנבחר. הפעל פעולת agent תואמת ולא תואמת, ואז בדוק את ההחלטה ב-**Observe → policy**. - ערוך את `policies-config.json` של הטווח הנבחר, ואז הרץ `failproofai policies` כדי להעלות שמות מדיניות או מפתחות פרמטרים לא ידועים. + ערוך את ה-`policies-config.json` של הטווח שנבחר, ואז הרץ `failproofai policies`: הוא מזהיר לגבי ערך `policyParams` השם מדיניות שלא חבילה מותקנת נושאת. הוא לא בודק את המפתחות בתוך ערך, לכן בדוק את הכתיב שלהם מול הטבלה למטה. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ Failproof AI מפריד בין בחירת מדיניות לבין הגדרות +### פרמטרים שמדיניויות Failproof AI מקבלות + +כל מדיניות מאמתת את סוגי הפרמטרים שלה. + +| מדיניות | פרמטר | סוג וברירת מחדל | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; ערכים מכילים `regex` ו-`label` | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| Infrastructure blockers | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + דפוס allow מרחיב את מה שה-agent יכול לעשות. בדוק את הטוקניזציה המדויקת וריאציות הפקודה ב-harness היעד לפני פריסה שלה על פני צי. + + ## הבן את קבצי המכונה `~/.failproofai` מכיל קבצים נפרדים עבור גבולות אמון נפרדים: -| נתיב | תכלית | +| נתיב | מטרה | | --- | --- | -| `config.json` | הגדרות daemon, ביקורת וטלמטריה ללא סוד | -| `credentials.json` | אישורי Cloud; מאוחסנים עם הרשאות רק בעלים | -| `policies-config.json` | בחירת builtin בטווח משתמש, פרמטרים ונתיבים מותאמים אישית ממפורשים | -| `policies/` | מדיניויות קונוונציה משתמש וחפצי מדיניות מנוהלים בענן | -| `hook-activity/` | יומן החלטות מדיניות מקומיות | -| `state/` | daemon spool, בריאות, השהיה ומצב זמן ריצה | +| `config.json` | הגדרות daemon, ביקורת וטלמטריה שאינן סודיות | +| `credentials.json` | אישורי ענן; מאוחסנים עם הרשאות בבעלות בלבד | +| `policies-config.json` | פרמטרי טווח user ונתיבי מדיניויות מותאמות אישית מפורשות | +| `policies/` | מדיניויות מוסכמה של משתמש, חבילות מותקנות ומדיניויות שלהן מופעלות, וחפצי מדיניות המנוהלים בענן | +| `hook-activity/` | יומן החלטות מדיניות מקומי | +| `state/` | spool דימון, בריאות, השהייה, וזמן ריצה | -השתמש ב-`FAILPROOFAI_HOME` כדי להעביר את פריסת המכונה המוחלטת עבור קונטיינר או בדיקה מבודדת. אל תעביר ספריות מצב בודדות באופן עצמאי. +השתמש ב-`FAILPROOFAI_HOME` לשינוי מיקום של הפריסה המלאה של המכונה עבור container או בדיקה מבודדת. אל תשנה מיקום של ספריות מצב בודדות בנפרד. - לעולם אל תבצע commit ל-`credentials.json`. בצע commit לתצורת מדיניות פרויקט ולמדיניויות קונוונציה פרויקט רק לאחר בדיקתם כקוד אכיפה. + לעולם אל תבצע commit ל-`credentials.json`. בצע commit לתצורת מדיניות פרויקט ומדיניויות מוסכמה של פרויקט רק לאחר בדיקתן כקוד אכיפה. \ No newline at end of file diff --git a/docs/he/policies/overview.mdx b/docs/he/policies/overview.mdx index 42c9b8c1..2e1df551 100644 --- a/docs/he/policies/overview.mdx +++ b/docs/he/policies/overview.mdx @@ -1,63 +1,54 @@ --- title: "מדיניויות" -description: "צפה, הנחה או חסום פעולות סוכן לפני שכישלון ידוע חוזר על עצמו." +description: "התבונן בפעולות סוכן, הנחה אותן או חסום אותן לפני שכישלון ידוע חוזר על עצמו." icon: "shield-check" --- מדיניות מעריכה אירוע hook של סוכן ומחזירה אחת משלוש החלטות: - `allow` מאפשרת להפעולה להמשיך. -- `instruct` נותנת הנחיה תיקונית לסוכן. +- `instruct` נותנת לסוכן הדרכה תיקונית. - `deny` חוסמת את הפעולה עם סיבה. -## השתמש בשלוש משטחי המדיניות +## היכן מדיניויות נמצאות - - - 1. עבור אל **Observe → policy** כדי לסנן ולבדוק החלטות מדיניות מהפגישות. - 2. עבור אל **Admin → policy editor** כדי להרכיב, לאמת, לפרסם, להשבית או לבדוק גרסאות בלתי משתנות. - 3. עבור אל **Admin → enforcement** כדי להקצות גרסאות והשפעות למחשבים. +| בלוח הבקרה | מה אתה עושה שם | +| --- | --- | +| **Observe → policy** | בדוק החלטות מפגישות אמיתיות: איזו מדיניות התאימה, על איזו מכונה, ולמה | +| **Admin → policy editor** | כתוב מדיניות, בדוק אותה אחורה מול תעבורה קודמת, פרסם גרסה בלתי משתנה, והשווה גרסאות ב-**library** | +| **Admin → enforcement** | שים גרסאות על מכונות, במצב observe או enforce | - השתמש בעמוד Policy כדי להבין מה כבר תואם לפני שתחבר או תשנה אכיפה. +עורך המדיניות הוא המקום שבו כישלון הופך לכלל. תאר את מצב הכישלון או הדבק את קוד המדיניות ב-**compose**, בדוק אחורה את הטיוטה מול תעבורה שיש לך כבר, ופרסם גרסה: - ![עמוד Policy המציג סך הכל החלטות וממפויי מדיניות מנוהלים מקומיים ובענן.](/images/dashboard/policy-observe.png) +![תצוגת compose של עורך המדיניות עם זהות מדיניות, עריכה בעזרת AI, אימות קוד, ובקרות פרסום.](/images/dashboard/policy-editor.png) - העורך הוא המקום שבו אתה הופך תנאי כישלון לקוד מקור, מאמת אותו ופורסם גרסה בלתי משתנה. +על מכונה, `failproofai policies` מרשום הכל החוסם שם. `fp policies` ו-`fp fleet` מכסים את העורך והאכיפה מטרמינל — ראה את [Cloud CLI reference](/he/reference/cloud-cli). - ![עורך המדיניות המשמש להרכבה ופרסום של גרסת מדיניות בלתי משתנה.](/images/dashboard/policy-editor.png) +## קבל מדיניות - האכיפה קובעת לאחר מכן את הגרסה המפורסמת וההשפעה שלה (צפייה או אכיפה) למחשבים. - - ![צי האכיפה המציג כיסוי מכונות וגרסאות מדיניות מוקצות.](/images/dashboard/enforcement-fleet.png) - - אמת החלטות חזרה בעמוד Policy לאחר הפריסה כך שהתצוגות של הרכבה וצי קשורות לפעילות סוכן בפועל. - - - השתמש ב-`failproofai` להתקנה מקומית ואימות מדיניות: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - השתמש ב-`fp` כדי למצוא את הפגישות והאירועים בענן המכילים החלטות מדיניות. הרכבה בענן וחלוקה בצי נשארות זרימות עבודה של לוח הבקרה. - - - -למדיניויות יש שלוש משטחים מובהקים ב-Failproof AI: - -1. **נתח החלטות** בפגישות, לוחות בקרה וב审查. -2. **הרכב גרסאות** עם כללים מובנים, קוד או עורך המדיניות. -3. **פרוס והטיל** גרסאות על מכונות נבחרות. - -התחל מממוד כישלון מאומת. הגדר את האירוע הקטן ביותר והתאמת כלים המזהים אותו, בדוק דוגמאות חוקיות וחסרות בטחון, ואז צפה לפני הטלת אכיפה. +יש שתי דרכים לקבל אחת. - - הפעל כלל שנבדק לסיכונים נפוצים של סודות, קליפות, Git, ענן וזרימת עבודה. + + תן ל-Failproof AI לכתוב אחת מממצא ביקורת, או כתוב את הקוד בעצמך, ואז בדוק ופרסם אותה בעורך. - - בטא החלטה ספציפית לזרימת עבודה ב-JavaScript או TypeScript. + + חבר חבילת מדיניות Failproof AI עבור המקרה שלך, או חבילת קהילה מ-policy hub, בפקודה אחת. - \ No newline at end of file + + +## אחר כך שלח אותה + + + + בדוק אחורה את הטיוטה מול תעבורה שיש לך כבר, והרץ אותה מול פעולה שעליה היא חייבת לחסום ואחת שעליה היא חייבת להתיר — הכל לפני שאתה מפרסם. ראה [Test a policy](/he/policies/test). + + + שים את הגרסה על מכונות במצב **observe**, קרא את ההחלטות שלה, ואחר כך אכוף. ראה [Deploy a policy](/he/policies/deploy). + + + כל פרסום הוא גרסה חדשה ובלתי משתנה, כך שגלגול שחוסם עבודה תקפה מבוטל על ידי פריסה חוזרת של הגרסה הטובה האחרונה. ראה [Versions and rollback](/he/policies/rollback). + + + +כדי לשתף את המדיניויות שלך עם קבוצות אחרות, [פרסם אותן כחבילה](/he/policies/publish-a-pack). כדי לדעת מה קורה כאשר לא ניתן להעריך מדיניות בכלל, ראה [Failure behavior](/he/policies/failure-behavior). \ No newline at end of file diff --git a/docs/he/policies/packs.mdx b/docs/he/policies/packs.mdx index 0d976c9c..cfade1d4 100644 --- a/docs/he/policies/packs.mdx +++ b/docs/he/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "חבילות מדיניות" -description: "התקן קבוצה של מדיניות שפורסמה כ-GitHub release, וניהול מה שהיא אוכפת." +title: "השתמש בחבילת מדיניות" +description: "חבר חבילת מדיניות Failproof AI לעבודתך, או חבילה קהילתית מ-policy hub, ובחר מה היא אוכפת." icon: "package" --- -חבילה היא קבוצה של מדיניות שפורסמה כ-GitHub release. פקודה אחת מתקינה אותה, סכומי הביקורת של ה-release מאומתים לפני כל הרצה, והדיג'סט מתועד כך שהחבילה לא יכולה להשתנות במכונה שלך אחר כך. +חבילה היא קבוצת מדיניויות שפורסמה כ-GitHub release. פקודה אחת מתקינה אותה: checksums של ה-release מאומתים לפני כל הרצה, והdigest שלו נרשם כך שהחבילה לא יכולה להשתנות במכונתך לאחר מכן. -## התקן את מדיניות Failproof AI +עיין בכל חבילה, וכל מדיניות בכל אחת, ב-[policy hub](https://befailproof.ai/policy-hub/). יש שני סוגים: + +- **חבילות מדיניות Failproof AI** — חבילות מוכנות מראש לשימושים קבועים: חבר אחת והוא עובד. [חבילת מדיניות coding agent](https://befailproof.ai/policy-hub/failproofai/policies/) זמינה כעת, וחבילות לשימושים נוספים קרובות בדרך. +- **חבילות מדיניות קהילתיות** — מדיניויות שמפתחים כתבו לשימושים שלהם וממחו לכל מי שרוצה להשתמש בהן. + +## חבילות מדיניות Failproof AI + +### חבילת מדיניות coding agent ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -זה מתקין את הקבוצה שאנו משתפים, מהעותק בתוך החבילה — כך שזה לא דורש רשת ולא יכול להכשל מאחורי proxy. קח חלק ממנה: +החבילה כוללת 38 מדיניויות והדלקה של 10 שלה manifest סימן כבטוחות להדלקה ללא השגחה; השאר מופיעות לבחירתך. חלק מהמשומשות ביותר, ואם `policies add` פשוט מדלקות אותן: + +| מדיניות | מה היא עושה | מדולקת כברירת מחדל | +| --- | --- | --- | +| `block-push-master` | חוסמת דחיפות ישירות לענפים מוגנים | כן | +| `block-env-files` | חוסמת קריאה וכתיבה של קובצי `.env` | כן | +| `protect-env-vars` | חוסמת פקודות שמדפיסות משתני סביבה | כן | +| `block-sudo` | חוסמת `sudo` אלא אם pattern של allow תואם | כן | +| `block-curl-pipe-sh` | חוסמת סקריפטים שהורדו שחוביים ישירות לשל | כן | +| `sanitize-*` (חמש מדיניויות) | דיווח על API keys, bearer tokens, JWTs, מפתחות פרטיים, וmigration strings שנמצאים בפלט של tool | כן | +| `block-rm-rf` | חוסמת מחיקות רקורסיביות קטסטרופליות | לא | +| `block-force-push` | חוסמת force-pushes | לא | +| `block-secrets-write` | חוסמת כתיבה לקבצי credentials ו-secret-key | לא | +| `warn-destructive-sql` | מתריעה על `DROP`, `TRUNCATE`, ו-`DELETE` בלי `WHERE` | לא | + +הדלק כל אחד שהוא כבוי לפי שם — `failproofai policies add block-rm-rf` — או קח את כל החבילה עם `--all`. ראה כל מדיניות בה, מקובצת לפי קטגוריה: ```bash -failproofai pack add core --policy block-rm-rf # אחת, או כמה מופרדות בפסיק -failproofai pack add core --category dangerous-commands # קטגוריה שלמה -failproofai pack add core --all # הכל בה +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` מציין כל קטגוריה שהחבילה מציעה. +## חבילות מדיניות קהילתיות -## ראה מה חבילה מכילה, לפני התקנתה +מפתחים מפרסמים חבילות לשימושים שהם פגשו, וה-[policy hub](https://befailproof.ai/policy-hub/) מופיע בה. חבילה קהילתית פורסמה על ידי המחבר שלה, לא נסקרה על ידי Failproof AI, אז קרא מה היא כוללת לפני התקנה: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -מציין כל מדיניות שהחבילה נושאת, מקובצת לפי קטגוריה, וסימון אילו מהן המחבר שלה הפעיל כברירת מחדל ואילו הן בחירה יוצאת דופן. זה קורא **רק את המניפסט** — אומנה הכניסה לעולם לא נוצלה ולעולם לא יובאה, כך שהסתכלות על חבילה של זר לא יכול להריץ קוד של זר. המניפסט עדיין נבדק לעומת `SHA256SUMS` שלו של ה-release, כך שמה שאתה קורא הוא מה שהיה מתקין. - -`failproofai pack list` ללא מקור מציין את החבילות שכבר מותקנות כאן. +זה מופיע בכל מדיניות בה, מקובצת לפי קטגוריה, וסימנים אילו המחבר מדלק כברירת מחדל. זה קורא **רק את ה-manifest** — artifact הכניסה לעולם לא הורד או ייובא, אז בחינת חבילה זרה לא יכולה להריץ קוד זר. ה-manifest עדיין בדוק כנגד `SHA256SUMS` של ה-release שלו, אז מה שאתה קורא הוא מה שהיה מתקין. -## התקן חבילה של מישהו אחר +ואז התקן אותו: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -כל אלה עובדים — הדבק אילו שיש לך: +כל אחד מאלה עובד — הדבק את מה שיש לך: | מקור | תוצאה | | --- | --- | -| `acme/support-agent` | ה-release החדש ביותר, **מוקצה** לתג המדויק שהוא פתר | +| `acme/support-agent` | ה-release החדש ביותר, **קבוע** ל-tag המדויק שאליו הוא התפזר | | `acme/support-agent@v2.1.0` | ה-release הזה | -| `github:acme/support-agent@v2.1.0` | אותו הדבר, כתוב במפורש | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | אותו הדבר, מועתק מדפדפן | +| `github:acme/support-agent@v2.1.0` | אותו דבר, כתוב במפורש | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | אותו דבר, מועתק מדפדפן | -ללא שם תג מתקין את ה-release החדש ביותר **ומקצה אותו**, ואז אומר לך איזה תג הוא בחר. מה שמתועד תמיד שם בדיוק release אחד, כך שהתקנה מחדש לא יכולה להסחוף. +אי-שמות של tag מתקין את ה-release החדש ביותר **וקובע אותו**, ואז אומר לך איזה tag הוא בחר. מה שנרשם תמיד שומות בדיוק release אחד, אז התקנה חוזרת לא יכולה להסחף. ## קח חלק מחבילה -כברירת מחדל אתה מקבל את ברירות ה-**שלה** של החבילה — המדיניות שהמחבר שלה סימן כבטוחות להפעלה ללא השגחה — לא את כל מה שהיא מכילה. +כברירת מחדל אתה מקבל את **שלו** defaults — המדיניויות שהמחבר שלו סימן כבטוחות להדלקה ללא השגחה — לא הכל שהוא מכיל. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # אחד, או כמה מופרדים בפסיק +failproofai policies add FailproofAI/policies --category dangerous-commands # קטגוריה שלמה +failproofai policies add FailproofAI/policies --all # הכל בה ``` -`--category` ו-`--policy` משלבים כאיחוד (`--only` מקובל כמילה נרדפת ל-`--policy`). הוספה מחדש בגרסה חדשה יותר שומרת על מה שבחרת במקום להפעיל את השאר בחזרה. +`--category` ו-`--policy` משלבים כחיבור (`--only` מקובל כמילון נרדף ל-`--policy`). כשהחבילה כבר מותקנת, הדגלים מוסיפים למה שהיה לך, והוספה חוזרת ללא דגל וללא terminal — לשדרוג, נגיד — שומרת על הבחירה שלך כפי שהיא. ב-terminal ללא דגל, `add` פותח את הbenerator במקום זאת, קדם-מסומן עם defaults של המחבר, ומה שאתה מסמן מחליף את הבחירה שלך. -## ניהול מה שנמצא בהפעלה +## נהל מה זה דלוק ```bash -failproofai policies # כל מקור ברשימה אחת, חבילות כלולות -failproofai pack list # רק חבילות, מקובצות לפי קטגוריה +failproofai policies # כל מקור ברשימה אחת, חבילות כלול +failproofai policies add block-rm-rf # הדלק מדיניות אחת failproofai policies --uninstall block-refunds # כבה מדיניות חבילה אחת -failproofai policies --install block-refunds # והחזר את זה בחזרה -failproofai pack remove acme/support-agent +failproofai policies --install block-refunds # וחזור על +failproofai policies remove acme/support-agent # הסר התקנה של החבילה ``` -שם חשוף אומר את **הבנוי** כשקיים שם כזה. שם העותק של החבילה במפורש כשאתה צריך: +הדלקת מדיניות חבילה או כיבויה חל על כל המכונה: ההדלקה נרשמת עם החבילה המותקנת, לא בקונפיגורציה של פרויקט, לא משנה מה `--scope` אומר. + +שם ללא slash הוא מדיניות; כל דבר עם אחד הוא מקור חבילה. שם חשוף מתפזר לחבילה המותקנת שמצהירה עליו. כששתי חבילות מותקנות מצהירות על אותו שם, שמות זה שאתה מתכוון: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -אם חבילה משלחת מדיניות שגם שמה הוא **בנוי מאופשר**, הבנוי רץ והעותק של החבילה מדולג — אותה הגנה היה מוערכת פעמיים. כבה את הבנוי כדי להשתמש בעותק של החבילה במקום זה. - - -## מהיכן מדיניות Failproof AI באה - -`core` קורא את העותק שהנדסה בחבילת npm. אותה קבוצה משתפרת כ-GitHub release, שזה מה שאתה מתקין אם אתה רוצה גרסה ספציפית: - -```bash -failproofai pack add core # מהחבילה הזו, ללא רשת -failproofai pack add FailproofAI/policies # אותה קבוצה, מ-GitHub release שלה -``` +Scopes, פרמטרים, והקבצים שהפקודות האלה כותבות מכוסות ב-[local configuration](/he/policies/local-configuration). -## מה שלמות עושה ולא עושה +## מה אמתות עושה ולא עושה -`SHA256SUMS` משלחת בא עם האומנה באותו release, כך שזו **לא** חתימה ואינה מוכיחה דבר על מי פרסם אותה. מה שזה כן מוכיח זה שהבתים הם אלה שה-release פרסם — ובגלל שהדיג'סט מתועד כשאתה מוסיף את החבילה ומאומת מחדש לפני כל יבוא, חבילה לא יכולה להשתנות תחתיך מכונה אחר כך. מאגר שעוד שם תג או מחליף נכס מפסיק טעינה במקום להריץ בשקט משהו אחר. +`SHA256SUMS` משלח באותו release כמו artifact, אז זה **לא** חתימה וזה לא מוכיח כלום על מי פרסם אותו. מה שזה כן מוכיח הוא שהבתים הם אלה ש-release פרסם — וכי digest נרשם כשהוספת את החבילה ובדוק מחדש לפני כל import, חבילה לא יכולה להשתנות תחת המכונה שלך לאחר מכן. מאגר שretags או החלפת asset מפסיק לטעון במקום להריץ בשקט משהו אחר. -בזמן התקנה החבילה גם **יובאה פעם אחת** ובדוקה לעומת המניפסט שלה. חבילה שהאומנה שלה לא מתפררת, או שרוכשת משהו שונה מהמוצהר שלה, מסורבת לפני כל הפעלה — במקום התקנה נקיה וכישלון בקריאת הכלי הבאה שלך. +בזמן התקנה החבילה גם **ייובאת פעם אחת** ובדוקה כנגד manifest שלה שלה. חבילה שartifact שלה לא parse, או שרוזם משהו שונה מה שהוא מצהיר, נדחה לפני שום דבר מופעל — במקום התקנה נקייה והבאה לשימוש בעל השיחה הבאה שלך. ראה [Failure behavior](/he/policies/failure-behavior). -## כאשר חבילה לא תטען +## כשחבילה לא תטעון -חבילה שמכונה זו נאמרה לאכוף ולא יכולה להריץ **מכחישה** את האירועים שהמדיניות החסרה שלה כיסתה, במקום לאפשר להם בשקט. ראה [Failure behavior](/he/policies/failure-behavior). `failproofai pack list` שם כל חבילה במצב זה וצא עם קוד שלא קיים. +חבילה שהמכונה הזאת נאמרה לה לאכוף ולא יכולה להריץ **כורעת** את האירועים שהמדיניויות החסרות שלה כיסו, במקום לתיר אותם בשקט — כ`pack/failproofai-pack-unavailable`, אשר outranks המדיניויות שכן טעונות אז ה-deny יוחס לחבילה החסרה במקום לאיזה guard התרחש להירות ראשון. החריג הוא `UserPromptSubmit`, אשר מדריך במקום זאת: כורעות שם יחסמו אותך מה-agent שאתה צריך כדי לתקן אותו. ראה [Failure behavior](/he/policies/failure-behavior). -## במצב לא מקוון ומראות +## אופליין ומראות -| משתנה | השפעה | +| משתנה | אפקט | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | מסרב להביא; חבילות שכבר מותקנות ממשיכות לאכוף | -| `FAILPROOFAI_PACK_BASE_URL` | מצביע משיכת חבילה על מראה במקום `github.com` | +| `FAILPROOFAI_NO_DOWNLOAD=1` | מסרב להביא; חבילות כבר מותקנות ממשיכות לאכוף | +| `FAILPROOFAI_PACK_BASE_URL` | מצביע על הבאת חבילה במראה במקום `github.com` | -פרסום החבילה שלך: ראה [Publish a pack](/he/policies/publish-a-pack). \ No newline at end of file +כדי לשתף את המדיניויות שלך בדרך זו, ראה [Publish a policy pack](/he/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/he/policies/publish-a-pack.mdx b/docs/he/policies/publish-a-pack.mdx index 6a26119f..3b7b816f 100644 --- a/docs/he/policies/publish-a-pack.mdx +++ b/docs/he/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "פרסום חבילה" -description: "שלחו את המדיניויות שלכם כהוצאה ב-GitHub שכל אחד יכול להתקין." +title: "פרסום חבילת מדיניות" +description: "שלח את המדיניויות שלך כהוצאה ב-GitHub שכל אחד יכול להתקין." icon: "upload" --- -חבילה היא שלוש קבצים המצורפים להוצאת GitHub. `failproofai pack build` כותב את שלוש מן קובץ מדיניות שכבר יש לכם. +חבילה היא שלוש קבצים המצורפים להוצאת GitHub. `failproofai publish` כותב את שלושתם מקבצי המדיניות שלפניו, יוצר את ההוצאה, ומעלה אותם. -## 1. כתבו את המדיניויות +## 1. כתוב את המדיניויות -קובץ אחד, באמצעות ה-API זהה לכל מדיניות מותאמת אישית. שני שדות נוספים חשובים לחבילה: +התחל משהו שכבר עובד במקום תבנית עם רווחים ריקים: + +```bash +failproofai publish --init +``` + +זה שואל מה שם החבילה, כותב `.mjs`, ועוצר — ללא רשת, ללא git, שום דבר לא פורסם. הקובץ שהוא כותב היא מדיניות אחת שכבר חוסמת `git push --force`. היא מסרבת להשתיק קובץ שקיים. + +מדיניויות משתמשות באותו API כמו כל מדיניות מותאמת אישית. שני שדות נוספים חשובים עבור חבילה: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` מתחיל כברירת מחדל ל-**false** כשאתם משמיטים אותו. `failproofai pack add` פשוט מחליף רק מה שסימנתם — התקנת כל מדיניות של זר ללא השגחה אינה החלטה שהמתקין צריך לקבל עבור המשתמש שלו. +`defaultEnabled` משתחרר ל-**false** כשאתה משמיט אותו. `failproofai policies add` פשוט מפעיל רק את מה שסימנת — התקנת כל מדיניות של זר ללא השגחה היא לא החלטה שהמתקין צריך לקבל עבור המשתמש שלו. + +כתוב כמה קבצים שאתה אוהב; קובץ אחד לכל קטגוריה נקרא טוב. כל קובץ בספרייה שרושם מדיניויות משולבים לתוך ההשמעה היחידה שחבילה צריכה להיות. -הרשומה חייבת להיות **קובץ אחד עצמאי**. רק הרשומה מעוגנת בעזרת digest, כך שחבילה שמייבאת קבצים מקומיים לא יכולה להטיח דעה שה-digest מכסה מה שפועל. צרור תחילה (`esbuild`, `bun build`, `rollup`) ובנו את החבילה מהצרור — `pack build` דוחה ייבוא מקומי במקום לשלוח הבטחה שהוא לא יכול להשמור. + Bundling דורש **bun**. ללא זה, הצמד לקובץ אחד המכיל את עצמו. כך או כך הערך המפורסם לא חייב להשיג קבצים מקומיים בזמן התקנה: רק הערך מקבל סיכום כזה, כך שחבילה שנגעה לשכנים לא יכולה בכנות לטעון שהסיכום מכסה מה שרץ — ו-`publish` מסרב לאחד במקום לספק הבטחה שהוא לא יכול לשמור. -## 2. בנו את נכסי ההוצאה +## 2. נסה את זה כאן תחילה + +לפני שמישהו אחר יכול לראות את זה, אכוף את הקובץ על המכונה הזו: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +כל נתיב, כל שם קובץ. בקש מהסוכן שלך לעשות את הדבר שחסמת וצפה בה להיחסם. שום דבר לא פורסם ואף אחד אחר לא מושפע. [בדוק מדיניות](/he/policies/test) מכסה את השאר: המקרה הלגיטימי שזה חייב לאפשר, וההקלדות שמשברות אותה. + +## 3. פרסום אותה + +```bash +failproofai publish ``` -הוא כותב שלוש קבצים, ומאמת כל מדיניות ב-**כללי של הטוען עצמו** תחילה — כך שחבילה שלעולם לא יכולה להתקין נכשלת כאן, כאשר אתם יכולים לתקן זאת: +זה מגלה לאן לפרסום, מה לשבור ואיזה גרסה לקרוא לה, וonly שואל כשום דבר במאגר לא אומר לה. לפי סדר, עוצר לפני שהוא יוצר הוצאה אם משהו לא בסדר: + +1. מוצא את קבצי המדיניות כאן לפי **תוכן** — אלה המייבאים `failproofai` וקוראים `customPolicies.add` — במקום לפי שם קובץ, אז הוא מוצא `guards.mjs` ומתעלם מ-`policies.mjs` לא קשור. זה לא יורד לתוך תיקיות משנה, כך ש-fixture בדיקה לא נחטף מקרי. +2. קורא את ה-repo מ-`git remote get-url origin`, בספרייה של **הקובץ** במקום שלך, ומחליט את הגרסה. +3. מוצא את ההעלמה שלך: `GITHUB_TOKEN`, `GH_TOKEN`, או `gh auth login`. זה צריך release-write ושום דבר אחר, ולא מודפס לעולם. +4. יוצר את המאגר אם הוא לא קיים. זה קורה לפני הבנייה, כך שחבילה שנדחתה בשלב הבא יכולה להשאיר מאגר חדש מאחוריה ללא הוצאה בזה. +5. בונה את שלוש ההשמעות, תוקפת אותן עם **כללי המטען שלהם** — אותו קוד שמחליט מה עלול להתקין על המכונה של זר — אז חבילה שלא יכולה להתקין לעולם נכשלת כאן, שם אתה עדיין יכול לתקן אותה. +6. יוצר או מעיד מחדש את ההוצאה ומעלה, החלפת הנכסים של אותו שם. | קובץ | מה זה | | --- | --- | -| `failproofai-pack.json` | המניפסט: id, version, effect, ורשומה אחת לכל מדיניות | -| `failproofai-pack.mjs` | הרשומה שלכם, כמות שהיא | -| `SHA256SUMS` | ` ` לשניים האחרים | +| `failproofai-pack.json` | המניפסט: id, גרסה, השפעה, וערך אחד לכל מדיניות | +| `failproofai-pack.mjs` | הערך המשולב שלך | +| `SHA256SUMS` | ` ` עבור השניים האחרים | -דחוי בזמן בנייה: id שאינו `publisher/name`, שם מדיניות המכיל `/`, מדיניות המצהירה על `alwaysOn`, חסרון `description`, `category` או `match`, רשומה שלא רושמת כלום, ורשומה שמייבאת קבצים מקומיים. +שמות הנכסים קבועים — הם מה שה-CLI של הצרכן בונה את כתובות ה-URL שלה מ, ללא קריאת API וללא גילוי. -## 3. צרפו אותם להוצאה +נדחה בזמן בנייה: id שאינו `publisher/name`, שם מדיניות המכיל `/`, מדיניות המצהירה `alwaysOn`, חסרה `description`, `category` או `match`, ערך שלא רושם שום דבר, וערך המייבא קבצים מקומיים. -תייגו את ההוצאה עם אותה גרסה שבנויה, וצרפו את שלוש הקבצים כנכסי הוצאה: +עקוף כל דבר שהחלטת: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -כל אחד יכול להתקין זאת כעת: +`--id` קובע את معرّف החבילה כאשר הוא צריך להיות שונה מ-repo, `--tag` קובע את תג ההוצאה, `--notes` מחליף את הערות ההוצאה שנוצרו — שבו `policies show --releases` קורא את הספירות וההחייבות של כל הוצאה מ- — `--out` בוחר לאן כתובים הנכסים (ברירת מחדל `dist-pack`), ו-`--dry-run` בונה אותם ללא פרסום ודורש ללא העלמה. -```bash -failproofai pack add acme/support-agent -``` +כל אחד יכול כעת להתקין אותו עם `failproofai policies add acme/support-agent`. ראה [חבילות מדיניות](/he/policies/packs) כדי להצמיד גרסה ולקחת רק חלק מאחד. + +### רשמו את זה ברכזת המדיניות -שמות הנכסים קבועים — הם מה שה-CLI של הצרכן בונה את כתובות ה-URL שלו, ללא קריאת API וללא גילוי. +הוסף את הנושא `failproofai-policies` למאגר ב-GitHub. אין טופס הגשה ואין תור אישור: [מרכז המדיניות](https://befailproof.ai/policy-hub/) של הזוחל בוחר את המאגר בחלוף שלו הבא. הנושא רק שמות אותו לשיקול — מה רשום אותו היא הוצאה שהמניפסט שלה אמת נגד `SHA256SUMS` שלה ופורס תחת אותם כללים ש-CLI משתמש, שהוא בדיוק מה `failproofai publish` מייצר. + +## כיצד הגרסה מוחלטת + +הגרסה היא **הקומיט שאתה פורסם מ** — ה-sha הקצר שלו, שנים עשר תווים: `a1b2c3d4e5f6`. אין שום דבר לבחור ואין שום דבר להגביל, והגרסה שמות בדיוק לאן הבתים באו, אז פרסום אותו מקור פעמיים נותן אותה גרסה. + +הוא קורא מהעץ שלפניך, לא מהוצאות המאגר, אז קלון טרי והמכונה מנותקת מהרשת חישוב אותה תשובה ללא שאלה של GitHub מה קרה לפני. + +מכיוון שהגרסה שומרת קומיט, הקומיט הזה חייב להיות קיים. ב-terminal, `publish` כותב אותה בשבילך: היא initializes מאגר כשאין אחד, ומחייבת קבצי מדיניות שונו לפני שהוא בונה. היא **מסרבת** במקום — מסמן `--version` כדרך החוצה — כשהוא רץ ללא terminal (קומיט שנעשה על רץ CI היה קיים בשום מקום אחר), כאשר קבצים אחרים מאשר המדיניויות לא מחויבים, או בחילוץ שאין לו קומיטים עדיין. תג ב-`HEAD` מנצח על ה-sha — מישהו שתיוג `v1.2.0` אמר מה הוצאה זו היא. + +שא אין סדר שלו, אז השתמש `failproofai policies show / --releases` כדי לראות איזה הוצאה באה קודם — חדש בחלק העליון. ## משלוח גרסה חדשה -בנו עם `--version` חדש, תייגו הוצאה חדשה, צרפו את שלוש הנכסים שוב. הצרכנים מפעילים את אותו `pack add` ושומרים את כל קבוצת המשנה שבחרו; מדיניות שהם כיבו נשארת כבויה על פני ההשדרוג. +Commit את השינוי והפעל `failproofai publish` שוב — הקומיט החדש הוא הגרסה החדשה. צרכנים רץ אותו `failproofai policies add`. ללא terminal, או עם דגל בחירה, הם משמרים את תת הקבוצה שבחרו ומדיניות שהם כיבו נשאר כבוי; ב-terminal ללא דגל, הבוחר נפתח pre-ticked עם ברירות המחדל שלך והתשובה שלהם משנה את הבחירה שלהם. + +שינוי שם של מדיניות היא שינוי שוביר: מכונה שהיתה כיבתה היא כיבתה שם שלא קיים יותר, והשם החדש מגיע בכל מה `defaultEnabled` אומר. -שינוי **שם** של מדיניות הוא שינוי מפורק: מכונה שכיבתה היא כיבתה שם שלא קיים עוד, והשם החדש מגיע בכל מה ש-`defaultEnabled` אומר. +## מה המשתמשים שלך מאמינים -## מה המשתמשים שלכם מאמינים +`SHA256SUMS` חי באותה הוצאה כמו הנכס, אז זה מוכיח שהבתים הם אלה שפרסמת — לא מי שאתה. מי שיכול לכתוב למאגר יכול לכתוב שני קבצים. ההגנה של המשתמשים שלך היא שהעיכול מוקדש כשהם מתקינים, כך שמה שכתבת לא יכול להשתנות מתחתם לאחר מכן. -`SHA256SUMS` חי באותה הוצאה כמו הקנין, כך שזה מוכיח שהבתים הם אלה שפרסמתם — לא מי אתם. מי שיכול לכתוב למאגר יכול לכתוב את שני הקבצים. הגנת המשתמשים שלכם היא שה-digest עוגן כשהם מתקינים, כך שמה שאתם שלחתם לא יכול להשתנות תחתיהם לאחר מכן. +פרסום מ-repo שבו אתה שולט בגישת הכתיבה, וטיפול בהוצאת חבילה כמו פרסום חבילה. -פרסמו ממאגר שלבקרת הכתיבה שלו אתם שולטים, והתייחסו לשחרור חבילה כפרסום חבילה. +המאגר גם חייב להיות **ציבורי**. התקנות הן HTTPS אנונימי ללא העלמה להצעה, אז repo פרטי קיים מסורב לפני שום דבר בנוי או עלה, וכל `publish` יוצר הוא ציבורי מאותה סיבה. `--allow-private` עוקף זה עבור מישהו הנותן את שלוש ההשמעות בדרך אחרת, ואומר בבהיר שלא `policies add` יכול להגיע אליהם. רק ההוצאה חשובה: התקנות קוראות `releases/download//` ולא נוגעות לעץ git שלך. -## צפו לפני שאתם אוכפים +## צפוי לפני שתאכוף -מניפסט עשוי להצהיר על `"effect": "observe"`. מדיניויות אלה פועלות וההוראות שלהן **נרשמות והודחות** — כלום לא חסום. זה הדרך למדוד כלל חדש מול תעבורה אמיתית לפני שיכול להפריע לעבודה של מישהו. +מניפסט עלול להצהיר `"effect": "observe"` — `failproofai publish --effect observe` הוא מה שמגדיר אותה. המדיניויות האלה רצות וההחלטות שלהן **נרשמות והשלכות** — שום דבר לא חוסם. זו הדרך למדוד כלל חדש נגד תנועה אמיתית לפני שהוא יכול להפריע לעבודה של מישהו. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/he/policies/rollback.mdx b/docs/he/policies/rollback.mdx index 7099da70..765544d1 100644 --- a/docs/he/policies/rollback.mdx +++ b/docs/he/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "חזרה לגרסה קודמת" -description: "שחזור פריסת מדיניות ידועה כאשר רולאוט משבש עבודה תקינה של agents." +title: "גרסאות וחזרה לגרסה קודמת" +description: "כל פרסום הוא גרסה בלתי משתנה, ולכן הטלת גרסה החוסמת עבודת סוכן תקינה מבוטלת על ידי הצבת הגרסה האחרונה הטובה." icon: "rotate-ccw" --- -חזרה לגרסה קודמת משנה את הגרסה המפורסת או מסירה הקצאת מדיניות; היא לא מוחקת את היסטוריית ההחלטות המסבירה את התקרית. +גרסת מדיניות שפורסמה לעולם לא משתנה. עריכת מדיניות ופרסום שוב יוצרת גרסה חדשה; לעולם לא משכתבת את זו שכבר על המכונות. זה מה שהופך את החזרה לגרסה קודמת לבטוחה: הגרסה האחרונה הטובה עדיין שם, בדיוק בת לבת, והחזרה לא מחוקה את היסטוריית ההחלטות שמסבירה מה השתבש. -## חזרה לגרסה קודמת של מכונה +## חיפוש גרסה - 1. עבור ל-**Admin → enforcement**, הרחב את המכונה המושפעת וזהה את מערך המדיניות של הגרסה הידועה האחרונה שלה. - 2. בחר **edit**, שחזר את הגרסאות והשפעות אלה, והחל את הפריסה החדשה. - 3. המתן לבדיקת מכונה, ואז אמת את הפריסה המדווחת. - 4. פתח **Observe → policy** ואת הסשנים המושפעים כדי לאשר שעבודה תקינה כבר לא חסומה. + עבור אל **Admin → policy editor** ופתח את **library** כדי להשוות גרסאות של מדיניות או להשבית אחת. + + + ```bash + fp policies list # כל גרסת מדיניות + fp policies show # גרסה אחת, עם המקור שלה + ``` + + +## חזרה לגרסה קודמת על מכונה + + + + 1. עבור אל **Admin → enforcement**, הרחב את המכונה שהושפעה, וזהה את קבוצת המדיניות הטובה האחרונה שלה. + 2. בחר **edit**, שחזר את הגרסאות והאפקטים האלה, והחל את ההצבה החדשה. + 3. המתן לבדיקה שלך של המכונה, ולאחר מכן אמת את ההצבה המדווחת. + 4. פתח את **Observe → policy** והסשנים המושפעים כדי לאשר שעבודה תקינה כבר לא חסומה. - חזרה לגרסה קודמת בפריסת Cloud היא זרימת עבודה של dashboard. השתמש בסטטוס מקומי כדי לאשר שהפריסה המתוקנת הגיעה למכונה: + כל הצבה למכונה היא דור שמסופר. רשום אותם, ואז חזר לאחד: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` משהה מדיניויות builtin, custom וconvention עבור סשן מקומי אחד. היא לא משהה מדיניויות המנוהלות על ידי Cloud, ולכן היא לא דרך עקיפה לפריסת Cloud גרועה. + `rollback` יוצר דור חדש שנושא את הקבוצה הישנה במקום להחזיר את המונה, כך שהיסטוריה נשארת append-only, והוא מסרב לדור שקוראים לו מדיניות מכיוון שהושבתה או נמחקה. זה דורש סשן עם כניסה חתום עם `policies:write`. `fp fleet diff ` מראה מה היה מעוצב לעומת מה שהמכונה יישמה — זה נקרא `behind` עד שהמכונה תסקור בפעם הבאה — ובמכונה עצמה, `failproofai policies` מפרטת את ההצבה שהיא מפעילה. +## הסר מדיניות אחת מכל מכונה + +```bash +fp policies disable # הסר אותה מכל הצבה שנושאת אותה +fp policies enable # הוסף אותה חזרה +``` + +כל אחת יוצרת דור חדש בכל הצבה שהיא משפיעה עליה. חזרה לגרסה קודמת של אחד מהדורים האלה היא לא איך אתה משחזר `disable`, אם כן — `rollback` מסרב לדור שקוראים לו מדיניות שהושבתה, וכל דור מלפני ההשבתה קוראים לזה. `fp policies enable` היא הדרך חזרה, והיא יוצרת את הדור שלה בתורה. + +## חזרה לגרסה קודמת של חבילה + +חבילה מוקצית לשחרור שהתקנת, כך שחזרה אליה אומרת התקנת אחת קודמת: + +```bash +failproofai policies show FailproofAI/policies --releases # כל גרסה שפרסמה, וכאיזו זו כאן +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # הקצה את זו +``` + +ללא טרמינל, או עם `--policy`, `--category` או `--all`, הוספה מחדש שומרת על תת-הקבוצה שבחרת. בטרמינל ללא אלה, הוא פותח את הבוחר מסומן מראש עם ברירות ההפקה של המחבר, ומה שאתה מסמן מחליף את הבחירה שלך — אז סמן שוב את מה שהיה לך. + ## מתי לחזור לגרסה קודמת -- מדיניות חוסמת פעולת production צפויה. -- נפח התאמה גדול משמעותית יותר מהחזוי של הרולאוט שנצפה. +- מדיניות חוסמת פעולת ייצור צפויה. +- נפח התאמה גבוה משמעותית מהחזוי ההנפקה שנצפה. - מדיניות תלויה בשדות שאינטגרציה לא מספקת. -- גרסה חדשה משנה התנהגות מחוץ למצב הכשל המיועד. +- גרסה חדשה משנה התנהגות מחוץ לאופן הכישלון המעוצב. -לאחר חזרה לגרסה קודמת, פתח את הסשנים המושפעים וזהה את התנאי שגרם לחיובי כוזב. צור גרסה חדשה, בדוק גם cases לא בטוחים וגם legit cases, ואז חזור על שלב ה-observe. +לאחר חזרה לגרסה קודמת, פתח את הסשנים המושפעים ומצא את התנאי מאחורי החיובי השקרי. פרסום גרסה חדשה, [בדיקה](/he/policies/test) של מקרה בלתי בטוח וגם חוקי, והתבונן בו שוב לפני אכיפה. - השהיה של enforcement יכולה להיות מתאימה במהלך תקרית, אך היא מרחיבה חשיפה עבור כל מדיניות פעילה בטווח זה. העדיפו חזרה לגרסה קודמת של גרסת המדיניות הספציפית כאשר זה אפשרי. + `failproofai config --pause` הולך מדיניות מקומיות לסשן אחד ולעולם לא מנוהלות בענן, אז זה לא יציאה מהצבת ענן רעה. השהיה גם מרחיבה חשיפה לכל מדיניות בהיקף שלה; העדף חזרה לגרסה קודמת של הגרסה היחידה שמתנהגת בצורה לא תקינה. \ No newline at end of file diff --git a/docs/he/policies/test.mdx b/docs/he/policies/test.mdx new file mode 100644 index 00000000..2e04ec1a --- /dev/null +++ b/docs/he/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "בדיקת מדיניות" +description: "בצע בדיקת אחורה של טיוטה מול תנועה שכבר יש לך, והוכח שהיא עוצרת את מה שצריך ומאפשרת את מה שחייב, לפני שכל מכונה אוכפת אותה." +icon: "flask-conical" +--- + +בדוק כל מדיניות בשתי דרכים: מול תנועה שהסוכנים שלך כבר ייצרו, ומול פעולה לגיטימית שהיא חייבת להתיר. מדיניות שנראתה רק למקרה הלא בטוח לא נבדקה. + +## בדיקת אחורה של הטיוטה + + + + עורך המדיניות משחק מחדש טיוטה מול קריאות שהצי שלך כבר ביצע, לפני שאתה מפרסם אותה. + + 1. פתח את הטיוטה ב-**Admin → policy editor**. העורך מאשר שהיא מתאימה כ-JavaScript. + 2. ב-**backtest**, בחר את הסוכנים ואת חלון הזמן להשחקה מחדש — **כל סוכן** ו-**30d** כברירת מחדל — והשאר את המסנן האחרון ב-**everything** אלא אם אתה רוצה לצמצם. + 3. בחר **run backtest**. + + ![לוח ה-backtest תחת טיוטה שמתאימה כ-JavaScript, עם שלושת המסננים שלה וה-run backtest action, מעל publish version.](/images/dashboard/policy-backtest.png) + + התוצאה היא מה שהטיוטה הייתה עושה לקריאות אלה — כולל כמה קריאות **עובדות** היה היא עוצרת. אלה חיובים כוזבים שנמצאו לפני שכל סוכן פוגש בהם: התחזק את הטיוטה והשחק אותה שוב עד שהמספר הזה הוא מספר שאתה יכול לקבל. + + + בדיקת אחורה היא תכונת dashboard. מטרמינל, הרץ את המדיניות מול אירועים שאתה מתאר במקום, למטה. + + + +## הרץ אותה מול אירוע שאתה מתאר + +`fp policies test` מריץ קובץ מדיניות על המכונה שלך מול אירוע סינתטי ובודק את ההחלטה. שום דבר לא מפורסם ותום דבר לא מגיע ל-Cloud: + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +עצב את האירוע עם `--event`, `--tool`, `--command` ו-`--file`. מסנן ה-`match` של המדיניות עצמה עדיין תקף, ולכן מדיניות שלא מכסה את האירוע שתיארת מדווחת `skipped` ולא החלטה — בדרך כלל סימן שה-`match` שלה צר יותר ממה שהתכוונת. + +## הרץ אותה על מכונה אחת + +לאחר מכן, אכוף אותה באמת על המכונה שלך, מול הסוכן שלך: + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +הפקודה הראשונה מאמתת ומתקינה את הקובץ; השנייה מאשרת שהיא נטענה, לצד כל השאר שאוכף כאן. בקש מהסוכן לעשות מה שהמדיניות עוצרת וראה שהיא תדחה, ואז עשה את הגרסה הלגיטימית וראה שהיא עוברת. לאף אחד אחר זה לא משפיע. + +על מכונה המחוברת ל-Cloud, בדוק את שתי ההחלטות תחת **Observe → policy**: סנן לפי שם המדיניות, ואז פתח כל הפעלה מקושרת כדי לאשר את קלט הכלי שהיא התאימה ואת הסיבה שהחזירה. + +## בדוק מה שמתקלקל + +ההתקנה דוחה קובץ חסר, שגיאת תחביר, ייבוא לא פתור, חריגה ברמה העליונה, או מודול שקופא בעת טעינה — אז הרץ שוב אחרי כל שינוי לקובץ או לכל דבר שהוא מייבא. בזמן אכיפה אותו קובץ שבור מתועד וביצוע מושעה כך שכל מדיניות אחרת ממשיכה לרוץ: התייחס לאזהרת טעינה ביומנים בייצור כאל אכיפה אבודה. קובצי קונבנציה נטענים ללא פקודת ההתקנה, אז שמור על שלב `failproofai policies --install --custom ` מפורש ב-CI — זה מה שגורם לבנייה להיכשל על מדיניות שבורה. + +לאחר מכן הזן לה מה שסוכנים בעצם שולחים, לא רק את הקלט שאתה צופה: שדות חסרים, שמות כלים חלופיים כגון `Write` ו-`Edit`, נתיבים של Windows, קלט שגוי. החזר בכוונה `allow`, `instruct` או `deny` בכל נתיב, שמור על הפונקציה דטרמיניסטית, וקשור כל קריאה חיצונית עם timeout קצר. + +## ואז פרסם אותה ותבחין בה + +בדיקת אחורה מראה מה המדיניות הייתה עושה לתנועה שהייתה לך; היא לא יכולה להראות מה תנועה שלא ראית עדיין תעשה. בחר **publish version** בעורך (או הרץ `fp policies publish`), ואז [פרוס אותה](/he/policies/deploy) ב-**observe** mode קודם — הפסקיות שלה מתועדות ותום דבר לא חסום — ואכוף ברגע שהתאימות שלה מפרידות בין פעולות לא בטוחות ליעילות בעל כורחך. \ No newline at end of file diff --git a/docs/he/reference/cloud-cli.mdx b/docs/he/reference/cloud-cli.mdx index 0b9ad564..c7b7c194 100644 --- a/docs/he/reference/cloud-cli.mdx +++ b/docs/he/reference/cloud-cli.mdx @@ -1,19 +1,19 @@ --- title: "Failproof Cloud CLI" -description: "עזר מלא לביצוע שאילתות וניהול Failproof AI Cloud עם fp." +description: "ספר הפניה המלא לשאילתות וניהול Failproof AI Cloud עם fp." icon: "cloud-cog" --- -השתמש ב-`fp` כדי לבדוק טלמטריית Cloud, לנהל אכיפה המנוהלת בענן (מדיניות, פריסות צי, החלטות guardrail), ולנהל ביקורות, ממצאים, בעיות, התראות, מפתחות, משתמשים, שאילתות והגדרות. השתמש ב-[`failproofai`](/he/reference/failproof-cli) עבור hooks מקומיים, מדיניות, capture, וביטוח מכונה. +השתמש ב-`fp` לבדיקת טלמטריית Cloud, ניהול כפיית Cloud (מדיניות, פריסות צי, החלטות guardrail), וניהול ביקורות, ממצאים, בעיות, התראות, מפתחות, משתמשים, שאילתות והגדרות. השתמש ב-[`failproofai`](/he/reference/failproof-cli) עבור hooks מקומיים, מדיניות, capture וההרשמה של מכונות. -התקן את Cloud CLI המשוחרר כ-tool מבודד: +התקן את Cloud CLI המשוחרר ככלי מבודד: ```bash uv tool install fp-cloud-cli fp version ``` -## התחברות +## כניסה ```bash fp login @@ -26,25 +26,25 @@ fp whoami fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` -אפשרויות globales חייבות להיות לפני הפקודה: +אפשרויות גלובליות חייבות להיות לפני הפקודה: ```bash fp --json sessions --since 24h ``` -הרץ `fp COMMAND --help` או `fp COMMAND SUBCOMMAND --help` עבור עזרה בטרמינל. +הרץ `fp COMMAND --help` או `fp COMMAND SUBCOMMAND --help` לעזרה בטרמינל. ## פקודות CLI -### Authentication +### אימות -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp login` | התחברות בעזרת קוד חד-פעמי שנשלח בדוא"ל ובחירת ארגון. | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | ביטול והסרת הפעילות המשתמש השמורה. | — | -| `fp whoami` | הצג את הזהות הנוכחית, מצב authentication, ארגון והרשאות. | — | -| `fp version` | הצג את גרסת CLI המותקנת. | — | -| `fp help` | הצג עזרה לפקודות ברמה העליונה. | — | +| `fp login` | כניסה עם קוד חד-זמני שנשלח דוא"ל וביחור ארגון. | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | שחרור והסרה של ההפעלה המשתמש השמורה. | — | +| `fp whoami` | הצגת הזהות הנוכחית, מצב אימות, ארגון והרשאות. | — | +| `fp version` | הצגת גרסת CLI המותקנת. | — | +| `fp help` | הצגת עזרה לפקודה בדרגה העליונה. | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,24 +57,24 @@ fp whoami fp events [OPTIONS] ``` -מפרט אירועי agent בודדים. ה-feed הקל כברירת מחדל אינו כולל payloads גולמיים; השתמש ב-`--full` רק עבור חקירה מוגבלת. +רשימת אירועי agent בודדים. ההזנה הקלה ברירת המחדל אינה כוללת payload גולם; השתמש ב-`--full` רק לחקירה מוגבלת. -| אפשרות | תיאור | +| Option | Description | | --- | --- | -| `--limit`, `-n ` | מקסימום שורות כוללות. ברירת מחדל: `50`. | +| `--limit`, `-n ` | מרבי שורות כוללות. ברירת מחדל: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, או `7d`. | -| `--from ` / `--to ` | טווח ISO 8601 UTC; מחליף את `--since`. | +| `--from ` / `--to ` | טווח ISO 8601 UTC; דורס את `--since`. | | `--env ` | מסנן סביבה; חזור או הפרד בפסיקים. | -| `--event-type ` | מסנן event-type; חזור או הפרד בפסיקים. | +| `--event-type ` | מסנן סוג אירוע; חזור או הפרד בפסיקים. | | `--agent-id ` | מסנן agent; חזור או הפרד בפסיקים. | | `--session-id ` | מסנן session; חזור או הפרד בפסיקים. | -| `--search ` | חיפוש טקסט payload; חוזר, כאשר כל מונח תואם. | +| `--search ` | חיפוש טקסט payload; חוזר, כל מונח תואם. | | `--order asc\|desc` | סדר זמן. ברירת מחדל: החדש ביותר תחילה. | -| `--all` | עמוד אוטומטי עד `--limit`. | -| `--cursor ` | חזור מ-cursor בעלום. | -| `--page-size ` | שורות לכל בקשה עם `--all`; מקסימום `200`. | -| `--full` | כלול payloads גולמיים דרך נקודת end of events כבדה יותר. | -| `--fields ` | החזר רק שדות נבחרים; בקשת `payload` מפעילה מצב מלא. | +| `--all` | עימוד אוטומטי עד `--limit`. | +| `--cursor ` | חידוש מ-cursor אטום. | +| `--page-size ` | שורות לבקשה עם `--all`; מרבי `200`. | +| `--full` | כלול payload גולם דרך נקודת הקצה של אירוע כבדה יותר. | +| `--fields ` | החזר רק שדות נבחרים; בקשת `payload` מאפשרת מצב מלא. | ```bash fp events --session-id --order asc --all --limit 10000 @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` עומד בעמוד **עד `--limit`**, שברירת מחדל היא **50** — כך ש-`--all` בעצמו עוצר ב-50 שורות. כאשר הוא עוצר מוקדם, התגובה נושאת `next_cursor` כדי לחזור ממנו; `"next_cursor": null` פירושו ש-feed באמת הסתיים. + `--all` פוגן **עד `--limit`**, שברירת המחדל היא **50** — אז `--all` לבדו מעצור ב-50 שורות. כאשר הוא מעצור מוקדם התגובה נושאת `next_cursor` לחידוש מעמדה; `"next_cursor": null` פירושו שההזנה באמת הייתה מחוקה. ### Sessions @@ -91,21 +91,21 @@ fp --json events --full --session-id --all --limit 10000 fp sessions [OPTIONS] ``` -| אפשרות | תיאור | +| Option | Description | | --- | --- | -| `--limit`, `-n ` | מקסימום שורות כוללות. ברירת מחדל: `50`. | +| `--limit`, `-n ` | מרבי שורות כוללות. ברירת מחדל: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, או `7d`. | -| `--from ` / `--to ` | טווח ISO 8601 UTC; מחליף את `--since`. | +| `--from ` / `--to ` | טווח ISO 8601 UTC; דורס את `--since`. | | `--env ` | מסנן סביבה; חזור או הפרד בפסיקים. | | `--status ` | `done`, `error`, או `timeout`; חזור או הפרד בפסיקים. | -| `--agent-id ` | התאם sessions הכרוכות בכל agent נבחר. | +| `--agent-id ` | התאמת sessions הכוללות כל agent נבחר. | | `--session-id ` | מסנן session; חזור או הפרד בפסיקים. | -| `--all` | עמוד אוטומטי עד `--limit`. | -| `--cursor ` | חזור מ-cursor בעלום. | -| `--page-size ` | שורות לכל בקשה עם `--all`; מקסימום `200`. | +| `--all` | עימוד אוטומטי עד `--limit`. | +| `--cursor ` | חידוש מ-cursor אטום. | +| `--page-size ` | שורות לבקשה עם `--all`; מרבי `200`. | | `--fields ` | החזר רק שדות נבחרים. | | `--full-ids` | אל תקצר session IDs בפלט טרמינל. | -| `--agents` | הרחב את רשימת ה-agent עבור multi-agent sessions. | +| `--agents` | הרחב רשימת agent עבור sessions מרובי-agent. | ### Evaluations @@ -113,17 +113,17 @@ fp sessions [OPTIONS] fp evals [OPTIONS] ``` -| אפשרות | תיאור | +| Option | Description | | --- | --- | -| `--aggregate` | הצג סך הכל ודוחות סטטיסטיקה per-score במקום evaluations בודדות. | -| `--limit`, `-n ` | מקסימום שורות ברשימה. ברירת מחדל: `50`. | -| `--since`, `--from`, `--to` | בחר את טווח הזמן. | -| `--env`, `--status`, `--agent-id`, `--session-id` | הצר לערך אחד מדויק לכל מסנן. | -| `--score KEY:MIN..MAX` | טווח score; חוזר וכל הטווחים חייבים להתאים. | -| `--all`, `--cursor`, `--page-size` | שלוט בעמוד הרשימה. | +| `--aggregate` | הצגת סכומים וסטטיסטיקות לכל ניקוד במקום הערכות בודדות. | +| `--limit`, `-n ` | מרבי שורות רשימה. ברירת מחדל: `50`. | +| `--since`, `--from`, `--to` | בחירת טווח הזמן. | +| `--env`, `--status`, `--agent-id`, `--session-id` | הצמצום לערך מדויק אחד לכל מסנן. | +| `--score KEY:MIN..MAX` | טווח ניקוד; חוזר וכל הטווחים חייבים להתאים. | +| `--all`, `--cursor`, `--page-size` | שליטה בעימוד רשימה. | | `--fields ` | החזר רק שדות נבחרים. | -| `--full-ids` | הצג session IDs מלאים. | -| `--scores-full` | הצג כל score בפלט טרמינל. | +| `--full-ids` | הצגת session IDs שלמים. | +| `--scores-full` | הצגת כל ניקוד בפלט טרמינל. | ### Errors @@ -131,122 +131,122 @@ fp evals [OPTIONS] fp errors [OPTIONS] ``` -| אפשרות | תיאור | +| Option | Description | | --- | --- | -| `--aggregate` | סיכום errors תואמים במקום רשימת שורות. | -| `--limit`, `-n ` | מקסימום שורות ברשימה. ברירת מחדל: `50`. | -| `--since`, `--from`, `--to` | בחר את טווח הזמן. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | צמצם את אוכלוסיית ה-error. | +| `--aggregate` | סיכום שגיאות תואמות במקום רישום שורות. | +| `--limit`, `-n ` | מרבי שורות רשימה. ברירת מחדל: `50`. | +| `--since`, `--from`, `--to` | בחירת טווח הזמן. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | הצמצום של אוכלוסיית השגיאות. | | `--search ` | חיפוש טקסט payload; חוזר. | | `--order asc\|desc` | סדר זמן. | -| `--all`, `--cursor`, `--page-size` | שלוט בעמוד הרשימה. | +| `--all`, `--cursor`, `--page-size` | שליטה בעימוד רשימה. | | `--fields ` | החזר רק שדות נבחרים. | -| `--full-ids` | הצג session IDs מלאים. | +| `--full-ids` | הצגת session IDs שלמים. | -### Usage וערכי מסנן +### שימוש וערכי מסננים -| פקודה | תכלית | +| Command | Purpose | | --- | --- | -| `fp usage` | הצג usage עבור חלון ה-metering הנוכחי. | -| `fp list envs` | רשום סביבות שנצפו. | -| `fp list agents` | רשום agent IDs שנצפו. | -| `fp list event_types` | רשום event types. | -| `fp list score_filters` | רשום evaluation score keys. | -| `fp list models` | רשום שמות מודלים. | -| `fp list hooks` | רשום שמות hooks. | -| `fp list tools` | רשום שמות tools. | -| `fp list error_types` | רשום error types. | +| `fp usage` | הצגת שימוש לחלון המדידה הנוכחי. | +| `fp list envs` | רשימת סביבות שנצפו. | +| `fp list agents` | רשימת agent IDs שנצפו. | +| `fp list event_types` | רשימת סוגי אירוע. | +| `fp list score_filters` | רשימת מפתחות ניקוד הערכה. | +| `fp list models` | רשימת שמות מודלים. | +| `fp list hooks` | רשימת שמות hook. | +| `fp list tools` | רשימת שמות כלים. | +| `fp list error_types` | רשימת סוגי שגיאה. | ### Organizations -| פקודה | תכלית | +| Command | Purpose | | --- | --- | -| `fp orgs list` | רשום ארגונים נגישים. | -| `fp orgs switch [SLUG]` | שמור ארגון פעיל; הנח כאשר מושמט. | -| `fp orgs current` | הצג את הארגון הפעיל. | -| `fp orgs perms` | הצג את ההרשאות שלך בארגון הפעיל. | +| `fp orgs list` | רשימת ארגונים נגישים. | +| `fp orgs switch [SLUG]` | שמירת ארגון פעיל; מהות כשהוא מושמט. | +| `fp orgs current` | הצגת הארגון הפעיל. | +| `fp orgs perms` | הצגת ההרשאות שלך בארגון הפעיל. | ### API keys -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp keys list` | רשום מפתחות ארגון. | `--show-id`; `--fields ` | -| `fp keys show NAME` | הצג מפתח אחד והוא grants. | — | -| `fp keys create NAME` | צור מפתח וחשוף את ה-secret שלו פעם אחת. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | החלף את permission set או התאם grants. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | סובב את ה-secret וחשוף את ההחלפה פעם אחת. | `--yes`, `-y` | -| `fp keys disable NAME` | בטל לצמיתות מפתח. | `--yes`, `-y` | +| `fp keys list` | רשימת מפתחות ארגון. | `--show-id`; `--fields ` | +| `fp keys show NAME` | הצגת מפתח אחד והנחות שלו. | — | +| `fp keys create NAME` | יצירת מפתח וחשיפת הסוד שלו פעם אחת. | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | החלפת קבוצת ההרשאות או התאמת הנחות. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | סיבוב הסוד וחשיפת התחליף פעם אחת. | `--yes`, `-y` | +| `fp keys disable NAME` | שחרור קבוע של מפתח. | `--yes`, `-y` | -Permission tokens משתמשים ב-`resource:action`, כגון `events:add`. חזור על `--add`, הפרד בפסיקים tokens, או השתמש בפעולות עם נקודות כגון `events:read.add`. +token הרשאות משתמשים ב-`resource:action`, כגון `events:add`. חזור על `--add`, הפרד בפסיקים token, או השתמש בפעולות מנוקדות כגון `events:read.add`. ### Queries -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp query list` | רשום שאילתות שמורות. | `--show-id`; `--fields ` | -| `fp query show NAME` | הצג שאילתה אחת. | — | -| `fp query create NAME` | שמור שאילתה. | `--sql `; `--description` | -| `fp query update NAME` | עדכן או שנה שם של שאילתה. | `--name`; `--sql`; `--description`; `--yes`, `-y` | -| `fp query delete NAME` | מחק שאילתה שמורה. | `--yes`, `-y` | -| `fp query run [NAME]` | הרץ שאילתה שמורה או SQL ad-hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | רשום tables שאפשר לשאול עליהם או בדוק אחד. | — | +| `fp query list` | רשימת שאילתות שמורות. | `--show-id`; `--fields ` | +| `fp query show NAME` | הצגת שאילתה אחת. | — | +| `fp query create NAME` | שמירת שאילתה. | `--sql `; `--description` | +| `fp query update NAME` | עדכון או שינוי שם של שאילתה. | `--name`; `--sql`; `--description`; `--yes`, `-y` | +| `fp query delete NAME` | מחיקת שאילתה שמורה. | `--yes`, `-y` | +| `fp query run [NAME]` | הרצת שאילתה שמורה או SQL ad-hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query schema [TABLE]` | רשימת טבלאות שניתן לשאול או בדיקה של טבלה אחת. | — | ### Users -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp users list` | רשום חברי ארגון. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | הצג חבר ו-grants שלו. | — | -| `fp users create EMAIL` | הוסף חבר. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | שנה grants של חבר. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp users disable EMAIL` | בטל כניסה. | `--yes`, `-y` | -| `fp users enable EMAIL` | הפעל מחדש כניסה. | `--yes`, `-y` | +| `fp users list` | רשימת חברי ארגון. | `--active-only`; `--show-id` | +| `fp users show EMAIL` | הצגת חברי ונחות שלו. | — | +| `fp users create EMAIL` | הוספת חברי. | `--permission-set`; `--add`; `--remove` | +| `fp users update EMAIL` | שינוי נחות של חברי. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users disable EMAIL` | השבתת כניסה. | `--yes`, `-y` | +| `fp users enable EMAIL` | הפעלה מחדש של כניסה. | `--yes`, `-y` | ### Settings -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp settings list` | רשום הגדרות ארגון וערכים נוכחיים. | — | -| `fp settings schema` | הצג ערכים מקובלים ותיאורים. | — | -| `fp settings set KEY` | שנה הגדרה קיימת. | בדיוק אחד מ-`--value`, `--json-value`, `--file`; optional `--yes`, `-y` | +| `fp settings list` | רשימת הגדרות ארגון וערכים נוכחיים. | — | +| `fp settings schema` | הצגת ערכים מקובלים ותיאורים. | — | +| `fp settings set KEY` | שינוי הגדרה קיימת. | בדיוק אחד מ-`--value`, `--json-value`, `--file`; אופציונלי `--yes`, `-y` | ### Alerts -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp alerts list` | רשום כללי התראה. | `--show-id` | -| `fp alerts show NAME` | הצג התראה אחת. | — | -| `fp alerts create NAME` | צור התראה. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | עדכן או שנה שם של התראה. | אפשרויות create בתוספת `--name`; `--yes`, `-y` | -| `fp alerts delete NAME` | מחק התראה. | `--yes`, `-y` | +| `fp alerts list` | רשימת כללי התראה. | `--show-id` | +| `fp alerts show NAME` | הצגת התראה אחת. | — | +| `fp alerts create NAME` | יצירת התראה. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | +| `fp alerts update NAME` | עדכון או שינוי שם של התראה. | אפשרויות יצירה בתוספת `--name`; `--yes`, `-y` | +| `fp alerts delete NAME` | מחיקת התראה. | `--yes`, `-y` | | `fp alerts test NAME` | שלח הודעה בדיקה. | `--channels`; `--yes`, `-y` | -חומרות התראה הן `info`, `warning`, ו-`critical`. סוגי triggers הם `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound`, ו-`per_event`. מרווחי evaluation חייבים להיות בין 30 ל-86,400 שניות. +חומרות התראה הן `info`, `warning`, ו-`critical`. סוגי trigger הם `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound`, ו-`per_event`. מרווחי הערכה חייבים להיות בין 30 ל-86,400 שניות. ### Audits -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp audits list` | רשום ביקורות. | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | הצג הגדרת ביקורת אחת וחוקה. | — | -| `fp audits create NAME` | צור ביקורת וקבע מיד את ההפעלה הראשונה שלה. | ראה [אפשרויות create](#audit-create-options). | -| `fp audits edit NAME` | החלף הגדרות ביקורת תוך שמירה על ערכים לא מוגדרים. | אפשרויות הגדרת create; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | מחק ביקורת, ממצאים שלה, והיסטוריית הפעלה. | `--yes`, `-y` | -| `fp audits run NAME` | קבע הפעלה ידנית. | — | -| `fp audits runs NAME` | רשום היסטוריית הפעלה. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | הצג את ה-brief וחוקת הבקשה של ה-URL ההתייחסות. | — | -| `fp audits context-set NAME` | שנה את ה-brief או URL התייחסות. | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | בקש מחדש את URL התייחסות. | — | -| `fp audits findings` | רשום ממצאים. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | הצג ממצא אחד והראיות שלו. | — | -| `fp audits ack FINDING_ID` | הכר בממצא. | `--reason` | -| `fp audits mute FINDING_ID` | דכא דפוס חוזר. | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | סמן דפוס כלא פעול וגדור אותו. | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | סמן ממצא כתוקן ללא דיכוי עתידי. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | החזר ממצא לתור החי וגדור דיכוי. | — | -| `fp audits assign FINDING_ID` | קבע בעל ממצא. | דרוש `--to ` | - -#### אפשרויות create של Audit +| `fp audits list` | רשימת ביקורות. | `--enabled-only`; `--show-id` | +| `fp audits show NAME` | הצגת הגדרת ביקורת אחת ומצב. | — | +| `fp audits create NAME` | יצירת ביקורת וערבוב הריצה הראשונה שלה מיד. | ראה [אפשרויות יצירה](#audit-create-options). | +| `fp audits edit NAME` | החלפת הגדרות ביקורת תוך שמירה על ערכים לא מוגדרים. | אפשרויות הגדרת יצירה; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | מחיקת ביקורת, ממצאים שלו והיסטוריית ריצה. | `--yes`, `-y` | +| `fp audits run NAME` | ערבוב ריצה ידנית. | — | +| `fp audits runs NAME` | רשימת היסטוריית ריצה. | `--limit`, `-n`; `--show-id` | +| `fp audits context-show NAME` | הצגת מצב ההיקף וה-URL Reference fetch. | — | +| `fp audits context-set NAME` | שינוי התיאור או Reference URLs. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-refresh NAME` | הזנת Reference URLs מחדש. | — | +| `fp audits findings` | רשימת ממצאים. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | +| `fp audits finding FINDING_ID` | הצגת ממצא אחד והראיה שלו. | — | +| `fp audits ack FINDING_ID` | הכרה בממצא. | `--reason` | +| `fp audits mute FINDING_ID` | ספיגת תבנית חוזרת. | `--reason`; `--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | סימון תבנית לא מעשית וספיגתה. | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | סימון ממצא תיקון ללא ספיגה עתידית. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | החזרת ממצא לתור החי וניקוי הספיגה. | — | +| `fp audits assign FINDING_ID` | הגדרת בעל ממצא. | דרוש `--to ` | + +#### Audit create options ```bash fp audits create checkout-reliability \ @@ -259,122 +259,122 @@ fp audits create checkout-reliability \ --url https://runbooks.example.com/checkout ``` -| אפשרות | תיאור | +| Option | Description | | --- | --- | -| `--file ` | בסס את ההגדרה על JSON, או השתמש ב-`-` עבור stdin. דגלים מפורשים דורסים ערכי קובץ. | -| `--description ` | ציין את שאלת הכישלון או המטרה. | -| `--enabled` / `--disabled` | התחל תזמון על או כבוי. ברירת מחדל: מאופשר. | +| `--file ` | בסיס ההגדרה על JSON, או השתמש ב-`-` עבור stdin. דגלים מפורשים דורסים ערכי קובץ. | +| `--description ` | מדינת שאלת כישלון או מטרה. | +| `--enabled` / `--disabled` | תחילת תזמון מופעל או כבוי. ברירת מחדל: מופעל. | | `--schedule-interval-secs ` | `3600`–`604800`. ברירת מחדל: `86400`. | -| `--schedule-anchor ` | שלב UTC קבוע בצורת ISO 8601. ברירת מחדל: הבא 09:00 UTC. | -| `--window-mode since_last\|fixed` | המשך אחרי החלון האחרון שנותחה לחלוטין או בדוק שוב חלון גלגול. ברירת מחדל: `since_last`. | +| `--schedule-anchor ` | שלב UTC קבוע בצורה ISO 8601. ברירת מחדל: 09:00 UTC הבא. | +| `--window-mode since_last\|fixed` | המשך לאחר החלון שנותח לאחרונה או בדיקה חוזרת של חלון מתגלגל. ברירת מחדל: `since_last`. | | `--lookback-window-secs ` | `3600`–`7776000`. ברירת מחדל: `604800`. | -| `--scope ''` | סנן לפי `environments`, `agent_ids`, או שדות scope אחרים. | -| `--ignore-error-type ` | אל תכלול error types; חזור או הפרד בפסיקים. | -| `--llm` / `--no-llm` | הפעל או בטל ניתוח agentic. ברירת מחדל: מאופשר. | +| `--scope ''` | סנן לפי `environments`, `agent_ids`, או שדות scope נתמכים אחרים. | +| `--ignore-error-type ` | הסרת סוגי שגיאה; חזור או הפרד בפסיקים. | +| `--llm` / `--no-llm` | הפעלה או השבתה של ניתוח agentic. ברירת מחדל: מופעל. | | `--top-k ` | שמור `1`–`500` ממצאים. ברירת מחדל: `50`. | -| `--sensitivity low\|medium\|high` | קבע רגישות דיווח. ברירת מחדל: `medium`. | -| `--channels ''` | מערך ערוץ הודעה. | -| `--text ` | brief מוטבע, מקסימום 8,192 תווים. | -| `--text-file ` | קרא את ה-brief מקובץ; בלעדי הדדי עם `--text`. | -| `--url ` | הוסף התייחסות ציבורית HTTPS; חזור עד חמש פעמים. | +| `--sensitivity low\|medium\|high` | הגדרת רגישות דיווח. ברירת מחדל: `medium`. | +| `--channels ''` | מערך ערוץ התראה. | +| `--text ` | תיאור מובנה, מרבי 8,192 תווים. | +| `--text-file ` | קרא את התיאור מקובץ; הדדיות בלעדית עם `--text`. | +| `--url ` | הוספת reference ציבורי HTTPS; חזור עד חמש פעמים. | -כלול context במהלך יצירה כאשר ההפעלה הראשונה זקוקה לו. יצירה מחייבת את ההגדרה ו-context ביחד לפני שההפעלה הקבועה מתחילה. +כלול הקשר במהלך יצירה כאשר הריצה הראשונה זקוקה לה. יצירה מחייבת את ההגדרה וההקשר ביחד לפני תחילת הריצה בתור. - `fp audits run` אינו סינכרוני. עמוד על `fp audits runs NAME` עד שההפעלה הסופית מצליחה או נכשלת לפני קריאת ממצאים שלה. + `fp audits run` אסינכרוני. סקור `fp audits runs NAME` עד שהריצה האחרונה מצליחה או נכשלת לפני קריאת הממצאים שלה. ### Issues -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp issues list` | רשום בעיות. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | ספור פתוח או בעיות מצבים נבחרים. | `--state` | -| `fp issues show INCIDENT_ID` | הצג פרטי בעיה, הערות, מנויים, ופעילות. | — | -| `fp issues open` | פתח בעיה ידנית או קשורה להתראה. | דרוש `--summary`; optional `--title`, `--alert-id`, `--severity` | -| `fp issues ack INCIDENT_ID` | הכר בבעיה. | — | -| `fp issues assign INCIDENT_ID` | החלף assignees; השמט את האפשרות כדי להסיר אותם. | חוזר `--assignee` | -| `fp issues resolve INCIDENT_ID` | פתור בעיה. | `--yes`, `-y` | -| `fp issues comment-list INCIDENT_ID` | רשום הערות. | — | +| `fp issues list` | רשימת בעיות. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | ספירת בעיות פתוחות או מדינות בעיות נבחרות. | `--state` | +| `fp issues show INCIDENT_ID` | הצגת פרטי בעיה, הערות, מנויים ופעילות. | — | +| `fp issues open` | פתיחת בעיה ידנית או קשורה להתראה. | דרוש `--summary`; אופציונלי `--title`, `--alert-id`, `--severity` | +| `fp issues ack INCIDENT_ID` | הכרה בבעיה. | — | +| `fp issues assign INCIDENT_ID` | החלפת מוקצים; הוציא את האפשרות לנקות אותם. | חוזר `--assignee` | +| `fp issues resolve INCIDENT_ID` | פתרון בעיה. | `--yes`, `-y` | +| `fp issues comment-list INCIDENT_ID` | רשימת הערות. | — | | `fp issues comment-add INCIDENT_ID` | הוסף הערה. | בדיוק אחד מ-`--body`, `--file` | -| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | מחק הערה. | `--yes`, `-y` | -| `fp issues subscribers INCIDENT_ID` | רשום מנויים. | — | -| `fp issues subscribe INCIDENT_ID` | הירשם בעצמך או למפעיל אחר. | `--email` | -| `fp issues unsubscribe INCIDENT_ID` | הסר מנוי. | `--email` | +| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | מחיקת הערה. | `--yes`, `-y` | +| `fp issues subscribers INCIDENT_ID` | רשימת מנויים. | — | +| `fp issues subscribe INCIDENT_ID` | הרשמה לעצמך או למפעיל אחר. | `--email` | +| `fp issues unsubscribe INCIDENT_ID` | הסרת הרשמה. | `--email` | -מצבי בעיה תקפים הם `firing`, `acknowledged`, ו-`resolved`. חומרות בעיות עצמאיות הן `info`, `warning`, ו-`critical`. +מצבי בעיה תקפים הם `firing`, `acknowledged`, ו-`resolved`. חומרות בעיה עצמאיות הן `info`, `warning`, ו-`critical`. ### Cloud assistant -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp agent health` | בדוק זמינות עוזר וקונפיגורציה. | — | -| `fp agent models` | רשום מודלי עוזר זמינים. | — | -| `fp agent chats` | רשום שיחות שמורות. | — | -| `fp agent ask [MESSAGE]` | התחל או המשך שיחה; קרא stdin כאשר ההודעה מושמטת. | `--chat`; `--model`; `--page-context` | -| `fp agent show CHAT_ID` | הצג שיחה שמורה. | — | -| `fp agent rename CHAT_ID` | שנה שם שיחה. | דרוש `--title` | -| `fp agent delete CHAT_ID` | מחק שיחה. | `--yes`, `-y` | +| `fp agent health` | בדיקת זמינות assistant והגדרה. | — | +| `fp agent models` | רשימת מודלים assistant זמינים. | — | +| `fp agent chats` | רשימת צ'אטים שמורים. | — | +| `fp agent ask [MESSAGE]` | התחלה או המשך של צ'אט; קריאת stdin כאשר ההודעה הוא מושמט. | `--chat`; `--model`; `--page-context` | +| `fp agent show CHAT_ID` | הצגת שיחה שמורה. | — | +| `fp agent rename CHAT_ID` | שינוי שם של שיחה. | דרוש `--title` | +| `fp agent delete CHAT_ID` | מחיקת שיחה. | `--yes`, `-y` | ### Policies -גרסאות מדיניות המנוהלות בענן. **Session-only** — כל פקודה כאן יוצאת עם `2` תחת API key, לפני כל בקשה, כי אלה הן root-only write routes בכוונה חסרות מ-`/v1`. +גרסות מדיניות מנוהלות ב-Cloud. **Session-only** — כל פקודה כאן יוצא `2` תחת מפתח API, לפני כל בקשה, כי אלה הן routes כתיבה root-only בכוונה לא קיים ב-`/v1`. -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp policies list` | רשום גרסאות מדיניות. | `--json` | -| `fp policies show POLICY_ID` | הצג מדיניות אחת, עם מקורה. | — | -| `fp policies publish NAME PATH` | טבעת גרסה מ-`.mjs` מקומי. | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | הוסף אותה בחזרה לכל פריסה שהוסרה ממנה, טיבעת דור חדש בכל אחת. | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | הסר אותה מכל פריסה שנושאת אותה, טיבעת דור חדש בכל אחת. | `--yes`, `-y` | -| `fp policies delete POLICY_ID` | מחק גרסת מדיניות. | `--yes`, `-y` | -| `fp policies test PATH` | הרץ מדיניות באופן מקומי כנגד context סינתטי. מחיל את מסנן ה-`match` של כל מדיניות, כך שאחת שלא מכסה את האירוע/tool הנתון מדווחת `skipped` במקום הריצה. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | טיוטה מדיניות עם העוזר. דרוש `policies:write`. | — | +| `fp policies list` | רשימת גרסות מדיניות. | `--json` | +| `fp policies show POLICY_ID` | הצגת מדיניות אחת, עם המקור שלה. | — | +| `fp policies publish NAME PATH` | הנפקת גרסה מ-`.mjs` מקומי. | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | הוסף אותה בחזרה לכל פריסה שהוא הוסר ממנה, הנפקת דור חדש בכל אחד. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | הסר אותה מכל פריסה שנושאת אותה, הנפקת דור חדש בכל אחד. | `--yes`, `-y` | +| `fp policies delete POLICY_ID` | מחיקת גרסת מדיניות. | `--yes`, `-y` | +| `fp policies test PATH` | הרצת מדיניות מקומית מול הקשר סינתטי. חל כל מסנן `match` של המדיניות, אז אחד שלא מכסה את האירוע/הכלי הנתון מדווח `skipped` ולא הרץ. | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | טיוטת מדיניות עם ה-assistant. צורך `policies:write`. | — | ### Fleet -אילו מכונות מריצות אילו מדיניות. **Session-only**, אותו סיבה כמו לעיל. +אילו מכונות מריצות אילו מדיניות. **Session-only**, אותו סיבה כמו לעיל. -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp fleet list` | רשום מכונות רשומות וגנרציית פריסה שלהן. | — | -| `fp fleet show MACHINE_ID` | מערך המדיניות שמכונה מריצה כעת. | — | -| `fp fleet deploy MACHINE_ID` | **מחליף את כל מערך המדיניות של המכונה.** הדפס את התוכנית וישאל רק בטרמינל אינטראקטיבי ללא `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | השווה מכונה לפריסה אחרת. | — | -| `fp fleet history MACHINE_ID` | פריסות קודמות עבור מכונה. | — | -| `fp fleet rollback MACHINE_ID` | שחזר פריסה קודמת. | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | תן לקבל שם קריא למכונה. | דרוש `--name` | +| `fp fleet list` | רשימת מכונות רשומות ודור פריסה שלהן. | — | +| `fp fleet show MACHINE_ID` | מערך מדיניות שמכונה מריצה כרגע. | — | +| `fp fleet deploy MACHINE_ID` | **החלפת כל מערך מדיניות של מכונה.** הדפס את התוכנית ושאל רק בטרמינל אינטראקטיבי ללא `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | השוואת מכונה לפריסה אחרת. | — | +| `fp fleet history MACHINE_ID` | פריסות קודמות למכונה. | — | +| `fp fleet rollback MACHINE_ID GENERATION` | הנחת דור קודם מערך מדיניות, כדור חדש. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | תן שם קריא למכונה. | דרוש `--name` | ### Guardrails -מה אכיפה באמת עשתה. **Session-only**, אותו סיבה כמו לעיל. +מה כפיית ממש עשתה. **Session-only**, אותו סיבה כמו לעיל. -| פקודה | תכלית | אפשרויות | +| Command | Purpose | Options | | --- | --- | --- | -| `fp guardrails summary` | כיסוי, חסום/הערך סכומים, sparkline deny, וטבלת per-policy. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | החלטות דלי על החלון, מסוכמות על פני כל מקור מדיניות. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | כיסוי, חסומות/מוערכות סכומות, ניצוץ deny, וטבלת per-policy. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | החלטות מכניות על החלון, סיכמו על כל מקור מדיניות. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -## דגלים globales +## דגלים גלובליים -| דגל | תיאור | +| Flag | Description | | --- | --- | -| `--json` | פלוט JSON קריא למכונה. | -| `--base-url ` | השתמש בדוח מתארח בעצמי או פיתוח. | +| `--json` | פלט JSON קריא למכונה. | +| `--base-url ` | השתמש בדashboard שמעוכב או פיתוח. | | `--org ` | בחר ארגון להפעלה זו. | -| `--token ` | דרוס token user-session השמור. | -| `--api-key ` | הנפק אוטומציה עם API key; לעולם לא שמור. | -| `--timeout ` | HTTP timeout; חייב להיות חיובי. ברירת מחדל: `30`. | -| `--quiet`, `-q` | דכא פלט סטטוס על stderr. | -| `--no-color` | בטל פלט צבוע. | -| `--insecure` / `--secure` | בטל או שחזר אימות תעודת TLS. | -| `--version` | הדפס את הגרסה והחץ. | -| `--help`, `-h` | הצג עזרה. | +| `--token ` | דרוס את token session המשתמש השמור. | +| `--api-key ` | הוסכם אוטומציה עם מפתח API; לעולם לא נשמר. | +| `--timeout ` | timeout HTTP; חייב להיות חיובי. ברירת מחדל: `30`. | +| `--quiet`, `-q` | דיכוי פלט סטטוס על stderr. | +| `--no-color` | השבתה של פלט צבעוני. | +| `--insecure` / `--secure` | השבתה או שחזור של אימות תעודה TLS. | +| `--version` | הדפס את הגרסה ופרוק והצא. | +| `--help`, `-h` | הצגת עזרה. | -`--api-key` מיועד לאוטומציה. Login, החלפת ארגון, ופקודות עוזר דורשות user session. +`--api-key` מיועד לאוטומציה. כניסה, החלפת ארגון, ופקודות assistant דורשות session משתמש. ## משתנים סביבה -| משתנה | שקול או תכלית | +| Variable | Equivalent or purpose | | --- | --- | | `FP_DASHBOARD_URL` | `--base-url` | | `FP_ORG` | `--org` | @@ -382,18 +382,18 @@ fp audits create checkout-reliability \ | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | הגר את ספריית קונפיגורציית CLI (ברירת מחדל `~/.failproofai/fpcli`). | -| `FP_ANALYTICS_DISABLED` או `DO_NOT_TRACK` | בטל ניתוח CLI אנונימי. | -| `NO_COLOR` | בטל פלט צבוע. | +| `FP_HOME` | עקירת ספריית תצורת CLI (ברירת מחדל `~/.failproofai/fpcli`). | +| `FP_ANALYTICS_DISABLED` או `DO_NOT_TRACK` | השבתה של אנליטיקה CLI אנונימית. | +| `NO_COLOR` | השבתה של פלט צבעוני. | -דגלים מפורשים דורסים משתנים סביבה, אשר דורסים את הקונפיגורציה השמורה. במצב API-key, בחר את ה-tenant בצורה מפורשת עם `--org` או `FP_ORG`. +דגלים מפורשים דורסים משתנים סביבה, שדורסים תצורה שמורה. במצב מפתח API, בחר את הדייר בצורה מפורשת עם `--org` או `FP_ORG`. - האיות `AGENTEYE_*` של אלה הם **לא נקרא על ידי `fp`** ואף פעם לא היו — ה-CLI מצהיר `FP_*` (`fp_cli/app.py`), ומשתנה לא ידוע אינו שגיאה. הגדרת `AGENTEYE_DASHBOARD_URL` לא משנה את היעד של ה-CLI; היא מתעלמת והפקודה שקט רצה כנגד הדוח השמור במקום זאת. + ה-AGENTEYE_* הנקודות של אלה הן **לא נקרא על ידי `fp`** ולעולם לא היו — ה-CLI מצהיר `FP_*` (`fp_cli/app.py`), ומשתנה לא ידוע אינו שגיאה. הגדרת `AGENTEYE_DASHBOARD_URL` לא מטרה מחדש את ה-CLI; הוא מתעלם ופקודה בשקט פעלה נגד הדashboard השמור במקום זאת. - `AGENTEYE_HOME` ו-`AGENTEYE_ENVIRONMENT` עדיין קיימים, אך הם שייכים ל-**collector וטלמטריית SDK**, לא ל-CLI זה. + `AGENTEYE_HOME` ו-`AGENTEYE_ENVIRONMENT` עדיין קיימים, אך הם משתייכים ל-**collector וה-telemetry SDK**, לא ל-CLI זה. - פקודות שמוחקות, מבטלות, דוכאות, פותרות, או מחליפות קונפיגורציה מנומנות כברירת מחדל. השתמש ב-`--yes` רק לאחר אימות ארגון פעיל ויעד. + פקודות המחיקות, רוקות, מדכאות, פותרות, או מחליפות תצורה מהות כברירת מחדל. השתמש ב-`--yes` רק לאחר אימות הארגון הפעיל והיעד. \ No newline at end of file diff --git a/docs/he/reference/custom-agents.mdx b/docs/he/reference/custom-agents.mdx index d70fedf8..451f4675 100644 --- a/docs/he/reference/custom-agents.mdx +++ b/docs/he/reference/custom-agents.mdx @@ -1,17 +1,17 @@ --- title: "סוכנים מותאמים" -description: "הגדרות, קטלוג האירועים, כללי קורלציה והעברה עבור failproofai-sdk." +description: "תצורה, קטלוג אירועים, כללי קורלציה והסלקת עומס עבור failproofai-sdk." icon: "python" --- -מה עושה כל הגדרה, שיטה וערך. אם אתה מכשיר לראשונה, התחל בגיד — דף זה מיועד לחיפוש דברים. +מה שכל הגדרה, שיטה ושדה עושים. אם אתה מעצב למשימה על בסיס תחזוקה, התחל עם ההדרכה — דף זה למטרות חיפוש. - - התקנה, כשור, שיטות האירועים, דוגמה שעבדה, ובעיות נפוצות. + + התקנה, עיצוב, שיטות אירועים, דוגמה מעובדת, ובעיות נפוצות. - - LangChain, CrewAI, LlamaIndex ו-Pydantic AI משקרים את עצמם עם קריאה אחת. + + LangChain, CrewAI, LlamaIndex ו-Pydantic AI מעצבים את עצמם עם קריאה אחת. @@ -23,30 +23,36 @@ Python 3.10 או חדש יותר. ללא תלויות זמן ריצה. pip install failproofai-sdk ``` -החבילה מותקנת כ-`failproofai-sdk` וייבואה ב-Python כ-`failproofai_sdk`. extras של תשקיות כגון `failproofai-sdk[langgraph]` מתקינים את התשקית עצמה; המתאמים תמיד משלחים בגלגל הבסיס. +החבילה מותקנת כ-`failproofai-sdk` וייבוא ב-Python כ-`failproofai_sdk`. תוספות פריימוורק כגון `failproofai-sdk[langgraph]` מותקנות הן את הפריימוורק עצמו; המתאמים תמיד משלחים בגלגל בסיס. -## חבר את ה-failproofai daemon +## חברת את שדכן Failproof - - 1. עבור אל **Admin → Keys** וצור מפתח עם `events:add`. - 2. [חבר את ה-failproofai daemon לענן](/he/start/setup#connect-a-machine-to-cloud) במכונת הסוכן. - 3. הפעל הפעלה משוקללת אחת, ואז מצא את המזהה המדויק שלה תחת **Observe → Events**. - 4. עבור אל **Observe → Sessions**, בחר באותו סביבה, ופתח את העקבות המשוקללים. + + 1. עבור ל-**Admin → Keys** וצור מפתח עם `events:add`. + 2. [חבר את שדכן Failproof ל-Cloud](/he/start/setup#connect-a-machine-to-cloud) על מכונת הסוכן. + 3. הפעל הפעלה מעוצבת אחת, ואז מצא את המזהה המדויק שלה תחת **Observe → Events**. + 4. עבור ל-**Observe → Sessions**, בחר את אותה סביבה, ופתח את העקבה שנוצרה מחדש. - ![סשן סוכן Python מותאם משוקלל כגרף ביצוע ועקבות אירוע מסודרות.](/images/dashboard/session-detail.png) + ![הפעלה של סוכן Python מותאם שנבנתה מחדש כגרף ביצוע ועקבה מסודרת של אירועים.](/images/dashboard/session-detail.png) + קרא את מפתח `events:add` לתוך הקונכייה. `read -s` לוקח אותה בהודעה שלא משקפת, כך שהיא לעולם לא מופיעה בפקודה או בהסטוריית הקונכייה: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + לאחר מכן הגדר את המכונה וודא שהיא התחברה: + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` -## הגדרות +## תצורה ```python import failproofai_sdk @@ -58,32 +64,32 @@ failproofai_sdk.configure( ) ``` -| ארגומנט | מה זה עושה | +| טיעון | מה זה עושה | | --- | --- | -| `environment` | התווית בכל אירוע — `production`, `staging`, `prod-eu`. ברירת מחדל: `dev`. | -| `flush_interval` | כמה threds הרקע כותב לדיסק, בשניות. ברירת מחדל: `0.5`. | -| `base_dir` | היכן לכתוב. ברירת מחדל: ה-spool של ה-daemon, וזה מה שאתה רוצה אלא אם אתה יודע אחרת. | +| `environment` | התווית בכל אירוע — `production`, `staging`, `prod-eu`. ברירת מחדל ל-`dev`. | +| `flush_interval` | כמו קרובה הפוך לדיסק בשניות. ברירת מחדל ל-`0.5`. | +| `base_dir` | היכן לכתוב. ברירת מחדל לספול של השדכן, שזה מה שאתה רוצה אלא אם אתה יודע אחרת. | הגדר לפי משתנה סביבה במקום: | משתנה | מה זה עושה | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | מגדיר `environment` ללא שינוי קוד, עבור כשהתווית שייכת להפצה ולא לאפליקציה. ארגומנט `configure()` מנצח עליו. | -| `FAILPROOFAI_HOME` | מעביר את ה-Failproof AI root שמחזיק את ה-spool. | -| `FAILPROOFAI_SDK_STRICT` | `1` גורם לשגיאות כשור להעלות במקום להיות רשומות. | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` גורם לבעיית תאימות תשקית להעלות במקום להזהיר ולהמשיך. | +| `AGENTEYE_ENVIRONMENT` | מגדיר `environment` ללא שינוי קוד, כאשר התווית שייכת להפצה ולא לאפליקציה. טיעון `configure()` מנצח עליו. | +| `FAILPROOFAI_HOME` | מעביר את שורש Failproof AI המחזיק בספול. | +| `FAILPROOFAI_SDK_STRICT` | `1` גורם לשגיאות עיצוב להעלות במקום להיות מתועדות. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` גורם לבעיית תאימות פריימוורק להעלות במקום להזהיר ולהמשיך. | - **אין פסיקים ב-`environment`.** Ingest מפצל את השדה הזה על פסיקים כדי לבנות את המסננים שלו, והדלק כל אירוע שתווית שלו מכילה אחד — כך הריצה כולה נעלמת בשקט. כתוב `prod-eu`, לא `prod,eu`. + **ללא פסיקים ב-`environment`.** Ingest מפצל שדה זה על פסיקים כדי לבנות את הסינונים שלו, וקופץ כל אירוע שהתווית שלו מכילה אחד — כך שריצה שלמה נעלמת בשקט. כתוב `prod-eu`, לא `prod,eu`. - `configure(environment="prod,eu")` מעלה כדי שתגלה מיד. `AGENTEYE_ENVIRONMENT` לא יכול להעלות — שום דבר לא קורא לך — אז זה מזהיר פעם אחת וחוזר אל `dev`. + `configure(environment="prod,eu")` מעלה כך שתגלה מיד. `AGENTEYE_ENVIRONMENT` לא יכול להעלות — שום דבר לא קורא לך — כך שזה מזהיר פעם אחת וחוזר לברירת המחדל `dev`. -אירועים מתורבצים בזיכרון וכתובים ברקע כל `flush_interval` שניות, עם flush סופי ביציאת המפרש. תהליך שנהרג לחלוטין מאבד כל מה שעדיין לא נכתב. +אירועים מתורים בזיכרון וכתבו בתוך הרקע כל `flush_interval` שניות, עם שטיפה סופית ביציאת המתורגמן. תהליך שנהרג בגלוי מאבד כל מה שלא היה כתוב עדיין. ## זהות -כל אירוע שייך לסשן וסוכן. **ההיקפים מילאו את שניהם**, כך שאתה בעצם לא עובר אותם: +כל אירוע שייך לתוך הפעלה וסוכן. **ההיקפים ממלאים את שניהם**, כך שאתה רק לעתים קרובות עוברים אותם: ```python with failproofai_sdk.session(): @@ -91,30 +97,30 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -העברת `session_id` או `agent_id` במפורש עדיין עובדת ומנצחת. ללא קשור או עובר, הקריאה מעלה `TypeError` ולא פולטת אירוע שענן היה בשקט מהדיר. +עבור `session_id` או `agent_id` בגלוי עדיין עובד וניצחונות. לא כבול ולא עבר, הקריאה מעלה `TypeError` במקום לפעול אירוע Cloud היה שקט מוסר. - זהות רוכבת על משתנים בהקשר. זה עוקב אחר `asyncio` tasks באופן אוטומטי, אבל **לא** threads חדשים — עטוף עובד ב-`failproofai_sdk.propagate()` או האירועים שלו נוחתים לא מצורפים. + זהות נוסעת על משתני הקשר. היא עוקבת אחר `asyncio` משימות באופן אוטומטי, אך **לא** חוטים חדשים — עטוף עובד ב-`failproofai_sdk.propagate()` או האירועים שלו נחת לא מחובר. ## קטלוג אירועים -חמש עשרה שיטות. רובן בא ב-**זוגות** — אתה קורא לפותח, ואז לסוגר, ה-SDK מתזמן את הפער. +חמש עשרה שיטות. רובם באים בזוגות — אתה קורא את הפותח, ואז הסוגר, וה-SDK מעבור הפער. -| | פותח | סוגר | +| | פתוח | סגור | | --- | --- | --- | | **סוכנים** | `agent_start` | `agent_end` | | | `agent_pause` | `agent_resume` | | **מודלים** | `model_request` | `model_response` | | **כלים** | `tool_use` | `tool_result` | -| **hooks** | `hook_triggered` | `hook_completed` | -| **בני אדם** | `human_wait` | `human_input` | +| **חיבורים** | `hook_triggered` | `hook_completed` | +| **אנשים** | `human_wait` | `human_input` | -שלוש עומדות לבד: `error`, `human_pause`, `human_interrupt`. +שלושה עומדים לבד: `error`, `human_pause`, `human_interrupt`. - + -כל שיטה גם לוקחת `session_id` ו-`agent_id`, אותם ההיקפים מילאו בשבילך. כל דבר שנשאר כ-`None` מופסק ולא נשלח כ-JSON `null`, וכל שיטה מחזירה `None`. +כל שיטה גם לוקחת `session_id` ו-`agent_id`, אשר ההיקפים ממלאים בשבילך. כל דבר שנותר כ-`None` זורק ולא נשלח כ-JSON `null`, וכל שיטה מחזירה `None`. | שיטה | נדרש | אופציונלי | | --- | --- | --- | @@ -137,12 +143,12 @@ with failproofai_sdk.session(): - כדי לסמן ריצה כנכשלה, `outcome` חייב להיות אחד מ-`failed`, `error`, `timeout` או `rejected`. כל דבר אחר — כולל הקרוב-lfail `"failure"` — נחשב להצלחה. + כדי להסמן ריצה כנכשלת, `outcome` חייב להיות אחד מ-`failed`, `error`, `timeout` או `rejected`. כל דבר אחר — כולל כמעט הפספוס `"failure"` — נחשב להצלחה. ## זיווג ומשך -**כלל אחד: תן לאירוע הסגירה את אותו מזהה כמו לפותח שלו.** זה מה שמקשר אותם, וזה מה שמאפשר ל-SDK לתזמן את הפער. +**כלל אחד: תן לאירוע הסגירה את אותו מזהה כמו הפותח שלו.** זה מה זיווג אותם, ומה שמאפשר ל-SDK למדוד את הפער. | זוג | התאם על | | --- | --- | @@ -152,46 +158,46 @@ with failproofai_sdk.session(): | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**אל תעבור `duration_ms` בעצמך.** ה-SDK מודד אותו, והעברתו מעלה `ValueError`. +**אל תעבור `duration_ms` בעצמך.** ה-SDK מודד אותו, ועברתו מעלה `ValueError`. -החריג היחיד הוא `model_response`, כאשר רק אתה יודע את הזמן ההמתנה של הספק בפועל. עבור מספר שלם של אלפיות שניה — float מעלה, כי העמודה היא מספר שלם 32-bit ואחרת תנחת ריקה. +חריג אחד הוא `model_response`, שם רק אתה יודע את חביון הספק האמיתי. עבור מספר שלם של אלפיות שנייה — צף מעלה, כי העמודה היא מספר שלם של 32 סיביות וייכנס אחרת ריק. - + -- **מזהים רק צריכים להיות ייחודיים לכל סוג, לכל סשן.** כלי וגרפוסקופ יכול לשתף אחד; שני סשנים פועלים בו זמנית יכול להשתמש שוב באותם מזהים ללא התנגשות. -- **הם לא מחומקים לסוכן.** זוג שנפתח תחת סוכן אחד וסגור תחת אחר עדיין תואם — וזה המקרה הרגיל בקוד מולטי-סוכן. -- **`request_id` הוא אופציונלי אך מומלץ.** ללא זה, אירועי מודל מקבלים zipping בסדר ההגעה שלהם, כך ששתי קריאות במקביל באותו סוכן יכולות להימסוג. -- **זוג מחולק על פני תהליכים** עדיין תואם בענן, אבל ה-SDK לא יכול לתזמן אותו — כלום בשום תהליך ראה שני החציים. -- **לכל היותר 10,000 פותחים המתינו לסוגר בו זמנית.** בעבר זה החדש הישן מושמט, כך שדזילת לא יכולה לגדול ללא קשור. +- **מזהים רק צריכים להיות ייחודיים לפי סוג, לכל הפעלה.** קריאה כלים וחיבור יכולים לחלוק אחד; שתי הפעלות פעם בו זמנית יכולות לעשן מחדש את אותם מזהים ללא התנגשות. +- **הם לא מתוחמים לסוכן.** זוג פתוח תחת סוכן אחד וסגור תחת אחר עדיין תואם — שהיא התיק הרגיל בקוד מולטי-סוכן. +- **`request_id` אופציונלי אך מומלץ.** ללא זה, אירועי מודל מזווגים בסדר ההגעה, כך ששתי קריאות בו זמנית באותו סוכן יכולות שגויות זוג. +- **זוג מפוצל על פני תהליכים** עדיין תואם ב-Cloud, אך ה-SDK לא יכול למדוד את זה — שום דבר בשתי התהליכים ראה שתי החצאים. +- **לכל היותר 10,000 פותחים מחכים לסוגר בו זמנית.** פחות מזה הישן הישן זורק, כל דליפה לא יכול לגדול ללא גבול. -## שדות משלך +## השדות שלך שלך -כל extra keyword שאתה עובר מאוחסן עם האירוע: +כל טיעון נוסף שאתה עובר מאוחסן עם האירוע: ```python failproofai_sdk.event.tool_use( tool_name="search", tool_call_id="c1", - fw_tenant="acme", fw_region="eu-west-1", # שלך + fw_tenant="acme", fw_region="eu-west-1", # שלך שלך ) ``` -דבוק סוגי JSON אם אתה רוצה לשאול אותם מאוחר יותר. כל דבר אחר — UUID, datetime, `Decimal`, set, bytes, אובייקט מודל — מאוחסן כמחרוזת. +עדיף סוגי JSON אם אתה רוצה לשאול אותם מאוחר יותר. כל דבר אחר — UUID, datetime, `Decimal`, סט, bytes, אובייקט מודל — מאוחסן כמחרוזת. - **קדימה שמות שדה שלך.** Extras משמשים אחרונים, כך ששדה שנקרא `model`, `tool_name` או `outcome` בשקט משכתב את האמיתי. מתאמי התשקית משתמשים ב-`fw_`; עשה כך ותיקבול שום דבר. + **קידומת שם השדות שלך.** תוספות מיושמות אחרונות, כך ששדה הנקרא `model`, `tool_name` או `outcome` בשקט דורס את האמיתי. מתאמי הפריימוורק משתמשים ב-`fw_`; עשה את אותו הדבר ו-שום דבר לא יכול להתנגש. - זו גם הסיבה שדה optional mispenned לא אי פעם שגיאות — זה פשוט הופך לשדה custom חדש. אם שדה סטנדרטי חסר בענן, בדוק את הכתיב קודם. + זה גם למה שדה אופציונלי שגוי עלול לעולם לא טוען — זה רק הופך לשדה מותאם חדש. אם שדה תקן חסר ב-Cloud, בדוק את האיות בתחילה. -חמישה שמות אלה שמורים והדחקו לחלוטין: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. +חמש שמות אלה שמורים ודחויים בגלוי: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. -## העברה והאמתה +## משלוח ואימות - - ב-**Observe → Events**, אמת `agent_start` קיים קודם כל ו-`agent_end` קיים אחרון. ואז פתח **Observe → Sessions** והאשר כי מודל, כלי, אדם, hook, ואירועי שגיאה מופיעים בסדר המיועד. השתמש בזהות סשן כמפתח פתרון בעיות ראשוני. + + ב-**Observe → Events**, אימות `agent_start` קיים בתחילה ו-`agent_end` קיים אחרון. לאחר מכן פתח **Observe → Sessions** ובדוק שמודל, כלי, אדם, חיבור, ואירועי שגיאה מופיעים בסדר המיועד. השתמש במזהה ההפעלה כמפתח פתרון בעיות ראשוני. ```bash @@ -203,14 +209,14 @@ failproofai_sdk.event.tool_use( -אם ענן ריק, בדוק `$FAILPROOFAI_HOME/custom-agents/events`, אחרת `~/.failproofai/custom-agents/events`. קבצי JSONL להוכיח פליטה של SDK; spool גדל מצביע על daemon הגדרות או העברה, בעוד spool ריק מצביע על כשור או lifetime תהליך. +אם Cloud ריק, בדוק `$FAILPROOFAI_HOME/custom-agents/events`, אחרת `~/.failproofai/custom-agents/events`. קבצי JSONL מוכיחים פליטת SDK; ספול גדל מצביע על תצורת שדכן או משלוח, בעוד ספול ריק מצביע על עיצוב או משך תהליך. - בדוק את ה-spool רק כאשר ה-daemon עצור. בזמן שהוא פועל, זה אוסף ומחק כל קבוצה בתוך אלפיות שניה, כך שרישום ספרייה מתחרות את הקולט ומראה הרבה פחות אירועים מאשר פולטו. + בדוק את הספול רק כאשר השדכן עצור. בזמן שהוא פועל, הוא אוסף ומוחק כל אצווה תוך אלפיות שנייה, כך שרישום ספריה מתחרה בקלט ומציג הרבה פחות אירועים מאלו שפליטו. ## מנע כישלונות בזמן ריצה מותאם -השתמש במצאי ביקורת ועקבות קשורות כדי להגדיר את הפעולה הלא בטוחה, ראיות נדרשות, ותגובה מיועדת. שילוב אכיפה מותאם חייב לחשוף את הפעולה לפני ביצוע, להעביר את הקלט המובנה שלה למנוע מדיניות, ויישום את החלטת allow, instruct, או deny שהתקבלה. +השתמש בממצאי ביקורת וזיכרות מקושרות כדי להגדיר את הפעולה בלתי בטוחה, ראיות נדרשות, ותגובה מיועדת. אינטגרציה אכיפה מותאמת חייבת לחשוף את הפעולה לפני ביצוע, להעביר את הקלט המובנה שלה למנוע המדיניות, ולהחיל את החלטת allow, instruct, או deny. -[יצור קשר עם Failproof AI](mailto:support@befailproof.ai) ואנחנו נעזור למפות את גבולות המודל, הכלי והחיים של הזמן ריצה שלך למנקי מדיניות, ואז אנחנו נאמת את השילוב איתך. \ No newline at end of file +[צור קשר עם Failproof AI](mailto:support@befailproof.ai) ואנחנו נעזור למפות את הגבולות של מודל, כלי וחיים בזמן הריצה שלך לחיבורי מדיניות, ואחר כך לאמת את האינטגרציה איתך. \ No newline at end of file diff --git a/docs/he/reference/evaluator-sdk.mdx b/docs/he/reference/evaluator-sdk.mdx index 26456b41..4908f2a1 100644 --- a/docs/he/reference/evaluator-sdk.mdx +++ b/docs/he/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "בנה שירות שמדרג Failproof AI sessions בצורה סינכרונית או אסינכרונית." +description: "הפעל תהליך הערכה משלך, לשופטי LLM וכל דבר אחר שהפייתון המתארח אינו יכול לעשות." icon: "gauge" --- -Evaluator מקבל סשן agent שהושלם ומחזיר את אותות האיכות שחשובים לך: ניקוד מספרי, הסבר לכל ניקוד, וסיכום אופציונלי. Failproof AI שומר את התוצאות הללו לצד ה-trace וממציא אותן על פני agents וסביבות שונות. +ה-Evaluator SDK מריץ הערכות על התשתית שלך. התהליך שלך רושם את ההערכות שלו עם Failproof AI, משוך סשנים כשהם מסתיימים, נותן להם ניקוד ושולח את התוצאות, הכל דרך HTTPS יוצא: שום דבר לא מתחבר אליו. השתמש בו לדברים ש-[hosted Python](/he/evaluations/write) לא יכול לעשות — שופטי LLM, קריאות מודל, חבילות, סודות וגישה לרשת. התוצאות שלו מופיעות לצד אלה שמתארחות בעמוד [evaluations](/he/sessions/evaluations), מתויגות **customer**. -## הגדר evaluator +הוא משולח ב-`failproofai-sdk`, תחת `failproofai_sdk.evaluator`; ייבוא ה-tracing SDK אינו טוען אותו. - - - התקן את ה-SDK ואת השרת המשמש להריצה שלו. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - צור `evaluator.py`. הדוגמה הזו בודקת האם סשן מכיל קריאות tool כושלות. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - הגדר token משותף, התחל את ה-evaluator, וודא שendpoint ה-health שלו מגיב. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - בטרמינל אחר: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## חבר את ה-evaluator ל-Failproof AI - -1. פרוס את ה-evaluator ב-URL של HTTPS שנגיש עבור Failproof AI Cloud. -2. הגדר את `EVALUATOR_ENDPOINT` עם ה-URL הזה וקבע את `EVALUATOR_TOKEN` לאותו token שמשמש את ה-evaluator. עבור Cloud מנוהל, צור קשר עם [support@befailproof.ai](mailto:support@befailproof.ai) כדי להגדיר את החיבור. -3. הרץ הערכה וודא שהניקודים שלה מופיעים ב-Failproof AI. - - - - פתח סשן שהושלם תחת **Observe → Sessions** ובחר **Run evaluation** אם הוא לא הוערך באופן אוטומטי. בדוק את ה-status, הניקודים, הנימוק והסיכום בלוח **Evaluation** של הסשן. - - השתמש ב-**Observe → Evaluations** כדי להשוות ניקודים על פני agents או סביבות שונות. השתמש ב-**Observe → Metrics** למדידות של latency, cost, token ואחרות מספריות. - - התחל עם סשן אחד כדי לודא שה-evaluator החזיר את מפתחות הניקוד הצפויים ונימוק שימושי עבור ריצה ספציפית זו. - - ![תצוגת פרטי סשן המציגה ניקודי הערכה ונימוק לצד ה-trace שלה.](/images/dashboard/session-detail.png) +```bash +pip install failproofai-sdk +``` - כאשר התוצאות הבודדות נראות נכונות, השתמש בדשבורד ההערכה כדי להשוות ניקודים אלה לאורך זמן ועל פני agents או סביבות שונות. +## כתיבת הערכות - ![דשבורד איכות שמציין ניקודי evaluator לאורך זמן.](/images/dashboard/dashboard-quality.png) +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - דיאגרמה בריאה צריכה להשתמש בשמות ניקוד יציבים; שינוי של מפתח יוצר סדרה נפרדת. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - -עבור instance Cloud בהוראה עצמית, הערכה אוטומטית מושבתת עד שקבעו `EVALUATOR_ENDPOINT` בתהליך השרת. הפעל מחדש את השרת לאחר שינוי משתני סביבה של evaluator. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` -השירות חושף `GET /health`, `GET /config`, `POST /evaluate`, ואפשרות `GET /evaluate/{job_id}`. החזר `JobPending` עבור עבודה אסינכרונית והרשם `@app.job_lookup` כדי Failproof AI יוכל לבדוק אותה. +- `@app.eval(key, version=...)` רושם הערכה. המפתח הוא מה שתוצאותיו מתרשמות תחתיו; שנה את הגרסה בכל פעם שהלוגיקה משתנה, וכל תוצאה שומרת את הגרסה שיצרה אותה. תהליך אחד מחזיק עד 100 הערכות. +- `result_kind` הוא `"score"` אלא אם ציינת אחרת. להערכת `"metric"` או `"assertion"`, תן לרשומה אחת `metrics` או `assertions` אחרי המפתח: הרשומה הזו היא התוצאה שלה. +- `when` מחליט האם סשן חל. החזר `ConditionResult(False, "")` כדי לדלג על אחד, והסיבה נרשמת. +- הערכה יכולה להיות פונקציה רגילה או `async`, ו-`timeout_seconds` מקשרת אותה. +- מפתחות עומס — `tool_name`, `response` ו-`content` למעלה — הם מה שהאג'נטים שלך שולחים, אז קרא אותם מסשן אמיתי. -כאשר token מוגדר, כל הנתיבים חוץ מ-health דורשים את אותו bearer token ש-Failproof AI שולח כ-`EVALUATOR_TOKEN`. +## הפעלת התהליך -## סוגי SDK +שים מפתח עם הרשאת `evaluations:run`, שנוצר תחת **Administration → Keys**, ב-`FAILPROOFAI_EVALUATOR_TOKEN` — הגדר אותו מחנות הסודות שלך ולא הקלד אותו לפקודה — והתחל את התהליך: -| Type | Fields | -| --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -## Decorators ונתיבים +ללא בלוק `__main__`, `python -m failproofai_sdk.evaluator evaluator:app` עושה את אותו הדבר. -| Decorator | Route | Required | +| משתנה | ברירת מחדל | תכלית | | --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | Yes | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | When returning `JobPending` | -| `@app.config` | `GET /config` | No | - -ה-SDK מגביל גופי בקשות הערכה ל-25 MiB. שדות בקשה לא ידועים מתעלמים כך ששירותים נשארים תואמים כחוזה האירוע גדל. +| `FAILPROOFAI_EVALUATOR_URL` | נדרש | היכן Failproof AI: `https://app.befailproof.ai` לעננן. HTTPS אלא אם זה מצביע על loopback | +| `FAILPROOFAI_EVALUATOR_TOKEN` | נדרש | מפתח עם `evaluations:run` | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | שמות לתהליך זה | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | סשנים שתהליך זה נותן ניקוד בו בעת זו | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | קצבת זמן לכל בקשה ל-Failproof AI | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | כמה זמן תהליך עוצר מחכה להרצות בטיסה | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | אפשר HTTP רגיל לכתובת שאינה loopback — ראה את ההתריעה להלן | +| `FAILPROOFAI_EVALUATOR_MODULE` | none | ה-`module:attribute` ל-`python -m failproofai_sdk.evaluator` | + + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` שולח הכל בטקסט צחוח. התהליך נושא את `FAILPROOFAI_EVALUATOR_TOKEN` כראש `Authorization: Bearer` בכל בקשה, והתמלילים שהוא משיג הם הסשנים עצמם — אז כל אחד בנתיב קורא את שניהם, והמפתח שהם קוראים מריץ הערכות עד שתסובב אותו. השתמש בו רק ברשת פיתוח מבודדת. בכל מקום אחר כתובת ה-URL חייבת להיות HTTPS; loopback לא צריך דגל. + + +## סוגי תוצאה + +| סוג | שדות | +| --- | --- | +| `Score` | `value` (0 עד 1), `passed`, `unit` (ברירת מחדל `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -## החזר עבודה אסינכרונית +`EvalResult` נושא לפחות ניקוד, מדד או טענה אחת, ולכל היותר 25, כל אחד תחת מפתח ייחודי. -השתמש ב-`JobPending` כאשר הערכה לא יכולה להסתיים בתוך בקשה אחת. מזהה הJob אטום ל-Failproof AI וחייב להישאר ניתן לפתרון על ידי שירותך עד שהתוצאה נאספת או תוקף ה-timeout של השרת תפוג. +## הסשן -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| שדה או שיטה | נותן לך | +| --- | --- | +| `session_id`, `agent_id`, `environment` | הזהות של הסשן | +| `started_at`, `ended_at` | מתי הוא התחיל והסתיים | +| `event_count`, `events` | התמלול המלא, מסודר | +| `count(event_type)` | כמה אירועים מסוג זה הוא מחזיק | +| `events_of_type(event_type)` | אותם אירועים, בסדר | -קדנציה של polling נבחרת בסדר זה: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs`, ואז `EVALUATOR_POLLING_INTERVAL_SECS` של השרת. ערכים מחוברים בין שנייה אחת ושעה אחת. תקרת polling של wall-clock ברירת המחדל של השרת היא שעה אחת. +כל אירוע נושא `id`, `ts`, `event_type` ו-`payload`. -## שדות בקשה ותגובה +## מעריך המורשת -| Field | Type | Notes | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | כרגע `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | זהות סשן וסביבה. | -| `started_at` | `datetime` | חותמת זמן של האירוע הראשון. | -| `ended_at` | `datetime \| None` | קיים כאשר הסשן פליט אירוע סיום. | -| `events` | `list[AgentEvent]` | זרם אירוע מלא ומסודר. | -| `AgentEvent.id` | `int` | מזהה שורה אירוע של backend. | -| `AgentEvent.ts` | `datetime` | חותמת זמן של אירוע. | -| `AgentEvent.event_type` | `str` | משפחת אירוע כגון `tool_use`. | -| `AgentEvent.payload` | `dict[str, Any]` | גוף אירוע מלא. | -| `EvalResponse.scores` | `dict[str, float] \| None` | ממדים מספריים שמופיעים בהערכות. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | הסברים לכל ניקוד; מפתחות צריכים לשקף את `scores`. | -| `EvalResponse.summary` | `str \| None` | סיפור הערכה כללי. | - -## הגדרות של מפעיל שרת - -הערכה אוטומטית היא כל deployment וגם נשארת מושבתת כאשר `EVALUATOR_ENDPOINT` חסר. - -| Variable | Default | Purpose | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | unset | Base URL של שירות ה-evaluator. | -| `EVALUATOR_TOKEN` | unset | Bearer token משותף עם `Evaluator(token=...)`. | -| `EVALUATOR_WORKERS` | `2` | עובדים של dispatcher בו-זמניים. | -| `EVALUATOR_CLAIM_BATCH` | `4` | סשנים טבועים לכל מעבר של dispatcher. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | קדנציית polling אסינכרונית של fallback. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | timeout evaluator לכל בקשה. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | ניסיונות משלוח לפני כישלון סופי. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | קדנציית refresh של `/config`. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | זמן polling אסינכרוני של wall-clock מרבי. | - -השרת יכול גם להגביל אילו ארגונים משתמשים ב-evaluator הגלובלי של deployment. התייחס לשינויים של endpoint, token, retry ו-organization-gate כהגדרת מפעיל והפעל מחדש או גלגול את השרת לאחר שינוי שלהם. - -## אבטחה ותפעול - -- הצב את ה-evaluator מאחורי HTTPS כאשר תעבור עוברת גבול של רשת מהימנה. -- הגדר bearer token לא ריק ושמור על זהותו בשני השירותים. -- אל תיומן את ה-token או prompts רגישים מלאים מגופי בקשות. -- הגדר핸handlers סינכרוניים כ-idempotent; retries עלולים לחזור על בקשה. -- המשך מצב עבודה אסינכרוני מחוץ לזיכרון תהליך בייצור. -- החזר מפתחות ניקוד יציבים. שינוי שם של מפתח יוצר סדרה תרשים חדשה במקום שינוי של הישן. - -ה-SDK פולט רישומי life-cycle מובנים כגון `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected`, ויוצאים מ-handler. הוא לא מגדיר handlers של logging; השתמש בהגדרת הlogging של יישום ה-host. \ No newline at end of file +ה-Evaluator SDK המוקדם — שירות HTTP שFailproof AI קרא ל-`EVALUATOR_ENDPOINT`, מענה ל-`/evaluate` ובדק דרך `JobPending` — הוא פרוש. בנה מעריכים חדשים בתהליך זה; מפעילים של מופע מתארח עצמי המריץ שירות מורשה יכול להשמור עליו דרך המעבר. \ No newline at end of file diff --git a/docs/he/reference/failproof-cli.mdx b/docs/he/reference/failproof-cli.mdx index 26547f12..495bcb37 100644 --- a/docs/he/reference/failproof-cli.mdx +++ b/docs/he/reference/failproof-cli.mdx @@ -1,86 +1,104 @@ --- title: "Failproof AI CLI" -description: "התקן hooks, נהל מדיניות מקומית, חבר ל-Cloud, והפעל את ה-daemon המקומי." +description: "התקן hooks, נהל מדיניות מקומית, התחבר ל-Cloud והפעל את ה-daemon המקומי." icon: "terminal" --- -התקן את ה-CLI המקומי עם `npm install -g failproofai`. הרץ אותו ללא ארגומנטים כדי לפתוח את לוח הבקרה של המדיניות המקומית. +התקן את ה-CLI המקומי עם `npm install -g failproofai`. הפעל אותו ללא ארגומנטים כדי לפתוח את לוח הבקרה של המדיניות המקומית. -החבילה דורשת Node.js 20.9 ואילך. Bun 1.3 ואילך נתמך לפיתוח והתקנות מקוד. `failproofai configure` ו-`failproofai setup` הם כינויים ל-`failproofai config`; `failproofai p` הוא כינוי ל-`failproofai policies`. +החבילה דורשת Node.js 20.9 ובאופן חדש יותר. Bun 1.3 ובאופן חדש יותר נתמך לפיתוח והתקנות מקור. `failproofai configure` ו-`failproofai setup` הם כינויים ל-`failproofai config`. `failproofai policy`, `failproofai pack` ו-`failproofai p` הם כל הכתיבות של `failproofai policies` — packs ומדיניות בודדות היו שלוש פקודות לרעיון אחד והן כעת אחת. הכתיבות הישנות עדיין עובדות, עם שתי חריגויות: `pack list ` הוא כעת `policies show `, ו-`pack build` הוא כעת `publish`. -## הגדרת מכונה +## הגדר מכונה + +התקן את ה-CLI, ואז קרא את מפתח המכונה לתוך ה-shell. `read -s` לוקח אותו בהנמקה שלא משתקפת, כך שהוא לא מופיע בפקודה: ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +אז הגדר את המכונה בחר מה היא אוכפת: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` -הרץ את `failproofai` ללא ארגומנטים כדי לפתוח את לוח הבקרה של המדיניות המקומית. +`failproofai config` הוא כל ההגדרה: הוא מתקין את שירות `failproofaid` (root פעם אחת, דרך `sudo -n` — לא לעולם הנחיית סיסמה אינטראקטיבית), חיווט hooks לכל agent CLI שהוא מוצא, והתחברות ל-Cloud כשמפתח זמין. ללא טרמינל — CI, קונטיינר, agent המנהל אותו — הוא מיישם במקום לשאול, ויוצא 1 אם משהו שהוא התבקש לעשות לא קרה. + +הוא בוחר **לא** מדיניות. זו עבודת הפקודה השנייה, וללא זה מכונה שנוצרה זה עתה אוכפת שום דבר פרט לשומר שתמיד פועל. + +עדיף להשתמש במשתנה הסביבה על פני `--token`: ארגומנט שורת פקודה קריא מ-`ps` על ידי כל משתמש בתיבה. זה כל מה שהמשתנה מגן עליו — מפתח שהוקלד לכל פקודה, כולל `export`, עדיין נוחת בהיסטוריית shell, וזו הסיבה שהוא קרא עם `read -s` למעלה. ב-CI, הגדר זאת מחנות הסודות והשאר עקיבה shell (`set -x`) כבויה, או העקיבה מדפיסה אותה. + + + `--connect ` רושם מכונה שהוא **כבר הוגדר**. זה חוזר ברגע שההרשמה מצליחה — זה לא מתקין את ה-daemon וזה לא חיווט כל hooks. השתמש בפשוט `failproofai config` (או `failproofai config --token `) על מכונה שלא הוגדרה עדיין, או זה יקרא כמחובר תוך איסוף והטלה של שום דבר. + + +הפעל את `failproofai` ללא ארגומנטים כדי לפתוח את לוח הבקרה של המדיניות המקומית. | פקודה | תוצאה | | --- | --- | -| `failproofai config` | הרץ הגדרת מכונה אינטראקטיבית | -| `failproofai config --connect --token ` | חבר הזרמת Cloud והעברת מדיניות | -| `failproofai config --status` | הצג מצב חיבור, daemon, העברה וקבוע השהייה | -| `failproofai policies` | רשום מדיניות מובנות, מותאמות אישית, קונוונציה, חבילה וממנוהלות על-ידי Cloud | -| `failproofai policies --install` | התקן hooks והפעל מדיניות | -| `failproofai policy add ` | הפעל מדיניות אחת — מובנית, או `:` מחבילה מותקנת | -| `failproofai policy remove ` | השבת מדיניות אחת, אותה שמות | -| `failproofai policies --uninstall` | השבת מדיניות או הסר hooks של ה-harness | -| `failproofai pack list` | רשום חבילות מדיניות מותקנות וכל מדיניות שכל אחת נושאת | -| `failproofai pack add ` | התקן חבילת מדיניות מ-GitHub release; ללא tag לוקח את החדשה ביותר וקובע אותה | -| `failproofai pack add --bundled` | התקן את המדיניות המובנות כחבילה, מהחבילה זו, ללא רשת | -| `failproofai pack build ` | בנה את שלושת נכסי ה-release לחבילה שלך | -| `failproofai pack remove ` | בטל הפעלה של חבילה מותקנת | -| `failproofai audit` | סרוק היסטוריית סוכנים מקומית ופתח את תצוגת הביקורת המקומית | -| `failproofai audit --schedule [days] --email
` | תזמן סריקות מקומיות חוזרות ושלח את הממצאים שלהן בדוא״ל | -| `failproofai audit --status` | הצג את כתובת הדוח, המרווח והסריקה הבאה המתוזמנת | +| `failproofai config` | הגדר את המכונה: agents, daemon, ו-Cloud כשמפתח נוכח | +| `failproofai config --token ` | הגדר והתחבר בפעם אחת, ללא שאלה | +| `failproofai config --connect ` | רשום מכונה שהיא **כבר** הוגדרה — לא daemon, לא hooks | +| `failproofai config --status` | הצג חיבור, daemon, משלוח, והשהיה של מדינה | +| `failproofai policies` | רשום מדיניות מובנית, מותאמת אישית, קונבנציה, pack, ו-Cloud | +| `failproofai policies --install` | חיווט hooks לתוך agent CLIs שלך. לא מאפשר מדיניות בעצמו | +| `failproofai policies add ` | אפשר מדיניות אחת — מובנית, או `:` מ-pack מותקן | +| `failproofai policies remove ` | השבת מדיניות אחת, אותו שם | +| `failproofai policies --uninstall` | השבת מדיניות או הסר hook hooks harness | +| `failproofai policies show /` | מה pack נושא, קרא מהמניפסט שלו, לפני שתיקח אותו | +| `failproofai policies show / --releases` | כל גרסה שפרסמה, וזה איזה אחד כאן | +| `failproofai policies add ` | התקן pack מדיניות מ-GitHub release; ללא תג לוקח את החדש ביותר וקובע אותו | +| `failproofai publish` | שלח את המדיניות שלך כ-pack; `--init` כותב אחד להתחיל ממנו | +| `failproofai policies remove ` | הסר התקנה של pack | +| `failproofai audit` | סרוק היסטוריית agent מקומית ופתח את התצוגה ביקורת מקומית | +| `failproofai audit --schedule [days] --email
` | תזמן סריקות מקומיות חוזרות ודברים את הממצאים שלהם | +| `failproofai audit --status` | הצג את כתובת הדוח, את המרווח, וסריקה מתוזמנת הבאה | | `failproofai audit --no-schedule` | עצור סריקות חוזרות ללא מחיקת היסטוריית ביקורת | -| `failproofai harness list` | רשום נתיבי לכידה נוספים | -| `failproofai flush --wait` | העבר את ה-spool של האירוע הנוכחי | +| `failproofai harness list` | רשום נתיבים של לכידה נוספים | +| `failproofai flush --wait` | משלוח ספול האירוע הנוכחי | | `failproofai backfill --since 30d` | קרא מחדש היסטוריה שעברה בעבר | -| `failproofai config --pause [duration]` | השהה ישומון מקומי אחד ל-30 דקות כברירת מחדל, עד 8 שעות | -| `failproofai config --resume` | התחזר לישומון מקומי המושהה; הוסף `--all` כדי לנקות את כל ההשהיות | -| `failproofai update` | סיים הידרות חבילה והדק את ה-daemon | -| `failproofai migrate --dry-run` | תצוג או הפעל הידרות פריסת ביתיות ממתינות | -| `failproofai uninstall` | הסר hooks וה-daemon לפני הסרת החבילה | -| `failproofai --version` | הדפס את גרסת החבילה המותקנת | +| `failproofai config --pause [duration]` | השהה הפעלה מקומית אחת במשך 30 דקות כברירת מחדל, עד 8 שעות | +| `failproofai config --resume` | חידוש הפעלה מקומית מושהית אחת; הוסף `--all` כדי לנקות את כל ההשהיות | +| `failproofai update` | סיים הגדרות חבילה והעדכן את ה-daemon | +| `failproofai migrate --dry-run` | תצוגה מקדימה או הפעלת הגדרות בית הנדירות | +| `failproofai uninstall` | הסר hooks ו-daemon לפני הסרת החבילה | +| `failproofai --version` | הדפס גרסה חבילה מותקנת | | `failproofai --help` | הצג פקודות ושימוש גלובלי | ## דגלי תצורה | דגל | שימוש | | --- | --- | -| `--connect --token ` | חבר בלא אינטראקטיבי | +| `--token ` | הגדר והתחבר ללא אינטראקטיבי; קראו גם מ-`FAILPROOFAI_CLOUD_TOKEN` | +| `--url ` | התחבר למקום אחר מאשר `app.befailproof.ai`; קראו גם מ-`FAILPROOFAI_CLOUD_URL` | +| `--connect ` | רשום בלבד, על מכונה כבר הוגדרה. דלג על ה-daemon וכל hook | | `--machine-id ` | הגדר את מזהה המכונה היציב | -| `--machine-label ` | הגדר או שנה את תווית לוח הבקרה | +| `--machine-label ` | שנה שם של מכונה שהיא **כבר מחוברת**. בעצמו זה לא מריץ הגדרה, כךשתן אותו אחרי `failproofai config`, לא במהלכו | | `--no-transcripts` | שלח החלטות ללא תוכן תמלול | -| `--disconnect` | עצור משיכות מדיניות Cloud והעברת אירוע | +| `--disconnect` | עצור משיכות מדיניות Cloud ומשלוח אירוע | | `--status` | הצג מצב מכונה נוכחי | -| `--pause [duration]` | השהה את הישומון החדש ביותר בספריה הנוכחית; מקבל שניות, דקות או שעות וברירת המחדל היא 30 דקות | -| `--resume` | סיים השהיה תואמת מוקדם | -| `--session ` | כוונן ישומון מפורש להשהיה או חזרה | +| `--pause [duration]` | השהה את הפעלה החדשה ביותר בספריה הנוכחית; קובל שניות, דקות, או שעות ברירת מחדל ל-30 דקות | +| `--resume` | סיים השהיה משובטת מוקדם | +| `--session ` | היעד הפעלה מפורשת להשהיה או חידוש | | `--all` | עם `--resume`, סיים כל השהיה פעילה | -השהיות מקומיות משהות מדיניות מובנית, מותאמת אישית, קונוונציה וחבילה לישומון אחד. הם תמיד פוקעים ולא משביתים מדיניות ממנוהלות על-ידי Cloud. `block-failproofai-commands` — שהוא תמיד פעיל ולא ניתן להשבית או להשהות בעצמו — מונע מסוכן מכוונן לשימוש בדלת בריחה זו. +השהיות מקומיות מחליקים מדיניות מובנית, מותאמת אישית, קונבנציה, ו-pack לפעלה אחת. הם תמיד פוקעים וזה לא משבית מדיניות Cloud. `block-failproofai-commands` — שהוא תמיד פועל ולא יכול להיות מושבת או מושהית — מונע agent מכשיר מ שימוש בדלק זה בעצמו. ## דגלי מדיניות | דגל | שימוש | | --- | --- | -| `--install`, `-i` | הפעל מדיניות והתקן hooks של harness | +| `--install`, `-i` | התקן hook harness. שמות אחריו מאפשרים את המדיניות הללו; ללא אחריו, לא שינויי מדיניות | | `--uninstall`, `-u` | השבת מדיניות או הסר hooks | -| `--cli ` | כוונן harness אחד או יותר הנתמכים | -| `--scope user\|project\|local\|all` | בחר את טווח התצורה; `all` לביטול התקנה | +| `--cli ` | היעד מכשירים נתמכים אחד או יותר | +| `--scope user\|project\|local\|all` | בחר טווח התצורה; `all` להסרה | | `--beta` | כלול מדיניות בטא | -| `--custom`, `-c ` | אמת וטען קובץ מדיניות מותאם אישית; חוזרת | +| `--custom`, `-c ` | אמת וטען קובץ מדיניות מותאם אישית; חוזר | -## דגלי העברה ותחזוקה +## משלוח וצמודים תחזוקה | פקודה | דגלים | | --- | --- | @@ -90,7 +108,7 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -יש להריץ את `failproofai update` לאחר `npm install -g failproofai@latest`; הוא מבצע הידרות פריסת ביתיות, מתקין את בינארי ה-daemon התואם, ומפעיל מחדש את השירות. `--no-daemon` מבצע רק את הידרת הפריסה. +`failproofai update` צריך להיות מופעל אחרי `npm install -g failproofai@latest`; זה מבצע הגדרות בית וסיגים, מתקין את ה-daemon בינארי התואם, ומפעיל מחדש את השירות. `--no-daemon` מבצע רק את הגדרת הנתח. ## נתיבי Harness @@ -100,38 +118,40 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -שמות harness הנתמכים הם `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` ו-`goose`. +שמות harness נתמכים הם `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, ו-`goose`. -תוויות מרחב שמות מזהי סוכנים נגזרים כאשר שני roots מכילים עותקים של אותו פרויקט. roots חופפים וכינויים כפולים נדחים כדי למנוע אוספים כפולים או הישחתות cursor. תצורה של נתיבים נוספים טוענת מחדש ללא הפעלה מחדש של daemon. +תוויות מרחב שמות agent ID נגזר כאשר שני שורשים מכילים עותקים של אותו פרויקט. שורשים חופפים וערכות כינויים כפולות נדחים כדי להתחמק מאיסוף כפול או קולקציה פעכרסור. תצורת נתיב נוסף טוענת מחדש ללא הפעלה מחדש של daemon. -סביבות קונטיינר יכולות להחליף נתיבים קבועים בקובץ בעזרת משתנה מופרד בפסיקים בשם `FAILPROOFAI__EXTRA_PATHS`, למשל: +סביבות קונטיינר יכולות להחליף נתיבים מוגדרים בקבצים בעזרת משתנה המופרד בפסיקים בשם `FAILPROOFAI__EXTRA_PATHS`, לדוגמה: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" ``` -## משתנים סביבתיים +## משתני סביבה -השתמש בקובצי תצורה לתנהגות מכונה קבועה. משתנים סביבתיים שימושיים ביותר לקונטיינרים, בדיקות וכתיב אחד. +השתמש בקבצי תצורה להתנהגות מכונה קבועה. משתני סביבה הם שימושיים ביותר לקונטיינרים, בדיקות, תהליך אחד. | משתנה | שימוש | | --- | --- | -| `FAILPROOFAI_HOME` | עביר את הפריסה השלמה של `~/.failproofai` | -| `FAILPROOFAI_LOG_LEVEL` | הגדר מילולות רישום מקומיות | -| `FAILPROOFAI_HOOK_LOG_FILE` | כתוב אבחון hook לקובץ שנבחר | +| `FAILPROOFAI_CLOUD_TOKEN` | המפתח Cloud, במקום `--token`. עדיף זה: ארגומנט קריא מ-`ps` על ידי כל משתמש. הגדר אותו עם `read -s` או מחנות סוד CI, לעולם לא על ידי הקלדת המפתח לפקודה, אשר נוחתת בהיסטוריית shell בכל מקרה | +| `FAILPROOFAI_CLOUD_URL` | Cloud URL, במקום `--url`. אותו משתנה ש-daemon קורא | +| `FAILPROOFAI_HOME` | איכלס את הפריסה `~/.failproofai` הושלמה | +| `FAILPROOFAI_LOG_LEVEL` | הגדר מילולוביות רישום מקומי | +| `FAILPROOFAI_HOOK_LOG_FILE` | כתוב diagnostics hook לקובץ שנבחר | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | השבת טלמטריה אנונימית לתהליך זה | -| `FAILPROOFAI_NO_FIRST_RUN=1` | דלג על הגדרת ההפעלה הראשונה האינטראקטיבית | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | דלג על הביקורת המקומית לאחר ההגדרה | -| `FAILPROOFAI_LLM_BASE_URL` | דרוס את נקודת הקצה התואמת OpenAI המשמשת מדיניות LLM | -| `FAILPROOFAI_LLM_API_KEY` | סך את מפתח ה-API המשמש מדיניות LLM | -| `FAILPROOFAI_LLM_MODEL` | בחר את המודל המשמש מדיניות LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | חץ טעינת מודול מדיניות מותאם אישית | -| `FAILPROOFAI_NO_DOWNLOAD=1` | סרב להביא חבילות וביניאריות daemon; מה שמותקן שומר על אכיפה | -| `FAILPROOFAI_PACK_BASE_URL` | הביא חבילות ממראה במקום מ-`github.com` | -| `FAILPROOFAI__EXTRA_PATHS` | החלף נתיבי לכידה נוספים מוגדרים לharness אחד | +| `FAILPROOFAI_NO_FIRST_RUN=1` | דלג על הגדרת הפעלה ראשונה אינטראקטיבית | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | דלג על ביקורת מקומית לאחר הגדרה | +| `FAILPROOFAI_LLM_BASE_URL` | לעקוף את endpoint התואם OpenAI המשמש במדיניות LLM | +| `FAILPROOFAI_LLM_API_KEY` | סחן את מפתח API המשמש במדיניות LLM | +| `FAILPROOFAI_LLM_MODEL` | בחר את המודל המשמש במדיניות LLM | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | חוק קובץ מדיניות מותאם אישית טעינת מודול | +| `FAILPROOFAI_NO_DOWNLOAD=1` | סרב להביא packs ודק binaries; מה התקן שומר אכיפה | +| `FAILPROOFAI_PACK_BASE_URL` | הביא packs מראי במקום `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | החלף נתיבי לכידה נוסף מוגדרים לאחד harness | | `NO_COLOR` | השבת פלט טרמינל צבעוני | -משתנים בית ספציפיים לסוכן כגון `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` ו-`OPENCLAW_HOME` דורסים היכן Failproof AI גילוי ישומונים מקומיים לחרט זה. +משתני בית ספציפיים agent כגון `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, ו-`OPENCLAW_HOME` לעקוף איפה Failproof AI גולש הפעלות מקומיות ל-harness זה. ## השהה או הסר מכונה בבטחה @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -השהיית ישומון מקומי אינה משביתה מדיניות ממנוהלות על-ידי Cloud. שחזר פריסות Cloud דרך זרימת העבודה של אכיפה Cloud כאשר ה-rollout עצמו הוא הבעיה. +השהיה הפעלה מקומית אינה משביתה מדיניות Cloud. שחזר פרסומי Cloud דרך זרימת עבודת Cloud כאשר ההטלה עצמה היא הבעיה. -לפני הסרת חבילת npm, הסר hooks מותקנים וה-daemon: +לפני הסרת חבילת npm, הסר hooks מותקנים ו-daemon: ```bash failproofai uninstall --dry-run @@ -151,8 +171,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -הרץ את `failproofai --help` לפרטים ספציפיים לגרסה. +הפעל את `failproofai --help` לפרטים ספציפיים לגרסה. - הרץ את `failproofai uninstall` לפני `npm rm -g failproofai`; npm אינו מסיר hooks של סוכנים מותקנים או שירות daemon. + הפעל את `failproofai uninstall` לפני `npm rm -g failproofai`; npm לא מסיר hook agent מותקנים או שירות daemon. \ No newline at end of file diff --git a/docs/he/reference/harnesses.mdx b/docs/he/reference/harnesses.mdx index 44c5d0ed..3adcc949 100644 --- a/docs/he/reference/harnesses.mdx +++ b/docs/he/reference/harnesses.mdx @@ -1,80 +1,86 @@ --- -title: "חיבורי agents" -description: "ללכוד הפעלות ויישום מדיניות בכל 12 חיבורי agents הנתמכים." +title: "מנגנוני סוכנים" +description: "תפסו הפעלות ואכפו מדיניות בכל 12 מנגנונים סוכנים נתמכים." icon: "plug-zap" --- -חיבור הוא הסביבה בה ה-agent שלך בעצם רץ. Failproof AI תומך בשנים עשר חיבורים, בשתי מחלקות: +מנגנון הוא כל דבר שהסוכן שלך בעצם רץ בתוכו. Failproof AI תומך בשנים עשר מהם, בשתי קטגוריות: -- **CLIs לקידוד** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **שערים של צ'ט וסוכני מידע** (2) — Hermes (Slack, Telegram, cron), OpenClaw (סוכן מארח עצמאי) +- **CLI קידוד** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **שערי צ'אט ועוזר** (2) — Hermes (Slack, Telegram, cron), OpenClaw (עוזר בעצמאות) -אותה מדיניות והיסטוריה של פעילות זהה חלות בכל חיבור. שכבת מתאם אחת ממפה את שמות האירועים המקוריים של כל חיבור, שמות הכלים ושדות קלט של כלים ל-29 אירועים קאנוניים לפני הרצת כל מדיניות. +אותן מדיניות ואותו היסטוריית הפעלה חלים בכל מנגנון שהסוכן רץ בו. שכבת מתאם אחת ממפה את שמות האירוע, שמות הכלים ושדות קלט הכלים המקוריים של כל מנגנון ל-29 אירועים קנוניים לפני שתי מדיניות רצה. -agent שרץ בכל **אחד** מהשנים עשר מותקן ישירות עם [Python SDK](/he/reference/custom-agents). זה חוזה שונה, וראוי לציין זאת בבהירות: ה-SDK מספק tracing, הפעלות, הערכות וביקורות — **הוא לא יוצא לאכיפת מדיניות בעצמו.** חסימת פעולה לא בטוחה לפני ביצועה דורשת וו אכיפה בגבול הכלי של זמן ההרצה שלך; [צור איתנו קשר](mailto:support@befailproof.ai) ואנחנו נממפה זאת. +סוכן שרץ ב**כלום** מבין השנים עשר מעוצבים ישירות עם [SDK Python](/he/reference/custom-agents). זה חוזה שונה, וכדאי להצהיר זאת בבירור: ה-SDK מספק עקיבה, הפעלות, הערכות ואודיטים — **הוא לא אוכף מדיניות בעצמו.** חסימת פעולה לא בטוחה לפני ההוצאה לפועל דורשת hook אכיפה בגבול הכלים של זמן הריצה שלך; [צור קשר איתנו](mailto:support@befailproof.ai) והנו נמפה זאת. -| חיבור | טווחי hook נתמכים | +| מנגנון | היקפי hook נתמכים | | --- | --- | | Claude Code | משתמש, פרויקט, מקומי | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | משתמש, פרויקט | | Factory Droid, Devin CLI, Antigravity CLI, Goose | משתמש, פרויקט | | Hermes, OpenClaw | משתמש | -כל אינטגרציה מנרמלת את שמות אירועי ה-hook המקוריים שלה, שמות כלים ושדות קלט של כלים לפני הרצת מדיניות. מדיניות יכולה לפעול רק על אירועים שהחיבור חושף; בדוק התנהגות של סוף תור והוראות בחיבור ובגרסה המדוקדקת שאתה משתמש בה. +כל אינטגרציה מנרמלת את שמות אירוע hook המקוריים שלה, שמות כלים ושדות קלט כלים לפני שמדיניות רצה. מדיניות יכולה לפעול רק על אירועים שהמנגנון חושף; בדוק התנהגות סוף תור והוראה בדיוק על המנגנון והגרסה שבהם תפרוש. ## יכולת אכיפה -"חסימה" פירושה שההחלטה שהוחזרה על ידי המתאם הנוכחי נצרכה על ידי החיבור המתואר. חסימה לאחר כלי עשויה להחליף את התוצאה המוצגת למודל אך לא יכולה לבטל תופעת צד של כלי שכבר התרחשה. +"חסום" פירושו שהפסק ההחזר של ההתאם הנוכחי נצרך על ידי המנגנון בשם. חסימה לאחר כלים עשויה להחליף את התוצאה המוצגת למודל אך לא יכולה לבטל אפקט צד של כלים שכבר קרה. -| חיבור | אירועי חסימה מאומתים | הערות של תצפית בלבד או לא-חסימה | +| מנגנון | אירועי חסימה מאומתים | חסמים רק-ראיה או לא-חוסמים | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` ותמות/אירועי תצורה מספר | `PostToolUse`, מחזור חיים של הפעלה, הודעות ואירועים לאחר כשל הם תצפית בלבד. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | חסימה לאחר כלי מחליפה את התוצאה לאחר ביצוע; אירועי התחלת הפעלה וכיווצה הם תצפית בלבד במתאם הנוכחי. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | חסימה לאחר כלי מחליפה את התוצאה לאחר ביצוע; אירועי הפעלה והודעה הם תצפית בלבד. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` ואירועי הפעלה הם תצפית בלבד. | -| OpenCode | `PreToolUse` | אירועי לאחר כלי ומחזור חיים הם תצפית בלבד; טיפול עצירה נוכחי הוא הנחיה לתור מאוחר יותר ולא שער מאומת. | -| Pi | `PreToolUse`, `UserPromptSubmit` | אירועי לאחר כלי ומחזור חיים הם תצפית בלבד; הנחיית עצירה חלה על תור מאוחר יותר. | -| Hermes | `PreToolUse` | החלטות של לאחר כלי, הפעלה וסטופ של סוכן משנה אינן שערים. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | אירועי לאחר כלי, הפעלה, עצירת סוכן משנה וכיווצה הם תצפית בלבד. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | החלטות של לאחר כלי וסטופ של סוכן משנה הן תצפית בלבד. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` מותנה | ווי הרשאה לא רצים בכל מצב הרשאה; אירועי לאחר כלי והפעלה הם תצפית בלבד. | -| Antigravity CLI | `PreToolUse`, `Stop` | החלטות של הנחיית משתמש ולאחר כלי הן תצפית בלבד; הנחיות הנחיה עדיין ניתן להזריק. | -| Goose | `PreToolUse` | אירועי של הנחיית משתמש, לאחר כלי והפעלה הם תצפית בלבד. ווי עצירה חסימה מקורי קיים במעלה הזרם אך לא מותקן על ידי המתאם הנוכחי. | - -יכולות רגישות לגרסה. בדוק מחדש לאחר שדרוג CLI של agent, במיוחד כאשר מדיניות מסתמכת על התנהגות של הנחיה, עצירה, הרשאה או לאחר כלי ולא על שער ה-pre-tool הנפוץ. - -## התקן ווי ללכידת מידע ומדיניות +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, וכמה אירועי משימה/קונפיגורציה | `PostToolUse`, מחזור חיים הפעלה, התראות, ואירועי לאחר כשל הם תצפיתיים. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | חסימה לאחר כלים מחליפה את התוצאה לאחר הביצוע; התחלת הפעלה ואירועי קומפקט הם תצפיתיים במתאם הנוכחי. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | חסימה לאחר כלים מחליפה את התוצאה לאחר הביצוע; אירועי הפעלה והתראה הם תצפיתיים. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` ואירועי הפעלה הם תצפיתיים. | +| OpenCode | `PreToolUse` | אירועי לאחר כלים ומחזור חיים הם תצפיתיים; ניהול עצירה נוכחי הוא הנחיה לתור מאוחר יותר ולא שער מאומת. | +| Pi | `PreToolUse`, `UserPromptSubmit` | אירועי לאחר כלים ומחזור חיים הם תצפיתיים; הנחיית עצירה חלה על תור מאוחר יותר. | +| Hermes | `PreToolUse` | אירועי לאחר כלים, הפעלה, וסוכן-עצירה משנית אינם שערים. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | אירועי לאחר כלים, הפעלה, סוכן-עצירה משנית, וקומפקציה הם תצפיתיים. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | אירועי לאחר כלים וסוכן-עצירה משנית הם תצפיתיים. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` מותנה | hook הרשאה לא רצה בכל מצב הרשאה; אירועי לאחר כלים והפעלה הם תצפיתיים. | +| Antigravity CLI | `PreToolUse`, `Stop` | אירועי הנחיה משתמש ולאחר כלים הם תצפיתיים; הנחיות הנחיה עדיין יכולות להיות מוזרקות. | +| Goose | `PreToolUse` | אירועי הנחיה משתמש, לאחר כלים, והפעלה הם תצפיתיים. hook עצירה חסימה מקור קיים אך לא מותקן על ידי המתאם הנוכחי. | + +יכולות רגישות לגרסה. בדוק מחדש לאחר שדרוג סוכן CLI, במיוחד כאשר מדיניות מסתמכת על התנהגות הנחיה, עצירה, הרשאה, או לאחר כלים ולא על שער הקדם-כלים הנפוץ. + +## התקן hook לכידת ומדיניות - - 1. פתח **Administration → Keys** וצור מפתח עם `events:add` ו-`policies:pull`, בשם המכונה או הסביבה. - 2. במכונת היעד, חבר את CLI המקומי עם המפתח המוצג והתקן את ווי החיבור. - 3. התחל הפעלה חדשה של agent, ואז אשר את אירועי ה-hook וההפעלה שלה תחת **Observe → Events**. - 4. פתח **Observe → policy** לאותו חלון זמן ואשר שהחלטת מדיניות מתויחסת למכונה. + + 1. פתח **ניהול → מפתחות** וצור מפתח עם `events:add` ו`policies:pull`, ובשם למכונה או סביבה. + 2. במכונת היעד, התחבר ל-CLI המקומי עם המפתח המוצג והתקן את hook המנגנון. + 3. התחל הפעלת סוכן חדשה, ואז אשר את hook שלה ואירועי הפעלה תחת **צפייה → אירועים**. + 4. פתח **צפייה → מדיניות** לאותו חלון זמן ואשר שהחלטת מדיניות מיוחסת למכונה. - החיבור מתחיל עם מפתח מכונה. אשר שהוא כולל הן הרשאות הנגשה והן הרשאות מסירת מדיניות לפני העתקת הסוד שלו. + החיבור מתחיל עם מפתח מכונה. אשר שהוא כולל הן הרשאות ספיגה והן הרשאות עמידת מדיניות לפני העתקת הסוד שלו. - ![מגירת מפתח ה-API החדשה המשמשת להענקת הרשאות הנגשה אירועים ומסירת מדיניות.](/images/dashboard/key-create.png) + ![ספריית מפתח API החדשה המשמשת להעניית הרשאות ספיגת אירוע והעמדת מדיניות.](/images/dashboard/key-create.png) - לאחר התקנת הווי, זרם האירועים צריך להציג אירועים חדשים מהמכונה והסביבה שחיברת. + לאחר התקנת hook, סטרימ האירועים צריך להציג אירועים חדשים מהמכונה והסביבה שבהן התחברת. - ![זרם האירועים החי המשמש לאישור שחיבור החיבור שנותקן החדש מדווח.](/images/dashboard/events-stream.png) + ![סטרימ האירועים החי המשמש לאישור מנגנון שהותקן לאחרונה דיווח.](/images/dashboard/events-stream.png) - לבסוף, אשר שהחלטות מדיניות מיוחסות לאותה מכונה. זה מאשר שהחיבור מדווח על פעילות מדיניות כמו גם אירועי trace. + לבסוף, ודא שהחלטות מדיניות מיוחסות לאותה מכונה. זה מאשר שהמנגנון דיווח פעילות מדיניות כמו גם אירועי עקיבה. - ![דף המדיניות המשמש לאימות החלטות מדיניות מחיבור חדש שחובר.](/images/dashboard/policy-observe.png) + ![דף המדיניות המשמש לאימות החלטות מדיניות מנגנון המחובר לאחרונה.](/images/dashboard/policy-observe.png) - התקן ווי לכל חיבור שהתגלה: + קרא את מפתח המכונה ל-shell. `read -s` מקבל אותו בהנחיה שלא משדרת, כך שהוא לא מופיע בפקודה או בהיסטוריית shell: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - או התקף חיבורים בשם וטווח תצורה: + ואז הגדר את המכונה — זה מחוט hook לכל מנגנון שזוהה, מתקין את daemon, ומתחבר ל-Cloud: + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + התקנה לא מאפשרת מדיניות בעצמה, וזה מה שהפקודה השנייה שלו. + + או לכוונן מנגנונים בשם ויקף קונפיגורציה: ```bash failproofai policies --install \ @@ -82,9 +88,9 @@ agent שרץ בכל **אחד** מהשנים עשר מותקן ישירות עם --scope user ``` - טווח פרויקט שומר תצורת hook עם מאגר. טווח משתמש מכסה עבודה על מאגרים. Claude Code תומך גם בטווח מקומי; התמיכה משתנה לפי חיבור ו-CLI דוחה שילובים לא נתמכים. + היקף פרויקט שומר את קונפיגורציית hook עם מאגר. היקף משתמש מכסה עבודה על פני מאגרים. Claude Code תומך גם בהיקף מקומי; התמיכה משתנה לפי מנגנון ו-CLI דוחה שילובים לא נתמכים. - אשר את המכונה ואת האירועים שלה: + אמת את המכונה ואת האירועים שלה: ```bash failproofai config --status @@ -97,10 +103,10 @@ agent שרץ בכל **אחד** מהשנים עשר מותקן ישירות עם ## הוסף נתיב הפעלה שאינו ברירת מחדל - - נתיבים נוספים רשומים במכונה, לא בחוזה. לאחר הוספת אחד, פתח **Observe → Sessions**, סנן לסביבת המכונה, ואשר שהפעלות מהנתיב החדש מופיעות. פתח הפעלה ובדוק את ה-agent, החיבור וחותמות הזמן של האירועים לפני הסמך עליה בביקורת. + + נתיבים נוספים רשומים במכונה, לא ב-Cloud. לאחר הוספת אחד, פתח **צפייה → הפעלות**, סנן לסביבת המכונה, והשתכנע שהפעלות מהנתיב החדש מופיעים. פתח הפעלה ובדוק את הסוכן, המנגנון, וחותמות זמן האירוע לפני הסתמכות עליו בביקורת. - ![רשימת ההפעלות מסוננת לסביבה המקבלת נתונים מנתיב ללכידת נוסף.](/images/dashboard/sessions-list.png) + ![רשימת ההפעלות מסוננת לסביבה שמקבלת נתונים מנתיב הכידה נוסף.](/images/dashboard/sessions-list.png) הוסף נתיב עם תווית אופציונלית, ואז בדוק את הנתיבים המוגדרים: @@ -117,5 +123,5 @@ agent שרץ בכל **אחד** מהשנים עשר מותקן ישירות עם - הרץ הפעלה חדשה אחת לאחר ההתקנה. אשר גם את זרם האירועים החי וגם החלטת מדיניות בפועל לפני הרחבת הגלגול. + הרץ הפעלת סוכן חדשה אחת לאחר התקנה. אמת גם את סטרימ האירוע החי וגם החלטת מדיניות בפועל לפני הרחבת ההנדסת. \ No newline at end of file diff --git a/docs/he/reference/overview.mdx b/docs/he/reference/overview.mdx index 4c993b07..bff2910a 100644 --- a/docs/he/reference/overview.mdx +++ b/docs/he/reference/overview.mdx @@ -1,81 +1,84 @@ --- -title: "אינטגרציות והפניות" -description: "חבר מחסנים נתמכים של סוכנים, SDKs, CLIs, וה-HTTP API." +title: "Integrations and reference" +description: "Connect supported agent harnesses, SDKs, CLIs, and the HTTP API." icon: "braces" --- בחר את האינטגרציה הקרובה ביותר למקום שבו הסוכן שלך כבר פועל. - - התקן hooks עבור CLIs נתמכים של סוכנים מקודדים וקודמים. + + התקן hooks עבור CLIs של coding ו-autonomous agents נתמכים. - - סדר LangGraph, CrewAI, LlamaIndex, Pydantic AI, או סוכן מותאם אישית. + + Instrument LangGraph, CrewAI, LlamaIndex, Pydantic AI, או סוכן מותאם אישית. - תצורה, קטלוג האירועים, כללי מתאם, והעברה. + Configuration, the event catalog, correlation rules, and delivery. - - סקור פרויקטים מקומיים, סשנים, פעילות מדיניות, וביקורות עצמאיות. + + בדוק פרויקטים מקומיים, sessions, policy activity, ו-audits offline. - קבע תצורה של כיבוד מקומי, hooks, מדיניויות, ביקורות, העברה, וסטטוס מכונה. + הגדר local capture, hooks, policies, audits, delivery, ו-machine state. - שאל וניהול סשנים בענן, ביקורות, בעיות, התראות, מפתחות, משתמשים והגדרות. + שאל וניהול Cloud sessions, audits, issues, alerts, keys, users, ו-settings. - דרג סשנים מלאים או לא פעילים עם שירות FastAPI. + דרג sessions שלמות או לא פעילות עם שירות FastAPI. - - תן וביקורת החלטות ספציפיות לזרימת עבודה של allow, instruct, ו-deny. + + כתוב ובדוק החלטות allow, instruct, ו-deny ספציפיות לflow עבודה. - פרוס את מישור הבקרה של Cloud בקלסטר Kubernetes שמנוהל על ידי הלקוח. + פרוס את Cloud control plane על cluster Kubernetes מנוהל על ידי לקוח. -ההפניה [HTTP API](/he/reference/http-api) שנוצרה מכסה את משטח `/v1` הציבורי. עמודים שנכתבו ביד מסבירים זרימות עבודה החוצות נקודות קצה מרובות או משתמשות בממשקי ניהול מחוץ למשטח הציבורי הזה. +ה-[HTTP API reference](/he/reference/http-api) שנוצר מכסה את הפני השטח הציבורי `/v1`. עמודים כתובים ביד מסבירים workflows שפורשים על פני multiple endpoints או משתמשים בממשקי ניהול מחוץ לפני השטח הציבורי הזה. -## חבר סוכן וודא נתונים +## חבר סוכן ואמת נתונים - - 1. פתח **Administration → Keys**, צור מפתח עם `events:add` ו-`policies:pull`, והעתק את הסוד. - 2. קבע תצורה של האינטגרציה באמצעות העמוד המתאים למעלה. - 3. פתח **Observe → Events** כדי לאשר שאירועים מגיעים, ולאחר מכן **Observe → Sessions** כדי לאשר שהם יוצרים הפעלות מלאות. - 4. סנן לסביבת האינטגרציה ובדוק סשן אחד כדי להבחין בשדות המודל, הכלי, השגיאה והמדיניות הדרושים לביקורות. + + 1. פתח **Administration → Keys**, צור key עם `events:add` ו-`policies:pull`, והעתק את הסוד. + 2. הגדר את האינטגרציה באמצעות העמוד המתאים למעלה. + 3. פתח **Observe → Events** כדי לאשר שאירועים מגיעים, ואז **Observe → Sessions** כדי לאשר שהם יוצרים ריצות שלמות. + 4. סנן לסביבה של האינטגרציה והבדוק session אחת עבור השדות model, tool, error, ו-policy הנדרשים על ידי audits. - התחל עם מגירת המפתחות. ההרשאות שנבחרו קובעות אם המכונה יכולה לשלוח אירועים וקבל מדיניויות הנוהלות בענן. + התחל עם תא ה-keys. ההרשאות שנבחרו קובעות אם המכונה יכולה לשלוח אירועים ולקבל policies מנוהלות בענן. - ![מגירת המפתח החדש של ה-API המשמשת להענקת הרשאות בליעת אירועים והעברת מדיניות.](/images/dashboard/key-create.png) + ![The new API key drawer used to grant event ingestion and policy delivery permissions.](/images/dashboard/key-create.png) - לאחר חיבור האינטגרציה, השתמש ברשימת הסשנים כדי לאשר שהאירועים שלה מקובצים להפעלות מלאות בסביבה הצפויה. + לאחר חיבור האינטגרציה, השתמש ברשימת Sessions כדי לאשר שהאירועים שלה מקובצים לריצות שלמות בסביבה הצפויה. - ![רשימת הסשנים המשמשת לאימות שאינטגרציה שחוברה לאחרונה מדווחת על הפעלות סוכנים מלאות.](/images/dashboard/sessions-list.png) + ![The Sessions list used to verify that a newly connected integration is reporting complete agent runs.](/images/dashboard/sessions-list.png) - פתח את אחד מהסשנים הללו לפני שאתה מיישם את האינטגרציה; העקבות צריכה להכיל את המודל, הכלי, השגיאה וראיות המדיניות שהביקורות שלך צריכות. + פתח אחת מ-sessions הללו לפני שאתה שוקל את האינטגרציה כמושלמת; ה-trace צריך להכיל את ה-evidence של model, tool, error, ו-policy שה-audits שלך צריכים. - צור מפתח מכונה, חבר את ה-Failproof daemon, וודא את הסשן הראשון. + צור machine key, ואז קרא את הסוד שהוא מדפיס לשל. `read -s` לוקח אותו בהנחיה שלא משדרת, כך שהוא לעולם לא מופיע בפקודה או בהיסטוריית shell: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + חבר את ה-Failproof daemon ואמת את ה-session הראשון: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - השתמש ב-`fp --json sessions ...` כאשר כלי אחרת תצרוך את התוצאה. דגלים גלובליים כגון `--json`, `--org`, ו-`--base-url` חייבים להיות לפני הפקודה. + השתמש ב-`fp --json sessions ...` כאשר כלי אחר יצרוך את התוצאה. דגלים גלובליים כגון `--json`, `--org`, ו-`--base-url` חייבים להיות לפני הפקודה. - ראה את [Failproof AI CLI reference](/he/reference/failproof-cli) לפקודות מקומיות ו-[Failproof Cloud CLI reference](/he/reference/cloud-cli#cli-commands) עבור פקודות `fp`. + ראה את ה-[Failproof AI CLI reference](/he/reference/failproof-cli) לפקודות מקומיות וה-[Failproof Cloud CLI reference](/he/reference/cloud-cli#cli-commands) לפקודות `fp`. \ No newline at end of file diff --git a/docs/he/reference/policy-sdk.mdx b/docs/he/reference/policy-sdk.mdx index 68fdc262..6ceda3fd 100644 --- a/docs/he/reference/policy-sdk.mdx +++ b/docs/he/reference/policy-sdk.mdx @@ -1,29 +1,29 @@ --- title: "מדיניות מותאמות" -description: "כתוב, בדוק ופרוס מדיניות JavaScript או TypeScript לכשלים ספציפיים לסוכנים שלך." +description: "כתוב, בדוק והפץ מדיניות JavaScript או TypeScript לכשלים ספציפיים לסוכנים שלך." icon: "shield-plus" --- -מדיניות מותאמת הופכת דפוס כשל מהעקבות או הביקורות שלך להחלטה שרצה כשהסוכן עובד. מדיניות יכולה לאפשר פעולה, לתת הנחיות לסוכן, או לשלול את הפעולה לפני שהיא גורמת לעוד תקרית. +מדיניות מותאמת הופכת דפוס כשל מעקיפות או ביקורות שלך להחלטה המופעלת בזמן שהסוכן עובד. מדיניות יכולה לאפשר פעולה, לתת הדרכה לסוכן, או לשלול את הפעולה לפני שהיא גורמת לתקادם נוסף. -השתמש במדיניות מותאמת כשההתנהגות תלויה בכלים, בנתיבים, בפקודות, בסביבות או בכללי תפעול שלך. בדוק קודם את [קטלוג המדיניות המובנה](/he/policies/builtin-catalog) כדי שלא תשחזור בקרה קיימת. +השתמש במדיניות מותאמת כאשר ההתנהגות תלויה בכלים שלך, בנתיבים, בפקודות, בסביבות או בכללי הפעולה שלך. בדוק קודם את [חבילת המדיניות של Failproof AI](/he/policies/packs) כדי שלא תיצור בחזרה בקרה קיימת. ## כתוב מדיניות מותאמת - 1. עבור אל **Admin → policy editor**, בחר **New policy**, ותאר את הכשל שברצונך למנוע. - 2. הוסף את קוד המדיניות, ולאחר מכן בדוק התאמות צפויות וללא התאמות בטוחות בעורך. פתור כל שגיאת אימות. - 3. שמור את הטיוטה ובחר **Publish version** כדי ליצור גרסה בלתי ניתנת לשינוי. - 4. עבור אל **Admin → enforcement**, פרוס את הגרסה למכונת בדיקה ב-**observe** מצב, ובדוק את ההחלטות שלה תחת **Observe → policy** לפני כפיית הביצוע. + 1. עבור אל **Admin → policy editor**, בחר **New policy**, ותאר את הכשל שאתה רוצה למנוע. + 2. הוסף את מקור המדיניות, ואז בדוק התאמות צפויות ואי-התאמות בטוחות בעורך. פתור כל שגיאת אימות. + 3. שמור את הטיוטה ובחר **Publish version** כדי ליצור גרסה בלתי משתנה. + 4. עבור אל **Admin → enforcement**, הפץ את הגרסה למכונת בדיקה במצב **observe**, וודא את ההחלטות שלה תחת **Observe → policy** לפני שאתה אוכף אותה. - ![עורך המדיניות המשמש לכתיבה ופרסום של מדיניות מותאמת.](/images/dashboard/policy-editor.png) + ![עורך המדיניות המשמש לכתיבה ופרסום מדיניות מותאמת.](/images/dashboard/policy-editor.png) 1. צור `.failproofai/policies/checkout-policies.ts`. שם הקובץ חייב להסתיים ב-`policies.js`, `policies.mjs`, או `policies.ts`. 2. הרשם אחת או יותר מדיניות עם `customPolicies.add()`. 3. אמת והתקן את הקובץ עם `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. - 4. הפעל פעולה אחת תואמת ופעולה בטוחה אחת. הריץ `failproofai policies`, ולאחר מכן בחן את ההחלטות המיוחסות תחת **Observe → policy**. + 4. הפעל פעולה אחת תואמת ופעולה בטוחה אחת. הפעל `failproofai policies`, ואז בדוק את ההחלטות שיוחסו תחת **Observe → policy**. @@ -55,20 +55,20 @@ customPolicies.add({ }); ``` -מדיניות טובה צר מספיק כדי להסביר במשפט אחד. התאם את הפעולה הניתנת לתצפית—לא הכוונה שאתה מקווה שהסוכן היה—והחזר `allow()` ברגע שהכלל לא חל. +מדיניות טובה היא צרה מספיק כדי להסביר במשפט אחד. התאם את הפעולה הנצפית — לא הכוונה שאתה מקווה שהסוכן היה לה — וחזור `allow()` ברגע שהכלל לא חל. ## בחר החלטה -| עוזר | תוצאה | השתמש בה כאשר | +| עוזר | תוצאה | השתמש בו כאשר | | --- | --- | --- | -| `allow(reason?)` | הפעולה ממשיכה. | המדיניות לא חלה או הפעולה בטוחה. | -| `instruct(reason)` | הפעולה ממשיכה עם הנחיות בעבור מקום שבו רתיעה תומכת בכך. | אתה רוצה לכוונן את הסוכן לכיוון גישה טובה יותר ללא כפיית משתנה. | -| `deny(reason)` | הפעולה חסומה כאשר האירוע ורתיעה תומכים בחסימה. | הפעולה לא חייבת להמשיך. | +| `allow(reason?)` | הפעולה נמשכת. | המדיניות לא חלה או הפעולה בטוחה. | +| `instruct(reason)` | הפעולה נמשכת עם הדרכה כאשר הקערה תומכת בכך. | אתה רוצה להנחות את הסוכן לגישה טובה יותר מבלי לאכוף אינוריאנט. | +| `deny(reason)` | הפעולה חסומה כאשר האירוע והקערה תומכים בחסימה. | הפעולה לא חייבת להמשיך. | -כתוב את ההנמקה לסוכן שחייב להתאוחד. הסבר מה גילוי וממה עליו לעשות במקום זאת. +כתוב את הסיבה לסוכן שחייב להחזיר. הסבר מה התגלה וקולט הוא צריך לעשות במקום זאת. - אל תשתמש ב-`instruct()` לגבול בטיחות. הספקת הנחיות משתנה לפי רתיעת סוכן. השתמש ב-`deny()` כאשר יש למנוע את הפעולה. + אל תשתמש ב-`instruct()` לגבול בטיחות. מסירת הדרכה משתנה לפי קערת הסוכן. השתמש ב-`deny()` כאשר יש לחסום את הפעולה. ## אובייקט מדיניות @@ -84,32 +84,32 @@ customPolicies.add({ | שדה | נדרש | תיאור | | --- | --- | --- | -| `name` | כן | מזהה יציב למדיניות. שמור שמות ייחודיים בקבצים. | -| `description` | לא | מטרה קריאה לאדם שמוצגת בתיעודי מדיניות והחלטות. | -| `match.events` | לא | סוגי אירועים שמכינים את המדיניות. השמטת `match` משדרת אותה לכל אירוע זמין. | -| `fn` | כן | פונקציה סינכרונית או אסינכרונית המחזירה תוצאת `allow`, `instruct`, או `deny`. | +| `name` | כן | מזהה יציב של המדיניות. שמור על שמות ייחודיים בקבצים. | +| `description` | לא | מטרה קריאה לאדם המוצגת בקבילות מדיניות והחלטות. | +| `match.events` | לא | סוגי אירועים המזמנים את המדיניות. השמטת `match` מזמנת אותה לכל אירוע זמין. | +| `fn` | כן | פונקציה סינכרונית או אסינכרונית המחזירה תוצאה `allow`, `instruct`, או `deny`. | -סנן כלים בתוך `fn`. `match.toolNames` אינו חלק מסוג המדיניות המותאמת הציבורי. +סנן כלים בתוך `fn`. `match.toolNames` אינו חלק מסוג המדיניות המותאם הציבורי. -## הקשר מדיניות +## הקשר המדיניות כל מדיניות מקבלת `PolicyContext`. | שדה | סוג | מה הוא מכיל | | --- | --- | --- | -| `eventType` | `HookEventType` | אירוע מנורמל כרגע להערכה. | +| `eventType` | `HookEventType` | אירוע מנורמל שמוערך כרגע. | | `toolName` | `string \| undefined` | שם כלי קנוני כגון `Bash`, `Read`, `Write`, או `Edit`. | -| `toolInput` | `Record \| undefined` | קלט קנוני לקריאת כלים הנוכחית. | +| `toolInput` | `Record \| undefined` | קלט קנוני לקריאת הכלי הנוכחית. | | `payload` | `Record` | מטען אירוע מנורמל מלא. | -| `session` | `SessionMetadata \| undefined` | מזהה הפעלה, ספריית עבודה, נתיב שלוג, מצב הרשאה, ומטא-נתוני רתיעה כאשר זמין. | -| `cli` | `string \| undefined` | סוכן רתיעה מקור, כגון `claude`, `codex`, או `cursor`. | -| `params` | `Record` | פרמטרי מדיניות מובנים. מדיניות מותאמת כרגע מקבלת אובייקט ריק. | +| `session` | `SessionMetadata \| undefined` | מזהה הפעלה, ספריית עבודה, נתיב תמליל, מצב הרשאה, ומטא-נתונים של קערה כאשר זמין. | +| `cli` | `string \| undefined` | קערת סוכן מקור, כגון `claude`, `codex`, או `cursor`. | +| `params` | `Record` | פרמטרי מדיניות מובנים. מדיניות מותאמת מקבלת כרגע אובייקט ריק. | -התייחס לכל ערך אופציונלי כאופציונלי באמת. גרסאות סוכן וסוגי אירועים לא כולם מספקים את אותם שדות. +התייחס לכל ערך אופציוני כאל בעצם אופציוני. גרסאות סוכן וסוגי אירועים לא כולם מספקים את אותם שדות. -### קלט כלים נפוץ +### קלטי כלים נפוצים -Failproof AI מנרמל כלים נפוצים על פני רתיעות נתמכות כדי שמדיניות יכולה בדרך כלל להשתמש בצורת קלט אחת. +Failproof AI מנורמל כלים נפוצים בין קערות תומכות כך שמדיניות יכולה בדרך כלל להשתמש בצורת קלט אחת. | כלי | שדות נפוצים | | --- | --- | @@ -119,7 +119,7 @@ Failproof AI מנרמל כלים נפוצים על פני רתיעות נתמכ | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | -השתמש בהיתוך הגנתי כי ערכי קלט כלים מוקלדים כ-`unknown`: +השתמש בכפיית הגנה כי ערכי קלט של כלים מוקלדים כ-`unknown`: ```ts const command = String(ctx.toolInput?.command ?? ""); @@ -128,19 +128,19 @@ const filePath = String(ctx.toolInput?.file_path ?? ""); ## בחר את האירוע -| אירוע | כאשר הוא רץ | שימוש טיפוסי | +| אירוע | כאשר הוא פועל | שימוש טיפוסי | | --- | --- | --- | -| `PreToolUse` | לפני ביצוע כלי. | חסום או הנחה פקודות, כתיבה, קריאה ופעולות חיצוניות. | -| `PostToolUse` | לאחר שכלי חוזר. | בדוק תוצאות לפני שהן מגיעות לסוכן. שלילה חוסמת את התוצאה כולה; היא לא מחסלת שדות נבחרים. | +| `PreToolUse` | לפני ביצוע כלי. | חסום או הנחה פקודות, כתיבה, קריאה, ופעולות חיצוניות. | +| `PostToolUse` | אחרי שכלי חוזר. | בדוק תוצאות לפני שהן מגיעות לסוכן. שלל חוסם את כל התוצאה; זה לא מחליש שדות נבחרים. | | `PermissionRequest` | כאשר הסוכן מבקש הרשאה. | החל כללי הרשאה ספציפיים לארגון. | -| `UserPromptSubmit` | לפני המשך הנושא שהוגש. | דחה הנחיות אסורות או הוסף הנחיות זרימת עבודה. | -| `Stop` | כאשר הסוכן מנסה לסיים. | דרוש תנאי השלמה בר הישג, כגון שלב אימות מקומי. | -| `SubagentStop` | כאשר סוכן משנה מנסה לסיים. | שער עבודה מופקדת לפני שחוזרת להורה. | -| `SessionStart` / `SessionEnd` | בגבולות הפעלה. | רשום או בדוק מצב ברמת ההפעלה. | +| `UserPromptSubmit` | לפני שהנושאת המוגשת ממשיכה. | דחה הנחיות אסורות או הוסף הדרכה זרימת עבודה. | +| `Stop` | כאשר הסוכן מנסה להסיים. | דרוש תנאי השלמה הנגיע, כגון שלב אימות מקומי. | +| `SubagentStop` | כאשר תת-סוכן מנסה להסיים. | שער עבודה משוויתה לפני שהוא חוזר להורה. | +| `SessionStart` / `SessionEnd` | בגבולות הפעלה. | רשום או בדוק מצב ברמת הפעלה. | -זמינות אירוע והתנהגות חסימה תלויים ברתיעת סוכן. ראה [סוכן רתיעות](/he/reference/harnesses) לפני שאתה מסתמך על אירוע בפני קרקע מעורבבת. +זמינות אירוע וחסימת התנהגות תלויים בקערת הסוכן. ראה [קערות סוכן](/he/reference/harnesses) לפני שתסמך על אירוע בצי מעורב. - + `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch`, ו-`Setup`. @@ -166,7 +166,7 @@ customPolicies.add({ }); ``` -### תן הנחיה ללא חסימה +### תן הדרכה לא חוסמת ```ts import { customPolicies, allow, instruct } from "failproofai"; @@ -215,30 +215,30 @@ customPolicies.add({ ``` - אירוע `Stop` שלול יכול לגרום לסוכן לנסות שוב. שער רק בתנאי שהסוכן יכול להשביח בסביבה הנוכחית, וקשור כל קריאה תהליך או רשת. + אירוע `Stop` שלול יכול להפוך את הסוכן לנסיון חוזר. שער רק בתנאי שהסוכן יכול להסתפק בסביבה הנוכחית, וכמוס כל קריאת תהליך משנה או רשת. ## טען קבצי מדיניות ### קבצי קונבנציה -קבצי קונבנציה טעונים באופן אוטומטי: +קבצי קונבנציה טוענים באופן אוטומטי: ```text /.failproofai/policies/security-policies.ts ~/.failproofai/policies/personal-policies.mjs ``` -- ספריות מדיניות פרויקט והמשתמש טעונות שתיהן. -- קבצים טעונים בצורה אלפביתית בכל ספרייה. +- ספריות מדיניות פרויקט וגם משתמש טוענות. +- קבצים טוענים בתרתיב אלפביתי בתוך כל ספרייה. - קובץ חייב להסתיים ב-`policies.js`, `policies.mjs`, או `policies.ts`. -- קריאות `customPolicies.add()` מרובות בקובץ אחד נתמכות. -- יבואים יחסיים מודולים מקומיים נתמכים. -- מדיניות פרויקט יכולה להיות מתוחלת כך שאותם כללים עוקבים את המאגר. +- מספר קריאות `customPolicies.add()` בקובץ אחד נתמכות. +- יבוא יחסי מודולים מקומיים נתמכים. +- מדיניות פרויקט יכולה להיות מחויבת כך שאותם כללים עוקבים את המאגר. -### קבצים מפורשים +### קבצים ברורים -השתמש בנתיבים מפורשים כאשר אימות או תצורה צריכה לתיבת שם הקובץ הכניסה ישירות: +השתמש בנתיבים מפורשים כאשר אימות או תצורה צריכים לתאר את קובץ הכניסה ישירות: ```bash failproofai policies --install \ @@ -247,11 +247,11 @@ failproofai policies --install \ --scope project ``` -קבצים מפורשים טעונים קודם, ואחריהם קבצי קונבנציה פרויקט ואחר כך קבצי קונבנציה משתמש. קובץ גילוי דרך שני הנתיבים טעון פעם אחת. +קבצים מפורשים טוענים ראשונים, ואחריהם קבצי קונבנציה פרויקט ואחריהם קבצי קונבנציה משתמש. קובץ המוגלה דרך שני הנתיבים טוען פעם אחת. -## אמת ובדוק +## אימות ובדיקה -אימות מבצע את המודול דרך המעמיס הייצור ומאשר שהוא רושם לפחות מדיניות אחת. +אימות מבצע את המודול דרך מטעין הייצור ומאשר שהוא רושם לפחות מדיניות אחת. ```bash failproofai policies --install \ @@ -260,44 +260,44 @@ failproofai policies --install \ failproofai policies ``` -אימות תופס קבצים חסרים, שגיאות תחביר, יבואים לא מחוזרים, חריגים ברמה עליונה וקבצי המתנה לטעינה מודול. זה לא מוכיח שלוגיקת ההתאמה שלך נכונה. +אימות תופס קבצים חסרים, שגיאות תחביר, ייבוא לא פתור, חריגים ברמה עליונה, וזמנים פגועים בטעינת מודול. זה לא מוכיח שהמנטק התאמה שלך נכון. -בדוק לפחות את המקרים הבאים: +בדוק לפחות במקרים אלה: -- פעולה אחת שחייבת להתאים ולהפיק את הנמקת המדיניות המתוכננת. -- פעולה קרובה בטוחה אחת שחייבת להחזיר `allow()`. -- שדות כלים חסרים או מעוותים. -- תחביר פקודה חלופי, נתיבים, ציטוטים, אותיות גדולות ורווח. -- תהליך משנה או תלות רשת בלתי זמינה. +- פעולה אחת שחייבת להתאים ולהפיק את סיבת המדיניות המיועדת. +- פעולה קרובה אך בטוחה אחת שחייבת להחזיר `allow()`. +- שדות כלים חסרים או שגויים. +- תחביר פקודה חלופי, נתיבים, ציטוט, רישור, ורווח. +- תת-תהליך או תלות רשת לא זמינים. -ייחס את התוצאה למדיניות המותאמת שלך תחת **Observe → policy**. בדיקה חסומה אינה מספקת אם מדיניות מובנית אחרת קבעה את ההחלטה. +שייך את התוצאה למדיניות המותאמת שלך תחת **Observe → policy**. בדיקה חסומה אינה מספיקה אם מדיניות מובנית שונה ייצרה את ההחלטה. ## התנהגות זמן ריצה - מדיניות מובנית מעריכה לפני מדיניות מותאמת. -- `deny` ראשון עוצר הערכה מדיניות נוספת. -- תוצאות `instruct` מרובות יכולות להיות משולבות כאשר אין מדיניות דוחה את האירוע. -- לפונקציה מדיניות יש הקצאת ביצוע של 10 שניות. -- חריג זרוק או קבלת זמן מחובר וממטפל כ-`allow()`. -- קובץ קונבנציה שלא ניתן לטעון דלוק; קבצים מותאמים אחרים ומדיניות מובנית להמשיך. -- טעינת מודול ברמה עליונה יש גם הקצאת 10 שניות. -- מצב תצפית ענן מריץ את המדיניות אך רושם החלטה שאינה ללא כפיית הביצוע. +- השלל הראשון עוצר הערכה נוספת של מדיניות. +- תוצאות `instruct` מרובות יכולות להיות משולבות כאשר אין מדיניות שלוללת את האירוע. +- לפונקציית מדיניות יש קו זמן ביצוע של 10 שניות. +- חריג שהוטל או זמן עבירה מתועדים ומטופלים כ-`allow()`. +- קובץ קונבנציה שלא בטעינה דלג; קבצים מותאמים וגם מדיניות מובנית אחרים ממשיכים. +- טעינת מודול ברמה עליונה כללה קו זמן של 10 שניות. +- מצב observe בענן מפעיל את המדיניות אך רושם החלטה שלא מאפשרת מבלי אכוף אותה. -שמור מודולי מדיניות דטרמיניסטי ומהיר. הימנע מקריאות רשת ברמה עליונה או הפעלה של שרת. עבודה קשורה בתוך `fn`, תופסת כשלים בתלות, ובחר בכוונה הייתה כשל זה צריך לאפשר או לשלול את הפעולה. +שמור על מודולי מדיניות דטרמיניסטיים ומהירים. הימנע מקריאות רשת ברמה עליונה או הפעלת שרת. עבודה גבולה בתוך `fn`, תפס כשלי תלות, ובחר בכוונה אם כשל זה צריך לאפשר או לשלול את הפעולה. -## ייצוא API +## ייצאות API | ייצוא | מטרה | | --- | --- | -| `customPolicies.add(policy)` | רשום מדיניות מותאמת בעת טעינת המודול. | +| `customPolicies.add(policy)` | הרשם מדיניות מותאמת כאשר המודול טוען. | | `allow(reason?)` | אפשר את הפעולה. | -| `instruct(reason)` | אפשר את הפעולה וספק הנחיות בעבור מקום שנתמך. | -| `deny(reason)` | חסום את הפעולה בעבור מקום נתמך. | -| `getCustomHooks()` | החזר את המדיניות כרגע רשומה בתיעודי המודול. | -| `clearCustomHooks()` | נקה את התיעודי, בעיקר לבדיקות וטוענים. | +| `instruct(reason)` | אפשר את הפעולה וספק הדרכה כאשר נתמך. | +| `deny(reason)` | חסום את הפעולה כאשר נתמך. | +| `getCustomHooks()` | חזור את המדיניות כרגע רשומה במודול רישום. | +| `clearCustomHooks()` | נקה את הרישום, בעיקר לבדיקות וטוענים. | -TypeScript ייצוא `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision`, ו-`PolicyFunction`. +TypeScript ייצא `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision`, ו-`PolicyFunction`. - - פרסם גרסה, פרוס אותה במצב תצפית, בדוק החלטות, ועבור לכפיית הביצוע. + + פרסם גרסה, הפץ אותה במצב observe, ודא החלטות, והעבר לאכיפה. \ No newline at end of file diff --git a/docs/he/sessions/evaluations.mdx b/docs/he/sessions/evaluations.mdx index 2b37f70d..4c38acdf 100644 --- a/docs/he/sessions/evaluations.mdx +++ b/docs/he/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "הערכות מקוונות" -description: "דירוג הפעלות חיות ושהסתיימו לאיכות, ציות, עלות ותופעת השהיה." +title: "קריאת תוצאות הערכה" +description: "תרשימי ניקוד הערכה לאורך זמן, השוואת סוכנים וסביבות, הבנת הסיבה לניקוד נמוך של סשן, וייעוץ עם העוזר." icon: "gauge" --- -הערכות מקוונות מיישמות שיקול דעת עקבי לשיחות של סוכנים. השתמש בהן לאותות שצריך למדוד ברציפות ולא רק בזמן ביקורת. +תוצאות מכל הערכה, המתארחות או מהעובד שלך, נוחתות באותם המקומות. -## סקור איכות הערכה +## השוואת ניקוד לאורך זמן - 1. עבור אל **Observe → Evaluations**. - 2. הוסף סדרה ובחר את הסוכן, הסביבה, ציון ההערכה, הנתון וההעקומה. - 3. הוסף סדרות להשוואת סביבות, סוכנים או מפתחות ציון. - 4. בחר תוצאה כדי לפתוח הפעלות תואמות או שתף את התצוגה המסוננת. השתמש ב-**Observe → Metrics** לערכי השהיה, אסימונים, עלות וערכי גודל אחרים. + עבור אל **Observe → evaluations**. - ![לוח מחוונים איכות המציג ציוני הערכה ממוצעים והטרנדים לאורך זמן.](/images/dashboard/dashboard-quality.png) + - **Recent runs** מפרט כל הערכה כשהיא מגיעה: האם היא הגיעה מהמערכת המתארחת (**managed**) או מהמעריך שלך (**customer**), הסוכן והסשן, ההערכה וגרסתה, המצב שלה, והניקוד או המדדים שלה. + - **Score over time** משרטט את מה שאתה מבקש. בחר **add series** ובחר סוכן, סביבה, הערכה וסטטיסטיקה: avg, min, max, p50, p75, p90, p95, p99, stddev, או mode. כל סדרה היא שורה אחת; תן לה **curve** משלה כדי לשרטט אותה על תרשים נפרד. - פתח הפעלה מהדקירה כדי לבדוק את הנימוקים לכל ציון: + ![עמוד ההערכות: הרצות אחרונות שתויגו customer, תרשים ניקוד לאורך זמן עם קווי הפניה ב-0.5 ו-0.8, וסדרה אחת המחשבת average של finished_clean בכל הסוכנים והסביבות.](/images/dashboard/evaluations-chart.png) - ![תצוגת פרטי הפעלה המציגה ציוני הערכה ונימוקים ליד העקבות המלאים.](/images/dashboard/session-detail.png) + טווח זמן אחד וגודל סל אחד חלים על כל סדרה. סל עדין מוצא תקרית; סל גס מציג מגמה, ויכול להסתיר את הקפיצות שאתה מחפש. דלי שבו לא ניקד כלום הוא פער בקו, לעולם לא אפס, וקווי הפניה מסמנים 0.5 ו-0.8. + + כל חלק בתצוגה חי ב-URL: **share** מעתיק אותו, וכל מי שפותח אותו רואה בדיוק את ההשוואה שבנית. ```bash @@ -28,25 +28,29 @@ icon: "gauge" fp evals --score helpfulness:0.8.. --since 7d ``` - הוסף `--json` גלובלי לפני `evals` לאוטומציה, לדוגמה `fp --json evals --aggregate --env production`. + הוסף `--json` גלובלי לפני `evals` לאוטומציה, למשל `fp --json evals --aggregate --env production`. -מעריך מקבל את זהות ההפעלה, הסביבה, חותמות זמן ואירועים מסודרים. הוא יכול להחזיר מפתחות ציון מספריים עם נימוקים אופציונליים וסיכום. מעריכים בעלי ריצה ארוכה יכולים להחזיר עבודה תלויה ולהיבדק מאוחר יותר. +שרטט **avg** ו-**p90** לאותה הערכה כדי לראות האם ממוצע טוב מסתיר זנב גרוע, או אותה הערכה לשני סוכנים, או לייצור וstaging, כדי להשוות ביניהם על ציר אחד. עלויות, latencies וספירות tokens, שנושאות יחידות, משרטטים תחת **Observe → metrics**, תרשים אחד ליחידה. + +## הבנת הסיבה לניקוד נמוך של סשן + +פתח סשן מ-**Observe → sessions**; הגריד מכיל את הניקוד של כל סשן מסנן לפי טווח ניקוד. הרכבת הימנית של הסשן מתחילה בסיכום ההערכה, ואז סרגל לכל ניקוד עם נימוק המעריך מתחתיו. + +![תצוגת פרטי סשן המציגה ניקודי הערכה ונימוק לצד הטrace המלא.](/images/dashboard/session-detail.png) + +## ייעוץ עם העוזר + +שאל על נתוני הערכה באנגלית פשוטה: "tell me about some of the recent evaluations", או אילו ניקודי סוכנים בהחלקה. ה-[assistant](/he/sessions/assistant) קורא ומנתח את התוצאות וענה בטבלאות שאתה יכול להמשיך איתן, ושאלה ראויה לשמירה יכולה להפוך ל-[query](/he/sessions/queries) או ל-[dashboard](/he/sessions/dashboards). -## יעדי הערכה טובים +![עמוד ההערכות לצד העוזר, שעונה על "tell me about some of the recent evaluations" עם סיכום של סך הכל, סטטוסים וניקודים.](/images/dashboard/evaluations-assistant.png) -- השלמת משימה או נכונות -- עוגנות וסיכון הזיה -- בחירת כלים ויעילות כלים -- ציות למדיניות או תהליך -- תקציבי עלות והשהיה -- הסלמה אנושית נדרשת +## צפייה ופעולה -## מציון לתגובה +- **Dashboards**, תחת **Analyze → dashboards**, משנים את הניקודים שאתה מתוכן, לכל סוכן וסביבה, לכל הארגון. -הצג ציונים בלוחות מחוונים כדי לעקוב אחר טרנדים. צור התראות לסף או תנאים מורכבים. כאשר ציון פוחת על פני אוכלוסייה, הפעל ביקורת כדי לחקור את הסיבה; כאשר הסיבה היא פעולה הניתנת לחזרה, פרוס מדיניות. + ![לוח איכות המציג ממוצע ניקודי הערכה ומגמות לאורך זמן.](/images/dashboard/dashboard-quality.png) - - הטמע הערכה סינכרונית או אסינכרונית עם ה-SDK של מעריך Python. - \ No newline at end of file +- **Alerts** מודיעים לך כאשר ניקוד חוצה סף. ראה [alerts](/he/audits/alerts). +- כאשר ניקוד מורד בפני סשנים רבים, [הרץ audit](/he/audits/run) כדי לגלות למה; כאשר הסיבה היא פעולה ניתנת לחזרה, [כתוב policy](/he/policies/editor). \ No newline at end of file diff --git a/docs/he/start/integrations/custom-agents.mdx b/docs/he/start/integrations/custom-agents.mdx index e58fedde..a7c18715 100644 --- a/docs/he/start/integrations/custom-agents.mdx +++ b/docs/he/start/integrations/custom-agents.mdx @@ -1,14 +1,13 @@ --- ---- -title: "סוכנים מותאמים" -sidebarTitle: "סוכנים מותאמים" -description: "כלאו סוכן שכתבת בעצמך, או פריימוורק ללא מתאם." +title: "סוכנים מותאמים אישית" +sidebarTitle: "סוכנים מותאמים אישית" +description: "הוסף מעקב לסוכן שכתבת בעצמך, או לפריימוורק ללא מתאם." icon: "code" --- -עבור סוכן שכתבת בעצמך, או פריימוורק שאין ל-Failproof AI מתאם בשבילו. אין שום דבר להכין: אתה פולט את האירועים. +לסוכן שכתבת בעצמך, או לפריימוורק של Failproof AI אין לו מתאם. אין כלום להוסיף: אתה פולט את האירועים. -זו אותה API שמתאמי הפריימוורק הארבעה קוראים בעומק. הם טבלאות תרגום עליה. +זה אותו API שארבעת מתאמי הפריימוורק קוראים תחתיו. הם טבלאות תרגום עליו. ## התקנה @@ -16,42 +15,42 @@ icon: "code" pip install failproofai-sdk ``` -ללא תוספות, וללא תלויות. +ללא תוספים, וללא תלויות. -## הכנה +## הוספת מעקב ```python import failproofai_sdk failproofai_sdk.configure(environment="production") -with failproofai_sdk.session(): # one run - with failproofai_sdk.agent("planner"): # one unit of work +with failproofai_sdk.session(): # הרצה אחת + with failproofai_sdk.agent("planner"): # יחידת עבודה אחת with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # one tool call + t.output = search(q) # קריאת כלי אחת ``` -קרא את זה מלמעלה למטה וזה אומר מה זה אומר: +קרא זאת מלמעלה למטה והיא אומרת מה זה אומר: -| עטוף בו | כדי לומר | +| עטוף אותו ב | כדי לומר | | --- | --- | -| `session()` | אירועים אלה שייכים לאותו ריצה | +| `session()` | האירועים הללו שייכים לאותה הרצה | | `agent()` | משהו עושה עבודה — תן לו שם שהיית מזהה ברשימה | -| `tool_call()` | זה כלי אחד, והנה מה שהוא החזיר | +| `tool_call()` | זהו כלי אחד, וזה מה שהוא החזיר | -ומה כל אחד בעצם פולט: +ומה כל אחד מהם למעשה פולט: | טווח | פולט | מטרה | | --- | --- | --- | -| `session()` | כלום | קושר מזהה סשן, קיבוץ ריצה אחת | -| `agent()` | `agent_start`, `agent_end` | מסוגריים יחידת עבודה | -| `tool_call()` | `tool_use`, `tool_result` | מסוגריים כלי אחד ומודד אותו | +| `session()` | כלום | קושר מזהה session, ומקבץ הרצה אחת | +| `agent()` | `agent_start`, `agent_end` | תוחם יחידת עבודה | +| `tool_call()` | `tool_use`, `tool_result` | תוחם כלי אחד ומודד אותו | -הכל בפנים יכול להשמיט את `session_id` ו-`agent_id`. הטווחים קושרים זהות על משתני הקשר וכל קריאת אירוע קוראת אותה בחזרה, אז אתה לעולם לא מעביר ids דרך הפונקציות שלך. +הכל בתוך יכול להשמיט `session_id` ו-`agent_id`. הטווחים קושרים זהות על משתנות context ותוך כל קריאת event היא קוראת אותה חזרה, כך שאתה אף פעם לא מחליק מזהים דרך הפונקציות שלך. -שלושתם עובדים תחת `async with` כמו גם `with`. +כל השלושה עובדים תחת `async with` כמו גם תחת `with`. -קינון סוכנים בונה את העץ. `parent_id` וגובה מחושבים מהערום: +קינון סוכנים בונה את העץ. `parent_id` והעמוק מחושבים מהערימה: ```python with failproofai_sdk.session(): @@ -60,22 +59,22 @@ with failproofai_sdk.session(): ... ``` -## איך טווח נסגר +## כיצד טווח סוגר -`agent()` מטפל בחריגים בשבילך: +`agent()` מטפל בחריגות עבורך: | מה קרה | אירועים | תוצאה | | --- | --- | --- | -| כלום לא הוצא | `agent_end` | `success` | -| `Exception` | `error`, אז `agent_end` | `failed` | -| `KeyboardInterrupt`, `SystemExit` | `error`, אז `agent_end` | `failed` | +| כלום לא הוגבה | `agent_end` | `success` | +| `Exception` | `error`, ואז `agent_end` | `failed` | +| `KeyboardInterrupt`, `SystemExit` | `error`, ואז `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | `agent_end` בלבד | `cancelled` | -השגיאה מופצת לפני `agent_end`, כי לוח הבקרה סוגר את ה-span ב-`agent_end` וכל דבר אחרי זה מיוחס לכלום. ביטול זה לא כישלון, אז ריצות מבוטלות לא מעלמות את משטח השגיאות. החריג תמיד מועלה מחדש: טווח לעולם לא בולע. +השגיאה פלטת לפני `agent_end`, כי הדashboard סוגר את ה-span ב-`agent_end` וכל דבר אחרי זה מיוחס לכלום. ביטול אינו כשל, כך שהרצות מבולות לא מזוהמות על משטח השגיאות. החריגה תמיד מוגבה מחדש: טווח אף פעם לא בולע. ## שיטות האירוע -חמש עשרה שיטות בשש משפחות. רובן מגיעים בזוגות — אתה פולט את ה-opener, אז את ה-closer, וה-SDK מודד את ה-span ביניהם. +חמש עשרה שיטות בשש משפחות. רובן מגיעות בזוגות — אתה פולט את הפותח, ואז את הסוגר, והSDK מודד את ה-span ביניהם. | משפחה | פותח | סוגר | עצמאי | | --- | --- | --- | --- | @@ -83,12 +82,12 @@ with failproofai_sdk.session(): | | `agent_pause` | `agent_resume` | — | | **מודלים** | `model_request` | `model_response` | — | | **כלים** | `tool_use` | `tool_result` | — | -| **Hooks** | `hook_triggered` | `hook_completed` | — | -| **אנשים** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **וו (Hook)** | `hook_triggered` | `hook_completed` | — | +| **בני אדם** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | | **כשלים** | — | — | `error` | - העדף את הטווחים — `agent()` ו-`tool_call()` — איפה שהם מתאימים. הם מבטיחים את אירוע הסגירה גם כשהגוף מעלה. הגיע לשיטות אלו ישירות כשזרימת הבקרה שלך לא מקוננת, כמו קריאת מודל בתוך עוזר. + העדף את הטווחים — `agent()` ו-`tool_call()` — בכל מקום שהם מתאימים. הם מבטיחים את אירוע הסיום גם כאשר הגוף מגביל. פנה לשיטות אלה ישירות כאשר זרימת הבקרה שלך לא קינה, כמו קריאה למודל בתוך עוזר. @@ -120,12 +119,12 @@ failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1", input={"q" failproofai_sdk.event.tool_result(tool_name="search", tool_call_id="c1", output="...") ``` -```python Hooks +```python וו failproofai_sdk.event.hook_triggered(hook_name="retrieve", hook_id="h1", trigger_event="node") failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome="success") ``` -```python אנשים +```python בני אדם failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") @@ -142,23 +141,23 @@ failproofai_sdk.event.error( - **שתי משפחות האנשים מצביעות בכיוונים מנוגדים.** + **שתי משפחות בני אדם מצביעות בכיוונים מנוגדים.** | שיטות | משמעות | | --- | --- | - | `human_wait` / `human_input` | ה**סוכן ביקש מאדם** — שער אישור, שאלה מבהירה | + | `human_wait` / `human_input` | **הסוכן שאל אדם** — שער אישור, שאלה הבהרה | | `human_pause` / `human_interrupt` | **אדם פעל על הסוכן** — כפתור עצור, השהיית מפעיל | - אף פריימוורק לא משדר את הזוג השני, אז זה תמיד שלך לפליטה. + אף פריימוורק לא משדר את הזוג השני, כך שתמיד שלך להפליט. - **עבור `request_id` כאשר קריאות מודל פועלות בו-זמנית.** ללא זה, בקשות תגובות מתאימות בסדר הגעה לכל סוכן — וקריאות בו-זמנית מתאימות בצורה שגויה, וקובעות כל תגובה לבקשה השגויה. + **עבור `request_id` כאשר קריאות מודל פועלות במקביל.** בלעדיו, בקשות ותגובות מתזווגות בסדר הגעה לכל סוכן — וקריאות מקבילות מתזווגות בצורה שגויה, ומצרפות כל תגובה לבקשה הלא נכונה. ## דוגמה -לולאת קריאת כלים כנגד ה-OpenAI API, ללא מסגרת סוכן: +לולאת קריאת כלי כנגד ה-OpenAI API, ללא פריימוורק סוכנים: ```python import json @@ -172,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """One model call, bracketed by the pair.""" + """קריאה מודל אחת, תוחומה בזוג.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -205,52 +204,53 @@ with failproofai_sdk.session(): }) ``` -זה מייצר אותם שישה סוגי אירוע שמתאם היה נותן לך. הגרסה הריצה המלאה, עם הגדרות הכלים, משלחת ב-SDK ב-`docs/manual/examples/`. +זה מייצר את אותם ששת סוגי אירוע שמתאם היה נותן לך. הגרסה הרצה המלאה, עם הגדרות הכלים, משפנה ב-SDK repository תחת +`docs/manual/examples/`. -## Threads ו-async +## חוטים ו-async -משתני הקשר מתפשטים למשימות asyncio באופן אוטומטי. הם לא מתפשטים לחוטים חדשים, כי חוט מתחיל עם קשר ריק. +משתנות context מתפשטות לתוך asyncio tasks באופן אוטומטי. הן לא מתפשטות לתוך חוטים חדשים, כי חוט מתחיל עם context ריק. ```python -# asyncio: nothing to do +# asyncio: כלום לא לעשות async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads: wrap the callable +# threads: עטוף את ה-callable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -ללא `propagate()`, אירועי העובד מעלים `TypeError` ששם את התיקון ולא נוחתים בשום סשן. זה בכוונה: אירוע ללא סשן מדולג על ידי ingest וענה `200`, שזה כישלון שקט שרמת הזהות קיימת כדי למנוע. +ללא `propagate()`, אירועי העובד מגבילים `TypeError` ששם את התיקון במקום נחיתה ללא session. זה כוונתי: אירוע ללא session מדולל על ידי ingest וענות `200`, שזה הכשל שקט שלנו שה-identity layer קיים כדי למנוע. -## הכנת פריימוורק ללא מתאם +## הוסף מעקב לפריימוורק ללא מתאם -כל מסגרת סוכן נותנת לך אותם שלושה seams. מפה אותם ויש לך עקבות שלם — ארבעת המתאמים המשודרים לא עושים יותר מזה. +כל סוכן פריימוורק נותן לך את אותם שלושה seams. מפה אותם ויש לך עקבות מלא — ארבעת המתאמים המספקים לא עושים יותר מזה. -| ה-seam | מה אתה כותב | מה נוחת | +| ה-seam | מה שאתה כותב | מה נחיתה | | --- | --- | --- | -| הריצה | `session()` + `agent()` | `agent_start`, `agent_end` | +| ה-run | `session()` + `agent()` | `agent_start`, `agent_end` | | כל כלי | `tool_call()` | `tool_use`, `tool_result` | | כל קריאת מודל | הזוג `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - בכל מה שהפריימוורק קורא עטיפת כלי או middleware. + + בכל מה שהפריימוורק קורא tool wrapper או middleware. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -265,31 +265,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **יש לך צומת, שלב או גבול middleware שכדאי לראות?** עטוף אותו בזוג hook — `hook_triggered` / `hook_completed` — לא `agent()` מקונן. `agent_id` הוא facet בעל עוצמה נמוכה, וערך אחד לכל צומת טובע אותו. span hook משדרו באותו אופן ונותן לך אותך-צומת latency. + **יש node, step או middleware boundary שחייב להיות נראה?** עטוף אותו בזוג hook — `hook_triggered` / `hook_completed` — לא nested `agent()`. `agent_id` הוא facet low-cardinality, והערך אחד לכל node טובע אותו. Hook spans מתרנדרים בדרך זהה וגם נותנים לך לטנציה לכל node. - **ידני ואוטומטי מרכיבים.** מתאם הפועל בתוך טווח כתוב בעצמך מצטרף לסשן זה ו-parents לסוכן זה, אז אתה מקבל עץ אחד במקום שניים — שימושי כאשר אתה מכין פריימוורק אחד בעצמך לצד אחד נתמך. + **ידני והאוטומטי מרכיבים.** מתאם שנמצא בתוך scope כתוב ביד מצטרף לשיוך זה ומוריש לסוכן זה, כך שאתה מקבל עץ אחד ולא שניים — שימושי כאשר אתה מעביר מסגרת אחת בעצמך לצד אחד בעל תמיכה. - שתי סיבות, ושלושת ה-seams לעיל הם התשובה לשתיהן: + שתי סיבות, והשלושת ה-seams למעלה הן התשובה לשניהם: - - `autogen-core` היה לא תחזוקה מאז ספטמבר 2025. - - AG2 לא חושף נקודת רישום בהיקף תהליך שקולה לה של הפריימוורקים האחרים' hooks, אז הכנה זה אומר עטיפת כל סוכן בכל אתר בנייה. + - `autogen-core` לא תופסת תחזוקה מ-September 2025. + - AG2 לא חושף נקודת רישום כללית תהליך שווה ערך למשדרים של פריימוורקים אחרים, כך שהוספת מעקב אומר עטיפת כל סוכן בכל אתר בנייה. - מיפוי ה-seams ביד רושמות את אותם אירועים, באותה נאמנות, כמו מתאם משודר היה. + מיפוי ה-seams ביד רושם את אותם אירועים, בדיוק זהה, שמתאם משודר היה עושה. -## הלוך עמוק יותר +## עומק יותר -איך ההקלטה בעצם עובדת. כלום לא הכרחי כדי להתחיל. +איך ההקלטה למעשה עובדת. כלום מזה לא נחוץ כדי להתחיל. -לכל הקלטה יש אותה צורה: span נפתח, עבודה מקוננת בתוכה, וכל אירוע פתיחה מקבל אירוע סגירה. +לכל הקלטה אותו צורה: span נפתח, עבודה קינה בתוכו, ולכל אירוע פותח יש אירוע סוגר אחד. ```mermaid flowchart LR @@ -301,9 +301,9 @@ flowchart LR C --> E(["agent_end"]) ``` -ה**זוג** הוא היחידה. כל אירוע סגירה נושא משך הזמן שה-SDK מודד מהפתיחה שלו. +ה**זוג** הוא היחידה. כל אירוע סוגר נושא משך זמן SDK מודד מה-opening שלו. -להלן ריצה אמיתית אחת לכל פריימוורק — תפוסה מהדוגמאות המשלחות עם ה-SDK, שם מודל מנורמל. שימו לב כמה חוזר מקריאה אחת. +להלן הרצה אמיתית אחת לכל פריימוורק — תפוסה מהדוגמאות שנמצאות עם ה-SDK, שם מודל מנורמל. שים לב כמה חוזר מקריאה יחידה. @@ -324,7 +324,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - צמתים הופכים לזוגות hook, אז אתה מקבל per-node latency ללא שהם חונקים את רשימת הסוכן. + Nodes הופכים לזוגות hook, כך שאתה מקבל לטנציה לכל node ללא טביעת הרשימה סוכנים. @@ -341,7 +341,7 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - כל `role` של סוכן הופך לשם span שלו, אז latency וtoken spend שבור למטה per role. + `role` של כל סוכן הופך לשם ה-span שלו, כך שלטנציה ו-token spend מתפרקים לפי תפקיד. @@ -361,7 +361,7 @@ flowchart LR 26 +7.038s agent_end Agent · success ``` - לולאת הסוכן עצמה גלויה, לא רק קריאות הדגם שלה. + לולאת סוכן עצמה נראית, לא רק קריאות המודל שלו. @@ -376,10 +376,10 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - אין זוגות hook: Pydantic AI אין לא צומת או גבול שלב לסוגר. + אין זוגות hook: ל-Pydantic AI אין node או step boundary לתחום. - + ```text 6 events 1 +0.000s agent_start main 2 +0.000s tool_use population @@ -389,36 +389,36 @@ flowchart LR 6 +0.000s agent_end main · success ``` - אתה פולט אלה בעצמך. אותם סוגי אירוע, אותה נאמנות — זה עולה אתה את אתרי הקריאה. + אתה פולט אלה בעצמך. אותם סוגי אירוע, דיוק זהה — זה עולה לך לאתרי קריאה. - + -**אין אירוע session-end.** סשן זה לא משהו אתה סוגר — זה קבוצה של אירועים המשתפים `session_id`. +**אין אירוע session-end.** session אינה משהו שאתה סוגר — היא קבוצה של אירועים השיתוף `session_id`. -סטטוס מגוזר מצורת העקבות: +סטטוס נגזר מצורת העקבות: | סטטוס | מתי | | --- | --- | | `ongoing` | לפחות span אחד עדיין פתוח | -| `paused` | `agent_pause` אין שום matching `agent_resume` | -| `error` | כלום לא פתוח, וולפחות אירוע אחד נכשל | +| `paused` | `agent_pause` אין לו matching `agent_resume` | +| `error` | כלום לא פתוח, ולפחות אירוע אחד נכשל | | `done` | כלום לא פתוח, וכלום לא נכשל | -אז סשן מסתיים כאשר כל זוג סגור. המתאמים פולטים `agent_end` בשבילך, וב-teardown הם סוגרים כל דבר עדיין פתוח ומסמנים אותו לא שלם — ריצה שהתרסקה מסתדרת כ-`done` עם פער גלוי במקום תלוי לנצח. +כך שsession מסתיים כאשר כל זוג סוגר. המתאמים פולטים `agent_end` עבורך, והם סוגרים כל דבר עדיין פתוח ומסימנים אותו לא שלם — הרצה קרוסה מתפזרת כ-`done` עם פער גלוי במקום תלויה לנצח. - זו הסיבה שסשן יכול להשתרע על שתי קריאות. `interrupt()` LangGraph מעצור את הריצה, ה-root span נשאר בכוונה פתוח, וקריאת השחזור סוגרת אותה. שתי הקריאות הן סשן אחד. + זה למה session יכול להקיף שתי קריאות. LangGraph `interrupt()` השהה את ה-run, ה-root span בכוונה נשאר פתוח, והקריאה הממשיכה סוגרת אותה. שתי הקריאות הן session אחד. - + -`session_id` ו-`agent_id` אופציונליים בכל שיטת אירוע. השמיט, הם פותרים מה-scoping: +`session_id` ו-`agent_id` הם אופציונליים בכל שיטת event. בהשמטה, הם מתפזרים מהטווח שוקע: ```python with failproofai_sdk.session(): @@ -426,139 +426,139 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -העברתם בצורה מפורשת עדיין עובדת ותקיחה עדיפות. עם כלום קשור וכלום עבר, הקריאה מעלה `TypeError` ששם את התיקון במקום פליטת אירוע עם לא סשן, וזה ingest היה דילוג עד בעת ענוה `200`. +העברתם בגלוי עדיין עובדת ולוקחת עדיפות. ללא כלום קשור וכלום עברר, הקריאה מגבילה `TypeError` שם את התיקון במקום הפקת אירוע ללא session, אשר ingest היה דלל תוך התשובה `200`. -Scopes קשרים זהות על משתני הקשר. אלה מתפשטים למשימות asyncio באופן אוטומטי אך לא לחוטים חדשים — עטוף עובד ב-`failproofai_sdk.propagate()`. +טווחים קושרים זהות על משתנות context. אלה מתפשטות לתוך asyncio tasks באופן אוטומטי אך לא לתוך חוטים חדשים — עטוף עובד ב-`failproofai_sdk.propagate()`. -#### מי טביע איזה id +#### מי חושב איזה id -| Id | טבוע על ידי | הערות | +| Id | חשוב על ידי | הערות | | --- | --- | --- | -| `session_id` | אתה, או ה-SDK | `session("chat-42")` משמש verbatim; השמיט, ה-SDK מייצר `uuid4().hex` | -| `agent_id` | אתה, או הפריימוורק | מ-`agent("analyst")`, CrewAI `role`, `FunctionAgent.name`. ערך הנראה כ-UUID מוחזק וקבע | -| `tool_call_id`, `hook_id`, `request_id` | אתה, או הפריימוורק | מתאמים עוד שוב להשתמש בה-framework שלה עוד ids, וזו למה זוגות עמוד חוט הקפצות | -| **אירוע id** | **ענן, ב-ingest** | ה-SDK פולט כלום | -| **`dedup_key`** | **ענן, ב-ingest** | גיבוב של ארגון, סשן, timestamp, סוג וחומלת עומס. זו הזהות האמיתית — זה עושה נסיון מחדש batch כמצטבר בקריסה במקום שכפול | +| `session_id` | אתה, או ה-SDK | `session("chat-42")` משמש verbatim; בהשמטה, SDK מייצר `uuid4().hex` | +| `agent_id` | אתה, או הפריימוורק | מ-`agent("analyst")`, CrewAI `role`, `FunctionAgent.name`. ערך דומה UUID נדחה והחלפה | +| `tool_call_id`, `hook_id`, `request_id` | אתה, או הפריימוורק | מתאמים מחדשים שימוש ב-framework's שלהם run ids, שזה למה זוגות שורדים thread hops | +| **Event id** | **Cloud, ב-ingest** | ה-SDK לא פולט | +| **`dedup_key`** | **Cloud, ב-ingest** | hash של org, session, timestamp, type ו-payload. זאת הזהות האמיתית — היא גורמת batch שנו נסכל בקריסה במקום כפול | -#### איך מתאמים פותרים `session_id` +#### איך מתאמים מתפזרים `session_id` -משחק ראשון זוכה: +תאימה ראשונה זוכה: -1. `session_id` בגלוי אפשרות -2. לכל קריאה מטא-נתונים -3. ה-enclosing `session()` scope -4. מטא-נתונים פריימוורק -5. ה-framework שלה עוד id ריצה +1. ערך `session_id` מפורש +2. metadata לכל קריאה +3. טווח `session()` שוקע +4. framework metadata +5. framework's שלהם run id -זו לעולם לא המצאה בזמן שאחת מאלה קיימת — id סינתטי היה לחלק ריצה אחת על פני מספר סשנים. +זה אף פעם לא המצוי בזמן אחד מאלה קיים — id סינתטי היה מפלג הרצה אחת על פני מספר sessions. #### שמור `agent_id` low cardinality -זו פן ראשי על כל משטח לוח בקרה, וא `LowCardinality(String)` עמודה. ערך לכל ריצה מדרדר העמודה ומלא את dropdown המסנן עם ערך אחד לכל ריצה. +זה ה-facet ראשי בכל משטח dashboard, ו-`LowCardinality(String)` כולונה. ערך לכל run מורידה את הכולונה ומלאה את ה-filter dropdown בערך אחד לכל run. -מתאמים שומרים על העמודה בשבילך: +מתאמים בטחון כולונה זו עבורך: -| הפריימוורק מסר | רשום כ | למה | +| הפריימוורק מוביל על | הוקלט כ | למה | | --- | --- | --- | -| `3f9a1c2b-…` (UUID) | `main` | כלום קריא להחזיק | -| מחרוזת hex ארוכה חשופה | `main` | זהה | -| `agent-3f9a1c2b-…` | `agent` | לכל ריצה id קורוע, חלק קריא שמור | -| `agent-v2` | `agent-v2` | מקטעים קצרים נותרו לבדם | +| `3f9a1c2b-…` (UUID) | `main` | כלום קריא לשמור | +| hex ארוך חשוף string | `main` | זהה | +| `agent-3f9a1c2b-…` | `agent` | לכל run id חשוף, ible part שמור | +| `agent-v2` | `agent-v2` | קטגוריה קצרה משומרת | | `step-3` | `step-3` | זהה | -ה-id האמיתי נשמר ב-`fw_agent_id` / `fw_run_id`, איפה זה נשאר queried ללא להיות facet. +ה-ID האמיתי שמור ב-`fw_agent_id` / `fw_run_id`, איפה זה נשאר queryable ללא להיות facet. - **הגן זה רק נוגע תוויות ה-*framework* בחר.** `agent_id` אתה עובר בעצמך — ל-`event.*`, או `failproofai_sdk.agent(...)` — רשום בדיוק כפי שניתן. שקט כתיבה מחדש של טיעון מפורש היה גרוע יותר מ-cardinality זה מונע, אז שם שלך משל עצמך ספאנס בהתאם. + **שמירה זו רק נוגעת בתוויות **הפריימוורק** בחר.** `agent_id` אתה עבור עצמך — ל-`event.*`, או ל-`failproofai_sdk.agent(...)` — הוקלט בדיוק כנתון. שמאלה כתוב argument מפורש היה גרוע יותר מה-cardinality זה מנע, כך שקרא את הspan שלך בהתאם. - + | קבוצה | אירועים | | --- | --- | | סוכנים | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | | מודלים | `model_request`, `model_response` | | כלים | `tool_use`, `tool_result` | -| Hooks | `hook_triggered`, `hook_completed` | -| אנשים | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| וו | `hook_triggered`, `hook_completed` | +| בני אדם | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | כשלים | `error` | -איזה מסגרת רושמת מה, נמדד מהריצות למעלה: +איזה פריימוורק רושם מה, נמדד מה-runs למעלה: -| אירוע | LangGraph | CrewAI | LlamaIndex | Pydantic AI | מותאם | +| אירוע | LangGraph | CrewAI | LlamaIndex | Pydantic AI | מותאם אישית | | --- | :--: | :--: | :--: | :--: | :--: | -| התחלה ולסוף סוכן | כן | כן | כן | כן | אתה | +| תחילת וסוף סוכן | כן | כן | כן | כן | אתה | | בקשת מודל ותגובה | כן | כן | כן | כן | אתה | -| שימוש בכלים ותוצאה | כן | כן | כן | כן | אתה | -| Hook triggered וsupplied | צומת | משימה | שלב | — | אתה | +| שימוש בכלי ותוצאה | כן | כן | כן | כן | אתה | +| וו מתוגבר וסיום | Node | משימה | Step | — | אתה | | שגיאה | כן | כן | כן | כן | אוטומטי | -| האדם מחכה ויזמה | כן | כן | כן | — | אתה | -| סוכן עצור וחזור | כן | כן | כן | — | אתה | +| חכיית אדם וקלט | כן | כן | כן | — | אתה | +| השהיית סוכן וחידוש | כן | כן | כן | — | אתה | -מקף אומר לפריימוורק אין מושג כזה. `human_pause` ו-`human_interrupt` תאר *אדם* פעל על הסוכן, וזה אף פריימוורק משדר — פלט אלה בעצמך. +dash פירושו הפריימוורק אין לו כזה קונספט. `human_pause` ו-`human_interrupt` תארו **אדם** פועל על סוכן, אשר אף פריימוורק משדר — הפלוט אלה בעצמך. - + -אירוע לעולם לא מגיע לבדו. אחד פותח span, אחד סוגר אותה, ואירוע הסגירה נושא משך הזמן שה-SDK מודד מהפתיחה. +אירוע אף פעם לא מגיע בודד. אחד פותח span, אחד סוגר אותו, ואירוע הסיום נוצא משך זמן SDK מודד מה-opening. -| פותח | סוגר | אירוע הסגירה נושא | +| פותח | סוגר | אירוע הסיום נוצא | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | | `model_request` | `model_response` | tokens, `stop_reason`, latency | -| `tool_use` | `tool_result` | `output` או `error`, משך | -| `hook_triggered` | `hook_completed` | `outcome`, משך | +| `tool_use` | `tool_result` | `output` או `error`, duration | +| `hook_triggered` | `hook_completed` | `outcome`, duration | | `agent_pause` | `agent_resume` | כמה זמן ההשהיה נמשכה | | `human_wait` | `human_input` | התשובה, וכמה זמן האדם לקח | - אירוע פתיחה ללא סגירה הוא span שלעולם לא מסתיים. הסשן משדר כעדיין פועל, לנצח, ומשך הזמן הפעיל שלו ממשיך לגדול. זה מצב הכשל לצפות כאשר אתה מכין ביד. + אירוע פותח ללא סוגר אחד הוא span שלא סיים. השיוך מתרנדר כעדיין פעיל, לנצח, וה-active duration שלו ממשיך לגדול. זה כשל mode לצפות בו כאשר אתה מוסיף מעקב ביד. -#### כללי מתאם +#### כללי קורלציה -- עוד שוב את אותו `tool_call_id`, `hook_id`, `pause_id`, או `input_id` לאירוע ההשלמה התואם. -- ה-SDK מחשב `duration_ms` ל-`tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. עברת אותו לשיטות אלו מעלה `ValueError`. -- `duration_ms` **כן** מקבל ב-`model_response`, כי רק הקורא יודע את latency ספק אמיתי. זה חייב להיות מספר שלם — float מעלה `ValueError` ב-אתר הקריאה, כי השרת קורא את העמודה כמספר שלם לא חתום ב-32 ביט וישמור NULL לכל אחר. -- מפתחות מתאם מתוחמים לפי סוג וסשן, אז כלי קוראה וחוק עשויים בבטחה לשתף id, וששתי סשנים בו-זמנים עשויים לעשות שימוש חוזר באותו ids ללא התנגשות. הם לא מתוחמים על ידי סוכן: זוג פתוח תחת סוכן אחד וסגור תחת שנייה עדיין מתאמים, שזה המקרה הרגיל במסגרות סוכן רבות. -- `request_id` זוגות `model_request` עם `model_response`. ללא זה, אירועי מודל זוגות בסדר לכל סוכן, אז קריאות בו-זמנים מתאימות בצורה שגויה. -- זוג לחלוקה על פני תהליכים עדיין מתאמים downstream, אך ה-SDK לא יכול לחשב משך הזמן בתוך הפרוסס שלה. -- המפה התלויה אחזיקה בסך הכל 10,000 התחלות ומסיקות את הערך הישן ביותר כאשר מלא. +- חזור על אותו `tool_call_id`, `hook_id`, `pause_id`, או `input_id` לאירוע השלמה תואם. +- SDK מחשבות `duration_ms` לכל `tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. עברור אותו הודעות raises `ValueError`. +- `duration_ms` **הוא** קבול ב-`model_response`, כי רק ה-caller יודע ה-real provider latency. זה חייב להיות integer — float raises `ValueError` בקריאה site, כי השרת קורא את הכולונה כ-unsigned 32-bit integer וחנה NULL לכל דבר אחר. +- מפתחות קורלציה בטוח לפי סוג וsession, אז tool call ו-hook עשוי בטוח שיתוף id, וsessions מקבילות שני חזור על אותם ids ללא התנגשות. הם לא בטוח על ידי סוכן: זוג פתוח תחת סוכן אחד וסגור תחת אחר עדיין קורלציה, שהיא המקרה הרגיל במסגרות רב סוכנים. +- `request_id` זוגות `model_request` עם `model_response`. ללא אותו, אירועי מודל זוג בסדר לכל סוכן, כך קריאות מקבילות mispair. +- זוג פיצול על פני processes עדיין קורלציה downstream, אך SDK לא יכול לחשב in-process duration. +- מפת pending מחזיקה לכל היותר 10,000 starts ו-evicts ערך עתיק כאשר מלא. - + -הקנו `failproofai-sdk` מקנה את הכל, את כל ארבעת המתאמים כלול. התוספות משכו את **פריימוורק**, לא את המתאם. +התקנת `failproofai-sdk` מתקנת הכל, כל ארבעת המתאמים כלול. ה-extras משדרים את **הפריימוורק**, לא את המתאם. ```python -import failproofai_sdk # loads nothing outside the standard library -failproofai_sdk.instrument() # imports only the adapters you actually need +import failproofai_sdk # עומס כלום חוץ מה-standard library +failproofai_sdk.instrument() # ייבוא רק המתאמים אתה בעצם צריך ``` -`import failproofai_sdk` הוא חוזה אפס-תלוי, אנוף על ידי בדיקה המקנה את הגלגל הבנוי עם `--no-deps` ואחר שמוכיח שאין פריימוורק מגיע ל-`sys.modules`. +`import failproofai_sdk` הוא חוזה אפס תלויות, אינפורמציה על ידי בדיקה שמתקנת את הגלגלון עם `--no-deps` ועוד שמוכיח אף פריימוורק מגיע ל-`sys.modules`. - אין `failproofai_sdk.crewai` תכונה. המתאמים בכוונה לא חשופים על חבילה ברמה עליונה: מגע של אחד היה לייבא את הפריימוורק כתופעת לוואי של גישה תכונה, שבור בחוזה אפס-תלוי. השתמש ב-`instrument()`. + אין `failproofai_sdk.crewai` תכונה. מתאמים בכוונת לא חשוף על הפרה עליונה חבילה: לוגע אחד היה ייבוא הפריימוורק כ-side effect של גישה תכונה, שבירת אפס תלויות הבטחה. השתמש `instrument()`. ```python -failproofai_sdk.instrument() # every framework already imported -failproofai_sdk.instrument("crewai") # exactly one, by name -failproofai_sdk.uninstrument("crewai") # put it back +failproofai_sdk.instrument() # כל פריימוורק כבר ייובא +failproofai_sdk.instrument("crewai") # בדיוק אחד, לפי שם +failproofai_sdk.uninstrument("crewai") # שים חזרה ``` -| שם | אף קבל | +| שם | גם קבול | | --- | --- | | `langchain` | `langgraph`, `langchain_core` | | `crewai` | — | | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -גילוי אוטו קורא `sys.modules`, לא את חבילה מותקנת רשימה, אז פריימוורק שיש לך מותקן אך לעולם לא יובא לא מכונו וישעדם לעולם לא יובא על בעד שלך. לראות מה חיווט עד: +גילוי אוטומטי קורא `sys.modules`, לא את רשימת חבילה מותקנת, אז פריימוורק שיש לך מותקן אבל אף פעם לא ייבוא הוא לא מוכן והוא אף פעם לא ייובא בשמך. להראות מה חווט למעלה: ```python from failproofai_sdk.integrations import active, available @@ -568,130 +568,132 @@ active() # ('langchain',) ``` - **`instrument("crewai")` על מכונה ללא CrewAI לא מעלה.** זה עליו קריאה וחזרות `()`, כך אחד פריימוורק חסר לעולם לא קח למטה תהליך גם כן מכין אחרים. + **`instrument("crewai")` על מכונה ללא CrewAI לא מגביל.** זה עוקב אזהרה ו-return `()`, אז פריימוורק חמיץ אף פעם לוקח תהליך שגם מהמרות אחרים. - התרעה נושא בו `ImportError`, והודעה זו שם קומנדה התקנה בדיוק — אז תיקון ב-יומנים שלך, לא מוסתר. + האזהרה נוצא ה-`ImportError` בקדמה, וזה הודעה שם את פקודת התקנה מדויקת — כך התיקון בלוגים שלך, לא מוסתר. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - קבע `FAILPROOFAI_SDK_STRICT=1` כדי היה זה מעלה במקום. דגל זה קורא **פעם וcached**, אז יצוא זה לפני הפרוסס שלך מתחיל במקום הגדרה בתוך ריצה. + ערכה `FAILPROOFAI_SDK_STRICT=1` כדי יש לו מגביל במקום. זה דגל קורא **פעם אחת ו-cached**, אז ייצוא זה לפני התהליך מתחיל במקום קביעה mid-run. - **`instrument()` חייב לבוא *לאחר* הייבא פריימוורק שלך.** גילוי אוטו קורא `sys.modules`, אז קריאה חשופה מעל הייבא מוצא כלום, מקנה כלום, וחזרות `()`. + **`instrument()` חייב לבוא **אחרי** ייבוא הפריימוורק שלך.** גילוי אוטומטי קורא `sys.modules`, אז קריאה ערומה מעל הייבוא מוצא כלום, מתקן כלום, וחוזר `()`. -```python Wrong +```python שגוי import failproofai_sdk -failproofai_sdk.instrument() # sys.modules has no langchain yet -> () +failproofai_sdk.instrument() # sys.modules אין langchain עדיין -> () -import langchain # too late, nothing is wired +import langchain # מאוחר מדי, כלום לא חווט ``` -```python Right -import langchain # import the framework first +```python נכון +import langchain # ייבוא הפריימוורק ראשון import failproofai_sdk -failproofai_sdk.instrument() # finds it -> ('langchain',) +failproofai_sdk.instrument() # מוצא זה -> ('langchain',) ``` -```python Right, order-proof +```python נכון, order-proof import failproofai_sdk -# Naming it imports the adapter on request, so this works from anywhere. +# שם זה ייבוא את המתאם על בקשה, אז זה עובד מכל מקום. failproofai_sdk.instrument("langchain") ``` -קבל זה לא ישר ותהליך פועל עם ה-SDK יובא, המתאם לכאורה מותקן, ו**לא אירוע אחד פלט**. זה עליו קריאה התרעה שכוללת בדיוק זה — אז בדוק יומנים שלך ראשון כאשר ריצה רושמת כלום. +קבל את זה שגוי והתהליך פועל עם ה-SDK ייובא, המתאם לכאורה מותקן, ו**לא אירוע אחד פלט**. זה עוקב אזהרה אומר בדיוק זה — אז בדוק לוגים ראשון כאשר run רושם כלום. - + ```mermaid flowchart LR - A["Your agent"] --> B["Adapter"] - B --> C["Writer
in-memory queue"] - C -->|"every 0.5s"| D["Spool
JSONL on disk"] + A["הסוכן שלך"] --> B["מתאם"] + B --> C["כותב
תור בזיכרון"] + C -->|"כל 0.5s"| D["Spool
JSONL בדיסק"] D --> E["Failproof daemon"] E -->|"HTTPS"| F["Cloud"] ``` -| בימה | עבודה | רץ ב | +| שלב | משימה | פועל בתוך | | --- | --- | --- | -| מתאם | תרגום קלט פריימוורק לאחד מ-15 סוגי אירוע | הפרוסס שלך | -| כותב | קיוו, אצווה, כתוב JSONL אטומית | הפרוסס שלך, חוט רקע | -| סקול | מעביר עמיד, שורד הפרוסס שלך יוצא | דיסק מקומי | -| דיימון | שמור סקול, ספינה אצווה, מחק מה ספינה | מכונה שלך | -| Ingest | הקצה שורה id וdedup מפתח, טלל queried עמודות | ענן | +| מתאם | תרגם callback פריימוורק לתוך אחד מ-15 סוגי אירוע | התהליך שלך | +| כותב | תור, אצווה, כתיבה JSONL אטומית | התהליך שלך, חוט רקע | +| Spool | Durable handoff, שורד התהליך יציאה | דיסק מקומי | +| Daemon | שומר spool, משלח אצוות, מוחק מה-shipped | המכונה שלך | +| Ingest | מקצה שורה id ו-dedup key, מקדם שאלה כולוניות | Cloud | -ה-spool הוא מה עושה זה בטח: הסוכן שלך לעולם לא חסום ברשת, והפרה ענן אומר ספרייה גדלה במקום אבוד אירועים. +ה-spool הוא מה עושה זה בטוח: סוכן שלך אף פעם לא חסום על הרשת, וCloud outage אומר ספריה גדלה במקום קביעה אירועים. -כל שטוף כותב אחד אצווה קובץ, `.tmp` ראשון, אז `fsync`, אז שינוי אטומית: +כל flush כתוב קובץ אצווה אחד, `.tmp` ראשון, ואז `fsync`, ואז atomic rename: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -הדיימון רק כריע `.jsonl`, אז זה יכול לעולם קרא חצי-כתוב קובץ. ה-stem נושא timestamp, פרוסס id ומספר רצף, אז שני תהליכים שטוף באותה מילישנייה לא יכולה התנגשות. הקיוו מכוסה ב-10,000 אירועים; עבר זה זה משחזר הישן וגב. +ה-daemon רק עוזב `.jsonl`, אז זה לא יכול אף פעם קרא חצי כתוב קובץ. הגזע נוצא timestamp, process id וסדר מספר, אז שני תהליכים flush בה-millisecond לא יכול להתנגש. התור כובל בחסום 10,000 אירועים; העבר זה זה טיפל הוקדם וrelog. - **`collector.redact` ברירות ל-`minimal` ל-SDK אירועים גם כן.** ה-SDK מנקה לפני כתיבה אצווה לדיסק, והדיימון חזר מעל אותו דטרמיניסטי לפני העלאה אז אצווה מה SDK ישן מוגן. + **`collector.redact` עושה לא חל ל-SDK אירועים שלך.** זה אף פעם לא רואה אותם. -הדיימון קורא כל אצווה וחל redaction בזיכרון לפני העלאה. זה לא כתיבה מחדש הדיסק קובץ זה קרא. +ה-daemon **משלח** אצוות שלך. זה לא פתוח או לשכתב אותם. -| אירועים | כתוב על ידי | איפה redaction minimal רץ | +| אירועים | כתוב על ידי | Redacted על ידי `collector.redact`? | | --- | --- | --- | -| עדכני סשן CLב | הדיימון | לפני הדיימון כתיבה האצווה | -| Hook פעילות | הדיימון | לפני הדיימון כתיבה האצווה | -| **הכל ה-SDK פולט** | **הפרוסס שלך** | **לפני ה-SDK כותב האצווה ושוב לפני daemon ההעלאה** | +| CLI session תחקירי | Daemon | כן | +| וו פעילות | Daemon | כן | +| **הכל ה-SDK פלט** | **התהליך שלך** | **לא** | + +Redaction פועל איפה ה-daemon **כתוב** שלהם אירועים — לא איפה אצוות **משודרים**. כך prompt או tool argument מחזיק API key עדיין מחזיק זה בהגעה. -קבע `collector.redact` ל-`off` רק כאשר verbatim מטענים הוא תבחין מפורש; ה-SDK וdaemon שניהם כבדו הגדרה. redaction minimal תופס API מנוצל, bearer אסימונים, JWTs, וסוד מטימות. זה לא יכול מייצר שרירות רגישות שרירותיות. +זה כוונתי. אלה בעצמך מעקב קריאות, וכתיבה מחדש בטרנזיט יומר את אירועים אתה קבל הם לא אירועים אתה פלט. - **אתה שלוט מטענים ב-מקור, ב-שתי מקומות:** + **אתה שלוט בפעילויות ב-source, בשני מקומות:** - - תור עוד תכן תופס ב-מתאם. **שם האפשרות שונה, ואחד מתאם אין כלום** — זה לא בחירה אוניברסלית יחידה: + - כבה לכידת תוכן על המתאם. **שם אפשרות שונה, ומתאם אחד אין אחד** — זה לא אחד כללי אוניברסלי מתג: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **אין תור תכן לכל**; `session_id` הוא רק אפשרות זה קורא, אז prompts השלמות תמיד רשום. + - CrewAI — **אין מתג תוכן בכל**; `session_id` היא רק אפשרות שהיא קורא, אז prompts ו-completions תמיד רשום. - `instrument()` טיל אפשרויות מתאם לא קורא, אז עברת שם שגוי מעלה כלום ושינויים כלום. - - אל תיד הסוד ל-`input=` ב-ראשון מקום. + `instrument()` טיול אפשרויות מתאם לא קורא, אז עברור שם שגוי מגביל כלום ושינויים כלום. + - אל תעביר את הסוד ל-`input=` בראשון מקום. - `collector.redact` הוא הגנה בעומק, לא תחליף לכל אחד. + `collector.redact` הוא לא תחליף לאף אחד מאלה. - **ספרייה סקול ריק הוא המצב בריא.** אל להשתמש זה לתברואה חלוקה. + **ספריה spool ריקה היא המדינה הבריאה.** אל תשתמש בזה כדי בדוק משלוח. -הדיימון מחק כל אצווה בתוך מילישנייה ספינה, אז `ls` מרוץ הקולקטור ותגיד שבר מה כוללים — בהבחנה מ-SDK שרשום כלום. +ה-daemon מוחק כל אצווה בתוך milliseconds משליחה, אז `ls` מרוצים collector וש fraction של מה אתה פלט — לא ניתנת להבחנה מ-SDK ש קיבוץ כלום. -כדי לעזוב אירועים בעצם נחתו, בדוק לוח בקרה. לצפות הסקול למטלאות, עצור דיימון ראשון. +לאשר אירועים באמת נחתו, בדוק את ה-dashboard. לצפות ה-spool תמלא, עצור את ה-daemon ראשון. - + -כל קלט רץ בתוך עטיפה שעבודה היחידה הוא להעלות מחדש, אז הקריאה שלך יושבת בדיוק אחד `try` וכול דבר ה-SDK עושה קורה חוץ זה. +כל callback פועל בתוך wrapper שלה יחידה משימה היא להגביל מחדש, אז קריאה שלך יושבת בדיוק אחד `try` והכל SDK עושה קורה מחוץ אותה. -| מה קרה | תוצאה | +| מה קורה | תוצאה | | --- | --- | -| חוק מעלה | רשום כפעם עם traceback שלה. הקריאה שלך לא מושפעת | -| אותו חוק מעלה שלוש פעמים | זה חוק אחד מנוטרל שאר הפרוסס, עם קו שגיאה אחד | -| `FAILPROOFAI_SDK_STRICT=1` קבע | החריג מוגבה במקום | -| פריימוורק גרסה מחוץ לטווח בדוק | קוראים פעם, מכין בכל זאת | -| יכול אחד חסר | זה חוק אחד מנוטרל, לעולם לא מתאם מלא | +| hook מגביל | עיתון פעם עם traceback. קריאה שלך לא השפעה | +| אותו hook מגביל שלוש פעמים | זה hook אחד משוביץ לנו התהליך, עם שורה טעות אחד | +| `FAILPROOFAI_SDK_STRICT=1` הוא קביעה | החריגה הוא re-raised במקום | +| פריימוורק גרסה חוץ בדוקו טווח | הזהרות פעם, מהמרות בכל זאת | +| יחיד יכולת היא חמיץ | זה חוק אחד משוביץ, אף פעם כל מתאם | -ברירת זה כון בייצור ולא בזמן ירא, כי זה יכול רק לעולם הוכיח טו לא קרס. קבע `FAILPROOFAI_SDK_STRICT=1` כדי עשה כישלון בולע רועם. +ה-default הוא ימין בייצור וחצי בזמן debug, כי זה יכול רק אי פעם הוכח אתה לא קרס. קביעה `FAILPROOFAI_SDK_STRICT=1` לעשות בוליט כשל קול. @@ -700,24 +702,24 @@ flowchart LR ## בעיות נפוצות - - אירוע פתיחה אין סגירה: `model_request` עם לא `model_response`, או `tool_use` עם לא `tool_result`. השתמש הטווחים, גם ערבות הזוג כאשר גוף מעלה. אם קריאה יוש שיטות אירוע, השתמש `try` ו-`finally`. + + אירוע פותח אין אחד סוגר: `model_request` ללא `model_response`, או `tool_use` ללא `tool_result`. השתמש הטווחים, אשר ערובה הזוג אפילו כאשר הגוף מגביל. אם אתה קורא את שיטות האירוע ישירות, השתמש `try` ו-`finally`. - - זה מודד מה אירוע פתיחה מתאם, אז זה דחה ב-`tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. זה קבול ב-`model_response`, כי רק אתה דע ספק אמיתי latency, וחייב להיות מספר שלם. + + זה נמדד מה-opening תואם אירוע, אז זה דחוי ב-`tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. זה קבול ב-`model_response`, כי רק אתה יודע ה-real provider latency, וזה חייב להיות integer. - - החוט לא עדיין ירש הקשר. עטוף הקריא ב-`failproofai_sdk.propagate()`. עיין [Threads וasync](#threads-and-async). + + החוט לא אף פעם inherited ה-context. עטוף את ה-callable ב-`failproofai_sdk.propagate()`. ראה [חוטים ו-async](#threads-and-async). - - שדות תוספת מגיעים אחרון, אז אחד שם כמו שדה אמיתי כגון `model` או `outcome` היה overwrite זה ושינוי עמודה אחסון. שדה שלך; המתאמים משתמש `fw_` קידומת. + + שדות תוספת מיזוג אחרון, אז אחד שנקרא כמו שדה אמיתי כמו `model` או `outcome` היה כתוב על זה ו-שינוי כלונה שמור. Namespace שלך; המתאמים משתמשים `fw_` קידומת. - - `agent_id` הוא low-cardinality facet וגם אתה שם id ריצה בו. השתמש תפקיד או צומת שם וגם שם id אמיתי ב-שדה מטענה. + + `agent_id` היא low-cardinality facet ו-אתה שים run id בזה. השתמש תפקיד או node שם ו-שים ה-ID אמיתי בשדה payload. @@ -725,12 +727,12 @@ flowchart LR - זוגות, ids, סשן lifecycle, וחלוקה. + זוגות, ids, session lifecycle, ו-delivery. - - עקוב causality דרך הסשן בדיוק תפסת. + + עקוב סיבתיות דרך ה-session אתה רק תפוסה. - + LangGraph, CrewAI, LlamaIndex, ו-Pydantic AI. \ No newline at end of file diff --git a/docs/he/start/quickstart.mdx b/docs/he/start/quickstart.mdx index b10b3a1c..78e2f219 100644 --- a/docs/he/start/quickstart.mdx +++ b/docs/he/start/quickstart.mdx @@ -1,17 +1,17 @@ --- title: "התחלה מהירה" -description: "תופסים עבודה של סוכן, מוצאים כישלון ומתחילים למנוע אותו." +description: "קבע מושב של סוכן, מצא כשל והתחל למנוע אותו." icon: "zap" --- -התחלה זו תגרום למכונה אחת לדווח על עבודות, תריץ ביקורת ותפרוס מדיניות. השתמש בכישרון כדי להגדיר את Failproof AI, או בצע את השלבים ידנית. +התחלה מהירה זו מציבה מחשב אחד לדיווח על מושבים, מפעילה ביקורת ופורסת מדיניות. השתמש בכישור כדי להגדיר את Failproof AI, או בצע את השלבים ידנית. -**איזה נתיב שלך?** אם הסוכן שלך רץ באחד מ-12 ה[מנועים](/he/reference/harnesses) שנתמכים — CLI לקידוד, או שער כמו Hermes או OpenClaw — בצע את השלבים למטה; אתה צריך Node.js 20.9 או יותר חדש. אם לסוכן שלך אין מנוע, הוסף אותו עם ה-[Python SDK](/he/reference/custom-agents) לעקיבה וביקורות, ואז חזור ל[הריצה הראשונה שלך של בדיקת כישלון](/he/start/first-audit); האכיפה בנתיב זה דורשת hook בזמן הריצה שלך. +**איזה נתיב שלך?** אם הסוכן שלך פועל באחד מ-12 [מסגרות](/he/reference/harnesses) שנתמכות — CLI קוד, או שער כמו Hermes או OpenClaw — בצע את השלבים למטה; אתה צריך Node.js 20.9 או גרסה חדשה יותר. אם לסוכן שלך אין מסגרת, יש לו אם כן להערות עם [Python SDK](/he/reference/custom-agents) לעקיבה וביקורות, ואז חזור אל [הפעל את בדיקת הכשל הראשונה שלך](/he/start/first-audit); אכיפה בנתיב זה דורשת hook בזמן הריצה שלך. - + - + ```bash npx skills add FailproofAI/skills ``` @@ -21,19 +21,19 @@ icon: "zap" Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - הסוכן שלך בודק את הפרויקט, בוחר את האינטגרציה הרלוונטית, מבצע את ההגדרה ומוודא אותה. ראה את [מאגר כישרוני FailproofAI](https://github.com/FailproofAI/skills) לכישרונות בודדים וואפשרויות התקנה מתקדמות. + הסוכן שלך בודק את הפרויקט, בוחר את האינטגרציה הרלוונטית, מבצע את ההגדרה ומוודא אותה. ראה את [מאגר כישורי FailproofAI](https://github.com/FailproofAI/skills) לקבלת כישורים בודדים ואפשרויות התקנה מתקדמות. ## לפני שתתחיל -1. פתח את [לוח הבקרה של Failproof AI](https://app.befailproof.ai) וצור חשבון או היכנס עם דוא״ל שלך בעבודה. -2. עבור ל**Administration → Keys** וצור מפתח עם `events:add` ו`policies:pull`. -3. העתק את הסוד שלשימוש חד-פעמי ושמור אותו על המכונה היעד: +1. פתח את [לוח הבקרה של Failproof AI](https://app.befailproof.ai) וצור חשבון או התחבר עם דוא״ל עבודה. +2. עבור אל **Administration → Keys** וצור מפתח עם `events:add` ו-`policies:pull`. +3. העתק את הסוד לשימוש חד-פעמי, ואז קרא אותו למעטפת על המחשב של היעד. `read -s` לוקח אותו בהודעה שלא משדרת, כך שהוא לא מופיע לעולם בפקודה: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## התקנה @@ -42,12 +42,18 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - תמלילי עבודה נשלחים כברירת מחדל. הוסף `--no-transcripts` כדי לדווח על פעילות hook והחלטות מדיניות ללא תוכן תמלילים. + אותה פקודה אחת היא כל ההגדרה: היא מתקינה את ה-daemon המקומי (root פעם אחת), חוטה hooks לכל CLI סוכן שהוא מוצא, וחוברת מחשב זה ל-Cloud. העברת המפתח דרך הסביבה במקום `--token` שומרת אותו מתוך `ps`, כאשר כל משתמש במחשב יכול לקרוא ארגומנטים של פקודה. זה לא שומר אותו מתוך היסטוריית הקליפה — קריאה שלו עם `read -s` היא מה שעושה זאת. ב-CI, הזרק אותו כסוד מוסווה והחזק ניתוח קליפה (`set -x`) כבוי, או ניתוח הדפסים. - אם למכונה זו כבר יש הסטוריית סוכן, הצג תצוגה מקדימה ויבא את שבעת הימים האחרונים, ואז חכה שההעברה תסתיים. דלג על שלב זה במכונה חדשה. + תמלילי מושבים נשלחים כברירת מחדל. הוסף `--no-transcripts` לדיווח על פעילות hook והחלטות מדיניות ללא תוכן תמליל. + + + אל תשלוף `failproofai config --connect ` כאן. דגל זה רושם מחשב שהוא **כבר** מוגדר ופוחת ישר אחרי כן — לא daemon, לא hooks — כך שהמחשב יופיע ב-Cloud בעת איסוף והנפקה של כלום. + + + אם למחשב זה יש כבר היסטוריית סוכן, תצוגה מקדימה וייבוא של שבעת הימים האחרונים, ואז חכו שההסלמה תסתיים. דלג על שלב זה במחשב חדש. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +61,41 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - פתח את **Sessions** ב-Failproof AI ובחר עבודה שיובאה. + פתח **Sessions** ב-Failproof AI ובחר מושב שיובא. - - זה מצמיד את Failproof AI למנוע שלך ומתקין את 39 המדיניויות המובנות. השתמש בהן כדי לראות החלטות מדיניות מקומיות ולנסות אכיפה לפני שFailproof AI בוודק את העבודות שלך וכותב מדיניויות לסוכנים שלך. + + השלב הקודם כבר חוטה כל CLI סוכן שהוא גילה. הפעל אותו מחדש לבר אחד במפורש כשאתה צריך, או כדי להוסיף מסגרת שהותקנה אחרי כן. כל אחד מ-12 הוא ערך `--cli` תקף — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + ```bash + failproofai policies --install --cli claude --scope user # CLI קוד + failproofai policies --install --cli hermes --scope user # שער Slack/Telegram + ``` - אפשר לגלאי ההתקנה לגלות את המנוע שלך, או שם אחד במפורש. כל אחד מ-12 הוא ערך `--cli` תקף — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + חסימת קריאת כלי לפני שהוא פועל מאומתת על כל 12. שערים של קצה סיבוב מאומתים על 8 — ראה [יכולת אכיפה](/he/reference/harnesses#enforcement-capability) למטריקס ל-per-harness. + + + חיטוב hooks מאפשר ללא מדיניות. התקנה בחרה בכוונה שום דבר — החלטה זו היא שלך — אז קחו חבילה: ```bash - failproofai policies --install --cli claude --scope user # a coding CLI - failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway + failproofai policies add FailproofAI/policies ``` - חסימת קריאת כלי לפני שהיא רצה מאומתת על כל 12. שערי סיום הפניה מאומתים על 8 — ראה [יכולת אכיפה](/he/reference/harnesses#enforcement-capability) למטריקס לכל מנוע. + החבילה מחוזרת מהשחרור ב-GitHub שלה, מאומת checksum, וקבוע לתג המדויק שהוא נפתר. הוא נושא 38 מדיניויות ומפסיק את 10 המניפסט שלו מסמן כבטוח להפעלה ללא השגחה. השתמש בהם כדי לראות החלטות מדיניות מקומיות וניסיון אכיפה לפני שFailproof AI מבקר במושבים שלך וכותב מדיניויות לסוכנים שלך. + + קרא כל חבילה לפני שתקחת אותה עם `failproofai policies show /`, ו[חבילות מדיניות](/he/policies/packs) לקבלת חלק אחד בלבד. + + עד שזה פועל, הדבר היחיד שמנוע הוא `block-failproofai-commands` — השומר תמיד פעיל החוסם סוכן משבית Failproof AI. `failproofai policies` רושם מה הוא פועל. - עקוב אחר [הריצה הראשונה שלך של בדיקת כישלון](/he/start/first-audit). השתמש במטרה קונקרטית כגון "מצא עבודות שבהן הסוכן ניסה מחדש כלי כושל ללא שינוי בגישה שלו." + בצע את [הפעל את בדיקת הכשל הראשונה שלך](/he/start/first-audit). השתמש במטרה קונקרטית כמו "מצא מושבים שבהם הסוכן ניסה שוב כלי כושל ללא שינוי בגישה שלו." - - עקוב אחר [מניעת הכישלון הראשון שלך עם מדיניות](/he/start/first-policy). התחל במצב צפייה, בדוק התאמות, ואז אכוף את הגרסה שנבדקה. + + בצע את [מנע את הכשל הראשון שלך עם מדיניות](/he/start/first-policy). התחל במצב צפייה, בדוק התאמות, ואז הנחל את הגרסה שבדקת. - הרץ `failproofai config --status`. הגדרה בריאה מדווחת על חיבור הענן, מצב ה-daemon, וואם אכיפה מושהית. + הפעל `failproofai config --status`. הגדרה בריאה מדווחת על חיבור ענן, מצב daemon, והאם אכיפה מושהית. \ No newline at end of file diff --git a/docs/he/start/setup.mdx b/docs/he/start/setup.mdx index f6f3403b..50c265f4 100644 --- a/docs/he/start/setup.mdx +++ b/docs/he/start/setup.mdx @@ -1,68 +1,89 @@ --- -title: "בחר את ההגדרות שלך" -description: "בחר אכיפה מקומית, Failproof AI Cloud, או פריסה ישירה לארגון." +title: "בחרו בהגדרת ההפעלה שלכם" +description: "בחרו בהאכיפה המקומית, ב-Failproof AI Cloud, או בהפעלה ארגונית." icon: "waypoints" --- - התקן hooks ומדיניות על מכונה. השתמש בזה כאשר אתה זקוק ל-guardrails מידיים ללא שליחת נתוני session ל-Cloud. + הגדירו מכונה ללא מפתח Cloud וקחו חבילת מדיניות. השתמשו בכך כאשר אתם זקוקים לממגנים מיידיים ללא שליחת נתוני הפעלה ל-Cloud. - הוסף sessions מרכזיות, ביקורות, הערכות מקוונות, dashboards, התראות, ופריסת מדיניות לחיל. + הוסיפו הפעלות מרכזיות, ביקורות, הערכות מקוונות, לוחות בקרה, התראות והפעלת מדיניות בחfleet. - - השתמש בבקרות ארגוניות, מפתחות בהיקף מוגבל, תשתית פרטית, ודרישות אבטחה ספציפיות לפריסה. + + השתמשו בבקרות ארגוניות, מפתחות בטווח מסוים, תשתית פרטית ודרישות אבטחה ספציפיות להפעלה. -## נתיב הייצור המומלץ +## אכיפה מקומית -1. חבר מכונה שאינה בייצור עם capture transcript מופעל. -2. אמת sessions והערכות ב-Cloud. -3. צור ביקורת עבור מצב תקלה ידוע. -4. פרוס את המדיניות הראשונה במצב observe. -5. הרחב לייצור לאחר בדיקת התאמות ו-false positives. +הריצו `failproofai config` ללא מפתח, ואז קחו חבילה עם `failproofai policies add FailproofAI/policies`. בטרמינל, בחרו **Not now — stay local** כאשר ההגדרה שואלת להתחבר ל-Cloud; ללא טרמינל וללא `FAILPROOFAI_CLOUD_TOKEN`, היא תישאר מקומית מעצמה. ה-daemon והחיבורים מאכיפים את המכונה, ואף נתוני הפעלה לא נשלחים ל-Cloud. כדי להתחבר מאוחר יותר, עקבו אחר השלבים למטה. -## חבר מכונה ל-Cloud +## נתיב הפקה מומלץ + +1. חברו מכונה שאינה בייצור עם הקטעת שדר מופעלת. +2. אמתו הפעלות והערכות ב-Cloud. +3. צרו ביקורת לצורך מצב כשל ידוע. +4. הפעילו את המדיניות הראשונה ב-observe mode. +5. הרחיבו לייצור לאחר בדיקת התאמות וחיובי שווא. + +## חברו מכונה ל-Cloud - 1. עבור ל-**Administration → Keys** וצור מפתח עם `events:add` ו-`policies:pull`. - 2. העתק את הסוד לשימוש חד-פעמי למכונת היעד. - 3. לאחר הפעלת פקודת החיבור של ה-CLI, עבור ל-**Admin → enforcement** ואמת שהמכונה מופיעה. - 4. עבור ל-**Observe → Events** ואמת שהאירוע הראשון שלה הגיע. + 1. עברו ל-**Administration → Keys** וצרו מפתח עם `events:add` ו-`policies:pull`. + 2. העתיקו את הסוד החד פעמי למכונה היעד. + 3. לאחר הרצת פקודת ה-CLI של החיבור, עברו ל-**Admin → enforcement** ואשרו שהמכונה מופיעה. + 4. עברו ל-**Observe → Events** ואשרו שהאירוע הראשון שלה הגיע. - מגירת המפתח מציגה שתי ההרשאות הנדרשות על ידי מכונה מחוברת: ingestion של אירועים ו-policy delivery. + מגירת המפתח מציגה את שתי ההרשאות הנדרשות על ידי מכונה מחוברת: ספיגת אירועים והעברת מדיניות. - ![מגירת מפתח ה-API החדשה המשמשת להענקת הרשאות ingestion של אירועים ו-policy delivery.](/images/dashboard/key-create.png) + ![מגירת מפתח ה-API החדשה המשמשת להעניית הרשאות ספיגת אירועים והעברת מדיניות.](/images/dashboard/key-create.png) - לאחר החיבור, המכונה צריכה להופיע ב-enforcement עם מצב המדיניות הרצוי שלה וסטטוס הפריסה. + לאחר החיבור, המכונה צריכה להופיע באכיפה עם מצב המדיניות הרצוי והמדווח שלה. - ![צי ה-Enforcement עם מכונה רשומה מורחבת כדי להציג את מצב המדיניות הרצוי שלה וסטטוס הפריסה.](/images/dashboard/enforcement-fleet.png) + ![ה-fleet בעינה עם מכונה רשומה המורחבת כדי להציג את מצב המדיניות הרצוי שלה וסטטוס ההפעלה.](/images/dashboard/enforcement-fleet.png) - האירוע הראשון שמגיע מאשר שה-daemon יכול להעביר נתונים ל-Cloud, ללא תלות בפריסת המדיניות. + האירוע הראשון שהגיע מאשר שה-daemon יכול להעביר נתונים ל-Cloud, בנפרדות מהפעלת המדיניות. - ![זרם האירועים החי המציג אירועים של agent, model ו-tool אחרונים.](/images/dashboard/events-stream-current.png) + ![זרם האירועים הקי מציג אירועי סוכן, מודל וכלים עדכניים.](/images/dashboard/events-stream-current.png) - המשך רק לאחר שהמכונה והאירוע הראשון שלה גלויים. + המשיכו רק לאחר שהמכונה והאירוע הראשון שלה גלויים. + קראו את הסוד החד פעמי לתוך ה-shell. `read -s` לוקח אותו בהנחיה שאינה משדרת, כך שהוא לעולם לא מופיע בפקודה או בהיסטוריית shell: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + לאחר מכן הגדירו את המכונה, בחרו את המדיניויות שלה ותנו לה שם: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` - הוסף `--no-transcripts` כאשר תוכן transcript חייב להישאר מקומי. + `failproofai config` עושה את כל ההגדרה — daemon, חיבורים לכל CLI סוכן שהוא מוצא, והחיבור ל-Cloud — לאחר מכן בוחר אפס מדיניויות, שזה מה שהפקודה השנייה היא בשביל. + + התווית מגיעה **לאחר** החיבור, לא במהלכו: `failproofai config --machine-label ` משנה את שם מכונה שכבר מחוברת, ועל אחת שאינה, היא לא עושה דבר אלא לומר זאת. + + הוסיפו `--no-transcripts` כאשר תוכן הקלטות חייב להישאר מקומי. + + ב-CI, הגדירו `FAILPROOFAI_CLOUD_TOKEN` מחנות הסודות במקום `read -s`, והשאירו את עקבוב ה-shell (`set -x`) כבוי, או העקבוב מדפיס את המפתח. + + + על מכונה שכבר **מוגדרת**, `failproofai config --connect ` רושמת אותה ושום דבר אחר. אל תשתמשו בצורה זו לעבור ראשון: היא חוזרת לפני שה-daemon או איזה חיבור יש במקום, ומשאירה מכונה שמופיעה ב-Cloud אך לא אוספת ולא אוכפת שום דבר. + -חיבור ל-Cloud מאמת את ingestion של אירועים ו-policy delivery באופן עצמאי. מפתח עשוי אפוא להיות תקף אך חסר הרשאה אחת נדרשת. השתמש ב-`failproofai config --status` כדי לראות איזו יכולת מוגדרת. +התחברות ל-Cloud מאמתת ספיגת אירועים והעברת מדיניות בנפרדות. מפתח עשוי אפוא להיות תקף אך חסר הרשאה נדרשת אחת. השתמשו ב-`failproofai config --status` כדי לראות איזו יכולת מוגדרת. - הגדרת Cloud כותבת credentials מקומיות רק לאחר שהיכולת הרלוונטית מצליחה. אימות שנכשל לא משאיר מכונה שנראית מחוברת כאשר היא לא כן. + הגדרת Cloud כותבת אישורים מקומיים רק לאחר שהיכולת הרלוונטית הצליחה. אימות כשל אינו משאיר מכונה שנראית מחוברת כשהיא לא כן. \ No newline at end of file diff --git a/docs/hi/admin/keys-and-permissions.mdx b/docs/hi/admin/keys-and-permissions.mdx index ba9fd66d..c1d1bfea 100644 --- a/docs/hi/admin/keys-and-permissions.mdx +++ b/docs/hi/admin/keys-and-permissions.mdx @@ -1,29 +1,29 @@ --- title: "कुंजियाँ और अनुमतियाँ" -description: "मशीनों, स्वचालन और ऑपरेटरों के लिए स्कोप की गई API कुंजियाँ बनाएँ।" +description: "मशीनों, स्वचालन और ऑपरेटरों के लिए स्कोप्ड API कुंजियाँ बनाएँ।" icon: "key-round" --- -API कुंजियाँ एक संगठन से संबंधित होती हैं और स्पष्ट अनुमतियाँ रखती हैं। agent ingestion, policy delivery, evaluators, CI automation और प्रशासनिक स्क्रिप्ट के लिए अलग-अलग कुंजियों का उपयोग करें। +API कुंजियाँ किसी संगठन से संबंधित होती हैं और स्पष्ट अनुमतियाँ रखती हैं। एजेंट इनजेस्शन, नीति वितरण, मूल्यांकनकर्ताओं, CI ऑटोमेशन और प्रशासनिक स्क्रिप्ट के लिए अलग-अलग कुंजियों का उपयोग करें। ## कुंजी बनाएँ और घुमाएँ - 1. **Administration → Keys** पर जाएँ, **new key** चुनें, और एक workload का नाम दर्ज करें। - 2. एक permission set चुनें और व्यक्तिगत अनुमतियों को केवल तब समायोजित करें जब preset अपर्याप्त हो। - 3. कुंजी बनाएँ और तुरंत इसके one-time secret को कॉपी करें। - 4. बाद में कुंजी खोलें ताकि grants को अपडेट करें, इसे अक्षम करें, या secret को पुनः उत्पन्न करें। + 1. **Administration → Keys** पर जाएँ, **new key** का चयन करें, और कार्यभार का नाम दर्ज करें। + 2. अनुमति सेट चुनें और जब प्रीसेट अपर्याप्त हो तो केवल अलग-अलग अनुमतियों को समायोजित करें। + 3. कुंजी बनाएँ और इसके एकबारी रहस्य को तुरंत कॉपी करें। + 4. बाद में कुंजी खोलें अनुदान अपडेट करने, इसे अक्षम करने, या रहस्य पुनः उत्पन्न करने के लिए। - Creation drawer वह जगह है जहाँ आप workload द्वारा आवश्यक सबसे संकीर्ण grants चुनते हैं। + निर्माण दराज वह स्थान है जहाँ आप कार्यभार द्वारा आवश्यक सबसे संकीर्ण अनुदान चुनते हैं। - ![नई API कुंजी drawer जिसमें permission presets और व्यक्तिगत grants हैं।](/images/dashboard/key-create.png) + ![अनुमति प्रीसेट और व्यक्तिगत अनुदान के साथ नई API कुंजी दराज।](/images/dashboard/key-create.png) - निर्माण के बाद, Keys page persistent metadata और management actions दिखाता है। one-time secret फिर से दिखाई नहीं देता। + निर्माण के बाद, Keys पृष्ठ स्थायी मेटाडेटा और प्रबंधन क्रियाएँ दिखाता है। एकबारी रहस्य फिर से नहीं दिखाया जाता है। - ![API Keys page जिसमें key permissions, creation time, और regenerate और disable actions हैं।](/images/dashboard/api-keys.png) + ![API Keys पृष्ठ कुंजी अनुमतियाँ, निर्माण समय, और पुनः उत्पन्न और अक्षम क्रियाएँ दिखा रहा है।](/images/dashboard/api-keys.png) - इस सूची का उपयोग करके regularly grants की समीक्षा करें और उन कुंजियों को अक्षम करें जो अब किसी सक्रिय workload से संबंधित नहीं हैं। + इस सूची का उपयोग अनुदान की नियमित रूप से समीक्षा करने और उन कुंजियों को अक्षम करने के लिए करें जो अब सक्रिय कार्यभार से मैप नहीं करती हैं। ```bash @@ -36,25 +36,25 @@ API कुंजियाँ एक संगठन से संबंधित fp keys disable production-agents ``` - Create/regenerate output को securely redirect या capture करें; secret एक बार लौटाया जाता है। + सुरक्षित रूप से create/regenerate आउटपुट को रीडायरेक्ट या कैप्चर करें; रहस्य एक बार लौटाया जाता है। -एक जुड़ी Failproof AI मशीन के लिए आवश्यक दो अनुमतियाँ स्वतंत्र हैं: +एक जुड़ी हुई Failproof AI मशीन द्वारा आवश्यक दो अनुमतियाँ स्वतंत्र हैं: -- `events:add` events और session data भेजता है। -- `policies:pull` assigned policy deployments को पुनः प्राप्त करता है। +- `events:add` इवेंट और सेशन डेटा भेजता है। +- `policies:pull` निर्दिष्ट नीति तैनातियों को पुनः प्राप्त करता है। -Key secrets तब दिखाए जाते हैं जब create या regenerate किए जाते हैं। उन्हें एक secret manager में store करें और उन्हें एक operator की interactive credentials को पुनः उपयोग किए बिना rotate करें। +कुंजी रहस्य बनाए जाने या पुनः उत्पन्न होने पर दिखाए जाते हैं। उन्हें एक रहस्य प्रबंधक में संग्रहीत करें और किसी ऑपरेटर की इंटरैक्टिव क्रेडेंशियल्स को पुनः उपयोग किए बिना उन्हें घुमाएँ। -## अनुमति कैटलॉग +## अनुमति सूची -| Area | Permissions | +| क्षेत्र | अनुमतियाँ | | --- | --- | | Events | `events:add`, `events:read` | | Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` केवल human-session है | | Users | `users:create`, `users:read`, `users:update`, `users:delete` | -| Evaluations | `evaluations:read`, `evaluations:trigger` | +| Evaluations | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | | Dashboards | `dashboards:read`, `dashboards:write`, `dashboards:delete` | | Queries | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | | Assistant | `agent:use` | @@ -65,10 +65,10 @@ Key secrets तब दिखाए जाते हैं जब create या r | Policies | `policies:read`, `policies:write`, `policies:pull` | | Usage | `usage:read` | -`orgs:admin` instance operator के लिए आरक्षित है और एक organization key या सामान्य सदस्य को दिया नहीं जा सकता। सेवानिवृत्त `incidents:*` और `alerts:ack` tokens compatibility के लिए स्वीकार किए जाते हैं और वर्तमान `issues:*` अनुमतियों में normalize होते हैं। +`orgs:admin` इंस्टेंस ऑपरेटर के लिए आरक्षित है और किसी संगठन कुंजी या साधारण सदस्य को प्रदान नहीं किया जा सकता है। सेवानिवृत्त `incidents:*` और `alerts:ack` टोकन अनुकूलता के लिए स्वीकार किए जाते हैं और वर्तमान `issues:*` अनुमतियों को सामान्य करते हैं। -Builtin permission sets `read-only`, `standard`, और `admin` हैं। `standard` read permissions में evaluation triggering, query execution, issue response, और assistant use जोड़ता है। Key creation human-only grants को हटाता है भले ही एक permission set में उनके हों। +बिल्ट-इन अनुमति सेट `read-only`, `standard`, और `admin` हैं। `standard` मूल्यांकन ट्रिगरिंग, क्वेरी निष्पादन, समस्या प्रतिक्रिया और सहायक उपयोग को अनुमतियों में जोड़ता है। कुंजी निर्माण मानव-केवल अनुदान को हटाता है यहाँ तक कि जब एक अनुमति सेट में वह हों। - Instance-scoped keys `X-AgentEye-Org` header के साथ एक organization चुन सकते हैं। multi-organization deployments पर इसे स्पष्ट रूप से सेट करें; चूक से default organization का चयन हो सकता है। + इंस्टेंस-स्कोप्ड कुंजियाँ `X-AgentEye-Org` हेडर के साथ किसी संगठन का चयन कर सकती हैं। बहु-संगठन तैनातियों पर इसे स्पष्ट रूप से सेट करें; चूक डिफ़ॉल्ट संगठन का चयन कर सकती है। \ No newline at end of file diff --git a/docs/hi/evaluations/deploy.mdx b/docs/hi/evaluations/deploy.mdx new file mode 100644 index 00000000..d1cd8a16 --- /dev/null +++ b/docs/hi/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "एक मूल्यांकन को तैनात करें और संस्करण बनाएं" +description: "एक अपरिवर्तनीय संस्करण तैनात करें, देखें कि क्या लाइव है, नए संस्करण प्रकाशित करें, रोलबैक करें, और उन सत्रों को स्कोर करें जो आपके पास पहले से हैं।" +icon: "cloud-upload" +--- + +## इसे तैनात करें + +लेखन पृष्ठ के निचले भाग में **deploy `@`** चुनें। संस्करण प्रकाशित होने के बाद अपरिवर्तनीय हो जाता है: उस समय से, हर सत्र जो समाप्त होता है, और जिसकी शर्त लागू होती है, इसके द्वारा स्कोर किया जाता है। + +## देखें कि क्या लाइव है + +**Analyze → eval authoring** आपके संगठन की होस्ट की गई परिभाषाएं सूचीबद्ध करता है, जो मूल्यांकन प्रबंधित मूल्यांकनकर्ता इसके लिए चलाता है। प्रत्येक पंक्ति दिखाता है: + +- इसका नाम, कुंजी, संस्करण, और परिणाम प्रकार +- इसका स्रोत चेकसम, जो तैनात संशोधनों को कोड खोले बिना अलग बताता है +- क्या यह **conditional** है या **सभी पूर्ण किए गए सत्रों** पर चलता है — शर्त एक मूल्यांकन को विशेष एजेंट या वातावरण तक सीमित करती है +- इसका टाइमआउट, इसके लेबल, और जब यह अंतिम बार बदला गया था + +![होस्ट की गई परिभाषाओं की सूची: प्रत्येक मूल्यांकन का नाम, कुंजी, संस्करण, परिणाम प्रकार, चेकसम, टाइमआउट, और दायरा, नए संस्करण और सक्षम या अक्षम विकल्प के साथ।](/images/dashboard/eval-definitions.png) + +सूची को खोजें, या इसे स्थिति के आधार पर फ़िल्टर करें। आपके स्वयं के कार्यकर्ता द्वारा पंजीकृत मूल्यांकन यहां सूचीबद्ध नहीं हैं; उनके परिणाम [मूल्यांकन पृष्ठ](/hi/sessions/evaluations) पर **customer** टैग रखते हैं, और होस्ट किए गए **managed** रखते हैं। + +एक संगठन के पास एक बार में सक्षम होने वाले 100 विभिन्न होस्ट किए गए मूल्यांकन हो सकते हैं। + +## एक नया संस्करण प्रकाशित करें + +एक पंक्ति पर **new version** चुनें। लेखन पृष्ठ उस संस्करण के कोड के साथ खुलता है; इसे बदलें, परीक्षण करें, और तैनात करें। इसकी कुंजी और परिणाम प्रकार स्थानांतरित होते हैं और परिवर्तन नहीं हो सकते हैं। + +एक उत्तराधिकारी प्रकाशित करना अपने पूर्ववर्ती को अक्षम करता है और इसे सूची पर रखता है। परिणाम उस संस्करण को रखते हैं जिसने उन्हें बनाया, इसलिए एक चार्ट दिखाता है कि नया तर्क कब प्रभावी हुआ। + +## रोलबैक करें + +वर्तमान संस्करण पर **disable** चुनें और उस पर **enable** चुनें जिसे आप वापस चाहते हैं। कुछ नहीं हटाया जाता, और हर परिणाम वैसा ही रहता है जैसा था। + +## एक मूल्यांकन को रोकें + +**disable** चुनें। कोई सक्षम संस्करण नहीं होने से, यह नए सत्रों पर चलना बंद कर देता है। अपने स्वयं के कार्यकर्ता द्वारा चलाए जाने वाले मूल्यांकन को रोकने के लिए, इसे पंजीकृत करना बंद करें: इसे कार्यकर्ता से हटाएं, या कार्यकर्ता को रोकें। + +## आपके पास पहले से मौजूद सत्रों को स्कोर करें + +मूल्यांकन आगे चलता है: एक संस्करण जो अभी तैनात किया गया है, कभी भी एक सत्र को स्कोर नहीं करता जो इससे पहले समाप्त हुआ था। इतिहास को स्कोर करने के लिए, eval लेखन पृष्ठ पर **score sessions you already have** खोलें, 90 दिनों तक की एक विंडो चुनें और, वैकल्पिक रूप से, एक एकल मूल्यांकन चुनें, और चलाने से पहले गिनती करें। गिनती बिल्कुल वही है जो चलेगी, और इसमें प्रत्येक सत्र-और-मूल्यांकन जोड़ी एक बिल योग्य मूल्यांकन है। + +यह केवल अंतराल को भरता है। एक सत्र जिसके पास पहले से उस मूल्यांकन के लिए एक परिणाम है, इसे रखता है, और एक ही विंडो को दो बार चलाना कुछ भी नया स्कोर नहीं करता है। + +एक सत्र को फिर से स्कोर करने के लिए — एक सुधार के बाद, या एक सत्र के लिए जो कभी स्वच्छ रूप से समाप्त नहीं हुआ — इसके पृष्ठ पर **re-evaluate** चुनें। नया परिणाम सत्र के इतिहास में जोड़ा जाता है; पहले वाले रहते हैं। + +## अनुमतियां + +| अनुमति | आपको अनुमति देता है | +| --- | --- | +| `evaluations:read` | परिणाम देखें, और eval लेखन पृष्ठ खोलें | +| `evaluations:trigger` | होस्ट की गई परिभाषाओं को देखें, तैनात करें, संस्करण बनाएं, सक्षम और अक्षम करें; उन्हें परीक्षण करें; इतिहास को स्कोर करें; एक सत्र को फिर से मूल्यांकन करें | +| `events:read` | वास्तविक सत्रों के विरुद्ध परीक्षण करें, और `evaluations:trigger` के शीर्ष पर अपनी पेलोड कुंजियों में मसौदे को आधार दें | +| `evaluations:run` | अपने स्वयं के मूल्यांकनकर्ता कार्यकर्ता को चलाएं | \ No newline at end of file diff --git a/docs/hi/evaluations/overview.mdx b/docs/hi/evaluations/overview.mdx new file mode 100644 index 00000000..72cbeed8 --- /dev/null +++ b/docs/hi/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "एजेंट्स का मूल्यांकन करें" +description: "हर पूरे सत्र को अपनी परिभाषित मूल्यांकन के साथ स्कोर करें: होस्ट किए गए Python चेक, या अपने वर्कर में LLM judges।" +icon: "gauge" +--- + +एक मूल्यांकन एक पूरे एजेंट सत्र को स्कोर करता है। जब कोई सत्र समाप्त होता है, तो हर सक्षम मूल्यांकन जो उस पर लागू होता है, चलता है और यह दर्ज करता है कि उसे क्या मिला, जिसके साथ तर्क आप ट्रेस के बगल में पढ़ सकते हैं: + +- 0 से 1 तक एक **स्कोर**, वैकल्पिक रूप से पास या विफल चिह्नित +- एक **मेट्रिक**, जैसे गिनती, अवधि, या लागत, इसकी इकाई के साथ +- एक **assertion**, जो पास हुआ या नहीं + +## दो प्रकार के मूल्यांकनकर्ता + +| | होस्ट किया गया Python | आपका अपना वर्कर | +| --- | --- | --- | +| लिखा गया | डैशबोर्ड में, **Analyze → eval authoring** के तहत | Python में, [Evaluator SDK](/hi/reference/evaluator-sdk) के साथ | +| चलता है | Failproof AI के प्रबंधित मूल्यांकनकर्ता पर, एक सैंडबॉक्स में | आपके बुनियादी ढांचे पर | +| सर्वोत्तम | नियतात्मक, कोड-आधारित जांच | LLM judges, मॉडल कॉल, पैकेज, secrets, नेटवर्क एक्सेस, भारी प्रोसेसिंग | + +होस्ट किया गया Python जानबूझकर छोटा है: एक अभिव्यक्ति, कोई आयात नहीं, कोई नेटवर्क नहीं। कुछ भी जो एक मॉडल की आवश्यकता है — एक LLM judge जो स्कोर करता है कि क्या कोई उत्तर प्रासंगिक था, कहें — इसके बजाय आपके अपने वर्कर में चलता है। दोनों प्रकार को कोई इनबाउंड कनेक्शन की आवश्यकता नहीं है: वर्कर पूरे सत्रों को दावा करते हैं और आउटबाउंड HTTPS पर परिणाम जमा करते हैं। + +## प्रत्येक संगठन अपने एजेंट्स का मूल्यांकन करता है + +मूल्यांकन उस संगठन के हैं जो उन्हें परिभाषित करता है। किसी उदाहरण पर प्रत्येक संगठन अपने स्वयं के लिखता है — इसकी अपनी जांच, शर्तें, सीमाएं, और लेबल — संस्करण और किसी अन्य को प्रभावित किए बिना उन्हें तैनात करता है, और केवल अपने परिणाम देखता है। उन परिणामों को एजेंट, पर्यावरण, मूल्यांकन, और समय के आधार पर फ़िल्टर करें, या सहायक से उनके बारे में पूछें। + +## पहले ड्राफ्ट से लाइव स्कोर तक + + + + वर्णन करें कि क्या मापना है और सहायक को इसे ड्राफ्ट करने दें, या इसे स्वयं लिखें। [एक मूल्यांकन लिखें](/hi/evaluations/write) देखें। + + + इससे पहले कि यह लाइव हो, इसे वास्तविक सत्रों के विरुद्ध चलाएं; कुछ भी संग्रहीत नहीं है। [एक मूल्यांकन का परीक्षण करें](/hi/evaluations/test) देखें। + + + एक अपरिवर्तनीय संस्करण तैनात करें, जैसे-जैसे यह विकसित होता है नए संस्करण प्रकाशित करें, और एक पहले वाले पर वापस रोल करें। [तैनात और संस्करण करें](/hi/evaluations/deploy) देखें। + + + समय के साथ स्कोर चार्ट करें, एजेंट्स और पर्यावरण की तुलना करें, और सहायक से पूछें। [मूल्यांकन परिणाम पढ़ें](/hi/sessions/evaluations) देखें। + + + +मूल्यांकन आगे की ओर चलता है: अभी तैनात किया गया एक संस्करण उन सत्रों को स्कोर करता है जो अब से समाप्त होते हैं। जो सत्र आपके पास पहले से हैं उन्हें स्कोर करने के लिए, [उन्हें backfill करें](/hi/evaluations/deploy#score-sessions-you-already-have)। \ No newline at end of file diff --git a/docs/hi/evaluations/test.mdx b/docs/hi/evaluations/test.mdx new file mode 100644 index 00000000..559fb1af --- /dev/null +++ b/docs/hi/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "एक मूल्यांकन का परीक्षण करें" +description: "इसे तैनात करने से पहले अपने वास्तविक सत्रों के विरुद्ध एक मूल्यांकन चलाएं। कुछ भी संग्रहीत नहीं है।" +icon: "flask-conical" +--- + +**इस मूल्यांकन का परीक्षण करें**, लेखन पृष्ठ पर, कोड को इसे तैनात किए बिना मूल्यांकनकर्ता फ़्लीट पर आपके वास्तविक सत्रों के विरुद्ध चलाता है। कुछ भी संग्रहीत नहीं है: यहाँ एक विफलता एक पूर्वावलोकन है, और तैनाती हमेशा की अनुमति है। + + + + **check** चुनें ताकि कोड और शर्त को सैंडबॉक्स के नियमों के विरुद्ध संकलित किया जा सके बिना उन्हें किसी भी सत्र पर चलाए। + + + मेल खाने वाले सत्रों को एजेंट, पर्यावरण, समय या सत्र आईडी द्वारा सीमित करें, और 10 तक को चिह्नित करें। ऐसे सत्र शामिल करें जिनमें मूल्यांकन विफल होना चाहिए और साथ ही वे जिनमें सफल होना चाहिए। + + + **N सत्रों के विरुद्ध चलाएं** चुनें, और प्रत्येक पंक्ति को पढ़ें। + + + +| पंक्ति | इसका मतलब क्या है | +| --- | --- | +| **ok** | यह चल गया। पंक्ति हर स्कोर, मेट्रिक और असर्शन को सूचीबद्ध करती है जो इसने लौटाई, और इसमें कितना समय लगा। | +| **skipped** | शर्त ने `False` लौटाई, इसलिए मूल्यांकन नहीं चला। यह एक विफलता नहीं है, एक छोड़ा गया है। | +| Failed | यह उभरा, समय समाप्त हो गया, या ऐसा कुछ उपयोग किया जो सैंडबॉक्स अस्वीकार करता है। पंक्ति कहती है कि कौन सा, और **इसे ठीक करें** त्रुटि को सहायक को सौंपता है जब यह मदद कर सकता है। | + +![परीक्षण यह मूल्यांकन पैनल: एजेंट द्वारा चुने गए तीन सत्र, दो ठीक और एक छोड़ा गया क्योंकि इसकी शर्त False लौटाई।](/images/dashboard/eval-test.png) + +एक परिणाम वर्तमान होना बंद हो जाता है जिस क्षण आप कोड को संपादित करते हैं; इसे फिर से उपयोग करने के बजाय मंद कर दिया जाता है। \ No newline at end of file diff --git a/docs/hi/evaluations/write.mdx b/docs/hi/evaluations/write.mdx new file mode 100644 index 00000000..78c8d527 --- /dev/null +++ b/docs/hi/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "एक मूल्यांकन लिखें" +description: "वर्णन करें कि क्या मापना है और सहायक को एक होस्टेड Python मूल्यांकन का मसौदा तैयार करने दें, या कोड स्वयं लिखें। LLM जजों को आपके अपने worker में चलाया जाता है।" +icon: "file-pen-line" +--- + +होस्टेड मूल्यांकन छोटे, नियतात्मक Python होते हैं, जो डैशबोर्ड में लिखे जाते हैं और Failproof AI के evaluator fleet पर चलाए जाते हैं। भारी तर्क — एक LLM judge, एक पैकेज, एक secret, एक नेटवर्क कॉल — इसके बजाय [आपके अपने worker](#write-it-in-your-own-worker) में चलता है। + +## विवरण से मसौदा तैयार करें + +1. **Analyze → eval authoring** पर जाएं और **new eval** चुनें। +2. सादी English में मापने के लिए क्या है यह बताएं, या **start from an example…** से चुनें, और **draft** को चुनें। +3. Fields और code की समीक्षा करें, फिर इसे [test करें](/hi/evaluations/test) और [deploy करें](/hi/evaluations/deploy)। + +![eval authoring पेज एक मसौदा मूल्यांकन के साथ: विवरण, मसौदे पर सहायक की नोट्स, और नाम, कुंजी, संस्करण, परिणाम, timeout, लेबल्स, और condition fields।](/images/dashboard/eval-authoring-draft.png) + +मसौदा आपके संगठन की अपनी events पर आधारित है: पेज पढ़ता है कि आपके sessions ने पिछले सात दिनों में कौन सी payload keys ले जाई हैं, इसलिए code उन keys को पढ़ता है जो मौजूद हैं अनुमान लगाने के बजाय। मसौदे को सौंपने से पहले, सहायक इसे आपके हाल के पांच sessions के साथ परीक्षण करता है, कुछ भी ठीक करता है जो वह साबित कर सकता है कि टूटा हुआ है — तीन राउंड तक — और एक बार जांच करता है कि code आपने जो पूछा था वह मापता है। विवरण को विशिष्ट रखें: व्यापक prompts धीमे हो सकते हैं और timeout हो सकते हैं। किसी भी तरह से code की समीक्षा करें; deploying कभी भी blocked नहीं होता है। + +## Fields सेट करें + +| Field | यह क्या है | +| --- | --- | +| name | जो लोग देखते हैं। बाद में editable | +| key | स्थिर identifier जिसके तहत इसके परिणाम chart होते हैं, जैसे `code_assistant_quality_gate` | +| version | कोई भी संस्करण string बिना spaces के, जैसे `1.0.0` | +| result | **score** (0 से 1), **metric** (एक संख्या एक इकाई के साथ), या **assertion** (पास किया गया या नहीं) | +| timeout seconds | Default 30। Sandbox किसी भी एकल run को 60 पर रोकता है | +| labels | 20 तक, comma-separated। बाद में editable | +| condition | Optional। एक Python expression; मूल्यांकन केवल उन sessions पर चलता है जहां यह `True` है | + +एक मूल्यांकन को उन agents और environments तक सीमित करने के लिए condition का उपयोग करें जिसके लिए यह meant है: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +Key, version, result type, condition, और code deployment के बाद immutable हैं: इनमें से कोई भी बदलने के लिए, एक नया version publish करें। Name, labels, और क्या यह enabled है यह editable रहता है। + +## कोड स्वयं लिखें + +**evaluator code** एक Python expression है जो `EvalResult(...)` return करता है, जिसमें `session` in scope है। यह tool results के share को score करता है जो ok आए: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +एक result मूल्यांकन की अपनी key के साथ शुरू होता है, अपने declared type में: score evaluation के लिए `score=`, या एक metric या assertion evaluation के लिए key के नाम से एक `metrics` या `assertions` entry। अन्य metrics और assertions इसके साथ ride करते हैं, एक run में 25 परिणाम तक। + +| In scope | आपको देता है | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count`, और `events`, plus `count(event_type)` और `events_of_type(event_type)` | +| प्रत्येक event | `id`, `ts`, `event_type`, और `payload` | +| Result types | `EvalResult`, `Score`, `Metric`, `Assertion`, और एक condition के लिए `ConditionResult` | +| Builtins | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +कुछ भी और reachable नहीं है: कोई imports नहीं, और session data और plain string और dictionary methods जैसे `get`, `lower`, और `split` से परे कोई attributes नहीं, जिन्हें reference किए जाने के बजाय called होना चाहिए। Payload keys वह हैं जो आपके agents भेजते हैं — `status` ऊपर केवल एक example है — इसलिए उन्हें एक real session से पढ़ें। **format** code को tidy करता है और **fix** सहायक को इसे repair करने के लिए कहता है। Code 128 KiB तक हो सकता है, और condition 16 KiB तक हो सकता है। + +![evaluator code editor, format और fix के साथ, एक मसौदा मूल्यांकन की assertions दिखा रहा है।](/images/dashboard/eval-authoring-code.png) + +## इसे अपने worker में लिखें + +जब एक मूल्यांकन को एक model, एक पैकेज, एक secret, या नेटवर्क की आवश्यकता होती है, तो इसे [Evaluator SDK](/hi/reference/evaluator-sdk) के साथ लिखें और इसे अपने infrastructure पर चलाएं। यह same result types का उपयोग करता है, और इसके परिणाम hosted ones के बगल में दिखाई देते हैं, **customer** tagged: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/hi/policies/deploy.mdx b/docs/hi/policies/deploy.mdx index be5385ab..55967e5a 100644 --- a/docs/hi/policies/deploy.mdx +++ b/docs/hi/policies/deploy.mdx @@ -1,51 +1,92 @@ --- -title: "नीतियों को तैनात करें" -description: "समीक्षित नीति संस्करण को इच्छित मशीनों पर रोल आउट करें।" +title: "एक नीति तैनात करें" +description: "परीक्षित नीति संस्करण को मशीनों पर निरीक्षण मोड में रखें, इसे लागू करें, और पुष्टि करें कि प्रत्येक मशीन ने इसे उठा लिया है।" icon: "cloud-upload" --- -एक तैनाती एक या अधिक नीति संस्करणों को नामांकित मशीनों के एक लक्ष्य सेट से जोड़ता है। +एक तैनाती प्रकाशित नीति संस्करणों को एक मशीन पर रखती है, प्रत्येक में दो प्रभावों में से एक होता है: -## तैनाती लागू करें +- **Observe** रिकॉर्ड करता है कि नीति क्या करती, और कुछ भी ब्लॉक नहीं करती। +- **Enforce** निर्णय पर कार्य करता है: एक `deny` कॉल को ब्लॉक करता है और एक `instruct` एजेंट को निर्देशित करता है। + +## एक मशीन जोड़ें + +एक मशीन **Admin → enforcement** के तहत दिखाई देती है जब यह Cloud से जुड़ी होती है। यदि जो आप चाहते हैं वह वहां अभी तक नहीं है: - 1. **Admin → enforcement** पर जाएं, मशीन को खोजें, और इसकी पंक्ति को विस्तारित करें। - 2. **edit** चुनें, समीक्षित नीति संस्करण जोड़ें, और **observe** या इसके प्रवर्तन प्रभाव को चुनें। - 3. परिवर्तन लागू करें, फिर मशीन की अगली जांच के लिए प्रतीक्षा करें और इसकी तैनाती और कवरेज स्थिति की पुष्टि करें। - 4. लाइव निर्णयों का निरीक्षण करने के लिए **Observe → policy** पर जाएं। - - ![नीति संस्करणों, enforce और observe प्रभावों, और तैनाती लागू करने की कार्रवाई के साथ मशीन तैनाती संपादक।](/images/dashboard/enforcement-editor.png) + 1. **Administration → Keys** पर जाएं और `policies:pull` के साथ एक कुंजी बनाएं, ताकि मशीन तैनाती प्राप्त कर सके, और `events:add`, ताकि इसके निर्णय Cloud तक पहुंचें। + 2. मशीन को उस कुंजी से कनेक्ट करें — [Cloud में एक मशीन कनेक्ट करें](/hi/start/setup#connect-a-machine-to-cloud) इसके माध्यम से चलता है। + 3. पुष्टि करें कि यह **Admin → enforcement** के तहत दिखाई देता है। - `fp fleet` के साथ CLI से तैनात करें। लागू करने से पहले परिणामी सेट की समीक्षा करें — `deploy` पूरी योजना प्रिंट करता है और **केवल `--json` के बिना एक इंटरैक्टिव टर्मिनल पर** पूछता है। `--json` के तहत, `--yes` के साथ, या stdin को रीडायरेक्ट के साथ (एक CI चरण, एक स्क्रिप्ट, एक एजेंट शेल आउट) यह बिना योजना और बिना प्रॉम्प्ट के तुरंत लागू होता है — इसलिए यदि आप समीक्षा चाहते हैं तो पहले `fp fleet show ` चलाएं: + मशीन पर: + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + एक टर्मिनल में, `failproofai config` पूछता है कि Cloud से कनेक्ट करना है या नहीं और एक मुखौटा प्रॉम्प्ट पर कुंजी लेता है। फिर `fp fleet list` के साथ कहीं से भी पुष्टि करें कि मशीन नामांकित है। + + + +## Observe मोड में तैनात करें + + + + 1. **Admin → enforcement** पर जाएं, मशीन खोजें, और इसकी पंक्ति को विस्तारित करें। + 2. **edit** चुनें, परीक्षित नीति संस्करण जोड़ें, और **observe** चुनें। + 3. परिवर्तन लागू करें, फिर मशीन के अगले चेक-इन का इंतज़ार करें और इसकी तैनाती और कवरेज स्थिति की पुष्टि करें। + 4. **Observe → policy** पर जाएं लाइव निर्णयों का निरीक्षण करने के लिए। + + ![नीति संस्करणों, लागू करें और अवलोकन प्रभाव, और तैनाती कार्रवाई लागू करने के साथ मशीन तैनाती संपादक।](/images/dashboard/enforcement-editor.png) + + ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` इरादा बनाम डिलीवरी दिखाता है (एक मशीन `behind` के रूप में पढ़ी जाती है जब तक वह अगली बार पोल न करे), `fp fleet history ` पीढ़ियों को सूचीबद्ध करता है, और `fp fleet rollback ` एक को पुनः स्थापित करता है — यह अस्वीकार करता है यदि वह पीढ़ी एक नीति का नाम रखती है जब से अक्षम या हटाई गई है। + `:observe` प्रत्यय यही है जो इसे observe बनाता है: एक साधारण `--add no-force-push` उस नीति के लिए मशीन के पास पहले से जो प्रभाव है उसे रखता है, और अन्यथा लागू करता है। इसे बाद में `--add no-force-push:enforce` के साथ लागू करने के लिए स्विच करें। + + `deploy` **मशीन के संपूर्ण नीति सेट को प्रतिस्थापित करता है** परिणाम के साथ। यह योजना प्रिंट करता है, फिर लागू करने से पहले पूछता है — लेकिन केवल एक इंटरैक्टिव टर्मिनल पर। `--yes` के साथ, `fp --json` के तहत, या stdin पुनर्निर्देशित के साथ (एक CI कदम, एक स्क्रिप्ट, एक एजेंट शेल आउट) यह बिना पूछे लागू होता है; योजना अभी भी प्रिंट की जाती है, या `--json` के तहत `plan` के रूप में लौटाई जाती है। - `failproofai config --status` के साथ मशीन की जांच करें, और तैनाती के बाद गतिविधि Cloud तक पहुंचती है यह सत्यापित करने के लिए `fp sessions --env production --since 24h` और `fp events --event-type hook_completed` का उपयोग करें। + मशीन पर, `failproofai policies` Cloud-प्रबंधित नीतियों को सूचीबद्ध करता है जो यह चला रहा है और `failproofai config --status` इसका कनेक्शन दिखाता है। `fp sessions --env production --since 24h` और `fp events --event-type hook_completed` का उपयोग करके इसकी गतिविधि Cloud तक पहुंचती है यह पुष्टि करें। - - एक संवेदनशील संस्करण तैनात करें, न कि एक परिवर्तनशील ड्राफ्ट, एक गैर-उत्पादन मशीन या छोटे समूह से शुरू करें जिसके सत्रों का आप निरीक्षण कर सकते हैं। + + प्रकाशित संस्करण और मशीनें चुनें जिन पर यह चलना चाहिए। - - काम को अवरुद्ध किए बिना मेलों, कारणों, प्रभावित उपकरणों, और गलत सकारात्मक की समीक्षा करें। + + मिलान, कारण, प्रभावित उपकरण, और झूठी सकारात्मकता की समीक्षा करें जबकि कुछ भी ब्लॉक न हो। - - अवलोकित मेलों के बाद प्रचार करें जो असुरक्षित कार्यों को मान्य लोगों से अलग करते हैं, फिर पुष्टि करें कि हर इच्छित मशीन ने तैनाती को खींचा है और निर्णय रिपोर्ट कर रही है। + + प्रभाव को लागू करने के लिए स्विच करें एक बार जब देखी गई मिलान असुरक्षित कार्यों को वैध लोगों से अलग कर दे, फिर पुष्टि करें कि हर इच्छित मशीन ने परिवर्तन को खींचा है और निर्णयों की रिपोर्टिंग कर रही है। -मशीनों को `policies:pull` क्षमता की आवश्यकता है। ईवेंट रिपोर्टिंग को अलग से `events:add` द्वारा नियंत्रित किया जाता है; दोनों को सत्यापित करें जब आप Cloud विश्लेषण और प्रवर्तन की अपेक्षा करते हैं। +## कवरेज जांचें + +कवरेज का उत्तर देता है कि क्या एक नीति जहां जोखिम है वहां चल रही है। + +1. **Admin → enforcement** पर जाएं और लागू करने और अवलोकन करने वाली कुल की समीक्षा करें। +2. ID या लेबल द्वारा एक मशीन खोजें, या एक नीति से अनुपलब्ध मशीनों के लिए फ़िल्टर करें। +3. निर्दिष्ट नीतियों, रिपोर्ट की गई तैनाती, अंतिम चेक-इन, और इतिहास की तुलना करने के लिए एक पंक्ति को विस्तारित करें। +4. मशीन के पोलिंग अंतराल के बाद ताज़ा करें जब एक लागू तैनाती अभी भी लंबित है। + +![नीति कवरेज, मशीन तैनाती स्थिति, और अवलोकन और लागू असाइनमेंट दिखाने वाली enforcement fleet।](/images/dashboard/enforcement-fleet.png) + +ऐसी मशीनों की तलाश करें जिन्होंने कभी नवीनतम तैनाती को नहीं खींचा, नामांकित मशीनें जिन्होंने रिपोर्टिंग बंद की हैं, एक गलत पर्यावरण को निर्दिष्ट एक नीति, और एक बाधित अपडेट के बाद संस्करण ड्रिफ्ट: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - प्रवर्तन प्रबंधन एक प्रशासनिक Cloud वर्कफ्लो है। केवल-रूट प्रवर्तन मार्गों को सामान्य ग्राहक `/v1` API एंडपॉइंट के रूप में न मानें। + Enforcement प्रबंधन एक प्रशासनिक Cloud वर्कफ़्लो है। root-only enforcement मार्गों को साधारण ग्राहक `/v1` API endpoints के रूप में न मानें। \ No newline at end of file diff --git a/docs/hi/policies/editor.mdx b/docs/hi/policies/editor.mdx index 29109750..203ad9e3 100644 --- a/docs/hi/policies/editor.mdx +++ b/docs/hi/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "नीति संपादक" -description: "एक पुष्ट विफलता मोड से संस्करणित नीतियां बनाएं और संशोधित करें।" +title: "एक नीति लिखें" +description: "Failproof AI को ऑडिट निष्कर्ष से एक नीति ड्राफ्ट करने दें, या स्रोत स्वयं लिखें, फिर इसकी समीक्षा करें, परीक्षण करें, और प्रकाशित करें।" icon: "file-pen-line" --- -किसी खोज या समस्या को एक तैनाती योग्य नियम में बदलने के लिए नीति संपादक का उपयोग करें। लेखन को तैनाती से अलग रखें ताकि एक ड्राफ्ट जीवंत व्यवहार को चुप्पी से बदल न सके। +एक नीति लिखने के दो तरीके हैं: Failproof AI को ऑडिट निष्कर्ष से ड्राफ्ट करने दें, या स्रोत स्वयं लिखें। जब तक आप प्रकाशित या तैनात करना चुनते हैं, तब तक कुछ भी प्रकाशित या तैनात नहीं होता है। -जब किसी समस्या का एक दोहराए जाने योग्य कार्य पैटर्न हो, तो इसे **विश्लेषण → समस्याएं** के तहत खोलें और **नीति उत्पन्न करें** का चयन करें। Failproof AI पहले समझाता है कि क्या कोई नीति समस्या को व्यक्त कर सकती है, फिर समीक्षित इरादे और खोज संदर्भ को संपादक में ले जाता है। जेनरेट किया गया स्रोत तब तक ड्राफ्ट रहता है जब तक आप इसे प्रकाशित न करें। +## ऑडिट से एक नीति लिखें -## नीति संस्करण प्रकाशित करें +एक ऑडिट एक विफलता खोजता है; एक नीति इसे फिर से होने से रोकती है। Failproof AI निष्कर्ष के अपने साक्ष्य से नीति ड्राफ्ट करता है। + +### 1. एक ऑडिट चलाएं + +उन सत्रों पर [एक ऑडिट चलाएं](/hi/audits/run) जहां विफलता होती है। प्रत्येक निष्कर्ष अपने साक्ष्य सत्र, मूल कारण और एक सुझाए गए रोकथाम पथ के साथ आता है। एक **दोहराए जाने वाली क्रिया पैटर्न** के साथ एक निष्कर्ष से काम करें — एक नीति केवल वही रोक सकती है जो वह हुक ईवेंट में पहचान सकती है। + +### 2. ड्राफ्ट जेनरेट करें - - 1. **व्यवस्थापक → नीति संपादक** पर जाएं और **रचना** में, विफलता मोड का वर्णन करें या JavaScript नीति स्रोत पेस्ट करें। - 2. स्रोत को मान्य करें और रिपोर्ट की गई प्रत्येक त्रुटि को ठीक करें। - 3. नीति पहचान दर्ज करें और इसे प्रकाशित करें, फिर संस्करणों की तुलना या अक्षम करने के लिए **लाइब्रेरी** का उपयोग करें। - 4. जब संस्करण एक मशीन रोलआउट के लिए तैयार हो तो **प्रवर्तन** का चयन करें। + + 1. **Analyze → issues** के तहत निष्कर्ष के मुद्दे को खोलें और इसके उद्धृत सत्र, मूल कारण और सिफारिश की जांच करें। + 2. **generate policy** चुनें। Failproof AI पहले कहता है कि क्या कोई नीति समस्या को बिल्कुल व्यक्त कर सकती है। एक **no policy** परिणाम का मतलब है कि समाधान एक सतर्कता, एक वर्कफ़्लो परिवर्तन, या एक व्यक्ति है — नीति नहीं। + 3. **write this policy** चुनें। मुद्दा शीर्षक, निष्कर्ष, मूल कारण, सिफारिश, और प्रस्तावित प्रवर्तन इरादा **Admin → policy editor** में एक ड्राफ्ट बन जाते हैं। जब आप उम्मीदवारी जांच से असहमत हों तो **open the editor anyway** का उपयोग करें। - ![नीति पहचान, AI-सहायता प्राप्त ड्राफ्टिंग, स्रोत सत्यापन और प्रकाशन नियंत्रण के साथ नीति संपादक रचना दृश्य।](/images/dashboard/policy-editor.png) + ![नीति पहचान, AI-सहायक ड्राफ्टिंग, स्रोत सत्यापन और प्रकाशन नियंत्रण के साथ Policy editor compose दृश्य।](/images/dashboard/policy-editor.png) - `fp policies publish` के साथ CLI से प्रकाशित करें। यह एक **नया संस्करण** बनाता है और कभी भी किसी को जगह पर संपादित नहीं करता है, और यह प्रकाशन से पहले node के साथ स्रोत को पार्स-जांच करता है — डाउनस्ट्रीम में कुछ भी ऐसा नहीं करता है, इसलिए एक सिंटैक्स त्रुटि अन्यथा प्रवर्तन समय पर मशीन पर सामने आती: + साक्ष्य पढ़ें, फिर सहायक के साथ ड्राफ्ट करें। `compose` आपकी समीक्षा के लिए स्रोत प्रिंट करता है और कुछ भी प्रकाशित नहीं करता: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - प्रकाशन कुछ भी तैनात नहीं करता — एक नया संस्करण अप्रयुक्त बैठता है जब तक `fp fleet deploy` इसे मशीन पर नहीं डालता। `fp policies compose ""` Cloud सहायक के साथ स्रोत का ड्राफ्ट करता है और इसे प्रकाशित करने के बजाय समीक्षा के लिए प्रिंट करता है। - - इसके बजाय एक स्थानीय एजेंट CLI में कोई नीति स्थापित करने के लिए (Cloud नहीं), `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project` का उपयोग करें। + `compose` को एक साइन-इन सत्र (`fp login`) की आवश्यकता है जिसकी भूमिका में `policies:write` है; यह API कुंजियों को अस्वीकार करता है। -## लेखन चेकलिस्ट +### 3. ड्राफ्ट की समीक्षा करें + +एक ड्राफ्ट एक शुरुआती बिंदु है, न कि एक फैसला। प्रकाशन से पहले, जांचें कि यह: + +1. विफलता मोड को परिचालन भाषा में नाम देता है। +2. केवल हुक ईवेंट और उपकरणों से मेल खाता है जिनके पास निर्णय लेने के लिए पर्याप्त साक्ष्य है। +3. सबसे संकीर्ण स्थिति का उपयोग करता है जो असुरक्षित क्रिया को पकड़ता है। +4. एक कारण देता है जो एजेंट को बताता है कि इसके बजाय क्या करना चाहिए। +5. `instruct` का उपयोग करता है जहां एजेंट सुरक्षित रूप से पाठ्यक्रम को ठीक कर सकता है, और `deny` केवल वहां जहां क्रिया की अनुमति देना अस्वीकार्य या अपरिवर्तनीय है। + +संपादक में स्रोत को सत्यापित करें और हर रिपोर्ट की गई त्रुटि को ठीक करें। + +### 4. इसे परीक्षण करें, फिर प्रकाशित करें + +स्रोत के अंतर्गत प्रकाशन से पहले **backtest** चलाएं: यह ड्राफ्ट को आपके बेड़े द्वारा पहले से किए गए कॉलों के विरुद्ध फिर से चलाता है और काम करने वाली कॉलों को गिनता है जिन्हें यह बाधित करता। [एक नीति परीक्षण करें](/hi/policies/test) यह और अन्य जांचें कवर करता है। + +जब यह व्यवहार करे, नीति पहचान दर्ज करें और **publish version** चुनें। प्रकाशन एक अपरिवर्तनीय संस्करण बनाता है और कुछ भी तैनात नहीं करता: यह अप्रयुक्त बैठता है जब तक आप इसे [तैनात न करें](/hi/policies/deploy)। एक टर्मिनल से: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` इसे भेजने से पहले स्रोत को पार्स-जांचता है, इसलिए एक सिंटैक्स त्रुटि प्रवर्तन समय पर एक मशीन के बजाय यहां सामने आती है। + +## इसे स्वयं लिखें + +एक नीति `failproofai` API के विरुद्ध JavaScript या TypeScript है: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +यह `production/config.yml`, `/srv/production/config.yml`, `/srv/production`, और `C:\\production\\config.yml` को `Write` और `Edit` दोनों के लिए मेल खाता है, लेकिन `production-backup` नहीं: `production` एक पूरा पथ खंड होना चाहिए। प्रसंग में ईवेंट प्रकार, सामान्यीकृत पेलोड, सत्र मेटाडेटा, पैरामीटर, और उपलब्ध होने पर स्रोत CLI भी होता है — [नीति SDK](/hi/reference/policy-sdk) देखें। + +इसे एक संस्करण के रूप में प्रकाशित करने के लिए, स्रोत को **Admin → policy editor** में **compose** में पेस्ट करें और ऊपर चरण 3 और 4 का पालन करें, या टर्मिनल से `fp policies publish` के साथ फ़ाइल प्रकाशित करें। -1. विफलता मोड को परिचालन भाषा में नाम दें। -2. हुक घटनाएं और उपकरण चुनें जिनमें निर्णय लेने के लिए पर्याप्त सबूत हो। -3. सबसे संकीर्ण शर्त लिखें जो असुरक्षित व्यवहार से मेल खाती हो। -4. एक कारण लौटाएं जो एजेंट या ऑपरेटर को बताता है कि आगे क्या करना है। -5. ऐसे उदाहरण जोड़ें जो मेल खाएं और ऐसे उदाहरण जो अनुमत रहने चाहिए। -6. एक नया संस्करण सहेजें और समीक्षा का अनुरोध करें। +इसे Cloud के बिना एक मशीन पर चलाने के लिए, इसे `.failproofai/policies/` के तहत एक नाम के साथ सहेजें जो `policies.js`, `policies.mjs` या `policies.ts` में समाप्त होता है — वह परियोजना और उपयोगकर्ता दायरे पर स्वचालित रूप से लोड होते हैं — या इसे पथ द्वारा स्थापित करें: -जब एजेंट सुरक्षित रूप से पाठ्यक्रम सुधार सकता है तो `instruct` का उपयोग करें। जब कार्य की अनुमति देने से अस्वीकार्य या अपरिवर्तनीय जोखिम पैदा होता है तो `deny` का उपयोग करें। +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - नीति संस्करण अपरिवर्तनीय तैनाती इनपुट हैं। एक ड्राफ्ट को संपादित करना एक नया संस्करण बनाता है; इसे पहले से ही मशीनों को निर्दिष्ट संस्करण को फिर से लिखना नहीं चाहिए। - \ No newline at end of file +हर नीति को एक नाम दें जो सम्मेलन, कस्टम, पैक, और Cloud-प्रबंधित नीतियों के बीच अद्वितीय है। \ No newline at end of file diff --git a/docs/hi/policies/failure-behavior.mdx b/docs/hi/policies/failure-behavior.mdx index 42bccfe6..d02f1016 100644 --- a/docs/hi/policies/failure-behavior.mdx +++ b/docs/hi/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- title: "विफलता व्यवहार" -description: "समझें कि जब नीति मूल्यांकन या स्थानीय daemon अनुपलब्ध हो तो क्या होता है।" +description: "समझें कि जब नीति मूल्यांकन या स्थानीय डेमॉन उपलब्ध नहीं है तो क्या होता है।" icon: "shield-alert" --- -Failproof AI को इस तरह डिज़ाइन किया गया है कि एक प्रवर्तन विफलता दृश्यमान हो, बजाय जोखिम भरे कार्य को चुप चाप अनुमति देने के। +Failproof AI इस तरह डिज़ाइन किया गया है कि प्रवर्तन विफलता दृश्यमान हो, जोखिम भरे काम को चुप-चाप अनुमति देने के बजाय। ## विफलता-बंद ब्लॉक का निदान करें - 1. **Admin → enforcement** पर जाएँ और मशीन को खोलें। - 2. इसके अंतिम चेक-इन, नियुक्त परिनियोजन और रिपोर्ट की गई परिनियोजन की जांच करें। - 3. **Observe → policy** पर जाएँ और अस्वीकृत निर्णय का सत्र खोलें। - 4. पुष्टि करें कि कारण daemon पहुंच, संस्करण विसंगति, या नीति स्वयं की रिपोर्ट करता है। + 1. **Admin → enforcement** पर जाएं और मशीन को खोलें। + 2. इसकी अंतिम चेक-इन, निर्धारित तैनाती, और रिपोर्ट की गई तैनाती की जांच करें। + 3. **Observe → policy** पर जाएं और अस्वीकृत निर्णय का सेशन खोलें। + 4. पुष्टि करें कि क्या कारण डेमॉन पहुंचयोग्यता, संस्करण विसंगति, या नीति स्वयं की रिपोर्ट करता है। @@ -23,45 +23,47 @@ Failproof AI को इस तरह डिज़ाइन किया गय failproofai config ``` - `failproofai config` को फिर से चलाने से पैकेज अपग्रेड के बाद daemon अपडेट और पुनः शुरू हो जाता है। + `failproofai config` को फिर से चलाने से पैकेज अपग्रेड के बाद डेमॉन अपडेट और पुनरारंभ होता है। -`failproofaid` का उपयोग करने के लिए कॉन्फ़िगर की गई मशीन पर, daemon एकमात्र मूल्यांकनकर्ता है। यदि यह अनुपलब्ध है या इसका प्रोटोकॉल संस्करण CLI से मेल नहीं खाता है, तो hook मूल्यांकन विफल हो जाता है। कार्रवाई को एक कारण के साथ अस्वीकार किया जाता है जो ऑपरेटर को daemon की जांच या अपडेट करने के लिए निर्देशित करता है। +`failproofaid` का उपयोग करने के लिए कॉन्फ़िगर की गई मशीन पर, डेमॉन एकमात्र मूल्यांकनकर्ता है। यदि यह पहुंच योग्य नहीं है या इसके प्रोटोकॉल संस्करण CLI से मेल नहीं खाते हैं, तो हुक मूल्यांकन विफल हो जाता है। कार्रवाई एक कारण के साथ अस्वीकार कर दी जाती है जो ऑपरेटर को डेमॉन की जांच या अपडेट करने के लिए निर्देशित करता है। -Daemon कॉन्फ़िगरेशन से पहले, hooks प्रक्रिया में नीतियों का मूल्यांकन करते हैं। एक बार daemon कॉन्फ़िगरेशन रिकॉर्ड हो जाने पर, Failproof AI daemon विफल होने पर दूसरे मूल्यांकनकर्ता में चुप चाप वापस नहीं जाता है। +डेमॉन कॉन्फ़िगरेशन से पहले, हुक प्रक्रिया में नीतियों का मूल्यांकन करते हैं। एक बार डेमॉन कॉन्फ़िगरेशन दर्ज हो जाने के बाद, Failproof AI डेमॉन विफल होने पर किसी दूसरे मूल्यांकनकर्ता में चुप-चाप वापस नहीं जाता है। ## विफलता-बंद निर्णय का जवाब दें -1. `failproofai config --status` चलाएँ। -2. यदि संस्करण भिन्न हैं, तो पैकेज अपडेट करने के बाद `failproofai config` को फिर से चलाएँ। -3. यदि daemon अनुपलब्ध है, तो इसकी सेवा स्थिति और स्थानीय लॉग का निरीक्षण करें। -4. एजेंट कार्य केवल तभी फिर से शुरू करें जब ज्ञात नीति मूल्यांकन पथ स्वस्थ हो। +1. `failproofai config --status` चलाएं। +2. यदि संस्करण भिन्न हैं, तो पैकेज अपडेट करने के बाद `failproofai config` को फिर से चलाएं। +3. यदि डेमॉन पहुंच योग्य नहीं है, तो इसकी सेवा स्थिति और स्थानीय लॉग की जांच करें। +4. केवल तभी एजेंट का काम फिर से शुरू करें जब ज्ञात नीति मूल्यांकन पथ स्वस्थ हो। - अवरुद्ध कार्रवाई को बार-बार पुनः प्रयास न करें। विफलता-बंद प्रतिक्रिया का मतलब है कि सिस्टम स्थापित नहीं कर सका कि कार्रवाई सुरक्षित थी। + अवरुद्ध कार्रवाई को बार-बार पुनः करने का प्रयास न करें। विफलता-बंद प्रतिक्रिया का मतलब है कि सिस्टम यह स्थापित नहीं कर सका कि कार्रवाई सुरक्षित थी। ## एक पैक लोड नहीं होगा -एक मशीन जिसे एक पैक लागू करने के लिए कहा गया था, और इसे चला नहीं सकते, चुप चाप जारी रखने के बजाय अस्वीकार करता है। ट्रिगर एक **रिकॉर्ड की गई अपेक्षा** है, कभी एक खाली नहीं: कोई पैक स्थापित नहीं होने वाली मशीन चुप है, जबकि एक पैक जो घोषित है और हल नहीं होगा — या जो अपने मैनिफेस्ट से कम पंजीकृत करता है — अस्वीकार करता है। +एक मशीन जिसे पैक को लागू करने के लिए कहा गया था, और इसे चलाने में असमर्थ है, चुप-चाप जारी रखने के बजाय अस्वीकार कर देती है। ट्रिगर एक **रिकॉर्ड किया गया अपेक्षा** है, कभी खाली नहीं: एक मशीन जिसके पास कोई पैक स्थापित नहीं है वह चुप होती है, जबकि एक पैक जो घोषित है और हल नहीं होगा — या जो अपने मैनिफेस्ट की तुलना में कम पंजीकृत है — अस्वीकार कर देता है। -अस्वीकृति **संकीर्ण** है, एक अनुपलब्ध daemon के विपरीत। एक daemon जिस तक नहीं पहुंचा जा सकता वह कोई मूल्यांकन नहीं हुआ, इसलिए कुछ भी सुरक्षित नहीं हो सकता। एक पैक जो लोड नहीं होगा में लापता गार्डों का एक गणनीय सेट है, क्योंकि हर घोषित नीति अपना `match` ले जाती है — इसलिए यह केवल उन घटनाओं और उपकरणों को अस्वीकार करता है जो वे नीतियां कवर करती हैं, और सबकुछ अन्यथा आगे बढ़ता है। +अस्वीकार **संकीर्ण** है, अप्राप्य डेमॉन के विपरीत। एक डेमॉन जो पहुंच योग्य नहीं है इसका मतलब है कि कोई मूल्यांकन बिल्कुल नहीं हुआ, इसलिए कुछ भी सुरक्षित के रूप में नहीं जाना जा सकता है। एक पैक जो लोड नहीं होगा, लापता गार्ड का एक गणनीय सेट है, क्योंकि हर घोषित नीति अपने स्वयं के `match` को ले जाती है — इसलिए यह केवल उन घटनाओं और उपकरणों को अस्वीकार करता है जिन्हें उन नीतियां कवर करती हैं, और बाकी सब कुछ आगे बढ़ता है। -यह निम्न के लिए आग नहीं लगाता है: +यह इसके लिए ट्रिगर नहीं होता है: - एक `observe` पैक, जो निर्माण द्वारा मूल्यांकन करता है और त्यागता है -- नीतियां जो आपने कभी नहीं लीं, या स्पष्ट रूप से बंद कीं -- एक पैक जो लोडर को कभी नहीं मिला, जहां "कोई पंजीकरण नहीं" एक जानबूझकर छोड़ से अलग नहीं हो सकता -- एक सक्रिय सत्र विराम -- एक लोड समय सीमा, जो क्षणिक है — एक धीमा डिस्क क्षण इतनी देर तक अस्वीकार नहीं करना चाहिए जब तक कोई मानव हस्तक्षेप न करे +- नीतियां जो आपने कभी नहीं लीं, या स्पष्ट रूप से बंद कर दीं +- एक पैक जो लोडर को कभी नहीं मिला, जहां "कोई पंजीकरण नहीं" को जानबूझकर छोड़ने से अलग नहीं बताया जा सकता है +- एक सक्रिय सेशन विराम +- एक लोड टाइमआउट, जो क्षणिक है — एक धीमा डिस्क क्षण किसी मानव के हस्तक्षेप तक अस्वीकार नहीं करना चाहिए -`UserPromptSubmit` **निर्देश** देता है अस्वीकार करने के बजाय, चाहे लापता नीति ने क्या घोषित किया हो। एक व्यापक अस्वीकृति इसे साथ ले जाएगी और आपको उस एजेंट से बाहर कर देगी जो समस्या को ठीक कर सकता था। +`UserPromptSubmit` किसी भी लापता नीति घोषणा के बावजूद अस्वीकार करने के बजाय **निर्देश** देता है। एक व्यापक अस्वीकार इसे ले जाएगा और आपको उस एजेंट से बाहर लॉक कर देगा जो समस्या को ठीक कर सके। -### क्या करें +### क्या करना है ```bash -failproofai pack list +failproofai policies ``` -यह किसी भी स्थापित पैक का नाम बताता है जो लोड नहीं होगा, कहता है क्यों, और गैर-शून्य के साथ बाहर निकलता है। फिर इसे पुनः स्थापित करें (`failproofai pack add `) या हटाएँ (`failproofai pack remove `) — इसे हटाने से अपेक्षा वापस ली जाती है, और अस्वीकृति इसके साथ रुक जाती है। \ No newline at end of file +सूची एक स्थापित पैक को फ्लैग करती है जिसका स्थापना रिकॉर्ड या डाइजेस्ट अब चेक आउट नहीं होता है, और कहता है कि क्यों। यह पैक को आयात नहीं करता है, इसलिए एक जो केवल लोड होने के बाद विफल हो जाता है — अपने मैनिफेस्ट से कम पंजीकृत करता है — सामान्य रूप से सूचीबद्ध होता है; नीचे दिया गया अस्वीकार वह है जो उस नाम को देता है। किसी भी तरह से, इसे पुनः स्थापित करें (`failproofai policies add `) या इसे हटाएं (`failproofai policies remove `) — इसे हटाने से अपेक्षा को हटा दिया जाता है, और अस्वीकार इसके साथ बंद हो जाता है। + +अस्वीकार स्वयं `pack/failproofai-pack-unavailable` को जिम्मेदार ठहराया जाता है, जो लोड की गई नीतियों को पार करता है, इसलिए एक अवरुद्ध उपकरण कॉल लापता पैक का नाम देता है बजाय इसके कि कौन सी उत्तरजीवी गार्ड पहले ट्रिगर होने वाली थी। \ No newline at end of file diff --git a/docs/hi/policies/local-configuration.mdx b/docs/hi/policies/local-configuration.mdx index d941f120..0455971d 100644 --- a/docs/hi/policies/local-configuration.mdx +++ b/docs/hi/policies/local-configuration.mdx @@ -1,55 +1,49 @@ --- title: "स्थानीय कॉन्फ़िगरेशन" -description: "नीति scope, पैरामीटर, कस्टम फ़ाइलें और मशीन-स्तर की Failproof AI सेटिंग को नियंत्रित करें।" +description: "नीति के दायरे, पैरामीटर, कस्टम फाइलें, और मशीन-स्तरीय Failproof AI सेटिंग्स को नियंत्रित करें।" icon: "file-cog" --- -Failproof AI नीति चयन को मशीन और daemon सेटिंग से अलग रखता है। यह repository नीति विकल्प को समीक्षा योग्य रखता है जबकि credentials और daemon स्थिति repository के बाहर रहती है। +Failproof AI एक रिपोजिटरी जो कमिट कर सकती है — हुक वायरिंग, नीति पैरामीटर, कस्टम नीतियां — को मशीन स्थिति जैसे क्रेडेंशियल्स, इंस्टॉल किए गए पैक्स, और डेमन से अलग रखता है। -## नीति scope चुनें +## एक दायरा चुनें - - - स्थानीय नीति dashboard खोलने के लिए बिना किसी argument के `failproofai` चलाएं। नीति सक्षम करने से पहले user, project या local scope चुनें ताकि परिवर्तन intended configuration फ़ाइल में लिखा जाए। +एक दायरा यह तय करता है कि हुक कहां वायर किए गए हैं, और आप पैरामीटर और कस्टम नीति पाथ को किस कॉन्फ़िगरेशन फाइल में लिखते हैं: - - **User** इस मशीन पर projects में लागू होता है। - - **Project** repository से संबंधित है और commit किया जा सकता है। - - **Local** एक project को एक user के लिए override करता है और gitignore में रहना चाहिए। +- **User** इस मशीन पर सभी प्रोजेक्ट्स में लागू होता है। +- **Project** रिपोजिटरी के अंतर्गत होता है और इसे कमिट किया जा सकता है। +- **Local** एक प्रोजेक्ट को एक उपयोगकर्ता के लिए ओवरराइड करता है और इसे gitignored रहना चाहिए। - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # wire hooks for this repository +failproofai policies --install --cli claude --scope user # or for every project on this machine +failproofai policies +``` - हर harness local scope को समर्थन नहीं करता। CLI एक scope को अस्वीकार करता है जिसे selected harness प्रस्तुत नहीं कर सकता। - - +प्रत्येक हार्नेस स्थानीय दायरे का समर्थन नहीं करता; CLI एक दायरे को अस्वीकार करता है जिसे चुने गए हार्नेस का प्रतिनिधित्व नहीं कर सकता। + +कौन सी पैक नीतियां चालू हैं यह **नहीं** स्कोप की गई है। स्विच इंस्टॉल किए गए पैक के साथ दर्ज किया जाता है, इसलिए `failproofai policies add ` पूरी मशीन के लिए एक नीति को चालू करता है, चाहे `--scope` कुछ भी कहे। -| Scope | नीति कॉन्फ़िगरेशन फ़ाइल | +| दायरा | नीति कॉन्फ़िगरेशन फाइल | | --- | --- | | Project | `/.failproofai/policies-config.json` | | Local | `/.failproofai/policies-config.local.json` | | User | `~/.failproofai/policies-config.json` | -सक्षम नीतियों को union के रूप में मर्ज किया जाता है। नीति पैरामीटर पहली scope का उपयोग करते हैं जो उस नीति के लिए पैरामीटर परिभाषित करती है, project → local → user क्रम में। Explicit custom नीति पथ पहली scope का उपयोग करते हैं जो उन्हें परिभाषित करती है। +नीति पैरामीटर पहले दायरे का उपयोग करते हैं जो उस नीति के लिए पैरामीटर को परिभाषित करता है, project → local → user क्रम में। स्पष्ट कस्टम नीति पाथ पहले दायरे का उपयोग करते हैं जो उन्हें परिभाषित करता है। -## नीति पैरामीटर कॉन्फ़िगर करें +## नीति पैरामीटर को कॉन्फ़िगर करें - स्थानीय dashboard में नीति खोलें, इसके समर्थित पैरामीटर को संपादित करें और selected scope में सहेजें। एक मेल खाने वाली और गैर-मेल खाने वाली agent action चलाएं, फिर **Observe → policy** में निर्णय का निरीक्षण करें। + स्थानीय डैशबोर्ड में नीति को खोलें, इसके समर्थित पैरामीटर को संपादित करें, और चुने गए दायरे में सहेजें। एक मेल खाने वाली और गैर-मेल खाने वाली एजेंट कार्रवाई चलाएं, फिर **Observe → policy** में निर्णय का निरीक्षण करें। - selected scope की `policies-config.json` को संपादित करें, फिर `failproofai policies` चलाएं ताकि अज्ञात नीति नाम या पैरामीटर keys सामने आएं। + चुने गए दायरे की `policies-config.json` को संपादित करें, फिर `failproofai policies` चलाएं: यह एक `policyParams` प्रविष्टि के बारे में चेतावनी देता है जो एक नीति का नाम देता है जो कोई इंस्टॉल किया गया पैक नहीं ले जाता। यह एक प्रविष्टि के अंदर कुंजियों की जांच नहीं करता है, इसलिए नीचे दी गई तालिका के विरुद्ध उनकी वर्तनी जांचें। ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ Failproof AI नीति चयन को मशीन और daemon सेट -## मशीन फ़ाइलों को समझें +### Failproof AI नीतियां जो पैरामीटर स्वीकार करती हैं + +प्रत्येक नीति अपने स्वयं के पैरामीटर प्रकारों को मान्य करती है। + +| नीति | पैरामीटर | प्रकार और डिफ़ॉल्ट | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; प्रविष्टियां `regex` और `label` रखती हैं | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| Infrastructure blockers | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + एक अनुमति पैटर्न एजेंट को जो कर सकता है उसे व्यापक बनाता है। किसी फ्लीट में इसे तैनात करने से पहले लक्ष्य हार्नेस पर सटीक टोकनाइजेशन और कमांड वेरिएंट का परीक्षण करें। + + +## मशीन फाइलों को समझें -`~/.failproofai` में अलग-अलग trust boundaries के लिए अलग-अलग फ़ाइलें हैं: +`~/.failproofai` अलग-अलग विश्वास सीमाओं के लिए अलग-अलग फाइलें रखता है: -| पथ | उद्देश्य | +| पाथ | उद्देश्य | | --- | --- | -| `config.json` | गैर-secret daemon, audit और telemetry सेटिंग | -| `credentials.json` | Cloud credentials; owner-only permissions के साथ संग्रहित | -| `policies-config.json` | User-scope builtin चयन, पैरामीटर और explicit custom पथ | -| `policies/` | User convention नीति और Cloud-managed नीति artifacts | -| `hook-activity/` | स्थानीय नीति निर्णय log | -| `state/` | Daemon spool, health, pause और runtime state | +| `config.json` | गैर-गोपनीय डेमन, ऑडिट, और टेलीमेट्री सेटिंग्स | +| `credentials.json` | क्लाउड क्रेडेंशियल्स; मालिक-केवल अनुमतियों के साथ संग्रहीत | +| `policies-config.json` | उपयोगकर्ता-दायरा पैरामीटर और स्पष्ट कस्टम नीति पाथ | +| `policies/` | उपयोगकर्ता सम्मेलन नीतियां, इंस्टॉल किए गए पैक्स और उनकी कौन सी नीतियां चालू हैं, और क्लाउड-प्रबंधित नीति कलाकृतियां | +| `hook-activity/` | स्थानीय नीति निर्णय लॉग | +| `state/` | डेमन स्पूल, स्वास्थ्य, विराम, और रनटाइम स्थिति | -Container या isolated test के लिए पूर्ण मशीन layout को relocate करने के लिए `FAILPROOFAI_HOME` का उपयोग करें। स्वतंत्र रूप से individual state directories को relocate न करें। +एक कंटेनर या अलग-थलग परीक्षण के लिए पूर्ण मशीन लेआउट को स्थानांतरित करने के लिए `FAILPROOFAI_HOME` का उपयोग करें। अलग-अलग स्थिति निर्देशिकाओं को स्वतंत्र रूप से स्थानांतरित न करें। - कभी भी `credentials.json` को commit न करें। project नीति कॉन्फ़िगरेशन और project convention नीति को केवल उन्हें enforcement code के रूप में समीक्षा करने के बाद ही commit करें। + कभी भी `credentials.json` को कमिट न करें। प्रोजेक्ट नीति कॉन्फ़िगरेशन और प्रोजेक्ट सम्मेलन नीतियों को केवल प्रवर्तन कोड के रूप में समीक्षा करने के बाद कमिट करें। \ No newline at end of file diff --git a/docs/hi/policies/overview.mdx b/docs/hi/policies/overview.mdx index 73d26a33..f76843af 100644 --- a/docs/hi/policies/overview.mdx +++ b/docs/hi/policies/overview.mdx @@ -1,63 +1,54 @@ --- title: "नीतियाँ" -description: "एजेंट कार्यों को देखें, निर्देशित करें, या ज्ञात विफलता को दोहराने से पहले अवरुद्ध करें।" +description: "एजेंट क्रियाओं को देखें, निर्देशित करें, या ब्लॉक करें इससे पहले कि कोई ज्ञात विफलता दोहराई जाए।" icon: "shield-check" --- -एक नीति एजेंट हुक इवेंट का मूल्यांकन करती है और तीन निर्णयों में से एक लौटाती है: +एक नीति एजेंट हुक इवेंट का मूल्यांकन करती है और तीन निर्णयों में से एक देती है: -- `allow` कार्य को जारी रखने देता है। +- `allow` क्रिया को जारी रहने देता है। - `instruct` एजेंट को सुधारात्मक मार्गदर्शन देता है। -- `deny` कार्य को एक कारण के साथ अवरुद्ध करता है। +- `deny` एक कारण के साथ क्रिया को ब्लॉक करता है। -## तीन नीति सतहों का उपयोग करें +## नीतियाँ कहाँ रहती हैं - - - 1. सत्रों से नीति निर्णयों को फ़िल्टर और निरीक्षण करने के लिए **Observe → policy** पर जाएं। - 2. नीति को संरचित करने, मान्य करने, प्रकाशित करने, अक्षम करने या अपरिवर्तनीय संस्करणों का निरीक्षण करने के लिए **Admin → policy editor** पर जाएं। - 3. मशीनों को संस्करण और प्रभाव निर्दिष्ट करने के लिए **Admin → enforcement** पर जाएं। +| डैशबोर्ड में | आप वहाँ क्या करते हैं | +| --- | --- | +| **Observe → policy** | वास्तविक सत्रों से निर्णय की समीक्षा करें: कौन सी नीति मेल खाई, किस मशीन पर, और क्यों | +| **Admin → policy editor** | एक नीति लिखें, पिछले ट्रैफिक के विरुद्ध इसका परीक्षण करें, एक अपरिवर्तनीय संस्करण प्रकाशित करें, और **library** में संस्करणों की तुलना करें | +| **Admin → enforcement** | मशीनों पर संस्करण रखें, अवलोकन या प्रवर्तन मोड में | - लेखन या प्रवर्तन में परिवर्तन करने से पहले समझने के लिए Policy पृष्ठ का उपयोग करें कि पहले से क्या मेल खा रहा है। +नीति संपादक वह जगह है जहाँ विफलता एक नियम बन जाती है। विफलता मोड का वर्णन करें या **compose** में नीति स्रोत चिपकाएँ, ड्राफ्ट को आपके पास पहले से मौजूद ट्रैफिक के विरुद्ध परीक्षण करें, और एक संस्करण प्रकाशित करें: - ![Policy पृष्ठ निर्णय कुल और स्थानीय और क्लाउड-प्रबंधित नीति मैपिंग दिखा रहा है।](/images/dashboard/policy-observe.png) +![नीति संपादक का संरचना दृश्य नीति पहचान, AI-सहायक ड्राफ्टिंग, स्रोत सत्यापन, और प्रकाशन नियंत्रण के साथ।](/images/dashboard/policy-editor.png) - संपादक वह जगह है जहां आप एक विफलता शर्त को स्रोत में बदलते हैं, इसे मान्य करते हैं, और एक अपरिवर्तनीय संस्करण प्रकाशित करते हैं। +एक मशीन पर, `failproofai policies` वहाँ लागू होने वाली सभी चीजों को सूचीबद्ध करता है। `fp policies` और `fp fleet` टर्मिनल से संपादक और प्रवर्तन को कवर करते हैं — [Cloud CLI संदर्भ](/hi/reference/cloud-cli) देखें। - ![Policy संपादक एक अपरिवर्तनीय नीति संस्करण को संरचित और प्रकाशित करने के लिए उपयोग किया जाता है।](/images/dashboard/policy-editor.png) +## एक नीति प्राप्त करें - प्रवर्तन फिर उस प्रकाशित संस्करण और इसके observe या enforce प्रभाव को मशीनों को निर्दिष्ट करता है। - - ![Enforcement fleet मशीन कवरेज और निर्दिष्ट नीति संस्करण दिखा रहा है।](/images/dashboard/enforcement-fleet.png) - - तैनाती के बाद Policy पृष्ठ पर निर्णयों को सत्यापित करें ताकि लेखन और fleet दृश्य वास्तविक एजेंट कार्यकलाप से जुड़े हों। - - - स्थानीय नीति स्थापना और सत्यापन के लिए `failproofai` का उपयोग करें: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - नीति निर्णय युक्त क्लाउड सत्र और इवेंट खोजने के लिए `fp` का उपयोग करें। क्लाउड लेखन और fleet तैनाती dashboard वर्कफ़्लो बने रहते हैं। - - - -Failproof AI में नीतियों की तीन अलग सतहें हैं: - -1. सत्र, डैशबोर्ड और ऑडिट में **निर्णयों का विश्लेषण** करें। -2. अंतर्निर्मित नियमों, कोड, या नीति संपादक के साथ **संस्करणों को लेखन** करें। -3. चुनी गई मशीनों में **संस्करणों को तैनात और प्रवर्तित** करें। - -एक पुष्ट विफलता मोड से शुरू करें। सबसे छोटा इवेंट और उपकरण मेल परिभाषित करें जो इसकी पहचान करता है, वैध और असुरक्षित उदाहरणों का परीक्षण करें, फिर प्रवर्तन से पहले देखें। +इसे प्राप्त करने के दो तरीके हैं। - - सामान्य गुप्त, शेल, Git, क्लाउड और वर्कफ़्लो जोखिमों के लिए एक समीक्षा किया गया नियम सक्षम करें। + + Failproof AI को एक ऑडिट निष्कर्ष से ड्राफ्ट करने दें, या स्रोत स्वयं लिखें, फिर संपादक में इसकी समीक्षा करें और प्रकाशित करें। - - JavaScript या TypeScript में एक वर्कफ़्लो-विशिष्ट निर्णय व्यक्त करें। + + अपने उपयोग के मामले के लिए एक Failproof AI नीति पैक, या नीति हब से एक सामुदायिक पैक, एक कमांड में जोड़ें। - \ No newline at end of file + + +## फिर इसे भेजें + + + + ड्राफ्ट को आपके पास पहले से मौजूद ट्रैफिक के विरुद्ध परीक्षण करें, और इसे एक क्रिया के विरुद्ध चलाएँ जिसे यह रोकना चाहिए और एक जिसे यह अनुमति देनी चाहिए — सब कुछ प्रकाशित करने से पहले। [एक नीति का परीक्षण करें](/hi/policies/test) देखें। + + + **observe** मोड में मशीनों पर संस्करण रखें, इसके निर्णय पढ़ें, फिर प्रवर्तन करें। [एक नीति तैनात करें](/hi/policies/deploy) देखें। + + + प्रत्येक प्रकाशन एक नया, अपरिवर्तनीय संस्करण है, इसलिए एक रोलआउट जो वैध कार्य को ब्लॉक करता है, अंतिम अच्छे को फिर से तैनात करके पूर्ववत किया जाता है। [संस्करण और रोलबैक](/hi/policies/rollback) देखें। + + + +अपनी नीतियों को अन्य टीमों के साथ साझा करने के लिए, [उन्हें एक पैक के रूप में प्रकाशित करें](/hi/policies/publish-a-pack)। जब एक नीति का मूल्यांकन किया ही नहीं जा सकता है, तो क्या होता है, इसके लिए [विफलता व्यवहार](/hi/policies/failure-behavior) देखें। \ No newline at end of file diff --git a/docs/hi/policies/packs.mdx b/docs/hi/policies/packs.mdx index e5d5e309..f64d7ea9 100644 --- a/docs/hi/policies/packs.mdx +++ b/docs/hi/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "Policy packs" -description: "एक GitHub रिलीज़ के रूप में प्रकाशित नीतियों का एक सेट इंस्टॉल करें, और इसे लागू करने वाली चीज़ों को प्रबंधित करें।" +title: "एक policy pack का उपयोग करें" +description: "अपने उपयोग के लिए एक Failproof AI policy pack को plug in करें, या policy hub से एक community pack को चुनें, और यह तय करें कि यह क्या enforce करेगा।" icon: "package" --- -एक pack GitHub रिलीज़ के रूप में प्रकाशित नीतियों का एक सेट है। एक कमांड इसे इंस्टॉल करता है, रिलीज़ के अपने चेकसम को कुछ भी चलाने से पहले सत्यापित किया जाता है, और डाइजेस्ट दर्ज किया जाता है ताकि pack आपकी मशीन पर बाद में बदल न सके। +एक pack policies का एक समूह है जो GitHub release के रूप में प्रकाशित किया जाता है। एक कमांड इसे install करता है: release के checksums को verify किया जाता है इससे पहले कि कुछ भी चले, और इसका digest record किया जाता है ताकि pack आपकी machine के अंतर्गत बाद में बदल न सके। -## Failproof AI नीतियां इंस्टॉल करें +हर pack को browse करें, और [policy hub](https://befailproof.ai/policy-hub/) पर प्रत्येक में हर policy को देखें। दो प्रकार हैं: + +- **Failproof AI policy packs** — पूर्वनिर्धारित use cases के लिए ready-made packs: एक को plug in करें और यह काम करता है। [coding agent policy pack](https://befailproof.ai/policy-hub/failproofai/policies/) अभी उपलब्ध है, और अधिक use cases के लिए packs जल्द ही आ रहे हैं। +- **Community policy packs** — policies जो developers ने अपने use cases के लिए लिखी हैं और किसी को भी लेने के लिए प्रकाशित की हैं। + +## Failproof AI policy packs + +### Coding agent policy pack ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -यह हमारे द्वारा प्रकाशित सेट को पैकेज के अंदर की प्रति से इंस्टॉल करता है — इसलिए इसे कोई नेटवर्क की आवश्यकता नहीं है और यह प्रॉक्सी के पीछे विफल नहीं हो सकता। इसका कुछ हिस्सा लें: +pack में 38 policies हैं और अपने manifest में 10 को safe के रूप में चिह्नित करता है ताकि unattended enable किया जा सके; बाकी को आपको चुनने के लिए सूचीबद्ध किया जाता है। सबसे अधिक उपयोग किए जाने वाले कुछ, और क्या एक plain `policies add` उन्हें switch on करता है: + +| Policy | यह क्या करता है | डिफ़ॉल्ट रूप से चालू | +| --- | --- | --- | +| `block-push-master` | Protected branches में direct pushes को block करता है | Yes | +| `block-env-files` | `.env` files को read और write करने को block करता है | Yes | +| `protect-env-vars` | Environment variables को dump करने वाली commands को block करता है | Yes | +| `block-sudo` | `sudo` को block करता है जब तक allow pattern match न हो | Yes | +| `block-curl-pipe-sh` | Downloaded scripts को सीधे shell में piped करने को block करता है | Yes | +| `sanitize-*` (पाँच policies) | API keys, bearer tokens, JWTs, private keys, और connection strings को report करता है जो tool output में मिली हों | Yes | +| `block-rm-rf` | Catastrophic recursive deletes को block करता है | No | +| `block-force-push` | Force-pushes को block करता है | No | +| `block-secrets-write` | Credential और secret-key files में writes को block करता है | No | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, और `WHERE` के बिना `DELETE` पर warning देता है | No | + +जो off हैं उन्हें नाम से switch on करें — `failproofai policies add block-rm-rf` — या `--all` के साथ पूरे pack को लें। इसमें हर policy को देखें, category के अनुसार समूहबद्ध: ```bash -failproofai pack add core --policy block-rm-rf # एक, या कुछ अल्पविराम-विभाजित -failproofai pack add core --category dangerous-commands # पूरी श्रेणी -failproofai pack add core --all # इसमें सब कुछ +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` pack द्वारा प्रस्तावित हर श्रेणी का नाम बताता है। +## Community policy packs -## इंस्टॉल करने से पहले देखें कि एक pack में क्या है +Developers अपने द्वारा मिले use cases के लिए packs प्रकाशित करते हैं, और [policy hub](https://befailproof.ai/policy-hub/) उन्हें सूचीबद्ध करता है। एक community pack अपने author द्वारा प्रकाशित है, Failproof AI द्वारा audited नहीं है, इसलिए इसे install करने से पहले यह पढ़ें कि इसमें क्या है: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -pack द्वारा की जाने वाली हर नीति को सूचीबद्ध करता है, श्रेणी के अनुसार समूहीकृत, यह चिह्नित करता है कि इसके लेखक को कौन सी डिफ़ॉल्ट रूप से चालू करता है और कौन सी ऑप्ट-इन है। यह **केवल manifest** पढ़ता है — entry artifact कभी डाउनलोड नहीं होता और कभी आयात नहीं होता, इसलिए किसी अजनबी के pack को देखना किसी अजनबी के कोड को चला नहीं सकता। manifest को अभी भी रिलीज़ के अपने `SHA256SUMS` के विरुद्ध जांचा जाता है, इसलिए आप जो पढ़ रहे हैं वह इंस्टॉल होगा। - -`failproofai pack list` किसी स्रोत के बिना पहले से इंस्टॉल किए गए packs को सूचीबद्ध करता है। +यह हर policy को list करता है जो इसमें है, category के अनुसार समूहबद्ध, और चिह्नित करता है कि इसके author कौन सी policies को डिफ़ॉल्ट रूप से switch on करते हैं। यह **केवल manifest को पढ़ता है** — entry artifact को कभी download या import नहीं किया जाता है, इसलिए एक अजनबी के pack को देखना एक अजनबी के code को नहीं चलाता है। Manifest को अभी भी release के अपने `SHA256SUMS` के विरुद्ध checked किया जाता है, इसलिए जो आप पढ़ते हैं वह यही है जो install होता। -## किसी और के pack को इंस्टॉल करें +फिर इसे install करें: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -इनमें से कोई भी काम करता है — जो कुछ आपके पास है वह चिपकाएँ: +ये सभी काम करते हैं — जो भी आपके पास है paste करें: -| स्रोत | परिणाम | +| Source | परिणाम | | --- | --- | -| `acme/support-agent` | नवीनतम रिलीज़, **पिन किया गया** सटीक टैग के लिए जो इसे हल किया | -| `acme/support-agent@v2.1.0` | वह रिलीज़ | -| `github:acme/support-agent@v2.1.0` | समान, स्पष्ट रूप से लिखा गया | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | समान, ब्राउज़र से कॉपी किया गया | +| `acme/support-agent` | Newest release, **pinned** को exact tag से जो resolve हुआ | +| `acme/support-agent@v2.1.0` | वह release | +| `github:acme/support-agent@v2.1.0` | वही, explicitly लिखा हुआ | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | वही, browser से copied | -कोई टैग नाम न देने से नवीनतम रिलीज़ **इंस्टॉल होता है और पिन किया जाता है**, फिर आपको बताता है कि इसने कौन सा टैग चुना। जो दर्ज किया जाता है वह हमेशा बिल्कुल एक रिलीज़ का नाम देता है, इसलिए एक पुनः इंस्टॉल बहाव नहीं कर सकता। +कोई tag नाम न रखना newest release को install करता है **और इसे pin करता है**, फिर आपको बताता है कि इसने कौन सा tag चुना। जो record किया जाता है वह हमेशा बिल्कुल एक release का नाम देता है, इसलिए एक reinstall drift नहीं कर सकता। -## एक pack का हिस्सा लें +## एक pack का एक हिस्सा लें -डिफ़ॉल्ट रूप से आप pack के **अपने** डिफ़ॉल्ट प्राप्त करते हैं — वह नीतियां जो इसके लेखक ने बिना निगरानी के चालू करने के लिए सुरक्षित चिह्नित किया है — इसमें सब कुछ नहीं। +डिफ़ॉल्ट रूप से आप pack के **अपने** defaults प्राप्त करते हैं — policies जो इसके author ने unattended switch on करने के लिए safe चिह्नित की हैं — यह सब कुछ नहीं जो यह contain करता है। ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # एक, या कुछ comma-separated +failproofai policies add FailproofAI/policies --category dangerous-commands # एक पूरी category +failproofai policies add FailproofAI/policies --all # इसमें सब कुछ ``` -`--category` और `--policy` एक union के रूप में संयोजित करते हैं (`--only` को `--policy` का पर्यायवाची स्वीकार किया जाता है)। नए संस्करण पर पुनः जोड़ने से आपकी चुनी हुई चीज़ें रहती हैं न कि बाकी को वापस चालू करने से। +`--category` और `--policy` एक union के रूप में combine होते हैं (`--only` को `--policy` के लिए एक synonym के रूप में स्वीकार किया जाता है)। जब pack पहले से ही installed है, तो flags आपके पास जो थे उसमें जोड़ते हैं, और इसे कोई flag और कोई terminal के साथ फिर से जोड़ना — upgrade करने के लिए, कहें — आपकी selection को जैसे है रखता है। एक terminal में कोई flag के साथ, `add` picker को खोलता है इसके बजाय, author के defaults के साथ pre-ticked, और जो आप tick करते हैं आपकी selection को replace करता है। -## क्या चालू है इसे प्रबंधित करें +## क्या है यह manage करें ```bash -failproofai policies # एक सूची में हर स्रोत, packs सहित -failproofai pack list # केवल packs, श्रेणी के अनुसार समूहीकृत -failproofai policies --uninstall block-refunds # एक pack नीति को बंद करें -failproofai policies --install block-refunds # और वापस चालू करें -failproofai pack remove acme/support-agent +failproofai policies # एक list में हर source, packs शामिल +failproofai policies add block-rm-rf # एक policy को switch on करें +failproofai policies --uninstall block-refunds # एक pack policy को turn off करें +failproofai policies --install block-refunds # और फिर से on करें +failproofai policies remove acme/support-agent # pack को uninstall करें ``` -एक नंगा नाम का अर्थ **builtin** है जब उस नाम से कोई मौजूद हो। जब आपको आवश्यकता हो तो एक pack की प्रति को स्पष्ट रूप से नाम दें: +एक pack policy को on या off करना पूरी machine पर लागू होता है: switch को installed pack के साथ record किया जाता है, project के configuration में नहीं, चाहे `--scope` क्या कहे। + +कोई slash के बिना एक नाम एक policy है; जो कुछ भी एक के साथ एक pack source है। एक bare नाम installed pack में resolve होता है जो इसे declare करता है। जब दो installed packs एक ही नाम declare करते हैं, तो जिस एक का आप मतलब करते हैं उसका नाम दें: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -यदि एक pack ऐसी नीति भेजता है जिसका नाम भी एक **सक्षम builtin** है, तो builtin चलता है और pack की प्रति को छोड़ दिया जाता है — अन्यथा समान guard का दो बार मूल्यांकन किया जाएगा। इसके बजाय pack की प्रति का उपयोग करने के लिए builtin को बंद करें। - - -## Failproof AI नीतियां कहां से आती हैं - -`core` npm पैकेज में vendored प्रति को पढ़ता है। समान सेट एक GitHub रिलीज़ के रूप में प्रकाशित किया जाता है, जो आप इंस्टॉल करते हैं यदि आप एक विशिष्ट संस्करण चाहते हैं: - -```bash -failproofai pack add core # इस पैकेज से, कोई नेटवर्क नहीं -failproofai pack add FailproofAI/policies # समान सेट, इसकी GitHub रिलीज़ से -``` +Scopes, parameters, और ये commands जो files लिखती हैं वे [local configuration](/hi/policies/local-configuration) में cover हैं। -## अखंडता क्या करती है और क्या नहीं करती है +## Integrity क्या करती है और क्या नहीं करती है -`SHA256SUMS` artifact के समान रिलीज़ में भेज दिया जाता है, इसलिए यह **एक हस्ताक्षर नहीं है** और इसे प्रकाशित करने वाले के बारे में कुछ भी साबित नहीं करता। यह साबित करता है कि बाइट्स वे हैं जो रिलीज़ ने प्रकाशित किए हैं — और क्योंकि digest को pack जोड़ने के समय दर्ज किया जाता है और हर आयात से पहले पुनः सत्यापित किया जाता है, एक pack आपकी मशीन पर बाद में नहीं बदल सकता। एक repository जो retags या किसी asset को replace करता है, वह शांति से कुछ और चलाने के बजाय लोड करना बंद कर देता है। +`SHA256SUMS` artifact के समान release में ships करता है, इसलिए यह **एक signature नहीं है** और किसी को publish करने के बारे में कुछ भी prove नहीं करता है। यह क्या prove करता है कि bytes वो हैं जो release ने publish किए — और क्योंकि digest को record किया जाता है जब आप pack add करते हैं और हर import से पहले re-verified होता है, एक pack आपकी machine के अंतर्गत बाद में नहीं बदल सकता। एक repository जो retags या एक asset को replace करता है loading को रोकता है इसके बजाय quietly कुछ और run करने के। -इंस्टॉल के समय pack को भी **एक बार आयात किया जाता है** और इसके अपने manifest के विरुद्ध जांचा जाता है। एक pack जिसकी artifact parse नहीं होती, या जो अपनी घोषणा के अलावा कुछ और रजिस्टर करता है, सक्रिय होने से पहले मना किया जाता है — न कि स्वच्छ रूप से इंस्टॉल करने और आपकी अगली tool call पर विफल होने के बजाय। +Install time पर pack को भी **एक बार import** किया जाता है और अपने manifest के विरुद्ध checked किया जाता है। एक pack जिसका artifact parse नहीं होता, या जो कुछ और register करता है जो वह declare नहीं करता, को refuse किया जाता है इससे पहले कि कुछ भी activate हो — इसके बजाय cleanly install होना और आपकी अगली tool call पर fail होना। -## जब एक pack लोड नहीं होगा +## जब एक pack load नहीं होगा -एक pack जिसे यह मशीन लागू करने के लिए कहा गया था और चला नहीं सकता **नीति को अस्वीकार करता है** जो इसकी missing नीतियों ने कवर किए, न कि शांति से अनुमति दी। [Failure behavior](/hi/policies/failure-behavior) देखें। `failproofai pack list` उस स्थिति में किसी भी pack का नाम बताता है और non-zero बाहर निकलता है। +एक pack जिसे इस machine को enforce करने के लिए कहा गया था और run नहीं कर सकता **deny** करता है events को जो इसकी missing policies covered करती थीं, उन्हें silently allow करने के बजाय — `pack/failproofai-pack-unavailable` के रूप में, जो policies को outrank करता है जो load हुई इसलिए deny को missing pack को attribute किया जाता है बजाय whichever guard happened to fire first के। Exception `UserPromptSubmit` है, जो इसके बजाय instruct करता है: वहाँ deny करना आपको lock कर देगा agent से जिसकी आप जरूरत है इसे ठीक करने के लिए। [Failure behavior](/hi/policies/failure-behavior) देखें। -## ऑफलाइन और मिरर +## Offline और mirrors -| चर | प्रभाव | +| Variable | प्रभाव | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | फेच करने से इनकार करता है; पहले से इंस्टॉल किए गए packs लागू करते रहते हैं | -| `FAILPROOFAI_PACK_BASE_URL` | pack फेचिंग को `github.com` के बजाय मिरर की ओर इंगित करता है | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Fetch करने से refuses करता है; पहले से ही installed packs enforce करते रहते हैं | +| `FAILPROOFAI_PACK_BASE_URL` | Pack fetching को `github.com` के बजाय एक mirror की ओर point करता है | -अपना पैक प्रकाशित करना: [Publish a pack](/hi/policies/publish-a-pack) देखें। \ No newline at end of file +अपनी policies को इस तरह share करने के लिए, [Publish a policy pack](/hi/policies/publish-a-pack) देखें। \ No newline at end of file diff --git a/docs/hi/policies/publish-a-pack.mdx b/docs/hi/policies/publish-a-pack.mdx index dec608db..0b6e37f2 100644 --- a/docs/hi/policies/publish-a-pack.mdx +++ b/docs/hi/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "एक पैक प्रकाशित करें" -description: "अपनी नीतियों को एक GitHub रिलीज़ के रूप में शिप करें जिसे कोई भी इंस्टॉल कर सके।" +title: "एक नीति पैक प्रकाशित करें" +description: "अपनी नीतियों को GitHub रिलीज़ के रूप में शिप करें जिसे कोई भी इंस्टॉल कर सकता है।" icon: "upload" --- -एक पैक एक GitHub रिलीज़ से जुड़ी तीन फाइलें हैं। `failproofai pack build` उन सभी को एक नीति फाइल से लिखता है जो आपके पास पहले से है। +एक पैक GitHub रिलीज़ से जुड़ी तीन फाइलें हैं। `failproofai publish` इन सभी को सामने आने वाली नीति फाइलों से लिखता है, रिलीज़ बनाता है, और उन्हें अपलोड करता है। ## 1. नीतियां लिखें -एक फाइल, किसी भी कस्टम नीति के समान API का उपयोग करते हुए। एक पैक के लिए दो अतिरिक्त फील्ड महत्वपूर्ण हैं: +टेम्पलेट से शुरुआत करने के बजाय किसी ऐसी चीज़ से शुरुआत करें जो पहले से काम कर रही हो: + +```bash +failproofai publish --init +``` + +यह पूछता है कि पैक का नाम क्या है, `.mjs` लिखता है, और रुक जाता है — कोई नेटवर्क नहीं, कोई git नहीं, कुछ भी प्रकाशित नहीं। यह फाइल जो लिखता है वह एक नीति है जो पहले से `git push --force` को ब्लॉक करता है। यह किसी मौजूदा फाइल को ओवरराइट नहीं करता। + +नीतियां किसी भी कस्टम नीति के समान API का उपयोग करती हैं। एक पैक के लिए दो अतिरिक्त फील्ड महत्वपूर्ण हैं: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` डिफ़ॉल्ट रूप से **false** होता है जब आप इसे छोड़ देते हैं। एक साधारण `failproofai pack add` केवल उन्हीं को सक्षम करता है जिन्हें आपने चिह्नित किया — किसी अजनबी की सभी नीतियों को निरीक्षण के बिना इंस्टॉल करना एक ऐसा निर्णय नहीं है जो इंस्टॉलर को अपने उपयोगकर्ता के लिए करना चाहिए। +जब आप इसे छोड़ देते हैं तो `defaultEnabled` डिफ़ॉल्ट रूप से **false** होता है। एक सादा `failproofai policies add` केवल वह चीज़ें स्विच करता है जिन्हें आपने चिह्नित किया है — किसी अजनबी की हर नीति को बिना निगरानी के इंस्टॉल करना एक ऐसा निर्णय नहीं है जो इंस्टॉलर को अपने उपयोगकर्ता के लिए करना चाहिए। + +जितनी चाहें उतनी फाइलें लिखें; एक प्रति श्रेणी अच्छी दिखती है। निर्देशिका में वह सभी फाइलें जो नीतियां पंजीकृत करती हैं, एक पैक को बंडल किया जाता है। -प्रविष्टि **एक आत्मनिर्भर फाइल** होनी चाहिए। केवल प्रविष्टि को डाइजेस्ट-पिन किया जाता है, इसलिए एक पैक जो स्थानीय फाइलों को आयात करता है वह ईमानदारी से यह दावा नहीं कर सकता कि डाइजेस्ट जो चलता है उसे कवर करता है। पहले बंडल करें (`esbuild`, `bun build`, `rollup`) और पैक को बंडल से बनाएं — `pack build` एक स्थानीय आयात से इनकार करता है क्योंकि यह एक ऐसा वादा नहीं करना चाहता जिसे वह पूरा नहीं कर सकता। + बंडलिंग के लिए **bun** की आवश्यकता है। इसके बिना, एक आत्मनिर्भर फाइल तक सीमित रहें। किसी भी तरह, प्रकाशित प्रविष्टि इंस्टॉल समय पर स्थानीय फाइलें आयात नहीं कर सकती: केवल प्रविष्टि डाइजेस्ट-पिन की जाती है, इसलिए एक पैक जो भाई-बहनों तक पहुंचता है, ईमानदारी से यह दावा नहीं कर सकता कि डाइजेस्ट वह कवर करता है जो चलता है — और `publish` इसे अस्वीकार कर देता है। -## 2. रिलीज़ एसेट्स बनाएं +## 2. पहले यहां इसे आजमाएं + +इससे पहले कि कोई और इसे देख सके, इस मशीन पर फाइल को लागू करें: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +कोई भी पथ, कोई भी फाइल नाम। अपने एजेंट को उस चीज़ को करने के लिए कहें जिसे आपने ब्लॉक किया है और इसे अस्वीकार किए जाते देखें। कुछ भी प्रकाशित नहीं है और कोई और प्रभावित नहीं है। [नीति का परीक्षण करें](/hi/policies/test) बाकी को कवर करता है: वह वैध मामला जिसे इसे अनुमति देनी चाहिए, और वह इनपुट जो इसे तोड़ते हैं। + +## 3. इसे प्रकाशित करें + +```bash +failproofai publish ``` -यह तीन फाइलें लिखता है, और पहले **लोडर के अपने नियमों** के साथ हर नीति को मान्य करता है — इसलिए एक पैक जो कभी इंस्टॉल नहीं हो सकता है यहां विफल हो जाता है, जहां आप इसे ठीक कर सकते हैं: +यह पता लगाता है कि कहां प्रकाशित करना है, क्या बंडल करना है और इसे क्या संस्करण देना है, और केवल तब पूछता है जब कुछ नहीं बताता। क्रम में, यदि कुछ गलत है तो रिलीज़ बनाने से पहले रुकता है: + +1. **सामग्री** द्वारा नीति फाइलें ढूंढता है — वे जो `failproofai` आयात करती हैं और `customPolicies.add` कॉल करती हैं — फाइल नाम के अनुसार नहीं, इसलिए यह `guards.mjs` ढूंढता है और एक असंबंधित `policies.mjs` को अनदेखा करता है। यह उप-निर्देशिकाओं में नहीं जाता, इसलिए एक परीक्षण फिक्स कभी गलती से नहीं चुना जाता। +2. `git remote get-url origin` से रिपो पढ़ता है, आपकी निर्देशिका के बजाय **फाइल की** निर्देशिका में, और संस्करण तय करता है। +3. आपके क्रेडेंशियल को ढूंढता है: `GITHUB_TOKEN`, `GH_TOKEN`, या `gh auth login`। इसे रिलीज़-राइट की आवश्यकता है और कुछ नहीं, और कभी नहीं छाया जाता। +4. भंडार बनाता है यदि यह मौजूद नहीं है। यह निर्माण से पहले होता है, इसलिए अगले चरण में अस्वीकार किया गया एक पैक इसमें कोई रिलीज़ के साथ एक नया भंडार छोड़ सकता है। +5. तीन संपत्तियां बनाता है, उन्हें **लोडर के अपने नियमों** से सत्यापित करता है — वही कोड जो तय करता है कि किसी अजनबी की मशीन पर क्या इंस्टॉल हो सकता है — इसलिए एक पैक जो कभी इंस्टॉल नहीं हो सकता वह यहां विफल हो जाता है, जहां आप अभी भी इसे ठीक कर सकते हैं। +6. रिलीज़ बनाता या पुनः उपयोग करता है और अपलोड करता है, समान नाम की संपत्तियों को बदलता है। | फाइल | यह क्या है | | --- | --- | -| `failproofai-pack.json` | मैनिफेस्ट: आईडी, संस्करण, प्रभाव, और प्रति नीति एक प्रविष्टि | -| `failproofai-pack.mjs` | आपकी प्रविष्टि, शब्दशः | -| `SHA256SUMS` | ` ` अन्य दोनों के लिए | +| `failproofai-pack.json` | मैनिफेस्ट: id, संस्करण, प्रभाव, और प्रति नीति एक प्रविष्टि | +| `failproofai-pack.mjs` | आपकी बंडल की गई प्रविष्टि | +| `SHA256SUMS` | ` ` अन्य दो के लिए | -बिल्ड समय पर अस्वीकार किया गया: एक आईडी जो `publisher/name` नहीं है, एक नीति नाम में `/` है, एक नीति `alwaysOn` की घोषणा करती है, एक लापता `description`, `category` या `match`, एक प्रविष्टि जो कुछ भी पंजीकृत नहीं करती है, और एक प्रविष्टि जो स्थानीय फाइलों को आयात करती है। +संपत्ति के नाम निर्धारित हैं — वे वह हैं जिन्हें एक उपभोक्ता का CLI अपने URLs से बनाता है, कोई API कॉल के साथ नहीं और कोई खोज नहीं। -## 3. उन्हें एक रिलीज़ से जोड़ें +निर्माण समय पर अस्वीकार किया गया: एक id जो `publisher/name` नहीं है, `/` युक्त नीति नाम, `alwaysOn` घोषित करने वाली नीति, `description`, `category` या `match` का अभाव, एक प्रविष्टि जो कुछ नहीं पंजीकृत करती, और एक प्रविष्टि जो स्थानीय फाइलें आयात करती है। -रिलीज़ को उसी संस्करण के साथ टैग करें जो आपने बनाया था, और सभी तीन फाइलों को रिलीज़ एसेट्स के रूप में जोड़ें: +जो कुछ भी यह तय करता है उसे ओवरराइड करें: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -अब कोई भी इसे इंस्टॉल कर सकता है: +`--id` पैक id सेट करता है जब यह रिपो से अलग होना चाहिए, `--tag` रिलीज़ का टैग सेट करता है, `--notes` जनरेट की गई रिलीज़ नोट्स को बदलता है — यह वह है जहां `policies show --releases` प्रत्येक रिलीज़ के गणना और कमिट को पढ़ता है — `--out` चुनता है कि संपत्तियां कहां लिखी जाएं (डिफ़ॉल्ट `dist-pack`), और `--dry-run` उन्हें प्रकाशित किए बिना बनाता है और कोई क्रेडेंशियल की आवश्यकता नहीं है। -```bash -failproofai pack add acme/support-agent -``` +कोई भी अब इसे `failproofai policies add acme/support-agent` के साथ इंस्टॉल कर सकता है। संस्करण को पिन करने और केवल एक के हिस्से को लेने के लिए [नीति पैक](/hi/policies/packs) देखें। + +### इसे नीति हब पर सूचीबद्ध करें -एसेट नाम निर्धारित हैं — ये वह हैं जो एक उपभोक्ता का CLI अपने URLs का निर्माण करने के लिए बनाता है, कोई API कॉल के बिना और कोई खोज के बिना। +GitHub पर भंडार में `failproofai-policies` विषय जोड़ें। कोई सबमिशन फॉर्म नहीं है और कोई अनुमोदन कतार नहीं है: [नीति हब](https://befailproof.ai/policy-hub/) क्रॉलर अपने अगले पास पर भंडार को उठाता है। विषय केवल इसे विचार के लिए रखता है — यह क्या सूचीबद्ध करता है वह एक रिलीज़ है जिसका मैनिफेस्ट अपने `SHA256SUMS` के विरुद्ध सत्यापित होता है और CLI उपयोग करने वाले समान नियमों के तहत पार्स करता है, जो ठीक वही है जो `failproofai publish` उत्पादित करता है। + +## संस्करण कैसे तय किया जाता है + +संस्करण **कमिट है जिससे आप प्रकाशित कर रहे हैं** — इसका संक्षिप्त sha, बारह वर्ण: `a1b2c3d4e5f6`। चुनने के लिए कुछ नहीं है और बढ़ाने के लिए कुछ नहीं है, और संस्करण ठीक उसी स्थान का नाम देता है जहां बाइट्स आए हैं, इसलिए समान स्रोत को दो बार प्रकाशित करने से समान संस्करण मिलता है। + +यह आपके सामने के पेड़ से पढ़ा जाता है, कभी भी भंडार की रिलीज़ से नहीं, इसलिए एक ताज़ा क्लोन और एक एयर-गैप्ड मशीन GitHub से पूछे बिना समान उत्तर की गणना करते हैं कि पहले क्या हुआ। + +क्योंकि संस्करण एक कमिट का नाम देता है, यह कमिट मौजूद होना चाहिए। एक टर्मिनल पर, `publish` यह आपके लिए बनाता है: यह एक भंडार को आरंभ करता है जब कोई नहीं है, और निर्माण से पहले परिवर्तित नीति फाइलों को कमिट करता है। यह **अस्वीकार करता है** — `--version` को तरीका के रूप में नाम देता है — जब यह टर्मिनल के बिना चलता है (एक CI धावक पर किया गया कमिट और कहीं मौजूद नहीं होगा), जब नीतियों के अलावा अन्य फाइलें अनकमिटेड हों, या एक चेकआउट में जिसमें अभी तक कोई कमिट नहीं है। `HEAD` पर एक टैग sha को जीतता है — किसी ने जिसने `v1.2.0` को टैग किया है, ने कहा है कि यह रिलीज़ क्या है। + +एक sha अपने आप में कोई क्रम नहीं रखता है, इसलिए यह देखने के लिए `failproofai policies show / --releases` का उपयोग करें कि कौन सी रिलीज़ पहले आई — शीर्ष पर सबसे नई। ## एक नया संस्करण शिप करना -नए `--version` के साथ बनाएं, एक नई रिलीज़ को टैग करें, तीनों एसेट्स को फिर से जोड़ें। उपभोक्ता समान `pack add` चलाते हैं और जो भी सबसेट उन्होंने चुना था उसे रखते हैं; एक नीति जिसे उन्होंने बंद किया था अपग्रेड के दौरान बंद रहती है। +परिवर्तन को कमिट करें और फिर से `failproofai publish` चलाएं — नया कमिट नया संस्करण है। उपभोक्ता समान `failproofai policies add` चलाते हैं। टर्मिनल के बिना, या चयन फ्लैग के साथ, वे उप-समुच्चय को रखते हैं जिसे उन्होंने चुना था और एक नीति जिसे उन्होंने बंद किया वह बंद रहता है; कोई फ्लैग के साथ एक टर्मिनल पर, पिकर आपके डिफ़ॉल्ट के साथ पूर्व-चेकित खुलता है और उनका उत्तर उनके चयन को बदलता है। -एक नीति के **नाम** को बदलना एक ब्रेकिंग परिवर्तन है: एक मशीन जिसने इसे बंद कर दिया था, एक नाम को बंद कर रही है जो अब मौजूद नहीं है, और नया नाम जो भी `defaultEnabled` कहता है उसमें आता है। +नीति के **नाम** को बदलना एक महत्वपूर्ण परिवर्तन है: एक मशीन जिसने इसे बंद किया था, एक ऐसा नाम बंद कर रहा है जो अब मौजूद नहीं है, और नया नाम जो भी `defaultEnabled` कहता है उसमें आता है। ## आपके उपयोगकर्ता क्या विश्वास कर रहे हैं -`SHA256SUMS` उसी रिलीज़ में रहता है जो आर्टिफैक्ट के समान है, इसलिए यह साबित करता है कि बाइट्स वे हैं जिन्हें आपने प्रकाशित किया — न कि आप कौन हैं। जो कोई भी रिपोजिटरी को लिख सकता है वह दोनों फाइलों को लिख सकता है। आपके उपयोगकर्ताओं की सुरक्षा यह है कि डाइजेस्ट को तब पिन किया जाता है जब वे इंस्टॉल करते हैं, इसलिए जो आपने शिप किया वह उसके बाद उनके अंतर्गत नहीं बदल सकता। +`SHA256SUMS` उसी रिलीज़ में रहता है जहां कलाकृति है, इसलिए यह साबित करता है कि बाइट्स वह हैं जो आपने प्रकाशित किए — आप कौन हैं नहीं। जो कोई भी भंडार में लिख सकता है वह दोनों फाइलें लिख सकता है। आपके उपयोगकर्ताओं की सुरक्षा यह है कि जब वे इंस्टॉल करते हैं तो डाइजेस्ट पिन किया जाता है, इसलिए जो आपने शिप किया वह उसके बाद उनके अंतर्गत नहीं बदल सकता। + +एक ऐसे भंडार से प्रकाशित करें जिसकी लिखने की पहुंच आप नियंत्रित करते हैं, और एक पैक रिलीज़ को पैकेज प्रकाशित करने की तरह मानें। -एक ऐसी रिपोजिटरी से प्रकाशित करें जिसके लिखने की पहुंच आप नियंत्रित करते हैं, और एक पैक रिलीज़ को एक पैकेज प्रकाशित करने की तरह व्यवहार करें। +भंडार भी **सार्वजनिक** होना चाहिए। इंस्टॉल गुमनाम HTTPS है कोई क्रेडेंशियल के साथ जो प्रस्ताव देने के लिए है, इसलिए एक मौजूदा निजी रिपो कुछ भी बनाने या अपलोड करने से पहले अस्वीकार कर दिया जाता है, और एक जो `publish` बनाता है वह समान कारण के लिए सार्वजनिक है। `--allow-private` किसी के लिए उस को ओवरराइड करता है जो तीनों संपत्तियों को दूसरे तरीके से सौंप रहा है, और स्पष्ट रूप से कहता है कि कोई भी `policies add` उन तक नहीं पहुंच सकता। केवल रिलीज़ महत्वपूर्ण है: इंस्टॉल `releases/download//` पढ़ते हैं और कभी आपके git पेड़ को स्पर्श नहीं करते। ## लागू करने से पहले देखें -एक मैनिफेस्ट `"effect": "observe"` घोषित कर सकता है। वे नीतियां चलती हैं और उनके फैसले **रिकॉर्ड किए जाते हैं और त्यागे जाते हैं** — कुछ भी ब्लॉक नहीं होता है। यह वास्तविक ट्रैफ़िक के विरुद्ध एक नई नियम को मापने का तरीका है इससे पहले कि यह किसी के काम को बाधित कर सके। +एक मैनिफेस्ट `"effect": "observe"` घोषित कर सकता है — `failproofai publish --effect observe` वह है जो इसे सेट करता है। वह नीतियां चलती हैं और उनके निर्णय **दर्ज और त्याग दिए जाते हैं** — कुछ नहीं ब्लॉक किया जाता है। यह किसी के काम को बाधित करने से पहले वास्तविक ट्रैफिक के खिलाफ एक नई नियम को मापने का तरीका है। ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/hi/policies/rollback.mdx b/docs/hi/policies/rollback.mdx index b197f7fe..56062420 100644 --- a/docs/hi/policies/rollback.mdx +++ b/docs/hi/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "रोलबैक" -description: "किसी ज्ञात नीति तैनाती को पुनः स्थापित करें जब कोई रोलआउट वैध एजेंट कार्य को बाधित करता है।" +title: "संस्करण और रोलबैक" +description: "हर प्रकाशन एक अपरिवर्तनीय संस्करण है, इसलिए किसी भी विघ्नकारी रोलआउट को पिछले अच्छे संस्करण को फिर से तैनात करके पूर्ववत किया जाता है।" icon: "rotate-ccw" --- -रोलबैक तैनात संस्करण को बदलता है या एक नीति असाइनमेंट को हटाता है; यह निर्णय इतिहास को मिटाता नहीं है जो घटना को समझाता है। +एक प्रकाशित नीति संस्करण कभी नहीं बदलता। किसी नीति को संपादित करना और फिर से प्रकाशित करना एक नया संस्करण बनाता है; यह पहले से मशीनों पर मौजूद संस्करण को कभी नहीं फिर से लिखता। यही रोलबैक को सुरक्षित बनाता है: अंतिम अच्छा संस्करण अभी भी वहां है, बिट दर बिट, और रोलबैक करने से निर्णय इतिहास मिटता नहीं है जो बताता है कि क्या गलत हुआ। + +## एक संस्करण खोजें + + + + **Admin → policy editor** पर जाएं और किसी नीति के संस्करणों की तुलना करने या किसी को अक्षम करने के लिए **library** खोलें। + + + ```bash + fp policies list # हर नीति संस्करण + fp policies show # एक संस्करण, इसके स्रोत के साथ + ``` + + ## एक मशीन को रोलबैक करें - 1. **Admin → enforcement** पर जाएं, प्रभावित मशीन को विस्तारित करें, और उसके अंतिम ज्ञात-अच्छी नीति सेट की पहचान करें। + 1. **Admin → enforcement** पर जाएं, प्रभावित मशीन को विस्तृत करें, और इसके अंतिम ज्ञात-अच्छी नीति सेट की पहचान करें। 2. **edit** चुनें, उन संस्करणों और प्रभावों को पुनः स्थापित करें, और नई तैनाती लागू करें। - 3. मशीन चेक-इन के लिए प्रतीक्षा करें, फिर रिपोर्ट की गई तैनाती को सत्यापित करें। - 4. **Observe → policy** खोलें और प्रभावित सत्रों को खोलकर पुष्टि करें कि वैध कार्य अब अवरुद्ध नहीं है। - + 3. मशीन के चेक-इन का इंतजार करें, फिर रिपोर्ट की गई तैनाती को सत्यापित करें। + 4. **Observe → policy** खोलें और प्रभावित सत्रों को खोलें यह पुष्टि करने के लिए कि मान्य कार्य अब अवरुद्ध नहीं है। - क्लाउड तैनाती रोलबैक एक डैशबोर्ड वर्कफ़्लो है। यह पुष्टि करने के लिए स्थानीय स्थिति का उपयोग करें कि सुधारी गई तैनाती मशीन तक पहुंच गई है: + मशीन पर हर तैनाती एक क्रमांकित जनरेशन है। उन्हें सूचीबद्ध करें, फिर एक को फिर से स्थापित करें: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` एक स्थानीय सत्र के लिए builtin, custom, और convention नीतियों को रोकता है। यह क्लाउड-प्रबंधित नीतियों को नहीं रोकता है, इसलिए यह एक खराब क्लाउड तैनाती के लिए कोई समाधान नहीं है। + `rollback` काउंटर को वापस न लपेटने के बजाय पुराने सेट को ले जाने वाली एक नई जनरेशन बनाता है, इसलिए इतिहास केवल-जोड़ रहता है, और यह एक जनरेशन से इनकार करता है जो एक ऐसी नीति का नाम देता है जो अक्षम या हटाई गई है। इसे `policies:write` के साथ एक हस्ताक्षरित-में सत्र की आवश्यकता है। `fp fleet diff ` दिखाता है कि क्या लक्षित था मशीन ने जो लागू किया उसके विरुद्ध — यह `behind` के रूप में पढ़ता है जब तक मशीन अगली बार पोल नहीं करती — और मशीन पर ही, `failproofai policies` जनरेशन सूचीबद्ध करता है जो यह चला रहा है। -## रोलबैक कब करें +## हर मशीन से एक नीति हटाएं + +```bash +fp policies disable # इसे इसे ले जाने वाली हर तैनाती से हटाएं +fp policies enable # इसे वापस जोड़ें +``` + +हर एक जनरेशन को जो यह छूता है उस पर एक नई जनरेशन बनाता है। उन जनरेशन में से एक को रोलबैक करना यह नहीं है कि आप `disable` को कैसे पूर्ववत करते हैं — `rollback` एक जनरेशन से इनकार करता है जो एक अक्षम नीति का नाम देता है, और अक्षम करने से पहले हर जनरेशन इस एक को नाम देता है। `fp policies enable` वापस का तरीका है, और यह बदले में अपनी स्वयं की जनरेशन बनाता है। + +## एक पैक को रोलबैक करें + +एक पैक आपके द्वारा स्थापित रिलीज़ के लिए पिन किया जाता है, इसलिए इसे रोलबैक करना एक पहले के को स्थापित करने का अर्थ है: + +```bash +failproofai policies show FailproofAI/policies --releases # हर संस्करण जो इसने प्रकाशित किया है, और कौन सा यहां है +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # उस एक को पिन करें +``` + +एक टर्मिनल के बिना, या `--policy`, `--category` या `--all` के साथ, फिर से जोड़ना आपके द्वारा चुने गए सबसेट को रखता है। कोई भी नहीं के साथ एक टर्मिनल पर, यह पिकर को लेखक के डिफ़ॉल्ट के साथ पूर्व-टिक किया खोलता है, और आप जो टिक करते हैं वह आपके चयन को प्रतिस्थापित करता है — इसलिए जो आपके पास था उसे फिर से टिक करें। + +## रोलबैक करने के लिए कब -- कोई नीति एक अपेक्षित उत्पादन कार्य को ब्लॉक करती है। -- मिलान वॉल्यूम अवलोकित रोलआउट की तुलना में अधिक बड़ा है। -- कोई नीति उन फील्ड पर निर्भर करती है जो कोई एकीकरण प्रदान नहीं करता है। -- एक नया संस्करण इच्छित विफलता मोड के बाहर का व्यवहार बदलता है। +- एक नीति एक अपेक्षित उत्पादन कार्रवाई को अवरुद्ध करती है। +- मिलान वॉल्यूम देखी गई रोलआउट की तुलना में भौतिक रूप से अधिक है। +- एक नीति ऐसे फ़ील्ड पर निर्भर करती है जो एक एकीकरण प्रदान नहीं करता है। +- एक नया संस्करण इच्छित विफलता मोड के बाहर व्यवहार को बदलता है। -रोलबैक के बाद, प्रभावित सत्रों को खोलें और उस स्थिति की पहचान करें जिसने गलत सकारात्मक का कारण बना। एक नया संस्करण बनाएं, असुरक्षित और वैध दोनों मामलों का परीक्षण करें, फिर अवलोकन चरण को दोहराएं। +रोलबैक करने के बाद, प्रभावित सत्रों को खोलें और झूठी सकारात्मकता के पीछे की स्थिति खोजें। एक नया संस्करण प्रकाशित करें, [test](/hi/policies/test) असुरक्षित और वैध दोनों मामलों को करें, और लागू करने से पहले इसे फिर से देखें। - प्रवर्तन को रोकना किसी घटना के दौरान उपयुक्त हो सकता है, लेकिन यह उस दायरे में हर सक्रिय नीति के लिए जोखिम को चौड़ा करता है। जहां संभव हो, विशिष्ट नीति संस्करण को रोलबैक करना पसंद करें। + `failproofai config --pause` एक सत्र के लिए स्थानीय नीतियों को निलंबित करता है और कभी Cloud-प्रबंधित नहीं, इसलिए यह एक बुरी Cloud तैनाती से निकलने का कोई रास्ता नहीं है। एक विराम भी अपने दायरे में हर नीति के लिए जोखिम को चौड़ा करता है; रोलबैक करना पसंद करें उस एक संस्करण को जो गलत व्यवहार कर रहा है। \ No newline at end of file diff --git a/docs/hi/policies/test.mdx b/docs/hi/policies/test.mdx new file mode 100644 index 00000000..128722f8 --- /dev/null +++ b/docs/hi/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "किसी नीति का परीक्षण करें" +description: "ऐसे ट्रैफ़िक के विरुद्ध बैकटेस्ट करें जो आपके पास पहले से है, और सिद्ध करें कि यह वह सब कुछ रोकता है जो इसे रोकना चाहिए और वह सब कुछ अनुमति देता है जो इसे देनी चाहिए, इससे पहले कि कोई मशीन इसे लागू करे।" +icon: "flask-conical" +--- + +हर नीति का परीक्षण दो तरीकों से करें: आपके एजेंटों द्वारा पहले से तैयार किए गए ट्रैफ़िक के विरुद्ध, और एक वैध कार्रवाई के विरुद्ध जिसे इसे अनुमति देनी चाहिए। एक नीति जिसने केवल असुरक्षित मामले को देखा है, उसका परीक्षण नहीं किया गया है। + +## ड्राफ्ट का बैकटेस्ट करें + + + + नीति संपादक एक ड्राफ्ट को उन कॉल के विरुद्ध फिर से चलाता है जो आपके फ्लीट ने पहले ही बना दिए हैं, इससे पहले कि आप इसे प्रकाशित करें। + + 1. **Admin → policy editor** में ड्राफ्ट खोलें। संपादक पुष्टि करता है कि यह JavaScript के रूप में पार्स होता है। + 2. **backtest** में, उन एजेंटों और समय विंडो को चुनें जिन्हें आप फिर से चलाना चाहते हैं — डिफ़ॉल्ट रूप से **every agent** और **30d** — और जब तक आप इसे सीमित नहीं करना चाहते, तब तक अंतिम फ़िल्टर को **everything** पर रखें। + 3. **run backtest** चुनें। + + ![एक ड्राफ्ट के अंतर्गत बैकटेस्ट पैनल जो JavaScript के रूप में पार्स होता है, इसके तीन फ़िल्टर और run backtest कार्रवाई के साथ, प्रकाशित संस्करण के ऊपर।](/images/dashboard/policy-backtest.png) + + परिणाम वह है जो ड्राफ्ट उन कॉल के साथ करता — जिसमें वह कितनी **working** कॉल को बाधित करता, यह भी शामिल है। ये गलत सकारात्मक हैं जो किसी भी एजेंट से मिलने से पहले पाए जाते हैं: ड्राफ्ट को कसें और जब तक वह संख्या आपके लिए स्वीकार्य न हो, तब तक इसे फिर से चलाएं। + + + बैकटेस्टिंग एक डैशबोर्ड सुविधा है। टर्मिनल से, इसके बजाय नीति को उन घटनाओं के विरुद्ध चलाएं जिन्हें आप नीचे वर्णित करते हैं। + + + +## इसे किसी ऐसी घटना के विरुद्ध चलाएं जिसे आप वर्णित करते हैं + +`fp policies test` नीति फ़ाइल को आपकी मशीन पर एक कृत्रिम घटना के विरुद्ध चलाता है और निर्णय की जांच करता है। कुछ भी प्रकाशित नहीं होता और कुछ भी Cloud तक नहीं पहुंचता: + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +`--event`, `--tool`, `--command` और `--file` के साथ घटना को आकार दें। नीति का अपना `match` फ़िल्टर अभी भी लागू होता है, इसलिए एक नीति जो आपके द्वारा वर्णित घटना को कवर नहीं करती है, एक निर्णय के बजाय `skipped` की रिपोर्ट करती है — आमतौर पर एक संकेत कि इसका `match` आपके इरादे से कम है। + +## इसे एक मशीन पर चलाएं + +अगला, इसे अपनी मशीन पर वास्तविक रूप से लागू करें, अपने स्वयं के एजेंट के विरुद्ध: + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +पहली कमांड फ़ाइल को मान्य करती है और स्थापित करती है; दूसरी पुष्टि करती है कि यह लोड हो गई है, बाकी सब कुछ के साथ जो यहां लागू हो रहा है। एजेंट को वह करने के लिए कहें जो नीति रोकती है और देखें कि यह अस्वीकार कर दिया जाता है, फिर वैध संस्करण करें और देखें कि यह आगे बढ़ता है। कोई और प्रभावित नहीं है। + +Cloud से जुड़ी मशीन पर, **Observe → policy** के अंतर्गत दोनों निर्णयों की जांच करें: नीति के नाम से फ़िल्टर करें, फिर प्रत्येक लिंक किए गए सत्र को खोलें ताकि टूल इनपुट की पुष्टि कर सकें जो इसके साथ मेल खाता है और यह कारण कि इसने क्या लौटाया। + +## जो विफल हो उसका परीक्षण करें + +स्थापना एक लापता फ़ाइल, एक सिंटैक्स त्रुटि, एक अनसुलझा आयात, एक शीर्ष-स्तरीय अपवाद, या एक मॉड्यूल जो लोडिंग के दौरान समय समाप्त हो जाता है, को अस्वीकार करता है — इसलिए फ़ाइल या इसमें शामिल किसी भी चीज में परिवर्तन के बाद इसे फिर से चलाएं। लागू समय पर वही टूटी हुई फ़ाइल लॉग की जाती है और **skipped** की जाती है ताकि हर दूसरी नीति चलती रहे: उत्पादन लॉग में एक लोड चेतावनी को खोई हुई लागू के रूप में मानें। कन्वेंशन फ़ाइलें स्थापना कमांड के बिना लोड होती हैं, इसलिए CI में एक स्पष्ट `failproofai policies --install --custom ` चरण रखें — यह वह है जो टूटी हुई नीति पर बिल्ड को विफल करता है। + +फिर इसे जो एजेंट वास्तव में भेजते हैं उससे खिलाएं, केवल वह इनपुट नहीं जिसकी आप अपेक्षा करते हैं: लापता फ़ील्ड, वैकल्पिक टूल नाम जैसे `Write` और `Edit`, Windows पथ, विकृत इनपुट। हर पथ पर एक इरादामय `allow`, `instruct` या `deny` लौटाएं, फ़ंक्शन को निर्धारक रखें, और किसी भी बाहरी कॉल को एक छोटे समय सीमा से बांधें। + +## फिर इसे प्रकाशित करें और इसे देखें + +एक बैकटेस्ट दिखाता है कि नीति उस ट्रैफ़िक के साथ क्या करती: यह नहीं दिखा सकता कि आपने जो ट्रैफ़िक नहीं देखा है वह क्या करेगा। संपादक में **publish version** चुनें (या `fp policies publish` चलाएं), फिर इसे [deploy it](/hi/policies/deploy) में **observe** मोड में पहले — इसके फैसले रिकॉर्ड किए जाते हैं और कुछ भी अवरुद्ध नहीं होता — और एक बार लागू करें जब इसके मेल असुरक्षित कार्यों को वैध कार्यों से अलग करते हैं। \ No newline at end of file diff --git a/docs/hi/reference/cloud-cli.mdx b/docs/hi/reference/cloud-cli.mdx index 0e1d1896..067e884f 100644 --- a/docs/hi/reference/cloud-cli.mdx +++ b/docs/hi/reference/cloud-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof Cloud CLI" -description: "Failproof AI Cloud को fp के साथ क्वेरी करने और प्रशासित करने के लिए संपूर्ण संदर्भ।" +description: "Failproof AI Cloud के साथ fp का उपयोग करके क्वेरी और प्रशासन के लिए संपूर्ण संदर्भ।" icon: "cloud-cog" --- -Cloud टेलीमेट्री का निरीक्षण करने, क्लाउड-प्रबंधित प्रवर्तन (नीतियां, फ्लीट परिनियोजन, गार्डरेल निर्णय) को प्रबंधित करने, और ऑडिट, निष्कर्ष, समस्याएं, सतर्कताएं, कुंजियां, उपयोगकर्ता, क्वेरी, और सेटिंग्स को प्रबंधित करने के लिए `fp` का उपयोग करें। स्थानीय हुक, नीतियां, कैप्चर, और मशीन नामांकन के लिए [`failproofai`](/hi/reference/failproof-cli) का उपयोग करें। +`fp` का उपयोग Cloud टेलीमेट्री को निरीक्षण करने, cloud-managed enforcement (policies, fleet deployments, guardrail decisions) को प्रबंधित करने, और audits, findings, issues, alerts, keys, users, queries, और settings को प्रबंधित करने के लिए करें। स्थानीय hooks, policies, capture, और machine enrollment के लिए [`failproofai`](/hi/reference/failproof-cli) का उपयोग करें। -Cloud CLI को एक अलग टूल के रूप में स्थापित करें: +Cloud CLI को एक isolated tool के रूप में install करें: ```bash uv tool install fp-cloud-cli @@ -26,55 +26,55 @@ fp whoami fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` -वैश्विक विकल्प कमांड से पहले आने चाहिए: +Global options को command से पहले आना चाहिए: ```bash fp --json sessions --since 24h ``` -टर्मिनल सहायता के लिए `fp COMMAND --help` या `fp COMMAND SUBCOMMAND --help` चलाएं। +Terminal help के लिए `fp COMMAND --help` या `fp COMMAND SUBCOMMAND --help` चलाएं। -## CLI कमांड +## CLI commands -### प्रमाणीकरण +### Authentication -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp login` | ईमेल किए गए एकबारी कोड के साथ साइन इन करें और एक संगठन चुनें। | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | सहेजे गए उपयोगकर्ता सत्र को निरस्त करें और हटाएं। | — | -| `fp whoami` | वर्तमान पहचान, प्रमाणीकरण मोड, संगठन और अनुमतियां दिखाएं। | — | -| `fp version` | स्थापित CLI संस्करण दिखाएं। | — | -| `fp help` | शीर्ष-स्तरीय कमांड सहायता दिखाएं। | — | +| `fp login` | ईमेल किए गए one-time code के साथ साइन इन करें और एक organization चुनें। | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | सहेजे गए user session को revoke और remove करें। | — | +| `fp whoami` | वर्तमान identity, authentication mode, organization, और permissions दिखाएं। | — | +| `fp version` | स्थापित CLI version दिखाएं। | — | +| `fp help` | शीर्ष-स्तर command help दिखाएं। | — | ```bash fp login --email you@example.com --org reliability-team fp whoami ``` -### घटनाएं +### Events ```text fp events [OPTIONS] ``` -व्यक्तिगत एजेंट घटनाओं की सूची बनाता है। डिफ़ॉल्ट लाइट फीड कच्चे पेलोड को बाहर निकालता है; `--full` का उपयोग केवल बंधी हुई जांच के लिए करें। +व्यक्तिगत agent events को सूचीबद्ध करता है। डिफ़ॉल्ट light feed raw payloads को बाहर करता है; `--full` का उपयोग केवल bounded investigation के लिए करें। -| विकल्प | विवरण | +| Option | Description | | --- | --- | -| `--limit`, `-n ` | अधिकतम कुल पंक्तियां। डिफ़ॉल्ट: `50`। | +| `--limit`, `-n ` | अधिकतम कुल rows। डिफ़ॉल्ट: `50`। | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, या `7d`। | -| `--from ` / `--to ` | ISO 8601 UTC रेंज; `--since` को ओवरराइड करता है। | -| `--env ` | पर्यावरण फ़िल्टर; मान दोहराएं या अल्पविराम से अलग करें। | -| `--event-type ` | घटना-प्रकार फ़िल्टर; मान दोहराएं या अल्पविराम से अलग करें। | -| `--agent-id ` | एजेंट फ़िल्टर; मान दोहराएं या अल्पविराम से अलग करें। | -| `--session-id ` | सत्र फ़िल्टर; मान दोहराएं या अल्पविराम से अलग करें। | -| `--search ` | पेलोड टेक्स्ट खोज; दोहराया जा सकता है, किसी भी शब्द से मेल खाता है। | -| `--order asc\|desc` | समय क्रम। डिफ़ॉल्ट: नवीनतम पहले। | -| `--all` | `--limit` तक स्वचालित-पृष्ठांकन। | -| `--cursor ` | एक अपारदर्शी कर्सर से फिर से शुरू करें। | -| `--page-size ` | `--all` के साथ प्रति अनुरोध पंक्तियां; अधिकतम `200`। | -| `--full` | भारी घटना समापन बिंदु के माध्यम से कच्चे पेलोड शामिल करें। | -| `--fields ` | केवल चयनित फ़ील्ड लौटाएं; `payload` का अनुरोध पूर्ण मोड को सक्षम करता है। | +| `--from ` / `--to ` | ISO 8601 UTC range; `--since` को override करता है। | +| `--env ` | Environment filter; values को repeat या comma-separate करें। | +| `--event-type ` | Event-type filter; values को repeat या comma-separate करें। | +| `--agent-id ` | Agent filter; values को repeat या comma-separate करें। | +| `--session-id ` | Session filter; values को repeat या comma-separate करें। | +| `--search ` | Payload text search; repeatable, किसी भी term के साथ matching। | +| `--order asc\|desc` | समय क्रम। डिफ़ॉल्ट: newest first। | +| `--all` | Auto-paginate `--limit` तक। | +| `--cursor ` | एक opaque cursor से resume करें। | +| `--page-size ` | `--all` के साथ rows per request; अधिकतम `200`। | +| `--full` | heavier event endpoint के माध्यम से raw payloads शामिल करें। | +| `--fields ` | केवल selected fields return करें; `payload` को requesting करने से full mode enable होता है। | ```bash fp events --session-id --order asc --all --limit 10000 @@ -82,171 +82,171 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` **`--limit` तक** पृष्ठांकन करता है, जो **50** तक चूक जाता है — इसलिए अपने आप से `--all` 50 पंक्तियों पर रुकता है। जब यह जल्दी बंद हो जाता है, तो प्रतिक्रिया से फिर से शुरू करने के लिए एक `next_cursor` ले जाता है; `"next_cursor": null` का मतलब है कि फीड वास्तव में समाप्त था। + `--all` **`--limit` तक पaginates करता है**, जिसका डिफ़ॉल्ट **50** है — तो अकेले `--all` 50 rows पर रुकता है। जब यह जल्दी रुकता है तो response एक `next_cursor` carry करता है; `"next_cursor": null` का मतलब है कि feed वास्तव में exhausted था। -### सत्र +### Sessions ```text fp sessions [OPTIONS] ``` -| विकल्प | विवरण | +| Option | Description | | --- | --- | -| `--limit`, `-n ` | अधिकतम कुल पंक्तियां। डिफ़ॉल्ट: `50`। | +| `--limit`, `-n ` | अधिकतम कुल rows। डिफ़ॉल्ट: `50`। | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, या `7d`। | -| `--from ` / `--to ` | ISO 8601 UTC रेंज; `--since` को ओवरराइड करता है। | -| `--env ` | पर्यावरण फ़िल्टर; मान दोहराएं या अल्पविराम से अलग करें। | -| `--status ` | `done`, `error`, या `timeout`; मान दोहराएं या अल्पविराम से अलग करें। | -| `--agent-id ` | किसी भी चयनित एजेंट को शामिल करने वाले सत्रों से मेल खाएं। | -| `--session-id ` | सत्र फ़िल्टर; मान दोहराएं या अल्पविराम से अलग करें। | -| `--all` | `--limit` तक स्वचालित-पृष्ठांकन। | -| `--cursor ` | एक अपारदर्शी कर्सर से फिर से शुरू करें। | -| `--page-size ` | `--all` के साथ प्रति अनुरोध पंक्तियां; अधिकतम `200`। | -| `--fields ` | केवल चयनित फ़ील्ड लौटाएं। | -| `--full-ids` | टर्मिनल आउटपुट में सत्र IDs को छोटा न करें। | -| `--agents` | मल्टी-एजेंट सत्रों के लिए एजेंट रोस्टर का विस्तार करें। | - -### मूल्यांकन +| `--from ` / `--to ` | ISO 8601 UTC range; `--since` को override करता है। | +| `--env ` | Environment filter; values को repeat या comma-separate करें। | +| `--status ` | `done`, `error`, या `timeout`; values को repeat या comma-separate करें। | +| `--agent-id ` | किसी भी selected agent को शामिल करने वाले sessions को match करें। | +| `--session-id ` | Session filter; values को repeat या comma-separate करें। | +| `--all` | Auto-paginate `--limit` तक। | +| `--cursor ` | एक opaque cursor से resume करें। | +| `--page-size ` | `--all` के साथ rows per request; अधिकतम `200`। | +| `--fields ` | केवल selected fields return करें। | +| `--full-ids` | Terminal output में session IDs को shorten न करें। | +| `--agents` | Multi-agent sessions के लिए agent roster को expand करें। | + +### Evaluations ```text fp evals [OPTIONS] ``` -| विकल्प | विवरण | +| Option | Description | | --- | --- | -| `--aggregate` | व्यक्तिगत मूल्यांकन के बजाय कुल और प्रति-स्कोर सांख्यिकी दिखाएं। | -| `--limit`, `-n ` | अधिकतम सूची पंक्तियां। डिफ़ॉल्ट: `50`। | -| `--since`, `--from`, `--to` | समय सीमा चुनें। | -| `--env`, `--status`, `--agent-id`, `--session-id` | एक सटीक मान प्रति फ़िल्टर तक संकीर्ण करें। | -| `--score KEY:MIN..MAX` | स्कोर रेंज; दोहराया जा सकता है और सभी रेंज से मेल खाना चाहिए। | -| `--all`, `--cursor`, `--page-size` | सूची पृष्ठांकन को नियंत्रित करें। | -| `--fields ` | केवल चयनित फ़ील्ड लौटाएं। | -| `--full-ids` | संपूर्ण सत्र IDs दिखाएं। | -| `--scores-full` | टर्मिनल आउटपुट में हर स्कोर दिखाएं। | - -### त्रुटियां +| `--aggregate` | Individual evaluations के बजाय totals और per-score statistics दिखाएं। | +| `--limit`, `-n ` | अधिकतम list rows। डिफ़ॉल्ट: `50`। | +| `--since`, `--from`, `--to` | समय range को चुनें। | +| `--env`, `--status`, `--agent-id`, `--session-id` | एक exact value प्रति filter तक narrow करें। | +| `--score KEY:MIN..MAX` | Score range; repeatable और सभी ranges को match करना होगा। | +| `--all`, `--cursor`, `--page-size` | List pagination को control करें। | +| `--fields ` | केवल selected fields return करें। | +| `--full-ids` | पूर्ण session IDs दिखाएं। | +| `--scores-full` | Terminal output में हर score दिखाएं। | + +### Errors ```text fp errors [OPTIONS] ``` -| विकल्प | विवरण | +| Option | Description | | --- | --- | -| `--aggregate` | पंक्तियों की सूची के बजाय मिलान करने वाली त्रुटियों को सारांशित करें। | -| `--limit`, `-n ` | अधिकतम सूची पंक्तियां। डिफ़ॉल्ट: `50`। | -| `--since`, `--from`, `--to` | समय सीमा चुनें। | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | त्रुटि जनसंख्या को संकीर्ण करें। | -| `--search ` | पेलोड टेक्स्ट खोजें; दोहराया जा सकता है। | +| `--aggregate` | Rows को list करने के बजाय matching errors को summarize करें। | +| `--limit`, `-n ` | अधिकतम list rows। डिफ़ॉल्ट: `50`। | +| `--since`, `--from`, `--to` | समय range को चुनें। | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Error population को narrow करें। | +| `--search ` | Payload text को search करें; repeatable। | | `--order asc\|desc` | समय क्रम। | -| `--all`, `--cursor`, `--page-size` | सूची पृष्ठांकन को नियंत्रित करें। | -| `--fields ` | केवल चयनित फ़ील्ड लौटाएं। | -| `--full-ids` | संपूर्ण सत्र IDs दिखाएं। | +| `--all`, `--cursor`, `--page-size` | List pagination को control करें। | +| `--fields ` | केवल selected fields return करें। | +| `--full-ids` | पूर्ण session IDs दिखाएं। | -### उपयोग और फ़िल्टर मान +### Usage और filter values -| कमांड | उद्देश्य | +| Command | Purpose | | --- | --- | -| `fp usage` | वर्तमान मीटरिंग विंडो के लिए उपयोग दिखाएं। | -| `fp list envs` | देखे गए वातावरण की सूची बनाएं। | -| `fp list agents` | देखे गए एजेंट IDs की सूची बनाएं। | -| `fp list event_types` | घटना प्रकार की सूची बनाएं। | -| `fp list score_filters` | मूल्यांकन स्कोर कुंजियों की सूची बनाएं। | -| `fp list models` | मॉडल नामों की सूची बनाएं। | -| `fp list hooks` | हुक नामों की सूची बनाएं। | -| `fp list tools` | टूल नामों की सूची बनाएं। | -| `fp list error_types` | त्रुटि प्रकार की सूची बनाएं। | - -### संगठन - -| कमांड | उद्देश्य | +| `fp usage` | वर्तमान metering window के लिए usage दिखाएं। | +| `fp list envs` | Observed environments को list करें। | +| `fp list agents` | Observed agent IDs को list करें। | +| `fp list event_types` | Event types को list करें। | +| `fp list score_filters` | Evaluation score keys को list करें। | +| `fp list models` | Model names को list करें। | +| `fp list hooks` | Hook names को list करें। | +| `fp list tools` | Tool names को list करें। | +| `fp list error_types` | Error types को list करें। | + +### Organizations + +| Command | Purpose | | --- | --- | -| `fp orgs list` | सुलभ संगठनों की सूची बनाएं। | -| `fp orgs switch [SLUG]` | एक सक्रिय संगठन सहेजें; लापता होने पर प्रेरित करें। | -| `fp orgs current` | सक्रिय संगठन दिखाएं। | -| `fp orgs perms` | सक्रिय संगठन में अपनी अनुमतियां दिखाएं। | +| `fp orgs list` | Accessible organizations को list करें। | +| `fp orgs switch [SLUG]` | एक active organization को save करें; omitted होने पर prompts। | +| `fp orgs current` | Active organization दिखाएं। | +| `fp orgs perms` | Active organization में आपकी permissions दिखाएं। | -### API कुंजियां +### API keys -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp keys list` | संगठन कुंजियों की सूची बनाएं। | `--show-id`; `--fields ` | -| `fp keys show NAME` | एक कुंजी और उसकी अनुदान दिखाएं। | — | -| `fp keys create NAME` | एक कुंजी बनाएं और इसके गुप्त को एक बार प्रकट करें। | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | अनुमति सेट को प्रतिस्थापित करें या अनुदान को समायोजित करें। | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | गुप्त को घुमाएं और प्रतिस्थापन को एक बार प्रकट करें। | `--yes`, `-y` | -| `fp keys disable NAME` | एक कुंजी को स्थायी रूप से निरस्त करें। | `--yes`, `-y` | +| `fp keys list` | Organization keys को list करें। | `--show-id`; `--fields ` | +| `fp keys show NAME` | एक key और इसके grants दिखाएं। | — | +| `fp keys create NAME` | एक key बनाएं और इसके secret को एक बार reveal करें। | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | Permission set को replace करें या grants को adjust करें। | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | Secret को rotate करें और replacement को एक बार reveal करें। | `--yes`, `-y` | +| `fp keys disable NAME` | एक key को permanently revoke करें। | `--yes`, `-y` | -अनुमति टोकन `resource:action` का उपयोग करते हैं, जैसे `events:add`। `--add` को दोहराएं, अल्पविराम से टोकन को अलग करें, या डॉटेड क्रियाओं का उपयोग करें जैसे `events:read.add`। +Permission tokens `resource:action` का उपयोग करते हैं, जैसे `events:add`। `--add` को repeat करें, tokens को comma-separate करें, या `events:read.add` जैसे dotted actions का उपयोग करें। -### क्वेरीज +### Queries -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp query list` | सहेजी गई क्वेरीज की सूची बनाएं। | `--show-id`; `--fields ` | -| `fp query show NAME` | एक क्वेरी दिखाएं। | — | -| `fp query create NAME` | एक क्वेरी सहेजें। | `--sql `; `--description` | -| `fp query update NAME` | एक क्वेरी को अपडेट या नाम बदलें। | `--name`; `--sql`; `--description`; `--yes`, `-y` | -| `fp query delete NAME` | एक सहेजी गई क्वेरी को हटाएं। | `--yes`, `-y` | -| `fp query run [NAME]` | एक सहेजी गई क्वेरी या तदर्थ SQL चलाएं। | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | क्वेरीयोग्य तालिकाओं की सूची बनाएं या एक तालिका का निरीक्षण करें। | — | +| `fp query list` | Saved queries को list करें। | `--show-id`; `--fields ` | +| `fp query show NAME` | एक query दिखाएं। | — | +| `fp query create NAME` | एक query को save करें। | `--sql `; `--description` | +| `fp query update NAME` | एक query को update या rename करें। | `--name`; `--sql`; `--description`; `--yes`, `-y` | +| `fp query delete NAME` | एक saved query को delete करें। | `--yes`, `-y` | +| `fp query run [NAME]` | एक saved query या ad-hoc SQL को run करें। | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query schema [TABLE]` | Queryable tables को list करें या एक table को inspect करें। | — | -### उपयोगकर्ता +### Users -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp users list` | संगठन सदस्यों की सूची बनाएं। | `--active-only`; `--show-id` | -| `fp users show EMAIL` | एक सदस्य और उनकी अनुदान दिखाएं। | — | -| `fp users create EMAIL` | एक सदस्य जोड़ें। | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | सदस्य की अनुदान बदलें। | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp users disable EMAIL` | साइन-इन को अक्षम करें। | `--yes`, `-y` | -| `fp users enable EMAIL` | साइन-इन को फिर से सक्षम करें। | `--yes`, `-y` | +| `fp users list` | Organization members को list करें। | `--active-only`; `--show-id` | +| `fp users show EMAIL` | एक member और उनके grants दिखाएं। | — | +| `fp users create EMAIL` | एक member को add करें। | `--permission-set`; `--add`; `--remove` | +| `fp users update EMAIL` | एक member के grants को change करें। | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users disable EMAIL` | Sign-in को disable करें। | `--yes`, `-y` | +| `fp users enable EMAIL` | Sign-in को re-enable करें। | `--yes`, `-y` | -### सेटिंग्स +### Settings -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp settings list` | संगठन सेटिंग्स और वर्तमान मानों की सूची बनाएं। | — | -| `fp settings schema` | स्वीकृत मान और विवरण दिखाएं। | — | -| `fp settings set KEY` | एक मौजूदा सेटिंग बदलें। | `--value`, `--json-value`, `--file` में से एक; वैकल्पिक `--yes`, `-y` | +| `fp settings list` | Organization settings और current values को list करें। | — | +| `fp settings schema` | Accepted values और descriptions दिखाएं। | — | +| `fp settings set KEY` | एक existing setting को change करें। | `--value`, `--json-value`, `--file` में से बिल्कुल एक; optional `--yes`, `-y` | -### सतर्कताएं +### Alerts -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp alerts list` | सतर्कता नियमों की सूची बनाएं। | `--show-id` | -| `fp alerts show NAME` | एक सतर्कता दिखाएं। | — | -| `fp alerts create NAME` | एक सतर्कता बनाएं। | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | एक सतर्कता को अपडेट या नाम बदलें। | विकल्प बनाएं प्लस `--name`; `--yes`, `-y` | -| `fp alerts delete NAME` | एक सतर्कता हटाएं। | `--yes`, `-y` | -| `fp alerts test NAME` | एक परीक्षण सूचना भेजें। | `--channels`; `--yes`, `-y` | +| `fp alerts list` | Alert rules को list करें। | `--show-id` | +| `fp alerts show NAME` | एक alert दिखाएं। | — | +| `fp alerts create NAME` | एक alert बनाएं। | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | +| `fp alerts update NAME` | एक alert को update या rename करें। | create options plus `--name`; `--yes`, `-y` | +| `fp alerts delete NAME` | एक alert को delete करें। | `--yes`, `-y` | +| `fp alerts test NAME` | एक test notification भेजें। | `--channels`; `--yes`, `-y` | -सतर्कता गंभीरताएं `info`, `warning`, और `critical` हैं। ट्रिगर प्रकार `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound`, और `per_event` हैं। मूल्यांकन अंतराल 30 और 86,400 सेकंड के बीच होना चाहिए। +Alert severities हैं `info`, `warning`, और `critical`। Trigger kinds हैं `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound`, और `per_event`। Evaluation intervals 30 और 86,400 seconds के बीच होने चाहिए। -### ऑडिट +### Audits -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp audits list` | ऑडिट की सूची बनाएं। | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | एक ऑडिट परिभाषा और स्थिति दिखाएं। | — | -| `fp audits create NAME` | एक ऑडिट बनाएं और तुरंत इसके पहले रन को कतार में रखें। | [बनाएं विकल्प](#audit-create-options) देखें। | -| `fp audits edit NAME` | ऑडिट सेटिंग्स को प्रतिस्थापित करते समय अनिर्दिष्ट मान बनाए रखें। | परिभाषा विकल्प बनाएं; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | एक ऑडिट, इसके निष्कर्ष, और रन इतिहास को हटाएं। | `--yes`, `-y` | -| `fp audits run NAME` | एक मैनुअल रन को कतार में रखें। | — | -| `fp audits runs NAME` | रन इतिहास की सूची बनाएं। | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | संक्षिप्त और संदर्भ URL प्राप्त स्थिति दिखाएं। | — | -| `fp audits context-set NAME` | संक्षिप्त या संदर्भ URLs बदलें। | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | संदर्भ URLs को फिर से प्राप्त करें। | — | -| `fp audits findings` | निष्कर्षों की सूची बनाएं। | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | एक निष्कर्ष और इसके साक्ष्य दिखाएं। | — | -| `fp audits ack FINDING_ID` | एक निष्कर्ष को स्वीकार करें। | `--reason` | -| `fp audits mute FINDING_ID` | एक आवर्ती पैटर्न को दबाएं। | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | एक पैटर्न को कार्यवाही योग्य नहीं चिह्नित करें और इसे दबाएं। | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | एक निष्कर्ष को भविष्य के दमन के बिना ठीक चिह्नित करें। | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | एक निष्कर्ष को लाइव कतार में वापस करें और दमन साफ़ करें। | — | -| `fp audits assign FINDING_ID` | निष्कर्ष स्वामी सेट करें। | आवश्यक `--to ` | - -#### ऑडिट बनाएं विकल्प +| `fp audits list` | Audits को list करें। | `--enabled-only`; `--show-id` | +| `fp audits show NAME` | एक audit definition और state दिखाएं। | — | +| `fp audits create NAME` | एक audit बनाएं और तुरंत इसके first run को queue करें। | [create options](#audit-create-options) देखें। | +| `fp audits edit NAME` | Audit settings को replace करें जबकि unspecified values को retain करें। | create definition options; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | एक audit, इसके findings, और run history को delete करें। | `--yes`, `-y` | +| `fp audits run NAME` | एक manual run को queue करें। | — | +| `fp audits runs NAME` | Run history को list करें। | `--limit`, `-n`; `--show-id` | +| `fp audits context-show NAME` | Brief और reference URL fetch state दिखाएं। | — | +| `fp audits context-set NAME` | Brief या reference URLs को change करें। | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-refresh NAME` | Reference URLs को re-fetch करें। | — | +| `fp audits findings` | Findings को list करें। | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | +| `fp audits finding FINDING_ID` | एक finding और इसके evidence दिखाएं। | — | +| `fp audits ack FINDING_ID` | एक finding को acknowledge करें। | `--reason` | +| `fp audits mute FINDING_ID` | एक recurring pattern को suppress करें। | `--reason`; `--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | एक pattern को not actionable के रूप में mark करें और suppress करें। | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | एक finding को fixed के रूप में mark करें बिना future suppression के। | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | एक finding को live queue में return करें और suppression को clear करें। | — | +| `fp audits assign FINDING_ID` | Finding owner को set करें। | required `--to ` | + +#### Audit create options ```bash fp audits create checkout-reliability \ @@ -259,122 +259,122 @@ fp audits create checkout-reliability \ --url https://runbooks.example.com/checkout ``` -| विकल्प | विवरण | +| Option | Description | | --- | --- | -| `--file ` | परिभाषा को JSON पर आधारित करें, या stdin के लिए `-` का उपयोग करें। स्पष्ट फ्लैग फ़ाइल मानों को ओवरराइड करते हैं। | -| `--description ` | विफलता प्रश्न या उद्देश्य बताएं। | -| `--enabled` / `--disabled` | शेड्यूलिंग को चालू या बंद शुरू करें। डिफ़ॉल्ट: सक्षम। | +| `--file ` | Definition को JSON के आधार पर set करें, या stdin के लिए `-` का उपयोग करें। Explicit flags file values को override करते हैं। | +| `--description ` | Failure question या purpose को state करें। | +| `--enabled` / `--disabled` | Scheduling को on या off से start करें। डिफ़ॉल्ट: enabled। | | `--schedule-interval-secs ` | `3600`–`604800`। डिफ़ॉल्ट: `86400`। | -| `--schedule-anchor ` | ISO 8601 रूप में निर्धारित UTC चरण। डिफ़ॉल्ट: अगला 09:00 UTC। | -| `--window-mode since_last\|fixed` | अंतिम पूरी तरह से विश्लेषण की गई विंडो के बाद जारी रखें या बार-बार एक रोलिंग विंडो का निरीक्षण करें। डिफ़ॉल्ट: `since_last`। | +| `--schedule-anchor ` | ISO 8601 form में fixed UTC phase। डिफ़ॉल्ट: next 09:00 UTC। | +| `--window-mode since_last\|fixed` | Last fully analyzed window के बाद continue करें या repeatedly एक rolling window को inspect करें। डिफ़ॉल्ट: `since_last`। | | `--lookback-window-secs ` | `3600`–`7776000`। डिफ़ॉल्ट: `604800`। | -| `--scope ''` | `environments`, `agent_ids`, या अन्य समर्थित स्कोप फ़ील्ड द्वारा फ़िल्टर करें। | -| `--ignore-error-type ` | त्रुटि प्रकार बाहर करें; दोहराएं या अल्पविराम से अलग करें। | -| `--llm` / `--no-llm` | एजेंटिक विश्लेषण सक्षम या अक्षम करें। डिफ़ॉल्ट: सक्षम। | -| `--top-k ` | `1`–`500` निष्कर्ष बनाए रखें। डिफ़ॉल्ट: `50`। | -| `--sensitivity low\|medium\|high` | रिपोर्टिंग संवेदनशीलता सेट करें। डिफ़ॉल्ट: `medium`। | -| `--channels ''` | सूचना चैनल सरणी। | -| `--text ` | इनलाइन संक्षिप्त, अधिकतम 8,192 वर्ण। | -| `--text-file ` | एक फ़ाइल से संक्षिप्त पढ़ें; `--text` के साथ परस्पर अनन्य। | -| `--url ` | एक सार्वजनिक HTTPS संदर्भ जोड़ें; पांच बार तक दोहराएं। | - -जब पहले रन को इसकी आवश्यकता हो तो बनाते समय संदर्भ शामिल करें। बनाना सूचीबद्ध रन शुरू होने से पहले परिभाषा और संदर्भ को एक साथ प्रतिबद्ध करता है। +| `--scope ''` | `environments`, `agent_ids`, या अन्य supported scope fields द्वारा filter करें। | +| `--ignore-error-type ` | Error types को exclude करें; repeat या comma-separate करें। | +| `--llm` / `--no-llm` | Agentic analysis को enable या disable करें। डिफ़ॉल्ट: enabled। | +| `--top-k ` | `1`–`500` findings को retain करें। डिफ़ॉल्ट: `50`। | +| `--sensitivity low\|medium\|high` | Reporting sensitivity को set करें। डिफ़ॉल्ट: `medium`। | +| `--channels ''` | Notification channel array। | +| `--text ` | Inline brief, अधिकतम 8,192 characters। | +| `--text-file ` | एक file से brief को read करें; `--text` के साथ mutually exclusive। | +| `--url ` | एक public HTTPS reference को add करें; पांच बार तक repeat करें। | + +जब first run को इसकी आवश्यकता हो तो creation के दौरान context को include करें। Creation definition और context को एक साथ commit करता है queued run शुरू होने से पहले। - `fp audits run` अतुल्यकालिक है। सूचीबद्ध रन को पढ़ने से पहले `fp audits runs NAME` तक पोल करें जब तक कि नवीनतम रन सफल या विफल न हो जाए। + `fp audits run` asynchronous है। Latest run के succeed या fail होने तक `fp audits runs NAME` को poll करें इससे पहले कि आप इसके findings को read करें। -### समस्याएं +### Issues -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp issues list` | समस्याओं की सूची बनाएं। | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | खुली या चयनित समस्या अवस्थाओं की गिनती करें। | `--state` | -| `fp issues show INCIDENT_ID` | समस्या विवरण, टिप्पणियां, सदस्य और गतिविधि दिखाएं। | — | -| `fp issues open` | एक मैनुअल या सतर्कता-लिंक्ड समस्या खोलें। | आवश्यक `--summary`; वैकल्पिक `--title`, `--alert-id`, `--severity` | -| `fp issues ack INCIDENT_ID` | एक समस्या को स्वीकार करें। | — | -| `fp issues assign INCIDENT_ID` | असाइन करने वालों को प्रतिस्थापित करें; विकल्प को स्पष्ट करने के लिए छोड़ दें। | दोहराया जा सकता है `--assignee` | -| `fp issues resolve INCIDENT_ID` | एक समस्या को समाधान करें। | `--yes`, `-y` | -| `fp issues comment-list INCIDENT_ID` | टिप्पणियों की सूची बनाएं। | — | -| `fp issues comment-add INCIDENT_ID` | एक टिप्पणी जोड़ें। | `--body`, `--file` में से एक | -| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | एक टिप्पणी हटाएं। | `--yes`, `-y` | -| `fp issues subscribers INCIDENT_ID` | सदस्यों की सूची बनाएं। | — | -| `fp issues subscribe INCIDENT_ID` | स्वयं या किसी अन्य ऑपरेटर को सदस्यता लें। | `--email` | -| `fp issues unsubscribe INCIDENT_ID` | एक सदस्यता हटाएं। | `--email` | - -मान्य समस्या अवस्थाएं `firing`, `acknowledged`, और `resolved` हैं। स्टैंडअलोन समस्या गंभीरताएं `info`, `warning`, और `critical` हैं। - -### Cloud सहायक - -| कमांड | उद्देश्य | विकल्प | +| `fp issues list` | Issues को list करें। | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | Open या selected issue states को count करें। | `--state` | +| `fp issues show INCIDENT_ID` | Issue details, comments, subscribers, और activity दिखाएं। | — | +| `fp issues open` | एक manual या alert-linked issue को open करें। | required `--summary`; optional `--title`, `--alert-id`, `--severity` | +| `fp issues ack INCIDENT_ID` | एक issue को acknowledge करें। | — | +| `fp issues assign INCIDENT_ID` | Assignees को replace करें; clear करने के लिए option को omit करें। | repeatable `--assignee` | +| `fp issues resolve INCIDENT_ID` | एक issue को resolve करें। | `--yes`, `-y` | +| `fp issues comment-list INCIDENT_ID` | Comments को list करें। | — | +| `fp issues comment-add INCIDENT_ID` | एक comment को add करें। | `--body`, `--file` में से बिल्कुल एक | +| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | एक comment को delete करें। | `--yes`, `-y` | +| `fp issues subscribers INCIDENT_ID` | Subscribers को list करें। | — | +| `fp issues subscribe INCIDENT_ID` | अपने आप को या किसी अन्य operator को subscribe करें। | `--email` | +| `fp issues unsubscribe INCIDENT_ID` | एक subscription को remove करें। | `--email` | + +Valid issue states हैं `firing`, `acknowledged`, और `resolved`। Standalone issue severities हैं `info`, `warning`, और `critical`। + +### Cloud assistant + +| Command | Purpose | Options | | --- | --- | --- | -| `fp agent health` | सहायक उपलब्धता और कॉन्फ़िगरेशन की जांच करें। | — | -| `fp agent models` | उपलब्ध सहायक मॉडल सूचीबद्ध करें। | — | -| `fp agent chats` | सहेजी गई चैट सूचीबद्ध करें। | — | -| `fp agent ask [MESSAGE]` | एक चैट शुरू करें या जारी रखें; संदेश लापता होने पर stdin पढ़ता है। | `--chat`; `--model`; `--page-context` | -| `fp agent show CHAT_ID` | एक सहेजी गई बातचीत दिखाएं। | — | -| `fp agent rename CHAT_ID` | एक बातचीत का नाम बदलें। | आवश्यक `--title` | -| `fp agent delete CHAT_ID` | एक बातचीत हटाएं। | `--yes`, `-y` | +| `fp agent health` | Assistant availability और configuration को check करें। | — | +| `fp agent models` | Available assistant models को list करें। | — | +| `fp agent chats` | Saved chats को list करें। | — | +| `fp agent ask [MESSAGE]` | एक chat को start या continue करें; message omitted होने पर stdin को read करें। | `--chat`; `--model`; `--page-context` | +| `fp agent show CHAT_ID` | एक saved conversation दिखाएं। | — | +| `fp agent rename CHAT_ID` | एक conversation को rename करें। | required `--title` | +| `fp agent delete CHAT_ID` | एक conversation को delete करें। | `--yes`, `-y` | -### नीतियां +### Policies -Cloud-प्रबंधित नीति संस्करण। **केवल सत्र** — यहां हर कमांड `2` को API कुंजी के तहत बाहर निकालता है, किसी भी अनुरोध से पहले, क्योंकि ये मूल-केवल लेखन मार्ग हैं जो जानबूझकर `/v1` से अनुपस्थित हैं। +Cloud-managed policy versions। **Session-only** — यहां हर command एक API key के तहत exit `2` पर जाता है, किसी भी request से पहले, क्योंकि ये root-only write routes हैं जानबूझकर `/v1` से अनुपस्थित हैं। -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp policies list` | नीति संस्करणों की सूची बनाएं। | `--json` | -| `fp policies show POLICY_ID` | एक नीति अपने स्रोत के साथ दिखाएं। | — | -| `fp policies publish NAME PATH` | एक स्थानीय `.mjs` से एक संस्करण बनाएं। | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | इसे हर परिनियोजन में वापस जोड़ें जहां से इसे हटाया गया था, प्रत्येक पर एक नई पीढ़ी बनाते हुए। | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | इसे हर परिनियोजन से हटाएं जो इसे ले जा रहा है, प्रत्येक पर एक नई पीढ़ी बनाते हुए। | `--yes`, `-y` | -| `fp policies delete POLICY_ID` | एक नीति संस्करण हटाएं। | `--yes`, `-y` | -| `fp policies test PATH` | एक नीति को स्थानीय रूप से एक सिंथेटिक संदर्भ के विरुद्ध चलाएं। प्रत्येक नीति के `match` फ़िल्टर को लागू करता है, इसलिए एक जो दिए गए घटना/उपकरण को कवर नहीं करता है, `skipped` की रिपोर्ट की जाती है बजाय चलाए जाने के। | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | सहायक के साथ एक नीति का मसौदा तैयार करें। `policies:write` की आवश्यकता है। | — | +| `fp policies list` | Policy versions को list करें। | `--json` | +| `fp policies show POLICY_ID` | एक policy अपने source के साथ दिखाएं। | — | +| `fp policies publish NAME PATH` | एक local `.mjs` से एक version को mint करें। | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | इसे हर deployment में वापस add करें जहां से इसे remove किया गया था, हर एक पर एक नई generation को mint करते हुए। | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | इसे हर deployment से remove करें जो इसे carry कर रहा है, हर एक पर एक नई generation को mint करते हुए। | `--yes`, `-y` | +| `fp policies delete POLICY_ID` | एक policy version को delete करें। | `--yes`, `-y` | +| `fp policies test PATH` | एक synthetic context के against एक policy को locally run करें। हर policy के `match` filter को apply करता है, तो एक जो given event/tool को cover नहीं करता है `skipped` के रूप में rather than run किया जाता है। | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | Assistant के साथ एक policy को draft करें। `policies:write` की जरूरत है। | — | -### फ्लीट +### Fleet -कौन सी मशीनें कौन सी नीतियां चलाती हैं। **केवल सत्र**, ऊपर जैसा ही कारण। +कौन से machines कौन सी policies को run करते हैं। **Session-only**, ऊपर जैसा ही कारण। -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp fleet list` | नामांकित मशीनों और उनकी परिनियोजन पीढ़ी की सूची बनाएं। | — | -| `fp fleet show MACHINE_ID` | एक मशीन वर्तमान में चलाई जा रही नीति सेट। | — | -| `fp fleet deploy MACHINE_ID` | **मशीन की पूरी नीति सेट को प्रतिस्थापित करता है।** योजना प्रिंट करता है और केवल `--json` बिना एक इंटरैक्टिव टर्मिनल पर पूछता है। | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | एक मशीन को दूसरी परिनियोजन के विरुद्ध तुलना करें। | — | -| `fp fleet history MACHINE_ID` | एक मशीन के लिए पिछली परिनियोजन। | — | -| `fp fleet rollback MACHINE_ID` | एक पिछली परिनियोजन को पुनः स्थापित करें। | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | मशीन को एक पठनीय नाम दें। | आवश्यक `--name` | +| `fp fleet list` | Enrolled machines और उनकी deployment generation को list करें। | — | +| `fp fleet show MACHINE_ID` | एक machine को currently run कर रहा policy set। | — | +| `fp fleet deploy MACHINE_ID` | **Machine के पूरे policy set को replace करता है।** Plan को print करता है और एक interactive terminal बिना `--json` पर ही पूछता है। | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | एक machine को दूसरी deployment के against compare करें। | — | +| `fp fleet history MACHINE_ID` | एक machine के लिए past deployments। | — | +| `fp fleet rollback MACHINE_ID GENERATION` | एक past generation के policy set को reinstate करें, एक नई generation के रूप में। | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | एक machine को एक readable name दें। | required `--name` | -### गार्डरेल +### Guardrails -प्रवर्तन वास्तव में क्या करता है। **केवल सत्र**, ऊपर जैसा ही कारण। +Enforcement ने वास्तव में क्या किया। **Session-only**, ऊपर जैसा ही कारण। -| कमांड | उद्देश्य | विकल्प | +| Command | Purpose | Options | | --- | --- | --- | -| `fp guardrails summary` | कवरेज, अवरुद्ध/मूल्यांकित कुल, एक अस्वीकार स्पार्कलाइन, और प्रति-नीति तालिका। | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | विंडो के ऊपर बाल्टी में निर्णय, हर नीति स्रोत के पार योग। | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | Coverage, blocked/evaluated totals, एक deny sparkline, और per-policy table। | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Window के ऊपर bucketed decisions, हर policy source के across summed। | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -## वैश्विक फ्लैग +## Global flags -| फ्लैग | विवरण | +| Flag | Description | | --- | --- | -| `--json` | मशीन-पठनीय JSON उत्सर्जित करें। | -| `--base-url ` | एक स्व-होस्टेड या विकास डैशबोर्ड का उपयोग करें। | -| `--org ` | इस आह्वान के लिए एक संगठन चुनें। | -| `--token ` | सहेजे गए उपयोगकर्ता-सत्र टोकन को ओवरराइड करें। | -| `--api-key ` | API कुंजी के साथ स्वचालन प्रमाणित करें; कभी सहेजा नहीं। | -| `--timeout ` | HTTP समय समाप्त; सकारात्मक होना चाहिए। डिफ़ॉल्ट: `30`। | -| `--quiet`, `-q` | stderr पर स्थिति आउटपुट को दबाएं। | -| `--no-color` | रंगीन आउटपुट अक्षम करें। | -| `--insecure` / `--secure` | TLS प्रमाणपत्र सत्यापन को अक्षम या पुनः स्थापित करें। | -| `--version` | असंपीड़ित संस्करण प्रिंट करें और बाहर निकलें। | -| `--help`, `-h` | सहायता दिखाएं। | - -`--api-key` स्वचालन के लिए अभिप्रेत है। लॉगिन, संगठन स्विचिंग, और सहायक कमांड को उपयोगकर्ता सत्र की आवश्यकता है। - -## पर्यावरण चर - -| चर | समकक्ष या उद्देश्य | +| `--json` | Machine-readable JSON को emit करें। | +| `--base-url ` | एक self-hosted या development dashboard का उपयोग करें। | +| `--org ` | इस invocation के लिए एक organization को select करें। | +| `--token ` | Saved user-session token को override करें। | +| `--api-key ` | एक API key के साथ automation को authenticate करें; कभी save नहीं किया जाता। | +| `--timeout ` | HTTP timeout; सकारात्मक होना चाहिए। डिफ़ॉल्ट: `30`। | +| `--quiet`, `-q` | stderr पर status output को suppress करें। | +| `--no-color` | Colored output को disable करें। | +| `--insecure` / `--secure` | TLS certificate verification को disable या restore करें। | +| `--version` | Unboxed version को print करें और exit करें। | +| `--help`, `-h` | Help दिखाएं। | + +`--api-key` automation के लिए intended है। Login, organization switching, और assistant commands को एक user session की आवश्यकता है। + +## Environment variables + +| Variable | Equivalent या purpose | | --- | --- | | `FP_DASHBOARD_URL` | `--base-url` | | `FP_ORG` | `--org` | @@ -382,18 +382,18 @@ Cloud-प्रबंधित नीति संस्करण। **केव | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | CLI कॉन्फ़िगरेशन निर्देशिका को स्थानांतरित करें (डिफ़ॉल्ट `~/.failproofai/fpcli`)। | -| `FP_ANALYTICS_DISABLED` या `DO_NOT_TRACK` | अनाम CLI विश्लेषण अक्षम करें। | -| `NO_COLOR` | रंगीन आउटपुट अक्षम करें। | +| `FP_HOME` | CLI configuration directory को relocate करें (डिफ़ॉल्ट `~/.failproofai/fpcli`)। | +| `FP_ANALYTICS_DISABLED` या `DO_NOT_TRACK` | Anonymous CLI analytics को disable करें। | +| `NO_COLOR` | Colored output को disable करें। | -स्पष्ट फ्लैग पर्यावरण चर को ओवरराइड करते हैं, जो सहेजे गए कॉन्फ़िगरेशन को ओवरराइड करते हैं। API-कुंजी मोड में, `--org` या `FP_ORG` के साथ किरायेदार को स्पष्ट रूप से चुनें। +Explicit flags environment variables को override करते हैं, जो saved configuration को override करते हैं। API-key mode में, `--org` या `FP_ORG` के साथ tenant को explicitly select करें। - `AGENTEYE_*` वर्तनी के ये `fp` द्वारा **नहीं पढ़े जाते** और कभी नहीं थे — CLI `FP_*` (fp_cli/app.py) घोषित करता है, और एक अज्ञात चर त्रुटि नहीं है। `AGENTEYE_DASHBOARD_URL` सेट करना CLI को पुनः लक्षित नहीं करता; इसे अनदेखा किया जाता है और कमांड चुपचाप सहेजे गए डैशबोर्ड के विरुद्ध चलता है। + इन के `AGENTEYE_*` spellings **`fp` द्वारा read नहीं किए जाते** और कभी नहीं थे — CLI `FP_*` (`fp_cli/app.py`) को declare करता है, और एक unknown variable एक error नहीं है। `AGENTEYE_DASHBOARD_URL` को set करने से CLI को retarget नहीं किया जाता; इसे ignore किया जाता है और command silently saved dashboard के against run होता है। - `AGENTEYE_HOME` और `AGENTEYE_ENVIRONMENT` अभी भी मौजूद हैं, लेकिन वे **कलेक्टर और टेलीमेट्री SDK** के हैं, इस CLI के नहीं। + `AGENTEYE_HOME` और `AGENTEYE_ENVIRONMENT` अभी भी exist करते हैं, लेकिन वे **collector और telemetry SDK** को belong करते हैं, इस CLI को नहीं। - कमांड जो कॉन्फ़िगरेशन को हटाते हैं, निरस्त करते हैं, दबाते हैं, समाधान करते हैं, या प्रतिस्थापित करते हैं, डिफ़ॉल्ट रूप से प्रेरित करते हैं। केवल सक्रिय संगठन और लक्ष्य को सत्यापित करने के बाद `--yes` का उपयोग करें। + जो commands delete, revoke, suppress, resolve, या replace configuration करते हैं वे डिफ़ॉल्ट रूप से prompt करते हैं। `--yes` को केवल active organization और target को verify करने के बाद उपयोग करें। \ No newline at end of file diff --git a/docs/hi/reference/custom-agents.mdx b/docs/hi/reference/custom-agents.mdx index fd07c66b..81c19fd1 100644 --- a/docs/hi/reference/custom-agents.mdx +++ b/docs/hi/reference/custom-agents.mdx @@ -1,21 +1,21 @@ --- -title: "कस्टम एजेंट्स" +title: "कस्टम agents" description: "failproofai-sdk के लिए कॉन्फ़िगरेशन, इवेंट कैटलॉग, सहसंबंध नियम, और डिलीवरी।" icon: "python" --- -हर सेटिंग, मेथड और फील्ड क्या करता है। यदि आप पहली बार इंस्ट्रूमेंटेशन कर रहे हैं, तो गाइड से शुरू करें — यह पृष्ठ चीजों को देखने के लिए है। +हर सेटिंग, मेथड और फील्ड क्या करता है। यदि आप पहली बार instrumentation कर रहे हैं, तो गाइड से शुरू करें — यह पृष्ठ चीजों को देखने के लिए है। - - इंस्टॉल करें, इंस्ट्रूमेंट करें, इवेंट मेथड्स, एक कार्यशील उदाहरण, और सामान्य समस्याएं। + + इंस्टॉल, instrumentation, इवेंट मेथड, एक व्यावहारिक उदाहरण, और सामान्य समस्याएं। - LangChain, CrewAI, LlamaIndex और Pydantic AI एक कॉल से खुद को इंस्ट्रूमेंट करते हैं। + LangChain, CrewAI, LlamaIndex और Pydantic AI एक कॉल के साथ खुद को instrument करते हैं। -Python 3.10 या नवीनतर। कोई रनटाइम निर्भरताएं नहीं। +Python 3.10 या नया। कोई runtime dependency नहीं। ## इंस्टॉल करें @@ -23,24 +23,30 @@ Python 3.10 या नवीनतर। कोई रनटाइम निर pip install failproofai-sdk ``` -पैकेज को `failproofai-sdk` के रूप में इंस्टॉल किया गया है और Python में `failproofai_sdk` के रूप में आयात किया गया है। `failproofai-sdk[langgraph]` जैसे फ्रेमवर्क एक्सट्रास फ्रेमवर्क को ही इंस्टॉल करते हैं; एडेप्टर हमेशा बेस व्हील में शिप होते हैं। +पैकेज को `failproofai-sdk` के रूप में इंस्टॉल किया जाता है और Python में `failproofai_sdk` के रूप में आयात किया जाता है। फ्रेमवर्क extras जैसे `failproofai-sdk[langgraph]` फ्रेमवर्क को ही इंस्टॉल करते हैं; adapters हमेशा base wheel में शिप होते हैं। -## Failproof डेमॉन कनेक्ट करें +## Failproof daemon को कनेक्ट करें - - 1. **Admin → Keys** पर जाएं और `events:add` के साथ एक कुंजी बनाएं। - 2. [Failproof डेमॉन को Cloud से कनेक्ट करें](/hi/start/setup#connect-a-machine-to-cloud) एजेंट मशीन पर। - 3. एक इंस्ट्रूमेंटेड सेशन चलाएं, फिर **Observe → Events** के तहत इसकी सटीक ID खोजें। - 4. **Observe → Sessions** पर जाएं, वही वातावरण चुनें, और पुनर्निर्मित ट्रेस खोलें। + + 1. **Admin → Keys** पर जाएं और `events:add` के साथ एक key बनाएं। + 2. [Failproof daemon को Cloud से कनेक्ट करें](/hi/start/setup#connect-a-machine-to-cloud) agent मशीन पर। + 3. एक instrumented सेशन चलाएं, फिर **Observe → Events** के तहत इसकी सटीक ID खोजें। + 4. **Observe → Sessions** पर जाएं, एक ही environment चुनें, और पुनर्निर्मित trace खोलें। - ![एक कस्टम Python एजेंट सेशन एक्सीक्यूशन ग्राफ और क्रमबद्ध इवेंट ट्रेस के रूप में पुनर्निर्मित।](/images/dashboard/session-detail.png) + ![एक कस्टम Python agent सेशन को एक execution graph और ordered event trace के रूप में पुनर्निर्मित किया गया।](/images/dashboard/session-detail.png) + `events:add` key को shell में पढ़ें। `read -s` इसे एक प्रॉम्प्ट पर लेता है जो echo नहीं करता, इसलिए यह कभी command में या shell history में दिखाई नहीं देता: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + फिर मशीन को सेट अप करें और जांचें कि यह कनेक्ट हुआ: + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -58,32 +64,32 @@ failproofai_sdk.configure( ) ``` -| तर्क | यह क्या करता है | +| Argument | यह क्या करता है | | --- | --- | -| `environment` | हर इवेंट पर लेबल — `production`, `staging`, `prod-eu`। डिफ़ॉल्ट `dev`। | -| `flush_interval` | पृष्ठभूमि थ्रेड कितनी बार डिस्क पर लिखता है, सेकंड में। डिफ़ॉल्ट `0.5`। | -| `base_dir` | कहाँ लिखें। डिफ़ॉल्ट डेमॉन का स्पूल है, जो आप चाहते हैं जब तक कि आप अन्यथा न जानते हों। | +| `environment` | हर event पर लेबल — `production`, `staging`, `prod-eu`। डिफ़ॉल्ट `dev` है। | +| `flush_interval` | बैकग्राउंड thread कितनी बार disk में लिखता है, सेकंड में। डिफ़ॉल्ट `0.5` है। | +| `base_dir` | कहाँ लिखना है। डिफ़ॉल्ट daemon का spool है, जो आप चाहते हैं जब तक आप अन्यथा न जानते हों। | -इसके बजाय वातावरण चर द्वारा सेट करें: +इसके बजाय environment variable द्वारा सेट करें: -| चर | यह क्या करता है | +| Variable | यह क्या करता है | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | कोड परिवर्तन के बिना `environment` सेट करता है, जब लेबल डिप्लॉयमेंट के बजाय ऐप से संबंधित हो। एक `configure()` तर्क इसे ओवरराइड करता है। | -| `FAILPROOFAI_HOME` | Failproof AI रूट को स्थानांतरित करता है जो स्पूल रखता है। | -| `FAILPROOFAI_SDK_STRICT` | `1` इंस्ट्रूमेंटेशन त्रुटियों को लॉग करने के बजाय बढ़ाता है। | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` एक फ्रेमवर्क-संगतता समस्या को चेतावनी और जारी रखने के बजाय बढ़ाता है। | +| `AGENTEYE_ENVIRONMENT` | कोड परिवर्तन के बिना `environment` सेट करता है, जब लेबल deployment के बजाय app से संबंधित हो। एक `configure()` argument इसे ओवरराइड करता है। | +| `FAILPROOFAI_HOME` | Failproof AI root को स्थानांतरित करता है जो spool रखता है। | +| `FAILPROOFAI_SDK_STRICT` | `1` instrumentation errors को log किए जाने की जगह raise करता है। | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` एक framework-compatibility समस्या को warn करने और जारी रखने की जगह raise करता है। | - **`environment` में कोई अल्पविराम नहीं।** Ingest उस फील्ड को कोमा पर विभाजित करता है अपने फ़िल्टर बनाने के लिए, और कोई भी इवेंट जिसमें एक हो स्किप करता है — इसलिए एक पूरा रन चुपचाप गायब हो जाता है। `prod,eu` नहीं, `prod-eu` लिखें। + **`environment` में कोई comma नहीं।** Ingest उस फील्ड को commas पर split करता है इसके filters बनाने के लिए, और किसी भी event को skip करता है जिसके लेबल में एक है — इसलिए एक पूरा run चुप चाप गायब हो जाता है। `prod,eu` नहीं, `prod-eu` लिखें। - `configure(environment="prod,eu")` बढ़ाता है इसलिए आप तुरंत पता लगा सकते हैं। `AGENTEYE_ENVIRONMENT` नहीं बढ़ा सकता — कोई आपको कॉल नहीं कर रहा — इसलिए यह एक बार चेतावनी देता है और `dev` पर फॉल बैक करता है। + `configure(environment="prod,eu")` raise करता है इसलिए आप तुरंत पता चलता है। `AGENTEYE_ENVIRONMENT` raise नहीं कर सकता — कोई आपको कॉल नहीं कर रहा — इसलिए यह एक बार warn करता है और `dev` पर वापस जाता है। -इवेंट्स मेमोरी में कतारबद्ध होते हैं और हर `flush_interval` सेकंड में पृष्ठभूमि में लिखे जाते हैं, इंटरप्रेटर एक्जिट पर एक अंतिम फ्लश के साथ। एक प्रक्रिया जो सीधे मार दी जाती है वह जो अभी तक नहीं लिखा गया था उसे खो देता है। +Events को memory में queue किया जाता है और हर `flush_interval` सेकंड में बैकग्राउंड में लिखा जाता है, interpreter exit पर एक final flush के साथ। एक प्रक्रिया जो सीधे kill की जाती है, वह कुछ खो देती है जो अभी तक लिखी नहीं गई थी। -## पहचान +## Identity -हर इवेंट एक सेशन और एक एजेंट से संबंधित है। **स्कोप दोनों को भरते हैं**, इसलिए आप शायद ही कभी उन्हें पास करते हैं: +हर event एक session और एक agent से संबंधित है। **Scopes दोनों को भरते हैं**, इसलिए आप शायद ही कभी उन्हें pass करते हैं: ```python with failproofai_sdk.session(): @@ -91,32 +97,32 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -`session_id` या `agent_id` को स्पष्ट रूप से पास करना अभी भी काम करता है और जीत जाता है। न तो बाउंड और न ही पास के साथ, कॉल `TypeError` बढ़ाता है बजाय एक इवेंट उत्सर्जित करने के जो Cloud चुपचाप छोड़ देता। +`session_id` या `agent_id` को explicitly pass करना अभी भी काम करता है और जीतता है। न bound और न ही passed के साथ, कॉल `TypeError` raise करता है, न कि एक event emit करता है जो Cloud quietly discard करेगा। - पहचान कॉन्टेक्स्ट चर पर चलती है। यह `asyncio` कार्यों को स्वचालित रूप से अनुसरण करता है, लेकिन **नई थ्रेड्स नहीं** — एक कार्यकर्ता को `failproofai_sdk.propagate()` में लपेटें या इसके इवेंट्स अनलगा रहते हैं। + Identity context variables पर सवार होती है। यह `asyncio` tasks को automatically follow करता है, लेकिन **नहीं** नए threads को — एक worker को `failproofai_sdk.propagate()` में wrap करें या इसके events unattached land करते हैं। -## इवेंट कैटलॉग +## Event कैटलॉग -पंद्रह मेथड्स। अधिकांश **जोड़े** में आते हैं — आप ओपनर को कॉल करते हैं, फिर क्लोजर को, और SDK ने अंतराल को समय दिया। +पंद्रह मेथड। अधिकांश **pairs** में आते हैं — आप opener को कॉल करते हैं, फिर closer को, और SDK gap को time करता है। -| | खोलता है | बंद करता है | +| | Opens | Closes | | --- | --- | --- | -| **एजेंट्स** | `agent_start` | `agent_end` | +| **Agents** | `agent_start` | `agent_end` | | | `agent_pause` | `agent_resume` | -| **मॉडल्स** | `model_request` | `model_response` | -| **टूल्स** | `tool_use` | `tool_result` | -| **हुक्स** | `hook_triggered` | `hook_completed` | -| **ह्यूमन्स** | `human_wait` | `human_input` | +| **Models** | `model_request` | `model_response` | +| **Tools** | `tool_use` | `tool_result` | +| **Hooks** | `hook_triggered` | `hook_completed` | +| **Humans** | `human_wait` | `human_input` | -तीन अलग खड़े हैं: `error`, `human_pause`, `human_interrupt`। +तीन standalone हैं: `error`, `human_pause`, `human_interrupt`। -हर मेथड भी `session_id` और `agent_id` लेता है, जो स्कोप आपके लिए भरते हैं। कुछ भी `None` के रूप में छोड़ा गया JSON `null` के रूप में भेजने के बजाय ड्रॉप किया जाता है, और हर मेथड `None` रिटर्न करता है। +हर मेथड `session_id` और `agent_id` भी लेता है, जो scopes आपके लिए भरते हैं। कुछ भी `None` के रूप में छोड़ा गया JSON `null` के रूप में भेजे जाने की जगह dropped है, और हर मेथड `None` return करता है। -| मेथड | आवश्यक | वैकल्पिक | +| Method | आवश्यक | Optional | | --- | --- | --- | | `agent_start` | — | `goal`, `parent_id` | | `agent_end` | — | `outcome`, `summary` | @@ -137,14 +143,14 @@ with failproofai_sdk.session(): - एक रन को विफल के रूप में चिह्नित करने के लिए, `outcome` निम्नलिखित में से एक होना चाहिए `failed`, `error`, `timeout` या `rejected`। कुछ भी अन्य — निकट-मिस `"failure"` सहित — एक सफलता के रूप में गिना जाता है। + एक run को failed के रूप में चिह्नित करने के लिए, `outcome` को `failed`, `error`, `timeout` या `rejected` में से एक होना चाहिए। कुछ भी और — near-miss `"failure"` सहित — एक success के रूप में counts करता है। -## जोड़ी और अवधि +## Pairing और duration -**एक नियम: क्लोजिंग इवेंट को अपने ओपनर के समान ID दें।** यही है जो उन्हें जोड़ता है, और यही है जो SDK को अंतराल को समय देता है। +**एक नियम: closing event को अपने opener के समान id दें।** वह क्या उन्हें pairs करता है, और क्या SDK को gap को time करने देता है। -| जोड़ी | मिलान किया गया | +| Pair | Matched on | | --- | --- | | `tool_use` → `tool_result` | `tool_call_id` | | `hook_triggered` → `hook_completed` | `hook_id` | @@ -152,46 +158,46 @@ with failproofai_sdk.session(): | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**स्वयं `duration_ms` पास न करें।** SDK इसे मापता है, और इसे पास करना `ValueError` बढ़ाता है। +**`duration_ms` को yourself pass न करें।** SDK इसे measure करता है, और इसे pass करना `ValueError` raise करता है। -एक अपवाद `model_response` है, जहां केवल आप वास्तविक प्रदाता विलंब जानते हैं। मिलीसेकंड की एक पूरी संख्या पास करें — एक फ्लोट बढ़ाता है, क्योंकि कॉलम एक 32-बिट पूर्णांक है और अन्यथा खाली हो जाएगा। +एक अपवाद `model_response` है, जहां केवल आप real provider latency को जानते हैं। milliseconds की एक पूरी संख्या pass करें — एक float raise करता है, क्योंकि column एक 32-bit integer है और अन्यथा empty land करेगी। - + -- **आईडीज को केवल प्रति प्रकार, प्रति सेशन अद्वितीय होने की आवश्यकता है।** एक टूल कॉल और एक हुक एक को साझा कर सकते हैं; एक साथ दो सेशन एक ही आईडीज को बिना टकराए पुन: उपयोग कर सकते हैं। -- **वे एक एजेंट को स्कोप नहीं किए जाते हैं।** एक जोड़ी जो एक एजेंट के तहत खोली जाती है और दूसरे के तहत बंद हो जाती है अभी भी मेल खाती है — जो बहु-एजेंट कोड में सामान्य स्थिति है। -- **`request_id` वैकल्पिक लेकिन अनुशंसित है।** इसके बिना, मॉडल इवेंट्स उस क्रम में जोड़े जाते हैं जिसमें वे आते हैं, इसलिए एक ही एजेंट में दो समवर्ती कॉल गलत जोड़ी कर सकते हैं। -- **एक जोड़ी जो प्रक्रियाओं में विभाजित है** Cloud में अभी भी मेल खाती है, लेकिन SDK इसे समय नहीं दे सकता — कुछ भी किसी भी प्रक्रिया में दोनों हिस्सों को नहीं देखा। -- **सबसे अधिक 10,000 ओपनर्स एक बार में क्लोजर का इंतजार करते हैं।** इससे पहले सबसे पुराने को छोड़ दिया जाता है, इसलिए एक रिसाव बिना बाध्य बढ़ नहीं सकता। +- **Ids केवल kind per, per session के लिए unique होना चाहिए।** एक tool call और एक hook एक share कर सकते हैं; दो sessions एक साथ चल सकते हैं एक ही ids को reuse कर सकते हैं बिना colliding के। +- **वे agent को scoped नहीं हैं।** एक pair एक agent के तहत open किया गया और दूसरे agent के तहत close किया गया अभी भी match करता है — जो multi-agent code में सामान्य case है। +- **`request_id` optional है लेकिन अनुशंसित है।** इसके बिना, model events उनके आने के क्रम में pair up करते हैं, इसलिए एक ही agent में दो concurrent calls mispair कर सकते हैं। +- **एक pair processes में split** अभी भी Cloud में match करता है, लेकिन SDK इसे time नहीं कर सकता — दोनों processes में कुछ भी दोनों halves नहीं देखा। +- **अधिकतम 10,000 openers एक बार में एक closer के लिए wait करते हैं।** उसके बाद oldest को drop किया जाता है, इसलिए एक leak बिना bound के grow नहीं कर सकता। -## आपकी अपनी फील्ड्स +## अपने स्वयं के फील्ड -कोई भी अतिरिक्त कीवर्ड जो आप पास करते हैं वह इवेंट के साथ संग्रहीत है: +कोई भी extra keyword जो आप pass करते हैं event के साथ stored है: ```python failproofai_sdk.event.tool_use( tool_name="search", tool_call_id="c1", - fw_tenant="acme", fw_region="eu-west-1", # आपकी अपनी + fw_tenant="acme", fw_region="eu-west-1", # आपके अपने ) ``` -JSON प्रकारों को बेहतर करें यदि आप बाद में उन्हें क्वेरी करना चाहते हैं। कुछ भी अन्य — एक UUID, एक datetime, एक `Decimal`, एक सेट, bytes, एक मॉडल ऑब्जेक्ट — एक स्ट्रिंग के रूप में संग्रहीत है। +यदि आप बाद में query करना चाहते हैं तो JSON types को prefer करें। कुछ भी और — एक UUID, एक datetime, एक `Decimal`, एक set, bytes, एक model object — एक string के रूप में stored है। - **अपने फील्ड नामों को प्रीफिक्स करें।** एक्सट्रास अंत में लागू होते हैं, इसलिए `model`, `tool_name` या `outcome` नाम की फील्ड चुपचाप असली को ओवरराइट करता है। फ्रेमवर्क एडेप्टर्स `fw_` का उपयोग करते हैं; वही करें और कुछ भी टकरा नहीं सकता। + **अपने फील्ड names को prefix करें।** Extras अंत में apply किए जाते हैं, इसलिए एक field `model`, `tool_name` या `outcome` को called करना silently real one को overwrite करता है। Framework adapters `fw_` उपयोग करते हैं; वही करें और कुछ भी collide नहीं कर सकता। - यही कारण है कि एक गलत वर्तनी वैकल्पिक फील्ड कभी त्रुटि नहीं करता — यह केवल एक नई कस्टम फील्ड बन जाता है। यदि एक मानक फील्ड Cloud में गायब है, तो पहले वर्तनी की जांच करें। + यह भी है क्यों एक misspelled optional field कभी errors नहीं करता — यह बस एक नया custom field बन जाता है। यदि एक standard field Cloud में missing है, तो पहले spelling check करें। -ये पाँच नाम आरक्षित हैं और सीधे अस्वीकार किए जाते हैं: `timestamp`, `session_id`, `agent_id`, `type`, `environment`। +ये पाँच names reserved हैं और सीधे rejected हैं: `timestamp`, `session_id`, `agent_id`, `type`, `environment`। -## डिलीवर करें और सत्यापित करें +## Deliver और verify करें - - **Observe → Events** में, पहले सत्यापित करें कि `agent_start` मौजूद है और `agent_end` अंत में मौजूद है। फिर **Observe → Sessions** खोलें और पुष्टि करें कि मॉडल, टूल, ह्यूमन, हुक, और त्रुटि इवेंट्स इच्छित क्रम में दिखाई देते हैं। सेशन ID को प्राथमिक समस्या निवारण कुंजी के रूप में उपयोग करें। + + **Observe → Events** में, पहले verify करें `agent_start` exists है और `agent_end` exists अंत में है। फिर **Observe → Sessions** खोलें और confirm करें model, tool, human, hook, और error events intended order में दिखाई देते हैं। Session ID को primary troubleshooting key के रूप में उपयोग करें। ```bash @@ -203,14 +209,14 @@ JSON प्रकारों को बेहतर करें यदि आ -यदि Cloud खाली है, तो `$FAILPROOFAI_HOME/custom-agents/events` का निरीक्षण करें, अन्यथा `~/.failproofai/custom-agents/events`। JSONL फाइलें SDK उत्सर्जन को साबित करती हैं; एक बढ़ता हुआ स्पूल डेमॉन कॉन्फ़िगरेशन या डिलीवरी की ओर इशारा करता है, जबकि एक खाली स्पूल इंस्ट्रूमेंटेशन या प्रक्रिया जीवनकाल की ओर इशारा करता है। +यदि Cloud खाली है, तो `$FAILPROOFAI_HOME/custom-agents/events` inspect करें, अन्यथा `~/.failproofai/custom-agents/events`। JSONL files SDK emission को prove करती हैं; एक growing spool daemon configuration या delivery को point करता है, जबकि एक empty spool instrumentation या process lifetime को point करता है। - स्पूल का निरीक्षण केवल तब करें जब डेमॉन बंद हो। जबकि यह चलता है, यह मिलीसेकंड के भीतर प्रत्येक बैच को एकत्र करता है और हटाता है, इसलिए एक निर्देशिका सूची कलेक्टर के साथ दौड़ती है और उत्सर्जित इवेंट्स की तुलना में बहुत कम इवेंट्स दिखाती है। + Spool को केवल तब inspect करें जब daemon बंद हो। जबकि यह चलता है, यह collects करता है और हर batch को milliseconds में delete करता है, इसलिए एक directory listing races करता है collector के साथ और emit किए गए events से far fewer दिखाता है। -## कस्टम रनटाइम में विफलताओं को रोकें +## कस्टम runtime में failures को prevent करें -असुरक्षित कार्रवाई, आवश्यक साक्ष्य, और इच्छित प्रतिक्रिया को परिभाषित करने के लिए ऑडिट निष्कर्षों और लिंक किए गए ट्रेस का उपयोग करें। एक कस्टम प्रवर्तन एकीकरण को निष्पादन से पहले कार्रवाई को उजागर करना चाहिए, इसके संरचित इनपुट को नीति इंजन में पास करना चाहिए, और परिणामी allow, instruct, या deny निर्णय लागू करना चाहिए। +Audit findings और linked traces का use करके unsafe action, required evidence, और intended response को define करें। एक custom enforcement integration को execution से पहले action को expose करना चाहिए, इसके structured input को policy engine में pass करना चाहिए, और resulting allow, instruct, या deny decision को apply करना चाहिए। -[Failproof AI से संपर्क करें](mailto:support@befailproof.ai) और हम आपके रनटाइम के मॉडल, टूल और जीवनचक्र सीमाओं को नीति हुक्स से मैप करने में मदद करेंगे, फिर एकीकरण को आपके साथ सत्यापित करेंगे। \ No newline at end of file +[Failproof AI से contact करें](mailto:support@befailproof.ai) और हम आपके runtime के model, tool और lifecycle boundaries को policy hooks से map करने में मदद करेंगे, फिर integration को आपके साथ validate करेंगे। \ No newline at end of file diff --git a/docs/hi/reference/evaluator-sdk.mdx b/docs/hi/reference/evaluator-sdk.mdx index aa533bf5..26bd5e13 100644 --- a/docs/hi/reference/evaluator-sdk.mdx +++ b/docs/hi/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "एक सेवा बनाएँ जो Failproof AI सेशन को समकालीन या असमकालीन रूप से स्कोर करती है।" +description: "अपने स्वयं के evaluation worker को चलाएं, LLM judges और अन्य किसी भी चीज़ के लिए जो hosted Python नहीं कर सकता।" icon: "gauge" --- -एक मूल्यांकनकर्ता एक पूर्ण एजेंट सेशन प्राप्त करता है और गुणवत्ता संकेत लौटाता है जिनकी आपको परवाह है: संख्यात्मक स्कोर, प्रत्येक स्कोर के लिए एक व्याख्या, और एक वैकल्पिक सारांश। Failproof AI इन परिणामों को ट्रेस के साथ संग्रहीत करता है और एजेंट और वातावरण के पार उन्हें चार्ट करता है। +Evaluator SDK आपके स्वयं के infrastructure पर evaluations चलाता है। आपका worker अपने evaluations को Failproof AI में register करता है, जैसे ही sessions समाप्त होते हैं उन्हें claim करता है, उन्हें score करता है, और परिणाम सबमिट करता है, सब कुछ outbound HTTPS पर: कुछ भी इसमें कनेक्ट नहीं होता। इसे उस चीज़ के लिए use करें जो [hosted Python](/hi/evaluations/write) नहीं कर सकता — LLM judges, model calls, packages, secrets, और network access। इसके परिणाम [evaluations page](/hi/sessions/evaluations) पर hosted ones के साथ दिखाई देते हैं, **customer** टैग के साथ। -## एक मूल्यांकनकर्ता सेट अप करें +यह `failproofai-sdk` में आता है, `failproofai_sdk.evaluator` के तहत; tracing SDK को import करने से यह load नहीं होता। - - - SDK और इसे चलाने के लिए उपयोग किए जाने वाले सर्वर को इंस्टॉल करें। - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - `evaluator.py` बनाएँ। यह उदाहरण जाँचता है कि क्या एक सेशन में कोई विफल टूल कॉल है। - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - एक साझा टोकन सेट करें, मूल्यांकनकर्ता शुरू करें, और पुष्टि करें कि इसका health endpoint प्रतिक्रिया देता है। - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - एक अन्य टर्मिनल में: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## मूल्यांकनकर्ता को Failproof AI से कनेक्ट करें - -1. मूल्यांकनकर्ता को एक HTTPS URL पर तैनात करें जो Failproof AI Cloud द्वारा पहुँचा जा सकता है। -2. `EVALUATOR_ENDPOINT` को उस URL के साथ कॉन्फ़िगर करें और `EVALUATOR_TOKEN` को मूल्यांकनकर्ता द्वारा उपयोग किए जाने वाले टोकन पर सेट करें। प्रबंधित Cloud के लिए, कनेक्शन कॉन्फ़िगर करने के लिए [support@befailproof.ai](mailto:support@befailproof.ai) से संपर्क करें। -3. एक मूल्यांकन चलाएँ और पुष्टि करें कि इसके स्कोर Failproof AI में दिखाई देते हैं। - - - - **Observe → Sessions** के तहत एक पूर्ण सेशन खोलें और यदि यह स्वचालित रूप से मूल्यांकन नहीं किया गया था तो **Run evaluation** चुनें। सेशन के **Evaluation** पैनल में स्थिति, स्कोर, तर्क और सारांश की समीक्षा करें। - - एजेंट या वातावरण के पार स्कोर की तुलना करने के लिए **Observe → Evaluations** का उपयोग करें। विलंबता, लागत, टोकन और अन्य संख्यात्मक माप के लिए **Observe → Metrics** का उपयोग करें। - - पुष्टि करने के लिए एक सेशन के साथ शुरुआत करें कि मूल्यांकनकर्ता ने उस विशिष्ट रन के लिए अपेक्षित स्कोर कुंजी और उपयोगी तर्क लौटाए हैं। - - ![एक सेशन विस्तार दृश्य जो इसके ट्रेस के बगल में मूल्यांकन स्कोर और तर्क दिखाता है।](/images/dashboard/session-detail.png) +```bash +pip install failproofai-sdk +``` - एक बार जब व्यक्तिगत परिणाम सही दिखें, समय के साथ और एजेंट या वातावरण के पार उन स्कोर की तुलना करने के लिए मूल्यांकन डैशबोर्ड का उपयोग करें। +## Evaluations लिखें - ![एक गुणवत्ता डैशबोर्ड जो समय के साथ मूल्यांकनकर्ता स्कोर चार्ट करता है।](/images/dashboard/dashboard-quality.png) +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - एक स्वस्थ चार्ट को स्थिर स्कोर नाम का उपयोग करना चाहिए; एक कुंजी को पुनः नाम देना एक अलग श्रृंखला बनाता है। - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - -एक self-hosted Cloud उदाहरण के लिए, जब तक `EVALUATOR_ENDPOINT` सर्वर प्रक्रिया पर सेट नहीं किया जाता तब तक स्वचालित मूल्यांकन अक्षम है। मूल्यांकनकर्ता पर्यावरण चर बदलने के बाद सर्वर को पुनः शुरू करें। +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` -सेवा `GET /health`, `GET /config`, `POST /evaluate`, और वैकल्पिक रूप से `GET /evaluate/{job_id}` को उजागर करती है। असमकालीन कार्य के लिए `JobPending` लौटाएँ और `@app.job_lookup` को पंजीकृत करें ताकि Failproof AI इसे पोल कर सके। +- `@app.eval(key, version=...)` एक evaluation को register करता है। key वह है जिसके तहत इसके परिणाम chart होते हैं; जब भी logic बदले तो version बदलें, और प्रत्येक result उस version को रखता है जिसने इसे produce किया। एक worker 100 तक evaluations hold कर सकता है। +- `result_kind` है `"score"` जब तक आप अन्यथा न कहें। एक `"metric"` या `"assertion"` evaluation के लिए, key के बाद एक `metrics` या `assertions` entry को नाम दें: वह entry इसका result है। +- `when` तय करता है कि क्या एक session लागू होता है। एक को skip करने के लिए `ConditionResult(False, "")` return करें, और reason record किया जाता है। +- एक evaluation एक plain function या `async` हो सकता है, और `timeout_seconds` इसे bound करता है। +- Payload keys — `tool_name`, `response`, और `content` ऊपर — जो कुछ भी आपके agents भेजते हैं, इसलिए उन्हें एक real session से पढ़ें। -जब एक टोकन कॉन्फ़िगर किया गया हो, तो health को छोड़कर सभी रूट को समान bearer token की आवश्यकता है जो Failproof AI `EVALUATOR_TOKEN` के रूप में भेजता है। +## Worker चलाएं -## SDK प्रकार +**Administration → Keys** के तहत बनाई गई एक key को `evaluations:run` permission के साथ `FAILPROOFAI_EVALUATOR_TOKEN` में रखें — इसे अपने secret store से set करें न कि इसे किसी command में type करें — और worker शुरू करें: -| प्रकार | फ़ील्ड | -| --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -## Decorators और routes +`__main__` block के बिना, `python -m failproofai_sdk.evaluator evaluator:app` वही करता है। -| Decorator | Route | आवश्यक | +| Variable | Default | Purpose | | --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | हाँ | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | `JobPending` लौटाते समय | -| `@app.config` | `GET /config` | नहीं | - -SDK मूल्यांकन request bodies को 25 MiB पर सीमित करता है। अज्ञात request फ़ील्ड को अनदेखा किया जाता है ताकि सेवाएँ event contract के विकास के साथ संगत रहें। +| `FAILPROOFAI_EVALUATOR_URL` | required | Failproof AI कहां है: Cloud के लिए `https://app.befailproof.ai`। HTTPS जब तक यह loopback की ओर न point करे | +| `FAILPROOFAI_EVALUATOR_TOKEN` | required | `evaluations:run` के साथ एक key | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | इस worker को नाम देता है | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | Sessions जिन्हें यह worker एक साथ score करता है | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Failproof AI के लिए प्रत्येक request के लिए timeout | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | रुकने वाला worker flight में runs के लिए कितने समय का इंतज़ार करता है | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | एक URL को plain HTTP की अनुमति दें जो loopback नहीं है — नीचे warning देखें | +| `FAILPROOFAI_EVALUATOR_MODULE` | none | `python -m failproofai_sdk.evaluator` के लिए `module:attribute` | + + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` सब कुछ cleartext में भेजता है। Worker प्रत्येक request पर एक `Authorization: Bearer` header के रूप में `FAILPROOFAI_EVALUATOR_TOKEN` ले जाता है, और transcripts जो वह fetch करता है वह sessions ही हैं — तो path पर कोई भी दोनों को reads करता है, और token जो वे read करते हैं वह evaluations चलाता है जब तक आप इसे rotate नहीं करते। इसे केवल एक isolated development network पर use करें। अन्य सभी जगह URL HTTPS होना चाहिए; loopback को कोई flag की ज़रूरत नहीं। + + +## Result types + +| Type | Fields | +| --- | --- | +| `Score` | `value` (0 से 1), `passed`, `unit` (default `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -## असमकालीन कार्य लौटाएँ +एक `EvalResult` कम से कम एक score, metric, या assertion ले जाता है, और अधिकतम 25, प्रत्येक एक unique key के तहत। -`JobPending` का उपयोग करें जब मूल्यांकन एक request के भीतर समाप्त नहीं हो सकता है। job ID Failproof AI के लिए अपारदर्शी है और परिणाम एकत्र किए जाने या सर्वर timeout समाप्त होने तक आपकी सेवा द्वारा resolvable रहना चाहिए। +## Session -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| Field या method | आपको देता है | +| --- | --- | +| `session_id`, `agent_id`, `environment` | Session की identity | +| `started_at`, `ended_at` | जब यह शुरू हुआ और समाप्त हुआ | +| `event_count`, `events` | पूर्ण, ordered transcript | +| `count(event_type)` | कितने events उस type के इसमें हैं | +| `events_of_type(event_type)` | वे events, order में | -Polling cadence इस क्रम में चुना जाता है: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs`, फिर सर्वर का `EVALUATOR_POLLING_INTERVAL_SECS`। मान 1 सेकंड और 1 घंटे के बीच fixed हैं। सर्वर की डिफ़ॉल्ट wall-clock polling cap एक घंटा है। +प्रत्येक event `id`, `ts`, `event_type`, और `payload` ले जाता है। -## Request और response फ़ील्ड +## Legacy evaluator -| फ़ील्ड | प्रकार | नोट्स | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | वर्तमान में `"1"`। | -| `session_id`, `agent_id`, `environment` | `str` | सेशन identity और वातावरण। | -| `started_at` | `datetime` | पहली event का timestamp। | -| `ended_at` | `datetime \| None` | जब सेशन ने एक end event emit किया तो मौजूद है। | -| `events` | `list[AgentEvent]` | पूर्ण क्रमबद्ध event stream। | -| `AgentEvent.id` | `int` | Backend event row identifier। | -| `AgentEvent.ts` | `datetime` | Event timestamp। | -| `AgentEvent.event_type` | `str` | Event family जैसे `tool_use`। | -| `AgentEvent.payload` | `dict[str, Any]` | संपूर्ण event payload। | -| `EvalResponse.scores` | `dict[str, float] \| None` | मूल्यांकन में charted संख्यात्मक आयाम। | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | Per-score व्याख्या; keys को `scores` को mirror करना चाहिए। | -| `EvalResponse.summary` | `str \| None` | समग्र मूल्यांकन narrative। | - -## Server operator सेटिंग्स - -स्वचालित मूल्यांकन deployment-wide है और जब `EVALUATOR_ENDPOINT` अनुपस्थित होता है तो अक्षम रहता है। - -| Variable | Default | उद्देश्य | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | unset | मूल्यांकनकर्ता सेवा का Base URL। | -| `EVALUATOR_TOKEN` | unset | Bearer token `Evaluator(token=...)` के साथ साझा किया जाता है। | -| `EVALUATOR_WORKERS` | `2` | समवर्ती dispatcher workers। | -| `EVALUATOR_CLAIM_BATCH` | `4` | Dispatcher pass प्रति दावा किए गए सेशन। | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Fallback async polling cadence। | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Per-request मूल्यांकनकर्ता timeout। | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | Terminal failure से पहले delivery attempts। | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | `/config` के लिए refresh cadence। | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | अधिकतम wall-clock async polling time। | - -सर्वर यह भी restrict कर सकता है कि कौन सी organizations deployment-global मूल्यांकनकर्ता का उपयोग करती हैं। endpoint, token, retry, और organization-gate परिवर्तनों को operator configuration के रूप में मानें और उन्हें बदलने के बाद सर्वर को restart या roll करें। - -## सुरक्षा और संचालन - -- जब traffic एक trusted network boundary को पार करता है तो मूल्यांकनकर्ता को HTTPS के पीछे रखें। -- एक non-empty bearer token कॉन्फ़िगर करें और इसे दोनों सेवाओं पर identical रखें। -- टोकन या request payloads से पूर्ण sensitive prompts को log न करें। -- समकालीन handlers को idempotent बनाएँ; retries एक request को दोहरा सकते हैं। -- Production में process memory के बाहर असमकालीन job state को persist करें। -- स्थिर स्कोर कुंजी लौटाएँ। एक कुंजी को पुनः नाम देना एक नई chart series बनाता है पुरानी को बदलने के बजाय। - -SDK structured lifecycle logs emit करता है जैसे `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected`, और handler exceptions। यह logging handlers कॉन्फ़िगर नहीं करता; host application की logging configuration का उपयोग करें। \ No newline at end of file +पहले का Evaluator SDK — एक HTTP service जिसे Failproof AI `EVALUATOR_ENDPOINT` पर called करता था, `/evaluate` का जवाब देता था और `JobPending` के through poll किया जाता था — retired है। इस worker पर नए evaluators build करें; एक self-hosted instance के operators जो एक legacy service चला रहे हैं वह transition के through इसे keep कर सकते हैं। \ No newline at end of file diff --git a/docs/hi/reference/failproof-cli.mdx b/docs/hi/reference/failproof-cli.mdx index 86346082..90275016 100644 --- a/docs/hi/reference/failproof-cli.mdx +++ b/docs/hi/reference/failproof-cli.mdx @@ -1,88 +1,106 @@ --- title: "Failproof AI CLI" -description: "हुक्स इंस्टॉल करें, स्थानीय नीतियों को प्रबंधित करें, क्लाउड से कनेक्ट करें, और स्थानीय डेमन को चलाएं।" +description: "हुक इंस्टॉल करें, स्थानीय नीतियों को प्रबंधित करें, Cloud को कनेक्ट करें, और स्थानीय डेमन को संचालित करें।" icon: "terminal" --- -`npm install -g failproofai` के साथ स्थानीय CLI इंस्टॉल करें। इसे बिना किसी आर्गुमेंट के चलाने के लिए स्थानीय नीति डैशबोर्ड खोलें। +`npm install -g failproofai` के साथ स्थानीय CLI को इंस्टॉल करें। इसे बिना किसी तर्क के चलाएं ताकि स्थानीय नीति डैशबोर्ड खुल जाए। -पैकेज के लिए Node.js 20.9 या नया संस्करण आवश्यक है। विकास और स्रोत इंस्टॉल के लिए Bun 1.3 या नया समर्थित है। `failproofai configure` और `failproofai setup` क्रमशः `failproofai config` के उपनाम हैं; `failproofai p` को `failproofai policies` के लिए उपनाम है। +पैकेज को Node.js 20.9 या नए संस्करण की आवश्यकता है। Bun 1.3 या नए संस्करण का विकास और स्रोत इंस्टॉल के लिए समर्थन किया जाता है। `failproofai configure` और `failproofai setup` , `failproofai config` के लिए उपनाम हैं। `failproofai policy` , `failproofai pack` और `failproofai p` सभी `failproofai policies` की वर्तनी हैं — पैक और एकल नीतियां एक विचार के लिए तीन कमांड थीं और अब एक हैं। पुरानी वर्तनी अभी भी काम करती है, दो अपवादों के साथ: `pack list ` अब `policies show ` है, और `pack build` अब `publish` है। -## एक मशीन सेटअप करें +## एक मशीन सेट अप करें + +CLI को इंस्टॉल करें, फिर मशीन की कुंजी को शेल में पढ़ें। `read -s` इसे एक संकेत पर लेता है जो गूंजता नहीं है, इसलिए यह कभी एक कमांड में दिखाई नहीं देता: ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +फिर मशीन को सेट अप करें और चुनें कि यह क्या लागू करता है: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` -स्थानीय नीति डैशबोर्ड खोलने के लिए बिना किसी आर्गुमेंट के `failproofai` चलाएं। +`failproofai config` पूरा सेटअप है: यह `failproofaid` सेवा को इंस्टॉल करता है (रूट एक बार, `sudo -n` के माध्यम से — कभी भी एक इंटरेक्टिव पासवर्ड प्रॉम्प्ट नहीं), हर एजेंट CLI में हुक डालता है जो वह पाता है, और जब एक कुंजी उपलब्ध हो तो Cloud से कनेक्ट करता है। टर्मिनल के बिना — CI, एक कंटेनर, एक एजेंट इसे चला रहा है — यह पूछने के बजाय लागू करता है, और यदि इसे जो करने के लिए कहा गया था वह नहीं हुआ तो 1 से बाहर निकलता है। + +यह **कोई भी** नीतियां नहीं चुनता है। वह दूसरी कमांड का काम है, और इसके बिना एक नई तरह से कॉन्फ़िगर की गई मशीन हमेशा चालू गार्ड को छोड़कर कुछ भी लागू नहीं करती है। + +`--token` पर पर्यावरण चर को प्राथमिकता दें: एक कमांड-लाइन तर्क बॉक्स पर हर उपयोगकर्ता द्वारा `ps` से पठनीय है। यह सब चर की रक्षा करता है — किसी भी कमांड में टाइप की गई कुंजी, `export` सहित, अभी भी शेल इतिहास में उतरती है, जिसीलिए इसे ऊपर `read -s` के साथ पढ़ा जाता है। CI में, इसे गुप्त स्टोर से सेट करें और शेल ट्रेसिंग (`set -x`) को बंद रखें, अन्यथा ट्रेस इसे प्रिंट करता है। + + + `--connect ` एक मशीन को नामांकित करता है जो **पहले से ही सेट अप है**। यह नामांकन सफल होने के तुरंत बाद लौटता है — यह डेमन को इंस्टॉल नहीं करता है और किसी भी हुक को नहीं डालता है। एक मशीन पर सादा `failproofai config` (या `failproofai config --token `) का उपयोग करें जो अभी तक सेट अप नहीं किया गया है, अन्यथा यह कुछ भी एकत्र और लागू न करते हुए जुड़ा हुआ दिखाई देगा। + + +स्थानीय नीति डैशबोर्ड खोलने के लिए `failproofai` को बिना किसी तर्क के चलाएं। | कमांड | परिणाम | | --- | --- | -| `failproofai config` | इंटरैक्टिव मशीन सेटअप चलाएं | -| `failproofai config --connect --token ` | क्लाउड इनजेशन और पॉलिसी डिलीवरी से कनेक्ट करें | +| `failproofai config` | मशीन को सेट अप करें: एजेंट, डेमन, और जब कुंजी मौजूद हो तो Cloud | +| `failproofai config --token ` | एक पास में सेट अप करें और कनेक्ट करें, कुछ भी पूछे बिना | +| `failproofai config --connect ` | एक मशीन को नामांकित करें जो **पहले से ही** सेट अप है — कोई डेमन नहीं, कोई हुक नहीं | | `failproofai config --status` | कनेक्शन, डेमन, डिलीवरी, और पॉज़ स्थिति दिखाएं | -| `failproofai policies` | बिल्ट-इन, कस्टम, कन्वेंशन, पैक, और क्लाउड द्वारा प्रबंधित नीतियों की सूची बनाएं | -| `failproofai policies --install` | हुक्स इंस्टॉल करें और नीतियों को सक्षम करें | -| `failproofai policy add ` | एक नीति सक्षम करें — एक बिल्ट-इन, या इंस्टॉल किए गए पैक से `:` | -| `failproofai policy remove ` | एक नीति अक्षम करें, समान नामकरण | -| `failproofai policies --uninstall` | नीतियों को अक्षम करें या हार्नेस हुक्स निकालें | -| `failproofai pack list` | इंस्टॉल किए गए नीति पैक और प्रत्येक की सभी नीतियों की सूची बनाएं | -| `failproofai pack add ` | GitHub रिलीज़ से एक नीति पैक इंस्टॉल करें; कोई टैग नहीं लेने से नवीनतम मिलता है और इसे पिन किया जाता है | -| `failproofai pack add --bundled` | इस पैकेज से बिल्ट-इन नीतियों को एक पैक के रूप में इंस्टॉल करें, बिना नेटवर्क के | -| `failproofai pack build ` | अपने स्वयं के पैक के लिए तीन रिलीज़ एसेट्स बनाएं | -| `failproofai pack remove ` | एक इंस्टॉल किए गए पैक को निष्क्रिय करें | -| `failproofai audit` | स्थानीय एजेंट इतिहास स्कैन करें और स्थानीय ऑडिट दृश्य खोलें | -| `failproofai audit --schedule [days] --email
` | आवर्ती स्थानीय स्कैन शेड्यूल करें और उनके निष्कर्ष ईमेल करें | -| `failproofai audit --status` | रिपोर्ट पता, अंतराल, और अगली शेड्यूल किए गए स्कैन को दिखाएं | -| `failproofai audit --no-schedule` | आवर्ती स्कैन को रोकें बिना ऑडिट इतिहास को हटाए | -| `failproofai harness list` | अतिरिक्त कैप्चर पथ सूचीबद्ध करें | +| `failproofai policies` | बिल्ट-इन, कस्टम, सम्मेलन, पैक, और Cloud-प्रबंधित नीतियां सूचीबद्ध करें | +| `failproofai policies --install` | अपने एजेंट CLIs में हुक डालें। अपने आप पर कोई नीति सक्षम नहीं करता है | +| `failproofai policies add ` | एक नीति सक्षम करें — एक बिल्ट-इन, या एक स्थापित पैक से `:` | +| `failproofai policies remove ` | एक नीति अक्षम करें, समान नामकरण | +| `failproofai policies --uninstall` | नीतियों को अक्षम करें या हार्नेस हुक हटाएं | +| `failproofai policies show /` | एक पैक क्या ले जाता है, इसके मैनिफेस्ट से पढ़ा जाता है, इसे लेने से पहले | +| `failproofai policies show / --releases` | हर संस्करण जो इसने प्रकाशित किया है, और कौन सा यहां है | +| `failproofai policies add ` | GitHub रिलीज़ से एक नीति पैक इंस्टॉल करें; कोई टैग नहीं नए को लेता है और इसे पिन करता है | +| `failproofai publish` | अपनी नीतियों को एक पैक के रूप में भेजें; `--init` एक को शुरू करने के लिए लिखता है | +| `failproofai policies remove ` | एक पैक अनइंस्टॉल करें | +| `failproofai audit` | स्थानीय एजेंट इतिहास को स्कैन करें और स्थानीय ऑडिट दृश्य खोलें | +| `failproofai audit --schedule [days] --email
` | आवर्ती स्थानीय स्कैन शेड्यूल करें और उनके निष्कर्षों को ईमेल करें | +| `failproofai audit --status` | रिपोर्ट पता, अंतराल, और अगली निर्धारित स्कैन दिखाएं | +| `failproofai audit --no-schedule` | आडिट इतिहास को हटाए बिना आवर्ती स्कैन बंद करें | +| `failproofai harness list` | अतिरिक्त कैप्चर पाथ सूचीबद्ध करें | | `failproofai flush --wait` | वर्तमान इवेंट स्पूल डिलीवर करें | -| `failproofai backfill --since 30d` | पहले से पास किए गए इतिहास को फिर से पढ़ें | -| `failproofai config --pause [duration]` | एक स्थानीय सेशन को डिफ़ॉल्ट रूप से 30 मिनट के लिए पॉज़ करें, 8 घंटे तक | -| `failproofai config --resume` | एक पॉज़ किए गए स्थानीय सेशन को फिर से शुरू करें; सभी पॉज़ को साफ़ करने के लिए `--all` जोड़ें | -| `failproofai update` | पैकेज माइग्रेशन को समाप्त करें और डेमन को अपडेट करें | -| `failproofai migrate --dry-run` | लंबित होम-लेआउट माइग्रेशन को प्रीव्यू या चलाएं | -| `failproofai uninstall` | डेमन को हटाने से पहले हुक्स को निकालें | -| `failproofai --version` | इंस्टॉल किए गए पैकेज संस्करण को प्रिंट करें | +| `failproofai backfill --since 30d` | पहले पारित इतिहास को फिर से पढ़ें | +| `failproofai config --pause [duration]` | एक स्थानीय सत्र को डिफ़ॉल्ट रूप से 30 मिनट के लिए पॉज़ करें, 8 घंटे तक | +| `failproofai config --resume` | एक पॉज़ किए गए स्थानीय सत्र को फिर से शुरू करें; सभी पॉज़ को साफ़ करने के लिए `--all` जोड़ें | +| `failproofai update` | पैकेज माइग्रेशन समाप्त करें और डेमन को अपडेट करें | +| `failproofai migrate --dry-run` | लंबित होम-लेआउट माइग्रेशन की पूर्वावलोकन या चलाएं | +| `failproofai uninstall` | पैकेज को हटाने से पहले हुक और डेमन हटाएं | +| `failproofai --version` | स्थापित पैकेज संस्करण प्रिंट करें | | `failproofai --help` | कमांड और वैश्विक उपयोग दिखाएं | -## कॉन्फ़िगरेशन फ़्लैग्स +## कॉन्फ़िगरेशन फ़्लैग | फ़्लैग | उपयोग | | --- | --- | -| `--connect --token ` | गैर-इंटरैक्टिव रूप से कनेक्ट करें | -| `--machine-id ` | स्थिर मशीन ID सेट करें | -| `--machine-label ` | डैशबोर्ड लेबल सेट या बदलें | -| `--no-transcripts` | ट्रांसक्रिप्ट सामग्री के बिना निर्णय भेजें | -| `--disconnect` | क्लाउड नीति पुल्स और इवेंट डिलीवरी को रोकें | +| `--token ` | गैर-इंटरेक्टिवली सेट अप और कनेक्ट करें; `FAILPROOFAI_CLOUD_TOKEN` से भी पढ़ें | +| `--url ` | `app.befailproof.ai` के अलावा कहीं और कनेक्ट करें; `FAILPROOFAI_CLOUD_URL` से भी पढ़ें | +| `--connect ` | केवल नामांकन, एक पहले से ही सेट अप की गई मशीन पर। डेमन और हर हुक को छोड़ देता है | +| `--machine-id ` | स्थिर मशीन आईडी सेट करें | +| `--machine-label ` | एक मशीन को तोड़ना जो **पहले से ही जुड़ी हुई है**। अपने आप पर यह कभी भी सेटअप नहीं चलाता है, इसलिए इसे `failproofai config` के बाद दें, सेटअप के दौरान नहीं | +| `--no-transcripts` | प्रतिलिपि सामग्री के बिना निर्णय भेजें | +| `--disconnect` | Cloud नीति पुल और ईवेंट डिलीवरी बंद करें | | `--status` | वर्तमान मशीन स्थिति दिखाएं | -| `--pause [duration]` | वर्तमान निर्देशिका में नवीनतम सेशन को पॉज़ करें; सेकंड, मिनट, या घंटे स्वीकार करता है और डिफ़ॉल्ट रूप से 30 मिनट है | -| `--resume` | एक मिलान पॉज़ को जल्दी समाप्त करें | -| `--session ` | पॉज़ या रिज़्यूम के लिए एक स्पष्ट सेशन को लक्ष्य करें | -| `--all` | `--resume` के साथ, सभी सक्रिय पॉज़ को समाप्त करें | +| `--pause [duration]` | वर्तमान निर्देशिका में नए सत्र को पॉज़ करें; सेकंड, मिनट, या घंटे स्वीकार करता है और डिफ़ॉल्ट रूप से 30 मिनट है | +| `--resume` | एक मिलती पॉज़ को जल्दी समाप्त करें | +| `--session ` | पॉज़ या रिज़्यूम के लिए एक स्पष्ट सत्र को लक्ष्य करें | +| `--all` | `--resume` के साथ, हर सक्रिय पॉज़ को समाप्त करें | -स्थानीय पॉज़ एक सेशन के लिए बिल्ट-इन, कस्टम, कन्वेंशन, और पैक नीतियों को निलंबित करते हैं। वे हमेशा समाप्त होते हैं और क्लाउड द्वारा प्रबंधित नीतियों को अक्षम नहीं करते। `block-failproofai-commands` — जो हमेशा चालू है और स्वयं को अक्षम या पॉज़ नहीं किया जा सकता — एक उपकरण एजेंट को इस एस्केप हैच का उपयोग करने से रोकता है। +स्थानीय पॉज़ एक सत्र के लिए बिल्ट-इन, कस्टम, सम्मेलन, और पैक नीतियों को निलंबित करते हैं। वे हमेशा समाप्त होते हैं और Cloud-प्रबंधित नीतियों को अक्षम नहीं करते हैं। `block-failproofai-commands` — जो हमेशा चालू है और अपने आप को अक्षम या पॉज़ नहीं किया जा सकता है — एक उपकरणित एजेंट को इस बचाव हैच को स्वयं उपयोग करने से रोकता है। -## नीति फ़्लैग्स +## नीति फ़्लैग | फ़्लैग | उपयोग | | --- | --- | -| `--install`, `-i` | नीतियों को सक्षम करें और हार्नेस हुक्स इंस्टॉल करें | -| `--uninstall`, `-u` | नीतियों को अक्षम करें या हुक्स को निकालें | +| `--install`, `-i` | हार्नेस हुक इंस्टॉल करें। इसके बाद के नाम उन नीतियों को सक्षम करते हैं; कोई नहीं होने पर, कोई नीति परिवर्तन नहीं | +| `--uninstall`, `-u` | नीतियों को अक्षम करें या हुक हटाएं | | `--cli ` | एक या अधिक समर्थित हार्नेस को लक्ष्य करें | | `--scope user\|project\|local\|all` | कॉन्फ़िगरेशन स्कोप चुनें; `all` अनइंस्टॉल के लिए है | -| `--beta` | बीटा नीतियों को शामिल करें | -| `--custom`, `-c ` | एक कस्टम नीति फ़ाइल को मान्य करें और लोड करें; दोहराए जा सकते हैं | +| `--beta` | बीटा नीतियां शामिल करें | +| `--custom`, `-c ` | एक कस्टम नीति फ़ाइल को मान्य करें और लोड करें; दोहराया जा सकता है | -## डिलीवरी और रखरखाव फ़्लैग्स +## डिलीवरी और रखरखाव फ़्लैग -| कमांड | फ़्लैग्स | +| कमांड | फ़्लैग | | --- | --- | | `backfill` | `--since <30d\|6m\|YYYY-MM-DD>`, `--dry-run` | | `flush` | `--wait`, `--timeout ` | @@ -90,9 +108,9 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` को `npm install -g failproofai@latest` के बाद चलाया जाना चाहिए; यह होम-लेआउट माइग्रेशन करता है, मिलान डेमन बाइनरी इंस्टॉल करता है, और सेवा को पुनः शुरू करता है। `--no-daemon` केवल लेआउट माइग्रेशन करता है। +`failproofai update` को `npm install -g failproofai@latest` के बाद चलाया जाना चाहिए; यह होम-लेआउट माइग्रेशन करता है, मेल खाने वाले डेमन बाइनरी को इंस्टॉल करता है, और सेवा को पुनरारंभ करता है। `--no-daemon` केवल लेआउट माइग्रेशन करता है। -## हार्नेस पथ +## हार्नेस पाथ ```text failproofai harness list [harness] @@ -102,9 +120,9 @@ failproofai harness remove-path समर्थित हार्नेस नाम `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, और `goose` हैं। -लेबल नामस्थान व्युत्पन्न एजेंट IDs जब दो रूट्स में एक ही प्रोजेक्ट की कॉपी हो। अतिव्यापी रूट्स और डुप्लिकेट लेबल को दोहरे संग्रह या कर्सर भ्रष्टाचार को रोकने के लिए अस्वीकार किया जाता है। अतिरिक्त-पथ कॉन्फ़िगरेशन डेमन पुनरारंभ के बिना पुनः लोड होता है। +लेबल व्युत्पन्न एजेंट आईडी को नेमस्पेस करते हैं जब दो रूट एक ही परियोजना की प्रतियां रखते हैं। ओवरलैपिंग रूट और डुप्लिकेट लेबल को डुप्लिकेट संग्रह या कर्सर भ्रष्टाचार को रोकने के लिए अस्वीकार कर दिया जाता है। अतिरिक्त-पाथ कॉन्फ़िगरेशन डेमन पुनरारंभ के बिना पुनः लोड करता है। -कंटेनर वातावरण फ़ाइल-कॉन्फ़िगर किए गए अतिरिक्त पथों को `FAILPROOFAI__EXTRA_PATHS` नामक एक अल्पविराम-अलग चर के साथ प्रतिस्थापित कर सकते हैं, उदाहरण के लिए: +कंटेनर वातावरण फ़ाइल-कॉन्फ़िगर किए गए अतिरिक्त पाथों को `FAILPROOFAI__EXTRA_PATHS` नाम के एक अल्पविराम-पृथक चर के साथ बदल सकते हैं, उदाहरण के लिए: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -116,24 +134,26 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl | चर | उपयोग | | --- | --- | +| `FAILPROOFAI_CLOUD_TOKEN` | Cloud कुंजी, `--token` की बजाय। इसे प्राथमिकता दें: एक तर्क `ps` से हर उपयोगकर्ता द्वारा पठनीय है। इसे `read -s` या CI गुप्त स्टोर से सेट करें, कभी भी कुंजी को एक कमांड में टाइप करके नहीं, जो किसी भी तरह से शेल इतिहास में आती है | +| `FAILPROOFAI_CLOUD_URL` | Cloud URL, `--url` की बजाय। वही चर जो डेमन पढ़ता है | | `FAILPROOFAI_HOME` | संपूर्ण `~/.failproofai` लेआउट को स्थानांतरित करें | -| `FAILPROOFAI_LOG_LEVEL` | स्थानीय लॉगिंग विस्तृतता सेट करें | +| `FAILPROOFAI_LOG_LEVEL` | स्थानीय लॉगिंग वर्बोसिटी सेट करें | | `FAILPROOFAI_HOOK_LOG_FILE` | हुक डायग्नोस्टिक्स को एक चयनित फ़ाइल में लिखें | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | इस प्रक्रिया के लिए अनाम टेलीमेट्री अक्षम करें | -| `FAILPROOFAI_NO_FIRST_RUN=1` | इंटरैक्टिव फ़र्स्ट-रन सेटअप को स्किप करें | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | सेटअप के बाद स्थानीय ऑडिट को स्किप करें | -| `FAILPROOFAI_LLM_BASE_URL` | LLM नीतियों द्वारा उपयोग किए गए OpenAI-संगत एंडपॉइंट को ओवरराइड करें | -| `FAILPROOFAI_LLM_API_KEY` | LLM नीतियों द्वारा उपयोग किए गए API कुंजी को सप्लाई करें | -| `FAILPROOFAI_LLM_MODEL` | LLM नीतियों द्वारा उपयोग किए गए मॉडल को चुनें | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | कस्टम नीति मॉड्यूल लोडिंग को बाध्य करें | -| `FAILPROOFAI_NO_DOWNLOAD=1` | पैक्स और डेमन बाइनरी को फेच करने से इनकार करें; जो इंस्टॉल है वह लागू रहता है | -| `FAILPROOFAI_PACK_BASE_URL` | `github.com` के बजाय मिरर से पैक्स को फेच करें | -| `FAILPROOFAI__EXTRA_PATHS` | एक हार्नेस के लिए कॉन्फ़िगर किए गए अतिरिक्त कैप्चर पथ को प्रतिस्थापित करें | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | इस प्रक्रिया के लिए अनाम टेलीमेट्री को अक्षम करें | +| `FAILPROOFAI_NO_FIRST_RUN=1` | इंटरेक्टिव पहली रन सेटअप को छोड़ें | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | पोस्ट-सेटअप स्थानीय ऑडिट को छोड़ें | +| `FAILPROOFAI_LLM_BASE_URL` | LLM नीतियों द्वारा उपयोग किए जाने वाले OpenAI-संगत अंतिम बिंदु को ओवरराइड करें | +| `FAILPROOFAI_LLM_API_KEY` | LLM नीतियों द्वारा उपयोग की जाने वाली API कुंजी की आपूर्ति करें | +| `FAILPROOFAI_LLM_MODEL` | LLM नीतियों द्वारा उपयोग किए गए मॉडल का चयन करें | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | कस्टम नीति मॉड्यूल लोडिंग को बांधें | +| `FAILPROOFAI_NO_DOWNLOAD=1` | पैक और डेमन बाइनरी प्राप्त करने से मना करें; जो स्थापित है वह लागू करना रखता है | +| `FAILPROOFAI_PACK_BASE_URL` | `github.com` की बजाय एक मिरर से पैक प्राप्त करें | +| `FAILPROOFAI__EXTRA_PATHS` | एक हार्नेस के लिए कॉन्फ़िगर किए गए अतिरिक्त कैप्चर पाथ को प्रतिस्थापित करें | | `NO_COLOR` | रंगीन टर्मिनल आउटपुट को अक्षम करें | -एजेंट-विशिष्ट होम चर जैसे `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, और `OPENCLAW_HOME` ओवरराइड करते हैं कि Failproof AI उस हार्नेस के लिए स्थानीय सेशन कहां खोजता है। +एजेंट-विशिष्ट होम चर जैसे `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, और `OPENCLAW_HOME` को ओवरराइड करते हैं कि Failproof AI उस हार्नेस के लिए स्थानीय सत्र की खोज कहां करता है। -## एक मशीन को सुरक्षित रूप से पॉज़ या निकालें +## एक मशीन को सुरक्षित रूप से पॉज़ या हटाएं ```bash failproofai config --pause @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -एक स्थानीय सेशन पॉज़ क्लाउड द्वारा प्रबंधित नीतियों को अक्षम नहीं करता। जब रोलआउट स्वयं समस्या है तो क्लाउड एन्फोर्समेंट वर्कफ़्लो के माध्यम से क्लाउड डिप्लॉयमेंट को पुनः स्थापित करें। +एक स्थानीय सत्र पॉज़ Cloud-प्रबंधित नीतियों को अक्षम नहीं करता है। जब रोलआउट ही समस्या हो तो Cloud विज्ञापन वर्कफ़्लो के माध्यम से Cloud तैनाती को पुनः स्थापित करें। -npm पैकेज को निकालने से पहले, इंस्टॉल किए गए हुक्स और डेमन को निकालें: +npm पैकेज को हटाने से पहले, स्थापित हुक और डेमन को हटाएं: ```bash failproofai uninstall --dry-run @@ -154,5 +174,5 @@ npm rm -g failproofai संस्करण-विशिष्ट विवरण के लिए `failproofai --help` चलाएं। - npm पैकेज को निकालने से पहले `failproofai uninstall` चलाएं; npm इंस्टॉल किए गए एजेंट हुक्स या डेमन सेवा को नहीं हटाता। + `npm rm -g failproofai` से पहले `failproofai uninstall` चलाएं; npm स्थापित एजेंट हुक या डेमन सेवा को नहीं हटाता है। \ No newline at end of file diff --git a/docs/hi/reference/harnesses.mdx b/docs/hi/reference/harnesses.mdx index b98640cb..7639945c 100644 --- a/docs/hi/reference/harnesses.mdx +++ b/docs/hi/reference/harnesses.mdx @@ -1,17 +1,17 @@ --- title: "एजेंट हार्नेस" -description: "सभी 12 समर्थित एजेंट हार्नेस में सत्र कैप्चर करें और नीतियां लागू करें।" +description: "सभी 12 समर्थित एजेंट हार्नेस में सत्र कैप्चर करें और नीतियों को लागू करें।" icon: "plug-zap" --- -एक हार्नेस वह है जिसके अंदर आपका एजेंट वास्तव में चलता है। Failproof AI उन्नीस को समर्थन करता है, दो वर्गों में: +एक हार्नेस वह है जिसके अंदर आपका एजेंट वास्तव में चलता है। Failproof AI इन्हें दो वर्गों में से बारह का समर्थन करता है: - **कोडिंग CLIs** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **चैट और सहायक गेटवे** (2) — Hermes (Slack, Telegram, cron), OpenClaw (स्व-होस्टेड सहायक) +- **चैट और असिस्टेंट गेटवे** (2) — Hermes (Slack, Telegram, cron), OpenClaw (self-hosted assistant) -एक ही नीतियां और एक ही सत्र इतिहास लागू होते हैं, चाहे एजेंट किसी भी हार्नेस में चले। एक एडेप्टर परत प्रत्येक हार्नेस के मूल ईवेंट नामों, टूल नामों और टूल-इनपुट फ़ील्ड को किसी भी नीति के चलने से पहले 29 कैनोनिकल ईवेंट में मैप करती है। +चाहे एजेंट किसी भी हार्नेस में चले, समान नीतियां और समान सत्र इतिहास लागू होता है। एक एडेप्टर परत प्रत्येक हार्नेस के मूल इवेंट नामों, टूल नामों, और टूल-इनपुट फील्ड को 29 विहित इवेंट पर मैप करती है, इससे पहले कि कोई नीति चले। -एक एजेंट जो बारह में से **किसी में भी नहीं** चलता है, [Python SDK](/hi/reference/custom-agents) के साथ सीधे इंस्ट्रुमेंट किया जाता है। यह एक अलग अनुबंध है, और स्पष्ट रूप से कहने लायक है: SDK ट्रेसिंग, सत्र, मूल्यांकन और ऑडिट प्रदान करता है — **यह स्वयं नीतियां लागू नहीं करता।** किसी असुरक्षित कार्रवाई को निष्पादन से पहले ब्लॉक करने के लिए आपके रनटाइम की टूल सीमा पर एक प्रवर्तन हुक की आवश्यकता है; [हमसे संपर्क करें](mailto:support@befailproof.ai) और हम इसे मैप करेंगे। +एक एजेंट जो बारहों में से **किसी में नहीं** चलता है, वह [Python SDK](/hi/reference/custom-agents) के साथ सीधे इंस्ट्रूमेंट किया जाता है। यह एक अलग अनुबंध है, और स्पष्ट रूप से बताने के लायक है: SDK ट्रेसिंग, सत्र, मूल्यांकन और ऑडिट प्रदान करता है — **यह अपने आप पर नीतियों को लागू नहीं करता।** निष्पादन से पहले एक असुरक्षित कार्रवाई को अवरुद्ध करने के लिए आपके रनटाइम के टूल सीमा पर एक प्रवर्तन हुक की आवश्यकता है; [हमसे संपर्क करें](mailto:support@befailproof.ai) और हम इसे मैप करेंगे। | हार्नेस | समर्थित हुक स्कोप | | --- | --- | @@ -20,61 +20,67 @@ icon: "plug-zap" | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -प्रत्येक इंटीग्रेशन नीतियों के चलने से पहले अपने मूल हुक ईवेंट नामों, टूल नामों और टूल-इनपुट फ़ील्ड को सामान्य करता है। एक नीति केवल उन ईवेंट पर कार्य कर सकती है जो हार्नेस उजागर करता है; सटीक हार्नेस और संस्करण पर अंत-मोड़ और निर्देश व्यवहार का परीक्षण करें जो आप तैनात करते हैं। +प्रत्येक इंटीग्रेशन नीतियों के चलने से पहले अपने मूल हुक इवेंट नामों, टूल नामों, और टूल-इनपुट फील्ड को सामान्य करता है। एक नीति केवल उन इवेंट पर कार्य कर सकती है जो हार्नेस उजागर करता है; बिल्कुल उसी हार्नेस और संस्करण पर टर्न के अंत और निर्देश व्यवहार का परीक्षण करें जो आप तैनात करते हैं। ## प्रवर्तन क्षमता -"ब्लॉक" का अर्थ है कि वर्तमान एडेप्टर की वापसी की गई राय को नामित हार्नेस द्वारा सेवन किया जाता है। पोस्ट-टूल ब्लॉकिंग मॉडल को दिखाया गया परिणाम बदल सकती है लेकिन ऐसी टूल साइड इफेक्ट को पूर्ववत नहीं कर सकती जो पहले से हो चुकी है। +"ब्लॉक" का मतलब है कि वर्तमान एडेप्टर की प्राप्त राय नामित हार्नेस द्वारा उपभोग की जाती है। पोस्ट-टूल ब्लॉकिंग मॉडल को दिखाया गया परिणाम प्रतिस्थापित कर सकता है लेकिन एक टूल साइड इफेक्ट को पूर्ववत नहीं कर सकता जो पहले से हो चुका है। -| हार्नेस | सत्यापित ब्लॉकिंग ईवेंट | केवल देखना या गैर-ब्लॉकिंग सावधानियां | +| हार्नेस | सत्यापित ब्लॉकिंग इवेंट | केवल-अवलोकन या गैर-ब्लॉकिंग चेतावनियां | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, और कई कार्य/कॉन्फ़िग ईवेंट | `PostToolUse`, सत्र जीवनचक्र, सूचनाएं, और पोस्ट-विफलता ईवेंट अवलोकनीय हैं। | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | पोस्ट-टूल ब्लॉकिंग निष्पादन के बाद परिणाम को बदलती है; सत्र-शुरुआत और कॉम्पैक्ट ईवेंट वर्तमान एडेप्टर में अवलोकनीय हैं। | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | पोस्ट-टूल ब्लॉकिंग निष्पादन के बाद परिणाम को बदलती है; सत्र और सूचना ईवेंट अवलोकनीय हैं। | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` और सत्र ईवेंट अवलोकनीय हैं। | -| OpenCode | `PreToolUse` | पोस्ट-टूल और जीवनचक्र ईवेंट अवलोकनीय हैं; वर्तमान स्टॉप हैंडलिंग एक सत्यापित द्वार के बजाय बाद के मोड़ के लिए मार्गदर्शन है। | -| Pi | `PreToolUse`, `UserPromptSubmit` | पोस्ट-टूल और जीवनचक्र ईवेंट अवलोकनीय हैं; स्टॉप मार्गदर्शन बाद के मोड़ के लिए लागू होता है। | -| Hermes | `PreToolUse` | पोस्ट-टूल, सत्र, और सबएजेंट-स्टॉप निर्णय द्वार नहीं हैं। | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | पोस्ट-टूल, सत्र, सबएजेंट-स्टॉप, और कॉम्पैक्शन ईवेंट अवलोकनीय हैं। | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | पोस्ट-टूल और सबएजेंट-स्टॉप निर्णय अवलोकनीय हैं। | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, सशर्त `PermissionRequest` | अनुमति हुक हर अनुमति मोड में नहीं चलते; पोस्ट-टूल और सत्र ईवेंट अवलोकनीय हैं। | -| Antigravity CLI | `PreToolUse`, `Stop` | उपयोगकर्ता-प्रॉम्प्ट और पोस्ट-टूल निर्णय अवलोकनीय हैं; प्रॉम्प्ट निर्देश अभी भी इंजेक्ट किए जा सकते हैं। | -| Goose | `PreToolUse` | उपयोगकर्ता-प्रॉम्प्ट, पोस्ट-टूल, और सत्र ईवेंट अवलोकनीय हैं। एक मूल ब्लॉकिंग स्टॉप हुक अपस्ट्रीम में मौजूद है लेकिन वर्तमान एडेप्टर द्वारा स्थापित नहीं है। | - -क्षमताएं संस्करण-संवेदनशील हैं। एजेंट CLI को अपग्रेड करने के बाद पुनः परीक्षण करें, विशेष रूप से जब कोई नीति प्रॉम्प्ट, स्टॉप, अनुमति, या पोस्ट-टूल व्यवहार पर निर्भर करती है, न कि सामान्य प्री-टूल गेट पर। +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, और कई टास्क/कॉन्फ़िग इवेंट | `PostToolUse`, सत्र जीवनचक्र, सूचनाएं, और पोस्ट-विफलता इवेंट अवलोकनात्मक हैं। | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | पोस्ट-टूल ब्लॉकिंग निष्पादन के बाद परिणाम को प्रतिस्थापित करता है; सत्र-शुरुआत और कॉम्पैक्ट इवेंट वर्तमान एडेप्टर में अवलोकनात्मक हैं। | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | पोस्ट-टूल ब्लॉकिंग निष्पादन के बाद परिणाम को प्रतिस्थापित करता है; सत्र और सूचना इवेंट अवलोकनात्मक हैं। | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` और सत्र इवेंट अवलोकनात्मक हैं। | +| OpenCode | `PreToolUse` | पोस्ट-टूल और जीवनचक्र इवेंट अवलोकनात्मक हैं; वर्तमान स्टॉप हैंडलिंग एक सत्यापित गेट के बजाय बाद की बारी के लिए मार्गदर्शन है। | +| Pi | `PreToolUse`, `UserPromptSubmit` | पोस्ट-टूल और जीवनचक्र इवेंट अवलोकनात्मक हैं; स्टॉप मार्गदर्शन बाद की बारी पर लागू होता है। | +| Hermes | `PreToolUse` | पोस्ट-टूल, सत्र, और subagent-stop राय गेट नहीं हैं। | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | पोस्ट-टूल, सत्र, subagent-stop, और कॉम्पैक्शन इवेंट अवलोकनात्मक हैं। | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | पोस्ट-टूल और subagent-stop राय अवलोकनात्मक हैं। | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, सशर्त `PermissionRequest` | अनुमति हुक हर अनुमति मोड में नहीं चलते; पोस्ट-टूल और सत्र इवेंट अवलोकनात्मक हैं। | +| Antigravity CLI | `PreToolUse`, `Stop` | उपयोगकर्ता-प्रॉम्प्ट और पोस्ट-टूल राय अवलोकनात्मक हैं; प्रॉम्प्ट निर्देश अभी भी इंजेक्ट किए जा सकते हैं। | +| Goose | `PreToolUse` | उपयोगकर्ता-प्रॉम्प्ट, पोस्ट-टूल, और सत्र इवेंट अवलोकनात्मक हैं। एक मूल ब्लॉकिंग स्टॉप हुक अपस्ट्रीम में मौजूद है लेकिन वर्तमान एडेप्टर द्वारा स्थापित नहीं है। | + +क्षमताएं संस्करण-संवेदनशील हैं। एक एजेंट CLI को अपग्रेड करने के बाद फिर से परीक्षण करें, विशेष रूप से जब कोई नीति सामान्य पूर्व-टूल गेट के बजाय प्रॉम्प्ट, स्टॉप, अनुमति, या पोस्ट-टूल व्यवहार पर निर्भर करती है। ## कैप्चर और नीति हुक स्थापित करें - - 1. **Administration → Keys** खोलें और `events:add` और `policies:pull` के साथ एक कुंजी बनाएं, मशीन या वातावरण के लिए नामित। + + 1. **Administration → Keys** खोलें और `events:add` और `policies:pull` के साथ एक कुंजी बनाएं, मशीन या परिवेश के लिए नामित करें। 2. लक्ष्य मशीन पर, स्थानीय CLI को प्रदर्शित कुंजी के साथ कनेक्ट करें और हार्नेस हुक स्थापित करें। - 3. एक नया एजेंट सत्र शुरू करें, फिर **Observe → Events** के तहत इसके हुक और सत्र ईवेंट की पुष्टि करें। - 4. समान समय विंडो के लिए **Observe → policy** खोलें और पुष्टि करें कि एक नीति निर्णय मशीन को जिम्मेदार है। + 3. एक नया एजेंट सत्र शुरू करें, फिर **Observe → Events** के अंतर्गत इसके हुक और सत्र इवेंट की पुष्टि करें। + 4. एक ही समय विंडो के लिए **Observe → policy** खोलें और पुष्टि करें कि एक नीति निर्णय मशीन को जिम्मेदार ठहराया गया है। - कनेक्शन एक मशीन कुंजी के साथ शुरू होता है। पुष्टि करें कि इसमें अपनी गुप्त को कॉपी करने से पहले इनजेशन और नीति-वितरण दोनों अनुमतियां शामिल हैं। + कनेक्शन एक मशीन कुंजी के साथ शुरू होता है। पुष्टि करें कि इसमें इसके गुप्त को कॉपी करने से पहले इनजेशन और नीति-वितरण दोनों अनुमतियां शामिल हैं। - ![नई API कुंजी ड्रॉअर जिसका उपयोग ईवेंट इनजेशन और नीति वितरण अनुमतियां प्रदान करने के लिए किया जाता है।](/images/dashboard/key-create.png) + ![नई API कुंजी दराज जिसे इवेंट इनजेशन और नीति वितरण अनुमतियां प्रदान करने के लिए उपयोग किया जाता है।](/images/dashboard/key-create.png) - हुक स्थापित करने के बाद, ईवेंट स्ट्रीम को आपके द्वारा कनेक्ट की गई मशीन और वातावरण से नई ईवेंट दिखाई देनी चाहिए। + हुक स्थापित करने के बाद, Events स्ट्रीम को आप जो मशीन और परिवेश कनेक्ट करते हैं उससे नए इवेंट दिखाने चाहिए। - ![लाइव ईवेंट स्ट्रीम का उपयोग नए स्थापित हार्नेस की रिपोर्टिंग की पुष्टि करने के लिए।](/images/dashboard/events-stream.png) + ![लाइव Events स्ट्रीम जिसका उपयोग एक नए स्थापित हार्नेस की रिपोर्टिंग की पुष्टि करने के लिए किया जाता है।](/images/dashboard/events-stream.png) - अंत में, सत्यापित करें कि नीति निर्णय एक ही मशीन को जिम्मेदार हैं। यह पुष्टि करता है कि हार्नेस ट्रेस ईवेंट के साथ-साथ नीति गतिविधि की भी रिपोर्टिंग कर रहा है। + अंत में, पुष्टि करें कि नीति निर्णय उसी मशीन को जिम्मेदार ठहराए गए हैं। यह पुष्टि करता है कि हार्नेस नीति गतिविधि के साथ-साथ ट्रेस इवेंट की रिपोर्ट कर रहा है। - ![नीति पृष्ठ का उपयोग नए से जुड़े हार्नेस से नीति निर्णयों को सत्यापित करने के लिए।](/images/dashboard/policy-observe.png) + ![नीति पृष्ठ जिसका उपयोग एक नए कनेक्ट किए गए हार्नेस से नीति निर्णयों को सत्यापित करने के लिए किया जाता है।](/images/dashboard/policy-observe.png) - सभी पता लगाए गए हार्नेस के लिए हुक स्थापित करें: + मशीन कुंजी को शेल में पढ़ें। `read -s` इसे एक प्रॉम्प्ट पर लेता है जो प्रतिध्वनि नहीं करता, इसलिए यह कभी एक कमांड में या शेल इतिहास में दिखाई नहीं देता: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - या नामित हार्नेस और कॉन्फ़िगरेशन स्कोप को लक्ष्य करें: + फिर मशीन को सेट करें — यह हर पता लगाए गए हार्नेस के लिए हुक तारों, daemon स्थापित करता है, और Cloud से कनेक्ट करता है: + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + सेटअप अपने आप पर कोई नीति सक्षम नहीं करता है, जो दूसरी कमांड के लिए है। + + या नामित हार्नेस और एक कॉन्फ़िगरेशन स्कोप को लक्ष्य करें: ```bash failproofai policies --install \ @@ -82,9 +88,9 @@ icon: "plug-zap" --scope user ``` - प्रोजेक्ट स्कोप हुक कॉन्फ़िगरेशन को एक रिपॉजिटरी के साथ रखता है। उपयोगकर्ता स्कोप रिपॉजिटरी में काम को कवर करता है। Claude Code स्थानीय स्कोप को भी समर्थन करता है; समर्थन हार्नेस के आधार पर भिन्न होता है और CLI असमर्थित संयोजनों को अस्वीकार करता है। + प्रोजेक्ट स्कोप हुक कॉन्फ़िगरेशन को एक रिपॉजिटरी के साथ रखता है। उपयोगकर्ता स्कोप रिपॉजिटरी में काम को कवर करता है। Claude Code स्थानीय स्कोप को भी समर्थन करता है; समर्थन हार्नेस के अनुसार भिन्न होता है और CLI असमर्थित संयोजनों को अस्वीकार करता है। - मशीन और इसकी ईवेंट सत्यापित करें: + मशीन और इसके इवेंट की पुष्टि करें: ```bash failproofai config --status @@ -94,16 +100,16 @@ icon: "plug-zap" -## एक गैर-डिफ़ॉल्ट सत्र पथ जोड़ें +## गैर-डिफ़ॉल्ट सत्र पाथ जोड़ें - - अतिरिक्त पथ मशीन पर पंजीकृत हैं, क्लाउड में नहीं। एक जोड़ने के बाद, **Observe → Sessions** खोलें, मशीन के वातावरण के लिए फ़िल्टर करें, और पुष्टि करें कि नए पथ से सत्र दिखाई दे रहे हैं। एक सत्र खोलें और ऑडिट में भरोसा करने से पहले एजेंट, हार्नेस, और ईवेंट टाइमस्टैम्प की जांच करें। + + अतिरिक्त पाथ मशीन पर पंजीकृत हैं, Cloud में नहीं। एक जोड़ने के बाद, **Observe → Sessions** खोलें, मशीन के परिवेश को फ़िल्टर करें, और पुष्टि करें कि नए पाथ से सत्र दिखाई देते हैं। एक ऑडिट में इस पर भरोसा करने से पहले एक सत्र खोलें और एजेंट, हार्नेस, और इवेंट टाइमस्टैम्प की जांच करें। - ![सत्र सूची अतिरिक्त कैप्चर पथ से डेटा प्राप्त करने वाले वातावरण के लिए फ़िल्ट की गई।](/images/dashboard/sessions-list.png) + ![अतिरिक्त कैप्चर पाथ से डेटा प्राप्त करने वाले परिवेश के लिए फ़िल्टर किए गए सत्र सूची।](/images/dashboard/sessions-list.png) - एक वैकल्पिक लेबल के साथ एक पथ जोड़ें, फिर कॉन्फ़िगर किए गए पथ की जांच करें: + एक वैकल्पिक लेबल के साथ एक पाथ जोड़ें, फिर कॉन्फ़िगर किए गए पाथ को निरीक्षण करें: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -112,10 +118,10 @@ icon: "plug-zap" failproofai backfill --since 7d ``` - `failproofai harness remove-path claude checkout` के साथ एक पथ हटाएं। + `failproofai harness remove-path claude checkout` के साथ एक पाथ हटाएं। - स्थापन के बाद एक नया सत्र चलाएं। रोलआउट का विस्तार करने से पहले लाइव ईवेंट स्ट्रीम और एक वास्तविक नीति निर्णय दोनों को सत्यापित करें। + स्थापन के बाद एक नया सत्र चलाएं। रोलआउट का विस्तार करने से पहले लाइव इवेंट स्ट्रीम और एक वास्तविक नीति निर्णय दोनों की पुष्टि करें। \ No newline at end of file diff --git a/docs/hi/reference/overview.mdx b/docs/hi/reference/overview.mdx index f8ac180e..b16576eb 100644 --- a/docs/hi/reference/overview.mdx +++ b/docs/hi/reference/overview.mdx @@ -1,81 +1,84 @@ --- title: "एकीकरण और संदर्भ" -description: "समर्थित एजेंट हार्नेस, SDK, CLI, और HTTP API को कनेक्ट करें।" +description: "समर्थित एजेंट हार्नेस, SDKs, CLIs, और HTTP API को कनेक्ट करें।" icon: "braces" --- -अपने एजेंट के पहले से चल रहे स्थान के सबसे करीब का एकीकरण चुनें। +अपने एजेंट के चलने वाले स्थान के सबसे करीब का एकीकरण चुनें। - समर्थित कोडिंग और स्वायत्त एजेंट CLI के लिए हुक इंस्टॉल करें। + समर्थित कोडिंग और स्वायत्त एजेंट CLIs के लिए हुक इंस्टॉल करें। - - LangGraph, CrewAI, LlamaIndex, Pydantic AI, या एक कस्टम एजेंट को साधन लगाएं। + + LangGraph, CrewAI, LlamaIndex, Pydantic AI, या कस्टम एजेंट को इंस्ट्रूमेंट करें। कॉन्फ़िगरेशन, इवेंट कैटलॉग, सहसंबंध नियम, और डिलीवरी। - - स्थानीय प्रोजेक्ट, सत्र, नीति गतिविधि, और ऑफलाइन ऑडिट की समीक्षा करें। + + लोकल प्रोजेक्ट्स, सेशन, पॉलिसी गतिविधि, और ऑफलाइन ऑडिट की समीक्षा करें। - स्थानीय कैप्चर, हुक, नीतियां, ऑडिट, डिलीवरी, और मशीन स्थिति को कॉन्फ़िगर करें। + लोकल कैप्चर, हुक, पॉलिसी, ऑडिट, डिलीवरी, और मशीन स्टेट कॉन्फ़िगर करें। - - क्लाउड सत्र, ऑडिट, समस्याएं, अलर्ट, कुंजियां, उपयोगकर्ता, और सेटिंग्स को क्वेरी और प्रशासित करें। + + क्लाउड सेशन, ऑडिट, इश्यू, अलर्ट, की, यूजर, और सेटिंग्स को क्वेरी और एडमिनिस्ट्रेट करें। - - एक FastAPI सेवा के साथ संपूर्ण या निष्क्रिय सत्रों को स्कोर करें। + + एक FastAPI सेवा के साथ पूर्ण या निष्क्रिय सेशन को स्कोर करें। - - वर्कफ़्लो-विशिष्ट allow, instruct, और deny निर्णयों को लिखें और परीक्षण करें। + + वर्कफ़्लो-विशिष्ट allow, instruct, और deny निर्णय लिखें और परीक्षण करें। - एक ग्राहक-प्रबंधित Kubernetes क्लस्टर पर क्लाउड नियंत्रण विमान को तैनात करें। + क्लाउड कंट्रोल प्लेन को ग्राहक-प्रबंधित Kubernetes क्लस्टर पर तैनात करें। -जनरेट किया गया [HTTP API संदर्भ](/hi/reference/http-api) सार्वजनिक `/v1` सतह को कवर करता है। हाथ से लिखे गए पृष्ठ उन वर्कफ़्लो की व्याख्या करते हैं जो कई एंडपॉइंट्स में फैली हुई हैं या उस सार्वजनिक सतह के बाहर प्रशासनिक इंटरफेस का उपयोग करती हैं। +जनरेट किया गया [HTTP API संदर्भ](/hi/reference/http-api) सार्वजनिक `/v1` सतह को कवर करता है। हस्तलिखित पृष्ठ वर्कफ़्लो की व्याख्या करते हैं जो कई एंडपॉइंट्स तक फैले हुए हैं या उस सार्वजनिक सतह के बाहर प्रशासनिक इंटरफेस का उपयोग करते हैं। ## एक एजेंट को कनेक्ट करें और डेटा सत्यापित करें - 1. **प्रशासन → कुंजियां** खोलें, `events:add` और `policies:pull` के साथ एक कुंजी बनाएं, और रहस्य को कॉपी करें। - 2. ऊपर दिए गए मेल खाने वाले पृष्ठ का उपयोग करके एकीकरण को कॉन्फ़िगर करें। - 3. **अवलोकन → इवेंट्स** खोलें यह पुष्टि करने के लिए कि इवेंट्स आ रहे हैं, फिर **अवलोकन → सत्र** खोलें यह पुष्टि करने के लिए कि वे पूर्ण रन बनाते हैं। - 4. एकीकरण के परिवेश को फ़िल्टर करें और ऑडिट के लिए आवश्यक मॉडल, टूल, त्रुटि, और नीति फ़ील्ड के लिए एक सत्र का निरीक्षण करें। + 1. **प्रशासन → कीज** खोलें, `events:add` और `policies:pull` के साथ एक कुंजी बनाएं, और सीक्रेट को कॉपी करें। + 2. ऊपर दिए गए मेल खाते वाले पृष्ठ का उपयोग करके एकीकरण कॉन्फ़िगर करें। + 3. **अवलोकन → इवेंट्स** खोलें यह पुष्टि करने के लिए कि इवेंट्स आते हैं, फिर **अवलोकन → सेशन** खोलें यह पुष्टि करने के लिए कि वे पूर्ण रन बनाते हैं। + 4. एकीकरण के पर्यावरण के लिए फ़िल्टर करें और ऑडिट्स के लिए आवश्यक मॉडल, टूल, एरर, और पॉलिसी फील्ड के लिए एक सेशन का निरीक्षण करें। - कुंजी ड्रॉअर से शुरू करें। चयनित अनुदान यह निर्धारित करते हैं कि क्या मशीन इवेंट्स भेज सकती है और क्लाउड-प्रबंधित नीतियां प्राप्त कर सकती है। + कुंजी ड्रॉअर से शुरू करें। चयनित अनुदान यह निर्धारित करते हैं कि क्या मशीन इवेंट्स भेज सकती है और क्लाउड-प्रबंधित पॉलिसीज प्राप्त कर सकती है। - ![नई API कुंजी ड्रॉअर का उपयोग इवेंट इंजेशन और नीति डिलीवरी अनुमतियां देने के लिए।](/images/dashboard/key-create.png) + ![नई API कुंजी ड्रॉअर जिसका उपयोग इवेंट इंजेशन और पॉलिसी डिलीवरी अनुमतियों को देने के लिए किया जाता है।](/images/dashboard/key-create.png) - एकीकरण को कनेक्ट करने के बाद, सत्र सूची का उपयोग यह पुष्टि करने के लिए करें कि इसके इवेंट्स अपेक्षित परिवेश में पूर्ण रन में समूहीकृत हो रहे हैं। + एकीकरण को कनेक्ट करने के बाद, सेशन सूची का उपयोग करके पुष्टि करें कि इसके इवेंट्स को अपेक्षित पर्यावरण में पूर्ण रन में समूहीकृत किया जा रहा है। - ![सत्र सूची का उपयोग यह सत्यापित करने के लिए कि एक नया कनेक्ट किया गया एकीकरण पूर्ण एजेंट रन की रिपोर्ट कर रहा है।](/images/dashboard/sessions-list.png) + ![सेशन सूची जिसका उपयोग यह सत्यापित करने के लिए किया जाता है कि एक नया कनेक्ट किया गया एकीकरण पूर्ण एजेंट रन रिपोर्ट कर रहा है।](/images/dashboard/sessions-list.png) - एकीकरण को पूर्ण मानने से पहले इन सत्रों में से एक को खोलें; ट्रेस में आपके ऑडिट को आवश्यक मॉडल, टूल, त्रुटि, और नीति सबूत होना चाहिए। + एकीकरण को पूर्ण मानने से पहले इनमें से एक सेशन खोलें; ट्रेस में आपके ऑडिट्स को आवश्यक मॉडल, टूल, एरर, और पॉलिसी साक्ष्य होना चाहिए। - एक मशीन कुंजी बनाएं, Failproof डेमॉन को कनेक्ट करें, और पहले सत्र को सत्यापित करें। + एक मशीन कुंजी बनाएं, फिर इसे शेल में प्रिंट करने वाली सीक्रेट को पढ़ें। `read -s` इसे एक प्रॉम्प्ट पर लेता है जो प्रतिध्वनित नहीं होता, इसलिए यह कभी भी किसी कमांड में या शेल हिस्ट्री में नहीं दिखाई देता: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Failproof डेमन को कनेक्ट करें और पहले सेशन को सत्यापित करें: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - जब कोई अन्य टूल परिणाम का उपभोग करेगा तो `fp --json sessions ...` का उपयोग करें। `--json`, `--org`, और `--base-url` जैसे वैश्विक फ़्लैग्स को कमांड से पहले आना चाहिए। + जब कोई अन्य टूल परिणाम का उपभोग करेगा तो `fp --json sessions ...` का उपयोग करें। `--json`, `--org`, और `--base-url` जैसे ग्लोबल फ्लैग को कमांड से पहले आना चाहिए। - स्थानीय कमांड के लिए [Failproof AI CLI संदर्भ](/hi/reference/failproof-cli) और `fp` कमांड के लिए [Failproof क्लाउड CLI संदर्भ](/hi/reference/cloud-cli#cli-commands) देखें। + लोकल कमांड के लिए [Failproof AI CLI संदर्भ](/hi/reference/failproof-cli) और `fp` कमांड के लिए [Failproof Cloud CLI संदर्भ](/hi/reference/cloud-cli#cli-commands) देखें। \ No newline at end of file diff --git a/docs/hi/reference/policy-sdk.mdx b/docs/hi/reference/policy-sdk.mdx index d1fb7b53..2399faba 100644 --- a/docs/hi/reference/policy-sdk.mdx +++ b/docs/hi/reference/policy-sdk.mdx @@ -1,35 +1,35 @@ --- -title: "कस्टम नीतियां" -description: "आपके एजेंट्स के लिए विशिष्ट विफलताओं के लिए जावास्क्रिप्ट या टाइपस्क्रिप्ट नीतियां बनाएं, परीक्षण करें और तैनात करें।" +title: "कस्टम policies" +description: "अपने agents के लिए विशिष्ट failures के लिए JavaScript या TypeScript policies को author, test, और deploy करें।" icon: "shield-plus" --- -कस्टम नीतियां आपके ट्रेस या ऑडिट से एक विफलता पैटर्न को एक निर्णय में बदल देती हैं जो एजेंट काम करते समय चलता है। एक नीति एक कार्रवाई की अनुमति दे सकती है, एजेंट को मार्गदर्शन दे सकती है, या कार्रवाई को अस्वीकार कर सकती है इससे पहले कि यह एक और घटना का कारण बने। +कस्टम policies आपके traces या audits से एक failure pattern को एक decision में बदल देते हैं जो agent के काम करते समय चलता है। एक policy एक action को allow कर सकता है, agent को guidance दे सकता है, या action को deny कर सकता है इससे पहले कि यह दूसरा incident का कारण बने। -एक कस्टम नीति का उपयोग करें जब व्यवहार आपके टूल्स, पाथ्स, कमांड्स, एनवायरनमेंट्स या ऑपरेटिंग नियमों पर निर्भर करता है। पहले [बिल्ट-इन नीति कैटलॉग](/hi/policies/builtin-catalog) देखें ताकि आप किसी मौजूदा नियंत्रण को फिर से न बनाएं। +एक कस्टम policy का उपयोग करें जब behavior आपके tools, paths, commands, environments, या operating rules पर निर्भर करता हो। पहले [Failproof AI policy pack](/hi/policies/packs) को check करें ताकि आप एक existing control को recreate न करें। -## कस्टम नीति बनाएं +## कस्टम policy को author करें - 1. **Admin → policy editor** पर जाएं, **New policy** चुनें, और विफलता का वर्णन करें जिसे आप रोकना चाहते हैं। - 2. नीति स्रोत जोड़ें, फिर संपादक में अपेक्षित मिलान और सुरक्षित गैर-मिलान परीक्षण करें। हर सत्यापन त्रुटि को हल करें। - 3. ड्राफ्ट को सहेजें और एक अपरिवर्तनीय संस्करण बनाने के लिए **Publish version** चुनें। - 4. **Admin → enforcement** पर जाएं, संस्करण को **observe** मोड में एक परीक्षण मशीन पर तैनात करें, और इसे लागू करने से पहले **Observe → policy** के तहत इसके निर्णयों को सत्यापित करें। + 1. **Admin → policy editor** पर जाएं, **New policy** चुनें, और failure को describe करें जिसे आप prevent करना चाहते हैं। + 2. policy source को add करें, फिर editor में expected matches और safe non-matches को test करें। हर validation error को resolve करें। + 3. draft को save करें और **Publish version** को चुनकर एक immutable version बनाएं। + 4. **Admin → enforcement** पर जाएं, version को एक test machine में **observe** mode में deploy करें, और **Observe → policy** के अंतर्गत इसके decisions को verify करें इससे पहले कि आप इसे enforce करें। - ![कस्टम नीति को बनाने और प्रकाशित करने के लिए उपयोग किया जाने वाला नीति संपादक।](/images/dashboard/policy-editor.png) + ![कस्टम policy को author और publish करने के लिए use की जाने वाली policy editor।](/images/dashboard/policy-editor.png) - 1. `.failproofai/policies/checkout-policies.ts` बनाएं। फाइल नाम `policies.js`, `policies.mjs`, या `policies.ts` में समाप्त होना चाहिए। - 2. `customPolicies.add()` के साथ एक या अधिक नीतियों को पंजीकृत करें। - 3. `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project` के साथ फाइल को सत्यापित और स्थापित करें। - 4. एक मेल खाने वाली कार्रवाई और एक सुरक्षित कार्रवाई को ट्रिगर करें। `failproofai policies` चलाएं, फिर **Observe → policy** के तहत जिम्मेदार निर्णयों का निरीक्षण करें। + 1. `.failproofai/policies/checkout-policies.ts` create करें। filename को `policies.js`, `policies.mjs`, या `policies.ts` में end होना चाहिए। + 2. एक या अधिक policies को `customPolicies.add()` के साथ register करें। + 3. file को `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project` के साथ validate और install करें। + 4. एक matching action और एक safe action को trigger करें। `failproofai policies` run करें, फिर **Observe → policy** के अंतर्गत attributed decisions को inspect करें। -## एक संकीर्ण नियम से शुरू करें +## एक narrow rule के साथ शुरू करें -यह नीति विनाशकारी Kubernetes कमांड्स को केवल तब ब्लॉक करती है जब कमांड उत्पादन को लक्षित करता है। उस सटीक विफलता मोड के बाहर सब कुछ `allow()` देता है। +यह policy destructive Kubernetes commands को केवल तभी block करता है जब command production को target करता है। उस exact failure mode के बाहर सब कुछ `allow()` return करता है। ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,23 +55,23 @@ customPolicies.add({ }); ``` -अच्छी नीतियां इतनी संकीर्ण होती हैं कि एक वाक्य में समझाई जा सकें। अवलोकन योग्य कार्रवाई से मेल खाएं—न कि इस इरादे से जो आप उम्मीद करते हैं कि एजेंट ने किया हो—और जैसे ही नियम लागू न हो तुरंत `allow()` देता है। +अच्छी policies उतनी narrow होती हैं कि एक sentence में explain की जा सकें। observable action को match करें—न कि वह intent जो आप उम्मीद करते हैं कि agent के पास हो—और `allow()` को return करें जैसे ही rule apply न हो। -## एक निर्णय चुनें +## एक decision चुनें -| हेल्पर | परिणाम | इसका उपयोग करें जब | +| Helper | Result | इसे use करें जब | | --- | --- | --- | -| `allow(reason?)` | ऑपरेशन जारी रहता है। | नीति लागू नहीं होती है या कार्रवाई सुरक्षित है। | -| `instruct(reason)` | ऑपरेशन जारी रहता है जहां कहीं हार्नेस इसका समर्थन करता है गाइडेंस के साथ। | आप एजेंट को एक बेहतर दृष्टिकोण की ओर निर्देशित करना चाहते हैं बिना किसी अपरिवर्तनीय को लागू किए। | -| `deny(reason)` | ऑपरेशन को ब्लॉक किया जाता है जब इवेंट और हार्नेस ब्लॉकिंग का समर्थन करते हैं। | कार्रवाई आगे नहीं बढ़नी चाहिए। | +| `allow(reason?)` | Operation continue होता है। | Policy apply नहीं होती है या action safe है। | +| `instruct(reason)` | Operation guidance के साथ continue होता है जहां harness इसे support करता है। | आप agent को बेहतर approach की ओर guide करना चाहते हैं बिना एक invariant को enforce किए। | +| `deny(reason)` | Operation blocked होता है जब event और harness blocking को support करते हैं। | Action को proceed नहीं करना चाहिए। | -एजेंट के लिए कारण लिखें जिसे ठीक करना होगा। समझाएं कि क्या पहचाना गया था और इसे इसके बजाय क्या करना चाहिए। +Agent के लिए reason लिखें जिसे recover करना होगा। Explain करें कि क्या detect किया गया और उसे इसके बजाय क्या करना चाहिए। - सुरक्षा सीमा के लिए `instruct()` का उपयोग न करें। गाइडेंस डिलीवरी एजेंट हार्नेस के अनुसार भिन्न होती है। `deny()` का उपयोग करें जब कार्रवाई को रोका जाना चाहिए। + एक safety boundary के लिए `instruct()` का use न करें। Guidance delivery agent harness के आधार पर अलग-अलग होती है। `deny()` का use करें जब action को prevent किया जाना चाहिए। -## नीति ऑब्जेक्ट +## Policy object ```ts customPolicies.add({ @@ -82,36 +82,36 @@ customPolicies.add({ }); ``` -| फील्ड | आवश्यक | विवरण | +| Field | Required | Description | | --- | --- | --- | -| `name` | हां | नीति के लिए स्थिर पहचानकर्ता। फाइलों में नाम अद्वितीय रखें। | -| `description` | नहीं | मानव-पठनीय उद्देश्य नीति सूचियों और निर्णयों में दिखाया जाता है। | -| `match.events` | नहीं | इवेंट प्रकार जो नीति को आमंत्रित करते हैं। `match` को छोड़ने से यह हर उपलब्ध इवेंट के लिए इसे आमंत्रित करता है। | -| `fn` | हां | सिंक्रोनस या एसिंक्रोनस फंक्शन जो `allow`, `instruct`, या `deny` परिणाम देता है। | +| `name` | Yes | Policy के लिए stable identifier। Names को files के across unique रखें। | +| `description` | No | Human-readable purpose जो policy listings और decisions में show होता है। | +| `match.events` | No | Event types जो policy को invoke करते हैं। `match` को omit करने से यह हर available event के लिए invoke होता है। | +| `fn` | Yes | Synchronous या asynchronous function जो एक `allow`, `instruct`, या `deny` result return करता है। | -`fn` के अंदर टूल्स को फिल्टर करें। `match.toolNames` सार्वजनिक कस्टम-नीति प्रकार का हिस्सा नहीं है। +Tools को `fn` के अंदर filter करें। `match.toolNames` public custom-policy type का हिस्सा नहीं है। -## नीति संदर्भ +## Policy context -हर नीति को एक `PolicyContext` प्राप्त होता है। +हर policy को एक `PolicyContext` मिलता है। -| फील्ड | प्रकार | इसमें क्या है | +| Field | Type | यह क्या contain करता है | | --- | --- | --- | -| `eventType` | `HookEventType` | वर्तमान में मूल्यांकन किए जा रहे सामान्यीकृत इवेंट। | -| `toolName` | `string \| undefined` | कैनोनिकल टूल नाम जैसे `Bash`, `Read`, `Write`, या `Edit`। | -| `toolInput` | `Record \| undefined` | वर्तमान टूल कॉल के लिए कैनोनिकल इनपुट। | -| `payload` | `Record` | संपूर्ण सामान्यीकृत इवेंट पेलोड। | -| `session` | `SessionMetadata \| undefined` | सेशन ID, कार्यशील निर्देशिका, ट्रांसक्रिप्ट पाथ, अनुमति मोड, और उपलब्ध होने पर हार्नेस मेटाडेटा। | -| `cli` | `string \| undefined` | स्रोत एजेंट हार्नेस, जैसे `claude`, `codex`, या `cursor`। | -| `params` | `Record` | बिल्ट-इन नीति पैरामीटर। कस्टम नीतियां वर्तमान में एक खाली ऑब्जेक्ट प्राप्त करती हैं। | +| `eventType` | `HookEventType` | Normalized event जो currently evaluate किया जा रहा है। | +| `toolName` | `string \| undefined` | Canonical tool name जैसे `Bash`, `Read`, `Write`, या `Edit`। | +| `toolInput` | `Record \| undefined` | Current tool call के लिए canonical input। | +| `payload` | `Record` | Complete normalized event payload। | +| `session` | `SessionMetadata \| undefined` | Session ID, working directory, transcript path, permission mode, और harness metadata जब available हो। | +| `cli` | `string \| undefined` | Source agent harness, जैसे `claude`, `codex`, या `cursor`। | +| `params` | `Record` | Built-in policy parameters। Custom policies currently एक empty object receive करते हैं। | -हर वैकल्पिक मान को वास्तव में वैकल्पिक मानें। एजेंट संस्करण और इवेंट प्रकार सभी समान फील्ड प्रदान नहीं करते हैं। +हर optional value को genuinely optional मानें। Agent versions और event types सभी fields provide नहीं करते हैं। -### सामान्य टूल इनपुट +### Common tool inputs -Failproof AI समर्थित हार्नेस में सामान्य टूल्स को सामान्यीकृत करता है ताकि एक नीति आमतौर पर एक इनपुट आकार का उपयोग कर सके। +Failproof AI common tools को supported harnesses के across normalize करता है ताकि एक policy आमतौर पर एक input shape use कर सके। -| टूल | सामान्य फील्ड्स | +| Tool | Common fields | | --- | --- | | `Bash` | `command` | | `Read` | `file_path` | @@ -119,34 +119,34 @@ Failproof AI समर्थित हार्नेस में सामा | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | -रक्षात्मक जबरदस्ती का उपयोग करें क्योंकि टूल इनपुट मान `unknown` के रूप में टाइप किए गए हैं: +Defensive coercion का use करें क्योंकि tool input values `unknown` के रूप में typed होती हैं: ```ts const command = String(ctx.toolInput?.command ?? ""); const filePath = String(ctx.toolInput?.file_path ?? ""); ``` -## इवेंट चुनें +## Event को choose करें -| इवेंट | कब चलता है | विशिष्ट उपयोग | +| Event | यह कब चलता है | Typical use | | --- | --- | --- | -| `PreToolUse` | एक टूल निष्पादित होने से पहले। | कमांड्स, लेखन, पढ़ने और बाहरी कार्रवाइयों को ब्लॉक या निर्देशित करें। | -| `PostToolUse` | एक टूल परिणाम देने के बाद। | एजेंट तक पहुंचने से पहले परिणामों का निरीक्षण करें। एक अस्वीकार पूरे परिणाम को ब्लॉक करता है; यह चयनित फील्ड्स को संशोधित नहीं करता है। | -| `PermissionRequest` | जब एजेंट अनुमति का अनुरोध करता है। | संगठन-विशिष्ट अनुमति नियम लागू करें। | -| `UserPromptSubmit` | जमा किए गए प्रॉम्प्ट से पहले जारी रहता है। | प्रतिबंधित निर्देशों को अस्वीकार करें या वर्कफ़्लो गाइडेंस जोड़ें। | -| `Stop` | जब एजेंट समाप्त करने का प्रयास करता है। | एक पहुंच योग्य समापन स्थिति की आवश्यकता करें, जैसे कि स्थानीय सत्यापन चरण। | -| `SubagentStop` | जब एक सबएजेंट समाप्त करने का प्रयास करता है। | अनुचर कार्य को गेट करें इससे पहले कि यह माता-पिता को लौटे। | -| `SessionStart` / `SessionEnd` | सेशन सीमाओं पर। | सेशन-स्तर की स्थिति रिकॉर्ड या जांच करें। | +| `PreToolUse` | एक tool execute होने से पहले। | Commands, writes, reads, और external actions को block या guide करें। | +| `PostToolUse` | एक tool return होने के बाद। | Agent तक पहुंचने से पहले results को inspect करें। एक deny पूरे result को block करता है; यह selected fields को redact नहीं करता है। | +| `PermissionRequest` | जब agent permission request करता है। | Organization-specific permission rules को apply करें। | +| `UserPromptSubmit` | एक submitted prompt continue होने से पहले। | Prohibited instructions को reject करें या workflow guidance add करें। | +| `Stop` | जब agent finish करने का attempt करता है। | एक reachable completion condition require करें, जैसे कि एक local verification step। | +| `SubagentStop` | जब एक subagent finish करने का attempt करता है। | Delegated work को gate करें इससे पहले कि यह parent को return हो। | +| `SessionStart` / `SessionEnd` | Session boundaries पर। | Session-level state को record या check करें। | -इवेंट उपलब्धता और ब्लॉकिंग व्यवहार एजेंट हार्नेस पर निर्भर करते हैं। एक मिश्रित बेड़े में किसी इवेंट पर निर्भर करने से पहले [Agent harnesses](/hi/reference/harnesses) देखें। +Event availability और blocking behavior agent harness पर depend करते हैं। Mixed fleet के across एक event पर rely करने से पहले [Agent harnesses](/hi/reference/harnesses) को देखें। - + `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch`, और `Setup`। -## सामान्य नीति पैटर्न बनाएं +## Common policy patterns को author करें -### संरक्षित पाथ्स में लेखन ब्लॉक करें +### Protected paths में writes को block करें ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -166,7 +166,7 @@ customPolicies.add({ }); ``` -### गैर-ब्लॉकिंग गाइडेंस दें +### Non-blocking guidance दें ```ts import { customPolicies, allow, instruct } from "failproofai"; @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### सेशन समापन को गेट करें +### Session completion को gate करें ```ts import { execFileSync } from "node:child_process"; @@ -215,30 +215,30 @@ customPolicies.add({ ``` - एक अस्वीकृत `Stop` इवेंट एजेंट को दोबारा कोशिश करने के लिए बना सकता है। केवल एक ऐसी शर्त पर गेट करें जिसे एजेंट वर्तमान वातावरण में संतुष्ट कर सके, और हर सबप्रोसेस या नेटवर्क कॉल को सीमित करें। + एक denied `Stop` event agent को retry करने के लिए कर सकता है। केवल एक ऐसी condition पर gate करें जिसे agent current environment में satisfy कर सकता है, और हर subprocess या network call को bound करें। -## नीति फाइलें लोड करें +## Policy files को load करें -### परंपरा फाइलें +### Convention files -परंपरा फाइलें स्वचालित रूप से लोड होती हैं: +Convention files automatically load होती हैं: ```text /.failproofai/policies/security-policies.ts ~/.failproofai/policies/personal-policies.mjs ``` -- प्रोजेक्ट और उपयोगकर्ता नीति निर्देशिकाएं दोनों लोड होती हैं। -- फाइलें प्रत्येक निर्देशिका के भीतर वर्णानुक्रमिक रूप से लोड होती हैं। -- एक फाइल `policies.js`, `policies.mjs`, या `policies.ts` में समाप्त होनी चाहिए। -- एक फाइल में एकाधिक `customPolicies.add()` कॉल समर्थित हैं। -- स्थानीय मॉड्यूल्स से सापेक्ष आयात समर्थित हैं। -- प्रोजेक्ट नीतियां प्रतिबद्ध की जा सकती हैं ताकि समान नियम रिपोजिटरी का अनुसरण करें। +- Project और user policy directories दोनों को load किया जाता है। +- Files प्रत्येक directory के अंदर alphabetically load होती हैं। +- एक file को `policies.js`, `policies.mjs`, या `policies.ts` में end होना चाहिए। +- एक file में multiple `customPolicies.add()` calls supported हैं। +- Local modules से relative imports supported हैं। +- Project policies को commit किया जा सकता है ताकि same rules repository को follow करें। -### स्पष्ट फाइलें +### Explicit files -स्पष्ट पाथ्स का उपयोग करें जब सत्यापन या कॉन्फ़िगरेशन को प्रवेश फाइल को सीधे नाम देना चाहिए: +Explicit paths का use करें जब validation या configuration को entry file को directly name करना चाहिए: ```bash failproofai policies --install \ @@ -247,11 +247,11 @@ failproofai policies --install \ --scope project ``` -स्पष्ट फाइलें पहले लोड होती हैं, इसके बाद प्रोजेक्ट परंपरा फाइलें और फिर उपयोगकर्ता परंपरा फाइलें। दोनों पाथ्स के माध्यम से खोजी गई फाइल एक बार लोड होती है। +Explicit files पहले load होती हैं, फिर project convention files और फिर user convention files। एक file जो दोनों paths के through discover होती है, एक बार load होती है। -## सत्यापित और परीक्षण करें +## Validate और test करें -सत्यापन मॉड्यूल को प्रोडक्शन लोडर के माध्यम से निष्पादित करता है और पुष्टि करता है कि यह कम से कम एक नीति को पंजीकृत करता है। +Validation module को production loader के through execute करता है और confirm करता है कि यह कम से कम एक policy को register करता है। ```bash failproofai policies --install \ @@ -260,44 +260,44 @@ failproofai policies --install \ failproofai policies ``` -सत्यापन लापता फाइलें, सिंटैक्स त्रुटियां, अनसुलझे आयात, शीर्ष-स्तरीय अपवाद और मॉड्यूल-लोड टाइमआउट को पकड़ता है। यह साबित नहीं करता है कि आपका मेल तर्क सही है। +Validation missing files, syntax errors, unresolved imports, top-level exceptions, और module-load timeouts को catch करता है। यह prove नहीं करता कि आपकी match logic सही है। -कम से कम ये मामले परीक्षण करें: +कम से कम इन cases को test करें: -- एक कार्रवाई जो मेल खानी चाहिए और इच्छित नीति कारण दे। -- एक पास-पास लेकिन सुरक्षित कार्रवाई जो `allow()` देनी चाहिए। -- लापता या विकृत टूल फील्ड्स। -- वैकल्पिक कमांड सिंटैक्स, पाथ्स, उद्धरण, मामला और व्हाइटस्पेस। -- एक अनुपलब्ध सबप्रोसेस या नेटवर्क निर्भरता। +- एक action जो match करना चाहिए और intended policy reason produce करना चाहिए। +- एक nearby लेकिन safe action जो `allow()` return करना चाहिए। +- Missing या malformed tool fields। +- Alternate command syntax, paths, quoting, casing, और whitespace। +- एक unavailable subprocess या network dependency। -परिणाम को **Observe → policy** के तहत आपकी कस्टम नीति के लिए जिम्मेदार ठहराएं। एक ब्लॉक किया गया परीक्षण पर्याप्त नहीं है यदि एक अलग बिल्ट-इन नीति ने निर्णय लिया। +Result को अपने custom policy के लिए **Observe → policy** के अंतर्गत attribute करें। एक blocked test sufficient नहीं है अगर एक different built-in policy ने decision बनाया है। -## रनटाइम व्यवहार +## Runtime behavior -- बिल्ट-इन नीतियां कस्टम नीतियों से पहले मूल्यांकन करती हैं। -- पहला `deny` आगे की नीति मूल्यांकन को बंद करता है। -- कई `instruct` परिणामों को जोड़ा जा सकता है जब कोई नीति इवेंट को अस्वीकार नहीं करती है। -- एक नीति फंक्शन के पास 10-सेकंड का निष्पादन समय सीमा है। -- एक फेंकी गई अपवाद या टाइमआउट को लॉग किया जाता है और `allow()` के रूप में माना जाता है। -- एक परंपरा फाइल जो लोड करने में विफल हो जाती है को छोड़ दिया जाता है; अन्य कस्टम फाइलें और बिल्ट-इन नीतियां जारी रहती हैं। -- शीर्ष-स्तरीय मॉड्यूल लोडिंग के पास भी 10-सेकंड की समय सीमा है। -- क्लाउड अवलोकन मोड नीति चलाता है लेकिन एक गैर-अनुमति निर्णय को इसे लागू किए बिना रिकॉर्ड करता है। +- Built-in policies custom policies से पहले evaluate होती हैं। +- पहला `deny` further policy evaluation को stop करता है। +- Multiple `instruct` results को combine किया जा सकता है जब कोई भी policy event को deny नहीं करता है। +- एक policy function के पास 10-second execution deadline होता है। +- एक thrown exception या timeout को log किया जाता है और `allow()` के रूप में treat किया जाता है। +- एक convention file जो load होने में fail होती है, को skip किया जाता है; अन्य custom files और built-in policies continue होती हैं। +- Top-level module loading के पास भी 10-second deadline होता है। +- Cloud observe mode policy को run करता है लेकिन एक non-allow decision को record करता है बिना इसे enforce किए। -नीति मॉड्यूल्स को नियतात्मक और तेज रखें। शीर्ष-स्तरीय नेटवर्क कॉल या सर्वर स्टार्टअप से बचें। `fn` के अंदर काम को सीमित करें, निर्भरता विफलताओं को पकड़ें, और जानबूझकर चुनें कि क्या वह विफलता ऑपरेशन को अनुमति दे या अस्वीकार करे। +Policy modules को deterministic और quick रखें। Top-level network calls या server startup से avoid करें। `fn` के अंदर work को bound करें, dependency failures को catch करें, और deliberately choose करें कि वह failure operation को allow या deny करना चाहिए। -## API निर्यात +## API exports -| निर्यात | उद्देश्य | +| Export | Purpose | | --- | --- | -| `customPolicies.add(policy)` | जब मॉड्यूल लोड होता है एक कस्टम नीति पंजीकृत करें। | -| `allow(reason?)` | ऑपरेशन की अनुमति दें। | -| `instruct(reason)` | ऑपरेशन की अनुमति दें और जहां समर्थित है गाइडेंस प्रदान करें। | -| `deny(reason)` | जहां समर्थित है ऑपरेशन को ब्लॉक करें। | -| `getCustomHooks()` | वर्तमान में मॉड्यूल रजिस्ट्री में पंजीकृत नीतियों को लौटाएं। | -| `clearCustomHooks()` | उस रजिस्ट्री को साफ करें, मुख्य रूप से परीक्षणों और लोडर्स के लिए। | +| `customPolicies.add(policy)` | Module load होने पर एक custom policy को register करें। | +| `allow(reason?)` | Operation को permit करें। | +| `instruct(reason)` | Operation को permit करें और जहां supported हो guidance provide करें। | +| `deny(reason)` | Operation को block करें जहां supported हो। | +| `getCustomHooks()` | Module registry में currently registered policies को return करें। | +| `clearCustomHooks()` | उस registry को clear करें, primarily tests और loaders के लिए। | -टाइपस्क्रिप्ट `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision`, और `PolicyFunction` को निर्यात करता है। +TypeScript `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision`, और `PolicyFunction` को export करता है। - - एक संस्करण प्रकाशित करें, इसे अवलोकन मोड में तैनात करें, निर्णयों को सत्यापित करें, और प्रवर्तन में जाएं। + + एक version को publish करें, इसे observe mode में deploy करें, decisions को verify करें, और enforcement की ओर move करें। \ No newline at end of file diff --git a/docs/hi/sessions/evaluations.mdx b/docs/hi/sessions/evaluations.mdx index 4eb1d3d3..40391db0 100644 --- a/docs/hi/sessions/evaluations.mdx +++ b/docs/hi/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "ऑनलाइन मूल्यांकन" -description: "गुणवत्ता, अनुपालन, लागत और विलंबता के लिए लाइव और पूर्ण सत्रों को स्कोर करें।" +title: "मूल्यांकन परिणाम पढ़ें" +description: "समय के साथ मूल्यांकन स्कोर चार्ट करें, agents और environments की तुलना करें, देखें कि एक session को कम स्कोर क्यों मिला, और assistant से पूछें।" icon: "gauge" --- -ऑनलाइन मूल्यांकन एजेंट सत्रों पर सामंजस्यपूर्ण निर्णय लागू करते हैं। उन संकेतों के लिए इनका उपयोग करें जिन्हें केवल ऑडिट के दौरान जांच करने के बजाय लगातार मापा जाना चाहिए। +हर मूल्यांकन के परिणाम, चाहे hosted हों या आपके स्वयं के worker से, एक ही जगहों पर आते हैं। -## मूल्यांकन गुणवत्ता की समीक्षा करें +## समय के साथ स्कोर की तुलना करें - 1. **Observe → Evaluations** पर जाएं। - 2. एक श्रृंखला जोड़ें और एजेंट, पर्यावरण, मूल्यांकन स्कोर, सांख्यिकी और वक्र चुनें। - 3. पर्यावरण, एजेंट या स्कोर कुंजियों की तुलना करने के लिए श्रृंखला जोड़ें। - 4. मिलान करने वाले सत्रों को खोलने या फ़िल्ट किए गए दृश्य को साझा करने के लिए एक परिणाम चुनें। विलंबता, टोकन, लागत और अन्य परिमाण मानों के लिए **Observe → Metrics** का उपयोग करें। + **Observe → evaluations** पर जाएँ। - ![गुणवत्ता डैशबोर्ड जो समय के साथ औसत मूल्यांकन स्कोर और प्रवृत्तियां दिखाता है।](/images/dashboard/dashboard-quality.png) + - **Recent runs** प्रत्येक मूल्यांकन को सूचीबद्ध करता है जैसे ही वह आता है: चाहे वह एक hosted (**managed**) या आपके स्वयं के (**customer**) evaluator से आया हो, agent और session, मूल्यांकन और इसका संस्करण, इसकी स्थिति, और इसका स्कोर या metrics। + - **Score over time** वह प्लॉट करता है जो आप चाहते हैं। **add series** चुनें और एक agent, एक environment, एक मूल्यांकन, और एक statistic चुनें: avg, min, max, p50, p75, p90, p95, p99, stddev, या mode। प्रत्येक series एक लाइन है; इसे अपना स्वयं का **curve** दें ताकि इसे अलग चार्ट पर खींचा जा सके। - प्रति-स्कोर तर्क का निरीक्षण करने के लिए ड्रिल-डाउन से एक सत्र खोलें: + ![मूल्यांकन पृष्ठ: customer टैग किए गए हाल के रन, 0.5 और 0.8 पर संदर्भ लाइनों के साथ एक स्कोर समय के साथ चार्ट, और सभी agents और environments में finished_clean को average करने वाली एक series।](/images/dashboard/evaluations-chart.png) - ![एक सत्र विस्तार दृश्य जो पूर्ण ट्रेस के बगल में मूल्यांकन स्कोर और तर्क दिखाता है।](/images/dashboard/session-detail.png) + एक समय सीमा और एक bin आकार सभी series पर लागू होता है। एक बेहतरीन bin एक घटना खोजता है; एक मोटा आकार एक प्रवृत्ति दिखाता है, और आप जो spikes ढूंढ रहे हैं उन्हें छिपा सकता है। एक bucket जहां कुछ भी स्कोर नहीं किया गया था लाइन में एक gap है, कभी zero नहीं, और संदर्भ लाइनें 0.5 और 0.8 को चिह्नित करती हैं। + + दृश्य के हर भाग URL में रहता है: **share** इसे कॉपी करता है, और जो कोई भी इसे खोलता है वह बिल्कुल वह तुलना देखता है जो आपने बनाई है। ```bash @@ -28,25 +28,29 @@ icon: "gauge" fp evals --score helpfulness:0.8.. --since 7d ``` - स्वचालन के लिए `evals` से पहले वैश्विक `--json` जोड़ें, उदाहरण के लिए `fp --json evals --aggregate --env production`। + स्वचालन के लिए `evals` से पहले global `--json` जोड़ें, उदाहरण के लिए `fp --json evals --aggregate --env production`। -एक मूल्यांकनकर्ता सत्र पहचान, पर्यावरण, समय मुहर और क्रमबद्ध घटनाएं प्राप्त करता है। यह वैकल्पिक तर्क और सारांश के साथ संख्यात्मक स्कोर कुंजियां लौटा सकता है। दीर्घकालीन मूल्यांकनकर्ता एक लंबित कार्य लौटा सकते हैं और बाद में सर्वेक्षण किए जा सकते हैं। +एक ही मूल्यांकन के लिए **avg** और **p90** को प्लॉट करें यह देखने के लिए कि क्या एक अच्छा औसत एक खराब tail को छिपा रहा है, या दो agents के लिए एक ही मूल्यांकन, या production और staging के लिए, उन्हें एक अक्ष पर तुलना करने के लिए। Costs, latencies, और token counts, जिनमें units होते हैं, **Observe → metrics** के तहत चार्ट होते हैं, एक chart प्रति unit। + +## देखें कि एक session को कम स्कोर क्यों मिला + +**Observe → sessions** से एक session खोलें; grid प्रत्येक session के स्कोर को ले जाता है और score range के आधार पर filter करता है। session का right rail मूल्यांकन सारांश के साथ शुरू होता है, फिर प्रत्येक स्कोर के लिए एक bar के साथ evaluator का reasoning इसके नीचे होता है। + +![एक session detail view जो पूर्ण trace के बगल में मूल्यांकन स्कोर और reasoning दिखाता है।](/images/dashboard/session-detail.png) + +## Assistant से पूछें + +सादे अंग्रेजी में मूल्यांकन डेटा के बारे में पूछें: "मुझे हाल के कुछ मूल्यांकनों के बारे में बताएं", या कौन से agents के स्कोर में गिरावट आ रही है। [assistant](/hi/sessions/assistant) परिणामों को पढ़ता और विश्लेषण करता है और tables के साथ उत्तर देता है जिन पर आप follow up कर सकते हैं, और एक सार्थक प्रश्न एक [query](/hi/sessions/queries) या एक [dashboard](/hi/sessions/dashboards) बन सकता है। -## अच्छे मूल्यांकन लक्ष्य +![मूल्यांकन पृष्ठ assistant के बगल में, जो "मुझे हाल के कुछ मूल्यांकनों के बारे में बताएं" का उत्तर totals, statuses, और scores की एक सारांश के साथ देता है।](/images/dashboard/evaluations-assistant.png) -- कार्य पूर्णता या शुद्धता -- आधारहीनता और मतिभ्रम जोखिम -- उपकरण चयन और उपकरण दक्षता -- नीति या प्रक्रिया अनुपालन -- लागत और विलंबता बजट -- आवश्यक मानव एस्केलेशन +## देखें और कार्य करें -## स्कोर से प्रतिक्रिया तक +- **Dashboards**, **Analyze → dashboards** के तहत, आप जिन स्कोर को feature करते हैं उन्हें trend करते हैं, प्रत्येक agent और environment के लिए, पूरे संगठन के लिए। -प्रवृत्तियों को ट्रैक करने के लिए डैशबोर्ड में स्कोर दिखाएं। थ्रेसहोल्ड या यौगिक शर्तों के लिए सतर्कताएं बनाएं। जब कोई स्कोर किसी जनसंख्या के पार गिरता है, तो जांच करने के लिए ऑडिट चलाएं; जब कारण एक दोहराई जाने वाली कार्रवाई है, तो एक नीति तैनात करें। + ![एक quality dashboard जो औसत मूल्यांकन स्कोर और समय के साथ trends दिखाता है।](/images/dashboard/dashboard-quality.png) - - Python मूल्यांकनकर्ता SDK के साथ सिंक्रोनस या असिंक्रोनस मूल्यांकन लागू करें। - \ No newline at end of file +- **Alerts** आपको सूचित करता है जब एक स्कोर एक threshold को पार करता है। [alerts](/hi/audits/alerts) देखें। +- जब एक स्कोर कई sessions में गिरता है, [एक audit चलाएँ](/hi/audits/run) यह पता लगाने के लिए कि क्यों; जब कारण एक repeatable action है, [एक policy लिखें](/hi/policies/editor)। \ No newline at end of file diff --git a/docs/hi/start/integrations/custom-agents.mdx b/docs/hi/start/integrations/custom-agents.mdx index e7b8f675..52b1fcc4 100644 --- a/docs/hi/start/integrations/custom-agents.mdx +++ b/docs/hi/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "कस्टम एजेंट" sidebarTitle: "कस्टम एजेंट" -description: "अपने द्वारा लिखे गए एजेंट या ऐसे फ्रेमवर्क को इंस्ट्रूमेंट करें जिसके लिए कोई एडाप्टर नहीं है।" +description: "एक एजेंट को इंस्ट्रूमेंट करें जिसे आपने स्वयं लिखा है, या एक फ्रेमवर्क जिसके लिए कोई एडेप्टर नहीं है।" icon: "code" --- -एजेंट जो आपने अपने आप लिखा हो, या कोई ऐसा फ्रेमवर्क जिसके लिए Failproof AI के पास एडाप्टर नहीं है। इंस्ट्रूमेंट करने के लिए कुछ नहीं है: आप ही इवेंट्स को एमिट करते हैं। +एक एजेंट के लिए जिसे आपने स्वयं लिखा है, या एक फ्रेमवर्क जिसके लिए Failproof AI के पास कोई एडेप्टर नहीं है। इंस्ट्रूमेंट करने के लिए कुछ नहीं है: आप ईवेंट उत्सर्जित करते हैं। -यह वही API है जिसे चारों फ्रेमवर्क एडाप्टर अंदर से कॉल करते हैं। वे इसके ऊपर ट्रांसलेशन टेबल हैं। +यह वही API है जिसे चारों फ्रेमवर्क एडेप्टर अंदर से कॉल करते हैं। वे इसके ऊपर अनुवाद तालिकाएं हैं। ## इंस्टॉल करें @@ -15,7 +15,7 @@ icon: "code" pip install failproofai-sdk ``` -कोई एक्सट्रास नहीं, और कोई डिपेंडेंसीज नहीं। +कोई अतिरिक्त नहीं, और कोई निर्भरता नहीं। ## इंस्ट्रूमेंट करें @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # एक रन t.output = search(q) # एक टूल कॉल ``` -इसे ऊपर से नीचे पढ़ें और यह कहता है कि इसका क्या मतलब है: +इसे ऊपर से नीचे पढ़ें और यह कहता है कि इसका मतलब क्या है: -| इसमें रखें | यह कहने के लिए | +| इसे लपेटें | कहने के लिए | | --- | --- | -| `session()` | ये इवेंट्स एक ही रन से संबंधित हैं | -| `agent()` | कोई काम कर रहा है — इसे एक नाम दें जिसे आप किसी लिस्ट में पहचान सकें | -| `tool_call()` | यह एक टूल है, और इसने यह वापस किया | +| `session()` | ये ईवेंट एक ही रन से संबंधित हैं | +| `agent()` | कुछ काम कर रहा है — इसे एक नाम दें जिसे आप सूची में पहचान सकें | +| `tool_call()` | यह एक टूल है, और यहां यह क्या लौटाया है | -और हर एक वास्तव में क्या एमिट करता है: +और प्रत्येक वास्तव में क्या उत्सर्जित करता है: -| स्कोप | एमिट करता है | उद्देश्य | +| स्कोप | उत्सर्जन | उद्देश्य | | --- | --- | --- | -| `session()` | कुछ नहीं | एक सेशन आईडी को बांधता है, एक रन को ग्रुप करता है | +| `session()` | कुछ नहीं | एक सेशन id बांधता है, एक रन को समूहीकृत करता है | | `agent()` | `agent_start`, `agent_end` | काम की एक यूनिट को ब्रैकेट करता है | | `tool_call()` | `tool_use`, `tool_result` | एक टूल को ब्रैकेट करता है और इसे मापता है | -इसके अंदर कुछ भी `session_id` और `agent_id` को छोड़ सकता है। स्कोप्स कॉन्टेक्स्ट वेरिएबल्स पर आइडेंटिटी को बांधते हैं और हर इवेंट कॉल इसे वापस पढ़ता है, इसलिए आप कभी आईडीज को अपने फंक्शन्स के माध्यम से थ्रेड नहीं करते। +अंदर सब कुछ `session_id` और `agent_id` को छोड़ सकता है। स्कोप संदर्भ चर पर पहचान बांधते हैं और हर ईवेंट कॉल इसे वापस पढ़ता है, इसलिए आप अपने फ़ंक्शन के माध्यम से कभी id का धागा नहीं डालते। -तीनों `with` के साथ-साथ `async with` के तहत भी काम करते हैं। +तीनों `async with` और `with` दोनों के तहत काम करते हैं। -एजेंट्स को नेस्ट करना ट्री बनाता है। `parent_id` और डेप्थ को स्टैक से कंप्यूट किया जाता है: +एजेंट को नेस्ट करने से पेड़ बनता है। `parent_id` और गहराई को स्टैक से गणना की जाती है: ```python with failproofai_sdk.session(): @@ -61,44 +61,44 @@ with failproofai_sdk.session(): ## एक स्कोप कैसे बंद होता है -`agent()` आपके लिए एक्सेप्शन्स को हैंडल करता है: +`agent()` आपके लिए अपवाद संभालता है: -| क्या हुआ | इवेंट्स | परिणाम | +| क्या हुआ | ईवेंट | परिणाम | | --- | --- | --- | | कुछ नहीं उठा | `agent_end` | `success` | | `Exception` | `error`, फिर `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, फिर `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | केवल `agent_end` | `cancelled` | -एरर को `agent_end` से पहले एमिट किया जाता है, क्योंकि डैशबोर्ड `agent_end` पर स्पैन को बंद करता है और इसके बाद कुछ भी कुछ नहीं के लिए एट्रिब्यूट किया जाता है। कैंसलेशन एक विफलता नहीं है, इसलिए कैंसल किए गए रन एरर्स सर्फेस को प्रदूषित नहीं करते। एक्सेप्शन को हमेशा फिर से उठाया जाता है: एक स्कोप कभी निगल नहीं जाता। +त्रुटि `agent_end` से पहले उत्सर्जित होती है, क्योंकि डैशबोर्ड `agent_end` पर स्पान को बंद करता है और इसके बाद कुछ भी कुछ भी में जिम्मेदार नहीं है। एक रद्दीकरण एक विफलता नहीं है, इसलिए रद्द किए गए रन त्रुटि सतह को प्रदूषित नहीं करते। अपवाद हमेशा फिर से उठाया जाता है: एक स्कोप कभी निगल नहीं लेता। -## इवेंट मेथड्स +## ईवेंट विधियां -छः परिवारों में पंद्रह मेथड्स। अधिकांश जोड़े में आते हैं — आप ओपनर को एमिट करते हैं, फिर क्लोजर को, और SDK उनके बीच के स्पैन को मापता है। +छह परिवारों में पंद्रह विधियां। अधिकतर जोड़े में आते हैं — आप ओपनर उत्सर्जित करते हैं, फिर क्लोजर, और SDK उनके बीच का स्पान मापता है। -| परिवार | खोलता है | बंद करता है | स्टैंडअलोन | +| परिवार | खुलता है | बंद होता है | स्टैंडअलोन | | --- | --- | --- | --- | -| **एजेंट्स** | `agent_start` | `agent_end` | — | +| **एजेंट** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | -| **मॉडल्स** | `model_request` | `model_response` | — | -| **टूल्स** | `tool_use` | `tool_result` | — | -| **हुक्स** | `hook_triggered` | `hook_completed` | — | -| **ह्यूमन्स** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **मॉडल** | `model_request` | `model_response` | — | +| **टूल** | `tool_use` | `tool_result` | — | +| **हुक** | `hook_triggered` | `hook_completed` | — | +| **मनुष्य** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | | **विफलताएं** | — | — | `error` | - स्कोप्स को प्राथमिकता दें — `agent()` और `tool_call()` — जहां कहीं वे फिट हों। वे क्लोजिंग इवेंट को गारंटी देते हैं भले ही बॉडी उठे। इन मेथड्स को सीधे तब तक के लिए रीच करें जब तक आपके कंट्रोल फ्लो नेस्ट न हों, जैसे किसी हेल्पर के अंदर एक मॉडल कॉल। + स्कोप को प्राथमिकता दें — `agent()` और `tool_call()` — जहां वे फिट हों। वे बंद होने वाली ईवेंट की गारंटी देते हैं यहां तक कि जब बॉडी उठे। इन विधियों को सीधे तब पकड़ें जब आपका नियंत्रण प्रवाह नेस्ट न हो, जैसे कि एक हेल्पर के अंदर एक मॉडल कॉल। -```python एजेंट्स +```python एजेंट failproofai_sdk.event.agent_start(agent_id="planner", goal="find the cheapest flight") failproofai_sdk.event.agent_end(agent_id="planner", outcome="success", summary="...") failproofai_sdk.event.agent_pause(pause_id="p1", reason="awaiting approval") failproofai_sdk.event.agent_resume(pause_id="p1") ``` -```python मॉडल्स +```python मॉडल failproofai_sdk.event.model_request( model="gpt-4o-mini", messages=[{"role": "user", "content": "..."}], @@ -114,17 +114,17 @@ failproofai_sdk.event.model_response( ) ``` -```python टूल्स +```python टूल failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1", input={"q": "..."}) failproofai_sdk.event.tool_result(tool_name="search", tool_call_id="c1", output="...") ``` -```python हुक्स +```python हुक failproofai_sdk.event.hook_triggered(hook_name="retrieve", hook_id="h1", trigger_event="node") failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome="success") ``` -```python ह्यूमन्स +```python मनुष्य failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **दोनों ह्यूमन परिवार विपरीत दिशाओं में इशारा करते हैं।** + **दो मानव परिवार विपरीत दिशा में इंगित करते हैं।** - | मेथड्स | मतलब | + | विधियां | अर्थ | | --- | --- | - | `human_wait` / `human_input` | **एजेंट ने किसी व्यक्ति से पूछा** — एक अनुमोदन गेट, एक स्पष्टीकरण प्रश्न | - | `human_pause` / `human_interrupt` | **किसी व्यक्ति ने एजेंट पर काम किया** — एक स्टॉप बटन, एक ऑपरेटर पॉज़ | + | `human_wait` / `human_input` | **एजेंट ने एक व्यक्ति से पूछा** — एक अनुमोदन गेट, एक स्पष्ट प्रश्न | + | `human_pause` / `human_interrupt` | **किसी व्यक्ति ने एजेंट पर कार्य किया** — एक स्टॉप बटन, एक ऑपरेटर पॉज़ | - कोई भी फ्रेमवर्क दूसरी जोड़ी को सिग्नल नहीं करता, इसलिए यह हमेशा आपका है। + कोई फ्रेमवर्क दूसरी जोड़ी का संकेत नहीं देता, इसलिए यह हमेशा आपकी है कि उत्सर्जन करें। - **जब मॉडल कॉल्स एक साथ चलते हैं तो `request_id` पास करें।** इसके बिना, रिक्वेस्ट्स और रिस्पांसेस प्रति एजेंट एरिवल ऑर्डर में जोड़े जाते हैं — और एक साथ कॉल्स मिस्पेयर होते हैं, हर रिस्पांस को गलत रिक्वेस्ट से जोड़ते हैं। + **जब मॉडल कॉल समवर्ती रूप से चलते हैं तो `request_id` पास करें।** इसके बिना, अनुरोध और प्रतिक्रियाएं प्रति एजेंट आगमन क्रम में जोड़ी होती हैं — और समवर्ती कॉल गलत जोड़ी बनाते हैं, प्रत्येक प्रतिक्रिया को गलत अनुरोध से जोड़ते हैं। ## उदाहरण -OpenAI API के खिलाफ एक टूल-कॉलिंग लूप, कोई एजेंट फ्रेमवर्क के बिना: +OpenAI API के विरुद्ध एक टूल-कॉलिंग लूप, कोई एजेंट फ्रेमवर्क के बिना: ```python import json @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # bounded; an unbounded agent loop is its own bug + for _ in range(4): # सीमाबद्ध; एक असीमित एजेंट लूप इसका अपना बग है message = turn(messages) if not message.tool_calls: break @@ -204,34 +204,34 @@ with failproofai_sdk.session(): }) ``` -यह छः इवेंट टाइप्स को प्रोड्यूस करता है जो एक एडाप्टर आपको देगा। संपूर्ण रनेबल वर्जन, टूल डेफिनिशन्स के साथ, SDK रिपॉजिटरी में `docs/manual/examples/` के तहत शिप होता है। +यह छह ईवेंट प्रकार का उत्पादन करता है जो एक एडेप्टर आपको देगा। पूर्ण चलने योग्य संस्करण, टूल परिभाषाओं के साथ, SDK रिपोजिटरी में `docs/manual/examples/` के तहत शिप होता है। ## थ्रेड्स और async -कॉन्टेक्स्ट वेरिएबल्स asyncio टास्क्स में स्वचालित रूप से प्रोपेगेट होते हैं। वे नए थ्रेड्स में प्रोपेगेट नहीं होते, क्योंकि एक थ्रेड खाली कॉन्टेक्स्ट के साथ शुरू होता है। +संदर्भ चर asyncio कार्यों में स्वचालित रूप से प्रसारित होते हैं। वे नए थ्रेड में प्रसारित नहीं होते, क्योंकि एक थ्रेड एक खाली संदर्भ के साथ शुरू होता है। ```python -# asyncio: कुछ नहीं करना है +# asyncio: कुछ भी नहीं करना है async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads: कॉलेबल को रैप करें +# थ्रेड्स: कॉलेबल को लपेटें pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -`propagate()` के बिना, वर्कर की इवेंट्स एक `TypeError` को उठाती हैं जो फिक्स को नाम देता है उसके बजाय कि कोई सेशन न हो। यह जानबूझकर है: कोई इवेंट कोई सेशन के साथ इनजेस्ट द्वारा स्किप किया जाता है और `200` का जवाब दिया जाता है, जो साइलेंट विफलता है जो आइडेंटिटी लेयर मौजूद होने के लिए है। +`propagate()` के बिना, वर्कर की ईवेंट एक `TypeError` उठाती हैं जो सुधार का नाम देते हैं बजाय किसी सेशन पर उतरने के। यह जानबूझकर है: कोई सेशन के साथ एक ईवेंट को ingest द्वारा छोड़ दिया जाता है और `200` उत्तर दिया जाता है, जो मूक विफलता है जिसे पहचान परत रोकने के लिए मौजूद है। -## एक फ्रेमवर्क को इंस्ट्रूमेंट करें जिसके पास एडाप्टर नहीं है +## एडेप्टर के बिना एक फ्रेमवर्क इंस्ट्रूमेंट करें -हर एजेंट फ्रेमवर्क आपको तीन समान सीम देता है। उन्हें मैप करें और आपके पास एक संपूर्ण ट्रेस है — चारों शिप किए गए एडाप्टर इससे ज्यादा कुछ नहीं करते। +हर एजेंट फ्रेमवर्क आपको एक ही तीन सीम देता है। उन्हें मैप करें और आपके पास एक पूर्ण ट्रेस है — चारों शिप किए गए एडेप्टर इससे अधिक कुछ नहीं करते। -| सीम | आप क्या लिखते हैं | क्या लैंड होता है | +| सीम | आप क्या लिखते हैं | क्या उतरता है | | --- | --- | --- | | रन | `session()` + `agent()` | `agent_start`, `agent_end` | -| हर टूल | `tool_call()` | `tool_use`, `tool_result` | -| हर मॉडल कॉल | `model_*` जोड़ी | `model_request`, `model_response` | +| प्रत्येक टूल | `tool_call()` | `tool_use`, `tool_result` | +| प्रत्येक मॉडल कॉल | `model_*` जोड़ी | `model_request`, `model_response` | @@ -241,15 +241,15 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) result = framework.run(task) ``` - - जो कुछ भी फ्रेमवर्क एक टूल रैपर या मिडलवेयर कहता है। + + जो कुछ भी फ्रेमवर्क एक टूल रैपर या मिडलवेयर कहता है उसमें। ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -264,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **क्या आपके पास कोई नोड, स्टेप या मिडलवेयर बाउंड्री है जो देखने लायक है?** इसे एक हुक जोड़ी में रैप करें — `hook_triggered` / `hook_completed` — एक नेस्टेड `agent()` नहीं। `agent_id` एक लो-कार्डिनैलिटी फैसेट है, और प्रति नोड एक प्रविष्टि इसे डूब देती है। हुक स्पैन्स एक जैसे रेंडर होते हैं और आपको प्रति-नोड लेटेंसी देते हैं। + **एक नोड, स्टेप या मिडलवेयर सीमा देखने योग्य है?** इसे एक हुक जोड़ी में लपेटें — `hook_triggered` / `hook_completed` — एक नेस्ट किए गए `agent()` में नहीं। `agent_id` कम-कार्डिनलिटी पहलू है, और प्रति नोड एक प्रविष्टि इसे डुबो देती है। हुक स्पान एक ही तरह से प्रस्तुत होते हैं और आपको प्रति-नोड विलंबता देते हैं। - **मैनुअल और ऑटोमैटिक कम्पोज़ होते हैं।** एक एडाप्टर एक हाथ से लिखे गए स्कोप के अंदर चलता है जो उस सेशन को जॉइन करता है और उस एजेंट को पेरेंट करता है, इसलिए आप एक ट्री प्राप्त करते हैं न कि दो — उपयोगी जब आप एक फ्रेमवर्क को अपने आप से इंस्ट्रूमेंट करते हैं किसी समर्थित के साथ। + **मैनुअल और स्वचालित मिश्रित होते हैं।** एक एडेप्टर एक हाथ से लिखे गए स्कोप के अंदर चल रहा है उस सेशन से जुड़ता है और उस एजेंट का माता-पिता बनता है, इसलिए आपको एक पेड़ मिलता है दो के बजाय — उपयोगी जब आप एक फ्रेमवर्क को स्वयं एक समर्थित के साथ इंस्ट्रूमेंट करते हैं। - - दो कारण हैं, और उपरोक्त तीन सीम दोनों के लिए जवाब हैं: + + दो कारण, और ऊपर दिए गए तीन सीम दोनों का उत्तर हैं: - - `autogen-core` सितंबर 2025 के बाद से अनमेन्टेन्ड है। - - AG2 कोई प्रोसेस-वाइड रजिस्ट्रेशन पॉइंट नहीं देता है अन्य फ्रेमवर्क्स के हुक्स के बराबर, इसलिए इसे इंस्ट्रूमेंट करने का मतलब हर निर्माण साइट पर हर एजेंट को रैप करना है। + - `autogen-core` सितंबर 2025 के बाद से अरक्षित है। + - AG2 अन्य फ्रेमवर्क के हुक के समकक्ष कोई प्रक्रिया-व्यापी पंजीकरण बिंदु नहीं उजागर करता है, इसलिए इसे इंस्ट्रूमेंट करने का अर्थ हर निर्माण साइट पर हर एजेंट को लपेटना है। - सीम्स को हाथ से मैप करना वही इवेंट्स रिकॉर्ड करता है, एक शिप किए गए एडाप्टर की तरह ही फिडेलिटी पर। + सीम को हाथ से मैप करना एक ही ईवेंट को एक ही निष्ठा पर रिकॉर्ड करता है जो एक शिप किया गया एडेप्टर होगा। -## गहराई में जाएं +## गहराई में जाना -रिकॉर्डिंग वास्तव में कैसे काम करती है। शुरुआत करने के लिए इसमें से कोई भी जरूरी नहीं है। +रिकॉर्डिंग वास्तव में कैसे काम करती है। शुरुआत करने के लिए इसमें से कोई भी आवश्यक नहीं है। -हर रिकॉर्डिंग का एक जैसा आकार है: एक स्पैन खुलता है, काम इसके अंदर नेस्ट होता है, और हर ओपनिंग इवेंट को क्लोजिंग इवेंट मिलता है। +हर रिकॉर्डिंग का एक ही आकार है: एक स्पान खुलता है, काम इसके अंदर नेस्ट होता है, और हर ओपनिंग ईवेंट को एक क्लोजिंग ईवेंट मिलता है। ```mermaid flowchart LR @@ -300,17 +300,17 @@ flowchart LR C --> E(["agent_end"]) ``` -**जोड़ी** यूनिट है। हर क्लोजिंग इवेंट एक डेशन लेकर आती है जिसे SDK इसके ओपनिंग वन से मापता है। +**जोड़ी** यूनिट है। प्रत्येक क्लोजिंग ईवेंट एक अवधि ले जाता है जो SDK इसके ओपनिंग वाले से मापता है। -नीचे एक रियल रन प्रति फ्रेमवर्क है — SDK के साथ शिप किए गए उदाहरणों से कैप्चर किया गया, मॉडल नाम नॉर्मलाइज़्ड। ध्यान दें कि एक एकल कॉल से कितना वापस आता है। +नीचे एक वास्तविक रन प्रति फ्रेमवर्क है — SDK के साथ शिप किए गए उदाहरणों से कैप्चर किया गया, मॉडल नाम सामान्यीकृत। ध्यान दें कि एक एकल कॉल से कितना वापस आता है। - ```text 14 events + ```text 14 ईवेंट 1 +0.000s agent_start LangGraph 2 +0.001s hook_triggered agent 3 +0.002s model_request gpt-4o-mini - 4 +3.023s model_response gpt-4o-mini · 21 out-tok + 4 +3.023s model_response gpt-4o-mini · 21 आउट-टोक 5 +3.024s hook_completed agent 6 +3.024s hook_triggered tools 7 +3.025s tool_use word_count @@ -318,77 +318,77 @@ flowchart LR 9 +3.025s hook_completed tools 10 +3.026s hook_triggered agent 11 +3.027s model_request gpt-4o-mini - 12 +5.717s model_response gpt-4o-mini · 5 out-tok + 12 +5.717s model_response gpt-4o-mini · 5 आउट-टोक 13 +5.720s hook_completed agent 14 +5.721s agent_end LangGraph · success ``` - नोड्स हुक जोड़े बन जाते हैं, इसलिए आप प्रति-नोड लेटेंसी प्राप्त करते हैं बिना इसके कि वे एजेंट लिस्ट को भीड़ में ले जाएं। + नोड्स हुक जोड़ी बन जाते हैं, इसलिए आप प्रति-नोड विलंबता प्राप्त करते हैं बिना उन्हें एजेंट सूची में भीड़ किए। - ```text 10 events + ```text 10 ईवेंट 1 +0.000s agent_start crew - 2 +0.050s agent_start analyst · under crew + 2 +0.050s agent_start analyst · crew के तहत 3 +0.057s model_request gpt-4o-mini - 4 +3.475s model_response gpt-4o-mini · 19 out-tok + 4 +3.475s model_response gpt-4o-mini · 19 आउट-टोक 5 +3.478s tool_use lookup_metric 6 +3.478s tool_result lookup_metric · ok 7 +3.486s model_request gpt-4o-mini - 8 +5.694s model_response gpt-4o-mini · 9 out-tok + 8 +5.694s model_response gpt-4o-mini · 9 आउट-टोक 9 +5.727s agent_end analyst · success 10 +5.739s agent_end crew · success ``` - हर एजेंट की `role` इसका स्पैन नाम बन जाती है, इसलिए लेटेंसी और टोकन स्पेंड प्रति रोल को तोड़ते हैं। + प्रत्येक एजेंट का `role` इसका स्पान नाम बनता है, इसलिए विलंबता और टोकन खर्च प्रति भूमिका में विभाजित होते हैं। - ```text 26 events + ```text 26 ईवेंट 1 +0.000s agent_start Agent 2 +0.001s hook_triggered init_run 4 +0.501s hook_triggered setup_agent 6 +0.503s hook_triggered run_agent_step 7 +0.505s model_request gpt-4o-mini - 8 +3.083s model_response gpt-4o-mini · 18 out-tok + 8 +3.083s model_response gpt-4o-mini · 18 आउट-टोक 10 +3.197s hook_triggered parse_agent_output 12 +3.355s hook_triggered call_tool 13 +3.355s tool_use city_population 14 +3.355s tool_result city_population · ok 16 +3.356s hook_triggered aggregate_tool_results - ... दूसरा इटरेशन + ... दूसरा पुनरावृत्ति 26 +7.038s agent_end Agent · success ``` - एजेंट लूप ही दिखाई देता है, केवल इसकी मॉडल कॉल्स नहीं। + एजेंट लूप स्वयं दृश्यमान है, केवल इसके मॉडल कॉल नहीं। - ```text 8 events + ```text 8 ईवेंट 1 +0.000s agent_start agent 2 +0.001s model_request gpt-4o-mini - 3 +4.413s model_response gpt-4o-mini · 17 out-tok + 3 +4.413s model_response gpt-4o-mini · 17 आउट-टोक 4 +4.415s tool_use population 5 +4.415s tool_result population · ok 6 +4.416s model_request gpt-4o-mini - 7 +8.118s model_response gpt-4o-mini · 6 out-tok + 7 +8.118s model_response gpt-4o-mini · 6 आउट-टोक 8 +8.119s agent_end agent · success ``` - कोई हुक जोड़ी नहीं: Pydantic AI के पास कोई नोड या स्टेप बाउंड्री नहीं है। + कोई हुक जोड़ी नहीं: Pydantic AI के पास कोई नोड या स्टेप सीमा नहीं है कि ब्रैकेट करने के लिए। - - ```text 6 events + + ```text 6 ईवेंट 1 +0.000s agent_start main 2 +0.000s tool_use population 3 +0.000s tool_result population · ok 4 +0.000s model_request gpt-4o-mini - 5 +0.000s model_response gpt-4o-mini · 3 out-tok + 5 +0.000s model_response gpt-4o-mini · 3 आउट-टोक 6 +0.000s agent_end main · success ``` - आप इन्हें अपने आप एमिट करते हैं। एक ही इवेंट टाइप्स, एक ही फिडेलिटी — यह आपको कॉल साइट्स खर्च करता है। + आप स्वयं इन्हें उत्सर्जित करते हैं। एक ही ईवेंट प्रकार, एक ही निष्ठा — इसका मतलब कॉल साइट है। @@ -396,28 +396,28 @@ flowchart LR -**कोई सेशन-एंड इवेंट नहीं है।** एक सेशन कुछ नहीं है जिसे आप बंद करते हैं — यह एक `session_id` साझा करने वाली इवेंट्स का एक समूह है। +**कोई सेशन-अंत ईवेंट नहीं है।** एक सेशन कुछ ऐसा नहीं है जिसे आप बंद करते हैं — यह एक `session_id` साझा करने वाली ईवेंट का एक समूह है। -स्टेटस ट्रेस के आकार से निकाला गया है: +स्थिति ट्रेस के आकार से प्राप्त की जाती है: -| स्टेटस | कब | +| स्थिति | कब | | --- | --- | -| `ongoing` | कम से कम एक स्पैन अभी भी खुला है | -| `paused` | एक `agent_pause` का कोई मेल खाता `agent_resume` नहीं है | -| `error` | कुछ नहीं खुला है, और कम से कम एक इवेंट विफल हुई | -| `done` | कुछ नहीं खुला है, और कुछ विफल नहीं हुआ | +| `ongoing` | कम से कम एक स्पान अभी भी खुला है | +| `paused` | एक `agent_pause` का कोई मिलान `agent_resume` नहीं है | +| `error` | कुछ नहीं खुला है, और कम से कम एक ईवेंट विफल रहा | +| `done` | कुछ नहीं खुला है, और कुछ भी विफल नहीं रहा | -तो एक सेशन तब समाप्त होता है जब हर जोड़ी बंद हो जाती है। एडाप्टर आपके लिए `agent_end` एमिट करते हैं, और टियरडाउन पर वे कुछ भी अभी भी खुला छोड़ देते हैं और इसे अधूरा चिह्नित करते हैं — एक क्रैश किया रन `done` के रूप में एक दृश्य अंतराल के साथ सेट हो जाता है हैंगिंग की बजाय। +तो एक सेशन तब समाप्त होता है जब हर जोड़ी बंद हो जाती है। एडेप्टर आपके लिए `agent_end` उत्सर्जित करते हैं, और टियरडाउन पर वे कुछ भी अभी भी खुला बंद करते हैं और इसे अधूरा चिह्नित करते हैं — एक क्रैश किया गया रन `done` बैठता है एक दृश्यमान अंतराल के साथ बजाय हैंगिंग के। - यह है कि क्यों एक सेशन दो कॉल्स को स्पैन कर सकता है। एक LangGraph `interrupt()` रन को रोकता है, रूट स्पैन जानबूझकर खुला रहता है, और रेज़्यूमिंग कॉल इसे बंद करता है। दोनों कॉल्स एक सेशन हैं। + यह है कि एक सेशन दो कॉल पर फैल सकता है। एक LangGraph `interrupt()` रन को रोकता है, रूट स्पान जानबूझकर खुला रहता है, और पुनरारंभ करने वाली कॉल इसे बंद करती है। दोनों कॉल एक सेशन हैं। - + -`session_id` और `agent_id` हर इवेंट मेथड पर वैकल्पिक हैं। छोड़े गए, वे एनक्लोजिंग स्कोप से रिज़ॉल्व होते हैं: +`session_id` और `agent_id` हर ईवेंट विधि पर वैकल्पिक हैं। छोड़ा गया, वे एनक्लोजिंग स्कोप से समाधान करते हैं: ```python with failproofai_sdk.session(): @@ -425,129 +425,129 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -उन्हें स्पष्ट रूप से पास करना अभी भी काम करता है और प्राथमिकता लेता है। कुछ भी बाउंड न हो और कुछ पास न हो, कॉल एक `TypeError` को उठाती है जो फिक्स को नाम देता है न कि कोई सेशन के साथ एक इवेंट एमिट करने के बजाय, जिसे इनजेस्ट स्किप करेगा `200` का जवाब देते हुए। +उन्हें स्पष्ट रूप से पास करने से अभी भी काम करता है और प्राथमिकता लेता है। कुछ भी बांधा नहीं और कुछ भी पारित नहीं, कॉल एक `TypeError` उठाता है जो सुधार का नाम देता है बजाय कोई सेशन के साथ एक ईवेंट उत्सर्जित करने के, जिसे ingest `200` का उत्तर देते हुए छोड़ देगा। -स्कोप्स कॉन्टेक्स्ट वेरिएबल्स पर आइडेंटिटी को बांधते हैं। वे asyncio टास्क्स में स्वचालित रूप से प्रोपेगेट होते हैं लेकिन नए थ्रेड्स में नहीं — `failproofai_sdk.propagate()` में एक वर्कर को रैप करें। +स्कोप संदर्भ चर पर पहचान बांधते हैं। वे asyncio कार्यों में स्वचालित रूप से प्रसारित होते हैं लेकिन नए थ्रेड में नहीं — `failproofai_sdk.propagate()` में एक वर्कर लपेटें। -#### कौन कौन सी आईडी मिंट करता है +#### कौन कौन सी id बनाता है -| आईडी | मिंट किया गया है | नोट्स | +| Id | द्वारा बनाई गई | नोट्स | | --- | --- | --- | -| `session_id` | आप, या SDK | `session("chat-42")` वर्बैटिम है; छोड़े गए, SDK एक `uuid4().hex` जेनरेट करता है | -| `agent_id` | आप, या फ्रेमवर्क | `agent("analyst")` से, एक CrewAI `role`, एक `FunctionAgent.name`। UUID-लुकिंग वैल्यू को अस्वीकार किया जाता है और बदला जाता है | -| `tool_call_id`, `hook_id`, `request_id` | आप, या फ्रेमवर्क | एडाप्टर फ्रेमवर्क की अपनी रन आईडीज को दोबारा उपयोग करते हैं, जो है क्यों जोड़े थ्रेड हॉप्स को सर्वाइव करते हैं | -| **इवेंट आईडी** | **क्लाउड, इनजेस्ट पर** | SDK कोई एमिट नहीं करता है | -| **`dedup_key`** | **क्लाउड, इनजेस्ट पर** | org, session, timestamp, type और payload का एक हैश। यह असली आइडेंटिटी है — यह एक रिट्राइड बैच को डुप्लीकेट होने की बजाय कोलैप्स करता है | +| `session_id` | आप, या SDK | `session("chat-42")` को शब्दशः उपयोग किया जाता है; छोड़ा गया, SDK एक `uuid4().hex` उत्पन्न करता है | +| `agent_id` | आप, या फ्रेमवर्क | `agent("analyst")` से, एक CrewAI `role`, एक `FunctionAgent.name` से। UUID जैसा मान अस्वीकार और प्रतिस्थापित है | +| `tool_call_id`, `hook_id`, `request_id` | आप, या फ्रेमवर्क | एडेप्टर फ्रेमवर्क के अपने रन id को पुनः उपयोग करते हैं, जिसके कारण जोड़ी थ्रेड हॉप के बाद जीवित रहती हैं | +| **ईवेंट id** | **क्लाउड, ingest पर** | SDK कोई उत्सर्जित नहीं करता है | +| **`dedup_key`** | **क्लाउड, ingest पर** | Org, सेशन, टाइमस्टैम्प, प्रकार और पेलोड का एक हैश। यह असली पहचान है — यह एक पुनः प्रयास की गई बैच को डुप्लिकेट करने के बजाय ढहा देता है | -#### एडाप्टर `session_id` को कैसे रिज़ॉल्व करते हैं +#### एडेप्टर `session_id` कैसे समाधान करते हैं -पहला मैच जीतता है: +पहला मैच जीता: 1. एक स्पष्ट `session_id` विकल्प 2. प्रति-कॉल मेटाडेटा 3. एनक्लोजिंग `session()` स्कोप 4. फ्रेमवर्क मेटाडेटा -5. फ्रेमवर्क की अपनी रन आईडी +5. फ्रेमवर्क का अपना रन id -यह कभी भी तब तक इन्वेंट नहीं किया जाता जब तक उनमें से एक मौजूद है — एक सिंथेसाइज़्ड आईडी एक रन को कई सेशन्स में स्प्लिट करेगी। +इसे कभी आविष्कार नहीं किया जाता है जबकि इनमें से एक मौजूद है — एक संश्लेषित id एक रन को कई सेशन में विभाजित करेगा। -#### `agent_id` को लो कार्डिनैलिटी रखें +#### `agent_id` को कम कार्डिनलिटी रखें -यह हर डैशबोर्ड सर्फेस पर प्राथमिक फैसेट है, और एक `LowCardinality(String)` कॉलम है। एक प्रति-रन वैल्यू कॉलम को डिग्रेड करती है और फिल्टर ड्रॉपडाउन को प्रति रन एक प्रविष्टि से भर देती है। +यह हर डैशबोर्ड सतह पर प्राथमिक पहलू है, और एक `LowCardinality(String)` कॉलम। एक प्रति-रन मान कॉलम को खराब करता है और फ़िल्टर ड्रॉपडाउन को प्रति रन एक प्रविष्टि से भरता है। -एडाप्टर आपके लिए उस कॉलम की रक्षा करते हैं: +एडेप्टर उस कॉलम की रक्षा करते हैं: -| फ्रेमवर्क हाथ ओवर करता है | रिकॉर्ड किया गया है | क्यों | +| फ्रेमवर्क सौंपता है | रिकॉर्ड किया गया | क्यों | | --- | --- | --- | -| `3f9a1c2b-…` (एक UUID) | `main` | रखने के लिए कुछ भी पठनीय नहीं | -| एक लंबी खाली हेक्स स्ट्रिंग | `main` | वही | -| `agent-3f9a1c2b-…` | `agent` | प्रति-रन आईडी स्ट्रिप, पठनीय भाग रखा | -| `agent-v2` | `agent-v2` | शॉर्ट सेगमेंट्स अकेला छोड़ दिया गया | +| `3f9a1c2b-…` (एक UUID) | `main` | कुछ पठनीय नहीं रखने के लिए | +| एक लंबी नंगी हेक्स स्ट्रिंग | `main` | वही | +| `agent-3f9a1c2b-…` | `agent` | प्रति-रन id छीन लिया गया, पठनीय भाग रखा गया | +| `agent-v2` | `agent-v2` | छोटे सेगमेंट अकेले छोड़ दिए जाते हैं | | `step-3` | `step-3` | वही | -असली आईडी को `fw_agent_id` / `fw_run_id` पर रखा जाता है, जहां यह एक फैसेट होने के बिना क्वेरीएबल रहता है। +असली id `fw_agent_id` / `fw_run_id` पर रखा जाता है, जहां यह एक पहलू बने बिना पूछताछ योग्य रहता है। - **यह गार्ड केवल लेबल को छूता है जो *फ्रेमवर्क* ने चुना।** एक `agent_id` जो आप खुद पास करते हैं — `event.*` को, या `failproofai_sdk.agent(...)` को — बिल्कुल जैसे दिया गया है रिकॉर्ड किया जाता है। एक स्पष्ट तर्क को साइलेंटली दोबारा लिखना इसे रोकने वाली कार्डिनैलिटी से बदतर होगा, इसलिए अपने स्वयं के स्पैन्स को तदनुसार नाम दें। + **यह गार्ड केवल *फ्रेमवर्क* द्वारा चुने गए लेबल को छूता है।** एक `agent_id` जिसे आप स्वयं पास करते हैं — `event.*`, या `failproofai_sdk.agent(...)` के लिए — ठीक जैसे दिया गया रिकॉर्ड किया जाता है। एक स्पष्ट तर्क को मूक रूप से फिर से लिखना उस कार्डिनलिटी से बदतर होगा जिसे यह रोकता है, इसलिए अपने स्वयं के स्पान का नाम तदनुसार रखें। - + -| ग्रुप | इवेंट्स | +| समूह | ईवेंट | | --- | --- | -| एजेंट्स | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | -| मॉडल्स | `model_request`, `model_response` | -| टूल्स | `tool_use`, `tool_result` | -| हुक्स | `hook_triggered`, `hook_completed` | -| ह्यूमन्स | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| एजेंट | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| मॉडल | `model_request`, `model_response` | +| टूल | `tool_use`, `tool_result` | +| हुक | `hook_triggered`, `hook_completed` | +| मनुष्य | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | विफलताएं | `error` | -कौन सा फ्रेमवर्क क्या रिकॉर्ड करता है, उपरोक्त रन से मापा गया: +कौन सा फ्रेमवर्क क्या रिकॉर्ड करता है, ऊपर से रन से मापा गया: -| इवेंट | LangGraph | CrewAI | LlamaIndex | Pydantic AI | कस्टम | +| ईवेंट | LangGraph | CrewAI | LlamaIndex | Pydantic AI | कस्टम | | --- | :--: | :--: | :--: | :--: | :--: | -| एजेंट स्टार्ट और एंड | हाँ | हाँ | हाँ | हाँ | आप | -| मॉडल रिक्वेस्ट और रिस्पांस | हाँ | हाँ | हाँ | हाँ | आप | -| टूल यूज़ और रिजल्ट | हाँ | हाँ | हाँ | हाँ | आप | -| हुक ट्रिगर्ड और कम्पलीटेड | नोड | टास्क | स्टेप | — | आप | -| एरर | हाँ | हाँ | हाँ | हाँ | ऑटोमैटिक | -| ह्यूमन वेट और इनपुट | हाँ | हाँ | हाँ | — | आप | -| एजेंट पॉज़ और रेज़्यूम | हाँ | हाँ | हाँ | — | आप | +| एजेंट शुरु और अंत | हां | हां | हां | हां | आप | +| मॉडल अनुरोध और प्रतिक्रिया | हां | हां | हां | हां | आप | +| टूल उपयोग और परिणाम | हां | हां | हां | हां | आप | +| हुक ट्रिगर और पूर्ण | नोड | कार्य | स्टेप | — | आप | +| त्रुटि | हां | हां | हां | हां | स्वचालित | +| मानव प्रतीक्षा और इनपुट | हां | हां | हां | — | आप | +| एजेंट पॉज़ और पुनरारंभ | हां | हां | हां | — | आप | -एक डैश का मतलब है कि फ्रेमवर्क के पास ऐसी कोई कॉन्सेप्ट नहीं है। `human_pause` और `human_interrupt` एक *व्यक्ति* को एजेंट पर काम करने का वर्णन करते हैं, जिसे कोई फ्रेमवर्क सिग्नल नहीं करता — इन्हें अपने आप एमिट करें। +एक डैश का मतलब फ्रेमवर्क के पास कोई ऐसी अवधारणा नहीं है। `human_pause` और `human_interrupt` एक *व्यक्ति* द्वारा एजेंट पर कार्य करने का वर्णन करते हैं, जिसका कोई फ्रेमवर्क संकेत नहीं देता — स्वयं उत्सर्जन करें। - + -एक इवेंट कभी भी अकेली नहीं आती। एक स्पैन को खोलता है, एक इसे बंद करता है, और क्लोजिंग इवेंट एक डेशन लेकर आती है जिसे SDK ओपनिंग वन से मापता है। +एक ईवेंट कभी अकेले नहीं आता। एक स्पान खुलता है, एक बंद होता है, और क्लोजिंग ईवेंट एक अवधि ले जाता है जो SDK इसके ओपनिंग वाले से मापता है। -| खोलता है | बंद करता है | क्लोजिंग इवेंट लेकर आती है | +| खुलता है | बंद होता है | क्लोजिंग ईवेंट ले जाता है | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | -| `model_request` | `model_response` | टोकन्स, `stop_reason`, लेटेंसी | -| `tool_use` | `tool_result` | `output` या `error`, डेशन | -| `hook_triggered` | `hook_completed` | `outcome`, डेशन | -| `agent_pause` | `agent_resume` | पॉज़ कितना लंबा रहा | -| `human_wait` | `human_input` | जवाब, और व्यक्ति को कितना समय लगा | +| `model_request` | `model_response` | टोकन, `stop_reason`, विलंबता | +| `tool_use` | `tool_result` | `output` या `error`, अवधि | +| `hook_triggered` | `hook_completed` | `outcome`, अवधि | +| `agent_pause` | `agent_resume` | पॉज़ कितने समय तक चला | +| `human_wait` | `human_input` | उत्तर, और व्यक्ति को कितना समय लगा | - कोई क्लोजिंग इवेंट के साथ एक ओपनिंग इवेंट एक स्पैन है जो कभी ख़त्म नहीं होता है। सेशन हमेशा चल रहा दिखाई देता है, हमेशा के लिए, और इसकी एक्टिव डेशन बढ़ती रहती है। यह विफलता मोड है जब आप हाथ से इंस्ट्रूमेंट करते हैं तो देखने के लिए है। + कोई क्लोजिंग के साथ एक ओपनिंग ईवेंट कभी खत्म नहीं होने वाला एक स्पान है। सेशन हमेशा चल रहे के रूप में प्रस्तुत होता है, हमेशा के लिए, और इसकी सक्रिय अवधि बढ़ती रहती है। यह वह विफलता मोड है जिसे हाथ से इंस्ट्रूमेंट करते समय देखने के लिए है। -#### कोरिलेशन नियम +#### सहसंबंध नियम -- मेल खाती कम्पलीशन इवेंट के लिए एक ही `tool_call_id`, `hook_id`, `pause_id`, या `input_id` को दोबारा यूज़ करें। -- SDK `tool_result`, `hook_completed`, `agent_resume`, और `human_input` के लिए `duration_ms` को कंप्यूट करता है। इसे उन मेथड्स को पास करना `ValueError` को उठाता है। -- `duration_ms` **को स्वीकार किया जाता है** `model_response` पर, क्योंकि केवल कॉलर असली प्रोवाइडर लेटेंसी को जानता है। यह एक इंटीजर होना चाहिए — एक फ्लोट कॉल साइट पर `ValueError` को उठाता है, क्योंकि सर्वर कॉलम को एक अनसाइन्ड 32-बिट इंटीजर के रूप में पढ़ता है और कुछ भी और के लिए NULL स्टोर करेगा। -- कोरिलेशन कीज़ को kind और session द्वारा स्कोप किया जाता है, इसलिए एक टूल कॉल और एक हुक सुरक्षित रूप से एक आईडी साझा कर सकते हैं, और दो एक साथ सेशन्स बिना कोलाइड किए एक ही आईडीज को दोबारा उपयोग कर सकते हैं। वे एजेंट द्वारा स्कोप नहीं किए जाते: एक जोड़ी एक एजेंट के तहत खुली और दूसरे के तहत बंद अभी भी डाउनस्ट्रीम में कोरिलेट होती है, जो मल्टी-एजेंट फ्रेमवर्क्स में सामान्य केस है। -- `request_id` `model_request` को `model_response` से जोड़ता है। इसके बिना, मॉडल इवेंट्स प्रति एजेंट ऑर्डर में जोड़े जाते हैं, इसलिए एक साथ कॉल्स मिस्पेयर होती हैं। -- एक जोड़ी प्रोसेस्स में स्प्लिट डाउनस्ट्रीम में अभी भी कोरिलेट होती है, लेकिन SDK इसकी इन-प्रोसेस डेशन को कंप्यूट नहीं कर सकता है। -- पेंडिंग मैप सर्वाधिक 10,000 स्टार्ट्स रखता है और पूर्ण होने पर सबसे पुरानी प्रविष्टि को निष्कासित करता है। +- मिलान पूर्णता ईवेंट के लिए एक ही `tool_call_id`, `hook_id`, `pause_id`, या `input_id` का पुनः उपयोग करें। +- SDK `tool_result`, `hook_completed`, `agent_resume`, और `human_input` के लिए `duration_ms` की गणना करता है। इसे उन विधियों में पास करने से `ValueError` उठता है। +- `duration_ms` **स्वीकार किया जाता है** `model_response` पर, क्योंकि केवल कॉलर असली प्रदाता विलंबता जानता है। यह एक पूर्णांक होना चाहिए — एक फ्लोट कॉल साइट पर `ValueError` उठाता है, क्योंकि सर्वर कॉलम को एक अहस्ताक्षरित 32-बिट पूर्णांक के रूप में पढ़ता है और कुछ और के लिए NULL संग्रहीत करेगा। +- सहसंबंध कुंजियां तरह और सेशन द्वारा स्कोप की जाती हैं, इसलिए एक टूल कॉल और एक हुक सुरक्षित रूप से एक id साझा कर सकते हैं, और दो समवर्ती सेशन टकराए बिना समान id का पुनः उपयोग कर सकते हैं। वे एजेंट द्वारा स्कोप नहीं किए जाते हैं: एक जोड़ी एक एजेंट के तहत खुली और दूसरे के तहत बंद अभी भी सहसंबंधित होती है, जो बहु-एजेंट फ्रेमवर्क में सामान्य मामला है। +- `request_id` `model_request` को `model_response` के साथ जोड़ी करता है। इसके बिना, मॉडल ईवेंट प्रति एजेंट क्रम में जोड़ी होती हैं, इसलिए समवर्ती कॉल गलत जोड़ी बनाती हैं। +- प्रक्रियाओं में विभाजित एक जोड़ी अभी भी डाउनस्ट्रीम में सहसंबंधित होती है, लेकिन SDK इसकी प्रक्रिया में-अवधि की गणना नहीं कर सकता है। +- लंबित मानचित्र अधिकतम 10,000 स्टार्ट पकड़ता है और पूर्ण होने पर सबसे पुरानी प्रविष्टि को निष्कासित करता है। - + -`failproofai-sdk` को इंस्टॉल करने से सब कुछ इंस्टॉल होता है, सभी चारों एडाप्टर शामिल। एक्सट्रास **फ्रेमवर्क** को पुल इन करते हैं, एडाप्टर को नहीं। +`failproofai-sdk` इंस्टॉल करने से सब कुछ इंस्टॉल होता है, सभी चार एडेप्टर शामिल हैं। अतिरिक्त एडेप्टर नहीं, **फ्रेमवर्क** खींचते हैं। ```python -import failproofai_sdk # स्टैंडर्ड लाइब्रेरी के बाहर कुछ नहीं लोड करता है -failproofai_sdk.instrument() # केवल एडाप्टर्स को इंपोर्ट करता है जिन्हें आप वास्तव में चाहते हैं +import failproofai_sdk # मानक पुस्तकालय के बाहर कुछ भी लोड नहीं करता है +failproofai_sdk.instrument() # केवल एडेप्टर आयात करता है जिसकी आपको वास्तव में आवश्यकता है ``` -`import failproofai_sdk` संविदात्मक रूप से शून्य-निर्भरता है, एक टेस्ट द्वारा लागू किया गया है जो `--no-deps` के साथ बिल्ट व्हील को इंस्टॉल करता है और एक अन्य जो साबित करता है कि कोई फ्रेमवर्क `sys.modules` तक नहीं पहुंचता है। +`import failproofai_sdk` अनुबंध शून्य-निर्भरता है, एक परीक्षण द्वारा प्रवर्तित जो निर्मित व्हील को `--no-deps` के साथ इंस्टॉल करता है और एक और जो साबित करता है कि कोई फ्रेमवर्क `sys.modules` तक नहीं पहुंचता है। - कोई `failproofai_sdk.crewai` एट्रिब्यूट नहीं है। एडाप्टर्स को जानबूझकर टॉप-लेवल पैकेज पर एक्सपोज़ नहीं किया जाता है: एक को छूना एक एट्रिब्यूट एक्सेस के साइड इफेक्ट के रूप में फ्रेमवर्क को इंपोर्ट करेगा, शून्य-निर्भरता प्रॉमिस को तोड़ देगा। `instrument()` का यूज़ करें। + कोई `failproofai_sdk.crewai` विशेषता नहीं है। एडेप्टर जानबूझकर शीर्ष-स्तरीय पैकेज पर प्रदर्शित नहीं होते हैं: एक को छूना एक विशेषता पहुंच के दुष्प्रभाव के रूप में फ्रेमवर्क आयात करेगा, शून्य-निर्भरता प्रतिश्रुति को तोड़ते हुए। `instrument()` का उपयोग करें। ```python -failproofai_sdk.instrument() # हर फ्रेमवर्क पहले से ही इंपोर्ट किया गया +failproofai_sdk.instrument() # हर फ्रेमवर्क पहले से ही आयात किया गया है failproofai_sdk.instrument("crewai") # बिल्कुल एक, नाम से -failproofai_sdk.uninstrument("crewai") # इसे वापस रखें +failproofai_sdk.uninstrument("crewai") # इसे वापस रखो ``` | नाम | यह भी स्वीकार करता है | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # इसे वापस रखें | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -ऑटो-डिटेक्शन `sys.modules` को पढ़ता है, इंस्टॉल किए गए पैकेज लिस्ट को नहीं, इसलिए एक फ्रेमवर्क जो आपके पास इंस्टॉल है लेकिन कभी इंपोर्ट नहीं किया गया इंस्ट्रूमेंट नहीं है और आपकी ओर से कभी इंपोर्ट नहीं होता है। क्या है यह देखने के लिए वायर्ड अप: +ऑटो-डिटेक्शन `sys.modules` को पढ़ता है, न कि इंस्टॉल किए गए पैकेज सूची को, इसलिए एक फ्रेमवर्क जिसे आपने इंस्टॉल किया है लेकिन कभी आयात नहीं किया वह इंस्ट्रूमेंट नहीं है और आपकी ओर से कभी आयात नहीं किया जाता है। यह देखने के लिए कि क्या वायर्ड है: ```python from failproofai_sdk.integrations import active, available @@ -567,130 +567,132 @@ active() # ('langchain',) ``` - **`instrument("crewai")` एक मशीन पर CrewAI के बिना उठाता नहीं है।** यह एक चेतावनी लॉग करता है और `()` रिटर्न करता है, इसलिए एक गायब फ्रेमवर्क कभी भी एक प्रोसेस को नीचे नहीं ले जाता जो अन्य लोगों को भी इंस्ट्रूमेंट करता है। + **बिना CrewAI वाली मशीन पर `instrument("crewai")` नहीं उठाता।** यह एक चेतावनी लॉग करता है और `()` लौटाता है, इसलिए एक लापता फ्रेमवर्क कभी एक प्रक्रिया को नीचे नहीं लाता है जो अन्य को भी इंस्ट्रूमेंट करता है। - चेतावनी अंतर्निहित `ImportError` को लेकर आती है, और वह संदेश सटीक इंस्टॉल कमांड को नाम देता है — इसलिए फिक्स आपके लॉग्स में है, छिपा नहीं है। + चेतावनी अंतर्निहित `ImportError` ले जाती है, और वह संदेश सटीक install कमांड का नाम देता है — इसलिए सुधार आपके लॉग में है, छिपा नहीं। ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - इसे उठाने के लिए `FAILPROOFAI_SDK_STRICT=1` सेट करें। वह फ्लैग **एक बार पढ़ा जाता है और कैश किया जाता है**, इसलिए इसे अपनी प्रोसेस शुरू होने से पहले एक्सपोर्ट करें न कि मिड-रन सेट करें। + इसके बजाय उठाने के लिए `FAILPROOFAI_SDK_STRICT=1` सेट करें। वह झंडा **एक बार पढ़ा जाता है और कैश किया जाता है**, इसलिए मध्य-रन सेट करने के बजाय अपनी प्रक्रिया शुरू होने से पहले निर्यात करें। - **`instrument()` आपके फ्रेमवर्क इंपोर्ट के *बाद* आना चाहिए।** ऑटो-डिटेक्शन `sys.modules` को पढ़ता है, इसलिए इंपोर्ट के ऊपर एक खाली कॉल कुछ नहीं खोजता है, कुछ नहीं इंस्टॉल करता है, और `()` रिटर्न करता है। + **`instrument()` *आपके फ्रेमवर्क आयात के बाद* आना चाहिए।** ऑटो-डिटेक्शन `sys.modules` को पढ़ता है, इसलिए आयात के ऊपर एक नंगा कॉल कुछ भी नहीं खोजता है, कुछ भी इंस्टॉल नहीं करता है, और `()` लौटाता है। ```python गलत import failproofai_sdk -failproofai_sdk.instrument() # sys.modules के पास अभी langchain नहीं है -> () +failproofai_sdk.instrument() # sys.modules के पास अभी तक कोई langchain नहीं है -> () -import langchain # बहुत देर, कुछ नहीं वायर्ड है +import langchain # बहुत देर हो गई, कुछ भी वायर्ड नहीं है ``` ```python सही -import langchain # पहले फ्रेमवर्क को इंपोर्ट करें +import langchain # पहले फ्रेमवर्क आयात करें import failproofai_sdk failproofai_sdk.instrument() # इसे खोजता है -> ('langchain',) ``` -```python सही, ऑर्डर-प्रूफ +```python सही, क्रम-प्रूफ import failproofai_sdk -# इसे नाम देने से एडाप्टर को अनुरोध पर इंपोर्ट करता है, इसलिए यह कहीं से भी काम करता है। +# इसका नाम देने से एडेप्टर अनुरोध पर आयात होता है, इसलिए यह कहीं से भी काम करता है। failproofai_sdk.instrument("langchain") ``` -यह गलत प्राप्त करें और प्रोसेस SDK इंपोर्ट के साथ चलता है, एडाप्टर स्पष्ट रूप से इंस्टॉल किया गया, और **एक भी इवेंट एमिट नहीं।** यह यह कह रही एक चेतावनी लॉग करता है — इसलिए जब एक रन कुछ भी रिकॉर्ड नहीं करता है तो पहले अपने लॉग्स को चेक करें। +यह गलत प्राप्त करें और प्रक्रिया SDK आयातित, एडेप्टर स्पष्ट रूप से इंस्टॉल, और **कोई भी ईवेंट उत्सर्जित नहीं** के साथ चलता है। यह एक चेतावनी लॉग करता है जो बिल्कुल ऐसा कहता है — इसलिए एक रन रिकॉर्ड नहीं करते समय पहले अपने लॉग जांचें। - + ```mermaid flowchart LR - A["आपका एजेंट"] --> B["एडाप्टर"] - B --> C["राइटर
इन-मेमोरी क्यू"] + A["आपका एजेंट"] --> B["एडेप्टर"] + B --> C["राइटर
इन-मेमोरी कतार"] C -->|"हर 0.5s"| D["स्पूल
डिस्क पर JSONL"] - D --> E["Failproof डेमॉन"] + D --> E["Failproof डेमन"] E -->|"HTTPS"| F["क्लाउड"] ``` -| स्टेज | जॉब | रन में | +| चरण | काम | में चलता है | | --- | --- | --- | -| एडाप्टर | एक फ्रेमवर्क कॉलबैक को 15 इवेंट टाइप्स में से एक में ट्रांसलेट करता है | आपकी प्रोसेस | -| राइटर | क्यू करता है, बैच करता है, JSONL को परमाणु रूप से लिखता है | आपकी प्रोसेस, बैकग्राउंड थ्रेड | -| स्पूल | टिकाऊ हैंडऑफ, आपकी प्रोसेस से बाहर निकलना सर्वाइव करता है | स्थानीय डिस्क | -| डेमॉन | स्पूल को देखता है, बैच को शिप करता है, जो शिप करता है उसे डिलीट करता है | आपकी मशीन | -| इनजेस्ट | एक पंक्ति आईडी और डीडुप की असाइन करता है, क्वेरीएबल कॉलम्स को प्रमोट करता है | क्लाउड | +| एडेप्टर | एक फ्रेमवर्क कॉलबैक को 15 ईवेंट प्रकारों में से एक में अनुवाद करता है | आपकी प्रक्रिया | +| राइटर | कतार, बैच, JSONL परमाणु रूप से लिखता है | आपकी प्रक्रिया, पृष्ठभूमि थ्रेड | +| स्पूल | टिकाऊ हस्तांतरण, आपकी प्रक्रिया से बचता है | स्थानीय डिस्क | +| डेमन | स्पूल देखता है, बैच भेजता है, जो भेजा गया है उसे हटाता है | आपकी मशीन | +| Ingest | एक पंक्ति id और dedup कुंजी असाइन करता है, पूछताछ योग्य कॉलम को बढ़ावा देता है | क्लाउड | -स्पूल यह है जो यह सुरक्षित बनाता है: आपका एजेंट कभी भी नेटवर्क पर ब्लॉक नहीं करता है, और एक क्लाउड आउटेज का मतलब एक बढ़ती हुई डायरेक्टरी है खोई हुई इवेंट्स की बजाय। +स्पूल वह है जो इसे सुरक्षित बनाता है: आपका एजेंट कभी नेटवर्क पर ब्लॉक नहीं होता है, और एक क्लाउड आउटेज एक बढ़ती डायरेक्टरी का मतलब है खोई हुई ईवेंट के बजाय। -हर फ्लश एक बैच फ़ाइल लिखता है, `.tmp` पहले, फिर `fsync`, फिर एक परमाणु रीनेम: +प्रत्येक फ्लश एक बैच फाइल लिखता है, पहले `.tmp`, फिर `fsync`, फिर एक परमाणु नाम बदलना: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -डेमॉन केवल `.jsonl` को पिक अप करता है, इसलिए यह कभी भी एक आधी-लिखी गई फ़ाइल को नहीं पढ़ सकता है। स्टेम एक टाইमस्टैम्प, प्रोसेस आईडी और सीक्वेंस नंबर को लेकर आती है, इसलिए दो प्रोसेस्स एक ही मिलीसेकंड में फ्लश होने से कोलाइड नहीं कर सकते हैं। क्यू को 10,000 इवेंट्स पर कैप किया गया है; उसके आगे यह सबसे पुरानी को ड्रॉप करता है और लॉग करता है। +डेमन केवल `.jsonl` उठाता है, इसलिए यह कभी आधी-लिखी गई फाइल नहीं पढ़ सकता। स्टेम एक टाइमस्टैम्प, प्रक्रिया id और अनुक्रम संख्या ले जाता है, इसलिए दो प्रक्रियाएं एक ही मिलीसेकंड में फ्लश करना संघर्ष नहीं कर सकती हैं। कतार 10,000 ईवेंट पर capped है; इसके बाद यह सबसे पुरानी को बंद करता है और लॉग करता है। - **`collector.redact` SDK इवेंट्स के लिए भी `minimal` को डिफ़ॉल्ट करता है।** SDK बैच को डिस्क में लिखने से पहले स्क्रब करता है, और डेमॉन अपलोड से पहले एक ही नियतिवादी पास को दोहराता है इसलिए पुराने SDKs से बैच संरक्षित हैं। + **`collector.redact` आपकी SDK ईवेंट पर लागू नहीं होता है।** यह कभी उन्हें नहीं देखता है। -डेमॉन हर बैच को पढ़ता है और अपलोड से पहले इन-मेमोरी में रीडेक्शन को लागू करता है। यह पढ़ी गई स्पूल फ़ाइल को दोबारा लिखता नहीं है। +डेमन आपकी बैच **भेजता है**। वह उन्हें खोलता या फिर से लिखता नहीं है। -| इवेंट्स | लिखा गया है | जहां न्यूनतम रीडेक्शन चलता है | +| ईवेंट | द्वारा लिखा गया | `collector.redact` से संरक्षित? | | --- | --- | --- | -| CLI सेशन ट्रांसक्रिप्ट्स | डेमॉन | डेमॉन बैच लिखने से पहले | -| हुक एक्टिविटी | डेमॉन | डेमॉन बैच लिखने से पहले | -| **सब कुछ SDK एमिट करता है** | **आपकी प्रोसेस** | **SDK बैच लिखने से पहले और डेमॉन अपलोड से पहले** | +| CLI सेशन प्रतिलेख | डेमन | हां | +| हुक गतिविधि | डेमन | हां | +| **SDK जो कुछ भी उत्सर्जित करता है** | **आपकी प्रक्रिया** | **नहीं** | -`collector.redact` को `off` पर केवल तब सेट करें जब वर्बैटिम पेलोड्स एक स्पष्ट आवश्यकता हों; SDK और डेमॉन दोनों उस सेटिंग को सम्मानित करते हैं। न्यूनतम रीडेक्शन सामान्य API की, बेयरर टोकन्स, JWTs, और सीक्रेट असाइनमेंट्स को पकड़ता है। यह मनमाना संवेदनशील गद्य को आइडेंटिफाई नहीं कर सकता है। +संपादन जहां डेमन अपनी स्वयं की ईवेंट **लिखता है** — जहां बैच **भेजे जाते हैं** नहीं। इसलिए एक प्रॉम्प्ट या एक टूल तर्क जिसमें एक API कुंजी होती है अभी भी आगमन पर रखती है। + +यह जानबूझकर है। ये आपके स्वयं के इंस्ट्रूमेंटेशन कॉल हैं, और पारगमन में उन्हें फिर से लिखने का अर्थ होगा कि आप जो ईवेंट प्राप्त करते हैं वे ईवेंट नहीं हैं जो आपने उत्सर्जित किए हैं। - **आप पेलोड्स को स्रोत पर नियंत्रित करते हैं, दो जगहों में:** + **आप स्रोत पर पेलोड को नियंत्रित करते हैं, दो जगहों में:** - - एडाप्टर पर कॉन्टेंट कैप्चर को बंद करें। **विकल्प नाम भिन्न होता है, और एक एडाप्टर के पास कोई नहीं है** — यह एक एकल सार्वभौमिक स्विच नहीं है: + - एडेप्टर पर सामग्री कैप्चर बंद करें। **विकल्प नाम भिन्न होता है, और एक एडेप्टर के पास कोई नहीं है** — यह एक एकल सार्वभौमिक स्विच नहीं है: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **कोई कॉन्टेंट स्विच नहीं**; `session_id` एकमात्र विकल्प है जो यह पढ़ता है, इसलिए प्रॉम्प्ट्स और कम्पलीशन्स हमेशा रिकॉर्ड होते हैं। + - CrewAI — **कोई सामग्री स्विच नहीं**; `session_id` एकमात्र विकल्प है यह पढ़ता है, इसलिए प्रॉम्प्ट और पूर्ति हमेशा रिकॉर्ड किए जाते हैं। - `instrument()` ऐसे विकल्पों को ड्रॉप करता है जो एक एडाप्टर पढ़ता नहीं है, इसलिए गलत नाम को पास करना कुछ भी उठाता नहीं और कुछ भी नहीं बदलता है। - - सीक्रेट को `input=` में पहली जगह पर हाथ न दें। + `instrument()` एडेप्टर द्वारा पढ़ी जाने वाली विकल्प को छोड़ता है, इसलिए गलत नाम पास करने से कुछ नहीं उठाया जाता है और कुछ भी नहीं बदलता है। + - पहली जगह में रहस्य को `input=` को हाथ न सौंपें। - `collector.redact` डिफेंस इन डेप्थ है, किसी भी का विकल्प नहीं। + `collector.redact` किसी के लिए विकल्प नहीं है। - **एक खाली स्पूल डायरेक्टरी स्वस्थ स्टेट है।** डिलीवरी को चेक करने के लिए इसका यूज़ न करें। + **एक खाली स्पूल डायरेक्टरी स्वस्थ स्थिति है।** इसे डिलीवरी की जांच करने के लिए न बनाएं। -डेमॉन इसे शिप करने के एक मिलीसेकंड के अंदर हर बैच को डिलीट करता है, इसलिए एक `ls` कलेक्टर को रेस करता है और आपने जो एमिट किया उसका एक अंश दिखाता है — एक SDK से अलग नहीं जिसने कुछ भी रिकॉर्ड नहीं किया। +डेमन इसे भेजने के मिलीसेकंड के भीतर प्रत्येक बैच को हटा देता है, इसलिए एक `ls` रेस एकत्रकर्ता और आपने जो उत्सर्जित किया उसका एक अंश दिखाता है — एक SDK से अप्रभेद्य जो कुछ भी रिकॉर्ड नहीं करता है। -इवेंट्स वास्तव में लैंड किए गए हैं यह कन्फर्म करने के लिए, डैशबोर्ड को चेक करें। स्पूल को भरते हुए देखने के लिए, पहले डेमॉन को स्टॉप करें। +ईवेंट वास्तव में उतरे हैं यह पुष्टि करने के लिए, डैशबोर्ड की जांच करें। स्पूल को भरते हुए देखने के लिए, पहले डेमन को रोकें। - + -हर कॉलबैक एक रैपर के अंदर चलता है जिसका एकमात्र जॉब फिर से उठाना है, इसलिए आपकी कॉल बिल्कुल एक `try` में बैठती है और सब कुछ SDK करता है इसके बाहर होता है। +हर कॉलबैक एक रैपर के अंदर चलता है जिसका एकमात्र काम पुनः उठाना है, इसलिए आपकी कॉल ठीक एक `try` में बैठता है और सब कुछ SDK करता है इसके बाहर होता है। | क्या होता है | परिणाम | | --- | --- | -| एक हुक उठाता है | अपनी ट्रेसबैक के साथ एक बार लॉग किया गया। आपकी कॉल अप्रभावित है | -| एक ही हुक तीन बार उठाता है | वह हुक बाकी प्रोसेस के लिए डिसेबल्ड है, एक एरर लाइन के साथ | -| `FAILPROOFAI_SDK_STRICT=1` सेट है | एक्सेप्शन को फिर से उठाया जाता है | -| एक फ्रेमवर्क वर्जन टेस्ट्ड रेंज के बाहर है | एक बार चेतावनी, अभी भी इंस्ट्रूमेंट करता है | -| एक एकल क्षमता गायब है | वह हुक डिसेबल्ड है, कभी पूरा एडाप्टर नहीं | +| एक हुक उठाता है | अपने ट्रेसबैक के साथ एक बार लॉग किया गया। आपकी कॉल अप्रभावित है | +| एक ही हुक तीन बार उठाता है | वह एक हुक बाकी के लिए अक्षम हो जाता है, एक त्रुटि पंक्ति के साथ | +| `FAILPROOFAI_SDK_STRICT=1` सेट है | अपवाद के बजाय फिर से उठाया जाता है | +| एक फ्रेमवर्क संस्करण परीक्षित सीमा के बाहर है | एक बार चेतावनी, किसी भी तरह इंस्ट्रूमेंट | +| एक एकल क्षमता लापता है | वह एक हुक अक्षम है, संपूर्ण एडेप्टर कभी नहीं | -डिफ़ॉल्ट प्रोडक्शन में सही है और डीबग करते समय गलत है, क्योंकि यह केवल यह साबित कर सकता है कि यह क्रैश नहीं हुआ। `FAILPROOFAI_SDK_STRICT=1` सेट करें एक निगली हुई विफलता को जोर दे करने के लिए। +डिफ़ॉल्ट उत्पादन में सही है और डीबग करते समय गलत है, क्योंकि यह केवल यह साबित कर सकता है कि यह क्रैश नहीं हुआ। डीबग करते समय इसे जोर देने के लिए `FAILPROOFAI_SDK_STRICT=1` सेट करें। @@ -699,24 +701,24 @@ flowchart LR ## सामान्य समस्याएं - - एक ओपनिंग इवेंट का कोई क्लोजिंग नहीं है: एक `model_request` कोई `model_response` के बिना, या एक `tool_use` कोई `tool_result` के बिना। स्कोप्स का यूज़ करें, जो भले ही बॉडी उठे तब भी जोड़ी को गारंटी देते हैं। यदि आप इवेंट मेथड्स को सीधे कॉल करते हैं, तो `try` और `finally` का यूज़ करें। + + एक ओपनिंग ईवेंट का कोई क्लोजिंग नहीं है: एक `model_request` के बिना `model_response`, या एक `tool_use` के बिना `tool_result`। स्कोप का उपयोग करें, जो शरीर उठाए जाने पर भी जोड़ी की गारंटी देते हैं। यदि आप ईवेंट विधियों को सीधे कॉल करते हैं, तो `try` और `finally` का उपयोग करें। - - यह मेल खाती ओपनिंग इवेंट से मापा जाता है, इसलिए यह `tool_result`, `hook_completed`, `agent_resume`, और `human_input` पर अस्वीकार किया जाता है। यह `model_response` पर स्वीकार किया जाता है, क्योंकि केवल आप असली प्रोवाइडर लेटेंसी को जानते हैं, और यह एक इंटीजर होना चाहिए। + + यह मिलान ओपनिंग ईवेंट से मापा जाता है, इसलिए यह `tool_result`, `hook_completed`, `agent_resume`, और `human_input` पर अस्वीकार किया जाता है। यह `model_response` पर स्वीकार किया जाता है, क्योंकि केवल आप असली प्रदाता विलंबता जानते हैं, और यह एक पूर्णांक होना चाहिए। - - थ्रेड ने कभी कॉन्टेक्स्ट को इन्हेरिट नहीं किया। कॉलेबल को `failproofai_sdk.propagate()` में रैप करें। [थ्रेड्स और async](#threads-and-async) को देखें। + + थ्रेड ने कभी संदर्भ को विरासत में नहीं दिया। कॉलेबल को `failproofai_sdk.propagate()` में लपेटें। [थ्रेड्स और async](#threads-and-async) देखें। - - एक्सट्रा फ़ील्ड्स आखिरी में मर्ज होती हैं, इसलिए `model` या `outcome` जैसी असली फ़ील्ड की तरह एक का नाम इसे ओवरराइट करेगा और एक स्टोर किए गए कॉलम को बदलेगा। अपने को नेमस्पेस दें; एडाप्टर्स एक `fw_` प्रीफिक्स का यूज़ करते हैं। + + अतिरिक्त फील्ड आखिरी में मर्ज होते हैं, इसलिए `model` या `outcome` जैसे वास्तविक फील्ड का नाम इसे अधिलेखित करेगा और एक संग्रहीत कॉलम बदल देगा। अपना नामस्थान; एडेप्टर एक `fw_` उपसर्ग का उपयोग करते हैं। - - `agent_id` एक लो-कार्डिनैलिटी फैसेट है और आपने एक रन आईडी को इसमें डाल दिया। एक रोल या नोड नाम का यूज़ करें और असली आईडी को एक पेलोड फ़ील्ड में डालें। + + `agent_id` कम-कार्डिनलिटी पहलू है और आपने एक रन id में डाल दिया। एक भूमिका या नोड नाम का उपयोग करें और असली id को एक पेलोड फील्ड में डालें। @@ -724,12 +726,12 @@ flowchart LR - जोड़े, आईडीज, सेशन लाइफसाइकल, और डिलीवरी। + जोड़ी, id, सेशन जीवनचक्र, और डिलीवरी। - - सेशन के माध्यम से कारण को फॉलो करें जिसे आपने अभी कैप्चर किया है। + + आपके द्वारा अभी कैप्चर किए गए सेशन के माध्यम से कारणात्मकता का पालन करें। - + LangGraph, CrewAI, LlamaIndex, और Pydantic AI। \ No newline at end of file diff --git a/docs/hi/start/quickstart.mdx b/docs/hi/start/quickstart.mdx index 2186108d..d7db1253 100644 --- a/docs/hi/start/quickstart.mdx +++ b/docs/hi/start/quickstart.mdx @@ -1,12 +1,12 @@ --- -title: "त्वरित शुरुआत" +title: "शुरुआत" description: "एक एजेंट सेशन कैप्चर करें, विफलता खोजें, और इसे रोकना शुरू करें।" icon: "zap" --- -यह त्वरित शुरुआत एक मशीन को सेशन रिपोर्ट करने के लिए तैयार करती है, एक ऑडिट चलाती है, और एक नीति तैनात करती है। Failproof AI को सेट अप करने के लिए स्किल का उपयोग करें, या मैनुअल चरणों का पालन करें। +यह शुरुआत एक मशीन को सेशन रिपोर्ट करने, ऑडिट चलाने और एक नीति तैनात करने के लिए सेट करती है। Failproof को सेट अप करने के लिए स्किल का उपयोग करें, या मैनुअल चरणों का पालन करें। -**आपका पथ कौन सा है?** यदि आपका एजेंट 12 समर्थित [harnesses](/hi/reference/harnesses) में से एक में चलता है — एक कोडिंग CLI, या Hermes या OpenClaw जैसा गेटवे — नीचे दिए गए चरणों का पालन करें; आपको Node.js 20.9 या बाद का संस्करण चाहिए। यदि आपके एजेंट के पास कोई harness नहीं है, तो ट्रेसिंग और ऑडिट के लिए इसे [Python SDK](/hi/reference/custom-agents) से जोड़ें, फिर [अपनी पहली विफलता जांच चलाएं](/hi/start/first-audit) पर वापस आएं; उस पथ पर enforcement के लिए आपके runtime में एक hook की आवश्यकता है। +**आपका रास्ता कौन सा है?** यदि आपका एजेंट 12 समर्थित [harnesses](/hi/reference/harnesses) में से एक में चलता है — एक कोडिंग CLI, या Hermes या OpenClaw जैसा गेटवे — नीचे दिए गए चरणों का पालन करें; आपको Node.js 20.9 या बाद का संस्करण चाहिए। यदि आपके एजेंट के पास कोई harness नहीं है, तो इसे ट्रेसिंग और ऑडिट के लिए [Python SDK](/hi/reference/custom-agents) से जोड़ें, फिर [अपनी पहली विफलता जांच चलाएं](/hi/start/first-audit) पर फिर से जुड़ें; उस पथ पर प्रवर्तन को आपके रनटाइम में एक हुक की आवश्यकता है। @@ -16,38 +16,44 @@ icon: "zap" npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - आपका एजेंट प्रोजेक्ट की जांच करता है, प्रासंगिक integration चुनता है, सेटअप करता है, और इसे सत्यापित करता है। व्यक्तिगत स्किल और उन्नत इंस्टॉलेशन विकल्पों के लिए [FailproofAI skills repository](https://github.com/FailproofAI/skills) देखें। + आपका एजेंट प्रोजेक्ट का निरीक्षण करता है, प्रासंगिक एकीकरण चुनता है, सेटअप करता है, और इसे सत्यापित करता है। व्यक्तिगत स्किल और उन्नत इंस्टॉलेशन विकल्पों के लिए [FailproofAI skills repository](https://github.com/FailproofAI/skills) देखें। ## शुरू करने से पहले -1. [Failproof AI dashboard](https://app.befailproof.ai) खोलें और एक खाता बनाएं या अपने कार्य ईमेल से साइन इन करें। -2. **Administration → Keys** पर जाएं और `events:add` और `policies:pull` के साथ एक key बनाएं। -3. एकबारगी secret को कॉपी करें और इसे target मशीन पर स्टोर करें: +1. [Failproof AI डैशबोर्ड](https://app.befailproof.ai) खोलें और अपना खाता बनाएं या अपने कार्य ईमेल से साइन इन करें। +2. **Administration → Keys** पर जाएं और `events:add` और `policies:pull` के साथ एक कुंजी बनाएं। +3. वन-टाइम सीक्रेट कॉपी करें, फिर इसे टार्गेट मशीन पर एक शेल में पढ़ें। `read -s` इसे एक प्रॉम्प्ट पर लेता है जो इको नहीं करता है, इसलिए यह कभी कमांड में दिखाई नहीं देता है: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## इंस्टॉल करें - + ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - सेशन transcript डिफ़ॉल्ट रूप से भेजे जाते हैं। Transcript सामग्री के बिना hook activity और policy decisions को रिपोर्ट करने के लिए `--no-transcripts` जोड़ें। + वह एक कमांड पूरे सेटअप का है: यह स्थानीय डेमॉन (root एक बार) को इंस्टॉल करता है, इसे हर एजेंट CLI में वायर करता है जो यह पाता है, और इस मशीन को Cloud से कनेक्ट करता है। कुंजी को `--token` की बजाय पर्यावरण के माध्यम से पास करने से यह `ps` में बाहर रहता है, जहां मशीन पर हर उपयोगकर्ता कमांड के तर्कों को पढ़ सकता है। यह इसे शेल हिस्ट्री से बाहर नहीं रखता है — `read -s` के साथ इसे पढ़ना है जो ऐसा करता है। CI में, इसे एक मास्क किए गए सीक्रेट के रूप में इंजेक्ट करें और शेल ट्रेसिंग (`set -x`) को बंद रखें, या ट्रेस इसे प्रिंट करेगा। - यदि इस मशीन के पास पहले से एजेंट history है, तो पिछले सात दिनों का पूर्वावलोकन करें और import करें, फिर delivery के पूरा होने की प्रतीक्षा करें। एक नई मशीन पर इस चरण को छोड़ें। + सेशन ट्रांसक्रिप्ट डिफ़ॉल्ट रूप से भेजे जाते हैं। ट्रांसक्रिप्ट सामग्री के बिना हुक गतिविधि और नीति निर्णय रिपोर्ट करने के लिए `--no-transcripts` जोड़ें। + + + यहां `failproofai config --connect ` के लिए हाथ न बढ़ाएं। वह फ्लैग एक मशीन को enroll करता है जो **पहले से** सेट अप है और सीधे लौटता है — कोई डेमॉन नहीं, कोई हुक नहीं — इसलिए मशीन Cloud में दिखाई देगी जबकि कुछ भी कलेक्ट और प्रवर्तित नहीं करेगी। + + + यदि इस मशीन के पास पहले से एजेंट हिस्ट्री है, तो पिछले सात दिनों को प्रीव्यू और इंपोर्ट करें, फिर डिलीवरी समाप्त होने का इंतजार करें। नई मशीन पर इस चरण को छोड़ें। ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +61,41 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Failproof AI में **Sessions** खोलें और एक import किए गए सेशन को चुनें। + Failproof AI में **Sessions** खोलें और एक आयात किया गया सेशन चुनें। - - यह Failproof AI को आपके harness से जोड़ता है और 39 built-in policies इंस्टॉल करता है। Failproof AI द्वारा आपके सेशन को ऑडिट करने और आपके एजेंट के लिए policies लिखने से पहले स्थानीय policy decisions को देखने और enforcement को आजमाने के लिए इनका उपयोग करें। - - Installer को अपने harness को detect करने दें, या एक को स्पष्ट रूप से नाम दें। 12 में से हर एक एक वैध `--cli` value है — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`। + + पिछले चरण ने पहले से हर एजेंट CLI को वायर कर दिया है जिसे यह पाया। जब आपको चाहिए तब एक harness के लिए स्पष्ट रूप से इसे फिर से चलाएं, या बाद में इंस्टॉल किए गए एक harness को जोड़ने के लिए। 12 में से हर एक एक वैध `--cli` मान है — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`। ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - एक tool call को चलने से पहले ब्लॉक करना सभी 12 पर सत्यापित है। Turn-end gates 8 पर सत्यापित हैं — [enforcement capability](/hi/reference/harnesses#enforcement-capability) के लिए per-harness matrix देखें। + एक टूल कॉल को इसे चलाने से पहले ब्लॉक करना सभी 12 पर सत्यापित है। टर्न-एंड गेट 8 पर सत्यापित हैं — प्रति-harness मैट्रिक्स के लिए [enforcement capability](/hi/reference/harnesses#enforcement-capability) देखें। + + + हुक वायर करना कोई नीति सक्षम नहीं करता है। सेटअप जानबूझकर कोई नहीं चुनता है — वह निर्णय आपका है — इसलिए एक पैक लें: + + ```bash + failproofai policies add FailproofAI/policies + ``` + + पैक को इसके GitHub रिलीज से लाया जाता है, चेकसम-सत्यापित, और सटीक टैग पर पिन किया जाता है जिस पर यह हल करता है। यह 38 नीतियों को ले जाता है और 10 को उन पर चालू करता है जिन्हें इसका मेनिफेस्ट बिना निगरानी के सक्षम करने के लिए सुरक्षित के रूप में चिह्नित करता है। उन्हें स्थानीय नीति निर्णय देखने और Failproof AI आपके सेशन ऑडिट करने और आपके एजेंट के लिए नीतियां लिखने से पहले प्रवर्तन का प्रयास करने के लिए उपयोग करें। + + `failproofai policies show /` के साथ किसी भी पैक को लेने से पहले पढ़ें, और [policy packs](/hi/policies/packs) के लिए केवल एक का हिस्सा लें देखें। + + जब तक यह नहीं चलता है, तब तक केवल `block-failproofai-commands` प्रवर्तित करने वाला है — हमेशा-चालू गार्ड जो एजेंट को Failproof AI बंद करने से रोकता है। `failproofai policies` सूचीबद्ध करता है कि क्या चालू है। - - [अपनी पहली विफलता जांच चलाएं](/hi/start/first-audit) का पालन करें। एक ठोस लक्ष्य का उपयोग करें जैसे "ऐसे सेशन खोजें जहां एजेंट ने विफल tool को अपना दृष्टिकोण बदले बिना फिर से आजमाया।" + + [अपनी पहली विफलता जांच चलाएं](/hi/start/first-audit) का पालन करें। एक ठोस लक्ष्य का उपयोग करें जैसे अपने दृष्टिकोण को बदले बिना विफल टूल को फिर से आजमाने वाले एजेंट के साथ सेशन खोजें। - [एक नीति के साथ अपनी पहली विफलता को रोकें](/hi/start/first-policy) का पालन करें। observe mode में शुरू करें, matches का निरीक्षण करें, फिर reviewed संस्करण को enforce करें। + [एक नीति के साथ अपनी पहली विफलता को रोकें](/hi/start/first-policy) का पालन करें। ऑब्जर्व मोड में शुरू करें, मिलान निरीक्षण करें, फिर समीक्षा किए गए संस्करण को प्रवर्तित करें। - `failproofai config --status` चलाएं। एक स्वस्थ सेटअप क्लाउड कनेक्शन, daemon state, और enforcement paused है या नहीं, यह रिपोर्ट करता है। + `failproofai config --status` चलाएं। एक स्वस्थ सेटअप क्लाउड कनेक्शन, डेमॉन स्थिति, और क्या प्रवर्तन को रोका गया है, रिपोर्ट करता है। \ No newline at end of file diff --git a/docs/hi/start/setup.mdx b/docs/hi/start/setup.mdx index 25c35f96..24882cdc 100644 --- a/docs/hi/start/setup.mdx +++ b/docs/hi/start/setup.mdx @@ -1,68 +1,89 @@ --- title: "अपना सेटअप चुनें" -description: "स्थानीय प्रवर्तन, Failproof AI Cloud, या एंटरप्राइज़ तैनाती चुनें।" +description: "स्थानीय प्रवर्तन, Failproof AI Cloud, या एंटरप्राइज़ परिनियोजन चुनें।" icon: "waypoints" --- - - एक मशीन पर हुक और नीतियां स्थापित करें। इसका उपयोग करें जब आपको सत्र डेटा को Cloud में भेजे बिना तुरंत सुरक्षा उपायों की आवश्यकता हो। + + एक मशीन को बिना Cloud key के सेट करें और एक policy pack लें। इसका उपयोग तब करें जब आपको तुरंत safeguards की आवश्यकता हो और session डेटा को Cloud में भेजना न हो। - केंद्रीकृत सत्र, ऑडिट, ऑनलाइन मूल्यांकन, डैशबोर्ड, अलर्ट और फ्लीट नीति तैनाती जोड़ें। + केंद्रीकृत sessions, audits, ऑनलाइन मूल्यांकन, डैशबोर्ड, alerts, और fleet policy परिनियोजन जोड़ें। - - संगठन नियंत्रण, स्कोप्ड कुंजियां, निजी बुनियादी ढांचा, और तैनाती-विशिष्ट सुरक्षा आवश्यकताओं का उपयोग करें। + + संगठन नियंत्रण, scoped keys, निजी infrastructure, और परिनियोजन-विशिष्ट सुरक्षा आवश्यकताओं का उपयोग करें। -## अनुशंसित उत्पादन पथ +## स्थानीय रूप से प्रवर्तन करें -1. ट्रांसक्रिप्ट कैप्चर सक्षम करके एक गैर-उत्पादन मशीन को कनेक्ट करें। -2. Cloud में सत्रों और मूल्यांकनों को सत्यापित करें। -3. एक ज्ञात विफलता मोड के लिए एक ऑडिट बनाएं। -4. पहली नीति को निरीक्षण मोड में तैनात करें। -5. मिलान और गलत सकारात्मकों की समीक्षा करने के बाद उत्पादन में विस्तार करें। +बिना key के `failproofai config` चलाएं, फिर `failproofai policies add FailproofAI/policies` के साथ एक pack लें। एक terminal में, जब setup Cloud से कनेक्ट करने के लिए कहे तो **Not now — stay local** चुनें; बिना terminal और बिना `FAILPROOFAI_CLOUD_TOKEN` के, यह अपने आप स्थानीय रहता है। daemon और hooks मशीन पर प्रवर्तन करते हैं, और कोई session डेटा Cloud को भेजा नहीं जाता। बाद में कनेक्ट करने के लिए, नीचे दिए गए चरणों का पालन करें। -## Cloud के साथ एक मशीन को कनेक्ट करें +## अनुशंसित production path + +1. transcript capture सक्षम के साथ एक non-production मशीन को कनेक्ट करें। +2. Cloud में sessions और मूल्यांकन सत्यापित करें। +3. एक ज्ञात failure mode के लिए एक audit बनाएं। +4. पहली policy को observe mode में परिनियोजित करें। +5. matches और false positives की समीक्षा करने के बाद production में विस्तार करें। + +## एक मशीन को Cloud से कनेक्ट करें - - 1. **Administration → Keys** पर जाएं और `events:add` और `policies:pull` के साथ एक कुंजी बनाएं। - 2. एकबारी गुप्त को लक्ष्य मशीन में कॉपी करें। + + 1. **Administration → Keys** पर जाएं और `events:add` और `policies:pull` के साथ एक key बनाएं। + 2. one-time secret को target मशीन पर कॉपी करें। 3. CLI कनेक्शन कमांड चलाने के बाद, **Admin → enforcement** पर जाएं और पुष्टि करें कि मशीन दिखाई देती है। - 4. **Observe → Events** पर जाएं और पुष्टि करें कि इसकी पहली घटना आती है। + 4. **Observe → Events** पर जाएं और पुष्टि करें कि इसकी पहली event पहुंचती है। - कुंजी ड्रॉअर कनेक्ट की गई मशीन के लिए आवश्यक दो अनुमतियां दिखाता है: ईवेंट अंतर्ग्रहण और नीति वितरण। + key drawer एक कनेक्ट की गई मशीन के लिए आवश्यक दो grants दिखाता है: event ingestion और policy delivery। - ![नई API कुंजी ड्रॉअर जिसका उपयोग ईवेंट अंतर्ग्रहण और नीति वितरण अनुमतियां देने के लिए किया जाता है।](/images/dashboard/key-create.png) + ![नई API key drawer जिसका उपयोग event ingestion और policy delivery permissions देने के लिए किया जाता है।](/images/dashboard/key-create.png) - कनेक्शन के बाद, मशीन enforcement में अपनी वांछित और रिपोर्ट की गई नीति स्थिति के साथ दिखाई देनी चाहिए। + कनेक्शन के बाद, मशीन enforcement में दिखाई देनी चाहिए जिसमें इसकी desired और reported policy state दिखाई दे। - ![Enforcement फ्लीट एक नामांकित मशीन के साथ विस्तृत है जो इसकी वांछित नीति स्थिति और तैनाती स्थिति दिखाती है।](/images/dashboard/enforcement-fleet.png) + ![Enforcement fleet एक enrolled मशीन के साथ विस्तृत है जो इसकी desired policy state और deployment status दिखाती है।](/images/dashboard/enforcement-fleet.png) - पहली आने वाली घटना की पुष्टि करती है कि daemon नीति तैनाती से स्वतंत्र रूप से Cloud को डेटा वितरित कर सकता है। + पहली arriving event पुष्टि करती है कि daemon Cloud को डेटा deliver कर सकता है, policy deployment से स्वतंत्र रूप से। - ![लाइव ईवेंट स्ट्रीम जो हाल की एजेंट, मॉडल और टूल घटनाएं दिखाती है।](/images/dashboard/events-stream-current.png) + ![लाइव event stream जो हाल के agent, model, और tool events दिखाता है।](/images/dashboard/events-stream-current.png) - केवल तब जारी रखें जब मशीन और इसकी पहली घटना दोनों दृश्यमान हों। + केवल तभी आगे बढ़ें जब मशीन और इसकी पहली event दोनों दिखाई दें। + one-time secret को shell में पढ़ें। `read -s` इसे एक ऐसे prompt पर लेता है जो echo नहीं करता, इसलिए यह कभी command में या shell history में नहीं दिखाई देता: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + फिर मशीन को सेट करें, इसकी policies चुनें, और इसे नाम दें: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` - जब ट्रांसक्रिप्ट सामग्री स्थानीय रहनी चाहिए तो `--no-transcripts` जोड़ें। + `failproofai config` पूरे सेटअप को करता है — daemon, हर agent CLI के लिए hooks जो यह पाता है, और Cloud connection — फिर कोई policies नहीं चुनता, जो दूसरी कमांड किसके लिए है। + + label कनेक्ट करने के **बाद** आता है, during नहीं: `failproofai config --machine-label ` एक मशीन का नाम बदलता है जो पहले से कनेक्ट है, और जो नहीं है उस पर यह केवल ऐसा कहता है। + + `--no-transcripts` जोड़ें जब transcript content को स्थानीय रहना चाहिए। + + CI में, `read -s` के बजाय secret store से `FAILPROOFAI_CLOUD_TOKEN` सेट करें, और shell tracing (`set -x`) को बंद रखें, या trace key को प्रिंट करता है। + + + एक मशीन पर जो **पहले से** सेट अप है, `failproofai config --connect ` इसे enrol करता है और कुछ नहीं। पहली install के लिए वह form का उपयोग न करें: यह daemon या किसी hook के स्थान पर लौटता है, एक मशीन छोड़ जाता है जो Cloud में दिखाई देती है लेकिन कुछ भी collect और enforce नहीं करती है। + -Cloud से कनेक्ट करने से ईवेंट अंतर्ग्रहण और नीति वितरण स्वतंत्र रूप से सत्यापित होते हैं। एक कुंजी इसलिए वैध हो सकती है लेकिन एक आवश्यक अनुमति गायब हो सकती है। यह देखने के लिए `failproofai config --status` का उपयोग करें कि कौन सी क्षमता कॉन्फ़िगर की गई है। +Cloud से कनेक्ट करना event ingestion और policy delivery को independently सत्यापित करता है। एक key इसलिए valid हो सकता है लेकिन एक आवश्यक permission missing हो सकता है। कौन सी capability configured है यह देखने के लिए `failproofai config --status` का उपयोग करें। - Cloud सेटअप स्थानीय क्रेडेंशियल केवल प्रासंगिक क्षमता सफल होने के बाद लिखता है। एक विफल सत्यापन मशीन को कनेक्ट दिखने नहीं देता जब यह नहीं है। + Cloud सेटअप स्थानीय credentials केवल तभी लिखता है जब relevant capability succeed हो। एक failed verification एक मशीन को कनेक्ट दिखते हुए नहीं छोड़ता जब यह नहीं है। \ No newline at end of file diff --git a/docs/i18n/README.ar.md b/docs/i18n/README.ar.md index 42561648..0b656ee7 100644 --- a/docs/i18n/README.ar.md +++ b/docs/i18n/README.ar.md @@ -22,27 +22,25 @@ **الترجمات:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**المراقبة والتنفيذ لكل مسار يعمل فيه عملاؤك.** -حيثما يعمل عملاؤك، نراهم — وبإمكاننا الرفض. يربط Failproof 12 مسارًا للعملاء — واجهات سطر أوامر الترميز مثل Claude Code و Codex، بوابات الدردشة مثل Hermes، والمساعدات ذاتية الاستضافة مثل OpenClaw — ويلتقط كل تشغيل ويحجب استدعاءات الأدوات الخطيرة قبل تنفيذها. 39 سياسة مضمنة. بدون تأخير. يعمل محليًا. +**المراقبة والفرض لكل بيئة تشغيل يعمل فيها الوكلاء الذكيون.** أينما يعمل وكلاؤك، نحن نراها — ويمكننا الرفض. يتصل Failproof بـ 12 بيئة تشغيل لوكلاء — واجهات سطر أوامر لكتابة الأكواد مثل Claude Code و Codex، بوابات الدردشة مثل Hermes، المساعدات المستضافة ذاتياً مثل OpenClaw — حيث نلتقط كل تشغيل ونمنع استدعاءات الأدوات الخطيرة قبل تنفيذها. 39 سياسة مدمجة. لا توجد زمن انتظار. يعمل محلياً.

- Failproof AI in action + Failproof AI في العمل

--- -## المسارات المدعومة +## بيئات التشغيل المدعومة -اثنا عشر مسارًا في فئتين — عشر واجهات سطر أوامر ترميز، وبوابتان للدردشة والمساعدات (Hermes، OpenClaw). نفس الأحداث، نفس السياسات، نفس سجل الجلسة، أيًا كان المسار الذي يعمل فيه عملاؤك. +اثنتا عشرة بيئة تشغيل في فئتين — عشر واجهات سطر أوامر لكتابة الأكواد، واثنتا بوابات دردشة ومساعدات (Hermes و OpenClaw). واجهة برمجية واحدة للسياسات وسجل جلسة واحد في جميع الأنحاء. ما يمكن لسياسة *منعه* يختلف حسب البيئة: إيقاف استدعاء أداة قبل تشغيله يتم التحقق منه في جميع الاثنتي عشرة، أبواب نهاية المحادثة في ثمانية. تُدرج [مصفوفة البيئات](https://docs.befailproof.ai/reference/harnesses#enforcement-capability) الأحداث التي يحترمها كل منها. -العملاء الذين لا يعملون في أي منها يقدمون تقارير من خلال [SDK Python](https://docs.befailproof.ai/reference/custom-agents)، -والذي يوفر لك التتبع والجلسات والتدقيق. يحتاج التنفيذ هناك إلى ربط في وقت التشغيل الخاص بك — [تحدث إلينا](mailto:support@befailproof.ai) وسنقوم بتعيينها. +الوكلاء الذين يعملون في لا أحد منها يبلغون من خلال [Python SDK](https://docs.befailproof.ai/reference/custom-agents)، والذي يعطيك التتبع والجلسات والتدقيق. يتطلب الفرض هناك خطاف في وقت التشغيل الخاص بك — [تحدث معنا](mailto:support@befailproof.ai) وسنقوم بتعيينه. -{/* A 6-column table instead of inline runs: table columns never re-wrap, - so the grid stays 2×6 at any window width (scrolling on very narrow screens - instead of collapsing into ragged orphan rows). */} +{/* جدول بـ 6 أعمدة بدلاً من مضمنة: أعمدة الجدول لا تعاد التفاف أبداً، + لذا تبقى الشبكة 2×6 بأي عرض نافذة (التمرير على الشاشات الضيقة جداً + بدلاً من الانهيار إلى صفوف يتيمة غير منتظمة). */}
@@ -138,37 +136,39 @@ ```sh npm install -g failproofai -failproofai policies --install -failproofai +failproofai config # قم بتوصيل وكلاؤك والقسم +failproofai policies add FailproofAI/policies # اختر ما يجب فرضه +failproofai # لوحة التحكم على localhost:8020 ``` -تتفعل 39 سياسة مضمنة على الفور. لوحة التحكم في `localhost:8020`. عطّل موجه التشغيل الأول باستخدام `FAILPROOFAI_NO_FIRST_RUN=1`. +يقوم الإعداد بتوصيل الخطافات واختيار **لا أحد** من السياسات — هذا الأمر الثاني هو ما يضع حراسات على الجهاز، وأي مجموعة يتم كتابتها بنفس الطريقة (`failproofai policies add /`؛ `policies show /` يقرأ واحدة أولاً). قم بتشغيل `failproofai config` بدون محطة — CI، حاوية، وكيل يقودها — وتطبق بدلاً من السؤال. على جهاز لم يتم إعداده أبداً، أي أمر آخر يقوم بتشغيل نفس المعالج أولاً؛ عطّله باستخدام `FAILPROOFAI_NO_FIRST_RUN=1`. + +حتى تصل مجموعة، الشيء الوحيد الذي يفرضه هو `block-failproofai-commands`، وهو يعمل دائماً ولا يمكن إيقافه أو إيقافه مؤقتاً: وكيل يمكنه إيقاف الفرض يمكنه إيقاف كل سياسة أخرى. --- -## ما الذي يوقفه +## ما يتم إيقافه -| السياسة | ما يحجبه | +| السياسة | ما يتم منعه | |---|---| -| `sanitize-api-keys` | مفاتيح API تتسرب إلى سياق العميل | -| `block-env-files` | قراءات ملفات `.env` والملفات السرية الأخرى | -| `warn-repeated-tool-calls` | العميل يحلق على نفس الاستدعاء | +| `block-env-files` | قراءة ملفات `.env` والملفات السرية الأخرى | +| `warn-repeated-tool-calls` | الوكيل الذي ينقر على نفس الاستدعاء | | `block-sudo` | تصعيد الامتيازات | -| `warn-destructive-sql` | `DROP`، `TRUNCATE`، `DELETE` غير المحددة | -| `block-terraform` / `block-kubectl` | تغييرات غير مراجعة للبنية التحتية المباشرة | -| `block-rm-rf` | حذف الملفات العودي | -| `block-force-push` / `block-push-master` | `git push --force`، الدفع المباشر إلى `main` | +| `warn-destructive-sql` | `DROP`، `TRUNCATE`، `DELETE` غير محدود | +| `block-terraform` / `block-kubectl` | التغييرات غير المراجعة على البنية التحتية المباشرة | +| `block-rm-rf` | حذف ملفات متكرر | +| `block-force-push` / `block-push-master` | `git push --force`، دفع مباشر إلى `main` | -الخمسة الأولى تنطبق على أي عميل يمكنه استدعاء أداة. الثلاثة الأخيرة هي المفضلة لدى المطورين — واجهات سطر أوامر الترميز هي فئة المسار التي نغطيها بعمق. +كل واحد منها يوقف الاستدعاء *قبل* تشغيله، لذا فهو يعمل في جميع الاثنتي عشرة بيئات تشغيل. الأربعة الأولى تنطبق على أي وكيل يمكنه استدعاء أداة؛ الثلاثة الأخيرة هي المفضلة للمطورين — واجهات سطر أوامر الكتابة هي فئة البيئات التي نغطيها بعمق. أسرة `sanitize-*` منفصلة: فهي تعمل بعد عودة الأداة، لذا تبلغ عن سر في إخراج الأداة بدلاً من إبقاؤه بعيداً عن السياق. -→ [جميع السياسات المدمجة 39](https://docs.befailproof.ai/policies/builtin) +→ [جميع 39 سياسة مدمجة](https://docs.befailproof.ai/policies/packs) --- ## سياساتك الخاصة -ضع ملفًا في `.failproofai/policies/` — يتم تحميله تلقائيًا، لا توجد علامات مطلوبة. -التزم به وسيحصل الفريق بأكمله عليه عند السحب التالي. +أسقط ملف في `.failproofai/policies/` — يتم تحميله تلقائياً، بدون أعلام مطلوبة. +تعهد بها والفريق بأكمله يحصل عليها في السحب التالي. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -189,78 +189,74 @@ customPolicies.add({ | القرار | التأثير | |---|---| | `allow()` | السماح بالعملية | -| `deny(message)` | حجبها — تعود الرسالة إلى العميل | -| `instruct(message)` | السماح لها بالمرور، لكن إضافة سياق إلى موجه العميل التالي | +| `deny(message)` | منعها — الرسالة تعود إلى الوكيل | +| `instruct(message)` | السماح بها، لكن أضف سياقاً إلى طلب الوكيل التالي | -→ [دليل السياسات المخصصة](https://docs.befailproof.ai/policies/custom) +→ [اكتب سياسة](https://docs.befailproof.ai/policies/editor) --- ## المراقبة -التنفيذ هو نصف الطريق. النصف الآخر هو رؤية ما فعله العميل فعلاً. +الفرض هو نصف. النصف الآخر هو معرفة ما فعله الوكيل فعلاً. -شغّل `failproofai` بدون معاملات وسيخدم لوحة تحكم على `localhost:8020` -قارئًا سجل التشغيل الموجود بالفعل على جهازك — بدون حساب، بدون تسجيل، لا شيء يترك الصندوق. تحصل على قائمة الجلسة، تسلسل استدعاءات النموذج، استدعاءات الأدوات وقرارات الربط داخل كل تشغيل، ما تم حجبه وما قالته السياسة للعميل، وتدقيق دون اتصال (`failproofai audit`) يفحص سجلك عن أنماط محفوفة بالمخاطر ويقترح سياسات لإيقافها. +قم بتشغيل `failproofai` بدون وسائط وسيخدم لوحة تحكم على `localhost:8020` يقرأ سجل التشغيل الموجود بالفعل على جهازك — بدون حساب، بدون التسجيل، لا شيء يترك الصندوق. تحصل على قائمة الجلسات، وتسلسل استدعاءات النموذج، واستدعاءات الأدوات وقرارات الخطاف داخل كل تشغيل، ما تم منعه وما قالت السياسة للوكيل، وتدقيق غير متصل (`failproofai audit`) الذي يمسح السجل الخاص بك بحثاً عن أنماط محفوفة بالمخاطر ويقترح سياسات لإيقافها. → [لوحة التحكم المحلية](https://docs.befailproof.ai/reference/local-dashboard) · [قراءة تتبع](https://docs.befailproof.ai/sessions/read-a-trace) · [التدقيق المحلي](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** هي الجانب المستضاف من نفس نموذج البيانات، للفرق -التي تشغل العملاء عبر أسطول: كل تشغيل من كل مسار في مكان واحد، رسم بياني للتنفيذ مع العملاء الفرعيين المتوازيين على مساراتهم الخاصة، زمن الكمون p50/p95/p99 -للنماذج والأدوات والربطات، تتبع التكلفة لكل نموذج وتتبع نافذة السياق، تتبع الأخطاء، SQL على تتبعاتك الخاصة مع لوحات تحكم قابلة للمشاركة، التقييمات المسجلة من قبل خدمتك الخاصة، التدقيق المجدول الذي يحول الأعطال المتكررة إلى نتائج مدعومة بالأدلة، والتنبيهات الموجهة إلى Slack أو البريد الإلكتروني أو webhook موقّع. الاستضافة الذاتية في مجموعتك الخاصة متاحة في خطة Enterprise. +**Failproof AI Observability** هي الجانب المستضاف من نفس نموذج البيانات، للفرق التي تشغل وكلاء عبر أسطول: كل تشغيل من كل بيئة تشغيل في مكان واحد، رسم بياني للتنفيذ مع وكلاء فرعيين متوازيين على مسارات خاصة بهم، زمن انتظار p50/p95/p99 للنماذج والأدوات والخطافات، تكلفة لكل نموذج وتتبع نافذة السياق، تتبع الأخطاء، SQL على أثارك الخاصة مع لوحات تحكم قابلة للمشاركة، التقييمات المسجلة من قبل خدمتك الخاصة، التدقيق المجدول الذي يحول الإخفاقات المتكررة إلى نتائج مدعومة بالأدلة، والتنبيهات الموجهة إلى Slack أو البريد الإلكتروني أو webhook موقعة. الاستضافة الذاتية في مجموعتك الخاصة متاحة على خطة Enterprise. → [الجلسات](https://docs.befailproof.ai/sessions/overview) · [التدقيق](https://docs.befailproof.ai/audits/overview) · -[احجز عرضًا توضيحيًا](https://befailproof.ai/get-a-demo) +[احجز عرضاً توضيحياً](https://befailproof.ai/get-a-demo) --- -## التوثيق +## الوثائق -| البدء | | +| ابدأ | | |---|---| -| [البدء السريع](https://docs.befailproof.ai/start/quickstart) | التثبيت، توصيل مسار، رؤية التشغيل الأول | -| [المفاهيم](https://docs.befailproof.ai/start/concepts) | كيفية عمل نظام الربط | -| [المسارات المدعومة](https://docs.befailproof.ai/reference/harnesses) | الـ 12 جميعًا، وما يمكن لكل منها تنفيذه | +| [البداية السريعة](https://docs.befailproof.ai/start/quickstart) | قم بالتثبيت، وقم بتوصيل بيئة تشغيل، وشاهد أول تشغيل | +| [المفاهيم](https://docs.befailproof.ai/start/concepts) | كيفية عمل نظام الخطاف | +| [بيئات التشغيل المدعومة](https://docs.befailproof.ai/reference/harnesses) | جميع 12، وما يمكن لكل واحدة أن تفرضه | -| المراقبة | | +| لاحظ | | |---|---| -| [الجلسات](https://docs.befailproof.ai/sessions/overview) | متابعة تشغيل: النماذج والأدوات والأخطاء وزمن الكمون | -| [قراءة تتبع](https://docs.befailproof.ai/sessions/read-a-trace) | ما يخبرك به رسم البياني للتنفيذ | -| [التدقيق](https://docs.befailproof.ai/audits/overview) | البحث عن أنماط الأعطال عبر جلسات متعددة | -| [لوحة التحكم المحلية](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`، لا حاجة لحساب | +| [الجلسات](https://docs.befailproof.ai/sessions/overview) | اتبع التشغيل: النماذج والأدوات والأخطاء وزمن الانتظار | +| [قراءة تتبع](https://docs.befailproof.ai/sessions/read-a-trace) | ما يخبرك به رسم البياني التنفيذي | +| [التدقيق](https://docs.befailproof.ai/audits/overview) | ابحث عن أنماط الفشل عبر جلسات عديدة | +| [لوحة التحكم المحلية](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`، لا يتطلب حساباً | -| التنفيذ | | +| فرض | | |---|---| -| [السياسات المدمجة](https://docs.befailproof.ai/policies/builtin) | جميع السياسات 39 مع المعاملات | -| [السياسات المخصصة](https://docs.befailproof.ai/policies/custom) | اكتب الخاصة بك | -| [التكوين](https://docs.befailproof.ai/policies/local-configuration) | نطاقات التكوين وقواعد الدمج | +| [مجموعات السياسات](https://docs.befailproof.ai/policies/packs) | سياسات Failproof AI، والمجموعات من مركز السياسات | +| [اكتب سياسة](https://docs.befailproof.ai/policies/editor) | من التدقيق، أو في الكود | +| [الإعدادات](https://docs.befailproof.ai/policies/local-configuration) | نطاقات التكوين وقواعد الدمج ومعاملات السياسة | -| جهز عميلك الخاص | | +| أدخل وكيلك الخاص | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | الإبلاغ عن التشغيل من عميل بدون مسار | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` مرجع | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | الإبلاغ عن عمليات من وكيل بدون بيئة تشغيل | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | مرجع `allow` / `deny` / `instruct` | --- ## الترخيص -MIT مع [Commons Clause](https://commonsclause.com/) — مجاني للاستخدام الداخلي والشخصي؛ إعادة بيع failproofai نفسه تجاريًا يتطلب اتفاقية منفصلة. انظر [LICENSE](../../LICENSE) للنص الكامل. +MIT مع [Commons Clause](https://commonsclause.com/) — مجاني للاستخدام الداخلي والشخصي؛ إعادة البيع التجاري لـ failproofai نفسه تتطلب اتفاقية منفصلة. انظر [LICENSE](../../LICENSE) للنص الكامل. --- ## المساهمة -انظر [CONTRIBUTING.md](../../CONTRIBUTING.md). السياسات الجديدة والحالات الحدية والترجمات جميعها مرحب بها. +انظر [CONTRIBUTING.md](../../CONTRIBUTING.md). السياسات الجديدة والحالات الحدودية والترجمات جميعها موضع ترحيب. -> **بناء قبل أن تبدأ.** شغّل `bun install && bun run build` أولاً. يقوم هذا المستودع بتشغيل ربطات failproofai الخاصة به على نفسه، وهي تحل استيراد `failproofai` مقابل حزمة `dist/` المترجمة — بدون بناء، ستواجه أخطاء ربط `Cannot find package 'failproofai'`. أعد البناء بعد تغيير `src/`. انظر -> [البناء قبل أن تعمل ربطات dev المحلية في المستودع](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **قم بالبناء قبل أن تبدأ.** قم بتشغيل `bun install && bun run build` أولاً. يقوم هذا الريبو بتشغيل خطافات failproofai الخاصة به على نفسه، ويحل `failproofai` المستورد مقابل `dist/` المترجم — بدون بناء ستصل إلى أخطاء خطاف `Cannot find package 'failproofai'`. أعد البناء بعد تغيير `src/`. انظر [البناء قبل أن تعمل خطافات dev في الريبو](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -تم البناء بـ ❤️ بواسطة [befailproof.ai](https://befailproof.ai) في سان فرانسيسكو وبنغالور. +تم البناء بـ ❤️ بواسطة [befailproof.ai](https://befailproof.ai) في SF و Bengaluru. \ No newline at end of file diff --git a/docs/i18n/README.de.md b/docs/i18n/README.de.md index a5fec5be..346a3fdc 100644 --- a/docs/i18n/README.de.md +++ b/docs/i18n/README.de.md @@ -20,8 +20,8 @@ **Übersetzungen:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Observability und Durchsetzung für jeden Harness, in dem deine Agenten laufen.** -Egal wo deine Agenten ausgeführt werden – wir sehen es und können eingreifen. Failproof bindet sich in 12 Agent-Harnesses ein – Coding-CLIs wie Claude Code und Codex, Chat-Gateways wie Hermes, selbst gehostete Assistenten wie OpenClaw – erfasst jeden Lauf und blockiert gefährliche Tool-Aufrufe, bevor sie ausgeführt werden. 39 eingebaute Richtlinien. Keine Latenz. Läuft lokal. +**Observability und Durchsetzung für jede Umgebung, in der deine Agenten laufen.** +Egal wo deine Agenten ausgeführt werden – wir sehen es und können eingreifen. Failproof bindet sich in 12 Agent-Harnesses ein: Coding-CLIs wie Claude Code und Codex, Chat-Gateways wie Hermes, selbstgehostete Assistenten wie OpenClaw – erfasst jeden Lauf und blockiert gefährliche Tool-Aufrufe, bevor sie ausgeführt werden. 39 integrierte Richtlinien. Null Latenz. Läuft lokal. @@ -33,9 +33,12 @@ Egal wo deine Agenten ausgeführt werden – wir sehen es und können eingreifen ## Unterstützte Harnesses -Zwölf Harnesses in zwei Klassen – zehn Coding-CLIs und zwei Chat- und Assistenz-Gateways (Hermes, OpenClaw). Gleiche Events, gleiche Richtlinien, gleiche Session-Historie – egal in welchem dein Agent läuft. +Zwölf Harnesses in zwei Klassen – zehn Coding-CLIs und zwei Chat- und Assistenten-Gateways (Hermes, OpenClaw). Eine einheitliche Policy-API und eine gemeinsame Sitzungshistorie für alle. Was eine Richtlinie *blockieren* kann, ist harness-spezifisch: Das Stoppen eines Tool-Aufrufs vor seiner Ausführung ist auf allen zwölf verifiziert, Gesprächsende-Gates auf acht. Die +[harness-spezifische Matrix](https://docs.befailproof.ai/reference/harnesses#enforcement-capability) +listet die Ereignisse auf, die jeder Harness berücksichtigt. -Agenten, die in keinem davon laufen, melden sich über das [Python SDK](https://docs.befailproof.ai/reference/custom-agents), das dir Tracing, Sessions und Audits bietet. Für die Durchsetzung dort ist ein Hook in deiner eigenen Runtime nötig – [kontaktiere uns](mailto:support@befailproof.ai), und wir erarbeiten gemeinsam eine Lösung. +Agenten, die in keinem davon laufen, berichten über das [Python SDK](https://docs.befailproof.ai/reference/custom-agents), +das Tracing, Sitzungen und Audits bietet. Durchsetzung dort erfordert einen Hook in deiner eigenen Laufzeitumgebung – [sprich uns an](mailto:support@befailproof.ai) und wir finden gemeinsam eine Lösung. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,36 +138,40 @@ Agenten, die in keinem davon laufen, melden sich über das [Python SDK](https:// ```sh npm install -g failproofai -failproofai policies --install # oder einfach `failproofai` ausführen und die Erststart-Abfrage bestätigen -failproofai +failproofai config # wire up your agents and the daemon +failproofai policies add FailproofAI/policies # choose what to enforce +failproofai # dashboard on localhost:8020 ``` -39 eingebaute Richtlinien werden sofort aktiv. Dashboard unter `localhost:8020`. Die Erststart-Abfrage lässt sich mit `FAILPROOFAI_NO_FIRST_RUN=1` deaktivieren. +Die Einrichtung verbindet die Hooks und wählt **keine** Richtlinien aus – der zweite Befehl ist es, der Leitplanken auf dem Rechner aktiviert. Jedes Paket wird auf dieselbe Weise angegeben +(`failproofai policies add /`; `policies show /` zeigt zunächst eines an). Führe `failproofai config` ohne Terminal aus – in CI, einem Container oder einem steuernden Agenten – und es wird direkt angewendet, ohne Rückfragen. Auf einem noch nicht eingerichteten Rechner führt jeder andere Befehl zunächst denselben Einrichtungsassistenten aus; deaktiviere das mit `FAILPROOFAI_NO_FIRST_RUN=1`. + +Solange kein Paket geladen ist, ist lediglich `block-failproofai-commands` aktiv – diese Richtlinie ist immer eingeschaltet und kann weder deaktiviert noch pausiert werden: Ein Agent, der die Durchsetzung pausieren kann, könnte sonst jede andere Richtlinie abschalten. --- ## Was blockiert wird -| Richtlinie | Was sie verhindert | +| Richtlinie | Was sie blockiert | |---|---| -| `sanitize-api-keys` | API-Schlüssel, die in den Kontext des Agenten gelangen | -| `block-env-files` | Lesezugriffe auf `.env`-Dateien und andere Secret-Dateien | +| `block-env-files` | Lesezugriffe auf `.env` und andere Secret-Dateien | | `warn-repeated-tool-calls` | Endlosschleifen des Agenten beim selben Aufruf | -| `block-sudo` | Privilege-Escalation | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, uneingeschränkte `DELETE`-Statements | +| `block-sudo` | Privilege Escalation | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, uneingeschränkte `DELETE`-Anweisungen | | `block-terraform` / `block-kubectl` | Ungeprüfte Änderungen an Live-Infrastruktur | | `block-rm-rf` | Rekursives Löschen von Dateien | | `block-force-push` / `block-push-master` | `git push --force`, direkte Pushes nach `main` | -Die ersten fünf gelten für jeden Agenten, der Tools aufrufen kann. Die letzten drei sind die Favoriten unter Entwicklern – Coding-CLIs sind die Harness-Klasse, die wir am tiefsten abdecken. +Alle diese Schranken greifen *vor* der Ausführung des Aufrufs – sie gelten daher für alle zwölf Harnesses. Die ersten vier wirken auf jeden Agenten, der Tools aufrufen kann; die letzten drei sind die Favoriten unter Entwicklern – Coding-CLIs sind die Harness-Klasse, die wir am tiefsten abdecken. Die `sanitize-*`-Familie ist separat: Sie läuft nach der Rückgabe eines Tools und meldet ein Secret in der Tool-Ausgabe, anstatt es aus dem Kontext fernzuhalten. -→ [Alle 39 eingebauten Richtlinien](https://docs.befailproof.ai/policies/builtin) +→ [Alle 39 integrierten Richtlinien](https://docs.befailproof.ai/policies/packs) --- ## Eigene Richtlinien -Lege eine Datei in `.failproofai/policies/` ab – sie wird automatisch geladen, ohne zusätzliche Flags. Commit sie ins Repository, und das gesamte Team erhält sie beim nächsten Pull. +Lege eine Datei in `.failproofai/policies/` ab – sie wird automatisch geladen, ohne weitere Flags. +Commit sie und das gesamte Team erhält sie beim nächsten Pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -180,15 +187,15 @@ customPolicies.add({ }); ``` -Jede Richtlinie hat drei mögliche Entscheidungen: +Jeder Richtlinie stehen drei Entscheidungen zur Verfügung: | Entscheidung | Wirkung | |---|---| -| `allow()` | Vorgang erlauben | -| `deny(message)` | Blockieren – die Nachricht wird an den Agenten zurückgegeben | +| `allow()` | Operation erlauben | +| `deny(message)` | Blockieren – die Nachricht geht zurück an den Agenten | | `instruct(message)` | Durchlassen, aber dem nächsten Prompt des Agenten Kontext hinzufügen | -→ [Anleitung für eigene Richtlinien](https://docs.befailproof.ai/policies/custom) +→ [Richtlinie schreiben](https://docs.befailproof.ai/policies/editor) --- @@ -196,15 +203,17 @@ Jede Richtlinie hat drei mögliche Entscheidungen: Durchsetzung ist die eine Hälfte. Die andere Hälfte ist zu sehen, was der Agent tatsächlich getan hat. -Starte `failproofai` ohne Argumente, und es stellt ein Dashboard unter `localhost:8020` bereit, das die bereits auf deinem Rechner vorhandene Verlaufshistorie liest – kein Konto, keine Registrierung, nichts verlässt den Rechner. Du erhältst die Session-Liste, die Abfolge von Modell-Aufrufen, Tool-Aufrufen und Hook-Entscheidungen innerhalb jedes Laufs, was blockiert wurde und was die Richtlinie dem Agenten mitgeteilt hat, sowie ein Offline-Audit (`failproofai audit`), das deinen Verlauf auf riskante Muster durchsucht und Richtlinien vorschlägt, um diese zu unterbinden. +Führe `failproofai` ohne Argumente aus und es startet ein Dashboard unter `localhost:8020`, +das die bereits auf deinem Rechner gespeicherte Ausführungshistorie liest – kein Konto, keine Registrierung, nichts verlässt das Gerät. Du erhältst die Sitzungsliste, die Abfolge von Modellaufrufen, Tool-Aufrufen und Hook-Entscheidungen innerhalb jedes Laufs, was blockiert wurde und was die Richtlinie dem Agenten mitgeteilt hat, sowie ein Offline-Audit (`failproofai audit`), das deine Historie auf riskante Muster scannt und Richtlinien vorschlägt, um sie zu unterbinden. → [Lokales Dashboard](https://docs.befailproof.ai/reference/local-dashboard) · [Einen Trace lesen](https://docs.befailproof.ai/sessions/read-a-trace) · [Lokales Audit](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** ist die gehostete Seite desselben Datenmodells – für Teams, die Agenten über eine ganze Flotte hinweg betreiben: alle Läufe aller Harnesses an einem Ort, ein Ausführungsgraph mit parallelen Sub-Agenten auf eigenen Spuren, p50/p95/p99-Latenzen für Modelle, Tools und Hooks, modellbezogene Kosten- und Context-Window-Verfolgung, Fehlerverfolgung, SQL über eigene Traces mit teilbaren Dashboards, Evaluierungen bewertet durch deinen eigenen Service, geplante Audits, die wiederkehrende Fehler in belegbare Erkenntnisse umwandeln, sowie Benachrichtigungen über Slack, E-Mail oder einen signierten Webhook. Self-Hosting im eigenen Cluster ist im Enterprise-Plan verfügbar. +**Failproof AI Observability** ist die gehostete Seite desselben Datenmodells, für Teams, +die Agenten auf einer ganzen Flotte betreiben: Jeder Lauf aus jedem Harness an einem Ort, ein Ausführungsgraph mit parallelen Sub-Agenten auf eigenen Spuren, p50/p95/p99-Latenz für Modelle, Tools und Hooks, modellbezogene Kosten- und Kontextfenster-Verfolgung, Fehler-Tracking, SQL über deine eigenen Traces mit teilbaren Dashboards, Auswertungen durch deinen eigenen Dienst bewertet, geplante Audits, die wiederkehrende Fehler in belegbare Erkenntnisse umwandeln, und Benachrichtigungen an Slack, E-Mail oder einen signierten Webhook. Self-Hosting im eigenen Cluster ist im Enterprise-Plan verfügbar. -→ [Sessions](https://docs.befailproof.ai/sessions/overview) · +→ [Sitzungen](https://docs.befailproof.ai/sessions/overview) · [Audits](https://docs.befailproof.ai/audits/overview) · [Demo buchen](https://befailproof.ai/get-a-demo) @@ -214,22 +223,22 @@ Starte `failproofai` ohne Argumente, und es stellt ein Dashboard unter `localhos | Einstieg | | |---|---| -| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Installieren, einen Harness verbinden, den ersten Lauf beobachten | +| [Schnellstart](https://docs.befailproof.ai/start/quickstart) | Installieren, Harness verbinden, ersten Lauf ansehen | | [Konzepte](https://docs.befailproof.ai/start/concepts) | Wie das Hook-System funktioniert | -| [Unterstützte Harnesses](https://docs.befailproof.ai/reference/harnesses) | Alle 12 und was jeder davon durchsetzen kann | +| [Unterstützte Harnesses](https://docs.befailproof.ai/reference/harnesses) | Alle 12 und was jeder durchsetzen kann | | Beobachten | | |---|---| -| [Sessions](https://docs.befailproof.ai/sessions/overview) | Einen Lauf verfolgen: Modelle, Tools, Fehler, Latenzen | -| [Einen Trace lesen](https://docs.befailproof.ai/sessions/read-a-trace) | Was der Ausführungsgraph dir mitteilt | -| [Audits](https://docs.befailproof.ai/audits/overview) | Fehlermuster über viele Sessions hinweg aufdecken | +| [Sitzungen](https://docs.befailproof.ai/sessions/overview) | Einen Lauf verfolgen: Modelle, Tools, Fehler, Latenz | +| [Einen Trace lesen](https://docs.befailproof.ai/sessions/read-a-trace) | Was der Ausführungsgraph aussagt | +| [Audits](https://docs.befailproof.ai/audits/overview) | Fehlermuster über viele Sitzungen hinweg finden | | [Lokales Dashboard](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, kein Konto erforderlich | | Durchsetzen | | |---|---| -| [Eingebaute Richtlinien](https://docs.befailproof.ai/policies/builtin) | Alle 39 Richtlinien mit Parametern | -| [Eigene Richtlinien](https://docs.befailproof.ai/policies/custom) | Eigene schreiben | -| [Konfiguration](https://docs.befailproof.ai/policies/local-configuration) | Konfigurations-Scopes und Merge-Regeln | +| [Richtlinienpakete](https://docs.befailproof.ai/policies/packs) | Die Failproof AI-Richtlinien und Pakete aus dem Policy Hub | +| [Richtlinie schreiben](https://docs.befailproof.ai/policies/editor) | Aus einem Audit oder im Code | +| [Konfiguration](https://docs.befailproof.ai/policies/local-configuration) | Konfigurationsbereiche, Zusammenführungsregeln und Richtlinienparameter | | Eigenen Agenten instrumentieren | | |---|---| @@ -240,7 +249,7 @@ Starte `failproofai` ohne Argumente, und es stellt ein Dashboard unter `localhos ## Lizenz -MIT mit [Commons Clause](https://commonsclause.com/) – kostenlos für den internen und privaten Gebrauch; der kommerzielle Weiterverkauf von failproofai selbst erfordert eine gesonderte Vereinbarung. Den vollständigen Text findest du in [LICENSE](../../LICENSE). +MIT mit [Commons Clause](https://commonsclause.com/) – kostenlos für den internen und privaten Gebrauch; der kommerzielle Weiterverkauf von failproofai selbst erfordert eine separate Vereinbarung. Den vollständigen Text findest du unter [LICENSE](../../LICENSE). --- @@ -248,7 +257,7 @@ MIT mit [Commons Clause](https://commonsclause.com/) – kostenlos für den inte Siehe [CONTRIBUTING.md](../../CONTRIBUTING.md). Neue Richtlinien, Randfälle und Übersetzungen sind herzlich willkommen. -> **Erst bauen, dann starten.** Führe zuerst `bun install && bun run build` aus. Dieses Repository führt failproofais eigene Hooks auf sich selbst aus, und diese lösen den `failproofai`-Import gegen das kompilierte `dist/`-Bundle auf – ohne einen Build erhältst du `Cannot find package 'failproofai'`-Hook-Fehler. Nach Änderungen an `src/` neu bauen. Siehe +> **Vor dem Start bauen.** Führe zuerst `bun install && bun run build` aus. Dieses Repository wendet failproofais eigene Hooks auf sich selbst an, und diese lösen den `failproofai`-Import gegen das kompilierte `dist/`-Bundle auf – ohne einen Build erhältst du `Cannot find package 'failproofai'`-Hook-Fehler. Nach Änderungen an `src/` neu bauen. Siehe > [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md index cefff72f..7e8820cc 100644 --- a/docs/i18n/README.es.md +++ b/docs/i18n/README.es.md @@ -20,8 +20,8 @@ **Traducciones:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Observabilidad y control de cumplimiento para cada entorno en el que corren tus agentes.** -Donde sea que ejecuten tus agentes, nosotros lo vemos — y podemos decir que no. Failproof engancha 12 entornos de agentes — CLIs de programación como Claude Code y Codex, pasarelas de chat como Hermes, asistentes autoalojados como OpenClaw — capturando cada ejecución y bloqueando llamadas a herramientas peligrosas antes de que se ejecuten. 39 políticas integradas. Sin latencia. Corre localmente. +**Observabilidad y control para cada entorno en el que corren tus agentes.** +Donde sea que corran tus agentes, nosotros lo vemos — y podemos decir que no. Failproof se conecta a 12 entornos de agentes — CLIs de codificación como Claude Code y Codex, pasarelas de chat como Hermes, asistentes autoalojados como OpenClaw — capturando cada ejecución y bloqueando llamadas a herramientas peligrosas antes de que se ejecuten. 39 políticas integradas. Cero latencia. Corre localmente. @@ -33,9 +33,9 @@ Donde sea que ejecuten tus agentes, nosotros lo vemos — y podemos decir que no ## Entornos compatibles -Doce entornos en dos categorías — diez CLIs de programación y dos pasarelas de chat y asistentes (Hermes, OpenClaw). Los mismos eventos, las mismas políticas, el mismo historial de sesiones, independientemente del entorno en el que corra tu agente. +Doce entornos en dos clases — diez CLIs de codificación, y dos pasarelas de chat y asistentes (Hermes, OpenClaw). Una única API de políticas e historial de sesiones compartido entre todos. Lo que una política puede *bloquear* depende de cada entorno: detener una llamada a herramienta antes de que se ejecute está verificado en los doce, y las compuertas de fin de turno funcionan en ocho. La [matriz por entorno](https://docs.befailproof.ai/reference/harnesses#enforcement-capability) lista los eventos que cada uno respeta. -Los agentes que no ejecutan en ninguno de ellos reportan a través del [SDK de Python](https://docs.befailproof.ai/reference/custom-agents), que te proporciona trazabilidad, sesiones y auditorías. El cumplimiento allí requiere un hook en tu propio entorno de ejecución — [contáctanos](mailto:support@befailproof.ai) y lo configuramos juntos. +Los agentes que no corren en ninguno de ellos reportan a través del [SDK de Python](https://docs.befailproof.ai/reference/custom-agents), que te ofrece trazabilidad, sesiones y auditorías. El control en ese caso requiere un hook en tu propio entorno de ejecución — [contáctanos](mailto:support@befailproof.ai) y lo configuramos juntos. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,37 +135,38 @@ Los agentes que no ejecutan en ninguno de ellos reportan a través del [SDK de P ```sh npm install -g failproofai -failproofai policies --install # o simplemente ejecuta `failproofai` y acepta el aviso de primera ejecución -failproofai +failproofai config # configura tus agentes y el daemon +failproofai policies add FailproofAI/policies # elige qué aplicar +failproofai # panel en localhost:8020 ``` -39 políticas integradas se activan de inmediato. Panel de control en `localhost:8020`. Deshabilita el aviso de primera ejecución con `FAILPROOFAI_NO_FIRST_RUN=1`. +La configuración conecta los hooks y **no** selecciona ninguna política — el segundo comando es el que añade las salvaguardas a la máquina, y cualquier paquete se escribe de la misma manera (`failproofai policies add /`; `policies show /` lee uno primero). Ejecuta `failproofai config` sin terminal — en CI, en un contenedor, con un agente al mando — y aplica la configuración en lugar de preguntar. En una máquina que nunca se ha configurado, cualquier otro comando ejecuta el mismo asistente primero; desactívalo con `FAILPROOFAI_NO_FIRST_RUN=1`. + +Hasta que llegue un paquete, lo único que aplica control es `block-failproofai-commands`, que siempre está activo y no puede desactivarse ni pausarse: un agente que puede pausar el control puede desactivar todas las demás políticas. --- -## Lo que bloquea +## Qué detiene | Política | Qué bloquea | |---|---| -| `sanitize-api-keys` | Claves de API que se filtran al contexto del agente | | `block-env-files` | Lecturas de `.env` y otros archivos de secretos | -| `warn-repeated-tool-calls` | El agente repitiendo en bucle la misma llamada | +| `warn-repeated-tool-calls` | El agente en bucle sobre la misma llamada | | `block-sudo` | Escalada de privilegios | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sin condición de filtrado | -| `block-terraform` / `block-kubectl` | Cambios no revisados en infraestructura en producción | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sin límites | +| `block-terraform` / `block-kubectl` | Cambios sin revisión en infraestructura en producción | | `block-rm-rf` | Eliminación recursiva de archivos | | `block-force-push` / `block-push-master` | `git push --force`, pushes directos a `main` | -Las primeras cinco aplican a cualquier agente que pueda invocar una herramienta. Las últimas tres son las favoritas de los desarrolladores — las CLIs de programación son la categoría de entorno que cubrimos con mayor profundidad. +Cada una de estas compuertas actúa *antes* de que la llamada se ejecute, por lo que funcionan en los doce entornos. Las primeras cuatro aplican a cualquier agente que pueda invocar una herramienta; las últimas tres son las favoritas de los desarrolladores — los CLIs de codificación son la clase de entorno que cubrimos con mayor profundidad. La familia `sanitize-*` es distinta: se ejecuta después de que una herramienta devuelve su resultado, por lo que reporta un secreto en la salida de la herramienta en lugar de evitar que llegue al contexto. -→ [Las 39 políticas integradas](https://docs.befailproof.ai/policies/builtin) +→ [Las 39 políticas integradas](https://docs.befailproof.ai/policies/packs) --- ## Tus propias políticas -Coloca un archivo en `.failproofai/policies/` — se carga automáticamente, sin necesidad de indicadores. -Confírmalo en el repositorio y todo el equipo lo obtendrá en el próximo pull. +Coloca un archivo en `.failproofai/policies/` — se carga automáticamente, sin necesidad de flags. Confírmalo al repositorio y todo el equipo lo obtiene en el próximo pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -187,24 +188,23 @@ Tres decisiones disponibles para cada política: |---|---| | `allow()` | Permite la operación | | `deny(message)` | La bloquea — el mensaje se devuelve al agente | -| `instruct(message)` | La deja pasar, pero añade contexto al próximo prompt del agente | +| `instruct(message)` | La deja pasar, pero añade contexto al siguiente prompt del agente | -→ [Guía de políticas personalizadas](https://docs.befailproof.ai/policies/custom) +→ [Escribir una política](https://docs.befailproof.ai/policies/editor) --- ## Observabilidad -El cumplimiento es una mitad. La otra mitad es ver lo que el agente hizo realmente. +El control es una mitad. La otra mitad es ver qué hizo realmente el agente. -Ejecuta `failproofai` sin argumentos y sirve un panel de control en `localhost:8020` -que lee el historial de ejecuciones ya almacenado en tu máquina — sin cuenta, sin registro, sin que nada salga del equipo. Obtienes la lista de sesiones, la secuencia de llamadas al modelo, llamadas a herramientas y decisiones de hook dentro de cada ejecución, qué fue bloqueado y qué le indicó la política al agente, y una auditoría sin conexión (`failproofai audit`) que analiza tu historial en busca de patrones de riesgo y sugiere políticas para detenerlos. +Ejecuta `failproofai` sin argumentos y sirve un panel en `localhost:8020` que lee el historial de ejecuciones ya almacenado en tu máquina — sin cuenta, sin registro, sin que nada salga del equipo. Obtienes la lista de sesiones, la secuencia de llamadas al modelo, llamadas a herramientas y decisiones de hooks dentro de cada ejecución, qué fue bloqueado y qué le dijo la política al agente, y una auditoría offline (`failproofai audit`) que analiza tu historial en busca de patrones de riesgo y sugiere políticas para detenerlos. -→ [Panel de control local](https://docs.befailproof.ai/reference/local-dashboard) · +→ [Panel local](https://docs.befailproof.ai/reference/local-dashboard) · [Leer una traza](https://docs.befailproof.ai/sessions/read-a-trace) · [Auditoría local](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** es el lado alojado del mismo modelo de datos, para equipos que ejecutan agentes en una flota: cada ejecución de cada entorno en un solo lugar, un grafo de ejecución con subagentes paralelos en sus propias pistas, latencia p50/p95/p99 para modelos, herramientas y hooks, seguimiento de costes y ventana de contexto por modelo, seguimiento de errores, SQL sobre tus propias trazas con paneles compartibles, evaluaciones puntuadas por tu propio servicio, auditorías programadas que convierten fallos recurrentes en hallazgos respaldados por evidencia, y alertas enrutadas a Slack, correo electrónico o un webhook firmado. El autoalojamiento en tu propio clúster está disponible en el plan Enterprise. +**Failproof AI Observability** es la versión alojada del mismo modelo de datos, para equipos que ejecutan agentes en una flota: cada ejecución de cada entorno en un solo lugar, un grafo de ejecución con subagentes paralelos en sus propios carriles, latencia p50/p95/p99 para modelos, herramientas y hooks, seguimiento de costos y ventana de contexto por modelo, seguimiento de errores, SQL sobre tus propias trazas con paneles compartibles, evaluaciones puntuadas por tu propio servicio, auditorías programadas que convierten fallos recurrentes en hallazgos respaldados por evidencia, y alertas enrutadas a Slack, correo electrónico o un webhook firmado. El autoalojamiento en tu propio clúster está disponible en el plan Enterprise. → [Sesiones](https://docs.befailproof.ai/sessions/overview) · [Auditorías](https://docs.befailproof.ai/audits/overview) · @@ -214,44 +214,44 @@ que lee el historial de ejecuciones ya almacenado en tu máquina — sin cuenta, ## Documentación -| Comenzar | | +| Inicio | | |---|---| -| [Inicio rápido](https://docs.befailproof.ai/start/quickstart) | Instalar, conectar un entorno, ver la primera ejecución | +| [Inicio rápido](https://docs.befailproof.ai/start/quickstart) | Instala, conecta un entorno, ve la primera ejecución | | [Conceptos](https://docs.befailproof.ai/start/concepts) | Cómo funciona el sistema de hooks | | [Entornos compatibles](https://docs.befailproof.ai/reference/harnesses) | Los 12, y qué puede aplicar cada uno | | Observar | | |---|---| -| [Sesiones](https://docs.befailproof.ai/sessions/overview) | Seguir una ejecución: modelos, herramientas, errores, latencia | -| [Leer una traza](https://docs.befailproof.ai/sessions/read-a-trace) | Lo que te está indicando el grafo de ejecución | -| [Auditorías](https://docs.befailproof.ai/audits/overview) | Encontrar patrones de fallo en múltiples sesiones | -| [Panel de control local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sin necesidad de cuenta | +| [Sesiones](https://docs.befailproof.ai/sessions/overview) | Sigue una ejecución: modelos, herramientas, errores, latencia | +| [Leer una traza](https://docs.befailproof.ai/sessions/read-a-trace) | Qué te está diciendo el grafo de ejecución | +| [Auditorías](https://docs.befailproof.ai/audits/overview) | Encuentra patrones de fallos en muchas sesiones | +| [Panel local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sin cuenta necesaria | -| Aplicar políticas | | +| Aplicar control | | |---|---| -| [Políticas integradas](https://docs.befailproof.ai/policies/builtin) | Las 39 políticas con sus parámetros | -| [Políticas personalizadas](https://docs.befailproof.ai/policies/custom) | Escribe las tuyas propias | -| [Configuración](https://docs.befailproof.ai/policies/local-configuration) | Ámbitos de configuración y reglas de combinación | +| [Paquetes de políticas](https://docs.befailproof.ai/policies/packs) | Las políticas de Failproof AI y paquetes del hub de políticas | +| [Escribir una política](https://docs.befailproof.ai/policies/editor) | Desde una auditoría o en código | +| [Configuración](https://docs.befailproof.ai/policies/local-configuration) | Ámbitos de configuración, reglas de fusión y parámetros de políticas | | Instrumentar tu propio agente | | |---|---| -| [SDK de Python](https://docs.befailproof.ai/reference/custom-agents) | Reportar ejecuciones desde un agente sin entorno propio | +| [SDK de Python](https://docs.befailproof.ai/reference/custom-agents) | Reporta ejecuciones desde un agente sin entorno | | [SDK de políticas](https://docs.befailproof.ai/reference/policy-sdk) | Referencia de `allow` / `deny` / `instruct` | --- ## Licencia -MIT con [Commons Clause](https://commonsclause.com/) — libre para uso interno y personal; la reventa comercial de failproofai en sí requiere un acuerdo separado. Consulta [LICENSE](../../LICENSE) para el texto completo. +MIT con [Commons Clause](https://commonsclause.com/) — libre para uso interno y personal; la reventa comercial de failproofai en sí misma requiere un acuerdo separado. Consulta [LICENSE](../../LICENSE) para el texto completo. --- ## Contribuir -Consulta [CONTRIBUTING.md](../../CONTRIBUTING.md). Son bienvenidas nuevas políticas, casos límite y traducciones. +Consulta [CONTRIBUTING.md](../../CONTRIBUTING.md). Se aceptan nuevas políticas, casos límite y traducciones. -> **Compila antes de empezar.** Ejecuta `bun install && bun run build` primero. Este repositorio ejecuta los propios hooks de failproofai sobre sí mismo, y resuelven la importación de `failproofai` contra el paquete compilado en `dist/` — sin una compilación obtendrás errores de hook `Cannot find package 'failproofai'`. Vuelve a compilar después de modificar `src/`. Consulta [Compilar antes de que funcionen los hooks de desarrollo del repositorio](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Compila antes de empezar.** Ejecuta `bun install && bun run build` primero. Este repositorio ejecuta los propios hooks de failproofai sobre sí mismo, y estos resuelven la importación de `failproofai` contra el bundle compilado en `dist/` — sin una compilación obtendrás errores de hook `Cannot find package 'failproofai'`. Vuelve a compilar después de modificar `src/`. Consulta [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Construido con ❤️ por [befailproof.ai](https://befailproof.ai) en SF y Bengaluru. +Hecho con ❤️ por [befailproof.ai](https://befailproof.ai) en San Francisco y Bengaluru. diff --git a/docs/i18n/README.fr.md b/docs/i18n/README.fr.md index 011274f6..55980def 100644 --- a/docs/i18n/README.fr.md +++ b/docs/i18n/README.fr.md @@ -20,8 +20,8 @@ **Traductions :** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Observabilité et contrôle pour chaque environnement d'exécution de vos agents.** -Où que vos agents s'exécutent, nous le voyons — et nous pouvons dire non. Failproof s'intègre à 12 environnements d'agents — des CLI de codage comme Claude Code et Codex, des passerelles de chat comme Hermes, des assistants auto-hébergés comme OpenClaw — capturant chaque exécution et bloquant les appels d'outils dangereux avant qu'ils ne se produisent. 39 politiques intégrées. Zéro latence. Fonctionne en local. +**Observabilité et application des règles pour chaque environnement d'exécution de vos agents.** +Où que vos agents s'exécutent, nous le voyons — et nous pouvons dire non. Failproof s'intègre à 12 environnements d'agents — des CLI de développement comme Claude Code et Codex, des passerelles de chat comme Hermes, des assistants auto-hébergés comme OpenClaw — capturant chaque exécution et bloquant les appels d'outils dangereux avant qu'ils ne se produisent. 39 politiques intégrées. Zéro latence. Fonctionne en local. @@ -33,9 +33,9 @@ Où que vos agents s'exécutent, nous le voyons — et nous pouvons dire non. Fa ## Environnements pris en charge -Douze environnements en deux catégories — dix CLI de codage, et deux passerelles de chat et d'assistants (Hermes, OpenClaw). Mêmes événements, mêmes politiques, même historique de session, quel que soit l'environnement dans lequel votre agent s'exécute. +Douze environnements répartis en deux catégories — dix CLI de développement, et deux passerelles de chat et d'assistant (Hermes, OpenClaw). Une seule API de politiques et un historique de sessions commun pour tous. Ce qu'une politique peut *bloquer* dépend de l'environnement : l'interruption d'un appel d'outil avant son exécution est vérifiée sur les douze, les contrôles en fin de tour sur huit. La [matrice par environnement](https://docs.befailproof.ai/reference/harnesses#enforcement-capability) liste les événements honorés par chacun. -Les agents qui ne s'exécutent dans aucun d'eux remontent leurs données via le [SDK Python](https://docs.befailproof.ai/reference/custom-agents), qui vous offre le traçage, les sessions et les audits. L'application des politiques nécessite alors un hook dans votre propre runtime — [contactez-nous](mailto:support@befailproof.ai) et nous l'adapterons. +Les agents qui ne s'exécutent dans aucun d'eux remontent leurs données via le [SDK Python](https://docs.befailproof.ai/reference/custom-agents), qui vous offre le traçage, les sessions et les audits. L'application des règles nécessite un hook dans votre propre runtime — [contactez-nous](mailto:support@befailproof.ai) et nous vous aiderons à le mettre en place. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,11 +135,14 @@ Les agents qui ne s'exécutent dans aucun d'eux remontent leurs données via le ```sh npm install -g failproofai -failproofai policies --install # ou lancez simplement `failproofai` et acceptez l'invite au premier démarrage -failproofai +failproofai config # connectez vos agents et le daemon +failproofai policies add FailproofAI/policies # choisissez ce que vous souhaitez appliquer +failproofai # tableau de bord sur localhost:8020 ``` -39 politiques intégrées s'activent immédiatement. Tableau de bord disponible sur `localhost:8020`. Désactivez l'invite au premier démarrage avec `FAILPROOFAI_NO_FIRST_RUN=1`. +La configuration installe les hooks et ne sélectionne **aucune** politique — la deuxième commande est celle qui place des garde-fous sur la machine, et n'importe quel pack se spécifie de la même façon (`failproofai policies add /` ; `policies show /` permet d'en consulter un au préalable). Exécutez `failproofai config` sans terminal — en CI, dans un conteneur, avec un agent aux commandes — et il applique la configuration sans poser de questions. Sur une machine qui n'a jamais été configurée, toute autre commande déclenche le même assistant en premier ; désactivez ce comportement avec `FAILPROOFAI_NO_FIRST_RUN=1`. + +Tant qu'aucun pack n'est installé, la seule règle active est `block-failproofai-commands`, qui est toujours activée et ne peut pas être désactivée ni suspendue : un agent capable de suspendre l'application des règles pourrait désactiver toutes les autres politiques. --- @@ -147,25 +150,24 @@ failproofai | Politique | Ce qu'elle bloque | |---|---| -| `sanitize-api-keys` | Les clés API qui fuient dans le contexte de l'agent | | `block-env-files` | La lecture des fichiers `.env` et autres fichiers de secrets | | `warn-repeated-tool-calls` | L'agent qui boucle sur le même appel | | `block-sudo` | L'élévation de privilèges | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sans conditions | -| `block-terraform` / `block-kubectl` | Les modifications non validées de l'infrastructure en production | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sans clause de restriction | +| `block-terraform` / `block-kubectl` | Les modifications non relues sur l'infrastructure en production | | `block-rm-rf` | La suppression récursive de fichiers | -| `block-force-push` / `block-push-master` | `git push --force`, les pushs directs vers `main` | +| `block-force-push` / `block-push-master` | `git push --force`, les poussées directes sur `main` | -Les cinq premières s'appliquent à tout agent capable d'appeler un outil. Les trois dernières sont les favorites des développeurs — les CLI de codage sont la catégorie d'environnements que nous couvrons le plus en profondeur. +Chacune de ces règles intercepte l'appel *avant* son exécution, ce qui garantit leur efficacité sur les douze environnements. Les quatre premières s'appliquent à tout agent capable d'appeler un outil ; les trois dernières sont les préférées des développeurs — les CLI de développement constituent la catégorie d'environnements que nous couvrons le plus en profondeur. La famille `sanitize-*` est à part : elle s'exécute après le retour d'un outil, signalant ainsi un secret dans la sortie de l'outil plutôt que de l'empêcher d'entrer dans le contexte. -→ [Les 39 politiques intégrées](https://docs.befailproof.ai/policies/builtin) +→ [Les 39 politiques intégrées](https://docs.befailproof.ai/policies/packs) --- ## Vos propres politiques Déposez un fichier dans `.failproofai/policies/` — il se charge automatiquement, sans aucun flag. -Committez-le et toute l'équipe en bénéficiera au prochain pull. +Commitez-le et toute l'équipe en bénéficiera au prochain pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -187,23 +189,23 @@ Trois décisions disponibles pour chaque politique : |---|---| | `allow()` | Autoriser l'opération | | `deny(message)` | La bloquer — le message est renvoyé à l'agent | -| `instruct(message)` | La laisser passer, mais ajouter du contexte au prochain prompt de l'agent | +| `instruct(message)` | La laisser passer, mais ajouter du contexte à la prochaine invite de l'agent | -→ [Guide des politiques personnalisées](https://docs.befailproof.ai/policies/custom) +→ [Écrire une politique](https://docs.befailproof.ai/policies/editor) --- ## Observabilité -L'application des règles n'est qu'une moitié. L'autre moitié, c'est de voir ce que l'agent a réellement fait. +L'application des règles représente une moitié du tableau. L'autre moitié, c'est voir ce que l'agent a réellement fait. -Lancez `failproofai` sans argument et il sert un tableau de bord sur `localhost:8020`, qui lit l'historique d'exécution déjà présent sur votre machine — sans compte, sans inscription, rien ne quitte votre poste. Vous accédez à la liste des sessions, à la séquence des appels de modèles, aux appels d'outils et aux décisions des hooks à l'intérieur de chaque exécution, à ce qui a été bloqué et à ce que la politique a transmis à l'agent, ainsi qu'à un audit hors ligne (`failproofai audit`) qui analyse votre historique à la recherche de schémas risqués et suggère des politiques pour les enrayer. +Lancez `failproofai` sans arguments et il sert un tableau de bord sur `localhost:8020` en lisant l'historique d'exécution déjà présent sur votre machine — pas de compte, pas d'inscription, rien ne quitte la machine. Vous obtenez la liste des sessions, la séquence des appels de modèles, les appels d'outils et les décisions des hooks à l'intérieur de chaque exécution, ce qui a été bloqué et ce que la politique a indiqué à l'agent, ainsi qu'un audit hors ligne (`failproofai audit`) qui analyse votre historique à la recherche de motifs risqués et suggère des politiques pour les prévenir. → [Tableau de bord local](https://docs.befailproof.ai/reference/local-dashboard) · [Lire une trace](https://docs.befailproof.ai/sessions/read-a-trace) · [Audit local](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** est la version hébergée du même modèle de données, destinée aux équipes qui exécutent des agents sur une flotte : toutes les exécutions de tous les environnements en un seul endroit, un graphe d'exécution avec des sous-agents parallèles sur leurs propres voies, la latence p50/p95/p99 pour les modèles, les outils et les hooks, le suivi des coûts et de la fenêtre de contexte par modèle, le suivi des erreurs, SQL sur vos propres traces avec des tableaux de bord partageables, des évaluations notées par votre propre service, des audits planifiés qui transforment les échecs récurrents en constats étayés par des preuves, et des alertes acheminées vers Slack, par e-mail ou via un webhook signé. L'auto-hébergement dans votre propre cluster est disponible avec le plan Enterprise. +**Failproof AI Observability** est la version hébergée du même modèle de données, destinée aux équipes faisant tourner des agents sur une flotte de machines : chaque exécution de chaque environnement en un seul endroit, un graphe d'exécution avec des sous-agents parallèles sur leurs propres voies, la latence p50/p95/p99 pour les modèles, les outils et les hooks, le suivi des coûts et de la fenêtre de contexte par modèle, le suivi des erreurs, du SQL sur vos propres traces avec des tableaux de bord partageables, des évaluations notées par votre propre service, des audits planifiés qui transforment les échecs récurrents en constats étayés par des preuves, et des alertes routées vers Slack, par e-mail ou via un webhook signé. L'auto-hébergement dans votre propre cluster est disponible dans le plan Entreprise. → [Sessions](https://docs.befailproof.ai/sessions/overview) · [Audits](https://docs.befailproof.ai/audits/overview) · @@ -213,7 +215,7 @@ Lancez `failproofai` sans argument et il sert un tableau de bord sur `localhost: ## Documentation -| Démarrer | | +| Démarrage | | |---|---| | [Démarrage rapide](https://docs.befailproof.ai/start/quickstart) | Installer, connecter un environnement, voir la première exécution | | [Concepts](https://docs.befailproof.ai/start/concepts) | Comment fonctionne le système de hooks | @@ -222,19 +224,19 @@ Lancez `failproofai` sans argument et il sert un tableau de bord sur `localhost: | Observer | | |---|---| | [Sessions](https://docs.befailproof.ai/sessions/overview) | Suivre une exécution : modèles, outils, erreurs, latence | -| [Lire une trace](https://docs.befailproof.ai/sessions/read-a-trace) | Ce que le graphe d'exécution vous révèle | -| [Audits](https://docs.befailproof.ai/audits/overview) | Identifier les schémas d'échec sur de nombreuses sessions | -| [Tableau de bord local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sans compte requis | +| [Lire une trace](https://docs.befailproof.ai/sessions/read-a-trace) | Ce que le graphe d'exécution vous indique | +| [Audits](https://docs.befailproof.ai/audits/overview) | Trouver des motifs d'échec sur de nombreuses sessions | +| [Tableau de bord local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sans compte nécessaire | | Appliquer | | |---|---| -| [Politiques intégrées](https://docs.befailproof.ai/policies/builtin) | Les 39 politiques avec leurs paramètres | -| [Politiques personnalisées](https://docs.befailproof.ai/policies/custom) | Écrire les vôtres | -| [Configuration](https://docs.befailproof.ai/policies/local-configuration) | Portées de configuration et règles de fusion | +| [Packs de politiques](https://docs.befailproof.ai/policies/packs) | Les politiques Failproof AI et les packs du hub de politiques | +| [Écrire une politique](https://docs.befailproof.ai/policies/editor) | À partir d'un audit ou directement en code | +| [Configuration](https://docs.befailproof.ai/policies/local-configuration) | Portées de configuration, règles de fusion et paramètres de politique | | Instrumenter votre propre agent | | |---|---| -| [SDK Python](https://docs.befailproof.ai/reference/custom-agents) | Remonter les exécutions d'un agent sans environnement | +| [SDK Python](https://docs.befailproof.ai/reference/custom-agents) | Remonter les exécutions depuis un agent sans environnement dédié | | [SDK de politiques](https://docs.befailproof.ai/reference/policy-sdk) | Référence `allow` / `deny` / `instruct` | --- @@ -247,11 +249,10 @@ MIT avec [Commons Clause](https://commonsclause.com/) — gratuit pour un usage ## Contribuer -Consultez [CONTRIBUTING.md](../../CONTRIBUTING.md). Nouvelles politiques, cas limites et traductions sont les bienvenus. +Voir [CONTRIBUTING.md](../../CONTRIBUTING.md). Les nouvelles politiques, les cas limites et les traductions sont les bienvenus. -> **Compilez avant de commencer.** Exécutez d'abord `bun install && bun run build`. Ce dépôt exécute les hooks de failproofai sur lui-même, et ceux-ci résolvent l'import `failproofai` depuis le bundle compilé `dist/` — sans compilation, vous obtiendrez des erreurs de hook `Cannot find package 'failproofai'`. Recompilez après toute modification de `src/`. Voir -> [Compiler avant que les hooks de développement intégrés au dépôt fonctionnent](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Compilez avant de commencer.** Exécutez d'abord `bun install && bun run build`. Ce dépôt fait tourner ses propres hooks failproofai sur lui-même, et ils résolvent l'import `failproofai` par rapport au bundle compilé `dist/` — sans compilation, vous obtiendrez des erreurs de hook `Cannot find package 'failproofai'`. Recompilez après avoir modifié `src/`. Voir [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Fait avec ❤️ par [befailproof.ai](https://befailproof.ai) à San Francisco et Bengaluru. +Conçu avec ❤️ par [befailproof.ai](https://befailproof.ai) à San Francisco et Bengaluru. diff --git a/docs/i18n/README.he.md b/docs/i18n/README.he.md index a3e186fa..b505a76c 100644 --- a/docs/i18n/README.he.md +++ b/docs/i18n/README.he.md @@ -22,23 +22,21 @@ **תרגומים:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**צפייה ויישום לכל סביבה בה הסוכנים שלך רצים.** -איפה שהסוכנים שלך רצים, אנחנו רואים את זה — ואנחנו יכולים לומר לא. Failproof משתלב עם 12 סביבות סוכנים — CLIs קידוד כמו Claude Code וCodex, שערים לצ'אט כמו Hermes, עוזרים עצמיים כמו OpenClaw — תופס כל הרצה וחוסם קריאות כלים מסוכנות לפני שהן מתבצעות. 39 מדיניות מובנית. אפס זיהוי. פועל מקומי. +**ניטור והטלת אכיפה על כל מנוף שבו מריצים Agents.** בכל מקום שבו מריצים את Agents שלך, אנחנו רואים את זה — ואנחנו יכולים להגיד לא. Failproof מתחבר ל-12 מנופי agents — CLIs קוד כמו Claude Code ו-Codex, שערי צ'אט כמו Hermes, assistants בעצמאות עצמית כמו OpenClaw — לוכדים כל הרצה וחוסמים קריאות כלים מסוכנות לפני ביצוע. 39 מדיניות מובנות. זליגה אפס. פועל ברמה מקומית.

- Failproof AI בפעולה + Failproof AI in action

--- -## סביבות נתמכות +## מנופים נתמכים -שתים-עשרה סביבות בשתי קטגוריות — עשרה CLIs קידוד, ושני שערים לצ'אט ועוזרים (Hermes, OpenClaw). אותם אירועים, אותן מדיניויות, אותו היסטוריית הפעלה, איפה שלא רץ הסוכן שלך. +שנים עשר מנופים בשתי מחלקות — עשרה CLIs קוד, ושני שערי צ'אט ו-assistant (Hermes, OpenClaw). API מדיניות אחד והיסטוריית הפעלה אחת על כולם. מה שמדיניות יכולה לחסום הוא לפי מנוף: עצירת קריאת כלים לפני ביצוע מתוודאת בכל שנים עשר, שערי קצה הרצה בשמונה. ה[מטריצה לפי מנוף](https://docs.befailproof.ai/reference/harnesses#enforcement-capability) רשמת את האירועים שכל אחד מהם מכבד. -סוכנים שלא רצים באף אחת מהן דיווחים דרך [Python SDK](https://docs.befailproof.ai/reference/custom-agents), -שנותן לך מעקב, הפעלות וביקורות. יישום בחזקת החוקים שם דורש hook בזמן הרצה שלך — [דבר אתנו](mailto:support@befailproof.ai) ונמפה זאת. +Agents שפועלים בשום אחד מהם דיווח דרך [ה-Python SDK](https://docs.befailproof.ai/reference/custom-agents), שנותן לך ניתוח, הפעלות וביקורות. אכיפה שם צריכה ווי בסביבת ההרצה שלך — [דברו איתנו](mailto:support@befailproof.ai) ואנחנו נמפה אותה. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -138,37 +136,38 @@ ```sh npm install -g failproofai -failproofai policies --install # או פשוט הרץ `failproofai` והסכם להנחיה בהרצה הראשונה -failproofai +failproofai config # חוט את ה-agents שלך ו-daemon +failproofai policies add FailproofAI/policies # בחר מה להטיל +failproofai # לוח בקרה ב-localhost:8020 ``` -39 מדיניויות מובנית מופעלות מיד. לוח בקרה ב `localhost:8020`. בטל את ההנחיה בהרצה הראשונה עם `FAILPROOFAI_NO_FIRST_RUN=1`. +ההגדרה מתחברת את ההוקים ובוחרת אפס מדיניות — הפקודה השנייה הזו היא מה שמוציא מגבלות על המכונה, וכל חבילה מוקלדת באותו אופן (`failproofai policies add /`; `policies show /` קורא אחת ראשונה). הרץ `failproofai config` ללא טרמינל — CI, קונטיינר, agent שמנהל אותה — וזה מיישם במקום לשאול. על מכונה שלא הוגדרה מעולם, כל פקודה אחרת מריץ את אותה אשף קודם; השבת את זה עם `FAILPROOFAI_NO_FIRST_RUN=1`. + +עד שחבילה תגיע, הדבר היחיד שמטיל אכיפה הוא `block-failproofai-commands`, שתמיד פועל ולא ניתן להשבתה או השהיה: agent שיכול להשהות אכיפה יכול להשבית כל מדיניות אחרת. --- ## מה זה עוצר -| מדיניות | מה היא חוסמת | +| מדיניות | מה זה חוסם | |---|---| -| `sanitize-api-keys` | מפתחות API שדולפים להקשר של הסוכן | -| `block-env-files` | קריאות של קבצים סודיים כמו `.env` | -| `warn-repeated-tool-calls` | הסוכן משתמש שוב באותה קריאה | +| `block-env-files` | קריאות של קבצי `.env` וקבצי סוד אחרים | +| `warn-repeated-tool-calls` | ה-agent לולאה בקריאה זהה | | `block-sudo` | הסלמת הרשאות | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` ללא מגבלה | -| `block-terraform` / `block-kubectl` | שינויים לא מבוקרים לתשתית חיה | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` ללא גבול | +| `block-terraform` / `block-kubectl` | שינויים שלא זוקפו לתשומת לב לתשתיות חיות | | `block-rm-rf` | מחיקת קבצים רקורסיבית | -| `block-force-push` / `block-push-master` | `git push --force`, דחיפה ישירה ל `main` | +| `block-force-push` / `block-push-master` | `git push --force`, דחיפות ישירות ל-`main` | -חמשת הראשונים חלים על כל סוכן שיכול לקרוא לכלי. שלוש האחרונות הן החביבות של המפתחים — CLIs קידוד הם הסוג של סביבה שבו אנחנו מכסים את התעמקות ביותר. +כל אחת מהן משער את הקריאה *לפני* ביצוע, כך שהן מחזיקות בכל שנים עשר מנופים. ארבע הראשונות חלות על כל agent שיכול לקרוא לכלי; שלושת האחרונים הם המועדפים של המפתחים — CLIs קוד הם מחלקת המנוף שאנו מכסים בעומק. משפחת `sanitize-*` נפרדת: היא רצה לאחר שכלי חוזר, כך שהיא מדווחת על סוד בפלט כלים ולא שומרת אותה מהקשר. -→ [כל 39 המדיניויות המובניות](https://docs.befailproof.ai/policies/builtin) +→ [כל 39 מדיניות מובנות](https://docs.befailproof.ai/policies/packs) --- ## המדיניויות שלך -זרוק קובץ לתוך `.failproofai/policies/` — הוא נטען אוטומטית, אין צורך בדגלים. -עשה קומיט וכל הצוות שלך יקבל אותו בפול הבא. +השלך קובץ לתוך `.failproofai/policies/` — הוא טוען באופן אוטומטי, לא צריך דגלים. התחייב אותו והצוות כולו מקבל אותו בדחיפה הבאה. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -178,7 +177,7 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("כתיבה לנתיבי ייצור חסומה."); + return deny("Writes to production paths are blocked."); return allow(); }, }); @@ -188,78 +187,76 @@ customPolicies.add({ | החלטה | השפעה | |---|---| -| `allow()` | הרשה את הפעולה | -| `deny(message)` | חסום אותה — ההודעה חוזרת לסוכן | -| `instruct(message)` | תן לה לעבור, אך הוסף הקשר להנחיה הבאה של הסוכן | +| `allow()` | התר את הפעולה | +| `deny(message)` | חסום אותה — ההודעה חוזרת ל-agent | +| `instruct(message)` | תן לזה לעבור, אבל הוסף הקשר להנחיה הבאה של ה-agent | -→ [מדריך מדיניויות מותאמות](https://docs.befailproof.ai/policies/custom) +→ [כתוב מדיניות](https://docs.befailproof.ai/policies/editor) --- -## צפייה +## ניטור -יישום הוא חצי. החצי השני הוא לראות מה הסוכן בעצם עשה. +אכיפה היא חצי אחד. החצי השני הוא לראות מה ה-agent בעצם עשה. -הרץ `failproofai` ללא ארגומנטים והוא משרת לוח בקרה ב `localhost:8020` -קוראת את היסטוריית הריצה שכבר ישנה במכונה שלך — אין חשבון, אין הרשמה, כלום לא עוזב את הקופסה. אתה מקבל את רשימת ההפעלות, את רצף קריאות המודל, קריאות הכלים והחלטות ה-hook בכל הרצה, מה שחוסם ומה שאמרה המדיניות לסוכן, וביקורת ללא חיבור (`failproofai audit`) שסורקת את ההיסטוריה שלך לחיפוש דפוסים מסוכנים וממליצה על מדיניויות כדי לעצור אותם. +הרץ `failproofai` ללא טיעונים וזה משרת לוח בקרה ב-`localhost:8020` קורא את היסטוריית ההרצה כבר על המכונה שלך — אין חשבון, אין הרשמה, כלום עוזב את הקופסה. אתה מקבל רשימת הפעלות, סדר קריאות מודל, קריאות כלים והחלטות ווי בתוך כל הרצה, מה שנחסם ומה המדיניות אמרה ל-agent, וביקורת במצב לא מקוון (`failproofai audit`) שסורקת את ההיסטוריה שלך לדפוסים מסוכנים ומציעה מדיניויות לעצור אותם. → [לוח בקרה מקומי](https://docs.befailproof.ai/reference/local-dashboard) · -[קרא עקיבה](https://docs.befailproof.ai/sessions/read-a-trace) · +[קרא עקבול](https://docs.befailproof.ai/sessions/read-a-trace) · [ביקורת מקומית](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** היא הצד המארח של אותו מודל נתונים, לצוותים -המריצים סוכנים על פני חיל: כל הרצה מכל סביבה במקום אחד, גרף ביצוע עם תת-סוכנים מקבילים על נתיבים שלהם, p50/p95/p99 זיהוי לדגמים, כלים ו-hooks, עלות לכל דגם ומעקב חלון הקשר, מעקב שגיאות, SQL על העקיבות שלך עם לוחות בקרה שניתן לשתף, הערכות המדורגות על ידי שירותך, ביקורות מתוזמנות שהופכות כשלים יוקרים לממצאים מבוססי הוכחות, ותראות המנותבות ל-Slack, דוא"ל או webhook חתום. Self-hosting בקבוצה שלך זמין בתוכנית Enterprise. +**Failproof AI Observability** היא הצד המארח של אותו מודל נתונים, לצוותים שמריצים agents על פני צי: כל הרצה מכל מנוף במקום אחד, גרף ביצוע עם תת-agents מקביל בנתיבים שלהם, p50/p95/p99 latency עבור מודלים, כלים וווי, עלות לכל מודל וניתוח חלון הקשר, ניתוח שגיאות, SQL על העקבול שלך עם לוחות משתפים, הערכות הניקוד על ידי השירות שלך, ביקורות מתוזמנות שהופכות כשלים חוזרים להוכחות מרוכזות, והתראות שנמשלחו ל-Slack, דוא״ל או webhook חתום. Self-hosting בקלסטר שלך זמין בתוכנית Enterprise. → [הפעלות](https://docs.befailproof.ai/sessions/overview) · [ביקורות](https://docs.befailproof.ai/audits/overview) · -[ספק דגמה](https://befailproof.ai/get-a-demo) +[הזמן הדגמה](https://befailproof.ai/get-a-demo) --- ## תיעוד -| התחלה | | +| התחל | | |---|---| -| [התחלה מהירה](https://docs.befailproof.ai/start/quickstart) | התקן, חבר סביבה, ראה את ההרצה הראשונה | -| [קונספטים](https://docs.befailproof.ai/start/concepts) | איך מערכת ה-hook עובדת | -| [סביבות נתמכות](https://docs.befailproof.ai/reference/harnesses) | כל 12, ומה כל אחת יכולה להטיל | +| [Quickstart](https://docs.befailproof.ai/start/quickstart) | התקן, חבר מנוף, ראה את ההרצה הראשונה | +| [מושגים](https://docs.befailproof.ai/start/concepts) | איך מערכת הווי עובדת | +| [מנופים נתמכים](https://docs.befailproof.ai/reference/harnesses) | כל 12, וכל אחד יכול להטיל | -| צפה | | +| שקוף | | |---|---| -| [הפעלות](https://docs.befailproof.ai/sessions/overview) | עקוב אחרי הרצה: דגמים, כלים, שגיאות, זיהוי | -| [קרא עקיבה](https://docs.befailproof.ai/sessions/read-a-trace) | מה גרף הביצוע מספר לך | +| [הפעלות](https://docs.befailproof.ai/sessions/overview) | עקוב אחרי הרצה: מודלים, כלים, שגיאות, latency | +| [קרא עקבול](https://docs.befailproof.ai/sessions/read-a-trace) | מה גרף הביצוע אומר לך | | [ביקורות](https://docs.befailproof.ai/audits/overview) | מצא דפוסי כשל על פני הפעלות רבות | | [לוח בקרה מקומי](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, אין צורך בחשבון | -| יישם | | +| הטל | | |---|---| -| [מדיניויות מובניות](https://docs.befailproof.ai/policies/builtin) | כל 39 המדיניויות עם פרמטרים | -| [מדיניויות מותאמות](https://docs.befailproof.ai/policies/custom) | כתוב שלך | -| [תצורה](https://docs.befailproof.ai/policies/local-configuration) | היקפי תצורה וכללי מיזוג | +| [חבילות מדיניות](https://docs.befailproof.ai/policies/packs) | מדיניויות Failproof AI, וחבילות מחוב המדיניות | +| [כתוב מדיניות](https://docs.befailproof.ai/policies/editor) | מביקורת, או בקוד | +| [הגדרה](https://docs.befailproof.ai/policies/local-configuration) | היקפי הגדרה, כללי מיזוג ופרמטרים של מדיניות | -| השקע את הסוכן שלך | | +| כלי את ה-agent שלך | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | דווח הרצות מסוכן ללא סביבה | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | התייחסות `allow` / `deny` / `instruct` | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | דווח על הרצות מ-agent ללא מנוף | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | הפניית `allow` / `deny` / `instruct` | --- ## רישיון -MIT עם [Commons Clause](https://commonsclause.com/) — חינם לשימוש פנימי ואישי; מכירת מסחרית של failproofai דורשת הסכם נפרד. ראה [LICENSE](../../LICENSE) לטקסט המלא. +MIT עם [Commons Clause](https://commonsclause.com/) — חינם לשימוש פנימי ואישי; מכירת הטלות מחדש של failproofai עצמה דורשת הסכם נפרד. ראה [LICENSE](../../LICENSE) לטקסט המלא. --- ## תרומה -ראה [CONTRIBUTING.md](../../CONTRIBUTING.md). מדיניויות חדשות, מקרים קצהיים, ותרגומים כל ברוכים. +ראה [CONTRIBUTING.md](../../CONTRIBUTING.md). מדיניויות חדשות, מקרי קצה, ותרגומים כולם מוזמנים. -> **בנה לפני שתתחיל.** הרץ `bun install && bun run build` ראשית. מחסן זה מריץ את ה-hooks שלו עצמו, והם פותרים את ה-import של `failproofai` כנגד הצרור המחובר של `dist/` — ללא בנייה תפגע ב-`Cannot find package 'failproofai'` שגיאות hook. בנה מחדש לאחר שינוי `src/`. ראה -> [בנה לפני שה-hooks של dev בתוך הסחסום יעבדו](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **בנה לפני שתתחיל.** הרץ `bun install && bun run build` קודם. מחסן זה מריץ את הווי שלו failproofai על עצמו, והם פותרים את `failproofai` import כנגד ה-bundle המתורגל `dist/` — ללא בנייה תיפגע `Cannot find package 'failproofai'` שגיאות ווי. בנייה מחדש לאחר שינוי `src/`. ראה +> [בנה לפני שהווי התוך-מחסן יעבדו](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -בנוי עם ❤️ על ידי [befailproof.ai](https://befailproof.ai) ב-SF וב-Bengaluru. +בנוי עם ❤️ על ידי [befailproof.ai](https://befailproof.ai) ב-SF ובנגלור. \ No newline at end of file diff --git a/docs/i18n/README.hi.md b/docs/i18n/README.hi.md index 4040e13a..6856d3eb 100644 --- a/docs/i18n/README.hi.md +++ b/docs/i18n/README.hi.md @@ -20,11 +20,8 @@ **अनुवाद:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**प्रत्येक हार्नेस के लिए अवलोकनीयता और प्रवर्तन जहां आपके एजेंट चलते हैं।** -आपके एजेंट जहां भी चलें, हम इसे देखते हैं — और हम नहीं कह सकते। Failproof 12 एजेंट -हार्नेस को हुक करता है — कोडिंग CLIs जैसे Claude Code और Codex, चैट गेटवे जैसे Hermes, -स्व-होस्ट किए गए सहायक जैसे OpenClaw — प्रत्येक रन को कैप्चर करना और खतरनाक -टूल कॉल को निष्पादन से पहले ब्लॉक करना। 39 बिल्ट-इन नीतियाँ। शून्य लेटेंसी। स्थानीय रूप से चलता है। +**हर harness के लिए अवलोकन और प्रवर्तन जो आपके agents चलाते हैं।** +जहां भी आपके agents चलते हैं, हम इसे देखते हैं — और हम नहीं कह सकते। Failproof 12 agent harnesses को हुक करता है — Claude Code और Codex जैसे कोडिंग CLIs, Hermes जैसे chat gateways, OpenClaw जैसे self-hosted assistants — हर run को कैप्चर करता है और execution से पहले खतरनाक tool calls को block करता है। 39 built-in policies। शून्य latency। स्थानीय रूप से चलता है। @@ -34,14 +31,11 @@ --- -## समर्थित हार्नेस +## समर्थित harnesses -दो वर्गों में बारह हार्नेस — दस कोडिंग CLIs, और दो चैट और सहायक -गेटवे (Hermes, OpenClaw)। समान ईवेंट, समान नीतियाँ, समान सत्र इतिहास, -चाहे आपका एजेंट किसमें भी चले। +दो वर्गों में बारह harnesses — दस कोडिंग CLIs, और दो chat और assistant gateways (Hermes, OpenClaw)। सभी के लिए एक policy API और एक session history। एक policy क्या *block* कर सकती है यह per-harness है: tool call को चलने से पहले रोकना सभी बारह पर सत्यापित है, turn-end gates आठ पर हैं। [per-harness matrix](https://docs.befailproof.ai/reference/harnesses#enforcement-capability) प्रत्येक द्वारा honored events की सूची देता है। -जो एजेंट इनमें से किसी में भी नहीं चलते हैं वे [Python SDK](https://docs.befailproof.ai/reference/custom-agents) के माध्यम से रिपोर्ट करते हैं, -जो आपको ट्रेसिंग, सत्र और ऑडिट देता है। वहाँ प्रवर्तन के लिए आपके अपने रनटाइम में एक हुक की आवश्यकता होती है — [हमसे बात करें](mailto:support@befailproof.ai) और हम इसे मैप करेंगे। +जो Agents किसी में भी नहीं चलते हैं वे [Python SDK](https://docs.befailproof.ai/reference/custom-agents) के माध्यम से रिपोर्ट करते हैं, जो आपको tracing, sessions और audits देता है। वहां enforcement के लिए आपके स्वयं के runtime में एक hook की आवश्यकता होती है — [हमसे बात करें](mailto:support@befailproof.ai) और हम इसे map करेंगे। {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -137,42 +131,43 @@
-## स्थापना +## स्थापित करें ```sh npm install -g failproofai -failproofai policies --install # या बस `failproofai` चलाएं और पहली बार के संकेत को स्वीकार करें -failproofai +failproofai config # अपने agents और daemon को wire करें +failproofai policies add FailproofAI/policies # प्रवर्तन करने के लिए क्या चुनें +failproofai # localhost:8020 पर dashboard ``` -39 बिल्ट-इन नीतियाँ तुरंत सक्रिय हो जाती हैं। डैशबोर्ड `localhost:8020` पर। पहली बार के संकेत को `FAILPROOFAI_NO_FIRST_RUN=1` से अक्षम करें। +Setup hooks को wire करता है और **कोई नहीं** policies चुनता है — वह दूसरी कमांड है जो मशीन पर guardrails रखती है, और कोई भी pack एक ही तरह से typed है (`failproofai policies add /`; `policies show /` पहले एक को पढ़ता है)। बिना terminal के `failproofai config` चलाएं — CI, container, agent इसे चलाते हुए — और यह पूछने के बजाय लागू करता है। एक मशीन पर जो कभी setup नहीं हुई है, कोई भी अन्य कमांड पहले एक ही wizard चलाती है; इसे `FAILPROOFAI_NO_FIRST_RUN=1` से disable करें। + +जब तक pack नहीं आता, एकमात्र चीज़ जो प्रवर्तन करती है वह `block-failproofai-commands` है, जो हमेशा चालू रहती है और switch off या paused नहीं हो सकती: एक agent जो enforcement को pause कर सकता है अन्य सभी policies को switch off कर सकता है। --- ## यह क्या रोकता है -| नीति | यह क्या ब्लॉक करता है | +| Policy | यह क्या blocks करता है | |---|---| -| `sanitize-api-keys` | API कुंजियाँ एजेंट के संदर्भ में लीक होना | -| `block-env-files` | `.env` और अन्य गुप्त फाइलों का पढ़ना | -| `warn-repeated-tool-calls` | एजेंट एक ही कॉल पर लूपिंग करना | -| `block-sudo` | विशेषाधिकार एस्केलेशन | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, असीमित `DELETE` | -| `block-terraform` / `block-kubectl` | लाइव बुनियादी ढाँचे में बिना समीक्षा के परिवर्तन | -| `block-rm-rf` | पुनरावर्ती फाइल हटाना | -| `block-force-push` / `block-push-master` | `git push --force`, `main` को सीधा पुश | +| `block-env-files` | `.env` और अन्य secret files की reads | +| `warn-repeated-tool-calls` | Agent एक ही call पर looping कर रहा है | +| `block-sudo` | Privilege escalation | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, unbounded `DELETE` | +| `block-terraform` / `block-kubectl` | Unreviewed changes to live infrastructure | +| `block-rm-rf` | Recursive file deletion | +| `block-force-push` / `block-push-master` | `git push --force`, direct pushes to `main` | -पहली पाँच किसी भी एजेंट पर लागू होती हैं जो एक टूल कॉल कर सकता है। अंतिम तीन -डेवलपर पसंदीदा हैं — कोडिंग CLIs हार्नेस का वर्ग हैं जिसे हम सबसे गहराई से कवर करते हैं। +इनमें से हर एक call को चलने से *पहले* gate करता है, इसलिए वे सभी बारह harnesses पर काम करते हैं। पहले चार किसी भी agent पर लागू होते हैं जो tool call कर सकता है; अंतिम तीन developer पसंद हैं — कोडिंग CLIs harness class हैं जिन्हें हम सबसे गहराई से कवर करते हैं। `sanitize-*` family अलग है: यह tool return के बाद चलता है, इसलिए यह context में secret को रखने के बजाय tool output में रिपोर्ट करता है। -→ [सभी 39 बिल्ट-इन नीतियाँ](https://docs.befailproof.ai/policies/builtin) +→ [सभी 39 built-in policies](https://docs.befailproof.ai/policies/packs) --- -## आपकी अपनी नीतियाँ +## आपकी स्वयं की policies -`.failproofai/policies/` में एक फाइल ड्रॉप करें — यह स्वचालित रूप से लोड होती है, कोई फ्लैग की आवश्यकता नहीं। -इसे कमिट करें और पूरी टीम को अगली पुल पर मिल जाएगा। +`.failproofai/policies/` में एक फाइल छोड़ें — यह स्वचालित रूप से लोड होता है, कोई flags की आवश्यकता नहीं। +इसे commit करें और पूरी team को अगली pull पर यह मिल जाएगा। ```js import { customPolicies, deny, allow } from "failproofai"; @@ -188,90 +183,76 @@ customPolicies.add({ }); ``` -हर नीति के लिए तीन निर्णय उपलब्ध हैं: +हर policy के लिए उपलब्ध तीन निर्णय: | निर्णय | प्रभाव | |---|---| -| `allow()` | ऑपरेशन की अनुमति दें | -| `deny(message)` | इसे ब्लॉक करें — संदेश एजेंट को वापस जाता है | -| `instruct(message)` | इसे के माध्यम से चलने दें, लेकिन एजेंट के अगले प्रॉम्प्ट में संदर्भ जोड़ें | +| `allow()` | Operation की अनुमति दें | +| `deny(message)` | इसे block करें — message agent को वापस जाता है | +| `instruct(message)` | इसे through होने दें, लेकिन agent के अगले prompt में context जोड़ें | -→ [कस्टम नीतियाँ गाइड](https://docs.befailproof.ai/policies/custom) +→ [एक policy लिखें](https://docs.befailproof.ai/policies/editor) --- -## अवलोकनीयता +## अवलोकन -प्रवर्तन एक आधा है। दूसरा आधा यह देखना है कि एजेंट ने वास्तव में क्या किया। +Enforcement एक आधा है। दूसरा आधा यह देखना है कि agent ने वास्तव में क्या किया। -बिना किसी तर्क के `failproofai` चलाएं और यह `localhost:8020` पर एक डैशबोर्ड प्रस्तुत करता है -जो आपकी मशीन पर पहले से मौजूद रन हिस्ट्री को पढ़ता है — कोई खाता, कोई साइन-अप, कुछ भी -बॉक्स से बाहर नहीं जा रहा। आप सत्र सूची, मॉडल कॉल का क्रम, टूल कॉल और हुक निर्णय -प्रत्येक रन के अंदर, क्या ब्लॉक किया गया और नीति ने एजेंट को क्या बताया, और एक ऑफ़लाइन ऑडिट (`failproofai audit`) प्राप्त करते हैं -जो आपके इतिहास को जोखिम भरे पैटर्न के लिए स्कैन करता है और नीतियों का सुझाव देता है -उन्हें रोकने के लिए। +`failproofai` को कोई arguments के साथ चलाएं और यह `localhost:8020` पर एक dashboard serve करता है जो आपकी मशीन पर पहले से मौजूद run history को पढ़ता है — कोई account नहीं, कोई signup नहीं, कुछ भी box से बाहर नहीं जाता। आप session list, हर run के अंदर model calls, tool calls और hook decisions का sequence, क्या block हुआ और policy ने agent को क्या बताया, और एक offline audit (`failproofai audit`) प्राप्त करते हैं जो आपके history को risky patterns के लिए scan करता है और policies suggest करता है उन्हें रोकने के लिए। -→ [लोकल डैशबोर्ड](https://docs.befailproof.ai/reference/local-dashboard) · -[एक ट्रेस पढ़ें](https://docs.befailproof.ai/sessions/read-a-trace) · -[स्थानीय ऑडिट](https://docs.befailproof.ai/audits/local-audit) +→ [Local dashboard](https://docs.befailproof.ai/reference/local-dashboard) · +[एक trace पढ़ें](https://docs.befailproof.ai/sessions/read-a-trace) · +[Local audit](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI अवलोकनीयता** समान डेटा मॉडल का होस्ट किया गया पक्ष है, एजेंट चलाने वाली टीमों के लिए -एक बेड़े में: हर हार्नेस से हर रन एक जगह में, एक निष्पादन ग्राफ अपने स्वयं के लेन पर समानांतर -उप-एजेंट के साथ, p50/p95/p99 मॉडल, टूल और हुक के लिए लेटेंसी, प्रति-मॉडल लागत और -संदर्भ-विंडो ट्रैकिंग, त्रुटि ट्रैकिंग, आपके अपने ट्रेस पर SQL साझा करने योग्य डैशबोर्ड के साथ, -आपकी अपनी सेवा द्वारा स्कोर किए गए मूल्यांकन, निर्धारित ऑडिट जो आवर्ती विफलता को -साक्ष्य-आधारित निष्कर्ष में बदलते हैं, और Slack, ईमेल या हस्ताक्षरित वेबहुक को भेजे गए अलर्ट। -आपके अपने क्लस्टर में स्व-होस्टिंग एंटरप्राइज योजना पर उपलब्ध है। +**Failproof AI Observability** उसी data model का hosted side है, teams के लिए जो fleet में agents चलाते हैं: हर harness से हर run एक जगह पर, एक execution graph जिसमें parallel sub-agents अपनी lanes पर हैं, models, tools और hooks के लिए p50/p95/p99 latency, per-model cost और context-window tracking, error tracking, आपके स्वयं के traces पर SQL के साथ shareable dashboards, आपकी स्वयं की service द्वारा scored evaluations, और scheduled audits जो recurring failures को evidence-backed findings में बदलते हैं, और alerts Slack, email या एक signed webhook को route करते हैं। Enterprise plan पर आपके स्वयं के cluster में self-hosting उपलब्ध है। -→ [सत्र](https://docs.befailproof.ai/sessions/overview) · -[ऑडिट](https://docs.befailproof.ai/audits/overview) · -[डेमो बुक करें](https://befailproof.ai/get-a-demo) +→ [Sessions](https://docs.befailproof.ai/sessions/overview) · +[Audits](https://docs.befailproof.ai/audits/overview) · +[एक demo बुक करें](https://befailproof.ai/get-a-demo) --- -## दस्तावेज़ +## Documentation -| शुरुआत | | +| शुरुआत करें | | |---|---| -| [त्वरित शुरुआत](https://docs.befailproof.ai/start/quickstart) | स्थापित करें, एक हार्नेस कनेक्ट करें, पहला रन देखें | -| [अवधारणाएँ](https://docs.befailproof.ai/start/concepts) | हुक सिस्टम कैसे काम करता है | -| [समर्थित हार्नेस](https://docs.befailproof.ai/reference/harnesses) | सभी 12, और प्रत्येक क्या प्रवर्तन कर सकता है | +| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Install करें, एक harness connect करें, पहला run देखें | +| [Concepts](https://docs.befailproof.ai/start/concepts) | Hook system कैसे काम करता है | +| [समर्थित harnesses](https://docs.befailproof.ai/reference/harnesses) | सभी 12, और हर एक क्या enforce कर सकता है | -| अवलोकन करें | | +| देखभाल करें | | |---|---| -| [सत्र](https://docs.befailproof.ai/sessions/overview) | एक रन का पालन करें: मॉडल, टूल, त्रुटियाँ, लेटेंसी | -| [एक ट्रेस पढ़ें](https://docs.befailproof.ai/sessions/read-a-trace) | निष्पादन ग्राफ आपको क्या बता रहा है | -| [ऑडिट](https://docs.befailproof.ai/audits/overview) | कई सत्रों में विफलता पैटर्न खोजें | -| [स्थानीय डैशबोर्ड](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, कोई खाता आवश्यक नहीं | +| [Sessions](https://docs.befailproof.ai/sessions/overview) | एक run को follow करें: models, tools, errors, latency | +| [एक trace पढ़ें](https://docs.befailproof.ai/sessions/read-a-trace) | Execution graph आपको क्या बता रहा है | +| [Audits](https://docs.befailproof.ai/audits/overview) | कई sessions में failure patterns खोजें | +| [Local dashboard](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, कोई account की आवश्यकता नहीं | -| प्रवर्तन | | +| प्रवर्तन करें | | |---|---| -| [बिल्ट-इन नीतियाँ](https://docs.befailproof.ai/policies/builtin) | सभी 39 नीतियाँ पैरामीटर के साथ | -| [कस्टम नीतियाँ](https://docs.befailproof.ai/policies/custom) | अपनी खुद की लिखें | -| [कॉन्फ़िगरेशन](https://docs.befailproof.ai/policies/local-configuration) | कॉन्फ़िग स्कोप और मर्ज नियम | +| [Policy packs](https://docs.befailproof.ai/policies/packs) | Failproof AI policies, और policy hub से packs | +| [एक policy लिखें](https://docs.befailproof.ai/policies/editor) | एक audit से, या code में | +| [Configuration](https://docs.befailproof.ai/policies/local-configuration) | Config scopes, merge rules और policy parameters | -| अपने स्वयं के एजेंट को साधन | | +| अपने स्वयं के agent को instrument करें | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | बिना हार्नेस वाले एजेंट से रन रिपोर्ट करें | -| [नीति SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` संदर्भ | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | किसी भी harness के बिना एक agent से runs रिपोर्ट करें | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` reference | --- -## लाइसेंस +## License -[Commons Clause](https://commonsclause.com/) के साथ MIT — आंतरिक और व्यक्तिगत उपयोग के लिए मुफ्त; failproofai स्वयं का वाणिज्यिक पुनर्विक्रय को एक अलग समझौते की आवश्यकता है। पूर्ण पाठ के लिए [LICENSE](../../LICENSE) देखें। +MIT with [Commons Clause](https://commonsclause.com/) — आंतरिक और व्यक्तिगत उपयोग के लिए मुक्त; failproofai का स्वयं का commercial resale एक अलग समझौते की आवश्यकता है। पूर्ण text के लिए [LICENSE](../../LICENSE) देखें। --- ## योगदान -[CONTRIBUTING.md](../../CONTRIBUTING.md) देखें। नई नीतियाँ, एज केस, और अनुवाद सभी का स्वागत है। +[CONTRIBUTING.md](../../CONTRIBUTING.md) देखें। नई policies, edge cases, और अनुवाद सभी स्वागत हैं। -> **शुरू करने से पहले बिल्ड करें।** पहले `bun install && bun run build` चलाएं। यह रिपो failproofai की अपनी हुक को -> अपने ऊपर चलाता है, और वे `failproofai` आयात को संकलित `dist/` बंडल के विरुद्ध हल करते हैं — बिल्ड के बिना -> आप `Cannot find package 'failproofai'` हुक त्रुटियों को हिट करेंगे। `src/` को बदलने के बाद -> पुनः बिल्ड करें। [बिल्ड से पहले इन-रिपो डेव हुक काम करेंगे](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) देखें। +> **शुरू करने से पहले build करें।** पहले `bun install && bun run build` चलाएं। यह repo failproofai के स्वयं के hooks को स्वयं पर चलाता है, और वे compiled `dist/` bundle के विरुद्ध `failproofai` import को resolve करते हैं — build के बिना आप `Cannot find package 'failproofai'` hook errors को hit करेंगे। `src/` बदलने के बाद rebuild करें। देखें [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)। --- -SF और बेंगलुरु में [befailproof.ai](https://befailproof.ai) द्वारा ❤️ के साथ बनाया गया। +❤️ के साथ [befailproof.ai](https://befailproof.ai) द्वारा SF और Bengaluru में निर्मित। diff --git a/docs/i18n/README.it.md b/docs/i18n/README.it.md index 4374a493..095096a2 100644 --- a/docs/i18n/README.it.md +++ b/docs/i18n/README.it.md @@ -20,22 +20,22 @@ **Traduzioni:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Osservabilità e controllo per ogni ambiente di esecuzione dei tuoi agenti.** -Dovunque i tuoi agenti vengono eseguiti, noi li vediamo — e possiamo dire di no. Failproof si integra con 12 ambienti di esecuzione — CLI di coding come Claude Code e Codex, gateway di chat come Hermes, assistenti self-hosted come OpenClaw — catturando ogni esecuzione e bloccando le chiamate agli strumenti pericolose prima che vengano eseguite. 39 politiche integrate. Latenza zero. Funziona localmente. +**Osservabilità e controllo per ogni harness su cui i tuoi agenti vengono eseguiti.** +Ovunque i tuoi agenti vengono eseguiti, noi lo vediamo — e possiamo dire no. Failproof si integra con 12 harness di agenti — CLI di coding come Claude Code e Codex, gateway di chat come Hermes, assistenti self-hosted come OpenClaw — catturando ogni esecuzione e bloccando le chiamate ai tool pericolose prima che vengano eseguite. 39 policy built-in. Zero latenza. Esecuzione locale.

- Failproof AI in azione + Failproof AI in action

--- -## Ambienti di esecuzione supportati +## Harness supportati -Dodici ambienti in due classi — dieci CLI di coding e due gateway di chat e assistenti (Hermes, OpenClaw). Gli stessi eventi, le stesse politiche, lo stesso storico sessione, indipendentemente dall'ambiente in cui viene eseguito il tuo agente. +Dodici harness in due categorie — dieci CLI di coding e due gateway di chat e assistente (Hermes, OpenClaw). Un'unica API policy e una cronologia di sessione comune a tutti. Ciò che una policy può *bloccare* è specifico dell'harness: fermare una chiamata a un tool prima che venga eseguita è verificato su tutti e dodici, i gate di fine turno su otto. La [matrice per-harness](https://docs.befailproof.ai/reference/harnesses#enforcement-capability) elenca gli eventi che ognuno gestisce. -Gli agenti che non vengono eseguiti in nessuno di questi possono fare rapporto tramite [Python SDK](https://docs.befailproof.ai/reference/custom-agents), che ti fornisce tracciamento, sessioni e audit. L'enforcement lì richiede un hook nel tuo runtime — [contattaci](mailto:support@befailproof.ai) e lo mapperemo. +Gli agenti che vengono eseguiti in nessuno di essi segnalano tramite l'[SDK Python](https://docs.befailproof.ai/reference/custom-agents), che ti fornisce tracciamento, sessioni e audit. L'enforcement lì richiede un hook nel tuo runtime — [contattaci](mailto:support@befailproof.ai) e lo mapperemo. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,37 +135,39 @@ Gli agenti che non vengono eseguiti in nessuno di questi possono fare rapporto t ```sh npm install -g failproofai -failproofai policies --install # oppure esegui semplicemente `failproofai` e accetta il prompt di prima esecuzione -failproofai +failproofai config # configura i tuoi agenti e il daemon +failproofai policies add FailproofAI/policies # scegli cosa mettere in controllo +failproofai # dashboard su localhost:8020 ``` -39 politiche integrate si attivano immediatamente. Dashboard su `localhost:8020`. Disabilita il prompt di prima esecuzione con `FAILPROOFAI_NO_FIRST_RUN=1`. +La configurazione collega gli hook e non seleziona **nessuna** policy — il secondo comando è quello che attiva i guardrail sulla macchina, e qualsiasi pack viene tipizzato nello stesso modo (`failproofai policies add /`; `policies show /` legge prima uno). Esegui `failproofai config` senza terminale — CI, un container, un agente che lo comanda — e applica piuttosto che chiedere. Su una macchina che non è mai stata configurata, qualsiasi altro comando esegue prima la stessa procedura guidata; disabilita questo con `FAILPROOFAI_NO_FIRST_RUN=1`. + +Finché un pack non arriva, l'unica cosa che fa enforcement è `block-failproofai-commands`, che è sempre attiva e non può essere disattivata o messa in pausa: un agente che può mettere in pausa l'enforcement può disattivare ogni altra policy. --- ## Cosa blocca -| Politica | Cosa blocca | +| Policy | Cosa blocca | |---|---| -| `sanitize-api-keys` | Perdita di chiavi API nel contesto dell'agente | -| `block-env-files` | Letture di `.env` e altri file segreti | -| `warn-repeated-tool-calls` | L'agente che si ripete sulla stessa chiamata | +| `block-env-files` | Letture di `.env` e altri file di secret | +| `warn-repeated-tool-calls` | L'agente che si mette in loop sulla stessa chiamata | | `block-sudo` | Escalation dei privilegi | | `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` illimitati | -| `block-terraform` / `block-kubectl` | Modifiche non verificate all'infrastruttura live | +| `block-terraform` / `block-kubectl` | Modifiche non revisionate a infrastrutture live | | `block-rm-rf` | Eliminazione ricorsiva di file | | `block-force-push` / `block-push-master` | `git push --force`, push diretti a `main` | -I primi cinque si applicano a qualsiasi agente che possa chiamare uno strumento. Gli ultimi tre sono i preferiti dagli sviluppatori — i CLI di coding sono la classe di ambienti che copriamo più profondamente. +Ognuna di queste controlla la chiamata *prima* che venga eseguita, quindi funzionano su tutti e dodici gli harness. Le prime quattro si applicano a qualsiasi agente che può chiamare un tool; le ultime tre sono i preferiti degli sviluppatori — i CLI di coding sono la classe di harness che copriamo più profondamente. La famiglia `sanitize-*` è separata: viene eseguita dopo che un tool ritorna, quindi segnala un secret nell'output del tool piuttosto che tenerlo fuori dal contesto. -→ [Tutte le 39 politiche integrate](https://docs.befailproof.ai/policies/builtin) +→ [Tutte le 39 policy built-in](https://docs.befailproof.ai/policies/packs) --- -## Le tue politiche personalizzate +## Le tue policy personali -Rilascia un file in `.failproofai/policies/` — carica automaticamente, senza flag necessari. -Committalo e l'intero team lo avrà al prossimo pull. +Rilascia un file in `.failproofai/policies/` — carica automaticamente, non sono necessari flag. +Eseguine il commit e l'intero team lo riceve al prossimo pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -181,29 +183,29 @@ customPolicies.add({ }); ``` -Tre decisioni disponibili per ogni politica: +Tre decisioni disponibili per ogni policy: | Decisione | Effetto | |---|---| | `allow()` | Consenti l'operazione | -| `deny(message)` | Blocca — il messaggio ritorna all'agente | -| `instruct(message)` | Lascia passare, ma aggiungi contesto al prossimo prompt dell'agente | +| `deny(message)` | Bloccala — il messaggio torna all'agente | +| `instruct(message)` | Lasciarla passare, ma aggiungi contesto al prossimo prompt dell'agente | -→ [Guida alle politiche personalizzate](https://docs.befailproof.ai/policies/custom) +→ [Scrivi una policy](https://docs.befailproof.ai/policies/editor) --- ## Osservabilità -L'enforcement è una metà. L'altra metà è vedere cosa ha effettivamente fatto l'agente. +L'enforcement è una metà. L'altra metà è vedere ciò che l'agente ha effettivamente fatto. -Esegui `failproofai` senza argomenti e servirà un dashboard su `localhost:8020` leggendo lo storico di esecuzione già sulla tua macchina — nessun account, nessuna registrazione, nulla che esce dal box. Ottieni l'elenco sessioni, la sequenza di chiamate modello, chiamate strumento e decisioni di hook dentro ogni esecuzione, cosa è stato bloccato e cosa la politica ha detto all'agente, e un audit offline (`failproofai audit`) che scansiona il tuo storico alla ricerca di pattern rischiosi e suggerisce politiche per fermarli. +Esegui `failproofai` senza argomenti e servirà una dashboard su `localhost:8020` leggendo la cronologia di esecuzione già sulla tua macchina — nessun account, nessuna registrazione, nulla che lasci la scatola. Ottieni l'elenco delle sessioni, la sequenza di chiamate ai modelli, chiamate ai tool e decisioni del hook dentro ogni esecuzione, ciò che è stato bloccato e cosa la policy ha detto all'agente, e un audit offline (`failproofai audit`) che scansiona la tua cronologia per pattern rischiosi e suggerisce policy per fermarli. → [Dashboard locale](https://docs.befailproof.ai/reference/local-dashboard) · [Leggi una traccia](https://docs.befailproof.ai/sessions/read-a-trace) · [Audit locale](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** è il lato hosted dello stesso modello di dati, per team che eseguono agenti su una flotta: ogni esecuzione da ogni ambiente in un'unica posizione, un grafico di esecuzione con sub-agenti paralleli su le loro corsie, latenza p50/p95/p99 per modelli, strumenti e hook, costo per modello e tracciamento della finestra di contesto, tracciamento degli errori, SQL sul tuoi tracce con dashboard condivisibili, valutazioni puntate dal tuo servizio, audit pianificati che trasformano i fallimenti ricorrenti in risultati supportati da prove, e avvisi instradati a Slack, email o un webhook firmato. L'hosting autonomo nel tuo cluster è disponibile nel piano Enterprise. +**Failproof AI Observability** è il lato hostato dello stesso modello di dati, per team che eseguono agenti su una flotta: ogni esecuzione da ogni harness in un unico posto, un grafico di esecuzione con sub-agenti paralleli su loro corsie, latenza p50/p95/p99 per modelli, tool e hook, costi per-modello e tracciamento della finestra di contesto, tracciamento degli errori, SQL sulle tue tracce con dashboard condivisibili, valutazioni puntate dal tuo servizio, audit pianificati che trasformano fallimenti ricorrenti in risultati basati su prove, e avvisi indirizzati a Slack, email o webhook firmato. L'auto-hosting nel tuo cluster è disponibile nel piano Enterprise. → [Sessioni](https://docs.befailproof.ai/sessions/overview) · [Audit](https://docs.befailproof.ai/audits/overview) · @@ -215,27 +217,27 @@ Esegui `failproofai` senza argomenti e servirà un dashboard su `localhost:8020` | Inizia | | |---|---| -| [Avvio rapido](https://docs.befailproof.ai/start/quickstart) | Installa, connetti un ambiente, vedi la prima esecuzione | +| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Installa, connetti un harness, vedi la prima esecuzione | | [Concetti](https://docs.befailproof.ai/start/concepts) | Come funziona il sistema di hook | -| [Ambienti di esecuzione supportati](https://docs.befailproof.ai/reference/harnesses) | Tutti i 12, e cosa può enforcement ciascuno | +| [Harness supportati](https://docs.befailproof.ai/reference/harnesses) | Tutti e 12, e cosa può fare enforcement ognuno | | Osserva | | |---|---| -| [Sessioni](https://docs.befailproof.ai/sessions/overview) | Segui un'esecuzione: modelli, strumenti, errori, latenza | +| [Sessioni](https://docs.befailproof.ai/sessions/overview) | Segui un'esecuzione: modelli, tool, errori, latenza | | [Leggi una traccia](https://docs.befailproof.ai/sessions/read-a-trace) | Cosa ti sta dicendo il grafico di esecuzione | -| [Audit](https://docs.befailproof.ai/audits/overview) | Trova pattern di fallimento tra molte sessioni | +| [Audit](https://docs.befailproof.ai/audits/overview) | Trova pattern di errore su molte sessioni | | [Dashboard locale](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, nessun account necessario | -| Enforcement | | +| Applica | | |---|---| -| [Politiche integrate](https://docs.befailproof.ai/policies/builtin) | Tutte le 39 politiche con parametri | -| [Politiche personalizzate](https://docs.befailproof.ai/policies/custom) | Scrivi la tua | -| [Configurazione](https://docs.befailproof.ai/policies/local-configuration) | Scope di configurazione e regole di merge | +| [Pack di policy](https://docs.befailproof.ai/policies/packs) | Le policy Failproof AI e i pack dall'hub di policy | +| [Scrivi una policy](https://docs.befailproof.ai/policies/editor) | Da un audit, o nel codice | +| [Configurazione](https://docs.befailproof.ai/policies/local-configuration) | Ambiti di configurazione, regole di merge e parametri di policy | -| Strumenta il tuo agente personalizzato | | +| Strumenta il tuo agente personale | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Fai rapporto di esecuzioni da un agente senza ambiente | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Riferimento `allow` / `deny` / `instruct` | +| [SDK Python](https://docs.befailproof.ai/reference/custom-agents) | Segnala esecuzioni da un agente senza harness | +| [SDK Policy](https://docs.befailproof.ai/reference/policy-sdk) | Riferimento `allow` / `deny` / `instruct` | --- @@ -247,9 +249,9 @@ MIT con [Commons Clause](https://commonsclause.com/) — gratuito per uso intern ## Contribuire -Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md). Nuove politiche, casi limite e traduzioni sono tutte benvenute. +Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md). Nuove policy, casi limite e traduzioni sono tutti benvenuti. -> **Costruisci prima di iniziare.** Esegui `bun install && bun run build` per primo. Questo repository esegue i propri hook di failproofai su se stesso, e risolvono l'import `failproofai` nel bundle compilato `dist/` — senza una build otterrai errori di hook `Cannot find package 'failproofai'`. Ricostruisci dopo aver modificato `src/`. Vedi [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Compila prima di iniziare.** Esegui `bun install && bun run build` per primo. Questo repository esegue gli hook di failproofai su se stesso, e risolvono l'import `failproofai` contro il bundle compilato `dist/` — senza una compilazione riceverai errori hook `Cannot find package 'failproofai'`. Ricompila dopo aver modificato `src/`. Vedi [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.ja.md b/docs/i18n/README.ja.md index 52540d27..75161bbb 100644 --- a/docs/i18n/README.ja.md +++ b/docs/i18n/README.ja.md @@ -20,8 +20,8 @@ **翻訳:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**あらゆるハーネス上のエージェントに、可観測性と制御を。** -エージェントがどこで動いていても、Failproofはそれを把握し、必要とあれば止めます。Failproofは12種類のエージェントハーネスにフックし、Claude Code や Codex のようなコーディング CLI、Hermes のようなチャットゲートウェイ、OpenClaw のようなセルフホスト型アシスタントを対象に、すべての実行をキャプチャし、危険なツール呼び出しを実行前にブロックします。39種類の組み込みポリシー。レイテンシーゼロ。ローカルで動作。 +**エージェントが動作するあらゆるハーネスに対応したオブザーバビリティと制御。** +エージェントがどこで動いていても、私たちはすべてを把握し、必要なら止めることができます。Failproof は 12 種類のエージェントハーネスにフックし — Claude Code や Codex のようなコーディング CLI、Hermes のようなチャットゲートウェイ、OpenClaw のようなセルフホスト型アシスタント — すべての実行をキャプチャし、危険なツール呼び出しを実行前にブロックします。39 個の組み込みポリシー。ゼロレイテンシー。ローカル実行。 @@ -33,9 +33,9 @@ ## 対応ハーネス -12種類のハーネスは2つのクラスに分かれます。コーディング CLI が10種類、チャット・アシスタントゲートウェイ（Hermes、OpenClaw）が2種類です。エージェントがどのハーネスで動いていても、イベント、ポリシー、セッション履歴はすべて共通です。 +12 種類のハーネスを 2 つのカテゴリに分類しています — コーディング CLI が 10 種類、チャット・アシスタントゲートウェイ（Hermes、OpenClaw）が 2 種類です。すべてのハーネスで共通のポリシー API とセッション履歴を使用します。ポリシーで*ブロック*できる内容はハーネスごとに異なります。ツール呼び出しを実行前に停止する機能は 12 種類すべてで検証済み、ターン終了ゲートは 8 種類で対応しています。[ハーネス別対応表](https://docs.befailproof.ai/reference/harnesses#enforcement-capability)には各ハーネスが処理するイベントの一覧が掲載されています。 -どのハーネスにも属さないエージェントは [Python SDK](https://docs.befailproof.ai/reference/custom-agents) 経由でレポートできます。トレーシング、セッション、監査機能を利用可能です。そのハーネスでの制御には独自ランタイムへのフックが必要です。詳細は[お問い合わせください](mailto:support@befailproof.ai)。 +いずれのハーネスでも動作しないエージェントは [Python SDK](https://docs.befailproof.ai/reference/custom-agents) を通じてレポートでき、トレーシング、セッション管理、監査機能が利用できます。その場合の制御には独自ランタイムへのフック実装が必要です — [お問い合わせ](mailto:support@befailproof.ai)いただければ対応方法をご案内します。 {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,11 +135,14 @@ ```sh npm install -g failproofai -failproofai policies --install # または `failproofai` を実行して初回プロンプトを承認 -failproofai +failproofai config # エージェントとデーモンを接続する +failproofai policies add FailproofAI/policies # 適用するポリシーを選択する +failproofai # localhost:8020 でダッシュボードを起動 ``` -39種類の組み込みポリシーが即座に有効化されます。ダッシュボードは `localhost:8020` で確認できます。初回プロンプトを無効にするには `FAILPROOFAI_NO_FIRST_RUN=1` を設定してください。 +セットアップはフックを接続しますが、ポリシーは**何も**適用しません — 2 番目のコマンドがマシンにガードレールを設定します。パックはすべて同じ形式で指定できます（`failproofai policies add /`。`policies show /` で内容を先に確認できます）。ターミナルなしで `failproofai config` を実行すると — CI 環境、コンテナ、それを操作するエージェントからでも — 対話形式ではなく自動的に設定が適用されます。まだセットアップされていないマシンでは、他のコマンドを実行すると最初に同じウィザードが起動します。`FAILPROOFAI_NO_FIRST_RUN=1` で無効にできます。 + +パックが導入されるまでの間、`block-failproofai-commands` のみが有効な制御として機能します。これは常時オンで、無効化や一時停止はできません。制御を一時停止できるエージェントは、他のすべてのポリシーも無効にできてしまうためです。 --- @@ -147,8 +150,7 @@ failproofai | ポリシー | ブロック対象 | |---|---| -| `sanitize-api-keys` | エージェントのコンテキストへの API キー漏洩 | -| `block-env-files` | `.env` などのシークレットファイルの読み込み | +| `block-env-files` | `.env` などのシークレットファイルの読み取り | | `warn-repeated-tool-calls` | 同じ呼び出しをループするエージェント | | `block-sudo` | 権限昇格 | | `warn-destructive-sql` | `DROP`、`TRUNCATE`、条件なし `DELETE` | @@ -156,16 +158,15 @@ failproofai | `block-rm-rf` | 再帰的なファイル削除 | | `block-force-push` / `block-push-master` | `git push --force`、`main` への直接プッシュ | -最初の5つはツールを呼び出せるすべてのエージェントに適用されます。残り3つは開発者に特に人気があります。コーディング CLI は私たちが最も深くカバーするハーネスクラスです。 +これらはすべて呼び出しが実行される*前*にゲートするため、12 種類すべてのハーネスで機能します。最初の 4 つはツールを呼び出せる任意のエージェントに適用されます。残りの 3 つは開発者に特に人気のポリシーで、コーディング CLI は私たちが最も深くカバーするハーネスクラスです。`sanitize-*` ファミリーは別扱いで、ツールの戻り値の後に実行されるため、コンテキストへの混入を防ぐのではなく、ツール出力にシークレットが含まれていることを報告します。 -→ [39種類すべての組み込みポリシー](https://docs.befailproof.ai/policies/builtin) +→ [39 個の組み込みポリシー一覧](https://docs.befailproof.ai/policies/packs) --- -## 独自ポリシーの作成 +## カスタムポリシー -`.failproofai/policies/` にファイルを置くだけで自動的に読み込まれます。フラグは不要です。 -コミットすれば、次回プル時にチーム全員に適用されます。 +`.failproofai/policies/` にファイルを置くだけで自動的に読み込まれます — フラグの指定は不要です。コミットすれば、チーム全員が次回のプルで同じポリシーを受け取ります。 ```js import { customPolicies, deny, allow } from "failproofai"; @@ -181,7 +182,7 @@ customPolicies.add({ }); ``` -各ポリシーで使用できる3つの判定: +各ポリシーで使用できる 3 種類の判定: | 判定 | 効果 | |---|---| @@ -189,50 +190,50 @@ customPolicies.add({ | `deny(message)` | ブロックする — メッセージがエージェントに返される | | `instruct(message)` | 通過させるが、エージェントの次のプロンプトにコンテキストを追加する | -→ [カスタムポリシーガイド](https://docs.befailproof.ai/policies/custom) +→ [ポリシーを書く](https://docs.befailproof.ai/policies/editor) --- -## 可観測性 +## オブザーバビリティ -制御は機能の半分にすぎません。もう半分は、エージェントが実際に何をしたかを把握することです。 +制御は機能の半分に過ぎません。もう半分は、エージェントが実際に何をしたかを把握することです。 -引数なしで `failproofai` を実行すると、`localhost:8020` にダッシュボードが起動し、マシン上の実行履歴を読み込みます。アカウント不要、サインアップ不要、データは外部に送信されません。セッション一覧、モデル呼び出しのシーケンス、各実行内のツール呼び出しとフックの判定、ブロックされた内容とポリシーがエージェントに伝えた内容、そしてオフライン監査（`failproofai audit`）により履歴をスキャンしてリスクのあるパターンを検出し、対処するポリシーを提案します。 +引数なしで `failproofai` を実行すると、マシン上にすである実行履歴を読み込んで `localhost:8020` でダッシュボードを提供します — アカウント不要、サインアップ不要、データがマシンの外に出ることもありません。セッション一覧、モデル呼び出しのシーケンス、各実行内のツール呼び出しとフックの判定、ブロックされた内容とポリシーがエージェントに伝えた内容、そしてオフライン監査（`failproofai audit`）として履歴をスキャンしてリスクのあるパターンを検出し、対処するポリシーを提案します。 → [ローカルダッシュボード](https://docs.befailproof.ai/reference/local-dashboard) · [トレースを読む](https://docs.befailproof.ai/sessions/read-a-trace) · [ローカル監査](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** は同じデータモデルのホスト型サービスで、フリートでエージェントを運用するチーム向けです。すべてのハーネスからのすべての実行を一か所に集約し、並列サブエージェントを独立したレーンで表示する実行グラフ、モデル・ツール・フックの p50/p95/p99 レイテンシー、モデルごとのコストとコンテキストウィンドウのトラッキング、エラートラッキング、共有可能なダッシュボード付きの独自トレースへの SQL クエリ、独自サービスによるスコアリング評価、繰り返す失敗をエビデンスに基づく知見に変えるスケジュール監査、Slack・メール・署名付き Webhook へのアラート配信を提供します。Enterprise プランでは独自クラスターへのセルフホスティングも利用可能です。 +**Failproof AI Observability** は同じデータモデルのホスト型サービスで、複数マシンでエージェントを運用するチーム向けです。すべてのハーネスからのすべての実行を一か所で管理、並列サブエージェントを個別レーンで表示する実行グラフ、モデル・ツール・フックの p50/p95/p99 レイテンシー、モデルごとのコストとコンテキストウィンドウのトラッキング、エラートラッキング、共有可能なダッシュボード付きの独自トレースへの SQL クエリ、独自サービスでスコアリングする評価機能、繰り返し発生する障害をエビデンスに基づく知見として記録するスケジュール監査、Slack・メール・署名付き Webhook へのアラート通知が利用できます。Enterprise プランでは独自クラスターへのセルフホスティングも対応しています。 → [セッション](https://docs.befailproof.ai/sessions/overview) · [監査](https://docs.befailproof.ai/audits/overview) · -[デモを予約](https://befailproof.ai/get-a-demo) +[デモを予約する](https://befailproof.ai/get-a-demo) --- ## ドキュメント -| はじめる | | +| はじめに | | |---|---| -| [クイックスタート](https://docs.befailproof.ai/start/quickstart) | インストール、ハーネスへの接続、初回実行の確認 | +| [クイックスタート](https://docs.befailproof.ai/start/quickstart) | インストール、ハーネスの接続、初回実行の確認 | | [コンセプト](https://docs.befailproof.ai/start/concepts) | フックシステムの仕組み | -| [対応ハーネス](https://docs.befailproof.ai/reference/harnesses) | 全12種類と各ハーネスで制御できること | +| [対応ハーネス](https://docs.befailproof.ai/reference/harnesses) | 12 種類すべてと各ハーネスで制御できること | -| 観測する | | +| 監視 | | |---|---| -| [セッション](https://docs.befailproof.ai/sessions/overview) | 実行を追跡する：モデル、ツール、エラー、レイテンシー | +| [セッション](https://docs.befailproof.ai/sessions/overview) | 実行を追う：モデル、ツール、エラー、レイテンシー | | [トレースを読む](https://docs.befailproof.ai/sessions/read-a-trace) | 実行グラフが示していること | -| [監査](https://docs.befailproof.ai/audits/overview) | 多数のセッションにわたる失敗パターンを発見する | +| [監査](https://docs.befailproof.ai/audits/overview) | 多くのセッションにまたがる障害パターンを見つける | | [ローカルダッシュボード](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`、アカウント不要 | -| 制御する | | +| 制御 | | |---|---| -| [組み込みポリシー](https://docs.befailproof.ai/policies/builtin) | パラメーター付きの全39ポリシー | -| [カスタムポリシー](https://docs.befailproof.ai/policies/custom) | 独自ポリシーを作成する | -| [設定](https://docs.befailproof.ai/policies/local-configuration) | 設定スコープとマージルール | +| [ポリシーパック](https://docs.befailproof.ai/policies/packs) | Failproof AI のポリシーとポリシーハブのパック | +| [ポリシーを書く](https://docs.befailproof.ai/policies/editor) | 監査結果から、またはコードで作成 | +| [設定](https://docs.befailproof.ai/policies/local-configuration) | 設定スコープ、マージルール、ポリシーパラメーター | -| 独自エージェントを計装する | | +| 独自エージェントの計測 | | |---|---| | [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | ハーネスなしのエージェントから実行をレポートする | | [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` リファレンス | @@ -241,7 +242,7 @@ customPolicies.add({ ## ライセンス -MIT with [Commons Clause](https://commonsclause.com/) — 社内利用および個人利用は無料です。failproofai 自体の商用再販には別途契約が必要です。全文は [LICENSE](../../LICENSE) をご覧ください。 +MIT に [Commons Clause](https://commonsclause.com/) を付加したライセンス — 社内利用および個人利用は無料。failproofai 自体の商業的な再販には別途契約が必要です。全文は [LICENSE](../../LICENSE) をご覧ください。 --- @@ -249,8 +250,8 @@ MIT with [Commons Clause](https://commonsclause.com/) — 社内利用および [CONTRIBUTING.md](../../CONTRIBUTING.md) をご覧ください。新しいポリシー、エッジケースの対応、翻訳はいずれも歓迎します。 -> **作業前にビルドしてください。** 最初に `bun install && bun run build` を実行してください。このリポジトリは failproofai 自身のフックを自分自身に適用しており、フックはコンパイル済みの `dist/` バンドルに対して `failproofai` インポートを解決します。ビルドなしでは `Cannot find package 'failproofai'` というフックエラーが発生します。`src/` を変更した後は再ビルドしてください。詳細は [リポジトリ内開発用フックを動作させるためのビルド手順](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) をご覧ください。 +> **開始前にビルドしてください。** 最初に `bun install && bun run build` を実行してください。このリポジトリは failproofai 自身のフックを自分自身に適用しており、フックは `failproofai` のインポートをコンパイル済みの `dist/` バンドルに対して解決します — ビルドなしでは `Cannot find package 'failproofai'` というフックエラーが発生します。`src/` を変更した後は再ビルドしてください。詳細は [リポジトリ内の開発用フックを動かすにはビルドが必要](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) をご覧ください。 --- -❤️ を込めて [befailproof.ai](https://befailproof.ai) がサンフランシスコとベンガルールで開発。 +SF とベンガルールの [befailproof.ai](https://befailproof.ai) チームが ❤️ を込めて開発しています。 diff --git a/docs/i18n/README.ko.md b/docs/i18n/README.ko.md index 669d7c9b..b6a3e9df 100644 --- a/docs/i18n/README.ko.md +++ b/docs/i18n/README.ko.md @@ -20,11 +20,11 @@ **번역:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**에이전트가 실행되는 모든 하네스를 위한 옵저버빌리티와 정책 집행.** -에이전트가 어디서 실행되든 우리는 그것을 감지하며, 차단할 수 있습니다. Failproof는 12개의 에이전트 -하네스에 훅을 제공합니다 — Claude Code, Codex 같은 코딩 CLI, Hermes 같은 채팅 게이트웨이, -OpenClaw 같은 셀프 호스팅 어시스턴트 — 모든 실행을 캡처하고, 위험한 툴 호출이 -실행되기 전에 차단합니다. 기본 제공 정책 39개. 지연 없음. 로컬에서 실행. +**에이전트가 실행되는 모든 하네스를 위한 관측성과 정책 집행.** +에이전트가 어디서 실행되든 우리는 확인하고 — 차단할 수 있습니다. Failproof는 12개의 에이전트 +하네스를 후킹합니다 — Claude Code, Codex 같은 코딩 CLI, Hermes 같은 채팅 게이트웨이, +OpenClaw 같은 자체 호스팅 어시스턴트 — 모든 실행을 캡처하고 위험한 +툴 호출을 실행 전에 차단합니다. 기본 제공 정책 39개. 레이턴시 없음. 로컬에서 실행. @@ -36,11 +36,10 @@ OpenClaw 같은 셀프 호스팅 어시스턴트 — 모든 실행을 캡처하 ## 지원 하네스 -두 가지 유형의 하네스 12개 — 코딩 CLI 10개, 채팅 및 어시스턴트 게이트웨이(Hermes, OpenClaw) 2개. -에이전트가 어느 하네스에서 실행되든 동일한 이벤트, 동일한 정책, 동일한 세션 이력을 사용합니다. +두 가지 클래스로 나뉜 12개의 하네스 — 코딩 CLI 10개, 채팅 및 어시스턴트 게이트웨이 2개(Hermes, OpenClaw). 모든 하네스에 걸쳐 하나의 정책 API와 하나의 세션 히스토리를 공유합니다. 정책이 *차단*할 수 있는 범위는 하네스마다 다릅니다. 툴 호출을 실행 전에 멈추는 기능은 12개 모두에서 검증되었으며, 턴 종료 게이트는 8개에서 작동합니다. +[하네스별 매트릭스](https://docs.befailproof.ai/reference/harnesses#enforcement-capability)에서 각 하네스가 지원하는 이벤트를 확인할 수 있습니다. -이 중 어느 것도 사용하지 않는 에이전트는 [Python SDK](https://docs.befailproof.ai/reference/custom-agents)를 통해 보고할 수 있으며, -트레이싱, 세션, 감사 기능을 제공합니다. 해당 환경에서의 정책 집행은 별도의 런타임 훅이 필요합니다 — [문의하시면](mailto:support@befailproof.ai) 적용 방법을 안내해 드립니다. +12개 하네스 중 어디에도 속하지 않는 에이전트는 [Python SDK](https://docs.befailproof.ai/reference/custom-agents)를 통해 보고하며, 트레이싱, 세션, 감사 기능을 제공합니다. 해당 환경에서의 정책 집행은 자체 런타임에 훅이 필요합니다 — [문의하시면](mailto:support@befailproof.ai) 매핑을 도와드립니다. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -140,38 +139,40 @@ OpenClaw 같은 셀프 호스팅 어시스턴트 — 모든 실행을 캡처하 ```sh npm install -g failproofai -failproofai policies --install # 또는 `failproofai`를 실행하고 첫 실행 프롬프트에서 수락 -failproofai +failproofai config # 에이전트와 데몬 연결 설정 +failproofai policies add FailproofAI/policies # 적용할 정책 선택 +failproofai # localhost:8020에서 대시보드 실행 ``` -기본 제공 정책 39개가 즉시 활성화됩니다. 대시보드는 `localhost:8020`에서 확인하세요. `FAILPROOFAI_NO_FIRST_RUN=1`로 첫 실행 프롬프트를 비활성화할 수 있습니다. +설정은 훅을 연결하되 정책을 **아무것도** 적용하지 않습니다 — 두 번째 명령이 머신에 가드레일을 설치하는 역할을 하며, 모든 팩은 동일한 방식으로 지정합니다 +(`failproofai policies add /`; `policies show /`로 먼저 내용을 확인할 수 있습니다). 터미널 없이 `failproofai config`를 실행하면 — CI, 컨테이너, 에이전트가 직접 구동하는 경우 — 묻지 않고 바로 적용합니다. 한 번도 설정되지 않은 머신에서는 다른 명령을 실행해도 동일한 설정 마법사가 먼저 실행됩니다. `FAILPROOFAI_NO_FIRST_RUN=1`로 이를 비활성화할 수 있습니다. + +팩이 추가되기 전까지는 `block-failproofai-commands`만 정책을 집행합니다. 이 정책은 항상 활성화되어 있으며 끄거나 일시 중지할 수 없습니다. 집행을 일시 중지할 수 있는 에이전트는 다른 모든 정책도 끌 수 있기 때문입니다. --- -## 차단 항목 +## 차단 대상 -| 정책 | 차단 대상 | +| 정책 | 차단 내용 | |---|---| -| `sanitize-api-keys` | 에이전트 컨텍스트로 유출되는 API 키 | | `block-env-files` | `.env` 및 기타 시크릿 파일 읽기 | -| `warn-repeated-tool-calls` | 동일한 호출을 반복하는 에이전트 루프 | +| `warn-repeated-tool-calls` | 동일한 툴 호출을 반복하는 에이전트 루프 | | `block-sudo` | 권한 상승 | | `warn-destructive-sql` | `DROP`, `TRUNCATE`, 조건 없는 `DELETE` | | `block-terraform` / `block-kubectl` | 검토되지 않은 라이브 인프라 변경 | | `block-rm-rf` | 재귀적 파일 삭제 | -| `block-force-push` / `block-push-master` | `git push --force`, `main`으로의 직접 푸시 | +| `block-force-push` / `block-push-master` | `git push --force`, `main` 브랜치로의 직접 푸시 | -처음 다섯 개는 툴을 호출할 수 있는 모든 에이전트에 적용됩니다. 마지막 세 개는 -개발자들이 가장 선호하는 정책으로 — 코딩 CLI는 우리가 가장 깊이 지원하는 하네스 유형입니다. +이 모든 정책은 툴 호출을 실행 *전에* 차단하므로 12개 하네스 모두에서 동작합니다. 처음 네 가지는 툴을 호출할 수 있는 모든 에이전트에 적용되고, 나머지 세 가지는 개발자들이 가장 선호하는 정책입니다 — 코딩 CLI는 우리가 가장 깊이 지원하는 하네스 클래스입니다. `sanitize-*` 계열은 별도로 작동합니다. 툴이 반환된 후 실행되므로, 시크릿이 컨텍스트에 포함되지 않도록 막는 것이 아니라 툴 출력에서 시크릿을 감지해 보고합니다. -→ [기본 제공 정책 39개 전체 목록](https://docs.befailproof.ai/policies/builtin) +→ [39개의 기본 제공 정책 전체 보기](https://docs.befailproof.ai/policies/packs) --- ## 커스텀 정책 -`.failproofai/policies/` 디렉토리에 파일을 추가하면 별도의 플래그 없이 자동으로 로드됩니다. -커밋하면 팀 전체가 다음 풀 시 적용받습니다. +`.failproofai/policies/` 디렉터리에 파일을 추가하면 자동으로 로드됩니다 — 별도의 플래그가 필요 없습니다. +커밋하면 팀 전체가 다음 풀 때 적용됩니다. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -187,32 +188,29 @@ customPolicies.add({ }); ``` -모든 정책에서 사용 가능한 세 가지 결정: +모든 정책에서 사용할 수 있는 세 가지 결정: | 결정 | 효과 | |---|---| | `allow()` | 작업 허용 | -| `deny(message)` | 차단 — 메시지가 에이전트로 반환됨 | -| `instruct(message)` | 통과 허용, 에이전트의 다음 프롬프트에 컨텍스트 추가 | +| `deny(message)` | 차단 — 메시지가 에이전트에게 반환됨 | +| `instruct(message)` | 통과시키되, 에이전트의 다음 프롬프트에 컨텍스트 추가 | -→ [커스텀 정책 가이드](https://docs.befailproof.ai/policies/custom) +→ [정책 작성하기](https://docs.befailproof.ai/policies/editor) --- -## 옵저버빌리티 +## 관측성 -정책 집행은 한 축입니다. 다른 한 축은 에이전트가 실제로 무엇을 했는지 확인하는 것입니다. +정책 집행은 절반에 불과합니다. 나머지 절반은 에이전트가 실제로 무엇을 했는지 파악하는 것입니다. -`failproofai`를 인수 없이 실행하면 `localhost:8020`에 대시보드가 실행되며, -이미 로컬에 저장된 실행 기록을 읽어옵니다 — 계정도, 회원 가입도, 외부 전송도 필요 없습니다. -세션 목록, 각 실행 내의 모델 호출 순서, 툴 호출 및 훅 결정, 차단된 항목과 정책이 에이전트에게 전달한 내용, -그리고 오프라인 감사(`failproofai audit`) — 실행 이력에서 위험 패턴을 스캔하고 이를 방지할 정책을 제안합니다. +인수 없이 `failproofai`를 실행하면 `localhost:8020`에서 대시보드가 시작되며, 이미 머신에 저장된 실행 히스토리를 읽어옵니다 — 계정도, 회원가입도, 외부 전송도 없습니다. 세션 목록, 각 실행 내의 모델 호출 순서, 툴 호출, 훅 결정, 차단된 내용과 정책이 에이전트에 전달한 내용, 그리고 히스토리에서 위험 패턴을 스캔하고 차단할 정책을 제안하는 오프라인 감사(`failproofai audit`)를 제공합니다. → [로컬 대시보드](https://docs.befailproof.ai/reference/local-dashboard) · [트레이스 읽기](https://docs.befailproof.ai/sessions/read-a-trace) · [로컬 감사](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability**는 동일한 데이터 모델의 호스팅 버전으로, 다수의 서버에서 에이전트를 운영하는 팀을 위해 설계되었습니다: 모든 하네스의 모든 실행을 한 곳에서, 병렬 서브 에이전트가 각자의 레인에 표시되는 실행 그래프, 모델·툴·훅의 p50/p95/p99 레이턴시, 모델별 비용 및 컨텍스트 윈도우 추적, 오류 추적, 공유 가능한 대시보드를 포함한 트레이스 SQL 쿼리, 자체 서비스로 평가하는 에벌루에이션, 반복 실패를 근거 기반 발견으로 전환하는 예약 감사, Slack·이메일·서명된 웹훅으로 전달되는 알림. 자체 클러스터에서의 셀프 호스팅은 엔터프라이즈 플랜에서 이용 가능합니다. +**Failproof AI Observability**는 동일한 데이터 모델의 호스팅 버전으로, 플릿 전체에서 에이전트를 운영하는 팀을 위한 서비스입니다. 모든 하네스의 모든 실행을 한 곳에서 확인하고, 병렬 서브에이전트를 별도 레인으로 표시하는 실행 그래프, 모델·툴·훅의 p50/p95/p99 레이턴시, 모델별 비용 및 컨텍스트 윈도우 추적, 오류 추적, 공유 가능한 대시보드를 갖춘 자체 트레이스 SQL 쿼리, 자체 서비스로 점수를 매기는 평가, 반복적인 실패를 증거 기반 결과로 변환하는 예약 감사, Slack·이메일·서명된 웹훅으로의 알림 라우팅을 제공합니다. Enterprise 플랜에서는 자체 클러스터 셀프 호스팅도 지원합니다. → [세션](https://docs.befailproof.ai/sessions/overview) · [감사](https://docs.befailproof.ai/audits/overview) · @@ -224,44 +222,44 @@ customPolicies.add({ | 시작하기 | | |---|---| -| [빠른 시작](https://docs.befailproof.ai/start/quickstart) | 설치, 하네스 연결, 첫 실행 확인 | -| [개념](https://docs.befailproof.ai/start/concepts) | 훅 시스템의 작동 방식 | -| [지원 하네스](https://docs.befailproof.ai/reference/harnesses) | 12개 전체와 각각의 집행 가능 항목 | +| [빠른 시작](https://docs.befailproof.ai/start/quickstart) | 설치, 하네스 연결, 첫 번째 실행 확인 | +| [개념](https://docs.befailproof.ai/start/concepts) | 훅 시스템 작동 방식 | +| [지원 하네스](https://docs.befailproof.ai/reference/harnesses) | 12개 전체 및 각 하네스의 집행 범위 | -| 관찰 | | +| 관측 | | |---|---| | [세션](https://docs.befailproof.ai/sessions/overview) | 실행 추적: 모델, 툴, 오류, 레이턴시 | | [트레이스 읽기](https://docs.befailproof.ai/sessions/read-a-trace) | 실행 그래프가 말해주는 것 | -| [감사](https://docs.befailproof.ai/audits/overview) | 여러 세션에서 실패 패턴 찾기 | +| [감사](https://docs.befailproof.ai/audits/overview) | 여러 세션에 걸친 실패 패턴 탐지 | | [로컬 대시보드](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, 계정 불필요 | | 집행 | | |---|---| -| [기본 제공 정책](https://docs.befailproof.ai/policies/builtin) | 매개변수를 포함한 39개 정책 전체 | -| [커스텀 정책](https://docs.befailproof.ai/policies/custom) | 직접 작성하기 | -| [설정](https://docs.befailproof.ai/policies/local-configuration) | 설정 범위 및 병합 규칙 | +| [정책 팩](https://docs.befailproof.ai/policies/packs) | Failproof AI 정책 및 정책 허브의 팩 | +| [정책 작성하기](https://docs.befailproof.ai/policies/editor) | 감사 결과 기반 또는 코드로 직접 작성 | +| [설정](https://docs.befailproof.ai/policies/local-configuration) | 설정 스코프, 병합 규칙 및 정책 파라미터 | -| 에이전트 직접 계측 | | +| 커스텀 에이전트 연동 | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | 하네스 없는 에이전트에서 실행 보고 | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` 레퍼런스 | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | 하네스 없이 에이전트 실행을 보고 | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | allow / deny / instruct 레퍼런스 | --- ## 라이선스 -[Commons Clause](https://commonsclause.com/)가 적용된 MIT — 내부 및 개인 사용은 무료이며, failproofai 자체의 상업적 재판매는 별도 계약이 필요합니다. 전체 내용은 [LICENSE](../../LICENSE)를 참조하세요. +[Commons Clause](https://commonsclause.com/)가 포함된 MIT 라이선스 — 내부 및 개인 사용은 무료이며, failproofai 자체의 상업적 재판매는 별도 계약이 필요합니다. 전문은 [LICENSE](../../LICENSE)를 참조하세요. --- -## 기여 +## 기여하기 [CONTRIBUTING.md](../../CONTRIBUTING.md)를 참조하세요. 새로운 정책, 엣지 케이스, 번역 모두 환영합니다. > **시작 전에 빌드하세요.** 먼저 `bun install && bun run build`를 실행하세요. 이 저장소는 -> failproofai 자체의 훅을 자기 자신에게 적용하며, 컴파일된 `dist/` 번들에 대해 `failproofai` 임포트를 해석합니다 — 빌드 없이는 `Cannot find package 'failproofai'` -> 훅 오류가 발생합니다. `src/`를 변경한 후에는 다시 빌드하세요. -> [리포 내 개발 훅이 작동하려면 빌드를 먼저 하세요](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)를 참조하세요. +> failproofai 자체 훅을 자기 자신에게 적용하며, 훅은 컴파일된 `dist/` 번들에서 `failproofai` 임포트를 해석합니다 — 빌드 없이는 `Cannot find package 'failproofai'` +> 훅 오류가 발생합니다. `src/` 변경 후에는 다시 빌드하세요. 자세한 내용은 +> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)를 참조하세요. --- diff --git a/docs/i18n/README.pt-br.md b/docs/i18n/README.pt-br.md index 614f9041..fdaca107 100644 --- a/docs/i18n/README.pt-br.md +++ b/docs/i18n/README.pt-br.md @@ -20,8 +20,8 @@ **Traduções:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Observabilidade e controle para cada ambiente em que seus agentes rodam.** -Onde quer que seus agentes executem, nós enxergamos — e podemos dizer não. O Failproof se integra a 12 ambientes de agentes — CLIs de codificação como Claude Code e Codex, gateways de chat como Hermes, assistentes auto-hospedados como OpenClaw — capturando cada execução e bloqueando chamadas de ferramentas perigosas antes que sejam realizadas. 39 políticas nativas. Zero latência. Roda localmente. +**Observabilidade e controle de acesso para todos os harnesses em que seus agentes rodam.** +Onde quer que seus agentes executem, nós enxergamos — e podemos dizer não. O Failproof conecta 12 harnesses de agentes — CLIs de codificação como Claude Code e Codex, gateways de chat como Hermes, assistentes auto-hospedados como OpenClaw — capturando cada execução e bloqueando chamadas de ferramentas perigosas antes que aconteçam. 39 políticas embutidas. Zero latência. Roda localmente. @@ -31,11 +31,11 @@ Onde quer que seus agentes executem, nós enxergamos — e podemos dizer não. O --- -## Ambientes suportados +## Harnesses suportados -Doze ambientes em duas categorias — dez CLIs de codificação e dois gateways de chat e assistente (Hermes, OpenClaw). Mesmos eventos, mesmas políticas, mesmo histórico de sessões, independentemente do ambiente em que seu agente roda. +Doze harnesses em duas classes — dez CLIs de codificação e dois gateways de chat e assistente (Hermes, OpenClaw). Uma única API de políticas e um único histórico de sessões para todos eles. O que uma política pode *bloquear* varia por harness: interromper uma chamada de ferramenta antes de executar está verificado nos doze; portões de fim de turno funcionam em oito. A [matriz por harness](https://docs.befailproof.ai/reference/harnesses#enforcement-capability) lista os eventos que cada um respeita. -Agentes que não rodam em nenhum deles reportam pelo [SDK Python](https://docs.befailproof.ai/reference/custom-agents), que oferece rastreamento, sessões e auditorias. O enforcement nesses casos requer um hook no seu próprio runtime — [fale conosco](mailto:support@befailproof.ai) e vamos mapear a solução juntos. +Agentes que não rodam em nenhum deles reportam via [Python SDK](https://docs.befailproof.ai/reference/custom-agents), que oferece rastreamento, sessões e auditorias. Enforcement nesses casos requer um hook no seu próprio runtime — [fale conosco](mailto:support@befailproof.ai) e mapeamos juntos. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,11 +135,14 @@ Agentes que não rodam em nenhum deles reportam pelo [SDK Python](https://docs.b ```sh npm install -g failproofai -failproofai policies --install # ou simplesmente execute `failproofai` e aceite o prompt da primeira execução -failproofai +failproofai config # conecte seus agentes e o daemon +failproofai policies add FailproofAI/policies # escolha o que aplicar +failproofai # dashboard em localhost:8020 ``` -39 políticas nativas são ativadas imediatamente. Dashboard em `localhost:8020`. Desative o prompt da primeira execução com `FAILPROOFAI_NO_FIRST_RUN=1`. +A configuração conecta os hooks e não seleciona **nenhuma** política — o segundo comando é o que coloca as proteções na máquina, e qualquer pacote é adicionado da mesma forma (`failproofai policies add /`; `policies show /` lê um antes). Execute `failproofai config` sem terminal — em CI, num container, com um agente controlando — e ele aplica as configurações em vez de perguntar. Em uma máquina que nunca foi configurada, qualquer outro comando executa o mesmo assistente primeiro; desative isso com `FAILPROOFAI_NO_FIRST_RUN=1`. + +Até que um pacote chegue, a única coisa em vigor é `block-failproofai-commands`, que está sempre ativa e não pode ser desligada ou pausada: um agente que pode pausar o enforcement consegue desligar todas as outras políticas. --- @@ -147,25 +150,23 @@ failproofai | Política | O que bloqueia | |---|---| -| `sanitize-api-keys` | Vazamento de chaves de API para o contexto do agente | -| `block-env-files` | Leitura de arquivos `.env` e outros arquivos de segredos | -| `warn-repeated-tool-calls` | O agente entrando em loop na mesma chamada | +| `block-env-files` | Leitura de `.env` e outros arquivos de segredos | +| `warn-repeated-tool-calls` | O agente em loop na mesma chamada | | `block-sudo` | Escalada de privilégios | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sem restrições | -| `block-terraform` / `block-kubectl` | Alterações não revisadas em infraestrutura em produção | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sem restrição | +| `block-terraform` / `block-kubectl` | Alterações não revisadas em infraestrutura ativa | | `block-rm-rf` | Exclusão recursiva de arquivos | | `block-force-push` / `block-push-master` | `git push --force`, pushes diretos para `main` | -As cinco primeiras se aplicam a qualquer agente que possa chamar uma ferramenta. As três últimas são as favoritas dos desenvolvedores — CLIs de codificação são a categoria de ambiente com cobertura mais profunda. +Cada uma dessas políticas intercepta a chamada *antes* de executar, então funcionam nos doze harnesses. As quatro primeiras se aplicam a qualquer agente que possa chamar uma ferramenta; as três últimas são as favoritas dos desenvolvedores — CLIs de codificação são a classe de harness que cobrimos com mais profundidade. A família `sanitize-*` é separada: ela roda após o retorno de uma ferramenta, então reporta um segredo na saída da ferramenta em vez de impedi-lo de entrar no contexto. -→ [Todas as 39 políticas nativas](https://docs.befailproof.ai/policies/builtin) +→ [Todas as 39 políticas embutidas](https://docs.befailproof.ai/policies/packs) --- ## Suas próprias políticas -Adicione um arquivo em `.failproofai/policies/` — ele é carregado automaticamente, sem necessidade de flags. -Faça commit e toda a equipe receberá na próxima vez que fizer pull. +Coloque um arquivo em `.failproofai/policies/` — ele é carregado automaticamente, sem flags necessárias. Faça commit e toda a equipe recebe na próxima vez que fizer pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -189,65 +190,53 @@ Três decisões disponíveis para cada política: | `deny(message)` | Bloqueia — a mensagem é enviada de volta ao agente | | `instruct(message)` | Deixa passar, mas adiciona contexto ao próximo prompt do agente | -→ [Guia de políticas personalizadas](https://docs.befailproof.ai/policies/custom) +→ [Escrever uma política](https://docs.befailproof.ai/policies/editor) --- ## Observabilidade -O enforcement é uma metade. A outra metade é ver o que o agente realmente fez. +Enforcement é uma metade. A outra metade é ver o que o agente realmente fez. -Execute `failproofai` sem argumentos e ele serve um dashboard em `localhost:8020` -lendo o histórico de execuções já armazenado na sua máquina — sem conta, sem cadastro, sem nada -saindo do seu ambiente. Você tem a lista de sessões, a sequência de chamadas ao modelo, chamadas de ferramentas -e decisões de hooks em cada execução, o que foi bloqueado e o que a política comunicou ao -agente, além de uma auditoria offline (`failproofai audit`) que varre seu histórico em busca de padrões -arriscados e sugere políticas para bloqueá-los. +Execute `failproofai` sem argumentos e ele serve um dashboard em `localhost:8020` lendo o histórico de execuções já presente na sua máquina — sem conta, sem cadastro, nada sai da máquina. Você obtém a lista de sessões, a sequência de chamadas ao modelo, chamadas de ferramentas e decisões de hooks dentro de cada execução, o que foi bloqueado e o que a política disse ao agente, além de uma auditoria offline (`failproofai audit`) que varre seu histórico em busca de padrões arriscados e sugere políticas para evitá-los. → [Dashboard local](https://docs.befailproof.ai/reference/local-dashboard) · -[Lendo um trace](https://docs.befailproof.ai/sessions/read-a-trace) · +[Ler um trace](https://docs.befailproof.ai/sessions/read-a-trace) · [Auditoria local](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** é o lado hospedado do mesmo modelo de dados, para equipes -que executam agentes em uma frota: cada execução de cada ambiente em um só lugar, um -grafo de execução com sub-agentes paralelos em suas próprias trilhas, latência p50/p95/p99 -para modelos, ferramentas e hooks, rastreamento de custo e janela de contexto por modelo, rastreamento -de erros, SQL sobre seus próprios traces com dashboards compartilháveis, avaliações pontuadas pelo -seu próprio serviço, auditorias agendadas que transformam falhas recorrentes em achados embasados em evidências, -e alertas roteados para Slack, e-mail ou um webhook assinado. Auto-hospedagem no seu -próprio cluster está disponível no plano Enterprise. +**Failproof AI Observability** é o lado hospedado do mesmo modelo de dados, para equipes que rodam agentes em uma frota: todas as execuções de todos os harnesses em um só lugar, um grafo de execução com sub-agentes paralelos em suas próprias trilhas, latência p50/p95/p99 para modelos, ferramentas e hooks, rastreamento de custo e janela de contexto por modelo, rastreamento de erros, SQL sobre seus próprios traces com dashboards compartilháveis, avaliações pontuadas pelo seu próprio serviço, auditorias programadas que transformam falhas recorrentes em descobertas embasadas em evidências, e alertas roteados para Slack, e-mail ou um webhook assinado. Auto-hospedagem no seu próprio cluster está disponível no plano Enterprise. → [Sessões](https://docs.befailproof.ai/sessions/overview) · [Auditorias](https://docs.befailproof.ai/audits/overview) · -[Agende uma demo](https://befailproof.ai/get-a-demo) +[Agendar uma demo](https://befailproof.ai/get-a-demo) --- ## Documentação -| Início | | +| Começar | | |---|---| -| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Instale, conecte um ambiente, veja a primeira execução | +| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Instale, conecte um harness, veja a primeira execução | | [Conceitos](https://docs.befailproof.ai/start/concepts) | Como o sistema de hooks funciona | -| [Ambientes suportados](https://docs.befailproof.ai/reference/harnesses) | Todos os 12 e o que cada um pode enforce | +| [Harnesses suportados](https://docs.befailproof.ai/reference/harnesses) | Todos os 12 e o que cada um pode aplicar | | Observar | | |---|---| | [Sessões](https://docs.befailproof.ai/sessions/overview) | Acompanhe uma execução: modelos, ferramentas, erros, latência | -| [Lendo um trace](https://docs.befailproof.ai/sessions/read-a-trace) | O que o grafo de execução está revelando | -| [Auditorias](https://docs.befailproof.ai/audits/overview) | Encontre padrões de falha em múltiplas sessões | -| [Dashboard local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sem necessidade de conta | +| [Ler um trace](https://docs.befailproof.ai/sessions/read-a-trace) | O que o grafo de execução está dizendo | +| [Auditorias](https://docs.befailproof.ai/audits/overview) | Encontre padrões de falha em muitas sessões | +| [Dashboard local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sem conta necessária | -| Enforce | | +| Aplicar | | |---|---| -| [Políticas nativas](https://docs.befailproof.ai/policies/builtin) | Todas as 39 políticas com parâmetros | -| [Políticas personalizadas](https://docs.befailproof.ai/policies/custom) | Escreva as suas próprias | -| [Configuração](https://docs.befailproof.ai/policies/local-configuration) | Escopos de configuração e regras de mesclagem | +| [Pacotes de políticas](https://docs.befailproof.ai/policies/packs) | As políticas do Failproof AI e pacotes do hub de políticas | +| [Escrever uma política](https://docs.befailproof.ai/policies/editor) | A partir de uma auditoria ou em código | +| [Configuração](https://docs.befailproof.ai/policies/local-configuration) | Escopos de configuração, regras de mesclagem e parâmetros de política | -| Instrumente seu próprio agente | | +| Instrumentar seu próprio agente | | |---|---| -| [SDK Python](https://docs.befailproof.ai/reference/custom-agents) | Reporte execuções de um agente sem ambiente | -| [SDK de políticas](https://docs.befailproof.ai/reference/policy-sdk) | Referência de `allow` / `deny` / `instruct` | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Reporte execuções de um agente sem harness | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Referência de `allow` / `deny` / `instruct` | --- @@ -259,13 +248,9 @@ MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso inter ## Contribuindo -Consulte [CONTRIBUTING.md](../../CONTRIBUTING.md). Novas políticas, casos extremos e traduções são bem-vindos. +Veja [CONTRIBUTING.md](../../CONTRIBUTING.md). Novas políticas, casos extremos e traduções são sempre bem-vindos. -> **Faça o build antes de começar.** Execute `bun install && bun run build` primeiro. Este repositório roda -> os próprios hooks do failproofai sobre si mesmo, e eles resolvem o import `failproofai` contra o -> bundle compilado em `dist/` — sem um build, você vai encontrar erros de hook com `Cannot find package 'failproofai'`. -> Refaça o build após alterar `src/`. Veja -> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Compile antes de começar.** Execute `bun install && bun run build` primeiro. Este repositório roda os próprios hooks do failproofai sobre si mesmo, e eles resolvem o import `failproofai` contra o bundle compilado em `dist/` — sem um build você receberá erros de hook `Cannot find package 'failproofai'`. Recompile após alterar `src/`. Veja [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.ru.md b/docs/i18n/README.ru.md index 2f4e32c6..e60d1e03 100644 --- a/docs/i18n/README.ru.md +++ b/docs/i18n/README.ru.md @@ -20,8 +20,8 @@ **Переводы:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Наблюдаемость и управление для каждой инфраструктуры, на которой работают ваши агенты.** -Где бы ни работали ваши агенты, мы это видим — и можем отказать. Failproof интегрируется с 12 инфраструктурами агентов — IDE программирования, такими как Claude Code и Codex, шлюзы чата, такие как Hermes, самостоятельно размещаемые ассистенты, такие как OpenClaw — захватывая каждый запуск и блокируя опасные вызовы инструментов до их выполнения. 39 встроенных политик. Нулевая задержка. Работает локально. +**Наблюдаемость и контроль для каждого окружения, в котором работают ваши агенты.** +Где бы ни работали ваши агенты, мы это видим — и можем сказать нет. Failproof подключается к 12 окружениям агентов — кодирующим CLI, как Claude Code и Codex, шлюзам чатов, как Hermes, самостоятельным помощникам, как OpenClaw — перехватывая каждый запуск и блокируя опасные вызовы инструментов перед их выполнением. 39 встроенных политик. Нулевая задержка. Работает локально. @@ -31,11 +31,11 @@ --- -## Поддерживаемые инфраструктуры +## Поддерживаемые окружения -Двенадцать инфраструктур в двух классах — десять IDE программирования и два шлюза чата и ассистентов (Hermes, OpenClaw). Те же события, те же политики, та же история сессий, независимо от того, в какой инфраструктуре работает ваш агент. +Двенадцать окружений в двух классах — десять кодирующих CLI и два шлюза чатов и помощников (Hermes, OpenClaw). Один API политик и история сеансов для всех них. То, что может *заблокировать* политика, зависит от окружения: остановка вызова инструмента перед его выполнением проверяется во всех двенадцати, завершение раунда — в восьми. [Матрица возможностей по окружениям](https://docs.befailproof.ai/reference/harnesses#enforcement-capability) показывает события, которые поддерживает каждое. -Агенты, которые не работают в одной из них, отправляют отчеты через [Python SDK](https://docs.befailproof.ai/reference/custom-agents), который дает вам трассировку, сессии и аудиты. Управление там требует hook в вашей собственной runtime — [свяжитесь с нами](mailto:support@befailproof.ai), и мы это настроим. +Агенты, работающие ни в одном из них, передают данные через [Python SDK](https://docs.befailproof.ai/reference/custom-agents), который предоставляет трассировку, сеансы и аудиты. Контроль там требует подключения в вашем собственном окружении — [свяжитесь с нами](mailto:support@befailproof.ai) и мы его настроим. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,37 +135,39 @@ ```sh npm install -g failproofai -failproofai policies --install # или просто запустите `failproofai` и примите первый запрос -failproofai +failproofai config # настройте ваши агенты и демон +failproofai policies add FailproofAI/policies # выберите, что нужно контролировать +failproofai # панель управления на localhost:8020 ``` -39 встроенных политик активируются немедленно. Панель управления находится на `localhost:8020`. Отключите первый запрос с помощью `FAILPROOFAI_NO_FIRST_RUN=1`. +Установка подключает подключения и не выбирает никакие политики по умолчанию — вторая команда — это то, что ставит защиту на машину, и любой набор можно использовать тем же способом (`failproofai policies add /`; `policies show /` сначала его читает). Запустите `failproofai config` без терминала — в CI, контейнере, агентом — и она применится вместо вопросов. На машине, которая никогда не была настроена, любая другая команда запускает ту же мастер-программу сначала; отключите это с помощью `FAILPROOFAI_NO_FIRST_RUN=1`. + +До тех пор, пока набор не загружен, единственное, что контролирует `block-failproofai-commands`, которая всегда включена и не может быть отключена или приостановлена: агент, который может приостановить контроль, может отключить всю остальную политику. --- -## Что это останавливает +## Что блокируется -| Политика | Что она блокирует | +| Политика | Что блокируется | |---|---| -| `sanitize-api-keys` | Утечка ключей API в контекст агента | -| `block-env-files` | Чтение файлов `.env` и других секретных файлов | -| `warn-repeated-tool-calls` | Агент зависает на том же вызове | +| `block-env-files` | Чтение `.env` и других файлов с секретами | +| `warn-repeated-tool-calls` | Агент, зацикливающийся на одном и том же вызове | | `block-sudo` | Повышение привилегий | | `warn-destructive-sql` | `DROP`, `TRUNCATE`, неограниченный `DELETE` | -| `block-terraform` / `block-kubectl` | Необходозненные изменения активной инфраструктуры | +| `block-terraform` / `block-kubectl` | Необремпроверенные изменения ливой инфраструктуры | | `block-rm-rf` | Рекурсивное удаление файлов | -| `block-force-push` / `block-push-master` | `git push --force`, прямые push'и в `main` | +| `block-force-push` / `block-push-master` | `git push --force`, прямые отправления в `main` | -Первые пять применяются к любому агенту, который может вызвать инструмент. Последние три — фавориты разработчиков — IDE программирования — это класс инфраструктуры, который мы покрываем наиболее полно. +Каждая из них контролирует вызов *перед* его выполнением, поэтому они работают во всех двенадцати окружениях. Первые четыре применяются к любому агенту, который может вызвать инструмент; последние три — фавориты разработчиков — кодирующие CLI это класс окружений, которые мы освещаем наиболее глубоко. Семейство `sanitize-*` отдельное: оно запускается после возврата инструмента, поэтому оно сообщает о секрете в выходе инструмента, а не удерживает его из контекста. -→ [Все 39 встроенных политик](https://docs.befailproof.ai/policies/builtin) +→ [Все 39 встроенных политик](https://docs.befailproof.ai/policies/packs) --- ## Ваши собственные политики -Поместите файл в `.failproofai/policies/` — он загружается автоматически, никаких флагов не требуется. -Зафиксируйте его, и вся команда получит его при следующем pull. +Поместите файл в `.failproofai/policies/` — он загружается автоматически, без флагов не требуется. +Закоммитьте его, и вся команда получит его при следующем pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -175,39 +177,39 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Записи в production пути заблокированы."); + return deny("Writes to production paths are blocked."); return allow(); }, }); ``` -Три решения, доступные для каждой политики: +Три решения доступны для каждой политики: | Решение | Эффект | |---|---| | `allow()` | Разрешить операцию | -| `deny(message)` | Заблокировать — сообщение передается обратно агенту | -| `instruct(message)` | Пропустить, но добавить контекст в следующий запрос агента | +| `deny(message)` | Заблокировать её — сообщение возвращается агенту | +| `instruct(message)` | Пропустить, но добавить контекст в следующую подсказку агента | -→ [Руководство по пользовательским политикам](https://docs.befailproof.ai/policies/custom) +→ [Напишите политику](https://docs.befailproof.ai/policies/editor) --- ## Наблюдаемость -Управление — это одна половина. Вторая половина — это видение того, что реально сделал агент. +Контроль — это одна половина. Другая половина — видеть, что агент на самом деле сделал. -Запустите `failproofai` без аргументов, и он предоставит панель управления на `localhost:8020`, читая историю запусков, уже находящуюся на вашей машине — без учетной записи, без регистрации, ничего не уходит за пределы. Вы получите список сессий, последовательность вызовов моделей, вызовы инструментов и решения hook в каждом запуске, что было заблокировано и что политика рассказала агенту, и автономный аудит (`failproofai audit`), который сканирует вашу историю на предмет рисков и предлагает политики для их остановки. +Запустите `failproofai` без аргументов, и он будет служить панелью управления на `localhost:8020`, читая историю запусков, уже находящуюся на вашей машине — никаких аккаунтов, регистрации, ничего не покидает коробку. Вы получаете список сеансов, последовательность вызовов модели, вызовов инструментов и решений крючков внутри каждого запуска, что было заблокировано и что политика сказала агенту, и локальный аудит (`failproofai audit`), который сканирует вашу историю на предмет рискованных шаблонов и предлагает политики для их остановки. → [Локальная панель управления](https://docs.befailproof.ai/reference/local-dashboard) · -[Чтение трассировки](https://docs.befailproof.ai/sessions/read-a-trace) · +[Прочитайте трассировку](https://docs.befailproof.ai/sessions/read-a-trace) · [Локальный аудит](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** — это размещенная сторона той же модели данных для команд, запускающих агентов на множестве машин: каждый запуск от каждой инфраструктуры в одном месте, граф выполнения с параллельными подагентами на их собственных дорожках, задержка p50/p95/p99 для моделей, инструментов и hook'ов, затраты для каждой модели и отслеживание контекстного окна, отслеживание ошибок, SQL на основе ваших собственных трассировок с общими панелями управления, оценки, оцениваемые вашим собственным сервисом, запланированные аудиты, которые преобразуют повторяющиеся сбои в основанные на доказательствах выводы, и оповещения, направляемые в Slack, по электронной почте или на подписанный webhook. Самостоятельное размещение в вашем собственном кластере доступно в плане Enterprise. +**Failproof AI Observability** — это хостируемая сторона той же модели данных, для команд, запускающих агентов по всему флоту: каждый запуск из каждого окружения в одном месте, граф выполнения с параллельными суб-агентами на своих дорожках, задержка p50/p95/p99 для моделей, инструментов и крючков, затраты по моделям и отслеживание контекстного окна, отслеживание ошибок, SQL над вашими собственными трассировками с общими панелями управления, оценки, выставленные вашей собственной службой, запланированные аудиты, которые превращают повторяющиеся сбои в подтвержденные результаты, и оповещения, направленные в Slack, по электронной почте или подписанному вебхуку. Самостоятельное размещение в вашем собственном кластере доступно в плане Enterprise. -→ [Сессии](https://docs.befailproof.ai/sessions/overview) · +→ [Сеансы](https://docs.befailproof.ai/sessions/overview) · [Аудиты](https://docs.befailproof.ai/audits/overview) · -[Запросить демонстрацию](https://befailproof.ai/get-a-demo) +[Заказать демонстрацию](https://befailproof.ai/get-a-demo) --- @@ -215,42 +217,42 @@ customPolicies.add({ | Начало | | |---|---| -| [Быстрый старт](https://docs.befailproof.ai/start/quickstart) | Установка, подключение инфраструктуры, первый запуск | -| [Концепции](https://docs.befailproof.ai/start/concepts) | Как работает система hook'ов | -| [Поддерживаемые инфраструктуры](https://docs.befailproof.ai/reference/harnesses) | Все 12 и что каждая может управлять | +| [Краткое руководство](https://docs.befailproof.ai/start/quickstart) | Установка, подключение окружения, просмотр первого запуска | +| [Концепции](https://docs.befailproof.ai/start/concepts) | Как работает система подключений | +| [Поддерживаемые окружения](https://docs.befailproof.ai/reference/harnesses) | Все 12 и то, что может контролировать каждое | | Наблюдение | | |---|---| -| [Сессии](https://docs.befailproof.ai/sessions/overview) | Отследите запуск: модели, инструменты, ошибки, задержка | -| [Чтение трассировки](https://docs.befailproof.ai/sessions/read-a-trace) | Что вам говорит граф выполнения | -| [Аудиты](https://docs.befailproof.ai/audits/overview) | Найдите паттерны отказов во многих сессиях | -| [Локальная панель управления](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, без необходимости в учетной записи | +| [Сеансы](https://docs.befailproof.ai/sessions/overview) | Следуйте за запуском: модели, инструменты, ошибки, задержка | +| [Прочитайте трассировку](https://docs.befailproof.ai/sessions/read-a-trace) | Что вам говорит граф выполнения | +| [Аудиты](https://docs.befailproof.ai/audits/overview) | Найдите шаблоны сбоев в разных сеансах | +| [Локальная панель управления](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, аккаунт не требуется | -| Управление | | +| Контроль | | |---|---| -| [Встроенные политики](https://docs.befailproof.ai/policies/builtin) | Все 39 политик с параметрами | -| [Пользовательские политики](https://docs.befailproof.ai/policies/custom) | Напишите свои собственные | -| [Конфигурация](https://docs.befailproof.ai/policies/local-configuration) | Области конфигурации и правила слияния | +| [Наборы политик](https://docs.befailproof.ai/policies/packs) | Политики failproofai и наборы из хаба политик | +| [Напишите политику](https://docs.befailproof.ai/policies/editor) | Из аудита или в коде | +| [Конфигурация](https://docs.befailproof.ai/policies/local-configuration) | Области конфигурации, правила слияния и параметры политики | -| Инструментируйте своего собственного агента | | +| Инструментируйте свой собственный агент | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Отправляйте отчеты из агента без инфраструктуры | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Справочник `allow` / `deny` / `instruct` | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Отчет о запусках от агента без окружения | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` справочник | --- ## Лицензия -MIT с [Commons Clause](https://commonsclause.com/) — свободно для внутреннего и личного использования; коммерческая перепродажа самого failproofai требует отдельного соглашения. Полный текст см. в [LICENSE](../../LICENSE). +MIT с [Commons Clause](https://commonsclause.com/) — бесплатно для внутреннего и личного использования; коммерческая перепродажа самого failproofai требует отдельного соглашения. Полный текст см. в [LICENSE](../../LICENSE). --- ## Вклад -Смотрите [CONTRIBUTING.md](../../CONTRIBUTING.md). Новые политики, граничные случаи и переводы приветствуются. +См. [CONTRIBUTING.md](../../CONTRIBUTING.md). Новые политики, граничные случаи и переводы приветствуются. -> **Соберите перед началом.** Сначала запустите `bun install && bun run build`. Этот репозиторий запускает собственные hook'и failproofai на себе, и они разрешают импорт `failproofai` против скомпилированного пакета `dist/` — без сборки вы столкнетесь с ошибками hook'ов `Cannot find package 'failproofai'`. Пересоберите после изменения `src/`. Смотрите [Сборка перед тем, как локальные dev hook'и будут работать](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Постройте перед началом.** Сначала запустите `bun install && bun run build`. Этот репозиторий запускает собственные подключения failproofai на себя, и они разрешают импорт `failproofai` против скомпилированного пакета `dist/` — без сборки вы получите ошибки подключений `Cannot find package 'failproofai'`. Пересоберите после изменения `src/`. См. [Постройте перед тем, как внутрирепозиторные подключения девелопмента будут работать](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Создано с ❤️ компанией [befailproof.ai](https://befailproof.ai) в SF и Bengaluru. +Создано с ❤️ от [befailproof.ai](https://befailproof.ai) в Сан-Франциско и Бенгалуру. diff --git a/docs/i18n/README.tr.md b/docs/i18n/README.tr.md index 67d2f0bd..5f86e6f7 100644 --- a/docs/i18n/README.tr.md +++ b/docs/i18n/README.tr.md @@ -20,27 +20,26 @@ **Çeviriler:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Agenlarınızın çalıştığı her sistem için gözlemlenebilirlik ve zorlama.** -Agenlarınız nereye çalışırsa çalışsın, biz bunu görüyoruz — ve hayır diyebiliriz. Failproof, 12 ajan sistemine kanca yerleştiriyor — Claude Code ve Codex gibi kodlama CLI'ları, Hermes gibi sohbet ağ geçitleri, OpenClaw gibi kendi kendini barındıran asistanlar — her çalıştırmayı yakalayıp tehlikeli araç çağrılarını yürütülmeden önce engelleme. 39 yerleşik politika. Sıfır gecikme. Yerel olarak çalışır. +**Aracılarınızın çalıştığı her ortam için gözlemlenebilirlik ve zorlama.** +Aracılarınız nerede çalışırsa çalışsın, biz onu görebiliriz — ve hayır diyebiliriz. Failproof, 12 aracı ortamına bağlanır — Claude Code ve Codex gibi kodlama CLI'ları, Hermes gibi sohbet ağ geçitleri, OpenClaw gibi kendi kendine barındırılan asistanlar — her çalıştırmayı yakalar ve yürütülmeden önce tehlikeli araç çağrılarını engeller. 39 yerleşik ilke. Sıfır gecikme. Yerel olarak çalışır.

- Failproof AI in action + Failproof AI uygulamada

--- -## Desteklenen sistemler +## Desteklenen ortamlar -İki sınıfta on iki sistem — on kodlama CLI'sı ve iki sohbet ve asistan ağ geçidi (Hermes, OpenClaw). Aynı olaylar, aynı politikalar, aynı oturum geçmişi, agenınız hangisinde çalışırsa çalışsın. +İki sınıfta on iki ortam — on kodlama CLI'ı ve iki sohbet ve asistan ağ geçidi (Hermes, OpenClaw). Tüm ortamlar arasında bir ilke API'ı ve bir oturum geçmişi. Bir ilkenin *engelleyebileceği* ortama özgüdür: bir araç çağrısını çalıştırmadan önce durdurmak tüm on ikide doğrulanır, oturum sonu kapıları sekizde açılır. [Ortama özgü matris](https://docs.befailproof.ai/reference/harnesses#enforcement-capability), her birinin hangi olayları onurlandırdığını listeler. -Bunlardan hiçbirinde çalışmayan ajanlar [Python SDK](https://docs.befailproof.ai/reference/custom-agents) üzerinden rapor verin, -bu size izleme, oturumlar ve denetimler sunar. Orada zorlama, kendi çalışma zamanınıza bir kanca gerektirir — [bizimle iletişime geçin](mailto:support@befailproof.ai) ve biz bunu haritalandıracağız. +Bunlardan hiçbirinde çalışmayan aracılar [Python SDK](https://docs.befailproof.ai/reference/custom-agents) aracılığıyla raporlanır; bu size izleme, oturumlar ve denetimler verir. Orada zorlama, kendi çalışma zamanınıza bir kanca takılmasını gerektirir — [bizimle iletişime geçin](mailto:support@befailproof.ai) ve biz onu eşleştireceğiz. -{/* A 6-column table instead of inline runs: table columns never re-wrap, - so the grid stays 2×6 at any window width (scrolling on very narrow screens - instead of collapsing into ragged orphan rows). */} +{/* Satır içi çalışmalarının yerine 6 sütunlu bir tablo: tablo sütunları hiçbir zaman yeniden kaydırılmaz, + bu nedenle ızgara herhangi bir pencere genişliğinde 2×6 kalır (çok dar ekranlarda kaydırma + bunun yerine düzensiz yetim satırlara çökmek). */}
@@ -132,41 +131,44 @@ bu size izleme, oturumlar ve denetimler sunar. Orada zorlama, kendi çalışma z
-## Yükle +## Yükleme ```sh npm install -g failproofai -failproofai policies --install # veya sadece `failproofai` çalıştırın ve ilk çalıştırma istemini kabul edin -failproofai +failproofai config # aracılarınızı ve daemon'u bağlayın +failproofai policies add FailproofAI/policies # neleri uygulayacağınızı seçin +failproofai # localhost:8020 üzerinde kontrol paneli ``` -39 yerleşik politika hemen etkinleşir. Pano `localhost:8020` adresinde bulunur. İlk çalıştırma istemini `FAILPROOFAI_NO_FIRST_RUN=1` ile devre dışı bırakın. +Kurulum, kancaları bağlar ve **hiçbir** ilke seçmez — ikinci komut, makinede güvenlik duvarları koyan şeydir ve herhangi bir paket aynı şekilde yazılır +(`failproofai policies add /`; `policies show /` önce birini okur). Terminal olmadan `failproofai config` çalıştırın — CI, bir konteyner, onu yöneten bir aracı — ve sorular sormak yerine uygular. Hiçbir zaman kurulmamış bir makinede, başka herhangi bir komut önce aynı sihirbazı çalıştırır; bunu `FAILPROOFAI_NO_FIRST_RUN=1` ile devre dışı bırakın. + +Bir paket gelene kadar, uygulamayı yapan tek şey `block-failproofai-commands`, her zaman açık olan ve kapatılamayan veya duraklatılamayan şeydir: zorlamayı duraklatabilecek bir aracı, diğer her ilkeyi açabilir. --- -## Engellediği şeyler +## Neyi engeller -| Politika | Engellediği şey | +| İlke | Neyi engeller | |---|---| -| `sanitize-api-keys` | API anahtarlarının ajanın bağlamına sızması | | `block-env-files` | `.env` ve diğer gizli dosyaların okunması | -| `warn-repeated-tool-calls` | Ajanın aynı çağrıda döngü halinde kalması | +| `warn-repeated-tool-calls` | Aracının aynı çağrıda döngüye girmesi | | `block-sudo` | Ayrıcalık yükseltme | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, sınırlandırılmamış `DELETE` | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, sınırlanmamış `DELETE` | | `block-terraform` / `block-kubectl` | Canlı altyapıya gözden geçirilmemiş değişiklikler | | `block-rm-rf` | Özyinelemeli dosya silme | -| `block-force-push` / `block-push-master` | `git push --force`, doğrudan `main` dalına gönderimler | +| `block-force-push` / `block-push-master` | `git push --force`, `main` üzerine doğrudan itme | -İlk beş, bir araç çağırabilen herhangi bir ajana uygulanır. Son üç, geliştirici favorileridir — kodlama CLI'ları, en derinlemesine kapsadığımız sistem sınıfıdır. +Bu komutların hepsi çağrısı çalıştırmadan önce kapıdan geçer, bu nedenle tüm on iki ortamda geçerlidirler. İlk dördü, bir aracı çağrı yapabilen herhangi bir araçla geçerlidir; sonuncu üçü geliştirici favorileridir — kodlama CLI'ları en derin kapladığımız ortam sınıfıdır. `sanitize-*` ailesi ayrıdır: bir araç döndükten sonra çalışır, bu nedenle bağlamdan onu tutmak yerine araç çıktısında bir gizli kodunu bildirir. -→ [Tüm 39 yerleşik politika](https://docs.befailproof.ai/policies/builtin) +→ [Tüm 39 yerleşik ilke](https://docs.befailproof.ai/policies/packs) --- -## Kendi politikalarınız +## Kendi ilkeleriniz -Bir dosyayı `.failproofai/policies/` içine bırakın — otomatik olarak yüklendiğinde, hiçbir bayrak gerekmez. -Bunu kaydedin ve tüm ekip sonraki çekme işleminde bunu alacak. +`.failproofai/policies/` içine bir dosya bırakın — otomatik olarak yüklenir, bayrak gerekmez. +Onu işleyin ve tüm takım bir sonraki çekişte onu alır. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -176,83 +178,82 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Writes to production paths are blocked."); + return deny("Üretim yollarına yazma engellenir."); return allow(); }, }); ``` -Her politika için üç karar mevcuttur: +Her ilke için kullanılabilir üç karar: | Karar | Etki | |---|---| | `allow()` | İşleme izin ver | -| `deny(message)` | Engelle — mesaj ajana geri gider | -| `instruct(message)` | İzin ver, ama ajanın sonraki istemine bağlam ekle | +| `deny(message)` | Engelle — ileti aracıya geri gider | +| `instruct(message)` | Geçmesine izin ver, ancak aracının sonraki komutuna bağlam ekle | -→ [Özel politikalar rehberi](https://docs.befailproof.ai/policies/custom) +→ [İlke yaz](https://docs.befailproof.ai/policies/editor) --- ## Gözlemlenebilirlik -Zorlama bir yarısı. Diğer yarısı ajanın aslında ne yaptığını görmektir. +Zorlama bir yarısıdır. Diğer yarısı, aracının gerçekten ne yaptığını görmektir. -Hiçbir argüman olmadan `failproofai` çalıştırın ve makinenizde zaten olan çalıştırma geçmişini okuyan `localhost:8020` adresinde bir pano sunacaktır — hesap yok, kaydolma yok, kutudan hiçbir şey çıkmıyor. Oturum listesini, her çalıştırma içinde model çağrılarının, araç çağrılarının ve kanca kararlarının sırasını, engellenenin ne olduğunu ve politikanın ajana ne söylediğini ve geçmişinizi riskli desenler açısından tarayan ve onları durduracak politikaları öneren çevrimdışı bir denetimi (`failproofai audit`) alırsınız. +`failproofai`yi argument olmadan çalıştırın ve `localhost:8020` üzerinde makinenizde zaten olan çalıştırma geçmişini okuyan bir kontrol paneli sunar — hesap yok, kaydolma yok, hiçbir şey kutunun dışına çıkmaz. Oturum listesini, her çalıştırmanın içinde model çağrılarının, araç çağrılarının ve kanca kararlarının sırasını, neyin engellendiğini ve ilkenin aracıya ne söylediğini alırsınız ve risky modelleri taradığınız ve onları durdurmak için ilkeler önerdiği çevrimdışı bir denetim (`failproofai audit`). -→ [Yerel pano](https://docs.befailproof.ai/reference/local-dashboard) · -[İzlemeyi oku](https://docs.befailproof.ai/sessions/read-a-trace) · +→ [Yerel kontrol paneli](https://docs.befailproof.ai/reference/local-dashboard) · +[İz oku](https://docs.befailproof.ai/sessions/read-a-trace) · [Yerel denetim](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Gözlemlenebilirliği**, aynı veri modelinin barındırılan tarafı, bir filo genelinde ajanlar çalıştıran takımlar için: her sistemden her çalıştırma tek bir yerde, kendi şeritlerinde paralel alt ajanlarla bir yürütme grafiği, modeller, araçlar ve kancalar için p50/p95/p99 gecikme, model başına maliyet ve bağlam penceresi izleme, hata izleme, kendi izlemeleriniz üzerinde SQL ve paylaşılabilir panolar, kendi hizmetiniz tarafından puanlanan değerlendirmeler, yinelenen hataları kanıt destekli bulgulara dönüştüren planlanan denetimler ve Slack, e-posta veya imzalı webhook'a yönlendirilen uyarılar. Kendi kümenizde kendi barındırma Enterprise planında kullanılabilir. +**Failproof AI Gözlemlenebilirliği**, aynı veri modelinin barındırılan tarafıdır, bir filo genelinde aracılar çalıştıran takımlar için: her ortamın her çalıştırması tek bir yerde, paralel alt-aracıların kendi şeritlerinde olduğu bir yürütme grafiği, modeller, araçlar ve kancalar için p50/p95/p99 gecikme, modele göre maliyet ve bağlam-penceresi izleme, hata izleme, kendi izleriiniz üzerinde SQL paylaşılabilir panolarla, kendi hizmetiniz tarafından puanlanan değerlendirmeler, yinelenen başarısızlıkları kanıta dayalı bulgulara dönüştüren planlanan denetimler ve uyarılar Slack, e-posta veya imzalı bir webhook'a yönlendirilir. Kendi kümenizde kendi kendine barındırma, Enterprise planında mevcuttur. → [Oturumlar](https://docs.befailproof.ai/sessions/overview) · [Denetimler](https://docs.befailproof.ai/audits/overview) · -[Demo ayırtın](https://befailproof.ai/get-a-demo) +[Demo kitapla](https://befailproof.ai/get-a-demo) --- ## Belgeler -| Başlangıç | | +| Başlat | | |---|---| -| [Hızlı başlangıç](https://docs.befailproof.ai/start/quickstart) | Yükleyin, bir sistem bağlayın, ilk çalıştırmayı görün | -| [Kavramlar](https://docs.befailproof.ai/start/concepts) | Kanca sistemi nasıl çalışır | -| [Desteklenen sistemler](https://docs.befailproof.ai/reference/harnesses) | Tümü 12 ve her biri ne uygulayabileceği | +| [Hızlı başlangıç](https://docs.befailproof.ai/start/quickstart) | Yükle, bir ortamı bağla, ilk çalıştırmayı gör | +| [Konseptler](https://docs.befailproof.ai/start/concepts) | Kanca sistemi nasıl çalışır | +| [Desteklenen ortamlar](https://docs.befailproof.ai/reference/harnesses) | Tüm 12 ve her birinin neleri uygulayabileceği | | Gözlemle | | |---|---| -| [Oturumlar](https://docs.befailproof.ai/sessions/overview) | Bir çalıştırmayı izleyin: modeller, araçlar, hatalar, gecikme | -| [İzlemeyi oku](https://docs.befailproof.ai/sessions/read-a-trace) | Yürütme grafiğinin size söyledikleri | -| [Denetimler](https://docs.befailproof.ai/audits/overview) | Çok sayıda oturum genelinde hata desenlerini bulun | -| [Yerel pano](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, hesap gerekmez | +| [Oturumlar](https://docs.befailproof.ai/sessions/overview) | Bir çalıştırmayı takip et: modeller, araçlar, hatalar, gecikme | +| [İz oku](https://docs.befailproof.ai/sessions/read-a-trace) | Yürütme grafiği sana ne söylüyor | +| [Denetimler](https://docs.befailproof.ai/audits/overview) | Birçok oturum arasında başarısızlık modellerini bul | +| [Yerel kontrol paneli](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, hesap gerekli değil | -| Zorlama | | +| Uygula | | |---|---| -| [Yerleşik politikalar](https://docs.befailproof.ai/policies/builtin) | Tüm 39 politika parametrelerle | -| [Özel politikalar](https://docs.befailproof.ai/policies/custom) | Kendinizinkini yazın | -| [Yapılandırma](https://docs.befailproof.ai/policies/local-configuration) | Yapılandırma kapsamları ve birleştirme kuralları | +| [İlke paketleri](https://docs.befailproof.ai/policies/packs) | Failproof AI ilkeleri ve ilke merkezi'nden paketler | +| [İlke yaz](https://docs.befailproof.ai/policies/editor) | Bir denetimden veya kodda | +| [Yapılandırma](https://docs.befailproof.ai/policies/local-configuration) | Konfigürasyon kapsamları, birleştirme kuralları ve ilke parametreleri | -| Kendi ajanınızı enstrüman edin | | +| Kendi aracınızı enstrüman edin | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Sistem olmayan ajanından çalıştırmaları rapor edin | -| [Politika SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` referansı | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Ortamı olmayan bir aracıdan çalıştırmaları raporla | +| [İlke SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` referansı | --- ## Lisans -MIT with [Commons Clause](https://commonsclause.com/) — dahili ve kişisel kullanım için ücretsiz; failproofai'nin ticari olarak yeniden satışı ayrı bir anlaşma gerektirir. Tam metin için [LICENSE](../../LICENSE) bölümüne bakın. +MIT [Commons Clause](https://commonsclause.com/) — dahili ve kişisel kullanım için ücretsiz; failproofai'in ticari yeniden satışı ayrı bir anlaşma gerektirir. Tam metin için [LİSANS](../../LICENSE) bölümüne bakın. --- ## Katkıda bulunma -[CONTRIBUTING.md](../../CONTRIBUTING.md) bölümüne bakın. Yeni politikalar, kenar durumlar ve çeviriler hepsi hoş geldiniz. +[CONTRIBUTING.md](../../CONTRIBUTING.md) bölümüne bakın. Yeni ilkeler, edge case'ler ve çeviriler hepsi hoş geldiniz. -> **Başlamadan önce derleyin.** İlk olarak `bun install && bun run build` komutunu çalıştırın. Bu depo, failproofai'nin kendi kancalarını kendinde çalıştırır ve `failproofai` içe aktarımını derlenmiş `dist/` paketine karşı çözerler — bir yapı olmadan `Cannot find package 'failproofai'` kanca hataları alırsınız. `src/` değiştikten sonra yeniden derleyin. Bkz. -> [İn-repo dev hooks'un çalışması için önce derleyin](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Başlamadan önce oluşturun.** Önce `bun install && bun run build` çalıştırın. Bu depo, failproofai'in kendi kancalarını kendisinde çalıştırır ve `failproofai` içe aktarmasını derlenmiş `dist/` paketine karşı çözerler — bir derleme olmadan `Cannot find package 'failproofai'` kanca hatalarına çarparsınız. `src/` değiştirildikten sonra yeniden derleyin. Bkz. [İçi repo dev kancaları çalışmaya başlayacak şekilde önce oluşturun](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -SF ve Bengaluru'da [befailproof.ai](https://befailproof.ai) tarafından ❤️ ile yapıldı. +SF ve Bengaluru'da [befailproof.ai](https://befailproof.ai) tarafından ❤️ ile inşa edildi. diff --git a/docs/i18n/README.vi.md b/docs/i18n/README.vi.md index 19d0492b..c7933dc4 100644 --- a/docs/i18n/README.vi.md +++ b/docs/i18n/README.vi.md @@ -20,8 +20,7 @@ **Bản dịch:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Quan sát và thực thi cho mọi harness mà agents chạy.** -Dù agents chạy ở đâu, chúng tôi nhìn thấy nó — và chúng tôi có thể từ chối. Failproof kết nối 12 agent harness — các CLI để viết code như Claude Code và Codex, các gateway chat như Hermes, các asistant tự lưu trữ như OpenClaw — ghi lại mọi lần chạy và chặn các lệnh gọi công cụ nguy hiểm trước khi chúng thực thi. 39 chính sách được xây dựng sẵn. Độ trễ bằng không. Chạy cục bộ. +**Quan sát và thực thi cho mọi hệ thống agents của bạn.** Dù agents chạy ở đâu, chúng tôi đều nhìn thấy — và có thể từ chối. Failproof kết nối 12 hệ thống agent — các CLI viết code như Claude Code và Codex, các gateway chat như Hermes, các trợ lý tự lưu trữ như OpenClaw — ghi lại mọi lần chạy và chặn các lệnh gọi công cụ nguy hiểm trước khi chúng được thực thi. 39 chính sách tích hợp sẵn. Độ trễ bằng không. Chạy cục bộ. @@ -31,11 +30,11 @@ Dù agents chạy ở đâu, chúng tôi nhìn thấy nó — và chúng tôi c --- -## Các harness được hỗ trợ +## Hệ thống được hỗ trợ -Mười hai harness trong hai lớp — mười CLI để viết code, và hai gateway chat và asistant (Hermes, OpenClaw). Cùng các sự kiện, cùng các chính sách, cùng lịch sử phiên, bất kể harness nào mà agent chạy. +Mười hai hệ thống trong hai loại — mười CLI viết code và hai gateway chat và trợ lý (Hermes, OpenClaw). Một API chính sách và lịch sử phiên chung trên tất cả chúng. Những gì một chính sách có thể *chặn* là tùy từng hệ thống: dừng lệnh gọi công cụ trước khi chạy được xác minh trên tất cả mười hai, cổng cuối lượt trên tám. [Ma trận tùy từng hệ thống](https://docs.befailproof.ai/reference/harnesses#enforcement-capability) liệt kê các sự kiện mà mỗi hệ thống hỗ trợ. -Các agent chạy ở bên ngoài chúng được báo cáo thông qua [SDK Python](https://docs.befailproof.ai/reference/custom-agents), cung cấp cho bạn tracing, phiên và audits. Thực thi ở đó cần một hook trong runtime của riêng bạn — [liên lạc với chúng tôi](mailto:support@befailproof.ai) và chúng tôi sẽ ánh xạ nó. +Các agents chạy trong không có hệ thống nào báo cáo thông qua [Python SDK](https://docs.befailproof.ai/reference/custom-agents), cung cấp tracing, phiên và kiểm tra. Thực thi ở đó cần một hook trong runtime của bạn — [liên hệ với chúng tôi](mailto:support@befailproof.ai) và chúng tôi sẽ ánh xạ nó. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,11 +134,14 @@ Các agent chạy ở bên ngoài chúng được báo cáo thông qua [SDK Pyth ```sh npm install -g failproofai -failproofai policies --install # hoặc chỉ cần chạy `failproofai` và chấp nhận lời nhắc lần đầu -failproofai +failproofai config # kết nối agents và daemon của bạn +failproofai policies add FailproofAI/policies # chọn những gì cần thực thi +failproofai # bảng điều khiển trên localhost:8020 ``` -39 chính sách được xây dựng sẵn kích hoạt ngay lập tức. Bảng điều khiển tại `localhost:8020`. Tắt lời nhắc lần đầu bằng `FAILPROOFAI_NO_FIRST_RUN=1`. +Thiết lập kết nối các hooks và chọn **không** chính sách — lệnh thứ hai là những gì đặt hàng rào bảo vệ trên máy, và bất kỳ gói nào cũng có cùng kiểu (`failproofai policies add /`; `policies show /` đọc một lần đầu). Chạy `failproofai config` mà không có terminal — CI, một container, một agent điều khiển nó — và nó áp dụng thay vì hỏi. Trên máy chưa bao giờ được thiết lập, bất kỳ lệnh nào khác sẽ chạy cùng một trình hướng dẫn trước; vô hiệu hóa điều đó bằng `FAILPROOFAI_NO_FIRST_RUN=1`. + +Cho đến khi gói tới, điều duy nhất thực thi là `block-failproofai-commands`, luôn bật và không thể tắt hoặc tạm dừng: một agent có thể tạm dừng thực thi có thể tắt tất cả các chính sách khác. --- @@ -147,25 +149,23 @@ failproofai | Chính sách | Những gì nó chặn | |---|---| -| `sanitize-api-keys` | Các khóa API rò rỉ vào ngữ cảnh của agent | -| `block-env-files` | Đọc các tệp `.env` và các tệp bí mật khác | +| `block-env-files` | Các đọc file `.env` và file bí mật khác | | `warn-repeated-tool-calls` | Agent lặp lại cùng một lệnh gọi | -| `block-sudo` | Nâng cao quyền hạn | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` không bị giới hạn | -| `block-terraform` / `block-kubectl` | Thay đổi chưa được xem xét cho cơ sở hạ tầng trực tiếp | -| `block-rm-rf` | Xóa tệp đệ quy | +| `block-sudo` | Nâng cao đặc quyền | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` không giới hạn | +| `block-terraform` / `block-kubectl` | Thay đổi cơ sở hạ tầng trực tiếp chưa được xem xét | +| `block-rm-rf` | Xóa file đệ quy | | `block-force-push` / `block-push-master` | `git push --force`, đẩy trực tiếp đến `main` | -Năm cái đầu tiên áp dụng cho bất kỳ agent nào có thể gọi một công cụ. Ba cái cuối cùng là những yêu thích của nhà phát triển — các CLI để viết code là lớp harness mà chúng tôi bao phủ sâu nhất. +Mỗi một cổng gọi *trước* khi nó chạy, vì vậy chúng giữ trên tất cả mười hai hệ thống. Bốn cái đầu tiên áp dụng cho bất kỳ agent nào có thể gọi một công cụ; ba cái cuối cùng là những điều yêu thích của nhà phát triển — CLI viết code là loại hệ thống chúng tôi bao phủ sâu nhất. Họ `sanitize-*` là riêng biệt: nó chạy sau khi một công cụ trả về, vì vậy nó báo cáo một bí mật trong kết quả công cụ thay vì giữ nó ra khỏi ngữ cảnh. -→ [Tất cả 39 chính sách được xây dựng sẵn](https://docs.befailproof.ai/policies/builtin) +→ [Tất cả 39 chính sách tích hợp sẵn](https://docs.befailproof.ai/policies/packs) --- -## Các chính sách của riêng bạn +## Chính sách của riêng bạn -Thả một tệp vào `.failproofai/policies/` — nó tải tự động, không cần cờ nào. -Commit nó và toàn bộ nhóm sẽ nhận được nó khi pull tiếp theo. +Thả một file vào `.failproofai/policies/` — nó tải tự động, không cần cờ. Commit và toàn bộ nhóm sẽ nhận được nó lần tiếp theo. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -183,29 +183,29 @@ customPolicies.add({ Ba quyết định có sẵn cho mọi chính sách: -| Quyết định | Tác dụng | +| Quyết định | Hiệu ứng | |---|---| -| `allow()` | Cho phép thao tác | -| `deny(message)` | Chặn nó — tin nhắn quay lại agent | -| `instruct(message)` | Cho phép nó, nhưng thêm ngữ cảnh vào lời nhắc tiếp theo của agent | +| `allow()` | Cho phép hoạt động | +| `deny(message)` | Chặn nó — thông báo quay lại agent | +| `instruct(message)` | Cho nó qua, nhưng thêm ngữ cảnh vào lời nhắc tiếp theo của agent | -→ [Hướng dẫn chính sách tùy chỉnh](https://docs.befailproof.ai/policies/custom) +→ [Viết một chính sách](https://docs.befailproof.ai/policies/editor) --- ## Quan sát -Thực thi là một nửa. Nửa kia là thấy agent thực sự đã làm gì. +Thực thi là một nửa. Nửa kia là xem agent thực sự làm gì. -Chạy `failproofai` mà không có đối số và nó cung cấp một bảng điều khiển tại `localhost:8020` đọc lịch sử chạy đã có trên máy của bạn — không có tài khoản, không có đăng ký, không có gì rời khỏi hộp. Bạn nhận được danh sách phiên, trình tự các lệnh gọi mô hình, lệnh gọi công cụ và quyết định hook bên trong mỗi lần chạy, những gì bị chặn và những gì chính sách nói với agent, và một kiểm tra ngoại tuyến (`failproofai audit`) quét lịch sử của bạn tìm các mẫu rủi ro và đề xuất các chính sách để dừng chúng. +Chạy `failproofai` mà không có đối số và nó phục vụ bảng điều khiển trên `localhost:8020` đọc lịch sử chạy đã có trên máy của bạn — không tài khoản, không đăng ký, không có gì rời khỏi hộp. Bạn nhận được danh sách phiên, chuỗi các lệnh gọi mô hình, lệnh gọi công cụ và quyết định hook bên trong mỗi lần chạy, những gì bị chặn và những gì chính sách nói với agent, và kiểm tra ngoại tuyến (`failproofai audit`) quét lịch sử của bạn để tìm các mẫu rủi ro và gợi ý chính sách để dừng chúng. → [Bảng điều khiển cục bộ](https://docs.befailproof.ai/reference/local-dashboard) · [Đọc một trace](https://docs.befailproof.ai/sessions/read-a-trace) · [Kiểm tra cục bộ](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** là mặt được lưu trữ của cùng một mô hình dữ liệu, cho các nhóm chạy agents trên một fleet: mọi lần chạy từ mọi harness ở một nơi, biểu đồ thực thi với các sub-agent song song trên các làn riêng, độ trễ p50/p95/p99 cho mô hình, công cụ và hook, chi phí trên mỗi mô hình và theo dõi cửa sổ ngữ cảnh, theo dõi lỗi, SQL trên các trace của riêng bạn với bảng điều khiển có thể chia sẻ, đánh giá được chấm điểm bởi dịch vụ của riêng bạn, các kiểm tra được lên lịch biến các lỗi tái diễn thành những phát hiện dựa trên bằng chứng, và cảnh báo được định tuyến đến Slack, email hoặc một webhook được ký. Tự lưu trữ trong cluster của riêng bạn có sẵn trên gói Enterprise. +**Failproof AI Observability** là phía được lưu trữ của cùng một mô hình dữ liệu, cho các nhóm chạy agents trên một bộ: mỗi lần chạy từ mọi hệ thống ở một nơi, biểu đồ thực thi với các sub-agents song song trên các đường riêng của họ, độ trễ p50/p95/p99 cho mô hình, công cụ và hooks, chi phí theo mô hình và theo dõi cửa sổ ngữ cảnh, theo dõi lỗi, SQL trên traces của riêng bạn với bảng điều khiển có thể chia sẻ, các đánh giá được tính điểm bởi dịch vụ của bạn, kiểm tra theo lịch trình biến các lỗi định kỳ thành phát hiện hỗ trợ bằng bằng chứng, và cảnh báo được định tuyến đến Slack, email hoặc webhook đã ký. Tự lưu trữ trong cụm của riêng bạn có sẵn trong kế hoạch Enterprise. -→ [Các phiên](https://docs.befailproof.ai/sessions/overview) · +→ [Phiên](https://docs.befailproof.ai/sessions/overview) · [Kiểm tra](https://docs.befailproof.ai/audits/overview) · [Đặt lịch demo](https://befailproof.ai/get-a-demo) @@ -215,42 +215,42 @@ Chạy `failproofai` mà không có đối số và nó cung cấp một bảng | Bắt đầu | | |---|---| -| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Cài đặt, kết nối một harness, xem lần chạy đầu tiên | -| [Khái niệm](https://docs.befailproof.ai/start/concepts) | Cách hệ thống hook hoạt động | -| [Các harness được hỗ trợ](https://docs.befailproof.ai/reference/harnesses) | Tất cả 12 và những gì mỗi cái có thể thực thi | +| [Hướng dẫn bắt đầu nhanh](https://docs.befailproof.ai/start/quickstart) | Cài đặt, kết nối một hệ thống, xem lần chạy đầu tiên | +| [Các khái niệm](https://docs.befailproof.ai/start/concepts) | Cách hệ thống hook hoạt động | +| [Hệ thống được hỗ trợ](https://docs.befailproof.ai/reference/harnesses) | Tất cả 12, và những gì mỗi cái có thể thực thi | | Quan sát | | |---|---| -| [Các phiên](https://docs.befailproof.ai/sessions/overview) | Theo dõi một lần chạy: mô hình, công cụ, lỗi, độ trễ | -| [Đọc một trace](https://docs.befailproof.ai/sessions/read-a-trace) | Biểu đồ thực thi đang nói gì với bạn | -| [Kiểm tra](https://docs.befailproof.ai/audits/overview) | Tìm các mẫu lỗi trên nhiều phiên | +| [Phiên](https://docs.befailproof.ai/sessions/overview) | Theo dõi một lần chạy: mô hình, công cụ, lỗi, độ trễ | +| [Đọc một trace](https://docs.befailproof.ai/sessions/read-a-trace) | Biểu đồ thực thi đang nói với bạn điều gì | +| [Kiểm tra](https://docs.befailproof.ai/audits/overview) | Tìm mẫu lỗi trên nhiều phiên | | [Bảng điều khiển cục bộ](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, không cần tài khoản | | Thực thi | | |---|---| -| [Chính sách được xây dựng sẵn](https://docs.befailproof.ai/policies/builtin) | Tất cả 39 chính sách với các tham số | -| [Chính sách tùy chỉnh](https://docs.befailproof.ai/policies/custom) | Viết chính sách của riêng bạn | -| [Cấu hình](https://docs.befailproof.ai/policies/local-configuration) | Phạm vi cấu hình và quy tắc hợp nhất | +| [Gói chính sách](https://docs.befailproof.ai/policies/packs) | Các chính sách Failproof AI và gói từ hub chính sách | +| [Viết một chính sách](https://docs.befailproof.ai/policies/editor) | Từ một kiểm tra hoặc trong code | +| [Cấu hình](https://docs.befailproof.ai/policies/local-configuration) | Phạm vi cấu hình, quy tắc hợp nhất và tham số chính sách | -| Cấp độ agent của riêng bạn | | +| Công cụ agent của riêng bạn | | |---|---| -| [SDK Python](https://docs.befailproof.ai/reference/custom-agents) | Báo cáo các lần chạy từ một agent không có harness | -| [SDK chính sách](https://docs.befailproof.ai/reference/policy-sdk) | Tham chiếu `allow` / `deny` / `instruct` | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Báo cáo chạy từ một agent không có hệ thống | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Tham chiếu `allow` / `deny` / `instruct` | --- ## Giấy phép -MIT với [Commons Clause](https://commonsclause.com/) — miễn phí cho sử dụng nội bộ và cá nhân; bán lại thương mại của failproofai yêu cầu một thỏa thuận riêng. Xem [LICENSE](../../LICENSE) để có toàn bộ văn bản. +MIT với [Commons Clause](https://commonsclause.com/) — miễn phí cho sử dụng nội bộ và cá nhân; bán lại thương mại của failproofai yêu cầu một thỏa thuận riêng. Xem [LICENSE](../../LICENSE) để biết toàn bộ văn bản. --- ## Đóng góp -Xem [CONTRIBUTING.md](../../CONTRIBUTING.md). Các chính sách mới, các trường hợp cạnh, và các bản dịch đều được hoan nghênh. +Xem [CONTRIBUTING.md](../../CONTRIBUTING.md). Các chính sách mới, trường hợp đặc biệt và bản dịch đều được chào đón. -> **Xây dựng trước khi bạn bắt đầu.** Chạy `bun install && bun run build` trước tiên. Repo này chạy các hook của failproofai trên chính nó, và chúng giải quyết import `failproofai` với bộ bundle `dist/` được biên dịch — mà không cần xây dựng bạn sẽ gặp lỗi `Cannot find package 'failproofai'` hook. Xây dựng lại sau khi thay đổi `src/`. Xem [Xây dựng trước khi các in-repo dev hook sẽ hoạt động](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Xây dựng trước khi bạn bắt đầu.** Chạy `bun install && bun run build` trước. Repo này chạy các hooks của failproofai trên chính nó, và chúng giải quyết import `failproofai` so với gói `dist/` được biên dịch — mà không có bản dựng bạn sẽ gặp các lỗi hook `Cannot find package 'failproofai'`. Xây dựng lại sau khi thay đổi `src/`. Xem [Xây dựng trước khi các dev hooks trong repo sẽ hoạt động](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Xây dựng với ❤️ bởi [befailproof.ai](https://befailproof.ai) ở SF và Bengaluru. +Xây dựng với ❤️ bởi [befailproof.ai](https://befailproof.ai) tại SF và Bengaluru. diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md index 202ad4fb..e02269cc 100644 --- a/docs/i18n/README.zh.md +++ b/docs/i18n/README.zh.md @@ -20,8 +20,9 @@ **翻译版本：** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**为 Agent 运行的每一个执行环境提供可观测性与管控能力。** -无论你的 Agent 在哪里运行，我们都能看到——并且可以说"不"。Failproof 接入了 12 种 Agent 执行框架（harness）——包括 Claude Code、Codex 等编码 CLI，Hermes 等对话网关，以及 OpenClaw 等自托管助手——捕获每次运行，并在危险工具调用执行前将其拦截。39 条内置策略，零延迟，本地运行。 +**为你的 Agent 所运行的每一个框架提供可观测性与策略执行。** +无论你的 Agent 在哪里运行，我们都能感知——并且可以说不。Failproof 接入了 12 个 Agent +框架——包括 Claude Code 和 Codex 等编码 CLI，Hermes 等聊天网关，以及 OpenClaw 等自托管助手——捕获每一次运行，并在危险工具调用执行之前将其拦截。内置 39 条策略，零延迟，本地运行。 @@ -31,11 +32,11 @@ --- -## 支持的执行框架 +## 支持的框架 -共 12 种执行框架，分为两类——10 种编码 CLI，以及 2 种对话与助手网关（Hermes、OpenClaw）。无论你的 Agent 运行在哪一种框架中，事件、策略、会话历史均保持一致。 +共支持两类十二个框架——十个编码 CLI，以及两个聊天与助手网关（Hermes、OpenClaw）。所有框架共享同一套策略 API 和会话历史记录。策略的*拦截*能力因框架而异：在工具调用执行前拦截已在全部十二个框架上验证，轮次结束门控在八个框架上可用。[各框架能力矩阵](https://docs.befailproof.ai/reference/harnesses#enforcement-capability)列出了每个框架所支持的事件。 -若 Agent 不在上述任何框架中运行，可通过 [Python SDK](https://docs.befailproof.ai/reference/custom-agents) 上报数据，获得链路追踪、会话管理和审计能力。在该场景下的管控功能需要在你自己的运行时中挂载 hook——[联系我们](mailto:support@befailproof.ai)，我们会协助你完成适配。 +不在上述框架中运行的 Agent 可通过 [Python SDK](https://docs.befailproof.ai/reference/custom-agents) 上报数据，获得追踪、会话和审计能力。在该场景下实施执行策略需要在你自己的运行时中添加 hook——[联系我们](mailto:support@befailproof.ai)，我们会协助你完成接入。 {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,36 +136,38 @@ ```sh npm install -g failproofai -failproofai policies --install # 或直接运行 `failproofai` 并在首次运行提示时确认 -failproofai +failproofai config # 配置你的 Agent 和守护进程 +failproofai policies add FailproofAI/policies # 选择要执行的策略 +failproofai # 在 localhost:8020 启动仪表盘 ``` -39 条内置策略立即生效。控制台地址：`localhost:8020`。可通过设置 `FAILPROOFAI_NO_FIRST_RUN=1` 禁用首次运行提示。 +配置向导会自动连接 hook，但**不会**默认启用任何策略——第二条命令才是真正为机器添加防护栏的操作。所有策略包的添加方式相同（`failproofai policies add /`；`policies show /` 可预览某个包的内容）。在无终端环境（CI、容器、由 Agent 驱动的环境）下运行 `failproofai config` 时，它会直接应用配置而不会弹出交互问答。对于从未配置过的机器，运行其他任何命令都会先触发配置向导；可通过设置 `FAILPROOFAI_NO_FIRST_RUN=1` 来禁用此行为。 + +在策略包加载之前，唯一生效的策略是 `block-failproofai-commands`，该策略始终开启且无法关闭或暂停：若 Agent 能够暂停策略执行，则它就能关闭其他所有策略。 --- -## 能拦截哪些风险 +## 能拦截什么 | 策略 | 拦截内容 | |---|---| -| `sanitize-api-keys` | API 密钥泄露到 Agent 上下文中 | -| `block-env-files` | 读取 `.env` 及其他机密文件 | -| `warn-repeated-tool-calls` | Agent 对同一调用陷入循环 | -| `block-sudo` | 权限提升操作 | +| `block-env-files` | 读取 `.env` 及其他密钥文件 | +| `warn-repeated-tool-calls` | Agent 对同一调用的循环重试 | +| `block-sudo` | 权限提升 | | `warn-destructive-sql` | `DROP`、`TRUNCATE`、无条件 `DELETE` | | `block-terraform` / `block-kubectl` | 未经审查的生产基础设施变更 | | `block-rm-rf` | 递归删除文件 | -| `block-force-push` / `block-push-master` | `git push --force`、直接推送至 `main` 分支 | +| `block-force-push` / `block-push-master` | `git push --force`，直接推送到 `main` | -前五条适用于任何能调用工具的 Agent，后三条是开发者最常用的——编码 CLI 是我们覆盖最深入的执行框架类别。 +以上所有策略均在调用*执行前*进行拦截，因此对全部十二个框架均有效。前四条适用于任何能调用工具的 Agent；后三条是开发者最常用的——编码 CLI 是我们覆盖最深入的框架类别。`sanitize-*` 系列策略有所不同：它在工具返回结果后运行，用于报告工具输出中的密钥，而非阻止其进入上下文。 -→ [全部 39 条内置策略](https://docs.befailproof.ai/policies/builtin) +→ [全部 39 条内置策略](https://docs.befailproof.ai/policies/packs) --- ## 自定义策略 -将文件放入 `.failproofai/policies/` 目录即可自动加载，无需任何额外参数。提交到代码仓库后，团队所有成员在下次拉取时即可生效。 +将文件放入 `.failproofai/policies/` 目录——无需任何参数，自动加载。提交到代码仓库后，团队所有成员在下次拉取时即可生效。 ```js import { customPolicies, deny, allow } from "failproofai"; @@ -180,29 +183,29 @@ customPolicies.add({ }); ``` -每条策略可使用三种决策： +每条策略可做出三种决策： | 决策 | 效果 | |---|---| | `allow()` | 允许该操作 | -| `deny(message)` | 阻止该操作——消息会返回给 Agent | -| `instruct(message)` | 放行，但在 Agent 的下一个提示词中附加上下文信息 | +| `deny(message)` | 拦截操作——消息会返回给 Agent | +| `instruct(message)` | 放行操作，但向 Agent 的下一条提示中追加上下文 | -→ [自定义策略指南](https://docs.befailproof.ai/policies/custom) +→ [编写策略](https://docs.befailproof.ai/policies/editor) --- ## 可观测性 -管控是一半，另一半是洞察 Agent 的实际行为。 +策略执行只是其中一半。另一半是了解 Agent 实际做了什么。 -不带任何参数运行 `failproofai`，它会在 `localhost:8020` 提供一个控制台，读取本机已有的运行历史——无需账号、无需注册、数据不离开本机。你可以查看会话列表、每次运行中模型调用和工具调用的完整序列及 hook 决策、被拦截的内容以及策略向 Agent 传达的信息，还可以进行离线审计（`failproofai audit`），扫描历史记录中的风险模式并给出策略建议。 +不带参数运行 `failproofai`，它会在 `localhost:8020` 启动一个仪表盘，读取已存储在本机的运行历史——无需账号，无需注册，数据不会离开本机。你可以查看会话列表、每次运行中的模型调用序列、工具调用和 hook 决策、哪些操作被拦截以及策略向 Agent 反馈了什么内容，还有离线审计功能（`failproofai audit`），可扫描你的历史记录以发现风险模式并建议相应的防护策略。 -→ [本地控制台](https://docs.befailproof.ai/reference/local-dashboard) · -[解读链路追踪](https://docs.befailproof.ai/sessions/read-a-trace) · +→ [本地仪表盘](https://docs.befailproof.ai/reference/local-dashboard) · +[读取追踪记录](https://docs.befailproof.ai/sessions/read-a-trace) · [本地审计](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** 是同一数据模型的托管版本，面向在集群中大规模运行 Agent 的团队：所有执行框架的每次运行都汇聚在同一个地方，执行图支持并行子 Agent 独立泳道展示，提供模型、工具和 hook 的 p50/p95/p99 延迟数据，按模型统计的费用和上下文窗口追踪、错误追踪，支持通过 SQL 查询你自己的链路数据并生成可分享的仪表盘，可使用自有服务对评估结果打分，定期审计将反复出现的故障转化为有据可查的发现，以及通过 Slack、邮件或签名 Webhook 发送告警。企业版支持在你自己的集群中自托管部署。 +**Failproof AI Observability** 是同一数据模型的托管版本，适用于在集群中跨多台机器运行 Agent 的团队：所有框架的所有运行记录汇聚一处；支持并行子 Agent 各自独立泳道的执行图；模型、工具和 hook 的 p50/p95/p99 延迟统计；按模型统计的成本与上下文窗口追踪；错误追踪；可对你自己的追踪数据执行 SQL 查询并生成可分享的仪表盘；支持由你自己的服务评分的评估功能；可将反复出现的失败转化为有据可查的发现的定期审计；以及路由到 Slack、邮件或签名 Webhook 的告警。企业版计划支持在你自己的集群中自托管。 → [会话](https://docs.befailproof.ai/sessions/overview) · [审计](https://docs.befailproof.ai/audits/overview) · @@ -214,42 +217,42 @@ customPolicies.add({ | 入门 | | |---|---| -| [快速开始](https://docs.befailproof.ai/start/quickstart) | 安装、接入执行框架、查看首次运行结果 | -| [核心概念](https://docs.befailproof.ai/start/concepts) | Hook 系统的工作原理 | -| [支持的执行框架](https://docs.befailproof.ai/reference/harnesses) | 全部 12 种及各自的管控能力 | +| [快速开始](https://docs.befailproof.ai/start/quickstart) | 安装、连接框架、查看首次运行 | +| [核心概念](https://docs.befailproof.ai/start/concepts) | hook 系统的工作原理 | +| [支持的框架](https://docs.befailproof.ai/reference/harnesses) | 全部 12 个框架及各自的执行能力 | -| 可观测性 | | +| 观测 | | |---|---| -| [会话](https://docs.befailproof.ai/sessions/overview) | 追踪一次运行：模型、工具、错误、延迟 | -| [解读链路追踪](https://docs.befailproof.ai/sessions/read-a-trace) | 执行图所传达的信息 | -| [审计](https://docs.befailproof.ai/audits/overview) | 跨多个会话发现故障模式 | -| [本地控制台](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`，无需账号 | +| [会话](https://docs.befailproof.ai/sessions/overview) | 追踪运行过程：模型、工具、错误、延迟 | +| [读取追踪记录](https://docs.befailproof.ai/sessions/read-a-trace) | 执行图所传达的信息 | +| [审计](https://docs.befailproof.ai/audits/overview) | 在大量会话中发现失败模式 | +| [本地仪表盘](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`，无需账号 | -| 管控 | | +| 执行 | | |---|---| -| [内置策略](https://docs.befailproof.ai/policies/builtin) | 全部 39 条策略及其参数说明 | -| [自定义策略](https://docs.befailproof.ai/policies/custom) | 编写你自己的策略 | -| [配置说明](https://docs.befailproof.ai/policies/local-configuration) | 配置作用域与合并规则 | +| [策略包](https://docs.befailproof.ai/policies/packs) | Failproof AI 内置策略及策略中心的第三方包 | +| [编写策略](https://docs.befailproof.ai/policies/editor) | 从审计结果出发，或直接在代码中编写 | +| [配置](https://docs.befailproof.ai/policies/local-configuration) | 配置作用域、合并规则与策略参数 | -| 接入你自己的 Agent | | +| 接入自定义 Agent | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | 从无执行框架的 Agent 上报运行数据 | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | 从无框架的 Agent 上报运行数据 | | [策略 SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` 参考文档 | --- ## 许可证 -MIT 附加 [Commons Clause](https://commonsclause.com/)——个人和内部使用免费；将 failproofai 本身作为商业产品转售需签订单独协议。完整条款请参阅 [LICENSE](../../LICENSE)。 +MIT 附加 [Commons Clause](https://commonsclause.com/)——个人及内部使用免费；将 failproofai 本身作为商业产品转售需签订单独协议。完整条款请参见 [LICENSE](../../LICENSE)。 --- -## 参与贡献 +## 贡献 -请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。欢迎贡献新策略、边界用例和翻译内容。 +请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。欢迎贡献新策略、边界情况修复以及翻译。 -> **开始前请先构建项目。** 首先运行 `bun install && bun run build`。本仓库会对自身运行 failproofai 的 hook，这些 hook 会从编译后的 `dist/` 包中解析 `failproofai` 的导入——如果未执行构建，你会遇到 `Cannot find package 'failproofai'` hook 错误。修改 `src/` 后请重新构建。详见 [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)。 +> **开始前请先构建项目。** 首先运行 `bun install && bun run build`。本仓库会对自身运行 failproofai 的 hook，而这些 hook 需要从编译后的 `dist/` 包中解析 `failproofai` 导入——如果未构建，你会遇到 `Cannot find package 'failproofai'` 的 hook 错误。修改 `src/` 后请重新构建。详见 [构建后才能使用仓库内开发 hook](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)。 --- -由 [befailproof.ai](https://befailproof.ai) 团队在旧金山与班加罗尔用 ❤️ 打造。 +由 [befailproof.ai](https://befailproof.ai) 团队在旧金山和班加罗尔用 ❤️ 打造。 diff --git a/docs/it/admin/keys-and-permissions.mdx b/docs/it/admin/keys-and-permissions.mdx index 8c65d5e2..9a13ad6c 100644 --- a/docs/it/admin/keys-and-permissions.mdx +++ b/docs/it/admin/keys-and-permissions.mdx @@ -1,29 +1,29 @@ --- -title: "Chiavi e autorizzazioni" -description: "Crea chiavi API con ambito limitato per macchine, automazione e operatori." +title: "Chiavi e permessi" +description: "Crea chiavi API con ambito per macchine, automazione e operatori." icon: "key-round" --- -Le chiavi API appartengono a un'organizzazione e hanno autorizzazioni esplicite. Usa chiavi separate per l'ingestion degli agenti, la distribuzione delle politiche, i valutatori, l'automazione CI e gli script amministrativi. +Le chiavi API appartengono a un'organizzazione e portano con sé permessi espliciti. Usa chiavi separate per l'ingestion degli agenti, la distribuzione delle policy, i valutatori, l'automazione CI e gli script amministrativi. -## Creare e ruotare una chiave +## Crea e ruota una chiave - 1. Vai a **Amministrazione → Chiavi**, seleziona **nuova chiave** e inserisci un nome del carico di lavoro. - 2. Scegli un set di autorizzazioni e regola le autorizzazioni individuali solo quando il preset non è sufficiente. + 1. Vai a **Administration → Keys**, seleziona **new key** e inserisci il nome del carico di lavoro. + 2. Scegli un set di permessi e regola i permessi individuali solo quando il preset non è sufficiente. 3. Crea la chiave e copia il suo segreto monouso immediatamente. - 4. Apri la chiave in seguito per aggiornare le autorizzazioni, disabilitarla o rigenerare il segreto. + 4. Apri la chiave in seguito per aggiornare i grant, disabilitarla o rigenerare il segreto. - Il drawer di creazione è dove scegli le autorizzazioni più ristrette richieste dal carico di lavoro. + Il drawer di creazione è dove scegli i grant più ristretti richiesti dal carico di lavoro. - ![Il drawer della nuova chiave API con i preset di autorizzazioni e le autorizzazioni individuali.](/images/dashboard/key-create.png) + ![Il drawer della nuova chiave API con preset di permessi e grant individuali.](/images/dashboard/key-create.png) - Dopo la creazione, la pagina Chiavi mostra i metadati persistenti e le azioni di gestione. Il segreto monouso non viene più mostrato. + Dopo la creazione, la pagina Keys mostra i metadati persistenti e le azioni di gestione. Il segreto monouso non viene più mostrato. - ![La pagina Chiavi API che mostra le autorizzazioni della chiave, l'ora di creazione e le azioni di rigenerazione e disabilitazione.](/images/dashboard/api-keys.png) + ![La pagina API Keys che mostra i permessi della chiave, l'ora di creazione e le azioni di rigenerazione e disabilitazione.](/images/dashboard/api-keys.png) - Usa questo elenco per rivedere regolarmente le autorizzazioni e disabilitare le chiavi che non corrispondono più a un carico di lavoro attivo. + Usa questo elenco per rivedere regolarmente i grant e disabilitare le chiavi che non corrispondono più a un carico di lavoro attivo. ```bash @@ -40,35 +40,35 @@ Le chiavi API appartengono a un'organizzazione e hanno autorizzazioni esplicite. -Le due autorizzazioni richieste da una macchina Failproof AI connessa sono indipendenti: +I due permessi richiesti da una macchina Failproof AI collegata sono indipendenti: - `events:add` invia eventi e dati di sessione. -- `policies:pull` recupera le distribuzioni di politiche assegnate. +- `policies:pull` recupera le distribuzioni di policy assegnate. I segreti delle chiavi vengono mostrati quando creati o rigenerati. Archiviali in un gestore di segreti e ruotali senza riutilizzare le credenziali interattive di un operatore. -## Catalogo delle autorizzazioni +## Catalogo dei permessi -| Area | Autorizzazioni | +| Area | Permessi | | --- | --- | -| Eventi | `events:add`, `events:read` | -| Chiavi | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` è solo per sessioni umane | -| Utenti | `users:create`, `users:read`, `users:update`, `users:delete` | -| Valutazioni | `evaluations:read`, `evaluations:trigger` | -| Dashboard | `dashboards:read`, `dashboards:write`, `dashboards:delete` | -| Query | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | -| Assistente | `agent:use` | -| Impostazioni | `settings:read`, `settings:write` | -| Avvisi | `alerts:read`, `alerts:write` | -| Problemi | `issues:read`, `issues:create`, `issues:close` | -| Audit | `audits:read`, `audits:write` | -| Politiche | `policies:read`, `policies:write`, `policies:pull` | -| Utilizzo | `usage:read` | - -`orgs:admin` è riservato all'operatore dell'istanza e non può essere concesso a una chiave dell'organizzazione o a un membro ordinario. I token obsoleti `incidents:*` e `alerts:ack` sono accettati per compatibilità e si normalizzano alle autorizzazioni `issues:*` attuali. - -I set di autorizzazioni incorporati sono `read-only`, `standard` e `admin`. `standard` aggiunge attivazione di valutazioni, esecuzione di query, risposta ai problemi e uso dell'assistente alle autorizzazioni di lettura. La creazione di chiavi rimuove le autorizzazioni solo per umani anche quando un set di autorizzazioni le contiene. +| Events | `events:add`, `events:read` | +| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` è solo per sessione interattiva | +| Users | `users:create`, `users:read`, `users:update`, `users:delete` | +| Evaluations | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | +| Dashboards | `dashboards:read`, `dashboards:write`, `dashboards:delete` | +| Queries | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | +| Assistant | `agent:use` | +| Settings | `settings:read`, `settings:write` | +| Alerts | `alerts:read`, `alerts:write` | +| Issues | `issues:read`, `issues:create`, `issues:close` | +| Audits | `audits:read`, `audits:write` | +| Policies | `policies:read`, `policies:write`, `policies:pull` | +| Usage | `usage:read` | + +`orgs:admin` è riservato all'operatore dell'istanza e non può essere concesso a una chiave dell'organizzazione o a un membro ordinario. I token ritirati `incidents:*` e `alerts:ack` sono accettati per compatibilità e si normalizzano ai permessi `issues:*` attuali. + +I set di permessi integrati sono `read-only`, `standard` e `admin`. `standard` aggiunge il triggering della valutazione, l'esecuzione delle query, la risposta ai problemi e l'uso dell'assistente ai permessi di lettura. La creazione della chiave rimuove i grant solo per l'interazione umana anche quando un set di permessi li contiene. - Le chiavi con ambito dell'istanza possono selezionare un'organizzazione con l'intestazione `X-AgentEye-Org`. Impostala esplicitamente nelle distribuzioni multi-organizzazione; l'omissione potrebbe selezionare l'organizzazione predefinita. + Le chiavi con ambito dell'istanza possono selezionare un'organizzazione con l'intestazione `X-AgentEye-Org`. Impostala esplicitamente su distribuzioni multi-organizzazione; l'omissione potrebbe selezionare l'organizzazione predefinita. \ No newline at end of file diff --git a/docs/it/evaluations/deploy.mdx b/docs/it/evaluations/deploy.mdx new file mode 100644 index 00000000..d74f0848 --- /dev/null +++ b/docs/it/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "Distribuire e versionare una valutazione" +description: "Distribuisci una versione immutabile, vedi cosa è in produzione, pubblica nuove versioni, ripristina versioni precedenti e valuta le sessioni già presenti." +icon: "cloud-upload" +--- + +## Distribuiscila + +Seleziona **deploy `@`** in fondo alla pagina di authoring. La versione diventa immutabile una volta pubblicata: da quel momento in poi, ogni sessione che si conclude e alla quale si applica la condizione sarà valutata da essa. + +## Vedi cosa è in produzione + +**Analyze → eval authoring** elenca le definizioni ospitate della tua organizzazione, le valutazioni che l'evaluator gestito esegue per essa. Ogni riga mostra: + +- il nome, la chiave, la versione e il tipo di risultato +- il checksum della fonte, che distingue le revisioni distribuite senza aprire il codice +- se è **condizionale** o se eseguita su **tutte le sessioni completate** — la condizione è quello che limita una valutazione a particolari agent o ambienti +- il timeout, le etichette e quando è stato modificato per ultimo + +![L'elenco delle definizioni ospitate: nome, chiave, versione, tipo di risultato, checksum, timeout e ambito di ciascuna valutazione, con opzione per nuova versione e abilitazione o disabilitazione.](/images/dashboard/eval-definitions.png) + +Cerca nell'elenco o filtralo per stato. Le valutazioni registrate dal tuo worker non sono elencate qui; i loro risultati portano un'etichetta **customer** nella [pagina delle valutazioni](/it/sessions/evaluations), e quelle ospitate portano **managed**. + +Un'organizzazione può avere fino a 100 valutazioni ospitate diverse abilitate contemporaneamente. + +## Pubblica una nuova versione + +Seleziona **new version** su una riga. La pagina di authoring si apre con il codice di quella versione; modificalo, testalo e distribuiscilo. La sua chiave e il tipo di risultato rimangono e non possono cambiare. + +Pubblicare un successore disabilita il predecessore e lo mantiene nell'elenco. I risultati mantengono la versione che li ha prodotti, così un grafico mostra esattamente quando la nuova logica ha preso il controllo. + +## Ripristina una versione precedente + +Seleziona **disable** sulla versione attuale e **enable** su quella che desideri ripristinare. Niente è eliminato e ogni risultato rimane come era. + +## Interrompi una valutazione + +Seleziona **disable**. Senza una versione abilitata, interrompe l'esecuzione nelle nuove sessioni. Per interrompere una valutazione eseguita dal tuo worker, smetti di registrarla: rimuovila dal worker o arresta il worker. + +## Valuta le sessioni già presenti + +La valutazione procede in avanti: una versione distribuita ora non valuterà mai una sessione che è terminata prima. Per valutare la cronologia, apri **score sessions you already have** nella pagina di authoring della valutazione, scegli un intervallo di tempo fino a 90 giorni e, opzionalmente, una singola valutazione, e conta prima di eseguire. Il conteggio è esattamente quello che verrà eseguito e ogni coppia sessione-valutazione in esso è una valutazione fatturabile. + +Riempie solo i vuoti. Una sessione che ha già un risultato per quella valutazione lo mantiene e l'esecuzione della stessa finestra due volte non valuta nulla di nuovo. + +Per valutare nuovamente una sessione — dopo una correzione, o per una sessione che non si è mai conclusa correttamente — seleziona **re-evaluate** sulla sua pagina. Il nuovo risultato viene aggiunto alla cronologia della sessione; i precedenti rimangono. + +## Autorizzazioni + +| Autorizzazione | Ti permette di | +| --- | --- | +| `evaluations:read` | Vedere i risultati e aprire la pagina di authoring della valutazione | +| `evaluations:trigger` | Vedere, distribuire, versionare, abilitare e disabilitare definizioni ospitate; testarle; valutare la cronologia; rivalutare una sessione | +| `events:read` | Testare contro sessioni reali e basare bozze sulle tue chiavi payload, oltre a `evaluations:trigger` | +| `evaluations:run` | Eseguire il tuo worker valutatore personalizzato | \ No newline at end of file diff --git a/docs/it/evaluations/overview.mdx b/docs/it/evaluations/overview.mdx new file mode 100644 index 00000000..0f51b72e --- /dev/null +++ b/docs/it/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "Valuta gli agenti" +description: "Assegna un punteggio a ogni sessione conclusa dell'agente con valutazioni che definisci: controlli Python ospitati o giudici LLM nel tuo worker." +icon: "gauge" +--- + +Una valutazione assegna un punteggio a una sessione dell'agente conclusa. Quando una sessione termina, ogni valutazione abilitata che le si applica viene eseguita e registra i risultati trovati, con un ragionamento che puoi leggere accanto alla traccia: + +- un **punteggio** da 0 a 1, opzionalmente contrassegnato come superato o non superato +- una **metrica**, come un conteggio, una durata o un costo, con la relativa unità +- un'**asserzione**, che è stata superata o non superata + +## Due tipi di valutatore + +| | Python ospitato | Il tuo worker | +| --- | --- | --- | +| Scritto | Nel dashboard, sotto **Analyze → eval authoring** | In Python, con l'[Evaluator SDK](/it/reference/evaluator-sdk) | +| Esecuzione | Sul valutatore gestito di Failproof AI, in una sandbox | Sulla tua infrastruttura | +| Ideale per | Controlli deterministici basati su codice | Giudici LLM, chiamate ai modelli, pacchetti, segreti, accesso di rete, elaborazione pesante | + +Python ospitato è deliberatamente limitato: un'espressione, nessuna importazione, nessuna rete. Qualsiasi cosa che richieda un modello — un giudice LLM che valuta se una risposta era rilevante, ad esempio — viene eseguita nel tuo worker. Nessuno dei due tipi ha bisogno di una connessione in entrata: i worker richiedono le sessioni terminate e inviano i risultati tramite HTTPS in uscita. + +## Ogni organizzazione valuta i propri agenti + +Le valutazioni appartengono all'organizzazione che le definisce. Ogni organizzazione su un'istanza scrive le proprie — i propri controlli, condizioni, soglie ed etichette — le varia e le distribuisce senza influenzare altre, e vede solo i propri risultati. Filtra questi risultati per agente, ambiente, valutazione e ora, oppure chiedi informazioni all'assistente. + +## Dalla prima bozza ai punteggi live + + + + Descrivi cosa misurare e lascia che l'assistente la rediga, oppure scrivila tu stesso. Vedi [Scrivi una valutazione](/it/evaluations/write). + + + Eseguila su sessioni reali prima che sia live; nulla viene memorizzato. Vedi [Testa una valutazione](/it/evaluations/test). + + + Distribuisci una versione immutabile, pubblica nuove versioni mentre evolve, e torna a una versione precedente. Vedi [Distribuisci e versiona](/it/evaluations/deploy). + + + Traccia i punteggi nel tempo, confronta agenti e ambienti, e chiedi all'assistente. Vedi [Leggi i risultati della valutazione](/it/sessions/evaluations). + + + +La valutazione procede in avanti: una versione distribuita ora assegna un punteggio alle sessioni che terminano da ora in poi. Per assegnare un punteggio alle sessioni che hai già, [completale retroattivamente](/it/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file diff --git a/docs/it/evaluations/test.mdx b/docs/it/evaluations/test.mdx new file mode 100644 index 00000000..f8c6bb8c --- /dev/null +++ b/docs/it/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "Testare una valutazione" +description: "Esegui una valutazione rispetto alle tue sessioni reali prima di distribuirla. Nulla viene archiviato." +icon: "flask-conical" +--- + +**testare questa valutazione**, nella pagina di creazione, esegue il codice rispetto alle sessioni reali tue sulla flotta di valutazione senza distribuirlo. Nulla viene archiviato: un errore qui è un'anteprima, e la distribuzione è sempre consentita. + + + + Seleziona **check** per compilare il codice e la condizione rispetto alle regole della sandbox senza eseguirli su alcuna sessione. + + + Restringi le sessioni corrispondenti per agente, ambiente, ora o ID della sessione, e selezionane fino a 10. Includi sia sessioni in cui la valutazione dovrebbe fallire che sessioni in cui dovrebbe avere successo. + + + Seleziona **run against N sessions**, e leggi ogni riga. + + + +| Riga | Cosa significa | +| --- | --- | +| **ok** | Si è eseguita. La riga elenca ogni punteggio, metrica e asserzione che ha restituito, e quanto tempo ha impiegato. | +| **skipped** | La condizione ha restituito `False`, quindi la valutazione non si è eseguita. È un salto, non un errore. | +| Failed | Ha sollevato un'eccezione, è scaduta o ha utilizzato qualcosa che la sandbox rifiuta. La riga indica quale, e **Fix it** passa l'errore all'assistente quando può essere utile. | + +![Il pannello test this evaluation: tre sessioni selezionate per agente, due ok e una saltata perché la sua condizione ha restituito False.](/images/dashboard/eval-test.png) + +Un risultato smette di essere attuale nel momento in cui modifichi il codice; viene attenuato invece di essere riutilizzato. \ No newline at end of file diff --git a/docs/it/evaluations/write.mdx b/docs/it/evaluations/write.mdx new file mode 100644 index 00000000..75d81a95 --- /dev/null +++ b/docs/it/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "Scrivi una valutazione" +description: "Descrivi cosa misurare e lascia che l'assistente rediga una valutazione Python ospitata, oppure scrivi il codice tu stesso. I giudici LLM vengono eseguiti nel tuo worker." +icon: "file-pen-line" +--- + +Le valutazioni ospitate sono piccoli Python deterministici, scritti nel dashboard ed eseguiti sulla flotta di valutatori di Failproof AI. La logica più complessa — un giudice LLM, un pacchetto, un segreto, una chiamata di rete — viene eseguita nel [tuo worker](#write-it-in-your-own-worker). + +## Redila da una descrizione + +1. Vai a **Analyze → eval authoring** e seleziona **new eval**. +2. Descrivi cosa misurare in inglese semplice, oppure scegli da **start from an example…**, e seleziona **draft**. +3. Rivedi i campi e il codice che compila, quindi [testalo](/it/evaluations/test) e [distribuiscilo](/it/evaluations/deploy). + +![La pagina di authoring eval con una valutazione redatta: la descrizione, le note dell'assistente sulla bozza, e i campi name, key, version, result, timeout, labels e condition.](/images/dashboard/eval-authoring-draft.png) + +La bozza è radicata negli eventi della tua organizzazione: la pagina legge quali chiavi di payload le tue sessioni hanno trasportato negli ultimi sette giorni, quindi il codice legge chiavi che esistono piuttosto che indovinare. Prima di consegnare la bozza, l'assistente la testa su fino a cinque delle tue sessioni recenti, ripara tutto ciò che può provare sia rotto — per un massimo di tre cicli — e controlla una volta che il codice misuri quello che hai chiesto. Mantieni la descrizione specifica: i prompt ampi sono più lenti e possono andare in timeout. Rivedi il codice comunque; la distribuzione non è mai bloccata. + +## Imposta i campi + +| Campo | Cos'è | +| --- | --- | +| name | Quello che vedono le persone. Modificabile in seguito | +| key | L'identificatore stabile sotto il quale i suoi risultati vengono graficati, ad esempio `code_assistant_quality_gate` | +| version | Qualsiasi stringa di versione senza spazi, ad esempio `1.0.0` | +| result | **score** (da 0 a 1), **metric** (un numero con un'unità), o **assertion** (riuscito o meno) | +| timeout seconds | Predefinito 30. La sandbox interrompe qualsiasi singola esecuzione a 60 | +| labels | Fino a 20, separate da virgole. Modificabili in seguito | +| condition | Opzionale. Un'espressione Python; la valutazione viene eseguita solo sulle sessioni in cui è `True` | + +Usa la condition per limitare una valutazione agli agenti e agli ambienti per cui è destinata: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +La key, la version, il tipo di result, la condition e il codice sono immutabili una volta distribuiti: per modificarne uno qualsiasi, pubblica una nuova versione. Il name, i labels e se è abilitato rimangono modificabili. + +## Scrivi il codice tu stesso + +Il **codice evaluator** è un'unica espressione Python che restituisce `EvalResult(...)`, con `session` in ambito. Questo calcola la quota di risultati di strumenti tornati ok: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +Un risultato inizia con la propria key della valutazione, nel suo tipo dichiarato: `score=` per una valutazione score, oppure una voce `metrics` o `assertions` denominata dalla key per una valutazione metric o assertion. Altre metriche e assertion la accompagnano, fino a 25 risultati in un'esecuzione. + +| In ambito | Ti dà | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count`, e `events`, più `count(event_type)` e `events_of_type(event_type)` | +| Ogni event | `id`, `ts`, `event_type`, e `payload` | +| Tipi di risultato | `EvalResult`, `Score`, `Metric`, `Assertion`, e `ConditionResult` per una condition | +| Builtins | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +Nient'altro è raggiungibile: nessun import, e nessun attributo oltre i dati della sessione e i metodi plain string e dictionary come `get`, `lower`, e `split`, che devono essere chiamati piuttosto che referenziati. Le chiavi di payload sono qualunque cosa i tuoi agenti inviino — `status` sopra è solo un esempio — quindi leggile da una sessione reale. **format** ordina il codice e **fix** chiede all'assistente di ripararlo. Il codice può essere fino a 128 KiB, e la condition fino a 16 KiB. + +![L'editor del codice evaluator, con format e fix, che mostra le assertion di una valutazione redatta.](/images/dashboard/eval-authoring-code.png) + +## Scrivi nel tuo worker + +Quando una valutazione ha bisogno di un modello, un pacchetto, un segreto, o la rete, scrivila con l'[Evaluator SDK](/it/reference/evaluator-sdk) ed eseguila sulla tua infrastruttura. Usa gli stessi tipi di risultato, e i suoi risultati appaiono accanto a quelli ospitati, etichettati **customer**: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/it/policies/deploy.mdx b/docs/it/policies/deploy.mdx index db0b441a..48017d30 100644 --- a/docs/it/policies/deploy.mdx +++ b/docs/it/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "Distribuire policy" -description: "Implementa una versione di policy revisionata sulle macchine designate." +title: "Distribuire una policy" +description: "Metti in produzione una versione di policy testata su macchine in modalità osservazione, attivala e conferma che ogni macchina l'ha ricevuta." icon: "cloud-upload" --- -Una distribuzione connette una o più versioni di policy a un insieme di macchine registrate. +Una distribuzione mette versioni di policy pubblicate su una macchina, ciascuna con uno dei due effetti: -## Applicare una distribuzione +- **Observe** registra quello che la policy avrebbe fatto e non blocca nulla. +- **Enforce** agisce sulla decisione: un `deny` blocca la chiamata e un `instruct` orienta l'agente. + +## Aggiungi una macchina + +Una macchina appare in **Admin → enforcement** una volta connessa a Cloud. Se quella che ti serve non è ancora lì: - 1. Vai su **Admin → enforcement**, trova la macchina e espandi la sua riga. - 2. Seleziona **edit**, aggiungi la versione di policy revisionata e scegli **observe** o il suo effetto di enforcement. - 3. Applica la modifica, quindi attendi il prossimo check-in della macchina e conferma lo stato della sua distribuzione e copertura. - 4. Vai su **Observe → policy** per ispezionare le decisioni in diretta. - - ![L'editor di distribuzione della macchina con versioni di policy, effetti enforce e observe, e l'azione di applicazione della distribuzione.](/images/dashboard/enforcement-editor.png) + 1. Vai a **Administration → Keys** e crea una chiave con `policies:pull`, in modo che la macchina possa ricevere distribuzioni, e `events:add`, in modo che le sue decisioni raggiungano Cloud. + 2. Connetti la macchina con quella chiave — [Connect a machine to Cloud](/it/start/setup#connect-a-machine-to-cloud) ti spiega come. + 3. Conferma che appare in **Admin → enforcement**. - Distribuisci dalla CLI con `fp fleet`. Rivedi il set risultante prima di applicarlo — `deploy` stampa il piano completo e chiede conferma **solo su un terminale interattivo senza `--json`**. Con `--json`, con `--yes`, o con stdin reindirizzato (un step di CI, uno script, un agente che esegue comandi shell) applica immediatamente senza piano e senza richiesta — quindi esegui prima `fp fleet show ` se vuoi revisionare: + Sulla macchina: + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + In un terminale, `failproofai config` chiede se connettersi a Cloud e richiede la chiave in un prompt mascherato. Poi conferma che la macchina è registrata, da qualsiasi posto, con `fp fleet list`. + + + +## Distribuisci in modalità osservazione + + + + 1. Vai a **Admin → enforcement**, trova la macchina e espandi la sua riga. + 2. Seleziona **edit**, aggiungi la versione di policy testata e scegli **observe**. + 3. Applica la modifica, poi attendi il prossimo check-in della macchina e conferma lo stato della distribuzione e della copertura. + 4. Vai a **Observe → policy** per ispezionare le decisioni in tempo reale. + ![L'editor di distribuzione della macchina con versioni di policy, effetti enforce e observe, e l'azione di distribuzione apply.](/images/dashboard/enforcement-editor.png) + + ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` mostra intent vs delivery (una macchina si legge come `behind` finché non esegue il prossimo poll), `fp fleet history ` elenca le generazioni, e `fp fleet rollback ` ripristina una — rifiuta se quella generazione nomina una policy nel frattempo disabilitata o cancellata. + Il suffisso `:observe` è quello che attiva l'osservazione: un semplice `--add no-force-push` mantiene l'effetto che la macchina ha già per quella policy, altrimenti applica enforce. Cambialo in enforce più tardi con `--add no-force-push:enforce`. + + `deploy` **sostituisce l'intero set di policy della macchina** con il risultato. Stampa il piano, poi chiede prima di applicare — ma solo su un terminale interattivo. Con `--yes`, sotto `fp --json`, o con stdin reindirizzato (un step di CI, uno script, un agente che lancia comandi) applica senza chiedere; il piano è ancora stampato, oppure restituito come `plan` sotto `--json`. - Controlla la macchina stessa con `failproofai config --status`, e usa `fp sessions --env production --since 24h` e `fp events --event-type hook_completed` dopo la distribuzione per verificare che l'attività raggiunga Cloud. + Sulla macchina, `failproofai policies` elenca le policy gestite da Cloud che sta eseguendo e `failproofai config --status` mostra la sua connessione. Usa `fp sessions --env production --since 24h` e `fp events --event-type hook_completed` per confermare che la sua attività raggiunge Cloud. - - Distribuisci una versione revisionata, non una bozza mutabile, iniziando con una macchina non-production o una piccola coorte le cui sessioni puoi ispezionare. + + Seleziona la versione pubblicata e le macchine su cui dovrebbe essere eseguita. - - Rivedi corrispondenze, motivi, strumenti interessati e falsi positivi senza bloccare il lavoro. + + Rivedi i match, le ragioni, gli strumenti interessati e i falsi positivi mentre nulla viene bloccato. - - Promuovi dopo che le corrispondenze osservate separano le azioni non sicure da quelle valide, quindi conferma che ogni macchina designata ha acquisito la distribuzione e sta segnalando le decisioni. + + Cambia l'effetto in enforce una volta che i match osservati distinguono le azioni non sicure da quelle valide, poi conferma che ogni macchina prevista ha ricevuto la modifica e sta segnalando le decisioni. -Le macchine necessitano della capacità `policies:pull`. La segnalazione degli eventi è controllata separatamente da `events:add`; verifica entrambi quando prevedi analisi e enforcement da Cloud. +## Controlla la copertura + +La copertura risponde se una policy è in esecuzione dove c'è il rischio. + +1. Vai a **Admin → enforcement** e rivedi i totali di enforce e observe. +2. Cerca una macchina per ID o label, o filtra le macchine a cui manca una policy. +3. Espandi una riga per confrontare le policy assegnate, la distribuzione segnalata, l'ultimo check-in e la cronologia. +4. Aggiorna dopo l'intervallo di polling della macchina quando una distribuzione applicata è ancora in sospeso. + +![La flotta Enforcement che mostra la copertura della policy, lo stato di distribuzione della macchina e gli incarichi observe e enforce.](/images/dashboard/enforcement-fleet.png) + +Cerca macchine che non hanno mai ricevuto l'ultima distribuzione, macchine registrate che hanno smesso di segnalare, una policy assegnata all'ambiente sbagliato e drift di versione dopo un aggiornamento interrotto. + +Etichetta le macchine per workload e ambiente — i nomi host da soli raramente sopravvivono all'autoscaling o alla sostituzione: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - La gestione dell'enforcement è un flusso di lavoro amministrativo di Cloud. Non trattare le rotte di enforcement solo-root come endpoint API ordinari `/v1` del cliente. + La gestione dell'enforcement è un flusso di lavoro Cloud amministrativo. Non trattare le route di enforcement root-only come endpoint `/v1` ordinari del cliente. \ No newline at end of file diff --git a/docs/it/policies/editor.mdx b/docs/it/policies/editor.mdx index 2c85e597..95876cd9 100644 --- a/docs/it/policies/editor.mdx +++ b/docs/it/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "Editor criteri" -description: "Crea e rivedi i criteri con versione a partire da una modalità di errore confermata." +title: "Scrivi una policy" +description: "Lascia che Failproof AI rediga una policy da un risultato di audit, o scrivi il codice sorgente tu stesso, quindi rivedilo, testalo e pubblicalo." icon: "file-pen-line" --- -Utilizza l'editor criteri per trasformare un risultato o un problema in una regola distribuibile. Mantieni la creazione separata dalla distribuzione in modo che una bozza non possa modificare silenziosamente il comportamento in produzione. +Ci sono due modi per scrivere una policy: lasciare che Failproof AI la rediga da un risultato di audit, oppure scrivere il codice sorgente tu stesso. Nulla viene pubblicato o distribuito finché non scegli di farlo. -Quando un problema ha un modello di azione ripetibile, aprilo in **Analyze → issues** e seleziona **generate policy**. Failproof AI spiega innanzitutto se un criterio può esprimere il problema, quindi trasporta l'intento rivisto e il contesto del risultato nell'editor. La fonte generata rimane una bozza finché non la pubblichi. +## Scrivi una policy da un audit -## Pubblica una versione del criterio +Un audit trova un errore; una policy lo impedisce che accada di nuovo. Failproof AI redige la policy dalla stessa evidenza del risultato. + +### 1. Esegui un audit + +[Esegui un audit](/it/audits/run) sulle sessioni in cui si verifica l'errore. Ogni risultato contiene le sessioni di evidenza, una causa radice e un percorso di prevenzione suggerito. Lavora da un risultato con un **pattern di azione ripetibile** — una policy può solo bloccare ciò che riesce a riconoscere in un evento hook. + +### 2. Genera la bozza - 1. Vai a **Admin → policy editor** e, in **compose**, descrivi la modalità di errore o incolla la fonte della policy JavaScript. - 2. Convalida la fonte e correggi ogni errore segnalato. - 3. Inserisci l'identità del criterio e pubblicalo, quindi utilizza **library** per confrontare o disabilitare le versioni. - 4. Seleziona **enforcement** quando la versione è pronta per una distribuzione su machine. + 1. Apri il problema del risultato in **Analyze → issues** e controlla le sessioni citate, la causa radice e la raccomandazione. + 2. Seleziona **generate policy**. Failproof AI innanzitutto indica se una policy può esprimere il problema. Un risultato **no policy** significa che la soluzione è un avviso, un cambiamento di flusso di lavoro, o una persona — non una policy. + 3. Seleziona **write this policy**. Il titolo del problema, il risultato, la causa radice, la raccomandazione e l'intento di enforcement proposto diventano una bozza in **Admin → policy editor**. Usa **open the editor anyway** quando non sei d'accordo con il controllo di candidatura. - ![La vista compose dell'editor criteri con identità del criterio, redazione assistita da IA, convalida della fonte e controlli di pubblicazione.](/images/dashboard/policy-editor.png) + ![La vista compose dell'editor di policy con identità della policy, drafting assistito da AI, validazione del sorgente e controlli di pubblicazione.](/images/dashboard/policy-editor.png) - Pubblica da CLI con `fp policies publish`. Crea una **nuova versione** e non ne modifica mai una sul posto, inoltre verifica la sintassi della fonte con node prima di inviare — nessun componente downstream lo fa, quindi un errore di sintassi altrimenti emergerebbe sulla machine al momento dell'enforcement: + Leggi l'evidenza, quindi redigi con l'assistente. `compose` stampa il sorgente per la revisione e non pubblica nulla: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - La pubblicazione non distribuisce nulla — una nuova versione rimane inutilizzata finché `fp fleet deploy` non la mette su una machine. `fp policies compose ""` redige la fonte con l'assistente Cloud e la stampa per la revisione piuttosto che pubblicarla. - - Per installare un criterio in un agente CLI locale (non Cloud), utilizza `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. + `compose` richiede una sessione autenticata (`fp login`) il cui ruolo ha `policies:write`; rifiuta le chiavi API. -## Checklist di creazione +### 3. Rivedi la bozza + +Una bozza è un punto di partenza, non un verdetto. Prima di pubblicare, verifica che: + +1. Nomini la modalità di errore in linguaggio operativo. +2. Corrisponda solo agli eventi hook e agli strumenti che portano sufficienti evidenze per decidere. +3. Utilizzi la condizione più ristretta che catturi l'azione non sicura. +4. Restituisca un motivo che dica all'agente cosa fare invece. +5. Utilizzi `instruct` dove l'agente può correggere il corso in modo sicuro, e `deny` solo dove consentire l'azione è inaccettabile o irreversibile. + +Valida il sorgente nell'editor e correggi ogni errore segnalato. + +### 4. Testalo, quindi pubblicalo + +Esegui **backtest** sotto il sorgente prima di pubblicare: riproduce la bozza rispetto alle chiamate già effettuate dalla tua flotta e conta le chiamate funzionanti che avrebbe interrotto. [Test a policy](/it/policies/test) copre questo e gli altri controlli. + +Quando si comporta correttamente, inserisci l'identità della policy e seleziona **publish version**. La pubblicazione crea una versione immutabile e non distribuisce nulla: rimane inutilizzata finché non la [distribuisci](/it/policies/deploy). Da un terminale: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` effettua controlli di parse sul sorgente prima di inviarlo, così un errore di sintassi emerge qui invece che su una macchina al momento dell'enforcement. + +## Scrivila tu stesso + +Una policy è JavaScript o TypeScript contro l'API `failproofai`: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +Questo corrisponde a `production/config.yml`, `/srv/production/config.yml`, `/srv/production` e `C:\\production\\config.yml` per sia `Write` che `Edit`, ma non a `production-backup`: `production` deve essere un segmento di percorso intero. Il contesto contiene anche il tipo di evento, il payload normalizzato, i metadati della sessione, i parametri e la CLI sorgente quando disponibile — vedi l'[SDK per policy](/it/reference/policy-sdk). + +Per pubblicarla come versione, incolla il sorgente in **compose** in **Admin → policy editor** e segui i passaggi 3 e 4 sopra, oppure pubblica il file da un terminale con `fp policies publish`. -1. Assegna un nome alla modalità di errore nel linguaggio operativo. -2. Seleziona gli eventi hook e gli strumenti che contengono prove sufficienti per decidere. -3. Scrivi la condizione più ristretta che corrisponda al comportamento non sicuro. -4. Restituisci un motivo che comunichi all'agente o all'operatore cosa fare dopo. -5. Aggiungi esempi che dovrebbero corrispondere ed esempi che devono rimanere consentiti. -6. Salva una nuova versione e richiedi una revisione. +Per eseguirla su una macchina senza Cloud, salvala in `.failproofai/policies/` con un nome che termina in `policies.js`, `policies.mjs` o `policies.ts` — questi si caricano automaticamente in ambito progetto e utente — o installala per percorso: -Utilizza `instruct` quando l'agente può correggere il corso in modo sicuro. Utilizza `deny` quando consentire l'azione comporterebbe un rischio inaccettabile o irreversibile. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - Le versioni dei criteri sono input di distribuzione immutabili. La modifica di una bozza crea una nuova versione; non dovrebbe riscrivere la versione già assegnata alle machine. - \ No newline at end of file +Assegna a ogni policy un nome univoco tra le policy di convenzione, personalizzate, di pack e gestite da Cloud. \ No newline at end of file diff --git a/docs/it/policies/failure-behavior.mdx b/docs/it/policies/failure-behavior.mdx index bd5548bd..fe082d6a 100644 --- a/docs/it/policies/failure-behavior.mdx +++ b/docs/it/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- title: "Comportamento in caso di errore" -description: "Scopri cosa accade quando la valutazione delle policy o il daemon locale non sono disponibili." +description: "Comprendi cosa accade quando la valutazione delle policy o il daemon locale non sono disponibili." icon: "shield-alert" --- -Failproof AI è progettato in modo che un errore di enforcement sia visibile anziché permettere silenziosamente lavori rischiosi. +Failproof AI è progettato affinché un errore di applicazione sia visibile anziché permettere silenziosamente lavori rischiosi. ## Diagnosticare un blocco failure-closed - 1. Vai a **Admin → enforcement** e apri la macchina. - 2. Controlla il suo ultimo check-in, deployment assegnato e deployment segnalato. - 3. Vai a **Observe → policy** e apri la sessione della decisione negata. - 4. Conferma se il motivo riporta raggiungibilità del daemon, version skew o la policy stessa. + 1. Vai su **Admin → enforcement** e apri la macchina. + 2. Verifica il suo ultimo check-in, il deployment assegnato e il deployment segnalato. + 3. Vai su **Observe → policy** e apri la sessione della decisione negata. + 4. Conferma se il motivo segnala raggiungibilità del daemon, versione non corrispondente o la policy stessa. @@ -23,45 +23,47 @@ Failproof AI è progettato in modo che un errore di enforcement sia visibile anz failproofai config ``` - Rieseguire `failproofai config` aggiorna e riavvia il daemon dopo un aggiornamento del package. + Rieseguire `failproofai config` aggiorna e riavvia il daemon dopo un aggiornamento del pacchetto. -Su una macchina configurata per usare `failproofaid`, il daemon è l'unico valutatore. Se non è raggiungibile o la sua versione di protocollo non corrisponde a quella della CLI, la valutazione dell'hook fallisce in modalità closed. L'azione viene negata con un motivo che guida l'operatore a verificare o aggiornare il daemon. +Su una macchina configurata per usare `failproofaid`, il daemon è l'unico valutatore. Se non è raggiungibile o la sua versione del protocollo non corrisponde a quella della CLI, la valutazione degli hook fallisce in modo chiuso. L'azione viene negata con un motivo che indirizza l'operatore a controllare o aggiornare il daemon. -Prima della configurazione del daemon, gli hook valutano le policy in process. Una volta registrata la configurazione del daemon, Failproof AI non ritorna silenziosamente a un secondo valutatore quando il daemon fallisce. +Prima della configurazione del daemon, gli hook valutano le policy in processo. Una volta registrata la configurazione del daemon, Failproof AI non ritorna silenziosamente a un secondo valutatore quando il daemon fallisce. ## Rispondere a una decisione failure-closed 1. Esegui `failproofai config --status`. -2. Se le versioni differiscono, riesegui `failproofai config` dopo aver aggiornato il package. -3. Se il daemon non è raggiungibile, ispeziona lo stato del suo servizio e i log locali. -4. Riprendi il lavoro dell'agent solo dopo aver verificato che un percorso di valutazione della policy noto sia salubre. +2. Se le versioni differiscono, riesegui `failproofai config` dopo aver aggiornato il pacchetto. +3. Se il daemon non è raggiungibile, ispeziona lo stato del servizio e i log locali. +4. Riprendi il lavoro dell'agent solo dopo aver verificato che un percorso di valutazione delle policy noto sia integro. - Non ritentare ripetutamente l'azione bloccata. Una risposta failure-closed significa che il sistema non ha potuto stabilire che l'azione fosse sicura. + Non riprovare ripetutamente l'azione bloccata. Una risposta failure-closed significa che il sistema non ha potuto stabilire che l'azione fosse sicura. ## Un pack non si carica -Una macchina a cui è stato detto di enforcement di un pack, e che non può eseguirlo, nega anziché continuare silenziosamente. Il trigger è un'**aspettativa registrata**, mai vuota: una macchina senza pack installati è silenziosa, mentre un pack dichiarato che non si risolve — o che registra meno di quanto dichiara il suo manifest — nega. +Una macchina a cui è stato detto di applicare un pack e non può eseguirlo, nega anziché continuare silenziosamente. Il trigger è un'**aspettativa registrata**, mai una vuota: una macchina senza pack installati è silenziosa, mentre un pack che è dichiarato e non si risolverà — o che registra meno di quanto il suo manifest dichiara — nega. -Il deny è **ristretto**, diversamente da un daemon non raggiungibile. Un daemon che non può essere raggiunto significa che nessuna valutazione è accaduta, quindi nulla può essere conosciuto come sicuro. Un pack che non si carica ha un insieme enumerabile di guard mancanti, perché ogni policy dichiarata porta il suo proprio `match` — quindi nega solo gli eventi e gli strumenti che quelle policy coprivano, e tutto il resto procede. +Il diniego è **ristretto**, a differenza di un daemon non raggiungibile. Un daemon che non può essere raggiunto significa che non è avvenuta alcuna valutazione, quindi nulla può essere ritenuto sicuro. Un pack che non si carica ha un insieme enumerabile di protezioni mancanti, perché ogni policy dichiarata porta il suo proprio `match` — quindi nega solo gli eventi e gli strumenti coperti da quelle policy, e tutto il resto procede. Non si attiva per: -- un pack di tipo `observe`, che valuta e scarta per costruzione -- policy che non hai mai preso, o esplicitamente disattivato -- un pack che il loader non ha mai ricevuto, dove "nessuna registrazione" non può essere distinto da un skip deliberato +- un pack `observe`, che valuta e scarta per costruzione +- policy che non hai mai accettato, o che hai esplicitamente disattivato +- un pack che il loader non ha mai ricevuto, dove "nessuna registrazione" non può essere distinto da un salto deliberato - una pausa di sessione attiva -- un timeout di caricamento, che è transitorio — un momento di disco lento non deve negare finché non interviene un umano +- un timeout di caricamento, che è transitorio — un momento di lentezza del disco non deve negare finché un umano non interviene -`UserPromptSubmit` **istruisce** anziché negare, indipendentemente da ciò che la policy mancante ha dichiarato. Un deny universale lo includerebbe e ti bloccherebbe fuori dall'agent che potrebbe risolvere il problema. +`UserPromptSubmit` **istruisce** anziché negare, indipendentemente da ciò che la policy mancante ha dichiarato. Un diniego totale l'includerebbe e ti bloccherebbe fuori dall'agent che potrebbe risolvere il problema. ### Cosa fare ```bash -failproofai pack list +failproofai policies ``` -Nomina qualsiasi pack installato che non si caricherà, dice il motivo ed esce con codice non-zero. Quindi reinstallalo (`failproofai pack add `) o rimuovilo (`failproofai pack remove `) — rimuoverlo ritira l'aspettativa, e il deny si interrompe con essa. \ No newline at end of file +L'elenco segnala un pack installato il cui record di installazione o digest non è più valido e spiega perché. Non importa il pack, quindi uno che fallisce solo una volta caricato — registrando meno di quanto il suo manifest dichiara — viene elencato normalmente; il diniego sottostante è ciò che lo identifica. In ogni caso, reinstallalo (`failproofai policies add `) o rimuovilo (`failproofai policies remove `) — rimuoverlo ritira l'aspettativa e il diniego si interrompe con esso. + +Il diniego stesso è attribuito a `pack/failproofai-pack-unavailable`, che ha la precedenza sulle policy che si sono caricate, quindi una chiamata di strumento bloccata nomina il pack mancante anziché una qualsiasi protezione superstite che casualmente si è attivata per prima. \ No newline at end of file diff --git a/docs/it/policies/local-configuration.mdx b/docs/it/policies/local-configuration.mdx index a758d960..d07ec7d3 100644 --- a/docs/it/policies/local-configuration.mdx +++ b/docs/it/policies/local-configuration.mdx @@ -4,30 +4,25 @@ description: "Controlla l'ambito delle policy, i parametri, i file personalizzat icon: "file-cog" --- -Failproof AI separa la selezione delle policy dalle impostazioni della macchina e del daemon. Questo mantiene le scelte delle policy del repository revisionabili mentre le credenziali e lo stato del daemon rimangono al di fuori del repository. +Failproof AI mantiene separato ciò che un repository può eseguire nel commit — il cablaggio dei hook, i parametri delle policy, le policy personalizzate — dallo stato della macchina come credenziali, pack installati e daemon. -## Scegli un ambito di policy +## Scegli un ambito - - - Esegui `failproofai` senza argomenti per aprire il dashboard locale delle policy. Scegli l'ambito utente, progetto o locale prima di abilitare una policy in modo che la modifica venga scritta nel file di configurazione desiderato. +Un ambito decide dove vengono cablati gli hook e in quale file di configurazione scrivi i parametri e i percorsi delle policy personalizzate: - - **User** si applica in tutti i progetti su questa macchina. - - **Project** appartiene al repository e può essere committed. - - **Local** sostituisce un progetto per un utente e dovrebbe rimanere gitignored. +- **User** si applica a tutti i progetti su questa macchina. +- **Project** appartiene al repository e può essere sottoposto a commit. +- **Local** sovrascrive un progetto per un utente e deve rimanere gitignored. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # wire hooks for this repository +failproofai policies --install --cli claude --scope user # or for every project on this machine +failproofai policies +``` - Non tutti i harness supportano l'ambito locale. La CLI rifiuta un ambito che l'harness selezionato non può rappresentare. - - +Non tutti gli harness supportano l'ambito locale; la CLI rifiuta un ambito che l'harness selezionato non può rappresentare. + +Quali policy dei pack sono attive **non** sono scoped. L'interruttore viene registrato con il pack installato, quindi `failproofai policies add ` attiva una policy per tutta la macchina, indipendentemente da ciò che dice `--scope`. | Ambito | File di configurazione della policy | | --- | --- | @@ -35,21 +30,20 @@ Failproof AI separa la selezione delle policy dalle impostazioni della macchina | Local | `/.failproofai/policies-config.local.json` | | User | `~/.failproofai/policies-config.json` | -Le policy abilitate vengono unite come un'unione. I parametri della policy utilizzano il primo ambito che definisce i parametri per quella policy, nell'ordine project → local → user. I percorsi delle policy personalizzate espliciti utilizzano il primo ambito che li definisce. +I parametri delle policy utilizzano il primo ambito che definisce i parametri per quella policy, nell'ordine project → local → user. I percorsi espliciti delle policy personalizzate utilizzano il primo ambito che li definisce. -## Configura i parametri della policy +## Configura i parametri delle policy - Apri la policy nel dashboard locale, modifica i parametri supportati e salva nell'ambito selezionato. Esegui un'azione dell'agent corrispondente e una non corrispondente, quindi ispeziona la decisione in **Observe → policy**. + Apri la policy nel dashboard locale, modifica i suoi parametri supportati e salva nell'ambito selezionato. Esegui un'azione dell'agent corrispondente e non corrispondente, quindi ispeziona la decisione in **Observe → policy**. - Modifica il `policies-config.json` dell'ambito selezionato, quindi esegui `failproofai policies` per evidenziare i nomi delle policy o le chiavi dei parametri sconosciuti. + Modifica il file `policies-config.json` dell'ambito selezionato, quindi esegui `failproofai policies`: ti avviserà di una voce `policyParams` che nomina una policy che nessun pack installato contiene. Non controlla le chiavi all'interno di una voce, quindi verifica la loro ortografia rispetto alla tabella sottostante. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ Le policy abilitate vengono unite come un'unione. I parametri della policy utili +### Parametri che le policy di Failproof AI accettano + +Ogni policy valida i suoi propri tipi di parametri. + +| Policy | Parametro | Tipo e impostazione predefinita | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; le voci contengono `regex` e `label` | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| Infrastructure blockers | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + Un pattern di allowance amplia ciò che un agent può fare. Testa l'esatta tokenizzazione e le varianti di comando sull'harness di destinazione prima di implementarla in un parco. + + ## Comprendi i file della macchina `~/.failproofai` contiene file separati per confini di fiducia separati: | Percorso | Scopo | | --- | --- | -| `config.json` | Impostazioni di daemon, audit e telemetria non segrete | -| `credentials.json` | Credenziali cloud; archiviate con permessi solo del proprietario | -| `policies-config.json` | Selezione builtin a livello di ambito utente, parametri e percorsi personalizzati espliciti | -| `policies/` | Policy di convenzione utente e artefatti di policy gestiti dal cloud | -| `hook-activity/` | Log locale delle decisioni della policy | -| `state/` | Spool del daemon, salute, pausa e stato di runtime | +| `config.json` | Impostazioni daemon, audit e telemetry non sensibili | +| `credentials.json` | Credenziali cloud; archiviati con permessi solo del proprietario | +| `policies-config.json` | Parametri di ambito utente e percorsi espliciti delle policy personalizzate | +| `policies/` | Policy di convenzione utente, pack installati e quali delle loro policy sono attive, e artefatti di policy gestiti da Cloud | +| `hook-activity/` | Log locale delle decisioni di policy | +| `state/` | Spool daemon, salute, pausa e stato di runtime | -Usa `FAILPROOFAI_HOME` per riposizionare il layout completo della macchina per un contenitore o un test isolato. Non riposizionare le directory di stato individuali indipendentemente. +Utilizza `FAILPROOFAI_HOME` per riposizionare il layout completo della macchina per un container o un test isolato. Non riposizionare le directory di stato individualmente in modo indipendente. - Non eseguire mai il commit di `credentials.json`. Esegui il commit della configurazione della policy del progetto e delle policy di convenzione del progetto solo dopo averle riviste come codice di applicazione. + Non eseguire mai il commit di `credentials.json`. Esegui il commit della configurazione della policy del progetto e delle policy di convenzione del progetto solo dopo averle revisionate come codice di enforcement. \ No newline at end of file diff --git a/docs/it/policies/overview.mdx b/docs/it/policies/overview.mdx index 4213fa2d..4c6d30ea 100644 --- a/docs/it/policies/overview.mdx +++ b/docs/it/policies/overview.mdx @@ -1,63 +1,54 @@ --- -title: "Politiche" -description: "Osserva, guida o blocca le azioni degli agenti prima che un errore noto si ripeta." +title: "Policies" +description: "Osserva, guida o blocca le azioni dell'agente prima che un errore noto si ripeta." icon: "shield-check" --- -Una politica valuta un evento hook dell'agente e restituisce una di tre decisioni: +Una policy valuta un evento hook dell'agente e restituisce una di tre decisioni: - `allow` consente all'azione di continuare. - `instruct` fornisce all'agente una guida correttiva. - `deny` blocca l'azione con una motivazione. -## Utilizza le tre superfici di politica +## Dove si trovano le policy - - - 1. Vai a **Observe → policy** per filtrare e ispezionare le decisioni di politica dalle sessioni. - 2. Vai a **Admin → policy editor** per comporre, convalidare, pubblicare, disabilitare o ispezionare versioni immutabili. - 3. Vai a **Admin → enforcement** per assegnare versioni ed effetti alle macchine. +| Nel dashboard | Cosa fai lì | +| --- | --- | +| **Observe → policy** | Rivedi le decisioni dalle sessioni reali: quale policy ha corrisposto, su quale macchina e perché | +| **Admin → policy editor** | Scrivi una policy, effettua un backtest rispetto al traffico passato, pubblica una versione immutabile e confronta le versioni in **library** | +| **Admin → enforcement** | Distribuisci le versioni sulle macchine, in modalità observe o enforce | - Utilizza la pagina Policy per comprendere cosa sta già corrispondendo prima di creare o modificare l'applicazione. +L'editor di policy è dove un errore diventa una regola. Descrivi la modalità di errore o incolla il codice della policy in **compose**, effettua un backtest della bozza rispetto al traffico che hai già, e pubblica una versione: - ![La pagina Policy che mostra i totali delle decisioni e i mapping delle politiche gestite localmente e nel Cloud.](/images/dashboard/policy-observe.png) +![La vista compose dell'editor di policy con identità della policy, drafting assistito da AI, convalida del codice sorgente e controlli di pubblicazione.](/images/dashboard/policy-editor.png) - L'editor è il luogo in cui trasformi una condizione di errore in codice, la convalidi e pubblichi una versione immutabile. +Su una macchina, `failproofai policies` elenca tutto ciò che viene applicato lì. `fp policies` e `fp fleet` coprono l'editor e l'enforcement da un terminale — vedi il [Cloud CLI reference](/it/reference/cloud-cli). - ![L'editor Policy utilizzato per comporre e pubblicare una versione di politica immutabile.](/images/dashboard/policy-editor.png) +## Ottieni una policy - L'applicazione assegna quindi quella versione pubblicata e il suo effetto di osservazione o applicazione alle macchine. - - ![La flotta di applicazione che mostra la copertura delle macchine e le versioni di politica assegnate.](/images/dashboard/enforcement-fleet.png) - - Verifica le decisioni sulla pagina Policy dopo la distribuzione in modo che le visualizzazioni di creazione e flotta siano legate all'attività reale dell'agente. - - - Utilizza `failproofai` per l'installazione e la convalida locale della politica: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - Utilizza `fp` per trovare le sessioni e gli eventi del Cloud contenenti decisioni di politica. La creazione nel Cloud e la distribuzione della flotta rimangono flussi di lavoro del dashboard. - - - -Le politiche hanno tre superfici distinte in Failproof AI: - -1. **Analizza le decisioni** nelle sessioni, nei dashboard e negli audit. -2. **Crea versioni** con regole integrate, codice o l'editor di politica. -3. **Distribuisci e applica** versioni su macchine selezionate. - -Inizia da una modalità di errore confermata. Definisci l'evento e l'abbinamento di strumento più piccoli che lo identificano, testa esempi legittimi e non sicuri, quindi osserva prima di applicare. +Ci sono due modi per ottenerne una. - - Abilita una regola verificata per rischi comuni di segreti, shell, Git, cloud e flussi di lavoro. + + Lascia che Failproof AI ne rediga una da una rilevazione di audit, oppure scrivi il codice sorgente tu stesso, quindi rivedi e pubblica nell'editor. - - Esprimi una decisione specifica del flusso di lavoro in JavaScript o TypeScript. + + Integra un policy pack di Failproof AI per il tuo caso d'uso, oppure un pack della community dall'hub delle policy, con un unico comando. - \ No newline at end of file + + +## Poi distribuiscilo + + + + Effettua un backtest della bozza rispetto al traffico che hai già, ed eseguila su un'azione che deve bloccare e una che deve consentire — tutto prima di pubblicare. Vedi [Test a policy](/it/policies/test). + + + Metti la versione sulle macchine in modalità **observe**, leggi le sue decisioni, quindi applica l'enforce. Vedi [Deploy a policy](/it/policies/deploy). + + + Ogni pubblicazione è una versione nuova e immutabile, quindi un rollout che blocca lavoro valido viene annullato ridistribuendo l'ultima versione buona. Vedi [Versions and rollback](/it/policies/rollback). + + + +Per condividere le tue policy con altri team, [pubblicale come pack](/it/policies/publish-a-pack). Per scoprire cosa accade quando una policy non può essere valutata affatto, vedi [Failure behavior](/it/policies/failure-behavior). \ No newline at end of file diff --git a/docs/it/policies/packs.mdx b/docs/it/policies/packs.mdx index b6cdebb9..b4b9dfda 100644 --- a/docs/it/policies/packs.mdx +++ b/docs/it/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "Policy pack" -description: "Installa una serie di policy pubblicate come release su GitHub e gestisci cosa viene applicato." +title: "Usa un policy pack" +description: "Collega un policy pack di Failproof AI per il tuo caso d'uso, o un pack della comunità dall'hub delle policy, e scegli cosa applica." icon: "package" --- -Un pack è un insieme di policy pubblicate come release su GitHub. Un unico comando lo installa, i checksum della release vengono verificati prima che qualsiasi cosa venga eseguita, e il digest viene registrato in modo che il pack non possa cambiare sulla tua macchina in seguito. +Un pack è un insieme di policy pubblicate come release di GitHub. Un solo comando le installa: i checksum della release vengono verificati prima di qualsiasi esecuzione, e il suo digest viene registrato in modo che il pack non possa cambiare sulla tua macchina in seguito. -## Installa le policy di Failproof AI +Sfoglia ogni pack e ogni policy in ciascuno su [policy hub](https://befailproof.ai/policy-hub/). Ce ne sono due tipi: + +- **Policy pack di Failproof AI** — pack pronti per casi d'uso predefiniti: collegane uno e funziona. Il [coding agent policy pack](https://befailproof.ai/policy-hub/failproofai/policies/) è disponibile ora, e pack per altri casi d'uso arriveranno presto. +- **Policy pack della comunità** — policy scritte da sviluppatori per i loro casi d'uso e pubblicate affinché chiunque le possa utilizzare. + +## Policy pack di Failproof AI + +### Coding agent policy pack ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -Questo installa l'insieme che pubblichiamo, dalla copia inclusa nel package — non richiede quindi connessione di rete e non può fallire dietro un proxy. Prendi parte di esso: +Il pack contiene 38 policy e attiva le 10 che il suo manifest contrassegna come sicure per l'esecuzione automatica; le altre sono elencate perché tu possa scegliere. Alcune delle più utilizzate, e se un semplice `policies add` le attiva: + +| Policy | Cosa fa | Attivo per impostazione predefinita | +| --- | --- | --- | +| `block-push-master` | Blocca i push diretti ai branch protetti | Sì | +| `block-env-files` | Blocca la lettura e la scrittura di file `.env` | Sì | +| `protect-env-vars` | Blocca i comandi che scaricano le variabili d'ambiente | Sì | +| `block-sudo` | Blocca `sudo` se non corrisponde un pattern di autorizzazione | Sì | +| `block-curl-pipe-sh` | Blocca gli script scaricati direttamente piped in una shell | Sì | +| `sanitize-*` (cinque policy) | Segnala chiavi API, bearer token, JWT, chiavi private e stringhe di connessione trovate nell'output dello strumento | Sì | +| `block-rm-rf` | Blocca le eliminazioni ricorsive catastrofiche | No | +| `block-force-push` | Blocca i force-push | No | +| `block-secrets-write` | Blocca le scritture su file di credenziali e chiavi segrete | No | +| `warn-destructive-sql` | Avvisa su `DROP`, `TRUNCATE` e `DELETE` senza `WHERE` | No | + +Attiva qualsiasi policy disattivata per nome — `failproofai policies add block-rm-rf` — o prendi tutto il pack con `--all`. Vedi ogni policy in esso, raggruppate per categoria: ```bash -failproofai pack add core --policy block-rm-rf # uno, o pochi separati da virgola -failproofai pack add core --category dangerous-commands # un'intera categoria -failproofai pack add core --all # tutto ciò che contiene +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` elenca ogni categoria che il pack offre. +## Policy pack della comunità -## Vedi cosa contiene un pack, prima di installarlo +Gli sviluppatori pubblicano pack per i casi d'uso che hanno incontrato, e l'[policy hub](https://befailproof.ai/policy-hub/) li elenca. Un pack della comunità è pubblicato dal suo autore, non controllato da Failproof AI, quindi leggi cosa contiene prima di installarlo: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -Elenca ogni policy che il pack contiene, raggruppata per categoria, indicando quali vengono attivate per impostazione predefinita dall'autore e quali sono opzionali. Legge **solo il manifest** — l'artifact di accesso non viene mai scaricato e mai importato, quindi guardare il pack di uno sconosciuto non può eseguire il codice di uno sconosciuto. Il manifest è comunque verificato rispetto ai `SHA256SUMS` propri della release, quindi quello che stai leggendo è quello che verrebbe installato. - -`failproofai pack list` senza una fonte elenca i pack già installati qui. +Elenca ogni policy che contiene, raggruppate per categoria, e contrassegna quali l'autore attiva per impostazione predefinita. Legge **solo il manifest** — l'artefatto di input non viene mai scaricato o importato, quindi esaminare il pack di uno sconosciuto non può eseguire il codice di uno sconosciuto. Il manifest è ancora controllato rispetto ai `SHA256SUMS` della release stessa, quindi quello che leggi è quello che verrebbe installato. -## Installa il pack di qualcun altro +Poi installalo: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -Tutti questi funzionano — incolla quello che hai: +Qualsiasi di questi funziona — incolla quello che hai: -| Fonte | Risultato | +| Sorgente | Risultato | | --- | --- | -| `acme/support-agent` | Release più recente, **fissata** al tag esatto che ha risolto | +| `acme/support-agent` | Release più recente, **bloccata** al tag esatto che ha risolto | | `acme/support-agent@v2.1.0` | Quella release | -| `github:acme/support-agent@v2.1.0` | La stessa, scritta esplicitamente | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | La stessa, copiata da un browser | +| `github:acme/support-agent@v2.1.0` | Lo stesso, scritto esplicitamente | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Lo stesso, copiato da un browser | -Se non specifichi un tag, installa la release più recente **e la fissa**, poi ti dice quale tag ha scelto. Quello che viene registrato nomina sempre esattamente una release, quindi una reinstallazione non può divergere. +Se non specifichi alcun tag installi la release più recente **e la blocchi**, poi ti dice quale tag ha scelto. Quello che viene registrato nomina sempre esattamente una release, così una reinstallazione non può divergere. -## Prendi parte di un pack +## Prendi una parte di un pack -Per impostazione predefinita ottieni i **propri** default del pack — le policy che l'autore ha marcato come sicure da attivare senza supervisione — non tutto ciò che contiene. +Per impostazione predefinita ottieni i valori predefiniti **propri** del pack — le policy che l'autore ha contrassegnato come sicure per l'attivazione automatica — non tutto quello che contiene. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # una, o alcuni separati da virgola +failproofai policies add FailproofAI/policies --category dangerous-commands # un'intera categoria +failproofai policies add FailproofAI/policies --all # tutto quello che contiene ``` -`--category` e `--policy` si combinano come unione (`--only` è accettato come sinonimo di `--policy`). Ri-aggiungere una versione più recente mantiene quello che hai scelto piuttosto che riattivare il resto. +`--category` e `--policy` si combinano come unione (`--only` è accettato come sinonimo di `--policy`). Quando il pack è già installato, i flag si aggiungono a quello che avevi, e reinstallarlo senza flag e senza terminale — per aggiornare, ad esempio — mantiene la tua selezione così com'è. In un terminale senza flag, `add` apre il selettore, preselezionato con i valori predefiniti dell'autore, e quello che selezioni sostituisce la tua selezione. ## Gestisci cosa è attivo ```bash -failproofai policies # ogni fonte in un unico elenco, pack inclusi -failproofai pack list # solo pack, raggruppati per categoria -failproofai policies --uninstall block-refunds # disattiva una policy del pack -failproofai policies --install block-refunds # e riattiva -failproofai pack remove acme/support-agent +failproofai policies # ogni sorgente in un unico elenco, pack inclusi +failproofai policies add block-rm-rf # attiva una policy +failproofai policies --uninstall block-refunds # disattiva una policy di pack +failproofai policies --install block-refunds # e attivala di nuovo +failproofai policies remove acme/support-agent # disinstalla il pack ``` -Un nome senza qualificazione significa il **built-in** quando ne esiste uno con quel nome. Specifica il nome della copia del pack esplicitamente quando ne hai bisogno: +Attivare o disattivare una policy di pack si applica all'intera macchina: l'interruttore viene registrato con il pack installato, non nella configurazione di un progetto, qualunque cosa dica `--scope`. + +Un nome senza barra è una policy; qualsiasi cosa con una è una sorgente di pack. Un nome semplice si risolve nel pack installato che la dichiara. Quando due pack installati dichiarano lo stesso nome, specifica quale intendi: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -Se un pack distribuisce una policy il cui nome è anche un **built-in abilitato**, il built-in viene eseguito e la copia del pack viene saltata — la stessa protezione non verrebbe altrimenti valutata due volte. Disattiva il built-in per usare la copia del pack al suo posto. - - -## Da dove provengono le policy di Failproof AI - -`core` legge la copia inclusa nel package npm. Lo stesso insieme è pubblicato come release su GitHub, che è quello che installi se desideri una versione specifica: - -```bash -failproofai pack add core # da questo package, senza rete -failproofai pack add FailproofAI/policies # lo stesso insieme, dalla sua release su GitHub -``` +Gli ambiti, i parametri e i file che questi comandi scrivono sono coperti in [configurazione locale](/it/policies/local-configuration). -## Cosa garantisce e cosa non garantisce l'integrità +## Cosa l'integrità fa e non fa -`SHA256SUMS` è incluso nella stessa release dell'artifact, quindi **non** è una firma e non prova nulla su chi lo ha pubblicato. Quello che prova è che i byte sono quelli pubblicati da quella release — e poiché il digest viene registrato quando aggiungi il pack e ri-verificato prima di ogni importazione, un pack non può cambiare sulla tua macchina in seguito. Un repository che retag o sostituisce un asset smette di caricarsi anziché eseguire silenziosamente qualcosa di diverso. +`SHA256SUMS` è spedito nella stessa release dell'artefatto, quindi **non** è una firma e non prova nulla su chi l'ha pubblicato. Quello che prova è che i byte sono quelli che quella release ha pubblicato — e poiché il digest viene registrato quando aggiungi il pack e verificato di nuovo prima di ogni import, un pack non può cambiare sulla tua macchina in seguito. Un repository che ritag o sostituisce un asset smette di caricarsi invece di eseguire silenziosamente qualcos'altro. -Al momento dell'installazione, il pack viene anche **importato una sola volta** e verificato rispetto al suo manifest. Un pack il cui artifact non viene analizzato, o che registra qualcosa di diverso da quello che dichiara, viene rifiutato prima che qualsiasi cosa venga attivata — piuttosto che installarsi correttamente e fallire alla prossima chiamata di tool. +Al momento dell'installazione il pack viene anche **importato una volta** e controllato rispetto al suo manifesto. Un pack il cui artefatto non viene analizzato, o che registra qualcosa di diverso da quello che dichiara, viene rifiutato prima che qualsiasi cosa venga attivata — piuttosto che installare correttamente e fallire nella tua prossima chiamata allo strumento. -## Quando un pack non si carica +## Quando un pack non si caricherà -Un pack che questa macchina è stata incaricata di applicare e non può eseguire **nega** gli eventi coperto dalle sue policy mancanti, anziché permetterli silenziosamente. Vedi [Comportamento in caso di errore](/it/policies/failure-behavior). `failproofai pack list` elenca qualsiasi pack in quello stato ed esce con codice non-zero. +Un pack che questa macchina è stata istruita ad applicare e non riesce a eseguire **nega** gli eventi coperti dalle sue policy mancanti, piuttosto che consentirli silenziosamente — come `pack/failproofai-pack-unavailable`, che ha la priorità sulle policy che hanno caricato in modo che il rifiuto sia attribuito al pack mancante piuttosto che a qualsiasi guard che sia stato il primo a attivarsi. L'eccezione è `UserPromptSubmit`, che istruisce invece: rifiutare lì ti bloccherebbe fuori dall'agente di cui hai bisogno per risolverlo. Vedi [Comportamento in caso di errore](/it/policies/failure-behavior). ## Offline e mirror | Variabile | Effetto | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Rifiuta di recuperare; i pack già installati continuano a essere applicati | -| `FAILPROOFAI_PACK_BASE_URL` | Indirizza il recupero dei pack verso un mirror anziché `github.com` | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Rifiuta di recuperare; i pack già installati continuano ad applicarsi | +| `FAILPROOFAI_PACK_BASE_URL` | Indirizza il recupero dei pack a un mirror invece di `github.com` | -Pubblicare il tuo pack: vedi [Pubblica un pack](/it/policies/publish-a-pack). \ No newline at end of file +Per condividere le tue policy in questo modo, vedi [Pubblica un policy pack](/it/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/it/policies/publish-a-pack.mdx b/docs/it/policies/publish-a-pack.mdx index 60bbea2f..0d9b00e0 100644 --- a/docs/it/policies/publish-a-pack.mdx +++ b/docs/it/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "Pubblica un pack" -description: "Distribuisci le tue policy come rilascio GitHub che chiunque può installare." +title: "Pubblicare un policy pack" +description: "Distribuisci le tue policy come release GitHub che chiunque può installare." icon: "upload" --- -Un pack è costituito da tre file allegati a un rilascio GitHub. `failproofai pack build` scrive tutti e tre partendo da un file di policy che hai già. +Un pack è costituito da tre file allegati a una release GitHub. `failproofai publish` scrive tutti e tre dai file di policy di fronte a te, crea la release e li carica. ## 1. Scrivi le policy -Un file, utilizzando la stessa API di qualsiasi custom policy. Due campi extra sono importanti per un pack: +Inizia da qualcosa che già funziona piuttosto che da un template vuoto: + +```bash +failproofai publish --init +``` + +Ti chiede come si chiama il pack, scrive `.mjs` e si ferma — nessuna rete, nessun git, niente pubblicato. Il file che scrive è una policy che già blocca `git push --force`. Si rifiuta di sovrascrivere un file che esiste. + +Le policy usano la stessa API di qualsiasi policy personalizzata. Due campi extra contano per un pack: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` di default è **false** quando lo ometti. Un semplice `failproofai pack add` attiva solo quello che hai contrassegnato — installare senza controllo ogni policy di uno sconosciuto non è una decisione che l'installer dovrebbe prendere per l'utente. +`defaultEnabled` di default è **false** quando lo ometti. Un semplice `failproofai policies add` attiva solo ciò che hai contrassegnato — installare tutte le policy di uno sconosciuto senza supervisione non è una decisione che l'installatore deve prendere per il suo utente. + +Scrivi quanti file vuoi; uno per categoria si legge bene. Ogni file nella directory che registra policy è raggruppato nell'unico artefatto che un pack deve avere. -La voce deve essere **un singolo file autocontenuto**. Solo la voce è fissata con digest, quindi un pack che importa file locali non potrebbe onestamente affermare che il digest copre ciò che viene eseguito. Raggruppa prima (`esbuild`, `bun build`, `rollup`) e costruisci il pack dal bundle — `pack build` rifiuta un import locale piuttosto che distribuire una promessa che non può mantenere. + Il raggruppamento richiede **bun**. Senza di esso, limitati a un file autocontenuto. In ogni caso, l'entry pubblicato non deve importare file locali al momento dell'installazione: solo l'entry è bloccato con digest, quindi un pack che raggiungesse i fratelli non potrebbe onestamente affermare che il digest copre ciò che viene eseguito — e `publish` si rifiuta piuttosto che distribuire una promessa che non può mantenere. -## 2. Costruisci gli asset del rilascio +## 2. Prova prima qui + +Prima che altri possano vederla, applica il file su questa macchina: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +Qualsiasi percorso, qualsiasi nome file. Chiedi al tuo agent di fare la cosa che hai bloccato e guardala essere rifiutata. Niente è pubblicato e nessun altro è interessato. [Test a policy](/it/policies/test) copre il resto: il caso legittimo che deve permettere e gli input che lo rompono. + +## 3. Pubblicalo + +```bash +failproofai publish ``` -Scrive tre file e convalida ogni policy con le **proprie regole del loader** prima — quindi un pack che non potrebbe mai essere installato fallisce qui, dove puoi correggerlo: +Scopre dove pubblicare, cosa raggruppare e quale versione chiamarla, e chiede solo quando il repository non dice nulla. In ordine, fermandosi prima di creare una release se c'è qualcosa di sbagliato: + +1. Trova i file di policy qui per **contenuto** — quelli che importano `failproofai` e chiamano `customPolicies.add` — piuttosto che per nome file, quindi trova `guards.mjs` e ignora un `policies.mjs` non correlato. Non scende nelle sottodirectory, quindi un fixture di test non viene mai raccolto accidentalmente. +2. Legge il repository da `git remote get-url origin`, nella **directory del file** piuttosto che nella tua, e decide la versione. +3. Trova la tua credenziale: `GITHUB_TOKEN`, `GH_TOKEN` o `gh auth login`. Ha bisogno di release-write e nient'altro, e non viene mai stampato. +4. Crea il repository se non esiste. Questo accade prima della build, quindi un pack rifiutato nel passaggio successivo può lasciare dietro un nuovo repository senza release. +5. Costruisce i tre asset, validandoli con le **regole del loader** — lo stesso codice che decide cosa può installare sulla macchina di uno sconosciuto — quindi un pack che non potrebbe mai installare fallisce qui, dove puoi ancora correggerlo. +6. Crea o riutilizza la release e carica, sostituendo gli asset con lo stesso nome. | File | Cos'è | | --- | --- | -| `failproofai-pack.json` | Il manifest: id, version, effect e una voce per ogni policy | -| `failproofai-pack.mjs` | La tua voce, testualmente | +| `failproofai-pack.json` | Il manifest: id, versione, effetto e una voce per policy | +| `failproofai-pack.mjs` | La tua entry raggruppata | | `SHA256SUMS` | ` ` per gli altri due | -Rifiutati al momento della costruzione: un id che non è `publisher/name`, un nome di policy contenente `/`, una policy che dichiara `alwaysOn`, una `description`, `category` o `match` mancante, una voce che non registra nulla e una voce che importa file locali. +I nomi degli asset sono fissi — sono quelli che il CLI del consumer costruisce dai suoi URL, senza API call e senza discovery. -## 3. Allegali a un rilascio +Rifiutato al momento della build: un id che non è `publisher/name`, un nome di policy contenente `/`, una policy dichiarante `alwaysOn`, una `description`, `category` o `match` mancante, un entry che non registra niente e un entry che importa file locali. -Etichetta il rilascio con la stessa versione che hai costruito e allega tutti e tre i file come asset di rilascio: +Sovrascrivi qualsiasi cosa abbia deciso: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -Chiunque può ora installarlo: +`--id` imposta l'id del pack quando dovrebbe differire dal repository, `--tag` imposta il tag della release, `--notes` sostituisce le note di release generate — che è dove `policies show --releases` legge i conteggi e il commit di ogni release — `--out` sceglie dove vengono scritti gli asset (default `dist-pack`), e `--dry-run` li costruisce senza pubblicare e non ha bisogno di credenziale. -```bash -failproofai pack add acme/support-agent -``` +Chiunque può ora installarlo con `failproofai policies add acme/support-agent`. Vedi [policy packs](/it/policies/packs) per fissare una versione e prendere solo parte di una. + +### Elencalo nell'hub di policy -I nomi degli asset sono fissi — sono quelli da cui la CLI di un consumer costruisce i suoi URL, senza chiamata API e senza discovery. +Aggiungi il topic `failproofai-policies` al repository su GitHub. Non c'è modulo di invio e nessuna coda di approvazione: il crawler dell'[hub di policy](https://befailproof.ai/policy-hub/) raccoglie il repository al suo prossimo passaggio. Il topic lo mette solo in considerazione — quello che lo elenca è una release il cui manifest verifica contro il suo `SHA256SUMS` e analizza secondo le stesse regole che il CLI usa, che è esattamente quello che `failproofai publish` produce. + +## Come viene decisa la versione + +La versione è il **commit da cui stai pubblicando** — il suo short sha, dodici caratteri: `a1b2c3d4e5f6`. Non c'è nulla da scegliere e nulla da incrementare, e la versione nomina esattamente da dove vengono i byte, quindi pubblicare la stessa fonte due volte dà la stessa versione. + +È letta dall'albero di fronte a te, mai dalle release del repository, quindi un clone fresco e una macchina isolata dalla rete calcolano la stessa risposta senza chiedere a GitHub cosa è successo prima. + +Perché la versione nomina un commit, quel commit deve esistere. A un terminale, `publish` lo crea per te: inizializza un repository quando non ce n'è uno e commette i file di policy modificati prima di costruire. Si **rifiuta** invece — nominando `--version` come via d'uscita — quando viene eseguito senza terminale (un commit fatto su un runner CI non esisterebbe da nessun'altra parte), quando file diversi dalle policy non sono committati, o in un checkout che non ha ancora commit. Un tag su `HEAD` vince sullo sha — chi ha taggato `v1.2.0` ha detto cos'è questa release. + +Uno sha non porta ordinamento di suo, quindi usa `failproofai policies show / --releases` per vedere quale release è venuta prima — la più recente in cima. ## Distribuire una nuova versione -Costruisci con il nuovo `--version`, etichetta un nuovo rilascio, allega di nuovo i tre asset. I consumer eseguono lo stesso `pack add` e mantengono qualsiasi sottoinsieme avevano scelto; una policy che hanno disattivato rimane disattivata durante l'aggiornamento. +Committa il cambiamento ed esegui `failproofai publish` di nuovo — il nuovo commit è la nuova versione. I consumer eseguono lo stesso `failproofai policies add`. Senza terminale, o con un flag di selezione, mantengono il sottoinsieme che avevano scelto e una policy che hanno disattivato rimane disattivata; a un terminale senza flag, il picker si apre pre-selezionato con i tuoi default e la loro risposta sostituisce la loro selezione. + +Cambiare il **nome** di una policy è un breaking change: una macchina che l'aveva disattivata sta disattivando un nome che non esiste più e il nuovo nome arriva in base a ciò che `defaultEnabled` dice. -Cambiare il **name** di una policy è una breaking change: una macchina che l'aveva disattivata sta disattivando un nome che non esiste più e il nuovo nome arriva con quello che `defaultEnabled` dice. +## Cosa stanno fidarsi i tuoi utenti -## Cosa i tuoi utenti stanno affidandoti +`SHA256SUMS` vive nella stessa release dell'artefatto, quindi prova che i byte sono quelli che hai pubblicato — non chi sei. Chiunque possa scrivere nel repository può scrivere entrambi i file. La protezione dei tuoi utenti è che il digest è fissato quando installano, quindi ciò che hai spedito non può cambiarsi sotto di loro in seguito. -`SHA256SUMS` risiede nello stesso rilascio dell'artefatto, quindi prova che i byte sono quelli che hai pubblicato — non chi sei tu. Chiunque possa scrivere nel repository può scrivere entrambi i file. La protezione dei tuoi utenti è che il digest è fissato quando installano, quindi quello che hai distribuito non può cambiare sotto di loro dopo. +Pubblica da un repository il cui accesso in scrittura controlli e tratta una release di pack come pubblicare un package. -Pubblica da un repository il cui accesso in scrittura controlli e tratta un rilascio di pack come se stessi pubblicando un package. +Il repository deve anche essere **public**. Gli install sono HTTPS anonimo senza credenziale da offrire, quindi un repository privato esistente viene rifiutato prima di qualsiasi cosa sia costruita o caricata, e uno che `publish` crea è public per lo stesso motivo. `--allow-private` scavalca per qualcuno che passa i tre asset in un altro modo e dice chiaramente che nessun `policies add` può raggiungerli. Solo la release conta: gli install leggono `releases/download//` e non toccano mai il tuo albero git. -## Osserva prima di applicare +## Osserva prima di fare rispettare -Un manifest può dichiarare `"effect": "observe"`. Quelle policy vengono eseguite e i loro verdetti sono **registrati e scartati** — nulla è bloccato. È il modo per misurare una nuova regola rispetto al traffico reale prima che possa interrompere il lavoro di chiunque. +Un manifest può dichiarare `"effect": "observe"` — `failproofai publish --effect observe` è quello che lo imposta. Quelle policy vengono eseguite e i loro verdetti sono **registrati e scartati** — niente è bloccato. È il modo di misurare una nuova regola contro il traffico reale prima che possa interrompere il lavoro di qualcuno. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/it/policies/rollback.mdx b/docs/it/policies/rollback.mdx index 3ca35eb6..b6122486 100644 --- a/docs/it/policies/rollback.mdx +++ b/docs/it/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "Ripristino" -description: "Ripristina una distribuzione di policy nota quando un rollout interrompe il lavoro valido dell'agent." +title: "Versioni e rollback" +description: "Ogni pubblicazione è una versione immutabile, quindi un rollout che interrompe il lavoro valido degli agent viene annullato ridistribuendo l'ultima versione corretta." icon: "rotate-ccw" --- -Il ripristino cambia la versione distribuita o rimuove un'assegnazione di policy; non cancella la cronologia delle decisioni che spiega l'incidente. +Una versione di policy pubblicata non cambia mai. La modifica di una policy e una nuova pubblicazione creano una nuova versione; non riscrivono mai quella già sui computer. Questo è ciò che rende il rollback sicuro: l'ultima versione corretta è ancora lì, byte per byte, e il rollback non cancella la cronologia delle decisioni che spiega cosa è andato storto. -## Ripristinare una macchina +## Trovare una versione - 1. Vai a **Admin → enforcement**, espandi la macchina interessata e identifica il suo ultimo set di policy noto come corretto. - 2. Seleziona **edit**, ripristina quelle versioni ed effetti e applica la nuova distribuzione. - 3. Attendi il check-in della macchina, quindi verifica la distribuzione segnalata. - 4. Apri **Observe → policy** e le sessioni interessate per confermare che il lavoro valido non è più bloccato. + Vai a **Admin → policy editor** e apri **library** per confrontare le versioni di una policy o disabilitarne una. + + + ```bash + fp policies list # ogni versione di policy + fp policies show # una versione, con il suo codice sorgente + ``` + + +## Eseguire il rollback di un computer + + + + 1. Vai a **Admin → enforcement**, espandi il computer interessato e identifica il suo ultimo set di policy noto come corretto. + 2. Seleziona **edit**, ripristina quelle versioni e i loro effetti, e applica la nuova distribuzione. + 3. Attendi il check-in del computer, quindi verifica la distribuzione segnalata. + 4. Apri **Observe → policy** e le sessioni interessate per confermare che il lavoro valido non è più bloccato. - Il ripristino della distribuzione cloud è un flusso di lavoro del dashboard. Usa lo stato locale per confermare che la distribuzione corretta ha raggiunto la macchina: + Ogni distribuzione su un computer è una generazione numerata. Elencale, quindi ripristinane una: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` sospende le policy builtin, custom e convention per una sessione locale. Non sospende le policy gestite da Cloud, quindi non è una soluzione alternativa per una distribuzione cloud non corretta. + `rollback` crea una nuova generazione con il vecchio set anziché riavvolgere il contatore, quindi la cronologia rimane append-only e rifiuta una generazione che nomina una policy successivamente disabilitata o eliminata. Richiede una sessione autenticata con `policies:write`. `fp fleet diff ` mostra cosa era previsto rispetto a ciò che il computer ha applicato — viene letto come `behind` finché il computer non fa il prossimo polling — e sulla macchina stessa, `failproofai policies` elenca la distribuzione che sta eseguendo. -## Quando eseguire un ripristino +## Rimuovere una policy da ogni computer + +```bash +fp policies disable # rimuovila da ogni distribuzione che la contiene +fp policies enable # aggiungila di nuovo +``` + +Ciascuno crea una nuova generazione su ogni distribuzione che tocca. Eseguire il rollback di una di quelle generazioni non è il modo per annullare un `disable`, però — `rollback` rifiuta una generazione che nomina una policy disabilitata, e ogni generazione da prima del disable nomina questa. `fp policies enable` è il modo per tornare indietro, e crea a sua volta la sua generazione. + +## Eseguire il rollback di un pack + +Un pack è bloccato alla versione che hai installato, quindi eseguirne il rollback significa installare una versione precedente: + +```bash +failproofai policies show FailproofAI/policies --releases # ogni versione che ha pubblicato e quale è qui +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # fissa quella +``` + +Senza un terminale, o con `--policy`, `--category` o `--all`, l'aggiunta di nuovo mantiene il sottoinsieme che avevi scelto. In un terminale senza questi, apre il picker pre-selezionato con le impostazioni predefinite dell'autore, e ciò che selezioni sostituisce la tua selezione — quindi seleziona di nuovo ciò che avevi. + +## Quando eseguire il rollback - Una policy blocca un'azione di produzione prevista. -- Il volume di corrispondenze è notevolmente superiore a quanto previsto dal rollout osservato. +- Il volume delle corrispondenze è materialmente superiore a quanto previsto dal rollout osservato. - Una policy dipende da campi che un'integrazione non fornisce. - Una nuova versione cambia il comportamento al di fuori della modalità di errore prevista. -Dopo il ripristino, apri le sessioni interessate e identifica la condizione che ha causato il falso positivo. Crea una nuova versione, testa sia i casi non sicuri che quelli legittimi, quindi ripeti la fase di osservazione. +Dopo il rollback, apri le sessioni interessate e trova la condizione dietro il falso positivo. Pubblica una nuova versione, [testa](/it/policies/test) sia il caso non sicuro che quello legittimo, e osservalo di nuovo prima di applicare. - Sospendere l'enforcement può essere appropriato durante un incidente, ma allarga l'esposizione per ogni policy attiva in tale ambito. Preferisci eseguire il rollback della versione specifica della policy quando possibile. + `failproofai config --pause` sospende le policy locali per una sessione e non quelle gestite da Cloud, quindi non è una via d'uscita da una distribuzione Cloud difettosa. Una pausa allarga anche l'esposizione per ogni policy nel suo ambito; preferisci eseguire il rollback della versione che si comporta male. \ No newline at end of file diff --git a/docs/it/policies/test.mdx b/docs/it/policies/test.mdx new file mode 100644 index 00000000..65c191f1 --- /dev/null +++ b/docs/it/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "Testare una policy" +description: "Backtesta una bozza rispetto al traffico che hai già, e dimostra che blocca ciò che deve bloccare e consente ciò che deve permettere, prima che qualsiasi macchina la esegua." +icon: "flask-conical" +--- + +Testa ogni policy in due modi: rispetto al traffico che i tuoi agenti hanno già prodotto, e rispetto a un'azione legittima che deve lasciare passare. Una policy che ha visto solo il caso non sicuro non è stata testata. + +## Backtesta la bozza + + + + L'editor delle policy riesegue una bozza rispetto alle chiamate che la tua flotta ha già effettuato, prima di pubblicarla. + + 1. Apri la bozza in **Admin → policy editor**. L'editor conferma che il parsing avviene come JavaScript. + 2. In **backtest**, scegli gli agenti e l'intervallo di tempo da rieseguire — **ogni agente** e **30d** per impostazione predefinita — e lascia l'ultimo filtro su **everything** a meno che tu non voglia restringerlo. + 3. Seleziona **run backtest**. + + ![Il pannello backtest sotto una bozza che esegue il parsing come JavaScript, con i suoi tre filtri e l'azione run backtest, sopra publish version.](/images/dashboard/policy-backtest.png) + + Il risultato è ciò che la bozza avrebbe fatto a quelle chiamate — incluso quante chiamate **funzionanti** avrebbe interrotto. Questi sono falsi positivi trovati prima che qualsiasi agente li incontri: affina la bozza e rieseguila finché quel numero non è uno che puoi accettare. + + + Il backtesting è una funzione del dashboard. Da un terminale, esegui invece la policy rispetto agli eventi che descrivi qui sotto. + + + +## Eseguila rispetto a un evento che descrivi + +`fp policies test` esegue un file di policy sulla tua macchina rispetto a un evento sintetico e controlla la decisione. Nulla viene pubblicato e nulla raggiunge Cloud: + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +Modella l'evento con `--event`, `--tool`, `--command` e `--file`. Il filtro `match` della policy stessa si applica ancora, quindi una policy che non copre l'evento che hai descritto riporta `skipped` piuttosto che una decisione — di solito un segno che il suo `match` è più restrittivo di quanto intendevi. + +## Eseguila su una macchina + +Successivamente, forzala sul serio sulla tua macchina, rispetto al tuo agente: + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +Il primo comando valida e installa il file; il secondo conferma che è stato caricato, insieme a tutto il resto che sta applicando qui. Chiedi all'agente di fare ciò che la policy blocca e guardalo rifiutare, quindi fai la versione legittima e guardalo passare. Nessun altro è interessato. + +Su una macchina connessa a Cloud, controlla entrambe le decisioni sotto **Observe → policy**: filtra per il nome della policy, quindi apri ogni sessione collegata per confermare l'input dello strumento con cui ha fatto match e il motivo per cui ha restituito. + +## Testa cosa si rompe + +L'installazione rifiuta un file mancante, un errore di sintassi, un import non risolto, un'eccezione di primo livello, o un modulo che scade il timeout durante il caricamento — quindi rieseguila dopo ogni modifica al file o a qualsiasi cosa importi. Al momento dell'esecuzione lo stesso file rotto viene registrato e **skipped** in modo che ogni altra policy continui a funzionare: tratta un avviso di caricamento nei log di produzione come applicazione persa. I file di convenzione si caricano senza il comando install, quindi mantieni un passaggio esplicito `failproofai policies --install --custom ` in CI — è quello che fa fallire la build su una policy rotta. + +Quindi alimentala con ciò che gli agenti effettivamente inviano, non solo l'input che ti aspetti: campi mancanti, nomi di strumenti alternativi come `Write` e `Edit`, percorsi Windows, input malformato. Restituisci un `allow`, `instruct` o `deny` intenzionale su ogni percorso, mantieni la funzione deterministica, e limita qualsiasi chiamata esterna con un timeout breve. + +## Quindi pubblicala e osservala + +Un backtest mostra ciò che la policy avrebbe fatto al traffico che avevi; non può mostrare cosa farà il traffico che non hai ancora visto. Seleziona **publish version** nell'editor (o esegui `fp policies publish`), quindi [distribuiscila](/it/policies/deploy) in modalità **observe** prima — i suoi verdetti vengono registrati e nulla viene bloccato — e forzala una volta che i suoi match separano le azioni non sicure da quelle valide. \ No newline at end of file diff --git a/docs/it/reference/cloud-cli.mdx b/docs/it/reference/cloud-cli.mdx index ddd8b2e1..5495eb12 100644 --- a/docs/it/reference/cloud-cli.mdx +++ b/docs/it/reference/cloud-cli.mdx @@ -4,7 +4,7 @@ description: "Riferimento completo per interrogare e amministrare Failproof AI C icon: "cloud-cog" --- -Usa `fp` per ispezionare la telemetria del Cloud, gestire l'enforcement gestito dal cloud (policy, distribuzioni di flotte, decisioni di guardrail) e gestire audit, findings, issues, alert, chiavi, utenti, query e impostazioni. Usa [`failproofai`](/it/reference/failproof-cli) per hook locali, policy, capture e enrollment di macchine. +Usa `fp` per ispezionare la telemetria Cloud, gestire l'enforcement gestito dal cloud (politiche, distribuzioni di flotta, decisioni di guardrail) e gestire audit, findings, issues, alert, chiavi, utenti, query e impostazioni. Usa [`failproofai`](/it/reference/failproof-cli) per hook locali, politiche, acquisizione e registrazione di macchine. Installa la Cloud CLI rilasciata come strumento isolato: @@ -32,7 +32,7 @@ Le opzioni globali devono venire prima del comando: fp --json sessions --since 24h ``` -Esegui `fp COMMAND --help` o `fp COMMAND SUBCOMMAND --help` per l'aiuto nel terminale. +Esegui `fp COMMAND --help` o `fp COMMAND SUBCOMMAND --help` per l'aiuto in terminale. ## Comandi CLI @@ -40,9 +40,9 @@ Esegui `fp COMMAND --help` o `fp COMMAND SUBCOMMAND --help` per l'aiuto nel term | Comando | Scopo | Opzioni | | --- | --- | --- | -| `fp login` | Accedi con un codice monouso inviato per email e seleziona un'organizzazione. | `--email`, `-e`; `--org`; `--force` | +| `fp login` | Accedi con un codice monouso inviato via email e seleziona un'organizzazione. | `--email`, `-e`; `--org`; `--force` | | `fp logout` | Revoca e rimuovi la sessione utente salvata. | — | -| `fp whoami` | Mostra l'identità attuale, la modalità di autenticazione, l'organizzazione e i permessi. | — | +| `fp whoami` | Mostra l'identità corrente, la modalità di autenticazione, l'organizzazione e i permessi. | — | | `fp version` | Mostra la versione della CLI installata. | — | | `fp help` | Mostra l'aiuto dei comandi di livello superiore. | — | @@ -57,23 +57,23 @@ fp whoami fp events [OPTIONS] ``` -Elenca i singoli eventi dell'agent. Il feed leggero predefinito esclude i payload grezzi; usa `--full` solo per un'indagine limitata. +Elenca i singoli eventi dell'agente. Il feed leggero predefinito esclude i payload grezzi; usa `--full` solo per un'indagine limitata. | Opzione | Descrizione | | --- | --- | -| `--limit`, `-n ` | Massimo totale di righe. Predefinito: `50`. | -| `--since ` | `all`, `15m`, `1h`, `6h`, `24h` o `7d`. | +| `--limit`, `-n ` | Numero massimo totale di righe. Predefinito: `50`. | +| `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, o `7d`. | | `--from ` / `--to ` | Intervallo ISO 8601 UTC; sostituisce `--since`. | -| `--env ` | Filtro per ambiente; ripeti o separa con virgola i valori. | -| `--event-type ` | Filtro per tipo di evento; ripeti o separa con virgola i valori. | -| `--agent-id ` | Filtro per agent; ripeti o separa con virgola i valori. | -| `--session-id ` | Filtro per sessione; ripeti o separa con virgola i valori. | -| `--search ` | Ricerca testo nel payload; ripetibile, corrisponde a qualsiasi termine. | -| `--order asc\|desc` | Ordine temporale. Predefinito: più recenti per primi. | +| `--env ` | Filtro ambiente; ripeti o separato da virgola. | +| `--event-type ` | Filtro tipo evento; ripeti o separato da virgola. | +| `--agent-id ` | Filtro agente; ripeti o separato da virgola. | +| `--session-id ` | Filtro sessione; ripeti o separato da virgola. | +| `--search ` | Ricerca testo payload; ripetibile, con qualsiasi termine corrispondente. | +| `--order asc\|desc` | Ordine temporale. Predefinito: più recente prima. | | `--all` | Paginazione automatica fino a `--limit`. | | `--cursor ` | Riprendi da un cursore opaco. | | `--page-size ` | Righe per richiesta con `--all`; massimo `200`. | -| `--full` | Includi payload grezzi attraverso l'endpoint evento più pesante. | +| `--full` | Includi payload grezzi tramite l'endpoint dell'evento più pesante. | | `--fields ` | Restituisci solo i campi selezionati; richiedere `payload` abilita la modalità completa. | ```bash @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` pagina **fino a `--limit`**, che ha predefinito **50** — quindi `--all` da solo si ferma a 50 righe. Quando si ferma anticipatamente la risposta contiene un `next_cursor` per riprendere da lì; `"next_cursor": null` significa che il feed era veramente esaurito. + `--all` pagina **fino a `--limit`**, che è predefinito a **50** — quindi `--all` da solo si ferma a 50 righe. Quando si ferma prima, la risposta contiene un `next_cursor` per riprendere; `"next_cursor": null` significa che il feed era realmente esaurito. ### Sessioni @@ -93,19 +93,19 @@ fp sessions [OPTIONS] | Opzione | Descrizione | | --- | --- | -| `--limit`, `-n ` | Massimo totale di righe. Predefinito: `50`. | -| `--since ` | `all`, `15m`, `1h`, `6h`, `24h` o `7d`. | +| `--limit`, `-n ` | Numero massimo totale di righe. Predefinito: `50`. | +| `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, o `7d`. | | `--from ` / `--to ` | Intervallo ISO 8601 UTC; sostituisce `--since`. | -| `--env ` | Filtro per ambiente; ripeti o separa con virgola i valori. | -| `--status ` | `done`, `error` o `timeout`; ripeti o separa con virgola i valori. | -| `--agent-id ` | Corrisponde a sessioni che coinvolgono qualsiasi agent selezionato. | -| `--session-id ` | Filtro per sessione; ripeti o separa con virgola i valori. | +| `--env ` | Filtro ambiente; ripeti o separato da virgola. | +| `--status ` | `done`, `error`, o `timeout`; ripeti o separato da virgola. | +| `--agent-id ` | Abbina sessioni che coinvolgono un agente selezionato. | +| `--session-id ` | Filtro sessione; ripeti o separato da virgola. | | `--all` | Paginazione automatica fino a `--limit`. | | `--cursor ` | Riprendi da un cursore opaco. | | `--page-size ` | Righe per richiesta con `--all`; massimo `200`. | | `--fields ` | Restituisci solo i campi selezionati. | -| `--full-ids` | Non abbreviare gli ID di sessione nell'output del terminale. | -| `--agents` | Espandi il roster degli agent per le sessioni multi-agent. | +| `--full-ids` | Non abbreviare gli ID sessione nell'output del terminale. | +| `--agents` | Espandi il roster agente per le sessioni multi-agente. | ### Valutazioni @@ -115,15 +115,15 @@ fp evals [OPTIONS] | Opzione | Descrizione | | --- | --- | -| `--aggregate` | Mostra totali e statistiche per-score invece delle singole valutazioni. | -| `--limit`, `-n ` | Massimo righe elenco. Predefinito: `50`. | +| `--aggregate` | Mostra i totali e le statistiche per punteggio invece delle valutazioni individuali. | +| `--limit`, `-n ` | Numero massimo di righe dell'elenco. Predefinito: `50`. | | `--since`, `--from`, `--to` | Seleziona l'intervallo temporale. | -| `--env`, `--status`, `--agent-id`, `--session-id` | Restringi a un valore esatto per filtro. | -| `--score KEY:MIN..MAX` | Intervallo di score; ripetibile e tutti gli intervalli devono corrispondere. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Limita a un valore esatto per filtro. | +| `--score KEY:MIN..MAX` | Intervallo punteggio; ripetibile e tutti gli intervalli devono corrispondere. | | `--all`, `--cursor`, `--page-size` | Controlla la paginazione dell'elenco. | | `--fields ` | Restituisci solo i campi selezionati. | -| `--full-ids` | Mostra gli ID di sessione completi. | -| `--scores-full` | Mostra ogni score nell'output del terminale. | +| `--full-ids` | Mostra gli ID sessione completi. | +| `--scores-full` | Mostra ogni punteggio nell'output del terminale. | ### Errori @@ -134,27 +134,27 @@ fp errors [OPTIONS] | Opzione | Descrizione | | --- | --- | | `--aggregate` | Riassumi gli errori corrispondenti invece di elencare le righe. | -| `--limit`, `-n ` | Massimo righe elenco. Predefinito: `50`. | +| `--limit`, `-n ` | Numero massimo di righe dell'elenco. Predefinito: `50`. | | `--since`, `--from`, `--to` | Seleziona l'intervallo temporale. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Restringi la popolazione di errori. | -| `--search ` | Ricerca testo nel payload; ripetibile. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Limita la popolazione di errori. | +| `--search ` | Ricerca testo payload; ripetibile. | | `--order asc\|desc` | Ordine temporale. | | `--all`, `--cursor`, `--page-size` | Controlla la paginazione dell'elenco. | | `--fields ` | Restituisci solo i campi selezionati. | -| `--full-ids` | Mostra gli ID di sessione completi. | +| `--full-ids` | Mostra gli ID sessione completi. | -### Utilizzo e valori filtro +### Utilizzo e valori di filtro | Comando | Scopo | | --- | --- | | `fp usage` | Mostra l'utilizzo per la finestra di misurazione corrente. | | `fp list envs` | Elenca gli ambienti osservati. | -| `fp list agents` | Elenca gli ID degli agent osservati. | +| `fp list agents` | Elenca gli ID agente osservati. | | `fp list event_types` | Elenca i tipi di evento. | -| `fp list score_filters` | Elenca le chiavi di score di valutazione. | +| `fp list score_filters` | Elenca le chiavi di punteggio di valutazione. | | `fp list models` | Elenca i nomi dei modelli. | | `fp list hooks` | Elenca i nomi degli hook. | -| `fp list tools` | Elenca i nomi degli strumenti. | +| `fp list tools` | Elenca i nomi dei tool. | | `fp list error_types` | Elenca i tipi di errore. | ### Organizzazioni @@ -162,7 +162,7 @@ fp errors [OPTIONS] | Comando | Scopo | | --- | --- | | `fp orgs list` | Elenca le organizzazioni accessibili. | -| `fp orgs switch [SLUG]` | Salva un'organizzazione attiva; chiede se omessa. | +| `fp orgs switch [SLUG]` | Salva un'organizzazione attiva; chiede quando omesso. | | `fp orgs current` | Mostra l'organizzazione attiva. | | `fp orgs perms` | Mostra i tuoi permessi nell'organizzazione attiva. | @@ -171,13 +171,13 @@ fp errors [OPTIONS] | Comando | Scopo | Opzioni | | --- | --- | --- | | `fp keys list` | Elenca le chiavi dell'organizzazione. | `--show-id`; `--fields ` | -| `fp keys show NAME` | Mostra una chiave e i suoi grant. | — | -| `fp keys create NAME` | Crea una chiave e rivela il suo segreto una volta. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | Sostituisci il set di permessi o regola i grant. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | Ruota il segreto e rivela il rimpiazzo una volta. | `--yes`, `-y` | +| `fp keys show NAME` | Mostra una chiave e i suoi permessi. | — | +| `fp keys create NAME` | Crea una chiave e rivela il suo segreto una sola volta. | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | Sostituisci il set di permessi o aggiusta i permessi. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | Ruota il segreto e rivela la sostituzione una sola volta. | `--yes`, `-y` | | `fp keys disable NAME` | Revoca permanentemente una chiave. | `--yes`, `-y` | -I token di permesso usano `resource:action`, ad esempio `events:add`. Ripeti `--add`, separa con virgola i token o usa azioni puntate come `events:read.add`. +I token di permesso usano `resource:action`, come `events:add`. Ripeti `--add`, separato da virgola i token, o usa azioni puntate come `events:read.add`. ### Query @@ -196,9 +196,9 @@ I token di permesso usano `resource:action`, ad esempio `events:add`. Ripeti `-- | Comando | Scopo | Opzioni | | --- | --- | --- | | `fp users list` | Elenca i membri dell'organizzazione. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | Mostra un membro e i suoi grant. | — | +| `fp users show EMAIL` | Mostra un membro e i suoi permessi. | — | | `fp users create EMAIL` | Aggiungi un membro. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | Cambia i grant di un membro. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users update EMAIL` | Cambia i permessi di un membro. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | | `fp users disable EMAIL` | Disabilita l'accesso. | `--yes`, `-y` | | `fp users enable EMAIL` | Riabilita l'accesso. | `--yes`, `-y` | @@ -206,9 +206,9 @@ I token di permesso usano `resource:action`, ad esempio `events:add`. Ripeti `-- | Comando | Scopo | Opzioni | | --- | --- | --- | -| `fp settings list` | Elenca le impostazioni dell'organizzazione e i valori attuali. | — | +| `fp settings list` | Elenca le impostazioni dell'organizzazione e i valori correnti. | — | | `fp settings schema` | Mostra i valori accettati e le descrizioni. | — | -| `fp settings set KEY` | Cambia un'impostazione esistente. | esattamente uno tra `--value`, `--json-value`, `--file`; facoltativo `--yes`, `-y` | +| `fp settings set KEY` | Cambia un'impostazione esistente. | esattamente uno di `--value`, `--json-value`, `--file`; `--yes`, `-y` opzionale | ### Alert @@ -217,36 +217,36 @@ I token di permesso usano `resource:action`, ad esempio `events:add`. Ripeti `-- | `fp alerts list` | Elenca le regole di alert. | `--show-id` | | `fp alerts show NAME` | Mostra un alert. | — | | `fp alerts create NAME` | Crea un alert. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | Aggiorna o rinomina un alert. | opzioni di creazione più `--name`; `--yes`, `-y` | +| `fp alerts update NAME` | Aggiorna o rinomina un alert. | opzioni create più `--name`; `--yes`, `-y` | | `fp alerts delete NAME` | Elimina un alert. | `--yes`, `-y` | | `fp alerts test NAME` | Invia una notifica di test. | `--channels`; `--yes`, `-y` | -Le severità di alert sono `info`, `warning` e `critical`. I trigger kind sono `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` e `per_event`. Gli intervalli di valutazione devono essere tra 30 e 86.400 secondi. +Le severità degli alert sono `info`, `warning` e `critical`. I tipi di trigger sono `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` e `per_event`. Gli intervalli di valutazione devono essere tra 30 e 86.400 secondi. ### Audit | Comando | Scopo | Opzioni | | --- | --- | --- | | `fp audits list` | Elenca gli audit. | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | Mostra una definizione di audit e il suo stato. | — | -| `fp audits create NAME` | Crea un audit e accoda immediatamente la sua prima esecuzione. | Vedi [opzioni di creazione](#audit-create-options). | -| `fp audits edit NAME` | Sostituisci le impostazioni di audit mantenendo i valori non specificati. | opzioni di definizione creazione; `--name`; `--yes`, `-y` | +| `fp audits show NAME` | Mostra una definizione di audit e lo stato. | — | +| `fp audits create NAME` | Crea un audit e metti subito in coda la sua prima esecuzione. | Vedi [opzioni di creazione](#audit-create-options). | +| `fp audits edit NAME` | Sostituisci le impostazioni di audit mantenendo i valori non specificati. | opzioni di definizione create; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | Elimina un audit, i suoi findings e la cronologia di esecuzione. | `--yes`, `-y` | -| `fp audits run NAME` | Accoda un'esecuzione manuale. | — | +| `fp audits run NAME` | Metti in coda un'esecuzione manuale. | — | | `fp audits runs NAME` | Elenca la cronologia di esecuzione. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | Mostra il briefing e lo stato di fetch dell'URL di riferimento. | — | -| `fp audits context-set NAME` | Cambia il briefing o gli URL di riferimento. | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | Re-fetch degli URL di riferimento. | — | +| `fp audits context-show NAME` | Mostra il testo breve e lo stato del recupero dell'URL di riferimento. | — | +| `fp audits context-set NAME` | Cambia il testo breve o gli URL di riferimento. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-refresh NAME` | Recupera di nuovo gli URL di riferimento. | — | | `fp audits findings` | Elenca i findings. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | Mostra un finding e la sua evidenza. | — | +| `fp audits finding FINDING_ID` | Mostra un finding e le sue evidenze. | — | | `fp audits ack FINDING_ID` | Riconosci un finding. | `--reason` | -| `fp audits mute FINDING_ID` | Sopprimere un pattern ricorrente. | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | Contrassegna un pattern come non azionabile e sopprimilo. | `--reason`; `--yes`, `-y` | +| `fp audits mute FINDING_ID` | Sopprimi un pattern ricorrente. | `--reason`; `--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | Contrassegna un pattern come non attuabile e supprimi. | `--reason`; `--yes`, `-y` | | `fp audits resolve FINDING_ID` | Contrassegna un finding come risolto senza soppressione futura. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | Restituisci un finding alla coda live e cancella la soppressione. | — | -| `fp audits assign FINDING_ID` | Imposta il proprietario del finding. | richiesto `--to ` | +| `fp audits reopen FINDING_ID` | Restituisci un finding alla coda attiva e cancella la soppressione. | — | +| `fp audits assign FINDING_ID` | Imposta il proprietario del finding. | required `--to ` | -#### Opzioni di creazione audit +#### Opzioni di creazione di audit ```bash fp audits create checkout-reliability \ @@ -261,48 +261,48 @@ fp audits create checkout-reliability \ | Opzione | Descrizione | | --- | --- | -| `--file ` | Basa la definizione su JSON o usa `-` per stdin. Flag espliciti sostituiscono i valori del file. | -| `--description ` | Dichiara la domanda di errore o lo scopo. | -| `--enabled` / `--disabled` | Avvia la pianificazione attiva o no. Predefinito: abilitato. | +| `--file ` | Basa la definizione su JSON, o usa `-` per stdin. I flag espliciti sostituiscono i valori del file. | +| `--description ` | Dichiara la domanda o lo scopo del fallimento. | +| `--enabled` / `--disabled` | Avvia la programmazione attiva o inattiva. Predefinito: abilitato. | | `--schedule-interval-secs ` | `3600`–`604800`. Predefinito: `86400`. | -| `--schedule-anchor ` | Fase UTC fissa in formato ISO 8601. Predefinito: prossimo 09:00 UTC. | +| `--schedule-anchor ` | Fase UTC fissa in forma ISO 8601. Predefinito: prossime 09:00 UTC. | | `--window-mode since_last\|fixed` | Continua dopo l'ultima finestra completamente analizzata o ispeziona ripetutamente una finestra mobile. Predefinito: `since_last`. | | `--lookback-window-secs ` | `3600`–`7776000`. Predefinito: `604800`. | | `--scope ''` | Filtra per `environments`, `agent_ids` o altri campi di scope supportati. | -| `--ignore-error-type ` | Escludi tipi di errore; ripeti o separa con virgola. | +| `--ignore-error-type ` | Escludi tipi di errore; ripeti o separato da virgola. | | `--llm` / `--no-llm` | Abilita o disabilita l'analisi agentiva. Predefinito: abilitato. | -| `--top-k ` | Conserva `1`–`500` findings. Predefinito: `50`. | -| `--sensitivity low\|medium\|high` | Imposta la sensibilità di reporting. Predefinito: `medium`. | -| `--channels ''` | Array di canali di notifica. | -| `--text ` | Briefing inline, massimo 8.192 caratteri. | -| `--text-file ` | Leggi il briefing da un file; mutualmente esclusivo con `--text`. | +| `--top-k ` | Mantieni `1`–`500` findings. Predefinito: `50`. | +| `--sensitivity low\|medium\|high` | Imposta la sensibilità del report. Predefinito: `medium`. | +| `--channels ''` | Array del canale di notifica. | +| `--text ` | Testo breve inline, massimo 8.192 caratteri. | +| `--text-file ` | Leggi il testo breve da un file; mutuamente esclusivo con `--text`. | | `--url ` | Aggiungi un riferimento HTTPS pubblico; ripeti fino a cinque volte. | Includi il contesto durante la creazione quando la prima esecuzione ne ha bisogno. La creazione impegna la definizione e il contesto insieme prima che l'esecuzione in coda inizi. - `fp audits run` è asincrona. Esegui il polling di `fp audits runs NAME` fino a quando l'esecuzione più recente riesce o non fallisce prima di leggere i suoi findings. + `fp audits run` è asincrono. Polling di `fp audits runs NAME` finché l'ultima esecuzione non riesce o fallisce prima di leggere i suoi findings. -### Issue +### Issues | Comando | Scopo | Opzioni | | --- | --- | --- | -| `fp issues list` | Elenca le issue. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | Conta gli stati di issue aperti o selezionati. | `--state` | +| `fp issues list` | Elenca gli issue. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | Conta gli issue aperti o selezionati. | `--state` | | `fp issues show INCIDENT_ID` | Mostra i dettagli dell'issue, i commenti, gli abbonati e l'attività. | — | -| `fp issues open` | Apri un'issue manuale o collegata a un alert. | richiesto `--summary`; facoltativo `--title`, `--alert-id`, `--severity` | -| `fp issues ack INCIDENT_ID` | Riconosci un'issue. | — | -| `fp issues assign INCIDENT_ID` | Sostituisci gli assegnatari; ometti l'opzione per cancellarli. | ripetibile `--assignee` | -| `fp issues resolve INCIDENT_ID` | Risolvi un'issue. | `--yes`, `-y` | +| `fp issues open` | Apri un issue manuale o collegato a un alert. | required `--summary`; optional `--title`, `--alert-id`, `--severity` | +| `fp issues ack INCIDENT_ID` | Riconosci un issue. | — | +| `fp issues assign INCIDENT_ID` | Sostituisci gli assegnati; ometti l'opzione per cancellarli. | repeatable `--assignee` | +| `fp issues resolve INCIDENT_ID` | Risolvi un issue. | `--yes`, `-y` | | `fp issues comment-list INCIDENT_ID` | Elenca i commenti. | — | -| `fp issues comment-add INCIDENT_ID` | Aggiungi un commento. | esattamente uno tra `--body`, `--file` | +| `fp issues comment-add INCIDENT_ID` | Aggiungi un commento. | esattamente uno di `--body`, `--file` | | `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Elimina un commento. | `--yes`, `-y` | | `fp issues subscribers INCIDENT_ID` | Elenca gli abbonati. | — | | `fp issues subscribe INCIDENT_ID` | Iscriviti tu stesso o un altro operatore. | `--email` | | `fp issues unsubscribe INCIDENT_ID` | Rimuovi un abbonamento. | `--email` | -Gli stati validi di issue sono `firing`, `acknowledged` e `resolved`. Le severità di issue autonome sono `info`, `warning` e `critical`. +Gli stati di issue validi sono `firing`, `acknowledged` e `resolved`. Le severità degli issue autonomi sono `info`, `warning` e `critical`. ### Assistente Cloud @@ -311,55 +311,55 @@ Gli stati validi di issue sono `firing`, `acknowledged` e `resolved`. Le severit | `fp agent health` | Controlla la disponibilità e la configurazione dell'assistente. | — | | `fp agent models` | Elenca i modelli di assistente disponibili. | — | | `fp agent chats` | Elenca le chat salvate. | — | -| `fp agent ask [MESSAGE]` | Avvia o continua una chat; legge stdin quando il messaggio è omesso. | `--chat`; `--model`; `--page-context` | +| `fp agent ask [MESSAGE]` | Avvia o continua una chat; leggi stdin quando il messaggio è omesso. | `--chat`; `--model`; `--page-context` | | `fp agent show CHAT_ID` | Mostra una conversazione salvata. | — | -| `fp agent rename CHAT_ID` | Rinomina una conversazione. | richiesto `--title` | +| `fp agent rename CHAT_ID` | Rinomina una conversazione. | required `--title` | | `fp agent delete CHAT_ID` | Elimina una conversazione. | `--yes`, `-y` | -### Policy +### Politiche -Versioni di policy gestite dal cloud. **Solo sessione** — ogni comando qui esce con `2` con una chiave API, prima di qualsiasi richiesta, perché questi sono percorsi di scrittura root-only deliberatamente assenti da `/v1`. +Versioni di politica gestite dal cloud. **Solo sessione** — ogni comando qui esce con `2` sotto una chiave API, prima di qualsiasi richiesta, perché questi sono percorsi di scrittura solo root deliberatamente assenti da `/v1`. | Comando | Scopo | Opzioni | | --- | --- | --- | -| `fp policies list` | Elenca le versioni di policy. | `--json` | -| `fp policies show POLICY_ID` | Mostra una policy con il suo sorgente. | — | +| `fp policies list` | Elenca le versioni di politica. | `--json` | +| `fp policies show POLICY_ID` | Mostra una politica, con il suo sorgente. | — | | `fp policies publish NAME PATH` | Crea una versione da un `.mjs` locale. | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | Aggiungila a ogni deployment da cui è stata rimossa, creando una nuova generazione su ognuna. | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | Rimuovila da ogni deployment che la contiene, creando una nuova generazione su ognuna. | `--yes`, `-y` | -| `fp policies delete POLICY_ID` | Elimina una versione di policy. | `--yes`, `-y` | -| `fp policies test PATH` | Esegui una policy localmente su un contesto sintetico. Applica il filtro `match` di ogni policy, quindi una che non copre l'evento/strumento specificato è riportata come `skipped` piuttosto che eseguita. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | Elabora una policy con l'assistente. Necessita `policies:write`. | — | +| `fp policies enable POLICY_ID` | Aggiungila di nuovo a ogni distribuzione da cui è stata rimossa, creando una nuova generazione su ciascuna. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | Rimuovila da ogni distribuzione che la contiene, creando una nuova generazione su ciascuna. | `--yes`, `-y` | +| `fp policies delete POLICY_ID` | Elimina una versione di politica. | `--yes`, `-y` | +| `fp policies test PATH` | Esegui una politica localmente contro un contesto sintetico. Applica il filtro `match` di ogni politica, quindi una che non copre l'evento/tool dato è segnalata come `skipped` piuttosto che eseguita. | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | Bozza una politica con l'assistente. Richiede `policies:write`. | — | -### Fleet +### Flotta -Quali macchine eseguono quali policy. **Solo sessione**, stesso motivo di cui sopra. +Quali macchine eseguono quali politiche. **Solo sessione**, per lo stesso motivo di cui sopra. | Comando | Scopo | Opzioni | | --- | --- | --- | -| `fp fleet list` | Elenca le macchine iscritte e la loro generazione di deployment. | — | -| `fp fleet show MACHINE_ID` | Il set di policy che una macchina attualmente esegue. | — | -| `fp fleet deploy MACHINE_ID` | **Sostituisce l'intero set di policy della macchina.** Stampa il piano e chiede solo su un terminale interattivo senza `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | Confronta una macchina con un altro deployment. | — | -| `fp fleet history MACHINE_ID` | Deployment precedenti per una macchina. | — | -| `fp fleet rollback MACHINE_ID` | Ripristina un deployment precedente. | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | Assegna a una macchina un nome leggibile. | richiesto `--name` | +| `fp fleet list` | Elenca le macchine registrate e la loro generazione di distribuzione. | — | +| `fp fleet show MACHINE_ID` | Il set di politiche che una macchina esegue attualmente. | — | +| `fp fleet deploy MACHINE_ID` | **Sostituisce l'intero set di politiche della macchina.** Stampa il piano e chiede solo su un terminale interattivo senza `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | Confronta una macchina con un'altra distribuzione. | — | +| `fp fleet history MACHINE_ID` | Distribuzioni passate per una macchina. | — | +| `fp fleet rollback MACHINE_ID GENERATION` | Ripristina il set di politiche di una generazione passata, come una nuova generazione. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | Assegna un nome leggibile a una macchina. | required `--name` | ### Guardrail -Cosa l'enforcement ha effettivamente fatto. **Solo sessione**, stesso motivo di cui sopra. +Cosa ha fatto realmente l'enforcement. **Solo sessione**, per lo stesso motivo di cui sopra. | Comando | Scopo | Opzioni | | --- | --- | --- | -| `fp guardrails summary` | Copertura, totali bloccati/valutati, una sparkline di deny e la tabella per-policy. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | Decisioni raggruppate sulla finestra, sommate su ogni fonte di policy. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | Copertura, totali bloccati/valutati, una scintilla di negazione e la tabella per politica. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Decisioni raggruppate sulla finestra, sommate su ogni fonte di politica. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | ## Flag globali | Flag | Descrizione | | --- | --- | | `--json` | Emetti JSON leggibile da macchina. | -| `--base-url ` | Usa un dashboard auto-hosted o di sviluppo. | +| `--base-url ` | Usa un dashboard self-hosted o di sviluppo. | | `--org ` | Seleziona un'organizzazione per questa invocazione. | | `--token ` | Sostituisci il token di sessione utente salvato. | | `--api-key ` | Autentica l'automazione con una chiave API; mai salvata. | @@ -370,9 +370,9 @@ Cosa l'enforcement ha effettivamente fatto. **Solo sessione**, stesso motivo di | `--version` | Stampa la versione e esci. | | `--help`, `-h` | Mostra l'aiuto. | -`--api-key` è destinato all'automazione. L'accesso, il cambio di organizzazione e i comandi dell'assistente richiedono una sessione utente. +`--api-key` è inteso per l'automazione. L'accesso, il cambio di organizzazione e i comandi dell'assistente richiedono una sessione utente. -## Variabili d'ambiente +## Variabili di ambiente | Variabile | Equivalente o scopo | | --- | --- | @@ -383,13 +383,13 @@ Cosa l'enforcement ha effettivamente fatto. **Solo sessione**, stesso motivo di | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | | `FP_HOME` | Riposiziona la directory di configurazione della CLI (predefinito `~/.failproofai/fpcli`). | -| `FP_ANALYTICS_DISABLED` o `DO_NOT_TRACK` | Disabilita l'analitiche anonime della CLI. | +| `FP_ANALYTICS_DISABLED` o `DO_NOT_TRACK` | Disabilita l'analisi anonima della CLI. | | `NO_COLOR` | Disabilita l'output colorato. | -I flag espliciti sostituiscono le variabili d'ambiente, che a loro volta sostituiscono la configurazione salvata. In modalità chiave API, seleziona il tenant esplicitamente con `--org` o `FP_ORG`. +I flag espliciti sostituiscono le variabili di ambiente, che sostituiscono la configurazione salvata. In modalità chiave API, seleziona il tenant esplicitamente con `--org` o `FP_ORG`. - I nomi `AGENTEYE_*` di questi **non sono letti da `fp`** e non lo sono mai stati — la CLI dichiara `FP_*` (`fp_cli/app.py`), e una variabile sconosciuta non è un errore. Impostare `AGENTEYE_DASHBOARD_URL` non reindirizz la CLI; viene ignorato e il comando è eseguito silenziosamente contro il dashboard salvato. + Gli spelling `AGENTEYE_*` di questi **non sono letti da `fp`** e non lo sono mai stati — la CLI dichiara `FP_*` (`fp_cli/app.py`), e una variabile sconosciuta non è un errore. Impostare `AGENTEYE_DASHBOARD_URL` non reindirizza la CLI; viene ignorato e il comando silenziosamente viene eseguito contro il dashboard salvato invece. `AGENTEYE_HOME` e `AGENTEYE_ENVIRONMENT` esistono ancora, ma appartengono al **collector e all'SDK di telemetria**, non a questa CLI. diff --git a/docs/it/reference/custom-agents.mdx b/docs/it/reference/custom-agents.mdx index 75259e19..5ef9d637 100644 --- a/docs/it/reference/custom-agents.mdx +++ b/docs/it/reference/custom-agents.mdx @@ -4,43 +4,49 @@ description: "Configurazione, catalogo degli eventi, regole di correlazione e co icon: "python" --- -Cosa fa ogni impostazione, metodo e campo. Se stai strumentando per la prima volta, inizia con la guida — questa pagina serve per cercare le cose. +Cosa fanno ogni impostazione, metodo e campo. Se stai strumentando per la prima volta, inizia con la guida — questa pagina è per cercare le cose. - - Installa, strumenta, i metodi degli eventi, un esempio completo e problemi comuni. + + Installazione, strumentazione, i metodi degli eventi, un esempio pratico e problemi comuni. - - LangChain, CrewAI, LlamaIndex e Pydantic AI si strumentano automaticamente con una sola chiamata. + + LangChain, CrewAI, LlamaIndex e Pydantic AI si strumentano da soli con una sola chiamata. -Python 3.10 o più recente. Nessuna dipendenza runtime. +Python 3.10 o più recente. Nessuna dipendenza di runtime. -## Installa +## Installazione ```bash pip install failproofai-sdk ``` -Il pacchetto è installato come `failproofai-sdk` e importato in Python come `failproofai_sdk`. Gli extra dei framework come `failproofai-sdk[langgraph]` installano il framework stesso; gli adattatori vengono sempre forniti nella wheel di base. +Il pacchetto è installato come `failproofai-sdk` e importato in Python come `failproofai_sdk`. I framework extra come `failproofai-sdk[langgraph]` installano il framework stesso; gli adattatori sono sempre inclusi nella wheel di base. ## Connetti il daemon Failproof - 1. Vai su **Admin → Keys** e crea una chiave con `events:add`. + 1. Vai a **Admin → Keys** e crea una chiave con `events:add`. 2. [Connetti il daemon Failproof al Cloud](/it/start/setup#connect-a-machine-to-cloud) sulla macchina dell'agente. 3. Esegui una sessione strumentata, quindi trova il suo ID esatto in **Observe → Events**. - 4. Vai su **Observe → Sessions**, seleziona lo stesso ambiente e apri la traccia ricostruita. + 4. Vai a **Observe → Sessions**, seleziona lo stesso ambiente e apri la traccia ricostruita. - ![Una sessione di agente Python personalizzato ricostruita come grafo di esecuzione e traccia di eventi ordinata.](/images/dashboard/session-detail.png) + ![Una sessione di agente Python personalizzato ricostruita come grafico di esecuzione e traccia di eventi ordinata.](/images/dashboard/session-detail.png) + Leggi la chiave `events:add` nella shell. `read -s` la riceve con un prompt che non echeggia, quindi non appare mai in un comando o nella cronologia della shell: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Quindi configura la macchina e verifica che si sia connessa: + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -60,30 +66,30 @@ failproofai_sdk.configure( | Argomento | Cosa fa | | --- | --- | -| `environment` | L'etichetta su ogni evento — `production`, `staging`, `prod-eu`. Il valore predefinito è `dev`. | -| `flush_interval` | Ogni quanto il thread in background scrive su disco, in secondi. Il valore predefinito è `0.5`. | -| `base_dir` | Dove scrivere. Il valore predefinito è lo spool del daemon, che è quello che vuoi a meno che tu non sappia diversamente. | +| `environment` | L'etichetta su ogni evento — `production`, `staging`, `prod-eu`. Defaults a `dev`. | +| `flush_interval` | Quanto spesso il thread di background scrive su disco, in secondi. Defaults a `0.5`. | +| `base_dir` | Dove scrivere. Defaults allo spool del daemon, che è quello che vuoi a meno che tu non sappia diversamente. | -Impostare tramite variabile di ambiente: +Imposta tramite variabile d'ambiente invece: | Variabile | Cosa fa | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | Imposta `environment` senza modificare il codice, per quando l'etichetta appartiene al deployment piuttosto che all'app. Un argomento `configure()` ha la precedenza. | -| `FAILPROOFAI_HOME` | Sposta la root di Failproof AI che contiene lo spool. | -| `FAILPROOFAI_SDK_STRICT` | `1` fa sollevare gli errori di strumentazione invece di registrarli. | +| `AGENTEYE_ENVIRONMENT` | Imposta `environment` senza un cambio di codice, per quando l'etichetta appartiene al deployment piuttosto che all'app. Un argomento `configure()` prevale su di essa. | +| `FAILPROOFAI_HOME` | Sposta la radice Failproof AI che contiene lo spool. | +| `FAILPROOFAI_SDK_STRICT` | `1` fa sollevare gli errori di strumentazione invece di essere registrati. | | `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` fa sollevare un problema di compatibilità del framework invece di avvertire e continuare. | - **Niente virgole in `environment`.** L'ingest divide quel campo su virgole per creare i suoi filtri e salta tutti gli eventi la cui etichetta ne contiene una — quindi un'intera esecuzione scompare silenziosamente. Scrivi `prod-eu`, non `prod,eu`. + **Nessuna virgola in `environment`.** L'ingest divide quel campo su virgole per costruire i suoi filtri e salta qualsiasi evento la cui etichetta ne contiene una — quindi un'intera esecuzione scompare silenziosamente. Scrivi `prod-eu`, non `prod,eu`. - `configure(environment="prod,eu")` genera un'eccezione per farti scoprirlo immediatamente. `AGENTEYE_ENVIRONMENT` non può generare un'eccezione — nessuno ti sta chiamando — quindi avverte una volta e ricade a `dev`. + `configure(environment="prod,eu")` solleva un errore in modo da scoprirlo immediatamente. `AGENTEYE_ENVIRONMENT` non può sollevare — nessuno ti sta chiamando — quindi avverte una volta e ritorna a `dev`. -Gli eventi sono accodati in memoria e scritti in background ogni `flush_interval` secondi, con uno scarico finale all'uscita dell'interprete. Un processo ucciso immediatamente perde qualunque cosa non fosse stata ancora scritta. +Gli eventi sono accodati in memoria e scritti in background ogni `flush_interval` secondi, con un flush finale all'uscita dell'interprete. Un processo ucciso bruscamente perde tutto ciò che non era stato ancora scritto. ## Identità -Ogni evento appartiene a una sessione e un agente. **Gli scope riempiono entrambi**, quindi raramente li passi: +Ogni evento appartiene a una sessione e un agente. **Gli scope compilano entrambi**, quindi raramente li passi: ```python with failproofai_sdk.session(): @@ -91,15 +97,15 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Passare `session_id` o `agent_id` esplicitamente funziona ancora e ha la precedenza. Senza né un vincolo né un passaggio, la chiamata genera `TypeError` piuttosto che emettere un evento che il Cloud scarterebbero silenziosamente. +Passare `session_id` o `agent_id` esplicitamente funziona ancora e prevale. Senza né binding né passaggio, la chiamata solleva `TypeError` anziché emettere un evento che Cloud scapterebbe silenziosamente. - L'identità si basa su variabili di contesto. Segue automaticamente i compiti `asyncio`, ma **non** i nuovi thread — avvolgi un worker in `failproofai_sdk.propagate()` o i suoi eventi rimangono scollati. + L'identità si basa su variabili di contesto. Segue automaticamente i task `asyncio`, ma **non** i nuovi thread — avvolgi un worker in `failproofai_sdk.propagate()` o i suoi eventi finiscono scollati. ## Catalogo degli eventi -Quindici metodi. La maggior parte arriva in **coppie** — chiami l'opener, poi il closer, e l'SDK misura il divario. +Quindici metodi. La maggior parte vengono in **coppie** — chiami l'apertura, quindi la chiusura, e l'SDK misura l'intervallo. | | Apre | Chiude | | --- | --- | --- | @@ -107,14 +113,14 @@ Quindici metodi. La maggior parte arriva in **coppie** — chiami l'opener, poi | | `agent_pause` | `agent_resume` | | **Modelli** | `model_request` | `model_response` | | **Strumenti** | `tool_use` | `tool_result` | -| **Hook** | `hook_triggered` | `hook_completed` | +| **Hooks** | `hook_triggered` | `hook_completed` | | **Umani** | `human_wait` | `human_input` | Tre sono indipendenti: `error`, `human_pause`, `human_interrupt`. -Ogni metodo accetta anche `session_id` e `agent_id`, che gli scope riempiono per te. Qualunque cosa rimanga come `None` viene scartata piuttosto che inviata come JSON `null`, e ogni metodo restituisce `None`. +Ogni metodo accetta anche `session_id` e `agent_id`, che gli scope compilano per te. Qualsiasi cosa lasciata come `None` viene scartata anziché essere inviata come JSON `null`, e ogni metodo restituisce `None`. | Metodo | Richiesto | Opzionale | | --- | --- | --- | @@ -137,14 +143,14 @@ Ogni metodo accetta anche `session_id` e `agent_id`, che gli scope riempiono per - Per contrassegnare un'esecuzione come non riuscita, `outcome` deve essere uno di `failed`, `error`, `timeout` o `rejected`. Qualunque altro valore — incluso il quasi-colpo `"failure"` — conta come un successo. + Per contrassegnare un'esecuzione come non riuscita, `outcome` deve essere uno di `failed`, `error`, `timeout` o `rejected`. Qualsiasi altro valore — incluso il quasi-match `"failure"` — conta come un successo. -## Accoppiamento e durata +## Associazione e durata -**Una regola: dai all'evento di chiusura lo stesso id del suo opener.** Questo è ciò che li accoppia e che permette all'SDK di misurare il divario. +**Una regola: dai all'evento di chiusura lo stesso id del suo apertura.** È questo che li associa e che consente all'SDK di misurare l'intervallo. -| Coppia | Abbinato su | +| Coppia | Associato su | | --- | --- | | `tool_use` → `tool_result` | `tool_call_id` | | `hook_triggered` → `hook_completed` | `hook_id` | @@ -152,46 +158,46 @@ Ogni metodo accetta anche `session_id` e `agent_id`, che gli scope riempiono per | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**Non passare `duration_ms` tu stesso.** L'SDK lo misura e passarlo genera `ValueError`. +**Non passare `duration_ms` tu stesso.** L'SDK lo misura e passarlo solleva `ValueError`. -L'unica eccezione è `model_response`, dove solo tu conosci la vera latenza del provider. Passa un numero intero di millisecondi — un float genera un'eccezione, perché la colonna è un intero a 32 bit e altrimenti sarebbe vuota. +L'unica eccezione è `model_response`, dove solo tu conosci la vera latenza del provider. Passa un numero intero di millisecondi — un float solleva un errore perché la colonna è un intero a 32 bit e altrimenti atterrerebbe vuota. -- **Gli Id devono essere univoci solo per tipo, per sessione.** Una chiamata a uno strumento e un hook possono condividerne uno; due sessioni in esecuzione contemporaneamente possono riutilizzare gli stessi id senza collisioni. -- **Non sono scoped a un agente.** Una coppia aperta in un agente e chiusa in un altro corrisponde comunque — che è il caso normale nel codice multi-agente. -- **`request_id` è opzionale ma consigliato.** Senza di esso, gli eventi del modello si accoppiano nell'ordine di arrivo, quindi due chiamate concorrenti nello stesso agente possono accoppiarsi male. -- **Una coppia divisa tra processi** corrisponde comunque nel Cloud, ma l'SDK non può misurarla — nessuno in nessuno dei due processi ha visto entrambe le metà. -- **Al massimo 10.000 opener attendono un closer contemporaneamente.** Oltre questo il più vecchio viene scartato, quindi una perdita non può crescere senza limiti. +- **Gli id devono essere univoci solo per tipo, per sessione.** Una chiamata di strumento e un hook possono condividerne uno; due sessioni in esecuzione contemporaneamente possono riutilizzare gli stessi id senza collisioni. +- **Non sono scoped a un agente.** Una coppia aperta sotto un agente e chiusa sotto un altro corrisponde ancora — che è il caso normale nel codice multi-agente. +- **`request_id` è opzionale ma consigliato.** Senza di esso, gli eventi del modello si associano nell'ordine in cui arrivano, quindi due chiamate simultanee nello stesso agente possono associarsi male. +- **Una coppia divisa tra processi** corrisponde ancora nel Cloud, ma l'SDK non può misurarla — nulla in entrambi i processi ha visto entrambe le metà. +- **Al massimo 10.000 aperture attendono una chiusura contemporaneamente.** Oltre questo la più vecchia viene scartata, quindi una perdita non può crescere senza limiti. -## I tuoi campi propri +## I tuoi campi personalizzati -Qualunque extra keyword che passi viene memorizzato con l'evento: +Qualsiasi extra keyword che passi viene archiviato con l'evento: ```python failproofai_sdk.event.tool_use( tool_name="search", tool_call_id="c1", - fw_tenant="acme", fw_region="eu-west-1", # tuoi + fw_tenant="acme", fw_region="eu-west-1", # i tuoi ) ``` -Preferisci tipi JSON se vuoi interrogarli in seguito. Qualunque altro — un UUID, un datetime, un `Decimal`, un set, bytes, un oggetto modello — viene memorizzato come stringa. +Preferisci i tipi JSON se vuoi interrogarli in seguito. Qualsiasi altra cosa — un UUID, un datetime, un `Decimal`, un set, bytes, un oggetto modello — viene archiviata come stringa. - **Prefissa i tuoi nomi di campo.** Gli extra vengono applicati per ultimi, quindi un campo chiamato `model`, `tool_name` o `outcome` sovrascrive silenziosamente quello vero. Gli adattatori del framework usano `fw_`; fai lo stesso e niente può collidere. + **Prefissa i nomi dei tuoi campi.** Gli extra vengono applicati per ultimi, quindi un campo chiamato `model`, `tool_name` o `outcome` sovrascrive silenziosamente quello reale. Gli adattatori del framework usano `fw_`; fai lo stesso e nulla può collidere. - È anche per questo che un campo opzionale con errore di ortografia non genera mai un errore — diventa semplicemente un nuovo campo personalizzato. Se un campo standard manca nel Cloud, controlla prima l'ortografia. + Questo è anche il motivo per cui un campo opzionale con errori di ortografia non solleva mai — diventa solo un nuovo campo personalizzato. Se un campo standard manca nel Cloud, controlla prima l'ortografia. -Questi cinque nomi sono riservati e rifiutati immediatamente: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. +Questi cinque nomi sono riservati e rifiutati completamente: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. -## Consegna e verifica +## Consegnare e verificare - In **Observe → Events**, verifica che `agent_start` esista per primo e `agent_end` esista per ultimo. Quindi apri **Observe → Sessions** e conferma che gli eventi modello, strumento, umano, hook ed errore appaiano nell'ordine previsto. Usa l'ID della sessione come chiave di risoluzione dei problemi primaria. + In **Observe → Events**, verifica che `agent_start` esista prima e `agent_end` esista per ultimo. Quindi apri **Observe → Sessions** e conferma che gli eventi di modello, strumento, umano, hook e errore appaiano nell'ordine previsto. Usa l'ID sessione come chiave di risoluzione dei problemi principale. ```bash @@ -203,14 +209,14 @@ Questi cinque nomi sono riservati e rifiutati immediatamente: `timestamp`, `sess -Se il Cloud è vuoto, ispeziona `$FAILPROOFAI_HOME/custom-agents/events`, altrimenti `~/.failproofai/custom-agents/events`. I file JSONL provano l'emissione dell'SDK; uno spool in crescita punta a configurazione del daemon o consegna, mentre uno spool vuoto punta a strumentazione o durata del processo. +Se Cloud è vuoto, ispeziona `$FAILPROOFAI_HOME/custom-agents/events`, altrimenti `~/.failproofai/custom-agents/events`. I file JSONL provano l'emissione dell'SDK; uno spool crescente indica un daemon o una consegna configurazione, mentre uno spool vuoto indica un'instrumentazione o una durata del processo. - Ispeziona lo spool solo quando il daemon è arrestato. Mentre è in esecuzione, raccoglie e cancella ogni batch in millisecondi, quindi un elenco di directory gara il collettore e mostra molti meno eventi di quelli emessi. + Ispeziona lo spool solo quando il daemon è arrestato. Mentre è in esecuzione, raccoglie ed elimina ogni batch entro millisecondi, quindi un elenco di directory corre con il collezionista e mostra molti meno eventi di quelli che sono stati emessi. ## Prevenire errori in un runtime personalizzato -Usa i risultati dell'audit e le tracce collegate per definire l'azione non sicura, la prova richiesta e la risposta prevista. Un'integrazione di enforcement personalizzata deve esporre l'azione prima dell'esecuzione, passare il suo input strutturato al motore delle policy e applicare la decisione allow, instruct o deny risultante. +Usa i risultati dell'audit e le tracce collegate per definire l'azione non sicura, le prove richieste e la risposta prevista. Un'integrazione di enforcement personalizzata deve esporre l'azione prima dell'esecuzione, passare il suo input strutturato al motore delle politiche e applicare la decisione risultante di allow, instruct o deny. -[Contatta Failproof AI](mailto:support@befailproof.ai) e ti aiuteremo a mappare i confini di modello, strumento e ciclo di vita del tuo runtime agli hook delle policy, quindi convalidare l'integrazione con te. \ No newline at end of file +[Contatta Failproof AI](mailto:support@befailproof.ai) e ti aiuteremo a mappare i confini del modello, dello strumento e del ciclo di vita del tuo runtime agli hook delle politiche, quindi convalidare l'integrazione con te. \ No newline at end of file diff --git a/docs/it/reference/evaluator-sdk.mdx b/docs/it/reference/evaluator-sdk.mdx index 0fc26069..7f678ff9 100644 --- a/docs/it/reference/evaluator-sdk.mdx +++ b/docs/it/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "Costruisci un servizio che valuta le sessioni di Failproof AI in modo sincrono o asincrono." +description: "Esegui il tuo worker di valutazione, per giudici LLM e tutto ciò che Python ospitato non può fare." icon: "gauge" --- -Un evaluator riceve una sessione di agent completata e restituisce i segnali di qualità che desideri: punteggi numerici, una spiegazione per ogni punteggio e un riepilogo opzionale. Failproof AI archivia questi risultati accanto alla traccia e li rappresenta graficamente tra gli agent e gli ambienti. +L'Evaluator SDK esegue valutazioni sulla tua infrastruttura. Il tuo worker registra le sue valutazioni con Failproof AI, rivendica le sessioni al loro completamento, le valuta e invia i risultati, tutto tramite HTTPS in uscita: niente si connette ad esso. Usalo per ciò che [Python ospitato](/it/evaluations/write) non può fare — giudici LLM, chiamate di modello, pacchetti, segreti e accesso di rete. I suoi risultati appaiono accanto a quelli ospitati nella [pagina valutazioni](/it/sessions/evaluations), etichettati **customer**. -## Configurare un evaluator +È fornito in `failproofai-sdk`, sotto `failproofai_sdk.evaluator`; importare l'SDK di tracciamento non lo carica. - - - Installa l'SDK e il server utilizzato per eseguirlo. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - Crea `evaluator.py`. Questo esempio verifica se una sessione contiene chiamate di strumenti non riuscite. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - Imposta un token condiviso, avvia l'evaluator e conferma che l'endpoint di integrità risponde. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - In un altro terminale: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## Connettere l'evaluator a Failproof AI +```bash +pip install failproofai-sdk +``` -1. Distribuisci l'evaluator a un URL HTTPS raggiungibile da Failproof AI Cloud. -2. Configura `EVALUATOR_ENDPOINT` con tale URL e imposta `EVALUATOR_TOKEN` sullo stesso token utilizzato dall'evaluator. Per il Cloud gestito, contatta [support@befailproof.ai](mailto:support@befailproof.ai) per configurare la connessione. -3. Esegui una valutazione e conferma che i punteggi vengono visualizzati in Failproof AI. +## Scrivi valutazioni - - - Apri una sessione completata in **Observe → Sessions** e seleziona **Run evaluation** se non è stata valutata automaticamente. Esamina lo stato, i punteggi, il ragionamento e il riepilogo nel pannello **Evaluation** della sessione. +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - Usa **Observe → Evaluations** per confrontare i punteggi tra gli agent o gli ambienti. Usa **Observe → Metrics** per latenza, costo, token e altre misurazioni numeriche. - Inizia con una sessione per confermare che l'evaluator ha restituito le chiavi di punteggio previste e un ragionamento utile per quella specifica esecuzione. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![Una vista dei dettagli della sessione che mostra i punteggi di valutazione e il ragionamento accanto alla traccia.](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` registra una valutazione. La chiave è ciò su cui viene tracciato il suo risultato; cambia la versione ogni volta che la logica cambia, e ogni risultato mantiene la versione che l'ha prodotto. Un worker contiene fino a 100 valutazioni. +- `result_kind` è `"score"` a meno che tu non dica diversamente. Per una valutazione `"metric"` o `"assertion"`, assegna a una voce `metrics` o `assertions` il nome della chiave: quella voce è il suo risultato. +- `when` decide se una sessione si applica. Restituisci `ConditionResult(False, "")` per saltarne una, e il motivo viene registrato. +- Una valutazione può essere una funzione semplice o `async`, e `timeout_seconds` la delimita. +- Le chiavi di payload — `tool_name`, `response` e `content` sopra — sono ciò che i tuoi agenti inviano, quindi leggile da una sessione reale. - Una volta che i risultati individuali appaiono corretti, utilizza il dashboard di valutazione per confrontare i punteggi nel tempo e tra gli agent o gli ambienti. +## Esegui il worker - ![Un dashboard di qualità che rappresenta graficamente i punteggi dell'evaluator nel tempo.](/images/dashboard/dashboard-quality.png) +Metti una chiave con l'autorizzazione `evaluations:run`, creata sotto **Administration → Keys**, in `FAILPROOFAI_EVALUATOR_TOKEN` — impostala dal tuo archivio segreti piuttosto che digiarla in un comando — e avvia il worker: - Un grafico salutare dovrebbe utilizzare nomi di punteggio stabili; cambiare una chiave crea una serie separata. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -Per un'istanza Cloud auto-ospitata, la valutazione automatica è disabilitata fino a quando `EVALUATOR_ENDPOINT` non è impostato nel processo del server. Riavvia il server dopo aver modificato le variabili di ambiente dell'evaluator. +Senza il blocco `__main__`, `python -m failproofai_sdk.evaluator evaluator:app` fa lo stesso. -Il servizio espone `GET /health`, `GET /config`, `POST /evaluate` e facoltativamente `GET /evaluate/{job_id}`. Restituisci `JobPending` per il lavoro asincrono e registra `@app.job_lookup` in modo che Failproof AI possa eseguirne il polling. +| Variabile | Predefinito | Scopo | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | obbligatorio | Dove si trova Failproof AI: `https://app.befailproof.ai` per Cloud. HTTPS a meno che non punti a loopback | +| `FAILPROOFAI_EVALUATOR_TOKEN` | obbligatorio | Una chiave con `evaluations:run` | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | Nomina questo worker | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | Sessioni che questo worker valuta contemporaneamente | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Timeout per ogni richiesta a Failproof AI | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | Quanto tempo un worker in arresto aspetta le esecuzioni in corso | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | Consenti HTTP semplice a un URL che non è loopback — vedi l'avvertimento sotto | +| `FAILPROOFAI_EVALUATOR_MODULE` | nessuno | Il `module:attribute` per `python -m failproofai_sdk.evaluator` | -Quando un token è configurato, tutte le route eccetto health richiedono lo stesso bearer token che Failproof AI invia come `EVALUATOR_TOKEN`. + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` invia tutto in testo non crittografato. Il worker trasporta `FAILPROOFAI_EVALUATOR_TOKEN` come intestazione `Authorization: Bearer` su ogni richiesta, e i trascritti che recupera sono le sessioni stesse — quindi chiunque si trovi sul percorso legge entrambi, e la chiave che legge esegue valutazioni fino a quando non la ruoti. Usalo solo su una rete di sviluppo isolata. Ovunque altro l'URL deve essere HTTPS; loopback non ha bisogno di flag. + -## Tipi SDK +## Tipi di risultato | Tipo | Campi | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## Decoratori e route +| `Score` | `value` (da 0 a 1), `passed`, `unit` (predefinito `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -| Decoratore | Route | Obbligatorio | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | Sì | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | Quando si restituisce `JobPending` | -| `@app.config` | `GET /config` | No | - -L'SDK limita i corpi delle richieste di valutazione a 25 MiB. I campi di richiesta sconosciuti vengono ignorati in modo che i servizi rimangono compatibili quando il contratto degli eventi cresce. +Un `EvalResult` contiene almeno un punteggio, una metrica o un'asserzione, e al massimo 25, ciascuno sotto una chiave univoca. -## Restituire lavoro asincrono +## La sessione -Usa `JobPending` quando la valutazione non può finire all'interno di una richiesta. L'ID del lavoro è opaco a Failproof AI e deve rimanere risolvibile dal tuo servizio fino a quando il risultato non viene raccolto o il timeout del server non scade. - -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| Campo o metodo | Ti dà | +| --- | --- | +| `session_id`, `agent_id`, `environment` | L'identità della sessione | +| `started_at`, `ended_at` | Quando ha iniziato e terminato | +| `event_count`, `events` | Il trascritto completo e ordinato | +| `count(event_type)` | Quanti eventi di quel tipo contiene | +| `events_of_type(event_type)` | Quegli eventi, in ordine | -La cadenza di polling viene selezionata in questo ordine: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs`, quindi `EVALUATOR_POLLING_INTERVAL_SECS` del server. I valori vengono fissati tra 1 secondo e 1 ora. Il limite di polling wall-clock predefinito del server è di un'ora. +Ogni evento contiene `id`, `ts`, `event_type` e `payload`. -## Campi di richiesta e risposta +## L'evaluator legacy -| Campo | Tipo | Note | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | Attualmente `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | Identità della sessione e ambiente. | -| `started_at` | `datetime` | Timestamp del primo evento. | -| `ended_at` | `datetime \| None` | Presente quando la sessione ha emesso un evento di fine. | -| `events` | `list[AgentEvent]` | Flusso di eventi ordinato completo. | -| `AgentEvent.id` | `int` | Identificatore della riga di evento del backend. | -| `AgentEvent.ts` | `datetime` | Timestamp dell'evento. | -| `AgentEvent.event_type` | `str` | Famiglia di eventi come `tool_use`. | -| `AgentEvent.payload` | `dict[str, Any]` | Payload dell'evento completo. | -| `EvalResponse.scores` | `dict[str, float] \| None` | Dimensioni numeriche rappresentate graficamente nelle valutazioni. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | Spiegazioni per punteggio; le chiavi dovrebbero rispecchiare `scores`. | -| `EvalResponse.summary` | `str \| None` | Narrazione di valutazione complessiva. | - -## Impostazioni dell'operatore del server - -La valutazione automatica è a livello di distribuzione e rimane disabilitata quando `EVALUATOR_ENDPOINT` è assente. - -| Variabile | Predefinito | Scopo | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | non impostato | URL di base del servizio evaluator. | -| `EVALUATOR_TOKEN` | non impostato | Bearer token condiviso con `Evaluator(token=...)`. | -| `EVALUATOR_WORKERS` | `2` | Worker dispatcher concorrenti. | -| `EVALUATOR_CLAIM_BATCH` | `4` | Sessioni rivendicate per passaggio del dispatcher. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Cadenza di polling asincrono di fallback. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Timeout dell'evaluator per richiesta. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | Tentativi di consegna prima del guasto terminale. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | Cadenza di aggiornamento per `/config`. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Tempo massimo di polling asincrono wall-clock. | - -Il server può anche limitare quali organizzazioni utilizzano l'evaluator globale della distribuzione. Considera le modifiche di endpoint, token, retry e organization-gate come configurazione dell'operatore e riavvia o distribuisci il server dopo averle modificate. - -## Sicurezza e operazioni - -- Metti l'evaluator dietro HTTPS quando il traffico attraversa un confine di rete attendibile. -- Configura un bearer token non vuoto e mantienilo identico su entrambi i servizi. -- Non registrare il token o i prompt sensibili completi dai payload delle richieste. -- Rendi i gestori sincroni idempotenti; i tentativi possono ripetere una richiesta. -- Mantieni lo stato del lavoro asincrono al di fuori della memoria del processo in produzione. -- Restituisci chiavi di punteggio stabili. Rinominare una chiave crea una nuova serie di grafici anziché modificare quella vecchia. - -L'SDK emette log del ciclo di vita strutturati come `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` e eccezioni del gestore. Non configura gestori di logging; utilizza la configurazione di logging dell'applicazione host. \ No newline at end of file +Il precedente Evaluator SDK — un servizio HTTP che Failproof AI chiamava a `EVALUATOR_ENDPOINT`, rispondendo a `/evaluate` e sottoposto a polling tramite `JobPending` — è ritirato. Costruisci nuovi evaluator su questo worker; gli operatori di un'istanza self-hosted che eseguono un servizio legacy possono mantenerlo durante la transizione. \ No newline at end of file diff --git a/docs/it/reference/failproof-cli.mdx b/docs/it/reference/failproof-cli.mdx index 07dced0a..b557844c 100644 --- a/docs/it/reference/failproof-cli.mdx +++ b/docs/it/reference/failproof-cli.mdx @@ -1,86 +1,104 @@ --- title: "Failproof AI CLI" -description: "Installa gli hook, gestisci le politiche locali, connetti il Cloud e gestisci il daemon locale." +description: "Installa hook, gestisci le policy locali, connettiti al Cloud e gestisci il daemon locale." icon: "terminal" --- -Installa la CLI locale con `npm install -g failproofai`. Eseguila senza argomenti per aprire il dashboard delle politiche locali. +Installa la CLI locale con `npm install -g failproofai`. Eseguila senza argomenti per aprire il dashboard delle policy locali. -Il pacchetto richiede Node.js 20.9 o versioni successive. Bun 1.3 o versioni successive è supportato per sviluppo e installazioni da codice sorgente. `failproofai configure` e `failproofai setup` sono alias per `failproofai config`; `failproofai p` è un alias per `failproofai policies`. +Il pacchetto richiede Node.js 20.9 o più recente. Bun 1.3 o più recente è supportato per lo sviluppo e le installazioni da source. `failproofai configure` e `failproofai setup` sono alias per `failproofai config`. `failproofai policy`, `failproofai pack` e `failproofai p` sono tutti modi di scrivere `failproofai policies` — pack e policy singole erano tre comandi per una sola idea e ora sono uno solo. I vecchi nomi funzionano ancora, con due eccezioni: `pack list ` è ora `policies show `, e `pack build` è ora `publish`. ## Configura una macchina +Installa la CLI, poi leggi la chiave della macchina nella shell. `read -s` la prende da un prompt che non rimbalza, quindi non appare mai in un comando: + ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +Poi configura la macchina e scegli cosa enforza: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` -Esegui `failproofai` senza argomenti per aprire il dashboard delle politiche locali. +`failproofai config` è l'intero setup: installa il servizio `failproofaid` (root una sola volta, via `sudo -n` — mai un prompt interattivo di password), collega i hook in ogni agent CLI che trova, e si connette al Cloud quando una chiave è disponibile. Senza un terminale — CI, un container, un agent che la gestisce — applica piuttosto che chiedere, ed esce con codice 1 se qualcosa di quello che le è stato chiesto non è accaduto. + +Non sceglie nessuna policy. È il compito del secondo comando, e senza di esso una macchina appena configurata non enforza nulla se non il guard sempre attivo. + +Preferisci la variabile d'ambiente rispetto a `--token`: un argomento da riga di comando è leggibile da `ps` da ogni utente della macchina. È tutto ciò che la variabile protegge — una chiave digitata in qualsiasi comando, `export` incluso, finisce comunque nella cronologia della shell, ed è per questo che viene letta con `read -s` sopra. In CI, impostala dallo store di segreti e mantieni disattivata la traccia della shell (`set -x`), altrimenti la traccia la stampa. + + + `--connect ` iscrve una macchina che è **già configurata**. Torna non appena l'iscrizione riesce — non installa il daemon e non collega nessun hook. Usa il semplice `failproofai config` (o `failproofai config --token `) su una macchina che non è stata ancora configurata, altrimenti risulterà connessa mentre raccoglie e enforza nulla. + + +Esegui `failproofai` senza argomenti per aprire il dashboard delle policy locali. | Comando | Risultato | | --- | --- | -| `failproofai config` | Esegui la configurazione interattiva della macchina | -| `failproofai config --connect --token ` | Connetti l'acquisizione Cloud e la distribuzione delle politiche | -| `failproofai config --status` | Mostra lo stato della connessione, del daemon, della distribuzione e della pausa | -| `failproofai policies` | Elenca le politiche integrate, personalizzate, convenzionali, pack e gestite da Cloud | -| `failproofai policies --install` | Installa gli hook e abilita le politiche | -| `failproofai policy add ` | Abilita una politica — una integrata o `:` da un pack installato | -| `failproofai policy remove ` | Disabilita una politica, stessa nomenclatura | -| `failproofai policies --uninstall` | Disabilita le politiche o rimuovi gli hook del harness | -| `failproofai pack list` | Elenca i pack di politiche installati e tutte le politiche che contengono | -| `failproofai pack add ` | Installa un pack di politiche da un rilascio GitHub; senza tag prende il più recente e lo blocca | -| `failproofai pack add --bundled` | Installa le politiche integrate come pack, da questo pacchetto, senza rete | -| `failproofai pack build ` | Costruisci i tre asset di rilascio per un pack tuo | -| `failproofai pack remove ` | Disattiva un pack installato | -| `failproofai audit` | Scansiona la cronologia locale dell'agente e apri la vista di audit locale | -| `failproofai audit --schedule [days] --email
` | Pianifica scansioni locali ricorrenti e invia i risultati via email | +| `failproofai config` | Configura la macchina: agent, daemon, e Cloud quando una chiave è presente | +| `failproofai config --token ` | Configura e connetti in un solo passaggio, senza chiedere nulla | +| `failproofai config --connect ` | Iscrivi una macchina che è **già** configurata — nessun daemon, nessun hook | +| `failproofai config --status` | Mostra lo stato di connessione, daemon, consegna e pausa | +| `failproofai policies` | Elenca le policy builtin, custom, convention, pack e gestite dal Cloud | +| `failproofai policies --install` | Collega i hook ai tuoi agent CLI. Non abilita nessuna policy di per sé | +| `failproofai policies add ` | Abilita una policy — una builtin, o `:` da un pack installato | +| `failproofai policies remove ` | Disabilita una policy, con la stessa nomenclatura | +| `failproofai policies --uninstall` | Disabilita le policy o rimuovi i hook del harness | +| `failproofai policies show /` | Cosa contiene un pack, letto dal suo manifest, prima di scaricarlo | +| `failproofai policies show / --releases` | Ogni versione che ha pubblicato, e quale è presente qui | +| `failproofai policies add ` | Installa un policy pack da un rilascio GitHub; nessun tag prende il più recente e lo fissa | +| `failproofai publish` | Spedisci le tue policy come pack; `--init` ne scrive una da cui iniziare | +| `failproofai policies remove ` | Disinstalla un pack | +| `failproofai audit` | Scansiona la cronologia locale dell'agent e apri la vista audit locale | +| `failproofai audit --schedule [days] --email
` | Pianifica scansioni locali ricorrenti e invia i loro risultati via email | | `failproofai audit --status` | Mostra l'indirizzo del report, l'intervallo e la prossima scansione pianificata | -| `failproofai audit --no-schedule` | Interrompi le scansioni ricorrenti senza eliminare la cronologia di audit | -| `failproofai harness list` | Elenca i percorsi di acquisizione aggiuntivi | -| `failproofai flush --wait` | Distribuisci lo spool di eventi corrente | -| `failproofai backfill --since 30d` | Rileggi la cronologia passata in precedenza | +| `failproofai audit --no-schedule` | Ferma le scansioni ricorrenti senza eliminare la cronologia audit | +| `failproofai harness list` | Elenca i percorsi di cattura aggiuntivi | +| `failproofai flush --wait` | Consegna lo spool di eventi corrente | +| `failproofai backfill --since 30d` | Rileggi la cronologia precedentemente passata | | `failproofai config --pause [duration]` | Pausa una sessione locale per 30 minuti per impostazione predefinita, fino a 8 ore | -| `failproofai config --resume` | Riprendi una sessione locale messa in pausa; aggiungi `--all` per cancellare tutte le pause | +| `failproofai config --resume` | Riprendi una sessione locale in pausa; aggiungi `--all` per cancellare tutte le pause | | `failproofai update` | Completa le migrazioni dei pacchetti e aggiorna il daemon | -| `failproofai migrate --dry-run` | Anteprima o esegui migrazioni del layout home in sospeso | -| `failproofai uninstall` | Rimuovi gli hook e il daemon prima di rimuovere il pacchetto | +| `failproofai migrate --dry-run` | Visualizza in anteprima o esegui le migrazioni di layout home in sospeso | +| `failproofai uninstall` | Rimuovi i hook e il daemon prima di rimuovere il pacchetto | | `failproofai --version` | Stampa la versione del pacchetto installato | -| `failproofai --help` | Mostra i comandi e l'uso globale | +| `failproofai --help` | Mostra i comandi e l'utilizzo globale | ## Flag di configurazione | Flag | Uso | | --- | --- | -| `--connect --token ` | Connetti in modo non interattivo | +| `--token ` | Configura e connetti in modo non interattivo; leggi anche da `FAILPROOFAI_CLOUD_TOKEN` | +| `--url ` | Connettiti a un posto diverso da `app.befailproof.ai`; leggi anche da `FAILPROOFAI_CLOUD_URL` | +| `--connect ` | Solo iscrizione, su una macchina già configurata. Salta il daemon e ogni hook | | `--machine-id ` | Imposta l'ID macchina stabile | -| `--machine-label ` | Imposta o modifica l'etichetta del dashboard | -| `--no-transcripts` | Invia decisioni senza contenuto della trascrizione | -| `--disconnect` | Interrompi i pull delle politiche Cloud e la distribuzione degli eventi | +| `--machine-label ` | Rinomina una macchina che è **già connessa**. Da solo non esegue mai setup, quindi forniscilo dopo `failproofai config`, non durante | +| `--no-transcripts` | Invia decisioni senza contenuto di trascrizione | +| `--disconnect` | Ferma i pull delle policy Cloud e la consegna degli eventi | | `--status` | Mostra lo stato della macchina corrente | -| `--pause [duration]` | Metti in pausa la sessione più recente nella directory corrente; accetta secondi, minuti o ore e il valore predefinito è 30 minuti | +| `--pause [duration]` | Pausa la sessione più recente nella directory corrente; accetta secondi, minuti o ore e per impostazione predefinita è 30 minuti | | `--resume` | Termina una pausa corrispondente in anticipo | -| `--session ` | Seleziona una sessione esplicita per la pausa o la ripresa | +| `--session ` | Prendi di mira una sessione esplicita per pausa o ripresa | | `--all` | Con `--resume`, termina ogni pausa attiva | -Le pause locali sospendono le politiche integrate, personalizzate, convenzionali e pack per una sessione. Scadono sempre e non disabilitano le politiche gestite da Cloud. `block-failproofai-commands` — che è sempre attivo e non può essere disabilitato o messo in pausa — impedisce a un agente strumentato di usare questo meccanismo di fuga. +Le pause locali sospendono le policy builtin, custom, convention e pack per una sessione. Scadono sempre e non disabilitano le policy gestite dal Cloud. `block-failproofai-commands` — che è sempre attivo e non può essere disabilitato o messo in pausa — impedisce a un agent instrumentato di usare questo scappatoia. -## Flag delle politiche +## Flag delle policy | Flag | Uso | | --- | --- | -| `--install`, `-i` | Abilita le politiche e installa gli hook del harness | -| `--uninstall`, `-u` | Disabilita le politiche o rimuovi gli hook | -| `--cli ` | Seleziona uno o più harness supportati | -| `--scope user\|project\|local\|all` | Scegli l'ambito della configurazione; `all` è per la disinstallazione | -| `--beta` | Includi le politiche beta | -| `--custom`, `-c ` | Convalida e carica un file di politica personalizzata; ripetibile | +| `--install`, `-i` | Installa i hook del harness. I nomi dopo di esso abilitano quelle policy; senza nessuno, nessun cambiamento di policy | +| `--uninstall`, `-u` | Disabilita le policy o rimuovi i hook | +| `--cli ` | Prendi di mira uno o più harness supportati | +| `--scope user\|project\|local\|all` | Scegli l'ambito di configurazione; `all` è per uninstall | +| `--beta` | Includi le policy beta | +| `--custom`, `-c ` | Valida e carica un file di policy personalizzato; ripetibile | -## Flag di distribuzione e manutenzione +## Flag di consegna e manutenzione | Comando | Flag | | --- | --- | @@ -90,7 +108,7 @@ Le pause locali sospendono le politiche integrate, personalizzate, convenzionali | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` deve essere eseguito dopo `npm install -g failproofai@latest`; esegue migrazioni del layout home, installa il binario del daemon corrispondente e riavvia il servizio. `--no-daemon` esegue solo la migrazione del layout. +`failproofai update` dovrebbe essere eseguito dopo `npm install -g failproofai@latest`; esegue le migrazioni di layout home, installa il binario daemon corrispondente e riavvia il servizio. `--no-daemon` esegue solo la migrazione di layout. ## Percorsi del harness @@ -100,11 +118,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -I nomi dei harness supportati sono `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` e `goose`. +I nomi di harness supportati sono `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` e `goose`. -Le etichette classificano gli ID dell'agente derivato quando due root contengono copie dello stesso progetto. Le radici sovrapposte e le etichette duplicate vengono rifiutate per prevenire la raccolta duplicata o il danneggiamento del cursore. La configurazione del percorso aggiuntivo si ricarica senza un riavvio del daemon. +Le etichette creano uno spazio dei nomi per gli ID agent derivati quando due radici contengono copie dello stesso progetto. Le radici sovrapposte e le etichette duplicate vengono rifiutate per prevenire la raccolta duplicata o la corruzione del cursore. La configurazione dei percorsi aggiuntivi si ricarica senza un riavvio del daemon. -Gli ambienti container possono sostituire i percorsi aggiuntivi configurati su file con una variabile separata da virgole denominata `FAILPROOFAI__EXTRA_PATHS`, ad esempio: +Gli ambienti container possono sostituire i percorsi aggiuntivi configurati con file con una variabile separata da virgole denominata `FAILPROOFAI__EXTRA_PATHS`, ad esempio: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -112,28 +130,30 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Variabili d'ambiente -Usa file di configurazione per il comportamento persistente della macchina. Le variabili d'ambiente sono più utili per container, test e un singolo processo. +Usa i file di configurazione per il comportamento persistente della macchina. Le variabili d'ambiente sono più utili per container, test e un singolo processo. | Variabile | Uso | | --- | --- | +| `FAILPROOFAI_CLOUD_TOKEN` | La chiave Cloud, al posto di `--token`. Preferisci questa: un argomento è leggibile da `ps` da ogni utente. Impostala con `read -s` o da uno store di segreti CI, mai digitando la chiave in un comando, che finisce nella cronologia della shell comunque | +| `FAILPROOFAI_CLOUD_URL` | L'URL Cloud, al posto di `--url`. La stessa variabile che legge il daemon | | `FAILPROOFAI_HOME` | Trasferisci il layout completo `~/.failproofai` | | `FAILPROOFAI_LOG_LEVEL` | Imposta la verbosità della registrazione locale | | `FAILPROOFAI_HOOK_LOG_FILE` | Scrivi la diagnostica degli hook in un file selezionato | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | Disabilita la telemetria anonima per questo processo | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Salta la configurazione interattiva della prima esecuzione | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Salta l'audit locale post-configurazione | -| `FAILPROOFAI_LLM_BASE_URL` | Sovrascrivi l'endpoint compatibile con OpenAI utilizzato dalle politiche LLM | -| `FAILPROOFAI_LLM_API_KEY` | Fornisci la chiave API utilizzata dalle politiche LLM | -| `FAILPROOFAI_LLM_MODEL` | Seleziona il modello utilizzato dalle politiche LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limitare il caricamento del modulo di politica personalizzata | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Rifiuta di scaricare pack e binari daemon; ciò che è installato continua a funzionare | -| `FAILPROOFAI_PACK_BASE_URL` | Scarica i pack da uno specchio invece di `github.com` | -| `FAILPROOFAI__EXTRA_PATHS` | Sostituisci i percorsi di acquisizione aggiuntivi configurati per un harness | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Salta la configurazione interattiva del primo avvio | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Salta l'audit locale dopo il setup | +| `FAILPROOFAI_LLM_BASE_URL` | Sovrascrivi l'endpoint compatibile con OpenAI utilizzato dalle policy LLM | +| `FAILPROOFAI_LLM_API_KEY` | Fornisci la chiave API utilizzata dalle policy LLM | +| `FAILPROOFAI_LLM_MODEL` | Seleziona il modello utilizzato dalle policy LLM | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limita il caricamento del modulo di policy personalizzato | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Rifiuta di scaricare pack e binari daemon; ciò che è installato continua a enforza | +| `FAILPROOFAI_PACK_BASE_URL` | Scarica pack da uno specchio invece di `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | Sostituisci i percorsi di cattura aggiuntivi configurati per un harness | | `NO_COLOR` | Disabilita l'output del terminale colorato | -Le variabili home specifiche dell'agente come `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` e `OPENCLAW_HOME` sovrascrivono dove Failproof AI scopre le sessioni locali per quel harness. +Le variabili home specifiche dell'agent come `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` e `OPENCLAW_HOME` controllano dove Failproof AI scopre le sessioni locali per quell'harness. -## Metti in pausa o rimuovi una macchina in sicurezza +## Pausa o rimuovi una macchina in sicurezza ```bash failproofai config --pause @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -Una pausa della sessione locale non disabilita le politiche gestite da Cloud. Ripristina le distribuzioni Cloud attraverso il flusso di lavoro di enforcement Cloud quando il rollout stesso è il problema. +Una pausa della sessione locale non disabilita le policy gestite dal Cloud. Ripristina i deployment Cloud tramite il flusso di enforcement Cloud quando il rollout stesso è il problema. -Prima di rimuovere il pacchetto npm, rimuovi gli hook installati e il daemon: +Prima di rimuovere il pacchetto npm, rimuovi i hook installati e il daemon: ```bash failproofai uninstall --dry-run @@ -154,5 +174,5 @@ npm rm -g failproofai Esegui `failproofai --help` per i dettagli specifici della versione. - Esegui `failproofai uninstall` prima di `npm rm -g failproofai`; npm non rimuove gli hook dell'agente installati o il servizio daemon. + Esegui `failproofai uninstall` prima di `npm rm -g failproofai`; npm non rimuove i hook dell'agent installati o il servizio daemon. \ No newline at end of file diff --git a/docs/it/reference/harnesses.mdx b/docs/it/reference/harnesses.mdx index 5839de80..6490d98f 100644 --- a/docs/it/reference/harnesses.mdx +++ b/docs/it/reference/harnesses.mdx @@ -1,80 +1,86 @@ --- -title: "Harness per agent" -description: "Cattura sessioni e applica policy su tutti i 12 harness per agent supportati." +title: "Adattatori agente" +description: "Cattura sessioni e applica politiche su tutti i 12 adattatori agente supportati." icon: "plug-zap" --- -Un harness è ciò in cui l'agent effettivamente viene eseguito. Failproof AI supporta dodici di loro, in due categorie: +Un adattatore è ciò in cui l'agente effettivamente viene eseguito. Failproof AI supporta dodici di essi, in due classi: -- **Coding CLI** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Chat e gateway per assistant** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistant auto-ospitato) +- **CLI di codifica** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **Gateway di chat e assistenti** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistente self-hosted) -Le stesse policy e la stessa cronologia delle sessioni si applicano indipendentemente da quale harness esegue l'agent. Un livello adattatore mappa i nomi degli eventi nativi di ogni harness, i nomi degli strumenti e i campi di input degli strumenti su 29 eventi canonici prima che qualsiasi policy venga eseguita. +Le stesse politiche e la stessa cronologia delle sessioni si applicano indipendentemente da quale adattatore esegue l'agente. Un livello di adattamento mappa i nomi degli eventi nativi di ogni adattatore, i nomi degli strumenti e i campi di input degli strumenti su 29 eventi canonici prima che qualsiasi politica venga eseguita. -Un agent che viene eseguito in **nessuno** dei dodici viene instrumentato direttamente con [Python SDK](/it/reference/custom-agents). Questo è un contratto diverso, e vale la pena affermarlo chiaramente: l'SDK fornisce tracciamento, sessioni, valutazioni e audit — **non applica policy di per sé.** Bloccare un'azione non sicura prima che venga eseguita richiede un hook di applicazione al confine dello strumento del tuo runtime; [contattaci](mailto:support@befailproof.ai) e lo mapperemo. +Un agente che viene eseguito in **nessuno** dei dodici viene strumentato direttamente con [Python SDK](/it/reference/custom-agents). Si tratta di un contratto diverso, e vale la pena dichiararlo esplicitamente: l'SDK fornisce tracciamento, sessioni, valutazioni e audit — **non applica politiche di per sé.** Bloccare un'azione non sicura prima che venga eseguita richiede un hook di applicazione al confine degli strumenti del runtime; [contattaci](mailto:support@befailproof.ai) e lo mapperemo. -| Harness | Scope di hook supportati | +| Adattatore | Ambiti di hook supportati | | --- | --- | -| Claude Code | User, project, local | -| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | -| Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | -| Hermes, OpenClaw | User | +| Claude Code | Utente, progetto, locale | +| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | Utente, progetto | +| Factory Droid, Devin CLI, Antigravity CLI, Goose | Utente, progetto | +| Hermes, OpenClaw | Utente | -Ogni integrazione normalizza i nomi degli eventi hook nativi, i nomi degli strumenti e i campi di input degli strumenti prima che le policy vengano eseguite. Una policy può agire solo su eventi esposti dall'harness; testa il comportamento end-of-turn e delle istruzioni sull'harness e la versione esatti che distribuisci. +Ogni integrazione normalizza i nomi degli eventi hook nativi, i nomi degli strumenti e i campi di input degli strumenti prima che le politiche vengano eseguite. Una politica può agire solo su eventi esposti dall'adattatore; testa il comportamento di fine turno e istruzione sull'esatto adattatore e versione che distribuisci. ## Capacità di applicazione -"Block" significa che il verdetto restituito dall'adattatore attuale viene utilizzato dall'harness nominato. Il blocco post-tool può sostituire il risultato mostrato al modello ma non può annullare un effetto collaterale dello strumento che è già accaduto. +"Blocco" significa che il verdetto restituito dall'adattatore corrente viene utilizzato dall'adattatore nominato. Il blocco post-strumento può sostituire il risultato mostrato al modello ma non può annullare un effetto collaterale dello strumento già avvenuto. -| Harness | Eventi di blocco verificati | Caveats di sola osservazione o non bloccanti | +| Adattatore | Eventi di blocco verificati | Avvertenze di osservazione o non blocco | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` e diversi eventi di task/config | `PostToolUse`, ciclo di vita della sessione, notifiche e eventi post-errore sono osservazionali. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Il blocco post-tool sostituisce il risultato dopo l'esecuzione; gli eventi di inizio sessione e compattazione sono osservazionali nell'adattatore attuale. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Il blocco post-tool sostituisce il risultato dopo l'esecuzione; gli eventi di sessione e notifica sono osservazionali. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` e gli eventi di sessione sono osservazionali. | -| OpenCode | `PreToolUse` | Gli eventi post-tool e di ciclo di vita sono osservazionali; la gestione dello stop attuale è una guida per un turno successivo piuttosto che un gate verificato. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Gli eventi post-tool e di ciclo di vita sono osservazionali; la guida di stop si applica a un turno successivo. | -| Hermes | `PreToolUse` | I verdetti post-tool, sessione e subagent-stop non sono gate. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Gli eventi post-tool, sessione, subagent-stop e compattazione sono osservazionali. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | I verdetti post-tool e subagent-stop sono osservazionali. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condizionale | Gli hook di permesso non vengono eseguiti in ogni modalità di permesso; gli eventi post-tool e sessione sono osservazionali. | -| Antigravity CLI | `PreToolUse`, `Stop` | I verdetti di user-prompt e post-tool sono osservazionali; le istruzioni del prompt possono ancora essere iniettate. | -| Goose | `PreToolUse` | Gli eventi di user-prompt, post-tool e sessione sono osservazionali. Esiste un hook di stop di blocco nativo a monte ma non viene installato dall'adattatore attuale. | - -Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un CLI di agent, specialmente quando una policy si affida al comportamento di prompt, stop, permesso o post-tool piuttosto che al comune gate pre-tool. - -## Installa gli hook di cattura e policy +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, e diversi eventi di task/config | `PostToolUse`, ciclo di vita della sessione, notifiche ed eventi post-errore sono osservativi. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Il blocco post-strumento sostituisce il risultato dopo l'esecuzione; gli eventi di avvio della sessione e compattazione sono osservativi nell'adattatore corrente. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Il blocco post-strumento sostituisce il risultato dopo l'esecuzione; gli eventi di sessione e notifica sono osservativi. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` e gli eventi di sessione sono osservativi. | +| OpenCode | `PreToolUse` | Gli eventi post-strumento e del ciclo di vita sono osservativi; la gestione dello stop corrente è una guida per un turno successivo piuttosto che un gate verificato. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Gli eventi post-strumento e del ciclo di vita sono osservativi; la guida dello stop si applica a un turno successivo. | +| Hermes | `PreToolUse` | I verdetti post-strumento, sessione e subagent-stop non sono gate. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Gli eventi post-strumento, sessione, subagent-stop e compattazione sono osservativi. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | I verdetti post-strumento e subagent-stop sono osservativi. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condizionale | Gli hook di permesso non vengono eseguiti in ogni modalità di permesso; gli eventi post-strumento e di sessione sono osservativi. | +| Antigravity CLI | `PreToolUse`, `Stop` | I verdetti di prompt utente e post-strumento sono osservativi; le istruzioni di prompt possono comunque essere iniettate. | +| Goose | `PreToolUse` | Gli eventi di prompt utente, post-strumento e di sessione sono osservativi. Esiste un hook di stop di blocco nativo a monte ma non viene installato dall'adattatore corrente. | + +Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un CLI agente, soprattutto quando una politica si basa su comportamento di prompt, stop, permesso o post-strumento piuttosto che sul gate pre-strumento comune. + +## Installa hook di cattura e politica - 1. Apri **Administration → Keys** e crea una chiave con `events:add` e `policies:pull`, denominata per la macchina o l'ambiente. - 2. Sulla macchina di destinazione, connetti la CLI locale con la chiave visualizzata e installa gli hook dell'harness. - 3. Avvia una nuova sessione di agent, quindi conferma i suoi hook e gli eventi di sessione in **Observe → Events**. - 4. Apri **Observe → policy** per la stessa finestra temporale e conferma che una decisione di policy sia attribuita alla macchina. + 1. Apri **Administration → Keys** e crea una chiave con `events:add` e `policies:pull`, nominata per la macchina o l'ambiente. + 2. Sulla macchina di destinazione, connetti il CLI locale con la chiave visualizzata e installa gli hook dell'adattatore. + 3. Avvia una nuova sessione agente, quindi conferma i relativi hook e gli eventi di sessione sotto **Observe → Events**. + 4. Apri **Observe → policy** per la stessa finestra temporale e conferma che una decisione di politica è attribuita alla macchina. - La connessione inizia con una chiave di macchina. Conferma che includa sia le autorizzazioni di acquisizione che di consegna delle policy prima di copiare il suo segreto. + La connessione inizia con una chiave di macchina. Conferma che includa sia le autorizzazioni di acquisizione che di consegna delle politiche prima di copiare il suo segreto. - ![Il nuovo drawer della chiave API utilizzato per concedere le autorizzazioni di acquisizione degli eventi e consegna delle policy.](/images/dashboard/key-create.png) + ![Il nuovo cassetto della chiave API utilizzato per concedere autorizzazioni di acquisizione di eventi e consegna delle politiche.](/images/dashboard/key-create.png) - Dopo l'installazione degli hook, il flusso Events dovrebbe mostrare nuovi eventi dalla macchina e dall'ambiente che hai connesso. + Dopo aver installato gli hook, il flusso Events dovrebbe mostrare nuovi eventi dalla macchina e dall'ambiente che hai connesso. - ![Il flusso Events live utilizzato per confermare che un harness appena installato sta segnalando.](/images/dashboard/events-stream.png) + ![Il flusso Events live utilizzato per confermare che un adattatore appena installato sta segnalando.](/images/dashboard/events-stream.png) - Infine, verifica che le decisioni di policy siano attribuite alla stessa macchina. Questo conferma che l'harness sta segnalando l'attività di policy oltre agli eventi di traccia. + Infine, verifica che le decisioni di politica siano attribuite alla stessa macchina. Questo conferma che l'adattatore sta segnalando l'attività di politica così come gli eventi di tracciamento. - ![La pagina Policy utilizzata per verificare le decisioni di policy da un harness appena connesso.](/images/dashboard/policy-observe.png) + ![La pagina Policy utilizzata per verificare le decisioni di politica da un adattatore appena connesso.](/images/dashboard/policy-observe.png) - Installa hook per ogni harness rilevato: + Leggi la chiave di macchina nella shell. `read -s` la accetta a un prompt che non fa echo, quindi non appare mai in un comando o nella cronologia della shell: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Oppure indirizza harness nominati e uno scope di configurazione: + Quindi configura la macchina — questo collega hook per ogni adattatore rilevato, installa il daemon e si connette a Cloud: + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + La configurazione non abilita alcuna politica di per sé, ed è quello per cui serve il secondo comando. + + Oppure seleziona adattatori denominati e un ambito di configurazione: ```bash failproofai policies --install \ @@ -82,7 +88,7 @@ Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un CL --scope user ``` - Lo scope del progetto mantiene la configurazione dell'hook con un repository. Lo scope dell'utente copre il lavoro tra i repository. Claude Code supporta anche lo scope locale; il supporto varia per harness e la CLI rifiuta le combinazioni non supportate. + L'ambito di progetto mantiene la configurazione dell'hook con un repository. L'ambito utente copre il lavoro su più repository. Claude Code supporta anche l'ambito locale; il supporto varia in base all'adattatore e il CLI rifiuta le combinazioni non supportate. Verifica la macchina e i suoi eventi: @@ -98,9 +104,9 @@ Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un CL - I percorsi aggiuntivi vengono registrati sulla macchina, non nel Cloud. Dopo averne aggiunto uno, apri **Observe → Sessions**, filtra per l'ambiente della macchina e conferma che le sessioni dal nuovo percorso compaiono. Apri una sessione e controlla l'agent, l'harness e i timestamp degli eventi prima di affidarti ad essa in un audit. + I percorsi aggiuntivi vengono registrati sulla macchina, non in Cloud. Dopo averne aggiunto uno, apri **Observe → Sessions**, filtra per l'ambiente della macchina e conferma che le sessioni dal nuovo percorso vengono visualizzate. Apri una sessione e verifica l'agente, l'adattatore e i timestamp degli eventi prima di affidarsi su di essa in un audit. - ![L'elenco Sessions filtrato per l'ambiente che riceve dati dal percorso di cattura aggiuntivo.](/images/dashboard/sessions-list.png) + ![L'elenco Sessions filtrato all'ambiente che riceve dati dal percorso di cattura aggiuntivo.](/images/dashboard/sessions-list.png) Aggiungi un percorso con un'etichetta opzionale, quindi ispeziona i percorsi configurati: @@ -117,5 +123,5 @@ Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un CL - Esegui una nuova sessione dopo l'installazione. Verifica sia il flusso di eventi live che una decisione di policy effettiva prima di espandere il rollout. + Esegui una nuova sessione dopo l'installazione. Verifica sia il flusso di eventi live che una decisione di politica effettiva prima di espandere l'implementazione. \ No newline at end of file diff --git a/docs/it/reference/overview.mdx b/docs/it/reference/overview.mdx index f064779c..2bff4348 100644 --- a/docs/it/reference/overview.mdx +++ b/docs/it/reference/overview.mdx @@ -1,73 +1,76 @@ --- title: "Integrazioni e riferimento" -description: "Connetti harness di agenti supportati, SDK, CLI e l'API HTTP." +description: "Connetti harness di agent supportati, SDK, CLI e l'API HTTP." icon: "braces" --- -Scegli l'integrazione più vicina a dove il tuo agente viene già eseguito. +Scegli l'integrazione più vicina a dove il tuo agent è già in esecuzione. - Installa hook per CLI di agenti autonomi e di codifica supportati. + Installa hook per CLI di agent di codifica e autonomi supportati. - - Strumenta LangGraph, CrewAI, LlamaIndex, Pydantic AI o un agente personalizzato. + + Strumenta LangGraph, CrewAI, LlamaIndex, Pydantic AI o un agent personalizzato. Configurazione, catalogo degli eventi, regole di correlazione e consegna. - Rivedi progetti locali, sessioni, attività delle policy e audit offline. + Esamina progetti locali, sessioni, attività delle policy e audit offline. - - Configura cattura locale, hook, policy, audit, consegna e stato della macchina. + + Configura acquisizione locale, hook, policy, audit, consegna e stato della macchina. - + Interroga e amministra sessioni Cloud, audit, problemi, avvisi, chiavi, utenti e impostazioni. Valuta sessioni complete o inattive con un servizio FastAPI. - Crea e testa decisioni di autorizzazione, istruzione e negazione specifiche per il flusso di lavoro. + Crea e testa decisioni allow, instruct e deny specifiche del flusso di lavoro. - + Distribuisci il piano di controllo Cloud su un cluster Kubernetes gestito dal cliente. -Il [riferimento dell'API HTTP](/it/reference/http-api) generato copre la superficie pubblica `/v1`. Le pagine scritte manualmente spiegano i flussi di lavoro che si estendono su più endpoint o utilizzano interfacce amministrative al di fuori di quella superficie pubblica. +Il [riferimento dell'API HTTP](/it/reference/http-api) generato copre la superficie pubblica `/v1`. Le pagine scritte manualmente spiegano i flussi di lavoro che abbracciano più endpoint o utilizzano interfacce amministrative al di fuori di quella superficie pubblica. -## Connetti un agente e verifica i dati +## Connetti un agent e verifica i dati 1. Apri **Administration → Keys**, crea una chiave con `events:add` e `policies:pull`, e copia il segreto. - 2. Configura l'integrazione utilizzando la pagina corrispondente in alto. - 3. Apri **Observe → Events** per confermare l'arrivo degli eventi, quindi **Observe → Sessions** per confermare che formano esecuzioni complete. - 4. Filtra per l'ambiente dell'integrazione e ispeziona una sessione per i campi modello, strumento, errore e policy necessari agli audit. + 2. Configura l'integrazione usando la pagina corrispondente sopra. + 3. Apri **Observe → Events** per confermare che gli eventi arrivano, quindi **Observe → Sessions** per confermare che formano esecuzioni complete. + 4. Filtra per l'ambiente dell'integrazione e ispeziona una sessione per i campi model, tool, error e policy necessari agli audit. Inizia con il cassetto delle chiavi. I grant selezionati determinano se la macchina può inviare eventi e ricevere policy gestite da Cloud. - ![Il nuovo cassetto della chiave API utilizzato per concedere le autorizzazioni di acquisizione degli eventi e consegna delle policy.](/images/dashboard/key-create.png) + ![Il cassetto delle nuove chiavi API utilizzato per concedere autorizzazioni di acquisizione degli eventi e consegna delle policy.](/images/dashboard/key-create.png) - Dopo aver connesso l'integrazione, usa l'elenco Sessions per confermare che i suoi eventi vengono raggruppati in esecuzioni complete nell'ambiente previsto. + Dopo aver connesso l'integrazione, utilizza l'elenco delle sessioni per confermare che i suoi eventi vengono raggruppati in esecuzioni complete nell'ambiente previsto. - ![L'elenco Sessions utilizzato per verificare che un'integrazione appena connessa stia segnalando esecuzioni complete dell'agente.](/images/dashboard/sessions-list.png) + ![L'elenco delle sessioni utilizzato per verificare che un'integrazione appena connessa stia segnalando esecuzioni complete dell'agent.](/images/dashboard/sessions-list.png) - Apri una di queste sessioni prima di considerare l'integrazione completa; la traccia deve contenere il modello, lo strumento, l'errore e le prove di policy di cui i tuoi audit hanno bisogno. + Apri una di queste sessioni prima di considerare l'integrazione completa; la traccia dovrebbe contenere il model, il tool, l'error e le evidenze delle policy di cui i tuoi audit hanno bisogno. - Crea una chiave macchina, connetti il daemon Failproof e verifica la prima sessione. + Crea una chiave della macchina, quindi leggi il segreto che stampa nella shell. `read -s` lo accetta a un prompt che non fa echo, quindi non appare mai in un comando o nella cronologia della shell: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Connetti il daemon Failproof e verifica la prima sessione: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production @@ -76,6 +79,6 @@ Il [riferimento dell'API HTTP](/it/reference/http-api) generato copre la superfi Usa `fp --json sessions ...` quando un altro strumento consumerà il risultato. I flag globali come `--json`, `--org` e `--base-url` devono venire prima del comando. - Consulta il [riferimento della CLI Failproof AI](/it/reference/failproof-cli) per i comandi locali e il [riferimento della CLI Failproof Cloud](/it/reference/cloud-cli#cli-commands) per i comandi `fp`. + Vedi il [riferimento della Failproof AI CLI](/it/reference/failproof-cli) per i comandi locali e il [riferimento della Failproof Cloud CLI](/it/reference/cloud-cli#cli-commands) per i comandi `fp`. \ No newline at end of file diff --git a/docs/it/reference/policy-sdk.mdx b/docs/it/reference/policy-sdk.mdx index 14aad7b1..8ce37da1 100644 --- a/docs/it/reference/policy-sdk.mdx +++ b/docs/it/reference/policy-sdk.mdx @@ -1,35 +1,35 @@ --- -title: "Politiche personalizzate" -description: "Crea, testa e distribuisci politiche JavaScript o TypeScript per errori specifici dei tuoi agenti." +title: "Criteri personalizzati" +description: "Scrivi, testa e distribuisci criteri JavaScript o TypeScript per errori specifici dei tuoi agenti." icon: "shield-plus" --- -Le politiche personalizzate trasformano un modello di errore dalle tue tracce o audit in una decisione che viene eseguita mentre un agente lavora. Una politica può consentire un'azione, fornire indicazioni all'agente o negare l'azione prima che causi un altro incidente. +I criteri personalizzati trasformano un pattern di errore dalle tue tracce o auditor in una decisione che si esegue mentre un agente lavora. Un criterio può consentire un'azione, fornire indicazioni all'agente o negare l'azione prima che causi un altro incidente. -Usa una politica personalizzata quando il comportamento dipende dai tuoi strumenti, percorsi, comandi, ambienti o regole operative. Consulta il [catalogo delle politiche integrate](/it/policies/builtin-catalog) prima di ricrearne una esistente. +Utilizza un criterio personalizzato quando il comportamento dipende dai tuoi strumenti, percorsi, comandi, ambienti o regole operative. Consulta prima il [Failproof AI policy pack](/it/policies/packs) per evitare di ricreare un controllo esistente. -## Crea una politica personalizzata +## Scrivi un criterio personalizzato - 1. Vai a **Admin → policy editor**, seleziona **New policy** e descrivi l'errore che desideri prevenire. - 2. Aggiungi il codice sorgente della politica, quindi testa i corrispondenze previste e i non-corrispondenze sicuri nell'editor. Risolvi ogni errore di convalida. + 1. Vai a **Admin → policy editor**, seleziona **New policy** e descrivi l'errore che vuoi prevenire. + 2. Aggiungi il codice del criterio, quindi testa i match previsti e i non-match sicuri nell'editor. Risolvi ogni errore di validazione. 3. Salva la bozza e seleziona **Publish version** per creare una versione immutabile. - 4. Vai a **Admin → enforcement**, distribuisci la versione a una macchina di test in modalità **observe** e verifica le sue decisioni sotto **Observe → policy** prima di applicarla. + 4. Vai a **Admin → enforcement**, distribuisci la versione a una macchina di test in modalità **observe** e verifica le sue decisioni in **Observe → policy** prima di applicarla. - ![L'editor delle politiche utilizzato per creare e pubblicare una politica personalizzata.](/images/dashboard/policy-editor.png) + ![L'editor dei criteri utilizzato per scrivere e pubblicare un criterio personalizzato.](/images/dashboard/policy-editor.png) - 1. Crea `.failproofai/policies/checkout-policies.ts`. Il nome del file deve terminare con `policies.js`, `policies.mjs` o `policies.ts`. - 2. Registra una o più politiche con `customPolicies.add()`. + 1. Crea `.failproofai/policies/checkout-policies.ts`. Il nome del file deve terminare in `policies.js`, `policies.mjs` o `policies.ts`. + 2. Registra uno o più criteri con `customPolicies.add()`. 3. Valida e installa il file con `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. - 4. Attiva un'azione corrispondente e un'azione sicura. Esegui `failproofai policies`, quindi ispeziona le decisioni attribuite sotto **Observe → policy**. + 4. Attiva un'azione corrispondente e un'azione sicura. Esegui `failproofai policies`, quindi ispeziona le decisioni attribuite in **Observe → policy**. ## Inizia con una regola ristretta -Questa politica blocca i comandi Kubernetes distruttivi solo quando il comando ha come bersaglio la produzione. Tutto ciò che è al di fuori di quel preciso modello di errore restituisce `allow()`. +Questo criterio blocca i comandi Kubernetes distruttivi solo quando il comando è rivolto a produzione. Tutto al di fuori di quel pattern di errore esatto restituisce `allow()`. ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,23 +55,23 @@ customPolicies.add({ }); ``` -Le buone politiche sono abbastanza ristrette da poter essere spiegate in una frase. Corrisponde all'azione osservabile, non all'intento che speriamo avesse l'agente, e restituisci `allow()` non appena la regola non si applica. +I criteri validi sono abbastanza ristretti da poter essere spiegati in una sola frase. Fai corrispondere l'azione osservabile, non l'intento che speravi avesse l'agente, e restituisci `allow()` non appena la regola non si applica. ## Scegli una decisione | Helper | Risultato | Usalo quando | | --- | --- | --- | -| `allow(reason?)` | L'operazione continua. | La politica non si applica o l'azione è sicura. | -| `instruct(reason)` | L'operazione continua con guida dove il harness la supporta. | Desideri indirizzare l'agente verso un approccio migliore senza applicare un invariante. | +| `allow(reason?)` | L'operazione continua. | Il criterio non si applica o l'azione è sicura. | +| `instruct(reason)` | L'operazione continua con indicazioni dove lo supporta l'harness. | Vuoi indirizzare l'agente verso un approccio migliore senza applicare un invariante. | | `deny(reason)` | L'operazione viene bloccata quando l'evento e l'harness supportano il blocco. | L'azione non deve procedere. | Scrivi il motivo per l'agente che deve recuperare. Spiega cosa è stato rilevato e cosa dovrebbe fare invece. - Non usare `instruct()` per un limite di sicurezza. La consegna delle indicazioni varia a seconda dell'harness dell'agente. Usa `deny()` quando l'azione deve essere impedita. + Non usare `instruct()` per un confine di sicurezza. La distribuzione delle indicazioni varia in base all'harness dell'agente. Usa `deny()` quando l'azione deve essere prevenuta. -## Oggetto politica +## Oggetto criterio ```ts customPolicies.add({ @@ -84,32 +84,32 @@ customPolicies.add({ | Campo | Obbligatorio | Descrizione | | --- | --- | --- | -| `name` | Sì | Identificatore stabile per la politica. Mantieni i nomi univoci tra i file. | -| `description` | No | Scopo leggibile dall'uomo mostrato negli elenchi delle politiche e nelle decisioni. | -| `match.events` | No | Tipi di evento che invocano la politica. Omettere `match` la invoca per ogni evento disponibile. | +| `name` | Sì | Identificatore stabile del criterio. Mantieni i nomi univoci nei file. | +| `description` | No | Scopo leggibile mostrato negli elenchi dei criteri e nelle decisioni. | +| `match.events` | No | Tipi di evento che invocano il criterio. Omettere `match` lo invoca per ogni evento disponibile. | | `fn` | Sì | Funzione sincrona o asincrona che restituisce un risultato `allow`, `instruct` o `deny`. | -Filtra gli strumenti all'interno di `fn`. `match.toolNames` non fa parte del tipo personalizzato di politica pubblica. +Filtra gli strumenti dentro `fn`. `match.toolNames` non fa parte del tipo custom-policy pubblico. -## Contesto della politica +## Contesto del criterio -Ogni politica riceve un `PolicyContext`. +Ogni criterio riceve un `PolicyContext`. | Campo | Tipo | Cosa contiene | | --- | --- | --- | -| `eventType` | `HookEventType` | Evento normalizzato attualmente valutato. | +| `eventType` | `HookEventType` | Evento normalizzato attualmente in valutazione. | | `toolName` | `string \| undefined` | Nome dello strumento canonico come `Bash`, `Read`, `Write` o `Edit`. | -| `toolInput` | `Record \| undefined` | Input canonico per la chiamata dello strumento attuale. | -| `payload` | `Record` | Payload completo dell'evento normalizzato. | -| `session` | `SessionMetadata \| undefined` | ID della sessione, directory di lavoro, percorso della trascrizione, modalità di permesso e metadati dell'harness quando disponibili. | +| `toolInput` | `Record \| undefined` | Input canonico per la chiamata dello strumento corrente. | +| `payload` | `Record` | Payload dell'evento normalizzato completo. | +| `session` | `SessionMetadata \| undefined` | ID di sessione, directory di lavoro, percorso della trascrizione, modalità di autorizzazione e metadati dell'harness quando disponibili. | | `cli` | `string \| undefined` | Harness dell'agente sorgente, come `claude`, `codex` o `cursor`. | -| `params` | `Record` | Parametri delle politiche integrate. Le politiche personalizzate attualmente ricevono un oggetto vuoto. | +| `params` | `Record` | Parametri del criterio integrati. I criteri personalizzati ricevono attualmente un oggetto vuoto. | -Tratta ogni valore opzionale come genuinamente opzionale. Le versioni dell'agente e i tipi di evento non forniscono tutti gli stessi campi. +Tratta ogni valore facoltativo come genuinamente facoltativo. Le versioni degli agenti e i tipi di evento non forniscono tutti gli stessi campi. -### Input degli strumenti comuni +### Input comuni degli strumenti -Failproof AI normalizza gli strumenti comuni su tutti gli harness supportati in modo che una politica possa solitamente usare una forma di input. +Failproof AI normalizza gli strumenti comuni tra gli harness supportati in modo che un criterio possa di solito utilizzare una sola forma di input. | Strumento | Campi comuni | | --- | --- | @@ -119,7 +119,7 @@ Failproof AI normalizza gli strumenti comuni su tutti gli harness supportati in | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | -Usa coercizione difensiva perché i valori di input dello strumento sono tipizzati come `unknown`: +Usa una coercizione difensiva perché i valori di input dello strumento sono digitati come `unknown`: ```ts const command = String(ctx.toolInput?.command ?? ""); @@ -128,25 +128,25 @@ const filePath = String(ctx.toolInput?.file_path ?? ""); ## Scegli l'evento -| Evento | Quando viene eseguito | Uso tipico | +| Evento | Quando si esegue | Uso tipico | | --- | --- | --- | -| `PreToolUse` | Prima che uno strumento viene eseguito. | Blocca o guida comandi, scritture, letture e azioni esterne. | -| `PostToolUse` | Dopo che uno strumento restituisce. | Ispeziona i risultati prima che raggiungano l'agente. Un deny blocca il risultato intero; non redige campi selezionati. | -| `PermissionRequest` | Quando l'agente richiede un permesso. | Applica regole di permesso specifiche dell'organizzazione. | -| `UserPromptSubmit` | Prima che un prompt inviato continui. | Rifiuta istruzioni vietate o aggiungi guida del flusso di lavoro. | -| `Stop` | Quando l'agente tenta di finire. | Richiedi una condizione di completamento raggiungibile, come un passo di verifica locale. | -| `SubagentStop` | Quando un subagente tenta di finire. | Limita il lavoro delegato prima che ritorni al padre. | -| `SessionStart` / `SessionEnd` | Ai confini della sessione. | Registra o controlla lo stato a livello di sessione. | +| `PreToolUse` | Prima che uno strumento si esegua. | Blocca o guida comandi, scritture, letture e azioni esterne. | +| `PostToolUse` | Dopo che uno strumento restituisce. | Ispeziona i risultati prima che raggiungano l'agente. Un deny blocca l'intero risultato; non redige campi selezionati. | +| `PermissionRequest` | Quando l'agente richiede autorizzazione. | Applica regole di autorizzazione specifiche dell'organizzazione. | +| `UserPromptSubmit` | Prima che un prompt inviato continui. | Rifiuta istruzioni vietate o aggiungi indicazioni di workflow. | +| `Stop` | Quando l'agente tenta di terminare. | Richiedi una condizione di completamento raggiungibile, come un passo di verifica locale. | +| `SubagentStop` | Quando un subagente tenta di terminare. | Blocca il lavoro delegato prima che ritorni al genitore. | +| `SessionStart` / `SessionEnd` | Ai confini della sessione. | Registra o verifica lo stato a livello di sessione. | -La disponibilità dell'evento e il comportamento di blocco dipendono dall'harness dell'agente. Vedi [Agent harnesses](/it/reference/harnesses) prima di basarsi su un evento in una flotta mista. +La disponibilità dell'evento e il comportamento di blocco dipendono dall'harness dell'agente. Vedi [Agent harnesses](/it/reference/harnesses) prima di affidarti a un evento in una flotta mista. - + `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` e `Setup`. -## Crea modelli di politiche comuni +## Scrivi pattern comuni di criteri -### Blocca le scritture in percorsi protetti +### Blocca scritture su percorsi protetti ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### Limita il completamento della sessione +### Blocca il completamento della sessione ```ts import { execFileSync } from "node:child_process"; @@ -215,30 +215,30 @@ customPolicies.add({ ``` - Un evento `Stop` negato può far riprovare l'agente. Limita solo a una condizione che l'agente può soddisfare nell'ambiente attuale e circoscrivi ogni chiamata di subprocess o rete. + Un evento `Stop` negato può far ritentare all'agente. Blocca solo su una condizione che l'agente può soddisfare nell'ambiente corrente e delimita ogni chiamata di subprocess o di rete. -## Carica file di politica +## Carica i file dei criteri ### File di convenzione -I file di convenzione vengono caricati automaticamente: +I file di convenzione si caricano automaticamente: ```text /.failproofai/policies/security-policies.ts ~/.failproofai/policies/personal-policies.mjs ``` -- Vengono caricate sia le directory delle politiche del progetto che quelle dell'utente. -- I file vengono caricati alfabeticamente all'interno di ogni directory. -- Un file deve terminare con `policies.js`, `policies.mjs` o `policies.ts`. +- Sia le directory dei criteri del progetto che quelle dell'utente vengono caricate. +- I file si caricano alfabeticamente all'interno di ogni directory. +- Un file deve terminare in `policies.js`, `policies.mjs` o `policies.ts`. - Sono supportate più chiamate `customPolicies.add()` in un file. -- Sono supportati i relativi import da moduli locali. -- Le politiche del progetto possono essere commitmate in modo che le stesse regole seguano il repository. +- Sono supportate le importazioni relative da moduli locali. +- I criteri del progetto possono essere sottoposti a commit in modo che le stesse regole seguano il repository. ### File espliciti -Usa percorsi espliciti quando la convalida o la configurazione dovrebbe denominare direttamente il file di ingresso: +Usa percorsi espliciti quando la validazione o la configurazione deve nominare direttamente il file di ingresso: ```bash failproofai policies --install \ @@ -247,11 +247,11 @@ failproofai policies --install \ --scope project ``` -I file espliciti vengono caricati per primi, seguiti dai file di convenzione del progetto e poi dai file di convenzione dell'utente. Un file scoperto in entrambi i percorsi viene caricato una volta. +I file espliciti si caricano per primi, seguiti dai file di convenzione del progetto e dai file di convenzione dell'utente. Un file scoperto attraverso entrambi i percorsi viene caricato una sola volta. ## Valida e testa -La convalida esegue il modulo attraverso il loader di produzione e conferma che registra almeno una politica. +La validazione esegue il modulo attraverso il caricatore di produzione e conferma che registra almeno un criterio. ```bash failproofai policies --install \ @@ -260,44 +260,44 @@ failproofai policies --install \ failproofai policies ``` -La convalida rileva file mancanti, errori di sintassi, import non risolti, eccezioni di primo livello e timeout di caricamento dei moduli. Non prova che la tua logica di corrispondenza sia corretta. +La validazione rileva file mancanti, errori di sintassi, importazioni non risolte, eccezioni di livello superiore e timeout di caricamento del modulo. Non prova che la tua logica di match sia corretta. Testa almeno questi casi: -- Un'azione che deve corrispondere e produrre il motivo della politica previsto. +- Un'azione che deve corrispondere e produrre il motivo del criterio previsto. - Un'azione vicina ma sicura che deve restituire `allow()`. - Campi dello strumento mancanti o malformati. -- Sintassi alternativa di comandi, percorsi, virgolette, maiuscole/minuscole e spazi bianchi. +- Sintassi alternative del comando, percorsi, virgolette, casing e spazi. - Una dipendenza di subprocess o rete non disponibile. -Attribuisci il risultato alla tua politica personalizzata sotto **Observe → policy**. Un test bloccato non è sufficiente se una diversa politica integrata ha preso la decisione. +Attribuisci il risultato al tuo criterio personalizzato in **Observe → policy**. Un test bloccato non è sufficiente se un criterio integrato diverso ha preso la decisione. -## Comportamento a runtime +## Comportamento runtime -- Le politiche integrate vengono valutate prima delle politiche personalizzate. -- Il primo `deny` interrompe l'ulteriore valutazione della politica. -- Più risultati `instruct` possono essere combinati quando nessuna politica nega l'evento. -- Una funzione di politica ha una scadenza di esecuzione di 10 secondi. +- I criteri integrati vengono valutati prima dei criteri personalizzati. +- Il primo `deny` interrompe l'ulteriore valutazione dei criteri. +- Più risultati di `instruct` possono essere combinati quando nessun criterio nega l'evento. +- Una funzione di criterio ha una scadenza di esecuzione di 10 secondi. - Un'eccezione lanciata o un timeout viene registrato e trattato come `allow()`. -- Un file di convenzione che non riesce a caricarsi viene saltato; altri file personalizzati e le politiche integrate continuano. -- Il caricamento del modulo di primo livello ha anche una scadenza di 10 secondi. -- La modalità observe del cloud esegue la politica ma registra una decisione non consentire senza applicarla. +- Un file di convenzione che non riesce a caricarsi viene saltato; altri file personalizzati e criteri integrati continuano. +- Il caricamento del modulo di livello superiore ha anche una scadenza di 10 secondi. +- La modalità observe nel cloud esegue il criterio ma registra una decisione non-allow senza applicarla. -Mantieni i moduli di politica deterministici e veloci. Evita le chiamate di rete di primo livello o l'avvio del server. Circoscrivi il lavoro all'interno di `fn`, cattura i guasti di dipendenza e scegli deliberatamente se quel guasto dovrebbe consentire o negare l'operazione. +Mantieni i moduli di criterio deterministici e veloci. Evita chiamate di rete di livello superiore o avvio del server. Delimita il lavoro dentro `fn`, cattura i guasti di dipendenza e scegli deliberatamente se quel guasto dovrebbe consentire o negare l'operazione. ## Esportazioni API | Esportazione | Scopo | | --- | --- | -| `customPolicies.add(policy)` | Registra una politica personalizzata quando il modulo viene caricato. | +| `customPolicies.add(policy)` | Registra un criterio personalizzato quando il modulo si carica. | | `allow(reason?)` | Consenti l'operazione. | -| `instruct(reason)` | Consenti l'operazione e fornisci guida dove supportata. | -| `deny(reason)` | Blocca l'operazione dove supportata. | -| `getCustomHooks()` | Restituisce le politiche attualmente registrate nel registro del modulo. | -| `clearCustomHooks()` | Cancella quel registro, principalmente per test e loader. | +| `instruct(reason)` | Consenti l'operazione e fornisci indicazioni dove supportate. | +| `deny(reason)` | Blocca l'operazione dove supportato. | +| `getCustomHooks()` | Restituisce i criteri attualmente registrati nel registro del modulo. | +| `clearCustomHooks()` | Cancella quel registro, principalmente per test e caricatori. | TypeScript esporta `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` e `PolicyFunction`. - - Pubblica una versione, distribuiscila in modalità observe, verifica le decisioni e passa all'enforcement. + + Pubblica una versione, distribuiscila in modalità observe, verifica le decisioni e passa all'applicazione. \ No newline at end of file diff --git a/docs/it/sessions/evaluations.mdx b/docs/it/sessions/evaluations.mdx index ee8a957b..648dcf83 100644 --- a/docs/it/sessions/evaluations.mdx +++ b/docs/it/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "Valutazioni online" -description: "Valuta sessioni live e completate per qualità, conformità, costi e latenza." +title: "Leggere i risultati delle valutazioni" +description: "Traccia i punteggi di valutazione nel tempo, confronta agenti e ambienti, scopri perché una sessione ha ottenuto un punteggio basso e chiedi all'assistente." icon: "gauge" --- -Le valutazioni online applicano giudizi coerenti alle sessioni degli agenti. Usale per segnali che devono essere misurati continuamente piuttosto che indagati solo durante un audit. +I risultati di ogni valutazione, ospitata o dal tuo worker, arrivano negli stessi luoghi. -## Rivedere la qualità della valutazione +## Confronta i punteggi nel tempo - 1. Vai a **Observe → Evaluations**. - 2. Aggiungi una serie e scegli l'agente, l'ambiente, il punteggio di valutazione, la statistica e la curva. - 3. Aggiungi serie per confrontare ambienti, agenti o chiavi di punteggio. - 4. Seleziona un risultato per aprire le sessioni corrispondenti o condividere la vista filtrata. Usa **Observe → Metrics** per latenza, token, costi e altri valori di grandezza. + Vai a **Observe → evaluations**. - ![Un dashboard di qualità che mostra i punteggi di valutazione medi e i trend nel tempo.](/images/dashboard/dashboard-quality.png) + - **Recent runs** elenca ogni valutazione man mano che arriva: se proviene da un valutatore ospitato (**managed**) o dal tuo (**customer**), l'agente e la sessione, la valutazione e la sua versione, il suo stato e il suo punteggio o metriche. + - **Score over time** traccia quello che chiedi. Seleziona **add series** e scegli un agente, un ambiente, una valutazione e una statistica: avg, min, max, p50, p75, p90, p95, p99, stddev o mode. Ogni serie è una linea; assegnale una propria **curve** per disegnarla su un grafico separato. - Apri una sessione dal drill-down per ispezionare il suo ragionamento per punteggio: + ![La pagina delle valutazioni: esecuzioni recenti contrassegnate come customer, un grafico dei punteggi nel tempo con linee di riferimento a 0,5 e 0,8, e una serie che fa la media di finished_clean su tutti gli agenti e gli ambienti.](/images/dashboard/evaluations-chart.png) - ![Una vista dettagli sessione che mostra i punteggi di valutazione e il ragionamento accanto alla traccia completa.](/images/dashboard/session-detail.png) + Un intervallo di tempo e una dimensione del bin si applicano a tutte le serie. Un bin fine trova un incidente; uno grossolano mostra un trend e può nascondere i picchi che stai cercando. Un bucket dove non è stato calcolato alcun punteggio è uno spazio nella linea, mai uno zero, e le linee di riferimento segnano 0,5 e 0,8. + + Ogni parte della vista vive nell'URL: **share** la copia, e chiunque la apra vede esattamente il confronto che hai costruito. ```bash @@ -28,25 +28,29 @@ Le valutazioni online applicano giudizi coerenti alle sessioni degli agenti. Usa fp evals --score helpfulness:0.8.. --since 7d ``` - Aggiungi il flag globale `--json` prima di `evals` per l'automazione, ad esempio `fp --json evals --aggregate --env production`. + Aggiungi il global `--json` prima di `evals` per l'automazione, ad esempio `fp --json evals --aggregate --env production`. -Un valutatore riceve l'identità della sessione, l'ambiente, i timestamp e gli eventi ordinati. Può restituire chiavi di punteggio numeriche con ragionamento facoltativo e un riepilogo. I valutatori a lunga esecuzione possono restituire un job in sospeso e essere sottoposti a polling in seguito. +Traccia **avg** e **p90** per la stessa valutazione per vedere se una buona media sta nascondendo una coda scadente, oppure la stessa valutazione per due agenti, o per production e staging, per confrontarli su un solo asse. Costi, latenze e conteggi di token, che hanno unità, si trovano in un grafico sotto **Observe → metrics**, un grafico per unità. + +## Scopri perché una sessione ha ottenuto un punteggio basso + +Apri una sessione da **Observe → sessions**; la griglia contiene i punteggi di ogni sessione e filtra per intervallo di punteggio. La barra laterale destra della sessione inizia con il riepilogo della valutazione, quindi una barra per ogni punteggio con il ragionamento del valutatore sotto di essa. + +![Una vista dei dettagli della sessione che mostra i punteggi di valutazione e il ragionamento accanto alla traccia completa.](/images/dashboard/session-detail.png) + +## Chiedi all'assistente + +Fai domande sui dati di valutazione in inglese semplice: "dimmi qualcosa sulle valutazioni recenti", oppure su quali agenti i punteggi stanno diminuendo. L'[assistente](/it/sessions/assistant) legge e analizza i risultati e risponde con tabelle su cui puoi fare ulteriori domande, e una domanda interessante può diventare una [query](/it/sessions/queries) o una [dashboard](/it/sessions/dashboards). -## Buoni obiettivi di valutazione +![La pagina delle valutazioni accanto all'assistente, che risponde a "tell me about some of the recent evaluations" con un riepilogo di totali, stati e punteggi.](/images/dashboard/evaluations-assistant.png) -- Completamento o correttezza del compito -- Fondatezza e rischio di allucinazione -- Selezione degli strumenti ed efficienza degli strumenti -- Conformità alle politiche o ai processi -- Budget di costi e latenza -- Escalation umana richiesta +## Monitora e agisci -## Dal punteggio alla risposta +- **Dashboards**, sotto **Analyze → dashboards**, tendono i punteggi che presenti, per agente e ambiente, per l'intera organizzazione. -Mostra i punteggi nei dashboard per tracciare i trend. Crea avvisi per soglie o condizioni composte. Quando un punteggio diminuisce all'interno di una popolazione, esegui un audit per indagare il motivo; quando la causa è un'azione ripetibile, distribuisci una politica. + ![Una dashboard di qualità che mostra i punteggi medi di valutazione e i trend nel tempo.](/images/dashboard/dashboard-quality.png) - - Implementa una valutazione sincrona o asincrona con l'SDK valutatore Python. - \ No newline at end of file +- **Alerts** ti notificano quando un punteggio supera una soglia. Vedi [alerts](/it/audits/alerts). +- Quando un punteggio diminuisce su molte sessioni, [esegui un audit](/it/audits/run) per scoprire il motivo; quando la causa è un'azione ripetibile, [scrivi una policy](/it/policies/editor). \ No newline at end of file diff --git a/docs/it/start/integrations/custom-agents.mdx b/docs/it/start/integrations/custom-agents.mdx index 7b6ed12e..9e2f4361 100644 --- a/docs/it/start/integrations/custom-agents.mdx +++ b/docs/it/start/integrations/custom-agents.mdx @@ -7,7 +7,7 @@ icon: "code" Per un agente che hai scritto tu stesso, o un framework per il quale Failproof AI non ha un adapter. Non c'è nulla da strumentare: tu emetti gli eventi. -Questa è la stessa API che i quattro adapter del framework chiamano internamente. Sono tabelle di traduzione su di essa. +Questa è la stessa API che i quattro adapter di framework chiamano internamente. Sono tabelle di traduzione su di essa. ## Installa @@ -15,7 +15,7 @@ Questa è la stessa API che i quattro adapter del framework chiamano internament pip install failproofai-sdk ``` -Nessun extra, e nessuna dipendenza. +Nessun extra, nessuna dipendenza. ## Strumenta @@ -24,33 +24,33 @@ import failproofai_sdk failproofai_sdk.configure(environment="production") -with failproofai_sdk.session(): # one run - with failproofai_sdk.agent("planner"): # one unit of work +with failproofai_sdk.session(): # una esecuzione + with failproofai_sdk.agent("planner"): # un'unità di lavoro with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # one tool call + t.output = search(q) # una chiamata dello strumento ``` -Leggilo dall'alto al basso e dice quello che significa: +Leggi da cima a fondo e dice quello che significa: -| Avvolgilo in | Per dire | +| Avvolgi con | Per dire | | --- | --- | | `session()` | Questi eventi appartengono alla stessa esecuzione | -| `agent()` | Qualcosa sta facendo lavoro — dagli un nome che riconosceresti in una lista | +| `agent()` | Qualcosa sta svolgendo un lavoro — assegnale un nome che riconosceresti in un elenco | | `tool_call()` | Questo è uno strumento, e ecco cosa ha restituito | -E quello che ognuno effettivamente emette: +E cosa emette effettivamente ciascuno: | Ambito | Emette | Scopo | | --- | --- | --- | -| `session()` | Niente | Associa un session id, raggruppando un'esecuzione | +| `session()` | Nulla | Associa un session id, raggruppando un'esecuzione | | `agent()` | `agent_start`, `agent_end` | Racchiude un'unità di lavoro | | `tool_call()` | `tool_use`, `tool_result` | Racchiude uno strumento e lo misura | -Tutto ciò che è dentro può omettere `session_id` e `agent_id`. Gli ambiti associano l'identità su variabili di contesto e ogni chiamata di evento la legge di nuovo, quindi non devi mai passare gli id attraverso le tue funzioni. +Tutto ciò che è contenuto può omettere `session_id` e `agent_id`. Gli ambiti vincolano l'identità su variabili di contesto e ogni chiamata di evento la legge di nuovo, quindi non devi mai passare gli id attraverso le tue funzioni. -Tutti e tre funzionano con `async with` così come con `with`. +Tutti e tre funzionano sia con `async with` che con `with`. -Annidare gli agenti costruisce l'albero. `parent_id` e la profondità vengono calcolati dallo stack: +L'annidamento di agenti costruisce l'albero. `parent_id` e profondità sono calcolati dalla stack: ```python with failproofai_sdk.session(): @@ -59,24 +59,24 @@ with failproofai_sdk.session(): ... ``` -## Come si chiude un ambito +## Come un ambito si chiude `agent()` gestisce le eccezioni per te: | Cosa è successo | Eventi | Risultato | | --- | --- | --- | -| Niente sollevato | `agent_end` | `success` | +| Nulla lanciato | `agent_end` | `success` | | `Exception` | `error`, poi `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, poi `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | solo `agent_end` | `cancelled` | -L'errore viene emesso prima di `agent_end`, perché la dashboard chiude lo span a `agent_end` e qualsiasi cosa dopo viene attribuita al nulla. Un'annullamento non è un fallimento, quindi le esecuzioni annullate non inquinano la superficie degli errori. L'eccezione viene sempre sollevata di nuovo: un ambito non la inghiotte mai. +L'errore è emesso prima di `agent_end`, perché il dashboard chiude lo span a `agent_end` e qualsiasi cosa dopo è attribuita a nulla. Una cancellazione non è un fallimento, quindi le esecuzioni cancellate non inquinano la superficie degli errori. L'eccezione è sempre lanciata di nuovo: un ambito non inghiotte mai. -## I metodi degli eventi +## I metodi evento -Quindici metodi in sei famiglie. La maggior parte viene in coppie — tu emetti l'apertura, poi la chiusura, e l'SDK misura lo span tra loro. +Quindici metodi in sei famiglie. La maggior parte viene in coppia — emetti l'apertura, poi la chiusura, e l'SDK misura l'intervallo tra loro. -| Famiglia | Apre | Chiude | Autonomo | +| Famiglia | Apre | Chiude | Indipendente | | --- | --- | --- | --- | | **Agenti** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | @@ -87,7 +87,7 @@ Quindici metodi in sei famiglie. La maggior parte viene in coppie — tu emetti | **Fallimenti** | — | — | `error` | - Preferisci gli ambiti — `agent()` e `tool_call()` — ovunque si adattino. Garantiscono l'evento di chiusura anche quando il corpo solleva. Raggiungi questi metodi direttamente quando il flusso di controllo non si annida, come una chiamata di modello all'interno di un helper. + Preferisci gli ambiti — `agent()` e `tool_call()` — ovunque si adattino. Garantiscono l'evento di chiusura anche quando il corpo genera un'eccezione. Raggiungi questi metodi direttamente quando il tuo flusso di controllo non si annida, ad esempio una chiamata di modello dentro un helper. @@ -148,16 +148,16 @@ failproofai_sdk.event.error( | `human_wait` / `human_input` | L'**agente ha chiesto a una persona** — un gate di approvazione, una domanda di chiarimento | | `human_pause` / `human_interrupt` | Una **persona ha agito sull'agente** — un pulsante di arresto, una pausa dell'operatore | - Nessun framework segnala la seconda coppia, quindi spetta sempre a te emetterla. + Nessun framework segnala la seconda coppia, quindi è sempre tuo compito emetterla. - **Passa `request_id` quando le chiamate di modello vengono eseguite contemporaneamente.** Senza di esso, le richieste e le risposte si associano in ordine di arrivo per agente — e le chiamate contemporanee si accopiano male, allegando ogni risposta alla richiesta sbagliata. + **Passa `request_id` quando le chiamate di modello vengono eseguite contemporaneamente.** Senza di esso, le richieste e le risposte si abbinano in ordine di arrivo per agente — e le chiamate contemporanee si abbinano male, allegando ogni risposta alla richiesta sbagliata. ## Esempio -Un ciclo di tool-calling rispetto all'API OpenAI, senza framework di agenti: +Un ciclo di chiamata di strumenti contro l'API di OpenAI, senza framework di agenti: ```python import json @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # bounded; an unbounded agent loop is its own bug + for _ in range(4): # limitato; un ciclo di agente illimitato è un suo bug message = turn(messages) if not message.tool_calls: break @@ -204,30 +204,30 @@ with failproofai_sdk.session(): }) ``` -Questo produce gli stessi sei tipi di evento che darebbe un adapter. La versione completamente eseguibile, con le definizioni degli strumenti, è spedita nel repository dell'SDK sotto `docs/manual/examples/`. +Questo produce gli stessi sei tipi di evento che un adapter ti darebbe. La versione completamente eseguibile, con le definizioni degli strumenti, è fornita nel repository SDK under `docs/manual/examples/`. ## Thread e async -Le variabili di contesto si propagano nei compiti asyncio automaticamente. Non si propagano nei nuovi thread, perché un thread inizia con un contesto vuoto. +Le variabili di contesto si propagano nei task asyncio automaticamente. Non si propagano nei nuovi thread, perché un thread inizia con un contesto vuoto. ```python -# asyncio: nothing to do +# asyncio: nulla da fare async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads: wrap the callable +# thread: avvolgi il callable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Senza `propagate()`, gli eventi del worker sollevano un `TypeError` nominando la correzione piuttosto che arrivare a nessuna sessione. È intenzionale: un evento senza sessione viene saltato dall'ingest e riceve `200`, che è il fallimento silenzioso che il livello di identità esiste per prevenire. +Senza `propagate()`, gli eventi del worker generano un `TypeError` che nomina la correzione anziché atterrare su nessuna sessione. È intenzionale: un evento senza sessione è saltato dall'ingest e restituito `200`, che è il fallimento silenzioso che il livello di identità esiste per prevenire. ## Strumenta un framework senza un adapter -Ogni framework di agenti ti dà le stesse tre giunture. Mappale e hai una traccia completa — i quattro adapter spediti non fanno niente di più che questo. +Ogni framework di agenti ti dà le stesse tre giunzioni. Mappale e hai una traccia completa — i quattro adapter forniti non fanno nulla di più che questo. -| La giuntura | Quello che scrivi | Quello che arriva | +| La giunzione | Quello che scrivi | Quello che atterra | | --- | --- | --- | | L'esecuzione | `session()` + `agent()` | `agent_start`, `agent_end` | | Ogni strumento | `tool_call()` | `tool_use`, `tool_result` | @@ -242,7 +242,7 @@ Ogni framework di agenti ti dà le stesse tre giunture. Mappale e hai una tracci ``` - In qualunque cosa il framework chiami un wrapper di strumento o middleware. + In qualsiasi cosa il framework chiami wrapper di strumento o middleware. ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -264,31 +264,31 @@ Ogni framework di agenti ti dà le stesse tre giunture. Mappale e hai una tracci - **Hai un confine di nodo, step o middleware che vale la pena vedere?** Avvolgilo in una coppia di hook — `hook_triggered` / `hook_completed` — non un `agent()` annidato. `agent_id` è una facet a bassa cardinalità, e un'entry per nodo l'annega. Gli span Hook si rendono nello stesso modo e ti danno una latenza per nodo. + **Hai un confine di nodo, passo o middleware che vale la pena vedere?** Avvolgilo in una coppia di hook — `hook_triggered` / `hook_completed` — non in un `agent()` annidato. `agent_id` è una sfaccettatura a bassa cardinalità, e un'entry per nodo lo annega. Gli span hook si rendono allo stesso modo e ti danno latenza per nodo. - **Manuale e automatico si compongono.** Un adapter in esecuzione all'interno di un ambito scritto a mano si unisce a quella sessione e ha come padre quell'agente, quindi ottieni un albero piuttosto che due — utile quando strumenti un framework tu stesso insieme a uno supportato. + **Manuale e automatico si compongono.** Un adapter in esecuzione dentro un ambito scritto a mano si unisce a quella sessione e si aggancia a quell'agente, quindi ottieni un albero anziché due — utile quando strumenti un framework da solo insieme a uno supportato. - Due ragioni, e le tre giunture sopra sono la risposta a entrambe: + Due motivi, e le tre giunzioni sopra sono la risposta ad entrambi: - - `autogen-core` non è stato mantenuto da settembre 2025. - - AG2 non espone un punto di registrazione a livello di processo equivalente agli hook dei framework altri, quindi strumentarlo significa avvolgere ogni agente in ogni sito di costruzione. + - `autogen-core` non è stata mantenuta dal settembre 2025. + - AG2 non espone un punto di registrazione a livello di processo equivalente agli hook degli altri framework, quindi strumentarlo significa avvolgere ogni agente ad ogni sito di costruzione. - Mappare le giunture a mano registra gli stessi eventi, con la stessa fedeltà, di un adapter spedito. + Mappare le giunzioni a mano registra gli stessi eventi, con la stessa fedeltà, che un adapter fornito darebbe. ## Approfondisci -Come funziona effettivamente la registrazione. Niente di questo è necessario per iniziare. +Come la registrazione funziona effettivamente. Niente di tutto ciò è necessario per iniziare. -Ogni registrazione ha la stessa forma: uno span si apre, il lavoro si annida dentro, e ogni evento di apertura riceve uno di chiusura. +Ogni registrazione ha la stessa forma: uno span si apre, il lavoro si annida dentro, e ogni evento di apertura ne ottiene uno di chiusura. ```mermaid flowchart LR @@ -302,15 +302,15 @@ flowchart LR La **coppia** è l'unità. Ogni evento di chiusura porta una durata che l'SDK misura dal suo evento di apertura. -Di seguito è una vera esecuzione per framework — catturata dagli esempi spediti con l'SDK, il nome del modello normalizzato. Nota quanto ritorna da una singola chiamata. +Di seguito è una vera esecuzione per framework — catturata dagli esempi forniti con l'SDK, nome del modello normalizzato. Nota quanto ritorna da una singola chiamata. - ```text 14 events + ```text 14 eventi 1 +0.000s agent_start LangGraph 2 +0.001s hook_triggered agent 3 +0.002s model_request gpt-4o-mini - 4 +3.023s model_response gpt-4o-mini · 21 out-tok + 4 +3.023s model_response gpt-4o-mini · 21 token-out 5 +3.024s hook_completed agent 6 +3.024s hook_triggered tools 7 +3.025s tool_use word_count @@ -318,24 +318,24 @@ Di seguito è una vera esecuzione per framework — catturata dagli esempi spedi 9 +3.025s hook_completed tools 10 +3.026s hook_triggered agent 11 +3.027s model_request gpt-4o-mini - 12 +5.717s model_response gpt-4o-mini · 5 out-tok + 12 +5.717s model_response gpt-4o-mini · 5 token-out 13 +5.720s hook_completed agent 14 +5.721s agent_end LangGraph · success ``` - I nodi diventano coppie di hook, quindi ottieni la latenza per nodo senza che affollino la lista degli agenti. + I nodi diventano coppie di hook, quindi ottieni la latenza per nodo senza che affollino l'elenco degli agenti. - ```text 10 events + ```text 10 eventi 1 +0.000s agent_start crew 2 +0.050s agent_start analyst · under crew 3 +0.057s model_request gpt-4o-mini - 4 +3.475s model_response gpt-4o-mini · 19 out-tok + 4 +3.475s model_response gpt-4o-mini · 19 token-out 5 +3.478s tool_use lookup_metric 6 +3.478s tool_result lookup_metric · ok 7 +3.486s model_request gpt-4o-mini - 8 +5.694s model_response gpt-4o-mini · 9 out-tok + 8 +5.694s model_response gpt-4o-mini · 9 token-out 9 +5.727s agent_end analyst · success 10 +5.739s agent_end crew · success ``` @@ -344,19 +344,19 @@ Di seguito è una vera esecuzione per framework — catturata dagli esempi spedi - ```text 26 events + ```text 26 eventi 1 +0.000s agent_start Agent 2 +0.001s hook_triggered init_run 4 +0.501s hook_triggered setup_agent 6 +0.503s hook_triggered run_agent_step 7 +0.505s model_request gpt-4o-mini - 8 +3.083s model_response gpt-4o-mini · 18 out-tok + 8 +3.083s model_response gpt-4o-mini · 18 token-out 10 +3.197s hook_triggered parse_agent_output 12 +3.355s hook_triggered call_tool 13 +3.355s tool_use city_population 14 +3.355s tool_result city_population · ok 16 +3.356s hook_triggered aggregate_tool_results - ... second iteration + ... seconda iterazione 26 +7.038s agent_end Agent · success ``` @@ -364,60 +364,60 @@ Di seguito è una vera esecuzione per framework — catturata dagli esempi spedi - ```text 8 events + ```text 8 eventi 1 +0.000s agent_start agent 2 +0.001s model_request gpt-4o-mini - 3 +4.413s model_response gpt-4o-mini · 17 out-tok + 3 +4.413s model_response gpt-4o-mini · 17 token-out 4 +4.415s tool_use population 5 +4.415s tool_result population · ok 6 +4.416s model_request gpt-4o-mini - 7 +8.118s model_response gpt-4o-mini · 6 out-tok + 7 +8.118s model_response gpt-4o-mini · 6 token-out 8 +8.119s agent_end agent · success ``` - Nessuna coppia di hook: Pydantic AI non ha un confine di nodo o step da racchiudere. + Nessuna coppia di hook: Pydantic AI non ha un confine di nodo o passo da racchiudere. - ```text 6 events + ```text 6 eventi 1 +0.000s agent_start main 2 +0.000s tool_use population 3 +0.000s tool_result population · ok 4 +0.000s model_request gpt-4o-mini - 5 +0.000s model_response gpt-4o-mini · 3 out-tok + 5 +0.000s model_response gpt-4o-mini · 3 token-out 6 +0.000s agent_end main · success ``` - Tu emetti questi tu stesso. Stessi tipi di evento, stessa fedeltà — ti costa i siti di chiamata. + Tu emetti questi. Stessi tipi di evento, stessa fedeltà — ti costa i siti di chiamata. - + -**Non esiste un evento session-end.** Una sessione non è qualcosa che chiudi — è un gruppo di eventi che condividono un `session_id`. +**Non c'è evento di chiusura sessione.** Una sessione non è qualcosa che chiudi — è un gruppo di eventi che condividono un `session_id`. Lo stato è derivato dalla forma della traccia: | Stato | Quando | | --- | --- | | `ongoing` | Almeno uno span è ancora aperto | -| `paused` | Un `agent_pause` non ha un `agent_resume` corrispondente | -| `error` | Niente è aperto, e almeno un evento ha fallito | -| `done` | Niente è aperto, e niente ha fallito | +| `paused` | Un `agent_pause` non ha un corrispondente `agent_resume` | +| `error` | Nulla è aperto, e almeno un evento ha fallito | +| `done` | Nulla è aperto, e nulla ha fallito | -Quindi una sessione finisce quando ogni coppia è chiusa. Gli adapter emettono `agent_end` per te, e allo smontaggio chiudono tutto ciò che è ancora aperto e lo contrassegnano come incompleto — un'esecuzione in crash si risolve come `done` con un vuoto visibile piuttosto che rimanendo sospesa. +Quindi una sessione termina quando ogni coppia è chiusa. Gli adapter emettono `agent_end` per te, e in fase di teardown chiudono qualsiasi cosa ancora aperta e la contrassegnano come incompleta — un'esecuzione arrestata si assesta come `done` con un gap visibile anziché stare sospesa. - Ecco perché una sessione può durare due chiamate. Un `interrupt()` LangGraph mette in pausa l'esecuzione, lo span radice rimane volutamente aperto, e la chiamata riprendente lo chiude. Entrambe le chiamate sono una sessione. + Questo è il motivo per cui una sessione può coprire due chiamate. Un `interrupt()` di LangGraph mette in pausa l'esecuzione, lo span radice rimane deliberatamente aperto, e la chiamata ripresa lo chiude. Entrambe le chiamate sono una sessione. - + -`session_id` e `agent_id` sono opzionali su ogni metodo di evento. Omessi, si risolvono dall'ambito che li racchiude: +`session_id` e `agent_id` sono opzionali in ogni metodo evento. Omessi, si risolvono dall'ambito che li racchiude: ```python with failproofai_sdk.session(): @@ -425,50 +425,50 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Passarli esplicitamente funziona ancora e ha la precedenza. Senza niente associato e niente passato, la chiamata solleva un `TypeError` nominando la correzione piuttosto che emettendo un evento senza sessione, che ingest salterebbe rispondendo `200`. +Pasarli esplicitamente funziona ancora e ha precedenza. Senza nulla vincolato e nulla passato, la chiamata genera un `TypeError` che nomina la correzione anziché emettere un evento senza sessione, che l'ingest salterebbe mentre restituisce `200`. -Gli ambiti associano l'identità su variabili di contesto. Queste si propagano nei compiti asyncio automaticamente ma non nei nuovi thread — avvolgi un worker in `failproofai_sdk.propagate()`. +Gli ambiti vincolano l'identità su variabili di contesto. Queste si propagano nei task asyncio automaticamente ma non nei nuovi thread — avvolgi un worker in `failproofai_sdk.propagate()`. -#### Chi crea quale id +#### Chi conia quale id -| Id | Creato da | Note | +| Id | Coniato da | Note | | --- | --- | --- | -| `session_id` | Tu, o l'SDK | `session("chat-42")` viene usato verbatim; omesso, l'SDK genera un `uuid4().hex` | -| `agent_id` | Tu, o il framework | Da `agent("analyst")`, un `role` di CrewAI, un `FunctionAgent.name`. Un valore simile a UUID viene rifiutato e sostituito | -| `tool_call_id`, `hook_id`, `request_id` | Tu, o il framework | Gli adapter riutilizzano gli id di esecuzione del framework stesso, ecco perché le coppie sopravvivono ai salti di thread | -| **Event id** | **Cloud, all'ingest** | L'SDK non ne emette nessuno | -| **`dedup_key`** | **Cloud, all'ingest** | Un hash di org, sessione, timestamp, tipo e payload. Questa è l'identità reale — fa collassare un batch ritentato invece di duplicarlo | +| `session_id` | Tu, o l'SDK | `session("chat-42")` è usato verbatim; omesso, l'SDK genera un `uuid4().hex` | +| `agent_id` | Tu, o il framework | Da `agent("analyst")`, un `role` di CrewAI, un `FunctionAgent.name`. Un valore che somiglia a UUID è rifiutato e sostituito | +| `tool_call_id`, `hook_id`, `request_id` | Tu, o il framework | Gli adapter riutilizzano gli id di esecuzione propri del framework, motivo per cui le coppie sopravvivono ai salti di thread | +| **Id evento** | **Cloud, in ingest** | L'SDK non ne emette alcuno | +| **`dedup_key`** | **Cloud, in ingest** | Un hash di org, sessione, timestamp, tipo e payload. Questa è l'identità reale — rende un batch ritentato collassato anziché duplicato | #### Come gli adapter risolvono `session_id` La prima corrispondenza vince: 1. Un `session_id` esplicito -2. Metadati per-call -3. L'ambito `session()` che racchiude +2. Metadati per-chiamata +3. L'ambito `session()` che lo racchiude 4. Metadati del framework -5. L'id di esecuzione del framework stesso +5. L'id di esecuzione proprio del framework -Non viene mai inventato mentre uno di quelli esiste — un id sintetizzato dividerebbe un'esecuzione su più sessioni. +Non è mai inventato mentre uno di questi esiste — un id sintetizzato dividerebbe un'esecuzione su più sessioni. #### Mantieni `agent_id` a bassa cardinalità -È la facet primaria su ogni superficie della dashboard, e una colonna `LowCardinality(String)`. Un valore per-esecuzione degrada la colonna e riempie il menu filtro con un'entry per esecuzione. +È la sfaccettatura primaria su ogni superficie del dashboard, e una colonna `LowCardinality(String)`. Un valore per-esecuzione degrada la colonna e riempie il dropdown del filtro con un'entry per esecuzione. Gli adapter difendono quella colonna per te: | Il framework consegna | Registrato come | Perché | | --- | --- | --- | -| `3f9a1c2b-…` (un UUID) | `main` | Niente di leggibile da mantenere | -| Una lunga stringa di hex nuda | `main` | Stesso | -| `agent-3f9a1c2b-…` | `agent` | Id per-esecuzione strappato, parte leggibile mantenuta | -| `agent-v2` | `agent-v2` | Segmenti brevi vengono lasciati soli | -| `step-3` | `step-3` | Stesso | +| `3f9a1c2b-…` (un UUID) | `main` | Nulla di leggibile da conservare | +| Una lunga stringa hex nuda | `main` | Uguale | +| `agent-3f9a1c2b-…` | `agent` | Id per-esecuzione rimosso, parte leggibile conservata | +| `agent-v2` | `agent-v2` | Brevi segmenti sono lasciati soli | +| `step-3` | `step-3` | Uguale | -L'id reale viene mantenuto su `fw_agent_id` / `fw_run_id`, dove rimane interrogabile senza essere una facet. +L'id reale è conservato su `fw_agent_id` / `fw_run_id`, dove rimane interrogabile senza essere una sfaccettatura. - **Questo guard tocca solo le etichette che il *framework* ha scelto.** Un `agent_id` che passi tu stesso — a `event.*`, o a `failproofai_sdk.agent(...)` — viene registrato esattamente come dato. Riscrivere silenziosamente un argomento esplicito sarebbe peggio della cardinalità che previene, quindi nomina i tuoi span di conseguenza. + **Questa guardia tocca solo etichette che il *framework* ha scelto.** Un `agent_id` che passi tu stesso — a `event.*`, o a `failproofai_sdk.agent(...)` — è registrato esattamente come dato. Riscrivere silenziosamente un argomento esplicito sarebbe peggio della cardinalità che previene, quindi nomina i tuoi span di conseguenza. @@ -491,18 +491,18 @@ Quale framework registra cosa, misurato dalle esecuzioni sopra: | Inizio e fine dell'agente | Sì | Sì | Sì | Sì | Tu | | Richiesta e risposta del modello | Sì | Sì | Sì | Sì | Tu | | Uso e risultato dello strumento | Sì | Sì | Sì | Sì | Tu | -| Hook attivato e completato | Nodo | Compito | Step | — | Tu | +| Hook attivato e completato | Nodo | Attività | Passo | — | Tu | | Errore | Sì | Sì | Sì | Sì | Automatico | -| Attesa e input umano | Sì | Sì | Sì | — | Tu | +| Attesa umana e input | Sì | Sì | Sì | — | Tu | | Pausa e ripresa dell'agente | Sì | Sì | Sì | — | Tu | -Un trattino significa che il framework non ha un tale concetto. `human_pause` e `human_interrupt` descrivono una *persona* che agisce sull'agente, che nessun framework segnala — emetti quelli tu stesso. +Un trattino significa che il framework non ha un tale concetto. `human_pause` e `human_interrupt` descrivono una *persona* che agisce sull'agente, che nessun framework segnala — emettili tu stesso. -Un evento non arriva mai da solo. Uno apre uno span, uno lo chiude, e l'evento di chiusura porta una durata che l'SDK misura dal suo evento di apertura. +Un evento non arriva mai solo. Uno apre uno span, uno lo chiude, e l'evento di chiusura porta una durata che l'SDK misura dal suo evento di apertura. | Apre | Chiude | L'evento di chiusura porta | | --- | --- | --- | @@ -511,43 +511,43 @@ Un evento non arriva mai da solo. Uno apre uno span, uno lo chiude, e l'evento d | `tool_use` | `tool_result` | `output` o `error`, durata | | `hook_triggered` | `hook_completed` | `outcome`, durata | | `agent_pause` | `agent_resume` | quanto è durata la pausa | -| `human_wait` | `human_input` | la risposta, e quanto tempo ha impiegato la persona | +| `human_wait` | `human_input` | la risposta, e quanto tempo la persona ha impiegato | - Un evento di apertura senza uno di chiusura è uno span che non finisce mai. La sessione si mostra come ancora in esecuzione, per sempre, e la sua durata attiva continua a crescere. Questo è il modo di fallimento da guardare quando strumenti a mano. + Un evento di apertura senza uno di chiusura è uno span che non finisce mai. La sessione si rende come ancora in esecuzione, per sempre, e la sua durata attiva continua a crescere. Questo è il modo di fallimento da osservare quando strumenti a mano. #### Regole di correlazione - Riutilizza lo stesso `tool_call_id`, `hook_id`, `pause_id`, o `input_id` per l'evento di completamento corrispondente. -- L'SDK calcola `duration_ms` per `tool_result`, `hook_completed`, `agent_resume`, e `human_input`. Passarlo a quei metodi solleva `ValueError`. -- `duration_ms` **è** accettato su `model_response`, perché solo il chiamante conosce la vera latenza del provider. Deve essere un intero — un float solleva `ValueError` al sito di chiamata, perché il server legge la colonna come un intero senza segno a 32 bit e memorizzerebbe NULL per qualsiasi cosa. -- Le chiavi di correlazione sono scoped per genere e sessione, quindi una chiamata di strumento e un hook possono tranquillamente condividere un id, e due sessioni contemporanee possono riutilizzare gli stessi id senza collidere. Non sono scoped per agente: una coppia aperta sotto un agente e chiusa sotto un altro correla ancora, che è il caso ordinario nei framework multi-agente. -- `request_id` accoppia `model_request` con `model_response`. Senza di esso, gli eventi di modello si accopiano in ordine per agente, quindi le chiamate contemporanee si accopiano male. -- Una coppia divisa tra processi correla ancora downstream, ma l'SDK non può calcolarne la durata in-process. -- La mappa in sospeso contiene al massimo 10.000 avvii ed estrae l'entry più vecchia quando è piena. +- L'SDK calcola `duration_ms` per `tool_result`, `hook_completed`, `agent_resume`, e `human_input`. Passarlo a questi metodi genera `ValueError`. +- `duration_ms` **è** accettato su `model_response`, perché solo il chiamante conosce la vera latenza del provider. Deve essere un intero — un float genera `ValueError` al sito di chiamata, perché il server legge la colonna come un intero senza segno a 32 bit e memorizzerebbe NULL per qualsiasi cosa diversa. +- Le chiavi di correlazione sono scoped per genere e sessione, quindi una chiamata di strumento e un hook possono condividere un id in sicurezza, e due sessioni contemporanee possono riutilizzare gli stessi id senza collisioni. Non sono scoped per agente: una coppia aperta sotto un agente e chiusa sotto un altro ancora si correla, che è il caso ordinario nei framework multi-agente. +- `request_id` accoppia `model_request` con `model_response`. Senza di esso, gli eventi di modello si abbinano in ordine per agente, quindi le chiamate contemporanee si abbinano male. +- Una coppia divisa tra processi ancora si correla a valle, ma l'SDK non può calcolarne la durata in-processo. +- La mappa in sospeso contiene al massimo 10.000 avviamenti e elimina l'entry più vecchia quando è piena. - + -L'installazione di `failproofai-sdk` installa tutto, tutti e quattro gli adapter inclusi. Gli extra tirano il **framework**, non l'adapter. +Installare `failproofai-sdk` installa tutto, tutti e quattro gli adapter inclusi. Gli extra tirano il **framework**, non l'adapter. ```python -import failproofai_sdk # loads nothing outside the standard library -failproofai_sdk.instrument() # imports only the adapters you actually need +import failproofai_sdk # non carica nulla fuori dalla libreria standard +failproofai_sdk.instrument() # importa solo gli adapter che effettivamente usi ``` `import failproofai_sdk` è contrattualmente zero-dipendenza, applicato da un test che installa la wheel costruita con `--no-deps` e un altro che prova che nessun framework raggiunge `sys.modules`. - Non esiste un attributo `failproofai_sdk.crewai`. Gli adapter sono deliberatamente non esposti sul pacchetto di primo livello: toccarne uno importerebbe il framework come effetto collaterale di un accesso dell'attributo, rompendo la promessa zero-dipendenza. Usa `instrument()`. + Non c'è un attributo `failproofai_sdk.crewai`. Gli adapter sono deliberatamente non esposti sul package di livello superiore: toccare uno importerebbe il framework come effetto collaterale di un accesso agli attributi, rompendo la promessa di zero-dipendenza. Usa `instrument()`. ```python -failproofai_sdk.instrument() # every framework already imported -failproofai_sdk.instrument("crewai") # exactly one, by name -failproofai_sdk.uninstrument("crewai") # put it back +failproofai_sdk.instrument() # ogni framework già importato +failproofai_sdk.instrument("crewai") # esattamente uno, per nome +failproofai_sdk.uninstrument("crewai") # rimettilo come era ``` | Nome | Accetta anche | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # put it back | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -L'auto-rilevamento legge `sys.modules`, non l'elenco dei pacchetti installati, quindi un framework che hai installato ma mai importato non viene strumentato e non viene mai importato per tuo conto. Per vedere cosa è cablato: +L'auto-rilevamento legge `sys.modules`, non l'elenco dei pacchetti installati, quindi un framework che hai installato ma mai importato non è strumentato e non è mai importato per tuo conto. Per vedere cosa è collegato: ```python from failproofai_sdk.integrations import active, available @@ -567,46 +567,46 @@ active() # ('langchain',) ``` - **`instrument("crewai")` su una macchina senza CrewAI non solleva.** Registra un avviso e restituisce `()`, quindi un framework mancante non porta mai giù un processo che strumenta anche altri. + **`instrument("crewai")` su una macchina senza CrewAI non genera.** Registra un avviso e restituisce `()`, quindi un framework mancante non fa mai cadere un processo che strumenta anche altri. - L'avviso porta l'`ImportError` sottostante, e quel messaggio nomina il comando di installazione esatto — quindi la correzione è nei tuoi log, non nascosta. + L'avviso porta il sottostante `ImportError`, e quel messaggio nomina il comando di installazione esatto — così la correzione è nei tuoi log, non nascosta. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Imposta `FAILPROOFAI_SDK_STRICT=1` per farlo sollevare invece. Quel flag viene letto **una volta e cachato**, quindi esportalo prima che il tuo processo inizi piuttosto che impostarlo a metà esecuzione. + Imposta `FAILPROOFAI_SDK_STRICT=1` affinché generi al contrario. Quel flag è letto **una sola volta e cachato**, quindi esportalo prima che il tuo processo inizi anziché impostarlo mid-run. - **`instrument()` deve venire *dopo* l'importazione del tuo framework.** L'auto-rilevamento legge `sys.modules`, quindi una chiamata nuda sopra l'importazione non trova niente, non installa niente, e restituisce `()`. + **`instrument()` deve venire *dopo* il tuo import del framework.** L'auto-rilevamento legge `sys.modules`, quindi una chiamata nuda sopra l'import trova nulla, installa nulla, e restituisce `()`. ```python Sbagliato import failproofai_sdk -failproofai_sdk.instrument() # sys.modules has no langchain yet -> () +failproofai_sdk.instrument() # sys.modules non ha langchain ancora -> () -import langchain # too late, nothing is wired +import langchain # troppo tardi, nulla è cablato ``` ```python Giusto -import langchain # import the framework first +import langchain # importa il framework per primo import failproofai_sdk -failproofai_sdk.instrument() # finds it -> ('langchain',) +failproofai_sdk.instrument() # lo trova -> ('langchain',) ``` -```python Giusto, a prova di ordine +```python Giusto, order-proof import failproofai_sdk -# Naming it imports the adapter on request, so this works from anywhere. +# Nominarlo importa l'adapter su richiesta, quindi questo funziona da qualsiasi parte. failproofai_sdk.instrument("langchain") ``` -Sbaglialo e il processo gira con l'SDK importato, l'adapter apparentemente installato, e **non un evento emesso**. Registra un avviso dicendo esattamente questo — quindi controlla prima i tuoi log quando un'esecuzione non registra niente. +Fai male e il processo viene eseguito con l'SDK importato, l'adapter apparentemente installato, e **nemmeno un evento emesso**. Registra un avviso dicendo esattamente quello — quindi controlla i tuoi log per primo quando un'esecuzione non registra nulla. @@ -614,83 +614,85 @@ Sbaglialo e il processo gira con l'SDK importato, l'adapter apparentemente insta ```mermaid flowchart LR - A["Your agent"] --> B["Adapter"] - B --> C["Writer
in-memory queue"] - C -->|"every 0.5s"| D["Spool
JSONL on disk"] - D --> E["Failproof daemon"] + A["Il tuo agente"] --> B["Adapter"] + B --> C["Writer
coda in-memoria"] + C -->|"ogni 0.5s"| D["Spool
JSONL su disco"] + D --> E["Daemon Failproof"] E -->|"HTTPS"| F["Cloud"] ``` -| Fase | Lavoro | Gira in | +| Fase | Compito | Eseguita in | | --- | --- | --- | | Adapter | Traduce un callback del framework in uno dei 15 tipi di evento | Il tuo processo | -| Writer | Coda, batch, scrive JSONL atomicamente | Il tuo processo, thread di background | -| Spool | Consegna durabile, sopravvive all'uscita del tuo processo | Disco locale | -| Daemon | Osserva lo spool, spedisce i batch, cancella quello che ha spedito | La tua macchina | -| Ingest | Assegna un id di riga e chiave dedup, promuove colonne interrogabili | Cloud | +| Writer | Accoda, raggruppa, scrive JSONL atomicamente | Il tuo processo, thread di background | +| Spool | Consegna duratura, sopravvive all'uscita del tuo processo | Disco locale | +| Daemon | Guarda lo spool, spedisce batch, cancella quello che ha spedito | La tua macchina | +| Ingest | Assegna un id riga e dedup key, promuove colonne interrogabili | Cloud | -Lo spool è quello che rende questo sicuro: il tuo agente non blocca mai sulla rete, e un'interruzione di Cloud significa una directory in crescita piuttosto che eventi persi. +Lo spool è quello che rende questo sicuro: il tuo agente non si blocca mai sulla rete, e un'interruzione di Cloud significa una directory in crescita anziché eventi persi. -Ogni flush scrive un file batch, `.tmp` prima, poi `fsync`, poi una ridenominazione atomica: +Ogni flush scrive un file batch, `.tmp` per primo, poi `fsync`, poi un rename atomico: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Il daemon raccoglie solo `.jsonl`, quindi non può mai leggere un file mezzo scritto. Lo stem porta un timestamp, id processo e numero di sequenza, quindi due processi che fanno flush nello stesso millisecondo non possono collidere. La coda è limitata a 10.000 eventi; oltre quello cancella il più vecchio e registra. +Il daemon raccoglie solo `.jsonl`, quindi non può mai leggere un file scritto a metà. Lo stem porta un timestamp, id processo e numero di sequenza, quindi due processi che flushano nello stesso millisecondo non possono collisioni. La coda è limitata a 10.000 eventi; passato questo i più vecchi sono scartati e registrati. - **`collector.redact` predefinisce a `minimal` anche per gli eventi SDK.** L'SDK scrappa prima di scrivere un batch su disco, e il daemon ripete lo stesso passaggio deterministico prima dell'upload così i batch da SDK più vecchi sono protetti. + **`collector.redact` non si applica ai tuoi eventi SDK.** Non li vede mai. -Il daemon legge ogni batch e applica la redazione in memoria prima dell'upload. Non riscrittore il file spool che ha letto. +Il daemon **spedisce** i tuoi batch. Non li apre o li riscrive. -| Eventi | Scritti da | Dove gira la redazione minima | +| Eventi | Scritti da | Redatti da `collector.redact`? | | --- | --- | --- | -| Trascritti di sessione CLI | Il daemon | Prima che il daemon scriva il batch | -| Attività hook | Il daemon | Prima che il daemon scriva il batch | -| **Tutto quello che emette l'SDK** | **Il tuo processo** | **Prima che l'SDK scriva il batch e di nuovo prima dell'upload del daemon** | +| Trascritti di sessione CLI | Il daemon | Sì | +| Attività hook | Il daemon | Sì | +| **Tutto ciò che l'SDK emette** | **Il tuo processo** | **No** | -Imposta `collector.redact` su `off` solo quando i payload verbatim sono un requisito esplicito; sia l'SDK che il daemon onorano quell'impostazione. La redazione minima cattura chiavi API comuni, token bearer, JWT e assegnazioni segrete. Non può identificare prosa sensibile arbitraria. +La redazione viene eseguita dove il daemon *scrive* i suoi propri eventi — non dove i batch sono *spediti*. Quindi un prompt o un argomento di strumento che tiene una chiave API ancora la tiene all'arrivo. + +È deliberato. Queste sono le tue stesse chiamate di strumentazione, e riscriverle in transito significherebbe che gli eventi che ricevi non sono gli eventi che hai emesso. - **Controlli i payload alla fonte, in due posti:** + **Controlli i payload alla sorgente, in due posti:** - - Disattiva l'acquisizione di contenuti sull'adapter. **Il nome dell'opzione differisce, e un adapter non ne ha nessuno** — questo non è un singolo interruttore universale: + - Spegni la cattura di contenuto sull'adapter. **Il nome dell'opzione differisce, e un adapter non ne ha alcuno** — non è un singolo interruttore universale: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **nessuno switch di contenuto**; `session_id` è l'unica opzione che legge, quindi i prompt e i completamenti vengono sempre registrati. + - CrewAI — **nessuno switch di contenuto**; `session_id` è l'unica opzione che legge, quindi i prompt e i completamenti sono sempre registrati. - `instrument()` elimina le opzioni che un adapter non legge, quindi passare il nome sbagliato non solleva niente e non cambia niente. + `instrument()` scarta le opzioni che un adapter non legge, quindi passare il nome sbagliato non genera nulla e non cambia nulla. - Non consegnare il segreto a `input=` in primo luogo. - `collector.redact` è difesa in profondità, non un sostituto per nessuno dei due. + `collector.redact` non è un sostituto per nessuno dei due. - **Una directory spool vuota è lo stato sano.** Non usarla per controllare la consegna. + **Una directory spool vuota è lo stato salutistico.** Non usarla per controllare la consegna. -Il daemon cancella ogni batch entro millisecondi dal suo invio, quindi un `ls` gara il collettore e mostra una frazione di quello che hai emesso — indistinguibile da un SDK che non ha registrato niente. +Il daemon cancella ogni batch entro millisecondi dalla sua spedizione, quindi un `ls` corre il collector e mostra una frazione di ciò che hai emesso — indistinguibile da un SDK che non ha registrato nulla. -Per confermare che gli eventi sono effettivamente arrivati, controlla la dashboard. Per guardare lo spool riempirsi, ferma il daemon prima. +Per confermare che gli eventi effettivamente atterrano, controlla il dashboard. Per osservare lo spool riempirsi, ferma prima il daemon. -Ogni callback gira dentro un wrapper il cui unico lavoro è ri-sollevare, quindi la tua chiamata si trova in esattamente uno `try` e tutto quello che l'SDK fa accade fuori da esso. +Ogni callback viene eseguito dentro un wrapper il cui unico compito è lanciare di nuovo, quindi la tua chiamata sta esattamente in un `try` e tutto ciò che l'SDK fa accade al di fuori di esso. | Cosa succede | Risultato | | --- | --- | -| Un hook solleva | Registrato una volta con il suo traceback. La tua chiamata non è interessata | -| Lo stesso hook solleva tre volte | Quell'hook è disabilitato per il resto del processo, con una riga di errore | -| `FAILPROOFAI_SDK_STRICT=1` è impostato | L'eccezione viene ri-sollevata invece | -| Una versione del framework è fuori dall'intervallo testato | Avverte una volta, strumenta comunque | +| Un hook genera | Registrato una volta con il suo traceback. La tua chiamata non è interessata | +| Lo stesso hook genera tre volte | Quell'hook è disabilitato per il resto del processo, con una riga di errore | +| `FAILPROOFAI_SDK_STRICT=1` è impostato | L'eccezione è lanciata di nuovo al contrario | +| Una versione di framework è fuori dall'intervallo testato | Avvisa una volta, strumenta comunque | | Una singola capacità è mancante | Quell'hook è disabilitato, mai l'intero adapter | -L'impostazione predefinita è giusta in produzione e sbagliata durante il debug, perché può solo mai provare il non-crash. Imposta `FAILPROOFAI_SDK_STRICT=1` per rendere forte un fallimento ingoiato. +Il default è giusto in produzione e sbagliato mentre esegui il debug, perché può solo mai provare "non è crashato". Imposta `FAILPROOFAI_SDK_STRICT=1` per rendere un fallimento ingoiato rumoroso. @@ -700,27 +702,27 @@ L'impostazione predefinita è giusta in produzione e sbagliata durante il debug, - Un evento di apertura non ha uno di chiusura: un `model_request` senza `model_response`, o un `tool_use` senza `tool_result`. Usa gli ambiti, che garantiscono la coppia anche quando il corpo solleva. Se chiami i metodi di evento direttamente, usa `try` e `finally`. + Un evento di apertura non ha uno di chiusura: un `model_request` senza `model_response`, o un `tool_use` senza `tool_result`. Usa gli ambiti, che garantiscono la coppia anche quando il corpo genera. Se chiami i metodi evento direttamente, usa `try` e `finally`. - - Viene misurato dal suo evento di apertura corrispondente, quindi viene rifiutato su `tool_result`, `hook_completed`, `agent_resume`, e `human_input`. Viene accettato su `model_response`, perché solo tu conosci la vera latenza del provider, e deve essere un intero. + + È misurato dall'evento di apertura corrispondente, quindi è rifiutato su `tool_result`, `hook_completed`, `agent_resume`, e `human_input`. È accettato su `model_response`, perché solo tu conosci la vera latenza del provider, e deve essere un intero. - - Il thread non ha mai ereditato il contesto. Avvolgi il callable in `failproofai_sdk.propagate()`. Vedi [Thread e async](#threads-and-async). + + Il thread non ha mai ereditato il contesto. Avvolgi il callable in `failproofai_sdk.propagate()`. Vedi [Thread e async](#thread-e-async). - I campi extra si uniscono per ultimo, quindi uno nominato come un campo reale come `model` o `outcome` lo sovrascrivererebbe e cambierebbe una colonna memorizzata. Usa uno spazio dei nomi; gli adapter usano un prefisso `fw_`. + I campi extra si fondono ultimi, quindi uno denominato come un campo reale come `model` o `outcome` lo sovrascriverebbe e cambierebbe una colonna memorizzata. Spazianomina i tuoi; gli adapter usano un prefisso `fw_`. - `agent_id` è una facet a bassa cardinalità e tu hai messo un id di esecuzione in esso. Usa un ruolo o nome di nodo e metti l'id reale in un campo payload. + `agent_id` è una sfaccettatura a bassa cardinalità e ci hai messo un id di esecuzione. Usa un nome di ruolo o nodo e metti l'id reale in un campo di payload. -## Prossimo +## Avanti @@ -729,7 +731,7 @@ L'impostazione predefinita è giusta in produzione e sbagliata durante il debug, Segui la causalità attraverso la sessione che hai appena catturato. - + LangGraph, CrewAI, LlamaIndex, e Pydantic AI. \ No newline at end of file diff --git a/docs/it/start/quickstart.mdx b/docs/it/start/quickstart.mdx index 067df316..e293d2e8 100644 --- a/docs/it/start/quickstart.mdx +++ b/docs/it/start/quickstart.mdx @@ -1,17 +1,17 @@ --- -title: "Guida rapida" -description: "Acquisisci una sessione di agente, identifica un errore e inizia a prevenirlo." +title: "Guida introduttiva" +description: "Acquisisci una sessione di agente, trova un errore e inizia a prevenirlo." icon: "zap" --- -Questa guida rapida configura una macchina per la segnalazione delle sessioni, esegue un audit e distribuisce una policy. Utilizza lo skill per configurare Failproof, oppure segui i passaggi manuali. +Questa guida introduttiva configura una macchina per segnalare sessioni, esegue un audit e distribuisce una policy. Usa la skill per configurare Failproof AI, oppure segui i passaggi manuali. -**Quale percorso è il tuo?** Se il tuo agente viene eseguito in uno dei 12 [harness](/it/reference/harnesses) supportati — una CLI di codifica o un gateway come Hermes oppure OpenClaw — segui i passaggi di seguito; hai bisogno di Node.js 20.9 o successivo. Se il tuo agente non dispone di harness, strumentalo con [Python SDK](/it/reference/custom-agents) per il tracing e gli audit, quindi torna a [Esegui il tuo primo controllo degli errori](/it/start/first-audit); l'enforcement su quel percorso richiede un hook nel tuo runtime. +**Quale percorso è il tuo?** Se il tuo agente funziona in uno dei 12 [harness](/it/reference/harnesses) supportati — una CLI di coding o un gateway come Hermes o OpenClaw — segui i passaggi seguenti; hai bisogno di Node.js 20.9 o versioni successive. Se il tuo agente non ha un harness, strumentalo con [Python SDK](/it/reference/custom-agents) per il tracing e gli audit, quindi unisciti a [Esegui il tuo primo controllo di errore](/it/start/first-audit); l'enforcement su quel percorso richiede un hook nel tuo runtime. - + - + ```bash npx skills add FailproofAI/skills ``` @@ -21,19 +21,19 @@ Questa guida rapida configura una macchina per la segnalazione delle sessioni, e Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Il tuo agente ispeziona il progetto, sceglie l'integrazione rilevante, esegue la configurazione e la verifica. Consulta il [repository degli skill FailproofAI](https://github.com/FailproofAI/skills) per gli skill individuali e le opzioni di installazione avanzate. + Il tuo agente ispeziona il progetto, sceglie l'integrazione rilevante, esegue la configurazione e la verifica. Consulta il [repository delle skill FailproofAI](https://github.com/FailproofAI/skills) per le skill individuali e le opzioni di installazione avanzate. ## Prima di iniziare -1. Apri il [dashboard di Failproof AI](https://app.befailproof.ai) e crea un account oppure accedi con la tua email di lavoro. +1. Apri il [dashboard Failproof AI](https://app.befailproof.ai) e crea un account o accedi con la tua email aziendale. 2. Vai a **Administration → Keys** e crea una chiave con `events:add` e `policies:pull`. -3. Copia il segreto monouso e salvalo sulla macchina di destinazione: +3. Copia il segreto monouso, quindi leggilo in una shell sulla macchina di destinazione. `read -s` lo accetta da un prompt che non viene visualizzato, quindi non appare mai in un comando: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## Installa @@ -42,12 +42,18 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - I trascritti delle sessioni vengono inviati per impostazione predefinita. Aggiungi `--no-transcripts` per segnalare l'attività dell'hook e le decisioni delle policy senza il contenuto del trascritto. + Un unico comando completa tutta la configurazione: installa il daemon locale (root una volta), collega i hook in ogni CLI di agente che trova e connette questa macchina al Cloud. Passare la chiave attraverso l'ambiente piuttosto che tramite `--token` la mantiene fuori da `ps`, dove ogni utente della macchina può leggere gli argomenti di un comando. Non la mantiene fuori dalla cronologia della shell — leggerla con `read -s` è quello che lo fa. In CI, inettala come segreto mascherato e mantieni il tracing della shell (`set -x`) disattivato, altrimenti la traccia la stampa. - Se questa macchina dispone già di cronologia degli agenti, visualizza in anteprima e importa gli ultimi sette giorni, quindi attendi il completamento della consegna. Salta questo passaggio su una macchina nuova. + Le trascrizioni delle sessioni vengono inviate per impostazione predefinita. Aggiungi `--no-transcripts` per segnalare l'attività degli hook e le decisioni sulle policy senza il contenuto della trascrizione. + + + Non usare `failproofai config --connect ` qui. Quel flag iscrive una macchina che è **già** configurata e ritorna subito — nessun daemon, nessun hook — quindi la macchina apparirebbe nel Cloud senza raccogliere e applicare nulla. + + + Se questa macchina ha già una cronologia di agenti, visualizza in anteprima e importa gli ultimi sette giorni, quindi attendi il completamento della consegna. Salta questo passaggio su una nuova macchina. ```bash failproofai backfill --since 7d --dry-run @@ -57,28 +63,39 @@ export FAILPROOFAI_KEY="" Apri **Sessions** in Failproof AI e seleziona una sessione importata. - - Questo collega Failproof AI al tuo harness e installa le 39 policy built-in. Utilizzale per visualizzare le decisioni delle policy locali e provare l'enforcement prima che Failproof AI auditi le tue sessioni e scritti le policy per i tuoi agenti. - - Consenti al programma di installazione di rilevare il tuo harness oppure denominarne uno in modo esplicito. Ognuno dei 12 è un valore `--cli` valido — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + Il passaggio precedente ha già collegato ogni CLI di agente rilevata. Eseguilo nuovamente per un harness esplicitamente quando necessario, o per aggiungere un harness installato successivamente. Ognuno dei 12 è un valore `--cli` valido — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - Il blocco di una chiamata di strumento prima dell'esecuzione è verificato su tutti i 12. I gate di fine turno sono verificati su 8 — consulta [enforcement capability](/it/reference/harnesses#enforcement-capability) per la matrice per harness. + Il blocco di una chiamata di tool prima che venga eseguita è verificato su tutti i 12. I gate di fine turno sono verificati su 8 — consulta [enforcement capability](/it/reference/harnesses#enforcement-capability) per la matrice per harness. + + + Il collegamento dei hook non abilita alcuna policy. La configurazione deliberatamente non ne sceglie nessuna — quella decisione è tua — quindi prendi un pacchetto: + + ```bash + failproofai policies add FailproofAI/policies + ``` + + Il pacchetto viene recuperato dal suo rilascio GitHub, verificato con checksum e bloccato al tag esatto in cui è stato risolto. Contiene 38 policy e attiva le 10 che il suo manifest contrassegna come sicure da abilitare in modo non presidiato. Usale per vedere le decisioni delle policy locali e provare l'enforcement prima che Failproof AI auditi le tue sessioni e scriva policy per i tuoi agenti. + + Leggi qualsiasi pacchetto prima di prenderlo con `failproofai policies show /`, e consulta [policy packs](/it/policies/packs) per prendere solo parte di uno. + + Finché questo non viene eseguito, l'unica cosa che applica è `block-failproofai-commands` — la guardia sempre attiva che impedisce a un agente di disattivare Failproof AI. `failproofai policies` elenca cosa è attivo. - - Segui [Esegui il tuo primo controllo degli errori](/it/start/first-audit). Utilizza un obiettivo concreto come "trovare sessioni in cui l'agente ha ritentato uno strumento che non funzionava senza modificare il suo approccio." + + Segui [Esegui il tuo primo controllo di errore](/it/start/first-audit). Usa un obiettivo concreto come trovare sessioni in cui l'agente ha ritentato un tool non riuscito senza cambiare il suo approccio. - Segui [Previeni il tuo primo errore con una policy](/it/start/first-policy). Inizia in modalità osservazione, ispeziona le corrispondenze, quindi applica la versione revisionata. + Segui [Previeni il tuo primo errore con una policy](/it/start/first-policy). Inizia in modalità osservazione, ispeziona le corrispondenze, quindi applica la versione rivista. - Esegui `failproofai config --status`. Una configurazione integra segnala la connessione cloud, lo stato del daemon e se l'enforcement è in pausa. + Esegui `failproofai config --status`. Una configurazione corretta segnala la connessione cloud, lo stato del daemon e se l'enforcement è in pausa. \ No newline at end of file diff --git a/docs/it/start/setup.mdx b/docs/it/start/setup.mdx index 62fb7a4c..3a17ebfc 100644 --- a/docs/it/start/setup.mdx +++ b/docs/it/start/setup.mdx @@ -1,68 +1,89 @@ --- title: "Scegli la tua configurazione" -description: "Scegli tra applicazione locale, Failproof AI Cloud o un deployment enterprise." +description: "Scegli l'applicazione locale, Failproof AI Cloud, o un deployment aziendale." icon: "waypoints" --- - Installa hook e policy su una macchina. Usa questa opzione quando hai bisogno di protezioni immediate senza inviare i dati della sessione al Cloud. + Configura una macchina senza una chiave Cloud e scegli un policy pack. Usa questa opzione quando hai bisogno di protezioni immediate senza inviare i dati della sessione a Cloud. - Aggiungi sessioni centralizzate, audit, valutazioni online, dashboard, avvisi e deployment di policy su flotta. + Aggiungi sessioni centralizzate, audit, valutazioni online, dashboard, avvisi e deployment delle policy su flotta. - Usa i controlli organizzativi, chiavi scoped, infrastruttura privata e requisiti di sicurezza specifici del deployment. + Utilizza controlli organizzativi, chiavi scoped, infrastruttura privata e requisiti di sicurezza specifici del deployment. +## Applicazione locale + +Esegui `failproofai config` senza una chiave, quindi scegli un pack con `failproofai policies add FailproofAI/policies`. In un terminale, seleziona **Not now — stay local** quando la configurazione chiede di connettersi a Cloud; senza terminale e senza `FAILPROOFAI_CLOUD_TOKEN`, rimane locale automaticamente. Il daemon e i hook applicano le policy sulla macchina, e nessun dato di sessione viene inviato a Cloud. Per connetterti in seguito, segui i passaggi sotto. + ## Percorso di produzione consigliato -1. Collega una macchina non in produzione con acquisizione di transcript abilitata. +1. Connetti una macchina non di produzione con l'acquisizione dei transcript abilitata. 2. Verifica le sessioni e le valutazioni in Cloud. 3. Crea un audit per una modalità di errore nota. 4. Distribuisci la prima policy in modalità observe. -5. Espandi a produzione dopo aver rivisto i match e i falsi positivi. +5. Espandi alla produzione dopo aver revisionato i match e i falsi positivi. -## Collega una macchina al Cloud +## Connetti una macchina a Cloud - 1. Vai su **Administration → Keys** e crea una chiave con `events:add` e `policies:pull`. - 2. Copia il secret monouso sulla macchina di destinazione. - 3. Dopo aver eseguito il comando di connessione della CLI, vai su **Admin → enforcement** e conferma che la macchina appare. - 4. Vai su **Observe → Events** e conferma che il suo primo evento arriva. + 1. Vai a **Administration → Keys** e crea una chiave con i permessi `events:add` e `policies:pull`. + 2. Copia il segreto monouso sulla macchina target. + 3. Dopo aver eseguito il comando CLI di connessione, vai a **Admin → enforcement** e conferma che la macchina appare. + 4. Vai a **Observe → Events** e conferma che il suo primo evento è arrivato. - Il drawer delle chiavi mostra i due grant necessari a una macchina connessa: acquisizione di eventi e consegna di policy. + Il drawer delle chiavi mostra i due permessi necessari a una macchina connessa: ingestione degli eventi e consegna delle policy. - ![Il nuovo drawer della chiave API utilizzato per concedere i permessi di acquisizione di eventi e consegna di policy.](/images/dashboard/key-create.png) + ![Il nuovo drawer delle chiavi API utilizzato per concedere i permessi di ingestione degli eventi e consegna delle policy.](/images/dashboard/key-create.png) - Dopo la connessione, la macchina dovrebbe apparire in enforcement con lo stato desiderato e quello segnalato della policy. + Dopo la connessione, la macchina dovrebbe apparire in enforcement con lo stato delle policy desiderato e quello riportato. - ![La flotta Enforcement con una macchina registrata espansa per mostrare lo stato desiderato della policy e lo stato del deployment.](/images/dashboard/enforcement-fleet.png) + ![La flotta Enforcement con una macchina registrata espansa per mostrare lo stato della policy desiderato e lo stato del deployment.](/images/dashboard/enforcement-fleet.png) - Il primo evento in arrivo conferma che il daemon può consegnare i dati al Cloud, indipendentemente dal deployment della policy. + Il primo evento arrivato conferma che il daemon può consegnare i dati a Cloud, indipendentemente dal deployment della policy. - ![Lo stream di eventi live che mostra i recenti eventi di agent, model e tool.](/images/dashboard/events-stream-current.png) + ![Lo stream degli eventi live che mostra gli eventi recenti di agent, model e tool.](/images/dashboard/events-stream-current.png) - Continua solo dopo che sia la macchina che il suo primo evento sono visibili. + Continua solo dopo che la macchina e il suo primo evento sono visibili. + Leggi il segreto monouso nella shell. `read -s` lo prende da un prompt che non rispecchia, in modo che non appaia mai in un comando o nella cronologia della shell: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Quindi configura la macchina, scegli le sue policy e assegnale un nome: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` - Aggiungi `--no-transcripts` quando il contenuto del transcript deve rimanere locale. + `failproofai config` esegue l'intera configurazione — daemon, hook per ogni CLI di agent che trova, e la connessione a Cloud — quindi non sceglie alcuna policy, per questo serve il secondo comando. + + L'etichetta viene **dopo** la connessione, non durante: `failproofai config --machine-label ` rinomina una macchina già connessa, e su una che non lo è non fa nulla se non comunicarlo. + + Aggiungi `--no-transcripts` quando il contenuto dei transcript deve rimanere locale. + + In CI, imposta `FAILPROOFAI_CLOUD_TOKEN` dal secret store invece di `read -s`, e mantieni il tracing della shell (`set -x`) disattivato, altrimenti il trace stampa la chiave. + + + Su una macchina **già** configurata, `failproofai config --connect ` la registra e nient'altro. Non usare questa forma per una prima installazione: ritorna prima che il daemon o qualsiasi hook sia in posizione, lasciando una macchina che appare in Cloud ma non raccoglie né applica nulla. + -La connessione al Cloud verifica l'acquisizione di eventi e la consegna di policy in modo indipendente. Una chiave può quindi essere valida ma priva di un permesso necessario. Usa `failproofai config --status` per vedere quale capacità è configurata. +La connessione a Cloud verifica l'ingestione degli eventi e la consegna delle policy indipendentemente. Una chiave potrebbe quindi essere valida ma priva di un permesso richiesto. Usa `failproofai config --status` per vedere quale capacità è configurata. - La configurazione del Cloud scrive le credenziali locali solo dopo il successo della capacità rilevante. Una verifica fallita non lascia una macchina che appaia connessa quando in realtà non lo è. + La configurazione di Cloud scrive le credenziali locali solo dopo che la capacità rilevante ha avuto successo. Una verifica fallita non lascia una macchina che sembra connessa quando non lo è. \ No newline at end of file diff --git a/docs/ja/admin/keys-and-permissions.mdx b/docs/ja/admin/keys-and-permissions.mdx index 5afb0ab8..4e6c572c 100644 --- a/docs/ja/admin/keys-and-permissions.mdx +++ b/docs/ja/admin/keys-and-permissions.mdx @@ -4,26 +4,26 @@ description: "マシン、自動化、オペレーター向けにスコープ付 icon: "key-round" --- -APIキーは組織に属し、明示的な権限を持ちます。エージェントのインジェスト、ポリシーの配信、評価者、CI自動化、管理スクリプトにはそれぞれ別のキーを使用してください。 +APIキーは組織に属し、明示的な権限を持ちます。エージェントの取り込み、ポリシーの配信、評価者、CI自動化、および管理スクリプトには、それぞれ個別のキーを使用してください。 ## キーの作成とローテーション - 1. **Administration → Keys** に移動し、**new key** を選択してワークロード名を入力します。 + 1. **管理 → キー** に移動し、**新しいキー** を選択してワークロード名を入力します。 2. 権限セットを選択し、プリセットが不十分な場合のみ個別の権限を調整します。 - 3. キーを作成し、一度限りのシークレットをすぐにコピーします。 - 4. 後でキーを開いて権限の更新、無効化、またはシークレットの再生成を行います。 + 3. キーを作成し、ワンタイムシークレットをすぐにコピーします。 + 4. 後でキーを開いて、権限の更新、無効化、またはシークレットの再生成を行います。 - 作成ドロワーでは、ワークロードに必要な最小限の権限を選択します。 + 作成ドロワーは、ワークロードに必要な最小限の権限を選択する場所です。 - ![権限プリセットと個別の権限が表示された新しいAPIキードロワー。](/images/dashboard/key-create.png) + ![権限プリセットと個別の権限設定が表示された新規APIキー作成ドロワー。](/images/dashboard/key-create.png) - 作成後、Keysページには永続的なメタデータと管理操作が表示されます。一度限りのシークレットは再表示されません。 + 作成後、キーページには永続的なメタデータと管理アクションが表示されます。ワンタイムシークレットは再表示されません。 ![キーの権限、作成日時、再生成および無効化アクションが表示されたAPIキーページ。](/images/dashboard/api-keys.png) - このリストを定期的に確認し、アクティブなワークロードに対応しなくなったキーを無効化してください。 + このリストを定期的に確認して権限を見直し、アクティブなワークロードに対応しなくなったキーを無効化してください。 ```bash @@ -36,39 +36,39 @@ APIキーは組織に属し、明示的な権限を持ちます。エージェ fp keys disable production-agents ``` - シークレットは一度だけ返されるため、create/regenerateの出力を安全にリダイレクトまたはキャプチャしてください。 + 作成・再生成の出力はリダイレクトするか安全にキャプチャしてください。シークレットは一度だけ返されます。 -接続された Failproof AI マシンに必要な2つの権限は独立しています。 +接続された Failproof AI マシンが必要とする2つの権限は独立しています。 - `events:add` はイベントとセッションデータを送信します。 - `policies:pull` は割り当てられたポリシーのデプロイメントを取得します。 -キーのシークレットは作成時または再生成時に表示されます。シークレットマネージャーに保存し、オペレーターのインタラクティブな認証情報を再利用せずにローテーションしてください。 +キーのシークレットは、作成時または再生成時にのみ表示されます。シークレットマネージャーに保存し、オペレーターのインタラクティブな認証情報を再利用せずにローテーションしてください。 ## 権限カタログ | エリア | 権限 | | --- | --- | -| Events | `events:add`, `events:read` | -| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` はヒューマンセッション専用 | -| Users | `users:create`, `users:read`, `users:update`, `users:delete` | -| Evaluations | `evaluations:read`, `evaluations:trigger` | -| Dashboards | `dashboards:read`, `dashboards:write`, `dashboards:delete` | -| Queries | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | -| Assistant | `agent:use` | -| Settings | `settings:read`, `settings:write` | -| Alerts | `alerts:read`, `alerts:write` | -| Issues | `issues:read`, `issues:create`, `issues:close` | -| Audits | `audits:read`, `audits:write` | -| Policies | `policies:read`, `policies:write`, `policies:pull` | -| Usage | `usage:read` | - -`orgs:admin` はインスタンスオペレーター専用であり、組織キーや一般メンバーには付与できません。廃止された `incidents:*` および `alerts:ack` トークンは互換性のために受け入れられ、現在の `issues:*` 権限に正規化されます。 - -組み込みの権限セットは `read-only`、`standard`、`admin` の3種類です。`standard` は読み取り権限に加え、評価のトリガー、クエリの実行、イシューへの対応、アシスタントの使用が追加されます。キーの作成時には、権限セットに含まれていても人間専用の権限は除外されます。 +| イベント | `events:add`, `events:read` | +| キー | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` はヒューマンセッション専用 | +| ユーザー | `users:create`, `users:read`, `users:update`, `users:delete` | +| 評価 | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | +| ダッシュボード | `dashboards:read`, `dashboards:write`, `dashboards:delete` | +| クエリ | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | +| アシスタント | `agent:use` | +| 設定 | `settings:read`, `settings:write` | +| アラート | `alerts:read`, `alerts:write` | +| イシュー | `issues:read`, `issues:create`, `issues:close` | +| 監査 | `audits:read`, `audits:write` | +| ポリシー | `policies:read`, `policies:write`, `policies:pull` | +| 使用量 | `usage:read` | + +`orgs:admin` はインスタンスオペレーター専用に予約されており、組織キーや一般メンバーには付与できません。廃止された `incidents:*` および `alerts:ack` トークンは互換性のために受け付けられ、現在の `issues:*` 権限に正規化されます。 + +組み込みの権限セットは `read-only`、`standard`、`admin` です。`standard` は読み取り権限に加えて、評価のトリガー、クエリの実行、イシュー対応、アシスタントの使用が追加されます。キーの作成時には、権限セットにヒューマン専用の権限が含まれていても自動的に除外されます。 - インスタンススコープのキーは、`X-AgentEye-Org` ヘッダーで組織を選択できます。マルチ組織デプロイメントでは明示的に設定してください。省略するとデフォルト組織が選択される場合があります。 + インスタンススコープのキーは、`X-AgentEye-Org` ヘッダーで組織を選択できます。複数組織のデプロイメントでは明示的に設定してください。省略すると、デフォルトの組織が選択される場合があります。 \ No newline at end of file diff --git a/docs/ja/evaluations/deploy.mdx b/docs/ja/evaluations/deploy.mdx new file mode 100644 index 00000000..4290a719 --- /dev/null +++ b/docs/ja/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "評価のデプロイとバージョン管理" +description: "不変バージョンのデプロイ、ライブ中の内容の確認、新バージョンの公開、ロールバック、既存セッションのスコアリング。" +icon: "cloud-upload" +--- + +## デプロイする + +オーサリングページの下部にある **deploy `@`** を選択します。バージョンは一度公開すると変更できません。以降、完了したすべてのセッションのうち、条件に該当するものがこのバージョンによってスコアリングされます。 + +## ライブ中の内容を確認する + +**Analyze → eval authoring** には、組織がホストしている定義（マネージド評価者が実行する評価）の一覧が表示されます。各行には次の情報が含まれます。 + +- 名前、キー、バージョン、結果タイプ +- ソースチェックサム（コードを開かずにデプロイ済みリビジョンを識別するための値） +- **conditional**（条件付き）か **all completed sessions**（全完了セッション対象）か — 条件は評価を特定のエージェントや環境に絞り込むためのもの +- タイムアウト、ラベル、最終更新日時 + +![ホスト定義一覧：各評価の名前、キー、バージョン、結果タイプ、チェックサム、タイムアウト、スコープ、新バージョンボタン、有効化・無効化ボタン](/images/dashboard/eval-definitions.png) + +一覧はキーワード検索や状態によるフィルタリングが可能です。自身のワーカーが登録した評価はここには表示されません。それらの結果は[評価ページ](/ja/sessions/evaluations)で **customer** タグとして表示され、ホスト型のものは **managed** タグで表示されます。 + +1つの組織が同時に有効にできるホスト評価は最大100件です。 + +## 新バージョンを公開する + +行の **new version** を選択します。そのバージョンのコードを持つオーサリングページが開くので、変更してテストし、デプロイします。キーと結果タイプは引き継がれ、変更できません。 + +後継バージョンを公開すると、前のバージョンは無効化され、一覧には残り続けます。結果にはそれを生成したバージョンが記録されるため、グラフ上で新しいロジックがいつ適用されたかを正確に確認できます。 + +## ロールバックする + +現在のバージョンで **disable** を選択し、戻したいバージョンで **enable** を選択します。データは削除されず、すべての結果はそのまま保持されます。 + +## 評価を停止する + +**disable** を選択します。有効なバージョンがなくなると、新しいセッションへの評価実行が停止します。自身のワーカーが実行している評価を停止するには、登録をやめてください。ワーカーから評価を削除するか、ワーカー自体を停止します。 + +## 既存セッションをスコアリングする + +評価は将来に向かって実行されます。つまり、今デプロイしたバージョンは、それ以前に終了したセッションをスコアリングすることはありません。過去のセッションをスコアリングするには、eval オーサリングページの **score sessions you already have** を開き、最大90日間の期間を選択し、必要に応じて評価を1つ指定してから、実行前に件数を確認します。この件数が実際の実行対象数と一致しており、含まれるセッションと評価のペアごとに課金対象の評価となります。 + +差分のみが補完されます。すでにその評価の結果が存在するセッションはそのまま保持され、同じ期間を2回実行しても新たにスコアリングされるものはありません。 + +1つのセッションを再スコアリングしたい場合（修正後や正常終了しなかったセッションなど）は、そのセッションのページで **re-evaluate** を選択します。新しい結果はセッションの履歴に追加され、以前の結果は保持されます。 + +## 権限 + +| 権限 | 可能な操作 | +| --- | --- | +| `evaluations:read` | 結果の確認、eval オーサリングページを開く | +| `evaluations:trigger` | ホスト定義の確認・デプロイ・バージョン管理・有効化・無効化、テスト実行、履歴のスコアリング、セッションの再評価 | +| `events:read` | 実際のセッションを使ったテスト、`evaluations:trigger` に加えてペイロードキーによるドラフトの補完 | +| `evaluations:run` | 独自の評価者ワーカーの実行 | \ No newline at end of file diff --git a/docs/ja/evaluations/overview.mdx b/docs/ja/evaluations/overview.mdx new file mode 100644 index 00000000..4813f8a2 --- /dev/null +++ b/docs/ja/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "エージェントを評価する" +description: "完了したすべてのセッションを、自分で定義した評価でスコアリングします。ホスト型Pythonチェック、またはご自身のワーカー上のLLMジャッジを使用できます。" +icon: "gauge" +--- + +評価は、完了したエージェントセッションをスコアリングします。セッションが終了すると、適用される有効な評価がすべて実行され、その結果がトレースの横に表示される根拠とともに記録されます。 + +- 0〜1の**スコア**（オプションで合格・不合格を付与可能） +- **メトリクス**（カウント、時間、コストなど、単位付き） +- **アサーション**（合格または不合格） + +## 2種類のエバリュエーター + +| | ホスト型Python | 自前のワーカー | +| --- | --- | --- | +| 記述場所 | ダッシュボードの **Analyze → eval authoring** | Pythonで、[Evaluator SDK](/ja/reference/evaluator-sdk) を使用 | +| 実行環境 | Failproof AI のマネージドエバリュエーター（サンドボックス内） | 自分のインフラ上 | +| 適している用途 | 決定論的なコードベースのチェック | LLMジャッジ、モデル呼び出し、パッケージ、シークレット、ネットワークアクセス、重い処理 | + +ホスト型Pythonは意図的にシンプルな設計です。1つの式のみ、インポートなし、ネットワーク接続なし。モデルが必要な処理——たとえば回答が適切だったかをスコアリングするLLMジャッジなど——は、代わりに自前のワーカーで実行します。どちらの種類もインバウンド接続は不要です。ワーカーは完了したセッションを取得し、アウトバウンドHTTPS経由で結果を送信します。 + +## 各組織は自分のエージェントを評価する + +評価は、それを定義した組織に属します。インスタンス上の各組織は独自の評価——独自のチェック、条件、しきい値、ラベル——を作成し、他の組織に影響を与えることなくバージョン管理・デプロイし、自分の結果のみを参照できます。結果はエージェント、環境、評価、時間でフィルタリングしたり、アシスタントに問い合わせたりすることができます。 + +## 最初のドラフトからライブスコアまで + + + + 測定対象を説明してアシスタントにドラフトを作成させるか、自分で記述します。[評価を作成する](/ja/evaluations/write) を参照してください。 + + + 本番稼働前に実際のセッションに対して実行します。結果は保存されません。[評価をテストする](/ja/evaluations/test) を参照してください。 + + + イミュータブルなバージョンをデプロイし、進化に合わせて新しいバージョンを公開し、以前のバージョンにロールバックします。[デプロイとバージョン管理](/ja/evaluations/deploy) を参照してください。 + + + スコアの推移をグラフ化し、エージェントや環境を比較し、アシスタントに問い合わせます。[評価結果を確認する](/ja/sessions/evaluations) を参照してください。 + + + +評価は前方向に実行されます。つまり、現在デプロイされたバージョンは、これ以降に完了するセッションをスコアリングします。すでに存在するセッションをスコアリングするには、[バックフィル](/ja/evaluations/deploy#score-sessions-you-already-have) を行ってください。 \ No newline at end of file diff --git a/docs/ja/evaluations/test.mdx b/docs/ja/evaluations/test.mdx new file mode 100644 index 00000000..c0a774f1 --- /dev/null +++ b/docs/ja/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "評価をテストする" +description: "デプロイ前に実際のセッションに対して評価を実行します。データは保存されません。" +icon: "flask-conical" +--- + +**test this evaluation** は、オーサリングページ上でデプロイすることなく、エバリュエーターフリートにある実際のセッションに対してコードを実行します。データは一切保存されません。ここでの失敗はプレビューであり、デプロイは常に許可されています。 + + + + **check** を選択すると、セッションに対して実行せずに、サンドボックスのルールに基づいてコードとコンディションをコンパイルして検証できます。 + + + エージェント、環境、時刻、セッション ID でマッチするセッションを絞り込み、最大 10 件にチェックを入れます。評価が失敗すべきセッションと、成功すべきセッションの両方を含めてください。 + + + **run against N sessions** を選択し、各行の結果を確認します。 + + + +| 行 | 意味 | +| --- | --- | +| **ok** | 実行されました。その行には、返されたすべてのスコア、メトリクス、アサーション、および実行時間が表示されます。 | +| **skipped** | コンディションが `False` を返したため、評価は実行されませんでした。これはスキップであり、失敗ではありません。 | +| Failed | 例外が発生したか、タイムアウトしたか、サンドボックスが拒否した操作が使用されました。行にその詳細が表示され、アシスタントが対応できる場合は **Fix it** でエラーが渡されます。 | + +![test this evaluation パネル: エージェントで絞り込まれた 3 つのセッションのうち、2 つが ok、1 つはコンディションが False を返したため skipped になっています。](/images/dashboard/eval-test.png) + +コードを編集した瞬間、その結果は最新でなくなり、再利用されるのではなく薄くグレーアウト表示されます。 \ No newline at end of file diff --git a/docs/ja/evaluations/write.mdx b/docs/ja/evaluations/write.mdx new file mode 100644 index 00000000..5539ed72 --- /dev/null +++ b/docs/ja/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "評価を作成する" +description: "測定内容を説明してアシスタントにホスト型Python評価の下書きを作成させるか、コードを自分で記述します。LLMジャッジはお客様自身のワーカー上で実行されます。" +icon: "file-pen-line" +--- + +ホスト型評価は、ダッシュボードで記述してFailproof AIのエバリュエーターフリート上で実行される、小さな決定論的なPythonコードです。より重い処理（LLMジャッジ、パッケージ、シークレット、ネットワーク呼び出しなど）は、代わりに[お客様自身のワーカー](#write-it-in-your-own-worker)上で実行されます。 + +## 説明から下書きを作成する + +1. **Analyze → eval authoring** に移動し、**new eval** を選択します。 +2. 測定内容を平易な英語で説明するか、**start from an example…** から選択して、**draft** を選択します。 +3. フィールドと自動入力されたコードを確認し、[テスト](/ja/evaluations/test)して[デプロイ](/ja/evaluations/deploy)します。 + +![下書きされた評価が表示されたeval authoringページ：説明、下書きに関するアシスタントのメモ、name・key・version・result・timeout・labels・conditionの各フィールド。](/images/dashboard/eval-authoring-draft.png) + +下書きは組織独自のイベントに基づいています。このページは過去7日間のセッションで使用されたペイロードキーを読み取るため、コードは推測ではなく実際に存在するキーを参照します。下書きを渡す前に、アシスタントは最大5件の最近のセッションに対してテストを行い、最大3ラウンドで修正可能な問題を修正し、コードが要求された内容を測定しているか一度確認します。説明は具体的に記述してください。広範なプロンプトは処理が遅くタイムアウトする場合があります。いずれの場合もコードをレビューしてください。デプロイがブロックされることはありません。 + +## フィールドを設定する + +| フィールド | 内容 | +| --- | --- | +| name | 表示される名前。後から編集可能 | +| key | 結果をチャートで示す際の安定した識別子（例：`code_assistant_quality_gate`） | +| version | スペースなしの任意のバージョン文字列（例：`1.0.0`） | +| result | **score**（0〜1）、**metric**（単位付きの数値）、または **assertion**（合否） | +| timeout seconds | デフォルトは30。サンドボックスは1回の実行を60秒で停止 | +| labels | 最大20件、カンマ区切り。後から編集可能 | +| condition | 任意。Python式。`True` となるセッションのみで評価が実行される | + +conditionを使用して、評価を対象とするエージェントおよび環境にスコープを絞り込みます： + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +key、version、result type、condition、コードはデプロイ後は変更不可です。これらを変更する場合は、新しいバージョンを公開してください。name、labels、および有効/無効の状態は引き続き編集可能です。 + +## コードを自分で記述する + +**evaluator code** は `EvalResult(...)` を返す1つのPython式で、スコープ内に `session` があります。以下の例は、ステータスがokで返ってきたツール結果の割合を採点します： + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +結果は、評価自身のキーを宣言された型でリードします。score評価には `score=`、metric評価またはassertion評価にはキーと同じ名前の `metrics` または `assertions` エントリを使用します。その他のmetricsとassertionsはこれに付随し、1回の実行で最大25件の結果を含められます。 + +| スコープ内 | 利用できるもの | +| --- | --- | +| `session` | `session_id`、`agent_id`、`environment`、`started_at`、`ended_at`、`event_count`、`events`、および `count(event_type)`、`events_of_type(event_type)` | +| 各イベント | `id`、`ts`、`event_type`、`payload` | +| 結果型 | `EvalResult`、`Score`、`Metric`、`Assertion`、conditionには `ConditionResult` | +| 組み込み関数 | `abs`、`all`、`any`、`bool`、`dict`、`float`、`int`、`len`、`list`、`max`、`min`、`range`、`round`、`set`、`sorted`、`str`、`sum`、`tuple` | + +それ以外にはアクセスできません。importは使用できず、セッションデータとプレーンな文字列・辞書メソッド（`get`、`lower`、`split` など、参照ではなく呼び出しが必要）以外の属性も使用できません。ペイロードキーはエージェントが送信する内容によって異なります（上記の `status` はあくまで例です）。実際のセッションから確認してください。**format** はコードを整形し、**fix** はアシスタントに修正を依頼します。コードは最大128 KiB、conditionは最大16 KiBです。 + +![evaluatorコードエディター。formatとfixが表示され、下書きされた評価のassertionsを示している。](/images/dashboard/eval-authoring-code.png) + +## お客様自身のワーカーで記述する + +評価にモデル、パッケージ、シークレット、またはネットワークが必要な場合は、[Evaluator SDK](/ja/reference/evaluator-sdk) を使用して記述し、お客様自身のインフラストラクチャ上で実行します。同じ結果型を使用し、その結果はホスト型の結果の隣に **customer** タグ付きで表示されます： + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/ja/policies/deploy.mdx b/docs/ja/policies/deploy.mdx index 35bd9629..80bfe211 100644 --- a/docs/ja/policies/deploy.mdx +++ b/docs/ja/policies/deploy.mdx @@ -1,51 +1,94 @@ --- title: "ポリシーをデプロイする" -description: "レビュー済みのポリシーバージョンを対象マシンにロールアウトします。" +description: "テスト済みのポリシーバージョンをオブザーブモードでマシンに展開し、強制適用に切り替えて、すべてのマシンが変更を取得したことを確認します。" icon: "cloud-upload" --- -デプロイメントは、1つ以上のポリシーバージョンを登録済みマシンのターゲットセットに接続します。 +デプロイメントは、公開済みのポリシーバージョンをマシンに展開します。各ポリシーは以下のいずれかの効果を持ちます。 -## デプロイメントを適用する +- **Observe（観察）** は、ポリシーが何を行ったかを記録しますが、何もブロックしません。 +- **Enforce（強制）** は、判定に従って実際に動作します。`deny` はコールをブロックし、`instruct` はエージェントを誘導します。 + +## マシンを追加する + +マシンが Cloud に接続されると、**Admin → enforcement** に表示されます。対象のマシンがまだ表示されていない場合は、以下の手順を実行してください。 - 1. **Admin → enforcement** に移動し、マシンを見つけて行を展開します。 - 2. **edit** を選択し、レビュー済みのポリシーバージョンを追加して、**observe** または強制効果を選択します。 - 3. 変更を適用し、マシンの次回チェックインを待ってデプロイメントとカバレッジの状態を確認します。 - 4. **Observe → policy** に移動してライブの判定を確認します。 - - ![ポリシーバージョン、enforce および observe エフェクト、デプロイメント適用アクションが表示されたマシンデプロイメントエディター。](/images/dashboard/enforcement-editor.png) + 1. **Administration → Keys** に移動し、`policies:pull`（デプロイメントの受信用）と `events:add`（判定結果を Cloud に送信するため）の権限を持つキーを作成します。 + 2. そのキーを使用してマシンを接続します。手順については [マシンを Cloud に接続する](/ja/start/setup#connect-a-machine-to-cloud) を参照してください。 + 3. **Admin → enforcement** にマシンが表示されることを確認します。 - `fp fleet` を使用してCLIからデプロイします。適用前に結果セットを確認してください — `deploy` はフルプランを表示し、**`--json` なしのインタラクティブターミナルでのみ** 確認を求めます。`--json` 指定時、`--yes` 指定時、またはstdinがリダイレクトされている場合（CIステップ、スクリプト、エージェントのシェルアウトなど）は、プランも確認プロンプトも表示されず即座に適用されます。レビューが必要な場合は事前に `fp fleet show ` を実行してください： + マシン上で以下を実行します。 + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + ターミナルで `failproofai config` を実行すると、Cloud への接続の可否が確認され、マスクされたプロンプトでキーの入力を求められます。その後、任意の場所から `fp fleet list` を実行して、マシンが登録済みであることを確認します。 + + + +## オブザーブモードでデプロイする + + + + 1. **Admin → enforcement** に移動し、対象のマシンを見つけて行を展開します。 + 2. **edit** を選択し、テスト済みのポリシーバージョンを追加して **observe** を選択します。 + 3. 変更を適用し、マシンの次回チェックインまで待機してから、デプロイメントとカバレッジの状態を確認します。 + 4. **Observe → policy** に移動して、ライブの判定結果を確認します。 + ![ポリシーバージョン、enforce/observe の効果、デプロイメント適用アクションを表示したマシンデプロイメントエディター。](/images/dashboard/enforcement-editor.png) + + ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` はインテントとデリバリーの差分を表示します（マシンが次回ポーリングするまでは `behind` と表示されます）。`fp fleet history ` はジェネレーションの一覧を表示し、`fp fleet rollback ` は特定のジェネレーションを復元します — そのジェネレーションが無効化または削除されたポリシーを参照している場合は拒否されます。 + `:observe` サフィックスがオブザーブモードの指定です。`--add no-force-push` のようにサフィックスなしで指定すると、そのポリシーについてマシンが既に持つ効果が維持され、それ以外の場合は enforce が適用されます。後から `--add no-force-push:enforce` に切り替えることで enforce に変更できます。 + + `deploy` コマンドは **マシンのポリシーセット全体を結果で置き換えます**。実行計画を表示してから適用前に確認を求めますが、これは対話型ターミナルの場合のみです。`--yes` を指定した場合、`fp --json` 配下で実行した場合、または stdin がリダイレクトされている場合（CI ステップ、スクリプト、エージェントからのシェル実行など）は確認なしで適用されます。ただし、実行計画は引き続き表示されるか、`--json` 指定時には `plan` として返されます。 - マシン自体は `failproofai config --status` で確認し、デプロイ後は `fp sessions --env production --since 24h` と `fp events --event-type hook_completed` を使用してアクティビティがCloudに届いているか検証します。 + マシン上で `failproofai policies` を実行すると、Cloud が管理するポリシーの一覧が表示され、`failproofai config --status` で接続状態を確認できます。`fp sessions --env production --since 24h` や `fp events --event-type hook_completed` を使用して、マシンのアクティビティが Cloud に届いていることを確認してください。 - - 可変のドラフトではなくレビュー済みのバージョンをデプロイし、セッションを確認できる非本番マシンまたは小規模なコホートから開始します。 + + 公開済みのバージョンと、それを実行するマシンを選択します。 - - 作業をブロックせずに、マッチ結果、理由、影響を受けるツール、および誤検知を確認します。 + + 何もブロックされない状態で、マッチした内容、理由、影響を受けるツール、および誤検知を確認します。 - - 観察されたマッチが安全でないアクションと正当なアクションを分離した後にプロモートし、すべての対象マシンがデプロイメントを取得して判定を報告していることを確認します。 + + 観察したマッチ結果が安全でない操作と正当な操作を区別できるようになったら、効果を enforce に切り替えます。その後、対象のすべてのマシンが変更を取得し、判定を報告していることを確認します。 -マシンには `policies:pull` 権限が必要です。イベント報告は `events:add` で個別に制御されます。Cloudの分析と強制適用を期待する場合は、両方を確認してください。 +## カバレッジを確認する + +カバレッジは、ポリシーがリスクのある場所で実行されているかどうかを示します。 + +1. **Admin → enforcement** に移動し、enforce と observe の合計数を確認します。 +2. ID またはラベルでマシンを検索するか、ポリシーが適用されていないマシンでフィルタリングします。 +3. 行を展開して、割り当てられたポリシー、報告されたデプロイメント状態、最終チェックイン時刻、および履歴を比較します。 +4. 適用済みのデプロイメントが保留中の場合は、マシンのポーリングインターバルの後に更新します。 + +![ポリシーカバレッジ、マシンのデプロイメント状態、observe/enforce の割り当てを表示した Enforcement フリート画面。](/images/dashboard/enforcement-fleet.png) + +最新のデプロイメントを一度も取得していないマシン、報告を停止した登録済みマシン、誤った環境に割り当てられたポリシー、中断された更新後のバージョンずれなどに注意してください。 + +マシンにはワークロードと環境ごとにラベルを付けてください。ホスト名だけではオートスケーリングや入れ替えが発生した際に対応できないことが多いためです。 + +```bash +failproofai config --machine-label checkout-runner-03 +``` - 強制適用の管理はCloud上の管理者ワークフローです。ルート専用の強制適用ルートを通常の顧客向け `/v1` APIエンドポイントとして扱わないでください。 + Enforcement の管理は、管理者向けの Cloud ワークフローです。ルート専用の enforcement ルートを通常の顧客向け `/v1` API エンドポイントとして扱わないでください。 \ No newline at end of file diff --git a/docs/ja/policies/editor.mdx b/docs/ja/policies/editor.mdx index 9e23dc51..61553290 100644 --- a/docs/ja/policies/editor.mdx +++ b/docs/ja/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "ポリシーエディター" -description: "確認された失敗パターンからバージョン管理されたポリシーを作成・改訂します。" +title: "ポリシーを作成する" +description: "Failproof AI に監査の発見からポリシーの下書きを作成させるか、自分でソースを記述し、レビュー・テスト・公開を行います。" icon: "file-pen-line" --- -ポリシーエディターを使用して、検出された問題をデプロイ可能なルールへと変換します。下書きがライブの動作をサイレントに変更しないよう、作成とデプロイを分離しています。 +ポリシーを作成する方法は2つあります。Failproof AI に監査の発見からポリシーの下書きを作成させるか、自分でソースを記述するかです。いずれの場合も、明示的に選択するまで公開・デプロイは行われません。 -問題に繰り返し可能なアクションパターンがある場合は、**Analyze → issues** で該当の問題を開き、**generate policy** を選択してください。Failproof AI はまずそのポリシーで問題を表現できるかどうかを説明し、レビュー済みのインテントと検出コンテキストをエディターに引き継ぎます。生成されたソースは公開するまで下書きのままです。 +## 監査からポリシーを作成する -## ポリシーバージョンの公開 +監査は失敗を検出し、ポリシーはその再発を防ぎます。Failproof AI は発見の証拠をもとにポリシーの下書きを作成します。 + +### 1. 監査を実行する + +失敗が発生しているセッションに対して[監査を実行](/ja/audits/run)します。各発見には証拠となるセッション、根本原因、推奨される予防策が含まれています。**繰り返し可能なアクションパターン**を持つ発見をもとに作業してください。ポリシーはフックイベントで認識できるものしか防ぐことができません。 + +### 2. 下書きを生成する - - 1. **Admin → policy editor** に移動し、**compose** で失敗モードを説明するか、JavaScript ポリシーソースを貼り付けます。 - 2. ソースを検証し、報告されたすべてのエラーを修正します。 - 3. ポリシーの識別情報を入力して公開し、**library** を使用してバージョンの比較や無効化を行います。 - 4. マシンへのロールアウトの準備ができたら **enforcement** を選択します。 + + 1. **Analyze → issues** で発見の Issue を開き、引用されているセッション、根本原因、推奨事項を確認します。 + 2. **generate policy** を選択します。Failproof AI はまず、問題をポリシーで表現できるかどうかを判断します。**no policy** という結果が返った場合、修正策はアラート、ワークフローの変更、または人的対応であり、ポリシーではありません。 + 3. **write this policy** を選択します。Issue のタイトル、発見内容、根本原因、推奨事項、提案された強制意図が **Admin → policy editor** の下書きになります。候補チェックの結果に同意しない場合は **open the editor anyway** を使用してください。 - ![ポリシーの識別情報、AI支援による下書き、ソース検証、公開コントロールを備えたポリシーエディターのcomposeビュー。](/images/dashboard/policy-editor.png) + ![ポリシーの識別情報、AI支援の下書き作成、ソースの検証、公開コントロールを含む Policy editor の作成画面。](/images/dashboard/policy-editor.png) - CLI から `fp policies publish` を使用して公開します。このコマンドは**新しいバージョン**を作成するのみで、既存のバージョンをその場で編集することはありません。また、送信前に node でソースの構文チェックを行います。下流では誰もチェックしないため、構文エラーがあるとエンフォースメント時にマシン上で表面化してしまいます。 + 証拠を確認してから、アシスタントで下書きを作成します。`compose` はレビュー用のソースを出力するだけで、何も公開しません。 ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - 公開してもデプロイは行われません。新しいバージョンは `fp fleet deploy` でマシンに配備されるまで未使用のままです。`fp policies compose ""` は Cloud アシスタントを使ってソースの下書きを生成し、公開せずにレビュー用として出力します。 - - Cloud ではなくローカルのエージェント CLI にポリシーをインストールするには、`failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project` を使用してください。 + `compose` を使用するには、`policies:write` ロールを持つセッションでサインインしている必要があります（`fp login`）。API キーは使用できません。 -## 作成チェックリスト +### 3. 下書きをレビューする + +下書きはあくまで出発点であり、最終的な判断ではありません。公開前に以下を確認してください。 + +1. 運用上の言葉で失敗モードが明確に示されていること。 +2. 判断に十分な証拠を持つフックイベントとツールのみに一致すること。 +3. 安全でないアクションを捉える最も狭い条件を使用していること。 +4. エージェントが次に何をすべきかを伝える理由を返すこと。 +5. エージェントが安全に修正できる場合は `instruct` を使用し、アクションの許可が受け入れられないか取り消せない場合にのみ `deny` を使用していること。 + +エディタでソースを検証し、報告されたすべてのエラーを修正してください。 + +### 4. テストしてから公開する + +公開前にソースの下の **backtest** を実行してください。これにより、フリートがすでに実行した呼び出しに対して下書きを再生し、中断されたであろう有効な呼び出しをカウントします。[ポリシーのテスト](/ja/policies/test)では、この確認とその他のチェックについて説明しています。 + +動作が確認できたら、ポリシーの識別情報を入力して **publish version** を選択します。公開すると不変のバージョンが作成されますが、何もデプロイされません。[デプロイ](/ja/policies/deploy)するまでは未使用のまま待機します。ターミナルから実行する場合: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` はソースを送信前に構文チェックを行うため、構文エラーはここで検出され、強制適用時にマシン上で発生することはありません。 + +## 自分で記述する + +ポリシーは `failproofai` API に対する JavaScript または TypeScript で記述します。 + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +これは `production/config.yml`、`/srv/production/config.yml`、`/srv/production`、`C:\\production\\config.yml` に対して `Write` と `Edit` の両方でマッチしますが、`production-backup` にはマッチしません。`production` はパスセグメント全体である必要があります。コンテキストにはイベントタイプ、正規化されたペイロード、セッションメタデータ、パラメータ、利用可能な場合はソース CLI も含まれます。詳細は [policy SDK](/ja/reference/policy-sdk) を参照してください。 + +バージョンとして公開するには、**Admin → policy editor** の **compose** にソースを貼り付けて上記の手順3と4に従うか、ターミナルから `fp policies publish` でファイルを公開してください。 -1. 運用上の言葉で失敗モードを明名する。 -2. 判断に十分な証拠を含むフックイベントとツールを選択する。 -3. 安全でない動作に一致する最も狭い条件を記述する。 -4. エージェントまたはオペレーターが次に何をすべきかを伝える理由を返す。 -5. 一致すべき例と、許可されたままであるべき例を追加する。 -6. 新しいバージョンを保存してレビューを依頼する。 +Cloud なしでマシン上で実行するには、名前の末尾が `policies.js`、`policies.mjs`、または `policies.ts` のファイルとして `.failproofai/policies/` に保存してください。これらはプロジェクトとユーザースコープで自動的に読み込まれます。パスを指定してインストールすることもできます。 -エージェントが安全に軌道修正できる場合は `instruct` を使用します。そのアクションを許可することが受け入れがたいリスクや取り返しのつかない結果をもたらす場合は `deny` を使用します。 +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - ポリシーバージョンはイミュータブルなデプロイ入力です。下書きを編集すると新しいバージョンが作成されます。すでにマシンに割り当てられているバージョンを上書きしないようにしてください。 - \ No newline at end of file +すべてのポリシーに、コンベンション・カスタム・パック・Cloud 管理ポリシーの全体で一意の名前を付けてください。 \ No newline at end of file diff --git a/docs/ja/policies/failure-behavior.mdx b/docs/ja/policies/failure-behavior.mdx index 8d674db4..e748dd4c 100644 --- a/docs/ja/policies/failure-behavior.mdx +++ b/docs/ja/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- title: "障害時の動作" -description: "ポリシー評価またはローカルデーモンが利用できない場合の動作を理解する。" +description: "ポリシー評価またはローカルデーモンが利用できない場合の動作を理解します。" icon: "shield-alert" --- -Failproof AI は、強制の失敗が無音でリスクのある作業を許可するのではなく、明示的に可視化されるよう設計されています。 +Failproof AI は、強制適用の失敗が無音でリスクのある操作を許可するのではなく、明示的に可視化されるよう設計されています。 -## 失敗クローズドブロックの診断 +## 失敗クローズ（failure-closed）ブロックの診断 - 1. **Admin → enforcement** に移動し、対象マシンを開きます。 - 2. 最終チェックイン日時、割り当てられたデプロイメント、および報告されたデプロイメントを確認します。 - 3. **Observe → policy** に移動し、拒否された決定のセッションを開きます。 - 4. 理由がデーモンの到達不能、バージョンのずれ、またはポリシー自体のどれを示しているか確認します。 + 1. **Admin → enforcement** に移動してマシンを開きます。 + 2. 最後のチェックイン、割り当てられたデプロイメント、および報告されたデプロイメントを確認します。 + 3. **Observe → policy** に移動して、拒否された決定のセッションを開きます。 + 4. 理由がデーモンの到達可能性、バージョンの不一致、またはポリシー自体を示しているかを確認します。 @@ -27,41 +27,43 @@ Failproof AI は、強制の失敗が無音でリスクのある作業を許可 -`failproofaid` を使用するよう設定されたマシンでは、デーモンが唯一の評価者です。デーモンに到達できない場合、またはプロトコルバージョンが CLI と一致しない場合、フック評価は失敗クローズドになります。アクションは拒否され、オペレーターにデーモンの確認または更新を促す理由が表示されます。 +`failproofaid` を使用するよう設定されたマシンでは、デーモンが唯一の評価者です。デーモンに到達できない場合、またはそのプロトコルバージョンが CLI と一致しない場合、フック評価は失敗クローズとなります。アクションは拒否され、その理由にはオペレーターにデーモンの確認または更新を促すメッセージが含まれます。 -デーモン設定前は、フックがインプロセスでポリシーを評価します。デーモン設定が記録された後は、Failproof AI はデーモンが失敗した際に別の評価者へ無音でフォールバックすることはありません。 +デーモン設定の前は、フックはプロセス内でポリシーを評価します。デーモン設定が記録されると、Failproof AI はデーモンが失敗した際に第二の評価者へ無音でフォールバックすることはありません。 -## 失敗クローズドの決定への対応 +## 失敗クローズ（failure-closed）の決定への対応 1. `failproofai config --status` を実行します。 -2. バージョンが異なる場合は、パッケージを更新した後に `failproofai config` を再実行します。 +2. バージョンが異なる場合は、パッケージを更新してから `failproofai config` を再実行します。 3. デーモンに到達できない場合は、サービスの状態とローカルログを確認します。 -4. ポリシー評価のパスが正常であることを確認してからエージェント作業を再開します。 +4. ポリシー評価のパスが正常であることを確認してからエージェントの作業を再開します。 - ブロックされたアクションを繰り返し再試行しないでください。失敗クローズドの応答は、そのアクションが安全であることをシステムが確認できなかったことを意味します。 + ブロックされたアクションを繰り返し再試行しないでください。失敗クローズの応答は、システムがそのアクションの安全性を確立できなかったことを意味します。 ## パックが読み込まれない場合 -パックを強制するよう指示されたマシンが、そのパックを実行できない場合、静かに続行するのではなく拒否します。トリガーは**記録された期待値**であり、空の期待値ではありません。パックがインストールされていないマシンは無音ですが、宣言されているのに解決できないパック、またはマニフェストの宣言より少ない登録しかできないパックは拒否します。 +パックを強制適用するよう指示されたマシンがそれを実行できない場合、静かに継続するのではなく拒否します。トリガーとなるのは**記録された期待値**であり、空の期待値ではありません。パックがインストールされていないマシンは無音のままですが、宣言されているにもかかわらず解決できないパック、またはマニフェストで宣言された数より少ないガードしか登録しないパックは拒否されます。 -この拒否は、到達不能なデーモンとは異なり**限定的**です。デーモンに到達できない場合、評価が全く行われていないため何も安全とは言えません。読み込まれないパックには、不足しているガードの列挙可能なセットがあります。宣言されたすべてのポリシーがそれぞれ `match` を持つためです。そのため、対象のポリシーがカバーするイベントとツールのみを拒否し、それ以外はすべて続行されます。 +この拒否は、到達できないデーモンとは異なり**限定的**です。デーモンに到達できない場合は評価そのものが行われておらず、何も安全であるとはわかりません。読み込めないパックには、宣言されたポリシーごとに独自の `match` があるため、欠けているガードのセットが列挙可能です。つまり、それらのポリシーが対象とするイベントとツールのみ拒否され、それ以外はすべて続行されます。 -以下の場合は発動しません： +以下の場合には発動しません： -- `observe` パック（構成上、評価後に破棄するため） -- 採用しなかったポリシー、または明示的に無効にしたポリシー -- ローダーが受け取らなかったパック（「登録なし」と意図的なスキップを区別できないため） +- `observe` パック（構造上、評価して破棄します） +- 採用していないポリシー、または明示的に無効にしたポリシー +- ローダーが受け取れなかったパック（「登録なし」は意図的なスキップと区別できません） - アクティブなセッションの一時停止 -- 読み込みタイムアウト（一時的なもの）— ディスクが一時的に遅い程度で、人が介入するまで拒否し続けるべきではありません +- 読み込みタイムアウト（これは一時的なもので、ディスクの一瞬の遅延のために人が介入するまで拒否を続けるべきではありません） -`UserPromptSubmit` は、不足しているポリシーが何を宣言していても、拒否ではなく **instruct** を行います。一括拒否を行うと、問題を修正できるエージェントへのアクセスも失われてしまいます。 +`UserPromptSubmit` は、欠けているポリシーが何を宣言していたかにかかわらず、拒否の代わりに **instruct** を行います。一括拒否では問題を修正できるエージェントへのアクセスも遮断してしまうためです。 ### 対処方法 ```bash -failproofai pack list +failproofai policies ``` -このコマンドは読み込まれないインストール済みパックを名前とともに表示し、理由を示したうえでゼロ以外の終了コードで終了します。その後、パックを再インストール（`failproofai pack add `）するか、削除（`failproofai pack remove `）してください。削除すると期待値が取り消され、拒否も停止します。 \ No newline at end of file +このリストは、インストール記録またはダイジェストが照合できなくなったインストール済みパックにフラグを立て、その理由を表示します。パックのインポートは行わないため、読み込んだ後にのみ失敗するパック（マニフェストが宣言した数より少ないガードしか登録しないもの）は通常どおりリストされます。その場合は以下の拒否によって特定されます。いずれの場合も、パックを再インストール（`failproofai policies add `）するか、削除（`failproofai policies remove `）してください。削除すると期待値が取り下げられ、拒否も停止します。 + +拒否自体は `pack/failproofai-pack-unavailable` に帰属し、これは読み込まれたポリシーよりも優先されます。そのため、ブロックされたツール呼び出しは、最初に発動した既存のガードではなく、欠けているパックを示します。 \ No newline at end of file diff --git a/docs/ja/policies/local-configuration.mdx b/docs/ja/policies/local-configuration.mdx index c889e596..ef3b7ecc 100644 --- a/docs/ja/policies/local-configuration.mdx +++ b/docs/ja/policies/local-configuration.mdx @@ -1,33 +1,28 @@ --- title: "ローカル設定" -description: "ポリシーのスコープ、パラメータ、カスタムファイル、およびマシンレベルの Failproof AI 設定を管理します。" +description: "ポリシーのスコープ、パラメーター、カスタムファイル、マシンレベルの Failproof AI 設定を管理します。" icon: "file-cog" --- -Failproof AI は、ポリシーの選択とマシン・デーモンの設定を分離しています。これにより、リポジトリのポリシー選択を審査可能な状態に保ちつつ、認証情報やデーモンの状態をリポジトリの外に置くことができます。 +Failproof AI は、リポジトリがコミットできるもの（フックの配線、ポリシーパラメーター、カスタムポリシー）と、認証情報・インストール済みパック・デーモンなどのマシン状態を分けて管理します。 -## ポリシースコープの選択 +## スコープの選択 - - - 引数なしで `failproofai` を実行するとローカルポリシーダッシュボードが開きます。ポリシーを有効にする前に、user・project・local のいずれかのスコープを選択することで、変更が意図した設定ファイルに書き込まれます。 +スコープはフックの配線先と、パラメーターおよびカスタムポリシーパスを記述する設定ファイルを決定します。 - - **User** はこのマシン上のすべてのプロジェクトに適用されます。 - - **Project** はリポジトリに紐づき、コミットに含めることができます。 - - **Local** は特定プロジェクトを特定ユーザー向けにオーバーライドするもので、gitignore に追加しておく必要があります。 +- **User** — このマシン上のすべてのプロジェクトに適用されます。 +- **Project** — リポジトリに属し、コミット可能です。 +- **Local** — 特定のプロジェクトを特定のユーザー向けにオーバーライドします。gitignore に追加しておく必要があります。 - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # このリポジトリ用にフックを配線する +failproofai policies --install --cli claude --scope user # またはこのマシン上のすべてのプロジェクト用に配線する +failproofai policies +``` - すべてのハーネスが local スコープに対応しているわけではありません。選択したハーネスが表現できないスコープを指定した場合、CLI はエラーを返します。 - - +すべてのハーネスがローカルスコープに対応しているわけではありません。選択したハーネスがサポートしていないスコープを指定すると、CLI はエラーを返します。 + +どのパックポリシーが有効かは**スコープの影響を受けません**。この設定はインストール済みパックに記録されるため、`failproofai policies add ` を実行すると、`--scope` の指定に関わらずマシン全体でそのポリシーが有効になります。 | スコープ | ポリシー設定ファイル | | --- | --- | @@ -35,21 +30,20 @@ Failproof AI は、ポリシーの選択とマシン・デーモンの設定を | Local | `/.failproofai/policies-config.local.json` | | User | `~/.failproofai/policies-config.json` | -有効化されたポリシーは和集合としてマージされます。ポリシーパラメータは、そのポリシーのパラメータを定義している最初のスコープが使用され、適用順は project → local → user の順となります。明示的なカスタムポリシーパスも、それを定義している最初のスコープが使用されます。 +ポリシーパラメーターは、そのポリシーのパラメーターを定義している最初のスコープが使用されます（優先順位: project → local → user）。明示的なカスタムポリシーパスも、それを定義している最初のスコープが使用されます。 -## ポリシーパラメータの設定 +## ポリシーパラメーターの設定 - ローカルダッシュボードでポリシーを開き、サポートされているパラメータを編集して、選択したスコープで保存します。条件に一致するエージェントアクションと一致しないエージェントアクションをそれぞれ実行し、**Observe → policy** で判定結果を確認します。 + ローカルダッシュボードでポリシーを開き、サポートされているパラメーターを編集して、選択したスコープで保存します。一致するエージェントアクションと一致しないエージェントアクションをそれぞれ実行し、**Observe → policy** で判定内容を確認します。 - 選択したスコープの `policies-config.json` を編集してから、`failproofai policies` を実行して不明なポリシー名やパラメータキーを検出します。 + 選択したスコープの `policies-config.json` を編集し、`failproofai policies` を実行します。インストール済みパックに存在しないポリシー名が `policyParams` エントリに含まれている場合は警告が表示されます。エントリ内のキーの検証は行われないため、下記の表と照らし合わせてスペルを確認してください。 ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ Failproof AI は、ポリシーの選択とマシン・デーモンの設定を -## マシンファイルの概要 +### Failproof AI ポリシーが受け付けるパラメーター + +各ポリシーは独自のパラメーター型を検証します。 + +| ポリシー | パラメーター | 型とデフォルト値 | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`、`[]`；各エントリに `regex` と `label` を含む | +| `block-read-outside-cwd` | `allowPaths` | `string[]`、`[]` | +| `block-sudo` | `allowPatterns` | `string[]`、`[]` | +| `block-rm-rf` | `allowPaths` | `string[]`、`[]` | +| インフラストラクチャブロッカー | `allowPatterns` | `string[]`、`[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`、`[]` | +| `block-push-master` | `protectedBranches` | `string[]`、`["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`、`["main", "master"]` | +| `prefer-package-manager` | `allowed`、`blocked` | `string[]`、`[]` | +| `warn-large-file-write` | `thresholdKb` | `number`、`1024` | +| `require-push-before-stop` | `remote`、`baseBranch` | `string`、`"origin"`；`string`、`"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`、`"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`、`"main"` | + + + 許可パターンはエージェントが実行できる範囲を広げます。フリート全体に展開する前に、対象のハーネス上でトークナイズの挙動やコマンドのバリエーションを正確にテストしてください。 + + +## マシンファイルの構成 -`~/.failproofai` には、信頼境界ごとに分かれたファイルが格納されています。 +`~/.failproofai` には、信頼境界ごとに個別のファイルが格納されています。 | パス | 用途 | | --- | --- | -| `config.json` | 機密情報を含まないデーモン・監査・テレメトリ設定 | -| `credentials.json` | クラウド認証情報。オーナーのみ読み取り可能なパーミッションで保存 | -| `policies-config.json` | ユーザースコープの組み込みポリシー選択、パラメータ、および明示的なカスタムパス | -| `policies/` | ユーザー規約ポリシーおよびクラウド管理のポリシーアーティファクト | -| `hook-activity/` | ローカルポリシー判定ログ | -| `state/` | デーモンスプール、ヘルス、一時停止、およびランタイム状態 | +| `config.json` | 非機密のデーモン・監査・テレメトリー設定 | +| `credentials.json` | クラウド認証情報；オーナーのみがアクセスできるパーミッションで保存 | +| `policies-config.json` | ユーザースコープのパラメーターおよび明示的なカスタムポリシーパス | +| `policies/` | ユーザー定義のコンベンションポリシー、インストール済みパックとその有効ポリシー、クラウド管理のポリシーアーティファクト | +| `hook-activity/` | ローカルのポリシー判定ログ | +| `state/` | デーモンスプール、ヘルス状態、一時停止状態、ランタイム状態 | -コンテナや隔離されたテスト環境向けにマシン全体のレイアウトを移動する場合は `FAILPROOFAI_HOME` を使用してください。個別の状態ディレクトリを独立して移動しないようにしてください。 +コンテナや隔離テスト環境のためにマシン全体のレイアウトを移動するには `FAILPROOFAI_HOME` を使用してください。個々の状態ディレクトリを個別に移動することは避けてください。 - `credentials.json` は絶対にコミットしないでください。プロジェクトのポリシー設定およびプロジェクト規約ポリシーは、執行コードとしてレビューした上でのみコミットしてください。 + `credentials.json` は絶対にコミットしないでください。プロジェクトのポリシー設定およびプロジェクトのコンベンションポリシーをコミットする場合は、必ず強制コードとして内容を確認してからにしてください。 \ No newline at end of file diff --git a/docs/ja/policies/overview.mdx b/docs/ja/policies/overview.mdx index a5253446..578561da 100644 --- a/docs/ja/policies/overview.mdx +++ b/docs/ja/policies/overview.mdx @@ -1,63 +1,54 @@ --- title: "ポリシー" -description: "既知の障害が再発する前に、エージェントのアクションを監視・誘導・ブロックします。" +description: "既知の失敗が再発する前に、エージェントのアクションを観察・誘導・ブロックします。" icon: "shield-check" --- -ポリシーはエージェントのフックイベントを評価し、以下の3つのいずれかの判断を返します： +ポリシーはエージェントのフックイベントを評価し、3つの判断のいずれかを返します。 - `allow` はアクションの続行を許可します。 - `instruct` はエージェントに修正指示を与えます。 -- `deny` は理由を添えてアクションをブロックします。 +- `deny` は理由を示してアクションをブロックします。 -## 3つのポリシー操作画面を活用する +## ポリシーの管理場所 - - - 1. **Observe → policy** でセッションのポリシー判断をフィルタリング・確認します。 - 2. **Admin → policy editor** でポリシーの作成・検証・公開・無効化、またはイミュータブルなバージョンの確認を行います。 - 3. **Admin → enforcement** でバージョンとエフェクトをマシンに割り当てます。 +| ダッシュボード上の場所 | そこで行うこと | +| --- | --- | +| **Observe → policy** | 実際のセッションにおける判断内容（どのポリシーが、どのマシンで、なぜマッチしたか）を確認する | +| **Admin → policy editor** | ポリシーを記述し、過去のトラフィックに対してバックテストを実施し、変更不可能なバージョンとして公開し、**library** でバージョンを比較する | +| **Admin → enforcement** | バージョンをマシンに適用し、observe モードまたは enforce モードで運用する | - ポリシーの作成や適用を変更する前に、Policyページで何がすでにマッチしているかを把握してください。 +policy editor は、失敗をルールへと変える場所です。**compose** で失敗のパターンを説明するか、ポリシーのソースコードを貼り付け、既存のトラフィックに対してドラフトをバックテストし、バージョンを公開します。 - ![判断件数とローカルおよびクラウド管理のポリシーマッピングを表示するPolicyページ。](/images/dashboard/policy-observe.png) +![ポリシーのアイデンティティ、AI支援による下書き、ソース検証、公開コントロールを備えたPolicy editorのcomposeビュー。](/images/dashboard/policy-editor.png) - エディターでは、障害条件をソースコードに変換し、検証してイミュータブルなバージョンとして公開します。 +マシン上では、`failproofai policies` でそのマシンに適用されているすべてのポリシーを確認できます。`fp policies` と `fp fleet` を使えば、ターミナルからエディターと enforcement を操作できます。詳細は [Cloud CLI リファレンス](/ja/reference/cloud-cli) を参照してください。 - ![イミュータブルなポリシーバージョンの作成と公開に使用するポリシーエディター。](/images/dashboard/policy-editor.png) +## ポリシーの取得方法 - Enforcementでは、公開済みバージョンとそのobserveまたはenforceエフェクトをマシンに割り当てます。 - - ![マシンのカバレッジと割り当て済みポリシーバージョンを表示するEnforcementフリート画面。](/images/dashboard/enforcement-fleet.png) - - デプロイ後はPolicyページで判断内容を確認し、作成画面とフリート画面が実際のエージェントアクティビティと紐付いていることを検証してください。 - - - ローカルへのポリシーのインストールと検証には `failproofai` を使用します： - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - ポリシー判断を含むクラウドのセッションやイベントを検索するには `fp` を使用します。クラウドでのポリシー作成とフリートへのデプロイは引き続きダッシュボード上での操作となります。 - - - -Failproof AI のポリシーには3つの独立した操作画面があります： - -1. **判断の分析** — セッション、ダッシュボード、監査ログで確認します。 -2. **バージョンの作成** — ビルトインルール、コード、またはポリシーエディターで作成します。 -3. **バージョンのデプロイと適用** — 対象マシンへ展開します。 - -確認済みの障害モードを起点にしてください。それを特定できる最小限のイベントとツールの条件を定義し、正常なケースと危険なケースの両方でテストを行い、適用前にまず監視モードで運用します。 +ポリシーを取得するには2つの方法があります。 - - シークレット、シェル、Git、クラウド、ワークフローに関する一般的なリスクに対応した、レビュー済みのルールを有効化します。 + + 監査結果をもとに Failproof AI にドラフトを作成させるか、自分でソースを記述し、エディターで確認・公開します。 - - ワークフロー固有の判断をJavaScriptまたはTypeScriptで記述します。 + + ユースケースに合った Failproof AI ポリシーパック、またはポリシーハブのコミュニティパックを1つのコマンドで導入します。 - \ No newline at end of file + + +## リリースする + + + + 既存のトラフィックに対してドラフトをバックテストし、ブロックすべきアクションと許可すべきアクションの両方に対して実行してから公開します。詳細は [ポリシーのテスト](/ja/policies/test) を参照してください。 + + + **observe** モードでバージョンをマシンに適用し、判断内容を確認してから enforce に移行します。詳細は [ポリシーのデプロイ](/ja/policies/deploy) を参照してください。 + + + 公開のたびに新しい変更不可能なバージョンが作成されるため、正当な作業がブロックされるロールアウトが発生しても、直前の正常なバージョンを再デプロイするだけで元に戻せます。詳細は [バージョンとロールバック](/ja/policies/rollback) を参照してください。 + + + +ポリシーを他のチームと共有するには、[パックとして公開](/ja/policies/publish-a-pack) してください。ポリシーをまったく評価できない場合の動作については、[失敗時の動作](/ja/policies/failure-behavior) を参照してください。 \ No newline at end of file diff --git a/docs/ja/policies/packs.mdx b/docs/ja/policies/packs.mdx index 81d2a918..85ecba7c 100644 --- a/docs/ja/policies/packs.mdx +++ b/docs/ja/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "ポリシーパック" -description: "GitHubリリースとして公開されたポリシーセットをインストールし、適用内容を管理します。" +title: "ポリシーパックを使用する" +description: "Failproof AI のポリシーパックやポリシーハブのコミュニティパックを用途に合わせて導入し、適用する内容を選択します。" icon: "package" --- -パックとは、GitHubリリースとして公開されたポリシーのセットです。コマンド1つでインストールでき、実行前にリリース自身のチェックサムが検証され、ダイジェストが記録されるため、インストール後にパックの内容が変更されることはありません。 +パックとは、GitHub リリースとして公開されたポリシーの集合です。インストールはコマンド1つで完了します。実行前にリリースのチェックサムが検証され、ダイジェストが記録されるため、以降はマシン上でパックが変更されることはありません。 -## Failproof AI ポリシーのインストール +すべてのパックと各パック内のすべてのポリシーは、[ポリシーハブ](https://befailproof.ai/policy-hub/)で参照できます。パックには2種類あります。 + +- **Failproof AI ポリシーパック** — あらかじめ定義されたユースケース向けの既製パックです。導入するだけですぐに使えます。[コーディングエージェント ポリシーパック](https://befailproof.ai/policy-hub/failproofai/policies/)が現在提供されており、他のユースケース向けパックも近日公開予定です。 +- **コミュニティポリシーパック** — 開発者が自身のユースケース向けに作成し、誰でも利用できるよう公開したポリシーです。 + +## Failproof AI ポリシーパック + +### コーディングエージェントポリシーパック ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -これにより、npmパッケージ内に同梱されたコピーからポリシーセットがインストールされます。ネットワーク接続は不要で、プロキシ環境でも失敗しません。一部だけインストールする場合は次のようにします： +このパックには38のポリシーが含まれており、マニフェストで無人実行時に安全とマークされた10個が自動で有効化されます。残りは選択肢として一覧表示されます。よく使われるポリシーとデフォルトの有効状態は以下の通りです。 + +| ポリシー | 動作内容 | デフォルトで有効 | +| --- | --- | --- | +| `block-push-master` | 保護ブランチへの直接プッシュをブロック | はい | +| `block-env-files` | `.env` ファイルの読み書きをブロック | はい | +| `protect-env-vars` | 環境変数をダンプするコマンドをブロック | はい | +| `block-sudo` | 許可パターンに一致しない限り `sudo` をブロック | はい | +| `block-curl-pipe-sh` | ダウンロードしたスクリプトをシェルに直接パイプすることをブロック | はい | +| `sanitize-*`（5つのポリシー） | ツール出力に含まれる API キー、ベアラートークン、JWT、秘密鍵、接続文字列を報告 | はい | +| `block-rm-rf` | 危険な再帰削除をブロック | いいえ | +| `block-force-push` | フォースプッシュをブロック | いいえ | +| `block-secrets-write` | 認証情報・秘密鍵ファイルへの書き込みをブロック | いいえ | +| `warn-destructive-sql` | `WHERE` なしの `DROP`、`TRUNCATE`、`DELETE` を警告 | いいえ | + +無効なポリシーは名前で有効化できます — `failproofai policies add block-rm-rf` — またはパック全体を `--all` で取得できます。カテゴリー別に全ポリシーを確認するには以下を実行します。 ```bash -failproofai pack add core --policy block-rm-rf # 1つ、またはカンマ区切りで複数指定 -failproofai pack add core --category dangerous-commands # カテゴリ全体 -failproofai pack add core --all # パック内のすべて +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` で、パックが提供するすべてのカテゴリを確認できます。 +## コミュニティポリシーパック -## インストール前にパックの内容を確認する +開発者が自身のユースケース向けにパックを公開しており、[ポリシーハブ](https://befailproof.ai/policy-hub/)で一覧を確認できます。コミュニティパックはその作者が公開したもので、Failproof AI による審査は行われていません。インストール前に内容を確認してください。 ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -パックに含まれるすべてのポリシーをカテゴリ別に一覧表示し、作者がデフォルトで有効にしているものとオプトインのものを区別して表示します。**マニフェストのみ**を読み込むため、エントリアーティファクトはダウンロードもインポートもされません。つまり、第三者のパックを確認しても、第三者のコードが実行されることはありません。マニフェストはリリースの `SHA256SUMS` に対して検証されるため、表示された内容がそのままインストールされます。 - -ソースを指定せずに `failproofai pack list` を実行すると、現在インストール済みのパックが一覧表示されます。 +このコマンドはパックに含まれるすべてのポリシーをカテゴリー別に表示し、作者がデフォルトで有効化しているものをマークします。**マニフェストのみ**を読み込みます — エントリーアーティファクトはダウンロードもインポートもされないため、見知らぬパックを参照しても見知らぬコードが実行されることはありません。マニフェストはリリース自体の `SHA256SUMS` に照合して検証されるため、表示される内容がそのままインストールされます。 -## 第三者のパックをインストールする +インストールするには以下を実行します。 ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -以下のいずれの形式でも使用できます： +以下のいずれの形式でも使用できます。 | ソース | 結果 | | --- | --- | -| `acme/support-agent` | 最新リリース（解決されたタグに**固定**） | -| `acme/support-agent@v2.1.0` | 指定されたリリース | -| `github:acme/support-agent@v2.1.0` | 同上（明示的な記述） | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | 同上（ブラウザからコピーしたURL） | +| `acme/support-agent` | 最新リリースを取得し、解決したタグに**固定** | +| `acme/support-agent@v2.1.0` | 指定のリリース | +| `github:acme/support-agent@v2.1.0` | 同上（明示的な記法） | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | 同上（ブラウザからコピーした URL） | -タグを指定しない場合は最新リリースがインストールされ、**そのタグに固定**されます。選択されたタグも通知されます。記録される内容は常に1つのリリースを明示するため、再インストール時にバージョンがずれることはありません。 +タグを指定しない場合、最新リリースをインストールして**固定**し、選択されたタグを通知します。記録された内容は常に特定のリリース1つを指すため、再インストール時にバージョンがずれることはありません。 -## パックの一部だけを使用する +## パックの一部だけを取得する -デフォルトでは、パックに含まれるすべてのポリシーではなく、作者が無人実行に適切と判断してデフォルト有効にした**パック自身のデフォルト**が適用されます。 +デフォルトでは、パックの**独自の**デフォルト — 作者が無人実行時に安全とマークしたポリシー — のみが有効化され、含まれるすべてのポリシーが適用されるわけではありません。 ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # 1つ、またはカンマ区切りで複数指定 +failproofai policies add FailproofAI/policies --category dangerous-commands # カテゴリー全体 +failproofai policies add FailproofAI/policies --all # パック内のすべて ``` -`--category` と `--policy` は和集合として組み合わせられます（`--only` は `--policy` の別名として使用可能）。新しいバージョンで再追加した場合、選択した内容は維持され、残りのポリシーが再び有効になることはありません。 +`--category` と `--policy` は OR 条件で組み合わせられます（`--only` は `--policy` の同義語として使用可能）。パックがすでにインストール済みの場合、フラグで指定した内容は既存の選択に追加されます。フラグなし・端末なしで再追加した場合（アップグレード時など）は、既存の選択がそのまま維持されます。端末上でフラグなしで実行すると、作者のデフォルトがあらかじめチェックされた状態でピッカーが開き、チェックした内容が選択を置き換えます。 ## 有効なポリシーを管理する ```bash -failproofai policies # パックを含むすべてのソースを一覧表示 -failproofai pack list # パックのみをカテゴリ別に表示 +failproofai policies # パックを含む全ソースを一覧表示 +failproofai policies add block-rm-rf # ポリシーを1つ有効化 failproofai policies --uninstall block-refunds # パックのポリシーを1つ無効化 -failproofai policies --install block-refunds # 再び有効化 -failproofai pack remove acme/support-agent +failproofai policies --install block-refunds # 再度有効化 +failproofai policies remove acme/support-agent # パックをアンインストール ``` -名前のみを指定した場合、同名の**組み込みポリシー**が存在すればそちらを指します。パックのコピーを明示的に指定する場合は次のようにします： +パックのポリシーの有効・無効の切り替えはマシン全体に適用されます。`--scope` の値に関わらず、この設定はプロジェクトの設定ではなくインストール済みパックに記録されます。 + +スラッシュのない名前はポリシーを、スラッシュを含む名前はパックのソースを指します。単独の名前は、それを宣言しているインストール済みパックに解決されます。2つのインストール済みパックが同じ名前を宣言している場合は、対象を明示してください。 ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -パックのポリシー名が**有効な組み込みポリシー**と重複する場合、組み込みポリシーが実行され、パックのコピーはスキップされます。同じガードが2回評価されるのを防ぐためです。パックのコピーを使用したい場合は、組み込みポリシーを無効にしてください。 - - -## Failproof AI ポリシーの提供元 - -`core` は、npmパッケージ内にベンダリングされたコピーを読み込みます。同じセットはGitHubリリースとしても公開されており、特定のバージョンが必要な場合はそちらからインストールできます： - -```bash -failproofai pack add core # パッケージ内のコピーを使用（ネットワーク不要） -failproofai pack add FailproofAI/policies # 同じセットをGitHubリリースから取得 -``` +スコープ、パラメーター、およびこれらのコマンドが書き込むファイルの詳細については、[ローカル設定](/ja/policies/local-configuration)を参照してください。 -## 整合性チェックで保証されること・されないこと +## 整合性検証で保証されること・されないこと -`SHA256SUMS` はアーティファクトと同じリリースに含まれるため、**署名ではなく**、誰が公開したかを証明するものではありません。ただし、バイトがそのリリースで公開されたものと一致することを証明します。パック追加時にダイジェストが記録され、インポート前に毎回再検証されるため、インストール後にパックの内容が変更されることはありません。アセットの再タグ付けや置き換えが行われたリポジトリは、気づかないまま別のコードを実行するのではなく、ロードに失敗します。 +`SHA256SUMS` はアーティファクトと同じリリースに含まれているため、**署名ではなく**、誰が公開したかを証明するものではありません。証明されるのは、バイト列がそのリリースが公開したものと一致するということです。また、パックを追加した際にダイジェストが記録され、インポート前に毎回再検証されるため、以降はマシン上でパックが変更されることはありません。タグを付け直したりアセットを差し替えたりしたリポジトリは、他のものを静かに実行するのではなく、読み込みに失敗するようになります。 -インストール時にはパックが一度**インポートされ**、自身のマニフェストと照合されます。アーティファクトがパースできない場合、または宣言内容と異なるものを登録しようとする場合は、何かが有効化される前に拒否されます。クリーンにインストールされてから次のツール呼び出し時に失敗するような事態にはなりません。 +インストール時にはパックが**一度インポートされ**、自身のマニフェストと照合されます。アーティファクトが解析できないパック、または宣言された内容以外のものを登録しようとするパックは、何かが有効化される前に拒否されます。これにより、クリーンにインストールされた後に次のツール呼び出しで失敗するという事態を防ぎます。 -## パックがロードされない場合 +## パックが読み込まれない場合 -適用するよう設定されているパックが実行できない場合、そのパックがカバーしていたイベントは暗黙的に許可されるのではなく、**拒否**されます。詳細は[失敗時の動作](/ja/policies/failure-behavior)を参照してください。`failproofai pack list` はそのような状態のパックを表示し、ゼロ以外の終了コードで終了します。 +このマシンに適用するよう設定されたパックが実行できない場合、欠落しているポリシーが対象とするイベントを暗黙的に許可するのではなく、**拒否**します — `pack/failproofai-pack-unavailable` として処理され、読み込まれたポリシーよりも優先されるため、拒否は最初に発火したガードではなく欠落したパックに帰属します。例外は `UserPromptSubmit` で、こちらは拒否ではなく指示として処理されます。拒否するとエージェントにアクセスできなくなり、問題を修正できなくなるためです。詳細は[障害時の動作](/ja/policies/failure-behavior)を参照してください。 -## オフライン環境とミラー +## オフラインとミラー | 変数 | 効果 | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | フェッチを拒否。インストール済みのパックは引き続き適用される | -| `FAILPROOFAI_PACK_BASE_URL` | `github.com` の代わりにミラーからパックを取得 | +| `FAILPROOFAI_NO_DOWNLOAD=1` | フェッチを拒否します。インストール済みのパックは引き続き適用されます | +| `FAILPROOFAI_PACK_BASE_URL` | パックのフェッチ先を `github.com` ではなく指定のミラーに向けます | -独自パックの公開方法については、[パックを公開する](/ja/policies/publish-a-pack)を参照してください。 \ No newline at end of file +独自のポリシーをこの方法で共有する方法については、[ポリシーパックを公開する](/ja/policies/publish-a-pack)を参照してください。 \ No newline at end of file diff --git a/docs/ja/policies/publish-a-pack.mdx b/docs/ja/policies/publish-a-pack.mdx index 78a8a25d..f927c3d2 100644 --- a/docs/ja/policies/publish-a-pack.mdx +++ b/docs/ja/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "パックを公開する" -description: "自分のポリシーをGitHubリリースとして公開し、誰でもインストールできるようにする。" +title: "ポリシーパックを公開する" +description: "独自のポリシーをGitHubリリースとして配布し、誰でもインストールできるようにします。" icon: "upload" --- -パックはGitHubリリースに添付された3つのファイルで構成されます。`failproofai pack build` は既存のポリシーファイルからこの3つを生成します。 +パックは、GitHubリリースに添付された3つのファイルで構成されています。`failproofai publish` は、指定されたポリシーファイルからこれら3つのファイルをすべて生成し、リリースを作成してアップロードします。 -## 1. ポリシーを書く +## 1. ポリシーを作成する -カスタムポリシーと同じAPIを使った1つのファイルで記述します。パック固有のフィールドが2つあります： +空白のテンプレートではなく、すでに機能しているものから始めましょう： + +```bash +failproofai publish --init +``` + +パックの名前を尋ねた後、`.mjs` を作成して終了します — ネットワーク接続も、gitも、公開も一切行いません。作成されるファイルには `git push --force` をブロックするポリシーが1つ含まれています。既存のファイルは上書きしません。 + +ポリシーは、カスタムポリシーと同じAPIを使用します。パック向けに重要な追加フィールドが2つあります： ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` を省略した場合、デフォルトは **false** になります。通常の `failproofai pack add` は、マークしたポリシーのみを有効化します。見知らぬパックのすべてのポリシーを無人でインストールするかどうかは、インストーラーがユーザーに代わって決める判断ではありません。 +`defaultEnabled` を省略すると、デフォルトで **false** になります。単純な `failproofai policies add` は、マークしたポリシーのみを有効化します — 見知らぬ人のすべてのポリシーを無人でインストールするかどうかは、インストーラーがユーザーの代わりに決めるべき判断ではありません。 + +ファイルはいくつでも作成できます。カテゴリごとに1ファイルにすると読みやすくなります。ポリシーを登録するディレクトリ内のすべてのファイルは、パックが持つべき単一のアーティファクトにバンドルされます。 -エントリは**自己完結した1つのファイル**でなければなりません。ダイジェストが固定されるのはエントリのみであるため、ローカルファイルをインポートするパックは、ダイジェストが実行内容をカバーしていると正直に主張できません。先にバンドル（`esbuild`、`bun build`、`rollup`）し、バンドルからパックをビルドしてください。`pack build` はローカルインポートを検出した場合、守れない約束を出荷するのではなくビルドを拒否します。 + バンドルには **bun** が必要です。bun がない場合は、1つの自己完結型ファイルに留めてください。いずれの場合も、公開されたエントリはインストール時にローカルファイルをインポートしてはなりません。ダイジェストがピン留めされるのはエントリのみであるため、兄弟ファイルを参照するパックは、実行内容をダイジェストが保証しているとは言えません — そのため `publish` は、守れない約束を出荷するくらいなら拒否します。 -## 2. リリースアセットをビルドする +## 2. まずここで試す + +他の人が確認できるようになる前に、このマシンでファイルを強制適用します： ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +パスもファイル名も自由です。ブロックした操作をエージェントに実行させ、拒否されることを確認してください。何も公開されず、他のユーザーには影響しません。残りの手順（許可すべき正当なケースと、ポリシーを壊す入力のテスト）については、[ポリシーのテスト](/ja/policies/test)を参照してください。 + +## 3. 公開する + +```bash +failproofai publish ``` -3つのファイルを生成し、すべてのポリシーを**ローダー自身のルール**で事前に検証します。インストールできないパックは、修正できるこの段階で失敗します： +どこに公開するか、何をバンドルするか、バージョン番号は何にするかを自動で判断し、リポジトリから何も判断できない場合にのみ確認します。リリース作成前に問題があれば停止します。処理の順序は以下のとおりです： + +1. ファイル名ではなく **コンテンツ** でポリシーファイルを検索します — `failproofai` をインポートして `customPolicies.add` を呼び出しているものを対象にするため、`guards.mjs` は検出されますが、無関係な `policies.mjs` は無視されます。サブディレクトリには降りないため、テストフィクスチャが誤って含まれることはありません。 +2. **ファイルの** ディレクトリ（作業ディレクトリではなく）で `git remote get-url origin` からリポジトリを読み取り、バージョンを決定します。 +3. 認証情報を検索します：`GITHUB_TOKEN`、`GH_TOKEN`、または `gh auth login`。release-write 権限のみ必要で、表示されることはありません。 +4. リポジトリが存在しない場合は作成します。これはビルド前に行われるため、次のステップで拒否されたパックは、リリースのない新しいリポジトリを残す可能性があります。 +5. 3つのアセットをビルドし、**ローダー自身のルール** — 見知らぬマシンにインストールできるものを決定するのと同じコード — で検証します。そのため、インストールできないパックはここで失敗し、まだ修正できます。 +6. リリースを作成または再利用してアップロードし、同名のアセットは置き換えます。 | ファイル | 内容 | | --- | --- | -| `failproofai-pack.json` | マニフェスト：id、バージョン、エフェクト、各ポリシーのエントリ | -| `failproofai-pack.mjs` | エントリファイル（そのまま） | -| `SHA256SUMS` | 他の2ファイルに対する ` ` | +| `failproofai-pack.json` | マニフェスト：id、バージョン、エフェクト、ポリシーごとのエントリ | +| `failproofai-pack.mjs` | バンドルされたエントリ | +| `SHA256SUMS` | 他の2ファイルの ` ` | -ビルド時に拒否されるケース：`publisher/name` 形式でないid、`/` を含むポリシー名、`alwaysOn` を宣言するポリシー、`description`・`category`・`match` のいずれかが欠けている場合、何も登録しないエントリ、ローカルファイルをインポートするエントリ。 +アセット名は固定です — これはコンシューマーのCLIがAPIコールや探索なしにURLを構築するために使用するものだからです。 -## 3. リリースに添付する +ビルド時に拒否されるもの：`publisher/name` 形式でないid、`/` を含むポリシー名、`alwaysOn` を宣言するポリシー、`description`・`category`・`match` のいずれかが欠けているポリシー、何も登録しないエントリ、ローカルファイルをインポートするエントリ。 -ビルドと同じバージョンでリリースにタグを付け、3つのファイルをリリースアセットとして添付します： +自動判断した内容を上書きするには： ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -誰でも以下でインストールできます： +`--id` はリポジトリと異なる場合にパックidを設定し、`--tag` はリリースのタグを設定します。`--notes` は自動生成されたリリースノートを置き換えます（`policies show --releases` が各リリースのカウントとコミットを読み取る場所）。`--out` はアセットの出力先を指定し（デフォルトは `dist-pack`）、`--dry-run` は公開せずにビルドのみ行い、認証情報は不要です。 -```bash -failproofai pack add acme/support-agent -``` +これで `failproofai policies add acme/support-agent` を使って誰でもインストールできるようになります。バージョンのピン留めや一部のみのインストールについては、[ポリシーパック](/ja/policies/packs)を参照してください。 + +### ポリシーハブに登録する + +GitHubのリポジトリに `failproofai-policies` トピックを追加してください。申請フォームも承認キューもありません：[ポリシーハブ](https://befailproof.ai/policy-hub/)のクローラーが次回のパスでリポジトリを検出します。トピックは掲載の候補に挙げるだけです — 実際に掲載されるのは、マニフェストが自身の `SHA256SUMS` に対して検証され、CLIが使用するのと同じルールでパースされるリリースが存在する場合で、それはまさに `failproofai publish` が生成するものです。 + +## バージョンの決定方法 + +バージョンは **公開元のコミット** — 12文字の短縮sha：`a1b2c3d4e5f6` です。選択するものも、インクリメントするものも何もありません。バージョンはバイトがどこから来たかを正確に示すため、同じソースを2回公開すると同じバージョンになります。 + +バージョンはリポジトリのリリースからではなく、目の前のツリーから読み取られるため、フレッシュなクローンとエアギャップ環境のマシンは、GitHubに何があったかを尋ねることなく同じ答えを計算します。 + +バージョンはコミットを指しているため、そのコミットが存在する必要があります。ターミナルでは、`publish` が代わりにコミットを作成します：リポジトリがない場合は初期化し、変更されたポリシーファイルをビルド前にコミットします。ターミナルなしで実行された場合（CIランナーで作成されたコミットは他の場所には存在しない）、ポリシー以外のファイルがコミットされていない場合、またはまだコミットがないチェックアウトでは、**拒否** します — `--version` が回避策として案内されます。`HEAD` にタグがある場合はshaよりタグが優先されます — `v1.2.0` とタグを付けた人はこのリリースが何であるかを宣言しています。 + +shaにはそれ自体の順序付けがないため、`failproofai policies show / --releases` を使用して、どのリリースが先かを確認してください — 最新が上に表示されます。 -アセット名は固定されています。コンシューマーのCLIはAPIコールや探索なしに、この名前からURLを構築します。 +## 新しいバージョンを配布する -## 新しいバージョンを公開する +変更をコミットして `failproofai publish` を再実行してください — 新しいコミットが新しいバージョンになります。コンシューマーは同じ `failproofai policies add` を実行します。ターミナルなし、または選択フラグがある場合、選択したサブセットが保持され、無効にしたポリシーはオフのままです。ターミナルありでフラグなしの場合、ピッカーがデフォルト設定でチェック済みの状態で開き、選択した内容が以前の選択を置き換えます。 -新しい `--version` でビルドし、新しいリリースにタグを付け、3つのアセットを再度添付します。コンシューマーは同じ `pack add` を実行すれば、以前選択したサブセットが引き継がれます。オフにしたポリシーはアップグレード後もオフのままです。 +ポリシーの **名前** を変更することは破壊的変更です：無効にしていたマシンは存在しない名前をオフにしていることになり、新しい名前は `defaultEnabled` の設定で有効化されます。 -ポリシーの **name** を変更すると破壊的変更になります。オフにしていたマシンは存在しない名前をオフにしようとし、新しい名前は `defaultEnabled` の設定に従って有効化されます。 +## ユーザーが信頼しているもの -## ユーザーが信頼していること +`SHA256SUMS` はアーティファクトと同じリリースに存在するため、バイトが公開したものであることを証明しますが、あなたが誰であるかは証明しません。リポジトリへの書き込み権限を持つ人は誰でも両方のファイルを書き換えられます。ユーザーの保護は、インストール時にダイジェストがピン留めされることで、配布後に内容を変更できなくなることです。 -`SHA256SUMS` はアーティファクトと同じリリースに含まれるため、公開したバイトであることは証明できますが、あなたが誰であるかは証明しません。リポジトリへの書き込みアクセスを持つ人は両方のファイルを書き換えることができます。ユーザーを守るのは、インストール時にダイジェストが固定されるという仕組みです。インストール後に公開内容が改ざんされても、ユーザーに影響はありません。 +書き込みアクセスを管理しているリポジトリから公開し、パックのリリースはパッケージの公開と同様に扱ってください。 -書き込みアクセスを自分で管理するリポジトリから公開し、パックリリースをパッケージの公開と同様に扱ってください。 +リポジトリは **公開** されている必要があります。インストールは認証情報のない匿名HTTPSで行われるため、既存のプライベートリポジトリはビルドやアップロード前に拒否され、`publish` が作成するリポジトリも同じ理由で公開されます。`--allow-private` は、3つのアセットを別の方法で渡す場合に上書きできますが、`policies add` ではアクセスできないことを明示します。重要なのはリリースのみです：インストールは `releases/download//` を読み取り、gitツリーには一切アクセスしません。 -## 適用前に観察する +## 強制適用前にオブザーブする -マニフェストには `"effect": "observe"` を宣言できます。このポリシーは実行されますが、判定は**記録されるだけで破棄**されます。何もブロックしません。実際のトラフィックに対して新しいルールを計測し、誰の作業も妨げることなく検証するための方法です。 +マニフェストは `"effect": "observe"` を宣言できます — `failproofai publish --effect observe` で設定します。これらのポリシーは実行され、その判定は **記録されますが破棄されます** — 何もブロックされません。誰かの作業を妨げる前に、実際のトラフィックに対して新しいルールを測定する方法です。 ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/ja/policies/rollback.mdx b/docs/ja/policies/rollback.mdx index 28cb39df..18664822 100644 --- a/docs/ja/policies/rollback.mdx +++ b/docs/ja/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "ロールバック" -description: "ロールアウトが有効なエージェントの作業を妨害した場合に、既知の正常なポリシーデプロイメントを復元します。" +title: "バージョンとロールバック" +description: "公開されたものはすべて不変のバージョンとなるため、有効なエージェントの作業を妨げるロールアウトは、最後の正常なバージョンを再デプロイすることで元に戻せます。" icon: "rotate-ccw" --- -ロールバックは、デプロイされたバージョンを変更するか、ポリシーの割り当てを削除します。インシデントの経緯を説明する判断履歴は消去されません。 +公開されたポリシーバージョンは変更されません。ポリシーを編集して再公開すると新しいバージョンが作成されますが、すでにマシン上にあるバージョンが上書きされることはありません。これによりロールバックが安全に行えます。最後の正常なバージョンはバイト単位でそのまま残っており、ロールバックしても何が問題だったかを説明する意思決定の履歴は消去されません。 -## マシンをロールバックする +## バージョンを確認する - 1. **Admin → enforcement** に移動し、影響を受けたマシンを展開して、最後に正常であることが確認されたポリシーセットを特定します。 - 2. **edit** を選択し、それらのバージョンと効果を復元して、新しいデプロイメントを適用します。 - 3. マシンのチェックインを待ち、レポートされたデプロイメントを確認します。 - 4. **Observe → policy** および影響を受けたセッションを開き、有効な作業がブロックされなくなったことを確認します。 + **Admin → policy editor** に移動し、**library** を開いてポリシーのバージョンを比較したり、無効化したりできます。 + + + ```bash + fp policies list # every policy version + fp policies show # one version, with its source + ``` + + + +## マシンをロールバックする + + + 1. **Admin → enforcement** に移動し、対象のマシンを展開して、最後に正常だとわかっているポリシーセットを特定します。 + 2. **edit** を選択し、そのバージョンと効果を復元して新しいデプロイを適用します。 + 3. マシンのチェックインを待ち、報告されたデプロイを確認します。 + 4. **Observe → policy** と対象のセッションを開き、有効な作業がブロックされなくなったことを確認します。 - クラウドデプロイメントのロールバックはダッシュボードのワークフローです。ローカルのステータスを使用して、修正済みのデプロイメントがマシンに届いたことを確認してください: + マシンへのデプロイはそれぞれ番号付きのジェネレーションです。一覧を確認してから、特定のジェネレーションに戻します。 ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` は、1 つのローカルセッションに対してビルトイン、カスタム、およびコンベンションポリシーを一時停止します。クラウド管理ポリシーは一時停止されないため、不正なクラウドデプロイメントの回避策にはなりません。 + `rollback` はカウンターを巻き戻すのではなく、古いセットを持つ新しいジェネレーションを作成するため、履歴は追記専用のまま維持されます。また、無効化または削除されたポリシーを参照するジェネレーションへのロールバックは拒否されます。実行には `policies:write` 権限を持つサインイン済みセッションが必要です。`fp fleet diff ` は意図されたものとマシンが実際に適用したものとの差異を表示します。マシンが次回ポーリングするまでは `behind` と表示されます。マシン上では `failproofai policies` を実行すると、現在実行中のデプロイが一覧表示されます。 -## ロールバックが必要なケース +## 全マシンから特定のポリシーを削除する + +```bash +fp policies disable # remove it from every deployment carrying it +fp policies enable # add it back +``` + +これらのコマンドはそれぞれ、対象となるすべてのデプロイに新しいジェネレーションを作成します。ただし、それらのジェネレーションのいずれかをロールバックしても `disable` を元に戻すことはできません。`rollback` は無効化されたポリシーを参照するジェネレーションへのロールバックを拒否しており、無効化以前のすべてのジェネレーションはそのポリシーを参照しているからです。元に戻す方法は `fp policies enable` であり、これがまた独自のジェネレーションを作成します。 + +## パックをロールバックする + +パックはインストール時のリリースに固定されているため、ロールバックするには古いバージョンをインストールします。 + +```bash +failproofai policies show FailproofAI/policies --releases # every version it has published, and which one is here +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # pin that one +``` + +ターミナルを使用しない場合、または `--policy`、`--category`、`--all` を指定する場合、再追加を行うと以前選択していたサブセットが保持されます。ターミナルを使用し、これらのオプションを指定しない場合は、作者のデフォルトがあらかじめチェックされた状態でピッカーが開きます。チェックした内容が現在の選択を置き換えるため、以前の選択を再度チェックしてください。 + +## ロールバックするタイミング -- ポリシーが想定された本番環境のアクションをブロックしている。 -- マッチ件数が、観測されたロールアウトの予測を大幅に上回っている。 +- ポリシーが想定されている本番環境の操作をブロックしている。 +- マッチ件数が、観測されたロールアウトが予測していた数値を大幅に上回っている。 - ポリシーが、インテグレーションから提供されないフィールドに依存している。 -- 新しいバージョンが、意図した障害モード以外の動作を変更した。 +- 新しいバージョンが、意図した障害モード以外の動作を変更している。 -ロールバック後、影響を受けたセッションを開き、誤検知の原因となった条件を特定してください。新しいバージョンを作成し、安全でないケースと正当なケースの両方をテストしてから、オブザーブフェーズを繰り返してください。 +ロールバック後は、対象のセッションを開いて誤検知の原因となった条件を特定してください。新しいバージョンを公開し、安全でないケースと正当なケースの両方を[テスト](/ja/policies/test)してから、再度適用する前に動作を観察してください。 - インシデント発生中にエンフォースメントを一時停止することは適切な場合もありますが、そのスコープ内のすべてのアクティブなポリシーに対してリスクが広がります。可能な限り、特定のポリシーバージョンをロールバックすることを優先してください。 + `failproofai config --pause` はローカルポリシーを1セッションの間停止しますが、クラウド管理のポリシーには一切効果がありません。そのため、クラウドデプロイの問題を解決する手段にはなりません。また、一時停止はそのスコープ内のすべてのポリシーの露出を広げます。問題のある特定のバージョンをロールバックすることを優先してください。 \ No newline at end of file diff --git a/docs/ja/policies/test.mdx b/docs/ja/policies/test.mdx new file mode 100644 index 00000000..77178d8a --- /dev/null +++ b/docs/ja/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "ポリシーをテストする" +description: "既存のトラフィックに対してドラフトをバックテストし、ブロックすべき操作を確実に止め、許可すべき操作を確実に通過させることを、実際に適用される前に検証します。" +icon: "flask-conical" +--- + +ポリシーは必ず2つの方法でテストしてください。エージェントが既に生成したトラフィックに対するテストと、必ず通過させなければならない正当な操作に対するテストです。安全でないケースしか確認していないポリシーは、テスト済みとは言えません。 + +## ドラフトをバックテストする + + + + ポリシーエディタは、公開前にドラフトをフリート（全エージェント群）が実際に行った呼び出しに対して再実行します。 + + 1. **Admin → policy editor** でドラフトを開きます。エディタはJavaScriptとして正しくパースされることを確認します。 + 2. **backtest** で、再実行するエージェントと時間ウィンドウを選択します。デフォルトは **every agent** と **30d** です。範囲を絞り込みたい場合を除き、最後のフィルターは **everything** のままにしてください。 + 3. **run backtest** を選択します。 + + ![JavaScriptとして正しくパースされるドラフトの下にあるバックテストパネル。3つのフィルターとrun backeastアクション、その上のpublish versionが表示されている。](/images/dashboard/policy-backtest.png) + + 結果は、ドラフトがそれらの呼び出しに対してどのような動作をしたかを示します。**正常に動作していた**呼び出しのうち、どれだけが中断されていたかも含まれます。これは、エージェントが実際に遭遇する前に発見された誤検知です。その数が許容できるレベルになるまで、ドラフトを調整して再実行してください。 + + + バックテストはダッシュボードの機能です。ターミナルからは、代わりに以下の方法で自分で定義したイベントに対してポリシーを実行できます。 + + + +## 自分で定義したイベントに対して実行する + +`fp policies test` は、ポリシーファイルをローカルマシン上で合成イベントに対して実行し、判定結果を確認します。何も公開されず、クラウドにも何も送信されません。 + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +`--event`、`--tool`、`--command`、`--file` でイベントの内容を指定します。ポリシー自身の `match` フィルターは引き続き適用されるため、指定したイベントをカバーしていないポリシーは判定ではなく `skipped` を返します。これはたいていの場合、`match` の範囲が意図より狭くなっているサインです。 + +## 1台のマシンで実行する + +次に、自分のマシン上で自分のエージェントに対して実際に適用してみます。 + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +最初のコマンドはファイルを検証してインストールします。2番目のコマンドは、このマシンで適用されている他のすべてのポリシーとともに、正しく読み込まれたことを確認します。ポリシーがブロックする操作をエージェントに試させて拒否されることを確認し、次に正当な操作を試させて通過することを確認します。他の誰にも影響はありません。 + +クラウドに接続されたマシンでは、**Observe → policy** で両方の判定結果を確認します。ポリシー名でフィルタリングし、リンクされた各セッションを開いて、マッチしたツール入力と返された理由を確認してください。 + +## 壊れたケースをテストする + +インストールは、ファイルが存在しない場合、構文エラー、未解決のインポート、トップレベルの例外、またはロード中にタイムアウトするモジュールがある場合に失敗します。そのため、ファイルまたはインポートしているものを変更するたびに再実行してください。適用時には、同様に壊れたファイルはログに記録され **skipped** されるため、他のすべてのポリシーは引き続き実行されます。本番ログのロード警告は適用の欠落として扱ってください。Conventionファイルはインストールコマンドなしで読み込まれるため、CIには明示的な `failproofai policies --install --custom ` ステップを含めてください。これが壊れたポリシーでビルドを失敗させる仕組みです。 + +次に、期待する入力だけでなく、エージェントが実際に送信するものをすべて与えてテストしてください。フィールドの欠落、`Write` や `Edit` などの別のツール名、Windowsパス、不正な形式の入力などです。すべてのコードパスで意図的に `allow`、`instruct`、または `deny` を返し、関数を決定論的に保ち、外部呼び出しには短いタイムアウトを設定してください。 + +## 公開して観察する + +バックテストは、既存のトラフィックに対してポリシーが何をしたかを示しますが、まだ見ていないトラフィックがどう動くかは示せません。エディタで **publish version** を選択（または `fp policies publish` を実行）し、まず **observe** モードで[デプロイ](/ja/policies/deploy)してください。このモードでは判定結果が記録されるだけで何もブロックされません。マッチした結果が安全でない操作と正当な操作を正しく分離できていることを確認してから、実際の適用に切り替えてください。 \ No newline at end of file diff --git a/docs/ja/reference/cloud-cli.mdx b/docs/ja/reference/cloud-cli.mdx index a1ab744a..c32b4b48 100644 --- a/docs/ja/reference/cloud-cli.mdx +++ b/docs/ja/reference/cloud-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof Cloud CLI" -description: "fp を使った Failproof AI Cloud のクエリと管理の完全リファレンス。" +description: "fp を使用した Failproof AI Cloud のクエリと管理の完全リファレンス。" icon: "cloud-cog" --- -`fp` を使って、Cloud テレメトリの確認、クラウド管理の強制適用（ポリシー、フリートデプロイ、ガードレールの判定）、および監査・検出結果・課題・アラート・キー・ユーザー・クエリ・設定の管理を行います。ローカルフック、ポリシー、キャプチャ、マシンの登録には [`failproofai`](/ja/reference/failproof-cli) を使用してください。 +`fp` を使用して、Cloudのテレメトリの検査、クラウド管理の適用（ポリシー、フリートデプロイメント、ガードレール決定）の管理、および監査、所見、課題、アラート、キー、ユーザー、クエリ、設定の管理を行います。ローカルフック、ポリシー、キャプチャ、マシン登録には [`failproofai`](/ja/reference/failproof-cli) を使用してください。 -リリース済み Cloud CLI を独立したツールとしてインストールします： +リリース済みの Cloud CLI を独立したツールとしてインストールします： ```bash uv tool install fp-cloud-cli @@ -32,19 +32,19 @@ fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] fp --json sessions --since 24h ``` -ターミナルのヘルプを表示するには `fp COMMAND --help` または `fp COMMAND SUBCOMMAND --help` を実行してください。 +ターミナルヘルプを表示するには `fp COMMAND --help` または `fp COMMAND SUBCOMMAND --help` を実行してください。 -## CLI コマンド +## CLIコマンド ### 認証 | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp login` | メールで届いたワンタイムコードでサインインし、組織を選択する。 | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | 保存済みユーザーセッションを失効・削除する。 | — | -| `fp whoami` | 現在のID、認証モード、組織、権限を表示する。 | — | -| `fp version` | インストール済み CLI のバージョンを表示する。 | — | -| `fp help` | トップレベルのコマンドヘルプを表示する。 | — | +| `fp login` | メールで送信されたワンタイムコードでサインインし、組織を選択します。 | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | 保存されたユーザーセッションを無効化して削除します。 | — | +| `fp whoami` | 現在のID、認証モード、組織、および権限を表示します。 | — | +| `fp version` | インストールされているCLIバージョンを表示します。 | — | +| `fp help` | トップレベルのコマンドヘルプを表示します。 | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,24 +57,24 @@ fp whoami fp events [OPTIONS] ``` -個別のエージェントイベントを一覧表示します。デフォルトの軽量フィードは生のペイロードを除外します。`--full` は限定的な調査にのみ使用してください。 +個々のエージェントイベントを一覧表示します。デフォルトのライトフィードは生のペイロードを除外します。`--full` は範囲を限定した調査にのみ使用してください。 | オプション | 説明 | | --- | --- | -| `--limit`, `-n ` | 最大総行数。デフォルト：`50`。 | +| `--limit`, `-n ` | 最大合計行数。デフォルト：`50`。 | | `--since ` | `all`、`15m`、`1h`、`6h`、`24h`、または `7d`。 | -| `--from ` / `--to ` | ISO 8601 UTC 範囲。`--since` を上書きする。 | -| `--env ` | 環境フィルター。繰り返しまたはカンマ区切りで複数指定可。 | -| `--event-type ` | イベントタイプフィルター。繰り返しまたはカンマ区切りで複数指定可。 | -| `--agent-id ` | エージェントフィルター。繰り返しまたはカンマ区切りで複数指定可。 | -| `--session-id ` | セッションフィルター。繰り返しまたはカンマ区切りで複数指定可。 | -| `--search ` | ペイロードテキスト検索。繰り返し可能で、いずれかの語句に一致。 | -| `--order asc\|desc` | 時刻の順序。デフォルト：新しい順。 | -| `--all` | `--limit` まで自動ページネーション。 | -| `--cursor ` | 不透明なカーソルから再開する。 | +| `--from ` / `--to ` | ISO 8601 UTC範囲。`--since` より優先されます。 | +| `--env ` | 環境フィルター。値を繰り返すかカンマ区切りで指定します。 | +| `--event-type ` | イベントタイプフィルター。値を繰り返すかカンマ区切りで指定します。 | +| `--agent-id ` | エージェントフィルター。値を繰り返すかカンマ区切りで指定します。 | +| `--session-id ` | セッションフィルター。値を繰り返すかカンマ区切りで指定します。 | +| `--search ` | ペイロードテキスト検索。繰り返し指定可能で、いずれかの語句が一致します。 | +| `--order asc\|desc` | 時間順。デフォルト：新しい順。 | +| `--all` | `--limit` まで自動ページネーションします。 | +| `--cursor ` | 不透明なカーソルから再開します。 | | `--page-size ` | `--all` 使用時のリクエストごとの行数。最大 `200`。 | -| `--full` | 重いイベントエンドポイント経由で生のペイロードを含める。 | -| `--fields ` | 選択したフィールドのみ返す。`payload` を指定するとフルモードが有効になる。 | +| `--full` | より重いイベントエンドポイントを通じて生のペイロードを含めます。 | +| `--fields ` | 選択したフィールドのみを返します。`payload` を指定するとフルモードが有効になります。 | ```bash fp events --session-id --order asc --all --limit 10000 @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` は **`--limit` まで**ページネーションを行いますが、デフォルトは **50** です — そのため `--all` 単体では 50 行で停止します。早期停止した場合、レスポンスには再開用の `next_cursor` が含まれます。`"next_cursor": null` はフィードが本当に終了したことを意味します。 + `--all` は **`--limit` まで**ページネーションします。デフォルトは **50** です。つまり、`--all` を単独で使用すると50行で停止します。早期に停止した場合、レスポンスには再開用の `next_cursor` が含まれます。`"next_cursor": null` はフィードが実際に終了したことを意味します。 ### セッション @@ -93,19 +93,19 @@ fp sessions [OPTIONS] | オプション | 説明 | | --- | --- | -| `--limit`, `-n ` | 最大総行数。デフォルト：`50`。 | +| `--limit`, `-n ` | 最大合計行数。デフォルト：`50`。 | | `--since ` | `all`、`15m`、`1h`、`6h`、`24h`、または `7d`。 | -| `--from ` / `--to ` | ISO 8601 UTC 範囲。`--since` を上書きする。 | -| `--env ` | 環境フィルター。繰り返しまたはカンマ区切りで複数指定可。 | -| `--status ` | `done`、`error`、または `timeout`。繰り返しまたはカンマ区切りで複数指定可。 | -| `--agent-id ` | 選択したエージェントのいずれかを含むセッションに一致。 | -| `--session-id ` | セッションフィルター。繰り返しまたはカンマ区切りで複数指定可。 | -| `--all` | `--limit` まで自動ページネーション。 | -| `--cursor ` | 不透明なカーソルから再開する。 | +| `--from ` / `--to ` | ISO 8601 UTC範囲。`--since` より優先されます。 | +| `--env ` | 環境フィルター。値を繰り返すかカンマ区切りで指定します。 | +| `--status ` | `done`、`error`、または `timeout`。値を繰り返すかカンマ区切りで指定します。 | +| `--agent-id ` | 選択したエージェントが関与するセッションに一致します。 | +| `--session-id ` | セッションフィルター。値を繰り返すかカンマ区切りで指定します。 | +| `--all` | `--limit` まで自動ページネーションします。 | +| `--cursor ` | 不透明なカーソルから再開します。 | | `--page-size ` | `--all` 使用時のリクエストごとの行数。最大 `200`。 | -| `--fields ` | 選択したフィールドのみ返す。 | -| `--full-ids` | ターミナル出力でセッション ID を短縮しない。 | -| `--agents` | マルチエージェントセッションのエージェント一覧を展開する。 | +| `--fields ` | 選択したフィールドのみを返します。 | +| `--full-ids` | ターミナル出力でセッションIDを短縮しません。 | +| `--agents` | マルチエージェントセッションのエージェントリストを展開します。 | ### 評価 @@ -115,15 +115,15 @@ fp evals [OPTIONS] | オプション | 説明 | | --- | --- | -| `--aggregate` | 個別の評価ではなく、合計値とスコアごとの統計を表示する。 | +| `--aggregate` | 個々の評価の代わりに合計とスコアごとの統計を表示します。 | | `--limit`, `-n ` | 最大リスト行数。デフォルト：`50`。 | -| `--since`, `--from`, `--to` | 時間範囲を選択する。 | -| `--env`, `--status`, `--agent-id`, `--session-id` | 各フィルターで1つの値に絞り込む。 | -| `--score KEY:MIN..MAX` | スコア範囲。繰り返し可能で、すべての範囲に一致する必要がある。 | -| `--all`, `--cursor`, `--page-size` | リストのページネーションを制御する。 | -| `--fields ` | 選択したフィールドのみ返す。 | -| `--full-ids` | 完全なセッション ID を表示する。 | -| `--scores-full` | ターミナル出力ですべてのスコアを表示する。 | +| `--since`, `--from`, `--to` | 時間範囲を選択します。 | +| `--env`, `--status`, `--agent-id`, `--session-id` | フィルターごとに1つの正確な値に絞り込みます。 | +| `--score KEY:MIN..MAX` | スコア範囲。繰り返し指定可能で、すべての範囲が一致する必要があります。 | +| `--all`, `--cursor`, `--page-size` | リストのページネーションを制御します。 | +| `--fields ` | 選択したフィールドのみを返します。 | +| `--full-ids` | 完全なセッションIDを表示します。 | +| `--scores-full` | ターミナル出力にすべてのスコアを表示します。 | ### エラー @@ -133,118 +133,118 @@ fp errors [OPTIONS] | オプション | 説明 | | --- | --- | -| `--aggregate` | 行を一覧表示するのではなく、一致するエラーを集計する。 | +| `--aggregate` | 行の一覧表示の代わりに一致するエラーを集計します。 | | `--limit`, `-n ` | 最大リスト行数。デフォルト：`50`。 | -| `--since`, `--from`, `--to` | 時間範囲を選択する。 | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | エラーの対象を絞り込む。 | -| `--search ` | ペイロードテキストを検索する。繰り返し可能。 | -| `--order asc\|desc` | 時刻の順序。 | -| `--all`, `--cursor`, `--page-size` | リストのページネーションを制御する。 | -| `--fields ` | 選択したフィールドのみ返す。 | -| `--full-ids` | 完全なセッション ID を表示する。 | +| `--since`, `--from`, `--to` | 時間範囲を選択します。 | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | エラーの対象を絞り込みます。 | +| `--search ` | ペイロードテキストを検索します。繰り返し指定可能。 | +| `--order asc\|desc` | 時間順。 | +| `--all`, `--cursor`, `--page-size` | リストのページネーションを制御します。 | +| `--fields ` | 選択したフィールドのみを返します。 | +| `--full-ids` | 完全なセッションIDを表示します。 | ### 使用状況とフィルター値 | コマンド | 目的 | | --- | --- | -| `fp usage` | 現在の計測ウィンドウの使用状況を表示する。 | -| `fp list envs` | 観測された環境を一覧表示する。 | -| `fp list agents` | 観測されたエージェント ID を一覧表示する。 | -| `fp list event_types` | イベントタイプを一覧表示する。 | -| `fp list score_filters` | 評価スコアのキーを一覧表示する。 | -| `fp list models` | モデル名を一覧表示する。 | -| `fp list hooks` | フック名を一覧表示する。 | -| `fp list tools` | ツール名を一覧表示する。 | -| `fp list error_types` | エラータイプを一覧表示する。 | +| `fp usage` | 現在のメータリングウィンドウの使用状況を表示します。 | +| `fp list envs` | 観測された環境を一覧表示します。 | +| `fp list agents` | 観測されたエージェントIDを一覧表示します。 | +| `fp list event_types` | イベントタイプを一覧表示します。 | +| `fp list score_filters` | 評価スコアキーを一覧表示します。 | +| `fp list models` | モデル名を一覧表示します。 | +| `fp list hooks` | フック名を一覧表示します。 | +| `fp list tools` | ツール名を一覧表示します。 | +| `fp list error_types` | エラータイプを一覧表示します。 | ### 組織 | コマンド | 目的 | | --- | --- | -| `fp orgs list` | アクセス可能な組織を一覧表示する。 | -| `fp orgs switch [SLUG]` | アクティブな組織を保存する。省略時はプロンプトが表示される。 | -| `fp orgs current` | アクティブな組織を表示する。 | -| `fp orgs perms` | アクティブな組織での自分の権限を表示する。 | +| `fp orgs list` | アクセス可能な組織を一覧表示します。 | +| `fp orgs switch [SLUG]` | アクティブな組織を保存します。省略した場合はプロンプトが表示されます。 | +| `fp orgs current` | アクティブな組織を表示します。 | +| `fp orgs perms` | アクティブな組織での権限を表示します。 | -### API キー +### APIキー | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp keys list` | 組織のキーを一覧表示する。 | `--show-id`; `--fields ` | -| `fp keys show NAME` | 1つのキーとそのグラントを表示する。 | — | -| `fp keys create NAME` | キーを作成し、シークレットを一度だけ表示する。 | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | 権限セットを置き換えるか、グラントを調整する。 | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | シークレットをローテーションし、置き換えを一度だけ表示する。 | `--yes`, `-y` | -| `fp keys disable NAME` | キーを永続的に失効させる。 | `--yes`, `-y` | +| `fp keys list` | 組織のキーを一覧表示します。 | `--show-id`; `--fields ` | +| `fp keys show NAME` | 1つのキーとそのグラントを表示します。 | — | +| `fp keys create NAME` | キーを作成し、シークレットを1回だけ表示します。 | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | 権限セットを置き換えるか、グラントを調整します。 | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | シークレットをローテーションし、置き換えを1回だけ表示します。 | `--yes`, `-y` | +| `fp keys disable NAME` | キーを恒久的に無効化します。 | `--yes`, `-y` | -権限トークンには `events:add` のように `resource:action` の形式を使います。`--add` を繰り返すか、カンマ区切りでトークンを指定するか、`events:read.add` のようにドット区切りのアクションを使用できます。 +権限トークンは `events:add` のように `resource:action` の形式を使用します。`--add` を繰り返すか、トークンをカンマ区切りにするか、`events:read.add` のようなドット記法のアクションを使用してください。 ### クエリ | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp query list` | 保存済みクエリを一覧表示する。 | `--show-id`; `--fields ` | -| `fp query show NAME` | 1つのクエリを表示する。 | — | -| `fp query create NAME` | クエリを保存する。 | `--sql `; `--description` | -| `fp query update NAME` | クエリを更新または名前変更する。 | `--name`; `--sql`; `--description`; `--yes`, `-y` | -| `fp query delete NAME` | 保存済みクエリを削除する。 | `--yes`, `-y` | -| `fp query run [NAME]` | 保存済みクエリまたはアドホック SQL を実行する。 | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | クエリ可能なテーブルを一覧表示するか、1つのテーブルを確認する。 | — | +| `fp query list` | 保存済みクエリを一覧表示します。 | `--show-id`; `--fields ` | +| `fp query show NAME` | 1つのクエリを表示します。 | — | +| `fp query create NAME` | クエリを保存します。 | `--sql `; `--description` | +| `fp query update NAME` | クエリを更新または名前変更します。 | `--name`; `--sql`; `--description`; `--yes`, `-y` | +| `fp query delete NAME` | 保存済みクエリを削除します。 | `--yes`, `-y` | +| `fp query run [NAME]` | 保存済みクエリまたはアドホックSQLを実行します。 | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query schema [TABLE]` | クエリ可能なテーブルを一覧表示するか、1つのテーブルを検査します。 | — | ### ユーザー | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp users list` | 組織メンバーを一覧表示する。 | `--active-only`; `--show-id` | -| `fp users show EMAIL` | メンバーとそのグラントを表示する。 | — | -| `fp users create EMAIL` | メンバーを追加する。 | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | メンバーのグラントを変更する。 | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp users disable EMAIL` | サインインを無効にする。 | `--yes`, `-y` | -| `fp users enable EMAIL` | サインインを再度有効にする。 | `--yes`, `-y` | +| `fp users list` | 組織メンバーを一覧表示します。 | `--active-only`; `--show-id` | +| `fp users show EMAIL` | メンバーとそのグラントを表示します。 | — | +| `fp users create EMAIL` | メンバーを追加します。 | `--permission-set`; `--add`; `--remove` | +| `fp users update EMAIL` | メンバーのグラントを変更します。 | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users disable EMAIL` | サインインを無効にします。 | `--yes`, `-y` | +| `fp users enable EMAIL` | サインインを再度有効にします。 | `--yes`, `-y` | ### 設定 | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp settings list` | 組織の設定と現在の値を一覧表示する。 | — | -| `fp settings schema` | 許容値と説明を表示する。 | — | -| `fp settings set KEY` | 既存の設定を変更する。 | `--value`、`--json-value`、`--file` のいずれか1つ（必須）。`--yes`, `-y`（任意） | +| `fp settings list` | 組織の設定と現在の値を一覧表示します。 | — | +| `fp settings schema` | 許容値と説明を表示します。 | — | +| `fp settings set KEY` | 既存の設定を変更します。 | `--value`、`--json-value`、`--file` のいずれか1つ（必須）。オプションで `--yes`, `-y`。 | ### アラート | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp alerts list` | アラートルールを一覧表示する。 | `--show-id` | -| `fp alerts show NAME` | 1つのアラートを表示する。 | — | -| `fp alerts create NAME` | アラートを作成する。 | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | アラートを更新または名前変更する。 | create オプションに加えて `--name`; `--yes`, `-y` | -| `fp alerts delete NAME` | アラートを削除する。 | `--yes`, `-y` | -| `fp alerts test NAME` | テスト通知を送信する。 | `--channels`; `--yes`, `-y` | +| `fp alerts list` | アラートルールを一覧表示します。 | `--show-id` | +| `fp alerts show NAME` | 1つのアラートを表示します。 | — | +| `fp alerts create NAME` | アラートを作成します。 | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | +| `fp alerts update NAME` | アラートを更新または名前変更します。 | createオプションに加えて `--name`; `--yes`, `-y` | +| `fp alerts delete NAME` | アラートを削除します。 | `--yes`, `-y` | +| `fp alerts test NAME` | テスト通知を送信します。 | `--channels`; `--yes`, `-y` | -アラートの重大度は `info`、`warning`、`critical` です。トリガーの種類は `metric_threshold`、`custom_sql`、`evaluation_score`、`eval_compound`、`per_event` です。評価間隔は 30〜86,400 秒の間で指定する必要があります。 +アラートの重大度は `info`、`warning`、`critical` です。トリガーの種類は `metric_threshold`、`custom_sql`、`evaluation_score`、`eval_compound`、`per_event` です。評価間隔は30〜86,400秒の間でなければなりません。 ### 監査 | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp audits list` | 監査を一覧表示する。 | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | 1つの監査定義と状態を表示する。 | — | -| `fp audits create NAME` | 監査を作成し、最初の実行を即座にキューに追加する。 | [作成オプション](#audit-create-options)を参照。 | -| `fp audits edit NAME` | 未指定の値を保持しながら監査設定を置き換える。 | 定義の作成オプション; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | 監査、その検出結果、および実行履歴を削除する。 | `--yes`, `-y` | -| `fp audits run NAME` | 手動実行をキューに追加する。 | — | -| `fp audits runs NAME` | 実行履歴を一覧表示する。 | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | ブリーフと参照 URL のフェッチ状態を表示する。 | — | -| `fp audits context-set NAME` | ブリーフまたは参照 URL を変更する。 | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | 参照 URL を再フェッチする。 | — | -| `fp audits findings` | 検出結果を一覧表示する。 | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | 1つの検出結果とその証拠を表示する。 | — | -| `fp audits ack FINDING_ID` | 検出結果を確認済みにする。 | `--reason` | -| `fp audits mute FINDING_ID` | 繰り返し発生するパターンを抑制する。 | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | パターンをアクション不要としてマークし、抑制する。 | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | 以降の抑制なしに検出結果を修正済みとしてマークする。 | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | 検出結果をライブキューに戻し、抑制を解除する。 | — | -| `fp audits assign FINDING_ID` | 検出結果の担当者を設定する。 | `--to ` が必須 | +| `fp audits list` | 監査を一覧表示します。 | `--enabled-only`; `--show-id` | +| `fp audits show NAME` | 1つの監査定義と状態を表示します。 | — | +| `fp audits create NAME` | 監査を作成し、最初の実行を即座にキューに入れます。 | [作成オプション](#audit-create-options)を参照。 | +| `fp audits edit NAME` | 指定されていない値を保持しながら監査設定を置き換えます。 | create定義オプション; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | 監査、その所見、および実行履歴を削除します。 | `--yes`, `-y` | +| `fp audits run NAME` | 手動実行をキューに入れます。 | — | +| `fp audits runs NAME` | 実行履歴を一覧表示します。 | `--limit`, `-n`; `--show-id` | +| `fp audits context-show NAME` | ブリーフとリファレンスURLのフェッチ状態を表示します。 | — | +| `fp audits context-set NAME` | ブリーフまたはリファレンスURLを変更します。 | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-refresh NAME` | リファレンスURLを再フェッチします。 | — | +| `fp audits findings` | 所見を一覧表示します。 | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | +| `fp audits finding FINDING_ID` | 1つの所見とその証拠を表示します。 | — | +| `fp audits ack FINDING_ID` | 所見を確認します。 | `--reason` | +| `fp audits mute FINDING_ID` | 繰り返し発生するパターンを抑制します。 | `--reason`; `--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | パターンを対応不要としてマークし、抑制します。 | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | 将来の抑制なしに所見を修正済みとしてマークします。 | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | 所見をライブキューに戻し、抑制をクリアします。 | — | +| `fp audits assign FINDING_ID` | 所見のオーナーを設定します。 | 必須 `--to ` | #### 監査の作成オプション @@ -261,46 +261,46 @@ fp audits create checkout-reliability \ | オプション | 説明 | | --- | --- | -| `--file ` | JSON をベースに定義するか、stdin には `-` を使用する。明示的なフラグはファイルの値を上書きする。 | -| `--description ` | 障害の問いや目的を記述する。 | -| `--enabled` / `--disabled` | スケジューリングを有効または無効な状態で開始する。デフォルト：有効。 | +| `--file ` | JSONに基づいて定義を作成します。stdin の場合は `-` を使用します。明示的なフラグがファイルの値を上書きします。 | +| `--description ` | 失敗の質問または目的を記述します。 | +| `--enabled` / `--disabled` | スケジューリングをオンまたはオフで開始します。デフォルト：有効。 | | `--schedule-interval-secs ` | `3600`〜`604800`。デフォルト：`86400`。 | -| `--schedule-anchor ` | ISO 8601 形式の固定 UTC フェーズ。デフォルト：次の 09:00 UTC。 | -| `--window-mode since_last\|fixed` | 最後に完全に分析されたウィンドウの後から継続するか、ローリングウィンドウを繰り返し検査する。デフォルト：`since_last`。 | +| `--schedule-anchor ` | ISO 8601形式の固定UTCフェーズ。デフォルト：次の09:00 UTC。 | +| `--window-mode since_last\|fixed` | 最後に完全に分析されたウィンドウの後に続けるか、ローリングウィンドウを繰り返し検査します。デフォルト：`since_last`。 | | `--lookback-window-secs ` | `3600`〜`7776000`。デフォルト：`604800`。 | -| `--scope ''` | `environments`、`agent_ids`、またはその他のサポートされるスコープフィールドでフィルタリングする。 | -| `--ignore-error-type ` | エラータイプを除外する。繰り返しまたはカンマ区切りで複数指定可。 | -| `--llm` / `--no-llm` | エージェント分析を有効または無効にする。デフォルト：有効。 | -| `--top-k ` | `1`〜`500` 件の検出結果を保持する。デフォルト：`50`。 | -| `--sensitivity low\|medium\|high` | レポートの感度を設定する。デフォルト：`medium`。 | +| `--scope ''` | `environments`、`agent_ids`、またはその他のサポートされているスコープフィールドでフィルタリングします。 | +| `--ignore-error-type ` | エラータイプを除外します。繰り返しまたはカンマ区切りで指定します。 | +| `--llm` / `--no-llm` | エージェンティック分析を有効または無効にします。デフォルト：有効。 | +| `--top-k ` | `1`〜`500` の所見を保持します。デフォルト：`50`。 | +| `--sensitivity low\|medium\|high` | レポートの感度を設定します。デフォルト：`medium`。 | | `--channels ''` | 通知チャンネルの配列。 | -| `--text ` | インラインブリーフ。最大 8,192 文字。 | -| `--text-file ` | ファイルからブリーフを読み込む。`--text` とは相互排他。 | -| `--url ` | 公開 HTTPS 参照を追加する。最大5回繰り返し可能。 | +| `--text ` | インラインブリーフ。最大8,192文字。 | +| `--text-file ` | ファイルからブリーフを読み込みます。`--text` とは相互排他的。 | +| `--url ` | 公開HTTPSリファレンスを追加します。最大5回繰り返し可能。 | -最初の実行にコンテキストが必要な場合は、作成時に含めてください。作成は、キューに入った実行が開始する前に定義とコンテキストをまとめてコミットします。 +最初の実行でコンテキストが必要な場合は、作成時に含めてください。作成はキューに入れられた実行が開始される前に、定義とコンテキストを一緒にコミットします。 - `fp audits run` は非同期です。検出結果を読む前に `fp audits runs NAME` をポーリングして、最新の実行が成功または失敗するまで待ってください。 + `fp audits run` は非同期です。所見を読む前に `fp audits runs NAME` をポーリングし、最新の実行が成功または失敗するまで待機してください。 ### 課題 | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp issues list` | 課題を一覧表示する。 | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | オープンまたは選択した状態の課題数をカウントする。 | `--state` | -| `fp issues show INCIDENT_ID` | 課題の詳細、コメント、サブスクライバー、アクティビティを表示する。 | — | -| `fp issues open` | 手動またはアラートにリンクした課題を開く。 | `--summary` が必須; `--title`, `--alert-id`, `--severity` は任意 | -| `fp issues ack INCIDENT_ID` | 課題を確認済みにする。 | — | -| `fp issues assign INCIDENT_ID` | 担当者を置き換える。オプションを省略すると担当者をクリアする。 | 繰り返し可能な `--assignee` | -| `fp issues resolve INCIDENT_ID` | 課題を解決する。 | `--yes`, `-y` | -| `fp issues comment-list INCIDENT_ID` | コメントを一覧表示する。 | — | -| `fp issues comment-add INCIDENT_ID` | コメントを追加する。 | `--body` または `--file` のいずれか1つ（必須） | -| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | コメントを削除する。 | `--yes`, `-y` | -| `fp issues subscribers INCIDENT_ID` | サブスクライバーを一覧表示する。 | — | -| `fp issues subscribe INCIDENT_ID` | 自分または他のオペレーターをサブスクライブする。 | `--email` | -| `fp issues unsubscribe INCIDENT_ID` | サブスクリプションを削除する。 | `--email` | +| `fp issues list` | 課題を一覧表示します。 | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | オープンまたは選択した課題の状態をカウントします。 | `--state` | +| `fp issues show INCIDENT_ID` | 課題の詳細、コメント、サブスクライバー、およびアクティビティを表示します。 | — | +| `fp issues open` | 手動またはアラートにリンクされた課題を開きます。 | 必須 `--summary`; オプション `--title`、`--alert-id`、`--severity` | +| `fp issues ack INCIDENT_ID` | 課題を確認します。 | — | +| `fp issues assign INCIDENT_ID` | 担当者を置き換えます。オプションを省略するとクリアされます。 | 繰り返し可能な `--assignee` | +| `fp issues resolve INCIDENT_ID` | 課題を解決します。 | `--yes`, `-y` | +| `fp issues comment-list INCIDENT_ID` | コメントを一覧表示します。 | — | +| `fp issues comment-add INCIDENT_ID` | コメントを追加します。 | `--body`、`--file` のいずれか1つ（必須） | +| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | コメントを削除します。 | `--yes`, `-y` | +| `fp issues subscribers INCIDENT_ID` | サブスクライバーを一覧表示します。 | — | +| `fp issues subscribe INCIDENT_ID` | 自分自身または別のオペレーターをサブスクライブします。 | `--email` | +| `fp issues unsubscribe INCIDENT_ID` | サブスクリプションを削除します。 | `--email` | 有効な課題の状態は `firing`、`acknowledged`、`resolved` です。スタンドアロン課題の重大度は `info`、`warning`、`critical` です。 @@ -308,73 +308,73 @@ fp audits create checkout-reliability \ | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp agent health` | アシスタントの可用性と設定を確認する。 | — | -| `fp agent models` | 利用可能なアシスタントモデルを一覧表示する。 | — | -| `fp agent chats` | 保存済みチャットを一覧表示する。 | — | -| `fp agent ask [MESSAGE]` | チャットを開始または継続する。メッセージが省略された場合は stdin から読み込む。 | `--chat`; `--model`; `--page-context` | -| `fp agent show CHAT_ID` | 保存された会話を表示する。 | — | -| `fp agent rename CHAT_ID` | 会話の名前を変更する。 | `--title` が必須 | -| `fp agent delete CHAT_ID` | 会話を削除する。 | `--yes`, `-y` | +| `fp agent health` | アシスタントの可用性と設定を確認します。 | — | +| `fp agent models` | 利用可能なアシスタントモデルを一覧表示します。 | — | +| `fp agent chats` | 保存済みチャットを一覧表示します。 | — | +| `fp agent ask [MESSAGE]` | チャットを開始または継続します。メッセージが省略された場合は stdin を読み取ります。 | `--chat`; `--model`; `--page-context` | +| `fp agent show CHAT_ID` | 保存済みの会話を表示します。 | — | +| `fp agent rename CHAT_ID` | 会話の名前を変更します。 | 必須 `--title` | +| `fp agent delete CHAT_ID` | 会話を削除します。 | `--yes`, `-y` | ### ポリシー -クラウド管理のポリシーバージョン。**セッション限定** — これらのコマンドはすべて API キー使用時にリクエスト前に終了コード `2` で終了します。これらは `/v1` に意図的に存在しないルート限定の書き込みルートだからです。 +クラウド管理のポリシーバージョン。**セッション限定** — APIキーを使用した場合、リクエストの前にすべてのコマンドが終了コード `2` で終了します。これらは `/v1` に意図的に存在しないルート限定の書き込みルートだからです。 | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp policies list` | ポリシーバージョンを一覧表示する。 | `--json` | -| `fp policies show POLICY_ID` | ソースを含む1つのポリシーを表示する。 | — | -| `fp policies publish NAME PATH` | ローカルの `.mjs` からバージョンを作成する。 | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | それが削除されたすべてのデプロイに再追加し、それぞれに新しいジェネレーションを作成する。 | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | それを保持するすべてのデプロイから削除し、それぞれに新しいジェネレーションを作成する。 | `--yes`, `-y` | -| `fp policies delete POLICY_ID` | ポリシーバージョンを削除する。 | `--yes`, `-y` | -| `fp policies test PATH` | 合成コンテキストに対してローカルでポリシーをテストする。各ポリシーの `match` フィルターを適用するため、指定されたイベント/ツールに対応していないポリシーは実行されずに `skipped` として報告される。 | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | アシスタントを使ってポリシーを下書きする。`policies:write` が必要。 | — | +| `fp policies list` | ポリシーバージョンを一覧表示します。 | `--json` | +| `fp policies show POLICY_ID` | ソースを含む1つのポリシーを表示します。 | — | +| `fp policies publish NAME PATH` | ローカルの `.mjs` からバージョンを作成します。 | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | 削除されたすべてのデプロイメントに再追加し、各デプロイメントで新しいジェネレーションを作成します。 | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | それを含むすべてのデプロイメントから削除し、各デプロイメントで新しいジェネレーションを作成します。 | `--yes`, `-y` | +| `fp policies delete POLICY_ID` | ポリシーバージョンを削除します。 | `--yes`, `-y` | +| `fp policies test PATH` | 合成コンテキストに対してポリシーをローカルで実行します。各ポリシーの `match` フィルターを適用するため、指定されたイベント/ツールをカバーしないポリシーは実行されずに `skipped` と報告されます。 | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | アシスタントでポリシーを下書きします。`policies:write` が必要です。 | — | ### フリート -どのマシンがどのポリシーを実行するかを管理します。**セッション限定**（上記と同じ理由）。 +どのマシンがどのポリシーを実行するか。上記と同じ理由で**セッション限定**。 | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp fleet list` | 登録済みマシンとそのデプロイジェネレーションを一覧表示する。 | — | -| `fp fleet show MACHINE_ID` | マシンが現在実行しているポリシーセットを表示する。 | — | -| `fp fleet deploy MACHINE_ID` | **マシンのポリシーセット全体を置き換える。** プランを出力し、`--json` なしのインタラクティブターミナルでのみ確認を求める。 | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | マシンを別のデプロイと比較する。 | — | -| `fp fleet history MACHINE_ID` | マシンの過去のデプロイを表示する。 | — | -| `fp fleet rollback MACHINE_ID` | 以前のデプロイを復元する。 | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | マシンに読みやすい名前を付ける。 | `--name` が必須 | +| `fp fleet list` | 登録済みマシンとそのデプロイメントジェネレーションを一覧表示します。 | — | +| `fp fleet show MACHINE_ID` | マシンが現在実行しているポリシーセットを表示します。 | — | +| `fp fleet deploy MACHINE_ID` | **マシンのポリシーセット全体を置き換えます。** プランを表示し、`--json` なしのインタラクティブターミナルでのみ確認を求めます。 | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | マシンを別のデプロイメントと比較します。 | — | +| `fp fleet history MACHINE_ID` | マシンの過去のデプロイメントを表示します。 | — | +| `fp fleet rollback MACHINE_ID GENERATION` | 過去のジェネレーションのポリシーセットを新しいジェネレーションとして復元します。 | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | マシンに読みやすい名前を付けます。 | 必須 `--name` | ### ガードレール -強制適用が実際に行ったことを確認します。**セッション限定**（上記と同じ理由）。 +実際に適用が行ったこと。上記と同じ理由で**セッション限定**。 | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp guardrails summary` | カバレッジ、ブロック/評価の合計、拒否のスパークライン、ポリシーごとのテーブルを表示する。 | `--since`（`1h`、`6h`、`24h`、`7d`）; `--machine` | -| `fp guardrails timeline` | ウィンドウ全体でバケット化された判定を、すべてのポリシーソースにわたって合計して表示する。 | `--since`（`1h`、`6h`、`24h`、`7d`）; `--machine` | +| `fp guardrails summary` | カバレッジ、ブロック/評価の合計、拒否スパークライン、およびポリシーごとのテーブル。 | `--since`（`1h`、`6h`、`24h`、`7d`）; `--machine` | +| `fp guardrails timeline` | ウィンドウ全体でバケット化され、すべてのポリシーソース全体で合計された決定。 | `--since`（`1h`、`6h`、`24h`、`7d`）; `--machine` | ## グローバルフラグ | フラグ | 説明 | | --- | --- | -| `--json` | 機械可読な JSON を出力する。 | -| `--base-url ` | セルフホストまたは開発用ダッシュボードを使用する。 | -| `--org ` | この呼び出しの組織を選択する。 | -| `--token ` | 保存済みのユーザーセッショントークンを上書きする。 | -| `--api-key ` | API キーで自動化を認証する。保存されない。 | -| `--timeout ` | HTTP タイムアウト。正の値である必要がある。デフォルト：`30`。 | -| `--quiet`, `-q` | stderr のステータス出力を抑制する。 | -| `--no-color` | カラー出力を無効にする。 | -| `--insecure` / `--secure` | TLS 証明書の検証を無効または復元する。 | -| `--version` | バージョンを出力して終了する。 | -| `--help`, `-h` | ヘルプを表示する。 | - -`--api-key` は自動化向けです。ログイン、組織の切り替え、アシスタントコマンドにはユーザーセッションが必要です。 +| `--json` | マシン可読JSONを出力します。 | +| `--base-url ` | セルフホストまたは開発ダッシュボードを使用します。 | +| `--org ` | この呼び出しの組織を選択します。 | +| `--token ` | 保存されたユーザーセッショントークンを上書きします。 | +| `--api-key ` | APIキーで自動化を認証します。保存されません。 | +| `--timeout ` | HTTPタイムアウト。正の値でなければなりません。デフォルト：`30`。 | +| `--quiet`, `-q` | stderrのステータス出力を抑制します。 | +| `--no-color` | 色付き出力を無効にします。 | +| `--insecure` / `--secure` | TLS証明書の検証を無効化または復元します。 | +| `--version` | バージョンを表示して終了します。 | +| `--help`, `-h` | ヘルプを表示します。 | + +`--api-key` は自動化を目的としています。ログイン、組織の切り替え、アシスタントコマンドにはユーザーセッションが必要です。 ## 環境変数 -| 変数 | 相当するフラグまたは目的 | +| 変数 | 同等またはその目的 | | --- | --- | | `FP_DASHBOARD_URL` | `--base-url` | | `FP_ORG` | `--org` | @@ -382,18 +382,18 @@ fp audits create checkout-reliability \ | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | CLI 設定ディレクトリを再配置する（デフォルト：`~/.failproofai/fpcli`）。 | -| `FP_ANALYTICS_DISABLED` または `DO_NOT_TRACK` | 匿名 CLI アナリティクスを無効にする。 | -| `NO_COLOR` | カラー出力を無効にする。 | +| `FP_HOME` | CLI設定ディレクトリの場所を変更します（デフォルト `~/.failproofai/fpcli`）。 | +| `FP_ANALYTICS_DISABLED` または `DO_NOT_TRACK` | 匿名CLIアナリティクスを無効にします。 | +| `NO_COLOR` | 色付き出力を無効にします。 | -明示的なフラグは環境変数を上書きし、環境変数は保存済み設定を上書きします。API キーモードでは、`--org` または `FP_ORG` でテナントを明示的に選択してください。 +明示的なフラグが環境変数を上書きし、環境変数が保存された設定を上書きします。APIキーモードでは、`--org` または `FP_ORG` でテナントを明示的に選択してください。 - これらの `AGENTEYE_*` スペルは **`fp` では読み込まれず**、これまでも読み込まれたことはありません — CLI は `FP_*`（`fp_cli/app.py`）を宣言しており、未知の変数はエラーにはなりません。`AGENTEYE_DASHBOARD_URL` を設定しても CLI の向き先は変わらず、無視されてコマンドは保存済みのダッシュボードに対してサイレントに実行されます。 + これらの変数の `AGENTEYE_*` 形式は **`fp` では読み込まれず**、これまでも読み込まれたことはありません。CLIは `FP_*` を宣言しており（`fp_cli/app.py`）、未知の変数はエラーになりません。`AGENTEYE_DASHBOARD_URL` を設定してもCLIの向き先は変わりません。無視され、コマンドは保存済みダッシュボードに対してサイレントに実行されます。 - `AGENTEYE_HOME` と `AGENTEYE_ENVIRONMENT` は依然として存在しますが、これらはこの CLI ではなく**コレクターとテレメトリ SDK** に属します。 + `AGENTEYE_HOME` と `AGENTEYE_ENVIRONMENT` は引き続き存在しますが、これらは**コレクターとテレメトリSDK**に属するものであり、このCLIには属しません。 - 削除、失効、抑制、解決、または設定の置き換えを行うコマンドはデフォルトで確認を求めます。`--yes` はアクティブな組織とターゲットを確認した後にのみ使用してください。 + 削除、無効化、抑制、解決、または設定の置き換えを行うコマンドは、デフォルトで確認プロンプトが表示されます。アクティブな組織とターゲットを確認した後にのみ `--yes` を使用してください。 \ No newline at end of file diff --git a/docs/ja/reference/custom-agents.mdx b/docs/ja/reference/custom-agents.mdx index f30f16be..31893c81 100644 --- a/docs/ja/reference/custom-agents.mdx +++ b/docs/ja/reference/custom-agents.mdx @@ -1,21 +1,21 @@ --- title: "カスタムエージェント" -description: "failproofai-sdk の設定、イベントカタログ、相関ルール、配信について。" +description: "failproofai-sdk の設定、イベントカタログ、相関ルール、デリバリーについて。" icon: "python" --- -すべての設定・メソッド・フィールドの説明です。初めてインストルメント化する場合はガイドから始めてください — このページはリファレンス用です。 +各設定・メソッド・フィールドの役割を説明します。初めてインストゥルメンテーションを行う場合はガイドから始めてください。このページはリファレンスとしてご活用ください。 - インストール、インストルメント化、イベントメソッド、実装例、よくある問題。 + インストール、インストゥルメンテーション、イベントメソッド、実装例、よくある問題について説明します。 - LangChain、CrewAI、LlamaIndex、Pydantic AI は1回の呼び出しで自動的にインストルメント化されます。 + LangChain、CrewAI、LlamaIndex、Pydantic AI は1回の呼び出しで自動的にインストゥルメント化されます。 -Python 3.10 以降。実行時の依存関係なし。 +Python 3.10 以降が必要です。実行時の依存関係はありません。 ## インストール @@ -23,24 +23,30 @@ Python 3.10 以降。実行時の依存関係なし。 pip install failproofai-sdk ``` -パッケージは `failproofai-sdk` としてインストールされ、Python では `failproofai_sdk` としてインポートします。`failproofai-sdk[langgraph]` のようなフレームワーク追加パッケージはフレームワーク本体もインストールしますが、アダプターは常にベースのホイールに含まれています。 +このパッケージは `failproofai-sdk` としてインストールされ、Python では `failproofai_sdk` としてインポートします。`failproofai-sdk[langgraph]` などのフレームワーク用エクストラはフレームワーク本体もインストールしますが、アダプターは常にベースパッケージに含まれています。 ## Failproof デーモンへの接続 - 1. **Admin → Keys** に移動し、`events:add` 権限を持つキーを作成します。 - 2. エージェントマシン上で [Failproof デーモンをクラウドに接続](/ja/start/setup#connect-a-machine-to-cloud)します。 - 3. インストルメント化したセッションを1つ実行し、**Observe → Events** でその正確な ID を確認します。 - 4. **Observe → Sessions** に移動し、同じ環境を選択して再構成されたトレースを開きます。 + 1. **Admin → Keys** で `events:add` 権限を持つキーを作成します。 + 2. エージェントマシン上で [Failproof デーモンをクラウドに接続](/ja/start/setup#connect-a-machine-to-cloud) します。 + 3. インストゥルメントされたセッションを1回実行し、**Observe → Events** で正確な ID を確認します。 + 4. **Observe → Sessions** に移動して同じ環境を選択し、再構築されたトレースを開きます。 - ![実行グラフと順序付きイベントトレースとして再構成されたカスタム Python エージェントセッション。](/images/dashboard/session-detail.png) + ![カスタム Python エージェントのセッションが実行グラフと順序付きイベントトレースとして再構築されている様子。](/images/dashboard/session-detail.png) + `events:add` キーをシェルに読み込みます。`read -s` はエコーされないプロンプトで入力を受け取るため、コマンド履歴に残りません。 + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + 次に、マシンをセットアップして接続状態を確認します。 + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -60,30 +66,30 @@ failproofai_sdk.configure( | 引数 | 説明 | | --- | --- | -| `environment` | すべてのイベントに付くラベル — `production`、`staging`、`prod-eu` など。デフォルトは `dev`。 | -| `flush_interval` | バックグラウンドスレッドがディスクに書き込む頻度（秒）。デフォルトは `0.5`。 | -| `base_dir` | 書き込み先。デフォルトはデーモンのスプールで、特別な理由がない限りこのままにしてください。 | +| `environment` | すべてのイベントに付与されるラベル（例: `production`、`staging`、`prod-eu`）。デフォルトは `dev`。 | +| `flush_interval` | バックグラウンドスレッドがディスクに書き込む間隔（秒）。デフォルトは `0.5`。 | +| `base_dir` | 書き込み先のディレクトリ。デフォルトはデーモンのスプールディレクトリ。特別な理由がない限り変更不要。 | -環境変数で設定する場合: +環境変数でも設定できます。 | 変数 | 説明 | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | コードを変更せずに `environment` を設定します。ラベルがアプリではなくデプロイメントに属する場合に使用します。`configure()` の引数はこれより優先されます。 | -| `FAILPROOFAI_HOME` | スプールを保持する Failproof AI のルートディレクトリを変更します。 | -| `FAILPROOFAI_SDK_STRICT` | `1` に設定すると、インストルメント化エラーがログ記録ではなく例外として発生します。 | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` に設定すると、フレームワークの互換性問題が警告を出して続行するのではなく例外として発生します。 | +| `AGENTEYE_ENVIRONMENT` | コードを変更せずに `environment` を設定します。ラベルがアプリではなくデプロイ環境に属する場合に使用します。`configure()` の引数が優先されます。 | +| `FAILPROOFAI_HOME` | スプールを含む Failproof AI のルートディレクトリを変更します。 | +| `FAILPROOFAI_SDK_STRICT` | `1` に設定するとインストゥルメンテーションエラーがログ記録ではなく例外として発生します。 | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` に設定するとフレームワークの互換性の問題が警告ではなく例外として発生します。 | - **`environment` にカンマを使用しないでください。** インジェストはそのフィールドをカンマで分割してフィルターを構築し、ラベルにカンマが含まれるイベントはすべてスキップされます — そのため実行全体がサイレントに消えてしまいます。`prod,eu` ではなく `prod-eu` と記述してください。 + **`environment` にカンマを含めないでください。** インジェストはこのフィールドをカンマで分割してフィルターを構築し、ラベルにカンマが含まれるイベントをすべてスキップします。結果として、実行全体がサイレントに消えてしまいます。`prod,eu` ではなく `prod-eu` と記述してください。 - `configure(environment="prod,eu")` は即座に例外を発生させるので問題にすぐ気づけます。`AGENTEYE_ENVIRONMENT` は例外を発生させられません（呼び出し元がないため）— 1回警告を出して `dev` にフォールバックします。 + `configure(environment="prod,eu")` は即座に例外を発生させるため、すぐに気づけます。一方、`AGENTEYE_ENVIRONMENT` は例外を発生させられないため、1回警告を出して `dev` にフォールバックします。 -イベントはメモリ内でキューに入れられ、`flush_interval` 秒ごとにバックグラウンドで書き込まれます。インタープリター終了時に最終フラッシュが行われます。プロセスが強制終了された場合、まだ書き込まれていないデータは失われます。 +イベントはメモリ内でキューに入れられ、バックグラウンドで `flush_interval` 秒ごとに書き込まれます。インタープリター終了時にも最終フラッシュが行われます。プロセスが強制終了された場合、未書き込みのイベントは失われます。 -## ID +## アイデンティティ -すべてのイベントはセッションとエージェントに属します。**スコープが両方を自動的に設定する**ため、通常は渡す必要はありません: +すべてのイベントはセッションとエージェントに属します。**スコープが両方を自動的に設定する**ため、通常は明示的に渡す必要はありません。 ```python with failproofai_sdk.session(): @@ -91,32 +97,32 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -`session_id` や `agent_id` を明示的に渡すことも可能で、その値が優先されます。バインドも渡しもされていない場合、クラウドが静かに破棄するようなイベントを送信するのではなく、`TypeError` が発生します。 +`session_id` や `agent_id` を明示的に渡すことも可能で、その値が優先されます。スコープが設定されておらず、かつ引数として渡されていない場合、クラウドが静かに破棄するようなイベントを送信するのではなく、`TypeError` が発生します。 - ID はコンテキスト変数で管理されます。`asyncio` タスクには自動的に引き継がれますが、**新しいスレッドには引き継がれません** — ワーカーを `failproofai_sdk.propagate()` でラップしないと、そのイベントは未紐付けになります。 + アイデンティティはコンテキスト変数として渡されます。`asyncio` のタスクには自動的に伝播されますが、**新しいスレッドには伝播されません**。ワーカースレッドは `failproofai_sdk.propagate()` でラップしてください。そうしないと、イベントが紐付けられなくなります。 ## イベントカタログ -15のメソッドがあります。ほとんどは**ペア**になっています — オープナーを呼び出してからクローザーを呼び出すと、SDK がその間隔を計測します。 +15 個のメソッドがあります。ほとんどは**ペア**になっています。開始メソッドを呼び出し、その後に終了メソッドを呼び出すと、SDK が経過時間を計測します。 -| | オープン | クローズ | +| | 開始 | 終了 | | --- | --- | --- | | **エージェント** | `agent_start` | `agent_end` | | | `agent_pause` | `agent_resume` | | **モデル** | `model_request` | `model_response` | | **ツール** | `tool_use` | `tool_result` | | **フック** | `hook_triggered` | `hook_completed` | -| **人間** | `human_wait` | `human_input` | +| **ヒューマン** | `human_wait` | `human_input` | -単独で使用するものが3つあります: `error`、`human_pause`、`human_interrupt`。 +単独で使用するメソッドは `error`、`human_pause`、`human_interrupt` の3つです。 - + -すべてのメソッドは `session_id` と `agent_id` も受け取りますが、スコープが自動的に設定します。`None` のままの値は JSON の `null` として送信されるのではなく省略され、すべてのメソッドは `None` を返します。 +すべてのメソッドは `session_id` と `agent_id` も受け取りますが、スコープが自動的に設定します。`None` のままのフィールドは JSON の `null` として送信されるのではなく、省略されます。すべてのメソッドは `None` を返します。 -| メソッド | 必須 | 任意 | +| メソッド | 必須 | 省略可能 | | --- | --- | --- | | `agent_start` | — | `goal`, `parent_id` | | `agent_end` | — | `outcome`, `summary` | @@ -137,14 +143,14 @@ with failproofai_sdk.session(): - 実行を失敗としてマークするには、`outcome` が `failed`、`error`、`timeout`、または `rejected` のいずれかでなければなりません。惜しい `"failure"` を含め、それ以外はすべて成功とみなされます。 + 実行を失敗としてマークするには、`outcome` が `failed`、`error`、`timeout`、`rejected` のいずれかである必要があります。`"failure"` のような類似した値を含め、それ以外はすべて成功として扱われます。 ## ペアリングと所要時間 -**ルールは1つ: クローズイベントにオープナーと同じ ID を渡すこと。** それがペアリングの方法であり、SDK が間隔を計測できる理由です。 +**ルールは1つ：終了イベントには開始イベントと同じ ID を渡してください。** これによってペアが作られ、SDK が経過時間を計測できるようになります。 -| ペア | マッチング基準 | +| ペア | マッチキー | | --- | --- | | `tool_use` → `tool_result` | `tool_call_id` | | `hook_triggered` → `hook_completed` | `hook_id` | @@ -152,46 +158,46 @@ with failproofai_sdk.session(): | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**`duration_ms` を自分で渡さないでください。** SDK が計測し、渡すと `ValueError` が発生します。 +**`duration_ms` を自分で渡さないでください。** SDK が計測します。渡した場合は `ValueError` が発生します。 -唯一の例外は `model_response` で、実際のプロバイダーレイテンシを知っているのはあなただけです。ミリ秒の整数値を渡してください — float を渡すと例外が発生します。このカラムは 32 ビット整数のため、float だと空になってしまいます。 +例外は `model_response` のみです。実際のプロバイダーレイテンシはあなた自身しか知らないためです。ミリ秒単位の整数を渡してください。float を渡すと例外が発生します。このカラムは 32 ビット整数であり、float では値が空になってしまうためです。 -- **ID はペアの種類ごと、セッションごとに一意であれば十分です。** ツール呼び出しとフックが同じ ID を共有することも、同時に実行中の2つのセッションが同じ ID を再利用しても衝突しません。 -- **エージェントにスコープされません。** あるエージェントの下でオープンされ、別のエージェントの下でクローズされたペアも正しくマッチします — マルチエージェントコードでは通常のケースです。 -- **`request_id` は任意ですが推奨します。** これがないと、モデルイベントは到着順にペアリングされるため、同じエージェント内の2つの並行呼び出しが誤ってペアリングされる可能性があります。 -- **プロセスをまたいだペア**はクラウドでも正しくマッチしますが、SDK は計測できません — どのプロセスも両方のハーフを見ていないためです。 -- **最大 10,000 個のオープナーがクローザーを待機できます。** それを超えると最も古いものが破棄されるため、リークが無限に増え続けることはありません。 +- **ID は種類ごと、セッションごとに一意であれば十分です。** ツール呼び出しとフックが同じ ID を共有しても構いません。同時に実行中の2つのセッションが同じ ID を再利用しても衝突しません。 +- **ID はエージェントにスコープされません。** あるエージェント下で開かれ、別のエージェント下で閉じられたペアも正しくマッチします。これはマルチエージェントコードでは通常のケースです。 +- **`request_id` は省略可能ですが推奨します。** 指定しない場合、モデルイベントは到着順にペアリングされるため、同じエージェント内の2つの並行呼び出しが誤ってペアリングされる可能性があります。 +- **プロセスをまたぐペア** はクラウド上では正しくマッチしますが、SDK は計時できません。どちらのプロセスも両方の半分を見ていないためです。 +- **最大 10,000 個の開始イベントが終了イベントを待機できます。** それを超えると最も古いものが破棄されるため、リークが無制限に増大することはありません。 -## 独自フィールド +## カスタムフィールド -渡した追加のキーワードはイベントとともに保存されます: +追加のキーワード引数を渡すと、そのイベントと一緒に保存されます。 ```python failproofai_sdk.event.tool_use( tool_name="search", tool_call_id="c1", - fw_tenant="acme", fw_region="eu-west-1", # 独自フィールド + fw_tenant="acme", fw_region="eu-west-1", # your own ) ``` -後でクエリしたい場合は JSON 型を使用してください。それ以外 — UUID、datetime、`Decimal`、set、bytes、モデルオブジェクト — は文字列として保存されます。 +後でクエリしたい場合は JSON 型を使用することをお勧めします。UUID、datetime、`Decimal`、set、bytes、モデルオブジェクトなど、それ以外の型は文字列として保存されます。 - **フィールド名にプレフィックスを付けてください。** 追加フィールドは最後に適用されるため、`model`、`tool_name`、`outcome` という名前のフィールドは実際の値をサイレントに上書きします。フレームワークアダプターは `fw_` を使用しているので、同様にすれば衝突しません。 + **フィールド名にプレフィックスを付けてください。** エクストラは最後に適用されるため、`model`、`tool_name`、`outcome` といった名前のフィールドは実際の値を静かに上書きしてしまいます。フレームワークアダプターは `fw_` を使用しています。同じようにすれば衝突を防げます。 - これがスペルミスのある任意フィールドがエラーにならない理由でもあります — 単に新しいカスタムフィールドになるだけです。クラウドで標準フィールドが見当たらない場合は、まずスペルを確認してください。 + これは、スペルミスのある省略可能フィールドがエラーにならない理由でもあります。単に新しいカスタムフィールドになるだけです。クラウドで標準フィールドが見つからない場合は、まずスペルを確認してください。 -以下の5つの名前は予約済みで、使用すると拒否されます: `timestamp`、`session_id`、`agent_id`、`type`、`environment`。 +以下の5つの名前は予約済みであり、使用できません: `timestamp`、`session_id`、`agent_id`、`type`、`environment`。 -## 配信と確認 +## デリバリーと検証 - **Observe → Events** で、最初に `agent_start` が存在し、最後に `agent_end` が存在することを確認します。次に **Observe → Sessions** を開いて、モデル、ツール、人間、フック、エラーのイベントが意図した順序で表示されていることを確認します。セッション ID をトラブルシューティングの主要キーとして使用してください。 + **Observe → Events** で、最初に `agent_start` が存在し、最後に `agent_end` が存在することを確認します。次に **Observe → Sessions** を開き、モデル、ツール、ヒューマン、フック、エラーの各イベントが意図した順序で表示されていることを確認します。トラブルシューティングの主キーとしてセッション ID を使用します。 ```bash @@ -203,14 +209,14 @@ failproofai_sdk.event.tool_use( -クラウドが空の場合は `$FAILPROOFAI_HOME/custom-agents/events`、それ以外は `~/.failproofai/custom-agents/events` を確認してください。JSONL ファイルがあれば SDK からの送信が証明されます。スプールが増加し続ける場合はデーモンの設定または配信の問題、スプールが空の場合はインストルメント化またはプロセスのライフタイムの問題です。 +クラウドが空の場合は `$FAILPROOFAI_HOME/custom-agents/events` を、それ以外の場合は `~/.failproofai/custom-agents/events` を確認してください。JSONL ファイルが存在すれば SDK からの送信は確認できています。スプールが増え続けている場合はデーモンの設定やデリバリーの問題であり、スプールが空の場合はインストゥルメンテーションまたはプロセスのライフタイムの問題です。 - スプールはデーモンが停止しているときのみ確認してください。デーモンが動作中の場合、数ミリ秒ごとにバッチを収集・削除するため、ディレクトリ一覧はコレクターと競合し、実際に送信されたイベント数より大幅に少なく表示されます。 + スプールはデーモンが停止しているときにのみ確認してください。実行中のデーモンは数ミリ秒以内に各バッチを収集・削除するため、ディレクトリ一覧の表示がコレクターと競合し、実際に送信されたよりもはるかに少ないイベントしか表示されません。 ## カスタムランタイムでの障害防止 -監査結果とリンクされたトレースを使用して、安全でないアクション、必要なエビデンス、意図したレスポンスを定義します。カスタムエンフォースメントの統合では、実行前にアクションを公開し、その構造化された入力をポリシーエンジンに渡して、resulting allow、instruct、または deny の決定を適用する必要があります。 +監査の結果とリンクされたトレースを使用して、安全でないアクション、必要な証拠、および意図する対応を定義します。カスタムエンフォースメントインテグレーションは、実行前にアクションを公開し、その構造化された入力をポリシーエンジンに渡し、返された allow、instruct、deny の判断を適用する必要があります。 -[Failproof AI にお問い合わせください](mailto:support@befailproof.ai)。ランタイムのモデル、ツール、ライフサイクル境界をポリシーフックにマッピングし、統合の検証をお手伝いします。 \ No newline at end of file +[Failproof AI にお問い合わせ](mailto:support@befailproof.ai)いただければ、ランタイムのモデル・ツール・ライフサイクルの境界をポリシーフックにマッピングし、インテグレーションの検証をサポートします。 \ No newline at end of file diff --git a/docs/ja/reference/evaluator-sdk.mdx b/docs/ja/reference/evaluator-sdk.mdx index 036848f3..47b98b79 100644 --- a/docs/ja/reference/evaluator-sdk.mdx +++ b/docs/ja/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "Failproof AI セッションを同期または非同期でスコアリングするサービスを構築します。" +description: "LLMジャッジなど、ホスト型Pythonでは対応できない処理を独自の評価ワーカーで実行します。" icon: "gauge" --- -エバリュエーターは、完了したエージェントセッションを受け取り、必要な品質シグナルを返します。具体的には、数値スコア、各スコアの説明、およびオプションのサマリーです。Failproof AI はこれらの結果をトレースの横に保存し、エージェントや環境をまたいでグラフ化します。 +Evaluator SDKは、独自のインフラ上で評価を実行します。ワーカーはFailproof AIに評価を登録し、セッションが完了するたびにそれを取得してスコアリングし、結果を送信します。すべてアウトバウンドHTTPS経由で行われるため、外部から接続を受け付けません。[ホスト型Python](/ja/evaluations/write)では実現できないLLMジャッジ、モデル呼び出し、パッケージ、シークレット、ネットワークアクセスを活用するためにご利用ください。結果は[評価ページ](/ja/sessions/evaluations)にホスト型の結果と並んで表示され、**customer** タグが付きます。 -## エバリュエーターのセットアップ +`failproofai-sdk` に含まれており、`failproofai_sdk.evaluator` 配下にあります。トレーシングSDKをインポートしても自動的には読み込まれません。 - - - SDK と実行に使用するサーバーをインストールします。 - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - `evaluator.py` を作成します。この例では、セッション内に失敗したツール呼び出しが含まれているかどうかを確認します。 - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - 共有トークンを設定し、エバリュエーターを起動して、ヘルスエンドポイントが応答することを確認します。 - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - 別のターミナルで: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## エバリュエーターを Failproof AI に接続する +```bash +pip install failproofai-sdk +``` -1. Failproof AI Cloud からアクセス可能な HTTPS URL にエバリュエーターをデプロイします。 -2. その URL で `EVALUATOR_ENDPOINT` を設定し、`EVALUATOR_TOKEN` にエバリュエーターが使用しているトークンと同じ値を設定します。マネージド Cloud の場合は、[support@befailproof.ai](mailto:support@befailproof.ai) に連絡して接続設定を行ってください。 -3. 評価を実行し、スコアが Failproof AI に表示されることを確認します。 +## 評価の作成 - - - **Observe → Sessions** で完了したセッションを開き、自動評価が行われていない場合は **Run evaluation** を選択します。セッションの **Evaluation** パネルでステータス、スコア、推論、サマリーを確認します。 +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - **Observe → Evaluations** を使用して、エージェントや環境をまたいでスコアを比較できます。レイテンシー、コスト、トークンなどの数値計測には **Observe → Metrics** を使用してください。 - まず 1 つのセッションから始めて、エバリュエーターが期待するスコアキーと有用な推論をその実行について返しているかを確認します。 +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![評価スコアと推論がトレースの横に表示されたセッション詳細ビュー。](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` で評価を登録します。キーは結果のチャート表示に使われます。ロジックを変更したらバージョンも更新してください。各結果にはそれを生成したバージョンが保持されます。1つのワーカーには最大100件の評価を登録できます。 +- `result_kind` は特に指定しない限り `"score"` です。`"metric"` または `"assertion"` 評価の場合は、`metrics` または `assertions` エントリのいずれか1つにキーと同じ名前を付けてください。そのエントリが結果として扱われます。 +- `when` はセッションに評価を適用するかどうかを決定します。スキップする場合は `ConditionResult(False, "")` を返してください。理由が記録されます。 +- 評価は通常の関数でも `async` 関数でも構いません。`timeout_seconds` でタイムアウトを設定できます。 +- ペイロードキー（上記の `tool_name`、`response`、`content` など）はエージェントが送信する値によって異なるため、実際のセッションから確認してください。 - 個々の結果が正しいことを確認したら、評価ダッシュボードを使用してスコアを時系列でエージェントや環境をまたいで比較します。 +## ワーカーの起動 - ![エバリュエーターのスコアを時系列でグラフ化した品質ダッシュボード。](/images/dashboard/dashboard-quality.png) +**Administration → Keys** で作成した `evaluations:run` 権限を持つキーを `FAILPROOFAI_EVALUATOR_TOKEN` に設定し（コマンドに直接入力せず、シークレットストアから設定してください）、ワーカーを起動します。 - 健全なチャートは安定したスコア名を使用している必要があります。キーを変更すると別のシリーズが作成されます。 - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -セルフホスト型 Cloud インスタンスでは、サーバープロセスに `EVALUATOR_ENDPOINT` が設定されるまで自動評価は無効になっています。エバリュエーターの環境変数を変更した後はサーバーを再起動してください。 +`__main__` ブロックがない場合は、`python -m failproofai_sdk.evaluator evaluator:app` でも同様に起動できます。 -このサービスは `GET /health`、`GET /config`、`POST /evaluate`、およびオプションで `GET /evaluate/{job_id}` を公開します。非同期処理には `JobPending` を返し、Failproof AI がポーリングできるよう `@app.job_lookup` を登録してください。 +| 変数 | デフォルト | 用途 | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | 必須 | Failproof AI のURL。Cloudの場合は `https://app.befailproof.ai`。ループバックアドレス以外はHTTPS必須 | +| `FAILPROOFAI_EVALUATOR_TOKEN` | 必須 | `evaluations:run` 権限を持つキー | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | このワーカーの識別名 | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | このワーカーが同時にスコアリングするセッション数 | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Failproof AI への各リクエストのタイムアウト | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | 停止中のワーカーが実行中の処理の完了を待つ時間 | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | ループバック以外のURLへの平文HTTP通信を許可する（下記の警告を参照） | +| `FAILPROOFAI_EVALUATOR_MODULE` | なし | `python -m failproofai_sdk.evaluator` 用の `module:attribute` | -トークンが設定されている場合、health 以外のすべてのルートは、Failproof AI が `EVALUATOR_TOKEN` として送信するベアラートークンと同一のトークンを要求します。 + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` を有効にすると、すべての通信が平文で送信されます。ワーカーはすべてのリクエストに `Authorization: Bearer` ヘッダーとして `FAILPROOFAI_EVALUATOR_TOKEN` を付加します。また、取得するトランスクリプトはセッションそのものであるため、通信経路上の第三者がトークンとセッション内容の両方を読み取ることができます。読み取られたトークンはローテーションするまで評価の実行に悪用される可能性があります。このオプションは隔離された開発ネットワーク上のみで使用してください。それ以外の環境ではURLはHTTPSである必要があります。ループバックアドレスの場合はフラグ不要です。 + -## SDK の型 +## 結果の型 | 型 | フィールド | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## デコレーターとルート +| `Score` | `value`（0〜1）、`passed`、`unit`（デフォルト: `ratio`）、`display_value`、`description` | +| `Metric` | `value`、`unit`、`display_value`、`description` | +| `Assertion` | `passed`、`description` | +| `EvalResult` | `score`、`metrics`、`assertions`、`reasoning`、`summary`、`labels` | +| `ConditionResult` | `applicable`、`reason_code` | -| デコレーター | ルート | 必須 | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | はい | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | `JobPending` を返す場合 | -| `@app.config` | `GET /config` | いいえ | - -SDK は評価リクエストボディを 25 MiB に制限します。不明なリクエストフィールドは無視されるため、イベントコントラクトが拡張されてもサービスの互換性が維持されます。 +`EvalResult` にはスコア、メトリクス、アサーションのいずれかが少なくとも1つ必要で、最大25件まで設定できます。それぞれのキーは一意である必要があります。 -## 非同期処理の返却 +## セッション -評価が 1 回のリクエスト内で完了できない場合は `JobPending` を使用します。ジョブ ID は Failproof AI にとって不透明であり、結果が収集されるかサーバーのタイムアウトが切れるまで、サービスで解決可能な状態を維持する必要があります。 - -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| フィールドまたはメソッド | 内容 | +| --- | --- | +| `session_id`、`agent_id`、`environment` | セッションの識別情報 | +| `started_at`、`ended_at` | 開始時刻と終了時刻 | +| `event_count`、`events` | 順序付きの完全なトランスクリプト | +| `count(event_type)` | そのイベントタイプの件数 | +| `events_of_type(event_type)` | そのイベントタイプのイベント一覧（順序付き） | -ポーリング間隔は次の順序で決定されます: `JobPending.next_poll_secs`、`EvaluatorConfig.default_poll_interval_secs`、次にサーバーの `EVALUATOR_POLLING_INTERVAL_SECS`。値は 1 秒から 1 時間の間にクランプされます。サーバーのデフォルトのウォールクロックポーリング上限は 1 時間です。 +各イベントには `id`、`ts`、`event_type`、`payload` が含まれます。 -## リクエストとレスポンスのフィールド +## レガシー評価器 -| フィールド | 型 | 備考 | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | 現在は `"1"`。 | -| `session_id`, `agent_id`, `environment` | `str` | セッションの識別子と環境。 | -| `started_at` | `datetime` | 最初のイベントのタイムスタンプ。 | -| `ended_at` | `datetime \| None` | セッションが終了イベントを発行した場合に存在。 | -| `events` | `list[AgentEvent]` | 完全な順序付きイベントストリーム。 | -| `AgentEvent.id` | `int` | バックエンドのイベント行識別子。 | -| `AgentEvent.ts` | `datetime` | イベントのタイムスタンプ。 | -| `AgentEvent.event_type` | `str` | `tool_use` などのイベントファミリー。 | -| `AgentEvent.payload` | `dict[str, Any]` | 完全なイベントペイロード。 | -| `EvalResponse.scores` | `dict[str, float] \| None` | 評価でグラフ化される数値ディメンション。 | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | スコアごとの説明。キーは `scores` と対応している必要があります。 | -| `EvalResponse.summary` | `str \| None` | 評価全体のナラティブ。 | - -## サーバーオペレーターの設定 - -自動評価はデプロイ全体に適用され、`EVALUATOR_ENDPOINT` が存在しない場合は無効のままになります。 - -| 変数 | デフォルト | 用途 | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | 未設定 | エバリュエーターサービスのベース URL。 | -| `EVALUATOR_TOKEN` | 未設定 | `Evaluator(token=...)` と共有するベアラートークン。 | -| `EVALUATOR_WORKERS` | `2` | 同時ディスパッチャーワーカー数。 | -| `EVALUATOR_CLAIM_BATCH` | `4` | ディスパッチャーパスごとにクレームするセッション数。 | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | 非同期ポーリングのフォールバック間隔。 | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | リクエストごとのエバリュエータータイムアウト。 | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | 終端障害前の配信試行回数。 | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | `/config` のリフレッシュ間隔。 | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | 非同期ポーリングの最大ウォールクロック時間。 | - -サーバーは、デプロイ全体のエバリュエーターを使用する組織を制限することもできます。エンドポイント、トークン、リトライ、組織ゲートの変更はオペレーター設定として扱い、変更後はサーバーを再起動またはローリング更新してください。 - -## セキュリティと運用 - -- トラフィックが信頼されたネットワーク境界を越える場合は、エバリュエーターを HTTPS の背後に配置します。 -- 空でないベアラートークンを設定し、両方のサービスで同一に保ちます。 -- トークンやリクエストペイロードの機密プロンプトをログに記録しないでください。 -- 同期ハンドラーをべき等にしてください。リトライによってリクエストが繰り返される場合があります。 -- 本番環境では非同期ジョブの状態をプロセスメモリ外に永続化します。 -- スコアキーを安定させてください。キーの名前を変更すると、既存のシリーズが変更されるのではなく新しいチャートシリーズが作成されます。 - -SDK は `eval received`、`eval responded`、`job lookup`、`config returned`、`auth rejected`、およびハンドラー例外などの構造化されたライフサイクルログを出力します。ロギングハンドラーの設定は行いません。ホストアプリケーションのロギング設定を使用してください。 \ No newline at end of file +旧Evaluator SDK（Failproof AIが `EVALUATOR_ENDPOINT` でHTTPサービスを呼び出し、`/evaluate` に応答し、`JobPending` でポーリングする方式）は廃止されました。新しい評価器はこのワーカーを使用して構築してください。レガシーサービスを稼働中のセルフホスト環境のオペレーターは、移行期間中は引き続き使用できます。 \ No newline at end of file diff --git a/docs/ja/reference/failproof-cli.mdx b/docs/ja/reference/failproof-cli.mdx index 92754e75..4838715d 100644 --- a/docs/ja/reference/failproof-cli.mdx +++ b/docs/ja/reference/failproof-cli.mdx @@ -1,54 +1,70 @@ --- title: "Failproof AI CLI" -description: "フックのインストール、ローカルポリシーの管理、Cloudへの接続、ローカルデーモンの操作を行います。" +description: "フックのインストール、ローカルポリシーの管理、Cloudへの接続、ローカルデーモンの操作。" icon: "terminal" --- `npm install -g failproofai` でローカル CLI をインストールします。引数なしで実行するとローカルポリシーダッシュボードが開きます。 -このパッケージには Node.js 20.9 以降が必要です。Bun 1.3 以降は開発用およびソースインストール用としてサポートされています。`failproofai configure` および `failproofai setup` は `failproofai config` のエイリアスです。`failproofai p` は `failproofai policies` のエイリアスです。 +このパッケージには Node.js 20.9 以降が必要です。開発環境およびソースインストールには Bun 1.3 以降がサポートされています。`failproofai configure` と `failproofai setup` は `failproofai config` のエイリアスです。`failproofai policy`、`failproofai pack`、`failproofai p` はいずれも `failproofai policies` の別表記です — パックと個別ポリシーはもともと 3 つのコマンドに分かれていましたが、1 つの概念として統合されました。古い表記も引き続き使用できますが、例外が 2 つあります: `pack list ` は `policies show ` に、`pack build` は `publish` に変更されました。 ## マシンのセットアップ +CLI をインストールし、マシンキーをシェルに読み込みます。`read -s` を使うとコマンドに表示されずにプロンプトで入力できるため、履歴に残りません: + ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +次に、マシンをセットアップして適用するポリシーを選択します: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` +`failproofai config` はセットアップのすべてを担います: `failproofaid` サービスのインストール（ルート権限で一度だけ、`sudo -n` 経由 — 対話的なパスワードプロンプトは表示されません）、見つかったすべてのエージェント CLI へのフックの接続、キーが有効な場合の Cloud への接続を行います。ターミナルがない環境（CI、コンテナ、エージェントが操作している場合など）では、対話なしで設定を適用し、指定された操作が完了しない場合は終了コード 1 で終了します。 + +ポリシーは**何も**選択されません。それは 2 番目のコマンドの役割であり、これがなければ新しく設定されたマシンは常時オンのガードのみを適用します。 + +`--token` よりも環境変数を推奨します: コマンドライン引数はシステム上のすべてのユーザーが `ps` で読み取れるためです。ただし、環境変数が保護するのはその点のみです — `export` を含め、コマンドに直接キーを入力するとシェル履歴に残るため、上記のように `read -s` で読み込んでいます。CI では、シェルトレーシング（`set -x`）をオフにした状態でシークレットストアから設定してください。オンにするとトレースに出力されてしまいます。 + + + `--connect ` は**すでにセットアップ済み**のマシンを登録します。登録が成功するとすぐに返り、デーモンのインストールやフックの接続は行いません。まだセットアップされていないマシンには `failproofai config`（または `failproofai config --token `）を使用してください。そうしないと、接続済みと表示されながら何も収集・適用されない状態になります。 + + 引数なしで `failproofai` を実行するとローカルポリシーダッシュボードが開きます。 | コマンド | 動作 | | --- | --- | -| `failproofai config` | インタラクティブなマシンセットアップを実行 | -| `failproofai config --connect --token ` | Cloud インジェストおよびポリシー配信を接続 | -| `failproofai config --status` | 接続、デーモン、配信、一時停止状態を表示 | -| `failproofai policies` | 組み込み、カスタム、慣習、パック、Cloud 管理ポリシーを一覧表示 | -| `failproofai policies --install` | フックをインストールしてポリシーを有効化 | -| `failproofai policy add ` | ポリシーを 1 つ有効化 — 組み込みポリシー、またはインストール済みパックの `:` 形式 | -| `failproofai policy remove ` | 同じ命名規則でポリシーを 1 つ無効化 | -| `failproofai policies --uninstall` | ポリシーを無効化またはハーネスフックを削除 | -| `failproofai pack list` | インストール済みポリシーパックとそれぞれが持つポリシーを一覧表示 | -| `failproofai pack add ` | GitHub リリースからポリシーパックをインストール。タグ未指定の場合は最新版を取得してピン留め | -| `failproofai pack add --bundled` | 組み込みポリシーをパックとしてインストール（このパッケージから、ネットワーク不要） | -| `failproofai pack build ` | 独自パックの 3 つのリリースアセットをビルド | -| `failproofai pack remove ` | インストール済みパックを無効化 | +| `failproofai config` | マシンをセットアップ: エージェント、デーモン、キーがある場合は Cloud も接続 | +| `failproofai config --token ` | 対話なしで一括セットアップと接続 | +| `failproofai config --connect ` | **すでに**セットアップ済みのマシンを登録 — デーモンとフックは対象外 | +| `failproofai config --status` | 接続、デーモン、配信、一時停止の状態を表示 | +| `failproofai policies` | 組み込み、カスタム、規約、パック、Cloud 管理のポリシーを一覧表示 | +| `failproofai policies --install` | エージェント CLI にフックを接続。それ自体はポリシーを有効化しない | +| `failproofai policies add ` | ポリシーを 1 つ有効化 — 組み込みポリシー、またはインストール済みパックの `:` | +| `failproofai policies remove ` | ポリシーを 1 つ無効化、同じ命名規則 | +| `failproofai policies --uninstall` | ポリシーを無効化するかハーネスフックを削除 | +| `failproofai policies show /` | パックが持つ内容をマニフェストから確認（適用前に） | +| `failproofai policies show / --releases` | 公開済みの全バージョンと現在のバージョン | +| `failproofai policies add ` | GitHub リリースからポリシーパックをインストール; タグなしは最新版を取得してピン留め | +| `failproofai publish` | 独自ポリシーをパックとして公開; `--init` でひな形を作成 | +| `failproofai policies remove ` | パックをアンインストール | | `failproofai audit` | ローカルエージェント履歴をスキャンしてローカル監査ビューを開く | -| `failproofai audit --schedule [days] --email
` | 定期的なローカルスキャンをスケジュールし、結果をメールで送信 | -| `failproofai audit --status` | レポートアドレス、間隔、次回スケジュールスキャンを表示 | +| `failproofai audit --schedule [days] --email
` | 定期的なローカルスキャンをスケジュールし、結果をメール送信 | +| `failproofai audit --status` | レポートアドレス、間隔、次回スキャン予定を表示 | | `failproofai audit --no-schedule` | 監査履歴を削除せずに定期スキャンを停止 | -| `failproofai harness list` | 追加キャプチャパスを一覧表示 | +| `failproofai harness list` | 追加のキャプチャパスを一覧表示 | | `failproofai flush --wait` | 現在のイベントスプールを配信 | -| `failproofai backfill --since 30d` | 過去に処理済みの履歴を再読み込み | -| `failproofai config --pause [duration]` | デフォルト 30 分（最大 8 時間）ローカルセッションを一時停止 | -| `failproofai config --resume` | 一時停止中のローカルセッションを再開。`--all` で全停止を解除 | -| `failproofai update` | パッケージのマイグレーションを完了してデーモンを更新 | -| `failproofai migrate --dry-run` | 保留中のホームレイアウトマイグレーションをプレビューまたは実行 | -| `failproofai uninstall` | パッケージ削除前にフックとデーモンを削除 | +| `failproofai backfill --since 30d` | 以前に通過した履歴を再読み込み | +| `failproofai config --pause [duration]` | 現在のローカルセッションを一時停止（デフォルト 30 分、最大 8 時間） | +| `failproofai config --resume` | 一時停止中のローカルセッションを再開; `--all` ですべての一時停止を解除 | +| `failproofai update` | パッケージマイグレーションを完了してデーモンを更新 | +| `failproofai migrate --dry-run` | ホームレイアウトのマイグレーション予定をプレビューまたは実行 | +| `failproofai uninstall` | パッケージを削除する前にフックとデーモンを削除 | | `failproofai --version` | インストール済みパッケージのバージョンを表示 | | `failproofai --help` | コマンドと全体的な使い方を表示 | @@ -56,31 +72,33 @@ failproofai config --status | フラグ | 用途 | | --- | --- | -| `--connect --token ` | 非インタラクティブに接続 | -| `--machine-id ` | 安定したマシン ID を設定 | -| `--machine-label ` | ダッシュボードラベルを設定または変更 | -| `--no-transcripts` | トランスクリプトの内容を含めずに判断を送信 | +| `--token ` | 非対話的にセットアップと接続; `FAILPROOFAI_CLOUD_TOKEN` からも読み取り可能 | +| `--url ` | `app.befailproof.ai` 以外の場所に接続; `FAILPROOFAI_CLOUD_URL` からも読み取り可能 | +| `--connect ` | すでにセットアップ済みのマシンのみ登録。デーモンとすべてのフックをスキップ | +| `--machine-id ` | 固定マシン ID を設定 | +| `--machine-label ` | **すでに接続済み**のマシンの名前を変更。それ自体はセットアップを実行しないため、セットアップ中ではなく `failproofai config` の後に使用すること | +| `--no-transcripts` | トランスクリプト内容なしで決定を送信 | | `--disconnect` | Cloud ポリシーの取得とイベント配信を停止 | | `--status` | 現在のマシン状態を表示 | -| `--pause [duration]` | カレントディレクトリの最新セッションを一時停止。秒・分・時間を受け付け、デフォルトは 30 分 | +| `--pause [duration]` | 現在のディレクトリの最新セッションを一時停止; 秒、分、時間を受け付け、デフォルトは 30 分 | | `--resume` | 一致する一時停止を早期終了 | | `--session ` | 一時停止または再開の対象セッションを明示的に指定 | -| `--all` | `--resume` と併用して全アクティブ一時停止を終了 | +| `--all` | `--resume` と併用して、すべてのアクティブな一時停止を終了 | -ローカル一時停止は、1 セッションの組み込み・カスタム・慣習・パックポリシーを停止します。必ず期限切れとなり、Cloud 管理ポリシーは無効化しません。`block-failproofai-commands` — 常にオンであり、それ自体を無効化または一時停止することはできません — は、計測されたエージェントがこのエスケープハッチを使用するのを防ぎます。 +ローカルの一時停止は、組み込み、カスタム、規約、パックのポリシーを 1 セッションの間だけ停止します。一時停止は必ず期限切れになり、Cloud 管理のポリシーは無効化されません。`block-failproofai-commands` は常時オンで無効化も一時停止もできず、インストゥルメント済みエージェントがこの回避策を使うことを防ぎます。 ## ポリシーフラグ | フラグ | 用途 | | --- | --- | -| `--install`, `-i` | ポリシーを有効化してハーネスフックをインストール | +| `--install`, `-i` | ハーネスフックをインストール。後続の名前はそのポリシーを有効化; 名前なしの場合はポリシー変更なし | | `--uninstall`, `-u` | ポリシーを無効化またはフックを削除 | -| `--cli ` | 1 つ以上のサポート対象ハーネスを指定 | -| `--scope user\|project\|local\|all` | 設定スコープを選択。`all` はアンインストール用 | +| `--cli ` | サポートされているハーネスを 1 つ以上指定 | +| `--scope user\|project\|local\|all` | 設定スコープを選択; `all` はアンインストール用 | | `--beta` | ベータポリシーを含める | -| `--custom`, `-c ` | カスタムポリシーファイルを検証して読み込み。繰り返し指定可能 | +| `--custom`, `-c ` | カスタムポリシーファイルを検証して読み込み; 繰り返し指定可能 | -## 配信・メンテナンスフラグ +## 配信とメンテナンスフラグ | コマンド | フラグ | | --- | --- | @@ -100,11 +118,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -サポートされるハーネス名は `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose` です。 +サポートされているハーネス名は `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose` です。 -ラベルは、2 つのルートに同じプロジェクトのコピーが存在する場合に、派生エージェント ID の名前空間を分けます。重複した収集やカーソルの破損を防ぐため、重複するルートや同一ラベルは拒否されます。追加パスの設定はデーモンを再起動せずにリロードされます。 +ラベルは、2 つのルートが同じプロジェクトのコピーを含む場合に、派生エージェント ID を名前空間で区別します。重複するルートと重複するラベルは、収集の重複やカーソルの破損を防ぐために拒否されます。追加パスの設定はデーモンの再起動なしにリロードされます。 -コンテナ環境では、ファイルで設定された追加パスを `FAILPROOFAI__EXTRA_PATHS` という名前のカンマ区切り変数で置き換えることができます。例： +コンテナ環境では、ファイルで設定された追加パスをカンマ区切りの変数 `FAILPROOFAI__EXTRA_PATHS` で置き換えることができます。例: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -116,24 +134,26 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl | 変数 | 用途 | | --- | --- | -| `FAILPROOFAI_HOME` | `~/.failproofai` レイアウト全体を移動 | -| `FAILPROOFAI_LOG_LEVEL` | ローカルロギングの詳細度を設定 | +| `FAILPROOFAI_CLOUD_TOKEN` | `--token` の代わりに使用する Cloud キー。こちらを推奨: 引数はシステム上のすべてのユーザーが `ps` で読み取れます。`read -s` または CI のシークレットストアから設定し、コマンドに直接キーを入力しないでください（どちらの方法でもシェル履歴に残ります） | +| `FAILPROOFAI_CLOUD_URL` | `--url` の代わりに使用する Cloud URL。デーモンが読み取るのと同じ変数 | +| `FAILPROOFAI_HOME` | `~/.failproofai` レイアウト全体を別の場所に移動 | +| `FAILPROOFAI_LOG_LEVEL` | ローカルログの詳細レベルを設定 | | `FAILPROOFAI_HOOK_LOG_FILE` | フック診断を指定ファイルに書き込み | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | このプロセスの匿名テレメトリを無効化 | -| `FAILPROOFAI_NO_FIRST_RUN=1` | インタラクティブな初回セットアップをスキップ | +| `FAILPROOFAI_NO_FIRST_RUN=1` | 対話的な初回セットアップをスキップ | | `FAILPROOFAI_NO_AUTO_AUDIT=1` | セットアップ後のローカル監査をスキップ | | `FAILPROOFAI_LLM_BASE_URL` | LLM ポリシーが使用する OpenAI 互換エンドポイントを上書き | | `FAILPROOFAI_LLM_API_KEY` | LLM ポリシーが使用する API キーを提供 | | `FAILPROOFAI_LLM_MODEL` | LLM ポリシーが使用するモデルを選択 | | `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | カスタムポリシーモジュールの読み込み時間を制限 | -| `FAILPROOFAI_NO_DOWNLOAD=1` | パックとデーモンバイナリの取得を拒否。インストール済みのものはそのまま適用 | +| `FAILPROOFAI_NO_DOWNLOAD=1` | パックとデーモンバイナリの取得を拒否; インストール済みのものは引き続き適用 | | `FAILPROOFAI_PACK_BASE_URL` | `github.com` の代わりにミラーからパックを取得 | | `FAILPROOFAI__EXTRA_PATHS` | 1 つのハーネスに設定された追加キャプチャパスを置き換え | -| `NO_COLOR` | ターミナルのカラー出力を無効化 | +| `NO_COLOR` | カラーターミナル出力を無効化 | `CLAUDE_PROJECTS_PATH`、`CURSOR_HOME`、`HERMES_HOME`、`OPENCLAW_HOME` などのエージェント固有のホーム変数は、Failproof AI がそのハーネスのローカルセッションを検出する場所を上書きします。 -## マシンの安全な一時停止または削除 +## マシンを安全に一時停止または削除する ```bash failproofai config --pause @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -ローカルセッションの一時停止は Cloud 管理ポリシーを無効化しません。ロールアウト自体に問題がある場合は、Cloud 強制適用ワークフローを通じて Cloud デプロイメントを復元してください。 +ローカルセッションの一時停止は Cloud 管理のポリシーを無効化しません。ロールアウト自体が問題の場合は、Cloud の適用ワークフローを通じて Cloud のデプロイを復元してください。 -npm パッケージを削除する前に、インストール済みフックとデーモンを削除してください： +npm パッケージを削除する前に、インストール済みのフックとデーモンを削除してください: ```bash failproofai uninstall --dry-run @@ -151,8 +171,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -バージョン固有の詳細については `failproofai --help` を実行してください。 +バージョン固有の詳細は `failproofai --help` で確認してください。 - `npm rm -g failproofai` の前に `failproofai uninstall` を実行してください。npm はインストール済みエージェントフックやデーモンサービスを削除しません。 + `npm rm -g failproofai` の前に `failproofai uninstall` を実行してください。npm はインストール済みのエージェントフックやデーモンサービスを削除しません。 \ No newline at end of file diff --git a/docs/ja/reference/harnesses.mdx b/docs/ja/reference/harnesses.mdx index 87cf43d2..98da7ff2 100644 --- a/docs/ja/reference/harnesses.mdx +++ b/docs/ja/reference/harnesses.mdx @@ -1,80 +1,86 @@ --- title: "エージェントハーネス" -description: "サポートされている12のエージェントハーネス全体でセッションをキャプチャし、ポリシーを適用します。" +description: "サポートされている12種類のエージェントハーネス全体でセッションをキャプチャし、ポリシーを適用します。" icon: "plug-zap" --- -ハーネスとは、エージェントが実際に動作する環境のことです。Failproof AI は12種類のハーネスをサポートしており、2つのクラスに分類されます。 +ハーネスとは、エージェントが実際に動作する環境のことです。Failproof AI は2種類、計12のハーネスをサポートしています。 -- **コーディングCLI**（10種）— Claude Code、Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi、Factory Droid、Devin CLI、Antigravity CLI、Goose -- **チャットおよびアシスタントゲートウェイ**（2種）— Hermes（Slack、Telegram、cron）、OpenClaw（セルフホスト型アシスタント） +- **コーディングCLI**（10種類）— Claude Code、Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi、Factory Droid、Devin CLI、Antigravity CLI、Goose +- **チャット・アシスタントゲートウェイ**（2種類）— Hermes（Slack、Telegram、cron）、OpenClaw（セルフホスト型アシスタント） -エージェントがどのハーネスで動作していても、同一のポリシーおよびセッション履歴が適用されます。アダプターレイヤーは、各ハーネスのネイティブイベント名・ツール名・ツール入力フィールドを、ポリシーが実行される前に29の標準イベントへとマッピングします。 +どのハーネスでエージェントが動作していても、同じポリシーと同じセッション履歴が適用されます。1つのアダプター層が、各ハーネス固有のイベント名・ツール名・ツール入力フィールドを、ポリシー実行前に29種類の標準イベントへマッピングします。 -12種類のいずれにも該当しないハーネスで動作するエージェントには、[Python SDK](/ja/reference/custom-agents) を使って直接インスツルメンテーションを行います。これは異なる契約であり、明示しておく価値があります。SDKはトレーシング・セッション・評価・監査を提供しますが、**それ自体でポリシーを適用するわけではありません。** 実行前に安全でないアクションをブロックするには、ランタイムのツール境界に適用フックが必要です。[お問い合わせ](mailto:support@befailproof.ai)いただければマッピングを行います。 +12種類のいずれにも該当しないエージェントは、[Python SDK](/ja/reference/custom-agents) を使って直接インストルメント化されます。これは異なる契約であり、明確にお伝えしておくべき点があります。SDKはトレーシング・セッション・評価・監査を提供しますが、**ポリシーを単独で適用する機能はありません。** 実行前に安全でないアクションをブロックするには、ランタイムのツール境界に強制フックが必要です。[お問い合わせ](mailto:support@befailproof.ai)いただければ、マッピングをご支援します。 | ハーネス | サポートされるフックスコープ | | --- | --- | -| Claude Code | ユーザー、プロジェクト、ローカル | -| Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi | ユーザー、プロジェクト | -| Factory Droid、Devin CLI、Antigravity CLI、Goose | ユーザー、プロジェクト | -| Hermes、OpenClaw | ユーザー | +| Claude Code | User、project、local | +| Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi | User、project | +| Factory Droid、Devin CLI、Antigravity CLI、Goose | User、project | +| Hermes、OpenClaw | User | -各インテグレーションは、ポリシーが実行される前に、ネイティブのフックイベント名・ツール名・ツール入力フィールドを正規化します。ポリシーが作用できるのは、ハーネスが公開しているイベントのみです。ターン終了時や命令の動作については、実際にデプロイするハーネスとバージョンで必ずテストしてください。 +各インテグレーションは、ポリシー実行前にハーネス固有のフックイベント名・ツール名・ツール入力フィールドを正規化します。ポリシーはハーネスが公開するイベントに対してのみ作用します。エンドオブターンの動作やインストラクションの動作は、実際にデプロイするハーネスとバージョンで必ずテストしてください。 -## 適用機能 +## 強制適用の機能 -「ブロック」とは、現在のアダプターが返した判定が指定のハーネスによって消費されることを意味します。ツール実行後のブロックは、モデルに表示される結果を差し替えることはできますが、すでに発生したツールの副作用を取り消すことはできません。 +「ブロック」とは、現在のアダプターが返した判定を対象ハーネスが受け入れることを意味します。ツール後のブロックはモデルに示される結果を置き換えることができますが、既に発生したツールの副作用を元に戻すことはできません。 -| ハーネス | 検証済みブロックイベント | 観測のみまたは非ブロックの注意事項 | +| ハーネス | 検証済みブロックイベント | 観察のみ、またはブロック非対応の注意事項 | | --- | --- | --- | -| Claude Code | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PreCompact`、および複数のタスク/設定イベント | `PostToolUse`、セッションライフサイクル、通知、および失敗後のイベントは観測のみ。 | -| Codex | `PreToolUse`、`PermissionRequest`、`UserPromptSubmit`、`Stop`、`SubagentStop`、`PostToolUse` | ツール実行後のブロックは実行後に結果を差し替えます。セッション開始およびコンパクトイベントは現在のアダプターでは観測のみ。 | -| GitHub Copilot CLI | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PostToolUse` | ツール実行後のブロックは実行後に結果を差し替えます。セッションおよび通知イベントは観測のみ。 | -| Cursor | `PreToolUse`、`UserPromptSubmit`、`Stop` | `PostToolUse` およびセッションイベントは観測のみ。 | -| OpenCode | `PreToolUse` | ツール実行後およびライフサイクルイベントは観測のみ。現在のストップ処理は検証済みゲートではなく、後続ターンへのガイダンスとして機能します。 | -| Pi | `PreToolUse`、`UserPromptSubmit` | ツール実行後およびライフサイクルイベントは観測のみ。ストップガイダンスは後続ターンに適用されます。 | -| Hermes | `PreToolUse` | ツール実行後・セッション・サブエージェントストップの判定はゲートとして機能しません。 | -| OpenClaw | `PreToolUse`、`UserPromptSubmit`、`Stop` | ツール実行後・セッション・サブエージェントストップ・コンパクションイベントは観測のみ。 | -| Factory Droid | `PreToolUse`、`UserPromptSubmit`、`Stop`、`PreCompact` | ツール実行後およびサブエージェントストップの判定は観測のみ。 | -| Devin CLI | `PreToolUse`、`UserPromptSubmit`、`Stop`、条件付き `PermissionRequest` | パーミッションフックはすべてのパーミッションモードで実行されるわけではありません。ツール実行後およびセッションイベントは観測のみ。 | -| Antigravity CLI | `PreToolUse`、`Stop` | ユーザープロンプトおよびツール実行後の判定は観測のみ。プロンプト命令の注入は引き続き可能です。 | -| Goose | `PreToolUse` | ユーザープロンプト・ツール実行後・セッションイベントは観測のみ。ネイティブのブロック用ストップフックはアップストリームに存在しますが、現在のアダプターではインストールされていません。 | - -機能はバージョンに依存します。特にポリシーがプロンプト・ストップ・パーミッション・ツール実行後の動作に依存している場合（共通のプリツールゲートではなく）、エージェントCLIをアップグレードした後は必ず再テストしてください。 +| Claude Code | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PreCompact`、およびいくつかのタスク/設定イベント | `PostToolUse`、セッションライフサイクル、通知、失敗後イベントは観察のみ。 | +| Codex | `PreToolUse`、`PermissionRequest`、`UserPromptSubmit`、`Stop`、`SubagentStop`、`PostToolUse` | ツール後のブロックは実行後に結果を置き換えます。セッション開始およびコンパクトイベントは現在のアダプターでは観察のみ。 | +| GitHub Copilot CLI | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PostToolUse` | ツール後のブロックは実行後に結果を置き換えます。セッションおよび通知イベントは観察のみ。 | +| Cursor | `PreToolUse`、`UserPromptSubmit`、`Stop` | `PostToolUse` およびセッションイベントは観察のみ。 | +| OpenCode | `PreToolUse` | ツール後およびライフサイクルイベントは観察のみ。現在のストップ処理は検証済みゲートではなく、後続ターンへのガイダンスとして機能。 | +| Pi | `PreToolUse`、`UserPromptSubmit` | ツール後およびライフサイクルイベントは観察のみ。ストップガイダンスは後続ターンに適用。 | +| Hermes | `PreToolUse` | ツール後、セッション、サブエージェントストップの判定はゲートとして機能しません。 | +| OpenClaw | `PreToolUse`、`UserPromptSubmit`、`Stop` | ツール後、セッション、サブエージェントストップ、コンパクションイベントは観察のみ。 | +| Factory Droid | `PreToolUse`、`UserPromptSubmit`、`Stop`、`PreCompact` | ツール後およびサブエージェントストップの判定は観察のみ。 | +| Devin CLI | `PreToolUse`、`UserPromptSubmit`、`Stop`、条件付き `PermissionRequest` | パーミッションフックはすべてのパーミッションモードで実行されるわけではありません。ツール後およびセッションイベントは観察のみ。 | +| Antigravity CLI | `PreToolUse`、`Stop` | ユーザープロンプトおよびツール後の判定は観察のみ。プロンプトインストラクションのインジェクションは引き続き可能。 | +| Goose | `PreToolUse` | ユーザープロンプト、ツール後、セッションイベントは観察のみ。ネイティブのブロッキングストップフックは上流に存在しますが、現在のアダプターではインストールされていません。 | + +機能はバージョンに依存します。エージェントCLIをアップグレードした後は、特にポリシーが共通のプリツールゲートではなく、プロンプト・ストップ・パーミッション・ツール後の動作に依存している場合は、必ず再テストを行ってください。 ## キャプチャとポリシーフックのインストール - 1. **管理 → キー** を開き、`events:add` および `policies:pull` 権限を持つキーを作成します。マシンまたは環境に合わせた名前を付けてください。 + 1. **Administration → Keys** を開き、`events:add` と `policies:pull` の権限を持つキーを作成します。マシンまたは環境の名前を付けてください。 2. 対象マシンで、表示されたキーを使ってローカルCLIを接続し、ハーネスフックをインストールします。 - 3. 新しいエージェントセッションを開始し、**観察 → イベント** でフックとセッションのイベントを確認します。 - 4. 同じ時間帯で **観察 → ポリシー** を開き、そのマシンに帰属するポリシー決定を確認します。 + 3. 新しいエージェントセッションを開始し、**Observe → Events** でフックとセッションイベントを確認します。 + 4. 同じ時間帯の **Observe → policy** を開き、そのマシンにポリシー決定が帰属していることを確認します。 - 接続はマシンキーから始まります。シークレットをコピーする前に、取り込みとポリシー配信の両方の権限が含まれていることを確認してください。 + 接続はマシンキーから始まります。シークレットをコピーする前に、インジェストとポリシー配信の両方の権限が含まれていることを確認してください。 - ![イベント取り込みおよびポリシー配信権限を付与するための新規APIキードロワー。](/images/dashboard/key-create.png) + ![イベントインジェストとポリシー配信の権限を付与するための新しいAPIキードロワー。](/images/dashboard/key-create.png) - フックをインストールすると、接続したマシンと環境から新しいイベントがイベントストリームに表示されるはずです。 + フックをインストールした後、Eventsストリームに接続したマシンと環境からの新しいイベントが表示されるはずです。 - ![新しくインストールされたハーネスがレポートしていることを確認するためのライブイベントストリーム。](/images/dashboard/events-stream.png) + ![新しくインストールされたハーネスが報告していることを確認するためのライブEventsストリーム。](/images/dashboard/events-stream.png) 最後に、ポリシー決定が同じマシンに帰属していることを確認します。これにより、ハーネスがトレースイベントだけでなくポリシーアクティビティも報告していることが確認できます。 - ![新しく接続されたハーネスからのポリシー決定を確認するためのポリシーページ。](/images/dashboard/policy-observe.png) + ![新しく接続されたハーネスからのポリシー決定を確認するためのPolicyページ。](/images/dashboard/policy-observe.png) - 検出されたすべてのハーネスにフックをインストールします。 + マシンキーをシェルに読み込みます。`read -s` はエコーされないプロンプトでキーを受け取るため、コマンドやシェル履歴に残ることはありません。 ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - または、特定のハーネスと設定スコープを指定します。 + 次にマシンをセットアップします。検出されたすべてのハーネスにフックを接続し、デーモンをインストールし、Cloudに接続します。 + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + セットアップ自体はポリシーを有効にしません。それが2番目のコマンドの役割です。 + + または、特定のハーネスと設定スコープを指定することもできます。 ```bash failproofai policies --install \ @@ -82,7 +88,7 @@ icon: "plug-zap" --scope user ``` - プロジェクトスコープはフック設定をリポジトリに紐付けます。ユーザースコープはリポジトリをまたいだ作業全体をカバーします。Claude Code はローカルスコープもサポートしています。サポート状況はハーネスによって異なり、CLIはサポートされていない組み合わせを拒否します。 + プロジェクトスコープはフック設定をリポジトリと一緒に管理します。ユーザースコープはリポジトリをまたいだ作業をカバーします。Claude Code はローカルスコープもサポートしていますが、サポート状況はハーネスによって異なり、CLIはサポートされていない組み合わせを拒否します。 マシンとそのイベントを確認します。 @@ -94,13 +100,13 @@ icon: "plug-zap" -## デフォルト以外のセッションパスの追加 +## デフォルト以外のセッションパスを追加する - 追加パスはクラウドではなく、マシン上に登録されます。追加後、**観察 → セッション** を開き、マシンの環境でフィルタリングして、新しいパスからのセッションが表示されることを確認します。セッションを開き、監査に使用する前にエージェント・ハーネス・イベントのタイムスタンプを確認してください。 + 追加パスはマシン上に登録されます（Cloud上ではありません）。追加後、**Observe → Sessions** を開き、マシンの環境でフィルタリングして、新しいパスからのセッションが表示されることを確認してください。セッションを開いて、監査で使用する前にエージェント・ハーネス・イベントのタイムスタンプを確認してください。 - ![追加のキャプチャパスからデータを受信している環境でフィルタリングされたセッションリスト。](/images/dashboard/sessions-list.png) + ![追加のキャプチャパスからデータを受信している環境にフィルタリングされたSessionsリスト。](/images/dashboard/sessions-list.png) オプションのラベルを付けてパスを追加し、設定済みパスを確認します。 diff --git a/docs/ja/reference/overview.mdx b/docs/ja/reference/overview.mdx index aac88e79..c6e9a659 100644 --- a/docs/ja/reference/overview.mdx +++ b/docs/ja/reference/overview.mdx @@ -1,6 +1,6 @@ --- title: "インテグレーションとリファレンス" -description: "対応エージェントハーネス、SDK、CLI、HTTP API を接続する。" +description: "対応エージェントハーネス、SDK、CLI、HTTP APIを接続します。" icon: "braces" --- @@ -8,12 +8,12 @@ icon: "braces" - 対応するコーディング・自律エージェント CLI 向けにフックをインストールします。 + 対応するコーディング・自律エージェントCLIにフックをインストールします。 - - LangGraph、CrewAI、LlamaIndex、Pydantic AI、またはカスタムエージェントをインストルメント化します。 + + LangGraph、CrewAI、LlamaIndex、Pydantic AI、またはカスタムエージェントを計装します。 - + 設定、イベントカタログ、相関ルール、デリバリーについて説明します。 @@ -23,59 +23,62 @@ icon: "braces" ローカルキャプチャ、フック、ポリシー、監査、デリバリー、マシン状態を設定します。 - Cloud のセッション、監査、イシュー、アラート、キー、ユーザー、設定をクエリおよび管理します。 + クラウドのセッション、監査、Issue、アラート、キー、ユーザー、設定を照会・管理します。 - - FastAPI サービスを使用して完了済みまたは非アクティブなセッションをスコアリングします。 + + FastAPIサービスを使って完了済みまたは非アクティブなセッションをスコアリングします。 - ワークフロー固有の allow、instruct、deny の判断を作成・テストします。 + ワークフロー固有のallow、instruct、deny判定を作成・テストします。 - 顧客管理の Kubernetes クラスター上に Cloud コントロールプレーンをデプロイします。 + 顧客管理のKubernetesクラスターにクラウドコントロールプレーンをデプロイします。 -生成された [HTTP API リファレンス](/ja/reference/http-api) は公開 `/v1` サーフェスを対象としています。手書きのページでは、複数のエンドポイントにまたがるワークフローや、その公開サーフェス外の管理インターフェースを使用するワークフローについて説明しています。 +自動生成された[HTTP APIリファレンス](/ja/reference/http-api)は公開 `/v1` サーフェスを網羅しています。手書きのページでは、複数のエンドポイントにまたがるワークフローや、その公開サーフェス外の管理インターフェースを使用するフローについて説明しています。 ## エージェントを接続してデータを確認する - 1. **管理 → キー** を開き、`events:add` および `policies:pull` 権限を持つキーを作成してシークレットをコピーします。 - 2. 上記の対応するページを参考にインテグレーションを設定します。 - 3. **観察 → イベント** を開いてイベントが届いていることを確認し、次に **観察 → セッション** を開いて完全な実行として形成されていることを確認します。 - 4. インテグレーションの環境でフィルタリングし、監査に必要なモデル、ツール、エラー、ポリシーフィールドを含む 1 つのセッションを検査します。 + 1. **Administration → Keys** を開き、`events:add` と `policies:pull` の権限を持つキーを作成してシークレットをコピーします。 + 2. 上記の対応するページを使ってインテグレーションを設定します。 + 3. **Observe → Events** を開いてイベントが届いていることを確認し、次に **Observe → Sessions** で完全な実行としてまとめられていることを確認します。 + 4. インテグレーションの環境でフィルタリングし、1つのセッションを開いて監査に必要なモデル、ツール、エラー、ポリシーの各フィールドを確認します。 - まずキードロワーから始めます。選択した権限によって、マシンがイベントを送信し、Cloud 管理のポリシーを受信できるかどうかが決まります。 + まずキードロワーから始めてください。選択した権限によって、マシンがイベントを送信できるか、クラウド管理ポリシーを受信できるかが決まります。 - ![イベント取り込みとポリシーデリバリー権限を付与するための新しい API キードロワー。](/images/dashboard/key-create.png) + ![イベント取り込みとポリシー配信の権限を付与するための新しいAPIキードロワー。](/images/dashboard/key-create.png) - インテグレーションを接続した後、セッション一覧を使用して、イベントが期待される環境で完全な実行としてグループ化されていることを確認します。 + インテグレーションを接続したら、セッションリストを使って、そのイベントが想定された環境内で完全な実行としてグループ化されていることを確認してください。 - ![新しく接続されたインテグレーションが完全なエージェント実行を報告していることを確認するためのセッション一覧。](/images/dashboard/sessions-list.png) + ![新しく接続したインテグレーションが完全なエージェント実行を報告していることを確認するためのセッションリスト。](/images/dashboard/sessions-list.png) - インテグレーションが完了したと判断する前に、これらのセッションの 1 つを開きます。トレースには、監査に必要なモデル、ツール、エラー、ポリシーの証跡が含まれているはずです。 + インテグレーションが完了したと判断する前に、これらのセッションのうち1つを開いてください。トレースには、監査に必要なモデル、ツール、エラー、ポリシーのエビデンスが含まれているはずです。 - マシンキーを作成し、Failproof デーモンを接続して、最初のセッションを確認します。 + マシンキーを作成し、表示されたシークレットをシェルに読み込みます。`read -s` はエコーしないプロンプトで入力を受け取るため、コマンドやシェル履歴に記録されることはありません。 ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Failproofデーモンを接続して最初のセッションを確認します。 - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - 別のツールが結果を処理する場合は `fp --json sessions ...` を使用してください。`--json`、`--org`、`--base-url` などのグローバルフラグはコマンドの前に記述する必要があります。 + 別のツールが結果を処理する場合は `fp --json sessions ...` を使用してください。`--json`、`--org`、`--base-url` などのグローバルフラグはコマンドの前に指定する必要があります。 - ローカルコマンドについては [Failproof AI CLI リファレンス](/ja/reference/failproof-cli) を、`fp` コマンドについては [Failproof Cloud CLI リファレンス](/ja/reference/cloud-cli#cli-commands) を参照してください。 + ローカルコマンドについては[Failproof AI CLIリファレンス](/ja/reference/failproof-cli)を、`fp` コマンドについては[Failproof Cloud CLIリファレンス](/ja/reference/cloud-cli#cli-commands)を参照してください。 \ No newline at end of file diff --git a/docs/ja/reference/policy-sdk.mdx b/docs/ja/reference/policy-sdk.mdx index 24a8fc9b..ff0a49b8 100644 --- a/docs/ja/reference/policy-sdk.mdx +++ b/docs/ja/reference/policy-sdk.mdx @@ -1,35 +1,35 @@ --- title: "カスタムポリシー" -description: "エージェント固有の障害に対応するJavaScriptまたはTypeScriptのポリシーを作成、テスト、デプロイします。" +description: "エージェント固有の障害に対応するJavaScriptまたはTypeScriptポリシーの作成、テスト、デプロイ。" icon: "shield-plus" --- -カスタムポリシーは、トレースや監査から得た障害パターンを、エージェントの動作中にリアルタイムで実行される判断に変換します。ポリシーはアクションを許可したり、エージェントにガイダンスを提供したり、問題が再発する前にアクションを拒否したりできます。 +カスタムポリシーは、トレースや監査から得られた障害パターンを、エージェントの動作中にリアルタイムで実行される判断に変換します。ポリシーはアクションを許可したり、エージェントにガイダンスを提供したり、別のインシデントを引き起こす前にアクションを拒否したりできます。 -ツール、パス、コマンド、環境、または運用ルールに依存する動作に対してカスタムポリシーを使用してください。既存の制御を再作成しないよう、まず[組み込みポリシーカタログ](/ja/policies/builtin-catalog)を確認してください。 +動作がツール、パス、コマンド、環境、または運用ルールに依存する場合はカスタムポリシーを使用してください。既存のコントロールを再作成しないよう、まず [Failproof AI ポリシーパック](/ja/policies/packs) を確認してください。 -## カスタムポリシーを作成する +## カスタムポリシーの作成 - 1. **Admin → policy editor** に移動し、**New policy** を選択して、防止したい障害を説明します。 - 2. ポリシーソースを追加し、エディターで期待される一致ケースと安全な非一致ケースをテストします。すべてのバリデーションエラーを解消してください。 - 3. ドラフトを保存し、**Publish version** を選択してイミュータブルなバージョンを作成します。 - 4. **Admin → enforcement** に移動し、テストマシンに **observe** モードでバージョンをデプロイし、適用前に **Observe → policy** で判断内容を確認します。 + 1. **Admin → ポリシーエディター** に移動し、**新しいポリシー** を選択して、防止したい障害を説明します。 + 2. ポリシーソースを追加し、エディターで期待されるマッチと安全な非マッチをテストします。すべてのバリデーションエラーを解消します。 + 3. ドラフトを保存し、**バージョンを公開** を選択して不変バージョンを作成します。 + 4. **Admin → 施行** に移動し、**観察** モードでテストマシンにバージョンをデプロイし、施行する前に **観察 → ポリシー** で決定を確認します。 - ![カスタムポリシーを作成・公開するためのポリシーエディター。](/images/dashboard/policy-editor.png) + ![カスタムポリシーの作成と公開に使用するポリシーエディター。](/images/dashboard/policy-editor.png) 1. `.failproofai/policies/checkout-policies.ts` を作成します。ファイル名は `policies.js`、`policies.mjs`、または `policies.ts` で終わる必要があります。 2. `customPolicies.add()` で1つ以上のポリシーを登録します。 3. `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project` でファイルをバリデートしてインストールします。 - 4. 一致するアクションと安全なアクションを1つずつトリガーします。`failproofai policies` を実行し、**Observe → policy** で帰属する判断内容を確認します。 + 4. マッチするアクションと安全なアクションをそれぞれ1回トリガーします。`failproofai policies` を実行し、**観察 → ポリシー** で帰属する決定を確認します。 ## 狭いルールから始める -このポリシーは、コマンドがproduction環境を対象としている場合にのみ、破壊的なKubernetesコマンドをブロックします。その正確な障害モード以外のすべてのケースは `allow()` を返します。 +このポリシーは、コマンドがproductionをターゲットにしている場合にのみ、破壊的なKubernetesコマンドをブロックします。この厳密な障害モード以外はすべて `allow()` を返します。 ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,20 +55,20 @@ customPolicies.add({ }); ``` -良いポリシーは、一文で説明できるほど狭いものです。エージェントの意図ではなく、観測可能なアクションにマッチさせ、ルールが適用されない場合はすぐに `allow()` を返します。 +良いポリシーは1文で説明できるほど狭いものです。エージェントの意図ではなく、観察可能なアクションにマッチさせ、ルールが適用されない場合はすぐに `allow()` を返します。 -## 判断を選択する +## 決定を選択する -| ヘルパー | 結果 | 使用するタイミング | +| ヘルパー | 結果 | 使用する場面 | | --- | --- | --- | -| `allow(reason?)` | 操作が続行される。 | ポリシーが適用されない場合、またはアクションが安全な場合。 | -| `instruct(reason)` | ハーネスがサポートしている場合、ガイダンス付きで操作が続行される。 | 不変条件を強制せずにエージェントをより良いアプローチへ誘導したい場合。 | -| `deny(reason)` | イベントとハーネスがブロックをサポートしている場合、操作がブロックされる。 | アクションを進めてはならない場合。 | +| `allow(reason?)` | 操作が続行されます。 | ポリシーが適用されないか、アクションが安全な場合。 | +| `instruct(reason)` | ハーネスがサポートしている場合、ガイダンス付きで操作が続行されます。 | 不変条件を強制せずにエージェントをより良いアプローチに誘導したい場合。 | +| `deny(reason)` | イベントとハーネスがブロックをサポートしている場合、操作がブロックされます。 | アクションを進めてはならない場合。 | -理由は回復しなければならないエージェント向けに記述してください。何が検出されたか、そして代わりに何をすべきかを説明してください。 +理由は回復しなければならないエージェント向けに書いてください。何が検出されたか、代わりに何をすべきかを説明します。 - 安全境界には `instruct()` を使用しないでください。ガイダンスの配信はエージェントハーネスによって異なります。アクションを防止しなければならない場合は `deny()` を使用してください。 + 安全境界に `instruct()` を使用しないでください。ガイダンスの配信はエージェントハーネスによって異なります。アクションを防止しなければならない場合は `deny()` を使用してください。 ## ポリシーオブジェクト @@ -84,8 +84,8 @@ customPolicies.add({ | フィールド | 必須 | 説明 | | --- | --- | --- | -| `name` | はい | ポリシーの安定した識別子。ファイル間でユニークな名前を維持してください。 | -| `description` | いいえ | ポリシー一覧や判断に表示される人間が読める目的の説明。 | +| `name` | はい | ポリシーの安定した識別子。ファイル間で名前をユニークに保ちます。 | +| `description` | いいえ | ポリシー一覧や決定に表示される人間が読める目的の説明。 | | `match.events` | いいえ | ポリシーを呼び出すイベントタイプ。`match` を省略すると、利用可能なすべてのイベントに対して呼び出されます。 | | `fn` | はい | `allow`、`instruct`、または `deny` の結果を返す同期または非同期関数。 | @@ -103,23 +103,23 @@ customPolicies.add({ | `payload` | `Record` | 完全な正規化されたイベントペイロード。 | | `session` | `SessionMetadata \| undefined` | セッションID、作業ディレクトリ、トランスクリプトパス、パーミッションモード、および利用可能な場合のハーネスメタデータ。 | | `cli` | `string \| undefined` | `claude`、`codex`、`cursor` などのソースエージェントハーネス。 | -| `params` | `Record` | 組み込みポリシーのパラメータ。カスタムポリシーは現在空のオブジェクトを受け取ります。 | +| `params` | `Record` | 組み込みポリシーパラメーター。カスタムポリシーは現在空のオブジェクトを受け取ります。 | -すべてのオプション値は本当にオプションとして扱ってください。エージェントのバージョンやイベントタイプによって、提供されるフィールドが異なります。 +すべてのオプション値を本当にオプションとして扱ってください。エージェントのバージョンとイベントタイプによって提供されるフィールドは異なります。 -### 一般的なツール入力 +### 共通ツール入力 -Failproof AI はサポートされているハーネス間で一般的なツールを正規化するため、通常1つの入力形式でポリシーを使用できます。 +Failproof AI はサポートされているハーネス間で共通ツールを正規化するため、ポリシーは通常1つの入力形式を使用できます。 | ツール | 共通フィールド | | --- | --- | | `Bash` | `command` | | `Read` | `file_path` | -| `Write` | `file_path`、`content` | -| `Edit` | `file_path`、`old_string`、`new_string` | -| `Grep` | `pattern`、`path` | +| `Write` | `file_path`, `content` | +| `Edit` | `file_path`, `old_string`, `new_string` | +| `Grep` | `pattern`, `path` | -ツール入力値は `unknown` として型付けされているため、防御的な型変換を使用してください： +ツール入力値は `unknown` 型であるため、防御的な型変換を使用してください： ```ts const command = String(ctx.toolInput?.command ?? ""); @@ -128,23 +128,23 @@ const filePath = String(ctx.toolInput?.file_path ?? ""); ## イベントを選択する -| イベント | 実行タイミング | 典型的な用途 | +| イベント | 実行タイミング | 主な用途 | | --- | --- | --- | -| `PreToolUse` | ツールの実行前。 | コマンド、書き込み、読み取り、外部アクションのブロックまたはガイド。 | -| `PostToolUse` | ツールの返却後。 | エージェントに届く前に結果を検査する。denyはすべての結果をブロックし、特定フィールドを編集するわけではない。 | -| `PermissionRequest` | エージェントがパーミッションをリクエストする時。 | 組織固有のパーミッションルールを適用する。 | -| `UserPromptSubmit` | 送信されたプロンプトが続行する前。 | 禁止された指示を拒否したり、ワークフローガイダンスを追加したりする。 | -| `Stop` | エージェントが終了しようとする時。 | ローカル検証ステップなど、達成可能な完了条件を要求する。 | -| `SubagentStop` | サブエージェントが終了しようとする時。 | 委任された作業が親に戻る前にゲート処理する。 | -| `SessionStart` / `SessionEnd` | セッションの境界時。 | セッションレベルの状態を記録または確認する。 | +| `PreToolUse` | ツール実行前。 | コマンド、書き込み、読み取り、外部アクションのブロックまたは誘導。 | +| `PostToolUse` | ツール返却後。 | エージェントに届く前に結果を検査します。denyはすべての結果をブロックします；選択したフィールドのみを削除することはできません。 | +| `PermissionRequest` | エージェントがパーミッションを要求したとき。 | 組織固有のパーミッションルールを適用します。 | +| `UserPromptSubmit` | 送信されたプロンプトが続行される前。 | 禁止された指示を拒否するか、ワークフローガイダンスを追加します。 | +| `Stop` | エージェントが終了しようとしたとき。 | ローカルの検証ステップなど、到達可能な完了条件を要求します。 | +| `SubagentStop` | サブエージェントが終了しようとしたとき。 | 委任された作業が親に返る前にゲートします。 | +| `SessionStart` / `SessionEnd` | セッション境界で。 | セッションレベルの状態を記録または確認します。 | -イベントの可用性とブロック動作はエージェントハーネスによって異なります。混在フリートでイベントに依存する前に、[エージェントハーネス](/ja/reference/harnesses)を確認してください。 +イベントの可用性とブロック動作はエージェントハーネスによって異なります。混合フリートでイベントに依存する前に [エージェントハーネス](/ja/reference/harnesses) を参照してください。 `SessionStart`、`SessionEnd`、`UserPromptSubmit`、`PreToolUse`、`PermissionRequest`、`PermissionDenied`、`PostToolUse`、`PostToolUseFailure`、`Notification`、`SubagentStart`、`SubagentStop`、`TaskCreated`、`TaskCompleted`、`Stop`、`StopFailure`、`TeammateIdle`、`InstructionsLoaded`、`ConfigChange`、`CwdChanged`、`FileChanged`、`WorktreeCreate`、`WorktreeRemove`、`PreCompact`、`PostCompact`、`Elicitation`、`ElicitationResult`、`UserPromptExpansion`、`PostToolBatch`、`Setup`。 -## 一般的なポリシーパターンを作成する +## 一般的なポリシーパターンの作成 ### 保護されたパスへの書き込みをブロックする @@ -166,7 +166,7 @@ customPolicies.add({ }); ``` -### ノンブロッキングガイダンスを提供する +### 非ブロッキングのガイダンスを提供する ```ts import { customPolicies, allow, instruct } from "failproofai"; @@ -215,10 +215,10 @@ customPolicies.add({ ``` - 拒否された `Stop` イベントはエージェントを再試行させる可能性があります。現在の環境でエージェントが満たせる条件のみをゲートとして使用し、すべてのサブプロセスやネットワーク呼び出しに上限を設けてください。 + `Stop` イベントが拒否されると、エージェントが再試行する可能性があります。現在の環境でエージェントが満たせる条件のみにゲートし、すべてのサブプロセスやネットワーク呼び出しに制限を設けてください。 -## ポリシーファイルを読み込む +## ポリシーファイルの読み込み ### コンベンションファイル @@ -229,16 +229,16 @@ customPolicies.add({ ~/.failproofai/policies/personal-policies.mjs ``` -- プロジェクトとユーザーのポリシーディレクトリは両方とも読み込まれます。 +- プロジェクトとユーザーのポリシーディレクトリは両方読み込まれます。 - ファイルは各ディレクトリ内でアルファベット順に読み込まれます。 - ファイルは `policies.js`、`policies.mjs`、または `policies.ts` で終わる必要があります。 -- 1つのファイルで複数の `customPolicies.add()` 呼び出しがサポートされています。 +- 1つのファイル内で複数の `customPolicies.add()` 呼び出しがサポートされています。 - ローカルモジュールからの相対インポートがサポートされています。 -- プロジェクトポリシーはコミットできるため、同じルールがリポジトリに従います。 +- プロジェクトポリシーはコミットでき、同じルールがリポジトリに従います。 ### 明示的なファイル -バリデーションや設定でエントリファイルを直接指定する必要がある場合は、明示的なパスを使用してください： +バリデーションや設定でエントリーファイルを直接指定する場合は明示的なパスを使用してください： ```bash failproofai policies --install \ @@ -247,11 +247,11 @@ failproofai policies --install \ --scope project ``` -明示的なファイルが最初に読み込まれ、次にプロジェクトコンベンションファイル、最後にユーザーコンベンションファイルが読み込まれます。両方のパスで見つかったファイルは一度だけ読み込まれます。 +明示的なファイルが最初に読み込まれ、次にプロジェクトのコンベンションファイル、その後ユーザーのコンベンションファイルが読み込まれます。両方のパスで見つかったファイルは一度だけ読み込まれます。 -## バリデートしてテストする +## バリデートとテスト -バリデーションはモジュールをプロダクションローダーで実行し、少なくとも1つのポリシーが登録されていることを確認します。 +バリデーションはプロダクションローダーを通じてモジュールを実行し、少なくとも1つのポリシーが登録されていることを確認します。 ```bash failproofai policies --install \ @@ -260,44 +260,44 @@ failproofai policies --install \ failproofai policies ``` -バリデーションはファイルの欠如、構文エラー、未解決のインポート、トップレベルの例外、モジュール読み込みタイムアウトを検出します。ただし、マッチロジックが正しいことは証明しません。 +バリデーションは、ファイルの欠落、構文エラー、未解決のインポート、トップレベルの例外、およびモジュール読み込みタイムアウトを検出します。ただし、マッチロジックが正しいかどうかは検証されません。 少なくとも以下のケースをテストしてください： -- 一致して意図したポリシー理由を生成するアクションを1つ。 -- `allow()` を返す必要のある近いが安全なアクションを1つ。 -- 欠落または不正なツールフィールド。 -- 代替コマンド構文、パス、引用符、大文字小文字、空白。 -- 利用不可能なサブプロセスまたはネットワーク依存関係。 +- マッチして意図したポリシー理由を生成しなければならないアクション。 +- `allow()` を返さなければならない近しいが安全なアクション。 +- ツールフィールドの欠落または不正な形式。 +- 代替コマンド構文、パス、クォート、大文字小文字、および空白。 +- 利用できないサブプロセスまたはネットワーク依存関係。 -**Observe → policy** で結果をカスタムポリシーに帰属させてください。異なる組み込みポリシーが判断を行った場合、ブロックされたテストだけでは不十分です。 +**観察 → ポリシー** でカスタムポリシーに結果を帰属させてください。異なる組み込みポリシーが決定を行った場合、ブロックされたテストは十分ではありません。 -## ランタイムの動作 +## ランタイム動作 -- 組み込みポリシーはカスタムポリシーより前に評価されます。 -- 最初の `deny` がそれ以降のポリシー評価を停止します。 -- イベントを拒否するポリシーがない場合、複数の `instruct` 結果を組み合わせることができます。 +- 組み込みポリシーはカスタムポリシーより先に評価されます。 +- 最初の `deny` でそれ以降のポリシー評価が停止します。 +- どのポリシーもイベントを拒否しない場合、複数の `instruct` 結果を組み合わせることができます。 - ポリシー関数の実行期限は10秒です。 -- スローされた例外またはタイムアウトはログに記録され、`allow()` として扱われます。 -- 読み込みに失敗したコンベンションファイルはスキップされ、他のカスタムファイルと組み込みポリシーは継続します。 +- 例外またはタイムアウトはログに記録され、`allow()` として扱われます。 +- 読み込みに失敗したコンベンションファイルはスキップされ、他のカスタムファイルと組み込みポリシーは続行されます。 - トップレベルのモジュール読み込みにも10秒の期限があります。 -- クラウドオブザーブモードはポリシーを実行しますが、非allowの判断を強制せずに記録します。 +- クラウド観察モードはポリシーを実行しますが、非許可の決定を施行せずに記録します。 -ポリシーモジュールは決定論的で高速に保ってください。トップレベルのネットワーク呼び出しやサーバーの起動を避けてください。`fn` 内の処理に上限を設け、依存関係の失敗をキャッチし、その失敗が操作を許可すべきか拒否すべきかを意図的に選択してください。 +ポリシーモジュールは決定論的かつ高速に保ちます。トップレベルのネットワーク呼び出しやサーバー起動は避けてください。`fn` 内の処理を制限し、依存関係の失敗をキャッチし、その失敗がアクションを許可するか拒否するかを意図的に選択してください。 ## APIエクスポート | エクスポート | 目的 | | --- | --- | -| `customPolicies.add(policy)` | モジュール読み込み時にカスタムポリシーを登録する。 | -| `allow(reason?)` | 操作を許可する。 | -| `instruct(reason)` | 操作を許可し、サポートされている場合はガイダンスを提供する。 | -| `deny(reason)` | サポートされている場合、操作をブロックする。 | -| `getCustomHooks()` | モジュールレジストリに現在登録されているポリシーを返す。 | -| `clearCustomHooks()` | そのレジストリをクリアする。主にテストとローダー用。 | +| `customPolicies.add(policy)` | モジュール読み込み時にカスタムポリシーを登録します。 | +| `allow(reason?)` | 操作を許可します。 | +| `instruct(reason)` | 操作を許可し、サポートされている場合はガイダンスを提供します。 | +| `deny(reason)` | サポートされている場所で操作をブロックします。 | +| `getCustomHooks()` | モジュールレジストリに現在登録されているポリシーを返します。 | +| `clearCustomHooks()` | そのレジストリをクリアします。主にテストとローダー向けです。 | -TypeScript は `PolicyContext`、`PolicyResult`、`CustomHook`、`PolicyDecision`、`PolicyFunction` をエクスポートします。 +TypeScriptは `PolicyContext`、`PolicyResult`、`CustomHook`、`PolicyDecision`、および `PolicyFunction` をエクスポートします。 - バージョンを公開し、observeモードでデプロイし、判断内容を確認して、適用に移行します。 + バージョンを公開し、観察モードでデプロイして決定を確認し、施行に移行します。 \ No newline at end of file diff --git a/docs/ja/sessions/evaluations.mdx b/docs/ja/sessions/evaluations.mdx index 51633673..198efdb8 100644 --- a/docs/ja/sessions/evaluations.mdx +++ b/docs/ja/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "オンライン評価" -description: "ライブセッションおよび完了済みセッションを品質・コンプライアンス・コスト・レイテンシの観点でスコアリングします。" +title: "評価結果を読む" +description: "時系列で評価スコアをグラフ化し、エージェントや環境を比較し、セッションのスコアが低い理由を確認し、アシスタントに質問する。" icon: "gauge" --- -オンライン評価は、エージェントセッションに一貫した判断を適用します。監査時にのみ調査するのではなく、継続的に計測すべき指標に活用してください。 +ホスト型または独自のワーカーからの評価結果は、すべて同じ場所に集まります。 -## 評価品質のレビュー +## スコアを時系列で比較する - 1. **Observe → Evaluations** に移動します。 - 2. シリーズを追加し、エージェント・環境・評価スコア・統計値・カーブを選択します。 - 3. シリーズを追加して、環境・エージェント・スコアキーを比較します。 - 4. 結果を選択して対応するセッションを開くか、フィルタリングされたビューを共有します。レイテンシ・トークン数・コスト・その他の数値には **Observe → Metrics** を使用してください。 + **Observe → evaluations** に移動します。 - ![平均評価スコアと時系列トレンドを表示した品質ダッシュボード。](/images/dashboard/dashboard-quality.png) + - **Recent runs** には、各評価が届いた順に一覧表示されます。ホスト型（**managed**）か独自（**customer**）の評価器からのものか、エージェントとセッション、評価とそのバージョン、ステータス、スコアまたはメトリクスが確認できます。 + - **Score over time** は、指定した内容をグラフにプロットします。**add series** を選択し、エージェント、環境、評価、統計値（avg、min、max、p50、p75、p90、p95、p99、stddev、mode）を選択します。各シリーズは1本の線になり、独自の **curve** を割り当てると別のチャートに描画されます。 - ドリルダウンからセッションを開くと、スコアごとの推論内容を確認できます。 + ![評価ページ: customer タグが付いた recent runs、0.5 と 0.8 に参照線があるスコア時系列チャート、すべてのエージェントと環境にわたって finished_clean を平均化した1つのシリーズ。](/images/dashboard/evaluations-chart.png) - ![完全なトレースとともに評価スコアと推論を表示したセッション詳細ビュー。](/images/dashboard/session-detail.png) + すべてのシリーズに共通の時間範囲とビンサイズが適用されます。細かいビンはインシデントを見つけるのに適しており、粗いビンはトレンドを示しますが、探しているスパイクを隠してしまうことがあります。何もスコアが付かなかったバケットは、ゼロではなくラインのギャップとして表示され、参照線は 0.5 と 0.8 の位置にあります。 + + ビューのすべての状態は URL に含まれています。**share** でコピーでき、開いた人は構築した比較をそのまま確認できます。 ```bash @@ -28,25 +28,29 @@ icon: "gauge" fp evals --score helpfulness:0.8.. --since 7d ``` - 自動化のためにグローバルオプション `--json` を `evals` の前に付けてください。例：`fp --json evals --aggregate --env production` + 自動化のためにグローバルオプション `--json` を `evals` の前に追加します。例: `fp --json evals --aggregate --env production`。 -エバリュエーターは、セッション識別子・環境・タイムスタンプ・順序付きイベントを受け取ります。オプションの推論内容とサマリーを含む数値スコアキーを返すことができます。長時間実行されるエバリュエーターは保留中のジョブを返し、後でポーリングすることも可能です。 +同じ評価に対して **avg** と **p90** をプロットすることで、良好な平均値が悪いテールを隠していないか確認できます。また、2つのエージェントや本番・ステージング環境に対して同じ評価をプロットし、1つの軸で比較することもできます。単位を持つコスト、レイテンシ、トークン数は **Observe → metrics** でチャート表示され、単位ごとに1つのチャートになります。 + +## セッションのスコアが低い理由を確認する + +**Observe → sessions** からセッションを開きます。グリッドには各セッションのスコアが表示され、スコア範囲でフィルタリングできます。セッションの右サイドレールには評価サマリーが表示され、その下に各スコアのバーと評価器の根拠が表示されます。 + +![完全なトレースの横に評価スコアと根拠が表示されたセッション詳細ビュー。](/images/dashboard/session-detail.png) + +## アシスタントに質問する + +評価データについて自然な言葉で質問できます。「最近の評価について教えて」や、どのエージェントのスコアが下がっているかなどを尋ねることができます。[アシスタント](/ja/sessions/assistant)は結果を読み取って分析し、フォローアップできる表形式で回答します。有益な質問は[クエリ](/ja/sessions/queries)や[ダッシュボード](/ja/sessions/dashboards)として保存することもできます。 -## 評価に適したターゲット +![アシスタントと並んだ評価ページ。アシスタントが「最近の評価について教えて」という質問に、合計数、ステータス、スコアのサマリーで回答している。](/images/dashboard/evaluations-assistant.png) -- タスクの完了度または正確性 -- 根拠の有無とハルシネーションのリスク -- ツール選択とツールの効率性 -- ポリシーまたはプロセスへの準拠 -- コストおよびレイテンシの予算 -- 必要な人間へのエスカレーション +## 監視とアクション -## スコアから対応へ +- **Analyze → dashboards** の **Dashboards** では、組織全体でエージェントおよび環境ごとに注目しているスコアのトレンドを確認できます。 -スコアをダッシュボードに表示してトレンドを追跡します。閾値や複合条件に対してアラートを作成します。スコアが集団全体で低下した場合は監査を実施して原因を調査し、原因が再現可能なアクションである場合はポリシーを展開します。 + ![平均評価スコアと時系列のトレンドを示す品質ダッシュボード。](/images/dashboard/dashboard-quality.png) - - Python エバリュエーター SDK を使用して、同期または非同期の評価を実装します。 - \ No newline at end of file +- **Alerts** は、スコアがしきい値を超えたときに通知します。[アラート](/ja/audits/alerts)を参照してください。 +- 多くのセッションでスコアが低下している場合は、[監査を実行](/ja/audits/run)して原因を調査します。原因が繰り返し可能なアクションであれば、[ポリシーを記述](/ja/policies/editor)します。 \ No newline at end of file diff --git a/docs/ja/start/integrations/custom-agents.mdx b/docs/ja/start/integrations/custom-agents.mdx index 9bbfe90b..38782e56 100644 --- a/docs/ja/start/integrations/custom-agents.mdx +++ b/docs/ja/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "カスタムエージェント" sidebarTitle: "カスタムエージェント" -description: "自作のエージェントや、アダプターのないフレームワークをインストゥルメントします。" +description: "自作のエージェント、またはアダプターのないフレームワークにインストルメンテーションを追加する。" icon: "code" --- -自作のエージェント、またはFailproof AIがアダプターを提供していないフレームワークを対象としています。インストゥルメントするものは何もありません。イベントを直接発行するだけです。 +自作のエージェント、またはFailproof AIがアダプターを提供していないフレームワーク向けの説明です。インストルメンテーションの設定は不要です。イベントを自分で送出するだけです。 -これは4つのフレームワークアダプターが内部で呼び出しているAPIと同じです。アダプターはその上に構築された変換テーブルにすぎません。 +これは、4つのフレームワークアダプターが内部で呼び出しているのと同じAPIです。それらのアダプターは、このAPIの変換テーブルにすぎません。 ## インストール @@ -15,42 +15,42 @@ icon: "code" pip install failproofai-sdk ``` -追加パッケージもなく、依存関係もありません。 +追加パッケージも依存関係もありません。 -## インストゥルメント +## インストルメンテーション ```python import failproofai_sdk failproofai_sdk.configure(environment="production") -with failproofai_sdk.session(): # one run - with failproofai_sdk.agent("planner"): # one unit of work +with failproofai_sdk.session(): # 1回の実行 + with failproofai_sdk.agent("planner"): # 1つの作業単位 with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # one tool call + t.output = search(q) # 1回のツール呼び出し ``` -上から下に読めば、そのまま意味がわかります： +上から読んでいくと、その意味がそのまま伝わります： -| スコープ | 意味 | +| ラップする対象 | 意味 | | --- | --- | | `session()` | これらのイベントは同じ実行に属する | -| `agent()` | 何かが作業を行っている — リストで認識できる名前を付ける | -| `tool_call()` | これは1つのツールで、返した結果がこれ | +| `agent()` | 何かが作業をしている — リストで認識できる名前を付ける | +| `tool_call()` | これは1つのツールであり、その返り値がここにある | -各スコープが実際に発行するもの： +各スコープが実際に送出するイベント： -| スコープ | 発行するイベント | 用途 | +| スコープ | 送出するイベント | 目的 | | --- | --- | --- | | `session()` | なし | セッションIDをバインドし、1回の実行をグループ化する | -| `agent()` | `agent_start`、`agent_end` | 作業単位を囲む | +| `agent()` | `agent_start`、`agent_end` | 作業単位の前後を囲む | | `tool_call()` | `tool_use`、`tool_result` | 1つのツールを囲み、計測する | -内部では `session_id` と `agent_id` を省略できます。スコープはコンテキスト変数にIDをバインドし、すべてのイベント呼び出しがそれを参照するため、関数間でIDを引き回す必要はありません。 +スコープ内のコードは `session_id` や `agent_id` を省略できます。スコープはコンテキスト変数にIDをバインドし、すべてのイベント呼び出しがそこから読み取るため、関数にIDを引き回す必要はありません。 -3つすべてが `async with` にも `with` にも対応しています。 +3つのスコープはいずれも `async with` と `with` の両方で動作します。 -エージェントをネストするとツリーが構築されます。`parent_id` と深さはスタックから自動的に計算されます： +エージェントをネストするとツリーが構築されます。`parent_id` と深さはスタックから自動計算されます： ```python with failproofai_sdk.session(): @@ -59,35 +59,35 @@ with failproofai_sdk.session(): ... ``` -## スコープのクローズ方法 +## スコープの終了方法 -`agent()` は例外を自動的に処理します： +`agent()` は例外を自動で処理します： -| 状況 | イベント | 結果 | +| 発生したこと | イベント | 結果 | | --- | --- | --- | | 例外なし | `agent_end` | `success` | -| `Exception` | `error`、その後 `agent_end` | `failed` | -| `KeyboardInterrupt`、`SystemExit` | `error`、その後 `agent_end` | `failed` | +| `Exception` | `error`、次に `agent_end` | `failed` | +| `KeyboardInterrupt`、`SystemExit` | `error`、次に `agent_end` | `failed` | | `CancelledError`、`GeneratorExit` | `agent_end` のみ | `cancelled` | -エラーは `agent_end` の前に発行されます。ダッシュボードが `agent_end` でスパンを閉じるため、それ以降のものは何にも帰属されないからです。キャンセルは失敗ではないため、キャンセルされた実行はエラー画面を汚染しません。例外は必ず再スローされます。スコープが例外を飲み込むことはありません。 +エラーは `agent_end` の前に送出されます。これはダッシュボードが `agent_end` でスパンを閉じるため、それ以降に発生したイベントはどのスパンにも帰属しなくなるためです。キャンセルは失敗ではないため、キャンセルされた実行はエラーサーフェスを汚染しません。例外は常に再送出されます。スコープが例外を握りつぶすことはありません。 ## イベントメソッド -6つのファミリーに分かれた15のメソッドです。ほとんどはペアで提供されます。開始側を発行し、次に終了側を発行すると、SDKがその間のスパンを計測します。 +6つのファミリーに分類された15のメソッドがあります。ほとんどはペアで提供されます — オープナーを送出し、次にクローザーを送出すると、SDKがその間のスパンを計測します。 -| ファミリー | 開始 | 終了 | 単独 | +| ファミリー | 開く | 閉じる | 単独 | | --- | --- | --- | --- | | **エージェント** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | | **モデル** | `model_request` | `model_response` | — | | **ツール** | `tool_use` | `tool_result` | — | | **フック** | `hook_triggered` | `hook_completed` | — | -| **ヒューマン** | `human_wait` | `human_input` | `human_pause`、`human_interrupt` | +| **人間** | `human_wait` | `human_input` | `human_pause`、`human_interrupt` | | **失敗** | — | — | `error` | - 制御フローがネストできる場合は、`agent()` や `tool_call()` などのスコープを優先してください。本体が例外を発生させても、クローズイベントが保証されます。ヘルパー内のモデル呼び出しなど、制御フローがネストしない場合は、これらのメソッドを直接使用してください。 + 可能な限りスコープ — `agent()` と `tool_call()` — を優先してください。本体が例外を送出した場合でも、クローズイベントの送出を保証します。制御フローがネストされない場合（ヘルパー内のモデル呼び出しなど）は、これらのメソッドを直接使用してください。 @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **2つのヒューマンファミリーは方向が逆です。** + **2つの人間ファミリーは方向が逆です。** | メソッド | 意味 | | --- | --- | - | `human_wait` / `human_input` | **エージェントが人に尋ねた** — 承認ゲート、確認の質問 | - | `human_pause` / `human_interrupt` | **人がエージェントに作用した** — 停止ボタン、オペレーターによる一時停止 | + | `human_wait` / `human_input` | **エージェントが人間に問いかけた** — 承認ゲート、確認のための質問 | + | `human_pause` / `human_interrupt` | **人間がエージェントに働きかけた** — 停止ボタン、オペレーターによる一時停止 | - フレームワークは後者のペアをシグナルしないため、常に自分で発行する必要があります。 + どのフレームワークも後者のペアを通知しないため、常に自分で送出する必要があります。 - **モデル呼び出しが並行して実行される場合は `request_id` を渡してください。** 指定しない場合、リクエストとレスポンスはエージェントごとの到着順にペアリングされ、並行呼び出しでは各レスポンスが誤ったリクエストに関連付けられます。 + **モデル呼び出しを並行実行する場合は `request_id` を渡してください。** 指定しない場合、リクエストとレスポンスはエージェントごとの受信順にペアリングされます。並行呼び出しでは順序が保証されないため、各レスポンスが誤ったリクエストに紐付く可能性があります。 -## 例 +## 使用例 -エージェントフレームワークを使わず、OpenAI APIに対するツール呼び出しループの例： +エージェントフレームワークなしで、OpenAI APIに対してツール呼び出しループを実行する例： ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """One model call, bracketed by the pair.""" + """1回のモデル呼び出し。ペアで囲む。""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # bounded; an unbounded agent loop is its own bug + for _ in range(4): # 上限あり。無制限のエージェントループはそれ自体がバグ message = turn(messages) if not message.tool_calls: break @@ -204,34 +204,34 @@ with failproofai_sdk.session(): }) ``` -これにより、アダプターが生成するものと同じ6種類のイベントタイプが生成されます。ツール定義を含む完全な実行可能バージョンは、SDKリポジトリの `docs/manual/examples/` に収録されています。 +これにより、アダプターが生成するのと同じ6種類のイベントタイプが生成されます。ツール定義を含む完全な実行可能バージョンは、SDKリポジトリの `docs/manual/examples/` に含まれています。 ## スレッドと非同期 -コンテキスト変数はasyncioタスクに自動的に伝播します。新しいスレッドには伝播しません。スレッドは空のコンテキストで開始するためです。 +コンテキスト変数はasyncioタスクに自動的に伝播します。新しいスレッドには伝播しません。スレッドは空のコンテキストで開始されるためです。 ```python -# asyncio: nothing to do +# asyncio: 特別な操作不要 async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads: wrap the callable +# スレッド: callableをラップする pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -`propagate()` なしでは、ワーカーのイベントがセッションなしで着信する代わりに、修正方法を示す `TypeError` が発生します。これは意図的な設計です。セッションのないイベントはインジェスト時にスキップされ `200` が返されますが、それはIDレイヤーが防ごうとしているサイレントな失敗だからです。 +`propagate()` なしでは、ワーカーのイベントがセッションなしで着信する代わりに、修正方法を示す `TypeError` が発生します。これは意図的な設計です。セッションのないイベントはインジェスト側でスキップされつつ `200` が返されるため、無音の失敗となります。それを防ぐためにIDレイヤーが存在します。 -## アダプターのないフレームワークをインストゥルメントする +## アダプターのないフレームワークへのインストルメンテーション -どのエージェントフレームワークにも同じ3つのシームがあります。それらをマッピングすれば完全なトレースが得られます。出荷済みの4つのアダプターもこれ以上のことはしていません。 +どのエージェントフレームワークにも同じ3つの接合点があります。それらをマッピングすれば、完全なトレースが得られます — 4つの既存アダプターもこれ以上のことはしていません。 -| シーム | 書くもの | 記録されるもの | +| 接合点 | 書くコード | 記録されるイベント | | --- | --- | --- | | 実行 | `session()` + `agent()` | `agent_start`、`agent_end` | | 各ツール | `tool_call()` | `tool_use`、`tool_result` | -| 各モデル呼び出し | `model_*` ペア | `model_request`、`model_response` | +| 各モデル呼び出し | `model_*` のペア | `model_request`、`model_response` | @@ -242,7 +242,7 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` - フレームワークがツールラッパーまたはミドルウェアと呼ぶものの中で。 + フレームワークのツールラッパーまたはミドルウェアに相当する箇所に追加します。 ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -264,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **確認する価値のあるノード、ステップ、ミドルウェアの境界がありますか？** ネストされた `agent()` ではなく、フックペア（`hook_triggered` / `hook_completed`）で囲んでください。`agent_id` は低カーディナリティのファセットで、ノードごとに1エントリあるとリストが溢れます。フックスパンは同じように表示され、ノードごとのレイテンシが確認できます。 + **ノード、ステップ、ミドルウェア境界を可視化したい場合は？** ネストされた `agent()` ではなく、フックペア — `hook_triggered` / `hook_completed` — でラップしてください。`agent_id` は低カーディナリティのファセットであり、ノードごとに1エントリ追加するとすぐに埋め尽くされます。フックスパンは同様にレンダリングされ、ノードごとのレイテンシを確認できます。 - **手動と自動は組み合わせられます。** 手書きのスコープ内で実行するアダプターはそのセッションに参加し、そのエージェントの配下に入るため、2つのツリーではなく1つのツリーが得られます。サポート済みのフレームワークと並行して自分でインストゥルメントするときに便利です。 + **手動計装と自動計装は組み合わせ可能です。** 手書きスコープ内で実行されるアダプターは、そのセッションに参加し、そのエージェントを親として設定します。2つのツリーではなく1つのツリーが得られるため、対応フレームワークと独自フレームワークを同時に計装する際に便利です。 - - 2つの理由があり、上記の3つのシームがその両方に対する答えです： + + 2つの理由があります。上記の3つの接合点が、その両方に対する答えです： - `autogen-core` は2025年9月以降メンテナンスされていません。 - - AG2は他のフレームワークのフックに相当するプロセス全体の登録ポイントを公開していないため、インストゥルメントするにはすべての構築サイトでエージェントをラップする必要があります。 + - AG2には他のフレームワークのフックに相当するプロセス全体の登録ポイントがないため、計装するにはすべての構築箇所でエージェントをラップする必要があります。 - シームを手動でマッピングすることで、出荷済みアダプターと同じイベントを同じ精度で記録できます。 + 接合点を手動でマッピングすることで、既存アダプターと同じイベントが同じ精度で記録されます。 -## より深く理解する +## 詳細 -記録の実際の仕組みです。始めるためには何も必要ありません。 +記録の実際の仕組みについて。始めるために必要な知識ではありません。 - + -すべての記録は同じ形をしています。スパンが開き、作業がその中にネストされ、各開始イベントに対応する終了イベントがあります。 +すべての記録は同じ形をしています。スパンが開き、その中に作業がネストされ、各オープンイベントに対応するクローズイベントがあります。 ```mermaid flowchart LR @@ -300,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -**ペア**が基本単位です。各終了イベントには、対応する開始イベントからSDKが計測した期間が含まれます。 +**ペア**が基本単位です。各クローズイベントには、SDKがオープンイベントからの経過時間として計測したdurationが含まれます。 -以下はフレームワークごとの実際の1回の実行です。SDKに付属するサンプルからキャプチャし、モデル名を正規化しています。1回の呼び出しでどれだけ多くの情報が返ってくるかに注目してください。 +以下は各フレームワークの実際の1回の実行 — SDKに同梱されているサンプルから取得、モデル名は正規化済み。1回の呼び出しでどれだけ多くの情報が返されるかに注目してください。 @@ -323,7 +323,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - ノードがフックペアになるため、エージェントリストを圧迫することなくノードごとのレイテンシが確認できます。 + ノードがフックペアになるため、エージェントリストを埋め尽くすことなくノードごとのレイテンシを確認できます。 @@ -356,11 +356,11 @@ flowchart LR 13 +3.355s tool_use city_population 14 +3.355s tool_result city_population · ok 16 +3.356s hook_triggered aggregate_tool_results - ... second iteration + ... 2回目のイテレーション 26 +7.038s agent_end Agent · success ``` - モデル呼び出しだけでなく、エージェントループ自体が可視化されます。 + エージェントループ自体が可視化され、モデル呼び出しだけでなくループ全体が見えます。 @@ -375,7 +375,7 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - フックペアなし：Pydantic AIにはブラケットするノードやステップの境界がありません。 + フックペアなし: Pydantic AIにはブラケットで囲むべきノードやステップ境界がありません。 @@ -388,36 +388,36 @@ flowchart LR 6 +0.000s agent_end main · success ``` - これらは自分で発行します。同じイベントタイプ、同じ精度 — 呼び出しサイトのコストがかかります。 + これらを自分で送出します。同じイベントタイプ、同じ精度 — 呼び出し箇所を書くコストがかかります。 - + -**セッション終了イベントはありません。** セッションはクローズするものではなく、`session_id` を共有するイベントのグループです。 +**セッション終了イベントは存在しません。** セッションは閉じるものではなく、同じ `session_id` を共有するイベントのグループです。 -ステータスはトレースの形から導出されます： +ステータスはトレースの形状から導出されます： | ステータス | 条件 | | --- | --- | | `ongoing` | 少なくとも1つのスパンがまだ開いている | | `paused` | `agent_pause` に対応する `agent_resume` がない | -| `error` | 開いているものがなく、少なくとも1つのイベントが失敗した | -| `done` | 開いているものがなく、失敗もない | +| `error` | 開いているスパンがなく、少なくとも1つのイベントが失敗した | +| `done` | 開いているスパンがなく、失敗もない | -つまり、すべてのペアが閉じられるとセッションが終了します。アダプターは `agent_end` を自動で発行し、ティアダウン時に残っているものをすべて閉じて不完全とマークします。クラッシュした実行は、永遠にハングするのではなく、可視ギャップのある `done` として落ち着きます。 +つまり、すべてのペアが閉じられるとセッションが終了します。アダプターは `agent_end` を自動送出し、テアダウン時にはまだ開いているものをすべて閉じてincompleteとしてマークします — クラッシュした実行は永遠にハングするのではなく、visible gapを持つ `done` として落ち着きます。 - これがセッションが2回の呼び出しにまたがれる理由です。LangGraphの `interrupt()` が実行を一時停止し、ルートスパンが意図的に開いたままになり、再開する呼び出しがそれを閉じます。両方の呼び出しが1つのセッションです。 + これが、1つのセッションが2回の呼び出しにまたがれる理由です。LangGraphの `interrupt()` は実行を一時停止し、ルートスパンを意図的に開いたままにします。再開する呼び出しがそれを閉じます。両方の呼び出しが1つのセッションです。 - + -`session_id` と `agent_id` はすべてのイベントメソッドでオプションです。省略した場合、囲むスコープから解決されます： +`session_id` と `agent_id` はすべてのイベントメソッドでオプションです。省略した場合、囲んでいるスコープから解決されます： ```python with failproofai_sdk.session(): @@ -425,55 +425,55 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -明示的に渡すことも可能で、その場合は優先されます。何もバインドされておらず何も渡されていない場合、セッションなしのイベントを発行する代わりに（インジェストはそれをスキップして `200` を返します）、修正方法を示す `TypeError` が発生します。 +明示的に渡すことも可能で、その場合は優先されます。何もバインドされておらず何も渡されない場合、セッションなしでイベントを送出する代わりに、修正方法を示す `TypeError` が発生します（インジェストはセッションなしのイベントをスキップしつつ `200` を返します）。 -スコープはコンテキスト変数にIDをバインドします。それらはasyncioタスクには自動的に伝播しますが、新しいスレッドには伝播しません。ワーカーを `failproofai_sdk.propagate()` でラップしてください。 +スコープはコンテキスト変数にIDをバインドします。asyncioタスクには自動的に伝播しますが、新しいスレッドには伝播しません — ワーカーを `failproofai_sdk.propagate()` でラップしてください。 -#### 誰がどのIDを生成するか +#### どのIDを誰が発行するか -| ID | 生成者 | 備考 | +| ID | 発行者 | 備考 | | --- | --- | --- | -| `session_id` | あなた、またはSDK | `session("chat-42")` はそのまま使用される。省略した場合、SDKが `uuid4().hex` を生成する | -| `agent_id` | あなた、またはフレームワーク | `agent("analyst")`、CrewAIの `role`、`FunctionAgent.name` から。UUID形式の値は拒否されて置き換えられる | -| `tool_call_id`、`hook_id`、`request_id` | あなた、またはフレームワーク | アダプターはフレームワーク自身の実行IDを再利用するため、スレッドをまたいでもペアが維持される | -| **イベントID** | **クラウド、インジェスト時** | SDKは発行しない | -| **`dedup_key`** | **クラウド、インジェスト時** | org、セッション、タイムスタンプ、タイプ、ペイロードのハッシュ。これが本当のID — リトライされたバッチが重複する代わりに集約される | +| `session_id` | ユーザー、またはSDK | `session("chat-42")` はそのまま使用される。省略時、SDKは `uuid4().hex` を生成する | +| `agent_id` | ユーザー、またはフレームワーク | `agent("analyst")`、CrewAIの `role`、`FunctionAgent.name` から。UUIDのような値は拒否されて置換される | +| `tool_call_id`、`hook_id`、`request_id` | ユーザー、またはフレームワーク | アダプターはフレームワーク独自の実行IDを再利用する。ペアがスレッドホップを越えて一致するのはそのためである | +| **イベントID** | **Cloud（インジェスト時）** | SDKは送出しない | +| **`dedup_key`** | **Cloud（インジェスト時）** | org、session、timestamp、type、payloadのハッシュ。これが実際のID — 再試行されたバッチが重複する代わりに折りたたまれる | #### アダプターが `session_id` を解決する方法 -最初にマッチしたものが使われます： +最初のマッチが優先されます： 1. 明示的な `session_id` オプション 2. 呼び出しごとのメタデータ -3. 囲む `session()` スコープ +3. 囲んでいる `session()` スコープ 4. フレームワークのメタデータ -5. フレームワーク自身の実行ID +5. フレームワーク独自の実行ID -これらのいずれかが存在する間は生成されません。合成されたIDは1つの実行を複数のセッションに分割してしまいます。 +これらのいずれかが存在する間は、IDが新規生成されることはありません — 合成されたIDは1回の実行を複数のセッションに分割してしまうためです。 #### `agent_id` は低カーディナリティに保つ -これはすべてのダッシュボード画面の主要ファセットであり、`LowCardinality(String)` カラムです。実行ごとの値はカラムを劣化させ、フィルタードロップダウンを実行ごとの1エントリで埋めてしまいます。 +すべてのダッシュボードサーフェスの主要ファセットであり、`LowCardinality(String)` カラムです。実行ごとの値を使用するとカラムが劣化し、フィルターのドロップダウンが実行1件につき1エントリで埋まります。 アダプターはそのカラムを守ります： | フレームワークが渡す値 | 記録される値 | 理由 | | --- | --- | --- | -| `3f9a1c2b-…`（UUID） | `main` | 読める部分がない | -| 長い生の16進数文字列 | `main` | 同上 | -| `agent-3f9a1c2b-…` | `agent` | 実行IDが除去され、読める部分が保持される | -| `agent-v2` | `agent-v2` | 短いセグメントはそのまま | +| `3f9a1c2b-…`（UUID） | `main` | 読める情報がない | +| 長い16進数文字列 | `main` | 同上 | +| `agent-3f9a1c2b-…` | `agent` | 実行IDを削除し、読める部分を保持 | +| `agent-v2` | `agent-v2` | 短いセグメントはそのまま残す | | `step-3` | `step-3` | 同上 | -実際のIDは `fw_agent_id` / `fw_run_id` に保持され、ファセットにならずにクエリ可能なままです。 +実際のIDは `fw_agent_id` / `fw_run_id` に保持されるため、ファセットにならずともクエリ可能です。 - **このガードは*フレームワーク*が選んだラベルにのみ適用されます。** `event.*` や `failproofai_sdk.agent(...)` に自分で渡す `agent_id` はそのまま記録されます。明示的な引数をサイレントに書き換えることは、それが防ぐカーディナリティ問題よりも悪いためです。自分のスパンには適切な名前を付けてください。 + **このガードは*フレームワーク*が選んだラベルにのみ適用されます。** `event.*` や `failproofai_sdk.agent(...)` に自分で渡す `agent_id` は、渡したとおりに記録されます。明示的な引数を暗黙的に書き換えることは、防ごうとするカーディナリティの問題よりも悪いため、スパン名は適切に命名してください。 - + | グループ | イベント | | --- | --- | @@ -481,73 +481,73 @@ with failproofai_sdk.session(): | モデル | `model_request`、`model_response` | | ツール | `tool_use`、`tool_result` | | フック | `hook_triggered`、`hook_completed` | -| ヒューマン | `human_wait`、`human_input`、`human_pause`、`human_interrupt` | +| 人間 | `human_wait`、`human_input`、`human_pause`、`human_interrupt` | | 失敗 | `error` | -上記の実行から計測した、フレームワーク別の記録対象： +上記の実行から計測した、フレームワークごとの記録内容： | イベント | LangGraph | CrewAI | LlamaIndex | Pydantic AI | カスタム | | --- | :--: | :--: | :--: | :--: | :--: | -| エージェント開始・終了 | Yes | Yes | Yes | Yes | あなた | -| モデルリクエスト・レスポンス | Yes | Yes | Yes | Yes | あなた | -| ツール使用・結果 | Yes | Yes | Yes | Yes | あなた | -| フックトリガー・完了 | Node | Task | Step | — | あなた | -| エラー | Yes | Yes | Yes | Yes | 自動 | -| ヒューマン待機・入力 | Yes | Yes | Yes | — | あなた | -| エージェント一時停止・再開 | Yes | Yes | Yes | — | あなた | +| エージェント開始・終了 | あり | あり | あり | あり | 自前 | +| モデルリクエスト・レスポンス | あり | あり | あり | あり | 自前 | +| ツール使用・結果 | あり | あり | あり | あり | 自前 | +| フックトリガー・完了 | ノード | タスク | ステップ | — | 自前 | +| エラー | あり | あり | あり | あり | 自動 | +| 人間の待機・入力 | あり | あり | あり | — | 自前 | +| エージェント一時停止・再開 | あり | あり | あり | — | 自前 | -ダッシュはフレームワークにそのような概念がないことを意味します。`human_pause` と `human_interrupt` は*人*がエージェントに作用することを表しており、どのフレームワークもシグナルしません。自分で発行してください。 +ダッシュはそのフレームワークにその概念がないことを意味します。`human_pause` と `human_interrupt` は*人間*がエージェントに働きかけることを表しており、どのフレームワークも通知しません — これらは自分で送出してください。 - + -イベントは単独では届きません。1つが開き、1つが閉じ、終了イベントにはSDKが開始イベントから計測した期間が含まれます。 +イベントは単独では届きません。1つがスパンを開き、1つが閉じます。クローズイベントには、SDKがオープンイベントからの経過時間として計測したdurationが含まれます。 -| 開始 | 終了 | 終了イベントが持つもの | +| 開く | 閉じる | クローズイベントが持つ値 | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`、`summary` | -| `model_request` | `model_response` | トークン、`stop_reason`、レイテンシ | -| `tool_use` | `tool_result` | `output` または `error`、期間 | -| `hook_triggered` | `hook_completed` | `outcome`、期間 | +| `model_request` | `model_response` | トークン数、`stop_reason`、レイテンシ | +| `tool_use` | `tool_result` | `output` または `error`、duration | +| `hook_triggered` | `hook_completed` | `outcome`、duration | | `agent_pause` | `agent_resume` | 一時停止の継続時間 | -| `human_wait` | `human_input` | 回答、および人が要した時間 | +| `human_wait` | `human_input` | 回答、および人間が要した時間 | - 対応する終了イベントのない開始イベントは、永遠に終わらないスパンになります。セッションは永遠に実行中として表示され、アクティブな期間が増え続けます。これが手動インストゥルメント時に注意すべき失敗モードです。 + クローズイベントのないオープンイベントは、永遠に終わらないスパンです。セッションはずっと実行中としてレンダリングされ、アクティブdurationが増え続けます。これは手動で計装する際に注意すべき失敗パターンです。 #### 相関ルール -- マッチする完了イベントには同じ `tool_call_id`、`hook_id`、`pause_id`、または `input_id` を再利用してください。 +- マッチするクロージングイベントには同じ `tool_call_id`、`hook_id`、`pause_id`、または `input_id` を再利用してください。 - SDKは `tool_result`、`hook_completed`、`agent_resume`、`human_input` の `duration_ms` を計算します。これらのメソッドに渡すと `ValueError` が発生します。 -- `duration_ms` は `model_response` では**受け付けられます**。本当のプロバイダーレイテンシを知っているのは呼び出し元だけだからです。整数でなければなりません。浮動小数点数は呼び出しサイトで `ValueError` が発生します。サーバーはカラムを符号なし32ビット整数として読み取るため、それ以外はNULLとして格納されます。 -- 相関キーはKindとセッションでスコープされているため、ツール呼び出しとフックは安全にIDを共有でき、2つの並行セッションは同じIDを衝突なしに再利用できます。エージェントではスコープされません。あるエージェントで開かれ別のエージェントで閉じられたペアも相関します。これはマルチエージェントフレームワークでの通常のケースです。 -- `request_id` は `model_request` と `model_response` をペアにします。これなしでは、モデルイベントはエージェントごとの順序でペアリングされるため、並行呼び出しは誤ってペアリングされます。 -- プロセスをまたぐペアは下流で相関しますが、SDKはプロセス内の期間を計算できません。 -- ペンディングマップは最大10,000件の開始エントリを保持し、満杯になると最古のエントリを削除します。 +- `duration_ms` は `model_response` では**受け付けられます**。これは実際のプロバイダーレイテンシを知っているのが呼び出し側だけだからです。整数でなければなりません — floatを渡すと呼び出し箇所で `ValueError` が発生します（サーバーはそのカラムを符号なし32ビット整数として読み取るため、それ以外はNULLとして保存されます）。 +- 相関キーはkindとsessionでスコープされます。ツール呼び出しとフックは同じIDを安全に共有でき、2つの並行セッションは衝突なく同じIDを再利用できます。agentによるスコープはありません。あるエージェントで開かれ別のエージェントで閉じられたペアも相関します。これはマルチエージェントフレームワークでは通常のケースです。 +- `request_id` は `model_request` と `model_response` をペアリングします。指定しない場合、モデルイベントはエージェントごとの順序でペアリングされるため、並行呼び出しではペアが誤ります。 +- プロセスをまたいで分割されたペアはダウンストリームで相関しますが、SDKはプロセス内のdurationを計算できません。 +- ペンディングマップは最大10,000エントリを保持し、満杯になると最古のエントリを削除します。 - + -`failproofai-sdk` をインストールすると、4つのアダプターすべてを含むすべてのものがインストールされます。エクストラは**フレームワーク**を引き込むものであり、アダプターではありません。 +`failproofai-sdk` をインストールすると、4つのアダプターを含むすべてがインストールされます。extrasが引き込むのはアダプターではなく**フレームワーク**です。 ```python -import failproofai_sdk # loads nothing outside the standard library -failproofai_sdk.instrument() # imports only the adapters you actually need +import failproofai_sdk # 標準ライブラリ以外は何もロードしない +failproofai_sdk.instrument() # 実際に必要なアダプターのみインポートする ``` -`import failproofai_sdk` は契約上ゼロ依存です。ビルドされたwheelを `--no-deps` でインストールするテストと、フレームワークが `sys.modules` に到達しないことを証明するテストによって強制されています。 +`import failproofai_sdk` は契約上ゼロ依存であり、`--no-deps` でビルド済みwheelをインストールするテストと、どのフレームワークも `sys.modules` に到達しないことを証明するテストによって強制されます。 - `failproofai_sdk.crewai` 属性はありません。アダプターはトップレベルパッケージに意図的に公開されていません。属性アクセスの副作用としてフレームワークがインポートされ、ゼロ依存の約束が破られるからです。`instrument()` を使用してください。 + `failproofai_sdk.crewai` という属性は存在しません。アダプターはトップレベルパッケージに意図的に公開されていません。属性アクセスの副作用としてフレームワークがインポートされ、ゼロ依存の約束が破られるためです。`instrument()` を使用してください。 ```python -failproofai_sdk.instrument() # every framework already imported -failproofai_sdk.instrument("crewai") # exactly one, by name -failproofai_sdk.uninstrument("crewai") # put it back +failproofai_sdk.instrument() # インポート済みのすべてのフレームワーク +failproofai_sdk.instrument("crewai") # 名前で1つだけ指定 +failproofai_sdk.uninstrument("crewai") # 元に戻す ``` | 名前 | 別名 | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # put it back | `llama_index` | `llamaindex`、`llama-index` | | `pydantic_ai` | `pydantic-ai`、`pydanticai` | -自動検出はインストール済みパッケージリストではなく `sys.modules` を読み取るため、インストール済みだがインポートしていないフレームワークはインストゥルメントされず、代わりにインポートされることもありません。接続されているものを確認するには： +自動検出はインストール済みパッケージリストではなく `sys.modules` を読み取ります。インストールはしてあるがインポートしていないフレームワークは計装されず、代わりにインポートされることもありません。現在の状態を確認するには： ```python from failproofai_sdk.integrations import active, available @@ -567,16 +567,16 @@ active() # ('langchain',) ``` - **CrewAIのないマシンで `instrument("crewai")` を呼び出しても例外は発生しません。** 警告をログに記録して `()` を返すため、フレームワークが1つ欠けていても他のインストゥルメントをしているプロセスを停止させません。 + **CrewAIがインストールされていないマシンで `instrument("crewai")` を呼び出しても例外は発生しません。** 警告をログに記録して `()` を返すため、1つのフレームワークが欠けていても他を計装するプロセスが停止することはありません。 - 警告には根本的な `ImportError` が含まれており、そのメッセージには正確なインストールコマンドが記載されています。修正方法はログにあり、隠れていません。 + 警告には元の `ImportError` が含まれており、そのメッセージに正確なインストールコマンドが示されています — 修正方法はログに記録されており、隠されていません。 ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - `FAILPROOFAI_SDK_STRICT=1` を設定すると、代わりに例外が発生します。このフラグは**一度だけ読み取られてキャッシュされる**ため、プロセス実行中に設定するのではなく、プロセスが開始する前にエクスポートしてください。 + 代わりに例外を発生させるには `FAILPROOFAI_SDK_STRICT=1` を設定してください。このフラグは**一度だけ読み取られてキャッシュされます**。実行中に設定するのではなく、プロセス起動前にエクスポートしてください。 @@ -586,111 +586,113 @@ active() # ('langchain',) ```python Wrong import failproofai_sdk -failproofai_sdk.instrument() # sys.modules has no langchain yet -> () +failproofai_sdk.instrument() # sys.modulesにlangchainがまだない -> () -import langchain # too late, nothing is wired +import langchain # 遅すぎる。何もワイヤリングされない ``` ```python Right -import langchain # import the framework first +import langchain # 先にフレームワークをインポート import failproofai_sdk -failproofai_sdk.instrument() # finds it -> ('langchain',) +failproofai_sdk.instrument() # 検出される -> ('langchain',) ``` ```python Right, order-proof import failproofai_sdk -# Naming it imports the adapter on request, so this works from anywhere. +# 名前を指定するとアダプターが要求時にインポートされるため、どこからでも動作する failproofai_sdk.instrument("langchain") ``` -これを誤るとプロセスはSDKがインポートされ、アダプターが明らかにインストールされているにもかかわらず、**1つもイベントが発行されない**状態で動作します。まさにそれを示す警告がログに記録されます。実行が何も記録しない場合はまずログを確認してください。 +これを誤ると、SDKがインポートされアダプターが一見インストールされているのに、**イベントが1件も送出されない**状態になります。ログにその旨の警告が記録されます — 実行が何も記録しない場合、まずログを確認してください。 - + ```mermaid flowchart LR - A["Your agent"] --> B["Adapter"] - B --> C["Writer
in-memory queue"] - C -->|"every 0.5s"| D["Spool
JSONL on disk"] - D --> E["Failproof daemon"] + A["エージェント"] --> B["アダプター"] + B --> C["Writer
インメモリキュー"] + C -->|"0.5秒ごと"| D["Spool
ディスク上のJSONL"] + D --> E["Failproofデーモン"] E -->|"HTTPS"| F["Cloud"] ``` | ステージ | 役割 | 実行場所 | | --- | --- | --- | -| アダプター | フレームワークのコールバックを15種類のイベントタイプのいずれかに変換する | あなたのプロセス | -| ライター | キューに入れ、バッチ処理し、JSONLをアトミックに書き込む | あなたのプロセス、バックグラウンドスレッド | -| スプール | 耐久性のあるハンドオフ。プロセスが終了しても生き残る | ローカルディスク | -| デーモン | スプールを監視し、バッチを送信し、送信済みのものを削除する | あなたのマシン | -| インジェスト | 行IDとdedupキーを割り当て、クエリ可能なカラムを昇格させる | クラウド | +| アダプター | フレームワークのコールバックを15種類のイベントタイプに変換 | プロセス内 | +| Writer | キューに追加、バッチ化、JSONLをアトミックに書き込む | プロセス内（バックグラウンドスレッド） | +| Spool | 耐久性のある引き渡し。プロセス終了後も保存される | ローカルディスク | +| デーモン | Spoolを監視し、バッチを送信し、送信済みを削除する | マシン上 | +| インジェスト | 行IDとdedup keyを割り当て、クエリ可能なカラムに昇格させる | Cloud | -スプールがこれを安全にしています。エージェントがネットワークをブロックすることはなく、クラウドが停止してもイベントが失われる代わりにディレクトリが大きくなるだけです。 +Spoolがこれを安全にする理由です。エージェントはネットワークをブロックすることなく動作し、Cloudの障害は消失したイベントではなくディレクトリの増大として現れます。 -各フラッシュは1つのバッチファイルを書き込みます。`.tmp` として書き込み、`fsync`、その後アトミックなリネームを行います： +各フラッシュは1つのバッチファイルを書き込みます。`.tmp` で書き始め、次に `fsync`、そしてアトミックリネームを行います： ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -デーモンは `.jsonl` のみを読み取るため、半分書かれたファイルを読む可能性はありません。ステムにはタイムスタンプ、プロセスID、シーケンス番号が含まれているため、同じミリ秒にフラッシュする2つのプロセスが衝突することはありません。キューの上限は10,000イベントで、それを超えると最古のものをドロップしてログに記録します。 +デーモンは `.jsonl` のみを読み取るため、書き込み途中のファイルを読むことは決してありません。ファイル名にはタイムスタンプ、プロセスID、シーケンス番号が含まれるため、2つのプロセスが同じミリ秒にフラッシュしても衝突しません。キューの上限は10,000イベントで、それを超えると最古のものを削除してログに記録します。 - **`collector.redact` はSDKイベントにもデフォルトで `minimal` が適用されます。** SDKはバッチをディスクに書き込む前にスクラブし、デーモンはアップロード前に同じ決定論的パスを繰り返します。これにより古いSDKからのバッチも保護されます。 + **`collector.redact` はSDKイベントには適用されません。** SDKイベントは `collector.redact` の処理対象外です。 -デーモンは各バッチを読み取り、アップロード前にメモリ内でリダクションを適用します。読み取ったスプールファイルを書き換えることはありません。 +デーモンはバッチを**送信**します。バッチを開いたり書き換えたりしません。 -| イベント | 書き込み元 | 最小リダクションの実行タイミング | +| イベント | 書き込み者 | `collector.redact` による編集 | | --- | --- | --- | -| CLIセッションのトランスクリプト | デーモン | デーモンがバッチを書き込む前 | -| フックアクティビティ | デーモン | デーモンがバッチを書き込む前 | -| **SDKが発行するすべてのもの** | **あなたのプロセス** | **SDKがバッチを書き込む前、およびデーモンのアップロード前** | +| CLIセッションのトランスクリプト | デーモン | あり | +| フックのアクティビティ | デーモン | あり | +| **SDKが送出するすべてのイベント** | **プロセス** | **なし** | -逐語的なペイロードが明示的な要件である場合にのみ `collector.redact` を `off` に設定してください。SDKとデーモンの両方がその設定を尊重します。最小リダクションは一般的なAPIキー、ベアラートークン、JWT、シークレットの代入をキャッチします。任意の機密テキストを識別することはできません。 +編集はデーモンが自身のイベントを*書き込む*場所で実行されます — バッチが*送信される*場所ではありません。そのため、APIキーを含むプロンプトやツール引数は、到着時もそのままの状態です。 + +これは意図的な設計です。これらはご自身の計装コールであり、送受信中に書き換えることは、送出したイベントと受け取るイベントが異なるものになることを意味します。 - **ペイロードはソースで2か所制御できます：** + **ペイロードはソースの2箇所で制御できます：** - - アダプターのコンテンツキャプチャをオフにする。**オプション名は異なり、コンテンツスイッチのないアダプターもあります** — これは単一の汎用スイッチではありません： + - アダプターでコンテンツキャプチャを無効にする。**オプション名はアダプターによって異なり、対応していないアダプターもあります** — 共通の単一スイッチではありません： - LangChain / LangGraph、Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **コンテンツスイッチなし**。読み取るオプションは `session_id` のみで、プロンプトと補完は常に記録されます。 + - CrewAI — **コンテンツスイッチなし**。読み取るオプションは `session_id` のみのため、プロンプトと補完は常に記録されます。 - `instrument()` はアダプターが読み取らないオプションをドロップするため、誤った名前を渡しても例外は発生せず、何も変わりません。 + `instrument()` はアダプターが読み取らないオプションを無視するため、誤った名前を渡しても何も起きず、何も変わりません。 - そもそもシークレットを `input=` に渡さない。 - `collector.redact` は多層防御であり、どちらかの代替ではありません。 + `collector.redact` はどちらの代替手段にもなりません。 - **スプールディレクトリが空なのが正常な状態です。** 配信確認にそれを使わないでください。 + **Spoolディレクトリが空の状態が正常です。** 配信確認のために使用しないでください。 -デーモンは送信から数ミリ秒以内に各バッチを削除するため、`ls` はコレクターと競合し、実際に発行したもののごく一部しか表示されません。これは何も記録していないSDKと区別がつきません。 +デーモンは送信後数ミリ秒以内に各バッチを削除するため、`ls` はコレクターと競合し、実際に送出したイベントのごく一部しか表示されません — 何も記録していないSDKと区別がつきません。 -イベントが実際に届いたことを確認するにはダッシュボードを確認してください。スプールが満たされるのを見るにはまずデーモンを停止してください。 +イベントが実際に届いたかどうかはダッシュボードで確認してください。Spoolが埋まる様子を観察するには、先にデーモンを停止してください。 - + -すべてのコールバックは、再スローすることだけが役割のラッパー内で実行されます。呼び出しは正確に1つの `try` の中にあり、SDKが行うすべてのことはその外で行われます。 +すべてのコールバックは再送出のみを行うラッパー内で実行されます。コードは1つの `try` の中に置かれ、SDKが行うすべての処理はその外側で実行されます。 -| 状況 | 結果 | +| 発生したこと | 結果 | | --- | --- | -| フックが例外を発生させる | トレースバック付きで1回ログに記録される。呼び出しへの影響なし | -| 同じフックが3回例外を発生させる | そのフックはプロセスの残りの間無効化され、エラー行が1つ記録される | -| `FAILPROOFAI_SDK_STRICT=1` が設定されている | 例外が代わりに再スローされる | -| フレームワークのバージョンがテスト済み範囲外 | 1回警告し、インストゥルメントを続行する | -| 単一の機能が欠けている | そのフックのみ無効化され、アダプター全体ではない | +| フックが例外を送出した | トレースバック付きで1回ログに記録される。コードは影響を受けない | +| 同じフックが3回例外を送出した | そのフックはプロセスの残り時間中無効化され、1行のエラーログが記録される | +| `FAILPROOFAI_SDK_STRICT=1` が設定されている | 代わりに例外が再送出される | +| フレームワークのバージョンがテスト済み範囲外 | 1回警告が出されるが、計装は続行される | +| 1つの機能が欠けている | そのフックのみ無効化される。アダプター全体は無効化されない | -デフォルトは本番では正しく、デバッグ中は誤りです。「クラッシュしなかった」ことしか証明できないからです。`FAILPROOFAI_SDK_STRICT=1` を設定して、飲み込まれた失敗を顕在化させてください。 +デフォルトは本番環境では適切ですが、デバッグ時には不適切です。「クラッシュしなかった」ことしか証明できないためです。隠れた失敗を顕在化させるには `FAILPROOFAI_SDK_STRICT=1` を設定してください。 @@ -699,24 +701,24 @@ flowchart LR ## よくある問題 - - 開始イベントに対応する終了イベントがありません。`model_request` に `model_response` がない、または `tool_use` に `tool_result` がない場合です。本体が例外を発生させてもペアを保証するスコープを使用してください。イベントメソッドを直接呼び出す場合は `try` と `finally` を使用してください。 + + オープンイベントに対応するクローズイベントがありません。`model_request` に `model_response` がない、または `tool_use` に `tool_result` がない状態です。スコープを使用してください。本体が例外を送出した場合でもペアが保証されます。イベントメソッドを直接呼び出す場合は `try` と `finally` を使用してください。 - - これは対応する開始イベントから計測されるため、`tool_result`、`hook_completed`、`agent_resume`、`human_input` では拒否されます。本当のプロバイダーレイテンシを知っているのは呼び出し元だけであるため、`model_response` では受け付けられます。整数でなければなりません。 + + `tool_result`、`hook_completed`、`agent_resume`、`human_input` では、対応するオープンイベントからの経過時間として計測されるため拒否されます。`model_response` では受け付けられます。実際のプロバイダーレイテンシを知っているのが呼び出し側だけだからです。整数でなければなりません。 - - スレッドがコンテキストを継承しませんでした。呼び出し可能オブジェクトを `failproofai_sdk.propagate()` でラップしてください。[スレッドと非同期](#threads-and-async)を参照してください。 + + スレッドがコンテキストを継承していません。callableを `failproofai_sdk.propagate()` でラップしてください。[スレッドと非同期](#threads-and-async) を参照してください。 - - 追加フィールドは最後にマージされるため、`model` や `outcome` などの実際のフィールドと同じ名前のものはそれを上書きし、格納されるカラムを変更します。独自のものには名前空間を付けてください。アダプターは `fw_` プレフィックスを使用しています。 + + 追加フィールドは最後にマージされます。`model` や `outcome` など実際のフィールドと同じ名前を使用すると上書きされ、保存されるカラムが変わります。独自フィールドには名前空間を付けてください。アダプターは `fw_` プレフィックスを使用しています。 - - `agent_id` は低カーディナリティのファセットで、実行IDが入っています。ロール名またはノード名を使用し、実際のIDはペイロードフィールドに入れてください。 + + `agent_id` は低カーディナリティのファセットですが、実行IDを設定しています。ロール名やノード名を使用し、実際のIDはペイロードフィールドに格納してください。 @@ -724,10 +726,10 @@ flowchart LR - ペア、ID、セッションライフサイクル、配信について。 + ペア、ID、セッションのライフサイクル、配信の詳細。 - キャプチャしたセッションを通じて因果関係を追う。 + 記録したセッションの因果関係をたどる。 LangGraph、CrewAI、LlamaIndex、Pydantic AI。 diff --git a/docs/ja/start/quickstart.mdx b/docs/ja/start/quickstart.mdx index ace7fce4..6c3be338 100644 --- a/docs/ja/start/quickstart.mdx +++ b/docs/ja/start/quickstart.mdx @@ -1,12 +1,12 @@ --- title: "クイックスタート" -description: "エージェントセッションをキャプチャし、障害を検出し、防止策を導入する。" +description: "エージェントセッションをキャプチャし、障害を発見して、防止策を展開する。" icon: "zap" --- -このクイックスタートでは、1台のマシンでセッションのレポートを開始し、監査を実行し、ポリシーをデプロイします。スキルを使って Failproof を設定するか、手動手順に従ってください。 +このクイックスタートでは、1台のマシンにセッションをレポートさせ、監査を実行し、ポリシーをデプロイします。スキルを使ってFailproofをセットアップするか、手動の手順に従ってください。 -**どちらのパスを選びますか？** エージェントがサポートされている12の[ハーネス](/ja/reference/harnesses)のいずれか（コーディング CLI、または Hermes や OpenClaw などのゲートウェイ）で動作している場合は、以下の手順に従ってください。Node.js 20.9 以降が必要です。エージェントにハーネスがない場合は、[Python SDK](/ja/reference/custom-agents) を使ってトレースと監査のためのインストルメンテーションを行い、[最初の障害チェックを実行する](/ja/start/first-audit)から再合流してください。このパスでの enforcement にはランタイムにフックが必要です。 +**どちらの方法を選びますか？** エージェントがサポートされている12の[ハーネス](/ja/reference/harnesses)のいずれか（コーディングCLI、またはHermesやOpenClawのようなゲートウェイ）で動作している場合は、以下の手順に従ってください。Node.js 20.9以降が必要です。エージェントにハーネスがない場合は、[Python SDK](/ja/reference/custom-agents)でトレースと監査のためのインストルメント化を行い、[最初の障害チェックを実行する](/ja/start/first-audit)から再参加してください。そのパスでの強制執行には、ランタイムにフックが必要です。 @@ -21,19 +21,19 @@ icon: "zap" Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - エージェントがプロジェクトを検査し、関連するインテグレーションを選択し、セットアップを実行して検証します。個々のスキルや高度なインストールオプションについては、[FailproofAI スキルリポジトリ](https://github.com/FailproofAI/skills)を参照してください。 + エージェントがプロジェクトを検査し、適切なインテグレーションを選択し、セットアップを実行して確認します。個別のスキルや高度なインストールオプションについては、[FailproofAI スキルリポジトリ](https://github.com/FailproofAI/skills)をご覧ください。 - ## 始める前に + ## 開始前に -1. [Failproof AI ダッシュボード](https://app.befailproof.ai)を開き、アカウントを作成するか、仕事用メールアドレスでサインインします。 -2. **Administration → Keys** に移動し、`events:add` と `policies:pull` 権限を持つキーを作成します。 -3. ワンタイムシークレットをコピーし、対象マシンに保存します: +1. [Failproof AI ダッシュボード](https://app.befailproof.ai)を開き、アカウントを作成するか、仕事用メールでサインインします。 +2. **Administration → Keys** に移動し、`events:add` と `policies:pull` を持つキーを作成します。 +3. ワンタイムシークレットをコピーし、対象マシンのシェルで読み込みます。`read -s` はエコーしないプロンプトで受け取るため、コマンドに表示されることはありません。 ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## インストール @@ -42,12 +42,18 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - セッションのトランスクリプトはデフォルトで送信されます。トランスクリプトの内容を除いてフックアクティビティとポリシー決定のみをレポートするには、`--no-transcripts` を追加してください。 + このコマンド1つがセットアップのすべてです。ローカルデーモンをインストールし（rootで1回）、検出したすべてのエージェントCLIにフックを接続し、このマシンをCloudに接続します。`--token` ではなく環境変数でキーを渡すことで、`ps` からキーを隠します（マシン上のすべてのユーザーがコマンドの引数を読めるため）。ただし、シェル履歴からは隠れません — それを行うのが `read -s` です。CIでは、マスクされたシークレットとして注入し、シェルトレース（`set -x`）をオフにしてください。オンにすると、トレースにキーが出力されます。 - このマシンにすでにエージェントの履歴がある場合は、過去7日分をプレビューしてインポートし、配信が完了するまで待ちます。新しいマシンではこのステップをスキップしてください。 + セッションのトランスクリプトはデフォルトで送信されます。トランスクリプトの内容なしにフックアクティビティとポリシー決定のみをレポートするには、`--no-transcripts` を追加してください。 + + + ここで `failproofai config --connect ` は使用しないでください。このフラグは**すでに**セットアップ済みのマシンを登録してすぐに戻るだけで、デーモンもフックも設定されません。そのため、マシンがCloudに表示されても、何も収集・強制執行されない状態になります。 + + + このマシンにすでにエージェントの履歴がある場合は、過去7日間のデータをプレビューしてインポートし、配信が完了するまで待ちます。新しいマシンではこの手順をスキップしてください。 ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +61,41 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Failproof AI の **Sessions** を開き、インポートされたセッションを選択します。 + Failproof AI の **Sessions** を開き、インポートしたセッションを選択します。 - - これにより Failproof AI がハーネスにアタッチされ、39の組み込みポリシーがインストールされます。Failproof AI がセッションを監査してエージェント向けのポリシーを作成する前に、ローカルでのポリシー決定を確認したり enforcement を試したりするために使用できます。 + + 前の手順で、検出したすべてのエージェントCLIにすでに接続されています。必要に応じて1つのハーネスに対して明示的に再実行するか、後からインストールしたハーネスを追加する際に使用します。12種類すべてが有効な `--cli` の値です — `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose`。 + + ```bash + failproofai policies --install --cli claude --scope user # コーディングCLI + failproofai policies --install --cli hermes --scope user # Slack/Telegramゲートウェイ + ``` - インストーラーにハーネスを自動検出させるか、明示的に指定してください。12すべてが有効な `--cli` 値です — `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose`。 + 実行前のツールコールのブロックは12種類すべてで検証済みです。ターン終了ゲートは8種類で検証済みです — ハーネスごとのマトリクスは[強制執行機能](/ja/reference/harnesses#enforcement-capability)をご覧ください。 + + + フックの接続によってポリシーは有効になりません。セットアップは意図的にポリシーを選択しません — その決定はあなたに委ねられています — パックを取得してください： ```bash - failproofai policies --install --cli claude --scope user # コーディング CLI - failproofai policies --install --cli hermes --scope user # Slack/Telegram ゲートウェイ + failproofai policies add FailproofAI/policies ``` - ツールコールの実行前にブロックすることは12すべてで検証済みです。ターン終了ゲートは8つで検証済みです — ハーネスごとのマトリックスは[enforcement 機能](/ja/reference/harnesses#enforcement-capability)を参照してください。 + パックはGitHubリリースから取得され、チェックサムが検証され、解決された正確なタグにピン留めされます。38のポリシーが含まれており、マニフェストが無人で有効化しても安全とマークした10個が初期状態でオンになっています。Failproof AIがセッションを監査してエージェント用のポリシーを作成する前に、ローカルのポリシー決定を確認し、強制執行を試すために使用してください。 + + 取得前に `failproofai policies show /` でパックの内容を確認できます。パックの一部のみを取得する方法については、[ポリシーパック](/ja/policies/packs)をご覧ください。 + + これを実行するまでの間、強制執行されているのは `block-failproofai-commands` のみです — エージェントがFailproof AIをオフにすることを防ぐ、常時オンのガードです。`failproofai policies` で現在オンになっているものを一覧表示できます。 - [最初の障害チェックを実行する](/ja/start/first-audit)に従ってください。「エージェントがアプローチを変えずに失敗したツールをリトライしたセッションを見つける」など、具体的な目標を設定してください。 + [最初の障害チェックを実行する](/ja/start/first-audit)に従ってください。「エージェントがアプローチを変えずに失敗したツールを再試行したセッションを探す」などの具体的な目標を使用してください。 - [ポリシーで最初の障害を防止する](/ja/start/first-policy)に従ってください。観察モードで開始し、マッチを確認してから、レビュー済みのバージョンを enforce します。 + [ポリシーで最初の障害を防止する](/ja/start/first-policy)に従ってください。オブザーブモードで開始し、マッチを確認してから、レビュー済みのバージョンを強制執行してください。 - `failproofai config --status` を実行してください。正常なセットアップでは、クラウド接続、デーモンの状態、および enforcement が一時停止中かどうかがレポートされます。 + `failproofai config --status` を実行してください。正常なセットアップでは、クラウド接続、デーモンの状態、および強制執行が一時停止されているかどうかがレポートされます。 \ No newline at end of file diff --git a/docs/ja/start/setup.mdx b/docs/ja/start/setup.mdx index b1a2a6ca..c0eb1716 100644 --- a/docs/ja/start/setup.mdx +++ b/docs/ja/start/setup.mdx @@ -1,68 +1,89 @@ --- -title: "セットアップの選択" -description: "ローカル適用、Failproof AI Cloud、またはエンタープライズデプロイメントからお選びください。" +title: "セットアップ方法を選ぶ" +description: "ローカル実施、Failproof AI Cloud、またはエンタープライズ展開から選択してください。" icon: "waypoints" --- - - フックとポリシーをマシンにインストールします。セッションデータをクラウドに送信せずに即座にガードレールが必要な場合に使用してください。 + + Cloudキーなしでマシンをセットアップし、ポリシーパックを適用します。セッションデータをCloudに送信せずに即座にガードレールが必要な場合に使用してください。 - 集中管理されたセッション、監査、オンライン評価、ダッシュボード、アラート、フリートポリシーのデプロイメントを追加します。 + 集中管理されたセッション、監査、オンライン評価、ダッシュボード、アラート、フリートポリシー展開を追加できます。 - - 組織コントロール、スコープ付きキー、プライベートインフラ、およびデプロイメント固有のセキュリティ要件を使用します。 + + 組織コントロール、スコープ付きキー、プライベートインフラ、展開固有のセキュリティ要件を利用できます。 -## 推奨する本番環境への移行手順 +## ローカルで実施する -1. トランスクリプトキャプチャを有効にした非本番マシンを接続します。 -2. Cloud でセッションと評価を確認します。 -3. 既知の障害パターンに対する監査を作成します。 -4. 最初のポリシーをオブザーブモードでデプロイします。 -5. マッチ結果と誤検知を確認した後、本番環境へ展開します。 +キーなしで `failproofai config` を実行し、`failproofai policies add FailproofAI/policies` でパックを適用します。ターミナルでは、セットアップ時にCloudへの接続を求められたら **Not now — stay local** を選択してください。ターミナルがない場合や `FAILPROOFAI_CLOUD_TOKEN` が設定されていない場合は、自動的にローカルモードのまま動作します。デーモンとフックはマシン上で実施され、セッションデータはCloudに送信されません。後でCloudに接続するには、以下の手順に従ってください。 -## マシンを Cloud に接続する +## 推奨される本番導入の手順 + +1. トランスクリプトキャプチャを有効にして、非本番マシンを接続する。 +2. Cloudでセッションと評価を確認する。 +3. 既知の障害パターンに対して監査を作成する。 +4. 最初のポリシーをオブザーブモードで展開する。 +5. マッチ結果と誤検知を確認した後、本番環境に展開する。 + +## マシンをCloudに接続する 1. **Administration → Keys** に移動し、`events:add` と `policies:pull` の権限を持つキーを作成します。 2. ワンタイムシークレットをターゲットマシンにコピーします。 - 3. CLI の接続コマンドを実行した後、**Admin → enforcement** に移動して、マシンが表示されていることを確認します。 - 4. **Observe → Events** に移動して、最初のイベントが届いていることを確認します。 + 3. CLIの接続コマンドを実行した後、**Admin → enforcement** に移動し、マシンが表示されていることを確認します。 + 4. **Observe → Events** に移動し、最初のイベントが届いていることを確認します。 キードロワーには、接続されたマシンが必要とする2つの権限（イベント取り込みとポリシー配信）が表示されます。 - ![イベント取り込みとポリシー配信の権限を付与するための新しい API キードロワー。](/images/dashboard/key-create.png) + ![イベント取り込みとポリシー配信の権限を付与するための新しいAPIキードロワー。](/images/dashboard/key-create.png) - 接続後、マシンは適用状況ページに、希望するポリシー状態とデプロイメントステータスとともに表示されます。 + 接続後、マシンは希望するポリシー状態と展開ステータスとともに実施画面に表示されるはずです。 - ![希望するポリシー状態とデプロイメントステータスを表示するために展開された、登録済みマシンを含む Enforcement フリート。](/images/dashboard/enforcement-fleet.png) + ![登録済みマシンを展開して、希望するポリシー状態と展開ステータスを表示したEnforcementフリート。](/images/dashboard/enforcement-fleet.png) - 最初に届いたイベントにより、デーモンがポリシーのデプロイメントとは独立して、Cloud にデータを送信できることが確認されます。 + 最初のイベントが届いたことで、ポリシー展開とは独立してデーモンがCloudにデータを送信できることが確認されます。 ![最近のエージェント、モデル、ツールのイベントを表示するライブイベントストリーム。](/images/dashboard/events-stream-current.png) - マシンとその最初のイベントの両方が表示されていることを確認してから次に進んでください。 + マシンと最初のイベントの両方が表示されてから次に進んでください。 + ワンタイムシークレットをシェルに読み込みます。`read -s` はエコーされないプロンプトで入力を受け取るため、コマンドやシェル履歴に表示されることはありません。 + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + 次に、マシンをセットアップし、ポリシーを選択してラベルを付けます。 - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` - トランスクリプトのコンテンツをローカルに保持する必要がある場合は `--no-transcripts` を追加してください。 + `failproofai config` はセットアップ全体（デーモン、検出されたすべてのエージェントCLI向けのフック、Cloudへの接続）を実行し、ポリシーは選択しません。ポリシーの選択は2番目のコマンドで行います。 + + ラベルは接続**後**に付けます。セットアップ中ではありません。`failproofai config --machine-label ` はすでに接続済みのマシンの名前を変更します。未接続のマシンに対して実行してもその旨が表示されるだけです。 + + トランスクリプトの内容をローカルに保持する必要がある場合は `--no-transcripts` を追加してください。 + + CIでは、`read -s` の代わりにシークレットストアから `FAILPROOFAI_CLOUD_TOKEN` を設定し、シェルトレース（`set -x`）はオフにしてください。有効にするとトレースにキーが出力されてしまいます。 + + + **すでにセットアップ済み**のマシンでは、`failproofai config --connect ` は登録のみを行います。初回インストールにこの形式を使用しないでください。デーモンやフックが設置される前に処理が戻り、Cloudには表示されるが何も収集・実施しないマシンが残ってしまいます。 + -Cloud への接続では、イベント取り込みとポリシー配信が独立して検証されます。そのため、キーが有効であっても必要な権限の一方が不足している場合があります。どの機能が設定されているかを確認するには `failproofai config --status` を使用してください。 +Cloudへの接続では、イベント取り込みとポリシー配信が独立して検証されます。そのため、キーが有効でも必要な権限が不足している場合があります。どの機能が設定されているかを確認するには、`failproofai config --status` を使用してください。 - Cloud のセットアップは、関連する機能の検証が成功した場合にのみローカル認証情報を書き込みます。検証に失敗しても、実際には接続されていないのに接続済みのように見えるマシンが残ることはありません。 + Cloudのセットアップは、対応する機能の検証が成功した後にのみローカルの認証情報を書き込みます。検証に失敗しても、接続されていないマシンが接続済みのように見えることはありません。 \ No newline at end of file diff --git a/docs/ko/admin/keys-and-permissions.mdx b/docs/ko/admin/keys-and-permissions.mdx index d655eb9b..79f95cc4 100644 --- a/docs/ko/admin/keys-and-permissions.mdx +++ b/docs/ko/admin/keys-and-permissions.mdx @@ -1,29 +1,29 @@ --- title: "키와 권한" -description: "머신, 자동화, 운영자를 위한 범위가 지정된 API 키를 생성합니다." +description: "머신, 자동화, 운영자를 위한 범위 지정 API 키를 생성합니다." icon: "key-round" --- -API 키는 조직에 속하며 명시적인 권한을 갖습니다. 에이전트 수집, 정책 전달, 평가자, CI 자동화, 관리 스크립트에는 각각 별도의 키를 사용하세요. +API 키는 조직에 귀속되며 명시적인 권한을 가집니다. 에이전트 수집, 정책 전달, 평가자, CI 자동화, 관리 스크립트에는 각각 별도의 키를 사용하세요. ## 키 생성 및 교체 - 1. **Administration → Keys**로 이동하여 **새 키**를 선택하고 워크로드 이름을 입력합니다. - 2. 권한 세트를 선택하고, 사전 설정이 부족한 경우에만 개별 권한을 조정합니다. + 1. **Administration → Keys**로 이동하여 **new key**를 선택하고 워크로드 이름을 입력합니다. + 2. 권한 프리셋을 선택하고, 프리셋이 충분하지 않을 경우에만 개별 권한을 조정합니다. 3. 키를 생성하고 일회성 시크릿을 즉시 복사합니다. 4. 나중에 키를 열어 권한을 업데이트하거나, 비활성화하거나, 시크릿을 재생성할 수 있습니다. 생성 드로어에서 워크로드에 필요한 최소한의 권한을 선택합니다. - ![권한 사전 설정과 개별 권한이 표시된 새 API 키 드로어.](/images/dashboard/key-create.png) + ![권한 프리셋과 개별 권한이 표시된 새 API 키 드로어.](/images/dashboard/key-create.png) 생성 후 Keys 페이지에는 영구 메타데이터와 관리 작업이 표시됩니다. 일회성 시크릿은 다시 표시되지 않습니다. ![키 권한, 생성 시간, 재생성 및 비활성화 작업이 표시된 API Keys 페이지.](/images/dashboard/api-keys.png) - 이 목록을 주기적으로 검토하여 권한을 확인하고, 더 이상 활성 워크로드에 매핑되지 않는 키는 비활성화하세요. + 이 목록을 정기적으로 검토하여 권한을 확인하고, 더 이상 활성 워크로드에 매핑되지 않는 키는 비활성화하세요. ```bash @@ -40,12 +40,12 @@ API 키는 조직에 속하며 명시적인 권한을 갖습니다. 에이전트 -연결된 Failproof AI 머신에 필요한 두 가지 권한은 독립적입니다: +연결된 Failproof AI 머신에 필요한 두 가지 권한은 독립적입니다. -- `events:add`는 이벤트와 세션 데이터를 전송합니다. +- `events:add`는 이벤트 및 세션 데이터를 전송합니다. - `policies:pull`은 할당된 정책 배포를 가져옵니다. -키 시크릿은 생성 또는 재생성 시 표시됩니다. 시크릿 매니저에 저장하고, 운영자의 대화형 자격 증명을 재사용하지 않고 교체하세요. +키 시크릿은 생성 또는 재생성 시에만 표시됩니다. 시크릿 매니저에 저장하고, 운영자의 대화형 자격 증명을 재사용하지 않고 교체하세요. ## 권한 카탈로그 @@ -54,7 +54,7 @@ API 키는 조직에 속하며 명시적인 권한을 갖습니다. 에이전트 | Events | `events:add`, `events:read` | | Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update`는 사람 세션 전용 | | Users | `users:create`, `users:read`, `users:update`, `users:delete` | -| Evaluations | `evaluations:read`, `evaluations:trigger` | +| Evaluations | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | | Dashboards | `dashboards:read`, `dashboards:write`, `dashboards:delete` | | Queries | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | | Assistant | `agent:use` | @@ -65,10 +65,10 @@ API 키는 조직에 속하며 명시적인 권한을 갖습니다. 에이전트 | Policies | `policies:read`, `policies:write`, `policies:pull` | | Usage | `usage:read` | -`orgs:admin`은 인스턴스 운영자용으로 예약되어 있으며 조직 키 또는 일반 멤버에게 부여할 수 없습니다. 더 이상 사용되지 않는 `incidents:*` 및 `alerts:ack` 토큰은 호환성을 위해 계속 허용되며 현재 `issues:*` 권한으로 정규화됩니다. +`orgs:admin`은 인스턴스 운영자 전용으로 예약되어 있으며, 조직 키나 일반 멤버에게 부여할 수 없습니다. 폐기된 `incidents:*` 및 `alerts:ack` 토큰은 호환성을 위해 허용되며 현재 `issues:*` 권한으로 정규화됩니다. -기본 제공 권한 세트는 `read-only`, `standard`, `admin`입니다. `standard`는 읽기 권한에 평가 트리거, 쿼리 실행, 이슈 대응, 어시스턴트 사용을 추가합니다. 키 생성 시 권한 세트에 사람 전용 권한이 포함되어 있더라도 해당 권한은 제거됩니다. +기본 제공 권한 세트는 `read-only`, `standard`, `admin`입니다. `standard`는 읽기 권한에 평가 트리거, 쿼리 실행, 이슈 응답, 어시스턴트 사용 권한을 추가합니다. 키 생성 시 권한 세트에 포함되어 있더라도 사람 전용 권한은 제거됩니다. - 인스턴스 범위 키는 `X-AgentEye-Org` 헤더로 조직을 선택할 수 있습니다. 다중 조직 배포 환경에서는 이 헤더를 명시적으로 설정하세요. 생략하면 기본 조직이 선택될 수 있습니다. + 인스턴스 범위 키는 `X-AgentEye-Org` 헤더로 조직을 선택할 수 있습니다. 다중 조직 배포 환경에서는 이를 명시적으로 설정하세요. 생략하면 기본 조직이 선택될 수 있습니다. \ No newline at end of file diff --git a/docs/ko/evaluations/deploy.mdx b/docs/ko/evaluations/deploy.mdx new file mode 100644 index 00000000..414efebd --- /dev/null +++ b/docs/ko/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "평가 배포 및 버전 관리" +description: "불변 버전을 배포하고, 현재 운영 중인 항목을 확인하고, 새 버전을 게시하고, 롤백하고, 기존 세션을 채점하세요." +icon: "cloud-upload" +--- + +## 배포하기 + +작성 페이지 하단에서 **`@` 배포**를 선택하세요. 버전은 게시된 이후 불변 상태가 됩니다. 그 시점부터 완료된 모든 세션 중 조건에 해당하는 세션은 해당 버전으로 채점됩니다. + +## 현재 운영 중인 항목 확인 + +**Analyze → eval authoring**에서 조직의 호스팅된 정의 목록, 즉 관리형 평가자가 실행하는 평가 항목들을 확인할 수 있습니다. 각 행에는 다음 정보가 표시됩니다. + +- 이름, 키, 버전, 결과 유형 +- 소스 체크섬 — 코드를 열어보지 않고도 배포된 리비전을 구별할 수 있습니다 +- **조건부**로 실행되는지, **완료된 모든 세션**에 대해 실행되는지 여부 — 조건은 평가를 특정 에이전트나 환경으로 범위를 제한하는 기준입니다 +- 타임아웃, 레이블, 마지막 변경 시각 + +![호스팅된 정의 목록: 각 평가의 이름, 키, 버전, 결과 유형, 체크섬, 타임아웃, 범위와 함께 새 버전 및 활성화/비활성화 옵션이 표시됩니다.](/images/dashboard/eval-definitions.png) + +목록을 검색하거나 상태별로 필터링할 수 있습니다. 직접 등록한 워커의 평가는 여기에 표시되지 않으며, 해당 결과는 [evaluations 페이지](/ko/sessions/evaluations)에서 **customer** 태그로 표시되고, 호스팅된 평가는 **managed** 태그로 표시됩니다. + +조직에서는 최대 100개의 서로 다른 호스팅 평가를 동시에 활성화할 수 있습니다. + +## 새 버전 게시 + +해당 행에서 **new version**을 선택하세요. 해당 버전의 코드가 작성 페이지에 열립니다. 수정하고 테스트한 후 배포하세요. 키와 결과 유형은 그대로 유지되며 변경할 수 없습니다. + +새 버전을 게시하면 이전 버전이 비활성화되고 목록에는 계속 남아 있습니다. 결과에는 해당 결과를 생성한 버전 정보가 유지되므로, 차트에서 새 로직이 적용된 시점을 정확히 확인할 수 있습니다. + +## 롤백 + +현재 버전에서 **disable**을 선택하고, 복원하려는 버전에서 **enable**을 선택하세요. 아무것도 삭제되지 않으며, 모든 결과는 그대로 유지됩니다. + +## 평가 중단 + +**disable**을 선택하세요. 활성화된 버전이 없으면 새 세션에 대해 실행이 중단됩니다. 직접 실행 중인 워커의 평가를 중단하려면, 워커에서 해당 평가를 제거하거나 워커를 중단하여 등록을 해제하세요. + +## 기존 세션 채점 + +평가는 앞방향으로만 실행됩니다. 현재 배포된 버전은 배포 이전에 종료된 세션을 채점하지 않습니다. 과거 기록을 채점하려면 eval authoring 페이지에서 **score sessions you already have**를 열고, 최대 90일 범위의 기간을 선택한 후 선택적으로 단일 평가를 지정하여 실행 전에 건수를 확인하세요. 해당 건수가 정확히 실행될 대상이며, 포함된 각 세션-평가 쌍은 과금 대상 평가입니다. + +이 기능은 누락된 항목만 채웁니다. 해당 평가에 대한 결과가 이미 있는 세션은 기존 결과를 유지하며, 동일한 기간을 두 번 실행해도 새로운 채점이 발생하지 않습니다. + +수정 후 또는 정상적으로 종료되지 않은 세션에 대해 특정 세션을 다시 채점하려면, 해당 세션 페이지에서 **re-evaluate**를 선택하세요. 새 결과가 세션 기록에 추가되며, 이전 결과는 그대로 유지됩니다. + +## 권한 + +| 권한 | 허용 작업 | +| --- | --- | +| `evaluations:read` | 결과 확인 및 eval authoring 페이지 열기 | +| `evaluations:trigger` | 호스팅된 정의 확인, 배포, 버전 관리, 활성화 및 비활성화, 테스트, 기록 채점, 세션 재평가 | +| `events:read` | `evaluations:trigger` 권한에 더해, 실제 세션으로 테스트하고 페이로드 키를 기반으로 초안 작성 | +| `evaluations:run` | 직접 평가자 워커 실행 | \ No newline at end of file diff --git a/docs/ko/evaluations/overview.mdx b/docs/ko/evaluations/overview.mdx new file mode 100644 index 00000000..acf10118 --- /dev/null +++ b/docs/ko/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "에이전트 평가" +description: "완료된 모든 세션을 직접 정의한 평가로 채점합니다: 호스팅된 Python 체크 또는 자체 워커의 LLM 심사위원을 사용할 수 있습니다." +icon: "gauge" +--- + +평가는 완료된 에이전트 세션을 채점합니다. 세션이 종료되면 해당 세션에 적용되는 모든 활성화된 평가가 실행되고, 트레이스 옆에서 확인할 수 있는 근거와 함께 결과를 기록합니다: + +- **점수**: 0에서 1 사이의 값으로, 선택적으로 통과 또는 실패로 표시 +- **메트릭**: 횟수, 소요 시간, 비용 등의 수치와 단위 +- **어서션**: 통과 여부 + +## 두 가지 평가자 유형 + +| | 호스팅된 Python | 자체 워커 | +| --- | --- | --- | +| 작성 위치 | 대시보드의 **Analyze → eval authoring** | Python으로 작성, [Evaluator SDK](/ko/reference/evaluator-sdk) 사용 | +| 실행 환경 | Failproof AI의 관리형 평가자 (샌드박스 내부) | 직접 운영하는 인프라 | +| 적합한 경우 | 결정론적 코드 기반 체크 | LLM 심사위원, 모델 호출, 패키지, 시크릿, 네트워크 접근, 고부하 처리 | + +호스팅된 Python은 의도적으로 제한적입니다: 표현식 하나, 임포트 없음, 네트워크 없음. 모델이 필요한 작업 — 예를 들어 답변의 관련성을 판단하는 LLM 심사위원 — 은 자체 워커에서 실행합니다. 두 유형 모두 인바운드 연결이 필요하지 않습니다: 워커가 완료된 세션을 가져와 아웃바운드 HTTPS로 결과를 제출합니다. + +## 각 조직은 자신의 에이전트를 직접 평가합니다 + +평가는 이를 정의한 조직에 속합니다. 인스턴스 내의 각 조직은 자체적인 평가를 작성하며 — 체크 항목, 조건, 임계값, 레이블 모두 직접 설정하고 — 다른 조직에 영향을 주지 않고 버전을 관리하고 배포하며, 자신의 결과만 확인할 수 있습니다. 에이전트, 환경, 평가 항목, 시간별로 결과를 필터링하거나 어시스턴트에게 질문할 수 있습니다. + +## 초안 작성부터 실제 채점까지 + + + + 측정할 내용을 설명하고 어시스턴트가 초안을 작성하도록 하거나, 직접 작성합니다. [평가 작성하기](/ko/evaluations/write)를 참고하세요. + + + 실제 세션에 대해 실행하여 배포 전에 검증합니다. 결과는 저장되지 않습니다. [평가 테스트하기](/ko/evaluations/test)를 참고하세요. + + + 변경 불가능한 버전을 배포하고, 발전에 따라 새 버전을 게시하며, 이전 버전으로 롤백할 수 있습니다. [배포 및 버전 관리](/ko/evaluations/deploy)를 참고하세요. + + + 시간별 점수 추이를 차트로 확인하고, 에이전트와 환경을 비교하며, 어시스턴트에게 질문합니다. [평가 결과 확인하기](/ko/sessions/evaluations)를 참고하세요. + + + +평가는 순방향으로 실행됩니다: 지금 배포된 버전은 지금부터 완료되는 세션을 채점합니다. 이미 보유한 세션을 채점하려면 [백필](/ko/evaluations/deploy#score-sessions-you-already-have)을 사용하세요. \ No newline at end of file diff --git a/docs/ko/evaluations/test.mdx b/docs/ko/evaluations/test.mdx new file mode 100644 index 00000000..213f2d21 --- /dev/null +++ b/docs/ko/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "평가 테스트" +description: "평가를 배포하기 전에 실제 세션에 대해 실행해 보세요. 아무것도 저장되지 않습니다." +icon: "flask-conical" +--- + +작성 페이지에서 **이 평가 테스트**를 실행하면, 배포 없이 평가자 플릿의 실제 세션에 코드를 실행합니다. 아무것도 저장되지 않으며, 여기서 실패하더라도 미리보기일 뿐이고 배포는 항상 허용됩니다. + + + + **확인**을 선택하면 코드와 조건을 샌드박스의 규칙에 따라 컴파일하되, 어떤 세션에도 실행하지 않습니다. + + + 에이전트, 환경, 시간 또는 세션 ID로 매칭 세션을 좁힌 후, 최대 10개까지 선택하세요. 평가가 실패해야 하는 세션과 통과해야 하는 세션을 모두 포함하세요. + + + **N개의 세션에 대해 실행**을 선택하고, 각 행의 결과를 확인하세요. + + + +| 행 | 의미 | +| --- | --- | +| **ok** | 실행 완료. 반환된 모든 점수, 지표, 어설션과 소요 시간이 행에 표시됩니다. | +| **skipped** | 조건이 `False`를 반환하여 평가가 실행되지 않았습니다. 이는 실패가 아니라 건너뜀입니다. | +| Failed | 예외 발생, 타임아웃, 또는 샌드박스가 허용하지 않는 동작을 사용했습니다. 행에 원인이 표시되며, **Fix it**을 누르면 도움이 가능한 경우 오류를 어시스턴트에게 전달합니다. | + +![이 평가 테스트 패널: 에이전트 기준으로 세션 3개가 선택되어 있으며, 2개는 ok이고 1개는 조건이 False를 반환하여 skipped 상태입니다.](/images/dashboard/eval-test.png) + +코드를 수정하는 순간 결과는 더 이상 유효하지 않으며, 재사용되지 않고 흐리게 표시됩니다. \ No newline at end of file diff --git a/docs/ko/evaluations/write.mdx b/docs/ko/evaluations/write.mdx new file mode 100644 index 00000000..1b3f2dc2 --- /dev/null +++ b/docs/ko/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "평가 작성하기" +description: "측정할 내용을 설명하면 어시스턴트가 호스팅된 Python 평가를 초안으로 작성하거나, 직접 코드를 작성할 수 있습니다. LLM 판정자는 사용자 자신의 워커에서 실행됩니다." +icon: "file-pen-line" +--- + +호스팅 평가는 간결하고 결정론적인 Python 코드로, 대시보드에서 작성하고 Failproof AI의 평가자 플릿에서 실행됩니다. LLM 판정자, 패키지, 시크릿, 네트워크 호출 등 무거운 로직은 대신 [사용자 자신의 워커](#write-it-in-your-own-worker)에서 실행됩니다. + +## 설명으로 초안 작성하기 + +1. **Analyze → eval authoring**으로 이동하여 **new eval**을 선택합니다. +2. 측정할 내용을 일반 영어로 설명하거나 **start from an example…**에서 선택한 후 **draft**를 선택합니다. +3. 필드와 자동으로 채워진 코드를 검토한 다음 [테스트](/ko/evaluations/test)하고 [배포](/ko/evaluations/deploy)합니다. + +![설명, 초안에 대한 어시스턴트 노트, 이름, 키, 버전, 결과, 타임아웃, 레이블, 조건 필드가 포함된 초안 평가가 표시된 eval authoring 페이지.](/images/dashboard/eval-authoring-draft.png) + +초안은 조직 자체 이벤트를 기반으로 작성됩니다. 해당 페이지는 지난 7일간 세션에서 전달된 페이로드 키를 읽어, 코드가 추측이 아닌 실제로 존재하는 키를 참조하도록 합니다. 초안을 전달하기 전에 어시스턴트는 최근 세션 최대 5개를 대상으로 테스트하고, 최대 3라운드에 걸쳐 오류를 수정한 뒤, 코드가 요청한 내용을 측정하는지 한 번 더 확인합니다. 설명은 구체적으로 작성하세요. 광범위한 프롬프트는 처리 속도가 느리고 타임아웃이 발생할 수 있습니다. 어떤 경우에도 코드를 검토하세요. 배포는 항상 가능합니다. + +## 필드 설정하기 + +| 필드 | 설명 | +| --- | --- | +| name | 사용자에게 표시되는 이름. 이후 수정 가능 | +| key | 결과가 차트에 표시될 때 사용되는 고정 식별자 (예: `code_assistant_quality_gate`) | +| version | 공백 없는 버전 문자열 (예: `1.0.0`) | +| result | **score** (0~1), **metric** (단위가 있는 숫자), 또는 **assertion** (통과 여부) | +| timeout seconds | 기본값 30. 샌드박스는 단일 실행을 60초에서 중지합니다 | +| labels | 최대 20개, 쉼표로 구분. 이후 수정 가능 | +| condition | 선택 사항. Python 표현식으로, 해당 표현식이 `True`인 세션에서만 평가가 실행됩니다 | + +condition을 사용하면 평가 대상 에이전트와 환경으로 범위를 제한할 수 있습니다: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +키, 버전, 결과 유형, 조건, 코드는 배포 후 변경할 수 없습니다. 이 중 하나라도 변경하려면 새 버전을 게시해야 합니다. 이름, 레이블, 활성화 여부는 계속 수정할 수 있습니다. + +## 직접 코드 작성하기 + +**evaluator code**는 `EvalResult(...)`를 반환하는 단일 Python 표현식이며, 스코프 내에 `session`이 제공됩니다. 아래 예제는 성공적으로 반환된 도구 결과의 비율을 점수로 계산합니다: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +결과는 평가 자체의 키를 선두에 두고, 선언된 유형으로 시작합니다. 점수 평가는 `score=`를, 메트릭 또는 어서션 평가는 해당 키 이름의 `metrics` 또는 `assertions` 항목을 사용합니다. 그 외 메트릭과 어서션은 함께 포함될 수 있으며, 한 번 실행에 최대 25개의 결과를 담을 수 있습니다. + +| 스코프 내 항목 | 제공되는 정보 | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count`, `events`, 그리고 `count(event_type)`, `events_of_type(event_type)` | +| 각 이벤트 | `id`, `ts`, `event_type`, `payload` | +| 결과 유형 | `EvalResult`, `Score`, `Metric`, `Assertion`, 그리고 조건용 `ConditionResult` | +| 내장 함수 | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +이외에는 접근할 수 없습니다. import도 불가하며, 세션 데이터와 `get`, `lower`, `split` 같은 기본 문자열 및 딕셔너리 메서드 외의 속성은 사용할 수 없습니다. 이 메서드들은 참조가 아닌 호출 방식으로 사용해야 합니다. 페이로드 키는 에이전트가 전송하는 내용에 따라 달라집니다. 위의 `status`는 예시일 뿐이므로, 실제 세션에서 키를 직접 확인하세요. **format**은 코드를 정리하고, **fix**는 어시스턴트에게 수정을 요청합니다. 코드는 최대 128 KiB, 조건은 최대 16 KiB까지 작성할 수 있습니다. + +![초안 평가의 어서션을 보여주는 format 및 fix 버튼이 있는 evaluator code 편집기.](/images/dashboard/eval-authoring-code.png) + +## 사용자 자신의 워커에서 작성하기 + +평가에 모델, 패키지, 시크릿, 또는 네트워크가 필요한 경우, [Evaluator SDK](/ko/reference/evaluator-sdk)를 사용하여 작성하고 자체 인프라에서 실행하세요. 동일한 결과 유형을 사용하며, 결과는 호스팅된 결과 옆에 **customer** 태그와 함께 표시됩니다: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/ko/policies/deploy.mdx b/docs/ko/policies/deploy.mdx index 4f82eecd..5c886294 100644 --- a/docs/ko/policies/deploy.mdx +++ b/docs/ko/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "정책 배포" -description: "검토된 정책 버전을 대상 머신에 배포합니다." +title: "정책 배포하기" +description: "테스트된 정책 버전을 관찰 모드로 머신에 배포하고, 적용(enforce)한 뒤 모든 머신이 정상적으로 업데이트를 수신했는지 확인합니다." icon: "cloud-upload" --- -배포는 하나 이상의 정책 버전을 등록된 대상 머신 집합에 연결합니다. +배포는 게시된 정책 버전을 머신에 적용하며, 다음 두 가지 효과 중 하나로 동작합니다: -## 배포 적용 +- **Observe(관찰)**: 정책이 어떤 결정을 내렸을지 기록하며, 실제로 차단하지는 않습니다. +- **Enforce(적용)**: 결정에 따라 실제로 동작합니다. `deny`는 호출을 차단하고, `instruct`는 에이전트를 유도합니다. + +## 머신 추가하기 + +머신이 Cloud에 연결되면 **Admin → enforcement** 아래에 표시됩니다. 원하는 머신이 아직 나타나지 않는 경우: - 1. **Admin → enforcement**로 이동하여 머신을 찾고 해당 행을 펼칩니다. - 2. **edit**를 선택하고 검토된 정책 버전을 추가한 후 **observe** 또는 적용할 enforcement 효과를 선택합니다. - 3. 변경 사항을 적용한 후 머신의 다음 체크인을 기다리고 배포 및 커버리지 상태를 확인합니다. - 4. **Observe → policy**로 이동하여 실시간 결정 사항을 검사합니다. - - ![정책 버전, enforce 및 observe 효과, 배포 적용 액션이 표시된 머신 배포 편집기.](/images/dashboard/enforcement-editor.png) + 1. **Administration → Keys**로 이동하여 키를 생성합니다. 머신이 배포를 수신할 수 있도록 `policies:pull` 권한을, Cloud로 결정 내용을 전송할 수 있도록 `events:add` 권한을 부여합니다. + 2. 해당 키로 머신을 연결합니다. — [머신을 Cloud에 연결하기](/ko/start/setup#connect-a-machine-to-cloud)에서 자세한 과정을 안내합니다. + 3. **Admin → enforcement** 아래에 머신이 표시되는지 확인합니다. - CLI에서 `fp fleet`을 사용하여 배포합니다. 적용하기 전에 결과 집합을 검토하세요 — `deploy`는 전체 계획을 출력하며 `--json` 없이 인터랙티브 터미널에서만 확인을 요청합니다. `--json`이나 `--yes`를 사용하거나 stdin이 리다이렉트된 경우(CI 단계, 스크립트, 에이전트 셸 실행 등)에는 계획 표시 및 확인 없이 즉시 적용되므로, 검토가 필요하다면 먼저 `fp fleet show `을 실행하세요: + 머신에서 다음을 실행합니다: + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + 터미널에서 `failproofai config`를 실행하면 Cloud 연결 여부를 묻고, 마스킹된 프롬프트에서 키를 입력받습니다. 이후 어디서든 `fp fleet list` 명령으로 머신이 등록되었는지 확인할 수 있습니다. + + + +## 관찰 모드로 배포하기 + + + + 1. **Admin → enforcement**로 이동하여 머신을 찾고, 해당 행을 펼칩니다. + 2. **편집(edit)**을 선택하고, 테스트된 정책 버전을 추가한 뒤 **observe**를 선택합니다. + 3. 변경 사항을 적용한 후 머신의 다음 체크인을 기다리고, 배포 상태와 커버리지 상태를 확인합니다. + 4. **Observe → policy**로 이동하여 실시간 결정 내용을 검토합니다. + ![정책 버전, enforce/observe 효과, 배포 적용 액션이 포함된 머신 배포 편집기 화면](/images/dashboard/enforcement-editor.png) + + ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff `는 의도와 실제 적용 상태의 차이를 보여주고(머신은 다음 폴링 전까지 `behind` 상태로 표시됨), `fp fleet history `는 세대 목록을 나열하며, `fp fleet rollback `은 특정 세대로 복원합니다 — 해당 세대가 비활성화되거나 삭제된 정책을 참조하는 경우 거부됩니다. + `:observe` 접미사가 관찰 모드로 동작하게 합니다. `--add no-force-push`처럼 접미사 없이 사용하면 해당 정책에 대해 머신이 이미 가진 효과를 유지하며, 기본값은 enforce입니다. 나중에 `--add no-force-push:enforce`로 적용 모드로 전환할 수 있습니다. + + `deploy`는 **머신의 전체 정책 세트를 결과로 교체합니다**. 계획(plan)을 출력한 뒤 적용 전에 확인을 요청하지만, 이는 인터랙티브 터미널에서만 해당됩니다. `--yes` 옵션 사용 시, `fp --json` 아래에서, 또는 stdin이 리디렉션된 경우(CI 단계, 스크립트, 에이전트가 셸을 실행하는 경우)에는 확인 없이 바로 적용됩니다. 이 경우에도 계획은 계속 출력되거나 `--json` 옵션 사용 시 `plan` 필드로 반환됩니다. - 머신 자체는 `failproofai config --status`로 확인하고, 배포 후 `fp sessions --env production --since 24h` 및 `fp events --event-type hook_completed`를 사용하여 활동이 Cloud에 전달되는지 검증하세요. + 머신에서 `failproofai policies`를 실행하면 현재 실행 중인 Cloud 관리 정책 목록을, `failproofai config --status`를 실행하면 연결 상태를 확인할 수 있습니다. `fp sessions --env production --since 24h` 및 `fp events --event-type hook_completed` 명령으로 머신의 활동이 Cloud에 정상적으로 전달되는지 확인하세요. - - 변경 가능한 드래프트가 아닌 검토된 버전을 배포하되, 세션을 검사할 수 있는 비프로덕션 머신 또는 소규모 그룹부터 시작하세요. + + 게시된 버전과 해당 버전을 실행할 머신을 선택합니다. - - 작업을 차단하지 않고 매칭 항목, 이유, 영향받은 도구, 오탐지를 검토합니다. + + 아무것도 차단되지 않는 상태에서 매칭 결과, 사유, 영향받는 도구, 오탐(false positive)을 검토합니다. - - 관찰된 매칭 항목이 안전하지 않은 작업과 유효한 작업을 구분한 후 적용(enforce)하고, 의도한 모든 머신이 배포를 가져왔으며 결정 사항을 보고하고 있는지 확인합니다. + + 관찰된 매칭 결과가 안전하지 않은 행동과 유효한 행동을 명확히 구분하면 효과를 enforce로 전환합니다. 그런 다음 의도한 모든 머신이 변경 사항을 수신하고 결정 내용을 보고하고 있는지 확인합니다. -머신에는 `policies:pull` 권한이 필요합니다. 이벤트 보고는 `events:add`로 별도로 제어됩니다. Cloud 분석 및 적용을 기대하는 경우 두 가지 모두 확인하세요. +## 커버리지 확인하기 + +커버리지는 위험이 있는 곳에 정책이 실제로 실행되고 있는지를 나타냅니다. + +1. **Admin → enforcement**로 이동하여 enforce 및 observe 합계를 검토합니다. +2. ID나 레이블로 머신을 검색하거나, 특정 정책이 누락된 머신을 필터링합니다. +3. 행을 펼쳐 할당된 정책, 보고된 배포 상태, 마지막 체크인 시간, 이력을 비교합니다. +4. 적용된 배포가 아직 대기 중인 경우, 머신의 폴링 간격이 지난 후 새로고침합니다. + +![정책 커버리지, 머신 배포 상태, observe/enforce 할당 현황을 보여주는 Enforcement 플릿 화면](/images/dashboard/enforcement-fleet.png) + +최신 배포를 한 번도 수신하지 않은 머신, 보고를 중단한 등록된 머신, 잘못된 환경에 할당된 정책, 업데이트 중단 후 발생한 버전 불일치 등을 주의 깊게 확인하세요. + +머신에는 워크로드와 환경별로 레이블을 지정하세요 — 호스트명만으로는 오토스케일링이나 머신 교체 시 식별이 어렵습니다: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - Enforcement 관리는 관리자 전용 Cloud 워크플로우입니다. 루트 전용 enforcement 경로를 일반 고객용 `/v1` API 엔드포인트로 취급하지 마세요. + Enforcement 관리는 관리자 전용 Cloud 워크플로입니다. 루트 전용 enforcement 라우트를 일반 고객용 `/v1` API 엔드포인트로 취급하지 마세요. \ No newline at end of file diff --git a/docs/ko/policies/editor.mdx b/docs/ko/policies/editor.mdx index e4161882..bdc75997 100644 --- a/docs/ko/policies/editor.mdx +++ b/docs/ko/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "정책 편집기" -description: "확인된 실패 모드에서 버전 관리되는 정책을 생성하고 수정합니다." +title: "정책 작성" +description: "Failproof AI가 감사 결과를 바탕으로 정책 초안을 작성하거나, 직접 소스를 작성한 후 검토, 테스트, 게시할 수 있습니다." icon: "file-pen-line" --- -정책 편집기를 사용하여 발견된 문제나 이슈를 배포 가능한 규칙으로 변환합니다. 초안이 라이브 동작을 조용히 변경하지 않도록 작성과 배포를 분리하여 유지합니다. +정책을 작성하는 방법은 두 가지입니다. Failproof AI가 감사 결과를 바탕으로 초안을 작성하거나, 직접 소스를 작성하는 것입니다. 직접 선택하기 전까지는 어떤 것도 게시되거나 배포되지 않습니다. -이슈에 반복 가능한 액션 패턴이 있는 경우, **Analyze → issues** 에서 해당 이슈를 열고 **generate policy**를 선택합니다. Failproof AI는 먼저 정책이 해당 문제를 표현할 수 있는지 설명한 다음, 검토된 의도와 발견 컨텍스트를 편집기로 가져옵니다. 생성된 소스는 게시하기 전까지 초안 상태로 유지됩니다. +## 감사 결과로 정책 작성 -## 정책 버전 게시하기 +감사는 실패를 찾아내고, 정책은 그 실패가 다시 발생하는 것을 막습니다. Failproof AI는 결과의 증거 자료를 바탕으로 정책 초안을 작성합니다. + +### 1. 감사 실행 + +실패가 발생한 세션을 대상으로 [감사를 실행](/ko/audits/run)하세요. 각 결과에는 증거 세션, 근본 원인, 권장 예방 방법이 포함됩니다. **반복 가능한 액션 패턴**이 있는 결과를 기준으로 작업하세요 — 정책은 훅 이벤트에서 인식할 수 있는 것만 막을 수 있습니다. + +### 2. 초안 생성 - - 1. **Admin → policy editor**로 이동하여 **compose**에서 실패 모드를 설명하거나 JavaScript 정책 소스를 붙여넣습니다. - 2. 소스를 검증하고 보고된 모든 오류를 수정합니다. - 3. 정책 ID를 입력하고 게시한 다음, **library**를 사용하여 버전을 비교하거나 비활성화합니다. - 4. 버전이 머신 롤아웃 준비가 되면 **enforcement**를 선택합니다. + + 1. **Analyze → issues**에서 해당 결과의 이슈를 열고, 인용된 세션, 근본 원인, 권장 사항을 확인하세요. + 2. **generate policy**를 선택하세요. Failproof AI가 먼저 해당 문제를 정책으로 표현할 수 있는지 여부를 알려줍니다. **no policy** 결과는 수정 방법이 알림, 워크플로 변경, 또는 사람의 개입이 필요함을 의미하며 — 정책으로는 해결되지 않습니다. + 3. **write this policy**를 선택하세요. 이슈 제목, 결과, 근본 원인, 권장 사항, 제안된 적용 의도가 **Admin → policy editor**에 초안으로 생성됩니다. 적합성 검사에 동의하지 않을 경우 **open the editor anyway**를 사용하세요. - ![정책 ID, AI 지원 초안 작성, 소스 검증, 게시 컨트롤이 포함된 정책 편집기 compose 뷰.](/images/dashboard/policy-editor.png) + ![정책 ID, AI 지원 초안 작성, 소스 유효성 검사, 게시 컨트롤이 포함된 정책 편집기 작성 화면.](/images/dashboard/policy-editor.png) - `fp policies publish`를 사용하여 CLI에서 게시합니다. 이 명령은 **새 버전**을 생성하며 기존 버전을 직접 수정하지 않습니다. 또한 전송 전에 node로 소스의 파싱 오류를 확인합니다. 다운스트림에서는 이 검사를 수행하지 않으므로, 구문 오류가 있을 경우 시행 시점에 머신에서 오류가 발생할 수 있습니다: + 증거를 읽은 다음 어시스턴트로 초안을 작성하세요. `compose`는 검토할 소스를 출력하며 아무것도 게시하지 않습니다: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - 게시는 아무것도 배포하지 않습니다. 새 버전은 `fp fleet deploy`가 머신에 적용하기 전까지 미사용 상태로 유지됩니다. `fp policies compose ""`는 Cloud 어시스턴트를 사용하여 소스 초안을 작성하고, 게시하지 않고 검토를 위해 출력합니다. - - 로컬 에이전트 CLI(Cloud가 아닌)에 정책을 설치하려면 `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`를 사용합니다. + `compose`는 `policies:write` 역할이 있는 로그인 세션(`fp login`)이 필요하며, API 키는 허용되지 않습니다. -## 작성 체크리스트 +### 3. 초안 검토 + +초안은 시작점이지, 최종 결론이 아닙니다. 게시하기 전에 다음 사항을 확인하세요: + +1. 운영 언어로 실패 모드가 명시되어 있는지 확인합니다. +2. 판단에 충분한 증거를 담은 훅 이벤트와 도구에만 매칭되는지 확인합니다. +3. 안전하지 않은 액션을 포착하는 가장 좁은 조건을 사용하는지 확인합니다. +4. 에이전트에게 대신 해야 할 일을 알려주는 이유를 반환하는지 확인합니다. +5. 에이전트가 안전하게 경로를 수정할 수 있는 경우 `instruct`를 사용하고, 액션을 허용하는 것이 허용 불가하거나 되돌릴 수 없는 경우에만 `deny`를 사용하는지 확인합니다. + +편집기에서 소스를 검증하고 보고된 모든 오류를 수정하세요. + +### 4. 테스트 후 게시 + +게시하기 전에 소스 아래에서 **backtest**를 실행하세요: 플릿이 이미 수행한 호출에 대해 초안을 재실행하여, 중단되었을 정상 작동 호출의 수를 계산합니다. [정책 테스트](/ko/policies/test)에서 해당 내용과 기타 검사 방법을 확인할 수 있습니다. + +정책이 올바르게 작동하면, 정책 ID를 입력하고 **publish version**을 선택하세요. 게시하면 변경 불가능한 버전이 생성되며 배포는 이루어지지 않습니다: [배포](/ko/policies/deploy)할 때까지 사용되지 않은 상태로 남아 있습니다. 터미널에서 실행하려면: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish`는 소스를 전송하기 전에 구문을 검사하므로, 구문 오류는 적용 시점에 머신에서 발생하는 대신 여기서 표면화됩니다. + +## 직접 작성하기 + +정책은 `failproofai` API를 사용하는 JavaScript 또는 TypeScript입니다: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +이 정책은 `Write`와 `Edit` 모두에 대해 `production/config.yml`, `/srv/production/config.yml`, `/srv/production`, `C:\\production\\config.yml`에 매칭되지만, `production-backup`에는 매칭되지 않습니다: `production`은 전체 경로 세그먼트여야 합니다. 컨텍스트에는 이벤트 유형, 정규화된 페이로드, 세션 메타데이터, 파라미터, 가능한 경우 소스 CLI도 포함됩니다 — [policy SDK](/ko/reference/policy-sdk)를 참조하세요. + +버전으로 게시하려면, **Admin → policy editor**의 **compose**에 소스를 붙여넣고 위의 3단계와 4단계를 따르거나, `fp policies publish`로 터미널에서 파일을 게시하세요. -1. 실패 모드를 운영 언어로 명명합니다. -2. 판단에 충분한 증거를 포함하는 훅 이벤트와 도구를 선택합니다. -3. 안전하지 않은 동작과 일치하는 가장 좁은 조건을 작성합니다. -4. 에이전트 또는 운영자에게 다음 조치를 알려주는 이유를 반환합니다. -5. 일치해야 하는 예시와 허용된 상태로 유지되어야 하는 예시를 추가합니다. -6. 새 버전을 저장하고 검토를 요청합니다. +Cloud 없이 머신에서 실행하려면, 이름이 `policies.js`, `policies.mjs` 또는 `policies.ts`로 끝나는 파일을 `.failproofai/policies/` 아래에 저장하세요 — 이 파일들은 프로젝트 및 사용자 범위에서 자동으로 로드됩니다 — 또는 경로로 설치하세요: -에이전트가 안전하게 방향을 수정할 수 있을 때는 `instruct`를 사용합니다. 액션을 허용하면 용납할 수 없거나 되돌릴 수 없는 위험이 발생할 때는 `deny`를 사용합니다. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - 정책 버전은 변경 불가능한 배포 입력입니다. 초안을 편집하면 새 버전이 생성되며, 이미 머신에 할당된 버전을 덮어쓰지 않아야 합니다. - \ No newline at end of file +모든 정책에는 기본 제공, 커스텀, 팩, Cloud 관리 정책 전체에서 고유한 이름을 지정하세요. \ No newline at end of file diff --git a/docs/ko/policies/failure-behavior.mdx b/docs/ko/policies/failure-behavior.mdx index 0ccf92a0..90d0662a 100644 --- a/docs/ko/policies/failure-behavior.mdx +++ b/docs/ko/policies/failure-behavior.mdx @@ -4,16 +4,16 @@ description: "정책 평가 또는 로컬 데몬을 사용할 수 없을 때 어 icon: "shield-alert" --- -Failproof AI는 강제 적용 실패가 위험한 작업을 자동으로 허용하지 않고 눈에 띄게 드러나도록 설계되었습니다. +Failproof AI는 시행 실패가 위험한 작업을 조용히 허용하는 대신 눈에 띄게 드러나도록 설계되어 있습니다. -## 실패 차단 진단 +## 실패-폐쇄 차단 진단 1. **Admin → enforcement**로 이동하여 해당 머신을 엽니다. 2. 마지막 체크인, 할당된 배포, 보고된 배포를 확인합니다. 3. **Observe → policy**로 이동하여 거부된 결정의 세션을 엽니다. - 4. 거부 이유가 데몬 접근성, 버전 불일치, 또는 정책 자체와 관련된 것인지 확인합니다. + 4. 이유가 데몬 도달 가능성, 버전 불일치, 또는 정책 자체를 가리키는지 확인합니다. @@ -23,15 +23,15 @@ Failproof AI는 강제 적용 실패가 위험한 작업을 자동으로 허용 failproofai config ``` - 패키지 업그레이드 후 `failproofai config`를 다시 실행하면 데몬이 업데이트되고 재시작됩니다. + `failproofai config`를 다시 실행하면 패키지 업그레이드 후 데몬이 업데이트되고 재시작됩니다. -`failproofaid`를 사용하도록 구성된 머신에서는 데몬이 유일한 평가자입니다. 데몬에 접근할 수 없거나 프로토콜 버전이 CLI와 일치하지 않으면, 훅 평가가 차단 상태로 실패합니다. 해당 작업은 거부되며, 운영자에게 데몬을 확인하거나 업데이트하도록 안내하는 이유가 표시됩니다. +`failproofaid`를 사용하도록 구성된 머신에서는 데몬이 유일한 평가자입니다. 데몬에 접근할 수 없거나 프로토콜 버전이 CLI와 일치하지 않으면 훅 평가가 실패-폐쇄 방식으로 처리됩니다. 작업이 거부되며, 운영자가 데몬을 확인하거나 업데이트하도록 안내하는 이유가 함께 제공됩니다. -데몬 구성 전에는 훅이 프로세스 내에서 정책을 평가합니다. 데몬 구성이 기록된 이후에는 Failproof AI가 데몬 실패 시 두 번째 평가자로 자동 전환하지 않습니다. +데몬 구성 이전에는 훅이 프로세스 내에서 정책을 평가합니다. 데몬 구성이 기록된 이후에는, 데몬이 실패하더라도 Failproof AI가 두 번째 평가자로 자동으로 폴백하지 않습니다. -## 실패 차단 결정에 대응하기 +## 실패-폐쇄 결정에 대응하기 1. `failproofai config --status`를 실행합니다. 2. 버전이 다를 경우, 패키지를 업데이트한 후 `failproofai config`를 다시 실행합니다. @@ -39,29 +39,31 @@ Failproof AI는 강제 적용 실패가 위험한 작업을 자동으로 허용 4. 정책 평가 경로가 정상임을 확인한 후에만 에이전트 작업을 재개합니다. - 차단된 작업을 반복해서 재시도하지 마십시오. 실패 차단 응답은 시스템이 해당 작업의 안전성을 확인하지 못했음을 의미합니다. + 차단된 작업을 반복적으로 재시도하지 마십시오. 실패-폐쇄 응답은 시스템이 해당 작업의 안전성을 확인할 수 없었음을 의미합니다. -## 팩이 로드되지 않는 경우 +## 팩을 불러올 수 없는 경우 -팩을 적용하도록 지시받은 머신이 해당 팩을 실행할 수 없는 경우, 조용히 계속 진행하지 않고 거부합니다. 트리거는 **기록된 기대치**이며, 비어 있는 기대치가 아닙니다. 팩이 설치되지 않은 머신은 아무 반응도 하지 않지만, 선언되었지만 확인되지 않는 팩이나 매니페스트에 선언된 것보다 적게 등록된 팩은 거부합니다. +팩을 시행하도록 설정된 머신이 해당 팩을 실행할 수 없을 때, 시스템은 조용히 계속 진행하는 대신 거부합니다. 트리거는 **기록된 기대값**이며, 빈 값이 아닙니다. 즉, 팩이 설치되지 않은 머신은 조용히 있지만, 선언되었지만 해석되지 않거나 매니페스트가 선언한 것보다 적게 등록된 팩은 거부합니다. -이 거부는 접근할 수 없는 데몬의 경우와 달리 **범위가 좁습니다**. 데몬에 접근할 수 없다는 것은 평가가 전혀 이루어지지 않았음을 의미하므로, 어떤 것도 안전하다고 알 수 없습니다. 반면 로드되지 않는 팩은 누락된 가드의 목록을 열거할 수 있습니다. 선언된 각 정책에는 자체 `match`가 있기 때문에, 해당 정책이 적용하는 이벤트와 도구만 거부하고 나머지는 계속 진행됩니다. +이 거부는 데몬에 접근할 수 없는 경우와 달리 **범위가 좁습니다**. 데몬에 접근할 수 없다는 것은 평가가 전혀 이루어지지 않아 어떤 것도 안전하다고 알 수 없음을 의미합니다. 반면, 불러올 수 없는 팩은 누락된 가드의 열거 가능한 집합을 가집니다. 모든 선언된 정책이 고유한 `match`를 가지기 때문에, 해당 정책이 적용되는 이벤트와 도구에 대해서만 거부하고 나머지는 정상 진행됩니다. -다음 경우에는 거부가 발생하지 않습니다: +다음 경우에는 발동되지 않습니다: -- 구성상 평가 후 폐기하는 `observe` 팩 -- 사용한 적 없거나 명시적으로 비활성화된 정책 -- 로더가 수신한 적 없는 팩 (이 경우 "등록 없음"과 의도적인 건너뜀을 구분할 수 없음) -- 활성 세션 일시 중지 -- 로드 타임아웃 (일시적인 현상) — 디스크가 잠깐 느린 순간 때문에 사람이 개입하기 전까지 거부가 발생해서는 안 됨 +- 구조적으로 평가 후 폐기하는 `observe` 팩 +- 사용하지 않거나 명시적으로 비활성화한 정책 +- 로더가 수신하지 못한 팩 (이 경우 "등록 없음"을 의도적인 건너뜀과 구별할 수 없음) +- 활성 세션 일시 정지 +- 부하 타임아웃 (일시적인 현상으로, 디스크가 한 번 느린 순간 때문에 사람이 개입할 때까지 거부해서는 안 됨) -`UserPromptSubmit`은 누락된 정책이 무엇을 선언했든 거부 대신 **instruct**합니다. 전면적인 거부는 문제를 해결할 수 있는 에이전트에서도 차단을 야기하기 때문입니다. +`UserPromptSubmit`은 누락된 정책이 무엇을 선언했든 관계없이 거부 대신 **instructs**합니다. 전면 거부는 이를 함께 차단하여 문제를 수정할 수 있는 에이전트에서 잠겨버릴 수 있기 때문입니다. ### 해결 방법 ```bash -failproofai pack list +failproofai policies ``` -이 명령은 로드되지 않는 설치된 팩의 이름과 이유를 출력하고 비정상 종료 코드로 종료합니다. 이후 팩을 재설치하거나(`failproofai pack add `) 제거하십시오(`failproofai pack remove `). 제거하면 기대치가 철회되고 거부도 함께 중단됩니다. \ No newline at end of file +목록에는 설치 레코드 또는 다이제스트가 더 이상 유효하지 않은 설치된 팩이 표시되며 그 이유도 알려줍니다. 팩을 임포트하지 않으므로, 로드될 때만 실패하는 팩(매니페스트가 선언한 것보다 적게 등록하는 팩)은 정상으로 나열됩니다. 이 경우 아래의 거부가 해당 팩을 식별합니다. 어느 경우든 팩을 재설치(`failproofai policies add `)하거나 제거(`failproofai policies remove `)하면 됩니다. 제거하면 기대값이 철회되고 거부도 함께 중단됩니다. + +거부 자체는 `pack/failproofai-pack-unavailable`에 귀속되며, 이는 로드된 정책보다 우선순위가 높습니다. 따라서 차단된 도구 호출은 먼저 발동된 살아남은 가드가 아닌 누락된 팩을 식별합니다. \ No newline at end of file diff --git a/docs/ko/policies/local-configuration.mdx b/docs/ko/policies/local-configuration.mdx index 48b4fde7..5aadfb09 100644 --- a/docs/ko/policies/local-configuration.mdx +++ b/docs/ko/policies/local-configuration.mdx @@ -1,33 +1,28 @@ --- title: "로컬 설정" -description: "정책 범위, 매개변수, 커스텀 파일, 머신 수준 Failproof AI 설정을 제어합니다." +description: "정책 범위, 파라미터, 사용자 정의 파일, 머신 수준 Failproof AI 설정을 제어합니다." icon: "file-cog" --- -Failproof AI는 정책 선택과 머신 및 데몬 설정을 분리합니다. 이를 통해 저장소 정책 선택 사항은 검토 가능한 상태로 유지하면서, 자격 증명과 데몬 상태는 저장소 외부에 보관됩니다. +Failproof AI는 저장소에 커밋할 수 있는 항목(훅 연결, 정책 파라미터, 사용자 정의 정책)과 자격 증명, 설치된 팩, 데몬과 같은 머신 상태를 분리하여 관리합니다. -## 정책 범위 선택 +## 범위 선택 - - - 인수 없이 `failproofai`를 실행하면 로컬 정책 대시보드가 열립니다. 정책을 활성화하기 전에 user, project, 또는 local 범위를 선택하면 변경 사항이 해당 설정 파일에 저장됩니다. +범위는 훅이 연결되는 위치와 파라미터 및 사용자 정의 정책 경로를 기록하는 설정 파일을 결정합니다: - - **User** 범위는 이 머신의 모든 프로젝트에 적용됩니다. - - **Project** 범위는 저장소에 속하며 커밋할 수 있습니다. - - **Local** 범위는 한 명의 사용자에 대해 하나의 프로젝트를 재정의하며, gitignore에 추가해야 합니다. +- **User**: 이 머신의 모든 프로젝트에 적용됩니다. +- **Project**: 저장소에 속하며 커밋할 수 있습니다. +- **Local**: 특정 프로젝트를 특정 사용자에게만 재정의하며, gitignore에 추가해야 합니다. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # 이 저장소에 훅 연결 +failproofai policies --install --cli claude --scope user # 또는 이 머신의 모든 프로젝트에 연결 +failproofai policies +``` - 모든 하네스가 local 범위를 지원하는 것은 아닙니다. CLI는 선택된 하네스가 표현할 수 없는 범위를 거부합니다. - - +모든 하네스가 로컬 범위를 지원하는 것은 아닙니다. 선택한 하네스가 해당 범위를 표현할 수 없으면 CLI가 거부합니다. + +팩 정책의 활성화 여부는 범위와 **무관합니다**. 이 설정은 설치된 팩에 함께 기록되므로, `failproofai policies add `은 `--scope` 값에 관계없이 머신 전체에서 정책을 활성화합니다. | 범위 | 정책 설정 파일 | | --- | --- | @@ -35,21 +30,20 @@ Failproof AI는 정책 선택과 머신 및 데몬 설정을 분리합니다. | Local | `/.failproofai/policies-config.local.json` | | User | `~/.failproofai/policies-config.json` | -활성화된 정책은 합집합으로 병합됩니다. 정책 매개변수는 project → local → user 순서로, 해당 정책의 매개변수를 정의한 첫 번째 범위를 사용합니다. 명시적 커스텀 정책 경로도 이를 정의한 첫 번째 범위를 사용합니다. +정책 파라미터는 해당 정책에 대한 파라미터를 정의하는 첫 번째 범위를 사용하며, 우선순위는 project → local → user 순입니다. 명시적인 사용자 정의 정책 경로도 이를 정의하는 첫 번째 범위를 사용합니다. -## 정책 매개변수 설정 +## 정책 파라미터 설정 - 로컬 대시보드에서 정책을 열고, 지원되는 매개변수를 편집한 후 선택한 범위에 저장합니다. 일치하는 에이전트 액션과 일치하지 않는 에이전트 액션을 각각 실행한 뒤, **Observe → policy**에서 결정 내용을 확인합니다. + 로컬 대시보드에서 정책을 열고, 지원되는 파라미터를 수정한 후 선택한 범위에 저장합니다. 일치하는 에이전트 작업과 일치하지 않는 에이전트 작업을 각각 실행한 후, **Observe → policy**에서 결정 내역을 확인합니다. - 선택한 범위의 `policies-config.json`을 편집한 후, `failproofai policies`를 실행하여 알 수 없는 정책 이름이나 매개변수 키를 확인합니다. + 선택한 범위의 `policies-config.json`을 직접 편집한 후 `failproofai policies`를 실행합니다. 설치된 팩에 없는 정책을 `policyParams` 항목에 지정하면 경고가 표시됩니다. 항목 내부의 키는 검사하지 않으므로, 아래 표를 참고하여 철자를 직접 확인하세요. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ Failproof AI는 정책 선택과 머신 및 데몬 설정을 분리합니다. -## 머신 파일 이해하기 +### Failproof AI 정책이 허용하는 파라미터 + +각 정책은 자체적으로 파라미터 타입을 검증합니다. + +| 정책 | 파라미터 | 타입 및 기본값 | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; 항목에 `regex`와 `label` 포함 | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| 인프라 차단 정책 | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + 허용 패턴은 에이전트가 수행할 수 있는 작업의 범위를 넓힙니다. 플릿 전체에 배포하기 전에 대상 하네스에서 정확한 토큰화 방식과 명령어 변형을 반드시 테스트하세요. + + +## 머신 파일 구조 이해 -`~/.failproofai`는 신뢰 경계별로 파일을 분리하여 저장합니다: +`~/.failproofai`는 신뢰 경계에 따라 파일을 분리하여 관리합니다: | 경로 | 용도 | | --- | --- | | `config.json` | 비밀이 아닌 데몬, 감사, 텔레메트리 설정 | | `credentials.json` | 클라우드 자격 증명; 소유자 전용 권한으로 저장 | -| `policies-config.json` | User 범위 빌트인 선택, 매개변수, 명시적 커스텀 경로 | -| `policies/` | User 규약 정책 및 Cloud 관리 정책 아티팩트 | +| `policies-config.json` | 사용자 범위 파라미터 및 명시적 사용자 정의 정책 경로 | +| `policies/` | 사용자 컨벤션 정책, 설치된 팩과 활성화된 정책 목록, Cloud 관리 정책 아티팩트 | | `hook-activity/` | 로컬 정책 결정 로그 | -| `state/` | 데몬 스풀, 상태 확인, 일시 중지, 런타임 상태 | +| `state/` | 데몬 스풀, 상태 점검, 일시 정지, 런타임 상태 | -컨테이너 또는 격리된 테스트 환경에서 전체 머신 레이아웃을 재배치하려면 `FAILPROOFAI_HOME`을 사용하세요. 개별 상태 디렉터리를 독립적으로 재배치하지 마세요. +컨테이너나 격리된 테스트 환경을 위해 전체 머신 레이아웃을 이전하려면 `FAILPROOFAI_HOME`을 사용하세요. 개별 상태 디렉터리를 독립적으로 이전하지 마세요. - `credentials.json`은 절대 커밋하지 마세요. 프로젝트 정책 설정과 프로젝트 규약 정책은 강제 적용 코드로서 검토한 후에만 커밋하세요. + `credentials.json`은 절대 커밋하지 마세요. 프로젝트 정책 설정과 프로젝트 컨벤션 정책은 강제 실행 코드로서 충분히 검토한 후에만 커밋하세요. \ No newline at end of file diff --git a/docs/ko/policies/overview.mdx b/docs/ko/policies/overview.mdx index 39373c44..761ce767 100644 --- a/docs/ko/policies/overview.mdx +++ b/docs/ko/policies/overview.mdx @@ -1,63 +1,54 @@ --- -title: "Policies" -description: "에이전트 동작을 관찰하고, 안내하거나, 알려진 실패가 반복되기 전에 차단하세요." +title: "정책" +description: "알려진 실패가 반복되기 전에 에이전트 작업을 관찰하고, 안내하거나, 차단하세요." icon: "shield-check" --- -Policy는 에이전트 훅 이벤트를 평가하여 세 가지 결정 중 하나를 반환합니다: +정책은 에이전트 훅 이벤트를 평가하고 세 가지 결정 중 하나를 반환합니다: -- `allow` — 작업을 계속 진행합니다. -- `instruct` — 에이전트에게 수정 안내를 제공합니다. -- `deny` — 이유와 함께 작업을 차단합니다. +- `allow`는 작업을 계속 진행하도록 허용합니다. +- `instruct`는 에이전트에게 수정 안내를 제공합니다. +- `deny`는 이유와 함께 작업을 차단합니다. -## 세 가지 Policy 화면 활용하기 +## 정책이 위치하는 곳 - - - 1. **Observe → policy**로 이동하여 세션의 policy 결정을 필터링하고 검토합니다. - 2. **Admin → policy editor**로 이동하여 policy를 작성, 검증, 게시, 비활성화하거나 변경 불가능한 버전을 확인합니다. - 3. **Admin → enforcement**로 이동하여 머신에 버전과 효과를 할당합니다. +| 대시보드 메뉴 | 수행 작업 | +| --- | --- | +| **Observe → policy** | 실제 세션의 결정 검토: 어떤 정책이 어떤 머신에서, 왜 매칭되었는지 확인 | +| **Admin → policy editor** | 정책 작성, 과거 트래픽 대상 백테스트, 변경 불가한 버전 게시, **library**에서 버전 비교 | +| **Admin → enforcement** | 머신에 버전 배포, observe 또는 enforce 모드 설정 | - Policy 작성이나 적용 변경 전에, Policy 페이지를 통해 이미 매칭되고 있는 항목을 파악하세요. +정책 편집기는 실패를 규칙으로 만드는 곳입니다. **compose**에서 실패 패턴을 설명하거나 정책 소스를 붙여넣고, 이미 보유한 트래픽을 대상으로 초안을 백테스트한 후 버전을 게시하세요: - ![결정 총계와 로컬 및 클라우드 관리 policy 매핑을 보여주는 Policy 페이지.](/images/dashboard/policy-observe.png) +![정책 ID, AI 보조 초안 작성, 소스 유효성 검사, 게시 컨트롤이 포함된 정책 편집기 compose 화면.](/images/dashboard/policy-editor.png) - 에디터에서는 실패 조건을 소스 코드로 변환하고, 검증한 뒤 변경 불가능한 버전으로 게시합니다. +머신에서 `failproofai policies`를 실행하면 해당 머신에 적용 중인 모든 항목이 나열됩니다. `fp policies`와 `fp fleet`은 터미널에서 편집기와 시행을 다룹니다 — [Cloud CLI 참조](/ko/reference/cloud-cli)를 확인하세요. - ![변경 불가능한 policy 버전을 작성하고 게시하는 데 사용되는 Policy 에디터.](/images/dashboard/policy-editor.png) +## 정책 가져오기 - Enforcement에서는 게시된 버전과 observe 또는 enforce 효과를 머신에 할당합니다. - - ![머신 커버리지와 할당된 policy 버전을 보여주는 Enforcement 플릿.](/images/dashboard/enforcement-fleet.png) - - 배포 후에는 Policy 페이지로 돌아가 결정 사항을 검증하여 작성 및 플릿 뷰가 실제 에이전트 활동과 연결되도록 합니다. - - - 로컬 policy 설치 및 검증에는 `failproofai`를 사용하세요: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - 클라우드 세션과 policy 결정이 포함된 이벤트를 찾으려면 `fp`를 사용하세요. 클라우드 policy 작성 및 플릿 배포는 대시보드 워크플로우로 진행됩니다. - - - -Failproof AI에서 Policy는 세 가지 독립적인 화면을 통해 운영됩니다: - -1. **결정 분석** — 세션, 대시보드, 감사 로그에서 확인합니다. -2. **버전 작성** — 내장 규칙, 코드, 또는 policy 에디터로 작성합니다. -3. **배포 및 적용** — 선택한 머신 전체에 버전을 배포하고 시행합니다. - -확인된 실패 사례에서 시작하세요. 해당 사례를 식별하는 가장 작은 이벤트 및 도구 매칭을 정의하고, 정상 및 비정상 예시로 테스트한 뒤, 시행(enforcing) 전에 먼저 관찰(observing)하세요. +두 가지 방법이 있습니다. - - 비밀 키, 셸, Git, 클라우드, 워크플로우 위험에 대한 검토된 규칙을 활성화하세요. + + 감사 결과를 바탕으로 Failproof AI가 초안을 작성하도록 하거나, 직접 소스를 작성한 후 편집기에서 검토하고 게시하세요. - - 워크플로우에 특화된 결정 로직을 JavaScript 또는 TypeScript로 작성하세요. + + 사용 사례에 맞는 Failproof AI 정책 팩이나 policy hub의 커뮤니티 팩을 한 번의 명령으로 적용하세요. - \ No newline at end of file + + +## 배포하기 + + + + 이미 보유한 트래픽을 대상으로 초안을 백테스트하고, 반드시 차단해야 하는 작업과 반드시 허용해야 하는 작업 모두에 대해 실행해 보세요 — 게시 전에 모두 완료합니다. [정책 테스트](/ko/policies/test)를 참조하세요. + + + **observe** 모드로 머신에 버전을 배포하고, 결정 사항을 확인한 후 enforce로 전환하세요. [정책 배포](/ko/policies/deploy)를 참조하세요. + + + 모든 게시는 새로운 변경 불가한 버전이므로, 유효한 작업을 차단하는 롤아웃이 발생하면 마지막 정상 버전을 재배포하여 되돌릴 수 있습니다. [버전 관리 및 롤백](/ko/policies/rollback)을 참조하세요. + + + +다른 팀과 정책을 공유하려면 [팩으로 게시](/ko/policies/publish-a-pack)하세요. 정책을 전혀 평가할 수 없는 경우 어떻게 되는지는 [실패 동작](/ko/policies/failure-behavior)을 참조하세요. \ No newline at end of file diff --git a/docs/ko/policies/packs.mdx b/docs/ko/policies/packs.mdx index 0ae6c86a..908ac1f8 100644 --- a/docs/ko/policies/packs.mdx +++ b/docs/ko/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "Policy packs" -description: "GitHub 릴리즈로 배포된 정책 집합을 설치하고, 적용 항목을 관리합니다." +title: "정책 팩 사용하기" +description: "사용 사례에 맞는 Failproof AI 정책 팩이나 정책 허브의 커뮤니티 팩을 연결하고, 적용할 내용을 선택하세요." icon: "package" --- -팩(pack)은 GitHub 릴리즈로 배포된 정책의 집합입니다. 명령 하나로 설치할 수 있으며, 실행 전에 릴리즈 자체의 체크섬이 검증되고, 이후 팩이 변경되지 않도록 다이제스트가 기록됩니다. +팩은 GitHub 릴리스로 배포되는 정책 모음입니다. 명령어 하나로 설치할 수 있으며, 실행 전에 릴리스의 체크섬이 검증되고 다이제스트가 기록됩니다. 기록 이후에는 팩이 변조되더라도 머신에서 감지됩니다. -## Failproof AI 정책 설치하기 +모든 팩과 각 팩에 포함된 모든 정책은 [정책 허브](https://befailproof.ai/policy-hub/)에서 확인할 수 있습니다. 두 가지 종류가 있습니다: + +- **Failproof AI 정책 팩** — 사전 정의된 사용 사례를 위한 완성형 팩입니다. 연결하는 즉시 작동합니다. [코딩 에이전트 정책 팩](https://befailproof.ai/policy-hub/failproofai/policies/)이 현재 제공되며, 더 많은 사용 사례를 위한 팩이 곧 출시될 예정입니다. +- **커뮤니티 정책 팩** — 개발자들이 자신의 사용 사례를 위해 작성하고 공개한 정책입니다. + +## Failproof AI 정책 팩 + +### 코딩 에이전트 정책 팩 ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -이 명령은 npm 패키지 내부에 포함된 복사본을 설치합니다. 네트워크가 필요 없으며 프록시 환경에서도 실패하지 않습니다. 일부만 선택해서 설치할 수도 있습니다: +이 팩에는 38개의 정책이 포함되어 있으며, 매니페스트에서 무인 실행에 안전하다고 표시된 10개가 기본으로 활성화됩니다. 나머지는 목록으로 제공되어 직접 선택할 수 있습니다. 가장 많이 사용되는 정책과 `policies add` 명령만으로 활성화되는지 여부는 다음과 같습니다: + +| 정책 | 기능 | 기본 활성화 | +| --- | --- | --- | +| `block-push-master` | 보호된 브랜치에 대한 직접 푸시 차단 | 예 | +| `block-env-files` | `.env` 파일 읽기 및 쓰기 차단 | 예 | +| `protect-env-vars` | 환경 변수를 출력하는 명령 차단 | 예 | +| `block-sudo` | allow 패턴이 일치하지 않는 한 `sudo` 차단 | 예 | +| `block-curl-pipe-sh` | 다운로드한 스크립트를 셸에 직접 파이프하는 행위 차단 | 예 | +| `sanitize-*` (5개 정책) | 도구 출력에서 발견된 API 키, 베어러 토큰, JWT, 개인 키, 연결 문자열 보고 | 예 | +| `block-rm-rf` | 재귀적 삭제 명령 차단 | 아니요 | +| `block-force-push` | 강제 푸시 차단 | 아니요 | +| `block-secrets-write` | 자격 증명 및 비밀 키 파일 쓰기 차단 | 아니요 | +| `warn-destructive-sql` | `WHERE` 절 없는 `DROP`, `TRUNCATE`, `DELETE` 경고 | 아니요 | + +비활성화된 정책은 이름으로 켤 수 있습니다 — `failproofai policies add block-rm-rf` — 또는 `--all`을 사용해 팩 전체를 가져올 수 있습니다. 카테고리별로 그룹화된 모든 정책 보기: ```bash -failproofai pack add core --policy block-rm-rf # 하나, 또는 쉼표로 구분된 여러 개 -failproofai pack add core --category dangerous-commands # 카테고리 전체 -failproofai pack add core --all # 팩에 포함된 모든 항목 +failproofai policies show FailproofAI/policies ``` -`failproofai pack list`를 실행하면 해당 팩이 제공하는 모든 카테고리를 확인할 수 있습니다. +## 커뮤니티 정책 팩 -## 설치 전에 팩의 내용 확인하기 +개발자들은 자신이 경험한 사용 사례를 위한 팩을 배포하며, [정책 허브](https://befailproof.ai/policy-hub/)에서 목록을 확인할 수 있습니다. 커뮤니티 팩은 작성자가 직접 배포하며 Failproof AI의 감사를 거치지 않으므로, 설치 전에 포함된 내용을 먼저 확인하세요: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -팩에 포함된 모든 정책을 카테고리별로 묶어 나열하며, 작성자가 기본으로 활성화한 항목과 선택적으로 추가해야 하는 항목을 구분해서 표시합니다. **매니페스트만** 읽으며, 진입 아티팩트는 다운로드되거나 임포트되지 않습니다. 즉, 외부 팩을 조회하더라도 외부 코드가 실행되지 않습니다. 매니페스트는 여전히 릴리즈의 `SHA256SUMS`와 대조하여 검증되므로, 표시되는 내용이 실제 설치될 내용과 동일합니다. - -소스 없이 `failproofai pack list`만 실행하면 현재 설치된 팩 목록을 확인할 수 있습니다. +이 명령은 팩에 포함된 모든 정책을 카테고리별로 나열하고, 작성자가 기본으로 활성화한 항목을 표시합니다. **매니페스트만 읽으며** — 진입 아티팩트는 다운로드되거나 임포트되지 않으므로, 낯선 팩을 조회해도 낯선 코드가 실행되지 않습니다. 매니페스트는 릴리스의 `SHA256SUMS`에 대해 검증되므로, 확인한 내용이 실제 설치될 내용과 동일합니다. -## 다른 사람의 팩 설치하기 +그런 다음 설치하세요: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -아래 형식 중 어떤 것이든 사용 가능합니다: +다음 형식 중 어느 것이든 사용할 수 있습니다: | 소스 | 결과 | | --- | --- | -| `acme/support-agent` | 최신 릴리즈, 해당 태그로 **고정** | -| `acme/support-agent@v2.1.0` | 해당 릴리즈 | -| `github:acme/support-agent@v2.1.0` | 동일한 결과, 명시적 형식 | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | 동일한 결과, 브라우저에서 복사한 URL | +| `acme/support-agent` | 최신 릴리스, 정확한 태그로 **고정** | +| `acme/support-agent@v2.1.0` | 해당 릴리스 | +| `github:acme/support-agent@v2.1.0` | 동일, 명시적 형식 | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | 동일, 브라우저에서 복사한 URL | -태그를 지정하지 않으면 최신 릴리즈가 설치되고 **고정**되며, 선택된 태그가 안내됩니다. 항상 정확히 하나의 릴리즈가 기록되므로 재설치 시 버전이 달라질 수 없습니다. +태그를 지정하지 않으면 최신 릴리스를 설치하고 **고정**한 뒤 선택된 태그를 알려줍니다. 항상 정확히 하나의 릴리스가 기록되므로 재설치 시 버전이 달라지지 않습니다. ## 팩의 일부만 가져오기 -기본적으로 팩 전체가 아닌 **작성자가 정한** 기본값, 즉 무인 환경에서도 안전하게 활성화할 수 있다고 표시된 정책만 설치됩니다. +기본적으로 팩에 포함된 전체 내용이 아닌, 작성자가 무인 실행에 안전하다고 표시한 **팩의 기본** 정책만 적용됩니다. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # 하나 또는 쉼표로 구분된 여러 개 +failproofai policies add FailproofAI/policies --category dangerous-commands # 카테고리 전체 +failproofai policies add FailproofAI/policies --all # 팩의 모든 항목 ``` -`--category`와 `--policy`는 합집합으로 결합됩니다(`--only`는 `--policy`의 동의어로 사용 가능). 새 버전으로 재설치할 때 선택한 항목은 유지되며, 나머지 항목이 다시 활성화되지 않습니다. +`--category`와 `--policy`는 합집합으로 결합됩니다(`--only`는 `--policy`의 동의어로 사용 가능). 팩이 이미 설치된 경우 이 플래그들은 기존 선택에 추가되며, 플래그 없이 비대화식으로 재추가하면(예: 업그레이드 시) 기존 선택이 유지됩니다. 터미널에서 플래그 없이 실행하면 `add`는 작성자의 기본값이 미리 선택된 피커를 열고, 선택한 항목이 기존 선택을 대체합니다. -## 활성화된 항목 관리하기 +## 활성화 상태 관리 ```bash -failproofai policies # 팩 포함, 모든 소스를 하나의 목록으로 표시 -failproofai pack list # 팩만, 카테고리별로 묶어 표시 +failproofai policies # 팩 포함, 모든 소스를 하나의 목록으로 +failproofai policies add block-rm-rf # 정책 하나 활성화 failproofai policies --uninstall block-refunds # 팩 정책 하나 비활성화 failproofai policies --install block-refunds # 다시 활성화 -failproofai pack remove acme/support-agent +failproofai policies remove acme/support-agent # 팩 제거 ``` -이름만 지정하면 해당 이름의 **내장 정책**이 있을 경우 내장 정책을 가리킵니다. 팩의 정책을 명시적으로 지정해야 할 때는 다음과 같이 입력합니다: +팩 정책의 활성화 또는 비활성화는 머신 전체에 적용됩니다. `--scope`와 관계없이 해당 설정은 프로젝트 구성이 아닌 설치된 팩과 함께 기록됩니다. + +슬래시가 없는 이름은 정책이고, 슬래시가 있는 이름은 팩 소스입니다. 슬래시 없는 이름은 해당 정책을 선언한 설치된 팩으로 해석됩니다. 설치된 두 팩이 동일한 이름을 선언하는 경우, 대상을 명확히 지정하세요: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -팩의 정책 이름이 **활성화된 내장 정책**과 동일한 경우, 내장 정책이 실행되고 팩의 복사본은 건너뜁니다. 동일한 가드가 두 번 평가되는 것을 방지하기 위함입니다. 팩의 복사본을 사용하려면 내장 정책을 비활성화하세요. - - -## Failproof AI 정책의 출처 - -`core`는 npm 패키지에 내장된 복사본을 읽습니다. 동일한 집합이 GitHub 릴리즈로도 배포되며, 특정 버전을 원할 경우 아래와 같이 설치할 수 있습니다: - -```bash -failproofai pack add core # 패키지 내장 복사본 사용, 네트워크 불필요 -failproofai pack add FailproofAI/policies # 동일한 집합, GitHub 릴리즈에서 설치 -``` +스코프, 파라미터, 이 명령들이 작성하는 파일에 대한 내용은 [로컬 구성](/ko/policies/local-configuration)에서 다룹니다. -## 무결성 검증이 보장하는 것과 보장하지 않는 것 +## 무결성 보장의 범위 -`SHA256SUMS`는 아티팩트와 동일한 릴리즈에 포함되므로 **서명이 아니며**, 게시자의 신원을 증명하지 않습니다. 검증이 보장하는 것은 해당 바이트가 릴리즈에서 배포된 것과 동일하다는 점입니다. 팩을 추가할 때 다이제스트가 기록되고 임포트 전마다 재검증되므로, 이후 팩이 변경될 수 없습니다. 리포지토리에서 태그를 변경하거나 에셋을 교체하면 팩이 조용히 다른 코드를 실행하는 대신 로드 자체가 실패합니다. +`SHA256SUMS`는 아티팩트와 동일한 릴리스에 포함되므로 **서명이 아니며** 게시자에 대한 증명이 아닙니다. 다만 바이트가 해당 릴리스에서 배포된 것임을 증명합니다. 팩을 추가할 때 다이제스트가 기록되고 임포트 전마다 재검증되므로, 이후 팩이 변조될 수 없습니다. 리포지토리가 태그를 변경하거나 에셋을 교체하면 조용히 다른 것을 실행하는 대신 로딩이 중단됩니다. -설치 시 팩은 **한 번 임포트**되어 자체 매니페스트와 대조 검증됩니다. 아티팩트가 파싱되지 않거나 선언된 것과 다른 내용을 등록하는 팩은 활성화되기 전에 거부됩니다. 깔끔하게 설치된 후 다음 도구 호출 시 실패하는 대신, 미리 차단됩니다. +설치 시 팩은 **한 번 임포트**되어 자체 매니페스트와 대조 검증됩니다. 아티팩트 파싱에 실패하거나 선언된 것과 다른 항목을 등록하려는 팩은 아무것도 활성화되기 전에 거부됩니다. 깔끔하게 설치된 후 다음 도구 호출 시 실패하는 대신, 미리 차단됩니다. -## 팩이 로드되지 않는 경우 +## 팩이 로드되지 않을 때 -이 머신에서 적용하도록 설정된 팩이 실행될 수 없는 경우, 해당 팩이 담당하던 이벤트는 자동으로 허용되는 대신 **거부**됩니다. [Failure behavior](/ko/policies/failure-behavior)를 참고하세요. `failproofai pack list`는 해당 상태의 팩 이름을 출력하고 비정상 종료 코드로 종료됩니다. +이 머신에서 적용하도록 설정된 팩이 실행되지 않을 경우, 누락된 정책이 다루던 이벤트는 조용히 허용되는 대신 **거부**됩니다 — `pack/failproofai-pack-unavailable`으로 처리되며, 이는 로드된 정책들보다 우선순위가 높아 거부가 우연히 먼저 실행된 가드가 아닌 누락된 팩에 귀속됩니다. 단, `UserPromptSubmit`는 예외로 거부 대신 지시를 내립니다. 여기서 거부하면 문제를 해결하는 데 필요한 에이전트 자체에서 잠겨버릴 수 있기 때문입니다. [오류 동작](/ko/policies/failure-behavior)을 참고하세요. -## 오프라인 환경 및 미러 +## 오프라인 및 미러 | 변수 | 효과 | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | 다운로드를 거부하며, 이미 설치된 팩은 계속 적용됨 | -| `FAILPROOFAI_PACK_BASE_URL` | 팩 다운로드를 `github.com` 대신 미러 서버로 지정 | +| `FAILPROOFAI_NO_DOWNLOAD=1` | 네트워크 요청 거부; 이미 설치된 팩은 계속 적용 | +| `FAILPROOFAI_PACK_BASE_URL` | 팩 다운로드를 `github.com` 대신 미러로 연결 | -직접 팩을 배포하는 방법은 [Publish a pack](/ko/policies/publish-a-pack)을 참고하세요. \ No newline at end of file +자신의 정책을 이 방식으로 공유하려면 [정책 팩 배포하기](/ko/policies/publish-a-pack)를 참고하세요. \ No newline at end of file diff --git a/docs/ko/policies/publish-a-pack.mdx b/docs/ko/policies/publish-a-pack.mdx index ae065bde..97d68045 100644 --- a/docs/ko/policies/publish-a-pack.mdx +++ b/docs/ko/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "팩 게시하기" -description: "나만의 정책을 GitHub 릴리스로 패키징해 누구나 설치할 수 있도록 배포합니다." +title: "정책 팩 배포하기" +description: "누구든 설치할 수 있는 GitHub 릴리스로 자신의 정책을 패키징하여 배포하세요." icon: "upload" --- -팩은 GitHub 릴리스에 첨부된 세 개의 파일로 구성됩니다. `failproofai pack build`는 기존에 작성한 정책 파일로부터 세 파일을 모두 생성합니다. +팩은 GitHub 릴리스에 첨부된 세 개의 파일로 구성됩니다. `failproofai publish`는 앞에 지정된 정책 파일들로부터 이 세 파일을 모두 작성하고, 릴리스를 생성한 후 업로드합니다. -## 1. 정책 작성 +## 1. 정책 작성하기 -커스텀 정책과 동일한 API를 사용하는 단일 파일입니다. 팩에서는 두 가지 필드가 추가로 중요합니다. +빈 템플릿 대신, 이미 동작하는 예시에서 시작하세요: + +```bash +failproofai publish --init +``` + +팩 이름을 물어본 뒤 `.mjs`를 작성하고 종료합니다 — 네트워크 접근도, git 작업도, 배포도 없습니다. 작성되는 파일에는 `git push --force`를 차단하는 정책 하나가 포함되어 있습니다. 이미 파일이 존재하면 덮어쓰지 않습니다. + +정책은 커스텀 정책과 동일한 API를 사용합니다. 팩에서 중요한 추가 필드가 두 가지 있습니다: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled`를 생략하면 기본값은 **false**입니다. 단순히 `failproofai pack add`를 실행하면 직접 표시한 정책만 활성화됩니다. 낯선 사람의 모든 정책을 무인으로 설치하는 것은 설치 도구가 사용자 대신 결정해서는 안 되는 사항입니다. +`defaultEnabled`를 생략하면 기본값은 **false**입니다. 단순히 `failproofai policies add`를 실행하면 표시된 정책만 활성화됩니다 — 모르는 사람의 모든 정책을 자동으로 설치할지 여부는 설치 도구가 사용자 대신 결정해서는 안 될 사항입니다. + +파일은 원하는 만큼 작성할 수 있습니다. 카테고리당 하나씩 작성하면 가독성이 좋습니다. 정책을 등록하는 디렉터리의 모든 파일은 팩이 가져야 할 단일 아티팩트로 번들링됩니다. -엔트리는 반드시 **자체 완결형 단일 파일**이어야 합니다. 엔트리만 다이제스트로 고정되므로, 로컬 파일을 임포트하는 팩은 다이제스트가 실제 실행 내용을 보장한다고 정직하게 주장할 수 없습니다. 먼저 번들링(`esbuild`, `bun build`, `rollup`)한 뒤 번들을 기반으로 팩을 빌드하세요 — `pack build`는 로컬 임포트가 있으면 지킬 수 없는 약속을 배포하는 대신 빌드를 거부합니다. + 번들링에는 **bun**이 필요합니다. bun 없이는 파일 하나에 모든 내용을 담으세요. 어떤 경우든 배포된 엔트리는 설치 시점에 로컬 파일을 임포트해서는 안 됩니다. 엔트리만 다이제스트로 고정되므로, 형제 파일을 참조하는 팩은 실행되는 내용이 다이제스트로 보장된다고 솔직하게 주장할 수 없습니다 — 그래서 `publish`는 이런 팩을 거부합니다. -## 2. 릴리스 에셋 빌드 +## 2. 먼저 로컬에서 테스트하기 + +다른 사람이 볼 수 있기 전에, 이 머신에서 파일을 직접 적용해 보세요: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +경로나 파일명은 자유롭게 지정할 수 있습니다. 차단한 작업을 에이전트에게 요청해서 거부되는지 확인하세요. 아직 아무것도 배포되지 않았고 다른 사람에게도 영향을 미치지 않습니다. 허용해야 할 정상적인 케이스와 엣지 케이스 테스트에 대해서는 [정책 테스트하기](/ko/policies/test)를 참고하세요. + +## 3. 배포하기 + +```bash +failproofai publish ``` -세 개의 파일을 생성하며, 모든 정책을 **로더 자체의 규칙**으로 먼저 검증합니다. 따라서 설치 자체가 불가능한 팩은 수정할 수 있는 이 단계에서 실패합니다. +어디에 배포할지, 무엇을 번들링할지, 어떤 버전으로 명명할지를 자동으로 결정하며, 저장소에서 정보를 찾을 수 없을 때만 묻습니다. 다음 순서로 진행하며, 문제가 있으면 릴리스 생성 전에 중단합니다: + +1. 파일명이 아닌 **내용**으로 정책 파일을 찾습니다 — `failproofai`를 임포트하고 `customPolicies.add`를 호출하는 파일을 찾으므로, `guards.mjs`는 찾아내고 관련 없는 `policies.mjs`는 무시합니다. 하위 디렉터리는 탐색하지 않으므로, 테스트 픽스처가 실수로 포함되지 않습니다. +2. **파일이 있는** 디렉터리에서 `git remote get-url origin`으로 저장소를 읽고 버전을 결정합니다. +3. 자격증명을 찾습니다: `GITHUB_TOKEN`, `GH_TOKEN`, 또는 `gh auth login`. 릴리스 쓰기 권한만 필요하며, 절대 출력되지 않습니다. +4. 저장소가 없으면 생성합니다. 빌드 전에 이루어지므로, 다음 단계에서 거부된 팩이 릴리스 없는 빈 저장소를 남길 수 있습니다. +5. 세 개의 에셋을 빌드하고 **로더 자체의 규칙**으로 유효성을 검사합니다 — 타인의 머신에 설치될 수 있는지 판단하는 동일한 코드를 사용하므로, 설치될 수 없는 팩은 여기서 실패합니다. 아직 수정할 수 있습니다. +6. 릴리스를 생성하거나 재사용하고 업로드하며, 같은 이름의 에셋을 교체합니다. | 파일 | 설명 | | --- | --- | -| `failproofai-pack.json` | 매니페스트: id, 버전, 효과, 정책별 엔트리 | -| `failproofai-pack.mjs` | 원본 그대로의 엔트리 파일 | +| `failproofai-pack.json` | 매니페스트: id, 버전, 효과, 정책별 항목 | +| `failproofai-pack.mjs` | 번들링된 엔트리 | | `SHA256SUMS` | 나머지 두 파일에 대한 ` ` | -빌드 시 거부되는 경우: `publisher/name` 형식이 아닌 id, `/`가 포함된 정책 이름, `alwaysOn`을 선언한 정책, `description`·`category`·`match` 누락, 아무것도 등록하지 않는 엔트리, 로컬 파일을 임포트하는 엔트리. +에셋 이름은 고정되어 있습니다 — 소비자의 CLI가 API 호출이나 디스커버리 없이 URL을 직접 구성할 때 사용하는 이름이기 때문입니다. -## 3. 릴리스에 첨부 +빌드 시 거부되는 경우: `publisher/name` 형식이 아닌 id, `/`를 포함하는 정책 이름, `alwaysOn`을 선언하는 정책, `description`/`category`/`match` 누락, 아무것도 등록하지 않는 엔트리, 로컬 파일을 임포트하는 엔트리. -빌드 시 사용한 버전과 동일한 태그로 릴리스를 생성하고 세 파일을 릴리스 에셋으로 첨부합니다. +자동으로 결정된 값을 재정의하려면: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -이제 누구나 설치할 수 있습니다. +`--id`는 저장소와 다른 경우 팩 id를 설정하고, `--tag`는 릴리스 태그를 설정하며, `--notes`는 자동 생성된 릴리스 노트를 대체합니다 — `policies show --releases`가 각 릴리스의 정책 수와 커밋 정보를 읽는 곳이기도 합니다 — `--out`은 에셋이 저장될 위치를 지정하고(기본값: `dist-pack`), `--dry-run`은 자격증명 없이 빌드만 하고 배포하지 않습니다. -```bash -failproofai pack add acme/support-agent -``` +이제 누구든 `failproofai policies add acme/support-agent`로 설치할 수 있습니다. 버전 고정 및 일부만 선택하는 방법은 [정책 팩](/ko/policies/packs)을 참고하세요. + +### 정책 허브에 등재하기 -에셋 이름은 고정되어 있습니다. 사용자의 CLI가 API 호출이나 디스커버리 없이 URL을 직접 구성하기 때문입니다. +GitHub 저장소에 `failproofai-policies` 토픽을 추가하세요. 제출 양식도 없고 승인 대기열도 없습니다: [정책 허브](https://befailproof.ai/policy-hub/)의 크롤러가 다음 순회 시 저장소를 자동으로 발견합니다. 토픽은 검토 대상으로 올리는 것에 불과하며, 실제로 등재되려면 매니페스트가 자체 `SHA256SUMS`로 검증되고 CLI가 사용하는 동일한 규칙으로 파싱되는 릴리스가 있어야 합니다 — 이것이 바로 `failproofai publish`가 생성하는 것입니다. -## 새 버전 배포 +## 버전 결정 방식 -새 `--version`으로 빌드하고, 새 릴리스에 태그를 달고, 세 에셋을 다시 첨부합니다. 사용자는 동일한 `pack add` 명령을 실행하며, 이전에 선택한 정책 조합은 그대로 유지됩니다. 끈 정책은 업그레이드 이후에도 꺼진 상태를 유지합니다. +버전은 **배포 중인 커밋** — 12자리 짧은 sha: `a1b2c3d4e5f6` 입니다. 선택할 것도, 증가시킬 것도 없으며, 버전 이름이 정확히 해당 바이트의 출처를 나타내므로 동일한 소스를 두 번 배포하면 동일한 버전이 됩니다. -정책의 **이름**을 변경하는 것은 호환성을 깨는 변경입니다. 해당 이름을 꺼둔 머신은 더 이상 존재하지 않는 이름을 끄는 셈이 되고, 새 이름은 `defaultEnabled`에 설정된 값으로 활성화됩니다. +현재 작업 트리에서 읽으며, 저장소의 릴리스 기록에서 읽지 않으므로, 새로 클론한 머신이나 에어갭 머신도 GitHub에 문의하지 않고 동일한 답을 계산합니다. + +버전이 커밋을 가리키므로 해당 커밋이 존재해야 합니다. 터미널에서 `publish`를 실행하면 자동으로 처리해 줍니다: 저장소가 없으면 초기화하고, 변경된 정책 파일을 빌드 전에 커밋합니다. 다음 상황에서는 거부하며 — `--version`을 해결책으로 안내합니다 — 터미널 없이 실행할 때(CI 러너에서 만든 커밋은 다른 곳에 존재하지 않음), 정책 파일 외의 파일이 커밋되지 않았을 때, 또는 아직 커밋이 없는 체크아웃에서. `HEAD`에 태그가 있으면 sha보다 우선합니다 — `v1.2.0`으로 태그한 사람은 이 릴리스가 무엇인지 이미 명시한 것입니다. + +sha 자체에는 순서 정보가 없으므로, `failproofai policies show / --releases`로 어떤 릴리스가 먼저 나왔는지 확인하세요 — 최신 순으로 표시됩니다. + +## 새 버전 배포하기 + +변경 사항을 커밋하고 `failproofai publish`를 다시 실행하세요 — 새 커밋이 새 버전이 됩니다. 소비자는 동일하게 `failproofai policies add`를 실행합니다. 터미널 없이, 또는 선택 플래그와 함께 실행하면 이전에 선택한 하위 집합을 유지하며, 꺼둔 정책은 꺼진 상태로 유지됩니다. 터미널에서 플래그 없이 실행하면 기본값이 미리 체크된 선택기가 열리고, 사용자의 답변이 기존 선택을 대체합니다. + +정책의 **이름**을 변경하는 것은 호환성을 깨는 변경입니다: 꺼둔 정책 이름이 더 이상 존재하지 않게 되고, 새 이름은 `defaultEnabled` 설정대로 동작합니다. ## 사용자가 신뢰하는 것 -`SHA256SUMS`는 아티팩트와 동일한 릴리스에 포함되므로 배포한 바이트가 동일함을 증명합니다 — 다만 배포자가 누구인지는 증명하지 않습니다. 저장소에 쓰기 권한이 있는 사람은 두 파일 모두 수정할 수 있습니다. 사용자를 보호하는 것은 설치 시 다이제스트가 고정된다는 점입니다. 배포 이후 파일이 변경되더라도 사용자에게 영향을 주지 않습니다. +`SHA256SUMS`는 아티팩트와 같은 릴리스에 있으므로, 배포한 바이트가 맞다는 것을 증명합니다 — 누가 배포했는지가 아닙니다. 저장소에 쓰기 권한이 있는 사람은 두 파일 모두 수정할 수 있습니다. 사용자의 보호 장치는 설치 시 다이제스트가 고정되어, 이후 배포한 내용이 변경될 수 없다는 것입니다. + +쓰기 권한을 직접 통제하는 저장소에서 배포하고, 팩 릴리스를 패키지 배포처럼 취급하세요. -쓰기 접근을 직접 통제하는 저장소에서 게시하고, 팩 릴리스를 패키지 게시와 동일하게 취급하세요. +저장소는 반드시 **공개**여야 합니다. 설치는 자격증명 없는 익명 HTTPS로 이루어지므로, 기존 비공개 저장소는 빌드나 업로드 전에 거부되며, `publish`가 생성하는 저장소도 같은 이유로 공개입니다. `--allow-private`는 세 에셋을 다른 방식으로 전달하는 경우를 위한 재정의 옵션이며, `policies add`로는 접근할 수 없음을 명시합니다. 릴리스만 중요합니다: 설치는 `releases/download//`에서 읽으며 git 트리는 절대 접근하지 않습니다. -## 적용 전 관찰 +## 적용 전 관찰 모드 사용하기 -매니페스트에 `"effect": "observe"`를 선언할 수 있습니다. 이 정책들은 실행되지만 결과는 **기록되고 폐기**됩니다 — 아무것도 차단되지 않습니다. 새 규칙을 실제 트래픽에 측정해 누군가의 작업을 방해하기 전에 검증하는 방법입니다. +매니페스트에 `"effect": "observe"`를 선언할 수 있으며 — `failproofai publish --effect observe`로 설정합니다. 이 정책들은 실행되지만 판정은 **기록만 되고 폐기됩니다** — 아무것도 차단되지 않습니다. 실제 트래픽에 대해 새 규칙을 측정한 후 실제 작업을 방해하기 전에 적용하는 방법입니다. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/ko/policies/rollback.mdx b/docs/ko/policies/rollback.mdx index a7e41484..2749e0a6 100644 --- a/docs/ko/policies/rollback.mdx +++ b/docs/ko/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "롤백" -description: "롤아웃으로 인해 정상적인 에이전트 작업이 중단된 경우, 알려진 정책 배포 상태로 복원합니다." +title: "버전과 롤백" +description: "모든 게시는 불변 버전으로 저장되므로, 유효한 에이전트 작업을 방해하는 배포는 마지막으로 정상 동작하던 버전을 재배포하여 되돌릴 수 있습니다." icon: "rotate-ccw" --- -롤백은 배포된 버전을 변경하거나 정책 할당을 제거합니다. 인시던트를 설명하는 결정 이력은 삭제되지 않습니다. +게시된 정책 버전은 절대 변경되지 않습니다. 정책을 수정하고 다시 게시하면 새로운 버전이 생성되며, 이미 머신에 배포된 버전을 덮어쓰지 않습니다. 이것이 롤백을 안전하게 만드는 이유입니다. 마지막으로 정상 동작하던 버전은 바이트 단위 그대로 존재하며, 롤백을 해도 무엇이 잘못되었는지 설명하는 의사결정 기록이 삭제되지 않습니다. -## 머신 롤백 +## 버전 찾기 - 1. **Admin → enforcement**로 이동하여 영향받은 머신을 펼치고, 마지막으로 정상 작동했던 정책 세트를 확인합니다. - 2. **edit**를 선택하고, 해당 버전과 효과를 복원한 뒤 새 배포를 적용합니다. - 3. 머신이 체크인할 때까지 기다린 후, 보고된 배포 상태를 확인합니다. - 4. **Observe → policy**와 영향받은 세션을 열어 정상적인 작업이 더 이상 차단되지 않는지 확인합니다. + **Admin → policy editor**로 이동하여 **library**를 열면 정책의 버전을 비교하거나 특정 버전을 비활성화할 수 있습니다. + + + ```bash + fp policies list # every policy version + fp policies show # one version, with its source + ``` + + + +## 머신 롤백 + + + 1. **Admin → enforcement**으로 이동하여 영향받은 머신을 펼치고, 마지막으로 정상 동작하던 정책 세트를 확인합니다. + 2. **edit**을 선택하고, 해당 버전과 효과를 복원한 뒤 새 배포를 적용합니다. + 3. 머신이 체크인할 때까지 기다린 다음, 보고된 배포 상태를 확인합니다. + 4. **Observe → policy**와 영향받은 세션을 열어 유효한 작업이 더 이상 차단되지 않는지 확인합니다. - Cloud 배포 롤백은 대시보드에서 진행하는 워크플로입니다. 로컬 상태를 통해 수정된 배포가 머신에 반영되었는지 확인할 수 있습니다: + 머신에 대한 모든 배포는 번호가 매겨진 세대(generation)로 관리됩니다. 목록을 확인하고 원하는 세대로 복원하세요: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause`는 현재 로컬 세션에서 빌트인, 커스텀, 컨벤션 정책을 일시 중지합니다. Cloud 관리 정책은 일시 중지되지 않으므로, 잘못된 Cloud 배포에 대한 임시 해결책이 될 수 없습니다. + `rollback`은 카운터를 되감는 것이 아니라 이전 정책 세트를 담은 새로운 세대를 생성하므로, 기록은 항상 추가 전용(append-only)으로 유지됩니다. 비활성화되거나 삭제된 정책을 참조하는 세대로의 롤백은 거부됩니다. `policies:write` 권한이 있는 로그인 세션이 필요합니다. `fp fleet diff `는 의도된 배포와 머신이 실제로 적용한 배포의 차이를 보여주며, 머신이 다음 번에 폴링할 때까지는 `behind`로 표시됩니다. 머신 자체에서는 `failproofai policies`를 실행하면 현재 실행 중인 배포를 확인할 수 있습니다. -## 롤백이 필요한 경우 +## 모든 머신에서 특정 정책 제거 + +```bash +fp policies disable # remove it from every deployment carrying it +fp policies enable # add it back +``` + +각 명령은 영향받는 모든 배포에 새로운 세대를 생성합니다. 단, `disable`을 취소하는 방법은 해당 세대 중 하나를 롤백하는 것이 아닙니다. `rollback`은 비활성화된 정책을 참조하는 세대를 거부하며, `disable` 이전의 모든 세대는 해당 정책을 참조하고 있기 때문입니다. 되돌리려면 `fp policies enable`을 사용해야 하며, 이 명령도 자체적인 새 세대를 생성합니다. + +## 팩 롤백 + +팩은 설치한 릴리스에 고정되므로, 롤백은 이전 버전을 설치하는 방식으로 이루어집니다: + +```bash +failproofai policies show FailproofAI/policies --releases # every version it has published, and which one is here +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # pin that one +``` + +터미널 없이 사용하거나 `--policy`, `--category`, `--all` 옵션을 사용하는 경우, 재추가 시 이전에 선택했던 서브셋이 유지됩니다. 터미널에서 해당 옵션 없이 실행하면 작성자의 기본값이 미리 선택된 상태로 선택 화면이 열리며, 선택한 항목이 기존 선택을 대체합니다. 따라서 이전에 선택했던 항목을 다시 선택해야 합니다. + +## 롤백이 필요한 상황 -- 정책이 예상된 프로덕션 작업을 차단할 때. -- 매치 횟수가 롤아웃 관찰 단계에서 예측한 수준보다 현저히 높을 때. -- 정책이 인테그레이션에서 제공하지 않는 필드에 의존할 때. -- 새 버전이 의도한 실패 모드 범위를 벗어난 동작 변경을 일으킬 때. +- 정책이 예상된 프로덕션 작업을 차단하는 경우 +- 매치 횟수가 관찰된 롤아웃 예측치보다 현저히 높은 경우 +- 정책이 연동된 시스템이 제공하지 않는 필드에 의존하는 경우 +- 새 버전이 의도된 실패 모드 외의 동작을 변경하는 경우 -롤백 후, 영향받은 세션을 열어 거짓 양성(false positive)을 유발한 조건을 파악하세요. 새 버전을 만들고 안전하지 않은 케이스와 정상적인 케이스 모두를 테스트한 다음, 관찰(observe) 단계를 다시 진행하세요. +롤백 후에는 영향받은 세션을 열어 오탐(false positive)의 원인 조건을 파악하세요. 새 버전을 게시하고, 위험한 케이스와 정상적인 케이스 모두 [테스트](/ko/policies/test)한 다음, 실제 적용하기 전에 다시 한번 관찰하세요. - 인시던트 중에 적용 강제를 일시 중지하는 것이 적절할 수 있지만, 해당 범위의 모든 활성 정책에 대한 노출이 넓어집니다. 가능하다면 특정 정책 버전만 롤백하는 방법을 우선적으로 사용하세요. + `failproofai config --pause`는 로컬 정책을 한 세션 동안만 일시 중지하며, 클라우드 관리 정책에는 적용되지 않습니다. 따라서 잘못된 클라우드 배포를 해결하는 방법으로는 사용할 수 없습니다. 또한 일시 중지는 해당 범위 내 모든 정책의 노출을 확대시키므로, 문제가 있는 특정 버전만 롤백하는 방법을 권장합니다. \ No newline at end of file diff --git a/docs/ko/policies/test.mdx b/docs/ko/policies/test.mdx new file mode 100644 index 00000000..3afcf51f --- /dev/null +++ b/docs/ko/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "정책 테스트" +description: "이미 보유한 트래픽을 기반으로 초안을 백테스트하고, 어떤 기계도 실행하기 전에 차단해야 할 것은 차단하고 허용해야 할 것은 허용함을 증명하세요." +icon: "flask-conical" +--- + +모든 정책을 두 가지 방법으로 테스트하세요. 에이전트가 이미 생성한 트래픽을 대상으로 테스트하고, 반드시 허용해야 하는 합법적인 작업을 대상으로 테스트하세요. 안전하지 않은 케이스만 테스트한 정책은 제대로 테스트된 것이 아닙니다. + +## 초안 백테스트 + + + + 정책 편집기는 게시하기 전에 이미 발생한 호출에 대해 초안을 재실행합니다. + + 1. **Admin → policy editor**에서 초안을 여세요. 편집기가 JavaScript로 파싱되는지 확인합니다. + 2. **backtest**에서 재실행할 에이전트와 시간 범위를 선택하세요. 기본값은 **every agent**와 **30d**이며, 범위를 좁히려는 경우가 아니면 마지막 필터는 **everything**으로 두세요. + 3. **run backtest**를 선택하세요. + + ![세 가지 필터와 run backtest 액션이 있는 초안 아래의 백테스트 패널, publish version 위에 표시됨.](/images/dashboard/policy-backtest.png) + + 결과는 해당 호출에 초안이 적용되었을 경우의 동작을 보여줍니다. **working** 호출 중 몇 개가 중단되었을지도 포함됩니다. 이것이 에이전트를 만나기 전에 발견된 거짓 양성입니다. 그 수가 수용 가능한 수준이 될 때까지 초안을 수정하고 다시 실행하세요. + + + 백테스팅은 대시보드 기능입니다. 터미널에서는 아래와 같이 직접 작성한 이벤트에 대해 정책을 실행하세요. + + + +## 직접 작성한 이벤트로 실행하기 + +`fp policies test`는 정책 파일을 로컬 머신에서 합성 이벤트에 대해 실행하고 결정을 확인합니다. 아무것도 게시되지 않으며 Cloud에도 전달되지 않습니다. + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +`--event`, `--tool`, `--command`, `--file`로 이벤트의 형태를 지정하세요. 정책 자체의 `match` 필터가 여전히 적용되므로, 작성한 이벤트를 커버하지 않는 정책은 결정 대신 `skipped`를 반환합니다. 이는 보통 `match` 범위가 의도보다 좁다는 신호입니다. + +## 한 대의 머신에서 실행하기 + +다음으로, 자신의 머신에서 자신의 에이전트를 대상으로 실제로 적용해 보세요. + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +첫 번째 명령은 파일을 검증하고 설치합니다. 두 번째 명령은 이곳에서 적용되는 모든 항목과 함께 로드되었음을 확인합니다. 에이전트에게 정책이 차단하는 작업을 요청하여 거부되는지 확인하고, 합법적인 작업을 요청하여 통과되는지 확인하세요. 다른 사람에게는 영향이 없습니다. + +Cloud에 연결된 머신에서는 **Observe → policy**에서 두 결정을 모두 확인하세요. 정책 이름으로 필터링한 후, 연결된 각 세션을 열어 매칭된 도구 입력과 반환된 이유를 확인하세요. + +## 오류 케이스 테스트 + +설치 시 누락된 파일, 구문 오류, 해결되지 않은 import, 최상위 예외, 또는 로딩 중 타임아웃되는 모듈이 있으면 거부됩니다. 따라서 파일이나 import하는 항목을 변경할 때마다 다시 실행하세요. 실행 시 동일하게 손상된 파일은 로그에 기록되고 **skipped** 처리되어 다른 모든 정책은 계속 실행됩니다. 프로덕션 로그에서 로드 경고를 발견하면 실행되지 않는 정책이 있다는 의미로 처리하세요. Convention 파일은 install 명령 없이 로드되므로 CI에 `failproofai policies --install --custom ` 단계를 명시적으로 추가하세요. 이것이 손상된 정책으로 인해 빌드를 실패시키는 방법입니다. + +그런 다음 예상하는 입력뿐만 아니라 에이전트가 실제로 전송하는 내용을 입력으로 사용하세요. 누락된 필드, `Write`와 `Edit` 같은 대체 도구 이름, Windows 경로, 잘못된 형식의 입력 등을 시도해보세요. 모든 경로에서 의도적인 `allow`, `instruct` 또는 `deny`를 반환하고, 함수를 결정적으로 유지하며, 외부 호출에는 짧은 타임아웃을 적용하세요. + +## 게시 후 관찰 + +백테스트는 보유한 트래픽에 정책이 어떻게 동작했을지 보여줍니다. 아직 보지 못한 트래픽이 어떻게 동작할지는 보여줄 수 없습니다. 편집기에서 **publish version**을 선택하거나 `fp policies publish`를 실행한 후, 먼저 **observe** 모드로 [배포하세요](/ko/policies/deploy). 이 모드에서는 판정이 기록되지만 아무것도 차단되지 않습니다. 매칭 결과가 안전하지 않은 작업과 유효한 작업을 명확히 구분하면 그때 적용하세요. \ No newline at end of file diff --git a/docs/ko/reference/cloud-cli.mdx b/docs/ko/reference/cloud-cli.mdx index 4fccb600..c2b03e94 100644 --- a/docs/ko/reference/cloud-cli.mdx +++ b/docs/ko/reference/cloud-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof Cloud CLI" -description: "fp를 사용한 Failproof AI Cloud 조회 및 관리를 위한 완전한 참조 가이드." +description: "fp를 사용하여 Failproof AI Cloud를 쿼리하고 관리하는 완전한 참조 가이드입니다." icon: "cloud-cog" --- -`fp`를 사용하여 Cloud 텔레메트리를 검사하고, 클라우드 관리 적용(정책, 플릿 배포, 가드레일 결정)을 관리하며, 감사, 발견 사항, 이슈, 알림, 키, 사용자, 쿼리, 설정을 관리하세요. 로컬 훅, 정책, 캡처, 머신 등록에는 [`failproofai`](/ko/reference/failproof-cli)를 사용하세요. +`fp`를 사용하여 Cloud 텔레메트리를 검사하고, 클라우드 관리형 적용(정책, 플릿 배포, 가드레일 결정)을 관리하며, 감사, 발견 사항, 이슈, 알림, 키, 사용자, 쿼리, 설정을 관리합니다. 로컬 훅, 정책, 캡처, 머신 등록에는 [`failproofai`](/ko/reference/failproof-cli)를 사용하세요. -릴리스된 Cloud CLI를 격리된 도구로 설치합니다: +배포된 Cloud CLI를 독립 도구로 설치합니다: ```bash uv tool install fp-cloud-cli @@ -20,13 +20,13 @@ fp login fp whoami ``` -## 구문 +## 문법 ```text fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` -글로벌 옵션은 커맨드 앞에 위치해야 합니다: +글로벌 옵션은 명령 앞에 와야 합니다: ```bash fp --json sessions --since 24h @@ -34,17 +34,17 @@ fp --json sessions --since 24h 터미널 도움말은 `fp COMMAND --help` 또는 `fp COMMAND SUBCOMMAND --help`를 실행하세요. -## CLI 커맨드 +## CLI 명령 ### 인증 -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | -| `fp login` | 이메일로 전송된 일회용 코드로 로그인하고 조직을 선택합니다. | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | 저장된 사용자 세션을 취소하고 삭제합니다. | — | -| `fp whoami` | 현재 신원, 인증 모드, 조직, 권한을 표시합니다. | — | +| `fp login` | 이메일 일회용 코드로 로그인하고 조직을 선택합니다. | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | 저장된 사용자 세션을 취소하고 제거합니다. | — | +| `fp whoami` | 현재 신원, 인증 모드, 조직 및 권한을 표시합니다. | — | | `fp version` | 설치된 CLI 버전을 표시합니다. | — | -| `fp help` | 최상위 커맨드 도움말을 표시합니다. | — | +| `fp help` | 최상위 명령 도움말을 표시합니다. | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,24 +57,24 @@ fp whoami fp events [OPTIONS] ``` -개별 에이전트 이벤트를 나열합니다. 기본 경량 피드는 원시 페이로드를 제외합니다; `--full`은 범위가 제한된 조사에만 사용하세요. +개별 에이전트 이벤트를 나열합니다. 기본 경량 피드는 원시 페이로드를 제외합니다. `--full`은 범위가 제한된 조사에만 사용하세요. | 옵션 | 설명 | | --- | --- | | `--limit`, `-n ` | 최대 총 행 수. 기본값: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, 또는 `7d`. | | `--from ` / `--to ` | ISO 8601 UTC 범위; `--since`를 재정의합니다. | -| `--env ` | 환경 필터; 값을 반복하거나 쉼표로 구분합니다. | -| `--event-type ` | 이벤트 유형 필터; 값을 반복하거나 쉼표로 구분합니다. | -| `--agent-id ` | 에이전트 필터; 값을 반복하거나 쉼표로 구분합니다. | -| `--session-id ` | 세션 필터; 값을 반복하거나 쉼표로 구분합니다. | -| `--search ` | 페이로드 텍스트 검색; 반복 가능하며, 임의의 용어가 일치합니다. | -| `--order asc\|desc` | 시간 정렬 순서. 기본값: 최신순. | +| `--env ` | 환경 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--event-type ` | 이벤트 유형 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--agent-id ` | 에이전트 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--session-id ` | 세션 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--search ` | 페이로드 텍스트 검색; 반복 가능하며 하나의 단어라도 일치하면 해당됩니다. | +| `--order asc\|desc` | 시간 순서. 기본값: 최신순. | | `--all` | `--limit`까지 자동 페이지네이션. | | `--cursor ` | 불투명 커서에서 재개합니다. | -| `--page-size ` | `--all` 사용 시 요청당 행 수; 최대 `200`. | +| `--page-size ` | `--all`을 사용할 때 요청당 행 수; 최대 `200`. | | `--full` | 더 무거운 이벤트 엔드포인트를 통해 원시 페이로드를 포함합니다. | -| `--fields ` | 선택한 필드만 반환합니다; `payload`를 요청하면 전체 모드가 활성화됩니다. | +| `--fields ` | 선택한 필드만 반환합니다. `payload`를 요청하면 전체 모드가 활성화됩니다. | ```bash fp events --session-id --order asc --all --limit 10000 @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all`은 기본값이 **50**인 `--limit`**까지** 페이지네이션합니다 — 따라서 `--all`만 단독으로 사용하면 50행에서 중단됩니다. 조기에 중단되면 응답에 재개를 위한 `next_cursor`가 포함됩니다; `"next_cursor": null`은 피드가 실제로 소진되었음을 의미합니다. + `--all`은 `--limit`**까지** 페이지네이션하며, 기본값은 **50**입니다. 따라서 `--all`만 단독으로 사용하면 50행에서 멈춥니다. 일찍 멈추면 응답에 재개할 수 있는 `next_cursor`가 포함됩니다. `"next_cursor": null`은 피드가 실제로 소진되었음을 의미합니다. ### 세션 @@ -96,16 +96,16 @@ fp sessions [OPTIONS] | `--limit`, `-n ` | 최대 총 행 수. 기본값: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, 또는 `7d`. | | `--from ` / `--to ` | ISO 8601 UTC 범위; `--since`를 재정의합니다. | -| `--env ` | 환경 필터; 값을 반복하거나 쉼표로 구분합니다. | -| `--status ` | `done`, `error`, 또는 `timeout`; 값을 반복하거나 쉼표로 구분합니다. | -| `--agent-id ` | 선택한 에이전트가 포함된 세션을 매칭합니다. | -| `--session-id ` | 세션 필터; 값을 반복하거나 쉼표로 구분합니다. | +| `--env ` | 환경 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--status ` | `done`, `error`, 또는 `timeout`; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--agent-id ` | 선택한 에이전트가 포함된 세션과 매칭합니다. | +| `--session-id ` | 세션 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | | `--all` | `--limit`까지 자동 페이지네이션. | | `--cursor ` | 불투명 커서에서 재개합니다. | -| `--page-size ` | `--all` 사용 시 요청당 행 수; 최대 `200`. | +| `--page-size ` | `--all`을 사용할 때 요청당 행 수; 최대 `200`. | | `--fields ` | 선택한 필드만 반환합니다. | -| `--full-ids` | 터미널 출력에서 세션 ID를 단축하지 않습니다. | -| `--agents` | 멀티 에이전트 세션의 에이전트 목록을 확장합니다. | +| `--full-ids` | 터미널 출력에서 세션 ID를 축약하지 않습니다. | +| `--agents` | 멀티 에이전트 세션의 에이전트 목록을 펼칩니다. | ### 평가 @@ -118,7 +118,7 @@ fp evals [OPTIONS] | `--aggregate` | 개별 평가 대신 총계 및 점수별 통계를 표시합니다. | | `--limit`, `-n ` | 최대 목록 행 수. 기본값: `50`. | | `--since`, `--from`, `--to` | 시간 범위를 선택합니다. | -| `--env`, `--status`, `--agent-id`, `--session-id` | 필터당 정확히 하나의 값으로 범위를 좁힙니다. | +| `--env`, `--status`, `--agent-id`, `--session-id` | 각 필터에 정확히 하나의 값으로 범위를 좁힙니다. | | `--score KEY:MIN..MAX` | 점수 범위; 반복 가능하며 모든 범위가 일치해야 합니다. | | `--all`, `--cursor`, `--page-size` | 목록 페이지네이션을 제어합니다. | | `--fields ` | 선택한 필드만 반환합니다. | @@ -137,19 +137,19 @@ fp errors [OPTIONS] | `--limit`, `-n ` | 최대 목록 행 수. 기본값: `50`. | | `--since`, `--from`, `--to` | 시간 범위를 선택합니다. | | `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | 오류 범위를 좁힙니다. | -| `--search ` | 페이로드 텍스트를 검색합니다; 반복 가능합니다. | -| `--order asc\|desc` | 시간 정렬 순서. | +| `--search ` | 페이로드 텍스트를 검색합니다; 반복 가능. | +| `--order asc\|desc` | 시간 순서. | | `--all`, `--cursor`, `--page-size` | 목록 페이지네이션을 제어합니다. | | `--fields ` | 선택한 필드만 반환합니다. | | `--full-ids` | 완전한 세션 ID를 표시합니다. | ### 사용량 및 필터 값 -| 커맨드 | 목적 | +| 명령 | 목적 | | --- | --- | -| `fp usage` | 현재 측정 기간의 사용량을 표시합니다. | -| `fp list envs` | 관측된 환경 목록을 표시합니다. | -| `fp list agents` | 관측된 에이전트 ID 목록을 표시합니다. | +| `fp usage` | 현재 계량 기간의 사용량을 표시합니다. | +| `fp list envs` | 관찰된 환경 목록을 표시합니다. | +| `fp list agents` | 관찰된 에이전트 ID 목록을 표시합니다. | | `fp list event_types` | 이벤트 유형 목록을 표시합니다. | | `fp list score_filters` | 평가 점수 키 목록을 표시합니다. | | `fp list models` | 모델 이름 목록을 표시합니다. | @@ -159,65 +159,65 @@ fp errors [OPTIONS] ### 조직 -| 커맨드 | 목적 | +| 명령 | 목적 | | --- | --- | | `fp orgs list` | 접근 가능한 조직 목록을 표시합니다. | -| `fp orgs switch [SLUG]` | 활성 조직을 저장합니다; 생략하면 프롬프트가 표시됩니다. | +| `fp orgs switch [SLUG]` | 활성 조직을 저장합니다; 생략 시 프롬프트가 표시됩니다. | | `fp orgs current` | 활성 조직을 표시합니다. | -| `fp orgs perms` | 활성 조직에서의 권한을 표시합니다. | +| `fp orgs perms` | 활성 조직에서 자신의 권한을 표시합니다. | ### API 키 -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | | `fp keys list` | 조직 키 목록을 표시합니다. | `--show-id`; `--fields ` | -| `fp keys show NAME` | 하나의 키와 해당 권한을 표시합니다. | — | -| `fp keys create NAME` | 키를 생성하고 시크릿을 한 번 표시합니다. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | 권한 세트를 교체하거나 권한을 조정합니다. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | 시크릿을 교체하고 대체 시크릿을 한 번 표시합니다. | `--yes`, `-y` | +| `fp keys show NAME` | 키 하나와 그 권한 부여 내용을 표시합니다. | — | +| `fp keys create NAME` | 키를 생성하고 비밀을 한 번 공개합니다. | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | 권한 세트를 교체하거나 권한 부여를 조정합니다. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | 비밀을 교체하고 교체된 값을 한 번 공개합니다. | `--yes`, `-y` | | `fp keys disable NAME` | 키를 영구적으로 취소합니다. | `--yes`, `-y` | -권한 토큰은 `events:add`와 같이 `resource:action` 형식을 사용합니다. `--add`를 반복하거나, 토큰을 쉼표로 구분하거나, `events:read.add`와 같이 점으로 구분된 액션을 사용하세요. +권한 토큰은 `events:add`와 같이 `resource:action` 형식을 사용합니다. `--add`를 반복하거나, 쉼표로 토큰을 구분하거나, `events:read.add`와 같이 점으로 구분된 액션을 사용할 수 있습니다. ### 쿼리 -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | | `fp query list` | 저장된 쿼리 목록을 표시합니다. | `--show-id`; `--fields ` | -| `fp query show NAME` | 하나의 쿼리를 표시합니다. | — | +| `fp query show NAME` | 쿼리 하나를 표시합니다. | — | | `fp query create NAME` | 쿼리를 저장합니다. | `--sql `; `--description` | | `fp query update NAME` | 쿼리를 업데이트하거나 이름을 변경합니다. | `--name`; `--sql`; `--description`; `--yes`, `-y` | | `fp query delete NAME` | 저장된 쿼리를 삭제합니다. | `--yes`, `-y` | | `fp query run [NAME]` | 저장된 쿼리 또는 임시 SQL을 실행합니다. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | 쿼리 가능한 테이블을 나열하거나 하나의 테이블을 검사합니다. | — | +| `fp query schema [TABLE]` | 쿼리 가능한 테이블 목록을 표시하거나 테이블 하나를 검사합니다. | — | ### 사용자 -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | -| `fp users list` | 조직 멤버 목록을 표시합니다. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | 멤버와 해당 권한을 표시합니다. | — | -| `fp users create EMAIL` | 멤버를 추가합니다. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | 멤버의 권한을 변경합니다. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users list` | 조직 구성원 목록을 표시합니다. | `--active-only`; `--show-id` | +| `fp users show EMAIL` | 구성원 하나와 그 권한 부여 내용을 표시합니다. | — | +| `fp users create EMAIL` | 구성원을 추가합니다. | `--permission-set`; `--add`; `--remove` | +| `fp users update EMAIL` | 구성원의 권한 부여를 변경합니다. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | | `fp users disable EMAIL` | 로그인을 비활성화합니다. | `--yes`, `-y` | -| `fp users enable EMAIL` | 로그인을 재활성화합니다. | `--yes`, `-y` | +| `fp users enable EMAIL` | 로그인을 다시 활성화합니다. | `--yes`, `-y` | ### 설정 -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | | `fp settings list` | 조직 설정과 현재 값 목록을 표시합니다. | — | | `fp settings schema` | 허용된 값과 설명을 표시합니다. | — | -| `fp settings set KEY` | 기존 설정을 변경합니다. | `--value`, `--json-value`, `--file` 중 정확히 하나; 선택적 `--yes`, `-y` | +| `fp settings set KEY` | 기존 설정을 변경합니다. | `--value`, `--json-value`, `--file` 중 정확히 하나; 선택적으로 `--yes`, `-y` | ### 알림 -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | | `fp alerts list` | 알림 규칙 목록을 표시합니다. | `--show-id` | -| `fp alerts show NAME` | 하나의 알림을 표시합니다. | — | +| `fp alerts show NAME` | 알림 하나를 표시합니다. | — | | `fp alerts create NAME` | 알림을 생성합니다. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | 알림을 업데이트하거나 이름을 변경합니다. | create 옵션에 `--name`; `--yes`, `-y` 추가 | +| `fp alerts update NAME` | 알림을 업데이트하거나 이름을 변경합니다. | create 옵션 추가로 `--name`; `--yes`, `-y` | | `fp alerts delete NAME` | 알림을 삭제합니다. | `--yes`, `-y` | | `fp alerts test NAME` | 테스트 알림을 전송합니다. | `--channels`; `--yes`, `-y` | @@ -225,28 +225,28 @@ fp errors [OPTIONS] ### 감사 -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | | `fp audits list` | 감사 목록을 표시합니다. | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | 하나의 감사 정의와 상태를 표시합니다. | — | +| `fp audits show NAME` | 감사 정의 하나와 상태를 표시합니다. | — | | `fp audits create NAME` | 감사를 생성하고 즉시 첫 번째 실행을 대기열에 추가합니다. | [create 옵션](#audit-create-options)을 참조하세요. | -| `fp audits edit NAME` | 지정되지 않은 값을 유지하면서 감사 설정을 교체합니다. | create 정의 옵션; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | 감사, 발견 사항, 실행 기록을 삭제합니다. | `--yes`, `-y` | +| `fp audits edit NAME` | 지정되지 않은 값은 유지하면서 감사 설정을 교체합니다. | create 정의 옵션; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | 감사, 발견 사항 및 실행 기록을 삭제합니다. | `--yes`, `-y` | | `fp audits run NAME` | 수동 실행을 대기열에 추가합니다. | — | | `fp audits runs NAME` | 실행 기록을 나열합니다. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | 브리프와 참조 URL 가져오기 상태를 표시합니다. | — | +| `fp audits context-show NAME` | 브리프 및 참조 URL 가져오기 상태를 표시합니다. | — | | `fp audits context-set NAME` | 브리프 또는 참조 URL을 변경합니다. | `--text`; `--text-file`; `--url`; `--clear-urls` | | `fp audits context-refresh NAME` | 참조 URL을 다시 가져옵니다. | — | | `fp audits findings` | 발견 사항 목록을 표시합니다. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | 하나의 발견 사항과 증거를 표시합니다. | — | +| `fp audits finding FINDING_ID` | 발견 사항 하나와 증거를 표시합니다. | — | | `fp audits ack FINDING_ID` | 발견 사항을 확인합니다. | `--reason` | | `fp audits mute FINDING_ID` | 반복되는 패턴을 억제합니다. | `--reason`; `--yes`, `-y` | | `fp audits dismiss FINDING_ID` | 패턴을 조치 불필요로 표시하고 억제합니다. | `--reason`; `--yes`, `-y` | | `fp audits resolve FINDING_ID` | 향후 억제 없이 발견 사항을 수정됨으로 표시합니다. | `--yes`, `-y` | | `fp audits reopen FINDING_ID` | 발견 사항을 활성 대기열로 되돌리고 억제를 해제합니다. | — | -| `fp audits assign FINDING_ID` | 발견 사항 소유자를 설정합니다. | 필수 `--to ` | +| `fp audits assign FINDING_ID` | 발견 사항 담당자를 지정합니다. | 필수 `--to ` | -#### Audit create options +#### 감사 create 옵션 ```bash fp audits create checkout-reliability \ @@ -261,116 +261,116 @@ fp audits create checkout-reliability \ | 옵션 | 설명 | | --- | --- | -| `--file ` | JSON을 기반으로 정의를 작성하거나, stdin에는 `-`를 사용합니다. 명시적 플래그가 파일 값을 재정의합니다. | -| `--description ` | 실패 질문 또는 목적을 기술합니다. | -| `--enabled` / `--disabled` | 스케줄링을 켜거나 끄고 시작합니다. 기본값: enabled. | +| `--file ` | JSON을 기반으로 정의하거나, stdin을 위해 `-`를 사용합니다. 명시적 플래그가 파일 값을 재정의합니다. | +| `--description ` | 장애 질문 또는 목적을 기술합니다. | +| `--enabled` / `--disabled` | 스케줄링을 켜거나 끈 상태로 시작합니다. 기본값: 활성화. | | `--schedule-interval-secs ` | `3600`–`604800`. 기본값: `86400`. | -| `--schedule-anchor ` | ISO 8601 형식의 고정 UTC 단계. 기본값: 다음 09:00 UTC. | -| `--window-mode since_last\|fixed` | 마지막으로 완전히 분석된 창 이후부터 계속하거나 롤링 창을 반복적으로 검사합니다. 기본값: `since_last`. | +| `--schedule-anchor ` | ISO 8601 형식의 고정 UTC 위상. 기본값: 다음 09:00 UTC. | +| `--window-mode since_last\|fixed` | 마지막으로 완전히 분석된 윈도우 이후부터 계속하거나 롤링 윈도우를 반복적으로 검사합니다. 기본값: `since_last`. | | `--lookback-window-secs ` | `3600`–`7776000`. 기본값: `604800`. | -| `--scope ''` | `environments`, `agent_ids` 또는 기타 지원되는 범위 필드로 필터링합니다. | +| `--scope ''` | `environments`, `agent_ids` 또는 지원되는 다른 범위 필드로 필터링합니다. | | `--ignore-error-type ` | 오류 유형을 제외합니다; 반복하거나 쉼표로 구분합니다. | -| `--llm` / `--no-llm` | 에이전틱 분석을 활성화하거나 비활성화합니다. 기본값: enabled. | +| `--llm` / `--no-llm` | 에이전트 분석을 활성화하거나 비활성화합니다. 기본값: 활성화. | | `--top-k ` | `1`–`500`개의 발견 사항을 유지합니다. 기본값: `50`. | | `--sensitivity low\|medium\|high` | 보고 민감도를 설정합니다. 기본값: `medium`. | | `--channels ''` | 알림 채널 배열. | | `--text ` | 인라인 브리프, 최대 8,192자. | -| `--text-file ` | 파일에서 브리프를 읽습니다; `--text`와 함께 사용할 수 없습니다. | -| `--url ` | 공개 HTTPS 참조를 추가합니다; 최대 다섯 번 반복 가능합니다. | +| `--text-file ` | 파일에서 브리프를 읽습니다; `--text`와 상호 배타적입니다. | +| `--url ` | 공개 HTTPS 참조를 추가합니다; 최대 5회 반복 가능합니다. | 첫 번째 실행에 컨텍스트가 필요한 경우 생성 시 포함하세요. 생성은 대기열에 추가된 실행이 시작되기 전에 정의와 컨텍스트를 함께 커밋합니다. - `fp audits run`은 비동기입니다. 발견 사항을 읽기 전에 최신 실행이 성공하거나 실패할 때까지 `fp audits runs NAME`을 폴링하세요. + `fp audits run`은 비동기입니다. 발견 사항을 읽기 전에 `fp audits runs NAME`을 폴링하여 최신 실행이 성공하거나 실패할 때까지 기다리세요. ### 이슈 -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | | `fp issues list` | 이슈 목록을 표시합니다. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | 열린 이슈 또는 선택한 이슈 상태를 계산합니다. | `--state` | -| `fp issues show INCIDENT_ID` | 이슈 세부 정보, 코멘트, 구독자, 활동을 표시합니다. | — | +| `fp issues count` | 열린 이슈 또는 선택된 이슈 상태를 카운트합니다. | `--state` | +| `fp issues show INCIDENT_ID` | 이슈 세부 정보, 댓글, 구독자 및 활동을 표시합니다. | — | | `fp issues open` | 수동 또는 알림 연결 이슈를 엽니다. | 필수 `--summary`; 선택적 `--title`, `--alert-id`, `--severity` | | `fp issues ack INCIDENT_ID` | 이슈를 확인합니다. | — | -| `fp issues assign INCIDENT_ID` | 담당자를 교체합니다; 옵션 생략 시 담당자를 초기화합니다. | 반복 가능한 `--assignee` | +| `fp issues assign INCIDENT_ID` | 담당자를 교체합니다; 옵션을 생략하면 담당자를 지웁니다. | 반복 가능한 `--assignee` | | `fp issues resolve INCIDENT_ID` | 이슈를 해결합니다. | `--yes`, `-y` | -| `fp issues comment-list INCIDENT_ID` | 코멘트 목록을 표시합니다. | — | -| `fp issues comment-add INCIDENT_ID` | 코멘트를 추가합니다. | `--body`, `--file` 중 정확히 하나 | -| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | 코멘트를 삭제합니다. | `--yes`, `-y` | +| `fp issues comment-list INCIDENT_ID` | 댓글 목록을 표시합니다. | — | +| `fp issues comment-add INCIDENT_ID` | 댓글을 추가합니다. | `--body`, `--file` 중 정확히 하나 | +| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | 댓글을 삭제합니다. | `--yes`, `-y` | | `fp issues subscribers INCIDENT_ID` | 구독자 목록을 표시합니다. | — | -| `fp issues subscribe INCIDENT_ID` | 본인 또는 다른 운영자를 구독합니다. | `--email` | +| `fp issues subscribe INCIDENT_ID` | 자신 또는 다른 운영자를 구독합니다. | `--email` | | `fp issues unsubscribe INCIDENT_ID` | 구독을 제거합니다. | `--email` | 유효한 이슈 상태는 `firing`, `acknowledged`, `resolved`입니다. 독립 이슈 심각도는 `info`, `warning`, `critical`입니다. -### 클라우드 어시스턴트 +### Cloud 어시스턴트 -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | -| `fp agent health` | 어시스턴트 가용성과 구성을 확인합니다. | — | -| `fp agent models` | 사용 가능한 어시스턴트 모델을 나열합니다. | — | +| `fp agent health` | 어시스턴트 가용성 및 구성을 확인합니다. | — | +| `fp agent models` | 사용 가능한 어시스턴트 모델 목록을 표시합니다. | — | | `fp agent chats` | 저장된 채팅 목록을 표시합니다. | — | -| `fp agent ask [MESSAGE]` | 채팅을 시작하거나 계속합니다; 메시지가 생략되면 stdin에서 읽습니다. | `--chat`; `--model`; `--page-context` | +| `fp agent ask [MESSAGE]` | 채팅을 시작하거나 계속합니다; 메시지를 생략하면 stdin에서 읽습니다. | `--chat`; `--model`; `--page-context` | | `fp agent show CHAT_ID` | 저장된 대화를 표시합니다. | — | | `fp agent rename CHAT_ID` | 대화 이름을 변경합니다. | 필수 `--title` | | `fp agent delete CHAT_ID` | 대화를 삭제합니다. | `--yes`, `-y` | ### 정책 -클라우드 관리 정책 버전. **세션 전용** — API 키 사용 시 모든 커맨드가 요청 전에 종료 코드 `2`로 종료됩니다. 이는 `/v1`에서 의도적으로 제외된 루트 전용 쓰기 경로이기 때문입니다. +클라우드 관리형 정책 버전입니다. **세션 전용** — 이 명령들은 API 키 아래에서 요청 전에 종료 코드 `2`로 종료됩니다. 이는 `/v1`에 의도적으로 없는 루트 전용 쓰기 경로이기 때문입니다. -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | | `fp policies list` | 정책 버전 목록을 표시합니다. | `--json` | -| `fp policies show POLICY_ID` | 소스와 함께 하나의 정책을 표시합니다. | — | +| `fp policies show POLICY_ID` | 소스와 함께 정책 하나를 표시합니다. | — | | `fp policies publish NAME PATH` | 로컬 `.mjs`에서 버전을 생성합니다. | `--description`; `--no-verify` | | `fp policies enable POLICY_ID` | 제거된 모든 배포에 다시 추가하고, 각 배포에서 새 세대를 생성합니다. | `--yes`, `-y` | | `fp policies disable POLICY_ID` | 이를 포함하는 모든 배포에서 제거하고, 각 배포에서 새 세대를 생성합니다. | `--yes`, `-y` | | `fp policies delete POLICY_ID` | 정책 버전을 삭제합니다. | `--yes`, `-y` | -| `fp policies test PATH` | 합성 컨텍스트에 대해 정책을 로컬에서 실행합니다. 각 정책의 `match` 필터를 적용하므로, 주어진 이벤트/도구를 다루지 않는 정책은 실행 대신 `skipped`로 보고됩니다. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | 어시스턴트를 사용하여 정책 초안을 작성합니다. `policies:write`가 필요합니다. | — | +| `fp policies test PATH` | 합성 컨텍스트에 대해 로컬에서 정책을 실행합니다. 각 정책의 `match` 필터를 적용하므로, 주어진 이벤트/도구를 다루지 않는 정책은 실행되지 않고 `skipped`로 보고됩니다. | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | 어시스턴트로 정책 초안을 작성합니다. `policies:write`가 필요합니다. | — | ### 플릿 -어떤 머신에서 어떤 정책이 실행되는지. 위와 동일한 이유로 **세션 전용**입니다. +어떤 머신에서 어떤 정책이 실행되는지를 관리합니다. **세션 전용**, 위와 같은 이유입니다. -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | -| `fp fleet list` | 등록된 머신과 배포 세대를 나열합니다. | — | +| `fp fleet list` | 등록된 머신과 그 배포 세대를 나열합니다. | — | | `fp fleet show MACHINE_ID` | 머신이 현재 실행 중인 정책 세트를 표시합니다. | — | -| `fp fleet deploy MACHINE_ID` | **머신의 전체 정책 세트를 교체합니다.** 계획을 출력하고, `--json` 없이 대화형 터미널에서만 확인을 요청합니다. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet deploy MACHINE_ID` | **머신의 전체 정책 세트를 교체합니다.** 계획을 출력하고 `--json` 없이 대화형 터미널에서만 확인을 요청합니다. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | | `fp fleet diff MACHINE_ID` | 머신을 다른 배포와 비교합니다. | — | | `fp fleet history MACHINE_ID` | 머신의 과거 배포 기록을 표시합니다. | — | -| `fp fleet rollback MACHINE_ID` | 이전 배포를 복원합니다. | `--yes`, `-y` | +| `fp fleet rollback MACHINE_ID GENERATION` | 과거 세대의 정책 세트를 새 세대로 복원합니다. | `--yes`, `-y` | | `fp fleet rename MACHINE_ID` | 머신에 읽기 쉬운 이름을 부여합니다. | 필수 `--name` | ### 가드레일 -적용이 실제로 수행한 작업. 위와 동일한 이유로 **세션 전용**입니다. +적용이 실제로 수행한 작업을 확인합니다. **세션 전용**, 위와 같은 이유입니다. -| 커맨드 | 목적 | 옵션 | +| 명령 | 목적 | 옵션 | | --- | --- | --- | -| `fp guardrails summary` | 커버리지, 차단/평가 총계, deny 스파크라인, 정책별 테이블을 표시합니다. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | 창 전체에 걸쳐 버킷화된 결정을 모든 정책 소스에 걸쳐 합산하여 표시합니다. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | 적용 범위, 차단/평가 총계, 거부 스파크라인 및 정책별 테이블을 표시합니다. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | 윈도우에 걸쳐 버킷화된 결정을 모든 정책 소스에 대해 합산하여 표시합니다. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | ## 글로벌 플래그 | 플래그 | 설명 | | --- | --- | -| `--json` | 기계 판독 가능한 JSON을 출력합니다. | +| `--json` | 기계가 읽을 수 있는 JSON을 출력합니다. | | `--base-url ` | 자체 호스팅 또는 개발 대시보드를 사용합니다. | -| `--org ` | 이번 호출에 대한 조직을 선택합니다. | +| `--org ` | 이번 호출에서 사용할 조직을 선택합니다. | | `--token ` | 저장된 사용자 세션 토큰을 재정의합니다. | | `--api-key ` | API 키로 자동화를 인증합니다; 저장되지 않습니다. | | `--timeout ` | HTTP 타임아웃; 양수여야 합니다. 기본값: `30`. | | `--quiet`, `-q` | stderr의 상태 출력을 억제합니다. | | `--no-color` | 색상 출력을 비활성화합니다. | -| `--insecure` / `--secure` | TLS 인증서 검증을 비활성화하거나 복원합니다. | -| `--version` | 패키지 버전을 출력하고 종료합니다. | +| `--insecure` / `--secure` | TLS 인증서 확인을 비활성화하거나 복원합니다. | +| `--version` | 버전을 출력하고 종료합니다. | | `--help`, `-h` | 도움말을 표시합니다. | -`--api-key`는 자동화용으로 설계되었습니다. 로그인, 조직 전환, 어시스턴트 커맨드에는 사용자 세션이 필요합니다. +`--api-key`는 자동화용입니다. 로그인, 조직 전환 및 어시스턴트 명령에는 사용자 세션이 필요합니다. ## 환경 변수 @@ -382,18 +382,18 @@ fp audits create checkout-reliability \ | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | CLI 구성 디렉토리를 재배치합니다 (기본값 `~/.failproofai/fpcli`). | +| `FP_HOME` | CLI 구성 디렉터리를 재배치합니다 (기본값 `~/.failproofai/fpcli`). | | `FP_ANALYTICS_DISABLED` 또는 `DO_NOT_TRACK` | 익명 CLI 분석을 비활성화합니다. | | `NO_COLOR` | 색상 출력을 비활성화합니다. | -명시적 플래그가 환경 변수를 재정의하고, 환경 변수는 저장된 구성을 재정의합니다. API 키 모드에서는 `--org` 또는 `FP_ORG`로 테넌트를 명시적으로 선택하세요. +명시적 플래그는 환경 변수를 재정의하며, 환경 변수는 저장된 구성을 재정의합니다. API 키 모드에서는 `--org` 또는 `FP_ORG`로 테넌트를 명시적으로 선택하세요. - 이 변수들의 `AGENTEYE_*` 형식은 **`fp`에서 읽히지 않으며** 처음부터 그런 적이 없습니다 — CLI는 `FP_*`를 선언하며 (`fp_cli/app.py`), 알 수 없는 변수는 오류가 아닙니다. `AGENTEYE_DASHBOARD_URL`을 설정해도 CLI의 대상이 변경되지 않습니다; 무시되며 커맨드는 저장된 대시보드를 대상으로 자동으로 실행됩니다. + 이 변수들의 `AGENTEYE_*` 형식은 **`fp`에서 읽히지 않으며** 처음부터 그랬습니다 — CLI는 `FP_*`를 선언하고(`fp_cli/app.py`), 알 수 없는 변수는 오류가 아닙니다. `AGENTEYE_DASHBOARD_URL`을 설정해도 CLI의 대상이 변경되지 않으며, 무시된 채 저장된 대시보드를 대상으로 명령이 자동으로 실행됩니다. - `AGENTEYE_HOME`과 `AGENTEYE_ENVIRONMENT`는 여전히 존재하지만, 이들은 **수집기 및 텔레메트리 SDK**에 속하며, 이 CLI에 속하지 않습니다. + `AGENTEYE_HOME`과 `AGENTEYE_ENVIRONMENT`는 여전히 존재하지만, 이 CLI가 아니라 **컬렉터와 텔레메트리 SDK**에 속합니다. - 삭제, 취소, 억제, 해결 또는 구성 교체를 수행하는 커맨드는 기본적으로 확인 프롬프트가 표시됩니다. `--yes`는 활성 조직과 대상을 확인한 후에만 사용하세요. + 삭제, 취소, 억제, 해결 또는 구성 교체를 수행하는 명령은 기본적으로 확인 프롬프트를 표시합니다. 활성 조직과 대상을 확인한 후에만 `--yes`를 사용하세요. \ No newline at end of file diff --git a/docs/ko/reference/custom-agents.mdx b/docs/ko/reference/custom-agents.mdx index 4a04f839..9c0c3b6d 100644 --- a/docs/ko/reference/custom-agents.mdx +++ b/docs/ko/reference/custom-agents.mdx @@ -1,17 +1,17 @@ --- title: "커스텀 에이전트" -description: "failproofai-sdk의 설정, 이벤트 카탈로그, 상관 관계 규칙 및 전달 방식." +description: "failproofai-sdk의 설정, 이벤트 카탈로그, 상관관계 규칙 및 전달 방식." icon: "python" --- -각 설정, 메서드, 필드가 하는 일을 설명합니다. 처음 계측하는 경우라면 가이드부터 시작하세요 — 이 페이지는 참조용입니다. +모든 설정, 메서드, 필드에 대한 설명입니다. 처음 계측을 시작하는 경우라면 가이드를 먼저 참조하세요 — 이 페이지는 참조용입니다. - 설치, 계측, 이벤트 메서드, 실제 예제 및 흔한 문제들. + 설치, 계측, 이벤트 메서드, 실제 예제, 그리고 자주 발생하는 문제들을 다룹니다. - LangChain, CrewAI, LlamaIndex, Pydantic AI는 호출 한 번으로 스스로 계측됩니다. + LangChain, CrewAI, LlamaIndex, Pydantic AI는 한 번의 호출로 자체 계측됩니다. @@ -23,24 +23,30 @@ Python 3.10 이상. 런타임 의존성 없음. pip install failproofai-sdk ``` -패키지는 `failproofai-sdk`로 설치되며 Python에서 `failproofai_sdk`로 임포트합니다. `failproofai-sdk[langgraph]` 같은 프레임워크 extras는 해당 프레임워크 자체를 설치하며, 어댑터는 항상 기본 wheel에 포함되어 있습니다. +패키지는 `failproofai-sdk`로 설치되며, Python에서는 `failproofai_sdk`로 임포트합니다. `failproofai-sdk[langgraph]`와 같은 프레임워크 extras는 해당 프레임워크를 함께 설치하지만, 어댑터는 항상 기본 wheel에 포함되어 있습니다. ## Failproof 데몬 연결 - 1. **Admin → Keys**로 이동하여 `events:add` 권한이 있는 키를 생성합니다. - 2. 에이전트 머신에서 [Failproof 데몬을 Cloud에 연결](/ko/start/setup#connect-a-machine-to-cloud)합니다. - 3. 계측된 세션을 한 번 실행한 후 **Observe → Events**에서 정확한 ID를 확인합니다. + 1. **Admin → Keys**로 이동하여 `events:add` 권한을 가진 키를 생성합니다. + 2. 에이전트 머신에서 [Failproof 데몬을 클라우드에 연결](/ko/start/setup#connect-a-machine-to-cloud)합니다. + 3. 계측된 세션을 한 번 실행한 후, **Observe → Events**에서 정확한 ID를 확인합니다. 4. **Observe → Sessions**으로 이동하여 동일한 환경을 선택하고 재구성된 트레이스를 엽니다. - ![실행 그래프와 정렬된 이벤트 트레이스로 재구성된 커스텀 Python 에이전트 세션.](/images/dashboard/session-detail.png) + ![커스텀 Python 에이전트 세션이 실행 그래프와 순서가 정렬된 이벤트 트레이스로 재구성된 모습.](/images/dashboard/session-detail.png) + `events:add` 키를 셸에서 읽어옵니다. `read -s`는 에코되지 않는 프롬프트에서 입력을 받으므로, 명령어나 셸 히스토리에 노출되지 않습니다. + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + 그런 다음 머신을 설정하고 연결 상태를 확인합니다. + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -61,29 +67,29 @@ failproofai_sdk.configure( | 인수 | 역할 | | --- | --- | | `environment` | 모든 이벤트에 붙는 레이블 — `production`, `staging`, `prod-eu`. 기본값은 `dev`. | -| `flush_interval` | 백그라운드 스레드가 디스크에 쓰는 주기(초). 기본값은 `0.5`. | -| `base_dir` | 쓰기 경로. 기본값은 데몬의 스풀이며, 특별한 이유가 없다면 이대로 두는 것이 좋습니다. | +| `flush_interval` | 백그라운드 스레드가 디스크에 기록하는 주기(초). 기본값은 `0.5`. | +| `base_dir` | 기록 위치. 기본값은 데몬의 스풀이며, 특별한 이유가 없다면 그대로 두는 것이 좋습니다. | -환경 변수로 설정하는 방법: +환경 변수로 설정할 수도 있습니다. | 변수 | 역할 | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | 코드 변경 없이 `environment`를 설정합니다. 레이블이 앱보다 배포 환경에 속할 때 유용합니다. `configure()` 인수가 우선 적용됩니다. | -| `FAILPROOFAI_HOME` | 스풀이 위치한 Failproof AI 루트 디렉터리를 변경합니다. | -| `FAILPROOFAI_SDK_STRICT` | `1`로 설정하면 계측 오류가 로그에 남는 대신 예외를 발생시킵니다. | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1`로 설정하면 프레임워크 호환성 문제 발생 시 경고 후 계속 진행하는 대신 예외를 발생시킵니다. | +| `AGENTEYE_ENVIRONMENT` | 코드 변경 없이 `environment`를 설정합니다. 레이블이 앱보다 배포 환경에 속하는 경우에 유용합니다. `configure()` 인수가 우선합니다. | +| `FAILPROOFAI_HOME` | 스풀을 보관하는 Failproof AI 루트 경로를 변경합니다. | +| `FAILPROOFAI_SDK_STRICT` | `1`로 설정하면 계측 오류가 로깅 대신 예외를 발생시킵니다. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1`로 설정하면 프레임워크 호환성 문제가 경고 후 계속 진행하는 대신 예외를 발생시킵니다. | - **`environment`에 쉼표를 넣지 마세요.** 수집 파이프라인은 해당 필드를 쉼표로 분리하여 필터를 구성하며, 레이블에 쉼표가 포함된 이벤트는 모두 무시됩니다 — 전체 실행이 조용히 사라질 수 있습니다. `prod,eu`가 아닌 `prod-eu`로 작성하세요. + **`environment`에 쉼표를 사용하지 마세요.** 수집 과정에서 해당 필드를 쉼표로 분리해 필터를 구성하며, 레이블에 쉼표가 포함된 이벤트는 건너뜁니다 — 결과적으로 전체 실행이 소리 없이 사라집니다. `prod,eu`가 아니라 `prod-eu`로 작성하세요. - `configure(environment="prod,eu")`는 즉시 예외를 발생시켜 바로 알 수 있습니다. `AGENTEYE_ENVIRONMENT`는 예외를 발생시킬 수 없습니다 — 호출자가 없기 때문입니다 — 그래서 한 번 경고한 후 `dev`로 폴백합니다. + `configure(environment="prod,eu")`는 즉시 예외를 발생시켜 문제를 바로 알 수 있습니다. `AGENTEYE_ENVIRONMENT`는 예외를 발생시킬 수 없습니다 — 호출 주체가 없기 때문에 — 따라서 한 번 경고를 출력하고 `dev`로 폴백합니다. -이벤트는 메모리에 큐잉되어 `flush_interval`초마다 백그라운드에서 기록되며, 인터프리터 종료 시 마지막으로 한 번 더 플러시됩니다. 프로세스가 강제 종료되면 아직 쓰이지 않은 이벤트는 손실됩니다. +이벤트는 메모리에 큐잉되었다가 `flush_interval`초마다 백그라운드에서 기록되며, 인터프리터 종료 시 최종 플러시가 이루어집니다. 프로세스가 강제 종료되면 아직 기록되지 않은 이벤트는 손실됩니다. ## 식별자 -모든 이벤트는 세션과 에이전트에 속합니다. **스코프가 두 정보를 모두 채워주므로** 직접 전달할 필요는 거의 없습니다: +모든 이벤트는 세션과 에이전트에 속합니다. **스코프가 두 가지를 모두 채워주므로**, 직접 전달하는 경우는 드뭅니다. ```python with failproofai_sdk.session(): @@ -91,17 +97,17 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -`session_id`나 `agent_id`를 명시적으로 전달해도 되며, 이 경우 전달한 값이 우선 적용됩니다. 스코프에 바인딩된 값도 없고 직접 전달하지도 않으면, Cloud가 조용히 버릴 이벤트를 방출하는 대신 `TypeError`가 발생합니다. +`session_id`나 `agent_id`를 명시적으로 전달하면 해당 값이 우선합니다. 스코프에 바인딩되지도 않고 인수도 전달하지 않으면, 클라우드가 조용히 버릴 이벤트를 내보내는 대신 `TypeError`가 발생합니다. - 식별자는 컨텍스트 변수에 저장됩니다. `asyncio` 태스크에서는 자동으로 전파되지만, **새 스레드에서는 그렇지 않습니다** — 워커를 `failproofai_sdk.propagate()`로 감싸지 않으면 해당 이벤트가 연결되지 않습니다. + 식별자는 컨텍스트 변수에 의존합니다. `asyncio` 태스크에서는 자동으로 전파되지만, **새 스레드에서는 그렇지 않습니다** — 워커를 `failproofai_sdk.propagate()`로 감싸지 않으면 해당 이벤트가 미연결 상태로 남습니다. ## 이벤트 카탈로그 -15개의 메서드가 있습니다. 대부분 **쌍으로** 구성되어 있으며 — 열기 메서드를 호출한 후 닫기 메서드를 호출하면 SDK가 그 사이의 시간을 측정합니다. +15개의 메서드가 있습니다. 대부분은 **쌍**으로 구성되어 있어, 시작 메서드를 호출한 후 종료 메서드를 호출하면 SDK가 그 사이의 시간을 측정합니다. -| | 열기 | 닫기 | +| | 시작 | 종료 | | --- | --- | --- | | **에이전트** | `agent_start` | `agent_end` | | | `agent_pause` | `agent_resume` | @@ -110,11 +116,11 @@ with failproofai_sdk.session(): | **훅** | `hook_triggered` | `hook_completed` | | **사람** | `human_wait` | `human_input` | -단독으로 사용하는 메서드 세 가지: `error`, `human_pause`, `human_interrupt`. +`error`, `human_pause`, `human_interrupt`는 단독으로 사용됩니다. -모든 메서드는 `session_id`와 `agent_id`도 받으며, 스코프가 이를 자동으로 채워줍니다. `None`으로 남겨진 값은 JSON `null`로 전송되는 대신 제외되며, 모든 메서드는 `None`을 반환합니다. +모든 메서드는 `session_id`와 `agent_id`도 받으며, 스코프가 이를 자동으로 채워줍니다. `None`으로 남겨진 값은 JSON `null`로 전송되는 대신 제거되며, 모든 메서드는 `None`을 반환합니다. | 메서드 | 필수 | 선택 | | --- | --- | --- | @@ -137,12 +143,12 @@ with failproofai_sdk.session(): - 실행을 실패로 표시하려면 `outcome`이 `failed`, `error`, `timeout`, `rejected` 중 하나여야 합니다. 그 외의 값 — 오탈자인 `"failure"` 포함 — 은 모두 성공으로 처리됩니다. + 실행을 실패로 표시하려면 `outcome`이 반드시 `failed`, `error`, `timeout`, `rejected` 중 하나여야 합니다. 아주 비슷한 `"failure"`를 포함하여 그 외의 모든 값은 성공으로 처리됩니다. -## 쌍 맞추기와 시간 측정 +## 쌍 매칭과 소요 시간 -**규칙은 하나입니다: 닫기 이벤트에 열기 이벤트와 동일한 id를 전달하세요.** 이것이 두 이벤트를 쌍으로 연결하고, SDK가 시간 간격을 측정하는 방식입니다. +**규칙은 하나입니다: 종료 이벤트에 시작 이벤트와 동일한 id를 전달하세요.** 이것이 두 이벤트를 쌍으로 묶고 SDK가 소요 시간을 측정하는 방법입니다. | 쌍 | 매칭 기준 | | --- | --- | @@ -152,46 +158,46 @@ with failproofai_sdk.session(): | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**`duration_ms`를 직접 전달하지 마세요.** SDK가 측정하며, 직접 전달하면 `ValueError`가 발생합니다. +**`duration_ms`는 직접 전달하지 마세요.** SDK가 측정하며, 전달하면 `ValueError`가 발생합니다. -단, `model_response`는 예외입니다. 실제 프로바이더 지연은 여러분만 알고 있습니다. 밀리초 단위의 정수를 전달하세요 — float를 전달하면 예외가 발생합니다. 해당 컬럼이 32비트 정수이므로 float는 빈 값으로 저장될 수 있기 때문입니다. +유일한 예외는 `model_response`로, 실제 제공자 지연 시간을 오직 사용자만 알 수 있습니다. 정수 밀리초를 전달하세요 — 해당 컬럼은 32비트 정수이므로 float를 전달하면 예외가 발생하여 값이 비어있게 됩니다. - + -- **id는 같은 종류, 같은 세션 내에서만 고유하면 됩니다.** 도구 호출과 훅이 같은 id를 공유할 수 있으며, 동시에 실행 중인 두 세션이 같은 id를 재사용해도 충돌하지 않습니다. -- **id는 에이전트에 종속되지 않습니다.** 한 에이전트에서 열고 다른 에이전트에서 닫은 쌍도 여전히 매칭됩니다 — 멀티 에이전트 코드에서는 이것이 일반적인 경우입니다. -- **`request_id`는 선택 사항이지만 권장합니다.** 없으면 모델 이벤트는 도착 순서대로 쌍이 맞춰지므로, 같은 에이전트에서 두 개의 동시 호출이 잘못 쌍을 이룰 수 있습니다. -- **프로세스를 나눠 처리된 쌍**은 Cloud에서 여전히 매칭되지만, SDK는 시간을 측정할 수 없습니다 — 어느 프로세스도 양쪽 절반을 모두 보지 못했기 때문입니다. -- **한 번에 최대 10,000개의 열기 이벤트가 닫기를 기다릴 수 있습니다.** 이를 초과하면 가장 오래된 것이 제거되므로, 누수가 있어도 무한정 증가하지 않습니다. +- **id는 종류별, 세션별로만 고유하면 됩니다.** 도구 호출과 훅이 동일한 id를 공유할 수 있으며, 동시에 실행 중인 두 세션도 id가 겹쳐도 충돌하지 않습니다. +- **id는 에이전트 범위로 한정되지 않습니다.** 한 에이전트에서 시작되고 다른 에이전트에서 종료된 쌍도 정상적으로 매칭됩니다 — 이는 멀티 에이전트 코드에서 일반적인 경우입니다. +- **`request_id`는 선택 사항이지만 권장합니다.** 없을 경우, 모델 이벤트는 도착 순서대로 쌍을 맞추므로 동일 에이전트 내에서 두 개의 동시 호출이 잘못 매칭될 수 있습니다. +- **프로세스를 가로지르는 쌍**도 클라우드에서는 매칭되지만, SDK는 시간을 측정할 수 없습니다 — 어느 프로세스도 양쪽 절반을 모두 보지 못했기 때문입니다. +- **최대 10,000개의 시작 이벤트만 종료 이벤트를 기다릴 수 있습니다.** 그 이상이 되면 가장 오래된 것이 제거되어, 누수가 무한히 커지지 않습니다. -## 사용자 정의 필드 +## 커스텀 필드 -추가로 전달하는 키워드는 이벤트와 함께 저장됩니다: +추가로 전달하는 키워드는 이벤트와 함께 저장됩니다. ```python failproofai_sdk.event.tool_use( tool_name="search", tool_call_id="c1", - fw_tenant="acme", fw_region="eu-west-1", # 사용자 정의 필드 + fw_tenant="acme", fw_region="eu-west-1", # 커스텀 필드 ) ``` -나중에 쿼리하려면 JSON 타입을 사용하세요. 그 외의 타입 — UUID, datetime, `Decimal`, set, bytes, 모델 객체 등 — 은 문자열로 저장됩니다. +나중에 쿼리하려면 JSON 타입을 사용하는 것이 좋습니다. UUID, datetime, `Decimal`, set, bytes, 모델 객체 등 그 외의 타입은 문자열로 저장됩니다. - **필드 이름에 접두사를 붙이세요.** 추가 필드는 마지막에 적용되므로, `model`, `tool_name`, `outcome`이라는 이름의 필드는 실제 값을 조용히 덮어씁니다. 프레임워크 어댑터는 `fw_`를 사용합니다; 동일하게 하면 충돌이 발생하지 않습니다. + **필드 이름에 접두사를 붙이세요.** extras는 마지막에 적용되므로, `model`, `tool_name`, `outcome`이라는 필드는 실제 값을 소리 없이 덮어씁니다. 프레임워크 어댑터는 `fw_`를 사용합니다. 동일한 방식을 따르면 충돌이 발생하지 않습니다. - 오탈자가 있는 선택 필드가 오류를 발생시키지 않는 것도 이 때문입니다 — 그냥 새로운 커스텀 필드가 됩니다. Cloud에서 표준 필드가 누락된 경우 먼저 철자를 확인하세요. + 오타가 있는 선택적 필드는 오류가 발생하지 않고 새로운 커스텀 필드가 됩니다. 클라우드에서 표준 필드가 없는 경우, 먼저 철자를 확인하세요. -다음 다섯 가지 이름은 예약되어 있어 사용이 거부됩니다: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. +다음 다섯 가지 이름은 예약되어 있으며 사용이 거부됩니다: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. -## 전달 및 확인 +## 전달 및 검증 - **Observe → Events**에서 `agent_start`가 맨 처음에, `agent_end`가 맨 마지막에 있는지 확인합니다. 그런 다음 **Observe → Sessions**을 열어 모델, 도구, 사람, 훅, 오류 이벤트가 의도한 순서대로 나타나는지 확인합니다. 세션 ID를 주요 문제 해결 키로 사용하세요. + **Observe → Events**에서 `agent_start`가 첫 번째로, `agent_end`가 마지막으로 존재하는지 확인합니다. 그런 다음 **Observe → Sessions**을 열고 모델, 도구, 사람, 훅, 오류 이벤트가 의도한 순서로 나타나는지 확인합니다. 세션 ID를 기본 문제 해결 키로 사용하세요. ```bash @@ -203,14 +209,14 @@ failproofai_sdk.event.tool_use( -Cloud가 비어 있다면 `$FAILPROOFAI_HOME/custom-agents/events`를 확인하고, 그렇지 않으면 `~/.failproofai/custom-agents/events`를 확인하세요. JSONL 파일이 있으면 SDK가 이벤트를 방출했다는 증거입니다. 스풀이 계속 늘어나면 데몬 설정이나 전달 문제를, 스풀이 비어 있으면 계측 또는 프로세스 수명 문제를 의심하세요. +클라우드가 비어있다면, `$FAILPROOFAI_HOME/custom-agents/events` 또는 `~/.failproofai/custom-agents/events`를 확인하세요. JSONL 파일이 있으면 SDK 방출이 이루어진 것이고, 스풀이 계속 커진다면 데몬 설정이나 전달 문제이며, 스풀이 비어있다면 계측이나 프로세스 수명 문제입니다. - 스풀은 데몬이 중지된 상태에서만 확인하세요. 데몬이 실행 중이면 밀리초 단위로 배치를 수집하고 삭제하므로, 디렉터리 목록 조회가 수집기와 경쟁 상태가 되어 실제로 방출된 것보다 훨씬 적은 이벤트만 보일 수 있습니다. + 데몬이 중지된 상태에서만 스풀을 검사하세요. 실행 중에는 데몬이 밀리초 단위로 배치를 수집하고 삭제하므로, 디렉터리 목록이 수집기와 경쟁하여 실제로 방출된 이벤트보다 훨씬 적은 수를 표시할 수 있습니다. -## 커스텀 런타임에서 실패 방지 +## 커스텀 런타임에서 장애 방지 -감사 결과와 연결된 트레이스를 사용하여 안전하지 않은 동작, 필요한 증거, 의도한 대응을 정의하세요. 커스텀 적용 통합은 실행 전에 동작을 노출하고, 구조화된 입력을 정책 엔진에 전달하며, 결과로 나온 allow, instruct, deny 결정을 적용해야 합니다. +감사 결과와 연결된 트레이스를 사용하여 안전하지 않은 동작, 필요한 근거, 그리고 의도된 응답을 정의하세요. 커스텀 집행 통합은 실행 전에 동작을 노출하고, 구조화된 입력을 정책 엔진에 전달하며, 결과로 나오는 allow, instruct, deny 결정을 적용해야 합니다. -[Failproof AI에 문의](mailto:support@befailproof.ai)하시면 런타임의 모델, 도구, 수명 주기 경계를 정책 훅에 매핑하고 통합을 함께 검증하는 데 도움을 드리겠습니다. \ No newline at end of file +[Failproof AI에 문의하시면](mailto:support@befailproof.ai) 런타임의 모델, 도구, 라이프사이클 경계를 정책 훅에 매핑하고 통합을 함께 검증하는 데 도움을 드리겠습니다. \ No newline at end of file diff --git a/docs/ko/reference/evaluator-sdk.mdx b/docs/ko/reference/evaluator-sdk.mdx index 0bf4bd02..587cced0 100644 --- a/docs/ko/reference/evaluator-sdk.mdx +++ b/docs/ko/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "Failproof AI 세션을 동기 또는 비동기 방식으로 채점하는 서비스를 구축합니다." +description: "자체 평가 워커를 실행하세요. LLM 판정자나 호스팅 Python으로 처리할 수 없는 모든 작업에 활용할 수 있습니다." icon: "gauge" --- -evaluator는 완료된 에이전트 세션을 수신하고, 원하는 품질 신호를 반환합니다: 수치 점수, 각 점수에 대한 설명, 그리고 선택적 요약. Failproof AI는 이 결과를 트레이스 옆에 저장하고, 에이전트 및 환경별로 차트로 시각화합니다. +Evaluator SDK는 자체 인프라에서 평가를 실행합니다. 워커가 Failproof AI에 평가를 등록하고, 세션이 완료되면 가져와서 점수를 매긴 뒤 결과를 제출합니다. 모든 통신은 아웃바운드 HTTPS로 이루어지며, 외부에서 워커로 직접 연결하는 일은 없습니다. [호스팅 Python](/ko/evaluations/write)으로 할 수 없는 작업 — LLM 판정자, 모델 호출, 패키지, 시크릿, 네트워크 접근 — 에 활용하세요. 결과는 [evaluations 페이지](/ko/sessions/evaluations)에서 호스팅 결과와 함께 **customer** 태그로 표시됩니다. -## evaluator 설정 +이 SDK는 `failproofai-sdk` 패키지의 `failproofai_sdk.evaluator` 모듈에 포함되어 있으며, 트레이싱 SDK를 임포트해도 자동으로 로드되지 않습니다. - - - SDK와 실행에 필요한 서버를 설치합니다. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - `evaluator.py`를 생성합니다. 이 예제는 세션에 실패한 도구 호출이 있는지 확인합니다. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - 공유 토큰을 설정하고, evaluator를 시작한 후 헬스 엔드포인트가 응답하는지 확인합니다. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - 다른 터미널에서: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## evaluator를 Failproof AI에 연결 +```bash +pip install failproofai-sdk +``` -1. Failproof AI Cloud에서 접근 가능한 HTTPS URL에 evaluator를 배포합니다. -2. `EVALUATOR_ENDPOINT`에 해당 URL을 설정하고, `EVALUATOR_TOKEN`을 evaluator에서 사용하는 토큰과 동일하게 설정합니다. 관리형 Cloud의 경우, 연결 설정을 위해 [support@befailproof.ai](mailto:support@befailproof.ai)로 문의하세요. -3. 평가를 실행하고, 점수가 Failproof AI에 표시되는지 확인합니다. +## 평가 작성 - - - **Observe → Sessions**에서 완료된 세션을 열고, 자동으로 평가되지 않은 경우 **Run evaluation**을 선택합니다. 세션의 **Evaluation** 패널에서 상태, 점수, 근거, 요약을 확인합니다. +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - **Observe → Evaluations**를 사용하여 에이전트 또는 환경별로 점수를 비교합니다. 지연 시간, 비용, 토큰 및 기타 수치 측정값은 **Observe → Metrics**를 사용합니다. - 먼저 하나의 세션으로 시작하여, evaluator가 해당 실행에 대해 예상된 점수 키와 유용한 근거를 반환했는지 확인합니다. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![평가 점수와 근거가 트레이스 옆에 표시된 세션 상세 보기.](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` 은 평가를 등록합니다. key는 결과가 표시될 이름이며, 로직이 변경될 때마다 version을 업데이트하면 각 결과에 생성 당시의 버전이 기록됩니다. 하나의 워커는 최대 100개의 평가를 보유할 수 있습니다. +- `result_kind` 는 별도로 지정하지 않으면 `"score"` 입니다. `"metric"` 또는 `"assertion"` 평가의 경우, `metrics` 또는 `assertions` 항목 중 하나의 이름을 key와 동일하게 지정하면 해당 항목이 결과로 사용됩니다. +- `when` 은 세션 적용 여부를 결정합니다. `ConditionResult(False, "")` 를 반환하면 해당 세션을 건너뛰고, 이유가 기록됩니다. +- 평가 함수는 일반 함수 또는 `async` 함수로 정의할 수 있으며, `timeout_seconds` 로 실행 시간을 제한할 수 있습니다. +- 페이로드 키 — 위 예시의 `tool_name`, `response`, `content` — 는 에이전트가 전송하는 값이므로, 실제 세션에서 확인하여 사용하세요. - 개별 결과가 정확한 것을 확인한 후, 평가 대시보드를 사용하여 시간 경과에 따른 점수와 에이전트 또는 환경별 점수를 비교합니다. +## 워커 실행 - ![시간 경과에 따른 evaluator 점수를 차트로 나타낸 품질 대시보드.](/images/dashboard/dashboard-quality.png) +**Administration → Keys** 에서 `evaluations:run` 권한을 가진 키를 생성하고, `FAILPROOFAI_EVALUATOR_TOKEN` 환경 변수에 설정하세요. 명령어에 직접 입력하지 말고 시크릿 저장소를 통해 설정하는 것을 권장합니다. 그런 다음 워커를 시작합니다: - 정상적인 차트는 안정적인 점수 이름을 사용해야 합니다. 키를 변경하면 별도의 시리즈가 생성됩니다. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -셀프 호스팅 Cloud 인스턴스의 경우, 서버 프로세스에 `EVALUATOR_ENDPOINT`가 설정될 때까지 자동 평가가 비활성화됩니다. evaluator 환경 변수를 변경한 후에는 서버를 재시작하세요. +`__main__` 블록 없이 사용할 경우, `python -m failproofai_sdk.evaluator evaluator:app` 으로도 동일하게 실행할 수 있습니다. -이 서비스는 `GET /health`, `GET /config`, `POST /evaluate`, 그리고 선택적으로 `GET /evaluate/{job_id}`를 노출합니다. 비동기 작업에는 `JobPending`을 반환하고, Failproof AI가 폴링할 수 있도록 `@app.job_lookup`을 등록하세요. +| 변수 | 기본값 | 설명 | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | 필수 | Failproof AI 주소: Cloud의 경우 `https://app.befailproof.ai`. 루프백을 가리키지 않는 한 HTTPS 사용 | +| `FAILPROOFAI_EVALUATOR_TOKEN` | 필수 | `evaluations:run` 권한을 가진 키 | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | 이 워커의 이름 | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | 동시에 점수를 매길 세션 수 | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Failproof AI에 대한 각 요청의 타임아웃 | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | 워커 종료 시 진행 중인 작업을 기다리는 시간 | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | 루프백이 아닌 URL에 대한 평문 HTTP 허용 — 아래 경고 참조 | +| `FAILPROOFAI_EVALUATOR_MODULE` | 없음 | `python -m failproofai_sdk.evaluator` 에 사용할 `module:attribute` | -토큰이 설정된 경우, health를 제외한 모든 라우트는 Failproof AI가 `EVALUATOR_TOKEN`으로 전송하는 동일한 bearer 토큰을 요구합니다. + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` 를 사용하면 모든 데이터가 평문으로 전송됩니다. 워커는 모든 요청의 `Authorization: Bearer` 헤더에 `FAILPROOFAI_EVALUATOR_TOKEN` 을 포함하며, 가져오는 트랜스크립트는 세션 자체입니다. 따라서 경로상의 누구든 토큰과 내용을 모두 읽을 수 있으며, 탈취된 토큰은 교체 전까지 평가 실행에 악용될 수 있습니다. 격리된 개발 네트워크에서만 사용하세요. 그 외 모든 환경에서는 URL이 HTTPS여야 하며, 루프백은 플래그 없이 사용할 수 있습니다. + -## SDK 타입 +## 결과 타입 | 타입 | 필드 | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## 데코레이터 및 라우트 - -| 데코레이터 | 라우트 | 필수 여부 | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | 필수 | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | `JobPending` 반환 시 | -| `@app.config` | `GET /config` | 선택 | - -SDK는 평가 요청 본문을 25 MiB로 제한합니다. 알 수 없는 요청 필드는 무시되므로, 이벤트 계약이 확장되어도 서비스 호환성이 유지됩니다. +| `Score` | `value` (0~1), `passed`, `unit` (기본값 `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -## 비동기 작업 반환 +`EvalResult` 는 score, metric, assertion 중 최소 하나 이상, 최대 25개까지 고유한 키로 포함해야 합니다. -평가가 단일 요청 내에서 완료될 수 없는 경우 `JobPending`을 사용합니다. job ID는 Failproof AI에 불투명하며, 결과가 수집되거나 서버 타임아웃이 만료될 때까지 서비스에서 조회 가능한 상태로 유지되어야 합니다. +## 세션 -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| 필드 또는 메서드 | 반환값 | +| --- | --- | +| `session_id`, `agent_id`, `environment` | 세션의 식별 정보 | +| `started_at`, `ended_at` | 세션 시작 및 종료 시각 | +| `event_count`, `events` | 전체 이벤트 목록 (순서 유지) | +| `count(event_type)` | 해당 타입의 이벤트 수 | +| `events_of_type(event_type)` | 해당 타입의 이벤트 목록 (순서 유지) | -폴링 주기는 다음 순서로 결정됩니다: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs`, 서버의 `EVALUATOR_POLLING_INTERVAL_SECS`. 값은 1초에서 1시간 사이로 제한됩니다. 서버의 기본 wall-clock 폴링 상한은 1시간입니다. +각 이벤트는 `id`, `ts`, `event_type`, `payload` 를 포함합니다. -## 요청 및 응답 필드 +## 레거시 Evaluator -| 필드 | 타입 | 비고 | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | 현재 `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | 세션 식별자 및 환경. | -| `started_at` | `datetime` | 첫 번째 이벤트의 타임스탬프. | -| `ended_at` | `datetime \| None` | 세션에서 종료 이벤트가 발생한 경우 존재. | -| `events` | `list[AgentEvent]` | 순서가 있는 전체 이벤트 스트림. | -| `AgentEvent.id` | `int` | 백엔드 이벤트 행 식별자. | -| `AgentEvent.ts` | `datetime` | 이벤트 타임스탬프. | -| `AgentEvent.event_type` | `str` | `tool_use` 등의 이벤트 유형. | -| `AgentEvent.payload` | `dict[str, Any]` | 전체 이벤트 페이로드. | -| `EvalResponse.scores` | `dict[str, float] \| None` | 평가에서 차트로 표시되는 수치 차원. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | 점수별 설명; 키는 `scores`와 일치해야 함. | -| `EvalResponse.summary` | `str \| None` | 전체 평가 서술. | - -## 서버 운영자 설정 - -자동 평가는 배포 전체에 적용되며, `EVALUATOR_ENDPOINT`가 없으면 비활성화 상태로 유지됩니다. - -| 변수 | 기본값 | 용도 | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | 미설정 | evaluator 서비스의 기본 URL. | -| `EVALUATOR_TOKEN` | 미설정 | `Evaluator(token=...)`과 공유하는 Bearer 토큰. | -| `EVALUATOR_WORKERS` | `2` | 동시 디스패처 워커 수. | -| `EVALUATOR_CLAIM_BATCH` | `4` | 디스패처 패스당 처리 세션 수. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | 폴백 비동기 폴링 주기. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | 요청당 evaluator 타임아웃. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | 최종 실패 전 전송 시도 횟수. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | `/config` 갱신 주기. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | 비동기 폴링 최대 wall-clock 시간. | - -서버는 배포 전역 evaluator를 사용하는 조직을 제한할 수도 있습니다. 엔드포인트, 토큰, 재시도, 조직 게이트 변경은 운영자 설정으로 처리하고, 변경 후 서버를 재시작하거나 롤링 업데이트하세요. - -## 보안 및 운영 - -- 트래픽이 신뢰할 수 없는 네트워크 경계를 넘는 경우 evaluator 앞에 HTTPS를 적용합니다. -- 비어 있지 않은 bearer 토큰을 설정하고, 두 서비스에서 동일하게 유지합니다. -- 토큰이나 요청 페이로드에 포함된 민감한 프롬프트 전체를 로그에 기록하지 마세요. -- 동기 핸들러는 멱등성을 보장하도록 작성하세요. 재시도 시 요청이 반복될 수 있습니다. -- 프로덕션 환경에서는 비동기 job 상태를 프로세스 메모리 외부에 저장하세요. -- 안정적인 점수 키를 반환하세요. 키 이름을 변경하면 기존 시리즈가 변경되는 것이 아니라 새 차트 시리즈가 생성됩니다. - -SDK는 `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected`, 핸들러 예외 등의 구조화된 라이프사이클 로그를 출력합니다. 로깅 핸들러는 자체적으로 설정하지 않으므로, 호스트 애플리케이션의 로깅 설정을 사용하세요. \ No newline at end of file +이전 Evaluator SDK — Failproof AI가 `EVALUATOR_ENDPOINT` 로 호출하고, `/evaluate` 엔드포인트에서 응답하며 `JobPending` 방식으로 폴링되는 HTTP 서비스 — 는 지원이 종료되었습니다. 새로운 평가는 이 워커 방식으로 구축하세요. 레거시 서비스를 운영 중인 셀프 호스팅 인스턴스의 운영자는 전환 기간 동안 기존 방식을 유지할 수 있습니다. \ No newline at end of file diff --git a/docs/ko/reference/failproof-cli.mdx b/docs/ko/reference/failproof-cli.mdx index 797de5f0..ddec14aa 100644 --- a/docs/ko/reference/failproof-cli.mdx +++ b/docs/ko/reference/failproof-cli.mdx @@ -4,48 +4,64 @@ description: "훅 설치, 로컬 정책 관리, Cloud 연결 및 로컬 데몬 icon: "terminal" --- -`npm install -g failproofai`로 로컬 CLI를 설치합니다. 인수 없이 실행하면 로컬 정책 대시보드가 열립니다. +`npm install -g failproofai`로 로컬 CLI를 설치하세요. 인수 없이 실행하면 로컬 정책 대시보드가 열립니다. -이 패키지는 Node.js 20.9 이상이 필요합니다. Bun 1.3 이상은 개발 및 소스 설치에서 지원됩니다. `failproofai configure`와 `failproofai setup`은 `failproofai config`의 별칭이며, `failproofai p`는 `failproofai policies`의 별칭입니다. +이 패키지는 Node.js 20.9 이상이 필요합니다. Bun 1.3 이상은 개발 및 소스 설치에서 지원됩니다. `failproofai configure`와 `failproofai setup`은 `failproofai config`의 별칭입니다. `failproofai policy`, `failproofai pack`, `failproofai p`는 모두 `failproofai policies`의 다른 표기법입니다 — 팩과 단일 정책은 한 개념에 대한 세 가지 명령이었으나 이제 하나로 통합되었습니다. 기존 표기법은 두 가지 예외를 제외하고 계속 작동합니다: `pack list `는 이제 `policies show `이고, `pack build`는 이제 `publish`입니다. ## 머신 설정 +CLI를 설치한 후 머신 키를 셸로 읽어옵니다. `read -s`는 에코되지 않는 프롬프트에서 입력을 받으므로 명령어에 키가 노출되지 않습니다: + ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +그런 다음 머신을 설정하고 적용할 정책을 선택합니다: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` +`failproofai config`는 설정의 전 과정을 담당합니다: `failproofaid` 서비스를 설치하고(루트 권한으로 한 번, `sudo -n` 사용 — 대화형 비밀번호 프롬프트 없음), 발견된 모든 에이전트 CLI에 훅을 연결하며, 키가 있으면 Cloud에 연결합니다. 터미널이 없는 환경(CI, 컨테이너, 에이전트가 구동하는 경우)에서는 묻지 않고 적용하며, 요청한 작업 중 하나라도 완료되지 않으면 종료 코드 1을 반환합니다. + +이 명령은 정책을 **선택하지 않습니다**. 그것은 두 번째 명령의 역할이며, 이 단계 없이 새로 설정된 머신은 항상 활성화된 가드 외에는 아무것도 적용하지 않습니다. + +`--token` 대신 환경 변수를 사용하는 것을 권장합니다: 명령줄 인수는 시스템의 모든 사용자가 `ps`로 읽을 수 있기 때문입니다. 환경 변수가 보호하는 것은 그것뿐입니다 — `export`를 포함하여 어떤 명령어에 키를 직접 입력하면 여전히 셸 히스토리에 남기 때문에, 위에서 `read -s`를 사용해 읽어오는 것입니다. CI에서는 시크릿 스토어에서 설정하고 셸 트레이싱(`set -x`)을 끄거나, 트레이스가 키를 출력할 수 있습니다. + + + `--connect `은 **이미 설정된** 머신을 등록합니다. 등록이 완료되는 즉시 반환합니다 — 데몬을 설치하거나 훅을 연결하지 않습니다. 아직 설정되지 않은 머신에서는 `failproofai config`(또는 `failproofai config --token `)를 사용하세요. 그렇지 않으면 연결된 것으로 표시되지만 실제로는 아무것도 수집하거나 적용하지 않습니다. + + 인수 없이 `failproofai`를 실행하면 로컬 정책 대시보드가 열립니다. | 명령어 | 결과 | | --- | --- | -| `failproofai config` | 대화형 머신 설정 실행 | -| `failproofai config --connect --token ` | Cloud 수집 및 정책 배포 연결 | -| `failproofai config --status` | 연결, 데몬, 배포, 일시 정지 상태 표시 | -| `failproofai policies` | 내장, 커스텀, 컨벤션, 팩, Cloud 관리 정책 목록 표시 | -| `failproofai policies --install` | 훅 설치 및 정책 활성화 | -| `failproofai policy add ` | 단일 정책 활성화 — 내장 정책 또는 설치된 팩의 `:` | -| `failproofai policy remove ` | 단일 정책 비활성화, 동일한 명명 방식 사용 | +| `failproofai config` | 머신 설정: 에이전트, 데몬, 키가 있으면 Cloud 연결 | +| `failproofai config --token ` | 아무것도 묻지 않고 한 번에 설정 및 연결 | +| `failproofai config --connect ` | **이미** 설정된 머신 등록 — 데몬 및 훅 없음 | +| `failproofai config --status` | 연결, 데몬, 전달, 일시 중지 상태 표시 | +| `failproofai policies` | 빌트인, 커스텀, 컨벤션, 팩, Cloud 관리 정책 목록 | +| `failproofai policies --install` | 에이전트 CLI에 훅 연결. 자체적으로는 정책을 활성화하지 않음 | +| `failproofai policies add ` | 정책 하나 활성화 — 빌트인 또는 설치된 팩의 `:` | +| `failproofai policies remove ` | 정책 하나 비활성화, 동일한 명명 방식 | | `failproofai policies --uninstall` | 정책 비활성화 또는 하네스 훅 제거 | -| `failproofai pack list` | 설치된 정책 팩과 각 팩에 포함된 모든 정책 목록 표시 | -| `failproofai pack add ` | GitHub 릴리스에서 정책 팩 설치; 태그 미지정 시 최신 버전을 가져와 고정 | -| `failproofai pack add --bundled` | 내장 정책을 팩으로 설치, 이 패키지에서 네트워크 없이 설치 | -| `failproofai pack build ` | 직접 만든 팩의 릴리스 자산 세 가지 빌드 | -| `failproofai pack remove ` | 설치된 팩 비활성화 | -| `failproofai audit` | 로컬 에이전트 기록 스캔 및 로컬 감사 뷰 열기 | -| `failproofai audit --schedule [days] --email
` | 반복 로컬 스캔 예약 및 결과를 이메일로 발송 | -| `failproofai audit --status` | 보고서 수신 주소, 간격, 다음 예약 스캔 표시 | -| `failproofai audit --no-schedule` | 감사 기록을 삭제하지 않고 반복 스캔 중지 | -| `failproofai harness list` | 추가 캡처 경로 목록 표시 | -| `failproofai flush --wait` | 현재 이벤트 스풀 전송 | -| `failproofai backfill --since 30d` | 이전에 처리된 기록 재읽기 | -| `failproofai config --pause [duration]` | 기본 30분(최대 8시간) 동안 로컬 세션 하나 일시 정지 | -| `failproofai config --resume` | 일시 정지된 로컬 세션 하나 재개; `--all`을 추가하면 모든 일시 정지 해제 | +| `failproofai policies show /` | 팩이 포함하는 내용을 매니페스트에서 읽어 설치 전에 확인 | +| `failproofai policies show / --releases` | 게시된 모든 버전과 현재 설치된 버전 | +| `failproofai policies add ` | GitHub 릴리스에서 정책 팩 설치; 태그 없이 실행하면 최신 버전을 가져와 고정 | +| `failproofai publish` | 자신의 정책을 팩으로 배포; `--init`으로 시작 템플릿 생성 | +| `failproofai policies remove ` | 팩 제거 | +| `failproofai audit` | 로컬 에이전트 히스토리 스캔 및 로컬 감사 뷰 열기 | +| `failproofai audit --schedule [days] --email
` | 주기적인 로컬 스캔 예약 및 결과를 이메일로 전송 | +| `failproofai audit --status` | 보고서 주소, 간격, 다음 예약 스캔 표시 | +| `failproofai audit --no-schedule` | 감사 히스토리를 삭제하지 않고 주기적 스캔 중단 | +| `failproofai harness list` | 추가 캡처 경로 목록 | +| `failproofai flush --wait` | 현재 이벤트 스풀 전달 | +| `failproofai backfill --since 30d` | 이전에 통과된 히스토리 재읽기 | +| `failproofai config --pause [duration]` | 로컬 세션 하나를 기본 30분(최대 8시간) 동안 일시 중지 | +| `failproofai config --resume` | 일시 중지된 로컬 세션 하나 재개; `--all`로 모든 일시 중지 해제 | | `failproofai update` | 패키지 마이그레이션 완료 및 데몬 업데이트 | | `failproofai migrate --dry-run` | 대기 중인 홈 레이아웃 마이그레이션 미리 보기 또는 실행 | | `failproofai uninstall` | 패키지 제거 전 훅 및 데몬 제거 | @@ -54,33 +70,35 @@ failproofai config --status ## 설정 플래그 -| 플래그 | 용도 | +| 플래그 | 사용법 | | --- | --- | -| `--connect --token ` | 비대화형 방식으로 연결 | -| `--machine-id ` | 고정 머신 ID 설정 | -| `--machine-label ` | 대시보드 레이블 설정 또는 변경 | -| `--no-transcripts` | 트랜스크립트 내용 없이 결정 사항만 전송 | -| `--disconnect` | Cloud 정책 가져오기 및 이벤트 전송 중지 | +| `--token ` | 비대화형으로 설정 및 연결; `FAILPROOFAI_CLOUD_TOKEN`에서도 읽음 | +| `--url ` | `app.befailproof.ai` 외 다른 곳에 연결; `FAILPROOFAI_CLOUD_URL`에서도 읽음 | +| `--connect ` | 이미 설정된 머신에서 등록만 수행. 데몬 및 모든 훅 건너뜀 | +| `--machine-id ` | 안정적인 머신 ID 설정 | +| `--machine-label ` | **이미 연결된** 머신 이름 변경. 단독으로는 설정을 실행하지 않으므로, 설정 중이 아니라 `failproofai config` 이후에 사용 | +| `--no-transcripts` | 트랜스크립트 내용 없이 결정 사항 전송 | +| `--disconnect` | Cloud 정책 풀 및 이벤트 전달 중단 | | `--status` | 현재 머신 상태 표시 | -| `--pause [duration]` | 현재 디렉터리의 최신 세션 일시 정지; 초, 분, 시간 단위를 허용하며 기본값은 30분 | -| `--resume` | 일치하는 일시 정지 조기 종료 | -| `--session ` | 일시 정지 또는 재개할 특정 세션 지정 | -| `--all` | `--resume`과 함께 사용 시 모든 활성 일시 정지 종료 | +| `--pause [duration]` | 현재 디렉토리에서 가장 최근 세션 일시 중지; 초, 분, 시간 단위 허용, 기본값 30분 | +| `--resume` | 일치하는 일시 중지 조기 종료 | +| `--session ` | 일시 중지 또는 재개할 명시적 세션 지정 | +| `--all` | `--resume`과 함께 사용 시 모든 활성 일시 중지 종료 | -로컬 일시 정지는 내장, 커스텀, 컨벤션, 팩 정책을 한 세션 동안 중단합니다. 항상 만료되며 Cloud 관리 정책은 비활성화하지 않습니다. `block-failproofai-commands`는 항상 켜져 있으며 비활성화하거나 일시 정지할 수 없습니다. 이를 통해 계측된 에이전트가 이 탈출구를 직접 사용하는 것을 방지합니다. +로컬 일시 중지는 한 세션에 대해 빌트인, 커스텀, 컨벤션, 팩 정책을 중단합니다. 항상 만료되며 Cloud 관리 정책은 비활성화하지 않습니다. `block-failproofai-commands` — 항상 활성화되어 있으며 비활성화하거나 일시 중지할 수 없음 — 는 에이전트가 이 탈출 수단을 직접 사용하는 것을 방지합니다. ## 정책 플래그 -| 플래그 | 용도 | +| 플래그 | 사용법 | | --- | --- | -| `--install`, `-i` | 정책 활성화 및 하네스 훅 설치 | +| `--install`, `-i` | 하네스 훅 설치. 이후에 오는 이름은 해당 정책을 활성화하며, 없으면 정책 변경 없음 | | `--uninstall`, `-u` | 정책 비활성화 또는 훅 제거 | -| `--cli ` | 하나 이상의 지원 하네스 대상 지정 | -| `--scope user\|project\|local\|all` | 설정 범위 선택; `all`은 제거 시 사용 | +| `--cli ` | 지원되는 하네스 하나 이상 지정 | +| `--scope user\|project\|local\|all` | 설정 범위 선택; `all`은 제거용 | | `--beta` | 베타 정책 포함 | -| `--custom`, `-c ` | 커스텀 정책 파일 유효성 검사 및 로드; 반복 사용 가능 | +| `--custom`, `-c ` | 커스텀 정책 파일 유효성 검사 및 로드; 반복 가능 | -## 전송 및 유지 관리 플래그 +## 전달 및 유지 관리 플래그 | 명령어 | 플래그 | | --- | --- | @@ -90,7 +108,7 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update`는 `npm install -g failproofai@latest` 실행 후에 실행해야 합니다. 홈 레이아웃 마이그레이션을 수행하고, 일치하는 데몬 바이너리를 설치하며, 서비스를 재시작합니다. `--no-daemon`은 레이아웃 마이그레이션만 수행합니다. +`failproofai update`는 `npm install -g failproofai@latest` 이후에 실행해야 합니다; 홈 레이아웃 마이그레이션을 수행하고, 일치하는 데몬 바이너리를 설치하며, 서비스를 재시작합니다. `--no-daemon`은 레이아웃 마이그레이션만 수행합니다. ## 하네스 경로 @@ -102,9 +120,9 @@ failproofai harness remove-path 지원되는 하네스 이름은 `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`입니다. -레이블은 두 루트에 동일한 프로젝트 사본이 있을 때 파생된 에이전트 ID의 네임스페이스를 구분합니다. 중복 수집이나 커서 손상을 방지하기 위해 겹치는 루트와 중복 레이블은 거부됩니다. 추가 경로 설정은 데몬 재시작 없이 다시 로드됩니다. +레이블은 두 루트에 동일한 프로젝트 복사본이 있을 때 파생된 에이전트 ID의 네임스페이스를 구분합니다. 겹치는 루트와 중복 레이블은 중복 수집이나 커서 손상을 방지하기 위해 거부됩니다. 추가 경로 설정은 데몬 재시작 없이 다시 로드됩니다. -컨테이너 환경에서는 파일로 설정된 추가 경로를 `FAILPROOFAI__EXTRA_PATHS`라는 쉼표로 구분된 변수로 대체할 수 있습니다. 예를 들면: +컨테이너 환경에서는 `FAILPROOFAI__EXTRA_PATHS`라는 이름의 쉼표로 구분된 변수로 파일에 설정된 추가 경로를 대체할 수 있습니다. 예를 들면: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -114,12 +132,14 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl 지속적인 머신 동작에는 설정 파일을 사용하세요. 환경 변수는 컨테이너, 테스트, 단일 프로세스에 가장 유용합니다. -| 변수 | 용도 | +| 변수 | 사용법 | | --- | --- | -| `FAILPROOFAI_HOME` | `~/.failproofai` 전체 레이아웃 재배치 | +| `FAILPROOFAI_CLOUD_TOKEN` | `--token` 대신 Cloud 키. 이 방법을 권장합니다: 인수는 모든 사용자가 `ps`로 읽을 수 있습니다. `read -s`나 CI 시크릿 스토어에서 설정하고, 절대로 명령어에 직접 입력하지 마세요 — 어떤 방식이든 셸 히스토리에 남습니다 | +| `FAILPROOFAI_CLOUD_URL` | `--url` 대신 Cloud URL. 데몬이 읽는 동일한 변수 | +| `FAILPROOFAI_HOME` | 전체 `~/.failproofai` 레이아웃 재배치 | | `FAILPROOFAI_LOG_LEVEL` | 로컬 로깅 상세도 설정 | -| `FAILPROOFAI_HOOK_LOG_FILE` | 훅 진단 정보를 지정한 파일에 기록 | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 이 프로세스의 익명 텔레메트리 비활성화 | +| `FAILPROOFAI_HOOK_LOG_FILE` | 선택한 파일에 훅 진단 기록 | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 이 프로세스에 대한 익명 텔레메트리 비활성화 | | `FAILPROOFAI_NO_FIRST_RUN=1` | 대화형 최초 실행 설정 건너뜀 | | `FAILPROOFAI_NO_AUTO_AUDIT=1` | 설정 후 로컬 감사 건너뜀 | | `FAILPROOFAI_LLM_BASE_URL` | LLM 정책에서 사용하는 OpenAI 호환 엔드포인트 재정의 | @@ -128,12 +148,12 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl | `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | 커스텀 정책 모듈 로딩 시간 제한 | | `FAILPROOFAI_NO_DOWNLOAD=1` | 팩 및 데몬 바이너리 가져오기 거부; 설치된 항목은 계속 적용됨 | | `FAILPROOFAI_PACK_BASE_URL` | `github.com` 대신 미러에서 팩 가져오기 | -| `FAILPROOFAI__EXTRA_PATHS` | 특정 하네스에 대해 설정된 추가 캡처 경로 대체 | -| `NO_COLOR` | 터미널 색상 출력 비활성화 | +| `FAILPROOFAI__EXTRA_PATHS` | 하나의 하네스에 대해 설정된 추가 캡처 경로 대체 | +| `NO_COLOR` | 색상 터미널 출력 비활성화 | -`CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, `OPENCLAW_HOME`과 같은 에이전트별 홈 변수는 Failproof AI가 해당 하네스의 로컬 세션을 검색하는 위치를 재정의합니다. +`CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, `OPENCLAW_HOME`과 같은 에이전트별 홈 변수는 Failproof AI가 해당 하네스의 로컬 세션을 탐색하는 위치를 재정의합니다. -## 머신을 안전하게 일시 정지하거나 제거하기 +## 머신 안전하게 일시 중지 또는 제거 ```bash failproofai config --pause @@ -141,7 +161,7 @@ failproofai config --status failproofai config --resume ``` -로컬 세션 일시 정지는 Cloud 관리 정책을 비활성화하지 않습니다. 롤아웃 자체가 문제인 경우 Cloud 적용 워크플로우를 통해 Cloud 배포를 복원하세요. +로컬 세션 일시 중지는 Cloud 관리 정책을 비활성화하지 않습니다. 롤아웃 자체가 문제인 경우 Cloud 적용 워크플로를 통해 Cloud 배포를 복원하세요. npm 패키지를 제거하기 전에 설치된 훅과 데몬을 먼저 제거하세요: @@ -154,5 +174,5 @@ npm rm -g failproofai 버전별 세부 정보는 `failproofai --help`를 실행하세요. - `npm rm -g failproofai` 전에 반드시 `failproofai uninstall`을 실행하세요. npm은 설치된 에이전트 훅이나 데몬 서비스를 제거하지 않습니다. + `npm rm -g failproofai` 전에 `failproofai uninstall`을 실행하세요; npm은 설치된 에이전트 훅이나 데몬 서비스를 제거하지 않습니다. \ No newline at end of file diff --git a/docs/ko/reference/harnesses.mdx b/docs/ko/reference/harnesses.mdx index a23fe207..36b7a4ad 100644 --- a/docs/ko/reference/harnesses.mdx +++ b/docs/ko/reference/harnesses.mdx @@ -1,17 +1,17 @@ --- title: "에이전트 하네스" -description: "지원되는 12가지 에이전트 하네스 전반에 걸쳐 세션을 캡처하고 정책을 적용합니다." +description: "지원되는 12개 에이전트 하네스 전반에 걸쳐 세션을 캡처하고 정책을 적용합니다." icon: "plug-zap" --- -하네스(harness)는 에이전트가 실제로 실행되는 환경을 의미합니다. Failproof AI는 두 가지 유형으로 나뉘는 12가지 하네스를 지원합니다. +하네스란 에이전트가 실제로 실행되는 환경을 의미합니다. Failproof AI는 두 가지 범주로 나뉜 12개의 하네스를 지원합니다. - **코딩 CLI** (10개) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **채팅 및 어시스턴트 게이트웨이** (2개) — Hermes (Slack, Telegram, cron), OpenClaw (셀프 호스팅 어시스턴트) +- **채팅 및 어시스턴트 게이트웨이** (2개) — Hermes (Slack, Telegram, cron), OpenClaw (자체 호스팅 어시스턴트) -에이전트가 어떤 하네스에서 실행되든 동일한 정책과 동일한 세션 기록이 적용됩니다. 어댑터 레이어 하나가 각 하네스의 고유 이벤트 이름, 툴 이름, 툴 입력 필드를 정책 실행 전에 29개의 표준 이벤트로 매핑합니다. +에이전트가 어떤 하네스에서 실행되든 동일한 정책과 동일한 세션 히스토리가 적용됩니다. 하나의 어댑터 레이어가 각 하네스의 네이티브 이벤트 이름, 툴 이름, 툴 입력 필드를 정책이 실행되기 전에 29개의 표준 이벤트로 매핑합니다. -12가지 하네스 중 **어느 것도** 사용하지 않는 에이전트는 [Python SDK](/ko/reference/custom-agents)를 통해 직접 계측됩니다. 이 경우에는 계약 내용이 다르므로 명확히 짚어 둘 필요가 있습니다. SDK는 트레이싱, 세션, 평가 및 감사를 제공하지만 **정책을 자체적으로 적용하지는 않습니다.** 실행 전에 안전하지 않은 작업을 차단하려면 런타임의 툴 경계에 실행 훅이 필요합니다. [문의하기](mailto:support@befailproof.ai)를 통해 연락주시면 매핑을 도와드리겠습니다. +12개 중 **어느 하네스에도** 속하지 않는 에이전트는 [Python SDK](/ko/reference/custom-agents)를 통해 직접 계측됩니다. 이는 별개의 계약이므로 명확히 짚고 넘어갈 필요가 있습니다. SDK는 트레이싱, 세션, 평가, 감사 기능을 제공하지만 **정책을 자체적으로 적용하지는 않습니다.** 툴이 실행되기 전에 안전하지 않은 동작을 차단하려면 런타임의 툴 경계에 실행 훅이 필요합니다. [문의하기](mailto:support@befailproof.ai)를 통해 연락 주시면 매핑해 드리겠습니다. | 하네스 | 지원되는 훅 스코프 | | --- | --- | @@ -20,61 +20,67 @@ icon: "plug-zap" | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -각 통합은 정책 실행 전에 고유 훅 이벤트 이름, 툴 이름, 툴 입력 필드를 정규화합니다. 정책은 해당 하네스가 노출하는 이벤트에만 작동할 수 있으므로, 실제로 배포하는 하네스와 버전에서 턴 종료 및 명령 동작을 직접 테스트하세요. +각 통합은 정책이 실행되기 전에 네이티브 훅 이벤트 이름, 툴 이름, 툴 입력 필드를 정규화합니다. 정책은 해당 하네스가 노출하는 이벤트에만 적용될 수 있으므로, 실제로 배포하는 하네스와 버전에서 직접 턴 종료 및 명령 동작을 테스트하시기 바랍니다. -## 적용 기능 +## 적용 가능 범위 -"차단(Block)"이란 현재 어댑터가 반환한 판정을 해당 하네스가 소비함을 의미합니다. 툴 사후 차단은 모델에 표시되는 결과를 대체할 수 있지만, 이미 발생한 툴 부작용을 되돌릴 수는 없습니다. +"차단(Block)"은 현재 어댑터가 반환한 판정(verdict)이 해당 하네스에 의해 처리됨을 의미합니다. 툴 실행 후(post-tool) 차단은 모델에게 표시되는 결과를 대체할 수 있지만, 이미 발생한 툴 부작용을 되돌릴 수는 없습니다. -| 하네스 | 검증된 차단 이벤트 | 관찰 전용 또는 비차단 주의 사항 | +| 하네스 | 검증된 차단 이벤트 | 관찰 전용 또는 비차단 주의사항 | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, 그 외 여러 태스크/설정 이벤트 | `PostToolUse`, 세션 라이프사이클, 알림, 실패 후 이벤트는 관찰용입니다. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | 툴 사후 차단은 실행 후 결과를 대체합니다. 세션 시작 및 compact 이벤트는 현재 어댑터에서 관찰용입니다. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | 툴 사후 차단은 실행 후 결과를 대체합니다. 세션 및 알림 이벤트는 관찰용입니다. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` 및 세션 이벤트는 관찰용입니다. | -| OpenCode | `PreToolUse` | 툴 사후 및 라이프사이클 이벤트는 관찰용입니다. 현재 stop 처리는 검증된 게이트가 아닌 다음 턴에 대한 안내입니다. | -| Pi | `PreToolUse`, `UserPromptSubmit` | 툴 사후 및 라이프사이클 이벤트는 관찰용입니다. stop 안내는 다음 턴에 적용됩니다. | -| Hermes | `PreToolUse` | 툴 사후, 세션, 서브에이전트 stop 판정은 게이트 역할을 하지 않습니다. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | 툴 사후, 세션, 서브에이전트 stop, compaction 이벤트는 관찰용입니다. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | 툴 사후 및 서브에이전트 stop 판정은 관찰용입니다. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, 조건부 `PermissionRequest` | 권한 훅은 모든 권한 모드에서 실행되지 않습니다. 툴 사후 및 세션 이벤트는 관찰용입니다. | -| Antigravity CLI | `PreToolUse`, `Stop` | 사용자 프롬프트 및 툴 사후 판정은 관찰용입니다. 프롬프트 명령은 여전히 주입될 수 있습니다. | -| Goose | `PreToolUse` | 사용자 프롬프트, 툴 사후, 세션 이벤트는 관찰용입니다. 업스트림에 네이티브 차단 stop 훅이 존재하지만 현재 어댑터에서는 설치되지 않습니다. | - -기능은 버전에 따라 달라질 수 있습니다. 특히 정책이 공통 사전 툴 게이트가 아닌 프롬프트, stop, 권한, 또는 툴 사후 동작에 의존하는 경우, 에이전트 CLI 업그레이드 후 재테스트하세요. +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` 및 여러 태스크/설정 이벤트 | `PostToolUse`, 세션 라이프사이클, 알림, 실패 후 이벤트는 관찰용입니다. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | 툴 실행 후 차단은 실행 완료 후 결과를 대체합니다. 세션 시작 및 컴팩트 이벤트는 현재 어댑터에서 관찰 전용입니다. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | 툴 실행 후 차단은 실행 완료 후 결과를 대체합니다. 세션 및 알림 이벤트는 관찰 전용입니다. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` 및 세션 이벤트는 관찰 전용입니다. | +| OpenCode | `PreToolUse` | 툴 실행 후 및 라이프사이클 이벤트는 관찰 전용입니다. 현재 stop 처리는 검증된 게이트가 아닌 다음 턴에 대한 안내입니다. | +| Pi | `PreToolUse`, `UserPromptSubmit` | 툴 실행 후 및 라이프사이클 이벤트는 관찰 전용입니다. stop 안내는 다음 턴에 적용됩니다. | +| Hermes | `PreToolUse` | 툴 실행 후, 세션, 서브에이전트 stop 판정은 게이트로 작동하지 않습니다. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | 툴 실행 후, 세션, 서브에이전트 stop, 컴팩션 이벤트는 관찰 전용입니다. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | 툴 실행 후 및 서브에이전트 stop 판정은 관찰 전용입니다. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, 조건부 `PermissionRequest` | 권한 훅은 모든 권한 모드에서 실행되지 않습니다. 툴 실행 후 및 세션 이벤트는 관찰 전용입니다. | +| Antigravity CLI | `PreToolUse`, `Stop` | 사용자 프롬프트 및 툴 실행 후 판정은 관찰 전용입니다. 프롬프트 지침은 여전히 주입될 수 있습니다. | +| Goose | `PreToolUse` | 사용자 프롬프트, 툴 실행 후, 세션 이벤트는 관찰 전용입니다. 네이티브 차단 stop 훅이 업스트림에 존재하지만 현재 어댑터에는 설치되어 있지 않습니다. | + +기능은 버전에 따라 달라질 수 있습니다. 에이전트 CLI를 업그레이드한 후에는, 특히 정책이 공통 프리툴 게이트가 아닌 프롬프트, stop, 권한, 또는 툴 실행 후 동작에 의존하는 경우 반드시 재테스트하시기 바랍니다. ## 캡처 및 정책 훅 설치 - 1. **Administration → Keys**를 열고 해당 머신 또는 환경 이름으로 `events:add` 및 `policies:pull` 권한이 있는 키를 생성합니다. + 1. **Administration → Keys**를 열고 `events:add` 및 `policies:pull` 권한을 가진 키를 생성하고, 머신 또는 환경에 맞는 이름을 붙입니다. 2. 대상 머신에서 표시된 키로 로컬 CLI를 연결하고 하네스 훅을 설치합니다. - 3. 새 에이전트 세션을 시작한 후, **Observe → Events**에서 훅과 세션 이벤트를 확인합니다. - 4. 동일한 시간 범위에서 **Observe → policy**를 열고 해당 머신에 정책 결정이 귀속되는지 확인합니다. + 3. 새 에이전트 세션을 시작한 후 **Observe → Events**에서 해당 훅 및 세션 이벤트를 확인합니다. + 4. 동일한 시간 범위의 **Observe → policy**를 열고 정책 결정이 해당 머신에 귀속되는지 확인합니다. - 연결은 머신 키로 시작됩니다. 시크릿을 복사하기 전에 인제스션 및 정책 전달 권한이 모두 포함되어 있는지 확인하세요. + 연결은 머신 키로 시작됩니다. 시크릿을 복사하기 전에 수집 및 정책 전달 권한이 모두 포함되어 있는지 확인하세요. - ![이벤트 인제스션 및 정책 전달 권한을 부여하는 데 사용되는 새 API 키 드로어.](/images/dashboard/key-create.png) + ![이벤트 수집 및 정책 전달 권한을 부여하는 새 API 키 드로어.](/images/dashboard/key-create.png) - 훅을 설치한 후, Events 스트림에서 연결한 머신과 환경의 새 이벤트가 표시되어야 합니다. + 훅을 설치한 후, Events 스트림에 연결한 머신 및 환경의 새 이벤트가 표시되어야 합니다. - ![새로 설치된 하네스가 보고 중인지 확인하는 데 사용되는 실시간 Events 스트림.](/images/dashboard/events-stream.png) + ![새로 설치된 하네스가 보고 중인지 확인하는 라이브 Events 스트림.](/images/dashboard/events-stream.png) 마지막으로, 정책 결정이 동일한 머신에 귀속되는지 확인합니다. 이를 통해 하네스가 트레이스 이벤트뿐만 아니라 정책 활동도 보고하고 있음을 확인할 수 있습니다. - ![새로 연결된 하네스의 정책 결정을 확인하는 데 사용되는 Policy 페이지.](/images/dashboard/policy-observe.png) + ![새로 연결된 하네스의 정책 결정을 검증하는 Policy 페이지.](/images/dashboard/policy-observe.png) - 감지된 모든 하네스에 훅을 설치합니다: + 머신 키를 셸로 읽어옵니다. `read -s`는 에코되지 않는 프롬프트에서 키를 입력받으므로 커맨드나 셸 히스토리에 절대 남지 않습니다. ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - 또는 특정 하네스와 설정 스코프를 지정합니다: + 그런 다음 머신을 설정합니다. 이 과정에서 감지된 모든 하네스에 훅을 연결하고, 데몬을 설치하며, Cloud에 연결합니다. + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + 설정 자체는 어떠한 정책도 활성화하지 않으며, 두 번째 명령이 그 역할을 합니다. + + 또는 특정 하네스와 설정 스코프를 지정할 수 있습니다. ```bash failproofai policies --install \ @@ -82,9 +88,9 @@ icon: "plug-zap" --scope user ``` - Project 스코프는 훅 설정을 저장소와 함께 유지합니다. User 스코프는 저장소 전반의 작업을 포괄합니다. Claude Code는 local 스코프도 지원하며, 지원 여부는 하네스에 따라 다르고 CLI는 지원되지 않는 조합을 거부합니다. + 프로젝트 스코프는 훅 설정을 리포지토리와 함께 유지합니다. 유저 스코프는 리포지토리 전반의 작업을 포괄합니다. Claude Code는 로컬 스코프도 지원하며, 지원 여부는 하네스마다 다르고 CLI는 지원되지 않는 조합을 거부합니다. - 머신과 이벤트를 확인합니다: + 머신과 이벤트를 확인합니다. ```bash failproofai config --status @@ -94,16 +100,16 @@ icon: "plug-zap" -## 기본값이 아닌 세션 경로 추가 +## 기본이 아닌 세션 경로 추가 - 추가 경로는 Cloud가 아닌 머신에 등록됩니다. 경로를 추가한 후 **Observe → Sessions**를 열고 해당 머신의 환경으로 필터링하여 새 경로의 세션이 표시되는지 확인하세요. 감사에 활용하기 전에 세션을 열어 에이전트, 하네스, 이벤트 타임스탬프를 확인하세요. + 추가 경로는 Cloud가 아닌 머신에 등록됩니다. 경로를 추가한 후 **Observe → Sessions**를 열고, 머신의 환경으로 필터링하여 새 경로에서 세션이 나타나는지 확인합니다. 감사에 활용하기 전에 세션을 열어 에이전트, 하네스, 이벤트 타임스탬프를 검토하세요. - ![추가 캡처 경로에서 데이터를 수신 중인 환경으로 필터링된 Sessions 목록.](/images/dashboard/sessions-list.png) + ![추가 캡처 경로로부터 데이터를 수신하는 환경으로 필터링된 Sessions 목록.](/images/dashboard/sessions-list.png) - 선택적 레이블과 함께 경로를 추가하고, 설정된 경로를 확인합니다: + 선택적 레이블과 함께 경로를 추가한 후 설정된 경로를 확인합니다. ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -112,10 +118,10 @@ icon: "plug-zap" failproofai backfill --since 7d ``` - `failproofai harness remove-path claude checkout` 명령으로 경로를 제거합니다. + 경로를 제거하려면 `failproofai harness remove-path claude checkout`을 사용하세요. - 설치 후 새 세션을 하나 실행하세요. 롤아웃을 확대하기 전에 실시간 이벤트 스트림과 실제 정책 결정을 모두 확인하세요. + 설치 후 새 세션을 한 번 실행하세요. 롤아웃을 확대하기 전에 라이브 이벤트 스트림과 실제 정책 결정을 모두 확인하시기 바랍니다. \ No newline at end of file diff --git a/docs/ko/reference/overview.mdx b/docs/ko/reference/overview.mdx index 7965f0f0..26ebf211 100644 --- a/docs/ko/reference/overview.mdx +++ b/docs/ko/reference/overview.mdx @@ -1,5 +1,5 @@ --- -title: "통합 및 레퍼런스" +title: "통합 및 참조" description: "지원되는 에이전트 하네스, SDK, CLI, HTTP API를 연결합니다." icon: "braces" --- @@ -13,69 +13,72 @@ icon: "braces" LangGraph, CrewAI, LlamaIndex, Pydantic AI 또는 커스텀 에이전트를 계측합니다. - - 설정, 이벤트 카탈로그, 상관관계 규칙, 전달 방식을 다룹니다. + + 설정, 이벤트 카탈로그, 상관 규칙, 전달 방법을 확인합니다. 로컬 프로젝트, 세션, 정책 활동, 오프라인 감사를 검토합니다. - 로컬 캡처, 훅, 정책, 감사, 전달, 머신 상태를 구성합니다. + 로컬 캡처, 훅, 정책, 감사, 전달, 머신 상태를 설정합니다. Cloud 세션, 감사, 이슈, 알림, 키, 사용자, 설정을 조회하고 관리합니다. - - FastAPI 서비스로 완료되었거나 비활성 상태인 세션을 평가합니다. + + FastAPI 서비스로 완료되거나 비활성화된 세션을 채점합니다. 워크플로우별 allow, instruct, deny 결정을 작성하고 테스트합니다. - - 고객 관리 Kubernetes 클러스터에 Cloud 컨트롤 플레인을 배포합니다. + + 고객 관리형 Kubernetes 클러스터에 Cloud 컨트롤 플레인을 배포합니다. -자동 생성된 [HTTP API 레퍼런스](/ko/reference/http-api)는 공개 `/v1` 표면을 다룹니다. 직접 작성된 페이지에서는 여러 엔드포인트에 걸쳐 있거나 해당 공개 표면 밖의 관리 인터페이스를 사용하는 워크플로우를 설명합니다. +자동 생성된 [HTTP API 참조](/ko/reference/http-api)는 공개 `/v1` 인터페이스를 다룹니다. 직접 작성된 페이지에서는 여러 엔드포인트에 걸친 워크플로우나 해당 공개 인터페이스 외부의 관리 인터페이스를 사용하는 경우를 설명합니다. -## 에이전트 연결 및 데이터 검증 +## 에이전트 연결 및 데이터 확인 1. **Administration → Keys**를 열고, `events:add`와 `policies:pull` 권한으로 키를 생성한 후 시크릿을 복사합니다. - 2. 위의 해당 페이지를 참고해 통합을 구성합니다. - 3. **Observe → Events**를 열어 이벤트가 도착하는지 확인한 다음, **Observe → Sessions**에서 완전한 실행으로 그룹화되는지 확인합니다. - 4. 통합의 환경으로 필터링하고, 감사에 필요한 모델, 도구, 오류, 정책 필드가 포함된 세션 하나를 검사합니다. + 2. 위의 해당 페이지를 참고하여 통합을 설정합니다. + 3. **Observe → Events**를 열어 이벤트가 수신되는지 확인하고, **Observe → Sessions**에서 이벤트가 완전한 실행으로 구성되는지 확인합니다. + 4. 통합의 환경으로 필터링하고, 감사에 필요한 모델, 도구, 오류, 정책 필드가 포함된 세션을 하나 검사합니다. - 키 드로어에서 시작하세요. 선택한 권한에 따라 머신이 이벤트를 전송하고 Cloud 관리 정책을 수신할 수 있는지 결정됩니다. + 키 드로어에서 시작하세요. 선택한 권한에 따라 머신이 이벤트를 전송하고 Cloud 관리형 정책을 수신할 수 있는지 결정됩니다. ![이벤트 수집 및 정책 전달 권한을 부여하는 데 사용되는 새 API 키 드로어.](/images/dashboard/key-create.png) - 통합을 연결한 후, Sessions 목록을 통해 해당 이벤트들이 예상 환경에서 완전한 실행으로 그룹화되고 있는지 확인하세요. + 통합을 연결한 후, Sessions 목록을 사용하여 이벤트가 예상 환경에서 완전한 실행으로 그룹화되고 있는지 확인합니다. ![새로 연결된 통합이 완전한 에이전트 실행을 보고하는지 확인하는 데 사용되는 Sessions 목록.](/images/dashboard/sessions-list.png) - 통합을 완료로 간주하기 전에 세션 중 하나를 열어보세요. 트레이스에 감사에 필요한 모델, 도구, 오류, 정책 증거가 포함되어 있어야 합니다. + 통합이 완료된 것으로 간주하기 전에 이 세션 중 하나를 열어보세요. 트레이스에는 감사에 필요한 모델, 도구, 오류, 정책 근거가 포함되어 있어야 합니다. - 머신 키를 생성하고, Failproof 데몬을 연결한 후 첫 번째 세션을 검증합니다. + 머신 키를 생성한 후, 출력된 시크릿을 셸로 읽어들입니다. `read -s`는 에코되지 않는 프롬프트에서 입력을 받으므로, 명령어나 셸 히스토리에 절대 노출되지 않습니다: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Failproof 데몬을 연결하고 첫 번째 세션을 확인합니다: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - 다른 도구가 결과를 사용할 경우 `fp --json sessions ...`를 사용하세요. `--json`, `--org`, `--base-url` 같은 전역 플래그는 명령어 앞에 위치해야 합니다. + 다른 도구가 결과를 사용할 경우 `fp --json sessions ...`를 활용하세요. `--json`, `--org`, `--base-url`과 같은 전역 플래그는 명령어 앞에 위치해야 합니다. - 로컬 명령어는 [Failproof AI CLI 레퍼런스](/ko/reference/failproof-cli)를, `fp` 명령어는 [Failproof Cloud CLI 레퍼런스](/ko/reference/cloud-cli#cli-commands)를 참고하세요. + 로컬 명령어는 [Failproof AI CLI 참조](/ko/reference/failproof-cli)를, `fp` 명령어는 [Failproof Cloud CLI 참조](/ko/reference/cloud-cli#cli-commands)를 참고하세요. \ No newline at end of file diff --git a/docs/ko/reference/policy-sdk.mdx b/docs/ko/reference/policy-sdk.mdx index db814ac2..be86e0b1 100644 --- a/docs/ko/reference/policy-sdk.mdx +++ b/docs/ko/reference/policy-sdk.mdx @@ -1,35 +1,35 @@ --- title: "커스텀 정책" -description: "에이전트에 특화된 장애 패턴을 처리하는 JavaScript 또는 TypeScript 정책을 작성, 테스트, 배포합니다." +description: "에이전트에 특화된 장애에 대응하는 JavaScript 또는 TypeScript 정책을 작성, 테스트, 배포하세요." icon: "shield-plus" --- -커스텀 정책은 트레이스나 감사 기록에서 발견된 장애 패턴을 에이전트가 작동하는 동안 실시간으로 처리하는 결정 규칙으로 전환합니다. 정책은 특정 작업을 허용하거나, 에이전트에게 지침을 제공하거나, 문제가 발생하기 전에 해당 작업을 차단할 수 있습니다. +커스텀 정책은 트레이스나 감사에서 발견된 장애 패턴을 에이전트가 작동하는 동안 실행되는 결정으로 전환합니다. 정책은 특정 작업을 허용하거나, 에이전트에게 지침을 제공하거나, 또 다른 사고가 발생하기 전에 해당 작업을 차단할 수 있습니다. -도구, 경로, 명령어, 환경, 또는 운영 규칙에 따라 동작이 달라지는 경우 커스텀 정책을 사용하세요. 기존 컨트롤을 중복으로 만들지 않도록 먼저 [기본 제공 정책 카탈로그](/ko/policies/builtin-catalog)를 확인하세요. +커스텀 정책은 도구, 경로, 명령, 환경, 또는 운영 규칙에 따라 동작이 달라지는 경우에 사용하세요. 기존 제어 항목을 중복 생성하지 않도록 먼저 [Failproof AI 정책 팩](/ko/policies/packs)을 확인하세요. ## 커스텀 정책 작성 - 1. **Admin → policy editor**로 이동하여 **New policy**를 선택하고, 방지하려는 장애를 설명합니다. - 2. 정책 소스를 추가한 후 에디터에서 예상 일치 케이스와 안전한 비일치 케이스를 테스트합니다. 모든 유효성 검사 오류를 해결하세요. - 3. 초안을 저장하고 **Publish version**을 선택하여 변경 불가능한 버전을 생성합니다. - 4. **Admin → enforcement**로 이동하여 **observe** 모드의 테스트 머신에 버전을 배포하고, 적용하기 전에 **Observe → policy**에서 결정 사항을 확인합니다. + 1. **Admin → 정책 편집기**로 이동하여 **새 정책**을 선택하고, 방지하려는 장애를 설명합니다. + 2. 정책 소스를 추가한 다음, 편집기에서 예상 일치 항목과 안전한 비일치 항목을 테스트합니다. 모든 유효성 검사 오류를 해결합니다. + 3. 초안을 저장하고 **버전 게시**를 선택하여 변경 불가능한 버전을 생성합니다. + 4. **Admin → 적용**으로 이동하여 **관찰** 모드로 테스트 머신에 버전을 배포하고, 적용하기 전에 **Observe → 정책**에서 결정 사항을 검증합니다. ![커스텀 정책을 작성하고 게시하는 데 사용되는 정책 편집기.](/images/dashboard/policy-editor.png) - 1. `.failproofai/policies/checkout-policies.ts`를 생성합니다. 파일명은 반드시 `policies.js`, `policies.mjs`, 또는 `policies.ts`로 끝나야 합니다. + 1. `.failproofai/policies/checkout-policies.ts`를 생성합니다. 파일 이름은 반드시 `policies.js`, `policies.mjs`, 또는 `policies.ts`로 끝나야 합니다. 2. `customPolicies.add()`로 하나 이상의 정책을 등록합니다. - 3. `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project` 명령어로 파일을 유효성 검사하고 설치합니다. - 4. 일치하는 작업 하나와 안전한 작업 하나를 트리거합니다. `failproofai policies`를 실행한 후 **Observe → policy**에서 해당 정책에 귀속된 결정 사항을 확인합니다. + 3. `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project` 명령으로 파일을 검증하고 설치합니다. + 4. 일치하는 작업 하나와 안전한 작업 하나를 트리거합니다. `failproofai policies`를 실행한 다음 **Observe → 정책**에서 귀속된 결정 사항을 확인합니다. -## 좁은 범위의 규칙으로 시작하기 +## 범위가 좁은 규칙으로 시작하기 -아래 정책은 명령어가 프로덕션을 대상으로 할 때만 파괴적인 Kubernetes 명령을 차단합니다. 해당 장애 패턴에 정확히 해당하지 않는 경우에는 `allow()`를 반환합니다. +이 정책은 명령이 프로덕션을 대상으로 할 때만 파괴적인 Kubernetes 명령을 차단합니다. 해당 장애 모드에 해당하지 않는 모든 경우는 `allow()`를 반환합니다. ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,20 +55,20 @@ customPolicies.add({ }); ``` -좋은 정책은 한 문장으로 설명할 수 있을 만큼 좁은 범위여야 합니다. 에이전트의 의도가 아닌 관찰 가능한 실제 행동에 매칭하고, 규칙이 적용되지 않는 즉시 `allow()`를 반환하세요. +좋은 정책은 한 문장으로 설명할 수 있을 만큼 범위가 좁습니다. 에이전트의 의도가 아닌 관찰 가능한 실제 작업을 매칭하고, 규칙이 적용되지 않는 즉시 `allow()`를 반환하세요. -## 결정 방식 선택 +## 결정 선택하기 -| 헬퍼 | 결과 | 사용 시기 | +| 헬퍼 | 결과 | 사용 시점 | | --- | --- | --- | | `allow(reason?)` | 작업이 계속됩니다. | 정책이 적용되지 않거나 작업이 안전한 경우. | -| `instruct(reason)` | 작업이 계속되며, 해당 하네스가 지원하는 경우 지침이 제공됩니다. | 불변 규칙을 강제하지 않고 에이전트가 더 나은 방법을 사용하도록 유도하려는 경우. | -| `deny(reason)` | 이벤트와 하네스가 차단을 지원하는 경우 작업이 차단됩니다. | 작업이 진행되어서는 안 되는 경우. | +| `instruct(reason)` | 하네스가 지원하는 경우 작업이 지침과 함께 계속됩니다. | 불변 조건을 강제하지 않고 에이전트를 더 나은 방향으로 유도하고 싶을 때. | +| `deny(reason)` | 이벤트 및 하네스가 차단을 지원하는 경우 작업이 차단됩니다. | 작업이 진행되어서는 안 되는 경우. | -복구해야 하는 에이전트를 위해 이유(reason)를 작성하세요. 무엇이 감지되었고 대신 무엇을 해야 하는지 설명하세요. +복구해야 하는 에이전트를 위해 이유를 작성하세요. 감지된 내용과 대신 수행해야 할 작업을 설명하세요. - `instruct()`를 안전 경계로 사용하지 마세요. 지침 전달 방식은 에이전트 하네스에 따라 다릅니다. 작업을 반드시 막아야 할 경우에는 `deny()`를 사용하세요. + 보안 경계에는 `instruct()`를 사용하지 마세요. 지침 전달은 에이전트 하네스에 따라 다를 수 있습니다. 작업을 반드시 방지해야 할 때는 `deny()`를 사용하세요. ## 정책 객체 @@ -84,32 +84,32 @@ customPolicies.add({ | 필드 | 필수 여부 | 설명 | | --- | --- | --- | -| `name` | 예 | 정책의 안정적인 식별자입니다. 파일 전체에서 고유한 이름을 유지하세요. | -| `description` | 아니오 | 정책 목록 및 결정 사항에 표시되는 사람이 읽을 수 있는 설명입니다. | -| `match.events` | 아니오 | 정책을 호출하는 이벤트 유형입니다. `match`를 생략하면 사용 가능한 모든 이벤트에 대해 호출됩니다. | -| `fn` | 예 | `allow`, `instruct`, 또는 `deny` 결과를 반환하는 동기 또는 비동기 함수입니다. | +| `name` | 예 | 정책의 안정적인 식별자. 파일 전체에서 이름이 고유해야 합니다. | +| `description` | 아니요 | 정책 목록 및 결정에 표시되는 사람이 읽을 수 있는 용도 설명. | +| `match.events` | 아니요 | 정책을 호출하는 이벤트 유형. `match`를 생략하면 사용 가능한 모든 이벤트에 대해 호출됩니다. | +| `fn` | 예 | `allow`, `instruct`, 또는 `deny` 결과를 반환하는 동기 또는 비동기 함수. | -`fn` 내부에서 도구를 필터링하세요. `match.toolNames`은 공개 커스텀 정책 타입에 포함되지 않습니다. +`fn` 내부에서 도구를 필터링하세요. `match.toolNames`는 공개 커스텀 정책 타입의 일부가 아닙니다. ## 정책 컨텍스트 모든 정책은 `PolicyContext`를 받습니다. -| 필드 | 타입 | 포함 내용 | +| 필드 | 타입 | 내용 | | --- | --- | --- | | `eventType` | `HookEventType` | 현재 평가 중인 정규화된 이벤트. | -| `toolName` | `string \| undefined` | `Bash`, `Read`, `Write`, `Edit` 등의 표준 도구 이름. | -| `toolInput` | `Record \| undefined` | 현재 도구 호출의 표준 입력. | +| `toolName` | `string \| undefined` | `Bash`, `Read`, `Write`, `Edit` 등 정규화된 도구 이름. | +| `toolInput` | `Record \| undefined` | 현재 도구 호출에 대한 정규화된 입력. | | `payload` | `Record` | 완전히 정규화된 이벤트 페이로드. | -| `session` | `SessionMetadata \| undefined` | 세션 ID, 작업 디렉토리, 트랜스크립트 경로, 권한 모드, 사용 가능한 경우 하네스 메타데이터. | -| `cli` | `string \| undefined` | `claude`, `codex`, `cursor` 등의 소스 에이전트 하네스. | -| `params` | `Record` | 기본 제공 정책 파라미터. 커스텀 정책은 현재 빈 객체를 받습니다. | +| `session` | `SessionMetadata \| undefined` | 사용 가능한 경우 세션 ID, 작업 디렉터리, 트랜스크립트 경로, 권한 모드, 하네스 메타데이터. | +| `cli` | `string \| undefined` | `claude`, `codex`, `cursor` 등 소스 에이전트 하네스. | +| `params` | `Record` | 내장 정책 파라미터. 커스텀 정책은 현재 빈 객체를 받습니다. | -모든 선택적 값을 실제로 선택 사항으로 취급하세요. 에이전트 버전과 이벤트 타입에 따라 제공되는 필드가 다를 수 있습니다. +모든 선택적 값을 실제로 선택적인 것으로 처리하세요. 에이전트 버전과 이벤트 유형이 항상 동일한 필드를 제공하지는 않습니다. ### 일반적인 도구 입력 -Failproof AI는 지원되는 하네스 전반에서 공통 도구를 정규화하므로, 정책은 일반적으로 하나의 입력 형태를 사용할 수 있습니다. +Failproof AI는 지원되는 하네스 전반에 걸쳐 일반적인 도구를 정규화하므로, 정책은 보통 하나의 입력 형태를 사용할 수 있습니다. | 도구 | 공통 필드 | | --- | --- | @@ -119,26 +119,26 @@ Failproof AI는 지원되는 하네스 전반에서 공통 도구를 정규화 | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | -도구 입력 값은 `unknown`으로 타입이 지정되므로 방어적 변환을 사용하세요: +도구 입력 값은 `unknown`으로 타입이 지정되므로 방어적인 형변환을 사용하세요: ```ts const command = String(ctx.toolInput?.command ?? ""); const filePath = String(ctx.toolInput?.file_path ?? ""); ``` -## 이벤트 선택 +## 이벤트 선택하기 | 이벤트 | 실행 시점 | 일반적인 용도 | | --- | --- | --- | -| `PreToolUse` | 도구 실행 전. | 명령어, 쓰기, 읽기, 외부 작업 차단 또는 안내. | -| `PostToolUse` | 도구 반환 후. | 에이전트에 도달하기 전 결과 검사. deny는 전체 결과를 차단하며, 선택적 필드를 삭제하지는 않습니다. | +| `PreToolUse` | 도구 실행 전. | 명령, 쓰기, 읽기, 외부 작업 차단 또는 안내. | +| `PostToolUse` | 도구 반환 후. | 에이전트에 도달하기 전에 결과 검사. deny는 전체 결과를 차단하며 특정 필드를 편집하지 않습니다. | | `PermissionRequest` | 에이전트가 권한을 요청할 때. | 조직별 권한 규칙 적용. | -| `UserPromptSubmit` | 제출된 프롬프트가 계속되기 전. | 금지된 지시 거부 또는 워크플로우 지침 추가. | -| `Stop` | 에이전트가 완료를 시도할 때. | 로컬 검증 단계 등 충족 가능한 완료 조건 요구. | -| `SubagentStop` | 서브에이전트가 완료를 시도할 때. | 부모에게 반환되기 전 위임된 작업 게이팅. | +| `UserPromptSubmit` | 제출된 프롬프트가 계속되기 전. | 금지된 지시 거부 또는 워크플로우 안내 추가. | +| `Stop` | 에이전트가 완료하려 할 때. | 로컬 검증 단계와 같이 달성 가능한 완료 조건 요구. | +| `SubagentStop` | 서브에이전트가 완료하려 할 때. | 부모에게 반환되기 전에 위임된 작업 게이팅. | | `SessionStart` / `SessionEnd` | 세션 경계에서. | 세션 수준 상태 기록 또는 확인. | -이벤트 가용성 및 차단 동작은 에이전트 하네스에 따라 다릅니다. 혼합 환경에서 이벤트에 의존하기 전에 [에이전트 하네스](/ko/reference/harnesses)를 확인하세요. +이벤트 가용성과 차단 동작은 에이전트 하네스에 따라 다릅니다. 혼합 플릿 전반에서 이벤트에 의존하기 전에 [에이전트 하네스](/ko/reference/harnesses)를 참조하세요. `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch`, `Setup`. @@ -215,7 +215,7 @@ customPolicies.add({ ``` - `Stop` 이벤트가 거부되면 에이전트가 재시도할 수 있습니다. 현재 환경에서 에이전트가 충족할 수 있는 조건에만 게이팅하고, 모든 서브프로세스나 네트워크 호출에 제한을 두세요. + 거부된 `Stop` 이벤트는 에이전트가 재시도하게 만들 수 있습니다. 현재 환경에서 에이전트가 충족할 수 있는 조건에만 게이팅하고, 모든 서브프로세스 또는 네트워크 호출에 제한을 두세요. ## 정책 파일 로드 @@ -229,16 +229,16 @@ customPolicies.add({ ~/.failproofai/policies/personal-policies.mjs ``` -- 프로젝트 및 사용자 정책 디렉토리가 모두 로드됩니다. -- 각 디렉토리 내에서 파일은 알파벳 순서로 로드됩니다. +- 프로젝트 및 사용자 정책 디렉터리가 모두 로드됩니다. +- 각 디렉터리 내에서 파일은 알파벳 순서로 로드됩니다. - 파일은 반드시 `policies.js`, `policies.mjs`, 또는 `policies.ts`로 끝나야 합니다. -- 하나의 파일에서 `customPolicies.add()`를 여러 번 호출할 수 있습니다. -- 로컬 모듈에서의 상대 임포트를 지원합니다. -- 프로젝트 정책은 커밋할 수 있어 동일한 규칙이 레포지토리를 따라갑니다. +- 하나의 파일에서 `customPolicies.add()`를 여러 번 호출하는 것이 지원됩니다. +- 로컬 모듈에서의 상대적 임포트가 지원됩니다. +- 프로젝트 정책은 커밋할 수 있으므로 동일한 규칙이 리포지터리를 따라갑니다. ### 명시적 파일 -유효성 검사나 설정에서 엔트리 파일을 직접 지정해야 할 때는 명시적 경로를 사용하세요: +유효성 검사 또는 구성에서 엔트리 파일을 직접 지정해야 할 때는 명시적 경로를 사용하세요: ```bash failproofai policies --install \ @@ -247,9 +247,9 @@ failproofai policies --install \ --scope project ``` -명시적 파일이 먼저 로드되고, 이후 프로젝트 컨벤션 파일, 사용자 컨벤션 파일 순으로 로드됩니다. 두 경로 모두에서 발견된 파일은 한 번만 로드됩니다. +명시적 파일이 먼저 로드되고, 그 다음 프로젝트 컨벤션 파일, 마지막으로 사용자 컨벤션 파일이 로드됩니다. 두 경로를 통해 발견된 파일은 한 번만 로드됩니다. -## 유효성 검사 및 테스트 +## 검증 및 테스트 유효성 검사는 프로덕션 로더를 통해 모듈을 실행하고 최소 하나의 정책이 등록되었는지 확인합니다. @@ -260,44 +260,44 @@ failproofai policies --install \ failproofai policies ``` -유효성 검사는 누락된 파일, 구문 오류, 해결되지 않은 임포트, 최상위 예외, 모듈 로드 타임아웃을 감지합니다. 단, 매칭 로직의 정확성을 보장하지는 않습니다. +유효성 검사는 누락된 파일, 구문 오류, 미해결 임포트, 최상위 예외, 모듈 로드 타임아웃을 감지합니다. 매칭 로직이 올바른지는 증명하지 않습니다. -최소한 다음 케이스를 테스트하세요: +최소한 다음 케이스들을 테스트하세요: -- 반드시 일치해야 하며 의도한 정책 이유를 생성하는 작업 하나. -- 유사하지만 안전한 작업으로 `allow()`를 반환해야 하는 케이스 하나. +- 반드시 일치해야 하며 의도된 정책 이유를 생성하는 작업 하나. +- 반드시 `allow()`를 반환해야 하는 유사하지만 안전한 작업 하나. - 누락되거나 잘못된 형식의 도구 필드. -- 대체 명령어 구문, 경로, 인용 방식, 대소문자, 공백. -- 사용 불가능한 서브프로세스 또는 네트워크 의존성. +- 대체 명령 구문, 경로, 따옴표, 대소문자, 공백. +- 사용할 수 없는 서브프로세스 또는 네트워크 의존성. -**Observe → policy**에서 결과가 커스텀 정책에 귀속되는지 확인하세요. 다른 기본 제공 정책이 결정을 내린 경우, 차단된 테스트만으로는 충분하지 않습니다. +**Observe → 정책**에서 결과를 커스텀 정책에 귀속시키세요. 다른 내장 정책이 결정을 내린 경우 차단된 테스트만으로는 충분하지 않습니다. ## 런타임 동작 -- 기본 제공 정책이 커스텀 정책보다 먼저 평가됩니다. -- 첫 번째 `deny`가 발생하면 이후 정책 평가가 중단됩니다. -- 어떤 정책도 이벤트를 거부하지 않을 경우, 여러 `instruct` 결과가 결합될 수 있습니다. -- 정책 함수의 실행 제한 시간은 10초입니다. +- 내장 정책이 커스텀 정책보다 먼저 평가됩니다. +- 첫 번째 `deny`가 추가 정책 평가를 중지시킵니다. +- 정책이 이벤트를 거부하지 않으면 여러 `instruct` 결과를 결합할 수 있습니다. +- 정책 함수의 실행 마감 시간은 10초입니다. - 예외가 발생하거나 타임아웃이 발생하면 로그에 기록되고 `allow()`로 처리됩니다. -- 로드에 실패한 컨벤션 파일은 건너뜁니다. 다른 커스텀 파일과 기본 제공 정책은 계속 실행됩니다. -- 최상위 모듈 로드에도 10초 제한 시간이 적용됩니다. -- Cloud observe 모드에서는 정책을 실행하지만, allow가 아닌 결정은 기록만 하고 적용하지 않습니다. +- 로드에 실패한 컨벤션 파일은 건너뜁니다. 다른 커스텀 파일과 내장 정책은 계속 실행됩니다. +- 최상위 모듈 로딩에도 10초 마감 시간이 있습니다. +- 클라우드 관찰 모드는 정책을 실행하지만 비허용 결정을 적용하지 않고 기록만 합니다. -정책 모듈은 결정론적이고 빠르게 유지하세요. 최상위 네트워크 호출이나 서버 시작을 피하세요. `fn` 내부의 작업을 제한하고, 의존성 실패를 캐치하며, 해당 실패가 작업을 허용할지 거부할지 신중하게 결정하세요. +정책 모듈은 결정론적이고 빠르게 유지하세요. 최상위 네트워크 호출이나 서버 시작을 피하세요. `fn` 내부에서 작업을 제한하고, 의존성 실패를 처리하며, 해당 실패가 작업을 허용해야 할지 거부해야 할지 신중하게 선택하세요. -## API 익스포트 +## API 내보내기 -| 익스포트 | 용도 | +| 내보내기 | 용도 | | --- | --- | | `customPolicies.add(policy)` | 모듈이 로드될 때 커스텀 정책을 등록합니다. | | `allow(reason?)` | 작업을 허용합니다. | | `instruct(reason)` | 작업을 허용하고 지원되는 경우 지침을 제공합니다. | | `deny(reason)` | 지원되는 경우 작업을 차단합니다. | | `getCustomHooks()` | 모듈 레지스트리에 현재 등록된 정책을 반환합니다. | -| `clearCustomHooks()` | 해당 레지스트리를 초기화합니다. 주로 테스트 및 로더에서 사용됩니다. | +| `clearCustomHooks()` | 주로 테스트 및 로더를 위해 해당 레지스트리를 초기화합니다. | -TypeScript는 `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision`, `PolicyFunction`을 익스포트합니다. +TypeScript는 `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision`, `PolicyFunction`을 내보냅니다. - 버전을 게시하고, observe 모드로 배포하고, 결정 사항을 확인한 후 적용 단계로 이동합니다. + 버전을 게시하고, 관찰 모드로 배포하고, 결정 사항을 검증한 다음, 적용 단계로 이동하세요. \ No newline at end of file diff --git a/docs/ko/sessions/evaluations.mdx b/docs/ko/sessions/evaluations.mdx index 64c3337b..c6a98fa4 100644 --- a/docs/ko/sessions/evaluations.mdx +++ b/docs/ko/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "온라인 평가" -description: "라이브 및 완료된 세션의 품질, 컴플라이언스, 비용, 레이턴시를 점수로 평가합니다." +title: "평가 결과 읽기" +description: "시간 경과에 따른 평가 점수를 차트로 확인하고, 에이전트와 환경을 비교하며, 세션 점수가 낮은 이유를 파악하고, 어시스턴트에게 질문하세요." icon: "gauge" --- -온라인 평가는 에이전트 세션에 일관된 판단을 적용합니다. 감사 시에만 조사하는 것이 아니라 지속적으로 측정해야 하는 신호에 활용하세요. +호스팅된 평가든 자체 워커를 통한 평가든, 모든 평가 결과는 동일한 위치에 저장됩니다. -## 평가 품질 검토 +## 시간 경과에 따른 점수 비교 - 1. **Observe → Evaluations**으로 이동합니다. - 2. 시리즈를 추가하고 에이전트, 환경, 평가 점수, 통계 및 곡선을 선택합니다. - 3. 시리즈를 추가하여 환경, 에이전트 또는 점수 키를 비교합니다. - 4. 결과를 선택하여 일치하는 세션을 열거나 필터링된 뷰를 공유합니다. 레이턴시, 토큰, 비용 및 기타 수치 값은 **Observe → Metrics**를 사용하세요. + **Observe → evaluations**으로 이동합니다. - ![평균 평가 점수와 시간에 따른 트렌드를 보여주는 품질 대시보드.](/images/dashboard/dashboard-quality.png) + - **Recent runs**에는 각 평가 결과가 수신된 순서대로 나열됩니다. 호스팅된(**managed**) 평가자에서 온 것인지 직접 운영하는(**customer**) 평가자에서 온 것인지 여부, 에이전트와 세션, 평가 항목과 버전, 상태, 점수 또는 지표가 표시됩니다. + - **Score over time**은 원하는 내용을 차트로 그립니다. **add series**를 선택하고 에이전트, 환경, 평가 항목, 통계(avg, min, max, p50, p75, p90, p95, p99, stddev, mode 중 하나)를 지정합니다. 각 시리즈는 하나의 선으로 표시되며, 별도 차트에 그리려면 **curve**를 지정하세요. - 드릴다운에서 세션을 열어 점수별 추론 내용을 확인하세요: + ![평가 페이지: customer 태그가 붙은 최근 실행 목록, 0.5와 0.8에 기준선이 있는 시간 경과 점수 차트, 모든 에이전트와 환경에 걸쳐 finished_clean을 평균 내는 하나의 시리즈.](/images/dashboard/evaluations-chart.png) - ![전체 트레이스 옆에 평가 점수와 추론을 표시하는 세션 상세 뷰.](/images/dashboard/session-detail.png) + 하나의 시간 범위와 하나의 구간 크기가 모든 시리즈에 적용됩니다. 세밀한 구간은 특정 인시던트를 찾아내고, 넓은 구간은 전체 추세를 보여주되 찾고 있는 급등 현상을 숨길 수 있습니다. 점수가 없는 구간은 선의 공백으로 표시되며 0으로 처리되지 않고, 기준선은 0.5와 0.8에 표시됩니다. + + 뷰의 모든 설정은 URL에 저장됩니다. **share**를 누르면 링크가 복사되고, 링크를 열면 구성한 비교 화면이 그대로 표시됩니다. ```bash @@ -28,25 +28,29 @@ icon: "gauge" fp evals --score helpfulness:0.8.. --since 7d ``` - 자동화를 위해 `evals` 앞에 전역 `--json`을 추가하세요. 예: `fp --json evals --aggregate --env production`. + 자동화 용도로는 `evals` 앞에 전역 옵션 `--json`을 추가하세요. 예: `fp --json evals --aggregate --env production`. -평가자는 세션 식별 정보, 환경, 타임스탬프, 순서가 있는 이벤트를 수신합니다. 선택적 추론 및 요약과 함께 숫자 점수 키를 반환할 수 있습니다. 장시간 실행되는 평가자는 보류 중인 작업을 반환하고 나중에 폴링할 수 있습니다. +동일한 평가에 대해 **avg**와 **p90**을 함께 플롯하면 좋은 평균값이 나쁜 꼬리 분포를 숨기고 있는지 확인할 수 있습니다. 두 에이전트 또는 프로덕션과 스테이징 환경에 대해 동일한 평가를 플롯하면 하나의 축에서 바로 비교할 수 있습니다. 단위가 있는 비용, 지연 시간, 토큰 수는 **Observe → metrics**에서 단위별로 별도 차트에 표시됩니다. + +## 세션 점수가 낮은 이유 파악하기 + +**Observe → sessions**에서 세션을 열면, 그리드에 각 세션의 점수가 표시되며 점수 범위로 필터링할 수 있습니다. 세션 오른쪽 패널에는 평가 요약이 먼저 표시되고, 그 아래에 각 점수를 나타내는 막대와 평가자의 추론 근거가 이어집니다. + +![완전한 트레이스 옆에 평가 점수와 근거가 표시된 세션 상세 뷰.](/images/dashboard/session-detail.png) + +## 어시스턴트에게 질문하기 + +평가 데이터에 대해 평문으로 질문할 수 있습니다. 예를 들어 "최근 평가 결과 몇 가지를 알려줘"라거나 어떤 에이전트의 점수가 떨어지고 있는지 물어볼 수 있습니다. [어시스턴트](/ko/sessions/assistant)는 결과를 읽고 분석하여 표 형태로 답변을 제공하며, 후속 질문도 가능합니다. 유용한 질문은 [쿼리](/ko/sessions/queries)나 [대시보드](/ko/sessions/dashboards)로 저장할 수 있습니다. -## 좋은 평가 대상 +![어시스턴트가 "최근 평가 결과 몇 가지를 알려줘"라는 질문에 총계, 상태, 점수 요약으로 답변하는 모습이 평가 페이지 옆에 표시된 화면.](/images/dashboard/evaluations-assistant.png) -- 태스크 완료 또는 정확성 -- 근거 충실도 및 환각 위험 -- 도구 선택 및 도구 효율성 -- 정책 또는 프로세스 컴플라이언스 -- 비용 및 레이턴시 예산 -- 필수 인간 에스컬레이션 +## 모니터링 및 대응 -## 점수에서 대응으로 +- **Dashboards**(**Analyze → dashboards**)에서는 조직 전체 기준으로 에이전트와 환경별 주요 점수 추세를 확인할 수 있습니다. -대시보드에 점수를 표시하여 트렌드를 추적하세요. 임계값 또는 복합 조건에 대한 알림을 생성하세요. 특정 집단에서 점수가 하락하면 감사를 실행하여 원인을 조사하고, 원인이 반복 가능한 행동인 경우 정책을 배포하세요. + ![평균 평가 점수와 시간 경과에 따른 추세를 보여주는 품질 대시보드.](/images/dashboard/dashboard-quality.png) - - Python 평가자 SDK를 사용하여 동기 또는 비동기 평가를 구현합니다. - \ No newline at end of file +- **Alerts**는 점수가 임계값을 넘으면 알림을 보냅니다. [알림](/ko/audits/alerts)을 참고하세요. +- 여러 세션에 걸쳐 점수가 하락할 경우 [감사 실행](/ko/audits/run)으로 원인을 파악하고, 원인이 반복적인 행동에 있다면 [정책을 작성](/ko/policies/editor)하세요. \ No newline at end of file diff --git a/docs/ko/start/integrations/custom-agents.mdx b/docs/ko/start/integrations/custom-agents.mdx index 38ab23b7..4fea8d3c 100644 --- a/docs/ko/start/integrations/custom-agents.mdx +++ b/docs/ko/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "커스텀 에이전트" sidebarTitle: "커스텀 에이전트" -description: "직접 작성한 에이전트 또는 어댑터가 없는 프레임워크를 계측합니다." +description: "직접 작성한 에이전트나 어댑터가 없는 프레임워크에 계측을 적용하세요." icon: "code" --- -직접 작성한 에이전트 또는 Failproof AI에 어댑터가 없는 프레임워크에 적합합니다. 별도로 계측할 것은 없습니다. 이벤트를 직접 발행하면 됩니다. +직접 작성한 에이전트나 Failproof AI에 어댑터가 없는 프레임워크에 사용합니다. 별도로 계측할 것은 없습니다. 이벤트를 직접 발행하면 됩니다. -이 API는 네 가지 프레임워크 어댑터가 내부적으로 호출하는 것과 동일합니다. 어댑터들은 이 API 위에 구현된 변환 테이블입니다. +이는 네 가지 프레임워크 어댑터가 내부적으로 호출하는 것과 동일한 API입니다. 어댑터들은 이 API에 대한 변환 테이블입니다. ## 설치 @@ -27,30 +27,30 @@ failproofai_sdk.configure(environment="production") with failproofai_sdk.session(): # 하나의 실행 with failproofai_sdk.agent("planner"): # 하나의 작업 단위 with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # 하나의 툴 호출 + t.output = search(q) # 하나의 도구 호출 ``` -위에서 아래로 읽으면 의미가 그대로 드러납니다: +위에서 아래로 읽으면 그 의미가 그대로 드러납니다: | 감싸는 것 | 의미 | | --- | --- | -| `session()` | 이 이벤트들은 동일한 실행에 속함 | -| `agent()` | 무언가가 작업 중 — 목록에서 알아볼 수 있는 이름을 부여 | -| `tool_call()` | 하나의 툴이며 반환값이 이것 | +| `session()` | 이 이벤트들은 동일한 실행에 속합니다 | +| `agent()` | 무언가 작업을 수행하고 있습니다 — 목록에서 알아볼 수 있는 이름을 붙이세요 | +| `tool_call()` | 이것은 하나의 도구이며, 반환한 값입니다 | 각각이 실제로 발행하는 이벤트: | 스코프 | 발행 이벤트 | 목적 | | --- | --- | --- | -| `session()` | 없음 | 세션 id를 바인딩하여 하나의 실행을 그룹화 | -| `agent()` | `agent_start`, `agent_end` | 작업 단위를 괄호로 묶음 | -| `tool_call()` | `tool_use`, `tool_result` | 하나의 툴을 괄호로 묶고 측정 | +| `session()` | 없음 | 세션 id를 바인딩하여 하나의 실행을 그룹화합니다 | +| `agent()` | `agent_start`, `agent_end` | 작업 단위를 괄호로 묶습니다 | +| `tool_call()` | `tool_use`, `tool_result` | 하나의 도구를 괄호로 묶고 측정합니다 | -내부의 모든 것은 `session_id`와 `agent_id`를 생략할 수 있습니다. 스코프가 컨텍스트 변수에 id를 바인딩하고 모든 이벤트 호출이 이를 읽어오므로, 함수에 id를 직접 전달할 필요가 없습니다. +내부의 모든 코드는 `session_id`와 `agent_id`를 생략할 수 있습니다. 스코프는 컨텍스트 변수에 식별자를 바인딩하며, 모든 이벤트 호출이 이를 읽어오므로 함수를 통해 id를 전달할 필요가 없습니다. 세 가지 모두 `with`뿐만 아니라 `async with`에서도 동작합니다. -에이전트를 중첩하면 트리가 만들어집니다. `parent_id`와 깊이는 스택에서 계산됩니다: +에이전트를 중첩하면 트리가 만들어집니다. `parent_id`와 깊이는 스택에서 자동으로 계산됩니다: ```python with failproofai_sdk.session(): @@ -59,35 +59,35 @@ with failproofai_sdk.session(): ... ``` -## 스코프 종료 방식 +## 스코프가 닫히는 방식 `agent()`는 예외를 자동으로 처리합니다: -| 상황 | 이벤트 | 결과 | +| 발생한 상황 | 이벤트 | 결과 | | --- | --- | --- | | 예외 없음 | `agent_end` | `success` | | `Exception` | `error`, 이후 `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, 이후 `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | `agent_end`만 | `cancelled` | -오류는 `agent_end` 이전에 발행됩니다. 대시보드가 `agent_end`에서 스팬을 닫기 때문에 그 이후의 이벤트는 귀속 대상이 없어지기 때문입니다. 취소는 실패가 아니므로 취소된 실행은 오류 목록을 오염시키지 않습니다. 예외는 항상 다시 발생합니다. 스코프는 절대 예외를 삼키지 않습니다. +`agent_end` 이전에 오류가 발행되는 이유는, 대시보드가 `agent_end`에서 스팬을 닫고 그 이후의 이벤트는 아무것에도 귀속되지 않기 때문입니다. 취소는 실패가 아니므로 취소된 실행은 오류 목록을 오염시키지 않습니다. 예외는 항상 다시 발생됩니다. 스코프는 예외를 삼키지 않습니다. ## 이벤트 메서드 -6개 패밀리, 15개 메서드. 대부분 쌍으로 구성되어 있으며 — 시작 이벤트를 발행한 후 종료 이벤트를 발행하면 SDK가 그 사이의 스팬을 측정합니다. +여섯 가지 계열에 걸쳐 열다섯 가지 메서드가 있습니다. 대부분은 쌍으로 이루어져 있으며, 여는 이벤트를 발행한 뒤 닫는 이벤트를 발행하면 SDK가 그 사이의 스팬을 측정합니다. -| 패밀리 | 시작 | 종료 | 단독 | +| 계열 | 여는 이벤트 | 닫는 이벤트 | 단독 이벤트 | | --- | --- | --- | --- | | **에이전트** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | | **모델** | `model_request` | `model_response` | — | -| **툴** | `tool_use` | `tool_result` | — | +| **도구** | `tool_use` | `tool_result` | — | | **훅** | `hook_triggered` | `hook_completed` | — | -| **휴먼** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **사람** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | | **실패** | — | — | `error` | - 가능한 곳에서는 스코프 — `agent()`와 `tool_call()` — 를 사용하세요. 본문에서 예외가 발생하더라도 종료 이벤트를 보장합니다. 모델 호출이 헬퍼 내부에 있는 것처럼 제어 흐름이 중첩되지 않을 때에만 이 메서드들을 직접 사용하세요. + 가능하면 `agent()`와 `tool_call()` 스코프를 사용하세요. 본문에서 예외가 발생해도 닫는 이벤트를 보장합니다. 제어 흐름이 중첩되지 않는 경우, 예를 들어 헬퍼 함수 내부의 모델 호출처럼 스코프가 맞지 않을 때는 이벤트 메서드를 직접 사용하세요. @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **두 휴먼 패밀리는 방향이 반대입니다.** + **두 가지 사람 관련 계열은 방향이 반대입니다.** | 메서드 | 의미 | | --- | --- | - | `human_wait` / `human_input` | **에이전트가 사람에게 요청** — 승인 게이트, 명확화 질문 | - | `human_pause` / `human_interrupt` | **사람이 에이전트에 개입** — 중지 버튼, 운영자 일시정지 | + | `human_wait` / `human_input` | **에이전트가 사람에게 요청** — 승인 게이트, 확인 질문 | + | `human_pause` / `human_interrupt` | **사람이 에이전트에 개입** — 중지 버튼, 운영자 일시 정지 | - 어떤 프레임워크도 두 번째 쌍을 신호로 보내지 않으므로 항상 직접 발행해야 합니다. + 두 번째 쌍은 어떤 프레임워크도 신호를 보내지 않으므로, 항상 직접 발행해야 합니다. - **모델 호출이 동시에 실행될 때는 `request_id`를 전달하세요.** 없으면 에이전트별 도착 순서대로 요청과 응답이 쌍을 이루어 동시 호출 시 잘못된 쌍이 만들어집니다. + **모델 호출이 동시에 실행될 때는 `request_id`를 전달하세요.** 전달하지 않으면 에이전트별로 요청과 응답이 도착 순서대로 쌍을 이루기 때문에, 동시 호출 시 잘못된 요청에 응답이 연결될 수 있습니다. -## 예제 +## 예시 -에이전트 프레임워크 없이 OpenAI API를 사용하는 툴 호출 루프: +에이전트 프레임워크 없이 OpenAI API를 사용하는 도구 호출 루프: ```python import json @@ -204,52 +204,52 @@ with failproofai_sdk.session(): }) ``` -이 코드는 어댑터가 생성하는 것과 동일한 6가지 이벤트 타입을 만들어냅니다. 툴 정의가 포함된 실행 가능한 전체 버전은 SDK 저장소의 `docs/manual/examples/`에 있습니다. +이 코드는 어댑터가 생성하는 것과 동일한 여섯 가지 이벤트 타입을 생성합니다. 도구 정의를 포함한 완전히 실행 가능한 버전은 SDK 저장소의 `docs/manual/examples/` 경로에 포함되어 있습니다. ## 스레드와 비동기 -컨텍스트 변수는 asyncio 태스크에 자동으로 전파됩니다. 스레드는 빈 컨텍스트로 시작하기 때문에 새 스레드에는 전파되지 않습니다. +컨텍스트 변수는 asyncio 태스크에 자동으로 전파됩니다. 하지만 새 스레드는 빈 컨텍스트로 시작하기 때문에 스레드로는 자동 전파되지 않습니다. ```python -# asyncio: 별도 처리 불필요 +# asyncio: 별도 작업 불필요 async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads: callable을 감싸기 +# 스레드: callable을 감쌀 것 pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -`propagate()`를 사용하지 않으면 워커의 이벤트가 세션 없이 전달되는 대신, 수정 방법을 알려주는 `TypeError`가 발생합니다. 이는 의도적인 동작입니다. 세션이 없는 이벤트는 인제스트에서 건너뛰고 `200`으로 응답하는데, 이것이 바로 id 레이어가 방지하고자 하는 조용한 실패이기 때문입니다. +`propagate()`를 사용하지 않으면, 워커의 이벤트는 세션 없이 처리되는 대신 수정 방법을 알려주는 `TypeError`를 발생시킵니다. 이는 의도적인 동작입니다. 세션이 없는 이벤트는 인제스트에서 건너뛰어지고 `200`으로 응답되는데, 이는 식별자 레이어가 방지하려는 무음 실패이기 때문입니다. ## 어댑터 없이 프레임워크 계측하기 -모든 에이전트 프레임워크는 동일한 세 가지 접합점을 제공합니다. 이것들을 매핑하면 완전한 트레이스를 얻을 수 있습니다 — 제공되는 네 가지 어댑터도 이것 이상을 하지 않습니다. +모든 에이전트 프레임워크는 동일한 세 가지 연결 지점을 제공합니다. 이를 매핑하면 완전한 트레이스를 얻을 수 있습니다. 출시된 네 가지 어댑터도 이것 이상을 하지 않습니다. -| 접합점 | 작성 내용 | 기록되는 것 | +| 연결 지점 | 작성할 코드 | 생성되는 이벤트 | | --- | --- | --- | | 실행 | `session()` + `agent()` | `agent_start`, `agent_end` | -| 각 툴 | `tool_call()` | `tool_use`, `tool_result` | +| 각 도구 | `tool_call()` | `tool_use`, `tool_result` | | 각 모델 호출 | `model_*` 쌍 | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - 프레임워크에서 툴 래퍼 또는 미들웨어라고 부르는 곳에서. + + 프레임워크에서 도구 래퍼나 미들웨어라고 부르는 곳에서 처리합니다. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -264,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **노드, 스텝 또는 미들웨어 경계를 확인하고 싶다면?** 중첩된 `agent()` 대신 훅 쌍 — `hook_triggered` / `hook_completed` — 으로 감싸세요. `agent_id`는 카디널리티가 낮은 패싯이며 노드마다 하나씩 항목을 만들면 이를 가득 채웁니다. 훅 스팬은 동일한 방식으로 렌더링되고 노드별 레이턴시를 제공합니다. + **노드, 스텝, 미들웨어 경계를 추적하고 싶다면?** 중첩된 `agent()` 대신 훅 쌍(`hook_triggered` / `hook_completed`)으로 감싸세요. `agent_id`는 저기수성 패싯이라 노드마다 항목이 생기면 목록이 넘쳐납니다. 훅 스팬은 동일하게 렌더링되면서 노드별 레이턴시를 제공합니다. - **수동 계측과 자동 계측은 함께 사용할 수 있습니다.** 직접 작성한 스코프 내에서 실행되는 어댑터는 해당 세션에 합류하고 해당 에이전트의 자식이 되므로, 두 개의 트리가 아닌 하나의 트리를 얻을 수 있습니다 — 지원되는 프레임워크와 함께 하나의 프레임워크를 직접 계측할 때 유용합니다. + **수동 계측과 자동 계측은 함께 동작합니다.** 직접 작성한 스코프 안에서 실행되는 어댑터는 해당 세션에 참여하고 해당 에이전트의 하위에 위치하므로, 두 개의 트리가 아닌 하나의 트리를 얻을 수 있습니다. 지원되는 프레임워크와 함께 다른 프레임워크를 직접 계측할 때 유용합니다. - 두 가지 이유가 있으며, 위의 세 가지 접합점이 그 답입니다: + 두 가지 이유가 있으며, 위의 세 가지 연결 지점이 두 경우 모두에 대한 답입니다: - - `autogen-core`는 2025년 9월부터 유지보수가 중단되었습니다. - - AG2는 다른 프레임워크의 훅에 상응하는 프로세스 전체 등록 지점을 노출하지 않아, 계측하려면 모든 생성 지점에서 각 에이전트를 감싸야 합니다. + - `autogen-core`는 2025년 9월 이후 유지 관리가 중단되었습니다. + - AG2는 다른 프레임워크들의 훅에 해당하는 프로세스 수준의 등록 지점을 제공하지 않기 때문에, 계측하려면 에이전트를 생성하는 모든 위치에서 래핑해야 합니다. - 접합점을 직접 매핑하면 제공되는 어댑터와 동일한 이벤트를 동일한 정밀도로 기록할 수 있습니다. + 연결 지점을 직접 매핑하면 출시된 어댑터와 동일한 이벤트를, 동일한 정밀도로 기록할 수 있습니다. ## 더 깊이 알아보기 -기록이 실제로 어떻게 동작하는지. 시작하는 데는 필요하지 않습니다. +레코딩이 실제로 동작하는 방식입니다. 시작하는 데 필요한 내용은 아닙니다. - + -모든 기록은 동일한 형태를 가집니다: 스팬이 열리고, 작업이 그 안에 중첩되고, 각 시작 이벤트에 종료 이벤트가 대응됩니다. +모든 레코딩은 동일한 형태를 가집니다. 스팬이 열리고, 그 안에 작업이 중첩되며, 각 열린 이벤트에 닫는 이벤트가 생깁니다. ```mermaid flowchart LR @@ -300,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -**쌍**이 기본 단위입니다. 각 종료 이벤트는 SDK가 시작 이벤트로부터 측정한 지속 시간을 포함합니다. +**쌍**이 기본 단위입니다. 각 닫는 이벤트는 SDK가 여는 이벤트부터 측정한 지속 시간을 가집니다. -아래는 프레임워크별 실제 실행 하나를 캡처한 것입니다 — SDK와 함께 제공되는 예제에서 가져왔으며 모델 이름은 정규화되었습니다. 단일 호출에서 얼마나 많은 정보가 반환되는지 확인하세요. +아래는 프레임워크별 실제 실행 결과입니다. SDK와 함께 제공되는 예시에서 캡처했으며 모델 이름은 정규화했습니다. 단 한 번의 호출에서 얼마나 많은 정보가 반환되는지 확인해 보세요. @@ -323,7 +323,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - 노드가 훅 쌍이 되므로 에이전트 목록을 채우지 않고도 노드별 레이턴시를 얻을 수 있습니다. + 노드가 훅 쌍이 되므로, 에이전트 목록을 복잡하게 만들지 않고도 노드별 레이턴시를 얻을 수 있습니다. @@ -340,7 +340,7 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - 각 에이전트의 `role`이 스팬 이름이 되므로 레이턴시와 토큰 사용량을 역할별로 분석할 수 있습니다. + 각 에이전트의 `role`이 스팬 이름이 되므로, 레이턴시와 토큰 사용량을 역할별로 분석할 수 있습니다. @@ -360,7 +360,7 @@ flowchart LR 26 +7.038s agent_end Agent · success ``` - 에이전트 루프 자체가 보이며, 모델 호출만이 아닙니다. + 에이전트 루프 자체가 보이며, 모델 호출만 보이는 것이 아닙니다. @@ -388,36 +388,36 @@ flowchart LR 6 +0.000s agent_end main · success ``` - 이것들을 직접 발행합니다. 동일한 이벤트 타입, 동일한 정밀도 — 호출 지점의 코드 작성이 필요합니다. + 직접 발행합니다. 동일한 이벤트 타입, 동일한 정밀도 — 호출 위치를 직접 작성하는 비용이 있습니다. - + -**세션 종료 이벤트는 없습니다.** 세션은 닫는 것이 아니라 `session_id`를 공유하는 이벤트들의 그룹입니다. +**세션 종료 이벤트는 없습니다.** 세션은 닫는 것이 아니라, `session_id`를 공유하는 이벤트들의 그룹입니다. 상태는 트레이스의 형태에서 도출됩니다: | 상태 | 조건 | | --- | --- | | `ongoing` | 적어도 하나의 스팬이 아직 열려 있음 | -| `paused` | `agent_pause`에 매칭되는 `agent_resume`가 없음 | -| `error` | 열린 것이 없고 최소 하나의 이벤트가 실패함 | -| `done` | 열린 것이 없고 실패한 것도 없음 | +| `paused` | `agent_pause`에 대응하는 `agent_resume`이 없음 | +| `error` | 열린 스팬이 없고, 적어도 하나의 이벤트가 실패함 | +| `done` | 열린 스팬이 없고, 실패한 이벤트도 없음 | -따라서 모든 쌍이 닫히면 세션이 종료됩니다. 어댑터는 `agent_end`를 자동으로 발행하며, 종료 시 아직 열려 있는 것은 모두 닫고 불완전으로 표시합니다 — 충돌한 실행은 영원히 걸리는 것이 아니라 눈에 보이는 갭과 함께 `done`으로 처리됩니다. +즉, 모든 쌍이 닫히면 세션이 종료됩니다. 어댑터는 `agent_end`를 자동으로 발행하며, 종료 시 아직 열려 있는 것들을 닫고 불완전으로 표시합니다. 충돌한 실행은 보이는 공백과 함께 `done`으로 정리되며 영원히 대기 상태로 남지 않습니다. - 이것이 세션이 두 번의 호출에 걸쳐 있을 수 있는 이유입니다. LangGraph의 `interrupt()`가 실행을 일시 중지하면 루트 스팬은 의도적으로 열려 있고, 재개 호출이 이를 닫습니다. 두 호출은 하나의 세션입니다. + 이것이 세션이 두 번의 호출에 걸쳐 있을 수 있는 이유입니다. LangGraph의 `interrupt()`는 실행을 일시 정지하고, 루트 스팬은 의도적으로 열린 상태를 유지하며, 재개하는 호출이 그것을 닫습니다. 두 호출은 하나의 세션입니다. - + -`session_id`와 `agent_id`는 모든 이벤트 메서드에서 선택적입니다. 생략하면 감싸는 스코프에서 해결됩니다: +`session_id`와 `agent_id`는 모든 이벤트 메서드에서 선택 사항입니다. 생략하면 감싸는 스코프에서 해결됩니다: ```python with failproofai_sdk.session(): @@ -425,139 +425,139 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -명시적으로 전달하는 것도 여전히 작동하며 우선적으로 적용됩니다. 바인딩된 것도 없고 전달된 것도 없으면, 세션 없이 이벤트를 발행하는 대신 수정 방법을 알려주는 `TypeError`가 발생합니다 — 인제스트는 세션 없는 이벤트를 건너뛰고 `200`으로 응답합니다. +명시적으로 전달하면 여전히 동작하며 우선순위를 가집니다. 바인딩된 것도 없고 전달된 것도 없으면, 세션 없이 이벤트를 발행하는 대신 수정 방법을 알려주는 `TypeError`가 발생합니다. 세션 없는 이벤트는 인제스트에서 건너뛰어지고 `200`으로 응답됩니다. -스코프는 컨텍스트 변수에 id를 바인딩합니다. asyncio 태스크에는 자동으로 전파되지만 새 스레드에는 전파되지 않습니다 — 워커를 `failproofai_sdk.propagate()`로 감싸세요. +스코프는 컨텍스트 변수에 식별자를 바인딩합니다. 이는 asyncio 태스크에는 자동으로 전파되지만 새 스레드에는 전파되지 않으므로, 워커를 `failproofai_sdk.propagate()`로 감싸야 합니다. -#### 어떤 id를 누가 생성하는가 +#### 누가 어떤 id를 생성하는가 -| Id | 생성 주체 | 비고 | +| Id | 생성자 | 비고 | | --- | --- | --- | -| `session_id` | 사용자 또는 SDK | `session("chat-42")`는 그대로 사용됨; 생략하면 SDK가 `uuid4().hex` 생성 | -| `agent_id` | 사용자 또는 프레임워크 | `agent("analyst")`, CrewAI `role`, `FunctionAgent.name`에서. UUID처럼 생긴 값은 거부되고 대체됨 | -| `tool_call_id`, `hook_id`, `request_id` | 사용자 또는 프레임워크 | 어댑터는 프레임워크 자체의 실행 id를 재사용하므로 쌍이 스레드 이동에서도 유지됨 | -| **이벤트 id** | **인제스트 시 클라우드** | SDK는 발행하지 않음 | -| **`dedup_key`** | **인제스트 시 클라우드** | 조직, 세션, 타임스탬프, 타입, 페이로드의 해시. 이것이 실제 id — 재시도된 배치가 중복 없이 합쳐지게 함 | +| `session_id` | 사용자 또는 SDK | `session("chat-42")`는 그대로 사용됨; 생략하면 SDK가 `uuid4().hex`를 생성 | +| `agent_id` | 사용자 또는 프레임워크 | `agent("analyst")`, CrewAI `role`, `FunctionAgent.name`에서 옴. UUID처럼 보이는 값은 거부되고 대체됨 | +| `tool_call_id`, `hook_id`, `request_id` | 사용자 또는 프레임워크 | 어댑터는 프레임워크 자체의 실행 id를 재사용하므로 쌍이 스레드 전환에서도 유지됨 | +| **이벤트 id** | **클라우드, 인제스트 시** | SDK는 발행하지 않음 | +| **`dedup_key`** | **클라우드, 인제스트 시** | 조직, 세션, 타임스탬프, 타입, 페이로드의 해시. 이것이 실제 식별자로, 재시도된 배치가 중복 대신 하나로 합쳐지게 함 | -#### 어댑터의 `session_id` 해결 방식 +#### 어댑터가 `session_id`를 해결하는 방식 -첫 번째 매치가 우선합니다: +첫 번째 매칭이 우선: 1. 명시적인 `session_id` 옵션 2. 호출별 메타데이터 3. 감싸는 `session()` 스코프 4. 프레임워크 메타데이터 -5. 프레임워크 자체의 실행 id +5. 프레임워크 자체 실행 id -이 중 하나가 존재하는 동안에는 id가 임의로 생성되지 않습니다 — 합성된 id는 하나의 실행을 여러 세션으로 분리할 수 있기 때문입니다. +이 중 하나가 존재하는 동안에는 임의로 생성되지 않습니다. 합성된 id는 하나의 실행을 여러 세션으로 분리하게 됩니다. -#### `agent_id`의 카디널리티를 낮게 유지하기 +#### `agent_id`는 저기수성으로 유지하세요 -모든 대시보드 화면의 주요 패싯이며 `LowCardinality(String)` 컬럼입니다. 실행당 값을 사용하면 컬럼의 성능을 저하시키고 필터 드롭다운에 실행당 하나의 항목이 가득 차게 됩니다. +모든 대시보드 화면의 주요 패싯이며 `LowCardinality(String)` 컬럼입니다. 실행별 값을 사용하면 컬럼 성능이 저하되고 필터 드롭다운에 실행마다 하나씩 항목이 쌓입니다. -어댑터가 이 컬럼을 자동으로 보호합니다: +어댑터는 이 컬럼을 자동으로 보호합니다: -| 프레임워크가 전달하는 것 | 기록되는 것 | 이유 | +| 프레임워크가 전달한 값 | 기록되는 값 | 이유 | | --- | --- | --- | -| `3f9a1c2b-…` (UUID) | `main` | 읽을 수 있는 내용이 없음 | +| `3f9a1c2b-…` (UUID) | `main` | 보존할 읽기 가능한 부분 없음 | | 긴 순수 16진수 문자열 | `main` | 동일 | -| `agent-3f9a1c2b-…` | `agent` | 실행별 id는 제거되고 읽을 수 있는 부분만 유지 | +| `agent-3f9a1c2b-…` | `agent` | 실행별 id 제거, 읽기 가능한 부분 유지 | | `agent-v2` | `agent-v2` | 짧은 세그먼트는 그대로 유지 | | `step-3` | `step-3` | 동일 | -실제 id는 `fw_agent_id` / `fw_run_id`에 유지되어 패싯이 되지 않으면서도 쿼리 가능합니다. +실제 id는 `fw_agent_id` / `fw_run_id`에 보존되어 패싯이 되지 않으면서도 쿼리 가능합니다. - **이 가드는 프레임워크가 선택한 레이블에만 적용됩니다.** `event.*`나 `failproofai_sdk.agent(...)`에 직접 전달하는 `agent_id`는 그대로 기록됩니다. 명시적인 인수를 조용히 재작성하는 것은 방지하려는 카디널리티 문제보다 더 나쁘기 때문입니다. 따라서 직접 명명한 스팬은 적절히 이름을 지으세요. + **이 보호는 프레임워크가 선택한 레이블에만 적용됩니다.** `event.*` 또는 `failproofai_sdk.agent(...)`에 직접 전달한 `agent_id`는 그대로 기록됩니다. 명시적인 인자를 조용히 재작성하는 것은 방지하려는 기수성 문제보다 더 나쁘기 때문입니다. 직접 작성하는 스팬 이름에 주의하세요. - + | 그룹 | 이벤트 | | --- | --- | | 에이전트 | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | | 모델 | `model_request`, `model_response` | -| 툴 | `tool_use`, `tool_result` | +| 도구 | `tool_use`, `tool_result` | | 훅 | `hook_triggered`, `hook_completed` | -| 휴먼 | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| 사람 | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | 실패 | `error` | -위의 실행에서 측정한 프레임워크별 기록 항목: +위의 실행 결과를 기준으로 프레임워크별 기록 여부: | 이벤트 | LangGraph | CrewAI | LlamaIndex | Pydantic AI | 커스텀 | | --- | :--: | :--: | :--: | :--: | :--: | | 에이전트 시작/종료 | 예 | 예 | 예 | 예 | 직접 | | 모델 요청/응답 | 예 | 예 | 예 | 예 | 직접 | -| 툴 사용/결과 | 예 | 예 | 예 | 예 | 직접 | -| 훅 트리거/완료 | 노드 | 태스크 | 스텝 | — | 직접 | +| 도구 사용/결과 | 예 | 예 | 예 | 예 | 직접 | +| 훅 시작/완료 | 노드 | 태스크 | 스텝 | — | 직접 | | 오류 | 예 | 예 | 예 | 예 | 자동 | -| 휴먼 대기/입력 | 예 | 예 | 예 | — | 직접 | +| 사람 대기/입력 | 예 | 예 | 예 | — | 직접 | | 에이전트 일시정지/재개 | 예 | 예 | 예 | — | 직접 | -대시(—)는 해당 프레임워크에 그런 개념이 없음을 의미합니다. `human_pause`와 `human_interrupt`는 에이전트에 개입하는 사람을 나타내며, 어떤 프레임워크도 이를 신호로 보내지 않으므로 직접 발행해야 합니다. +대시(—)는 프레임워크에 해당 개념이 없음을 의미합니다. `human_pause`와 `human_interrupt`는 에이전트에 _사람_이 개입하는 것을 나타내며, 어떤 프레임워크도 신호를 보내지 않으므로 직접 발행해야 합니다. - + -이벤트는 절대 단독으로 오지 않습니다. 하나가 스팬을 열고 하나가 닫으며, 종료 이벤트는 SDK가 시작 이벤트로부터 측정한 지속 시간을 포함합니다. +이벤트는 단독으로 도착하지 않습니다. 하나가 스팬을 열고, 하나가 닫으며, 닫는 이벤트는 SDK가 여는 이벤트부터 측정한 지속 시간을 가집니다. -| 시작 | 종료 | 종료 이벤트에 포함되는 것 | +| 여는 이벤트 | 닫는 이벤트 | 닫는 이벤트에 포함된 내용 | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | | `model_request` | `model_response` | 토큰, `stop_reason`, 레이턴시 | | `tool_use` | `tool_result` | `output` 또는 `error`, 지속 시간 | | `hook_triggered` | `hook_completed` | `outcome`, 지속 시간 | -| `agent_pause` | `agent_resume` | 일시정지 지속 시간 | -| `human_wait` | `human_input` | 응답, 그리고 사람이 걸린 시간 | +| `agent_pause` | `agent_resume` | 일시 정지 지속 시간 | +| `human_wait` | `human_input` | 응답, 응답까지 걸린 시간 | - 종료 이벤트가 없는 시작 이벤트는 영원히 끝나지 않는 스팬입니다. 세션은 영원히 실행 중으로 표시되고 활성 지속 시간이 계속 증가합니다. 직접 계측할 때 주의해야 할 실패 모드입니다. + 닫는 이벤트가 없는 여는 이벤트는 영원히 끝나지 않는 스팬입니다. 세션은 계속 실행 중으로 표시되고 활성 지속 시간이 계속 증가합니다. 이것이 수동 계측 시 주의해야 할 실패 패턴입니다. #### 상관관계 규칙 -- 매칭되는 완료 이벤트에 동일한 `tool_call_id`, `hook_id`, `pause_id`, 또는 `input_id`를 재사용하세요. -- SDK는 `tool_result`, `hook_completed`, `agent_resume`, `human_input`의 `duration_ms`를 계산합니다. 이 메서드들에 전달하면 `ValueError`가 발생합니다. -- `duration_ms`는 `model_response`에는 허용됩니다. 실제 프로바이더 레이턴시는 호출자만 알기 때문입니다. 정수여야 합니다 — float는 호출 지점에서 `ValueError`가 발생합니다. 서버가 해당 컬럼을 부호 없는 32비트 정수로 읽어 다른 값이면 NULL을 저장하기 때문입니다. -- 상관관계 키는 종류와 세션으로 범위가 지정되므로 툴 호출과 훅이 안전하게 id를 공유할 수 있고, 두 동시 세션이 충돌 없이 동일한 id를 재사용할 수 있습니다. 에이전트로는 범위가 지정되지 않습니다: 한 에이전트에서 열리고 다른 에이전트에서 닫힌 쌍도 여전히 상관관계를 가지며, 이것이 멀티 에이전트 프레임워크에서 일반적인 경우입니다. -- `request_id`는 `model_request`와 `model_response`를 쌍으로 묶습니다. 없으면 에이전트별 순서대로 모델 이벤트가 쌍을 이루어 동시 호출 시 잘못된 쌍이 만들어집니다. -- 프로세스에 걸쳐 분리된 쌍은 다운스트림에서 여전히 상관관계를 가지지만 SDK는 프로세스 내 지속 시간을 계산할 수 없습니다. -- 보류 맵은 최대 10,000개의 시작 이벤트를 보유하며 가득 찼을 때 가장 오래된 항목을 제거합니다. +- 매칭되는 완료 이벤트에 동일한 `tool_call_id`, `hook_id`, `pause_id`, `input_id`를 재사용하세요. +- SDK는 `tool_result`, `hook_completed`, `agent_resume`, `human_input`에 대해 `duration_ms`를 계산합니다. 이 메서드들에 전달하면 `ValueError`가 발생합니다. +- `duration_ms`는 `model_response`에서 **허용됩니다**. 실제 프로바이더 레이턴시는 호출자만 알기 때문입니다. 정수여야 합니다. 부동소수점은 호출 시점에 `ValueError`를 발생시킵니다. 서버가 해당 컬럼을 부호 없는 32비트 정수로 읽어 다른 값은 NULL로 저장하기 때문입니다. +- 상관관계 키는 종류와 세션별로 범위가 지정되므로, 도구 호출과 훅이 같은 id를 안전하게 공유할 수 있으며, 동시 세션도 동일한 id를 충돌 없이 재사용할 수 있습니다. 에이전트별로는 범위가 지정되지 않습니다. 한 에이전트 아래서 열리고 다른 에이전트 아래서 닫히는 쌍도 여전히 상관관계를 유지합니다. 이는 다중 에이전트 프레임워크에서 일반적인 경우입니다. +- `request_id`는 `model_request`와 `model_response`를 쌍으로 묶습니다. 없으면 모델 이벤트가 에이전트별 순서대로 쌍을 이루므로, 동시 호출 시 잘못된 쌍이 생깁니다. +- 프로세스를 넘나드는 쌍은 다운스트림에서도 상관관계를 유지하지만, SDK는 프로세스 내 지속 시간을 계산할 수 없습니다. +- 대기 중인 맵은 최대 10,000개의 시작 이벤트를 보유하며, 가득 차면 가장 오래된 항목을 삭제합니다. - + `failproofai-sdk`를 설치하면 네 가지 어댑터를 포함한 모든 것이 설치됩니다. extras는 어댑터가 아닌 **프레임워크**를 가져옵니다. ```python -import failproofai_sdk # 표준 라이브러리 외에는 아무것도 로드하지 않음 +import failproofai_sdk # 표준 라이브러리 외 아무것도 로드하지 않음 failproofai_sdk.instrument() # 실제로 필요한 어댑터만 임포트 ``` -`import failproofai_sdk`는 계약상 의존성이 없으며, `--no-deps`로 빌드된 wheel을 설치하는 테스트와 어떤 프레임워크도 `sys.modules`에 도달하지 않음을 증명하는 테스트로 강제됩니다. +`import failproofai_sdk`는 계약상 의존성이 없으며, `--no-deps`로 빌드된 wheel을 설치하는 테스트와 어떤 프레임워크도 `sys.modules`에 없음을 증명하는 테스트로 강제됩니다. - `failproofai_sdk.crewai` 속성은 없습니다. 어댑터는 의도적으로 최상위 패키지에 노출되지 않습니다: 속성에 접근하면 속성 접근의 부작용으로 프레임워크가 임포트되어 의존성 없음 약속이 깨집니다. `instrument()`를 사용하세요. + `failproofai_sdk.crewai` 속성은 없습니다. 어댑터는 의도적으로 최상위 패키지에 노출되지 않습니다. 하나를 건드리면 속성 접근의 부작용으로 프레임워크가 임포트되어 의존성 없음 약속이 깨집니다. `instrument()`를 사용하세요. ```python failproofai_sdk.instrument() # 이미 임포트된 모든 프레임워크 failproofai_sdk.instrument("crewai") # 이름으로 정확히 하나 -failproofai_sdk.uninstrument("crewai") # 원래대로 되돌리기 +failproofai_sdk.uninstrument("crewai") # 되돌리기 ``` -| 이름 | 대체 허용 | +| 이름 | 대체 이름 허용 | | --- | --- | | `langchain` | `langgraph`, `langchain_core` | | `crewai` | — | | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -자동 감지는 설치된 패키지 목록이 아닌 `sys.modules`를 읽으므로, 설치되었지만 임포트되지 않은 프레임워크는 계측되지 않으며 대신 임포트되지도 않습니다. 연결된 것을 확인하려면: +자동 탐지는 설치된 패키지 목록이 아닌 `sys.modules`를 읽으므로, 설치했지만 임포트하지 않은 프레임워크는 계측되지 않으며 임의로 임포트되지도 않습니다. 현재 연결된 것을 확인하려면: ```python from failproofai_sdk.integrations import active, available @@ -567,32 +567,32 @@ active() # ('langchain',) ``` - **CrewAI가 없는 머신에서 `instrument("crewai")`를 호출해도 예외가 발생하지 않습니다.** 경고를 로그로 출력하고 `()`를 반환하므로, 하나의 프레임워크가 없어도 다른 프레임워크를 계측하는 프로세스가 중단되지 않습니다. + **CrewAI가 없는 머신에서 `instrument("crewai")`를 호출해도 예외가 발생하지 않습니다.** 경고를 로그에 남기고 `()`를 반환하므로, 하나의 프레임워크가 없어도 다른 프레임워크를 계측하는 프로세스가 중단되지 않습니다. - 경고에는 기본 `ImportError`가 포함되며, 해당 메시지에 정확한 설치 명령이 나타납니다 — 수정 방법이 숨겨지지 않고 로그에 있습니다. + 경고에는 기본 `ImportError`가 포함되며, 해당 메시지에 정확한 설치 명령이 나와 있습니다. 수정 방법이 숨겨지지 않고 로그에 있습니다. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - 대신 예외를 발생시키려면 `FAILPROOFAI_SDK_STRICT=1`을 설정하세요. 해당 플래그는 **한 번 읽히고 캐시되므로** 실행 중에 설정하는 것이 아니라 프로세스 시작 전에 내보내야 합니다. + 예외를 발생시키려면 `FAILPROOFAI_SDK_STRICT=1`을 설정하세요. 이 플래그는 **한 번 읽히고 캐시되므로**, 실행 중에 설정하지 말고 프로세스 시작 전에 내보내세요. - **`instrument()`는 프레임워크 임포트 이후에 호출해야 합니다.** 자동 감지가 `sys.modules`를 읽으므로, 임포트 전에 호출하면 아무것도 찾지 못하고, 아무것도 설치하지 않고, `()`를 반환합니다. + **`instrument()`는 프레임워크 임포트 *이후*에 와야 합니다.** 자동 탐지는 `sys.modules`를 읽으므로, 임포트 전에 빈 호출을 하면 아무것도 찾지 못하고, 아무것도 설치하지 않고, `()`를 반환합니다. ```python Wrong import failproofai_sdk -failproofai_sdk.instrument() # sys.modules에 langchain이 아직 없음 -> () +failproofai_sdk.instrument() # sys.modules에 langchain 없음 -> () import langchain # 너무 늦음, 아무것도 연결되지 않음 ``` ```python Right -import langchain # 먼저 프레임워크를 임포트 +import langchain # 프레임워크를 먼저 임포트 import failproofai_sdk failproofai_sdk.instrument() # 찾음 -> ('langchain',) @@ -601,133 +601,135 @@ failproofai_sdk.instrument() # 찾음 -> ('langchain',) ```python Right, order-proof import failproofai_sdk -# 이름을 지정하면 어댑터를 요청 시 임포트하므로 어디서나 동작합니다. +# 이름으로 지정하면 요청 시 어댑터를 임포트하므로 어디서든 동작합니다. failproofai_sdk.instrument("langchain") ``` -이를 잘못하면 SDK가 임포트되고, 어댑터가 설치된 것처럼 보이며, **이벤트는 하나도 발행되지 않습니다**. 정확히 그 내용을 알려주는 경고가 로그로 출력됩니다 — 실행에서 아무것도 기록되지 않을 때 먼저 로그를 확인하세요. +잘못하면 SDK는 임포트되고 어댑터는 설치된 것처럼 보이지만 **이벤트가 하나도 발행되지 않습니다**. 정확히 그 내용을 알리는 경고를 로그에 남기므로, 실행이 아무것도 기록하지 않을 때 로그를 먼저 확인하세요. - + ```mermaid flowchart LR - A["에이전트"] --> B["어댑터"] - B --> C["Writer
인메모리 큐"] - C -->|"0.5초마다"| D["Spool
디스크의 JSONL"] - D --> E["Failproof 데몬"] - E -->|"HTTPS"| F["클라우드"] + A["Your agent"] --> B["Adapter"] + B --> C["Writer
in-memory queue"] + C -->|"every 0.5s"| D["Spool
JSONL on disk"] + D --> E["Failproof daemon"] + E -->|"HTTPS"| F["Cloud"] ``` | 단계 | 역할 | 실행 위치 | | --- | --- | --- | | 어댑터 | 프레임워크 콜백을 15가지 이벤트 타입 중 하나로 변환 | 사용자 프로세스 | -| Writer | 큐에 넣고, 배치로 묶고, JSONL을 원자적으로 작성 | 사용자 프로세스, 백그라운드 스레드 | -| Spool | 내구성 있는 핸드오프, 프로세스 종료 후에도 유지 | 로컬 디스크 | -| 데몬 | spool을 감시하고, 배치를 전송하고, 전송된 것을 삭제 | 사용자 머신 | -| 인제스트 | 행 id와 dedup 키를 할당하고, 쿼리 가능한 컬럼을 승격 | 클라우드 | +| 라이터 | 큐에 넣고, 배치로 묶어, JSONL을 원자적으로 쓰기 | 사용자 프로세스, 백그라운드 스레드 | +| 스풀 | 프로세스 종료에도 살아남는 내구성 있는 전달 지점 | 로컬 디스크 | +| 데몬 | 스풀을 감시하고, 배치를 전송하고, 전송한 것을 삭제 | 사용자 머신 | +| 인제스트 | 행 id와 dedup 키를 부여하고, 쿼리 가능한 컬럼으로 승격 | 클라우드 | -spool이 이 방식을 안전하게 만드는 요소입니다: 에이전트는 네트워크를 기다리지 않으며, 클라우드 장애는 이벤트 손실이 아닌 디렉토리 증가를 의미합니다. +스풀이 안전성의 핵심입니다. 에이전트는 네트워크에서 절대 차단되지 않으며, 클라우드 장애 시 이벤트가 유실되는 대신 디렉터리가 커집니다. -각 플러시는 하나의 배치 파일을 작성합니다. `.tmp` 먼저, 그 다음 `fsync`, 그 다음 원자적 이름 변경: +각 플러시는 하나의 배치 파일을 씁니다. `.tmp`로 먼저 쓰고, `fsync`한 뒤, 원자적으로 이름을 변경합니다: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -데몬은 `.jsonl`만 읽으므로 절반만 작성된 파일을 읽을 수 없습니다. 파일 이름에 타임스탬프, 프로세스 id, 순번이 포함되어 같은 밀리초에 두 프로세스가 플러시해도 충돌하지 않습니다. 큐는 10,000개의 이벤트로 제한되며, 초과 시 가장 오래된 것을 삭제하고 로그로 출력합니다. +데몬은 `.jsonl`만 읽으므로 절반만 쓰인 파일을 읽을 수 없습니다. 파일명에 타임스탬프, 프로세스 id, 시퀀스 번호가 포함되어 있어 두 프로세스가 같은 밀리초에 플러시해도 충돌하지 않습니다. 큐는 10,000개 이벤트로 제한되며, 초과 시 가장 오래된 것을 삭제하고 로그를 남깁니다. - **`collector.redact`는 SDK 이벤트에도 기본값이 `minimal`입니다.** SDK는 배치를 디스크에 작성하기 전에 스크럽하고, 데몬은 이전 SDK의 배치도 보호될 수 있도록 업로드 전에 동일한 결정적 처리를 반복합니다. + **`collector.redact`는 SDK 이벤트에 적용되지 않습니다.** 절대 해당 이벤트를 볼 수 없습니다. -데몬은 각 배치를 읽고 업로드 전에 메모리에서 리댁션을 적용합니다. 읽은 spool 파일은 재작성하지 않습니다. +데몬은 배치를 **전송**합니다. 열거나 다시 쓰지 않습니다. -| 이벤트 | 작성 주체 | 최소 리댁션 실행 위치 | +| 이벤트 | 작성자 | `collector.redact` 적용 여부 | | --- | --- | --- | -| CLI 세션 트랜스크립트 | 데몬 | 데몬이 배치를 작성하기 전 | -| 훅 활동 | 데몬 | 데몬이 배치를 작성하기 전 | -| **SDK가 발행하는 모든 것** | **사용자 프로세스** | **SDK가 배치를 작성하기 전, 그리고 데몬 업로드 전 다시** | +| CLI 세션 트랜스크립트 | 데몬 | 예 | +| 훅 활동 | 데몬 | 예 | +| **SDK가 발행하는 모든 것** | **사용자 프로세스** | **아니오** | -페이로드를 그대로 보내는 것이 명시적인 요구사항인 경우에만 `collector.redact`를 `off`로 설정하세요. SDK와 데몬 모두 해당 설정을 따릅니다. 최소 리댁션은 일반적인 API 키, 베어러 토큰, JWT, 시크릿 할당을 잡아냅니다. 임의의 민감한 내용은 식별할 수 없습니다. +리댁션은 데몬이 자체 이벤트를 *쓰는* 곳에서 실행됩니다. 배치가 *전송*되는 곳이 아닙니다. 따라서 API 키를 포함한 프롬프트나 도구 인자는 도착 시에도 그대로입니다. + +이는 의도적입니다. 이것은 사용자 자신의 계측 호출이며, 전송 중에 이를 재작성하면 받은 이벤트가 발행한 이벤트와 다르게 됩니다. - **소스에서 페이로드를 두 곳에서 제어할 수 있습니다:** + **페이로드는 소스에서 두 곳에서 제어할 수 있습니다:** - - 어댑터에서 콘텐츠 캡처를 끄세요. **옵션 이름이 다르며, 하나의 어댑터에는 없습니다** — 이것은 단일 범용 스위치가 아닙니다: + - 어댑터에서 콘텐츠 캡처를 끄세요. **옵션 이름이 다르며, 하나의 어댑터에는 옵션이 없습니다.** 이것은 단일 범용 스위치가 아닙니다: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **콘텐츠 스위치 없음**; `session_id`만 읽으므로 프롬프트와 완성 내용이 항상 기록됩니다. + - CrewAI — **콘텐츠 스위치 없음**; `session_id`가 읽는 유일한 옵션이므로 프롬프트와 완성은 항상 기록됩니다. - `instrument()`는 어댑터가 읽지 않는 옵션을 무시하므로, 잘못된 이름을 전달해도 예외가 발생하지 않고 아무것도 변경되지 않습니다. - - 애초에 `input=`에 시크릿을 전달하지 마세요. + `instrument()`는 어댑터가 읽지 않는 옵션을 무시하므로, 잘못된 이름을 전달해도 오류 없이 아무 변화도 없습니다. + - 처음부터 `input=`에 비밀을 전달하지 마세요. - `collector.redact`는 심층 방어이며, 이 둘 중 어느 것의 대체가 아닙니다. + `collector.redact`는 두 경우 중 어느 것도 대체하지 않습니다. - **spool 디렉토리가 비어 있는 것이 정상 상태입니다.** 이것으로 전달 여부를 확인하지 마세요. + **빈 스풀 디렉터리가 정상 상태입니다.** 전달 여부 확인에 사용하지 마세요. -데몬은 배치를 전송한 후 수 밀리초 내에 삭제하므로, `ls`는 콜렉터와 경쟁하여 발행한 것의 일부만 보여줍니다 — 아무것도 기록하지 않은 SDK와 구별할 수 없습니다. +데몬은 각 배치를 전송 후 수 밀리초 내에 삭제하므로, `ls`를 실행하면 수집기와 경쟁하게 되어 발행한 것의 일부만 보입니다. 아무것도 기록하지 않은 SDK와 구분할 수 없습니다. -이벤트가 실제로 전달되었는지 확인하려면 대시보드를 확인하세요. spool이 채워지는 것을 보려면 먼저 데몬을 중지하세요. +이벤트가 실제로 도달했는지 확인하려면 대시보드를 확인하세요. 스풀이 채워지는 것을 관찰하려면 먼저 데몬을 중지하세요. -모든 콜백은 단 하나의 역할만 하는 래퍼 안에서 실행됩니다 — 다시 발생시키는 것. 따라서 호출은 정확히 하나의 `try`에 있으며 SDK가 하는 모든 일은 그 밖에서 일어납니다. +모든 콜백은 재발생만을 담당하는 래퍼 안에서 실행됩니다. 따라서 호출은 정확히 하나의 `try` 안에 있고, SDK가 하는 모든 것은 그 밖에서 일어납니다. -| 발생 상황 | 결과 | +| 발생한 상황 | 결과 | | --- | --- | -| 훅에서 예외 발생 | 트레이스백과 함께 한 번 로그됨. 호출에 영향 없음 | -| 같은 훅에서 세 번 예외 발생 | 해당 훅만 프로세스의 나머지 동안 비활성화되며, 오류 한 줄 출력 | -| `FAILPROOFAI_SDK_STRICT=1` 설정 | 대신 예외가 다시 발생 | -| 프레임워크 버전이 테스트 범위 밖 | 한 번 경고하고 계측은 진행 | -| 단일 기능 누락 | 해당 훅만 비활성화되며, 전체 어댑터는 아님 | +| 훅이 예외 발생 | 트레이스백과 함께 한 번 로그됨. 호출에는 영향 없음 | +| 같은 훅이 세 번 예외 발생 | 해당 훅만 프로세스 나머지 동안 비활성화, 오류 한 줄 | +| `FAILPROOFAI_SDK_STRICT=1` 설정됨 | 예외가 대신 다시 발생 | +| 프레임워크 버전이 테스트 범위 밖 | 한 번 경고, 그래도 계측 진행 | +| 단일 기능이 없음 | 해당 훅만 비활성화, 어댑터 전체는 아님 | -기본값은 프로덕션에서는 맞고 디버깅 중에는 틀립니다. "충돌하지 않았다"는 것만 증명할 수 있기 때문입니다. 삼켜진 실패를 명확히 드러내려면 `FAILPROOFAI_SDK_STRICT=1`을 설정하세요. +기본값은 프로덕션에서는 맞고 디버깅 시에는 맞지 않습니다. "충돌하지 않았다"는 것만 증명할 수 있기 때문입니다. 삼켜진 실패를 드러내려면 `FAILPROOFAI_SDK_STRICT=1`을 설정하세요. -## 일반적인 문제 +## 자주 발생하는 문제 - - 시작 이벤트에 대응하는 종료 이벤트가 없습니다: `model_response`가 없는 `model_request`, 또는 `tool_result`가 없는 `tool_use`. 본문에서 예외가 발생해도 쌍을 보장하는 스코프를 사용하세요. 이벤트 메서드를 직접 호출한다면 `try`와 `finally`를 사용하세요. + + 여는 이벤트에 닫는 이벤트가 없는 경우입니다. `model_request`에 `model_response`가 없거나 `tool_use`에 `tool_result`가 없는 경우입니다. 본문에서 예외가 발생해도 쌍을 보장하는 스코프를 사용하세요. 이벤트 메서드를 직접 호출한다면 `try`와 `finally`를 사용하세요. - - 매칭되는 시작 이벤트로부터 측정되므로 `tool_result`, `hook_completed`, `agent_resume`, `human_input`에서는 거부됩니다. 실제 프로바이더 레이턴시는 사용자만 알기 때문에 `model_response`에서는 허용되며, 정수여야 합니다. + + 매칭되는 여는 이벤트부터 측정되므로, `tool_result`, `hook_completed`, `agent_resume`, `human_input`에서는 거부됩니다. `model_response`에서는 허용되며, 실제 프로바이더 레이턴시는 사용자만 알기 때문입니다. 정수여야 합니다. - - 스레드가 컨텍스트를 상속받지 않았습니다. callable을 `failproofai_sdk.propagate()`로 감싸세요. [스레드와 비동기](#threads-and-async)를 참조하세요. + + 스레드가 컨텍스트를 상속받지 못했습니다. callable을 `failproofai_sdk.propagate()`로 감싸세요. [스레드와 비동기](#threads-and-async)를 참고하세요. - - 추가 필드는 마지막에 병합되므로 `model`이나 `outcome` 같은 실제 필드와 같은 이름을 사용하면 덮어씌워져 저장된 컬럼이 변경됩니다. 네임스페이스를 사용하세요. 어댑터는 `fw_` 접두사를 사용합니다. + + 추가 필드는 마지막에 병합되므로, `model`이나 `outcome` 같은 실제 필드와 같은 이름이면 덮어쓰고 저장된 컬럼을 변경합니다. 네임스페이스를 사용하세요. 어댑터는 `fw_` 접두사를 사용합니다. - `agent_id`는 카디널리티가 낮은 패싯인데 실행 id를 넣었습니다. 역할이나 노드 이름을 사용하고 실제 id는 페이로드 필드에 넣으세요. + `agent_id`는 저기수성 패싯인데 실행 id를 넣었습니다. 역할이나 노드 이름을 사용하고 실제 id는 페이로드 필드에 넣으세요. ## 다음 단계 - - 쌍, id, 세션 생명주기, 그리고 전달. + + 쌍, id, 세션 생명주기, 전달 방식. - 방금 캡처한 세션에서 인과관계를 추적합니다. + 방금 캡처한 세션의 인과관계를 따라가세요. LangGraph, CrewAI, LlamaIndex, Pydantic AI. diff --git a/docs/ko/start/quickstart.mdx b/docs/ko/start/quickstart.mdx index aa2d4685..627cea54 100644 --- a/docs/ko/start/quickstart.mdx +++ b/docs/ko/start/quickstart.mdx @@ -1,12 +1,12 @@ --- title: "빠른 시작" -description: "에이전트 세션을 캡처하고, 실패를 발견하고, 예방을 시작하세요." +description: "에이전트 세션을 캡처하고, 실패를 찾고, 이를 방지하기 시작하세요." icon: "zap" --- -이 빠른 시작 가이드는 하나의 머신에서 세션을 보고하고, 감사를 실행하고, 정책을 배포하는 과정을 안내합니다. 스킬을 사용하거나 수동 단계를 따라 Failproof AI를 설정하세요. +이 빠른 시작 가이드는 한 대의 머신에서 세션을 보고하도록 설정하고, 감사를 실행하며, 정책을 배포하는 과정을 안내합니다. 스킬을 사용하거나 수동 단계를 따라 Failproof AI를 설정하세요. -**어떤 방법을 선택할까요?** 에이전트가 지원되는 12개의 [하네스](/ko/reference/harnesses) 중 하나에서 실행되는 경우 — 코딩 CLI, 또는 Hermes나 OpenClaw 같은 게이트웨이 — 아래 단계를 따르세요. Node.js 20.9 이상이 필요합니다. 에이전트에 하네스가 없는 경우, 추적과 감사를 위해 [Python SDK](/ko/reference/custom-agents)로 계측한 후 [첫 번째 실패 검사 실행](/ko/start/first-audit)에서 다시 합류하세요. 이 경로에서 적용(enforcement)은 런타임에 훅이 필요합니다. +**어떤 방법을 선택하시겠어요?** 에이전트가 12개의 지원 [하네스](/ko/reference/harnesses) 중 하나(코딩 CLI, 또는 Hermes나 OpenClaw 같은 게이트웨이)에서 실행된다면 아래 단계를 따르세요. Node.js 20.9 이상이 필요합니다. 에이전트에 하네스가 없다면 추적 및 감사를 위해 [Python SDK](/ko/reference/custom-agents)로 계측한 후, [첫 번째 실패 검사 실행](/ko/start/first-audit)에서 다시 합류하세요. 해당 경로에서의 적용(enforcement)은 런타임에 훅이 필요합니다. @@ -16,24 +16,24 @@ icon: "zap" npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - 에이전트가 프로젝트를 검사하고, 관련 통합을 선택하고, 설정을 수행하고, 검증합니다. 개별 스킬과 고급 설치 옵션은 [FailproofAI 스킬 저장소](https://github.com/FailproofAI/skills)를 참고하세요. + 에이전트가 프로젝트를 검사하고, 관련 통합을 선택하며, 설정을 수행하고, 검증합니다. 개별 스킬 및 고급 설치 옵션은 [FailproofAI 스킬 저장소](https://github.com/FailproofAI/skills)를 참조하세요. ## 시작 전 준비 -1. [Failproof AI 대시보드](https://app.befailproof.ai)를 열고 계정을 만들거나 업무용 이메일로 로그인하세요. -2. **Administration → Keys**로 이동하여 `events:add`와 `policies:pull` 권한이 있는 키를 생성하세요. -3. 일회용 시크릿을 복사하여 대상 머신에 저장하세요: +1. [Failproof AI 대시보드](https://app.befailproof.ai)를 열고 계정을 생성하거나 업무용 이메일로 로그인하세요. +2. **관리 → 키**로 이동하여 `events:add`와 `policies:pull` 권한을 가진 키를 생성하세요. +3. 일회성 시크릿을 복사한 후, 대상 머신의 셸로 읽어 들이세요. `read -s`는 에코되지 않는 프롬프트에서 입력을 받으므로 명령어에 노출되지 않습니다: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## 설치 @@ -42,12 +42,18 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - 기본적으로 세션 트랜스크립트가 전송됩니다. `--no-transcripts`를 추가하면 트랜스크립트 내용 없이 훅 활동과 정책 결정만 보고합니다. + 이 단 하나의 명령으로 전체 설정이 완료됩니다. 로컬 데몬을 설치하고(루트 권한 한 번 필요), 발견된 모든 에이전트 CLI에 훅을 연결하며, 이 머신을 Cloud에 연결합니다. 키를 `--token`이 아닌 환경 변수로 전달하면 `ps`에서 노출되지 않습니다(머신의 모든 사용자가 명령의 인수를 볼 수 있기 때문). 단, 셸 히스토리에는 남을 수 있으므로, `read -s`로 읽어 들이는 것이 그것을 방지합니다. CI에서는 마스킹된 시크릿으로 주입하고 셸 추적(`set -x`)을 끄세요. 추적이 켜져 있으면 키가 출력됩니다. - 이 머신에 이미 에이전트 히스토리가 있다면, 최근 7일간의 데이터를 미리 보고 가져온 후 전송이 완료될 때까지 기다리세요. 새 머신이라면 이 단계를 건너뛰세요. + 세션 트랜스크립트는 기본적으로 전송됩니다. 트랜스크립트 내용 없이 훅 활동과 정책 결정만 보고하려면 `--no-transcripts`를 추가하세요. + + + 여기서 `failproofai config --connect `을 사용하지 마세요. 이 플래그는 **이미** 설정된 머신을 등록하고 바로 반환합니다. 데몬도, 훅도 설정되지 않으므로, 머신이 Cloud에는 나타나지만 실제로는 아무것도 수집하거나 적용하지 않게 됩니다. + + + 이 머신에 이미 에이전트 기록이 있다면, 최근 7일치를 미리 보고 가져온 후 전달이 완료될 때까지 기다리세요. 새 머신이라면 이 단계를 건너뛰세요. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +61,41 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Failproof AI에서 **Sessions**를 열고 가져온 세션을 선택하세요. + Failproof AI에서 **세션**을 열고 가져온 세션을 선택하세요. - - 이 단계는 Failproof AI를 하네스에 연결하고 39개의 기본 제공 정책을 설치합니다. 이를 통해 로컬 정책 결정을 확인하고, Failproof AI가 세션을 감사하고 에이전트를 위한 정책을 작성하기 전에 적용을 시험해볼 수 있습니다. - - 설치 프로그램이 하네스를 자동으로 감지하게 하거나, 명시적으로 지정할 수 있습니다. 12개 모두 유효한 `--cli` 값입니다 — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + 이전 단계에서 감지된 모든 에이전트 CLI에 이미 연결이 완료되었습니다. 필요할 때 특정 하네스에 대해 명시적으로 재실행하거나, 이후에 설치된 하네스를 추가할 때 사용하세요. 12개 모두 유효한 `--cli` 값입니다 — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # 코딩 CLI failproofai policies --install --cli hermes --scope user # Slack/Telegram 게이트웨이 ``` - 도구 호출을 실행 전에 차단하는 기능은 12개 모두에서 검증되었습니다. 턴 종료 게이트는 8개에서 검증되었습니다 — 하네스별 매트릭스는 [적용 기능](/ko/reference/harnesses#enforcement-capability)을 참고하세요. + 실행 전에 도구 호출을 차단하는 기능은 12개 모두에서 검증됩니다. 턴 종료 게이트는 8개에서 검증됩니다 — 하네스별 매트릭스는 [적용 기능](/ko/reference/harnesses#enforcement-capability)을 참조하세요. + + + 훅 연결 자체는 어떤 정책도 활성화하지 않습니다. 설정 시 정책을 의도적으로 선택하지 않습니다 — 그 결정은 여러분의 것입니다. 다음과 같이 팩을 가져오세요: + + ```bash + failproofai policies add FailproofAI/policies + ``` + + 팩은 GitHub 릴리스에서 가져와 체크섬이 검증되고, 해석된 정확한 태그에 고정됩니다. 38개의 정책이 포함되어 있으며, 매니페스트에서 무인 활성화가 안전하다고 표시된 10개가 켜집니다. 이를 통해 Failproof AI가 세션을 감사하고 에이전트를 위한 정책을 작성하기 전에 로컬 정책 결정을 확인하고 적용을 시험해볼 수 있습니다. + + `failproofai policies show /`로 가져오기 전에 팩을 먼저 읽어보고, 일부만 가져오는 방법은 [정책 팩](/ko/policies/packs)을 참조하세요. + + 이 단계가 실행되기 전까지는 `block-failproofai-commands`만 적용됩니다 — 이는 에이전트가 Failproof AI를 끄지 못하도록 막는 항상 켜져 있는 가드입니다. `failproofai policies`로 현재 활성화된 정책을 확인할 수 있습니다. [첫 번째 실패 검사 실행](/ko/start/first-audit)을 따르세요. "에이전트가 접근 방식을 변경하지 않고 실패한 도구를 재시도한 세션 찾기"와 같이 구체적인 목표를 사용하세요. - - [정책으로 첫 번째 실패 예방하기](/ko/start/first-policy)를 따르세요. 관찰 모드에서 시작하고, 매칭을 검사한 후, 검토된 버전을 적용하세요. + + [정책으로 첫 번째 실패 방지](/ko/start/first-policy)를 따르세요. 관찰 모드에서 시작하여 매칭을 검사한 후, 검토된 버전을 적용하세요. - `failproofai config --status`를 실행하세요. 정상적인 설정은 클라우드 연결, 데몬 상태, 그리고 적용이 일시 중지되어 있는지 여부를 보고합니다. + `failproofai config --status`를 실행하세요. 정상적인 설정은 클라우드 연결, 데몬 상태, 적용(enforcement) 일시 중지 여부를 보고합니다. \ No newline at end of file diff --git a/docs/ko/start/setup.mdx b/docs/ko/start/setup.mdx index f1522377..97a404ea 100644 --- a/docs/ko/start/setup.mdx +++ b/docs/ko/start/setup.mdx @@ -1,68 +1,89 @@ --- -title: "설정 방법 선택" -description: "로컬 강제 적용, Failproof AI Cloud, 또는 엔터프라이즈 배포 중에서 선택하세요." +title: "설정 방식 선택" +description: "로컬 적용, Failproof AI Cloud, 또는 엔터프라이즈 배포 중 선택하세요." icon: "waypoints" --- - - 머신에 훅과 정책을 설치합니다. 세션 데이터를 Cloud에 전송하지 않고 즉시 가드레일이 필요한 경우에 사용하세요. + + Cloud 키 없이 머신을 설정하고 정책 팩을 적용합니다. 세션 데이터를 Cloud에 전송하지 않고 즉시 가드레일이 필요할 때 사용하세요. - 중앙화된 세션 관리, 감사, 온라인 평가, 대시보드, 알림, 그리고 플릿 정책 배포 기능을 추가합니다. + 중앙화된 세션, 감사, 온라인 평가, 대시보드, 알림, 그리고 플릿 정책 배포 기능을 추가합니다. - 조직 제어, 범위 지정 키, 프라이빗 인프라, 그리고 배포별 보안 요구사항을 활용합니다. + 조직 제어, 범위가 지정된 키, 프라이빗 인프라, 그리고 배포별 보안 요구사항을 활용합니다. +## 로컬 적용 + +키 없이 `failproofai config`를 실행한 다음 `failproofai policies add FailproofAI/policies`로 팩을 적용하세요. 터미널에서 설정 시 Cloud 연결 여부를 묻는 질문이 나오면 **지금은 아님 — 로컬 유지**를 선택하세요. 터미널이 없거나 `FAILPROOFAI_CLOUD_TOKEN`이 없으면 자동으로 로컬 모드로 유지됩니다. 데몬과 훅은 해당 머신에서 적용되며, 세션 데이터는 Cloud로 전송되지 않습니다. 나중에 연결하려면 아래 단계를 따르세요. + ## 권장 프로덕션 경로 -1. 트랜스크립트 캡처를 활성화한 상태로 비프로덕션 머신을 연결합니다. -2. Cloud에서 세션과 평가 결과를 확인합니다. -3. 알려진 장애 유형에 대한 감사를 생성합니다. -4. 첫 번째 정책을 관찰 모드로 배포합니다. -5. 매치 결과와 오탐을 검토한 후 프로덕션으로 확대합니다. +1. 트랜스크립트 캡처가 활성화된 비프로덕션 머신을 연결합니다. +2. Cloud에서 세션과 평가를 확인합니다. +3. 알려진 오류 사례에 대한 감사를 생성합니다. +4. 관찰 모드로 첫 번째 정책을 배포합니다. +5. 매칭 결과와 거짓 양성을 검토한 후 프로덕션으로 확장합니다. -## 머신을 Cloud에 연결하기 +## Cloud에 머신 연결 - 1. **Administration → Keys**로 이동하여 `events:add` 및 `policies:pull` 권한이 있는 키를 생성합니다. + 1. **Administration → Keys**로 이동하여 `events:add`와 `policies:pull` 권한이 있는 키를 생성합니다. 2. 일회용 시크릿을 대상 머신에 복사합니다. 3. CLI 연결 명령을 실행한 후 **Admin → enforcement**로 이동하여 머신이 표시되는지 확인합니다. 4. **Observe → Events**로 이동하여 첫 번째 이벤트가 도착하는지 확인합니다. - 키 드로어에는 연결된 머신에 필요한 두 가지 권한이 표시됩니다: 이벤트 수집과 정책 전달입니다. + 키 서랍에는 연결된 머신에 필요한 두 가지 권한(이벤트 수집 및 정책 전달)이 표시됩니다. - ![이벤트 수집 및 정책 전달 권한을 부여하는 새 API 키 드로어](/images/dashboard/key-create.png) + ![이벤트 수집 및 정책 전달 권한을 부여하는 데 사용되는 새 API 키 서랍.](/images/dashboard/key-create.png) - 연결 후, 머신이 원하는 정책 상태 및 배포 상태와 함께 enforcement에 표시되어야 합니다. + 연결 후 머신은 원하는 정책 상태와 배포 상태가 표시된 상태로 enforcement에 나타나야 합니다. - ![등록된 머신의 원하는 정책 상태와 배포 상태가 펼쳐진 Enforcement 플릿](/images/dashboard/enforcement-fleet.png) + ![등록된 머신의 원하는 정책 상태와 배포 상태가 펼쳐진 Enforcement 플릿.](/images/dashboard/enforcement-fleet.png) - 첫 번째 이벤트가 도착하면 데몬이 정책 배포와 독립적으로 Cloud에 데이터를 전달할 수 있음을 확인합니다. + 첫 번째 이벤트 도착은 정책 배포와 독립적으로 데몬이 Cloud에 데이터를 전달할 수 있음을 확인해 줍니다. - ![최근 에이전트, 모델, 도구 이벤트를 보여주는 실시간 이벤트 스트림](/images/dashboard/events-stream-current.png) + ![최근 에이전트, 모델, 툴 이벤트를 표시하는 실시간 이벤트 스트림.](/images/dashboard/events-stream-current.png) - 머신과 첫 번째 이벤트가 모두 표시된 후에만 다음 단계로 진행하세요. + 머신과 첫 번째 이벤트가 모두 표시된 것을 확인한 후에만 계속 진행하세요. + 일회용 시크릿을 셸로 읽어들입니다. `read -s`는 에코되지 않는 프롬프트에서 입력을 받으므로, 명령어나 셸 히스토리에 절대 나타나지 않습니다: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + 그런 다음 머신을 설정하고, 정책을 선택하고, 이름을 지정합니다: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` + `failproofai config`는 전체 설정(데몬, 발견된 모든 에이전트 CLI에 대한 훅, Cloud 연결)을 수행한 후 정책은 선택하지 않습니다. 정책 선택은 두 번째 명령어를 위한 것입니다. + + 레이블은 연결 **이후에** 지정하세요. 연결 중에 지정하는 것이 아닙니다: `failproofai config --machine-label `은 이미 연결된 머신의 이름을 변경하며, 연결되지 않은 머신에서는 그 사실만 알려줄 뿐 아무것도 하지 않습니다. + 트랜스크립트 내용을 로컬에 유지해야 하는 경우 `--no-transcripts`를 추가하세요. + + CI 환경에서는 `read -s` 대신 시크릿 스토어에서 `FAILPROOFAI_CLOUD_TOKEN`을 설정하고, 셸 트레이싱(`set -x`)은 키가 출력될 수 있으므로 꺼두세요. + + + **이미** 설정된 머신에서 `failproofai config --connect `은 등록만 수행하며 그 외에는 아무것도 하지 않습니다. 최초 설치에 이 형식을 사용하지 마세요: 데몬이나 훅이 준비되기 전에 반환되어, Cloud에는 표시되지만 아무것도 수집하거나 적용하지 않는 머신이 남게 됩니다. + -Cloud에 연결하면 이벤트 수집과 정책 전달이 각각 독립적으로 검증됩니다. 따라서 키가 유효하더라도 필요한 권한 중 하나가 누락될 수 있습니다. 어떤 기능이 구성되어 있는지 확인하려면 `failproofai config --status`를 사용하세요. +Cloud 연결은 이벤트 수집과 정책 전달을 독립적으로 검증합니다. 따라서 키가 유효하더라도 필수 권한 중 하나가 누락될 수 있습니다. `failproofai config --status`를 사용하여 어떤 기능이 구성되어 있는지 확인하세요. - Cloud 설정은 해당 기능 검증이 성공한 후에만 로컬 자격 증명을 기록합니다. 검증에 실패하더라도 실제로 연결되지 않은 머신이 연결된 것처럼 보이는 상태로 남지 않습니다. + Cloud 설정은 해당 기능 검증이 성공한 후에만 로컬 자격증명을 기록합니다. 검증에 실패해도 실제로는 연결되지 않은 머신이 연결된 것처럼 보이는 상태로 남지 않습니다. \ No newline at end of file diff --git a/docs/pt-br/admin/keys-and-permissions.mdx b/docs/pt-br/admin/keys-and-permissions.mdx index 8631199b..62aaf47a 100644 --- a/docs/pt-br/admin/keys-and-permissions.mdx +++ b/docs/pt-br/admin/keys-and-permissions.mdx @@ -10,20 +10,20 @@ As chaves de API pertencem a uma organização e carregam permissões explícita - 1. Acesse **Administration → Keys**, selecione **new key** e informe um nome para a carga de trabalho. - 2. Escolha um conjunto de permissões e ajuste permissões individuais apenas quando o preset for insuficiente. - 3. Crie a chave e copie o segredo de uso único imediatamente. + 1. Acesse **Administration → Keys**, selecione **new key** e insira um nome para a carga de trabalho. + 2. Escolha um conjunto de permissões e ajuste as permissões individuais somente quando o preset não for suficiente. + 3. Crie a chave e copie o segredo único imediatamente. 4. Abra a chave posteriormente para atualizar concessões, desativá-la ou regenerar o segredo. - O painel de criação é onde você escolhe as concessões mais restritas necessárias para a carga de trabalho. + O painel de criação é onde você escolhe as concessões mais restritas exigidas pela carga de trabalho. ![O painel de nova chave de API com presets de permissão e concessões individuais.](/images/dashboard/key-create.png) - Após a criação, a página Keys exibe os metadados persistentes e as ações de gerenciamento. O segredo de uso único não é exibido novamente. + Após a criação, a página Keys exibe os metadados persistentes e as ações de gerenciamento. O segredo único não é exibido novamente. - ![A página de Chaves de API exibindo permissões, data de criação e ações de regenerar e desativar.](/images/dashboard/api-keys.png) + ![A página API Keys exibindo permissões da chave, horário de criação e ações de regenerar e desativar.](/images/dashboard/api-keys.png) - Use essa lista para revisar concessões regularmente e desativar chaves que não correspondam mais a uma carga de trabalho ativa. + Use esta lista para revisar concessões regularmente e desativar chaves que não correspondam mais a uma carga de trabalho ativa. ```bash @@ -36,25 +36,25 @@ As chaves de API pertencem a uma organização e carregam permissões explícita fp keys disable production-agents ``` - Redirecione ou capture a saída de criação/regeneração de forma segura; o segredo é retornado apenas uma vez. + Redirecione ou capture a saída de criação/regeneração com segurança; o segredo é retornado apenas uma vez. -As duas permissões necessárias para uma máquina Failproof AI conectada são independentes: +As duas permissões exigidas por uma máquina Failproof AI conectada são independentes: - `events:add` envia eventos e dados de sessão. -- `policies:pull` recupera os deployments de políticas atribuídos. +- `policies:pull` recupera os deployments de política atribuídos. -Os segredos das chaves são exibidos no momento da criação ou regeneração. Armazene-os em um gerenciador de segredos e faça a rotação sem reutilizar credenciais interativas de operadores. +Os segredos das chaves são exibidos quando criados ou regenerados. Armazene-os em um gerenciador de segredos e faça a rotação sem reutilizar as credenciais interativas de um operador. ## Catálogo de permissões | Área | Permissões | | --- | --- | | Events | `events:add`, `events:read` | -| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` é exclusivo para sessões humanas | +| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` é exclusivo para sessão humana | | Users | `users:create`, `users:read`, `users:update`, `users:delete` | -| Evaluations | `evaluations:read`, `evaluations:trigger` | +| Evaluations | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | | Dashboards | `dashboards:read`, `dashboards:write`, `dashboards:delete` | | Queries | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | | Assistant | `agent:use` | @@ -65,9 +65,9 @@ Os segredos das chaves são exibidos no momento da criação ou regeneração. A | Policies | `policies:read`, `policies:write`, `policies:pull` | | Usage | `usage:read` | -`orgs:admin` é reservado para o operador da instância e não pode ser concedido a uma chave de organização ou a um membro comum. Tokens `incidents:*` e `alerts:ack` descontinuados são aceitos por compatibilidade e normalizados para as permissões `issues:*` atuais. +`orgs:admin` é reservado para o operador da instância e não pode ser concedido a uma chave de organização ou a um membro comum. Tokens `incidents:*` e `alerts:ack` descontinuados são aceitos por compatibilidade e são normalizados para as permissões `issues:*` atuais. -Os conjuntos de permissões nativos são `read-only`, `standard` e `admin`. O conjunto `standard` adiciona às permissões de leitura o disparo de avaliações, execução de consultas, resposta a issues e uso do assistente. A criação de chaves remove concessões exclusivas de sessões humanas mesmo quando um conjunto de permissões as contém. +Os conjuntos de permissões integrados são `read-only`, `standard` e `admin`. O `standard` adiciona acionamento de avaliações, execução de queries, resposta a issues e uso do assistente às permissões de leitura. A criação de chaves remove concessões exclusivas de usuários humanos, mesmo quando um conjunto de permissões as contém. Chaves com escopo de instância podem selecionar uma organização com o cabeçalho `X-AgentEye-Org`. Defina-o explicitamente em deployments com múltiplas organizações; a omissão pode selecionar a organização padrão. diff --git a/docs/pt-br/evaluations/deploy.mdx b/docs/pt-br/evaluations/deploy.mdx new file mode 100644 index 00000000..b355a7c0 --- /dev/null +++ b/docs/pt-br/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "Fazer deploy e versionar uma avaliação" +description: "Faça deploy de uma versão imutável, veja o que está em produção, publique novas versões, faça rollback e pontue sessões que você já tem." +icon: "cloud-upload" +--- + +## Fazer deploy + +Selecione **deploy `@`** na parte inferior da página de autoria. A versão é imutável após a publicação: a partir daí, toda sessão concluída à qual a condição se aplica é pontuada por ela. + +## Ver o que está em produção + +**Analyze → eval authoring** lista as definições hospedadas da sua organização — as avaliações que o avaliador gerenciado executa para ela. Cada linha exibe: + +- nome, chave, versão e tipo de resultado +- checksum do código-fonte, que diferencia revisões implantadas sem precisar abrir o código +- se é **condicional** ou se executa em **todas as sessões concluídas** — a condição é o que delimita uma avaliação a agentes ou ambientes específicos +- timeout, labels e data da última alteração + +![A lista de definições hospedadas: nome, chave, versão, tipo de resultado, checksum, timeout e escopo de cada avaliação, com opções de nova versão e habilitar ou desabilitar.](/images/dashboard/eval-definitions.png) + +Pesquise na lista ou filtre por estado. Avaliações registradas pelo seu próprio worker não aparecem aqui; seus resultados recebem a tag **customer** na [página de avaliações](/pt-br/sessions/evaluations), enquanto as hospedadas recebem **managed**. + +Uma organização pode ter até 100 avaliações hospedadas diferentes habilitadas ao mesmo tempo. + +## Publicar uma nova versão + +Selecione **new version** em uma linha. A página de autoria abre com o código dessa versão; altere, teste e faça o deploy. A chave e o tipo de resultado são mantidos e não podem ser alterados. + +Publicar uma versão sucessora desabilita a anterior e a mantém na lista. Os resultados preservam a versão que os gerou, portanto um gráfico mostra exatamente quando a nova lógica entrou em vigor. + +## Fazer rollback + +Selecione **disable** na versão atual e **enable** na versão para a qual deseja reverter. Nada é excluído e todos os resultados permanecem como estavam. + +## Parar uma avaliação + +Selecione **disable**. Sem nenhuma versão habilitada, ela para de ser executada em novas sessões. Para parar uma avaliação que seu próprio worker executa, pare de registrá-la: remova-a do worker ou pare o worker. + +## Pontuar sessões que você já tem + +A execução de avaliações é prospectiva: uma versão implantada agora nunca pontua uma sessão que terminou antes dela. Para pontuar o histórico, abra **score sessions you already have** na página de autoria da avaliação, escolha uma janela de até 90 dias e, opcionalmente, uma avaliação específica; depois conte antes de executar. O total é exatamente o que será executado, e cada par sessão-avaliação nele é uma avaliação faturável. + +Apenas lacunas são preenchidas. Uma sessão que já tem um resultado para aquela avaliação o mantém, e executar a mesma janela duas vezes não pontua nada novo. + +Para pontuar uma sessão novamente — após uma correção ou para uma sessão que nunca terminou corretamente — selecione **re-evaluate** na página dela. O novo resultado é adicionado ao histórico da sessão; os anteriores são mantidos. + +## Permissões + +| Permissão | Permite | +| --- | --- | +| `evaluations:read` | Ver resultados e abrir a página de autoria de avaliações | +| `evaluations:trigger` | Ver, fazer deploy, versionar, habilitar e desabilitar definições hospedadas; testá-las; pontuar o histórico; re-avaliar uma sessão | +| `events:read` | Testar com sessões reais e basear rascunhos nas suas chaves de payload, além de `evaluations:trigger` | +| `evaluations:run` | Executar seu próprio worker de avaliação | \ No newline at end of file diff --git a/docs/pt-br/evaluations/overview.mdx b/docs/pt-br/evaluations/overview.mdx new file mode 100644 index 00000000..8e8a736d --- /dev/null +++ b/docs/pt-br/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "Avaliar agentes" +description: "Pontue cada sessão finalizada com avaliações que você define: verificações Python hospedadas ou juízes LLM no seu próprio worker." +icon: "gauge" +--- + +Uma avaliação pontua uma sessão de agente finalizada. Quando uma sessão termina, todas as avaliações habilitadas que se aplicam a ela são executadas e registram o que encontraram, com o raciocínio que você pode ler ao lado do trace: + +- uma **pontuação** de 0 a 1, opcionalmente marcada como aprovada ou reprovada +- uma **métrica**, como uma contagem, uma duração ou um custo, com sua unidade +- uma **asserção**, que passou ou não + +## Dois tipos de avaliador + +| | Python Hospedado | Seu próprio worker | +| --- | --- | --- | +| Escrito | No dashboard, em **Analyze → eval authoring** | Em Python, com o [SDK de Avaliador](/pt-br/reference/evaluator-sdk) | +| Executa | No avaliador gerenciado do Failproof AI, em um sandbox | Na sua infraestrutura | +| Ideal para | Verificações determinísticas baseadas em código | Juízes LLM, chamadas de modelo, pacotes, segredos, acesso à rede, processamento pesado | + +O Python Hospedado é deliberadamente limitado: uma expressão, sem imports, sem rede. Qualquer coisa que precise de um modelo — um juiz LLM avaliando se uma resposta foi relevante, por exemplo — executa no seu próprio worker. Nenhum dos dois tipos precisa de uma conexão de entrada: os workers buscam sessões finalizadas e enviam resultados via HTTPS de saída. + +## Cada organização avalia seus próprios agentes + +As avaliações pertencem à organização que as define. Cada organização em uma instância escreve as suas próprias — com suas próprias verificações, condições, limites e rótulos — versionando e implantando-as sem afetar nenhuma outra, e visualizando apenas seus próprios resultados. Filtre esses resultados por agente, ambiente, avaliação e período, ou pergunte ao assistente sobre eles. + +## Do primeiro rascunho às pontuações ao vivo + + + + Descreva o que medir e deixe o assistente criar um rascunho, ou escreva você mesmo. Veja [Escrever uma avaliação](/pt-br/evaluations/write). + + + Execute contra sessões reais antes de entrar em produção; nada é armazenado. Veja [Testar uma avaliação](/pt-br/evaluations/test). + + + Implante uma versão imutável, publique novas versões conforme ela evolui e reverta para uma anterior quando necessário. Veja [Implantar e versionar](/pt-br/evaluations/deploy). + + + Visualize pontuações ao longo do tempo, compare agentes e ambientes e consulte o assistente. Veja [Ler resultados de avaliações](/pt-br/sessions/evaluations). + + + +A execução de avaliações segue em frente: uma versão implantada agora pontua as sessões que forem finalizadas a partir deste momento. Para pontuar sessões que você já tem, [faça um backfill](/pt-br/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file diff --git a/docs/pt-br/evaluations/test.mdx b/docs/pt-br/evaluations/test.mdx new file mode 100644 index 00000000..35935496 --- /dev/null +++ b/docs/pt-br/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "Testar uma avaliação" +description: "Execute uma avaliação contra suas sessões reais antes de implantá-la. Nada é armazenado." +icon: "flask-conical" +--- + +**Testar esta avaliação**, na página de criação, executa o código contra suas sessões reais na frota de avaliadores sem implantá-la. Nada é armazenado: uma falha aqui é apenas uma prévia, e a implantação sempre é permitida. + + + + Selecione **verificar** para compilar o código e a condição conforme as regras do sandbox sem executá-los em nenhuma sessão. + + + Filtre as sessões correspondentes por agente, ambiente, período ou ID de sessão, e marque até 10. Inclua sessões em que a avaliação deve falhar, bem como as que devem passar. + + + Selecione **executar contra N sessões** e leia cada linha. + + + +| Linha | O que significa | +| --- | --- | +| **ok** | Foi executada. A linha lista cada pontuação, métrica e asserção retornada, além do tempo que levou. | +| **ignorada** | A condição retornou `False`, portanto a avaliação não foi executada. Isso é um salto, não uma falha. | +| Falhou | Lançou uma exceção, atingiu o tempo limite ou usou algo que o sandbox recusa. A linha indica qual foi o problema, e **Corrigir** repassa o erro ao assistente quando ele pode ajudar. | + +![O painel de testar esta avaliação: três sessões selecionadas por agente, duas ok e uma ignorada porque sua condição retornou False.](/images/dashboard/eval-test.png) + +Um resultado deixa de ser atual no momento em que você edita o código; ele fica esmaecido em vez de ser reutilizado. \ No newline at end of file diff --git a/docs/pt-br/evaluations/write.mdx b/docs/pt-br/evaluations/write.mdx new file mode 100644 index 00000000..d7fb9932 --- /dev/null +++ b/docs/pt-br/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "Escrever uma avaliação" +description: "Descreva o que medir e deixe o assistente criar uma avaliação Python hospedada, ou escreva o código você mesmo. Juízes LLM rodam no seu próprio worker." +icon: "file-pen-line" +--- + +Avaliações hospedadas são pequenos scripts Python determinísticos, escritos no dashboard e executados na frota de avaliadores da Failproof AI. Lógicas mais pesadas — um juiz LLM, um pacote, um segredo, uma chamada de rede — rodam no [seu próprio worker](#write-it-in-your-own-worker). + +## Criar a partir de uma descrição + +1. Acesse **Analyze → eval authoring** e selecione **new eval**. +2. Descreva o que medir em linguagem natural, ou escolha em **start from an example…**, e selecione **draft**. +3. Revise os campos e o código gerado, depois [teste](/pt-br/evaluations/test) e [publique](/pt-br/evaluations/deploy). + +![A página de criação de avaliações com uma avaliação gerada: a descrição, as notas do assistente sobre o rascunho e os campos de nome, chave, versão, resultado, timeout, labels e condição.](/images/dashboard/eval-authoring-draft.png) + +O rascunho é baseado nos eventos da sua própria organização: a página lê quais chaves de payload suas sessões carregaram nos últimos sete dias, de modo que o código use chaves reais em vez de suposições. Antes de entregar o rascunho, o assistente o testa em até cinco das suas sessões recentes, corrige tudo o que conseguir provar estar errado — em até três rodadas — e verifica se o código mede o que você pediu. Seja específico na descrição: prompts amplos são mais lentos e podem ultrapassar o tempo limite. De qualquer forma, revise o código; a publicação nunca é bloqueada. + +## Configurar os campos + +| Campo | O que é | +| --- | --- | +| name | O que as pessoas veem. Editável depois | +| key | O identificador estável sob o qual os resultados são agrupados, como `code_assistant_quality_gate` | +| version | Qualquer string de versão sem espaços, como `1.0.0` | +| result | **score** (0 a 1), **metric** (um número com unidade) ou **assertion** (passou ou não) | +| timeout seconds | Padrão 30. O sandbox interrompe qualquer execução individual em 60 | +| labels | Até 20, separadas por vírgula. Editável depois | +| condition | Opcional. Uma expressão Python; a avaliação só roda em sessões onde o valor for `True` | + +Use a condição para restringir uma avaliação aos agentes e ambientes para os quais ela foi criada: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +A chave, versão, tipo de resultado, condição e código são imutáveis após a publicação: para alterar qualquer um deles, publique uma nova versão. O nome, as labels e se está habilitada permanecem editáveis. + +## Escrever o código você mesmo + +O **evaluator code** é uma única expressão Python que retorna `EvalResult(...)`, com `session` disponível no escopo. Este exemplo calcula a proporção de resultados de ferramentas que retornaram ok: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +Um resultado começa com a chave da própria avaliação, no tipo declarado: `score=` para uma avaliação de pontuação, ou uma entrada em `metrics` ou `assertions` com o nome da chave para uma avaliação de métrica ou asserção. Outras métricas e asserções podem acompanhá-la, com até 25 resultados por execução. + +| No escopo | Disponibiliza | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count` e `events`, além de `count(event_type)` e `events_of_type(event_type)` | +| Cada evento | `id`, `ts`, `event_type` e `payload` | +| Tipos de resultado | `EvalResult`, `Score`, `Metric`, `Assertion` e `ConditionResult` para uma condição | +| Builtins | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +Nada mais está acessível: sem imports, e sem atributos além dos dados de sessão e métodos simples de string e dicionário como `get`, `lower` e `split`, que devem ser chamados e não apenas referenciados. As chaves de payload são o que seus agentes enviam — `status` acima é apenas um exemplo — portanto, leia-as de uma sessão real. **format** organiza o código e **fix** pede ao assistente que o corrija. O código pode ter até 128 KiB, e a condição até 16 KiB. + +![O editor de código do avaliador, com format e fix, exibindo as asserções de uma avaliação gerada.](/images/dashboard/eval-authoring-code.png) + +## Escrever no seu próprio worker + +Quando uma avaliação precisa de um modelo, um pacote, um segredo ou acesso à rede, escreva-a com o [Evaluator SDK](/pt-br/reference/evaluator-sdk) e execute-a na sua própria infraestrutura. Ela usa os mesmos tipos de resultado, e seus resultados aparecem ao lado dos hospedados, marcados como **customer**: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # sua chamada LLM: uma pontuação de 0-1 e o motivo + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/pt-br/policies/deploy.mdx b/docs/pt-br/policies/deploy.mdx index 8ced4131..8ddff178 100644 --- a/docs/pt-br/policies/deploy.mdx +++ b/docs/pt-br/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "Fazer deploy de políticas" -description: "Publique uma versão de política revisada nas máquinas desejadas." +title: "Fazer deploy de uma política" +description: "Coloque uma versão de política testada em máquinas no modo de observação, aplique a execução e confirme que todas as máquinas a receberam." icon: "cloud-upload" --- -Um deployment conecta uma ou mais versões de política a um conjunto de máquinas registradas. +Um deploy coloca versões de políticas publicadas em uma máquina, cada uma com um dos dois efeitos: -## Aplicar um deployment +- **Observe** registra o que a política teria feito, sem bloquear nada. +- **Enforce** age conforme a decisão: um `deny` bloqueia a chamada e um `instruct` direciona o agente. + +## Adicionar uma máquina + +Uma máquina aparece em **Admin → enforcement** assim que se conecta à Cloud. Se a que você deseja ainda não está lá: - 1. Vá para **Admin → enforcement**, localize a máquina e expanda sua linha. - 2. Selecione **edit**, adicione a versão de política revisada e escolha o efeito **observe** ou de aplicação. - 3. Aplique a alteração, aguarde o próximo check-in da máquina e confirme o estado de deployment e cobertura. - 4. Vá para **Observe → policy** para inspecionar as decisões em tempo real. - - ![O editor de deployment de máquinas com versões de política, efeitos de enforce e observe, e a ação de aplicar deployment.](/images/dashboard/enforcement-editor.png) + 1. Acesse **Administration → Keys** e crie uma chave com `policies:pull`, para que a máquina possa receber deploys, e `events:add`, para que suas decisões cheguem à Cloud. + 2. Conecte a máquina com essa chave — [Conectar uma máquina à Cloud](/pt-br/start/setup#connect-a-machine-to-cloud) descreve o processo. + 3. Confirme que ela aparece em **Admin → enforcement**. - Faça o deploy pela CLI com `fp fleet`. Revise o conjunto resultante antes de aplicá-lo — `deploy` exibe o plano completo e solicita confirmação **apenas em um terminal interativo sem `--json`**. Com `--json`, com `--yes`, ou com stdin redirecionado (uma etapa de CI, um script, um agente executando subprocessos), ele é aplicado imediatamente sem plano e sem prompt — portanto, execute `fp fleet show ` primeiro caso queira revisar: + Na máquina: + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + No terminal, `failproofai config` pergunta se deve se conectar à Cloud e solicita a chave em um prompt mascarado. Em seguida, confirme que a máquina foi registrada, de qualquer lugar, com `fp fleet list`. + + + +## Fazer deploy no modo de observação + + + + 1. Acesse **Admin → enforcement**, encontre a máquina e expanda sua linha. + 2. Selecione **edit**, adicione a versão de política testada e escolha **observe**. + 3. Aplique a alteração, aguarde o próximo check-in da máquina e confirme o estado de deploy e cobertura. + 4. Acesse **Observe → policy** para inspecionar as decisões em tempo real. + ![O editor de deploy da máquina com versões de políticas, efeitos enforce e observe, e a ação de aplicar o deploy.](/images/dashboard/enforcement-editor.png) + + ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` mostra a intenção versus a entrega (uma máquina aparece como `behind` até a próxima consulta), `fp fleet history ` lista as gerações e `fp fleet rollback ` restaura uma delas — a operação é recusada se aquela geração referenciar uma política desabilitada ou excluída. + O sufixo `:observe` é o que define o modo de observação: usar `--add no-force-push` sem sufixo mantém o efeito que a máquina já possui para essa política e, caso contrário, executa em modo enforce. Mude para enforce posteriormente com `--add no-force-push:enforce`. + + O comando `deploy` **substitui todo o conjunto de políticas da máquina** pelo resultado. Ele exibe o plano e pede confirmação antes de aplicar — mas apenas em um terminal interativo. Com `--yes`, sob `fp --json`, ou com stdin redirecionado (uma etapa de CI, um script, um agente executando via shell), ele aplica sem perguntar; o plano ainda é exibido ou retornado como `plan` com `--json`. - Verifique a própria máquina com `failproofai config --status`, e utilize `fp sessions --env production --since 24h` e `fp events --event-type hook_completed` após o deployment para confirmar que a atividade está chegando ao Cloud. + Na máquina, `failproofai policies` lista as políticas gerenciadas pela Cloud que estão em execução e `failproofai config --status` mostra sua conexão. Use `fp sessions --env production --since 24h` e `fp events --event-type hook_completed` para confirmar que a atividade da máquina chega à Cloud. - - Faça o deploy de uma versão revisada, não de um rascunho mutável, começando por uma máquina fora de produção ou um grupo pequeno cujas sessões você possa inspecionar. + + Selecione a versão publicada e as máquinas em que ela deve ser executada. - - Revise correspondências, motivos, ferramentas afetadas e falsos positivos sem bloquear o trabalho. + + Revise correspondências, motivos, ferramentas afetadas e falsos positivos enquanto nada é bloqueado. - - Promova após as correspondências observadas separarem ações inseguras das válidas, depois confirme que cada máquina prevista obteve o deployment e está reportando decisões. + + Mude o efeito para enforce assim que as correspondências observadas separarem as ações inseguras das válidas, e então confirme que todas as máquinas pretendidas receberam a alteração e estão reportando decisões. -As máquinas precisam da capability `policies:pull`. O reporte de eventos é controlado separadamente por `events:add`; verifique ambos quando esperar análise e enforcement pelo Cloud. +## Verificar a cobertura + +A cobertura responde se uma política está sendo executada onde o risco existe. + +1. Acesse **Admin → enforcement** e revise os totais de enforce e observe. +2. Pesquise uma máquina por ID ou rótulo, ou filtre as máquinas em que falta uma política. +3. Expanda uma linha para comparar as políticas atribuídas, o deploy reportado, o último check-in e o histórico. +4. Atualize após o intervalo de polling da máquina quando um deploy aplicado ainda estiver pendente. + +![A frota de Enforcement mostrando cobertura de políticas, estado de deploy das máquinas e atribuições de observe e enforce.](/images/dashboard/enforcement-fleet.png) + +Fique atento a máquinas que nunca receberam o deploy mais recente, máquinas registradas que pararam de reportar, uma política atribuída ao ambiente errado e divergência de versões após uma atualização interrompida. + +Rotule as máquinas por carga de trabalho e ambiente — nomes de host sozinhos raramente sobrevivem a autoescalonamento ou substituição: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - O gerenciamento de enforcement é um fluxo administrativo do Cloud. Não trate as rotas de enforcement exclusivas para root como endpoints comuns da API `/v1` para clientes. + O gerenciamento de enforcement é um fluxo de trabalho administrativo da Cloud. Não trate as rotas de enforcement exclusivas de root como endpoints comuns da API `/v1` do cliente. \ No newline at end of file diff --git a/docs/pt-br/policies/editor.mdx b/docs/pt-br/policies/editor.mdx index 2a5ac419..7767bb20 100644 --- a/docs/pt-br/policies/editor.mdx +++ b/docs/pt-br/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "Editor de políticas" -description: "Crie e revise políticas versionadas a partir de um modo de falha confirmado." +title: "Escrever uma política" +description: "Deixe o Failproof AI redigir uma política a partir de uma descoberta de auditoria, ou escreva o código-fonte você mesmo, depois revise, teste e publique." icon: "file-pen-line" --- -Use o editor de políticas para transformar uma descoberta ou problema em uma regra publicável. Mantenha a criação separada da publicação para que um rascunho não possa alterar silenciosamente o comportamento em produção. +Há duas formas de escrever uma política: deixar o Failproof AI redigir a partir de uma descoberta de auditoria, ou escrever o código-fonte você mesmo. Nada é publicado ou implantado até que você decida. -Quando um problema tem um padrão de ação repetível, abra-o em **Analyze → issues** e selecione **generate policy**. O Failproof AI primeiro explica se uma política pode expressar o problema, e então leva o contexto do intent revisado e da descoberta para o editor. O código gerado permanece como rascunho até que você o publique. +## Escrever uma política a partir de uma auditoria -## Publicar uma versão de política +Uma auditoria encontra uma falha; uma política impede que ela aconteça novamente. O Failproof AI redige a política a partir das evidências da própria descoberta. + +### 1. Execute uma auditoria + +[Execute uma auditoria](/pt-br/audits/run) sobre as sessões onde a falha ocorre. Cada descoberta carrega suas sessões de evidência, uma causa raiz e um caminho de prevenção sugerido. Trabalhe a partir de uma descoberta com um **padrão de ação repetível** — uma política só pode bloquear o que consegue reconhecer em um evento de hook. + +### 2. Gere o rascunho - 1. Vá para **Admin → policy editor** e, em **compose**, descreva o modo de falha ou cole o código-fonte da política em JavaScript. - 2. Valide o código-fonte e corrija todos os erros reportados. - 3. Insira a identidade da política e publique-a; em seguida, use **library** para comparar ou desativar versões. - 4. Selecione **enforcement** quando a versão estiver pronta para implantação em máquinas. + 1. Abra o problema da descoberta em **Analyze → issues** e verifique as sessões citadas, a causa raiz e a recomendação. + 2. Selecione **generate policy**. O Failproof AI primeiro informa se uma política consegue expressar o problema. Um resultado **no policy** significa que a solução é um alerta, uma mudança de processo ou uma pessoa — e não uma política. + 3. Selecione **write this policy**. O título do problema, a descoberta, a causa raiz, a recomendação e a intenção de aplicação proposta se tornam um rascunho em **Admin → policy editor**. Use **open the editor anyway** quando você discordar da verificação de candidatura. - ![A view de composição do editor de políticas com identidade da política, criação assistida por IA, validação do código-fonte e controles de publicação.](/images/dashboard/policy-editor.png) + ![A visualização de composição do editor de políticas com identidade da política, redação assistida por IA, validação de código-fonte e controles de publicação.](/images/dashboard/policy-editor.png) - Publique pela CLI com `fp policies publish`. O comando cria uma **nova versão** e nunca edita uma existente, além de verificar a sintaxe do código com node antes de enviar — nada downstream faz isso, portanto um erro de sintaxe só apareceria na máquina no momento da aplicação: + Leia as evidências e depois redija com o assistente. `compose` imprime o código-fonte para você revisar e não publica nada: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - Publicar não implanta nada — uma nova versão fica inativa até que `fp fleet deploy` a coloque em uma máquina. `fp policies compose ""` cria um rascunho do código com o assistente Cloud e o exibe para revisão, sem publicá-lo. - - Para instalar uma política diretamente em um agente CLI local (não no Cloud), use `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. + `compose` requer uma sessão autenticada (`fp login`) cuja função tenha `policies:write`; ele rejeita chaves de API. -## Lista de verificação para criação de políticas +### 3. Revise o rascunho + +Um rascunho é um ponto de partida, não um veredicto. Antes de publicar, verifique se ele: + +1. Nomeia o modo de falha em linguagem operacional. +2. Corresponde apenas aos eventos de hook e ferramentas que carregam evidências suficientes para decidir. +3. Usa a condição mais restrita possível que captura a ação insegura. +4. Retorna um motivo que diz ao agente o que fazer em vez disso. +5. Usa `instruct` onde o agente pode corrigir o curso com segurança, e `deny` apenas onde permitir a ação é inaceitável ou irreversível. + +Valide o código-fonte no editor e corrija todos os erros reportados. + +### 4. Teste e depois publique + +Execute o **backtest** na aba de código-fonte antes de publicar: ele repete o rascunho contra chamadas que sua frota já realizou e conta as chamadas funcionais que teriam sido interrompidas. [Testar uma política](/pt-br/policies/test) cobre isso e as outras verificações. + +Quando o comportamento estiver correto, insira a identidade da política e selecione **publish version**. Publicar cria uma versão imutável e não implanta nada: ela fica sem uso até que você [a implante](/pt-br/policies/deploy). Em um terminal: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` verifica a sintaxe do código-fonte antes de enviá-lo, então um erro de sintaxe aparece aqui em vez de aparecer em uma máquina no momento de aplicação. + +## Escreva você mesmo + +Uma política é JavaScript ou TypeScript usando a API `failproofai`: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +Isso corresponde a `production/config.yml`, `/srv/production/config.yml`, `/srv/production` e `C:\\production\\config.yml` tanto para `Write` quanto para `Edit`, mas não para `production-backup`: `production` precisa ser um segmento de caminho completo. O contexto também carrega o tipo de evento, payload normalizado, metadados de sessão, parâmetros e CLI de origem quando disponível — veja o [SDK de políticas](/pt-br/reference/policy-sdk). + +Para publicá-la como uma versão, cole o código-fonte em **compose** em **Admin → policy editor** e siga os passos 3 e 4 acima, ou publique o arquivo a partir de um terminal com `fp policies publish`. -1. Nomeie o modo de falha em linguagem operacional. -2. Selecione os eventos de hook e as ferramentas que contêm evidências suficientes para decidir. -3. Escreva a condição mais restrita possível que corresponda ao comportamento inseguro. -4. Retorne uma mensagem que informe ao agente ou operador o que fazer a seguir. -5. Adicione exemplos que devem corresponder e exemplos que precisam permanecer permitidos. -6. Salve uma nova versão e solicite revisão. +Para executá-la em uma máquina sem Cloud, salve-a em `.failproofai/policies/` com um nome terminando em `policies.js`, `policies.mjs` ou `policies.ts` — esses arquivos são carregados automaticamente nos escopos de projeto e usuário — ou instale por caminho: -Use `instruct` quando o agente puder corrigir o curso com segurança. Use `deny` quando permitir a ação criaria um risco inaceitável ou irreversível. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - Versões de políticas são entradas de implantação imutáveis. Editar um rascunho cria uma nova versão; não deve reescrever a versão já atribuída às máquinas. - \ No newline at end of file +Dê a cada política um nome único entre políticas de convenção, personalizadas, de pacote e gerenciadas pela Cloud. \ No newline at end of file diff --git a/docs/pt-br/policies/failure-behavior.mdx b/docs/pt-br/policies/failure-behavior.mdx index 91b59e68..d169b6cd 100644 --- a/docs/pt-br/policies/failure-behavior.mdx +++ b/docs/pt-br/policies/failure-behavior.mdx @@ -1,18 +1,18 @@ --- -title: "Comportamento em falhas" +title: "Comportamento em caso de falha" description: "Entenda o que acontece quando a avaliação de políticas ou o daemon local está indisponível." icon: "shield-alert" --- -O Failproof AI é projetado para que uma falha de imposição seja visível, em vez de permitir silenciosamente trabalhos arriscados. +O Failproof AI foi projetado para que uma falha de execução seja visível, em vez de permitir silenciosamente que trabalhos arriscados prossigam. ## Diagnosticar um bloqueio por falha fechada - 1. Vá para **Admin → enforcement** e abra a máquina. + 1. Acesse **Admin → enforcement** e abra a máquina. 2. Verifique o último check-in, o deployment atribuído e o deployment reportado. - 3. Vá para **Observe → policy** e abra a sessão da decisão negada. + 3. Acesse **Observe → policy** e abra a sessão da decisão negada. 4. Confirme se o motivo indica inacessibilidade do daemon, divergência de versão ou a própria política. @@ -27,16 +27,16 @@ O Failproof AI é projetado para que uma falha de imposição seja visível, em -Em uma máquina configurada para usar `failproofaid`, o daemon é o único avaliador. Se ele estiver inacessível ou se sua versão de protocolo não corresponder à da CLI, a avaliação do hook falha de forma fechada. A ação é negada com um motivo que orienta o operador a verificar ou atualizar o daemon. +Em uma máquina configurada para usar o `failproofaid`, o daemon é o único avaliador. Se ele estiver inacessível ou se a versão do protocolo não corresponder à da CLI, a avaliação do hook falha de forma fechada. A ação é negada com um motivo que orienta o operador a verificar ou atualizar o daemon. -Antes da configuração do daemon, os hooks avaliam as políticas no processo. Uma vez que a configuração do daemon é registrada, o Failproof AI não recorre silenciosamente a um segundo avaliador quando o daemon falha. +Antes da configuração do daemon, os hooks avaliam as políticas no próprio processo. Uma vez que a configuração do daemon é registrada, o Failproof AI não recai silenciosamente sobre um segundo avaliador quando o daemon falha. ## Responder a uma decisão de falha fechada 1. Execute `failproofai config --status`. -2. Se as versões divergirem, execute `failproofai config` novamente após atualizar o pacote. +2. Se as versões forem diferentes, execute `failproofai config` novamente após atualizar o pacote. 3. Se o daemon estiver inacessível, inspecione o estado do serviço e os logs locais. -4. Retome o trabalho do agente somente após confirmar que o caminho de avaliação de políticas está saudável. +4. Retome o trabalho do agente somente após confirmar que um caminho de avaliação de políticas conhecido está saudável. Não tente repetidamente a ação bloqueada. Uma resposta de falha fechada significa que o sistema não conseguiu estabelecer que a ação era segura. @@ -44,24 +44,26 @@ Antes da configuração do daemon, os hooks avaliam as políticas no processo. U ## Um pack não carrega -Uma máquina instruída a aplicar um pack que não consegue executá-lo nega em vez de continuar silenciosamente. O gatilho é uma **expectativa registrada**, nunca uma vazia: uma máquina sem packs instalados permanece silenciosa, enquanto um pack declarado que não consegue ser resolvido — ou que registra menos do que seu manifesto declara — nega. +Uma máquina instruída a aplicar um pack que não consegue executá-lo nega em vez de continuar silenciosamente. O gatilho é uma **expectativa registrada**, nunca uma vazia: uma máquina sem packs instalados fica em silêncio, enquanto um pack declarado que não resolve — ou que registra menos do que seu manifesto declara — nega. -A negação é **restrita**, diferentemente de um daemon inacessível. Um daemon inacessível significa que nenhuma avaliação ocorreu, portanto nada pode ser considerado seguro. Um pack que não carrega possui um conjunto enumerável de guardas ausentes, pois cada política declarada carrega seu próprio `match` — portanto, ele nega apenas os eventos e ferramentas cobertos por essas políticas, e tudo o mais prossegue normalmente. +A negação é **restrita**, diferentemente de um daemon inacessível. Um daemon que não pode ser alcançado significa que nenhuma avaliação ocorreu, portanto nada pode ser considerado seguro. Um pack que não carrega possui um conjunto enumerável de guardas ausentes, pois cada política declarada carrega seu próprio `match` — portanto, ele nega apenas os eventos e ferramentas cobertos por essas políticas, e tudo o mais prossegue normalmente. Não é acionado para: - um pack `observe`, que avalia e descarta por construção -- políticas que você nunca assumiu ou desativou explicitamente -- um pack que o loader nunca recebeu, onde "sem registros" não pode ser distinguido de um skip deliberado +- políticas que você nunca adotou ou desativou explicitamente +- um pack que o loader nunca recebeu, onde "nenhum registro" não pode ser distinguido de um salto deliberado - uma pausa de sessão ativa - um timeout de carregamento, que é transitório — um momento de disco lento não deve negar até que um humano intervenha -`UserPromptSubmit` **instrui** em vez de negar, independentemente do que a política ausente declarou. Uma negação geral o incluiria e bloquearia o acesso ao agente que poderia corrigir o problema. +`UserPromptSubmit` **instrui** em vez de negar, independentemente do que a política ausente declarou. Uma negação irrestrita a incluiria e bloquearia o acesso ao agente que poderia corrigir o problema. ### O que fazer ```bash -failproofai pack list +failproofai policies ``` -Ele lista qualquer pack instalado que não carregará, indica o motivo e encerra com código não-zero. Em seguida, reinstale-o (`failproofai pack add `) ou remova-o (`failproofai pack remove `) — removê-lo retira a expectativa, e a negação cessa junto com ela. \ No newline at end of file +A listagem sinaliza um pack instalado cujo registro de instalação ou digest não confere mais, e informa o motivo. Ela não importa o pack, portanto um que falha apenas ao carregar — registrando menos do que seu manifesto declara — aparece como normal; a negação abaixo é o que identifica esse caso. De qualquer forma, reinstale-o (`failproofai policies add `) ou remova-o (`failproofai policies remove `) — removê-lo retira a expectativa, e a negação cessa junto. + +A própria negação é atribuída a `pack/failproofai-pack-unavailable`, que tem precedência sobre as políticas que foram carregadas, de modo que uma chamada de ferramenta bloqueada identifica o pack ausente em vez de qualquer guarda sobrevivente que por acaso tenha disparado primeiro. \ No newline at end of file diff --git a/docs/pt-br/policies/local-configuration.mdx b/docs/pt-br/policies/local-configuration.mdx index bd4798aa..674e7e3d 100644 --- a/docs/pt-br/policies/local-configuration.mdx +++ b/docs/pt-br/policies/local-configuration.mdx @@ -1,55 +1,49 @@ --- title: "Configuração local" -description: "Controle o escopo de políticas, parâmetros, arquivos personalizados e configurações de máquina do Failproof AI." +description: "Controle escopo de políticas, parâmetros, arquivos personalizados e configurações do Failproof AI a nível de máquina." icon: "file-cog" --- -O Failproof AI separa a seleção de políticas das configurações de máquina e daemon. Isso mantém as escolhas de políticas do repositório revisáveis, enquanto as credenciais e o estado do daemon permanecem fora do repositório. +O Failproof AI mantém separado o que um repositório pode commitar — conexão de hooks, parâmetros de políticas, políticas personalizadas — do estado da máquina, como credenciais, packs instalados e o daemon. -## Escolha um escopo de política +## Escolha um escopo - - - Execute `failproofai` sem argumentos para abrir o dashboard de políticas local. Escolha o escopo de usuário, projeto ou local antes de ativar uma política, para que a alteração seja gravada no arquivo de configuração correto. +O escopo define onde os hooks são conectados e em qual arquivo de configuração você escreve parâmetros e caminhos de políticas personalizadas: - - **Usuário** aplica-se a todos os projetos nesta máquina. - - **Projeto** pertence ao repositório e pode ser commitado. - - **Local** substitui um projeto para um usuário específico e deve permanecer no gitignore. +- **User** aplica-se a todos os projetos nesta máquina. +- **Project** pertence ao repositório e pode ser commitado. +- **Local** substitui um projeto para um único usuário e deve permanecer no gitignore. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # wire hooks for this repository +failproofai policies --install --cli claude --scope user # or for every project on this machine +failproofai policies +``` - Nem todo harness suporta escopo local. O CLI rejeita um escopo que o harness selecionado não consegue representar. - - +Nem todos os harnesses suportam escopo local; o CLI rejeita um escopo que o harness selecionado não consegue representar. + +Quais políticas de um pack estão ativas **não** tem escopo definido. A configuração é registrada junto com o pack instalado, portanto `failproofai policies add ` ativa uma política para toda a máquina, independentemente do que o `--scope` especifica. -| Escopo | Arquivo de configuração de política | +| Escopo | Arquivo de configuração de políticas | | --- | --- | -| Projeto | `/.failproofai/policies-config.json` | +| Project | `/.failproofai/policies-config.json` | | Local | `/.failproofai/policies-config.local.json` | -| Usuário | `~/.failproofai/policies-config.json` | +| User | `~/.failproofai/policies-config.json` | -As políticas ativadas são mescladas como uma união. Os parâmetros de política utilizam o primeiro escopo que define parâmetros para aquela política, na ordem projeto → local → usuário. Caminhos de política personalizada explícitos utilizam o primeiro escopo que os define. +Os parâmetros de políticas utilizam o primeiro escopo que define parâmetros para aquela política, na ordem project → local → user. Caminhos de políticas personalizadas explícitos utilizam o primeiro escopo que os define. -## Configure os parâmetros de política +## Configure parâmetros de políticas - Abra a política no dashboard local, edite os parâmetros suportados e salve no escopo selecionado. Execute uma ação de agente que corresponda e uma que não corresponda, depois inspecione a decisão em **Observar → política**. + Abra a política no dashboard local, edite os parâmetros suportados e salve no escopo selecionado. Execute uma ação do agente que corresponda e outra que não corresponda à política, depois inspecione a decisão em **Observe → policy**. - Edite o `policies-config.json` do escopo selecionado e execute `failproofai policies` para identificar nomes de políticas ou chaves de parâmetros desconhecidos. + Edite o `policies-config.json` do escopo selecionado e execute `failproofai policies`: ele alertará sobre uma entrada `policyParams` que nomeia uma política que nenhum pack instalado possui. Ele não verifica as chaves dentro de uma entrada, portanto confira a ortografia delas na tabela abaixo. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ As políticas ativadas são mescladas como uma união. Os parâmetros de políti -## Entenda os arquivos de máquina +### Parâmetros aceitos pelas políticas do Failproof AI + +Cada política valida seus próprios tipos de parâmetro. + +| Política | Parâmetro | Tipo e padrão | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; entradas contêm `regex` e `label` | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| Bloqueadores de infraestrutura | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + Um padrão de permissão amplia o que um agente pode fazer. Teste a tokenização exata e as variantes de comando no harness de destino antes de implantá-lo em todo um conjunto de máquinas. + + +## Entenda os arquivos da máquina -`~/.failproofai` contém arquivos separados para limites de confiança distintos: +`~/.failproofai` contém arquivos separados para diferentes limites de confiança: | Caminho | Finalidade | | --- | --- | -| `config.json` | Configurações de daemon, auditoria e telemetria sem segredos | +| `config.json` | Configurações de daemon, auditoria e telemetria (sem segredos) | | `credentials.json` | Credenciais de nuvem; armazenadas com permissões somente para o proprietário | -| `policies-config.json` | Seleção de built-ins com escopo de usuário, parâmetros e caminhos personalizados explícitos | -| `policies/` | Políticas de convenção do usuário e artefatos de política gerenciados pela nuvem | -| `hook-activity/` | Log local de decisões de política | -| `state/` | Spool do daemon, integridade, pausa e estado de execução | +| `policies-config.json` | Parâmetros de escopo de usuário e caminhos explícitos de políticas personalizadas | +| `policies/` | Políticas de convenção do usuário, packs instalados e quais de suas políticas estão ativas, além de artefatos de políticas gerenciadas pela nuvem | +| `hook-activity/` | Log local de decisões de políticas | +| `state/` | Spool do daemon, saúde, pausa e estado de execução | -Use `FAILPROOFAI_HOME` para realocar o layout completo da máquina para um container ou teste isolado. Não realoque diretórios de estado individuais de forma independente. +Use `FAILPROOFAI_HOME` para relocar todo o layout da máquina para um container ou teste isolado. Não reloce diretórios de estado individuais de forma independente. - Nunca faça commit de `credentials.json`. Faça commit da configuração de política do projeto e das políticas de convenção do projeto somente após revisá-las como código de aplicação. + Nunca faça commit de `credentials.json`. Faça commit da configuração de políticas do projeto e das políticas de convenção do projeto somente após revisá-las como código de enforcement. \ No newline at end of file diff --git a/docs/pt-br/policies/overview.mdx b/docs/pt-br/policies/overview.mdx index d42ea8d8..11e8cc69 100644 --- a/docs/pt-br/policies/overview.mdx +++ b/docs/pt-br/policies/overview.mdx @@ -1,6 +1,6 @@ --- title: "Policies" -description: "Observe, guide ou bloqueie ações do agente antes que uma falha conhecida se repita." +description: "Observe, guie ou bloqueie ações de agentes antes que uma falha conhecida se repita." icon: "shield-check" --- @@ -10,54 +10,45 @@ Uma policy avalia um evento de hook do agente e retorna uma de três decisões: - `instruct` fornece orientação corretiva ao agente. - `deny` bloqueia a ação com uma justificativa. -## Use as três superfícies de policy +## Onde as policies ficam - - - 1. Acesse **Observe → policy** para filtrar e inspecionar decisões de policy em sessões. - 2. Acesse **Admin → policy editor** para compor, validar, publicar, desativar ou inspecionar versões imutáveis. - 3. Acesse **Admin → enforcement** para atribuir versões e efeitos a máquinas. +| No dashboard | O que você faz lá | +| --- | --- | +| **Observe → policy** | Revise decisões de sessões reais: qual policy correspondeu, em qual máquina e por quê | +| **Admin → policy editor** | Escreva uma policy, faça backtest contra tráfego anterior, publique uma versão imutável e compare versões na **library** | +| **Admin → enforcement** | Coloque versões em máquinas, no modo observe ou enforce | - Use a página de Policy para entender o que já está sendo correspondido antes de criar ou alterar o enforcement. +O editor de policies é onde uma falha se transforma em regra. Descreva o modo de falha ou cole o código-fonte da policy em **compose**, faça backtest do rascunho contra o tráfego que você já possui e publique uma versão: - ![A página de Policy exibindo totais de decisões e mapeamentos de policy locais e gerenciados pela Cloud.](/images/dashboard/policy-observe.png) +![A visão compose do editor de policies com identidade da policy, criação assistida por IA, validação de código-fonte e controles de publicação.](/images/dashboard/policy-editor.png) - O editor é onde você transforma uma condição de falha em código-fonte, valida e publica uma versão imutável. +Em uma máquina, `failproofai policies` lista tudo que está sendo aplicado ali. `fp policies` e `fp fleet` cobrem o editor e o enforcement a partir de um terminal — veja a [referência do Cloud CLI](/pt-br/reference/cloud-cli). - ![O editor de Policy usado para compor e publicar uma versão imutável de policy.](/images/dashboard/policy-editor.png) +## Obter uma policy - O enforcement então atribui essa versão publicada e seu efeito de observe ou enforce às máquinas. - - ![A frota de Enforcement exibindo cobertura de máquinas e versões de policy atribuídas.](/images/dashboard/enforcement-fleet.png) - - Verifique as decisões na página de Policy após a implantação para que as visualizações de autoria e de frota estejam vinculadas à atividade real do agente. - - - Use `failproofai` para instalação e validação de policies locais: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - Use `fp` para encontrar as sessões e eventos da Cloud que contêm decisões de policy. A autoria na Cloud e a implantação em frota continuam sendo fluxos de trabalho do dashboard. - - - -As policies têm três superfícies distintas no Failproof AI: - -1. **Analisar decisões** em sessões, dashboards e auditorias. -2. **Criar versões** com regras embutidas, código ou o editor de policy. -3. **Implantar e aplicar** versões em máquinas selecionadas. - -Comece a partir de um modo de falha confirmado. Defina o menor evento e correspondência de ferramenta que o identifique, teste exemplos legítimos e inseguros e, em seguida, observe antes de aplicar o enforcement. +Há duas formas de obter uma. - - Ative uma regra revisada para riscos comuns de segredos, shell, Git, cloud e fluxo de trabalho. + + Deixe o Failproof AI criar uma a partir de uma descoberta de auditoria, ou escreva o código-fonte você mesmo, depois revise e publique no editor. - - Expresse uma decisão específica de fluxo de trabalho em JavaScript ou TypeScript. + + Conecte um policy pack do Failproof AI para o seu caso de uso, ou um pack da comunidade no hub de policies, com um único comando. - \ No newline at end of file + + +## Depois, coloque em produção + + + + Faça backtest do rascunho contra o tráfego que você já possui e execute-o contra uma ação que ele deve bloquear e uma que ele deve permitir — tudo antes de publicar. Veja [Testar uma policy](/pt-br/policies/test). + + + Coloque a versão em máquinas no modo **observe**, leia suas decisões, depois aplique o enforcement. Veja [Fazer deploy de uma policy](/pt-br/policies/deploy). + + + Cada publicação é uma nova versão imutável, então um rollout que bloqueia trabalho válido é desfeito simplesmente reimplantando a última versão boa. Veja [Versões e rollback](/pt-br/policies/rollback). + + + +Para compartilhar suas policies com outras equipes, [publique-as como um pack](/pt-br/policies/publish-a-pack). Para entender o que acontece quando uma policy não pode ser avaliada, veja [Comportamento em caso de falha](/pt-br/policies/failure-behavior). \ No newline at end of file diff --git a/docs/pt-br/policies/packs.mdx b/docs/pt-br/policies/packs.mdx index 7a25d459..9771245a 100644 --- a/docs/pt-br/policies/packs.mdx +++ b/docs/pt-br/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "Pacotes de políticas" -description: "Instale um conjunto de políticas publicado como uma release do GitHub e gerencie o que ele aplica." +title: "Usar um pacote de políticas" +description: "Conecte um pacote de políticas do Failproof AI para o seu caso de uso, ou um pacote da comunidade do hub de políticas, e escolha o que ele aplica." icon: "package" --- -Um pacote é um conjunto de políticas publicado como uma release do GitHub. Um único comando o instala, os checksums da própria release são verificados antes de qualquer execução, e o digest é registrado para que o pacote não possa ser alterado na sua máquina depois disso. +Um pacote é um conjunto de políticas publicado como uma release do GitHub. Um único comando o instala: os checksums da release são verificados antes de qualquer execução, e o digest é registrado para que o pacote não possa ser alterado na sua máquina posteriormente. -## Instalar as políticas do Failproof AI +Explore todos os pacotes e cada política em cada um deles no [hub de políticas](https://befailproof.ai/policy-hub/). Há dois tipos: + +- **Pacotes de políticas Failproof AI** — pacotes prontos para casos de uso predefinidos: conecte um e ele funciona. O [pacote de políticas para agente de codificação](https://befailproof.ai/policy-hub/failproofai/policies/) está disponível agora, e pacotes para mais casos de uso estão chegando em breve. +- **Pacotes de políticas da comunidade** — políticas que desenvolvedores criaram para seus próprios casos de uso e publicaram para qualquer pessoa usar. + +## Pacotes de políticas Failproof AI + +### Pacote de políticas para agente de codificação ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -Isso instala o conjunto que publicamos, a partir da cópia incluída no pacote — portanto, não precisa de rede e não falha por causa de um proxy. Para instalar apenas parte dele: +O pacote contém 38 políticas e ativa as 10 que seu manifesto marca como seguras para habilitar sem supervisão; as demais são listadas para você escolher. Algumas das mais usadas, e se um simples `policies add` as ativa: + +| Política | O que faz | Ativa por padrão | +| --- | --- | --- | +| `block-push-master` | Bloqueia pushes diretos para branches protegidas | Sim | +| `block-env-files` | Bloqueia leitura e escrita de arquivos `.env` | Sim | +| `protect-env-vars` | Bloqueia comandos que expõem variáveis de ambiente | Sim | +| `block-sudo` | Bloqueia `sudo` a menos que um padrão de permissão corresponda | Sim | +| `block-curl-pipe-sh` | Bloqueia scripts baixados redirecionados diretamente para um shell | Sim | +| `sanitize-*` (cinco políticas) | Reporta chaves de API, bearer tokens, JWTs, chaves privadas e strings de conexão encontradas na saída das ferramentas | Sim | +| `block-rm-rf` | Bloqueia exclusões recursivas catastróficas | Não | +| `block-force-push` | Bloqueia force-pushes | Não | +| `block-secrets-write` | Bloqueia escrita em arquivos de credenciais e chaves secretas | Não | +| `warn-destructive-sql` | Avisa sobre `DROP`, `TRUNCATE` e `DELETE` sem `WHERE` | Não | + +Ative qualquer uma que esteja desativada pelo nome — `failproofai policies add block-rm-rf` — ou pegue o pacote inteiro com `--all`. Veja todas as políticas nele, agrupadas por categoria: ```bash -failproofai pack add core --policy block-rm-rf # uma, ou algumas separadas por vírgula -failproofai pack add core --category dangerous-commands # uma categoria inteira -failproofai pack add core --all # tudo que está nele +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` lista todas as categorias que o pacote oferece. +## Pacotes de políticas da comunidade -## Ver o que um pacote contém antes de instalá-lo +Desenvolvedores publicam pacotes para os casos de uso que encontraram, e o [hub de políticas](https://befailproof.ai/policy-hub/) os lista. Um pacote da comunidade é publicado pelo seu autor e não é auditado pelo Failproof AI, então leia o que ele contém antes de instalá-lo: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -Lista todas as políticas que o pacote inclui, agrupadas por categoria, indicando quais foram ativadas por padrão pelo autor e quais são opcionais. Ele lê **apenas o manifesto** — o artefato de entrada nunca é baixado nem importado, portanto, inspecionar o pacote de um desconhecido não executa código desconhecido. O manifesto ainda é verificado contra o `SHA256SUMS` da própria release, garantindo que o que você está lendo é exatamente o que seria instalado. - -`failproofai pack list` sem nenhuma fonte lista os pacotes já instalados aqui. +Isso lista todas as políticas que ele contém, agrupadas por categoria, e marca quais o autor ativa por padrão. Ele lê **apenas o manifesto** — o artefato de entrada nunca é baixado ou importado, então examinar o pacote de um desconhecido não pode executar o código de um desconhecido. O manifesto ainda é verificado contra o `SHA256SUMS` da própria release, então o que você lê é exatamente o que seria instalado. -## Instalar o pacote de outra pessoa +Em seguida, instale-o: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -Qualquer um destes formatos funciona — cole o que você tiver: +Qualquer uma dessas formas funciona — cole a que você tiver: | Fonte | Resultado | | --- | --- | -| `acme/support-agent` | Release mais recente, **fixada** na tag exata que foi resolvida | +| `acme/support-agent` | Release mais recente, **fixada** à tag exata que foi resolvida | | `acme/support-agent@v2.1.0` | Aquela release | -| `github:acme/support-agent@v2.1.0` | O mesmo, escrito explicitamente | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | O mesmo, copiado do navegador | +| `github:acme/support-agent@v2.1.0` | A mesma, escrita explicitamente | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | A mesma, copiada de um navegador | -Não informar uma tag instala a release mais recente **e a fixa**, informando qual tag foi escolhida. O que fica registrado sempre nomeia exatamente uma release, portanto uma reinstalação não pode gerar divergências. +Não informar nenhuma tag instala a release mais recente **e a fixa**, e depois informa qual tag foi escolhida. O que é registrado sempre nomeia exatamente uma release, portanto uma reinstalação não pode divergir. -## Usar apenas parte de um pacote +## Usar parte de um pacote -Por padrão, você obtém os **próprios** padrões do pacote — as políticas que o autor marcou como seguras para ativar sem supervisão — e não tudo que ele contém. +Por padrão, você recebe os **próprios** padrões do pacote — as políticas que o autor marcou como seguras para ativar sem supervisão — não tudo o que ele contém. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # uma, ou algumas separadas por vírgula +failproofai policies add FailproofAI/policies --category dangerous-commands # uma categoria inteira +failproofai policies add FailproofAI/policies --all # tudo nele ``` -`--category` e `--policy` se combinam como uma união (`--only` é aceito como sinônimo de `--policy`). Adicionar novamente em uma versão mais recente mantém o que você escolheu, em vez de reativar o restante. +`--category` e `--policy` se combinam como uma união (`--only` é aceito como sinônimo de `--policy`). Quando o pacote já está instalado, os flags adicionam ao que você tinha, e re-adicioná-lo sem flag e sem terminal — para atualizar, por exemplo — mantém sua seleção como está. Em um terminal sem flag, `add` abre o seletor em vez disso, pré-marcado com os padrões do autor, e o que você marcar substitui sua seleção. ## Gerenciar o que está ativo ```bash -failproofai policies # todas as fontes em uma lista, incluindo pacotes -failproofai pack list # apenas pacotes, agrupados por categoria -failproofai policies --uninstall block-refunds # desativar uma política de pacote +failproofai policies # cada fonte em uma lista, pacotes incluídos +failproofai policies add block-rm-rf # ativar uma política +failproofai policies --uninstall block-refunds # desativar uma política do pacote failproofai policies --install block-refunds # e reativá-la -failproofai pack remove acme/support-agent +failproofai policies remove acme/support-agent # desinstalar o pacote ``` -Um nome simples refere-se ao **builtin** quando existe um com esse nome. Nomeie explicitamente a cópia de um pacote quando necessário: +Ativar ou desativar uma política de pacote se aplica a toda a máquina: a alteração é registrada com o pacote instalado, não na configuração de um projeto, independentemente do que `--scope` diga. + +Um nome sem barra é uma política; qualquer coisa com uma barra é uma fonte de pacote. Um nome simples resolve para o pacote instalado que o declara. Quando dois pacotes instalados declaram o mesmo nome, especifique o que você quer dizer: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -Se um pacote incluir uma política cujo nome também seja um **builtin habilitado**, o builtin é executado e a cópia do pacote é ignorada — caso contrário, a mesma proteção seria avaliada duas vezes. Desative o builtin para usar a cópia do pacote em seu lugar. - - -## De onde vêm as políticas do Failproof AI - -`core` lê a cópia incluída no pacote npm. O mesmo conjunto é publicado como uma release do GitHub, que é o que você instala se quiser uma versão específica: - -```bash -failproofai pack add core # do pacote atual, sem rede -failproofai pack add FailproofAI/policies # o mesmo conjunto, a partir da release no GitHub -``` +Escopos, parâmetros e os arquivos que esses comandos escrevem estão cobertos em [configuração local](/pt-br/policies/local-configuration). ## O que a integridade garante e o que não garante -`SHA256SUMS` é incluído na mesma release que o artefato, portanto **não** é uma assinatura e não prova nada sobre quem o publicou. O que ele prova é que os bytes são os que aquela release publicou — e como o digest é registrado quando você adiciona o pacote e reverificado antes de cada importação, um pacote não pode ser alterado na sua máquina depois disso. Um repositório que retaguea ou substitui um asset para de carregar em vez de executar silenciosamente algo diferente. +`SHA256SUMS` é distribuído na mesma release que o artefato, portanto **não** é uma assinatura e não prova nada sobre quem o publicou. O que ele prova é que os bytes são os que aquela release publicou — e como o digest é registrado quando você adiciona o pacote e reverificado antes de cada importação, um pacote não pode ser alterado na sua máquina posteriormente. Um repositório que troca a tag ou substitui um asset para de carregar em vez de executar silenciosamente outra coisa. -No momento da instalação, o pacote também é **importado uma vez** e verificado contra seu próprio manifesto. Um pacote cujo artefato não pode ser analisado, ou que registra algo diferente do que declara, é recusado antes de qualquer ativação — em vez de instalar normalmente e falhar na próxima chamada de ferramenta. +No momento da instalação, o pacote também é **importado uma vez** e verificado contra seu próprio manifesto. Um pacote cujo artefato não seja analisável, ou que registre algo diferente do que declara, é recusado antes que qualquer coisa seja ativada — em vez de instalar sem erros e falhar na sua próxima chamada de ferramenta. ## Quando um pacote não carrega -Um pacote que esta máquina foi instruída a aplicar e não consegue executar **nega** os eventos cobertos pelas políticas ausentes, em vez de permitir silenciosamente. Consulte [Comportamento em falhas](/pt-br/policies/failure-behavior). `failproofai pack list` identifica qualquer pacote nesse estado e encerra com código diferente de zero. +Um pacote que esta máquina foi instruída a aplicar e não consegue executar **nega** os eventos cobertos pelas políticas ausentes, em vez de permitir silenciosamente — como `pack/failproofai-pack-unavailable`, que tem prioridade sobre as políticas que foram carregadas, de modo que a negação é atribuída ao pacote ausente e não a qualquer guarda que por acaso tenha disparado primeiro. A exceção é `UserPromptSubmit`, que instrui em vez de negar: negar ali bloquearia seu acesso ao agente que você precisa para corrigir o problema. Veja [Comportamento em falhas](/pt-br/policies/failure-behavior). ## Offline e espelhos | Variável | Efeito | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Recusa fazer downloads; pacotes já instalados continuam sendo aplicados | -| `FAILPROOFAI_PACK_BASE_URL` | Direciona o download de pacotes para um espelho em vez do `github.com` | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Recusa buscar dados; pacotes já instalados continuam aplicando políticas | +| `FAILPROOFAI_PACK_BASE_URL` | Direciona a busca de pacotes para um espelho em vez de `github.com` | -Para publicar seu próprio pacote, consulte [Publicar um pacote](/pt-br/policies/publish-a-pack). \ No newline at end of file +Para compartilhar suas próprias políticas dessa forma, veja [Publicar um pacote de políticas](/pt-br/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/pt-br/policies/publish-a-pack.mdx b/docs/pt-br/policies/publish-a-pack.mdx index b91815c2..a7e4c7d3 100644 --- a/docs/pt-br/policies/publish-a-pack.mdx +++ b/docs/pt-br/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "Publicar um pack" +title: "Publicar um pacote de políticas" description: "Distribua suas próprias políticas como uma release do GitHub que qualquer pessoa pode instalar." icon: "upload" --- -Um pack consiste em três arquivos anexados a uma release do GitHub. `failproofai pack build` gera os três a partir de um arquivo de política que você já possui. +Um pacote consiste em três arquivos anexados a uma release do GitHub. O comando `failproofai publish` gera os três a partir dos arquivos de políticas fornecidos, cria a release e faz o upload deles. ## 1. Escreva as políticas -Um único arquivo, usando a mesma API de qualquer política personalizada. Dois campos extras são importantes para um pack: +Comece a partir de algo que já funciona, em vez de um template em branco: + +```bash +failproofai publish --init +``` + +O comando pergunta o nome do pacote, gera `.mjs` e encerra — sem rede, sem git, sem nada publicado. O arquivo gerado contém uma política que já bloqueia `git push --force`. Ele se recusa a sobrescrever um arquivo existente. + +As políticas usam a mesma API que qualquer política personalizada. Dois campos extras são relevantes para um pacote: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -16,8 +24,8 @@ import { customPolicies, deny, allow } from "failproofai"; customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", - category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + category: "Billing", // agrupa a política; é o que --category seleciona + defaultEnabled: true, // ativada por um `policies add` simples match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` assume o valor **false** quando omitido. Um `failproofai pack add` simples ativa apenas o que você marcou — instalar todas as políticas de um desconhecido sem supervisão não é uma decisão que o instalador deve tomar pelo usuário. +`defaultEnabled` assume o valor **false** quando omitido. Um `failproofai policies add` simples ativa apenas o que você marcou — instalar todas as políticas de um desconhecido sem supervisão não é uma decisão que o instalador deve tomar pelo usuário. + +Escreva quantos arquivos quiser; um por categoria facilita a leitura. Todos os arquivos do diretório que registram políticas são empacotados em um único artefato, que é o que um pacote deve ser. -O entry deve ser **um único arquivo autocontido**. Apenas o entry tem seu digest fixado, então um pack que importa arquivos locais não poderia honestamente afirmar que o digest cobre o que é executado. Faça o bundle primeiro (`esbuild`, `bun build`, `rollup`) e construa o pack a partir do bundle — `pack build` rejeita uma importação local em vez de fazer uma promessa que não pode cumprir. + O empacotamento requer **bun**. Sem ele, mantenha um único arquivo autocontido. De qualquer forma, o entry point publicado não deve importar arquivos locais no momento da instalação: apenas o entry point tem o digest fixado, então um pacote que buscasse arquivos vizinhos não poderia garantir honestamente que o digest cobre o que é executado — e o `publish` se recusa a publicá-lo em vez de entregar uma promessa que não pode cumprir. -## 2. Construa os assets da release +## 2. Teste localmente primeiro + +Antes que qualquer outra pessoa possa ver o pacote, aplique o arquivo nesta máquina: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +Qualquer caminho, qualquer nome de arquivo. Peça ao seu agente para executar a ação que você bloqueou e observe a recusa. Nada é publicado e ninguém mais é afetado. [Testar uma política](/pt-br/policies/test) cobre o restante: o caso legítimo que deve ser permitido e as entradas que a quebram. + +## 3. Publique + +```bash +failproofai publish ``` -O comando gera três arquivos e valida todas as políticas com as **próprias regras do loader** primeiro — assim, um pack que nunca poderia ser instalado falha aqui, onde você pode corrigir: +O comando descobre onde publicar, o que empacotar e qual versão atribuir, e só pergunta quando o repositório não fornece essa informação. Em ordem, interrompendo antes de criar uma release se algo estiver errado: + +1. Encontra os arquivos de política pelo **conteúdo** — aqueles que importam `failproofai` e chamam `customPolicies.add` — e não pelo nome do arquivo. Assim, encontra `guards.mjs` e ignora um `policies.mjs` não relacionado. Não desce em subdiretórios, portanto fixtures de teste nunca são incluídas por acidente. +2. Lê o repositório via `git remote get-url origin`, no diretório do **arquivo** e não no seu, e determina a versão. +3. Encontra sua credencial: `GITHUB_TOKEN`, `GH_TOKEN` ou `gh auth login`. Requer apenas permissão de escrita em releases e nunca é exibida. +4. Cria o repositório se ele não existir. Isso ocorre antes do build, então um pacote recusado na etapa seguinte pode deixar um novo repositório sem nenhuma release. +5. Faz o build dos três assets, validando-os com as **próprias regras do loader** — o mesmo código que decide o que pode ser instalado na máquina de outra pessoa — para que um pacote que nunca poderia ser instalado falhe aqui, onde você ainda pode corrigi-lo. +6. Cria ou reutiliza a release e faz o upload, substituindo assets de mesmo nome. | Arquivo | O que é | | --- | --- | -| `failproofai-pack.json` | O manifest: id, versão, efeito e uma entrada por política | -| `failproofai-pack.mjs` | Seu entry, literalmente | -| `SHA256SUMS` | ` ` para os outros dois | +| `failproofai-pack.json` | O manifesto: id, versão, efeito e uma entrada por política | +| `failproofai-pack.mjs` | Seu entry point empacotado | +| `SHA256SUMS` | ` ` para os outros dois | -Rejeitado no momento do build: um id que não segue o formato `publisher/name`, um nome de política contendo `/`, uma política declarando `alwaysOn`, `description`, `category` ou `match` ausentes, um entry que não registra nada e um entry que importa arquivos locais. +Os nomes dos assets são fixos — são eles que a CLI do consumidor usa para construir as URLs, sem chamadas de API e sem descoberta dinâmica. -## 3. Anexe os arquivos à release +Recusado no momento do build: um id que não seja `publisher/name`, um nome de política contendo `/`, uma política que declare `alwaysOn`, uma `description`, `category` ou `match` ausente, um entry point que não registra nada e um entry point que importa arquivos locais. -Crie a tag da release com a mesma versão que você usou no build e anexe os três arquivos como assets da release: +Substitua qualquer decisão tomada automaticamente: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -Agora qualquer pessoa pode instalá-lo: +`--id` define o id do pacote quando ele deve diferir do repositório, `--tag` define a tag da release, `--notes` substitui as notas de release geradas automaticamente — que é onde `policies show --releases` lê a contagem e o commit de cada release — `--out` escolhe onde os assets são gravados (padrão: `dist-pack`) e `--dry-run` faz o build sem publicar e não requer credencial. -```bash -failproofai pack add acme/support-agent -``` +Qualquer pessoa pode agora instalar o pacote com `failproofai policies add acme/support-agent`. Consulte [pacotes de políticas](/pt-br/policies/packs) para fixar uma versão ou instalar apenas parte de um pacote. + +### Liste no hub de políticas -Os nomes dos assets são fixos — são eles que a CLI do consumidor usa para construir suas URLs, sem chamada de API nem descoberta automática. +Adicione o tópico `failproofai-policies` ao repositório no GitHub. Não há formulário de envio nem fila de aprovação: o crawler do [policy hub](https://befailproof.ai/policy-hub/) indexa o repositório na próxima varredura. O tópico apenas o coloca em consideração — o que efetivamente o lista é uma release cujo manifesto se verifica contra seu próprio `SHA256SUMS` e é parseado pelas mesmas regras que a CLI usa, que é exatamente o que `failproofai publish` produz. + +## Como a versão é determinada + +A versão é o **commit a partir do qual você está publicando** — seu sha curto, doze caracteres: `a1b2c3d4e5f6`. Não há nada para escolher nem incrementar, e a versão identifica exatamente a origem dos bytes, então publicar a mesma fonte duas vezes produz a mesma versão. + +Ela é lida da árvore à sua frente, nunca das releases do repositório, então um clone recente e uma máquina air-gapped calculam a mesma resposta sem consultar o GitHub sobre o histórico. + +Como a versão nomeia um commit, esse commit precisa existir. Em um terminal, o `publish` cria um para você: inicializa um repositório quando não há nenhum e faz commit dos arquivos de política alterados antes do build. Ele **se recusa** — indicando `--version` como saída — quando executado sem terminal (um commit feito em um runner de CI não existiria em nenhum outro lugar), quando há arquivos além das políticas sem commit, ou em um checkout sem commits ainda. Uma tag no `HEAD` tem prioridade sobre o sha — quem taggeou `v1.2.0` declarou o que essa release é. + +Um sha não carrega ordenação própria, então use `failproofai policies show / --releases` para ver qual release veio primeiro — a mais recente no topo. ## Lançando uma nova versão -Faça o build com o novo `--version`, crie uma nova release com a tag correspondente e anexe os três assets novamente. Os consumidores executam o mesmo `pack add` e mantêm o subconjunto que haviam escolhido; uma política que foi desativada permanece desativada após a atualização. +Faça commit da alteração e execute `failproofai publish` novamente — o novo commit é a nova versão. Os consumidores executam o mesmo `failproofai policies add`. Sem terminal, ou com uma flag de seleção, eles mantêm o subconjunto que haviam escolhido e uma política desativada permanece desativada; em um terminal sem flag, o seletor abre pré-marcado com seus padrões e a resposta do usuário substitui a seleção anterior. -Alterar o **nome** de uma política é uma mudança incompatível: uma máquina que a havia desativado está desativando um nome que não existe mais, e o novo nome chega com o valor que `defaultEnabled` define. +Alterar o **nome** de uma política é uma mudança incompatível: uma máquina que havia desativado esse nome está desativando um nome que não existe mais, e o novo nome chega com o valor que `defaultEnabled` define. ## O que seus usuários estão confiando -O `SHA256SUMS` fica na mesma release que o artefato, portanto comprova que os bytes são os que você publicou — mas não comprova quem você é. Qualquer pessoa com acesso de escrita ao repositório pode modificar ambos os arquivos. A proteção dos seus usuários está no fato de que o digest é fixado no momento da instalação, de modo que o que você distribuiu não pode ser alterado depois. +O `SHA256SUMS` fica na mesma release que o artefato, então prova que os bytes são os que você publicou — mas não quem você é. Qualquer pessoa com acesso de escrita ao repositório pode escrever ambos os arquivos. A proteção dos seus usuários é que o digest é fixado no momento da instalação, então o que você enviou não pode mudar depois. + +Publique a partir de um repositório cujo acesso de escrita você controla, e trate uma release de pacote como a publicação de um pacote de software. -Publique a partir de um repositório cujo acesso de escrita você controla e trate uma release de pack como a publicação de um pacote. +O repositório também deve ser **público**. As instalações usam HTTPS anônimo sem credencial, então um repositório privado existente é recusado antes de qualquer build ou upload, e um repositório criado pelo `publish` também é público pelo mesmo motivo. `--allow-private` substitui esse comportamento para quem distribui os três assets por outro meio, e indica claramente que nenhum `policies add` poderá acessá-los. Apenas a release importa: as instalações leem `releases/download//` e nunca tocam na árvore git. ## Observe antes de aplicar -Um manifest pode declarar `"effect": "observe"`. Essas políticas são executadas e seus vereditos são **registrados e descartados** — nada é bloqueado. É a forma de medir uma nova regra contra tráfego real antes que ela possa interromper o trabalho de alguém. +Um manifesto pode declarar `"effect": "observe"` — `failproofai publish --effect observe` é o que o define. Essas políticas são executadas e seus vereditos são **registrados e descartados** — nada é bloqueado. É a forma de medir uma nova regra contra tráfego real antes que ela possa interromper o trabalho de alguém. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/pt-br/policies/rollback.mdx b/docs/pt-br/policies/rollback.mdx index 034bd511..8c23a3bc 100644 --- a/docs/pt-br/policies/rollback.mdx +++ b/docs/pt-br/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "Rollback" -description: "Restaure uma implantação de política conhecida quando um rollout interromper trabalhos válidos de agentes." +title: "Versões e rollback" +description: "Cada publicação gera uma versão imutável, então um rollout que interrompe trabalhos válidos do agente é desfeito reimplantando a última versão estável." icon: "rotate-ccw" --- -O rollback altera a versão implantada ou remove uma atribuição de política; ele não apaga o histórico de decisões que explica o incidente. +Uma versão de política publicada nunca muda. Editar uma política e publicar novamente cria uma nova versão; ela nunca sobrescreve a que já está nas máquinas. É isso que torna o rollback seguro: a última versão estável ainda está lá, byte por byte, e fazer o rollback não apaga o histórico de decisões que explica o que deu errado. -## Reverter uma máquina +## Encontrar uma versão - 1. Acesse **Admin → enforcement**, expanda a máquina afetada e identifique seu último conjunto de políticas conhecido como funcional. - 2. Selecione **edit**, restaure as versões e efeitos anteriores e aplique a nova implantação. - 3. Aguarde o check-in da máquina e verifique a implantação reportada. - 4. Abra **Observe → policy** e as sessões afetadas para confirmar que trabalhos válidos não estão mais sendo bloqueados. + Vá para **Admin → policy editor** e abra **library** para comparar as versões de uma política ou desativar uma delas. + + + ```bash + fp policies list # todas as versões de política + fp policies show # uma versão específica, com seu código-fonte + ``` + + +## Fazer rollback em uma máquina + + + + 1. Vá para **Admin → enforcement**, expanda a máquina afetada e identifique seu último conjunto de políticas estável. + 2. Selecione **edit**, restaure essas versões e efeitos e aplique a nova implantação. + 3. Aguarde o check-in da máquina e verifique a implantação reportada. + 4. Abra **Observe → policy** e as sessões afetadas para confirmar que o trabalho válido não está mais sendo bloqueado. - O rollback de implantações na nuvem é um fluxo do dashboard. Use o status local para confirmar que a implantação corrigida chegou à máquina: + Cada implantação em uma máquina é uma geração numerada. Liste-as e, em seguida, restaure uma: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` pausa as políticas built-in, personalizadas e de convenção para uma sessão local. Ele não pausa políticas gerenciadas pela nuvem, portanto não é uma solução alternativa para uma implantação Cloud com problemas. + O `rollback` cria uma nova geração carregando o conjunto antigo em vez de retroceder o contador, então o histórico permanece apenas-apenso. Ele recusa uma geração que referencia uma política desativada ou excluída. Requer uma sessão autenticada com `policies:write`. O `fp fleet diff ` mostra o que foi planejado versus o que a máquina aplicou — aparece como `behind` até a próxima vez que a máquina fizer polling — e na própria máquina, `failproofai policies` lista a implantação em execução. +## Remover uma política de todas as máquinas + +```bash +fp policies disable # remove de toda implantação que a contenha +fp policies enable # adiciona de volta +``` + +Cada comando cria uma nova geração em cada implantação que ele afeta. Porém, fazer rollback de uma dessas gerações não é a forma de desfazer um `disable` — o `rollback` recusa uma geração que referencia uma política desativada, e toda geração anterior ao disable referencia esta. O caminho de volta é `fp policies enable`, que por sua vez cria sua própria geração. + +## Fazer rollback de um pack + +Um pack fica fixado na versão que você instalou, então fazer rollback significa instalar uma versão anterior: + +```bash +failproofai policies show FailproofAI/policies --releases # todas as versões publicadas e qual está instalada +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # fixar essa versão +``` + +Sem um terminal, ou com `--policy`, `--category` ou `--all`, readicionar mantém o subconjunto que você havia escolhido. Em um terminal sem nenhuma dessas flags, o seletor abre pré-marcado com os padrões do autor, e o que você marcar substitui sua seleção — portanto, remarque o que você tinha. + ## Quando fazer rollback -- Uma política bloqueia uma ação de produção esperada. -- O volume de correspondências é materialmente maior do que o rollout observado havia previsto. +- Uma política bloqueia uma ação esperada em produção. +- O volume de correspondências é materialmente maior do que o previsto no rollout observado. - Uma política depende de campos que uma integração não fornece. - Uma nova versão altera o comportamento fora do modo de falha pretendido. -Após o rollback, abra as sessões afetadas e identifique a condição que causou o falso positivo. Crie uma nova versão, teste tanto os casos inseguros quanto os legítimos e repita a fase de observação. +Após o rollback, abra as sessões afetadas e identifique a condição por trás do falso positivo. Publique uma nova versão, [teste](/pt-br/policies/test) tanto o caso inseguro quanto o legítimo e observe-a novamente antes de enforçar. - Pausar o enforcement pode ser adequado durante um incidente, mas amplia a exposição para todas as políticas ativas naquele escopo. Prefira reverter a versão específica da política sempre que possível. + O `failproofai config --pause` suspende as políticas locais por uma sessão e nunca as gerenciadas pela Cloud, portanto não é uma saída para uma implantação Cloud problemática. Uma pausa também amplia a exposição para todas as políticas em seu escopo; prefira fazer rollback da versão específica que está se comportando incorretamente. \ No newline at end of file diff --git a/docs/pt-br/policies/test.mdx b/docs/pt-br/policies/test.mdx new file mode 100644 index 00000000..b1dbdb37 --- /dev/null +++ b/docs/pt-br/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "Testar uma política" +description: "Faça backtest de um rascunho com o tráfego que você já possui e comprove que ela bloqueia o que deve bloquear e permite o que deve permitir, antes que qualquer máquina a aplique." +icon: "flask-conical" +--- + +Teste cada política de duas formas: com o tráfego que seus agentes já produziram e com uma ação legítima que ela deve permitir. Uma política que só foi testada com o caso inseguro não foi verdadeiramente testada. + +## Faça backtest do rascunho + + + + O editor de políticas reproduz um rascunho com as chamadas que sua frota já realizou, antes de você publicá-lo. + + 1. Abra o rascunho em **Admin → policy editor**. O editor confirma que o código é um JavaScript válido. + 2. Em **backtest**, escolha os agentes e o intervalo de tempo a reproduzir — **every agent** e **30d** por padrão — e deixe o último filtro em **everything**, a menos que queira restringir o escopo. + 3. Selecione **run backtest**. + + ![O painel de backtest abaixo de um rascunho que é um JavaScript válido, com seus três filtros e a ação de executar backtest, acima de publicar versão.](/images/dashboard/policy-backtest.png) + + O resultado mostra o que o rascunho teria feito com essas chamadas — incluindo quantas chamadas **funcionando** ele teria interrompido. Esses são falsos positivos encontrados antes que qualquer agente os encontre: ajuste o rascunho e execute novamente até que esse número seja aceitável. + + + O backtest é um recurso do dashboard. No terminal, execute a política com eventos que você descrever diretamente, conforme explicado abaixo. + + + +## Execute contra um evento que você descreve + +`fp policies test` executa um arquivo de política na sua máquina com um evento sintético e verifica a decisão. Nada é publicado e nada chega à Cloud: + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +Modele o evento com `--event`, `--tool`, `--command` e `--file`. O filtro `match` da própria política ainda é aplicado, então uma política que não cobre o evento descrito reporta `skipped` em vez de uma decisão — geralmente um sinal de que seu `match` é mais restrito do que você pretendia. + +## Execute em uma máquina + +Em seguida, aplique a política de verdade na sua própria máquina, com o seu próprio agente: + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +O primeiro comando valida e instala o arquivo; o segundo confirma que ele foi carregado, junto com tudo mais que está sendo aplicado aqui. Peça ao agente para realizar o que a política bloqueia e observe a recusa; depois faça a versão legítima e observe que ela é permitida. Ninguém mais é afetado. + +Em uma máquina conectada à Cloud, verifique ambas as decisões em **Observe → policy**: filtre pelo nome da política e abra cada sessão vinculada para confirmar o input da ferramenta que foi correspondido e o motivo retornado. + +## Teste o que quebra + +A instalação rejeita um arquivo ausente, um erro de sintaxe, uma importação não resolvida, uma exceção de nível superior ou um módulo que excede o tempo limite ao carregar — portanto, reexecute após cada alteração no arquivo ou em qualquer coisa que ele importe. No momento de aplicação, o mesmo arquivo com problema é registrado e **ignorado** para que todas as outras políticas continuem em execução: trate um aviso de carregamento nos logs de produção como perda de aplicação. Os arquivos de convenção carregam sem o comando de instalação, então mantenha uma etapa explícita de `failproofai policies --install --custom ` no CI — é ela que falha o build quando uma política está com problema. + +Depois, alimente a política com o que os agentes realmente enviam, não apenas o input que você espera: campos ausentes, nomes de ferramentas alternativos como `Write` e `Edit`, caminhos do Windows, input malformado. Retorne um `allow`, `instruct` ou `deny` intencional em cada caminho, mantenha a função determinística e limite qualquer chamada externa com um timeout curto. + +## Publique e observe + +Um backtest mostra o que a política teria feito com o tráfego que você tinha; ele não consegue mostrar o que o tráfego ainda não visto fará. Selecione **publish version** no editor (ou execute `fp policies publish`), depois [faça o deploy](/pt-br/policies/deploy) no modo **observe** primeiro — os vereditos são registrados e nada é bloqueado — e aplique a política apenas quando suas correspondências separarem ações inseguras das válidas. \ No newline at end of file diff --git a/docs/pt-br/reference/cloud-cli.mdx b/docs/pt-br/reference/cloud-cli.mdx index b35971f8..9303d982 100644 --- a/docs/pt-br/reference/cloud-cli.mdx +++ b/docs/pt-br/reference/cloud-cli.mdx @@ -4,16 +4,16 @@ description: "Referência completa para consultar e administrar o Failproof AI C icon: "cloud-cog" --- -Use `fp` para inspecionar telemetria do Cloud, gerenciar enforcement gerenciado pela nuvem (políticas, implantações em frota, decisões de guardrail) e gerenciar auditorias, findings, issues, alertas, chaves, usuários, consultas e configurações. Use [`failproofai`](/pt-br/reference/failproof-cli) para hooks locais, políticas, captura e registro de máquinas. +Use `fp` para inspecionar telemetria do Cloud, gerenciar aplicação gerenciada pela nuvem (políticas, implantações em frota, decisões de guardrail) e gerenciar auditorias, descobertas, problemas, alertas, chaves, usuários, consultas e configurações. Use [`failproofai`](/pt-br/reference/failproof-cli) para hooks locais, políticas, captura e registro de máquinas. -Instale o Cloud CLI como uma ferramenta isolada: +Instale o Cloud CLI lançado como uma ferramenta isolada: ```bash uv tool install fp-cloud-cli fp version ``` -## Fazer login +## Entrar ```bash fp login @@ -32,7 +32,7 @@ As opções globais devem vir antes do comando: fp --json sessions --since 24h ``` -Execute `fp COMMAND --help` ou `fp COMMAND SUBCOMMAND --help` para ver a ajuda no terminal. +Execute `fp COMMAND --help` ou `fp COMMAND SUBCOMMAND --help` para obter ajuda no terminal. ## Comandos da CLI @@ -40,11 +40,11 @@ Execute `fp COMMAND --help` ou `fp COMMAND SUBCOMMAND --help` para ver a ajuda n | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp login` | Faz login com um código único enviado por e-mail e seleciona uma organização. | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | Revoga e remove a sessão de usuário salva. | — | -| `fp whoami` | Exibe a identidade atual, modo de autenticação, organização e permissões. | — | -| `fp version` | Exibe a versão instalada da CLI. | — | -| `fp help` | Exibe a ajuda dos comandos de nível superior. | — | +| `fp login` | Entrar com um código único enviado por e-mail e selecionar uma organização. | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | Revogar e remover a sessão de usuário salva. | — | +| `fp whoami` | Exibir a identidade atual, modo de autenticação, organização e permissões. | — | +| `fp version` | Exibir a versão da CLI instalada. | — | +| `fp help` | Exibir a ajuda dos comandos de nível superior. | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,24 +57,24 @@ fp whoami fp events [OPTIONS] ``` -Lista eventos individuais de agentes. O feed padrão (leve) exclui payloads brutos; use `--full` apenas para investigações delimitadas. +Lista eventos individuais de agentes. O feed leve padrão exclui payloads brutos; use `--full` apenas para investigações com escopo definido. | Opção | Descrição | | --- | --- | -| `--limit`, `-n ` | Número máximo total de linhas. Padrão: `50`. | +| `--limit`, `-n ` | Total máximo de linhas. Padrão: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` ou `7d`. | | `--from ` / `--to ` | Intervalo UTC em ISO 8601; substitui `--since`. | | `--env ` | Filtro de ambiente; repita ou separe valores por vírgula. | | `--event-type ` | Filtro de tipo de evento; repita ou separe valores por vírgula. | | `--agent-id ` | Filtro de agente; repita ou separe valores por vírgula. | | `--session-id ` | Filtro de sessão; repita ou separe valores por vírgula. | -| `--search ` | Busca de texto no payload; repetível, com correspondência em qualquer termo. | +| `--search ` | Busca de texto no payload; repetível, com correspondência de qualquer termo. | | `--order asc\|desc` | Ordem temporal. Padrão: mais recente primeiro. | -| `--all` | Pagina automaticamente até `--limit`. | -| `--cursor ` | Retoma a partir de um cursor opaco. | -| `--page-size ` | Linhas por requisição com `--all`; máximo `200`. | -| `--full` | Inclui payloads brutos via endpoint de eventos mais pesado. | -| `--fields ` | Retorna apenas os campos selecionados; solicitar `payload` ativa o modo full. | +| `--all` | Pagina automaticamente até o limite de `--limit`. | +| `--cursor ` | Retomar a partir de um cursor opaco. | +| `--page-size ` | Linhas por requisição com `--all`; máximo de `200`. | +| `--full` | Incluir payloads brutos via endpoint de eventos mais pesado. | +| `--fields ` | Retornar apenas os campos selecionados; solicitar `payload` habilita o modo completo. | ```bash fp events --session-id --order asc --all --limit 10000 @@ -82,7 +82,10 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` pagina **até `--limit`**, cujo padrão é **50** — portanto, `--all` sozinho para em 50 linhas. Quando para antes do fim, a resposta traz um `next_cursor` para retomar; `"next_cursor": null` indica que o feed foi realmente esgotado. + `--all` pagina **até `--limit`**, cujo padrão é **50** — portanto, `--all` sozinho + para em 50 linhas. Quando para antes do esperado, a resposta traz um + `next_cursor` para continuar; `"next_cursor": null` significa que o feed foi + realmente esgotado. ### Sessões @@ -93,19 +96,19 @@ fp sessions [OPTIONS] | Opção | Descrição | | --- | --- | -| `--limit`, `-n ` | Número máximo total de linhas. Padrão: `50`. | +| `--limit`, `-n ` | Total máximo de linhas. Padrão: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` ou `7d`. | | `--from ` / `--to ` | Intervalo UTC em ISO 8601; substitui `--since`. | | `--env ` | Filtro de ambiente; repita ou separe valores por vírgula. | | `--status ` | `done`, `error` ou `timeout`; repita ou separe valores por vírgula. | -| `--agent-id ` | Corresponde a sessões que envolvam qualquer agente selecionado. | +| `--agent-id ` | Corresponder sessões que envolvem qualquer agente selecionado. | | `--session-id ` | Filtro de sessão; repita ou separe valores por vírgula. | -| `--all` | Pagina automaticamente até `--limit`. | -| `--cursor ` | Retoma a partir de um cursor opaco. | -| `--page-size ` | Linhas por requisição com `--all`; máximo `200`. | -| `--fields ` | Retorna apenas os campos selecionados. | -| `--full-ids` | Não abrevia IDs de sessão na saída do terminal. | -| `--agents` | Expande o conjunto de agentes para sessões multi-agente. | +| `--all` | Pagina automaticamente até o limite de `--limit`. | +| `--cursor ` | Retomar a partir de um cursor opaco. | +| `--page-size ` | Linhas por requisição com `--all`; máximo de `200`. | +| `--fields ` | Retornar apenas os campos selecionados. | +| `--full-ids` | Não abreviar IDs de sessão na saída do terminal. | +| `--agents` | Expandir a lista de agentes para sessões com múltiplos agentes. | ### Avaliações @@ -115,15 +118,15 @@ fp evals [OPTIONS] | Opção | Descrição | | --- | --- | -| `--aggregate` | Exibe totais e estatísticas por pontuação em vez de avaliações individuais. | -| `--limit`, `-n ` | Número máximo de linhas na lista. Padrão: `50`. | -| `--since`, `--from`, `--to` | Seleciona o intervalo de tempo. | -| `--env`, `--status`, `--agent-id`, `--session-id` | Restringe a um valor exato por filtro. | +| `--aggregate` | Exibir totais e estatísticas por pontuação em vez de avaliações individuais. | +| `--limit`, `-n ` | Máximo de linhas na listagem. Padrão: `50`. | +| `--since`, `--from`, `--to` | Selecionar o intervalo de tempo. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Restringir a um único valor por filtro. | | `--score KEY:MIN..MAX` | Intervalo de pontuação; repetível e todos os intervalos devem corresponder. | -| `--all`, `--cursor`, `--page-size` | Controla a paginação da lista. | -| `--fields ` | Retorna apenas os campos selecionados. | -| `--full-ids` | Exibe IDs de sessão completos. | -| `--scores-full` | Exibe todas as pontuações na saída do terminal. | +| `--all`, `--cursor`, `--page-size` | Controlar a paginação da listagem. | +| `--fields ` | Retornar apenas os campos selecionados. | +| `--full-ids` | Exibir IDs de sessão completos. | +| `--scores-full` | Exibir todas as pontuações na saída do terminal. | ### Erros @@ -133,49 +136,49 @@ fp errors [OPTIONS] | Opção | Descrição | | --- | --- | -| `--aggregate` | Resume os erros correspondentes em vez de listar linhas. | -| `--limit`, `-n ` | Número máximo de linhas na lista. Padrão: `50`. | -| `--since`, `--from`, `--to` | Seleciona o intervalo de tempo. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Restringe a população de erros. | -| `--search ` | Busca texto no payload; repetível. | +| `--aggregate` | Resumir erros correspondentes em vez de listar linhas. | +| `--limit`, `-n ` | Máximo de linhas na listagem. Padrão: `50`. | +| `--since`, `--from`, `--to` | Selecionar o intervalo de tempo. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Restringir o conjunto de erros. | +| `--search ` | Buscar texto no payload; repetível. | | `--order asc\|desc` | Ordem temporal. | -| `--all`, `--cursor`, `--page-size` | Controla a paginação da lista. | -| `--fields ` | Retorna apenas os campos selecionados. | -| `--full-ids` | Exibe IDs de sessão completos. | +| `--all`, `--cursor`, `--page-size` | Controlar a paginação da listagem. | +| `--fields ` | Retornar apenas os campos selecionados. | +| `--full-ids` | Exibir IDs de sessão completos. | ### Uso e valores de filtro | Comando | Finalidade | | --- | --- | -| `fp usage` | Exibe o uso para a janela de medição atual. | -| `fp list envs` | Lista os ambientes observados. | -| `fp list agents` | Lista os IDs de agentes observados. | -| `fp list event_types` | Lista os tipos de eventos. | -| `fp list score_filters` | Lista as chaves de pontuação de avaliação. | -| `fp list models` | Lista os nomes de modelos. | -| `fp list hooks` | Lista os nomes de hooks. | -| `fp list tools` | Lista os nomes de ferramentas. | -| `fp list error_types` | Lista os tipos de erros. | +| `fp usage` | Exibir o uso da janela de medição atual. | +| `fp list envs` | Listar ambientes observados. | +| `fp list agents` | Listar IDs de agentes observados. | +| `fp list event_types` | Listar tipos de eventos. | +| `fp list score_filters` | Listar chaves de pontuação de avaliação. | +| `fp list models` | Listar nomes de modelos. | +| `fp list hooks` | Listar nomes de hooks. | +| `fp list tools` | Listar nomes de ferramentas. | +| `fp list error_types` | Listar tipos de erros. | ### Organizações | Comando | Finalidade | | --- | --- | -| `fp orgs list` | Lista as organizações acessíveis. | -| `fp orgs switch [SLUG]` | Salva uma organização ativa; solicita quando omitido. | -| `fp orgs current` | Exibe a organização ativa. | -| `fp orgs perms` | Exibe suas permissões na organização ativa. | +| `fp orgs list` | Listar organizações acessíveis. | +| `fp orgs switch [SLUG]` | Salvar uma organização ativa; solicita quando omitido. | +| `fp orgs current` | Exibir a organização ativa. | +| `fp orgs perms` | Exibir suas permissões na organização ativa. | ### Chaves de API | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp keys list` | Lista as chaves da organização. | `--show-id`; `--fields ` | -| `fp keys show NAME` | Exibe uma chave e suas concessões. | — | -| `fp keys create NAME` | Cria uma chave e revela seu segredo uma única vez. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | Substitui o conjunto de permissões ou ajusta as concessões. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | Rotaciona o segredo e revela o substituto uma única vez. | `--yes`, `-y` | -| `fp keys disable NAME` | Revoga permanentemente uma chave. | `--yes`, `-y` | +| `fp keys list` | Listar chaves da organização. | `--show-id`; `--fields ` | +| `fp keys show NAME` | Exibir uma chave e suas concessões. | — | +| `fp keys create NAME` | Criar uma chave e revelar seu segredo uma única vez. | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | Substituir o conjunto de permissões ou ajustar concessões. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | Rotacionar o segredo e revelar o substituto uma única vez. | `--yes`, `-y` | +| `fp keys disable NAME` | Revogar permanentemente uma chave. | `--yes`, `-y` | Os tokens de permissão usam o formato `resource:action`, como `events:add`. Repita `--add`, separe tokens por vírgula ou use ações com ponto, como `events:read.add`. @@ -183,68 +186,68 @@ Os tokens de permissão usam o formato `resource:action`, como `events:add`. Rep | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp query list` | Lista consultas salvas. | `--show-id`; `--fields ` | -| `fp query show NAME` | Exibe uma consulta. | — | -| `fp query create NAME` | Salva uma consulta. | `--sql `; `--description` | -| `fp query update NAME` | Atualiza ou renomeia uma consulta. | `--name`; `--sql`; `--description`; `--yes`, `-y` | -| `fp query delete NAME` | Exclui uma consulta salva. | `--yes`, `-y` | -| `fp query run [NAME]` | Executa uma consulta salva ou SQL ad-hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | Lista tabelas consultáveis ou inspeciona uma tabela. | — | +| `fp query list` | Listar consultas salvas. | `--show-id`; `--fields ` | +| `fp query show NAME` | Exibir uma consulta. | — | +| `fp query create NAME` | Salvar uma consulta. | `--sql `; `--description` | +| `fp query update NAME` | Atualizar ou renomear uma consulta. | `--name`; `--sql`; `--description`; `--yes`, `-y` | +| `fp query delete NAME` | Excluir uma consulta salva. | `--yes`, `-y` | +| `fp query run [NAME]` | Executar uma consulta salva ou SQL ad-hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query schema [TABLE]` | Listar tabelas consultáveis ou inspecionar uma tabela. | — | ### Usuários | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp users list` | Lista os membros da organização. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | Exibe um membro e suas concessões. | — | -| `fp users create EMAIL` | Adiciona um membro. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | Altera as concessões de um membro. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp users disable EMAIL` | Desabilita o login. | `--yes`, `-y` | -| `fp users enable EMAIL` | Reabilita o login. | `--yes`, `-y` | +| `fp users list` | Listar membros da organização. | `--active-only`; `--show-id` | +| `fp users show EMAIL` | Exibir um membro e suas concessões. | — | +| `fp users create EMAIL` | Adicionar um membro. | `--permission-set`; `--add`; `--remove` | +| `fp users update EMAIL` | Alterar as concessões de um membro. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users disable EMAIL` | Desabilitar o login. | `--yes`, `-y` | +| `fp users enable EMAIL` | Reabilitar o login. | `--yes`, `-y` | ### Configurações | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp settings list` | Lista as configurações da organização e seus valores atuais. | — | -| `fp settings schema` | Exibe os valores aceitos e suas descrições. | — | -| `fp settings set KEY` | Altera uma configuração existente. | exatamente uma de `--value`, `--json-value`, `--file`; `--yes`, `-y` opcional | +| `fp settings list` | Listar configurações da organização e seus valores atuais. | — | +| `fp settings schema` | Exibir valores aceitos e descrições. | — | +| `fp settings set KEY` | Alterar uma configuração existente. | exatamente um de `--value`, `--json-value`, `--file`; opcional `--yes`, `-y` | ### Alertas | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp alerts list` | Lista as regras de alerta. | `--show-id` | -| `fp alerts show NAME` | Exibe um alerta. | — | -| `fp alerts create NAME` | Cria um alerta. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | Atualiza ou renomeia um alerta. | opções de criação mais `--name`; `--yes`, `-y` | -| `fp alerts delete NAME` | Exclui um alerta. | `--yes`, `-y` | -| `fp alerts test NAME` | Envia uma notificação de teste. | `--channels`; `--yes`, `-y` | +| `fp alerts list` | Listar regras de alerta. | `--show-id` | +| `fp alerts show NAME` | Exibir um alerta. | — | +| `fp alerts create NAME` | Criar um alerta. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | +| `fp alerts update NAME` | Atualizar ou renomear um alerta. | opções de criação mais `--name`; `--yes`, `-y` | +| `fp alerts delete NAME` | Excluir um alerta. | `--yes`, `-y` | +| `fp alerts test NAME` | Enviar uma notificação de teste. | `--channels`; `--yes`, `-y` | -As severidades de alerta são `info`, `warning` e `critical`. Os tipos de trigger são `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` e `per_event`. Os intervalos de avaliação devem estar entre 30 e 86.400 segundos. +As severidades de alerta são `info`, `warning` e `critical`. Os tipos de gatilho são `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` e `per_event`. Os intervalos de avaliação devem estar entre 30 e 86.400 segundos. ### Auditorias | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp audits list` | Lista as auditorias. | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | Exibe uma definição de auditoria e seu estado. | — | -| `fp audits create NAME` | Cria uma auditoria e imediatamente enfileira sua primeira execução. | Veja [opções de criação](#audit-create-options). | -| `fp audits edit NAME` | Substitui as configurações da auditoria mantendo os valores não especificados. | opções de definição de criação; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | Exclui uma auditoria, seus findings e o histórico de execuções. | `--yes`, `-y` | -| `fp audits run NAME` | Enfileira uma execução manual. | — | -| `fp audits runs NAME` | Lista o histórico de execuções. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | Exibe o briefing e o estado de busca das URLs de referência. | — | -| `fp audits context-set NAME` | Altera o briefing ou as URLs de referência. | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | Rebusca as URLs de referência. | — | -| `fp audits findings` | Lista os findings. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | Exibe um finding e suas evidências. | — | -| `fp audits ack FINDING_ID` | Confirma o recebimento de um finding. | `--reason` | -| `fp audits mute FINDING_ID` | Suprime um padrão recorrente. | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | Marca um padrão como não acionável e o suprime. | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | Marca um finding como corrigido sem supressão futura. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | Retorna um finding à fila ativa e remove a supressão. | — | -| `fp audits assign FINDING_ID` | Define o responsável pelo finding. | `--to ` obrigatório | +| `fp audits list` | Listar auditorias. | `--enabled-only`; `--show-id` | +| `fp audits show NAME` | Exibir uma definição de auditoria e seu estado. | — | +| `fp audits create NAME` | Criar uma auditoria e enfileirar imediatamente sua primeira execução. | Veja [opções de criação](#audit-create-options). | +| `fp audits edit NAME` | Substituir configurações da auditoria mantendo os valores não especificados. | opções de definição de criação; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | Excluir uma auditoria, suas descobertas e o histórico de execuções. | `--yes`, `-y` | +| `fp audits run NAME` | Enfileirar uma execução manual. | — | +| `fp audits runs NAME` | Listar histórico de execuções. | `--limit`, `-n`; `--show-id` | +| `fp audits context-show NAME` | Exibir o resumo e o estado de busca das URLs de referência. | — | +| `fp audits context-set NAME` | Alterar o resumo ou as URLs de referência. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-refresh NAME` | Rebuscar as URLs de referência. | — | +| `fp audits findings` | Listar descobertas. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | +| `fp audits finding FINDING_ID` | Exibir uma descoberta e suas evidências. | — | +| `fp audits ack FINDING_ID` | Reconhecer uma descoberta. | `--reason` | +| `fp audits mute FINDING_ID` | Suprimir um padrão recorrente. | `--reason`; `--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | Marcar um padrão como não acionável e suprimi-lo. | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | Marcar uma descoberta como corrigida sem supressão futura. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | Devolver uma descoberta à fila ativa e limpar a supressão. | — | +| `fp audits assign FINDING_ID` | Definir o responsável pela descoberta. | `--to ` obrigatório | #### Opções de criação de auditoria @@ -261,75 +264,75 @@ fp audits create checkout-reliability \ | Opção | Descrição | | --- | --- | -| `--file ` | Baseia a definição em JSON, ou use `-` para stdin. Flags explícitas substituem os valores do arquivo. | -| `--description ` | Descreve a questão de falha ou finalidade. | -| `--enabled` / `--disabled` | Inicia o agendamento ativo ou inativo. Padrão: habilitado. | +| `--file ` | Basear a definição em JSON ou usar `-` para stdin. Flags explícitas substituem os valores do arquivo. | +| `--description ` | Descrever a questão de falha ou o propósito. | +| `--enabled` / `--disabled` | Iniciar o agendamento ativado ou desativado. Padrão: habilitado. | | `--schedule-interval-secs ` | `3600`–`604800`. Padrão: `86400`. | -| `--schedule-anchor ` | Fase UTC fixa no formato ISO 8601. Padrão: próximo 09:00 UTC. | -| `--window-mode since_last\|fixed` | Continua após a última janela totalmente analisada ou inspeciona repetidamente uma janela deslizante. Padrão: `since_last`. | +| `--schedule-anchor ` | Fase UTC fixa em formato ISO 8601. Padrão: próxima 09:00 UTC. | +| `--window-mode since_last\|fixed` | Continuar após a última janela totalmente analisada ou inspecionar repetidamente uma janela contínua. Padrão: `since_last`. | | `--lookback-window-secs ` | `3600`–`7776000`. Padrão: `604800`. | -| `--scope ''` | Filtra por `environments`, `agent_ids` ou outros campos de escopo suportados. | -| `--ignore-error-type ` | Exclui tipos de erros; repita ou separe por vírgula. | -| `--llm` / `--no-llm` | Habilita ou desabilita a análise agêntica. Padrão: habilitado. | -| `--top-k ` | Retém `1`–`500` findings. Padrão: `50`. | -| `--sensitivity low\|medium\|high` | Define a sensibilidade de relatório. Padrão: `medium`. | +| `--scope ''` | Filtrar por `environments`, `agent_ids` ou outros campos de escopo suportados. | +| `--ignore-error-type ` | Excluir tipos de erro; repita ou separe por vírgula. | +| `--llm` / `--no-llm` | Habilitar ou desabilitar a análise agêntica. Padrão: habilitado. | +| `--top-k ` | Reter `1`–`500` descobertas. Padrão: `50`. | +| `--sensitivity low\|medium\|high` | Definir a sensibilidade de relatórios. Padrão: `medium`. | | `--channels ''` | Array de canais de notificação. | -| `--text ` | Briefing inline, máximo de 8.192 caracteres. | -| `--text-file ` | Lê o briefing a partir de um arquivo; mutuamente exclusivo com `--text`. | -| `--url ` | Adiciona uma referência HTTPS pública; repita até cinco vezes. | +| `--text ` | Resumo inline, máximo de 8.192 caracteres. | +| `--text-file ` | Ler o resumo de um arquivo; mutuamente exclusivo com `--text`. | +| `--url ` | Adicionar uma referência HTTPS pública; repita até cinco vezes. | Inclua o contexto durante a criação quando a primeira execução precisar dele. A criação confirma a definição e o contexto juntos antes que a execução enfileirada comece. - `fp audits run` é assíncrono. Monitore `fp audits runs NAME` até que a execução mais recente seja concluída com sucesso ou falhe antes de ler seus findings. + `fp audits run` é assíncrono. Monitore `fp audits runs NAME` até que a execução mais recente seja bem-sucedida ou falhe antes de ler suas descobertas. -### Issues +### Problemas | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp issues list` | Lista os issues. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | Conta issues abertos ou nos estados selecionados. | `--state` | -| `fp issues show INCIDENT_ID` | Exibe detalhes do issue, comentários, assinantes e atividade. | — | -| `fp issues open` | Abre um issue manual ou vinculado a um alerta. | `--summary` obrigatório; `--title`, `--alert-id`, `--severity` opcionais | -| `fp issues ack INCIDENT_ID` | Confirma o recebimento de um issue. | — | -| `fp issues assign INCIDENT_ID` | Substitui os responsáveis; omita a opção para removê-los. | `--assignee` repetível | -| `fp issues resolve INCIDENT_ID` | Resolve um issue. | `--yes`, `-y` | -| `fp issues comment-list INCIDENT_ID` | Lista comentários. | — | -| `fp issues comment-add INCIDENT_ID` | Adiciona um comentário. | exatamente uma de `--body`, `--file` | -| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Exclui um comentário. | `--yes`, `-y` | -| `fp issues subscribers INCIDENT_ID` | Lista assinantes. | — | -| `fp issues subscribe INCIDENT_ID` | Assina você mesmo ou outro operador. | `--email` | -| `fp issues unsubscribe INCIDENT_ID` | Remove uma assinatura. | `--email` | - -Os estados válidos de issue são `firing`, `acknowledged` e `resolved`. As severidades de issues avulsos são `info`, `warning` e `critical`. - -### Assistente na nuvem +| `fp issues list` | Listar problemas. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | Contar problemas abertos ou estados selecionados. | `--state` | +| `fp issues show INCIDENT_ID` | Exibir detalhes, comentários, assinantes e atividade de um problema. | — | +| `fp issues open` | Abrir um problema manual ou vinculado a alerta. | `--summary` obrigatório; `--title`, `--alert-id`, `--severity` opcionais | +| `fp issues ack INCIDENT_ID` | Reconhecer um problema. | — | +| `fp issues assign INCIDENT_ID` | Substituir responsáveis; omita a opção para limpá-los. | `--assignee` repetível | +| `fp issues resolve INCIDENT_ID` | Resolver um problema. | `--yes`, `-y` | +| `fp issues comment-list INCIDENT_ID` | Listar comentários. | — | +| `fp issues comment-add INCIDENT_ID` | Adicionar um comentário. | exatamente um de `--body`, `--file` | +| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Excluir um comentário. | `--yes`, `-y` | +| `fp issues subscribers INCIDENT_ID` | Listar assinantes. | — | +| `fp issues subscribe INCIDENT_ID` | Inscrever você mesmo ou outro operador. | `--email` | +| `fp issues unsubscribe INCIDENT_ID` | Remover uma assinatura. | `--email` | + +Os estados válidos de problema são `firing`, `acknowledged` e `resolved`. As severidades de problemas avulsos são `info`, `warning` e `critical`. + +### Assistente de nuvem | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp agent health` | Verifica a disponibilidade e configuração do assistente. | — | -| `fp agent models` | Lista os modelos de assistente disponíveis. | — | -| `fp agent chats` | Lista os chats salvos. | — | -| `fp agent ask [MESSAGE]` | Inicia ou continua um chat; lê stdin quando a mensagem é omitida. | `--chat`; `--model`; `--page-context` | -| `fp agent show CHAT_ID` | Exibe uma conversa salva. | — | -| `fp agent rename CHAT_ID` | Renomeia uma conversa. | `--title` obrigatório | -| `fp agent delete CHAT_ID` | Exclui uma conversa. | `--yes`, `-y` | +| `fp agent health` | Verificar disponibilidade e configuração do assistente. | — | +| `fp agent models` | Listar modelos disponíveis do assistente. | — | +| `fp agent chats` | Listar conversas salvas. | — | +| `fp agent ask [MESSAGE]` | Iniciar ou continuar uma conversa; lê stdin quando a mensagem é omitida. | `--chat`; `--model`; `--page-context` | +| `fp agent show CHAT_ID` | Exibir uma conversa salva. | — | +| `fp agent rename CHAT_ID` | Renomear uma conversa. | `--title` obrigatório | +| `fp agent delete CHAT_ID` | Excluir uma conversa. | `--yes`, `-y` | ### Políticas -Versões de políticas gerenciadas pela nuvem. **Somente sessão** — todos os comandos aqui encerram com código `2` sob uma chave de API, antes de qualquer requisição, pois são rotas de escrita exclusivas de root deliberadamente ausentes de `/v1`. +Versões de políticas gerenciadas pela nuvem. **Somente sessão** — cada comando aqui encerra com `2` sob uma chave de API, antes de qualquer requisição, pois são rotas de escrita exclusivas de root deliberadamente ausentes de `/v1`. | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp policies list` | Lista versões de políticas. | `--json` | -| `fp policies show POLICY_ID` | Exibe uma política com seu código-fonte. | — | -| `fp policies publish NAME PATH` | Cria uma versão a partir de um `.mjs` local. | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | Adiciona a política de volta a cada implantação da qual foi removida, criando uma nova geração em cada uma. | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | Remove a política de cada implantação que a contém, criando uma nova geração em cada uma. | `--yes`, `-y` | -| `fp policies delete POLICY_ID` | Exclui uma versão de política. | `--yes`, `-y` | -| `fp policies test PATH` | Executa uma política localmente contra um contexto sintético. Aplica o filtro `match` de cada política, portanto uma que não cubra o evento/ferramenta fornecido é reportada como `skipped` em vez de executada. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | Elabora uma política com o assistente. Requer `policies:write`. | — | +| `fp policies list` | Listar versões de políticas. | `--json` | +| `fp policies show POLICY_ID` | Exibir uma política com seu código-fonte. | — | +| `fp policies publish NAME PATH` | Criar uma versão a partir de um `.mjs` local. | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | Adicioná-la de volta a cada implantação da qual foi removida, criando uma nova geração em cada uma. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | Removê-la de cada implantação que a carrega, criando uma nova geração em cada uma. | `--yes`, `-y` | +| `fp policies delete POLICY_ID` | Excluir uma versão de política. | `--yes`, `-y` | +| `fp policies test PATH` | Executar uma política localmente contra um contexto sintético. Aplica o filtro `match` de cada política, portanto uma que não cubra o evento/ferramenta fornecido é reportada como `skipped` em vez de executada. | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | Rascunhar uma política com o assistente. Requer `policies:write`. | — | ### Frota @@ -337,40 +340,40 @@ Quais máquinas executam quais políticas. **Somente sessão**, pelo mesmo motiv | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp fleet list` | Lista as máquinas registradas e sua geração de implantação. | — | +| `fp fleet list` | Listar máquinas registradas e sua geração de implantação. | — | | `fp fleet show MACHINE_ID` | O conjunto de políticas que uma máquina executa atualmente. | — | -| `fp fleet deploy MACHINE_ID` | **Substitui todo o conjunto de políticas da máquina.** Exibe o plano e solicita confirmação apenas em terminal interativo sem `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | Compara uma máquina com outra implantação. | — | -| `fp fleet history MACHINE_ID` | Implantações anteriores de uma máquina. | — | -| `fp fleet rollback MACHINE_ID` | Restaura uma implantação anterior. | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | Atribui um nome legível a uma máquina. | `--name` obrigatório | +| `fp fleet deploy MACHINE_ID` | **Substitui todo o conjunto de políticas da máquina.** Exibe o plano e pergunta apenas em terminal interativo sem `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | Comparar uma máquina com outra implantação. | — | +| `fp fleet history MACHINE_ID` | Implantações passadas de uma máquina. | — | +| `fp fleet rollback MACHINE_ID GENERATION` | Reinstaurar o conjunto de políticas de uma geração anterior, como uma nova geração. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | Dar um nome legível a uma máquina. | `--name` obrigatório | ### Guardrails -O que o enforcement realmente fez. **Somente sessão**, pelo mesmo motivo acima. +O que a aplicação realmente fez. **Somente sessão**, pelo mesmo motivo acima. | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp guardrails summary` | Cobertura, totais de bloqueados/avaliados, um sparkline de negações e a tabela por política. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | Decisões agrupadas ao longo da janela, somadas em todas as fontes de política. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | Cobertura, totais bloqueados/avaliados, um sparkline de negações e a tabela por política. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Decisões agrupadas ao longo da janela, somadas por todas as fontes de política. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | ## Flags globais | Flag | Descrição | | --- | --- | -| `--json` | Emite JSON legível por máquina. | -| `--base-url ` | Usa um dashboard auto-hospedado ou de desenvolvimento. | -| `--org ` | Seleciona uma organização para esta invocação. | -| `--token ` | Substitui o token de sessão de usuário salvo. | -| `--api-key ` | Autentica automação com uma chave de API; nunca é salva. | +| `--json` | Emitir JSON legível por máquina. | +| `--base-url ` | Usar um painel auto-hospedado ou de desenvolvimento. | +| `--org ` | Selecionar uma organização para esta invocação. | +| `--token ` | Substituir o token de sessão de usuário salvo. | +| `--api-key ` | Autenticar automação com uma chave de API; nunca salva. | | `--timeout ` | Timeout HTTP; deve ser positivo. Padrão: `30`. | -| `--quiet`, `-q` | Suprime a saída de status no stderr. | -| `--no-color` | Desabilita a saída colorida. | -| `--insecure` / `--secure` | Desabilita ou restaura a verificação de certificado TLS. | -| `--version` | Imprime a versão e encerra. | -| `--help`, `-h` | Exibe a ajuda. | +| `--quiet`, `-q` | Suprimir saída de status no stderr. | +| `--no-color` | Desabilitar saída colorida. | +| `--insecure` / `--secure` | Desabilitar ou restaurar a verificação de certificado TLS. | +| `--version` | Imprimir a versão e sair. | +| `--help`, `-h` | Exibir ajuda. | -`--api-key` é destinado à automação. Login, troca de organização e comandos do assistente requerem uma sessão de usuário. +`--api-key` é destinado a automação. Login, troca de organização e comandos do assistente requerem uma sessão de usuário. ## Variáveis de ambiente @@ -382,18 +385,18 @@ O que o enforcement realmente fez. **Somente sessão**, pelo mesmo motivo acima. | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | Reposiciona o diretório de configuração da CLI (padrão `~/.failproofai/fpcli`). | -| `FP_ANALYTICS_DISABLED` ou `DO_NOT_TRACK` | Desabilita analytics anônimos da CLI. | -| `NO_COLOR` | Desabilita a saída colorida. | +| `FP_HOME` | Realocar o diretório de configuração da CLI (padrão `~/.failproofai/fpcli`). | +| `FP_ANALYTICS_DISABLED` ou `DO_NOT_TRACK` | Desabilitar a telemetria anônima da CLI. | +| `NO_COLOR` | Desabilitar saída colorida. | Flags explícitas substituem variáveis de ambiente, que substituem a configuração salva. No modo de chave de API, selecione o tenant explicitamente com `--org` ou `FP_ORG`. - Os equivalentes `AGENTEYE_*` dessas variáveis **não são lidos pelo `fp`** e nunca foram — a CLI declara `FP_*` (`fp_cli/app.py`), e uma variável desconhecida não é um erro. Definir `AGENTEYE_DASHBOARD_URL` não redireciona a CLI; ela é ignorada e o comando executa silenciosamente contra o dashboard salvo. + As variações `AGENTEYE_*` dessas variáveis **não são lidas por `fp`** e nunca foram — a CLI declara `FP_*` (`fp_cli/app.py`), e uma variável desconhecida não é um erro. Definir `AGENTEYE_DASHBOARD_URL` não redireciona a CLI; ela é ignorada e o comando executa silenciosamente contra o painel salvo. `AGENTEYE_HOME` e `AGENTEYE_ENVIRONMENT` ainda existem, mas pertencem ao **coletor e ao SDK de telemetria**, não a esta CLI. - Comandos que excluem, revogam, suprimem, resolvem ou substituem configurações solicitam confirmação por padrão. Use `--yes` somente após verificar a organização ativa e o alvo. + Comandos que excluem, revogam, suprimem, resolvem ou substituem configurações solicitam confirmação por padrão. Use `--yes` somente após verificar a organização ativa e o destino. \ No newline at end of file diff --git a/docs/pt-br/reference/custom-agents.mdx b/docs/pt-br/reference/custom-agents.mdx index 385cc65e..d044b8d4 100644 --- a/docs/pt-br/reference/custom-agents.mdx +++ b/docs/pt-br/reference/custom-agents.mdx @@ -1,21 +1,21 @@ --- -title: "Agentes customizados" +title: "Agentes personalizados" description: "Configuração, catálogo de eventos, regras de correlação e entrega para o failproofai-sdk." icon: "python" --- -O que cada configuração, método e campo faz. Se você está instrumentando pela primeira vez, comece pelo guia — esta página é para consulta. +O que cada configuração, método e campo faz. Se você está instrumentando pela primeira vez, comece pelo guia — esta página serve como referência. - - Instalação, instrumentação, métodos de evento, um exemplo completo e problemas comuns. + + Instalação, instrumentação, métodos de evento, exemplo prático e problemas comuns. - LangChain, CrewAI, LlamaIndex e Pydantic AI se instrumentam com uma única chamada. + LangChain, CrewAI, LlamaIndex e Pydantic AI se instrumentam automaticamente com uma única chamada. -Python 3.10 ou superior. Sem dependências de runtime. +Python 3.10 ou superior. Sem dependências em tempo de execução. ## Instalação @@ -23,24 +23,30 @@ Python 3.10 ou superior. Sem dependências de runtime. pip install failproofai-sdk ``` -O pacote é instalado como `failproofai-sdk` e importado no Python como `failproofai_sdk`. Extras de framework como `failproofai-sdk[langgraph]` instalam o próprio framework; os adaptadores sempre estão incluídos no pacote base. +O pacote é instalado como `failproofai-sdk` e importado no Python como `failproofai_sdk`. Extras de framework como `failproofai-sdk[langgraph]` instalam o próprio framework; os adaptadores sempre vêm incluídos no pacote base. ## Conectar o daemon do Failproof 1. Acesse **Admin → Keys** e crie uma chave com `events:add`. - 2. [Conecte o daemon do Failproof à Cloud](/pt-br/start/setup#connect-a-machine-to-cloud) na máquina do agente. + 2. [Conecte o daemon do Failproof à nuvem](/pt-br/start/setup#connect-a-machine-to-cloud) na máquina do agente. 3. Execute uma sessão instrumentada e encontre o ID exato em **Observe → Events**. 4. Acesse **Observe → Sessions**, selecione o mesmo ambiente e abra o trace reconstruído. - ![Uma sessão de agente Python customizado reconstruída como grafo de execução e trace de eventos ordenado.](/images/dashboard/session-detail.png) + ![Uma sessão de agente Python personalizado reconstruída como grafo de execução e trace de eventos ordenados.](/images/dashboard/session-detail.png) + Leia a chave `events:add` para o shell. `read -s` captura a entrada em um prompt sem eco, de forma que ela nunca aparece em um comando nem no histórico do shell: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Em seguida, configure a máquina e verifique se a conexão foi estabelecida: + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -62,28 +68,28 @@ failproofai_sdk.configure( | --- | --- | | `environment` | O rótulo em cada evento — `production`, `staging`, `prod-eu`. Padrão: `dev`. | | `flush_interval` | Com que frequência a thread em segundo plano grava no disco, em segundos. Padrão: `0.5`. | -| `base_dir` | Onde gravar. Padrão: o spool do daemon, que é o desejado a menos que você saiba o contrário. | +| `base_dir` | Onde gravar. Padrão: o spool do daemon, que é o valor correto na maioria dos casos. | -Configurar via variável de ambiente: +Configuração via variável de ambiente: | Variável | O que faz | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | Define `environment` sem alterar o código, para quando o rótulo pertence ao deployment e não à aplicação. Um argumento de `configure()` tem precedência sobre ela. | -| `FAILPROOFAI_HOME` | Move a raiz do Failproof AI que contém o spool. | -| `FAILPROOFAI_SDK_STRICT` | `1` faz com que erros de instrumentação sejam lançados em vez de apenas registrados. | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` faz com que um problema de compatibilidade com framework seja lançado em vez de apenas avisar e continuar. | +| `AGENTEYE_ENVIRONMENT` | Define `environment` sem alteração de código, para quando o rótulo pertence ao deployment e não à aplicação. Um argumento de `configure()` tem precedência sobre ela. | +| `FAILPROOFAI_HOME` | Move o diretório raiz do Failproof AI que armazena o spool. | +| `FAILPROOFAI_SDK_STRICT` | `1` faz erros de instrumentação lançar exceção em vez de apenas registrar no log. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` faz um problema de compatibilidade com o framework lançar exceção em vez de apenas exibir um aviso e continuar. | - **Sem vírgulas em `environment`.** O ingest divide esse campo por vírgulas para construir seus filtros e ignora qualquer evento cujo rótulo contenha uma — fazendo com que toda uma execução desapareça silenciosamente. Escreva `prod-eu`, não `prod,eu`. + **Sem vírgulas em `environment`.** O sistema de ingestão divide esse campo por vírgulas para construir seus filtros e ignora qualquer evento cujo rótulo contenha uma — fazendo uma execução inteira desaparecer silenciosamente. Use `prod-eu`, não `prod,eu`. - `configure(environment="prod,eu")` lança um erro imediatamente. `AGENTEYE_ENVIRONMENT` não pode lançar — não há quem o chame — então emite um aviso uma vez e usa `dev` como fallback. + `configure(environment="prod,eu")` lança uma exceção para que você perceba imediatamente. `AGENTEYE_ENVIRONMENT` não pode lançar exceção — nada está te chamando — então ela emite um aviso uma vez e usa `dev` como fallback. -Os eventos são enfileirados em memória e gravados em segundo plano a cada `flush_interval` segundos, com um flush final ao encerrar o interpretador. Um processo encerrado abruptamente perde tudo que ainda não havia sido gravado. +Os eventos são enfileirados na memória e gravados em segundo plano a cada `flush_interval` segundos, com um flush final na saída do interpretador. Um processo encerrado abruptamente perde tudo o que ainda não foi gravado. ## Identidade -Todo evento pertence a uma sessão e a um agente. **Os escopos preenchem ambos automaticamente**, então raramente você precisa passá-los: +Todo evento pertence a uma sessão e a um agente. **Os escopos preenchem ambos automaticamente**, então raramente é necessário passá-los: ```python with failproofai_sdk.session(): @@ -91,15 +97,15 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Passar `session_id` ou `agent_id` explicitamente ainda funciona e tem precedência. Se nem um estiver vinculado nem passado, a chamada lança `TypeError` em vez de emitir um evento que a Cloud descartaria silenciosamente. +Passar `session_id` ou `agent_id` explicitamente ainda funciona e tem precedência. Se nenhum estiver vinculado nem passado, a chamada lança `TypeError` em vez de emitir um evento que a nuvem descartaria silenciosamente. - A identidade usa variáveis de contexto. Ela segue tasks `asyncio` automaticamente, mas **não** novas threads — envolva um worker com `failproofai_sdk.propagate()` ou seus eventos serão emitidos sem vínculo. + A identidade é transportada por variáveis de contexto. Ela segue tarefas `asyncio` automaticamente, mas **não** novas threads — encapsule um worker com `failproofai_sdk.propagate()` ou os eventos dele ficarão sem associação. ## Catálogo de eventos -Quinze métodos. A maioria vem em **pares** — você chama o abridor e depois o fechador, e o SDK mede o intervalo. +Quinze métodos. A maioria vem em **pares** — você chama o abridor e depois o fechador, e o SDK mede o intervalo entre eles. | | Abre | Fecha | | --- | --- | --- | @@ -112,9 +118,9 @@ Quinze métodos. A maioria vem em **pares** — você chama o abridor e depois o Três são independentes: `error`, `human_pause`, `human_interrupt`. - + -Todo método também aceita `session_id` e `agent_id`, que os escopos preenchem automaticamente. Qualquer campo deixado como `None` é descartado em vez de enviado como `null` no JSON, e todo método retorna `None`. +Cada método também aceita `session_id` e `agent_id`, que os escopos preenchem automaticamente. Qualquer campo deixado como `None` é descartado em vez de enviado como `null` no JSON, e todos os métodos retornam `None`. | Método | Obrigatório | Opcional | | --- | --- | --- | @@ -137,12 +143,12 @@ Todo método também aceita `session_id` e `agent_id`, que os escopos preenchem - Para marcar uma execução como falha, `outcome` deve ser um dos valores: `failed`, `error`, `timeout` ou `rejected`. Qualquer outro valor — incluindo o quase-correto `"failure"` — é tratado como sucesso. + Para marcar uma execução como falha, `outcome` deve ser um dos valores: `failed`, `error`, `timeout` ou `rejected`. Qualquer outro valor — incluindo o quase-correto `"failure"` — é contado como sucesso. ## Pareamento e duração -**Uma regra: passe o mesmo id ao evento de fechamento que foi usado no evento de abertura.** É isso que os emparelha e permite ao SDK medir o intervalo. +**Uma regra: dê ao evento de fechamento o mesmo id do seu abridor.** É isso que os emparelha e permite ao SDK medir o intervalo. | Par | Correspondência por | | --- | --- | @@ -152,37 +158,37 @@ Todo método também aceita `session_id` e `agent_id`, que os escopos preenchem | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**Não passe `duration_ms` manualmente.** O SDK o mede, e passá-lo lança `ValueError`. +**Não passe `duration_ms` manualmente.** O SDK o mede automaticamente, e passá-lo lança `ValueError`. -A única exceção é `model_response`, onde somente você conhece a latência real do provedor. Passe um número inteiro de milissegundos — um float lança erro, pois a coluna é um inteiro de 32 bits e ficaria vazia caso contrário. +A única exceção é `model_response`, onde somente você conhece a latência real do provedor. Passe um número inteiro de milissegundos — um float lança exceção, pois a coluna é um inteiro de 32 bits e ficaria vazia caso contrário. -- **Os ids precisam ser únicos apenas por tipo e por sessão.** Uma chamada de ferramenta e um hook podem compartilhar o mesmo id; duas sessões rodando ao mesmo tempo podem reutilizar os mesmos ids sem conflito. -- **Eles não têm escopo por agente.** Um par aberto em um agente e fechado em outro ainda é emparelhado corretamente — o que é o caso normal em código multi-agente. -- **`request_id` é opcional, mas recomendado.** Sem ele, os eventos de modelo são emparelhados na ordem de chegada, então duas chamadas concorrentes no mesmo agente podem ser emparelhadas incorretamente. -- **Um par dividido entre processos** ainda é emparelhado na Cloud, mas o SDK não consegue medir o tempo — nenhum dos processos viu ambas as metades. -- **No máximo 10.000 abridores aguardam um fechador ao mesmo tempo.** Além disso, o mais antigo é descartado, evitando que um vazamento cresça indefinidamente. +- **Os ids precisam ser únicos apenas por tipo e por sessão.** Uma chamada de ferramenta e um hook podem compartilhar o mesmo id; duas sessões em execução simultânea podem reutilizar os mesmos ids sem conflito. +- **Eles não são escopados por agente.** Um par aberto sob um agente e fechado sob outro ainda é emparelhado corretamente — o que é o caso normal em código multi-agente. +- **`request_id` é opcional, mas recomendado.** Sem ele, eventos de modelo são emparelhados na ordem de chegada, então duas chamadas concorrentes no mesmo agente podem ser emparelhadas incorretamente. +- **Um par dividido entre processos** ainda é emparelhado na nuvem, mas o SDK não consegue medir o tempo — nenhum dos processos viu as duas metades. +- **No máximo 10.000 abridores aguardam um fechador ao mesmo tempo.** Além disso, o mais antigo é descartado, então um vazamento não pode crescer indefinidamente. -## Campos próprios +## Seus próprios campos Qualquer palavra-chave extra que você passar é armazenada junto ao evento: ```python failproofai_sdk.event.tool_use( tool_name="search", tool_call_id="c1", - fw_tenant="acme", fw_region="eu-west-1", # seus próprios + fw_tenant="acme", fw_region="eu-west-1", # seus próprios campos ) ``` -Prefira tipos JSON se quiser consultá-los depois. Qualquer outro tipo — UUID, datetime, `Decimal`, set, bytes, objeto de modelo — é armazenado como string. +Prefira tipos JSON se quiser consultá-los posteriormente. Qualquer outro tipo — UUID, datetime, `Decimal`, set, bytes, objeto de modelo — é armazenado como string. - **Prefixe seus nomes de campo.** Os extras são aplicados por último, então um campo chamado `model`, `tool_name` ou `outcome` sobrescreve silenciosamente o valor real. Os adaptadores de framework usam `fw_`; faça o mesmo e não haverá conflitos. + **Use prefixo nos nomes dos seus campos.** Os extras são aplicados por último, então um campo chamado `model`, `tool_name` ou `outcome` sobrescreve silenciosamente o campo original. Os adaptadores de framework usam `fw_`; faça o mesmo e não haverá conflito. - É também por isso que um campo opcional com nome errado nunca gera erro — ele simplesmente se torna um novo campo customizado. Se um campo padrão estiver ausente na Cloud, verifique a ortografia primeiro. + É também por isso que um campo opcional com erro de ortografia nunca gera erro — ele simplesmente se torna um novo campo personalizado. Se um campo padrão estiver ausente na nuvem, verifique a ortografia primeiro. Estes cinco nomes são reservados e rejeitados diretamente: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. @@ -191,7 +197,7 @@ Estes cinco nomes são reservados e rejeitados diretamente: `timestamp`, `sessio - Em **Observe → Events**, verifique se `agent_start` existe primeiro e `agent_end` existe por último. Em seguida, abra **Observe → Sessions** e confirme se os eventos de modelo, ferramenta, humano, hook e erro aparecem na ordem esperada. Use o ID da sessão como chave principal de troubleshooting. + Em **Observe → Events**, verifique se `agent_start` existe primeiro e `agent_end` existe por último. Em seguida, abra **Observe → Sessions** e confirme que os eventos de modelo, ferramenta, humano, hook e erro aparecem na ordem esperada. Use o ID de sessão como chave principal de diagnóstico. ```bash @@ -203,14 +209,14 @@ Estes cinco nomes são reservados e rejeitados diretamente: `timestamp`, `sessio -Se a Cloud estiver vazia, inspecione `$FAILPROOFAI_HOME/custom-agents/events`, caso contrário `~/.failproofai/custom-agents/events`. Arquivos JSONL comprovam a emissão pelo SDK; um spool crescendo indica problema de configuração ou entrega do daemon, enquanto um spool vazio aponta para instrumentação ou tempo de vida do processo. +Se a nuvem estiver vazia, inspecione `$FAILPROOFAI_HOME/custom-agents/events`; caso contrário, `~/.failproofai/custom-agents/events`. Arquivos JSONL confirmam a emissão pelo SDK; um spool crescendo aponta para configuração do daemon ou entrega, enquanto um spool vazio aponta para instrumentação ou tempo de vida do processo. - Inspecione o spool somente quando o daemon estiver parado. Enquanto ele está em execução, ele coleta e exclui cada lote em milissegundos, então uma listagem de diretório disputa com o coletor e mostra muito menos eventos do que foram emitidos. + Inspecione o spool somente quando o daemon estiver parado. Enquanto ele executa, coleta e exclui cada lote em milissegundos, então uma listagem de diretório disputa com o coletor e exibe muito menos eventos do que foram emitidos. -## Prevenir falhas em um runtime customizado +## Prevenir falhas em um runtime personalizado -Use os achados de auditoria e os traces vinculados para definir a ação insegura, as evidências necessárias e a resposta pretendida. Uma integração de enforcement customizada deve expor a ação antes da execução, passar sua entrada estruturada ao motor de políticas e aplicar a decisão resultante de allow, instruct ou deny. +Use descobertas de auditoria e traces vinculados para definir a ação insegura, as evidências necessárias e a resposta pretendida. Uma integração de enforcement personalizada deve expor a ação antes da execução, passar sua entrada estruturada ao motor de políticas e aplicar a decisão resultante de allow, instruct ou deny. -[Entre em contato com o Failproof AI](mailto:support@befailproof.ai) e iremos ajudá-lo a mapear os limites de modelo, ferramenta e ciclo de vida do seu runtime para hooks de política e, em seguida, validar a integração com você. \ No newline at end of file +[Entre em contato com o Failproof AI](mailto:support@befailproof.ai) e iremos ajudar a mapear os limites de modelo, ferramenta e ciclo de vida do seu runtime para hooks de política, e então validar a integração junto com você. \ No newline at end of file diff --git a/docs/pt-br/reference/evaluator-sdk.mdx b/docs/pt-br/reference/evaluator-sdk.mdx index c7063d7c..31c2b086 100644 --- a/docs/pt-br/reference/evaluator-sdk.mdx +++ b/docs/pt-br/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "Construa um serviço que avalia sessões do Failproof AI de forma síncrona ou assíncrona." +description: "Execute seu próprio worker de avaliação, para juízes LLM e tudo mais que o Python hospedado não consegue fazer." icon: "gauge" --- -Um avaliador recebe uma sessão de agente concluída e retorna os sinais de qualidade que importam para você: pontuações numéricas, uma explicação para cada pontuação e um resumo opcional. O Failproof AI armazena esses resultados ao lado do trace e os exibe em gráficos por agentes e ambientes. +O Evaluator SDK executa avaliações na sua própria infraestrutura. Seu worker registra suas avaliações no Failproof AI, reivindica sessões conforme elas são concluídas, as pontua e envia os resultados — tudo via HTTPS de saída: nada se conecta a ele de fora. Use-o para o que o [Python hospedado](/pt-br/evaluations/write) não consegue fazer — juízes LLM, chamadas de modelo, pacotes, segredos e acesso à rede. Os resultados aparecem ao lado dos hospedados na [página de avaliações](/pt-br/sessions/evaluations), marcados como **customer**. -## Configurar um avaliador +Ele está incluído no `failproofai-sdk`, sob `failproofai_sdk.evaluator`; importar o SDK de rastreamento não o carrega. - - - Instale o SDK e o servidor necessário para executá-lo. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - Crie o arquivo `evaluator.py`. Este exemplo verifica se uma sessão contém chamadas de ferramentas com falha. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - Defina um token compartilhado, inicie o avaliador e confirme que o endpoint de saúde responde. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - Em outro terminal: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## Conectar o avaliador ao Failproof AI +```bash +pip install failproofai-sdk +``` -1. Faça o deploy do avaliador em uma URL HTTPS acessível pelo Failproof AI Cloud. -2. Configure `EVALUATOR_ENDPOINT` com essa URL e defina `EVALUATOR_TOKEN` com o mesmo token usado pelo avaliador. Para o Cloud gerenciado, entre em contato com [support@befailproof.ai](mailto:support@befailproof.ai) para configurar a conexão. -3. Execute uma avaliação e confirme que as pontuações aparecem no Failproof AI. +## Escrever avaliações - - - Abra uma sessão concluída em **Observe → Sessions** e selecione **Run evaluation** se ela não foi avaliada automaticamente. Revise o status, as pontuações, o raciocínio e o resumo no painel **Evaluation** da sessão. +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - Use **Observe → Evaluations** para comparar pontuações entre agentes ou ambientes. Use **Observe → Metrics** para medições de latência, custo, tokens e outros valores numéricos. - Comece com uma sessão para confirmar que o avaliador retornou as chaves de pontuação esperadas e um raciocínio útil para aquela execução específica. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![Uma visualização de detalhe de sessão mostrando pontuações de avaliação e raciocínio ao lado do trace.](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` registra uma avaliação. A chave é o nome pelo qual seus resultados são exibidos; altere a versão sempre que a lógica mudar, e cada resultado mantém a versão que o gerou. Um único worker comporta até 100 avaliações. +- `result_kind` é `"score"` por padrão. Para uma avaliação do tipo `"metric"` ou `"assertion"`, nomeie uma entrada de `metrics` ou `assertions` com a mesma chave: essa entrada será o resultado. +- `when` decide se uma sessão é aplicável. Retorne `ConditionResult(False, "")` para ignorá-la; o motivo é registrado. +- Uma avaliação pode ser uma função simples ou `async`, e `timeout_seconds` limita seu tempo de execução. +- As chaves de payload — `tool_name`, `response` e `content` acima — são as que seus agentes enviam, portanto leia-as a partir de uma sessão real. - Quando os resultados individuais parecerem corretos, use o dashboard de avaliação para comparar essas pontuações ao longo do tempo e entre agentes ou ambientes. +## Executar o worker - ![Um dashboard de qualidade com gráficos de pontuações do avaliador ao longo do tempo.](/images/dashboard/dashboard-quality.png) +Coloque uma chave com a permissão `evaluations:run`, criada em **Administration → Keys**, na variável `FAILPROOFAI_EVALUATOR_TOKEN` — defina-a a partir do seu cofre de segredos em vez de digitá-la diretamente em um comando — e inicie o worker: - Um gráfico saudável deve usar nomes de pontuação estáveis; alterar uma chave cria uma série separada. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -Para uma instância Cloud auto-hospedada, a avaliação automática fica desabilitada até que `EVALUATOR_ENDPOINT` seja definido no processo do servidor. Reinicie o servidor após alterar variáveis de ambiente do avaliador. +Sem o bloco `__main__`, `python -m failproofai_sdk.evaluator evaluator:app` faz o mesmo. -O serviço expõe `GET /health`, `GET /config`, `POST /evaluate` e, opcionalmente, `GET /evaluate/{job_id}`. Retorne `JobPending` para trabalho assíncrono e registre `@app.job_lookup` para que o Failproof AI possa fazer polling. +| Variável | Padrão | Finalidade | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | obrigatório | Endereço do Failproof AI: `https://app.befailproof.ai` para Cloud. HTTPS, salvo se apontar para loopback | +| `FAILPROOFAI_EVALUATOR_TOKEN` | obrigatório | Uma chave com `evaluations:run` | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | Identifica este worker | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | Sessões que este worker pontua simultaneamente | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Timeout para cada requisição ao Failproof AI | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | Quanto tempo um worker em encerramento aguarda as execuções em andamento | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | Permite HTTP simples para uma URL que não seja loopback — veja o aviso abaixo | +| `FAILPROOFAI_EVALUATOR_MODULE` | nenhum | O `module:attribute` para `python -m failproofai_sdk.evaluator` | -Quando um token está configurado, todas as rotas, exceto health, exigem o mesmo bearer token que o Failproof AI envia como `EVALUATOR_TOKEN`. + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` envia tudo em texto simples. O worker carrega `FAILPROOFAI_EVALUATOR_TOKEN` como um cabeçalho `Authorization: Bearer` em cada requisição, e as transcrições que ele busca são as próprias sessões — portanto, qualquer pessoa no caminho lê ambos, e o token que obtiverem pode executar avaliações até que você o revogue. Use apenas em uma rede de desenvolvimento isolada. Em todos os outros ambientes, a URL deve ser HTTPS; loopback não exige nenhuma flag. + -## Tipos do SDK +## Tipos de resultado | Tipo | Campos | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## Decoradores e rotas +| `Score` | `value` (0 a 1), `passed`, `unit` (padrão `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -| Decorador | Rota | Obrigatório | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | Sim | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | Ao retornar `JobPending` | -| `@app.config` | `GET /config` | Não | - -O SDK limita o corpo das requisições de avaliação em 25 MiB. Campos desconhecidos nas requisições são ignorados, mantendo a compatibilidade dos serviços conforme o contrato de eventos evolui. +Um `EvalResult` carrega pelo menos um score, métrica ou asserção, e no máximo 25, cada um sob uma chave única. -## Retornar trabalho assíncrono +## A sessão -Use `JobPending` quando a avaliação não puder ser concluída dentro de uma única requisição. O ID do job é opaco para o Failproof AI e deve permanecer resolvível pelo seu serviço até que o resultado seja coletado ou o timeout do servidor expire. - -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| Campo ou método | O que fornece | +| --- | --- | +| `session_id`, `agent_id`, `environment` | A identidade da sessão | +| `started_at`, `ended_at` | Quando ela começou e terminou | +| `event_count`, `events` | A transcrição completa e ordenada | +| `count(event_type)` | Quantos eventos daquele tipo ela contém | +| `events_of_type(event_type)` | Esses eventos, em ordem | -A cadência de polling é selecionada nesta ordem: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs` e, em seguida, `EVALUATOR_POLLING_INTERVAL_SECS` do servidor. Os valores são limitados entre 1 segundo e 1 hora. O limite padrão de polling em tempo real do servidor é de uma hora. +Cada evento carrega `id`, `ts`, `event_type` e `payload`. -## Campos de requisição e resposta +## O evaluator legado -| Campo | Tipo | Observações | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | Atualmente `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | Identidade da sessão e ambiente. | -| `started_at` | `datetime` | Timestamp do primeiro evento. | -| `ended_at` | `datetime \| None` | Presente quando a sessão emitiu um evento de encerramento. | -| `events` | `list[AgentEvent]` | Stream de eventos completo e ordenado. | -| `AgentEvent.id` | `int` | Identificador da linha do evento no backend. | -| `AgentEvent.ts` | `datetime` | Timestamp do evento. | -| `AgentEvent.event_type` | `str` | Família do evento, como `tool_use`. | -| `AgentEvent.payload` | `dict[str, Any]` | Payload completo do evento. | -| `EvalResponse.scores` | `dict[str, float] \| None` | Dimensões numéricas exibidas em gráficos nas avaliações. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | Explicações por pontuação; as chaves devem espelhar `scores`. | -| `EvalResponse.summary` | `str \| None` | Narrativa geral da avaliação. | - -## Configurações do operador do servidor - -A avaliação automática é global para o deployment e permanece desabilitada quando `EVALUATOR_ENDPOINT` não está definido. - -| Variável | Padrão | Finalidade | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | não definido | URL base do serviço avaliador. | -| `EVALUATOR_TOKEN` | não definido | Bearer token compartilhado com `Evaluator(token=...)`. | -| `EVALUATOR_WORKERS` | `2` | Workers do dispatcher em execução simultânea. | -| `EVALUATOR_CLAIM_BATCH` | `4` | Sessões reivindicadas por passagem do dispatcher. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Cadência de polling assíncrono de fallback. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Timeout do avaliador por requisição. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | Tentativas de entrega antes de falha terminal. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | Cadência de atualização para `/config`. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Tempo máximo de polling assíncrono em tempo real. | - -O servidor também pode restringir quais organizações utilizam o avaliador global do deployment. Trate as alterações de endpoint, token, retry e controle de acesso por organização como configuração de operador e reinicie ou atualize o servidor após modificá-las. - -## Segurança e operações - -- Coloque o avaliador atrás de HTTPS quando o tráfego cruzar um limite de rede não confiável. -- Configure um bearer token não vazio e mantenha-o idêntico em ambos os serviços. -- Não registre em log o token nem prompts sensíveis completos dos payloads das requisições. -- Torne os handlers síncronos idempotentes; novas tentativas podem repetir uma requisição. -- Persista o estado de jobs assíncronos fora da memória do processo em produção. -- Retorne chaves de pontuação estáveis. Renomear uma chave cria uma nova série no gráfico em vez de alterar a existente. - -O SDK emite logs de ciclo de vida estruturados como `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` e exceções de handlers. Ele não configura handlers de logging; utilize a configuração de logging da aplicação hospedeira. \ No newline at end of file +O Evaluator SDK anterior — um serviço HTTP que o Failproof AI chamava em `EVALUATOR_ENDPOINT`, respondendo em `/evaluate` e consultado via `JobPending` — foi descontinuado. Construa novos evaluators usando este worker; operadores de uma instância self-hosted que ainda utilizam um serviço legado podem mantê-lo durante a transição. \ No newline at end of file diff --git a/docs/pt-br/reference/failproof-cli.mdx b/docs/pt-br/reference/failproof-cli.mdx index 2d4329a9..96c89a30 100644 --- a/docs/pt-br/reference/failproof-cli.mdx +++ b/docs/pt-br/reference/failproof-cli.mdx @@ -6,79 +6,97 @@ icon: "terminal" Instale o CLI local com `npm install -g failproofai`. Execute sem argumentos para abrir o painel de políticas local. -O pacote requer Node.js 20.9 ou mais recente. Bun 1.3 ou mais recente é compatível para desenvolvimento e instalações a partir do código-fonte. `failproofai configure` e `failproofai setup` são aliases para `failproofai config`; `failproofai p` é um alias para `failproofai policies`. +O pacote requer Node.js 20.9 ou superior. Bun 1.3 ou superior é suportado para desenvolvimento e instalações a partir do código-fonte. `failproofai configure` e `failproofai setup` são aliases para `failproofai config`. `failproofai policy`, `failproofai pack` e `failproofai p` são todas as formas de escrever `failproofai policies` — packs e políticas individuais eram três comandos para uma mesma ideia e agora são um só. As formas antigas ainda funcionam, com duas exceções: `pack list ` agora é `policies show `, e `pack build` agora é `publish`. ## Configurar uma máquina +Instale o CLI, depois leia a chave da máquina para o shell. `read -s` a recebe em um prompt que não exibe o texto digitado, portanto ela nunca aparece em um comando: + ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +Em seguida, configure a máquina e escolha o que ela deve impor: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` +`failproofai config` é o processo de configuração completo: instala o serviço `failproofaid` (uma vez como root, via `sudo -n` — nunca solicita senha interativa), integra hooks em todos os CLIs de agentes encontrados e conecta ao Cloud quando uma chave está disponível. Sem terminal — CI, container, um agente executando — ele aplica as configurações em vez de perguntar, e sai com código 1 se qualquer ação solicitada não foi concluída. + +Ele não escolhe **nenhuma** política. Essa é a responsabilidade do segundo comando, e sem ele uma máquina recém-configurada não impõe nada além da proteção sempre ativa. + +Prefira a variável de ambiente em vez de `--token`: um argumento de linha de comando pode ser lido via `ps` por qualquer usuário da máquina. Isso é tudo que a variável protege — uma chave digitada em qualquer comando, incluindo `export`, ainda vai parar no histórico do shell, por isso ela é lida com `read -s` acima. Em CI, defina-a a partir do repositório de segredos e mantenha o rastreamento do shell (`set -x`) desativado, ou o trace a exibirá. + + + `--connect ` registra uma máquina que **já está configurada**. Retorna assim que o registro é concluído — não instala o daemon e não configura nenhum hook. Use o simples `failproofai config` (ou `failproofai config --token `) em uma máquina que ainda não foi configurada, caso contrário ela aparecerá como conectada enquanto não coleta nem impõe nada. + + Execute `failproofai` sem argumentos para abrir o painel de políticas local. | Comando | Resultado | | --- | --- | -| `failproofai config` | Executar configuração interativa da máquina | -| `failproofai config --connect --token ` | Conectar a ingestão Cloud e a entrega de políticas | -| `failproofai config --status` | Exibir estado de conexão, daemon, entrega e pausa | -| `failproofai policies` | Listar políticas integradas, personalizadas, de convenção, de pacote e gerenciadas pelo Cloud | -| `failproofai policies --install` | Instalar hooks e habilitar políticas | -| `failproofai policy add ` | Habilitar uma política — integrada ou `:` de um pacote instalado | -| `failproofai policy remove ` | Desabilitar uma política, com a mesma nomenclatura | -| `failproofai policies --uninstall` | Desabilitar políticas ou remover hooks do harness | -| `failproofai pack list` | Listar pacotes de políticas instalados e todas as políticas de cada um | -| `failproofai pack add ` | Instalar um pacote de políticas a partir de um release do GitHub; sem tag instala o mais recente e o fixa | -| `failproofai pack add --bundled` | Instalar as políticas integradas como pacote, a partir deste package, sem rede | -| `failproofai pack build ` | Compilar os três assets de release para um pacote próprio | -| `failproofai pack remove ` | Desativar um pacote instalado | -| `failproofai audit` | Escanear o histórico local do agente e abrir a visualização de auditoria local | -| `failproofai audit --schedule [days] --email
` | Agendar varreduras locais recorrentes e enviar os resultados por e-mail | -| `failproofai audit --status` | Exibir o endereço de relatório, intervalo e próxima varredura agendada | -| `failproofai audit --no-schedule` | Interromper varreduras recorrentes sem excluir o histórico de auditoria | -| `failproofai harness list` | Listar caminhos de captura adicionais | -| `failproofai flush --wait` | Entregar o spool de eventos atual | -| `failproofai backfill --since 30d` | Reler histórico previamente processado | -| `failproofai config --pause [duration]` | Pausar uma sessão local por 30 minutos por padrão, até 8 horas | -| `failproofai config --resume` | Retomar uma sessão local pausada; adicione `--all` para limpar todas as pausas | -| `failproofai update` | Concluir migrações do pacote e atualizar o daemon | -| `failproofai migrate --dry-run` | Visualizar ou executar migrações pendentes do layout home | -| `failproofai uninstall` | Remover hooks e o daemon antes de remover o pacote | -| `failproofai --version` | Exibir a versão do pacote instalado | -| `failproofai --help` | Mostrar comandos e uso global | +| `failproofai config` | Configura a máquina: agentes, daemon e Cloud quando uma chave está presente | +| `failproofai config --token ` | Configura e conecta em uma única etapa, sem perguntar nada | +| `failproofai config --connect ` | Registra uma máquina que **já está** configurada — sem daemon, sem hooks | +| `failproofai config --status` | Exibe o estado de conexão, daemon, entrega e pausa | +| `failproofai policies` | Lista políticas integradas, personalizadas, convencionadas, de pack e gerenciadas pelo Cloud | +| `failproofai policies --install` | Integra hooks nos CLIs de agentes. Não ativa nenhuma política por si só | +| `failproofai policies add ` | Ativa uma política — integrada, ou `:` de um pack instalado | +| `failproofai policies remove ` | Desativa uma política, com a mesma nomenclatura | +| `failproofai policies --uninstall` | Desativa políticas ou remove hooks do harness | +| `failproofai policies show /` | O que um pack contém, lido a partir de seu manifesto, antes de instalá-lo | +| `failproofai policies show / --releases` | Todas as versões publicadas e qual está instalada | +| `failproofai policies add ` | Instala um pack de políticas a partir de uma release do GitHub; sem tag, instala a versão mais recente e a fixa | +| `failproofai publish` | Publica suas próprias políticas como um pack; `--init` cria um ponto de partida | +| `failproofai policies remove ` | Desinstala um pack | +| `failproofai audit` | Escaneia o histórico local do agente e abre a visualização de auditoria local | +| `failproofai audit --schedule [days] --email
` | Agenda scans locais recorrentes e envia os resultados por e-mail | +| `failproofai audit --status` | Exibe o endereço do relatório, o intervalo e o próximo scan agendado | +| `failproofai audit --no-schedule` | Para os scans recorrentes sem excluir o histórico de auditoria | +| `failproofai harness list` | Lista caminhos de captura adicionais | +| `failproofai flush --wait` | Entrega o spool de eventos atual | +| `failproofai backfill --since 30d` | Relê o histórico previamente processado | +| `failproofai config --pause [duration]` | Pausa uma sessão local por 30 minutos por padrão, até 8 horas | +| `failproofai config --resume` | Retoma uma sessão local pausada; adicione `--all` para limpar todas as pausas | +| `failproofai update` | Finaliza migrações de pacotes e atualiza o daemon | +| `failproofai migrate --dry-run` | Visualiza ou executa migrações pendentes do layout do diretório home | +| `failproofai uninstall` | Remove hooks e o daemon antes de remover o pacote | +| `failproofai --version` | Exibe a versão do pacote instalado | +| `failproofai --help` | Exibe os comandos e o uso global | ## Flags de configuração | Flag | Uso | | --- | --- | -| `--connect --token ` | Conectar de forma não interativa | -| `--machine-id ` | Definir o ID estável da máquina | -| `--machine-label ` | Definir ou alterar o rótulo no painel | -| `--no-transcripts` | Enviar decisões sem o conteúdo da transcrição | -| `--disconnect` | Interromper pulls de políticas Cloud e entrega de eventos | -| `--status` | Exibir o estado atual da máquina | -| `--pause [duration]` | Pausar a sessão mais recente no diretório atual; aceita segundos, minutos ou horas e tem padrão de 30 minutos | -| `--resume` | Encerrar uma pausa correspondente antes do tempo | -| `--session ` | Direcionar uma sessão explícita para pausa ou retomada | -| `--all` | Com `--resume`, encerrar todas as pausas ativas | - -Pausas locais suspendem políticas integradas, personalizadas, de convenção e de pacote para uma sessão. Elas sempre expiram e não desabilitam políticas gerenciadas pelo Cloud. `block-failproofai-commands` — que está sempre ativo e não pode ser desabilitado ou pausado — impede que um agente instrumentado use esse escape por conta própria. +| `--token ` | Configura e conecta de forma não interativa; também lido de `FAILPROOFAI_CLOUD_TOKEN` | +| `--url ` | Conecta a um endereço diferente de `app.befailproof.ai`; também lido de `FAILPROOFAI_CLOUD_URL` | +| `--connect ` | Somente registra, em uma máquina já configurada. Ignora o daemon e todos os hooks | +| `--machine-id ` | Define o ID estável da máquina | +| `--machine-label ` | Renomeia uma máquina que **já está conectada**. Por si só nunca executa a configuração, portanto use após `failproofai config`, não durante | +| `--no-transcripts` | Envia decisões sem o conteúdo da transcrição | +| `--disconnect` | Para os pulls de políticas do Cloud e a entrega de eventos | +| `--status` | Exibe o estado atual da máquina | +| `--pause [duration]` | Pausa a sessão mais recente no diretório atual; aceita segundos, minutos ou horas e o padrão é 30 minutos | +| `--resume` | Encerra uma pausa correspondente antecipadamente | +| `--session ` | Seleciona uma sessão específica para pausar ou retomar | +| `--all` | Com `--resume`, encerra todas as pausas ativas | + +Pausas locais suspendem políticas integradas, personalizadas, convencionadas e de pack para uma sessão. Elas sempre expiram e não desativam políticas gerenciadas pelo Cloud. `block-failproofai-commands` — que está sempre ativo e não pode ser desativado ou pausado — impede que um agente instrumentado use esse recurso de escape por conta própria. ## Flags de políticas | Flag | Uso | | --- | --- | -| `--install`, `-i` | Habilitar políticas e instalar hooks do harness | -| `--uninstall`, `-u` | Desabilitar políticas ou remover hooks | -| `--cli ` | Direcionar um ou mais harnesses compatíveis | -| `--scope user\|project\|local\|all` | Escolher o escopo de configuração; `all` é para desinstalação | -| `--beta` | Incluir políticas beta | -| `--custom`, `-c ` | Validar e carregar um arquivo de política personalizado; repetível | +| `--install`, `-i` | Instala hooks do harness. Nomes após ele ativam essas políticas; sem nenhum, nenhuma política é alterada | +| `--uninstall`, `-u` | Desativa políticas ou remove hooks | +| `--cli ` | Seleciona um ou mais harnesses suportados | +| `--scope user\|project\|local\|all` | Escolhe o escopo de configuração; `all` é para desinstalação | +| `--beta` | Inclui políticas beta | +| `--custom`, `-c ` | Valida e carrega um arquivo de política personalizado; pode ser repetido | ## Flags de entrega e manutenção @@ -90,7 +108,7 @@ Pausas locais suspendem políticas integradas, personalizadas, de convenção e | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` deve ser executado após `npm install -g failproofai@latest`; ele realiza migrações do layout home, instala o binário do daemon correspondente e reinicia o serviço. `--no-daemon` executa apenas a migração do layout. +`failproofai update` deve ser executado após `npm install -g failproofai@latest`; ele realiza migrações do layout do diretório home, instala o binário do daemon correspondente e reinicia o serviço. `--no-daemon` realiza apenas a migração do layout. ## Caminhos do harness @@ -100,11 +118,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -Os nomes de harness compatíveis são `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` e `goose`. +Os nomes de harness suportados são `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` e `goose`. -Labels criam namespaces para IDs de agentes derivados quando duas raízes contêm cópias do mesmo projeto. Raízes sobrepostas e labels duplicados são rejeitados para evitar coleta duplicada ou corrupção de cursor. A configuração de caminhos extras é recarregada sem reiniciar o daemon. +Labels criam namespaces para IDs de agentes derivados quando dois roots contêm cópias do mesmo projeto. Roots sobrepostos e labels duplicadas são rejeitados para evitar coleta duplicada ou corrupção do cursor. A configuração de caminhos extras é recarregada sem reiniciar o daemon. -Ambientes de container podem substituir caminhos extras configurados em arquivo por uma variável separada por vírgulas chamada `FAILPROOFAI__EXTRA_PATHS`, por exemplo: +Ambientes de container podem substituir os caminhos extras configurados em arquivos por uma variável separada por vírgulas chamada `FAILPROOFAI__EXTRA_PATHS`, por exemplo: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -112,26 +130,28 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Variáveis de ambiente -Use arquivos de configuração para comportamento persistente da máquina. Variáveis de ambiente são mais úteis para containers, testes e processos únicos. +Use arquivos de configuração para o comportamento persistente da máquina. Variáveis de ambiente são mais úteis para containers, testes e processos individuais. | Variável | Uso | | --- | --- | -| `FAILPROOFAI_HOME` | Realocar o layout completo de `~/.failproofai` | -| `FAILPROOFAI_LOG_LEVEL` | Definir o nível de verbosidade do log local | -| `FAILPROOFAI_HOOK_LOG_FILE` | Gravar diagnósticos de hook em um arquivo selecionado | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Desabilitar telemetria anônima para este processo | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Pular a configuração interativa de primeiro uso | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Pular a auditoria local pós-configuração | -| `FAILPROOFAI_LLM_BASE_URL` | Substituir o endpoint compatível com OpenAI usado pelas políticas LLM | -| `FAILPROOFAI_LLM_API_KEY` | Fornecer a chave de API usada pelas políticas LLM | -| `FAILPROOFAI_LLM_MODEL` | Selecionar o modelo usado pelas políticas LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limitar o tempo de carregamento de módulos de política personalizados | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Recusar o download de pacotes e binários do daemon; o que estiver instalado continua em vigor | -| `FAILPROOFAI_PACK_BASE_URL` | Buscar pacotes de um espelho em vez de `github.com` | -| `FAILPROOFAI__EXTRA_PATHS` | Substituir os caminhos de captura extras configurados para um harness | -| `NO_COLOR` | Desabilitar saída colorida no terminal | - -Variáveis home específicas de agente, como `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` e `OPENCLAW_HOME`, substituem onde o Failproof AI descobre sessões locais para aquele harness. +| `FAILPROOFAI_CLOUD_TOKEN` | A chave do Cloud, em vez de `--token`. Prefira esta forma: um argumento pode ser lido via `ps` por qualquer usuário. Defina-a com `read -s` ou a partir de um repositório de segredos de CI, nunca digitando a chave diretamente em um comando, pois isso vai parar no histórico do shell de qualquer forma | +| `FAILPROOFAI_CLOUD_URL` | A URL do Cloud, em vez de `--url`. A mesma variável que o daemon lê | +| `FAILPROOFAI_HOME` | Relocate o layout completo de `~/.failproofai` | +| `FAILPROOFAI_LOG_LEVEL` | Define o nível de verbosidade do log local | +| `FAILPROOFAI_HOOK_LOG_FILE` | Grava diagnósticos de hook em um arquivo selecionado | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Desativa a telemetria anônima para este processo | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignora a configuração interativa de primeira execução | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Ignora a auditoria local pós-configuração | +| `FAILPROOFAI_LLM_BASE_URL` | Substitui o endpoint compatível com OpenAI usado pelas políticas LLM | +| `FAILPROOFAI_LLM_API_KEY` | Fornece a chave de API usada pelas políticas LLM | +| `FAILPROOFAI_LLM_MODEL` | Seleciona o modelo usado pelas políticas LLM | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limita o tempo de carregamento de módulos de política personalizada | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Recusa buscar packs e binários do daemon; o que está instalado continua sendo imposto | +| `FAILPROOFAI_PACK_BASE_URL` | Busca packs de um mirror em vez de `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | Substitui os caminhos de captura extras configurados para um harness específico | +| `NO_COLOR` | Desativa a saída colorida no terminal | + +Variáveis de home específicas de agentes como `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` e `OPENCLAW_HOME` substituem onde o Failproof AI busca sessões locais para aquele harness. ## Pausar ou remover uma máquina com segurança @@ -141,7 +161,7 @@ failproofai config --status failproofai config --resume ``` -Uma pausa de sessão local não desabilita políticas gerenciadas pelo Cloud. Restaure implantações Cloud pelo fluxo de trabalho de enforcement Cloud quando o próprio rollout for o problema. +Uma pausa de sessão local não desativa políticas gerenciadas pelo Cloud. Restaure implantações do Cloud por meio do fluxo de trabalho de imposição do Cloud quando o próprio rollout for o problema. Antes de remover o pacote npm, remova os hooks instalados e o daemon: @@ -154,5 +174,5 @@ npm rm -g failproofai Execute `failproofai --help` para detalhes específicos da versão. - Execute `failproofai uninstall` antes de `npm rm -g failproofai`; o npm não remove os hooks de agente instalados nem o serviço do daemon. + Execute `failproofai uninstall` antes de `npm rm -g failproofai`; o npm não remove os hooks de agentes instalados nem o serviço daemon. \ No newline at end of file diff --git a/docs/pt-br/reference/harnesses.mdx b/docs/pt-br/reference/harnesses.mdx index b8acaf03..18f33c03 100644 --- a/docs/pt-br/reference/harnesses.mdx +++ b/docs/pt-br/reference/harnesses.mdx @@ -4,14 +4,14 @@ description: "Capture sessões e aplique políticas em todos os 12 harnesses de icon: "plug-zap" --- -Um harness é o ambiente onde seu agente realmente executa. O Failproof AI suporta doze deles, em duas classes: +Um harness é o ambiente no qual seu agente realmente executa. Failproof AI suporta doze deles, em duas categorias: - **CLIs de codificação** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Gateways de chat e assistente** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistente self-hosted) +- **Gateways de chat e assistentes** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistente auto-hospedado) -As mesmas políticas e o mesmo histórico de sessão se aplicam independentemente de qual harness um agente utiliza. Uma camada adaptadora mapeia os nomes de eventos nativos, nomes de ferramentas e campos de entrada de ferramentas de cada harness para 29 eventos canônicos antes que qualquer política seja executada. +As mesmas políticas e o mesmo histórico de sessões se aplicam independentemente de qual harness o agente utiliza. Uma camada de adaptador mapeia os nomes de eventos nativos, nomes de ferramentas e campos de entrada de ferramentas de cada harness para 29 eventos canônicos antes que qualquer política seja executada. -Um agente que não roda em **nenhum** dos doze é instrumentado diretamente com o [SDK Python](/pt-br/reference/custom-agents). Esse é um contrato diferente, e vale deixar claro: o SDK fornece rastreamento, sessões, avaliações e auditorias — **ele não aplica políticas por conta própria.** Bloquear uma ação insegura antes que ela seja executada requer um hook de aplicação na fronteira de ferramentas do seu runtime; [entre em contato](mailto:support@befailproof.ai) e faremos o mapeamento. +Um agente que não utiliza **nenhum** dos doze é instrumentado diretamente com o [SDK Python](/pt-br/reference/custom-agents). Esse é um contrato diferente, e vale dizer claramente: o SDK oferece rastreamento, sessões, avaliações e auditorias — **mas não aplica políticas por conta própria.** Bloquear uma ação insegura antes que ela seja executada requer um hook de enforcement no limite de ferramentas do seu runtime; [entre em contato](mailto:support@befailproof.ai) e iremos mapeá-lo. | Harness | Escopos de hook suportados | | --- | --- | @@ -20,35 +20,35 @@ Um agente que não roda em **nenhum** dos doze é instrumentado diretamente com | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -Cada integração normaliza os nomes de eventos nativos do hook, nomes de ferramentas e campos de entrada de ferramentas antes que as políticas sejam executadas. Uma política só pode agir sobre eventos que o harness expõe; teste o comportamento de fim de turno e de instrução no harness e na versão exatos que você implanta. +Cada integração normaliza os nomes de eventos de hook nativos, nomes de ferramentas e campos de entrada de ferramentas antes que as políticas sejam executadas. Uma política só pode agir sobre eventos que o harness expõe; teste o comportamento de fim de turno e de instrução no harness e versão exatos que você implanta. -## Capacidade de aplicação +## Capacidade de enforcement -"Bloquear" significa que o veredito retornado pelo adaptador atual é consumido pelo harness indicado. O bloqueio pós-ferramenta pode substituir o resultado exibido ao modelo, mas não pode desfazer um efeito colateral de ferramenta que já ocorreu. +"Bloquear" significa que o veredicto retornado pelo adaptador atual é consumido pelo harness indicado. O bloqueio pós-ferramenta pode substituir o resultado exibido ao modelo, mas não pode desfazer um efeito colateral de ferramenta que já ocorreu. -| Harness | Eventos de bloqueio verificados | Ressalvas de observação ou não-bloqueio | +| Harness | Eventos de bloqueio verificados | Ressalvas de observação apenas ou sem bloqueio | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` e vários eventos de tarefa/configuração | `PostToolUse`, ciclo de vida de sessão, notificações e eventos pós-falha são observacionais. | +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` e vários eventos de task/config | `PostToolUse`, ciclo de vida de sessão, notificações e eventos pós-falha são observacionais. | | Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | O bloqueio pós-ferramenta substitui o resultado após a execução; eventos de início de sessão e compactação são observacionais no adaptador atual. | | GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | O bloqueio pós-ferramenta substitui o resultado após a execução; eventos de sessão e notificação são observacionais. | | Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` e eventos de sessão são observacionais. | | OpenCode | `PreToolUse` | Eventos pós-ferramenta e de ciclo de vida são observacionais; o tratamento de stop atual é uma orientação para um turno posterior, não um gate verificado. | | Pi | `PreToolUse`, `UserPromptSubmit` | Eventos pós-ferramenta e de ciclo de vida são observacionais; a orientação de stop se aplica a um turno posterior. | -| Hermes | `PreToolUse` | Vereditos pós-ferramenta, de sessão e de subagent-stop não são gates. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Eventos pós-ferramenta, de sessão, subagent-stop e de compactação são observacionais. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Vereditos pós-ferramenta e de subagent-stop são observacionais. | +| Hermes | `PreToolUse` | Veredictos pós-ferramenta, de sessão e de subagent-stop não são gates. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Eventos pós-ferramenta, de sessão, subagent-stop e compactação são observacionais. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Veredictos pós-ferramenta e subagent-stop são observacionais. | | Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condicional | Hooks de permissão não são executados em todos os modos de permissão; eventos pós-ferramenta e de sessão são observacionais. | -| Antigravity CLI | `PreToolUse`, `Stop` | Vereditos de prompt do usuário e pós-ferramenta são observacionais; instruções de prompt ainda podem ser injetadas. | -| Goose | `PreToolUse` | Eventos de prompt do usuário, pós-ferramenta e de sessão são observacionais. Existe um hook de stop com bloqueio nativo upstream, mas ele não é instalado pelo adaptador atual. | +| Antigravity CLI | `PreToolUse`, `Stop` | Veredictos de user-prompt e pós-ferramenta são observacionais; instruções de prompt ainda podem ser injetadas. | +| Goose | `PreToolUse` | Eventos de user-prompt, pós-ferramenta e de sessão são observacionais. Existe um hook de stop de bloqueio nativo upstream, mas não é instalado pelo adaptador atual. | -As capacidades são sensíveis à versão. Refaça os testes após atualizar uma CLI de agente, especialmente quando uma política depende de comportamento de prompt, stop, permissão ou pós-ferramenta em vez do gate pré-ferramenta comum. +As capacidades são sensíveis à versão. Repita os testes após atualizar um CLI de agente, especialmente quando uma política depende de comportamento de prompt, stop, permissão ou pós-ferramenta em vez do gate pré-ferramenta comum. -## Instalar hooks de captura e política +## Instalar hooks de captura e políticas 1. Abra **Administration → Keys** e crie uma chave com `events:add` e `policies:pull`, nomeada para a máquina ou ambiente. - 2. Na máquina de destino, conecte a CLI local com a chave exibida e instale os hooks do harness. + 2. Na máquina de destino, conecte o CLI local com a chave exibida e instale os hooks do harness. 3. Inicie uma nova sessão de agente e confirme seus eventos de hook e sessão em **Observe → Events**. 4. Abra **Observe → policy** para a mesma janela de tempo e confirme que uma decisão de política está atribuída à máquina. @@ -56,24 +56,30 @@ As capacidades são sensíveis à versão. Refaça os testes após atualizar uma ![O drawer de nova chave de API usado para conceder permissões de ingestão de eventos e entrega de políticas.](/images/dashboard/key-create.png) - Após instalar os hooks, o stream de Events deve exibir novos eventos da máquina e do ambiente que você conectou. + Após instalar os hooks, o stream de eventos deve mostrar novos eventos da máquina e do ambiente que você conectou. - ![O stream de Events ao vivo usado para confirmar que um harness recém-instalado está reportando.](/images/dashboard/events-stream.png) + ![O stream de eventos ao vivo usado para confirmar que um harness recém-instalado está reportando.](/images/dashboard/events-stream.png) - Por fim, verifique se as decisões de política estão atribuídas à mesma máquina. Isso confirma que o harness está reportando a atividade de política, além dos eventos de rastreamento. + Por fim, verifique se as decisões de política estão atribuídas à mesma máquina. Isso confirma que o harness está reportando atividade de políticas além dos eventos de rastreamento. - ![A página Policy usada para verificar decisões de política de um harness recém-conectado.](/images/dashboard/policy-observe.png) + ![A página de políticas usada para verificar decisões de política de um harness recém-conectado.](/images/dashboard/policy-observe.png) - Instale hooks para todos os harnesses detectados: + Leia a chave da máquina no shell. `read -s` a solicita em um prompt que não exibe a entrada, portanto ela nunca aparece em um comando ou no histórico do shell: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` + Em seguida, configure a máquina — isso conecta hooks para cada harness detectado, instala o daemon e conecta ao Cloud: + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + A configuração não habilita nenhuma política por conta própria; é para isso que serve o segundo comando. + Ou direcione harnesses específicos e um escopo de configuração: ```bash @@ -82,7 +88,7 @@ As capacidades são sensíveis à versão. Refaça os testes após atualizar uma --scope user ``` - O escopo de projeto mantém a configuração de hook junto ao repositório. O escopo de usuário cobre o trabalho em vários repositórios. Claude Code também suporta escopo local; o suporte varia por harness e a CLI rejeita combinações não suportadas. + O escopo de projeto mantém a configuração de hooks junto ao repositório. O escopo de usuário cobre o trabalho entre repositórios. Claude Code também suporta escopo local; o suporte varia por harness e o CLI rejeita combinações não suportadas. Verifique a máquina e seus eventos: @@ -98,9 +104,9 @@ As capacidades são sensíveis à versão. Refaça os testes após atualizar uma - Caminhos extras são registrados na máquina, não na Cloud. Após adicionar um, abra **Observe → Sessions**, filtre pelo ambiente da máquina e confirme se as sessões do novo caminho aparecem. Abra uma sessão e verifique o agente, o harness e os timestamps de eventos antes de utilizá-la em uma auditoria. + Caminhos extras são registrados na máquina, não no Cloud. Após adicionar um, abra **Observe → Sessions**, filtre pelo ambiente da máquina e confirme que as sessões do novo caminho aparecem. Abra uma sessão e verifique o agente, o harness e os timestamps de eventos antes de utilizá-la em uma auditoria. - ![A lista de Sessions filtrada pelo ambiente que recebe dados do caminho de captura adicional.](/images/dashboard/sessions-list.png) + ![A lista de sessões filtrada pelo ambiente que recebe dados do caminho de captura adicional.](/images/dashboard/sessions-list.png) Adicione um caminho com um rótulo opcional e inspecione os caminhos configurados: diff --git a/docs/pt-br/reference/overview.mdx b/docs/pt-br/reference/overview.mdx index f7172d6a..51a28a85 100644 --- a/docs/pt-br/reference/overview.mdx +++ b/docs/pt-br/reference/overview.mdx @@ -4,16 +4,16 @@ description: "Conecte harnesses de agentes, SDKs, CLIs e a API HTTP compatíveis icon: "braces" --- -Escolha a integração mais próxima de onde seu agente já está em execução. +Escolha a integração mais próxima de onde seu agente já está sendo executado. - Instale hooks para CLIs de codificação e agentes autônomos compatíveis. + Instale hooks para CLIs de agentes de codificação e autônomos compatíveis. - + Instrumente LangGraph, CrewAI, LlamaIndex, Pydantic AI ou um agente personalizado. - + Configuração, catálogo de eventos, regras de correlação e entrega. @@ -29,52 +29,55 @@ Escolha a integração mais próxima de onde seu agente já está em execução. Pontue sessões completas ou inativas com um serviço FastAPI. - Crie e teste decisões de allow, instruct e deny específicas para cada fluxo de trabalho. + Crie e teste decisões de allow, instruct e deny específicas para fluxos de trabalho. Implante o plano de controle do Cloud em um cluster Kubernetes gerenciado pelo cliente. -A [referência da API HTTP](/pt-br/reference/http-api) gerada cobre a superfície pública `/v1`. As páginas escritas manualmente explicam fluxos de trabalho que abrangem múltiplos endpoints ou utilizam interfaces administrativas fora dessa superfície pública. +A [referência da API HTTP](/pt-br/reference/http-api) gerada cobre a superfície pública `/v1`. Páginas escritas manualmente explicam fluxos de trabalho que abrangem múltiplos endpoints ou utilizam interfaces administrativas fora dessa superfície pública. -## Conectar um agente e verificar os dados +## Conectar um agente e verificar dados - 1. Abra **Administração → Chaves**, crie uma chave com `events:add` e `policies:pull`, e copie o segredo. + 1. Abra **Administration → Keys**, crie uma chave com `events:add` e `policies:pull`, e copie o segredo. 2. Configure a integração usando a página correspondente acima. - 3. Abra **Observar → Eventos** para confirmar que os eventos estão chegando, depois **Observar → Sessões** para confirmar que eles formam execuções completas. - 4. Filtre pelo ambiente da integração e inspecione uma sessão para verificar os campos de modelo, ferramenta, erro e política necessários para as auditorias. + 3. Abra **Observe → Events** para confirmar que os eventos chegam e, em seguida, **Observe → Sessions** para confirmar que eles formam execuções completas. + 4. Filtre pelo ambiente da integração e inspecione uma sessão para verificar os campos de modelo, ferramenta, erro e política necessários para auditorias. - Comece pelo painel de chaves. As permissões selecionadas determinam se a máquina pode enviar eventos e receber políticas gerenciadas pelo Cloud. + Comece pelo drawer de chaves. As permissões selecionadas determinam se a máquina pode enviar eventos e receber políticas gerenciadas pelo Cloud. - ![O painel de criação de chave de API usado para conceder permissões de ingestão de eventos e entrega de políticas.](/images/dashboard/key-create.png) + ![O drawer de criação de chave de API usado para conceder permissões de ingestão de eventos e entrega de políticas.](/images/dashboard/key-create.png) - Após conectar a integração, use a lista de Sessões para confirmar que seus eventos estão sendo agrupados em execuções completas no ambiente esperado. + Após conectar a integração, use a lista de Sessions para confirmar que seus eventos estão sendo agrupados em execuções completas no ambiente esperado. - ![A lista de Sessões usada para verificar que uma integração recém-conectada está reportando execuções completas de agentes.](/images/dashboard/sessions-list.png) + ![A lista de Sessions usada para verificar que uma integração recém-conectada está reportando execuções completas de agentes.](/images/dashboard/sessions-list.png) Abra uma dessas sessões antes de considerar a integração concluída; o rastreamento deve conter o modelo, a ferramenta, o erro e as evidências de política que suas auditorias precisam. - Crie uma chave de máquina, conecte o daemon do Failproof e verifique a primeira sessão. + Crie uma chave de máquina e leia o segredo impresso no shell. `read -s` o recebe em um prompt que não ecoa, portanto ele nunca aparece em um comando nem no histórico do shell: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Conecte o daemon do Failproof e verifique a primeira sessão: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - Use `fp --json sessions ...` quando outro tool consumir o resultado. Flags globais como `--json`, `--org` e `--base-url` devem vir antes do comando. + Use `fp --json sessions ...` quando outra ferramenta for consumir o resultado. Flags globais como `--json`, `--org` e `--base-url` devem vir antes do comando. Consulte a [referência do CLI do Failproof AI](/pt-br/reference/failproof-cli) para comandos locais e a [referência do CLI do Failproof Cloud](/pt-br/reference/cloud-cli#cli-commands) para comandos `fp`. diff --git a/docs/pt-br/reference/policy-sdk.mdx b/docs/pt-br/reference/policy-sdk.mdx index acc6bf81..13a85aeb 100644 --- a/docs/pt-br/reference/policy-sdk.mdx +++ b/docs/pt-br/reference/policy-sdk.mdx @@ -4,18 +4,18 @@ description: "Crie, teste e implante políticas em JavaScript ou TypeScript para icon: "shield-plus" --- -As políticas personalizadas transformam um padrão de falha identificado nos seus rastreamentos ou auditorias em uma decisão que é executada enquanto o agente trabalha. Uma política pode permitir uma ação, fornecer orientação ao agente ou bloquear a ação antes que ela cause outro incidente. +Políticas personalizadas transformam um padrão de falha encontrado nos seus traces ou auditorias em uma decisão que é executada enquanto o agente trabalha. Uma política pode permitir uma ação, fornecer orientação ao agente ou bloquear a ação antes que ela cause um novo incidente. -Use uma política personalizada quando o comportamento depende das suas ferramentas, caminhos, comandos, ambientes ou regras operacionais. Consulte o [catálogo de políticas integradas](/pt-br/policies/builtin-catalog) antes para não recriar um controle já existente. +Use uma política personalizada quando o comportamento depende das suas ferramentas, caminhos, comandos, ambientes ou regras operacionais. Consulte primeiro o [pacote de políticas do Failproof AI](/pt-br/policies/packs) para não recriar um controle já existente. -## Criando uma política personalizada +## Criar uma política personalizada - 1. Acesse **Admin → editor de políticas**, selecione **Nova política** e descreva a falha que deseja prevenir. - 2. Adicione o código da política e teste correspondências esperadas e não correspondências seguras no editor. Resolva todos os erros de validação. + 1. Acesse **Admin → editor de políticas**, selecione **Nova política** e descreva a falha que você deseja prevenir. + 2. Adicione o código-fonte da política, depois teste as correspondências esperadas e os casos seguros que não devem corresponder no editor. Resolva todos os erros de validação. 3. Salve o rascunho e selecione **Publicar versão** para criar uma versão imutável. - 4. Acesse **Admin → enforcement**, implante a versão em uma máquina de teste no modo **observe** e verifique as decisões em **Observe → policy** antes de aplicá-la. + 4. Acesse **Admin → enforcement**, implante a versão em uma máquina de teste no modo **observe** e verifique suas decisões em **Observe → policy** antes de aplicá-la. ![O editor de políticas usado para criar e publicar uma política personalizada.](/images/dashboard/policy-editor.png) @@ -23,13 +23,13 @@ Use uma política personalizada quando o comportamento depende das suas ferramen 1. Crie `.failproofai/policies/checkout-policies.ts`. O nome do arquivo deve terminar em `policies.js`, `policies.mjs` ou `policies.ts`. 2. Registre uma ou mais políticas com `customPolicies.add()`. 3. Valide e instale o arquivo com `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. - 4. Acione uma ação correspondente e uma ação segura. Execute `failproofai policies` e inspecione as decisões atribuídas em **Observe → policy**. + 4. Acione uma ação que deve corresponder e uma ação segura. Execute `failproofai policies` e inspecione as decisões atribuídas em **Observe → policy**. ## Comece com uma regra restrita -Esta política bloqueia comandos Kubernetes destrutivos apenas quando o comando tem como alvo a produção. Tudo fora desse modo de falha específico retorna `allow()`. +Esta política bloqueia comandos destrutivos do Kubernetes somente quando o comando tem como alvo o ambiente de produção. Tudo fora desse padrão de falha exato retorna `allow()`. ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,20 +55,20 @@ customPolicies.add({ }); ``` -Boas políticas são suficientemente restritas para serem explicadas em uma única frase. Corresponda à ação observável — não à intenção que você espera que o agente tenha — e retorne `allow()` assim que a regra não se aplicar. +Boas políticas são restritas o suficiente para serem explicadas em uma única frase. Corresponda à ação observável — não à intenção que você espera que o agente tenha — e retorne `allow()` assim que a regra não se aplicar. -## Escolhendo uma decisão +## Escolha uma decisão -| Helper | Resultado | Use quando | +| Helper | Resultado | Quando usar | | --- | --- | --- | | `allow(reason?)` | A operação continua. | A política não se aplica ou a ação é segura. | -| `instruct(reason)` | A operação continua com orientação onde o harness suporta. | Você deseja direcionar o agente para uma abordagem melhor sem impor uma restrição absoluta. | +| `instruct(reason)` | A operação continua com orientação quando o harness suporta. | Você quer direcionar o agente para uma abordagem melhor sem impor uma invariante. | | `deny(reason)` | A operação é bloqueada quando o evento e o harness suportam bloqueio. | A ação não deve prosseguir. | Escreva o motivo para o agente que precisará se recuperar. Explique o que foi detectado e o que ele deve fazer em vez disso. - Não use `instruct()` para um limite de segurança. A entrega de orientação varia conforme o harness do agente. Use `deny()` quando a ação precisar ser impedida. + Não use `instruct()` para um limite de segurança. A entrega de orientações varia conforme o harness do agente. Use `deny()` quando a ação deve ser impedida. ## Objeto de política @@ -84,12 +84,12 @@ customPolicies.add({ | Campo | Obrigatório | Descrição | | --- | --- | --- | -| `name` | Sim | Identificador estável para a política. Mantenha nomes únicos entre os arquivos. | -| `description` | Não | Descrição legível exibida nas listagens de políticas e decisões. | -| `match.events` | Não | Tipos de eventos que invocam a política. Omitir `match` faz com que ela seja invocada para todo evento disponível. | +| `name` | Sim | Identificador estável da política. Mantenha os nomes únicos entre arquivos. | +| `description` | Não | Descrição legível exibida nas listagens de políticas e nas decisões. | +| `match.events` | Não | Tipos de eventos que invocam a política. Omitir `match` faz com que ela seja invocada para todos os eventos disponíveis. | | `fn` | Sim | Função síncrona ou assíncrona que retorna um resultado `allow`, `instruct` ou `deny`. | -Filtre ferramentas dentro de `fn`. `match.toolNames` não faz parte do tipo público de política personalizada. +Filtre as ferramentas dentro de `fn`. O campo `match.toolNames` não faz parte do tipo público de política personalizada. ## Contexto da política @@ -101,11 +101,11 @@ Toda política recebe um `PolicyContext`. | `toolName` | `string \| undefined` | Nome canônico da ferramenta, como `Bash`, `Read`, `Write` ou `Edit`. | | `toolInput` | `Record \| undefined` | Entrada canônica para a chamada de ferramenta atual. | | `payload` | `Record` | Payload completo do evento normalizado. | -| `session` | `SessionMetadata \| undefined` | ID da sessão, diretório de trabalho, caminho da transcrição, modo de permissão e metadados do harness quando disponíveis. | +| `session` | `SessionMetadata \| undefined` | ID da sessão, diretório de trabalho, caminho do transcript, modo de permissão e metadados do harness quando disponíveis. | | `cli` | `string \| undefined` | Harness do agente de origem, como `claude`, `codex` ou `cursor`. | -| `params` | `Record` | Parâmetros de política integrada. Políticas personalizadas atualmente recebem um objeto vazio. | +| `params` | `Record` | Parâmetros de políticas integradas. Políticas personalizadas atualmente recebem um objeto vazio. | -Trate todo valor opcional como genuinamente opcional. Versões de agentes e tipos de eventos nem sempre fornecem os mesmos campos. +Trate todos os valores opcionais como genuinamente opcionais. Versões de agentes e tipos de eventos nem sempre fornecem os mesmos campos. ### Entradas comuns de ferramentas @@ -119,26 +119,26 @@ O Failproof AI normaliza ferramentas comuns entre os harnesses suportados para q | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | -Use coerção defensiva, pois os valores de entrada de ferramenta são tipados como `unknown`: +Use coerção defensiva porque os valores de entrada das ferramentas são tipados como `unknown`: ```ts const command = String(ctx.toolInput?.command ?? ""); const filePath = String(ctx.toolInput?.file_path ?? ""); ``` -## Escolhendo o evento +## Escolha o evento | Evento | Quando é executado | Uso típico | | --- | --- | --- | | `PreToolUse` | Antes de uma ferramenta ser executada. | Bloquear ou orientar comandos, escritas, leituras e ações externas. | -| `PostToolUse` | Após uma ferramenta retornar. | Inspecionar resultados antes que cheguem ao agente. Um deny bloqueia todo o resultado; não redige campos selecionados. | +| `PostToolUse` | Após uma ferramenta retornar. | Inspecionar resultados antes de chegarem ao agente. Um deny bloqueia o resultado inteiro; não redige campos selecionados. | | `PermissionRequest` | Quando o agente solicita permissão. | Aplicar regras de permissão específicas da organização. | -| `UserPromptSubmit` | Antes de um prompt enviado continuar. | Rejeitar instruções proibidas ou adicionar orientação de fluxo de trabalho. | +| `UserPromptSubmit` | Antes de um prompt enviado continuar. | Rejeitar instruções proibidas ou adicionar orientações de fluxo de trabalho. | | `Stop` | Quando o agente tenta finalizar. | Exigir uma condição de conclusão alcançável, como uma etapa de verificação local. | -| `SubagentStop` | Quando um subagente tenta finalizar. | Controlar o trabalho delegado antes que retorne ao agente pai. | -| `SessionStart` / `SessionEnd` | Nos limites de sessão. | Registrar ou verificar o estado em nível de sessão. | +| `SubagentStop` | Quando um subagente tenta finalizar. | Controlar o trabalho delegado antes de retorná-lo ao agente pai. | +| `SessionStart` / `SessionEnd` | Em limites de sessão. | Registrar ou verificar estado no nível da sessão. | -A disponibilidade de eventos e o comportamento de bloqueio dependem do harness do agente. Consulte [Harnesses de agentes](/pt-br/reference/harnesses) antes de depender de um evento em uma frota mista. +A disponibilidade dos eventos e o comportamento de bloqueio dependem do harness do agente. Consulte [Harnesses de agentes](/pt-br/reference/harnesses) antes de depender de um evento em uma frota heterogênea. `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` e `Setup`. @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### Controlar a conclusão de sessão +### Controlar a conclusão da sessão ```ts import { execFileSync } from "node:child_process"; @@ -215,10 +215,10 @@ customPolicies.add({ ``` - Um evento `Stop` negado pode fazer o agente tentar novamente. Apenas controle por uma condição que o agente possa satisfazer no ambiente atual, e limite todo subprocesso ou chamada de rede. + Um evento `Stop` negado pode fazer o agente tentar novamente. Aplique a condição somente se o agente conseguir satisfazê-la no ambiente atual, e defina limites de tempo para todo subprocesso ou chamada de rede. -## Carregando arquivos de política +## Carregar arquivos de política ### Arquivos de convenção @@ -231,14 +231,14 @@ Arquivos de convenção são carregados automaticamente: - Os diretórios de políticas do projeto e do usuário são carregados. - Os arquivos são carregados em ordem alfabética dentro de cada diretório. -- Um arquivo deve terminar em `policies.js`, `policies.mjs` ou `policies.ts`. -- Múltiplas chamadas `customPolicies.add()` em um arquivo são suportadas. +- O arquivo deve terminar em `policies.js`, `policies.mjs` ou `policies.ts`. +- Múltiplas chamadas `customPolicies.add()` em um mesmo arquivo são suportadas. - Importações relativas de módulos locais são suportadas. - As políticas do projeto podem ser versionadas para que as mesmas regras acompanhem o repositório. ### Arquivos explícitos -Use caminhos explícitos quando a validação ou configuração deve nomear diretamente o arquivo de entrada: +Use caminhos explícitos quando a validação ou configuração precisar nomear diretamente o arquivo de entrada: ```bash failproofai policies --install \ @@ -260,44 +260,44 @@ failproofai policies --install \ failproofai policies ``` -A validação detecta arquivos ausentes, erros de sintaxe, importações não resolvidas, exceções de nível superior e timeouts de carregamento de módulo. Ela não garante que sua lógica de correspondência esteja correta. +A validação detecta arquivos ausentes, erros de sintaxe, importações não resolvidas, exceções no nível superior e timeouts de carregamento de módulo. Ela não comprova que a lógica de correspondência está correta. Teste pelo menos estes casos: -- Uma ação que deve corresponder e produzir o motivo de política pretendido. +- Uma ação que deve corresponder e produzir o motivo de política esperado. - Uma ação próxima, mas segura, que deve retornar `allow()`. - Campos de ferramenta ausentes ou malformados. -- Sintaxe de comando alternativa, caminhos, aspas, capitalização e espaços em branco. +- Sintaxe alternativa de comandos, caminhos, aspas, capitalização e espaços em branco. - Um subprocesso ou dependência de rede indisponível. -Atribua o resultado à sua política personalizada em **Observe → policy**. Um teste bloqueado não é suficiente se uma política integrada diferente tiver tomado a decisão. +Atribua o resultado à sua política personalizada em **Observe → policy**. Um teste bloqueado não é suficiente se uma política integrada diferente tomou a decisão. ## Comportamento em tempo de execução -- Políticas integradas são avaliadas antes das políticas personalizadas. -- O primeiro `deny` interrompe a avaliação de políticas subsequentes. -- Múltiplos resultados `instruct` podem ser combinados quando nenhuma política nega o evento. +- As políticas integradas são avaliadas antes das políticas personalizadas. +- O primeiro `deny` interrompe a avaliação das demais políticas. +- Múltiplos resultados `instruct` podem ser combinados quando nenhuma políticanega o evento. - Uma função de política tem um prazo de execução de 10 segundos. - Uma exceção lançada ou timeout é registrado e tratado como `allow()`. -- Um arquivo de convenção que falha ao carregar é ignorado; outros arquivos personalizados e políticas integradas continuam. -- O carregamento de módulo de nível superior também tem um prazo de 10 segundos. +- Um arquivo de convenção que falha ao carregar é ignorado; os outros arquivos personalizados e as políticas integradas continuam funcionando. +- O carregamento de módulo no nível superior também tem um prazo de 10 segundos. - O modo observe em nuvem executa a política, mas registra uma decisão diferente de allow sem aplicá-la. -Mantenha os módulos de política determinísticos e rápidos. Evite chamadas de rede ou inicialização de servidor no nível superior. Limite o trabalho dentro de `fn`, trate falhas de dependências e escolha deliberadamente se essa falha deve permitir ou bloquear a operação. +Mantenha os módulos de política determinísticos e rápidos. Evite chamadas de rede ou inicialização de servidores no nível superior. Delimite o trabalho dentro de `fn`, trate falhas de dependência e decida conscientemente se essa falha deve permitir ou bloquear a operação. ## Exportações da API | Exportação | Finalidade | | --- | --- | -| `customPolicies.add(policy)` | Registrar uma política personalizada quando o módulo carrega. | -| `allow(reason?)` | Permitir a operação. | -| `instruct(reason)` | Permitir a operação e fornecer orientação onde suportado. | -| `deny(reason)` | Bloquear a operação onde suportado. | -| `getCustomHooks()` | Retornar as políticas atualmente registradas no registro do módulo. | -| `clearCustomHooks()` | Limpar esse registro, principalmente para testes e carregadores. | +| `customPolicies.add(policy)` | Registra uma política personalizada quando o módulo é carregado. | +| `allow(reason?)` | Permite a operação. | +| `instruct(reason)` | Permite a operação e fornece orientação onde suportado. | +| `deny(reason)` | Bloqueia a operação onde suportado. | +| `getCustomHooks()` | Retorna as políticas atualmente registradas no registro do módulo. | +| `clearCustomHooks()` | Limpa esse registro, principalmente para testes e carregadores. | -TypeScript exporta `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` e `PolicyFunction`. +O TypeScript exporta `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` e `PolicyFunction`. - Publique uma versão, implante-a no modo observe, verifique as decisões e avance para o enforcement. + Publique uma versão, implante-a no modo observe, verifique as decisões e passe para a aplicação. \ No newline at end of file diff --git a/docs/pt-br/sessions/evaluations.mdx b/docs/pt-br/sessions/evaluations.mdx index f57e93d5..1757fdbf 100644 --- a/docs/pt-br/sessions/evaluations.mdx +++ b/docs/pt-br/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "Avaliações online" -description: "Pontue sessões ativas e concluídas em relação à qualidade, conformidade, custo e latência." +title: "Leia os resultados das avaliações" +description: "Visualize pontuações ao longo do tempo, compare agentes e ambientes, veja por que uma sessão teve pontuação baixa e consulte o assistente." icon: "gauge" --- -As avaliações online aplicam julgamentos consistentes às sessões de agentes. Utilize-as para sinais que devem ser medidos continuamente, e não apenas investigados durante uma auditoria. +Os resultados de cada avaliação, sejam hospedadas ou do seu próprio worker, chegam nos mesmos lugares. -## Revise a qualidade das avaliações +## Compare pontuações ao longo do tempo - 1. Vá para **Observe → Evaluations**. - 2. Adicione uma série e escolha o agente, o ambiente, a pontuação de avaliação, a estatística e a curva. - 3. Adicione séries para comparar ambientes, agentes ou chaves de pontuação. - 4. Selecione um resultado para abrir as sessões correspondentes ou compartilhar a visualização filtrada. Use **Observe → Metrics** para latência, tokens, custo e outros valores de magnitude. + Acesse **Observe → evaluations**. - ![Um dashboard de qualidade exibindo pontuações médias de avaliação e tendências ao longo do tempo.](/images/dashboard/dashboard-quality.png) + - **Recent runs** lista cada avaliação conforme ela chega: se veio de um avaliador hospedado (**managed**) ou do seu próprio (**customer**), o agente e a sessão, a avaliação e sua versão, o status e a pontuação ou métricas. + - **Score over time** plota o que você solicitar. Selecione **add series** e escolha um agente, um ambiente, uma avaliação e uma estatística: avg, min, max, p50, p75, p90, p95, p99, stddev ou mode. Cada série é uma linha; atribua uma **curve** própria para desenhá-la em um gráfico separado. - Abra uma sessão a partir do detalhamento para inspecionar o raciocínio por pontuação: + ![A página de avaliações: execuções recentes marcadas como customer, um gráfico de pontuação ao longo do tempo com linhas de referência em 0,5 e 0,8, e uma série calculando a média de finished_clean entre todos os agentes e ambientes.](/images/dashboard/evaluations-chart.png) - ![Uma visualização de detalhes de sessão mostrando pontuações de avaliação e raciocínio ao lado do trace completo.](/images/dashboard/session-detail.png) + Um único intervalo de tempo e um tamanho de bin se aplicam a todas as séries. Um bin fino identifica um incidente; um mais grosseiro mostra uma tendência e pode ocultar os picos que você está procurando. Um intervalo sem nenhuma pontuação aparece como uma lacuna na linha, nunca como zero, e linhas de referência marcam 0,5 e 0,8. + + Cada parte da visualização está na URL: **share** copia o link, e quem o abrir verá exatamente a comparação que você criou. ```bash @@ -28,25 +28,29 @@ As avaliações online aplicam julgamentos consistentes às sessões de agentes. fp evals --score helpfulness:0.8.. --since 7d ``` - Adicione o parâmetro global `--json` antes de `evals` para automação, por exemplo `fp --json evals --aggregate --env production`. + Adicione o flag global `--json` antes de `evals` para automação, por exemplo `fp --json evals --aggregate --env production`. -Um avaliador recebe a identidade da sessão, o ambiente, os timestamps e os eventos ordenados. Ele pode retornar chaves de pontuação numéricas com raciocínio opcional e um resumo. Avaliadores de longa duração podem retornar um job pendente e ser consultados posteriormente. +Plote **avg** e **p90** para a mesma avaliação para verificar se uma boa média está ocultando uma cauda ruim, ou a mesma avaliação para dois agentes, ou para produção e staging, comparando-os no mesmo eixo. Custos, latências e contagens de tokens, que possuem unidades, são exibidos em **Observe → metrics**, um gráfico por unidade. + +## Veja por que uma sessão teve pontuação baixa + +Abra uma sessão em **Observe → sessions**; a grade exibe as pontuações de cada sessão e permite filtrar por faixa de pontuação. O painel lateral direito da sessão começa com o resumo da avaliação, seguido de uma barra por pontuação com o raciocínio do avaliador abaixo dela. + +![Uma visão detalhada de sessão mostrando pontuações de avaliação e raciocínio ao lado do trace completo.](/images/dashboard/session-detail.png) + +## Consulte o assistente + +Faça perguntas sobre dados de avaliação em linguagem natural: "me fale sobre algumas das avaliações recentes", ou quais agentes estão com pontuações em queda. O [assistente](/pt-br/sessions/assistant) lê e analisa os resultados e responde com tabelas que você pode explorar mais a fundo; uma pergunta relevante pode se tornar uma [query](/pt-br/sessions/queries) ou um [dashboard](/pt-br/sessions/dashboards). -## Bons alvos de avaliação +![A página de avaliações ao lado do assistente, que responde à pergunta sobre avaliações recentes com um resumo de totais, status e pontuações.](/images/dashboard/evaluations-assistant.png) -- Conclusão de tarefas ou correção -- Fundamentação e risco de alucinação -- Seleção de ferramentas e eficiência no uso de ferramentas -- Conformidade com políticas ou processos -- Orçamentos de custo e latência -- Escalação humana necessária +## Monitore e aja -## Da pontuação à resposta +- **Dashboards**, em **Analyze → dashboards**, acompanham as pontuações em destaque, por agente e ambiente, para toda a organização. -Exiba as pontuações em dashboards para acompanhar tendências. Crie alertas para limites ou condições compostas. Quando uma pontuação cai em uma população, execute uma auditoria para investigar o motivo; quando a causa é uma ação repetível, implante uma política. + ![Um dashboard de qualidade mostrando pontuações médias de avaliação e tendências ao longo do tempo.](/images/dashboard/dashboard-quality.png) - - Implemente avaliações síncronas ou assíncronas com o SDK de avaliadores em Python. - \ No newline at end of file +- **Alerts** notificam você quando uma pontuação cruza um limite. Consulte [alerts](/pt-br/audits/alerts). +- Quando uma pontuação cai em muitas sessões, [execute uma auditoria](/pt-br/audits/run) para descobrir o motivo; quando a causa é uma ação repetível, [escreva uma política](/pt-br/policies/editor). \ No newline at end of file diff --git a/docs/pt-br/start/integrations/custom-agents.mdx b/docs/pt-br/start/integrations/custom-agents.mdx index bb396cc8..fd1ab4f0 100644 --- a/docs/pt-br/start/integrations/custom-agents.mdx +++ b/docs/pt-br/start/integrations/custom-agents.mdx @@ -5,9 +5,9 @@ description: "Instrumente um agente que você mesmo escreveu, ou um framework se icon: "code" --- -Para um agente que você escreveu, ou um framework sem adaptador no Failproof AI. Não há nada a instrumentar: você emite os eventos. +Para um agente que você mesmo escreveu, ou um framework para o qual Failproof AI não possui adaptador. Não há nada a instrumentar: você emite os eventos. -Esta é a mesma API que os quatro adaptadores de framework utilizam por baixo dos panos. Eles são tabelas de tradução sobre ela. +Esta é a mesma API que os quatro adaptadores de framework utilizam internamente. Eles são tabelas de tradução sobre ela. ## Instalação @@ -30,7 +30,7 @@ with failproofai_sdk.session(): # uma execução t.output = search(q) # uma chamada de ferramenta ``` -Leia de cima para baixo e o código diz exatamente o que significa: +Leia de cima para baixo e o código diz o que significa: | Envolva em | Para dizer | | --- | --- | @@ -38,15 +38,15 @@ Leia de cima para baixo e o código diz exatamente o que significa: | `agent()` | Algo está realizando trabalho — dê um nome que você reconheceria em uma lista | | `tool_call()` | Esta é uma ferramenta, e aqui está o que ela retornou | -E o que cada um realmente emite: +E o que cada um emite de fato: | Escopo | Emite | Propósito | | --- | --- | --- | -| `session()` | Nada | Vincula um id de sessão, agrupando uma execução | +| `session()` | Nada | Vincula um session id, agrupando uma execução | | `agent()` | `agent_start`, `agent_end` | Delimita uma unidade de trabalho | -| `tool_call()` | `tool_use`, `tool_result` | Delimita uma ferramenta e a mede | +| `tool_call()` | `tool_use`, `tool_result` | Delimita uma ferramenta e mede sua duração | -Tudo dentro pode omitir `session_id` e `agent_id`. Os escopos vinculam identidade em variáveis de contexto e toda chamada de evento lê de volta, então você nunca precisa passar ids pelas suas funções. +Tudo que está dentro pode omitir `session_id` e `agent_id`. Os escopos vinculam identidade em variáveis de contexto e cada chamada de evento a lê de volta, então você nunca precisa passar ids pelas suas funções. Os três funcionam com `async with` assim como com `with`. @@ -61,20 +61,20 @@ with failproofai_sdk.session(): ## Como um escopo é fechado -`agent()` trata exceções por você: +`agent()` trata exceções para você: | O que aconteceu | Eventos | Resultado | | --- | --- | --- | | Nada foi lançado | `agent_end` | `success` | | `Exception` | `error`, depois `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, depois `agent_end` | `failed` | -| `CancelledError`, `GeneratorExit` | apenas `agent_end` | `cancelled` | +| `CancelledError`, `GeneratorExit` | Apenas `agent_end` | `cancelled` | -O erro é emitido antes de `agent_end`, porque o dashboard fecha o span em `agent_end` e qualquer coisa depois disso não é atribuída a nada. Um cancelamento não é uma falha, portanto execuções canceladas não poluem a superfície de erros. A exceção sempre é relançada: um escopo nunca a engole. +O erro é emitido antes de `agent_end`, porque o dashboard fecha o span em `agent_end` e qualquer coisa depois disso não é atribuída a nada. Um cancelamento não é uma falha, então execuções canceladas não poluem a superfície de erros. A exceção sempre é relançada: um escopo nunca a engole. ## Os métodos de evento -Quinze métodos em seis famílias. A maioria vem em pares — você emite o abridor, depois o fechador, e o SDK mede o intervalo entre eles. +Quinze métodos em seis famílias. A maioria vem em pares — você emite o abridor, depois o fechador, e o SDK mede o span entre eles. | Família | Abre | Fecha | Independente | | --- | --- | --- | --- | @@ -87,7 +87,7 @@ Quinze métodos em seis famílias. A maioria vem em pares — você emite o abri | **Falhas** | — | — | `error` | - Prefira os escopos — `agent()` e `tool_call()` — sempre que possível. Eles garantem o evento de fechamento mesmo quando o corpo lança uma exceção. Use esses métodos diretamente quando o seu fluxo de controle não aninha, como uma chamada de modelo dentro de uma função auxiliar. + Prefira os escopos — `agent()` e `tool_call()` — sempre que se encaixarem. Eles garantem o evento de fechamento mesmo quando o corpo lança uma exceção. Recorra a esses métodos diretamente quando seu fluxo de controle não for aninhado, como uma chamada de modelo dentro de um helper. @@ -145,19 +145,19 @@ failproofai_sdk.event.error( | Métodos | Significado | | --- | --- | - | `human_wait` / `human_input` | O **agente perguntou a uma pessoa** — uma aprovação, uma pergunta de esclarecimento | - | `human_pause` / `human_interrupt` | Uma **pessoa agiu sobre o agente** — um botão de parada, uma pausa do operador | + | `human_wait` / `human_input` | O **agente perguntou a uma pessoa** — uma porta de aprovação, uma pergunta de esclarecimento | + | `human_pause` / `human_interrupt` | **Uma pessoa agiu sobre o agente** — um botão de parada, uma pausa do operador | - Nenhum framework sinaliza o segundo par, portanto cabe sempre a você emiti-lo. + Nenhum framework sinaliza o segundo par, então sempre cabe a você emiti-lo. - **Passe `request_id` quando chamadas de modelo ocorrem concorrentemente.** Sem ele, requisições e respostas são pareadas por ordem de chegada por agente — e chamadas concorrentes são emparelhadas incorretamente, associando cada resposta à requisição errada. + **Passe `request_id` quando chamadas de modelo rodarem concorrentemente.** Sem ele, requisições e respostas são emparelhadas na ordem de chegada por agente — e chamadas concorrentes se desemparelham, associando cada resposta à requisição errada. ## Exemplo -Um loop de chamadas de ferramenta contra a API da OpenAI, sem nenhum framework de agente: +Um loop de chamada de ferramentas contra a API da OpenAI, sem framework de agentes: ```python import json @@ -204,13 +204,13 @@ with failproofai_sdk.session(): }) ``` -Isso produz os mesmos seis tipos de evento que um adaptador geraria. A versão -completa e executável, com as definições de ferramentas, está no repositório do SDK em +Isso produz os mesmos seis tipos de evento que um adaptador forneceria. A versão +completa e executável, com as definições de ferramentas, está disponível no repositório do SDK em `docs/manual/examples/`. ## Threads e async -Variáveis de contexto propagam automaticamente para tasks do asyncio. Elas não propagam para novas threads, porque uma thread começa com um contexto vazio. +Variáveis de contexto se propagam automaticamente para tarefas asyncio. Elas não se propagam para novas threads, porque uma thread começa com um contexto vazio. ```python # asyncio: nada a fazer @@ -223,13 +223,13 @@ threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Sem `propagate()`, os eventos do worker lançam um `TypeError` informando a correção em vez de aterrissar em nenhuma sessão. Isso é intencional: um evento sem sessão é ignorado pelo ingest e respondido com `200`, que é a falha silenciosa que a camada de identidade existe para prevenir. +Sem `propagate()`, os eventos do worker lançam um `TypeError` indicando a correção, em vez de serem associados a nenhuma sessão. Isso é intencional: um evento sem sessão é ignorado pelo ingest e respondido com `200`, que é a falha silenciosa que a camada de identidade existe para evitar. ## Instrumentar um framework sem adaptador -Todo framework de agente oferece as mesmas três costuras. Mapeie-as e você terá um trace completo — os quatro adaptadores incluídos não fazem nada além disso. +Todo framework de agentes oferece as mesmas três costuras. Mapeie-as e você terá um trace completo — os quatro adaptadores fornecidos não fazem nada além disso. -| A costura | O que você escreve | O que é registrado | +| A costura | O que você escreve | O que registra | | --- | --- | --- | | A execução | `session()` + `agent()` | `agent_start`, `agent_end` | | Cada ferramenta | `tool_call()` | `tool_use`, `tool_result` | @@ -244,14 +244,14 @@ Todo framework de agente oferece as mesmas três costuras. Mapeie-as e você ter ``` - No que quer que o framework chame de wrapper ou middleware de ferramenta. + No que quer que o framework chame de wrapper de ferramenta ou middleware. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -266,20 +266,20 @@ Todo framework de agente oferece as mesmas três costuras. Mapeie-as e você ter - **Tem um boundary de nó, etapa ou middleware que vale ver?** Envolva-o em um par de hooks — `hook_triggered` / `hook_completed` — em vez de um `agent()` aninhado. `agent_id` é uma faceta de baixa cardinalidade, e uma entrada por nó o sobrecarrega. Spans de hook são renderizados da mesma forma e fornecem latência por nó. + **Tem um limite de nó, passo ou middleware que vale a pena visualizar?** Envolva-o em um par de hook — `hook_triggered` / `hook_completed` — não em um `agent()` aninhado. `agent_id` é uma faceta de baixa cardinalidade, e uma entrada por nó a satura. Spans de hook são renderizados da mesma forma e fornecem latência por nó. - **Manual e automático se compõem.** Um adaptador executando dentro de um escopo escrito à mão se junta a essa sessão e se torna filho daquele agente, então você obtém uma árvore em vez de duas — útil quando você instrumenta um framework você mesmo ao lado de um suportado. + **Manual e automático se compõem.** Um adaptador rodando dentro de um escopo escrito à mão entra nessa sessão e torna-se filho daquele agente, então você obtém uma árvore em vez de duas — útil quando você instrumenta um framework manualmente ao lado de um suportado. Dois motivos, e as três costuras acima são a resposta para ambos: - - `autogen-core` está sem manutenção desde setembro de 2025. - - AG2 não expõe um ponto de registro global equivalente aos hooks dos outros frameworks, então instrumentá-lo significa envolver cada agente em cada ponto de construção. + - `autogen-core` não é mantido desde setembro de 2025. + - O AG2 não expõe nenhum ponto de registro global equivalente aos hooks dos outros frameworks, então instrumentá-lo significa envolver cada agente em cada local de construção. - Mapear as costuras manualmente registra os mesmos eventos, com a mesma fidelidade, que um adaptador incluído faria. + Mapear as costuras manualmente registra os mesmos eventos, com a mesma fidelidade, que um adaptador fornecido faria. ## Indo mais fundo @@ -290,7 +290,7 @@ Como a gravação realmente funciona. Nada disso é necessário para começar. -Toda gravação tem a mesma forma: um span abre, o trabalho é aninhado dentro dele, e cada evento de abertura recebe um de fechamento. +Toda gravação tem a mesma forma: um span abre, o trabalho aninha dentro dele, e cada evento de abertura recebe um de fechamento. ```mermaid flowchart LR @@ -304,7 +304,7 @@ flowchart LR O **par** é a unidade. Cada evento de fechamento carrega uma duração que o SDK mede a partir do evento de abertura correspondente. -Abaixo está uma execução real por framework — capturada dos exemplos que acompanham o SDK, com o nome do modelo normalizado. Observe quanto retorna de uma única chamada. +Abaixo há uma execução real por framework — capturada a partir dos exemplos que acompanham o SDK, com o nome do modelo normalizado. Note o quanto retorna de uma única chamada. @@ -325,7 +325,7 @@ Abaixo está uma execução real por framework — capturada dos exemplos que ac 14 +5.721s agent_end LangGraph · success ``` - Nós se tornam pares de hooks, então você obtém latência por nó sem sobrecarregar a lista de agentes. + Nós se tornam pares de hook, então você obtém latência por nó sem sobrecarregar a lista de agentes. @@ -342,7 +342,7 @@ Abaixo está uma execução real por framework — capturada dos exemplos que ac 10 +5.739s agent_end crew · success ``` - O `role` de cada agente se torna o nome do seu span, então latência e gasto de tokens se decompõem por papel. + O `role` de cada agente torna-se seu nome de span, então latência e consumo de tokens se dividem por role. @@ -362,7 +362,7 @@ Abaixo está uma execução real por framework — capturada dos exemplos que ac 26 +7.038s agent_end Agent · success ``` - O próprio loop do agente está visível, não apenas suas chamadas de modelo. + O loop do agente em si fica visível, não apenas suas chamadas de modelo. @@ -377,7 +377,7 @@ Abaixo está uma execução real por framework — capturada dos exemplos que ac 8 +8.119s agent_end agent · success ``` - Sem pares de hooks: Pydantic AI não tem nó ou boundary de etapa para delimitar. + Sem pares de hook: Pydantic AI não possui limite de nó ou passo para delimitar. @@ -390,7 +390,7 @@ Abaixo está uma execução real por framework — capturada dos exemplos que ac 6 +0.000s agent_end main · success ``` - Você emite esses eventos você mesmo. Mesmos tipos de evento, mesma fidelidade — custa os pontos de chamada. + Você emite esses eventos você mesmo. Mesmos tipos de evento, mesma fidelidade — custa-lhe os pontos de chamada. @@ -398,7 +398,7 @@ Abaixo está uma execução real por framework — capturada dos exemplos que ac -**Não há evento de encerramento de sessão.** Uma sessão não é algo que você fecha — é um grupo de eventos compartilhando um `session_id`. +**Não existe evento de fim de sessão.** Uma sessão não é algo que você fecha — é um grupo de eventos que compartilham um `session_id`. O status é derivado da forma do trace: @@ -409,15 +409,15 @@ O status é derivado da forma do trace: | `error` | Nada está aberto e pelo menos um evento falhou | | `done` | Nada está aberto e nada falhou | -Portanto, uma sessão termina quando todos os pares estão fechados. Os adaptadores emitem `agent_end` por você, e durante o encerramento fecham tudo que ainda está aberto e marcam como incompleto — uma execução com falha se estabiliza como `done` com uma lacuna visível em vez de ficar presa. +Então uma sessão termina quando todos os pares são fechados. Os adaptadores emitem `agent_end` para você, e no encerramento fecham tudo que ainda estiver aberto e marcam como incompleto — uma execução com crash se resolve como `done` com uma lacuna visível, em vez de ficar pendente. - É por isso que uma sessão pode abranger duas chamadas. Um `interrupt()` do LangGraph pausa a execução, o span raiz permanece deliberadamente aberto, e a chamada de retomada o fecha. Ambas as chamadas são uma única sessão. + É por isso que uma sessão pode abranger duas chamadas. Um `interrupt()` do LangGraph pausa a execução, o span raiz permanece aberto deliberadamente, e a chamada de retomada o fecha. Ambas as chamadas são uma única sessão. - + `session_id` e `agent_id` são opcionais em todo método de evento. Quando omitidos, são resolvidos a partir do escopo envolvente: @@ -427,50 +427,50 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Passá-los explicitamente ainda funciona e tem precedência. Com nada vinculado e nada passado, a chamada lança um `TypeError` informando a correção em vez de emitir um evento sem sessão, que o ingest ignoraria respondendo com `200`. +Passá-los explicitamente ainda funciona e tem precedência. Se nada estiver vinculado e nada for passado, a chamada lança um `TypeError` indicando a correção, em vez de emitir um evento sem sessão, que o ingest ignoraria enquanto responderia `200`. -Escopos vinculam identidade em variáveis de contexto. Essas propagam para tasks do asyncio automaticamente, mas não para novas threads — envolva um worker em `failproofai_sdk.propagate()`. +Os escopos vinculam identidade em variáveis de contexto. Essas se propagam automaticamente para tarefas asyncio, mas não para novas threads — envolva um worker em `failproofai_sdk.propagate()`. -#### Quem cria qual id +#### Quem gera qual id -| Id | Criado por | Notas | +| Id | Gerado por | Observações | | --- | --- | --- | -| `session_id` | Você, ou o SDK | `session("chat-42")` é usado literalmente; quando omitido, o SDK gera um `uuid4().hex` | -| `agent_id` | Você, ou o framework | De `agent("analyst")`, um `role` do CrewAI, um `FunctionAgent.name`. Um valor com aparência de UUID é recusado e substituído | -| `tool_call_id`, `hook_id`, `request_id` | Você, ou o framework | Adaptadores reutilizam os próprios ids de execução do framework, por isso pares sobrevivem a saltos de thread | -| **Id do evento** | **Cloud, no ingest** | O SDK não emite nenhum | -| **`dedup_key`** | **Cloud, no ingest** | Um hash de org, sessão, timestamp, tipo e payload. Esta é a identidade real — faz um batch reprocessado colapsar em vez de duplicar | +| `session_id` | Você, ou o SDK | `session("chat-42")` é usado literalmente; se omitido, o SDK gera um `uuid4().hex` | +| `agent_id` | Você, ou o framework | De `agent("analyst")`, um `role` do CrewAI, um `FunctionAgent.name`. Valores com aparência de UUID são recusados e substituídos | +| `tool_call_id`, `hook_id`, `request_id` | Você, ou o framework | Adaptadores reutilizam os ids de execução do próprio framework, por isso os pares sobrevivem a saltos entre threads | +| **Event id** | **Cloud, no ingest** | O SDK não emite nenhum | +| **`dedup_key`** | **Cloud, no ingest** | Um hash de org, sessão, timestamp, tipo e payload. Esta é a identidade real — faz com que um lote reprocessado colapse em vez de duplicar | -#### Como os adaptadores resolvem `session_id` +#### Como adaptadores resolvem `session_id` O primeiro match vence: -1. Uma opção explícita `session_id` +1. Uma opção `session_id` explícita 2. Metadados por chamada 3. O escopo `session()` envolvente 4. Metadados do framework 5. O próprio id de execução do framework -Nunca é inventado enquanto um desses existe — um id sintetizado dividiria uma execução em várias sessões. +Ele nunca é inventado enquanto um desses existir — um id sintetizado dividiria uma execução entre várias sessões. #### Mantenha `agent_id` com baixa cardinalidade -É a faceta primária em toda superfície do dashboard, e uma coluna `LowCardinality(String)`. Um valor por execução degrada a coluna e preenche o dropdown de filtro com uma entrada por execução. +É a faceta principal em toda superfície do dashboard, e uma coluna `LowCardinality(String)`. Um valor por execução degrada a coluna e preenche o dropdown de filtros com uma entrada por execução. -Os adaptadores defendem essa coluna por você: +Os adaptadores protegem essa coluna para você: -| O framework entrega | Registrado como | Por quê | +| O framework entrega | Gravado como | Por quê | | --- | --- | --- | | `3f9a1c2b-…` (um UUID) | `main` | Nada legível para manter | -| Uma longa string hex pura | `main` | Mesmo motivo | +| Uma longa string hexadecimal | `main` | Igual | | `agent-3f9a1c2b-…` | `agent` | Id por execução removido, parte legível mantida | | `agent-v2` | `agent-v2` | Segmentos curtos são mantidos | -| `step-3` | `step-3` | Mesmo motivo | +| `step-3` | `step-3` | Igual | O id real é mantido em `fw_agent_id` / `fw_run_id`, onde permanece consultável sem ser uma faceta. - **Essa proteção só toca rótulos que o *framework* escolheu.** Um `agent_id` que você passa você mesmo — para `event.*` ou para `failproofai_sdk.agent(...)` — é registrado exatamente como fornecido. Reescrever silenciosamente um argumento explícito seria pior do que a cardinalidade que previne, então nomeie seus próprios spans adequadamente. + **Esta proteção só toca rótulos que o *framework* escolheu.** Um `agent_id` que você passa você mesmo — para `event.*` ou para `failproofai_sdk.agent(...)` — é gravado exatamente como fornecido. Reescrever silenciosamente um argumento explícito seria pior do que a cardinalidade que previne, então nomeie seus próprios spans adequadamente. @@ -493,12 +493,12 @@ O que cada framework registra, medido a partir das execuções acima: | Início e fim de agente | Sim | Sim | Sim | Sim | Você | | Requisição e resposta de modelo | Sim | Sim | Sim | Sim | Você | | Uso e resultado de ferramenta | Sim | Sim | Sim | Sim | Você | -| Hook disparado e concluído | Nó | Task | Etapa | — | Você | +| Hook disparado e concluído | Nó | Tarefa | Passo | — | Você | | Erro | Sim | Sim | Sim | Sim | Automático | | Espera e entrada humana | Sim | Sim | Sim | — | Você | | Pausa e retomada de agente | Sim | Sim | Sim | — | Você | -Um traço significa que o framework não tem esse conceito. `human_pause` e `human_interrupt` descrevem uma *pessoa* agindo sobre o agente, o que nenhum framework sinaliza — emita esses você mesmo. +Um traço significa que o framework não possui tal conceito. `human_pause` e `human_interrupt` descrevem uma *pessoa* agindo sobre o agente, o que nenhum framework sinaliza — emita-os você mesmo. @@ -512,26 +512,26 @@ Um evento nunca chega sozinho. Um abre um span, outro o fecha, e o evento de fec | `model_request` | `model_response` | tokens, `stop_reason`, latência | | `tool_use` | `tool_result` | `output` ou `error`, duração | | `hook_triggered` | `hook_completed` | `outcome`, duração | -| `agent_pause` | `agent_resume` | quanto tempo durou a pausa | +| `agent_pause` | `agent_resume` | quanto tempo a pausa durou | | `human_wait` | `human_input` | a resposta e quanto tempo a pessoa levou | - Um evento de abertura sem evento de fechamento correspondente é um span que nunca termina. A sessão é renderizada como ainda em execução, para sempre, e sua duração ativa continua crescendo. Este é o modo de falha a observar quando você instrumenta manualmente. + Um evento de abertura sem evento de fechamento é um span que nunca termina. A sessão é renderizada como ainda em execução, para sempre, e sua duração ativa continua crescendo. Este é o modo de falha a observar quando você instrumenta manualmente. #### Regras de correlação - Reutilize o mesmo `tool_call_id`, `hook_id`, `pause_id` ou `input_id` para o evento de conclusão correspondente. - O SDK calcula `duration_ms` para `tool_result`, `hook_completed`, `agent_resume` e `human_input`. Passá-lo nesses métodos lança `ValueError`. -- `duration_ms` **é** aceito em `model_response`, porque somente o chamador conhece a latência real do provedor. Deve ser um inteiro — um float lança `ValueError` no ponto de chamada, porque o servidor lê a coluna como um inteiro de 32 bits sem sinal e armazenaria NULL para qualquer outra coisa. +- `duration_ms` **é** aceito em `model_response`, porque apenas quem chama conhece a latência real do provedor. Deve ser um inteiro — um float lança `ValueError` no ponto de chamada, porque o servidor lê a coluna como um inteiro sem sinal de 32 bits e armazenaria NULL para qualquer outro valor. - Chaves de correlação têm escopo por tipo e sessão, então uma chamada de ferramenta e um hook podem compartilhar um id com segurança, e duas sessões concorrentes podem reutilizar os mesmos ids sem colisão. Elas não têm escopo por agente: um par aberto sob um agente e fechado sob outro ainda correlaciona, que é o caso comum em frameworks multi-agente. -- `request_id` pareia `model_request` com `model_response`. Sem ele, eventos de modelo são pareados em ordem por agente, então chamadas concorrentes são emparelhadas incorretamente. -- Um par dividido entre processos ainda correlaciona no downstream, mas o SDK não consegue calcular sua duração em processo. -- O mapa pendente comporta no máximo 10.000 inícios e descarta a entrada mais antiga quando cheio. +- `request_id` emparelha `model_request` com `model_response`. Sem ele, eventos de modelo são emparelhados em ordem por agente, então chamadas concorrentes se desemparelham. +- Um par dividido entre processos ainda correlaciona no downstream, mas o SDK não pode calcular sua duração em processo. +- O mapa pendente armazena no máximo 10.000 inícios e remove a entrada mais antiga quando cheio. - + Instalar `failproofai-sdk` instala tudo, incluindo os quatro adaptadores. Os extras instalam o **framework**, não o adaptador. @@ -540,16 +540,16 @@ import failproofai_sdk # não carrega nada fora da biblioteca padrão failproofai_sdk.instrument() # importa apenas os adaptadores que você realmente precisa ``` -`import failproofai_sdk` é contratualmente zero-dependência, aplicado por um teste que instala o wheel construído com `--no-deps` e outro que prova que nenhum framework chega a `sys.modules`. +`import failproofai_sdk` é contratualmente de dependência zero, verificado por um teste que instala o wheel compilado com `--no-deps` e outro que prova que nenhum framework alcança `sys.modules`. - Não existe atributo `failproofai_sdk.crewai`. Adaptadores são deliberadamente não expostos no pacote de nível superior: tocar em um importaria o framework como efeito colateral de um acesso de atributo, quebrando a promessa de zero-dependência. Use `instrument()`. + Não existe atributo `failproofai_sdk.crewai`. Os adaptadores são deliberadamente não expostos no pacote de nível superior: acessar um importaria o framework como efeito colateral de um acesso a atributo, quebrando a promessa de dependência zero. Use `instrument()`. ```python failproofai_sdk.instrument() # todo framework já importado failproofai_sdk.instrument("crewai") # exatamente um, pelo nome -failproofai_sdk.uninstrument("crewai") # desfazer +failproofai_sdk.uninstrument("crewai") # desfaz ``` | Nome | Também aceita | @@ -559,7 +559,7 @@ failproofai_sdk.uninstrument("crewai") # desfazer | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -A detecção automática lê `sys.modules`, não a lista de pacotes instalados, então um framework que você instalou mas nunca importou não é instrumentado e nunca é importado por você. Para ver o que está conectado: +A detecção automática lê `sys.modules`, não a lista de pacotes instalados, então um framework que você tem instalado mas nunca importou não é instrumentado e nunca é importado em seu nome. Para ver o que está conectado: ```python from failproofai_sdk.integrations import active, available @@ -571,24 +571,24 @@ active() # ('langchain',) **`instrument("crewai")` em uma máquina sem CrewAI não lança exceção.** Registra um aviso e retorna `()`, então um framework ausente nunca derruba um processo que também instrumenta outros. - O aviso carrega o `ImportError` subjacente, e essa mensagem indica o comando de instalação exato — então a correção está nos seus logs, não escondida. + O aviso carrega o `ImportError` subjacente, e essa mensagem indica o comando exato de instalação — então a correção está nos seus logs, não oculta. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Defina `FAILPROOFAI_SDK_STRICT=1` para que ele lance em vez disso. Esse flag é lido **uma vez e armazenado em cache**, então exporte-o antes de seu processo iniciar em vez de defini-lo durante a execução. + Defina `FAILPROOFAI_SDK_STRICT=1` para que ele lance uma exceção em vez disso. Essa flag é lida **uma vez e armazenada em cache**, então exporte-a antes de seu processo iniciar em vez de defini-la durante a execução. - **`instrument()` deve vir *depois* do import do seu framework.** A detecção automática lê `sys.modules`, então uma chamada simples antes do import não encontra nada, não instala nada e retorna `()`. + **`instrument()` deve vir *depois* da importação do seu framework.** A detecção automática lê `sys.modules`, então uma chamada sem argumentos acima do import não encontra nada, não instala nada e retorna `()`. ```python Wrong import failproofai_sdk -failproofai_sdk.instrument() # sys.modules ainda não tem langchain -> () +failproofai_sdk.instrument() # sys.modules não tem langchain ainda -> () import langchain # tarde demais, nada está conectado ``` @@ -597,18 +597,18 @@ import langchain # tarde demais, nada está conectado import langchain # importe o framework primeiro import failproofai_sdk -failproofai_sdk.instrument() # encontra ele -> ('langchain',) +failproofai_sdk.instrument() # encontra -> ('langchain',) ``` ```python Right, order-proof import failproofai_sdk -# Nomear o framework importa o adaptador sob demanda, então funciona de qualquer lugar. +# Nomear importa o adaptador sob demanda, então isso funciona de qualquer lugar. failproofai_sdk.instrument("langchain") ``` -Erre isso e o processo roda com o SDK importado, o adaptador aparentemente instalado, e **nenhum evento emitido**. Ele registra um aviso dizendo exatamente isso — então verifique seus logs primeiro quando uma execução não registra nada. +Errar isso e o processo roda com o SDK importado, o adaptador aparentemente instalado, e **nenhum evento emitido**. Ele registra um aviso dizendo exatamente isso — então verifique seus logs primeiro quando uma execução não registrar nada. @@ -623,80 +623,78 @@ flowchart LR E -->|"HTTPS"| F["Cloud"] ``` -| Estágio | Função | Executa em | +| Estágio | Função | Roda em | | --- | --- | --- | | Adaptador | Traduz um callback do framework em um dos 15 tipos de evento | Seu processo | | Writer | Enfileira, agrupa, escreve JSONL atomicamente | Seu processo, thread em background | | Spool | Handoff durável, sobrevive ao encerramento do seu processo | Disco local | -| Daemon | Monitora o spool, envia batches, exclui o que enviou | Sua máquina | -| Ingest | Atribui um id de linha e chave de dedup, promove colunas consultáveis | Cloud | +| Daemon | Monitora o spool, envia lotes, deleta o que enviou | Sua máquina | +| Ingest | Atribui id de linha e chave de dedup, promove colunas consultáveis | Cloud | O spool é o que torna isso seguro: seu agente nunca bloqueia na rede, e uma interrupção do Cloud significa um diretório crescendo em vez de eventos perdidos. -Cada flush escreve um arquivo de batch, `.tmp` primeiro, depois `fsync`, depois um rename atômico: +Cada flush escreve um arquivo de lote, `.tmp` primeiro, depois `fsync`, depois um rename atômico: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -O daemon só coleta `.jsonl`, então nunca pode ler um arquivo escrito parcialmente. O nome do arquivo carrega timestamp, id de processo e número de sequência, então dois processos fazendo flush no mesmo milissegundo não colidem. A fila está limitada a 10.000 eventos; além disso, descarta os mais antigos e registra um log. +O daemon só lê `.jsonl`, então nunca pode ler um arquivo parcialmente escrito. O nome do arquivo carrega um timestamp, id de processo e número de sequência, então dois processos fazendo flush no mesmo milissegundo não podem colidir. A fila tem capacidade máxima de 10.000 eventos; além disso, descarta os mais antigos e registra um log. - **`collector.redact` tem padrão `minimal` para eventos do SDK também.** O SDK - limpa antes de escrever um batch em disco, e o daemon repete a mesma - passagem determinística antes do upload para que batches de SDKs mais antigos sejam protegidos. + **`collector.redact` não se aplica aos seus eventos do SDK.** Ele nunca os vê. -O daemon lê cada batch e aplica redação em memória antes do upload. Ele -não reescreve o arquivo de spool que leu. +O daemon **envia** seus lotes. Ele não os abre nem os reescreve. -| Eventos | Escritos por | Onde a redação minimal é executada | +| Eventos | Escritos por | Redacted por `collector.redact`? | | --- | --- | --- | -| Transcrições de sessão CLI | O daemon | Antes do daemon escrever o batch | -| Atividade de hook | O daemon | Antes do daemon escrever o batch | -| **Tudo que o SDK emite** | **Seu processo** | **Antes do SDK escrever o batch e novamente antes do upload do daemon** | +| Transcrições de sessão CLI | O daemon | Sim | +| Atividade de hook | O daemon | Sim | +| **Tudo que o SDK emite** | **Seu processo** | **Não** | -Defina `collector.redact` como `off` apenas quando payloads literais forem um requisito explícito; -o SDK e o daemon honram essa configuração. A redação minimal detecta chaves de API comuns, bearer tokens, JWTs e atribuições de segredos. Ela não consegue identificar prosa sensível arbitrária. +A redação roda onde o daemon *escreve* seus próprios eventos — não onde os lotes são *enviados*. Então um prompt ou argumento de ferramenta contendo uma chave de API ainda a contém na chegada. + +Isso é intencional. Estas são suas próprias chamadas de instrumentação, e reescrevê-las em trânsito significaria que os eventos que você recebe não são os eventos que você emitiu. - **Você controla payloads na fonte, em dois lugares:** + **Você controla os payloads na fonte, em dois lugares:** - - Desative a captura de conteúdo no adaptador. **O nome da opção é diferente, e um adaptador não tem nenhuma** — este não é um switch universal único: + - Desative a captura de conteúdo no adaptador. **O nome da opção é diferente, e um adaptador não tem nenhuma** — este não é um interruptor universal único: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **nenhum switch de conteúdo**; `session_id` é a única opção que ele lê, então prompts e completions são sempre gravados. + - CrewAI — **sem opção de conteúdo alguma**; `session_id` é a única opção que ele lê, então prompts e completions são sempre gravados. - `instrument()` descarta opções que um adaptador não lê, então passar o nome errado não lança nada e não muda nada. + `instrument()` descarta opções que um adaptador não lê, então passar o nome errado não lança nada e não altera nada. - Não passe o segredo para `input=` em primeiro lugar. - `collector.redact` é defesa em profundidade, não substituto para nenhum dos dois. + `collector.redact` não é substituto para nenhum dos dois. **Um diretório de spool vazio é o estado saudável.** Não o use para verificar a entrega. -O daemon exclui cada batch em milissegundos após enviá-lo, então um `ls` compete com o coletor e mostra uma fração do que você emitiu — indistinguível de um SDK que não registrou nada. +O daemon deleta cada lote em milissegundos após enviá-lo, então um `ls` compete com o collector e mostra uma fração do que você emitiu — indistinguível de um SDK que não gravou nada. -Para confirmar que os eventos realmente chegaram, verifique o dashboard. Para observar o spool se enchendo, pare o daemon primeiro. +Para confirmar que os eventos realmente chegaram, verifique o dashboard. Para observar o spool enchendo, pare o daemon primeiro. -Todo callback executa dentro de um wrapper cujo único trabalho é relançar, então sua chamada fica em exatamente um `try` e tudo que o SDK faz acontece fora dele. +Todo callback roda dentro de um wrapper cuja única função é relançar, então sua chamada fica em exatamente um `try` e tudo que o SDK faz acontece fora dele. | O que acontece | Resultado | | --- | --- | | Um hook lança | Registrado uma vez com seu traceback. Sua chamada não é afetada | -| O mesmo hook lança três vezes | Esse hook é desabilitado pelo restante do processo, com uma linha de erro | +| O mesmo hook lança três vezes | Aquele hook é desabilitado pelo resto do processo, com uma linha de erro | | `FAILPROOFAI_SDK_STRICT=1` está definido | A exceção é relançada em vez disso | -| Uma versão do framework está fora do intervalo testado | Avisa uma vez, instrumenta mesmo assim | -| Uma única capacidade está ausente | Apenas esse hook é desabilitado, nunca o adaptador inteiro | +| Uma versão de framework está fora do intervalo testado | Avisa uma vez, instrumenta mesmo assim | +| Uma única capacidade está ausente | Apenas aquele hook é desabilitado, nunca o adaptador inteiro | -O padrão é correto em produção e errado durante a depuração, porque só pode provar que não travou. Defina `FAILPROOFAI_SDK_STRICT=1` para tornar uma falha engolida barulhenta. +O padrão é correto em produção e errado durante debug, porque só pode provar "não crashou". Defina `FAILPROOFAI_SDK_STRICT=1` para tornar uma falha engolida visível. @@ -706,23 +704,23 @@ O padrão é correto em produção e errado durante a depuração, porque só po - Um evento de abertura não tem evento de fechamento correspondente: um `model_request` sem `model_response`, ou um `tool_use` sem `tool_result`. Use os escopos, que garantem o par mesmo quando o corpo lança uma exceção. Se você chamar os métodos de evento diretamente, use `try` e `finally`. + Um evento de abertura não tem evento de fechamento: um `model_request` sem `model_response`, ou um `tool_use` sem `tool_result`. Use os escopos, que garantem o par mesmo quando o corpo lança uma exceção. Se você chamar os métodos de evento diretamente, use `try` e `finally`. - - Ele é medido a partir do evento de abertura correspondente, então é rejeitado em `tool_result`, `hook_completed`, `agent_resume` e `human_input`. É aceito em `model_response`, porque somente você conhece a latência real do provedor, e deve ser um inteiro. + + É medido a partir do evento de abertura correspondente, então é rejeitado em `tool_result`, `hook_completed`, `agent_resume` e `human_input`. É aceito em `model_response`, porque apenas você conhece a latência real do provedor, e deve ser um inteiro. - - A thread nunca herdou o contexto. Envolva o callable em `failproofai_sdk.propagate()`. Consulte [Threads e async](#threads-and-async). + + A thread nunca herdou o contexto. Envolva o callable em `failproofai_sdk.propagate()`. Veja [Threads e async](#threads-and-async). - Campos extras são mesclados por último, então um nomeado como um campo real, como `model` ou `outcome`, o sobrescreveria e alteraria uma coluna armazenada. Use um namespace para os seus; os adaptadores usam o prefixo `fw_`. + Campos extras são mesclados por último, então um nomeado como um campo real, como `model` ou `outcome`, o sobrescreveria e alteraria uma coluna armazenada. Use um namespace nos seus; os adaptadores usam o prefixo `fw_`. - `agent_id` é uma faceta de baixa cardinalidade e você colocou um id de execução nele. Use um nome de papel ou nó e coloque o id real em um campo de payload. + `agent_id` é uma faceta de baixa cardinalidade e você colocou um id de execução nela. Use um nome de role ou nó e coloque o id real em um campo de payload. @@ -730,7 +728,7 @@ O padrão é correto em produção e errado durante a depuração, porque só po - Pares, ids, ciclo de vida de sessão e entrega. + Pares, ids, ciclo de vida da sessão e entrega. Siga a causalidade pela sessão que você acabou de capturar. diff --git a/docs/pt-br/start/quickstart.mdx b/docs/pt-br/start/quickstart.mdx index a719882e..e78a33af 100644 --- a/docs/pt-br/start/quickstart.mdx +++ b/docs/pt-br/start/quickstart.mdx @@ -4,14 +4,14 @@ description: "Capture uma sessão de agente, encontre uma falha e comece a preve icon: "zap" --- -Este início rápido configura uma máquina para reportar sessões, executa uma auditoria e implanta uma política. Use a skill para configurar o Failproof AI, ou siga as etapas manuais. +Este início rápido faz uma máquina reportar sessões, executa uma auditoria e implanta uma política. Use a skill para configurar o Failproof ou siga os passos manuais. -**Qual caminho é o seu?** Se o seu agente roda em um dos 12 [harnesses](/pt-br/reference/harnesses) suportados — uma CLI de codificação ou um gateway como Hermes ou OpenClaw — siga os passos abaixo; você precisa do Node.js 20.9 ou superior. Se o seu agente não tem harness, instrumente-o com o [Python SDK](/pt-br/reference/custom-agents) para rastreamento e auditorias, e então retome em [Execute sua primeira verificação de falha](/pt-br/start/first-audit); a aplicação de políticas nesse caminho requer um hook no seu runtime. +**Qual caminho é o seu?** Se o seu agente roda em um dos 12 [harnesses](/pt-br/reference/harnesses) suportados — uma CLI de codificação, ou um gateway como Hermes ou OpenClaw — siga os passos abaixo; você precisará do Node.js 20.9 ou superior. Se o seu agente não possui harness, instrumente-o com o [Python SDK](/pt-br/reference/custom-agents) para rastreamento e auditorias, depois retome em [Execute sua primeira verificação de falhas](/pt-br/start/first-audit); a aplicação de políticas nesse caminho requer um hook no seu runtime. - + ```bash npx skills add FailproofAI/skills ``` @@ -28,26 +28,32 @@ Este início rápido configura uma máquina para reportar sessões, executa uma ## Antes de começar -1. Abra o [painel do Failproof AI](https://app.befailproof.ai) e crie uma conta ou entre com seu e-mail de trabalho. +1. Abra o [dashboard do Failproof AI](https://app.befailproof.ai) e crie uma conta ou faça login com seu e-mail corporativo. 2. Vá em **Administration → Keys** e crie uma chave com `events:add` e `policies:pull`. -3. Copie o segredo de uso único e armazene-o na máquina de destino: +3. Copie o segredo de uso único e leia-o em um shell na máquina de destino. `read -s` solicita a entrada em um prompt que não exibe o que é digitado, portanto ele nunca aparece em um comando: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` - ## Instalar + ## Instalação - + ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - Transcrições de sessões são enviadas por padrão. Adicione `--no-transcripts` para reportar atividade de hooks e decisões de políticas sem o conteúdo das transcrições. + Esse único comando representa toda a configuração: instala o daemon local (root uma vez), conecta hooks em toda CLI de agente encontrada e conecta esta máquina ao Cloud. Passar a chave pela variável de ambiente em vez de `--token` mantém-a fora do `ps`, onde qualquer usuário da máquina pode ler os argumentos de um comando. Isso não a mantém fora do histórico do shell — ler com `read -s` é o que faz isso. Em CI, injete-a como um segredo mascarado e mantenha o rastreamento do shell (`set -x`) desativado, ou o trace a exibirá. - Se esta máquina já possui histórico de agente, visualize e importe os últimos sete dias, depois aguarde a entrega ser concluída. Pule esta etapa em uma máquina nova. + Transcrições de sessão são enviadas por padrão. Adicione `--no-transcripts` para reportar a atividade de hooks e decisões de políticas sem o conteúdo das transcrições. + + + Não utilize `failproofai config --connect ` aqui. Esse flag registra uma máquina que **já** está configurada e retorna imediatamente — sem daemon, sem hooks — portanto a máquina apareceria no Cloud sem coletar nem aplicar nada. + + + Se esta máquina já tem histórico de agentes, pré-visualize e importe os últimos sete dias, depois aguarde a entrega ser concluída. Pule este passo em uma máquina nova. ```bash failproofai backfill --since 7d --dry-run @@ -57,28 +63,39 @@ export FAILPROOFAI_KEY="" Abra **Sessions** no Failproof AI e selecione uma sessão importada. - - Isso conecta o Failproof AI ao seu harness e instala as 39 políticas integradas. Use-as para visualizar decisões de políticas locais e testar a aplicação antes que o Failproof AI audite suas sessões e crie políticas para seus agentes. - - Deixe o instalador detectar seu harness automaticamente, ou especifique um explicitamente. Qualquer um dos 12 é um valor válido para `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + O passo anterior já conectou todos os CLIs de agente detectados. Execute-o novamente para um harness específico quando necessário, ou para adicionar um harness instalado posteriormente. Cada um dos 12 é um valor válido para `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # uma CLI de codificação failproofai policies --install --cli hermes --scope user # um gateway Slack/Telegram ``` - O bloqueio de uma chamada de ferramenta antes de sua execução é verificado em todos os 12. Os gates de fim de turno são verificados em 8 — consulte a [capacidade de aplicação](/pt-br/reference/harnesses#enforcement-capability) para a matriz por harness. + O bloqueio de uma chamada de ferramenta antes de ela ser executada é verificado em todos os 12. Gates de fim de turno são verificados em 8 — consulte a [capacidade de aplicação](/pt-br/reference/harnesses#enforcement-capability) para a matriz por harness. + + + Conectar hooks não ativa nenhuma política. A configuração intencionalmente não escolhe nenhuma — essa decisão é sua — então pegue um pacote: + + ```bash + failproofai policies add FailproofAI/policies + ``` + + O pacote é baixado do seu release no GitHub, verificado por checksum e fixado na tag exata resolvida. Ele contém 38 políticas e ativa as 10 que seu manifesto marca como seguras para habilitar sem supervisão. Use-as para visualizar decisões de políticas locais e experimentar a aplicação antes que o Failproof AI audite suas sessões e escreva políticas para seus agentes. + + Leia qualquer pacote antes de adotá-lo com `failproofai policies show /`, e consulte [pacotes de políticas](/pt-br/policies/packs) para adotar apenas parte de um. + + Até que isso seja executado, a única coisa aplicando regras é `block-failproofai-commands` — a proteção sempre ativa que impede um agente de desligar o Failproof AI. `failproofai policies` lista o que está ativo. - - Siga [Execute sua primeira verificação de falha](/pt-br/start/first-audit). Use um objetivo concreto como "encontrar sessões em que o agente tentou novamente uma ferramenta com falha sem mudar sua abordagem." + + Siga [Execute sua primeira verificação de falhas](/pt-br/start/first-audit). Use um objetivo concreto, como "encontrar sessões em que o agente tentou novamente uma ferramenta com falha sem mudar sua abordagem." - - Siga [Previna sua primeira falha com uma política](/pt-br/start/first-policy). Comece no modo de observação, inspecione as correspondências e então aplique a versão revisada. + + Siga [Previna sua primeira falha com uma política](/pt-br/start/first-policy). Comece no modo de observação, inspecione as correspondências e depois aplique a versão revisada. - Execute `failproofai config --status`. Uma configuração saudável reporta a conexão com a nuvem, o estado do daemon e se a aplicação de políticas está pausada. + Execute `failproofai config --status`. Uma configuração saudável reporta a conexão com o cloud, o estado do daemon e se a aplicação de políticas está pausada. \ No newline at end of file diff --git a/docs/pt-br/start/setup.mdx b/docs/pt-br/start/setup.mdx index cd204789..2c9d99c1 100644 --- a/docs/pt-br/start/setup.mdx +++ b/docs/pt-br/start/setup.mdx @@ -6,19 +6,23 @@ icon: "waypoints" - Instale hooks e políticas em uma máquina. Use esta opção quando precisar de proteções imediatas sem enviar dados de sessão para a Cloud. + Configure uma máquina sem chave Cloud e utilize um pacote de políticas. Use esta opção quando precisar de proteções imediatas sem enviar dados de sessão para a Cloud. Adicione sessões centralizadas, auditorias, avaliações online, dashboards, alertas e implantação de políticas para toda a frota. - Utilize controles organizacionais, chaves com escopo definido, infraestrutura privada e requisitos de segurança específicos para cada implantação. + Use controles organizacionais, chaves com escopo definido, infraestrutura privada e requisitos de segurança específicos para cada implantação. +## Aplicar localmente + +Execute `failproofai config` sem uma chave e, em seguida, adicione um pacote com `failproofai policies add FailproofAI/policies`. No terminal, selecione **Not now — stay local** quando a configuração perguntar sobre a conexão com a Cloud; se não houver terminal e nenhum `FAILPROOFAI_CLOUD_TOKEN`, o sistema permanecerá local automaticamente. O daemon e os hooks aplicam as políticas na máquina e nenhum dado de sessão é enviado para a Cloud. Para conectar posteriormente, siga os passos abaixo. + ## Caminho recomendado para produção -1. Conecte uma máquina de não-produção com a captura de transcrições habilitada. +1. Conecte uma máquina fora de produção com a captura de transcrições habilitada. 2. Verifique sessões e avaliações na Cloud. 3. Crie uma auditoria para um modo de falha conhecido. 4. Implante a primeira política em modo de observação. @@ -28,41 +32,58 @@ icon: "waypoints" - 1. Vá em **Administração → Chaves** e crie uma chave com `events:add` e `policies:pull`. + 1. Acesse **Administration → Keys** e crie uma chave com `events:add` e `policies:pull`. 2. Copie o segredo de uso único para a máquina de destino. - 3. Após executar o comando de conexão da CLI, vá em **Admin → enforcement** e confirme que a máquina aparece. - 4. Vá em **Observar → Eventos** e confirme que o primeiro evento chega. + 3. Após executar o comando de conexão da CLI, acesse **Admin → enforcement** e confirme que a máquina aparece na lista. + 4. Acesse **Observe → Events** e confirme que o primeiro evento chega. O painel de chaves exibe as duas permissões necessárias para uma máquina conectada: ingestão de eventos e entrega de políticas. ![O painel de criação de chave de API usado para conceder permissões de ingestão de eventos e entrega de políticas.](/images/dashboard/key-create.png) - Após a conexão, a máquina deve aparecer em enforcement com o estado de política desejado e o estado reportado. + Após a conexão, a máquina deve aparecer na seção de aplicação com o estado de política desejado e o estado reportado. - ![A frota de Enforcement com uma máquina registrada expandida para mostrar o estado de política desejado e o status de implantação.](/images/dashboard/enforcement-fleet.png) + ![A frota de aplicação com uma máquina inscrita expandida para mostrar o estado de política desejado e o status de implantação.](/images/dashboard/enforcement-fleet.png) - O primeiro evento recebido confirma que o daemon consegue entregar dados à Cloud, independentemente da implantação de políticas. + O primeiro evento recebido confirma que o daemon consegue enviar dados para a Cloud, independentemente da implantação de políticas. - ![O stream de eventos em tempo real mostrando eventos recentes de agente, modelo e ferramenta.](/images/dashboard/events-stream-current.png) + ![O fluxo de eventos ao vivo mostrando eventos recentes de agente, modelo e ferramenta.](/images/dashboard/events-stream-current.png) - Continue somente após a máquina e seu primeiro evento estarem visíveis. + Prossiga somente após a máquina e seu primeiro evento estarem visíveis. + Leia o segredo de uso único no shell. O `read -s` solicita a entrada em um prompt que não exibe o que foi digitado, portanto ele nunca aparece em um comando ou no histórico do shell: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Em seguida, configure a máquina, escolha suas políticas e atribua um nome a ela: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` + O `failproofai config` realiza toda a configuração — daemon, hooks para cada CLI de agente encontrada e a conexão com a Cloud — e não escolhe nenhuma política inicialmente, o que é para isso que serve o segundo comando. + + O rótulo é definido **após** a conexão, não durante: `failproofai config --machine-label ` renomeia uma máquina que já está conectada; em uma máquina não conectada, o comando não faz nada além de informar isso. + Adicione `--no-transcripts` quando o conteúdo das transcrições precisar permanecer local. + + Em ambientes de CI, defina `FAILPROOFAI_CLOUD_TOKEN` a partir do repositório de segredos em vez de usar `read -s`, e mantenha o rastreamento do shell (`set -x`) desativado, pois o rastreamento imprime a chave. + + + Em uma máquina que **já está** configurada, `failproofai config --connect ` apenas a inscreve e nada mais. Não use essa forma para uma primeira instalação: o comando retorna antes de o daemon ou qualquer hook estar em funcionamento, deixando uma máquina que aparece na Cloud mas não coleta nem aplica nada. + -A conexão com a Cloud verifica a ingestão de eventos e a entrega de políticas de forma independente. Por isso, uma chave pode ser válida, mas estar faltando uma permissão obrigatória. Use `failproofai config --status` para verificar qual capacidade está configurada. +A conexão com a Cloud verifica a ingestão de eventos e a entrega de políticas de forma independente. Portanto, uma chave pode ser válida, mas estar sem uma permissão necessária. Use `failproofai config --status` para verificar qual capacidade está configurada. - A configuração da Cloud grava credenciais locais somente após a capacidade relevante ser verificada com sucesso. Uma verificação com falha não deixa a máquina com aparência de conectada quando não está. + A configuração da Cloud grava as credenciais locais somente após a capacidade relevante ser verificada com sucesso. Uma verificação com falha não deixa a máquina aparentando estar conectada quando não está. \ No newline at end of file diff --git a/docs/ru/admin/keys-and-permissions.mdx b/docs/ru/admin/keys-and-permissions.mdx index fc507a40..0b0e4ba5 100644 --- a/docs/ru/admin/keys-and-permissions.mdx +++ b/docs/ru/admin/keys-and-permissions.mdx @@ -4,26 +4,26 @@ description: "Создавайте API-ключи с ограниченной о icon: "key-round" --- -API-ключи принадлежат организации и имеют явные разрешения. Используйте отдельные ключи для приема событий агента, доставки политик, оценщиков, CI-автоматизации и административных скриптов. +API-ключи принадлежат организации и содержат явные разрешения. Используйте отдельные ключи для приема событий агента, доставки политик, оценивателей, автоматизации CI и административных скриптов. ## Создание и ротация ключа - 1. Перейдите в **Administration → Keys**, выберите **new key** и введите имя рабочей нагрузки. - 2. Выберите набор разрешений и корректируйте отдельные разрешения только если предустановка недостаточна. - 3. Создайте ключ и немедленно скопируйте его одноразовый секрет. - 4. Откройте ключ позже, чтобы обновить разрешения, отключить его или переформировать секрет. + 1. Перейдите в **Administration → Keys**, выберите **new key** и введите название рабочей нагрузки. + 2. Выберите набор разрешений и настройте отдельные разрешения только если предустановки недостаточно. + 3. Создайте ключ и скопируйте его одноразовый секрет немедленно. + 4. Откройте ключ позже, чтобы обновить права, отключить его или переинициализировать секрет. - Окно создания — это место, где вы выбираете наиболее узкие разрешения, требуемые рабочей нагрузкой. + Окно создания — это место, где вы выбираете самые узкие права, требуемые рабочей нагрузкой. - ![Ящик нового API-ключа с предустановками разрешений и отдельными разрешениями.](/images/dashboard/key-create.png) + ![Окно создания нового API-ключа с предустановками разрешений и отдельными правами.](/images/dashboard/key-create.png) После создания страница Keys показывает постоянные метаданные и действия управления. Одноразовый секрет больше не отображается. - ![Страница API Keys, показывающая разрешения ключа, время создания и действия для переформирования и отключения.](/images/dashboard/api-keys.png) + ![Страница API Keys, показывающая разрешения ключа, время создания, а также действия переинициализации и отключения.](/images/dashboard/api-keys.png) - Используйте этот список для регулярного проверки разрешений и отключения ключей, которые больше не соответствуют активной рабочей нагрузке. + Используйте этот список, чтобы регулярно проверять права и отключать ключи, которые больше не соответствуют активной рабочей нагрузке. ```bash @@ -36,25 +36,25 @@ API-ключи принадлежат организации и имеют яв fp keys disable production-agents ``` - Перенаправляйте или захватывайте вывод создания/переформирования безопасно; секрет возвращается один раз. + Перенаправьте или захватите результаты создания/переинициализации безопасно; секрет возвращается один раз. -Два разрешения, требуемые подключенной машиной Failproof AI, независимы друг от друга: +Два разрешения, требуемые подключенной машиной Failproof AI, независимы: -- `events:add` отправляет события и данные сеанса. -- `policies:pull` извлекает назначенные развертывания политик. +- `events:add` отправляет события и данные сессии. +- `policies:pull` получает назначенные развертывания политик. -Секреты ключей отображаются при создании или переформировании. Сохраняйте их в менеджере секретов и ротируйте без повторного использования интерактивных учетных данных оператора. +Секреты ключей отображаются при создании или переинициализации. Сохраняйте их в менеджере секретов и ротируйте их без повторного использования интерактивных учетных данных оператора. ## Каталог разрешений | Область | Разрешения | | --- | --- | | Events | `events:add`, `events:read` | -| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` только для интерактивных сеансов | +| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` только для интерактивной сессии | | Users | `users:create`, `users:read`, `users:update`, `users:delete` | -| Evaluations | `evaluations:read`, `evaluations:trigger` | +| Evaluations | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | | Dashboards | `dashboards:read`, `dashboards:write`, `dashboards:delete` | | Queries | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | | Assistant | `agent:use` | @@ -65,10 +65,10 @@ API-ключи принадлежат организации и имеют яв | Policies | `policies:read`, `policies:write`, `policies:pull` | | Usage | `usage:read` | -`orgs:admin` зарезервирован для оператора экземпляра и не может быть предоставлен ключу организации или обычному члену. Устаревшие токены `incidents:*` и `alerts:ack` принимаются для совместимости и нормализуются к текущим разрешениям `issues:*`. +`orgs:admin` зарезервировано для оператора экземпляра и не может быть предоставлено ключу организации или обычному члену. Устаревшие токены `incidents:*` и `alerts:ack` принимаются для совместимости и нормализуются к текущим разрешениям `issues:*`. -Встроенные наборы разрешений — это `read-only`, `standard` и `admin`. `standard` добавляет триггерирование оценок, выполнение запросов, ответ на проблемы и использование ассистента к разрешениям для чтения. Создание ключа удаляет разрешения только для людей, даже если набор разрешений их содержит. +Встроенные наборы разрешений: `read-only`, `standard` и `admin`. `standard` добавляет запуск оценок, выполнение запросов, ответы на проблемы и использование ассистента к разрешениям на чтение. Создание ключа удаляет права только для человека, даже если набор разрешений их содержит. - Ключи с областью действия экземпляра могут выбирать организацию с помощью заголовка `X-AgentEye-Org`. Устанавливайте его явно при развертывании нескольких организаций; его отсутствие может выбрать организацию по умолчанию. + Ключи с областью действия экземпляра могут выбирать организацию с помощью заголовка `X-AgentEye-Org`. Устанавливайте его явно при развертываниях с несколькими организациями; его отсутствие может выбрать организацию по умолчанию. \ No newline at end of file diff --git a/docs/ru/evaluations/deploy.mdx b/docs/ru/evaluations/deploy.mdx new file mode 100644 index 00000000..dc841f68 --- /dev/null +++ b/docs/ru/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "Развернуть и версионировать оценку" +description: "Разверните неизменяемую версию, посмотрите, что активно, опубликуйте новые версии, откатитесь назад и оцените уже имеющиеся сессии." +icon: "cloud-upload" +--- + +## Развернуть + +Выберите **deploy `@`** в нижней части страницы разработки. После публикации версия становится неизменяемой: с этого момента каждая завершившаяся сессия, к которой применяется условие, оценивается с её помощью. + +## Посмотреть, что активно + +**Analyze → eval authoring** показывает размещённые определения вашей организации — оценки, которые управляемый оценивающий модуль выполняет для неё. Каждая строка содержит: + +- имя, ключ, версию и тип результата +- контрольную сумму исходного кода, которая помогает различать развёрнутые версии без просмотра кода +- **условная** ли это оценка или она выполняется для **всех завершённых сессий** — условие определяет, к каким агентам или окружениям применяется оценка +- её таймаут, метки и время последнего изменения + +![Список размещённых определений: имя, ключ, версия, тип результата, контрольная сумма, таймаут и область применения каждой оценки, с опциями новой версии и включения или отключения.](/images/dashboard/eval-definitions.png) + +Ищите в списке или фильтруйте по состоянию. Оценки, которые регистрирует ваш собственный рабочий процесс, здесь не отображаются; их результаты содержат метку **customer** на [странице оценок](/ru/sessions/evaluations), а размещённые — **managed**. + +Организация может иметь одновременно включено до 100 различных размещённых оценок. + +## Опубликовать новую версию + +Выберите **new version** в строке. Откроется страница разработки с кодом этой версии; измените его, протестируйте и разверните. Её ключ и тип результата переносятся и не могут быть изменены. + +Публикация новой версии отключает предыдущую и оставляет её в списке. Результаты сохраняют версию, которая их произвела, поэтому диаграмма показывает точно, когда вступила в действие новая логика. + +## Откатить назад + +Выберите **disable** на текущей версии и **enable** на нужной вам версии. Ничего не удаляется, и каждый результат остаётся неизменным. + +## Остановить оценку + +Выберите **disable**. Без включённой версии оценка перестанет выполняться на новых сессиях. Чтобы остановить оценку, которую выполняет ваш собственный рабочий процесс, прекратите её регистрацию: удалите из рабочего процесса или остановите рабочий процесс. + +## Оценить уже имеющиеся сессии + +Оценка работает перспективно: версия, развёрнутая сейчас, никогда не оценит сессию, которая завершилась раньше. Чтобы оценить историю, откройте **score sessions you already have** на странице разработки оценки, выберите окно до 90 дней и, опционально, одну оценку, и посчитайте перед запуском. Число точно соответствует тому, что будет запущено, и каждая пара сессия-оценка в нём — это оплачиваемая оценка. + +Заполняются только пробелы. Сессия, которая уже имеет результат для этой оценки, сохраняет его, и повторный запуск того же окна ничего нового не оценивает. + +Чтобы оценить одну сессию снова — после исправления или для сессии, которая так и не завершилась корректно — выберите **re-evaluate** на её странице. Новый результат добавляется в историю сессии; предыдущие остаются. + +## Разрешения + +| Разрешение | Позволяет вам | +| --- | --- | +| `evaluations:read` | Просматривать результаты и открывать страницу разработки оценки | +| `evaluations:trigger` | Просматривать, развёртывать, версионировать, включать и отключать размещённые определения; тестировать их; оценивать историю; переоценивать сессию | +| `events:read` | Тестировать на реальных сессиях и обосновывать черновики ключами вашего payload, в дополнение к `evaluations:trigger` | +| `evaluations:run` | Запускать ваш собственный рабочий процесс оценивающего модуля | \ No newline at end of file diff --git a/docs/ru/evaluations/overview.mdx b/docs/ru/evaluations/overview.mdx new file mode 100644 index 00000000..b3237f41 --- /dev/null +++ b/docs/ru/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "Оценка агентов" +description: "Оценивайте каждую завершённую сессию с помощью проверок на Python или LLM-судей в вашей инфраструктуре." +icon: "gauge" +--- + +Оценка — это результат работы завершённой сессии агента. Когда сессия заканчивается, каждая активная применимая оценка запускается и записывает найденные результаты с обоснованием, которое вы можете увидеть рядом с трассой: + +- **оценка** от 0 до 1, опционально отмеченная как пройденная или не пройденная +- **метрика**, например количество, продолжительность или стоимость, с её единицей измерения +- **утверждение**, которое прошло или не прошло + +## Два вида оценщиков + +| | Hosted Python | Ваша собственная инфраструктура | +| --- | --- | --- | +| Разработка | На панели инструментов в разделе **Analyze → eval authoring** | На Python с использованием [Evaluator SDK](/ru/reference/evaluator-sdk) | +| Выполнение | На управляемом оценщике Failproof AI в изолированной среде | На вашей инфраструктуре | +| Лучше всего для | Детерминированные проверки на основе кода | LLM-судьи, вызовы моделей, пакеты, секреты, сетевой доступ, интенсивная обработка | + +Hosted Python намеренно минимален: одно выражение, без импортов, без сети. Всё, что требует модель — например, LLM-судья, оценивающий релевантность ответа — выполняется в вашей инфраструктуре. Ни один вид не требует входящего подключения: рабочие процессы получают завершённые сессии и отправляют результаты по исходящему HTTPS. + +## Каждая организация оценивает свои агентов + +Оценки принадлежат организации, которая их определила. Каждая организация в инстансе пишет свои — свои проверки, условия, пороги и ярлыки — версионирует и развёртывает их без влияния на другие, и видит только свои результаты. Фильтруйте результаты по агенту, окружению, оценке и времени, или обсудите их с помощником. + +## От первого варианта к живым оценкам + + + + Опишите, что нужно измерить, и дайте помощнику его набросать, или напишите сами. См. [Написание оценки](/ru/evaluations/write). + + + Запустите её на реальных сессиях перед запуском в продакшене; ничего не сохраняется. См. [Тестирование оценки](/ru/evaluations/test). + + + Разверните неизменяемую версию, публикуйте новые по мере развития и откатывайтесь к более ранней версии. См. [Развёртывание и версионирование](/ru/evaluations/deploy). + + + Постройте графики оценок во времени, сравните агентов и окружения, и обсудите их с помощником. См. [Чтение результатов оценки](/ru/sessions/evaluations). + + + +Оценки выполняются вперёд: версия, развёрнутая сейчас, оценивает сессии, которые завершаются с этого момента. Чтобы оценить уже имеющиеся сессии, [заполните их задним числом](/ru/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file diff --git a/docs/ru/evaluations/test.mdx b/docs/ru/evaluations/test.mdx new file mode 100644 index 00000000..cbf8f4bd --- /dev/null +++ b/docs/ru/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "Протестировать оценку" +description: "Запустите оценку для ваших реальных сессий перед развёртыванием. Ничего не сохраняется." +icon: "flask-conical" +--- + +**протестировать эту оценку** на странице редактирования запускает код для реальных сессий на fleet оценивателя без развёртывания. Ничего не сохраняется: ошибка здесь — это предпросмотр, развёртывание всегда разрешено. + + + + Выберите **check**, чтобы скомпилировать код и условие по правилам sandbox без запуска на каких-либо сессиях. + + + Сузьте подходящие сессии по агенту, окружению, времени или ID сессии, и отметьте до 10. Включите сессии, на которых оценка должна не пройти, а также те, на которых она должна пройти. + + + Выберите **run against N sessions** и прочитайте каждую строку. + + + +| Строка | Что это означает | +| --- | --- | +| **ok** | Выполнено. Строка содержит каждый показатель, метрику и утверждение, которые она вернула, и время выполнения. | +| **skipped** | Условие вернуло `False`, поэтому оценка не выполнялась. Это пропуск, а не ошибка. | +| Failed | Произошла ошибка, истекло время ожидания или использовалось что-то, что sandbox запрещает. Строка указывает причину, а **Fix it** передаёт ошибку помощнику, когда он может помочь. | + +![Панель тестирования оценки: три сессии отобраны по агенту, две выполнены успешно и одна пропущена, потому что условие вернуло False.](/images/dashboard/eval-test.png) + +Результат перестаёт быть актуальным в момент редактирования кода; он отображается слегка затемнённым вместо того, чтобы быть переиспользованным. \ No newline at end of file diff --git a/docs/ru/evaluations/write.mdx b/docs/ru/evaluations/write.mdx new file mode 100644 index 00000000..b99e4a69 --- /dev/null +++ b/docs/ru/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "Написать оценку" +description: "Опишите, что нужно измерить, и позвольте помощнику составить размещённую оценку на Python, или напишите код сами. Судьи на основе LLM работают в вашем воркере." +icon: "file-pen-line" +--- + +Размещённые оценки — это небольшие детерминированные программы на Python, написанные в панели управления и выполняемые на оценочном кластере Failproof AI. Более сложную логику — судью на основе LLM, пакет, секрет, сетевой запрос — лучше запустить в [вашем собственном воркере](#write-it-in-your-own-worker). + +## Составить оценку из описания + +1. Перейдите в **Analyze → eval authoring** и выберите **new eval**. +2. Опишите, что нужно измерить, на простом английском языке или выберите **start from an example…**, затем нажмите **draft**. +3. Проверьте поля и сгенерированный код, потом [протестируйте его](/ru/evaluations/test) и [разверните](/ru/evaluations/deploy). + +![Страница создания оценки с составленной оценкой: описание, заметки помощника о черновике, поля имени, ключа, версии, результата, тайм-аута, меток и условия.](/images/dashboard/eval-authoring-draft.png) + +Черновик основан на событиях вашей организации: страница определяет, какие ключи полезной нагрузки были в ваших сессиях за последние семь дней, поэтому код читает существующие ключи, а не угадывает. Перед тем как предложить черновик, помощник тестирует его на до пяти недавних сессий, исправляет всё, что он может доказать, что сломано — до трёх раундов — и один раз проверяет, что код измеряет именно то, что вы просили. Делайте описание конкретным: широкие запросы медленнее и могут истечь по времени. Всё равно проверьте код; развёртывание никогда не блокируется. + +## Установить поля + +| Поле | Что это | +| --- | --- | +| name | То, что видят люди. Можно редактировать позже | +| key | Стабильный идентификатор, под которым группируются его результаты, например `code_assistant_quality_gate` | +| version | Любая строка версии без пробелов, например `1.0.0` | +| result | **score** (от 0 до 1), **metric** (число с единицей) или **assertion** (пройдено или нет) | +| timeout seconds | По умолчанию 30. Изолированная среда останавливает любой отдельный запуск на 60 | +| labels | До 20, разделённые запятыми. Можно редактировать позже | +| condition | Необязательно. Выражение на Python; оценка запускается только на сессиях, где оно имеет значение `True` | + +Используйте условие, чтобы ограничить оценку агентами и средами, для которых она предназначена: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +Ключ, версия, тип результата, условие и код неизменяемы после развёртывания: чтобы изменить любое из них, опубликуйте новую версию. Имя, метки и статус включения остаются редактируемыми. + +## Написать код самостоятельно + +**Код оценки** — это одно выражение на Python, которое возвращает `EvalResult(...)` с доступным `session`. Вот пример, который оценивает долю результатов инструмента, которые пришли в порядке: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +Результат начинается с собственного ключа оценки в объявленном типе: `score=` для оценки-балла или запись `metrics` или `assertions` с именем ключа для метрики или утверждения. Другие метрики и утверждения идут с ним, до 25 результатов в запуске. + +| В области видимости | Предоставляет | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count` и `events`, плюс `count(event_type)` и `events_of_type(event_type)` | +| Каждое событие | `id`, `ts`, `event_type` и `payload` | +| Типы результатов | `EvalResult`, `Score`, `Metric`, `Assertion` и `ConditionResult` для условия | +| Встроенные функции | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +Больше ничего недоступно: нет импортов и нет атрибутов кроме данных сессии и простых методов строк и словарей, таких как `get`, `lower` и `split`, которые должны вызываться, а не просто ссылаться. Ключи полезной нагрузки — это всё, что отправляют ваши агенты — `status` выше только пример — поэтому берите их из реальной сессии. **format** приводит код в порядок, а **fix** просит помощника его исправить. Код может быть до 128 КиБ, условие — до 16 КиБ. + +![Редактор кода оценки с форматированием и исправлением, показывающий утверждения составленной оценки.](/images/dashboard/eval-authoring-code.png) + +## Написать в своём воркере + +Когда оценке требуется модель, пакет, секрет или сеть, напишите её с помощью [Evaluator SDK](/ru/reference/evaluator-sdk) и запустите в собственной инфраструктуре. Она использует те же типы результатов, и её результаты появляются рядом с размещёнными, помеченные **customer**: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/ru/policies/deploy.mdx b/docs/ru/policies/deploy.mdx index d33b9879..fae337de 100644 --- a/docs/ru/policies/deploy.mdx +++ b/docs/ru/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "Развертывание политик" -description: "Разверните проверенную версию политики на целевых машинах." +title: "Развернуть политику" +description: "Разместите протестированную версию политики на машинах в режиме наблюдения, включите её применение и убедитесь, что каждая машина получила обновление." icon: "cloud-upload" --- -Развертывание связывает одну или несколько версий политик с набором зарегистрированных машин. +Развертывание размещает опубликованные версии политики на машине, каждая с одним из двух эффектов: -## Применить развертывание +- **Observe** записывает, что бы сделала политика, и ничего не блокирует. +- **Enforce** действует согласно решению: `deny` блокирует вызов, а `instruct` направляет агента. + +## Добавить машину + +Машина появляется в разделе **Admin → enforcement** после подключения к Cloud. Если нужная машина еще там не показана: + + + + 1. Перейдите в **Administration → Keys** и создайте ключ с разрешениями `policies:pull`, чтобы машина могла получать развертывания, и `events:add`, чтобы её решения попадали в Cloud. + 2. Подключите машину с этим ключом — в разделе [Connect a machine to Cloud](/ru/start/setup#connect-a-machine-to-cloud) есть пошаговая инструкция. + 3. Убедитесь, что машина появилась в разделе **Admin → enforcement**. + + + На машине: + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + В терминале команда `failproofai config` спросит, подключиться ли к Cloud, и запросит ключ в защищённом поле ввода. Затем подтвердите, что машина зарегистрирована, выполнив команду `fp fleet list` из любого места. + + + +## Развернуть в режиме наблюдения 1. Перейдите в **Admin → enforcement**, найдите машину и разверните её строку. - 2. Выберите **edit**, добавьте проверенную версию политики и выберите режим **observe** или его эффект принудительного применения. - 3. Примените изменение, дождитесь следующей проверки машины и подтвердите состояние развертывания и покрытия. - 4. Перейдите в **Observe → policy** для проверки актуальных решений. + 2. Выберите **edit**, добавьте протестированную версию политики и выберите **observe**. + 3. Примените изменение и дождитесь следующей синхронизации машины, затем проверьте состояние развертывания и покрытия. + 4. Перейдите в **Observe → policy**, чтобы просмотреть решения в реальном времени. - ![Редактор развертывания машины с версиями политик, эффектами enforce и observe, и действием применения развертывания.](/images/dashboard/enforcement-editor.png) + ![Редактор развертывания машины с версиями политик, режимами enforce и observe, и действием применить развертывание.](/images/dashboard/enforcement-editor.png) - Разверните из CLI с помощью `fp fleet`. Проверьте полученный набор перед применением — `deploy` выводит полный план и запрашивает подтверждение **только в интерактивном терминале без `--json`**. С флагом `--json`, `--yes` или при перенаправлении stdin (шаг CI, скрипт, агент с shell-командой) применяется сразу без плана и приглашения — поэтому сначала выполните `fp fleet show `, если хотите проверить: - ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` показывает намерение и фактическое состояние (машина отображается как `behind` до следующего опроса), `fp fleet history ` выводит список поколений, а `fp fleet rollback ` восстанавливает одно — отклоняет, если это поколение ссылается на политику, которая уже отключена или удалена. + Суффикс `:observe` активирует режим наблюдения: просто `--add no-force-push` сохраняет текущий эффект машины для этой политики, иначе применяется enforce. Позже переключитесь на enforce с помощью `--add no-force-push:enforce`. + + Команда `deploy` **заменяет весь набор политик на машине** на результат. Она выводит план и просит подтверждение на интерактивном терминале. С флагом `--yes`, внутри `fp --json`, или при переназначении stdin (CI-шаг, скрипт, агент, вызывающий shell) применяется без подтверждения; план все ещё выводится или возвращается как `plan` в `--json`. - Проверьте саму машину с помощью `failproofai config --status` и используйте `fp sessions --env production --since 24h` и `fp events --event-type hook_completed` после развертывания, чтобы убедиться, что активность достигает Cloud. + На машине команда `failproofai policies` показывает управляемые Cloud политики, которые она запускает, а `failproofai config --status` показывает её подключение. Используйте `fp sessions --env production --since 24h` и `fp events --event-type hook_completed`, чтобы подтвердить, что активность машины достигает Cloud. - - Разверните проверенную версию, а не изменяемый черновик, начиная с машины без production или небольшой группы, сеансы которой вы можете проверить. + + Выберите опубликованную версию и машины, на которых она должна запускаться. - - Проверьте совпадения, причины, затронутые инструменты и ложные срабатывания без блокирования работы. + + Изучите совпадения, причины, затронутые инструменты и ложные срабатывания, пока ничего не блокируется. - - Перейдите к принудительному применению после того, как наблюдаемые совпадения отделят небезопасные действия от допустимых, затем подтвердите, что каждая целевая машина получила развертывание и передает решения. + + Переключитесь на enforce, когда наблюдаемые совпадения отделяют небезопасные действия от правильных, затем подтвердите, что каждая нужная машина получила изменение и сообщает решения. -Машинам требуется возможность `policies:pull`. Передача событий контролируется отдельно через `events:add`; проверьте оба параметра, если ожидаете анализа и применения Cloud. +## Проверить покрытие + +Покрытие показывает, запускается ли политика там, где существует риск. + +1. Перейдите в **Admin → enforcement** и проверьте итоги по enforce и observe. +2. Найдите машину по ID или метке либо отфильтруйте машины, у которых отсутствует политика. +3. Разверните строку, чтобы сравнить назначенные политики, сообщённое развертывание, последнюю синхронизацию и историю. +4. Обновите страницу после интервала опроса машины, если развертывание все ещё ожидает применения. + +![Парк машин Enforcement с покрытием политик, состоянием развертывания и назначениями observe и enforce.](/images/dashboard/enforcement-fleet.png) + +Обратите внимание на машины, которые никогда не получали последнее развертывание, зарегистрированные машины, которые перестали отправлять отчеты, политику, назначенную неправильному окружению, и расхождение версий после прерванного обновления. + +Метьте машины по рабочей нагрузке и окружению — одних имён хостов обычно недостаточно при автоскейлинге или замене: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - Управление принудительным применением — это административный рабочий процесс Cloud. Не рассматривайте корневые маршруты принудительного применения как обычные конечные точки API `/v1` для клиентов. + Управление enforcement — это административный рабочий процесс Cloud. Не обращайтесь с доступными только root пользователю маршрутами enforcement как с обычными конечными точками API `/v1` для клиентов. \ No newline at end of file diff --git a/docs/ru/policies/editor.mdx b/docs/ru/policies/editor.mdx index 279cecc1..e0d4c778 100644 --- a/docs/ru/policies/editor.mdx +++ b/docs/ru/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "Редактор политик" -description: "Создавайте и пересматривайте версионированные политики на основе подтвержденного режима отказа." +title: "Написание политики" +description: "Позвольте Failproof AI создать проект политики на основе результатов аудита, или напишите исходный код сами, затем проверьте, протестируйте и опубликуйте его." icon: "file-pen-line" --- -Используйте редактор политик для преобразования обнаруженной проблемы в развертываемое правило. Отделите создание от развертывания, чтобы черновик не мог скрытно изменить поведение в боевой среде. +Существует два способа написать политику: позволить Failproof AI создать её на основе результатов аудита или написать исходный код самостоятельно. Ничего не публикуется и не развёртывается, пока вы этого не выберете. -Когда проблема имеет повторяющийся паттерн действий, откройте ее в **Analyze → issues** и выберите **generate policy**. Failproof AI сначала объясняет, может ли политика выразить проблему, затем переносит проверенное намерение и контекст обнаружения в редактор. Созданный источник остается черновиком до его публикации. +## Написание политики на основе аудита -## Опубликуйте версию политики +Аудит выявляет отказ; политика предотвращает его повторение. Failproof AI создаёт проект политики на основе доказательств из найденных результатов. + +### 1. Запустите аудит + +[Запустите аудит](/ru/audits/run) над сеансами, в которых происходит отказ. Каждый результат содержит свидетельствующие сеансы, основную причину и рекомендуемый путь предотвращения. Работайте с результатом, который имеет **повторяющийся паттерн действий** — политика может предотвратить только то, что она может распознать в событии хука. + +### 2. Создайте проект - - 1. Перейдите в **Admin → policy editor** и в разделе **compose** опишите режим отказа или вставьте исходный код политики JavaScript. - 2. Проверьте источник и исправьте все сообщенные ошибки. - 3. Введите идентификатор политики и опубликуйте ее, затем используйте **library** для сравнения или отключения версий. - 4. Выберите **enforcement**, когда версия готова к машинному развертыванию. + + 1. Откройте проблему результата в разделе **Analyze → issues** и проверьте цитируемые сеансы, основную причину и рекомендацию. + 2. Выберите **generate policy**. Failproof AI сначала указывает, может ли политика вообще выразить проблему. Результат **no policy** означает, что решением является оповещение, изменение рабочего процесса или действие человека — не политика. + 3. Выберите **write this policy**. Название проблемы, результат, основная причина, рекомендация и предлагаемое намерение принуждения становятся проектом в **Admin → policy editor**. Используйте **open the editor anyway**, если вы не согласны с проверкой кандидатуры. - ![Представление compose редактора политик с идентификатором политики, автоматизированным созданием черновиков, проверкой источника и элементами управления публикацией.](/images/dashboard/policy-editor.png) + ![Представление компоновщика редактора политик с идентификацией политики, поддерживаемой ИИ разработкой, проверкой исходного кода и элементами управления публикацией.](/images/dashboard/policy-editor.png) - Опубликуйте из CLI с помощью `fp policies publish`. Эта команда создает **новую версию** и никогда не редактирует существующую на месте, а также проверяет синтаксис источника с помощью node перед отправкой — никакой другой компонент этого не делает, поэтому синтаксическая ошибка иначе появилась бы на машине во время развертывания: + Прочитайте доказательства, затем создайте проект с помощью ассистента. `compose` выводит исходный код для проверки и ничего не публикует: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - Публикация не развертывает ничего — новая версия остается неиспользованной до тех пор, пока `fp fleet deploy` не поместит ее на машину. `fp policies compose ""` создает источник с помощью облачного ассистента и выводит его для проверки вместо публикации. - - Чтобы установить политику в локальный агент CLI (не облако), используйте `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. + `compose` требует аутентифицированного сеанса (`fp login`), роль которого имеет `policies:write`; он отклоняет API-ключи. -## Контрольный список создания +### 3. Проверьте проект + +Проект — это отправная точка, не вердикт. Перед публикацией убедитесь, что он: + +1. Называет режим отказа на операционном языке. +2. Соответствует только событиям хука и инструментам, которые содержат достаточно доказательств для принятия решения. +3. Использует наиболее узкое условие, которое ловит небезопасное действие. +4. Возвращает причину, которая подсказывает агенту, что делать вместо этого. +5. Использует `instruct`, где агент может безопасно скорректировать курс, и `deny` только там, где разрешение действия неприемлемо или необратимо. + +Проверьте исходный код в редакторе и исправьте все ошибки. + +### 4. Протестируйте и опубликуйте + +Запустите **backtest** под исходным кодом перед публикацией: он переиграет проект против вызовов, которые уже сделал ваш парк, и подсчитает рабочие вызовы, которые он прервал бы. [Тестирование политики](/ru/policies/test) охватывает это и другие проверки. + +Когда это работает, введите идентификацию политики и выберите **publish version**. Публикация создаёт неизменяемую версию и ничего не развёртывает: она остаётся неиспользованной, пока вы её не [развернёте](/ru/policies/deploy). Из терминала: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` проверяет исходный код перед отправкой, поэтому ошибка синтаксиса проявляется здесь, а не на машине во время выполнения. + +## Напишите сами + +Политика — это JavaScript или TypeScript для API `failproofai`: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +Это соответствует `production/config.yml`, `/srv/production/config.yml`, `/srv/production` и `C:\\production\\config.yml` для обоих `Write` и `Edit`, но не `production-backup`: `production` должен быть целым сегментом пути. Контекст также содержит тип события, нормализованный payload, метаданные сеанса, параметры и исходный CLI, если доступен — см. [policy SDK](/ru/reference/policy-sdk). + +Чтобы опубликовать его как версию, вставьте исходный код в **compose** в **Admin → policy editor** и следуйте шагам 3 и 4 выше, или опубликуйте файл из терминала с помощью `fp policies publish`. -1. Назовите режим отказа на операционном языке. -2. Выберите события hook и инструменты, которые содержат достаточно доказательств для принятия решения. -3. Напишите наиболее узкое условие, которое соответствует небезопасному поведению. -4. Вернитесь к причине, которая подскажет агенту или оператору, что делать дальше. -5. Добавьте примеры, которые должны совпадать, и примеры, которые должны остаться разрешенными. -6. Сохраните новую версию и запросите проверку. +Чтобы запустить его на машине без облака, сохраните его под `.failproofai/policies/` с именем, заканчивающимся на `policies.js`, `policies.mjs` или `policies.ts` — они автоматически загружаются на уровне проекта и пользователя — или установите по пути: -Используйте `instruct`, когда агент может безопасно изменить курс. Используйте `deny`, когда разрешение действия создаст неприемлемый или необратимый риск. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - Версии политик являются неизменяемыми входными данными для развертывания. Редактирование черновика создает новую версию; он не должен переписывать версию, уже назначенную машинам. - \ No newline at end of file +Дайте каждой политике имя, которое уникально во всех соглашениях, пользовательских, пакетных и управляемых облаком политиках. \ No newline at end of file diff --git a/docs/ru/policies/failure-behavior.mdx b/docs/ru/policies/failure-behavior.mdx index 95f2d691..99df3593 100644 --- a/docs/ru/policies/failure-behavior.mdx +++ b/docs/ru/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- -title: "Поведение при сбое" -description: "Поймите, что происходит, когда оценка политики или локальный демон недоступны." +title: "Поведение при отказах" +description: "Узнайте, что происходит, когда вычисление политики или локальный демон недоступны." icon: "shield-alert" --- -Failproof AI разработан так, чтобы сбой при применении был видим, а не скрыто разрешал рискованные действия. +Failproof AI разработан так, чтобы отказ при принудительном применении был виден, а не молча допускал рискованные операции. -## Диагностика блокировки при сбое +## Диагностика блокировки при отказе 1. Перейдите в **Admin → enforcement** и откройте машину. - 2. Проверьте её последний check-in, назначенное развёртывание и сообщённое развёртывание. - 3. Перейдите в **Observe → policy** и откройте сессию отклонённого решения. - 4. Подтвердите, указывает ли причина на доступность демона, несоответствие версий или саму политику. + 2. Проверьте последнее подключение, назначенное развертывание и сообщенное развертывание. + 3. Перейдите в **Observe → policy** и откройте сеанс отклоненного решения. + 4. Подтвердите, содержит ли причина сведения о доступности демона, рассогласовании версий или самой политике. @@ -23,45 +23,47 @@ Failproof AI разработан так, чтобы сбой при приме failproofai config ``` - Повторный запуск `failproofai config` обновляет и перезапускает демон после обновления пакета. + Повторное выполнение `failproofai config` обновляет и перезапускает демон после обновления пакета. -На машине, настроенной на использование `failproofaid`, демон является единственным оценщиком. Если он недоступен или его версия протокола не совпадает с версией CLI, оценка hook завершается отказом. Действие отклоняется с причиной, которая направляет оператора проверить или обновить демон. +На машине, настроенной для использования `failproofaid`, демон является единственным оценивающим. Если он недоступен или его версия протокола не совпадает с версией CLI, вычисление хука завершается отказом. Действие отклоняется с причиной, которая направляет оператора на проверку или обновление демона. -До настройки демона hooks оценивают политики внутри процесса. После того как конфигурация демона записана, Failproof AI не переходит молча на второго оценщика при отказе демона. +До конфигурации демона хуки вычисляют политики внутри процесса. После того как конфигурация демона записана, Failproof AI не молча не переходит на второго оценивающего при отказе демона. -## Ответ на решение об отказе при сбое +## Ответ на решение об отказе при отказе 1. Запустите `failproofai config --status`. -2. Если версии отличаются, повторно запустите `failproofai config` после обновления пакета. +2. Если версии отличаются, переустановите пакет и повторно запустите `failproofai config`. 3. Если демон недоступен, проверьте состояние его сервиса и локальные журналы. -4. Возобновляйте работу агента только после проверки целостности известного пути оценки политики. +4. Продолжайте работу агента только после того, как известный путь вычисления политики будет исправен. - Не повторяйте заблокированное действие многократно. Ответ об отказе при сбое означает, что система не смогла установить безопасность действия. + Не повторяйте заблокированное действие несколько раз. Ответ об отказе означает, что система не смогла установить, что действие было безопасным. -## Pack не загружается +## Пакет не загружается -Машина, которой было приказано применять pack, и которая не может его запустить, отклоняет его, а не продолжает молча. Триггер — это **записанное ожидание**, никогда не пустое: машина без установленных pack молчит, в то время как pack, который объявлен и не будет разрешён — или который регистрирует меньше, чем объявляет его манифест — отклоняет. +Машина, которой было приказано применить пакет и которая не может его запустить, отклоняет его, а не продолжает молча. Триггер — это **записанное ожидание**, никогда не пустое: машина без установленных пакетов молчит, а пакет, который объявлен и не разрешится — или зарегистрирует меньше, чем объявляет его манифест — отклоняется. -Отказ **узкий**, в отличие от недоступного демона. Недостижимый демон означает, что оценка не произошла вообще, поэтому ничего не может быть известно как безопасное. Pack, который не загружается, имеет перечислимый набор отсутствующих гвардов, потому что каждая объявленная политика имеет собственный `match` — поэтому он отклоняет только события и инструменты, охватываемые этими политиками, и всё остальное продолжается. +Отказ **узконаправленный**, в отличие от недоступного демона. Недоступный демон означает, что вычисление вообще не произошло, поэтому ничего нельзя считать безопасным. Пакет, который не загружается, имеет перечислимый набор отсутствующих политик, потому что каждая объявленная политика имеет свой собственный `match` — поэтому он отклоняет только события и инструменты, охватываемые этими политиками, а все остальное продолжается. Он не срабатывает для: -- `observe` pack, который по конструкции оценивает и отбрасывает -- политик, которые вы никогда не принимали, или явно отключили -- pack, который загрузчик никогда не получал, где "отсутствие регистраций" невозможно отличить от намеренного пропуска -- активной паузы сессии -- timeout загрузки, который преходящий — один медленный момент диска не должен отклонять, пока человек не вмешается +- пакета `observe`, который по конструкции вычисляет и отклоняет +- политик, которые вы никогда не брали или явно отключили +- пакета, который загрузчик никогда не получал, где нельзя отличить отсутствие регистраций от преднамеренного пропуска +- активной паузы сеанса +- превышения времени загрузки, что является переходным — один медленный момент диска не должен отклонять до тех пор, пока не вмешается человек -`UserPromptSubmit` **инструктирует** вместо отказа, независимо от того, что объявляла отсутствующая политика. Полный отказ взял бы его с собой и заблокировал бы доступ к агенту, который мог бы исправить проблему. +`UserPromptSubmit` **инструктирует** вместо отказа, какой бы отсутствующей политике ни объявляли. Полный отказ повлек бы это и заблокировал бы вам доступ к агенту, который мог бы решить проблему. ### Что делать ```bash -failproofai pack list +failproofai policies ``` -Он называет любой установленный pack, который не загружается, говорит почему и выходит с ненулевым кодом. Затем либо переустановите его (`failproofai pack add `), либо удалите его (`failproofai pack remove `) — удаление снимает ожидание, и отказ прекращается вместе с ним. \ No newline at end of file +Список отмечает установленный пакет, запись об установке или дайджест которого больше не проверяются, и объясняет почему. Он не импортирует пакет, поэтому тот, который не работает, пока не загружается — регистрирует меньше, чем объявляет его манифест — отображается как обычно; приведенный ниже отказ — это то, что его называет. В любом случае переустановите его (`failproofai policies add `) или удалите его (`failproofai policies remove `) — удаление снимает ожидание, и отказ прекращается вместе с ним. + +Сам отказ атрибутируется `pack/failproofai-pack-unavailable`, которая имеет приоритет над загруженными политиками, поэтому заблокированный вызов инструмента называет отсутствующий пакет, а не какую-нибудь оставшуюся политику, которая сработала первой. \ No newline at end of file diff --git a/docs/ru/policies/local-configuration.mdx b/docs/ru/policies/local-configuration.mdx index 4dca36c5..8d23ee88 100644 --- a/docs/ru/policies/local-configuration.mdx +++ b/docs/ru/policies/local-configuration.mdx @@ -1,55 +1,49 @@ --- title: "Локальная конфигурация" -description: "Управляйте областью действия политик, параметрами, пользовательскими файлами и параметрами Failproof AI на уровне машины." +description: "Управляйте областью действия политик, параметрами, пользовательскими файлами и машинными настройками Failproof AI." icon: "file-cog" --- -Failproof AI разделяет выбор политик от параметров машины и демона. Это позволяет проверять выбор политик репозитория, при этом учетные данные и состояние демона остаются за пределами репозитория. +Failproof AI разделяет содержимое репозитория — подключение хуков, параметры политик, пользовательские политики — от машинного состояния, такого как учетные данные, установленные пакеты и демон. -## Выберите область действия политики +## Выберите область действия - - - Запустите `failproofai` без аргументов, чтобы открыть локальную панель управления политиками. Выберите область пользователя, проекта или локальную область перед включением политики, чтобы изменение было записано в нужный файл конфигурации. +Область действия определяет, где подключаются хуки и в какой файл конфигурации вы записываете параметры и пути к пользовательским политикам: - - **User** применяется ко всем проектам на этой машине. - - **Project** принадлежит репозиторию и может быть закоммичена. - - **Local** переопределяет один проект для одного пользователя и должна оставаться в .gitignore. +- **User** применяется ко всем проектам на этой машине. +- **Project** принадлежит репозиторию и может быть закоммичена. +- **Local** переопределяет один проект для одного пользователя и должна оставаться в gitignore. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # wire hooks for this repository +failproofai policies --install --cli claude --scope user # or for every project on this machine +failproofai policies +``` - Не все хранилища поддерживают локальную область. CLI отклоняет область, которую выбранное хранилище не может представить. - - +Не все инструменты поддерживают локальную область действия; CLI отклоняет область, которую выбранный инструмент не может представить. + +То, какие политики пакета включены, **не** входит в область действия. Переключатель записывается вместе с установленным пакетом, поэтому `failproofai policies add ` включает политику для всей машины, независимо от `--scope`. -| Область | Файл конфигурации политики | +| Область действия | Файл конфигурации политик | | --- | --- | | Project | `/.failproofai/policies-config.json` | | Local | `/.failproofai/policies-config.local.json` | | User | `~/.failproofai/policies-config.json` | -Включенные политики объединяются как объединение. Параметры политики используют первую область, которая определяет параметры для этой политики, в порядке project → local → user. Явные пользовательские пути политик используют первую область, которая их определяет. +Параметры политик используют первую область действия, которая определяет параметры для этой политики, в порядке project → local → user. Явные пути к пользовательским политикам используют первую область действия, которая их определяет. -## Настройте параметры политики +## Настройте параметры политик - Откройте политику в локальной панели управления, отредактируйте поддерживаемые параметры и сохраните в выбранной области. Запустите совпадающее и несовпадающее действие агента, затем проверьте решение в **Observe → policy**. + Откройте политику в локальной приборной панели, отредактируйте поддерживаемые параметры и сохраните в выбранную область действия. Запустите действие агента, которое совпадает и не совпадает, затем посмотрите решение в **Observe → policy**. - Отредактируйте `policies-config.json` выбранной области, затем запустите `failproofai policies`, чтобы выявить неизвестные имена политик или ключи параметров. + Отредактируйте `policies-config.json` в выбранной области действия, затем запустите `failproofai policies`: оно выдаст предупреждение о записи `policyParams`, которая называет политику, которую не несет ни один установленный пакет. Он не проверяет ключи внутри записи, поэтому проверьте их орфографию в таблице ниже. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ Failproof AI разделяет выбор политик от параметр -## Изучите файлы машины +### Параметры, которые принимают политики Failproof AI + +Каждая политика самостоятельно проверяет типы своих параметров. + +| Политика | Параметр | Тип и значение по умолчанию | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; записи содержат `regex` и `label` | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| Infrastructure blockers | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + Разрешающий шаблон расширяет то, что может делать агент. Протестируйте точную токенизацию и варианты команд на целевом инструменте перед развертыванием на множество машин. + + +## Разберитесь в машинных файлах `~/.failproofai` содержит отдельные файлы для отдельных границ доверия: | Путь | Назначение | | --- | --- | -| `config.json` | Параметры демона без секретов, аудита и телеметрии | +| `config.json` | Некритичные параметры демона, аудита и телеметрии | | `credentials.json` | Облачные учетные данные; хранятся с разрешениями только для владельца | -| `policies-config.json` | Выбор встроенной области пользователя, параметры и явные пользовательские пути | -| `policies/` | Пользовательские политики соглашения и управляемые облаком артефакты политик | -| `hook-activity/` | Локальный журнал решений политики | -| `state/` | Демон спул, здоровье, пауза и состояние выполнения | +| `policies-config.json` | Параметры области пользователя и явные пути к пользовательским политикам | +| `policies/` | Условные политики пользователя, установленные пакеты и которые их политики включены, а также артефакты политик, управляемые облаком | +| `hook-activity/` | Локальный журнал решений политик | +| `state/` | Очередь демона, состояние здоровья, пауза и состояние выполнения | -Используйте `FAILPROOFAI_HOME` для переноса полного макета машины для контейнера или изолированного теста. Не переносите отдельные каталоги состояния независимо. +Используйте `FAILPROOFAI_HOME` для перемещения полного макета машины для контейнера или изолированного теста. Не переумещайте отдельные каталоги состояния независимо. - Никогда не коммитьте `credentials.json`. Коммитьте конфигурацию политики проекта и пользовательские политики проекта только после проверки их как кода обеспечения. + Никогда не коммитьте `credentials.json`. Коммитьте конфигурацию политик проекта и условные политики проекта только после проверки их как кода обеспечения. \ No newline at end of file diff --git a/docs/ru/policies/overview.mdx b/docs/ru/policies/overview.mdx index df8e4d76..b1698984 100644 --- a/docs/ru/policies/overview.mdx +++ b/docs/ru/policies/overview.mdx @@ -1,63 +1,54 @@ --- title: "Политики" -description: "Наблюдайте, направляйте или блокируйте действия агента перед повторением известного сбоя." +description: "Отслеживайте, направляйте или блокируйте действия агента перед тем, как известный сбой повторится." icon: "shield-check" --- Политика оценивает событие хука агента и возвращает одно из трёх решений: -- `allow` позволяет действию продолжиться. -- `instruct` дает агенту корректирующее указание. -- `deny` блокирует действие с указанием причины. +- `allow` разрешает действию продолжиться. +- `instruct` даёт агенту корректирующие рекомендации. +- `deny` блокирует действие с объяснением причины. -## Используйте три уровня политики +## Где хранятся политики - - - 1. Перейдите в **Observe → policy** для фильтрации и проверки решений политики из сеансов. - 2. Перейдите в **Admin → policy editor** для создания, валидации, публикации, отключения или проверки неизменяемых версий. - 3. Перейдите в **Admin → enforcement** для назначения версий и эффектов машинам. +| В панели управления | Что вы там делаете | +| --- | --- | +| **Observe → policy** | Проверяйте решения из реальных сеансов: какая политика совпала, на каком устройстве и почему | +| **Admin → policy editor** | Напишите политику, протестируйте её на прошлом трафике, опубликуйте неизменяемую версию и сравнивайте версии в **library** | +| **Admin → enforcement** | Разместите версии на устройствах в режиме наблюдения или принудительного исполнения | - Используйте страницу Policy для понимания того, что уже соответствует критериям перед созданием или изменением принудительного применения. +Редактор политик — это то место, где сбой становится правилом. Опишите режим отказа или вставьте исходный текст политики в **compose**, протестируйте черновик на имеющемся у вас трафике и опубликуйте версию: - ![Страница Policy с итогами решений и локально управляемыми и облачными сопоставлениями политик.](/images/dashboard/policy-observe.png) +![Представление compose редактора политик с идентификацией политики, AI-ассистентом для черновика, валидацией исходного кода и элементами управления публикацией.](/images/dashboard/policy-editor.png) - Редактор — это место, где вы преобразуете условие сбоя в исходный код, валидируете его и публикуете неизменяемую версию. +На устройстве `failproofai policies` перечисляет всё, что там действует. `fp policies` и `fp fleet` охватывают редактор и принудительное исполнение из терминала — см. [справку Cloud CLI](/ru/reference/cloud-cli). - ![Редактор Policy, используемый для создания и публикации неизменяемой версии политики.](/images/dashboard/policy-editor.png) +## Получить политику - Принудительное применение затем назначает опубликованную версию и её эффект наблюдения или применения машинам. - - ![Fleet принудительного применения, показывающий охват машин и назначенные версии политик.](/images/dashboard/enforcement-fleet.png) - - Проверьте решения на странице Policy после развертывания, чтобы представления создания и флота были связаны с реальной деятельностью агента. - - - Используйте `failproofai` для локальной установки и валидации политик: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - Используйте `fp` для поиска облачных сеансов и событий, содержащих решения политики. Создание облачных политик и развертывание флота остаются рабочими процессами панели. - - - -Политики имеют три отдельных уровня в Failproof AI: - -1. **Анализируйте решения** в сеансах, панелях и аудитах. -2. **Создавайте версии** с встроенными правилами, кодом или редактором политик. -3. **Развертывайте и применяйте** версии на выбранных машинах. - -Начните с подтвержденного режима сбоя. Определите наименьшее событие и совпадение инструмента, которые его идентифицируют, протестируйте легитимные и небезопасные примеры, затем наблюдайте перед применением. +Есть два способа. - - Включите проверенное правило для общих рисков, связанных с секретами, shell, Git, облаком и рабочими процессами. + + Позвольте Failproof AI составить её на основе аудита, или напишите исходный текст сами, а затем проверьте и опубликуйте в редакторе. - - Выразите решение, специфичное для рабочего процесса, на JavaScript или TypeScript. + + Подключите пакет политик Failproof AI для вашего сценария или пакет сообщества из hub политик одной командой. - \ No newline at end of file + + +## Затем разверните её + + + + Протестируйте черновик на имеющемся у вас трафике и запустите его на действии, которое он должен остановить, и на действии, которое он должен разрешить — всё до публикации. См. [Тестирование политики](/ru/policies/test). + + + Разместите версию на устройствах в режиме **observe**, прочитайте её решения, затем включите принудительное исполнение. См. [Развёртывание политики](/ru/policies/deploy). + + + Каждая публикация — это новая неизменяемая версия, поэтому развёртывание, блокирующее допустимую работу, отменяется переразвёртыванием последней хорошей версии. См. [Версии и откат](/ru/policies/rollback). + + + +Чтобы поделиться своими политиками с другими командами, [опубликуйте их как пакет](/ru/policies/publish-a-pack). Чтобы узнать, что происходит, когда политика не может быть оценена вообще, см. [Поведение при сбое](/ru/policies/failure-behavior). \ No newline at end of file diff --git a/docs/ru/policies/packs.mdx b/docs/ru/policies/packs.mdx index 3e0b9cdb..276891e0 100644 --- a/docs/ru/policies/packs.mdx +++ b/docs/ru/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "Наборы политик" -description: "Установите набор политик, опубликованный как выпуск GitHub, и управляйте тем, что он принудительно применяет." +title: "Использование пакета политик" +description: "Подключите пакет политик Failproof AI для вашего сценария использования или пакет сообщества из хаба политик и выберите, что он будет проверять." icon: "package" --- -Набор — это совокупность политик, опубликованная как выпуск GitHub. Одна команда устанавливает его, контрольные суммы самого выпуска проверяются перед запуском, и хеш записывается так, чтобы набор не мог измениться на вашей машине впоследствии. +Пакет — это набор политик, опубликованный как GitHub release. Одна команда устанавливает его: контрольные суммы release проверяются перед запуском чего-либо, и его дайджест записывается так, чтобы пакет не мог измениться на вашей машине впоследствии. -## Установите политики Failproof AI +Изучите все пакеты и каждую политику в них на [хабе политик](https://befailproof.ai/policy-hub/). Есть два типа: + +- **Пакеты политик Failproof AI** — готовые пакеты для предопределённых сценариев использования: подключите один, и он работает. [Пакет политик для агента кодирования](https://befailproof.ai/policy-hub/failproofai/policies/) доступен сейчас, и пакеты для других сценариев скоро появятся. +- **Пакеты политик сообщества** — политики, которые разработчики написали для собственных сценариев и опубликовали для всех. + +## Пакеты политик Failproof AI + +### Пакет политик для агента кодирования ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -Это устанавливает набор, который мы публикуем, из копии внутри пакета — поэтому он не требует сетевого подключения и не может сломаться за прокси. Возьмите часть из него: +Пакет содержит 38 политик и включает 10, которые его манифест помечает как безопасные для автоматического включения; остальные перечислены для вас, чтобы выбрать. Некоторые из наиболее используемых и показано, включены ли они по умолчанию при простой команде `policies add`: + +| Политика | Что она делает | Включена по умолчанию | +| --- | --- | --- | +| `block-push-master` | Блокирует прямые push в защищённые ветки | Да | +| `block-env-files` | Блокирует чтение и запись файлов `.env` | Да | +| `protect-env-vars` | Блокирует команды, которые выводят переменные окружения | Да | +| `block-sudo` | Блокирует `sudo`, если не совпадает разрешённый паттерн | Да | +| `block-curl-pipe-sh` | Блокирует загруженные скрипты, передаваемые прямо в shell | Да | +| `sanitize-*` (пять политик) | Сообщают об API ключах, bearer токенах, JWT, приватных ключах и строках подключения в выводе инструментов | Да | +| `block-rm-rf` | Блокирует катастрофичное рекурсивное удаление | Нет | +| `block-force-push` | Блокирует force-push | Нет | +| `block-secrets-write` | Блокирует записи в файлы учётных данных и секретных ключей | Нет | +| `warn-destructive-sql` | Предупреждает о `DROP`, `TRUNCATE` и `DELETE` без `WHERE` | Нет | + +Включите любые отключённые по имени — `failproofai policies add block-rm-rf` — или возьмите весь пакет с `--all`. Смотрите каждую политику в нём, сгруппированную по категориям: ```bash -failproofai pack add core --policy block-rm-rf # одну, или несколько через запятую -failproofai pack add core --category dangerous-commands # целую категорию -failproofai pack add core --all # всё в нём +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` выводит названия всех категорий, которые предоставляет набор. +## Пакеты политик сообщества -## Посмотрите, что содержит набор, перед установкой +Разработчики публикуют пакеты для своих сценариев использования, и [хаб политик](https://befailproof.ai/policy-hub/) их перечисляет. Пакет сообщества опубликован его автором, не проверен Failproof AI, поэтому прочитайте, что он содержит, перед установкой: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -Выводит список всех политик в наборе, сгруппированных по категориям, с указанием того, какие из них автор включает по умолчанию и какие являются опциональными. Он читает **только манифест** — артефакт входа никогда не загружается и никогда не импортируется, поэтому изучение чужого набора не может запустить чужой код. Манифест по-прежнему проверяется против `SHA256SUMS` самого выпуска, поэтому вы читаете именно то, что будет установлено. - -`failproofai pack list` без источника выводит уже установленные здесь наборы. +Это перечисляет все политики, которые он содержит, сгруппированные по категориям, и отмечает, какие автор включает по умолчанию. Он читает **только манифест** — основной артефакт никогда не загружается и не импортируется, поэтому просмотр пакета незнакомца не может запустить его код. Манифест всё ещё проверяется против собственной `SHA256SUMS` release, поэтому то, что вы видите, это то, что установится. -## Установите чужой набор +Затем установите его: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -Работают любые из этих вариантов — вставьте то, что у вас есть: +Любое из этих значений работает — вставьте то, что у вас есть: | Источник | Результат | | --- | --- | -| `acme/support-agent` | Новейший выпуск, **привязанный** к точному тегу, на который он разрешился | -| `acme/support-agent@v2.1.0` | Тот выпуск | +| `acme/support-agent` | Последний release, **закреплённый** к точному тегу, на который он разрешился | +| `acme/support-agent@v2.1.0` | Этот release | | `github:acme/support-agent@v2.1.0` | То же самое, написано явно | | `https://github.com/acme/support-agent/releases/tag/v2.1.0` | То же самое, скопировано из браузера | -Если не указать тег, устанавливается новейший выпуск **и привязывается**, затем вам сообщается, какой тег он выбрал. Что записывается всегда указывает ровно один выпуск, поэтому переустановка не может измениться. +Если не указан тег, устанавливается последний release **и закрепляется**, затем вам сообщается, какой тег был выбран. То, что записывается, всегда называет ровно один release, поэтому переустановка не может дрейфовать. -## Возьмите часть набора +## Возьмите часть пакета -По умолчанию вы получаете **собственные** установки набора — политики, которые его автор отметил как безопасные для включения без присмотра — а не всё, что он содержит. +По умолчанию вы получаете **собственные** значения по умолчанию пакета — политики, которые автор пометил как безопасные для автоматического включения — не всё, что он содержит. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # одну или несколько через запятую +failproofai policies add FailproofAI/policies --category dangerous-commands # целую категорию +failproofai policies add FailproofAI/policies --all # всё в нём ``` -`--category` и `--policy` объединяются как объединение (`--only` принимается как синоним для `--policy`). Переустановка на новой версии сохраняет то, что вы выбрали, вместо того чтобы включить остальное обратно. +`--category` и `--policy` объединяются как объединение (`--only` принимается как синоним для `--policy`). Когда пакет уже установлен, флаги добавляются к тому, что у вас было, и переустановка его без флага и без терминала — для обновления, например — сохраняет вашу выборку как есть. В терминале без флага `add` открывает выбор вместо этого, предварительно отмечен значениями по умолчанию автора, и то, что вы отметите, заменит вашу выборку. -## Управляйте тем, что включено +## Управление включёнными ```bash -failproofai policies # все источники в одном списке, наборы включены -failproofai pack list # только наборы, сгруппированные по категориям -failproofai policies --uninstall block-refunds # выключить одну политику набора +failproofai policies # каждый источник в одном списке, пакеты включены +failproofai policies add block-rm-rf # включить одну политику +failproofai policies --uninstall block-refunds # выключить одну политику пакета failproofai policies --install block-refunds # и включить обратно -failproofai pack remove acme/support-agent +failproofai policies remove acme/support-agent # удалить пакет ``` -Голое имя означает **встроенную** политику, когда таковая существует под этим именем. Назовите копию набора явно, когда вам нужно: +Включение или выключение политики пакета применяется на всю машину: переключатель записывается вместе с установленным пакетом, а не в конфигурацию проекта, что бы ни говорил `--scope`. + +Имя без слеша — это политика; всё с одним — это источник пакета. Простое имя разрешается в установленный пакет, который его объявляет. Когда два установленных пакета объявляют одно имя, назовите нужный вам: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -Если набор поставляет политику, имя которой также совпадает с **включённой встроенной**, встроенная политика запускается и копия из набора пропускается — в противном случае одна и та же защита оценивалась бы дважды. Выключите встроенную, чтобы вместо этого использовать копию из набора. - - -## Откуда берутся политики Failproof AI - -`core` читает копию, поставляемую с npm-пакетом. Тот же набор публикуется как выпуск GitHub, который вы устанавливаете, если хотите конкретную версию: - -```bash -failproofai pack add core # из этого пакета, без сети -failproofai pack add FailproofAI/policies # тот же набор, из его выпуска GitHub -``` +Области, параметры и файлы, которые эти команды записывают, рассматриваются в [локальной конфигурации](/ru/policies/local-configuration). ## Что даёт целостность и что нет -`SHA256SUMS` поставляется в том же выпуске, что и артефакт, поэтому это **не** подпись и ничего не доказывает о том, кто его опубликовал. Что она доказывает, так это то, что байты — это те, которые опубликовал выпуск — и поскольку хеш записывается при добавлении набора и перепроверяется перед каждым импортом, набор не может измениться на вашей машине впоследствии. Репозиторий, который переделывает теги или заменяет активы, перестаёт загружаться вместо того, чтобы молча запустить что-то другое. +`SHA256SUMS` поставляется в том же release, что и артефакт, поэтому это **не** подпись и ничего не доказывает о том, кто его опубликовал. Что она доказывает, так это то, что байты — это те, которые опубликовал этот release — и потому что дайджест записывается при добавлении пакета и повторно проверяется перед каждым импортом, пакет не может измениться на вашей машине впоследствии. Репозиторий, который переназначает или заменяет ресурс, перестаёт загружаться вместо того, чтобы тихо запустить что-то другое. -При установке набор также **импортируется один раз** и проверяется против своего собственного манифеста. Набор, артефакт которого не разбирается, или который регистрирует что-то другое, чем он объявляет, отказывается перед активацией чего-либо — вместо чистой установки и отказа при следующем вызове инструмента. +При установке пакет также **импортируется один раз** и проверяется против собственного манифеста. Пакет, чей артефакт не парсится или регистрирует что-то иное, чем он объявляет, отклоняется перед тем, как что-либо активируется — вместо чистой установки и сбоя при следующем вызове инструмента. -## Когда набор не загружается +## Когда пакет не загружается -Набор, который эта машина должна была принудительно применять и не может запустить, **отрицает** события, которые охватывали его отсутствующие политики, вместо того чтобы молча разрешить их. Смотрите [Поведение при отказе](/ru/policies/failure-behavior). `failproofai pack list` выводит названия любого набора в таком состоянии и выходит с ненулевым кодом. +Пакет, который эта машина была приказана проверять и не может запустить, **отрицает** события, которые охватывали его отсутствующие политики, вместо того чтобы молчаливо их разрешить — как `pack/failproofai-pack-unavailable`, что перевешивает политики, которые загрузились, так что отрицание приписывается отсутствующему пакету, а не той охране, которая случайно сработала первой. Исключением является `UserPromptSubmit`, которое инструктирует вместо этого: отрицание там запер бы вас в агенте, который нужен для исправления. Смотрите [Поведение при сбое](/ru/policies/failure-behavior). -## Вне сети и зеркала +## Оффлайн и зеркала | Переменная | Эффект | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Отказывает в загрузке; уже установленные наборы продолжают применяться | -| `FAILPROOFAI_PACK_BASE_URL` | Направляет загрузку наборов на зеркало вместо `github.com` | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Отказывает в загрузке; уже установленные пакеты продолжают действовать | +| `FAILPROOFAI_PACK_BASE_URL` | Указывает загрузку пакетов на зеркало вместо `github.com` | -Публикация собственного набора: смотрите [Опубликуйте набор](/ru/policies/publish-a-pack). \ No newline at end of file +Чтобы поделиться своими политиками таким образом, смотрите [Опубликовать пакет политик](/ru/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/ru/policies/publish-a-pack.mdx b/docs/ru/policies/publish-a-pack.mdx index 5298b450..9d006b72 100644 --- a/docs/ru/policies/publish-a-pack.mdx +++ b/docs/ru/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "Опубликовать пак" -description: "Распространяйте собственные политики как релиз на GitHub, который сможет установить любой." +title: "Опубликовать пакет политик" +description: "Выпустите свои политики как GitHub release, которые может установить кто угодно." icon: "upload" --- -Пак — это три файла, прикреплённые к релизу GitHub. `failproofai pack build` записывает все три из файла политики, который у вас уже есть. +Пакет — это три файла, прикреплённые к GitHub release. `failproofai publish` создаёт все три из файлов политик, создаёт release и загружает их. ## 1. Напишите политики -Один файл, используя тот же API, что и любая пользовательская политика. Два дополнительных поля важны для пака: +Начните с чего-то, что уже работает, а не с шаблона с пропусками: + +```bash +failproofai publish --init +``` + +Это спросит название пакета, напишет `.mjs` и остановится — никакой сети, никакого git, ничего не опубликовано. Файл, который он создаёт — это одна политика, которая уже блокирует `git push --force`. Он не перезаписывает существующие файлы. + +Политики используют тот же API, что и любая пользовательская политика. Два дополнительных поля важны для пакета: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -16,8 +24,8 @@ import { customPolicies, deny, allow } from "failproofai"; customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", - category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + category: "Billing", // группирует её, и это то, что выбирает --category + defaultEnabled: true, // включается обычной командой `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` по умолчанию равен **false**, если вы его опустите. Обычный `failproofai pack add` включает только то, что вы отметили — установка всех политик незнакомца без надзора — это решение, которое установщик не должен принимать за своего пользователя. +`defaultEnabled` по умолчанию равен **false**, если вы его опустите. Обычная команда `failproofai policies add` включает только отмеченные вами политики — установка всех политик незнакомца без присмотра — это не решение, которое установщик должен принимать за своего пользователя. + +Напишите столько файлов, сколько хотите; по одному на категорию читается хорошо. Каждый файл в директории, который регистрирует политики, будет собран в единый артефакт, который должен быть пакет. -Точка входа должна быть **одним автономным файлом**. Только точка входа закреплена хешем, поэтому пак, который импортирует локальные файлы, не может честно заявлять, что хеш покрывает то, что запускается. Сначала объедините файлы (`esbuild`, `bun build`, `rollup`) и создайте пак из объединённого кода — `pack build` отказывается от локального импорта, а не отправляет обещание, которое не может выполнить. + Сборка требует **bun**. Без него придерживайтесь одного самостоятельного файла. В любом случае опубликованная точка входа не должна импортировать локальные файлы при установке: только точка входа имеет закреплённый дайджест, поэтому пакет, который загружал соседние файлы, не мог бы честно утверждать, что дайджест охватывает то, что запускается — и `publish` отказывает в таком случае, чтобы не отправить обещание, которое не может быть выполнено. -## 2. Создайте ресурсы релиза +## 2. Сначала попробуйте здесь + +Перед тем, как это смогут увидеть другие, примените файл на этой машине: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +Любой путь, любое имя файла. Попросите вашего агента выполнить то, что вы заблокировали, и смотрите, как это будет отклонено. Ничего не опубликовано и никто другой не затронут. [Протестировать политику](/ru/policies/test) охватывает остальное: правомерный случай, который она должна разрешить, и входные данные, которые её сломают. + +## 3. Опубликуйте + +```bash +failproofai publish ``` -Он записывает три файла и проверяет каждую политику с помощью **собственных правил загрузчика** — поэтому пак, который никогда не установится, заканчивается здесь, где вы можете это исправить: +Она выясняет, где опубликовать, что собирать и какой версии это дать, и только спрашивает, когда репозиторий ничего не подсказывает. По порядку, останавливаясь перед созданием release, если что-то не так: + +1. Находит файлы политик здесь по **содержимому** — те, что импортируют `failproofai` и вызывают `customPolicies.add` — а не по имени файла, так что находит `guards.mjs` и игнорирует несвязанный `policies.mjs`. Она не спускается в подпапки, так что тестовый fixture никогда не будет случайно собран. +2. Читает репо из `git remote get-url origin`, в **директории файла**, а не в вашей, и определяет версию. +3. Находит ваши учётные данные: `GITHUB_TOKEN`, `GH_TOKEN` или `gh auth login`. Нужны права release-write и ничего больше, никогда не выводится. +4. Создаёт репозиторий, если он не существует. Это происходит перед сборкой, так что пакет, отклонённый на следующем шаге, может оставить новый репозиторий без release в нём. +5. Создаёт три ресурса, валидируя их **собственными правилами загрузчика** — тем же кодом, который решает, что может быть установлено на чужой машине — так что пакет, который никогда не сможет быть установлен, отказывается здесь, где вы ещё можете его исправить. +6. Создаёт или переиспользует release и загружает, заменяя ресурсы с тем же именем. -| Файл | Что это такое | +| Файл | Что это | | --- | --- | -| `failproofai-pack.json` | Манифест: id, версия, эффект и по одной записи на политику | -| `failproofai-pack.mjs` | Ваша точка входа, без изменений | -| `SHA256SUMS` | ` ` для остальных двух | +| `failproofai-pack.json` | Манифест: id, версия, эффект и одна запись на политику | +| `failproofai-pack.mjs` | Ваша собранная точка входа | +| `SHA256SUMS` | ` ` для двух остальных | -Отклонено на этапе сборки: id, который не имеет формата `publisher/name`, имя политики, содержащее `/`, политика, объявляющая `alwaysOn`, отсутствующие `description`, `category` или `match`, точка входа, которая ничего не регистрирует, и точка входа, которая импортирует локальные файлы. +Имена ресурсов фиксированы — это то, из чего CLI потребителя конструирует URL, без вызова API и без поиска. -## 3. Прикрепите их к релизу +Отклонено при сборке: id, который не `publisher/name`, имя политики с `/`, политика, объявляющая `alwaysOn`, отсутствующее `description`, `category` или `match`, точка входа, которая ничего не регистрирует, и точка входа, которая импортирует локальные файлы. -Пометьте релиз той же версией, которую вы создали, и прикрепите все три файла как ресурсы релиза: +Переопределите всё, что она решила: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -Теперь любой сможет его установить: +`--id` устанавливает id пакета, когда он должен отличаться от репо, `--tag` устанавливает тег release, `--notes` заменяет сгенерированные примечания release — это то, откуда `policies show --releases` читает счётчики и коммит каждого release — `--out` выбирает, где писать ресурсы (по умолчанию `dist-pack`), и `--dry-run` создаёт их без публикации и не нужны учётные данные. -```bash -failproofai pack add acme/support-agent -``` +Теперь кто угодно может установить его с помощью `failproofai policies add acme/support-agent`. Смотрите [пакеты политик](/ru/policies/packs) для закрепления версии и взятия только части одного. + +### Выведите его на хаб политик -Имена ресурсов фиксированы — это то, из чего CLI потребителя создаёт свои URL-адреса, без вызова API и без обнаружения. +Добавьте тему `failproofai-policies` к репозиторию на GitHub. Нет формы отправки и нет очереди одобрения: [хаб политик](https://befailproof.ai/policy-hub/) сканер подхватывает репозиторий при следующем проходе. Тема только выводит его на рассмотрение — то, что выводит его в список — это release, чей манифест проверяется против его собственного `SHA256SUMS` и разбирается по тем же правилам, которые использует CLI, что точно производит `failproofai publish`. -## Отправка новой версии +## Как определяется версия -Создайте пак с новым `--version`, пометьте новый релиз, снова прикрепите три ресурса. Потребители запускают одну и ту же `pack add` и сохраняют любое подмножество, которое они выбрали; политика, которую они отключили, остаётся отключённой при обновлении. +Версия — это **коммит, из которого вы публикуете** — его короткий sha, двенадцать символов: `a1b2c3d4e5f6`. Нет ничего, что нужно выбирать и ничего, что нужно увеличивать, и версия точно называет то, откуда пришли байты, так что публикация одного и того же источника дважды даёт одну и ту же версию. -Изменение **имени** политики — это критическое изменение: машина, которая отключила его, отключает имя, которого больше не существует, и новое имя поступает с любым `defaultEnabled` сказано. +Она читается из дерева перед вами, никогда не из release репозитория, так что свежий клон и машина без интернета вычисляют один и тот же ответ без запроса GitHub о том, что было раньше. + +Потому что версия называет коммит, этот коммит должен существовать. При терминале `publish` создаёт его для вас: инициализирует репозиторий, когда его нет, и коммитит изменённые файлы политик перед сборкой. Она **отказывает** вместо этого — называя `--version` как выход — когда работает без терминала (коммит, сделанный на CI runner, не существовал бы больше нигде), когда файлы кроме политик не закоммичены, или в checkout, который не имеет коммитов вообще. Тег на `HEAD` выигрывает над sha — тот, кто отметил `v1.2.0`, сказал, что это release. + +Sha не имеет собственного упорядочения, так что используйте `failproofai policies show / --releases` чтобы увидеть, какой release был первым — новейший вверху. + +## Доставка новой версии + +Закоммитьте изменение и запустите `failproofai publish` снова — новый коммит — это новая версия. Потребители запускают один и тот же `failproofai policies add`. Без терминала или с флагом выбора, они сохраняют подмножество, которое выбрали, и политика, которую они отключили, остаётся отключенной; при терминале без флага, выбиратель открывается с предварительно отмеченными вашими значениями по умолчанию и их ответ заменяет их выбор. + +Изменение **имени** политики — это критическое изменение: машина, которая отключила её, отключает имя, которое больше не существует, и новое имя приходит с тем, что говорит `defaultEnabled`. ## Чему доверяют ваши пользователи -`SHA256SUMS` находится в том же релизе, что и артефакт, поэтому это доказывает, что байты — это те, которые вы опубликовали, — не кто вы. Любой, кто может писать в репозиторий, может писать оба файла. Защита ваших пользователей заключается в том, что хеш закреплён при установке, поэтому то, что вы отправили, не может измениться под ними впоследствии. +`SHA256SUMS` находится в одном release с артефактом, так что доказывает, что байты — это те, что вы опубликовали — не то, кто вы. Тот, кто может писать в репозиторий, может писать оба файла. Защита ваших пользователей в том, что дайджест закреплён при установке, так что то, что вы отправили, не может измениться под ними после этого. + +Публикуйте из репозитория, доступ на запись в который вы контролируете, и относитесь к выпуску пакета как к публикации пакета. -Публикуйте из репозитория, доступ на запись в который вы контролируете, и относитесь к релизу пака как к публикации пакета. +Репозиторий также должен быть **публичным**. Установки — это анонимный HTTPS без учётных данных, так что существующий приватный репо отказывается перед тем, как что-либо собирается или загружается, и один `publish` создаёт публичный по той же причине. `--allow-private` переопределяет это для кого-то, передающего три ресурса другим способом, и говорит ясно, что никакой `policies add` не сможет их достичь. Только release имеет значение: установки читают `releases/download//` и никогда не трогают ваше git дерево. -## Наблюдайте перед применением +## Наблюдайте перед тем, как применять -Манифест может объявить `"effect": "observe"`. Эти политики запускаются, и их вердикты **записываются и отбрасываются** — ничего не блокируется. Это способ оценить новое правило на реальном трафике перед тем, как оно сможет прерывать чью-либо работу. +Манифест может объявить `"effect": "observe"` — `failproofai publish --effect observe` это то, что это устанавливает. Те политики запускаются и их вердикты **записываются и отбрасываются** — ничего не блокируется. Это способ измерить новое правило против реального трафика перед тем, как оно может помешать чьей-либо работе. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/ru/policies/rollback.mdx b/docs/ru/policies/rollback.mdx index 26743413..0f409f7d 100644 --- a/docs/ru/policies/rollback.mdx +++ b/docs/ru/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "Откат" -description: "Восстановление известного развертывания политики при сбое, нарушающем корректную работу агента." +title: "Версии и откат" +description: "Каждая опубликованная версия неизменяема, поэтому откат неудачного развертывания выполняется путем переразвертывания последней рабочей версии." icon: "rotate-ccw" --- -Откат изменяет развернутую версию или удаляет назначение политики; он не стирает историю решений, которая объясняет инцидент. +Опубликованная версия политики никогда не изменяется. При редактировании политики и повторной публикации создается новая версия; старая версия на машинах остается нетронутой. Это делает откат безопасным: последняя рабочая версия по-прежнему там, без единого изменения, и откат не стирает историю решений, которая объясняет, что пошло не так. -## Откатить машину +## Найти версию - - 1. Перейдите на страницу **Admin → enforcement**, разверните затронутую машину и определите последний известный хороший набор политик. - 2. Выберите **edit**, восстановите те версии и эффекты, и примените новое развертывание. - 3. Дождитесь синхронизации машины, затем проверьте сообщаемое развертывание. - 4. Откройте **Observe → policy** и затронутые сессии, чтобы убедиться, что корректная работа больше не блокируется. + + Откройте **Admin → policy editor** и **library**, чтобы сравнить версии политики или отключить одну из них. + + + ```bash + fp policies list # все версии политик + fp policies show # одна версия с её исходным кодом + ``` + + + +## Откатить машину + + + 1. Откройте **Admin → enforcement**, разверните нужную машину и определите её последний известный рабочий набор политик. + 2. Выберите **edit**, восстановите эти версии и эффекты, затем примените новое развертывание. + 3. Дождитесь проверки машины, затем проверьте сообщаемое развертывание. + 4. Откройте **Observe → policy** и нужные сеансы, чтобы подтвердить, что корректная работа больше не блокируется. - Откат облачного развертывания — это рабочий процесс панели управления. Используйте локальный статус для подтверждения того, что исправленное развертывание достигло машины: + Каждое развертывание на машину — это пронумерованное поколение. Перечислите их, затем восстановите нужное: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` приостанавливает встроенные, пользовательские и конвенционные политики на одну локальную сессию. Он не приостанавливает управляемые облаком политики, поэтому не является обходным решением для неправильного облачного развертывания. + `rollback` создает новое поколение со старым набором, а не перематывает счетчик, поэтому история остается добавочной. Команда отказывает, если указать поколение с отключенной или удаленной политикой. Требуется сеанс с авторизацией и правами `policies:write`. `fp fleet diff ` показывает, что было предусмотрено в сравнении с тем, что машина применила — это отображается как `behind`, пока машина не проведет следующий опрос — а на самой машине `failproofai policies` перечисляет развертывание, которое она запускает. -## Когда выполнять откат +## Отключить одну политику на всех машинах + +```bash +fp policies disable # удалить её из всех развертываний, её содержащих +fp policies enable # добавить её обратно +``` + +Каждая команда создает новое поколение на каждом развертывании, которое она затрагивает. Откат одного из этих поколений — не способ отменить `disable`, хотя — `rollback` отказывает при указании поколения с отключенной политикой, и каждое поколение до отключения называет эту политику. `fp policies enable` — это способ вернуться, и она в свою очередь создает собственное поколение. + +## Откатить пакет + +Пакет привязан к установленному выпуску, поэтому его откат означает установку более ранней версии: + +```bash +failproofai policies show FailproofAI/policies --releases # каждая опубликованная версия и какая установлена здесь +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # привязать эту версию +``` + +Без терминала или с опциями `--policy`, `--category` или `--all` переустановка сохраняет выбранный вами подмножество. В терминале без этих опций открывается выбиратель с предустановками автора, и выбранные вами элементы заменяют вашу прежнюю выборку — поэтому переустановите то, что у вас было. + +## Когда откатывать -- Политика блокирует ожидаемое производственное действие. -- Объем совпадений значительно выше, чем предсказано при наблюдаемом развертывании. +- Политика блокирует ожидаемое действие в production. +- Объем совпадений существенно выше, чем предсказывало наблюдаемое развертывание. - Политика зависит от полей, которые интеграция не предоставляет. -- Новая версия изменяет поведение вне предполагаемого режима отказа. +- Новая версия меняет поведение вне предусмотренного режима отказа. -После отката откройте затронутые сессии и определите условие, вызвавшее ложный срабатыванию. Создайте новую версию, протестируйте как небезопасные, так и допустимые случаи, затем повторите фазу наблюдения. +После отката откройте затронутые сеансы и найдите условие, стоящее за ложноположительным срабатыванием. Опубликуйте новую версию, [протестируйте](/ru/policies/test) как небезопасный, так и допустимый случаи, и проверьте её снова перед принудительным применением. - Приостановка принудительного применения может быть уместна во время инцидента, но она расширяет уязвимость для каждой активной политики в этой области. Предпочитайте откат конкретной версии политики, когда это возможно. + `failproofai config --pause` приостанавливает локальные политики на один сеанс и никогда не приостанавливает управляемые Cloud, поэтому это не способ выхода из неудачного Cloud-развертывания. Пауза также расширяет уязвимость для каждой политики в её области; предпочтите откат единственной версии, которая неправильно себя ведет. \ No newline at end of file diff --git a/docs/ru/policies/test.mdx b/docs/ru/policies/test.mdx new file mode 100644 index 00000000..7fd93efd --- /dev/null +++ b/docs/ru/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "Протестировать политику" +description: "Проверьте черновик на основе уже полученного трафика, убедитесь, что он блокирует то, что нужно, и пропускает то, что должно пройти, прежде чем машина будет его применять." +icon: "flask-conical" +--- + +Протестируйте каждую политику двумя способами: на трафике, который уже произвели ваши агенты, и на законной операции, которую политика должна пропустить. Политика, которая видела только небезопасный сценарий, не протестирована. + +## Протестировать черновик + + + + Редактор политик воспроизводит черновик по вызовам, которые уже сделал ваш флот, прежде чем вы его опубликуете. + + 1. Откройте черновик в **Admin → policy editor**. Редактор подтверждает, что он парсится как JavaScript. + 2. В **backtest** выберите агентов и временное окно для воспроизведения — по умолчанию **every agent** и **30d** — и оставьте последний фильтр на **everything**, если вы не хотите его сужать. + 3. Выберите **run backtest**. + + ![Панель backtest под черновиком, который парсится как JavaScript, с тремя фильтрами и действием run backtest, выше publish version.](/images/dashboard/policy-backtest.png) + + Результат показывает, что бы черновик сделал с этими вызовами — включая количество **работающих** вызовов, которые он прервал бы. Это ложные срабатывания, найденные до того, как агенты их встретят: уточните черновик и запустите его снова, пока это число не станет приемлемым. + + + Тестирование на истории — функция панели управления. Из терминала вместо этого запустите политику на событиях, которые вы описываете, как показано ниже. + + + +## Запустить её на описанном событии + +`fp policies test` запускает файл политики на вашем компьютере на синтетическом событии и проверяет решение. Ничего не публикуется и ничего не достигает облака: + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +Сформируйте событие с помощью `--event`, `--tool`, `--command` и `--file`. Фильтр `match` самой политики по-прежнему применяется, поэтому политика, которая не охватывает описанное вами событие, выдаст `skipped` вместо решения — обычно признак того, что её `match` уже, чем вы имели в виду. + +## Запустить её на одной машине + +Затем примените её на самом деле на своей машине против собственного агента: + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +Первая команда проверяет и устанавливает файл; вторая подтверждает, что он загрузился вместе со всем остальным, что здесь применяется. Попросите агента сделать то, что политика блокирует, и смотрите, как это будет отклонено, затем выполните законную версию и смотрите, как она пройдёт. Никто другой не будет затронут. + +На машине, подключённой к облаку, проверьте оба решения в **Observe → policy**: отфильтруйте по названию политики, затем откройте каждый связанный сеанс, чтобы подтвердить ввод инструмента, на который она сработала, и причину возвращённого результата. + +## Протестировать то, что может сломаться + +Установка отклоняет отсутствующий файл, синтаксическую ошибку, неразрешённый импорт, исключение верхнего уровня или модуль, который замирает при загрузке — поэтому переустановите после каждого изменения файла или всего, что он импортирует. Во время применения тот же сломанный файл логируется и **пропускается**, поэтому каждая другая политика продолжит работу: рассматривайте предупреждение о загрузке в журналах производства как потерянное применение. Файлы соглашений загружаются без команды install, поэтому сохраняйте явный шаг `failproofai policies --install --custom ` в CI — это то, что вызывает отказ сборки при сломанной политике. + +Затем скормите ей то, что агенты действительно отправляют, а не только ожидаемый ввод: отсутствующие поля, альтернативные названия инструментов, такие как `Write` и `Edit`, пути Windows, неправильно сформированный ввод. Возвращайте намеренный `allow`, `instruct` или `deny` на каждом пути, сохраняйте функцию детерминированной и ограничивайте любой внешний вызов коротким таймаутом. + +## Затем опубликуйте и наблюдайте за ней + +Тестирование на истории показывает, что бы политика сделала с трафиком, который у вас был; оно не может показать, что сделает трафик, который вы ещё не видели. Выберите **publish version** в редакторе (или запустите `fp policies publish`), затем [разверните его](/ru/policies/deploy) сначала в режиме **observe** — его вердикты записываются и ничего не блокируется — и применяйте, когда его совпадения разделят небезопасные действия от допустимых. \ No newline at end of file diff --git a/docs/ru/reference/cloud-cli.mdx b/docs/ru/reference/cloud-cli.mdx index 3c8cfba5..cace1bef 100644 --- a/docs/ru/reference/cloud-cli.mdx +++ b/docs/ru/reference/cloud-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof Cloud CLI" -description: "Полный справочник для запроса и администрирования Failproof AI Cloud с помощью fp." +description: "Полный справочник по запросам и администрированию Failproof AI Cloud с помощью fp." icon: "cloud-cog" --- -Используйте `fp` для проверки телеметрии Cloud, управления облачным вынужденным применением (политиками, развёртываниями флота, решениями guardrail) и управления аудитами, выводами, проблемами, оповещениями, ключами, пользователями, запросами и параметрами. Используйте [`failproofai`](/ru/reference/failproof-cli) для локальных перехватчиков, политик, захвата и регистрации машин. +Используйте `fp` для проверки телеметрии Cloud, управления облачным enforcement (политики, развертывания флота, решения guardrail), а также управления аудитами, findings, issues, alerts, ключами, пользователями, запросами и параметрами. Используйте [`failproofai`](/ru/reference/failproof-cli) для локальных hooks, политик, захвата и регистрации машин. -Установите выпущенный Cloud CLI как отдельный инструмент: +Установите выпущенный Cloud CLI как изолированный инструмент: ```bash uv tool install fp-cloud-cli @@ -26,7 +26,7 @@ fp whoami fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` -Глобальные параметры должны идти перед командой: +Глобальные параметры должны предшествовать команде: ```bash fp --json sessions --since 24h @@ -40,11 +40,11 @@ fp --json sessions --since 24h | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp login` | Войдите с использованием одноразового кода, отправленного по электронной почте, и выберите организацию. | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | Отозвать и удалить сохранённый сеанс пользователя. | — | -| `fp whoami` | Показать текущую идентификацию, режим аутентификации, организацию и разрешения. | — | +| `fp login` | Вход с использованием одноразового кода, отправленного по электронной почте, и выбор организации. | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | Отозвать и удалить сохраненный сеанс пользователя. | — | +| `fp whoami` | Показать текущую идентичность, режим аутентификации, организацию и разрешения. | — | | `fp version` | Показать установленную версию CLI. | — | -| `fp help` | Показать справку по командам верхнего уровня. | — | +| `fp help` | Показать справку по команде верхнего уровня. | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,23 +57,23 @@ fp whoami fp events [OPTIONS] ``` -Список отдельных событий агента. Лёгкий поток по умолчанию исключает необработанные данные; используйте `--full` только для ограниченного расследования. +Выводит отдельные события агента. Легкий поток по умолчанию исключает необработанные полезные нагрузки; используйте `--full` только для ограниченного исследования. | Параметр | Описание | | --- | --- | -| `--limit`, `-n ` | Максимальное количество строк. По умолчанию: `50`. | +| `--limit`, `-n ` | Максимум всего строк. По умолчанию: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` или `7d`. | | `--from ` / `--to ` | Диапазон ISO 8601 UTC; переопределяет `--since`. | -| `--env ` | Фильтр окружения; повторите или разделите запятыми. | -| `--event-type ` | Фильтр типа события; повторите или разделите запятыми. | -| `--agent-id ` | Фильтр агента; повторите или разделите запятыми. | -| `--session-id ` | Фильтр сеанса; повторите или разделите запятыми. | -| `--search ` | Поиск текста в данных; повторяемо, с совпадением любого условия. | +| `--env ` | Фильтр окружения; повторяется или разделяется запятыми. | +| `--event-type ` | Фильтр типа события; повторяется или разделяется запятыми. | +| `--agent-id ` | Фильтр агента; повторяется или разделяется запятыми. | +| `--session-id ` | Фильтр сеанса; повторяется или разделяется запятыми. | +| `--search ` | Поиск текста в полезной нагрузке; повторяется с совпадением любого условия. | | `--order asc\|desc` | Порядок времени. По умолчанию: сначала новые. | -| `--all` | Автоматическая пагинация до `--limit`. | +| `--all` | Автоматическое разбиение на страницы до `--limit`. | | `--cursor ` | Возобновить с непрозрачного курсора. | -| `--page-size ` | Строк за запрос с `--all`; максимум `200`. | -| `--full` | Включить необработанные данные через более тяжелую конечную точку события. | +| `--page-size ` | Строк на запрос с `--all`; максимум `200`. | +| `--full` | Включить необработанные полезные нагрузки через более тяжелую конечную точку события. | | `--fields ` | Возвращать только выбранные поля; запрос `payload` включает полный режим. | ```bash @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` пагинирует **до `--limit`**, по умолчанию **50** — так что `--all` в одиночку останавливается на 50 строках. Когда он останавливается рано, ответ содержит `next_cursor` для возобновления; `"next_cursor": null` означает, что поток действительно был исчерпан. + `--all` разбивает на страницы **до `--limit`**, который по умолчанию равен **50** — поэтому `--all` само по себе останавливается на 50 строках. Когда он останавливается рано, ответ содержит `next_cursor` для возобновления; `"next_cursor": null` означает, что поток действительно исчерпан. ### Сеансы @@ -93,19 +93,19 @@ fp sessions [OPTIONS] | Параметр | Описание | | --- | --- | -| `--limit`, `-n ` | Максимальное количество строк. По умолчанию: `50`. | +| `--limit`, `-n ` | Максимум всего строк. По умолчанию: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` или `7d`. | | `--from ` / `--to ` | Диапазон ISO 8601 UTC; переопределяет `--since`. | -| `--env ` | Фильтр окружения; повторите или разделите запятыми. | -| `--status ` | `done`, `error` или `timeout`; повторите или разделите запятыми. | -| `--agent-id ` | Сеансы с участием любого выбранного агента. | -| `--session-id ` | Фильтр сеанса; повторите или разделите запятыми. | -| `--all` | Автоматическая пагинация до `--limit`. | +| `--env ` | Фильтр окружения; повторяется или разделяется запятыми. | +| `--status ` | `done`, `error` или `timeout`; повторяется или разделяется запятыми. | +| `--agent-id ` | Совпадают сеансы, включающие любого выбранного агента. | +| `--session-id ` | Фильтр сеанса; повторяется или разделяется запятыми. | +| `--all` | Автоматическое разбиение на страницы до `--limit`. | | `--cursor ` | Возобновить с непрозрачного курсора. | -| `--page-size ` | Строк за запрос с `--all`; максимум `200`. | +| `--page-size ` | Строк на запрос с `--all`; максимум `200`. | | `--fields ` | Возвращать только выбранные поля. | -| `--full-ids` | Не сокращайте идентификаторы сеансов в выводе терминала. | -| `--agents` | Расширить реестр агентов для многоагентных сеансов. | +| `--full-ids` | Не сокращать ID сеансов в выводе терминала. | +| `--agents` | Развернуть список агентов для многоагентных сеансов. | ### Оценки @@ -116,14 +116,14 @@ fp evals [OPTIONS] | Параметр | Описание | | --- | --- | | `--aggregate` | Показать итоги и статистику по баллам вместо отдельных оценок. | -| `--limit`, `-n ` | Максимум строк списка. По умолчанию: `50`. | -| `--since`, `--from`, `--to` | Выбрать диапазон времени. | -| `--env`, `--status`, `--agent-id`, `--session-id` | Сузить на одно точное значение за фильтр. | -| `--score KEY:MIN..MAX` | Диапазон баллов; повторяемо, все диапазоны должны совпадать. | -| `--all`, `--cursor`, `--page-size` | Управление пагинацией списка. | +| `--limit`, `-n ` | Максимум строк в списке. По умолчанию: `50`. | +| `--since`, `--from`, `--to` | Выбрать временной диапазон. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Сузить до одного точного значения за фильтр. | +| `--score KEY:MIN..MAX` | Диапазон баллов; повторяется и все диапазоны должны совпадать. | +| `--all`, `--cursor`, `--page-size` | Управлять разбиением на страницы списка. | | `--fields ` | Возвращать только выбранные поля. | -| `--full-ids` | Показать полные идентификаторы сеансов. | -| `--scores-full` | Показать все баллы в выводе терминала. | +| `--full-ids` | Показать полные ID сеансов. | +| `--scores-full` | Показать каждый балл в выводе терминала. | ### Ошибки @@ -133,36 +133,36 @@ fp errors [OPTIONS] | Параметр | Описание | | --- | --- | -| `--aggregate` | Обобщить совпадающие ошибки вместо списка строк. | -| `--limit`, `-n ` | Максимум строк списка. По умолчанию: `50`. | -| `--since`, `--from`, `--to` | Выбрать диапазон времени. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Сузить совокупность ошибок. | -| `--search ` | Поиск текста в данных; повторяемо. | +| `--aggregate` | Суммировать совпадающие ошибки вместо вывода строк. | +| `--limit`, `-n ` | Максимум строк в списке. По умолчанию: `50`. | +| `--since`, `--from`, `--to` | Выбрать временной диапазон. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Сузить популяцию ошибок. | +| `--search ` | Поиск текста в полезной нагрузке; повторяется. | | `--order asc\|desc` | Порядок времени. | -| `--all`, `--cursor`, `--page-size` | Управление пагинацией списка. | +| `--all`, `--cursor`, `--page-size` | Управлять разбиением на страницы списка. | | `--fields ` | Возвращать только выбранные поля. | -| `--full-ids` | Показать полные идентификаторы сеансов. | +| `--full-ids` | Показать полные ID сеансов. | ### Использование и значения фильтров | Команда | Назначение | | --- | --- | -| `fp usage` | Показать использование для текущего окна учёта. | -| `fp list envs` | Список наблюдаемых окружений. | -| `fp list agents` | Список наблюдаемых идентификаторов агентов. | -| `fp list event_types` | Список типов событий. | -| `fp list score_filters` | Список ключей баллов оценки. | -| `fp list models` | Список названий моделей. | -| `fp list hooks` | Список названий перехватчиков. | -| `fp list tools` | Список названий инструментов. | -| `fp list error_types` | Список типов ошибок. | +| `fp usage` | Показать использование для текущего окна измерения. | +| `fp list envs` | Вывести наблюдаемые окружения. | +| `fp list agents` | Вывести наблюдаемые ID агентов. | +| `fp list event_types` | Вывести типы событий. | +| `fp list score_filters` | Вывести ключи баллов оценки. | +| `fp list models` | Вывести имена моделей. | +| `fp list hooks` | Вывести имена hooks. | +| `fp list tools` | Вывести имена инструментов. | +| `fp list error_types` | Вывести типы ошибок. | ### Организации | Команда | Назначение | | --- | --- | -| `fp orgs list` | Список доступных организаций. | -| `fp orgs switch [SLUG]` | Сохранить активную организацию; запрашивает при пропуске. | +| `fp orgs list` | Вывести доступные организации. | +| `fp orgs switch [SLUG]` | Сохранить активную организацию; запрашивает, если опущено. | | `fp orgs current` | Показать активную организацию. | | `fp orgs perms` | Показать ваши разрешения в активной организации. | @@ -170,32 +170,32 @@ fp errors [OPTIONS] | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp keys list` | Список ключей организации. | `--show-id`; `--fields ` | +| `fp keys list` | Вывести ключи организации. | `--show-id`; `--fields ` | | `fp keys show NAME` | Показать один ключ и его гранты. | — | -| `fp keys create NAME` | Создать ключ и раскрыть его секрет один раз. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | Заменить набор разрешений или отрегулировать гранты. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | Ротация секрета и раскрытие замены один раз. | `--yes`, `-y` | -| `fp keys disable NAME` | Безвозвратно отозвать ключ. | `--yes`, `-y` | +| `fp keys create NAME` | Создать ключ и открыть его секрет один раз. | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | Заменить набор разрешений или настроить гранты. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | Повернуть секрет и открыть замену один раз. | `--yes`, `-y` | +| `fp keys disable NAME` | Навсегда отозвать ключ. | `--yes`, `-y` | -Токены разрешений используют `resource:action`, такие как `events:add`. Повторите `--add`, разделите запятыми токены или используйте точечные действия, такие как `events:read.add`. +Токены разрешений используют `resource:action`, такие как `events:add`. Повторяйте `--add`, разделяйте запятыми или используйте точечные действия, такие как `events:read.add`. ### Запросы | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp query list` | Список сохранённых запросов. | `--show-id`; `--fields ` | +| `fp query list` | Вывести сохраненные запросы. | `--show-id`; `--fields ` | | `fp query show NAME` | Показать один запрос. | — | | `fp query create NAME` | Сохранить запрос. | `--sql `; `--description` | | `fp query update NAME` | Обновить или переименовать запрос. | `--name`; `--sql`; `--description`; `--yes`, `-y` | -| `fp query delete NAME` | Удалить сохранённый запрос. | `--yes`, `-y` | -| `fp query run [NAME]` | Запустить сохранённый запрос илиSQL на лету. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | Список таблиц для запроса или проверить одну таблицу. | — | +| `fp query delete NAME` | Удалить сохраненный запрос. | `--yes`, `-y` | +| `fp query run [NAME]` | Запустить сохраненный запрос или SQL на лету. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query schema [TABLE]` | Вывести доступные таблицы или проверить одну таблицу. | — | ### Пользователи | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp users list` | Список членов организации. | `--active-only`; `--show-id` | +| `fp users list` | Вывести членов организации. | `--active-only`; `--show-id` | | `fp users show EMAIL` | Показать члена и его гранты. | — | | `fp users create EMAIL` | Добавить члена. | `--permission-set`; `--add`; `--remove` | | `fp users update EMAIL` | Изменить гранты члена. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | @@ -206,45 +206,45 @@ fp errors [OPTIONS] | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp settings list` | Список параметров организации и текущих значений. | — | -| `fp settings schema` | Показать принимаемые значения и описания. | — | -| `fp settings set KEY` | Изменить существующий параметр. | ровно одно из `--value`, `--json-value`, `--file`; опционально `--yes`, `-y` | +| `fp settings list` | Вывести параметры организации и текущие значения. | — | +| `fp settings schema` | Показать принятые значения и описания. | — | +| `fp settings set KEY` | Изменить существующий параметр. | ровно одно из `--value`, `--json-value`, `--file`; опциональное `--yes`, `-y` | -### Оповещения +### Алерты | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp alerts list` | Список правил оповещения. | `--show-id` | -| `fp alerts show NAME` | Показать одно оповещение. | — | -| `fp alerts create NAME` | Создать оповещение. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | Обновить или переименовать оповещение. | параметры создания плюс `--name`; `--yes`, `-y` | -| `fp alerts delete NAME` | Удалить оповещение. | `--yes`, `-y` | +| `fp alerts list` | Вывести правила алертов. | `--show-id` | +| `fp alerts show NAME` | Показать один алерт. | — | +| `fp alerts create NAME` | Создать алерт. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | +| `fp alerts update NAME` | Обновить или переименовать алерт. | параметры create плюс `--name`; `--yes`, `-y` | +| `fp alerts delete NAME` | Удалить алерт. | `--yes`, `-y` | | `fp alerts test NAME` | Отправить тестовое уведомление. | `--channels`; `--yes`, `-y` | -Серьёзность оповещений — `info`, `warning` и `critical`. Типы триггеров — `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` и `per_event`. Интервалы оценки должны быть между 30 и 86 400 секунд. +Серьезности алертов — `info`, `warning` и `critical`. Виды триггеров — `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` и `per_event`. Интервалы оценки должны быть между 30 и 86,400 секундами. ### Аудиты | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp audits list` | Список аудитов. | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | Показать определение и состояние одного аудита. | — | +| `fp audits list` | Вывести аудиты. | `--enabled-only`; `--show-id` | +| `fp audits show NAME` | Показать одно определение аудита и состояние. | — | | `fp audits create NAME` | Создать аудит и немедленно поставить в очередь его первый запуск. | См. [параметры создания](#audit-create-options). | -| `fp audits edit NAME` | Заменить параметры аудита, сохраняя неуказанные значения. | параметры определения создания; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | Удалить аудит, его выводы и историю запусков. | `--yes`, `-y` | +| `fp audits edit NAME` | Заменить параметры аудита, сохраняя неуказанные значения. | параметры создания определения; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | Удалить аудит, его findings и историю запусков. | `--yes`, `-y` | | `fp audits run NAME` | Поставить в очередь ручной запуск. | — | -| `fp audits runs NAME` | Список истории запусков. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | Показать состояние краткого описания и получения справочного URL. | — | -| `fp audits context-set NAME` | Изменить краткое описание или справочные URL. | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | Повторно получить справочные URL. | — | -| `fp audits findings` | Список выводов. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | Показать один вывод и его доказательства. | — | -| `fp audits ack FINDING_ID` | Подтвердить вывод. | `--reason` | +| `fp audits runs NAME` | Вывести историю запусков. | `--limit`, `-n`; `--show-id` | +| `fp audits context-show NAME` | Показать краткую справку и состояние выборки ссылок справочника. | — | +| `fp audits context-set NAME` | Изменить краткую справку или ссылки справочника. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-refresh NAME` | Повторно выбрать ссылки справочника. | — | +| `fp audits findings` | Вывести findings. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | +| `fp audits finding FINDING_ID` | Показать один finding и его доказательства. | — | +| `fp audits ack FINDING_ID` | Подтвердить finding. | `--reason` | | `fp audits mute FINDING_ID` | Подавить повторяющийся паттерн. | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | Отметить паттерн как неприменимый и подавить его. | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | Отметить вывод как исправленный без будущего подавления. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | Вернуть вывод в живую очередь и очистить подавление. | — | -| `fp audits assign FINDING_ID` | Установить владельца вывода. | требуемый `--to ` | +| `fp audits dismiss FINDING_ID` | Отметить паттерн как не требующий действия и подавить его. | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | Отметить finding как исправленный без будущего подавления. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | Вернуть finding в живую очередь и очистить подавление. | — | +| `fp audits assign FINDING_ID` | Установить владельца finding. | обязательный `--to ` | #### Параметры создания аудита @@ -262,115 +262,115 @@ fp audits create checkout-reliability \ | Параметр | Описание | | --- | --- | | `--file ` | Основать определение на JSON или использовать `-` для stdin. Явные флаги переопределяют значения файла. | -| `--description ` | Укажите вопрос об отказе или цель. | -| `--enabled` / `--disabled` | Начать планирование или нет. По умолчанию: включено. | +| `--description ` | Указать вопрос о сбое или назначение. | +| `--enabled` / `--disabled` | Начать расписание включенным или выключенным. По умолчанию: включено. | | `--schedule-interval-secs ` | `3600`–`604800`. По умолчанию: `86400`. | -| `--schedule-anchor ` | Фиксированная фаза UTC в форме ISO 8601. По умолчанию: следующие 09:00 UTC. | -| `--window-mode since_last\|fixed` | Продолжить после последнего полностью проанализированного окна или повторно проверить скользящее окно. По умолчанию: `since_last`. | +| `--schedule-anchor ` | Фиксированная фаза UTC в формате ISO 8601. По умолчанию: следующие 09:00 UTC. | +| `--window-mode since_last\|fixed` | Продолжить после последнего полностью анализируемого окна или повторно проверить скользящее окно. По умолчанию: `since_last`. | | `--lookback-window-secs ` | `3600`–`7776000`. По умолчанию: `604800`. | -| `--scope ''` | Фильтр по `environments`, `agent_ids` или другим поддерживаемым полям области. | -| `--ignore-error-type ` | Исключить типы ошибок; повторите или разделите запятыми. | -| `--llm` / `--no-llm` | Включить или отключить анализ на основе агентов. По умолчанию: включено. | -| `--top-k ` | Сохранить `1`–`500` выводов. По умолчанию: `50`. | -| `--sensitivity low\|medium\|high` | Установить чувствительность отчётности. По умолчанию: `medium`. | -| `--channels ''` | Массив канала уведомлений. | -| `--text ` | Встроенное краткое описание, максимум 8 192 символа. | -| `--text-file ` | Прочитать краткое описание из файла; взаимоисключающе с `--text`. | -| `--url ` | Добавить открытую справку HTTPS; повторите до пяти раз. | - -Включите контекст во время создания, когда первый запуск его нуждается. Создание фиксирует определение и контекст вместе до начала поставленного в очередь запуска. +| `--scope ''` | Фильтровать по `environments`, `agent_ids` или другим поддерживаемым полям области. | +| `--ignore-error-type ` | Исключить типы ошибок; повторяется или разделяется запятыми. | +| `--llm` / `--no-llm` | Включить или отключить агентский анализ. По умолчанию: включено. | +| `--top-k ` | Сохранить `1`–`500` findings. По умолчанию: `50`. | +| `--sensitivity low\|medium\|high` | Установить чувствительность отчета. По умолчанию: `medium`. | +| `--channels ''` | Массив каналов уведомлений. | +| `--text ` | Встроенная краткая справка, максимум 8,192 символов. | +| `--text-file ` | Прочитать краткую справку из файла; взаимно исключающее с `--text`. | +| `--url ` | Добавить общую ссылку справочника HTTPS; повторяется до пяти раз. | + +Включите контекст при создании, если первый запуск его нуждается. Создание фиксирует определение и контекст вместе перед началом поставленного в очередь запуска. - `fp audits run` асинхронно. Опросите `fp audits runs NAME` до тех пор, пока последний запуск не завершится успешно или не потерпит неудачу, прежде чем читать его выводы. + `fp audits run` является асинхронным. Опросите `fp audits runs NAME` до тех пор, пока последний запуск не завершится успешно или не завершится ошибкой, прежде чем читать его findings. -### Проблемы +### Issues | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp issues list` | Список проблем. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | Подсчёт открытых или выбранных состояний проблемы. | `--state` | -| `fp issues show INCIDENT_ID` | Показать детали проблемы, комментарии, подписчиков и активность. | — | -| `fp issues open` | Открыть ручную или связанную с оповещением проблему. | требуемый `--summary`; опциональный `--title`, `--alert-id`, `--severity` | -| `fp issues ack INCIDENT_ID` | Подтвердить проблему. | — | -| `fp issues assign INCIDENT_ID` | Заменить ответственных; пропустите параметр, чтобы очистить их. | повторяемый `--assignee` | -| `fp issues resolve INCIDENT_ID` | Разрешить проблему. | `--yes`, `-y` | -| `fp issues comment-list INCIDENT_ID` | Список комментариев. | — | +| `fp issues list` | Вывести issues. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | Подсчитать открытые или выбранные состояния issues. | `--state` | +| `fp issues show INCIDENT_ID` | Показать детали issue, комментарии, подписчиков и активность. | — | +| `fp issues open` | Открыть ручной или связанный с алертом issue. | обязательный `--summary`; опциональные `--title`, `--alert-id`, `--severity` | +| `fp issues ack INCIDENT_ID` | Подтвердить issue. | — | +| `fp issues assign INCIDENT_ID` | Заменить ответственных; опустить опцию для их очистки. | повторяемый `--assignee` | +| `fp issues resolve INCIDENT_ID` | Разрешить issue. | `--yes`, `-y` | +| `fp issues comment-list INCIDENT_ID` | Вывести комментарии. | — | | `fp issues comment-add INCIDENT_ID` | Добавить комментарий. | ровно одно из `--body`, `--file` | | `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Удалить комментарий. | `--yes`, `-y` | -| `fp issues subscribers INCIDENT_ID` | Список подписчиков. | — | -| `fp issues subscribe INCIDENT_ID` | Подписаться сами или другой оператор. | `--email` | +| `fp issues subscribers INCIDENT_ID` | Вывести подписчиков. | — | +| `fp issues subscribe INCIDENT_ID` | Подписать себя или другого оператора. | `--email` | | `fp issues unsubscribe INCIDENT_ID` | Удалить подписку. | `--email` | -Допустимые состояния проблемы — `firing`, `acknowledged` и `resolved`. Серьёзность автономной проблемы — `info`, `warning` и `critical`. +Действительные состояния issues — `firing`, `acknowledged` и `resolved`. Серьезности автономных issues — `info`, `warning` и `critical`. -### Облачный ассистент +### Облачный помощник | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp agent health` | Проверить доступность и конфигурацию помощника. | — | -| `fp agent models` | Список доступных моделей помощника. | — | -| `fp agent chats` | Список сохранённых чатов. | — | -| `fp agent ask [MESSAGE]` | Начать или продолжить чат; читает stdin при пропуске сообщения. | `--chat`; `--model`; `--page-context` | -| `fp agent show CHAT_ID` | Показать сохранённый разговор. | — | -| `fp agent rename CHAT_ID` | Переименовать разговор. | требуемый `--title` | +| `fp agent health` | Проверить доступность помощника и конфигурацию. | — | +| `fp agent models` | Вывести доступные модели помощника. | — | +| `fp agent chats` | Вывести сохраненные чаты. | — | +| `fp agent ask [MESSAGE]` | Начать или продолжить чат; читает stdin, когда сообщение опущено. | `--chat`; `--model`; `--page-context` | +| `fp agent show CHAT_ID` | Показать сохраненный разговор. | — | +| `fp agent rename CHAT_ID` | Переименовать разговор. | обязательный `--title` | | `fp agent delete CHAT_ID` | Удалить разговор. | `--yes`, `-y` | ### Политики -Версии политик, управляемые облаком. **Только сеанс** — каждая команда здесь выходит с `2` под ключом API, перед любым запросом, потому что это маршруты записи, предназначенные только для корня, намеренно отсутствующие в `/v1`. +Версии политик, управляемые облаком. **Только сеанс** — каждая команда здесь выходит с кодом `2` под ключом API перед любым запросом, потому что это корневые маршруты записи, намеренно отсутствующие в `/v1`. | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp policies list` | Список версий политик. | `--json` | -| `fp policies show POLICY_ID` | Показать одну политику с её источником. | — | -| `fp policies publish NAME PATH` | Выпустить версию из локального `.mjs`. | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | Добавить её обратно на каждое развёртывание, с которого она была удалена, выпустив новое поколение на каждом. | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | Удалить её с каждого развёртывания, несущего её, выпустив новое поколение на каждом. | `--yes`, `-y` | +| `fp policies list` | Вывести версии политик. | `--json` | +| `fp policies show POLICY_ID` | Показать одну политику с ее исходным кодом. | — | +| `fp policies publish NAME PATH` | Создать версию из локального `.mjs`. | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | Добавить ее обратно в каждое развертывание, из которого она была удалена, создав новое поколение в каждом. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | Удалить из каждого развертывания, которое ее содержит, создав новое поколение в каждом. | `--yes`, `-y` | | `fp policies delete POLICY_ID` | Удалить версию политики. | `--yes`, `-y` | -| `fp policies test PATH` | Запустить политику локально против синтетического контекста. Применяет фильтр `match` каждой политики, так что тот, который не охватывает данное событие/инструмент, сообщается как `skipped` вместо запуска. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | Разработать политику с ассистентом. Требует `policies:write`. | — | +| `fp policies test PATH` | Запустить политику локально против синтетического контекста. Применяет фильтр `match` каждой политики, поэтому та, которая не охватывает данное событие/инструмент, сообщается как `skipped` вместо запуска. | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | Разработать политику с помощью помощника. Требует `policies:write`. | — | ### Флот -Какие машины запускают какие политики. **Только сеанс**, по той же причине, что выше. +Какие машины запускают какие политики. **Только сеанс**, по той же причине, что и выше. | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp fleet list` | Список зарегистрированных машин и их поколение развёртывания. | — | -| `fp fleet show MACHINE_ID` | Набор политик, который машина запускает в данный момент. | — | -| `fp fleet deploy MACHINE_ID` | **Заменить весь набор политик машины.** Выводит план и запрашивает только на интерактивном терминале без `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | Сравнить машину с другим развёртыванием. | — | -| `fp fleet history MACHINE_ID` | Прошлые развёртывания машины. | — | -| `fp fleet rollback MACHINE_ID` | Восстановить предыдущее развёртывание. | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | Присвоить машине читаемое имя. | требуемый `--name` | +| `fp fleet list` | Вывести зарегистрированные машины и их поколение развертывания. | — | +| `fp fleet show MACHINE_ID` | Набор политик, которые машина в настоящее время запускает. | — | +| `fp fleet deploy MACHINE_ID` | **Заменить весь набор политик машины.** Выводит план и запрашивает только в интерактивном терминале без `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | Сравнить машину с другим развертыванием. | — | +| `fp fleet history MACHINE_ID` | Прошлые развертывания для машины. | — | +| `fp fleet rollback MACHINE_ID GENERATION` | Восстановить набор политик прошлого поколения как новое поколение. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | Дать машине читаемое имя. | обязательный `--name` | ### Guardrails -Что вынужденное применение на самом деле сделало. **Только сеанс**, по той же причине, что выше. +Что enforcement фактически сделал. **Только сеанс**, по той же причине, что и выше. | Команда | Назначение | Параметры | | --- | --- | --- | -| `fp guardrails summary` | Охват, всего заблокировано/оценено, спарклайн отказа и таблица за политику. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | Решения разбиты по окну, просуммированы по каждому источнику политики. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | Охват, всего заблокированных/оцененных, спарклайн deny и таблица за политику. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Решения разбросаны по окну, просуммированы на каждый источник политики. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | ## Глобальные флаги | Флаг | Описание | | --- | --- | -| `--json` | Выдать машиночитаемый JSON. | -| `--base-url ` | Используйте самостоятельно размещённую или облачную приборную панель разработки. | +| `--json` | Выпустить машинно-читаемый JSON. | +| `--base-url ` | Использовать самостоятельно размещенный или развивающийся dashboard. | | `--org ` | Выбрать организацию для этого вызова. | -| `--token ` | Переопределить сохранённый токен сеанса пользователя. | +| `--token ` | Переопределить сохраненный токен пользовательского сеанса. | | `--api-key ` | Аутентифицировать автоматизацию с помощью ключа API; никогда не сохраняется. | -| `--timeout ` | Тайм-аут HTTP; должен быть положительным. По умолчанию: `30`. | -| `--quiet`, `-q` | Подавить вывод статуса на stderr. | -| `--no-color` | Отключить цветной вывод. | +| `--timeout ` | Timeout HTTP; должен быть положительным. По умолчанию: `30`. | +| `--quiet`, `-q` | Подавить статус output на stderr. | +| `--no-color` | Отключить цветной output. | | `--insecure` / `--secure` | Отключить или восстановить проверку сертификата TLS. | -| `--version` | Вывести версию и выход. | +| `--version` | Вывести развернутую версию и выйти. | | `--help`, `-h` | Показать справку. | -`--api-key` предназначен для автоматизации. Вход, переключение организации и команды ассистента требуют сеанс пользователя. +`--api-key` предназначен для автоматизации. Вход, переключение организации и команды помощника требуют пользовательский сеанс. ## Переменные окружения @@ -384,16 +384,16 @@ fp audits create checkout-reliability \ | `FP_INSECURE` | `--insecure` | | `FP_HOME` | Переместить каталог конфигурации CLI (по умолчанию `~/.failproofai/fpcli`). | | `FP_ANALYTICS_DISABLED` или `DO_NOT_TRACK` | Отключить анонимную аналитику CLI. | -| `NO_COLOR` | Отключить цветной вывод. | +| `NO_COLOR` | Отключить цветной output. | -Явные флаги переопределяют переменные окружения, которые переопределяют сохранённую конфигурацию. В режиме ключа API выберите арендатора явно с помощью `--org` или `FP_ORG`. +Явные флаги переопределяют переменные окружения, которые переопределяют сохраненную конфигурацию. В режиме ключа API выберите тенант явно с помощью `--org` или `FP_ORG`. - Написания `AGENTEYE_*` этих **не читаются `fp`** и никогда не были — CLI объявляет `FP_*` (`fp_cli/app.py`), и неизвестная переменная — это не ошибка. Установка `AGENTEYE_DASHBOARD_URL` не переориентирует CLI; она игнорируется и команда молча работает против сохранённой приборной панели. + Написания `AGENTEYE_*` этих параметров **не читаются `fp`** и никогда не были — CLI объявляет `FP_*` (`fp_cli/app.py`), и неизвестная переменная не является ошибкой. Установка `AGENTEYE_DASHBOARD_URL` не перенаправляет CLI; она игнорируется и команда молча выполняется против сохраненного dashboard вместо этого. - `AGENTEYE_HOME` и `AGENTEYE_ENVIRONMENT` всё ещё существуют, но они принадлежат **сборщику и телеметрии SDK**, а не этому CLI. + `AGENTEYE_HOME` и `AGENTEYE_ENVIRONMENT` все еще существуют, но они принадлежат **сборщику и телеметрии SDK**, а не этому CLI. - Команды, которые удаляют, отзывают, подавляют, разрешают или заменяют конфигурацию, запрашивают по умолчанию. Используйте `--yes` только после проверки активной организации и целевого объекта. + Команды, которые удаляют, отзывают, подавляют, разрешают или заменяют конфигурацию, запрашивают по умолчанию. Используйте `--yes` только после проверки активной организации и цели. \ No newline at end of file diff --git a/docs/ru/reference/custom-agents.mdx b/docs/ru/reference/custom-agents.mdx index 931b13b6..59c77a56 100644 --- a/docs/ru/reference/custom-agents.mdx +++ b/docs/ru/reference/custom-agents.mdx @@ -4,18 +4,18 @@ description: "Конфигурация, каталог событий, прав icon: "python" --- -Описание каждого параметра, метода и поля. Если вы впервые осуществляете инструментирование, начните с руководства — эта страница предназначена для справки. +Что делает каждый параметр, метод и поле. Если вы инструментируете впервые, начните с руководства — эта страница предназначена для справок. - - Установка, инструментирование, методы событий, практический пример и типичные проблемы. + + Установка, инструментирование, методы событий, рабочий пример и типичные проблемы. LangChain, CrewAI, LlamaIndex и Pydantic AI инструментируют себя одним вызовом. -Python 3.10 или новее. Без зависимостей во время выполнения. +Python 3.10 или новее. Без зависимостей времени выполнения. ## Установка @@ -23,24 +23,30 @@ Python 3.10 или новее. Без зависимостей во время pip install failproofai-sdk ``` -Пакет устанавливается как `failproofai-sdk` и импортируется в Python как `failproofai_sdk`. Дополнения фреймворков, такие как `failproofai-sdk[langgraph]`, устанавливают сам фреймворк; адаптеры всегда идут в базовом пакете. +Пакет устанавливается как `failproofai-sdk` и импортируется в Python как `failproofai_sdk`. Дополнительные пакеты для фреймворков, такие как `failproofai-sdk[langgraph]`, устанавливают сам фреймворк; адаптеры всегда поставляются в базовом пакете. -## Подключение daemon Failproof +## Подключение демона Failproof - - 1. Перейдите в **Admin → Keys** и создайте ключ с разрешением `events:add`. - 2. [Подключите daemon Failproof к Cloud](/ru/start/setup#connect-a-machine-to-cloud) на машине агента. - 3. Запустите одну сеанс с инструментированием, затем найдите его точный ID в **Observe → Events**. - 4. Перейдите в **Observe → Sessions**, выберите ту же среду и откройте восстановленную трассировку. + + 1. Перейдите в **Admin → Keys** и создайте ключ с правом `events:add`. + 2. [Подключите демон Failproof к облаку](/ru/start/setup#connect-a-machine-to-cloud) на машине агента. + 3. Запустите одну инструментированную сессию, затем найдите её точный ID в **Observe → Events**. + 4. Перейдите в **Observe → Sessions**, выберите ту же среду и откройте восстановленный след. - ![Сеанс пользовательского Python агента восстановлен в виде графика выполнения и упорядоченной трассировки событий.](/images/dashboard/session-detail.png) + ![Сессия пользовательского агента на Python, восстановленная как граф выполнения и упорядоченный след событий.](/images/dashboard/session-detail.png) + Прочитайте ключ `events:add` в оболочку. `read -s` получает его на подсказке без эха, поэтому он никогда не появится в команде или истории оболочки: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Затем настройте машину и проверьте, что она подключена: + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -62,28 +68,28 @@ failproofai_sdk.configure( | --- | --- | | `environment` | Метка для каждого события — `production`, `staging`, `prod-eu`. По умолчанию `dev`. | | `flush_interval` | Как часто фоновый поток записывает на диск, в секундах. По умолчанию `0.5`. | -| `base_dir` | Где писать. По умолчанию спул daemon, что подходит в большинстве случаев. | +| `base_dir` | Куда писать. По умолчанию spooling демона, что вам нужно, если вы не знаете иное. | -Задайте через переменную окружения: +Устанавливается переменной окружения: | Переменная | Что она делает | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | Задаёт `environment` без изменения кода, для случаев, когда метка относится к развёртыванию, а не к приложению. Аргумент `configure()` имеет приоритет. | -| `FAILPROOFAI_HOME` | Перемещает корень Failproof AI, содержащий спул. | -| `FAILPROOFAI_SDK_STRICT` | `1` заставляет ошибки инструментирования генерировать исключение вместо логирования. | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` заставляет проблему совместимости фреймворка генерировать исключение вместо предупреждения. | +| `AGENTEYE_ENVIRONMENT` | Устанавливает `environment` без изменения кода, когда метка принадлежит развёртыванию, а не приложению. Аргумент `configure()` имеет приоритет. | +| `FAILPROOFAI_HOME` | Перемещает корень Failproof AI, который содержит spooling. | +| `FAILPROOFAI_SDK_STRICT` | `1` заставляет ошибки инструментирования выбрасываться вместо логирования. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` заставляет проблему совместимости фреймворка выбрасываться вместо предупреждения и продолжения. | - **Без запятых в `environment`.** Система приёма разбивает это поле по запятым для построения фильтров и пропускает любое событие, метка которого содержит запятую — весь запуск может молча исчезнуть. Пишите `prod-eu`, а не `prod,eu`. + **Без запятых в `environment`.** Ingest разбивает это поле на запятые для построения фильтров и пропускает любое событие, метка которого содержит запятую — вся сессия молча исчезает. Пишите `prod-eu`, а не `prod,eu`. - `configure(environment="prod,eu")` генерирует исключение, чтобы вы узнали сразу. `AGENTEYE_ENVIRONMENT` не может генерировать исключение — вас никто не вызывает — поэтому она выдаёт предупреждение один раз и откатывается на `dev`. + `configure(environment="prod,eu")` выбросит исключение, чтобы вы узнали немедленно. `AGENTEYE_ENVIRONMENT` не может выбросить — никто вас не вызывает — так что он предупреждает один раз и откатывается на `dev`. -События ставятся в очередь в памяти и записываются в фоне каждые `flush_interval` секунд, с финальной записью при выходе интерпретатора. Процесс, грубо завершённый, теряет всё, что ещё не было записано. +События ставятся в очередь в памяти и записываются в фоне каждые `flush_interval` секунд, с финальной записью при выходе интерпретатора. Процесс, убитый силой, теряет всё, что ещё не было записано. -## Идентификация +## Идентичность -Каждое событие принадлежит сеансу и агенту. **Области заполняют оба**, поэтому вы редко их передаёте: +Каждое событие принадлежит сессии и агенту. **Области заполняют обе**, поэтому вы редко их передаёте: ```python with failproofai_sdk.session(): @@ -91,15 +97,15 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Передача `session_id` или `agent_id` явно всё ещё работает и имеет приоритет. Если ни один не привязан и не передан, вызов генерирует `TypeError` вместо отправки события, которое Cloud молча отбросит. +Явная передача `session_id` или `agent_id` по-прежнему работает и имеет приоритет. Без ни одной из них вызов выбросит `TypeError` вместо того, чтобы излучить событие, которое облако молча отбросит. - Идентификация работает через переменные контекста. Она следует за задачами `asyncio` автоматически, но **не** новыми потоками — оберните рабочий код в `failproofai_sdk.propagate()` или его события окажутся неприкреплёнными. + Идентичность ездит на переменных контекста. Она автоматически следует за `asyncio` задачами, но **не** новыми потоками — оборачивайте рабочий процесс в `failproofai_sdk.propagate()` или его события окажутся неприкреплёнными. ## Каталог событий -Пятнадцать методов. Большинство идут в **парах** — вы вызываете открывающий, затем закрывающий, и SDK измеряет интервал. +Пятнадцать методов. Большинство идут **парами** — вы вызываете открывающий, затем закрывающий, и SDK измеряет разницу. | | Открывает | Закрывает | | --- | --- | --- | @@ -110,13 +116,13 @@ with failproofai_sdk.session(): | **Хуки** | `hook_triggered` | `hook_completed` | | **Люди** | `human_wait` | `human_input` | -Три работают отдельно: `error`, `human_pause`, `human_interrupt`. +Три стоят отдельно: `error`, `human_pause`, `human_interrupt`. -Каждый метод также принимает `session_id` и `agent_id`, которые области заполняют для вас. Всё, оставленное как `None`, отбрасывается вместо отправки в JSON как `null`, и каждый метод возвращает `None`. +Каждый метод также принимает `session_id` и `agent_id`, которые области заполняют для вас. Все оставленное как `None` удаляется вместо отправки как JSON `null`, и каждый метод возвращает `None`. -| Метод | Обязательно | Опционально | +| Метод | Обязательные | Опциональные | | --- | --- | --- | | `agent_start` | — | `goal`, `parent_id` | | `agent_end` | — | `outcome`, `summary` | @@ -137,14 +143,14 @@ with failproofai_sdk.session(): - Чтобы отметить запуск как неудачный, `outcome` должен быть одним из `failed`, `error`, `timeout` или `rejected`. Всё остальное — включая похожее `"failure"` — считается успехом. + Чтобы пометить запуск как неудачный, `outcome` должен быть одним из `failed`, `error`, `timeout` или `rejected`. Что-либо ещё — включая близкое совпадение `failure` — считается успехом. -## Парирование и длительность +## Спаривание и длительность -**Одно правило: передайте закрывающему событию тот же id, что и его открывающему.** Это то, что их связывает, и что позволяет SDK измерить интервал. +**Одно правило: дайте закрывающему событию тот же идентификатор, что и его открывающий.** Это то, что их спаривает и позволяет SDK измерить разницу. -| Пара | Сопоставляется по | +| Пара | Согласовано по | | --- | --- | | `tool_use` → `tool_result` | `tool_call_id` | | `hook_triggered` → `hook_completed` | `hook_id` | @@ -152,17 +158,17 @@ with failproofai_sdk.session(): | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**Не передавайте `duration_ms` сами.** SDK измеряет его, и передача генерирует `ValueError`. +**Не передавайте `duration_ms` сами.** SDK измеряет это, и передача его выбросит `ValueError`. -Одно исключение — `model_response`, где только вы знаете реальную задержку поставщика. Передайте целое число миллисекунд — float генерирует исключение, потому что столбец 32-битное целое и иначе остался бы пуст. +Единственное исключение — `model_response`, где только вы знаете реальную задержку провайдера. Передайте целое число миллисекунд — число с плавающей точкой выбросит, потому что столбец — это 32-битное целое число и в противном случае окажется пустым. -- **Id'ы должны быть уникальны только в пределах вида, в пределах сеанса.** Вызов инструмента и хук могут разделять один; два одновременно запущенных сеанса могут переиспользовать те же id'ы без коллизии. -- **Они не привязаны к агенту.** Пара, открытая под одним агентом и закрытая под другим, всё ещё совпадает — это нормальный случай в коде с несколькими агентами. -- **`request_id` опционален, но рекомендуется.** Без него события модели парируются в порядке поступления, поэтому два одновременных вызова в одном агенте могут неправильно спариться. -- **Пара, разделённая между процессами**, всё ещё совпадает в Cloud, но SDK не может её измерить — ничто ни в одном процессе не видело обе половины. -- **Максимум 10 000 открывающих ждут закрывающего одновременно.** После этого самый старый отбрасывается, поэтому утечка не может расти без ограничений. +- **Идентификаторы нужно делать уникальными только для своего вида, в каждой сессии.** Вызов инструмента и хук могут поделиться одним; две сессии, запущенные одновременно, могут переиспользовать одни и те же идентификаторы без столкновений. +- **Они не привязаны к агенту.** Пара, открытая под одним агентом и закрытая под другим, по-прежнему совпадает — что является нормальным случаем в многоагентном коде. +- **`request_id` опционален, но рекомендуется.** Без него события модели спариваются в порядке их поступления, поэтому два одновременных вызова в одном агенте могут неправильно спариться. +- **Пара, разбитая между процессами**, по-прежнему совпадает в облаке, но SDK не может измерить это — ничто в обоих процессах не видело обе половины. +- **Максимум 10 000 открывающих событий ожидают закрывающего одновременно.** Сверх этого самое старое выбрасывается, поэтому утечка не может расти бесконечно. @@ -173,16 +179,16 @@ with failproofai_sdk.session(): ```python failproofai_sdk.event.tool_use( tool_name="search", tool_call_id="c1", - fw_tenant="acme", fw_region="eu-west-1", # ваши собственные + fw_tenant="acme", fw_region="eu-west-1", # ваши ) ``` -Предпочитайте JSON типы, если хотите запрашивать их позже. Всё остальное — UUID, datetime, `Decimal`, set, bytes, объект модели — хранится как строка. +Предпочитайте типы JSON, если хотите запрашивать их позже. Все остальное — UUID, datetime, `Decimal`, set, bytes, объект модели — хранится как строка. - **Добавляйте префикс к названиям ваших полей.** Дополнительные поля применяются последними, поэтому поле, названное `model`, `tool_name` или `outcome`, молча перезапишет реальное. Адаптеры фреймворков используют `fw_`; делайте то же самое и ничто не может конфликтовать. + **Добавьте префикс к названиям своих полей.** Дополнительные элементы применяются последними, поэтому поле с именем `model`, `tool_name` или `outcome` молча перезаписывает настоящее. Адаптеры фреймворков используют `fw_`; делайте то же самое и ничто не может столкнуться. - Это также почему неправильно написанное опциональное поле никогда не ошибается — оно просто становится новым пользовательским полем. Если стандартное поле отсутствует в Cloud, сначала проверьте орфографию. + Вот почему опечатка в опциональном поле никогда не вызывает ошибку — это просто становится новым пользовательским полем. Если стандартного поля нет в облаке, сначала проверьте орфографию. Эти пять имён зарезервированы и отклоняются сразу: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. @@ -190,8 +196,8 @@ failproofai_sdk.event.tool_use( ## Доставка и проверка - - В **Observe → Events** сначала проверьте наличие `agent_start` и наличие `agent_end` в конце. Затем откройте **Observe → Sessions** и подтвердите, что события модели, инструмента, человека, хука и ошибок появляются в предполагаемом порядке. Используйте ID сеанса как первичный ключ устранения неполадок. + + В **Observe → Events** сначала проверьте наличие `agent_start` и `agent_end` в конце. Затем откройте **Observe → Sessions** и подтвердите, что события модели, инструмента, человека, хука и ошибки появляются в намеченном порядке. Используйте ID сессии как основной ключ для устранения неполадок. ```bash @@ -203,14 +209,14 @@ failproofai_sdk.event.tool_use( -Если Cloud пуста, проверьте `$FAILPROOFAI_HOME/custom-agents/events`, иначе `~/.failproofai/custom-agents/events`. JSONL файлы доказывают эмиссию SDK; растущий спул указывает на конфигурацию daemon или доставку, а пустой спул указывает на инструментирование или время жизни процесса. +Если облако пусто, проверьте `$FAILPROOFAI_HOME/custom-agents/events`, иначе `~/.failproofai/custom-agents/events`. Файлы JSONL доказывают излучение SDK; растущий spooling указывает на конфигурацию демона или доставку, в то время как пустой spooling указывает на инструментирование или время жизни процесса. - Проверяйте спул только когда daemon остановлен. Во время его работы он собирает и удаляет каждый пакет в течение миллисекунд, поэтому список директории гонится с коллектором и показывает гораздо меньше событий, чем было излучено. + Проверяйте spooling только когда демон остановлен. Пока он работает, он собирает и удаляет каждый пакет в течение миллисекунд, поэтому перечисление каталога расходится со сборщиком и показывает намного меньше событий, чем было излучено. -## Предотвращение сбоев в пользовательской среде выполнения +## Предотвращение сбоев в пользовательском времени выполнения -Используйте результаты аудита и связанные трассировки для определения небезопасного действия, требуемого доказательства и предполагаемого ответа. Пользовательская интеграция обеспечения должна выявить действие перед выполнением, передать его структурированный ввод в механизм политик и применить результирующее решение allow, instruct или deny. +Используйте результаты аудита и связанные следы для определения небезопасного действия, необходимых доказательств и предполагаемого ответа. Пользовательская интеграция обеспечения должна предоставить действие перед выполнением, передать его структурированный вход механизму политики и применить результирующее решение allow, instruct или deny. -[Свяжитесь с Failproof AI](mailto:support@befailproof.ai) и мы поможем отобразить границы модели, инструмента и жизненного цикла вашей среды выполнения на хуки политик, затем проверим интеграцию с вами. \ No newline at end of file +[Свяжитесь с Failproof AI](mailto:support@befailproof.ai) и мы поможем сопоставить границы модели, инструмента и жизненного цикла вашего времени выполнения с хуками политики, затем проверим интеграцию с вами. \ No newline at end of file diff --git a/docs/ru/reference/evaluator-sdk.mdx b/docs/ru/reference/evaluator-sdk.mdx index 2becb737..e3be4055 100644 --- a/docs/ru/reference/evaluator-sdk.mdx +++ b/docs/ru/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "Создавайте сервисы, которые оценивают сессии Failproof AI синхронно или асинхронно." +description: "Запускайте собственного оценивающего worker для LLM судей и всего остального, что размещённый Python не может сделать." icon: "gauge" --- -Evaluator получает завершённую сессию агента и возвращает интересующие вас сигналы качества: числовые оценки, объяснение для каждой оценки и необязательное резюме. Failproof AI сохраняет эти результаты рядом с трассой и отображает их на графиках для агентов и окружений. +Evaluator SDK запускает оценивания на вашей собственной инфраструктуре. Ваш worker регистрирует свои оценивания в Failproof AI, получает сессии по мере их завершения, оценивает их и отправляет результаты — всё через исходящий HTTPS: ничто не подключается к нему. Используйте его для того, что [размещённый Python](/ru/evaluations/write) не может сделать — LLM судьи, вызовы моделей, пакеты, секреты и сетевой доступ. Его результаты появляются рядом с размещёнными на [странице оценивания](/ru/sessions/evaluations) с меткой **customer**. -## Настройка evaluator +Он поставляется в `failproofai-sdk` под `failproofai_sdk.evaluator`; импорт SDK трассировки не загружает его. - - - Установите SDK и сервер для его запуска. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - Создайте `evaluator.py`. В этом примере проверяется наличие неудачных вызовов инструментов в сессии. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - Установите общий токен, запустите evaluator и убедитесь, что endpoint проверки здоровья отвечает. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - В другом терминале: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## Подключение evaluator к Failproof AI +```bash +pip install failproofai-sdk +``` -1. Разверните evaluator на HTTPS URL, доступном для Failproof AI Cloud. -2. Настройте `EVALUATOR_ENDPOINT` с этим URL и установите `EVALUATOR_TOKEN` на тот же токен, который использует evaluator. Для управляемого Cloud обратитесь в [support@befailproof.ai](mailto:support@befailproof.ai) для настройки подключения. -3. Запустите оценку и убедитесь, что её результаты появились в Failproof AI. +## Напишите оценивания - - - Откройте завершённую сессию в разделе **Observe → Sessions** и выберите **Run evaluation**, если оценка не была выполнена автоматически. Посмотрите статус, оценки, объяснения и резюме в панели **Evaluation** сессии. +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - Используйте **Observe → Evaluations** для сравнения оценок между агентами или окружениями. Используйте **Observe → Metrics** для метрик задержки, стоимости, количества токенов и других числовых измерений. - Начните с одной сессии, чтобы убедиться, что evaluator вернул ожидаемые ключи оценок и полезные объяснения для этого конкретного запуска. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![Представление деталей сессии, показывающее оценки и объяснения рядом с трассой.](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` регистрирует оценивание. Ключ — это то, по чему отображаются его результаты на графике; меняйте версию всякий раз, когда меняется логика, и каждый результат сохраняет версию, которая его произвела. Один worker может содержать до 100 оцениваний. +- `result_kind` по умолчанию имеет значение `"score"`, если не указано иное. Для оценивания типа `"metric"` или `"assertion"` назовите одну запись `metrics` или `assertions` по имени ключа: эта запись — его результат. +- `when` определяет, применяется ли оценивание к сессии. Верните `ConditionResult(False, "")` чтобы пропустить сессию, и причина будет записана. +- Оценивание может быть обычной функцией или `async`, и `timeout_seconds` ограничивает его. +- Ключи полезной нагрузки — `tool_name`, `response` и `content` выше — это то, что отправляют ваши agents, поэтому прочитайте их с реальной сессии. - После того как отдельные результаты выглядят корректно, используйте панель оценок для сравнения этих оценок во времени и между агентами или окружениями. +## Запустите worker - ![Панель качества, отображающая оценки evaluator во времени.](/images/dashboard/dashboard-quality.png) +Поместите ключ с разрешением `evaluations:run`, созданный в разделе **Administration → Keys**, в `FAILPROOFAI_EVALUATOR_TOKEN` — установите его из вашего хранилища секретов вместо ввода его в команду — и запустите worker: - Здоровый график должен использовать стабильные названия оценок; изменение ключа создаёт отдельный ряд. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -Для локально размещённого экземпляра Cloud автоматическая оценка отключена до установки `EVALUATOR_ENDPOINT` на процессе сервера. Перезапустите сервер после изменения переменных окружения evaluator. +Без блока `__main__` то же самое делает `python -m failproofai_sdk.evaluator evaluator:app`. -Сервис предоставляет `GET /health`, `GET /config`, `POST /evaluate` и опционально `GET /evaluate/{job_id}`. Возвращайте `JobPending` для асинхронной работы и регистрируйте `@app.job_lookup`, чтобы Failproof AI мог её опрашивать. +| Переменная | По умолчанию | Назначение | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | обязательна | Где находится Failproof AI: `https://app.befailproof.ai` для Cloud. HTTPS кроме случаев, когда это указывает на loopback | +| `FAILPROOFAI_EVALUATOR_TOKEN` | обязательна | Ключ с разрешением `evaluations:run` | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | Имя этого worker | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | Количество сессий, которые worker оценивает одновременно | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Тайм-аут для каждого запроса к Failproof AI | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | Как долго остановленный worker ждёт выполняющихся запусков | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | Разрешить простой HTTP к URL, который не является loopback — см. предупреждение ниже | +| `FAILPROOFAI_EVALUATOR_MODULE` | нет | Параметр `module:attribute` для `python -m failproofai_sdk.evaluator` | -Когда токен настроен, все маршруты, кроме health, требуют тот же bearer токен, который Failproof AI отправляет как `EVALUATOR_TOKEN`. + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` отправляет всё в открытом виде. Worker носит `FAILPROOFAI_EVALUATOR_TOKEN` в заголовке `Authorization: Bearer` на каждом запросе, и копии транскриптов, которые он загружает, — это сами сессии — поэтому любой на пути может прочитать оба, и прочитанный ими токен будет запускать оценивания до тех пор, пока вы его не обновите. Используйте только в изолированной сети разработки. Везде использование HTTPS обязательно; loopback не требует флага. + -## Типы SDK +## Типы результатов | Тип | Поля | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## Декораторы и маршруты - -| Декоратор | Маршрут | Требуется | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | Да | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | При возврате `JobPending` | -| `@app.config` | `GET /config` | Нет | - -SDK ограничивает тела запросов оценки до 25 МиБ. Неизвестные поля запроса игнорируются, поэтому сервисы остаются совместимы по мере развития контракта событий. +| `Score` | `value` (от 0 до 1), `passed`, `unit` (по умолчанию `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -## Возврат асинхронной работы +`EvalResult` содержит по крайней мере один score, metric или assertion, и максимум 25, каждый с уникальным ключом. -Используйте `JobPending`, когда оценка не может завершиться в одном запросе. ID задачи непрозрачен для Failproof AI и должен оставаться разрешимым вашим сервисом до сбора результата или истечения таймаута сервера. +## Сессия -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| Поле или метод | Даёт вам | +| --- | --- | +| `session_id`, `agent_id`, `environment` | Идентификация сессии | +| `started_at`, `ended_at` | Когда она началась и закончилась | +| `event_count`, `events` | Полный упорядоченный транскрипт | +| `count(event_type)` | Количество событий такого типа | +| `events_of_type(event_type)` | Эти события в порядке возникновения | -Интервал опроса выбирается в таком порядке: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs`, затем `EVALUATOR_POLLING_INTERVAL_SECS` сервера. Значения зажимаются между 1 секундой и 1 часом. Стандартная верхняя граница настенного времени опроса сервера — один час. +Каждое событие содержит `id`, `ts`, `event_type` и `payload`. -## Поля запроса и ответа +## Устаревший оценивающий -| Поле | Тип | Примечания | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | В настоящий момент `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | Идентификация сессии и окружение. | -| `started_at` | `datetime` | Временная метка первого события. | -| `ended_at` | `datetime \| None` | Присутствует, когда сессия отправила событие окончания. | -| `events` | `list[AgentEvent]` | Полный упорядоченный поток событий. | -| `AgentEvent.id` | `int` | Идентификатор строки события в backend. | -| `AgentEvent.ts` | `datetime` | Временная метка события. | -| `AgentEvent.event_type` | `str` | Семейство события, например `tool_use`. | -| `AgentEvent.payload` | `dict[str, Any]` | Полная полезная нагрузка события. | -| `EvalResponse.scores` | `dict[str, float] \| None` | Числовые измерения, отображаемые на графиках в оценках. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | Объяснения для каждой оценки; ключи должны отражать `scores`. | -| `EvalResponse.summary` | `str \| None` | Общее повествование оценки. | - -## Настройки оператора сервера - -Автоматическая оценка работает на уровне развертывания и остаётся отключённой при отсутствии `EVALUATOR_ENDPOINT`. - -| Переменная | Стандартное значение | Назначение | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | не установлено | Базовый URL сервиса evaluator. | -| `EVALUATOR_TOKEN` | не установлено | Bearer токен, используемый совместно с `Evaluator(token=...)`. | -| `EVALUATOR_WORKERS` | `2` | Количество параллельных рабочих диспетчера. | -| `EVALUATOR_CLAIM_BATCH` | `4` | Сессии, захватываемые за один проход диспетчера. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Резервный интервал асинхронного опроса. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Таймаут для каждого запроса evaluator. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | Попытки доставки перед окончательным отказом. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | Интервал обновления для `/config`. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Максимальное настенное время асинхронного опроса. | - -Сервер также может ограничить, какие организации используют глобальный evaluator развертывания. Рассматривайте изменения endpoint, токена, повтора и организационных врат как конфигурацию оператора и перезапустите или переделайте сервер после их изменения. - -## Безопасность и операции - -- Разместите evaluator за HTTPS, когда трафик пересекает границу доверенной сети. -- Настройте непустой bearer токен и держите его идентичным на обоих сервисах. -- Не логируйте токен или полные конфиденциальные подсказки из полезных нагрузок запросов. -- Сделайте синхронные обработчики идемпотентными; повторные попытки могут повторить запрос. -- Сохраняйте состояние асинхронных задач вне памяти процесса в production. -- Возвращайте стабильные ключи оценок. Переименование ключа создаёт новый ряд диаграммы вместо изменения старого. - -SDK выдаёт структурированные логи жизненного цикла, такие как `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` и исключения обработчиков. Он не настраивает обработчики логирования; используйте конфигурацию логирования хост-приложения. \ No newline at end of file +Более ранний Evaluator SDK — HTTP сервис, который Failproof AI вызывал на `EVALUATOR_ENDPOINT`, отвечающий на `/evaluate` и опрашиваемый через `JobPending` — больше не поддерживается. Строите новые оценивающих на этом worker; операторы самостоятельно размещённого экземпляра, запускающего устаревший сервис, могут его сохранить на период переходного процесса. \ No newline at end of file diff --git a/docs/ru/reference/failproof-cli.mdx b/docs/ru/reference/failproof-cli.mdx index 05b4806e..a76cbb50 100644 --- a/docs/ru/reference/failproof-cli.mdx +++ b/docs/ru/reference/failproof-cli.mdx @@ -1,84 +1,102 @@ --- title: "Failproof AI CLI" -description: "Установите hooks, управляйте локальными политиками, подключайте облако и управляйте локальным демоном." +description: "Установка хуков, управление локальными политиками, подключение облака и работа с локальным демоном." icon: "terminal" --- Установите локальный CLI с помощью `npm install -g failproofai`. Запустите без аргументов, чтобы открыть локальную панель управления политиками. -Пакет требует Node.js версии 20.9 или новее. Bun версии 1.3 или новее поддерживается для разработки и установки из исходного кода. `failproofai configure` и `failproofai setup` — это псевдонимы для `failproofai config`; `failproofai p` — это псевдоним для `failproofai policies`. +Пакет требует Node.js 20.9 или новее. Bun 1.3 или новее поддерживается для разработки и установки из исходного кода. `failproofai configure` и `failproofai setup` — это псевдонимы для `failproofai config`. `failproofai policy`, `failproofai pack` и `failproofai p` — это все варианты написания `failproofai policies` — пакеты и отдельные политики раньше были тремя командами для одной идеи, а теперь это одна команда. Старые варианты написания по-прежнему работают, с двумя исключениями: `pack list ` теперь `policies show `, а `pack build` теперь `publish`. ## Настройка машины +Установите CLI, затем прочитайте ключ машины в оболочку. `read -s` принимает его в приглашении, которое не отображается, поэтому он никогда не появляется в команде: + ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +Затем настройте машину и выберите, что она должна применять: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` +`failproofai config` — это вся настройка: он установит сервис `failproofaid` (root один раз через `sudo -n` — никогда интерактивный запрос пароля), подключит хуки в каждый найденный CLI агента и свяжется с облаком при наличии ключа. Без терминала — в CI, контейнере, агенте, управляющем им — он применяет вместо того, чтобы спрашивать, и выходит с кодом 1, если что-то из того, что было запрошено, не произошло. + +Он выбирает **отсутствие** политик. Это задача второй команды, и без неё только что настроенная машина ничего не применяет, кроме всегда включенной защиты. + +Предпочитайте переменную окружения вместо `--token`: аргумент командной строки можно прочитать из `ps` каждым пользователем на машине. Это всё, от чего защищает переменная — ключ, введенный в любую команду, включая `export`, всё равно попадает в историю оболочки, поэтому его читают с помощью `read -s` выше. В CI установите его из хранилища секретов и отключите трассировку оболочки (`set -x`), иначе трассировка выведет его. + + + `--connect ` регистрирует машину, которая **уже настроена**. Он возвращает результат сразу же после успешной регистрации — он не устанавливает демон и не подключает никаких хуков. Используйте обычный `failproofai config` (или `failproofai config --token `) на машине, которая еще не была настроена, иначе она будет выглядеть подключенной при сборе и применении ничего. + + Запустите `failproofai` без аргументов, чтобы открыть локальную панель управления политиками. | Команда | Результат | | --- | --- | -| `failproofai config` | Запустить интерактивную настройку машины | -| `failproofai config --connect --token ` | Подключить доставку облачной политики и ввод данных | +| `failproofai config` | Настройте машину: агенты, демон и облако при наличии ключа | +| `failproofai config --token ` | Настройте и подключитесь за один раз, ничего не спрашивая | +| `failproofai config --connect ` | Зарегистрируйте машину, которая **уже** настроена — нет демона, нет хуков | | `failproofai config --status` | Показать состояние подключения, демона, доставки и паузы | -| `failproofai policies` | Список встроенных, пользовательских, условных политик, пакетов и облачно-управляемых политик | -| `failproofai policies --install` | Установить hooks и включить политики | -| `failproofai policy add ` | Включить одну политику — встроенную или `:` из установленного пакета | -| `failproofai policy remove ` | Отключить одну политику, с тем же именованием | -| `failproofai policies --uninstall` | Отключить политики или удалить hooks привязки | -| `failproofai pack list` | Список установленных пакетов политик и всех политик, которые они содержат | -| `failproofai pack add ` | Установить пакет политик из выпуска GitHub; без тега берется самый новый и закрепляется | -| `failproofai pack add --bundled` | Установить встроенные политики как пакет из этого пакета без сетевого доступа | -| `failproofai pack build ` | Собрать три ресурса выпуска для вашего собственного пакета | -| `failproofai pack remove ` | Деактивировать установленный пакет | -| `failproofai audit` | Сканировать локальную историю агента и открыть локальное представление аудита | -| `failproofai audit --schedule [days] --email
` | Запланировать повторяющиеся локальные сканирования и отправить их результаты по электронной почте | +| `failproofai policies` | Список встроенных, пользовательских, соглашений, пакетов и управляемых облаком политик | +| `failproofai policies --install` | Подключите хуки в ваши CLI агентов. Не включает никакую политику самостоятельно | +| `failproofai policies add ` | Включите одну политику — встроенную или `:` из установленного пакета | +| `failproofai policies remove ` | Отключите одну политику, то же именование | +| `failproofai policies --uninstall` | Отключите политики или удалите хуки обвязки | +| `failproofai policies show /` | Что содержит пакет, прочитайте из его манифеста, прежде чем его использовать | +| `failproofai policies show / --releases` | Каждая версия, которую он выпустил, и какая здесь | +| `failproofai policies add ` | Установите пакет политик из выпуска GitHub; отсутствие тега берет новейший и его закрепляет | +| `failproofai publish` | Отправьте ваши собственные политики как пакет; `--init` запишет один для начала | +| `failproofai policies remove ` | Удалите пакет | +| `failproofai audit` | Сканируйте локальную историю агента и откройте локальный вид аудита | +| `failproofai audit --schedule [days] --email
` | Планируйте повторяющиеся локальные сканирования и отправляйте их результаты по электронной почте | | `failproofai audit --status` | Показать адрес отчета, интервал и следующее запланированное сканирование | | `failproofai audit --no-schedule` | Остановить повторяющиеся сканирования без удаления истории аудита | | `failproofai harness list` | Список дополнительных путей захвата | -| `failproofai flush --wait` | Доставить текущую катушку событий | -| `failproofai backfill --since 30d` | Повторно прочитать предыдущую перенесенную историю | -| `failproofai config --pause [duration]` | Приостановить одну локальную сессию на 30 минут по умолчанию, до 8 часов | -| `failproofai config --resume` | Возобновить одну приостановленную локальную сессию; добавьте `--all` для очистки всех пауз | -| `failproofai update` | Завершить миграции пакетов и обновить демона | -| `failproofai migrate --dry-run` | Просмотреть или выполнить ожидающие миграции макета домашней папки | -| `failproofai uninstall` | Удалить hooks и демона перед удалением пакета | -| `failproofai --version` | Вывести установленную версию пакета | -| `failproofai --help` | Показать команды и глобальное использование | +| `failproofai flush --wait` | Доставьте текущую очередь событий | +| `failproofai backfill --since 30d` | Перечитайте ранее переданную историю | +| `failproofai config --pause [duration]` | Приостановите одну локальную сессию на 30 минут по умолчанию, до 8 часов | +| `failproofai config --resume` | Возобновите одну приостановленную локальную сессию; добавьте `--all`, чтобы очистить все паузы | +| `failproofai update` | Завершите миграции пакетов и обновите демон | +| `failproofai migrate --dry-run` | Просмотрите или выполните отложенные миграции макета домашней папки | +| `failproofai uninstall` | Удалите хуки и демон перед удалением пакета | +| `failproofai --version` | Выведите установленную версию пакета | +| `failproofai --help` | Покажите команды и глобальное использование | ## Флаги конфигурации | Флаг | Использование | | --- | --- | -| `--connect --token ` | Подключиться неинтерактивно | -| `--machine-id ` | Установить стабильный ID машины | -| `--machine-label ` | Установить или изменить метку панели управления | -| `--no-transcripts` | Отправить решения без содержимого транскрипта | -| `--disconnect` | Остановить извлечение облачной политики и доставку событий | +| `--token ` | Настройте и подключитесь неинтерактивно; также читайте из `FAILPROOFAI_CLOUD_TOKEN` | +| `--url ` | Подключитесь где-то, кроме `app.befailproof.ai`; также читайте из `FAILPROOFAI_CLOUD_URL` | +| `--connect ` | Только регистрация на машине, которая уже настроена. Пропускает демон и все хуки | +| `--machine-id ` | Установите стабильный ID машины | +| `--machine-label ` | Переименуйте машину, которая **уже подключена**. Сам по себе никогда не запускает настройку, поэтому используйте его после `failproofai config`, а не во время | +| `--no-transcripts` | Отправляйте решения без содержания расшифровок | +| `--disconnect` | Остановите извлечение политик облака и доставку событий | | `--status` | Показать текущее состояние машины | -| `--pause [duration]` | Приостановить новейшую сессию в текущей директории; принимает секунды, минуты или часы и по умолчанию составляет 30 минут | -| `--resume` | Завершить совпадающую паузу раньше | -| `--session ` | Нацелиться на явную сессию для паузы или возобновления | -| `--all` | С `--resume` завершить все активные паузы | +| `--pause [duration]` | Приостановите новейшую сессию в текущей папке; принимает секунды, минуты или часы и по умолчанию 30 минут | +| `--resume` | Завершите соответствующую паузу раньше | +| `--session ` | Направьте явную сессию для паузы или возобновления | +| `--all` | С `--resume`, завершите все активные паузы | -Локальные паузы приостанавливают встроенные, пользовательские, условные политики и политики пакетов для одной сессии. Они всегда истекают и не отключают облачно-управляемые политики. `block-failproofai-commands` — который всегда включен и не может быть отключен или приостановлен сам по себе — предотвращает использование этого механизма обхода инструментированным агентом. +Локальные паузы приостанавливают встроенные, пользовательские, соглашения и политики пакетов для одной сессии. Они всегда истекают и не отключают управляемые облаком политики. `block-failproofai-commands` — который всегда включен и не может быть отключен или приостановлен — предотвращает использование этого люка самим инструментированным агентом. ## Флаги политики | Флаг | Использование | | --- | --- | -| `--install`, `-i` | Включить политики и установить hooks привязки | -| `--uninstall`, `-u` | Отключить политики или удалить hooks | -| `--cli ` | Нацелиться на один или несколько поддерживаемых привязок | -| `--scope user\|project\|local\|all` | Выбрать область конфигурации; `all` для удаления | -| `--beta` | Включить бета-политики | -| `--custom`, `-c ` | Валидировать и загрузить пользовательский файл политики; повторяемо | +| `--install`, `-i` | Установите хуки обвязки. Имена после него включают эти политики; без них никаких изменений политики | +| `--uninstall`, `-u` | Отключите политики или удалите хуки | +| `--cli ` | Направьте один или несколько поддерживаемых обвязок | +| `--scope user\|project\|local\|all` | Выберите область конфигурации; `all` для удаления | +| `--beta` | Включите бета-политики | +| `--custom`, `-c ` | Проверьте и загрузите пользовательский файл политики; повторяется | ## Флаги доставки и обслуживания @@ -90,9 +108,9 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` следует запустить после `npm install -g failproofai@latest`; он выполняет миграции макета домашней папки, устанавливает соответствующий бинарный файл демона и перезапускает сервис. `--no-daemon` выполняет только миграцию макета. +`failproofai update` должен быть запущен после `npm install -g failproofai@latest`; он выполняет миграции макета домашней папки, устанавливает соответствующий бинарный демон и перезагружает сервис. `--no-daemon` выполняет только миграцию макета. -## Пути привязки +## Пути обвязки ```text failproofai harness list [harness] @@ -100,11 +118,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -Поддерживаемые имена привязок: `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` и `goose`. +Поддерживаемые имена обвязок: `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` и `goose`. -Метки помещают полученные ID агентов в пространство имен, когда два корня содержат копии одного и того же проекта. Перекрывающиеся корни и дублирующиеся метки отклоняются для предотвращения дублирования сбора или повреждения курсора. Конфигурация дополнительного пути перезагружается без перезагрузки демона. +Метки разделяют ID производных агентов, когда два корня содержат копии одного и того же проекта. Перекрывающиеся корни и дублирующиеся метки отклоняются, чтобы предотвратить дублирующийся сбор или повреждение курсора. Конфигурация дополнительных путей перезагружается без перезагрузки демона. -Контейнерные среды могут заменить сконфигурированные файлом дополнительные пути переменной с разделением запятыми с именем `FAILPROOFAI__EXTRA_PATHS`, например: +Контейнерные среды могут заменить сконфигурированные файлом дополнительные пути переменной, разделенной запятыми, с именем `FAILPROOFAI__EXTRA_PATHS`, например: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -116,22 +134,24 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl | Переменная | Использование | | --- | --- | -| `FAILPROOFAI_HOME` | Переместить полный макет `~/.failproofai` | -| `FAILPROOFAI_LOG_LEVEL` | Установить подробность локального логирования | -| `FAILPROOFAI_HOOK_LOG_FILE` | Писать диагностику hooks в выбранный файл | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Отключить анонимную телеметрию для этого процесса | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Пропустить интерактивную первичную настройку | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Пропустить локальный аудит после настройки | -| `FAILPROOFAI_LLM_BASE_URL` | Переопределить конечную точку, совместимую с OpenAI, используемую политиками LLM | -| `FAILPROOFAI_LLM_API_KEY` | Предоставить ключ API, используемый политиками LLM | -| `FAILPROOFAI_LLM_MODEL` | Выбрать модель, используемую политиками LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Ограничить загрузку модуля пользовательской политики | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Отказаться получать пакеты и бинарные файлы демона; что установлено, продолжает работать | -| `FAILPROOFAI_PACK_BASE_URL` | Получать пакеты из зеркала вместо `github.com` | -| `FAILPROOFAI__EXTRA_PATHS` | Заменить сконфигурированные дополнительные пути захвата для одной привязки | -| `NO_COLOR` | Отключить цветной вывод терминала | - -Переменные домашней папки, специфичные для агента, такие как `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` и `OPENCLAW_HOME` переопределяют, где Failproof AI обнаруживает локальные сессии для этой привязки. +| `FAILPROOFAI_CLOUD_TOKEN` | Ключ облака вместо `--token`. Предпочитайте это: аргумент можно прочитать из `ps` каждым пользователем. Установите его с помощью `read -s` или из хранилища секретов CI, никогда не вводите ключ в команду, что в любом случае попадает в историю оболочки | +| `FAILPROOFAI_CLOUD_URL` | URL облака вместо `--url`. Та же переменная, которую читает демон | +| `FAILPROOFAI_HOME` | Переместите полный макет `~/.failproofai` | +| `FAILPROOFAI_LOG_LEVEL` | Установите уровень локального ведения журнала | +| `FAILPROOFAI_HOOK_LOG_FILE` | Напишите диагностику хуков в выбранный файл | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Отключите анонимную телеметрию для этого процесса | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Пропустите интерактивную первоначальную настройку | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Пропустите локальный аудит после настройки | +| `FAILPROOFAI_LLM_BASE_URL` | Переопределите совместимую с OpenAI конечную точку, используемую политиками LLM | +| `FAILPROOFAI_LLM_API_KEY` | Укажите ключ API, используемый политиками LLM | +| `FAILPROOFAI_LLM_MODEL` | Выберите модель, используемую политиками LLM | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Ограничьте загрузку модуля пользовательской политики | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Откажитесь получать пакеты и бинарные демоны; то, что установлено, продолжает применяться | +| `FAILPROOFAI_PACK_BASE_URL` | Получайте пакеты с зеркала вместо `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | Замените сконфигурированные пути захвата для одной обвязки | +| `NO_COLOR` | Отключите цветной вывод терминала | + +Переменные домашней папки, зависящие от агента, такие как `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` и `OPENCLAW_HOME`, переопределяют то, где Failproof AI обнаруживает локальные сессии для этой обвязки. ## Безопасно приостановить или удалить машину @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -Локальная пауза сессии не отключает облачно-управляемые политики. Восстановите облачные развертывания через рабочий процесс облачного принудительного применения, когда сам развертывание является проблемой. +Пауза локальной сессии не отключает управляемые облаком политики. Восстановите развертывания облака через рабочий процесс применения облака, когда сам выпуск является проблемой. -Перед удалением npm пакета удалите установленные hooks и демона: +Перед удалением пакета npm удалите установленные хуки и демон: ```bash failproofai uninstall --dry-run @@ -154,5 +174,5 @@ npm rm -g failproofai Запустите `failproofai --help` для деталей, зависящих от версии. - Запустите `failproofai uninstall` перед `npm rm -g failproofai`; npm не удаляет установленные hooks агента или сервис демона. + Запустите `failproofai uninstall` перед `npm rm -g failproofai`; npm не удаляет установленные хуки агента или сервис демона. \ No newline at end of file diff --git a/docs/ru/reference/harnesses.mdx b/docs/ru/reference/harnesses.mdx index 360ec913..26bcb07f 100644 --- a/docs/ru/reference/harnesses.mdx +++ b/docs/ru/reference/harnesses.mdx @@ -1,80 +1,86 @@ --- title: "Адаптеры агентов" -description: "Захватывайте сессии и применяйте политики во всех 12 поддерживаемых адаптерах агентов." +description: "Захватывайте сеансы и применяйте политики на всех 12 поддерживаемых адаптерах агентов." icon: "plug-zap" --- -Адаптер — это всё, внутри чего фактически работает ваш агент. Failproof AI поддерживает двенадцать адаптеров в двух категориях: +Адаптер — это среда, в которой фактически работает ваш агент. Failproof AI поддерживает двенадцать адаптеров в двух категориях: -- **Coding CLIs** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Chat and assistant gateways** (2) — Hermes (Slack, Telegram, cron), OpenClaw (self-hosted assistant) +- **Кодовые CLI** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **Шлюзы чатов и ассистентов** (2) — Hermes (Slack, Telegram, cron), OpenClaw (самостоятельно размещаемый ассистент) -Одни и те же политики и одна и та же история сессий применяются независимо от того, в каком адаптере работает агент. Один слой адаптера преобразует имена событий, имена инструментов и поля входных данных каждого адаптера на 29 канонических событий до выполнения любой политики. +Одни и те же политики и одна и та же история сеанса применяются независимо от того, в каком адаптере работает агент. Один слой адаптера преобразует собственные имена событий, имена инструментов и поля входных данных инструментов каждого адаптера в 29 канонических событий до применения любой политики. -Агент, работающий **ни в одном** из двенадцати адаптеров, инструментируется напрямую с помощью [Python SDK](/ru/reference/custom-agents). Это другой контракт, и стоит об этом сказать открыто: SDK обеспечивает трассировку, сессии, оценки и аудиты — **он не применяет политики самостоятельно.** Для блокировки небезопасного действия до его выполнения требуется крючок применения на границе инструментов вашей среды выполнения; [свяжитесь с нами](mailto:support@befailproof.ai) и мы его установим. +Агент, работающий **ни в одном** из двенадцати адаптеров, инструментируется непосредственно с помощью [Python SDK](/ru/reference/custom-agents). Это другой контракт, и стоит сказать прямо: SDK обеспечивает трассировку, сеансы, оценки и аудиты — **он не применяет политики самостоятельно.** Для блокировки небезопасного действия перед его выполнением требуется перехватчик применения на границе инструмента вашего времени выполнения; [свяжитесь с нами](mailto:support@befailproof.ai) и мы его реализуем. -| Адаптер | Поддерживаемые области крючков | +| Адаптер | Поддерживаемые области перехватчиков | | --- | --- | | Claude Code | User, project, local | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -Каждая интеграция нормализует имена событий крючков, имена инструментов и поля входных данных перед выполнением политик. Политика может действовать только на события, которые предоставляет адаптер; протестируйте поведение в конце хода и инструкции на точном адаптере и версии, которую вы развёртываете. +Каждая интеграция нормализует собственные имена событий перехватчика, имена инструментов и поля входных данных инструментов перед применением политик. Политика может действовать только на события, которые предоставляет адаптер; протестируйте поведение в конце хода и поведение инструкций на точном адаптере и версии, которые вы развертываете. ## Возможности применения -«Block» означает, что решение адаптера используется названным адаптером. Блокировка после инструмента может заменить результат, показываемый модели, но не может отменить побочный эффект инструмента, который уже произошёл. +«Блокировка» означает, что решение возвращаемого адаптером потребляется названным адаптером. Блокировка после инструмента может заменить результат, показываемый модели, но не может отменить побочный эффект инструмента, который уже произошел. -| Адаптер | Проверенные события блокировки | Замечания о режиме наблюдения или отсутствии блокировки | +| Адаптер | Проверенные события блокировки | Полностью наблюдательные или не блокирующие замечания | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` и несколько событий задач/конфигурации | `PostToolUse`, жизненный цикл сессии, уведомления и события после сбоя — только для наблюдения. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Блокировка после инструмента заменяет результат после выполнения; события запуска сессии и compaction — только для наблюдения в текущем адаптере. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Блокировка после инструмента заменяет результат после выполнения; события сессии и уведомлений — только для наблюдения. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` и события сессии — только для наблюдения. | -| OpenCode | `PreToolUse` | События после инструмента и жизненного цикла — только для наблюдения; текущая обработка остановки — это рекомендация для следующего хода, а не проверенный вентиль. | -| Pi | `PreToolUse`, `UserPromptSubmit` | События после инструмента и жизненного цикла — только для наблюдения; рекомендация остановки применяется к следующему ходу. | -| Hermes | `PreToolUse` | Решения после инструмента, сессии и остановки подагента — не вентили. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | События после инструмента, сессии, остановки подагента и compaction — только для наблюдения. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Решения после инструмента и остановки подагента — только для наблюдения. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, условный `PermissionRequest` | Крючки разрешений выполняются не в каждом режиме разрешений; события после инструмента и сессии — только для наблюдения. | -| Antigravity CLI | `PreToolUse`, `Stop` | Решения по приглашению пользователя и после инструмента — только для наблюдения; инструкции приглашения всё ещё могут быть внедрены. | -| Goose | `PreToolUse` | События приглашения пользователя, после инструмента и сессии — только для наблюдения. Собственный вентиль блокировки остановки существует выше по потоку, но не установлен текущим адаптером. | - -Возможности зависят от версии. Переоцените после обновления CLI агента, особенно если политика полагается на поведение приглашения, остановки, разрешения или после инструмента, а не на обычный вентиль перед инструментом. - -## Установка захвата и крючков политик +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` и несколько событий задач/конфигурации | `PostToolUse`, жизненный цикл сеанса, уведомления и события после сбоя являются наблюдательными. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Блокировка после инструмента заменяет результат после выполнения; события начала сеанса и компактирования являются наблюдательными в текущем адаптере. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Блокировка после инструмента заменяет результат после выполнения; события сеанса и уведомления являются наблюдательными. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` и события сеанса являются наблюдательными. | +| OpenCode | `PreToolUse` | События после инструмента и жизненного цикла являются наблюдательными; текущая обработка остановки — это рекомендация для более позднего хода, а не проверенные ворота. | +| Pi | `PreToolUse`, `UserPromptSubmit` | События после инструмента и жизненного цикла являются наблюдательными; рекомендация остановки применяется к более позднему ходу. | +| Hermes | `PreToolUse` | Решения после инструмента, сеанса и остановки подагента не являются воротами. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | События после инструмента, сеанса, остановки подагента и компактирования являются наблюдательными. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Решения после инструмента и остановки подагента являются наблюдательными. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, условный `PermissionRequest` | Перехватчики разрешений работают не во всех режимах разрешений; события после инструмента и сеанса являются наблюдательными. | +| Antigravity CLI | `PreToolUse`, `Stop` | Решения запроса пользователя и после инструмента являются наблюдательными; инструкции запроса все еще можно внедрить. | +| Goose | `PreToolUse` | События запроса пользователя, после инструмента и сеанса являются наблюдательными. Существует родной перехватчик блокирующей остановки выше по течению, но не установлен текущим адаптером. | + +Возможности зависят от версии. Протестируйте снова после обновления CLI агента, особенно когда политика основана на поведении запроса, остановки, разрешения или после инструмента, а не на общих воротах перед инструментом. + +## Установка перехватчиков захвата и политики 1. Откройте **Administration → Keys** и создайте ключ с `events:add` и `policies:pull`, названный для машины или окружения. - 2. На целевой машине подключите локальный CLI с отображаемым ключом и установите крючки адаптера. - 3. Запустите новую сессию агента, затем подтвердите её крючки и события сессии в **Observe → Events**. - 4. Откройте **Observe → policy** для того же временного окна и подтвердите, что решение политики приписано машине. + 2. На целевой машине подключите локальный CLI с отображаемым ключом и установите перехватчики адаптера. + 3. Запустите новый сеанс агента, затем подтвердите его перехватчик и события сеанса в **Observe → Events**. + 4. Откройте **Observe → policy** для того же временного окна и подтвердите, что решение политики принято машиной. - Подключение начинается с ключа машины. Подтвердите, что он включает разрешения как на приём, так и на доставку политик перед копированием его секрета. + Подключение начинается с ключа машины. Подтвердите, что он включает разрешения на ingestion и delivery политик перед копированием его секрета. - ![Ящик нового API-ключа для предоставления разрешений приёма событий и доставки политик.](/images/dashboard/key-create.png) + ![Новое окно создания ключа API, используемое для предоставления разрешений на ingestion событий и delivery политик.](/images/dashboard/key-create.png) - После установки крючков поток Events должен показать новые события от подключённой машины и окружения. + После установки перехватчиков поток Events должен показывать новые события с машины и окружения, которое вы подключили. - ![Живой поток Events для подтверждения отчётности новоустановленного адаптера.](/images/dashboard/events-stream.png) + ![Живой поток Events, используемый для подтверждения того, что новый установленный адаптер отправляет отчеты.](/images/dashboard/events-stream.png) - Наконец, проверьте, что решения политики приписаны той же машине. Это подтверждает, что адаптер отчитывается как о деятельности политики, так и о событиях трассировки. + Наконец, проверьте, что решения политики принимаются той же машиной. Это подтверждает, что адаптер отправляет отчеты как о деятельности политики, так и о событиях трассировки. - ![Страница Policy для проверки решений политики от новоподключённого адаптера.](/images/dashboard/policy-observe.png) + ![Страница Policy, используемая для проверки решений политики с недавно подключенного адаптера.](/images/dashboard/policy-observe.png) - Установите крючки для каждого обнаруженного адаптера: + Прочитайте ключ машины в оболочку. `read -s` берет его в приглашении, которое не выводится эхом, поэтому он никогда не появляется в команде или в истории оболочки: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Или выберите названные адаптеры и область конфигурации: + Затем настройте машину — это подключит перехватчики для каждого обнаруженного адаптера, установит демон и подключится к Cloud: + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + Настройка не включает никакие политики самостоятельно, поэтому нужна вторая команда. + + Или нацеленно выберите именованные адаптеры и область конфигурации: ```bash failproofai policies --install \ @@ -82,7 +88,7 @@ icon: "plug-zap" --scope user ``` - Область project сохраняет конфигурацию крючков с репозиторием. Область user охватывает работу в разных репозиториях. Claude Code также поддерживает область local; поддержка варьируется по адаптерам, и CLI отклоняет неподдерживаемые комбинации. + Область project сохраняет конфигурацию перехватчика с репозиторием. Область user охватывает работу через репозитории. Claude Code также поддерживает область local; поддержка варьируется в зависимости от адаптера и CLI отклоняет неподдерживаемые комбинации. Проверьте машину и её события: @@ -94,16 +100,16 @@ icon: "plug-zap" -## Добавьте нестандартный путь сессии +## Добавьте путь сеанса, не установленный по умолчанию - Дополнительные пути регистрируются на машине, а не в Cloud. После добавления одного откройте **Observe → Sessions**, отфильтруйте по окружению машины и подтвердите появление сессий из нового пути. Откройте сессию и проверьте агента, адаптер и временные метки событий перед использованием в аудите. + Дополнительные пути регистрируются на машине, а не в Cloud. После добавления одного откройте **Observe → Sessions**, отфильтруйте по окружению машины и подтвердите, что сеансы с нового пути отображаются. Откройте сеанс и проверьте агента, адаптер и временные метки событий перед использованием в аудите. ![Список Sessions, отфильтрованный по окружению, получающему данные от дополнительного пути захвата.](/images/dashboard/sessions-list.png) - Добавьте путь с опциональной меткой, затем проверьте настроенные пути: + Добавьте путь с необязательной меткой, затем проверьте настроенные пути: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -117,5 +123,5 @@ icon: "plug-zap" - Запустите одну новую сессию после установки. Проверьте как живой поток событий, так и фактическое решение политики перед расширением развёртывания. + Запустите один новый сеанс после установки. Проверьте как живой поток событий, так и фактическое решение политики перед расширением развертывания. \ No newline at end of file diff --git a/docs/ru/reference/overview.mdx b/docs/ru/reference/overview.mdx index 743ec2c3..a8b1b7f1 100644 --- a/docs/ru/reference/overview.mdx +++ b/docs/ru/reference/overview.mdx @@ -1,81 +1,84 @@ --- -title: "Интеграции и справочные материалы" -description: "Подключите поддерживаемые фреймворки агентов, SDK, CLI и HTTP API." +title: "Интеграции и справочник" +description: "Подключайте поддерживаемые оболочки агентов, SDK, CLI и HTTP API." icon: "braces" --- -Выберите интеграцию, наиболее близкую к месту запуска вашего агента. +Выберите интеграцию, которая наиболее близка к месту запуска вашего агента. - - Установите перехватчики для поддерживаемых CLI агентов кодирования и автономных агентов. + + Установите хуки для поддерживаемых CLI кодирования и автономных агентов. - Интегрируйте LangGraph, CrewAI, LlamaIndex, Pydantic AI или пользовательского агента. + Инструментируйте LangGraph, CrewAI, LlamaIndex, Pydantic AI или пользовательского агента. - + Конфигурация, каталог событий, правила корреляции и доставка. - - Просмотр локальных проектов, сеансов, действий политик и автономных аудитов. + + Просмотрите локальные проекты, сеансы, активность политик и оффлайн-аудиты. - - Конфигурация локального захвата, перехватчиков, политик, аудитов, доставки и состояния машины. + + Настройте локальный сбор, хуки, политики, аудиты, доставку и состояние машины. - - Запрос и администрирование облачных сеансов, аудитов, проблем, оповещений, ключей, пользователей и параметров. + + Запрашивайте и администрируйте сеансы Cloud, аудиты, проблемы, оповещения, ключи, пользователей и параметры. - - Оцените завершённые или неактивные сеансы с помощью сервиса FastAPI. + + Оценивайте полные или неактивные сеансы с помощью сервиса FastAPI. - Создавайте и тестируйте решения allow, instruct и deny для конкретных рабочих процессов. + Создавайте и тестируйте решения, специфичные для рабочего процесса: allow, instruct и deny. - - Разверните плоскость управления облака на управляемом клиентом кластере Kubernetes. + + Разверните плоскость управления Cloud на кластере Kubernetes, управляемом пользователем. -Автоматически создаваемый [справочник HTTP API](/ru/reference/http-api) охватывает общедоступный интерфейс `/v1`. Руководства объясняют рабочие процессы, охватывающие несколько конечных точек или использующие административные интерфейсы вне этого общедоступного интерфейса. +Сгенерированный [справочник HTTP API](/ru/reference/http-api) охватывает общественную поверхность `/v1`. Написанные вручную страницы объясняют рабочие процессы, охватывающие несколько конечных точек или использующие административные интерфейсы, не входящие в эту общественную поверхность. -## Подключение агента и проверка данных +## Подключите агента и проверьте данные - - 1. Откройте **Administration → Keys**, создайте ключ с разрешениями `events:add` и `policies:pull` и скопируйте секрет. - 2. Конфигурируйте интеграцию, используя соответствующую страницу выше. - 3. Откройте **Observe → Events** для подтверждения поступления событий, затем **Observe → Sessions** для подтверждения формирования полных запусков. - 4. Отфильтруйте по окружению интеграции и проверьте один сеанс на предмет полей модели, инструмента, ошибки и политики, необходимых для аудитов. + + 1. Откройте **Administration → Keys**, создайте ключ с `events:add` и `policies:pull` и скопируйте секрет. + 2. Настройте интеграцию, используя соответствующую страницу выше. + 3. Откройте **Observe → Events**, чтобы подтвердить получение событий, затем **Observe → Sessions**, чтобы подтвердить, что они образуют полные прогоны. + 4. Отфильтруйте по среде интеграции и проверьте один сеанс на наличие полей модели, инструмента, ошибки и политики, необходимых аудитам. - Начните с панели ключей. Выбранные разрешения определяют, может ли машина отправлять события и получать управляемые облаком политики. + Начните с ящика ключей. Выбранные разрешения определяют, может ли машина отправлять события и получать управляемые Cloud политики. - ![Панель создания нового ключа API для предоставления разрешений на приём событий и доставку политик.](/images/dashboard/key-create.png) + ![Ящик создания нового ключа API, используемый для предоставления разрешений на прием событий и доставку политик.](/images/dashboard/key-create.png) - После подключения интеграции используйте список Sessions для подтверждения того, что её события группируются в полные запуски в ожидаемом окружении. + После подключения интеграции используйте список Sessions для подтверждения того, что её события группируются в полные прогоны в ожидаемой среде. - ![Список Sessions, используемый для проверки того, что недавно подключенная интеграция сообщает о полных запусках агента.](/images/dashboard/sessions-list.png) + ![Список Sessions, используемый для проверки того, что вновь подключённая интеграция сообщает о полных прогонах агента.](/images/dashboard/sessions-list.png) - Откройте один из этих сеансов перед завершением интеграции; трассировка должна содержать свидетельства модели, инструмента, ошибки и политики, необходимые вашим аудитам. + Откройте один из этих сеансов перед тем, как считать интеграцию завершённой; трасса должна содержать доказательства модели, инструмента, ошибки и политики, которые требуют ваши аудиты. - Создайте ключ машины, подключите демон Failproof и проверьте первый сеанс. + Создайте ключ машины и прочитайте выводимый им секрет в shell. `read -s` принимает его в приглашении, которое не эхируется, так что он никогда не появляется в команде или истории shell: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Подключите демон Failproof и проверьте первый сеанс: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - Используйте `fp --json sessions ...` когда результат будет использоваться другим инструментом. Глобальные флаги такие как `--json`, `--org` и `--base-url` должны быть перед командой. + Используйте `fp --json sessions ...`, когда другой инструмент будет использовать результат. Глобальные флаги, такие как `--json`, `--org` и `--base-url`, должны предшествовать команде. - Смотрите [справку CLI Failproof AI](/ru/reference/failproof-cli) для локальных команд и [справку CLI облака Failproof](/ru/reference/cloud-cli#cli-commands) для команд `fp`. + Смотрите [справочник Failproof AI CLI](/ru/reference/failproof-cli) для локальных команд и [справочник Failproof Cloud CLI](/ru/reference/cloud-cli#cli-commands) для команд `fp`. \ No newline at end of file diff --git a/docs/ru/reference/policy-sdk.mdx b/docs/ru/reference/policy-sdk.mdx index 72e4ee6d..de79c16a 100644 --- a/docs/ru/reference/policy-sdk.mdx +++ b/docs/ru/reference/policy-sdk.mdx @@ -1,35 +1,35 @@ --- title: "Пользовательские политики" -description: "Создавайте, тестируйте и развёртывайте политики на JavaScript или TypeScript для ошибок, специфичных для ваших агентов." +description: "Разработайте, протестируйте и развертывайте политики на JavaScript или TypeScript для сбоев, специфичных для ваших агентов." icon: "shield-plus" --- -Пользовательские политики преобразуют шаблон сбоя из ваших трассировок или аудитов в решение, которое выполняется во время работы агента. Политика может разрешить действие, предоставить агенту рекомендации или заблокировать действие до того, как оно вызовет ещё один инцидент. +Пользовательские политики преобразуют паттерн сбоя из ваших трасс или аудитов в решение, которое выполняется во время работы агента. Политика может разрешить действие, дать агенту рекомендацию или запретить действие до того, как оно вызовет еще один инцидент. -Используйте пользовательскую политику, когда поведение зависит от ваших инструментов, путей, команд, окружения или операционных правил. Сначала проверьте [каталог встроенных политик](/ru/policies/builtin-catalog), чтобы не дублировать существующий контроль. +Используйте пользовательскую политику, когда поведение зависит от ваших инструментов, путей, команд, окружений или операционных правил. Сначала проверьте [пакет политик Failproof AI](/ru/policies/packs), чтобы не воссоздавать существующий контроль. -## Создание пользовательской политики +## Разработка пользовательской политики 1. Перейдите в **Admin → policy editor**, выберите **New policy** и опишите сбой, который вы хотите предотвратить. - 2. Добавьте исходный код политики, затем протестируйте ожидаемые совпадения и безопасные несовпадения в редакторе. Разрешите все ошибки валидации. + 2. Добавьте исходный код политики, затем протестируйте ожидаемые совпадения и безопасные несовпадения в редакторе. Исправьте все ошибки валидации. 3. Сохраните черновик и выберите **Publish version**, чтобы создать неизменяемую версию. - 4. Перейдите в **Admin → enforcement**, разверните версию на тестовой машине в режиме **observe** и проверьте её решения под **Observe → policy** перед её применением. + 4. Перейдите в **Admin → enforcement**, развертните версию на тестовой машине в режиме **observe** и проверьте её решения в **Observe → policy** перед её применением. - ![Редактор политик, используемый для создания и публикации пользовательской политики.](/images/dashboard/policy-editor.png) + ![Редактор политик, используемый для разработки и публикации пользовательской политики.](/images/dashboard/policy-editor.png) - 1. Создайте `.failproofai/policies/checkout-policies.ts`. Имя файла должно оканчиваться на `policies.js`, `policies.mjs` или `policies.ts`. + 1. Создайте `.failproofai/policies/checkout-policies.ts`. Имя файла должно заканчиваться на `policies.js`, `policies.mjs` или `policies.ts`. 2. Зарегистрируйте одну или несколько политик с помощью `customPolicies.add()`. - 3. Валидируйте и установите файл командой `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. - 4. Запустите одно совпадающее действие и одно безопасное действие. Выполните `failproofai policies`, затем проверьте атрибутированные решения в разделе **Observe → policy**. + 3. Валидируйте и установите файл с помощью `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. + 4. Запустите одно совпадающее действие и одно безопасное действие. Выполните `failproofai policies`, затем проверьте приписанные решения в **Observe → policy**. ## Начните с узкого правила -Эта политика блокирует деструктивные команды Kubernetes только когда команда нацелена на production. Всё остальное вне этого точного шаблона сбоя возвращает `allow()`. +Эта политика блокирует деструктивные команды Kubernetes только когда команда нацелена на production. Все остальное вне этого точного паттерна сбоя возвращает `allow()`. ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,20 +55,20 @@ customPolicies.add({ }); ``` -Хорошие политики достаточно узки, чтобы объяснить одним предложением. Совпадайте с наблюдаемым действием — а не с тем намерением, которое вы надеялись найти у агента — и возвращайте `allow()` как только правило перестанет применяться. +Хорошие политики достаточно узки, чтобы объяснить их одним предложением. Совпадайте с наблюдаемым действием — а не с намерением, которое вы надеялись иметь у агента — и возвращайте `allow()` как только правило не применяется. ## Выберите решение | Вспомогательная функция | Результат | Используйте, когда | | --- | --- | --- | | `allow(reason?)` | Операция продолжается. | Политика не применяется или действие безопасно. | -| `instruct(reason)` | Операция продолжается с рекомендациями, где это поддерживается. | Вы хотите направить агента на лучший подход без применения инварианта. | -| `deny(reason)` | Операция блокируется, когда событие и обработчик это поддерживают. | Действие не должно продолжаться. | +| `instruct(reason)` | Операция продолжается с рекомендацией где поддерживается harness. | Вы хотите направить агента к лучшему подходу без применения инварианта. | +| `deny(reason)` | Операция блокируется когда событие и harness поддерживают блокировку. | Действие не должно продолжаться. | -Напишите причину для агента, который должен восстановиться. Объясните, что было обнаружено и что ему следует делать вместо этого. +Напишите причину для агента, который должен восстановиться. Объясните, что было обнаружено и что он должен делать вместо этого. - Не используйте `instruct()` для границы безопасности. Доставка рекомендаций варьируется в зависимости от обработчика агента. Используйте `deny()`, когда действие должно быть предотвращено. + Не используйте `instruct()` для границы безопасности. Доставка рекомендаций варьируется в зависимости от harness агента. Используйте `deny()` когда действие должно быть предотвращено. ## Объект политики @@ -82,14 +82,14 @@ customPolicies.add({ }); ``` -| Поле | Обязательно | Описание | +| Поле | Обязательное | Описание | | --- | --- | --- | -| `name` | Да | Стабильный идентификатор политики. Держите имена уникальными во всех файлах. | -| `description` | Нет | Читаемая цель, показываемая в списках политик и решениях. | -| `match.events` | Нет | Типы событий, которые вызывают политику. Если `match` опущен, политика вызывается для каждого доступного события. | +| `name` | Да | Стабильный идентификатор политики. Держите имена уникальными в разных файлах. | +| `description` | Нет | Читаемое назначение, показываемое в списках политик и решениях. | +| `match.events` | Нет | Типы событий, которые вызывают политику. Пропуск `match` вызывает её для каждого доступного события. | | `fn` | Да | Синхронная или асинхронная функция, которая возвращает результат `allow`, `instruct` или `deny`. | -Фильтруйте инструменты внутри `fn`. `match.toolNames` не является частью публичного типа пользовательской политики. +Фильтруйте инструменты внутри `fn`. `match.toolNames` не является частью публичного типа custom-policy. ## Контекст политики @@ -97,21 +97,21 @@ customPolicies.add({ | Поле | Тип | Что оно содержит | | --- | --- | --- | -| `eventType` | `HookEventType` | Нормализованное событие, которое в настоящее время оценивается. | -| `toolName` | `string \| undefined` | Каноническое имя инструмента, такое как `Bash`, `Read`, `Write` или `Edit`. | +| `eventType` | `HookEventType` | Нормализованное событие, которое в данный момент оценивается. | +| `toolName` | `string \| undefined` | Канонический имя инструмента, такое как `Bash`, `Read`, `Write` или `Edit`. | | `toolInput` | `Record \| undefined` | Канонический ввод для текущего вызова инструмента. | -| `payload` | `Record` | Полная нормализованная полезная нагрузка события. | -| `session` | `SessionMetadata \| undefined` | ID сессии, рабочий каталог, путь к транскрипту, режим разрешений и метаданные обработчика, если доступны. | -| `cli` | `string \| undefined` | Исходный обработчик агента, такой как `claude`, `codex` или `cursor`. | -| `params` | `Record` | Параметры встроенной политики. Пользовательские политики в настоящее время получают пустой объект. | +| `payload` | `Record` | Полный нормализованный payload события. | +| `session` | `SessionMetadata \| undefined` | ID сессии, рабочая директория, путь транскрипта, режим разрешений и метаданные harness, когда доступны. | +| `cli` | `string \| undefined` | Исходный harness агента, такой как `claude`, `codex` или `cursor`. | +| `params` | `Record` | Встроенные параметры политики. Пользовательские политики в настоящее время получают пустой объект. | -Рассматривайте каждое необязательное значение как действительно необязательное. Версии агентов и типы событий не предоставляют одни и те же поля. +Рассматривайте каждое необязательное значение как действительно необязательное. Версии агентов и типы событий не предоставляют одинаковые поля. -### Распространённые входные данные инструментов +### Общие входы инструментов -Failproof AI нормализует распространённые инструменты по поддерживаемым обработчикам, чтобы политика обычно могла использовать одну форму ввода. +Failproof AI нормализует общие инструменты в поддерживаемых harnesses, поэтому политика обычно может использовать одну форму ввода. -| Инструмент | Распространённые поля | +| Инструмент | Общие поля | | --- | --- | | `Bash` | `command` | | `Read` | `file_path` | @@ -119,7 +119,7 @@ Failproof AI нормализует распространённые инстр | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | -Используйте защитное приведение типов, поскольку значения входных данных инструмента типизированы как `unknown`: +Используйте оборонительное приведение типов, потому что значения входа инструмента типизированы как `unknown`: ```ts const command = String(ctx.toolInput?.command ?? ""); @@ -131,22 +131,22 @@ const filePath = String(ctx.toolInput?.file_path ?? ""); | Событие | Когда оно выполняется | Типичное использование | | --- | --- | --- | | `PreToolUse` | Перед выполнением инструмента. | Блокируйте или направляйте команды, записи, чтения и внешние действия. | -| `PostToolUse` | После возврата инструмента. | Проверьте результаты перед тем, как они достигнут агента. Отказ блокирует весь результат; он не редактирует избранные поля. | +| `PostToolUse` | После возврата инструмента. | Проверьте результаты перед тем, как они достигнут агента. Отказ блокирует весь результат; он не редактирует выбранные поля. | | `PermissionRequest` | Когда агент запрашивает разрешение. | Применяйте правила разрешений, специфичные для организации. | | `UserPromptSubmit` | Перед продолжением отправленной подсказки. | Отклоняйте запрещённые инструкции или добавляйте рекомендации по рабочему процессу. | -| `Stop` | Когда агент пытается завершить работу. | Требуйте достижимое условие завершения, например локальный шаг проверки. | -| `SubagentStop` | Когда подагент пытается завершить работу. | Контролируйте делегированную работу перед её возвращением в родительский процесс. | -| `SessionStart` / `SessionEnd` | На границах сессии. | Записывайте или проверяйте состояние на уровне сессии. | +| `Stop` | Когда агент пытается завершить. | Требуйте достижимое условие завершения, такое как локальный шаг проверки. | +| `SubagentStop` | Когда субагент пытается завершить. | Контролируйте делегированную работу перед её возвратом к родительскому процессу. | +| `SessionStart` / `SessionEnd` | На границах сессии. | Запишите или проверьте состояние на уровне сессии. | -Доступность события и поведение блокирования зависят от обработчика агента. См. [Обработчики агентов](/ru/reference/harnesses) перед использованием события на смешанном парке. +Доступность события и поведение блокировки зависят от harness агента. Смотрите [Agent harnesses](/ru/reference/harnesses) перед использованием события в смешанном парке. - + `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` и `Setup`. -## Создание распространённых шаблонов политик +## Разработка общих паттернов политик -### Блокирование записей в защищённые пути +### Блокируйте записи в защищённые пути ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -166,7 +166,7 @@ customPolicies.add({ }); ``` -### Предоставление нераспорядительных рекомендаций +### Дайте неблокирующие рекомендации ```ts import { customPolicies, allow, instruct } from "failproofai"; @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### Контроль завершения сессии +### Контролируйте завершение сессии ```ts import { execFileSync } from "node:child_process"; @@ -215,7 +215,7 @@ customPolicies.add({ ``` - Отказанное событие `Stop` может заставить агента повторить попытку. Только контролируйте условие, которое агент может удовлетворить в текущем окружении, и ограничивайте каждый подпроцесс или сетевой вызов. + Отказанное событие `Stop` может заставить агента повторить попытку. Контролируйте только условие, которое агент может удовлетворить в текущей среде, и ограничивайте каждый подпроцесс или сетевой вызов. ## Загрузка файлов политик @@ -229,16 +229,16 @@ customPolicies.add({ ~/.failproofai/policies/personal-policies.mjs ``` -- Загружаются как проектные, так и пользовательские каталоги политик. -- Файлы загружаются в алфавитном порядке в каждом каталоге. +- Загружаются как проектные, так и пользовательские директории политик. +- Файлы загружаются в алфавитном порядке в каждой директории. - Файл должен заканчиваться на `policies.js`, `policies.mjs` или `policies.ts`. -- В одном файле поддерживаются несколько вызовов `customPolicies.add()`. +- Поддерживаются множественные вызовы `customPolicies.add()` в одном файле. - Поддерживаются относительные импорты из локальных модулей. -- Проектные политики можно закоммитить, чтобы одни и те же правила следовали репозиторию. +- Проектные политики могут быть закомиченты, так что одинаковые правила следуют репозиторию. ### Явные файлы -Используйте явные пути, когда валидация или конфигурация должна назвать файл точки входа напрямую: +Используйте явные пути когда валидация или конфигурация должны назвать файл входа напрямую: ```bash failproofai policies --install \ @@ -247,9 +247,9 @@ failproofai policies --install \ --scope project ``` -Явные файлы загружаются первыми, затем следуют файлы проектных соглашений и затем файлы пользовательских соглашений. Файл, обнаруженный через оба пути, загружается один раз. +Явные файлы загружаются первыми, затем следуют проектные файлы соглашений и пользовательские файлы соглашений. Файл, обнаруженный по обоим путям, загружается один раз. -## Валидация и тестирование +## Валидируйте и тестируйте Валидация выполняет модуль через продакшн-загрузчик и подтверждает, что он регистрирует по крайней мере одну политику. @@ -260,30 +260,30 @@ failproofai policies --install \ failproofai policies ``` -Валидация выявляет отсутствующие файлы, синтаксические ошибки, неразрешённые импорты, исключения верхнего уровня и тайм-ауты загрузки модуля. Она не доказывает, что ваша логика совпадения корректна. +Валидация ловит отсутствующие файлы, синтаксические ошибки, неразрешённые импорты, исключения верхнего уровня и таймауты загрузки модуля. Она не доказывает, что ваша логика совпадения правильна. Протестируйте по крайней мере эти случаи: -- Одно действие, которое должно совпадать и произвести предполагаемую причину политики. -- Одно близкое, но безопасное действие, которое должно вернуть `allow()`. -- Отсутствующие или неправильно сформированные поля инструмента. -- Альтернативный синтаксис команды, пути, кавычки, прописные буквы и пробелы. +- Одно действие, которое должно совпасть и произвести предполагаемую причину политики. +- Одно близкое но безопасное действие, которое должно вернуть `allow()`. +- Отсутствующие или неправильно сформированные поля инструментов. +- Альтернативный синтаксис команд, пути, кавычки, регистр и пробелы. - Недоступная зависимость подпроцесса или сети. -Атрибутируйте результат вашей пользовательской политике в разделе **Observe → policy**. Заблокированный тест недостаточен, если другая встроенная политика приняла решение. +Приписывайте результат вашей пользовательской политике в **Observe → policy**. Заблокированный тест недостаточен, если другая встроенная политика приняла решение. -## Поведение во время выполнения +## Поведение при выполнении - Встроенные политики оцениваются перед пользовательскими политиками. -- Первый `deny` прекращает дальнейшую оценку политики. -- Несколько результатов `instruct` могут быть объединены, когда ни одна политика не отказывает событие. -- Функция политики имеет крайний срок выполнения в 10 секунд. -- Выброшенное исключение или тайм-аут регистрируется и обрабатывается как `allow()`. -- Файл соглашения, который не загружается, пропускается; другие пользовательские файлы и встроенные политики продолжают работу. -- Загрузка модуля верхнего уровня также имеет крайний срок в 10 секунд. -- Режим облачного наблюдения выполняет политику, но записывает решение, не являющееся allow, без его применения. +- Первый `deny` останавливает дальнейшую оценку политики. +- Множественные результаты `instruct` могут быть объединены, когда ни одна политика не отклоняет событие. +- Функция политики имеет дедлайн выполнения 10 секунд. +- Выброшенное исключение или таймаут логируется и рассматривается как `allow()`. +- Файл соглашений, который не загружается, пропускается; другие пользовательские файлы и встроенные политики продолжаются. +- Загрузка модуля верхнего уровня также имеет дедлайн 10 секунд. +- Режим облачного наблюдения выполняет политику но записывает решение, не относящееся к allow, без применения его. -Держите модули политик детерминированными и быстрыми. Избегайте сетевых вызовов верхнего уровня или запуска сервера. Ограничивайте работу внутри `fn`, обрабатывайте сбои зависимостей и сознательно выбирайте, должен ли этот сбой разрешить или заблокировать операцию. +Держите модули политик детерминированными и быстрыми. Избегайте вызовов сети верхнего уровня или запуска сервера. Ограничивайте работу внутри `fn`, ловите сбои зависимостей и сознательно выбирайте должно ли это разрешение или отказ выполнить операцию. ## Экспорты API @@ -291,13 +291,13 @@ failproofai policies | --- | --- | | `customPolicies.add(policy)` | Зарегистрируйте пользовательскую политику при загрузке модуля. | | `allow(reason?)` | Разрешите операцию. | -| `instruct(reason)` | Разрешите операцию и предоставьте рекомендации, если поддерживается. | -| `deny(reason)` | Блокируйте операцию, где поддерживается. | -| `getCustomHooks()` | Верните политики, в настоящее время зарегистрированные в реестре модулей. | +| `instruct(reason)` | Разрешите операцию и предоставьте рекомендацию где поддерживается. | +| `deny(reason)` | Заблокируйте операцию где поддерживается. | +| `getCustomHooks()` | Верните политики, которые в настоящее время зарегистрированы в реестре модулей. | | `clearCustomHooks()` | Очистите этот реестр, в основном для тестов и загрузчиков. | TypeScript экспортирует `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` и `PolicyFunction`. - - Опубликуйте версию, разверните её в режиме наблюдения, проверьте решения и перейдите к применению. + + Опубликуйте версию, разверните её в режиме наблюдения, проверьте решения и переходите к применению. \ No newline at end of file diff --git a/docs/ru/sessions/evaluations.mdx b/docs/ru/sessions/evaluations.mdx index 63ec08d7..7611e47c 100644 --- a/docs/ru/sessions/evaluations.mdx +++ b/docs/ru/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "Онлайн-оценки" -description: "Оценивайте активные и завершенные сессии по качеству, соответствию, стоимости и задержке." +title: "Читать результаты оценок" +description: "Визуализируйте оценки на графике во времени, сравнивайте агентов и окружения, узнайте, почему сессия получила низкий балл, и задайте вопросы ассистенту." icon: "gauge" --- -Онлайн-оценки применяют согласованные критерии к сессиям агентов. Используйте их для метрик, которые должны измеряться постоянно, а не только исследоваться во время аудита. +Результаты каждой оценки, размещённой на хосте или от вашего собственного обработчика, попадают в одни и те же места. -## Проверка качества оценок +## Сравнивайте оценки во времени - - 1. Перейдите в **Observe → Evaluations**. - 2. Добавьте серию и выберите агента, окружение, метрику оценки, статистику и кривую. - 3. Добавьте серии для сравнения окружений, агентов или ключей оценки. - 4. Выберите результат, чтобы открыть соответствующие сессии или поделиться отфильтрованным представлением. Используйте **Observe → Metrics** для значений задержки, токенов, стоимости и других величин. + + Перейдите в **Observe → evaluations**. - ![Панель качества, показывающая средние оценки и тренды во времени.](/images/dashboard/dashboard-quality.png) + - **Recent runs** перечисляет каждую оценку по мере её поступления: откуда она пришла — от размещённого (**managed**) или вашего собственного (**customer**) оценивателя, агент и сессию, оценку и её версию, статус и оценку или метрики. + - **Score over time** строит график для выбранных вами данных. Выберите **add series** и укажите агент, окружение, оценку и статистику: avg, min, max, p50, p75, p90, p95, p99, stddev или mode. Каждый ряд — одна линия; задайте ей собственную **curve**, чтобы нарисовать её на отдельном графике. - Откройте сессию из детализации, чтобы проверить рассуждение для каждой оценки: + ![Страница оценок: недавние запуски с меткой customer, график оценок во времени со справочными линиями на 0.5 и 0.8, и один ряд, усредняющий finished_clean по всем агентам и окружениям.](/images/dashboard/evaluations-chart.png) - ![Представление деталей сессии с оценками и рассуждениями рядом с полной трассировкой.](/images/dashboard/session-detail.png) + Один диапазон времени и один размер интервала применяются ко всем рядам. Мелкий интервал помогает найти инцидент; крупный показывает тренд и может скрыть скачки, которые вы ищете. Интервал, где ничего не оценивалось — это разрыв в линии, никогда не нуль, а справочные линии отмечают 0.5 и 0.8. + + Каждая часть представления находится в URL: нажмите **share**, чтобы скопировать его, и любой, кто откроет ссылку, увидит ровно то сравнение, которое вы построили. ```bash @@ -32,21 +32,25 @@ icon: "gauge" -Оценивающая функция получает идентификатор сессии, окружение, временные метки и упорядоченные события. Она может возвращать числовые ключи оценок с необязательным рассуждением и резюме. Долгоживущие оценивающие функции могут возвращать ожидающую задачу и быть опрошены позже. +Визуализируйте **avg** и **p90** для одной и той же оценки, чтобы увидеть, скрывает ли хорошее среднее плохой хвост, или одну и ту же оценку для двух агентов, или для production и staging, чтобы сравнить их на одной оси. Затраты, задержки и количество токенов, которые имеют единицы измерения, отображаются под **Observe → metrics**, один график на единицу. + +## Узнайте, почему сессия получила низкий балл + +Откройте сессию из **Observe → sessions**; таблица содержит оценки каждой сессии и фильтрует по диапазону оценок. Правая панель сессии начинается с краткого резюме оценки, затем идёт полоса для каждой оценки с рассуждением оценивателя под ней. + +![Представление деталей сессии, показывающее оценки и рассуждения оценивателя рядом с полной трассировкой.](/images/dashboard/session-detail.png) + +## Задавайте вопросы ассистенту + +Спрашивайте об оценках на простом английском языке: "tell me about some of the recent evaluations" или какие оценки агентов понижаются. [Ассистент](/ru/sessions/assistant) читает и анализирует результаты и отвечает таблицами, на которые можно дать уточнение, а интересный вопрос можно сохранить как [запрос](/ru/sessions/queries) или [панель управления](/ru/sessions/dashboards). -## Хорошие цели для оценивания +![Страница оценок рядом с ассистентом, который отвечает на "tell me about some of the recent evaluations" сводкой по итогам, статусам и оценкам.](/images/dashboard/evaluations-assistant.png) -- Завершенность задачи или корректность -- Обоснованность и риск галлюцинаций -- Выбор инструментов и эффективность их использования -- Соответствие политикам или процессам -- Бюджеты по стоимости и задержке -- Необходимость эскалации к человеку +## Отслеживайте и действуйте -## От оценки к действию +- **Dashboards**, в разделе **Analyze → dashboards**, показывают тренды отобранных вами оценок по агентам и окружениям для всей организации. -Отображайте оценки на панелях для отслеживания трендов. Создавайте оповещения для пороговых или комбинированных условий. Когда оценка снижается в группе сессий, запустите аудит для исследования причины; когда причина — повторяющееся действие, разверните политику. + ![Панель качества, показывающая средние оценки и тренды во времени.](/images/dashboard/dashboard-quality.png) - - Реализуйте синхронную или асинхронную оценку с помощью SDK оценивающей функции на Python. - \ No newline at end of file +- **Alerts** уведомляют вас, когда оценка пересекает порог. См. [alerts](/ru/audits/alerts). +- Когда оценка падает по многим сессиям, [запустите аудит](/ru/audits/run), чтобы узнать причину; если причина — повторяющееся действие, [напишите политику](/ru/policies/editor). \ No newline at end of file diff --git a/docs/ru/start/integrations/custom-agents.mdx b/docs/ru/start/integrations/custom-agents.mdx index 38170069..17b107d2 100644 --- a/docs/ru/start/integrations/custom-agents.mdx +++ b/docs/ru/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "Пользовательские агенты" sidebarTitle: "Пользовательские агенты" -description: "Инструментируйте агента, написанного вами самим, или фреймворк, для которого нет адаптера." +description: "Инструментируйте агента, который вы написали сами, или фреймворк без адаптера." icon: "code" --- -Для агента, написанного вами самим, или фреймворка, для которого у Failproof AI нет адаптера. Здесь нечего инструментировать: вы сами испускаете события. +Для агента, который вы написали сами, или фреймворка, для которого у Failproof AI нет адаптера. Инструментировать нечего — вы сами генерируете события. -Это тот же API, который используют четыре встроенных адаптера фреймворков. Они — таблицы трансляции над ним. +Это тот же API, который используют четыре адаптера фреймворков. Они — таблицы трансляции над ним. ## Установка @@ -15,9 +15,9 @@ icon: "code" pip install failproofai-sdk ``` -Без дополнительных зависимостей. +Никаких дополнений и зависимостей. -## Инструментация +## Инструментирование ```python import failproofai_sdk @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # один запуск t.output = search(q) # один вызов инструмента ``` -Читайте сверху вниз — это говорит, что имеется в виду: +Читайте сверху вниз — и станет ясно, что это означает: | Оберните в | Чтобы сказать | | --- | --- | -| `session()` | Эти события относятся к одному запуску | -| `agent()` | Что-то работает — дайте ему имя, которое вы узнаете в списке | +| `session()` | Эти события принадлежат одному запуску | +| `agent()` | Что-то выполняет работу — дайте ему имя, которое вы узнаете в списке | | `tool_call()` | Это один инструмент и вот что он вернул | -И что каждый из них на самом деле испускает: +И что каждый из них фактически генерирует: -| Область | Испускает | Назначение | +| Область | Генерирует | Назначение | | --- | --- | --- | -| `session()` | Ничего | Привязывает идентификатор сессии, группирует один запуск | -| `agent()` | `agent_start`, `agent_end` | Обрамляет единицу работы | -| `tool_call()` | `tool_use`, `tool_result` | Обрамляет один инструмент и измеряет его | +| `session()` | Ничего | Привязывает session id, группируя один запуск | +| `agent()` | `agent_start`, `agent_end` | Ограничивает единицу работы | +| `tool_call()` | `tool_use`, `tool_result` | Ограничивает один инструмент и его результат | -Всё внутри может опустить `session_id` и `agent_id`. Области привязывают идентичность к переменным контекста, и каждый вызов события считывает её обратно, поэтому вы никогда не передаёте идентификаторы через функции. +Всё внутри может опустить `session_id` и `agent_id`. Области привязывают идентификацию на переменные контекста и каждый вызов события читает её обратно, поэтому вам никогда не нужно передавать id через функции. -Все три работают как с `async with`, так и с `with`. +Все три работают с `async with` наравне с `with`. -Вложение агентов строит дерево. `parent_id` и глубина вычисляются из стека: +Вложенные агенты строят дерево. `parent_id` и глубина вычисляются из стека: ```python with failproofai_sdk.session(): @@ -59,7 +59,7 @@ with failproofai_sdk.session(): ... ``` -## Как область закрывается +## Как закрывается область `agent()` обрабатывает исключения за вас: @@ -70,35 +70,35 @@ with failproofai_sdk.session(): | `KeyboardInterrupt`, `SystemExit` | `error`, затем `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | только `agent_end` | `cancelled` | -Ошибка испускается до `agent_end`, потому что панель закрывает span на `agent_end`, и всё после этого атрибутируется ничему. Отмена — не неудача, поэтому отменённые запуски не загрязняют поверхность ошибок. Исключение всегда переиспускается: область никогда не глушит. +Ошибка генерируется перед `agent_end`, потому что панель управления закрывает span при `agent_end` и всё после этого не атрибутируется ничему. Отмена — не ошибка, поэтому отменённые запуски не загромождают поверхность ошибок. Исключение всегда переиспускается: область никогда его не подавляет. -## Методы событий +## Методы события -Пятнадцать методов в шести семействах. Большинство идут парами — вы испускаете открытие, затем закрытие, и SDK измеряет промежуток между ними. +Пятнадцать методов в шести семействах. Большинство идут парами — вы генерируете открывающее событие, затем закрывающее, и SDK измеряет промежуток между ними. -| Семейство | Открывает | Закрывает | Самостоятельно | +| Семейство | Открывает | Закрывает | Самостоятельное | | --- | --- | --- | --- | -| **Агенты** | `agent_start` | `agent_end` | — | +| **Agents** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | -| **Модели** | `model_request` | `model_response` | — | -| **Инструменты** | `tool_use` | `tool_result` | — | +| **Models** | `model_request` | `model_response` | — | +| **Tools** | `tool_use` | `tool_result` | — | | **Hooks** | `hook_triggered` | `hook_completed` | — | -| **Люди** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | -| **Ошибки** | — | — | `error` | +| **Humans** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **Failures** | — | — | `error` | - Предпочитайте области — `agent()` и `tool_call()` — где они подходят. Они гарантируют событие закрытия даже если тело возбуждает исключение. Обращайтесь к этим методам напрямую, когда ваш поток управления не вложен, например вызов модели внутри вспомогательной функции. + Предпочитайте области — `agent()` и `tool_call()` — везде, где они подходят. Они гарантируют закрывающее событие даже когда тело выбрасывает исключение. Обращайтесь к этим методам напрямую, когда ваш управляющий поток не вложен, например вызов модели внутри вспомогательной функции. -```python Агенты +```python Agents failproofai_sdk.event.agent_start(agent_id="planner", goal="find the cheapest flight") failproofai_sdk.event.agent_end(agent_id="planner", outcome="success", summary="...") failproofai_sdk.event.agent_pause(pause_id="p1", reason="awaiting approval") failproofai_sdk.event.agent_resume(pause_id="p1") ``` -```python Модели +```python Models failproofai_sdk.event.model_request( model="gpt-4o-mini", messages=[{"role": "user", "content": "..."}], @@ -114,7 +114,7 @@ failproofai_sdk.event.model_response( ) ``` -```python Инструменты +```python Tools failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1", input={"q": "..."}) failproofai_sdk.event.tool_result(tool_name="search", tool_call_id="c1", output="...") ``` @@ -124,14 +124,14 @@ failproofai_sdk.event.hook_triggered(hook_name="retrieve", hook_id="h1", trigger failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome="success") ``` -```python Люди +```python Humans failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") failproofai_sdk.event.human_interrupt(reason="operator stopped the run", at_step="step_3") ``` -```python Ошибки +```python Failures failproofai_sdk.event.error( error_type="TimeoutError", message="provider timed out after 30s", @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **Два семейства «люди» указывают в противоположные стороны.** + **Два семейства human указывают в противоположных направлениях.** | Методы | Значение | | --- | --- | - | `human_wait` / `human_input` | **Агент попросил человека** — врата одобрения, уточняющий вопрос | - | `human_pause` / `human_interrupt` | **Человек действовал на агента** — кнопка стоп, пауза оператора | + | `human_wait` / `human_input` | **Агент попросил человека** — ворота одобрения, уточняющий вопрос | + | `human_pause` / `human_interrupt` | **Человек действовал на агента** — кнопка остановки, пауза оператора | - Ни один фреймворк не сигнализирует вторую пару, поэтому вы всегда испускаете её. + Ни один фреймворк не сигнализирует вторую пару, поэтому её всегда нужно генерировать вам. - **Передавайте `request_id` когда вызовы модели выполняются одновременно.** Без него запросы и ответы согласуются в порядке прихода на агента — и одновременные вызовы не согласуются, каждый ответ прикрепляется к неправильному запросу. + **Передавайте `request_id` когда вызовы модели выполняются одновременно.** Без него запросы и ответы сопряжаются в порядке поступления за агента — и одновременные вызовы неправильно сопрягаются, присоединяя каждый ответ к неправильному запросу. ## Пример -Цикл вызовов инструментов с API OpenAI без фреймворка агента: +Цикл вызовов инструментов против OpenAI API без фреймворка агента: ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """Один вызов модели, обрамлённый парой.""" + """Один вызов модели, ограниченный парой событий.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # ограничено; неограниченный цикл агента — его собственная ошибка + for _ in range(4): # ограниченное количество; бесконечный цикл агента — его собственная ошибка message = turn(messages) if not message.tool_calls: break @@ -204,44 +204,44 @@ with failproofai_sdk.session(): }) ``` -Это производит те же шесть типов событий, которые дал бы адаптер. Полная исполняемая версия с определениями инструментов поставляется в репозитории SDK в `docs/manual/examples/`. +Это генерирует те же шесть типов событий, которые даст адаптер. Полная рабочая версия с определениями инструментов поставляется в репозитории SDK в `docs/manual/examples/`. ## Потоки и async -Переменные контекста распространяются в задачи asyncio автоматически. Они не распространяются в новые потоки, потому что поток начинается с пустым контекстом. +Переменные контекста автоматически распространяются в asyncio задачи. Они не распространяются в новые потоки, потому что поток начинается с пустым контекстом. ```python # asyncio: ничего не нужно делать async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# потоки: оберните вызываемое +# threads: оберните callable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Без `propagate()` события рабочего возбуждают `TypeError`, называя исправление, а не приземляются без сессии. Это намеренно: событие без сессии пропускается при приёме и отвечается `200`, что является молчаливой неудачей, которую предотвращает слой идентичности. +Без `propagate()` события рабочего выбросят `TypeError` с названием исправления вместо приземления без session. Это намеренно: событие без session пропускается при обработке и ему ответили `200`, что — это скрытый отказ, который существует уровень идентификации чтобы предотвратить. -## Инструментируйте фреймворк без адаптера +## Инструментирование фреймворка без адаптера -Каждый фреймворк агентов даёт вам одни и те же три точки соединения. Отобразите их — и у вас есть полная трассировка — четыре встроенных адаптера ничего больше не делают. +Каждый фреймворк агента даёт вам те же три точки. Отобразите их — и у вас есть полная трассировка. Четыре поставляемых адаптера делают ровно это. -| Точка соединения | Что вы пишете | Что приземляется | +| Точка | Что вы пишете | Что попадает | | --- | --- | --- | | Запуск | `session()` + `agent()` | `agent_start`, `agent_end` | | Каждый инструмент | `tool_call()` | `tool_use`, `tool_result` | | Каждый вызов модели | Пара `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - + В чём бы фреймворк ни называл обёртку инструмента или middleware. ```python @@ -249,7 +249,7 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -264,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **Есть граница узла, шага или middleware, достойная внимания?** Оберните её в пару hook — `hook_triggered` / `hook_completed` — а не вложенный `agent()`. `agent_id` — низкокардинальный аспект, и одна запись на узел его топит. Spans hook отображаются одинаково и дают вам задержку на узел. + **Есть граница узла, шага или middleware, достойная внимания?** Оберните её в пару hook — `hook_triggered` / `hook_completed` — а не вложенный `agent()`. `agent_id` — низко-кардинальный фасет, и одна запись на узел его захламляет. Span-ы hook отображаются так же и дают вам задержку за узел. - **Ручная и автоматическая комбинируются.** Адаптер, работающий внутри написанной вручную области, присоединяется к этой сессии и становится родителем этому агенту, так что вы получаете одно дерево вместо двух — полезно когда вы инструментируете один фреймворк сами рядом с поддерживаемым. + **Ручное и автоматическое взаимодействуют.** Адаптер, работающий внутри ручной области, присоединяется к этой session и становится родителем этого агента, поэтому вы получаете одно дерево вместо двух — это полезно когда вы инструментируете один фреймворк сами наряду с поддерживаемым. - Две причины, и три точки соединения выше — ответ на обе: + Две причины, и три точки выше — ответ на обе: - `autogen-core` не обслуживается с сентября 2025. - - AG2 не предоставляет глобальную точку регистрации, эквивалентную hooks других фреймворков, поэтому инструментация означает обёртывание каждого агента в каждом месте конструкции. + - AG2 не раскрывает точку регистрации масштаба процесса, эквивалентную хукам других фреймворков, поэтому инструментирование означает обёртывание каждого агента на каждом месте конструирования. - Отображение точек соединения вручную записывает те же события с той же полнотой, что делал бы встроенный адаптер. + Ручное отображение точек записывает те же события с той же точностью, что и поставляемый адаптер. ## Глубже -Как запись на самом деле работает. Ничего из этого не требуется для начала. +Как запись фактически работает. Ничего из этого не требуется для начала. - + -Каждая запись имеет одну форму: span открывается, работа вложена в него, и каждое открывающее событие получает закрывающее. +Каждая запись имеет одну форму: span открывается, работа вложена внутри, и каждому открывающему событию соответствует закрывающее. ```mermaid flowchart LR @@ -300,13 +300,13 @@ flowchart LR C --> E(["agent_end"]) ``` -**Пара** — это единица. Каждое закрывающее событие несёт продолжительность, которую SDK измеряет от открывающего события. +**Пара** — это единица. Каждое закрывающее событие несёт длительность, которую SDK измеряет от открывающего. -Ниже — один реальный запуск на фреймворк — захвачен из примеров, поставляемых с SDK, имя модели нормализовано. Обратите внимание, сколько возвращается из одного вызова. +Ниже один реальный запуск на фреймворк — захвачен из примеров, которые поставляются с SDK, имя модели нормализовано. Обратите внимание, сколько возвращается из одного вызова. - ```text 14 событий + ```text 14 events 1 +0.000s agent_start LangGraph 2 +0.001s hook_triggered agent 3 +0.002s model_request gpt-4o-mini @@ -323,11 +323,11 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - Узлы становятся парами hook, так что вы получаете задержку на узел без их переполнения списка агентов. + Узлы становятся парами hook, поэтому вы получаете задержку за узел без того, чтобы они загромождали список агентов. - ```text 10 событий + ```text 10 events 1 +0.000s agent_start crew 2 +0.050s agent_start analyst · under crew 3 +0.057s model_request gpt-4o-mini @@ -340,11 +340,11 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - `role` каждого агента становится именем его span, так что задержка и трата токенов разбиваются на роль. + Каждый `role` агента становится имя span-а, поэтому задержка и трата токенов разбиваются по role. - ```text 26 событий + ```text 26 events 1 +0.000s agent_start Agent 2 +0.001s hook_triggered init_run 4 +0.501s hook_triggered setup_agent @@ -356,15 +356,15 @@ flowchart LR 13 +3.355s tool_use city_population 14 +3.355s tool_result city_population · ok 16 +3.356s hook_triggered aggregate_tool_results - ... вторая итерация + ... second iteration 26 +7.038s agent_end Agent · success ``` - Цикл агента видим сам, не только его вызовы модели. + Цикл агента сам видим, не только его вызовы модели. - ```text 8 событий + ```text 8 events 1 +0.000s agent_start agent 2 +0.001s model_request gpt-4o-mini 3 +4.413s model_response gpt-4o-mini · 17 out-tok @@ -375,11 +375,11 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - Нет пар hook: Pydantic AI не имеет границы узла или шага для обрамления. + Нет пар hook: Pydantic AI не имеет границы узла или шага для ограничения. - - ```text 6 событий + + ```text 6 events 1 +0.000s agent_start main 2 +0.000s tool_use population 3 +0.000s tool_result population · ok @@ -388,36 +388,36 @@ flowchart LR 6 +0.000s agent_end main · success ``` - Вы испускаете их сами. Те же типы событий, та же полнота — это стоит вам вызовов. + Вы генерируете их сами. Те же типы событий, та же точность — это стоит вам мест вызовов. - + -**Нет события конца сессии.** Сессия — это не то, что вы закрываете — это группа событий, делящих `session_id`. +**Нет события завершения session.** Session — это не то, что вы закрываете — это группа событий, разделяющих `session_id`. Статус выводится из формы трассировки: | Статус | Когда | | --- | --- | -| `ongoing` | По крайней мере один span ещё открыт | -| `paused` | `agent_pause` не имеет согласованного `agent_resume` | -| `error` | Ничего не открыто, и по крайней мере одно событие не удалось | -| `done` | Ничего не открыто, и ничего не не удалось | +| `ongoing` | По крайней мере один span всё ещё открыт | +| `paused` | `agent_pause` не имеет соответствующей `agent_resume` | +| `error` | Ничего не открыто и по крайней мере одно событие не прошло | +| `done` | Ничего не открыто и ничего не провалилось | -Поэтому сессия заканчивается, когда каждая пара закрыта. Адаптеры испускают `agent_end` за вас, и при разборке они закрывают всё ещё открытое и отмечают его неполным — сбойный запуск устанавливается как `done` с видимым промежутком вместо вечного зависания. +Поэтому session заканчивается когда каждая пара закрыта. Адаптеры генерируют `agent_end` для вас, и при завершении они закрывают всё ещё открытое и отмечают его неполным — упавший запуск урегулируется как `done` с видимым пробелом вместо вечного зависания. - Вот почему сессия может охватывать два вызова. LangGraph `interrupt()` приостанавливает запуск, корневой span намеренно остаётся открыт, и возобновляющий вызов закрывает его. Оба вызова — одна сессия. + Вот почему session может охватывать два вызова. `interrupt()` LangGraph пауза запуска, root span намеренно остаётся открыт, и возобновляющий вызов его закрывает. Оба вызова — одна session. - + -`session_id` и `agent_id` необязательны на каждом методе события. Опущены, они разрешаются из области охватывающей: +`session_id` и `agent_id` опциональны для каждого метода события. Опущены — они разрешаются из вмещающей области: ```python with failproofai_sdk.session(): @@ -425,50 +425,50 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Передача их явно всё ещё работает и имеет приоритет. Ничто не привязано и ничто не передано — вызов возбуждает `TypeError`, называя исправление, а не испускает событие без сессии, которое инgest пропустит отвечая `200`. +Их явная передача всё ещё работает и имеет приоритет. Без привязанного и без переданного вызов выбросит `TypeError` с названием исправления вместо того чтобы генерировать событие без session, которое ingest пропустит при ответе `200`. -Области привязывают идентичность к переменным контекста. Те распространяются в задачи asyncio автоматически но не в новые потоки — оберните рабочего в `failproofai_sdk.propagate()`. +Области привязывают идентификацию на переменные контекста. Они распространяются в asyncio задачи автоматически но не в новые потоки — оберните рабочего в `failproofai_sdk.propagate()`. #### Кто создаёт какой id -| Id | Создано | Примечания | +| Id | Создан | Заметки | | --- | --- | --- | -| `session_id` | Вы или SDK | `session("chat-42")` используется дословно; опущено, SDK генерирует `uuid4().hex` | -| `agent_id` | Вы или фреймворк | Из `agent("analyst")`, `role` CrewAI, `FunctionAgent.name`. Значение похожее на UUID отклоняется и заменяется | -| `tool_call_id`, `hook_id`, `request_id` | Вы или фреймворк | Адаптеры переиспользуют собственные run ids фреймворка, вот почему пары выживают прыжки потоков | -| **Event id** | **Cloud при приёме** | SDK не испускает ни один | -| **`dedup_key`** | **Cloud при приёме** | Хеш org, сессии, временной метки, типа и полезной нагрузки. Это реальная идентичность — она заставляет переданный batch схлопнуться вместо дублирования | +| `session_id` | Вы или SDK | `session("chat-42")` используется как есть; опущен, SDK генерирует `uuid4().hex` | +| `agent_id` | Вы или фреймворк | От `agent("analyst")`, CrewAI `role`, имя `FunctionAgent.name`. UUID-подобное значение отклоняется и заменяется | +| `tool_call_id`, `hook_id`, `request_id` | Вы или фреймворк | Адаптеры переиспользуют собственные id запуска фреймворка, вот почему пары выживают переходы через потоки | +| **Event id** | **Cloud at ingest** | SDK не генерирует | +| **`dedup_key`** | **Cloud at ingest** | Хеш org, session, timestamp, type и payload. Это реальная идентификация — делает повторённую партию коллапсом вместо дублирования | #### Как адаптеры разрешают `session_id` Первое совпадение выигрывает: -1. Явное значение `session_id` -2. Метаданные по вызову -3. Область охватывающая `session()` +1. Явная опция `session_id` +2. Per-call метаданные +3. Вмещающая область `session()` 4. Метаданные фреймворка 5. Собственный run id фреймворка -Это никогда не выдумывается пока существует одно из них — синтезированный id разделил бы один запуск на несколько сессий. +Она никогда не синтезируется пока одна из них существует — синтезированный id расколол бы один запуск на несколько session. -#### Держите `agent_id` низкокардинальным +#### Держите `agent_id` низко-кардинальным -Это первичный аспект на каждой поверхности панели, и колонка `LowCardinality(String)`. Значение на запуск деградирует колонку и заполняет раскрывающееся меню фильтра одной записью на запуск. +Это первичный фасет на каждой поверхности панели управления и `LowCardinality(String)` колонка. Per-run значение деградирует колонку и заполняет выпадающий фильтр одной записью за запуск. -Адаптеры защищают эту колонку за вас: +Адаптеры защищают эту колонку для вас: -| Фреймворк передаёт | Записывается как | Почему | +| Фреймворк передаёт | Записано как | Почему | | --- | --- | --- | -| `3f9a1c2b-…` (UUID) | `main` | Нечего читаемое держать | -| Длинная голая hex-строка | `main` | То же | -| `agent-3f9a1c2b-…` | `agent` | Id на запуск убран, читаемая часть сохранена | -| `agent-v2` | `agent-v2` | Короткие сегменты оставлены в покое | -| `step-3` | `step-3` | То же | +| `3f9a1c2b-…` (UUID) | `main` | Нечего читаемого хранить | +| Долгая чистая hex строка | `main` | То же самое | +| `agent-3f9a1c2b-…` | `agent` | Per-run id удалён, читаемая часть сохранена | +| `agent-v2` | `agent-v2` | Короткие сегменты оставлены одни | +| `step-3` | `step-3` | То же самое | -Реальный id сохранён на `fw_agent_id` / `fw_run_id`, где он остаётся запрашиваемым без того, чтобы быть аспектом. +Реальный id хранится на `fw_agent_id` / `fw_run_id`, где остаётся queryable без того чтобы быть фасетом. - **Эта защита трогает только ярлыки, выбранные *фреймворком*.** `agent_id`, который вы передали сами — в `event.*` или в `failproofai_sdk.agent(...)` — записывается ровно как дано. Молчаливая переделка явного аргумента хуже кардинальности, которую она предотвращает, поэтому назовите свои spans соответственно. + **Эта защита только трогает ярлыки, которые **фреймворк** выбрал.** `agent_id`, который вы сами передали — в `event.*` или в `failproofai_sdk.agent(...)` — записывается ровно как дано. Молчаливое переписывание явного аргумента было бы хуже чем кардинальность, которую оно предотвращает, поэтому называйте ваши span-ы сами соответственно. @@ -477,77 +477,77 @@ with failproofai_sdk.session(): | Группа | События | | --- | --- | -| Агенты | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | -| Модели | `model_request`, `model_response` | -| Инструменты | `tool_use`, `tool_result` | +| Agents | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| Models | `model_request`, `model_response` | +| Tools | `tool_use`, `tool_result` | | Hooks | `hook_triggered`, `hook_completed` | -| Люди | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | -| Ошибки | `error` | +| Humans | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| Failures | `error` | -Какой фреймворк что записывает, измеренное из запусков выше: +Какой фреймворк что записывает, измеренный от запусков выше: -| Событие | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | +| События | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | -| Начало и конец агента | Да | Да | Да | Да | Вы | -| Запрос и ответ модели | Да | Да | Да | Да | Вы | -| Использование и результат инструмента | Да | Да | Да | Да | Вы | -| Hook триггер и завершение | Узел | Задача | Шаг | — | Вы | -| Ошибка | Да | Да | Да | Да | Автоматически | -| Ожидание и ввод человека | Да | Да | Да | — | Вы | -| Пауза и возобновление агента | Да | Да | Да | — | Вы | +| Старт и конец агента | Yes | Yes | Yes | Yes | You | +| Запрос и ответ модели | Yes | Yes | Yes | Yes | You | +| Использование и результат инструмента | Yes | Yes | Yes | Yes | You | +| Hook triggered и completed | Node | Task | Step | — | You | +| Error | Yes | Yes | Yes | Yes | Automatic | +| Human wait и input | Yes | Yes | Yes | — | You | +| Agent pause и resume | Yes | Yes | Yes | — | You | -Прочерк означает, что фреймворк не имеет такой концепции. `human_pause` и `human_interrupt` описывают *человека*, действующего на агента, что ни один фреймворк не сигнализирует — испускайте их сами. +Тире означает фреймворк не имеет такой концепции. `human_pause` и `human_interrupt` описывают **человека**, действующего на агента, что ни один фреймворк не сигнализирует — генерируйте их сами. - + -Событие никогда не прибывает одно. Одно открывает span, одно закрывает его, и закрывающее событие несёт продолжительность, которую SDK измеряет от открывающего. +Событие никогда не приходит одно. Одно открывает span, одно закрывает его, и закрывающее событие несёт длительность, которую SDK измеряет от открывающего. | Открывает | Закрывает | Закрывающее событие несёт | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | -| `model_request` | `model_response` | токены, `stop_reason`, задержку | -| `tool_use` | `tool_result` | `output` или `error`, продолжительность | -| `hook_triggered` | `hook_completed` | `outcome`, продолжительность | -| `agent_pause` | `agent_resume` | как долго длилась пауза | -| `human_wait` | `human_input` | ответ и как долго человек ждал | +| `model_request` | `model_response` | токены, `stop_reason`, задержка | +| `tool_use` | `tool_result` | `output` или `error`, длительность | +| `hook_triggered` | `hook_completed` | `outcome`, длительность | +| `agent_pause` | `agent_resume` | как долго пауза длилась | +| `human_wait` | `human_input` | ответ и как долго человек занимал | - Открывающее событие без закрывающего — это span, который никогда не заканчивается. Сессия отображается всё ещё работающей вечно, и её активная продолжительность растёт. Это режим неудачи, который нужно наблюдать при инструментации вручную. + Открывающее событие без закрывающего — это span, который никогда не завершается. Session отображается как всё ещё работающий, навсегда, и его активная длительность продолжает расти. Это режим отказа, за которым нужно следить когда вы инструментируете вручную. #### Правила корреляции -- Переиспользуйте то же `tool_call_id`, `hook_id`, `pause_id` или `input_id` для согласованного события завершения. -- SDK вычисляет `duration_ms` для `tool_result`, `hook_completed`, `agent_resume` и `human_input`. Передача его этим методам возбуждает `ValueError`. -- `duration_ms` **принимается** на `model_response`, потому что только вызывающий знает реальную задержку провайдера. Это должно быть целое число — float возбуждает `ValueError` на месте вызова, потому что сервер читает колонку как беззнаковое 32-битное целое и хранил бы NULL для чего-либо ещё. -- Ключи корреляции ограничены типом и сессией, поэтому вызов инструмента и hook могут безопасно делить id, и две одновременные сессии могут переиспользовать одни и те же ids без коллизий. Они не ограничены агентом: пара открытая под одним агентом и закрытая под другим всё ещё коррелирует, что обычно в мультиагентных фреймворках. -- `request_id` согласует `model_request` с `model_response`. Без него события модели согласуются по порядку на агента, поэтому одновременные вызовы не согласуются. -- Пара, разделённая процессами, всё ещё коррелирует ниже по течению, но SDK не может вычислить её в процессе продолжительность. -- Карта ожидания содержит максимум 10 000 начал и вытесняет самую старую запись когда полна. +- Переиспользуйте тот же `tool_call_id`, `hook_id`, `pause_id` или `input_id` для соответствующего события завершения. +- SDK вычисляет `duration_ms` для `tool_result`, `hook_completed`, `agent_resume` и `human_input`. Передача его этим методам выбросит `ValueError`. +- `duration_ms` **принят** на `model_response`, потому что только вызывающий знает реальную задержку провайдера. Это должно быть целое число — float выбросит `ValueError` на месте вызова, потому что сервер читает колонку как 32-битное целое число без знака и сохранит NULL для чего-либо ещё. +- Ключи корреляции ограничены видом и session, поэтому вызов инструмента и hook могут безопасно разделить id, и две одновременные session могут переиспользовать те же id без столкновения. Они не ограничены агентом: пара открытая под одним агентом и закрытая под другим всё ещё коррелирует, это обычный случай в multi-agent фреймворках. +- `request_id` сопрягает `model_request` с `model_response`. Без него события модели сопрягаются в порядке за агента, поэтому одновременные вызовы неправильно сопрягаются. +- Пара разделённая через процессы всё ещё коррелирует downstream, но SDK не может вычислить её in-process длительность. +- Ожидающая карта держит максимум 10,000 стартов и вытеснит самую старую запись когда полна. -Установка `failproofai-sdk` устанавливает всё, все четыре адаптера включены. Extras тянут **фреймворк**, не адаптер. +Установка `failproofai-sdk` устанавливает всё, все четыре адаптера включены. Extras вытягивают **фреймворк**, а не адаптер. ```python -import failproofai_sdk # ничего за пределами стандартной библиотеки -failproofai_sdk.instrument() # импортирует только адаптеры, которые вы фактически используете +import failproofai_sdk # загружает ничего вне стандартной библиотеки +failproofai_sdk.instrument() # импортирует только адаптеры, которые вам фактически нужны ``` -`import failproofai_sdk` контрактно беззависимость, обеспечено тестом, который устанавливает встроенное колесо с `--no-deps` и другим, который доказывает что ни один фреймворк не достигает `sys.modules`. +`import failproofai_sdk` контрактно ноль-зависимости, принудительно тестом который устанавливает построенное колесо с `--no-deps` и другое которое доказывает что ни один фреймворк не достигает `sys.modules`. - Нет атрибута `failproofai_sdk.crewai`. Адаптеры намеренно не выставлены на пакет верхнего уровня: трогание одного импортировало бы фреймворк как побочный эффект доступа атрибута, нарушая обещание беззависимости. Используйте `instrument()`. + Нет атрибута `failproofai_sdk.crewai`. Адаптеры намеренно не раскрыты на пакете верхнего уровня: трогание одного импортировало бы фреймворк как побочный эффект доступа атрибута, ломая ноль-зависимость обещание. Используйте `instrument()`. ```python failproofai_sdk.instrument() # каждый фреймворк уже импортирован -failproofai_sdk.instrument("crewai") # ровно один по имени -failproofai_sdk.uninstrument("crewai") # верните его обратно +failproofai_sdk.instrument("crewai") # ровно один, по имени +failproofai_sdk.uninstrument("crewai") # вернуть его ``` | Имя | Также принимает | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # верните его обратно | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -Автообнаружение читает `sys.modules`, не список установленных пакетов, поэтому фреймворк, который вы установили но никогда не импортировали, не инструментируется и никогда не импортируется вашим именем. Чтобы видеть, что подключено: +Auto-detection читает `sys.modules`, не список установленных пакетов, поэтому фреймворк, который вы установили но никогда не импортировали, не инструментируется и никогда не импортируется от вашего имени. Чтобы увидеть что подключено: ```python from failproofai_sdk.integrations import active, available @@ -567,46 +567,46 @@ active() # ('langchain',) ``` - **`instrument("crewai")` на машине без CrewAI не возбуждает.** Оно логирует предупреждение и возвращает `()`, поэтому один отсутствующий фреймворк никогда не снимает процесс, который также инструментирует других. + **`instrument("crewai")` на машине без CrewAI не выбросит.** Это логирует предупреждение и возвращает `()`, поэтому один отсутствующий фреймворк никогда не возьмёт процесс который также инструментирует других. - Предупреждение несёт основной `ImportError`, и то сообщение называет точную команду установки — так что исправление в ваших логах, не спрятано. + Предупреждение несёт базовую `ImportError`, и это сообщение называет точную команду установки — поэтому исправление в ваших логах, не спрятано. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Установите `FAILPROOFAI_SDK_STRICT=1` чтобы заставить её возбуждать вместо этого. Этот флаг читается **один раз и кешируется**, поэтому экспортируйте его перед началом вашего процесса вместо установки посредине запуска. + Установите `FAILPROOFAI_SDK_STRICT=1` чтобы это выбросило вместо этого. Этот флаг читается **один раз и кэшируется**, поэтому экспортируйте его перед тем как ваш процесс начнётся вместо того чтобы устанавливать mid-run. - **`instrument()` должен идти *после* импорта вашего фреймворка*.** Автообнаружение читает `sys.modules`, поэтому голый вызов выше импорта находит ничего, устанавливает ничего и возвращает `()`. + **`instrument()` должен прийти *после* вашего импорта фреймворка.** Auto-detection читает `sys.modules`, поэтому чистый вызов выше импорта находит ничего, устанавливает ничего, и возвращает `()`. -```python Неправильно +```python Wrong import failproofai_sdk failproofai_sdk.instrument() # sys.modules ещё не имеет langchain -> () import langchain # слишком поздно, ничего не подключено ``` -```python Правильно +```python Right import langchain # импортируйте фреймворк первым import failproofai_sdk failproofai_sdk.instrument() # находит его -> ('langchain',) ``` -```python Правильно, порядок-доказательство +```python Right, order-proof import failproofai_sdk -# Называние его импортирует адаптер по запросу, поэтому это работает откуда угодно. +# Называние этого импортирует адаптер по запросу, поэтому это работает отовсюду. failproofai_sdk.instrument("langchain") ``` -Ошибитесь в этом и процесс работает с импортированным SDK, адаптер видимо установлен, и **ни одно событие не испущено**. Оно логирует предупреждение говоря ровно это — так что сначала проверьте ваши логи когда запуск ничего не записывает. +Получите это неправильно и процесс работает с импортированным SDK, видимо установленным адаптером, и **не одно событие не генерируется**. Это логирует предупреждение говоря ровно это — поэтому проверьте ваши логи первым когда запуск ничего не записывает. @@ -614,120 +614,122 @@ failproofai_sdk.instrument("langchain") ```mermaid flowchart LR - A["Ваш агент"] --> B["Адаптер"] - B --> C["Писатель
очередь в памяти"] - C -->|"каждые 0.5s"| D["Катушка
JSONL на диске"] - D --> E["Daemon Failproof"] + A["Your agent"] --> B["Adapter"] + B --> C["Writer
in-memory queue"] + C -->|"every 0.5s"| D["Spool
JSONL on disk"] + D --> E["Failproof daemon"] E -->|"HTTPS"| F["Cloud"] ``` -| Этап | Задача | Работает в | +| Этап | Работа | Работает в | | --- | --- | --- | -| Адаптер | Переводит callback фреймворка в один из 15 типов событий | Ваш процесс | -| Писатель | Ставит в очередь, батчит, пишет JSONL атомарно | Ваш процесс, фоновый поток | -| Катушка | Прочная передача, выживает выход вашего процесса | Локальный диск | -| Daemon | Смотрит на катушку, отправляет батчи, удаляет отправленное | Ваша машина | -| Приём | Назначает id строки и ключ dedup, повышает запрашиваемые колонки | Cloud | +| Adapter | Переводит обратный вызов фреймворка в один из 15 типов событий | Ваш процесс | +| Writer | Очереди, батчи, писать JSONL атомарно | Ваш процесс, фоновый поток | +| Spool | Прочная передача, выживает выход вашего процесса | Локальный диск | +| Daemon | Следит за spool, доставляет батчи, удаляет то что он доставил | Ваша машина | +| Ingest | Присваивает row id и dedup key, рекламирует queryable колонки | Cloud | -Катушка — это то, что делает это безопасным: ваш агент никогда не блокирует на сети, и Cloud outage означает растущий директорий вместо потерянных событий. +Spool — это то что делает это безопасным: ваш агент никогда не блокируется на сети, и Cloud outage означает растущую директорию вместо потерянных событий. -Каждый flush пишет один batch файл, `.tmp` первым, затем `fsync`, затем атомарное переименование: +Каждый flush пишет один batch файл, `.tmp` сначала, затем `fsync`, затем атомарное переименование: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Daemon берёт только `.jsonl`, поэтому он никогда не может читать полупиписанный файл. Основание несёт временную метку, id процесса и номер последовательности, поэтому два процесса, flushing в одной миллисекунде, не могут коллизировать. Очередь ограничена 10 000 событиями; свыше того она выбрасывает самое старое и логирует. +Daemon только подбирает `.jsonl`, поэтому никогда не может прочитать наполовину написанный файл. Stem несёт timestamp, process id и sequence number, поэтому два процесса flushing в той же миллисекунде не могут столкнуться. Очередь ограничена 10,000 событиями; сверх этого она отбрасывает самое старое и логирует. - **`collector.redact` по умолчанию `minimal` для событий SDK тоже.** SDK скребёт перед написанием batch на диск, и daemon повторяет тот же детерминистский проход перед загрузкой так что batch от старших SDKs защищены. + **`collector.redact` не применяется к вашим SDK событиям.** Он их никогда не видит. -Daemon читает каждый batch и применяет редакцию в памяти перед загрузкой. Он не переписывает файл катушки, который прочитал. +Daemon **доставляет** ваши батчи. Он их не открывает и не переписывает. -| События | Написаны | Где minimal редакция работает | +| События | Написано | Отредактировано `collector.redact`? | | --- | --- | --- | -| CLI стенограммы сессии | Daemon | Перед тем как daemon пишет batch | -| Активность Hook | Daemon | Перед тем как daemon пишет batch | -| **Всё что SDK испускает** | **Ваш процесс** | **Перед тем как SDK пишет batch и снова перед daemon загрузкой** | +| CLI session транскрипты | Daemon | Yes | +| Hook activity | Daemon | Yes | +| **Всё что SDK генерирует** | **Ваш процесс** | **No** | -Установите `collector.redact` на `off` только когда дословные полезные нагрузки — явное требование; SDK и daemon оба уважают эту установку. Minimal редакция ловит обычные API ключи, bearer токены, JWTs и секретные назначения. Она не может определить произвольную чувствительную прозу. +Редакция работает где daemon **пишет** его собственные события — не где батчи **доставляются**. Поэтому prompt или инструмент argument держащий API key всё ещё держит его по прибытии. + +Это намеренно. Это ваши собственные вызовы инструментирования, и переписывание их в пути бы означало события которые вы получаете не события которые вы генерировали. - **Вы управляете полезными нагрузками у источника в двух местах:** + **Вы контролируете payloads на источнике в двух местах:** - - Выключите захват содержимого на адаптере. **Имя опции различается, и один адаптер не имеет ни одного** — это не один универсальный переключатель: + - Выключите захват контента на адаптере. **Имя опции отличается и один адаптер не имеет** — это не один универсальный переключатель: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **нет переключателя содержимого**; `session_id` — единственная опция, которую он читает, так что prompts и completions всегда записываются. + - CrewAI — **no content switch at all**; `session_id` единственная опция, которую он читает, поэтому prompts и completions всегда записываются. - `instrument()` выбрасывает опции адаптер не читает, поэтому передача неправильного имени ничего не возбуждает и ничего не меняет. - - Не передавайте секрет в `input=` первом месте. + `instrument()` отбрасывает опции адаптер не читает, поэтому передача неправильного имени выбросит ничего и изменит ничего. + - Не передавайте secret в `input=` в первую очередь. - `collector.redact` — защита в глубину, не замена для любого. + `collector.redact` не является заменой для обоих. - **Пустой директорий катушки — здоровое состояние.** Не используйте его для проверки доставки. + **Пустая spool директория — здоровое состояние.** Не используйте её для проверки доставки. -Daemon удаляет каждый batch в миллисеконде доставки, поэтому `ls` гонится с collector и показывает дробь того, что вы испустили — неразличимо от SDK, который ничего не записал. +Daemon удаляет каждый батч в миллисекундах доставки, поэтому `ls` гонится по collector и показывает fraction того что вы генерировали — неразличимый от SDK который ничего не записал. -Чтобы подтвердить события действительно приземлились, проверьте панель. Чтобы смотреть катушку наполняться, сначала остановите daemon. +Чтобы подтвердить события действительно приземлились, проверьте панель управления. Чтобы看着 spool заполняться, сначала остановите daemon. - + -Каждый callback работает внутри обёртки, единственная задача которой переиспускать, поэтому ваш вызов сидит в ровно одном `try` и всё что SDK делает происходит вне него. +Каждый обратный вызов работает внутри обёртки чья единственная работа переиспустить, поэтому ваш вызов сидит в ровно одном `try` и всё что SDK делает происходит вне его. | Что происходит | Результат | | --- | --- | -| Hook возбуждает | Логируется один раз с traceback. Ваш вызов не затронут | -| Один и то же hook возбуждает три раза | Этот один hook отключён для остатка процесса с одной error линией | +| Hook выбросит | Логировано один раз с его traceback. Ваш вызов не затронут | +| Тот же hook выбросит трижды | Тот хук отключен для остатка процесса, с одной линией ошибки | | `FAILPROOFAI_SDK_STRICT=1` установлен | Исключение переиспущено вместо этого | | Версия фреймворка вне протестированного диапазона | Предупреждает один раз, инструментирует всё равно | -| Одна возможность отсутствует | Этот один hook отключён, никогда не весь адаптер | +| Один capability отсутствует | Тот хук отключен, никогда весь адаптер | -По умолчанию правильно в production и неправильно при отладке, потому что оно может только когда-нибудь доказать — не сломалось. Установите `FAILPROOFAI_SDK_STRICT=1` чтобы заставить проглоченную неудачу быть громкой. +Default правильный в production и неправильный при debugging, потому что может только когда-либо доказать that it did not crash. Установите `FAILPROOFAI_SDK_STRICT=1` чтобы сделать проглоченную ошибку громкой. -## Общие проблемы +## Частые проблемы - - Открывающее событие не имеет закрывающего: `model_request` без `model_response` или `tool_use` без `tool_result`. Используйте области, которые гарантируют пару даже когда тело возбуждает. Если вы вызываете методы события напрямую используйте `try` и `finally`. + + Открывающее событие не имеет закрывающего: `model_request` без `model_response` или `tool_use` без `tool_result`. Используйте области, которые гарантируют пару даже когда тело выбросит. Если вы вызываете методы события напрямую, используйте `try` и `finally`. - - Она измеряется от согласованного открывающего события, поэтому она отклоняется на `tool_result`, `hook_completed`, `agent_resume` и `human_input`. Она принимается на `model_response`, потому что только вы знаете реальную задержку провайдера, и она должна быть целое число. + + Это измеряется от соответствующего открывающего события, поэтому отклоняется на `tool_result`, `hook_completed`, `agent_resume` и `human_input`. Принято на `model_response`, потому что только вы знаете реальную задержку провайдера, и это должно быть целое число. - - Поток никогда не наследовал контекст. Оберните вызываемое в `failproofai_sdk.propagate()`. См. [Потоки и async](#потоки-и-async). + + Поток никогда не наследовал контекст. Оберните callable в `failproofai_sdk.propagate()`. См. [Потоки и async](#threads-and-async). - - Дополнительные поля объединяются последними, поэтому одно с именем как реальное поле такое как `model` или `outcome` перезаписало бы его и изменило бы сохранённую колонку. Пространство имён своих; адаптеры используют префикс `fw_`. + + Дополнительные поля слияны последние, поэтому одно названное как реальное поле такое как `model` или `outcome` переписало бы его и изменило сохранённую колонку. Пространство имён ваши; адаптеры используют префикс `fw_`. - `agent_id` — низкокардинальный аспект и вы поставили id запуска в него. Используйте роль или имя узла и поставьте реальный id в поле полезной нагрузки. + `agent_id` — низко-кардинальный фасет и вы положили в него run id. Используйте role или имя узла и положите реальный id в поле payload. -## Далее +## Дальше - Пары, ids, жизненный цикл сессии и доставка. + Пары, id, жизненный цикл session и доставка. - - Следите причинности через сессию, которую вы только что захватили. + + Следите за причинностью через session которую вы только что захватили. LangGraph, CrewAI, LlamaIndex и Pydantic AI. diff --git a/docs/ru/start/quickstart.mdx b/docs/ru/start/quickstart.mdx index bea20028..a46fecd8 100644 --- a/docs/ru/start/quickstart.mdx +++ b/docs/ru/start/quickstart.mdx @@ -1,12 +1,12 @@ --- title: "Быстрый старт" -description: "Захватите сеанс агента, найдите сбой и начните его предотвращать." +description: "Захватите сессию агента, найдите сбой и начните его предотвращение." icon: "zap" --- -Этот быстрый старт позволяет одной машине отправлять сеансы, запустить аудит и развернуть политику. Используйте навык для настройки Failproof AI или следуйте ручным шагам. +Этот быстрый старт подготавливает одну машину для отправки сессий, запускает аудит и развертывает политику. Используйте навык для настройки Failproof AI, либо выполните шаги вручную. -**Какой путь для вас?** Если ваш агент работает в одном из 12 поддерживаемых [сред](/ru/reference/harnesses) — кодирующем CLI или шлюзе вроде Hermes или OpenClaw — следуйте шагам ниже; вам нужна Node.js версии 20.9 или выше. Если ваш агент не имеет среды, инструментируйте его [Python SDK](/ru/reference/custom-agents) для трассировки и аудитов, затем вернитесь к пункту [Запустите первую проверку на сбои](/ru/start/first-audit); принудительное применение на этом пути требует хука в вашей среде выполнения. +**Какой путь вам подходит?** Если ваш агент работает в одном из 12 поддерживаемых [harnesses](/ru/reference/harnesses) — кодирующем CLI или gateway типа Hermes или OpenClaw — следуйте шагам ниже; вам нужен Node.js 20.9 или позже. Если у вашего агента нет harness, инструментируйте его с помощью [Python SDK](/ru/reference/custom-agents) для трассировки и аудитов, затем вернитесь к [Запуск первой проверки сбоев](/ru/start/first-audit); принудительное применение на этом пути требует hook в вашем runtime. @@ -16,24 +16,24 @@ icon: "zap" npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Ваш агент проверяет проект, выбирает релевантную интеграцию, выполняет настройку и проверяет её. См. [репозиторий навыков FailproofAI](https://github.com/FailproofAI/skills) для отдельных навыков и продвинутых опций установки. + Ваш агент проверяет проект, выбирает релевантную интеграцию, выполняет настройку и проверяет её. См. [репозиторий навыков FailproofAI](https://github.com/FailproofAI/skills) для отдельных навыков и расширенных опций установки. ## Перед началом -1. Откройте [панель управления Failproof AI](https://app.befailproof.ai) и создайте аккаунт или войдите с рабочей почтой. -2. Перейдите в **Administration → Keys** и создайте ключ с разрешениями `events:add` и `policies:pull`. -3. Скопируйте одноразовый секрет и сохраните его на целевой машине: +1. Откройте [панель управления Failproof AI](https://app.befailproof.ai) и создайте учетную запись или войдите с помощью рабочей электронной почты. +2. Перейдите в **Administration → Keys** и создайте ключ с правами `events:add` и `policies:pull`. +3. Скопируйте одноразовый секрет, затем прочитайте его в shell целевой машины. `read -s` принимает его в приглашении, которое не отображается, поэтому он никогда не появится в команде: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## Установка @@ -42,12 +42,18 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - Транскрипты сеансов отправляются по умолчанию. Добавьте `--no-transcripts` для отправки активности хука и решений политик без содержимого транскрипта. + Одна команда — это вся настройка: она устанавливает локальный daemon (root один раз), встраивает hooks во все найденные CLI агентов и подключает эту машину к Cloud. Передача ключа через переменную окружения вместо `--token` исключает его из `ps`, где все пользователи машины могут прочитать аргументы команды. Это не исключает его из истории shell — для этого служит чтение с `read -s`. В CI внедрите его как замаскированный секрет и отключите трассировку shell (`set -x`), иначе трассировка его выведет. - Если на этой машине уже есть история агента, просмотрите и импортируйте последние семь дней, затем ждите завершения доставки. Пропустите этот шаг на новой машине. + Транскрипты сессий отправляются по умолчанию. Добавьте `--no-transcripts` для отправки информации о hook-активности и решениях политик без содержимого транскриптов. + + + Не используйте `failproofai config --connect ` здесь. Этот флаг регистрирует машину, которая **уже** настроена, и сразу возвращается — без daemon, без hooks — так что машина будет видна в Cloud, но не будет ничего собирать и применять. + + + Если на этой машине уже есть история агента, предпросмотрите и импортируйте последние семь дней, затем дождитесь завершения доставки. Пропустите этот шаг на новой машине. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +61,41 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Откройте **Sessions** в Failproof AI и выберите импортированный сеанс. + Откройте **Sessions** в Failproof AI и выберите импортированную сессию. - - Это подключает Failproof AI к вашей среде и устанавливает 39 встроенных политик. Используйте их для просмотра локальных решений политик и опробования принудительного применения перед тем, как Failproof AI аудирует ваши сеансы и пишет политики для ваших агентов. + + Предыдущий шаг уже встроил все обнаруженные CLI агентов. Повторите его для одного harness явно, когда это необходимо, или чтобы добавить harness установленный позже. Каждый из 12 — это действительное значение `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + ```bash + failproofai policies --install --cli claude --scope user # coding CLI + failproofai policies --install --cli hermes --scope user # Slack/Telegram gateway + ``` - Позвольте установщику автоматически определить вашу среду или укажите её явно. Каждая из 12 сред является допустимым значением `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Блокировка вызова инструмента перед его выполнением проверена на всех 12. Gates конца хода проверены на 8 — см. [capability enforcement](/ru/reference/harnesses#enforcement-capability) для матрицы по каждому harness. + + + Встраивание hooks не включает никакую политику. Настройка специально не выбирает ничего — это решение за вами — поэтому возьмите пакет: ```bash - failproofai policies --install --cli claude --scope user # a coding CLI - failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway + failproofai policies add FailproofAI/policies ``` - Блокировка вызова инструмента перед его выполнением проверяется на всех 12 средах. Проверки в конце хода проверяются на 8 — см. [возможности принудительного применения](/ru/reference/harnesses#enforcement-capability) для матрицы по средам. + Пакет загружается из своего GitHub релиза, проверяется контрольная сумма и закрепляется на точном теге, в который он разрешился. Он содержит 38 политик и включает 10, которые его манифест отмечает как безопасные для автоматического включения. Используйте их, чтобы увидеть локальные решения политики и попробовать применение перед тем, как Failproof AI аудирует ваши сессии и пишет политики для ваших агентов. + + Прочитайте любой пакет перед его использованием с `failproofai policies show /` и см. [пакеты политик](/ru/policies/packs) для использования только части одного. + + До запуска этой команды единственное, что применяется — это `block-failproofai-commands` — всегда включенная защита, которая предотвращает отключение Failproof AI агентом. `failproofai policies` список того, что включено. - - Следуйте [Запустите первую проверку на сбои](/ru/start/first-audit). Используйте конкретную цель, например «найти сеансы, где агент повторил неудачный инструмент без изменения своего подхода». + + Следуйте [Запуск первой проверки сбоев](/ru/start/first-audit). Используйте конкретную цель, такую как «найти сессии, где агент повторил неудачный инструмент без изменения своего подхода». - Следуйте [Предотвратите первый сбой с помощью политики](/ru/start/first-policy). Начните в режиме наблюдения, проверьте совпадения, затем примените проверенную версию. + Следуйте [Предотвратьте первый сбой с помощью политики](/ru/start/first-policy). Начните в режиме наблюдения, проверьте совпадения, затем примените проверенную версию. - Запустите `failproofai config --status`. Здоровая конфигурация выведет облачное соединение, состояние демона и информацию о том, приостановлено ли принудительное применение. + Запустите `failproofai config --status`. Здоровая установка сообщает о подключении к облаку, состоянии daemon и включен ли режим пауза применения. \ No newline at end of file diff --git a/docs/ru/start/setup.mdx b/docs/ru/start/setup.mdx index 17568fa3..c5d715a9 100644 --- a/docs/ru/start/setup.mdx +++ b/docs/ru/start/setup.mdx @@ -1,68 +1,89 @@ --- -title: "Выберите вашу установку" -description: "Выберите локальное обеспечение, Failproof AI Cloud или развертывание на предприятии." +title: "Выберите вашу конфигурацию" +description: "Выберите локальное управление, Failproof AI Cloud или корпоративное развертывание." icon: "waypoints" --- - - Установите хуки и политики на машине. Используйте этот вариант, когда вам нужны немедленные защиты без отправки данных сеанса в Cloud. + + Установите машину без облачного ключа и возьмите пакет политик. Используйте это, когда вам нужны немедленные защиты без отправки данных сеанса в облако. - Добавьте централизованные сеансы, аудиты, оценки в режиме реального времени, панели управления, оповещения и развертывание политик в парке машин. + Добавьте централизованные сеансы, аудиты, онлайн-оценки, панели управления, оповещения и развертывание политик для флота. - - Используйте элементы управления организацией, ограниченные ключи, частную инфраструктуру и требования безопасности для конкретного развертывания. + + Используйте управление организацией, ограниченные ключи, приватную инфраструктуру и требования безопасности, специфичные для развертывания. +## Управление на локальной машине + +Запустите `failproofai config` без ключа, затем возьмите пакет с помощью `failproofai policies add FailproofAI/policies`. В терминале выберите **Not now — stay local** когда установка предложит подключиться к облаку; без терминала и без `FAILPROOFAI_CLOUD_TOKEN` это автоматически остается локальным. Демон и хуки работают на машине, и никакие данные сеанса не отправляются в облако. Чтобы подключиться позже, выполните шаги ниже. + ## Рекомендуемый путь для production -1. Подключите машину вне production с включенной записью стенограмм. -2. Проверьте сеансы и оценки в Cloud. -3. Создайте аудит для известного сценария отказа. +1. Подключите непроизводственную машину с включенной записью транскриптов. +2. Проверьте сеансы и оценки в облаке. +3. Создайте аудит для известного режима сбоя. 4. Разверните первую политику в режиме наблюдения. 5. Расширьте на production после проверки совпадений и ложных срабатываний. -## Подключение машины к Cloud +## Подключите машину к облаку - 1. Перейдите в **Administration → Keys** и создайте ключ с правами `events:add` и `policies:pull`. + 1. Перейдите в **Administration → Keys** и создайте ключ с `events:add` и `policies:pull`. 2. Скопируйте одноразовый секрет на целевую машину. - 3. После запуска команды подключения CLI перейдите в **Admin → enforcement** и убедитесь, что машина появилась. - 4. Перейдите в **Observe → Events** и убедитесь, что его первое событие поступило. + 3. После запуска команды подключения CLI перейдите в **Admin → enforcement** и подтвердите, что машина появилась. + 4. Перейдите в **Observe → Events** и подтвердите, что ее первое событие поступило. - Ящик ключа отображает два разрешения, необходимые подключенной машине: прием событий и доставка политик. + Ящик ключей показывает два разрешения, необходимые подключенной машине: прием событий и доставка политик. - ![Ящик нового ключа API, используемый для предоставления разрешений на прием событий и доставку политик.](/images/dashboard/key-create.png) + ![Новое окно создания API ключа для предоставления разрешений на прием событий и доставку политик.](/images/dashboard/key-create.png) - После подключения машина должна появиться в enforcement с желаемым и сообщаемым состоянием политики. + После подключения машина должна появиться в управлении с желаемым и сообщаемым состоянием политики. - ![Парк Enforcement с развернутой машиной, показывающей желаемое состояние политики и статус развертывания.](/images/dashboard/enforcement-fleet.png) + ![Флот управления с зарегистрированной машиной, раскрытой для отображения желаемого состояния политики и статуса развертывания.](/images/dashboard/enforcement-fleet.png) - Первое поступившее событие подтверждает, что демон может доставлять данные в Cloud независимо от развертывания политик. + Первое поступившее событие подтверждает, что демон может доставлять данные в облако, независимо от развертывания политики. - ![Поток живых событий, показывающий недавние события агента, модели и инструмента.](/images/dashboard/events-stream-current.png) + ![Прямой поток событий, показывающий недавние события агента, модели и инструмента.](/images/dashboard/events-stream-current.png) - Продолжайте только после того, как видны и машина, и её первое событие. + Продолжайте только после того, как машина и ее первое событие будут видны. + Прочитайте одноразовый секрет в оболочку. `read -s` принимает его в приглашении, которое не выводит, поэтому он никогда не появляется в команде или истории оболочки: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Затем установите машину, выберите ее политики и назовите ее: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` - Добавьте `--no-transcripts` когда содержимое стенограмм должно оставаться локальным. + `failproofai config` выполняет полную установку — демон, хуки для каждого найденного CLI агента и облачное соединение — затем не выбирает никакие политики, что и делает вторая команда. + + Метка идет **после** подключения, не во время: `failproofai config --machine-label ` переименовывает машину, которая уже подключена, а на той, которая не подключена, не делает ничего, кроме как это скажет. + + Добавьте `--no-transcripts` когда содержание транскриптов должно оставаться локальным. + + В CI установите `FAILPROOFAI_CLOUD_TOKEN` из хранилища секретов вместо `read -s` и держите трассировку оболочки (`set -x`) выключенной, иначе трассировка выведет ключ. + + + На машине, которая **уже** установлена, `failproofai config --connect ` регистрирует ее и ничего больше. Не используйте эту форму для первой установки: она возвращается до того, как демон или какой-либо хук будет на месте, оставляя машину, которая появляется в облаке, но не собирает и не обеспечивает ничего. + -Подключение к Cloud проверяет прием событий и доставку политик независимо. Ключ может быть действительным, но не иметь одного требуемого разрешения. Используйте `failproofai config --status` чтобы увидеть, какая возможность настроена. +Подключение к облаку проверяет прием событий и доставку политик независимо. Ключ может быть действительным, но не хватает одного необходимого разрешения. Используйте `failproofai config --status` чтобы увидеть, какая возможность настроена. - Установка Cloud записывает локальные учетные данные только после успешной проверки соответствующей возможности. Неудачная проверка не оставляет машину выглядящей подключенной, когда она не подключена. + Установка облака записывает локальные учетные данные только после успешной проверки соответствующей возможности. Неудачная проверка не оставляет машину выглядящей подключенной, когда она на самом деле не подключена. \ No newline at end of file diff --git a/docs/tr/admin/keys-and-permissions.mdx b/docs/tr/admin/keys-and-permissions.mdx index 08d6f7da..855cf61c 100644 --- a/docs/tr/admin/keys-and-permissions.mdx +++ b/docs/tr/admin/keys-and-permissions.mdx @@ -1,29 +1,29 @@ --- -title: "Anahtarlar ve izinler" +title: "Anahtarlar ve İzinler" description: "Makineler, otomasyon ve operatörler için kapsamlı API anahtarları oluşturun." icon: "key-round" --- -API anahtarları bir kuruluşa aittir ve açık izinler taşır. Ajan alımı, politika teslimi, değerlendiriciler, CI otomasyonu ve yönetim betikleri için ayrı anahtarlar kullanın. +API anahtarları bir organizasyona aittir ve açık izinleri taşır. Ajan alımı, politika teslimi, değerlendiriciler, CI otomasyonu ve yönetim betikleri için ayrı anahtarlar kullanın. -## Anahtar oluşturma ve rotasyonu +## Anahtar Oluşturma ve Döndürme - 1. **Administration → Keys** bölümüne gidin, **new key** seçeneğini seçin ve iş yükü adını girin. - 2. Bir izin kümesi seçin ve önceden ayarlanmış izin yeterli olmadığında yalnızca bireysel izinleri ayarlayın. + 1. **Yönetim → Anahtarlar** sayfasına gidin, **yeni anahtar** seçin ve bir iş yükü adı girin. + 2. Bir izin seti seçin ve hazır ayarlar yetersiz kaldığında yalnızca bireysel izinleri ayarlayın. 3. Anahtarı oluşturun ve tek seferlik sırrını hemen kopyalayın. - 4. Anahtarı daha sonra açarak izinleri güncelleyin, devre dışı bırakın veya sırrı yeniden oluşturun. + 4. Anahtarı daha sonra açarak yetkilendirmeleri güncelleyin, devre dışı bırakın veya sırrı yeniden oluşturun. - Oluşturma bölmesi, iş yükü tarafından gereken en dar izinleri seçtiğiniz yerdir. + Oluşturma paneli, iş yükü tarafından gereken en dar yetkilendirmeleri seçtiğiniz yerdir. - ![Yeni API anahtar bölmesi izin ön ayarları ve bireysel izinlerle.](/images/dashboard/key-create.png) + ![İzin ön ayarları ve bireysel yetkilendirmeler gösteren yeni API anahtarı paneli.](/images/dashboard/key-create.png) - Oluşturulduktan sonra, Keys sayfası kalıcı metadata ve yönetim eylemlerini gösterir. Tek seferlik sır bir daha gösterilmez. + Oluşturulduktan sonra, Anahtarlar sayfası kalıcı meta verileri ve yönetim işlemlerini gösterir. Tek seferlik sır bir daha gösterilmez. - ![API Keys sayfası anahtar izinlerini, oluşturulma zamanını ve yeniden oluştur ile devre dışı bırak eylemlerini göstermektedir.](/images/dashboard/api-keys.png) + ![Anahtar izinlerini, oluşturulma zamanını ve yeniden oluştur ile devre dışı bırak işlemlerini gösteren API Anahtarları sayfası.](/images/dashboard/api-keys.png) - Bu listeyi kullanarak izinleri düzenli olarak gözden geçirin ve artık etkin iş yüküne karşılık gelmeyen anahtarları devre dışı bırakın. + Bu listeyi kullanarak izinleri düzenli olarak gözden geçirin ve artık etkin bir iş yüküne eşlenmeyen anahtarları devre dışı bırakın. ```bash @@ -36,39 +36,39 @@ API anahtarları bir kuruluşa aittir ve açık izinler taşır. Ajan alımı, p fp keys disable production-agents ``` - Oluşturma/yeniden oluşturma çıktısını güvenli bir şekilde yönlendirin veya yakalayın; sır bir kez döndürülür. + Oluşturma/yeniden oluşturma çıktısını güvenli bir şekilde yönlendirin veya yakalayin; sır bir kez döndürülür. -Bağlı bir Failproof AI makinesi tarafından gereken iki izin bağımsızdır: +Bağlantılı bir Failproof AI makinesinin gerektirdiği iki izin bağımsızdır: -- `events:add` olayları ve oturum verilerini gönderir. -- `policies:pull` atanmış politika dağıtımlarını alır. +- `events:add` etkinlikleri ve oturum verilerini gönderir. +- `policies:pull` atanan politika dağıtımlarını alır. Anahtar sırları oluşturulduğunda veya yeniden oluşturulduğunda gösterilir. Bunları bir sır yöneticisinde depolayın ve bir operatörün etkileşimli kimlik bilgilerini yeniden kullanmadan döndürün. -## İzin kataloğu +## İzin Kataloğu | Alan | İzinler | | --- | --- | -| Events | `events:add`, `events:read` | -| Keys | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` yalnızca insan oturumunda | -| Users | `users:create`, `users:read`, `users:update`, `users:delete` | -| Evaluations | `evaluations:read`, `evaluations:trigger` | -| Dashboards | `dashboards:read`, `dashboards:write`, `dashboards:delete` | -| Queries | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | -| Assistant | `agent:use` | -| Settings | `settings:read`, `settings:write` | -| Alerts | `alerts:read`, `alerts:write` | -| Issues | `issues:read`, `issues:create`, `issues:close` | -| Audits | `audits:read`, `audits:write` | -| Policies | `policies:read`, `policies:write`, `policies:pull` | -| Usage | `usage:read` | - -`orgs:admin` örnek operatörü için ayrılmıştır ve bir kuruluş anahtarına veya sıradan bir üyeye verilemez. Eski `incidents:*` ve `alerts:ack` belirteçleri uyumluluk için kabul edilir ve mevcut `issues:*` izinlerine normalleştirilir. - -Yerleşik izin kümeleri `read-only`, `standard` ve `admin` şeklindedir. `standard` değerlendirme tetikleme, sorgu yürütme, sorun yanıtı ve asistan kullanımını okuma izinlerine ekler. Anahtar oluşturması bir izin kümesi içermese bile yalnızca insan izinlerini kaldırır. +| Etkinlikler | `events:add`, `events:read` | +| Anahtarlar | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` yalnızca insan oturumunda | +| Kullanıcılar | `users:create`, `users:read`, `users:update`, `users:delete` | +| Değerlendirmeler | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | +| Panolar | `dashboards:read`, `dashboards:write`, `dashboards:delete` | +| Sorgular | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | +| Asistan | `agent:use` | +| Ayarlar | `settings:read`, `settings:write` | +| Uyarılar | `alerts:read`, `alerts:write` | +| Sorunlar | `issues:read`, `issues:create`, `issues:close` | +| Denetimler | `audits:read`, `audits:write` | +| Politikalar | `policies:read`, `policies:write`, `policies:pull` | +| Kullanım | `usage:read` | + +`orgs:admin` örnek operatörü için ayrılmıştır ve bir organizasyon anahtarına veya sıradan üyeye verilemez. Emekli `incidents:*` ve `alerts:ack` belirteçleri uyumluluk için kabul edilir ve geçerli `issues:*` izinlerine normalleştirilir. + +Yerleşik izin setleri `read-only`, `standard` ve `admin` şeklindedir. `standard`, okuma izinlerine değerlendirme tetikleme, sorgu yürütme, sorun yanıtı ve asistan kullanımını ekler. Anahtar oluşturma, bir izin seti içerdiğinde bile insan için ayrılmış yetkileri kaldırır. - Örnek kapsamlı anahtarlar `X-AgentEye-Org` başlığı ile bir kuruluş seçebilir. Çok kuruluşlu dağıtımlarda açıkça ayarlayın; atlanması varsayılan kuruluşu seçebilir. + Örnek kapsamındaki anahtarlar `X-AgentEye-Org` başlığı ile bir organizasyon seçebilir. Çok organizasyonlu dağıtımlarda açıkça ayarlayın; atlama varsayılan organizasyonu seçebilir. \ No newline at end of file diff --git a/docs/tr/evaluations/deploy.mdx b/docs/tr/evaluations/deploy.mdx new file mode 100644 index 00000000..23dc4433 --- /dev/null +++ b/docs/tr/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "Bir değerlendirmeyi dağıtın ve sürümleyin" +description: "Değişmez bir sürüm dağıtın, canlı olanı görün, yeni sürümler yayınlayın, geri alın ve zaten sahip olduğunuz oturumları puanlayın." +icon: "cloud-upload" +--- + +## Dağıtın + +Yazma sayfasının altında **deploy `@`** seçeneğini seçin. Sürüm yayınlandıktan sonra değişmezdir: o andan itibaren, koşulu uygulanan her biten oturum tarafından puanlanır. + +## Canlı olanı görün + +**Analyze → eval authoring** kuruluşunuzun barındırılan tanımlarını, yönetilen değerlendirici tarafından çalıştırılan değerlendirmeleri listeler. Her satır şunları gösterir: + +- adı, anahtarı, sürümü ve sonuç türü +- dağıtılan revizyonları ayırt etmek için kodu açmadan söyleyen kaynak sağlama toplamı +- **koşullu** olup olmadığı veya **tüm tamamlanan oturumlar** üzerinde çalışıp çalışmadığı — koşul, bir değerlendirmeyi belirli ajanlar veya ortamlara kapsamlandıran şeydir +- zaman aşımı, etiketleri ve son ne zaman değiştiği + +![Barındırılan tanımlar listesi: her değerlendirmenin adı, anahtarı, sürümü, sonuç türü, sağlama toplamı, zaman aşımı ve kapsamı, yeni sürüm ve etkinleştir veya devre dışı bırak seçenekleri ile.](/images/dashboard/eval-definitions.png) + +Listeyi arayın veya duruma göre filtreleyin. Kendi çalışanınızın kaydettiği değerlendirmeler burada listelenmez; bunların sonuçları [değerlendirmeler sayfasında](/tr/sessions/evaluations) **customer** etiketi taşır ve barındırılanlar **managed** etiketini taşır. + +Bir kuruluş aynı anda en fazla 100 farklı barındırılan değerlendirmeyi etkinleştirebilir. + +## Yeni sürüm yayınlayın + +Bir satırda **new version** seçeneğini seçin. Yazma sayfası o sürümün koduyla açılır; değiştirin, test edin ve dağıtın. Anahtarı ve sonuç türü aktarılır ve değişemez. + +Bir halefin yayınlanması, öncülünü devre dışı bırakır ve listeye alır. Sonuçlar bunları üreten sürümü korur, bu nedenle bir grafik tam olarak yeni mantığın ne zaman devralındığını gösterir. + +## Geri alın + +Geçerli sürümde **disable** seçeneğini ve istediğiniz sürümde **enable** seçeneğini belirleyin. Hiçbir şey silinmez ve her sonuç olduğu gibi kalır. + +## Bir değerlendirmeyi durdurun + +**Disable** seçeneğini belirleyin. Etkinleştirilen sürüm olmadan, yeni oturumlar üzerinde çalışmayı durdurur. Kendi çalışanınızın çalıştırdığı bir değerlendirmeyi durdurmak için, bunu kaydetmeyi durdurun: çalışanından kaldırın veya çalışanı durdurun. + +## Zaten sahip olduğunuz oturumları puanlayın + +Değerlendirme ileri gider: şimdi dağıtılan bir sürüm, bundan önce biten bir oturumu asla puanlamaz. Geçmişi puanlamak için, eval yazma sayfasında **score sessions you already have** seçeneğini açın, 90 güne kadar bir zaman penceresi ve isteğe bağlı olarak tek bir değerlendirme seçin ve çalıştırmadan önce sayın. Sayı tam olarak çalıştırılacak şeydir ve içindeki her oturum-ve-değerlendirme çifti bir faturalandırılabilir değerlendirmedir. + +Yalnızca boşlukları doldurur. O değerlendirme için zaten bir sonucu olan bir oturum bunu korur ve aynı pencereyi iki kez çalıştırmak hiçbir yeni şey puanlamaz. + +Bir oturumu tekrar puanlamak için — bir düzeltmeden sonra veya temiz bir şekilde bitmemiş bir oturum için — onun sayfasında **re-evaluate** seçeneğini belirleyin. Yeni sonuç, oturumun geçmişine eklenir; önceki olanlar kalır. + +## İzinler + +| İzin | Size izin verir | +| --- | --- | +| `evaluations:read` | Sonuçları görün ve eval yazma sayfasını açın | +| `evaluations:trigger` | Barındırılan tanımları görmek, dağıtmak, sürümlemek, etkinleştirmek ve devre dışı bırakmak; test etmek; geçmişi puanlamak; bir oturumu yeniden değerlendirmek | +| `events:read` | `evaluations:trigger` üstüne gerçek oturumlar karşısında test etmek ve taslakları yük anahtarlarınıza dayandırmak | +| `evaluations:run` | Kendi değerlendirici çalışanınızı çalıştırmak | \ No newline at end of file diff --git a/docs/tr/evaluations/overview.mdx b/docs/tr/evaluations/overview.mdx new file mode 100644 index 00000000..4f09431b --- /dev/null +++ b/docs/tr/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "Ajanları değerlendir" +description: "Tanımladığınız değerlendirmelerle her tamamlanan oturumu puanlandırın: barındırılan Python kontrolleri veya kendi worker'ınızdaki LLM yargıçlar." +icon: "gauge" +--- + +Bir değerlendirme, tamamlanan bir ajan oturumunu puanlandırır. Bir oturum bittiğinde, ona uygulanan her etkinleştirilmiş değerlendirme çalışır ve bulduklarını kaydeder; izi yanında okuyabileceğiniz açıklamalarıyla birlikte: + +- 0 ile 1 arasında bir **puan**, isteğe bağlı olarak geçti veya başarısız olarak işaretlenmiş +- bir **metrik**, örneğin bir sayı, bir süre veya bir maliyet, birimiyle birlikte +- bir **assertion**, geçti veya geçmedi + +## İki tür değerlendirici + +| | Barındırılan Python | Kendi worker'ınız | +| --- | --- | --- | +| Yazıldığı yer | Panoda, **Analiz → eval authoring** altında | Python'da, [Evaluator SDK](/tr/reference/evaluator-sdk) ile | +| Çalıştırıldığı yer | Failproof AI'ın yönetilen değerlendiriicisinde, bir sandbox'ta | Kendi altyapınızda | +| En iyi kullanıldığı | Deterministik, kod tabanlı kontroller | LLM yargıçlar, model çağrıları, paketler, sırlar, ağ erişimi, yoğun işleme | + +Barındırılan Python kasıtlı olarak küçüktür: bir ifade, içe aktarım yok, ağ yok. Bir modele ihtiyaç duyan herhangi bir şey — bir LLM yargıcının bir cevabın uygun olup olmadığını puanlandırması, örneğin — bunun yerine kendi worker'ınızda çalışır. Her iki tür de gelen bir bağlantıya ihtiyaç duymaz: worker'lar tamamlanan oturumları talep eder ve sonuçları giden HTTPS üzerinden gönderir. + +## Her organizasyon kendi ajanlarını değerlendirir + +Değerlendirmeler onları tanımlayan organizasyona aittir. Bir instance'taki her organizasyon kendi değerlendirmesini yazar — kendi kontrolleri, koşulları, eşikleri ve etiketleri — sürümleri oluşturur ve diğerini etkilemeden dağıtır ve yalnızca kendi sonuçlarını görür. Bu sonuçları ajan, ortam, değerlendirme ve zamana göre filtreleyebilir veya asistana onlar hakkında sorabilirsiniz. + +## İlk taslaktan canlı puanlara + + + + Neyi ölçeceğinizi açıklayın ve asistanın bunu hazırlamasını sağlayın veya kendiniz yazın. Bkz. [Bir değerlendirme yazın](/tr/evaluations/write). + + + Canlı gitmeden önce bunu gerçek oturumlar karşısında çalıştırın; hiçbir şey depolanmaz. Bkz. [Bir değerlendirmeyi test edin](/tr/evaluations/test). + + + Değişmez bir sürüm dağıtın, evrim geçirdiğinde yeni olanlar yayınlayın ve önceki birine geri dönün. Bkz. [Dağıtım ve sürüm oluşturma](/tr/evaluations/deploy). + + + Puanları zaman içinde grafiklendirin, ajanları ve ortamları karşılaştırın ve asistana sorun. Bkz. [Değerlendirme sonuçlarını okuyun](/tr/sessions/evaluations). + + + +Değerlendirme ileriye doğru çalışır: şimdi dağıtılan bir sürüm, şimdi itibaren biten oturumları puanlandırır. Zaten sahip olduğunuz oturumları puanlandırmak için, [onları geri doldurun](/tr/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file diff --git a/docs/tr/evaluations/test.mdx b/docs/tr/evaluations/test.mdx new file mode 100644 index 00000000..e441549b --- /dev/null +++ b/docs/tr/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "Bir değerlendirmeyi test etme" +description: "Dağıtmadan önce değerlendirmeyi gerçek oturumlarınıza karşı çalıştırın. Hiçbir şey depolanmaz." +icon: "flask-conical" +--- + +**bu değerlendirmeyi test et**, yazma sayfasında, kodu değerlendirici filoya karşı gerçek oturumlarınızda dağıtmadan çalıştırır. Hiçbir şey depolanmaz: burada bir hata, bir ön izlemedir ve dağıtım her zaman yapılabilir. + + + + Kodu derlemek ve koşulu sandbox kurallarına karşı kontrol etmek için **check** seçeneğini seçin, herhangi bir oturumda çalıştırmadan. + + + Eşleşen oturumları aracıya, ortama, zamana veya oturum kimliğine göre daraltın ve en fazla 10 tanesini işaretleyin. Değerlendirmenin başarısız olması gereken oturumların yanı sıra başarılı olması gereken oturumları da dahil edin. + + + **N oturuma karşı çalıştır** seçeneğini seçin ve her satırı okuyun. + + + +| Satır | Ne anlama gelmektedir | +| --- | --- | +| **ok** | Çalıştı. Satır, döndürdüğü tüm puanları, metrikleri, onaylamaları ve ne kadar sürdüğünü listeler. | +| **skipped** | Koşul `False` döndürdü, bu nedenle değerlendirme çalışmadı. Bu bir hata değil, bir atlamadır. | +| Failed | Bir hata oluştu, zaman aşımı oluştu veya sandbox'un reddettiği bir şey kullandı. Satır hangisinin olduğunu söyler ve **Fix it** hata yardımcı olabildiğinde onu asistana verir. | + +![Bu değerlendirmeyi test et paneli: aracıya göre seçilen üç oturum, ikisi ok ve biri koşul False döndürdüğü için atlandı.](/images/dashboard/eval-test.png) + +Bir sonuç, kodu düzenledikten sonra güncel olmaktan çıkar; yeniden kullanılmak yerine soluklaştırılır. \ No newline at end of file diff --git a/docs/tr/evaluations/write.mdx b/docs/tr/evaluations/write.mdx new file mode 100644 index 00000000..c20e64e3 --- /dev/null +++ b/docs/tr/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "Bir değerlendirme yazın" +description: "Neyi ölçeceğinizi açıklayın ve asistanın barındırılan bir Python değerlendirmesini taslak hale getirmesini sağlayın veya kodu kendiniz yazın. LLM hakimleri kendi worker'ınızda çalışır." +icon: "file-pen-line" +--- + +Barındırılan değerlendirmeler, panoda yazılan ve Failproof AI'nin değerlendirici filosunda çalıştırılan küçük, belirleyici Python kodlarıdır. Daha ağır mantık — bir LLM hakim, bir paket, bir gizli anahtar, bir ağ çağrısı — bunun yerine [kendi worker'ınızda](#write-it-in-your-own-worker) çalışır. + +## Bir açıklamadan taslak oluşturun + +1. **Analyze → eval authoring** öğesine gidin ve **new eval** öğesini seçin. +2. Ölçülecek şeyi düz İngilizce'de açıklayın veya **start from an example…** öğesinden seçim yapın ve **draft** öğesini seçin. +3. Alanları ve doldurduğu kodu gözden geçirin, ardından [test edin](/tr/evaluations/test) ve [dağıtın](/tr/evaluations/deploy). + +![Taslak bir değerlendirme içeren eval authoring sayfası: açıklama, taslaağa ilişkin asistanın notları ve ad, anahtar, sürüm, sonuç, zaman aşımı, etiketler ve koşul alanları.](/images/dashboard/eval-authoring-draft.png) + +Taslak, kuruluşunuzun kendi etkinliklerine dayanır: sayfa, oturumlarınızın son yedi gün içinde hangi yük anahtarlarını taşıdığını okur, böylece kod tahmin etmek yerine var olan anahtarları okur. Taslağı teslim etmeden önce, asistan onu son oturumlarınızdan beşe kadarına karşı test eder, kanıtlayabileceği herhangi bir şeyi onarır — üç tura kadar — ve kodu istediğiniz şeyi ölçüp ölçmediğini bir kez daha kontrol eder. Açıklamayı spesifik tutun: geniş istekler daha yavaş olabilir ve zaman aşımına uğrayabilir. Her halükarda kodu gözden geçirin; dağıtım asla engellenmez. + +## Alanları ayarlayın + +| Alan | Nedir | +| --- | --- | +| name | İnsanların gördüğü şey. Daha sonra düzenlenebilir | +| key | Sonuçlarını grafiklere çizen kararlı tanımlayıcı, örneğin `code_assistant_quality_gate` | +| version | Boşluk olmayan herhangi bir sürüm dizesi, örneğin `1.0.0` | +| result | **score** (0 ile 1 arasında), **metric** (bir birime sahip sayı) veya **assertion** (geçti ya da geçmedi) | +| timeout seconds | Varsayılan 30. Sandbox herhangi bir çalışmayı 60'ta durdurur | +| labels | En fazla 20, virgülle ayrılmış. Daha sonra düzenlenebilir | +| condition | İsteğe bağlı. Bir Python ifadesi; değerlendirme yalnızca `True` olduğu oturumlarla çalışır | + +Bir değerlendirmeyi bunu amaçlayan aracılara ve ortamlara kapsamı belirlemek için koşulu kullanın: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +Anahtar, sürüm, sonuç türü, koşul ve kod dağıtıldıktan sonra değişmezdir: bunlardan herhangi birini değiştirmek için yeni bir sürüm yayınlayın. Ad, etiketler ve etkinleştirilip etkinleştirilmediği düzenlenebilir kalır. + +## Kodu kendiniz yazın + +**Evaluator kodu**, `EvalResult(...)` döndüren tek bir Python ifadesidir ve `session` kapsamındadır. Bu, araç sonuçlarının iyi olma oranını puanlar: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +Bir sonuç değerlendirmenin kendi anahtarı ile başlar, deklaresi edilen türünde: bir skor değerlendirmesi için `score=` veya bir metrik veya assertion değerlendirmesi için anahtarla adlandırılan `metrics` veya `assertions` girişi. Diğer metrikler ve iddialar bununla birlikte gider, bir çalışmada 25'e kadar sonuç. + +| Kapsamında | Sağlar | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count` ve `events`, artı `count(event_type)` ve `events_of_type(event_type)` | +| Her olay | `id`, `ts`, `event_type` ve `payload` | +| Sonuç türleri | `EvalResult`, `Score`, `Metric`, `Assertion` ve bir koşul için `ConditionResult` | +| Builtins | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +Başka hiçbir şeye ulaşılamaz: içe aktarma yok ve oturum verileri ve `get`, `lower` ve `split` gibi düz dize ve sözlük yöntemleri dışında hiçbir öznitelik yoktur ve bunlar başvurulan değil, çağrılan şeylerse. Yük anahtarları aracılarınızın gönderdiği şeydir — yukarıdaki `status` yalnızca bir örnektir — bunları gerçek bir oturumdan okuyun. **format** kodu temizler ve **fix** asistandan bunu onarmalarını ister. Kod 128 KiB'e kadar olabilir ve koşul 16 KiB'e kadar olabilir. + +![Evaluator kod editörü, biçim ve onarım ile birlikte, taslak bir değerlendirmenin iddialarını gösterir.](/images/dashboard/eval-authoring-code.png) + +## Bunu kendi worker'ınızda yazın + +Bir değerlendirme bir modele, bir pakete, bir gizli anahtara veya ağa ihtiyaç duyduğunda, onu [Evaluator SDK](/tr/reference/evaluator-sdk) ile yazın ve kendi altyapınızda çalıştırın. Aynı sonuç türlerini kullanır ve sonuçları barındırılan olanların yanında görünür, **customer** olarak etiketlenir: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/tr/policies/deploy.mdx b/docs/tr/policies/deploy.mdx index 568f67d9..97d8d276 100644 --- a/docs/tr/policies/deploy.mdx +++ b/docs/tr/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "İlkeleri dağıtma" -description: "İncelenen bir ilke sürümünü hedeflenen makinelere kullanıma sunma." +title: "Bir politikayı dağıtın" +description: "Test edilmiş bir politika sürümünü makinelere gözlem modunda yerleştirin, uygulayın ve her makinenin bunu aldığını doğrulayın." icon: "cloud-upload" --- -Bir dağıtım, bir veya daha fazla ilke sürümünü kaydedilmiş bir makine kümesine bağlar. +Bir dağıtım, yayınlanan politika sürümlerini bir makineye yerleştirir; her biri iki etkiden birine sahiptir: -## Bir dağıtımı uygulama +- **Observe** politikanın ne yapacağını kaydeder ve hiçbir şeyi engellemiyor. +- **Enforce** karara göre hareket eder: bir `deny` çağrıyı engeller ve bir `instruct` aracıyı yönlendirir. + +## Makine ekleyin + +Cloud'a bağlandıktan sonra bir makine **Admin → enforcement** altında görünür. İstediğiniz makine henüz orada değilse: + + + + 1. **Administration → Keys** sayfasına gidin ve makinenin dağıtımları alabilmesi için `policies:pull` ve kararlarının Cloud'a ulaşabilmesi için `events:add` yetkisine sahip bir anahtar oluşturun. + 2. Makineyi bu anahtarla bağlayın — [Connect a machine to Cloud](/tr/start/setup#connect-a-machine-to-cloud) bunu adım adım göstermektedir. + 3. **Admin → enforcement** altında göründüğünü doğrulayın. + + + Makinede: + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + Bir terminalde `failproofai config` Cloud'a bağlanıp bağlanmayacağını sorar ve anahtarı gizli bir istemi de alır. Ardından makinenin kaydedildiğini `fp fleet list` komutuyla her yerden doğrulayın. + + + +## Gözlem modunda dağıtın 1. **Admin → enforcement** sayfasına gidin, makineyi bulun ve satırını genişletin. - 2. **edit** seçeneğini seçin, incelenen ilke sürümünü ekleyin ve **observe** ya da zorlama efektini seçin. - 3. Değişikliği uygulayın, makinenin sonraki kontrolünü bekleyin ve dağıtım ile kapsam durumunu doğrulayın. + 2. **edit** seçeneğini seçin, test edilmiş politika sürümünü ekleyin ve **observe** seçeneğini seçin. + 3. Değişikliği uygulayın, ardından makinenin sonraki check-in'ini bekleyin ve dağıtım ile kapsam durumunu doğrulayın. 4. Canlı kararları incelemek için **Observe → policy** sayfasına gidin. - ![İlke sürümleri, zorlama ve gözlem efektlerini gösteren ve dağıtımı uygulama eyleminin yer aldığı makine dağıtım editörü.](/images/dashboard/enforcement-editor.png) + ![Politika sürümleri, enforce ve observe efektleri ve dağıtımı uygula eylemini gösteren makine dağıtım editörü.](/images/dashboard/enforcement-editor.png) - CLI'dan `fp fleet` komutuyla dağıtım yapın. Uygulamadan önce sonuç kümesini gözden geçirin — `deploy` komutu tam planı yazdırır ve **yalnızca `--json` olmayan etkileşimli bir terminalinde** sorar. `--json` altında, `--yes` ile veya stdin yönlendirildiğinde (CI adımı, betik, aracı kabuk komutu) hiç plan ve istem olmaksızın hemen uygulanır — gözden geçirmek istiyorsanız önce `fp fleet show ` komutunu çalıştırın: - ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` komut amacını ve teslimi gösterir (makine sonraki yoklamaya kadar `behind` olarak okunur), `fp fleet history ` kuşakları listeler ve `fp fleet rollback ` birini yeniden kurar — devre dışı bırakılmış veya silinmiş bir ilke adlandıran kuşak varsa reddeder. + `:observe` eki bunu gözlem moduna getirir: bare `--add no-force-push` makinenin o politika için zaten sahip olduğu efekti tutar ve aksi takdirde enforce eder. Bunu daha sonra `--add no-force-push:enforce` komutuyla enforce'a geçirin. + + `deploy` **makinenin tüm politika setini** sonuçla değiştirir. Planı yazdırır, ardından uygulamadan önce sorar — ancak yalnızca etkileşimli bir terminalde. `--yes` ile, `fp --json` altında veya stdin yönlendirilmiş olduğunda (CI adımı, betik, aracı shell dışarı atarken) onay istemeden uygular; plan yine de yazdırılır veya `--json` altında `plan` olarak döndürülür. - Makine üzerinde `failproofai config --status` komutuyla kontrol edin ve dağıtım sonrasında etkinliğin Cloud'a ulaşıp ulaşmadığını doğrulamak için `fp sessions --env production --since 24h` ve `fp events --event-type hook_completed` komutlarını kullanın. + Makinede, `failproofai policies` çalıştırdığı Cloud tarafından yönetilen politikaları listeler ve `failproofai config --status` bağlantısını gösterir. Etkinliğinin Cloud'a ulaştığını doğrulamak için `fp sessions --env production --since 24h` ve `fp events --event-type hook_completed` komutlarını kullanın. - - Değişebilir bir taslak değil, incelenen bir sürümü dağıtın; oturumlarını inceleyebileceğiniz üretim dışı bir makine veya küçük bir kohortla başlayın. + + Yayınlanan sürümü ve üzerinde çalışması gereken makineleri seçin. - - Çalışmayı engellemeden eşleşmeleri, nedenleri, etkilenen araçları ve yanlış pozitifleri gözden geçirin. + + Hiçbir şey engellenmediği sürece eşleşmeleri, nedenleri, etkilenen araçları ve yanlış pozitifleri gözden geçirin. - - Gözlemlenen eşleşmeler güvensiz eylemleri geçerli olanlardan ayırdıktan sonra yükseltin, ardından hedeflenen tüm makinelerin dağıtımı çekmiş olduğunu ve kararları rapor ettiğini doğrulayın. + + Gözlemlenen eşleşmeler güvensiz eylemleri geçerli olanlardan ayırdığında efekti enforce'a geçirin, ardından her amaçlanan makinenin değişikliği aldığını ve kararları raporladığını doğrulayın. -Makinelerin `policies:pull` yeteneğine ihtiyacı vardır. Olay raporlaması `events:add` tarafından ayrı olarak kontrol edilir; Cloud analizi ve zorlama beklediğinizde her ikisini de doğrulayın. +## Kapsamı kontrol edin + +Kapsam, bir politikanın riskin olduğu yerde çalışıp çalışmadığını yanıtlar. + +1. **Admin → enforcement** sayfasına gidin ve enforce ve gözlem toplamlarını gözden geçirin. +2. Makineleri ID veya etikete göre arayın veya bir politikadan eksik olan makineleri filtreleyin. +3. Atanan politikaları, bildirilen dağıtımı, son check-in'i ve geçmişi karşılaştırmak için bir satırı genişletin. +4. Uygulanan bir dağıtım henüz beklemede olduğunda makinenin yoklama aralığından sonra yenileyin. + +![Politika kapsamı, makine dağıtım durumu ve observe ve enforce atamalarını gösteren Enforcement filo.](/images/dashboard/enforcement-fleet.png) + +En son dağıtımı hiç almayan makineleri, raporlamayı durduran kayıtlı makineleri, yanlış ortama atanan bir politikayı ve kesintiye uğramış bir güncelleme sonrası sürüm kaymasını arayın. + +Makineleri iş yükü ve ortama göre etiketleyin — yalnızca ana bilgisayar adları nadiren otomatik ölçeklendirme veya değiştirmeden sağ çıkar: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - Zorlama yönetimi bir idari Cloud iş akışıdır. Yalnızca köke ait zorlama rotalarını sıradan müşteri `/v1` API uç noktaları olarak değerlendirmeyin. + Enforcement yönetimi, yönetimsel bir Cloud iş akışıdır. Yalnızca kök enforcemet rotalarını sıradan müşteri `/v1` API uç noktaları olarak ele almayın. \ No newline at end of file diff --git a/docs/tr/policies/editor.mdx b/docs/tr/policies/editor.mdx index 376cdf63..85ad77e0 100644 --- a/docs/tr/policies/editor.mdx +++ b/docs/tr/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "Policy editor" -description: "Onaylanmış bir hata modundan sürümlü politikalar oluşturun ve gözden geçirin." +title: "Bir politika yazın" +description: "Failproof AI'nın bir denetim bulgusundan bir politika taslağı hazırlamasını sağlayın veya kaynağı kendiniz yazın, ardından gözden geçirin, test edin ve yayınlayın." icon: "file-pen-line" --- -Policy editor kullanarak bir bulguyu veya sorunu dağıtılabilir bir kurala dönüştürün. Yayımlamayı yazımdan ayrı tutarak, bir taslak canlı davranışı sessizce değiştiremez. +Bir politika yazmanın iki yolu vardır: Failproof AI'nın bir denetim bulgusundan taslak hazırlamasını sağlamak veya kaynağı kendiniz yazmak. Yayınlamayı veya dağıtmayı seçene kadar hiçbir şey yayınlanmaz veya dağıtılmaz. -Bir sorunun tekrarlanabilir bir eylem deseni varsa, bunu **Analyze → issues** altında açın ve **generate policy** seçeneğini seçin. Failproof AI önce politikanın sorunu ifade edip edemeyeceğini açıklar, ardından gözden geçirilen amacı ve bulgu bağlamını editöre taşır. Oluşturulan kaynak, yayımlayana kadar taslak olarak kalır. +## Denetimden bir politika yazın -## Bir politika sürümünü yayımlayın +Denetim bir hatayı bulur; politika bunun yeniden olmasını engeller. Failproof AI, politikayı bulguyu oluşturan kanıtlardan taslaklaştırır. + +### 1. Denetim çalıştırın + +Hatanın meydana geldiği oturumlar üzerinde [denetim çalıştırın](/tr/audits/run). Her bulgu kanıt oturumları, kök neden ve önerilen önleme yolunu içerir. **Tekrarlanabilir bir işlem deseni** taşıyan bir bulguden başlayın — bir politika yalnızca hook olayında tanıyabileceği şeyi durdurabilir. + +### 2. Taslağı oluşturun - 1. **Admin → policy editor** bölümüne gidin ve **compose** içinde hata modunu açıklayın veya JavaScript politika kaynağını yapıştırın. - 2. Kaynağı doğrulayın ve bildirilen her hatayı düzeltin. - 3. Politika kimliğini girin ve yayımlayın, ardından sürümleri karşılaştırmak veya devre dışı bırakmak için **library** kullanın. - 4. Sürüm bir makine dağıtımı için hazır olduğunda **enforcement** seçeneğini seçin. + 1. **Analyze → issues** altında bulgunun sorununu açın ve alıntı yapılan oturumları, kök nedeni ve tavsiyesini kontrol edin. + 2. **generate policy** seçeneğini seçin. Failproof AI önce bir politikanın sorunu hiç ifade edip edemeyeceğini söyler. **no policy** sonucu, düzeltmenin bir uyarı, iş akışı değişikliği veya bir kişi olduğu anlamına gelir — politika değil. + 3. **write this policy** seçeneğini seçin. Sorun başlığı, bulgu, kök neden, tavsiye ve önerilen yaptırım amacı **Admin → policy editor** içinde bir taslak haline gelir. Aday değerlendirme kontrolüne katılmadığınızda **open the editor anyway** kullanın. - ![Policy editor compose görünümü, politika kimliği, yapay zeka destekli taslaklama, kaynak doğrulama ve yayımlama kontrolleriyle.](/images/dashboard/policy-editor.png) + ![Policy editor compose görünümü, politika kimliği, yapay zeka destekli taslak, kaynak doğrulama ve yayın kontrolleri ile.](/images/dashboard/policy-editor.png) - CLI'dan `fp policies publish` ile yayımlayın. Bu yeni bir **version** oluşturur ve asla mevcut olanı düzenlemez. Kaynak, gönderilmeden önce node ile ayrıştırılıp kontrol edilir — aşağıdaki hiçbir sistem bunu yapmaz, bu nedenle bir sözdizimi hatası uygulanma sırasında makinede ortaya çıkabilir: + Kanıtları okuyun, ardından asistan ile taslak oluşturun. `compose` kaynağı gözden geçirmeniz için yazdırır ve hiçbir şey yayınlamaz: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - Yayımlama hiçbir şey dağıtmaz — yeni bir sürüm `fp fleet deploy` onu makineye koyana kadar kullanılmamış olarak kalır. `fp policies compose ""` Cloud asistanı ile kaynak hazırlar ve yayımlamak yerine gözden geçirilmesi için yazdırır. - - Bunun yerine yerel bir aracı CLI'ye (Cloud değil) bir politika yüklemek için `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project` komutunu kullanın. + `compose` imzalanmış bir oturuma ihtiyaç duyar (`fp login`) ki rolü `policies:write` yetkisine sahip olsun; API anahtarlarını reddeder. -## Yazım kontrol listesi +### 3. Taslağı gözden geçirin + +Taslak bir başlangıç noktasıdır, bir karar değil. Yayınlamadan önce şunları kontrol edin: + +1. Başarısızlık modunu operasyonel dilde adlandırır. +2. Yalnızca karar almak için yeterli kanıt taşıyan hook olayları ve araçlarıyla eşleşir. +3. Güvenli olmayan işlemi yakalayan en dar koşulu kullanır. +4. Ajanı ne yapması gerektiğini söyleyen bir neden döndürür. +5. Ajanın güvenli bir şekilde düzeltebileceği yerde `instruct` kullanır ve işlemin yapılmasına izin vermek kabul edilemez veya tersine döndürülemez olduğu yerde yalnızca `deny` kullanır. + +Editörde kaynağı doğrulayın ve bildirilen her hatayı düzeltin. + +### 4. Test edin, ardından yayınlayın + +Yayınlamadan önce kaynak altında **backtest** çalıştırın: taslağı donanımınızın zaten yaptığı çağrılara karşı yeniden oynatır ve kesintiye uğratacağı çalışan çağrıları sayar. [Bir politikayı test edin](/tr/policies/test) bunu ve diğer kontrolleri kapsar. + +Davrandığında, politika kimliğini girin ve **publish version** seçeneğini seçin. Yayınlama değişmez bir sürümü oluşturur ve hiçbir şey dağıtmaz: [dağıtıncaya kadar](/tr/policies/deploy) kullanılmamış kalır. Bir terminalden: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` kaynağı göndermeden önce ayrıştırma denetimi yapar, bu nedenle söz dizimi hatası bir makinede yaptırım süresi yerine burada ortaya çıkar. + +## Kendiniz yazın + +Bir politika `failproofai` API'ye karşı JavaScript veya TypeScript'tir: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +Bu `production/config.yml`, `/srv/production/config.yml`, `/srv/production` ve `C:\\production\\config.yml` için `Write` ve `Edit` öğelerini eşleştirir, ancak `production-backup` öğesini eşleştirmez: `production` tam bir yol segmenti olmalıdır. Bağlam ayrıca olay türü, normalleştirilmiş yük, oturum meta verileri, parametreler ve kullanılabilir olduğunda kaynak CLI'yi içerir — [politika SDK](/tr/reference/policy-sdk) sayfasına bakın. + +Bunu bir sürüm olarak yayınlamak için kaynağı **Admin → policy editor** içindeki **compose** girişine yapıştırın ve yukarıdaki 3 ve 4. adımları izleyin veya dosyayı terminalden `fp policies publish` ile yayınlayın. -1. Hata modunu operasyonel dilinde adlandırın. -2. Karar vermek için yeterli kanıt içeren hook olaylarını ve araçlarını seçin. -3. Güvensiz davranışla eşleşen en dar koşulu yazın. -4. Aracıya veya operatöre ne yapması gerektiğini söyleyen bir neden döndürün. -5. Eşleşmesi gereken örnekler ve izin verilmesi gereken örnekler ekleyin. -6. Yeni bir sürüm kaydedin ve gözden geçirilmesini isteyin. +Cloud olmadan bir makinede çalıştırmak için `.failproofai/policies/` altında `policies.js`, `policies.mjs` veya `policies.ts` ile biten bir adla kaydedin — bunlar proje ve kullanıcı kapsamında otomatik olarak yüklenirler — veya yola göre yükleyin: -Aracı güvenli bir şekilde yoluna döndürebiliyorsa `instruct` kullanın. Eyleme izin vermek kabul edilemez veya geri döndürülemez bir risk oluşturursa `deny` kullanın. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - Policy sürümleri değişmez dağıtım girdileridir. Bir taslağı düzenlemek yeni bir sürüm oluşturur; zaten makinelere atanmış olan sürümü yeniden yazmamalıdır. - \ No newline at end of file +Her politikaya, kural, özel, paket ve Cloud tarafından yönetilen politikalar arasında benzersiz olan bir ad verin. \ No newline at end of file diff --git a/docs/tr/policies/failure-behavior.mdx b/docs/tr/policies/failure-behavior.mdx index adaff6ff..7f3dac2c 100644 --- a/docs/tr/policies/failure-behavior.mdx +++ b/docs/tr/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- -title: "Hata davranışı" -description: "İlke değerlendirmesi veya yerel daemon kullanılamadığında neler olacağını anlayın." +title: "Başarısızlık davranışı" +description: "İlke değerlendirmesi veya yerel daemon kullanılamadığında ne olacağını anlayın." icon: "shield-alert" --- -Failproof AI, bir zorunluluk hatasının sessizce riskli işlere izin vermek yerine görünür olacak şekilde tasarlanmıştır. +Failproof AI, bir zorlama başarısızlığının görünür olacak şekilde tasarlanmıştır; riskli çalışmaya sessizce izin verilmez. -## Kapalı hata bloğunu tanılayın +## Başarısızlık-kapalı engeli tanılayın 1. **Admin → enforcement** bölümüne gidin ve makineyi açın. - 2. Son check-in'ini, atanan dağıtımını ve bildirilen dağıtımını kontrol edin. + 2. Son check-in zamanını, atanmış dağıtımını ve bildirilen dağıtımını kontrol edin. 3. **Observe → policy** bölümüne gidin ve reddedilen kararın oturumunu açın. - 4. Nedinin daemon ulaşılabilirliğini, sürüm uyumsuzluğunu veya ilkenin kendisini bildirip bildirmediğini doğrulayın. + 4. Nedenin daemon erişilebilirliğini, sürüm uyumsuzluğunu veya ilkenin kendisini bildirip bildirmediğini doğrulayın. @@ -23,45 +23,47 @@ Failproof AI, bir zorunluluk hatasının sessizce riskli işlere izin vermek yer failproofai config ``` - `failproofai config` komutunu yeniden çalıştırmak, bir paket yükseltmesinden sonra daemon'u günceller ve yeniden başlatır. + `failproofai config` komutunu yeniden çalıştırmak, paket yükseltmesinden sonra daemon'u günceller ve yeniden başlatır. -`failproofaid` kullanmak üzere yapılandırılan bir makinede, daemon tek değerlendirmeci olur. Ulaşılamıyorsa veya protokol sürümü CLI'dan eşleşmiyorsa, hook değerlendirmesi kapalı olarak başarısız olur. İşlem, operatöre daemon'u kontrol etme veya güncelleme talimatı veren bir nedenden reddedilir. +`failproofaid` kullanacak şekilde yapılandırılan bir makinede, daemon tek değerlendiricileridir. Erişilemez ise veya protokol sürümü CLI ile eşleşmiyorsa, hook değerlendirmesi başarısızlık-kapalı olur. İşlem, operatörü daemon'u kontrol etmeye veya güncellemeye yönlendiren bir neden ile reddedilir. -Daemon yapılandırmasından önce, hook'lar ilkeleri işlem içinde değerlendirir. Daemon yapılandırması kaydedildikten sonra, Failproof AI daemon başarısız olduğunda ikinci bir değerlendirmeciye sessizce geri dönmez. +Daemon yapılandırmasından önce, hook'lar ilkeleri işlem içinde değerlendirir. Daemon yapılandırması kaydedildikten sonra, Failproof AI daemon başarısız olduğunda ikinci bir değerlendirici'ye sessizce geri dönmez. -## Kapalı bir karara yanıt verin +## Başarısızlık-kapalı kararına yanıt verin 1. `failproofai config --status` komutunu çalıştırın. 2. Sürümler farklıysa, paketi güncelledikten sonra `failproofai config` komutunu yeniden çalıştırın. -3. Daemon ulaşılamıyorsa, hizmet durumunu ve yerel günlükleri inceleyin. -4. Bilinen bir ilke değerlendirme yolunun sağlıklı olduğundan emin olduktan sonra aracı çalışmasını devam ettirin. +3. Daemon erişilemez ise, hizmetin durumunu ve yerel günlükleri inceleyin. +4. Agent çalışmasını yalnızca bilinen bir ilke değerlendirme yolu sağlıklı olduktan sonra devam ettirin. - Engellenen işlemi tekrar tekrar denemeyin. Kapalı bir yanıt, sistemin işlemin güvenli olduğunu belirleyemediği anlamına gelir. + Engellenen işlemi tekrar tekrar denemeyin. Başarısızlık-kapalı yanıt, sistemin işlemin güvenli olduğunu belirleyemediği anlamına gelir. -## Bir pack yüklenmeyecek +## Bir paket yüklenmeyecek -Bir pack'i uygulamak için söylenen bir makine, bunu çalıştıramıyorsa, sessizce devam etmek yerine reddeder. Tetikleyici, asla boş olmayan **kaydedilmiş bir beklenti**dir: hiçbir pack'i yüklü olmayan bir makine sessizdir, ancak bildirilen ve çözülmeyecek bir pack veya manifesti bildirdiklerinden daha az kayıt yapan bir pack reddeder. +Bir paketi uygulamaya söylenen ve çalıştıramayan bir makine, sessizce devam etmek yerine reddeder. Tetikleyici **kaydedilmiş bir beklenti**dir, asla boş değildir: kurulu paketi olmayan bir makine sessizdir, ancak beyan edilen ve çözülmeyecek olan bir paket — veya manifestinin deklare ettiğinden daha az kaydettiği bir paket — reddeder. -Reddetme **dar kapsamlı**dır, ulaşılamayan bir daemon'dan farklı olarak. Ulaşılamayan bir daemon, hiçbir değerlendirmenin gerçekleşmediği anlamına gelir, bu nedenle hiçbir şey güvenli olduğu bilinmez. Yüklenmeyecek bir pack, numaralandırılabilen eksik guard kümesine sahiptir, çünkü her bildirilen ilke kendi `match` değerine sahiptir; bu nedenle, yalnızca bu ilkelerin kapsadığı olayları ve araçları reddeder, diğer her şey devam eder. +Reddetme **dar**dır, ulaşılamayan bir daemon'dan farklı olarak. Ulaşılamayan bir daemon hiç değerlendirmenin yapılmadığı anlamına gelir, bu nedenle hiçbir şeyin güvenli olduğu bilinmez. Yüklenmeyecek bir paketin numaralandırılabilir bir eksik korumaları kümesi vardır, çünkü her beyan edilen ilke kendi `match` değerine sahiptir — bu nedenle yalnızca bu ilkelerin kapsadığı olayları ve araçları reddeder ve başka her şey devam eder. -Şu durumlar için tetiklenmez: +Aşağıdakiler için tetiklenmez: -- yapısı gereği değerlendiren ve atma işlemi yapan bir `observe` pack -- asla almadığınız veya açıkça kapatılan ilkeler -- yükleyicinin hiçbir zaman almadığı bir pack; burada "kayıt yok", kasıtlı bir atlanmışlık olarak ayırt edilemez +- yapısı itibariyle değerlendirilen ve atılan bir `observe` paketi +- asla almadığınız veya açıkça kapattığınız ilkeler +- yükleyicinin hiç almadığı bir paket; "kayıt yok" kasıtlı atlama ile ayrılamaz - etkin bir oturum duraklatması -- geçici olan bir yükleme zaman aşımı; bir yavaş disk anı, bir insan müdahale edene kadar reddetmemelidir +- yükleme zaman aşımı (geçicidir) — bir yavaş disk anı, insani müdahale olana kadar reddetmemelidir -`UserPromptSubmit`, bildirilen eksik ilkelerden bağımsız olarak reddediş yerine **talimat** verir. Kapsamlı bir reddetme, bunu da yanına alır ve sorunu çözebilecek aracıya sizi kilitler. +`UserPromptSubmit` ne kadar eksik ilke beyan etmiş olsa, reddetme yerine **talimat** verir. Genel bir reddetme bunu alır ve sorunu çözbilecek agent'ı kilitler. -### Yapılması gerekenler +### Ne yapmalı ```bash -failproofai pack list +failproofai policies ``` -Yüklenmeyecek yüklü pack'leri listeler, nedenini söyler ve sıfır olmayan bir değerle çıkır. Sonra bunu yeniden yükleyin (`failproofai pack add `) veya kaldırın (`failproofai pack remove `) — kaldırmak beklentiyi geri çeker ve reddetme de bununla birlikte durur. \ No newline at end of file +Listeleme, yüklemesi kaydı veya özeti artık kontrol edilmeyecek yüklü bir paketi işaretler ve nedenini söyler. Paketi içe aktarmaz, bu nedenle yalnızca yüklemesinden sonra başarısız olan bir paket — manifestinin deklare ettiğinden daha az kaydettiği — normal olarak listelenir; aşağıdaki reddetme bunu adlandıran şeydir. Her halükarda, onu yeniden yükleyin (`failproofai policies add `) veya kaldırın (`failproofai policies remove `) — kaldırma beklentiyi geri çeker ve reddetme onunla birlikte durur. + +Reddetme kendisi `pack/failproofai-pack-unavailable` öğesine atfedilir ve bu, yüklenen ilkeleri geçersiz kılar, bu nedenle engellenen bir araç çağrısı, ilk harekete geçen surviv korumasından ziyade eksik paketi adlandırır. \ No newline at end of file diff --git a/docs/tr/policies/local-configuration.mdx b/docs/tr/policies/local-configuration.mdx index dc5537b0..fb8b8e67 100644 --- a/docs/tr/policies/local-configuration.mdx +++ b/docs/tr/policies/local-configuration.mdx @@ -1,55 +1,49 @@ --- -title: "Yerel yapılandırma" -description: "Policy kapsamını, parametrelerini, özel dosyaları ve makine düzeyindeki Failproof AI ayarlarını kontrol edin." +title: "Yerel konfigürasyon" +description: "Failproof AI politika kapsamını, parametrelerini, özel dosyaları ve makine düzeyindeki ayarlarını kontrol edin." icon: "file-cog" --- -Failproof AI, policy seçimini makine ve daemon ayarlarından ayırır. Bu, depo policy seçimlerinin gözden geçirilebilir kalmasını sağlarken, kimlik bilgileri ve daemon durumu depo dışında kalır. +Failproof AI, bir deponun commit edebileceği şeyleri — hook bağlantısı, politika parametreleri, özel politikalar — kimlik bilgileri, yüklü paketler ve daemon gibi makine durumundan ayrı tutar. -## Policy kapsamını seçin +## Bir kapsam seçin - - - Yerel policy panosunu açmak için `failproofai` komutunu bağımsız değişken olmadan çalıştırın. Bir policy'yi etkinleştirmeden önce kullanıcı, proje veya yerel kapsamı seçin, böylece değişiklik amaçlanan yapılandırma dosyasına yazılır. +Bir kapsam, hook'ların nerede bağlandığını ve parametreleri ile özel politika yollarını hangi konfigürasyon dosyasına yazacağınızı belirler: - - **User** bu makinedeki tüm projeler arasında geçerlidir. - - **Project** depoya aittir ve işlenebilir (commit). - - **Local** bir projeyi tek bir kullanıcı için geçersiz kılar ve gitignore'da kalmalıdır. +- **User** bu makinede projeler arasında geçerlidir. +- **Project** depoya aittir ve commit edilebilir. +- **Local** bir projeyi bir kullanıcı için geçersiz kılar ve gitignore'da kalmalıdır. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # bu depo için hook'ları bağla +failproofai policies --install --cli claude --scope user # veya bu makinedeki her proje için +failproofai policies +``` - Her harness yerel kapsamı desteklemez. CLI, seçilen harness'in temsil edemediği bir kapsamı reddeder. - - +Her harness yerel kapsamı desteklemez; CLI, seçilen harness'in temsil edemeyeceği bir kapsamı reddeder. + +Hangi paket politikalarının açık olduğu **kapsamlı değildir**. Anahtar, yüklü pakettle kaydedilir, bu nedenle `failproofai policies add ` `--scope` ne derse desin, bir politikayı tüm makine için açar. -| Kapsam | Policy yapılandırma dosyası | +| Kapsam | Politika konfigürasyon dosyası | | --- | --- | | Project | `/.failproofai/policies-config.json` | | Local | `/.failproofai/policies-config.local.json` | | User | `~/.failproofai/policies-config.json` | -Etkinleştirilen policy'ler bir birleşim olarak birleştirilir. Policy parametreleri, bu policy için parametreleri tanımlayan ilk kapsamı kullanır (proje → yerel → kullanıcı sırasında). Açık özel policy yolları, bunları tanımlayan ilk kapsamı kullanır. +Politika parametreleri, o politika için parametreleri tanımlayan ilk kapsamı kullanır; proje → yerel → kullanıcı sırasında. Açık özel politika yolları, bunları tanımlayan ilk kapsamı kullanır. -## Policy parametrelerini yapılandırın +## Politika parametrelerini yapılandırın - Yerel panosunda policy'yi açın, desteklenen parametrelerini düzenleyin ve seçilen kapsamda kaydedin. Eşleşen ve eşleşmeyen bir agent eylemi çalıştırın, ardından **Observe → policy** bölümünde kararı inceleyin. + Yerel dashboard'da politikayı açın, desteklenen parametrelerini düzenleyin ve seçilen kapsamda kaydedin. Eşleşen ve eşleşmeyen bir ajan eylemini çalıştırın, ardından **Observe → policy** kısmında kararı inceleyin. - Seçilen kapsamın `policies-config.json` dosyasını düzenleyin, ardından bilinmeyen policy adlarını veya parametre anahtarlarını ortaya çıkarmak için `failproofai policies` komutunu çalıştırın. + Seçilen kapsamın `policies-config.json` dosyasını düzenleyin, ardından `failproofai policies` çalıştırın: bir `policyParams` girdisinin yüklenmiş hiçbir paket tarafından taşınmayan bir politikayı adlandırması durumunda uyarır. Bir girdinin içindeki anahtarları kontrol etmez, bu nedenle bunları aşağıdaki tabloya göre kontrol edin. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ Etkinleştirilen policy'ler bir birleşim olarak birleştirilir. Policy parametr +### Failproof AI politikalarının kabul ettiği parametreler + +Her politika kendi parametre türlerini doğrular. + +| Politika | Parametre | Tür ve varsayılan | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; girdiler `regex` ve `label` içerir | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| Altyapı engelleyicileri | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + İzin verme deseni, bir ajanın yapabileceği şeyleri genişletir. Hedef harness'te tam tokenleştirme ve komut varyantlarını test ettikten sonra bir filo genelinde dağıtın. + + ## Makine dosyalarını anlayın -`~/.failproofai`, ayrı güven sınırları için ayrı dosyalar içerir: +`~/.failproofai` farklı güven sınırları için ayrı dosyalar içerir: | Yol | Amaç | | --- | --- | | `config.json` | Gizli olmayan daemon, denetim ve telemetri ayarları | -| `credentials.json` | Bulut kimlik bilgileri; yalnızca sahip izinleriyle depolanır | -| `policies-config.json` | Kullanıcı kapsamı yerleşik seçim, parametreler ve açık özel yollar | -| `policies/` | Kullanıcı kuralı policy'leri ve Bulut tarafından yönetilen policy yapıtları | -| `hook-activity/` | Yerel policy karar günlüğü | -| `state/` | Daemon spool'u, sağlık, duraklatma ve çalışma zamanı durumu | +| `credentials.json` | Bulut kimlik bilgileri; yalnızca sahibin izinleriyle depolanır | +| `policies-config.json` | Kullanıcı kapsamı parametreleri ve açık özel politika yolları | +| `policies/` | Kullanıcı kural politikaları, yüklü paketler ve bunların politikalarından hangilerinin açık olduğu ve Bulut tarafından yönetilen politika yapıtları | +| `hook-activity/` | Yerel politika karar günlüğü | +| `state/` | Daemon spool, sistem sağlığı, duraklatma ve çalışma zamanı durumu | -Bir konteyner veya izole test için tam makine düzenini yeniden konumlandırmak amacıyla `FAILPROOFAI_HOME` kullanın. Tek tek durum dizinlerini bağımsız olarak yeniden konumlandırmayın. +Bir konteyner veya izole edilmiş test için tam makine düzenini yeniden konumlandırmak için `FAILPROOFAI_HOME` kullanın. Durum dizinlerini bağımsız olarak yeniden konumlandırmayın. - `credentials.json` dosyasını asla işlemeyin (commit). Proje policy yapılandırması ve proje kuralı policy'lerini yalnızca uygulama kodu olarak gözden geçirdikten sonra işleyin. + Asla `credentials.json` commit etmeyin. Proje politika konfigürasyonunu ve proje kural politikalarını yalnızca uygulama kodu olarak inceledikten sonra commit edin. \ No newline at end of file diff --git a/docs/tr/policies/overview.mdx b/docs/tr/policies/overview.mdx index 2887a250..8ec3699f 100644 --- a/docs/tr/policies/overview.mdx +++ b/docs/tr/policies/overview.mdx @@ -1,63 +1,54 @@ --- -title: "Politikalar" -description: "Bilinen bir hata tekrarlanmadan önce agent eylemlerini gözlemleyin, yönlendirin veya engelleyin." +title: "İlkeler" +description: "Aracı eylemlerini gözlemleyin, yönlendirin veya bilinen bir hata tekrarlanmadan önce engelleyin." icon: "shield-check" --- -Bir politika, bir agent hook olayını değerlendirir ve üç karardan birini döndürür: +Bir ilke, bir aracı hook olayını değerlendirir ve üç karardan birini döndürür: -- `allow` eylemi devam ettirir. -- `instruct` agent'a düzeltici rehberlik sağlar. -- `deny` eylemi bir nedenle engeller. +- `allow` eyleme devam etmesine izin verir. +- `instruct` aracıya düzeltici rehberlik sağlar. +- `deny` eylemi bir neden ile engeller. -## Üç politika yüzeyini kullanın +## İlkeler nerede yer alır - - - 1. Oturumlardan politika kararlarını filtrelemek ve incelemek için **Observe → policy** sayfasına gidin. - 2. Politika oluşturmak, doğrulamak, yayınlamak, devre dışı bırakmak veya değişmez sürümleri incelemek için **Admin → policy editor** sayfasına gidin. - 3. Sürümleri ve etkileri makinelere atamak için **Admin → enforcement** sayfasına gidin. +| Panoda | Orada yapacağınız şey | +| --- | --- | +| **Gözlem → ilke** | Gerçek oturumlardan alınan kararları gözden geçirin: hangi ilke eşleşti, hangi makinede ve neden | +| **Yönetim → ilke editörü** | Bir ilke yazın, geçmiş trafiğe karşı geri test edin, değişmez bir sürüm yayınlayın ve **kütüphanede** sürümleri karşılaştırın | +| **Yönetim → zorlama** | Sürümleri makinelere, gözlem veya zorlama modunda yerleştirin | - Yazar olmadan veya zorlama değiştirmeden önce neyin zaten eşleştiğini anlamak için Policy sayfasını kullanın. +İlke editörü, bir hatanın kural haline geldiği yerdir. **Oluştur** kısmında hata modunu açıklayın veya ilke kaynağını yapıştırın, taslağı halihazırda sahip olduğunuz trafiğe karşı geri test edin ve bir sürüm yayınlayın: - ![Karar toplamlarını ve yerel ve Cloud tarafından yönetilen politika eşlemelerini gösteren Policy sayfası.](/images/dashboard/policy-observe.png) +![İlke editörü oluştur görünümü - ilke kimliği, yapay zeka destekli taslak oluşturma, kaynak doğrulama ve yayınlama kontrolleri.](/images/dashboard/policy-editor.png) - Editör, bir hata durumunu kaynağa dönüştürdüğünüz, doğruladığınız ve değişmez bir sürümü yayınladığınız yerdir. +Bir makinede, `failproofai policies` orada uygulanan her şeyi listeler. `fp policies` ve `fp fleet` terminalden editörü ve uygulamayı kapsar — bkz. [Cloud CLI referansı](/tr/reference/cloud-cli). - ![Değişmez bir politika sürümü oluşturmak ve yayınlamak için kullanılan Policy editörü.](/images/dashboard/policy-editor.png) +## Bir ilke edinin - Zorlama daha sonra o yayınlanmış sürümü ve onun gözlemle veya zorlama efektini makinelere atar. - - ![Makine kapsamı ve atanan politika sürümlerini gösteren Enforcement fillosu.](/images/dashboard/enforcement-fleet.png) - - Dağıtımdan sonra Policy sayfasında kararları doğrulayın, böylece yazma ve filo görünümleri gerçek agent aktivitesine bağlı olur. - - - Yerel politika kurulumu ve doğrulaması için `failproofai` kullanın: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - Politika kararları içeren Cloud oturumlarını ve olaylarını bulmak için `fp` kullanın. Cloud yazma ve filo dağıtımı dashboard iş akışlarında kalır. - - - -Politikaların Failproof AI'de üç farklı yüzeyi vardır: - -1. **Kararları analiz edin** oturumlarda, panorlarda ve denetimlerde. -2. **Sürümleri yazın** yerleşik kurallar, kod veya politika editörü ile. -3. **Sürümleri dağıtın ve zorlayın** seçilen makineler arasında. - -Onaylı bir hata modundan başlayın. Onu tanımlayan en küçük olayı ve araç eşleşmesini tanımlayın, yasal ve güvenli olmayan örnekleri test edin, sonra zorlamadan önce gözlemleyin. +İki yolu vardır. - - Yaygın gizli bilgi, shell, Git, bulut ve iş akışı riskleri için gözden geçirilmiş bir kural etkinleştirin. + + Failproof AI'ın bir denetim bulgusundan bir taslak oluşturmasına izin verin veya kaynağı kendiniz yazın, ardından editörde gözden geçirin ve yayınlayın. - - JavaScript veya TypeScript ile iş akışına özgü bir karar ifade edin. + + Kullanım durumunuz için bir Failproof AI ilke paketi ya da ilke hub'ından bir topluluk paketini tek bir komutla bağlayın. - \ No newline at end of file + + +## Ardından gönder + + + + Taslağı halihazırda sahip olduğunuz trafiğe karşı geri test edin ve durması gereken bir eylem ile izin vermesi gereken bir eyleme karşı çalıştırın — tümü yayınlamadan önce. Bkz. [İlkeyi test et](/tr/policies/test). + + + Sürümü makinelere **gözlem** modunda yerleştirin, kararlarını okuyun, ardından uygulayın. Bkz. [İlke dağıt](/tr/policies/deploy). + + + Her yayın yeni, değişmez bir sürümdür; bu nedenle geçerli çalışmayı engelleyen bir dağıtım, son iyi sürümü yeniden dağıtarak geri alınır. Bkz. [Sürümler ve geri alma](/tr/policies/rollback). + + + +İlkelerinizi diğer ekiplerle paylaşmak için [bunları bir paket olarak yayınlayın](/tr/policies/publish-a-pack). Bir ilke hiç değerlendirilemediğinde ne olur öğrenmek için bkz. [Başarısızlık davranışı](/tr/policies/failure-behavior). \ No newline at end of file diff --git a/docs/tr/policies/packs.mdx b/docs/tr/policies/packs.mdx index f04f6631..9c967212 100644 --- a/docs/tr/policies/packs.mdx +++ b/docs/tr/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "İlke paketleri" -description: "GitHub sürümü olarak yayınlanan bir ilke setini yükleyin ve uyguladığı şeyleri yönetin." +title: "İlke paketini kullanma" +description: "Failproof AI ilke paketini veya politika merkezindeki bir topluluk paketini kullanım durumunuz için eklyin ve neyi uyguladığını seçin." icon: "package" --- -Bir paket, GitHub sürümü olarak yayınlanan bir ilke setidir. Tek bir komut bunu yükler, sürümün kendi sağlama toplamları çalıştırılmadan önce doğrulanır ve paket makineniz altında değişemeyecek şekilde özeti kaydedilir. +Paket, bir GitHub sürümü olarak yayımlanan bir ilke setidir. Tek bir komut ile kurar: sürümün kontrol toplamları herhangi bir şey çalışmadan önce doğrulanır ve paketi makineniz altında değiştiremeyecek şekilde özeti kaydedilir. -## Failproof AI ilkelerini yükleyin +Her paketi ve içindeki her ilkeyi [politika merkezinde](https://befailproof.ai/policy-hub/) bulabilirsiniz. İki tür vardır: + +- **Failproof AI ilke paketleri** — önceden tanımlanmış kullanım durumları için hazır paketler: birini ekleyin ve çalışır. [Kodlama aracısı ilke paketi](https://befailproof.ai/policy-hub/failproofai/policies/) şu anda kullanılabilir ve daha fazla kullanım durumu için paketler yakında geliyor. +- **Topluluk ilke paketleri** — geliştiricilerin kendi kullanım durumları için yazdığı ve herkese açık olarak yayımladığı ilkeler. + +## Failproof AI ilke paketleri + +### Kodlama aracısı ilke paketi ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -Bu, pakette bulunan kopya tarafından yayınlanan seti yükler — bu nedenle ağ gerektirmez ve bir proxy arkasında başarısız olamaz. Bir kısmını alın: +Paket 38 ilke taşır ve bildiriminin uygun olarak işaretlediği 10'unu katılımsız şekilde etkinleştirir; geriye kalanlar sizin seçmeniz için listelenir. En çok kullanılanlardan bazıları ve düz `policies add` ile açılıp açılmadığı: + +| İlke | Ne yaptığı | Varsayılan olarak açık | +| --- | --- | --- | +| `block-push-master` | Korumalı dalara doğrudan itmeleri engeller | Evet | +| `block-env-files` | `.env` dosyalarını okuma ve yazma işlemlerini engeller | Evet | +| `protect-env-vars` | Ortam değişkenlerini döken komutları engeller | Evet | +| `block-sudo` | İzin desenine uymadıkça `sudo` öğesini engeller | Evet | +| `block-curl-pipe-sh` | İndirilen komut dosyalarının doğrudan bir kabuk içine boru aktarılmasını engeller | Evet | +| `sanitize-*` (beş ilke) | Araç çıkışında bulunan API anahtarları, taşıyıcı belirteçleri, JWT'ler, özel anahtarlar ve bağlantı dizelerini bildir | Evet | +| `block-rm-rf` | Yıkıcı özyinelemeli silmeleri engeller | Hayır | +| `block-force-push` | Kuvvet itişlerini engeller | Hayır | +| `block-secrets-write` | Kimlik bilgisi ve gizli anahtar dosyalarına yazma işlemlerini engeller | Hayır | +| `warn-destructive-sql` | `WHERE` olmayan `DROP`, `TRUNCATE` ve `DELETE` öğelerinde uyarır | Hayır | + +Kapalı olanları ada göre açın — `failproofai policies add block-rm-rf` — veya `--all` ile tüm paketi alın. İçindeki her ilkeyi kategoriye göre gruplandırılmış olarak görün: ```bash -failproofai pack add core --policy block-rm-rf # bir tane veya virgülle ayrılmış birkaç tane -failproofai pack add core --category dangerous-commands # tüm bir kategori -failproofai pack add core --all # içindeki her şey +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` paketin sunduğu her kategoriyi adlandırır. +## Topluluk ilke paketleri -## Bir paketi yüklemeden önce neler içerdiğini görmek +Geliştiriciler karşılaştıkları kullanım durumları için paketler yayımlar ve [politika merkezi](https://befailproof.ai/policy-hub/) bunları listeler. Bir topluluk paketi yazar tarafından yayımlanır, Failproof AI tarafından denetlenmez; bu nedenle kurmadan önce neyi taşıdığını okuyun: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -Paketin taşıdığı her ilkeyi kategoriye göre gruplandırılmış şekilde listeler, yazarının varsayılan olarak hangileri açtığını ve hangilerinin isteğe bağlı olduğunu işaretler. **Yalnızca manifesto** okur — giriş yapısı asla indirilmez ve asla aktarılmaz, bu nedenle bir yabancının paketine bakmak yabancı kodun çalışmasına neden olamaz. Manifest yine de sürümün kendi `SHA256SUMS` öğelerine karşı kontrol edilir, bu nedenle okuduğunuz şey yüklenecek olan şeydir. - -`failproofai pack list` kaynak olmadan burada zaten yüklü olan paketleri listeler. +Bu, taşıdığı her ilkeyi kategoriye göre gruplandırılmış olarak listeler ve yazarın varsayılan olarak hangi olanları etkinleştirdiğini işaretler. **Yalnızca bildirimi** okur — giriş yapısı hiçbir zaman indirilmez veya ithal edilmez; bu nedenle bir yabancının paketine bakmak bir yabancının kodunu çalıştıramaz. Bildirim yine de sürümün kendi `SHA256SUMS` dosyasına karşı denetlenir; bu nedenle okuduğunuz şey yükleyeceğiniz şeydir. -## Başka birinin paketini yükleyin +Ardından onu kurun: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -Bu seçeneklerden herhangi biri çalışır — hangisine sahipseniz yapıştırın: +Bunların herhangi biri çalışır — sahip olduğunuz herhangi birini yapıştırın: | Kaynak | Sonuç | | --- | --- | -| `acme/support-agent` | En yeni sürüm, **çözdüğü tam etikete sabitlenmiş** | +| `acme/support-agent` | En yeni sürüm, **sabitlenmiş** tam etikete | | `acme/support-agent@v2.1.0` | O sürüm | -| `github:acme/support-agent@v2.1.0` | Aynısı, açıkça yazılmış | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Aynısı, tarayıcıdan kopyalanmış | +| `github:acme/support-agent@v2.1.0` | Aynı, açıkça yazılmış | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Aynı, tarayıcıdan kopyalanmış | -Etiketi adlandırmaması en yeni sürümü yükler **ve sabitler**, sonra hangi etiketi seçtiğini söyler. Kaydedilen her şey tam olarak bir sürümü adlandırır, bu nedenle yeniden yükleme kayabilmez. +Etiket adını vermeme en yeni sürümü yükler **ve sabitler**, ardından seçtiği etiketi söyler. Kaydedilen her zaman tam olarak bir sürümü adlandırır; bu nedenle yeniden kurulum bozulamaz. -## Bir paketin bir parçasını alın +## Bir paket parçasını alın -Varsayılan olarak paketin **kendi** varsayılanlarını alırsınız — yazarının yanında çalıştırmak için güvenli olarak işaretlediği ilkeler — içerdiği her şeyi değil. +Varsayılan olarak paket **kendi** varsayılanlarını alırsınız — ilkesinin yazarı katılımsız olarak açılmak için güvenli olarak işaretlediği; içerdiği her şeyi değil. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # bir veya virgülle ayrılmış birkaç +failproofai policies add FailproofAI/policies --category dangerous-commands # tüm bir kategori +failproofai policies add FailproofAI/policies --all # içindeki her şey ``` -`--category` ve `--policy` birleşim olarak birleşir (`--only` `--policy` için eş anlamlı olarak kabul edilir). Daha yeni bir sürümde yeniden eklemek, kalan her şeyi geri açmak yerine seçtiğiniz şeyi tutar. +`--category` ve `--policy` bir birleşim olarak birleşir (`--only` `--policy` için eş anlamlı olarak kabul edilir). Paket zaten yüklendiğinde, bayraklar sahip olduklarınıza eklenir ve yükseltme gibi hiçbir bayrak ve terminal olmadan yeniden eklenmesi seçiminizi olduğu gibi tutar. Terminal ile bayrak olmadan `add` seçiciyi açar; yazarın varsayılanları ile önceden işaretlenmiş ve işaretledikleriniz seçiminizi değiştirir. ## Açık olanları yönetin ```bash -failproofai policies # bir listede her kaynak, paketler dahil -failproofai pack list # yalnızca paketler, kategoriye göre gruplandırılmış +failproofai policies # her kaynak tek bir listede, paketler dahil +failproofai policies add block-rm-rf # bir ilkeyi açın failproofai policies --uninstall block-refunds # bir paket ilkesini kapatın failproofai policies --install block-refunds # ve geri açın -failproofai pack remove acme/support-agent +failproofai policies remove acme/support-agent # paketi kaldırın ``` -Açık bir ad, o adla bir **yerleşik** anlamına gelir. İhtiyacınız olduğunda bir paketin kopyasını açıkça adlandırın: +Bir paket ilkesini açmak veya kapatmak tüm makine için geçerlidir: anahtar, `--scope` ne derse desin, bir projenin yapılandırmasında değil, yüklü paket ile kaydedilir. + +Eğik çizgisi olmayan bir ad, bir ilkedir; biri olan herhangi bir şey, bir paket kaynağıdır. Çıplak bir ad, onu bildiren yüklü paketi çözer. İki yüklü paket aynı adı bildirdiğinde, istediğinizi adlandırın: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -Bir paket, adı aynı zamanda etkinleştirilmiş bir **yerleşik** olan bir ilke gönderirse, yerleşik çalışır ve paketin kopyası atlanır — aynı koruma aksi takdirde iki kez değerlendirilirdi. Yerine paketin kopyasını kullanmak için yerleşik olanı kapatın. - - -## Failproof AI ilkeleri nereden geliyor - -`core` npm paketinde satılan kopyayı okur. Aynı set GitHub sürümü olarak yayınlanır, belirli bir sürüm istiyorsanız bunu yüklersiniz: - -```bash -failproofai pack add core # bu paketten, ağ yok -failproofai pack add FailproofAI/policies # aynı set, GitHub sürümünden -``` +Kapsamlar, parametreler ve bu komutların yazdığı dosyalar [yerel yapılandırma](/tr/policies/local-configuration) içinde ele alınır. -## Bütünlüğün ne satın aldığı ve satın almadığı +## Bütünlüğün ne satın aldığı ve almadığı -`SHA256SUMS` yapı ile aynı sürümde gönderilir, bu nedenle **imza değildir** ve yayın yapanın kim olduğu konusunda hiçbir şey kanıtlamaz. Kanıtladığı şey, baytların o sürümün yayınladığı olanlar olmasıdır — ve paketin eklendiğinde özet kaydedildiğinden ve her aktarımdan önce yeniden doğrulanması nedeniyle, bir paket makineniz altında değişemez. Bir depoyu yeniden etiketleyen veya bir varlığı değiştiren, sessizce başka bir şey çalıştırmak yerine yüklenmez. +`SHA256SUMS` yapıyla aynı sürümde gemi; bu nedenle **imza değildir** ve yayımlayanlar hakkında hiçbir şey kanıtlamaz. Kanıtladığı şey, baytların o sürümün yayımladıkları olmasıdır — ve paketi eklediğinizde özet kaydedildiği ve her ithalatından önce yeniden doğrulandığı için, paket makineniz altında değişemez. Etiketi yeniden etiketleyen veya bir varlığı değiştiren bir depo, sessizce başka bir şey çalıştırmak yerine yüklemeyi durdurur. -Yükleme sırasında paket da **bir kez aktarılır** ve kendi manifestosuna karşı kontrol edilir. Yapısı ayrıştırılmayan veya bildirdiklerinden başka bir şey kaydeden bir paket, herhangi bir şey etkinleştirilmeden önce reddedilir — temiz bir şekilde yüklemek ve bir sonraki araç çağrısında başarısız olmak yerine. +Kurulum sırasında paket da **bir kez ithal** edilir ve kendi bildirimine karşı denetlenir. Yapısı ayrıştırılmayan veya bildirdiğinden başka bir şey kaydeden bir paket, hiçbir şey etkinleştirilmeden önce reddedilir — temiz şekilde kurulduktan sonra bir sonraki araç çağrısında başarısız olmak yerine. -## Bir paket ne zaman yüklenmeyecek +## Bir paket yüklenemeyen zaman -Bu makinenin uygulaması gerektiği ve çalıştıramadığı bir paket **eksik ilkelerinin kapsadığı olayları reddeder**, bunları sessizce izin vermek yerine. [Hata davranışı](/tr/policies/failure-behavior) bölümünü görün. `failproofai pack list` o durumdaki herhangi bir paketi adlandırır ve sıfırdan farklı bir değerle çıkılır. +Bu makinenin uygulaması söylendiği ve çalışması imkansız olan paket, eksik ilkelerinin kapsadığı olayları yoksayarak **reddeder** — `pack/failproofai-pack-unavailable` olarak, yüklü ilkeleri geçersiz kılan politikaları sıralar; bu nedenle reddin eksik pakete atfı yapılır; hangisi ateşlendi. İstisna `UserPromptSubmit` dır; orada reddetmek sizi düzeltmek için ihtiyaç duyduğunuz aracıdan kilitlerdi. Bkz. [Başarısızlık davranışı](/tr/policies/failure-behavior). ## Çevrimdışı ve aynalar | Değişken | Etki | | --- | --- | | `FAILPROOFAI_NO_DOWNLOAD=1` | Getirmeyi reddeder; zaten yüklü paketler uygulamaya devam eder | -| `FAILPROOFAI_PACK_BASE_URL` | Paket getirme işlemini `github.com` yerine bir aynaya yönlendirir | +| `FAILPROOFAI_PACK_BASE_URL` | Paket getirmesini `github.com` yerine bir aynaya işaret eder | -Kendi paketin yayınlanması: [Bir paket yayınla](/tr/policies/publish-a-pack) bölümünü görün. \ No newline at end of file +Kendi ilkelerinizi bu şekilde paylaşmak için bkz. [İlke paketi yayımla](/tr/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/tr/policies/publish-a-pack.mdx b/docs/tr/policies/publish-a-pack.mdx index 97dc5697..ccfd861c 100644 --- a/docs/tr/policies/publish-a-pack.mdx +++ b/docs/tr/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "Paket yayınlama" -description: "Kendi politikalarınızı herkesin yükleyebileceği bir GitHub sürümü olarak gönderin." +title: "Bir politika paketini yayınla" +description: "Kendi politikalarını herkesin yükleyebileceği bir GitHub sürümü olarak dağıt." icon: "upload" --- -Bir paket, GitHub sürümüne eklenen üç dosyadan oluşur. `failproofai pack build` bunların üçünü de zaten sahip olduğunuz bir politika dosyasından yazar. +Bir paket, bir GitHub sürümüne eklenen üç dosyadan oluşur. `failproofai publish` bunların hepsini önündeki politika dosyalarından yazar, sürümü oluşturur ve bunları yükler. -## 1. Politikaları yazın +## 1. Politikaları yaz -Bir dosya, herhangi bir özel politika ile aynı API'yi kullanır. Bir paket için iki ek alan önemlidir: +Boşlukları olan bir şablondan ziyade zaten çalışan bir şeyden başla: + +```bash +failproofai publish --init +``` + +Bu, paketin adını sorar, `.mjs` dosyasını yazar ve durur — ağ yok, git yok, hiçbir şey yayınlanmadı. Yazdığı dosya, `git push --force` komutunu zaten engelleyen bir politikadır. Zaten var olan bir dosyanın üzerine yazmayı reddeder. + +Politikalar, herhangi bir özel politika ile aynı API'yi kullanır. Bir paket için önemli olan iki ekstra alan vardır: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -Bunu atladığınızda `defaultEnabled` varsayılan olarak **false** olur. Düz bir `failproofai pack add` yalnızca işaretlediklerinizi açar — bir yabancının her politikasını izinsiz yüklemek, yükleyicinin kullanıcısı için yapması gereken bir karar değildir. +`defaultEnabled` değerini atladığında varsayılan olarak **false** olur. Düz `failproofai policies add` komutu yalnızca işaretlediklerinizi açar — bir yabancının her politikasını kurulu olarak yüklemek, yükleyicinin kullanıcısı için yapması gereken bir karar değildir. + +İstediğiniz kadar dosya yazabilirsiniz; kategori başına bir dosya iyi okunur. Politikalara kayıt olan dizindeki her dosya, bir paketin sahip olması gereken tek yapıya dahil edilir. -Girdi **tek kendi içinde olan bir dosya** olmalıdır. Yalnızca girdinin özeti sabitlendiğinden, yerel dosyaları içe aktaran bir paket, özeti çalışanları kapsadığını dürüstçe iddia edemez. Önce paketleyin (`esbuild`, `bun build`, `rollup`) ve paketi paketten oluşturun — `pack build` yerel bir içe aktarmayı reddeder ve tutamayacağı bir vaadi göndermek yerine. + Paketleme **bun** gerektirir. Bunu olmadan, tek bir kendi kendine yeterli dosyada kalın. Her iki durumda da yayınlanan giriş, yükleme zamanında yerel dosyaları içe aktarmamalıdır: yalnızca giriş özet-sabitlemiştir, bu nedenle kardeş dosyalara uzanan bir paket, özetin çalışan şeyi kapsadığını dürüstçe iddia edemez — ve `publish` bunu yapan yerine, tutamayacağı bir söz göndermekten kaçınır. -## 2. Sürüm varlıklarını oluşturun +## 2. Önce burada dene + +Başka biri onu görmeden önce, dosyayı bu makinede uygula: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +Herhangi bir yol, herhangi bir dosya adı. Aracınızdan engellediğiniz şeyi yapmasını isteyin ve bunun reddedildiğini izleyin. Hiçbir şey yayınlanmaz ve başka hiç kimse etkilenmez. [Bir politikayı test et](/tr/policies/test) kalanını kapsar: izin vermesi gereken yasal durum ve onu kıran girdiler. + +## 3. Bunu yayınla + +```bash +failproofai publish ``` -Üç dosya yazar ve her politikayı önce **yükleyicinin kendi kuralları** ile doğrular — böylece hiçbir zaman yüklenemeyecek bir paket burada başarısız olur ve siz bunu düzeltebilirsiniz: +Nereye yayınlanacağını, ne paketleneceğini ve buna hangi sürümü çağırılacağını çözer ve yalnızca depo hiçbir şey söylemediğinde sorar. Herhangi bir şey yanlışsa bir sürüm oluşturmadan önce durarak sırasıyla: + +1. Politika dosyalarını burada **içerik** yoluyla bulur — `failproofai` içe aktaran ve `customPolicies.add` çağıran dosyalar — dosya adına göre değil, bu nedenle `guards.mjs` bulur ve ilgisiz `policies.mjs` öğesini yoksayar. Alt dizinlere inmez, bu nedenle bir test demeti asla yanlışlıkla taranmaz. +2. `git remote get-url origin` öğesinden depoyu okur, **dosyanızın** dizininde sizin dizininiz yerine ve sürümü belirler. +3. Kimlik bilgilerinizi bulur: `GITHUB_TOKEN`, `GH_TOKEN` veya `gh auth login`. Sürüm-yazma gerekir ve başka hiçbir şey gerekli değildir ve asla yazdırılmaz. +4. Depo zaten var olmadığında oluşturur. Bu, yapıdan önce gerçekleşir, bu nedenle sonraki adımda reddedilen bir paket, içinde hiçbir sürüm olmayan yeni bir depo bırakabilir. +5. Üç varlığı oluşturur ve **yükleyicinin kendi kurallarıyla** doğrular — bir yabancının makinesine neyin yüklenmesine izin verileceğini belirleyen aynı kod — bu nedenle asla yüklenmeyebilecek bir paket burada başarısız olur, burada hala bunu düzeltebilirsiniz. +6. Sürümü oluşturur veya yeniden kullanır ve varlıkları yükler, aynı adla olanları değiştirir. | Dosya | Ne olduğu | | --- | --- | -| `failproofai-pack.json` | Manifest: id, version, effect ve politika başına bir giriş | -| `failproofai-pack.mjs` | Girdiniz, aynen | -| `SHA256SUMS` | ` ` diğer ikisi için | +| `failproofai-pack.json` | Bildirim: id, sürüm, etki ve politika başına bir giriş | +| `failproofai-pack.mjs` | Paketlenmiş girişiniz | +| `SHA256SUMS` | ` ` diğer ikisiniz için | -Yapı zamanında reddedilir: `publisher/name` olmayan bir id, `/` içeren bir politika adı, `alwaysOn` bildiren bir politika, eksik `description`, `category` veya `match`, hiçbir şey kaydetmeyen bir giriş ve yerel dosyaları içe aktaran bir giriş. +Varlık adları sabittir — bir tüketicinin CLI'sinin URL'lerini bunlardan oluşturduğu şeydir, API çağrısı yok ve keşif yok. -## 3. Onları bir sürüme ekleyin +Derleme zamanında reddedildi: `publisher/name` olmayan bir id, `/` içeren bir politika adı, `alwaysOn` bildiren bir politika, eksik `description`, `category` veya `match`, hiçbir şeye kaydolmayan bir giriş ve yerel dosyaları içe aktaran bir giriş. -Sürümü oluşturduğunuz aynı sürümle etiketleyin ve üç dosyayı da sürüm varlıkları olarak ekleyin: +Belirlediği herhangi bir şeyi geçersiz kıl: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -Artık herkes bunu yükleyebilir: +`--id` depo ile farklı olması gereken durumlarda paket id'sini ayarlar, `--tag` sürüm etiketini ayarlar, `--notes` oluşturulan sürüm notlarının yerini alır — `policies show --releases`'in her sürümün sayılarını ve commit'ini okuduğu yer — `--out` varlıkların nereye yazıldığını seçer (varsayılan `dist-pack`) ve `--dry-run` bunları yayınlamadan oluşturur ve kimlik bilgisi gerektirmez. -```bash -failproofai pack add acme/support-agent -``` +Herkes şimdi `failproofai policies add acme/support-agent` komutu ile bunu yükleyebilir. Bir sürümü sabitleme ve birinin sadece bir kısmını alma hakkında [politika paketleri](/tr/policies/packs) bölümüne bakın. + +### Bunu politika hub'ında listele + +GitHub'daki deponuza `failproofai-policies` konusunu ekleyin. Gönderim formu yok ve onay kuyruğu yok: [politika hub'ı](https://befailproof.ai/policy-hub/) tarayıcı sonraki geçişinde depoyu alır. Konu yalnızca onu değerlendirmeye koymaktadır — bunu listeleyen şey, bildirimi kendi `SHA256SUMS` ile doğrulayan ve CLI'nin kullandığı kurallar altında ayrıştıran bir sürümdür; bu tam olarak `failproofai publish` ürettiği şeydir. + +## Sürümün nasıl belirlendiği + +Sürüm, **yayınladığınız commit** — onun kısa sha'sı, on iki karakter: `a1b2c3d4e5f6`. Seçilecek hiçbir şey yok ve artırılacak hiçbir şey yok ve sürüm tam olarak baytların nereden geldiğini adlandırır, bu nedenle aynı kaynağı iki kez yayınlamak aynı sürümü verir. + +Depoların sürümlerinden asla sizin önünüzdeki ağaçtan okunur, bu nedenle yeni bir klon ve hava geçişli bir makine GitHub'a bundan önce ne olduğunu sormadan aynı cevabı hesaplar. + +Sürüm bir commit'i adlandırdığından, bu commit var olmalıdır. Terminal'de, `publish` bunu sizin için yapar: bir depo olmadığında başlatır ve derlenmeden önce değişen politika dosyalarını commit'ler. Bunun yerine **reddeder** — `--version` olarak çıkış yolunu adlandırarak — terminal olmadan çalıştığında (CI koşucuda yapılan bir commit başka hiçbir yerde var olmaz), dosyalar politikalardan farklı olduğunda komut edilmediğinde veya henüz hiçbir commit'lik bir checkout'ta. `HEAD` üzerinde bir etiket sha'yı geçer — birisi `v1.2.0` etiketlendirmişse bu sürümün ne olduğunu söylemiştir. + +Bir sha'nın kendine ait bir sıralaması yoktur, bu nedenle hangi sürümün ilk geldiğini görmek için `failproofai policies show / --releases` kullanın — en yeni en üstte. -Varlık adları sabitlenmiştir — bunlar, bir tüketicinin CLI'sinin URL'lerini oluşturduğu şeydir, API çağrısı olmadan ve keşif olmadan. +## Yeni bir sürüm gönderm -## Yeni bir sürüm göndermek +Değişikliği commit'leyin ve tekrar `failproofai publish` çalıştırın — yeni commit yeni sürümdür. Tüketiciler aynı `failproofai policies add` komutunu çalıştırır. Terminal olmadan veya bir seçim bayrağı ile, seçtikleri alt kümesini tutar ve açtıkları bir politika kapalı kalır; hiçbir bayrak olmadan terminalde seçici, varsayılanlarınız ile önceden işaretlenmiş durumda açılır ve cevapları seçimlerini değiştirir. -Yeni `--version` ile oluşturun, yeni bir sürümü etiketleyin, üç varlığı tekrar ekleyin. Tüketiciler aynı `pack add` komutunu çalıştırır ve seçtikleri alt kümesini tutarlar; kapattıkları bir politika yükseltme sırasında kapalı kalır. +Bir politikanın **adını** değiştirmek kırılan bir değişikliktir: onu kapattığı bir makine artık var olmayan bir adı kapatıyor ve yeni ad, ne olursa olsun `defaultEnabled` söyler. -Bir politikanın **adını** değiştirmek kırıcı bir değişikliktir: kapalı tuttuğu bir makine, artık var olmayan bir adı kapatıyor ve yeni ad, `defaultEnabled` söylenene gelir. +## Kullanıcılarınızın ne güvendiği -## Kullanıcılarınızın güvendiği şey +`SHA256SUMS`, yapıtla aynı sürümde yer alır, bu nedenle baytların yayınladıklarınız olduğunu kanıtlar — siz kim değil. Depoya yazabilen herkez her iki dosyayı yazabilir. Kullanıcılarınızın koruması, yüklediklerinde özet sabitlendikçe, gönderdikleriniz sonra onların altında değişemez. -`SHA256SUMS` yapıyla aynı sürümde yaşadığından, baytların yayınladığınız olanlar olduğunu kanıtlar — kim olduğunuzu değil. Depoyu yazabilen herkes her iki dosyayı da yazabilir. Kullanıcılarınızın koruması, yüklediğinde özeti sabitlenmesidir, böylece gönderdikleriniz daha sonra onların altında değişemez. +Yazma erişimini kontrol ettiğiniz bir depodan yayınlayın ve bir paket sürümünü bir paket yayınlamak gibi ele alın. -Yazma erişimini kontrol ettiğiniz bir depodan yayınlayın ve bir paket sürümünü paket yayınlama gibi işleyin. +Depo da **public** olmalıdır. Yüklemeler, sunacak kimlik bilgisi olmayan anonim HTTPS'dir, bu nedenle mevcut bir özel depo, herhangi bir şey oluşturulmadan veya yüklenmedikten önce reddedilir ve `publish` oluşturduğu bir depo aynı nedenle halka açıktır. `--allow-private` bunu birinin üç varlığı başka bir yolla teslim ettiği biri için geçersiz kılar ve `policies add`'in bunlara ulaşamayacağını açıkça söyler. Yalnızca sürüm önemlidir: yüklemeler `releases/download//` okur ve git ağacınıza asla dokunmaz. ## Uygulamadan önce gözlemleyin -Bir manifest, `"effect": "observe"` bildirebilir. Bu politikalar çalışır ve kararları **kaydedilir ve atılır** — hiçbir şey engellenmez. Yeni bir kuralı herhangi birinin işini kesintiye uğratabilmesinden önce gerçek trafiğe karşı ölçmek için bu yoldur. +Bir bildirim `"effect": "observe"` bildirebilir — `failproofai publish --effect observe` bunu ayarlayan şeydir. Bu politikalar çalışır ve verdiktleri **kaydedilir ve atılır** — hiçbir şey engellenmez. Bu, yeni bir kuralı gerçek trafiğe karşı ölçmenin yolu, herkesin çalışmasını kesintiye uğratmadan önce. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/tr/policies/rollback.mdx b/docs/tr/policies/rollback.mdx index 366a3651..7c4319c8 100644 --- a/docs/tr/policies/rollback.mdx +++ b/docs/tr/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "Geri Alma" -description: "Bir dağıtım geçerli ajan çalışmasını aksattığında bilinen bir politika dağıtımını geri yükleyin." +title: "Sürümler ve geri alma" +description: "Her yayın değişmez bir sürümdür, bu nedenle geçerli agent çalışmasını kesintiye uğratan bir dağıtım, son iyi sürümün yeniden dağıtılmasıyla geri alınır." icon: "rotate-ccw" --- -Geri alma, dağıtılan sürümü değiştirir veya bir politika atamasını kaldırır; olayı açıklayan karar geçmişini silmez. +Yayınlanan bir policy sürümü asla değişmez. Bir policy düzenlemesi ve yeniden yayınlanması yeni bir sürüm oluşturur; zaten makinelerde olan sürümü asla yeniden yazmaz. İşte geri almanın güvenli olmasının nedeni: son iyi sürüm hala tam olarak orada duruyor ve geri alma, ne gitmişse ona dair karar geçmişini silmez. -## Bir makineyi geri alın +## Bir sürümü bulma - 1. **Admin → enforcement** bölümüne gidin, etkilenen makineyi genişletin ve son bilinen iyi politika setini tanımlayın. - 2. **edit** seçeneğini seçin, bu sürümleri ve etkileri geri yükleyin ve yeni dağıtımı uygulayın. - 3. Makine check-in için bekleyin, ardından bildirilen dağıtımı doğrulayın. - 4. **Observe → policy** bölümünü açın ve geçerli çalışmanın artık engellenmediğini doğrulamak için etkilenen oturumları kontrol edin. + **Admin → policy editor** sayfasına gidin ve bir policy'nin sürümlerini karşılaştırmak veya birini devre dışı bırakmak için **library** sayfasını açın. + + + ```bash + fp policies list # her policy sürümü + fp policies show # bir sürüm, kaynak kodu ile birlikte + ``` + + +## Bir makineyi geri alma + + + + 1. **Admin → enforcement** sayfasına gidin, etkilenen makineyi genişletin ve son bilinen iyi policy setini belirleyin. + 2. **edit** sayfasını seçin, bu sürümleri ve etkileri geri yükleyin ve yeni dağıtımı uygulayın. + 3. Makinenin check-in'i için bekleyin, sonra bildirilen dağıtımı doğrulayın. + 4. **Observe → policy** sayfasını açın ve geçerli çalışmanın artık engellenmediğini onaylamak için etkilenen oturumları kontrol edin. - Cloud dağıtımı geri alma, bir dashboard iş akışıdır. Düzeltilmiş dağıtımın makineye ulaştığını doğrulamak için yerel durumu kullanın: + Bir makineye yapılan her dağıtım numaralı bir generasyondur. Listeleyin, sonra birini geri yükleyin: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` yerleşik, özel ve kural politikalarını bir yerel oturum için duraklatır. Cloud tarafından yönetilen politikaları duraklatmaz, bu nedenle kötü bir Cloud dağıtımı için bir geçici çözüm değildir. + `rollback` sayacı geri sarmak yerine eski seti taşıyan yeni bir generasyon oluşturur, bu nedenle geçmiş sadece eklenmeye devam eder ve devre dışı bırakılan veya silinen bir policy'yi adlandıran generasyonu reddeder. `policies:write` izni olan oturum açmış bir oturuma ihtiyaç duyar. `fp fleet diff ` makine uygulanırken amaçlanan şeyi gösterir — makine bir sonraki kez anket yapana kadar `behind` olarak okunur — ve makinenin kendisinde `failproofai policies` çalıştırılan dağıtımı listeler. -## Geri almak ne zaman gerekli +## Bir policy'yi her makineden çıkarma + +```bash +fp policies disable # bunu taşıyan her dağıtımdan kaldır +fp policies enable # geri ekle +``` + +Her biri etkilediği her dağıtımda yeni bir generasyon oluşturur. Bu generasyonlardan birini geri almak, bir `disable` işlemini geri almanın yolu değildir — `rollback` devre dışı bırakılan bir policy'yi adlandıran generasyonu reddeder ve disable işleminden önceki her generasyon bu policy'yi adlandırır. `fp policies enable` geri dönüş yoludur ve sırasıyla kendi generasyonunu oluşturur. + +## Bir pack'i geri alma + +Bir pack yüklendiğiniz sürüme sabitlenmiştir, bu nedenle geri almak daha önceki bir sürümü yüklemek anlamına gelir: + +```bash +failproofai policies show FailproofAI/policies --releases # yayınladığı her sürüm ve burada hangisi olduğu +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # o sürümü sabitlenmiş şekilde kullan +``` + +Terminal olmadan veya `--policy`, `--category` veya `--all` ile, yeniden ekleme seçtiğiniz alt kümeyi tutar. Terminal ile hiçbiri olmadan, seçici yazarın varsayılanları ile önceden işaretli olarak açılır ve işaretledikleriniz seçiminizi değiştirir — bu nedenle sahip olduğunuz şeyleri yeniden işaretleyin. + +## Ne zaman geri alınır? -- Bir politika beklenen bir üretim işlemini engeller. -- Eşleştirme hacmi, gözlenen dağıtımın öngördüğünden materyal olarak daha yüksek. -- Bir politika, bir integrasyon tarafından sağlanmayan alanlara bağlıdır. -- Yeni bir sürüm, amaçlanan hata modunun dışında davranışı değiştirir. +- Bir policy beklenen bir üretim eylemini engeller. +- Uyuşturma hacmi gözlenen dağıtımın tahmin ettiğinden önemli ölçüde daha yüksektir. +- Bir policy, entegrasyonun sağlamadığı alanlara bağlıdır. +- Yeni bir sürüm amaçlanan hata modunun dışında davranışı değiştirir. -Geri aldıktan sonra etkilenen oturumları açın ve yanlış pozitife neden olan koşulu tanımlayın. Yeni bir sürüm oluşturun, hem güvensiz hem de yasal durumları test edin, ardından gözlem aşamasını tekrarlayın. +Geri aldıktan sonra, etkilenen oturumları açın ve yanlış pozitifin arkasındaki koşulu bulun. Yeni bir sürüm yayınlayın, [test](/tr/policies/test) hem güvenli olmayan hem de meşru durumu test edin ve zorunlu kılmadan önce tekrar gözlemleyin. - Uygulamayı duraklatmak bir olay sırasında uygun olabilir, ancak bu kapsam içindeki her etkin politika için açığı genişletir. Mümkün olduğunda belirli politika sürümünü geri almayı tercih edin. + `failproofai config --pause` yerel policies'i bir oturum için askıya alır ve asla Cloud tarafından yönetilenleri askıya almaz, bu nedenle kötü bir Cloud dağıtımından çıkış yolu değildir. Durdurma ayrıca kapsamındaki her policy için maruziyeti genişletir; yanlış davranan tek sürümü geri almayı tercih edin. \ No newline at end of file diff --git a/docs/tr/policies/test.mdx b/docs/tr/policies/test.mdx new file mode 100644 index 00000000..7c8ffbc3 --- /dev/null +++ b/docs/tr/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "Bir politikayı test edin" +description: "Sahip olduğunuz trafiğe karşı bir taslağı geriye dönük test edin ve herhangi bir makine onu uygulamadan önce, istediğinizi durdurduğunu ve izin vermesi gerekenlere izin verdiğini kanıtlayın." +icon: "flask-conical" +--- + +Her politikayı iki şekilde test edin: ajanlarınızın halihazırda ürettiği trafiğe karşı ve geçmesi gereken meşru bir işleme karşı. Yalnızca güvenli olmayan durumu görmüş bir politika test edilmemiştir. + +## Taslağı geriye dönük olarak test edin + + + + Politika editörü, taslağı yayımlamadan önce aracınızın zaten yaptığı çağrılara karşı yeniden oynatır. + + 1. **Admin → policy editor** altında taslağı açın. Editör, JavaScript olarak ayrıştırıldığını doğrular. + 2. **backtest** bölümünde, yeniden oynatılacak ajanları ve zaman penceresini seçin — varsayılan olarak **her ajan** ve **30d** — ve son filtreyi **her şey**te bırakın, sürece daraltmak istemeseniz. + 3. **run backtest** seçeneğini belirleyin. + + ![JavaScript olarak ayrıştırılan bir taslağın altındaki backtest paneli, üç filtresine ve run backtest işlemine sahip, yayımla sürümün üzerinde.](/images/dashboard/policy-backtest.png) + + Sonuç, taslağın bu çağrılara ne yapacağı olacaktır — kaç tane **çalışan** çağrıyı kesmesi gerektiği dahil. Bunlar, herhangi bir ajan onlarla karşılaşmadan önce bulunan yanlış pozitiflerdir: taslağı sıkılaştırın ve o sayı kabul edebileceğiniz bir sayı olana kadar tekrar çalıştırın. + + + Geriye dönük test, bir dashboard özelliğidir. Bir terminalden, bunun yerine aşağıda açıkladığınız olaylara karşı politikayı çalıştırın. + + + +## Açıkladığınız bir olaya karşı çalıştırın + +`fp policies test`, makinenizde bir politika dosyasını sentetik bir olay üzerinde çalıştırır ve kararı kontrol eder. Hiçbir şey yayımlanmaz ve Cloud'a hiçbir şey ulaşmaz: + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +Olayı `--event`, `--tool`, `--command` ve `--file` ile şekillendirin. Politikanın kendi `match` filtresi hala geçerlidir, bu nedenle açıkladığınız olayı kapsamamış bir politika, karar yerine `skipped` bildirir — genellikle `match` değerinin amaçladığınızdan daha dar olduğunun bir işaretidir. + +## Bir makinede çalıştırın + +Sonra, kendi makinenizde kendi ajanınıza karşı gerçekten uygulamaya koyun: + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +İlk komut dosyayı doğrular ve yükler; ikincisi, burada uygulamaya konulan her şeyin yanında yüklü olduğunu doğrular. Ajantan politikanın durdurduğu şeyi yapmasını isteyin ve reddedildiğini izleyin, sonra meşru sürümü yapın ve geçişini izleyin. Başka kimse etkilenmez. + +Cloud'a bağlı bir makinede, **Observe → policy** altında her iki kararı da kontrol edin: politika adına göre filtreleyin, ardından eşleştirdiği araç girişini ve döndürdüğü nedeni doğrulamak için her bağlantılı oturumu açın. + +## Neyin kırıldığını test edin + +Yükleme, eksik dosyayı, sözdizimi hatasını, çözümlenemeyen ithalatı, üst düzey istisnayı veya yüklenmesi sırasında zaman aşımına uğrayan bir modülü reddeder — bu nedenle dosyaya veya ithalatı yapılan her şeyde bir değişiklik yapıldıktan sonra yeniden çalıştırın. Uygulamaya koyma zamanında aynı bozuk dosya kaydedilir ve **atlanır**, böylece diğer her politika çalışmaya devam eder: üretim günlüklerindeki yükleme uyarısını kayıp uygulamaya koyma olarak değerlendirin. Kural dosyaları yükleme komutu olmadan yüklenir, bu nedenle CI'de açık bir `failproofai policies --install --custom ` adımı tutun — bozuk bir politikada derlemede başarısız olandır. + +Daha sonra ajanların gerçekten gönderdiklerini verin, yalnızca beklediğiniz girişi değil: eksik alanlar, `Write` ve `Edit` gibi alternatif araç adları, Windows yolları, yanlış biçimlendirilmiş giriş. Her yolda kasıtlı bir `allow`, `instruct` veya `deny` döndürün, işlevi deterministik tutun ve tüm dış çağrıları kısa bir zaman aşımı ile sınırlayın. + +## Daha sonra yayımla ve gözlemle + +Geriye dönük test, politikanın sahip olduğu trafiğe ne yapacağını gösterir; görmediğiniz trafiğin ne yapacağını gösteremez. Editörde **publish version** seçeneğini seçin (veya `fp policies publish` çalıştırın), ardından ilk olarak **observe** modunda [dağıtın](/tr/policies/deploy) — verdikleri kararlar kaydedilir ve hiçbir şey engellenmez — ve eşleştirmeleri güvenli olmayan işlemleri geçerli olanlardan ayırdığında uygulamaya koyun. \ No newline at end of file diff --git a/docs/tr/reference/cloud-cli.mdx b/docs/tr/reference/cloud-cli.mdx index fa491b25..6794be2b 100644 --- a/docs/tr/reference/cloud-cli.mdx +++ b/docs/tr/reference/cloud-cli.mdx @@ -1,26 +1,26 @@ --- title: "Failproof Cloud CLI" -description: "Failproof AI Cloud'u fp ile sorgulamak ve yönetmek için kapsamlı referans." +description: "Failproof AI Cloud'u fp ile sorgulamak ve yönetmek için tam referans." icon: "cloud-cog" --- -`fp` komutunu kullanarak Cloud telemetrisi inceleyebilir, bulut tarafından yönetilen yaptırımları (ilkeler, fleet dağıtımları, koruma kararları) yönetebilir ve denetim, bulgular, sorunlar, uyarılar, anahtarlar, kullanıcılar, sorgular ve ayarları yönetebilirsiniz. Yerel hook'lar, ilkeler, yakalama ve makine kaydı için [`failproofai`](/tr/reference/failproof-cli) komutunu kullanın. +Bulut telemetrisini incelemek, bulut tarafından yönetilen uygulamayı (ilkeler, filo dağıtımları, koruma raya kararları) yönetmek ve denetimler, bulgular, sorunlar, uyarılar, anahtarlar, kullanıcılar, sorgular ve ayarları yönetmek için `fp` kullanın. Yerel kancalar, ilkeler, yakalama ve makine kaydı için [`failproofai`](/tr/reference/failproof-cli) kullanın. -Yayımlanmış Cloud CLI'yi izole bir araç olarak yükleyin: +Yayınlanan Bulut CLI'yi yalıtılmış bir araç olarak kurun: ```bash uv tool install fp-cloud-cli fp version ``` -## Oturum aç +## Oturum açın ```bash fp login fp whoami ``` -## Söz dizimi +## Sözdizimi ```text fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] @@ -32,16 +32,16 @@ Genel seçenekler komuttan önce gelmelidir: fp --json sessions --since 24h ``` -Terminal yardımı için `fp COMMAND --help` veya `fp COMMAND SUBCOMMAND --help` komutlarını çalıştırın. +Terminal yardımı için `fp COMMAND --help` veya `fp COMMAND SUBCOMMAND --help` çalıştırın. ## CLI komutları -### Kimlik doğrulama +### Kimlik Doğrulama | Komut | Amaç | Seçenekler | | --- | --- | --- | -| `fp login` | E-posta yoluyla gelen tek kullanımlık koduyla oturum açın ve bir kuruluş seçin. | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | Kaydedilen kullanıcı oturumunu iptal edin ve silin. | — | +| `fp login` | E-posta gönderilen tek kullanımlık kod ile oturum açın ve bir kuruluş seçin. | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | Kaydedilen kullanıcı oturumunu iptal edin ve kaldırın. | — | | `fp whoami` | Mevcut kimliği, kimlik doğrulama modunu, kuruluşu ve izinleri gösterin. | — | | `fp version` | Yüklü CLI sürümünü gösterin. | — | | `fp help` | Üst düzey komut yardımını gösterin. | — | @@ -51,29 +51,29 @@ fp login --email you@example.com --org reliability-team fp whoami ``` -### Olaylar +### Etkinlikler ```text fp events [OPTIONS] ``` -Ayrı ayrı ajan olaylarını listeler. Varsayılan hafif akış ham yükleri hariç tutar; `--full` seçeneğini yalnızca sınırlı bir araştırma için kullanın. +Bireysel aracı etkinliklerini listeler. Varsayılan hafif akış ham yükleri hariç tutar; `--full` seçeneğini yalnızca sınırlı bir soruşturma için kullanın. | Seçenek | Açıklama | | --- | --- | -| `--limit`, `-n ` | En fazla toplam satır. Varsayılan: `50`. | +| `--limit`, `-n ` | Maksimum toplam satır. Varsayılan: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` veya `7d`. | | `--from ` / `--to ` | ISO 8601 UTC aralığı; `--since` seçeneğini geçersiz kılar. | | `--env ` | Ortam filtresi; değerleri tekrarlayın veya virgülle ayırın. | -| `--event-type ` | Olay türü filtresi; tekrarlayın veya virgülle ayırın. | -| `--agent-id ` | Ajan filtresi; tekrarlayın veya virgülle ayırın. | +| `--event-type ` | Etkinlik türü filtresi; tekrarlayın veya virgülle ayırın. | +| `--agent-id ` | Aracı filtresi; tekrarlayın veya virgülle ayırın. | | `--session-id ` | Oturum filtresi; tekrarlayın veya virgülle ayırın. | | `--search ` | Yük metni araması; tekrarlanabilir, herhangi bir terim eşleşir. | | `--order asc\|desc` | Zaman sırası. Varsayılan: en yeni ilk. | -| `--all` | `--limit` değerine kadar otomatik sayfalama. | -| `--cursor ` | Donuk imleçten devam edin. | -| `--page-size ` | `--all` seçeneğiyle istek başına satırlar; maksimum `200`. | -| `--full` | Daha ağır olay uç noktası aracılığıyla ham yükleri dahil edin. | +| `--all` | `--limit` seçeneğine kadar otomatik sayfalandırma. | +| `--cursor ` | Opak imleçten devam edin. | +| `--page-size ` | `--all` ile istek başına satırlar; maksimum `200`. | +| `--full` | Daha ağır etkinlik uç noktası aracılığıyla ham yükleri dahil edin. | | `--fields ` | Yalnızca seçili alanları döndürün; `payload` istemek tam modu etkinleştirir. | ```bash @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` **`--limit` değerine kadar** sayfalandırır, varsayılan olarak **50**'dir — bu nedenle `--all` tek başına 50 satırda durur. Erken durduğunda, yanıt `next_cursor` içerir; `"next_cursor": null` akışın gerçekten tükendiği anlamına gelir. + `--all` **`--limit` seçeneğine kadar** sayfalandırır; varsayılan değeri **50**'dir — bu nedenle kendi başına `--all` 50 satırda durur. Erken durduğunda yanıt devam etmek için bir `next_cursor` taşır; `"next_cursor": null` akışın gerçekten tükenmişse anlamına gelir. ### Oturumlar @@ -93,19 +93,19 @@ fp sessions [OPTIONS] | Seçenek | Açıklama | | --- | --- | -| `--limit`, `-n ` | En fazla toplam satır. Varsayılan: `50`. | +| `--limit`, `-n ` | Maksimum toplam satır. Varsayılan: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` veya `7d`. | | `--from ` / `--to ` | ISO 8601 UTC aralığı; `--since` seçeneğini geçersiz kılar. | | `--env ` | Ortam filtresi; tekrarlayın veya virgülle ayırın. | | `--status ` | `done`, `error` veya `timeout`; tekrarlayın veya virgülle ayırın. | -| `--agent-id ` | Seçili herhangi bir ajanı içeren oturumları eşleştirin. | +| `--agent-id ` | Seçili aracıları içeren oturumları eşleştirin. | | `--session-id ` | Oturum filtresi; tekrarlayın veya virgülle ayırın. | -| `--all` | `--limit` değerine kadar otomatik sayfalama. | -| `--cursor ` | Donuk imleçten devam edin. | -| `--page-size ` | `--all` seçeneğiyle istek başına satırlar; maksimum `200`. | +| `--all` | `--limit` seçeneğine kadar otomatik sayfalandırma. | +| `--cursor ` | Opak imleçten devam edin. | +| `--page-size ` | `--all` ile istek başına satırlar; maksimum `200`. | | `--fields ` | Yalnızca seçili alanları döndürün. | -| `--full-ids` | Terminal çıktısında oturum kimliklerini kısaltmayın. | -| `--agents` | Çok ajanı oturumlar için ajan rosterini genişletin. | +| `--full-ids` | Terminal çıkışında oturum kimliklerini kısaltmayın. | +| `--agents` | Çok aracılı oturumlar için aracı rosterini genişletin. | ### Değerlendirmeler @@ -115,15 +115,15 @@ fp evals [OPTIONS] | Seçenek | Açıklama | | --- | --- | -| `--aggregate` | Ayrı ayrı değerlendirmeler yerine toplam ve puan başına istatistikleri gösterin. | -| `--limit`, `-n ` | En fazla liste satırı. Varsayılan: `50`. | +| `--aggregate` | Bireysel değerlendirmeler yerine toplamları ve puan başına istatistikleri gösterin. | +| `--limit`, `-n ` | Maksimum liste satırı. Varsayılan: `50`. | | `--since`, `--from`, `--to` | Zaman aralığını seçin. | -| `--env`, `--status`, `--agent-id`, `--session-id` | Her filtre için bir tam değere daraltın. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Filtre başına tek bir tam değer olacak şekilde daraltın. | | `--score KEY:MIN..MAX` | Puan aralığı; tekrarlanabilir ve tüm aralıklar eşleşmelidir. | -| `--all`, `--cursor`, `--page-size` | Liste sayfalamayı kontrol edin. | +| `--all`, `--cursor`, `--page-size` | Liste sayfalandırmasını kontrol edin. | | `--fields ` | Yalnızca seçili alanları döndürün. | | `--full-ids` | Tam oturum kimliklerini gösterin. | -| `--scores-full` | Terminal çıktısında her puanı gösterin. | +| `--scores-full` | Terminal çıkışında her puanı gösterin. | ### Hatalar @@ -133,13 +133,13 @@ fp errors [OPTIONS] | Seçenek | Açıklama | | --- | --- | -| `--aggregate` | Satırları listelemek yerine eşleşen hataları özetleyin. | -| `--limit`, `-n ` | En fazla liste satırı. Varsayılan: `50`. | +| `--aggregate` | Satırları listeleme yerine eşleşen hataları özetleyin. | +| `--limit`, `-n ` | Maksimum liste satırı. Varsayılan: `50`. | | `--since`, `--from`, `--to` | Zaman aralığını seçin. | | `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Hata popülasyonunu daraltın. | -| `--search ` | Yük metni arayın; tekrarlanabilir. | +| `--search ` | Yük metni araması; tekrarlanabilir. | | `--order asc\|desc` | Zaman sırası. | -| `--all`, `--cursor`, `--page-size` | Liste sayfalamayı kontrol edin. | +| `--all`, `--cursor`, `--page-size` | Liste sayfalandırmasını kontrol edin. | | `--fields ` | Yalnızca seçili alanları döndürün. | | `--full-ids` | Tam oturum kimliklerini gösterin. | @@ -147,13 +147,13 @@ fp errors [OPTIONS] | Komut | Amaç | | --- | --- | -| `fp usage` | Mevcut ölçüm penceresinin kullanımını gösterin. | +| `fp usage` | Geçerli ölçüm penceresi için kullanımı gösterin. | | `fp list envs` | Gözlemlenen ortamları listeleyin. | -| `fp list agents` | Gözlemlenen ajan kimliklerini listeleyin. | -| `fp list event_types` | Olay türlerini listeleyin. | +| `fp list agents` | Gözlemlenen aracı kimliklerini listeleyin. | +| `fp list event_types` | Etkinlik türlerini listeleyin. | | `fp list score_filters` | Değerlendirme puanı anahtarlarını listeleyin. | | `fp list models` | Model adlarını listeleyin. | -| `fp list hooks` | Hook adlarını listeleyin. | +| `fp list hooks` | Kanca adlarını listeleyin. | | `fp list tools` | Araç adlarını listeleyin. | | `fp list error_types` | Hata türlerini listeleyin. | @@ -162,22 +162,22 @@ fp errors [OPTIONS] | Komut | Amaç | | --- | --- | | `fp orgs list` | Erişilebilir kuruluşları listeleyin. | -| `fp orgs switch [SLUG]` | Etkin bir kuruluşu kaydedin; eksik olduğunda sorar. | +| `fp orgs switch [SLUG]` | Etkin bir kuruluşu kaydedin; atlandığında sor. | | `fp orgs current` | Etkin kuruluşu gösterin. | -| `fp orgs perms` | Etkin kuruluşta izinlerinizi gösterin. | +| `fp orgs perms` | Etkin kuruluştaki izinlerinizi gösterin. | ### API anahtarları | Komut | Amaç | Seçenekler | | --- | --- | --- | | `fp keys list` | Kuruluş anahtarlarını listeleyin. | `--show-id`; `--fields ` | -| `fp keys show NAME` | Bir anahtarı ve izinlerini gösterin. | — | +| `fp keys show NAME` | Bir anahtarı ve onun yetkilerini gösterin. | — | | `fp keys create NAME` | Bir anahtar oluşturun ve sırrını bir kez ortaya çıkarın. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | İzin setini değiştirin veya izinleri ayarlayın. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | Sırrı döndürün ve yenisini bir kez ortaya çıkarın. | `--yes`, `-y` | +| `fp keys update NAME` | İzin setini değiştirin veya yetkileri ayarlayın. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | Sırrı döndürün ve değiştirmeyi bir kez ortaya çıkarın. | `--yes`, `-y` | | `fp keys disable NAME` | Bir anahtarı kalıcı olarak iptal edin. | `--yes`, `-y` | -İzin belirteçleri `resource:action` biçimini kullanır; örneğin `events:add`. `--add` seçeneğini tekrarlayın, virgülle ayırın veya `events:read.add` gibi noktalı eylemleri kullanın. +İzin belirteçleri `resource:action` biçimini kullanır; örneğin `events:add`. `--add` seçeneğini tekrarlayın, belirteçleri virgülle ayırın veya `events:read.add` gibi noktalı eylemleri kullanın. ### Sorgular @@ -186,9 +186,9 @@ fp errors [OPTIONS] | `fp query list` | Kaydedilmiş sorguları listeleyin. | `--show-id`; `--fields ` | | `fp query show NAME` | Bir sorguyu gösterin. | — | | `fp query create NAME` | Bir sorguyu kaydedin. | `--sql `; `--description` | -| `fp query update NAME` | Bir sorguyu güncelleyin veya yeniden adlandırın. | `--name`; `--sql`; `--description`; `--yes`, `-y` | -| `fp query delete NAME` | Kaydedilmiş bir sorguyu silin. | `--yes`, `-y` | -| `fp query run [NAME]` | Kaydedilmiş bir sorguyu veya geçici SQL'i çalıştırın. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query update NAME` | Sorguyu güncelleyin veya yeniden adlandırın. | `--name`; `--sql`; `--description`; `--yes`, `-y` | +| `fp query delete NAME` | Kaydedilmiş sorguyu silin. | `--yes`, `-y` | +| `fp query run [NAME]` | Kaydedilmiş sorguyu veya ad-hoc SQL'i çalıştırın. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | | `fp query schema [TABLE]` | Sorgulanabilir tabloları listeleyin veya bir tabloyu inceleyin. | — | ### Kullanıcılar @@ -196,9 +196,9 @@ fp errors [OPTIONS] | Komut | Amaç | Seçenekler | | --- | --- | --- | | `fp users list` | Kuruluş üyelerini listeleyin. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | Bir üyeyi ve izinlerini gösterin. | — | -| `fp users create EMAIL` | Bir üyeyi ekleyin. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | Bir üyenin izinlerini değiştirin. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users show EMAIL` | Üyeyi ve yetkilerini gösterin. | — | +| `fp users create EMAIL` | Bir üye ekleyin. | `--permission-set`; `--add`; `--remove` | +| `fp users update EMAIL` | Üyenin yetkilerini değiştirin. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | | `fp users disable EMAIL` | Oturum açmayı devre dışı bırakın. | `--yes`, `-y` | | `fp users enable EMAIL` | Oturum açmayı yeniden etkinleştirin. | `--yes`, `-y` | @@ -206,9 +206,9 @@ fp errors [OPTIONS] | Komut | Amaç | Seçenekler | | --- | --- | --- | -| `fp settings list` | Kuruluş ayarlarını ve mevcut değerleri listeleyin. | — | +| `fp settings list` | Kuruluş ayarlarını ve geçerli değerleri listeleyin. | — | | `fp settings schema` | Kabul edilen değerleri ve açıklamaları gösterin. | — | -| `fp settings set KEY` | Mevcut bir ayarı değiştirin. | `--value`, `--json-value`, `--file` seçeneklerinden biri; isteğe bağlı `--yes`, `-y` | +| `fp settings set KEY` | Mevcut bir ayarı değiştirin. | `--value`, `--json-value`, `--file` seçeneklerinden tam biri; isteğe bağlı `--yes`, `-y` | ### Uyarılar @@ -217,34 +217,34 @@ fp errors [OPTIONS] | `fp alerts list` | Uyarı kurallarını listeleyin. | `--show-id` | | `fp alerts show NAME` | Bir uyarıyı gösterin. | — | | `fp alerts create NAME` | Bir uyarı oluşturun. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | Bir uyarıyı güncelleyin veya yeniden adlandırın. | oluşturma seçenekleri artı `--name`; `--yes`, `-y` | -| `fp alerts delete NAME` | Bir uyarıyı silin. | `--yes`, `-y` | -| `fp alerts test NAME` | Test bildirimini gönderin. | `--channels`; `--yes`, `-y` | +| `fp alerts update NAME` | Uyarıyı güncelleyin veya yeniden adlandırın. | create seçenekleri artı `--name`; `--yes`, `-y` | +| `fp alerts delete NAME` | Uyarıyı silin. | `--yes`, `-y` | +| `fp alerts test NAME` | Test bildirimi gönderin. | `--channels`; `--yes`, `-y` | -Uyarı önem dereceleri `info`, `warning` ve `critical`'dir. Tetik türleri `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` ve `per_event`'dir. Değerlendirme aralıkları 30 ile 86.400 saniye arasında olmalıdır. +Uyarı önem dereceleri `info`, `warning` ve `critical` seçenekleridir. Tetikleyici türleri `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` ve `per_event` seçenekleridir. Değerlendirme aralıkları 30 ile 86.400 saniye arasında olmalıdır. -### Denetim +### Denetimler | Komut | Amaç | Seçenekler | | --- | --- | --- | | `fp audits list` | Denetimleri listeleyin. | `--enabled-only`; `--show-id` | | `fp audits show NAME` | Bir denetim tanımını ve durumunu gösterin. | — | -| `fp audits create NAME` | Bir denetim oluşturun ve ilk çalışmasını hemen sıraya alın. | [Oluşturma seçeneklerine](#audit-create-options) bakın. | -| `fp audits edit NAME` | Denetim ayarlarını değiştirirken belirtilmeyen değerleri koruyun. | oluşturma tanım seçenekleri; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | Bir denetimi, bulgularını ve çalışma geçmişini silin. | `--yes`, `-y` | -| `fp audits run NAME` | Manuel çalışma sırası alın. | — | +| `fp audits create NAME` | Bir denetim oluşturun ve ilk çalıştırmasını hemen sıraya alın. | Bkz. [create seçenekleri](#audit-create-options). | +| `fp audits edit NAME` | Belirtilmemiş değerleri korurken denetim ayarlarını değiştirin. | create tanımı seçenekleri; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | Denetimi, bulguları ve çalışma geçmişini silin. | `--yes`, `-y` | +| `fp audits run NAME` | Manual çalıştırmayı sıraya alın. | — | | `fp audits runs NAME` | Çalışma geçmişini listeleyin. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | Özet ve referans URL alma durumunu gösterin. | — | -| `fp audits context-set NAME` | Özet veya referans URL'lerini değiştirin. | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | Referans URL'lerini yeniden alın. | — | +| `fp audits context-show NAME` | Özeti ve başvuru URL'si alma durumunu gösterin. | — | +| `fp audits context-set NAME` | Özeti veya başvuru URL'lerini değiştirin. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-refresh NAME` | Başvuru URL'lerini yeniden alın. | — | | `fp audits findings` | Bulguları listeleyin. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | Bir bulguyu ve kanıtını gösterin. | — | -| `fp audits ack FINDING_ID` | Bir bulguyu onaylayın. | `--reason` | -| `fp audits mute FINDING_ID` | Yinelenen bir deseni bastırın. | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | Bir deseni harekete geçirilemez olarak işaretleyin ve bastırın. | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | Bir bulguyu düzeltilenmiş olarak işaretleyin, gelecekte bastırılmayacak. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | Bir bulguyu canlı kuyruğa geri alın ve bastırmayı temizleyin. | — | -| `fp audits assign FINDING_ID` | Bulguyu sahibini ayarlayın. | gerekli `--to ` | +| `fp audits finding FINDING_ID` | Bir bulguyı ve delilini gösterin. | — | +| `fp audits ack FINDING_ID` | Bir bulguyu kabul edin. | `--reason` | +| `fp audits mute FINDING_ID` | Tekrarlayan bir modeli bastırın. | `--reason`; `--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | Bir modeli işlem yapılmayacak şekilde işaretleyin ve bastırın. | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | Bulguyu düzeltildi olarak işaretleyin, gelecekte bastırma olmadan. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | Bulguyu canlı sıraya döndürün ve bastırmayı temizleyin. | — | +| `fp audits assign FINDING_ID` | Bulgu sahibini ayarlayın. | gerekli `--to ` | #### Denetim oluşturma seçenekleri @@ -263,25 +263,25 @@ fp audits create checkout-reliability \ | --- | --- | | `--file ` | Tanımı JSON'a dayandırın veya stdin için `-` kullanın. Açık bayraklar dosya değerlerini geçersiz kılar. | | `--description ` | Başarısızlık sorusunu veya amacını belirtin. | -| `--enabled` / `--disabled` | Zamanlamayı açık veya kapalı başlatın. Varsayılan: etkin. | +| `--enabled` / `--disabled` | Zamanlamayı açık veya kapalı olarak başlatın. Varsayılan: etkin. | | `--schedule-interval-secs ` | `3600`–`604800`. Varsayılan: `86400`. | | `--schedule-anchor ` | ISO 8601 formunda sabit UTC fazı. Varsayılan: sonraki 09:00 UTC. | -| `--window-mode since_last\|fixed` | Son tam analiz edilen pencereden sonra devam edin veya yuvarlak pencereyi tekrarlayan şekilde inceleyin. Varsayılan: `since_last`. | +| `--window-mode since_last\|fixed` | Son tam analiz edilen pencereden sonra devam edin veya bir kayan pencereyi tekrar tekrar inceleyin. Varsayılan: `since_last`. | | `--lookback-window-secs ` | `3600`–`7776000`. Varsayılan: `604800`. | | `--scope ''` | `environments`, `agent_ids` veya diğer desteklenen kapsam alanlarına göre filtreleyin. | | `--ignore-error-type ` | Hata türlerini hariç tutun; tekrarlayın veya virgülle ayırın. | -| `--llm` / `--no-llm` | Ajansal analizi etkinleştirin veya devre dışı bırakın. Varsayılan: etkin. | -| `--top-k ` | `1`–`500` bulguyu koruyun. Varsayılan: `50`. | +| `--llm` / `--no-llm` | Agentic analizi etkinleştirin veya devre dışı bırakın. Varsayılan: etkin. | +| `--top-k ` | `1`–`500` bulguları koruyun. Varsayılan: `50`. | | `--sensitivity low\|medium\|high` | Raporlama duyarlılığını ayarlayın. Varsayılan: `medium`. | | `--channels ''` | Bildirim kanalı dizisi. | | `--text ` | Satır içi özet, maksimum 8.192 karakter. | -| `--text-file ` | Özeti bir dosyadan okuyun; `--text` ile birbirini dışlar. | -| `--url ` | Genel HTTPS referansı ekleyin; beş kata kadar tekrarlayın. | +| `--text-file ` | Özeti bir dosyadan okuyun; `--text` ile karşılıklı olarak münhasır. | +| `--url ` | Genel HTTPS başvurusu ekleyin; beş kata kadar tekrarlayın. | -İlk çalışmanın buna ihtiyaç duyduğu zaman oluşturma sırasında bağlam ekleyin. Oluşturma, tanımı ve bağlamı sıraya alınan çalışma başlamadan önce birlikte taahhüt eder. +Oluşturma sırasında ilk çalıştırmanın bağlama ihtiyacı olduğunda bağlamı dahil edin. Oluşturma tanımı ve bağlamı sıralanan çalıştırma başlamadan önce birlikte kaydeder. - `fp audits run` asenkrondur. Bulguları okumadan önce en son çalışma başarı veya başarısız olana kadar `fp audits runs NAME` sorgulamasını yapın. + `fp audits run` asenkrondur. Bulguları okumadan önce en son çalıştırmanın başarılı veya başarısız olmasını görmek için `fp audits runs NAME` seçeneğini yoklayın. ### Sorunlar @@ -290,19 +290,19 @@ fp audits create checkout-reliability \ | --- | --- | --- | | `fp issues list` | Sorunları listeleyin. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | | `fp issues count` | Açık veya seçili sorun durumlarını sayın. | `--state` | -| `fp issues show INCIDENT_ID` | Sorun ayrıntılarını, yorumları, abone olunması ve etkinliği gösterin. | — | -| `fp issues open` | Manuel veya uyarı bağlantılı bir sorun açın. | gerekli `--summary`; isteğe bağlı `--title`, `--alert-id`, `--severity` | -| `fp issues ack INCIDENT_ID` | Bir sorunu onaylayın. | — | -| `fp issues assign INCIDENT_ID` | Atanmışları değiştirin; temizlemek için seçeneği çıkarın. | tekrarlanabilir `--assignee` | -| `fp issues resolve INCIDENT_ID` | Bir sorunu çözün. | `--yes`, `-y` | +| `fp issues show INCIDENT_ID` | Sorun ayrıntılarını, yorumları, abone adaylarını ve etkinliği gösterin. | — | +| `fp issues open` | Manual veya uyarıya bağlı sorunu açın. | gerekli `--summary`; isteğe bağlı `--title`, `--alert-id`, `--severity` | +| `fp issues ack INCIDENT_ID` | Sorunu kabul edin. | — | +| `fp issues assign INCIDENT_ID` | Atanan kişileri değiştirin; temizlemek için seçeneği atlayın. | tekrarlanabilir `--assignee` | +| `fp issues resolve INCIDENT_ID` | Sorunu çözün. | `--yes`, `-y` | | `fp issues comment-list INCIDENT_ID` | Yorumları listeleyin. | — | -| `fp issues comment-add INCIDENT_ID` | Bir yorum ekleyin. | `--body` veya `--file` seçeneklerinden biri | -| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Bir yorumu silin. | `--yes`, `-y` | +| `fp issues comment-add INCIDENT_ID` | Yorum ekleyin. | `--body`, `--file` seçeneklerinden tam biri | +| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Yorumu silin. | `--yes`, `-y` | | `fp issues subscribers INCIDENT_ID` | Aboneleri listeleyin. | — | -| `fp issues subscribe INCIDENT_ID` | Kendinize veya başka bir operatöre abone olun. | `--email` | +| `fp issues subscribe INCIDENT_ID` | Siz veya başka bir operatörü abone yapın. | `--email` | | `fp issues unsubscribe INCIDENT_ID` | Aboneliği kaldırın. | `--email` | -Geçerli sorun durumları `firing`, `acknowledged` ve `resolved`'dir. Bağımsız sorun önem dereceleri `info`, `warning` ve `critical`'dir. +Geçerli sorun durumları `firing`, `acknowledged` ve `resolved` seçenekleridir. Tek başına sorun önem dereceleri `info`, `warning` ve `critical` seçenekleridir. ### Bulut asistanı @@ -311,70 +311,70 @@ Geçerli sorun durumları `firing`, `acknowledged` ve `resolved`'dir. Bağımsı | `fp agent health` | Asistan kullanılabilirliğini ve yapılandırmasını kontrol edin. | — | | `fp agent models` | Kullanılabilir asistan modellerini listeleyin. | — | | `fp agent chats` | Kaydedilmiş sohbetleri listeleyin. | — | -| `fp agent ask [MESSAGE]` | Bir sohbet başlatın veya devam edin; ileti eksik olduğunda stdin'den okuyun. | `--chat`; `--model`; `--page-context` | -| `fp agent show CHAT_ID` | Kaydedilmiş bir konuşmayı gösterin. | — | -| `fp agent rename CHAT_ID` | Bir konuşmayı yeniden adlandırın. | gerekli `--title` | -| `fp agent delete CHAT_ID` | Bir konuşmayı silin. | `--yes`, `-y` | +| `fp agent ask [MESSAGE]` | Sohbeti başlatın veya devam ettirin; ileti atlandığında stdin'den okuyun. | `--chat`; `--model`; `--page-context` | +| `fp agent show CHAT_ID` | Kaydedilmiş konuşmayı gösterin. | — | +| `fp agent rename CHAT_ID` | Konuşmayı yeniden adlandırın. | gerekli `--title` | +| `fp agent delete CHAT_ID` | Konuşmayı silin. | `--yes`, `-y` | ### İlkeler -Bulut tarafından yönetilen ilke sürümleri. **Yalnızca oturum** — buradaki her komut bir API anahtarı altında `2` seçeneğiyle çıkılır, herhangi bir istekten önce, çünkü bunlar `/v1` içinde kasıtlı olarak yokluğu yazma yollarıdır. +Bulut tarafından yönetilen ilke sürümleri. **Yalnızca oturum** — buradaki her komut bir API anahtarı altında çıkış `2` ile çıkar, herhangi bir istekten önce, çünkü bunlar `/v1`'den kasıtlı olarak kök yazma yollarıdır. | Komut | Amaç | Seçenekler | | --- | --- | --- | | `fp policies list` | İlke sürümlerini listeleyin. | `--json` | -| `fp policies show POLICY_ID` | Bir ilkeyi kaynağıyla gösterin. | — | -| `fp policies publish NAME PATH` | Yerel `.mjs` dosyasından bir sürüm alın. | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | Kaldırıldığı her dağıtıma geri ekleyin, her birinde yeni bir nesil alın. | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | Onu taşıyan her dağıtımdan kaldırın, her birinde yeni bir nesil alın. | `--yes`, `-y` | -| `fp policies delete POLICY_ID` | Bir ilke sürümünü silin. | `--yes`, `-y` | -| `fp policies test PATH` | Bir ilkeyi sentetik bir bağlama karşı yerel olarak çalıştırın. Her ilkenin `match` filtresini uygular, bu nedenle verilen olay/araç içermeyen biri çalıştırılmak yerine `skipped` olarak rapor edilir. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | Asistan ile bir ilke taslağı oluşturun. `policies:write` gerekir. | — | +| `fp policies show POLICY_ID` | Bir ilkeyi kaynak koduyla gösterin. | — | +| `fp policies publish NAME PATH` | Yerel `.mjs`'den bir sürüm oluşturun. | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | Kaldırıldığı her dağıtıma geri ekleyin, her biri üzerinde yeni bir nesil oluşturun. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | Taşıdığı her dağıtımdan kaldırın, her biri üzerinde yeni bir nesil oluşturun. | `--yes`, `-y` | +| `fp policies delete POLICY_ID` | İlke sürümünü silin. | `--yes`, `-y` | +| `fp policies test PATH` | Sentetik bir bağlama karşı yerel olarak bir ilkeyi çalıştırın. Her ilkenin `match` filtresini uygular, bu nedenle verilen etkinlik/aracı kapsamayan bir `skipped` yerine çalıştırılır. | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | Asistan ile bir ilke taslağı yapın. `policies:write` gerektirir. | — | -### Fleet +### Filo -Hangi makinelerin hangi ilkeleri çalıştırdığı. **Yalnızca oturum**, yukarıdakiyle aynı nedenden dolayı. +Hangi makinelerin hangi ilkeleri çalıştırdığı. **Yalnızca oturum**, yukarıda olduğu gibi aynı neden. | Komut | Amaç | Seçenekler | | --- | --- | --- | -| `fp fleet list` | Kayıtlı makineleri ve dağıtım neslini listeleyin. | — | -| `fp fleet show MACHINE_ID` | Bir makinenin şu anda çalıştırdığı ilke seti. | — | -| `fp fleet deploy MACHINE_ID` | **Makinenin tüm ilke setini değiştirir.** Planı yazdırır ve `--json` olmayan etkileşimli terminalde yalnızca sorar. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | Bir makineyi başka bir dağıtımla karşılaştırın. | — | +| `fp fleet list` | Kayıtlı makineleri ve dağıtım nesillerini listeleyin. | — | +| `fp fleet show MACHINE_ID` | Makinenin şu anda çalıştırdığı ilke seti. | — | +| `fp fleet deploy MACHINE_ID` | **Makinenin tamamını ilke setini değiştirir.** Planı yazdırır ve yalnızca `--json` olmadan etkileşimli bir terminalde sorar. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | Bir makineyi başka bir dağıtıma karşı karşılaştırın. | — | | `fp fleet history MACHINE_ID` | Bir makine için geçmiş dağıtımlar. | — | -| `fp fleet rollback MACHINE_ID` | Önceki bir dağıtımı geri yükleyin. | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | Bir makineye okunabilir bir ad verin. | gerekli `--name` | +| `fp fleet rollback MACHINE_ID GENERATION` | Geçmiş bir neslin ilke setini yeniden kurun, yeni bir nesil olarak. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | Makineye okunaklı bir ad verin. | gerekli `--name` | -### Koruma +### Koruma Rayları -Yaptırım gerçekten ne yaptı. **Yalnızca oturum**, yukarıdakiyle aynı nedenden dolayı. +Uygulamanın gerçekten yaptığı şey. **Yalnızca oturum**, yukarıda olduğu gibi aynı neden. | Komut | Amaç | Seçenekler | | --- | --- | --- | -| `fp guardrails summary` | Kapsam, engellenen/değerlendirilen toplamlar, bir reddetme kıvılcım çizgisi ve ilke başına tablo. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | Pencere üzerinde demetlenmiş kararlar, her ilke kaynağında toplandı. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | Kapsama, engellenen/değerlendirilen toplamlar, bir reddet kıvılcım çizgisi ve ilke başına tablo. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Pencere üzerinde zaman demetinde tutulan kararlar, her ilke kaynağında toplanmıştır. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | ## Genel bayraklar | Bayrak | Açıklama | | --- | --- | -| `--json` | Makine tarafından okunabilir JSON yayınlayın. | -| `--base-url ` | Öz barındırılmış veya geliştirme panosunu kullanın. | -| `--org ` | Bu çağırma için bir kuruluş seçin. | -| `--token ` | Kaydedilen kullanıcı oturumu belirtecini geçersiz kılın. | -| `--api-key ` | Otomasyon ile API anahtarı kimlik doğrulaması; asla kaydedilmez. | +| `--json` | Makine tarafından okunabilir JSON yayın. | +| `--base-url ` | Kendi kendine barındırılan veya geliştirme panosunu kullanın. | +| `--org ` | Bu çağrı için bir kuruluş seçin. | +| `--token ` | Kaydedilmiş kullanıcı oturumu belirtecini geçersiz kılın. | +| `--api-key ` | Otomasyon ile kimlik doğrulaması yapın API anahtarı ile; asla kaydedilmez. | | `--timeout ` | HTTP zaman aşımı; pozitif olmalı. Varsayılan: `30`. | -| `--quiet`, `-q` | Stderr'de durum çıktısını bastırın. | -| `--no-color` | Renkli çıktıyı devre dışı bırakın. | +| `--quiet`, `-q` | stderr üzerinde durum çıkışını bastırın. | +| `--no-color` | Renkli çıkışı devre dışı bırakın. | | `--insecure` / `--secure` | TLS sertifikası doğrulamasını devre dışı bırakın veya geri yükleyin. | -| `--version` | Kutusuz sürümü yazdırın ve çıkın. | +| `--version` | Açılmamış sürümü yazdırın ve çıkın. | | `--help`, `-h` | Yardımı gösterin. | -`--api-key` otomasyon için tasarlanmıştır. Oturum açma, kuruluş değiştirme ve asistan komutları kullanıcı oturumu gerektirir. +`--api-key` otomasyon için tasarlanmıştır. Oturum açma, kuruluş değiştirme ve asistan komutları bir kullanıcı oturumu gerektirir. ## Ortam değişkenleri -| Değişken | Eşdeğer veya amaç | +| Değişken | Eşdeğeri veya amacı | | --- | --- | | `FP_DASHBOARD_URL` | `--base-url` | | `FP_ORG` | `--org` | @@ -382,18 +382,18 @@ Yaptırım gerçekten ne yaptı. **Yalnızca oturum**, yukarıdakiyle aynı nede | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | CLI yapılandırma dizinini taşıyın (varsayılan `~/.failproofai/fpcli`). | -| `FP_ANALYTICS_DISABLED` veya `DO_NOT_TRACK` | Anonim CLI analitiğini devre dışı bırakın. | -| `NO_COLOR` | Renkli çıktıyı devre dışı bırakın. | +| `FP_HOME` | CLI yapılandırma dizinini yerleştirin (varsayılan `~/.failproofai/fpcli`). | +| `FP_ANALYTICS_DISABLED` veya `DO_NOT_TRACK` | Anonim CLI analizini devre dışı bırakın. | +| `NO_COLOR` | Renkli çıkışı devre dışı bırakın. | -Açık bayraklar ortam değişkenlerini geçersiz kılar; ortam değişkenleri kaydedilmiş yapılandırmayı geçersiz kılar. API anahtar modunda, `--org` veya `FP_ORG` ile kiracıyı açıkça seçin. +Açık bayraklar ortam değişkenlerini geçersiz kılar, bu da kaydedilmiş yapılandırmayı geçersiz kılar. API anahtarı modunda, kiracıyı `--org` veya `FP_ORG` ile açıkça seçin. - `AGENTEYE_*` yazımı **`fp` tarafından okunmaz** ve hiç okunmadı — CLI `FP_*` (`fp_cli/app.py`) bildirir, bilinmeyen bir değişken bir hata değildir. `AGENTEYE_DASHBOARD_URL` ayarlanması CLI'yi yeniden hedeflemez; yoksayılır ve komut sessizce kaydedilmiş pano yerine çalışır. + `AGENTEYE_*` yazımları `fp` tarafından **okunmaz** ve hiçbir zaman olmamıştır — CLI `FP_*` (`fp_cli/app.py`) değişkenleri bildirir ve bilinmeyen bir değişken bir hatadır. `AGENTEYE_DASHBOARD_URL` ayarlanması CLI'yi yeniden hedeflemez; yoksayılır ve komut sessizce kaydedilmiş panoya karşı çalışır. - `AGENTEYE_HOME` ve `AGENTEYE_ENVIRONMENT` hala mevcuttur, ancak bunlar **toplayıcı ve telemetri SDK'sı**'na aittir, bu CLI'ye değil. + `AGENTEYE_HOME` ve `AGENTEYE_ENVIRONMENT` hâlâ mevcuttur, ancak bu CLI'ye değil **kolektör ve telemetri SDK**'ye aittir. - Yapılandırmayı silen, iptal eden, bastıran, çözen veya değiştiren komutlar varsayılan olarak sorar. `--yes` seçeneğini yalnızca etkin kuruluşu ve hedefi doğruladıktan sonra kullanın. + Silen, iptal eden, bastıran, çözen veya yapılandırmayı değiştiren komutlar varsayılan olarak uyarır. `--yes` seçeneğini yalnızca etkin kuruluşu ve hedefi doğruladıktan sonra kullanın. \ No newline at end of file diff --git a/docs/tr/reference/custom-agents.mdx b/docs/tr/reference/custom-agents.mdx index f288b83b..efd16c42 100644 --- a/docs/tr/reference/custom-agents.mdx +++ b/docs/tr/reference/custom-agents.mdx @@ -1,46 +1,52 @@ --- -title: "Özel ajanlar" -description: "failproofai-sdk için konfigürasyon, olay kataloğu, korelasyon kuralları ve teslimat." +title: "Özel aracılar" +description: "Konfigürasyon, olay kataloğu, korelasyon kuralları ve failproofai-sdk için teslimat." icon: "python" --- -Her ayarın, metodun ve alanın ne yaptığı. İlk kez enstrüman ediyorsanız, kılavuzla başlayın — bu sayfa şeyler aramak içindir. +Her ayarın, metodun ve alanın ne işe yaradığı. İlk kez enstrümantasyon yapıyorsanız, rehberi okuyarak başlayın — bu sayfa referans amaçlıdır. - - Kurun, enstrüman edin, olay metodları, işlenmiş bir örnek ve yaygın sorunlar. + + Kurulum, enstrümantasyon, olay metodları, pratik örnek ve yaygın sorunlar. - - LangChain, CrewAI, LlamaIndex ve Pydantic AI kendilerini tek bir çağrıyla enstrüman ederler. + + LangChain, CrewAI, LlamaIndex ve Pydantic AI kendilerini tek çağrı ile enstrümante ederler. -Python 3.10 veya daha yeni. Çalışma zamanı bağımlılığı yok. +Python 3.10 veya daha yeni. Runtime bağımlılığı yok. -## Kurun +## Kurulum ```bash pip install failproofai-sdk ``` -Paket `failproofai-sdk` olarak yüklenir ve Python'da `failproofai_sdk` olarak içe aktarılır. `failproofai-sdk[langgraph]` gibi framework ekstraları, framework'ün kendisini kurar; adaptörler her zaman temel wheel'de gönderilir. +Paket `failproofai-sdk` olarak yüklenir ve Python'da `failproofai_sdk` olarak içe aktarılır. `failproofai-sdk[langgraph]` gibi framework ek paketleri framework'ü kendisini yükler; adaptörler her zaman temel wheel'de bulunur. ## Failproof daemon'ını bağlayın - 1. **Admin → Keys**'e gidin ve `events:add` ile bir anahtar oluşturun. + 1. **Admin → Keys** bölümüne gidin ve `events:add` ile bir anahtar oluşturun. 2. [Failproof daemon'ını Cloud'a bağlayın](/tr/start/setup#connect-a-machine-to-cloud) ajan makinesinde. - 3. Bir enstrümantalı oturumu çalıştırın, ardından **Observe → Events** altında tam kimliğini bulun. - 4. **Observe → Sessions**'a gidin, aynı ortamı seçin ve yeniden oluşturulmuş izlemeyi açın. + 3. Bir enstrümante edilmiş oturum çalıştırın, sonra **Observe → Events** altında tam ID'sini bulun. + 4. **Observe → Sessions** bölümüne gidin, aynı ortamı seçin ve yeniden oluşturulan iz'i açın. - ![Bir özel Python ajan oturumu yürütme grafiği ve sıralı olay izlemesi olarak yeniden oluşturulmuş.](/images/dashboard/session-detail.png) + ![Bir özel Python ajan oturumu yürütme grafiği ve sıralı olay izi olarak yeniden oluşturulmuş.](/images/dashboard/session-detail.png) + `events:add` anahtarını shell'e okuyun. `read -s` bunu yankılanmayan bir istemiçinde alır, bu nedenle hiçbir komutta veya shell geçmişinde görünmez: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Ardından makineyi ayarlayın ve bağlandığını kontrol edin: + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -58,32 +64,32 @@ failproofai_sdk.configure( ) ``` -| Bağımsız Değişken | Ne yapar | +| Bağımsız Değişken | Ne işe yarar | | --- | --- | -| `environment` | Her olay üzerindeki etiket — `production`, `staging`, `prod-eu`. Varsayılan olarak `dev`'dir. | -| `flush_interval` | Arka plan thread'inin diske yazma sıklığı, saniye cinsinden. Varsayılan olarak `0.5`'tir. | -| `base_dir` | Nereye yazılacağı. Varsayılan olarak daemon'ın spool'udur, aksi takdirde bilmediğiniz müddetçe istediğiniz şeydir. | +| `environment` | Her olaydaki etiket — `production`, `staging`, `prod-eu`. Varsayılan `dev`'dir. | +| `flush_interval` | Arka plan iş parçacığının diske ne sıklıkta yazacağı, saniye cinsinden. Varsayılan `0.5`'tir. | +| `base_dir` | Yazılanacak yer. Varsayılan olarak daemon'ın spool'u olup, aksi takdirde bilmiyorsanız istediğiniz yerdir. | Bunun yerine ortam değişkeni tarafından ayarlayın: -| Değişken | Ne yapar | +| Değişken | Ne işe yarar | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | Kod değişikliği olmadan `environment`'ı ayarlar, etiketin uygulamaya değil dağıtıma ait olduğu durumlarda. Bir `configure()` bağımsız değişkeni bunu geçersiz kılar. | -| `FAILPROOFAI_HOME` | Spool'u tutan Failproof AI köküne taşır. | -| `FAILPROOFAI_SDK_STRICT` | `1`, enstrümantasyon hatalarının günlüğe kaydedilmesi yerine yükseltilmesine neden olur. | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1`, bir framework uyumluluk sorununun devam etmek ve uyarı vermek yerine yükseltilmesine neden olur. | +| `AGENTEYE_ENVIRONMENT` | Kod değişikliği olmadan `environment`'ı ayarlar, etiket dağıtıma ait olduğunda. Bir `configure()` bağımsız değişkeni bunu geçersiz kılar. | +| `FAILPROOFAI_HOME` | Spool'u tutan Failproof AI kökünü taşır. | +| `FAILPROOFAI_SDK_STRICT` | `1` enstrümantasyon hatalarının kaydedilmek yerine yükseltilmesini sağlar. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` framework uyumluluğu sorununda uyarı verip devam etmek yerine yükseltmeyi sağlar. | - **`environment`'da virgül yok.** İşlem bu alanı filtrelerini oluşturmak için virgülde böler ve bir tane içeren herhangi bir olayı atlar — tüm çalıştırma sessizce kaybolur. `prod,eu` değil `prod-eu` yazın. + **`environment`'da virgül yok.** Ingest bu alanı virgülle bölmesi için filtreler oluşturur ve virgül içeren herhangi bir olayı atlar — böylece tüm bir çalıştırma sessizce kaybolur. `prod,eu` değil `prod-eu` yazın. - `configure(environment="prod,eu")` hemen öğrenmeniz için yükseltir. `AGENTEYE_ENVIRONMENT` yükseltemez — hiç kimse sizi aramıyor — bu nedenle bir kez uyarı verir ve `dev`'e geri döner. + `configure(environment="prod,eu")` yükseltir böylece hemen fark edersiniz. `AGENTEYE_ENVIRONMENT` yükseltemez — hiç sizi aramıyor — bu nedenle bir kez uyarır ve `dev`'e geri döner. -Olaylar bellekte sıralanır ve arka planda her `flush_interval` saniyede yazılır; yorumlayıcı çıkışında son bir temizlik yapılır. Doğrudan öldürülen bir işlem henüz yazılmamış her şeyi kaybeder. +Olaylar bellekte sıraya alınır ve arka planda her `flush_interval` saniyede diske yazılır; yorumlayıcı çıkışında son bir flush yapılır. Doğrudan öldürülen bir işlem henüz yazılmış olmayan her şeyi kaybeder. ## Kimlik -Her olay bir oturuma ve bir ajana aittir. **Kapsamlar her ikisini de doldurur**, bu nedenle nadiren bunları geçersiniz: +Her olay bir oturum ve bir ajanına aittir. **Kapsamlar her ikisini de doldurur**, bu nedenle nadiren bunları geçersiniz: ```python with failproofai_sdk.session(): @@ -91,30 +97,30 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -`session_id` veya `agent_id`'yi açıkça geçmek hala çalışır ve kazanır. Hiçbiri bağlı veya geçilmez ise, çağrı Cloud'un sessizce atması gereken bir olay yayacak yerine `TypeError` yükseltir. +`session_id` veya `agent_id`'yi açıkça geçmek hala çalışır ve kazanır. Bağlı ne de geçilmiş olmadan, çağrı Cloud'un sessizce atılacağı bir olayı yayınlamak yerine `TypeError` yükseltir. - Kimlik, bağlam değişkenlerinde bulunur. `asyncio` görevlerini otomatik olarak takip eder, ancak **yeni thread'leri değil** — bir işçiyi `failproofai_sdk.propagate()` içine sarın veya olayları eki olmadan başarısız alın. + Kimlik bağlam değişkenlerinde durur. `asyncio` görevlerini otomatik olarak takip eder, ancak **yeni iş parçacıklarını değil** — bir işçiyi `failproofai_sdk.propagate()` içine sarın veya olayları bağlantısız kalırlar. ## Olay kataloğu -On beş metod. Çoğu **çiftler** halinde gelir — açıcıyı çağırırsınız, ardından kapatıcıyı ve SDK boşluğu zamanlar. +On beş metod. Çoğu **çiftler halinde** gelir — açanı çağırırısınız, sonra kapatıcısını, ve SDK açıklığı ölçer. -| | Açar | Kapatır | +| | Açar | Kapar | | --- | --- | --- | -| **Ajanlar** | `agent_start` | `agent_end` | +| **Aracılar** | `agent_start` | `agent_end` | | | `agent_pause` | `agent_resume` | | **Modeller** | `model_request` | `model_response` | | **Araçlar** | `tool_use` | `tool_result` | | **Kancalar** | `hook_triggered` | `hook_completed` | | **İnsanlar** | `human_wait` | `human_input` | -Üç başında durur: `error`, `human_pause`, `human_interrupt`. +Üçü bağımsız: `error`, `human_pause`, `human_interrupt`. - + -Her metod ayrıca `session_id` ve `agent_id` alır, kapsamlar bunları sizin için doldurur. `None` olarak bırakılan herhangi bir şey JSON `null` olarak gönderilmek yerine bırakılır ve her metod `None` döndürür. +Her metod ayrıca `session_id` ve `agent_id` alır, kapsamlar bunları sizin için doldurur. `None` olarak bırakılan her şey JSON `null` olarak gönderilmek yerine atılır ve her metod `None` döndürür. | Metod | Gerekli | İsteğe Bağlı | | --- | --- | --- | @@ -137,14 +143,14 @@ Her metod ayrıca `session_id` ve `agent_id` alır, kapsamlar bunları sizin iç - Bir çalıştırmayı başarısız olarak işaretlemek için `outcome`, `failed`, `error`, `timeout` veya `rejected` olmalıdır. Başka herhangi bir şey — yakın kaçış `"failure"` da dahil olmak üzere — bir başarı olarak sayılır. + Bir çalıştırmayı başarısız olarak işaretlemek için, `outcome` şunlardan biri olmalıdır: `failed`, `error`, `timeout` veya `rejected`. Başka bir şey — yakın kaçış `"failure"` dahil — başarı olarak sayılır. ## Eşleştirme ve süre -**Bir kural: kapatma olayına açıcısıyla aynı kimliği verin.** Bu onları eşleştirir ve SDK'ya boşluğu zamanlamasını sağlar. +**Bir kural: kapatıcı olayına açıcısı ile aynı id'yi verin.** Bunun ne eşleştirdikleri ne de SDK'nın boşluğu zamanlamasını sağlayan şeydir. -| Çift | Eşleştirilir | +| Çift | Eşleştirilen | | --- | --- | | `tool_use` → `tool_result` | `tool_call_id` | | `hook_triggered` → `hook_completed` | `hook_id` | @@ -152,23 +158,23 @@ Her metod ayrıca `session_id` ve `agent_id` alır, kapsamlar bunları sizin iç | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**`duration_ms` kendiniz geçmeyin.** SDK bunu ölçer ve geçmek `ValueError` yükseltir. +**Kendiniz `duration_ms` geçmeyin.** SDK onu ölçer ve geçmesi `ValueError` yükseltir. -Tek istisna `model_response`'dir; burada sadece siz gerçek sağlayıcı gecikmesini bilirsiniz. Milisaniye cinsinden bir tam sayı geçin — bir float yükseltir, çünkü sütun 32 bit bir tamsayıdır ve aksi takdirde boş kalırdı. +Tek istisna `model_response`'tir, burada yalnızca siz gerçek sağlayıcı gecikmesini bilirsiniz. Tam bir milisaniye sayısı geçin — kayan sayı yükseltir, çünkü sütun 32-bit bir tamsayıdır ve aksi takdirde boş kalırdı. -- **Kimlikler yalnızca tür başına, oturum başına benzersiz olması gerekir.** Bir araç çağrısı ve bir kanca aynısını paylaşabilir; aynı anda çalışan iki oturum aynı kimlikler çarpışmadan yeniden kullanabilir. -- **Bunlar bir ajana kapsamlı değildir.** Bir çiftin bir ajan altında açılması ve başka bir ajan altında kapatılması hala eşleşir — bu, çok ajanlı kodda normal durumdur. -- **`request_id` isteğe bağlı ancak önerilir.** Olmadan, model olayları varış sırasında eşleştirilir, bu nedenle aynı ajan içinde iki eşzamanlı çağrı yanlış eşleşebilir. -- **Süreçler arasında bölünmüş bir çift** Cloud'da hala eşleşir, ancak SDK bunu zamanlamaz — hiçbir işlemin her iki yarısı da görmediği bir şey. -- **En fazla 10.000 açıcı aynı anda kapatıcı için bekler.** Bunun ötesinde en eski bırakılır, bu nedenle bir sızıntı sınırsız olarak büyüyemez. +- **ID'ler yalnızca tür başına, oturum başına benzersiz olması gerekir.** Bir araç çağrısı ve bir kanca bir taneyi paylaşabilir; aynı anda çalışan iki oturum çarpışma olmadan aynı ID'leri yeniden kullanabilir. +- **Onlar bir ajanın kapsamında değildir.** Bir çift bir ajan altında açılıp başka bir ajan altında kapatılırsa yine eşleşir — bu, çok ajanın kodunda normal durumdur. +- **`request_id` isteğe bağlıdır ancak önerilir.** Olmadan, model olayları gelişte sıraya alınırlar, bu nedenle aynı ajan içindeki iki eşzamanlı çağrı hatalı eşleşebilir. +- **İşlemler arasında bölünmüş bir çift** Cloud'da yine eşleşir, ancak SDK onu zamanlamaz — hiçbir işlem her iki yarıyı da görmedi. +- **En fazla 10.000 açıcı aynı anda kapatıcıyı bekler.** Bunun ötesinde en eski atılır, böylece bir sızıntı sınırsızca büyüyemez. ## Kendi alanlarınız -Geçtiğiniz herhangi bir ekstra anahtar sözcük olay ile saklanır: +Geçtiğiniz herhangi bir ekstra anahtar sözcük olayda depolanır: ```python failproofai_sdk.event.tool_use( @@ -177,21 +183,21 @@ failproofai_sdk.event.tool_use( ) ``` -Daha sonra sorgulamak istiyorsanız JSON türlerini tercih edin. Başka herhangi bir şey — bir UUID, bir datetime, bir `Decimal`, bir set, bytes, bir model nesnesi — dize olarak depolanır. +Daha sonra sorgulamak istiyorsanız JSON türlerini tercih edin. Başka bir şey — bir UUID, tarih/saat, bir `Decimal`, küme, bayt, bir model nesnesi — bir dizi olarak depolanır. - **Alan adlarınızı önek olarak yazın.** Ekstralar son olarak uygulanır, bu nedenle `model`, `tool_name` veya `outcome` adı verilen bir alan sessizce gerçek olanı geçersiz kılar. Framework adaptörleri `fw_` kullanır; aynısını yapın ve hiçbir şey çarpışamaz. + **Alan adlarınızı önek yapın.** Ekstralar son olarak uygulanır, bu nedenle `model`, `tool_name` veya `outcome` adlı bir alan sessizce gerçek olanın yerini alır. Framework adaptörleri `fw_` kullanır; aynısını yapın ve hiçbir şey çarpışamaz. - Bunun nedeni de yazım hatası yapılan isteğe bağlı bir alanın hiçbir zaman hata vermemesidir — sadece yeni bir özel alan olur. Cloud'da standart bir alan eksikse, önce yazımı kontrol edin. + Bu aynı zamanda yanlış yazılmış isteğe bağlı bir alanın neden hiçbir zaman hata vermediğinin nedenidir — sadece yeni bir özel alan olur. Standart bir alan Cloud'da eksikse, ilk olarak yazımı kontrol edin. -Bu beş ad ayrılmıştır ve doğrudan reddedilir: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. +Bu beş ad ayrılmıştır ve tamamen reddedilir: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. ## Teslimat ve doğrulama - **Observe → Events**'te `agent_start` ilk olarak ve `agent_end` son olarak bulunduğunu doğrulayın. Ardından **Observe → Sessions**'ı açın ve model, araç, insan, kanca ve hata olaylarının amaçlanan sırada göründüğünü onaylayın. Oturum kimliğini birincil sorun giderme anahtarı olarak kullanın. + **Observe → Events** bölümünde önce `agent_start` var mı kontrol edin ve `agent_end` sonunda var mı. Sonra **Observe → Sessions** bölümünü açın ve model, araç, insan, kanca ve hata olaylarının amaçlanan sırada göründüğünü doğrulayın. Oturum ID'sini birincil sorun giderme anahtarı olarak kullanın. ```bash @@ -203,14 +209,14 @@ Bu beş ad ayrılmıştır ve doğrudan reddedilir: `timestamp`, `session_id`, ` -Cloud boşsa, `$FAILPROOFAI_HOME/custom-agents/events`'i, aksi takdirde `~/.failproofai/custom-agents/events`'i inceleyin. JSONL dosyaları SDK emisyonunu kanıtlar; büyüyen bir spool daemon konfigürasyonuna veya teslimata işaret ederken, boş bir spool enstrümantasyona veya işlem ömrüne işaret eder. +Cloud boşsa, `$FAILPROOFAI_HOME/custom-agents/events` bölümünü inceleyin, aksi takdirde `~/.failproofai/custom-agents/events` bölümünü inceleyin. JSONL dosyaları SDK yayınını kanıtlar; büyüyen bir spool daemon konfigürasyonunu veya teslimatı gösterirken boş bir spool enstrümantasyonu veya süreç ömrünü gösterir. - Spool'u yalnızca daemon durdurulduğunda inceleyin. Çalışırken, her toplu işi milisaniye içinde toplar ve siler, bu nedenle bir dizin listesi toplayıcıyla yarışır ve yayılan olaylardan çok daha azını gösterir. + Spool'u yalnızca daemon durdurulmuş durumdayken inceleyin. Çalışırken, her topluyu milisaniye cinsinden toplar ve siler, bu nedenle bir dizin listesi toplayıcıyla yarışır ve yayınlanan etkinliklerden çok daha azını gösterir. -## Özel bir çalışma zamanında başarısızlıkları önleyin +## Özel runtime'da başarısızlıkları önleyin -Güvensiz eylemi, gerekli kanıtı ve amaçlanan yanıtı tanımlamak için denetim bulgularını ve bağlantılı izlemeleri kullanın. Özel bir uygulama entegrasyonu, eylemi yürütmeden önce ortaya koymak, yapılandırılmış girdisini ilke motoruna geçirmek ve ortaya çıkan allow, instruct veya deny kararını uygulamalıdır. +Güvensiz eylemi, gerekli kanıtı ve amaçlanan yanıtı tanımlamak için denetim bulgularını ve bağlı izleri kullanın. Özel bir uygulama entegrasyonu, yürütülmeden önce eylemi ortaya çıkarmalı, yapılandırılmış girdisini ilke motoruna geçirmeli ve ortaya çıkan allow, instruct veya deny kararını uygulamalıdır. -[Failproof AI ile iletişime geçin](mailto:support@befailproof.ai) ve çalışma zamanınızın model, araç ve yaşam döngüsü sınırlarını ilke kancalarına harita taşımasına yardımcı olur, ardından entegrasyonu sizle doğrularız. \ No newline at end of file +[Failproof AI ile iletişime geçin](mailto:support@befailproof.ai) ve runtime'ınızın model, araç ve yaşam döngüsü sınırlarını ilke kancalarına eşlemesine yardımcı olacak, ardından entegrasyonu sizle doğrulayacağız. \ No newline at end of file diff --git a/docs/tr/reference/evaluator-sdk.mdx b/docs/tr/reference/evaluator-sdk.mdx index ff1efbee..671bfcb4 100644 --- a/docs/tr/reference/evaluator-sdk.mdx +++ b/docs/tr/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "Failproof AI oturumlarını senkron veya asenkron olarak puanlayan bir hizmet oluşturun." +description: "Kendi altyapınızda değerlendirme çalışanını çalıştırın — LLM yargıçlar ve barındırılan Python'un yapamadığı diğer her şey için." icon: "gauge" --- -Bir evaluator tamamlanmış bir aracı oturumunu alır ve önemsediğiniz kalite sinyallerini döndürür: sayısal puanlar, her puan için bir açıklama ve isteğe bağlı bir özet. Failproof AI bu sonuçları izin izi yanında depolar ve aracılar ile ortamlar arasında grafik gösterimini yapar. +Evaluator SDK, değerlendirmeleri kendi altyapınızda çalıştırır. Çalışanınız, değerlendirmelerini Failproof AI'ya kaydeder, oturumlar bittiğinde talep eder, bunları puanlar ve sonuçları gönderir — tümü giden HTTPS üzerinden: hiçbir şey ona bağlanmaz. [Barındırılan Python](/tr/evaluations/write)'un yapamadığı şeyler için kullanın — LLM yargıçlar, model çağrıları, paketler, sırlar ve ağ erişimi. Sonuçları, [değerlendirmeler sayfasında](/tr/sessions/evaluations) barındırılan olanların yanında görünür, **customer** etiketi ile etiketlenir. -## Bir evaluator kurun +`failproofai-sdk` içinde, `failproofai_sdk.evaluator` altında gemi olarak gönderilir; izleme SDK'sını içe aktarmak onu yüklemez. - - - SDK'yı ve onu çalıştırmak için kullanılan sunucuyu yükleyin. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - `evaluator.py` oluşturun. Bu örnek, bir oturumda başarısız araç çağrıları olup olmadığını kontrol eder. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - Paylaşılan bir token ayarlayın, evaluator'ı başlatın ve sağlık uç noktasının yanıt verip vermediğini doğrulayın. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - Başka bir terminalde: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## Evaluator'ı Failproof AI'a bağlayın +```bash +pip install failproofai-sdk +``` -1. Evaluator'ı Failproof AI Cloud tarafından erişilebilen bir HTTPS URL'de yayınlayın. -2. `EVALUATOR_ENDPOINT` değerini o URL ile yapılandırın ve `EVALUATOR_TOKEN` değerini evaluator tarafından kullanılan aynı token olarak ayarlayın. Yönetilen Cloud için bağlantıyı yapılandırmak amacıyla [support@befailproof.ai](mailto:support@befailproof.ai) ile iletişime geçin. -3. Bir değerlendirme çalıştırın ve puanlarının Failproof AI'da göründüğünü doğrulayın. +## Değerlendirmeler yazın - - - **Observe → Sessions** altında tamamlanmış bir oturumu açın ve otomatik olarak değerlendirilmediyse **Run evaluation** seçeneğini seçin. Oturumun **Evaluation** panelinde durumu, puanları, mantığı ve özeti gözden geçirin. +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - Aracılar veya ortamlar arasında puanları karşılaştırmak için **Observe → Evaluations** seçeneğini kullanın. Gecikme, maliyet, token ve diğer sayısal ölçümler için **Observe → Metrics** seçeneğini kullanın. - Evaluator'ın beklenen puan anahtarlarını ve o belirli çalıştırma için yararlı mantığı döndürdüğünü doğrulamak için bir oturumla başlayın. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![Değerlendirme puanları ve mantığını izin izi yanında gösteren bir oturum detay görünümü.](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` bir değerlendirmeyi kaydeder. Anahtar, sonuçlarının altında göründüğü şeydir; mantık değişirse sürümü değiştirin ve her sonuç onu üreten sürümü tutar. Bir çalışan 100 adede kadar değerlendirmeyi tutabilir. +- `result_kind` aksi belirtilmediği sürece `"score"` dir. Bir `"metric"` veya `"assertion"` değerlendirmesi için, bir `metrics` veya `assertions` girişini anahtardan sonra adlandırın: bu giriş sonucu olur. +- `when` bir oturumun uygulanıp uygulanmadığını belirler. Birini atlamak için `ConditionResult(False, "")` döndürün ve neden kaydedilir. +- Bir değerlendirme düz bir işlev veya `async` olabilir ve `timeout_seconds` onu sınırlar. +- Yük anahtarları — yukarıdaki `tool_name`, `response` ve `content` — aracılarınızın gönderdikleri şeydir, bu nedenle bunları gerçek bir oturumdan okuyun. - Bireysel sonuçlar doğru göründüğünde, bu puanları zaman içinde ve aracılar veya ortamlar arasında karşılaştırmak için değerlendirme panosu kullanın. +## Çalışanı çalıştırın - ![Evaluator puanlarını zaman içinde gösteren bir kalite panosu.](/images/dashboard/dashboard-quality.png) +**Administration → Keys** altında oluşturulan `evaluations:run` izinli bir anahtarı `FAILPROOFAI_EVALUATOR_TOKEN` içine koyun — bunu bir komuta yazıp yazıp yapmak yerine gizli deponuzdan ayarlayın — ve çalışanı başlatın: - Sağlıklı bir grafik, istikrarlı puan adları kullanmalıdır; bir anahtar adı değiştirmek ayrı bir seri oluşturur. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -Kendi kendini barındıran bir Cloud örneği için, sunucu işleminde `EVALUATOR_ENDPOINT` ayarlanana kadar otomatik değerlendirme devre dışı bırakılır. Evaluator ortam değişkenlerini değiştirdikten sonra sunucuyu yeniden başlatın. +`__main__` bloğu olmadan, `python -m failproofai_sdk.evaluator evaluator:app` aynısını yapar. -Hizmet `GET /health`, `GET /config`, `POST /evaluate` ve isteğe bağlı olarak `GET /evaluate/{job_id}` sunar. Asenkron çalışmalar için `JobPending` döndürün ve `@app.job_lookup` kaydedin, böylece Failproof AI bunu yoklayabilsin. +| Değişken | Varsayılan | Amaç | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | gerekli | Failproof AI'ın nerede olduğu: Cloud için `https://app.befailproof.ai`. Loopback'e işaret etmedikçe HTTPS | +| `FAILPROOFAI_EVALUATOR_TOKEN` | gerekli | `evaluations:run` izinli bir anahtar | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | Bu çalışanı adlandırır | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | Bu çalışanın aynı anda puanladığı oturumlar | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Failproof AI'ya yapılan her istek için zaman aşımı | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | Duran bir çalışanın uçuş halindeki çalışmaları ne kadar bekleyeceği | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | Loopback olmayan bir URL'ye düz HTTP'ye izin ver — aşağıdaki uyarıya bakın | +| `FAILPROOFAI_EVALUATOR_MODULE` | yok | `python -m failproofai_sdk.evaluator` için `module:attribute` | -Bir token yapılandırıldığında, sağlık dışındaki tüm rotalar Failproof AI'ın `EVALUATOR_TOKEN` olarak gönderdiği aynı taşıyıcı token'ı gerektirir. + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` her şeyi açık metin olarak gönderir. Çalışan, `FAILPROOFAI_EVALUATOR_TOKEN` değerini her istekte `Authorization: Bearer` başlığı olarak taşır ve getirdiği yazılı tutanaklar oturumların kendisidir — bu nedenle yoldaki herkes ikisini de okur ve okuduğu token, siz döndürmediğiniz sürece değerlendirmeleri çalıştırır. Bunu yalnızca yalıtılmış bir geliştirme ağında kullanın. Başka her yerde URL HTTPS olmalıdır; loopback hiçbir bayrak gerektirmez. + -## SDK türleri +## Sonuç türleri | Tür | Alanlar | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## Dekoratörler ve rotalar +| `Score` | `value` (0 ile 1 arasında), `passed`, `unit` (varsayılan `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -| Dekoratör | Rota | Gerekli | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | Evet | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | `JobPending` döndürürken | -| `@app.config` | `GET /config` | Hayır | - -SDK, değerlendirme isteği gövdelerini 25 MiB ile sınırlar. Bilinmeyen istek alanları göz ardı edilir, böylece hizmetler olay sözleşmesi büyüdükçe uyumlu kalır. +Bir `EvalResult` en az bir puan, metrik veya iddaa tutar ve en fazla 25 tutar, her biri benzersiz bir anahtar altında. -## Asenkron işleri döndürün +## Oturum -Değerlendirme bir istek içinde tamamlanamadığında `JobPending` kullanın. İş kimliği Failproof AI için opaktır ve sonuç toplanana veya sunucu zaman aşımı sona erene kadar hizmetiniz tarafından çözülebilir durumda kalmalıdır. - -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| Alan veya yöntem | Size verir | +| --- | --- | +| `session_id`, `agent_id`, `environment` | Oturumun kimliği | +| `started_at`, `ended_at` | Ne zaman başladığı ve bittiği | +| `event_count`, `events` | Tam, sıralı yazılı tutanak | +| `count(event_type)` | O tür kaç olayı tuttuğu | +| `events_of_type(event_type)` | Sıra içinde bu olaylar | -Yoklama hızı şu sırada seçilir: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs`, ardından sunucunun `EVALUATOR_POLLING_INTERVAL_SECS` değeri. Değerler 1 saniye ile 1 saat arasında sınırlandırılır. Sunucunun varsayılan duvar saati yoklama üst limiti bir saattir. +Her olay `id`, `ts`, `event_type` ve `payload` taşır. -## İstek ve yanıt alanları +## Eski değerlendirici -| Alan | Tür | Notlar | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | Şu anda `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | Oturum kimliği ve ortamı. | -| `started_at` | `datetime` | İlk olayın zaman damgası. | -| `ended_at` | `datetime \| None` | Oturum bir son olayını yayınladığında mevcut. | -| `events` | `list[AgentEvent]` | Tam sıralı olay akışı. | -| `AgentEvent.id` | `int` | Arka uç olay satırı tanımlayıcısı. | -| `AgentEvent.ts` | `datetime` | Olay zaman damgası. | -| `AgentEvent.event_type` | `str` | `tool_use` gibi olay ailesi. | -| `AgentEvent.payload` | `dict[str, Any]` | Tam olay yükü. | -| `EvalResponse.scores` | `dict[str, float] \| None` | Değerlendirmelerde grafik gösterilen sayısal boyutlar. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | Puan başına açıklamalar; anahtarlar `scores` değerleriyle eşleşmelidir. | -| `EvalResponse.summary` | `str \| None` | Genel değerlendirme açıklaması. | - -## Sunucu operatörü ayarları - -Otomatik değerlendirme dağıtım genelinde gerçekleşir ve `EVALUATOR_ENDPOINT` bulunmadığında devre dışı kalır. - -| Değişken | Varsayılan | Amaç | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | ayarlanmamış | Evaluator hizmetinin temel URL'si. | -| `EVALUATOR_TOKEN` | ayarlanmamış | `Evaluator(token=...)` ile paylaşılan taşıyıcı token. | -| `EVALUATOR_WORKERS` | `2` | Eşzamanlı görev işçileri. | -| `EVALUATOR_CLAIM_BATCH` | `4` | Görev işçisi geçişi başına talep edilen oturumlar. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Asenkron yoklama hız geri dönüşü. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | İstek başına evaluator zaman aşımı. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | Terminal hatası öncesi teslim denemeleri. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | `/config` için yenileme hızı. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Maksimum duvar saati asenkron yoklama süresi. | - -Sunucu ayrıca dağıtım genelindeki evaluator'ı hangi kuruluşların kullanabileceğini sınırlandırabilir. Uç nokta, token, yeniden deneme ve kuruluş kapı değişikliklerini operatör yapılandırması olarak değerlendirin ve bunları değiştirdikten sonra sunucuyu yeniden başlatın veya döndürün. - -## Güvenlik ve operasyonlar - -- Trafik güvenilir bir ağ sınırı aştığında evaluator'ı HTTPS'nin arkasına koyun. -- Boş olmayan bir taşıyıcı token yapılandırın ve her iki hizmet üzerinde de aynı tutun. -- Token veya istek yüklerinden tam hassas istekleri günlüğe kaydetmeyin. -- Senkron işleyicileri idempotent yapın; yeniden denemeler bir isteği tekrar edebilir. -- Asenkron iş durumunu üretim ortamında işlem belleği dışında kalıcı hale getirin. -- Kararlı puan anahtarları döndürün. Bir anahtarı yeniden adlandırmak eski olanı değiştirmek yerine yeni bir grafik serisi oluşturur. - -SDK `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` ve işleyici istisnalı yapılandırılmış yaşam döngüsü günlükleri yayınlar. Günlüğe kaydetme işleyicilerini yapılandırmaz; ana uygulamanın günlüğe kaydetme yapılandırmasını kullanın. \ No newline at end of file +Daha önceki Evaluator SDK — Failproof AI'ın `/evaluate` adresinde `EVALUATOR_ENDPOINT`'de çağırdığı ve `JobPending` aracılığıyla yoklanan bir HTTP hizmeti — emekli olmuştur. Bu çalışan üzerinde yeni değerlendiriciler oluşturun; eski bir hizmet çalıştıran kendi kendini barındıran örneğin operatörleri bunu geçiş sırasında tutabilir. \ No newline at end of file diff --git a/docs/tr/reference/failproof-cli.mdx b/docs/tr/reference/failproof-cli.mdx index 0993f698..b7146cc7 100644 --- a/docs/tr/reference/failproof-cli.mdx +++ b/docs/tr/reference/failproof-cli.mdx @@ -1,86 +1,104 @@ --- title: "Failproof AI CLI" -description: "Hook yükle, yerel politikaları yönet, Cloud'u bağla ve yerel daemon'ı çalıştır." +description: "Kancaları yükleyin, yerel politikaları yönetin, Cloud'a bağlanın ve yerel daemon'ı çalıştırın." icon: "terminal" --- -Yerel CLI'yi `npm install -g failproofai` ile yükle. Bağımsız değişken olmadan çalıştırarak yerel politika panosunu aç. +`npm install -g failproofai` ile yerel CLI'yi yükleyin. Hiçbir argüman olmadan çalıştırarak yerel politika göstergesini açın. -Paket Node.js 20.9 veya daha yeni bir sürümünü gerektirir. Bun 1.3 veya daha yeni sürümü geliştirme ve kaynak yüklemeleri için desteklenir. `failproofai configure` ve `failproofai setup`, `failproofai config` için takma adlardır; `failproofai p`, `failproofai policies` için bir takma addır. +Paket Node.js 20.9 veya daha yeni bir sürüm gerektirir. Bun 1.3 veya daha yeni sürüm geliştirme ve kaynak yüklemeleri için desteklenir. `failproofai configure` ve `failproofai setup`, `failproofai config` için diğer adlardır. `failproofai policy`, `failproofai pack` ve `failproofai p` hepsi `failproofai policies` yazımlarıdır — paketler ve tek politikalar daha önce üç komut iken şimdi birdir. Eski yazımlar hala çalışır, iki istisna dışında: `pack list ` artık `policies show ` olmuştur ve `pack build` artık `publish` olmuştur. -## Makine Kurulumu +## Bir makineyi kurun + +CLI'yi yükleyin, ardından makine anahtarını kabuğa okuyun. `read -s`, komutta asla görünmeyecek şekilde yankılanmayan bir komut isteminde alır: ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +Daha sonra makineyi kurun ve ne uygulayacağını seçin: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` -Yerel politika panosunu açmak için `failproofai` komutunu bağımsız değişken olmadan çalıştır. +`failproofai config` kurulumun tamamıdır: `failproofaid` hizmetini yükler (kök bir kez, `sudo -n` aracılığıyla — asla etkileşimli bir parola istemi değil), bulduğu her ajan CLI'ye kancaları bağlar ve bir anahtar mevcut olduğunda Cloud'a bağlanır. Terminal olmadan — CI, bir konteyner, onu yöneten bir ajan — sormak yerine uygular ve yapması istenen herhangi bir şey olmazsa 1 ile çıkar. + +Hiçbir politika seçmez. Bu ikinci komutun işidir ve onsuz yeni yapılandırılan bir makine yalnızca her zaman açık olan korumayı uygular. + +Ortam değişkenini `--token`'e tercih edin: komut satırı argümanı kutudaki her kullanıcı tarafından `ps` aracılığıyla okunabilir. Bu değişkenin koruduğu tek şeydir — herhangi bir komuta yazılan bir anahtar, `export` dahil, kabuk geçmişine düşer; bu nedenle yukarıda `read -s` ile okunur. CI'de, bunu gizli mağazadan ayarlayın ve kabuk izlemesini (`set -x`) kapalı tutun veya izleme bunu yazdırır. + + + `--connect ` **zaten kurulmuş** bir makineyi kaydeder. Kayıt başarılı olur olmaz döner — daemon'ı yüklemez ve hiçbir kancayı bağlamaz. Henüz kurulmamış bir makinede düz `failproofai config` (veya `failproofai config --token `) kullanın, aksi takdirde hiçbir şey toplamadığı ve uygulamadığı halde bağlı olarak okunur. + + +Yerel politika göstergesini açmak için `failproofai`'yi hiçbir argüman olmadan çalıştırın. | Komut | Sonuç | | --- | --- | -| `failproofai config` | Etkileşimli makine kurulumunu çalıştır | -| `failproofai config --connect --token ` | Cloud alımı ve politika sunumunu bağla | -| `failproofai config --status` | Bağlantı, daemon, sunum ve duraklatma durumunu göster | -| `failproofai policies` | Yerleşik, özel, kural, paket ve Cloud tarafından yönetilen politikaları listele | -| `failproofai policies --install` | Hook yükle ve politikaları etkinleştir | -| `failproofai policy add ` | Bir politikayı etkinleştir — yerleşik veya yüklenmiş paketten `:` | -| `failproofai policy remove ` | Bir politikayı devre dışı bırak, aynı adlandırma | -| `failproofai policies --uninstall` | Politikaları devre dışı bırak veya harness hook'larını kaldır | -| `failproofai pack list` | Yüklenmiş politika paketlerini ve her birinin taşıdığı her politikayı listele | -| `failproofai pack add ` | Bir politika paketini GitHub sürümünden yükle; etiket olmayan en yeni sürümü alır ve sabitleri | -| `failproofai pack add --bundled` | Yerleşik politikaları bir paket olarak yükle, bu paketten, ağ olmadan | -| `failproofai pack build ` | Kendi paketiniz için üç sürüm varlığını oluştur | -| `failproofai pack remove ` | Yüklenmiş bir paketi deaktive et | -| `failproofai audit` | Yerel agent geçmişini tara ve yerel denetim görünümünü aç | -| `failproofai audit --schedule [days] --email
` | Yinelenen yerel taramaları zamanla ve bulgularını e-postayla gönder | -| `failproofai audit --status` | Rapor adresini, aralığını ve sonraki planlanan taramayı göster | -| `failproofai audit --no-schedule` | Denetim geçmişini silmeden yinelenen taramaları durdur | -| `failproofai harness list` | Ekstra yakalama yollarını listele | -| `failproofai flush --wait` | Geçerli olay spool'unu teslim et | -| `failproofai backfill --since 30d` | Daha önce geçiş yapılan geçmişi yeniden oku | -| `failproofai config --pause [duration]` | Bir yerel oturumu varsayılan olarak 30 dakika, en fazla 8 saat duraklatabilir | -| `failproofai config --resume` | Duraklatılan bir yerel oturumuna devam et; tüm duraklatmaları temizlemek için `--all` ekle | -| `failproofai update` | Paket geçişlerini tamamla ve daemon'ı güncelle | -| `failproofai migrate --dry-run` | Bekleyen home-layout geçişlerinin önizlemesini görün veya çalıştırın | -| `failproofai uninstall` | Paketi kaldırmadan önce hook'ları ve daemon'ı kaldır | -| `failproofai --version` | Yüklenmiş paket sürümünü yazdır | -| `failproofai --help` | Komutları ve genel kullanımı göster | +| `failproofai config` | Makineyi kurun: ajanlar, daemon ve bir anahtar mevcut olduğunda Cloud | +| `failproofai config --token ` | Tek seferde kurun ve bağlanın, hiçbir şey sormayarak | +| `failproofai config --connect ` | **Zaten** kurulmuş bir makineyi kaydedin — daemon yok, kanca yok | +| `failproofai config --status` | Bağlantı, daemon, teslimat ve duraklama durumunu gösterin | +| `failproofai policies` | Yerleşik, özel, kural, paket ve Cloud tarafından yönetilen politikaları listeleyin | +| `failproofai policies --install` | Ajan CLI'lerinize kancaları bağlayın. Kendisinde hiçbir politikayı etkinleştirmez | +| `failproofai policies add ` | Bir politikayı etkinleştirin — yerleşik veya yüklenmiş paketten `:` | +| `failproofai policies remove ` | Bir politikayı devre dışı bırakın, aynı adlandırma | +| `failproofai policies --uninstall` | Politikaları devre dışı bırakın veya ağı kanca çıkarın | +| `failproofai policies show /` | Bir paket ne taşıdığını, manifestinden okuyun, almadan önce | +| `failproofai policies show / --releases` | Yayımladığı her sürüm ve burada hangisi olduğu | +| `failproofai policies add ` | Bir politika paketini GitHub yayınından yükleyin; hiçbir etiket en yenisini alır ve sabitler | +| `failproofai publish` | Kendi politikalarınızı bir paket olarak gönderin; `--init` başlamak için bir tane yazıyor | +| `failproofai policies remove ` | Bir paketi kaldırın | +| `failproofai audit` | Yerel ajan geçmişini tarayın ve yerel denetim görünümünü açın | +| `failproofai audit --schedule [days] --email
` | Tekrarlayan yerel taramaları planlayın ve bulgularını e-postayla gönderin | +| `failproofai audit --status` | Rapor adresini, aralığı ve sonraki planlanan taramayı gösterin | +| `failproofai audit --no-schedule` | Denetim geçmişini silmeden tekrarlayan taramaları durdurun | +| `failproofai harness list` | Ekstra yakalama yollarını listeleyin | +| `failproofai flush --wait` | Geçerli olay spool'unu teslim edin | +| `failproofai backfill --since 30d` | Daha önce geçen geçmişi yeniden okuyun | +| `failproofai config --pause [duration]` | Bir yerel oturumu varsayılan olarak 30 dakika, en fazla 8 saat duraklatın | +| `failproofai config --resume` | Duraklatılmış bir yerel oturumu sürdürün; tüm duraklamaları temizlemek için `--all` ekleyin | +| `failproofai update` | Paket göçlerini tamamlayın ve daemon'ı güncelleyin | +| `failproofai migrate --dry-run` | Bekleyen ana düzen göçlerini önizleyin veya çalıştırın | +| `failproofai uninstall` | Paketi kaldırmadan önce kancaları ve daemon'ı kaldırın | +| `failproofai --version` | Yüklenmiş paket sürümünü yazdırın | +| `failproofai --help` | Komutları ve genel kullanımı gösterin | ## Yapılandırma bayrakları | Bayrak | Kullanım | | --- | --- | -| `--connect --token ` | Etkileşimsiz olarak bağla | -| `--machine-id ` | Kararlı makine kimliğini ayarla | -| `--machine-label ` | Pano etiketini ayarla veya değiştir | -| `--no-transcripts` | Kararları transkript içeriği olmadan gönder | -| `--disconnect` | Cloud politika çekişlerini ve olay sunumunu durdur | -| `--status` | Geçerli makine durumunu göster | -| `--pause [duration]` | Geçerli dizinde en yeni oturumu duraklatabilir; saniye, dakika veya saat kabul eder ve varsayılan 30 dakikadır | -| `--resume` | Eşleşen bir duraklatmayı erken sonlandır | -| `--session ` | Duraklatma veya devam etme için açık bir oturum hedefle | -| `--all` | `--resume` ile, her etkin duraklatmayı sonlandır | - -Yerel duraklatmalar, bir oturum için yerleşik, özel, kural ve paket politikalarını askıya alır. Bunlar her zaman sona erer ve Cloud tarafından yönetilen politikaları devre dışı bırakmaz. Her zaman açık olan ve devre dışı bırakılamayan veya duraklatılamayan `block-failproofai-commands`, enstrümantal agent'ın bu kaçış kapısını kendisi kullanmasını engeller. +| `--token ` | Etkileşimli olmayan şekilde kurun ve bağlanın; ayrıca `FAILPROOFAI_CLOUD_TOKEN` adresinden okuyun | +| `--url ` | `app.befailproof.ai` dışında bir yere bağlanın; ayrıca `FAILPROOFAI_CLOUD_URL` adresinden okuyun | +| `--connect ` | Zaten kurulmuş bir makinede yalnızca kaydedin. Daemon ve her kancayı atlar | +| `--machine-id ` | Sabit makine kimliğini ayarlayın | +| `--machine-label ` | **Zaten bağlı** olan bir makineyı yeniden adlandırın. Kendi başına asla kurulum çalıştırmaz, bu nedenle `failproofai config` sonrasında verin, kurulum sırasında değil | +| `--no-transcripts` | Transkript içeriği olmadan kararları gönderin | +| `--disconnect` | Cloud politikası çekişlerini ve olay teslimatını durdurun | +| `--status` | Geçerli makine durumunu gösterin | +| `--pause [duration]` | Geçerli dizindeki en yeni oturumu duraklatın; saniye, dakika veya saat kabul eder ve varsayılan olarak 30 dakikadır | +| `--resume` | Eşleşen bir duraklamayı erken bitirine | +| `--session ` | Duraklatma veya sürdürme için açık oturum belirleyin | +| `--all` | `--resume` ile, her etkin duraklamayı bitirine | + +Yerel duraklamalar yerleşik, özel, kural ve paket politikalarını bir oturum için askıya alır. Her zaman sona erer ve Cloud tarafından yönetilen politikaları devre dışı bırakmaz. Her zaman açık olan ve kendisi devre dışı bırakılamayan veya duraklatılamayan `block-failproofai-commands`, bir enstrümente edilen ajanın bu kaçış penceresini kendisi kullanmasını engeller. ## Politika bayrakları | Bayrak | Kullanım | | --- | --- | -| `--install`, `-i` | Politikaları etkinleştir ve harness hook'larını yükle | -| `--uninstall`, `-u` | Politikaları devre dışı bırak veya hook'ları kaldır | -| `--cli ` | Desteklenen bir veya daha fazla harness'i hedefle | -| `--scope user\|project\|local\|all` | Yapılandırma kapsamını seç; `all` kaldırma için | -| `--beta` | Beta politikalarını dahil et | -| `--custom`, `-c ` | Özel bir politika dosyasını doğrula ve yükle; tekrarlanabilir | +| `--install`, `-i` | Ağ kancalarını yükleyin. Bundan sonraki adlar bu politikaları etkinleştirir; yok ise, hiçbir politika değişikliği | +| `--uninstall`, `-u` | Politikaları devre dışı bırakın veya kancaları kaldırın | +| `--cli ` | Desteklenen bir veya daha fazla ağlarını hedefleyin | +| `--scope user\|project\|local\|all` | Yapılandırma kapsamını seçin; `all` kaldırmak içindir | +| `--beta` | Beta politikalarını dahil edin | +| `--custom`, `-c ` | Özel bir politika dosyasını doğrulayın ve yükleyin; tekrarlanabilir | -## Sunum ve bakım bayrakları +## Teslimat ve bakım bayrakları | Komut | Bayraklar | | --- | --- | @@ -90,9 +108,9 @@ Yerel duraklatmalar, bir oturum için yerleşik, özel, kural ve paket politikal | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update`, `npm install -g failproofai@latest` sonrasında çalıştırılmalıdır; home-layout geçişlerini gerçekleştirir, eşleşen daemon ikilisini yükler ve hizmeti yeniden başlatır. `--no-daemon` yalnızca layout geçişini gerçekleştirir. +`failproofai update`, `npm install -g failproofai@latest` sonrasında çalıştırılmalıdır; ana düzen göçlerini gerçekleştirir, eşleşen daemon ikilisini yükler ve hizmeti yeniden başlatır. `--no-daemon` yalnızca düzen göçünü gerçekleştirir. -## Harness yolları +## Ağ yolları ```text failproofai harness list [harness] @@ -100,11 +118,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -Desteklenen harness adları `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` ve `goose` adlarıdır. +Desteklenen ağ adları `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` ve `goose` olur. -Etiketler, iki kök aynı projenin kopyalarını içerdiğinde türetilen agent kimliklerini ad alanı oluşturur. Çakışan kökler ve yinelenen etiketler, yinelenen koleksiyon veya imleç bozulmasını önlemek için reddedilir. Ekstra yol yapılandırması, daemon yeniden başlatması olmadan yeniden yüklenir. +Etiketler, iki kök aynı projenin kopyalarını içerdiğinde türetilen ajan kimliklerinin ad alanlarını verir. Çakışan kökler ve yinelenen etiketler, yinelenen koleksiyon veya imleç bozulmasını önlemek için reddedilir. Ekstra yol yapılandırması, daemon yeniden başlaması olmadan yeniden yüklenir. -Kapsayıcı ortamları, dosya yapılandırılmış ekstra yolları `FAILPROOFAI__EXTRA_PATHS` adlı virgülle ayrılmış bir değişkenle değiştirebilir, örneğin: +Konteyner ortamları, dosya yapılandırılmış ekstra yolları virgülle ayrılmış bir değişkenle değiştirebilir; örneğin: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -112,28 +130,30 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Ortam değişkenleri -Kalıcı makine davranışı için yapılandırma dosyalarını kullan. Ortam değişkenleri kapsayıcılar, testler ve bir işlem için en yararlıdır. +Kalıcı makine davranışı için yapılandırma dosyalarını kullanın. Ortam değişkenleri konteynerler, testler ve bir süreç için en kullanışlıdır. | Değişken | Kullanım | | --- | --- | -| `FAILPROOFAI_HOME` | Tam `~/.failproofai` düzenini yeniden konumlandır | -| `FAILPROOFAI_LOG_LEVEL` | Yerel günlüğe kaydetme ayrıntılılığını ayarla | -| `FAILPROOFAI_HOOK_LOG_FILE` | Hook tanılamalarını seçilen bir dosyaya yaz | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Bu işlem için anonim telemetriyi devre dışı bırak | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Etkileşimli ilk çalıştırma kurulumunu atla | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Kurulum sonrası yerel denetimi atla | -| `FAILPROOFAI_LLM_BASE_URL` | LLM politikaları tarafından kullanılan OpenAI uyumlu uç noktasını geçersiz kıl | -| `FAILPROOFAI_LLM_API_KEY` | LLM politikaları tarafından kullanılan API anahtarını sağla | -| `FAILPROOFAI_LLM_MODEL` | LLM politikaları tarafından kullanılan modeli seç | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Özel politika modülü yüklemesini sınırla | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Paketleri ve daemon ikililerini getirmeyi reddet; kurulu olan enforsu sağlamaya devam eder | -| `FAILPROOFAI_PACK_BASE_URL` | Paketleri `github.com` yerine bir yansıdan getir | -| `FAILPROOFAI__EXTRA_PATHS` | Bir harness için yapılandırılmış ekstra yakalama yollarını değiştir | -| `NO_COLOR` | Renkli terminal çıkışını devre dışı bırak | - -Agent'a özgü home değişkenleri `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` ve `OPENCLAW_HOME` gibi, Failproof AI'ın bu harness için yerel oturumları nerede keşfettiğini geçersiz kılar. - -## Bir makineyi güvenli bir şekilde duraklatabilir veya kaldırabilir +| `FAILPROOFAI_CLOUD_TOKEN` | Cloud anahtarı, `--token` yerine. Bunu tercih edin: bir argüman, kutudaki her kullanıcı tarafından `ps` aracılığıyla okunabilir. Bunu `read -s` ile veya CI gizli mağazasından ayarlayın, asla anahtarı bir komuta yazarak, hangi durumda da kabuk geçmişine düşer | +| `FAILPROOFAI_CLOUD_URL` | Cloud URL'si, `--url` yerine. Daemon'ın okuduğu aynı değişken | +| `FAILPROOFAI_HOME` | Tüm `~/.failproofai` düzenini taşıyın | +| `FAILPROOFAI_LOG_LEVEL` | Yerel günlük ayrıntısını ayarlayın | +| `FAILPROOFAI_HOOK_LOG_FILE` | Kanca tanılamalarını seçili bir dosyaya yazın | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Bu işlem için anonim telemetriyi devre dışı bırakın | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Etkileşimli ilk çalıştırma kurulumunu atlayın | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Kurulum sonrası yerel denetimi atlayın | +| `FAILPROOFAI_LLM_BASE_URL` | LLM politikaları tarafından kullanılan OpenAI uyumlu uç noktayı geçersiz kılın | +| `FAILPROOFAI_LLM_API_KEY` | LLM politikaları tarafından kullanılan API anahtarını sağlayın | +| `FAILPROOFAI_LLM_MODEL` | LLM politikaları tarafından kullanılan modeli seçin | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Özel politika modülü yüklenmesini sınırlandırın | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Paketleri ve daemon ikililerini getirmeyi reddedin; yüklü olanlar uygulamaya devam eder | +| `FAILPROOFAI_PACK_BASE_URL` | `github.com` yerine bir yansıdan paketleri getirin | +| `FAILPROOFAI__EXTRA_PATHS` | Bir ağ için yapılandırılmış ekstra yakalama yollarını değiştirin | +| `NO_COLOR` | Renkli terminal çıktısını devre dışı bırakın | + +`CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` ve `OPENCLAW_HOME` gibi ajana özel ana değişkenler, Failproof AI'nin bu ağ için yerel oturumları nerede keşfettiğini geçersiz kılar. + +## Bir makineyi güvenli bir şekilde duraklatın veya kaldırın ```bash failproofai config --pause @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -Yerel oturum duraklatması, Cloud tarafından yönetilen politikaları devre dışı bırakmaz. Sorun rollout'ın kendisi olduğunda Cloud dağıtımlarını Cloud zorlama iş akışı aracılığıyla geri yükle. +Yerel oturum duraklaması Cloud tarafından yönetilen politikaları devre dışı bırakmaz. Cloud dağıtımlarını Cloud uygulama iş akışı aracılığıyla geri yükleyin; sorun rollout'ün kendisiyse. -npm paketini kaldırmadan önce yüklenmiş hook'ları ve daemon'ı kaldırabilir: +npm paketini kaldırmadan önce, yüklenmiş kancaları ve daemon'ı kaldırın: ```bash failproofai uninstall --dry-run @@ -151,8 +171,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -Sürüme özgü ayrıntılar için `failproofai --help` komutunu çalıştırabilir. +Sürüme özel ayrıntılar için `failproofai --help` çalıştırın. - `npm rm -g failproofai` öncesinde `failproofai uninstall` komutunu çalıştırabilir; npm yüklenmiş agent hook'larını veya daemon hizmetini kaldırmaz. + `npm rm -g failproofai` öncesinde `failproofai uninstall` çalıştırın; npm yüklenmiş ajan kancalarını veya daemon hizmetini kaldırmaz. \ No newline at end of file diff --git a/docs/tr/reference/harnesses.mdx b/docs/tr/reference/harnesses.mdx index 440450f5..4105c451 100644 --- a/docs/tr/reference/harnesses.mdx +++ b/docs/tr/reference/harnesses.mdx @@ -1,80 +1,86 @@ --- -title: "Agent araçları" -description: "12 desteklenen agent aracında oturumları yakalayın ve politikaları uygulatın." +title: "Agent arayüzleri" +description: "12 desteklenen agent arayüzünde oturumları yakala ve politikaları uygula." icon: "plug-zap" --- -Araç (harness), aracınızın çalıştığı ortamdır. Failproof AI on ikiini destekler, iki sınıfta: +Bir arayüz, agendinizin gerçekte içinde çalıştığı ortamdır. Failproof AI bunlardan on ikisini destekler, iki sınıfta: -- **Kod CLI'ları** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Sohbet ve asistan ağ geçitleri** (2) — Hermes (Slack, Telegram, cron), OpenClaw (kendi kendine barındırılan asistan) +- **Kodlama CLI'ları** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **Sohbet ve asistan ağ geçitleri** (2) — Hermes (Slack, Telegram, cron), OpenClaw (kendi barındırılan asistan) -Hangi araçta çalıştırılırsa çalıştırılsın aynı politikalar ve aynı oturum geçmişi uygulanır. Tek bir adaptör katmanı, her aracın yerel olay adlarını, araç adlarını ve araç giriş alanlarını herhangi bir politika çalışmadan önce 29 kanonik olaya eşler. +Aynı politikalar ve aynı oturum geçmişi, agendin hangi arayüzde çalıştığına bakılmaksızın geçerlidir. Bir adaptör katmanı, her arayüzün yerel olay adlarını, araç adlarını ve araç giriş alanlarını, herhangi bir politika çalışmadan önce 29 kurallı olaya eşler. -**Hiçbir** on iki araçta çalışmayan bir aracı doğrudan [Python SDK](/tr/reference/custom-agents) ile enstrümante edersiniz. Bu, farklı bir kontrat ve açıkça belirtilmeye değerdir: SDK, izleme, oturumlar, değerlendirmeler ve denetimler sağlar — **kendi başına politikaları uygulamaz.** Güvensiz bir işlemi yürütülmeden önce engellemek, çalışma zamanınızın araç sınırında bir uygulama kancası gerektirir; [bize ulaşın](mailto:support@befailproof.ai) ve bunu eşleştireceğiz. +On ikinin **hiçbirinde** çalışmayan bir agent, doğrudan [Python SDK](/tr/reference/custom-agents) ile enstrümente edilir. Bu farklı bir sözleşmedir ve açıkça belirtmeye değer: SDK izleme, oturumlar, değerlendirmeler ve denetimler sağlar — **kendi başına politikaları uygulamaz.** Güvensiz bir eylemi yürütülmeden önce engellemek, çalışma zamanınızın araç sınırında bir zorlama kancası gerektirir; [bize ulaşın](mailto:support@befailproof.ai) ve biz bunu eşleriz. -| Araç | Desteklenen kanca kapsamları | +| Arayüz | Desteklenen kanca kapsamları | | --- | --- | | Claude Code | Kullanıcı, proje, yerel | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | Kullanıcı, proje | | Factory Droid, Devin CLI, Antigravity CLI, Goose | Kullanıcı, proje | | Hermes, OpenClaw | Kullanıcı | -Her entegrasyon, politikalar çalışmadan önce yerel kanca olay adlarını, araç adlarını ve araç giriş alanlarını normalleştirir. Bir politika, yalnızca aracın ortaya koyduğu olaylara etki edebilir; uygulayacağınız tam aracı ve sürümde sıranın sonu ve talimat davranışını test edin. +Her entegrasyon, politikalar çalışmadan önce yerel kanca olay adlarını, araç adlarını ve araç giriş alanlarını normalleştirir. Bir politika yalnızca arayüzün açığa çıkardığı olaylara göre hareket edebilir; tam olarak dağıttığınız arayüz ve sürüm üzerinde dönem sonu ve talimat davranışını test edin. -## Uygulama yeteneği +## Zorlama yeteneği -"Engelle", adlandırılmış aracı tarafından tüketilen geçerli adaptörün döndürdüğü kararı ifade eder. Araç sonrası engelleme, modele gösterilen sonucu değiştirebilir ancak zaten gerçekleşen bir araç yan etkisini geri alamaz. +"Engelle" ile kastedilen, mevcut adaptörün döndürülen kararının adlandırılan arayüz tarafından tüketilmesidir. Araç sonrası engelleme, modele gösterilen sonucu değiştirebilir ancak zaten gerçekleşmiş bir araç yan etkisini geri alamaz. -| Araç | Doğrulanmış engelleme olayları | Yalnızca gözlem veya engellemeyen uyarılar | +| Arayüz | Doğrulanmış engelleme olayları | Yalnızca gözlemli veya engelleme olmayan uyarılar | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` ve birkaç görev/yapılandırma olayı | `PostToolUse`, oturum yaşam döngüsü, bildirimler ve başarısız sonra olayları gözlemcidir. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Araç sonrası engelleme, yürütmeden sonra sonucu değiştirir; oturum başlangıcı ve kompakt olayları geçerli adaptörde gözlemcidir. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Araç sonrası engelleme, yürütmeden sonra sonucu değiştirir; oturum ve bildirim olayları gözlemcidir. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` ve oturum olayları gözlemcidir. | -| OpenCode | `PreToolUse` | Araç sonrası ve yaşam döngüsü olayları gözlemcidir; geçerli durma işleme, doğrulanmış bir kapı yerine sonraki sıra için rehberlik. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Araç sonrası ve yaşam döngüsü olayları gözlemcidir; durma rehberliği sonraki sıraya uygulanır. | -| Hermes | `PreToolUse` | Araç sonrası, oturum ve alt-araç-durdurma kararları kapı değildir. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Araç sonrası, oturum, alt-araç-durdurma ve sıkıştırma olayları gözlemcidir. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Araç sonrası ve alt-araç-durdurma kararları gözlemcidir. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, koşullu `PermissionRequest` | İzin kankaları her izin modunda çalışmaz; araç sonrası ve oturum olayları gözlemcidir. | -| Antigravity CLI | `PreToolUse`, `Stop` | Kullanıcı istemi ve araç sonrası kararları gözlemcidir; impt talimatları yine de enjekte edilebilir. | -| Goose | `PreToolUse` | Kullanıcı istemi, araç sonrası ve oturum olayları gözlemcidir. Kendi kendine engelleme durması kancası hızda mevcuttur ancak geçerli adaptör tarafından kurulmamıştır. | - -Yetenekler sürüme duyarlıdır. Agent CLI'ı yükselttikten sonra, özellikle bir politika ortak araç öncesi kapı yerine istem, durma, izin veya araç sonrası davranışına dayandığında yeniden test edin. +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` ve birkaç görev/yapılandırma olayı | `PostToolUse`, oturum yaşam döngüsü, bildirimler ve başarısızlık sonrası olaylar gözlemci niteliğindedir. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Araç sonrası engelleme yürütülmeden sonra sonucu değiştirir; oturum başlangıcı ve kompakt olaylar mevcut adaptörde gözlemci niteliğindedir. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Araç sonrası engelleme yürütülmeden sonra sonucu değiştirir; oturum ve bildirim olayları gözlemci niteliğindedir. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` ve oturum olayları gözlemci niteliğindedir. | +| OpenCode | `PreToolUse` | Araç sonrası ve yaşam döngüsü olayları gözlemci niteliğindedir; mevcut durdurma işlemi doğrulanmış bir kapı yerine daha sonraki bir dönem için rehberliktir. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Araç sonrası ve yaşam döngüsü olayları gözlemci niteliğindedir; durdurma rehberliği daha sonraki bir döneme uygulanır. | +| Hermes | `PreToolUse` | Araç sonrası, oturum ve subagent durdurma kararları kapı değildir. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Araç sonrası, oturum, subagent durdurma ve sıkıştırma olayları gözlemci niteliğindedir. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Araç sonrası ve subagent durdurma kararları gözlemci niteliğindedir. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, koşullu `PermissionRequest` | İzin kankaları her izin modunda çalışmaz; araç sonrası ve oturum olayları gözlemci niteliğindedir. | +| Antigravity CLI | `PreToolUse`, `Stop` | Kullanıcı istemi ve araç sonrası kararlar gözlemci niteliğindedir; komut satırı talimatları yine de enjekte edilebilir. | +| Goose | `PreToolUse` | Kullanıcı istemi, araç sonrası ve oturum olayları gözlemci niteliğindedir. Yerel bir engelleme durdurma kancası hizla mevcuttur ancak mevcut adaptör tarafından yüklenmez. | + +Yetenekler sürüme duyarlıdır. Bir agent CLI'sını yükselttikten sonra yeniden test edin, özellikle bir politika ortak ön araç kapısından ziyade komut satırı, durdurma, izin veya araç sonrası davranışına bağlıysa. ## Yakalama ve politika kankaları yükleyin - - 1. **Yönetim → Anahtarlar**'ı açın ve `events:add` ve `policies:pull` ile makine veya ortam için adlandırılmış bir anahtar oluşturun. - 2. Hedef makinede, yerel CLI'ı görüntülenen anahtarla bağlayın ve araç kankaları yükleyin. - 3. Yeni bir agent oturumu başlatın, ardından **Gözlem → Olaylar** altında kanca ve oturum olaylarını onaylayın. - 4. Aynı zaman penceresi için **Gözlem → Politika**'yı açın ve bir politika kararının makineye atfedildiğini onaylayın. + + 1. **Yönetim → Anahtarları** açın ve `events:add` ve `policies:pull` izinleriyle, makine veya ortam için adlandırılmış bir anahtar oluşturun. + 2. Hedef makinede, yerel CLI'ı gösterilen anahtarla bağlayın ve arayüz kankaları yükleyin. + 3. Yeni bir agent oturumu başlatın, ardından **Gözlemle → Olaylar** altında kanca ve oturum olaylarını doğrulayın. + 4. Aynı zaman penceresi için **Gözlemle → politika** seçeneğini açın ve bir politika kararının makineye atandığını doğrulayın. - Bağlantı, bir makine anahtarıyla başlar. Kopyalamadan önce hem alım hem de politika-teslimat izinlerini içerdiğini onaylayın. + Bağlantı bir makine anahtarı ile başlar. Gizli anahtarını kopyalamadan önce hem içe alma hem de politika teslimi izinlerini içerdiğini doğrulayın. - ![Olay alımı ve politika teslimatı izinleri vermek için kullanılan yeni API anahtar çekmeceesi.](/images/dashboard/key-create.png) + ![Olay içe alma ve politika teslimi izinleri vermek için kullanılan yeni API anahtar çekme kutusu.](/images/dashboard/key-create.png) Kankaları yükledikten sonra, Olaylar akışı bağladığınız makineden ve ortamdan yeni olayları göstermelidir. - ![Yeni yüklenen bir araçın rapor verdiğini onaylamak için kullanılan canlı Olaylar akışı.](/images/dashboard/events-stream.png) + ![Yeni yüklenen bir arayüzün raporlama yapması gerektiğini doğrulamak için kullanılan canlı Olaylar akışı.](/images/dashboard/events-stream.png) - Son olarak, politika kararlarının aynı makineye atfedildiğini doğrulayın. Bu, araçın izleme olaylarının yanı sıra politika etkinliğini de bildirdiğini doğrular. + Son olarak, politika kararlarının aynı makineye atandığını doğrulayın. Bu, arayüzün politika etkinliğinin yanı sıra izleme olaylarını da raporlama yapması gerektiğini doğrular. - ![Yeni bağlı bir araçtan politika kararlarını doğrulamak için kullanılan Politika sayfası.](/images/dashboard/policy-observe.png) + ![Yeni bağlanan bir arayüzden politika kararlarını doğrulamak için kullanılan Politika sayfası.](/images/dashboard/policy-observe.png) - Algılanan her araç için kankaları yükleyin: + Makine anahtarını kabuğa okuyun. `read -s`, onu yankılamayan bir istemde alır, böylece hiçbir zaman bir komutta veya kabuk geçmişinde görünmez: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Veya adlandırılmış araçları ve bir yapılandırma kapsamını hedefleyin: + Ardından makineyi ayarlayın — bu, tespit edilen her arayüz için kankaları bağlar, daemonu yükler ve Buluta bağlanır: + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + Kurulum kendi başına hiçbir politikayı etkinleştirmez, bu ikinci komutun amacı budur. + + Veya adlandırılmış arayüzleri ve yapılandırma kapsamını hedefleyin: ```bash failproofai policies --install \ @@ -82,7 +88,7 @@ Yetenekler sürüme duyarlıdır. Agent CLI'ı yükselttikten sonra, özellikle --scope user ``` - Proje kapsamı, kanca yapılandırmasını bir depoyla tutar. Kullanıcı kapsamı, depolar arasında çalışmayı kapsar. Claude Code, yerel kapsamı da destekler; destek aracı tarafından değişir ve CLI, desteklenmeyen kombinasyonları reddeder. + Proje kapsamı, kanca yapılandırmasını bir depoda tutar. Kullanıcı kapsamı depolar arasında çalışmayı kapsar. Claude Code ayrıca yerel kapsamı destekler; destek arayüze göre değişir ve CLI desteklenmeyen kombinasyonları reddeder. Makineyi ve olaylarını doğrulayın: @@ -97,13 +103,13 @@ Yetenekler sürüme duyarlıdır. Agent CLI'ı yükselttikten sonra, özellikle ## Varsayılan olmayan bir oturum yolu ekleyin - - Ekstra yollar, Bulut'ta değil, makinede kaydedilir. Bir tane ekledikten sonra, **Gözlem → Oturumlar**'ı açın, ortamı makineye filtreleyin ve yeni yoldan gelen oturumların göründüğünü onaylayın. Bir oturumu açın ve buna güvenmeden önce aracıyı, aracı ve olay zaman damgalarını kontrol edin. + + Ekstra yollar makinede kaydedilir, Bulutta değil. Bir tane ekledikten sonra **Gözlemle → Oturumlar** seçeneğini açın, makine ortamına göre filtreleyin ve yeni yoldan oturumlar göründüğünü doğrulayın. Bir oturumu açın ve denetimde buna güvenmeden önce agent, arayüz ve olay zaman damgalarını kontrol edin. - ![Ek yakalama yolundan veri alan ortama filtrellenen Oturumlar listesi.](/images/dashboard/sessions-list.png) + ![Ek yakalama yolundan veri alan ortama filtrelenen Oturumlar listesi.](/images/dashboard/sessions-list.png) - İsteğe bağlı bir etiketle bir yol ekleyin, ardından yapılandırılan yolları inceleyin: + İsteğe bağlı bir etiketle bir yol ekleyin, ardından yapılandırılmış yolları inceleyin: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -112,10 +118,10 @@ Yetenekler sürüme duyarlıdır. Agent CLI'ı yükselttikten sonra, özellikle failproofai backfill --since 7d ``` - `failproofai harness remove-path claude checkout` ile bir yolu kaldırın. + `failproofai harness remove-path claude checkout` komutuyla bir yolu kaldırın. - Yüklemeden sonra bir yeni oturum çalıştırın. Dağıtımı genişletmeden önce hem canlı olay akışını hem de gerçek bir politika kararını doğrulayın. + Kurulumdan sonra bir yeni oturum çalıştırın. Dağıtımı genişletmeden önce hem canlı olay akışını hem de gerçek bir politika kararını doğrulayın. \ No newline at end of file diff --git a/docs/tr/reference/overview.mdx b/docs/tr/reference/overview.mdx index ea70c56d..e3366e56 100644 --- a/docs/tr/reference/overview.mdx +++ b/docs/tr/reference/overview.mdx @@ -1,81 +1,84 @@ --- title: "Entegrasyonlar ve referans" -description: "Desteklenen agent harness'leri, SDK'ları, CLI'ları ve HTTP API'sini bağlayın." +description: "Desteklenen agent harness'ları, SDK'ları, CLI'ları ve HTTP API'sini bağlayın." icon: "braces" --- -Agenizin zaten çalıştığı yere en yakın entegrasyonu seçin. +Agent'inizin zaten çalıştığı yere en yakın entegrasyonu seçin. - - Desteklenen kodlama ve özerk agent CLI'ları için hook'ları yükleyin. + + Desteklenen kodlama ve otonom agent CLI'ları için hook'lar yükleyin. - - LangGraph, CrewAI, LlamaIndex, Pydantic AI veya özel bir agent'ı araçlandırın. + + LangGraph, CrewAI, LlamaIndex, Pydantic AI veya özel bir agent'i enstrüman edin. - Konfigürasyon, olay kataloğu, korelasyon kuralları ve teslimat. + Konfigürasyon, etkinlik kataloğu, korelasyon kuralları ve teslimat. Yerel projeleri, oturumları, politika aktivitesini ve çevrimdışı denetimleri gözden geçirin. - Yerel yakalaması, hook'ları, politikaları, denetimleri, teslimati ve makine durumunu yapılandırın. + Yerel yakalama, hook'lar, politikalar, denetimler, teslimat ve makine durumunu yapılandırın. Cloud oturumlarını, denetimleri, sorunları, uyarıları, anahtarları, kullanıcıları ve ayarları sorgulayın ve yönetin. - Tamamlanmış veya etkin olmayan oturumları FastAPI hizmeti ile puanlayın. + Tamamlanan veya inaktif oturumları FastAPI hizmeti ile puanlayın. İş akışına özgü allow, instruct ve deny kararlarını yazın ve test edin. - + Cloud kontrol düzlemini müşteri tarafından yönetilen bir Kubernetes kümesine dağıtın. -Oluşturulan [HTTP API referansı](/tr/reference/http-api), genel `/v1` yüzeyini kapsar. El yazısı sayfalar, birden çok endpoint'i kapsayan veya bu genel yüzeyin dışında idari arayüzleri kullanan iş akışlarını açıklar. +Oluşturulan [HTTP API referansı](/tr/reference/http-api), genel `/v1` yüzeyini kapsar. El ile yazılmış sayfalar, birden fazla uç noktaya yayılan veya söz konusu genel yüzeyin dışında yönetim arabirimleri kullanan iş akışlarını açıklar. -## Bir agent'ı bağlayın ve verileri doğrulayın +## Agent'i bağlayın ve verileri doğrulayın - 1. **Administration → Keys** bölümünü açın, `events:add` ve `policies:pull` izinlerine sahip bir anahtar oluşturun ve parolayı kopyalayın. + 1. **Administration → Keys** seçeneğini açın, `events:add` ve `policies:pull` ile bir anahtar oluşturun ve sırrı kopyalayın. 2. Entegrasyonu yukarıdaki eşleşen sayfa kullanarak yapılandırın. - 3. Olayların gelişini doğrulamak için **Observe → Events** bölümünü açın, ardından bunların tam çalıştırılışlar oluşturduğunu doğrulamak için **Observe → Sessions** bölümünü açın. - 4. Entegrasyonun ortamına filtre uygulayın ve denetimler tarafından gerekli olan model, araç, hata ve politika alanları için bir oturumu inceleyin. + 3. **Observe → Events** seçeneğini açarak etkinliklerin geldiğini onaylayın, ardından **Observe → Sessions** seçeneğini açarak tam çalıştırımlar oluşturduğunu onaylayın. + 4. Entegrasyonun ortamına filtre uygulayın ve denetimler için gereken model, tool, error ve policy alanlarını incelemek için bir oturumu açın. - Anahtar çekmecesiyle başlayın. Seçilen izinler, makinenin olayları gönderip Cloud tarafından yönetilen politikaları alıp alamayacağını belirler. + Anahtar çekmeciyle başlayın. Seçilen yetkiler, makinenin etkinlik gönderebilmesini ve Cloud tarafından yönetilen politikaları alabilmesini belirler. - ![Etkinlik alımı ve politika teslim izinleri vermek için kullanılan yeni API anahtar çekmecesi.](/images/dashboard/key-create.png) + ![Etkinlik alımı ve politika teslimatı izinleri vermek için kullanılan yeni API anahtarı çekmeciği.](/images/dashboard/key-create.png) - Entegrasyonu bağladıktan sonra, olaylarının beklenen ortamda tam çalıştırılışlar halinde gruplandırıldığını doğrulamak için Sessions listesini kullanın. + Entegrasyonu bağladıktan sonra, etkinliklerinin beklenen ortamda tam çalıştırımlara gruplandırılıp gruplandırılmadığını doğrulamak için Sessions listesini kullanın. - ![Yeni bağlanmış bir entegrasyonun tam agent çalıştırılışlarını raporladığını doğrulamak için kullanılan Sessions listesi.](/images/dashboard/sessions-list.png) + ![Yeni bağlanan bir entegrasyonun tam agent çalıştırımlarını raporladığını doğrulamak için kullanılan Sessions listesi.](/images/dashboard/sessions-list.png) - Entegrasyonu tamamlanmış olarak değerlendirmeden önce bu oturumlardan birini açın; izleme, denetimlerinizin ihtiyaç duyduğu model, araç, hata ve politika kanıtlarını içermelidir. + Entegrasyonu tamamlanmış kabul etmeden önce bu oturumlardan birini açın; iz, denetimlerinizin ihtiyaç duyduğu model, tool, error ve policy kanıtlarını içermelidir. - Bir makine anahtarı oluşturun, Failproof daemon'unu bağlayın ve ilk oturumu doğrulayın. + Bir makine anahtarı oluşturun, ardından yazdığı sırrı shell'e okuyun. `read -s` bunu yankılanmayan bir istemde alır, bu nedenle bir komutta veya shell geçmişinde asla görünmez: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Failproof daemon'ını bağlayın ve ilk oturumu doğrulayın: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - Başka bir araç sonucu kullanacağında `fp --json sessions ...` komutunu kullanın. `--json`, `--org` ve `--base-url` gibi genel bayraklar komuttan önce gelmelidir. + Başka bir araç sonucu tüketecek olduğunda `fp --json sessions ...` kullanın. `--json`, `--org` ve `--base-url` gibi global bayraklar komuttan önce gelmelidir. - Yerel komutlar için [Failproof AI CLI referansı](/tr/reference/failproof-cli) ve `fp` komutları için [Failproof Cloud CLI referansı](/tr/reference/cloud-cli#cli-commands) bölümüne bakın. + Yerel komutlar için [Failproof AI CLI referansı](/tr/reference/failproof-cli) ve `fp` komutları için [Failproof Cloud CLI referansı](/tr/reference/cloud-cli#cli-commands) sayfalarına bakın. \ No newline at end of file diff --git a/docs/tr/reference/policy-sdk.mdx b/docs/tr/reference/policy-sdk.mdx index ef8e6fbf..10acbaf0 100644 --- a/docs/tr/reference/policy-sdk.mdx +++ b/docs/tr/reference/policy-sdk.mdx @@ -1,35 +1,35 @@ --- title: "Özel politikalar" -description: "Aracılarınıza özgü hatalar için JavaScript veya TypeScript politikaları yazın, test edin ve dağıtın." +description: "Aracılarınıza özel hata kalıplarını engellemek için JavaScript veya TypeScript politikaları yazın, test edin ve dağıtın." icon: "shield-plus" --- -Özel politikalar, izlemeleriniz veya denetimlerinizden bir hata modelini, bir aracı çalışırken çalışan bir karara dönüştürür. Bir politika bir işlemi izin verebilir, aracıya rehberlik sağlayabilir veya başka bir olaya neden olmadan işlemi reddedebilir. +Özel politikalar, izlemelerizdeki veya denetimlerinizden bir hata kalıbını bir aracı çalışırken çalışan bir karara dönüştürür. Bir politika bir işleme izin verebilir, aracıya rehberlik sağlayabilir veya başka bir olay meydana gelmeden önce işlemi reddedebilir. -Davranış aracınızın araçlarına, yollarına, komutlarına, ortamlarına veya işletme kurallarına bağlı olduğunda özel bir politika kullanın. Mevcut bir kontrolü yeniden oluşturmamak için önce [yerleşik politika kataloğunu](/tr/policies/builtin-catalog) kontrol edin. +Davranış araçlarınız, yollarınız, komutlarınız, ortamlarınız veya işletme kurallarınıza bağlı olduğunda özel bir politika kullanın. Mevcut bir kontrolü yeniden oluşturmamak için önce [Failproof AI politika paketini](/tr/policies/packs) kontrol edin. -## Özel politika yazma +## Özel politika yazın - 1. **Admin → policy editor** (politika editörü) sayfasına gidin, **New policy** (Yeni politika) seçin ve önlemek istediğiniz hatayı açıklayın. - 2. Politika kaynağını ekleyin, ardından editörde beklenen eşleşmeleri ve güvenli eşleşmeleri test edin. Her doğrulama hatasını çözün. - 3. taslağı kaydedin ve değişmez bir sürüm oluşturmak için **Publish version** (Sürümü yayımla) seçeneğini tıklayın. - 4. **Admin → enforcement** (uygulamaya zorlama) sayfasına gidin, sürümü test makinasına **observe** (gözlemle) modunda dağıtın ve **Observe → policy** (Gözlemle → politika) altında kararlarını doğrulamadan önce zorlayın. + 1. **Admin → policy editor** bölümüne gidin, **New policy** seçeneğini belirleyin ve önlemek istediğiniz hatayı açıklayın. + 2. Politika kaynak kodunu ekleyin, ardından editörde beklenen eşleşmeleri ve güvenli eşleşmeyenleri test edin. Her doğrulama hatasını çözün. + 3. taslağı kaydedin ve **Publish version** seçeneğini belirterek değişmez bir sürüm oluşturun. + 4. **Admin → enforcement** bölümüne gidin, sürümü test makinasına **observe** modunda dağıtın ve uygulamadan önce kararlarını **Observe → policy** bölümünde doğrulayın. - ![Özel bir politika yazmak ve yayımlamak için kullanılan politika editörü.](/images/dashboard/policy-editor.png) + ![Özel bir politika yazıp yayınlamak için kullanılan politika editörü.](/images/dashboard/policy-editor.png) 1. `.failproofai/policies/checkout-policies.ts` dosyasını oluşturun. Dosya adı `policies.js`, `policies.mjs` veya `policies.ts` ile bitmelidir. 2. `customPolicies.add()` ile bir veya daha fazla politika kaydedin. - 3. Dosyayı `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project` komutuyla doğrulayın ve yükleyin. - 4. Eşleşen bir işlem ve güvenli bir işlem tetikleyin. `failproofai policies` komutunu çalıştırın, ardından **Observe → policy** (Gözlemle → politika) altındaki atanmış kararları inceleyin. + 3. Dosyayı `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project` ile doğrulayın ve yükleyin. + 4. Eşleşen bir işlemi ve bir güvenli işlemi tetikleyin. `failproofai policies` komutunu çalıştırın, ardından **Observe → policy** bölümünde atfedilen kararları inceleyin. ## Dar bir kuralla başlayın -Bu politika, yalnızca komut üretimi hedeflediğinde yıkıcı Kubernetes komutlarını engeller. O kesin hata modu dışındaki her şey `allow()` döndürür. +Bu politika, komut üretimi hedeflediğinde yalnızca yıkıcı Kubernetes komutlarını engeller. Bu tam hata modu dışındaki her şey `allow()` döndürür. ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,20 +55,20 @@ customPolicies.add({ }); ``` -İyi politikalar bir cümle ile açıklanacak kadar dar olmalıdır. Umarım aracının niyeti olan değil gözlemlenebilir işlemi eşleştirin ve kural geçerli olmayınca hemen `allow()` döndürün. +İyi politikalar, bir cümle ile açıklanacak kadar dar olmalıdır. Gözlemlenebilen işlemi eşleştirin—aracının hangi niyeti olduğunu değil—ve kural uygulanmadığı anda `allow()` döndürün. ## Bir karar seçin | Yardımcı | Sonuç | Şu durumlarda kullanın | | --- | --- | --- | -| `allow(reason?)` | İşlem devam eder. | Politika geçerli değildir veya işlem güvenlidir. | -| `instruct(reason)` | İşlem, koşul aracı tarafından destekleniyorsa rehberlikle devam eder. | Aracıyı değişmezliği uygulamadan daha iyi bir yaklaşıma yönlendirmek istiyorsanız. | -| `deny(reason)` | Olay ve koşul engellemeyi destekliyorsa işlem engellenir. | İşlem ilerlememeli. | +| `allow(reason?)` | İşlem devam eder. | Politika uygulanmaz veya işlem güvenlidir. | +| `instruct(reason)` | İşlem, koşulu destekleyen yerlerde rehberlik ile devam eder. | Aracıyı bir değişkeni uygulamadan daha iyi bir yaklaşıma yönlendirmek istediğinizde. | +| `deny(reason)` | Olay ve koşul engellemeyi desteklediğinde işlem engellenir. | İşlem devam etmemelidir. | -Kurtarması gereken aracı için sebebi yazın. Ne tespit edildiğini ve bunun yerine ne yapması gerektiğini açıklayın. +Aracının kurtarması gereken nedeni yazın. Neyin tespit edildiğini ve bunun yerine ne yapması gerektiğini açıklayın. - Bir güvenlik sınırı için `instruct()` kullanmayın. Rehberlik sunumu, aracı koşuluna göre değişir. İşlem önlenmelidir. `deny()` kullanın. + Güvenlik sınırı için `instruct()` kullanmayın. Rehberlik sunumu, aracı koşuluna göre değişir. İşlem engellenmelidir `deny()` kullanın. ## Politika nesnesi @@ -84,32 +84,32 @@ customPolicies.add({ | Alan | Gerekli | Açıklama | | --- | --- | --- | -| `name` | Evet | Politika için kararlı tanımlayıcı. Dosyalar arasında adları benzersiz tutun. | -| `description` | Hayır | Politika listelerinde ve kararlarda gösterilen insan tarafından okunabilir amaç. | -| `match.events` | Hayır | Politikayı çağıran olay türleri. `match` atlarsanız, her kullanılabilir olay için çağrılır. | -| `fn` | Evet | `allow`, `instruct` veya `deny` sonucu döndüren eşzamanlı veya asenkron işlev. | +| `name` | Evet | Politika için sabit tanımlayıcı. Adları dosyalar arasında benzersiz tutun. | +| `description` | Hayır | Politika listelerinde ve kararlarda gösterilen okunabilir amaç. | +| `match.events` | Hayır | Politikayı çağıran olay türleri. `match` atlanırsa her kullanılabilir olay için çağrılır. | +| `fn` | Evet | `allow`, `instruct` veya `deny` sonucu döndüren eşzamanlı veya eşzamansız işlev. | -`fn` içinde araçları filtreleyin. `match.toolNames`, genel özel politika türünün bir parçası değildir. +Araçları `fn` içinde filtreleyin. `match.toolNames` özel politika türünün parçası değildir. ## Politika bağlamı Her politika bir `PolicyContext` alır. -| Alan | Tür | İçerdiği şey | +| Alan | Tür | İçeriği | | --- | --- | --- | | `eventType` | `HookEventType` | Şu anda değerlendirilen normalleştirilmiş olay. | | `toolName` | `string \| undefined` | `Bash`, `Read`, `Write` veya `Edit` gibi kanonik araç adı. | -| `toolInput` | `Record \| undefined` | Geçerli araç çağrısı için kanonik giriş. | -| `payload` | `Record` | Tamamlanmış normalleştirilmiş olay yükü. | -| `session` | `SessionMetadata \| undefined` | Oturum kimliği, çalışma dizini, transkript yolu, izin modu ve mevcut olduğunda koşul meta verileri. | +| `toolInput` | `Record \| undefined` | Mevcut araç çağrısı için kanonik giriş. | +| `payload` | `Record` | Tam normalleştirilmiş olay yükü. | +| `session` | `SessionMetadata \| undefined` | Mevcut olduğunda oturum ID'si, çalışma dizini, transkript yolu, izin modu ve koşul meta verileri. | | `cli` | `string \| undefined` | `claude`, `codex` veya `cursor` gibi kaynak aracı koşulu. | | `params` | `Record` | Yerleşik politika parametreleri. Özel politikalar şu anda boş bir nesne alır. | -Her isteğe bağlı değeri gerçekten isteğe bağlı olarak değerlendirin. Aracı sürümleri ve olay türleri aynı alanları sağlamaz. +Her isteğe bağlı değeri gerçekten isteğe bağlı olarak ele alın. Aracı sürümleri ve olay türleri aynı alanları sağlamaz. -### Yaygın araç girdileri +### Ortak araç girdileri -Failproof AI, desteklenen koşullar arasında yaygın araçları normalleştirir, böylece bir politika genellikle bir giriş şekli kullanabilir. +Failproof AI, desteklenen koşullar arasında ortak araçları normalleştirir, böylece bir politika genellikle bir giriş şeklini kullanabilir. | Araç | Ortak alanlar | | --- | --- | @@ -119,34 +119,34 @@ Failproof AI, desteklenen koşullar arasında yaygın araçları normalleştirir | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | -Araç giriş değerleri `unknown` olarak yazıldığı için savunmacı zorlama kullanın: +Araç giriş değerleri `unknown` olarak yazıldığından koruyucu zorlama kullanın: ```ts const command = String(ctx.toolInput?.command ?? ""); const filePath = String(ctx.toolInput?.file_path ?? ""); ``` -## Olayı seçin +## Etkinliği seçin -| Olay | Ne zaman çalıştırılır | Tipik kullanım | +| Olay | Ne zaman çalışır | Tipik kullanım | | --- | --- | --- | -| `PreToolUse` | Bir araç çalıştırılmadan önce. | Komutları, yazıları, okumaları ve dış işlemleri engelleyin veya rehberlik sağlayın. | -| `PostToolUse` | Bir araç sonucu döndürdükten sonra. | Sonuçları aracıya ulaşmadan önce inceleyin. Bir reddetme tüm sonucu engeller; seçilen alanları redakte etmez. | -| `PermissionRequest` | Aracı izin talep ettiğinde. | Kuruluşa özgü izin kuralları uygulayın. | -| `UserPromptSubmit` | Gönderilen bir istem devam etmeden önce. | Yasaklanmış talimatları reddedin veya iş akışı rehberliği ekleyin. | -| `Stop` | Aracı bitirmeyi denediğinde. | Yerel doğrulama adımı gibi erişilebilir bir tamamlanma koşulu gerektir. | -| `SubagentStop` | Bir alt aracı bitirmeyi denediğinde. | Yetkilendirilmiş işi ebeveyne dönmeden önce kontrol edin. | -| `SessionStart` / `SessionEnd` | Oturum sınırlarında. | Oturum düzeyindeki durumu kaydedin veya kontrol edin. | +| `PreToolUse` | Bir araç yürütülmeden önce. | Komutları, yazıları, okumaları ve dış işlemleri engelle veya yönlendir. | +| `PostToolUse` | Bir araç döndükten sonra. | Sonuçları aracıya ulaşmadan önce incele. Bir reddetme tüm sonucu engeller; seçilen alanları redakte etmez. | +| `PermissionRequest` | Aracı izin istediğinde. | Kuruluşa özgü izin kurallarını uygula. | +| `UserPromptSubmit` | Gönderilen bir istem devam etmeden önce. | Yasak talimatları reddet veya iş akışı rehberliği ekle. | +| `Stop` | Aracı bitirmeye çalıştığında. | Yerel doğrulama adımı gibi ulaşılabilir bir tamamlama koşulu iste. | +| `SubagentStop` | Bir alt aracı bitirmeye çalıştığında. | Devredilen çalışmayı ebeveyne dönmeden önce kontrol et. | +| `SessionStart` / `SessionEnd` | Oturum sınırlarında. | Oturum düzeyi durumunu kaydet veya kontrol et. | -Olay kullanılabilirliği ve engelleme davranışı aracı koşuluna bağlıdır. Karışık bir filo arasında bir olaya güvenmeden önce [Aracı koşulları](/tr/reference/harnesses) makalesine bakın. +Olay kullanılabilirliği ve engelleme davranışı aracı koşuluna bağlıdır. Karma bir filo arasında bir olaya güvenmeden önce [Aracı koşulları](/tr/reference/harnesses) bölümüne bakın. `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` ve `Setup`. -## Yaygın politika modellerini yazın +## Ortak politika kalıplarını yazın -### Korumalı yollara yazıları engelle +### Korunan yollara yazmaları engelle ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -166,7 +166,7 @@ customPolicies.add({ }); ``` -### Engel olmayan rehberlik sağla +### Bloke edilmeden rehberlik ver ```ts import { customPolicies, allow, instruct } from "failproofai"; @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### Oturum tamamlanmasını kapıyı koru +### Oturum tamamlanmasını kontrol et ```ts import { execFileSync } from "node:child_process"; @@ -215,7 +215,7 @@ customPolicies.add({ ``` - Reddedilen bir `Stop` olayı aracıyı yeniden denemeye yapabilir. Yalnızca aracının geçerli ortamda karşılayabileceği bir koşulda kapıyı koruyun ve her alt işlem veya ağ çağrısını sınırlayın. + Reddedilen `Stop` olayı aracının yeniden denemesini sağlayabilir. Yalnızca aracının mevcut ortamda yerine getirebileceği bir koşul üzerinde engelle ve her alt işlem veya ağ çağrısını sınırla. ## Politika dosyalarını yükle @@ -233,12 +233,12 @@ Kural dosyaları otomatik olarak yüklenir: - Dosyalar her dizin içinde alfabetik olarak yüklenir. - Bir dosya `policies.js`, `policies.mjs` veya `policies.ts` ile bitmelidir. - Bir dosyada birden fazla `customPolicies.add()` çağrısı desteklenir. -- Yerel modüllerden göreceli içe aktarmalar desteklenir. -- Proje politikaları kaydedilebilir, böylece aynı kurallar depoyu takip eder. +- Yerel modüllerden göreli içeri aktarmalar desteklenir. +- Proje politikaları kaydedilebilir, böylece aynı kurallar depo takip eder. ### Açık dosyalar -Doğrulama veya yapılandırma, giriş dosyasını doğrudan adlandırmalı olduğunda açık yolları kullanın: +Doğrulama veya yapılandırmanın giriş dosyasını doğrudan adlandırması gerektiğinde açık yollar kullanın: ```bash failproofai policies --install \ @@ -247,11 +247,11 @@ failproofai policies --install \ --scope project ``` -Açık dosyalar önce yüklenir, ardından proje kural dosyaları ve sonra kullanıcı kural dosyaları gelir. Her iki yol aracılığıyla keşfedilen bir dosya bir kez yüklenir. +Açık dosyalar önce yüklenir, ardından proje kural dosyaları ve sonra kullanıcı kural dosyaları gelir. Her iki yoldan da keşfedilen bir dosya bir kez yüklenir. ## Doğrula ve test et -Doğrulama, modülü üretim yükleyicisi aracılığıyla yürütür ve en az bir politika kaydettiğini onaylar. +Doğrulama, modülü üretim yükleyicisinden geçirir ve en az bir politika kaydettiğini onaylar. ```bash failproofai policies --install \ @@ -260,44 +260,44 @@ failproofai policies --install \ failproofai policies ``` -Doğrulama, eksik dosyaları, sözdizimi hatalarını, çözülmemiş içe aktarmaları, üst düzey istisnalar ve modül yükleme zaman aşımlarını yakalar. Match mantığınızın doğru olduğunu kanıtlamaz. +Doğrulama, eksik dosyaları, söz dizimi hatalarını, çözülmemiş içeri aktarmaları, üst düzey istisnaları ve modül yükleme zaman aşımlarını yakalar. Bu, eşleşme mantığının doğru olduğunu kanıtlamaz. -En azından bu durumları test edin: +En az bu durumları test edin: -- Eşleşmesi gereken ve amaçlanan politika sebebini üreten bir işlem. -- Yakınlarda ancak güvenli olan `allow()` döndürmesi gereken bir işlem. -- Eksik veya yanlış biçimlendirilmiş araç alanları. -- Alternatif komut sözdizimi, yollar, alıntılama, harf durumu ve boşluk. +- Eşleşmesi gereken ve amaçlanan politika nedenini üretmesi gereken bir işlem. +- Güvenli olması gereken, yakındaki ancak güvenli bir işlem `allow()` döndürmeli. +- Eksik veya hatalı araç alanları. +- Alternatif komut söz dizimi, yollar, tırnak işaretleri, büyük/küçük harf ve boşluk. - Kullanılamayan bir alt işlem veya ağ bağımlılığı. -Sonucu **Observe → policy** (Gözlemle → politika) altında özel politikanıza atayın. Farklı bir yerleşik politika kararı verirse, engellenen bir test yeterli değildir. +Sonucu **Observe → policy** bölümünde özel politikaya atfet. Farklı bir yerleşik politika kararı aldıysa engellenen bir test yeterli değildir. ## Çalışma zamanı davranışı - Yerleşik politikalar özel politikalardan önce değerlendirilir. - İlk `deny` daha fazla politika değerlendirmesini durdurur. -- Hiçbir politika olayı reddetmediğinde birden fazla `instruct` sonucu birleştirilebilir. -- Bir politika işlevinin 10 saniyelik bir yürütme süresi vardır. -- Atılan bir istisna veya zaman aşımı günlüğe kaydedilir ve `allow()` olarak değerlendirilir. -- Başarısız olarak yüklenmiş bir kural dosyası atlanır; diğer özel dosyalar ve yerleşik politikalar devam eder. -- Üst düzey modül yükleme de 10 saniyelik bir süresi vardır. -- Bulut gözlemle modu politikayı çalıştırır ancak onu uygulamadan izin olmayan bir kararı kaydeder. +- Politika olayı reddetmediğinde birden fazla `instruct` sonucu birleştirilebilir. +- Bir politika işlevinin 10 saniyelik yürütme süresi limiti vardır. +- Atılan bir istisna veya zaman aşımı kaydedilir ve `allow()` olarak değerlendirilir. +- Yüklemeyi başarısız olan bir kural dosyası atlanır; diğer özel dosyalar ve yerleşik politikalar devam eder. +- Üst düzey modül yüklemenin de 10 saniyelik süresi limiti vardır. +- Bulut observe modu politikayı çalıştırır ancak uygulamadan bir non-allow kararını kaydeder. -Politika modüllerini belirli ve hızlı tutun. Üst düzey ağ çağrılarından veya sunucu başlatmadan kaçının. `fn` içindeki işi sınırlayın, bağımlılık başarısızlıklarını yakalayın ve bu başarısızlığın işleme izin verip vermeyeceğini veya reddetmesi gerekip gerekmediğini kasıtlı olarak seçin. +Politika modüllerini belirlenimci ve hızlı tutun. Üst düzey ağ çağrılarından veya sunucu başlatmadan kaçının. `fn` içinde çalışmayı sınırla, bağımlılık başarısızlıklarını yakala ve bu başarısızlığın işleme izin vermesi mi yoksa reddetmesi mi gerektiğine bilinçli olarak karar ver. ## API dışa aktarmaları | Dışa aktarma | Amaç | | --- | --- | -| `customPolicies.add(policy)` | Modül yüklenirken özel bir politika kaydedin. | -| `allow(reason?)` | İşleme izin verin. | -| `instruct(reason)` | İşleme izin verin ve destekleniyorsa rehberlik sağlayın. | -| `deny(reason)` | Destekleniyorsa işlemi engelleyin. | -| `getCustomHooks()` | Modül kayıt defterinde şu anda kayıtlı politikaları döndürün. | -| `clearCustomHooks()` | Bu kayıt defterini temizleyin, esas olarak testler ve yükleyiciler için. | +| `customPolicies.add(policy)` | Modül yüklendiğinde özel bir politika kaydet. | +| `allow(reason?)` | İşleme izin ver. | +| `instruct(reason)` | İşleme izin ver ve desteklenen yerlerde rehberlik sağla. | +| `deny(reason)` | Desteklenen yerlerde işlemi engelle. | +| `getCustomHooks()` | Modül kaydında şu anda kayıtlı olan politikaları döndür. | +| `clearCustomHooks()` | Bu kayıt defteri temizle, öncelikle testler ve yükleyiciler için. | -TypeScript `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` ve `PolicyFunction` dışa aktarımını sağlar. +TypeScript, `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` ve `PolicyFunction` dışa aktarır. - Bir sürümü yayımla, gözlemle modunda dağıt, kararları doğrula ve uygulamaya geçişi yap. + Bir sürüm yayınla, observe modunda dağıt, kararları doğrula ve uygulamaya taşı. \ No newline at end of file diff --git a/docs/tr/sessions/evaluations.mdx b/docs/tr/sessions/evaluations.mdx index da1f9079..e28fcd90 100644 --- a/docs/tr/sessions/evaluations.mdx +++ b/docs/tr/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "Çevrimiçi değerlendirmeler" -description: "Canlı ve tamamlanan oturumları kalite, uyum, maliyet ve gecikme açısından puanlayın." +title: "Değerlendirme sonuçlarını okuyun" +description: "Zaman içinde değerlendirme puanlarını grafikle gösterin, ajanları ve ortamları karşılaştırın, bir oturumun neden düşük puan aldığını görün ve asistana soruları sorun." icon: "gauge" --- -Çevrimiçi değerlendirmeler, ajan oturumlarına tutarlı kararlar uygular. Yalnızca denetim sırasında araştırılması yerine sürekli olarak ölçülmesi gereken sinyaller için bunları kullanın. +Her değerlendirmeden gelen sonuçlar, barındırılan veya kendi worker'ınızdan gelen sonuçlar, aynı yerlere kaydedilir. -## Değerlendirme kalitesini gözden geçirin +## Puanları zaman içinde karşılaştırın - 1. **Observe → Evaluations** sayfasına gidin. - 2. Bir seri ekleyin ve ajan, ortam, değerlendirme puanı, istatistik ve eğriyi seçin. - 3. Ortamları, ajanları veya puan anahtarlarını karşılaştırmak için seri ekleyin. - 4. Eşleşen oturumları açmak veya filtrelenmiş görünümü paylaşmak için bir sonucu seçin. Gecikme, token, maliyet ve diğer büyüklük değerleri için **Observe → Metrics** kullanın. + **Observe → evaluations** bölümüne gidin. - ![Ortalama değerlendirme puanlarını ve zaman içindeki eğilimleri gösteren bir kalite panosu.](/images/dashboard/dashboard-quality.png) + - **Recent runs**, her değerlendirmeyi geldiği sırayla listeler: barındırılan (**managed**) veya kendi (**customer**) evaluator'ünüzden gelip gelmediğini, ajanı ve oturumu, değerlendirmesini ve sürümünü, durumunu ve puanını veya metriklerini gösterir. + - **Score over time**, istediğiniz şeyi çizer. **add series** seçin ve bir ajan, bir ortam, bir değerlendirme ve bir istatistik seçin: avg, min, max, p50, p75, p90, p95, p99, stddev, veya mode. Her seri bir satırdır; ayrı bir grafikte çizmek için ona kendi **curve**'ünü verin. - Her puan için akıl yürütmeyi incelemek için drill-down'dan bir oturum açın: + ![Değerlendirmeler sayfası: customer olarak etiketlenmiş son çalıştırmalar, 0.5 ve 0.8 referans çizgileriyle bir puanı zaman içinde grafik ve tüm ajanlar ve ortamlar arasında finished_clean'i ortalaması alan bir seri.](/images/dashboard/evaluations-chart.png) - ![Değerlendirme puanlarını ve akıl yürütmeyi tam iz yanında gösteren bir oturum ayrıntı görünümü.](/images/dashboard/session-detail.png) + Bir zaman aralığı ve bir bin boyutu tüm serilere uygulanır. İnce bir bin bir olayı bulur; kaba bir bin trend gösterir ve aradığınız ani yükselişleri gizleyebilir. Hiçbir şeyin puanlanmadığı bir bucket, satırda bir boşluk olup, hiçbir zaman sıfır değildir ve referans çizgileri 0.5 ve 0.8'i işaretler. + + Görünümün her parçası URL'de yaşar: **share** onu kopyalar ve onu açan herkes tam olarak oluşturduğunuz karşılaştırmayı görür. ```bash @@ -28,25 +28,29 @@ icon: "gauge" fp evals --score helpfulness:0.8.. --since 7d ``` - Otomasyon için `evals` öncesine global `--json` ekleyin, örneğin `fp --json evals --aggregate --env production`. + Otomasyon için `evals` öncesinde genel `--json` ekleyin, örneğin `fp --json evals --aggregate --env production`. -Bir değerlendirici, oturum kimliğini, ortamı, zaman damgalarını ve sıralanmış olayları alır. İsteğe bağlı akıl yürütme ve bir özet ile sayısal puan anahtarlarını döndürebilir. Uzun süre çalışan değerlendiriciler, beklemede bir iş döndürebilir ve daha sonra sorgulanabilir. +Aynı değerlendirme için iyi bir ortalamanın kötü bir tail'i gizleyip gizlemediğini görmek için **avg** ve **p90** çizin veya iki ajan için veya production ve staging için aynı değerlendirmeyi çizin, bunları bir eksende karşılaştırmak için. Birimler taşıyan maliyetler, gecikmeler ve token sayıları, **Observe → metrics** altında birim başına bir grafik olarak grafiklendirilir. + +## Bir oturumun neden düşük puan aldığını görün + +**Observe → sessions** bölümünden bir oturum açın; grid, her oturumun puanlarını taşır ve puan aralığına göre filtreler. Oturumun sağ raya, değerlendirme özeti ile başlar, sonra her puan için altında evaluator'ün akıl yürütmesi vardır. + +![Tam izlemenin yanında değerlendirme puanları ve akıl yürütmeyi gösteren bir oturum ayrıntı görünümü.](/images/dashboard/session-detail.png) + +## Asistana soruları sorun + +Değerlendirme verileri hakkında düz İngilizce ile soruları sorun: "bana son değerlendirmelerden bazılarından bahset" veya hangi ajanların puanlarının düştüğü. [Asistan](/tr/sessions/assistant) sonuçları okur ve analiz eder ve takip edebileceğiniz tablolarla cevap verir ve tutulması gereken bir soru [query](/tr/sessions/queries) veya [dashboard](/tr/sessions/dashboards) haline gelebilir. -## İyi değerlendirme hedefleri +![Değerlendirmeler sayfası asistan'ın yanında, "bana son değerlendirmelerden bazılarından bahset" sorusuna toplam, durumlar ve puanların özeti ile cevap verir.](/images/dashboard/evaluations-assistant.png) -- Görev tamamlanması veya doğruluğu -- Gerçeklilik ve halüsinasyon riski -- Araç seçimi ve araç verimliliği -- İlke veya süreç uyumu -- Maliyet ve gecikme bütçeleri -- Gerekli insan eskalasyonu +## İzleyin ve harekete geçin -## Puandan yanıta +- **Dashboards**, **Analyze → dashboards** altında, öne çıkardığınız puanları, ajan ve ortam başına, tüm kuruluş için trendler. -Eğilimleri izlemek için puanları panolarda gösterin. Eşikler veya bileşik koşullar için uyarılar oluşturun. Bir puanın bir popülasyon genelinde düşmesi durumunda, nedenini araştırmak için bir denetim çalıştırın; neden tekrarlanabilir bir eylem ise, bir ilke yayınlayın. + ![Ortalama değerlendirme puanları ve zaman içinde trendleri gösteren bir kalite dashboard'u.](/images/dashboard/dashboard-quality.png) - - Python değerlendirici SDK'sı ile senkron veya asenkron değerlendirme uygulayın. - \ No newline at end of file +- **Alerts**, bir puan bir eşiği geçtiğinde sizi bilgilendirir. Bkz. [alerts](/tr/audits/alerts). +- Bir puan birçok oturum arasında düştüğünde, nedenini öğrenmek için [bir audit çalıştırın](/tr/audits/run); neden tekrarlanabilir bir eylem olduğunda, [bir policy yazın](/tr/policies/editor). \ No newline at end of file diff --git a/docs/tr/start/integrations/custom-agents.mdx b/docs/tr/start/integrations/custom-agents.mdx index b93694ce..b091505d 100644 --- a/docs/tr/start/integrations/custom-agents.mdx +++ b/docs/tr/start/integrations/custom-agents.mdx @@ -1,23 +1,23 @@ --- -title: "Özel ajanlar" -sidebarTitle: "Özel ajanlar" -description: "Kendi yazdığınız bir ajana veya uyarlaması olmayan bir çerçeveye bir alet yerleştirin." +title: "Özel aracılar" +sidebarTitle: "Özel aracılar" +description: "Kendiniz yazdığınız bir aracıyı veya adaptörü olmayan bir çerçeveyi enstrüman edin." icon: "code" --- -Kendi yazdığınız bir ajan için veya Failproof AI'ın uyarlaması olmayan bir çerçeve için. Yerleştirilecek hiçbir şey yoktur: siz olayları yayınlarsınız. +Kendiniz yazdığınız bir aracı veya Failproof AI'nin adaptörü olmayan bir çerçeve için. Enstrümante edilecek bir şey yoktur: olayları siz yayınlarsınız. -Bu, dört çerçeve adaptörünün altında çağırdığı API'dir. Bunlar bunun üzerindeki çeviri tablolarıdır. +Bu, dört çerçeve adaptörünün altında çağırdığı API'dir. Bunlar onun üzerinde çeviri tablolarıdır. -## Kurulum +## Yükleme ```bash pip install failproofai-sdk ``` -Ekstralar ve bağımlılıklar yok. +Ek paket yok, bağımlılık yok. -## Yerleştirme +## Enstrümantasyon ```python import failproofai_sdk @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # bir çalışma t.output = search(q) # bir araç çağrısı ``` -Yukarıdan aşağıya okuyun ve ne demek istediğini söyler: +Baştan sona okuyun, söylediği şey budur: -| İçinde sarmalayın | Söylemek için | +| Bunu sarın | Demek için | | --- | --- | | `session()` | Bu olaylar aynı çalışmaya ait | -| `agent()` | Bir şey çalışma yapıyor — bir listede tanıyabileceğiniz bir ad verin | +| `agent()` | Birisi çalışıyor — listedeki tanıyacağınız bir ad verin | | `tool_call()` | Bu bir araç ve işte ne döndürdüğü | -Ve her biri gerçekten ne yayınlar: +Ve her biri aslında neyi yayınlar: | Kapsam | Yayınlar | Amaç | | --- | --- | --- | -| `session()` | Hiçbir şey | Bir oturumu bağlar, bir çalışmayı gruplandırır | -| `agent()` | `agent_start`, `agent_end` | Bir iş birimini parantez içine alır | -| `tool_call()` | `tool_use`, `tool_result` | Bir aracı parantez içine alır ve ölçer | +| `session()` | Hiçbir şey | Oturum kimliğini bağlar, bir çalışmayı gruplandırır | +| `agent()` | `agent_start`, `agent_end` | Bir iş birimini köşeli ayraç içine alır | +| `tool_call()` | `tool_use`, `tool_result` | Bir aracı köşeli ayraç içine alır ve ölçer | -İçindeki her şey `session_id` ve `agent_id` öğesini atlayabilir. Kapsamlar kimliği bağlam değişkenlerine bağlar ve her olay çağrısı bunu geri okur, bu nedenle hiçbir zaman işlevleriniz arasında kimlikleri geçirmezsiniz. +İçindeki her şey `session_id` ve `agent_id` atlamabilir. Kapsamlar kimliği bağlam değişkenlerine bağlar ve her olay çağrısı onu geri okur, bu yüzden kimlikler hiçbir zaman işlevler aracılığıyla iletilmez. -Her üçü `async with` kadar `with` altında da çalışır. +Üçü de `async with` ve `with` altında çalışır. -Ajanlari yuvalamak ağacı oluşturur. `parent_id` ve derinlik yığından hesaplanır: +Aracıları iç içe yerleştirmek ağacı oluşturur. `parent_id` ve derinlik yığından hesaplanır: ```python with failproofai_sdk.session(): @@ -59,42 +59,42 @@ with failproofai_sdk.session(): ... ``` -## Bir kapsam kapanırken +## Bir kapsam nasıl kapanır -`agent()` istisnalar sizin için işler: +`agent()` istisnaları sizin için işler: | Ne oldu | Olaylar | Sonuç | | --- | --- | --- | | Hiçbir şey yükseltilmedi | `agent_end` | `success` | | `Exception` | `error`, sonra `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, sonra `agent_end` | `failed` | -| `CancelledError`, `GeneratorExit` | sadece `agent_end` | `cancelled` | +| `CancelledError`, `GeneratorExit` | yalnızca `agent_end` | `cancelled` | -Hata `agent_end` öncesinde yayınlanır, çünkü pano aralığı `agent_end` adresinde kapatır ve bundan sonra her şey hiçbir şeye atfedilir. İptal bir başarısızlık değildir, bu nedenle iptal edilen çalışmalar hata yüzeyini kirletmez. İstisna her zaman yeniden yükseltilir: bir kapsam hiçbir zaman istisna kalmaz. +Hata `agent_end` öncesinde yayınlanır, çünkü gösterge paneli yayını `agent_end` konumunda kapatır ve bundan sonra gelen her şey hiçbir şeye atfedilir. İptal bir hata değildir, bu nedenle iptal edilen çalışmalar hata yüzeyini kirletmez. İstisna her zaman yeniden yükseltilir: bir kapsam asla yutmaz. ## Olay yöntemleri -On beş yöntem altı aileden. Çoğu çiftler halinde gelir — açıcıyı siz yayınlarsınız, sonra kapatıcıyı yayınlarsınız ve SDK arası aralığı ölçer. +On beş yöntem altı ailededir. Çoğu çiftler halinde gelir — açan yayını yayınlarsınız, sonra kapatanı yayınlarsınız ve SDK aralarındaki yayını ölçer. | Aile | Açar | Kapatır | Bağımsız | | --- | --- | --- | --- | -| **Ajanlar** | `agent_start` | `agent_end` | — | +| **Aracılar** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | | **Modeller** | `model_request` | `model_response` | — | | **Araçlar** | `tool_use` | `tool_result` | — | | **Kancalar** | `hook_triggered` | `hook_completed` | — | | **İnsanlar** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | -| **Başarısızlıklar** | — | — | `error` | +| **Hatalar** | — | — | `error` | - Kapsamlar — `agent()` ve `tool_call()` — her yerde tercih edin. Gövde yükselttiğinde bile kapatma olayını garantilerler. İçinde iç içe geçmeyen kontrol akışına (örneğin bir yardımcı içinde bir model çağrısı) sahip olduğunuzda bu yöntemlere doğrudan ulaşın. + Kapsamları tercih edin — `agent()` ve `tool_call()` — uygun oldukları yerlerde. Gövde yükseltirse bile kapanan olayı garantilerler. İçerik akışınız iç içe olmadığında doğrudan bu yöntemlere ulaşın; örneğin yardımcı içinde bir model çağrısı. -```python Ajanlar -failproofai_sdk.event.agent_start(agent_id="planner", goal="find the cheapest flight") +```python Aracılar +failproofai_sdk.event.agent_start(agent_id="planner", goal="en ucuz uçuşu bul") failproofai_sdk.event.agent_end(agent_id="planner", outcome="success", summary="...") -failproofai_sdk.event.agent_pause(pause_id="p1", reason="awaiting approval") +failproofai_sdk.event.agent_pause(pause_id="p1", reason="onay beklemede") failproofai_sdk.event.agent_resume(pause_id="p1") ``` @@ -125,39 +125,39 @@ failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome ``` ```python İnsanlar -failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) +failproofai_sdk.event.human_wait(input_id="i1", prompt="Onayla?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") -failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") -failproofai_sdk.event.human_interrupt(reason="operator stopped the run", at_step="step_3") +failproofai_sdk.event.human_pause(reason="operatör çalışmayı duraklatttı", user_id="dana") +failproofai_sdk.event.human_interrupt(reason="operatör çalışmayı durdurdu", at_step="step_3") ``` -```python Başarısızlıklar +```python Hatalar failproofai_sdk.event.error( error_type="TimeoutError", - message="provider timed out after 30s", + message="sağlayıcı 30 saniye sonra zaman aşımına uğradı", traceback="...", ) ``` - **İki insan ailesi zıt yönleri işaret eder.** + **İki insan ailesi zıt yönleri gösterir.** | Yöntemler | Anlamı | | --- | --- | - | `human_wait` / `human_input` | **Ajan bir kişiye sordu** — bir onay kapısı, açıklayıcı bir soru | - | `human_pause` / `human_interrupt` | **Bir kişi ajana hareket etti** — durdur düğmesi, operatör duraklatması | + | `human_wait` / `human_input` | **Aracı bir kişiye sordu** — onay kapısı, açıklayıcı soru | + | `human_pause` / `human_interrupt` | **Bir kişi aracıya etkide bulundu** — durdur düğmesi, operatör duraklaması | - Hiçbir çerçeve ikinci çifti sinyal vermez, bu nedenle her zaman sizin yayınlamanız gereken şeydir. + Hiçbir çerçeve ikinci çifti sinyal vermez, bu yüzden her zaman siz yayınlarsınız. - **Model çağrıları eşzamanlı olarak çalıştığında `request_id` geçirin.** Olmadan, istekler ve yanıtlar ajan başına varış sırasıyla eşleşir — ve eşzamanlı çağrılar yanlış eşleşir ve her yanıtı yanlış isteğe ekler. + **Model çağrıları eşzamanlı olarak çalıştığında `request_id` geçirin.** Olmadan, istekler ve yanıtlar ajan başına varış sırasına göre eşleşir — ve eşzamanlı çağrılar yanlış eşleşir, her yanıtı yanlış isteğe iliştirir. ## Örnek -OpenAI API'sine karşı bir araç çağırma döngüsü, ajan çerçevesi olmadan: +OpenAI API'sine karşı araç çağırma döngüsü, ajan çerçevesi olmadan: ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """Bir model çağrısı, çift tarafından parantez içine alındı.""" + """Bir model çağrısı, çift tarafından köşeli ayraç içine alınmış.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -185,8 +185,8 @@ def turn(messages: list): with failproofai_sdk.session(): - with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # sınırlı; sınırsız bir ajan döngüsü kendi bir hatadır + with failproofai_sdk.agent("inventory", goal="fiyat raporu"): + for _ in range(4): # sınırlandırılmış; sınırsız ajan döngüsü kendi hatası message = turn(messages) if not message.tool_calls: break @@ -204,45 +204,45 @@ with failproofai_sdk.session(): }) ``` -Bu, bir adaptörün sağlayacağı aynı altı olay türünü üretir. Tam çalıştırılabilir sürüm, araç tanımlarıyla birlikte, SDK deposunda `docs/manual/examples/` altında gemi. +Bu, bir adaptörün size vereceği altı olay türünü üretir. Tam çalıştırılabilir sürüm, araç tanımlarıyla birlikte, SDK deposunda `docs/manual/examples/` altında bulunur. ## İş parçacıkları ve async -Bağlam değişkenleri asyncio görevlerine otomatik olarak yayılır. Bir iş parçacığı boş bir bağlamla başladığı için yeni iş parçacıklarına yayılmazlar. +Bağlam değişkenleri asyncio görevlerine otomatik olarak yayılır. Bir iş parçacığı boş bir bağlamla başladığı için yeni iş parçacıklarına yayılmaz. ```python -# asyncio: yapılacak hiçbir şey yok +# asyncio: yapılacak bir şey yok async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# iş parçacıkları: çağrılanı sarmalayın +# iş parçacıkları: çağrıyı sarın pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -`propagate()` olmadan, çalışanın olayları düzeltmeyi adlandıran bir `TypeError` yükseltir, bunun yerine hiçbir oturuma iniş. Bu kasıtlıdır: hiçbir oturuma sahip olmayan bir olay alımında atlanır ve `200` ile yanıtlanır, bu da kimlik katmanının var olması için sessiz başarısızlıktır. +`propagate()` olmadan, worker'ın olayları düzeltmeyi adlandıran bir `TypeError` yükseltir, bu da hiçbir oturuma gitmez. Bu kasıtlıdır: oturumu olmayan bir olay ingest tarafından atlanır ve `200` ile yanıtlanır, bu da kimlik katmanının önlemesi amaçladığı sessiz başarısızdır. -## Adaptörü olmayan bir çerçeveye alet takın +## Adaptörü olmayan bir çerçeveyi enstrümante edin -Her ajan çerçevesi aynı üç dikiş verir. Onları eşleştirin ve tam bir izin aldınız — dört gemi adaptörü bundan daha fazlasını yapmazlar. +Her ajan çerçevesi aynı üç bağlantı noktası sağlar. Onları harita yapın ve tam bir izlemeniz vardır — sevk edilen dört adaptör bundan fazla bir şey yapmaz. -| Dikiş | Yazarız | Arazileri | +| Bağlantı noktası | Yazarınız | İnişi olan | | --- | --- | --- | | Çalışma | `session()` + `agent()` | `agent_start`, `agent_end` | | Her araç | `tool_call()` | `tool_use`, `tool_result` | | Her model çağrısı | `model_*` çifti | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - Çerçevenin bir araç sarmalayıcısı veya ara yazılım dediği ne olursa olsun. + + Çerçevenin araç sarıcısı veya ara yazılım olarak adlandırdığı her şeyde. ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -264,31 +264,31 @@ Her ajan çerçevesi aynı üç dikiş verir. Onları eşleştirin ve tam bir iz - **Görmek değer bir düğüm, adım veya ara yazılım sınırı var mı?** Bir kanca çifti içinde sarmalayın — `hook_triggered` / `hook_completed` — iç içe geçmiş `agent()` değil. `agent_id`, düşük kardinalite bir nitelik ve düğüm başına bir giriş onu boğar. Kanca aralıkları aynı şekilde renderlenir ve size düğüm başına gecikme süresi verir. + **Görmeye değer bir düğüm, adım veya ara yazılım sınırı var mı?** Bunu iç içe bir `agent()` değil, kancanın içine sarın — `hook_triggered` / `hook_completed`. `agent_id` düşük kardinalite yönüdür ve düğüm başına bir giriş onu boğar. Kancanın yayını aynı şekilde işlenir ve düğüm başına gecikme süresi sağlar. - **Manuel ve otomatik oluştur.** Bir uyarlanmış içinde çalışan bir çerçeve, bu oturuma katılır ve bu ajana üst olur, bu nedenle iki ağaç yerine bir ağaç alırsınız — bir desteklenen çerçeve ile birlikte kendi kendine bir çerçeve alet takmanız yararlı. + **Manuel ve otomatik oluşturma.** El yazısı bir kapsam içinde çalışan bir adaptör bu oturuma katılır ve bu aracıya ebeveyn olur, bu nedenle iki tane yerine bir ağaç alırsınız — desteklenen bir tarafı kendiniz enstrümante ederken bir çerçeveyi yan yana kullanışlı olduğunda. - - İki neden ve yukarıdaki üç dikiş her ikisinin cevabıdır: + + İki neden vardır ve yukarıdaki üç bağlantı noktası her ikisine de cevaptır: - - `autogen-core` Eylül 2025'ten beri bakımsızdır. - - AG2, diğer çerçevelerin kancaları eşdeğer işlem çapında bir kayıt noktası ortaya çıkarmaz, bu nedenle bunu araç takınmak her inşaat sitesinde her ajanı sarmalamak anlamına gelir. + - `autogen-core` Eylül 2025'ten beri bakımsız olmuştur. + - AG2, diğer çerçevelerin kancanlarına eşdeğer hiçbir işlem açısından kayıt noktası açığa çıkarmaz, bu nedenle enstrümantasyonu her inşaat alanında her aracıyı sararak anlamına gelir. - Dikiş eşleştirmesini el ile yapmak, bir gemi adaptörü olarak aynı olayları aynı doğrulukta kaydeder. + Bağlantı noktalarını elle harita yaparak, sevk edilen bir adaptörün yaptığı aynı fidelitede aynı olayları kaydeder. -## Daha derine inmek +## Daha derine gitme -Kayıt gerçekten nasıl çalışır. Başlamak için bunların hiçbiri gerekli değildir. +Kaydın aslında nasıl çalıştığı. Başlamak için buna ihtiyaç yoktur. - + -Her kaydın aynı şekli vardır: bir aralık açılır, çalışma içinde yuvalanır ve her açılış olayı kapatma olayı alır. +Her kaydın aynı şekli vardır: bir yay açılır, iş içinde iç içe geçer ve her açma olayı kapatma olayı alır. ```mermaid flowchart LR @@ -300,17 +300,17 @@ flowchart LR C --> E(["agent_end"]) ``` -**Çift** birim. Her kapatma olayı, SDK'nın açılış olayından ölçtüğü bir süreyi taşır. +**Çift** birimdir. Her kapatma olayı SDK'nın açma olayından ölçtüğü bir süre taşır. -Aşağıda SDK ile birlikte gelen örneklerden yakalanan çerçeve başına bir gerçek çalışma — model adı normalleştirildi. Tek bir çağrıdan ne kadar geri döndüğüne dikkat edin. +Aşağıda SDK ile sevk edilen örneklerden yakalanan çerçeve başına bir gerçek çalışma vardır — model adı normalleştirilmiştir. Tek bir çağrıdan ne kadar döndüğüne dikkat edin. - ```text 14 olaylar + ```text 14 olay 1 +0.000s agent_start LangGraph 2 +0.001s hook_triggered agent 3 +0.002s model_request gpt-4o-mini - 4 +3.023s model_response gpt-4o-mini · 21 out-tok + 4 +3.023s model_response gpt-4o-mini · 21 çıkış-tok 5 +3.024s hook_completed agent 6 +3.024s hook_triggered tools 7 +3.025s tool_use word_count @@ -318,106 +318,106 @@ Aşağıda SDK ile birlikte gelen örneklerden yakalanan çerçeve başına bir 9 +3.025s hook_completed tools 10 +3.026s hook_triggered agent 11 +3.027s model_request gpt-4o-mini - 12 +5.717s model_response gpt-4o-mini · 5 out-tok + 12 +5.717s model_response gpt-4o-mini · 5 çıkış-tok 13 +5.720s hook_completed agent 14 +5.721s agent_end LangGraph · success ``` - Düğümler kanca çiftleri haline gelir, böylece ajan listesini doldurmadan düğüm başına gecikme süresi alırsınız. + Düğümler kancanın çiftleri olur, bu nedenle onları kalabalık yapmadan düğüm başına gecikme süresi alırsınız. - ```text 10 olaylar + ```text 10 olay 1 +0.000s agent_start crew 2 +0.050s agent_start analyst · under crew 3 +0.057s model_request gpt-4o-mini - 4 +3.475s model_response gpt-4o-mini · 19 out-tok + 4 +3.475s model_response gpt-4o-mini · 19 çıkış-tok 5 +3.478s tool_use lookup_metric 6 +3.478s tool_result lookup_metric · ok 7 +3.486s model_request gpt-4o-mini - 8 +5.694s model_response gpt-4o-mini · 9 out-tok + 8 +5.694s model_response gpt-4o-mini · 9 çıkış-tok 9 +5.727s agent_end analyst · success 10 +5.739s agent_end crew · success ``` - Her ajanın `role` aralık adı haline gelir, böylece gecikme ve jeton harcaması rol başına bölünür. + Her aracının `role` yay adı olur, bu nedenle gecikme süresi ve jeton harcaması rol başına bölünür. - ```text 26 olaylar + ```text 26 olay 1 +0.000s agent_start Agent 2 +0.001s hook_triggered init_run 4 +0.501s hook_triggered setup_agent 6 +0.503s hook_triggered run_agent_step 7 +0.505s model_request gpt-4o-mini - 8 +3.083s model_response gpt-4o-mini · 18 out-tok + 8 +3.083s model_response gpt-4o-mini · 18 çıkış-tok 10 +3.197s hook_triggered parse_agent_output 12 +3.355s hook_triggered call_tool 13 +3.355s tool_use city_population 14 +3.355s tool_result city_population · ok 16 +3.356s hook_triggered aggregate_tool_results - ... ikinci yineleme + ... ikinci iterasyon 26 +7.038s agent_end Agent · success ``` - Ajan döngüsünün kendisi görülebilir, sadece model çağrıları değil. + Ajan döngüsü kendisi görünür, yalnızca model çağrıları değil. - ```text 8 olaylar + ```text 8 olay 1 +0.000s agent_start agent 2 +0.001s model_request gpt-4o-mini - 3 +4.413s model_response gpt-4o-mini · 17 out-tok + 3 +4.413s model_response gpt-4o-mini · 17 çıkış-tok 4 +4.415s tool_use population 5 +4.415s tool_result population · ok 6 +4.416s model_request gpt-4o-mini - 7 +8.118s model_response gpt-4o-mini · 6 out-tok + 7 +8.118s model_response gpt-4o-mini · 6 çıkış-tok 8 +8.119s agent_end agent · success ``` - Kanca çifti yok: Pydantic AI'nin parantez içine alacak bir düğüm veya adım sınırı yoktur. + Kancanın çifti yok: Pydantic AI'nin köşeli ayraç içine alacak düğüm veya adım sınırı yok. - - ```text 6 olaylar + + ```text 6 olay 1 +0.000s agent_start main 2 +0.000s tool_use population 3 +0.000s tool_result population · ok 4 +0.000s model_request gpt-4o-mini - 5 +0.000s model_response gpt-4o-mini · 3 out-tok + 5 +0.000s model_response gpt-4o-mini · 3 çıkış-tok 6 +0.000s agent_end main · success ``` - Bunları kendiniz yayınlıyorsunuz. Aynı olay türleri, aynı doğruluk — çağrı sitelerine mal olur. + Bunları kendiniz yayınlarsınız. Aynı olay türleri, aynı fidelite — çağrı alanlarına mal olur. - + -**Oturum sonu olayı yoktur.** Bir oturum kapatıp kapatmadığınız bir şey değildir — aynı `session_id` paylaşan bir olay grubudur. +**Oturum sonu olayı yoktur.** Oturum kapattığınız bir şey değil — `session_id` paylaşan bir olay grubudur. -Durum izin şeklinden türetilir: +Durum izlemenin şeklinden türetilir: | Durum | Ne zaman | | --- | --- | -| `ongoing` | En az bir aralık hala açık | -| `paused` | `agent_pause` eşleşen `agent_resume` yok | +| `ongoing` | En az bir yay hala açık | +| `paused` | Bir `agent_pause` eşleşen `agent_resume` yok | | `error` | Hiçbir şey açık değil ve en az bir olay başarısız oldu | | `done` | Hiçbir şey açık değil ve hiçbir şey başarısız olmadı | -Bu nedenle bir oturum her çift kapandığında biter. Adaptörler sizin için `agent_end` yayınlar ve bozulma sırasında hala açık olan her şeyi kapatır ve eksik olarak işaretler — kilitlenmiş bir çalışma, asılı kalmak yerine görünen boşluk olarak `done` çözümlenir. +Yani bir oturum her çift kapatıldığında biter. Adaptörler sizin için `agent_end` yayınlar ve kapalı kaldığında açık kalan her şeyi kapatırlar ve eksik olarak işaretlerler — çökmüş bir çalışma asılı kalmak yerine görünür bir boşlukla `done` olarak yerleşir. - Bu nedenle bir oturum iki çağrıya yayılabilir. Bir LangGraph `interrupt()` çalışmayı duraklatır, kök aralığı kasıtlı olarak açık kalır ve devam çağrısı bunu kapatır. Her iki çağrı da bir oturumdu. + Bu yüzden bir oturum iki çağrıya yayılabilir. Bir LangGraph `interrupt()` çalışmayı duraklatır, kök yayı kasıtlı olarak açık kalır ve devam eden çağrı onu kapatır. Her iki çağrı bir oturuma aittir. - + -`session_id` ve `agent_id` her olay yönteminde isteğe bağlıdır. Atlanıldığında, çevreleyen kapsamdan çözülebilirler: +`session_id` ve `agent_id` her olay yönteminde isteğe bağlıdır. Atlanırsa, çevreleyen kapsamdan çözülürler: ```python with failproofai_sdk.session(): @@ -425,84 +425,84 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Bunları açıkça geçirmek yine de çalışır ve öncelik alır. Hiçbir şey bağlı olmayıp hiçbir şey geçmediyse, çağrı düzeltmeyi adlandıran bir `TypeError` yükseltir, yoksa alım tarafından atlanacak hiçbir oturuma sahip bir olay yayınlar ve `200` ile yanıtlar. +Bunları açıkça iletmek yine de işe yarar ve önceliği alır. Hiçbir şey bağlı değil ve hiçbir şey iletilmezse, çağrı düzeltmeyi adlandıran bir `TypeError` yükseltir, ingest atlamış olacağı oturumu olmayan bir olayı yayınlamak yerine, `200` ile yanıtlar. -Kapsamlar kimliği bağlam değişkenlerine bağlar. Bunlar asyncio görevlerine otomatik olarak yayılır, ancak yeni iş parçacıklarına değil — bir işçiyi `failproofai_sdk.propagate()` içinde sarmalayın. +Kapsamlar kimliği bağlam değişkenlerine bağlar. Bunlar asyncio görevlerine otomatik olarak yayılır ancak yeni iş parçacıklarına yayılmaz — bir worker'ı `failproofai_sdk.propagate()` içine sarın. -#### Hangi kimlik kim başlatır +#### Hangi kimlik kim tarafından basım yapılır -| Kimlik | Tarafından başlatıldı | Notlar | +| Kimlik | Basım yapan | Notlar | | --- | --- | --- | -| `session_id` | Siz veya SDK | `session("chat-42")` tam olarak kullanılır; atlanıldığında, SDK bir `uuid4().hex` üretir | -| `agent_id` | Siz veya çerçeve | `agent("analyst")` danışmanından, CrewAI `role`, bir `FunctionAgent.name`. UUID benzeri bir değer reddedilir ve değiştirilir | -| `tool_call_id`, `hook_id`, `request_id` | Siz veya çerçeve | Adaptörler çerçevenin kendi çalışma kimliklerini yeniden kullanır, bu da çiftlerin iş parçacığı atlaması nedeniyle hayatta kaldığı nedenidir | -| **Olay kimliği** | **Bulut, alımda** | SDK hiçbirini yayınlamaz | -| **`dedup_key`** | **Bulut, alımda** | Org, oturum, zaman damgası, tür ve yükün karması. Bu gerçek kimlik — bir yeniden denenen toplu işin kopyalanmak yerine çökmesini sağlar | +| `session_id` | Siz veya SDK | `session("chat-42")` kelimesi kelimesine kullanılır; atlanırsa, SDK bir `uuid4().hex` oluşturur | +| `agent_id` | Siz veya çerçeve | `agent("analyst")`, CrewAI `role`, bir `FunctionAgent.name`'den. UUID görünüşlü bir değer reddedilir ve değiştirilir | +| `tool_call_id`, `hook_id`, `request_id` | Siz veya çerçeve | Adaptörler çerçevenin kendi çalışma kimliklerini yeniden kullanır, bu yüzden çiftler iş parçacığı atlamalarında hayatta kalır | +| **Olay kimliği** | **Bulut, ingest'te** | SDK hiçbirini yayınlamaz | +| **`dedup_key`** | **Bulut, ingest'te** | Kuruluş, oturum, zaman damgası, tür ve yüke karşı bir karma. Bu gerçek kimlik — yeniden denenen bir topluyu çoğaltmak yerine daraltır | -#### Adaptörler `session_id` nasıl çözerler +#### Adaptörler `session_id` nasıl çözer İlk eşleşme kazanır: -1. Açık `session_id` seçeneği -2. Çağrı başına meta veriler -3. `session()` kapsamını çevreleyen +1. Açık bir `session_id` seçeneği +2. Çağrı başına meta veri +3. Çevreleyen `session()` kapsamı 4. Çerçeve meta verileri 5. Çerçevenin kendi çalışma kimliği -Bunlardan biri var iken asla icat edilmez — sentezlenmiş bir kimlik bir çalışmayı birkaç oturum arasında bölmek olur. +Bunlardan biri vardığı sürece asla icat edilmez — sentezlenmiş bir kimlik bir çalışmayı birkaç oturuma böler. -#### `agent_id` düşük kardinaliteyi tutun +#### `agent_id` düşük kardinaliteyi koruyun -Her pano yüzeyinde birincil yüz ve bir `LowCardinality(String)` sütunudur. Çalışma başına bir değer sütunu bozar ve filtre açılır penceresini çalışma başına bir giriş ile doldurur. +Bu her gösterge paneli yüzeyinde birincil yönüdür ve `LowCardinality(String)` sütunu. Çalışma başına bir değer sütunu düşürür ve filtre açılır menüsünü çalışma başına bir giriş ile doldurur. Adaptörler bu sütunu sizin için savunur: -| Çerçeve teslim eder | Olarak kaydedildi | Neden | +| Çerçeve teslim eder | Kaydedilmiş olarak | Neden | | --- | --- | --- | -| `3f9a1c2b-…` (UUID) | `main` | Tutacak hiçbir şey okunaklı | -| Uzun çıplak onaltılık dize | `main` | Aynı | -| `agent-3f9a1c2b-…` | `agent` | Çalışma başına kimlik çıkarıldı, okunaklı kısım tutuldu | +| `3f9a1c2b-…` (bir UUID) | `main` | Tutmak için okunabilir bir şey yok | +| Uzun çıplak hex dizesi | `main` | Aynı | +| `agent-3f9a1c2b-…` | `agent` | Çalışma başına kimlik çıkarıldı, okunabilir bölüm tutuldu | | `agent-v2` | `agent-v2` | Kısa segmentler yalnız bırakılır | | `step-3` | `step-3` | Aynı | -Gerçek kimlik, nitelik olmadan sorgulanabilir kaldığı `fw_agent_id` / `fw_run_id` üzerinde tutulur. +Gerçek kimlik `fw_agent_id` / `fw_run_id` üzerinde tutulur, burada yönü olmuş bir yüzey olmadan sorgulanabilir kalır. - **Bu koruma yalnızca *çerçevenin* seçtiği etiketlere dokunur.** Kendi geçtiğiniz bir `agent_id` — `event.*` veya `failproofai_sdk.agent(...)` — tam olarak verilen gibi kaydedilir. Açık bir argümanı sessizce yeniden yazmak önlediği kardinaliteden daha kötü olur, bu nedenle kendi aralıklarınızı buna göre adlandırın. + **Bu koruma yalnızca **çerçevenin** seçtiği etiketlere dokunur.** Kendiniz ilettiğiniz bir `agent_id` — `event.*` veya `failproofai_sdk.agent(...)` için — tam olarak verilen şekilde kaydedilir. Açık bir bağımsız değişkeni sessizce yeniden yazmak, kardinalieti önledikten daha kötü olur, bu yüzden kendi yaylarınızı buna göre adlandırın. - + | Grup | Olaylar | | --- | --- | -| Ajanlar | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| Aracılar | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | | Modeller | `model_request`, `model_response` | | Araçlar | `tool_use`, `tool_result` | | Kancalar | `hook_triggered`, `hook_completed` | | İnsanlar | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | -| Başarısızlıklar | `error` | +| Hatalar | `error` | -Hangi çerçeve ne kaydeder, yukarıdaki çalışmalardan ölçülmüştür: +Hangi çerçeve neyi kaydeder, yukarıdaki çalışmalardan ölçülen: | Olay | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Özel | | --- | :--: | :--: | :--: | :--: | :--: | -| Ajan başlangıcı ve sonu | Evet | Evet | Evet | Evet | Siz | +| Ajan başı ve sonu | Evet | Evet | Evet | Evet | Siz | | Model isteği ve yanıtı | Evet | Evet | Evet | Evet | Siz | | Araç kullanımı ve sonucu | Evet | Evet | Evet | Evet | Siz | -| Kanca tetiklendi ve tamamlandı | Düğüm | Görev | Adım | — | Siz | +| Kancanın tetiklenmesi ve tamamlanması | Düğüm | Görev | Adım | — | Siz | | Hata | Evet | Evet | Evet | Evet | Otomatik | -| İnsan bekle ve giriş | Evet | Evet | Evet | — | Siz | -| Ajan duraklat ve devam et | Evet | Evet | Evet | — | Siz | +| İnsan bekleme ve girişi | Evet | Evet | Evet | — | Siz | +| Ajan duraklaması ve devam etmesi | Evet | Evet | Evet | — | Siz | -Bir tire çerçevenin böyle bir kavramı olmadığı anlamına gelir. `human_pause` ve `human_interrupt` ajana etki eden bir *kişi* anlatılar — hiçbir çerçeve sinyal vermez — bunları kendiniz yayınlayın. +Tire, çerçevenin böyle bir kavramı olmadığı anlamına gelir. `human_pause` ve `human_interrupt`, aracıya etkide bulunan bir *kişiyi* tanımlar, hiçbir çerçeve sinyal vermez — bunları kendiniz yayınlayın. -Bir olay asla tek başına gelmez. Biri aralığı açar, biri kapatır ve kapatma olayı SDK'nın açılış olayından ölçtüğü bir süreyi taşır. +Bir olay asla yalnız gelmez. Biri bir yayı açar, biri onu kapatır ve kapatma olayı SDK'nın açma olayından ölçtüğü bir süre taşır. | Açar | Kapatır | Kapatma olayı taşır | | --- | --- | --- | @@ -510,44 +510,44 @@ Bir olay asla tek başına gelmez. Biri aralığı açar, biri kapatır ve kapat | `model_request` | `model_response` | jetonlar, `stop_reason`, gecikme | | `tool_use` | `tool_result` | `output` veya `error`, süre | | `hook_triggered` | `hook_completed` | `outcome`, süre | -| `agent_pause` | `agent_resume` | duraklatmanın ne kadar sürdüğü | -| `human_wait` | `human_input` | cevap ve kişi kaç süre aldı | +| `agent_pause` | `agent_resume` | duraklamanın ne kadar sürdüğü | +| `human_wait` | `human_input` | cevap ve kişinin ne kadar sürdüğü | - Kapatma olayı olmayan bir açılış olayı hiçbir zaman bitmeyen bir araçlıktır. Oturum sonsuza dek hala çalışıyor olarak renderlenir ve etkin süresi artmaya devam eder. Bu, elinizle alet takınırken izlenecek başarısızlık modudur. + Kapatma olayı olmayan açma olayı hiçbir zaman bitmez bir yaydır. Oturum sonsuza dek çalışıyor olarak işlenir ve etkin süresi büyümeye devam eder. Bu, el ile enstrümante ederken izlenecek hata modudur. #### Korelasyon kuralları - Eşleşen tamamlama olayı için aynı `tool_call_id`, `hook_id`, `pause_id` veya `input_id` yeniden kullanın. -- SDK, `tool_result`, `hook_completed`, `agent_resume` ve `human_input` için `duration_ms` hesaplar. Bunu bu yöntemlere geçirmek `ValueError` yükseltir. -- `duration_ms` **kabul edilir** `model_response` adresinde, çünkü yalnızca arayana gerçek sağlayıcı gecikmesi bilinir. Tamsayı olmalı — bir kayan nokta çağrı sitesinde `ValueError` yükseltir, çünkü sunucu sütunu imzasız 32 bitlik bir tamsayı olarak okur ve diğer her şey için NULL depolar. -- Korelasyon anahtarları tür ve oturum tarafından kapsamlandırılır, bu nedenle bir araç çağrısı ve kanca güvenli bir şekilde bir kimliği paylaşabilir ve iki eşzamanlı oturum aynı kimlikleri çarpışmadan yeniden kullanabilir. Ajan tarafından kapsamlandırılmaz: bir ajan altında açılıp başka bir ajan altında kapatılan bir çift hala korelat olur, bu da çok ajanı çerçevelerde sıradan bir durumdur. -- `request_id` `model_request` ile `model_response` eşleştiriler. Olmadan, model olayları ajan başına sipariş olarak eşleşir, bu nedenle eşzamanlı çağrılar yanlış eşleşir. -- İşlemler arasında bölünmüş bir çift hala aşağı akışta korelat, ancak SDK işlem içi süresini hesaplayamaz. -- Beklemede harita en fazla 10.000 başlama tutar ve dolu olduğunda en eski girişi tahliye eder. +- SDK `tool_result`, `hook_completed`, `agent_resume` ve `human_input` için `duration_ms` hesaplar. Bunları iletmek `ValueError` yükseltir. +- `duration_ms` **kabul edilir** `model_response` üzerinde, çünkü yalnızca arayan gerçek sağlayıcı gecikmesini bilir. Bir tamsayı olmalı — bir kayan sayı çağrı sitesinde `ValueError` yükseltir, sunucu sütunu işaretsiz 32 bitlik bir tamsayı olarak okur ve başka bir şey için NULL depolar. +- Korelasyon anahtarları tür ve oturum kapsamındadır, böylece bir araç çağrısı ve kancanın kimliği güvenle paylaşabilir ve iki eşzamanlı oturum kimlikler yeniden kullanabilir çarpışma olmadan. Agent kapsamında değil: bir ajan altında açılan ve diğeri altında kapatılan bir çift yine de ilişkilendirilir, bu multi-ajan çerçevelerdeki sıradan durumdur. +- `request_id` `model_request` `model_response` ile eşleştirir. Olmadan, model olayları ajan başına sırada eşleşir, bu nedenle eşzamanlı çağrılar yanlış eşleşir. +- İşlemler arasında bölünmüş bir çift yine de aşağı doğru ilişkilendirilir, ancak SDK işlem içi süresini hesaplayamaz. +- Bekleyen harita en fazla 10.000 başlangıç tutar ve dolu olduğunda en eski giriş tahliye eder. - + -`failproofai-sdk` kurulması her şeyi kurar, dört adaptör dahildir. Ekstralar **çerçeveyi** kurar, adaptörü değil. +`failproofai-sdk` kurmak her şeyi, dört adaptör dahil olmak üzere yükler. Ekstralar adaptörü değil, **çerçeveyi** çeker. ```python import failproofai_sdk # standart kitaplığın dışında hiçbir şey yüklemez -failproofai_sdk.instrument() # gerçekten ihtiyacınız olan adaptörleri yalnızca alır +failproofai_sdk.instrument() # yalnızca gerçekten ihtiyaç duyduğunuz adaptörleri içe aktarır ``` -`import failproofai_sdk` sözleşmeli olarak sıfır bağımlılık, inşa edilen tekerleği `--no-deps` ile kuran bir test ve hiçbir çerçevenin `sys.modules` ulaşmadığını kanıtlayan başka bir test tarafından zorunlu. +`import failproofai_sdk` sözleşmeli olarak sıfır bağımlılıktır, yerleşik tekerleği `--no-deps` ile kuran ve hiçbir çerçevenin `sys.modules` erişmemesini kanıtlayan başka bir test tarafından uygulanır. - `failproofai_sdk.crewai` özniteliği yoktur. Adaptörler kasıtlı olarak üst düzey pakette ortaya çıkmaz: bir adaptörü dokunmak çerçeveyi bir öznitelik erişiminin yan etkisi olarak içe aktarır, sıfır bağımlılık sözünü kırar. `instrument()` kullanın. + `failproofai_sdk.crewai` niteliği yoktur. Adaptörler kasıtlı olarak en üst düzey pakette açığa çıkarılmaz: birini değmek, öznitelik erişiminin yan etkisi olarak çerçeveyi içe aktarır, sıfır bağımlılık vaadini kırarak. `instrument()` kullanın. ```python -failproofai_sdk.instrument() # her çerçeve zaten alındı -failproofai_sdk.instrument("crewai") # tam olarak biri, ada göre -failproofai_sdk.uninstrument("crewai") # geri koy +failproofai_sdk.instrument() # her çerçeve zaten içe aktarıldı +failproofai_sdk.instrument("crewai") # tam olarak bir, adıyla +failproofai_sdk.uninstrument("crewai") # geri koyun ``` | Ad | Ayrıca kabul eder | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # geri koy | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -Otomatik algılama `sys.modules` okur, yüklü paket listesi değil, bu nedenle yüklediğiniz ancak asla içe aktarmadığınız bir çerçeve alet takılmaz ve hiçbir zaman sizin adınıza alınmaz. Neler bağlıdır görmek için: +Otomatik algılama `sys.modules` okur, yüklü paket listesi değil, bu nedenle kurmuş ancak asla içe aktarmadığınız bir çerçeve enstrümente edilmez ve asla sizin adınıza içe aktarılmaz. Neyin bağlı olduğunu görmek için: ```python from failproofai_sdk.integrations import active, available @@ -567,130 +567,132 @@ active() # ('langchain',) ``` - **CrewAI olmayan bir makinede `instrument("crewai")` yükseltmez.** Bir uyarı günlüğe kaydeder ve `()` döndürür, bu nedenle eksik bir çerçeve diğerlerini de alet takmayan bir işlemi asla çökertmez. + **CrewAI olmayan bir makinede `instrument("crewai")` yükseltmez.** Bir uyarı kaydeder ve `()` döndürür, bu nedenle bir eksik çerçeve diğerlerini de enstrümante eden bir işlemi asla alır. - Uyarı temel `ImportError` taşır ve bu ileti kesin kurulum komutunu adlandırır — bu nedenle onarım günlüklerinizde, gizli değildir. + Uyarı temel `ImportError` taşır ve bu ileti tam kurulum komutu adlandırır — düzeltme günlüklerde gizli değildir. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Bunun yerine yükseltmesini sağlamak için `FAILPROOFAI_SDK_STRICT=1` ayarlayın. Bu bayrak **bir kez okunur ve önbelleğe alınır**, bu nedenle mid-run ayarlamak yerine işleminiz başlamadan önce ihraç edin. + Bunun yerine yükseltmesini sağlamak için `FAILPROOFAI_SDK_STRICT=1` ayarlayın. Bu bayrak **bir kez okunur ve önbelleğe alınır**, bu yüzden işleminiz başlamadan önce bunu dışa aktarın, çalışma sırasında ayarlamak yerine. - **`instrument()` çerçeve alımınızdan *sonra* gelmelidir.** Otomatik algılama `sys.modules` okur, bu nedenle alımın üstünde bir çıplak çağrı hiçbir şey bulamaz, hiçbir şey kurmaz ve `()` döndürür. + **`instrument()` çerçeve ithalinizin *sonra* gelmeli.** Otomatik algılama `sys.modules` okur, bu yüzden içeri aktarmanın üstünde açık bir çağrı hiçbir şey bulmaz, hiçbir şey yüklemez ve `()` döndürür. ```python Yanlış import failproofai_sdk -failproofai_sdk.instrument() # sys.modules'te henüz langchain yok -> () +failproofai_sdk.instrument() # sys.modules'da henüz langchain yok -> () import langchain # çok geç, hiçbir şey bağlı değil ``` ```python Doğru -import langchain # ilk çerçeveyi içe aktarın +import langchain # çerçeveyi ilk olarak içe aktarın import failproofai_sdk failproofai_sdk.instrument() # onu bulur -> ('langchain',) ``` -```python Doğru, düzen kanıtı +```python Doğru, sıra-kanıtlı import failproofai_sdk -# Bunu adlandırmak adaptörü isteğe bağlı olarak alır, bu nedenle buradan her yerde çalışır. +# Adını verme, adaptörü talep üzerine yükler, bu yüzden buradan herhangi bir yerden işe yarar. failproofai_sdk.instrument("langchain") ``` -Bunu yanlış aldıktan sonra işlem SDK alındı, adaptör görünen kurulu ve **hiçbir olay yayınlanmamış** dengan çalışır. Bu yayınlanan bir uyarı tam olarak söyler — bu nedenle bir çalışma hiçbir şey kaydettiğinde günlüklerinizi ilk kontrol edin. +Bunu yanlış yapın ve işlem SDK'yı içe aktarılmış, adaptör görünüşte yüklenmiş ve **tek bir olayı yayınla olmayan** ile çalışır. Bu tam olarak söyleyen bir uyarı kaydeder — çalışma hiçbir şey kaydedildiğinde loglarınızı ilk kontrol edin. - + ```mermaid flowchart LR - A["Sizin ajanınız"] --> B["Adaptör"] - B --> C["Yazar
bellek içi sıra"] - C -->|"her 0.5s"| D["Makara
diskette JSONL"] + A["Ajanız"] --> B["Adaptör"] + B --> C["Yazar
bellek içi kuyruk"] + C -->|"her 0.5s"| D["Makara
diskte JSONL"] D --> E["Failproof daemon"] E -->|"HTTPS"| F["Bulut"] ``` -| Aşama | İş | Çalışması | +| Aşama | İş | Çalışır | | --- | --- | --- | -| Adaptör | Çerçeve geri aramasını 15 olay türünden birine çevirir | Sizin işleminiz | -| Yazar | Kuyruklar, toplu işler, JSONL atomik olarak yazar | Sizin işleminiz, arka plan iş parçacığı | -| Makara | Dayanıklı teslim, işleminizin çıkışını devam ettirir | Yerel disk | -| Daemon | Makarayı izler, toplu işler gemi, ne gemi yaptığını siler | Sizin makineniz | -| Alım | Satır kimliği ve dedup anahtarı atar, sorgulanabilir sütunları yükseltir | Bulut | +| Adaptör | Çerçeve geri çağrısını 15 olay türünden birine çevirir | İşleminiz | +| Yazar | Kuyruklar, toplar, JSONL atomik olarak yazar | İşleminiz, arka plan iş parçacığı | +| Makara | Dayanıklı teslim, işleminiz çıktığında hayatta kalır | Yerel disk | +| Daemon | Makarayı izler, topluları gönderir, gönderdiklerini siler | Makineniz | +| Ingest | Satır kimliği ve dedup anahtarı atar, sorgulanabilir sütunları yükseltir | Bulut | -Makara ne yapar güvenli bu: ajanınız hiçbir zaman ağda engellenmez ve Bulut kesintisi kayıp olaylar yerine büyüyen bir dizin anlamına gelir. +Makara bunu güvenli yapar: ajanız hiçbir zaman ağda bloke olmaz ve Bulut kesintisi, kayıp olaylar yerine büyüyen bir dizin anlamına gelir. -Her temizleme bir toplu işlem dosyası yazar, ilk `.tmp`, sonra `fsync`, sonra atomik adı değiştir: +Her temizleme bir toplu dosya yazar, `.tmp` ilk, sonra `fsync`, sonra atomik yeniden adlandır: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Daemon yalnızca `.jsonl` alır, bu nedenle hiçbir zaman yarı yazılı bir dosya okunamaz. Gövde bir zaman damgası, işlem kimliği ve sıra numarası taşır, bu nedenle iki işlem aynı milisaniye içinde temizleme yapabilen çarpışamaz. Sıra 10.000 olaya sınırlı; geçtikten sonra en eski bırakır ve günlüğe kaydeder. +Daemon yalnızca `.jsonl` alır, bu nedenle asla yarı yazılı dosya okuyamaz. Gövde zaman damgası, işlem kimliği ve sıra numarası taşır, bu nedenle iki işlem aynı milisaniyede temizlenirse çarpışamaz. Kuyruk 10.000 olayda sınırlıdır; bunun ötesinde en eskisini bırakır ve kaydeder. - **`collector.redact` SDK olayları için de `minimal` varsayılan olarak belirtilir.** SDK diske bir toplu işlem yazmadan önce kaşıntı çıkarır ve daemon yeniden deneme sırasında aynı belirleneci geçişi yapar, böylece eski SDK'lardan toplu işlemler korunur. + **`collector.redact` SDK olaylarınıza uygulanmaz.** Asla onları görmez. -Daemon her toplu işlem okur ve bellekte yükleme öncesi redaction uygular. Okuduğu makara dosyasını yeniden yazmaz. +Daemon **gönderir** topluları. Açmaz veya yeniden yazmaları yapmaz. -| Olaylar | Tarafından yazıldı | Minimal redaction nerede çalışır | +| Olaylar | Tarafından yazılan | `collector.redact` tarafından redakte mi? | | --- | --- | --- | -| CLI oturum transkriptleri | Daemon | Daemon toplu işlem yazmadan önce | -| Kanca etkinliği | Daemon | Daemon toplu işlem yazmadan önce | -| **SDK yayınlayan her şey** | **Sizin işleminiz** | **SDK toplu işlem yazmadan önce ve daemon yükleme öncesi** | +| CLI oturum transkriptleri | Daemon | Evet | +| Kancanın aktivitesi | Daemon | Evet | +| **SDK'nin yayınladığı her şey** | **İşleminiz** | **Hayır** | -`collector.redact` yalnızca verbatim yükleri açık bir gereklilik olduğunda `off` ayarlayın; SDK ve daemon her ikisi de bu ayarı onurlandırır. Minimal redaction yaygın API anahtarlarını, taşıyıcı jetonlarını, JWT'leri ve gizli atamalarını yakalar. Keyfi hassas nesri tanımlayamaz. +Redaksiyon daemon'un kendi olaylarını *yazdığı* yerde çalışır — topluların *sevk edildiği* yerde değil. Bu yüzden bir istemi veya bir API anahtarı tutan araç bağımsız değişkeni varışta tutmaya devam eder. + +Bu kasıtlıdır. Bunlar kendi enstrümantasyon çağrılarınızdır ve bunları aktarım sırasında yeniden yazmak, aldığınız olayların yayınladığınız olaylar olmadığı anlamına gelir. - **Kaynakta, iki yerde yükleri kontrol edersiniz:** + **Yüklemeleri kaynakta kontrol edersiniz, iki yerde:** - - Adaptör üzerinde içerik yakalamayı kapatın. **Seçenek adı farklıdır ve bir adaptör hiç yoktur** — bu tek bir evrensel anahtar değildir: + - Adaptörde içerik yakalamayı kapatın. **Seçenek adı farklıdır ve bir adaptörün hiçbiri yoktur** — bu tek evrensel anahtar değildir: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **hiç içerik anahtarı yok**; `session_id` okuduğu tek seçenektir, bu nedenle istemler ve tamamlamalar her zaman kaydedilir. + - CrewAI — **içerik anahtarı hiç yoktur**; `session_id` okuduğu tek seçenektir, bu yüzden istekler ve tamamlamalar her zaman kaydedilir. - `instrument()` bir adaptörün okumadığı seçenekleri düşürür, bu nedenle yanlış adı geçirmek hiçbir şeyi yükseltmez ve değiştiremez. - - Gizli anahtarı ilk yerde `input=` adresine geçirmeyin. + `instrument()` bir adaptörün okumuyor olduğu seçenekleri bırakır, bu nedenle yanlış adı iletmek hiçbir şey yükseltmez ve hiçbir şey değiştirmez. + - Sırrı ilk yerde `input=` tutmayın. - `collector.redact` derinlemesine savunma, ikisinin yerine değildir. + `collector.redact` ikisi için bir yedek değil. - **Boş bir makara dizini sağlıklı durumdur.** Teslimatı kontrol etmek için kullanmayın. + **Boş bir makara dizini sağlıklı durumdur.** Teslimi kontrol etmek için kullanmayın. -Daemon her toplu işlem yükleme sayılı milisaniye içinde siler, bu nedenle bir `ls` dedektif ve yayınladığınız kesrini gösterir — hiç bir SDK kayıtlı olmamış bir dedektiften ayırt edilemez. +Daemon her topluyu gönderdikten sonra milisaniyeler içinde siler, bu yüzden `ls` toplayıcıyı yarışır ve yayınladığınız kesirini gösterir — hiçbir şey kaydeden bir SDK'dan ayırt edilemez. -Olayların gerçekten indiğini doğrulamak için panoyu kontrol edin. Makara doldurmak için izlemek için ilk daemon'u durdurun. +Olayların gerçekten iniş yaptığını doğrulamak için gösterge panelini kontrol edin. Makarayı dolmaya karşı izlemek için daemon'u ilk durdurun. - + -Her geri arama, tek işi yeniden yükseltmek olan bir sarmalayıcı içinde çalışır, bu nedenle çağrınız tam olarak bir `try` ve SDK'nın yaptığı her şey dışında oturur. +Her geri çağrı, tek işi yeniden yükseltmek olan bir sarıcı içinde çalışır, bu nedenle çağrınız tam olarak bir `try` içinde oturur ve SDK'nın yaptığı her şey bunun dışında olur. | Ne oldu | Sonuç | | --- | --- | -| Bir kanca yükseltilir | Traceback ile bir kez günlüğe kaydedildi. Çağrınız etkilenmez | -| Aynı kanca üç kez yükseltilir | O kanca, işlem geri kalanı için devre dışı bırakılır, bir hata satırı ile | -| `FAILPROOFAI_SDK_STRICT=1` ayarlandı | İstisna bunun yerine yeniden yükseltilir | -| Bir çerçeve sürümü sınanan aralığın dışında | Bir kez uyarır, yine de araç takın | -| Tek bir yetenek eksiktir | O kanca devre dışı bırakılır, asla adaptörün tamamı değil | +| Bir kancanın yükseltmesi | Traceback ile bir kez kaydedildi. Çağrınız etkilenmez | +| Aynı kancanın üç kez yükseltmesi | O bir kancanın geri kalanı için devre dışı, tek bir hata satırı | +| `FAILPROOFAI_SDK_STRICT=1` ayarlanmış | İstisna bunun yerine yeniden yükseltildi | +| Bir çerçeve sürümü test edilen aralığın dışında | Uyarılar bir kez, yine de enstrümente eder | +| Tek bir yetenek eksik | O bir kancanın devre dışı, asla tüm adaptör | -Varsayılan üretimde doğrudur ve hata ayıklama sırasında yanlış, çünkü sadece "çökertmedi" kanıtlayabilir. Yutulmuş bir başarısızlığı yüksek yapmak için `FAILPROOFAI_SDK_STRICT=1` ayarlayın. +Varsayılan, üretimde doğru ve hata ayıklarken yanlıştır, çünkü yalnızca hiçbir zaman çökmediğini kanıtlayabilir. Yutkunmuş bir başarısızlığı yüksek sesle yapmak için `FAILPROOFAI_SDK_STRICT=1` ayarlayın. @@ -699,24 +701,24 @@ Varsayılan üretimde doğrudur ve hata ayıklama sırasında yanlış, çünkü ## Yaygın sorunlar - - Bir açılış olayının hiçbir kapatma olayı yoktur: `model_response` olmayan `model_request` veya `tool_result` olmayan `tool_use`. Gövde yükselttiğinde bile çifti garantileyen kapsamları kullanın. Olay yöntemlerini doğrudan çağırırsanız, `try` ve `finally` kullanın. + + Açma olayı kapatma olayı olmaz: `model_response` olmayan `model_request` veya `tool_result` olmayan `tool_use`. Kapsamları kullanın, gövde yükseltirse bile çifti garanti ederler. Olay yöntemlerini doğrudan çağrırsanız, `try` ve `finally` kullanın. - - Eşleşen açılış olayından ölçülür, bu nedenle `tool_result`, `hook_completed`, `agent_resume` ve `human_input` üzerinde reddedilir. `model_response` adresinde kabul edilir, çünkü gerçek sağlayıcı gecikmesi yalnızca sizin biliyor ve tamsayı olması gerekir. + + Eşleşen açma olayından ölçüldüğü için `tool_result`, `hook_completed`, `agent_resume` ve `human_input` üzerinde reddedilir. `model_response` üzerinde kabul edilir, çünkü yalnızca siz gerçek sağlayıcı gecikmesini bilirsiniz ve bir tamsayı olmalı. - - İş parçacığı hiçbir zaman bağlamı devralması. Çağrılanı `failproofai_sdk.propagate()` içinde sarmalayın. [İş parçacıkları ve async](#threads-and-async) adresine bakın. + + İş parçacığı asla bağlamı devralması olmadı. Çağrıyı `failproofai_sdk.propagate()` içine sarın. Bkz. [İş parçacıkları ve async](#threads-and-async). - Ekstra alanlar en son birleşir, bu nedenle `model` veya `outcome` gibi gerçek bir alanın adıyla biri bunu üzerine yazardı ve depolanmış bir sütunu değiştirir. Sizinkini ad alanı; adaptörler bir `fw_` öneki kullanır. + Ekstra alanlar son olarak birleşir, bu nedenle `model` veya `outcome` gibi gerçek alana benzer bir ad, onu yeniden yazar ve depolanmış sütunu değiştirir. Sizinkini ad alanı yapın; adaptörler bir `fw_` ön eki kullanır. - - `agent_id` düşük kardinalite nitelik ve siz buna bir çalışma kimliği koydunuz. Bir rol veya düğüm adı kullanın ve gerçek kimliği bir yük alanına koyun. + + `agent_id` düşük kardinalite yönüdür ve bir çalışma kimliğini içine koydunuz. Rol veya düğüm adı kullanın ve gerçek kimliği yayın alanına koyun. @@ -726,8 +728,8 @@ Varsayılan üretimde doğrudur ve hata ayıklama sırasında yanlış, çünkü Çiftler, kimlikler, oturum yaşam döngüsü ve teslim. - - Yeni yakaladığınız oturum aracılığıyla nedenselliği izleyin. + + Az önce yakaladığınız oturum aracılığıyla nedenselliği takip edin. LangGraph, CrewAI, LlamaIndex ve Pydantic AI. diff --git a/docs/tr/start/quickstart.mdx b/docs/tr/start/quickstart.mdx index 13d213ab..ee5755c8 100644 --- a/docs/tr/start/quickstart.mdx +++ b/docs/tr/start/quickstart.mdx @@ -1,53 +1,59 @@ --- title: "Hızlı Başlangıç" -description: "Bir ajan oturumunu yakalayın, bir hatayı bulun ve onu engellemeye başlayın." +description: "Bir aracı oturumunu yakala, bir hatayı bul ve onu önlemeye başla." icon: "zap" --- -Bu hızlı başlangıç, bir makinenin oturumları raporlamasını sağlar, bir denetim çalıştırır ve bir politika dağıtır. Failproof AI'ı kurmak için beceriyi kullanın veya manuel adımları izleyin. +Bu hızlı başlangıç, bir makineyi oturumları raporlamaya ayarlar, bir denetim çalıştırır ve bir politika dağıtır. Failproof AI'ı kurmak için beceriyi kullanın veya manuel adımları izleyin. -**Sizin yolunuz hangisi?** Ajanınız desteklenen 12 [harnessten](/tr/reference/harnesses) birinde çalışıyorsa — bir kodlama CLI'si veya Hermes ya da OpenClaw gibi bir ağ geçidi — aşağıdaki adımları izleyin; Node.js 20.9 veya sonrası gereklidir. Ajanınızın hiç harness'i yoksa, izleme ve denetimler için onu [Python SDK](/tr/reference/custom-agents) ile enstrümente edin, ardından [İlk başarısızlık kontrolünüzü çalıştırın](/tr/start/first-audit) adımından devam edin; o yoldaki zorlama işlemi, çalışma zamanınızda bir hook gerektirir. +**Sizin yolunuz hangisi?** Aracınız 12 desteklenen [harness](/tr/reference/harnesses) türünden birinde çalışıyorsa — bir kodlama CLI'si veya Hermes veya OpenClaw gibi bir ağ geçidi — aşağıdaki adımları izleyin; Node.js 20.9 veya sonraki sürüme ihtiyacınız vardır. Aracınızın harness'i yoksa, izleme ve denetimler için [Python SDK](/tr/reference/custom-agents) ile enstrümente edin, ardından [İlk başarısızlık kontrolünüzü çalıştırın](/tr/start/first-audit) bölümüne dönün; bu yoldaki zorlama, runtime'ınızda bir hook gerektirir. - + ```bash npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Ajanınız projeyi inceleyeceğim, ilgili entegrasyonu seçecek, kurulumu yapacak ve doğrulayacaktır. Bireysel beceriler ve gelişmiş kurulum seçenekleri için [FailproofAI beceriler havuzuna](https://github.com/FailproofAI/skills) bakın. + Aracınız projeyi inceler, ilgili entegrasyonu seçer, kurulumu gerçekleştirir ve doğrular. Bireysel beceriler ve gelişmiş yükleme seçenekleri için [FailproofAI beceriler deposu](https://github.com/FailproofAI/skills) bölümüne bakın. ## Başlamadan önce -1. [Failproof AI panosunu](https://app.befailproof.ai) açın ve bir hesap oluşturun ya da iş e-postanızla oturum açın. -2. **Yönetim → Anahtarlar** bölümüne gidin ve `events:add` ve `policies:pull` izinlerine sahip bir anahtar oluşturun. -3. Tek seferlik sırrı kopyalayın ve hedef makinede depolayın: +1. [Failproof AI panosunu](https://app.befailproof.ai) açın ve bir hesap oluşturun veya iş e-postanızla oturum açın. +2. **Administration → Keys** bölümüne gidin ve `events:add` ve `policies:pull` izinlerine sahip bir anahtar oluşturun. +3. Tek kullanımlık sırrı kopyalayın, ardından hedef makinedeki bir kabukta okuyun. `read -s` bunu yankılamayan bir istemde alır, böylece komutta hiçbir zaman görünmez: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` - ## Yükleyin + ## Yükle ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - Oturum transkriptleri varsayılan olarak gönderilir. Hook aktivitesi ve politika kararlarını transkript içeriği olmadan raporlamak için `--no-transcripts` ekleyin. + Bu tek komut kurulumun tamamıdır: yerel daemon'u yükler (bir kez root), bulduğu her aracı CLI'ye hook'ları bağlar ve bu makineyi Cloud'a bağlar. Anahtarı `--token` yerine ortam aracılığıyla geçirmek, makinedeki her kullanıcının bir komutun argümanlarını okuyabileceği `ps`'ten uzak tutar. Kabuk geçmişinden uzak tutmaz — onu `read -s` ile okumak bunu yapar. CI'de, onu maskelenmiş bir gizli olarak enjekte edin ve kabuk izlemesini (`set -x`) kapalı tutun, aksi takdirde izleme bunu yazdırır. - Bu makinede zaten ajan geçmişi varsa, son yedi günü önizleyin ve içe aktarın, ardından teslimesinin bitmesini bekleyin. Yeni bir makinede bu adımı atlayın. + Oturum transkriptleri varsayılan olarak gönderilir. Transkript içeriği olmadan hook etkinliğini ve politika kararlarını raporlamak için `--no-transcripts` ekleyin. + + + Burada `failproofai config --connect ` kullanmayın. Bu bayrak **zaten** kurulu olan bir makineyi kaydeder ve hemen sonra döner — daemon yok, hook yok — bu nedenle makine Cloud'da görünürken hiçbir şey toplamaz ve zorlayamaz. + + + Bu makine zaten aracı geçmişine sahipse, son yedi günü önizleyin ve içe aktarın, ardından teslim bitene kadar bekleyin. Yeni bir makinede bu adımı atlayın. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +61,41 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Failproof AI'da **Oturumlar** bölümünü açın ve içe aktarılan bir oturumu seçin. + Failproof AI'da **Sessions** bölümünü açın ve içe aktarılan bir oturumu seçin. - - Bu, Failproof AI'ı harness'inize bağlayacak ve 39 yerleşik politikayı kuracaktır. Failproof AI oturumlarınızı denetlemeden ve ajanlarınız için politikalar yazmadan önce yerel politika kararlarını görmek ve zorlama işlemini denemek için bunları kullanın. - - Yükleyicinin harness'inizi algılamasına izin verin veya açıkça adlandırın. 12'nin her biri geçerli bir `--cli` değeridir — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + Önceki adım zaten algılanan her aracı CLI'ye hook'ları bağlamıştır. Gerektiğinde biri için açıkça yeniden çalıştırın veya daha sonra yüklenen bir harness'i eklemek için. 12'nin tümü geçerli bir `--cli` değeridir — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - Bir araç çağrısını çalışmadan önce engelleme tüm 12'de doğrulanır. Tur sonu kapıları 8'de doğrulanır — harness başına matris için [zorlama yeteneğine](/tr/reference/harnesses#enforcement-capability) bakın. + Bir araç çağrısını çalışmadan önce engellemek tümü 12'de doğrulanır. Dönüş sonu kapıları 8'de doğrulanır — harness başına matris için [zorlama yeteneğine](/tr/reference/harnesses#enforcement-capability) bakın. + + + Hook'ları bağlama hiçbir politikayı etkinleştirmez. Kurulum kasıtlı olarak hiçbirini seçmez — bu karar sizin — bu nedenle bir paket alın: + + ```bash + failproofai policies add FailproofAI/policies + ``` + + Paket, GitHub sürümünden getirilir, sağlama toplamı doğrulanır ve çözdüğü tam etikete sabitlenir. 38 politika içerir ve manifestinin katılımsız olarak etkinleştirmek için güvenli olduğunu işaretleyen 10'u açar. Bunları yerel politika kararlarını görmek ve Failproof AI aracılarınızın oturumlarını denetlemeden ve politikalarını yazmadan önce zorlama denemek için kullanın. + + Herhangi bir paketle almadan önce `failproofai policies show /` ile okuyun ve bunun sadece bir kısmını almak için [politika paketlerine](/tr/policies/packs) bakın. + + Bu çalışana kadar, zorlayan tek şey `block-failproofai-commands` — Failproof AI'ı kapatmayı durduran her zaman açık koruma. `failproofai policies` neler açık olduğunu listeler. - [İlk başarısızlık kontrolünüzü çalıştırın](/tr/start/first-audit) adımını izleyin. "Ajanın başarısız bir aracı yaklaşımını değiştirmeden yeniden denediği oturumları bul" gibi somut bir hedef kullanın. + [İlk başarısızlık kontrolünüzü çalıştırın](/tr/start/first-audit) bölümünü izleyin. Araç aracının başarısız bir aracı yaklaşımını değiştirmeden yeniden denediği oturumları bul" gibi somut bir hedef kullanın. - [İlk başarısızlığınızı bir politikayla önleyin](/tr/start/first-policy) adımını izleyin. Gözlemle modunda başlayın, eşleşmeleri inceleyin, ardından incelenen sürümü zorlayın. + [İlk başarısızlığınızı bir politikayla önleyin](/tr/start/first-policy) bölümünü izleyin. Gözlem modunda başlayın, eşleşmeleri inceleyin, ardından gözden geçirilen sürümü zorlayın. - `failproofai config --status` komutunu çalıştırın. Sağlıklı bir kurulum, bulut bağlantısını, daemon durumunu ve zorlama işleminin duraklatılıp duraklatılmadığını bildirir. + `failproofai config --status` komutunu çalıştırın. Sağlıklı bir kurulum, bulut bağlantısını, daemon durumunu ve zorlama durmasının duraklatılıp duraklatılmadığını raportar. \ No newline at end of file diff --git a/docs/tr/start/setup.mdx b/docs/tr/start/setup.mdx index d111c35b..c5d162d4 100644 --- a/docs/tr/start/setup.mdx +++ b/docs/tr/start/setup.mdx @@ -1,68 +1,89 @@ --- title: "Kurulumunuzu seçin" -description: "Yerel zorlama, Failproof AI Cloud veya kurumsal bir dağıtım seçin." +description: "Yerel uygulama, Failproof AI Cloud veya kurumsal dağıtım seçin." icon: "waypoints" --- - - Kancaları ve politikaları bir makineye kurun. Oturum verilerini Cloud'a göndermeden anında koruma raylı çözümler gerektiğinde bunu kullanın. + + Bulut anahtarı olmadan bir makineyi ayarlayın ve bir politika paketi alın. Oturum verilerini Buluta göndermeden hemen koruma gerektiğinde bunu kullanın. - Merkezi oturumlar, denetimler, çevrimiçi değerlendirmeler, gösterge tabloları, uyarılar ve filo politikası dağıtımı ekleyin. + Merkezi oturumlar, denetimler, çevrimiçi değerlendirmeler, panolar, uyarılar ve filo politikası dağıtımı ekleyin. - + Kuruluş kontrolleri, kapsamlı anahtarlar, özel altyapı ve dağıtıma özgü güvenlik gereksinimlerini kullanın. +## Yerel olarak uygulayın + +Anahtar olmadan `failproofai config` komutunu çalıştırın, ardından `failproofai policies add FailproofAI/policies` komutuyla bir paket alın. Terminal'de, kurulum Buluta bağlanmayı sorduğunda **Şimdi değil — yerel kal**'ı seçin; terminal yok ve `FAILPROOFAI_CLOUD_TOKEN` yok ise, kendi kendine yerel kalır. Daemon ve hook'lar makinede uygulama yapar ve Buluta hiçbir oturum verisi gönderilmez. Daha sonra bağlanmak için aşağıdaki adımları izleyin. + ## Önerilen üretim yolu -1. Transkript yakalaması etkinleştirilmiş şekilde üretim dışı bir makineyi bağlayın. -2. Oturumları ve değerlendirmeleri Cloud'da doğrulayın. +1. Transkript yakalama etkin olan bir üretim dışı makineyi bağlayın. +2. Bulut'ta oturumları ve değerlendirmeleri doğrulayın. 3. Bilinen bir hata modu için bir denetim oluşturun. 4. İlk politikayı gözlem modunda dağıtın. -5. Eşleşmeleri ve yanlış pozitif sonuçları gözden geçirdikten sonra üretimine geçin. +5. Eşleşmeleri ve yanlış pozitifleri inceledikten sonra üretim ortamına genişletin. -## Bir makineyi Cloud'a bağlayın +## Bir makineyi Buluta bağlayın 1. **Administration → Keys** bölümüne gidin ve `events:add` ve `policies:pull` izinleriyle bir anahtar oluşturun. 2. Tek seferlik gizli anahtarı hedef makineye kopyalayın. - 3. CLI bağlantı komutunu çalıştırdıktan sonra **Admin → enforcement** bölümüne gidin ve makinenin göründüğünü doğrulayın. + 3. CLI bağlantı komutunu çalıştırdıktan sonra, **Admin → enforcement** bölümüne gidin ve makinenin görüntülendiğini doğrulayın. 4. **Observe → Events** bölümüne gidin ve ilk etkinliğinin geldiğini doğrulayın. - Anahtar açılır penceresinde bağlı bir makine tarafından gereken iki izin gösterilir: etkinlik alımı ve politika teslimi. + Anahtar çekmecesi, bağlantılı bir makine tarafından gereken iki izni gösterir: etkinlik alımı ve politika dağıtımı. - ![Etkinlik alımı ve politika teslimi izinlerini vermek için kullanılan yeni API anahtar çekmeceği.](/images/dashboard/key-create.png) + ![Etkinlik alımı ve politika dağıtımı izinleri vermek için kullanılan yeni API anahtar çekmecesi.](/images/dashboard/key-create.png) - Bağlantıdan sonra makine, istenen ve bildirilen politika durumunu gösteren enforcement bölümünde görünmelidir. + Bağlantıdan sonra, makine, istenen ve raporlanan politika durumunu gösteren uygulamada görünmelidir. - ![Kayıtlı bir makineyi göstermek için genişletilmiş Enforcement filosu, istenen politika durumunu ve dağıtım durumunu gösterir.](/images/dashboard/enforcement-fleet.png) + ![İstenen politika durumu ve dağıtım durumunu gösteren genişletilmiş bağlı makinenin bulunduğu Uygulamalar filosu.](/images/dashboard/enforcement-fleet.png) - İlk gelen etkinlik, daemon'un politika dağıtımından bağımsız olarak verileri Cloud'a iletebileceğini doğrular. + Gelen ilk etkinlik, daemon'un politika dağıtımından bağımsız olarak Buluta veri teslim edebileceğini doğrular. - ![Son ajan, model ve araç etkinliklerini gösteren canlı etkinlik akışı.](/images/dashboard/events-stream-current.png) + ![Son aracı, model ve araç etkinliklerini gösteren canlı etkinlik akışı.](/images/dashboard/events-stream-current.png) - Hem makine hem de ilk etkinliği göründükten sonra devam edin. + Hem makine hem de ilk etkinliği görebildikten sonra devam edin. + Tek seferlik gizli anahtarı kabuğa okuyun. `read -s` onu yankılamayan bir istemde alır, bu nedenle hiçbir zaman bir komutta veya kabuk geçmişinde görünmez: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Daha sonra makineyi ayarlayın, politikalarını seçin ve adını verin: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` - Transkript içeriğinin yerel kalması gerektiğinde `--no-transcripts` ekleyin. + `failproofai config` tüm kurulumu yapar — daemon, bulduğu her aracı CLI için hook'lar ve Bulut bağlantısı — sonra hiç politika seçmez, bu yüzden ikinci komut oradadır. + + Etiket bağlantı **sırasında değil**, **sonrasında** gelir: `failproofai config --machine-label ` zaten bağlantılı olan bir makineyi yeniden adlandırır ve bağlantılı olmayan bir makine üzerinde hiçbir şey yapmaz ve sadece bunu söyler. + + Transkript içeriği yerel kalmalı ise `--no-transcripts` ekleyin. + + CI'de, `read -s` yerine `FAILPROOFAI_CLOUD_TOKEN`'ı gizli depodan ayarlayın ve kabuk izlemeyi (`set -x`) kapatın, aksi takdirde iz, anahtarı yazdırır. + + + **Zaten** ayarlanmış olan bir makinede, `failproofai config --connect ` bunu kaydeder ve başka hiçbir şey yapmaz. İlk kurulum için bu formu kullanmayın: daemon veya herhangi bir hook uygulanmadan önce döner, bir makineyi Bulut'ta göründüğü halde hiçbir şey toplamayan ve uygulamayan bir durumda bırakır. + -Cloud'a bağlanmak etkinlik alımı ve politika teslimini bağımsız olarak doğrular. Dolayısıyla bir anahtar geçerli olabilir ancak gerekli bir izne sahip olmayabilir. Hangi yeteneğin yapılandırıldığını görmek için `failproofai config --status` kullanın. +Buluta bağlanmak, etkinlik alımı ve politika dağıtımını bağımsız olarak doğrular. Bu nedenle bir anahtar geçerli olabilir ancak gerekli izinlerden biri eksik olabilir. Yapılandırılan yetenekleri görmek için `failproofai config --status` komutunu kullanın. - Cloud kurulumu, ilgili yetenek başarılı olduktan sonra yerel kimlik bilgilerini yazar. Başarısız bir doğrulama, bir makineyi bağlı gibi görünmüş olduğu halde gerçekte bağlı olmadığını gösteren bir duruma yol açmaz. + Bulut kurulumu, ilgili yetenek başarılı olduktan sonra yalnızca yerel kimlik bilgilerini yazar. Başarısız bir doğrulama, bir makineyi olmadığında bağlantılı gibi bırakmaz. \ No newline at end of file diff --git a/docs/vi/admin/keys-and-permissions.mdx b/docs/vi/admin/keys-and-permissions.mdx index 504586ad..b0a3a1d7 100644 --- a/docs/vi/admin/keys-and-permissions.mdx +++ b/docs/vi/admin/keys-and-permissions.mdx @@ -1,29 +1,29 @@ --- title: "Khóa và quyền hạn" -description: "Tạo khóa API có phạm vi cho máy, tự động hóa, và nhà khai thác." +description: "Tạo các khóa API có phạm vi cho máy, tự động hóa và nhà điều hành." icon: "key-round" --- -Khóa API thuộc về một tổ chức và mang các quyền hạn rõ ràng. Sử dụng các khóa riêng biệt cho nhập liệu tác nhân, phân phối chính sách, bộ đánh giá, tự động hóa CI, và các kịch bản quản trị. +Các khóa API thuộc về một tổ chức và mang theo các quyền hạn rõ ràng. Sử dụng các khóa riêng biệt cho nhập liệu tác nhân, phân phối chính sách, đánh giá, tự động hóa CI và tập lệnh quản trị. ## Tạo và xoay khóa - 1. Đi tới **Administration → Keys**, chọn **new key**, và nhập tên khối lượng công việc. - 2. Chọn một bộ quyền hạn và chỉ điều chỉnh các quyền hạn riêng lẻ khi bộ cài sẵn không đủ. + 1. Đi đến **Administration → Keys**, chọn **new key** và nhập tên khối lượng công việc. + 2. Chọn một tập hợp quyền hạn và chỉ điều chỉnh các quyền riêng lẻ khi tập hợp cài sẵn không đủ. 3. Tạo khóa và sao chép bí mật một lần của nó ngay lập tức. - 4. Mở khóa sau này để cập nhật cấp phát, vô hiệu hóa nó, hoặc tạo lại bí mật. + 4. Mở khóa sau này để cập nhật cấp phát, tắt nó hoặc tạo lại bí mật. - Ngăn tạo là nơi bạn chọn những cấp phát hẹp nhất cần thiết bởi khối lượng công việc. + Ngăn kéo tạo là nơi bạn chọn các cấp phát hẹp nhất yêu cầu bởi khối lượng công việc. - ![Ngăn khóa API mới với các bộ quyền hạn sẵn có và các cấp phát riêng lẻ.](/images/dashboard/key-create.png) + ![Ngăn kéo khóa API mới với các tập hợp quyền cài sẵn và các cấp phát riêng lẻ.](/images/dashboard/key-create.png) - Sau khi tạo, trang Khóa hiển thị siêu dữ liệu bền vững và các hành động quản lý. Bí mật một lần không được hiển thị lại. + Sau khi tạo, trang Keys hiển thị siêu dữ liệu liên tục và các hành động quản lý. Bí mật một lần không được hiển thị lại. - ![Trang Khóa API hiển thị quyền khóa, thời gian tạo, và các hành động tạo lại và vô hiệu hóa.](/images/dashboard/api-keys.png) + ![Trang Khóa API hiển thị quyền hạn khóa, thời gian tạo và các hành động tạo lại và tắt.](/images/dashboard/api-keys.png) - Sử dụng danh sách này để xem xét các cấp phát thường xuyên và vô hiệu hóa các khóa không còn ánh xạ tới khối lượng công việc hoạt động. + Sử dụng danh sách này để xem xét các cấp phát thường xuyên và tắt các khóa không còn ánh xạ tới khối lượng công việc hoạt động. ```bash @@ -36,25 +36,25 @@ Khóa API thuộc về một tổ chức và mang các quyền hạn rõ ràng. fp keys disable production-agents ``` - Chuyển hướng hoặc nắm bắt đầu ra tạo/tạo lại một cách an toàn; bí mật được trả lại một lần. + Chuyển hướng hoặc ghi lại đầu ra tạo/tạo lại một cách an toàn; bí mật được trả về một lần. -Hai quyền hạn cần thiết bởi máy Failproof AI kết nối là độc lập: +Hai quyền hạn yêu cầu bởi máy Failproof AI kết nối là độc lập: -- `events:add` gửi các sự kiện và dữ liệu phiên. +- `events:add` gửi sự kiện và dữ liệu phiên làm việc. - `policies:pull` truy xuất các triển khai chính sách được gán. -Bí mật khóa được hiển thị khi tạo hoặc tạo lại. Lưu trữ chúng trong một trình quản lý bí mật và xoay chúng mà không tái sử dụng thông tin xác thực tương tác của nhà khai thác. +Bí mật khóa được hiển thị khi được tạo hoặc tạo lại. Lưu trữ chúng trong trình quản lý bí mật và xoay chúng mà không tái sử dụng thông tin đăng nhập tương tác của nhà điều hành. ## Danh mục quyền hạn -| Khu vực | Quyền hạn | +| Lĩnh vực | Quyền hạn | | --- | --- | | Sự kiện | `events:add`, `events:read` | -| Khóa | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` chỉ dành cho phiên con người | +| Khóa | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`; `keys:update` chỉ cho phiên con người | | Người dùng | `users:create`, `users:read`, `users:update`, `users:delete` | -| Đánh giá | `evaluations:read`, `evaluations:trigger` | +| Đánh giá | `evaluations:read`, `evaluations:trigger`, `evaluations:run` | | Bảng điều khiển | `dashboards:read`, `dashboards:write`, `dashboards:delete` | | Truy vấn | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | | Trợ lý | `agent:use` | @@ -65,10 +65,10 @@ Bí mật khóa được hiển thị khi tạo hoặc tạo lại. Lưu trữ c | Chính sách | `policies:read`, `policies:write`, `policies:pull` | | Sử dụng | `usage:read` | -`orgs:admin` được dành riêng cho nhà khai thác thể hiện và không thể được cấp cho khóa tổ chức hoặc thành viên thông thường. Các token `incidents:*` và `alerts:ack` đã loại bỏ được chấp nhận để tương thích và chuẩn hóa thành quyền hạn `issues:*` hiện tại. +`orgs:admin` được dành riêng cho nhà điều hành thực thể và không thể được cấp cho khóa tổ chức hoặc thành viên thường. Các mã thông báo `incidents:*` và `alerts:ack` đã loại bỏ được chấp nhận để tương thích và chuẩn hóa thành quyền hạn `issues:*` hiện tại. -Các bộ quyền hạn tích hợp là `read-only`, `standard`, và `admin`. `standard` bổ sung kích hoạt đánh giá, thực thi truy vấn, phản ứng vấn đề, và sử dụng trợ lý cho các quyền hạn đọc. Tạo khóa loại bỏ các cấp phát chỉ dành cho con người ngay cả khi một bộ quyền hạn chứa chúng. +Các tập hợp quyền hạn tích hợp là `read-only`, `standard` và `admin`. `standard` thêm kích hoạt đánh giá, thực thi truy vấn, phản hồi vấn đề và sử dụng trợ lý cho quyền hạn đọc. Tạo khóa loại bỏ các cấp phát chỉ dành cho con người ngay cả khi tập hợp quyền hạn chứa chúng. - Khóa có phạm vi thể hiện có thể chọn một tổ chức bằng tiêu đề `X-AgentEye-Org`. Đặt nó rõ ràng trên các triển khai đa tổ chức; việc bỏ qua có thể chọn tổ chức mặc định. + Các khóa có phạm vi thực thể có thể chọn một tổ chức bằng tiêu đề `X-AgentEye-Org`. Đặt nó một cách rõ ràng trên các triển khai đa tổ chức; việc bỏ qua có thể chọn tổ chức mặc định. \ No newline at end of file diff --git a/docs/vi/evaluations/deploy.mdx b/docs/vi/evaluations/deploy.mdx new file mode 100644 index 00000000..d38f31f1 --- /dev/null +++ b/docs/vi/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "Triển khai và phiên bản hóa một evaluation" +description: "Triển khai một phiên bản bất biến, xem những gì đang hoạt động, xuất bản các phiên bản mới, quay lại phiên bản trước, và chấm điểm các phiên làm việc bạn đã có." +icon: "cloud-upload" +--- + +## Triển khai + +Chọn **deploy `@`** ở dưới cùng của trang soạn thảo. Phiên bản trở thành bất biến sau khi được xuất bản: từ đó trở đi, mọi phiên làm việc kết thúc mà điều kiện của nó áp dụng sẽ được chấm điểm bởi nó. + +## Xem những gì đang hoạt động + +**Analyze → eval authoring** liệt kê các định nghĩa được lưu trữ của tổ chức bạn, những evaluation mà trình đánh giá được quản lý chạy cho nó. Mỗi hàng hiển thị: + +- tên, khóa, phiên bản và loại kết quả của nó +- mã kiểm tra nguồn của nó, cho phép phân biệt các bản triển khai mà không cần mở mã +- liệu nó có **điều kiện** hay chạy trên **tất cả các phiên làm việc đã hoàn thành** — điều kiện là những gì giới hạn một evaluation để đặc trưng cho các agent hoặc môi trường cụ thể +- thời gian chờ, nhãn của nó và thời điểm nó thay đổi lần cuối + +![Danh sách các định nghĩa được lưu trữ: tên, khóa, phiên bản, loại kết quả, mã kiểm tra, thời gian chờ và phạm vi của mỗi evaluation, với tùy chọn phiên bản mới và bật hoặc tắt.](/images/dashboard/eval-definitions.png) + +Tìm kiếm danh sách hoặc lọc theo trạng thái. Các evaluation mà worker của bạn tự đăng ký không được liệt kê ở đây; kết quả của chúng mang thẻ **customer** trên [trang evaluations](/vi/sessions/evaluations), và những cái được quản lý mang thẻ **managed**. + +Một tổ chức có thể có tối đa 100 evaluation được lưu trữ khác nhau được bật cùng một lúc. + +## Xuất bản phiên bản mới + +Chọn **new version** trên một hàng. Trang soạn thảo mở với mã của phiên bản đó; thay đổi nó, kiểm tra nó và triển khai nó. Khóa và loại kết quả của nó được chuyển giao và không thể thay đổi. + +Xuất bản một phiên bản kế tiếp sẽ vô hiệu hóa phần trước của nó và giữ nó trên danh sách. Kết quả giữ lại phiên bản đã tạo ra chúng, do đó biểu đồ cho thấy chính xác khi nào logic mới đảm nhận. + +## Quay lại phiên bản trước + +Chọn **disable** trên phiên bản hiện tại và **enable** trên phiên bản bạn muốn quay lại. Không có gì bị xóa, và mọi kết quả vẫn như cũ. + +## Dừng một evaluation + +Chọn **disable**. Khi không có phiên bản nào được bật, nó sẽ dừng chạy trên các phiên làm việc mới. Để dừng một evaluation mà worker của riêng bạn chạy, hãy dừng đăng ký nó: xóa nó khỏi worker hoặc dừng worker. + +## Chấm điểm các phiên làm việc bạn đã có + +Evaluation chạy về phía trước: một phiên bản được triển khai bây giờ sẽ không bao giờ chấm điểm một phiên làm việc kết thúc trước đó. Để chấm điểm lịch sử, hãy mở **score sessions you already have** trên trang soạn thảo eval, chọn một khoảng thời gian tối đa 90 ngày và tùy chọn một evaluation duy nhất, và đếm trước khi chạy. Số lượng chính xác là những gì sẽ chạy, và mỗi cặp phiên làm việc và evaluation trong nó là một evaluation có thể tính phí. + +Nó chỉ lấp đầy những khoảng trống. Một phiên làm việc đã có kết quả cho evaluation đó sẽ giữ lại, và chạy cùng một cửa sổ hai lần sẽ không chấm điểm gì mới. + +Để chấm điểm một phiên làm việc lại — sau khi sửa chữa hoặc cho một phiên làm việc không bao giờ kết thúc sạch sẽ — chọn **re-evaluate** trên trang của nó. Kết quả mới được thêm vào lịch sử phiên làm việc; những cái trước đó vẫn giữ nguyên. + +## Quyền hạn + +| Quyền hạn | Cho phép bạn | +| --- | --- | +| `evaluations:read` | Xem kết quả và mở trang soạn thảo eval | +| `evaluations:trigger` | Xem, triển khai, phiên bản hóa, bật và tắt các định nghĩa được lưu trữ; kiểm tra chúng; chấm điểm lịch sử; đánh giá lại một phiên làm việc | +| `events:read` | Kiểm tra với các phiên làm việc thực và định vị các bản nháp trong các khóa payload của bạn, trên cơ sở `evaluations:trigger` | +| `evaluations:run` | Chạy worker evaluator của riêng bạn | \ No newline at end of file diff --git a/docs/vi/evaluations/overview.mdx b/docs/vi/evaluations/overview.mdx new file mode 100644 index 00000000..2a6f2361 --- /dev/null +++ b/docs/vi/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "Đánh giá các agent" +description: "Chấm điểm mỗi phiên làm việc hoàn tất với các đánh giá bạn định nghĩa: các kiểm tra Python được lưu trữ hoặc các tr裁判LLM trong worker của riêng bạn." +icon: "gauge" +--- + +Một đánh giá chấm điểm một phiên agent hoàn tất. Khi một phiên kết thúc, mỗi đánh giá được bật và áp dụng cho nó sẽ chạy và ghi lại những gì nó tìm thấy, kèm theo lý do bạn có thể đọc bên cạnh trace: + +- một **điểm số** từ 0 đến 1, tùy chọn được đánh dấu là đã vượt qua hoặc không vượt qua +- một **chỉ số**, chẳng hạn như số lượng, thời lượng hoặc chi phí, kèm theo đơn vị của nó +- một **khẳng định**, đã vượt qua hoặc không vượt qua + +## Hai loại trình đánh giá + +| | Python được lưu trữ | Worker của riêng bạn | +| --- | --- | --- | +| Được viết | Trong bảng điều khiển, ở **Analyze → eval authoring** | Bằng Python, với [Evaluator SDK](/vi/reference/evaluator-sdk) | +| Chạy | Trên trình đánh giá được quản lý của Failproof AI, trong một sandbox | Trên cơ sở hạ tầng của bạn | +| Tốt nhất cho | Các kiểm tra xác định, dựa trên mã | Các tr裁判 LLM, lệnh gọi mô hình, gói, bí mật, truy cập mạng, xử lý nặng | + +Python được lưu trữ được thiết kế một cách cố ý nhỏ: một biểu thức, không có nhập khẩu, không có mạng. Bất cứ điều gì cần một mô hình — một tr裁判 LLM chấm điểm xem liệu một câu trả lời có phù hợp hay không, chẳng hạn — chạy trong worker của riêng bạn. Cả hai loại đều không cần kết nối vào: worker yêu cầu các phiên hoàn tất và gửi kết quả qua HTTPS đi ra ngoài. + +## Mỗi tổ chức đánh giá các agent của riêng nó + +Các đánh giá thuộc về tổ chức xác định chúng. Mỗi tổ chức trên một instance viết của riêng nó — các kiểm tra, điều kiện, ngưỡng và nhãn của riêng nó — các phiên bản và triển khai chúng mà không ảnh hưởng đến bất kỳ phiên bản nào khác, và chỉ xem kết quả của riêng nó. Lọc những kết quả đó theo agent, môi trường, đánh giá và thời gian, hoặc hỏi trợ lý về chúng. + +## Từ bản nháp đầu tiên đến các điểm số trực tiếp + + + + Mô tả những gì cần đo lường và để trợ lý soạn thảo nó, hoặc viết nó yourself. Xem [Write an evaluation](/vi/evaluations/write). + + + Chạy nó với các phiên thực tế trước khi nó đi trực tiếp; không có gì được lưu trữ. Xem [Test an evaluation](/vi/evaluations/test). + + + Triển khai một phiên bản bất biến, xuất bản những phiên bản mới khi nó phát triển, và quay lại một phiên bản trước đó. Xem [Deploy and version](/vi/evaluations/deploy). + + + Vẽ biểu đồ điểm số theo thời gian, so sánh các agent và môi trường, và hỏi trợ lý. Xem [Read evaluation results](/vi/sessions/evaluations). + + + +Đánh giá chạy về phía trước: một phiên bản triển khai ngay bây giờ chấm điểm các phiên hoàn tất từ bây giờ trở đi. Để chấm điểm các phiên bạn đã có, [backfill chúng](/vi/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file diff --git a/docs/vi/evaluations/test.mdx b/docs/vi/evaluations/test.mdx new file mode 100644 index 00000000..306ef667 --- /dev/null +++ b/docs/vi/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "Kiểm tra một đánh giá" +description: "Chạy một đánh giá dựa trên các phiên làm việc thực tế của bạn trước khi triển khai. Không có dữ liệu nào được lưu trữ." +icon: "flask-conical" +--- + +**kiểm tra đánh giá này**, trên trang tác giả, chạy mã dựa trên các phiên làm việc thực tế của bạn trên fleet đánh giá mà không triển khai nó. Không có dữ liệu nào được lưu trữ: một lỗi ở đây chỉ là xem trước, và triển khai luôn được phép. + + + + Chọn **check** để biên dịch mã và điều kiện dựa trên quy tắc của sandbox mà không chạy chúng trên bất kỳ phiên nào. + + + Thu hẹp các phiên phù hợp theo agent, môi trường, thời gian hoặc id phiên, và chọn tối đa 10. Bao gồm các phiên mà đánh giá này nên thất bại cũng như những phiên nó nên thành công. + + + Chọn **run against N sessions**, và đọc từng hàng. + + + +| Hàng | Ý nghĩa | +| --- | --- | +| **ok** | Nó đã chạy. Hàng liệt kê mọi điểm, metric và assertion nó trả về, và thời gian thực hiện. | +| **skipped** | Điều kiện trả về `False`, vì vậy đánh giá không chạy. Đó là bỏ qua, không phải lỗi. | +| Failed | Nó đã đưa ra ngoại lệ, hết thời gian chờ, hoặc sử dụng thứ gì đó mà sandbox từ chối. Hàng sẽ cho biết điều đó, và **Fix it** chuyển lỗi cho trợ lý khi nó có thể giúp đỡ. | + +![Panel kiểm tra đánh giá này: ba phiên được chọn theo agent, hai phiên ok và một phiên bị bỏ qua vì điều kiện của nó trả về False.](/images/dashboard/eval-test.png) + +Một kết quả không còn hiện tại ngay khi bạn chỉnh sửa mã; nó sẽ bị làm mờ thay vì được tái sử dụng. \ No newline at end of file diff --git a/docs/vi/evaluations/write.mdx b/docs/vi/evaluations/write.mdx new file mode 100644 index 00000000..9e3f29ad --- /dev/null +++ b/docs/vi/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "Viết một bài đánh giá" +description: "Mô tả những gì cần đo lường và để trợ lý soạn thảo một bài đánh giá Python được lưu trữ, hoặc viết mã của riêng bạn. Các trọng tài LLM chạy trong worker của riêng bạn." +icon: "file-pen-line" +--- + +Các bài đánh giá được lưu trữ là những chương trình Python nhỏ và xác định, được viết trong bảng điều khiển và chạy trên đội đánh giá của Failproof AI. Logics nặng hơn — một trọng tài LLM, một gói, một bí mật, một lệnh gọi mạng — chạy trong [worker của riêng bạn](#write-it-in-your-own-worker) thay thế. + +## Soạn thảo từ một mô tả + +1. Đi tới **Analyze → eval authoring** và chọn **new eval**. +2. Mô tả những gì cần đo lường bằng tiếng Anh thường nhật, hoặc chọn từ **start from an example…**, rồi chọn **draft**. +3. Xem xét các trường và mã nó điền vào, sau đó [kiểm tra nó](/vi/evaluations/test) và [triển khai nó](/vi/evaluations/deploy). + +![Trang soạn thảo eval với một bài đánh giá được soạn thảo: mô tả, ghi chú của trợ lý về bản soạn thảo, và các trường tên, khóa, phiên bản, kết quả, thời gian chờ, nhãn và điều kiện.](/images/dashboard/eval-authoring-draft.png) + +Bản soạn thảo được dựa trên các sự kiện của riêng tổ chức bạn: trang đọc những khóa tải trọng nào mà phiên của bạn đã sử dụng trong bảy ngày qua, vì vậy mã đọc các khóa tồn tại thay vì đoán. Trước khi chuyển bản soạn thảo, trợ lý kiểm tra nó dựa trên tối đa năm phiên gần đây của bạn, sửa chữa bất cứ điều gì nó có thể chứng minh là bị hỏng — trong tối đa ba vòng — và kiểm tra một lần rằng mã đo lường những gì bạn yêu cầu. Giữ mô tả cụ thể: các lời nhắc rộng nham rổn hơn và có thể hết thời gian chờ. Xem xét mã dù sao; triển khai không bao giờ bị chặn. + +## Đặt các trường + +| Trường | Nó là gì | +| --- | --- | +| name | Những gì mọi người nhìn thấy. Có thể chỉnh sửa sau | +| key | Định danh ổn định của nó kết quả sơ đồ dưới, chẳng hạn như `code_assistant_quality_gate` | +| version | Bất kỳ chuỗi phiên bản nào không có khoảng trắng, chẳng hạn như `1.0.0` | +| result | **score** (0 đến 1), **metric** (một số có một đơn vị), hoặc **assertion** (passed hoặc không) | +| timeout seconds | Mặc định 30. Hộp cát dừng bất kỳ lần chạy nào ở 60 | +| labels | Tối đa 20, cách nhau bằng dấu phẩy. Có thể chỉnh sửa sau | +| condition | Tùy chọn. Một biểu thức Python; bài đánh giá chỉ chạy trên các phiên mà nó là `True` | + +Sử dụng điều kiện để phạm vi bài đánh giá đến các agent và môi trường nó được dùng cho: + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +Khóa, phiên bản, loại kết quả, điều kiện và mã là bất biến sau khi triển khai: để thay đổi bất kỳ trong số chúng, hãy xuất bản một phiên bản mới. Tên, nhãn và liệu nó được bật vẫn có thể chỉnh sửa. + +## Viết mã của riêng bạn + +**evaluator code** là một biểu thức Python trả về `EvalResult(...)`, có `session` trong phạm vi. Cái này ghi điểm phần chia của kết quả công cụ quay trở lại ok: + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +Một kết quả dẫn đầu với khóa riêng của bài đánh giá, trong loại khai báo của nó: `score=` cho một bài đánh giá điểm, hoặc một `metrics` hoặc `assertions` mục được đặt tên theo khóa cho một số liệu hoặc một bài đánh giá khẳng định. Các số liệu và khẳng định khác đi cùng với nó, lên tới 25 kết quả trong một lần chạy. + +| Trong phạm vi | Cung cấp cho bạn | +| --- | --- | +| `session` | `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `event_count`, và `events`, cộng với `count(event_type)` và `events_of_type(event_type)` | +| Mỗi sự kiện | `id`, `ts`, `event_type`, và `payload` | +| Loại kết quả | `EvalResult`, `Score`, `Metric`, `Assertion`, và `ConditionResult` cho một điều kiện | +| Builtins | `abs`, `all`, `any`, `bool`, `dict`, `float`, `int`, `len`, `list`, `max`, `min`, `range`, `round`, `set`, `sorted`, `str`, `sum`, `tuple` | + +Không gì khác là có thể tiếp cận: không nhập, và không có thuộc tính ngoài dữ liệu phiên đó và các phương thức chuỗi và từ điển thông thường chẳng hạn như `get`, `lower`, và `split`, chúng phải được gọi chứ không phải được tham chiếu. Khóa tải trọng là bất cứ thứ gì các agent của bạn gửi — `status` ở trên chỉ là một ví dụ — vì vậy hãy đọc chúng từ một phiên thực. **format** làm gọn mã và **fix** yêu cầu trợ lý sửa chữa nó. Mã có thể lên tới 128 KiB, và điều kiện lên tới 16 KiB. + +![Trình chỉnh sửa mã đánh giá, với định dạng và sửa chữa, cho thấy các khẳng định của một bài đánh giá được soạn thảo.](/images/dashboard/eval-authoring-code.png) + +## Viết nó trong worker của riêng bạn + +Khi một bài đánh giá cần một mô hình, một gói, một bí mật, hoặc mạng, hãy viết nó với [Evaluator SDK](/vi/reference/evaluator-sdk) và chạy nó trên cơ sở hạ tầng của riêng bạn. Nó sử dụng các loại kết quả tương tự, và kết quả của nó xuất hiện bên cạnh những kết quả được lưu trữ, được gắn thẻ **customer**: + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/vi/policies/deploy.mdx b/docs/vi/policies/deploy.mdx index 439b9dee..48bce236 100644 --- a/docs/vi/policies/deploy.mdx +++ b/docs/vi/policies/deploy.mdx @@ -1,51 +1,94 @@ --- -title: "Triển khai chính sách" -description: "Đưa phiên bản chính sách đã xem xét ra các máy được chỉ định." +title: "Triển khai một policy" +description: "Đưa một phiên bản policy đã kiểm tra lên các máy ở chế độ observe, thực thi nó, và xác nhận mọi máy đã nhận được." icon: "cloud-upload" --- -Một triển khai kết nối một hoặc nhiều phiên bản chính sách với một tập hợp các máy đã được đăng ký. +Một deployment đưa các phiên bản policy đã xuất bản lên một máy, mỗi phiên bản có một trong hai hiệu ứng: -## Áp dụng một triển khai +- **Observe** ghi lại những gì policy sẽ làm, và không chặn bất kỳ điều gì. +- **Enforce** thực hiện quyết định: một `deny` chặn cuộc gọi và một `instruct` điều hướng agent. + +## Thêm một máy + +Một máy xuất hiện dưới **Admin → enforcement** sau khi nó kết nối với Cloud. Nếu máy bạn muốn chưa có ở đó: - 1. Truy cập **Admin → enforcement**, tìm máy và mở rộng hàng của nó. - 2. Chọn **edit**, thêm phiên bản chính sách đã xem xét, và chọn **observe** hoặc hiệu ứng thực thi của nó. - 3. Áp dụng thay đổi, sau đó đợi lần kiểm tra tiếp theo của máy và xác nhận trạng thái triển khai và phạm vi của nó. - 4. Truy cập **Observe → policy** để kiểm tra các quyết định trực tiếp. - - ![Trình chỉnh sửa triển khai máy với các phiên bản chính sách, hiệu ứng enforce và observe, và hành động áp dụng triển khai.](/images/dashboard/enforcement-editor.png) + 1. Đi tới **Administration → Keys** và tạo một khóa với `policies:pull`, để máy có thể nhận các deployment, và `events:add`, để các quyết định của nó đạt tới Cloud. + 2. Kết nối máy với khóa đó — [Connect a machine to Cloud](/vi/start/setup#connect-a-machine-to-cloud) hướng dẫn từng bước. + 3. Xác nhận nó xuất hiện dưới **Admin → enforcement**. - Triển khai từ CLI bằng `fp fleet`. Xem xét tập hợp kết quả trước khi áp dụng — `deploy` in ra toàn bộ kế hoạch và chỉ hỏi **trên terminal tương tác mà không có `--json`**. Dưới `--json`, với `--yes`, hoặc với stdin được chuyển hướng (một bước CI, một script, một agent chạy lệnh shell) nó sẽ áp dụng ngay lập tức mà không có kế hoạch và không có lời nhắc — vì vậy hãy chạy `fp fleet show ` trước nếu bạn muốn xem xét: + Trên máy: + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + Trong terminal, `failproofai config` hỏi có muốn kết nối với Cloud và nhận khóa tại một dấu nhắc ẩn. Sau đó xác nhận máy đã được đăng ký, từ bất kỳ đâu, bằng `fp fleet list`. + + + +## Triển khai ở chế độ observe + + + + 1. Đi tới **Admin → enforcement**, tìm máy, và mở rộng hàng của nó. + 2. Chọn **edit**, thêm phiên bản policy đã kiểm tra, và chọn **observe**. + 3. Áp dụng thay đổi, sau đó chờ đợi lần check-in tiếp theo của máy và xác nhận trạng thái deployment và coverage của nó. + 4. Đi tới **Observe → policy** để kiểm tra các quyết định trực tiếp. + ![Trình chỉnh sửa deployment máy với các phiên bản policy, hiệu ứng enforce và observe, và hành động áp dụng deployment.](/images/dashboard/enforcement-editor.png) + + ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` hiển thị ý định so với việc phân phối (một máy được đọc là `behind` cho đến khi nó tiếp theo thăm dò), `fp fleet history ` liệt kê các thế hệ, và `fp fleet rollback ` khôi phục một thế hệ — nó từ chối nếu thế hệ đó đặt tên cho một chính sách vì đã bị tắt hoặc xóa. + Hậu tố `:observe` là thứ làm nó observe: một `--add no-force-push` đơn thuần giữ lại hiệu ứng mà máy đã có cho policy đó, và ngoài ra thực thi. Chuyển nó sang enforce sau này bằng `--add no-force-push:enforce`. + + `deploy` **thay thế toàn bộ tập hợp policy của máy** bằng kết quả. Nó in ra kế hoạch, sau đó hỏi trước khi áp dụng — nhưng chỉ trên một terminal tương tác. Với `--yes`, dưới `fp --json`, hoặc với stdin được chuyển hướng (một bước CI, một kịch bản, một agent gọi shell) nó sẽ áp dụng mà không hỏi; kế hoạch vẫn được in hoặc trả về dưới dạng `plan` trong `--json`. - Kiểm tra chính máy với `failproofai config --status`, và sử dụng `fp sessions --env production --since 24h` và `fp events --event-type hook_completed` sau khi triển khai để xác minh hoạt động đến Cloud. + Trên máy, `failproofai policies` liệt kê các policy do Cloud quản lý mà nó đang chạy và `failproofai config --status` hiển thị kết nối của nó. Sử dụng `fp sessions --env production --since 24h` và `fp events --event-type hook_completed` để xác nhận hoạt động của nó đạt tới Cloud. - - Triển khai một phiên bản đã xem xét, không phải bản nháp có thể thay đổi được, bắt đầu bằng một máy không phải sản xuất hoặc một nhóm nhỏ mà bạn có thể kiểm tra các phiên làm việc của nó. + + Chọn phiên bản đã xuất bản và các máy nó sẽ chạy trên đó. - - Xem xét các kết quả trùng khớp, lý do, công cụ bị ảnh hưởng và dương tính giả mà không chặn công việc. + + Kiểm tra các kết quả khớp, lý do, công cụ bị ảnh hưởng, và những lần dương tính giả trong khi không có gì bị chặn. - - Nâng cấp sau khi các kết quả quan sát được tách các hành động không an toàn khỏi các hành động hợp lệ, sau đó xác nhận mọi máy dự định đã kéo bản triển khai và đang báo cáo quyết định. + + Chuyển hiệu ứng thành enforce sau khi các kết quả được quan sát tách biệt các hành động không an toàn khỏi những hành động hợp lệ, sau đó xác nhận mọi máy dự định đã kéo thay đổi và đang báo cáo quyết định. -Các máy cần khả năng `policies:pull`. Báo cáo sự kiện được kiểm soát riêng biệt bởi `events:add`; xác minh cả hai khi bạn mong đợi phân tích và thực thi Cloud. +## Kiểm tra coverage + +Coverage trả lời câu hỏi liệu một policy có đang chạy nơi có rủi ro không. + +1. Đi tới **Admin → enforcement** và kiểm tra tổng số enforcing và observing. +2. Tìm kiếm một máy theo ID hoặc nhãn, hoặc lọc các máy thiếu một policy. +3. Mở rộng một hàng để so sánh các policy được gán, deployment được báo cáo, lần check-in cuối cùng, và lịch sử. +4. Làm mới sau khoảng thời gian polling của máy khi một deployment được áp dụng vẫn đang chờ xử lý. + +![Lực lượng Enforcement hiển thị coverage policy, trạng thái deployment máy, và các gán observe và enforce.](/images/dashboard/enforcement-fleet.png) + +Tìm các máy chưa bao giờ kéo latest deployment, các máy đã đăng ký ngừng báo cáo, một policy được gán cho môi trường sai, và version drift sau khi cập nhật bị gián đoạn. + +Gắn nhãn máy theo workload và môi trường — chỉ tên máy chủ hiếm khi sống sót qua autoscaling hoặc thay thế: + +```bash +failproofai config --machine-label checkout-runner-03 +``` - Quản lý thực thi là một quy trình công việc Cloud của quản trị viên. Không coi các tuyến thực thi chỉ root như các điểm cuối API `/v1` khách hàng thông thường. + Enforcement management là một quy trình Cloud quản trị. Đừng coi các tuyến đường enforcement chỉ dành cho root là các endpoint `/v1` API khách hàng thông thường. \ No newline at end of file diff --git a/docs/vi/policies/editor.mdx b/docs/vi/policies/editor.mdx index a65fa1db..ca267c3c 100644 --- a/docs/vi/policies/editor.mdx +++ b/docs/vi/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "Trình soạn thảo chính sách" -description: "Tạo và sửa đổi các chính sách có phiên bản từ một chế độ lỗi đã được xác nhận." +title: "Viết một chính sách" +description: "Cho phép Failproof AI soạn thảo một chính sách từ kết quả kiểm tra, hoặc tự viết nguồn, sau đó xem xét, kiểm tra và xuất bản." icon: "file-pen-line" --- -Sử dụng trình soạn thảo chính sách để biến một phát hiện hoặc vấn đề thành một quy tắc có thể triển khai. Giữ tác vụ soạn thảo riêng biệt với triển khai để một bản nháp không thể âm thầm thay đổi hành vi hiện tại. +Có hai cách để viết một chính sách: cho phép Failproof AI soạn thảo từ kết quả kiểm tra, hoặc tự viết nguồn. Không có gì được xuất bản hoặc triển khai cho đến khi bạn chọn. -Khi một vấn đề có mẫu hành động có thể lặp lại, hãy mở nó trong **Analyze → issues** và chọn **generate policy**. Failproof AI trước tiên giải thích liệu một chính sách có thể biểu thị vấn đề hay không, sau đó đưa ý định đã xem xét và bối cảnh phát hiện vào trình soạn thảo. Nguồn được tạo ra vẫn là bản nháp cho đến khi bạn xuất bản nó. +## Viết một chính sách từ một cuộc kiểm tra -## Xuất bản một phiên bản chính sách +Một cuộc kiểm tra phát hiện một lỗi; một chính sách ngăn chặn nó lặp lại. Failproof AI soạn thảo chính sách từ bằng chứng của kết quả phát hiện. + +### 1. Chạy một cuộc kiểm tra + +[Chạy một cuộc kiểm tra](/vi/audits/run) trên các phiên làm việc nơi lỗi xảy ra. Mỗi kết quả phát hiện mang theo các phiên bằng chứng, nguyên nhân gốc rễ và đường dẫn ngăn chặn được đề xuất. Làm việc từ một kết quả phát hiện có **mẫu hành động có thể lặp lại** — một chính sách chỉ có thể ngăn chặn những gì nó có thể nhận dạng trong sự kiện hook. + +### 2. Tạo bản nháp - 1. Đi tới **Admin → policy editor** và trong **compose**, mô tả chế độ lỗi hoặc dán nguồn chính sách JavaScript. - 2. Xác nhận nguồn và sửa lỗi từng cái được báo cáo. - 3. Nhập danh tính chính sách và xuất bản nó, sau đó sử dụng **library** để so sánh hoặc vô hiệu hóa các phiên bản. - 4. Chọn **enforcement** khi phiên bản sẵn sàng để triển khai máy. + 1. Mở vấn đề phát hiện dưới **Analyze → issues** và kiểm tra các phiên được trích dẫn, nguyên nhân gốc rễ và khuyến cáo. + 2. Chọn **generate policy**. Failproof AI trước tiên cho biết liệu chính sách có thể biểu đạt vấn đề hay không. Kết quả **no policy** có nghĩa là bản sửa lỗi là một cảnh báo, thay đổi quy trình làm việc hoặc một người — không phải một chính sách. + 3. Chọn **write this policy**. Tiêu đề vấn đề, kết quả phát hiện, nguyên nhân gốc rễ, khuyến cáo và ý định thực thi được đề xuất trở thành bản nháp trong **Admin → policy editor**. Sử dụng **open the editor anyway** khi bạn không đồng ý với kiểm tra ứng cử viên. - ![Chế độ soạn thảo của trình soạn thảo chính sách với danh tính chính sách, soạn thảo hỗ trợ AI, xác nhận nguồn và kiểm soát xuất bản.](/images/dashboard/policy-editor.png) + ![Chế độ soạn thảo trình soạn chính sách với danh tính chính sách, soạn thảo hỗ trợ AI, xác thực nguồn và điều khiển xuất bản.](/images/dashboard/policy-editor.png) - Xuất bản từ CLI bằng `fp policies publish`. Nó tạo ra một **phiên bản mới** và không bao giờ chỉnh sửa một phiên bản tại chỗ, và nó kiểm tra cú pháp nguồn bằng node trước khi gửi — không có gì phía sau làm, vì vậy một lỗi cú pháp sẽ xuất hiện trên máy tại thời điểm thực thi: + Đọc bằng chứng, sau đó soạn thảo với trợ lý. `compose` in nguồn để bạn xem xét và không xuất bản bất cứ điều gì: ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - Xuất bản không triển khai bất cứ điều gì — một phiên bản mới không được sử dụng cho đến khi `fp fleet deploy` đặt nó trên một máy. `fp policies compose ""` soạn thảo nguồn với trợ lý Cloud và in nó để xem xét thay vì xuất bản nó. - - Để cài đặt một chính sách vào CLI tác nhân cục bộ thay vào đó (không phải Cloud), hãy sử dụng `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. + `compose` cần một phiên đã đăng nhập (`fp login`) có vai trò `policies:write`; nó từ chối các khóa API. -## Danh sách kiểm tra tác vụ soạn thảo +### 3. Xem xét bản nháp + +Bản nháp là điểm khởi đầu, không phải một phán quyết. Trước khi xuất bản, hãy kiểm tra rằng nó: + +1. Đặt tên chế độ lỗi bằng ngôn ngữ vận hành. +2. Khớp chỉ các sự kiện hook và công cụ mang đủ bằng chứng để quyết định. +3. Sử dụng điều kiện hẹp nhất bắt được hành động không an toàn. +4. Trả lại một lý do cho agent biết phải làm gì khác. +5. Sử dụng `instruct` khi agent có thể an toàn sửa đổi hướng, và `deny` chỉ khi cho phép hành động là không thể chấp nhận được hoặc không thể đảo ngược. + +Xác thực nguồn trong trình soạn thảo và sửa tất cả các lỗi được báo cáo. + +### 4. Kiểm tra, sau đó xuất bản + +Chạy **backtest** dưới nguồn trước khi bạn xuất bản: nó phát lại bản nháp dựa trên các lệnh gọi mà hạm đội của bạn đã thực hiện và đếm số lượng các lệnh gọi hoạt động mà nó sẽ đã gián đoạn. [Test a policy](/vi/policies/test) bao gồm điều đó và các kiểm tra khác. + +Khi nó hoạt động, nhập danh tính chính sách và chọn **publish version**. Xuất bản tạo một phiên bản bất biến và không triển khai bất cứ điều gì: nó nằm không được sử dụng cho đến khi bạn [triển khai nó](/vi/policies/deploy). Từ một terminal: + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` kiểm tra phân tích cú pháp nguồn trước khi gửi, vì vậy lỗi cú pháp sẽ xuất hiện ở đây thay vì trên máy tại thời điểm thực thi. + +## Tự viết nó + +Một chính sách là JavaScript hoặc TypeScript dựa trên API `failproofai`: + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +Điều này khớp `production/config.yml`, `/srv/production/config.yml`, `/srv/production` và `C:\\production\\config.yml` cho cả `Write` và `Edit`, nhưng không phải `production-backup`: `production` phải là một phân đoạn đường dẫn hoàn chỉnh. Ngữ cảnh cũng mang theo loại sự kiện, tải trọng chuẩn hóa, siêu dữ liệu phiên, tham số và CLI nguồn khi có sẵn — xem [policy SDK](/vi/reference/policy-sdk). + +Để xuất bản nó như một phiên bản, dán nguồn vào **compose** trong **Admin → policy editor** và làm theo các bước 3 và 4 ở trên, hoặc xuất bản tệp từ terminal bằng `fp policies publish`. -1. Đặt tên cho chế độ lỗi bằng ngôn ngữ hoạt động. -2. Chọn các sự kiện hook và công cụ chứa đủ bằng chứng để quyết định. -3. Viết điều kiện hẹp nhất phù hợp với hành vi không an toàn. -4. Trả về lý do cho tác nhân hoặc nhà điều hành biết phải làm gì tiếp theo. -5. Thêm ví dụ phải khớp và ví dụ phải vẫn được phép. -6. Lưu một phiên bản mới và yêu cầu xem xét. +Để chạy nó trên máy mà không có Cloud, lưu nó dưới `.failproofai/policies/` với tên kết thúc bằng `policies.js`, `policies.mjs` hoặc `policies.ts` — những cái này tải tự động ở phạm vi dự án và người dùng — hoặc cài đặt nó theo đường dẫn: -Sử dụng `instruct` khi tác nhân có thể an toàn sửa lỗi đường hướng. Sử dụng `deny` khi cho phép hành động sẽ tạo ra rủi ro không thể chấp nhận hoặc không thể đảo ngược. +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - Các phiên bản chính sách là đầu vào triển khai không thay đổi. Chỉnh sửa bản nháp tạo ra một phiên bản mới; nó không nên viết lại phiên bản đã được gán cho máy. - \ No newline at end of file +Đặt cho mỗi chính sách một tên duy nhất trên các chính sách theo quy ước, tùy chỉnh, gói và được quản lý bởi Cloud. \ No newline at end of file diff --git a/docs/vi/policies/failure-behavior.mdx b/docs/vi/policies/failure-behavior.mdx index 3a64aa42..5934972b 100644 --- a/docs/vi/policies/failure-behavior.mdx +++ b/docs/vi/policies/failure-behavior.mdx @@ -4,7 +4,7 @@ description: "Hiểu điều gì xảy ra khi đánh giá chính sách hoặc da icon: "shield-alert" --- -Failproof AI được thiết kế để một lỗi thực thi có thể nhìn thấy được thay vì im lặng cho phép công việc rủi ro. +Failproof AI được thiết kế để sự cố trong thực thi là có thể nhìn thấy được thay vì âm thầm cho phép công việc rủi ro. ## Chẩn đoán một khối failure-closed @@ -12,8 +12,8 @@ Failproof AI được thiết kế để một lỗi thực thi có thể nhìn 1. Đi tới **Admin → enforcement** và mở máy. 2. Kiểm tra lần check-in cuối cùng, deployment được gán và deployment được báo cáo. - 3. Đi tới **Observe → policy** và mở phiên của quyết định bị từ chối. - 4. Xác nhận xem lý do có báo cáo về khả năng tiếp cận daemon, chênh lệch phiên bản, hay chính sách đó không. + 3. Đi tới **Observe → policy** và mở phiên làm việc của quyết định bị từ chối. + 4. Xác nhận xem lý do có báo cáo về khả năng tiếp cận daemon, version skew hoặc chính sách đó không. @@ -27,41 +27,43 @@ Failproof AI được thiết kế để một lỗi thực thi có thể nhìn -Trên một máy được cấu hình để sử dụng `failproofaid`, daemon là công cụ đánh giá duy nhất. Nếu nó không thể truy cập được hoặc phiên bản giao thức của nó không khớp với CLI, đánh giá hook sẽ thất bại. Hành động bị từ chối với lý do hướng dẫn người vận hành kiểm tra hoặc cập nhật daemon. +Trên một máy được cấu hình để sử dụng `failproofaid`, daemon là bộ đánh giá duy nhất. Nếu nó không thể tiếp cận được hoặc phiên bản giao thức của nó không khớp với CLI, đánh giá hook sẽ thất bại ở chế độ đóng. Hành động bị từ chối với lý do hướng dẫn nhà điều hành kiểm tra hoặc cập nhật daemon. -Trước khi cấu hình daemon, hooks đánh giá chính sách trong quá trình. Sau khi ghi lại cấu hình daemon, Failproof AI không im lặng quay lại một công cụ đánh giá thứ hai khi daemon gặp sự cố. +Trước khi cấu hình daemon, hook đánh giá các chính sách trong quá trình. Khi bản ghi cấu hình daemon được lưu, Failproof AI không âm thầm quay trở lại bộ đánh giá thứ hai khi daemon gặp sự cố. -## Phản ứng với quyết định failure-closed +## Đáp ứng với quyết định failure-closed 1. Chạy `failproofai config --status`. -2. Nếu các phiên bản khác nhau, chạy lại `failproofai config` sau khi cập nhật gói. -3. Nếu daemon không thể truy cập được, kiểm tra trạng thái dịch vụ của nó và nhật ký cục bộ. -4. Tiếp tục công việc của agent chỉ sau khi một đường đánh giá chính sách đã biết có tình trạng lành mạnh. +2. Nếu phiên bản khác nhau, hãy chạy lại `failproofai config` sau khi cập nhật gói. +3. Nếu daemon không thể tiếp cận được, hãy kiểm tra trạng thái dịch vụ và nhật ký cục bộ. +4. Chỉ tiếp tục công việc agent sau khi một đường dẫn đánh giá chính sách đã biết là lành mạnh. - Không thử lại hành động bị chặn lặp đi lặp lại. Phản ứng failure-closed có nghĩa là hệ thống không thể xác lập rằng hành động là an toàn. + Không lặp đi lặp lại hành động bị khóa. Phản hồi failure-closed có nghĩa là hệ thống không thể xác định được rằng hành động đó là an toàn. ## Một pack sẽ không tải -Một máy được yêu cầu thực thi một pack và không thể chạy nó sẽ từ chối thay vì tiếp tục im lặng. Kích hoạt là một **recorded expectation**, không bao giờ là một cái trống: một máy không có pack nào được cài đặt là im lặng, trong khi một pack được khai báo và sẽ không giải quyết — hoặc đăng ký ít hơn những gì manifest khai báo — sẽ từ chối. +Một máy được yêu cầu thực thi một pack và không thể chạy nó, sẽ từ chối thay vì tiếp tục âm thầm. Kích hoạt là một **recorded expectation**, không bao giờ là một cái trống: một máy không có pack nào được cài đặt là im lặng, trong khi một pack được khai báo và sẽ không giải quyết được — hoặc đăng ký ít hơn những gì manifest khai báo — sẽ từ chối. -Từ chối là **narrow**, không giống như một daemon không thể truy cập được. Một daemon không thể truy cập được có nghĩa là không có đánh giá nào xảy ra, vì vậy không có gì có thể được biết là an toàn. Một pack sẽ không tải có một bộ các guard bị thiếu có thể liệt kê, bởi vì mọi chính sách được khai báo đều mang `match` của riêng nó — vì vậy nó chỉ từ chối các sự kiện và công cụ mà những chính sách đó bao phủ, và mọi thứ khác diễn ra bình thường. +Sự từ chối là **narrow**, không giống như một daemon không thể tiếp cận được. Một daemon không thể tiếp cận được có nghĩa là không xảy ra đánh giá nào cả, vì vậy không có gì có thể được biết là an toàn. Một pack sẽ không tải có một tập hợp các guard bị thiếu có thể liệt kê, vì mỗi chính sách được khai báo đều mang theo `match` của riêng nó — vì vậy nó chỉ từ chối các sự kiện và công cụ mà các chính sách đó bao phủ, và mọi thứ khác sẽ tiếp tục. -Nó không phát động cho: +Nó không kích hoạt cho: -- một pack `observe`, để đánh giá và loại bỏ theo cấu trúc -- các chính sách bạn không bao giờ lấy, hoặc rõ ràng tắt -- một pack mà trình tải không bao giờ nhận được, nơi "không có đăng ký" không thể được phân biệt với một lần bỏ qua cố ý -- một tạm dừng phiên hoạt động -- một hết thời gian tải, đó là tạm thời — một thời điểm đĩa chậm không được phép từ chối cho đến khi con người can thiệp +- một pack `observe`, được đánh giá và loại bỏ theo cấu trúc +- các chính sách bạn không bao giờ áp dụng hoặc rõ ràng tắt +- một pack mà trình tải không bao giờ nhận được, nơi "no registrations" không thể phân biệt được với một bỏ qua cố ý +- một tạm dừng phiên làm việc hoạt động +- một timeout tải, đó là geçici — một thời điểm đĩa chậm không phải từ chối cho đến khi con người can thiệp -`UserPromptSubmit` **instructs** thay vì từ chối, bất kể chính sách bị thiếu đã khai báo gì. Một từ chối toàn bộ sẽ kéo theo nó và khóa bạn ra khỏi agent có thể khắc phục sự cố. +`UserPromptSubmit` **hướng dẫn** thay vì từ chối, bất kể chính sách bị thiếu khai báo gì. Một sự từ chối toàn diện sẽ thực hiện nó cùng nhau và khóa bạn khỏi agent có thể sửa chữa vấn đề. -### Việc cần làm +### Phải làm gì ```bash -failproofai pack list +failproofai policies ``` -Nó liệt kê bất kỳ pack được cài đặt nào sẽ không tải, cho biết lý do và thoát với mã khác không. Sau đó hãy cài đặt lại nó (`failproofai pack add `) hoặc xóa nó (`failproofai pack remove `) — xóa nó loại bỏ kỳ vọng, và từ chối dừng lại cùng với nó. \ No newline at end of file +Danh sách này đánh dấu một pack được cài đặt có bản ghi cài đặt hoặc digest không còn kiểm tra được nữa, và nói rõ lý do. Nó không nhập pack, vì vậy một pack chỉ thất bại khi nó tải — đăng ký ít hơn những gì manifest khai báo — liệt kê như bình thường; sự từ chối dưới đây là cái đặt tên cho cái đó. Dù bằng cách nào, hãy cài đặt lại nó (`failproofai policies add `) hoặc loại bỏ nó (`failproofai policies remove `) — loại bỏ nó sẽ rút lại kỳ vọng, và sự từ chối sẽ dừng lại cùng với nó. + +Sự từ chối chính nó được gán cho `pack/failproofai-pack-unavailable`, vượt qua các chính sách đã tải, vì vậy một cuộc gọi công cụ bị khóa sẽ đặt tên cho pack bị thiếu thay vì bất kỳ guard nào còn sống mà tình cờ kích hoạt đầu tiên. \ No newline at end of file diff --git a/docs/vi/policies/local-configuration.mdx b/docs/vi/policies/local-configuration.mdx index d0aca140..cb8bfa0e 100644 --- a/docs/vi/policies/local-configuration.mdx +++ b/docs/vi/policies/local-configuration.mdx @@ -4,30 +4,25 @@ description: "Kiểm soát phạm vi chính sách, tham số, tệp tùy chỉnh icon: "file-cog" --- -Failproof AI tách rời lựa chọn chính sách từ cài đặt máy và daemon. Điều này giữ cho lựa chọn chính sách kho lưu trữ có thể được xem xét trong khi thông tin xác thực và trạng thái daemon ở bên ngoài kho lưu trữ. +Failproof AI tách biệt những gì một kho lưu trữ có thể commit — hook wiring, tham số chính sách, chính sách tùy chỉnh — khỏi trạng thái máy như thông tin xác thực, các pack đã cài đặt và daemon. -## Chọn phạm vi chính sách +## Chọn một phạm vi - - - Chạy `failproofai` mà không có đối số để mở bảng điều khiển chính sách cục bộ. Chọn phạm vi người dùng, dự án hoặc cục bộ trước khi bật một chính sách để thay đổi được ghi vào tệp cấu hình dự định. +Phạm vi quyết định vị trí hook được wiring và tệp cấu hình nào bạn ghi tham số và đường dẫn chính sách tùy chỉnh vào: - - **User** áp dụng trên các dự án trên máy này. - - **Project** thuộc về kho lưu trữ và có thể được commit. - - **Local** ghi đè một dự án cho một người dùng và nên giữ trong gitignore. +- **User** áp dụng trên các dự án trên máy này. +- **Project** thuộc về kho lưu trữ và có thể được commit. +- **Local** ghi đè một dự án cho một người dùng và nên được gitignored. - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # wire hooks for this repository +failproofai policies --install --cli claude --scope user # or for every project on this machine +failproofai policies +``` - Không phải mọi harness đều hỗ trợ phạm vi cục bộ. CLI từ chối một phạm vi mà harness đã chọn không thể biểu diễn. - - +Không phải mọi harness đều hỗ trợ phạm vi cục bộ; CLI từ chối một phạm vi mà harness được chọn không thể đại diện. + +Chính sách pack nào được bật **không** được phạm vi hóa. Công tắc được ghi lại với pack đã cài đặt, vì vậy `failproofai policies add ` bật một chính sách cho toàn bộ máy, bất kể `--scope` nói gì. | Phạm vi | Tệp cấu hình chính sách | | --- | --- | @@ -35,21 +30,20 @@ Failproof AI tách rời lựa chọn chính sách từ cài đặt máy và dae | Local | `/.failproofai/policies-config.local.json` | | User | `~/.failproofai/policies-config.json` | -Các chính sách được bật được hợp nhất dưới dạng một union. Tham số chính sách sử dụng phạm vi đầu tiên xác định tham số cho chính sách đó, theo thứ tự project → local → user. Đường dẫn chính sách tùy chỉnh rõ ràng sử dụng phạm vi đầu tiên xác định chúng. +Tham số chính sách sử dụng phạm vi đầu tiên xác định tham số cho chính sách đó, theo thứ tự project → local → user. Đường dẫn chính sách tùy chỉnh rõ ràng sử dụng phạm vi đầu tiên xác định chúng. ## Cấu hình tham số chính sách - Mở chính sách trong bảng điều khiển cục bộ, chỉnh sửa các tham số được hỗ trợ của nó và lưu trong phạm vi đã chọn. Chạy một hành động agent phù hợp và không phù hợp, sau đó kiểm tra quyết định trong **Observe → policy**. + Mở chính sách trong bảng điều khiển cục bộ, chỉnh sửa các tham số được hỗ trợ của nó và lưu trong phạm vi được chọn. Chạy một hành động tác nhân phù hợp và không phù hợp, sau đó kiểm tra quyết định trong **Observe → policy**. - Chỉnh sửa `policies-config.json` của phạm vi đã chọn, sau đó chạy `failproofai policies` để làm nổi bật tên chính sách hoặc khóa tham số không xác định. + Chỉnh sửa `policies-config.json` của phạm vi được chọn, sau đó chạy `failproofai policies`: nó cảnh báo về mục nhập `policyParams` đặt tên cho một chính sách mà không có pack được cài đặt nào mang theo. Nó không kiểm tra các khóa bên trong mục nhập, vì vậy hãy kiểm tra cách viết của chúng so với bảng bên dưới. ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,6 +58,30 @@ Các chính sách được bật được hợp nhất dưới dạng một unio +### Tham số mà các chính sách Failproof AI chấp nhận + +Mỗi chính sách xác thực loại tham số của riêng nó. + +| Chính sách | Tham số | Loại và mặc định | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; các mục nhập chứa `regex` và `label` | +| `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | +| `block-sudo` | `allowPatterns` | `string[]`, `[]` | +| `block-rm-rf` | `allowPaths` | `string[]`, `[]` | +| Công cụ chặn cơ sở hạ tầng | `allowPatterns` | `string[]`, `[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | +| `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | +| `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | +| `warn-large-file-write` | `thresholdKb` | `number`, `1024` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | + + + Một mẫu cho phép mở rộng những gì một tác nhân có thể làm. Kiểm tra mã hóa token chính xác và các biến thể lệnh trên harness đích trước khi triển khai trên toàn bộ bộ máy. + + ## Hiểu các tệp máy `~/.failproofai` chứa các tệp riêng biệt cho các ranh giới tin tưởng riêng biệt: @@ -72,13 +90,13 @@ Các chính sách được bật được hợp nhất dưới dạng một unio | --- | --- | | `config.json` | Cài đặt daemon, kiểm toán và telemetry không bí mật | | `credentials.json` | Thông tin xác thực đám mây; được lưu trữ với quyền chỉ dành cho chủ sở hữu | -| `policies-config.json` | Lựa chọn builtin phạm vi người dùng, tham số và đường dẫn tùy chỉnh rõ ràng | -| `policies/` | Chính sách quy ước người dùng và hiện vật chính sách được quản lý bởi Cloud | +| `policies-config.json` | Tham số phạm vi người dùng và đường dẫn chính sách tùy chỉnh rõ ràng | +| `policies/` | Chính sách quy ước người dùng, các pack đã cài đặt và chính sách của chúng được bật, cũng như các tạo phẩm chính sách được quản lý bởi Cloud | | `hook-activity/` | Nhật ký quyết định chính sách cục bộ | -| `state/` | Daemon spool, health, pause và trạng thái runtime | +| `state/` | Daemon spool, tình trạng sức khỏe, tạm dừng và trạng thái thời gian chạy | -Sử dụng `FAILPROOFAI_HOME` để di chuyển bố cục máy hoàn chỉnh cho một container hoặc bài kiểm tra bị cô lập. Không di chuyển các thư mục trạng thái riêng lẻ độc lập. +Sử dụng `FAILPROOFAI_HOME` để định vị lại bố cục máy hoàn chỉnh cho container hoặc bài kiểm tra cô lập. Không định vị lại các thư mục trạng thái riêng lẻ độc lập với nhau. - Không bao giờ commit `credentials.json`. Commit cấu hình chính sách dự án và chính sách quy ước dự án chỉ sau khi xem xét chúng như mã thực thi. + Không bao giờ commit `credentials.json`. Chỉ commit cấu hình chính sách dự án và chính sách quy ước dự án sau khi xem xét chúng như mã thực thi. \ No newline at end of file diff --git a/docs/vi/policies/overview.mdx b/docs/vi/policies/overview.mdx index a8224dc8..66775cff 100644 --- a/docs/vi/policies/overview.mdx +++ b/docs/vi/policies/overview.mdx @@ -4,60 +4,51 @@ description: "Quan sát, hướng dẫn hoặc chặn các hành động của a icon: "shield-check" --- -Một chính sách đánh giá một sự kiện hook của agent và trả về một trong ba quyết định: +Một chính sách đánh giá sự kiện hook của agent và trả về một trong ba quyết định: - `allow` cho phép hành động tiếp tục. -- `instruct` cung cấp hướng dẫn sửa chữa cho agent. -- `deny` chặn hành động với một lý do. +- `instruct` cung cấp hướng dẫn sửa lỗi cho agent. +- `deny` chặn hành động kèm theo lý do. -## Sử dụng ba bề mặt chính sách +## Chính sách nằm ở đâu - - - 1. Chuyển đến **Observe → policy** để lọc và kiểm tra các quyết định chính sách từ các phiên. - 2. Chuyển đến **Admin → policy editor** để soạn, xác thực, xuất bản, vô hiệu hóa hoặc kiểm tra các phiên bản bất biến. - 3. Chuyển đến **Admin → enforcement** để gán các phiên bản và hiệu ứng cho các máy. +| Trên bảng điều khiển | Những gì bạn làm ở đó | +| --- | --- | +| **Observe → policy** | Xem xét các quyết định từ các phiên làm việc thực tế: chính sách nào khớp, trên máy nào và tại sao | +| **Admin → policy editor** | Viết một chính sách, kiểm tra ngược lại lưu lượng trước đó, xuất bản một phiên bản bất biến và so sánh các phiên bản trong **library** | +| **Admin → enforcement** | Triển khai các phiên bản trên các máy, ở chế độ quan sát hoặc thực thi | - Sử dụng trang Policy để hiểu những gì đã khớp trước khi soạn thảo hoặc thay đổi thực thi. +Trình soạn thảo chính sách là nơi một lỗi trở thành một quy tắc. Mô tả chế độ lỗi hoặc dán mã nguồn chính sách trong **compose**, kiểm tra ngược bản nháp với lưu lượng bạn đã có và xuất bản một phiên bản: - ![Trang Policy hiển thị tổng số quyết định và ánh xạ chính sách do cục bộ và Cloud quản lý.](/images/dashboard/policy-observe.png) +![Chế độ soạn thảo của trình soạn thảo chính sách với danh tính chính sách, soạn thảo hỗ trợ bởi AI, xác thực mã nguồn và các điều khiển xuất bản.](/images/dashboard/policy-editor.png) - Trình soạn thảo là nơi bạn biến một điều kiện lỗi thành mã nguồn, xác thực nó và xuất bản một phiên bản bất biến. +Trên một máy, `failproofai policies` liệt kê tất cả những gì được thực thi ở đó. `fp policies` và `fp fleet` bao quát trình soạn thảo và thực thi từ terminal — xem [Tham chiếu Cloud CLI](/vi/reference/cloud-cli). - ![Trình soạn thảo Policy được sử dụng để soạn và xuất bản một phiên bản chính sách bất biến.](/images/dashboard/policy-editor.png) +## Lấy một chính sách - Enforcement sau đó gán phiên bản đã xuất bản đó và hiệu ứng quan sát hoặc thực thi của nó cho các máy. - - ![Fleet thực thi hiển thị phạm vi máy và các phiên bản chính sách được gán.](/images/dashboard/enforcement-fleet.png) - - Xác minh các quyết định trở lại trang Policy sau khi triển khai để các chế độ xem soạn thảo và fleet được liên kết với hoạt động agent thực tế. - - - Sử dụng `failproofai` để cài đặt và xác thực chính sách cục bộ: - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - Sử dụng `fp` để tìm các phiên Cloud và sự kiện chứa các quyết định chính sách. Soạn thảo Cloud và triển khai fleet vẫn còn là quy trình công việc trên dashboard. - - - -Chính sách có ba bề mặt riêng biệt trong Failproof AI: - -1. **Phân tích các quyết định** trong các phiên, dashboard và kiểm toán. -2. **Soạn các phiên bản** với các quy tắc tích hợp, mã hoặc trình soạn thảo chính sách. -3. **Triển khai và thực thi** các phiên bản trên các máy được chọn. - -Bắt đầu từ một chế độ lỗi được xác nhận. Xác định sự kiện nhỏ nhất và sự khớp công cụ xác định nó, kiểm tra các ví dụ hợp pháp và không an toàn, sau đó quan sát trước khi thực thi. +Có hai cách để lấy một chính sách. - - Kích hoạt một quy tắc đã được xem xét cho các rủi ro bí mật, shell, Git, cloud và quy trình công việc phổ biến. + + Để Failproof AI soạn thảo một chính sách từ kết quả kiểm toàn, hoặc viết mã nguồn của bạn, sau đó xem xét và xuất bản nó trong trình soạn thảo. - - Biểu thị một quyết định dành riêng cho quy trình công việc bằng JavaScript hoặc TypeScript. + + Cắm vào một gói chính sách Failproof AI cho trường hợp sử dụng của bạn, hoặc một gói cộng đồng từ kho chính sách, chỉ với một lệnh. - \ No newline at end of file + + +## Sau đó triển khai nó + + + + Kiểm tra ngược bản nháp với lưu lượng bạn đã có, và chạy nó với một hành động nó phải chặn và một hành động nó phải cho phép — tất cả trước khi bạn xuất bản. Xem [Kiểm tra một chính sách](/vi/policies/test). + + + Đặt phiên bản trên các máy ở chế độ **observe**, đọc các quyết định của nó, sau đó thực thi. Xem [Triển khai một chính sách](/vi/policies/deploy). + + + Mỗi lần xuất bản là một phiên bản mới, bất biến, do đó một bản triển khai mà chặn công việc hợp lệ được hoàn nguyên bằng cách triển khai lại phiên bản tốt cuối cùng. Xem [Phiên bản và hoàn nguyên](/vi/policies/rollback). + + + +Để chia sẻ chính sách của bạn với các nhóm khác, [xuất bản chúng dưới dạng một gói](/vi/policies/publish-a-pack). Để biết điều gì xảy ra khi một chính sách không thể được đánh giá hoàn toàn, xem [Hành vi khi thất bại](/vi/policies/failure-behavior). \ No newline at end of file diff --git a/docs/vi/policies/packs.mdx b/docs/vi/policies/packs.mdx index 6839a34a..3e5002e4 100644 --- a/docs/vi/policies/packs.mdx +++ b/docs/vi/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "Policy packs" -description: "Cài đặt một bộ policies được công bố dưới dạng GitHub release, và quản lý những gì nó buộc thực thi." +title: "Sử dụng một gói chính sách" +description: "Cắm vào một gói chính sách Failproof AI cho trường hợp sử dụng của bạn, hoặc một gói của cộng đồng từ trung tâm chính sách, và chọn những gì nó áp dụng." icon: "package" --- -A pack is a set of policies published as a GitHub release. One command installs it, the release's own checksums are verified before anything runs, and the digest is recorded so the pack cannot change under your machine afterwards. +Một gói là một tập hợp các chính sách được xuất bản dưới dạng bản phát hành GitHub. Một lệnh duy nhất cài đặt nó: các tổng kiểm tra của bản phát hành được xác minh trước khi bất cứ thứ gì chạy, và nó được ghi lại sao cho gói không thể thay đổi trên máy của bạn sau này. -## Cài đặt Failproof AI policies +Duyệt qua mọi gói và mọi chính sách trong mỗi gói trên [trung tâm chính sách](https://befailproof.ai/policy-hub/). Có hai loại: + +- **Gói chính sách Failproof AI** — các gói sẵn sàng cho các trường hợp sử dụng được xác định trước: cắm vào một gói và nó hoạt động. [Gói chính sách coding agent](https://befailproof.ai/policy-hub/failproofai/policies/) hiện có sẵn, và các gói cho nhiều trường hợp sử dụng khác sắp ra mắt. +- **Gói chính sách của cộng đồng** — các chính sách mà các nhà phát triển đã viết cho trường hợp sử dụng của riêng họ và xuất bản cho bất kỳ ai sử dụng. + +## Gói chính sách Failproof AI + +### Gói chính sách coding agent ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -That installs the set we publish, from the copy inside the package — so it needs no network and cannot fail behind a proxy. Take part of it: +Gói này chứa 38 chính sách và bật 10 chính sách mà tệp kê khai của nó đánh dấu là an toàn để bật không giám sát; phần còn lại được liệt kê để bạn chọn. Một số chính sách được sử dụng nhiều nhất, và việc `policies add` đơn giản có bật chúng không: + +| Chính sách | Chức năng | Bật theo mặc định | +| --- | --- | --- | +| `block-push-master` | Chặn push trực tiếp đến các nhánh được bảo vệ | Có | +| `block-env-files` | Chặn đọc và ghi các tệp `.env` | Có | +| `protect-env-vars` | Chặn các lệnh xả các biến môi trường | Có | +| `block-sudo` | Chặn `sudo` trừ khi một mẫu cho phép phù hợp | Có | +| `block-curl-pipe-sh` | Chặn các tập lệnh được tải xuống được dẫn thẳng vào shell | Có | +| `sanitize-*` (năm chính sách) | Báo cáo các khóa API, mã thông báo người mang, JWT, khóa riêng tư và chuỗi kết nối được tìm thấy trong đầu ra công cụ | Có | +| `block-rm-rf` | Chặn xóa đệ quy thảm họa | Không | +| `block-force-push` | Chặn force-push | Không | +| `block-secrets-write` | Chặn ghi vào các tệp thông tin xác thực và khóa bí mật | Không | +| `warn-destructive-sql` | Cảnh báo về `DROP`, `TRUNCATE` và `DELETE` không có `WHERE` | Không | + +Bật bất kỳ chính sách nào đang tắt theo tên — `failproofai policies add block-rm-rf` — hoặc lấy toàn bộ gói với `--all`. Xem mọi chính sách trong nó, được nhóm theo danh mục: ```bash -failproofai pack add core --policy block-rm-rf # one, or a comma-separated few -failproofai pack add core --category dangerous-commands # a whole category -failproofai pack add core --all # everything in it +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` names every category the pack offers. +## Gói chính sách của cộng đồng -## Xem pack chứa gì trước khi cài đặt +Các nhà phát triển xuất bản các gói cho những trường hợp sử dụng mà họ gặp, và [trung tâm chính sách](https://befailproof.ai/policy-hub/) liệt kê chúng. Một gói chính sách của cộng đồng được xuất bản bởi tác giả của nó, không được kiểm toán bởi Failproof AI, vì vậy hãy đọc những gì nó chứa trước khi cài đặt: ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -Lists every policy the pack carries, grouped by category, marking which ones its author switches on by default and which are opt-in. It reads **only the manifest** — the entry artifact is never downloaded and never imported, so looking at a stranger's pack cannot run a stranger's code. The manifest is still checked against the release's own `SHA256SUMS`, so what you are reading is what would install. - -`failproofai pack list` with no source lists the packs already installed here. +Cái này liệt kê mọi chính sách nó chứa, được nhóm theo danh mục, và đánh dấu những cái mà tác giả của nó bật theo mặc định. Nó chỉ đọc **tệp kê khai** — artifact entry không bao giờ được tải xuống hoặc nhập, vì vậy xem xét gói của người lạ không thể chạy mã của người lạ. Tệp kê khai vẫn được kiểm tra so với `SHA256SUMS` của bản phát hành, vì vậy những gì bạn đọc chính là những gì sẽ được cài đặt. -## Cài đặt pack của người khác +Sau đó cài đặt nó: ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -Any of these work — paste whichever you have: +Bất kỳ điều nào trong số này đều hoạt động — dán bất kỳ thứ gì bạn có: | Nguồn | Kết quả | | --- | --- | -| `acme/support-agent` | Newest release, **pinned** to the exact tag it resolved | -| `acme/support-agent@v2.1.0` | That release | -| `github:acme/support-agent@v2.1.0` | The same, written explicitly | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | The same, copied from a browser | +| `acme/support-agent` | Bản phát hành mới nhất, **được ghim** vào thẻ chính xác mà nó phân giải | +| `acme/support-agent@v2.1.0` | Bản phát hành đó | +| `github:acme/support-agent@v2.1.0` | Cái tương tự, được viết rõ ràng | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Cái tương tự, được sao chép từ trình duyệt | -Naming no tag installs the newest release **and pins it**, then tells you which tag it chose. What gets recorded always names exactly one release, so a reinstall cannot drift. +Không đặt tên thẻ sẽ cài đặt bản phát hành mới nhất **và ghim nó**, sau đó cho bạn biết thẻ nào mà nó đã chọn. Những gì được ghi lại luôn đặt tên chính xác một bản phát hành, vì vậy một lần cài đặt lại không thể trôi dạt. -## Lấy một phần của pack +## Lấy một phần của gói -By default you get the pack's **own** defaults — the policies its author marked safe to switch on unattended — not everything it contains. +Theo mặc định, bạn nhận được **các giá trị mặc định riêng của** gói — các chính sách mà tác giả của nó đánh dấu là an toàn để bật không giám sát — không phải mọi thứ nó chứa. ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # một, hoặc một vài được phân tách bằng dấu phẩy +failproofai policies add FailproofAI/policies --category dangerous-commands # toàn bộ một danh mục +failproofai policies add FailproofAI/policies --all # mọi thứ trong nó ``` -`--category` and `--policy` combine as a union (`--only` is accepted as a synonym for `--policy`). Re-adding at a newer version keeps whatever you chose rather than switching the rest back on. +`--category` và `--policy` kết hợp như một liên hợp (`--only` được chấp nhận là từ đồng nghĩa cho `--policy`). Khi gói đã được cài đặt, các cờ sẽ thêm vào những gì bạn có, và thêm lại nó mà không có cờ và không có terminal — để nâng cấp, chẳng hạn — giữ nguyên lựa chọn của bạn như cũ. Ở terminal mà không có cờ, `add` mở trình chọn thay thế, được đánh dấu trước với các giá trị mặc định của tác giả, và những gì bạn đánh dấu sẽ thay thế lựa chọn của bạn. -## Quản lý những gì được bật +## Quản lý những gì đang bật ```bash -failproofai policies # every source in one list, packs included -failproofai pack list # packs only, grouped by category -failproofai policies --uninstall block-refunds # turn one pack policy off -failproofai policies --install block-refunds # and back on -failproofai pack remove acme/support-agent +failproofai policies # mọi nguồn trong một danh sách, các gói được bao gồm +failproofai policies add block-rm-rf # bật một chính sách +failproofai policies --uninstall block-refunds # tắt một chính sách gói +failproofai policies --install block-refunds # và bật lại +failproofai policies remove acme/support-agent # dỡ cài đặt gói ``` -A bare name means the **builtin** when one exists by that name. Name a pack's copy explicitly when you need to: +Bật hoặc tắt chính sách gói áp dụng cho toàn bộ máy: công tắc được ghi lại với gói đã cài đặt, không phải trong cấu hình của dự án, bất kể `--scope` nói gì. + +Một tên không có dấu gạch chéo là một chính sách; bất cứ thứ gì có một tên là một nguồn gói. Một tên trần phân giải thành gói đã cài đặt khai báo nó. Khi hai gói đã cài đặt khai báo cùng một tên, hãy đặt tên cái bạn muốn: ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -If a pack ships a policy whose name is also an **enabled builtin**, the builtin runs and the pack's copy is skipped — the same guard would otherwise be evaluated twice. Turn the builtin off to use the pack's copy instead. - - -## Failproof AI policies có nguồn gốc từ đâu - -`core` reads the copy vendored in the npm package. The same set is published as a GitHub release, which is what you install if you want a specific version: - -```bash -failproofai pack add core # from this package, no network -failproofai pack add FailproofAI/policies # the same set, from its GitHub release -``` +Phạm vi, tham số và các tệp mà các lệnh này viết được đề cập trong [cấu hình cục bộ](/vi/policies/local-configuration). -## Tính toàn vẹn mang lại cái gì và không mang lại cái gì +## Tính toàn vẹn mua lại gì và không mua lại gì -`SHA256SUMS` ships in the same release as the artifact, so it is **not** a signature and proves nothing about who published it. What it does prove is that the bytes are the ones that release published — and because the digest is recorded when you add the pack and re-verified before every import, a pack cannot change under your machine afterwards. A repository that retags or replaces an asset stops loading instead of quietly running something else. +`SHA256SUMS` được gửi trong cùng một bản phát hành như artifact, vì vậy nó **không** phải là chữ ký và không chứng minh bất cứ điều gì về ai xuất bản nó. Những gì nó chứng minh là các byte là những byte mà bản phát hành đó xuất bản — và bởi vì nó được ghi lại khi bạn thêm gói và được xác minh lại trước mỗi lần nhập, một gói không thể thay đổi trên máy của bạn sau này. Một kho lưu trữ mà retag hoặc thay thế một asset sẽ ngừng tải thay vì chạy âm thầm cái gì đó khác. -At install time the pack is also **imported once** and checked against its own manifest. A pack whose artifact does not parse, or that registers something other than what it declares, is refused before anything is activated — rather than installing cleanly and failing on your next tool call. +Tại thời điểm cài đặt, gói cũng **được nhập một lần** và được kiểm tra so với tệp kê khai của riêng nó. Một gói mà artifact của nó không phân tích cú pháp, hoặc mà đăng ký cái gì đó khác hơn những gì nó khai báo, bị từ chối trước khi bất cứ điều gì được kích hoạt — thay vì cài đặt sạch sẽ và thất bại vào lệnh công cụ tiếp theo của bạn. -## Khi một pack không tải được +## Khi một gói sẽ không tải -A pack this machine was told to enforce and cannot run **denies** the events its missing policies covered, rather than allowing them silently. See [Failure behavior](/vi/policies/failure-behavior). `failproofai pack list` names any pack in that state and exits non-zero. +Một gói mà máy này được bảo ghi để áp dụng và không thể chạy **từ chối** các sự kiện mà các chính sách còn thiếu của nó bao phủ, thay vì cho phép chúng âm thầm — như `pack/failproofai-pack-unavailable`, vốn vượt trội so với các chính sách đã tải để việc từ chối được quy cho gói bị mất thay vì cho bất kỳ vệ sĩ nào xảy ra bắn đầu tiên. Ngoại lệ là `UserPromptSubmit`, mà hướng dẫn thay thế: từ chối ở đó sẽ khóa bạn khỏi agent bạn cần để sửa nó. Xem [Hành vi thất bại](/vi/policies/failure-behavior). -## Ngoại tuyến và mirror +## Ngoại tuyến và gương -| Biến | Hiệu lực | +| Biến | Hiệu ứng | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Refuses to fetch; packs already installed keep enforcing | -| `FAILPROOFAI_PACK_BASE_URL` | Points pack fetching at a mirror instead of `github.com` | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Từ chối tìm nạp; các gói đã cài đặt tiếp tục áp dụng | +| `FAILPROOFAI_PACK_BASE_URL` | Chỉ các gói tìm nạp ở một gương thay vì `github.com` | -Publishing your own pack: see [Publish a pack](/vi/policies/publish-a-pack). \ No newline at end of file +Để chia sẻ các chính sách của riêng bạn theo cách này, hãy xem [Xuất bản một gói chính sách](/vi/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/vi/policies/publish-a-pack.mdx b/docs/vi/policies/publish-a-pack.mdx index afe59f55..8f6cc53b 100644 --- a/docs/vi/policies/publish-a-pack.mdx +++ b/docs/vi/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "Công bố một pack" -description: "Phân phối các policies của riêng bạn dưới dạng GitHub release mà bất kỳ ai cũng có thể cài đặt." +title: "Xuất bản một gói policies" +description: "Phát hành policies của riêng bạn như một GitHub release mà bất cứ ai cũng có thể cài đặt." icon: "upload" --- -Một pack bao gồm ba tệp được đính kèm vào GitHub release. `failproofai pack build` ghi tất cả ba tệp từ tệp policy mà bạn đã có. +Một gói là ba tệp được đính kèm vào một GitHub release. `failproofai publish` viết cả ba từ các policy files phía trước, tạo release và tải chúng lên. ## 1. Viết các policies -Một tệp, sử dụng API giống như bất kỳ custom policy nào. Hai trường bổ sung rất quan trọng đối với pack: +Bắt đầu từ thứ gì đó đã hoạt động thay vì một template có chỗ trống: + +```bash +failproofai publish --init +``` + +Lệnh này hỏi gói được gọi là gì, viết `.mjs` và dừng lại — không có mạng, không có git, không có gì được xuất bản. Tệp được viết là một policy đã chặn `git push --force`. Nó từ chối ghi đè lên một tệp đã tồn tại. + +Policies sử dụng cùng API với bất kỳ custom policy nào. Hai trường bổ sung quan trọng đối với một gói: ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -`defaultEnabled` mặc định là **false** khi bạn bỏ qua nó. Một lệnh `failproofai pack add` đơn giản chỉ bật những gì bạn đã đánh dấu — cài đặt tất cả các policies của người lạ mà không giám sát không phải là quyết định mà người cài đặt nên đưa ra cho người dùng của họ. +`defaultEnabled` mặc định là **false** khi bạn bỏ qua nó. Một `failproofai policies add` đơn giản chỉ bật những gì bạn đánh dấu — cài đặt mọi policy của người lạ mà không được chú ý không phải là một quyết định mà trình cài đặt nên đưa ra cho người dùng của nó. + +Viết bao nhiêu tệp tùy thích; một tệp trên mỗi category sẽ dễ đọc. Mọi tệp trong thư mục đăng ký policies được gộp lại thành một artifact duy nhất mà một gói phải có. -Entry phải là **một tệp tự chứa đầy đủ**. Chỉ entry được pinned bởi digest, vì vậy một pack nhập tệp cục bộ không thể thành thật tuyên bố rằng digest bao phủ những gì sẽ chạy. Hãy bundle trước (`esbuild`, `bun build`, `rollup`) và xây dựng pack từ bundle — `pack build` từ chối local import thay vì gửi một lời hứa mà nó không thể giữ. + Bundling cần **bun**. Nếu không có nó, hãy giữ một tệp độc lập duy nhất. Dù bằng cách nào, entry được xuất bản phải không import các tệp cục bộ tại thời điểm cài đặt: chỉ entry được pin digest, vì vậy một gói tiếp cận với các tệp bên cạnh không thể thành thật khẳng định rằng digest bao gồm những gì chạy — và `publish` từ chối nó thay vì gửi một lời hứa mà nó không thể giữ được. -## 2. Xây dựng các asset release +## 2. Hãy thử ở đây trước + +Trước khi bất cứ ai khác có thể thấy nó, thực thi tệp trên máy này: ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +Bất kỳ đường dẫn, bất kỳ tên tệp nào. Yêu cầu agent của bạn làm việc bạn đã chặn và xem nó bị từ chối. Không có gì được xuất bản và không ai khác bị ảnh hưởng. [Test a policy](/vi/policies/test) bao gồm phần còn lại: trường hợp hợp pháp mà nó phải cho phép, và các đầu vào phá vỡ nó. + +## 3. Xuất bản nó + +```bash +failproofai publish ``` -Nó ghi ba tệp và xác thực mọi policy với **các quy tắc riêng của loader** trước — vì vậy một pack không thể cài đặt sẽ thất bại ở đây, nơi bạn có thể sửa nó: +Nó tìm ra nơi xuất bản, những gì cần gộp và phiên bản nào gọi nó, và chỉ hỏi khi không có gì trong repository cho nó biết. Theo thứ tự, dừng lại trước khi tạo release nếu có bất kỳ vấn đề nào: + +1. Tìm các policy files ở đây theo **nội dung** — những cái import `failproofai` và gọi `customPolicies.add` — thay vì theo tên tệp, vì vậy nó tìm thấy `guards.mjs` và bỏ qua một `policies.mjs` không liên quan. Nó không đi vào các thư mục con, vì vậy một test fixture không bao giờ bị quét lên vô tình. +2. Đọc repo từ `git remote get-url origin`, trong **thư mục của tệp** thay vì của bạn, và quyết định phiên bản. +3. Tìm thông tin xác thực của bạn: `GITHUB_TOKEN`, `GH_TOKEN` hoặc `gh auth login`. Nó cần release-write và không cần gì khác, và không bao giờ được in ra. +4. Tạo repository nếu nó không tồn tại. Điều này xảy ra trước bản dựng, vì vậy một gói bị từ chối ở bước tiếp theo có thể để lại một repository mới mà không có release nào trong đó. +5. Xây dựng ba assets, xác thực chúng bằng **quy tắc của chính loader** — mã giống nhau quyết định những gì có thể cài đặt trên máy của người lạ — vì vậy một gói không bao giờ có thể cài đặt sẽ thất bại ở đây, nơi bạn vẫn có thể sửa nó. +6. Tạo hoặc sử dụng lại release và tải lên, thay thế assets có cùng tên. -| Tệp | Định nghĩa | +| Tệp | Nó là gì | | --- | --- | -| `failproofai-pack.json` | Manifest: id, version, effect, và một entry cho mỗi policy | -| `failproofai-pack.mjs` | Entry của bạn, nguyên vẹn | -| `SHA256SUMS` | ` ` cho hai tệp còn lại | +| `failproofai-pack.json` | Manifest: id, version, effect và một entry trên mỗi policy | +| `failproofai-pack.mjs` | Entry được gộp của bạn | +| `SHA256SUMS` | ` ` cho hai cái còn lại | -Bị từ chối tại thời điểm build: một id không phải là `publisher/name`, tên policy chứa `/`, policy khai báo `alwaysOn`, thiếu `description`, `category` hoặc `match`, một entry không đăng ký bất cứ thứ gì, và một entry nhập tệp cục bộ. +Tên assets được cố định — chúng là những gì CLI của người dùng xây dựng URL từ đó, không có lệnh gọi API và không có discovery. -## 3. Đính kèm chúng vào một release +Bị từ chối tại thời điểm xây dựng: một id không phải `publisher/name`, một tên policy chứa `/`, một policy khai báo `alwaysOn`, thiếu `description`, `category` hoặc `match`, một entry không đăng ký gì cả, và một entry import các tệp cục bộ. -Tag release với cùng version mà bạn đã build, và đính kèm cả ba tệp dưới dạng release assets: +Ghi đè bất kỳ quyết định nào mà nó đã đưa ra: ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -Bây giờ bất kỳ ai cũng có thể cài đặt nó: +`--id` đặt pack id khi nó nên khác với repo, `--tag` đặt tag của release, `--notes` thay thế các ghi chú release được tạo — đây là nơi `policies show --releases` đọc số lượng và commit của mỗi release từ — `--out` chọn nơi assets được viết (mặc định `dist-pack`), và `--dry-run` xây dựng chúng mà không xuất bản và không cần thông tin xác thực. -```bash -failproofai pack add acme/support-agent -``` +Bây giờ bất cứ ai cũng có thể cài đặt nó bằng `failproofai policies add acme/support-agent`. Xem [policy packs](/vi/policies/packs) để pin một phiên bản và chỉ lấy một phần của nó. + +### Liệt kê nó trên policy hub -Tên assets là cố định — chúng là những gì CLI của người tiêu dùng sử dụng để xây dựng các URL của nó, không có cuộc gọi API và không có discovery. +Thêm topic `failproofai-policies` vào repository trên GitHub. Không có biểu mẫu gửi và không có hàng chờ phê duyệt: [policy hub](https://befailproof.ai/policy-hub/) crawler sẽ nhặt repository lên trong lần chạy tiếp theo. Topic chỉ đưa nó lên để xem xét — những gì liệt kê nó là một release có manifest được xác minh dựa trên `SHA256SUMS` của nó và phân tích cú pháp theo các quy tắc giống nhau mà CLI sử dụng, đó chính xác là những gì `failproofai publish` tạo ra. -## Phân phối một phiên bản mới +## Cách phiên bản được quyết định -Xây dựng với `--version` mới, tag một release mới, đính kèm ba assets lần nữa. Người tiêu dùng chạy lệnh `pack add` tương tự và giữ bất kỳ tập hợp con nào họ đã chọn; một policy mà họ đã tắt sẽ vẫn tắt trong quá trình nâng cấp. +Phiên bản là **commit bạn đang xuất bản từ** — sha ngắn của nó, mười hai ký tự: `a1b2c3d4e5f6`. Không có gì để chọn và không có gì để tăng, và phiên bản đặt tên chính xác nơi bytes đến từ, vì vậy xuất bản cùng một nguồn hai lần sẽ cho cùng một phiên bản. -Thay đổi **name** của một policy là một breaking change: một máy tính đã tắt nó sẽ tắt một tên không còn tồn tại nữa, và tên mới tới với bất kỳ `defaultEnabled` nào. +Nó được đọc từ tree phía trước bạn, không bao giờ từ các release của repository, vì vậy một bản clone mới và một máy cách ly không khí sẽ tính toán cùng một câu trả lời mà không cần hỏi GitHub điều gì đã xảy ra trước đó. + +Vì phiên bản đặt tên một commit, commit đó phải tồn tại. Tại một terminal, `publish` tạo nó cho bạn: nó khởi tạo một repository khi không có, và commit các policy files đã thay đổi trước khi xây dựng. Nó **từ chối** thay vào đó — đặt tên `--version` là cách ra khỏi — khi nó chạy mà không có terminal (một commit được tạo trên CI runner sẽ không tồn tại ở bất kỳ nơi nào khác), khi các tệp khác ngoài các policies không được commit, hoặc trong một checkout không có commits nào. Một tag trên `HEAD` thắng so với sha — một ai đó đã tag `v1.2.0` đã nói release này là gì. + +Một sha không mang bất kỳ thứ tự nào của chính nó, vì vậy hãy sử dụng `failproofai policies show / --releases` để xem release nào đến trước — newest ở trên cùng. + +## Gửi một phiên bản mới + +Commit thay đổi và chạy `failproofai publish` lại — commit mới là phiên bản mới. Người dùng chạy cùng một `failproofai policies add`. Nếu không có terminal, hoặc có một lá cờ chọn lọc, họ giữ lại tập con mà họ đã chọn và một policy mà họ tắt đi sẽ vẫn tắt; tại một terminal mà không có lá cờ, bộ chọn mở với các lựa chọn mặc định của bạn được đánh dấu trước và câu trả lời của họ thay thế lựa chọn của họ. + +Thay đổi **tên** của một policy là một breaking change: một máy mà đã tắt nó sẽ tắt một tên không còn tồn tại, và tên mới đến với bất kỳ `defaultEnabled` nào nó nói. ## Những gì người dùng của bạn đang tin tưởng -`SHA256SUMS` nằm trong cùng release với artifact, vì vậy nó chứng minh rằng các byte là những byte bạn đã công bố — không phải bạn là ai. Bất kỳ ai có thể ghi vào repository đều có thể ghi cả hai tệp. Sự bảo vệ của người dùng bạn là digest được pinned khi họ cài đặt, vì vậy những gì bạn gửi không thể thay đổi dưới họ sau đó. +`SHA256SUMS` sống trong cùng release với artifact, vì vậy nó chứng minh các bytes là những cái bạn xuất bản — không phải bạn là ai. Bất cứ ai có thể ghi vào repository có thể ghi cả hai tệp. Bảo vệ của người dùng của bạn là digest được pin khi họ cài đặt, vì vậy những gì bạn gửi không thể thay đổi dưới họ sau này. + +Xuất bản từ một repository mà truy cập ghi bạn kiểm soát, và coi một pack release như xuất bản một package. -Công bố từ một repository mà bạn kiểm soát quyền ghi, và coi một pack release giống như công bố một package. +Repository cũng phải **public**. Installs là HTTPS ẩn danh mà không có thông tin xác thực để cung cấp, vì vậy một repo private hiện có bị từ chối trước khi bất kỳ thứ gì được xây dựng hoặc tải lên, và một `publish` tạo được công khai vì cùng lý do. `--allow-private` ghi đè điều đó cho ai đó trao ba assets theo cách khác, và nói rõ ràng rằng không có `policies add` nào có thể tiếp cận chúng. Chỉ release quan trọng: installs đọc `releases/download//` và không bao giờ chạm đến git tree của bạn. ## Quan sát trước khi bạn thực thi -Một manifest có thể khai báo `"effect": "observe"`. Những policies đó chạy và verdicts của chúng được **ghi lại và loại bỏ** — không có gì bị chặn. Đó là cách để đo lường một quy tắc mới so với lưu lượng thực tế trước khi nó có thể gián đoạn công việc của bất kỳ ai. +Một manifest có thể khai báo `"effect": "observe"` — `failproofai publish --effect observe` là những gì đặt nó. Những policies đó chạy và các phán quyết của chúng **được ghi lại và loại bỏ** — không có gì bị chặn. Đó là cách đo một quy tắc mới dựa trên lưu lượng thực tế trước khi nó có thể làm gián đoạn công việc của bất cứ ai. ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/vi/policies/rollback.mdx b/docs/vi/policies/rollback.mdx index 21e1490d..cdddc185 100644 --- a/docs/vi/policies/rollback.mdx +++ b/docs/vi/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "Rollback" -description: "Khôi phục một deployment policy được biết là hoạt động tốt khi quá trình triển khai gây gián đoạn công việc hợp lệ của agent." +title: "Phiên bản và khôi phục" +description: "Mỗi lần công bố là một phiên bản bất biến, vì vậy một triển khai gây gián đoạn công việc hợp lệ của agent được khôi phục bằng cách triển khai lại phiên bản cuối cùng tốt." icon: "rotate-ccw" --- -Rollback thay đổi phiên bản được triển khai hoặc xóa một gán policy; nó không xóa lịch sử quyết định giải thích sự cố. +Một phiên bản chính sách đã công bố không bao giờ thay đổi. Chỉnh sửa chính sách và công bố lại sẽ tạo một phiên bản mới; nó không bao giờ viết lại phiên bản đã có trên các máy. Đó là điều làm cho khôi phục an toàn: phiên bản tốt cuối cùng vẫn còn đó, từng byte, và khôi phục không xóa lịch sử quyết định giải thích điều gì đã xảy ra. -## Rollback một máy +## Tìm một phiên bản - 1. Đi tới **Admin → enforcement**, mở rộng máy bị ảnh hưởng và xác định bộ policy được biết là hoạt động tốt lần cuối cùng. - 2. Chọn **edit**, khôi phục những phiên bản và hiệu ứng đó, rồi áp dụng deployment mới. - 3. Chờ cho máy check-in, sau đó xác minh deployment được báo cáo. - 4. Mở **Observe → policy** và các phiên làm việc bị ảnh hưởng để xác nhận công việc hợp lệ không còn bị chặn. + Đi tới **Admin → policy editor** và mở **library** để so sánh các phiên bản của chính sách hoặc vô hiệu hóa một trong số chúng. + + + ```bash + fp policies list # mọi phiên bản chính sách + fp policies show # một phiên bản, với mã nguồn của nó + ``` + + +## Khôi phục một máy + + + + 1. Đi tới **Admin → enforcement**, mở rộng máy bị ảnh hưởng và xác định bộ chính sách tốt cuối cùng được biết đến của nó. + 2. Chọn **edit**, khôi phục các phiên bản và hiệu ứng đó, rồi áp dụng triển khai mới. + 3. Chờ máy check-in, sau đó xác minh triển khai được báo cáo. + 4. Mở **Observe → policy** và các phiên làm việc bị ảnh hưởng để xác nhận công việc hợp lệ không còn bị chặn. - Rollback deployment trên cloud là một quy trình dashboard. Sử dụng trạng thái local để xác nhận rằng deployment được sửa đã đến máy: + Mỗi triển khai cho một máy là một thế hệ được đánh số. Liệt kê chúng, sau đó khôi phục một: ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` tạm dừng builtin, custom, và convention policies cho một phiên làm việc local. Nó không tạm dừng Cloud-managed policies, vì vậy nó không phải là một cách khác cho deployment Cloud xấu. + `rollback` tạo một thế hệ mới mang bộ cũ thay vì đặt lại bộ đếm, vì vậy lịch sử luôn chỉ được nối thêm, và nó từ chối một thế hệ đặt tên cho chính sách vì đã bị vô hiệu hóa hoặc xóa. Nó cần một phiên đăng nhập với `policies:write`. `fp fleet diff ` hiển thị những gì được dự định so với những gì máy áp dụng — nó được đọc là `behind` cho đến khi máy thăm dò tiếp theo — và trên chính máy đó, `failproofai policies` liệt kê triển khai mà nó đang chạy. -## Khi nào để rollback +## Tắt một chính sách trên mọi máy + +```bash +fp policies disable # xóa nó khỏi mọi triển khai mang nó +fp policies enable # thêm nó lại +``` + +Mỗi lần tạo một thế hệ mới trên mọi triển khai mà nó chạm đến. Khôi phục một trong những thế hệ đó không phải là cách bạn hoàn tác `disable` — `rollback` từ chối một thế hệ đặt tên cho chính sách bị vô hiệu hóa, và mọi thế hệ từ trước lần vô hiệu hóa đều đặt tên cho chính sách này. `fp policies enable` là cách quay lại, và nó tạo thế hệ riêng của nó. + +## Khôi phục một gói + +Một gói được ghim vào bản phát hành mà bạn đã cài đặt, vì vậy khôi phục nó có nghĩa là cài đặt một bản trước đó: + +```bash +failproofai policies show FailproofAI/policies --releases # mọi phiên bản mà nó đã công bố, và phiên bản nào ở đây +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # ghim phiên bản đó +``` + +Nếu không có terminal, hoặc với `--policy`, `--category` hoặc `--all`, thêm lại sẽ giữ tập con mà bạn đã chọn. Tại terminal không có những điều đó, nó mở bộ chọn được đánh dấu trước bằng các giá trị mặc định của tác giả, và những gì bạn đánh dấu sẽ thay thế lựa chọn của bạn — vì vậy hãy đánh dấu lại những gì bạn đã có. + +## Khi nào cần khôi phục -- Một policy chặn một hành động production được mong đợi. -- Khối lượng kết quả match cao hơn đáng kể so với những gì dự đoán khi triển khai. -- Một policy phụ thuộc vào các trường mà một integration không cung cấp. -- Một phiên bản mới thay đổi hành vi ngoài failure mode được dự định. +- Một chính sách chặn một hành động sản xuất dự kiến. +- Khối lượng khớp cao hơn đáng kể so với dự báo triển khai quan sát được. +- Một chính sách phụ thuộc vào các trường mà một tích hợp không cung cấp. +- Một phiên bản mới thay đổi hành vi ngoài chế độ lỗi dự định. -Sau khi rollback, mở các phiên bị ảnh hưởng và xác định điều kiện gây ra false positive. Tạo một phiên bản mới, kiểm thử cả trường hợp không an toàn và trường hợp hợp lệ, sau đó lặp lại giai đoạn observe. +Sau khi khôi phục, mở các phiên làm việc bị ảnh hưởng và tìm điều kiện đằng sau dương tính giả. Công bố một phiên bản mới, [test](/vi/policies/test) cả trường hợp không an toàn và hợp pháp, rồi quan sát lại trước khi thực thi. - Tạm dừng enforcement có thể thích hợp trong một sự cố, nhưng nó mở rộng phơi nhiễm cho mọi policy đang hoạt động trong phạm vi đó. Ưu tiên rollback phiên bản policy cụ thể khi có thể. + `failproofai config --pause` tạm dừng chính sách cục bộ cho một phiên và không bao giờ những chính sách được quản lý bởi Cloud, vì vậy nó không phải là cách thoát khỏi triển khai Cloud xấu. Việc tạm dừng cũng mở rộng tiếp xúc cho mọi chính sách trong phạm vi của nó; ưu tiên khôi phục phiên bản duy nhất mà hoạt động không đúng. \ No newline at end of file diff --git a/docs/vi/policies/test.mdx b/docs/vi/policies/test.mdx new file mode 100644 index 00000000..0246a5ea --- /dev/null +++ b/docs/vi/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "Kiểm tra một chính sách" +description: "Kiểm tra lại bản nháp dựa trên lưu lượng bạn đã có, và chứng minh rằng nó ngăn chặn những gì nó nên ngăn và cho phép những gì nó phải cho phép, trước khi bất kỳ máy nào thực thi nó." +icon: "flask-conical" +--- + +Kiểm tra mọi chính sách theo hai cách: dựa trên lưu lượng mà các agent của bạn đã tạo ra, và dựa trên một hành động hợp pháp mà nó phải cho phép. Một chính sách chỉ đã kiểm tra trường hợp không an toàn là chưa được kiểm tra đầy đủ. + +## Kiểm tra lại bản nháp + + + + Trình chỉnh sửa chính sách sẽ phát lại bản nháp dựa trên các cuộc gọi mà đội của bạn đã thực hiện, trước khi bạn xuất bản nó. + + 1. Mở bản nháp trong **Admin → policy editor**. Trình chỉnh sửa sẽ xác nhận nó phân tích cú pháp đúng như JavaScript. + 2. Trong **backtest**, chọn các agent và khoảng thời gian để phát lại — **tất cả agent** và **30d** theo mặc định — và để bộ lọc cuối cùng trên **everything** trừ khi bạn muốn thu hẹp nó. + 3. Chọn **run backtest**. + + ![Bảng backtest dưới bản nháp phân tích cú pháp đúng như JavaScript, với ba bộ lọc của nó và hành động run backtest, ở trên publish version.](/images/dashboard/policy-backtest.png) + + Kết quả là những gì bản nháp sẽ làm với những cuộc gọi đó — bao gồm bao nhiêu cuộc gọi **working** mà nó sẽ đã làm gián đoạn. Đó là những dương tính giả được phát hiện trước khi bất kỳ agent nào gặp phải chúng: làm chặt chẽ bản nháp và chạy lại nó cho đến khi con số đó là một con số bạn có thể chấp nhận được. + + + Kiểm tra lại là một tính năng của dashboard. Từ terminal, hãy chạy chính sách dựa trên các sự kiện bạn mô tả thay thế, như bên dưới. + + + +## Chạy nó dựa trên một sự kiện bạn mô tả + +`fp policies test` chạy tệp chính sách trên máy của bạn dựa trên một sự kiện tổng hợp và kiểm tra quyết định. Không có gì được xuất bản và không có gì đến Cloud: + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +Định hình sự kiện với `--event`, `--tool`, `--command` và `--file`. Bộ lọc `match` của chính sách vẫn áp dụng, vì vậy một chính sách không bao gồm sự kiện bạn mô tả sẽ báo cáo `skipped` thay vì một quyết định — thường là dấu hiệu rằng `match` của nó hẹp hơn ý định của bạn. + +## Chạy nó trên một máy + +Tiếp theo, thực thi nó một cách thực sự trên máy của riêng bạn, dựa trên agent của riêng bạn: + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +Lệnh đầu tiên xác thực và cài đặt tệp; lệnh thứ hai xác nhận nó đã tải, cùng với mọi thứ khác thực thi tại đây. Yêu cầu agent thực hiện những gì chính sách ngăn chặn và xem nó bị từ chối, sau đó thực hiện phiên bản hợp pháp và xem nó đi qua. Không ai khác bị ảnh hưởng. + +Trên một máy được kết nối với Cloud, kiểm tra cả hai quyết định dưới **Observe → policy**: lọc theo tên chính sách, sau đó mở từng phiên được liên kết để xác nhận đầu vào công cụ mà nó khớp và lý do nó trả về. + +## Kiểm tra những gì bị hỏng + +Việc cài đặt sẽ từ chối một tệp bị thiếu, lỗi cú pháp, nhập không được giải quyết, một ngoại lệ ở cấp cao nhất, hoặc một mô-đun hết thời gian chờ trong khi tải — vì vậy hãy chạy lại nó sau mỗi thay đổi tệp hoặc bất cứ thứ gì nó nhập. Tại thời điểm thực thi, tệp bị hỏng tương tự được ghi lại và **skipped** để mọi chính sách khác tiếp tục chạy: coi một cảnh báo tải trong nhật ký sản xuất như một thực thi bị mất. Các tệp quy ước tải mà không cần lệnh cài đặt, vì vậy hãy giữ một bước `failproofai policies --install --custom ` rõ ràng trong CI — đó là những gì làm hỏng bản dựng trên một chính sách bị hỏng. + +Sau đó, cung cấp cho nó những gì các agent thực sự gửi, không chỉ đầu vào bạn mong đợi: các trường bị thiếu, tên công cụ thay thế như `Write` và `Edit`, đường dẫn Windows, đầu vào không đúng định dạng. Trả về một `allow`, `instruct` hoặc `deny` có chủ đích trên mọi đường dẫn, giữ hàm xác định, và ràng buộc bất kỳ cuộc gọi bên ngoài nào bằng một thời gian chờ ngắn. + +## Sau đó xuất bản nó và quan sát nó + +Một bài kiểm tra lại cho thấy những gì chính sách sẽ làm với lưu lượng bạn có; nó không thể cho thấy những gì lưu lượng bạn chưa thấy sẽ làm. Chọn **publish version** trong trình chỉnh sửa (hoặc chạy `fp policies publish`), sau đó [triển khai nó](/vi/policies/deploy) ở chế độ **observe** trước tiên — các phán quyết của nó được ghi lại và không có gì bị chặn — và thực thi khi các kết quả phù hợp của nó tách hành động không an toàn khỏi những hành động hợp lệ. \ No newline at end of file diff --git a/docs/vi/reference/cloud-cli.mdx b/docs/vi/reference/cloud-cli.mdx index fc412c3b..9ac4edcd 100644 --- a/docs/vi/reference/cloud-cli.mdx +++ b/docs/vi/reference/cloud-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof Cloud CLI" -description: "Tài liệu tham khảo hoàn chỉnh để truy vấn và quản trị Failproof AI Cloud bằng fp." +description: "Tham chiếu đầy đủ cho việc truy vấn và quản lý Failproof AI Cloud bằng fp." icon: "cloud-cog" --- -Sử dụng `fp` để kiểm tra telemetry trên Cloud, quản lý enforcement quản lý bởi cloud (policies, fleet deployments, guardrail decisions), và quản lý audits, findings, issues, alerts, keys, users, queries, và settings. Sử dụng [`failproofai`](/vi/reference/failproof-cli) cho local hooks, policies, capture, và machine enrollment. +Sử dụng `fp` để kiểm tra dữ liệu telemetry Cloud, quản lý enforcement được quản lý bởi cloud (policies, fleet deployments, guardrail decisions), và quản lý audits, findings, issues, alerts, keys, users, queries, và settings. Sử dụng [`failproofai`](/vi/reference/failproof-cli) cho local hooks, policies, capture, và machine enrollment. -Cài đặt Cloud CLI phát hành dưới dạng công cụ độc lập: +Cài đặt Cloud CLI được phát hành dưới dạng công cụ độc lập: ```bash uv tool install fp-cloud-cli @@ -26,23 +26,23 @@ fp whoami fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` -Các tùy chọn toàn cục phải đặt trước lệnh: +Global options phải đứng trước lệnh: ```bash fp --json sessions --since 24h ``` -Chạy `fp COMMAND --help` hoặc `fp COMMAND SUBCOMMAND --help` để xem trợ giúp trên terminal. +Chạy `fp COMMAND --help` hoặc `fp COMMAND SUBCOMMAND --help` để xem trợ giúp trong terminal. -## Các lệnh CLI +## Lệnh CLI -### Xác thực +### Authentication -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | | `fp login` | Đăng nhập bằng mã một lần được gửi qua email và chọn một tổ chức. | `--email`, `-e`; `--org`; `--force` | | `fp logout` | Thu hồi và xóa phiên người dùng đã lưu. | — | -| `fp whoami` | Hiển thị danh tính hiện tại, chế độ xác thực, tổ chức và quyền. | — | +| `fp whoami` | Hiển thị danh tính hiện tại, chế độ xác thực, tổ chức, và quyền hạn. | — | | `fp version` | Hiển thị phiên bản CLI được cài đặt. | — | | `fp help` | Hiển thị trợ giúp lệnh cấp cao nhất. | — | @@ -51,30 +51,30 @@ fp login --email you@example.com --org reliability-team fp whoami ``` -### Sự kiện +### Events ```text fp events [OPTIONS] ``` -Liệt kê các sự kiện agent riêng lẻ. Luồng nhẹ mặc định loại trừ các payload thô; sử dụng `--full` chỉ cho điều tra giới hạn. +Liệt kê các sự kiện agent riêng lẻ. Bộ feed nhẹ mặc định loại trừ các payload thô; chỉ sử dụng `--full` cho một cuộc điều tra có giới hạn. -| Tùy chọn | Mô tả | +| Option | Mô tả | | --- | --- | -| `--limit`, `-n ` | Tổng số hàng tối đa. Mặc định: `50`. | +| `--limit`, `-n ` | Tối đa hàng. Mặc định: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, hoặc `7d`. | -| `--from ` / `--to ` | Phạm vi UTC ISO 8601; ghi đè `--since`. | -| `--env ` | Bộ lọc môi trường; lặp lại hoặc phân tách bằng dấu phẩy. | -| `--event-type ` | Bộ lọc loại sự kiện; lặp lại hoặc phân tách bằng dấu phẩy. | +| `--from ` / `--to ` | Khoảng UTC ISO 8601; ghi đè `--since`. | +| `--env ` | Bộ lọc Environment; lặp lại hoặc phân tách bằng dấu phẩy. | +| `--event-type ` | Bộ lọc event-type; lặp lại hoặc phân tách bằng dấu phẩy. | | `--agent-id ` | Bộ lọc agent; lặp lại hoặc phân tách bằng dấu phẩy. | -| `--session-id ` | Bộ lọc phiên; lặp lại hoặc phân tách bằng dấu phẩy. | -| `--search ` | Tìm kiếm văn bản payload; có thể lặp lại, bất kỳ thuật ngữ nào khớp. | +| `--session-id ` | Bộ lọc session; lặp lại hoặc phân tách bằng dấu phẩy. | +| `--search ` | Tìm kiếm văn bản payload; có thể lặp lại, khớp bất kỳ thuật ngữ nào. | | `--order asc\|desc` | Thứ tự thời gian. Mặc định: mới nhất trước. | -| `--all` | Tự động phân trang lên đến `--limit`. | -| `--cursor ` | Tiếp tục từ một con trỏ không rõ. | -| `--page-size ` | Hàng trên mỗi yêu cầu với `--all`; tối đa `200`. | -| `--full` | Bao gồm các payload thô qua điểm cuối sự kiện nặng hơn. | -| `--fields ` | Trả về chỉ các trường đã chọn; yêu cầu `payload` kích hoạt chế độ đầy đủ. | +| `--all` | Tự động phân trang lên tới `--limit`. | +| `--cursor ` | Tiếp tục từ con trỏ không rõ. | +| `--page-size ` | Hàng mỗi yêu cầu với `--all`; tối đa `200`. | +| `--full` | Bao gồm các payload thô qua endpoint event nặng hơn. | +| `--fields ` | Trả về chỉ các trường được chọn; yêu cầu `payload` kích hoạt chế độ đầy đủ. | ```bash fp events --session-id --order asc --all --limit 10000 @@ -82,106 +82,106 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` phân trang **lên đến `--limit`**, mặc định là **50** — vì vậy `--all` riêng lẻ dừng lại ở 50 hàng. Khi dừng sớm, phản hồi mang theo `next_cursor` để tiếp tục từ đó; `"next_cursor": null` có nghĩa là luồng thực sự đã cạn kiệt. + `--all` phân trang **lên tới `--limit`**, mặc định là **50** — vì vậy `--all` riêng lẻ dừng ở 50 hàng. Khi nó dừng sớm, phản hồi sẽ có `next_cursor` để tiếp tục từ đó; `"next_cursor": null` có nghĩa là feed thực sự đã hết. -### Phiên +### Sessions ```text fp sessions [OPTIONS] ``` -| Tùy chọn | Mô tả | +| Option | Mô tả | | --- | --- | -| `--limit`, `-n ` | Tổng số hàng tối đa. Mặc định: `50`. | +| `--limit`, `-n ` | Tối đa hàng. Mặc định: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, hoặc `7d`. | -| `--from ` / `--to ` | Phạm vi UTC ISO 8601; ghi đè `--since`. | -| `--env ` | Bộ lọc môi trường; lặp lại hoặc phân tách bằng dấu phẩy. | +| `--from ` / `--to ` | Khoảng UTC ISO 8601; ghi đè `--since`. | +| `--env ` | Bộ lọc environment; lặp lại hoặc phân tách bằng dấu phẩy. | | `--status ` | `done`, `error`, hoặc `timeout`; lặp lại hoặc phân tách bằng dấu phẩy. | -| `--agent-id ` | Khớp các phiên liên quan đến bất kỳ agent nào được chọn. | -| `--session-id ` | Bộ lọc phiên; lặp lại hoặc phân tách bằng dấu phẩy. | -| `--all` | Tự động phân trang lên đến `--limit`. | -| `--cursor ` | Tiếp tục từ một con trỏ không rõ. | -| `--page-size ` | Hàng trên mỗi yêu cầu với `--all`; tối đa `200`. | -| `--fields ` | Trả về chỉ các trường đã chọn. | -| `--full-ids` | Không rút gọn ID phiên trong đầu ra terminal. | -| `--agents` | Mở rộng danh sách agent cho các phiên đa agent. | +| `--agent-id ` | Khớp các phiên liên quan đến bất kỳ agent được chọn nào. | +| `--session-id ` | Bộ lọc session; lặp lại hoặc phân tách bằng dấu phẩy. | +| `--all` | Tự động phân trang lên tới `--limit`. | +| `--cursor ` | Tiếp tục từ con trỏ không rõ. | +| `--page-size ` | Hàng mỗi yêu cầu với `--all`; tối đa `200`. | +| `--fields ` | Trả về chỉ các trường được chọn. | +| `--full-ids` | Không rút ngắn session ID trong đầu ra terminal. | +| `--agents` | Mở rộng danh sách agent cho các phiên multi-agent. | -### Đánh giá +### Evaluations ```text fp evals [OPTIONS] ``` -| Tùy chọn | Mô tả | +| Option | Mô tả | | --- | --- | -| `--aggregate` | Hiển thị tổng cộng và thống kê theo điểm thay vì các đánh giá riêng lẻ. | -| `--limit`, `-n ` | Hàng danh sách tối đa. Mặc định: `50`. | -| `--since`, `--from`, `--to` | Chọn phạm vi thời gian. | -| `--env`, `--status`, `--agent-id`, `--session-id` | Thu hẹp thành một giá trị chính xác cho mỗi bộ lọc. | -| `--score KEY:MIN..MAX` | Phạm vi điểm; có thể lặp lại và tất cả các phạm vi phải khớp. | +| `--aggregate` | Hiển thị tổng số và thống kê theo điểm thay vì các đánh giá riêng lẻ. | +| `--limit`, `-n ` | Tối đa hàng danh sách. Mặc định: `50`. | +| `--since`, `--from`, `--to` | Chọn khoảng thời gian. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Thu hẹp thành một giá trị chính xác mỗi bộ lọc. | +| `--score KEY:MIN..MAX` | Khoảng điểm; có thể lặp lại và tất cả các khoảng phải khớp. | | `--all`, `--cursor`, `--page-size` | Kiểm soát phân trang danh sách. | -| `--fields ` | Trả về chỉ các trường đã chọn. | -| `--full-ids` | Hiển thị ID phiên hoàn chỉnh. | -| `--scores-full` | Hiển thị mọi điểm trong đầu ra terminal. | +| `--fields ` | Trả về chỉ các trường được chọn. | +| `--full-ids` | Hiển thị session ID đầy đủ. | +| `--scores-full` | Hiển thị mỗi điểm trong đầu ra terminal. | -### Lỗi +### Errors ```text fp errors [OPTIONS] ``` -| Tùy chọn | Mô tả | +| Option | Mô tả | | --- | --- | -| `--aggregate` | Tóm tắt các lỗi khớp thay vì liệt kê hàng. | -| `--limit`, `-n ` | Hàng danh sách tối đa. Mặc định: `50`. | -| `--since`, `--from`, `--to` | Chọn phạm vi thời gian. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Thu hẹp dân số lỗi. | +| `--aggregate` | Tóm tắt lỗi phù hợp thay vì liệt kê hàng. | +| `--limit`, `-n ` | Tối đa hàng danh sách. Mặc định: `50`. | +| `--since`, `--from`, `--to` | Chọn khoảng thời gian. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Thu hẹp quần thể lỗi. | | `--search ` | Tìm kiếm văn bản payload; có thể lặp lại. | | `--order asc\|desc` | Thứ tự thời gian. | | `--all`, `--cursor`, `--page-size` | Kiểm soát phân trang danh sách. | -| `--fields ` | Trả về chỉ các trường đã chọn. | -| `--full-ids` | Hiển thị ID phiên hoàn chỉnh. | +| `--fields ` | Trả về chỉ các trường được chọn. | +| `--full-ids` | Hiển thị session ID đầy đủ. | -### Sử dụng và giá trị bộ lọc +### Usage and filter values -| Lệnh | Mục đích | +| Command | Mục đích | | --- | --- | | `fp usage` | Hiển thị sử dụng cho cửa sổ đo lường hiện tại. | -| `fp list envs` | Liệt kê các môi trường quan sát được. | -| `fp list agents` | Liệt kê các ID agent quan sát được. | -| `fp list event_types` | Liệt kê các loại sự kiện. | +| `fp list envs` | Liệt kê các environment được quan sát. | +| `fp list agents` | Liệt kê các agent ID được quan sát. | +| `fp list event_types` | Liệt kê các event type. | | `fp list score_filters` | Liệt kê các khóa điểm đánh giá. | -| `fp list models` | Liệt kê tên mô hình. | -| `fp list hooks` | Liệt kê tên hook. | -| `fp list tools` | Liệt kê tên công cụ. | +| `fp list models` | Liệt kê các tên mô hình. | +| `fp list hooks` | Liệt kê các tên hook. | +| `fp list tools` | Liệt kê các tên tool. | | `fp list error_types` | Liệt kê các loại lỗi. | -### Tổ chức +### Organizations -| Lệnh | Mục đích | +| Command | Mục đích | | --- | --- | | `fp orgs list` | Liệt kê các tổ chức có thể truy cập. | -| `fp orgs switch [SLUG]` | Lưu một tổ chức hoạt động; nhắc nhở khi bỏ qua. | +| `fp orgs switch [SLUG]` | Lưu một tổ chức hoạt động; nhắc khi bị bỏ qua. | | `fp orgs current` | Hiển thị tổ chức hoạt động. | -| `fp orgs perms` | Hiển thị quyền của bạn trong tổ chức hoạt động. | +| `fp orgs perms` | Hiển thị quyền hạn của bạn trong tổ chức hoạt động. | -### Khóa API +### API keys -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | -| `fp keys list` | Liệt kê các khóa tổ chức. | `--show-id`; `--fields ` | -| `fp keys show NAME` | Hiển thị một khóa và các quyền của nó. | — | -| `fp keys create NAME` | Tạo một khóa và tiết lộ bí mật của nó một lần. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | Thay thế bộ quyền hoặc điều chỉnh các quyền. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | Xoay vòng bí mật và tiết lộ sự thay thế một lần. | `--yes`, `-y` | -| `fp keys disable NAME` | Thu hồi vĩnh viễn một khóa. | `--yes`, `-y` | +| `fp keys list` | Liệt kê các kóa tổ chức. | `--show-id`; `--fields ` | +| `fp keys show NAME` | Hiển thị một kóa và các grant của nó. | — | +| `fp keys create NAME` | Tạo một kóa và tiết lộ bí mật của nó một lần. | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | Thay thế bộ quyền hoặc điều chỉnh grant. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | Xoay bí mật và tiết lộ sự thay thế một lần. | `--yes`, `-y` | +| `fp keys disable NAME` | Vĩnh viễn thu hồi một kóa. | `--yes`, `-y` | -Các mã thông báo quyền sử dụng `resource:action`, chẳng hạn như `events:add`. Lặp lại `--add`, phân tách bằng dấu phẩy, hoặc sử dụng các hành động chấm như `events:read.add`. +Token quyền sử dụng `resource:action`, chẳng hạn như `events:add`. Lặp lại `--add`, phân tách bằng dấu phẩy, hoặc sử dụng các hành động có dấu chấm như `events:read.add`. -### Truy vấn +### Queries -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | | `fp query list` | Liệt kê các truy vấn đã lưu. | `--show-id`; `--fields ` | | `fp query show NAME` | Hiển thị một truy vấn. | — | @@ -191,62 +191,62 @@ Các mã thông báo quyền sử dụng `resource:action`, chẳng hạn như ` | `fp query run [NAME]` | Chạy một truy vấn đã lưu hoặc SQL ad-hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | | `fp query schema [TABLE]` | Liệt kê các bảng có thể truy vấn hoặc kiểm tra một bảng. | — | -### Người dùng +### Users -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | | `fp users list` | Liệt kê các thành viên tổ chức. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | Hiển thị một thành viên và các quyền của họ. | — | +| `fp users show EMAIL` | Hiển thị một thành viên và các grant của họ. | — | | `fp users create EMAIL` | Thêm một thành viên. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | Thay đổi các quyền của thành viên. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users update EMAIL` | Thay đổi các grant của thành viên. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | | `fp users disable EMAIL` | Vô hiệu hóa đăng nhập. | `--yes`, `-y` | -| `fp users enable EMAIL` | Bật lại đăng nhập. | `--yes`, `-y` | +| `fp users enable EMAIL` | Kích hoạt lại đăng nhập. | `--yes`, `-y` | -### Cài đặt +### Settings -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | | `fp settings list` | Liệt kê các cài đặt tổ chức và giá trị hiện tại. | — | -| `fp settings schema` | Hiển thị các giá trị được chấp nhận và mô tả. | — | -| `fp settings set KEY` | Thay đổi một cài đặt hiện có. | chính xác một trong `--value`, `--json-value`, `--file`; tùy chọn `--yes`, `-y` | +| `fp settings schema` | Hiển thị các giá trị và mô tả được chấp nhận. | — | +| `fp settings set KEY` | Thay đổi cài đặt hiện có. | chính xác một trong `--value`, `--json-value`, `--file`; tùy chọn `--yes`, `-y` | -### Cảnh báo +### Alerts -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | | `fp alerts list` | Liệt kê các quy tắc cảnh báo. | `--show-id` | | `fp alerts show NAME` | Hiển thị một cảnh báo. | — | | `fp alerts create NAME` | Tạo một cảnh báo. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | Cập nhật hoặc đổi tên một cảnh báo. | các tùy chọn tạo cộng với `--name`; `--yes`, `-y` | +| `fp alerts update NAME` | Cập nhật hoặc đổi tên một cảnh báo. | create options cộng với `--name`; `--yes`, `-y` | | `fp alerts delete NAME` | Xóa một cảnh báo. | `--yes`, `-y` | -| `fp alerts test NAME` | Gửi một thông báo thử nghiệm. | `--channels`; `--yes`, `-y` | +| `fp alerts test NAME` | Gửi thông báo kiểm tra. | `--channels`; `--yes`, `-y` | -Mức độ cảnh báo là `info`, `warning`, và `critical`. Các loại kích hoạt là `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound`, và `per_event`. Các khoảng thời gian đánh giá phải nằm trong khoảng từ 30 đến 86.400 giây. +Độ nghiêm trọng cảnh báo là `info`, `warning`, và `critical`. Loại trigger là `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound`, và `per_event`. Khoảng thời gian đánh giá phải nằm trong khoảng 30 và 86.400 giây. -### Kiểm toán +### Audits -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | -| `fp audits list` | Liệt kê các kiểm toán. | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | Hiển thị một định nghĩa kiểm toán và trạng thái. | — | -| `fp audits create NAME` | Tạo một kiểm toán và ngay lập tức xếp hàng đợi lần chạy đầu tiên của nó. | Xem [tùy chọn tạo](#audit-create-options). | -| `fp audits edit NAME` | Thay thế các cài đặt kiểm toán trong khi giữ lại các giá trị không được chỉ định. | các tùy chọn định nghĩa tạo; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | Xóa một kiểm toán, các findings của nó và lịch sử chạy. | `--yes`, `-y` | -| `fp audits run NAME` | Xếp hàng đợi một lần chạy thủ công. | — | -| `fp audits runs NAME` | Liệt kê lịch sử chạy. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | Hiển thị trạng thái tóm tắt và tìm nạp URL tham chiếu. | — | -| `fp audits context-set NAME` | Thay đổi tóm tắt hoặc URL tham chiếu. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits list` | Liệt kê audits. | `--enabled-only`; `--show-id` | +| `fp audits show NAME` | Hiển thị định nghĩa và trạng thái audit. | — | +| `fp audits create NAME` | Tạo một audit và ngay lập tức xếp hàng lần chạy đầu tiên của nó. | Xem [create options](#audit-create-options). | +| `fp audits edit NAME` | Thay thế cài đặt audit trong khi giữ lại các giá trị không được chỉ định. | create definition options; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | Xóa một audit, findings của nó, và run history. | `--yes`, `-y` | +| `fp audits run NAME` | Xếp hàng một lần chạy thủ công. | — | +| `fp audits runs NAME` | Liệt kê run history. | `--limit`, `-n`; `--show-id` | +| `fp audits context-show NAME` | Hiển thị brief và trạng thái tìm nạp URL tham chiếu. | — | +| `fp audits context-set NAME` | Thay đổi brief hoặc URL tham chiếu. | `--text`; `--text-file`; `--url`; `--clear-urls` | | `fp audits context-refresh NAME` | Tái tìm nạp URL tham chiếu. | — | -| `fp audits findings` | Liệt kê các findings. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | +| `fp audits findings` | Liệt kê findings. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | | `fp audits finding FINDING_ID` | Hiển thị một finding và bằng chứng của nó. | — | | `fp audits ack FINDING_ID` | Xác nhận một finding. | `--reason` | -| `fp audits mute FINDING_ID` | Loại bỏ một mẫu lặp lại. | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | Đánh dấu một mẫu không thực hiện được và loại bỏ nó. | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | Đánh dấu một finding đã được sửa mà không có loại bỏ trong tương lai. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | Trả một finding về hàng đợi trực tiếp và xóa loại bỏ. | — | -| `fp audits assign FINDING_ID` | Đặt chủ sở hữu finding. | `--to ` bắt buộc | +| `fp audits mute FINDING_ID` | Chặn một mẫu tái diễn. | `--reason`; `--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | Đánh dấu một mẫu không hành động được và chặn nó. | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | Đánh dấu một finding đã sửa mà không có sự chặn trong tương lai. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | Trả một finding về hàng đợi trực tiếp và xóa sự chặn. | — | +| `fp audits assign FINDING_ID` | Đặt chủ sở hữu finding. | required `--to ` | -#### Các tùy chọn tạo kiểm toán +#### Audit create options ```bash fp audits create checkout-reliability \ @@ -259,122 +259,122 @@ fp audits create checkout-reliability \ --url https://runbooks.example.com/checkout ``` -| Tùy chọn | Mô tả | +| Option | Mô tả | | --- | --- | -| `--file ` | Dựa trên định nghĩa JSON, hoặc sử dụng `-` cho stdin. Các cờ rõ ràng ghi đè các giá trị tệp. | -| `--description ` | Nêu câu hỏi hoặc mục đích thất bại. | -| `--enabled` / `--disabled` | Bắt đầu lên lịch hoặc tắt. Mặc định: được bật. | +| `--file ` | Dựa định nghĩa trên JSON, hoặc sử dụng `-` cho stdin. Cờ rõ ràng ghi đè các giá trị tệp. | +| `--description ` | Nêu rõ câu hỏi lỗi hoặc mục đích. | +| `--enabled` / `--disabled` | Bắt đầu lên lịch bật hoặc tắt. Mặc định: enabled. | | `--schedule-interval-secs ` | `3600`–`604800`. Mặc định: `86400`. | | `--schedule-anchor ` | Giai đoạn UTC cố định ở dạng ISO 8601. Mặc định: 09:00 UTC tiếp theo. | -| `--window-mode since_last\|fixed` | Tiếp tục sau cửa sổ được phân tích đầy đủ cuối cùng hoặc kiểm tra lại một cửa sổ lăn. Mặc định: `since_last`. | +| `--window-mode since_last\|fixed` | Tiếp tục sau cửa sổ được phân tích đầy đủ cuối cùng hoặc lặp lại kiểm tra một cửa sổ lăn. Mặc định: `since_last`. | | `--lookback-window-secs ` | `3600`–`7776000`. Mặc định: `604800`. | | `--scope ''` | Lọc theo `environments`, `agent_ids`, hoặc các trường phạm vi được hỗ trợ khác. | | `--ignore-error-type ` | Loại trừ các loại lỗi; lặp lại hoặc phân tách bằng dấu phẩy. | -| `--llm` / `--no-llm` | Bật hoặc tắt phân tích agentic. Mặc định: được bật. | -| `--top-k ` | Giữ lại `1`–`500` findings. Mặc định: `50`. | +| `--llm` / `--no-llm` | Bật hoặc tắt phân tích agentic. Mặc định: enabled. | +| `--top-k ` | Giữ `1`–`500` findings. Mặc định: `50`. | | `--sensitivity low\|medium\|high` | Đặt độ nhạy báo cáo. Mặc định: `medium`. | | `--channels ''` | Mảng kênh thông báo. | -| `--text ` | Tóm tắt nội tuyến, tối đa 8.192 ký tự. | -| `--text-file ` | Đọc tóm tắt từ một tệp; loại trừ lẫn nhau với `--text`. | -| `--url ` | Thêm tham chiếu HTTPS công khai; lặp lại lên đến năm lần. | +| `--text ` | Brief nội tuyến, tối đa 8.192 ký tự. | +| `--text-file ` | Đọc brief từ một tệp; loại trừ lẫn nhau với `--text`. | +| `--url ` | Thêm tham chiếu HTTPS công khai; lặp lại lên tới năm lần. | -Bao gồm bối cảnh trong quá trình tạo khi lần chạy đầu tiên cần nó. Tạo cam kết định nghĩa và bối cảnh cùng nhau trước khi lần chạy được xếp hàng đợi bắt đầu. +Bao gồm context trong quá trình tạo khi lần chạy đầu tiên cần nó. Tạo commits định nghĩa và context cùng nhau trước khi lần chạy được xếp hàng bắt đầu. - `fp audits run` là không đồng bộ. Poll `fp audits runs NAME` cho đến khi lần chạy mới nhất thành công hoặc thất bại trước khi đọc các findings của nó. + `fp audits run` là không đồng bộ. Poll `fp audits runs NAME` cho đến khi lần chạy mới nhất thành công hoặc thất bại trước khi đọc findings của nó. -### Vấn đề +### Issues -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | -| `fp issues list` | Liệt kê các vấn đề. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | Đếm các trạng thái vấn đề mở hoặc được chọn. | `--state` | -| `fp issues show INCIDENT_ID` | Hiển thị chi tiết vấn đề, nhận xét, người đăng ký và hoạt động. | — | -| `fp issues open` | Mở một vấn đề thủ công hoặc liên kết cảnh báo. | `--summary` bắt buộc; `--title`, `--alert-id`, `--severity` tùy chọn | -| `fp issues ack INCIDENT_ID` | Xác nhận một vấn đề. | — | -| `fp issues assign INCIDENT_ID` | Thay thế những người được phân công; bỏ qua tùy chọn để xóa. | `--assignee` có thể lặp lại | -| `fp issues resolve INCIDENT_ID` | Giải quyết một vấn đề. | `--yes`, `-y` | -| `fp issues comment-list INCIDENT_ID` | Liệt kê các nhận xét. | — | +| `fp issues list` | Liệt kê issues. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | Đếm các trạng thái issue mở hoặc được chọn. | `--state` | +| `fp issues show INCIDENT_ID` | Hiển thị chi tiết issue, nhận xét, người đăng ký, và hoạt động. | — | +| `fp issues open` | Mở một issue thủ công hoặc liên kết cảnh báo. | required `--summary`; optional `--title`, `--alert-id`, `--severity` | +| `fp issues ack INCIDENT_ID` | Xác nhận một issue. | — | +| `fp issues assign INCIDENT_ID` | Thay thế những người được giao; bỏ qua tùy chọn để xóa. | repeatable `--assignee` | +| `fp issues resolve INCIDENT_ID` | Giải quyết một issue. | `--yes`, `-y` | +| `fp issues comment-list INCIDENT_ID` | Liệt kê nhận xét. | — | | `fp issues comment-add INCIDENT_ID` | Thêm một nhận xét. | chính xác một trong `--body`, `--file` | | `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Xóa một nhận xét. | `--yes`, `-y` | -| `fp issues subscribers INCIDENT_ID` | Liệt kê những người đăng ký. | — | -| `fp issues subscribe INCIDENT_ID` | Đăng ký chính mình hoặc một nhà khai thác khác. | `--email` | -| `fp issues unsubscribe INCIDENT_ID` | Xóa một đăng ký. | `--email` | +| `fp issues subscribers INCIDENT_ID` | Liệt kê người đăng ký. | — | +| `fp issues subscribe INCIDENT_ID` | Đăng ký chính mình hoặc một người điều hành khác. | `--email` | +| `fp issues unsubscribe INCIDENT_ID` | Loại bỏ một đăng ký. | `--email` | -Các trạng thái vấn đề hợp lệ là `firing`, `acknowledged`, và `resolved`. Mức độ nghiêm trọng của vấn đề độc lập là `info`, `warning`, và `critical`. +Trạng thái issue hợp lệ là `firing`, `acknowledged`, và `resolved`. Độ nghiêm trọng issue độc lập là `info`, `warning`, và `critical`. -### Trợ lý Cloud +### Cloud assistant -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | -| `fp agent health` | Kiểm tra sự sẵn có và cấu hình của trợ lý. | — | -| `fp agent models` | Liệt kê các mô hình trợ lý có sẵn. | — | -| `fp agent chats` | Liệt kê các cuộc trò chuyện đã lưu. | — | -| `fp agent ask [MESSAGE]` | Bắt đầu hoặc tiếp tục một cuộc trò chuyện; đọc stdin khi thông báo bị bỏ qua. | `--chat`; `--model`; `--page-context` | -| `fp agent show CHAT_ID` | Hiển thị một cuộc hội thoại đã lưu. | — | -| `fp agent rename CHAT_ID` | Đổi tên một cuộc hội thoại. | `--title` bắt buộc | -| `fp agent delete CHAT_ID` | Xóa một cuộc hội thoại. | `--yes`, `-y` | +| `fp agent health` | Kiểm tra tính khả dụng và cấu hình của assistant. | — | +| `fp agent models` | Liệt kê các mô hình assistant có sẵn. | — | +| `fp agent chats` | Liệt kê các trò chuyện đã lưu. | — | +| `fp agent ask [MESSAGE]` | Bắt đầu hoặc tiếp tục một trò chuyện; đọc stdin khi tin nhắn bị bỏ qua. | `--chat`; `--model`; `--page-context` | +| `fp agent show CHAT_ID` | Hiển thị một cuộc trò chuyện đã lưu. | — | +| `fp agent rename CHAT_ID` | Đổi tên một cuộc trò chuyện. | required `--title` | +| `fp agent delete CHAT_ID` | Xóa một cuộc trò chuyện. | `--yes`, `-y` | ### Policies -Các phiên bản policy quản lý bởi cloud. **Chỉ phiên** — mọi lệnh ở đây thoát `2` dưới một khóa API, trước bất kỳ yêu cầu nào, vì đây là các tuyến ghi root bị cố ý loại khỏi `/v1`. +Phiên bản policy được quản lý bởi cloud. **Session-only** — mỗi lệnh ở đây thoát với mã `2` dưới một API key, trước bất kỳ yêu cầu nào, vì đây là các tuyến ghi root-only được cố ý loại bỏ khỏi `/v1`. -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | | `fp policies list` | Liệt kê các phiên bản policy. | `--json` | -| `fp policies show POLICY_ID` | Hiển thị một policy, với nguồn của nó. | — | +| `fp policies show POLICY_ID` | Hiển thị một policy, với mã nguồn của nó. | — | | `fp policies publish NAME PATH` | Tạo một phiên bản từ `.mjs` cục bộ. | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | Thêm nó trở lại mọi deployment được xóa khỏi nó, tạo một thế hệ mới trên mỗi cái. | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | Xóa nó khỏi mọi deployment mang theo nó, tạo một thế hệ mới trên mỗi cái. | `--yes`, `-y` | +| `fp policies enable POLICY_ID` | Thêm nó trở lại mỗi deployment nó được loại bỏ, tạo ra một thế hệ mới trên mỗi cái. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | Loại bỏ nó khỏi mỗi deployment mang nó, tạo ra một thế hệ mới trên mỗi cái. | `--yes`, `-y` | | `fp policies delete POLICY_ID` | Xóa một phiên bản policy. | `--yes`, `-y` | -| `fp policies test PATH` | Chạy một policy cục bộ so với một bối cảnh tổng hợp. Áp dụng bộ lọc `match` của mỗi policy, vì vậy một policy không bao phủ sự kiện/công cụ đã cho được báo cáo `skipped` thay vì chạy. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | -| `fp policies compose PROMPT` | Soạn thảo một policy với trợ lý. Cần `policies:write`. | — | +| `fp policies test PATH` | Chạy một policy cục bộ chống lại bối cảnh tổng hợp. Áp dụng bộ lọc `match` của mỗi policy, vì vậy bộ không bao gồm sự kiện/tool được cung cấp sẽ được báo cáo `skipped` thay vì được chạy. | `--event`; `--tool`; `--command`; `--file`; `--expect` | +| `fp policies compose PROMPT` | Dự thảo một policy với assistant. Cần `policies:write`. | — | -### Hạm đội +### Fleet -Những chiếc máy nào chạy những policy nào. **Chỉ phiên**, lý do tương tự như trên. +Những máy nào chạy những policy nào. **Session-only**, lý do tương tự như trên. -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | -| `fp fleet list` | Liệt kê các máy được đăng ký và thế hệ deployment của chúng. | — | +| `fp fleet list` | Liệt kê các máy đã đăng ký và thế hệ deployment của chúng. | — | | `fp fleet show MACHINE_ID` | Bộ policy mà một máy hiện đang chạy. | — | -| `fp fleet deploy MACHINE_ID` | **Thay thế toàn bộ bộ policy của máy.** In kế hoạch và chỉ hỏi trên terminal tương tác mà không có `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | So sánh một máy với một deployment khác. | — | -| `fp fleet history MACHINE_ID` | Các deployments trước đó cho một máy. | — | -| `fp fleet rollback MACHINE_ID` | Khôi phục một deployment trước đó. | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | Đặt tên có thể đọc được cho một máy. | `--name` bắt buộc | +| `fp fleet deploy MACHINE_ID` | **Thay thế toàn bộ bộ policy của máy.** In kế hoạch và chỉ hỏi trên terminal tương tác không có `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | So sánh một máy chống lại một deployment khác. | — | +| `fp fleet history MACHINE_ID` | Deployments trong quá khứ cho một máy. | — | +| `fp fleet rollback MACHINE_ID GENERATION` | Phục hồi bộ policy của một thế hệ trong quá khứ, là một thế hệ mới. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | Đặt cho một máy một tên có thể đọc được. | required `--name` | ### Guardrails -Những gì enforcement thực sự đã làm. **Chỉ phiên**, lý do tương tự như trên. +Enforcement thực sự làm gì. **Session-only**, lý do tương tự như trên. -| Lệnh | Mục đích | Tùy chọn | +| Command | Mục đích | Options | | --- | --- | --- | -| `fp guardrails summary` | Phạm vi, các tổng đã chặn/được đánh giá, một sparkline deny, và bảng per-policy. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -| `fp guardrails timeline` | Các quyết định xếp thành từng cửa sổ, tính tổng trên mọi nguồn policy. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails summary` | Phạm vi bao phủ, tổng số bị chặn/được đánh giá, một sparkline từ chối, và bảng mỗi policy. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Quyết định xếp thành nhóm trên cửa sổ, tổng hợp trên mọi nguồn policy. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -## Các cờ toàn cục +## Global flags -| Cờ | Mô tả | +| Flag | Mô tả | | --- | --- | -| `--json` | Phát ra JSON có thể đọc bằng máy. | +| `--json` | Phát ra JSON có thể đọc được bởi máy. | | `--base-url ` | Sử dụng một dashboard tự lưu trữ hoặc phát triển. | -| `--org ` | Chọn một tổ chức cho lệnh này. | -| `--token ` | Ghi đè mã thông báo phiên người dùng đã lưu. | -| `--api-key ` | Xác thực tự động bằng khóa API; không bao giờ được lưu. | -| `--timeout ` | Timeout HTTP; phải dương. Mặc định: `30`. | -| `--quiet`, `-q` | Loại bỏ đầu ra trạng thái trên stderr. | -| `--no-color` | Tắt đầu ra có màu. | -| `--insecure` / `--secure` | Tắt hoặc khôi phục xác minh chứng chỉ TLS. | -| `--version` | In phiên bản không được đóng hộp và thoát. | +| `--org ` | Chọn một tổ chức cho lần gọi này. | +| `--token ` | Ghi đè token phiên người dùng đã lưu. | +| `--api-key ` | Xác thực tự động bằng API key; không bao giờ lưu. | +| `--timeout ` | HTTP timeout; phải là dương. Mặc định: `30`. | +| `--quiet`, `-q` | Chặn đầu ra trạng thái trên stderr. | +| `--no-color` | Vô hiệu hóa đầu ra có màu. | +| `--insecure` / `--secure` | Vô hiệu hóa hoặc khôi phục xác minh chứng chỉ TLS. | +| `--version` | In phiên bản và thoát. | | `--help`, `-h` | Hiển thị trợ giúp. | -`--api-key` dành cho tự động hóa. Đăng nhập, chuyển đổi tổ chức và các lệnh trợ lý yêu cầu phiên người dùng. +`--api-key` dành cho tự động hóa. Đăng nhập, chuyển đổi tổ chức, và lệnh assistant yêu cầu một phiên người dùng. -## Các biến môi trường +## Environment variables -| Biến | Tương đương hoặc mục đích | +| Variable | Tương đương hoặc mục đích | | --- | --- | | `FP_DASHBOARD_URL` | `--base-url` | | `FP_ORG` | `--org` | @@ -382,18 +382,18 @@ Những gì enforcement thực sự đã làm. **Chỉ phiên**, lý do tương | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | Chuyển vị thư mục cấu hình CLI (mặc định `~/.failproofai/fpcli`). | -| `FP_ANALYTICS_DISABLED` hoặc `DO_NOT_TRACK` | Tắt phân tích CLI ẩn danh. | -| `NO_COLOR` | Tắt đầu ra có màu. | +| `FP_HOME` | Chuyển vị trí thư mục cấu hình CLI (mặc định `~/.failproofai/fpcli`). | +| `FP_ANALYTICS_DISABLED` hoặc `DO_NOT_TRACK` | Vô hiệu hóa phân tích CLI ẩn danh. | +| `NO_COLOR` | Vô hiệu hóa đầu ra có màu. | -Các cờ rõ ràng ghi đè các biến môi trường, ghi đè cấu hình đã lưu. Ở chế độ khóa API, chọn tenancy rõ ràng với `--org` hoặc `FP_ORG`. +Cờ rõ ràng ghi đè các biến môi trường, ghi đè cấu hình đã lưu. Ở chế độ API-key, chọn tenant rõ ràng với `--org` hoặc `FP_ORG`. - Các cách viết `AGENTEYE_*` của chúng **không được `fp` đọc** và không bao giờ được — CLI khai báo `FP_*` (`fp_cli/app.py`), và một biến không xác định không phải là lỗi. Đặt `AGENTEYE_DASHBOARD_URL` không chuyển hướng lại CLI; nó bị bỏ qua và lệnh âm thầm chạy so với dashboard đã lưu thay vào đó. + Các cách viết `AGENTEYE_*` của các biến này **không được `fp` đọc** và không bao giờ được — CLI khai báo `FP_*` (`fp_cli/app.py`), và một biến không xác định không phải là lỗi. Đặt `AGENTEYE_DASHBOARD_URL` không chuyển hướng CLI; nó được bỏ qua và lệnh im lặng chạy chống lại dashboard đã lưu. - `AGENTEYE_HOME` và `AGENTEYE_ENVIRONMENT` vẫn tồn tại, nhưng chúng thuộc về **collector và SDK telemetry**, không phải CLI này. + `AGENTEYE_HOME` và `AGENTEYE_ENVIRONMENT` vẫn tồn tại, nhưng chúng thuộc về **collector và telemetry SDK**, không phải CLI này. - Các lệnh xóa, thu hồi, loại bỏ, giải quyết hoặc thay thế cấu hình nhắc nhở theo mặc định. Chỉ sử dụng `--yes` sau khi xác minh tổ chức hoạt động và mục tiêu. + Các lệnh xóa, thu hồi, chặn, giải quyết, hoặc thay thế cấu hình sẽ nhắc theo mặc định. Chỉ sử dụng `--yes` sau khi xác minh tổ chức hoạt động và mục tiêu. \ No newline at end of file diff --git a/docs/vi/reference/custom-agents.mdx b/docs/vi/reference/custom-agents.mdx index 8ee20a6a..519354c9 100644 --- a/docs/vi/reference/custom-agents.mdx +++ b/docs/vi/reference/custom-agents.mdx @@ -1,21 +1,21 @@ --- title: "Custom agents" -description: "Cấu hình, danh mục sự kiện, quy tắc tương quan và gửi dữ liệu cho failproofai-sdk." +description: "Cấu hình, danh mục sự kiện, quy tắc tương quan và phân phối cho failproofai-sdk." icon: "python" --- -Tất cả những gì mỗi thiết lập, phương thức và trường làm. Nếu bạn đang điều chỉnh lần đầu tiên, hãy bắt đầu với hướng dẫn — trang này dành cho việc tra cứu. +Mỗi cài đặt, phương thức và trường làm gì. Nếu bạn lần đầu tiên cấu hình, hãy bắt đầu bằng hướng dẫn — trang này dành cho việc tra cứu. - - Cài đặt, điều chỉnh, các phương thức sự kiện, ví dụ thực tế và các vấn đề phổ biến. + + Cài đặt, cấu hình, các phương thức sự kiện, một ví dụ chi tiết và các vấn đề thường gặp. - - LangChain, CrewAI, LlamaIndex và Pydantic AI tự điều chỉnh với một cuộc gọi. + + LangChain, CrewAI, LlamaIndex và Pydantic AI tự cấu hình với một lệnh gọi. -Python 3.10 trở lên. Không có phụ thuộc runtime. +Python 3.10 hoặc mới hơn. Không có phụ thuộc thời gian chạy. ## Cài đặt @@ -23,7 +23,7 @@ Python 3.10 trở lên. Không có phụ thuộc runtime. pip install failproofai-sdk ``` -Gói được cài đặt dưới tên `failproofai-sdk` và được nhập trong Python dưới tên `failproofai_sdk`. Các add-on framework như `failproofai-sdk[langgraph]` cài đặt chính framework; các adapter luôn được đi kèm trong wheel cơ sở. +Gói được cài đặt dưới dạng `failproofai-sdk` và nhập trong Python dưới dạng `failproofai_sdk`. Các tính năng bổ sung của framework như `failproofai-sdk[langgraph]` cài đặt framework; các adapter luôn được đi kèm trong wheel cơ bản. ## Kết nối daemon Failproof @@ -31,16 +31,22 @@ Gói được cài đặt dưới tên `failproofai-sdk` và được nhập tro 1. Đi tới **Admin → Keys** và tạo một khóa với `events:add`. 2. [Kết nối daemon Failproof với Cloud](/vi/start/setup#connect-a-machine-to-cloud) trên máy agent. - 3. Chạy một phiên được điều chỉnh, sau đó tìm ID chính xác của nó trong **Observe → Events**. - 4. Đi tới **Observe → Sessions**, chọn cùng một môi trường và mở trace được tái tạo. + 3. Chạy một phiên cấu hình, sau đó tìm ID chính xác của nó trong **Observe → Events**. + 4. Đi tới **Observe → Sessions**, chọn cùng một environment, và mở trace được tái tạo. - ![Một phiên custom Python agent được tái tạo thành một biểu đồ thực thi và dấu vết sự kiện được sắp xếp.](/images/dashboard/session-detail.png) + ![Một phiên custom Python agent được tái tạo dưới dạng biểu đồ thực thi và trace sự kiện theo thứ tự.](/images/dashboard/session-detail.png) + Đọc khóa `events:add` vào shell. `read -s` nhận nó ở một lời nhắc không được hiển thị, do đó nó không bao giờ xuất hiện trong lệnh hoặc lịch sử shell: + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Sau đó thiết lập máy và kiểm tra xem nó đã kết nối: + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -58,32 +64,32 @@ failproofai_sdk.configure( ) ``` -| Đối số | Chức năng | +| Tham số | Chức năng | | --- | --- | -| `environment` | Nhãn trên mỗi sự kiện — `production`, `staging`, `prod-eu`. Mặc định là `dev`. | +| `environment` | Nhãn trên mọi sự kiện — `production`, `staging`, `prod-eu`. Mặc định là `dev`. | | `flush_interval` | Tần suất luồng nền ghi vào đĩa, tính bằng giây. Mặc định là `0.5`. | | `base_dir` | Nơi ghi. Mặc định là spool của daemon, đó là những gì bạn muốn trừ khi bạn biết cách khác. | -Đặt bằng biến môi trường thay thế: +Đặt theo biến môi trường thay thế: | Biến | Chức năng | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | Đặt `environment` mà không thay đổi mã, cho khi nhãn thuộc về triển khai hơn là ứng dụng. Một đối số `configure()` sẽ ghi đè nó. | -| `FAILPROOFAI_HOME` | Chuyển gốc Failproof AI giữ spool. | -| `FAILPROOFAI_SDK_STRICT` | `1` làm cho lỗi điều chỉnh tăng thay vì được ghi nhật ký. | +| `AGENTEYE_ENVIRONMENT` | Đặt `environment` mà không thay đổi mã, cho trường hợp nhãn thuộc về triển khai chứ không phải ứng dụng. Tham số `configure()` sẽ được ưu tiên. | +| `FAILPROOFAI_HOME` | Di chuyển gốc Failproof AI chứa spool. | +| `FAILPROOFAI_SDK_STRICT` | `1` làm cho lỗi cấu hình tăng thay vì được ghi lại. | | `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` làm cho vấn đề tương thích framework tăng thay vì cảnh báo và tiếp tục. | - **Không có dấu phẩy trong `environment`.** Ingest chia trường đó thành dấu phẩy để xây dựng các bộ lọc của nó, và bỏ qua bất kỳ sự kiện nào có nhãn chứa một sự kiện — vì vậy toàn bộ chạy im lặng biến mất. Viết `prod-eu`, không phải `prod,eu`. + **Không có dấu phẩy trong `environment`.** Ingest chia trường đó trên dấu phẩy để xây dựng các bộ lọc và bỏ qua bất kỳ sự kiện nào có nhãn chứa một — vì vậy toàn bộ lần chạy biến mất âm thầm. Viết `prod-eu`, không phải `prod,eu`. - `configure(environment="prod,eu")` tăng để bạn phát hiện ra ngay lập tức. `AGENTEYE_ENVIRONMENT` không thể tăng — không có gì gọi bạn — vì vậy nó cảnh báo một lần và quay lại `dev`. + `configure(environment="prod,eu")` tăng để bạn tìm ra ngay lập tức. `AGENTEYE_ENVIRONMENT` không thể tăng — không có gì gọi bạn — vì vậy nó cảnh báo một lần và quay lại `dev`. -Các sự kiện được xếp hàng trong bộ nhớ và được ghi trong nền mỗi `flush_interval` giây, với một lần xóa cuối cùng khi thoát trình thông dịch. Một quá trình bị giết hoàn toàn sẽ mất bất cứ điều gì chưa được viết. +Các sự kiện được xếp hàng trong bộ nhớ và được ghi ở chế độ nền mỗi `flush_interval` giây, với một lần xóa cuối cùng khi thoát thông dịch viên. Một quy trình bị giết hoàn toàn mất bất cứ điều gì chưa được ghi. ## Danh tính -Mỗi sự kiện thuộc về một phiên và một agent. **Các phạm vi điền vào cả hai**, vì vậy bạn hiếm khi vượt qua chúng: +Mỗi sự kiện thuộc về một phiên và một agent. **Các phạm vi điền cả hai**, vì vậy bạn hiếm khi chuyển chúng: ```python with failproofai_sdk.session(): @@ -91,15 +97,15 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Truyền `session_id` hoặc `agent_id` rõ ràng vẫn hoạt động và chiến thắng. Khi không có liên kết cũng không truyền, cuộc gọi tăng `TypeError` thay vì phát hành một sự kiện Cloud sẽ yên tĩnh loại bỏ. +Chuyển `session_id` hoặc `agent_id` một cách rõ ràng vẫn hoạt động và thắng. Không có cả ràng buộc lẫn được truyền, cuộc gọi tăng `TypeError` chứ không phải phát thải một sự kiện Cloud sẽ yên lặng loại bỏ. - Danh tính đi trên các biến bối cảnh. Nó theo dõi các tác vụ `asyncio` tự động, nhưng **không** luồng mới — bọc một worker trong `failproofai_sdk.propagate()` hoặc các sự kiện của nó hạ cánh không được đính kèm. + Danh tính di trên các biến ngữ cảnh. Nó theo `asyncio` tự động, nhưng **không** các luồng mới — bao quanh công nhân trong `failproofai_sdk.propagate()` hoặc sự kiện của nó hạ cánh không được gắn. ## Danh mục sự kiện -Mười lăm phương thức. Hầu hết đều có **cặp** — bạn gọi phần mở, sau đó phần đóng, và SDK đo khoảng thời gian. +Mười lăm phương thức. Hầu hết đi theo **cặp** — bạn gọi bộ mở, sau đó bộ đóng, và SDK đo khoảng thời gian. | | Mở | Đóng | | --- | --- | --- | @@ -110,11 +116,11 @@ Mười lăm phương thức. Hầu hết đều có **cặp** — bạn gọi p | **Hooks** | `hook_triggered` | `hook_completed` | | **Humans** | `human_wait` | `human_input` | -Ba người đứng một mình: `error`, `human_pause`, `human_interrupt`. +Ba tự đứng: `error`, `human_pause`, `human_interrupt`. - + -Mỗi phương thức cũng lấy `session_id` và `agent_id`, được các phạm vi điền cho bạn. Bất cứ điều gì để lại là `None` được thả bỏ thay vì được gửi dưới dạng JSON `null`, và mỗi phương thức trả về `None`. +Mỗi phương thức cũng có `session_id` và `agent_id`, mà các phạm vi điền cho bạn. Bất cứ điều gì để lại là `None` được thả ra chứ không phải được gửi dưới dạng JSON `null`, và mỗi phương thức trả về `None`. | Phương thức | Bắt buộc | Tùy chọn | | --- | --- | --- | @@ -137,14 +143,14 @@ Mỗi phương thức cũng lấy `session_id` và `agent_id`, được các ph - Để đánh dấu một chạy là thất bại, `outcome` phải là một trong `failed`, `error`, `timeout` hoặc `rejected`. Bất cứ điều gì khác — bao gồm cả lần gần phát hiểu `"failure"` — đếm là thành công. + Để đánh dấu một lần chạy là thất bại, `outcome` phải là một trong số `failed`, `error`, `timeout` hoặc `rejected`. Bất cứ điều gì khác — kể cả gần như thất bại `"failure"` — đếm là thành công. -## Ghép đôi và khoảng thời gian +## Ghép đôi và thời lượng -**Một quy tắc: cung cấp cho sự kiện đóng cùng id với phần mở của nó.** Đó là điều ghi đôi chúng, và điều cho phép SDK đo khoảng thời gian. +**Một quy tắc: cho sự kiện đóng cùng id với bộ mở của nó.** Đó là những gì ghép đôi chúng, và những gì cho phép SDK đo khoảng thời gian. -| Cặp | Phù hợp với | +| Cặp | Khớp với | | --- | --- | | `tool_use` → `tool_result` | `tool_call_id` | | `hook_triggered` → `hook_completed` | `hook_id` | @@ -152,46 +158,46 @@ Mỗi phương thức cũng lấy `session_id` và `agent_id`, được các ph | `human_wait` → `human_input` | `input_id` | | `model_request` → `model_response` | `request_id` | -**Không truyền `duration_ms` chính mình.** SDK đo nó, và truyền nó tăng `ValueError`. +**Không tự truyền `duration_ms`.** SDK đo nó, và truyền nó tăng `ValueError`. -Ngoại lệ duy nhất là `model_response`, nơi chỉ bạn biết độ trễ nhà cung cấp thực tế. Truyền toàn bộ số mili giây — một float tăng, vì cột là một số nguyên 32-bit và sẽ khác không hạ cánh trống. +Ngoại lệ duy nhất là `model_response`, nơi chỉ bạn biết độ trễ nhà cung cấp thực. Chuyển một số nguyên của mili giây — một float tăng, bởi vì cột là một số nguyên 32-bit và sẽ hạ cánh trống. -- **Ids chỉ cần duy nhất cho mỗi loại, mỗi phiên.** Một cuộc gọi công cụ và một hook có thể chia sẻ một; hai phiên chạy cùng một lúc có thể tái sử dụng cùng một ids mà không va chạm. -- **Chúng không được phạm vi để một agent.** Một cặp mở dưới một agent và đóng dưới một agent khác vẫn phù hợp — đó là trường hợp bình thường trong mã multi-agent. -- **`request_id` là tùy chọn nhưng được khuyến nghị.** Không có nó, các sự kiện mô hình ghép đôi theo thứ tự họ tới, vì vậy hai cuộc gọi đồng thời trong cùng một agent có thể ghép đôi sai. -- **Một cặp chia nhỏ trên các quá trình** vẫn khớp trong Cloud, nhưng SDK không thể đo nó — không có gì trong quá trình nào thấy cả hai nửa. -- **Tối đa 10.000 openers chờ đợi một closer cùng một lúc.** Quá mức, người già nhất bị thả, vì vậy một rò rỉ không thể phát triển mà không bị ràng buộc. +- **Id chỉ cần phải là duy nhất cho mỗi loại, mỗi phiên.** Một lệnh gọi công cụ và một móc có thể chia một; hai phiên chạy cùng lúc có thể tái sử dụng cùng các id mà không va chạm. +- **Chúng không được phạm vi vào một agent.** Một cặp mở dưới một agent và đóng dưới một agent khác vẫn khớp — đó là trường hợp bình thường trong mã đa agent. +- **`request_id` là tùy chọn nhưng được khuyến khích.** Không có nó, các sự kiện mô hình ghép đôi theo thứ tự họ tới, vì vậy hai lệnh gọi đồng thời trong cùng một agent có thể sai lệch. +- **Một cặp chia tách trên các quy trình** vẫn khớp trong Cloud, nhưng SDK không thể đo nó — không có gì trong quy trình nào thấy cả hai nửa. +- **Nhiều nhất 10,000 bộ mở chờ một bộ đóng cùng một lúc.** Quá điều đó, bộ cũ nhất bị thả, vì vậy rò rỉ không thể phát triển mà không bị ràng buộc. -## Các trường riêng của bạn +## Trường của riêng bạn -Bất kỳ từ khóa bổ sung nào bạn truyền được lưu trữ với sự kiện: +Bất kỳ từ khóa bổ sung nào bạn chuyển được lưu trữ với sự kiện: ```python failproofai_sdk.event.tool_use( tool_name="search", tool_call_id="c1", - fw_tenant="acme", fw_region="eu-west-1", # của bạn riêng + fw_tenant="acme", fw_region="eu-west-1", # của bạn ) ``` -Thích loại JSON nếu bạn muốn truy vấn chúng sau này. Bất cứ điều gì khác — một UUID, một datetime, một `Decimal`, một set, bytes, một đối tượng mô hình — được lưu trữ dưới dạng chuỗi. +Ưu tiên các loại JSON nếu bạn muốn truy vấn chúng sau này. Bất cứ điều gì khác — một UUID, một datetime, một `Decimal`, một tập hợp, byte, một đối tượng mô hình — được lưu trữ dưới dạng chuỗi. - **Tiền tố tên trường của bạn.** Extras được áp dụng cuối cùng, vì vậy một trường được gọi là `model`, `tool_name` hoặc `outcome` yên tĩnh ghi đè lên một thực tế. Các adapter framework sử dụng `fw_`; làm như vậy và không có gì có thể va chạm. + **Tiền tố tên trường của bạn.** Các cái bổ sung được áp dụng cuối cùng, vì vậy một trường được gọi là `model`, `tool_name` hoặc `outcome` yên lặng ghi đè trường thực. Các adapter framework sử dụng `fw_`; làm như vậy và không có gì có thể va chạm. - Đây cũng là lý do tại sao một trường tùy chọn được viết sai không bao giờ lỗi — nó chỉ trở thành một trường tùy chỉnh mới. Nếu một trường tiêu chuẩn bị thiếu trong Cloud, hãy kiểm tra chính tả trước tiên. + Đây cũng là lý do tại sao một trường tùy chọn sai chính tả không bao giờ xảy ra lỗi — nó chỉ trở thành một trường tùy chỉnh mới. Nếu một trường tiêu chuẩn bị thiếu trong Cloud, kiểm tra chính tả trước tiên. Năm tên này được dành riêng và bị từ chối hoàn toàn: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. -## Gửi dữ liệu và xác minh +## Phân phối và xác minh - Trong **Observe → Events**, xác minh `agent_start` tồn tại trước tiên và `agent_end` tồn tại cuối cùng. Sau đó mở **Observe → Sessions** và xác nhận các sự kiện mô hình, công cụ, con người, hook và lỗi xuất hiện theo thứ tự dự định. Sử dụng ID phiên làm khóa khắc phục sự cố chính. + Trong **Observe → Events**, xác minh `agent_start` tồn tại trước tiên và `agent_end` tồn tại cuối cùng. Sau đó mở **Observe → Sessions** và xác nhận các sự kiện mô hình, công cụ, con người, móc và lỗi xuất hiện theo thứ tự dự định. Sử dụng ID phiên làm khóa khắc phục sự cố chính. ```bash @@ -203,14 +209,14 @@ Năm tên này được dành riêng và bị từ chối hoàn toàn: `timestam -Nếu Cloud trống, hãy kiểm tra `$FAILPROOFAI_HOME/custom-agents/events`, nếu không thì `~/.failproofai/custom-agents/events`. Các tệp JSONL chứng minh phát hành SDK; một spool phát triển chỉ đến cấu hình daemon hoặc gửi dữ liệu, trong khi một spool trống chỉ đến điều chỉnh hoặc thời lượng quá trình. +Nếu Cloud trống, kiểm tra `$FAILPROOFAI_HOME/custom-agents/events`, nếu không `~/.failproofai/custom-agents/events`. Các tệp JSONL chứng minh phát thải SDK; một spool phát triển trỏ đến cấu hình daemon hoặc phân phối, trong khi một spool trống trỏ đến cấu hình hoặc thời lượng quá trình. - Chỉ kiểm tra spool khi daemon bị dừng. Khi nó chạy, nó thu thập và xóa từng batch trong vòng mili giây, vì vậy danh sách thư mục đua với bộ sưu tập và hiển thị ít sự kiện hơn nhiều so với những gì được phát hành. + Chỉ kiểm tra spool khi daemon được dừng. Khi nó chạy, nó thu thập và xóa mỗi lô trong vài mili giây, vì vậy danh sách thư mục đua với bộ sưu tập và hiển thị ít sự kiện hơn nhiều so với sự kiện được phát thải. -## Ngăn chặn lỗi trong runtime tùy chỉnh +## Ngăn ngừa lỗi trong thời gian chạy tùy chỉnh -Sử dụng các phát hiện kiểm tra và dấu vết được liên kết để xác định hành động không an toàn, bằng chứng bắt buộc và phản ứng dự định. Một tích hợp thực thi tùy chỉnh phải tiếp xúc hành động trước khi thực thi, chuyển đầu vào có cấu trúc của nó cho công cụ chính sách và áp dụng quyết định allow, instruct hoặc deny kết quả. +Sử dụng các phát hiện kiểm toán và các trace được liên kết để xác định hành động không an toàn, bằng chứng bắt buộc và phản ứng dự định. Một tích hợp thực thi tùy chỉnh phải hiển thị hành động trước khi thực thi, chuyển đầu vào có cấu trúc của nó đến công cụ chính sách và áp dụng quyết định cho phép, hướng dẫn hoặc từ chối kết quả. -[Liên hệ Failproof AI](mailto:support@befailproof.ai) và chúng tôi sẽ giúp bạn ánh xạ các ranh giới mô hình, công cụ và chu kỳ sống của runtime của bạn với các hook chính sách, sau đó xác thực tích hợp với bạn. \ No newline at end of file +[Liên hệ Failproof AI](mailto:support@befailproof.ai) và chúng tôi sẽ giúp bạn ánh xạ các ranh giới mô hình, công cụ và vòng đời của thời gian chạy của bạn tới các móc chính sách, sau đó xác thực tích hợp với bạn. \ No newline at end of file diff --git a/docs/vi/reference/evaluator-sdk.mdx b/docs/vi/reference/evaluator-sdk.mdx index a3fc314c..b84acdfe 100644 --- a/docs/vi/reference/evaluator-sdk.mdx +++ b/docs/vi/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "Xây dựng một dịch vụ để đánh giá các phiên làm việc của Failproof AI một cách đồng bộ hoặc không đồng bộ." +description: "Chạy worker đánh giá của riêng bạn, cho các LLM judges và bất cứ điều gì mà hosted Python không thể làm." icon: "gauge" --- -Một evaluator nhận một phiên agent đã hoàn thành và trả về các tín hiệu chất lượng mà bạn quan tâm: điểm số, lời giải thích cho từng điểm số và tóm tắt tùy chọn. Failproof AI lưu trữ các kết quả này bên cạnh trace và hiển thị biểu đồ chúng trên các agent và môi trường. +Evaluator SDK chạy các đánh giá trên cơ sở hạ tầng của riêng bạn. Worker của bạn đăng ký các đánh giá của nó với Failproof AI, nhận các phiên khi chúng hoàn thành, chấm điểm chúng, và gửi kết quả, tất cả qua HTTPS đi ra: không có gì kết nối vào nó. Sử dụng nó cho những điều mà [hosted Python](/vi/evaluations/write) không thể làm — LLM judges, lệnh gọi mô hình, các gói, secrets, và truy cập mạng. Các kết quả của nó xuất hiện bên cạnh các kết quả hosted trên [trang evaluations](/vi/sessions/evaluations), được gắn thẻ **customer**. -## Thiết lập một evaluator +Nó được cung cấp trong `failproofai-sdk`, dưới `failproofai_sdk.evaluator`; nhập SDK tracing không tải nó. - - - Cài đặt SDK và máy chủ được sử dụng để chạy nó. - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - Tạo `evaluator.py`. Ví dụ này kiểm tra xem một phiên có chứa bất kỳ lỗi gọi công cụ nào không. - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - Đặt một token được chia sẻ, khởi động evaluator và xác nhận rằng điểm cuối health của nó phản hồi. - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - Trong một terminal khác: - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## Kết nối evaluator với Failproof AI - -1. Triển khai evaluator tại một URL HTTPS có thể truy cập được bởi Failproof AI Cloud. -2. Cấu hình `EVALUATOR_ENDPOINT` với URL đó và đặt `EVALUATOR_TOKEN` thành token giống nhau được sử dụng bởi evaluator. Để sử dụng Cloud được quản lý, liên hệ [support@befailproof.ai](mailto:support@befailproof.ai) để cấu hình kết nối. -3. Chạy một đánh giá và xác nhận rằng các điểm số của nó xuất hiện trong Failproof AI. - - - - Mở một phiên đã hoàn thành trong **Observe → Sessions** và chọn **Run evaluation** nếu nó chưa được đánh giá tự động. Xem lại trạng thái, điểm số, lý do đưa ra và tóm tắt trong bảng **Evaluation** của phiên. - - Sử dụng **Observe → Evaluations** để so sánh điểm số trên các agent hoặc môi trường. Sử dụng **Observe → Metrics** để đo lường độ trễ, chi phí, token và các phép đo số khác. - - Bắt đầu với một phiên để xác nhận rằng evaluator đã trả về các khóa điểm số dự kiến và lý do hữu ích cho lần chạy cụ thể đó. - - ![Chế độ xem chi tiết phiên hiển thị các điểm số đánh giá và lý do bên cạnh trace của nó.](/images/dashboard/session-detail.png) +```bash +pip install failproofai-sdk +``` - Khi các kết quả riêng lẻ trông chính xác, sử dụng bảng điều khiển đánh giá để so sánh các điểm số đó theo thời gian và trên các agent hoặc môi trường. +## Viết các evaluations - ![Bảng điều khiển chất lượng hiển thị các điểm số evaluator theo thời gian.](/images/dashboard/dashboard-quality.png) +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - Biểu đồ lành mạnh sẽ sử dụng tên điểm số ổn định; thay đổi khóa sẽ tạo một chuỗi riêng biệt. - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - -Đối với một instance Cloud tự lưu trữ, đánh giá tự động bị tắt cho đến khi `EVALUATOR_ENDPOINT` được đặt trên quy trình máy chủ. Khởi động lại máy chủ sau khi thay đổi các biến môi trường evaluator. +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` -Dịch vụ này hiển thị `GET /health`, `GET /config`, `POST /evaluate` và tùy chọn `GET /evaluate/{job_id}`. Trả về `JobPending` cho công việc không đồng bộ và đăng ký `@app.job_lookup` để Failproof AI có thể thăm dò nó. +- `@app.eval(key, version=...)` đăng ký một evaluation. Key là thứ mà các kết quả của nó được biểu diễn; thay đổi phiên bản bất cứ khi nào logic thay đổi, và mỗi kết quả giữ phiên bản đã tạo ra nó. Một worker chứa tối đa 100 evaluations. +- `result_kind` là `"score"` trừ khi bạn nói cách khác. Đối với một evaluation `"metric"` hoặc `"assertion"`, đặt tên một mục `metrics` hoặc `assertions` theo key: mục đó là kết quả của nó. +- `when` quyết định xem một phiên có áp dụng hay không. Trả về `ConditionResult(False, "")` để bỏ qua một phiên, và lý do được ghi lại. +- Một evaluation có thể là một hàm thông thường hoặc `async`, và `timeout_seconds` giới hạn nó. +- Các khóa payload — `tool_name`, `response`, và `content` ở trên — là bất cứ thứ gì agents của bạn gửi, vì vậy hãy đọc chúng từ một phiên thực. -Khi một token được cấu hình, tất cả các tuyến đường ngoại trừ health yêu cầu token bearer giống nhau mà Failproof AI gửi là `EVALUATOR_TOKEN`. +## Chạy worker -## Các loại SDK +Đặt một khóa với quyền `evaluations:run`, được tạo dưới **Administration → Keys**, trong `FAILPROOFAI_EVALUATOR_TOKEN` — đặt nó từ secret store của bạn thay vì gõ nó vào một lệnh — và khởi động worker: -| Type | Fields | -| --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -## Decorators và routes +Không có khối `__main__`, `python -m failproofai_sdk.evaluator evaluator:app` làm điều tương tự. -| Decorator | Route | Required | +| Biến | Mặc định | Mục đích | | --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | Yes | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | Khi trả về `JobPending` | -| `@app.config` | `GET /config` | No | - -SDK giới hạn các phần thân yêu cầu đánh giá ở 25 MiB. Các trường yêu cầu không xác định sẽ bị bỏ qua để các dịch vụ vẫn tương thích khi hợp đồng sự kiện phát triển. +| `FAILPROOFAI_EVALUATOR_URL` | bắt buộc | Nơi Failproof AI: `https://app.befailproof.ai` cho Cloud. HTTPS trừ khi nó trỏ tới loopback | +| `FAILPROOFAI_EVALUATOR_TOKEN` | bắt buộc | Một khóa có `evaluations:run` | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | Đặt tên cho worker này | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | Số phiên mà worker này chấm điểm cùng một lúc | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | Timeout cho mỗi yêu cầu tới Failproof AI | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | Thời gian một worker dừng chờ các chạy đang thực hiện | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | Cho phép HTTP thường cho một URL không phải loopback — xem cảnh báo bên dưới | +| `FAILPROOFAI_EVALUATOR_MODULE` | none | Cái `module:attribute` cho `python -m failproofai_sdk.evaluator` | + + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` gửi mọi thứ ở dạng plaintext. Worker mang `FAILPROOFAI_EVALUATOR_TOKEN` như một header `Authorization: Bearer` trên mỗi yêu cầu, và các bản ghi mà nó tìm nạp là các phiên themselves — vì vậy bất cứ ai trên đường đi đều đọc được cả hai, và token mà họ đọc được sẽ chạy các evaluations cho đến khi bạn xoay nó. Chỉ sử dụng nó trên một mạng phát triển bị cô lập. Ở bất kỳ nơi nào khác URL phải là HTTPS; loopback không cần cờ. + + +## Các loại kết quả + +| Loại | Trường | +| --- | --- | +| `Score` | `value` (0 tới 1), `passed`, `unit` (mặc định `ratio`), `display_value`, `description` | +| `Metric` | `value`, `unit`, `display_value`, `description` | +| `Assertion` | `passed`, `description` | +| `EvalResult` | `score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels` | +| `ConditionResult` | `applicable`, `reason_code` | -## Trả về công việc không đồng bộ +Một `EvalResult` mang ít nhất một score, metric, hoặc assertion, và tối đa 25, mỗi cái dưới một khóa duy nhất. -Sử dụng `JobPending` khi đánh giá không thể hoàn thành trong một yêu cầu. ID công việc là opaque đối với Failproof AI và phải vẫn có thể được giải quyết bởi dịch vụ của bạn cho đến khi kết quả được thu thập hoặc hết thời gian chờ máy chủ. +## Phiên -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| Trường hoặc phương thức | Cung cấp cho bạn | +| --- | --- | +| `session_id`, `agent_id`, `environment` | Nhận dạng của phiên | +| `started_at`, `ended_at` | Khi nó bắt đầu và kết thúc | +| `event_count`, `events` | Bảng ghi đầy đủ, có thứ tự | +| `count(event_type)` | Số lượng sự kiện của loại đó mà nó chứa | +| `events_of_type(event_type)` | Những sự kiện đó, theo thứ tự | -Tần suất thăm dò được chọn theo thứ tự này: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs`, sau đó là `EVALUATOR_POLLING_INTERVAL_SECS` của máy chủ. Các giá trị được giới hạn từ 1 giây đến 1 giờ. Giới hạn thăm dò wall-clock mặc định của máy chủ là một giờ. +Mỗi sự kiện mang `id`, `ts`, `event_type`, và `payload`. -## Các trường yêu cầu và phản hồi +## Evaluator cũ -| Field | Type | Notes | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | Hiện tại là `"1"`. | -| `session_id`, `agent_id`, `environment` | `str` | Nhận dạng phiên và môi trường. | -| `started_at` | `datetime` | Dấu thời gian của sự kiện đầu tiên. | -| `ended_at` | `datetime \| None` | Có mặt khi phiên phát ra sự kiện kết thúc. | -| `events` | `list[AgentEvent]` | Luồng sự kiện được sắp xếp đầy đủ. | -| `AgentEvent.id` | `int` | Định danh hàng sự kiện backend. | -| `AgentEvent.ts` | `datetime` | Dấu thời gian sự kiện. | -| `AgentEvent.event_type` | `str` | Họ sự kiện như `tool_use`. | -| `AgentEvent.payload` | `dict[str, Any]` | Tải trọng sự kiện hoàn chỉnh. | -| `EvalResponse.scores` | `dict[str, float] \| None` | Các chiều số được hiển thị trong đánh giá. | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | Giải thích cho từng điểm; các khóa phải phản ánh `scores`. | -| `EvalResponse.summary` | `str \| None` | Tường thuật đánh giá tổng thể. | - -## Cài đặt của người vận hành máy chủ - -Đánh giá tự động là toàn bộ triển khai và vẫn bị tắt khi `EVALUATOR_ENDPOINT` vắng mặt. - -| Variable | Default | Purpose | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | unset | URL cơ sở của dịch vụ evaluator. | -| `EVALUATOR_TOKEN` | unset | Token bearer được chia sẻ với `Evaluator(token=...)`. | -| `EVALUATOR_WORKERS` | `2` | Công nhân trình phân phối đồng thời. | -| `EVALUATOR_CLAIM_BATCH` | `4` | Phiên được yêu cầu trên mỗi lần chuyển trình phân phối. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Tần suất thăm dò không đồng bộ dự phòng. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Thời gian chờ evaluator cho mỗi yêu cầu. | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | Nỗ lực cung cấp trước lỗi terminal. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | Tần suất làm mới cho `/config`. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Thời gian thăm dò không đồng bộ wall-clock tối đa. | - -Máy chủ cũng có thể hạn chế những tổ chức nào sử dụng evaluator toàn cầu triển khai. Xử lý điểm cuối, token, thử lại và thay đổi cổng tổ chức như cấu hình người vận hành và khởi động lại hoặc cuộn máy chủ sau khi thay đổi chúng. - -## Bảo mật và hoạt động - -- Đặt evaluator đằng sau HTTPS khi traffic vượt qua ranh giới mạng đáng tin cậy. -- Cấu hình token bearer không rỗng và giữ nó giống nhau trên cả hai dịch vụ. -- Không ghi log token hoặc toàn bộ prompts nhạy cảm từ tải trọng yêu cầu. -- Làm cho các trình xử lý đồng bộ idempotent; các lần thử lại có thể lặp lại một yêu cầu. -- Duy trì trạng thái công việc không đồng bộ bên ngoài bộ nhớ quy trình trong production. -- Trả về các khóa điểm số ổn định. Đổi tên khóa sẽ tạo một chuỗi biểu đồ mới thay vì thay đổi khóa cũ. - -SDK phát hành các log lifecycle có cấu trúc như `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` và ngoại lệ trình xử lý. Nó không cấu hình các trình xử lý logging; sử dụng cấu hình logging của ứng dụng chủ. \ No newline at end of file +Evaluator SDK trước đó — một dịch vụ HTTP mà Failproof AI gọi tại `EVALUATOR_ENDPOINT`, trả lời `/evaluate` và được thăm dò qua `JobPending` — đã bị loại bỏ. Xây dựng các evaluator mới trên worker này; các nhà khai thác một instance tự lưu trữ chạy một dịch vụ cũ có thể giữ nó qua quá trình chuyển đổi. \ No newline at end of file diff --git a/docs/vi/reference/failproof-cli.mdx b/docs/vi/reference/failproof-cli.mdx index efb8a14b..14e1761c 100644 --- a/docs/vi/reference/failproof-cli.mdx +++ b/docs/vi/reference/failproof-cli.mdx @@ -4,83 +4,101 @@ description: "Cài đặt hooks, quản lý chính sách cục bộ, kết nối icon: "terminal" --- -Cài đặt CLI cục bộ với `npm install -g failproofai`. Chạy mà không có tham số để mở bảng điều khiển chính sách cục bộ. +Cài đặt CLI cục bộ với `npm install -g failproofai`. Chạy nó mà không có đối số để mở bảng điều khiển chính sách cục bộ. -Gói này yêu cầu Node.js 20.9 trở lên. Bun 1.3 trở lên được hỗ trợ cho phát triển và cài đặt từ nguồn. `failproofai configure` và `failproofai setup` là bí danh cho `failproofai config`; `failproofai p` là bí danh cho `failproofai policies`. +Gói yêu cầu Node.js 20.9 hoặc mới hơn. Bun 1.3 hoặc mới hơn được hỗ trợ để phát triển và cài đặt từ mã nguồn. `failproofai configure` và `failproofai setup` là bí danh cho `failproofai config`. `failproofai policy`, `failproofai pack` và `failproofai p` đều là cách viết của `failproofai policies` — các gói và chính sách riêng lẻ trước đây là ba lệnh cho một ý tưởng và bây giờ là một. Các cách viết cũ vẫn hoạt động, ngoại trừ hai trường hợp: `pack list ` hiện là `policies show `, và `pack build` hiện là `publish`. -## Thiết lập một máy +## Thiết lập máy + +Cài đặt CLI, sau đó đọc khóa máy vào shell. `read -s` nhận nó tại lệnh nhắc không hiển thị, do đó nó không bao giờ xuất hiện trong một lệnh: ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +Sau đó thiết lập máy và chọn những gì nó sẽ thực thi: + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` -Chạy `failproofai` mà không có tham số để mở bảng điều khiển chính sách cục bộ. +`failproofai config` là toàn bộ thiết lập: nó cài đặt dịch vụ `failproofaid` (root một lần, thông qua `sudo -n` — không bao giờ là lệnh nhắc mật khẩu tương tác), kết nối hooks vào mọi agent CLI mà nó tìm thấy, và kết nối với Cloud khi có khóa. Không có terminal — CI, container, agent điều hành nó — nó áp dụng thay vì hỏi, và thoát với mã 1 nếu bất cứ điều gì được yêu cầu không xảy ra. + +Nó không chọn bất kỳ chính sách nào. Đó là công việc của lệnh thứ hai, và nếu không có nó, một máy vừa được cấu hình không thực thi gì ngoài công cụ bảo vệ luôn bật. + +Ưu tiên biến môi trường hơn `--token`: một đối số dòng lệnh có thể đọc được từ `ps` bởi mọi người dùng trên máy. Đó là tất cả những gì biến bảo vệ — một khóa được nhập vào bất kỳ lệnh nào, `export` bao gồm, vẫn xuất hiện trong lịch sử shell, đó là lý do tại sao nó được đọc bằng `read -s` ở trên. Trong CI, đặt nó từ kho bí mật và tắt theo dõi shell (`set -x`), nếu không theo dõi sẽ in nó. + + + `--connect ` ghi danh một máy đã được **thiết lập**. Nó trả lại ngay khi ghi danh thành công — nó không cài đặt daemon và không kết nối bất kỳ hooks nào. Sử dụng `failproofai config` thuần túy (hoặc `failproofai config --token `) trên một máy chưa được thiết lập, nếu không nó sẽ được đọc là đã kết nối trong khi không thu thập và thực thi gì cả. + + +Chạy `failproofai` mà không có đối số để mở bảng điều khiển chính sách cục bộ. | Lệnh | Kết quả | | --- | --- | -| `failproofai config` | Chạy thiết lập máy tương tác | -| `failproofai config --connect --token ` | Kết nối Cloud ingestion và phân phối chính sách | -| `failproofai config --status` | Hiển thị trạng thái kết nối, daemon, phân phối và tạm dừng | -| `failproofai policies` | Liệt kê chính sách tích hợp sẵn, tùy chỉnh, quy ước, gói và được quản lý bởi Cloud | -| `failproofai policies --install` | Cài đặt hooks và bật chính sách | -| `failproofai policy add ` | Bật một chính sách — một tích hợp sẵn, hoặc `:` từ một gói đã cài đặt | -| `failproofai policy remove ` | Tắt một chính sách, cách đặt tên giống nhau | -| `failproofai policies --uninstall` | Tắt chính sách hoặc loại bỏ hooks harness | -| `failproofai pack list` | Liệt kê các gói chính sách đã cài đặt và mỗi chính sách mà chúng có | -| `failproofai pack add ` | Cài đặt một gói chính sách từ bản phát hành GitHub; không có thẻ sẽ lấy phiên bản mới nhất và ghim nó | -| `failproofai pack add --bundled` | Cài đặt chính sách tích hợp sẵn dưới dạng gói, từ gói này, không có mạng | -| `failproofai pack build ` | Xây dựng ba tài sản phát hành cho gói của riêng bạn | -| `failproofai pack remove ` | Hủy kích hoạt một gói đã cài đặt | -| `failproofai audit` | Quét lịch sử agent cục bộ và mở chế độ xem audit cục bộ | -| `failproofai audit --schedule [days] --email
` | Lên lịch quét cục bộ định kỳ và gửi email các kết quả của chúng | -| `failproofai audit --status` | Hiển thị địa chỉ báo cáo, khoảng thời gian và quét được lên lịch tiếp theo | -| `failproofai audit --no-schedule` | Dừng quét định kỳ mà không xóa lịch sử audit | -| `failproofai harness list` | Liệt kê các đường dẫn chụp bổ sung | -| `failproofai flush --wait` | Phân phối spooler sự kiện hiện tại | +| `failproofai config` | Thiết lập máy: agent, daemon, và Cloud khi có khóa | +| `failproofai config --token ` | Thiết lập và kết nối trong một lần, không hỏi gì | +| `failproofai config --connect ` | Ghi danh một máy **đã** được thiết lập — không daemon, không hooks | +| `failproofai config --status` | Hiển thị kết nối, daemon, truyền tải và trạng thái tạm dừng | +| `failproofai policies` | Liệt kê các chính sách tích hợp, tùy chỉnh, quy ước, gói và được quản lý bởi Cloud | +| `failproofai policies --install` | Kết nối hooks vào agent CLI của bạn. Không bật bất kỳ chính sách nào riêng lẻ | +| `failproofai policies add ` | Bật một chính sách — một tích hợp, hoặc `:` từ một gói đã cài đặt | +| `failproofai policies remove ` | Tắt một chính sách, cách đặt tên tương tự | +| `failproofai policies --uninstall` | Tắt chính sách hoặc loại bỏ hooks của harness | +| `failproofai policies show /` | Những gì một gói mang theo, đọc từ tệp kê khai của nó, trước khi bạn lấy nó | +| `failproofai policies show / --releases` | Mọi phiên bản nó đã xuất bản, và phiên bản nào ở đây | +| `failproofai policies add ` | Cài đặt một gói chính sách từ bản phát hành GitHub; không có thẻ nhận phiên bản mới nhất và ghim nó | +| `failproofai publish` | Vận chuyển các chính sách của riêng bạn dưới dạng một gói; `--init` viết một để bắt đầu | +| `failproofai policies remove ` | Gỡ cài đặt một gói | +| `failproofai audit` | Quét lịch sử agent cục bộ và mở chế độ xem kiểm tra cục bộ | +| `failproofai audit --schedule [days] --email
` | Lên lịch quét cục bộ định kỳ và gửi email kết quả của chúng | +| `failproofai audit --status` | Hiển thị địa chỉ báo cáo, khoảng thời gian và quét tiếp theo được lên lịch | +| `failproofai audit --no-schedule` | Dừng quét định kỳ mà không xóa lịch sử kiểm tra | +| `failproofai harness list` | Liệt kê các đường dẫn nắm bắt bổ sung | +| `failproofai flush --wait` | Truyền tải spool sự kiện hiện tại | | `failproofai backfill --since 30d` | Đọc lại lịch sử đã vượt qua trước đó | | `failproofai config --pause [duration]` | Tạm dừng một phiên cục bộ trong 30 phút theo mặc định, tối đa 8 giờ | -| `failproofai config --resume` | Tiếp tục một phiên cục bộ tạm dừng; thêm `--all` để xóa tất cả các tạm dừng | +| `failproofai config --resume` | Tiếp tục một phiên cục bộ đã tạm dừng; thêm `--all` để xóa tất cả các lần tạm dừng | | `failproofai update` | Hoàn thành di chuyển gói và cập nhật daemon | -| `failproofai migrate --dry-run` | Xem trước hoặc chạy các di chuyển bố cục nhà chờ xử lý | +| `failproofai migrate --dry-run` | Xem trước hoặc chạy các di chuyển bố cục nhà chờ | | `failproofai uninstall` | Loại bỏ hooks và daemon trước khi loại bỏ gói | | `failproofai --version` | In phiên bản gói được cài đặt | -| `failproofai --help` | Hiển thị lệnh và cách sử dụng chung | +| `failproofai --help` | Hiển thị lệnh và cách sử dụng toàn cầu | ## Cờ cấu hình | Cờ | Sử dụng | | --- | --- | -| `--connect --token ` | Kết nối không tương tác | +| `--token ` | Thiết lập và kết nối không tương tác; cũng đọc từ `FAILPROOFAI_CLOUD_TOKEN` | +| `--url ` | Kết nối ở nơi khác ngoài `app.befailproof.ai`; cũng đọc từ `FAILPROOFAI_CLOUD_URL` | +| `--connect ` | Chỉ ghi danh, trên một máy đã được thiết lập. Bỏ qua daemon và mọi hook | | `--machine-id ` | Đặt ID máy ổn định | -| `--machine-label ` | Đặt hoặc thay đổi nhãn bảng điều khiển | -| `--no-transcripts` | Gửi quyết định mà không có nội dung bản ghi | -| `--disconnect` | Dừng kéo chính sách Cloud và phân phối sự kiện | +| `--machine-label ` | Đổi tên một máy **đã** được kết nối. Riêng lẻ, nó không bao giờ chạy thiết lập, vì vậy hãy đặt nó sau `failproofai config`, không phải trong | +| `--no-transcripts` | Gửi quyết định mà không có nội dung bảng điểm | +| `--disconnect` | Dừng kéo chính sách Cloud và truyền tải sự kiện | | `--status` | Hiển thị trạng thái máy hiện tại | | `--pause [duration]` | Tạm dừng phiên mới nhất trong thư mục hiện tại; chấp nhận giây, phút hoặc giờ và mặc định là 30 phút | -| `--resume` | Kết thúc một tạm dừng phù hợp sớm | +| `--resume` | Kết thúc một lần tạm dừng khớp sớm | | `--session ` | Nhắm mục tiêu một phiên rõ ràng để tạm dừng hoặc tiếp tục | -| `--all` | Với `--resume`, kết thúc mọi tạm dừng hoạt động | +| `--all` | Với `--resume`, kết thúc mọi lần tạm dừng đang hoạt động | -Tạm dừng cục bộ tạm ngừng chính sách tích hợp sẵn, tùy chỉnh, quy ước và gói cho một phiên. Chúng luôn hết hạn và không vô hiệu hóa chính sách được quản lý bởi Cloud. `block-failproofai-commands` — luôn bật và không thể bị vô hiệu hóa hoặc tạm dừng chính nó — ngăn chặn một agent được cấy dòng sử dụng lối thoát này. +Các lần tạm dừng cục bộ tạm dừng chính sách tích hợp, tùy chỉnh, quy ước và gói cho một phiên. Chúng luôn hết hạn và không vô hiệu hóa các chính sách được quản lý bởi Cloud. `block-failproofai-commands` — luôn bật và không thể bị vô hiệu hóa hoặc tạm dừng — ngăn một agent được nhập chứng từ sử dụng cách thoát này. ## Cờ chính sách | Cờ | Sử dụng | | --- | --- | -| `--install`, `-i` | Bật chính sách và cài đặt hooks harness | +| `--install`, `-i` | Cài đặt hooks harness. Các tên sau đó bật các chính sách đó; không có gì, không có thay đổi chính sách | | `--uninstall`, `-u` | Tắt chính sách hoặc loại bỏ hooks | | `--cli ` | Nhắm mục tiêu một hoặc nhiều harness được hỗ trợ | | `--scope user\|project\|local\|all` | Chọn phạm vi cấu hình; `all` dành cho gỡ cài đặt | | `--beta` | Bao gồm các chính sách beta | | `--custom`, `-c ` | Xác thực và tải tệp chính sách tùy chỉnh; có thể lặp lại | -## Cờ phân phối và bảo trì +## Cờ truyền tải và bảo trì | Lệnh | Cờ | | --- | --- | @@ -90,7 +108,7 @@ Tạm dừng cục bộ tạm ngừng chính sách tích hợp sẵn, tùy chỉ | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` nên được chạy sau `npm install -g failproofai@latest`; nó thực hiện di chuyển bố cục nhà, cài đặt nhị phân daemon phù hợp và khởi động lại dịch vụ. `--no-daemon` chỉ thực hiện di chuyển bố cục. +`failproofai update` nên được chạy sau `npm install -g failproofai@latest`; nó thực hiện di chuyển bố cục nhà, cài đặt tệp nhị phân daemon phù hợp, và khởi động lại dịch vụ. `--no-daemon` chỉ thực hiện di chuyển bố cục. ## Đường dẫn harness @@ -100,11 +118,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -Các tên harness được hỗ trợ là `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` và `goose`. +Tên harness được hỗ trợ là `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, và `goose`. -Nhãn không gian ID agent dẫn xuất khi hai gốc chứa bản sao của cùng một dự án. Các gốc chồng chéo và nhãn trùng lặp bị từ chối để ngăn chặn thu thập trùng lặp hoặc hỏng con trỏ. Cấu hình đường dẫn bổ sung tải lại mà không cần khởi động lại daemon. +Nhãn không gian ID agent xuất phát khi hai gốc chứa bản sao của cùng một dự án. Gốc chồng chéo và nhãn trùng lặp bị từ chối để ngăn chặn bộ sưu tập trùng lặp hoặc hỏng con trỏ. Cấu hình đường dẫn bổ sung được tải lại mà không cần khởi động lại daemon. -Các môi trường vùng chứa có thể thay thế các đường dẫn bổ sung được cấu hình bằng tệp bằng một biến được phân tách bằng dấu phẩy được đặt tên `FAILPROOFAI__EXTRA_PATHS`, ví dụ: +Các môi trường vùng chứa có thể thay thế các đường dẫn bổ sung được cấu hình tệp bằng biến được phân tách bằng dấu phẩy có tên `FAILPROOFAI__EXTRA_PATHS`, ví dụ: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -112,28 +130,30 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Biến môi trường -Sử dụng tệp cấu hình cho hành vi máy liên tục. Các biến môi trường rất hữu ích cho các vùng chứa, bài kiểm tra và một quy trình. +Sử dụng tệp cấu hình cho hành vi máy liên tục. Các biến môi trường hữu ích nhất cho vùng chứa, bài kiểm tra và một quy trình. | Biến | Sử dụng | | --- | --- | -| `FAILPROOFAI_HOME` | Chuyển bố cục `~/.failproofai` hoàn chỉnh | -| `FAILPROOFAI_LOG_LEVEL` | Đặt mức chi tiết đăng nhập cục bộ | -| `FAILPROOFAI_HOOK_LOG_FILE` | Viết chẩn đoán hook vào một tệp được chọn | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Tắt telemetry ẩn danh cho quy trình này | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Bỏ qua thiết lập chạy lần đầu tương tác | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Bỏ qua audit cục bộ sau thiết lập | -| `FAILPROOFAI_LLM_BASE_URL` | Ghi đè điểm cuối tương thích với OpenAI được sử dụng bởi chính sách LLM | -| `FAILPROOFAI_LLM_API_KEY` | Cung cấp khóa API được sử dụng bởi chính sách LLM | -| `FAILPROOFAI_LLM_MODEL` | Chọn mô hình được sử dụng bởi chính sách LLM | +| `FAILPROOFAI_CLOUD_TOKEN` | Khóa Cloud, thay vì `--token`. Ưu tiên cái này: một đối số có thể đọc được từ `ps` bởi mọi người dùng. Đặt nó bằng `read -s` hoặc từ kho bí mật CI, không bao giờ bằng cách nhập khóa vào một lệnh, nó xuất hiện trong lịch sử shell đều như vậy | +| `FAILPROOFAI_CLOUD_URL` | URL Cloud, thay vì `--url`. Cùng biến mà daemon đọc | +| `FAILPROOFAI_HOME` | Dịch chuyển bố cục `~/.failproofai` hoàn chỉnh | +| `FAILPROOFAI_LOG_LEVEL` | Đặt chi tiết ghi nhật ký cục bộ | +| `FAILPROOFAI_HOOK_LOG_FILE` | Viết chẩn đoán hook vào tệp được chọn | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Vô hiệu hóa telemetry ẩn danh cho quy trình này | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Bỏ qua thiết lập lần đầu chạy tương tác | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Bỏ qua kiểm tra cục bộ sau thiết lập | +| `FAILPROOFAI_LLM_BASE_URL` | Ghi đè điểm cuối tương thích OpenAI được sử dụng bởi các chính sách LLM | +| `FAILPROOFAI_LLM_API_KEY` | Cung cấp khóa API được sử dụng bởi các chính sách LLM | +| `FAILPROOFAI_LLM_MODEL` | Chọn mô hình được sử dụng bởi các chính sách LLM | | `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Ràng buộc tải mô-đun chính sách tùy chỉnh | -| `FAILPROOFAI_NO_DOWNLOAD=1` | Từ chối tìm nạp gói và nhị phân daemon; những gì được cài đặt tiếp tục thực thi | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Từ chối tìm nạp gói và tệp nhị phân daemon; những gì được cài đặt tiếp tục thực thi | | `FAILPROOFAI_PACK_BASE_URL` | Tìm nạp gói từ một bản sao thay vì `github.com` | -| `FAILPROOFAI__EXTRA_PATHS` | Thay thế các đường dẫn chụp bổ sung được cấu hình cho một harness | -| `NO_COLOR` | Tắt đầu ra thiết bị đầu cuối có màu | +| `FAILPROOFAI__EXTRA_PATHS` | Thay thế đường dẫn nắm bắt bổ sung được cấu hình cho một harness | +| `NO_COLOR` | Tắt đầu ra terminal có màu | -Các biến nhà dành riêng cho agent chẳng hạn như `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` và `OPENCLAW_HOME` ghi đè nơi Failproof AI khám phá các phiên cục bộ cho harness đó. +Biến home cụ thể agent như `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, và `OPENCLAW_HOME` ghi đè nơi Failproof AI phát hiện các phiên cục bộ cho harness đó. -## Tạm dừng hoặc loại bỏ một máy một cách an toàn +## Tạm dừng hoặc loại bỏ máy một cách an toàn ```bash failproofai config --pause @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -Tạm dừng phiên cục bộ không vô hiệu hóa chính sách được quản lý bởi Cloud. Khôi phục các triển khai Cloud thông qua quy trình công việc thực thi Cloud khi chính triển khai đó là vấn đề. +Tạm dừng phiên cục bộ không vô hiệu hóa các chính sách được quản lý bởi Cloud. Khôi phục triển khai Cloud thông qua quy trình thực thi Cloud khi chính bản rollout là vấn đề. -Trước khi loại bỏ gói npm, hãy loại bỏ các hooks đã cài đặt và daemon: +Trước khi loại bỏ gói npm, loại bỏ hooks được cài đặt và daemon: ```bash failproofai uninstall --dry-run @@ -151,7 +171,7 @@ failproofai uninstall --yes npm rm -g failproofai ``` -Chạy `failproofai --help` để biết chi tiết dành riêng cho phiên bản. +Chạy `failproofai --help` để biết chi tiết cụ thể phiên bản. Chạy `failproofai uninstall` trước `npm rm -g failproofai`; npm không loại bỏ các hooks agent được cài đặt hoặc dịch vụ daemon. diff --git a/docs/vi/reference/harnesses.mdx b/docs/vi/reference/harnesses.mdx index 767c35de..bffd487a 100644 --- a/docs/vi/reference/harnesses.mdx +++ b/docs/vi/reference/harnesses.mdx @@ -1,80 +1,86 @@ --- -title: "Harnesses của agent" -description: "Thu thập phiên làm việc và thực thi chính sách trên tất cả 12 harnesses được hỗ trợ." +title: "Điểm kết nối agent" +description: "Ghi lại phiên làm việc và thực thi chính sách trên tất cả 12 điểm kết nối agent được hỗ trợ." icon: "plug-zap" --- -Harness là bất kỳ điều gì mà agent thực sự chạy bên trong. Failproof AI hỗ trợ mười hai harnesses, chia thành hai lớp: +Điểm kết nối là bất cứ nơi nào agent của bạn thực sự chạy. Failproof AI hỗ trợ mười hai điểm kết nối, được chia thành hai loại: -- **Coding CLIs** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Chat and assistant gateways** (2) — Hermes (Slack, Telegram, cron), OpenClaw (self-hosted assistant) +- **CLI Coding** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **Chat và cổng assistant** (2) — Hermes (Slack, Telegram, cron), OpenClaw (self-hosted assistant) -Cùng một chính sách và cùng lịch sử phiên làm việc áp dụng cho bất kỳ harness nào mà agent chạy trong đó. Một lớp adapter ánh xạ tên sự kiện gốc, tên công cụ và các trường input công cụ của mỗi harness thành 29 sự kiện chính tắc trước khi bất kỳ chính sách nào chạy. +Cùng một chính sách và lịch sử phiên làm việc tương tự được áp dụng bất kể agent chạy trong điểm kết nối nào. Một lớp adapter ánh xạ từng tên sự kiện gốc, tên công cụ và trường đầu vào của công cụ của mỗi điểm kết nối thành 29 sự kiện chính tắc trước khi bất kỳ chính sách nào chạy. -Một agent chạy trong **không** một trong mười hai harnesses được trang bị trực tiếp với [Python SDK](/vi/reference/custom-agents). Đó là một hợp đồng khác, và đáng nói rõ ràng: SDK cung cấp theo dõi, phiên làm việc, đánh giá và kiểm toán — **nó không tự thực thi chính sách.** Chặn một hành động không an toàn trước khi nó thực thi cần một hook thực thi tại ranh giới công cụ của runtime của bạn; [liên hệ với chúng tôi](mailto:support@befailproof.ai) và chúng tôi sẽ ánh xạ nó. +Một agent chạy trong **không** điểm kết nối nào trong mười hai sẽ được theo dõi trực tiếp bằng [Python SDK](/vi/reference/custom-agents). Đó là một hợp đồng khác, và cần nói rõ ràng: SDK cung cấp tracing, phiên làm việc, đánh giá và kiểm toán — **nó không tự thực thi chính sách.** Chặn một hành động không an toàn trước khi nó thực thi cần một hook thực thi ở ranh giới công cụ của runtime của bạn; [liên hệ với chúng tôi](mailto:support@befailproof.ai) và chúng tôi sẽ ánh xạ nó. -| Harness | Phạm vi hook được hỗ trợ | +| Điểm kết nối | Phạm vi hook được hỗ trợ | | --- | --- | | Claude Code | User, project, local | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -Mỗi tích hợp chuẩn hóa tên sự kiện hook gốc, tên công cụ và các trường input công cụ trước khi chính sách chạy. Một chính sách chỉ có thể tác động trên các sự kiện mà harness tiết lộ; hãy kiểm tra hành vi end-of-turn và instruction trên harness và phiên bản chính xác mà bạn triển khai. +Mỗi tích hợp chuẩn hóa tên sự kiện hook gốc, tên công cụ và trường đầu vào của công cụ trước khi chính sách chạy. Một chính sách chỉ có thể hoạt động trên các sự kiện mà điểm kết nối công khai; kiểm tra hành vi cuối lượt và hướng dẫn trên điểm kết nối và phiên bản chính xác mà bạn triển khai. ## Khả năng thực thi -"Block" có nghĩa là phán quyết được trả về của adapter hiện tại được tiêu thụ bởi harness được đặt tên. Chặn sau công cụ có thể thay thế kết quả được hiển thị cho mô hình nhưng không thể hoàn tác tác dụng phụ của công cụ đã xảy ra. +"Block" có nghĩa là phán quyết được trả về của adapter hiện tại được điểm kết nối đã đặt tên sử dụng. Chặn sau công cụ có thể thay thế kết quả được hiển thị cho model nhưng không thể hoàn tác hiệu ứng phụ của công cụ đã xảy ra. -| Harness | Các sự kiện chặn được xác minh | Chỉ quan sát hoặc những cảnh báo không chặn | +| Điểm kết nối | Sự kiện chặn được xác minh | Cảnh báo chỉ quan sát hoặc không chặn | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` và một số sự kiện task/config | `PostToolUse`, vòng đời phiên, thông báo và sự kiện sau lỗi là quan sát. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Chặn sau công cụ thay thế kết quả sau khi thực thi; sự kiện bắt đầu phiên và compact là quan sát trong adapter hiện tại. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Chặn sau công cụ thay thế kết quả sau khi thực thi; phiên và sự kiện thông báo là quan sát. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` và sự kiện phiên là quan sát. | -| OpenCode | `PreToolUse` | Sự kiện sau công cụ và vòng đời là quan sát; xử lý dừng hiện tại là hướng dẫn cho lượt sau thay vì một cổng được xác minh. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Sự kiện sau công cụ và vòng đời là quan sát; hướng dẫn dừng áp dụng cho lượt sau. | +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` và một số sự kiện task/config | `PostToolUse`, vòng đời phiên, thông báo và sự kiện hậu lỗi chỉ là quan sát. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Chặn sau công cụ thay thế kết quả sau khi thực thi; sự kiện bắt đầu phiên và compact chỉ được quan sát trong adapter hiện tại. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Chặn sau công cụ thay thế kết quả sau khi thực thi; sự kiện phiên và thông báo chỉ được quan sát. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` và sự kiện phiên chỉ được quan sát. | +| OpenCode | `PreToolUse` | Sự kiện sau công cụ và vòng đời chỉ được quan sát; xử lý stop hiện tại là hướng dẫn cho lượt sau hơn là một cổng được xác minh. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Sự kiện sau công cụ và vòng đời chỉ được quan sát; hướng dẫn stop áp dụng cho lượt sau. | | Hermes | `PreToolUse` | Phán quyết sau công cụ, phiên và subagent-stop không phải là cổng. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Sự kiện sau công cụ, phiên, subagent-stop và compact là quan sát. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Phán quyết sau công cụ và subagent-stop là quan sát. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` có điều kiện | Hook quyền không chạy ở mọi chế độ quyền; sự kiện sau công cụ và phiên là quan sát. | -| Antigravity CLI | `PreToolUse`, `Stop` | Phán quyết user-prompt và sau công cụ là quan sát; hướng dẫn nhắc vẫn có thể được inject. | -| Goose | `PreToolUse` | Sự kiện user-prompt, sau công cụ và phiên là quan sát. Một hook dừng chặn gốc tồn tại ở thượng nguồn nhưng không được cài đặt bởi adapter hiện tại. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Sự kiện sau công cụ, phiên, subagent-stop và compaction chỉ được quan sát. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Phán quyết sau công cụ và subagent-stop chỉ được quan sát. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` có điều kiện | Hook quyền không chạy trong mọi chế độ quyền; sự kiện sau công cụ và phiên chỉ được quan sát. | +| Antigravity CLI | `PreToolUse`, `Stop` | Phán quyết lời nhắc user và sau công cụ chỉ được quan sát; hướng dẫn lời nhắc vẫn có thể được tiêm. | +| Goose | `PreToolUse` | Sự kiện lời nhắc user, sau công cụ và phiên chỉ được quan sát. Một hook stop chặn gốc tồn tại ở thượng nguồn nhưng không được cài đặt bởi adapter hiện tại. | -Khả năng nhạy cảm với phiên bản. Hãy kiểm tra lại sau khi nâng cấp CLI agent, đặc biệt khi một chính sách dựa vào hành vi prompt, stop, permission hoặc post-tool thay vì cổng pre-tool phổ biến. +Khả năng nhạy cảm với phiên bản. Kiểm tra lại sau khi nâng cấp CLI agent, đặc biệt khi một chính sách dựa vào hành vi lời nhắc, stop, quyền hoặc sau công cụ hơn là cổng pre-tool thông thường. -## Cài đặt capture và policy hooks +## Cài đặt hook ghi lại và chính sách - 1. Mở **Administration → Keys** và tạo một khóa với `events:add` và `policies:pull`, được đặt tên cho máy hoặc môi trường. - 2. Trên máy đích, kết nối CLI cục bộ với khóa được hiển thị và cài đặt harness hooks. - 3. Bắt đầu phiên agent mới, sau đó xác nhận các hook và sự kiện phiên của nó trong **Observe → Events**. - 4. Mở **Observe → policy** cho cùng một cửa sổ thời gian và xác nhận phán quyết chính sách được gán cho máy. + 1. Mở **Administration → Keys** và tạo một khóa có `events:add` và `policies:pull`, được đặt tên cho máy hoặc môi trường. + 2. Trên máy đích, kết nối CLI cục bộ với khóa được hiển thị và cài đặt hook điểm kết nối. + 3. Bắt đầu một phiên agent mới, sau đó xác nhận sự kiện hook và phiên của nó trong **Observe → Events**. + 4. Mở **Observe → policy** cho cửa sổ thời gian tương tự và xác nhận quyết định chính sách được gán cho máy. - Kết nối bắt đầu với một khóa máy. Xác nhận rằng nó bao gồm cả quyền tiếp nhận và cung cấp chính sách trước khi sao chép bí mật của nó. + Kết nối bắt đầu với một khóa máy. Xác nhận rằng nó bao gồm cả quyền tiêu thụ và cung cấp chính sách trước khi sao chép bí mật của nó. - ![Ngăn tạo khóa API mới được sử dụng để cấp quyền tiếp nhận sự kiện và cung cấp chính sách.](/images/dashboard/key-create.png) + ![Ngăn tạo khóa API mới được sử dụng để cấp quyền tiêu thụ sự kiện và cung cấp chính sách.](/images/dashboard/key-create.png) - Sau khi cài đặt hooks, luồng Events sẽ hiển thị các sự kiện mới từ máy và môi trường bạn đã kết nối. + Sau khi cài đặt hook, luồng Events sẽ hiển thị các sự kiện mới từ máy và môi trường bạn kết nối. - ![Luồng Events trực tiếp được sử dụng để xác nhận harness mới được cài đặt đang báo cáo.](/images/dashboard/events-stream.png) + ![Luồng Events trực tiếp được sử dụng để xác nhận một điểm kết nối mới được cài đặt đang báo cáo.](/images/dashboard/events-stream.png) - Cuối cùng, xác minh rằng các phán quyết chính sách được gán cho cùng một máy. Điều này xác nhận harness đang báo cáo hoạt động chính sách cũng như sự kiện trace. + Cuối cùng, xác minh rằng quyết định chính sách được gán cho cùng một máy. Điều này xác nhận rằng điểm kết nối đang báo cáo hoạt động chính sách cũng như sự kiện trace. - ![Trang Policy được sử dụng để xác minh các phán quyết chính sách từ harness mới được kết nối.](/images/dashboard/policy-observe.png) + ![Trang Policy được sử dụng để xác minh quyết định chính sách từ một điểm kết nối mới được kết nối.](/images/dashboard/policy-observe.png) - Cài đặt hooks cho mọi harness được phát hiện: + Đọc khóa máy vào shell. `read -s` lấy nó ở một dấu nhắc không kéo theo, vì vậy nó không bao giờ xuất hiện trong một lệnh hoặc lịch sử shell: ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Hoặc nhắm mục tiêu các harnesses được đặt tên và phạm vi cấu hình: + Sau đó thiết lập máy — điều này tạo hook cho mọi điểm kết nối được phát hiện, cài đặt daemon và kết nối đến Cloud: + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + Thiết lập không kích hoạt bất kỳ chính sách nào, đó là lý do tại sao lệnh thứ hai tồn tại. + + Hoặc nhắm mục tiêu các điểm kết nối được đặt tên và phạm vi cấu hình: ```bash failproofai policies --install \ @@ -82,9 +88,9 @@ Khả năng nhạy cảm với phiên bản. Hãy kiểm tra lại sau khi nâng --scope user ``` - Phạm vi project giữ cấu hình hook với một kho lưu trữ. Phạm vi user bao gồm công việc trên các kho lưu trữ. Claude Code cũng hỗ trợ phạm vi local; hỗ trợ khác nhau tùy theo harness và CLI từ chối các kết hợp không được hỗ trợ. + Phạm vi project giữ cấu hình hook với một repository. Phạm vi user bao gồm công việc trên các repository. Claude Code cũng hỗ trợ phạm vi local; hỗ trợ khác nhau tùy theo điểm kết nối và CLI từ chối các kết hợp không được hỗ trợ. - Xác minh máy và các sự kiện của nó: + Xác minh máy và sự kiện của nó: ```bash failproofai config --status @@ -98,12 +104,12 @@ Khả năng nhạy cảm với phiên bản. Hãy kiểm tra lại sau khi nâng - Các đường dẫn bổ sung được đăng ký trên máy, không trong Cloud. Sau khi thêm một đường dẫn, mở **Observe → Sessions**, lọc theo môi trường của máy và xác nhận các phiên từ đường dẫn mới xuất hiện. Mở một phiên và kiểm tra agent, harness và dấu thời gian sự kiện trước khi dựa vào nó trong kiểm toán. + Các đường dẫn bổ sung được đăng ký trên máy, không phải trong Cloud. Sau khi thêm một đường dẫn, mở **Observe → Sessions**, lọc theo môi trường của máy và xác nhận các phiên từ đường dẫn mới xuất hiện. Mở một phiên và kiểm tra agent, điểm kết nối và dấu thời gian sự kiện trước khi sử dụng nó trong kiểm toán. - ![Danh sách Sessions được lọc theo môi trường nhận dữ liệu từ đường dẫn capture bổ sung.](/images/dashboard/sessions-list.png) + ![Danh sách Sessions được lọc theo môi trường nhận dữ liệu từ đường dẫn ghi lại bổ sung.](/images/dashboard/sessions-list.png) - Thêm một đường dẫn với nhãn tùy chọn, sau đó kiểm tra các đường dẫn được cấu hình: + Thêm một đường dẫn với một nhãn tùy chọn, sau đó kiểm tra các đường dẫn được cấu hình: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -117,5 +123,5 @@ Khả năng nhạy cảm với phiên bản. Hãy kiểm tra lại sau khi nâng - Chạy một phiên mới sau khi cài đặt. Xác minh cả luồng sự kiện trực tiếp và phán quyết chính sách thực tế trước khi mở rộng triển khai. + Chạy một phiên mới sau khi cài đặt. Xác minh cả luồng sự kiện trực tiếp và quyết định chính sách thực tế trước khi mở rộng phân phối. \ No newline at end of file diff --git a/docs/vi/reference/overview.mdx b/docs/vi/reference/overview.mdx index 64ae67af..f8e4a12c 100644 --- a/docs/vi/reference/overview.mdx +++ b/docs/vi/reference/overview.mdx @@ -1,81 +1,84 @@ --- -title: "Tích hợp và tham khảo" -description: "Kết nối các agent harness, SDK, CLI và HTTP API được hỗ trợ." +title: "Tích hợp và tài liệu tham khảo" +description: "Kết nối các harness agent được hỗ trợ, SDK, CLI, và HTTP API." icon: "braces" --- -Chọn tích hợp phù hợp nhất với nơi agent của bạn đang chạy. +Chọn tích hợp gần nhất với nơi agent của bạn đang chạy. - Cài đặt hooks cho các CLI agent tự động và mã hóa được hỗ trợ. + Cài đặt hooks cho các CLI agent mã hóa và tự trị được hỗ trợ. - Đo lường LangGraph, CrewAI, LlamaIndex, Pydantic AI hoặc một agent tùy chỉnh. + Thiết bị LangGraph, CrewAI, LlamaIndex, Pydantic AI, hoặc một agent tùy chỉnh. - - Cấu hình, danh mục sự kiện, quy tắc tương quan và gửi. + + Cấu hình, danh mục sự kiện, quy tắc tương quan và phân phối. - Xem xét các dự án cục bộ, phiên, hoạt động chính sách và kiểm toán ngoại tuyến. + Xem lại các dự án cục bộ, phiên, hoạt động chính sách và kiểm toán ngoại tuyến. - Cấu hình thu thập cục bộ, hooks, chính sách, kiểm toán, gửi và trạng thái máy. + Cấu hình xử lý cục bộ, hooks, chính sách, kiểm toán, phân phối và trạng thái máy. - Truy vấn và quản lý các phiên Cloud, kiểm toán, vấn đề, cảnh báo, khóa, người dùng và cài đặt. + Truy vấn và quản trị các phiên Cloud, kiểm toán, vấn đề, cảnh báo, khóa, người dùng và cài đặt. - Đánh giá các phiên hoàn chỉnh hoặc không hoạt động với dịch vụ FastAPI. + Chấm điểm các phiên hoàn thành hoặc không hoạt động bằng dịch vụ FastAPI. - Soạn và kiểm tra quyết định allow, instruct và deny theo quy trình làm việc cụ thể. + Tạo và kiểm tra các quyết định allow, instruct và deny dành riêng cho quy trình làm việc. Triển khai mặt phẳng điều khiển Cloud trên một cụm Kubernetes do khách hàng quản lý. -[Tham chiếu HTTP API](/vi/reference/http-api) được tạo bao gồm bề mặt `/v1` công khai. Các trang được viết bằng tay giải thích các quy trình làm việc bao gồm nhiều điểm cuối hoặc sử dụng các giao diện quản trị bên ngoài bề mặt công khai đó. +[Tài liệu tham khảo HTTP API](/vi/reference/http-api) được tạo bao gồm bề mặt công khai `/v1`. Các trang được viết thủ công giải thích các quy trình làm việc trải dài trên nhiều endpoint hoặc sử dụng giao diện quản trị bên ngoài bề mặt công khai đó. ## Kết nối một agent và xác minh dữ liệu - 1. Mở **Administration → Keys**, tạo một khóa có `events:add` và `policies:pull`, rồi sao chép mật khẩu. - 2. Cấu hình tích hợp bằng trang phù hợp ở trên. + 1. Mở **Administration → Keys**, tạo một khóa với `events:add` và `policies:pull`, và sao chép bí mật. + 2. Cấu hình tích hợp bằng cách sử dụng trang phù hợp ở trên. 3. Mở **Observe → Events** để xác nhận các sự kiện đến, sau đó **Observe → Sessions** để xác nhận chúng tạo thành các lần chạy hoàn chỉnh. - 4. Lọc theo môi trường tích hợp và kiểm tra một phiên để lấy các trường model, tool, error và policy cần thiết cho kiểm toán. + 4. Lọc theo môi trường tích hợp và kiểm tra một phiên cho các trường model, tool, error và policy cần thiết cho kiểm toán. - Bắt đầu bằng ngăn kéo khóa. Các quyền được chọn xác định xem máy có thể gửi sự kiện và nhận chính sách do Cloud quản lý hay không. + Bắt đầu bằng ngăn kéo khóa. Các quyền được chọn xác định xem máy có thể gửi sự kiện và nhận chính sách được quản lý bởi Cloud hay không. - ![Ngăn kéo khóa API mới được sử dụng để cấp quyền nhập sự kiện và gửi chính sách.](/images/dashboard/key-create.png) + ![Ngăn kéo tạo khóa API mới được sử dụng để cấp quyền xử lý sự kiện và phân phối chính sách.](/images/dashboard/key-create.png) - Sau khi kết nối tích hợp, sử dụng danh sách Sessions để xác nhận rằng các sự kiện của nó đang được nhóm thành các lần chạy hoàn chỉnh trong môi trường dự kiến. + Sau khi kết nối tích hợp, sử dụng danh sách Sessions để xác nhận rằng các sự kiện của nó được nhóm thành các lần chạy agent hoàn chỉnh trong môi trường dự kiến. - ![Danh sách Sessions được sử dụng để xác minh rằng tích hợp mới kết nối đang báo cáo các lần chạy agent hoàn chỉnh.](/images/dashboard/sessions-list.png) + ![Danh sách Sessions được sử dụng để xác minh rằng một tích hợp mới kết nối đang báo cáo các lần chạy agent hoàn chỉnh.](/images/dashboard/sessions-list.png) - Mở một trong những phiên này trước khi coi tích hợp hoàn thành; dấu vết sẽ chứa các bằng chứng model, tool, error và policy mà kiểm toán của bạn cần. + Mở một trong những phiên này trước khi coi tích hợp là hoàn chỉnh; bản theo dõi phải chứa bằng chứng model, tool, error và policy mà kiểm toán của bạn cần. - Tạo khóa máy, kết nối daemon Failproof và xác minh phiên đầu tiên. + Tạo một khóa máy, sau đó đọc bí mật mà nó in ra shell. `read -s` lấy nó ở một lời nhắc không in lại, vì vậy nó không bao giờ xuất hiện trong một lệnh hoặc lịch sử shell: ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Kết nối daemon Failproof và xác minh phiên đầu tiên: - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - Sử dụng `fp --json sessions ...` khi một công cụ khác sẽ sử dụng kết quả. Các cờ toàn cục như `--json`, `--org` và `--base-url` phải đứng trước lệnh. + Sử dụng `fp --json sessions ...` khi một công cụ khác sẽ sử dụng kết quả. Các cờ toàn cầu như `--json`, `--org` và `--base-url` phải đứng trước lệnh. - Xem [Tham khảo Failproof AI CLI](/vi/reference/failproof-cli) để biết các lệnh cục bộ và [Tham khảo Failproof Cloud CLI](/vi/reference/cloud-cli#cli-commands) cho các lệnh `fp`. + Xem [tài liệu tham khảo Failproof AI CLI](/vi/reference/failproof-cli) cho các lệnh cục bộ và [tài liệu tham khảo Failproof Cloud CLI](/vi/reference/cloud-cli#cli-commands) cho các lệnh `fp`. \ No newline at end of file diff --git a/docs/vi/reference/policy-sdk.mdx b/docs/vi/reference/policy-sdk.mdx index 19a12008..24b922e9 100644 --- a/docs/vi/reference/policy-sdk.mdx +++ b/docs/vi/reference/policy-sdk.mdx @@ -1,35 +1,35 @@ --- title: "Chính sách tùy chỉnh" -description: "Tạo, kiểm tra và triển khai các chính sách JavaScript hoặc TypeScript cho các lỗi cụ thể của các agent của bạn." +description: "Soạn thảo, kiểm tra và triển khai chính sách JavaScript hoặc TypeScript cho các lỗi cụ thể của agents." icon: "shield-plus" --- -Chính sách tùy chỉnh chuyển một mô hình lỗi từ các trace hoặc audit của bạn thành một quyết định chạy trong khi agent hoạt động. Một chính sách có thể cho phép một hành động, cung cấp hướng dẫn cho agent hoặc từ chối hành động trước khi nó gây ra một sự cố khác. +Chính sách tùy chỉnh chuyển đổi một mẫu lỗi từ traces hoặc audits của bạn thành một quyết định chạy trong khi agent hoạt động. Một chính sách có thể cho phép một hành động, cung cấp hướng dẫn cho agent hoặc từ chối hành động trước khi nó gây ra một sự cố khác. -Sử dụng chính sách tùy chỉnh khi hành vi phụ thuộc vào các công cụ, đường dẫn, lệnh, môi trường hoặc quy tắc hoạt động của bạn. Hãy kiểm tra [danh mục chính sách tích hợp](/vi/policies/builtin-catalog) trước để tránh tái tạo một điều khiển hiện có. +Sử dụng chính sách tùy chỉnh khi hành vi phụ thuộc vào các tools, đường dẫn, lệnh, môi trường hoặc quy tắc hoạt động của bạn. Kiểm tra [gói chính sách Failproof AI](/vi/policies/packs) trước để bạn không tạo lại một điều khiển hiện có. -## Tạo chính sách tùy chỉnh +## Soạn thảo chính sách tùy chỉnh - 1. Chuyển đến **Admin → policy editor**, chọn **New policy** và mô tả lỗi bạn muốn ngăn chặn. - 2. Thêm mã nguồn chính sách, sau đó kiểm tra các kết quả khớp mong đợi và các kết quả không khớp an toàn trong trình soạn thảo. Giải quyết mọi lỗi xác thực. + 1. Đi đến **Admin → policy editor**, chọn **New policy**, và mô tả lỗi mà bạn muốn ngăn chặn. + 2. Thêm mã nguồn chính sách, sau đó kiểm tra các kết quả khớp dự kiến và các kết quả không khớp an toàn trong trình chỉnh sửa. Giải quyết mọi lỗi xác thực. 3. Lưu bản nháp và chọn **Publish version** để tạo một phiên bản bất biến. - 4. Chuyển đến **Admin → enforcement**, triển khai phiên bản tới một máy thử nghiệm ở chế độ **observe** và xác minh các quyết định của nó dưới **Observe → policy** trước khi thực thi. + 4. Đi đến **Admin → enforcement**, triển khai phiên bản sang một máy kiểm tra trong chế độ **observe**, và xác minh các quyết định của nó dưới **Observe → policy** trước khi áp dụng nó. - ![Trình soạn thảo chính sách được sử dụng để tạo và xuất bản chính sách tùy chỉnh.](/images/dashboard/policy-editor.png) + ![Trình chỉnh sửa chính sách được sử dụng để soạn thảo và xuất bản chính sách tùy chỉnh.](/images/dashboard/policy-editor.png) - 1. Tạo `.failproofai/policies/checkout-policies.ts`. Tên tệp phải kết thúc bằng `policies.js`, `policies.mjs` hoặc `policies.ts`. + 1. Tạo `.failproofai/policies/checkout-policies.ts`. Tên file phải kết thúc bằng `policies.js`, `policies.mjs`, hoặc `policies.ts`. 2. Đăng ký một hoặc nhiều chính sách với `customPolicies.add()`. - 3. Xác thực và cài đặt tệp bằng `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. - 4. Kích hoạt một hành động khớp và một hành động an toàn. Chạy `failproofai policies`, sau đó kiểm tra các quyết định được quy cho dưới **Observe → policy**. + 3. Xác thực và cài đặt file với `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. + 4. Kích hoạt một hành động khớp và một hành động an toàn. Chạy `failproofai policies`, sau đó kiểm tra các quyết định được ghi nhận dưới **Observe → policy**. ## Bắt đầu với một quy tắc hẹp -Chính sách này chặn các lệnh Kubernetes phá hủy chỉ khi lệnh nhắm vào production. Mọi thứ ngoài chế độ lỗi chính xác đó trả về `allow()`. +Chính sách này chặn các lệnh Kubernetes phá hoại chỉ khi lệnh nhắm mục tiêu sản xuất. Mọi thứ bên ngoài chế độ lỗi chính xác đó trả về `allow()`. ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,17 +55,17 @@ customPolicies.add({ }); ``` -Các chính sách tốt đủ hẹp để giải thích trong một câu. Khớp hành động quan sát được—không phải ý định bạn hy vọng agent có—và trả về `allow()` ngay khi quy tắc không áp dụng. +Các chính sách tốt đủ hẹp để giải thích trong một câu. Khớp với hành động có thể quan sát được — không phải ý định mà bạn hy vọng agent có — và trả về `allow()` ngay khi quy tắc không áp dụng. ## Chọn một quyết định -| Trợ giúp | Kết quả | Sử dụng khi | +| Helper | Kết quả | Sử dụng nó khi | | --- | --- | --- | | `allow(reason?)` | Hoạt động tiếp tục. | Chính sách không áp dụng hoặc hành động là an toàn. | -| `instruct(reason)` | Hoạt động tiếp tục với hướng dẫn nơi harness hỗ trợ nó. | Bạn muốn hướng dẫn agent đến một cách tiếp cận tốt hơn mà không thực thi một bất biến. | -| `deny(reason)` | Hoạt động bị chặn khi sự kiện và harness hỗ trợ chặn. | Hành động không được phép tiếp tục. | +| `instruct(reason)` | Hoạt động tiếp tục với hướng dẫn nơi harness hỗ trợ. | Bạn muốn hướng dẫn agent hướng tới một cách tiếp cận tốt hơn mà không áp dụng một bất biến. | +| `deny(reason)` | Hoạt động bị chặn khi sự kiện và harness hỗ trợ chặn. | Hành động không được tiếp tục. | -Viết lý do cho agent phải khôi phục. Giải thích những gì được phát hiện và nó nên làm gì để thay thế. +Viết lý do cho agent phải phục hồi. Giải thích những gì được phát hiện và nó nên làm gì thay vào đó. Không sử dụng `instruct()` cho ranh giới an toàn. Việc cung cấp hướng dẫn khác nhau tùy theo harness agent. Sử dụng `deny()` khi hành động phải được ngăn chặn. @@ -84,34 +84,34 @@ customPolicies.add({ | Trường | Bắt buộc | Mô tả | | --- | --- | --- | -| `name` | Có | Định danh ổn định cho chính sách. Giữ tên duy nhất trong các tệp. | +| `name` | Có | Định danh ổn định cho chính sách. Giữ các tên duy nhất trên các file. | | `description` | Không | Mục đích có thể đọc được của con người được hiển thị trong danh sách chính sách và quyết định. | | `match.events` | Không | Các loại sự kiện gọi chính sách. Bỏ qua `match` gọi nó cho mọi sự kiện có sẵn. | -| `fn` | Có | Hàm đồng bộ hoặc không đồng bộ trả về kết quả `allow`, `instruct` hoặc `deny`. | +| `fn` | Có | Hàm đồng bộ hoặc không đồng bộ trả về kết quả `allow`, `instruct`, hoặc `deny`. | -Lọc công cụ bên trong `fn`. `match.toolNames` không phải là một phần của loại chính sách tùy chỉnh công khai. +Lọc các tools bên trong `fn`. `match.toolNames` không phải là một phần của loại chính sách tùy chỉnh công khai. ## Ngữ cảnh chính sách -Mỗi chính sách nhận một `PolicyContext`. +Mọi chính sách nhận một `PolicyContext`. | Trường | Loại | Nó chứa gì | | --- | --- | --- | -| `eventType` | `HookEventType` | Sự kiện chuẩn hóa hiện đang được đánh giá. | -| `toolName` | `string \| undefined` | Tên công cụ chính thức như `Bash`, `Read`, `Write` hoặc `Edit`. | -| `toolInput` | `Record \| undefined` | Đầu vào chính thức cho lệnh gọi công cụ hiện tại. | -| `payload` | `Record` | Tải trọng sự kiện chuẩn hóa hoàn chỉnh. | -| `session` | `SessionMetadata \| undefined` | ID phiên, thư mục làm việc, đường dẫn transcript, chế độ quyền và siêu dữ liệu harness khi có sẵn. | -| `cli` | `string \| undefined` | Harness agent nguồn, chẳng hạn như `claude`, `codex` hoặc `cursor`. | -| `params` | `Record` | Các tham số chính sách tích hợp. Các chính sách tùy chỉnh hiện tại nhận một đối tượng trống. | +| `eventType` | `HookEventType` | Sự kiện được chuẩn hóa hiện đang được đánh giá. | +| `toolName` | `string \| undefined` | Tên tool chính tắc như `Bash`, `Read`, `Write`, hoặc `Edit`. | +| `toolInput` | `Record \| undefined` | Đầu vào chính tắc cho lệnh gọi tool hiện tại. | +| `payload` | `Record` | Toàn bộ tải trọng sự kiện được chuẩn hóa. | +| `session` | `SessionMetadata \| undefined` | ID phiên, thư mục làm việc, đường dẫn phiên ghi âm, chế độ quyền hạn, và siêu dữ liệu harness khi có sẵn. | +| `cli` | `string \| undefined` | Harness agent nguồn, như `claude`, `codex`, hoặc `cursor`. | +| `params` | `Record` | Các tham số chính sách tích hợp sẵn. Các chính sách tùy chỉnh hiện tại nhận một đối tượng rỗng. | Coi mọi giá trị tùy chọn là thực sự tùy chọn. Các phiên bản agent và các loại sự kiện không cung cấp các trường giống nhau. -### Đầu vào công cụ phổ biến +### Đầu vào tool phổ biến -Failproof AI chuẩn hóa các công cụ phổ biến trên các harness được hỗ trợ để một chính sách thường có thể sử dụng một hình dạng đầu vào. +Failproof AI chuẩn hóa các tools phổ biến trên các harness được hỗ trợ để chính sách thường có thể sử dụng một hình dạng đầu vào. -| Công cụ | Các trường phổ biến | +| Tool | Các trường phổ biến | | --- | --- | | `Bash` | `command` | | `Read` | `file_path` | @@ -119,7 +119,7 @@ Failproof AI chuẩn hóa các công cụ phổ biến trên các harness đư | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | -Sử dụng chuyển đổi phòng thủ vì các giá trị đầu vào công cụ được gõ là `unknown`: +Sử dụng việc chuyển đổi phòng thủ vì các giá trị đầu vào tool được nhập là `unknown`: ```ts const command = String(ctx.toolInput?.command ?? ""); @@ -130,23 +130,23 @@ const filePath = String(ctx.toolInput?.file_path ?? ""); | Sự kiện | Khi nó chạy | Sử dụng điển hình | | --- | --- | --- | -| `PreToolUse` | Trước khi một công cụ thực thi. | Chặn hoặc hướng dẫn lệnh, ghi, đọc và hành động bên ngoài. | -| `PostToolUse` | Sau khi một công cụ trả về. | Kiểm tra kết quả trước khi chúng đến agent. Một deny chặn toàn bộ kết quả; nó không làm mất công dụng các trường được chọn. | -| `PermissionRequest` | Khi agent yêu cầu quyền. | Áp dụng các quy tắc quyền cụ thể của tổ chức. | -| `UserPromptSubmit` | Trước khi một prompt được gửi tiếp tục. | Từ chối các hướng dẫn bị cấm hoặc thêm hướng dẫn quy trình làm việc. | -| `Stop` | Khi agent cố gắng kết thúc. | Yêu cầu một điều kiện hoàn thành có thể truy cập được, chẳng hạn như một bước xác minh cục bộ. | -| `SubagentStop` | Khi một subagent cố gắng kết thúc. | Ghi công việc được ủy quyền trước khi nó trở lại parent. | -| `SessionStart` / `SessionEnd` | Tại ranh giới phiên. | Ghi hoặc kiểm tra trạng thái cấp phiên. | - -Tính khả dụng sự kiện và hành vi chặn phụ thuộc vào harness agent. Xem [Agent harnesses](/vi/reference/harnesses) trước khi dựa vào một sự kiện trên một lực lượng hỗn hợp. - - - `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` và `Setup`. +| `PreToolUse` | Trước khi một tool thực thi. | Chặn hoặc hướng dẫn các lệnh, ghi, đọc, và hành động bên ngoài. | +| `PostToolUse` | Sau khi một tool trả về. | Kiểm tra các kết quả trước khi chúng tiếp cận agent. Một deny chặn toàn bộ kết quả; nó không loại bỏ các trường được chọn. | +| `PermissionRequest` | Khi agent yêu cầu quyền hạn. | Áp dụng các quy tắc quyền hạn cụ thể của tổ chức. | +| `UserPromptSubmit` | Trước khi một lời nhắc được gửi tiếp tục. | Từ chối các hướng dẫn bị cấm hoặc thêm hướng dẫn quy trình làm việc. | +| `Stop` | Khi agent cố gắng kết thúc. | Yêu cầu một điều kiện hoàn thành có thể đạt được, như một bước xác minh cục bộ. | +| `SubagentStop` | Khi một subagent cố gắng kết thúc. | Chặn công việc được ủy thác trước khi nó trả về cho cha mẹ. | +| `SessionStart` / `SessionEnd` | Tại các ranh giới phiên. | Ghi nhận hoặc kiểm tra trạng thái cấp phiên. | + +Tính khả dụng sự kiện và hành vi chặn phụ thuộc vào harness agent. Xem [Agent harnesses](/vi/reference/harnesses) trước khi dựa vào một sự kiện trên một hạm đội hỗn hợp. + + + `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch`, và `Setup`. -## Tạo các mô hình chính sách phổ biến +## Soạn thảo các mẫu chính sách phổ biến -### Chặn ghi vào các đường dẫn được bảo vệ +### Chặn ghi vào đường dẫn được bảo vệ ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### Ghi công việc hoàn thành phiên +### Chặn hoàn thành phiên ```ts import { execFileSync } from "node:child_process"; @@ -215,14 +215,14 @@ customPolicies.add({ ``` - Một sự kiện `Stop` bị từ chối có thể làm cho agent thử lại. Chỉ ghi công việc trên một điều kiện mà agent có thể thỏa mãn trong môi trường hiện tại và giới hạn mọi lệnh con hoặc cuộc gọi mạng. + Một sự kiện `Stop` bị từ chối có thể khiến agent thử lại. Chỉ chặn trên một điều kiện mà agent có thể thỏa mãn trong môi trường hiện tại, và giới hạn mọi lệnh gọi con quy trình hoặc mạng. -## Tải tệp chính sách +## Tải các file chính sách -### Tệp quy ước +### File quy ước -Tệp quy ước tải tự động: +Các file quy ước tải tự động: ```text /.failproofai/policies/security-policies.ts @@ -230,15 +230,15 @@ Tệp quy ước tải tự động: ``` - Cả thư mục chính sách của dự án và người dùng đều được tải. -- Các tệp tải theo thứ tự bảng chữ cái trong mỗi thư mục. -- Một tệp phải kết thúc bằng `policies.js`, `policies.mjs` hoặc `policies.ts`. -- Nhiều lệnh gọi `customPolicies.add()` trong một tệp được hỗ trợ. -- Các nhập khẩu tương đối từ các mô-đun cục bộ được hỗ trợ. -- Các chính sách của dự án có thể được cam kết để các quy tắc tương tự theo dõi kho lưu trữ. +- Các file tải theo thứ tự bảng chữ cái trong mỗi thư mục. +- Một file phải kết thúc bằng `policies.js`, `policies.mjs`, hoặc `policies.ts`. +- Nhiều lệnh gọi `customPolicies.add()` trong một file được hỗ trợ. +- Các nhập tương đối từ các mô-đun cục bộ được hỗ trợ. +- Các chính sách của dự án có thể được cam kết để cùng các quy tắc theo kho lưu trữ. -### Tệp rõ ràng +### File tường minh -Sử dụng đường dẫn rõ ràng khi xác thực hoặc cấu hình nên đặt tên tệp nhập trực tiếp: +Sử dụng các đường dẫn tường minh khi xác thực hoặc cấu hình phải đặt tên file đầu vào trực tiếp: ```bash failproofai policies --install \ @@ -247,11 +247,11 @@ failproofai policies --install \ --scope project ``` -Các tệp rõ ràng tải trước tiên, theo sau là tệp quy ước dự án và sau đó là tệp quy ước người dùng. Một tệp được phát hiện thông qua cả hai đường dẫn được tải một lần. +Các file tường minh tải trước tiên, theo sau là các file quy ước của dự án và sau đó là các file quy ước của người dùng. Một file được phát hiện thông qua cả hai đường dẫn được tải một lần. ## Xác thực và kiểm tra -Xác thực thực hiện mô-đun thông qua trình tải sản xuất và xác nhận rằng nó đăng ký ít nhất một chính sách. +Xác thực thực thi mô-đun thông qua trình tải sản xuất và xác nhận rằng nó đăng ký ít nhất một chính sách. ```bash failproofai policies --install \ @@ -260,44 +260,44 @@ failproofai policies --install \ failproofai policies ``` -Xác thực bắt các tệp bị thiếu, lỗi cú pháp, nhập khẩu chưa giải quyết, ngoại lệ cấp cao nhất và thời gian chờ tải mô-đun. Nó không chứng minh rằng logic khớp của bạn là chính xác. +Xác thực bắt các file bị thiếu, lỗi cú pháp, nhập không được giải quyết, ngoại lệ cấp cao nhất, và hết thời gian tải mô-đun. Nó không chứng minh rằng logic khớp của bạn là chính xác. Kiểm tra ít nhất các trường hợp này: - Một hành động phải khớp và tạo ra lý do chính sách dự định. -- Một hành động gần đó nhưng an toàn phải trả về `allow()`. -- Các trường công cụ bị thiếu hoặc định dạng không đúng. -- Cú pháp lệnh thay thế, đường dẫn, dấu ngoặc, casing và khoảng trắng. -- Một quá trình con hoặc phụ thuộc mạng không có sẵn. +- Một hành động gần nhưng an toàn phải trả về `allow()`. +- Các trường tool bị thiếu hoặc sai định dạng. +- Cú pháp lệnh thay thế, đường dẫn, trích dẫn, casing và khoảng trắng. +- Một phụ thuộc con quy trình hoặc mạng không có sẵn. -Quy cho kết quả cho chính sách tùy chỉnh của bạn dưới **Observe → policy**. Một bài kiểm tra bị chặn là không đủ nếu một chính sách tích hợp khác đã đưa ra quyết định. +Ghi nhận kết quả cho chính sách tùy chỉnh của bạn dưới **Observe → policy**. Một bài kiểm tra bị chặn không đủ nếu một chính sách tích hợp sẵn khác đã đưa ra quyết định. ## Hành vi thời gian chạy -- Các chính sách tích hợp được đánh giá trước các chính sách tùy chỉnh. -- Lần `deny` đầu tiên dừng đánh giá chính sách thêm. +- Các chính sách tích hợp sẵn đánh giá trước các chính sách tùy chỉnh. +- Cái `deny` đầu tiên dừng đánh giá chính sách tiếp theo. - Nhiều kết quả `instruct` có thể được kết hợp khi không có chính sách nào từ chối sự kiện. -- Một hàm chính sách có thời hạn thực hiện 10 giây. -- Một ngoại lệ được ném hoặc thời gian chờ được ghi nhật ký và được coi là `allow()`. -- Một tệp quy ước không tải được bị bỏ qua; các tệp tùy chỉnh khác và chính sách tích hợp tiếp tục. +- Một hàm chính sách có thời hạn thực thi 10 giây. +- Một ngoại lệ bị ném hoặc hết thời gian là được ghi nhận và được coi là `allow()`. +- Một file quy ước không tải được bị bỏ qua; các file tùy chỉnh khác và chính sách tích hợp sẵn tiếp tục. - Tải mô-đun cấp cao nhất cũng có thời hạn 10 giây. -- Chế độ quan sát đám mây chạy chính sách nhưng ghi lại quyết định không phải là allow mà không thực thi nó. +- Chế độ quan sát đám mây chạy chính sách nhưng ghi nhận quyết định không phải là allow mà không áp dụng nó. -Giữ các mô-đun chính sách xác định và nhanh chóng. Tránh các cuộc gọi mạng cấp cao nhất hoặc khởi động máy chủ. Công việc ràng buộc bên trong `fn`, bắt các lỗi phụ thuộc và chọn có chủ ý liệu lỗi đó nên cho phép hay từ chối hoạt động. +Giữ các mô-đun chính sách xác định và nhanh. Tránh các lệnh gọi mạng cấp cao nhất hoặc khởi động máy chủ. Giới hạn công việc bên trong `fn`, bắt các lỗi phụ thuộc, và chọn có chủ ý xem liệu lỗi đó có nên cho phép hay từ chối hoạt động. ## Xuất API | Xuất | Mục đích | | --- | --- | -| `customPolicies.add(policy)` | Đăng ký chính sách tùy chỉnh khi mô-đun tải. | +| `customPolicies.add(policy)` | Đăng ký một chính sách tùy chỉnh khi mô-đun tải. | | `allow(reason?)` | Cho phép hoạt động. | | `instruct(reason)` | Cho phép hoạt động và cung cấp hướng dẫn nơi được hỗ trợ. | | `deny(reason)` | Chặn hoạt động nơi được hỗ trợ. | -| `getCustomHooks()` | Trả về các chính sách hiện được đăng ký trong sổ đăng ký mô-đun. | +| `getCustomHooks()` | Trả về các chính sách hiện đang được đăng ký trong sổ đăng ký mô-đun. | | `clearCustomHooks()` | Xóa sổ đăng ký đó, chủ yếu cho các bài kiểm tra và trình tải. | -TypeScript xuất `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` và `PolicyFunction`. +TypeScript xuất `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision`, và `PolicyFunction`. - - Xuất bản một phiên bản, triển khai nó ở chế độ quan sát, xác minh quyết định và chuyển đến thực thi. + + Xuất bản một phiên bản, triển khai nó trong chế độ quan sát, xác minh các quyết định, và chuyển sang thực thi. \ No newline at end of file diff --git a/docs/vi/sessions/evaluations.mdx b/docs/vi/sessions/evaluations.mdx index 821a1cd1..d2904257 100644 --- a/docs/vi/sessions/evaluations.mdx +++ b/docs/vi/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "Đánh giá trực tuyến" -description: "Chấm điểm các phiên làm việc trực tiếp và đã hoàn thành để đánh giá chất lượng, tuân thủ, chi phí và độ trễ." +title: "Đọc kết quả đánh giá" +description: "Vẽ biểu đồ điểm đánh giá theo thời gian, so sánh các agent và môi trường, xem lý do tại sao một phiên ghi điểm thấp, và hỏi trợ lý." icon: "gauge" --- -Đánh giá trực tuyến áp dụng các nhận xét nhất quán cho các phiên làm việc của agent. Sử dụng chúng cho các tín hiệu cần được đo lường liên tục thay vì chỉ được điều tra trong quá trình kiểm tra. +Kết quả từ mỗi đánh giá, được lưu trữ hoặc từ worker của riêng bạn, đều được lưu tới những nơi giống nhau. -## Xem xét chất lượng đánh giá +## So sánh điểm theo thời gian - 1. Đi tới **Observe → Evaluations**. - 2. Thêm một chuỗi và chọn agent, môi trường, điểm đánh giá, thống kê và đường cong. - 3. Thêm các chuỗi để so sánh các môi trường, agent hoặc các khóa điểm. - 4. Chọn một kết quả để mở các phiên khớp hoặc chia sẻ chế độ xem được lọc. Sử dụng **Observe → Metrics** cho độ trễ, token, chi phí và các giá trị độ lớn khác. + Đi tới **Observe → evaluations**. - ![Bảng điều khiển chất lượng hiển thị điểm đánh giá trung bình và các xu hướng theo thời gian.](/images/dashboard/dashboard-quality.png) + - **Recent runs** liệt kê từng đánh giá khi nó được ghi nhận: cho dù nó đến từ người đánh giá được lưu trữ (**managed**) hay từ người đánh giá của bạn (**customer**), agent và phiên, đánh giá và phiên bản của nó, trạng thái và điểm hoặc chỉ số của nó. + - **Score over time** vẽ biểu đồ những gì bạn yêu cầu. Chọn **add series** và lựa chọn một agent, một môi trường, một đánh giá, và một thống kê: avg, min, max, p50, p75, p90, p95, p99, stddev, hoặc mode. Mỗi series là một dòng; tạo **curve** riêng cho nó để vẽ nó trên biểu đồ riêng. - Mở một phiên từ phần chi tiết để kiểm tra lý do từng điểm: + ![Trang đánh giá: các lần chạy gần đây được gắn thẻ customer, biểu đồ điểm theo thời gian với các đường tham chiếu ở 0.5 và 0.8, và một series lấy trung bình finished_clean trên tất cả các agent và môi trường.](/images/dashboard/evaluations-chart.png) - ![Chế độ xem chi tiết phiên hiển thị điểm đánh giá và lý do bên cạnh dấu vết hoàn chỉnh.](/images/dashboard/session-detail.png) + Một phạm vi thời gian và một kích thước bin áp dụng cho mỗi series. Một bin nhỏ tìm thấy một sự cố; một bin lớn hơn thể hiện một xu hướng, và có thể ẩn các đỉnh bạn đang tìm kiếm. Một bucket mà không có gì được ghi điểm là một khoảng trống trong dòng, không bao giờ là số không, và các đường tham chiếu đánh dấu 0.5 và 0.8. + + Mỗi phần của chế độ xem nằm trong URL: **share** sao chép nó, và bất kỳ ai mở nó sẽ thấy chính xác so sánh bạn đã xây dựng. ```bash @@ -28,25 +28,29 @@ icon: "gauge" fp evals --score helpfulness:0.8.. --since 7d ``` - Thêm `--json` toàn cục trước `evals` để tự động hóa, ví dụ `fp --json evals --aggregate --env production`. + Thêm global `--json` trước `evals` để tự động hóa, ví dụ như `fp --json evals --aggregate --env production`. -Một bộ đánh giá nhận được nhận dạng phiên, môi trường, dấu thời gian và các sự kiện được sắp xếp. Nó có thể trả về các khóa điểm số với lý do tùy chọn và bản tóm tắt. Các bộ đánh giá chạy lâu dài có thể trả về một công việc đang chờ xử lý và được kiểm tra sau này. +Vẽ biểu đồ **avg** và **p90** cho cùng một đánh giá để xem liệu một trung bình tốt có đang ẩn một đuôi xấu, hoặc cùng một đánh giá cho hai agent, hoặc cho production và staging, để so sánh chúng trên một trục. Chi phí, độ trễ và số lượng token, mang các đơn vị, được vẽ biểu đồ dưới **Observe → metrics**, một biểu đồ cho mỗi đơn vị. + +## Xem lý do tại sao một phiên ghi điểm thấp + +Mở một phiên từ **Observe → sessions**; lưới thể hiện các điểm của mỗi phiên và lọc theo phạm vi điểm. Thanh bên phải của phiên bắt đầu với tóm tắt đánh giá, sau đó là một thanh cho mỗi điểm với lý do của người đánh giá dưới nó. + +![Chế độ xem chi tiết phiên hiển thị điểm đánh giá và lý do bên cạnh dấu vết hoàn chỉnh.](/images/dashboard/session-detail.png) + +## Hỏi trợ lý + +Hỏi về dữ liệu đánh giá bằng tiếng Anh đơn giản: "tell me about some of the recent evaluations", hoặc điểm của các agent nào đang giảm. [Trợ lý](/vi/sessions/assistant) đọc và phân tích kết quả và trả lời bằng các bảng bạn có thể theo dõi, và một câu hỏi đáng giữ có thể trở thành một [query](/vi/sessions/queries) hoặc một [dashboard](/vi/sessions/dashboards). -## Các mục tiêu đánh giá tốt +![Trang đánh giá bên cạnh trợ lý, trợ lý trả lời "tell me about some of the recent evaluations" bằng tóm tắt tổng số, trạng thái và điểm.](/images/dashboard/evaluations-assistant.png) -- Hoàn thành hoặc độ chính xác của tác vụ -- Tính dựa trên cơ sở và rủi ro ảo tưởng -- Lựa chọn công cụ và hiệu quả sử dụng công cụ -- Tuân thủ chính sách hoặc quy trình -- Ngân sách chi phí và độ trễ -- Yêu cầu leo thang cho con người +## Giám sát và hành động -## Từ điểm đến phản hồi +- **Dashboards**, dưới **Analyze → dashboards**, theo dõi xu hướng các điểm bạn giới thiệu, trên mỗi agent và môi trường, cho toàn bộ tổ chức. -Hiển thị điểm trên bảng điều khiển để theo dõi xu hướng. Tạo cảnh báo cho các ngưỡng hoặc điều kiện tổng hợp. Khi một điểm giảm trên toàn bộ dân số, hãy chạy một cuộc kiểm tra để điều tra lý do; khi nguyên nhân là một hành động có thể lặp lại, hãy triển khai một chính sách. + ![Bảng điều khiển chất lượng hiển thị các điểm đánh giá trung bình và xu hướng theo thời gian.](/images/dashboard/dashboard-quality.png) - - Triển khai đánh giá đồng bộ hoặc không đồng bộ với Python evaluator SDK. - \ No newline at end of file +- **Alerts** thông báo cho bạn khi một điểm vượt qua ngưỡng. Xem [alerts](/vi/audits/alerts). +- Khi một điểm giảm trong nhiều phiên, [chạy một audit](/vi/audits/run) để tìm hiểu lý do; khi nguyên nhân là một hành động có thể lặp lại, [viết một policy](/vi/policies/editor). \ No newline at end of file diff --git a/docs/vi/start/integrations/custom-agents.mdx b/docs/vi/start/integrations/custom-agents.mdx index 31fc9ed0..6a0b9f03 100644 --- a/docs/vi/start/integrations/custom-agents.mdx +++ b/docs/vi/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "Các agent tùy chỉnh" sidebarTitle: "Các agent tùy chỉnh" -description: "Instrument một agent mà bạn đã viết, hoặc một framework mà Failproof AI không có adapter cho." +description: "Công cụ hóa một agent bạn tự viết hoặc một framework mà Failproof AI không có adapter cho." icon: "code" --- -Đối với một agent mà bạn đã viết hoặc một framework mà Failproof AI không có adapter cho. Không có gì để instrument: bạn phát ra các sự kiện. +Đối với một agent mà bạn tự viết, hoặc một framework mà Failproof AI không có adapter cho. Không có gì phải công cụ hóa: bạn phát ra các sự kiện. -Đây là cùng một API mà bốn framework adapter gọi bên dưới. Chúng là bảng dịch lên nó. +Đây là cùng một API mà bốn adapter framework gọi bên dưới. Chúng là các bảng dịch của nó. ## Cài đặt @@ -15,42 +15,42 @@ icon: "code" pip install failproofai-sdk ``` -Không có extras và không có phụ thuộc. +Không có thêm gì, và không có phụ thuộc. -## Instrument +## Công cụ hóa ```python import failproofai_sdk failproofai_sdk.configure(environment="production") -with failproofai_sdk.session(): # một run - with failproofai_sdk.agent("planner"): # một đơn vị công việc +with failproofai_sdk.session(): # one run + with failproofai_sdk.agent("planner"): # one unit of work with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # một lệnh gọi công cụ + t.output = search(q) # one tool call ``` -Đọc từ trên xuống dưới và nó nói ra ý của nó: +Đọc từ trên xuống dưới và nó nói những gì nó có nghĩa: -| Bao bọc nó trong | Để nói | +| Bao nó trong | Để nói | | --- | --- | -| `session()` | Những sự kiện này thuộc cùng một run | -| `agent()` | Cái gì đó đang làm việc — hãy đặt tên cho nó mà bạn sẽ nhận ra trong một danh sách | -| `tool_call()` | Đây là một công cụ và đây là kết quả trả về của nó | +| `session()` | Những sự kiện này thuộc về cùng một lần chạy | +| `agent()` | Có cái gì đó đang làm việc — đặt tên cho nó bằng tên mà bạn sẽ nhận ra trong danh sách | +| `tool_call()` | Đây là một công cụ, và đây là những gì nó trả về | -Và kết quả thực tế mà mỗi cái phát ra: +Và những gì mỗi cái thực sự phát ra: | Phạm vi | Phát ra | Mục đích | | --- | --- | --- | -| `session()` | Không có gì | Ràng buộc một session id, nhóm một run | -| `agent()` | `agent_start`, `agent_end` | Đặt dấu ngoặc cho một đơn vị công việc | -| `tool_call()` | `tool_use`, `tool_result` | Đặt dấu ngoặc cho một công cụ và đo lường nó | +| `session()` | Không có gì | Liên kết một session id, nhóm một lần chạy | +| `agent()` | `agent_start`, `agent_end` | Dấu ngoặc một đơn vị công việc | +| `tool_call()` | `tool_use`, `tool_result` | Dấu ngoặc một công cụ và đo lường nó | -Mọi thứ bên trong có thể bỏ qua `session_id` và `agent_id`. Các phạm vi ràng buộc nhận dạng trên các biến ngữ cảnh và mỗi lệnh gọi sự kiện đều đọc nó trở lại, do đó bạn không bao giờ phải truyền id qua các hàm của mình. +Mọi thứ bên trong có thể bỏ qua `session_id` và `agent_id`. Các phạm vi liên kết danh tính trên các biến ngữ cảnh và mỗi lệnh gọi sự kiện đọc lại nó, vì vậy bạn không bao giờ phải điều phối các id thông qua các hàm của bạn. Cả ba đều hoạt động dưới `async with` cũng như `with`. -Lồng các agent xây dựng cây. `parent_id` và độ sâu được tính toán từ ngăn xếp: +Lồng các agent xây dựng cây. `parent_id` và độ sâu được tính từ ngăn xếp: ```python with failproofai_sdk.session(): @@ -63,18 +63,18 @@ with failproofai_sdk.session(): `agent()` xử lý ngoại lệ cho bạn: -| Chuyện gì đã xảy ra | Sự kiện | Kết quả | +| Những gì xảy ra | Sự kiện | Kết quả | | --- | --- | --- | -| Không có gì được raise | `agent_end` | `success` | +| Không có gì được nâng lên | `agent_end` | `success` | | `Exception` | `error`, sau đó `agent_end` | `failed` | | `KeyboardInterrupt`, `SystemExit` | `error`, sau đó `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | chỉ `agent_end` | `cancelled` | -Lỗi được phát ra trước `agent_end`, vì dashboard đóng span tại `agent_end` và bất kỳ thứ gì sau nó đều được ghi cho không có gì. Hủy bỏ không phải là một thất bại, do đó các run bị hủy không làm ô nhiễm bề mặt lỗi. Ngoại lệ luôn được tạo lại: một phạm vi không bao giờ nuốt chửng. +Lỗi được phát ra trước `agent_end`, bởi vì bảng điều khiển đóng span tại `agent_end` và bất cứ điều gì sau đó được quy cho không có gì. Hủy bỏ không phải là thất bại, vì vậy các lần chạy bị hủy không làm ô nhiễm bề mặt lỗi. Ngoại lệ luôn được nâng lại: một phạm vi không bao giờ nuốt chửng. ## Các phương thức sự kiện -Mười lăm phương thức trong sáu gia đình. Hầu hết đều có dạng cặp — bạn phát ra phần mở, sau đó là phần đóng, và SDK đo lường khoảng giữa chúng. +Mười năm phương thức trong sáu gia đình. Hầu hết đều đi thành cặp — bạn phát ra phần mở, sau đó là phần đóng, và SDK đo khoảng thời gian giữa chúng. | Gia đình | Mở | Đóng | Độc lập | | --- | --- | --- | --- | @@ -87,7 +87,7 @@ Mười lăm phương thức trong sáu gia đình. Hầu hết đều có dạn | **Failures** | — | — | `error` | - Ưu tiên các phạm vi — `agent()` và `tool_call()` — ở bất cứ nơi nào chúng phù hợp. Chúng đảm bảo sự kiện đóng ngay cả khi phần thân raise. Hãy sử dụng các phương thức này trực tiếp khi dòng điều khiển của bạn không lồng nhau, chẳng hạn như lệnh gọi mô hình bên trong trợ giúp. + Ưu tiên các phạm vi — `agent()` và `tool_call()` — ở bất kỳ nơi nào chúng phù hợp. Chúng đảm bảo sự kiện đóng ngay cả khi phần nội dung tăng. Chuyển đến các phương thức này trực tiếp khi luồng điều khiển của bạn không lồng nhau, chẳng hạn như lệnh gọi mô hình bên trong một trợ giúp. @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **Hai gia đình con người chỉ theo các hướng ngược lại.** + **Hai gia đình con người chỉ theo hướng ngược lại.** - | Phương thức | Nghĩa | + | Phương thức | Ý nghĩa | | --- | --- | | `human_wait` / `human_input` | **Agent yêu cầu một người** — cổng phê duyệt, câu hỏi làm rõ | - | `human_pause` / `human_interrupt` | **Một người hoạt động trên agent** — nút dừng, tạm dừng của người điều hành | + | `human_pause` / `human_interrupt` | **Một người hành động trên agent** — nút dừng, tạm dừng người điều hành | - Không có framework nào phát tín hiệu cho cặp thứ hai, do đó nó luôn là của bạn để phát ra. + Không có framework nào báo hiệu cặp thứ hai, vì vậy nó luôn là của bạn để phát ra. - **Chuyển `request_id` khi các lệnh gọi mô hình chạy song song.** Nếu không có nó, các yêu cầu và phản hồi ghép nối theo thứ tự đến hạn trên mỗi agent — và các lệnh gọi song song bị ghép nối sai, gắn mỗi phản hồi vào yêu cầu sai. + **Chuyển `request_id` khi các lệnh gọi mô hình chạy đồng thời.** Nếu không có nó, các yêu cầu và phản hồi ghép thành từng lệnh gọi trên mỗi agent — và các lệnh gọi đồng thời bị ghép sai, gắn mỗi phản hồi vào yêu cầu sai. ## Ví dụ -Một vòng lặp gọi công cụ chống lại API OpenAI, không có agent framework: +Một vòng lặp gọi công cụ trên API OpenAI, không có framework agent: ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """Một lệnh gọi mô hình, được đặt dấu ngoặc bởi cặp.""" + """One model call, bracketed by the pair.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -204,52 +204,52 @@ with failproofai_sdk.session(): }) ``` -Điều đó tạo ra cùng sáu loại sự kiện mà một adapter sẽ cho bạn. Phiên bản chạy được hoàn chỉnh, với các định nghĩa công cụ, được gửi trong kho SDK dưới `docs/manual/examples/`. +Điều đó tạo ra cùng sáu loại sự kiện mà một adapter sẽ cung cấp cho bạn. Phiên bản chạy được hoàn chỉnh, với các định nghĩa công cụ, được gửi trong kho SDK dưới `docs/manual/examples/`. -## Threads và async +## Luồng và async -Các biến ngữ cảnh lan truyền vào tác vụ asyncio tự động. Chúng không lan truyền vào các thread mới, vì một thread bắt đầu với bối cảnh trống. +Các biến ngữ cảnh lan truyền vào các tác vụ asyncio một cách tự động. Họ không lan truyền vào các luồng mới, bởi vì một luồng bắt đầu với một ngữ cảnh trống. ```python -# asyncio: không cần làm gì +# asyncio: nothing to do async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads: bao bọc callable +# threads: wrap the callable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -Nếu không có `propagate()`, các sự kiện của worker sẽ raise `TypeError` đặt tên cho bản sửa chữa thay vì hạ cánh trên không session. Điều đó là cố ý: một sự kiện không có session được bỏ qua bởi ingest và trả lời `200`, đó là lỗi yên tĩnh mà tầng nhận dạng tồn tại để ngăn chặn. +Nếu không có `propagate()`, sự kiện của worker sẽ tăng lên một `TypeError` đặt tên cho phần sửa chữa chứ không là đếm không có session. Điều này cố ý: một sự kiện không có session bị bỏ qua bằng cách nhập và trả lời `200`, đó là lỗi im lặng mà lớp danh tính tồn tại để ngăn chặn. -## Instrument một framework mà không có adapter +## Công cụ hóa một framework mà không có adapter -Mỗi agent framework đều cung cấp cho bạn ba chỗ điểm. Ánh xạ chúng và bạn có một dấu vết hoàn chỉnh — bốn adapter được gửi không làm gì nhiều hơn thế. +Mỗi framework agent cung cấp cho bạn ba đường nối tương tự. Ánh xạ chúng và bạn có một dấu vết hoàn chỉnh — bốn adapter được gửi không làm gì nhiều hơn thế. -| Chỗ điểm | Cái bạn viết | Cái hạ cánh | +| Đường nối | Những gì bạn viết | Những gì hạ cánh | | --- | --- | --- | -| Run | `session()` + `agent()` | `agent_start`, `agent_end` | +| Lần chạy | `session()` + `agent()` | `agent_start`, `agent_end` | | Mỗi công cụ | `tool_call()` | `tool_use`, `tool_result` | | Mỗi lệnh gọi mô hình | Cặp `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - Trong bất kỳ cái mà framework gọi là một bộ gói công cụ hoặc middleware. + + Ở bất kỳ nơi nào framework gọi trình bao bọc công cụ hoặc middleware. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -264,31 +264,31 @@ Mỗi agent framework đều cung cấp cho bạn ba chỗ điểm. Ánh xạ ch - **Có một node, step hoặc middleware boundary đáng nhìn?** Bao bọc nó trong một cặp hook — `hook_triggered` / `hook_completed` — không phải một `agent()` lồng nhau. `agent_id` là một facet cardinality thấp, và một entry trên mỗi node sẽ làm chìm nó. Hook span render cùng cách và cung cấp cho bạn độ trễ trên mỗi node. + **Có một nút, bước hoặc ranh giới middleware đáng xem?** Bao nó trong một cặp hook — `hook_triggered` / `hook_completed` — không phải một `agent()` lồng nhau. `agent_id` là một khía cạnh cardinality thấp, và một mục nhập trên mỗi nút làm chìm nó. Các khoảng hook hiển thị cùng cách và cung cấp cho bạn độ trễ trên mỗi nút. - **Manual và automatic kết hợp.** Một adapter chạy bên trong một phạm vi viết tay tham gia session đó và cha mẹ đó agent, do đó bạn nhận được một cây chứ không phải hai — hữu ích khi bạn instrument một framework tự mình cùng một được hỗ trợ. + **Tay và tự động soạn.** Một adapter chạy bên trong một phạm vi viết tay tham gia session đó và phụ huynh của đó, vì vậy bạn nhận được một cây chứ không phải hai — hữu ích khi bạn công cụ hóa một framework tự bên cạnh một cái được hỗ trợ. - - Hai lý do, và ba chỗ điểm ở trên là câu trả lời cho cả hai: + + Hai lý do, và ba đường nối trên là câu trả lời cho cả hai: - `autogen-core` đã không được bảo trì kể từ tháng 9 năm 2025. - - AG2 không expose điểm đăng ký toàn quy trình tương đương với các hook của framework khác, do đó instrument nó có nghĩa là bao bọc mỗi agent tại mỗi trang xây dựng. + - AG2 không cung cấp điểm đăng ký toàn bộ quy trình tương đương với các hook của các framework khác, vì vậy công cụ hóa nó có nghĩa là bao bọc mỗi agent ở mỗi trang xây dựng. - Ánh xạ các chỗ điểm bằng tay ghi lại các sự kiện tương tự, với cùng độ trung thực, như một adapter được gửi sẽ làm. + Ánh xạ các đường nối bằng tay ghi lại những sự kiện giống nhau, với cùng một độ tin cậy, như một adapter được gửi sẽ làm. ## Đi sâu hơn -Cách ghi âm thực tế hoạt động. Không cần bất kỳ thứ gì trong số này để bắt đầu. +Cách ghi âm thực sự hoạt động. Không cần thiết phải bắt đầu. - + -Mỗi bản ghi đều có hình dạng tương tự: một span mở, công việc lồng nhau bên trong nó, và mỗi sự kiện mở lại nhận được một sự kiện đóng. +Mỗi bản ghi có cùng một hình dạng: một span mở, công việc lồng nhau bên trong nó, và mỗi sự kiện mở nhận được một sự kiện đóng. ```mermaid flowchart LR @@ -300,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -**Cặp** là đơn vị. Mỗi sự kiện đóng mang theo một khoảng thời gian mà SDK đo từ cái mở của nó. +**Cặp** là đơn vị. Mỗi sự kiện đóng mang một khoảng thời gian mà SDK đo lường từ sự kiện mở của nó. -Dưới đây là một run thực trên mỗi framework — được chụp từ các ví dụ được gửi với SDK, tên mô hình được chuẩn hóa. Lưu ý có bao nhiêu quay trở lại từ một lệnh gọi duy nhất. +Dưới đây là một lần chạy thực tế trên mỗi framework — bắt được từ các ví dụ được gửi với SDK, tên mô hình bình thường hóa. Lưu ý bao nhiêu quay lại từ một lệnh gọi duy nhất. @@ -323,7 +323,7 @@ Dưới đây là một run thực trên mỗi framework — được chụp t 14 +5.721s agent_end LangGraph · success ``` - Node trở thành hook pair, do đó bạn nhận được độ trễ mỗi node mà không chúng tấn công danh sách agent. + Các nút trở thành các cặp hook, vì vậy bạn nhận được độ trễ trên mỗi nút mà không có chúng làm chìm danh sách agent. @@ -340,7 +340,7 @@ Dưới đây là một run thực trên mỗi framework — được chụp t 10 +5.739s agent_end crew · success ``` - `role` của mỗi agent trở thành tên span của nó, do đó độ trễ và chi phí token chia nhỏ theo role. + Mỗi `role` của agent trở thành tên span của nó, vì vậy độ trễ và chi tiêu token chia nhỏ theo vai trò. @@ -360,7 +360,7 @@ Dưới đây là một run thực trên mỗi framework — được chụp t 26 +7.038s agent_end Agent · success ``` - Vòng lặp agent tự nó đã hiển thị, không chỉ các lệnh gọi mô hình của nó. + Vòng lặp agent chính nó là khả nhìn thấy, không chỉ các lệnh gọi mô hình của nó. @@ -375,7 +375,7 @@ Dưới đây là một run thực trên mỗi framework — được chụp t 8 +8.119s agent_end agent · success ``` - Không có hook pair: Pydantic AI không có node hoặc step boundary để đặt dấu ngoặc. + Không có các cặp hook: Pydantic AI không có ranh giới nút hoặc bước để dấu ngoặc. @@ -388,17 +388,17 @@ Dưới đây là một run thực trên mỗi framework — được chụp t 6 +0.000s agent_end main · success ``` - Bạn phát ra các cái này tự mình. Cùng loại sự kiện, cùng độ trung thực — nó có giá là các trang gọi. + Bạn phát ra những cái này. Các loại sự kiện giống nhau, cùng độ tin cậy — nó chi phí cho bạn các trang gọi. - + -**Không có session-end event.** Một session không phải là cái gì bạn đóng — nó là một nhóm sự kiện chia sẻ một `session_id`. +**Không có sự kiện kết thúc phiên.** Một phiên không phải là cái gì bạn đóng — nó là một nhóm các sự kiện chia sẻ một `session_id`. -Trạng thái được rút ra từ hình dạng của dấu vết: +Trạng thái được lấy từ hình dạng của dấu vết: | Trạng thái | Khi nào | | --- | --- | @@ -407,17 +407,17 @@ Trạng thái được rút ra từ hình dạng của dấu vết: | `error` | Không có gì mở, và ít nhất một sự kiện thất bại | | `done` | Không có gì mở, và không có gì thất bại | -Vì vậy một session kết thúc khi mọi cặp được đóng. Các adapter phát ra `agent_end` cho bạn, và khi tắt chúng đóng bất kỳ thứ gì vẫn còn mở và đánh dấu nó không hoàn chỉnh — một run bị crash giải quyết là `done` với một khoảng trống nhìn thấy được chứ không phải treo. +Vì vậy, một phiên kết thúc khi mỗi cặp đóng. Các adapter phát ra `agent_end` cho bạn, và khi phân hủy chúng đóng bất cứ thứ gì vẫn mở và đánh dấu nó không đầy đủ — một lần chạy bị lỗi giải quyết dưới dạng `done` với một khoảng trống có thể nhìn thấy chứ không phải treo mãi mãi. - Đây là lý do tại sao một session có thể trải dài hai cuộc gọi. Một LangGraph `interrupt()` tạm dừng run, root span cố ý giữ mở, và cuộc gọi tiếp tục đóng nó. Cả hai cuộc gọi là một session. + Đây là lý do tại sao một phiên có thể kéo dài hai lệnh gọi. Một `interrupt()` LangGraph tạm dừng lần chạy, span gốc cố ý để mở, và lệnh gọi tiếp tục đóng nó. Cả hai lệnh gọi là một phiên. - + -`session_id` và `agent_id` là tùy chọn trên mỗi phương thức sự kiện. Được bỏ qua, chúng giải quyết từ phạm vi bao quanh: +`session_id` và `agent_id` là tùy chọn trên mỗi phương thức sự kiện. Bỏ qua, chúng giải quyết từ phạm vi bao quanh: ```python with failproofai_sdk.session(): @@ -425,50 +425,50 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -Vượt qua chúng một cách rõ ràng vẫn hoạt động và có ưu tiên. Nếu không có gì bị ràng buộc và không có gì bị vượt qua, cuộc gọi sẽ raise `TypeError` đặt tên cho bản sửa chữa chứ không phát ra một sự kiện không có session, mà ingest sẽ bỏ qua trong khi trả lời `200`. +Chuyển chúng rõ ràng vẫn hoạt động và ưu tiên. Không có gì liên kết và không có gì được chuyển, lệnh gọi tăng lên `TypeError` đặt tên cho phần sửa chữa chứ không phải phát ra sự kiện không có phiên, cái mà ingest sẽ bỏ qua trong khi trả lời `200`. -Các phạm vi ràng buộc nhận dạng trên các biến ngữ cảnh. Những cái đó lan truyền vào tác vụ asyncio tự động nhưng không vào thread mới — bao bọc một worker trong `failproofai_sdk.propagate()`. +Phạm vi liên kết danh tính trên các biến ngữ cảnh. Những cái đó lan truyền vào các tác vụ asyncio một cách tự động nhưng không vào các luồng mới — bao một worker trong `failproofai_sdk.propagate()`. #### Ai tạo ra id nào | Id | Được tạo bởi | Ghi chú | | --- | --- | --- | -| `session_id` | Bạn, hoặc SDK | `session("chat-42")` được sử dụng nguyên văn; bỏ qua, SDK tạo một `uuid4().hex` | -| `agent_id` | Bạn, hoặc framework | Từ `agent("analyst")`, một CrewAI `role`, một `FunctionAgent.name`. Một giá trị giống UUID bị từ chối và thay thế | -| `tool_call_id`, `hook_id`, `request_id` | Bạn, hoặc framework | Adapter tái sử dụng id run riêng của framework, đó là lý do tại sao các cặp sống sót qua thread hop | -| **Event id** | **Cloud, tại ingest** | SDK không phát ra bất kỳ cái nào | -| **`dedup_key`** | **Cloud, tại ingest** | Một hash của org, session, timestamp, type và payload. Đây là nhận dạng thực — nó làm cho một batch được thử lại bị sụp đổi thay vì nhân đôi | +| `session_id` | Bạn, hoặc SDK | `session("chat-42")` được sử dụng từng chữ; bỏ qua, SDK tạo một `uuid4().hex` | +| `agent_id` | Bạn, hoặc framework | Từ `agent("analyst")`, một `role` CrewAI, một `FunctionAgent.name`. Một giá trị trông giống như UUID bị từ chối và thay thế | +| `tool_call_id`, `hook_id`, `request_id` | Bạn, hoặc framework | Các adapter tái sử dụng các id chạy của riêng framework, đó là lý do tại sao các cặp sống sót qua bước hoa | +| **Event id** | **Cloud, tại ingest** | SDK không phát ra cái nào | +| **`dedup_key`** | **Cloud, tại ingest** | Một hash của org, phiên, dấu thời gian, loại và tải trọng. Đây là danh tính thực — nó làm cho một lô được thử lại sập thay vì sao chép | -#### Làm thế nào các adapter giải quyết `session_id` +#### Cách các adapter giải quyết `session_id` -Trận đầu tiên thắng: +Trận đấu đầu tiên thắng: -1. Một tùy chọn `session_id` rõ ràng -2. Metadata mỗi cuộc gọi +1. Một `session_id` tùy chọn rõ ràng +2. Siêu dữ liệu trên mỗi cuộc gọi 3. Phạm vi `session()` bao quanh -4. Metadata framework -5. Id run riêng của framework +4. Siêu dữ liệu framework +5. Id chạy của riêng framework -Nó không bao giờ được phát minh trong khi một cái đó tồn tại — một id tổng hợp sẽ chia một run thành nhiều session. +Nó không bao giờ được phát minh trong khi một trong những cái đó tồn tại — một id tổng hợp sẽ chia một lần chạy thành nhiều phiên. #### Giữ `agent_id` cardinality thấp -Nó là facet chính trên mọi bề mặt dashboard, và một cột `LowCardinality(String)`. Một giá trị mỗi run làm giảm chất lượng cột và lấp đầy dropdown bộ lọc bằng một entry trên mỗi run. +Đó là khía cạnh chính trên mỗi bề mặt bảng điều khiển, và một cột `LowCardinality(String)`. Một giá trị trên mỗi lần chạy làm giảm cột và lấp đầy thả xuống bộ lọc với một mục nhập trên mỗi lần chạy. Các adapter bảo vệ cột đó cho bạn: -| Framework trao | Ghi lại là | Tại sao | +| Framework trao | Được ghi lại dưới dạng | Tại sao | | --- | --- | --- | -| `3f9a1c2b-…` (một UUID) | `main` | Không có gì có thể đọc để giữ | +| `3f9a1c2b-…` (một UUID) | `main` | Không có gì có thể đọc được để giữ | | Một chuỗi hex trần dài | `main` | Giống nhau | -| `agent-3f9a1c2b-…` | `agent` | Id per-run bị tước, phần có thể đọc được được giữ | -| `agent-v2` | `agent-v2` | Các phân đoạn ngắn bị bỏ lại | +| `agent-3f9a1c2b-…` | `agent` | Id trên mỗi lần chạy bị tước, phần có thể đọc được được giữ | +| `agent-v2` | `agent-v2` | Các đoạn ngắn bị bỏ lại | | `step-3` | `step-3` | Giống nhau | -Id thực được giữ trên `fw_agent_id` / `fw_run_id`, nơi nó vẫn có thể truy vấn được mà không phải là một facet. +Id thực được giữ trên `fw_agent_id` / `fw_run_id`, nơi nó vẫn có thể truy vấn được mà không là một khía cạnh. - **Cái này bảo vệ chỉ các nhãn *framework* được chọn.** Một `agent_id` bạn vượt qua chính mình — để `event.*`, hoặc để `failproofai_sdk.agent(...)` — được ghi lại chính xác như được cho. Yên tĩnh viết lại một argument rõ ràng sẽ tồi tệ hơn cardinality nó ngăn chặn, vì vậy hãy đặt tên cho span của riêng bạn cho phù hợp. + **Bảo vệ này chỉ chạm vào các nhãn mà *framework* lựa chọn.** Một `agent_id` mà bạn tự chuyển — để `event.*`, hoặc để `failproofai_sdk.agent(...)` — được ghi lại chính xác như đã cho. Im lặng viết lại một đối số rõ ràng sẽ tệ hơn cardinality mà nó ngăn chặn, vì vậy đặt tên cho các span của riêng bạn phù hợp. @@ -484,25 +484,25 @@ Id thực được giữ trên `fw_agent_id` / `fw_run_id`, nơi nó vẫn có t | Humans | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | Failures | `error` | -Framework nào ghi lại cái gì, được đo từ các run ở trên: +Framework nào ghi lại gì, được đo lường từ các lần chạy trên: | Sự kiện | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | | --- | :--: | :--: | :--: | :--: | :--: | | Bắt đầu và kết thúc agent | Có | Có | Có | Có | Bạn | -| Yêu cầu và phản hồi mô hình | Có | Có | Có | Có | Bạn | +| Yêu cầu mô hình và phản hồi | Có | Có | Có | Có | Bạn | | Sử dụng công cụ và kết quả | Có | Có | Có | Có | Bạn | -| Hook triggered và completed | Node | Task | Step | — | Bạn | +| Hook được kích hoạt và hoàn thành | Nút | Nhiệm vụ | Bước | — | Bạn | | Lỗi | Có | Có | Có | Có | Tự động | -| Con người chờ và nhập | Có | Có | Có | — | Bạn | -| Tạm dừng và tiếp tục agent | Có | Có | Có | — | Bạn | +| Con người chờ và đầu vào | Có | Có | Có | — | Bạn | +| Agent tạm dừng và tiếp tục | Có | Có | Có | — | Bạn | -Một dấu gạch ngang có nghĩa là framework không có khái niệm như vậy. `human_pause` và `human_interrupt` mô tả một *người* hoạt động trên agent, mà không có framework nào phát tín hiệu — phát ra những cái đó tự mình. +Một dấu gạch ngang có nghĩa là framework không có khái niệm như vậy. `human_pause` và `human_interrupt` mô tả một *người* hành động trên agent, mà không có framework nào báo hiệu — tự phát ra những cái đó. -Một sự kiện không bao giờ đến một mình. Một mở một span, một đóng nó, và sự kiện đóng mang theo một khoảng thời gian mà SDK đo từ cái mở của nó. +Một sự kiện không bao giờ đến một mình. Một cái mở một span, một cái đóng nó, và sự kiện đóng mang một khoảng thời gian mà SDK đo lường từ sự kiện mở của nó. | Mở | Đóng | Sự kiện đóng mang theo | | --- | --- | --- | @@ -510,44 +510,44 @@ Một sự kiện không bao giờ đến một mình. Một mở một span, m | `model_request` | `model_response` | token, `stop_reason`, độ trễ | | `tool_use` | `tool_result` | `output` hoặc `error`, khoảng thời gian | | `hook_triggered` | `hook_completed` | `outcome`, khoảng thời gian | -| `agent_pause` | `agent_resume` | tạm dừng kéo dài bao lâu | -| `human_wait` | `human_input` | câu trả lời, và người tốn bao lâu | +| `agent_pause` | `agent_resume` | bao lâu tạm dừng kéo dài | +| `human_wait` | `human_input` | câu trả lời, và bao lâu người đó mất | - Một sự kiện mở mà không có sự kiện đóng là một span không bao giờ hoàn thành. Session render như vẫn đang chạy, mãi mãi, và khoảng thời gian hoạt động của nó tiếp tục tăng. Đây là chế độ thất bại để xem khi bạn instrument bằng tay. + Một sự kiện mở mà không có sự kiện đóng là một span không bao giờ kết thúc. Phiên hiển thị vẫn chạy, mãi mãi, và khoảng thời gian hoạt động của nó tiếp tục phát triển. Đây là chế độ lỗi để xem xét khi bạn công cụ hóa bằng tay. #### Quy tắc tương quan - Tái sử dụng cùng `tool_call_id`, `hook_id`, `pause_id`, hoặc `input_id` cho sự kiện hoàn thành phù hợp. -- SDK tính toán `duration_ms` cho `tool_result`, `hook_completed`, `agent_resume`, và `human_input`. Vượt qua nó cho các phương thức đó sẽ raise `ValueError`. -- `duration_ms` **được** chấp nhận trên `model_response`, vì chỉ người gọi biết độ trễ nhà cung cấp thực. Nó phải là một số nguyên — một float sẽ raise `ValueError` tại trang gọi, vì máy chủ đọc cột là một số nguyên 32-bit không dấu và sẽ lưu trữ NULL cho bất kỳ thứ gì khác. -- Kóa tương quan được định phạm vi theo loại và session, vì vậy một lệnh gọi công cụ và một hook có thể an toàn chia sẻ một id, và hai session đồng thời có thể tái sử dụng cùng id mà không va chạm. Chúng không được định phạm vi theo agent: một cặp mở dưới một agent và đóng dưới một agent khác vẫn tương quan, đây là trường hợp thông thường trong framework đa agent. -- `request_id` ghép nối `model_request` với `model_response`. Nếu không có nó, các sự kiện mô hình ghép nối theo thứ tự trên mỗi agent, vì vậy các lệnh gọi đồng thời bị ghép nối sai. -- Một cặp chia nhỏ trên các quy trình vẫn tương quan xuôi dòng, nhưng SDK không thể tính toán khoảng thời gian trong quy trình của nó. -- Bản đồ đang chờ xử lý giữ tối đa 10.000 lần bắt đầu và loại bỏ entry cũ nhất khi đầy. +- SDK tính toán `duration_ms` cho `tool_result`, `hook_completed`, `agent_resume`, và `human_input`. Chuyển nó cho những phương thức đó tăng `ValueError`. +- `duration_ms` **được** chấp nhận trên `model_response`, bởi vì chỉ người gọi biết độ trễ nhà cung cấp thực sự. Nó phải là một số nguyên — một float tăng `ValueError` tại trang gọi, bởi vì máy chủ đọc cột dưới dạng số nguyên 32-bit không dấu và sẽ lưu trữ NULL cho bất cứ điều gì khác. +- Khóa tương quan được phạm vi theo loại và phiên, vì vậy lệnh gọi công cụ và một hook có thể an toàn chia sẻ một id, và hai phiên đồng thời có thể tái sử dụng các id giống nhau mà không va chạm. Chúng không được phạm vi bởi agent: một cặp mở dưới một agent và đóng dưới một agent khác vẫn tương quan, đó là trường hợp thông thường trong các framework đa agent. +- `request_id` ghép `model_request` với `model_response`. Nếu không có nó, các sự kiện mô hình ghép theo thứ tự trên mỗi agent, vì vậy các lệnh gọi đồng thời bị ghép sai. +- Một cặp phân tách qua các quy trình vẫn tương quan xuôi dòng, nhưng SDK không thể tính toán khoảng thời gian trong quy trình của nó. +- Bản đồ chờ đợi giữ tối đa 10.000 bắt đầu và loại bỏ mục nhập cũ nhất khi đầy. - + -Cài đặt `failproofai-sdk` cài đặt mọi thứ, cả bốn adapter được bao gồm. Các extras kéo vào **framework**, không phải adapter. +Cài đặt `failproofai-sdk` cài đặt mọi thứ, cả bốn adapter được bao gồm. Các extras kéo **framework**, không phải adapter. ```python -import failproofai_sdk # tải không có gì ngoài thư viện tiêu chuẩn -failproofai_sdk.instrument() # nhập chỉ các adapter bạn thực sự cần +import failproofai_sdk # loads nothing outside the standard library +failproofai_sdk.instrument() # imports only the adapters you actually need ``` -`import failproofai_sdk` được hợp đồng bằng không phụ thuộc, thực thi bởi một bài kiểm tra cài đặt wheel xây dựng với `--no-deps` và một cái khác chứng minh không frame framework nào đạt `sys.modules`. +`import failproofai_sdk` được hợp đồng không phụ thuộc, được thực thi bởi một bài kiểm tra cài đặt bánh xe xây dựng với `--no-deps` và một bài kiểm tra khác chứng minh không có framework nào đến `sys.modules`. - Không có thuộc tính `failproofai_sdk.crewai`. Các adapter cố ý không được expose trên gói cấp cao: chạm vào một cái sẽ nhập framework như một tác dụng phụ của việc truy cập thuộc tính, phá vỡ lời hứa zero-dependency. Sử dụng `instrument()`. + Không có thuộc tính `failproofai_sdk.crewai`. Các adapter cố ý không được phơi bày trên gói cấp cao: chạm vào một cái sẽ nhập framework như một tác dụng phụ của truy cập thuộc tính, phá vỡ lời hứa không phụ thuộc. Sử dụng `instrument()`. ```python -failproofai_sdk.instrument() # mỗi framework đã được nhập -failproofai_sdk.instrument("crewai") # chính xác một, theo tên -failproofai_sdk.uninstrument("crewai") # đặt nó trở lại +failproofai_sdk.instrument() # every framework already imported +failproofai_sdk.instrument("crewai") # exactly one, by name +failproofai_sdk.uninstrument("crewai") # put it back ``` | Tên | Cũng chấp nhận | @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # đặt nó trở lại | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -Phát hiện tự động đọc `sys.modules`, không phải danh sách gói được cài đặt, vì vậy một framework mà bạn có cài đặt nhưng không bao giờ nhập không được instrument và không bao giờ được nhập thay mặt bạn. Để xem cái gì được kết nối: +Tự động phát hiện đọc `sys.modules`, không phải danh sách gói được cài đặt, vì vậy một framework bạn đã cài đặt nhưng không bao giờ nhập không được công cụ hóa và không bao giờ được nhập thay bạn. Để xem những gì được kết nối: ```python from failproofai_sdk.integrations import active, available @@ -567,50 +567,50 @@ active() # ('langchain',) ``` - **`instrument("crewai")` trên một máy không có CrewAI sẽ không raise.** Nó ghi lại cảnh báo và trả lại `()`, vì vậy một framework bị thiếu không bao giờ đánh bại một quy trình cũng instrument những cái khác. + **`instrument("crewai")` trên máy không có CrewAI không tăng.** Nó ghi một cảnh báo và trả về `()`, vì vậy một framework bị thiếu không bao giờ hạ một quy trình cũng công cụ hóa những cái khác. - Cảnh báo mang theo `ImportError` cơ bản, và thông điệp đó đặt tên cho lệnh cài đặt chính xác — vì vậy bản sửa chữa nằm trong log của bạn, không bị ẩn. + Cảnh báo mang theo `ImportError` cơ bản, và tin nhắn đó đặt tên cho lệnh cài đặt chính xác — vì vậy bản sửa chữa nằm trong nhật ký của bạn, không bị ẩn. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - Đặt `FAILPROOFAI_SDK_STRICT=1` để có nó raise thay thế. Cái cờ đó được đọc **một lần và cached**, vì vậy xuất nó trước khi quy trình của bạn bắt đầu thay vì đặt nó giữa run. + Đặt `FAILPROOFAI_SDK_STRICT=1` để làm cho nó tăng thay thế. Cờ đó được đọc **một lần và được lưu trong bộ đệm**, vì vậy xuất khẩu nó trước khi quy trình của bạn bắt đầu chứ không phải đặt nó giữa cuộc chạy. - **`instrument()` phải đến *sau* nhập framework của bạn.** Phát hiện tự động đọc `sys.modules`, vì vậy một lệnh gọi trần ở trên nhập tìm không có gì, cài đặt không có gì, và trả lại `()`. + **`instrument()` phải đến *sau* nhập framework của bạn.** Tự động phát hiện đọc `sys.modules`, vì vậy một cuộc gọi trần trên nhập tìm không có gì, cài đặt không có gì, và trả về `()`. -```python Sai +```python Wrong import failproofai_sdk -failproofai_sdk.instrument() # sys.modules không có langchain chưa -> () +failproofai_sdk.instrument() # sys.modules has no langchain yet -> () -import langchain # quá muộn, không có gì được kết nối +import langchain # too late, nothing is wired ``` -```python Đúng -import langchain # nhập framework trước +```python Right +import langchain # import the framework first import failproofai_sdk -failproofai_sdk.instrument() # tìm thấy nó -> ('langchain',) +failproofai_sdk.instrument() # finds it -> ('langchain',) ``` -```python Đúng, order-proof +```python Right, order-proof import failproofai_sdk -# Đặt tên nó nhập adapter theo yêu cầu, vì vậy điều này hoạt động từ bất cứ đâu. +# Naming it imports the adapter on request, so this works from anywhere. failproofai_sdk.instrument("langchain") ``` -Làm sai điều này và quy trình chạy với SDK được nhập, adapter rõ ràng được cài đặt, và **không một sự kiện nào được phát ra**. Nó ghi lại cảnh báo nói chính xác điều đó — vì vậy hãy kiểm tra log của bạn trước khi một run ghi lại không có gì. +Sai cái này và quy trình chạy với SDK được nhập, adapter rõ ràng được cài đặt, và **không một sự kiện được phát ra**. Nó ghi một cảnh báo nói chính xác điều đó — vì vậy kiểm tra nhật ký của bạn trước khi một lần chạy ghi lại không có gì. - + ```mermaid flowchart LR @@ -623,100 +623,102 @@ flowchart LR | Giai đoạn | Công việc | Chạy trong | | --- | --- | --- | -| Adapter | Dịch một callback framework thành một trong 15 loại sự kiện | Quy trình của bạn | -| Writer | Xếp hàng, batch, viết JSONL nguyên tử | Quy trình của bạn, thread nền | -| Spool | Handoff bền vững, sống sót qua quy trình của bạn thoát | Đĩa cục bộ | -| Daemon | Xem spool, ship batch, xóa cái nó gửi | Máy của bạn | -| Ingest | Gán một hàng id và dedup key, quảng bá các cột có thể truy vấn | Cloud | +| Adapter | Dịch lệnh gọi lại framework thành một trong 15 loại sự kiện | Quy trình của bạn | +| Writer | Xếp hàng, hàng loạt, viết JSONL một cách nguyên tử | Quy trình của bạn, luồng nền | +| Spool | Bàn giao bền, sống sót qua quá trình thoát của bạn | Đĩa cục bộ | +| Daemon | Xem spool, tàu hàng loạt, xóa những gì nó gửi | Máy của bạn | +| Ingest | Gán một hàng id và khóa dedup, thúc đẩy các cột có thể truy vấn | Cloud | -Spool là những gì làm điều này an toàn: agent của bạn không bao giờ chặn trên mạng, và một Cloud outage có nghĩa là một thư mục phát triển thay vì các sự kiện bị mất. +Spool là những gì làm cho điều này an toàn: agent của bạn không bao giờ chặn trên mạng, và mất điện Cloud có nghĩa là một thư mục phát triển chứ không phải các sự kiện bị mất. -Mỗi flush viết một file batch, `.tmp` trước, sau đó `fsync`, sau đó một rename nguyên tử: +Mỗi xóa viết một tệp lô, `.tmp` đầu tiên, sau đó `fsync`, sau đó một đổi tên nguyên tử: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -Daemon chỉ nhặt `.jsonl`, vì vậy nó không bao giờ đọc một file nửa viết. Thân mác mang theo một timestamp, process id và số thứ tự, vì vậy hai quy trình flush trong cùng một mili giây không thể va chạm. Hàng đợi được cắt ở 10.000 sự kiện; quá những gì nó thả cái cũ nhất và ghi lại. +Daemon chỉ nhặt `.jsonl`, vì vậy nó không bao giờ có thể đọc một tệp nửa viết. Thân phần mang một dấu thời gian, id quy trình và số thứ tự, vì vậy hai quy trình xóa trong cùng một mili giây không thể va chạm. Hàng đợi bị giới hạn ở 10.000 sự kiện; quá điểm đó, nó bỏ cái cũ nhất và ghi nhật ký. - **`collector.redact` mặc định `minimal` cho sự kiện SDK quá.** SDK tẩy sạch trước khi viết một batch để đĩa, và daemon lặp lại cùng một pass xác định trước khi tải lên vì vậy batch từ SDK cũ được bảo vệ. + **`collector.redact` không áp dụng cho các sự kiện SDK của bạn.** Nó không bao giờ nhìn thấy chúng. -Daemon đọc mỗi batch và áp dụng redaction trong bộ nhớ trước khi tải lên. Nó không viết lại file spool nó đọc. +Daemon **tàu** lô của bạn. Nó không mở hoặc viết lại chúng. -| Sự kiện | Viết bởi | Nơi redaction tối thiểu chạy | +| Sự kiện | Viết bởi | Được chỉnh sửa bởi `collector.redact`? | | --- | --- | --- | -| Phiên bản ghi session CLI | Daemon | Trước daemon viết batch | -| Hoạt động hook | Daemon | Trước daemon viết batch | -| **Mọi thứ SDK phát ra** | **Quy trình của bạn** | **Trước SDK viết batch và lại trước daemon tải lên** | +| Bản ghi phiên CLI | Daemon | Có | +| Hoạt động hook | Daemon | Có | +| **Mọi thứ SDK phát ra** | **Quy trình của bạn** | **Không** | -Đặt `collector.redact` để `off` chỉ khi payload nguyên văn là một yêu cầu rõ ràng; SDK và daemon cả sẽ tôn trọng cài đặt đó. Redaction tối thiểu bắt các API key chung, bearer token, JWT, và gán bí mật. Nó không thể xác định đặc biệt prose nhạy cảm. +Chỉnh sửa chạy ở nơi daemon *viết* sự kiện riêng của nó — không phải ở nơi lô được *gửi*. Vì vậy, một lời nhắc hoặc một đối số công cụ giữ một khóa API vẫn giữ nó trên lẫn. + +Điều đó cố ý. Đây là các cuộc gọi công cụ hóa của riêng bạn, và viết lại chúng trong quá trình không có nghĩa là các sự kiện bạn nhận được không phải là các sự kiện bạn phát ra. - **Bạn kiểm soát payload tại nguồn, ở hai nơi:** + **Bạn kiểm soát tải trọng tại nguồn, ở hai nơi:** - - Tắt chụp nội dung trên adapter. **Tên tùy chọn khác nhau, và một adapter không có tùy chọn** — đây không phải là một công tắc phổ quát duy nhất: + - Tắt quay phim nội dung trên adapter. **Tên tùy chọn khác nhau, và một adapter không có cái nào** — đây không phải là một công tắc chung duy nhất: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **không công tắc nội dung nào cả**; `session_id` là tùy chọn duy nhất nó đọc, vì vậy prompt và completion luôn được ghi lại. + - CrewAI — **không có công tắc nội dung nào cả**; `session_id` là tùy chọn duy nhất nó đọc, vì vậy lời nhắc và hoàn thành luôn được ghi lại. - `instrument()` thả các tùy chọn mà adapter không đọc, vì vậy vượt qua tên sai sẽ không raise và không thay đổi gì cả. - - Đừng trao bí mật để `input=` ở nơi đầu tiên. + `instrument()` bỏ các tùy chọn một adapter không đọc, vì vậy chuyển tên sai không tăng và không thay đổi gì. + - Đừng trao bí mật cho `input=` ở nơi đầu tiên. - `collector.redact` là bảo vệ sâu, không thay thế cho bất kỳ cái. + `collector.redact` không phải là thay thế cho cái nào cả. - **Một thư mục spool trống là trạng thái khoẻ mạnh.** Đừng sử dụng nó để kiểm tra giao hàng. + **Một thư mục spool trống là trạng thái lành mạnh.** Đừng sử dụng nó để kiểm tra giao hàng. -Daemon xóa mỗi batch trong mili giây gửi nó, vì vậy một `ls` đua daemon và hiển thị một phần của cái bạn phát ra — không thể phân biệt từ một SDK ghi lại không có gì. +Daemon xóa mỗi lô trong vài mili giây gửi nó, vì vậy một `ls` đua với bộ sưu tập và cho thấy một phần nhỏ những gì bạn phát ra — không thể phân biệt với một SDK không ghi lại được gì. -Để xác nhận sự kiện thực sự hạ cánh, kiểm tra dashboard. Để xem spool lấp đầy, dừng daemon trước. +Để xác nhận các sự kiện thực sự hạ cánh, kiểm tra bảng điều khiển. Để xem spool lấp đầy, dừng daemon trước tiên. - + -Mỗi callback chạy bên trong một bộ gói có công việc duy nhất là tạo lại, vì vậy cuộc gọi của bạn nằm trong chính xác một `try` và mọi thứ SDK làm xảy ra bên ngoài nó. +Mỗi cuộc gọi lại chạy bên trong một trình bao bọc công việc duy nhất của nó là nâng lên lại, vì vậy cuộc gọi của bạn nằm trong chính xác một `try` và mọi thứ SDK làm xảy ra bên ngoài nó. -| Chuyện gì xảy ra | Kết quả | +| Những gì xảy ra | Kết quả | | --- | --- | -| Một hook raise | Ghi lại một lần với traceback của nó. Cuộc gọi của bạn không bị ảnh hưởng | -| Hook tương tự raise ba lần | Cái hook đó bị vô hiệu hóa cho phần còn lại của quy trình, với một hàng lỗi | -| `FAILPROOFAI_SDK_STRICT=1` được đặt | Ngoại lệ được tạo lại thay thế | -| Một phiên bản framework nằm ngoài phạm vi được kiểm tra | Cảnh báo một lần, instrument dù sao | -| Một khả năng duy nhất bị thiếu | Cái hook đó bị vô hiệu hóa, không bao giờ toàn bộ adapter | +| Một móc tăng | Ghi lại một lần với dấu vết của nó. Cuộc gọi của bạn không bị ảnh hưởng | +| Cùng một móc tăng ba lần | Cái móc đó bị vô hiệu hóa cho phần còn lại của quy trình, với một dòng lỗi | +| `FAILPROOFAI_SDK_STRICT=1` được đặt | Ngoại lệ được nâng lại thay thế | +| Phiên bản framework ở ngoài phạm vi được kiểm tra | Cảnh báo một lần, công cụ hóa dù sao | +| Một khả năng duy nhất bị thiếu | Cái móc đó bị vô hiệu hóa, không bao giờ là toàn bộ adapter | -Mặc định là đúng ở production và sai trong khi gỡ lỗi, vì nó chỉ có thể chứng minh "nó không bị sập". Đặt `FAILPROOFAI_SDK_STRICT=1` để làm cho một thất bại nuốt chửng lớn. +Giá trị mặc định là đúng trong sản xuất và sai trong khi gỡ lỗi, bởi vì nó chỉ có thể chứng minh được "nó không bị sập". Đặt `FAILPROOFAI_SDK_STRICT=1` để làm cho một thất bại bị nuốt chửng trở nên ồn ào. -## Các vấn đề phổ biến +## Vấn đề phổ biến - - Một sự kiện mở không có sự kiện đóng: một `model_request` không có `model_response`, hoặc một `tool_use` không có `tool_result`. Sử dụng các phạm vi, những cái đó đảm bảo cặp ngay cả khi phần thân raise. Nếu bạn gọi các phương thức sự kiện trực tiếp, sử dụng `try` và `finally`. + + Một sự kiện mở không có sự kiện đóng: một `model_request` không có `model_response`, hoặc một `tool_use` không có `tool_result`. Sử dụng các phạm vi, chúng đảm bảo cặp ngay cả khi phần nội dung tăng. Nếu bạn gọi các phương thức sự kiện trực tiếp, sử dụng `try` và `finally`. - - Nó được đo từ sự kiện mở phù hợp, vì vậy nó bị từ chối trên `tool_result`, `hook_completed`, `agent_resume`, và `human_input`. Nó được chấp nhận trên `model_response`, vì chỉ bạn biết độ trễ nhà cung cấp thực, và nó phải là một số nguyên. + + Nó được đo lường từ sự kiện mở phù hợp, vì vậy nó bị từ chối trên `tool_result`, `hook_completed`, `agent_resume`, và `human_input`. Nó được chấp nhận trên `model_response`, bởi vì chỉ bạn biết độ trễ nhà cung cấp thực sự, và nó phải là một số nguyên. - - Thread không bao giờ kế thừa bối cảnh. Bao bọc callable trong `failproofai_sdk.propagate()`. Xem [Thread và async](#threads-and-async). + + Luồng không bao giờ kế thừa ngữ cảnh. Bao `callable` trong `failproofai_sdk.propagate()`. Xem [Luồng và async](#threads-and-async). - Các trường bổ sung hợp nhất cuối cùng, vì vậy một cái được đặt tên như một trường thực như `model` hoặc `outcome` sẽ ghi đè nó và thay đổi một cột được lưu trữ. Namespace của bạn; các adapter sử dụng một tiền tố `fw_`. + Các trường bổ sung hợp nhất cuối cùng, vì vậy cái nào có tên giống như trường thực như `model` hoặc `outcome` sẽ ghi đè nó và thay đổi một cột được lưu trữ. Không gian tên của bạn; các adapter sử dụng tiền tố `fw_`. - - `agent_id` là một facet cardinality thấp và bạn đặt một run id vào nó. Sử dụng một role hoặc node name và đặt id thực vào một trường payload. + + `agent_id` là một khía cạnh cardinality thấp và bạn để một id chạy vào nó. Sử dụng một vai trò hoặc tên nút và để id thực vào một trường tải trọng. @@ -724,12 +726,12 @@ Mặc định là đúng ở production và sai trong khi gỡ lỗi, vì nó ch - Cặp, id, vòng đời session, và giao hàng. + Cặp, id, vòng đời phiên và giao hàng. - Theo causality thông qua session bạn vừa chụp. + Theo nhân quả thông qua phiên bạn vừa bắt được. - + LangGraph, CrewAI, LlamaIndex, và Pydantic AI. \ No newline at end of file diff --git a/docs/vi/start/quickstart.mdx b/docs/vi/start/quickstart.mdx index 6745e075..5a7f5ccf 100644 --- a/docs/vi/start/quickstart.mdx +++ b/docs/vi/start/quickstart.mdx @@ -1,17 +1,17 @@ --- -title: "Khởi động nhanh" +title: "Bắt đầu nhanh" description: "Ghi lại một phiên làm việc của agent, tìm ra lỗi, và bắt đầu ngăn chặn nó." icon: "zap" --- -Khởi động nhanh này giúp bạn tạo một máy báo cáo phiên làm việc, chạy kiểm toán, và triển khai chính sách. Sử dụng kỹ năng để thiết lập Failproof AI, hoặc thực hiện theo các bước thủ công. +Hướng dẫn bắt đầu nhanh này sẽ giúp bạn thiết lập một máy để báo cáo phiên làm việc, chạy kiểm toán, và triển khai một chính sách. Sử dụng kỹ năng để thiết lập Failproof AI, hoặc thực hiện theo các bước thủ công. -**Đường đi của bạn là gì?** Nếu agent của bạn chạy trong một trong 12 [harness](/vi/reference/harnesses) được hỗ trợ — một CLI viết mã hoặc một gateway như Hermes hoặc OpenClaw — hãy làm theo các bước dưới đây; bạn cần Node.js 20.9 trở lên. Nếu agent của bạn không có harness, hãy nhập dữ liệu bằng [Python SDK](/vi/reference/custom-agents) để tracing và kiểm toán, sau đó quay lại tại [Chạy kiểm tra lỗi đầu tiên](/vi/start/first-audit); thực thi trên đường đi đó cần một hook trong runtime của bạn. +**Con đường nào là của bạn?** Nếu agent của bạn chạy trên một trong 12 [harnesses](/vi/reference/harnesses) được hỗ trợ — một CLI mã hóa, hoặc một gateway như Hermes hay OpenClaw — hãy thực hiện theo các bước dưới đây; bạn cần Node.js 20.9 hoặc phiên bản sau. Nếu agent của bạn không có harness, hãy sử dụng [Python SDK](/vi/reference/custom-agents) để thực hiện tracing và kiểm toán, rồi quay lại [Chạy kiểm tra lỗi đầu tiên của bạn](/vi/start/first-audit); thực thi trên con đường đó cần một hook trong runtime của bạn. - + ```bash npx skills add FailproofAI/skills ``` @@ -21,19 +21,19 @@ Khởi động nhanh này giúp bạn tạo một máy báo cáo phiên làm vi Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Agent của bạn kiểm tra dự án, lựa chọn tích hợp liên quan, thực hiện thiết lập và xác minh nó. Xem [kho lưu trữ kỹ năng FailproofAI](https://github.com/FailproofAI/skills) để xem các kỹ năng riêng lẻ và các tùy chọn cài đặt nâng cao. + Agent của bạn sẽ kiểm tra dự án, chọn tích hợp phù hợp, thực hiện thiết lập, và xác minh nó. Xem [kho lưu trữ kỹ năng FailproofAI](https://github.com/FailproofAI/skills) để xem các kỹ năng riêng lẻ và các tùy chọn cài đặt nâng cao. ## Trước khi bắt đầu -1. Mở [bảng điều khiển Failproof AI](https://app.befailproof.ai) và tạo tài khoản hoặc đăng nhập bằng email công việc của bạn. -2. Chuyển đến **Administration → Keys** và tạo một khóa có `events:add` và `policies:pull`. -3. Sao chép bí mật một lần và lưu trữ nó trên máy mục tiêu: +1. Mở [bảng điều khiển Failproof AI](https://app.befailproof.ai) và tạo một tài khoản hoặc đăng nhập bằng email công việc của bạn. +2. Đi tới **Administration → Keys** và tạo một khóa với `events:add` và `policies:pull`. +3. Sao chép mã bí mật một lần, sau đó đọc nó vào shell trên máy đích. `read -s` nhận nó tại một lời nhắc không phản hồi, vì vậy nó không bao giờ xuất hiện trong lệnh: ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## Cài đặt @@ -42,12 +42,18 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - Bản ghi phiên được gửi theo mặc định. Thêm `--no-transcripts` để báo cáo hoạt động hook và quyết định chính sách mà không có nội dung bản ghi. + Một lệnh duy nhất là tất cả những gì cần thiết cho thiết lập: nó cài đặt daemon cục bộ (root một lần), kết nối hooks vào mọi CLI agent mà nó tìm thấy, và kết nối máy này với Cloud. Truyền khóa thông qua môi trường thay vì `--token` giúp tránh nó trong `ps`, nơi mọi người dùng trên máy có thể đọc các đối số của lệnh. Nó không giữ nó ra khỏi lịch sử shell — đọc nó bằng `read -s` là điều đó làm. Trong CI, hãy tiêm nó như một mã bí mật được che dấu và giữ tracing shell (`set -x`) tắt, hoặc trace sẽ in ra nó. - Nếu máy này đã có lịch sử agent, hãy xem trước và nhập bảy ngày gần đây, sau đó chờ giao hàng hoàn tất. Bỏ qua bước này trên máy mới. + Các bảng điểm phiên được gửi theo mặc định. Thêm `--no-transcripts` để báo cáo hoạt động hook và quyết định chính sách mà không có nội dung bảng điểm. + + + Không sử dụng `failproofai config --connect ` tại đây. Cờ đó đăng ký một máy **đã** được thiết lập và trả về ngay lập tức — không có daemon, không có hooks — vì vậy máy sẽ xuất hiện trong Cloud trong khi không thu thập và thực thi bất cứ điều gì. + + + Nếu máy này đã có lịch sử agent, xem trước và nhập bảy ngày gần đây, sau đó chờ để kết thúc giao hàng. Bỏ qua bước này trên một máy mới. ```bash failproofai backfill --since 7d --dry-run @@ -57,28 +63,39 @@ export FAILPROOFAI_KEY="" Mở **Sessions** trong Failproof AI và chọn một phiên được nhập. - - Điều này kết nối Failproof AI với harness của bạn và cài đặt 39 chính sách tích hợp. Sử dụng chúng để xem quyết định chính sách cục bộ và thử thực thi trước khi Failproof AI kiểm toán phiên của bạn và viết chính sách cho agent của bạn. - - Cho phép trình cài đặt phát hiện harness của bạn hoặc chỉ định một cách rõ ràng. Mỗi một trong 12 đều là một giá trị `--cli` hợp lệ — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + + Bước trước đó đã kết nối mọi CLI agent mà nó phát hiện. Chạy lại nó cho một harness cụ thể khi bạn cần, hoặc để thêm một harness được cài đặt sau. Mỗi một trong 12 đều là một giá trị `--cli` hợp lệ — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - Chặn một lệnh gọi công cụ trước khi nó chạy được xác minh trên cả 12. Gate cuối lượt được xác minh trên 8 — xem [khả năng thực thi](/vi/reference/harnesses#enforcement-capability) để xem ma trận từng harness. + Chặn một lệnh công cụ trước khi nó chạy được xác minh trên tất cả 12. Các cổng lượt kết thúc được xác minh trên 8 — xem [khả năng thực thi](/vi/reference/harnesses#enforcement-capability) để xem ma trận cho từng harness. + + + Kết nối hooks không bật chính sách. Thiết lập cố tình không chọn bất cứ điều gì — quyết định đó là của bạn — vì vậy hãy lấy một bộ: + + ```bash + failproofai policies add FailproofAI/policies + ``` + + Bộ được tìm nạp từ bản phát hành GitHub của nó, xác minh tổng kiểm tra, và được ghim vào thẻ chính xác mà nó giải quyết. Nó mang 38 chính sách và bật 10 chính sách mà bản kê khai của nó đánh dấu là an toàn để bật khi không có người trực. Sử dụng chúng để xem các quyết định chính sách cục bộ và thử thực thi trước khi Failproof AI kiểm toán các phiên của bạn và viết chính sách cho các agent của bạn. + + Đọc bất kỳ bộ nào trước khi lấy nó bằng `failproofai policies show /`, và xem [bộ chính sách](/vi/policies/packs) để chỉ lấy một phần của bộ. + + Cho đến khi cái này chạy, điều duy nhất thực thi là `block-failproofai-commands` — bảo vệ luôn bật ngăn một agent tắt Failproof AI. `failproofai policies` liệt kê những gì được bật. - Làm theo [Chạy kiểm tra lỗi đầu tiên](/vi/start/first-audit). Sử dụng một mục tiêu cụ thể như tìm các phiên mà agent đã thử lại một công cụ không hoạt động mà không thay đổi cách tiếp cận của nó. + Thực hiện theo [Chạy kiểm tra lỗi đầu tiên của bạn](/vi/start/first-audit). Sử dụng một mục tiêu cụ thể như "tìm các phiên nơi agent thử lại một công cụ không thành công mà không thay đổi cách tiếp cận của nó." - Làm theo [Ngăn chặn lỗi đầu tiên của bạn bằng một chính sách](/vi/start/first-policy). Bắt đầu ở chế độ quan sát, kiểm tra các trận đấu, sau đó thực thi phiên bản đã được xem xét. + Thực hiện theo [Ngăn chặn lỗi đầu tiên của bạn bằng chính sách](/vi/start/first-policy). Bắt đầu ở chế độ quan sát, kiểm tra các kết quả khớp, sau đó thực thi phiên bản đã xem xét. - Chạy `failproofai config --status`. Một thiết lập lành mạnh báo cáo kết nối đám mây, trạng thái daemon và liệu thực thi có bị tạm dừng hay không. + Chạy `failproofai config --status`. Một thiết lập lành mạnh báo cáo kết nối đến cloud, trạng thái daemon, và liệu thực thi có bị tạm dừng hay không. \ No newline at end of file diff --git a/docs/vi/start/setup.mdx b/docs/vi/start/setup.mdx index 76290fdf..2d0e7245 100644 --- a/docs/vi/start/setup.mdx +++ b/docs/vi/start/setup.mdx @@ -1,68 +1,89 @@ --- -title: "Chọn cách thiết lập của bạn" +title: "Chọn cài đặt của bạn" description: "Chọn thực thi cục bộ, Failproof AI Cloud, hoặc triển khai doanh nghiệp." icon: "waypoints" --- - - Cài đặt hooks và policies trên một máy. Sử dụng khi bạn cần guardrails ngay lập tức mà không cần gửi dữ liệu phiên đến Cloud. + + Thiết lập một máy mà không có khóa Cloud và lấy một gói chính sách. Sử dụng khi bạn cần các biện pháp bảo vệ ngay lập tức mà không cần gửi dữ liệu phiên đến Cloud. - Thêm phiên tập trung, kiểm toán, đánh giá trực tuyến, bảng điều khiển, cảnh báo và triển khai chính sách flotta. + Thêm phiên tập trung, kiểm tra, đánh giá trực tuyến, bảng điều khiển, cảnh báo và triển khai chính sách hạm đội. - - Sử dụng các điều khiển tổ chức, khóa có phạm vi, cơ sở hạ tầng riêng tư và yêu cầu bảo mật cụ thể cho triển khai. + + Sử dụng kiểm soát tổ chức, khóa có phạm vi, cơ sở hạ tầng riêng tư và yêu cầu bảo mật riêng cho triển khai. -## Con đường sản xuất được khuyến nghị +## Thực thi cục bộ -1. Kết nối một máy không phải sản xuất với tính năng ghi lại bản ghi đã bật. -2. Xác minh các phiên và đánh giá trong Cloud. -3. Tạo một kiểm toán cho một chế độ lỗi đã biết. +Chạy `failproofai config` mà không có khóa, sau đó lấy một gói bằng `failproofai policies add FailproofAI/policies`. Trong một thiết bị đầu cuối, chọn **Not now — stay local** khi cài đặt yêu cầu kết nối đến Cloud; khi không có thiết bị đầu cuối và không có `FAILPROOFAI_CLOUD_TOKEN`, nó sẽ ở cục bộ tự động. Daemon và hook thực thi trên máy, và không có dữ liệu phiên nào được gửi đến Cloud. Để kết nối sau, hãy làm theo các bước dưới đây. + +## Đường dẫn sản xuất được khuyến nghị + +1. Kết nối một máy không phải sản xuất với tính năng ghi âm được bật. +2. Xác minh phiên và đánh giá trong Cloud. +3. Tạo một bản kiểm tra cho một chế độ lỗi đã biết. 4. Triển khai chính sách đầu tiên ở chế độ quan sát. -5. Mở rộng sang sản xuất sau khi xem xét các kết quả trùng khớp và dương tính giả. +5. Mở rộng đến sản xuất sau khi xem xét các trận đấu và dương tính giả. -## Kết nối một máy với Cloud +## Kết nối máy đến Cloud - - 1. Đi đến **Administration → Keys** và tạo một khóa với `events:add` và `policies:pull`. - 2. Sao chép bí mật một lần duy nhất sang máy đích. - 3. Sau khi chạy lệnh kết nối CLI, hãy đi đến **Admin → enforcement** và xác nhận máy xuất hiện. + + 1. Đi đến **Administration → Keys** và tạo một khóa có `events:add` và `policies:pull`. + 2. Sao chép bí mật một lần sang máy đích. + 3. Sau khi chạy lệnh kết nối CLI, đi đến **Admin → enforcement** và xác nhận máy xuất hiện. 4. Đi đến **Observe → Events** và xác nhận sự kiện đầu tiên của nó đến. - Ngăn kéa khóa hiển thị hai quyền cần thiết bởi một máy được kết nối: tiếp thụ sự kiện và cung cấp chính sách. + Ngăn kéa khóa hiển thị hai quyền cấp cấp bởi một máy được kết nối: tiếp nhận sự kiện và cung cấp chính sách. - ![Ngăn kéa khóa API mới được sử dụng để cấp quyền tiếp thụ sự kiện và cung cấp chính sách.](/images/dashboard/key-create.png) + ![Ngăn kéa khóa API mới được sử dụng để cấp quyền tiếp nhận sự kiện và cung cấp chính sách.](/images/dashboard/key-create.png) - Sau khi kết nối, máy sẽ xuất hiện trong enforcement với trạng thái chính sách mong muốn và được báo cáo. + Sau khi kết nối, máy sẽ xuất hiện trong thực thi với trạng thái chính sách mong muốn và được báo cáo. - ![Flotta thực thi với một máy được ghi danh được mở rộng để hiển thị trạng thái chính sách mong muốn và trạng thái triển khai của nó.](/images/dashboard/enforcement-fleet.png) + ![Hạm đội thực thi với một máy được đăng ký mở rộng để hiển thị trạng thái chính sách mong muốn và trạng thái triển khai.](/images/dashboard/enforcement-fleet.png) - Sự kiện đầu tiên đến xác nhận rằng daemon có thể cung cấp dữ liệu cho Cloud, độc lập với triển khai chính sách. + Sự kiện đầu tiên đến xác nhận rằng daemon có thể cung cấp dữ liệu đến Cloud, độc lập với triển khai chính sách. - ![Luồng sự kiện trực tiếp hiển thị các sự kiện agent, model và tool gần đây.](/images/dashboard/events-stream-current.png) + ![Luồng sự kiện trực tiếp cho thấy các sự kiện agent, mô hình và công cụ gần đây.](/images/dashboard/events-stream-current.png) Tiếp tục chỉ sau khi cả máy và sự kiện đầu tiên của nó đều hiển thị. + Đọc bí mật một lần vào shell. `read -s` lấy nó ở một lời nhắc không được in echo, vì vậy nó không bao giờ xuất hiện trong lệnh hoặc trong lịch sử shell: + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + Sau đó thiết lập máy, chọn chính sách của nó và đặt tên cho nó: - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` - Thêm `--no-transcripts` khi nội dung bản ghi phải ở lại cục bộ. + `failproofai config` thực hiện toàn bộ cài đặt — daemon, hook cho mỗi agent CLI mà nó tìm thấy và kết nối Cloud — sau đó chọn không có chính sách, đó là lý do lệnh thứ hai. + + Nhãn đến **sau** kết nối, không phải trong quá trình: `failproofai config --machine-label ` đổi tên máy đã được kết nối, và trên máy chưa kết nối thì nó không làm gì cả nhưng nói như vậy. + + Thêm `--no-transcripts` khi nội dung phiên ghi âm phải ở cục bộ. + + Trong CI, đặt `FAILPROOFAI_CLOUD_TOKEN` từ kho lưu trữ bí mật thay vì `read -s`, và giữ theo dõi shell (`set -x`) tắt, hoặc theo dõi in khóa. + + + Trên máy **đã** được thiết lập, `failproofai config --connect ` đăng ký nó và không gì khác. Không sử dụng biểu mẫu đó để cài đặt lần đầu: nó quay trở lại trước khi daemon hoặc bất kỳ hook nào được triển khai, để lại máy xuất hiện trong Cloud nhưng không thu thập và thực thi gì cả. + -Kết nối với Cloud xác minh tiếp thụ sự kiện và cung cấp chính sách một cách độc lập. Do đó, một khóa có thể hợp lệ nhưng thiếu một quyền bắt buộc. Sử dụng `failproofai config --status` để xem khả năng nào được cấu hình. +Kết nối đến Cloud xác minh tiếp nhận sự kiện và cung cấp chính sách độc lập. Do đó, một khóa có thể hợp lệ nhưng thiếu một quyền cấp bắt buộc. Sử dụng `failproofai config --status` để xem khả năng nào được định cấu hình. - Thiết lập Cloud chỉ ghi thông tin xác thực cục bộ sau khi khả năng liên quan thành công. Xác minh không thành công sẽ không để một máy trông như đã kết nối khi nó không phải. + Cài đặt Cloud chỉ ghi thông tin xác thực cục bộ sau khi khả năng liên quan thành công. Xác minh không thành công không để lại máy trông như đã kết nối khi nó không phải. \ No newline at end of file diff --git a/docs/zh/admin/keys-and-permissions.mdx b/docs/zh/admin/keys-and-permissions.mdx index 9914771d..a1d686bd 100644 --- a/docs/zh/admin/keys-and-permissions.mdx +++ b/docs/zh/admin/keys-and-permissions.mdx @@ -1,29 +1,29 @@ --- title: "密钥与权限" -description: "为机器、自动化任务和操作员创建具有范围限制的 API 密钥。" +description: "为机器、自动化任务和运营方创建限定范围的 API 密钥。" icon: "key-round" --- -API 密钥归属于某个组织，并携带明确的权限配置。请为代理数据采集、策略下发、评估器、CI 自动化以及管理脚本分别使用独立的密钥。 +API 密钥归属于某个组织，并携带明确的权限配置。请为 Agent 数据摄取、策略下发、评估器、CI 自动化及管理脚本分别使用独立的密钥。 ## 创建与轮换密钥 - 1. 前往 **Administration → Keys**，点击 **new key**，并输入工作负载名称。 - 2. 选择一个权限预设，仅在预设无法满足需求时才单独调整各项权限。 - 3. 创建密钥后立即复制一次性密钥值。 - 4. 之后可打开该密钥进行权限更新、禁用或重新生成密钥值。 + 1. 前往 **Administration → Keys**，选择 **new key**，并输入工作负载名称。 + 2. 选择一个权限预设，仅在预设不满足需求时才单独调整各项权限。 + 3. 创建密钥后，立即复制其一次性密钥值。 + 4. 之后可重新打开该密钥，更新授权、禁用密钥或重新生成密钥值。 - 在创建抽屉中，您可以选择工作负载所需的最小权限范围。 + 创建抽屉是选择工作负载所需最小权限的地方。 - ![包含权限预设和单项授权的新 API 密钥抽屉。](/images/dashboard/key-create.png) + ![带有权限预设和单项授权的新建 API 密钥抽屉。](/images/dashboard/key-create.png) 创建完成后，Keys 页面将显示持久化的元数据及管理操作。一次性密钥值不会再次显示。 - ![显示密钥权限、创建时间以及重新生成和禁用操作的 API Keys 页面。](/images/dashboard/api-keys.png) + ![显示密钥权限、创建时间以及重新生成和禁用操作的 API 密钥页面。](/images/dashboard/api-keys.png) - 请定期使用此列表审查权限授予情况，并禁用已不再对应活跃工作负载的密钥。 + 请定期通过此列表审查授权，并禁用不再对应活跃工作负载的密钥。 ```bash @@ -36,39 +36,39 @@ API 密钥归属于某个组织，并携带明确的权限配置。请为代理 fp keys disable production-agents ``` - 请以安全的方式重定向或捕获创建/重新生成操作的输出，密钥值仅返回一次。 + 请安全地重定向或捕获 create/regenerate 命令的输出；密钥值仅返回一次。 已连接的 Failproof AI 机器所需的两项权限相互独立： -- `events:add` 用于发送事件和会话数据。 -- `policies:pull` 用于获取已分配的策略部署。 +- `events:add`：发送事件和会话数据。 +- `policies:pull`：获取已分配的策略部署。 -密钥值在创建或重新生成时显示。请将其存储在密钥管理器中，并在不复用操作员交互凭证的情况下进行轮换。 +密钥值在创建或重新生成时显示。请将其存入密钥管理器，并在轮换时避免复用操作人员的交互式凭据。 ## 权限目录 | 领域 | 权限 | | --- | --- | -| 事件 | `events:add`, `events:read` | -| 密钥 | `keys:create`, `keys:read`, `keys:disable`, `keys:regenerate`；`keys:update` 仅限人工会话 | -| 用户 | `users:create`, `users:read`, `users:update`, `users:delete` | -| 评估 | `evaluations:read`, `evaluations:trigger` | -| 仪表板 | `dashboards:read`, `dashboards:write`, `dashboards:delete` | -| 查询 | `queries:read`, `queries:write`, `queries:delete`, `queries:run` | +| 事件 | `events:add`、`events:read` | +| 密钥 | `keys:create`、`keys:read`、`keys:disable`、`keys:regenerate`；`keys:update` 仅限人工会话 | +| 用户 | `users:create`、`users:read`、`users:update`、`users:delete` | +| 评估 | `evaluations:read`、`evaluations:trigger`、`evaluations:run` | +| 看板 | `dashboards:read`、`dashboards:write`、`dashboards:delete` | +| 查询 | `queries:read`、`queries:write`、`queries:delete`、`queries:run` | | 助手 | `agent:use` | -| 设置 | `settings:read`, `settings:write` | -| 告警 | `alerts:read`, `alerts:write` | -| 问题 | `issues:read`, `issues:create`, `issues:close` | -| 审计 | `audits:read`, `audits:write` | -| 策略 | `policies:read`, `policies:write`, `policies:pull` | +| 设置 | `settings:read`、`settings:write` | +| 告警 | `alerts:read`、`alerts:write` | +| 问题 | `issues:read`、`issues:create`、`issues:close` | +| 审计 | `audits:read`、`audits:write` | +| 策略 | `policies:read`、`policies:write`、`policies:pull` | | 用量 | `usage:read` | -`orgs:admin` 仅保留给实例操作员使用，无法授予给组织密钥或普通成员。已停用的 `incidents:*` 和 `alerts:ack` 令牌出于兼容性仍可被接受，并会规范化映射至当前的 `issues:*` 权限。 +`orgs:admin` 为实例运营方专属权限，不能授予组织密钥或普通成员。已停用的 `incidents:*` 和 `alerts:ack` 令牌出于兼容性仍可接受，并将规范化为当前的 `issues:*` 权限。 -内置权限集包括 `read-only`、`standard` 和 `admin`。`standard` 在只读权限的基础上新增了触发评估、执行查询、处理问题以及使用助手等能力。创建密钥时会自动剥离仅限人工会话的权限，即使所选权限集中包含这些权限也不例外。 +内置权限集包括 `read-only`、`standard` 和 `admin`。`standard` 在读取权限基础上增加了评估触发、查询执行、问题响应和助手使用功能。创建密钥时，即使权限集中包含仅限人工使用的授权，也会被自动移除。 - 实例级密钥可通过 `X-AgentEye-Org` 请求头指定目标组织。在多组织部署环境中请务必明确设置该请求头；若省略，系统可能会选择默认组织。 + 实例级别的密钥可通过 `X-AgentEye-Org` 请求头指定组织。在多组织部署环境中请务必显式设置该请求头；若省略，可能会选中默认组织。 \ No newline at end of file diff --git a/docs/zh/evaluations/deploy.mdx b/docs/zh/evaluations/deploy.mdx new file mode 100644 index 00000000..48261c83 --- /dev/null +++ b/docs/zh/evaluations/deploy.mdx @@ -0,0 +1,55 @@ +--- +title: "部署和版本管理评估" +description: "部署不可变版本、查看当前线上内容、发布新版本、回滚，以及对已有会话进行评分。" +icon: "cloud-upload" +--- + +## 部署 + +在编写页面底部选择 **deploy `@`**。版本一旦发布即不可变更：此后，所有已完成且符合其条件的会话都将由该版本进行评分。 + +## 查看当前线上内容 + +**Analyze → eval authoring** 列出了您组织已托管的定义，即托管评估器为其运行的评估项目。每一行显示： + +- 名称、键、版本和结果类型 +- 源校验和，无需打开代码即可区分已部署的各个版本 +- 是否为**条件性**评估，或对**所有已完成会话**运行——条件用于将评估的范围限定到特定的 Agent 或环境 +- 超时时间、标签，以及最后修改时间 + +![托管定义列表：每个评估的名称、键、版本、结果类型、校验和、超时时间及范围，以及新建版本和启用或禁用操作。](/images/dashboard/eval-definitions.png) + +可搜索列表，或按状态筛选。您自己的 worker 注册的评估不会显示在此处；其结果在[评估页面](/zh/sessions/evaluations)上带有 **customer** 标签，而托管评估则带有 **managed** 标签。 + +一个组织最多可同时启用 100 个不同的托管评估。 + +## 发布新版本 + +在某一行上选择 **new version**。编写页面将打开并显示该版本的代码；对其进行修改、测试，然后部署。键和结果类型会保留，且不可更改。 + +发布新版本会禁用其前一版本，并将其保留在列表中。结果会保留产生它们的版本信息，因此图表可以清晰显示新逻辑是何时生效的。 + +## 回滚 + +对当前版本选择 **disable**，对您想恢复的版本选择 **enable**。不会删除任何内容，所有结果保持不变。 + +## 停止评估 + +选择 **disable**。在没有启用版本的情况下，该评估将停止对新会话运行。若要停止您自己的 worker 运行的评估，请停止注册它：将其从 worker 中移除，或停止该 worker。 + +## 对已有会话进行评分 + +评估是向前运行的：现在部署的版本不会对其部署前已结束的会话进行评分。若要对历史数据评分，请在 eval 编写页面上打开 **score sessions you already have**，选择最多 90 天的时间窗口，以及可选的单个评估，并在运行前先进行计数。计数结果即为实际运行的数量，其中每个会话与评估的配对均为一次计费评估。 + +此功能仅填补空缺。已有某次评估结果的会话将保留原结果；对同一时间窗口重复运行不会产生新的评分。 + +若要对某个会话重新评分——例如修复问题之后，或针对未正常结束的会话——请在其页面上选择 **re-evaluate**。新结果将添加到该会话的历史记录中，早期结果予以保留。 + +## 权限 + +| 权限 | 允许您 | +| --- | --- | +| `evaluations:read` | 查看结果，并打开 eval 编写页面 | +| `evaluations:trigger` | 查看、部署、版本管理、启用和禁用托管定义；测试它们；对历史数据评分；重新评估某个会话 | +| `events:read` | 在 `evaluations:trigger` 的基础上，针对真实会话进行测试，并以您的 payload 键为草稿提供依据 | +| `evaluations:run` | 运行您自己的评估器 worker | \ No newline at end of file diff --git a/docs/zh/evaluations/overview.mdx b/docs/zh/evaluations/overview.mdx new file mode 100644 index 00000000..66a6693d --- /dev/null +++ b/docs/zh/evaluations/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "评估 Agent" +description: "使用您自定义的评估为每个已完成的会话打分：托管的 Python 检查，或在您自己的 Worker 中运行的 LLM 评判器。" +icon: "gauge" +--- + +评估会对已完成的 Agent 会话进行评分。当会话结束时，所有适用于该会话且已启用的评估都会运行，并将结果记录下来，您可以在追踪记录旁边读取相应的推理过程： + +- **分数**：0 到 1 之间，可选标记为通过或未通过 +- **指标**：如计数、时长或成本，附带其单位 +- **断言**：通过或未通过 + +## 两种评估器 + +| | 托管 Python | 您自己的 Worker | +| --- | --- | --- | +| 编写方式 | 在仪表板的 **Analyze → eval authoring** 中编写 | 用 Python 编写，配合 [Evaluator SDK](/zh/reference/evaluator-sdk) | +| 运行位置 | 在 Failproof AI 托管的评估器沙箱中运行 | 在您自己的基础设施上运行 | +| 适用场景 | 确定性的、基于代码的检查 | LLM 评判器、模型调用、依赖包、密钥、网络访问、大量处理 | + +托管 Python 有意保持精简：仅支持单个表达式，无法导入模块，无法访问网络。任何需要调用模型的场景——例如用 LLM 评判器判断答案是否相关——都应改为在您自己的 Worker 中运行。两种方式都不需要入站连接：Worker 主动拉取已完成的会话，并通过出站 HTTPS 提交结果。 + +## 每个组织独立评估自己的 Agent + +评估归定义它的组织所有。实例上的每个组织独立编写自己的评估——包括检查逻辑、条件、阈值和标签——可以独立进行版本管理和部署，不会影响其他组织，也只能查看自己的结果。您可以按 Agent、环境、评估和时间筛选结果，也可以直接向助手提问。 + +## 从初稿到上线评分 + + + + 描述要衡量的内容，让助手帮您起草，或者自行编写。参见[编写评估](/zh/evaluations/write)。 + + + 在正式上线前对真实会话进行测试，测试结果不会被存储。参见[测试评估](/zh/evaluations/test)。 + + + 部署不可变版本，随着评估的演进发布新版本，并可回滚到之前的版本。参见[部署与版本管理](/zh/evaluations/deploy)。 + + + 查看分数随时间的变化趋势，比较不同 Agent 和环境的表现，并向助手提问。参见[查看评估结果](/zh/sessions/evaluations)。 + + + +评估按时间顺序向前执行：现在部署的版本将对从此刻起完成的会话进行评分。如需对已有的历史会话评分，请[进行回填](/zh/evaluations/deploy#score-sessions-you-already-have)。 \ No newline at end of file diff --git a/docs/zh/evaluations/test.mdx b/docs/zh/evaluations/test.mdx new file mode 100644 index 00000000..961c2d82 --- /dev/null +++ b/docs/zh/evaluations/test.mdx @@ -0,0 +1,29 @@ +--- +title: "测试评估" +description: "在部署前对真实会话运行评估。不存储任何数据。" +icon: "flask-conical" +--- + +在编写页面上，**测试此评估**会在不部署的情况下，将代码在评估器集群上对您的真实会话运行。不存储任何数据：此处的失败仅为预览，部署始终是被允许的。 + + + + 选择 **check**，在不对任何会话运行的情况下，根据沙箱规则编译代码和条件。 + + + 按代理、环境、时间或会话 ID 筛选匹配的会话，最多勾选 10 个。既应包含评估预期应失败的会话，也应包含预期应通过的会话。 + + + 选择 **run against N sessions**，逐行查看结果。 + + + +| 行状态 | 含义 | +| --- | --- | +| **ok** | 已运行。该行列出了返回的每个分数、指标和断言，以及耗时。 | +| **skipped** | 条件返回了 `False`，因此评估未运行。这是跳过，而非失败。 | +| Failed | 发生了异常、超时，或使用了沙箱拒绝的内容。该行会说明具体原因，**Fix it** 会在可以协助时将错误交由助手处理。 | + +![测试此评估面板：按代理选取了三个会话，两个状态为 ok，一个因条件返回 False 而被跳过。](/images/dashboard/eval-test.png) + +一旦您编辑了代码，结果就不再是最新的，它会变暗而非被重用。 \ No newline at end of file diff --git a/docs/zh/evaluations/write.mdx b/docs/zh/evaluations/write.mdx new file mode 100644 index 00000000..4c325309 --- /dev/null +++ b/docs/zh/evaluations/write.mdx @@ -0,0 +1,76 @@ +--- +title: "编写评估" +description: "描述要衡量的内容，让助手起草一个托管的 Python 评估，或者自己编写代码。LLM 评判器在您自己的 worker 中运行。" +icon: "file-pen-line" +--- + +托管评估是用 Python 编写的小型确定性程序，在仪表板中编写并在 Failproof AI 的评估器集群上运行。较复杂的逻辑——LLM 评判器、第三方包、密钥、网络调用——则在[您自己的 worker](#write-it-in-your-own-worker) 中运行。 + +## 从描述起草 + +1. 前往 **Analyze → eval authoring**，选择 **new eval**。 +2. 用自然语言描述要衡量的内容，或从 **start from an example…** 中选择，然后点击 **draft**。 +3. 检查各字段和生成的代码，然后[测试](/zh/evaluations/test)并[部署](/zh/evaluations/deploy)。 + +![评估编写页面，显示已起草的评估：描述、助手对草稿的说明，以及名称、键、版本、结果、超时、标签和条件字段。](/images/dashboard/eval-authoring-draft.png) + +起草内容基于您组织自身的事件：页面会读取过去七天内会话携带的 payload 键，因此代码读取的是真实存在的键，而非猜测。在交付草稿之前，助手会针对您最近的最多五个会话进行测试，修复所有可以确认的问题（最多三轮），并再次确认代码是否衡量了您的要求。请尽量使描述具体：过于宽泛的提示会使处理变慢，甚至可能超时。无论如何都请审查代码；部署操作从不被阻止。 + +## 设置字段 + +| 字段 | 含义 | +| --- | --- | +| name | 显示给用户的名称，之后可编辑 | +| key | 其结果图表所用的稳定标识符，例如 `code_assistant_quality_gate` | +| version | 不含空格的任意版本字符串，例如 `1.0.0` | +| result | **score**（0 到 1）、**metric**（带单位的数值）或 **assertion**（通过或不通过） | +| timeout seconds | 默认 30 秒，沙箱会在 60 秒时停止任何单次运行 | +| labels | 最多 20 个，以逗号分隔，之后可编辑 | +| condition | 可选。一个 Python 表达式；仅当表达式结果为 `True` 的会话才会执行评估 | + +使用 condition 将评估限定到目标 agent 和环境： + +```python +session.agent_id == "code-assistant" and session.environment == "production" +``` + +键、版本、结果类型、条件和代码在部署后不可修改：如需更改其中任何一项，请发布新版本。名称、标签及是否启用可随时编辑。 + +## 自己编写代码 + +**evaluator code** 是一个返回 `EvalResult(...)` 的 Python 表达式，作用域内包含 `session`。以下示例对状态为 ok 的工具调用结果占比进行评分： + +```python +EvalResult( + score=Score( + len([e for e in session.events_of_type("tool_result") if e.payload.get("status") == "ok"]) + / max(1, session.count("tool_result")) + ), + metrics={"tool_calls": Metric(session.count("tool_use"), unit="calls")}, + reasoning="Share of tool results that came back ok.", +) +``` + +结果以评估本身的键为主，按其声明的类型：score 类评估用 `score=`，metric 或 assertion 类评估则在 `metrics` 或 `assertions` 中使用以该键命名的条目。其他指标和断言可附带其中，每次运行最多 25 个结果。 + +| 作用域内 | 提供内容 | +| --- | --- | +| `session` | `session_id`、`agent_id`、`environment`、`started_at`、`ended_at`、`event_count` 和 `events`，以及 `count(event_type)` 和 `events_of_type(event_type)` | +| 每个事件 | `id`、`ts`、`event_type` 和 `payload` | +| 结果类型 | `EvalResult`、`Score`、`Metric`、`Assertion`，以及用于条件的 `ConditionResult` | +| 内置函数 | `abs`、`all`、`any`、`bool`、`dict`、`float`、`int`、`len`、`list`、`max`、`min`、`range`、`round`、`set`、`sorted`、`str`、`sum`、`tuple` | + +除此之外均不可访问：不允许 import，也不能访问超出会话数据以及 `get`、`lower`、`split` 等普通字符串和字典方法的属性（这些方法必须被调用，而非仅引用）。Payload 键取决于您的 agent 发送的内容——上面的 `status` 仅为示例——因此请从真实会话中读取。**format** 可整理代码格式，**fix** 可让助手修复代码。代码最大 128 KiB，条件最大 16 KiB。 + +![评估器代码编辑器，带有 format 和 fix 功能，显示已起草评估的断言内容。](/images/dashboard/eval-authoring-code.png) + +## 在您自己的 worker 中编写 + +当评估需要模型、第三方包、密钥或网络时，请使用 [Evaluator SDK](/zh/reference/evaluator-sdk) 编写，并在您自己的基础设施上运行。它使用相同的结果类型，其结果会与托管评估一同显示，标记为 **customer**： + +```python +@app.eval("answer_relevance", version="judge-v1", labels=["llm_judge"], timeout_seconds=30) +async def answer_relevance(session): + value, reasoning = await ask_judge(session) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) +``` \ No newline at end of file diff --git a/docs/zh/policies/deploy.mdx b/docs/zh/policies/deploy.mdx index 80d5ff0c..f46a8353 100644 --- a/docs/zh/policies/deploy.mdx +++ b/docs/zh/policies/deploy.mdx @@ -1,51 +1,94 @@ --- title: "部署策略" -description: "将已审核的策略版本推送到目标机器。" +description: "将经过测试的策略版本以观察模式部署到机器上，强制执行，并确认每台机器都已接收到该版本。" icon: "cloud-upload" --- -部署将一个或多个策略版本关联到一组已注册的目标机器。 +部署会将已发布的策略版本推送到机器上，每个版本具有以下两种效果之一： -## 应用部署 +- **观察（Observe）** 记录策略本应执行的操作，但不阻止任何内容。 +- **强制（Enforce）** 根据决策采取行动：`deny` 会阻止调用，`instruct` 会引导代理。 + +## 添加机器 + +机器连接到 Cloud 后，会出现在 **Admin → enforcement** 下。如果目标机器尚未显示： - + + 1. 前往 **Administration → Keys**，创建一个包含 `policies:pull`（用于接收部署）和 `events:add`（用于将决策上报到 Cloud）权限的密钥。 + 2. 使用该密钥连接机器 — 具体步骤请参阅 [将机器连接到 Cloud](/zh/start/setup#connect-a-machine-to-cloud)。 + 3. 确认机器出现在 **Admin → enforcement** 下。 + + + 在机器上执行： + + ```bash + npm install -g failproofai + failproofai config + failproofai config --status + ``` + + 在终端中，`failproofai config` 会询问是否连接到 Cloud，并通过掩码提示符接收密钥。然后可在任意位置使用 `fp fleet list` 确认机器已成功注册。 + + + +## 以观察模式部署 + + + 1. 前往 **Admin → enforcement**，找到目标机器并展开其行。 - 2. 选择 **edit**，添加已审核的策略版本，并选择 **observe** 或对应的执行效果。 - 3. 应用更改，等待机器下次签入，然后确认其部署状态和覆盖状态。 + 2. 选择 **edit**，添加已测试的策略版本，并选择 **observe**。 + 3. 应用更改，等待机器下次签入，然后确认其部署和覆盖状态。 4. 前往 **Observe → policy** 查看实时决策。 - ![机器部署编辑器，包含策略版本、enforce 和 observe 效果，以及应用部署操作。](/images/dashboard/enforcement-editor.png) + ![机器部署编辑器，显示策略版本、强制和观察效果以及应用部署操作。](/images/dashboard/enforcement-editor.png) - 使用 `fp fleet` 通过 CLI 进行部署。在应用之前请先审查生成的配置集——`deploy` 会打印完整计划，并**仅在不带 `--json` 的交互式终端中进行确认提示**。使用 `--json`、`--yes` 或重定向 stdin 时（如 CI 步骤、脚本、Agent 调用），将直接应用，不显示计划也不提示确认——因此如需审查，请先运行 `fp fleet show `： - ```bash fp fleet list fp fleet show - fp fleet deploy --add no-force-push + fp fleet deploy --add no-force-push:observe ``` - `fp fleet diff ` 显示预期配置与实际下发之间的差异（机器在下次轮询前会显示为 `behind`），`fp fleet history ` 列出历史版本，`fp fleet rollback ` 可回滚到指定版本——若该版本引用了已禁用或已删除的策略，则回滚将被拒绝。 + `:observe` 后缀决定了观察模式：不带后缀的 `--add no-force-push` 会保持该策略在机器上原有的效果，默认为强制执行。之后可通过 `--add no-force-push:enforce` 切换为强制模式。 - 使用 `failproofai config --status` 检查机器本身的状态，并在部署后通过 `fp sessions --env production --since 24h` 和 `fp events --event-type hook_completed` 验证活动是否已上报至 Cloud。 + `deploy` **会用执行结果替换机器上的整个策略集**。它会打印执行计划，然后在应用前进行确认——但仅限于交互式终端。使用 `--yes`、`fp --json` 或 stdin 被重定向时（CI 步骤、脚本、代理调用），将直接应用而不询问；执行计划仍会被打印，或在 `--json` 模式下以 `plan` 字段返回。 + + 在机器上，`failproofai policies` 列出当前运行的 Cloud 管理策略，`failproofai config --status` 显示连接状态。使用 `fp sessions --env production --since 24h` 和 `fp events --event-type hook_completed` 确认机器活动已上报到 Cloud。 - - 部署已审核的版本，而非可变草稿，并从非生产环境机器或小型机器组开始，以便检查其会话。 + + 选择已发布的版本以及需要运行该版本的机器。 - - 在不阻断工作的前提下，审查匹配项、原因、受影响的工具及误报情况。 + + 在不阻止任何内容的情况下，审查匹配项、原因、受影响的工具以及误报。 - - 在观察到的匹配项能够区分不安全操作与合法操作后，再提升为执行模式，并确认所有目标机器均已拉取部署配置并正在上报决策。 + + 当观察到的匹配项能够区分不安全操作与合法操作后，将效果切换为强制执行，然后确认每台目标机器已拉取变更并正在上报决策。 -机器需要具备 `policies:pull` 能力。事件上报由 `events:add` 单独控制；当您期望 Cloud 进行分析和执行时，请验证两者均已配置。 +## 检查覆盖情况 + +覆盖情况用于评估策略是否在存在风险的地方运行。 + +1. 前往 **Admin → enforcement**，查看强制执行和观察中的汇总数据。 +2. 按 ID 或标签搜索机器，或筛选缺少某策略的机器。 +3. 展开某一行，比较已分配的策略、已上报的部署状态、最后签入时间以及历史记录。 +4. 如果已应用的部署仍处于待定状态，请在机器的轮询间隔后刷新。 + +![Enforcement fleet 页面，显示策略覆盖情况、机器部署状态以及观察和强制执行分配。](/images/dashboard/enforcement-fleet.png) + +注意以下情况：从未拉取最新部署的机器、已注册但停止上报的机器、分配到错误环境的策略，以及更新中断后导致的版本漂移。 + +按工作负载和环境为机器打标签——仅靠主机名在自动扩缩容或机器替换时往往无法持久： + +```bash +failproofai config --machine-label checkout-runner-03 +``` - 执行管理是 Cloud 的管理员工作流。请勿将仅限 root 的执行路由视为普通客户的 `/v1` API 端点。 + 强制执行管理是一项管理员级别的 Cloud 工作流。请勿将仅限 root 的强制执行路由视为普通客户的 `/v1` API 端点。 \ No newline at end of file diff --git a/docs/zh/policies/editor.mdx b/docs/zh/policies/editor.mdx index 804d0dde..8dbd1bf3 100644 --- a/docs/zh/policies/editor.mdx +++ b/docs/zh/policies/editor.mdx @@ -1,49 +1,96 @@ --- -title: "策略编辑器" -description: "从已确认的故障模式创建和修订带版本控制的策略。" +title: "编写策略" +description: "让 Failproof AI 根据审计发现起草策略，或自行编写源代码，然后审查、测试并发布。" icon: "file-pen-line" --- -使用策略编辑器将发现的问题转化为可部署的规则。将创作与部署分离，确保草稿不会悄然改变已上线的行为。 +编写策略有两种方式：让 Failproof AI 根据审计发现起草，或自行编写源代码。在你主动选择之前，不会有任何内容被发布或部署。 -当某个问题具有可重复的操作模式时，在 **Analyze → issues** 下打开该问题并选择 **generate policy**。Failproof AI 会首先说明该问题是否可以用策略来表达，然后将经过审查的意图和问题上下文带入编辑器。生成的源代码在您发布之前始终保持草稿状态。 +## 根据审计编写策略 -## 发布策略版本 +审计发现失败；策略阻止其再次发生。Failproof AI 根据发现项自身的证据起草策略。 + +### 1. 运行审计 + +针对发生失败的会话[运行审计](/zh/audits/run)。每个发现项都包含其证据会话、根本原因以及建议的预防路径。请从具有**可重复操作模式**的发现项入手——策略只能阻止它能在 hook 事件中识别的行为。 + +### 2. 生成草稿 - 1. 前往 **Admin → policy editor**，在 **compose** 中描述故障模式或粘贴 JavaScript 策略源代码。 - 2. 验证源代码并修复所有报告的错误。 - 3. 输入策略标识并发布，然后使用 **library** 比较或禁用各个版本。 - 4. 当版本准备好进行机器部署时，选择 **enforcement**。 + 1. 在 **Analyze → issues** 下打开发现项的问题，查看其引用的会话、根本原因和建议。 + 2. 选择 **generate policy**。Failproof AI 首先判断某个策略是否能够表达该问题。**no policy** 结果意味着解决方案是警报、工作流程变更或人工介入——而非策略。 + 3. 选择 **write this policy**。问题标题、发现内容、根本原因、建议以及拟定的执行意图将作为草稿出现在 **Admin → policy editor** 中。如果你不同意候选检查的结论，可使用 **open the editor anyway**。 - ![策略编辑器的 compose 视图，包含策略标识、AI 辅助草稿、源代码验证和发布控件。](/images/dashboard/policy-editor.png) + ![策略编辑器的编写视图，包含策略标识、AI 辅助起草、源代码验证和发布控件。](/images/dashboard/policy-editor.png) - 通过 CLI 使用 `fp policies publish` 发布。该命令会生成一个**新版本**，而不会在原处编辑，并在发送前使用 node 对源代码进行语法检查——否则语法错误只会在部署到机器上执行时才会暴露： + 阅读证据，然后通过助手起草。`compose` 会打印源代码供你审查，不会发布任何内容： ```bash - fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny - fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" + fp issues show + fp audits finding + fp policies compose "Block git push --force on release branches" ``` - 发布本身不会部署任何内容——新版本在 `fp fleet deploy` 将其部署到机器之前不会生效。`fp policies compose ""` 会使用云端助手生成源代码草稿并打印供审阅，而不会直接发布。 - - 如需将策略安装到本地 Agent CLI（而非云端），请使用 `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`。 + `compose` 需要一个已登录的会话（`fp login`），且其角色须具有 `policies:write` 权限；它不接受 API 密钥。 -## 创作检查清单 +### 3. 审查草稿 + +草稿是起点，而非定论。在发布之前，请检查它是否： + +1. 用运营语言命名了失败模式。 +2. 仅匹配包含足够证据以作判断的 hook 事件和工具。 +3. 使用最窄的条件来捕获不安全的操作。 +4. 返回的原因能够告知 Agent 应该采取什么替代措施。 +5. 在 Agent 能够安全纠正方向时使用 `instruct`，仅在允许该操作不可接受或不可逆转时使用 `deny`。 + +在编辑器中验证源代码，并修复所有报告的错误。 + +### 4. 测试后发布 + +在发布之前，在源代码下方运行 **backtest**：它会将草稿重放到你的集群已发出的调用上，并统计它会中断的正常调用数量。[测试策略](/zh/policies/test)涵盖了这一项及其他检查。 + +确认其行为符合预期后，输入策略标识并选择 **publish version**。发布会生成一个不可变版本，且不会部署任何内容：它处于闲置状态，直到你[部署它](/zh/policies/deploy)。在终端中执行： + +```bash +fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" +``` + +`publish` 在发送前会对源代码进行语法检查，因此语法错误会在此处暴露，而不是在执行时的机器上。 + +## 自行编写 + +策略是基于 `failproofai` API 的 JavaScript 或 TypeScript： + +```ts +import { customPolicies, allow, deny } from "failproofai"; + +customPolicies.add({ + name: "protect-production-paths", + description: "Block writes to production configuration", + match: { events: ["PreToolUse"] }, + fn: async (ctx) => { + if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow(); + const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/"); + if (path.split("/").includes("production")) { + return deny("Writes to production configuration require approval."); + } + return allow(); + }, +}); +``` + +这会对 `Write` 和 `Edit` 两种操作匹配 `production/config.yml`、`/srv/production/config.yml`、`/srv/production` 以及 `C:\\production\\config.yml`，但不匹配 `production-backup`：`production` 必须是完整的路径段。上下文还包含事件类型、规范化的载荷、会话元数据、参数以及可用时的源 CLI——详见 [policy SDK](/zh/reference/policy-sdk)。 + +要将其作为版本发布，请将源代码粘贴到 **Admin → policy editor** 的 **compose** 中，然后按照上述步骤 3 和 4 操作；或在终端中使用 `fp policies publish` 发布文件。 -1. 用运营语言描述故障模式。 -2. 选择包含足够判断依据的 hook 事件和工具。 -3. 编写能够匹配不安全行为的最精确条件。 -4. 返回一个原因说明，告知 Agent 或操作员下一步应该怎么做。 -5. 添加应当匹配的示例以及必须保持允许状态的示例。 -6. 保存新版本并请求审查。 +若要在没有 Cloud 的机器上运行，请将其保存在 `.failproofai/policies/` 目录下，文件名以 `policies.js`、`policies.mjs` 或 `policies.ts` 结尾——这些文件会在项目和用户范围内自动加载——或通过路径安装： -当 Agent 可以安全地自行纠正时，使用 `instruct`。当允许该操作会带来不可接受或不可逆的风险时，使用 `deny`。 +```bash +failproofai policies --install --custom ./security.policies.ts --scope project +``` - - 策略版本是不可变的部署输入。编辑草稿会创建新版本；不应重写已分配给机器的版本。 - \ No newline at end of file +为每个策略指定一个在约定策略、自定义策略、包策略和 Cloud 托管策略中唯一的名称。 \ No newline at end of file diff --git a/docs/zh/policies/failure-behavior.mdx b/docs/zh/policies/failure-behavior.mdx index 91f84573..964c9a77 100644 --- a/docs/zh/policies/failure-behavior.mdx +++ b/docs/zh/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- -title: "故障行为" +title: "失败行为" description: "了解策略评估或本地守护进程不可用时会发生什么。" icon: "shield-alert" --- -Failproof AI 的设计原则是：强制执行失败时应清晰可见，而非静默放行存在风险的操作。 +Failproof AI 的设计原则是：执行失败时应显式可见，而非悄无声息地放行有风险的操作。 -## 诊断失败关闭（failure-closed）阻断 +## 诊断失败关闭阻断 - - 1. 前往 **Admin → enforcement**，打开对应机器。 - 2. 检查其最后签到时间、已分配的部署及上报的部署信息。 - 3. 前往 **Observe → policy**，打开被拒绝决策所在的会话。 - 4. 确认原因是守护进程可达性问题、版本不匹配，还是策略本身的问题。 + + 1. 前往 **管理员 → 执行**，打开对应机器。 + 2. 检查其最后一次签入时间、已分配的部署及上报的部署。 + 3. 前往 **观察 → 策略**，打开被拒绝决策的会话。 + 4. 确认原因是否报告了守护进程可达性问题、版本偏差，或策略本身的问题。 @@ -23,45 +23,47 @@ Failproof AI 的设计原则是：强制执行失败时应清晰可见，而非 failproofai config ``` - 升级软件包后，重新运行 `failproofai config` 可更新并重启守护进程。 + 重新运行 `failproofai config` 会在软件包升级后更新并重启守护进程。 -在配置了 `failproofaid` 的机器上，守护进程是唯一的评估器。若其不可达，或其协议版本与 CLI 不匹配，hook 评估将失败关闭。该操作将被拒绝，并附带原因，引导操作员检查或更新守护进程。 +在配置为使用 `failproofaid` 的机器上，守护进程是唯一的评估器。如果它不可达，或其协议版本与 CLI 不匹配，Hook 评估将失败关闭。操作会被拒绝，并附带原因，指引操作员检查或更新守护进程。 -在守护进程配置之前，hook 会在进程内评估策略。一旦记录了守护进程配置，当守护进程出现故障时，Failproof AI 不会静默回退到其他评估器。 +在守护进程配置之前，Hook 会在进程内评估策略。一旦记录了守护进程配置，当守护进程发生故障时，Failproof AI 不会悄悄回退到备用评估器。 -## 应对失败关闭决策 +## 响应失败关闭决策 1. 运行 `failproofai config --status`。 -2. 若版本不一致，更新软件包后重新运行 `failproofai config`。 -3. 若守护进程不可达，检查其服务状态和本地日志。 -4. 仅在确认策略评估路径正常后，再恢复智能体工作。 +2. 如果版本不一致，更新软件包后重新运行 `failproofai config`。 +3. 如果守护进程不可达，检查其服务状态和本地日志。 +4. 仅在确认策略评估路径正常后，才继续进行 Agent 工作。 - 请勿反复重试被阻断的操作。失败关闭响应意味着系统无法确认该操作是安全的。 + 不要反复重试被阻断的操作。失败关闭响应意味着系统无法确认该操作是安全的。 -## 包无法加载 +## 策略包无法加载 -若一台机器被要求强制执行某个包，但该包无法运行，系统将拒绝操作而非静默继续。触发条件是**已记录的预期**，而非空预期：未安装任何包的机器保持静默；而已声明但无法解析的包——或注册项少于其清单声明的包——将触发拒绝。 +如果一台机器被要求执行某个策略包，但无法运行它，系统会拒绝操作而非悄然继续。触发条件是**已记录的预期**，而非空预期：未安装任何策略包的机器保持静默，而已声明但无法解析的策略包——或注册数量少于其清单声明数量的策略包——则会触发拒绝。 -与守护进程不可达不同，此拒绝的范围**较窄**。守护进程无法到达意味着根本未发生任何评估，因此无法确认任何操作的安全性。而无法加载的包具有可枚举的缺失守卫集合，因为每条已声明的策略都带有自己的 `match`——因此它只拒绝这些策略所覆盖的事件和工具，其余操作照常进行。 +这种拒绝是**范围限定的**，与守护进程不可达的情况不同。守护进程无法到达意味着根本没有进行任何评估，因此无从知晓任何操作是否安全。无法加载的策略包有可枚举的缺失守卫集合，因为每个声明的策略都携带自己的 `match`——所以它只拒绝这些策略所覆盖的事件和工具，其余操作正常进行。 以下情况不会触发拒绝： -- `observe` 包——其设计本身就是评估后丢弃 -- 从未启用或已明确关闭的策略 -- 加载器从未收到的包——此时「无注册项」与刻意跳过无法区分 -- 活跃会话暂停期间 -- 加载超时——这是暂时性问题，一次磁盘响应缓慢不应触发拒绝直至人工介入 +- `observe` 包，其设计本身就是评估后丢弃 +- 你从未采用或已明确关闭的策略 +- 加载器从未收到的策略包，因为"无注册"与故意跳过无法区分 +- 活跃会话暂停 +- 加载超时（属于瞬态情况）——单次磁盘缓慢不应触发拒绝，直到人工介入 -`UserPromptSubmit` 会使用 **instruct** 而非拒绝，无论缺失的策略声明了什么。全面拒绝会将其一并阻断，使你无法使用本可修复问题的智能体。 +`UserPromptSubmit` 会使用 **instruct** 而非拒绝，无论缺失的策略声明了什么。全量拒绝会将其一并阻断，使你无法访问本可修复问题的 Agent。 ### 处理方法 ```bash -failproofai pack list +failproofai policies ``` -该命令会列出所有已安装但无法加载的包，说明原因，并以非零状态码退出。随后，你可以重新安装（`failproofai pack add `）或移除该包（`failproofai pack remove `）——移除包会撤销预期，拒绝行为也将随之停止。 \ No newline at end of file +该列表会标记安装记录或摘要校验不通过的已安装策略包，并说明原因。它不会导入策略包，因此仅在加载时失败的包（注册数量少于清单声明）会正常显示在列表中；下方的拒绝信息才会指出该包。无论哪种情况，重新安装（`failproofai policies add `）或移除（`failproofai policies remove `）均可解决——移除操作会撤销预期，拒绝也随之停止。 + +拒绝本身归因于 `pack/failproofai-pack-unavailable`，其优先级高于已加载的策略，因此被阻断的工具调用会指向缺失的策略包，而非碰巧首先触发的某个存活守卫。 \ No newline at end of file diff --git a/docs/zh/policies/local-configuration.mdx b/docs/zh/policies/local-configuration.mdx index 45181c4f..d36c0bbb 100644 --- a/docs/zh/policies/local-configuration.mdx +++ b/docs/zh/policies/local-configuration.mdx @@ -1,55 +1,49 @@ --- title: "本地配置" -description: "控制策略范围、参数、自定义文件及机器级 Failproof AI 设置。" +description: "管理策略作用域、参数、自定义文件以及机器级 Failproof AI 设置。" icon: "file-cog" --- -Failproof AI 将策略选择与机器和守护进程设置分离。这样既能让仓库中的策略选择保持可审查性，又能将凭据和守护进程状态保留在仓库之外。 +Failproof AI 将仓库可提交的内容（钩子连接、策略参数、自定义策略）与机器状态（如凭据、已安装的包及守护进程）分开管理。 -## 选择策略范围 +## 选择作用域 - - - 不带参数运行 `failproofai` 可打开本地策略控制台。在启用策略之前，先选择用户、项目或本地范围，确保更改写入到正确的配置文件。 +作用域决定了钩子的连接位置，以及您在哪个配置文件中写入参数和自定义策略路径： - - **用户**：应用于本机上的所有项目。 - - **项目**：属于仓库，可以提交。 - - **本地**：针对某一用户覆盖单个项目，应保留在 gitignore 中。 +- **User**：应用于本机上的所有项目。 +- **Project**：归属于仓库，可以提交。 +- **Local**：为单个用户覆盖某个项目的配置，应保留在 gitignore 中。 - - - ```bash - failproofai policy add block-rm-rf --scope user - failproofai policy add block-force-push --scope project - failproofai policy add warn-large-file-write --scope local - failproofai policies - ``` +```bash +failproofai policies --install --cli claude --scope project # 为此仓库连接钩子 +failproofai policies --install --cli claude --scope user # 或为本机上的所有项目连接钩子 +failproofai policies +``` - 并非所有执行器都支持本地范围。如果所选执行器无法表示该范围，CLI 将拒绝执行。 - - +并非所有 harness 都支持 local 作用域；如果所选 harness 不支持指定的作用域，CLI 会拒绝该请求。 + +包策略的启用状态**不受作用域限制**。该开关与已安装的包一起记录，因此 `failproofai policies add ` 会在整台机器范围内启用某个策略，无论 `--scope` 如何设置。 -| 范围 | 策略配置文件 | +| 作用域 | 策略配置文件 | | --- | --- | -| 项目 | `/.failproofai/policies-config.json` | -| 本地 | `/.failproofai/policies-config.local.json` | -| 用户 | `~/.failproofai/policies-config.json` | +| Project | `/.failproofai/policies-config.json` | +| Local | `/.failproofai/policies-config.local.json` | +| User | `~/.failproofai/policies-config.json` | -已启用的策略以并集方式合并。策略参数按 项目 → 本地 → 用户 的顺序，使用第一个为该策略定义了参数的范围。显式自定义策略路径同样使用第一个定义它们的范围。 +策略参数按 project → local → user 的顺序，使用第一个为该策略定义了参数的作用域。显式自定义策略路径同样使用第一个定义了路径的作用域。 ## 配置策略参数 - 在本地控制台中打开策略，编辑其支持的参数，然后在选定范围内保存。运行一个匹配及一个不匹配的代理操作，然后在 **观察 → 策略** 中查看决策结果。 + 在本地控制台中打开相应策略，编辑其支持的参数，并保存到所选作用域。运行一个匹配和一个不匹配的 Agent 操作，然后在 **Observe → policy** 中查看决策结果。 - 编辑所选范围的 `policies-config.json`，然后运行 `failproofai policies` 以检测未知的策略名称或参数键。 + 编辑所选作用域的 `policies-config.json`，然后运行 `failproofai policies`：如果 `policyParams` 条目中指定的策略不存在于任何已安装的包中，系统会发出警告。它不会检查条目内部的键名，因此请对照下方表格核对拼写。 ```json { - "enabledPolicies": ["block-rm-rf", "block-force-push"], "policyParams": { "block-rm-rf": { "allowPaths": ["/tmp/build-output"] @@ -64,21 +58,45 @@ Failproof AI 将策略选择与机器和守护进程设置分离。这样既能 +### Failproof AI 策略接受的参数 + +每个策略会自行验证其参数类型。 + +| 策略 | 参数 | 类型与默认值 | +| --- | --- | --- | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`，`[]`；条目包含 `regex` 和 `label` | +| `block-read-outside-cwd` | `allowPaths` | `string[]`，`[]` | +| `block-sudo` | `allowPatterns` | `string[]`，`[]` | +| `block-rm-rf` | `allowPaths` | `string[]`，`[]` | +| 基础设施拦截器 | `allowPatterns` | `string[]`，`[]` | +| `block-secrets-write` | `additionalPatterns` | `string[]`，`[]` | +| `block-push-master` | `protectedBranches` | `string[]`，`["main", "master"]` | +| `block-work-on-main` | `protectedBranches` | `string[]`，`["main", "master"]` | +| `prefer-package-manager` | `allowed`，`blocked` | `string[]`，`[]` | +| `warn-large-file-write` | `thresholdKb` | `number`，`1024` | +| `require-push-before-stop` | `remote`，`baseBranch` | `string`，`"origin"`；`string`，`"main"` | +| `require-pr-before-stop` | `baseBranch` | `string`，`"main"` | +| `require-no-conflicts-before-stop` | `baseBranch` | `string`，`"main"` | + + + 允许模式会扩大 Agent 的操作权限。在将其部署到整个集群之前，请先在目标 harness 上测试准确的分词行为和各种命令变体。 + + ## 了解机器文件 -`~/.failproofai` 包含针对不同信任边界的独立文件： +`~/.failproofai` 针对不同信任边界包含独立文件： | 路径 | 用途 | | --- | --- | -| `config.json` | 非敏感的守护进程、审计及遥测设置 | -| `credentials.json` | 云凭据；以仅所有者可读的权限存储 | -| `policies-config.json` | 用户范围内置策略选择、参数及显式自定义路径 | -| `policies/` | 用户约定策略及云托管策略工件 | +| `config.json` | 守护进程、审计和遥测的非敏感设置 | +| `credentials.json` | 云凭据；以仅限所有者的权限存储 | +| `policies-config.json` | 用户作用域的参数及显式自定义策略路径 | +| `policies/` | 用户约定策略、已安装的包及其策略启用状态，以及云端管理的策略产物 | | `hook-activity/` | 本地策略决策日志 | -| `state/` | 守护进程队列、健康状态、暂停及运行时状态 | +| `state/` | 守护进程缓冲区、健康状态、暂停状态及运行时状态 | -使用 `FAILPROOFAI_HOME` 可为容器或隔离测试重新指定完整的机器布局目录。请勿单独迁移各个状态目录。 +使用 `FAILPROOFAI_HOME` 可将完整的机器目录布局迁移至容器或隔离测试环境。请勿单独迁移各个状态目录。 - 切勿提交 `credentials.json`。仅在将项目策略配置和项目约定策略作为执行代码审查后，才可提交它们。 + 切勿提交 `credentials.json`。项目策略配置和项目约定策略只有在作为执行代码审查完毕后才可提交。 \ No newline at end of file diff --git a/docs/zh/policies/overview.mdx b/docs/zh/policies/overview.mdx index 5672e248..66d8330b 100644 --- a/docs/zh/policies/overview.mdx +++ b/docs/zh/policies/overview.mdx @@ -1,63 +1,54 @@ --- title: "策略" -description: "在已知故障重复发生之前，观察、引导或阻止代理操作。" +description: "在已知故障重复发生之前，观察、引导或阻断 Agent 行为。" icon: "shield-check" --- -策略评估代理钩子事件，并返回以下三种决策之一： +策略会评估一个 Agent 钩子事件，并返回以下三种决策之一： - `allow` 允许操作继续执行。 -- `instruct` 为代理提供纠正性指导。 -- `deny` 以指定原因阻止该操作。 +- `instruct` 向 Agent 提供纠正性指导。 +- `deny` 以特定原因阻断该操作。 -## 使用三个策略界面 +## 策略的位置 - - - 1. 前往 **Observe → policy**，筛选并检查会话中的策略决策。 - 2. 前往 **Admin → policy editor**，编写、验证、发布、禁用或查看不可变版本。 - 3. 前往 **Admin → enforcement**，为机器分配版本和效果。 +| 控制台位置 | 在此执行的操作 | +| --- | --- | +| **Observe → policy** | 查看真实会话中的决策记录：哪条策略匹配、在哪台机器上、以及匹配原因 | +| **Admin → policy editor** | 编写策略、针对历史流量进行回测、发布不可变版本，并在 **library** 中对比各版本 | +| **Admin → enforcement** | 将版本部署到机器上，可选观察模式或强制执行模式 | - 在编写或更改执行规则之前，先通过策略页面了解当前已匹配的内容。 +策略编辑器是将故障转化为规则的地方。在 **compose** 中描述故障模式或粘贴策略源码，针对已有流量进行回测，然后发布版本： - ![策略页面，显示决策总数以及本地和云端管理的策略映射。](/images/dashboard/policy-observe.png) +![策略编辑器的 compose 视图，包含策略标识、AI 辅助起草、源码校验和发布控制。](/images/dashboard/policy-editor.png) - 编辑器用于将故障条件转化为源代码、进行验证并发布不可变版本。 +在机器上，`failproofai policies` 会列出该机器上所有正在执行的策略。`fp policies` 和 `fp fleet` 可从终端操作编辑器和执行配置——详见 [Cloud CLI 参考](/zh/reference/cloud-cli)。 - ![策略编辑器，用于编写和发布不可变策略版本。](/images/dashboard/policy-editor.png) +## 获取策略 - 执行模块将已发布的版本及其观察或强制效果分配给各台机器。 - - ![执行机队视图，显示机器覆盖情况及已分配的策略版本。](/images/dashboard/enforcement-fleet.png) - - 部署后，返回策略页面验证决策，确保编写视图和机队视图与真实的代理活动相关联。 - - - 使用 `failproofai` 进行本地策略安装和验证： - - ```bash - failproofai policies - failproofai policy add block-rm-rf --scope project - failproofai config --status - ``` - - 使用 `fp` 查找包含策略决策的云端会话和事件。云端编写和机队部署仍为控制台工作流。 - - - -策略在 Failproof AI 中有三个独立的界面： - -1. **分析决策**——在会话、控制台和审计中查看。 -2. **编写版本**——使用内置规则、代码或策略编辑器。 -3. **部署与执行**——在选定机器上部署和强制执行版本。 - -从已确认的故障模式出发。定义能够识别该故障的最小事件和工具匹配条件，测试合法示例和不安全示例，先观察再强制执行。 +有两种方式获取策略。 - - 启用经过审查的规则，覆盖常见的密钥、Shell、Git、云端和工作流风险。 + + 让 Failproof AI 根据审计发现起草策略，或自行编写源码，然后在编辑器中审核并发布。 - - 用 JavaScript 或 TypeScript 表达特定工作流的决策逻辑。 + + 一条命令即可接入适合您使用场景的 Failproof AI 策略包，或来自策略中心的社区策略包。 - \ No newline at end of file + + +## 然后部署上线 + + + + 在发布之前，针对已有流量进行回测，并分别针对一个必须被拦截的操作和一个必须被放行的操作运行测试。详见[测试策略](/zh/policies/test)。 + + + 以**观察**模式将版本部署到机器上，查看其决策结果，再切换到强制执行模式。详见[部署策略](/zh/policies/deploy)。 + + + 每次发布都会生成一个新的不可变版本，因此若某次部署阻断了正常工作，只需重新部署上一个可用版本即可撤销。详见[版本管理与回滚](/zh/policies/rollback)。 + + + +如需与其他团队共享策略，请[将其发布为策略包](/zh/policies/publish-a-pack)。如需了解策略完全无法评估时的处理逻辑，请参阅[故障行为](/zh/policies/failure-behavior)。 \ No newline at end of file diff --git a/docs/zh/policies/packs.mdx b/docs/zh/policies/packs.mdx index 0cc175a9..7e9bfce9 100644 --- a/docs/zh/policies/packs.mdx +++ b/docs/zh/policies/packs.mdx @@ -1,110 +1,119 @@ --- -title: "策略包" -description: "安装以 GitHub Release 形式发布的策略集，并管理其执行内容。" +title: "使用策略包" +description: "为您的用例接入 Failproof AI 策略包，或从策略中心获取社区包，并自定义其执行内容。" icon: "package" --- -策略包是以 GitHub Release 形式发布的一组策略。一条命令即可完成安装，运行前会验证 Release 自带的校验和，并记录摘要，确保策略包在安装后无法在您的机器上被悄然篡改。 +策略包是以 GitHub Release 形式发布的一组策略。只需一条命令即可完成安装：在运行任何内容之前，系统会验证发布版本的校验和，并记录其摘要，以确保该包在安装后无法在您的机器上被悄然替换。 -## 安装 Failproof AI 策略 +您可以在[策略中心](https://befailproof.ai/policy-hub/)浏览所有策略包及其中的每条策略。策略包分为两类： + +- **Failproof AI 策略包** — 针对预定义用例的现成策略包：接入即可使用。[代码智能体策略包](https://befailproof.ai/policy-hub/failproofai/policies/)现已上线，更多用例的策略包即将推出。 +- **社区策略包** — 开发者为自己的用例编写并公开发布、供他人使用的策略。 + +## Failproof AI 策略包 + +### 代码智能体策略包 ```bash -failproofai pack add core +failproofai policies add FailproofAI/policies ``` -该命令从 npm 包内置的副本安装我们发布的策略集——无需网络，也不会因代理设置而失败。您也可以只安装其中一部分： +该包包含 38 条策略，其中清单标记为可无人值守启用的 10 条会自动开启；其余策略供您按需选择。以下列出了一些常用策略及其默认开启状态： + +| 策略 | 作用 | 默认开启 | +| --- | --- | --- | +| `block-push-master` | 阻止直接推送到受保护分支 | 是 | +| `block-env-files` | 阻止读写 `.env` 文件 | 是 | +| `protect-env-vars` | 阻止转储环境变量的命令 | 是 | +| `block-sudo` | 阻止 `sudo`，除非匹配到允许模式 | 是 | +| `block-curl-pipe-sh` | 阻止将下载的脚本直接通过管道传入 shell 执行 | 是 | +| `sanitize-*`（五条策略） | 报告工具输出中发现的 API 密钥、Bearer Token、JWT、私钥及连接字符串 | 是 | +| `block-rm-rf` | 阻止灾难性的递归删除操作 | 否 | +| `block-force-push` | 阻止强制推送 | 否 | +| `block-secrets-write` | 阻止写入凭据和密钥文件 | 否 | +| `warn-destructive-sql` | 对不带 `WHERE` 子句的 `DROP`、`TRUNCATE` 和 `DELETE` 操作发出警告 | 否 | + +按名称开启任意未启用的策略 — `failproofai policies add block-rm-rf` — 或使用 `--all` 获取整个策略包。查看按类别分组的所有策略： ```bash -failproofai pack add core --policy block-rm-rf # 单个策略，或以逗号分隔的多个策略 -failproofai pack add core --category dangerous-commands # 整个分类 -failproofai pack add core --all # 包内所有策略 +failproofai policies show FailproofAI/policies ``` -`failproofai pack list` 会列出该策略包提供的所有分类。 +## 社区策略包 -## 安装前查看策略包内容 +开发者会针对自己遇到的用例发布策略包，[策略中心](https://befailproof.ai/policy-hub/)会统一列出。社区策略包由作者自行发布，未经 Failproof AI 审核，因此请在安装前了解其内容： ```bash -failproofai pack list acme/support-agent +failproofai policies show acme/support-agent ``` -该命令会列出策略包中的所有策略，按分类分组，并标注哪些策略是作者默认启用的，哪些需要手动选择。它**只读取清单（manifest）**——入口产物永远不会被下载或导入，因此查看陌生人的策略包不会执行任何陌生代码。清单仍会与 Release 自带的 `SHA256SUMS` 进行校验，确保您所看到的内容与实际安装的内容一致。 - -不带参数执行 `failproofai pack list` 会列出当前已安装的所有策略包。 +该命令会按类别列出策略包中的每条策略，并标注哪些是作者默认开启的。它**仅读取清单**——入口构件不会被下载或导入，因此查看陌生人的策略包不会执行陌生人的代码。清单仍会与发布版本自带的 `SHA256SUMS` 进行核验，确保您所看到的内容与实际安装内容一致。 -## 安装第三方策略包 +然后执行安装： ```bash -failproofai pack add acme/support-agent +failproofai policies add acme/support-agent ``` -以下格式均可使用——粘贴您手头的任意一种： +以下写法均有效——粘贴您手头的任意一种即可： -| 来源格式 | 效果 | +| 来源 | 结果 | | --- | --- | -| `acme/support-agent` | 最新 Release，**锁定**到解析到的确切标签 | -| `acme/support-agent@v2.1.0` | 指定该 Release | -| `github:acme/support-agent@v2.1.0` | 同上，显式写法 | -| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | 同上，从浏览器复制的地址 | +| `acme/support-agent` | 最新发布版本，**锁定**到解析到的确切标签 | +| `acme/support-agent@v2.1.0` | 指定版本 | +| `github:acme/support-agent@v2.1.0` | 与上一条相同，显式写法 | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | 与上一条相同，从浏览器复制的链接 | -不指定标签时，会安装最新 Release **并锁定版本**，同时告知您所选的标签。记录的内容始终精确指向某一个 Release，因此重新安装时不会发生版本漂移。 +不指定标签时，将安装最新发布版本并**锁定该版本**，同时告知您所选的标签。记录的内容始终精确对应某一个发布版本，因此重新安装时不会发生版本漂移。 -## 只安装策略包的部分内容 +## 仅使用策略包的部分内容 -默认情况下，您只会获得策略包**作者设定的默认值**——即作者标记为可无人值守启用的策略——而非全部内容。 +默认情况下，您获取的是策略包**自身**的默认配置——即作者标记为可无人值守启用的策略——而非包中的全部内容。 ```bash -failproofai pack add acme/support-agent --category billing,git -failproofai pack add acme/support-agent --policy block-refunds -failproofai pack add acme/support-agent --all +failproofai policies add FailproofAI/policies --policy block-rm-rf # 单条策略，或以逗号分隔的多条策略 +failproofai policies add FailproofAI/policies --category dangerous-commands # 整个类别 +failproofai policies add FailproofAI/policies --all # 包中的全部内容 ``` -`--category` 与 `--policy` 取并集组合使用（`--only` 是 `--policy` 的同义词）。以更新版本重新添加时，会保留您之前的选择，而不会将其余策略重新启用。 +`--category` 与 `--policy` 以并集方式组合使用（`--only` 是 `--policy` 的同义词）。当策略包已安装时，这些标志会在现有选择的基础上追加；在无终端的情况下不带任何标志地重新添加（例如用于升级），会保持您当前的选择不变。在终端中不带标志执行 `add` 时，会打开选择器，预先勾选作者的默认项，您的勾选结果将替换当前选择。 ## 管理已启用的策略 ```bash -failproofai policies # 所有来源的策略，包括策略包，统一列出 -failproofai pack list # 仅列出策略包，按分类分组 -failproofai policies --uninstall block-refunds # 禁用某个策略包中的策略 -failproofai policies --install block-refunds # 重新启用 -failproofai pack remove acme/support-agent +failproofai policies # 在一个列表中查看所有来源，包括策略包 +failproofai policies add block-rm-rf # 开启单条策略 +failproofai policies --uninstall block-refunds # 关闭某条策略包策略 +failproofai policies --install block-refunds # 重新开启 +failproofai policies remove acme/support-agent # 卸载策略包 ``` -单独使用名称时，如果存在同名**内置策略**，则指向该内置策略。如需明确指定策略包中的某个策略，请使用以下格式： +开启或关闭某条策略包策略对整台机器生效：该开关与已安装的策略包一同记录，而非存储在项目配置中，无论 `--scope` 如何设置。 + +不含斜杠的名称表示策略；含有斜杠的表示策略包来源。裸名称会解析为声明该策略的已安装策略包。当两个已安装的策略包声明了相同名称时，请明确指定目标包： ```bash failproofai policies --uninstall acme/support-agent:block-refunds ``` - -如果策略包中的某个策略与**已启用的内置策略**同名，则内置策略会执行，策略包中的副本会被跳过——否则同一检查逻辑会被执行两次。如需使用策略包中的版本，请先禁用对应的内置策略。 - - -## Failproof AI 策略的来源 - -`core` 读取的是 npm 包中内置的副本。同一套策略也以 GitHub Release 的形式发布，如需安装特定版本，可使用以下命令： - -```bash -failproofai pack add core # 来自当前 npm 包，无需网络 -failproofai pack add FailproofAI/policies # 同一套策略，来自其 GitHub Release -``` +作用域、参数以及这些命令所写入的文件，详见[本地配置](/zh/policies/local-configuration)。 -## 完整性校验的保障范围 +## 完整性校验的能力边界 -`SHA256SUMS` 与产物文件同属同一个 Release，因此它**不是签名**，无法证明发布者的身份。它所能证明的是：这些字节正是该 Release 所发布的内容——由于摘要在添加策略包时记录，并在每次导入前重新验证，策略包在安装后无法被悄然篡改。如果某个仓库重新打标签或替换了产物文件，策略包将停止加载，而不会静默地执行其他内容。 +`SHA256SUMS` 与构件一同包含在同一个发布版本中，因此它**不是签名**，无法证明发布者身份。它所能证明的是：这些字节与该发布版本所发布的内容一致——由于摘要在添加策略包时记录，并在每次导入前重新校验，策略包在安装后无法在您的机器上被悄然替换。如果某个仓库重新打标签或替换了构件，该包将停止加载，而不是静默地执行其他内容。 -安装时，策略包还会被**导入一次**，并与其自身的清单进行比对。如果产物无法解析，或注册的内容与声明不符，则会在任何内容激活前被拒绝——而不是安装成功后在下一次工具调用时才报错。 +安装时，策略包还会被**导入一次**并与自身清单进行核对。若构件无法解析，或注册内容与声明不符，则会在激活任何内容之前被拒绝——而不是安装成功后在您下次调用工具时才报错。 ## 策略包无法加载时的行为 -如果本机被要求执行某个策略包，但该包无法运行，则其所涵盖的事件会被**拒绝（deny）**，而不是静默放行。请参阅[故障行为](/zh/policies/failure-behavior)。`failproofai pack list` 会标注处于该状态的策略包，并以非零退出码退出。 +如果本机被要求执行的策略包无法运行，该包所覆盖事件会被**拒绝**，而非静默放行——以 `pack/failproofai-pack-unavailable` 的形式，其优先级高于已加载的策略，因此拒绝行为归因于缺失的策略包，而非碰巧触发的某个守卫。唯一例外是 `UserPromptSubmit`，该事件会改为发出指令而非拒绝——因为拒绝此事件会将您锁定在修复所需的智能体之外。详见[失败行为](/zh/policies/failure-behavior)。 ## 离线使用与镜像 | 变量 | 效果 | | --- | --- | -| `FAILPROOFAI_NO_DOWNLOAD=1` | 拒绝任何网络请求；已安装的策略包继续执行 | -| `FAILPROOFAI_PACK_BASE_URL` | 将策略包下载地址指向镜像，而非 `github.com` | +| `FAILPROOFAI_NO_DOWNLOAD=1` | 拒绝网络获取；已安装的策略包继续执行 | +| `FAILPROOFAI_PACK_BASE_URL` | 将策略包获取指向镜像地址，而非 `github.com` | -如需发布自己的策略包，请参阅[发布策略包](/zh/policies/publish-a-pack)。 \ No newline at end of file +如需以这种方式分享您自己的策略，请参阅[发布策略包](/zh/policies/publish-a-pack)。 \ No newline at end of file diff --git a/docs/zh/policies/publish-a-pack.mdx b/docs/zh/policies/publish-a-pack.mdx index 136d92a7..8262a1e6 100644 --- a/docs/zh/policies/publish-a-pack.mdx +++ b/docs/zh/policies/publish-a-pack.mdx @@ -1,14 +1,22 @@ --- -title: "发布规则包" -description: "将你自己的策略打包为 GitHub 发布版本，供任何人安装使用。" +title: "发布策略包" +description: "将您自己的策略作为 GitHub 发布版本发布，供任何人安装。" icon: "upload" --- -一个规则包由附加在 GitHub 发布版本上的三个文件组成。`failproofai pack build` 会从你已有的策略文件中生成这三个文件。 +策略包由附加到 GitHub 发布版本的三个文件组成。`failproofai publish` 从其前面的策略文件中生成这三个文件，创建发布版本并上传。 ## 1. 编写策略 -使用与自定义策略相同的 API，只需一个文件。规则包还有两个额外的重要字段： +从已经可以正常运行的内容开始，而不是从空白模板开始： + +```bash +failproofai publish --init +``` + +该命令会询问策略包的名称，写入 `.mjs` 文件后停止——不涉及网络、git，也不会发布任何内容。它生成的文件包含一条已经可以阻止 `git push --force` 的策略。如果文件已存在，它拒绝覆盖。 + +策略使用与任何自定义策略相同的 API。策略包有两个额外字段需要注意： ```js import { customPolicies, deny, allow } from "failproofai"; @@ -17,7 +25,7 @@ customPolicies.add({ name: "block-refunds", description: "Refunds above the approved limit need a human", category: "Billing", // groups it, and is what --category selects on - defaultEnabled: true, // switched on by a plain `pack add` + defaultEnabled: true, // switched on by a plain `policies add` match: { events: ["PreToolUse"], tools: ["Bash"] }, fn: async (ctx) => String(ctx.toolInput?.command ?? "").includes("refund") @@ -26,66 +34,95 @@ customPolicies.add({ }); ``` -省略 `defaultEnabled` 时，默认值为 **false**。执行 `failproofai pack add` 时，只会启用你标记为开启的策略——在无人值守的情况下自动安装陌生人的所有策略，不应由工具替用户做出这个决定。 +省略 `defaultEnabled` 时，默认值为 **false**。普通的 `failproofai policies add` 只会启用您标记过的策略——在无人值守的情况下安装陌生人的所有策略，不应由安装程序替用户做这个决定。 + +可以编写任意数量的文件；按类别一个文件读起来更清晰。目录中所有注册了策略的文件都会被打包成策略包所需的单一构件。 -入口文件必须是**一个完全自包含的文件**。只有入口文件会被摘要锁定，因此如果规则包引用了本地文件，就无法真实声称摘要覆盖了实际运行的内容。请先打包（使用 `esbuild`、`bun build` 或 `rollup`），然后再从打包产物构建规则包——`pack build` 会拒绝含有本地导入的文件，而不是发布一个无法兑现的承诺。 + 打包需要 **bun**。没有它，请只使用一个自包含的文件。无论哪种方式，发布的入口文件在安装时都不得导入本地文件：只有入口文件的摘要是固定的，因此引用兄弟文件的策略包无法诚实地声称摘要覆盖了实际运行的内容——`publish` 会拒绝此类情况，而不是发布一个它无法兑现的承诺。 -## 2. 构建发布资产 +## 2. 先在本地测试 + +在任何人看到之前，先在本机上执行该文件： ```bash -failproofai pack build ./policies.mjs \ - --id acme/support-agent \ - --version 1.0.0 \ - --out ./dist-pack +failproofai policies -i -c ./.mjs +``` + +任意路径，任意文件名。让您的 Agent 尝试执行被阻止的操作，观察它被拒绝。此时什么都不会发布，也不会影响其他人。[测试策略](/zh/policies/test) 涵盖了其余部分：必须允许的合法场景，以及会导致问题的输入。 + +## 3. 发布 + +```bash +failproofai publish ``` -该命令会生成三个文件，并首先用**加载器自身的规则**验证每条策略——这样，无法安装的规则包会在此处失败，方便你及时修复： +它会自动确定发布位置、要打包的内容以及版本号，仅在仓库中找不到相关信息时才会询问。按顺序执行以下步骤，如果任何步骤出错则在创建发布版本前停止： + +1. 根据**内容**查找策略文件——即那些导入了 `failproofai` 并调用了 `customPolicies.add` 的文件——而非根据文件名，因此它能找到 `guards.mjs` 并忽略不相关的 `policies.mjs`。它不会递归进入子目录，所以测试夹具文件不会被意外收录。 +2. 从**文件所在**目录的 `git remote get-url origin` 读取仓库信息（而非您当前所在目录），并确定版本号。 +3. 查找您的凭证：`GITHUB_TOKEN`、`GH_TOKEN` 或 `gh auth login`。它只需要 release-write 权限，凭证内容不会被打印出来。 +4. 如果仓库不存在则创建仓库。此步骤在构建之前执行，因此若策略包在下一步被拒绝，可能会留下一个没有任何发布版本的新仓库。 +5. 构建三个资产，并使用**加载器自身的规则**进行验证——即决定什么可以安装到陌生人机器上的同一套代码——因此永远无法安装的策略包会在这里失败，此时您仍可以修复它。 +6. 创建或复用发布版本并上传，替换同名资产。 | 文件 | 说明 | | --- | --- | -| `failproofai-pack.json` | 清单文件：包含 id、版本、效果以及每条策略的条目 | -| `failproofai-pack.mjs` | 你的入口文件，原样保留 | -| `SHA256SUMS` | 其他两个文件的 ` <文件名>` 校验值 | +| `failproofai-pack.json` | 清单文件：id、版本、效果，以及每条策略的条目 | +| `failproofai-pack.mjs` | 您的打包入口文件 | +| `SHA256SUMS` | 另外两个文件的 ` <文件名>` | -以下情况会在构建时被拒绝：id 格式不为 `publisher/name`、策略名称包含 `/`、策略声明了 `alwaysOn`、缺少 `description`、`category` 或 `match`、入口文件未注册任何策略，以及入口文件引用了本地文件。 +资产名称是固定的——消费方的 CLI 就是根据这些名称构建 URL 的，无需 API 调用，也无需服务发现。 -## 3. 将文件附加到发布版本 +构建时拒绝的情况包括：id 不符合 `publisher/name` 格式、策略名称包含 `/`、策略声明了 `alwaysOn`、缺少 `description`、`category` 或 `match`、入口文件没有注册任何策略，以及入口文件导入了本地文件。 -使用与构建时相同的版本号打标签，并将三个文件作为发布资产附加上去： +覆盖自动确定的任何设置： ```bash -gh release create 1.0.0 \ - ./dist-pack/failproofai-pack.json \ - ./dist-pack/failproofai-pack.mjs \ - ./dist-pack/SHA256SUMS +failproofai publish \ + --repo acme/support-agent \ + --version 1.0.0 \ + --effect observe \ + --dry-run ``` -任何人现在都可以安装它： +`--id` 在策略包 id 应与仓库不同时设置该 id，`--tag` 设置发布版本的标签，`--notes` 替换自动生成的发布说明——`policies show --releases` 从中读取每个发布版本的计数和提交信息——`--out` 指定资产写入位置（默认为 `dist-pack`），`--dry-run` 在不发布的情况下构建资产，无需凭证。 -```bash -failproofai pack add acme/support-agent -``` +任何人现在都可以通过 `failproofai policies add acme/support-agent` 安装它。关于固定版本和只安装部分策略，请参阅[策略包](/zh/policies/packs)。 + +### 在策略中心上架 -资产文件名是固定的——这正是消费者的 CLI 构建 URL 的依据，无需任何 API 调用或服务发现。 +在 GitHub 仓库中添加 `failproofai-policies` 主题标签。无需提交表单，也没有审核队列：[策略中心](https://befailproof.ai/policy-hub/)的爬虫会在下次扫描时自动收录该仓库。添加主题标签只是将其纳入考虑——真正使其上架的是一个发布版本，其清单能通过自身 `SHA256SUMS` 的验证，并能在 CLI 使用的相同规则下正确解析，而这正是 `failproofai publish` 所生成的内容。 + +## 版本号的确定方式 + +版本号就是**您正在发布的提交**——其短 sha，十二个字符：`a1b2c3d4e5f6`。无需选择，无需递增，版本号精确指向字节的来源，因此对同一份源代码发布两次会得到相同的版本号。 + +版本号从您面前的文件树中读取，从不从仓库的发布版本中读取，因此全新克隆和离线机器无需询问 GitHub 历史就能计算出相同的结果。 + +由于版本号指向一个提交，该提交必须存在。在终端中，`publish` 会替您完成这一步：在没有仓库时初始化仓库，并在构建前提交已变更的策略文件。在以下情况下它会**拒绝**执行，并提示 `--version` 作为解决方案：在没有终端的情况下运行（在 CI 运行器上创建的提交将不存在于其他地方）、除策略文件外还有其他文件未提交，或者在尚无任何提交的检出环境中。`HEAD` 上的标签优先于 sha——打了 `v1.2.0` 标签的人已经声明了这个发布版本的含义。 + +sha 本身没有顺序信息，因此使用 `failproofai policies show / --releases` 查看哪个发布版本在前——最新的在最上面。 ## 发布新版本 -使用新的 `--version` 构建，打一个新标签，再次附加三个资产文件。用户执行相同的 `pack add` 命令即可升级，已选择的策略子集保持不变；被关闭的策略在升级后仍保持关闭状态。 +提交更改并再次运行 `failproofai publish`——新提交即为新版本。消费者运行相同的 `failproofai policies add`。在没有终端的情况下，或使用了选择标志时，他们保留之前选择的子集，已关闭的策略保持关闭；在有终端且没有标志的情况下，选择器会以您的默认值预先勾选打开，他们的选择将替换之前的选择。 + +更改策略的**名称**是一项破坏性变更：之前关闭了该策略的机器正在关闭一个已不存在的名称，而新名称将以 `defaultEnabled` 所指定的状态出现。 -修改策略的**名称**是破坏性变更：曾将某个策略关闭的用户，关闭的是一个已不存在的名称，而新名称会按照 `defaultEnabled` 的设定启用。 +## 您的用户在信任什么 -## 你的用户在信任什么 +`SHA256SUMS` 与构件存放在同一个发布版本中，因此它证明了字节是您发布的那些——但无法证明您是谁。任何能写入该仓库的人都可以同时修改这两个文件。用户的保护在于：摘要在安装时被固定，因此您发布的内容事后无法被替换。 -`SHA256SUMS` 与产物文件存放在同一个发布版本中，因此它能证明字节内容正是你所发布的——但无法证明你是谁。任何拥有仓库写入权限的人都可以同时修改这两个文件。用户的保障在于：摘要在安装时被锁定，因此你所发布的内容此后不会在用户不知情的情况下被篡改。 +请从您控制写入权限的仓库发布，并像发布软件包一样对待策略包发布。 -请从你掌控写入权限的仓库发布，并像对待发布软件包一样对待规则包的发布。 +仓库还必须是**公开的**。安装是匿名 HTTPS，没有凭证可以提供，因此已存在的私有仓库会在构建或上传任何内容之前被拒绝，`publish` 创建的仓库也出于同样原因是公开的。`--allow-private` 可以为通过其他方式交付这三个资产的场景覆盖此限制，并明确表示没有 `policies add` 能访问到它们。只有发布版本重要：安装读取的是 `releases/download//`，从不接触您的 git 树。 -## 先观察，再执行 +## 观察模式优先于强制执行 -清单可以声明 `"effect": "observe"`。这些策略会正常运行，但其判决结果**仅被记录，随后丢弃**——不会阻止任何操作。这是在新规则真正拦截任何人的工作之前，用真实流量衡量其效果的方式。 +清单可以声明 `"effect": "observe"`——通过 `failproofai publish --effect observe` 设置。这些策略会运行，其裁决会被**记录并丢弃**——不会阻止任何操作。这是在新规则影响任何人工作之前，针对真实流量进行测量的方式。 ```json -{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +{ "id": "acme/support-agent", "version": "a1b2c3d4e5f6", "effect": "observe", "policies": [ ... ] } ``` \ No newline at end of file diff --git a/docs/zh/policies/rollback.mdx b/docs/zh/policies/rollback.mdx index 8593b6e8..0e4f6a68 100644 --- a/docs/zh/policies/rollback.mdx +++ b/docs/zh/policies/rollback.mdx @@ -1,41 +1,75 @@ --- -title: "回滚" -description: "在部署的策略干扰了正常 Agent 工作时，恢复已知的策略部署状态。" +title: "版本与回滚" +description: "每次发布都是不可变的版本，因此只需重新部署上一个良好版本，即可撤销影响有效 Agent 工作的发布。" icon: "rotate-ccw" --- -回滚会更改已部署的版本或移除策略分配，但不会清除解释该事件的决策历史记录。 +已发布的策略版本永不更改。编辑策略并重新发布会生成一个新版本，而不会覆盖已部署在机器上的版本。这正是回滚安全可靠的原因：上一个良好版本依然完整保存，回滚操作也不会抹去用于说明问题所在的决策历史。 -## 回滚某台机器 +## 查找版本 - 1. 进入 **Admin → enforcement**，展开受影响的机器，找到其上一个已知正常的策略集。 - 2. 选择 **edit**，恢复相应的版本和效果，然后应用新的部署。 - 3. 等待机器签入，然后验证上报的部署状态。 - 4. 打开 **Observe → policy** 及受影响的会话，确认正常工作不再被拦截。 + 前往 **Admin → policy editor**，打开 **library** 以比较某个策略的各版本或禁用其中一个。 + + + ```bash + fp policies list # 所有策略版本 + fp policies show # 单个版本及其源码 + ``` + + + +## 回滚某台机器 + + + 1. 前往 **Admin → enforcement**，展开受影响的机器，找出其最后一个已知良好的策略集。 + 2. 选择 **edit**，还原这些版本及其效果，然后应用新的部署。 + 3. 等待机器签入，再验证上报的部署状态。 + 4. 打开 **Observe → policy** 及受影响的会话，确认有效工作不再被拦截。 - 云端部署回滚是控制台操作流程。使用本地状态命令确认已修正的部署是否已到达该机器： + 每次对机器的部署都有一个编号的代次。列出所有代次后，选择其中一个进行恢复： ```bash - failproofai config --status + fp fleet history + fp fleet rollback ``` - `failproofai config --pause` 可在本地单个会话中暂停内置策略、自定义策略和约定策略，但不会暂停云端管理的策略，因此不能作为云端错误部署的临时解决方案。 + `rollback` 会以旧配置集生成一个新代次，而非回退计数器，因此历史记录保持只追加模式。若指定的代次所引用的策略已被禁用或删除，该命令将拒绝执行。执行此命令需要已登录且拥有 `policies:write` 权限的会话。`fp fleet diff ` 会对比预期配置与机器实际应用的配置——在机器下次轮询之前，状态显示为 `behind`；在机器本身上，`failproofai policies` 会列出当前运行的部署。 -## 何时回滚 +## 从所有机器上移除某个策略 + +```bash +fp policies disable # 从所有包含该策略的部署中移除它 +fp policies enable # 将其重新加入 +``` + +每次操作都会在其所影响的每个部署上生成一个新代次。不过，回滚某个代次并不是撤销 `disable` 的正确方式——`rollback` 会拒绝引用已禁用策略的代次，而禁用操作之前的所有代次都引用了该策略。`fp policies enable` 才是正确的恢复途径，它会自行生成一个新代次。 + +## 回滚策略包 + +策略包固定在你所安装的发布版本上，因此回滚意味着安装一个较早的版本： + +```bash +failproofai policies show FailproofAI/policies --releases # 列出所有已发布版本，以及当前使用的版本 +failproofai policies add FailproofAI/policies@a1b2c3d4e5f6 # 固定到该版本 +``` + +如果不在终端中操作，或使用了 `--policy`、`--category` 或 `--all` 参数，重新添加时会保留你之前选择的子集。若在终端中操作且未附加上述参数，则会打开选择器，并预先勾选作者的默认项，你的勾选结果将替换之前的选择——因此请重新勾选你原来的选项。 + +## 何时需要回滚 -- 某条策略拦截了预期中的生产操作。 -- 匹配量明显高于观测阶段预测的水平。 -- 某条策略依赖的字段未被集成提供。 +- 某个策略拦截了预期的生产操作。 +- 匹配量明显高于观测到的灰度发布预测值。 +- 某个策略依赖某些集成未提供的字段。 - 新版本在预期故障模式之外改变了行为。 -回滚后，打开受影响的会话，找出导致误报的条件。创建新版本，分别测试不安全场景和合法场景，然后重新进行观测阶段。 +回滚后，打开受影响的会话，找出导致误报的条件。发布一个新版本，[测试](/zh/policies/test)不安全情形和合法情形，在正式执行前再次观察其表现。 - 在发生事件期间暂停执行有时是合理的，但这会扩大该范围内所有有效策略的暴露面。在可能的情况下，优先回滚特定策略版本。 + `failproofai config --pause` 仅暂停当前会话的本地策略，对云端托管的策略无效，因此无法用于应对云端部署出现问题的情况。此外，暂停操作会扩大其作用范围内所有策略的暴露面；建议优先回滚出现异常的单个版本。 \ No newline at end of file diff --git a/docs/zh/policies/test.mdx b/docs/zh/policies/test.mdx new file mode 100644 index 00000000..921995ad --- /dev/null +++ b/docs/zh/policies/test.mdx @@ -0,0 +1,60 @@ +--- +title: "测试策略" +description: "在任何机器执行之前，针对已有流量对草稿进行回测，验证它能阻止应阻止的内容，并放行应允许的内容。" +icon: "flask-conical" +--- + +以两种方式测试每条策略：针对 Agent 已产生的流量，以及针对必须放行的合法操作。一条只见过不安全情况的策略，称不上经过了测试。 + +## 回测草稿 + + + + 策略编辑器会在发布前，将草稿针对您的 Agent 群已发出的调用进行重放。 + + 1. 在 **Admin → policy editor** 中打开草稿。编辑器会确认其能否正确解析为 JavaScript。 + 2. 在 **backtest** 中，选择要重放的 Agent 和时间窗口——默认为**所有 Agent** 和 **30d**——除非需要缩小范围，否则将最后一个过滤器保持在**全部**。 + 3. 选择 **run backtest**。 + + ![草稿解析为 JavaScript 后显示的回测面板，包含三个过滤器和运行回测操作，位于发布版本按钮上方。](/images/dashboard/policy-backtest.png) + + 结果显示该草稿对那些调用会做出何种处理——包括它会中断多少**正常运行**的调用。这些是在任何 Agent 遇到它们之前发现的误报：收紧草稿后重新运行，直到该数字降至可接受的范围。 + + + 回测是仪表板功能。在终端中，请改为针对您自行描述的事件运行策略（见下文）。 + + + +## 针对自定义事件运行 + +`fp policies test` 在您的机器上针对合成事件运行策略文件并检查决策结果。不会发布任何内容，也不会到达 Cloud： + +```bash +fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny +fp policies test ./checkout.policy.mjs --command "git push" --expect allow +``` + +使用 `--event`、`--tool`、`--command` 和 `--file` 来构造事件。策略自身的 `match` 过滤器仍然适用，因此如果策略不覆盖您描述的事件，会报告 `skipped` 而非给出决策——这通常说明其 `match` 比您预期的更窄。 + +## 在单台机器上运行 + +接下来，在您自己的机器上针对您自己的 Agent 进行真实执行： + +```bash +failproofai policies --install --custom ./checkout.policy.mjs --scope project +failproofai policies +``` + +第一条命令会验证并安装文件；第二条命令确认它已加载，以及当前正在执行的所有其他策略。让 Agent 执行策略所阻止的操作并观察其被拒绝，然后执行合法版本并观察其顺利通过。其他人不受影响。 + +在连接到 Cloud 的机器上，在 **Observe → policy** 下检查两个决策：按策略名称过滤，然后打开每个关联的会话，确认其匹配的工具输入和返回的原因。 + +## 测试异常情况 + +安装命令会拒绝以下情况：文件缺失、语法错误、无法解析的导入、顶层异常，或加载时超时的模块——因此每次修改文件或其导入内容后都要重新运行。在执行时，同样的损坏文件会被记录并**跳过**，以便所有其他策略继续运行：将生产日志中的加载警告视为执行缺失。惯例文件无需安装命令即可加载，因此请在 CI 中保留显式的 `failproofai policies --install --custom ` 步骤——这正是在策略损坏时使构建失败的关键。 + +然后向其提供 Agent 实际发送的内容，而不仅仅是您预期的输入：缺失字段、备用工具名称（如 `Write` 和 `Edit`）、Windows 路径、格式错误的输入。在每条路径上都返回明确的 `allow`、`instruct` 或 `deny`，保持函数确定性，并为任何外部调用设置较短的超时时间。 + +## 然后发布并观察 + +回测显示的是策略对已有流量会做出什么处理；它无法预测尚未见过的流量会带来什么。在编辑器中选择 **publish version**（或运行 `fp policies publish`），然后先以 **observe** 模式[部署它](/zh/policies/deploy)——此模式下只记录判决而不阻止任何内容——待其匹配结果能够区分不安全操作和有效操作后，再切换到执行模式。 \ No newline at end of file diff --git a/docs/zh/reference/cloud-cli.mdx b/docs/zh/reference/cloud-cli.mdx index 7f0cde4e..58b1c916 100644 --- a/docs/zh/reference/cloud-cli.mdx +++ b/docs/zh/reference/cloud-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof Cloud CLI" -description: "使用 fp 查询和管理 Failproof AI Cloud 的完整参考文档。" +description: "使用 fp 查询和管理 Failproof AI Cloud 的完整参考指南。" icon: "cloud-cog" --- -使用 `fp` 查看云端遥测数据、管理云端托管的执行策略（策略、机器群部署、护栏决策），以及管理审计、发现项、问题、告警、密钥、用户、查询和设置。本地钩子、策略、数据采集和机器注册请使用 [`failproofai`](/zh/reference/failproof-cli)。 +使用 `fp` 查看 Cloud 遥测数据、管理云端托管的执行策略（策略、机群部署、护栏决策），以及管理审计、发现项、问题、告警、密钥、用户、查询和设置。使用 [`failproofai`](/zh/reference/failproof-cli) 处理本地钩子、策略、数据捕获和机器注册。 -将发布的 Cloud CLI 作为独立工具安装： +以独立工具的方式安装正式发布版 Cloud CLI： ```bash uv tool install fp-cloud-cli @@ -26,13 +26,13 @@ fp whoami fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` -全局选项必须放在命令之前： +全局选项必须置于命令之前： ```bash fp --json sessions --since 24h ``` -运行 `fp COMMAND --help` 或 `fp COMMAND SUBCOMMAND --help` 查看终端帮助信息。 +运行 `fp COMMAND --help` 或 `fp COMMAND SUBCOMMAND --help` 可在终端查看帮助信息。 ## CLI 命令 @@ -40,11 +40,11 @@ fp --json sessions --since 24h | 命令 | 用途 | 选项 | | --- | --- | --- | -| `fp login` | 通过邮件一次性验证码登录并选择组织。 | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | 撤销并删除已保存的用户会话。 | — | +| `fp login` | 通过邮件发送的一次性验证码登录并选择组织。 | `--email`, `-e`；`--org`；`--force` | +| `fp logout` | 吊销并删除已保存的用户会话。 | — | | `fp whoami` | 显示当前身份、认证模式、组织和权限。 | — | | `fp version` | 显示已安装的 CLI 版本。 | — | -| `fp help` | 显示顶级命令帮助信息。 | — | +| `fp help` | 显示顶级命令帮助。 | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,24 +57,24 @@ fp whoami fp events [OPTIONS] ``` -列出各个 Agent 事件。默认的轻量级数据流不含原始载荷；仅在有限的排查场景中使用 `--full`。 +列出各个 Agent 事件。默认的轻量数据流不包含原始载荷；仅在有限范围的排查工作中使用 `--full`。 | 选项 | 说明 | | --- | --- | -| `--limit`, `-n ` | 最大总行数。默认：`50`。 | +| `--limit`, `-n ` | 最大总行数。默认值：`50`。 | | `--since ` | `all`、`15m`、`1h`、`6h`、`24h` 或 `7d`。 | | `--from ` / `--to ` | ISO 8601 UTC 时间范围；覆盖 `--since`。 | -| `--env ` | 环境过滤器；可重复使用或以逗号分隔。 | -| `--event-type ` | 事件类型过滤器；可重复使用或以逗号分隔。 | -| `--agent-id ` | Agent 过滤器；可重复使用或以逗号分隔。 | -| `--session-id ` | 会话过滤器；可重复使用或以逗号分隔。 | -| `--search ` | 载荷文本搜索；可重复使用，任意词匹配即可。 | -| `--order asc\|desc` | 时间排序。默认：最新优先。 | -| `--all` | 自动分页，直至达到 `--limit`。 | -| `--cursor ` | 从不透明游标处恢复。 | -| `--page-size ` | 使用 `--all` 时每次请求的行数；最大 `200`。 | +| `--env ` | 环境筛选器；可重复指定或以逗号分隔多个值。 | +| `--event-type ` | 事件类型筛选器；可重复指定或以逗号分隔多个值。 | +| `--agent-id ` | Agent 筛选器；可重复指定或以逗号分隔多个值。 | +| `--session-id ` | 会话筛选器；可重复指定或以逗号分隔多个值。 | +| `--search ` | 载荷文本搜索；可重复指定，任意词匹配即可。 | +| `--order asc\|desc` | 时间排序方式。默认：最新优先。 | +| `--all` | 自动分页，最多获取 `--limit` 条记录。 | +| `--cursor ` | 从不透明游标处继续获取。 | +| `--page-size ` | 与 `--all` 配合使用时每次请求的行数；最大值 `200`。 | | `--full` | 通过较重的事件端点获取原始载荷。 | -| `--fields ` | 仅返回指定字段；请求 `payload` 会启用完整模式。 | +| `--fields ` | 仅返回指定字段；请求 `payload` 字段时自动启用完整模式。 | ```bash fp events --session-id --order asc --all --limit 10000 @@ -82,7 +82,7 @@ fp --json events --full --session-id --all --limit 10000 ``` - `--all` 会分页获取数据，**直至达到 `--limit`**，而 `--limit` 默认为 **50** — 因此单独使用 `--all` 会在 50 行时停止。提前停止时，响应中会附带 `next_cursor` 以便继续获取；`"next_cursor": null` 表示数据流已真正耗尽。 + `--all` 分页获取的记录数**最多到 `--limit`**，而 `--limit` 默认为 **50**——因此单独使用 `--all` 时会在 50 条时停止。若提前停止，响应中会携带 `next_cursor` 以便继续获取；`"next_cursor": null` 表示数据流已真正耗尽。 ### 会话 @@ -93,16 +93,16 @@ fp sessions [OPTIONS] | 选项 | 说明 | | --- | --- | -| `--limit`, `-n ` | 最大总行数。默认：`50`。 | +| `--limit`, `-n ` | 最大总行数。默认值：`50`。 | | `--since ` | `all`、`15m`、`1h`、`6h`、`24h` 或 `7d`。 | | `--from ` / `--to ` | ISO 8601 UTC 时间范围；覆盖 `--since`。 | -| `--env ` | 环境过滤器；可重复使用或以逗号分隔。 | -| `--status ` | `done`、`error` 或 `timeout`；可重复使用或以逗号分隔。 | -| `--agent-id ` | 匹配涉及任意所选 Agent 的会话。 | -| `--session-id ` | 会话过滤器；可重复使用或以逗号分隔。 | -| `--all` | 自动分页，直至达到 `--limit`。 | -| `--cursor ` | 从不透明游标处恢复。 | -| `--page-size ` | 使用 `--all` 时每次请求的行数；最大 `200`。 | +| `--env ` | 环境筛选器；可重复指定或以逗号分隔多个值。 | +| `--status ` | `done`、`error` 或 `timeout`；可重复指定或以逗号分隔多个值。 | +| `--agent-id ` | 匹配涉及所选 Agent 的会话。 | +| `--session-id ` | 会话筛选器；可重复指定或以逗号分隔多个值。 | +| `--all` | 自动分页，最多获取 `--limit` 条记录。 | +| `--cursor ` | 从不透明游标处继续获取。 | +| `--page-size ` | 与 `--all` 配合使用时每次请求的行数；最大值 `200`。 | | `--fields ` | 仅返回指定字段。 | | `--full-ids` | 在终端输出中不缩短会话 ID。 | | `--agents` | 展开多 Agent 会话的 Agent 列表。 | @@ -115,15 +115,15 @@ fp evals [OPTIONS] | 选项 | 说明 | | --- | --- | -| `--aggregate` | 显示总计和各分数统计，而非单条评估记录。 | -| `--limit`, `-n ` | 最大列表行数。默认：`50`。 | +| `--aggregate` | 显示总计和各评分的统计数据，而非逐条评估结果。 | +| `--limit`, `-n ` | 最大列表行数。默认值：`50`。 | | `--since`, `--from`, `--to` | 选择时间范围。 | -| `--env`, `--status`, `--agent-id`, `--session-id` | 每个过滤器精确匹配一个值。 | -| `--score KEY:MIN..MAX` | 分数范围；可重复使用，所有范围必须同时满足。 | +| `--env`, `--status`, `--agent-id`, `--session-id` | 每个筛选器精确匹配一个值。 | +| `--score KEY:MIN..MAX` | 评分范围；可重复指定，所有范围必须同时满足。 | | `--all`, `--cursor`, `--page-size` | 控制列表分页。 | | `--fields ` | 仅返回指定字段。 | | `--full-ids` | 显示完整的会话 ID。 | -| `--scores-full` | 在终端输出中显示所有分数。 | +| `--scores-full` | 在终端输出中显示所有评分。 | ### 错误 @@ -133,25 +133,25 @@ fp errors [OPTIONS] | 选项 | 说明 | | --- | --- | -| `--aggregate` | 汇总匹配的错误，而非列出各行。 | -| `--limit`, `-n ` | 最大列表行数。默认：`50`。 | +| `--aggregate` | 对匹配的错误进行汇总，而非逐行列出。 | +| `--limit`, `-n ` | 最大列表行数。默认值：`50`。 | | `--since`, `--from`, `--to` | 选择时间范围。 | | `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | 缩小错误范围。 | -| `--search ` | 搜索载荷文本；可重复使用。 | -| `--order asc\|desc` | 时间排序。 | +| `--search ` | 搜索载荷文本；可重复指定。 | +| `--order asc\|desc` | 时间排序方式。 | | `--all`, `--cursor`, `--page-size` | 控制列表分页。 | | `--fields ` | 仅返回指定字段。 | | `--full-ids` | 显示完整的会话 ID。 | -### 使用情况和过滤值 +### 用量与筛选器值 | 命令 | 用途 | | --- | --- | -| `fp usage` | 显示当前计量周期的使用情况。 | +| `fp usage` | 显示当前计量周期的用量。 | | `fp list envs` | 列出已观测到的环境。 | | `fp list agents` | 列出已观测到的 Agent ID。 | | `fp list event_types` | 列出事件类型。 | -| `fp list score_filters` | 列出评估分数键。 | +| `fp list score_filters` | 列出评估评分键。 | | `fp list models` | 列出模型名称。 | | `fp list hooks` | 列出钩子名称。 | | `fp list tools` | 列出工具名称。 | @@ -162,7 +162,7 @@ fp errors [OPTIONS] | 命令 | 用途 | | --- | --- | | `fp orgs list` | 列出可访问的组织。 | -| `fp orgs switch [SLUG]` | 保存活跃组织；省略时会提示选择。 | +| `fp orgs switch [SLUG]` | 保存当前活跃组织；省略时弹出选择提示。 | | `fp orgs current` | 显示当前活跃组织。 | | `fp orgs perms` | 显示您在当前活跃组织中的权限。 | @@ -170,36 +170,36 @@ fp errors [OPTIONS] | 命令 | 用途 | 选项 | | --- | --- | --- | -| `fp keys list` | 列出组织密钥。 | `--show-id`; `--fields ` | +| `fp keys list` | 列出组织密钥。 | `--show-id`；`--fields ` | | `fp keys show NAME` | 显示一个密钥及其授权。 | — | -| `fp keys create NAME` | 创建密钥并一次性显示其密钥值。 | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | 替换权限集或调整授权。 | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | 轮换密钥值并一次性显示替换后的值。 | `--yes`, `-y` | -| `fp keys disable NAME` | 永久撤销一个密钥。 | `--yes`, `-y` | +| `fp keys create NAME` | 创建密钥并一次性展示其私钥。 | `--permission-set`；`--add`；`--remove` | +| `fp keys update NAME` | 替换权限集或调整授权。 | `--permission-set`；`--add`；`--remove`；`--yes`, `-y` | +| `fp keys regenerate NAME` | 轮换私钥并一次性展示替换后的密钥。 | `--yes`, `-y` | +| `fp keys disable NAME` | 永久吊销密钥。 | `--yes`, `-y` | -权限令牌使用 `resource:action` 格式，例如 `events:add`。可重复使用 `--add`、以逗号分隔令牌，或使用点号分隔的操作，例如 `events:read.add`。 +权限令牌格式为 `resource:action`，例如 `events:add`。可重复使用 `--add`、以逗号分隔令牌，或使用点式操作如 `events:read.add`。 ### 查询 | 命令 | 用途 | 选项 | | --- | --- | --- | -| `fp query list` | 列出已保存的查询。 | `--show-id`; `--fields ` | +| `fp query list` | 列出已保存的查询。 | `--show-id`；`--fields ` | | `fp query show NAME` | 显示一个查询。 | — | -| `fp query create NAME` | 保存一个查询。 | `--sql `; `--description` | -| `fp query update NAME` | 更新或重命名一个查询。 | `--name`; `--sql`; `--description`; `--yes`, `-y` | -| `fp query delete NAME` | 删除一个已保存的查询。 | `--yes`, `-y` | -| `fp query run [NAME]` | 运行已保存的查询或临时 SQL。 | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | 列出可查询的表或查看某个表的结构。 | — | +| `fp query create NAME` | 保存一个查询。 | `--sql `；`--description` | +| `fp query update NAME` | 更新或重命名查询。 | `--name`；`--sql`；`--description`；`--yes`, `-y` | +| `fp query delete NAME` | 删除已保存的查询。 | `--yes`, `-y` | +| `fp query run [NAME]` | 运行已保存的查询或临时 SQL。 | `--sql`；`--limit`；`--all`；`--arg`, `--param` | +| `fp query schema [TABLE]` | 列出可查询的表或查看某张表的结构。 | — | ### 用户 | 命令 | 用途 | 选项 | | --- | --- | --- | -| `fp users list` | 列出组织成员。 | `--active-only`; `--show-id` | -| `fp users show EMAIL` | 显示一名成员及其授权。 | — | -| `fp users create EMAIL` | 添加成员。 | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | 修改成员授权。 | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp users disable EMAIL` | 禁止登录。 | `--yes`, `-y` | +| `fp users list` | 列出组织成员。 | `--active-only`；`--show-id` | +| `fp users show EMAIL` | 显示成员及其授权。 | — | +| `fp users create EMAIL` | 添加成员。 | `--permission-set`；`--add`；`--remove` | +| `fp users update EMAIL` | 修改成员的授权。 | `--permission-set`；`--add`；`--remove`；`--yes`, `-y` | +| `fp users disable EMAIL` | 禁用登录。 | `--yes`, `-y` | | `fp users enable EMAIL` | 重新启用登录。 | `--yes`, `-y` | ### 设置 @@ -208,7 +208,7 @@ fp errors [OPTIONS] | --- | --- | --- | | `fp settings list` | 列出组织设置及当前值。 | — | | `fp settings schema` | 显示可接受的值和说明。 | — | -| `fp settings set KEY` | 修改现有设置。 | 三选一：`--value`、`--json-value`、`--file`；可选 `--yes`, `-y` | +| `fp settings set KEY` | 修改已有设置。 | 以下三选一：`--value`、`--json-value`、`--file`；可选 `--yes`, `-y` | ### 告警 @@ -216,35 +216,35 @@ fp errors [OPTIONS] | --- | --- | --- | | `fp alerts list` | 列出告警规则。 | `--show-id` | | `fp alerts show NAME` | 显示一条告警。 | — | -| `fp alerts create NAME` | 创建告警。 | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | -| `fp alerts update NAME` | 更新或重命名告警。 | 创建选项加上 `--name`; `--yes`, `-y` | +| `fp alerts create NAME` | 创建告警。 | `--file`；`--description`；`--severity`；`--trigger-kind`；`--trigger-spec`；`--channels`；`--eval-interval-secs`；`--min-breaches`；`--eval-window` | +| `fp alerts update NAME` | 更新或重命名告警。 | 创建选项加上 `--name`；`--yes`, `-y` | | `fp alerts delete NAME` | 删除告警。 | `--yes`, `-y` | -| `fp alerts test NAME` | 发送测试通知。 | `--channels`; `--yes`, `-y` | +| `fp alerts test NAME` | 发送测试通知。 | `--channels`；`--yes`, `-y` | -告警严重级别为 `info`、`warning` 和 `critical`。触发类型为 `metric_threshold`、`custom_sql`、`evaluation_score`、`eval_compound` 和 `per_event`。评估间隔必须在 30 至 86,400 秒之间。 +告警严重级别为 `info`、`warning` 和 `critical`。触发器类型为 `metric_threshold`、`custom_sql`、`evaluation_score`、`eval_compound` 和 `per_event`。评估间隔须在 30 至 86,400 秒之间。 ### 审计 | 命令 | 用途 | 选项 | | --- | --- | --- | -| `fp audits list` | 列出审计。 | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | 显示一条审计定义及其状态。 | — | -| `fp audits create NAME` | 创建审计并立即将其第一次运行加入队列。 | 参见[创建选项](#audit-create-options)。 | -| `fp audits edit NAME` | 替换审计设置，保留未指定的值。 | 创建定义选项；`--name`; `--yes`, `-y` | -| `fp audits delete NAME` | 删除审计、其发现项及运行历史。 | `--yes`, `-y` | -| `fp audits run NAME` | 手动将一次运行加入队列。 | — | -| `fp audits runs NAME` | 列出运行历史。 | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | 显示摘要和参考 URL 的获取状态。 | — | -| `fp audits context-set NAME` | 修改摘要或参考 URL。 | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits list` | 列出审计任务。 | `--enabled-only`；`--show-id` | +| `fp audits show NAME` | 显示一个审计定义及其状态。 | — | +| `fp audits create NAME` | 创建审计任务并立即将首次运行加入队列。 | 参见[创建选项](#audit-create-options)。 | +| `fp audits edit NAME` | 替换审计设置，保留未指定的值。 | 创建定义选项；`--name`；`--yes`, `-y` | +| `fp audits delete NAME` | 删除审计任务、其发现项及运行历史。 | `--yes`, `-y` | +| `fp audits run NAME` | 手动触发一次运行。 | — | +| `fp audits runs NAME` | 列出运行历史。 | `--limit`, `-n`；`--show-id` | +| `fp audits context-show NAME` | 显示简报和参考 URL 的获取状态。 | — | +| `fp audits context-set NAME` | 修改简报或参考 URL。 | `--text`；`--text-file`；`--url`；`--clear-urls` | | `fp audits context-refresh NAME` | 重新获取参考 URL。 | — | -| `fp audits findings` | 列出发现项。 | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | 显示一条发现项及其证据。 | — | -| `fp audits ack FINDING_ID` | 确认一条发现项。 | `--reason` | -| `fp audits mute FINDING_ID` | 抑制一个重复出现的模式。 | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | 将模式标记为不可操作并抑制它。 | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | 将发现项标记为已修复，不做未来抑制。 | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | 将发现项返回活跃队列并清除抑制。 | — | -| `fp audits assign FINDING_ID` | 设置发现项的负责人。 | 必填 `--to ` | +| `fp audits findings` | 列出发现项。 | `--audit`；`--run-id`；`--status`；`--limit`, `-n`；`--offset`；`--show-id` | +| `fp audits finding FINDING_ID` | 显示一个发现项及其证据。 | — | +| `fp audits ack FINDING_ID` | 确认一个发现项。 | `--reason` | +| `fp audits mute FINDING_ID` | 抑制重复出现的模式。 | `--reason`；`--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | 将某个模式标记为不可操作并抑制它。 | `--reason`；`--yes`, `-y` | +| `fp audits resolve FINDING_ID` | 将发现项标记为已修复，不再抑制。 | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | 将发现项重新加入活跃队列并清除抑制状态。 | — | +| `fp audits assign FINDING_ID` | 设置发现项的负责人。 | 必需：`--to ` | #### 审计创建选项 @@ -261,42 +261,42 @@ fp audits create checkout-reliability \ | 选项 | 说明 | | --- | --- | -| `--file ` | 基于 JSON 创建定义，或使用 `-` 从 stdin 读取。显式标志会覆盖文件中的值。 | -| `--description ` | 描述故障问题或用途。 | -| `--enabled` / `--disabled` | 启动时是否开启调度。默认：启用。 | -| `--schedule-interval-secs ` | `3600`–`604800`。默认：`86400`。 | -| `--schedule-anchor ` | 以 ISO 8601 格式表示的固定 UTC 基准时间。默认：下一个 09:00 UTC。 | -| `--window-mode since_last\|fixed` | 从上一个完整分析窗口后继续，或反复检查一个滚动窗口。默认：`since_last`。 | -| `--lookback-window-secs ` | `3600`–`7776000`。默认：`604800`。 | -| `--scope ''` | 按 `environments`、`agent_ids` 或其他支持的范围字段过滤。 | -| `--ignore-error-type ` | 排除错误类型；可重复使用或以逗号分隔。 | -| `--llm` / `--no-llm` | 启用或禁用 Agent 分析。默认：启用。 | -| `--top-k ` | 保留 `1`–`500` 条发现项。默认：`50`。 | +| `--file ` | 从 JSON 文件读取定义，或使用 `-` 从 stdin 读取。显式指定的标志会覆盖文件中的值。 | +| `--description ` | 描述需要排查的故障问题或目的。 | +| `--enabled` / `--disabled` | 开启或关闭调度。默认：开启。 | +| `--schedule-interval-secs ` | `3600`–`604800`。默认值：`86400`。 | +| `--schedule-anchor ` | 以 ISO 8601 格式指定固定的 UTC 基准时间。默认：下一个 09:00 UTC。 | +| `--window-mode since_last\|fixed` | 在上次完整分析窗口之后继续，或反复检查滚动窗口。默认：`since_last`。 | +| `--lookback-window-secs ` | `3600`–`7776000`。默认值：`604800`。 | +| `--scope ''` | 按 `environments`、`agent_ids` 或其他支持的范围字段筛选。 | +| `--ignore-error-type ` | 排除错误类型；可重复指定或以逗号分隔。 | +| `--llm` / `--no-llm` | 启用或禁用智能体分析。默认：启用。 | +| `--top-k ` | 保留 `1`–`500` 条发现项。默认值：`50`。 | | `--sensitivity low\|medium\|high` | 设置报告敏感度。默认：`medium`。 | | `--channels ''` | 通知渠道数组。 | -| `--text ` | 内联摘要，最多 8,192 个字符。 | -| `--text-file ` | 从文件读取摘要；与 `--text` 互斥。 | +| `--text ` | 内联简报，最多 8,192 个字符。 | +| `--text-file ` | 从文件读取简报；与 `--text` 互斥。 | | `--url ` | 添加公开 HTTPS 参考链接；最多重复五次。 | -在创建时附加上下文，以便第一次运行就能使用。创建操作会在队列中的运行开始之前，将定义和上下文一并提交。 +如果首次运行需要上下文信息，请在创建时一并提供。创建操作会在队列中的运行开始之前，将定义和上下文一起提交。 - `fp audits run` 是异步的。在读取发现项之前，请轮询 `fp audits runs NAME`，等待最近一次运行成功或失败。 + `fp audits run` 是异步操作。请轮询 `fp audits runs NAME`，等待最新运行成功或失败后，再读取其发现项。 ### 问题 | 命令 | 用途 | 选项 | | --- | --- | --- | -| `fp issues list` | 列出问题。 | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | 统计开放或指定状态的问题数量。 | `--state` | +| `fp issues list` | 列出问题。 | `--state`；`--alert-id`；`--limit`, `-n`；`--show-id` | +| `fp issues count` | 统计处于开放状态或指定状态的问题数量。 | `--state` | | `fp issues show INCIDENT_ID` | 显示问题详情、评论、订阅者和活动记录。 | — | -| `fp issues open` | 创建手动或关联告警的问题。 | 必填 `--summary`；可选 `--title`、`--alert-id`、`--severity` | +| `fp issues open` | 创建手动或与告警关联的问题。 | 必需：`--summary`；可选：`--title`、`--alert-id`、`--severity` | | `fp issues ack INCIDENT_ID` | 确认一个问题。 | — | -| `fp issues assign INCIDENT_ID` | 替换责任人；省略选项则清除责任人。 | 可重复 `--assignee` | +| `fp issues assign INCIDENT_ID` | 替换负责人；省略选项则清除负责人。 | 可重复的 `--assignee` | | `fp issues resolve INCIDENT_ID` | 解决一个问题。 | `--yes`, `-y` | | `fp issues comment-list INCIDENT_ID` | 列出评论。 | — | -| `fp issues comment-add INCIDENT_ID` | 添加评论。 | 二选一：`--body`、`--file` | +| `fp issues comment-add INCIDENT_ID` | 添加评论。 | 以下二选一：`--body`、`--file` | | `fp issues comment-delete INCIDENT_ID COMMENT_ID` | 删除评论。 | `--yes`, `-y` | | `fp issues subscribers INCIDENT_ID` | 列出订阅者。 | — | | `fp issues subscribe INCIDENT_ID` | 订阅自己或其他操作员。 | `--email` | @@ -311,48 +311,48 @@ fp audits create checkout-reliability \ | `fp agent health` | 检查助手的可用性和配置。 | — | | `fp agent models` | 列出可用的助手模型。 | — | | `fp agent chats` | 列出已保存的对话。 | — | -| `fp agent ask [MESSAGE]` | 开始或继续对话；省略消息时从 stdin 读取。 | `--chat`; `--model`; `--page-context` | +| `fp agent ask [MESSAGE]` | 开始或继续对话；省略消息时从 stdin 读取。 | `--chat`；`--model`；`--page-context` | | `fp agent show CHAT_ID` | 显示已保存的对话内容。 | — | -| `fp agent rename CHAT_ID` | 重命名对话。 | 必填 `--title` | +| `fp agent rename CHAT_ID` | 重命名对话。 | 必需：`--title` | | `fp agent delete CHAT_ID` | 删除对话。 | `--yes`, `-y` | ### 策略 -云端托管的策略版本。**仅限会话使用** — 此处每条命令在使用 API 密钥时会在发出任何请求之前以退出码 `2` 退出，因为这些是有意从 `/v1` 中排除的仅限 root 的写入路由。 +云端托管的策略版本。**仅限会话** — 此处所有命令在 API 密钥下均会在发出任何请求之前退出并返回 `2`，因为这些是仅限根用户的写入路由，在 `/v1` 中刻意不提供。 | 命令 | 用途 | 选项 | | --- | --- | --- | | `fp policies list` | 列出策略版本。 | `--json` | -| `fp policies show POLICY_ID` | 显示一个策略及其源码。 | — | -| `fp policies publish NAME PATH` | 从本地 `.mjs` 文件生成一个版本。 | `--description`; `--no-verify` | -| `fp policies enable POLICY_ID` | 将其重新添加到所有已移除的部署中，每个部署生成新的代次。 | `--yes`, `-y` | -| `fp policies disable POLICY_ID` | 从所有包含该策略的部署中移除，每个部署生成新的代次。 | `--yes`, `-y` | +| `fp policies show POLICY_ID` | 显示一个策略及其源代码。 | — | +| `fp policies publish NAME PATH` | 从本地 `.mjs` 文件创建一个版本。 | `--description`；`--no-verify` | +| `fp policies enable POLICY_ID` | 将其重新添加到所有已移除它的部署中，并在每个部署上生成新的代次。 | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | 从所有携带它的部署中移除，并在每个部署上生成新的代次。 | `--yes`, `-y` | | `fp policies delete POLICY_ID` | 删除一个策略版本。 | `--yes`, `-y` | -| `fp policies test PATH` | 针对合成上下文在本地运行策略。应用每个策略的 `match` 过滤器，因此不覆盖指定事件/工具的策略会报告为 `skipped` 而非运行。 | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | +| `fp policies test PATH` | 在本地针对合成上下文运行策略。对每个策略的 `match` 过滤器逐一应用，不覆盖给定事件/工具的策略会被报告为 `skipped` 而非运行。 | `--event`；`--tool`；`--command`；`--file`；`--expect` | | `fp policies compose PROMPT` | 使用助手起草策略。需要 `policies:write` 权限。 | — | -### 机器群 +### 机群 -哪些机器运行哪些策略。**仅限会话使用**，原因同上。 +控制哪些机器运行哪些策略。**仅限会话**，原因同上。 | 命令 | 用途 | 选项 | | --- | --- | --- | | `fp fleet list` | 列出已注册的机器及其部署代次。 | — | -| `fp fleet show MACHINE_ID` | 查看某台机器当前运行的策略集。 | — | -| `fp fleet deploy MACHINE_ID` | **替换机器的完整策略集。** 打印计划，在无 `--json` 的交互式终端中会提示确认。 | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | -| `fp fleet diff MACHINE_ID` | 将某台机器与另一个部署进行比较。 | — | -| `fp fleet history MACHINE_ID` | 查看某台机器的历史部署记录。 | — | -| `fp fleet rollback MACHINE_ID` | 还原到之前的部署。 | `--yes`, `-y` | -| `fp fleet rename MACHINE_ID` | 为机器指定一个易读的名称。 | 必填 `--name` | +| `fp fleet show MACHINE_ID` | 显示机器当前运行的策略集。 | — | +| `fp fleet deploy MACHINE_ID` | **替换机器的整个策略集。** 打印变更计划，在无 `--json` 的交互式终端中会进行确认提示。 | `--add`；`--remove`；`--set`；`--create`；`--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | 将机器与另一个部署进行比较。 | — | +| `fp fleet history MACHINE_ID` | 查看机器的历史部署记录。 | — | +| `fp fleet rollback MACHINE_ID GENERATION` | 以新代次的形式恢复历史代次的策略集。 | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | 为机器设置可读名称。 | 必需：`--name` | ### 护栏 -执行策略的实际操作记录。**仅限会话使用**，原因同上。 +记录执行的实际情况。**仅限会话**，原因同上。 | 命令 | 用途 | 选项 | | --- | --- | --- | -| `fp guardrails summary` | 覆盖率、已拦截/已评估总计、拒绝迷你图以及各策略表格。 | `--since`（`1h`、`6h`、`24h`、`7d`）；`--machine` | -| `fp guardrails timeline` | 在时间窗口内按桶划分的决策，汇总所有策略来源。 | `--since`（`1h`、`6h`、`24h`、`7d`）；`--machine` | +| `fp guardrails summary` | 显示覆盖范围、拦截/评估总计、拒绝趋势图以及每条策略的汇总表。 | `--since`（`1h`、`6h`、`24h`、`7d`）；`--machine` | +| `fp guardrails timeline` | 显示时间窗口内各决策桶的汇总，跨所有策略来源求和。 | `--since`（`1h`、`6h`、`24h`、`7d`）；`--machine` | ## 全局标志 @@ -363,18 +363,18 @@ fp audits create checkout-reliability \ | `--org ` | 为本次调用选择组织。 | | `--token ` | 覆盖已保存的用户会话令牌。 | | `--api-key ` | 使用 API 密钥进行自动化认证；不会被保存。 | -| `--timeout ` | HTTP 超时时间；必须为正数。默认：`30`。 | -| `--quiet`, `-q` | 在 stderr 上抑制状态输出。 | +| `--timeout ` | HTTP 超时时间；必须为正数。默认值：`30`。 | +| `--quiet`, `-q` | 抑制 stderr 上的状态输出。 | | `--no-color` | 禁用彩色输出。 | | `--insecure` / `--secure` | 禁用或恢复 TLS 证书验证。 | | `--version` | 打印版本号并退出。 | | `--help`, `-h` | 显示帮助信息。 | -`--api-key` 用于自动化场景。登录、切换组织和助手命令需要用户会话。 +`--api-key` 面向自动化场景设计。登录、组织切换和助手命令需要用户会话。 ## 环境变量 -| 变量 | 等效选项或用途 | +| 变量 | 对应选项或用途 | | --- | --- | | `FP_DASHBOARD_URL` | `--base-url` | | `FP_ORG` | `--org` | @@ -382,18 +382,18 @@ fp audits create checkout-reliability \ | `FP_API_KEY` | `--api-key` | | `FP_JSON` | `--json` | | `FP_INSECURE` | `--insecure` | -| `FP_HOME` | 重新指定 CLI 配置目录（默认 `~/.failproofai/fpcli`）。 | -| `FP_ANALYTICS_DISABLED` 或 `DO_NOT_TRACK` | 禁用匿名 CLI 分析。 | +| `FP_HOME` | 重新指定 CLI 配置目录（默认为 `~/.failproofai/fpcli`）。 | +| `FP_ANALYTICS_DISABLED` 或 `DO_NOT_TRACK` | 禁用匿名 CLI 分析数据收集。 | | `NO_COLOR` | 禁用彩色输出。 | -显式标志会覆盖环境变量，环境变量会覆盖已保存的配置。在 API 密钥模式下，请通过 `--org` 或 `FP_ORG` 显式指定租户。 +显式标志会覆盖环境变量，环境变量会覆盖已保存的配置。在 API 密钥模式下，请通过 `--org` 或 `FP_ORG` 明确指定租户。 - 这些变量的 `AGENTEYE_*` 写法**不会被 `fp` 读取**，也从来没有被读取过 — CLI 声明的是 `FP_*`（`fp_cli/app.py`），未知变量不会报错。设置 `AGENTEYE_DASHBOARD_URL` 不会改变 CLI 的目标地址；它会被忽略，命令将默默地继续连接已保存的 Dashboard。 + 这些变量的 `AGENTEYE_*` 命名形式**不会被 `fp` 读取**，从来如此 — CLI 声明的是 `FP_*`（`fp_cli/app.py`），未知变量不会报错。设置 `AGENTEYE_DASHBOARD_URL` 不会改变 CLI 的目标地址；该变量会被忽略，命令会静默地继续使用已保存的 Dashboard 地址运行。 - `AGENTEYE_HOME` 和 `AGENTEYE_ENVIRONMENT` 仍然存在，但它们属于**采集器和遥测 SDK**，而非此 CLI。 + `AGENTEYE_HOME` 和 `AGENTEYE_ENVIRONMENT` 仍然存在，但它们属于**采集器和遥测 SDK**，而非本 CLI。 - 执行删除、撤销、抑制、解决或替换配置的命令默认会提示确认。请在验证活跃组织和目标后再使用 `--yes`。 + 执行删除、吊销、抑制、解决或替换配置的命令默认会有确认提示。请在验证当前活跃组织和目标后再使用 `--yes`。 \ No newline at end of file diff --git a/docs/zh/reference/custom-agents.mdx b/docs/zh/reference/custom-agents.mdx index 6b83fe7e..bb317d60 100644 --- a/docs/zh/reference/custom-agents.mdx +++ b/docs/zh/reference/custom-agents.mdx @@ -1,21 +1,21 @@ --- title: "自定义 Agent" -description: "failproofai-sdk 的配置、事件目录、关联规则及数据传输说明。" +description: "failproofai-sdk 的配置、事件目录、关联规则及数据投递说明。" icon: "python" --- -本页介绍每个配置项、方法和字段的用途。如果您是第一次进行埋点，请先阅读指南——本页仅供查阅参考。 +本页介绍每个配置项、方法和字段的作用。如果你是第一次接入，请先阅读入门指南——本页面仅供查阅参考。 安装、埋点、事件方法、完整示例及常见问题。 - + LangChain、CrewAI、LlamaIndex 和 Pydantic AI 只需一次调用即可完成自动埋点。 -需要 Python 3.10 或更高版本。无运行时依赖。 +需要 Python 3.10 或更高版本，无运行时依赖。 ## 安装 @@ -23,24 +23,30 @@ icon: "python" pip install failproofai-sdk ``` -该包以 `failproofai-sdk` 为名安装，在 Python 中以 `failproofai_sdk` 导入。框架扩展（如 `failproofai-sdk[langgraph]`）会同时安装对应框架；适配器始终包含在基础 wheel 包中。 +包名为 `failproofai-sdk`，在 Python 中以 `failproofai_sdk` 导入。`failproofai-sdk[langgraph]` 等框架扩展会同时安装对应框架本身；适配器始终包含在基础安装包中。 ## 连接 Failproof 守护进程 - 1. 进入 **Admin → Keys**，创建一个具有 `events:add` 权限的密钥。 + 1. 前往 **Admin → Keys**，创建一个具有 `events:add` 权限的密钥。 2. 在 Agent 所在机器上[将 Failproof 守护进程连接到 Cloud](/zh/start/setup#connect-a-machine-to-cloud)。 - 3. 运行一次已埋点的会话，然后在 **Observe → Events** 下找到其准确 ID。 - 4. 进入 **Observe → Sessions**，选择相同的环境，打开重建后的追踪记录。 + 3. 运行一次已埋点的会话，然后在 **Observe → Events** 下找到其确切 ID。 + 4. 前往 **Observe → Sessions**，选择相同的环境，打开重建后的追踪记录。 ![以执行图和有序事件追踪方式重建的自定义 Python Agent 会话。](/images/dashboard/session-detail.png) + 将 `events:add` 密钥读入 Shell。`read -s` 通过不回显的提示符输入，确保密钥不会出现在命令行或 Shell 历史记录中： + + ```bash + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + 然后完成机器配置并验证连接状态： + ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token + failproofai config failproofai config --status ``` @@ -58,32 +64,32 @@ failproofai_sdk.configure( ) ``` -| 参数 | 用途 | +| 参数 | 说明 | | --- | --- | -| `environment` | 每个事件的标签，如 `production`、`staging`、`prod-eu`，默认值为 `dev`。 | -| `flush_interval` | 后台线程写入磁盘的时间间隔（秒），默认值为 `0.5`。 | -| `base_dir` | 写入路径，默认为守护进程的缓冲目录，通常无需修改。 | +| `environment` | 每个事件上的环境标签，如 `production`、`staging`、`prod-eu`，默认为 `dev`。 | +| `flush_interval` | 后台线程写入磁盘的频率，单位为秒，默认为 `0.5`。 | +| `base_dir` | 写入目录，默认为守护进程的 spool 目录，除非有特殊需求，否则保持默认即可。 | -也可通过环境变量进行设置： +也可通过环境变量进行配置： -| 变量 | 用途 | +| 变量 | 说明 | | --- | --- | -| `AGENTEYE_ENVIRONMENT` | 无需修改代码即可设置 `environment`，适用于标签属于部署环境而非应用本身的场景。`configure()` 中的参数优先级高于此变量。 | -| `FAILPROOFAI_HOME` | 更改 Failproof AI 根目录（包含缓冲目录）的位置。 | -| `FAILPROOFAI_SDK_STRICT` | 设为 `1` 时，埋点错误会抛出异常而非仅记录日志。 | -| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | 设为 `1` 时，框架兼容性问题会抛出异常而非仅发出警告并继续运行。 | +| `AGENTEYE_ENVIRONMENT` | 无需修改代码即可设置 `environment`，适用于环境标签属于部署配置而非应用代码的场景。`configure()` 参数优先级高于该变量。 | +| `FAILPROOFAI_HOME` | 移动存放 spool 的 Failproof AI 根目录。 | +| `FAILPROOFAI_SDK_STRICT` | 设为 `1` 时，埋点错误将抛出异常而非仅记录日志。 | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | 设为 `1` 时，框架兼容性问题将抛出异常而非仅发出警告后继续运行。 | - **`environment` 中不得包含逗号。** 摄取层会按逗号分割该字段以构建过滤器，标签中含逗号的事件会被跳过，导致整个运行批次无声无息地消失。请写 `prod-eu`，而非 `prod,eu`。 + **`environment` 中不能包含逗号。** 数据摄取服务会以逗号分割该字段来构建过滤器，标签中含有逗号的事件会被直接丢弃，导致整次运行无声无息地消失。请使用 `prod-eu`，而非 `prod,eu`。 - `configure(environment="prod,eu")` 会立即抛出异常，方便您及时发现问题。`AGENTEYE_ENVIRONMENT` 无法抛出异常（因为没有调用方可接收），因此只会发出一次警告并回退至 `dev`。 + `configure(environment="prod,eu")` 会立即抛出异常，方便你及时发现问题。`AGENTEYE_ENVIRONMENT` 无法抛出异常（因为没有调用方），所以它会警告一次并回退到 `dev`。 -事件先在内存中排队，每隔 `flush_interval` 秒由后台线程写入一次，解释器退出时会进行最终一次写入。如果进程被强制终止，尚未写入的事件将会丢失。 +事件先在内存中排队，每隔 `flush_interval` 秒由后台线程写入，解释器退出时执行最终刷写。进程被强制终止时，尚未写入的事件将会丢失。 ## 身份标识 -每个事件都属于某个会话和某个 Agent。**作用域会自动填充两者**，因此通常无需手动传入： +每个事件都归属于一个会话和一个 agent。**作用域会自动填充两者**，因此通常无需手动传入： ```python with failproofai_sdk.session(): @@ -91,30 +97,30 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -显式传入 `session_id` 或 `agent_id` 同样有效，且优先级更高。若两者均未绑定也未传入，调用会抛出 `TypeError`，而不是发送一个会被 Cloud 静默丢弃的事件。 +显式传入 `session_id` 或 `agent_id` 也完全有效，且优先级更高。如果既没有绑定作用域，也没有手动传入，调用将抛出 `TypeError`，而不是发出一个 Cloud 会静默丢弃的事件。 - 身份标识通过上下文变量传递。它会自动跟随 `asyncio` 任务传播，但**不会**跟随新线程——请用 `failproofai_sdk.propagate()` 包装工作线程，否则其事件将处于未关联状态。 + 身份标识基于上下文变量传递，会自动跟随 `asyncio` 任务，但**不会**跟随新线程——请使用 `failproofai_sdk.propagate()` 包装工作线程，否则其事件将无法关联到对应会话。 ## 事件目录 -共 15 个方法，大多数以**配对形式**出现——先调用开启方法，再调用关闭方法，SDK 会自动计算两者之间的时间差。 +共 15 个方法，大多数成**对**出现——调用开始方法，再调用结束方法，SDK 会自动计算两者之间的耗时。 -| | 开启 | 关闭 | +| | 开始 | 结束 | | --- | --- | --- | -| **Agents** | `agent_start` | `agent_end` | +| **Agent** | `agent_start` | `agent_end` | | | `agent_pause` | `agent_resume` | | **模型** | `model_request` | `model_response` | | **工具** | `tool_use` | `tool_result` | -| **Hooks** | `hook_triggered` | `hook_completed` | +| **Hook** | `hook_triggered` | `hook_completed` | | **人工** | `human_wait` | `human_input` | 另有三个独立方法：`error`、`human_pause`、`human_interrupt`。 - + -每个方法还接受 `session_id` 和 `agent_id`，作用域会自动填充。值为 `None` 的字段会被丢弃而非以 JSON `null` 形式发送，所有方法均返回 `None`。 +每个方法同样接受 `session_id` 和 `agent_id` 参数，由作用域自动填充。值为 `None` 的字段会被丢弃，不会以 JSON `null` 形式发送；所有方法均返回 `None`。 | 方法 | 必填 | 可选 | | --- | --- | --- | @@ -137,12 +143,12 @@ with failproofai_sdk.session(): - 若要将一次运行标记为失败，`outcome` 必须为以下值之一：`failed`、`error`、`timeout` 或 `rejected`。其他任何值——包括相近但有误的 `"failure"`——都会被视为成功。 + 要将一次运行标记为失败，`outcome` 必须是以下值之一：`failed`、`error`、`timeout` 或 `rejected`。其他任何值——包括容易写错的 `"failure"`——都会被视为成功。 -## 配对与时长 +## 配对与耗时 -**唯一规则：关闭事件必须与其对应的开启事件使用相同的 ID。** 这是配对的依据，也是 SDK 计算时间差的基础。 +**一条规则：结束事件必须与其对应的开始事件使用相同的 ID。** 这是配对的依据，也是 SDK 计算耗时的方式。 | 配对 | 匹配字段 | | --- | --- | @@ -154,21 +160,21 @@ with failproofai_sdk.session(): **不要自行传入 `duration_ms`。** SDK 会自动测量，手动传入会抛出 `ValueError`。 -唯一的例外是 `model_response`——只有您才知道真实的提供商延迟。请传入整数毫秒值——传入浮点数会抛出异常，因为该列为 32 位整数，否则会导致数据为空。 +唯一的例外是 `model_response`——只有你才知道真实的 provider 延迟。请传入整数毫秒值，浮点数会导致抛出异常，因为该字段是 32 位整数，传入浮点数会导致数据丢失。 -- **ID 仅需在同一类型、同一会话内唯一。** 工具调用和 Hook 可以共用同一个 ID；两个并发会话可以复用相同的 ID 而不会发生冲突。 -- **ID 不限于单个 Agent 的作用域。** 在一个 Agent 下开启、在另一个 Agent 下关闭的配对仍然可以匹配——这在多 Agent 代码中是正常情况。 -- **建议填写 `request_id`，虽非必填。** 若不填，模型事件将按到达顺序进行配对，同一 Agent 内的两个并发调用可能会错误匹配。 -- **跨进程的配对**在 Cloud 中仍可匹配，但 SDK 无法计算时长——因为没有任何进程同时看到了配对的两端。 -- **最多允许 10,000 个开启事件等待对应的关闭事件。** 超出后最旧的开启事件将被丢弃，以防止泄漏无限增长。 +- **ID 只需在同类事件、同一会话内唯一。** 一个工具调用和一个 hook 可以共用同一个 ID；同时运行的两个会话可以复用相同的 ID 而不会发生冲突。 +- **ID 不限定于某个 agent 的作用域。** 在一个 agent 下打开、在另一个 agent 下关闭的配对仍然可以匹配——这在多 agent 代码中是正常情况。 +- **`request_id` 可选，但推荐填写。** 不填时，模型事件按到达顺序配对，同一 agent 内的两个并发调用可能会错误配对。 +- **跨进程的配对**在 Cloud 中仍然可以匹配，但 SDK 无法计算耗时——因为没有任何一个进程同时看到了两半。 +- **最多同时等待 10,000 个待配对的开始事件。** 超出后最旧的会被丢弃，防止内存泄漏无限增长。 ## 自定义字段 -传入的任何额外关键字参数都会随事件一起存储： +额外传入的关键字参数会随事件一起存储： ```python failproofai_sdk.event.tool_use( @@ -177,21 +183,21 @@ failproofai_sdk.event.tool_use( ) ``` -若希望后续可以查询，建议使用 JSON 兼容类型。其他类型——UUID、datetime、`Decimal`、集合、字节、模型对象——均会以字符串形式存储。 +如果希望后续能够查询这些字段，建议使用 JSON 兼容类型。其他类型——UUID、datetime、`Decimal`、set、bytes、模型对象等——将以字符串形式存储。 - **请为自定义字段名添加前缀。** 额外字段最后应用，因此名为 `model`、`tool_name` 或 `outcome` 的字段会静默覆盖对应的标准字段。框架适配器使用 `fw_` 前缀；采用同样的约定可避免任何冲突。 + **为自定义字段名添加前缀。** 额外字段最后应用，因此名为 `model`、`tool_name` 或 `outcome` 的字段会静默覆盖真实字段。框架适配器使用 `fw_` 前缀；采用相同做法可避免任何冲突。 - 这也是为什么拼写错误的可选字段不会报错——它只会成为一个新的自定义字段。如果 Cloud 中某个标准字段缺失，请优先检查拼写。 + 这也是为什么拼写错误的可选字段不会报错——它只会变成一个新的自定义字段。如果 Cloud 中某个标准字段缺失，请先检查拼写。 -以下五个字段名为保留字，传入后会被直接拒绝：`timestamp`、`session_id`、`agent_id`、`type`、`environment`。 +以下五个字段名为保留字，会被直接拒绝：`timestamp`、`session_id`、`agent_id`、`type`、`environment`。 -## 传输与验证 +## 数据投递与验证 - 在 **Observe → Events** 中，先确认 `agent_start` 位于最前，`agent_end` 位于最后。然后进入 **Observe → Sessions**，确认模型、工具、人工、Hook 和错误事件按预期顺序出现。请以会话 ID 作为主要的故障排查线索。 + 在 **Observe → Events** 中，先确认存在 `agent_start` 事件，最后存在 `agent_end` 事件。然后打开 **Observe → Sessions**，确认模型、工具、人工、hook 和错误事件按预期顺序出现。排查问题时以 session ID 作为主要索引。 ```bash @@ -203,14 +209,14 @@ failproofai_sdk.event.tool_use( -如果 Cloud 中没有数据，请检查 `$FAILPROOFAI_HOME/custom-agents/events`，否则检查 `~/.failproofai/custom-agents/events`。JSONL 文件的存在证明 SDK 已成功发出事件；缓冲目录持续增长表明问题出在守护进程配置或数据传输上，而空的缓冲目录则指向埋点或进程生命周期问题。 +如果 Cloud 中没有数据，请检查 `$FAILPROOFAI_HOME/custom-agents/events`，否则检查 `~/.failproofai/custom-agents/events`。JSONL 文件的存在可证明 SDK 已成功发出事件；spool 持续增大说明问题在守护进程配置或数据投递环节；spool 为空则说明问题在埋点或进程生命周期管理上。 - 请仅在守护进程停止时检查缓冲目录。运行期间，守护进程会在数毫秒内收集并删除每个批次，因此目录列表会与收集器产生竞争，显示的事件数量会远少于实际发出的数量。 + 仅在守护进程停止时才检查 spool。守护进程运行期间，它会在毫秒内收集并删除每批数据，因此目录列表会与收集器产生竞争，显示的事件数量将远少于实际发出的数量。 ## 在自定义运行时中防止故障 -使用审计发现和关联追踪记录来定义不安全操作、所需证据以及预期响应。自定义执行集成必须在操作执行前将其暴露出来，将其结构化输入传递给策略引擎，并执行相应的 allow、instruct 或 deny 决策。 +通过审计发现和关联追踪来定义不安全操作、所需证据及预期响应。自定义执行集成必须在操作执行前将其暴露出来，将其结构化输入传递给策略引擎，并执行 allow、instruct 或 deny 决策结果。 -[联系 Failproof AI](mailto:support@befailproof.ai)，我们将帮助您将运行时的模型、工具和生命周期边界映射到策略 Hook，并与您共同验证集成效果。 \ No newline at end of file +[联系 Failproof AI](mailto:support@befailproof.ai)，我们将协助你将运行时的模型、工具和生命周期边界映射到策略 hook，并与你共同验证集成的正确性。 \ No newline at end of file diff --git a/docs/zh/reference/evaluator-sdk.mdx b/docs/zh/reference/evaluator-sdk.mdx index 5b2648c3..99255d45 100644 --- a/docs/zh/reference/evaluator-sdk.mdx +++ b/docs/zh/reference/evaluator-sdk.mdx @@ -1,190 +1,118 @@ --- title: "Evaluator SDK" -description: "构建一个同步或异步为 Failproof AI 会话评分的服务。" +description: "在您自己的基础设施上运行评估 Worker，用于 LLM 裁判以及托管 Python 无法完成的一切任务。" icon: "gauge" --- -评估器接收已完成的 Agent 会话，并返回您关注的质量信号：数值评分、每项评分的说明以及可选的摘要。Failproof AI 将这些结果存储在追踪记录旁，并在不同 Agent 和环境之间进行图表展示。 +Evaluator SDK 在您自己的基础设施上运行评估。您的 Worker 向 Failproof AI 注册评估项，在 Session 完成后认领它们、打分，并通过出站 HTTPS 提交结果——无需任何入站连接。它适用于[托管 Python](/zh/evaluations/write) 无法完成的场景——LLM 裁判、模型调用、第三方包、密钥和网络访问。其结果会与托管评估结果一并显示在[评估页面](/zh/sessions/evaluations)上，并标记为 **customer**。 -## 设置评估器 +它包含在 `failproofai-sdk` 中，位于 `failproofai_sdk.evaluator` 下；导入 Tracing SDK 不会加载它。 - - - 安装 SDK 及运行所需的服务器。 - - ```bash - pip install failproofai-sdk uvicorn - ``` - - - - 创建 `evaluator.py`。本示例检查会话中是否存在失败的工具调用。 - - ```python - import os - from failproofai.evaluator import Evaluator, EvalResponse - - app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) - - @app.config - def config(): - return {"inactivity_timeout_secs": 1800} - - @app.evaluator - def evaluate(req): - tool_errors = sum( - 1 for item in req.events - if item.event_type == "tool_result" and item.payload.get("error") - ) - return EvalResponse( - scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, - reasoning={"tool_reliability": f"{tool_errors} tool errors"}, - ) - ``` - - - - 设置共享令牌，启动评估器，并确认其健康检查端点可正常响应。 - - ```bash - export EVALUATOR_TOKEN= - uvicorn evaluator:app --host 0.0.0.0 --port 8080 - ``` - - 在另一个终端中： - - ```bash - curl http://127.0.0.1:8080/health - ``` - - - -## 将评估器连接到 Failproof AI +```bash +pip install failproofai-sdk +``` -1. 将评估器部署到 Failproof AI Cloud 可访问的 HTTPS URL。 -2. 使用该 URL 配置 `EVALUATOR_ENDPOINT`，并将 `EVALUATOR_TOKEN` 设置为与评估器相同的令牌。对于托管云服务，请联系 [support@befailproof.ai](mailto:support@befailproof.ai) 配置连接。 -3. 运行评估并确认评分结果显示在 Failproof AI 中。 +## 编写评估 - - - 在 **Observe → Sessions** 下打开已完成的会话，如果未自动评估，请选择 **Run evaluation**。在会话的 **Evaluation** 面板中查看状态、评分、推理说明和摘要。 +```python +from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score + +app = Evaluator(name="customer-production", version="2026.08.1") + + +@app.eval( + "tool_efficiency", + version="1.0.0", + labels=["tools", "deterministic"], + when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"), +) +def tool_efficiency(session): + calls = session.events_of_type("tool_use") + distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")} + value = len(distinct) / len(calls) + return EvalResult( + score=Score(value, passed=value >= 0.7), + metrics={"tool_call_count": Metric(len(calls), unit="events")}, + reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls", + ) - 使用 **Observe → Evaluations** 跨 Agent 或环境比较评分。使用 **Observe → Metrics** 查看延迟、成本、Token 及其他数值指标。 - 从单个会话开始，确认评估器为该次运行返回了预期的评分键和有效的推理说明。 +@app.eval( + "answer_relevance", + version="judge-v1", + labels=["llm_judge", "relevance"], + when=lambda session: ConditionResult( + session.count("human_input") > 0 and session.count("model_response") > 0, + "no_exchange", + ), + timeout_seconds=30, +) +async def answer_relevance(session): + question = session.events_of_type("human_input")[-1].payload.get("response") + answer = session.events_of_type("model_response")[-1].payload.get("content") + value, reasoning = await ask_judge(question, answer) # your LLM call: a 0-1 score and why + return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning) + + +if __name__ == "__main__": + app.run_from_env() +``` - ![显示会话详情的视图，在追踪记录旁展示评估评分和推理说明。](/images/dashboard/session-detail.png) +- `@app.eval(key, version=...)` 注册一个评估项。`key` 是其结果的显示名称；每次逻辑变更时更新版本号，每条结果都会保留生成它的版本信息。单个 Worker 最多可持有 100 个评估项。 +- `result_kind` 默认为 `"score"`，除非您另行指定。对于 `"metric"` 或 `"assertion"` 类型的评估，请在 `metrics` 或 `assertions` 中以与 key 相同的名称命名对应条目，该条目即为其结果。 +- `when` 决定一个 Session 是否适用。返回 `ConditionResult(False, "")` 可跳过该 Session，原因会被记录。 +- 评估函数可以是普通函数或 `async` 函数，`timeout_seconds` 限制其执行时间。 +- Payload 键——上面的 `tool_name`、`response` 和 `content`——由您的 Agent 发送的内容决定，请从真实 Session 中读取它们。 - 一旦单个结果看起来正确，即可使用评估控制台比较这些评分随时间以及跨 Agent 或环境的变化趋势。 +## 运行 Worker - ![质量控制台，以图表展示评估器评分随时间的变化。](/images/dashboard/dashboard-quality.png) +在 **Administration → Keys** 下创建一个具有 `evaluations:run` 权限的密钥，将其放入 `FAILPROOFAI_EVALUATOR_TOKEN` 环境变量——请从您的密钥存储中设置，而不是直接在命令中输入——然后启动 Worker： - 健康的图表应使用稳定的评分名称；更改键名会创建独立的数据系列。 - - - ```bash - fp evals --since 1h --score tool_reliability:0..1 - fp evals --since 24h --aggregate - ``` - - +```bash +FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py +``` -对于自托管的云实例，在服务器进程中设置 `EVALUATOR_ENDPOINT` 之前，自动评估功能保持禁用状态。更改评估器环境变量后请重启服务器。 +如果没有 `__main__` 代码块，`python -m failproofai_sdk.evaluator evaluator:app` 效果相同。 -该服务暴露 `GET /health`、`GET /config`、`POST /evaluate`，以及可选的 `GET /evaluate/{job_id}`。对于异步任务，返回 `JobPending` 并注册 `@app.job_lookup`，以便 Failproof AI 进行轮询。 +| 变量 | 默认值 | 用途 | +| --- | --- | --- | +| `FAILPROOFAI_EVALUATOR_URL` | 必填 | Failproof AI 的地址：Cloud 版使用 `https://app.befailproof.ai`。除非指向回环地址，否则必须使用 HTTPS | +| `FAILPROOFAI_EVALUATOR_TOKEN` | 必填 | 具有 `evaluations:run` 权限的密钥 | +| `FAILPROOFAI_EVALUATOR_WORKER_ID` | `-` | 该 Worker 的名称 | +| `FAILPROOFAI_EVALUATOR_CONCURRENCY` | `1` | 该 Worker 同时评分的 Session 数量 | +| `FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS` | `30` | 每次请求 Failproof AI 的超时时间 | +| `FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS` | `60` | Worker 停止时等待进行中任务完成的时间 | +| `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` | `false` | 允许向非回环地址的 URL 发送明文 HTTP——请参阅下方警告 | +| `FAILPROOFAI_EVALUATOR_MODULE` | 无 | 用于 `python -m failproofai_sdk.evaluator` 的 `module:attribute` | -配置令牌后，除健康检查路由外，所有路由都需要 Failproof AI 以 `EVALUATOR_TOKEN` 发送的相同 Bearer 令牌。 + + `FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP` 会以明文传输所有数据。Worker 在每个请求中都会携带 `FAILPROOFAI_EVALUATOR_TOKEN` 作为 `Authorization: Bearer` 请求头，其获取的会话记录即为 Session 本身——因此，链路上的任何人都可以读取两者，而他们读取到的 Token 在您轮换之前都可用于运行评估。请仅在隔离的开发网络中使用此选项。其他所有场景下，URL 必须使用 HTTPS；回环地址无需此标志。 + -## SDK 类型 +## 结果类型 | 类型 | 字段 | | --- | --- | -| `AgentEvent` | `id`, `ts`, `event_type`, `payload` | -| `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | -| `EvalResponse` | `scores`, `reasoning`, `summary` | -| `JobPending` | `job_id`, `next_poll_secs` | -| `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | - -## 装饰器与路由 +| `Score` | `value`（0 到 1）、`passed`、`unit`（默认 `ratio`）、`display_value`、`description` | +| `Metric` | `value`、`unit`、`display_value`、`description` | +| `Assertion` | `passed`、`description` | +| `EvalResult` | `score`、`metrics`、`assertions`、`reasoning`、`summary`、`labels` | +| `ConditionResult` | `applicable`、`reason_code` | -| 装饰器 | 路由 | 是否必需 | -| --- | --- | --- | -| `@app.evaluator` | `POST /evaluate` | 是 | -| `@app.job_lookup` | `GET /evaluate/{job_id}` | 返回 `JobPending` 时 | -| `@app.config` | `GET /config` | 否 | - -SDK 将评估请求体大小限制为 25 MiB。未知请求字段将被忽略，确保服务在事件协议扩展时保持兼容性。 +一个 `EvalResult` 至少包含一个 Score、Metric 或 Assertion，最多 25 个，每个都位于唯一的键下。 -## 返回异步任务 +## Session 对象 -当评估无法在单次请求内完成时，请使用 `JobPending`。任务 ID 对 Failproof AI 是不透明的，您的服务必须保证在结果被收集或服务器超时到期之前，该 ID 始终可被解析。 - -```python -from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending - -app = Evaluator(token="shared-secret") - -@app.evaluator -def start(req: EvalRequest) -> JobPending: - job_id = enqueue(req) - return JobPending(job_id=job_id, next_poll_secs=30) - -@app.job_lookup -def lookup(job_id: str): - result = get_result(job_id) - if result is None: - return JobPending(job_id=job_id, next_poll_secs=30) - return EvalResponse( - scores=result.scores, - reasoning=result.reasoning, - summary=result.summary, - ) -``` +| 字段或方法 | 返回内容 | +| --- | --- | +| `session_id`、`agent_id`、`environment` | Session 的标识信息 | +| `started_at`、`ended_at` | 开始和结束时间 | +| `event_count`、`events` | 完整的有序事件记录 | +| `count(event_type)` | 该类型事件的数量 | +| `events_of_type(event_type)` | 该类型的所有事件，按顺序排列 | -轮询频率按以下优先级确定：`JobPending.next_poll_secs`、`EvaluatorConfig.default_poll_interval_secs`，最后是服务器的 `EVALUATOR_POLLING_INTERVAL_SECS`。值被限制在 1 秒到 1 小时之间。服务器默认的挂钟轮询上限为 1 小时。 +每个事件包含 `id`、`ts`、`event_type` 和 `payload`。 -## 请求与响应字段 +## 旧版 Evaluator -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `EvalRequest.schema_version` | `str` | 当前为 `"1"`。 | -| `session_id`, `agent_id`, `environment` | `str` | 会话标识和环境信息。 | -| `started_at` | `datetime` | 第一个事件的时间戳。 | -| `ended_at` | `datetime \| None` | 会话发出结束事件时存在。 | -| `events` | `list[AgentEvent]` | 完整的有序事件流。 | -| `AgentEvent.id` | `int` | 后端事件行标识符。 | -| `AgentEvent.ts` | `datetime` | 事件时间戳。 | -| `AgentEvent.event_type` | `str` | 事件类型，例如 `tool_use`。 | -| `AgentEvent.payload` | `dict[str, Any]` | 完整的事件负载。 | -| `EvalResponse.scores` | `dict[str, float] \| None` | 在评估中以图表展示的数值维度。 | -| `EvalResponse.reasoning` | `dict[str, str] \| None` | 每项评分的说明；键应与 `scores` 对应。 | -| `EvalResponse.summary` | `str \| None` | 整体评估叙述。 | - -## 服务器运维配置 - -自动评估作用于整个部署范围，当 `EVALUATOR_ENDPOINT` 未设置时保持禁用。 - -| 变量 | 默认值 | 用途 | -| --- | --- | --- | -| `EVALUATOR_ENDPOINT` | 未设置 | 评估器服务的基础 URL。 | -| `EVALUATOR_TOKEN` | 未设置 | 与 `Evaluator(token=...)` 共享的 Bearer 令牌。 | -| `EVALUATOR_WORKERS` | `2` | 并发调度工作进程数。 | -| `EVALUATOR_CLAIM_BATCH` | `4` | 每次调度轮次认领的会话数。 | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | 异步轮询的回退频率。 | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | 单次评估器请求超时时间。 | -| `EVALUATOR_MAX_ATTEMPTS` | `5` | 终止失败前的最大投递尝试次数。 | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | `/config` 的刷新频率。 | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | 异步轮询的最大挂钟时间。 | - -服务器还可以限制哪些组织使用部署级别的全局评估器。请将端点、令牌、重试策略及组织访问控制的变更视为运维配置，更改后需重启或滚动更新服务器。 - -## 安全与运维 - -- 当流量跨越可信网络边界时，请将评估器置于 HTTPS 之后。 -- 配置非空的 Bearer 令牌，并确保两端服务使用完全相同的令牌。 -- 不要在日志中记录令牌或请求负载中的完整敏感提示词。 -- 确保同步处理器具备幂等性；重试可能会重复发送请求。 -- 在生产环境中，将异步任务状态持久化到进程内存之外。 -- 使用稳定的评分键。重命名键会创建新的图表数据系列，而非修改原有系列。 - -SDK 会输出结构化的生命周期日志，例如 `eval received`、`eval responded`、`job lookup`、`config returned`、`auth rejected` 以及处理器异常信息。它不配置日志处理器；请使用宿主应用的日志配置。 \ No newline at end of file +早期的 Evaluator SDK——由 Failproof AI 在 `EVALUATOR_ENDPOINT` 调用的 HTTP 服务，响应 `/evaluate` 并通过 `JobPending` 轮询——已停止支持。请基于此 Worker 构建新的评估器；自托管实例的运营者若仍在使用旧版服务，可在过渡期内继续使用。 \ No newline at end of file diff --git a/docs/zh/reference/failproof-cli.mdx b/docs/zh/reference/failproof-cli.mdx index 20044747..b46edd10 100644 --- a/docs/zh/reference/failproof-cli.mdx +++ b/docs/zh/reference/failproof-cli.mdx @@ -1,86 +1,104 @@ --- title: "Failproof AI CLI" -description: "安装钩子、管理本地策略、连接云端并操作本地守护进程。" +description: "安装 hooks、管理本地策略、连接 Cloud 并操作本地守护进程。" icon: "terminal" --- -使用 `npm install -g failproofai` 安装本地 CLI。不带任何参数运行将打开本地策略仪表板。 +使用 `npm install -g failproofai` 安装本地 CLI。不带参数运行即可打开本地策略仪表盘。 -此软件包需要 Node.js 20.9 或更高版本。开发和源码安装支持 Bun 1.3 或更高版本。`failproofai configure` 和 `failproofai setup` 是 `failproofai config` 的别名；`failproofai p` 是 `failproofai policies` 的别名。 +该软件包需要 Node.js 20.9 或更高版本。开发和源码安装支持 Bun 1.3 或更高版本。`failproofai configure` 和 `failproofai setup` 是 `failproofai config` 的别名。`failproofai policy`、`failproofai pack` 和 `failproofai p` 均为 `failproofai policies` 的不同写法——packs 和单个策略曾是三个命令对应一个概念，现已合并为一个。旧写法仍然有效，但有两个例外：`pack list ` 现在是 `policies show `，`pack build` 现在是 `publish`。 ## 配置一台机器 +安装 CLI，然后将机器密钥读入 shell。`read -s` 以不回显的提示符接收输入，因此密钥不会出现在命令中： + ```bash npm install -g failproofai -failproofai config \ - --connect https://app.befailproof.ai \ - --token \ - --machine-label checkout-prod-01 -failproofai policies --install +read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN +``` + +然后配置机器并选择要强制执行的内容： + +```bash +failproofai config +failproofai policies add FailproofAI/policies failproofai config --status ``` -不带参数运行 `failproofai` 可打开本地策略仪表板。 +`failproofai config` 涵盖全部设置流程：它安装 `failproofaid` 服务（以 root 身份通过 `sudo -n` 执行一次——从不出现交互式密码提示），将 hooks 连接到所有找到的 agent CLI，并在密钥可用时连接到 Cloud。在没有终端的环境下（CI、容器、由 agent 驱动），它直接应用配置而非询问，如果任何被要求执行的操作未能完成则以退出码 1 退出。 + +它**不会**选择任何策略。这是第二条命令的职责，没有它，刚配置好的机器除了始终开启的守护之外不会强制执行任何内容。 + +优先使用环境变量而非 `--token`：命令行参数可以被该机器上的所有用户通过 `ps` 读取。这是该变量唯一能防范的情况——无论是通过 `export` 还是其他方式键入命令的密钥，都会进入 shell 历史记录，这也是为什么要用上文的 `read -s` 来读取它。在 CI 中，请从密钥存储中设置它，并关闭 shell 追踪（`set -x`），否则追踪日志会将其打印出来。 + + + `--connect ` 用于注册一台**已配置好**的机器。它在注册成功后立即返回——不安装守护进程，也不连接任何 hooks。如果机器尚未配置，请使用普通的 `failproofai config`（或 `failproofai config --token `），否则机器将显示为已连接，但实际上不会收集或强制执行任何内容。 + + +不带参数运行 `failproofai` 可打开本地策略仪表盘。 -| 命令 | 功能说明 | +| 命令 | 说明 | | --- | --- | -| `failproofai config` | 运行交互式机器配置 | -| `failproofai config --connect --token ` | 连接云端数据采集和策略下发 | -| `failproofai config --status` | 显示连接、守护进程、下发及暂停状态 | -| `failproofai policies` | 列出内置、自定义、约定、扩展包及云端托管策略 | -| `failproofai policies --install` | 安装钩子并启用策略 | -| `failproofai policy add ` | 启用单条策略——内置策略或已安装扩展包中的 `:` | -| `failproofai policy remove ` | 禁用单条策略，命名规则相同 | -| `failproofai policies --uninstall` | 禁用策略或移除挂载钩子 | -| `failproofai pack list` | 列出已安装的策略包及其包含的所有策略 | -| `failproofai pack add ` | 从 GitHub Release 安装策略包；不指定标签则使用最新版本并固定 | -| `failproofai pack add --bundled` | 从本软件包安装内置策略包，无需网络 | -| `failproofai pack build ` | 为自定义策略包构建三个发布产物 | -| `failproofai pack remove ` | 停用已安装的策略包 | -| `failproofai audit` | 扫描本地 Agent 历史记录并打开本地审计视图 | -| `failproofai audit --schedule [days] --email
` | 定期安排本地扫描并将结果发送至邮件地址 | -| `failproofai audit --status` | 显示报告邮箱、周期及下次计划扫描时间 | -| `failproofai audit --no-schedule` | 停止定期扫描但不删除审计历史记录 | +| `failproofai config` | 配置机器：agents、守护进程，以及在密钥存在时连接 Cloud | +| `failproofai config --token ` | 一步完成配置和连接，无需任何交互 | +| `failproofai config --connect ` | 注册一台**已**配置好的机器——不含守护进程和 hooks | +| `failproofai config --status` | 显示连接、守护进程、投递及暂停状态 | +| `failproofai policies` | 列出内置、自定义、约定、pack 及 Cloud 管理的策略 | +| `failproofai policies --install` | 将 hooks 连接到 agent CLI，本身不启用任何策略 | +| `failproofai policies add ` | 启用一个策略——内置策略，或来自已安装 pack 的 `:` | +| `failproofai policies remove ` | 禁用一个策略，命名规则相同 | +| `failproofai policies --uninstall` | 禁用策略或移除 harness hooks | +| `failproofai policies show /` | 在安装前查看 pack 携带的内容，从其 manifest 读取 | +| `failproofai policies show / --releases` | 查看已发布的所有版本及当前安装的版本 | +| `failproofai policies add ` | 从 GitHub release 安装策略 pack；不指定 tag 则取最新版并固定 | +| `failproofai publish` | 将自己的策略发布为 pack；`--init` 生成初始文件 | +| `failproofai policies remove ` | 卸载一个 pack | +| `failproofai audit` | 扫描本地 agent 历史并打开本地审计视图 | +| `failproofai audit --schedule [days] --email
` | 安排定期本地扫描并将发现结果发送至邮件 | +| `failproofai audit --status` | 显示报告地址、间隔及下次计划扫描时间 | +| `failproofai audit --no-schedule` | 停止定期扫描，但不删除审计历史 | | `failproofai harness list` | 列出额外的捕获路径 | -| `failproofai flush --wait` | 立即投递当前事件队列 | -| `failproofai backfill --since 30d` | 重新读取此前已处理的历史记录 | +| `failproofai flush --wait` | 投递当前事件队列 | +| `failproofai backfill --since 30d` | 重新读取之前已处理的历史记录 | | `failproofai config --pause [duration]` | 暂停当前本地会话，默认 30 分钟，最长 8 小时 | -| `failproofai config --resume` | 恢复已暂停的本地会话；加 `--all` 可清除所有暂停 | -| `failproofai update` | 完成包迁移并更新守护进程 | -| `failproofai migrate --dry-run` | 预览或执行待处理的 home 目录布局迁移 | -| `failproofai uninstall` | 在移除软件包前卸载钩子和守护进程 | +| `failproofai config --resume` | 恢复一个已暂停的本地会话；加 `--all` 可清除所有暂停 | +| `failproofai update` | 完成软件包迁移并更新守护进程 | +| `failproofai migrate --dry-run` | 预览或执行待处理的 home 布局迁移 | +| `failproofai uninstall` | 在移除软件包前删除 hooks 和守护进程 | | `failproofai --version` | 打印已安装的软件包版本 | -| `failproofai --help` | 显示命令及全局用法 | +| `failproofai --help` | 显示命令和全局用法 | ## 配置标志 -| 标志 | 用途 | +| 标志 | 说明 | | --- | --- | -| `--connect --token ` | 非交互式连接 | +| `--token ` | 非交互式配置和连接；也可从 `FAILPROOFAI_CLOUD_TOKEN` 读取 | +| `--url ` | 连接到 `app.befailproof.ai` 以外的地址；也可从 `FAILPROOFAI_CLOUD_URL` 读取 | +| `--connect ` | 仅注册，用于已配置好的机器，跳过守护进程和所有 hooks | | `--machine-id ` | 设置稳定的机器 ID | -| `--machine-label ` | 设置或修改仪表板标签 | -| `--no-transcripts` | 仅发送决策结果，不包含会话内容 | -| `--disconnect` | 停止云端策略拉取和事件投递 | +| `--machine-label ` | 重命名一台**已连接**的机器。单独使用时不会运行配置，请在 `failproofai config` 之后使用，而非配置过程中 | +| `--no-transcripts` | 仅发送决策，不包含转录内容 | +| `--disconnect` | 停止 Cloud 策略拉取和事件投递 | | `--status` | 显示当前机器状态 | -| `--pause [duration]` | 暂停当前目录中最新的会话；接受秒、分钟或小时为单位，默认 30 分钟 | +| `--pause [duration]` | 暂停当前目录中最新的会话；接受秒、分钟或小时，默认 30 分钟 | | `--resume` | 提前结束匹配的暂停 | -| `--session ` | 为暂停或恢复指定明确的会话 | -| `--all` | 配合 `--resume` 使用，结束所有活跃的暂停 | +| `--session ` | 指定暂停或恢复的目标会话 | +| `--all` | 与 `--resume` 配合使用，结束所有活跃的暂停 | -本地暂停会针对单个会话暂停内置、自定义、约定及扩展包策略。暂停始终会过期，且不会禁用云端托管策略。`block-failproofai-commands`——始终开启且本身无法被禁用或暂停——可防止被监控的 Agent 自行利用此逃脱通道。 +本地暂停会为一个会话挂起内置、自定义、约定和 pack 策略。暂停总会到期，且不会禁用 Cloud 管理的策略。`block-failproofai-commands`——始终开启且本身无法被禁用或暂停——可防止被检测的 agent 自行使用此逃脱机制。 ## 策略标志 -| 标志 | 用途 | +| 标志 | 说明 | | --- | --- | -| `--install`, `-i` | 启用策略并安装挂载钩子 | -| `--uninstall`, `-u` | 禁用策略或移除钩子 | -| `--cli ` | 指定一个或多个支持的挂载目标 | -| `--scope user\|project\|local\|all` | 选择配置作用域；`all` 用于卸载 | +| `--install`, `-i` | 安装 harness hooks。其后的名称将启用对应策略；若无名称，则不更改任何策略 | +| `--uninstall`, `-u` | 禁用策略或移除 hooks | +| `--cli ` | 指定一个或多个支持的 harnesses | +| `--scope user\|project\|local\|all` | 选择配置范围；`all` 用于卸载 | | `--beta` | 包含测试版策略 | | `--custom`, `-c ` | 验证并加载自定义策略文件；可重复使用 | -## 数据投递与维护标志 +## 投递与维护标志 | 命令 | 标志 | | --- | --- | @@ -90,9 +108,9 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` 应在执行 `npm install -g failproofai@latest` 后运行；它会执行 home 目录布局迁移、安装匹配的守护进程二进制文件并重启服务。`--no-daemon` 仅执行布局迁移。 +`failproofai update` 应在 `npm install -g failproofai@latest` 之后运行；它执行 home 布局迁移、安装匹配的守护进程二进制文件并重启服务。`--no-daemon` 仅执行布局迁移。 -## 挂载路径 +## Harness 路径 ```text failproofai harness list [harness] @@ -100,11 +118,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -支持的挂载目标名称包括 `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity` 和 `goose`。 +支持的 harness 名称包括 `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity` 和 `goose`。 -当两个根目录包含同一项目的副本时，标签用于区分派生的 Agent ID 命名空间。系统会拒绝重叠的根目录和重复标签，以防止重复采集或游标损坏。额外路径配置无需重启守护进程即可重新加载。 +当两个根目录包含同一项目的副本时，标签会为派生的 agent ID 提供命名空间。重叠的根目录和重复的标签会被拒绝，以防止重复收集或游标损坏。额外路径配置无需重启守护进程即可重新加载。 -容器环境可使用以逗号分隔的变量 `FAILPROOFAI__EXTRA_PATHS` 替代文件配置的额外路径，例如： +容器环境可以用逗号分隔的变量 `FAILPROOFAI__EXTRA_PATHS` 替换文件配置的额外路径，例如： ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -112,28 +130,30 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## 环境变量 -持久化机器行为请使用配置文件。环境变量最适合用于容器、测试和单进程场景。 +使用配置文件来设置持久化的机器行为。环境变量最适用于容器、测试和单个进程。 -| 变量 | 用途 | +| 变量 | 说明 | | --- | --- | -| `FAILPROOFAI_HOME` | 重新定位完整的 `~/.failproofai` 目录布局 | +| `FAILPROOFAI_CLOUD_TOKEN` | Cloud 密钥，代替 `--token`。推荐使用此方式：命令行参数可被该机器上所有用户通过 `ps` 读取。使用 `read -s` 或从 CI 密钥存储中设置，切勿直接键入命令，否则无论如何都会进入 shell 历史记录 | +| `FAILPROOFAI_CLOUD_URL` | Cloud URL，代替 `--url`。与守护进程读取的变量相同 | +| `FAILPROOFAI_HOME` | 重新定位完整的 `~/.failproofai` 布局 | | `FAILPROOFAI_LOG_LEVEL` | 设置本地日志详细级别 | -| `FAILPROOFAI_HOOK_LOG_FILE` | 将钩子诊断信息写入指定文件 | +| `FAILPROOFAI_HOOK_LOG_FILE` | 将 hook 诊断信息写入指定文件 | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | 为当前进程禁用匿名遥测 | -| `FAILPROOFAI_NO_FIRST_RUN=1` | 跳过交互式首次运行配置 | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | 跳过配置后的本地自动审计 | +| `FAILPROOFAI_NO_FIRST_RUN=1` | 跳过交互式首次运行设置 | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | 跳过配置后的本地审计 | | `FAILPROOFAI_LLM_BASE_URL` | 覆盖 LLM 策略使用的 OpenAI 兼容端点 | | `FAILPROOFAI_LLM_API_KEY` | 提供 LLM 策略使用的 API 密钥 | | `FAILPROOFAI_LLM_MODEL` | 选择 LLM 策略使用的模型 | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | 限制自定义策略模块的加载超时时间 | -| `FAILPROOFAI_NO_DOWNLOAD=1` | 拒绝获取策略包和守护进程二进制文件；已安装的内容继续生效 | -| `FAILPROOFAI_PACK_BASE_URL` | 从镜像站点而非 `github.com` 获取策略包 | -| `FAILPROOFAI__EXTRA_PATHS` | 替换指定挂载目标已配置的额外捕获路径 | -| `NO_COLOR` | 禁用终端彩色输出 | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | 限制自定义策略模块的加载时间 | +| `FAILPROOFAI_NO_DOWNLOAD=1` | 拒绝获取 packs 和守护进程二进制文件；已安装的内容继续强制执行 | +| `FAILPROOFAI_PACK_BASE_URL` | 从镜像而非 `github.com` 获取 packs | +| `FAILPROOFAI__EXTRA_PATHS` | 替换某个 harness 的已配置额外捕获路径 | +| `NO_COLOR` | 禁用彩色终端输出 | -Agent 专属的 home 变量（如 `CLAUDE_PROJECTS_PATH`、`CURSOR_HOME`、`HERMES_HOME` 和 `OPENCLAW_HOME`）会覆盖 Failproof AI 发现该挂载目标本地会话的路径。 +特定 agent 的 home 变量，如 `CLAUDE_PROJECTS_PATH`、`CURSOR_HOME`、`HERMES_HOME` 和 `OPENCLAW_HOME`，可覆盖 Failproof AI 为该 harness 发现本地会话的位置。 -## 安全地暂停或移除机器 +## 安全地暂停或移除一台机器 ```bash failproofai config --pause @@ -141,9 +161,9 @@ failproofai config --status failproofai config --resume ``` -本地会话暂停不会禁用云端托管策略。若问题出在发布流程本身，请通过云端强制执行工作流恢复云端部署。 +本地会话暂停不会禁用 Cloud 管理的策略。当推出本身存在问题时，请通过 Cloud 强制执行工作流恢复 Cloud 部署。 -移除 npm 软件包之前，请先卸载已安装的钩子和守护进程： +在移除 npm 软件包之前，请先移除已安装的 hooks 和守护进程： ```bash failproofai uninstall --dry-run @@ -151,8 +171,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -运行 `failproofai --help` 可查看特定版本的详细说明。 +运行 `failproofai --help` 可查看特定版本的详细信息。 - 请在执行 `npm rm -g failproofai` 之前先运行 `failproofai uninstall`；npm 不会自动移除已安装的 Agent 钩子或守护进程服务。 + 请在 `npm rm -g failproofai` 之前运行 `failproofai uninstall`；npm 不会移除已安装的 agent hooks 或守护进程服务。 \ No newline at end of file diff --git a/docs/zh/reference/harnesses.mdx b/docs/zh/reference/harnesses.mdx index 2a9519ac..96ca6858 100644 --- a/docs/zh/reference/harnesses.mdx +++ b/docs/zh/reference/harnesses.mdx @@ -1,80 +1,86 @@ --- -title: "Agent harnesses" -description: "在所有 12 种受支持的 agent harness 中捕获会话并执行策略。" +title: "Agent Harness" +description: "跨所有 12 个支持的 agent harness 捕获会话并执行策略。" icon: "plug-zap" --- -Harness 是 agent 实际运行的环境。Failproof AI 支持十二种 harness，分为两类： +Harness 是你的 agent 实际运行的环境。Failproof AI 支持其中十二种，分为两类： -- **编码 CLI**（10 种）—— Claude Code、Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi、Factory Droid、Devin CLI、Antigravity CLI、Goose +- **编程 CLI**（10 种）—— Claude Code、Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi、Factory Droid、Devin CLI、Antigravity CLI、Goose - **对话与助手网关**（2 种）—— Hermes（Slack、Telegram、cron）、OpenClaw（自托管助手） -无论 agent 在哪个 harness 中运行，相同的策略和相同的会话历史均适用。一个适配器层会在任何策略执行之前，将每个 harness 的原生事件名称、工具名称和工具输入字段映射到 29 个规范事件。 +无论 agent 运行在哪个 harness 中，同一套策略和同一份会话历史均适用。一个适配器层会在任何策略执行之前，将每个 harness 的原生事件名称、工具名称和工具输入字段映射到 29 个标准化事件上。 -对于不在上述十二种 harness 中运行的 agent，可以直接通过 [Python SDK](/zh/reference/custom-agents) 进行插桩。这是一种不同的契约，值得明确说明：SDK 提供追踪、会话、评估和审计功能，**但它本身不执行策略。** 若要在不安全操作执行之前将其阻止，需要在运行时的工具边界处设置执行钩子；请[联系我们](mailto:support@befailproof.ai)，我们将为您进行映射。 +如果 agent 不在上述十二种 harness 中运行，则需直接使用 [Python SDK](/zh/reference/custom-agents) 进行插桩。这是一份不同的契约，有必要明确说明：SDK 提供追踪、会话、评估和审计功能——**它本身并不执行策略。** 在不安全操作执行之前将其拦截，需要在你的运行时工具边界处设置执行钩子；请[联系我们](mailto:support@befailproof.ai)，我们将为你完成映射。 -| Harness | 支持的钩子范围 | +| Harness | 支持的钩子作用域 | | --- | --- | | Claude Code | User、project、local | | Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi | User、project | | Factory Droid、Devin CLI、Antigravity CLI、Goose | User、project | | Hermes、OpenClaw | User | -每个集成在策略执行前会对其原生钩子事件名称、工具名称和工具输入字段进行规范化。策略只能作用于 harness 所暴露的事件；请在实际部署的 harness 及其版本上测试回合结束和指令行为。 +每个集成会在策略执行之前对其原生钩子事件名称、工具名称和工具输入字段进行标准化处理。策略只能对该 harness 所暴露的事件起作用；请在你实际部署的 harness 及其版本上测试轮次结束和指令行为。 ## 执行能力 -"阻止"意味着当前适配器返回的裁决由指定 harness 消费。工具执行后的阻止可能会替换展示给模型的结果，但无法撤销已发生的工具副作用。 +"拦截"是指当前适配器返回的裁决由指定 harness 消费。工具执行后的拦截可能会替换模型所看到的结果，但无法撤销已经发生的工具副作用。 -| Harness | 已验证的阻止事件 | 仅观测或非阻止说明 | +| Harness | 已验证的拦截事件 | 仅观测或非拦截说明 | | --- | --- | --- | -| Claude Code | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PreCompact` 及若干任务/配置事件 | `PostToolUse`、会话生命周期、通知及失败后事件仅供观测。 | -| Codex | `PreToolUse`、`PermissionRequest`、`UserPromptSubmit`、`Stop`、`SubagentStop`、`PostToolUse` | 工具执行后阻止会在执行后替换结果；会话启动和压缩事件在当前适配器中仅供观测。 | -| GitHub Copilot CLI | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PostToolUse` | 工具执行后阻止会在执行后替换结果；会话和通知事件仅供观测。 | +| Claude Code | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PreCompact` 以及若干任务/配置事件 | `PostToolUse`、会话生命周期、通知及失败后事件仅供观测。 | +| Codex | `PreToolUse`、`PermissionRequest`、`UserPromptSubmit`、`Stop`、`SubagentStop`、`PostToolUse` | 工具执行后的拦截会在执行完成后替换结果；会话启动和压缩事件在当前适配器中仅供观测。 | +| GitHub Copilot CLI | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PostToolUse` | 工具执行后的拦截会在执行完成后替换结果；会话和通知事件仅供观测。 | | Cursor | `PreToolUse`、`UserPromptSubmit`、`Stop` | `PostToolUse` 和会话事件仅供观测。 | -| OpenCode | `PreToolUse` | 工具执行后和生命周期事件仅供观测；当前的 stop 处理是对后续回合的引导，而非已验证的门控。 | -| Pi | `PreToolUse`、`UserPromptSubmit` | 工具执行后和生命周期事件仅供观测；stop 引导适用于后续回合。 | -| Hermes | `PreToolUse` | 工具执行后、会话和子 agent stop 的裁决不作为门控。 | -| OpenClaw | `PreToolUse`、`UserPromptSubmit`、`Stop` | 工具执行后、会话、子 agent stop 和压缩事件仅供观测。 | -| Factory Droid | `PreToolUse`、`UserPromptSubmit`、`Stop`、`PreCompact` | 工具执行后和子 agent stop 裁决仅供观测。 | -| Devin CLI | `PreToolUse`、`UserPromptSubmit`、`Stop`、条件性 `PermissionRequest` | 权限钩子并非在所有权限模式下都会运行；工具执行后和会话事件仅供观测。 | -| Antigravity CLI | `PreToolUse`、`Stop` | 用户提示和工具执行后裁决仅供观测；提示指令仍可被注入。 | -| Goose | `PreToolUse` | 用户提示、工具执行后和会话事件仅供观测。上游存在原生阻止 stop 钩子，但当前适配器未安装。 | +| OpenCode | `PreToolUse` | 工具后和生命周期事件仅供观测；当前的停止处理是对后续轮次的引导，而非已验证的拦截门。 | +| Pi | `PreToolUse`、`UserPromptSubmit` | 工具后和生命周期事件仅供观测；停止引导作用于后续轮次。 | +| Hermes | `PreToolUse` | 工具后、会话和子 agent 停止的裁决不构成拦截门。 | +| OpenClaw | `PreToolUse`、`UserPromptSubmit`、`Stop` | 工具后、会话、子 agent 停止和压缩事件仅供观测。 | +| Factory Droid | `PreToolUse`、`UserPromptSubmit`、`Stop`、`PreCompact` | 工具后和子 agent 停止的裁决仅供观测。 | +| Devin CLI | `PreToolUse`、`UserPromptSubmit`、`Stop`、条件性 `PermissionRequest` | 权限钩子并非在所有权限模式下都会运行；工具后和会话事件仅供观测。 | +| Antigravity CLI | `PreToolUse`、`Stop` | 用户提示和工具后的裁决仅供观测；仍可注入提示指令。 | +| Goose | `PreToolUse` | 用户提示、工具后和会话事件仅供观测。上游存在原生拦截停止钩子，但当前适配器未安装。 | -功能因版本而异。升级 agent CLI 后请重新测试，尤其是当策略依赖提示、stop、权限或工具执行后行为，而非通用的工具执行前门控时。 +各项能力对版本敏感。升级 agent CLI 后请重新测试，尤其是当策略依赖提示、停止、权限或工具后行为而非通用的工具前拦截门时。 -## 安装捕获与策略钩子 +## 安装捕获和策略钩子 - 1. 打开 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥，并以机器或环境命名。 - 2. 在目标机器上，使用显示的密钥连接本地 CLI 并安装 harness 钩子。 - 3. 启动一个新的 agent 会话，然后在 **Observe → Events** 下确认其钩子和会话事件。 - 4. 打开相同时间窗口的 **Observe → policy**，确认策略决策已归因到该机器。 + 1. 打开**管理 → 密钥**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥，并以机器或环境命名。 + 2. 在目标机器上，使用显示的密钥连接本地 CLI，并安装 harness 钩子。 + 3. 启动一个新的 agent 会话，然后在**观测 → 事件**下确认其钩子和会话事件。 + 4. 打开相同时间窗口的**观测 → 策略**，确认某条策略决策已归属到该机器。 - 连接从机器密钥开始。在复制其密钥之前，请确认它同时包含数据采集和策略下发权限。 + 连接从机器密钥开始。在复制其密钥之前，请确认它包含摄取和策略分发两项权限。 - ![用于授予事件采集和策略下发权限的新 API 密钥抽屉。](/images/dashboard/key-create.png) + ![用于授予事件摄取和策略分发权限的新 API 密钥抽屉。](/images/dashboard/key-create.png) - 安装钩子后，事件流应显示来自所连接机器和环境的新事件。 + 安装钩子后，事件流应显示来自你所连接的机器和环境的新事件。 - ![用于确认新安装的 harness 正在上报的实时事件流。](/images/dashboard/events-stream.png) + ![用于确认新安装的 harness 正在上报数据的实时事件流。](/images/dashboard/events-stream.png) - 最后，验证策略决策是否归因到同一台机器。这可以确认 harness 在上报追踪事件的同时，也在上报策略活动。 + 最后，验证策略决策已归属到同一台机器。这可以确认 harness 不仅在上报追踪事件，也在上报策略活动。 ![用于验证新连接 harness 策略决策的策略页面。](/images/dashboard/policy-observe.png) - 为所有检测到的 harness 安装钩子： + 将机器密钥读入 shell。`read -s` 通过不回显的提示接收输入，因此它不会出现在命令或 shell 历史记录中： ```bash - failproofai config \ - --connect https://app.befailproof.ai \ - --token - failproofai policies --install + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - 或指定 harness 名称和配置范围： + 然后配置机器——这将为所有检测到的 harness 连接钩子、安装守护进程并连接到 Cloud： + + ```bash + failproofai config + failproofai policies add FailproofAI/policies + ``` + + 配置本身不会启用任何策略，第二条命令正是为此而设。 + + 或者指定具体的 harness 和配置作用域： ```bash failproofai policies --install \ @@ -82,7 +88,7 @@ Harness 是 agent 实际运行的环境。Failproof AI 支持十二种 harness --scope user ``` - Project 范围将钩子配置与代码仓库绑定。User 范围覆盖跨仓库的工作。Claude Code 还支持 local 范围；支持情况因 harness 而异，CLI 会拒绝不受支持的组合。 + Project 作用域将钩子配置保留在仓库中。User 作用域覆盖跨仓库的工作。Claude Code 还支持 local 作用域；支持情况因 harness 而异，CLI 会拒绝不支持的组合。 验证机器及其事件： @@ -98,9 +104,9 @@ Harness 是 agent 实际运行的环境。Failproof AI 支持十二种 harness - 额外路径在机器上注册，而非在云端。添加路径后，打开 **Observe → Sessions**，筛选到该机器的环境，并确认来自新路径的会话已显示。打开一个会话，在将其用于审计之前，检查 agent、harness 和事件时间戳。 + 额外路径注册在机器上，而非 Cloud 中。添加后，打开**观测 → 会话**，按机器所在环境过滤，并确认来自新路径的会话已出现。打开一个会话，在将其用于审计之前检查 agent、harness 和事件时间戳。 - ![经过筛选的会话列表，显示从附加捕获路径接收数据的环境。](/images/dashboard/sessions-list.png) + ![过滤到接收附加捕获路径数据的环境的会话列表。](/images/dashboard/sessions-list.png) 添加带有可选标签的路径，然后查看已配置的路径： @@ -112,10 +118,10 @@ Harness 是 agent 实际运行的环境。Failproof AI 支持十二种 harness failproofai backfill --since 7d ``` - 使用 `failproofai harness remove-path claude checkout` 删除路径。 + 使用 `failproofai harness remove-path claude checkout` 移除路径。 - 安装后运行一个新会话。在扩大部署范围之前，请同时验证实时事件流和实际的策略决策。 + 安装后运行一个新会话。在扩大推广范围之前，先验证实时事件流和实际的策略决策均正常工作。 \ No newline at end of file diff --git a/docs/zh/reference/overview.mdx b/docs/zh/reference/overview.mdx index 9fd88fba..bb683d7e 100644 --- a/docs/zh/reference/overview.mdx +++ b/docs/zh/reference/overview.mdx @@ -1,80 +1,83 @@ --- title: "集成与参考" -description: "连接受支持的 Agent 运行框架、SDK、CLI 和 HTTP API。" +description: "连接支持的 Agent 运行框架、SDK、CLI 及 HTTP API。" icon: "braces" --- -选择最接近您 Agent 当前运行环境的集成方式。 +选择最接近您当前 Agent 运行环境的集成方式。 - 为受支持的编码和自主 Agent CLI 安装钩子。 + 为受支持的编码和自主 Agent CLI 安装 Hook。 接入 LangGraph、CrewAI、LlamaIndex、Pydantic AI 或自定义 Agent。 - 配置、事件目录、关联规则及数据传输。 + 配置说明、事件目录、关联规则及数据传输。 - 查看本地项目、会话、策略活动及离线审计。 + 查看本地项目、会话、策略活动及离线审计记录。 - 配置本地采集、钩子、策略、审计、数据传输及机器状态。 + 配置本地采集、Hook、策略、审计、数据传输及机器状态。 查询和管理云端会话、审计、问题、告警、密钥、用户及设置。 - 使用 FastAPI 服务对已完成或非活跃会话进行评分。 + 使用 FastAPI 服务对完整或非活跃会话进行评分。 - 编写并测试特定工作流的 allow、instruct 和 deny 决策。 + 编写并测试面向特定工作流的 allow、instruct 和 deny 决策。 在客户自管的 Kubernetes 集群上部署云端控制平面。 -自动生成的 [HTTP API 参考](/zh/reference/http-api) 涵盖公开的 `/v1` 接口。手动编写的页面则说明跨多个端点的工作流，或使用公开接口之外的管理界面的场景。 +自动生成的 [HTTP API 参考](/zh/reference/http-api) 覆盖公开的 `/v1` 接口。手动编写的页面则说明跨多个端点的工作流，或涉及公开接口之外的管理界面。 ## 连接 Agent 并验证数据 - 1. 打开 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥，并复制该密钥。 - 2. 根据上方对应页面配置集成。 - 3. 打开 **Observe → Events** 确认事件已成功接收，然后打开 **Observe → Sessions** 确认事件已组合成完整的运行记录。 - 4. 按集成环境筛选，并检查某个会话中审计所需的模型、工具、错误和策略字段。 + 1. 打开 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥，并复制密钥值。 + 2. 参照上方对应页面配置集成。 + 3. 打开 **Observe → Events** 确认事件正常到达，然后打开 **Observe → Sessions** 确认事件已组合成完整的运行记录。 + 4. 按集成所在环境进行筛选，并检查一个会话，确认其中包含审计所需的模型、工具、错误及策略字段。 - 从密钥创建抽屉开始操作。所选权限决定了该机器能否发送事件和接收云端托管策略。 + 从密钥抽屉开始操作。所选授权决定了该机器是否能够发送事件和接收云端管理的策略。 - ![用于授予事件采集和策略下发权限的新 API 密钥创建抽屉。](/images/dashboard/key-create.png) + ![用于授予事件摄取和策略下发权限的新 API 密钥抽屉。](/images/dashboard/key-create.png) - 连接集成后，使用会话列表确认其事件正在被归组为预期环境中的完整运行记录。 + 连接集成后，使用会话列表确认其事件正在被正确分组为完整运行记录，并出现在预期的环境中。 - ![用于验证新连接的集成是否正在上报完整 Agent 运行记录的会话列表。](/images/dashboard/sessions-list.png) + ![用于验证新连接集成是否正常上报完整 Agent 运行记录的会话列表。](/images/dashboard/sessions-list.png) - 在确认集成完成之前，请打开其中一个会话；追踪记录应包含审计所需的模型、工具、错误和策略信息。 + 在确认集成完成之前，请打开其中一个会话进行检查；追踪记录中应包含审计所需的模型、工具、错误及策略信息。 - 创建机器密钥，连接 Failproof 守护进程，并验证第一个会话。 + 创建一个机器密钥，然后将其输出的密钥值读入 Shell。使用 `read -s` 在不回显的提示符下输入，确保密钥不会出现在命令行或 Shell 历史记录中： ```bash fp keys create agent-production \ --add events:add \ --add policies:pull + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + 连接 Failproof 守护进程并验证首个会话： - failproofai config \ - --connect https://app.befailproof.ai \ - --token + ```bash + failproofai config failproofai flush --wait fp sessions --since 1h --env production fp events --since 1h --env production --limit 20 ``` - 当其他工具需要使用输出结果时，请使用 `fp --json sessions ...`。`--json`、`--org`、`--base-url` 等全局标志必须放在命令之前。 + 当需要将结果传递给其他工具时，请使用 `fp --json sessions ...`。`--json`、`--org`、`--base-url` 等全局参数必须放在子命令之前。 本地命令请参阅 [Failproof AI CLI 参考](/zh/reference/failproof-cli)，`fp` 命令请参阅 [Failproof Cloud CLI 参考](/zh/reference/cloud-cli#cli-commands)。 diff --git a/docs/zh/reference/policy-sdk.mdx b/docs/zh/reference/policy-sdk.mdx index b3a866fd..871e654d 100644 --- a/docs/zh/reference/policy-sdk.mdx +++ b/docs/zh/reference/policy-sdk.mdx @@ -1,35 +1,35 @@ --- title: "自定义策略" -description: "为 Agent 特有的故障编写、测试和部署 JavaScript 或 TypeScript 策略。" +description: "为你的 Agent 中特定的故障场景编写、测试并部署 JavaScript 或 TypeScript 策略。" icon: "shield-plus" --- -自定义策略将追踪记录或审计中发现的故障模式转化为 Agent 运行时的决策。策略可以允许某个操作、向 Agent 提供指导，或在操作再次引发问题之前予以拒绝。 +自定义策略能将你在追踪记录或审计中发现的故障模式，转化为 Agent 工作时实时执行的决策。策略可以允许某个操作、向 Agent 提供指导，或在操作引发新的问题之前将其拒绝。 -当行为取决于您自己的工具、路径、命令、环境或操作规则时，请使用自定义策略。在创建之前，请先查阅[内置策略目录](/zh/policies/builtin-catalog)，避免重复已有的控制项。 +当行为取决于你的工具、路径、命令、环境或操作规范时，请使用自定义策略。建议先查阅 [Failproof AI 策略包](/zh/policies/packs)，避免重复创建已有的控制规则。 ## 编写自定义策略 - 1. 前往 **Admin → 策略编辑器**，选择 **新建策略**，并描述您希望防止的故障。 - 2. 添加策略源码，然后在编辑器中测试预期匹配项和安全的非匹配项，解决所有验证错误。 - 3. 保存草稿并选择 **发布版本**，创建一个不可变版本。 - 4. 前往 **Admin → 执行**，以 **观察** 模式将版本部署到测试机器，并在 **Observe → policy** 下验证其决策，然后再执行强制执行。 + 1. 前往 **Admin → 策略编辑器**，选择 **新建策略**，描述你希望防范的故障场景。 + 2. 添加策略代码，然后在编辑器中测试预期匹配项和安全的非匹配项，解决所有验证错误。 + 3. 保存草稿并选择 **发布版本** 以创建一个不可变版本。 + 4. 前往 **Admin → 执行**，以 **观察** 模式将该版本部署到测试机器，并在 **Observe → policy** 下验证其决策，确认无误后再正式执行。 ![用于编写和发布自定义策略的策略编辑器。](/images/dashboard/policy-editor.png) - 1. 创建 `.failproofai/policies/checkout-policies.ts`，文件名必须以 `policies.js`、`policies.mjs` 或 `policies.ts` 结尾。 + 1. 创建 `.failproofai/policies/checkout-policies.ts`。文件名必须以 `policies.js`、`policies.mjs` 或 `policies.ts` 结尾。 2. 使用 `customPolicies.add()` 注册一个或多个策略。 - 3. 使用 `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project` 验证并安装该文件。 - 4. 触发一个匹配的操作和一个安全的操作，运行 `failproofai policies`，然后在 **Observe → policy** 下检查归因决策。 + 3. 使用 `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project` 验证并安装文件。 + 4. 触发一个匹配的操作和一个安全操作。运行 `failproofai policies`，然后在 **Observe → policy** 下查看归因决策。 -## 从精准规则开始 +## 从精确的规则开始 -以下策略仅在命令指向生产环境时才阻止破坏性的 Kubernetes 命令，不在该故障模式范围内的所有情况均返回 `allow()`。 +以下策略仅在命令指向生产环境时才会拦截破坏性的 Kubernetes 命令。不属于该故障模式的情况均返回 `allow()`。 ```ts import { customPolicies, allow, deny } from "failproofai"; @@ -55,20 +55,20 @@ customPolicies.add({ }); ``` -好的策略应精准到可以用一句话说清楚。匹配可观察到的操作，而非您期望 Agent 具有的意图——一旦规则不适用，立即返回 `allow()`。 +好的策略应该精确到能用一句话说清楚。匹配可观测的操作——而非你期望 Agent 的意图——并在规则不适用时尽早返回 `allow()`。 ## 选择决策类型 | 辅助函数 | 结果 | 使用场景 | | --- | --- | --- | -| `allow(reason?)` | 操作继续执行。 | 策略不适用，或操作是安全的。 | -| `instruct(reason)` | 在支持的 harness 中，操作继续执行并附带指导。 | 希望引导 Agent 采用更好的方式，而不强制执行不变量。 | -| `deny(reason)` | 在事件和 harness 支持阻止的情况下，操作被拦截。 | 操作不得继续执行。 | +| `allow(reason?)` | 操作继续执行。 | 策略不适用或操作是安全的。 | +| `instruct(reason)` | 操作继续执行，并在支持的运行环境中向 Agent 提供指导。 | 希望引导 Agent 采取更好的方式，而不强制执行某个不变量。 | +| `deny(reason)` | 在事件和运行环境支持拦截的情况下，操作被阻止。 | 操作不应继续进行。 | -原因说明是为需要从中恢复的 Agent 而写的，请解释检测到了什么以及 Agent 应该怎么做。 +为需要恢复的 Agent 撰写说明原因。解释检测到了什么，以及应该改为做什么。 - 不要将 `instruct()` 用于安全边界。指导的传达方式因 Agent harness 而异。当操作必须被阻止时，请使用 `deny()`。 + 不要将 `instruct()` 用于安全边界。指导的传递方式因 Agent 运行环境而异。当操作必须被阻止时，请使用 `deny()`。 ## 策略对象 @@ -82,36 +82,36 @@ customPolicies.add({ }); ``` -| 字段 | 是否必填 | 说明 | +| 字段 | 是否必填 | 描述 | | --- | --- | --- | -| `name` | 是 | 策略的稳定标识符，在所有文件中保持唯一。 | -| `description` | 否 | 在策略列表和决策记录中显示的可读描述。 | -| `match.events` | 否 | 触发策略的事件类型。省略 `match` 时，策略对所有可用事件生效。 | +| `name` | 是 | 策略的稳定标识符。请确保跨文件的名称唯一。 | +| `description` | 否 | 在策略列表和决策中显示的人类可读用途说明。 | +| `match.events` | 否 | 触发该策略的事件类型。省略 `match` 则对所有可用事件触发。 | | `fn` | 是 | 同步或异步函数，返回 `allow`、`instruct` 或 `deny` 结果。 | -请在 `fn` 内部过滤工具，`match.toolNames` 不属于公共自定义策略类型。 +请在 `fn` 内部过滤工具。`match.toolNames` 不属于公开的自定义策略类型。 ## 策略上下文 -每个策略都会收到一个 `PolicyContext`。 +每个策略都会接收一个 `PolicyContext`。 -| 字段 | 类型 | 内容 | +| 字段 | 类型 | 内容说明 | | --- | --- | --- | -| `eventType` | `HookEventType` | 当前正在评估的规范化事件。 | +| `eventType` | `HookEventType` | 当前正在评估的标准化事件。 | | `toolName` | `string \| undefined` | 规范工具名称，如 `Bash`、`Read`、`Write` 或 `Edit`。 | -| `toolInput` | `Record \| undefined` | 当前工具调用的规范化输入。 | -| `payload` | `Record` | 完整的规范化事件载荷。 | -| `session` | `SessionMetadata \| undefined` | 可用时包含会话 ID、工作目录、记录路径、权限模式和 harness 元数据。 | -| `cli` | `string \| undefined` | 来源 Agent harness，如 `claude`、`codex` 或 `cursor`。 | -| `params` | `Record` | 内置策略参数，自定义策略当前接收空对象。 | +| `toolInput` | `Record \| undefined` | 当前工具调用的规范输入。 | +| `payload` | `Record` | 完整的标准化事件载荷。 | +| `session` | `SessionMetadata \| undefined` | 会话 ID、工作目录、记录路径、权限模式以及可用时的运行环境元数据。 | +| `cli` | `string \| undefined` | 来源 Agent 运行环境，如 `claude`、`codex` 或 `cursor`。 | +| `params` | `Record` | 内置策略参数。自定义策略当前接收的是空对象。 | -请将所有可选值视为真正可选的。不同的 Agent 版本和事件类型不一定提供相同的字段。 +请将所有可选值视为真正可选。不同的 Agent 版本和事件类型并不一定提供相同的字段。 -### 常见工具输入 +### 常用工具输入 -Failproof AI 对所有支持 harness 中的常用工具输入进行了规范化，因此策略通常可以使用统一的输入结构。 +Failproof AI 在支持的运行环境中对常用工具进行了标准化处理，因此策略通常可以使用统一的输入结构。 -| 工具 | 常见字段 | +| 工具 | 常用字段 | | --- | --- | | `Bash` | `command` | | `Read` | `file_path` | @@ -126,25 +126,25 @@ const command = String(ctx.toolInput?.command ?? ""); const filePath = String(ctx.toolInput?.file_path ?? ""); ``` -## 选择事件 +## 选择事件类型 | 事件 | 触发时机 | 典型用途 | | --- | --- | --- | -| `PreToolUse` | 工具执行之前。 | 阻止或引导命令、写入、读取及外部操作。 | -| `PostToolUse` | 工具返回之后。 | 在结果到达 Agent 之前进行检查。deny 会阻止整个结果，不支持选择性编辑字段。 | +| `PreToolUse` | 工具执行之前。 | 拦截或引导命令、写入、读取及外部操作。 | +| `PostToolUse` | 工具返回之后。 | 在结果传递给 Agent 之前检查结果。deny 会阻止整个结果，而不是屏蔽特定字段。 | | `PermissionRequest` | Agent 请求权限时。 | 应用组织特定的权限规则。 | -| `UserPromptSubmit` | 提交的提示词继续执行之前。 | 拒绝被禁止的指令或添加工作流指导。 | -| `Stop` | Agent 尝试结束时。 | 要求满足可达的完成条件，例如本地验证步骤。 | -| `SubagentStop` | 子 Agent 尝试结束时。 | 在委托工作返回父级之前进行把关。 | -| `SessionStart` / `SessionEnd` | 会话边界处。 | 记录或检查会话级状态。 | +| `UserPromptSubmit` | 提交的提示词继续执行之前。 | 拒绝禁止的指令或添加工作流指导。 | +| `Stop` | Agent 尝试结束任务时。 | 要求满足可达的完成条件，例如本地验证步骤。 | +| `SubagentStop` | 子 Agent 尝试结束时。 | 在委托工作返回父 Agent 之前进行门控。 | +| `SessionStart` / `SessionEnd` | 会话边界时。 | 记录或检查会话级别的状态。 | -事件的可用性及阻止行为取决于 Agent harness。在混合机群中依赖某个事件之前，请参阅 [Agent harnesses](/zh/reference/harnesses)。 +事件可用性和拦截行为取决于 Agent 运行环境。在混合机群中依赖某个事件之前，请参阅 [Agent 运行环境](/zh/reference/harnesses)。 `SessionStart`、`SessionEnd`、`UserPromptSubmit`、`PreToolUse`、`PermissionRequest`、`PermissionDenied`、`PostToolUse`、`PostToolUseFailure`、`Notification`、`SubagentStart`、`SubagentStop`、`TaskCreated`、`TaskCompleted`、`Stop`、`StopFailure`、`TeammateIdle`、`InstructionsLoaded`、`ConfigChange`、`CwdChanged`、`FileChanged`、`WorktreeCreate`、`WorktreeRemove`、`PreCompact`、`PostCompact`、`Elicitation`、`ElicitationResult`、`UserPromptExpansion`、`PostToolBatch` 和 `Setup`。 -## 编写常见策略模式 +## 常见策略模式示例 ### 阻止对受保护路径的写入 @@ -166,7 +166,7 @@ customPolicies.add({ }); ``` -### 提供非阻止性指导 +### 提供非阻断性指导 ```ts import { customPolicies, allow, instruct } from "failproofai"; @@ -186,7 +186,7 @@ customPolicies.add({ }); ``` -### 把关会话完成 +### 对会话完成进行门控 ```ts import { execFileSync } from "node:child_process"; @@ -215,7 +215,7 @@ customPolicies.add({ ``` - 被拒绝的 `Stop` 事件可能导致 Agent 重试。请只对 Agent 在当前环境中能够满足的条件进行把关，并为所有子进程或网络调用设置超时限制。 + 被拒绝的 `Stop` 事件可能导致 Agent 重试。请只对 Agent 在当前环境中能够满足的条件进行门控，并为所有子进程或网络调用设置超时限制。 ## 加载策略文件 @@ -229,12 +229,12 @@ customPolicies.add({ ~/.failproofai/policies/personal-policies.mjs ``` -- 项目和用户策略目录均会加载。 -- 每个目录内的文件按字母顺序加载。 -- 文件必须以 `policies.js`、`policies.mjs` 或 `policies.ts` 结尾。 -- 支持在一个文件中多次调用 `customPolicies.add()`。 +- 项目和用户策略目录均会被加载。 +- 文件在各目录内按字母顺序加载。 +- 文件名必须以 `policies.js`、`policies.mjs` 或 `policies.ts` 结尾。 +- 一个文件中支持多次调用 `customPolicies.add()`。 - 支持从本地模块进行相对导入。 -- 项目策略可以提交到代码库，使相同规则随仓库一起流转。 +- 项目策略可以提交到版本库，使相同规则随代码库一同传递。 ### 显式文件 @@ -247,11 +247,11 @@ failproofai policies --install \ --scope project ``` -显式文件优先加载，其次是项目约定文件，最后是用户约定文件。通过两种路径均发现的文件只加载一次。 +显式文件优先加载，其次是项目约定文件，最后是用户约定文件。同一个文件通过两种路径发现时只加载一次。 -## 验证与测试 +## 验证和测试 -验证会通过生产加载器执行模块，并确认其至少注册了一个策略。 +验证过程会通过生产加载器执行模块，并确认其至少注册了一个策略。 ```bash failproofai policies --install \ @@ -260,44 +260,44 @@ failproofai policies --install \ failproofai policies ``` -验证可捕获缺失文件、语法错误、未解析的导入、顶层异常以及模块加载超时。但它无法证明匹配逻辑是否正确。 +验证能捕获缺失的文件、语法错误、未解析的导入、顶层异常和模块加载超时。但它无法证明你的匹配逻辑是否正确。 -至少测试以下情况： +至少测试以下场景： - 一个必须匹配并产生预期策略原因的操作。 -- 一个相近但安全的操作，必须返回 `allow()`。 +- 一个临近但安全、必须返回 `allow()` 的操作。 - 缺失或格式错误的工具字段。 -- 不同的命令语法、路径、引号、大小写和空白符。 -- 不可用的子进程或网络依赖。 +- 不同的命令语法、路径、引号、大小写和空白字符。 +- 子进程或网络依赖不可用的情况。 -在 **Observe → policy** 下将结果归因到您的自定义策略。如果是另一个内置策略做出了决策，仅有被阻止的测试是不够的。 +在 **Observe → policy** 下将结果归因于你的自定义策略。如果决策是由其他内置策略做出的，则被拦截的测试不能算作有效验证。 ## 运行时行为 -- 内置策略先于自定义策略执行。 -- 第一个 `deny` 会停止后续所有策略的评估。 +- 内置策略在自定义策略之前评估。 +- 第一个 `deny` 会停止后续的策略评估。 - 当没有策略拒绝事件时，多个 `instruct` 结果可以合并。 -- 策略函数的执行超时限制为 10 秒。 -- 抛出的异常或超时会被记录，并被视为 `allow()`。 -- 加载失败的约定文件会被跳过，其他自定义文件和内置策略继续运行。 -- 顶层模块加载同样有 10 秒的超时限制。 -- 云观察模式会运行策略，但记录非 allow 决策而不强制执行。 +- 策略函数有 10 秒的执行时限。 +- 抛出的异常或超时会被记录日志并视为 `allow()`。 +- 加载失败的约定文件会被跳过；其他自定义文件和内置策略继续执行。 +- 顶层模块加载同样有 10 秒的时限。 +- 云端观察模式会运行策略，但会记录非 allow 决策而不实际执行拦截。 -保持策略模块的确定性和执行速度。避免顶层网络调用或启动服务器。在 `fn` 内部限制操作范围，捕获依赖失败，并有意识地决定该失败应该 allow 还是 deny 操作。 +保持策略模块的确定性和高效性。避免顶层网络调用或服务启动。在 `fn` 内限制工作量、捕获依赖故障，并有意识地决定故障时应 allow 还是 deny 操作。 ## API 导出 | 导出 | 用途 | | --- | --- | -| `customPolicies.add(policy)` | 在模块加载时注册自定义策略。 | -| `allow(reason?)` | 允许操作。 | +| `customPolicies.add(policy)` | 在模块加载时注册一个自定义策略。 | +| `allow(reason?)` | 允许该操作。 | | `instruct(reason)` | 允许操作并在支持的环境中提供指导。 | -| `deny(reason)` | 在支持的环境中阻止操作。 | -| `getCustomHooks()` | 返回模块注册表中当前已注册的策略。 | -| `clearCustomHooks()` | 清空该注册表，主要用于测试和加载器。 | +| `deny(reason)` | 在支持的环境中阻止该操作。 | +| `getCustomHooks()` | 返回当前在模块注册表中注册的策略。 | +| `clearCustomHooks()` | 清除该注册表，主要用于测试和加载器。 | TypeScript 导出 `PolicyContext`、`PolicyResult`、`CustomHook`、`PolicyDecision` 和 `PolicyFunction`。 - 发布版本、以观察模式部署、验证决策，然后进入强制执行阶段。 + 发布版本、以观察模式部署、验证决策，然后切换到强制执行模式。 \ No newline at end of file diff --git a/docs/zh/sessions/evaluations.mdx b/docs/zh/sessions/evaluations.mdx index 3dfb30a6..7677daa9 100644 --- a/docs/zh/sessions/evaluations.mdx +++ b/docs/zh/sessions/evaluations.mdx @@ -1,25 +1,25 @@ --- -title: "在线评估" -description: "对实时和已完成的会话进行质量、合规性、成本和延迟评分。" +title: "读取评估结果" +description: "跨时间维度绘制评估分数图表、比较 Agent 和环境、查看会话低分原因，并向助手提问。" icon: "gauge" --- -在线评估对 Agent 会话应用一致的判断标准。适用于需要持续监测而非仅在审计时才进行检查的指标。 +每次评估的结果，无论来自托管评估器还是您自己的 Worker，都会汇聚到相同的位置。 -## 审查评估质量 +## 跨时间比较分数 - 1. 前往 **Observe → Evaluations**。 - 2. 添加系列，选择 Agent、环境、评估分数、统计量和曲线。 - 3. 添加多个系列以比较不同环境、Agent 或分数键。 - 4. 选择某条结果以打开匹配的会话或共享筛选视图。延迟、Token 数、成本及其他量值请使用 **Observe → Metrics**。 + 前往 **Observe → evaluations**。 - ![展示平均评估分数及其随时间变化趋势的质量仪表盘。](/images/dashboard/dashboard-quality.png) + - **Recent runs** 列出每次评估的到达记录：包括来源（**managed** 托管评估器或 **customer** 自有评估器）、Agent 和会话、评估项及其版本、状态，以及分数或指标。 + - **Score over time** 绘制您所关注的内容。选择 **add series**，然后选择 Agent、环境、评估项和统计量：avg、min、max、p50、p75、p90、p95、p99、stddev 或 mode。每个数据系列对应一条折线；为其分配独立的 **curve** 可将其绘制在单独的图表上。 - 从下钻视图中打开会话，可查看各分项的评估推理过程： + ![评估页面：标记为 customer 的近期运行记录、带有 0.5 和 0.8 参考线的随时间变化的分数图表，以及对所有 Agent 和环境中 finished_clean 取平均值的单条数据系列。](/images/dashboard/evaluations-chart.png) - ![在完整追踪旁边展示评估分数和推理内容的会话详情视图。](/images/dashboard/session-detail.png) + 所有数据系列共用同一个时间范围和分组粒度。细粒度分组便于定位异常事件，粗粒度分组有助于呈现整体趋势，但可能会掩盖您正在寻找的波峰。某个时间桶内若无评估数据，折线上会显示空缺而非零值，参考线标记在 0.5 和 0.8 处。 + + 视图的每个配置都保存在 URL 中：点击 **share** 即可复制链接，打开链接的人将看到与您完全相同的对比视图。 ```bash @@ -28,25 +28,29 @@ icon: "gauge" fp evals --score helpfulness:0.8.. --since 7d ``` - 如需用于自动化，可在 `evals` 前添加全局参数 `--json`，例如 `fp --json evals --aggregate --env production`。 + 在 `evals` 前添加全局参数 `--json` 可用于自动化，例如 `fp --json evals --aggregate --env production`。 -评估器接收会话标识、环境、时间戳和有序事件，可返回带有可选推理说明和摘要的数值分数键。长时间运行的评估器可返回一个待处理任务，并在稍后进行轮询。 +对同一评估项同时绘制 **avg** 和 **p90**，可判断良好的平均值是否掩盖了较差的尾部表现；也可将同一评估项应用于两个不同的 Agent，或分别对生产环境和预发布环境进行对比，在同一坐标轴上直观呈现差异。费用、延迟和 Token 数量等带有单位的指标，请在 **Observe → metrics** 下查看图表，每种单位对应一张独立图表。 + +## 查看会话低分原因 + +从 **Observe → sessions** 打开某个会话；列表中每个会话都显示其分数，并支持按分数范围筛选。会话详情页右侧边栏首先展示评估摘要，然后为每个分数显示一条进度条，下方附有评估器的推理说明。 + +![会话详情视图，在完整追踪记录旁边展示评估分数和推理说明。](/images/dashboard/session-detail.png) + +## 向助手提问 + +用自然语言向助手提问，例如："告诉我一些近期的评估情况"，或哪些 Agent 的分数在下滑。[助手](/zh/sessions/assistant)会读取并分析评估结果，以表格形式作答供您进一步追问；值得保留的问题可以转化为[查询](/zh/sessions/queries)或[仪表板](/zh/sessions/dashboards)。 -## 适合评估的目标 +![评估页面与助手并排展示，助手回答了"告诉我一些近期的评估情况"，并给出了总数、状态和分数的摘要。](/images/dashboard/evaluations-assistant.png) -- 任务完成度或正确性 -- 事实依据与幻觉风险 -- 工具选择与使用效率 -- 政策或流程合规性 -- 成本与延迟预算 -- 是否需要人工介入升级 +## 监控与响应 -## 从评分到响应 +- **Dashboards** 位于 **Analyze → dashboards** 下，按 Agent 和环境维度，为整个组织展示您关注的分数趋势。 -在仪表盘中展示分数以跟踪趋势。为阈值或复合条件创建告警。当某项分数在整体水平上持续下降时，运行审计调查原因；若原因是某个可重复的操作，则部署相应策略。 + ![质量仪表板，展示平均评估分数及随时间变化的趋势。](/images/dashboard/dashboard-quality.png) - - 使用 Python 评估器 SDK 实现同步或异步评估。 - \ No newline at end of file +- **Alerts** 在分数超过阈值时发出通知。请参阅[告警](/zh/audits/alerts)。 +- 当某项分数在多个会话中持续下降时，[运行审计](/zh/audits/run)以查明原因；当原因可归结为某个可重现的操作时，[编写策略](/zh/policies/editor)加以约束。 \ No newline at end of file diff --git a/docs/zh/start/integrations/custom-agents.mdx b/docs/zh/start/integrations/custom-agents.mdx index 15c8bf83..796ddd1b 100644 --- a/docs/zh/start/integrations/custom-agents.mdx +++ b/docs/zh/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- -title: "自定义 Agent" -sidebarTitle: "自定义 Agent" -description: "为自己编写的 agent 或没有适配器的框架接入 SDK。" +title: "自定义 agents" +sidebarTitle: "自定义 agents" +description: "为自行编写的 agent 或没有适配器的框架添加埋点。" icon: "code" --- -适用于您自己编写的 agent，或 Failproof AI 尚无适配器的框架。无需任何插桩操作：您只需直接发送事件即可。 +适用于自行编写的 agent，或 Failproof AI 尚无适配器的框架。无需额外配置——你只需直接发出事件。 -这与四个框架适配器底层调用的 API 完全相同，适配器不过是对其的封装映射。 +这与四个框架适配器底层调用的 API 完全相同。适配器不过是对它的封装映射表。 ## 安装 @@ -15,9 +15,9 @@ icon: "code" pip install failproofai-sdk ``` -无额外依赖，也无任何外部依赖项。 +无额外依赖。 -## 接入 +## 埋点 ```python import failproofai_sdk @@ -30,27 +30,27 @@ with failproofai_sdk.session(): # 一次运行 t.output = search(q) # 一次工具调用 ``` -从上到下阅读，含义一目了然： +从上到下读，含义一目了然： | 包裹在 | 表示 | | --- | --- | | `session()` | 这些事件属于同一次运行 | -| `agent()` | 某个组件正在执行工作——给它一个在列表中易于识别的名称 | -| `tool_call()` | 这是一次工具调用，以及它的返回结果 | +| `agent()` | 某个组件正在执行工作——给它一个在列表中能识别的名称 | +| `tool_call()` | 这是一次工具调用，以及它的返回值 | -各作用域实际发送的事件： +每个作用域实际发出的事件： -| 作用域 | 发送事件 | 用途 | +| 作用域 | 发出的事件 | 用途 | | --- | --- | --- | -| `session()` | 无 | 绑定 session id，将一次运行分组 | -| `agent()` | `agent_start`、`agent_end` | 标记一个工作单元的起止 | -| `tool_call()` | `tool_use`、`tool_result` | 标记一次工具调用的起止并计时 | +| `session()` | 无 | 绑定 session id，将一次运行归组 | +| `agent()` | `agent_start`、`agent_end` | 标记一个工作单元的开始和结束 | +| `tool_call()` | `tool_use`、`tool_result` | 标记一次工具调用并计时 | -内部的所有内容都可以省略 `session_id` 和 `agent_id`。作用域会将身份信息绑定到上下文变量中，每次事件调用都会自动读取，因此无需在函数间手动传递 id。 +内部的所有内容都可以省略 `session_id` 和 `agent_id`。作用域将身份信息绑定在上下文变量上，每次事件调用都会自动读取，无需在函数间手动传递 id。 -三者均支持 `async with` 和 `with`。 +三者均支持 `async with` 和普通 `with`。 -嵌套 agent 可构建调用树，`parent_id` 和深度会根据调用栈自动计算： +嵌套 agent 会构建树形结构。`parent_id` 和深度由调用栈自动计算： ```python with failproofai_sdk.session(): @@ -63,31 +63,31 @@ with failproofai_sdk.session(): `agent()` 会自动处理异常： -| 发生情况 | 事件 | 结果 | +| 发生了什么 | 发出的事件 | 结果 | | --- | --- | --- | | 无异常 | `agent_end` | `success` | | `Exception` | `error`，然后 `agent_end` | `failed` | | `KeyboardInterrupt`、`SystemExit` | `error`，然后 `agent_end` | `failed` | | `CancelledError`、`GeneratorExit` | 仅 `agent_end` | `cancelled` | -错误事件在 `agent_end` 之前发出，因为 dashboard 在 `agent_end` 时关闭 span，之后的任何内容都无法归属。取消操作不是失败，因此已取消的运行不会污染错误视图。异常始终会被重新抛出：作用域永远不会吞掉异常。 +error 事件在 `agent_end` 之前发出，因为 dashboard 在收到 `agent_end` 时关闭 span，之后的事件将无法归属。取消不是失败，因此已取消的运行不会污染错误面板。异常始终会被重新抛出——作用域永远不会吞掉异常。 ## 事件方法 -六个系列，共十五个方法。大多数成对出现——发送开始事件，再发送结束事件，SDK 会自动计算两者之间的时间跨度。 +六个类别，共十五个方法。大多数成对出现——你发出开启事件，再发出关闭事件，SDK 会测量两者之间的时间跨度。 -| 系列 | 开始 | 结束 | 独立 | +| 类别 | 开启 | 关闭 | 独立 | | --- | --- | --- | --- | | **Agents** | `agent_start` | `agent_end` | — | | | `agent_pause` | `agent_resume` | — | -| **Models** | `model_request` | `model_response` | — | -| **Tools** | `tool_use` | `tool_result` | — | +| **模型** | `model_request` | `model_response` | — | +| **工具** | `tool_use` | `tool_result` | — | | **Hooks** | `hook_triggered` | `hook_completed` | — | -| **Humans** | `human_wait` | `human_input` | `human_pause`、`human_interrupt` | -| **Failures** | — | — | `error` | +| **人工** | `human_wait` | `human_input` | `human_pause`、`human_interrupt` | +| **失败** | — | — | `error` | - 在适用的场景下，优先使用作用域——`agent()` 和 `tool_call()`。即使主体代码抛出异常，它们也能保证关闭事件被发出。只有当控制流无法嵌套时（例如辅助函数中的模型调用），才直接使用这些方法。 + 在适用的场景下优先使用作用域——`agent()` 和 `tool_call()`。它们能保证即使函数体抛出异常也会发出关闭事件。只有当控制流无法嵌套时（例如在辅助函数内的模型调用）才直接使用这些方法。 @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **两组人类事件方向相反。** + **两组人工事件的方向相反。** | 方法 | 含义 | | --- | --- | - | `human_wait` / `human_input` | **agent 询问人员**——审批门控、澄清性问题 | - | `human_pause` / `human_interrupt` | **人员操作 agent**——停止按钮、操作员暂停 | + | `human_wait` / `human_input` | **agent 向人发起请求**——审批门控、澄清问题 | + | `human_pause` / `human_interrupt` | **人对 agent 采取了操作**——停止按钮、运维暂停 | - 没有任何框架会发出第二组事件，因此始终需要您自行发送。 + 没有任何框架会发出第二对事件，因此始终需要你自己发出。 - **当模型调用并发执行时，请传入 `request_id`。** 如果不传，请求和响应将按每个 agent 的到达顺序配对——并发调用会错误配对，将每个响应关联到错误的请求上。 + **并发执行模型调用时请传入 `request_id`。** 若不传，请求和响应将按每个 agent 的到达顺序配对——并发调用会错配，将每个响应关联到错误的请求。 ## 示例 -直接调用 OpenAI API 的工具调用循环，不使用任何 agent 框架： +一个基于 OpenAI API 的工具调用循环，不使用任何 agent 框架： ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """一次模型调用，由事件对标记起止。""" + """一次模型调用，由事件对包裹。""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -186,7 +186,7 @@ def turn(messages: list): with failproofai_sdk.session(): with failproofai_sdk.agent("inventory", goal="price report"): - for _ in range(4): # 有界循环；无界 agent 循环本身就是一个 bug + for _ in range(4): # 有界循环；无界的 agent 循环本身就是一个 bug message = turn(messages) if not message.tool_calls: break @@ -204,14 +204,14 @@ with failproofai_sdk.session(): }) ``` -这会生成与适配器相同的六种事件类型。包含工具定义的完整可运行版本位于 SDK 仓库的 `docs/manual/examples/` 目录下。 +这将产生与适配器相同的六种事件类型。包含工具定义的完整可运行版本位于 SDK 仓库的 `docs/manual/examples/` 目录下。 ## 线程与异步 -上下文变量会自动传播到 asyncio 任务中，但不会传播到新线程，因为线程启动时上下文为空。 +上下文变量会自动传播到 asyncio 任务中，但不会传播到新线程——线程启动时上下文为空。 ```python -# asyncio：无需额外操作 +# asyncio：无需任何操作 async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) @@ -221,28 +221,28 @@ threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -不使用 `propagate()` 时，worker 的事件会抛出 `TypeError` 并提示修复方法，而不是落入无 session 的状态。这是有意为之：没有 session 的事件会被摄取层跳过并返回 `200`，而这正是身份层要防止的静默失败。 +不使用 `propagate()` 时，worker 的事件会抛出 `TypeError` 并提示修复方法，而不是静默地落到没有 session 的状态。这是有意为之：没有 session 的事件在摄入时会被跳过并返回 `200`，这正是身份层要防止的静默失败。 -## 为没有适配器的框架接入 +## 为没有适配器的框架添加埋点 -每个 agent 框架都提供相同的三个切入点。映射它们即可获得完整的追踪——已提供的四个适配器所做的不过如此。 +每个 agent 框架都提供相同的三个切入点。映射它们即可获得完整的追踪——四个内置适配器也仅此而已。 -| 切入点 | 您编写的内容 | 产生的事件 | +| 切入点 | 你需要编写 | 产生的事件 | | --- | --- | --- | | 运行 | `session()` + `agent()` | `agent_start`、`agent_end` | | 每次工具调用 | `tool_call()` | `tool_use`、`tool_result` | | 每次模型调用 | `model_*` 事件对 | `model_request`、`model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): result = framework.run(task) ``` - - 在框架中称为工具包装器或中间件的位置。 + + 在框架的工具包装器或中间件中添加。 ```python with failproofai_sdk.tool_call(name, input=args) as call: @@ -264,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **有值得观察的节点、步骤或中间件边界？** 用 hook 对——`hook_triggered` / `hook_completed`——来包裹，而不是嵌套 `agent()`。`agent_id` 是低基数维度，每个节点都创建一个条目会使其不可用。Hook span 的渲染方式相同，且能提供每个节点的延迟数据。 + **有值得观测的节点、步骤或中间件边界？** 用 hook 对——`hook_triggered` / `hook_completed`——来包裹，而不是嵌套的 `agent()`。`agent_id` 是低基数维度，每个节点一个条目会使其失效。Hook span 的渲染方式相同，还能提供每节点的延迟数据。 - **手动接入与自动接入可以组合使用。** 在手写作用域内运行的适配器会加入该 session 并以该 agent 作为父节点，从而生成一棵统一的树，而不是两棵独立的树——当您将一个框架与已支持的框架混合接入时非常有用。 + **手动埋点与自动埋点可以组合使用。** 在手动编写的作用域内运行的适配器会加入该 session 并以该 agent 为父节点，从而形成一棵树而非两棵——当你同时对一个框架手动埋点和使用受支持的框架时非常有用。 - 原因有两点，上述三个切入点就是解决方案： + 原因有两点，而上述三个切入点正是对这两点的解答： - `autogen-core` 自 2025 年 9 月起已停止维护。 - - AG2 没有提供等同于其他框架钩子的全局注册点，因此接入它意味着需要在每个构造点包裹每个 agent。 + - AG2 没有提供等同于其他框架 hook 的全局注册点，因此要对其埋点就意味着在每个构建位置包裹每个 agent。 - 手动映射切入点可以记录与正式适配器相同的事件，且精度相同。 + 手动映射这三个切入点所记录的事件，与内置适配器的保真度完全相同。 ## 深入了解 -以下是录制机制的工作原理，入门时无需阅读。 +记录机制的工作原理。入门时无需了解这些内容。 - + -每条录制的结构相同：一个 span 开始，工作嵌套其中，每个开始事件都有对应的结束事件。 +每次记录的结构相同：一个 span 开启，工作嵌套在其中，每个开启事件都有对应的关闭事件。 ```mermaid flowchart LR @@ -300,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -**事件对**是基本单元。每个结束事件携带 SDK 从对应开始事件起计算的持续时间。 +**事件对**是基本单元。每个关闭事件携带 SDK 从对应开启事件起测量的持续时间。 -以下是每个框架的一次真实运行——来自 SDK 附带的示例，模型名称已规范化。注意单次调用能返回多少信息。 +以下是每个框架各一次真实运行的记录——来自 SDK 附带的示例，模型名称已统一。注意单次调用能带回多少信息。 @@ -323,7 +323,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - 节点转换为 hook 对，因此您可以获取每个节点的延迟数据，而不会让 agent 列表过于拥挤。 + 节点转换为 hook 对，因此你可以获得每节点的延迟，而不会使 agent 列表过于拥挤。 @@ -340,7 +340,7 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - 每个 agent 的 `role` 成为其 span 名称，因此延迟和 token 消耗可按角色细分。 + 每个 agent 的 `role` 成为其 span 名称，因此延迟和 token 消耗可按角色分解。 @@ -360,7 +360,7 @@ flowchart LR 26 +7.038s agent_end Agent · success ``` - agent 循环本身清晰可见，而不仅仅是其模型调用。 + agent 循环本身是可见的，不仅仅是它的模型调用。 @@ -375,7 +375,7 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - 无 hook 对：Pydantic AI 没有可标记的节点或步骤边界。 + 无 hook 对：Pydantic AI 没有可供包裹的节点或步骤边界。 @@ -388,36 +388,36 @@ flowchart LR 6 +0.000s agent_end main · success ``` - 这些事件由您自行发送。事件类型相同，精度相同——代价是需要在调用处手动添加。 + 这些事件由你自己发出。事件类型相同，保真度相同——代价是需要手动添加调用点。 - + -**没有 session 结束事件。** Session 不是需要主动关闭的东西——它是一组共享同一 `session_id` 的事件。 +**没有 session 结束事件。** session 不是你去关闭的东西——它是一组共享同一 `session_id` 的事件。 状态由追踪的形态推导： -| 状态 | 条件 | +| 状态 | 时机 | | --- | --- | -| `ongoing` | 至少有一个 span 仍处于开放状态 | -| `paused` | 存在没有对应 `agent_resume` 的 `agent_pause` | -| `error` | 没有开放的 span，且至少有一个事件失败 | -| `done` | 没有开放的 span，且没有失败 | +| `ongoing` | 至少有一个 span 仍处于打开状态 | +| `paused` | `agent_pause` 没有对应的 `agent_resume` | +| `error` | 没有打开的 span，且至少有一个事件失败 | +| `done` | 没有打开的 span，且没有失败 | -因此，当所有事件对都关闭时，session 就结束了。适配器会为您发出 `agent_end`，在销毁时关闭所有仍处于开放状态的内容并标记为不完整——崩溃的运行会以 `done` 状态结束，并显示一个明显的缺口，而不是永远挂起。 +因此，当所有事件对都关闭时，session 即结束。适配器会为你发出 `agent_end`，并在拆卸时关闭所有仍打开的 span 并标记为未完成——崩溃的运行会以 `done` 状态结算，留下一个可见的缺口，而不是永久挂起。 - 这就是为什么一个 session 可以跨越两次调用。LangGraph `interrupt()` 会暂停运行，根 span 故意保持开放，恢复调用时再将其关闭。两次调用属于同一个 session。 + 这就是为什么一个 session 可以跨两次调用。LangGraph 的 `interrupt()` 会暂停运行，根 span 故意保持打开状态，由后续恢复调用来关闭它。两次调用属于同一个 session。 - + -`session_id` 和 `agent_id` 在每个事件方法上都是可选的。省略时，它们从外层作用域解析： +`session_id` 和 `agent_id` 在每个事件方法中都是可选的。省略时，它们从外层作用域解析： ```python with failproofai_sdk.session(): @@ -425,128 +425,128 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -显式传入时优先生效。如果没有绑定任何值也没有传入，调用会抛出 `TypeError` 并提示修复方法，而不是发出没有 session 的事件（摄取层会跳过该事件并返回 `200`）。 +显式传入仍然有效且优先级更高。若既没有绑定作用域也没有传入参数，调用会抛出 `TypeError` 并提示修复方法，而不是发出一个没有 session 的事件（这类事件在摄入时会被跳过并返回 `200`）。 -作用域将身份信息绑定到上下文变量中。这些变量会自动传播到 asyncio 任务，但不会传播到新线程——需要用 `failproofai_sdk.propagate()` 包裹 worker。 +作用域将身份信息绑定在上下文变量上。这些变量会自动传播到 asyncio 任务中，但不会传播到新线程——需要将 worker 包裹在 `failproofai_sdk.propagate()` 中。 -#### 各 id 的生成方 +#### 各 id 的生成者 -| Id | 生成方 | 说明 | +| Id | 生成者 | 说明 | | --- | --- | --- | -| `session_id` | 您，或 SDK | `session("chat-42")` 按原样使用；省略时，SDK 生成 `uuid4().hex` | -| `agent_id` | 您，或框架 | 来自 `agent("analyst")`、CrewAI 的 `role`、`FunctionAgent.name`。看起来像 UUID 的值会被拒绝并替换 | -| `tool_call_id`、`hook_id`、`request_id` | 您，或框架 | 适配器复用框架自身的运行 id，这就是为什么事件对能在线程切换后仍能正确配对 | -| **事件 id** | **Cloud，在摄取时** | SDK 不发送 | -| **`dedup_key`** | **Cloud，在摄取时** | 组织、session、时间戳、类型和 payload 的哈希值。这是真正的身份标识——使重试的批次合并而不是重复 | +| `session_id` | 你，或 SDK | `session("chat-42")` 原样使用；省略时 SDK 生成 `uuid4().hex` | +| `agent_id` | 你，或框架 | 来自 `agent("analyst")`、CrewAI 的 `role`、`FunctionAgent.name`。看起来像 UUID 的值会被拒绝并替换 | +| `tool_call_id`、`hook_id`、`request_id` | 你，或框架 | 适配器复用框架自身的运行 id，因此事件对在线程跳转后仍能正确配对 | +| **事件 id** | **Cloud，在摄入时** | SDK 不发出此值 | +| **`dedup_key`** | **Cloud，在摄入时** | 组织、session、时间戳、类型和载荷的哈希值。这才是真正的身份标识——它让重试的批次折叠而不是重复 | #### 适配器如何解析 `session_id` -先匹配者优先： +按优先级，第一个匹配生效： 1. 显式传入的 `session_id` 选项 2. 每次调用的元数据 -3. 外层 `session()` 作用域 +3. 外层的 `session()` 作用域 4. 框架元数据 5. 框架自身的运行 id -在上述来源存在时，永远不会凭空生成——合成的 id 会将一次运行拆分为多个 session。 +在上述任一来源存在时，绝不会凭空生成——合成的 id 会将一次运行拆分到多个 session 中。 -#### 保持 `agent_id` 低基数 +#### 保持 `agent_id` 的低基数 -它是每个 dashboard 视图的主要维度，也是 `LowCardinality(String)` 列。使用每次运行唯一的值会降低该列的效用，并在筛选下拉框中填满每次运行对应的条目。 +它是每个 dashboard 界面的主要维度，对应一个 `LowCardinality(String)` 列。每次运行一个值会降低该列的效能，并使过滤下拉菜单中充斥着每次运行的单独条目。 -适配器会为您维护该列： +适配器会为你维护这个列： -| 框架提供的值 | 记录为 | 原因 | +| 框架传入的值 | 记录为 | 原因 | | --- | --- | --- | | `3f9a1c2b-…`（UUID） | `main` | 没有可保留的可读内容 | -| 较长的纯十六进制字符串 | `main` | 同上 | -| `agent-3f9a1c2b-…` | `agent` | 去除每次运行的 id，保留可读部分 | +| 长的纯十六进制字符串 | `main` | 同上 | +| `agent-3f9a1c2b-…` | `agent` | 剥离每次运行的 id，保留可读部分 | | `agent-v2` | `agent-v2` | 短片段保持不变 | | `step-3` | `step-3` | 同上 | -真实 id 保存在 `fw_agent_id` / `fw_run_id` 上，在那里仍可查询，但不会作为维度。 +真实 id 保存在 `fw_agent_id` / `fw_run_id` 上，在那里仍可查询，但不作为维度。 - **此保护仅针对框架自动选择的标签。** 您自行传入的 `agent_id`——无论是传给 `event.*` 还是 `failproofai_sdk.agent(...)`——都会原样记录。静默改写显式参数比它所防止的基数问题更糟糕，因此请自行为 span 命名时注意命名规范。 + **此保护仅作用于框架自动选择的标签。** 你自己传入的 `agent_id`——无论是传给 `event.*` 还是 `failproofai_sdk.agent(...)`——都会原样记录。静默改写显式参数带来的危害比它所防止的基数问题更大，因此请自行为 span 命名。 - + | 分组 | 事件 | | --- | --- | | Agents | `agent_start`、`agent_end`、`agent_pause`、`agent_resume` | -| Models | `model_request`、`model_response` | -| Tools | `tool_use`、`tool_result` | +| 模型 | `model_request`、`model_response` | +| 工具 | `tool_use`、`tool_result` | | Hooks | `hook_triggered`、`hook_completed` | -| Humans | `human_wait`、`human_input`、`human_pause`、`human_interrupt` | -| Failures | `error` | +| 人工 | `human_wait`、`human_input`、`human_pause`、`human_interrupt` | +| 失败 | `error` | -各框架记录的内容（基于上述运行示例）： +基于上述运行数据，各框架记录的事件： -| 事件 | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | +| 事件 | LangGraph | CrewAI | LlamaIndex | Pydantic AI | 自定义 | | --- | :--: | :--: | :--: | :--: | :--: | -| Agent 开始和结束 | 是 | 是 | 是 | 是 | 您 | -| 模型请求和响应 | 是 | 是 | 是 | 是 | 您 | -| 工具使用和结果 | 是 | 是 | 是 | 是 | 您 | -| Hook 触发和完成 | 节点 | 任务 | 步骤 | — | 您 | +| Agent 开始和结束 | 是 | 是 | 是 | 是 | 你 | +| 模型请求和响应 | 是 | 是 | 是 | 是 | 你 | +| 工具使用和结果 | 是 | 是 | 是 | 是 | 你 | +| Hook 触发和完成 | 节点 | 任务 | 步骤 | — | 你 | | 错误 | 是 | 是 | 是 | 是 | 自动 | -| 人员等待和输入 | 是 | 是 | 是 | — | 您 | -| Agent 暂停和恢复 | 是 | 是 | 是 | — | 您 | +| 人工等待和输入 | 是 | 是 | 是 | — | 你 | +| Agent 暂停和恢复 | 是 | 是 | 是 | — | 你 | -破折号表示该框架没有此概念。`human_pause` 和 `human_interrupt` 描述的是*人员*对 agent 的操作，没有任何框架会发出这些事件——需要您自行发送。 +横线表示该框架没有此概念。`human_pause` 和 `human_interrupt` 描述的是人对 agent 采取操作，没有任何框架会发出这类信号——需要你自己发出。 -事件从不单独出现。一个开始，一个结束，结束事件携带 SDK 从开始事件起计算的持续时间。 +事件从不单独出现。一个开启，一个关闭，关闭事件携带 SDK 从开启事件起测量的持续时间。 -| 开始 | 结束 | 结束事件携带 | +| 开启 | 关闭 | 关闭事件携带的内容 | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`、`summary` | | `model_request` | `model_response` | token 数、`stop_reason`、延迟 | | `tool_use` | `tool_result` | `output` 或 `error`、持续时间 | | `hook_triggered` | `hook_completed` | `outcome`、持续时间 | -| `agent_pause` | `agent_resume` | 暂停持续时间 | -| `human_wait` | `human_input` | 答案，以及人员响应所用时间 | +| `agent_pause` | `agent_resume` | 暂停持续时长 | +| `human_wait` | `human_input` | 答复内容及人的响应时长 | - 有开始事件但没有结束事件，就是一个永不结束的 span。Session 会一直显示为运行中，其活动时长持续增长。这是手动接入时需要特别注意的失败模式。 + 有开启事件但没有对应关闭事件，意味着一个永远不会结束的 span。session 会显示为仍在运行，且活跃时长持续增长。这是手动埋点时需要注意的失败模式。 #### 关联规则 -- 在对应的完成事件中复用相同的 `tool_call_id`、`hook_id`、`pause_id` 或 `input_id`。 -- SDK 会自动计算 `tool_result`、`hook_completed`、`agent_resume` 和 `human_input` 的 `duration_ms`。向这些方法传入该参数会抛出 `ValueError`。 -- `duration_ms` **可以**传给 `model_response`，因为只有调用方才知道真实的提供商延迟。必须为整数——浮点数会在调用处抛出 `ValueError`，因为服务器将该列读取为无符号 32 位整数，其他类型会存储 NULL。 -- 关联键按类型和 session 限定范围，因此工具调用和 hook 可以安全地共用同一个 id，两个并发 session 也可以复用相同的 id 而不冲突。关联键不按 agent 限定范围：在一个 agent 下开始、在另一个 agent 下关闭的事件对仍能正确关联，这在多 agent 框架中是常见情况。 -- `request_id` 用于配对 `model_request` 和 `model_response`。不传时，模型事件按每个 agent 的顺序配对，并发调用会导致错误配对。 -- 跨进程的事件对在下游仍能关联，但 SDK 无法计算其进程内持续时间。 -- 待处理映射最多保存 10,000 个开始事件，满时驱逐最旧的条目。 +- 在匹配的完成事件中复用相同的 `tool_call_id`、`hook_id`、`pause_id` 或 `input_id`。 +- SDK 为 `tool_result`、`hook_completed`、`agent_resume` 和 `human_input` 计算 `duration_ms`。向这些方法传入 `duration_ms` 会抛出 `ValueError`。 +- `duration_ms` **可以**传给 `model_response`，因为只有调用方才知道真实的提供商延迟。它必须是整数——浮点数会在调用处抛出 `ValueError`，因为服务端将该列读取为无符号 32 位整数，其他类型会存储为 NULL。 +- 关联键按类型和 session 作用域，因此工具调用和 hook 可以安全地共享 id，两个并发 session 也可以复用相同的 id 而不冲突。关联键不按 agent 作用域：在一个 agent 下开启、在另一个 agent 下关闭的事件对仍然能正确关联，这在多 agent 框架中是常见情况。 +- `request_id` 将 `model_request` 与 `model_response` 配对。若不传，模型事件按每个 agent 的顺序配对，并发调用会错配。 +- 跨进程拆分的事件对在下游仍能关联，但 SDK 无法计算其进程内持续时间。 +- 待匹配映射最多保存 10,000 个开启事件，满后会驱逐最旧的条目。 - + -安装 `failproofai-sdk` 会安装所有内容，包含全部四个适配器。extras 安装的是**框架**本身，而不是适配器。 +安装 `failproofai-sdk` 会安装全部内容，包含四个适配器。extras 拉取的是**框架**，而不是适配器。 ```python import failproofai_sdk # 不加载标准库以外的任何内容 -failproofai_sdk.instrument() # 仅导入您实际需要的适配器 +failproofai_sdk.instrument() # 仅导入你实际需要的适配器 ``` -`import failproofai_sdk` 在契约上是零依赖的，通过两个测试强制保证：一个测试使用 `--no-deps` 安装构建好的 wheel，另一个测试确认没有任何框架出现在 `sys.modules` 中。 +`import failproofai_sdk` 承诺零依赖，通过以下测试强制保证：一个在不带 `--no-deps` 的情况下安装构建 wheel 的测试，以及另一个证明没有框架进入 `sys.modules` 的测试。 - 不存在 `failproofai_sdk.crewai` 属性。适配器有意不暴露在顶层包上：访问它会作为属性访问的副作用导入框架，破坏零依赖承诺。请使用 `instrument()`。 + 不存在 `failproofai_sdk.crewai` 属性。适配器故意不在顶层包上暴露：访问它会作为属性访问的副作用导入框架，破坏零依赖承诺。请使用 `instrument()`。 ```python failproofai_sdk.instrument() # 所有已导入的框架 -failproofai_sdk.instrument("crewai") # 指定一个，按名称 +failproofai_sdk.instrument("crewai") # 按名称指定单个框架 failproofai_sdk.uninstrument("crewai") # 还原 ``` @@ -557,7 +557,7 @@ failproofai_sdk.uninstrument("crewai") # 还原 | `llama_index` | `llamaindex`、`llama-index` | | `pydantic_ai` | `pydantic-ai`、`pydanticai` | -自动检测读取 `sys.modules`，而不是已安装的包列表，因此已安装但从未导入的框架不会被接入，也不会被代为导入。要查看当前已接入的内容： +自动检测读取 `sys.modules` 而不是已安装的包列表，因此已安装但从未导入的框架不会被埋点，也不会被代为导入。查看已连接的内容： ```python from failproofai_sdk.integrations import active, available @@ -567,20 +567,20 @@ active() # ('langchain',) ``` - **在未安装 CrewAI 的机器上调用 `instrument("crewai")` 不会抛出异常。** 它会记录一条警告并返回 `()`，因此缺少一个框架不会导致同时接入其他框架的进程崩溃。 + **在没有安装 CrewAI 的机器上调用 `instrument("crewai")` 不会抛出异常。** 它会记录一条警告并返回 `()`，因此一个缺失的框架不会拖垮同时埋点其他框架的进程。 - 警告中包含底层的 `ImportError`，该消息会给出准确的安装命令——修复方法就在您的日志中，不会被隐藏。 + 警告中包含底层的 `ImportError`，该消息会指出确切的安装命令——修复方法在你的日志里，不会被隐藏。 ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - 设置 `FAILPROOFAI_SDK_STRICT=1` 可改为抛出异常。该标志**只读取一次并缓存**，因此请在进程启动前导出，而不是在运行中途设置。 + 设置 `FAILPROOFAI_SDK_STRICT=1` 可改为抛出异常。该标志**只读取一次并缓存**，因此请在进程启动前导出它，而不是在运行途中设置。 - **`instrument()` 必须在框架导入*之后*调用。** 自动检测读取 `sys.modules`，因此在导入之前裸调用什么也找不到，不会安装任何内容，并返回 `()`。 + **`instrument()` 必须在框架导入**之后**调用。** 自动检测读取 `sys.modules`，因此在导入之前的裸调用什么都找不到，不会安装任何内容，并返回 `()`。 @@ -588,7 +588,7 @@ active() # ('langchain',) import failproofai_sdk failproofai_sdk.instrument() # sys.modules 中还没有 langchain -> () -import langchain # 太晚了，什么都没有接入 +import langchain # 太晚了，什么都没被连接 ``` ```python Right @@ -606,7 +606,7 @@ failproofai_sdk.instrument("langchain") ``` -操作有误时，进程会在 SDK 已导入、适配器看似已安装的情况下运行，但**一个事件都不会发出**。SDK 会记录一条明确说明此情况的警告——当运行没有记录任何内容时，请先检查日志。 +如果出错，进程会在 SDK 已导入、适配器看似已安装的情况下运行，但**不会发出任何事件**。它会记录一条明确说明此情况的警告——因此当某次运行没有记录任何内容时，请先检查日志。 @@ -614,7 +614,7 @@ failproofai_sdk.instrument("langchain") ```mermaid flowchart LR - A["您的 agent"] --> B["适配器"] + A["你的 agent"] --> B["适配器"] B --> C["Writer
内存队列"] C -->|"每 0.5 秒"| D["Spool
磁盘上的 JSONL"] D --> E["Failproof 守护进程"] @@ -623,74 +623,76 @@ flowchart LR | 阶段 | 职责 | 运行位置 | | --- | --- | --- | -| 适配器 | 将框架回调转换为 15 种事件类型之一 | 您的进程 | -| Writer | 队列、批处理、原子写入 JSONL | 您的进程，后台线程 | -| Spool | 持久化交接，进程退出后仍存在 | 本地磁盘 | -| 守护进程 | 监视 spool，发送批次，删除已发送内容 | 您的机器 | -| Ingest | 分配行 id 和去重键，提升可查询列 | Cloud | +| 适配器 | 将框架回调转换为 15 种事件类型之一 | 你的进程 | +| Writer | 排队、批处理、原子写入 JSONL | 你的进程，后台线程 | +| Spool | 持久交接，在你的进程退出后仍然存在 | 本地磁盘 | +| 守护进程 | 监视 spool，发送批次，删除已发送内容 | 你的机器 | +| 摄入 | 分配行 id 和去重键，提升可查询列 | Cloud | -Spool 是安全保障：您的 agent 永远不会因网络而阻塞，Cloud 故障只会导致目录增大，而不是事件丢失。 +spool 是确保安全的关键：你的 agent 永远不会因网络而阻塞，Cloud 故障只会导致目录增大，而不是事件丢失。 -每次刷新写入一个批次文件，先写 `.tmp`，然后 `fsync`，最后原子重命名： +每次刷新写入一个批次文件，先写 `.tmp`，然后 `fsync`，再原子重命名： ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -守护进程只读取 `.jsonl`，因此永远不会读到写了一半的文件。文件名包含时间戳、进程 id 和序列号，因此两个进程在同一毫秒内刷新也不会冲突。队列上限为 10,000 个事件；超过后会丢弃最旧的事件并记录日志。 +守护进程只处理 `.jsonl` 文件，因此永远不会读到写入一半的文件。文件名包含时间戳、进程 id 和序列号，因此两个进程在同一毫秒内刷新也不会冲突。队列最多容纳 10,000 个事件，超出后会丢弃最旧的并记录日志。 - **`collector.redact` 对 SDK 事件也默认为 `minimal`。** SDK 在将批次写入磁盘前进行脱敏，守护进程在上传前对相同内容执行同样的确定性处理，以确保来自旧版 SDK 的批次也受到保护。 + **`collector.redact` 不适用于你的 SDK 事件。** 它根本看不到这些事件。 -守护进程在内存中对每个批次进行脱敏后再上传，不会重写已读取的 spool 文件。 +守护进程**发送**你的批次。它不打开也不重写这些批次。 -| 事件 | 由谁写入 | minimal 脱敏在何处执行 | +| 事件 | 写入者 | 是否受 `collector.redact` 处理 | | --- | --- | --- | -| CLI 会话记录 | 守护进程 | 守护进程写入批次之前 | -| Hook 活动 | 守护进程 | 守护进程写入批次之前 | -| **SDK 发出的所有内容** | **您的进程** | **SDK 写入批次之前，以及守护进程上传之前** | +| CLI 会话记录 | 守护进程 | 是 | +| Hook 活动 | 守护进程 | 是 | +| **SDK 发出的所有事件** | **你的进程** | **否** | -仅当明确要求原始 payload 时才将 `collector.redact` 设为 `off`；SDK 和守护进程都遵循该设置。minimal 脱敏可识别常见的 API 密钥、bearer token、JWT 和密钥赋值，但无法识别任意敏感文本。 +脱敏在守护进程**写入**自身事件的地方运行——而不是在批次**发送**的地方。因此，包含 API 密钥的 prompt 或工具参数在到达时仍然包含该密钥。 + +这是有意为之。这些是你自己的埋点调用，在传输过程中改写它们意味着你收到的事件与你发出的不一致。 - **您可以在源头控制 payload，有两种方式：** + **你在源头控制载荷，有两种方式：** - - 在适配器上关闭内容捕获。**选项名称各不相同，且有一个适配器没有此选项**——这不是一个通用开关： - - LangChain / LangGraph、Pydantic AI — `capture_content=False` - - LlamaIndex — `capture_messages=False` - - CrewAI — **完全没有内容开关**；它只读取 `session_id` 选项，因此提示词和补全内容始终会被记录。 + - 在适配器上关闭内容捕获。**选项名称各不相同，且有一个适配器没有此选项**——这不是一个统一的开关： + - LangChain / LangGraph、Pydantic AI——`capture_content=False` + - LlamaIndex——`capture_messages=False` + - CrewAI——**完全没有内容开关**；它只读取 `session_id` 选项，因此 prompt 和补全内容始终会被记录。 - `instrument()` 会忽略适配器不支持的选项，因此传入错误的名称不会报错，也不会有任何效果。 - - 一开始就不要将密钥传给 `input=`。 + `instrument()` 会丢弃适配器不读取的选项，因此传入错误的名称不会报错，也不会有任何效果。 + - 一开始就不要将敏感信息传给 `input=`。 - `collector.redact` 是纵深防御，而不是上述两者的替代方案。 + `collector.redact` 不能替代上述两种方式。 - **spool 目录为空是正常状态。** 不要用它来确认投递情况。 + **spool 目录为空才是健康状态。** 不要用它来检查事件是否已送达。 -守护进程在发送后的毫秒内删除每个批次文件，因此 `ls` 会与收集器竞争，只能看到您发送内容的一小部分——与 SDK 什么都没记录的情况无法区分。 +守护进程在发送批次后的毫秒内就会将其删除，因此 `ls` 命令会与收集器产生竞争，只能看到你实际发出内容的一小部分——与 SDK 什么都没记录的情况无法区分。 -要确认事件是否真正送达，请查看 dashboard。要观察 spool 填充过程，请先停止守护进程。 +要确认事件已成功落地，请检查 dashboard。要观察 spool 的填充过程，请先停止守护进程。 - + -每个回调都运行在一个包装器内，该包装器的唯一职责是重新抛出异常，因此您的调用恰好位于一个 `try` 中，SDK 所做的一切都在其外部。 +每个回调都运行在一个包装器内，其唯一职责是重新抛出异常，因此你的调用恰好位于一个 `try` 中，SDK 的所有操作都在其外部进行。 -| 发生情况 | 结果 | +| 发生了什么 | 结果 | | --- | --- | -| 某个 hook 抛出异常 | 记录一次并附带 traceback，您的调用不受影响 | -| 同一个 hook 抛出三次 | 该 hook 在进程剩余时间内被禁用，并记录一行错误 | -| 设置了 `FAILPROOFAI_SDK_STRICT=1` | 异常会被重新抛出 | -| 框架版本超出测试范围 | 警告一次，但仍继续接入 | -| 某个功能缺失 | 仅禁用该 hook，不影响整个适配器 | +| 一个 hook 抛出异常 | 记录一次带有堆栈跟踪的日志。你的调用不受影响 | +| 同一个 hook 抛出三次异常 | 该 hook 在进程剩余生命周期内被禁用，记录一行错误 | +| 设置了 `FAILPROOFAI_SDK_STRICT=1` | 异常被重新抛出 | +| 框架版本不在测试范围内 | 发出一次警告，仍然进行埋点 | +| 单个功能缺失 | 仅禁用该 hook，不影响整个适配器 | -默认行为在生产环境中是正确的，但在调试时是错误的，因为它只能证明"没有崩溃"。设置 `FAILPROOFAI_SDK_STRICT=1` 可让被吞掉的失败变得明显。 +默认行为在生产环境中是正确的，在调试时是错误的，因为它只能证明"没有崩溃"。设置 `FAILPROOFAI_SDK_STRICT=1` 可让被吞掉的失败变得明显。 @@ -699,24 +701,24 @@ Spool 是安全保障：您的 agent 永远不会因网络而阻塞，Cloud 故 ## 常见问题 - - 开始事件没有对应的结束事件：`model_request` 没有 `model_response`，或 `tool_use` 没有 `tool_result`。请使用作用域，即使主体代码抛出异常也能保证事件对完整。如果直接调用事件方法，请使用 `try` 和 `finally`。 + + 某个开启事件没有对应的关闭事件：`model_request` 没有 `model_response`，或 `tool_use` 没有 `tool_result`。请使用作用域，它们能保证即使函数体抛出异常也会发出事件对。如果直接调用事件方法，请使用 `try` 和 `finally`。 - 持续时间由对应的开始事件起计算，因此在 `tool_result`、`hook_completed`、`agent_resume` 和 `human_input` 上传入该参数会被拒绝。在 `model_response` 上可以接受，因为只有您才知道真实的提供商延迟，且必须为整数。 + 持续时间由对应的开启事件测量，因此在 `tool_result`、`hook_completed`、`agent_resume` 和 `human_input` 上传入 `duration_ms` 会被拒绝。在 `model_response` 上可以接受，因为只有你知道真实的提供商延迟，且必须是整数。 - - 该线程从未继承上下文。请用 `failproofai_sdk.propagate()` 包裹可调用对象。参见[线程与异步](#threads-and-async)。 + + 该线程从未继承上下文。请将可调用对象包裹在 `failproofai_sdk.propagate()` 中。参见[线程与异步](#threads-and-async)。 - - 额外字段最后合并，因此与真实字段（如 `model` 或 `outcome`）同名的字段会覆盖它并改变存储列。请为您的字段加上命名空间；适配器使用 `fw_` 前缀。 + + 额外字段最后合并，因此与真实字段（如 `model` 或 `outcome`）同名的字段会覆盖它，改变存储的列值。请为你的字段加命名空间前缀；适配器使用 `fw_` 前缀。 - - `agent_id` 是低基数维度，而您将运行 id 放入了其中。请使用角色或节点名称，将真实 id 放在 payload 字段中。 + + `agent_id` 是低基数维度，而你在其中放入了运行 id。请使用角色或节点名称，将真实 id 放入载荷字段。 @@ -724,10 +726,10 @@ Spool 是安全保障：您的 agent 永远不会因网络而阻塞，Cloud 故 - 事件对、id、session 生命周期与投递机制。 + 事件对、id、session 生命周期与事件投递。 - - 在刚捕获的 session 中跟踪因果关系。 + + 在刚捕获的 session 中沿因果链路追溯。 LangGraph、CrewAI、LlamaIndex 和 Pydantic AI。 diff --git a/docs/zh/start/quickstart.mdx b/docs/zh/start/quickstart.mdx index 6b345280..72695799 100644 --- a/docs/zh/start/quickstart.mdx +++ b/docs/zh/start/quickstart.mdx @@ -1,39 +1,39 @@ --- title: "快速开始" -description: "捕获一次 Agent 会话，发现故障，并开始预防它。" +description: "捕获一次 agent 会话，发现故障，并开始预防。" icon: "zap" --- -本快速开始指南将帮助你完成：让一台机器上报会话、运行审计，并部署一个策略。你可以使用技能包来完成 Failproof 的配置，也可以按照手动步骤操作。 +本快速开始指南将帮助你完成：让一台机器开始上报会话、执行审计、并部署策略。你可以使用技能来设置 Failproof AI，或按照手动步骤操作。 -**选择适合你的路径：** 如果你的 Agent 运行在 12 个受支持的[执行环境](/zh/reference/harnesses)之一中——例如编码 CLI，或 Hermes、OpenClaw 等网关——请按照以下步骤操作；你需要 Node.js 20.9 或更高版本。如果你的 Agent 没有执行环境，请使用 [Python SDK](/zh/reference/custom-agents) 对其进行埋点以实现追踪和审计，然后从[运行你的首次故障检查](/zh/start/first-audit)处继续；该路径下的执行能力需要在你的运行时中添加一个 hook。 +**你属于哪种情况？** 如果你的 agent 运行在 12 种受支持的 [harnesses](/zh/reference/harnesses) 之一中——例如编码 CLI，或者 Hermes、OpenClaw 这类网关——请按照以下步骤操作；你需要 Node.js 20.9 或更高版本。如果你的 agent 没有 harness，请使用 [Python SDK](/zh/reference/custom-agents) 对其进行插桩以支持追踪和审计，然后从[运行你的第一次故障检查](/zh/start/first-audit)处继续；该路径上的强制执行需要在你的运行时中添加一个 hook。 - + - + ```bash npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - 你的 Agent 会检查项目、选择相关集成、执行配置并验证会话是否正常到达。如需了解各个技能及高级安装选项，请参阅 [FailproofAI 技能仓库](https://github.com/FailproofAI/skills)。 + 你的 agent 会检查项目、选择相关的集成方式、执行配置，并验证会话是否正常到达。请查看 [FailproofAI 技能仓库](https://github.com/FailproofAI/skills) 了解各项技能和高级安装选项。 - ## 开始之前 + ## 开始前的准备 1. 打开 [Failproof AI 控制台](https://app.befailproof.ai)，创建账号或使用工作邮箱登录。 -2. 进入 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥。 -3. 复制一次性密钥，并将其保存到目标机器上： +2. 前往 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥。 +3. 复制一次性密钥，然后在目标机器的 shell 中读取它。`read -s` 会在不回显的提示符下读取，因此密钥不会出现在命令中： ```bash -export FAILPROOFAI_KEY="" +read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY ``` ## 安装 @@ -42,12 +42,18 @@ export FAILPROOFAI_KEY="" ```bash npm install -g failproofai - failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" + FAILPROOFAI_CLOUD_TOKEN="$FAILPROOFAI_KEY" failproofai config ``` - 默认情况下会发送会话记录。添加 `--no-transcripts` 可在不包含记录内容的情况下上报 hook 活动和策略决策。 + 这一条命令完成全部配置：安装本地守护进程（需要 root 权限，仅一次）、将 hook 接入所有检测到的 agent CLI，并将本机连接到云端。通过环境变量而非 `--token` 传入密钥，可以避免密钥出现在 `ps` 输出中（机器上的所有用户都能读取命令参数）。但这并不能防止密钥出现在 shell 历史记录中——使用 `read -s` 读取才能做到这一点。在 CI 环境中，请以掩码密钥的方式注入，并关闭 shell 追踪（`set -x`），否则追踪日志会将其打印出来。 - 如果这台机器上已有 Agent 历史记录，可预览并导入最近七天的数据，然后等待传输完成。若是全新机器，请跳过此步骤。 + 默认情况下会发送会话记录。添加 `--no-transcripts` 可仅上报 hook 活动和策略决策，而不包含记录内容。 + + + 不要在此处使用 `failproofai config --connect `。该标志用于注册一台**已经**完成配置的机器，执行后立即返回——不启动守护进程，也不安装 hook——因此该机器会出现在云端，但不会采集或执行任何内容。 + + + 如果此机器上已有 agent 历史记录，可预览并导入最近七天的数据，然后等待传输完成。新机器可跳过此步骤。 ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +61,41 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - 在 Failproof AI 中打开 **Sessions**，选择一个已导入的会话。 + 在 Failproof AI 中打开 **Sessions** 并选择一个已导入的会话。 - - 此步骤会将 Failproof AI 附加到你的执行环境，并安装 39 个内置策略。在 Failproof AI 审计你的会话并为你的 Agent 编写策略之前，你可以先通过这些策略查看本地策略决策并试用执行功能。 - - 你可以让安装程序自动检测你的执行环境，也可以明确指定一个。12 个执行环境都是有效的 `--cli` 参数值——`claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose`。 + + 上一步已自动接入所有检测到的 agent CLI。如需为某个 harness 单独重新运行，或添加后续安装的 harness，可通过以下命令显式操作。12 种 harness 均可作为 `--cli` 的有效值——`claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose`。 ```bash failproofai policies --install --cli claude --scope user # 编码 CLI failproofai policies --install --cli hermes --scope user # Slack/Telegram 网关 ``` - 在工具调用执行前拦截的功能已在全部 12 个执行环境中验证。轮次结束门控已在 8 个环境中验证——各执行环境的详细矩阵请参阅[执行能力](/zh/reference/harnesses#enforcement-capability)。 + 在工具调用执行前拦截的功能已在全部 12 种 harness 上验证。轮次结束门控已在 8 种上验证——请参阅[强制执行能力](/zh/reference/harnesses#enforcement-capability)查看各 harness 的详细矩阵。 + + + 接入 hook 并不会启用任何策略。配置过程故意不做任何选择——这个决定由你来做——请选取一个策略包： + + ```bash + failproofai policies add FailproofAI/policies + ``` + + 该策略包从其 GitHub Release 中获取，经过校验和验证，并固定到解析出的确切标签。它包含 38 条策略，并默认开启其中 10 条——这些策略在 manifest 中被标记为可无人值守启用。使用它们可以查看本地策略决策、在 Failproof AI 审计你的会话并为你的 agent 编写策略之前试用强制执行功能。 + + 在采用策略包之前，可使用 `failproofai policies show /` 查看其内容；如需只采用其中一部分，请参阅[策略包](/zh/policies/packs)。 + + 在此步骤运行之前，唯一生效的策略是 `block-failproofai-commands`——这是一个始终开启的守卫，用于阻止 agent 关闭 Failproof AI。`failproofai policies` 会列出当前已启用的策略。 - 按照[运行你的首次故障检查](/zh/start/first-audit)进行操作。请使用具体的目标，例如"查找 Agent 在未改变方法的情况下重试失败工具的会话"。 + 按照[运行你的第一次故障检查](/zh/start/first-audit)操作。使用具体的目标，例如"查找 agent 在未改变方法的情况下重试失败工具的会话"。 - 按照[使用策略预防首次故障](/zh/start/first-policy)进行操作。先以观察模式启动，检查匹配结果，然后对审查后的版本执行强制策略。 + 按照[使用策略预防你的第一次故障](/zh/start/first-policy)操作。先在观察模式下运行，检查匹配结果，然后对审查后的版本启用强制执行。 - 运行 `failproofai config --status`。配置健康时，该命令会报告云连接状态、守护进程状态，以及执行功能是否已暂停。 + 运行 `failproofai config --status`。配置正常时，会输出云端连接状态、守护进程状态，以及强制执行是否已暂停。 \ No newline at end of file diff --git a/docs/zh/start/setup.mdx b/docs/zh/start/setup.mdx index 006f8b8c..539b2989 100644 --- a/docs/zh/start/setup.mdx +++ b/docs/zh/start/setup.mdx @@ -1,68 +1,89 @@ --- -title: "选择您的配置方式" -description: "选择本地执行、Failproof AI Cloud 或企业部署。" +title: "选择您的设置方式" +description: "选择本地强制执行、Failproof AI Cloud 或企业部署。" icon: "waypoints" --- - - 在机器上安装 hooks 和策略。当您需要立即设置防护栏而无需将会话数据发送至 Cloud 时，请使用此方式。 + + 无需 Cloud 密钥即可配置机器并应用策略包。当您需要立即设置护栏且不希望将会话数据发送到 Cloud 时，请使用此方式。 - 添加集中式会话管理、审计、在线评估、仪表盘、告警以及机群策略部署。 + 添加集中式会话管理、审计、在线评估、仪表盘、告警以及机群策略部署功能。 - 使用组织控制、范围密钥、私有基础设施以及特定部署的安全要求。 + 使用组织级控制、作用域密钥、私有基础设施以及特定部署的安全要求。 -## 推荐的生产环境路径 +## 本地强制执行 -1. 连接一台已启用会话记录捕获的非生产环境机器。 +在不使用密钥的情况下运行 `failproofai config`，然后通过 `failproofai policies add FailproofAI/policies` 应用策略包。在终端中，当设置向导询问是否连接到 Cloud 时，选择 **Not now — stay local**；若没有终端且未设置 `FAILPROOFAI_CLOUD_TOKEN`，系统将自动保持本地模式。守护进程和钩子在本机上执行策略，不会向 Cloud 发送任何会话数据。如需稍后连接，请按照以下步骤操作。 + +## 推荐的生产环境部署路径 + +1. 在非生产环境机器上启用会话记录功能并完成连接。 2. 在 Cloud 中验证会话和评估结果。 -3. 针对已知故障模式创建审计。 +3. 针对已知的失效场景创建审计。 4. 以观察模式部署第一条策略。 -5. 在审查匹配结果和误报后，扩展至生产环境。 +5. 在审查匹配结果和误报之后，再扩展至生产环境。 -## 将机器连接至 Cloud +## 将机器连接到 Cloud 1. 前往 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥。 2. 将一次性密钥复制到目标机器。 - 3. 运行 CLI 连接命令后，前往 **Admin → enforcement** 确认机器已出现在列表中。 + 3. 运行 CLI 连接命令后，前往 **Admin → enforcement** 确认该机器已出现在列表中。 4. 前往 **Observe → Events** 确认其第一个事件已到达。 - 密钥抽屉显示已连接机器所需的两项授权：事件摄取和策略分发。 + 密钥面板显示已连接机器所需的两项授权：事件摄取和策略下发。 - ![用于授予事件摄取和策略分发权限的新 API 密钥抽屉。](/images/dashboard/key-create.png) + ![用于授予事件摄取和策略下发权限的新 API 密钥面板。](/images/dashboard/key-create.png) - 连接后，该机器应出现在执行列表中，并显示其期望和已报告的策略状态。 + 连接完成后，该机器应出现在强制执行列表中，并显示其期望状态和已报告的策略状态。 - ![执行机群视图，展开已注册的机器以显示其期望策略状态和部署状态。](/images/dashboard/enforcement-fleet.png) + ![强制执行机群视图，展开后显示已注册机器的期望策略状态和部署状态。](/images/dashboard/enforcement-fleet.png) - 第一个到达的事件确认守护进程可以独立于策略部署向 Cloud 传输数据。 + 第一个到达的事件确认守护进程可以独立于策略部署向 Cloud 传送数据。 - ![显示最近代理、模型和工具事件的实时事件流。](/images/dashboard/events-stream-current.png) + ![实时事件流，显示近期的 Agent、模型和工具事件。](/images/dashboard/events-stream-current.png) - 仅在机器及其第一个事件均可见后，再继续后续操作。 + 仅在机器及其第一个事件均可见后，才继续后续操作。 + 将一次性密钥读取到 Shell 中。`read -s` 会在不回显的提示符下接收输入，因此密钥不会出现在命令或 Shell 历史记录中： + ```bash - failproofai config --connect https://app.befailproof.ai \ - --token "$FAILPROOFAI_KEY" \ - --machine-label checkout-runner-01 + read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN + ``` + + 然后配置机器、选择策略并为其命名： - failproofai policies --install --cli claude --scope user + ```bash + failproofai config + + failproofai policies add FailproofAI/policies + failproofai config --machine-label checkout-runner-01 failproofai config --status ``` - 当会话记录内容必须保留在本地时，请添加 `--no-transcripts`。 + `failproofai config` 会完成全部设置——守护进程、为所有检测到的 Agent CLI 安装钩子以及 Cloud 连接——但不会选择任何策略，这正是第二条命令的用途。 + + 标签需在连接**之后**设置，而非在连接过程中：`failproofai config --machine-label ` 用于重命名已连接的机器，若机器尚未连接，该命令不会执行任何操作，仅会提示说明。 + + 当会话内容必须保留在本地时，请添加 `--no-transcripts` 参数。 + + 在 CI 环境中，请从密钥存储中设置 `FAILPROOFAI_CLOUD_TOKEN`，而非使用 `read -s`，并关闭 Shell 追踪（`set -x`），否则追踪日志会打印出密钥。 + + + 对于**已完成**设置的机器，`failproofai config --connect ` 仅执行注册操作。请勿在首次安装时使用该命令：它会在守护进程或任何钩子就位之前返回，导致机器虽在 Cloud 中显示，但实际上不收集数据也不执行任何策略。 + -连接至 Cloud 会独立验证事件摄取和策略分发能力。因此，一个密钥可能有效但缺少某项必需权限。使用 `failproofai config --status` 查看已配置的功能。 +连接到 Cloud 会独立验证事件摄取和策略下发能力。因此，一个密钥可能有效，但缺少其中一项所需权限。使用 `failproofai config --status` 查看当前已配置的功能。 - Cloud 配置仅在相关功能验证成功后才会写入本地凭据。验证失败不会导致机器在未实际连接时显示为已连接状态。 + Cloud 设置仅在相关功能验证成功后才会写入本地凭证。验证失败不会导致机器在实际未连接的情况下显示为已连接状态。 \ No newline at end of file From 1d712d31a116f15502e977580efd7ac5a46584bf Mon Sep 17 00:00:00 2001 From: NiveditJain Date: Tue, 15 Sep 2026 11:01:44 +0530 Subject: [PATCH 3/8] docs: carry #791's redaction change into the custom-agents translations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Sep 12 run retranslated start/integrations/custom-agents.mdx from scratch in every locale because #791 changed one section of the English. The output was worse than what it replaced: Arabic rendered "daemon" as الشيطان ("the devil") twelve times and turned both 10,000 limits into 000, Turkish and Vietnamese garbled the adapter note, and CodeRabbit flagged ten more defects across nine locales. The Sep 14 run then overwrote those files with main's versions anyway, so every locale still told readers that `collector.redact` never sees SDK events. Keep main's translations and apply only what #791 changed, by hand: the Warning, the paragraph after it, the redaction table, the paragraph that replaced the two "this is deliberate" paragraphs, and the Tip's closing line. Fix what the review turned up in these same files: - The "manual and automatic compose" note said the adapter becomes the PARENT of the hand-written agent in ar, de, fr, hi, it, ru, tr and vi. The SDK sets the adapter agent's parent_id to the manual agent (integrations/_core.py), so it is a child. - ar described `done` as "nothing is open, and something failed". - The tr description now uses "enstrümante", the term the page's own headings use. - The ru and vi dedup_key rows now say a retried batch collapses instead of duplicating, and a stray 看着 in the ru delivery section is gone. - "See Threads and async" linked #threads-and-async, a slug no translated heading produces. It now targets each locale's own heading, verified with `mintlify broken-links --check-anchors`. Hebrew is rewritten in full in its own commit. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NrdeSVKcfqXd1H2BwP45Ad --- docs/ar/start/integrations/custom-agents.mdx | 24 ++++++++--------- docs/de/start/integrations/custom-agents.mdx | 20 +++++++------- docs/es/start/integrations/custom-agents.mdx | 20 +++++++------- docs/fr/start/integrations/custom-agents.mdx | 22 +++++++--------- docs/hi/start/integrations/custom-agents.mdx | 22 +++++++--------- docs/it/start/integrations/custom-agents.mdx | 20 +++++++------- docs/ja/start/integrations/custom-agents.mdx | 20 +++++++------- docs/ko/start/integrations/custom-agents.mdx | 20 +++++++------- .../start/integrations/custom-agents.mdx | 20 +++++++------- docs/ru/start/integrations/custom-agents.mdx | 26 +++++++++---------- docs/tr/start/integrations/custom-agents.mdx | 24 ++++++++--------- docs/vi/start/integrations/custom-agents.mdx | 24 ++++++++--------- docs/zh/start/integrations/custom-agents.mdx | 20 +++++++------- 13 files changed, 128 insertions(+), 154 deletions(-) diff --git a/docs/ar/start/integrations/custom-agents.mdx b/docs/ar/start/integrations/custom-agents.mdx index 6e5db3c2..fe07d3aa 100644 --- a/docs/ar/start/integrations/custom-agents.mdx +++ b/docs/ar/start/integrations/custom-agents.mdx @@ -268,7 +268,7 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **اليدوي والتلقائي يتكونان.** يدخل محول يعمل داخل نطاق مكتوب يدوياً تلك الجلسة والآباء إلى ذلك الوكيل، حتى تحصل على شجرة واحدة بدلاً من شجرتين — مفيد عندما تدرج إطار عمل بنفسك إلى جانب واحد مدعوم. + **اليدوي والتلقائي يعملان معاً.** المحوّل الذي يعمل داخل نطاق مكتوب يدوياً ينضم إلى تلك الجلسة ويصبح ابناً لذلك الوكيل، فتحصل على شجرة واحدة بدلاً من شجرتين — وهذا مفيد عندما تدرج إطار عمل بنفسك إلى جانب إطار عمل مدعوم. @@ -405,7 +405,7 @@ flowchart LR | `ongoing` | لا يزال امتداد واحد على الأقل مفتوحاً | | `paused` | `agent_pause` بدون `agent_resume` مطابقة | | `error` | لا شيء مفتوح، وحدث واحد على الأقل فشل | -| `done` | لا شيء مفتوح، وشيء فشل | +| `done` | لا شيء مفتوح، ولم يفشل أي شيء | لذلك تنتهي الجلسة عندما يتم إغلاق كل زوج. يصدر المحولات `agent_end` لك، وعند الهدم يغلقون أي شيء لا يزال مفتوحاً ويوقعونه كغير كامل — يستقر التشغيل المتعطل كـ `done` بفجوة مرئية بدلاً من التعليق. @@ -641,20 +641,18 @@ flowchart LR يختار المراقب فقط `.jsonl`، لذا لا يمكن أبداً قراءة ملف نصف مكتوب. الجذع يحمل طابع زمني، معرف العملية ورقم التسلسل، لذا لا يمكن لعمليتين تنظيف في نفس الميلي ثانية أن تصطدما. تُغطى القائمة بـ 10,000 حدث؛ بعد ذلك تسقط الأقدم وتسجل. - **`collector.redact` لا ينطبق على أحداث SDK الخاصة بك.** لا يراها أبداً. + **القيمة الافتراضية لـ `collector.redact` هي `minimal` لأحداث SDK أيضاً.** ينقّح SDK البيانات الحساسة قبل كتابة الدفعة على القرص، ثم يكرر المراقب المرور الحتمي نفسه قبل الرفع، فتبقى الدفعات الصادرة عن إصدارات SDK الأقدم محمية كذلك. -المراقب **ينقل** دفعاتك. إنه لا يفتحها أو يعيد كتابتها. +يقرأ المراقب كل دفعة ويطبّق التنقيح في الذاكرة قبل الرفع، ولا يعيد كتابة ملف spool الذي قرأه. -| الأحداث | مكتوب بواسطة | معاد بواسطة `collector.redact`؟ | +| الأحداث | مكتوب بواسطة | أين يعمل التنقيح الأدنى | | --- | --- | --- | -| نصوص جلسة CLI | المراقب | نعم | -| نشاط الخطاف | المراقب | نعم | -| **كل ما يصدره SDK** | **عمليتك** | **لا** | +| نصوص جلسة CLI | المراقب | قبل أن يكتب المراقب الدفعة | +| نشاط الخطاف | المراقب | قبل أن يكتب المراقب الدفعة | +| **كل ما يصدره SDK** | **عمليتك** | **قبل أن يكتب SDK الدفعة، ومرة أخرى قبل أن يرفعها المراقب** | -التعديل يعمل حيث **يكتب** المراقب أحداثه الخاصة — وليس حيث تُنقل الدفعات. لذا طلب أو حجة أداة تحمل مفتاح API لا تزال تحمله عند الوصول. - -هذا مقصود. هذه هي نداءات الإدراج الخاصة بك، وإعادة الكتابة في الحركة ستعني أن الأحداث التي تستقبلها ليست الأحداث التي أصدرتها. +اضبط `collector.redact` على `off` فقط عندما يكون الاحتفاظ بالحمولات كما هي متطلباً صريحاً؛ فكلٌّ من SDK والمراقب يلتزم بهذا الإعداد. يلتقط التنقيح الأدنى مفاتيح API الشائعة ورموز bearer وJWT وتعيينات الأسرار، لكنه لا يستطيع التعرّف على أي نص حساس عشوائي. **أنت تتحكم في الحمولات من المصدر، في مكانين:** @@ -667,7 +665,7 @@ flowchart LR `instrument()` يسقط الخيارات التي لا يقرأها محول، لذا تمرير الاسم الخاطئ لا يرفع شيء ولا يغير شيء. - لا تسلم السر إلى `input=` في المقام الأول. - `collector.redact` ليس بديلاً عن أي منهما. + `collector.redact` دفاعٌ في العمق، وليس بديلاً عن أيٍّ منهما. @@ -710,7 +708,7 @@ flowchart LR - الخيط لم يرث السياق أبداً. غلف الدالة في `failproofai_sdk.propagate()`. انظر [الخيوط و async](#threads-and-async). + الخيط لم يرث السياق أبداً. غلف الدالة في `failproofai_sdk.propagate()`. انظر [الخيوط و async](#الخيوط-و-async). diff --git a/docs/de/start/integrations/custom-agents.mdx b/docs/de/start/integrations/custom-agents.mdx index 824fb42f..87d7f33d 100644 --- a/docs/de/start/integrations/custom-agents.mdx +++ b/docs/de/start/integrations/custom-agents.mdx @@ -270,7 +270,7 @@ Jedes Agent-Framework gibt dir dieselben drei Nahtpunkte. Mappe sie und du hast - **Manuell und automatisch komponieren.** Ein Adapter, der innerhalb eines manuell erstellten Scopes läuft, schließt sich dieser Session an und wird dem Agenten als übergeordnet zugeordnet – du bekommst einen Baum statt zwei. Das ist nützlich, wenn du ein Framework selbst instrumentierst, das neben einem unterstützten läuft. + **Manuell und automatisch komponieren.** Ein Adapter, der innerhalb eines manuell erstellten Scopes läuft, schließt sich dieser Session an und wird diesem Agenten untergeordnet – du bekommst einen Baum statt zwei. Das ist nützlich, wenn du ein Framework selbst instrumentierst, das neben einem unterstützten läuft. @@ -643,20 +643,18 @@ Jeder Flush schreibt eine Batch-Datei: zuerst `.tmp`, dann `fsync`, dann ein ato Der Daemon liest nur `.jsonl`, kann also nie eine halb geschriebene Datei lesen. Der Dateiname trägt Timestamp, Prozess-ID und Sequenznummer, sodass zwei Prozesse, die in derselben Millisekunde flushen, nicht kollidieren können. Die Queue ist auf 10.000 Events begrenzt; darüber hinaus werden die ältesten gelöscht und geloggt. - **`collector.redact` gilt nicht für deine SDK-Events.** Es sieht sie nie. + **`collector.redact` steht auch für SDK-Events standardmäßig auf `minimal`.** Das SDK bereinigt die Daten, bevor es einen Batch auf die Disk schreibt, und der Daemon wiederholt denselben deterministischen Durchlauf vor dem Upload, sodass auch Batches älterer SDKs geschützt sind. -Der Daemon **versendet** deine Batches. Er öffnet oder überschreibt sie nicht. +Der Daemon liest jeden Batch und wendet die Bereinigung vor dem Upload im Arbeitsspeicher an. Die gelesene Spool-Datei schreibt er nicht um. -| Events | Geschrieben von | Durch `collector.redact` bereinigt? | +| Events | Geschrieben von | Wo die minimale Bereinigung läuft | | --- | --- | --- | -| CLI-Session-Transkripte | Dem Daemon | Ja | -| Hook-Aktivität | Dem Daemon | Ja | -| **Alles, was das SDK sendet** | **Deinem Prozess** | **Nein** | +| CLI-Session-Transkripte | Dem Daemon | Bevor der Daemon den Batch schreibt | +| Hook-Aktivität | Dem Daemon | Bevor der Daemon den Batch schreibt | +| **Alles, was das SDK sendet** | **Deinem Prozess** | **Bevor das SDK den Batch schreibt, und erneut vor dem Upload durch den Daemon** | -Bereinigung läuft dort, wo der Daemon seine *eigenen* Events schreibt – nicht wo Batches *versendet* werden. Ein Prompt oder ein Tool-Argument mit einem API-Key enthält ihn also noch beim Ankommen. - -Das ist beabsichtigt. Das sind deine eigenen Instrumentierungsaufrufe, und sie im Transit umzuschreiben würde bedeuten, dass die Events, die du empfängst, nicht die Events sind, die du gesendet hast. +Setze `collector.redact` nur dann auf `off`, wenn unveränderte Payloads ausdrücklich gefordert sind; SDK und Daemon halten sich beide an diese Einstellung. Die minimale Bereinigung erkennt gängige API-Keys, Bearer-Tokens, JWTs und Zuweisungen von Secrets. Beliebigen sensiblen Fließtext kann sie nicht erkennen. **Du kontrollierst Payloads an der Quelle, an zwei Stellen:** @@ -669,7 +667,7 @@ Das ist beabsichtigt. Das sind deine eigenen Instrumentierungsaufrufe, und sie i `instrument()` ignoriert Optionen, die ein Adapter nicht liest, sodass das Übergeben des falschen Namens nichts auslöst und nichts ändert. - Gib das Geheimnis von vornherein nicht an `input=` weiter. - `collector.redact` ist kein Ersatz für beides. + `collector.redact` ist ein Baustein der gestaffelten Verteidigung (Defense in Depth), aber kein Ersatz für beides. diff --git a/docs/es/start/integrations/custom-agents.mdx b/docs/es/start/integrations/custom-agents.mdx index 09d79215..7c5b2b6f 100644 --- a/docs/es/start/integrations/custom-agents.mdx +++ b/docs/es/start/integrations/custom-agents.mdx @@ -643,20 +643,18 @@ Cada flush escribe un archivo de lote, primero como `.tmp`, luego `fsync`, luego El daemon solo recoge `.jsonl`, por lo que nunca puede leer un archivo a medio escribir. El nombre lleva un timestamp, id de proceso y número de secuencia, por lo que dos procesos que hagan flush en el mismo milisegundo no colisionan. La cola tiene un límite de 10.000 eventos; a partir de ahí descarta los más antiguos y lo registra en el log. - **`collector.redact` no se aplica a los eventos de tu SDK.** Nunca los ve. + **`collector.redact` también usa `minimal` por defecto para los eventos del SDK.** El SDK enmascara los datos sensibles antes de escribir un lote en disco, y el daemon repite la misma pasada determinista antes de la subida, de modo que los lotes de SDK anteriores también quedan protegidos. -El daemon **envía** tus lotes. No los abre ni los reescribe. +El daemon lee cada lote y aplica el enmascaramiento en memoria antes de la subida. No reescribe el archivo de spool que leyó. -| Eventos | Escritos por | ¿Redactados por `collector.redact`? | +| Eventos | Escritos por | Dónde se aplica el enmascaramiento mínimo | | --- | --- | --- | -| Transcripciones de sesión CLI | El daemon | Sí | -| Actividad de hooks | El daemon | Sí | -| **Todo lo que emite el SDK** | **Tu proceso** | **No** | +| Transcripciones de sesión CLI | El daemon | Antes de que el daemon escriba el lote | +| Actividad de hooks | El daemon | Antes de que el daemon escriba el lote | +| **Todo lo que emite el SDK** | **Tu proceso** | **Antes de que el SDK escriba el lote y de nuevo antes de que el daemon lo suba** | -La redacción se ejecuta donde el daemon *escribe* sus propios eventos — no donde se *envían* los lotes. Así que un prompt o un argumento de herramienta que contenga una clave API la conservará al llegar. - -Esto es deliberado. Estas son tus propias llamadas de instrumentación, y reescribirlas en tránsito significaría que los eventos que recibes no son los que emitiste. +Configura `collector.redact` en `off` solo cuando los payloads literales sean un requisito explícito; tanto el SDK como el daemon respetan esa configuración. El enmascaramiento mínimo detecta las claves de API habituales, los bearer tokens, los JWT y las asignaciones de secretos. No puede identificar cualquier texto sensible arbitrario. **Controlas los payloads en el origen, en dos lugares:** @@ -669,7 +667,7 @@ Esto es deliberado. Estas son tus propias llamadas de instrumentación, y reescr `instrument()` descarta las opciones que un adaptador no lee, por lo que pasar el nombre incorrecto no lanza nada ni cambia nada. - No pases el secreto a `input=` desde el principio. - `collector.redact` no es un sustituto de ninguna de las dos opciones. + `collector.redact` es defensa en profundidad, no un sustituto de ninguna de las dos opciones. @@ -712,7 +710,7 @@ El comportamiento por defecto es correcto en producción e incorrecto al depurar - El hilo nunca heredó el contexto. Envuelve el callable en `failproofai_sdk.propagate()`. Consulta [Hilos y async](#threads-and-async). + El hilo nunca heredó el contexto. Envuelve el callable en `failproofai_sdk.propagate()`. Consulta [Hilos y async](#hilos-y-async). diff --git a/docs/fr/start/integrations/custom-agents.mdx b/docs/fr/start/integrations/custom-agents.mdx index 0fd0f1cd..74acc334 100644 --- a/docs/fr/start/integrations/custom-agents.mdx +++ b/docs/fr/start/integrations/custom-agents.mdx @@ -268,7 +268,7 @@ Tout framework d'agent vous expose les mêmes trois points d'insertion. Mappez-l - **Manuel et automatique se combinent.** Un adaptateur s'exécutant dans une portée écrite à la main rejoint cette session et se parenté à cet agent, vous obtenez donc un seul arbre plutôt que deux — utile quand vous instrumentez vous-même un framework aux côtés d'un framework supporté. + **Manuel et automatique se combinent.** Un adaptateur s'exécutant dans une portée écrite à la main rejoint cette session et devient enfant de cet agent, vous obtenez donc un seul arbre plutôt que deux — utile quand vous instrumentez vous-même un framework aux côtés d'un framework supporté. @@ -641,20 +641,18 @@ Chaque flush écrit un fichier batch, `.tmp` d'abord, puis `fsync`, puis un reno Le daemon ne prend que les `.jsonl`, il ne peut donc jamais lire un fichier à moitié écrit. Le nom de fichier porte un timestamp, un id de processus et un numéro de séquence, donc deux processus flushing dans la même milliseconde ne peuvent pas entrer en collision. La file d'attente est limitée à 10 000 événements ; au-delà, elle supprime les plus anciens et enregistre un log. - **`collector.redact` ne s'applique pas à vos événements SDK.** Il ne les voit jamais. + **`collector.redact` vaut aussi `minimal` par défaut pour les événements SDK.** Le SDK masque les données sensibles avant d'écrire un batch sur le disque, et le daemon répète le même passage déterministe avant l'envoi, si bien que les batches produits par des SDK plus anciens sont eux aussi protégés. -Le daemon **envoie** vos batches. Il ne les ouvre ni ne les réécrit. +Le daemon lit chaque batch et applique le masquage en mémoire avant l'envoi. Il ne réécrit pas le fichier de spool qu'il a lu. -| Événements | Écrits par | Traités par `collector.redact` ? | +| Événements | Écrits par | Où s'exécute le masquage minimal | | --- | --- | --- | -| Transcriptions de sessions CLI | Le daemon | Oui | -| Activité des hooks | Le daemon | Oui | -| **Tout ce que le SDK émet** | **Votre processus** | **Non** | +| Transcriptions de sessions CLI | Le daemon | Avant que le daemon écrive le batch | +| Activité des hooks | Le daemon | Avant que le daemon écrive le batch | +| **Tout ce que le SDK émet** | **Votre processus** | **Avant que le SDK écrive le batch, puis à nouveau avant l'envoi par le daemon** | -La rédaction s'exécute là où le daemon *écrit* ses propres événements — pas là où les batches sont *envoyés*. Donc un prompt ou un argument d'outil contenant une clé API la conserve à l'arrivée. - -C'est délibéré. Ce sont vos propres appels d'instrumentation, et réécrire les événements en transit signifierait que les événements que vous recevez ne sont pas ceux que vous avez émis. +Ne réglez `collector.redact` sur `off` que si des payloads intacts sont une exigence explicite ; le SDK comme le daemon respectent ce réglage. Le masquage minimal détecte les clés d'API courantes, les bearer tokens, les JWT et les affectations de secrets. Il ne peut pas repérer n'importe quel texte sensible. **Vous contrôlez les payloads à la source, en deux endroits :** @@ -667,7 +665,7 @@ C'est délibéré. Ce sont vos propres appels d'instrumentation, et réécrire l `instrument()` ignore les options qu'un adaptateur ne lit pas, donc passer le mauvais nom ne lève rien et ne change rien. - Ne transmettez pas le secret à `input=` en premier lieu. - `collector.redact` ne remplace ni l'un ni l'autre. + `collector.redact` est une défense en profondeur, pas un substitut à l'une ou l'autre. @@ -710,7 +708,7 @@ Le comportement par défaut est correct en production et problématique lors du - Le thread n'a jamais hérité du contexte. Enveloppez l'appelable dans `failproofai_sdk.propagate()`. Voir [Threads et async](#threads-and-async). + Le thread n'a jamais hérité du contexte. Enveloppez l'appelable dans `failproofai_sdk.propagate()`. Voir [Threads et async](#threads-et-async). diff --git a/docs/hi/start/integrations/custom-agents.mdx b/docs/hi/start/integrations/custom-agents.mdx index 52b1fcc4..3a7a1cb0 100644 --- a/docs/hi/start/integrations/custom-agents.mdx +++ b/docs/hi/start/integrations/custom-agents.mdx @@ -268,7 +268,7 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **मैनुअल और स्वचालित मिश्रित होते हैं।** एक एडेप्टर एक हाथ से लिखे गए स्कोप के अंदर चल रहा है उस सेशन से जुड़ता है और उस एजेंट का माता-पिता बनता है, इसलिए आपको एक पेड़ मिलता है दो के बजाय — उपयोगी जब आप एक फ्रेमवर्क को स्वयं एक समर्थित के साथ इंस्ट्रूमेंट करते हैं। + **मैनुअल और स्वचालित मिश्रित होते हैं।** एक एडेप्टर एक हाथ से लिखे गए स्कोप के अंदर चल रहा है उस सेशन से जुड़ता है और उस एजेंट का चाइल्ड बन जाता है, इसलिए आपको एक पेड़ मिलता है दो के बजाय — उपयोगी जब आप एक फ्रेमवर्क को स्वयं एक समर्थित के साथ इंस्ट्रूमेंट करते हैं। @@ -641,20 +641,18 @@ flowchart LR डेमन केवल `.jsonl` उठाता है, इसलिए यह कभी आधी-लिखी गई फाइल नहीं पढ़ सकता। स्टेम एक टाइमस्टैम्प, प्रक्रिया id और अनुक्रम संख्या ले जाता है, इसलिए दो प्रक्रियाएं एक ही मिलीसेकंड में फ्लश करना संघर्ष नहीं कर सकती हैं। कतार 10,000 ईवेंट पर capped है; इसके बाद यह सबसे पुरानी को बंद करता है और लॉग करता है। - **`collector.redact` आपकी SDK ईवेंट पर लागू नहीं होता है।** यह कभी उन्हें नहीं देखता है। + **SDK ईवेंट के लिए भी `collector.redact` डिफ़ॉल्ट रूप से `minimal` होता है।** SDK किसी बैच को डिस्क पर लिखने से पहले संवेदनशील डेटा हटा देता है, और डेमन अपलोड से पहले वही निर्धारक पास दोहराता है, ताकि पुराने SDK से आए बैच भी सुरक्षित रहें। -डेमन आपकी बैच **भेजता है**। वह उन्हें खोलता या फिर से लिखता नहीं है। +डेमन हर बैच को पढ़ता है और अपलोड से पहले मेमोरी में ही रिडैक्शन लागू करता है। वह पढ़ी गई स्पूल फ़ाइल को दोबारा नहीं लिखता। -| ईवेंट | द्वारा लिखा गया | `collector.redact` से संरक्षित? | +| ईवेंट | द्वारा लिखा गया | न्यूनतम रिडैक्शन कहाँ चलता है | | --- | --- | --- | -| CLI सेशन प्रतिलेख | डेमन | हां | -| हुक गतिविधि | डेमन | हां | -| **SDK जो कुछ भी उत्सर्जित करता है** | **आपकी प्रक्रिया** | **नहीं** | +| CLI सेशन प्रतिलेख | डेमन | डेमन के बैच लिखने से पहले | +| हुक गतिविधि | डेमन | डेमन के बैच लिखने से पहले | +| **SDK जो कुछ भी उत्सर्जित करता है** | **आपकी प्रक्रिया** | **SDK के बैच लिखने से पहले, और डेमन के अपलोड से पहले एक बार फिर** | -संपादन जहां डेमन अपनी स्वयं की ईवेंट **लिखता है** — जहां बैच **भेजे जाते हैं** नहीं। इसलिए एक प्रॉम्प्ट या एक टूल तर्क जिसमें एक API कुंजी होती है अभी भी आगमन पर रखती है। - -यह जानबूझकर है। ये आपके स्वयं के इंस्ट्रूमेंटेशन कॉल हैं, और पारगमन में उन्हें फिर से लिखने का अर्थ होगा कि आप जो ईवेंट प्राप्त करते हैं वे ईवेंट नहीं हैं जो आपने उत्सर्जित किए हैं। +`collector.redact` को `off` पर तभी सेट करें जब बिना बदले पेलोड स्पष्ट रूप से ज़रूरी हों; SDK और डेमन दोनों इस सेटिंग का पालन करते हैं। न्यूनतम रिडैक्शन आम API कुंजियों, bearer टोकन, JWT और सीक्रेट असाइनमेंट को पकड़ लेता है। यह हर तरह के संवेदनशील टेक्स्ट को नहीं पहचान सकता। **आप स्रोत पर पेलोड को नियंत्रित करते हैं, दो जगहों में:** @@ -667,7 +665,7 @@ flowchart LR `instrument()` एडेप्टर द्वारा पढ़ी जाने वाली विकल्प को छोड़ता है, इसलिए गलत नाम पास करने से कुछ नहीं उठाया जाता है और कुछ भी नहीं बदलता है। - पहली जगह में रहस्य को `input=` को हाथ न सौंपें। - `collector.redact` किसी के लिए विकल्प नहीं है। + `collector.redact` गहराई में सुरक्षा (defence in depth) की एक परत है, इन दोनों में से किसी का विकल्प नहीं। @@ -710,7 +708,7 @@ flowchart LR - थ्रेड ने कभी संदर्भ को विरासत में नहीं दिया। कॉलेबल को `failproofai_sdk.propagate()` में लपेटें। [थ्रेड्स और async](#threads-and-async) देखें। + थ्रेड ने कभी संदर्भ को विरासत में नहीं दिया। कॉलेबल को `failproofai_sdk.propagate()` में लपेटें। [थ्रेड्स और async](#थ्रेड्स-और-async) देखें। diff --git a/docs/it/start/integrations/custom-agents.mdx b/docs/it/start/integrations/custom-agents.mdx index 9e2f4361..ccf20220 100644 --- a/docs/it/start/integrations/custom-agents.mdx +++ b/docs/it/start/integrations/custom-agents.mdx @@ -268,7 +268,7 @@ Ogni framework di agenti ti dà le stesse tre giunzioni. Mappale e hai una tracc - **Manuale e automatico si compongono.** Un adapter in esecuzione dentro un ambito scritto a mano si unisce a quella sessione e si aggancia a quell'agente, quindi ottieni un albero anziché due — utile quando strumenti un framework da solo insieme a uno supportato. + **Manuale e automatico si compongono.** Un adapter in esecuzione dentro un ambito scritto a mano si unisce a quella sessione e diventa figlio di quell'agente, quindi ottieni un albero anziché due — utile quando strumenti un framework da solo insieme a uno supportato. @@ -641,20 +641,18 @@ Ogni flush scrive un file batch, `.tmp` per primo, poi `fsync`, poi un rename at Il daemon raccoglie solo `.jsonl`, quindi non può mai leggere un file scritto a metà. Lo stem porta un timestamp, id processo e numero di sequenza, quindi due processi che flushano nello stesso millisecondo non possono collisioni. La coda è limitata a 10.000 eventi; passato questo i più vecchi sono scartati e registrati. - **`collector.redact` non si applica ai tuoi eventi SDK.** Non li vede mai. + **Anche per gli eventi SDK il valore predefinito di `collector.redact` è `minimal`.** L'SDK maschera i dati sensibili prima di scrivere un batch su disco, e il daemon ripete lo stesso passaggio deterministico prima dell'upload, così anche i batch prodotti da SDK meno recenti restano protetti. -Il daemon **spedisce** i tuoi batch. Non li apre o li riscrive. +Il daemon legge ogni batch e applica il mascheramento in memoria prima dell'upload. Non riscrive il file di spool che ha letto. -| Eventi | Scritti da | Redatti da `collector.redact`? | +| Eventi | Scritti da | Dove viene applicato il mascheramento minimo | | --- | --- | --- | -| Trascritti di sessione CLI | Il daemon | Sì | -| Attività hook | Il daemon | Sì | -| **Tutto ciò che l'SDK emette** | **Il tuo processo** | **No** | +| Trascritti di sessione CLI | Il daemon | Prima che il daemon scriva il batch | +| Attività hook | Il daemon | Prima che il daemon scriva il batch | +| **Tutto ciò che l'SDK emette** | **Il tuo processo** | **Prima che l'SDK scriva il batch e di nuovo prima dell'upload da parte del daemon** | -La redazione viene eseguita dove il daemon *scrive* i suoi propri eventi — non dove i batch sono *spediti*. Quindi un prompt o un argomento di strumento che tiene una chiave API ancora la tiene all'arrivo. - -È deliberato. Queste sono le tue stesse chiamate di strumentazione, e riscriverle in transito significherebbe che gli eventi che ricevi non sono gli eventi che hai emesso. +Imposta `collector.redact` su `off` solo quando i payload integrali sono un requisito esplicito; sia l'SDK sia il daemon rispettano questa impostazione. Il mascheramento minimo intercetta le chiavi API più comuni, i bearer token, i JWT e le assegnazioni di secret. Non è in grado di riconoscere qualsiasi testo sensibile. **Controlli i payload alla sorgente, in due posti:** @@ -667,7 +665,7 @@ La redazione viene eseguita dove il daemon *scrive* i suoi propri eventi — non `instrument()` scarta le opzioni che un adapter non legge, quindi passare il nome sbagliato non genera nulla e non cambia nulla. - Non consegnare il segreto a `input=` in primo luogo. - `collector.redact` non è un sostituto per nessuno dei due. + `collector.redact` è una difesa in profondità, non un sostituto di nessuno dei due. diff --git a/docs/ja/start/integrations/custom-agents.mdx b/docs/ja/start/integrations/custom-agents.mdx index 38782e56..1f1422b4 100644 --- a/docs/ja/start/integrations/custom-agents.mdx +++ b/docs/ja/start/integrations/custom-agents.mdx @@ -641,20 +641,18 @@ Spoolがこれを安全にする理由です。エージェントはネットワ デーモンは `.jsonl` のみを読み取るため、書き込み途中のファイルを読むことは決してありません。ファイル名にはタイムスタンプ、プロセスID、シーケンス番号が含まれるため、2つのプロセスが同じミリ秒にフラッシュしても衝突しません。キューの上限は10,000イベントで、それを超えると最古のものを削除してログに記録します。 - **`collector.redact` はSDKイベントには適用されません。** SDKイベントは `collector.redact` の処理対象外です。 + **SDKイベントでも `collector.redact` のデフォルトは `minimal` です。** SDKはバッチをディスクに書き込む前に機密情報をマスクし、デーモンはアップロード前に同じ決定的な処理をもう一度実行します。そのため、古いバージョンのSDKが書き込んだバッチも保護されます。 -デーモンはバッチを**送信**します。バッチを開いたり書き換えたりしません。 +デーモンは各バッチを読み込み、アップロード前にメモリ上でマスキングを適用します。読み込んだSpoolファイル自体は書き換えません。 -| イベント | 書き込み者 | `collector.redact` による編集 | +| イベント | 書き込み者 | 最小限のマスキングが実行される場所 | | --- | --- | --- | -| CLIセッションのトランスクリプト | デーモン | あり | -| フックのアクティビティ | デーモン | あり | -| **SDKが送出するすべてのイベント** | **プロセス** | **なし** | +| CLIセッションのトランスクリプト | デーモン | デーモンがバッチを書き込む前 | +| フックのアクティビティ | デーモン | デーモンがバッチを書き込む前 | +| **SDKが送出するすべてのイベント** | **プロセス** | **SDKがバッチを書き込む前と、デーモンがアップロードする前の2回** | -編集はデーモンが自身のイベントを*書き込む*場所で実行されます — バッチが*送信される*場所ではありません。そのため、APIキーを含むプロンプトやツール引数は、到着時もそのままの状態です。 - -これは意図的な設計です。これらはご自身の計装コールであり、送受信中に書き換えることは、送出したイベントと受け取るイベントが異なるものになることを意味します。 +`collector.redact` を `off` にするのは、ペイロードをそのまま保持することが明確な要件である場合だけにしてください。SDKとデーモンはどちらもこの設定に従います。最小限のマスキングは、一般的なAPIキー、Bearerトークン、JWT、シークレットの代入を検出しますが、任意の機密性の高い文章までは識別できません。 **ペイロードはソースの2箇所で制御できます：** @@ -667,7 +665,7 @@ Spoolがこれを安全にする理由です。エージェントはネットワ `instrument()` はアダプターが読み取らないオプションを無視するため、誤った名前を渡しても何も起きず、何も変わりません。 - そもそもシークレットを `input=` に渡さない。 - `collector.redact` はどちらの代替手段にもなりません。 + `collector.redact` は多層防御の一部であり、どちらの代わりにもなりません。 @@ -710,7 +708,7 @@ Spoolがこれを安全にする理由です。エージェントはネットワ - スレッドがコンテキストを継承していません。callableを `failproofai_sdk.propagate()` でラップしてください。[スレッドと非同期](#threads-and-async) を参照してください。 + スレッドがコンテキストを継承していません。callableを `failproofai_sdk.propagate()` でラップしてください。[スレッドと非同期](#スレッドと非同期) を参照してください。 diff --git a/docs/ko/start/integrations/custom-agents.mdx b/docs/ko/start/integrations/custom-agents.mdx index 4fea8d3c..11a84539 100644 --- a/docs/ko/start/integrations/custom-agents.mdx +++ b/docs/ko/start/integrations/custom-agents.mdx @@ -641,20 +641,18 @@ flowchart LR 데몬은 `.jsonl`만 읽으므로 절반만 쓰인 파일을 읽을 수 없습니다. 파일명에 타임스탬프, 프로세스 id, 시퀀스 번호가 포함되어 있어 두 프로세스가 같은 밀리초에 플러시해도 충돌하지 않습니다. 큐는 10,000개 이벤트로 제한되며, 초과 시 가장 오래된 것을 삭제하고 로그를 남깁니다. - **`collector.redact`는 SDK 이벤트에 적용되지 않습니다.** 절대 해당 이벤트를 볼 수 없습니다. + **SDK 이벤트에서도 `collector.redact`의 기본값은 `minimal`입니다.** SDK는 배치를 디스크에 쓰기 전에 민감한 값을 가리고, 데몬은 업로드 전에 같은 결정적 처리를 한 번 더 수행하므로 이전 SDK가 쓴 배치도 보호됩니다. -데몬은 배치를 **전송**합니다. 열거나 다시 쓰지 않습니다. +데몬은 각 배치를 읽어 업로드 전에 메모리에서 리댁션을 적용합니다. 읽은 스풀 파일을 다시 쓰지는 않습니다. -| 이벤트 | 작성자 | `collector.redact` 적용 여부 | +| 이벤트 | 작성자 | 최소 리댁션이 실행되는 위치 | | --- | --- | --- | -| CLI 세션 트랜스크립트 | 데몬 | 예 | -| 훅 활동 | 데몬 | 예 | -| **SDK가 발행하는 모든 것** | **사용자 프로세스** | **아니오** | +| CLI 세션 트랜스크립트 | 데몬 | 데몬이 배치를 쓰기 전 | +| 훅 활동 | 데몬 | 데몬이 배치를 쓰기 전 | +| **SDK가 발행하는 모든 것** | **사용자 프로세스** | **SDK가 배치를 쓰기 전, 그리고 데몬이 업로드하기 전에 한 번 더** | -리댁션은 데몬이 자체 이벤트를 *쓰는* 곳에서 실행됩니다. 배치가 *전송*되는 곳이 아닙니다. 따라서 API 키를 포함한 프롬프트나 도구 인자는 도착 시에도 그대로입니다. - -이는 의도적입니다. 이것은 사용자 자신의 계측 호출이며, 전송 중에 이를 재작성하면 받은 이벤트가 발행한 이벤트와 다르게 됩니다. +페이로드를 원문 그대로 보존해야 하는 것이 명시적인 요구 사항일 때만 `collector.redact`를 `off`로 설정하세요. SDK와 데몬 모두 이 설정을 따릅니다. 최소 리댁션은 일반적인 API 키, bearer 토큰, JWT, 시크릿 할당을 잡아내지만, 임의의 민감한 문장까지 식별할 수는 없습니다. **페이로드는 소스에서 두 곳에서 제어할 수 있습니다:** @@ -667,7 +665,7 @@ flowchart LR `instrument()`는 어댑터가 읽지 않는 옵션을 무시하므로, 잘못된 이름을 전달해도 오류 없이 아무 변화도 없습니다. - 처음부터 `input=`에 비밀을 전달하지 마세요. - `collector.redact`는 두 경우 중 어느 것도 대체하지 않습니다. + `collector.redact`는 심층 방어 수단일 뿐, 두 방법 중 어느 것도 대체하지 않습니다. @@ -710,7 +708,7 @@ flowchart LR - 스레드가 컨텍스트를 상속받지 못했습니다. callable을 `failproofai_sdk.propagate()`로 감싸세요. [스레드와 비동기](#threads-and-async)를 참고하세요. + 스레드가 컨텍스트를 상속받지 못했습니다. callable을 `failproofai_sdk.propagate()`로 감싸세요. [스레드와 비동기](#스레드와-비동기)를 참고하세요. diff --git a/docs/pt-br/start/integrations/custom-agents.mdx b/docs/pt-br/start/integrations/custom-agents.mdx index fd1ab4f0..a46d42cf 100644 --- a/docs/pt-br/start/integrations/custom-agents.mdx +++ b/docs/pt-br/start/integrations/custom-agents.mdx @@ -643,20 +643,18 @@ Cada flush escreve um arquivo de lote, `.tmp` primeiro, depois `fsync`, depois u O daemon só lê `.jsonl`, então nunca pode ler um arquivo parcialmente escrito. O nome do arquivo carrega um timestamp, id de processo e número de sequência, então dois processos fazendo flush no mesmo milissegundo não podem colidir. A fila tem capacidade máxima de 10.000 eventos; além disso, descarta os mais antigos e registra um log. - **`collector.redact` não se aplica aos seus eventos do SDK.** Ele nunca os vê. + **`collector.redact` também usa `minimal` por padrão para eventos do SDK.** O SDK mascara os dados sensíveis antes de gravar um lote em disco, e o daemon repete a mesma passagem determinística antes do upload, para que lotes de SDKs mais antigos também fiquem protegidos. -O daemon **envia** seus lotes. Ele não os abre nem os reescreve. +O daemon lê cada lote e aplica o mascaramento em memória antes do upload. Ele não reescreve o arquivo de spool que leu. -| Eventos | Escritos por | Redacted por `collector.redact`? | +| Eventos | Escritos por | Onde o mascaramento mínimo é aplicado | | --- | --- | --- | -| Transcrições de sessão CLI | O daemon | Sim | -| Atividade de hook | O daemon | Sim | -| **Tudo que o SDK emite** | **Seu processo** | **Não** | +| Transcrições de sessão CLI | O daemon | Antes de o daemon gravar o lote | +| Atividade de hook | O daemon | Antes de o daemon gravar o lote | +| **Tudo que o SDK emite** | **Seu processo** | **Antes de o SDK gravar o lote e de novo antes do upload pelo daemon** | -A redação roda onde o daemon *escreve* seus próprios eventos — não onde os lotes são *enviados*. Então um prompt ou argumento de ferramenta contendo uma chave de API ainda a contém na chegada. - -Isso é intencional. Estas são suas próprias chamadas de instrumentação, e reescrevê-las em trânsito significaria que os eventos que você recebe não são os eventos que você emitiu. +Defina `collector.redact` como `off` somente quando payloads literais forem um requisito explícito; tanto o SDK quanto o daemon respeitam essa configuração. O mascaramento mínimo detecta chaves de API comuns, bearer tokens, JWTs e atribuições de segredos. Ele não consegue identificar qualquer texto sensível arbitrário. **Você controla os payloads na fonte, em dois lugares:** @@ -669,7 +667,7 @@ Isso é intencional. Estas são suas próprias chamadas de instrumentação, e r `instrument()` descarta opções que um adaptador não lê, então passar o nome errado não lança nada e não altera nada. - Não passe o segredo para `input=` em primeiro lugar. - `collector.redact` não é substituto para nenhum dos dois. + `collector.redact` é defesa em profundidade, não um substituto para nenhum dos dois. @@ -712,7 +710,7 @@ O padrão é correto em produção e errado durante debug, porque só pode prova - A thread nunca herdou o contexto. Envolva o callable em `failproofai_sdk.propagate()`. Veja [Threads e async](#threads-and-async). + A thread nunca herdou o contexto. Envolva o callable em `failproofai_sdk.propagate()`. Veja [Threads e async](#threads-e-async). diff --git a/docs/ru/start/integrations/custom-agents.mdx b/docs/ru/start/integrations/custom-agents.mdx index 17b107d2..7c6a562f 100644 --- a/docs/ru/start/integrations/custom-agents.mdx +++ b/docs/ru/start/integrations/custom-agents.mdx @@ -268,7 +268,7 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **Ручное и автоматическое взаимодействуют.** Адаптер, работающий внутри ручной области, присоединяется к этой session и становится родителем этого агента, поэтому вы получаете одно дерево вместо двух — это полезно когда вы инструментируете один фреймворк сами наряду с поддерживаемым. + **Ручное и автоматическое взаимодействуют.** Адаптер, работающий внутри ручной области, присоединяется к этой session и становится дочерним по отношению к этому агенту, поэтому вы получаете одно дерево вместо двух — это полезно когда вы инструментируете один фреймворк сами наряду с поддерживаемым. @@ -437,7 +437,7 @@ with failproofai_sdk.session(): | `agent_id` | Вы или фреймворк | От `agent("analyst")`, CrewAI `role`, имя `FunctionAgent.name`. UUID-подобное значение отклоняется и заменяется | | `tool_call_id`, `hook_id`, `request_id` | Вы или фреймворк | Адаптеры переиспользуют собственные id запуска фреймворка, вот почему пары выживают переходы через потоки | | **Event id** | **Cloud at ingest** | SDK не генерирует | -| **`dedup_key`** | **Cloud at ingest** | Хеш org, session, timestamp, type и payload. Это реальная идентификация — делает повторённую партию коллапсом вместо дублирования | +| **`dedup_key`** | **Cloud at ingest** | Хеш org, session, timestamp, type и payload. Это и есть настоящая идентичность: благодаря ему повторно отправленный батч схлопывается, а не дублируется | #### Как адаптеры разрешают `session_id` @@ -641,20 +641,18 @@ Spool — это то что делает это безопасным: ваш а Daemon только подбирает `.jsonl`, поэтому никогда не может прочитать наполовину написанный файл. Stem несёт timestamp, process id и sequence number, поэтому два процесса flushing в той же миллисекунде не могут столкнуться. Очередь ограничена 10,000 событиями; сверх этого она отбрасывает самое старое и логирует. - **`collector.redact` не применяется к вашим SDK событиям.** Он их никогда не видит. + **Для событий SDK `collector.redact` тоже по умолчанию равен `minimal`.** SDK маскирует данные перед записью батча на диск, а daemon повторяет тот же детерминированный проход перед отправкой, поэтому батчи от старых версий SDK тоже защищены. -Daemon **доставляет** ваши батчи. Он их не открывает и не переписывает. +Daemon читает каждый батч и применяет маскирование в памяти перед отправкой. Прочитанный spool-файл он не перезаписывает. -| События | Написано | Отредактировано `collector.redact`? | +| События | Кем записаны | Где выполняется минимальное маскирование | | --- | --- | --- | -| CLI session транскрипты | Daemon | Yes | -| Hook activity | Daemon | Yes | -| **Всё что SDK генерирует** | **Ваш процесс** | **No** | +| Транскрипты сессий CLI | Daemon | Перед тем как daemon запишет батч | +| Активность хуков | Daemon | Перед тем как daemon запишет батч | +| **Всё, что генерирует SDK** | **Ваш процесс** | **Перед тем как SDK запишет батч, и ещё раз перед отправкой через daemon** | -Редакция работает где daemon **пишет** его собственные события — не где батчи **доставляются**. Поэтому prompt или инструмент argument держащий API key всё ещё держит его по прибытии. - -Это намеренно. Это ваши собственные вызовы инструментирования, и переписывание их в пути бы означало события которые вы получаете не события которые вы генерировали. +Устанавливайте `collector.redact` в `off`, только если неизменённые payloads — явное требование; эту настройку учитывают и SDK, и daemon. Минимальное маскирование находит распространённые API-ключи, bearer-токены, JWT и присваивания секретов. Произвольный конфиденциальный текст оно распознать не может. **Вы контролируете payloads на источнике в двух местах:** @@ -667,7 +665,7 @@ Daemon **доставляет** ваши батчи. Он их не открыв `instrument()` отбрасывает опции адаптер не читает, поэтому передача неправильного имени выбросит ничего и изменит ничего. - Не передавайте secret в `input=` в первую очередь. - `collector.redact` не является заменой для обоих. + `collector.redact` — это эшелонированная защита, а не замена ни тому, ни другому. @@ -676,7 +674,7 @@ Daemon **доставляет** ваши батчи. Он их не открыв Daemon удаляет каждый батч в миллисекундах доставки, поэтому `ls` гонится по collector и показывает fraction того что вы генерировали — неразличимый от SDK который ничего не записал. -Чтобы подтвердить события действительно приземлились, проверьте панель управления. Чтобы看着 spool заполняться, сначала остановите daemon. +Чтобы убедиться, что события действительно дошли, проверьте панель управления. Чтобы посмотреть, как заполняется spool, сначала остановите daemon. @@ -710,7 +708,7 @@ Default правильный в production и неправильный при de - Поток никогда не наследовал контекст. Оберните callable в `failproofai_sdk.propagate()`. См. [Потоки и async](#threads-and-async). + Поток никогда не наследовал контекст. Оберните callable в `failproofai_sdk.propagate()`. См. [Потоки и async](#потоки-и-async). diff --git a/docs/tr/start/integrations/custom-agents.mdx b/docs/tr/start/integrations/custom-agents.mdx index b091505d..c150af50 100644 --- a/docs/tr/start/integrations/custom-agents.mdx +++ b/docs/tr/start/integrations/custom-agents.mdx @@ -1,7 +1,7 @@ --- title: "Özel aracılar" sidebarTitle: "Özel aracılar" -description: "Kendiniz yazdığınız bir aracıyı veya adaptörü olmayan bir çerçeveyi enstrüman edin." +description: "Kendi yazdığınız bir aracıyı ya da adaptörü olmayan bir çerçeveyi enstrümante edin." icon: "code" --- @@ -268,7 +268,7 @@ Her ajan çerçevesi aynı üç bağlantı noktası sağlar. Onları harita yap - **Manuel ve otomatik oluşturma.** El yazısı bir kapsam içinde çalışan bir adaptör bu oturuma katılır ve bu aracıya ebeveyn olur, bu nedenle iki tane yerine bir ağaç alırsınız — desteklenen bir tarafı kendiniz enstrümante ederken bir çerçeveyi yan yana kullanışlı olduğunda. + **Manuel ve otomatik birlikte çalışır.** Elle yazılmış bir kapsam içinde çalışan bir adaptör bu oturuma katılır ve bu aracının alt öğesi olur; böylece iki ağaç yerine tek bir ağaç elde edersiniz — desteklenen bir çerçevenin yanında başka bir çerçeveyi kendiniz enstrümante ettiğinizde kullanışlıdır. @@ -641,20 +641,18 @@ Her temizleme bir toplu dosya yazar, `.tmp` ilk, sonra `fsync`, sonra atomik yen Daemon yalnızca `.jsonl` alır, bu nedenle asla yarı yazılı dosya okuyamaz. Gövde zaman damgası, işlem kimliği ve sıra numarası taşır, bu nedenle iki işlem aynı milisaniyede temizlenirse çarpışamaz. Kuyruk 10.000 olayda sınırlıdır; bunun ötesinde en eskisini bırakır ve kaydeder. - **`collector.redact` SDK olaylarınıza uygulanmaz.** Asla onları görmez. + **`collector.redact`, SDK olayları için de varsayılan olarak `minimal` değerindedir.** SDK bir topluyu diske yazmadan önce hassas verileri maskeler, daemon da yüklemeden önce aynı deterministik geçişi tekrarlar; böylece eski SDK sürümlerinden gelen toplular da korunur. -Daemon **gönderir** topluları. Açmaz veya yeniden yazmaları yapmaz. +Daemon her topluyu okur ve yüklemeden önce maskelemeyi bellekte uygular. Okuduğu makara (spool) dosyasını yeniden yazmaz. -| Olaylar | Tarafından yazılan | `collector.redact` tarafından redakte mi? | +| Olaylar | Yazan | Minimal maskelemenin çalıştığı yer | | --- | --- | --- | -| CLI oturum transkriptleri | Daemon | Evet | -| Kancanın aktivitesi | Daemon | Evet | -| **SDK'nin yayınladığı her şey** | **İşleminiz** | **Hayır** | +| CLI oturum transkriptleri | Daemon | Daemon topluyu yazmadan önce | +| Kanca etkinliği | Daemon | Daemon topluyu yazmadan önce | +| **SDK'nin yayınladığı her şey** | **İşleminiz** | **SDK topluyu yazmadan önce ve daemon yüklemeden önce bir kez daha** | -Redaksiyon daemon'un kendi olaylarını *yazdığı* yerde çalışır — topluların *sevk edildiği* yerde değil. Bu yüzden bir istemi veya bir API anahtarı tutan araç bağımsız değişkeni varışta tutmaya devam eder. - -Bu kasıtlıdır. Bunlar kendi enstrümantasyon çağrılarınızdır ve bunları aktarım sırasında yeniden yazmak, aldığınız olayların yayınladığınız olaylar olmadığı anlamına gelir. +`collector.redact` değerini yalnızca payload'ların değiştirilmeden kalması açık bir gereksinim olduğunda `off` yapın; SDK da daemon da bu ayara uyar. Minimal maskeleme yaygın API anahtarlarını, bearer token'ları, JWT'leri ve gizli değer atamalarını yakalar. Rastgele hassas metinleri tanıyamaz. **Yüklemeleri kaynakta kontrol edersiniz, iki yerde:** @@ -667,7 +665,7 @@ Bu kasıtlıdır. Bunlar kendi enstrümantasyon çağrılarınızdır ve bunlar `instrument()` bir adaptörün okumuyor olduğu seçenekleri bırakır, bu nedenle yanlış adı iletmek hiçbir şey yükseltmez ve hiçbir şey değiştirmez. - Sırrı ilk yerde `input=` tutmayın. - `collector.redact` ikisi için bir yedek değil. + `collector.redact` derinlemesine savunmanın bir katmanıdır; ikisinin de yerini tutmaz. @@ -710,7 +708,7 @@ Varsayılan, üretimde doğru ve hata ayıklarken yanlıştır, çünkü yalnız - İş parçacığı asla bağlamı devralması olmadı. Çağrıyı `failproofai_sdk.propagate()` içine sarın. Bkz. [İş parçacıkları ve async](#threads-and-async). + İş parçacığı asla bağlamı devralması olmadı. Çağrıyı `failproofai_sdk.propagate()` içine sarın. Bkz. [İş parçacıkları ve async](#i̇ş-parçacıkları-ve-async). diff --git a/docs/vi/start/integrations/custom-agents.mdx b/docs/vi/start/integrations/custom-agents.mdx index 6a0b9f03..c99cc19d 100644 --- a/docs/vi/start/integrations/custom-agents.mdx +++ b/docs/vi/start/integrations/custom-agents.mdx @@ -268,7 +268,7 @@ Mỗi framework agent cung cấp cho bạn ba đường nối tương tự. Ánh - **Tay và tự động soạn.** Một adapter chạy bên trong một phạm vi viết tay tham gia session đó và phụ huynh của đó, vì vậy bạn nhận được một cây chứ không phải hai — hữu ích khi bạn công cụ hóa một framework tự bên cạnh một cái được hỗ trợ. + **Thủ công và tự động kết hợp được với nhau.** Một adapter chạy bên trong một phạm vi viết tay sẽ tham gia session đó và trở thành con của agent đó, nên bạn có một cây thay vì hai — hữu ích khi bạn tự công cụ hóa một framework bên cạnh một framework được hỗ trợ. @@ -437,7 +437,7 @@ Phạm vi liên kết danh tính trên các biến ngữ cảnh. Những cái đ | `agent_id` | Bạn, hoặc framework | Từ `agent("analyst")`, một `role` CrewAI, một `FunctionAgent.name`. Một giá trị trông giống như UUID bị từ chối và thay thế | | `tool_call_id`, `hook_id`, `request_id` | Bạn, hoặc framework | Các adapter tái sử dụng các id chạy của riêng framework, đó là lý do tại sao các cặp sống sót qua bước hoa | | **Event id** | **Cloud, tại ingest** | SDK không phát ra cái nào | -| **`dedup_key`** | **Cloud, tại ingest** | Một hash của org, phiên, dấu thời gian, loại và tải trọng. Đây là danh tính thực — nó làm cho một lô được thử lại sập thay vì sao chép | +| **`dedup_key`** | **Cloud, tại ingest** | Một hash của org, phiên, dấu thời gian, loại và tải trọng. Đây mới là danh tính thực sự — nhờ nó, một lô được gửi lại sẽ được gộp vào sự kiện đã có thay vì bị nhân đôi | #### Cách các adapter giải quyết `session_id` @@ -641,20 +641,18 @@ Mỗi xóa viết một tệp lô, `.tmp` đầu tiên, sau đó `fsync`, sau đ Daemon chỉ nhặt `.jsonl`, vì vậy nó không bao giờ có thể đọc một tệp nửa viết. Thân phần mang một dấu thời gian, id quy trình và số thứ tự, vì vậy hai quy trình xóa trong cùng một mili giây không thể va chạm. Hàng đợi bị giới hạn ở 10.000 sự kiện; quá điểm đó, nó bỏ cái cũ nhất và ghi nhật ký. - **`collector.redact` không áp dụng cho các sự kiện SDK của bạn.** Nó không bao giờ nhìn thấy chúng. + **`collector.redact` cũng mặc định là `minimal` đối với sự kiện SDK.** SDK che giấu dữ liệu nhạy cảm trước khi ghi một lô xuống đĩa, và daemon lặp lại đúng lượt xử lý tất định đó trước khi tải lên, nhờ vậy các lô từ những phiên bản SDK cũ hơn cũng được bảo vệ. -Daemon **tàu** lô của bạn. Nó không mở hoặc viết lại chúng. +Daemon đọc từng lô và áp dụng việc che giấu dữ liệu trong bộ nhớ trước khi tải lên. Nó không ghi lại tệp spool mà nó đã đọc. -| Sự kiện | Viết bởi | Được chỉnh sửa bởi `collector.redact`? | +| Sự kiện | Viết bởi | Nơi áp dụng che giấu tối thiểu | | --- | --- | --- | -| Bản ghi phiên CLI | Daemon | Có | -| Hoạt động hook | Daemon | Có | -| **Mọi thứ SDK phát ra** | **Quy trình của bạn** | **Không** | +| Bản ghi phiên CLI | Daemon | Trước khi daemon ghi lô | +| Hoạt động hook | Daemon | Trước khi daemon ghi lô | +| **Mọi thứ SDK phát ra** | **Quy trình của bạn** | **Trước khi SDK ghi lô và một lần nữa trước khi daemon tải lên** | -Chỉnh sửa chạy ở nơi daemon *viết* sự kiện riêng của nó — không phải ở nơi lô được *gửi*. Vì vậy, một lời nhắc hoặc một đối số công cụ giữ một khóa API vẫn giữ nó trên lẫn. - -Điều đó cố ý. Đây là các cuộc gọi công cụ hóa của riêng bạn, và viết lại chúng trong quá trình không có nghĩa là các sự kiện bạn nhận được không phải là các sự kiện bạn phát ra. +Chỉ đặt `collector.redact` thành `off` khi bạn thực sự cần giữ nguyên payload; cả SDK và daemon đều tuân theo thiết lập này. Che giấu tối thiểu phát hiện các khóa API phổ biến, bearer token, JWT và các phép gán bí mật. Nó không thể nhận diện mọi đoạn văn bản nhạy cảm tùy ý. **Bạn kiểm soát tải trọng tại nguồn, ở hai nơi:** @@ -667,7 +665,7 @@ Chỉnh sửa chạy ở nơi daemon *viết* sự kiện riêng của nó — k `instrument()` bỏ các tùy chọn một adapter không đọc, vì vậy chuyển tên sai không tăng và không thay đổi gì. - Đừng trao bí mật cho `input=` ở nơi đầu tiên. - `collector.redact` không phải là thay thế cho cái nào cả. + `collector.redact` là phòng thủ theo chiều sâu, không thay thế cho cách nào trong hai cách trên. @@ -710,7 +708,7 @@ Giá trị mặc định là đúng trong sản xuất và sai trong khi gỡ l - Luồng không bao giờ kế thừa ngữ cảnh. Bao `callable` trong `failproofai_sdk.propagate()`. Xem [Luồng và async](#threads-and-async). + Luồng không bao giờ kế thừa ngữ cảnh. Bao `callable` trong `failproofai_sdk.propagate()`. Xem [Luồng và async](#luồng-và-async). diff --git a/docs/zh/start/integrations/custom-agents.mdx b/docs/zh/start/integrations/custom-agents.mdx index 796ddd1b..915cd5d7 100644 --- a/docs/zh/start/integrations/custom-agents.mdx +++ b/docs/zh/start/integrations/custom-agents.mdx @@ -641,20 +641,18 @@ spool 是确保安全的关键：你的 agent 永远不会因网络而阻塞，C 守护进程只处理 `.jsonl` 文件，因此永远不会读到写入一半的文件。文件名包含时间戳、进程 id 和序列号，因此两个进程在同一毫秒内刷新也不会冲突。队列最多容纳 10,000 个事件，超出后会丢弃最旧的并记录日志。 - **`collector.redact` 不适用于你的 SDK 事件。** 它根本看不到这些事件。 + **对 SDK 事件，`collector.redact` 同样默认为 `minimal`。** SDK 在把批次写入磁盘前进行脱敏，守护进程在上传前还会重复同样的确定性处理，因此旧版 SDK 写入的批次也能得到保护。 -守护进程**发送**你的批次。它不打开也不重写这些批次。 +守护进程读取每个批次，并在上传前于内存中执行脱敏。它不会改写所读取的 spool 文件。 -| 事件 | 写入者 | 是否受 `collector.redact` 处理 | +| 事件 | 写入者 | 最小脱敏在何处执行 | | --- | --- | --- | -| CLI 会话记录 | 守护进程 | 是 | -| Hook 活动 | 守护进程 | 是 | -| **SDK 发出的所有事件** | **你的进程** | **否** | +| CLI 会话记录 | 守护进程 | 守护进程写入批次之前 | +| Hook 活动 | 守护进程 | 守护进程写入批次之前 | +| **SDK 发出的所有事件** | **你的进程** | **SDK 写入批次之前，以及守护进程上传之前再执行一次** | -脱敏在守护进程**写入**自身事件的地方运行——而不是在批次**发送**的地方。因此，包含 API 密钥的 prompt 或工具参数在到达时仍然包含该密钥。 - -这是有意为之。这些是你自己的埋点调用，在传输过程中改写它们意味着你收到的事件与你发出的不一致。 +只有在明确要求保留原样载荷时，才将 `collector.redact` 设为 `off`；SDK 和守护进程都会遵循该设置。最小脱敏可以识别常见的 API 密钥、Bearer 令牌、JWT 以及密钥赋值语句，但无法识别任意的敏感文本。 **你在源头控制载荷，有两种方式：** @@ -667,7 +665,7 @@ spool 是确保安全的关键：你的 agent 永远不会因网络而阻塞，C `instrument()` 会丢弃适配器不读取的选项，因此传入错误的名称不会报错，也不会有任何效果。 - 一开始就不要将敏感信息传给 `input=`。 - `collector.redact` 不能替代上述两种方式。 + `collector.redact` 是纵深防御的一环，不能替代上述任何一种方式。 @@ -710,7 +708,7 @@ spool 是确保安全的关键：你的 agent 永远不会因网络而阻塞，C - 该线程从未继承上下文。请将可调用对象包裹在 `failproofai_sdk.propagate()` 中。参见[线程与异步](#threads-and-async)。 + 该线程从未继承上下文。请将可调用对象包裹在 `failproofai_sdk.propagate()` 中。参见[线程与异步](#线程与异步)。 From d66d4f9d0129f1ae0e5bd1295105440844b48fa9 Mon Sep 17 00:00:00 2001 From: NiveditJain Date: Tue, 15 Sep 2026 11:01:44 +0530 Subject: [PATCH 4/8] docs: fix defects the Sep 14 translations introduced MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Parity checks of every locale page this PR touches against its English source (code blocks, inline code, links, component attributes, headings, numbers, foreign scripts, text left in English). What they found: - vi evaluations/overview: "tr裁判", a Chinese word for "judge", inside the Vietnamese text, twice. - he policy-sdk and publish-a-pack: Arabic letters inside Hebrew words, "השלל" ("the loot") for `deny`, and a garbled flag list. - he packs: "כורעת" ("kneels") for "denies", and a link the English does not have. - he cloud-cli and editor: `AGENTEYE_*` and `fp login` had lost their backticks inside mangled sentences. - he reference/overview: the title, description, card titles and two image alt texts had regressed to English. main had them translated. - he, hi and tr setup, hi reference/custom-agents, ru policy-sdk: component titles the run regressed to English, restored. - es cloud-cli translated the `resource:action` token inside backticks, ja and zh packs dropped `policies add`, tr failproof-cli dropped the `FAILPROOFAI__EXTRA_PATHS` name, and ru dropped the quotes that make `"failure"` the near-miss the sentence is about. - evaluations/overview linked deploy#score-sessions-you-already-have in all 14 locales, an English slug that no translated heading produces (Hermes F3). Each now targets its own locale's heading, verified with `mintlify broken-links --check-anchors`. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NrdeSVKcfqXd1H2BwP45Ad --- docs/ar/evaluations/overview.mdx | 2 +- docs/de/evaluations/overview.mdx | 2 +- docs/es/evaluations/overview.mdx | 2 +- docs/es/reference/cloud-cli.mdx | 2 +- docs/fr/evaluations/overview.mdx | 2 +- docs/he/evaluations/overview.mdx | 2 +- docs/he/policies/editor.mdx | 2 +- docs/he/policies/packs.mdx | 4 ++-- docs/he/policies/publish-a-pack.mdx | 2 +- docs/he/reference/cloud-cli.mdx | 2 +- docs/he/reference/overview.mdx | 24 ++++++++++++------------ docs/he/reference/policy-sdk.mdx | 4 ++-- docs/he/start/setup.mdx | 2 +- docs/hi/evaluations/overview.mdx | 2 +- docs/hi/reference/custom-agents.mdx | 6 +++--- docs/hi/start/setup.mdx | 6 +++--- docs/it/evaluations/overview.mdx | 2 +- docs/ja/evaluations/overview.mdx | 2 +- docs/ja/policies/packs.mdx | 4 ++-- docs/ko/evaluations/overview.mdx | 2 +- docs/pt-br/evaluations/overview.mdx | 2 +- docs/ru/evaluations/overview.mdx | 2 +- docs/ru/reference/custom-agents.mdx | 2 +- docs/ru/reference/policy-sdk.mdx | 2 +- docs/tr/evaluations/overview.mdx | 2 +- docs/tr/reference/failproof-cli.mdx | 2 +- docs/tr/start/setup.mdx | 2 +- docs/vi/evaluations/overview.mdx | 6 +++--- docs/zh/evaluations/overview.mdx | 2 +- docs/zh/policies/packs.mdx | 2 +- 30 files changed, 50 insertions(+), 50 deletions(-) diff --git a/docs/ar/evaluations/overview.mdx b/docs/ar/evaluations/overview.mdx index 4d3a2035..a3d77e20 100644 --- a/docs/ar/evaluations/overview.mdx +++ b/docs/ar/evaluations/overview.mdx @@ -41,4 +41,4 @@ Python المستضاف متعمد الصغر: تعبير واحد، بدون ا -التقييم يعمل للأمام: نسخة تم نشرها الآن تسجل الجلسات التي تنتهي من الآن فصاعدًا. لتسجيل الجلسات التي لديك بالفعل، [املأ الفجوات](/ar/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file +التقييم يعمل للأمام: نسخة تم نشرها الآن تسجل الجلسات التي تنتهي من الآن فصاعدًا. لتسجيل الجلسات التي لديك بالفعل، [املأ الفجوات](/ar/evaluations/deploy#تسجيل-الجلسات-التي-لديك-بالفعل). \ No newline at end of file diff --git a/docs/de/evaluations/overview.mdx b/docs/de/evaluations/overview.mdx index 6afd23c4..cb7c27e4 100644 --- a/docs/de/evaluations/overview.mdx +++ b/docs/de/evaluations/overview.mdx @@ -41,4 +41,4 @@ Evaluierungen gehören der Organisation, die sie definiert. Jede Organisation au -Evaluierungen wirken vorwärts: Eine jetzt deployete Version bewertet die Sitzungen, die ab sofort abgeschlossen werden. Um bereits vorhandene Sitzungen zu bewerten, [fülle sie nach](/de/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file +Evaluierungen wirken vorwärts: Eine jetzt deployete Version bewertet die Sitzungen, die ab sofort abgeschlossen werden. Um bereits vorhandene Sitzungen zu bewerten, [fülle sie nach](/de/evaluations/deploy#bereits-vorhandene-sessions-bewerten). \ No newline at end of file diff --git a/docs/es/evaluations/overview.mdx b/docs/es/evaluations/overview.mdx index a23aec25..a32ed9b7 100644 --- a/docs/es/evaluations/overview.mdx +++ b/docs/es/evaluations/overview.mdx @@ -41,4 +41,4 @@ Las evaluaciones pertenecen a la organización que las define. Cada organizació -Las evaluaciones avanzan hacia adelante: una versión desplegada ahora puntúa las sesiones que finalicen a partir de ese momento. Para puntuar sesiones que ya tienes, [rellena los datos anteriores](/es/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file +Las evaluaciones avanzan hacia adelante: una versión desplegada ahora puntúa las sesiones que finalicen a partir de ese momento. Para puntuar sesiones que ya tienes, [rellena los datos anteriores](/es/evaluations/deploy#puntuar-sesiones-que-ya-tienes). \ No newline at end of file diff --git a/docs/es/reference/cloud-cli.mdx b/docs/es/reference/cloud-cli.mdx index d63fe3bb..cf11a4e5 100644 --- a/docs/es/reference/cloud-cli.mdx +++ b/docs/es/reference/cloud-cli.mdx @@ -177,7 +177,7 @@ fp errors [OPTIONS] | `fp keys regenerate NAME` | Rota el secreto y revela el reemplazo una sola vez. | `--yes`, `-y` | | `fp keys disable NAME` | Revoca permanentemente una clave. | `--yes`, `-y` | -Los tokens de permiso usan el formato `recurso:acción`, como `events:add`. Repita `--add`, separe los tokens con comas o use acciones con puntos como `events:read.add`. +Los tokens de permiso usan el formato `resource:action`, como `events:add`. Repita `--add`, separe los tokens con comas o use acciones con puntos como `events:read.add`. ### Consultas diff --git a/docs/fr/evaluations/overview.mdx b/docs/fr/evaluations/overview.mdx index 000cb875..3f3d7ae0 100644 --- a/docs/fr/evaluations/overview.mdx +++ b/docs/fr/evaluations/overview.mdx @@ -41,4 +41,4 @@ Les évaluations appartiennent à l'organisation qui les définit. Chaque organi -L'évaluation s'applique en avance : une version déployée maintenant notera les sessions qui se termineront à partir de ce moment. Pour noter les sessions déjà existantes, [effectuez un remplissage rétrospectif](/fr/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file +L'évaluation s'applique en avance : une version déployée maintenant notera les sessions qui se termineront à partir de ce moment. Pour noter les sessions déjà existantes, [effectuez un remplissage rétrospectif](/fr/evaluations/deploy#noter-des-sessions-existantes). \ No newline at end of file diff --git a/docs/he/evaluations/overview.mdx b/docs/he/evaluations/overview.mdx index ec0b421f..a99ae9a3 100644 --- a/docs/he/evaluations/overview.mdx +++ b/docs/he/evaluations/overview.mdx @@ -41,4 +41,4 @@ Python מתארח הוא בכוונה קטן: ביטוי אחד, אין יבוא -הערכה רצה קדימה: גרסה שגובשה כעת משנה את הסשנים שמסתיימים מעכשיו ואילך. כדי לשנות סשנים שכבר יש לך, [מלא אותם](/he/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file +הערכה רצה קדימה: גרסה שגובשה כעת משנה את הסשנים שמסתיימים מעכשיו ואילך. כדי לשנות סשנים שכבר יש לך, [מלא אותם](/he/evaluations/deploy#הערכת-פעילויות-שכבר-יש-לך). \ No newline at end of file diff --git a/docs/he/policies/editor.mdx b/docs/he/policies/editor.mdx index 6ea4236a..83688055 100644 --- a/docs/he/policies/editor.mdx +++ b/docs/he/policies/editor.mdx @@ -33,7 +33,7 @@ icon: "file-pen-line" fp policies compose "Block git push --force on release branches" ``` - `compose` זקוק לתקופה שנכנסה (fp login) שתפקידה יש `policies:write`; היא מסרבת מפתחות API. + `compose` דורש session מחובר (`fp login`) שלתפקיד שלו יש הרשאת `policies:write`; מפתחות API נדחים. diff --git a/docs/he/policies/packs.mdx b/docs/he/policies/packs.mdx index cfade1d4..ba8a7794 100644 --- a/docs/he/policies/packs.mdx +++ b/docs/he/policies/packs.mdx @@ -103,11 +103,11 @@ Scopes, פרמטרים, והקבצים שהפקודות האלה כותבות מ `SHA256SUMS` משלח באותו release כמו artifact, אז זה **לא** חתימה וזה לא מוכיח כלום על מי פרסם אותו. מה שזה כן מוכיח הוא שהבתים הם אלה ש-release פרסם — וכי digest נרשם כשהוספת את החבילה ובדוק מחדש לפני כל import, חבילה לא יכולה להשתנות תחת המכונה שלך לאחר מכן. מאגר שretags או החלפת asset מפסיק לטעון במקום להריץ בשקט משהו אחר. -בזמן התקנה החבילה גם **ייובאת פעם אחת** ובדוקה כנגד manifest שלה שלה. חבילה שartifact שלה לא parse, או שרוזם משהו שונה מה שהוא מצהיר, נדחה לפני שום דבר מופעל — במקום התקנה נקייה והבאה לשימוש בעל השיחה הבאה שלך. ראה [Failure behavior](/he/policies/failure-behavior). +בזמן ההתקנה החבילה גם **מיובאת פעם אחת** ונבדקת מול ה-manifest שלה. חבילה שה-artifact שלה לא עובר parse, או שרושמת משהו שונה ממה שהיא מצהירה עליו, נדחית לפני שמשהו מופעל — במקום להיות מותקנת בלי שגיאה ולהיכשל בקריאת הכלי הבאה שלך. ## כשחבילה לא תטעון -חבילה שהמכונה הזאת נאמרה לה לאכוף ולא יכולה להריץ **כורעת** את האירועים שהמדיניויות החסרות שלה כיסו, במקום לתיר אותם בשקט — כ`pack/failproofai-pack-unavailable`, אשר outranks המדיניויות שכן טעונות אז ה-deny יוחס לחבילה החסרה במקום לאיזה guard התרחש להירות ראשון. החריג הוא `UserPromptSubmit`, אשר מדריך במקום זאת: כורעות שם יחסמו אותך מה-agent שאתה צריך כדי לתקן אותו. ראה [Failure behavior](/he/policies/failure-behavior). +חבילה שהמכונה הזו הונחתה לאכוף ואינה יכולה להריץ **חוסמת** את האירועים שהמדיניות החסרה שלה הייתה אמורה לכסות, במקום לאשר אותם בשקט — בתור `pack/failproofai-pack-unavailable`, שקודמת למדיניות שכן נטענה, כך שהחסימה מיוחסת לחבילה החסרה ולא לשומר שבמקרה הופעל ראשון. החריג הוא `UserPromptSubmit`, שבו נשלחת הנחיה במקום זאת: חסימה שם הייתה נועלת אותך מחוץ לסוכן שאתה צריך כדי לתקן את הבעיה. ראה [Failure behavior](/he/policies/failure-behavior). ## אופליין ומראות diff --git a/docs/he/policies/publish-a-pack.mdx b/docs/he/policies/publish-a-pack.mdx index 3b7b816f..72cb6cf6 100644 --- a/docs/he/policies/publish-a-pack.mdx +++ b/docs/he/policies/publish-a-pack.mdx @@ -87,7 +87,7 @@ failproofai publish \ --dry-run ``` -`--id` קובע את معرّف החבילה כאשר הוא צריך להיות שונה מ-repo, `--tag` קובע את תג ההוצאה, `--notes` מחליף את הערות ההוצאה שנוצרו — שבו `policies show --releases` קורא את הספירות וההחייבות של כל הוצאה מ- — `--out` בוחר לאן כתובים הנכסים (ברירת מחדל `dist-pack`), ו-`--dry-run` בונה אותם ללא פרסום ודורש ללא העלמה. +`--id` קובע את מזהה החבילה כשהוא צריך להיות שונה מה-repo, `--tag` קובע את התג של ה-release, `--notes` מחליף את הערות ה-release שנוצרו אוטומטית — ומהן `policies show --releases` קורא את המונים ואת ה-commit של כל release — `--out` בוחר לאן נכתבים ה-assets (ברירת מחדל `dist-pack`), ו-`--dry-run` בונה אותם בלי לפרסם ואינו דורש אישורי גישה. כל אחד יכול כעת להתקין אותו עם `failproofai policies add acme/support-agent`. ראה [חבילות מדיניות](/he/policies/packs) כדי להצמיד גרסה ולקחת רק חלק מאחד. diff --git a/docs/he/reference/cloud-cli.mdx b/docs/he/reference/cloud-cli.mdx index c7b7c194..06b6d673 100644 --- a/docs/he/reference/cloud-cli.mdx +++ b/docs/he/reference/cloud-cli.mdx @@ -389,7 +389,7 @@ fp audits create checkout-reliability \ דגלים מפורשים דורסים משתנים סביבה, שדורסים תצורה שמורה. במצב מפתח API, בחר את הדייר בצורה מפורשת עם `--org` או `FP_ORG`. - ה-AGENTEYE_* הנקודות של אלה הן **לא נקרא על ידי `fp`** ולעולם לא היו — ה-CLI מצהיר `FP_*` (`fp_cli/app.py`), ומשתנה לא ידוע אינו שגיאה. הגדרת `AGENTEYE_DASHBOARD_URL` לא מטרה מחדש את ה-CLI; הוא מתעלם ופקודה בשקט פעלה נגד הדashboard השמור במקום זאת. + הכתיבים `AGENTEYE_*` של משתנים אלה **אינם נקראים על ידי `fp`** ומעולם לא נקראו — ה-CLI מצהיר על `FP_*` (`fp_cli/app.py`), ומשתנה לא מוכר אינו נחשב שגיאה. הגדרת `AGENTEYE_DASHBOARD_URL` אינה מפנה את ה-CLI ליעד אחר; מתעלמים ממנה, והפקודה רצה בשקט מול ה-dashboard השמור. `AGENTEYE_HOME` ו-`AGENTEYE_ENVIRONMENT` עדיין קיימים, אך הם משתייכים ל-**collector וה-telemetry SDK**, לא ל-CLI זה. diff --git a/docs/he/reference/overview.mdx b/docs/he/reference/overview.mdx index bff2910a..794d68d4 100644 --- a/docs/he/reference/overview.mdx +++ b/docs/he/reference/overview.mdx @@ -1,22 +1,22 @@ --- -title: "Integrations and reference" -description: "Connect supported agent harnesses, SDKs, CLIs, and the HTTP API." +title: "אינטגרציות ומדריכי עיון" +description: "חבר סביבות סוכנים נתמכות, SDKs, ממשקי CLI ואת ה-HTTP API." icon: "braces" --- בחר את האינטגרציה הקרובה ביותר למקום שבו הסוכן שלך כבר פועל. - + התקן hooks עבור CLIs של coding ו-autonomous agents נתמכים. - - Instrument LangGraph, CrewAI, LlamaIndex, Pydantic AI, או סוכן מותאם אישית. + + הוסף instrumentation ל-LangGraph, ל-CrewAI, ל-LlamaIndex, ל-Pydantic AI או לסוכן מותאם אישית. - - Configuration, the event catalog, correlation rules, and delivery. + + תצורה, קטלוג האירועים, כללי הקורלציה והמסירה. - + בדוק פרויקטים מקומיים, sessions, policy activity, ו-audits offline. @@ -28,10 +28,10 @@ icon: "braces" דרג sessions שלמות או לא פעילות עם שירות FastAPI. - + כתוב ובדוק החלטות allow, instruct, ו-deny ספציפיות לflow עבודה. - + פרוס את Cloud control plane על cluster Kubernetes מנוהל על ידי לקוח. @@ -49,11 +49,11 @@ icon: "braces" התחל עם תא ה-keys. ההרשאות שנבחרו קובעות אם המכונה יכולה לשלוח אירועים ולקבל policies מנוהלות בענן. - ![The new API key drawer used to grant event ingestion and policy delivery permissions.](/images/dashboard/key-create.png) + ![מגירת מפתח ה-API החדש, שבה מעניקים הרשאות לקליטת אירועים ולמסירת מדיניות.](/images/dashboard/key-create.png) לאחר חיבור האינטגרציה, השתמש ברשימת Sessions כדי לאשר שהאירועים שלה מקובצים לריצות שלמות בסביבה הצפויה. - ![The Sessions list used to verify that a newly connected integration is reporting complete agent runs.](/images/dashboard/sessions-list.png) + ![רשימת ה-Sessions, שבה מוודאים שאינטגרציה שחוברה זה עתה מדווחת על ריצות סוכן שלמות.](/images/dashboard/sessions-list.png) פתח אחת מ-sessions הללו לפני שאתה שוקל את האינטגרציה כמושלמת; ה-trace צריך להכיל את ה-evidence של model, tool, error, ו-policy שה-audits שלך צריכים. diff --git a/docs/he/reference/policy-sdk.mdx b/docs/he/reference/policy-sdk.mdx index 6ceda3fd..42954090 100644 --- a/docs/he/reference/policy-sdk.mdx +++ b/docs/he/reference/policy-sdk.mdx @@ -4,7 +4,7 @@ description: "כתוב, בדוק והפץ מדיניות JavaScript או TypeScr icon: "shield-plus" --- -מדיניות מותאמת הופכת דפוס כשל מעקיפות או ביקורות שלך להחלטה המופעלת בזמן שהסוכן עובד. מדיניות יכולה לאפשר פעולה, לתת הדרכה לסוכן, או לשלול את הפעולה לפני שהיא גורמת לתקادם נוסף. +מדיניות מותאמת הופכת דפוס כשל מעקיפות או ביקורות שלך להחלטה המופעלת בזמן שהסוכן עובד. מדיניות יכולה לאפשר פעולה, לתת הדרכה לסוכן, או לשלול את הפעולה לפני שהיא גורמת לתקרית נוספת. השתמש במדיניות מותאמת כאשר ההתנהגות תלויה בכלים שלך, בנתיבים, בפקודות, בסביבות או בכללי הפעולה שלך. בדוק קודם את [חבילת המדיניות של Failproof AI](/he/policies/packs) כדי שלא תיצור בחזרה בקרה קיימת. @@ -275,7 +275,7 @@ failproofai policies ## התנהגות זמן ריצה - מדיניות מובנית מעריכה לפני מדיניות מותאמת. -- השלל הראשון עוצר הערכה נוספת של מדיניות. +- ה-`deny` הראשון עוצר את המשך הערכת המדיניות. - תוצאות `instruct` מרובות יכולות להיות משולבות כאשר אין מדיניות שלוללת את האירוע. - לפונקציית מדיניות יש קו זמן ביצוע של 10 שניות. - חריג שהוטל או זמן עבירה מתועדים ומטופלים כ-`allow()`. diff --git a/docs/he/start/setup.mdx b/docs/he/start/setup.mdx index 50c265f4..83682a4b 100644 --- a/docs/he/start/setup.mdx +++ b/docs/he/start/setup.mdx @@ -11,7 +11,7 @@ icon: "waypoints" הוסיפו הפעלות מרכזיות, ביקורות, הערכות מקוונות, לוחות בקרה, התראות והפעלת מדיניות בחfleet. - + השתמשו בבקרות ארגוניות, מפתחות בטווח מסוים, תשתית פרטית ודרישות אבטחה ספציפיות להפעלה. diff --git a/docs/hi/evaluations/overview.mdx b/docs/hi/evaluations/overview.mdx index 72cbeed8..cd7f2c60 100644 --- a/docs/hi/evaluations/overview.mdx +++ b/docs/hi/evaluations/overview.mdx @@ -41,4 +41,4 @@ icon: "gauge" -मूल्यांकन आगे की ओर चलता है: अभी तैनात किया गया एक संस्करण उन सत्रों को स्कोर करता है जो अब से समाप्त होते हैं। जो सत्र आपके पास पहले से हैं उन्हें स्कोर करने के लिए, [उन्हें backfill करें](/hi/evaluations/deploy#score-sessions-you-already-have)। \ No newline at end of file +मूल्यांकन आगे की ओर चलता है: अभी तैनात किया गया एक संस्करण उन सत्रों को स्कोर करता है जो अब से समाप्त होते हैं। जो सत्र आपके पास पहले से हैं उन्हें स्कोर करने के लिए, [उन्हें backfill करें](/hi/evaluations/deploy#आपके-पास-पहले-से-मौजूद-सत्रों-को-स्कोर-करें)। \ No newline at end of file diff --git a/docs/hi/reference/custom-agents.mdx b/docs/hi/reference/custom-agents.mdx index 81c19fd1..908a7ba0 100644 --- a/docs/hi/reference/custom-agents.mdx +++ b/docs/hi/reference/custom-agents.mdx @@ -28,7 +28,7 @@ pip install failproofai-sdk ## Failproof daemon को कनेक्ट करें - + 1. **Admin → Keys** पर जाएं और `events:add` के साथ एक key बनाएं। 2. [Failproof daemon को Cloud से कनेक्ट करें](/hi/start/setup#connect-a-machine-to-cloud) agent मशीन पर। 3. एक instrumented सेशन चलाएं, फिर **Observe → Events** के तहत इसकी सटीक ID खोजें। @@ -162,7 +162,7 @@ with failproofai_sdk.session(): एक अपवाद `model_response` है, जहां केवल आप real provider latency को जानते हैं। milliseconds की एक पूरी संख्या pass करें — एक float raise करता है, क्योंकि column एक 32-bit integer है और अन्यथा empty land करेगी। - + - **Ids केवल kind per, per session के लिए unique होना चाहिए।** एक tool call और एक hook एक share कर सकते हैं; दो sessions एक साथ चल सकते हैं एक ही ids को reuse कर सकते हैं बिना colliding के। - **वे agent को scoped नहीं हैं।** एक pair एक agent के तहत open किया गया और दूसरे agent के तहत close किया गया अभी भी match करता है — जो multi-agent code में सामान्य case है। @@ -196,7 +196,7 @@ failproofai_sdk.event.tool_use( ## Deliver और verify करें - + **Observe → Events** में, पहले verify करें `agent_start` exists है और `agent_end` exists अंत में है। फिर **Observe → Sessions** खोलें और confirm करें model, tool, human, hook, और error events intended order में दिखाई देते हैं। Session ID को primary troubleshooting key के रूप में उपयोग करें। diff --git a/docs/hi/start/setup.mdx b/docs/hi/start/setup.mdx index 24882cdc..0d535233 100644 --- a/docs/hi/start/setup.mdx +++ b/docs/hi/start/setup.mdx @@ -5,13 +5,13 @@ icon: "waypoints" --- - + एक मशीन को बिना Cloud key के सेट करें और एक policy pack लें। इसका उपयोग तब करें जब आपको तुरंत safeguards की आवश्यकता हो और session डेटा को Cloud में भेजना न हो। केंद्रीकृत sessions, audits, ऑनलाइन मूल्यांकन, डैशबोर्ड, alerts, और fleet policy परिनियोजन जोड़ें। - + संगठन नियंत्रण, scoped keys, निजी infrastructure, और परिनियोजन-विशिष्ट सुरक्षा आवश्यकताओं का उपयोग करें। @@ -31,7 +31,7 @@ icon: "waypoints" ## एक मशीन को Cloud से कनेक्ट करें - + 1. **Administration → Keys** पर जाएं और `events:add` और `policies:pull` के साथ एक key बनाएं। 2. one-time secret को target मशीन पर कॉपी करें। 3. CLI कनेक्शन कमांड चलाने के बाद, **Admin → enforcement** पर जाएं और पुष्टि करें कि मशीन दिखाई देती है। diff --git a/docs/it/evaluations/overview.mdx b/docs/it/evaluations/overview.mdx index 0f51b72e..50fa6817 100644 --- a/docs/it/evaluations/overview.mdx +++ b/docs/it/evaluations/overview.mdx @@ -41,4 +41,4 @@ Le valutazioni appartengono all'organizzazione che le definisce. Ogni organizzaz -La valutazione procede in avanti: una versione distribuita ora assegna un punteggio alle sessioni che terminano da ora in poi. Per assegnare un punteggio alle sessioni che hai già, [completale retroattivamente](/it/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file +La valutazione procede in avanti: una versione distribuita ora assegna un punteggio alle sessioni che terminano da ora in poi. Per assegnare un punteggio alle sessioni che hai già, [completale retroattivamente](/it/evaluations/deploy#valuta-le-sessioni-già-presenti). \ No newline at end of file diff --git a/docs/ja/evaluations/overview.mdx b/docs/ja/evaluations/overview.mdx index 4813f8a2..b202f250 100644 --- a/docs/ja/evaluations/overview.mdx +++ b/docs/ja/evaluations/overview.mdx @@ -41,4 +41,4 @@ icon: "gauge" -評価は前方向に実行されます。つまり、現在デプロイされたバージョンは、これ以降に完了するセッションをスコアリングします。すでに存在するセッションをスコアリングするには、[バックフィル](/ja/evaluations/deploy#score-sessions-you-already-have) を行ってください。 \ No newline at end of file +評価は前方向に実行されます。つまり、現在デプロイされたバージョンは、これ以降に完了するセッションをスコアリングします。すでに存在するセッションをスコアリングするには、[バックフィル](/ja/evaluations/deploy#既存セッションをスコアリングする) を行ってください。 \ No newline at end of file diff --git a/docs/ja/policies/packs.mdx b/docs/ja/policies/packs.mdx index 85ecba7c..dbcab243 100644 --- a/docs/ja/policies/packs.mdx +++ b/docs/ja/policies/packs.mdx @@ -19,7 +19,7 @@ icon: "package" failproofai policies add FailproofAI/policies ``` -このパックには38のポリシーが含まれており、マニフェストで無人実行時に安全とマークされた10個が自動で有効化されます。残りは選択肢として一覧表示されます。よく使われるポリシーとデフォルトの有効状態は以下の通りです。 +このパックには38のポリシーが含まれており、マニフェストで無人実行時に安全とマークされた10個が自動で有効化されます。残りは選択肢として一覧表示されます。よく使われるポリシーと、単に `policies add` を実行したときに有効になるかどうかは以下の通りです。 | ポリシー | 動作内容 | デフォルトで有効 | | --- | --- | --- | @@ -77,7 +77,7 @@ failproofai policies add FailproofAI/policies --category dangerous-commands # failproofai policies add FailproofAI/policies --all # パック内のすべて ``` -`--category` と `--policy` は OR 条件で組み合わせられます（`--only` は `--policy` の同義語として使用可能）。パックがすでにインストール済みの場合、フラグで指定した内容は既存の選択に追加されます。フラグなし・端末なしで再追加した場合（アップグレード時など）は、既存の選択がそのまま維持されます。端末上でフラグなしで実行すると、作者のデフォルトがあらかじめチェックされた状態でピッカーが開き、チェックした内容が選択を置き換えます。 +`--category` と `--policy` は OR 条件で組み合わせられます（`--only` は `--policy` の同義語として使用可能）。パックがすでにインストール済みの場合、フラグで指定した内容は既存の選択に追加されます。フラグなし・端末なしで再追加した場合（アップグレード時など）は、既存の選択がそのまま維持されます。端末上でフラグなしで `add` を実行すると、作者のデフォルトがあらかじめチェックされた状態でピッカーが開き、チェックした内容が選択を置き換えます。 ## 有効なポリシーを管理する diff --git a/docs/ko/evaluations/overview.mdx b/docs/ko/evaluations/overview.mdx index acf10118..a8656ebc 100644 --- a/docs/ko/evaluations/overview.mdx +++ b/docs/ko/evaluations/overview.mdx @@ -41,4 +41,4 @@ icon: "gauge" -평가는 순방향으로 실행됩니다: 지금 배포된 버전은 지금부터 완료되는 세션을 채점합니다. 이미 보유한 세션을 채점하려면 [백필](/ko/evaluations/deploy#score-sessions-you-already-have)을 사용하세요. \ No newline at end of file +평가는 순방향으로 실행됩니다: 지금 배포된 버전은 지금부터 완료되는 세션을 채점합니다. 이미 보유한 세션을 채점하려면 [백필](/ko/evaluations/deploy#기존-세션-채점)을 사용하세요. \ No newline at end of file diff --git a/docs/pt-br/evaluations/overview.mdx b/docs/pt-br/evaluations/overview.mdx index 8e8a736d..b1d0e764 100644 --- a/docs/pt-br/evaluations/overview.mdx +++ b/docs/pt-br/evaluations/overview.mdx @@ -41,4 +41,4 @@ As avaliações pertencem à organização que as define. Cada organização em -A execução de avaliações segue em frente: uma versão implantada agora pontua as sessões que forem finalizadas a partir deste momento. Para pontuar sessões que você já tem, [faça um backfill](/pt-br/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file +A execução de avaliações segue em frente: uma versão implantada agora pontua as sessões que forem finalizadas a partir deste momento. Para pontuar sessões que você já tem, [faça um backfill](/pt-br/evaluations/deploy#pontuar-sessões-que-você-já-tem). \ No newline at end of file diff --git a/docs/ru/evaluations/overview.mdx b/docs/ru/evaluations/overview.mdx index b3237f41..90bcb490 100644 --- a/docs/ru/evaluations/overview.mdx +++ b/docs/ru/evaluations/overview.mdx @@ -41,4 +41,4 @@ Hosted Python намеренно минимален: одно выражение -Оценки выполняются вперёд: версия, развёрнутая сейчас, оценивает сессии, которые завершаются с этого момента. Чтобы оценить уже имеющиеся сессии, [заполните их задним числом](/ru/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file +Оценки выполняются вперёд: версия, развёрнутая сейчас, оценивает сессии, которые завершаются с этого момента. Чтобы оценить уже имеющиеся сессии, [заполните их задним числом](/ru/evaluations/deploy#оценить-уже-имеющиеся-сессии). \ No newline at end of file diff --git a/docs/ru/reference/custom-agents.mdx b/docs/ru/reference/custom-agents.mdx index 59c77a56..c83e0b5f 100644 --- a/docs/ru/reference/custom-agents.mdx +++ b/docs/ru/reference/custom-agents.mdx @@ -143,7 +143,7 @@ with failproofai_sdk.session(): - Чтобы пометить запуск как неудачный, `outcome` должен быть одним из `failed`, `error`, `timeout` или `rejected`. Что-либо ещё — включая близкое совпадение `failure` — считается успехом. + Чтобы пометить запуск как неудачный, `outcome` должен быть одним из `failed`, `error`, `timeout` или `rejected`. Что-либо ещё — включая близкое совпадение `"failure"` — считается успехом. ## Спаривание и длительность diff --git a/docs/ru/reference/policy-sdk.mdx b/docs/ru/reference/policy-sdk.mdx index de79c16a..4204f382 100644 --- a/docs/ru/reference/policy-sdk.mdx +++ b/docs/ru/reference/policy-sdk.mdx @@ -140,7 +140,7 @@ const filePath = String(ctx.toolInput?.file_path ?? ""); Доступность события и поведение блокировки зависят от harness агента. Смотрите [Agent harnesses](/ru/reference/harnesses) перед использованием события в смешанном парке. - + `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` и `Setup`. diff --git a/docs/tr/evaluations/overview.mdx b/docs/tr/evaluations/overview.mdx index 4f09431b..60aa28d3 100644 --- a/docs/tr/evaluations/overview.mdx +++ b/docs/tr/evaluations/overview.mdx @@ -41,4 +41,4 @@ Değerlendirmeler onları tanımlayan organizasyona aittir. Bir instance'taki he -Değerlendirme ileriye doğru çalışır: şimdi dağıtılan bir sürüm, şimdi itibaren biten oturumları puanlandırır. Zaten sahip olduğunuz oturumları puanlandırmak için, [onları geri doldurun](/tr/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file +Değerlendirme ileriye doğru çalışır: şimdi dağıtılan bir sürüm, şimdi itibaren biten oturumları puanlandırır. Zaten sahip olduğunuz oturumları puanlandırmak için, [onları geri doldurun](/tr/evaluations/deploy#zaten-sahip-olduğunuz-oturumları-puanlayın). \ No newline at end of file diff --git a/docs/tr/reference/failproof-cli.mdx b/docs/tr/reference/failproof-cli.mdx index b7146cc7..dbca3853 100644 --- a/docs/tr/reference/failproof-cli.mdx +++ b/docs/tr/reference/failproof-cli.mdx @@ -122,7 +122,7 @@ Desteklenen ağ adları `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi` Etiketler, iki kök aynı projenin kopyalarını içerdiğinde türetilen ajan kimliklerinin ad alanlarını verir. Çakışan kökler ve yinelenen etiketler, yinelenen koleksiyon veya imleç bozulmasını önlemek için reddedilir. Ekstra yol yapılandırması, daemon yeniden başlaması olmadan yeniden yüklenir. -Konteyner ortamları, dosya yapılandırılmış ekstra yolları virgülle ayrılmış bir değişkenle değiştirebilir; örneğin: +Konteyner ortamları, dosyada yapılandırılmış ekstra yolları, `FAILPROOFAI__EXTRA_PATHS` adlı virgülle ayrılmış bir değişkenle değiştirebilir; örneğin: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" diff --git a/docs/tr/start/setup.mdx b/docs/tr/start/setup.mdx index c5d162d4..386d9f27 100644 --- a/docs/tr/start/setup.mdx +++ b/docs/tr/start/setup.mdx @@ -11,7 +11,7 @@ icon: "waypoints" Merkezi oturumlar, denetimler, çevrimiçi değerlendirmeler, panolar, uyarılar ve filo politikası dağıtımı ekleyin. - + Kuruluş kontrolleri, kapsamlı anahtarlar, özel altyapı ve dağıtıma özgü güvenlik gereksinimlerini kullanın. diff --git a/docs/vi/evaluations/overview.mdx b/docs/vi/evaluations/overview.mdx index 2a6f2361..350ea0aa 100644 --- a/docs/vi/evaluations/overview.mdx +++ b/docs/vi/evaluations/overview.mdx @@ -16,9 +16,9 @@ Một đánh giá chấm điểm một phiên agent hoàn tất. Khi một phiê | --- | --- | --- | | Được viết | Trong bảng điều khiển, ở **Analyze → eval authoring** | Bằng Python, với [Evaluator SDK](/vi/reference/evaluator-sdk) | | Chạy | Trên trình đánh giá được quản lý của Failproof AI, trong một sandbox | Trên cơ sở hạ tầng của bạn | -| Tốt nhất cho | Các kiểm tra xác định, dựa trên mã | Các tr裁判 LLM, lệnh gọi mô hình, gói, bí mật, truy cập mạng, xử lý nặng | +| Tốt nhất cho | Các kiểm tra xác định, dựa trên mã | Các giám khảo LLM, lệnh gọi mô hình, gói, bí mật, truy cập mạng, xử lý nặng | -Python được lưu trữ được thiết kế một cách cố ý nhỏ: một biểu thức, không có nhập khẩu, không có mạng. Bất cứ điều gì cần một mô hình — một tr裁判 LLM chấm điểm xem liệu một câu trả lời có phù hợp hay không, chẳng hạn — chạy trong worker của riêng bạn. Cả hai loại đều không cần kết nối vào: worker yêu cầu các phiên hoàn tất và gửi kết quả qua HTTPS đi ra ngoài. +Python được lưu trữ được thiết kế một cách cố ý nhỏ: một biểu thức, không có nhập khẩu, không có mạng. Bất cứ điều gì cần một mô hình — một giám khảo LLM chấm điểm xem liệu một câu trả lời có phù hợp hay không, chẳng hạn — chạy trong worker của riêng bạn. Cả hai loại đều không cần kết nối vào: worker yêu cầu các phiên hoàn tất và gửi kết quả qua HTTPS đi ra ngoài. ## Mỗi tổ chức đánh giá các agent của riêng nó @@ -41,4 +41,4 @@ Các đánh giá thuộc về tổ chức xác định chúng. Mỗi tổ chức -Đánh giá chạy về phía trước: một phiên bản triển khai ngay bây giờ chấm điểm các phiên hoàn tất từ bây giờ trở đi. Để chấm điểm các phiên bạn đã có, [backfill chúng](/vi/evaluations/deploy#score-sessions-you-already-have). \ No newline at end of file +Đánh giá chạy về phía trước: một phiên bản triển khai ngay bây giờ chấm điểm các phiên hoàn tất từ bây giờ trở đi. Để chấm điểm các phiên bạn đã có, [backfill chúng](/vi/evaluations/deploy#chấm-điểm-các-phiên-làm-việc-bạn-đã-có). \ No newline at end of file diff --git a/docs/zh/evaluations/overview.mdx b/docs/zh/evaluations/overview.mdx index 66a6693d..911eed67 100644 --- a/docs/zh/evaluations/overview.mdx +++ b/docs/zh/evaluations/overview.mdx @@ -41,4 +41,4 @@ icon: "gauge" -评估按时间顺序向前执行：现在部署的版本将对从此刻起完成的会话进行评分。如需对已有的历史会话评分，请[进行回填](/zh/evaluations/deploy#score-sessions-you-already-have)。 \ No newline at end of file +评估按时间顺序向前执行：现在部署的版本将对从此刻起完成的会话进行评分。如需对已有的历史会话评分，请[进行回填](/zh/evaluations/deploy#对已有会话进行评分)。 \ No newline at end of file diff --git a/docs/zh/policies/packs.mdx b/docs/zh/policies/packs.mdx index 7e9bfce9..e77c7fd8 100644 --- a/docs/zh/policies/packs.mdx +++ b/docs/zh/policies/packs.mdx @@ -19,7 +19,7 @@ icon: "package" failproofai policies add FailproofAI/policies ``` -该包包含 38 条策略，其中清单标记为可无人值守启用的 10 条会自动开启；其余策略供您按需选择。以下列出了一些常用策略及其默认开启状态： +该包包含 38 条策略，其中清单标记为可无人值守启用的 10 条会自动开启；其余策略供您按需选择。以下列出了一些最常用的策略，以及仅执行 `policies add` 时是否会开启它们： | 策略 | 作用 | 默认开启 | | --- | --- | --- | From 54bd0c43be8470ad78e4ad7a8943536c5e251d5b Mon Sep 17 00:00:00 2001 From: NiveditJain Date: Tue, 15 Sep 2026 11:06:53 +0530 Subject: [PATCH 5/8] docs: point translated fragment links at translated headings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mintlify derives each heading's anchor from its text, so a translated heading has a translated anchor. The translator leaves link fragments in English, which points them at slugs that do not exist on the translated page. `mintlify broken-links --check-anchors` found 228 such links across the locale pages (not counting docs/i18n/*.md, whose GitHub-relative links Mintlify does not serve). 30 are new in this PR: evaluations/write and policies/deploy's setup link are new in every locale, and the retranslated cloud-cli pages renamed the headings that ko/cloud-cli and pt-br/audits/findings-and-issues link to. 51 more were already broken on main but sit in pages this PR retranslates. All 81 now target the heading at the same position in the target page. The rewrite refuses when the English and translated heading structures differ, and none did. Slugs follow Mintlify's own slugify (@mintlify/common), including its rule that an apostrophe becomes a hyphen: "L'exécuter" gives l-exécuter, not lexécuter. The 146 that remain were broken on main and are in pages this PR does not touch, mostly links to custom-agents#going-deeper and cloud-cli#audits. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NrdeSVKcfqXd1H2BwP45Ad --- docs/ar/evaluations/write.mdx | 2 +- docs/ar/policies/deploy.mdx | 2 +- docs/ar/reference/cloud-cli.mdx | 2 +- docs/ar/reference/custom-agents.mdx | 2 +- docs/ar/reference/overview.mdx | 4 ++-- docs/ar/start/quickstart.mdx | 2 +- docs/de/evaluations/write.mdx | 2 +- docs/de/policies/deploy.mdx | 2 +- docs/de/reference/cloud-cli.mdx | 2 +- docs/de/reference/custom-agents.mdx | 2 +- docs/de/reference/overview.mdx | 4 ++-- docs/de/start/quickstart.mdx | 2 +- docs/es/evaluations/write.mdx | 2 +- docs/es/policies/deploy.mdx | 2 +- docs/es/reference/cloud-cli.mdx | 2 +- docs/es/reference/custom-agents.mdx | 2 +- docs/es/reference/overview.mdx | 4 ++-- docs/es/start/quickstart.mdx | 2 +- docs/fr/evaluations/write.mdx | 2 +- docs/fr/policies/deploy.mdx | 2 +- docs/fr/reference/cloud-cli.mdx | 2 +- docs/fr/reference/custom-agents.mdx | 2 +- docs/fr/reference/overview.mdx | 4 ++-- docs/fr/start/quickstart.mdx | 2 +- docs/he/evaluations/write.mdx | 2 +- docs/he/policies/deploy.mdx | 2 +- docs/he/reference/custom-agents.mdx | 2 +- docs/he/reference/overview.mdx | 4 ++-- docs/he/start/quickstart.mdx | 2 +- docs/hi/evaluations/write.mdx | 2 +- docs/hi/policies/deploy.mdx | 2 +- docs/hi/reference/custom-agents.mdx | 2 +- docs/hi/start/quickstart.mdx | 2 +- docs/it/evaluations/write.mdx | 2 +- docs/it/policies/deploy.mdx | 2 +- docs/it/reference/cloud-cli.mdx | 2 +- docs/it/reference/custom-agents.mdx | 2 +- docs/it/reference/overview.mdx | 4 ++-- docs/it/start/quickstart.mdx | 2 +- docs/ja/evaluations/write.mdx | 2 +- docs/ja/policies/deploy.mdx | 2 +- docs/ja/reference/cloud-cli.mdx | 2 +- docs/ja/reference/custom-agents.mdx | 2 +- docs/ja/reference/overview.mdx | 4 ++-- docs/ja/start/quickstart.mdx | 2 +- docs/ko/evaluations/write.mdx | 2 +- docs/ko/policies/deploy.mdx | 2 +- docs/ko/reference/cloud-cli.mdx | 2 +- docs/ko/reference/custom-agents.mdx | 2 +- docs/ko/reference/overview.mdx | 4 ++-- docs/ko/start/quickstart.mdx | 2 +- docs/pt-br/audits/findings-and-issues.mdx | 2 +- docs/pt-br/evaluations/write.mdx | 2 +- docs/pt-br/policies/deploy.mdx | 2 +- docs/pt-br/reference/cloud-cli.mdx | 2 +- docs/pt-br/reference/custom-agents.mdx | 2 +- docs/pt-br/reference/overview.mdx | 4 ++-- docs/pt-br/start/quickstart.mdx | 2 +- docs/ru/evaluations/write.mdx | 2 +- docs/ru/policies/deploy.mdx | 2 +- docs/ru/reference/cloud-cli.mdx | 2 +- docs/ru/reference/custom-agents.mdx | 2 +- docs/ru/reference/overview.mdx | 4 ++-- docs/ru/start/quickstart.mdx | 2 +- docs/tr/evaluations/write.mdx | 2 +- docs/tr/policies/deploy.mdx | 2 +- docs/tr/reference/cloud-cli.mdx | 2 +- docs/tr/reference/custom-agents.mdx | 2 +- docs/tr/reference/overview.mdx | 4 ++-- docs/tr/start/quickstart.mdx | 2 +- docs/vi/evaluations/write.mdx | 2 +- docs/vi/policies/deploy.mdx | 2 +- docs/vi/reference/custom-agents.mdx | 2 +- docs/vi/reference/overview.mdx | 4 ++-- docs/vi/start/quickstart.mdx | 2 +- docs/zh/evaluations/write.mdx | 2 +- docs/zh/policies/deploy.mdx | 2 +- docs/zh/reference/cloud-cli.mdx | 2 +- docs/zh/reference/custom-agents.mdx | 2 +- docs/zh/reference/overview.mdx | 4 ++-- docs/zh/start/quickstart.mdx | 2 +- 81 files changed, 94 insertions(+), 94 deletions(-) diff --git a/docs/ar/evaluations/write.mdx b/docs/ar/evaluations/write.mdx index 19400fac..0a46a11d 100644 --- a/docs/ar/evaluations/write.mdx +++ b/docs/ar/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "صف ما تريد قياسه واترك للمساعد صياغة icon: "file-pen-line" --- -التقييمات المستضافة عبارة عن أكواد Python صغيرة وحتمية، مكتوبة في لوحة التحكم وتعمل على أسطول تقييم Failproof AI. المنطق الأثقل — حكم LLM، أو حزمة، أو سر، أو استدعاء شبكة — يعمل في [عاملك الخاص](#write-it-in-your-own-worker) بدلاً من ذلك. +التقييمات المستضافة عبارة عن أكواد Python صغيرة وحتمية، مكتوبة في لوحة التحكم وتعمل على أسطول تقييم Failproof AI. المنطق الأثقل — حكم LLM، أو حزمة، أو سر، أو استدعاء شبكة — يعمل في [عاملك الخاص](#اكتبه-في-عاملك-الخاص) بدلاً من ذلك. ## صغه من وصف diff --git a/docs/ar/policies/deploy.mdx b/docs/ar/policies/deploy.mdx index 6d13da67..5c579a15 100644 --- a/docs/ar/policies/deploy.mdx +++ b/docs/ar/policies/deploy.mdx @@ -16,7 +16,7 @@ icon: "cloud-upload" 1. انتقل إلى **Administration → Keys** وأنشئ مفتاحًا باستخدام `policies:pull`، حتى تتمكن الآلة من استقبال النشرات، و`events:add`، حتى تصل قراراتها إلى Cloud. - 2. اتصل بالآلة باستخدام هذا المفتاح — [ربط آلة بـ Cloud](/ar/start/setup#connect-a-machine-to-cloud) يشرح ذلك. + 2. اتصل بالآلة باستخدام هذا المفتاح — [ربط آلة بـ Cloud](/ar/start/setup#توصيل-جهاز-بـ-cloud) يشرح ذلك. 3. تأكد من ظهورها ضمن **Admin → enforcement**. diff --git a/docs/ar/reference/cloud-cli.mdx b/docs/ar/reference/cloud-cli.mdx index 77ffc250..4ca626e3 100644 --- a/docs/ar/reference/cloud-cli.mdx +++ b/docs/ar/reference/cloud-cli.mdx @@ -229,7 +229,7 @@ fp errors [OPTIONS] | --- | --- | --- | | `fp audits list` | عرض قائمة المراجعات. | `--enabled-only`; `--show-id` | | `fp audits show NAME` | عرض تعريف المراجعة واحدة وحالتها. | — | -| `fp audits create NAME` | إنشاء مراجعة وطلب تشغيلها الأول على الفور. | انظر [خيارات الإنشاء](#audit-create-options). | +| `fp audits create NAME` | إنشاء مراجعة وطلب تشغيلها الأول على الفور. | انظر [خيارات الإنشاء](#خيارات-إنشاء-المراجعة). | | `fp audits edit NAME` | استبدل إعدادات المراجعة مع الاحتفاظ بالقيم غير المحددة. | خيارات تعريف الإنشاء؛ `--name`; `--yes`, `-y` | | `fp audits delete NAME` | حذف مراجعة ونتائجها وسجل التشغيل. | `--yes`, `-y` | | `fp audits run NAME` | طلب تشغيل يدوي. | — | diff --git a/docs/ar/reference/custom-agents.mdx b/docs/ar/reference/custom-agents.mdx index 5ca2384f..9185cee2 100644 --- a/docs/ar/reference/custom-agents.mdx +++ b/docs/ar/reference/custom-agents.mdx @@ -30,7 +30,7 @@ pip install failproofai-sdk 1. انتقل إلى **Admin → Keys** وأنشئ مفتاحاً بـ `events:add`. - 2. [وصّل مُراقب Failproof إلى Cloud](/ar/start/setup#connect-a-machine-to-cloud) على جهاز الوكيل. + 2. [وصّل مُراقب Failproof إلى Cloud](/ar/start/setup#توصيل-جهاز-بـ-cloud) على جهاز الوكيل. 3. قم بتشغيل جلسة واحدة مجهزة، ثم ابحث عن معرّفها الدقيق ضمن **Observe → Events**. 4. انتقل إلى **Observe → Sessions** واختر نفس البيئة وافتح الأثر المعاد بناؤه. diff --git a/docs/ar/reference/overview.mdx b/docs/ar/reference/overview.mdx index d673bfcb..be45cd3b 100644 --- a/docs/ar/reference/overview.mdx +++ b/docs/ar/reference/overview.mdx @@ -22,7 +22,7 @@ icon: "braces" قم بتكوين الالتقاط المحلي والخطافات والسياسات والتدقيق والتسليم وحالة الجهاز. - + الاستعلام والإدارة لجلسات Cloud والتدقيق والمشاكل والتنبيهات والمفاتيح والمستخدمين والإعدادات. @@ -79,6 +79,6 @@ icon: "braces" استخدم `fp --json sessions ...` عندما تستهلك أداة أخرى النتيجة. يجب أن تأتي الأعلام العامة مثل `--json` و `--org` و `--base-url` قبل الأمر. - انظر إلى [مرجع Failproof AI CLI](/ar/reference/failproof-cli) لأوامر محلية و [مرجع Failproof Cloud CLI](/ar/reference/cloud-cli#cli-commands) لأوامر `fp`. + انظر إلى [مرجع Failproof AI CLI](/ar/reference/failproof-cli) لأوامر محلية و [مرجع Failproof Cloud CLI](/ar/reference/cloud-cli#أوامر-cli) لأوامر `fp`. \ No newline at end of file diff --git a/docs/ar/start/quickstart.mdx b/docs/ar/start/quickstart.mdx index bdd1425f..4147aa12 100644 --- a/docs/ar/start/quickstart.mdx +++ b/docs/ar/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - يتم التحقق من حظر استدعاء الأداة قبل تشغيلها على الـ 12 جميعًا. يتم التحقق من بوابات نهاية الدوران على 8 — انظر [قدرة الإنفاذ](/ar/reference/harnesses#enforcement-capability) لمصفوفة كل نظام. + يتم التحقق من حظر استدعاء الأداة قبل تشغيلها على الـ 12 جميعًا. يتم التحقق من بوابات نهاية الدوران على 8 — انظر [قدرة الإنفاذ](/ar/reference/harnesses#قدرة-الإنفاذ) لمصفوفة كل نظام. ربط الخطافات لا يفعل أي سياسة. الإعداد يختار عن قصد لا شيء — هذا قرارك — لذا خذ حزمة: diff --git a/docs/de/evaluations/write.mdx b/docs/de/evaluations/write.mdx index 8d49af3a..bec03dfb 100644 --- a/docs/de/evaluations/write.mdx +++ b/docs/de/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "Beschreibe, was gemessen werden soll, und lass den Assistenten ein icon: "file-pen-line" --- -Gehostete Evaluierungen sind kleine, deterministische Python-Programme, die im Dashboard geschrieben und auf der Evaluator-Flotte von Failproof AI ausgeführt werden. Aufwendigere Logik — ein LLM-Richter, ein Paket, ein Secret, ein Netzwerkaufruf — läuft stattdessen [in deinem eigenen Worker](#write-it-in-your-own-worker). +Gehostete Evaluierungen sind kleine, deterministische Python-Programme, die im Dashboard geschrieben und auf der Evaluator-Flotte von Failproof AI ausgeführt werden. Aufwendigere Logik — ein LLM-Richter, ein Paket, ein Secret, ein Netzwerkaufruf — läuft stattdessen [in deinem eigenen Worker](#im-eigenen-worker-schreiben). ## Aus einer Beschreibung entwerfen diff --git a/docs/de/policies/deploy.mdx b/docs/de/policies/deploy.mdx index 42209a55..1957a7f7 100644 --- a/docs/de/policies/deploy.mdx +++ b/docs/de/policies/deploy.mdx @@ -16,7 +16,7 @@ Eine Maschine erscheint unter **Admin → enforcement**, sobald sie mit Cloud ve 1. Gehen Sie zu **Administration → Keys** und erstellen Sie einen Schlüssel mit `policies:pull`, damit die Maschine Bereitstellungen empfangen kann, und `events:add`, damit ihre Entscheidungen Cloud erreichen. - 2. Verbinden Sie die Maschine mit diesem Schlüssel — [Eine Maschine mit Cloud verbinden](/de/start/setup#connect-a-machine-to-cloud) führt Sie durch den Vorgang. + 2. Verbinden Sie die Maschine mit diesem Schlüssel — [Eine Maschine mit Cloud verbinden](/de/start/setup#eine-maschine-mit-der-cloud-verbinden) führt Sie durch den Vorgang. 3. Bestätigen Sie, dass sie unter **Admin → enforcement** angezeigt wird. diff --git a/docs/de/reference/cloud-cli.mdx b/docs/de/reference/cloud-cli.mdx index 25d68abb..07de74d0 100644 --- a/docs/de/reference/cloud-cli.mdx +++ b/docs/de/reference/cloud-cli.mdx @@ -229,7 +229,7 @@ Alert-Schweregrade sind `info`, `warning` und `critical`. Trigger-Arten sind `me | --- | --- | --- | | `fp audits list` | Audits auflisten. | `--enabled-only`; `--show-id` | | `fp audits show NAME` | Eine Audit-Definition und ihren Status anzeigen. | — | -| `fp audits create NAME` | Einen Audit erstellen und sofort seinen ersten Durchlauf einreihen. | Siehe [Erstellungsoptionen](#audit-create-options). | +| `fp audits create NAME` | Einen Audit erstellen und sofort seinen ersten Durchlauf einreihen. | Siehe [Erstellungsoptionen](#audit-erstellungsoptionen). | | `fp audits edit NAME` | Audit-Einstellungen ersetzen, ohne nicht angegebene Werte zu verändern. | Definitionsoptionen für die Erstellung; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | Einen Audit, seine Findings und den Ausführungsverlauf löschen. | `--yes`, `-y` | | `fp audits run NAME` | Einen manuellen Durchlauf einreihen. | — | diff --git a/docs/de/reference/custom-agents.mdx b/docs/de/reference/custom-agents.mdx index b66cb4dd..99b197f9 100644 --- a/docs/de/reference/custom-agents.mdx +++ b/docs/de/reference/custom-agents.mdx @@ -30,7 +30,7 @@ Das Paket wird als `failproofai-sdk` installiert und in Python als `failproofai_ 1. Gehen Sie zu **Admin → Keys** und erstellen Sie einen Schlüssel mit `events:add`. - 2. [Verbinden Sie den Failproof-Daemon mit Cloud](/de/start/setup#connect-a-machine-to-cloud) auf der Agent-Maschine. + 2. [Verbinden Sie den Failproof-Daemon mit Cloud](/de/start/setup#eine-maschine-mit-der-cloud-verbinden) auf der Agent-Maschine. 3. Führen Sie eine instrumentierte Sitzung aus und suchen Sie die genaue ID unter **Observe → Events**. 4. Gehen Sie zu **Observe → Sessions**, wählen Sie dieselbe Umgebung und öffnen Sie den rekonstruierten Trace. diff --git a/docs/de/reference/overview.mdx b/docs/de/reference/overview.mdx index 0779bbc7..abe056d5 100644 --- a/docs/de/reference/overview.mdx +++ b/docs/de/reference/overview.mdx @@ -22,7 +22,7 @@ Wähle die Integration, die am besten zu deiner bestehenden Agent-Umgebung passt Lokale Erfassung, Hooks, Policies, Audits, Zustellung und Maschinenzustand konfigurieren. - + Cloud-Sessions, Audits, Issues, Alerts, Schlüssel, Benutzer und Einstellungen abfragen und verwalten. @@ -79,6 +79,6 @@ Die generierte [HTTP-API-Referenz](/de/reference/http-api) deckt die öffentlich Verwende `fp --json sessions ...`, wenn das Ergebnis von einem anderen Tool weiterverarbeitet wird. Globale Flags wie `--json`, `--org` und `--base-url` müssen vor dem Befehl stehen. - Siehe die [Failproof AI CLI-Referenz](/de/reference/failproof-cli) für lokale Befehle und die [Failproof Cloud CLI-Referenz](/de/reference/cloud-cli#cli-commands) für `fp`-Befehle. + Siehe die [Failproof AI CLI-Referenz](/de/reference/failproof-cli) für lokale Befehle und die [Failproof Cloud CLI-Referenz](/de/reference/cloud-cli#cli-befehle) für `fp`-Befehle. \ No newline at end of file diff --git a/docs/de/start/quickstart.mdx b/docs/de/start/quickstart.mdx index 95748629..308137fe 100644 --- a/docs/de/start/quickstart.mdx +++ b/docs/de/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # ein Slack/Telegram-Gateway ``` - Das Blockieren eines Tool-Aufrufs vor seiner Ausführung ist auf allen 12 verifiziert. Turn-End-Gates sind auf 8 verifiziert — die harness-spezifische Matrix ist unter [Durchsetzungsfähigkeit](/de/reference/harnesses#enforcement-capability) zu finden. + Das Blockieren eines Tool-Aufrufs vor seiner Ausführung ist auf allen 12 verifiziert. Turn-End-Gates sind auf 8 verifiziert — die harness-spezifische Matrix ist unter [Durchsetzungsfähigkeit](/de/reference/harnesses#enforcement-fähigkeiten) zu finden. Das Verbinden der Hooks aktiviert keine Richtlinie. Das Setup wählt bewusst keine aus – diese Entscheidung liegt bei dir – nimm daher ein Paket: diff --git a/docs/es/evaluations/write.mdx b/docs/es/evaluations/write.mdx index 8cf2cedc..356580a1 100644 --- a/docs/es/evaluations/write.mdx +++ b/docs/es/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "Describe qué medir y deja que el asistente genere una evaluación icon: "file-pen-line" --- -Las evaluaciones alojadas son pequeñas piezas de Python deterministas, escritas en el dashboard y ejecutadas en la flota de evaluadores de Failproof AI. La lógica más pesada — un juez LLM, un paquete, un secreto, una llamada de red — se ejecuta en [tu propio worker](#write-it-in-your-own-worker). +Las evaluaciones alojadas son pequeñas piezas de Python deterministas, escritas en el dashboard y ejecutadas en la flota de evaluadores de Failproof AI. La lógica más pesada — un juez LLM, un paquete, un secreto, una llamada de red — se ejecuta en [tu propio worker](#escribirlo-en-tu-propio-worker). ## Generar a partir de una descripción diff --git a/docs/es/policies/deploy.mdx b/docs/es/policies/deploy.mdx index 61bdf7b6..6ccee8d9 100644 --- a/docs/es/policies/deploy.mdx +++ b/docs/es/policies/deploy.mdx @@ -16,7 +16,7 @@ Una máquina aparece en **Admin → enforcement** una vez que está conectada a 1. Ve a **Administración → Claves** y crea una clave con `policies:pull`, para que la máquina pueda recibir despliegues, y `events:add`, para que sus decisiones lleguen a Cloud. - 2. Conecta la máquina con esa clave — [Conectar una máquina a Cloud](/es/start/setup#connect-a-machine-to-cloud) te guía paso a paso. + 2. Conecta la máquina con esa clave — [Conectar una máquina a Cloud](/es/start/setup#conectar-una-máquina-a-cloud) te guía paso a paso. 3. Confirma que aparece en **Admin → enforcement**. diff --git a/docs/es/reference/cloud-cli.mdx b/docs/es/reference/cloud-cli.mdx index cf11a4e5..0da00cbc 100644 --- a/docs/es/reference/cloud-cli.mdx +++ b/docs/es/reference/cloud-cli.mdx @@ -229,7 +229,7 @@ Las severidades de alerta son `info`, `warning` y `critical`. Los tipos de dispa | --- | --- | --- | | `fp audits list` | Lista las auditorías. | `--enabled-only`; `--show-id` | | `fp audits show NAME` | Muestra una definición de auditoría y su estado. | — | -| `fp audits create NAME` | Crea una auditoría y pone en cola su primera ejecución inmediatamente. | Ver [opciones de creación](#audit-create-options). | +| `fp audits create NAME` | Crea una auditoría y pone en cola su primera ejecución inmediatamente. | Ver [opciones de creación](#opciones-de-creación-de-auditorías). | | `fp audits edit NAME` | Reemplaza la configuración de la auditoría conservando los valores no especificados. | opciones de definición de creación; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | Elimina una auditoría, sus hallazgos y el historial de ejecuciones. | `--yes`, `-y` | | `fp audits run NAME` | Pone en cola una ejecución manual. | — | diff --git a/docs/es/reference/custom-agents.mdx b/docs/es/reference/custom-agents.mdx index 5dcdfc58..24e10f98 100644 --- a/docs/es/reference/custom-agents.mdx +++ b/docs/es/reference/custom-agents.mdx @@ -30,7 +30,7 @@ El paquete se instala como `failproofai-sdk` y se importa en Python como `failpr 1. Ve a **Admin → Keys** y crea una clave con `events:add`. - 2. [Conecta el daemon de Failproof a Cloud](/es/start/setup#connect-a-machine-to-cloud) en la máquina del agente. + 2. [Conecta el daemon de Failproof a Cloud](/es/start/setup#conectar-una-máquina-a-cloud) en la máquina del agente. 3. Ejecuta una sesión instrumentada y luego busca su ID exacto en **Observe → Events**. 4. Ve a **Observe → Sessions**, selecciona el mismo entorno y abre el trace reconstruido. diff --git a/docs/es/reference/overview.mdx b/docs/es/reference/overview.mdx index 3022badd..f1549258 100644 --- a/docs/es/reference/overview.mdx +++ b/docs/es/reference/overview.mdx @@ -22,7 +22,7 @@ Elige la integración más adecuada para donde ya se ejecuta tu agente. Configura la captura local, hooks, políticas, auditorías, entrega y estado de la máquina. - + Consulta y administra sesiones, auditorías, incidencias, alertas, claves, usuarios y configuración en la nube. @@ -79,6 +79,6 @@ La [referencia de la API HTTP](/es/reference/http-api) generada cubre la superfi Usa `fp --json sessions ...` cuando otra herramienta vaya a consumir el resultado. Los flags globales como `--json`, `--org` y `--base-url` deben ir antes del comando. - Consulta la [referencia del Failproof AI CLI](/es/reference/failproof-cli) para los comandos locales y la [referencia del Failproof Cloud CLI](/es/reference/cloud-cli#cli-commands) para los comandos `fp`. + Consulta la [referencia del Failproof AI CLI](/es/reference/failproof-cli) para los comandos locales y la [referencia del Failproof Cloud CLI](/es/reference/cloud-cli#comandos-de-la-cli) para los comandos `fp`. \ No newline at end of file diff --git a/docs/es/start/quickstart.mdx b/docs/es/start/quickstart.mdx index dc6de9f1..74838cf5 100644 --- a/docs/es/start/quickstart.mdx +++ b/docs/es/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # una gateway de Slack/Telegram ``` - El bloqueo de una llamada de herramienta antes de ejecutarse está verificado en los 12. Las compuertas al final del turno están verificadas en 8 — consulta la [capacidad de aplicación](/es/reference/harnesses#enforcement-capability) para ver la matriz por harness. + El bloqueo de una llamada de herramienta antes de ejecutarse está verificado en los 12. Las compuertas al final del turno están verificadas en 8 — consulta la [capacidad de aplicación](/es/reference/harnesses#capacidades-de-aplicación) para ver la matriz por harness. Conectar los hooks no habilita ninguna política. La configuración no elige ninguna deliberadamente — esa decisión es tuya — así que toma un pack: diff --git a/docs/fr/evaluations/write.mdx b/docs/fr/evaluations/write.mdx index 80b533af..d545ec29 100644 --- a/docs/fr/evaluations/write.mdx +++ b/docs/fr/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "Décrivez ce que vous souhaitez mesurer et laissez l'assistant gé icon: "file-pen-line" --- -Les évaluations hébergées sont de petits scripts Python déterministes, écrits dans le tableau de bord et exécutés sur la flotte d'évaluateurs de Failproof AI. La logique plus lourde — un juge LLM, un package, un secret, un appel réseau — s'exécute plutôt dans [votre propre worker](#write-it-in-your-own-worker). +Les évaluations hébergées sont de petits scripts Python déterministes, écrits dans le tableau de bord et exécutés sur la flotte d'évaluateurs de Failproof AI. La logique plus lourde — un juge LLM, un package, un secret, un appel réseau — s'exécute plutôt dans [votre propre worker](#l-exécuter-dans-votre-propre-worker). ## Générer une ébauche à partir d'une description diff --git a/docs/fr/policies/deploy.mdx b/docs/fr/policies/deploy.mdx index 78a4a019..dc192727 100644 --- a/docs/fr/policies/deploy.mdx +++ b/docs/fr/policies/deploy.mdx @@ -16,7 +16,7 @@ Une machine apparaît sous **Admin → enforcement** dès qu'elle est connectée 1. Allez dans **Administration → Keys** et créez une clé avec `policies:pull`, pour que la machine puisse recevoir les déploiements, et `events:add`, pour que ses décisions parviennent au Cloud. - 2. Connectez la machine avec cette clé — [Connecter une machine au Cloud](/fr/start/setup#connect-a-machine-to-cloud) vous guide pas à pas. + 2. Connectez la machine avec cette clé — [Connecter une machine au Cloud](/fr/start/setup#connecter-une-machine-au-cloud) vous guide pas à pas. 3. Confirmez qu'elle apparaît bien sous **Admin → enforcement**. diff --git a/docs/fr/reference/cloud-cli.mdx b/docs/fr/reference/cloud-cli.mdx index a9137ce4..ede81d78 100644 --- a/docs/fr/reference/cloud-cli.mdx +++ b/docs/fr/reference/cloud-cli.mdx @@ -229,7 +229,7 @@ Les niveaux de gravité des alertes sont `info`, `warning` et `critical`. Les ty | --- | --- | --- | | `fp audits list` | Lister les audits. | `--enabled-only` ; `--show-id` | | `fp audits show NAME` | Afficher une définition d'audit et son état. | — | -| `fp audits create NAME` | Créer un audit et mettre immédiatement en file d'attente sa première exécution. | Voir [options de création](#audit-create-options). | +| `fp audits create NAME` | Créer un audit et mettre immédiatement en file d'attente sa première exécution. | Voir [options de création](#options-de-création-d-audit). | | `fp audits edit NAME` | Remplacer les paramètres d'audit en conservant les valeurs non spécifiées. | options de définition de création ; `--name` ; `--yes`, `-y` | | `fp audits delete NAME` | Supprimer un audit, ses résultats et son historique d'exécution. | `--yes`, `-y` | | `fp audits run NAME` | Mettre en file d'attente une exécution manuelle. | — | diff --git a/docs/fr/reference/custom-agents.mdx b/docs/fr/reference/custom-agents.mdx index ce2feca0..f1ddb70e 100644 --- a/docs/fr/reference/custom-agents.mdx +++ b/docs/fr/reference/custom-agents.mdx @@ -30,7 +30,7 @@ Le paquet est installé sous le nom `failproofai-sdk` et importé en Python sous 1. Accédez à **Admin → Keys** et créez une clé avec `events:add`. - 2. [Connectez le daemon Failproof au Cloud](/fr/start/setup#connect-a-machine-to-cloud) sur la machine de l'agent. + 2. [Connectez le daemon Failproof au Cloud](/fr/start/setup#connecter-une-machine-au-cloud) sur la machine de l'agent. 3. Lancez une session instrumentée, puis retrouvez son ID exact sous **Observe → Events**. 4. Allez dans **Observe → Sessions**, sélectionnez le même environnement et ouvrez la trace reconstruite. diff --git a/docs/fr/reference/overview.mdx b/docs/fr/reference/overview.mdx index 156428cf..74751076 100644 --- a/docs/fr/reference/overview.mdx +++ b/docs/fr/reference/overview.mdx @@ -22,7 +22,7 @@ Choisissez l'intégration la plus proche de l'environnement dans lequel votre ag Configurez la capture locale, les hooks, les politiques, les audits, la livraison et l'état machine. - + Interrogez et administrez les sessions, audits, problèmes, alertes, clés, utilisateurs et paramètres Cloud. @@ -79,6 +79,6 @@ La [référence de l'API HTTP](/fr/reference/http-api) générée couvre la surf Utilisez `fp --json sessions ...` lorsqu'un autre outil doit consommer le résultat. Les drapeaux globaux tels que `--json`, `--org` et `--base-url` doivent être placés avant la commande. - Consultez la [référence du CLI Failproof AI](/fr/reference/failproof-cli) pour les commandes locales et la [référence du CLI Failproof Cloud](/fr/reference/cloud-cli#cli-commands) pour les commandes `fp`. + Consultez la [référence du CLI Failproof AI](/fr/reference/failproof-cli) pour les commandes locales et la [référence du CLI Failproof Cloud](/fr/reference/cloud-cli#commandes-cli) pour les commandes `fp`. \ No newline at end of file diff --git a/docs/fr/start/quickstart.mdx b/docs/fr/start/quickstart.mdx index f8aa4d75..6474b908 100644 --- a/docs/fr/start/quickstart.mdx +++ b/docs/fr/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # une passerelle Slack/Telegram ``` - Le blocage d'un appel d'outil avant son exécution est vérifié sur les 12. Les points de contrôle en fin de tour sont vérifiés sur 8 — consultez la [capacité d'application](/fr/reference/harnesses#enforcement-capability) pour la matrice par harnais. + Le blocage d'un appel d'outil avant son exécution est vérifié sur les 12. Les points de contrôle en fin de tour sont vérifiés sur 8 — consultez la [capacité d'application](/fr/reference/harnesses#capacités-d-application) pour la matrice par harnais. Le câblage des hooks n'active aucune politique. La configuration n'en choisit délibérément aucune — cette décision vous appartient — alors prenez un pack : diff --git a/docs/he/evaluations/write.mdx b/docs/he/evaluations/write.mdx index 74224bef..09fd8621 100644 --- a/docs/he/evaluations/write.mdx +++ b/docs/he/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "תאר מה למדוד והנח לעוזר לעצב הערכת Pyt icon: "file-pen-line" --- -הערכות מתארחות הן Python קטנות וקביעות, שנכתבות בלוח הבקרה ופועלות בחfleet המעריכים של Failproof AI. לוגיקה כבדה יותר — שופט LLM, חבילה, סוד, קריאת רשת — פועלת ב[עובד שלך](#write-it-in-your-own-worker) במקום זאת. +הערכות מתארחות הן Python קטנות וקביעות, שנכתבות בלוח הבקרה ופועלות בחfleet המעריכים של Failproof AI. לוגיקה כבדה יותר — שופט LLM, חבילה, סוד, קריאת רשת — פועלת ב[עובד שלך](#כתוב-זאת-בעובד-שלך) במקום זאת. ## ערוך זאת מתיאור diff --git a/docs/he/policies/deploy.mdx b/docs/he/policies/deploy.mdx index 3794c7a9..c5e536c9 100644 --- a/docs/he/policies/deploy.mdx +++ b/docs/he/policies/deploy.mdx @@ -16,7 +16,7 @@ icon: "cloud-upload" 1. לך ל־**Administration → Keys** וצור מפתח עם `policies:pull`, כדי שהמכונה תוכל לקבל פריסות, ו־`events:add`, כדי שההחלטות שלה יגיעו ל־Cloud. - 2. חבר את המכונה עם המפתח הזה — [Connect a machine to Cloud](/he/start/setup#connect-a-machine-to-cloud) מנחה דרך זה. + 2. חבר את המכונה עם המפתח הזה — [Connect a machine to Cloud](/he/start/setup#חברו-מכונה-ל-cloud) מנחה דרך זה. 3. אשר שזו מופיעה תחת **Admin → enforcement**. diff --git a/docs/he/reference/custom-agents.mdx b/docs/he/reference/custom-agents.mdx index 451f4675..c9e729ee 100644 --- a/docs/he/reference/custom-agents.mdx +++ b/docs/he/reference/custom-agents.mdx @@ -30,7 +30,7 @@ pip install failproofai-sdk 1. עבור ל-**Admin → Keys** וצור מפתח עם `events:add`. - 2. [חבר את שדכן Failproof ל-Cloud](/he/start/setup#connect-a-machine-to-cloud) על מכונת הסוכן. + 2. [חבר את שדכן Failproof ל-Cloud](/he/start/setup#חברו-מכונה-ל-cloud) על מכונת הסוכן. 3. הפעל הפעלה מעוצבת אחת, ואז מצא את המזהה המדויק שלה תחת **Observe → Events**. 4. עבור ל-**Observe → Sessions**, בחר את אותה סביבה, ופתח את העקבה שנוצרה מחדש. diff --git a/docs/he/reference/overview.mdx b/docs/he/reference/overview.mdx index 794d68d4..6c20c03f 100644 --- a/docs/he/reference/overview.mdx +++ b/docs/he/reference/overview.mdx @@ -22,7 +22,7 @@ icon: "braces" הגדר local capture, hooks, policies, audits, delivery, ו-machine state. - + שאל וניהול Cloud sessions, audits, issues, alerts, keys, users, ו-settings. @@ -79,6 +79,6 @@ icon: "braces" השתמש ב-`fp --json sessions ...` כאשר כלי אחר יצרוך את התוצאה. דגלים גלובליים כגון `--json`, `--org`, ו-`--base-url` חייבים להיות לפני הפקודה. - ראה את ה-[Failproof AI CLI reference](/he/reference/failproof-cli) לפקודות מקומיות וה-[Failproof Cloud CLI reference](/he/reference/cloud-cli#cli-commands) לפקודות `fp`. + ראה את ה-[Failproof AI CLI reference](/he/reference/failproof-cli) לפקודות מקומיות וה-[Failproof Cloud CLI reference](/he/reference/cloud-cli#פקודות-cli) לפקודות `fp`. \ No newline at end of file diff --git a/docs/he/start/quickstart.mdx b/docs/he/start/quickstart.mdx index 78e2f219..28e3c62e 100644 --- a/docs/he/start/quickstart.mdx +++ b/docs/he/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # שער Slack/Telegram ``` - חסימת קריאת כלי לפני שהוא פועל מאומתת על כל 12. שערים של קצה סיבוב מאומתים על 8 — ראה [יכולת אכיפה](/he/reference/harnesses#enforcement-capability) למטריקס ל-per-harness. + חסימת קריאת כלי לפני שהוא פועל מאומתת על כל 12. שערים של קצה סיבוב מאומתים על 8 — ראה [יכולת אכיפה](/he/reference/harnesses#יכולת-אכיפה) למטריקס ל-per-harness. חיטוב hooks מאפשר ללא מדיניות. התקנה בחרה בכוונה שום דבר — החלטה זו היא שלך — אז קחו חבילה: diff --git a/docs/hi/evaluations/write.mdx b/docs/hi/evaluations/write.mdx index 78c8d527..3e13b621 100644 --- a/docs/hi/evaluations/write.mdx +++ b/docs/hi/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "वर्णन करें कि क्या मापना icon: "file-pen-line" --- -होस्टेड मूल्यांकन छोटे, नियतात्मक Python होते हैं, जो डैशबोर्ड में लिखे जाते हैं और Failproof AI के evaluator fleet पर चलाए जाते हैं। भारी तर्क — एक LLM judge, एक पैकेज, एक secret, एक नेटवर्क कॉल — इसके बजाय [आपके अपने worker](#write-it-in-your-own-worker) में चलता है। +होस्टेड मूल्यांकन छोटे, नियतात्मक Python होते हैं, जो डैशबोर्ड में लिखे जाते हैं और Failproof AI के evaluator fleet पर चलाए जाते हैं। भारी तर्क — एक LLM judge, एक पैकेज, एक secret, एक नेटवर्क कॉल — इसके बजाय [आपके अपने worker](#इसे-अपने-worker-में-लिखें) में चलता है। ## विवरण से मसौदा तैयार करें diff --git a/docs/hi/policies/deploy.mdx b/docs/hi/policies/deploy.mdx index 55967e5a..8c1519b2 100644 --- a/docs/hi/policies/deploy.mdx +++ b/docs/hi/policies/deploy.mdx @@ -16,7 +16,7 @@ icon: "cloud-upload" 1. **Administration → Keys** पर जाएं और `policies:pull` के साथ एक कुंजी बनाएं, ताकि मशीन तैनाती प्राप्त कर सके, और `events:add`, ताकि इसके निर्णय Cloud तक पहुंचें। - 2. मशीन को उस कुंजी से कनेक्ट करें — [Cloud में एक मशीन कनेक्ट करें](/hi/start/setup#connect-a-machine-to-cloud) इसके माध्यम से चलता है। + 2. मशीन को उस कुंजी से कनेक्ट करें — [Cloud में एक मशीन कनेक्ट करें](/hi/start/setup#एक-मशीन-को-cloud-से-कनेक्ट-करें) इसके माध्यम से चलता है। 3. पुष्टि करें कि यह **Admin → enforcement** के तहत दिखाई देता है। diff --git a/docs/hi/reference/custom-agents.mdx b/docs/hi/reference/custom-agents.mdx index 908a7ba0..0ee8165a 100644 --- a/docs/hi/reference/custom-agents.mdx +++ b/docs/hi/reference/custom-agents.mdx @@ -30,7 +30,7 @@ pip install failproofai-sdk 1. **Admin → Keys** पर जाएं और `events:add` के साथ एक key बनाएं। - 2. [Failproof daemon को Cloud से कनेक्ट करें](/hi/start/setup#connect-a-machine-to-cloud) agent मशीन पर। + 2. [Failproof daemon को Cloud से कनेक्ट करें](/hi/start/setup#एक-मशीन-को-cloud-से-कनेक्ट-करें) agent मशीन पर। 3. एक instrumented सेशन चलाएं, फिर **Observe → Events** के तहत इसकी सटीक ID खोजें। 4. **Observe → Sessions** पर जाएं, एक ही environment चुनें, और पुनर्निर्मित trace खोलें। diff --git a/docs/hi/start/quickstart.mdx b/docs/hi/start/quickstart.mdx index d7db1253..080c9b7c 100644 --- a/docs/hi/start/quickstart.mdx +++ b/docs/hi/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - एक टूल कॉल को इसे चलाने से पहले ब्लॉक करना सभी 12 पर सत्यापित है। टर्न-एंड गेट 8 पर सत्यापित हैं — प्रति-harness मैट्रिक्स के लिए [enforcement capability](/hi/reference/harnesses#enforcement-capability) देखें। + एक टूल कॉल को इसे चलाने से पहले ब्लॉक करना सभी 12 पर सत्यापित है। टर्न-एंड गेट 8 पर सत्यापित हैं — प्रति-harness मैट्रिक्स के लिए [enforcement capability](/hi/reference/harnesses#प्रवर्तन-क्षमता) देखें। हुक वायर करना कोई नीति सक्षम नहीं करता है। सेटअप जानबूझकर कोई नहीं चुनता है — वह निर्णय आपका है — इसलिए एक पैक लें: diff --git a/docs/it/evaluations/write.mdx b/docs/it/evaluations/write.mdx index 75d81a95..bda5c8c5 100644 --- a/docs/it/evaluations/write.mdx +++ b/docs/it/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "Descrivi cosa misurare e lascia che l'assistente rediga una valuta icon: "file-pen-line" --- -Le valutazioni ospitate sono piccoli Python deterministici, scritti nel dashboard ed eseguiti sulla flotta di valutatori di Failproof AI. La logica più complessa — un giudice LLM, un pacchetto, un segreto, una chiamata di rete — viene eseguita nel [tuo worker](#write-it-in-your-own-worker). +Le valutazioni ospitate sono piccoli Python deterministici, scritti nel dashboard ed eseguiti sulla flotta di valutatori di Failproof AI. La logica più complessa — un giudice LLM, un pacchetto, un segreto, una chiamata di rete — viene eseguita nel [tuo worker](#scrivi-nel-tuo-worker). ## Redila da una descrizione diff --git a/docs/it/policies/deploy.mdx b/docs/it/policies/deploy.mdx index 48017d30..7e6cb6f9 100644 --- a/docs/it/policies/deploy.mdx +++ b/docs/it/policies/deploy.mdx @@ -16,7 +16,7 @@ Una macchina appare in **Admin → enforcement** una volta connessa a Cloud. Se 1. Vai a **Administration → Keys** e crea una chiave con `policies:pull`, in modo che la macchina possa ricevere distribuzioni, e `events:add`, in modo che le sue decisioni raggiungano Cloud. - 2. Connetti la macchina con quella chiave — [Connect a machine to Cloud](/it/start/setup#connect-a-machine-to-cloud) ti spiega come. + 2. Connetti la macchina con quella chiave — [Connect a machine to Cloud](/it/start/setup#connetti-una-macchina-a-cloud) ti spiega come. 3. Conferma che appare in **Admin → enforcement**. diff --git a/docs/it/reference/cloud-cli.mdx b/docs/it/reference/cloud-cli.mdx index 5495eb12..036c8ce1 100644 --- a/docs/it/reference/cloud-cli.mdx +++ b/docs/it/reference/cloud-cli.mdx @@ -229,7 +229,7 @@ Le severità degli alert sono `info`, `warning` e `critical`. I tipi di trigger | --- | --- | --- | | `fp audits list` | Elenca gli audit. | `--enabled-only`; `--show-id` | | `fp audits show NAME` | Mostra una definizione di audit e lo stato. | — | -| `fp audits create NAME` | Crea un audit e metti subito in coda la sua prima esecuzione. | Vedi [opzioni di creazione](#audit-create-options). | +| `fp audits create NAME` | Crea un audit e metti subito in coda la sua prima esecuzione. | Vedi [opzioni di creazione](#opzioni-di-creazione-di-audit). | | `fp audits edit NAME` | Sostituisci le impostazioni di audit mantenendo i valori non specificati. | opzioni di definizione create; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | Elimina un audit, i suoi findings e la cronologia di esecuzione. | `--yes`, `-y` | | `fp audits run NAME` | Metti in coda un'esecuzione manuale. | — | diff --git a/docs/it/reference/custom-agents.mdx b/docs/it/reference/custom-agents.mdx index 5ef9d637..6459d750 100644 --- a/docs/it/reference/custom-agents.mdx +++ b/docs/it/reference/custom-agents.mdx @@ -30,7 +30,7 @@ Il pacchetto è installato come `failproofai-sdk` e importato in Python come `fa 1. Vai a **Admin → Keys** e crea una chiave con `events:add`. - 2. [Connetti il daemon Failproof al Cloud](/it/start/setup#connect-a-machine-to-cloud) sulla macchina dell'agente. + 2. [Connetti il daemon Failproof al Cloud](/it/start/setup#connetti-una-macchina-a-cloud) sulla macchina dell'agente. 3. Esegui una sessione strumentata, quindi trova il suo ID esatto in **Observe → Events**. 4. Vai a **Observe → Sessions**, seleziona lo stesso ambiente e apri la traccia ricostruita. diff --git a/docs/it/reference/overview.mdx b/docs/it/reference/overview.mdx index 2bff4348..6f575ee3 100644 --- a/docs/it/reference/overview.mdx +++ b/docs/it/reference/overview.mdx @@ -22,7 +22,7 @@ Scegli l'integrazione più vicina a dove il tuo agent è già in esecuzione. Configura acquisizione locale, hook, policy, audit, consegna e stato della macchina. - + Interroga e amministra sessioni Cloud, audit, problemi, avvisi, chiavi, utenti e impostazioni. @@ -79,6 +79,6 @@ Il [riferimento dell'API HTTP](/it/reference/http-api) generato copre la superfi Usa `fp --json sessions ...` quando un altro strumento consumerà il risultato. I flag globali come `--json`, `--org` e `--base-url` devono venire prima del comando. - Vedi il [riferimento della Failproof AI CLI](/it/reference/failproof-cli) per i comandi locali e il [riferimento della Failproof Cloud CLI](/it/reference/cloud-cli#cli-commands) per i comandi `fp`. + Vedi il [riferimento della Failproof AI CLI](/it/reference/failproof-cli) per i comandi locali e il [riferimento della Failproof Cloud CLI](/it/reference/cloud-cli#comandi-cli) per i comandi `fp`. \ No newline at end of file diff --git a/docs/it/start/quickstart.mdx b/docs/it/start/quickstart.mdx index e293d2e8..332dd617 100644 --- a/docs/it/start/quickstart.mdx +++ b/docs/it/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - Il blocco di una chiamata di tool prima che venga eseguita è verificato su tutti i 12. I gate di fine turno sono verificati su 8 — consulta [enforcement capability](/it/reference/harnesses#enforcement-capability) per la matrice per harness. + Il blocco di una chiamata di tool prima che venga eseguita è verificato su tutti i 12. I gate di fine turno sono verificati su 8 — consulta [enforcement capability](/it/reference/harnesses#capacità-di-applicazione) per la matrice per harness. Il collegamento dei hook non abilita alcuna policy. La configurazione deliberatamente non ne sceglie nessuna — quella decisione è tua — quindi prendi un pacchetto: diff --git a/docs/ja/evaluations/write.mdx b/docs/ja/evaluations/write.mdx index 5539ed72..9663de91 100644 --- a/docs/ja/evaluations/write.mdx +++ b/docs/ja/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "測定内容を説明してアシスタントにホスト型Python icon: "file-pen-line" --- -ホスト型評価は、ダッシュボードで記述してFailproof AIのエバリュエーターフリート上で実行される、小さな決定論的なPythonコードです。より重い処理（LLMジャッジ、パッケージ、シークレット、ネットワーク呼び出しなど）は、代わりに[お客様自身のワーカー](#write-it-in-your-own-worker)上で実行されます。 +ホスト型評価は、ダッシュボードで記述してFailproof AIのエバリュエーターフリート上で実行される、小さな決定論的なPythonコードです。より重い処理（LLMジャッジ、パッケージ、シークレット、ネットワーク呼び出しなど）は、代わりに[お客様自身のワーカー](#お客様自身のワーカーで記述する)上で実行されます。 ## 説明から下書きを作成する diff --git a/docs/ja/policies/deploy.mdx b/docs/ja/policies/deploy.mdx index 80bfe211..fdcfbc87 100644 --- a/docs/ja/policies/deploy.mdx +++ b/docs/ja/policies/deploy.mdx @@ -16,7 +16,7 @@ icon: "cloud-upload" 1. **Administration → Keys** に移動し、`policies:pull`（デプロイメントの受信用）と `events:add`（判定結果を Cloud に送信するため）の権限を持つキーを作成します。 - 2. そのキーを使用してマシンを接続します。手順については [マシンを Cloud に接続する](/ja/start/setup#connect-a-machine-to-cloud) を参照してください。 + 2. そのキーを使用してマシンを接続します。手順については [マシンを Cloud に接続する](/ja/start/setup#マシンをcloudに接続する) を参照してください。 3. **Admin → enforcement** にマシンが表示されることを確認します。 diff --git a/docs/ja/reference/cloud-cli.mdx b/docs/ja/reference/cloud-cli.mdx index c32b4b48..3475c08c 100644 --- a/docs/ja/reference/cloud-cli.mdx +++ b/docs/ja/reference/cloud-cli.mdx @@ -229,7 +229,7 @@ fp errors [OPTIONS] | --- | --- | --- | | `fp audits list` | 監査を一覧表示します。 | `--enabled-only`; `--show-id` | | `fp audits show NAME` | 1つの監査定義と状態を表示します。 | — | -| `fp audits create NAME` | 監査を作成し、最初の実行を即座にキューに入れます。 | [作成オプション](#audit-create-options)を参照。 | +| `fp audits create NAME` | 監査を作成し、最初の実行を即座にキューに入れます。 | [作成オプション](#監査の作成オプション)を参照。 | | `fp audits edit NAME` | 指定されていない値を保持しながら監査設定を置き換えます。 | create定義オプション; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | 監査、その所見、および実行履歴を削除します。 | `--yes`, `-y` | | `fp audits run NAME` | 手動実行をキューに入れます。 | — | diff --git a/docs/ja/reference/custom-agents.mdx b/docs/ja/reference/custom-agents.mdx index 31893c81..2233c753 100644 --- a/docs/ja/reference/custom-agents.mdx +++ b/docs/ja/reference/custom-agents.mdx @@ -30,7 +30,7 @@ pip install failproofai-sdk 1. **Admin → Keys** で `events:add` 権限を持つキーを作成します。 - 2. エージェントマシン上で [Failproof デーモンをクラウドに接続](/ja/start/setup#connect-a-machine-to-cloud) します。 + 2. エージェントマシン上で [Failproof デーモンをクラウドに接続](/ja/start/setup#マシンをcloudに接続する) します。 3. インストゥルメントされたセッションを1回実行し、**Observe → Events** で正確な ID を確認します。 4. **Observe → Sessions** に移動して同じ環境を選択し、再構築されたトレースを開きます。 diff --git a/docs/ja/reference/overview.mdx b/docs/ja/reference/overview.mdx index c6e9a659..37560a1e 100644 --- a/docs/ja/reference/overview.mdx +++ b/docs/ja/reference/overview.mdx @@ -22,7 +22,7 @@ icon: "braces" ローカルキャプチャ、フック、ポリシー、監査、デリバリー、マシン状態を設定します。 - + クラウドのセッション、監査、Issue、アラート、キー、ユーザー、設定を照会・管理します。 @@ -79,6 +79,6 @@ icon: "braces" 別のツールが結果を処理する場合は `fp --json sessions ...` を使用してください。`--json`、`--org`、`--base-url` などのグローバルフラグはコマンドの前に指定する必要があります。 - ローカルコマンドについては[Failproof AI CLIリファレンス](/ja/reference/failproof-cli)を、`fp` コマンドについては[Failproof Cloud CLIリファレンス](/ja/reference/cloud-cli#cli-commands)を参照してください。 + ローカルコマンドについては[Failproof AI CLIリファレンス](/ja/reference/failproof-cli)を、`fp` コマンドについては[Failproof Cloud CLIリファレンス](/ja/reference/cloud-cli#cliコマンド)を参照してください。 \ No newline at end of file diff --git a/docs/ja/start/quickstart.mdx b/docs/ja/start/quickstart.mdx index 6c3be338..394df8eb 100644 --- a/docs/ja/start/quickstart.mdx +++ b/docs/ja/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # Slack/Telegramゲートウェイ ``` - 実行前のツールコールのブロックは12種類すべてで検証済みです。ターン終了ゲートは8種類で検証済みです — ハーネスごとのマトリクスは[強制執行機能](/ja/reference/harnesses#enforcement-capability)をご覧ください。 + 実行前のツールコールのブロックは12種類すべてで検証済みです。ターン終了ゲートは8種類で検証済みです — ハーネスごとのマトリクスは[強制執行機能](/ja/reference/harnesses#強制適用の機能)をご覧ください。 フックの接続によってポリシーは有効になりません。セットアップは意図的にポリシーを選択しません — その決定はあなたに委ねられています — パックを取得してください： diff --git a/docs/ko/evaluations/write.mdx b/docs/ko/evaluations/write.mdx index 1b3f2dc2..eef3568f 100644 --- a/docs/ko/evaluations/write.mdx +++ b/docs/ko/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "측정할 내용을 설명하면 어시스턴트가 호스팅된 P icon: "file-pen-line" --- -호스팅 평가는 간결하고 결정론적인 Python 코드로, 대시보드에서 작성하고 Failproof AI의 평가자 플릿에서 실행됩니다. LLM 판정자, 패키지, 시크릿, 네트워크 호출 등 무거운 로직은 대신 [사용자 자신의 워커](#write-it-in-your-own-worker)에서 실행됩니다. +호스팅 평가는 간결하고 결정론적인 Python 코드로, 대시보드에서 작성하고 Failproof AI의 평가자 플릿에서 실행됩니다. LLM 판정자, 패키지, 시크릿, 네트워크 호출 등 무거운 로직은 대신 [사용자 자신의 워커](#사용자-자신의-워커에서-작성하기)에서 실행됩니다. ## 설명으로 초안 작성하기 diff --git a/docs/ko/policies/deploy.mdx b/docs/ko/policies/deploy.mdx index 5c886294..0ace9f1f 100644 --- a/docs/ko/policies/deploy.mdx +++ b/docs/ko/policies/deploy.mdx @@ -16,7 +16,7 @@ icon: "cloud-upload" 1. **Administration → Keys**로 이동하여 키를 생성합니다. 머신이 배포를 수신할 수 있도록 `policies:pull` 권한을, Cloud로 결정 내용을 전송할 수 있도록 `events:add` 권한을 부여합니다. - 2. 해당 키로 머신을 연결합니다. — [머신을 Cloud에 연결하기](/ko/start/setup#connect-a-machine-to-cloud)에서 자세한 과정을 안내합니다. + 2. 해당 키로 머신을 연결합니다. — [머신을 Cloud에 연결하기](/ko/start/setup#cloud에-머신-연결)에서 자세한 과정을 안내합니다. 3. **Admin → enforcement** 아래에 머신이 표시되는지 확인합니다. diff --git a/docs/ko/reference/cloud-cli.mdx b/docs/ko/reference/cloud-cli.mdx index c2b03e94..24ab6038 100644 --- a/docs/ko/reference/cloud-cli.mdx +++ b/docs/ko/reference/cloud-cli.mdx @@ -229,7 +229,7 @@ fp errors [OPTIONS] | --- | --- | --- | | `fp audits list` | 감사 목록을 표시합니다. | `--enabled-only`; `--show-id` | | `fp audits show NAME` | 감사 정의 하나와 상태를 표시합니다. | — | -| `fp audits create NAME` | 감사를 생성하고 즉시 첫 번째 실행을 대기열에 추가합니다. | [create 옵션](#audit-create-options)을 참조하세요. | +| `fp audits create NAME` | 감사를 생성하고 즉시 첫 번째 실행을 대기열에 추가합니다. | [create 옵션](#감사-create-옵션)을 참조하세요. | | `fp audits edit NAME` | 지정되지 않은 값은 유지하면서 감사 설정을 교체합니다. | create 정의 옵션; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | 감사, 발견 사항 및 실행 기록을 삭제합니다. | `--yes`, `-y` | | `fp audits run NAME` | 수동 실행을 대기열에 추가합니다. | — | diff --git a/docs/ko/reference/custom-agents.mdx b/docs/ko/reference/custom-agents.mdx index 9c0c3b6d..7f96a584 100644 --- a/docs/ko/reference/custom-agents.mdx +++ b/docs/ko/reference/custom-agents.mdx @@ -30,7 +30,7 @@ pip install failproofai-sdk 1. **Admin → Keys**로 이동하여 `events:add` 권한을 가진 키를 생성합니다. - 2. 에이전트 머신에서 [Failproof 데몬을 클라우드에 연결](/ko/start/setup#connect-a-machine-to-cloud)합니다. + 2. 에이전트 머신에서 [Failproof 데몬을 클라우드에 연결](/ko/start/setup#cloud에-머신-연결)합니다. 3. 계측된 세션을 한 번 실행한 후, **Observe → Events**에서 정확한 ID를 확인합니다. 4. **Observe → Sessions**으로 이동하여 동일한 환경을 선택하고 재구성된 트레이스를 엽니다. diff --git a/docs/ko/reference/overview.mdx b/docs/ko/reference/overview.mdx index 26ebf211..acd8c555 100644 --- a/docs/ko/reference/overview.mdx +++ b/docs/ko/reference/overview.mdx @@ -22,7 +22,7 @@ icon: "braces" 로컬 캡처, 훅, 정책, 감사, 전달, 머신 상태를 설정합니다. - + Cloud 세션, 감사, 이슈, 알림, 키, 사용자, 설정을 조회하고 관리합니다. @@ -79,6 +79,6 @@ icon: "braces" 다른 도구가 결과를 사용할 경우 `fp --json sessions ...`를 활용하세요. `--json`, `--org`, `--base-url`과 같은 전역 플래그는 명령어 앞에 위치해야 합니다. - 로컬 명령어는 [Failproof AI CLI 참조](/ko/reference/failproof-cli)를, `fp` 명령어는 [Failproof Cloud CLI 참조](/ko/reference/cloud-cli#cli-commands)를 참고하세요. + 로컬 명령어는 [Failproof AI CLI 참조](/ko/reference/failproof-cli)를, `fp` 명령어는 [Failproof Cloud CLI 참조](/ko/reference/cloud-cli#cli-명령)를 참고하세요. \ No newline at end of file diff --git a/docs/ko/start/quickstart.mdx b/docs/ko/start/quickstart.mdx index 627cea54..f323cf90 100644 --- a/docs/ko/start/quickstart.mdx +++ b/docs/ko/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # Slack/Telegram 게이트웨이 ``` - 실행 전에 도구 호출을 차단하는 기능은 12개 모두에서 검증됩니다. 턴 종료 게이트는 8개에서 검증됩니다 — 하네스별 매트릭스는 [적용 기능](/ko/reference/harnesses#enforcement-capability)을 참조하세요. + 실행 전에 도구 호출을 차단하는 기능은 12개 모두에서 검증됩니다. 턴 종료 게이트는 8개에서 검증됩니다 — 하네스별 매트릭스는 [적용 기능](/ko/reference/harnesses#적용-가능-범위)을 참조하세요. 훅 연결 자체는 어떤 정책도 활성화하지 않습니다. 설정 시 정책을 의도적으로 선택하지 않습니다 — 그 결정은 여러분의 것입니다. 다음과 같이 팩을 가져오세요: diff --git a/docs/pt-br/audits/findings-and-issues.mdx b/docs/pt-br/audits/findings-and-issues.mdx index 3a49d98a..4da6206c 100644 --- a/docs/pt-br/audits/findings-and-issues.mdx +++ b/docs/pt-br/audits/findings-and-issues.mdx @@ -47,7 +47,7 @@ Uma constatação é a declaração baseada em evidências da auditoria sobre um Use `fp issues subscribe `, `fp issues unsubscribe ` e `fp issues subscribers ` para gerenciar observadores. - Consulte a [referência da Cloud CLI para auditorias e problemas](/pt-br/reference/cloud-cli#audits) para constatações de auditoria e [`fp issues`](/pt-br/reference/cloud-cli#issues) para gerenciamento de problemas. + Consulte a [referência da Cloud CLI para auditorias e problemas](/pt-br/reference/cloud-cli#audits) para constatações de auditoria e [`fp issues`](/pt-br/reference/cloud-cli#problemas) para gerenciamento de problemas. diff --git a/docs/pt-br/evaluations/write.mdx b/docs/pt-br/evaluations/write.mdx index d7fb9932..2fd9aeba 100644 --- a/docs/pt-br/evaluations/write.mdx +++ b/docs/pt-br/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "Descreva o que medir e deixe o assistente criar uma avaliação Py icon: "file-pen-line" --- -Avaliações hospedadas são pequenos scripts Python determinísticos, escritos no dashboard e executados na frota de avaliadores da Failproof AI. Lógicas mais pesadas — um juiz LLM, um pacote, um segredo, uma chamada de rede — rodam no [seu próprio worker](#write-it-in-your-own-worker). +Avaliações hospedadas são pequenos scripts Python determinísticos, escritos no dashboard e executados na frota de avaliadores da Failproof AI. Lógicas mais pesadas — um juiz LLM, um pacote, um segredo, uma chamada de rede — rodam no [seu próprio worker](#escrever-no-seu-próprio-worker). ## Criar a partir de uma descrição diff --git a/docs/pt-br/policies/deploy.mdx b/docs/pt-br/policies/deploy.mdx index 8ddff178..db2788f8 100644 --- a/docs/pt-br/policies/deploy.mdx +++ b/docs/pt-br/policies/deploy.mdx @@ -16,7 +16,7 @@ Uma máquina aparece em **Admin → enforcement** assim que se conecta à Cloud. 1. Acesse **Administration → Keys** e crie uma chave com `policies:pull`, para que a máquina possa receber deploys, e `events:add`, para que suas decisões cheguem à Cloud. - 2. Conecte a máquina com essa chave — [Conectar uma máquina à Cloud](/pt-br/start/setup#connect-a-machine-to-cloud) descreve o processo. + 2. Conecte a máquina com essa chave — [Conectar uma máquina à Cloud](/pt-br/start/setup#conectar-uma-máquina-à-cloud) descreve o processo. 3. Confirme que ela aparece em **Admin → enforcement**. diff --git a/docs/pt-br/reference/cloud-cli.mdx b/docs/pt-br/reference/cloud-cli.mdx index 9303d982..71f01f2c 100644 --- a/docs/pt-br/reference/cloud-cli.mdx +++ b/docs/pt-br/reference/cloud-cli.mdx @@ -232,7 +232,7 @@ As severidades de alerta são `info`, `warning` e `critical`. Os tipos de gatilh | --- | --- | --- | | `fp audits list` | Listar auditorias. | `--enabled-only`; `--show-id` | | `fp audits show NAME` | Exibir uma definição de auditoria e seu estado. | — | -| `fp audits create NAME` | Criar uma auditoria e enfileirar imediatamente sua primeira execução. | Veja [opções de criação](#audit-create-options). | +| `fp audits create NAME` | Criar uma auditoria e enfileirar imediatamente sua primeira execução. | Veja [opções de criação](#opções-de-criação-de-auditoria). | | `fp audits edit NAME` | Substituir configurações da auditoria mantendo os valores não especificados. | opções de definição de criação; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | Excluir uma auditoria, suas descobertas e o histórico de execuções. | `--yes`, `-y` | | `fp audits run NAME` | Enfileirar uma execução manual. | — | diff --git a/docs/pt-br/reference/custom-agents.mdx b/docs/pt-br/reference/custom-agents.mdx index d044b8d4..ceb0fdd7 100644 --- a/docs/pt-br/reference/custom-agents.mdx +++ b/docs/pt-br/reference/custom-agents.mdx @@ -30,7 +30,7 @@ O pacote é instalado como `failproofai-sdk` e importado no Python como `failpro 1. Acesse **Admin → Keys** e crie uma chave com `events:add`. - 2. [Conecte o daemon do Failproof à nuvem](/pt-br/start/setup#connect-a-machine-to-cloud) na máquina do agente. + 2. [Conecte o daemon do Failproof à nuvem](/pt-br/start/setup#conectar-uma-máquina-à-cloud) na máquina do agente. 3. Execute uma sessão instrumentada e encontre o ID exato em **Observe → Events**. 4. Acesse **Observe → Sessions**, selecione o mesmo ambiente e abra o trace reconstruído. diff --git a/docs/pt-br/reference/overview.mdx b/docs/pt-br/reference/overview.mdx index 51a28a85..816b78f0 100644 --- a/docs/pt-br/reference/overview.mdx +++ b/docs/pt-br/reference/overview.mdx @@ -22,7 +22,7 @@ Escolha a integração mais próxima de onde seu agente já está sendo executad Configure captura local, hooks, políticas, auditorias, entrega e estado da máquina. - + Consulte e administre sessões, auditorias, problemas, alertas, chaves, usuários e configurações do Cloud. @@ -79,6 +79,6 @@ A [referência da API HTTP](/pt-br/reference/http-api) gerada cobre a superfíci Use `fp --json sessions ...` quando outra ferramenta for consumir o resultado. Flags globais como `--json`, `--org` e `--base-url` devem vir antes do comando. - Consulte a [referência do CLI do Failproof AI](/pt-br/reference/failproof-cli) para comandos locais e a [referência do CLI do Failproof Cloud](/pt-br/reference/cloud-cli#cli-commands) para comandos `fp`. + Consulte a [referência do CLI do Failproof AI](/pt-br/reference/failproof-cli) para comandos locais e a [referência do CLI do Failproof Cloud](/pt-br/reference/cloud-cli#comandos-da-cli) para comandos `fp`. \ No newline at end of file diff --git a/docs/pt-br/start/quickstart.mdx b/docs/pt-br/start/quickstart.mdx index e78a33af..69b135fe 100644 --- a/docs/pt-br/start/quickstart.mdx +++ b/docs/pt-br/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # um gateway Slack/Telegram ``` - O bloqueio de uma chamada de ferramenta antes de ela ser executada é verificado em todos os 12. Gates de fim de turno são verificados em 8 — consulte a [capacidade de aplicação](/pt-br/reference/harnesses#enforcement-capability) para a matriz por harness. + O bloqueio de uma chamada de ferramenta antes de ela ser executada é verificado em todos os 12. Gates de fim de turno são verificados em 8 — consulte a [capacidade de aplicação](/pt-br/reference/harnesses#capacidade-de-enforcement) para a matriz por harness. Conectar hooks não ativa nenhuma política. A configuração intencionalmente não escolhe nenhuma — essa decisão é sua — então pegue um pacote: diff --git a/docs/ru/evaluations/write.mdx b/docs/ru/evaluations/write.mdx index b99e4a69..3d8e7aae 100644 --- a/docs/ru/evaluations/write.mdx +++ b/docs/ru/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "Опишите, что нужно измерить, и позво icon: "file-pen-line" --- -Размещённые оценки — это небольшие детерминированные программы на Python, написанные в панели управления и выполняемые на оценочном кластере Failproof AI. Более сложную логику — судью на основе LLM, пакет, секрет, сетевой запрос — лучше запустить в [вашем собственном воркере](#write-it-in-your-own-worker). +Размещённые оценки — это небольшие детерминированные программы на Python, написанные в панели управления и выполняемые на оценочном кластере Failproof AI. Более сложную логику — судью на основе LLM, пакет, секрет, сетевой запрос — лучше запустить в [вашем собственном воркере](#написать-в-своём-воркере). ## Составить оценку из описания diff --git a/docs/ru/policies/deploy.mdx b/docs/ru/policies/deploy.mdx index fae337de..3d428dc1 100644 --- a/docs/ru/policies/deploy.mdx +++ b/docs/ru/policies/deploy.mdx @@ -16,7 +16,7 @@ icon: "cloud-upload" 1. Перейдите в **Administration → Keys** и создайте ключ с разрешениями `policies:pull`, чтобы машина могла получать развертывания, и `events:add`, чтобы её решения попадали в Cloud. - 2. Подключите машину с этим ключом — в разделе [Connect a machine to Cloud](/ru/start/setup#connect-a-machine-to-cloud) есть пошаговая инструкция. + 2. Подключите машину с этим ключом — в разделе [Connect a machine to Cloud](/ru/start/setup#подключите-машину-к-облаку) есть пошаговая инструкция. 3. Убедитесь, что машина появилась в разделе **Admin → enforcement**. diff --git a/docs/ru/reference/cloud-cli.mdx b/docs/ru/reference/cloud-cli.mdx index cace1bef..8ec1bda2 100644 --- a/docs/ru/reference/cloud-cli.mdx +++ b/docs/ru/reference/cloud-cli.mdx @@ -229,7 +229,7 @@ fp errors [OPTIONS] | --- | --- | --- | | `fp audits list` | Вывести аудиты. | `--enabled-only`; `--show-id` | | `fp audits show NAME` | Показать одно определение аудита и состояние. | — | -| `fp audits create NAME` | Создать аудит и немедленно поставить в очередь его первый запуск. | См. [параметры создания](#audit-create-options). | +| `fp audits create NAME` | Создать аудит и немедленно поставить в очередь его первый запуск. | См. [параметры создания](#параметры-создания-аудита). | | `fp audits edit NAME` | Заменить параметры аудита, сохраняя неуказанные значения. | параметры создания определения; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | Удалить аудит, его findings и историю запусков. | `--yes`, `-y` | | `fp audits run NAME` | Поставить в очередь ручной запуск. | — | diff --git a/docs/ru/reference/custom-agents.mdx b/docs/ru/reference/custom-agents.mdx index c83e0b5f..12f6893e 100644 --- a/docs/ru/reference/custom-agents.mdx +++ b/docs/ru/reference/custom-agents.mdx @@ -30,7 +30,7 @@ pip install failproofai-sdk 1. Перейдите в **Admin → Keys** и создайте ключ с правом `events:add`. - 2. [Подключите демон Failproof к облаку](/ru/start/setup#connect-a-machine-to-cloud) на машине агента. + 2. [Подключите демон Failproof к облаку](/ru/start/setup#подключите-машину-к-облаку) на машине агента. 3. Запустите одну инструментированную сессию, затем найдите её точный ID в **Observe → Events**. 4. Перейдите в **Observe → Sessions**, выберите ту же среду и откройте восстановленный след. diff --git a/docs/ru/reference/overview.mdx b/docs/ru/reference/overview.mdx index a8b1b7f1..6a745ae2 100644 --- a/docs/ru/reference/overview.mdx +++ b/docs/ru/reference/overview.mdx @@ -22,7 +22,7 @@ icon: "braces" Настройте локальный сбор, хуки, политики, аудиты, доставку и состояние машины. - + Запрашивайте и администрируйте сеансы Cloud, аудиты, проблемы, оповещения, ключи, пользователей и параметры. @@ -79,6 +79,6 @@ icon: "braces" Используйте `fp --json sessions ...`, когда другой инструмент будет использовать результат. Глобальные флаги, такие как `--json`, `--org` и `--base-url`, должны предшествовать команде. - Смотрите [справочник Failproof AI CLI](/ru/reference/failproof-cli) для локальных команд и [справочник Failproof Cloud CLI](/ru/reference/cloud-cli#cli-commands) для команд `fp`. + Смотрите [справочник Failproof AI CLI](/ru/reference/failproof-cli) для локальных команд и [справочник Failproof Cloud CLI](/ru/reference/cloud-cli#команды-cli) для команд `fp`. \ No newline at end of file diff --git a/docs/ru/start/quickstart.mdx b/docs/ru/start/quickstart.mdx index a46fecd8..67994933 100644 --- a/docs/ru/start/quickstart.mdx +++ b/docs/ru/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # Slack/Telegram gateway ``` - Блокировка вызова инструмента перед его выполнением проверена на всех 12. Gates конца хода проверены на 8 — см. [capability enforcement](/ru/reference/harnesses#enforcement-capability) для матрицы по каждому harness. + Блокировка вызова инструмента перед его выполнением проверена на всех 12. Gates конца хода проверены на 8 — см. [capability enforcement](/ru/reference/harnesses#возможности-применения) для матрицы по каждому harness. Встраивание hooks не включает никакую политику. Настройка специально не выбирает ничего — это решение за вами — поэтому возьмите пакет: diff --git a/docs/tr/evaluations/write.mdx b/docs/tr/evaluations/write.mdx index c20e64e3..31fe884b 100644 --- a/docs/tr/evaluations/write.mdx +++ b/docs/tr/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "Neyi ölçeceğinizi açıklayın ve asistanın barındırılan bi icon: "file-pen-line" --- -Barındırılan değerlendirmeler, panoda yazılan ve Failproof AI'nin değerlendirici filosunda çalıştırılan küçük, belirleyici Python kodlarıdır. Daha ağır mantık — bir LLM hakim, bir paket, bir gizli anahtar, bir ağ çağrısı — bunun yerine [kendi worker'ınızda](#write-it-in-your-own-worker) çalışır. +Barındırılan değerlendirmeler, panoda yazılan ve Failproof AI'nin değerlendirici filosunda çalıştırılan küçük, belirleyici Python kodlarıdır. Daha ağır mantık — bir LLM hakim, bir paket, bir gizli anahtar, bir ağ çağrısı — bunun yerine [kendi worker'ınızda](#bunu-kendi-worker-ınızda-yazın) çalışır. ## Bir açıklamadan taslak oluşturun diff --git a/docs/tr/policies/deploy.mdx b/docs/tr/policies/deploy.mdx index 97d8d276..fd96e7b1 100644 --- a/docs/tr/policies/deploy.mdx +++ b/docs/tr/policies/deploy.mdx @@ -16,7 +16,7 @@ Cloud'a bağlandıktan sonra bir makine **Admin → enforcement** altında gör 1. **Administration → Keys** sayfasına gidin ve makinenin dağıtımları alabilmesi için `policies:pull` ve kararlarının Cloud'a ulaşabilmesi için `events:add` yetkisine sahip bir anahtar oluşturun. - 2. Makineyi bu anahtarla bağlayın — [Connect a machine to Cloud](/tr/start/setup#connect-a-machine-to-cloud) bunu adım adım göstermektedir. + 2. Makineyi bu anahtarla bağlayın — [Connect a machine to Cloud](/tr/start/setup#bir-makineyi-buluta-bağlayın) bunu adım adım göstermektedir. 3. **Admin → enforcement** altında göründüğünü doğrulayın. diff --git a/docs/tr/reference/cloud-cli.mdx b/docs/tr/reference/cloud-cli.mdx index 6794be2b..b1b759dd 100644 --- a/docs/tr/reference/cloud-cli.mdx +++ b/docs/tr/reference/cloud-cli.mdx @@ -229,7 +229,7 @@ Uyarı önem dereceleri `info`, `warning` ve `critical` seçenekleridir. Tetikle | --- | --- | --- | | `fp audits list` | Denetimleri listeleyin. | `--enabled-only`; `--show-id` | | `fp audits show NAME` | Bir denetim tanımını ve durumunu gösterin. | — | -| `fp audits create NAME` | Bir denetim oluşturun ve ilk çalıştırmasını hemen sıraya alın. | Bkz. [create seçenekleri](#audit-create-options). | +| `fp audits create NAME` | Bir denetim oluşturun ve ilk çalıştırmasını hemen sıraya alın. | Bkz. [create seçenekleri](#denetim-oluşturma-seçenekleri). | | `fp audits edit NAME` | Belirtilmemiş değerleri korurken denetim ayarlarını değiştirin. | create tanımı seçenekleri; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | Denetimi, bulguları ve çalışma geçmişini silin. | `--yes`, `-y` | | `fp audits run NAME` | Manual çalıştırmayı sıraya alın. | — | diff --git a/docs/tr/reference/custom-agents.mdx b/docs/tr/reference/custom-agents.mdx index efd16c42..3dd99985 100644 --- a/docs/tr/reference/custom-agents.mdx +++ b/docs/tr/reference/custom-agents.mdx @@ -30,7 +30,7 @@ Paket `failproofai-sdk` olarak yüklenir ve Python'da `failproofai_sdk` olarak i 1. **Admin → Keys** bölümüne gidin ve `events:add` ile bir anahtar oluşturun. - 2. [Failproof daemon'ını Cloud'a bağlayın](/tr/start/setup#connect-a-machine-to-cloud) ajan makinesinde. + 2. [Failproof daemon'ını Cloud'a bağlayın](/tr/start/setup#bir-makineyi-buluta-bağlayın) ajan makinesinde. 3. Bir enstrümante edilmiş oturum çalıştırın, sonra **Observe → Events** altında tam ID'sini bulun. 4. **Observe → Sessions** bölümüne gidin, aynı ortamı seçin ve yeniden oluşturulan iz'i açın. diff --git a/docs/tr/reference/overview.mdx b/docs/tr/reference/overview.mdx index e3366e56..e11bd8e5 100644 --- a/docs/tr/reference/overview.mdx +++ b/docs/tr/reference/overview.mdx @@ -22,7 +22,7 @@ Agent'inizin zaten çalıştığı yere en yakın entegrasyonu seçin. Yerel yakalama, hook'lar, politikalar, denetimler, teslimat ve makine durumunu yapılandırın. - + Cloud oturumlarını, denetimleri, sorunları, uyarıları, anahtarları, kullanıcıları ve ayarları sorgulayın ve yönetin. @@ -79,6 +79,6 @@ Oluşturulan [HTTP API referansı](/tr/reference/http-api), genel `/v1` yüzeyin Başka bir araç sonucu tüketecek olduğunda `fp --json sessions ...` kullanın. `--json`, `--org` ve `--base-url` gibi global bayraklar komuttan önce gelmelidir. - Yerel komutlar için [Failproof AI CLI referansı](/tr/reference/failproof-cli) ve `fp` komutları için [Failproof Cloud CLI referansı](/tr/reference/cloud-cli#cli-commands) sayfalarına bakın. + Yerel komutlar için [Failproof AI CLI referansı](/tr/reference/failproof-cli) ve `fp` komutları için [Failproof Cloud CLI referansı](/tr/reference/cloud-cli#cli-komutları) sayfalarına bakın. \ No newline at end of file diff --git a/docs/tr/start/quickstart.mdx b/docs/tr/start/quickstart.mdx index ee5755c8..019f4c23 100644 --- a/docs/tr/start/quickstart.mdx +++ b/docs/tr/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - Bir araç çağrısını çalışmadan önce engellemek tümü 12'de doğrulanır. Dönüş sonu kapıları 8'de doğrulanır — harness başına matris için [zorlama yeteneğine](/tr/reference/harnesses#enforcement-capability) bakın. + Bir araç çağrısını çalışmadan önce engellemek tümü 12'de doğrulanır. Dönüş sonu kapıları 8'de doğrulanır — harness başına matris için [zorlama yeteneğine](/tr/reference/harnesses#zorlama-yeteneği) bakın. Hook'ları bağlama hiçbir politikayı etkinleştirmez. Kurulum kasıtlı olarak hiçbirini seçmez — bu karar sizin — bu nedenle bir paket alın: diff --git a/docs/vi/evaluations/write.mdx b/docs/vi/evaluations/write.mdx index 9e3f29ad..4d645951 100644 --- a/docs/vi/evaluations/write.mdx +++ b/docs/vi/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "Mô tả những gì cần đo lường và để trợ lý soạn icon: "file-pen-line" --- -Các bài đánh giá được lưu trữ là những chương trình Python nhỏ và xác định, được viết trong bảng điều khiển và chạy trên đội đánh giá của Failproof AI. Logics nặng hơn — một trọng tài LLM, một gói, một bí mật, một lệnh gọi mạng — chạy trong [worker của riêng bạn](#write-it-in-your-own-worker) thay thế. +Các bài đánh giá được lưu trữ là những chương trình Python nhỏ và xác định, được viết trong bảng điều khiển và chạy trên đội đánh giá của Failproof AI. Logics nặng hơn — một trọng tài LLM, một gói, một bí mật, một lệnh gọi mạng — chạy trong [worker của riêng bạn](#viết-nó-trong-worker-của-riêng-bạn) thay thế. ## Soạn thảo từ một mô tả diff --git a/docs/vi/policies/deploy.mdx b/docs/vi/policies/deploy.mdx index 48bce236..e16de3a2 100644 --- a/docs/vi/policies/deploy.mdx +++ b/docs/vi/policies/deploy.mdx @@ -16,7 +16,7 @@ Một máy xuất hiện dưới **Admin → enforcement** sau khi nó kết n 1. Đi tới **Administration → Keys** và tạo một khóa với `policies:pull`, để máy có thể nhận các deployment, và `events:add`, để các quyết định của nó đạt tới Cloud. - 2. Kết nối máy với khóa đó — [Connect a machine to Cloud](/vi/start/setup#connect-a-machine-to-cloud) hướng dẫn từng bước. + 2. Kết nối máy với khóa đó — [Connect a machine to Cloud](/vi/start/setup#kết-nối-máy-đến-cloud) hướng dẫn từng bước. 3. Xác nhận nó xuất hiện dưới **Admin → enforcement**. diff --git a/docs/vi/reference/custom-agents.mdx b/docs/vi/reference/custom-agents.mdx index 519354c9..a5753f9d 100644 --- a/docs/vi/reference/custom-agents.mdx +++ b/docs/vi/reference/custom-agents.mdx @@ -30,7 +30,7 @@ Gói được cài đặt dưới dạng `failproofai-sdk` và nhập trong Pyth 1. Đi tới **Admin → Keys** và tạo một khóa với `events:add`. - 2. [Kết nối daemon Failproof với Cloud](/vi/start/setup#connect-a-machine-to-cloud) trên máy agent. + 2. [Kết nối daemon Failproof với Cloud](/vi/start/setup#kết-nối-máy-đến-cloud) trên máy agent. 3. Chạy một phiên cấu hình, sau đó tìm ID chính xác của nó trong **Observe → Events**. 4. Đi tới **Observe → Sessions**, chọn cùng một environment, và mở trace được tái tạo. diff --git a/docs/vi/reference/overview.mdx b/docs/vi/reference/overview.mdx index f8e4a12c..f37a4585 100644 --- a/docs/vi/reference/overview.mdx +++ b/docs/vi/reference/overview.mdx @@ -22,7 +22,7 @@ Chọn tích hợp gần nhất với nơi agent của bạn đang chạy. Cấu hình xử lý cục bộ, hooks, chính sách, kiểm toán, phân phối và trạng thái máy. - + Truy vấn và quản trị các phiên Cloud, kiểm toán, vấn đề, cảnh báo, khóa, người dùng và cài đặt. @@ -79,6 +79,6 @@ Chọn tích hợp gần nhất với nơi agent của bạn đang chạy. Sử dụng `fp --json sessions ...` khi một công cụ khác sẽ sử dụng kết quả. Các cờ toàn cầu như `--json`, `--org` và `--base-url` phải đứng trước lệnh. - Xem [tài liệu tham khảo Failproof AI CLI](/vi/reference/failproof-cli) cho các lệnh cục bộ và [tài liệu tham khảo Failproof Cloud CLI](/vi/reference/cloud-cli#cli-commands) cho các lệnh `fp`. + Xem [tài liệu tham khảo Failproof AI CLI](/vi/reference/failproof-cli) cho các lệnh cục bộ và [tài liệu tham khảo Failproof Cloud CLI](/vi/reference/cloud-cli#lệnh-cli) cho các lệnh `fp`. \ No newline at end of file diff --git a/docs/vi/start/quickstart.mdx b/docs/vi/start/quickstart.mdx index 5a7f5ccf..15c56a84 100644 --- a/docs/vi/start/quickstart.mdx +++ b/docs/vi/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - Chặn một lệnh công cụ trước khi nó chạy được xác minh trên tất cả 12. Các cổng lượt kết thúc được xác minh trên 8 — xem [khả năng thực thi](/vi/reference/harnesses#enforcement-capability) để xem ma trận cho từng harness. + Chặn một lệnh công cụ trước khi nó chạy được xác minh trên tất cả 12. Các cổng lượt kết thúc được xác minh trên 8 — xem [khả năng thực thi](/vi/reference/harnesses#khả-năng-thực-thi) để xem ma trận cho từng harness. Kết nối hooks không bật chính sách. Thiết lập cố tình không chọn bất cứ điều gì — quyết định đó là của bạn — vì vậy hãy lấy một bộ: diff --git a/docs/zh/evaluations/write.mdx b/docs/zh/evaluations/write.mdx index 4c325309..25da51f5 100644 --- a/docs/zh/evaluations/write.mdx +++ b/docs/zh/evaluations/write.mdx @@ -4,7 +4,7 @@ description: "描述要衡量的内容，让助手起草一个托管的 Python icon: "file-pen-line" --- -托管评估是用 Python 编写的小型确定性程序，在仪表板中编写并在 Failproof AI 的评估器集群上运行。较复杂的逻辑——LLM 评判器、第三方包、密钥、网络调用——则在[您自己的 worker](#write-it-in-your-own-worker) 中运行。 +托管评估是用 Python 编写的小型确定性程序，在仪表板中编写并在 Failproof AI 的评估器集群上运行。较复杂的逻辑——LLM 评判器、第三方包、密钥、网络调用——则在[您自己的 worker](#在您自己的-worker-中编写) 中运行。 ## 从描述起草 diff --git a/docs/zh/policies/deploy.mdx b/docs/zh/policies/deploy.mdx index f46a8353..5ec50190 100644 --- a/docs/zh/policies/deploy.mdx +++ b/docs/zh/policies/deploy.mdx @@ -16,7 +16,7 @@ icon: "cloud-upload" 1. 前往 **Administration → Keys**，创建一个包含 `policies:pull`（用于接收部署）和 `events:add`（用于将决策上报到 Cloud）权限的密钥。 - 2. 使用该密钥连接机器 — 具体步骤请参阅 [将机器连接到 Cloud](/zh/start/setup#connect-a-machine-to-cloud)。 + 2. 使用该密钥连接机器 — 具体步骤请参阅 [将机器连接到 Cloud](/zh/start/setup#将机器连接到-cloud)。 3. 确认机器出现在 **Admin → enforcement** 下。 diff --git a/docs/zh/reference/cloud-cli.mdx b/docs/zh/reference/cloud-cli.mdx index 58b1c916..e74d5e4f 100644 --- a/docs/zh/reference/cloud-cli.mdx +++ b/docs/zh/reference/cloud-cli.mdx @@ -229,7 +229,7 @@ fp errors [OPTIONS] | --- | --- | --- | | `fp audits list` | 列出审计任务。 | `--enabled-only`；`--show-id` | | `fp audits show NAME` | 显示一个审计定义及其状态。 | — | -| `fp audits create NAME` | 创建审计任务并立即将首次运行加入队列。 | 参见[创建选项](#audit-create-options)。 | +| `fp audits create NAME` | 创建审计任务并立即将首次运行加入队列。 | 参见[创建选项](#审计创建选项)。 | | `fp audits edit NAME` | 替换审计设置，保留未指定的值。 | 创建定义选项；`--name`；`--yes`, `-y` | | `fp audits delete NAME` | 删除审计任务、其发现项及运行历史。 | `--yes`, `-y` | | `fp audits run NAME` | 手动触发一次运行。 | — | diff --git a/docs/zh/reference/custom-agents.mdx b/docs/zh/reference/custom-agents.mdx index bb317d60..dfbf38c1 100644 --- a/docs/zh/reference/custom-agents.mdx +++ b/docs/zh/reference/custom-agents.mdx @@ -30,7 +30,7 @@ pip install failproofai-sdk 1. 前往 **Admin → Keys**，创建一个具有 `events:add` 权限的密钥。 - 2. 在 Agent 所在机器上[将 Failproof 守护进程连接到 Cloud](/zh/start/setup#connect-a-machine-to-cloud)。 + 2. 在 Agent 所在机器上[将 Failproof 守护进程连接到 Cloud](/zh/start/setup#将机器连接到-cloud)。 3. 运行一次已埋点的会话，然后在 **Observe → Events** 下找到其确切 ID。 4. 前往 **Observe → Sessions**，选择相同的环境，打开重建后的追踪记录。 diff --git a/docs/zh/reference/overview.mdx b/docs/zh/reference/overview.mdx index bb683d7e..83ee1529 100644 --- a/docs/zh/reference/overview.mdx +++ b/docs/zh/reference/overview.mdx @@ -22,7 +22,7 @@ icon: "braces" 配置本地采集、Hook、策略、审计、数据传输及机器状态。 - + 查询和管理云端会话、审计、问题、告警、密钥、用户及设置。 @@ -79,6 +79,6 @@ icon: "braces" 当需要将结果传递给其他工具时，请使用 `fp --json sessions ...`。`--json`、`--org`、`--base-url` 等全局参数必须放在子命令之前。 - 本地命令请参阅 [Failproof AI CLI 参考](/zh/reference/failproof-cli)，`fp` 命令请参阅 [Failproof Cloud CLI 参考](/zh/reference/cloud-cli#cli-commands)。 + 本地命令请参阅 [Failproof AI CLI 参考](/zh/reference/failproof-cli)，`fp` 命令请参阅 [Failproof Cloud CLI 参考](/zh/reference/cloud-cli#cli-命令)。 \ No newline at end of file diff --git a/docs/zh/start/quickstart.mdx b/docs/zh/start/quickstart.mdx index 72695799..1cb2ec54 100644 --- a/docs/zh/start/quickstart.mdx +++ b/docs/zh/start/quickstart.mdx @@ -71,7 +71,7 @@ read -rs FAILPROOFAI_KEY && export FAILPROOFAI_KEY failproofai policies --install --cli hermes --scope user # Slack/Telegram 网关 ``` - 在工具调用执行前拦截的功能已在全部 12 种 harness 上验证。轮次结束门控已在 8 种上验证——请参阅[强制执行能力](/zh/reference/harnesses#enforcement-capability)查看各 harness 的详细矩阵。 + 在工具调用执行前拦截的功能已在全部 12 种 harness 上验证。轮次结束门控已在 8 种上验证——请参阅[强制执行能力](/zh/reference/harnesses#执行能力)查看各 harness 的详细矩阵。 接入 hook 并不会启用任何策略。配置过程故意不做任何选择——这个决定由你来做——请选取一个策略包： From 7fe1914c6859276c0b28f0e7c1fe82cd05a30f64 Mon Sep 17 00:00:00 2001 From: NiveditJain Date: Tue, 15 Sep 2026 11:06:53 +0530 Subject: [PATCH 6/8] docs: rewrite the Hebrew custom-agents page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CodeRabbit flagged this page as malformed throughout and asked for a full native-quality pass. main's version, which the previous commit's approach would otherwise have kept, is no better than the one it reviewed: "`collector.redact` עושה לא חל ל-SDK אירועים שלך", "הרצה קרוסה מתפזרת", "Hook triggered וsupplied" are word-for-word output, not Hebrew. It also still said `collector.redact` never sees SDK events. Rewritten from the current English. The redaction section matches #791, the adapter becomes a child of the hand-written agent, and the threads link targets #חוטים-ו-async. Code blocks are byte-identical to English again; the old page had translated their info strings, comments, a docstring and the mermaid labels. Terms follow the other Hebrew pages (חוטים, session, span, daemon). Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NrdeSVKcfqXd1H2BwP45Ad --- docs/he/start/integrations/custom-agents.mdx | 437 ++++++++++--------- 1 file changed, 220 insertions(+), 217 deletions(-) diff --git a/docs/he/start/integrations/custom-agents.mdx b/docs/he/start/integrations/custom-agents.mdx index a7c18715..3bce0da9 100644 --- a/docs/he/start/integrations/custom-agents.mdx +++ b/docs/he/start/integrations/custom-agents.mdx @@ -1,13 +1,13 @@ --- title: "סוכנים מותאמים אישית" sidebarTitle: "סוכנים מותאמים אישית" -description: "הוסף מעקב לסוכן שכתבת בעצמך, או לפריימוורק ללא מתאם." +description: "הוספת אינסטרומנטציה לסוכן שכתבת בעצמך, או לפריימוורק שאין לו מתאם." icon: "code" --- -לסוכן שכתבת בעצמך, או לפריימוורק של Failproof AI אין לו מתאם. אין כלום להוסיף: אתה פולט את האירועים. +הדף הזה מיועד לסוכן שכתבת בעצמך, או לפריימוורק שאין לו מתאם ב-Failproof AI. אין כאן פריימוורק שצריך לבצע עליו אינסטרומנטציה: את האירועים אתה פולט בעצמך. -זה אותו API שארבעת מתאמי הפריימוורק קוראים תחתיו. הם טבלאות תרגום עליו. +זהו אותו API שארבעת מתאמי הפריימוורק קוראים לו מאחורי הקלעים. הם בסך הכול טבלאות תרגום שנבנו מעליו. ## התקנה @@ -15,42 +15,42 @@ icon: "code" pip install failproofai-sdk ``` -ללא תוספים, וללא תלויות. +בלי extras ובלי תלויות. -## הוספת מעקב +## אינסטרומנטציה ```python import failproofai_sdk failproofai_sdk.configure(environment="production") -with failproofai_sdk.session(): # הרצה אחת - with failproofai_sdk.agent("planner"): # יחידת עבודה אחת +with failproofai_sdk.session(): # one run + with failproofai_sdk.agent("planner"): # one unit of work with failproofai_sdk.tool_call("search", input={"q": q}) as t: - t.output = search(q) # קריאת כלי אחת + t.output = search(q) # one tool call ``` -קרא זאת מלמעלה למטה והיא אומרת מה זה אומר: +קרא את הקוד מלמעלה למטה, והוא מסביר את עצמו: -| עטוף אותו ב | כדי לומר | +| במה לעטוף | מה זה אומר | | --- | --- | -| `session()` | האירועים הללו שייכים לאותה הרצה | -| `agent()` | משהו עושה עבודה — תן לו שם שהיית מזהה ברשימה | -| `tool_call()` | זהו כלי אחד, וזה מה שהוא החזיר | +| `session()` | האירועים האלה שייכים לאותה הרצה | +| `agent()` | משהו מבצע עבודה — תן לו שם שתזהה ברשימה | +| `tool_call()` | זה כלי אחד, וזה מה שהוא החזיר | -ומה כל אחד מהם למעשה פולט: +ומה כל אחד מהם פולט בפועל: -| טווח | פולט | מטרה | +| היקף | פולט | תפקיד | | --- | --- | --- | -| `session()` | כלום | קושר מזהה session, ומקבץ הרצה אחת | +| `session()` | כלום | קושר מזהה session שמקבץ הרצה אחת | | `agent()` | `agent_start`, `agent_end` | תוחם יחידת עבודה | | `tool_call()` | `tool_use`, `tool_result` | תוחם כלי אחד ומודד אותו | -הכל בתוך יכול להשמיט `session_id` ו-`agent_id`. הטווחים קושרים זהות על משתנות context ותוך כל קריאת event היא קוראת אותה חזרה, כך שאתה אף פעם לא מחליק מזהים דרך הפונקציות שלך. +כל מה שבתוך ההיקפים יכול להשמיט את `session_id` ואת `agent_id`. ההיקפים קושרים את הזהות למשתני הקשר (context variables), וכל קריאה לשיטת אירוע קוראת אותה משם, כך שלעולם לא צריך להעביר מזהים מפונקציה לפונקציה. -כל השלושה עובדים תחת `async with` כמו גם תחת `with`. +שלושתם עובדים גם עם `async with`, ולא רק עם `with`. -קינון סוכנים בונה את העץ. `parent_id` והעמוק מחושבים מהערימה: +קינון סוכנים בונה את העץ. `parent_id` והעומק מחושבים מתוך המחסנית: ```python with failproofai_sdk.session(): @@ -59,22 +59,22 @@ with failproofai_sdk.session(): ... ``` -## כיצד טווח סוגר +## איך היקף נסגר -`agent()` מטפל בחריגות עבורך: +`agent()` מטפל בחריגות בשבילך: | מה קרה | אירועים | תוצאה | | --- | --- | --- | -| כלום לא הוגבה | `agent_end` | `success` | -| `Exception` | `error`, ואז `agent_end` | `failed` | -| `KeyboardInterrupt`, `SystemExit` | `error`, ואז `agent_end` | `failed` | +| לא נזרקה חריגה | `agent_end` | `success` | +| `Exception` | `error`, ואחריו `agent_end` | `failed` | +| `KeyboardInterrupt`, `SystemExit` | `error`, ואחריו `agent_end` | `failed` | | `CancelledError`, `GeneratorExit` | `agent_end` בלבד | `cancelled` | -השגיאה פלטת לפני `agent_end`, כי הדashboard סוגר את ה-span ב-`agent_end` וכל דבר אחרי זה מיוחס לכלום. ביטול אינו כשל, כך שהרצות מבולות לא מזוהמות על משטח השגיאות. החריגה תמיד מוגבה מחדש: טווח אף פעם לא בולע. +השגיאה נפלטת לפני `agent_end`, כי ה-dashboard סוגר את ה-span ב-`agent_end`, וכל מה שמגיע אחריו לא משויך לשום דבר. ביטול אינו כישלון, ולכן הרצות שבוטלו לא מזהמות את תצוגת השגיאות. החריגה תמיד נזרקת מחדש: היקף אף פעם לא בולע אותה. -## שיטות האירוע +## שיטות האירועים -חמש עשרה שיטות בשש משפחות. רובן מגיעות בזוגות — אתה פולט את הפותח, ואז את הסוגר, והSDK מודד את ה-span ביניהם. +חמש עשרה שיטות בשש משפחות. רובן באות בזוגות — אתה פולט את אירוע הפתיחה ואחריו את אירוע הסגירה, וה-SDK מודד את ה-span שביניהם. | משפחה | פותח | סוגר | עצמאי | | --- | --- | --- | --- | @@ -82,23 +82,23 @@ with failproofai_sdk.session(): | | `agent_pause` | `agent_resume` | — | | **מודלים** | `model_request` | `model_response` | — | | **כלים** | `tool_use` | `tool_result` | — | -| **וו (Hook)** | `hook_triggered` | `hook_completed` | — | +| **Hooks** | `hook_triggered` | `hook_completed` | — | | **בני אדם** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | | **כשלים** | — | — | `error` | - העדף את הטווחים — `agent()` ו-`tool_call()` — בכל מקום שהם מתאימים. הם מבטיחים את אירוע הסיום גם כאשר הגוף מגביל. פנה לשיטות אלה ישירות כאשר זרימת הבקרה שלך לא קינה, כמו קריאה למודל בתוך עוזר. + העדף את ההיקפים — `agent()` ו-`tool_call()` — בכל מקום שהם מתאימים. הם מבטיחים שאירוע הסגירה ייפלט גם כשגוף הבלוק זורק חריגה. פנה לשיטות האלה ישירות כשזרימת הבקרה שלך לא בנויה בצורה מקוננת, למשל כשהקריאה למודל מתבצעת בתוך פונקציית עזר. -```python סוכנים +```python Agents failproofai_sdk.event.agent_start(agent_id="planner", goal="find the cheapest flight") failproofai_sdk.event.agent_end(agent_id="planner", outcome="success", summary="...") failproofai_sdk.event.agent_pause(pause_id="p1", reason="awaiting approval") failproofai_sdk.event.agent_resume(pause_id="p1") ``` -```python מודלים +```python Models failproofai_sdk.event.model_request( model="gpt-4o-mini", messages=[{"role": "user", "content": "..."}], @@ -114,24 +114,24 @@ failproofai_sdk.event.model_response( ) ``` -```python כלים +```python Tools failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1", input={"q": "..."}) failproofai_sdk.event.tool_result(tool_name="search", tool_call_id="c1", output="...") ``` -```python וו +```python Hooks failproofai_sdk.event.hook_triggered(hook_name="retrieve", hook_id="h1", trigger_event="node") failproofai_sdk.event.hook_completed(hook_name="retrieve", hook_id="h1", outcome="success") ``` -```python בני אדם +```python Humans failproofai_sdk.event.human_wait(input_id="i1", prompt="Approve?", options=["yes", "no"]) failproofai_sdk.event.human_input(input_id="i1", response="yes") failproofai_sdk.event.human_pause(reason="operator paused the run", user_id="dana") failproofai_sdk.event.human_interrupt(reason="operator stopped the run", at_step="step_3") ``` -```python כשלים +```python Failures failproofai_sdk.event.error( error_type="TimeoutError", message="provider timed out after 30s", @@ -141,23 +141,23 @@ failproofai_sdk.event.error( - **שתי משפחות בני אדם מצביעות בכיוונים מנוגדים.** + **שתי משפחות בני האדם פועלות בכיוונים הפוכים.** | שיטות | משמעות | | --- | --- | - | `human_wait` / `human_input` | **הסוכן שאל אדם** — שער אישור, שאלה הבהרה | - | `human_pause` / `human_interrupt` | **אדם פעל על הסוכן** — כפתור עצור, השהיית מפעיל | + | `human_wait` / `human_input` | **הסוכן פנה לאדם** — שער אישור, שאלת הבהרה | + | `human_pause` / `human_interrupt` | **אדם פעל על הסוכן** — כפתור עצירה, השהיה של מפעיל | - אף פריימוורק לא משדר את הזוג השני, כך שתמיד שלך להפליט. + אף פריימוורק לא מסמן את הזוג השני, ולכן תמיד תצטרך לפלוט אותו בעצמך. - **עבור `request_id` כאשר קריאות מודל פועלות במקביל.** בלעדיו, בקשות ותגובות מתזווגות בסדר הגעה לכל סוכן — וקריאות מקבילות מתזווגות בצורה שגויה, ומצרפות כל תגובה לבקשה הלא נכונה. + **העבר `request_id` כשקריאות למודל רצות במקביל.** בלעדיו, בקשות ותגובות מזווגות לפי סדר ההגעה בכל סוכן — וקריאות מקבילות מזווגות לא נכון, כך שכל תגובה מוצמדת לבקשה הלא נכונה. ## דוגמה -לולאת קריאת כלי כנגד ה-OpenAI API, ללא פריימוורק סוכנים: +לולאת קריאות לכלים מול ה-API של OpenAI, בלי פריימוורק סוכנים: ```python import json @@ -171,7 +171,7 @@ MODEL = "gpt-4o-mini" def turn(messages: list): - """קריאה מודל אחת, תוחומה בזוג.""" + """One model call, bracketed by the pair.""" failproofai_sdk.event.model_request(model=MODEL, messages=messages) reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) usage = reply.usage @@ -204,38 +204,37 @@ with failproofai_sdk.session(): }) ``` -זה מייצר את אותם ששת סוגי אירוע שמתאם היה נותן לך. הגרסה הרצה המלאה, עם הגדרות הכלים, משפנה ב-SDK repository תחת -`docs/manual/examples/`. +הקוד הזה מפיק את אותם שישה סוגי אירועים שמתאם היה נותן לך. הגרסה המלאה והניתנת להרצה, כולל הגדרות הכלים, נמצאת במאגר של ה-SDK תחת `docs/manual/examples/`. ## חוטים ו-async -משתנות context מתפשטות לתוך asyncio tasks באופן אוטומטי. הן לא מתפשטות לתוך חוטים חדשים, כי חוט מתחיל עם context ריק. +משתני הקשר עוברים אוטומטית למשימות asyncio. הם לא עוברים לחוטים חדשים, כי חוט מתחיל עם הקשר ריק. ```python -# asyncio: כלום לא לעשות +# asyncio: nothing to do async with failproofai_sdk.session(): await asyncio.gather(worker(1), worker(2)) -# threads: עטוף את ה-callable +# threads: wrap the callable pool.submit(failproofai_sdk.propagate(work), x) threading.Thread(target=failproofai_sdk.propagate(work)).start() loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` -ללא `propagate()`, אירועי העובד מגבילים `TypeError` ששם את התיקון במקום נחיתה ללא session. זה כוונתי: אירוע ללא session מדולל על ידי ingest וענות `200`, שזה הכשל שקט שלנו שה-identity layer קיים כדי למנוע. +בלי `propagate()`, קריאות האירועים ב-worker זורקות `TypeError` שמציין את התיקון, במקום שהאירועים ינחתו בלי session. זה מכוון: ה-ingest מדלג על אירוע בלי session ועונה `200`, וזה בדיוק הכשל השקט ששכבת הזהות נועדה למנוע. -## הוסף מעקב לפריימוורק ללא מתאם +## אינסטרומנטציה לפריימוורק שאין לו מתאם -כל סוכן פריימוורק נותן לך את אותם שלושה seams. מפה אותם ויש לך עקבות מלא — ארבעת המתאמים המספקים לא עושים יותר מזה. +כל פריימוורק סוכנים נותן לך את אותן שלוש נקודות חיבור. מפה אותן ותקבל trace מלא — ארבעת המתאמים שמגיעים עם ה-SDK לא עושים יותר מזה. -| ה-seam | מה שאתה כותב | מה נחיתה | +| נקודת החיבור | מה אתה כותב | מה נרשם | | --- | --- | --- | -| ה-run | `session()` + `agent()` | `agent_start`, `agent_end` | +| ההרצה | `session()` + `agent()` | `agent_start`, `agent_end` | | כל כלי | `tool_call()` | `tool_use`, `tool_result` | -| כל קריאת מודל | הזוג `model_*` | `model_request`, `model_response` | +| כל קריאה למודל | הזוג `model_*` | `model_request`, `model_response` | - + ```python with failproofai_sdk.session(): with failproofai_sdk.agent(agent_name, goal=task): @@ -243,14 +242,14 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) ``` - בכל מה שהפריימוורק קורא tool wrapper או middleware. + בכל רכיב שהפריימוורק מכנה tool wrapper או middleware. ```python with failproofai_sdk.tool_call(name, input=args) as call: call.output = original(**args) ``` - + ```python failproofai_sdk.event.model_request(model=model, messages=messages) reply = provider.complete(...) @@ -265,31 +264,31 @@ loop.run_in_executor(None, failproofai_sdk.propagate(work), x) - **יש node, step או middleware boundary שחייב להיות נראה?** עטוף אותו בזוג hook — `hook_triggered` / `hook_completed` — לא nested `agent()`. `agent_id` הוא facet low-cardinality, והערך אחד לכל node טובע אותו. Hook spans מתרנדרים בדרך זהה וגם נותנים לך לטנציה לכל node. + **יש גבול של צומת, שלב או middleware שכדאי לראות?** עטוף אותו בזוג hook — `hook_triggered` / `hook_completed` — ולא ב-`agent()` מקונן. `agent_id` הוא facet בעל קרדינליות נמוכה, ורשומה נפרדת לכל צומת מציפה אותו. ה-spans של hooks מוצגים באותה צורה ונותנים לך latency לכל צומת. - **ידני והאוטומטי מרכיבים.** מתאם שנמצא בתוך scope כתוב ביד מצטרף לשיוך זה ומוריש לסוכן זה, כך שאתה מקבל עץ אחד ולא שניים — שימושי כאשר אתה מעביר מסגרת אחת בעצמך לצד אחד בעל תמיכה. + **אינסטרומנטציה ידנית ואוטומטית משתלבות.** מתאם שרץ בתוך היקף שכתבת ידנית מצטרף ל-session של ההיקף הזה, והסוכן של המתאם נרשם כילד של הסוכן שכתבת ידנית — כך מתקבל עץ אחד ולא שניים. זה שימושי כשאתה מוסיף אינסטרומנטציה ידנית לפריימוורק אחד לצד פריימוורק נתמך. - - שתי סיבות, והשלושת ה-seams למעלה הן התשובה לשניהם: + + יש לכך שתי סיבות, ושלוש נקודות החיבור שלמעלה הן התשובה לשתיהן: - - `autogen-core` לא תופסת תחזוקה מ-September 2025. - - AG2 לא חושף נקודת רישום כללית תהליך שווה ערך למשדרים של פריימוורקים אחרים, כך שהוספת מעקב אומר עטיפת כל סוכן בכל אתר בנייה. + - `autogen-core` לא מתוחזק מאז ספטמבר 2025. + - AG2 לא חושף נקודת רישום ברמת התהליך כולו, מקבילה ל-hooks של הפריימוורקים האחרים, ולכן אינסטרומנטציה שלו פירושה לעטוף כל סוכן בכל מקום שבו הוא נוצר. - מיפוי ה-seams ביד רושם את אותם אירועים, בדיוק זהה, שמתאם משודר היה עושה. + מיפוי ידני של נקודות החיבור רושם את אותם אירועים, באותה רמת פירוט, שמתאם מובנה היה רושם. -## עומק יותר +## לעומק -איך ההקלטה למעשה עובדת. כלום מזה לא נחוץ כדי להתחיל. +איך ההקלטה עובדת בפועל. שום דבר מזה לא נדרש כדי להתחיל. - + -לכל הקלטה אותו צורה: span נפתח, עבודה קינה בתוכו, ולכל אירוע פותח יש אירוע סוגר אחד. +לכל הקלטה יש אותו מבנה: span נפתח, העבודה מקוננת בתוכו, ולכל אירוע פתיחה יש אירוע סגירה משלו. ```mermaid flowchart LR @@ -301,9 +300,9 @@ flowchart LR C --> E(["agent_end"]) ``` -ה**זוג** הוא היחידה. כל אירוע סוגר נושא משך זמן SDK מודד מה-opening שלו. +**הזוג** הוא יחידת הבסיס. כל אירוע סגירה נושא משך זמן שה-SDK מודד מאירוע הפתיחה שלו. -להלן הרצה אמיתית אחת לכל פריימוורק — תפוסה מהדוגמאות שנמצאות עם ה-SDK, שם מודל מנורמל. שים לב כמה חוזר מקריאה יחידה. +להלן הרצה אמיתית אחת לכל פריימוורק — כל אחת נלכדה מהדוגמאות שמגיעות עם ה-SDK, ושם המודל עבר נרמול. שים לב כמה מידע מתקבל מקריאה אחת. @@ -324,7 +323,7 @@ flowchart LR 14 +5.721s agent_end LangGraph · success ``` - Nodes הופכים לזוגות hook, כך שאתה מקבל לטנציה לכל node ללא טביעת הרשימה סוכנים. + צמתים הופכים לזוגות hook, כך שמתקבל latency לכל צומת בלי שהם יציפו את רשימת הסוכנים. @@ -341,7 +340,7 @@ flowchart LR 10 +5.739s agent_end crew · success ``` - `role` של כל סוכן הופך לשם ה-span שלו, כך שלטנציה ו-token spend מתפרקים לפי תפקיד. + ה-`role` של כל סוכן הופך לשם ה-span שלו, כך שה-latency וצריכת הטוקנים מתפלגים לפי תפקיד. @@ -361,7 +360,7 @@ flowchart LR 26 +7.038s agent_end Agent · success ``` - לולאת סוכן עצמה נראית, לא רק קריאות המודל שלו. + לולאת הסוכן עצמה גלויה, ולא רק הקריאות שלה למודל. @@ -376,7 +375,7 @@ flowchart LR 8 +8.119s agent_end agent · success ``` - אין זוגות hook: ל-Pydantic AI אין node או step boundary לתחום. + אין זוגות hook: ל-Pydantic AI אין גבול של צומת או שלב שאפשר לתחום. @@ -389,7 +388,7 @@ flowchart LR 6 +0.000s agent_end main · success ``` - אתה פולט אלה בעצמך. אותם סוגי אירוע, דיוק זהה — זה עולה לך לאתרי קריאה. + את האירועים האלה אתה פולט בעצמך. אותם סוגי אירועים, אותה רמת פירוט — המחיר הוא נקודות הקריאה שאתה כותב בעצמך. @@ -397,28 +396,28 @@ flowchart LR -**אין אירוע session-end.** session אינה משהו שאתה סוגר — היא קבוצה של אירועים השיתוף `session_id`. +**אין אירוע סיום ל-session.** את ה-session לא סוגרים — הוא פשוט קבוצת אירועים שחולקים את אותו `session_id`. -סטטוס נגזר מצורת העקבות: +הסטטוס נגזר מהמבנה של ה-trace: | סטטוס | מתי | | --- | --- | | `ongoing` | לפחות span אחד עדיין פתוח | -| `paused` | `agent_pause` אין לו matching `agent_resume` | -| `error` | כלום לא פתוח, ולפחות אירוע אחד נכשל | -| `done` | כלום לא פתוח, וכלום לא נכשל | +| `paused` | יש `agent_pause` בלי `agent_resume` תואם | +| `error` | שום דבר לא פתוח, ולפחות אירוע אחד נכשל | +| `done` | שום דבר לא פתוח, ושום דבר לא נכשל | -כך שsession מסתיים כאשר כל זוג סוגר. המתאמים פולטים `agent_end` עבורך, והם סוגרים כל דבר עדיין פתוח ומסימנים אותו לא שלם — הרצה קרוסה מתפזרת כ-`done` עם פער גלוי במקום תלויה לנצח. +כלומר, session מסתיים כשכל הזוגות נסגרו. המתאמים פולטים את `agent_end` בשבילך, ובזמן הכיבוי הם סוגרים כל מה שעדיין פתוח ומסמנים אותו כלא שלם — הרצה שקרסה מסתיימת בסטטוס `done` עם פער גלוי, במקום להישאר תלויה. - זה למה session יכול להקיף שתי קריאות. LangGraph `interrupt()` השהה את ה-run, ה-root span בכוונה נשאר פתוח, והקריאה הממשיכה סוגרת אותה. שתי הקריאות הן session אחד. + זו הסיבה ש-session יכול להשתרע על פני שתי קריאות. `interrupt()` של LangGraph משהה את ההרצה, ה-span השורשי נשאר פתוח בכוונה, והקריאה שממשיכה את ההרצה סוגרת אותו. שתי הקריאות הן session אחד. - + -`session_id` ו-`agent_id` הם אופציונליים בכל שיטת event. בהשמטה, הם מתפזרים מהטווח שוקע: +`session_id` ו-`agent_id` הם אופציונליים בכל שיטות האירועים. אם משמיטים אותם, הם נלקחים מההיקף העוטף: ```python with failproofai_sdk.session(): @@ -426,139 +425,139 @@ with failproofai_sdk.session(): failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -העברתם בגלוי עדיין עובדת ולוקחת עדיפות. ללא כלום קשור וכלום עברר, הקריאה מגבילה `TypeError` שם את התיקון במקום הפקת אירוע ללא session, אשר ingest היה דלל תוך התשובה `200`. +אפשר עדיין להעביר אותם במפורש, ואז הם גוברים על ההיקף. אם שום דבר לא קשור ושום דבר לא הועבר, הקריאה זורקת `TypeError` שמציין את התיקון, במקום לפלוט אירוע בלי session — אירוע שה-ingest היה מדלג עליו ובכל זאת עונה `200`. -טווחים קושרים זהות על משתנות context. אלה מתפשטות לתוך asyncio tasks באופן אוטומטי אך לא לתוך חוטים חדשים — עטוף עובד ב-`failproofai_sdk.propagate()`. +ההיקפים קושרים את הזהות למשתני הקשר. אלה עוברים אוטומטית למשימות asyncio, אבל לא לחוטים חדשים — עטוף את ה-worker ב-`failproofai_sdk.propagate()`. -#### מי חושב איזה id +#### מי מנפיק איזה מזהה -| Id | חשוב על ידי | הערות | +| מזהה | מי מנפיק | הערות | | --- | --- | --- | -| `session_id` | אתה, או ה-SDK | `session("chat-42")` משמש verbatim; בהשמטה, SDK מייצר `uuid4().hex` | -| `agent_id` | אתה, או הפריימוורק | מ-`agent("analyst")`, CrewAI `role`, `FunctionAgent.name`. ערך דומה UUID נדחה והחלפה | -| `tool_call_id`, `hook_id`, `request_id` | אתה, או הפריימוורק | מתאמים מחדשים שימוש ב-framework's שלהם run ids, שזה למה זוגות שורדים thread hops | -| **Event id** | **Cloud, ב-ingest** | ה-SDK לא פולט | -| **`dedup_key`** | **Cloud, ב-ingest** | hash של org, session, timestamp, type ו-payload. זאת הזהות האמיתית — היא גורמת batch שנו נסכל בקריסה במקום כפול | +| `session_id` | אתה, או ה-SDK | `session("chat-42")` נשמר כפי שהוא; אם משמיטים אותו, ה-SDK מייצר `uuid4().hex` | +| `agent_id` | אתה, או הפריימוורק | מתוך `agent("analyst")`, ה-`role` של CrewAI או `FunctionAgent.name`. ערך שנראה כמו UUID נדחה ומוחלף | +| `tool_call_id`, `hook_id`, `request_id` | אתה, או הפריימוורק | המתאמים משתמשים מחדש במזהי ההרצה של הפריימוורק עצמו, ולכן זוגות שורדים מעבר בין חוטים | +| **מזהה האירוע** | **Cloud, בשלב ה-ingest** | ה-SDK לא פולט מזהה כזה | +| **`dedup_key`** | **Cloud, בשלב ה-ingest** | גיבוב (hash) של הארגון, ה-session, חותמת הזמן, הסוג וה-payload. זו הזהות האמיתית — בזכותה אצווה שנשלחה שוב מתמזגת לעותק אחד במקום ליצור כפילויות | -#### איך מתאמים מתפזרים `session_id` +#### איך מתאמים קובעים את `session_id` -תאימה ראשונה זוכה: +ההתאמה הראשונה קובעת: -1. ערך `session_id` מפורש -2. metadata לכל קריאה -3. טווח `session()` שוקע -4. framework metadata -5. framework's שלהם run id +1. אפשרות `session_id` מפורשת +2. מטא-דאטה ברמת הקריאה +3. היקף `session()` העוטף +4. מטא-דאטה של הפריימוורק +5. מזהה ההרצה של הפריימוורק עצמו -זה אף פעם לא המצוי בזמן אחד מאלה קיים — id סינתטי היה מפלג הרצה אחת על פני מספר sessions. +המזהה אף פעם לא מומצא כל עוד אחד מאלה קיים — מזהה סינתטי היה מפצל הרצה אחת על פני כמה sessions. -#### שמור `agent_id` low cardinality +#### שמור על קרדינליות נמוכה ב-`agent_id` -זה ה-facet ראשי בכל משטח dashboard, ו-`LowCardinality(String)` כולונה. ערך לכל run מורידה את הכולונה ומלאה את ה-filter dropdown בערך אחד לכל run. +זהו ה-facet העיקרי בכל תצוגה של ה-dashboard, והוא עמודה מסוג `LowCardinality(String)`. ערך שמשתנה בכל הרצה פוגע ביעילות העמודה וממלא את התפריט הנפתח של המסנן ברשומה נפרדת לכל הרצה. -מתאמים בטחון כולונה זו עבורך: +המתאמים מגנים על העמודה הזו בשבילך: -| הפריימוורק מוביל על | הוקלט כ | למה | +| הפריימוורק מעביר | מה נרשם | הסיבה | | --- | --- | --- | -| `3f9a1c2b-…` (UUID) | `main` | כלום קריא לשמור | -| hex ארוך חשוף string | `main` | זהה | -| `agent-3f9a1c2b-…` | `agent` | לכל run id חשוף, ible part שמור | -| `agent-v2` | `agent-v2` | קטגוריה קצרה משומרת | -| `step-3` | `step-3` | זהה | +| `3f9a1c2b-…` (UUID) | `main` | אין חלק קריא שאפשר לשמור | +| מחרוזת hex ארוכה ותו לא | `main` | אותו דבר | +| `agent-3f9a1c2b-…` | `agent` | מזהה ההרצה הוסר, והחלק הקריא נשמר | +| `agent-v2` | `agent-v2` | מקטעים קצרים נשארים כמו שהם | +| `step-3` | `step-3` | אותו דבר | -ה-ID האמיתי שמור ב-`fw_agent_id` / `fw_run_id`, איפה זה נשאר queryable ללא להיות facet. +המזהה האמיתי נשמר ב-`fw_agent_id` / `fw_run_id`, שם עדיין אפשר לתשאל אותו בלי שהוא יהיה facet. - **שמירה זו רק נוגעת בתוויות **הפריימוורק** בחר.** `agent_id` אתה עבור עצמך — ל-`event.*`, או ל-`failproofai_sdk.agent(...)` — הוקלט בדיוק כנתון. שמאלה כתוב argument מפורש היה גרוע יותר מה-cardinality זה מנע, כך שקרא את הspan שלך בהתאם. + **ההגנה הזו חלה רק על תוויות שבחר *הפריימוורק*.** `agent_id` שאתה מעביר בעצמך — ל-`event.*` או ל-`failproofai_sdk.agent(...)` — נרשם בדיוק כפי שהועבר. שכתוב שקט של ארגומנט מפורש היה גרוע יותר מבעיית הקרדינליות שהוא בא למנוע, ולכן תן ל-spans שלך שמות מתאימים. - + | קבוצה | אירועים | | --- | --- | | סוכנים | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | | מודלים | `model_request`, `model_response` | | כלים | `tool_use`, `tool_result` | -| וו | `hook_triggered`, `hook_completed` | +| Hooks | `hook_triggered`, `hook_completed` | | בני אדם | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | | כשלים | `error` | -איזה פריימוורק רושם מה, נמדד מה-runs למעלה: +מה כל פריימוורק רושם, לפי מדידה בהרצות שלמעלה: | אירוע | LangGraph | CrewAI | LlamaIndex | Pydantic AI | מותאם אישית | | --- | :--: | :--: | :--: | :--: | :--: | -| תחילת וסוף סוכן | כן | כן | כן | כן | אתה | -| בקשת מודל ותגובה | כן | כן | כן | כן | אתה | -| שימוש בכלי ותוצאה | כן | כן | כן | כן | אתה | -| וו מתוגבר וסיום | Node | משימה | Step | — | אתה | +| התחלה וסיום של סוכן | כן | כן | כן | כן | אתה | +| בקשה ותגובה של מודל | כן | כן | כן | כן | אתה | +| שימוש בכלי ותוצאתו | כן | כן | כן | כן | אתה | +| הפעלה וסיום של hook | צומת | משימה | שלב | — | אתה | | שגיאה | כן | כן | כן | כן | אוטומטי | -| חכיית אדם וקלט | כן | כן | כן | — | אתה | -| השהיית סוכן וחידוש | כן | כן | כן | — | אתה | +| המתנה לאדם וקלט ממנו | כן | כן | כן | — | אתה | +| השהיה וחידוש של סוכן | כן | כן | כן | — | אתה | -dash פירושו הפריימוורק אין לו כזה קונספט. `human_pause` ו-`human_interrupt` תארו **אדם** פועל על סוכן, אשר אף פריימוורק משדר — הפלוט אלה בעצמך. +מקף פירושו שאין לפריימוורק מושג כזה. `human_pause` ו-`human_interrupt` מתארים *אדם* שפועל על הסוכן, ואף פריימוורק לא מסמן זאת — את אלה עליך לפלוט בעצמך. - + -אירוע אף פעם לא מגיע בודד. אחד פותח span, אחד סוגר אותו, ואירוע הסיום נוצא משך זמן SDK מודד מה-opening. +אירוע אף פעם לא מגיע לבד. אירוע אחד פותח span, אחר סוגר אותו, ואירוע הסגירה נושא משך זמן שה-SDK מודד מאירוע הפתיחה. -| פותח | סוגר | אירוע הסיום נוצא | +| פותח | סוגר | מה אירוע הסגירה נושא | | --- | --- | --- | | `agent_start` | `agent_end` | `outcome`, `summary` | -| `model_request` | `model_response` | tokens, `stop_reason`, latency | -| `tool_use` | `tool_result` | `output` או `error`, duration | -| `hook_triggered` | `hook_completed` | `outcome`, duration | -| `agent_pause` | `agent_resume` | כמה זמן ההשהיה נמשכה | -| `human_wait` | `human_input` | התשובה, וכמה זמן האדם לקח | +| `model_request` | `model_response` | טוקנים, `stop_reason`, latency | +| `tool_use` | `tool_result` | `output` או `error`, משך | +| `hook_triggered` | `hook_completed` | `outcome`, משך | +| `agent_pause` | `agent_resume` | כמה זמן נמשכה ההשהיה | +| `human_wait` | `human_input` | התשובה, וכמה זמן לקח לאדם לענות | - אירוע פותח ללא סוגר אחד הוא span שלא סיים. השיוך מתרנדר כעדיין פעיל, לנצח, וה-active duration שלו ממשיך לגדול. זה כשל mode לצפות בו כאשר אתה מוסיף מעקב ביד. + אירוע פתיחה בלי אירוע סגירה הוא span שלעולם לא מסתיים. ה-session מוצג כאילו הוא עדיין רץ, לנצח, ומשך הפעילות שלו ממשיך לגדול. זה הכשל שצריך להיזהר ממנו כשמבצעים אינסטרומנטציה ידנית. #### כללי קורלציה -- חזור על אותו `tool_call_id`, `hook_id`, `pause_id`, או `input_id` לאירוע השלמה תואם. -- SDK מחשבות `duration_ms` לכל `tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. עברור אותו הודעות raises `ValueError`. -- `duration_ms` **הוא** קבול ב-`model_response`, כי רק ה-caller יודע ה-real provider latency. זה חייב להיות integer — float raises `ValueError` בקריאה site, כי השרת קורא את הכולונה כ-unsigned 32-bit integer וחנה NULL לכל דבר אחר. -- מפתחות קורלציה בטוח לפי סוג וsession, אז tool call ו-hook עשוי בטוח שיתוף id, וsessions מקבילות שני חזור על אותם ids ללא התנגשות. הם לא בטוח על ידי סוכן: זוג פתוח תחת סוכן אחד וסגור תחת אחר עדיין קורלציה, שהיא המקרה הרגיל במסגרות רב סוכנים. -- `request_id` זוגות `model_request` עם `model_response`. ללא אותו, אירועי מודל זוג בסדר לכל סוכן, כך קריאות מקבילות mispair. -- זוג פיצול על פני processes עדיין קורלציה downstream, אך SDK לא יכול לחשב in-process duration. -- מפת pending מחזיקה לכל היותר 10,000 starts ו-evicts ערך עתיק כאשר מלא. +- השתמש באותו `tool_call_id`, `hook_id`, `pause_id` או `input_id` גם באירוע הסיום התואם. +- ה-SDK מחשב את `duration_ms` עבור `tool_result`, `hook_completed`, `agent_resume` ו-`human_input`. העברה שלו לשיטות האלה זורקת `ValueError`. +- `duration_ms` **כן** מתקבל ב-`model_response`, כי רק מי שמבצע את הקריאה יודע מה ה-latency האמיתי של הספק. הוא חייב להיות מספר שלם — ערך float זורק `ValueError` כבר בנקודת הקריאה, כי השרת קורא את העמודה כמספר שלם לא מסומן של 32 סיביות, ועבור כל ערך אחר היה שומר NULL. +- מפתחות הקורלציה תחומים לפי סוג ולפי session, כך שקריאה לכלי ו-hook יכולים לחלוק מזהה בבטחה, ושני sessions שרצים במקביל יכולים להשתמש באותם מזהים בלי להתנגש. הם לא תחומים לפי סוכן: זוג שנפתח תחת סוכן אחד ונסגר תחת סוכן אחר עדיין מתואם, וזה המצב הרגיל בפריימוורקים מרובי סוכנים. +- `request_id` מזווג את `model_request` עם `model_response`. בלעדיו, אירועי מודל מזווגים לפי הסדר בכל סוכן, כך שקריאות מקבילות מזווגות לא נכון. +- זוג שמפוצל בין תהליכים עדיין מתואם בהמשך הצינור, אבל ה-SDK לא יכול לחשב את משך הזמן שלו בתוך התהליך. +- מפת האירועים הממתינים מחזיקה לכל היותר 10,000 אירועי פתיחה, וכשהיא מתמלאת היא מפנה את הרשומה הישנה ביותר. - + -התקנת `failproofai-sdk` מתקנת הכל, כל ארבעת המתאמים כלול. ה-extras משדרים את **הפריימוורק**, לא את המתאם. +התקנת `failproofai-sdk` מתקינה הכול, כולל ארבעת המתאמים. ה-extras מושכים את **הפריימוורק**, לא את המתאם. ```python -import failproofai_sdk # עומס כלום חוץ מה-standard library -failproofai_sdk.instrument() # ייבוא רק המתאמים אתה בעצם צריך +import failproofai_sdk # loads nothing outside the standard library +failproofai_sdk.instrument() # imports only the adapters you actually need ``` -`import failproofai_sdk` הוא חוזה אפס תלויות, אינפורמציה על ידי בדיקה שמתקנת את הגלגלון עם `--no-deps` ועוד שמוכיח אף פריימוורק מגיע ל-`sys.modules`. +`import failproofai_sdk` מחויב חוזית לאפס תלויות. הדבר נאכף על ידי בדיקה שמתקינה את ה-wheel הבנוי עם `--no-deps`, ועל ידי בדיקה נוספת שמוכיחה שאף פריימוורק לא מגיע ל-`sys.modules`. - אין `failproofai_sdk.crewai` תכונה. מתאמים בכוונת לא חשוף על הפרה עליונה חבילה: לוגע אחד היה ייבוא הפריימוורק כ-side effect של גישה תכונה, שבירת אפס תלויות הבטחה. השתמש `instrument()`. + אין מאפיין `failproofai_sdk.crewai`. המתאמים לא נחשפים ברמה העליונה של החבילה, וזה מכוון: גישה לאחד מהם הייתה מייבאת את הפריימוורק כתופעת לוואי של גישה למאפיין, ושוברת את ההבטחה לאפס תלויות. השתמש ב-`instrument()`. ```python -failproofai_sdk.instrument() # כל פריימוורק כבר ייובא -failproofai_sdk.instrument("crewai") # בדיוק אחד, לפי שם -failproofai_sdk.uninstrument("crewai") # שים חזרה +failproofai_sdk.instrument() # every framework already imported +failproofai_sdk.instrument("crewai") # exactly one, by name +failproofai_sdk.uninstrument("crewai") # put it back ``` -| שם | גם קבול | +| שם | מקבל גם | | --- | --- | | `langchain` | `langgraph`, `langchain_core` | | `crewai` | — | | `llama_index` | `llamaindex`, `llama-index` | | `pydantic_ai` | `pydantic-ai`, `pydanticai` | -גילוי אוטומטי קורא `sys.modules`, לא את רשימת חבילה מותקנת, אז פריימוורק שיש לך מותקן אבל אף פעם לא ייבוא הוא לא מוכן והוא אף פעם לא ייובא בשמך. להראות מה חווט למעלה: +הזיהוי האוטומטי קורא את `sys.modules`, ולא את רשימת החבילות המותקנות, כך שפריימוורק שהתקנת אבל אף פעם לא ייבאת לא עובר אינסטרומנטציה, וגם לא ייובא בשמך. כדי לראות מה מחובר: ```python from failproofai_sdk.integrations import active, available @@ -568,132 +567,136 @@ active() # ('langchain',) ``` - **`instrument("crewai")` על מכונה ללא CrewAI לא מגביל.** זה עוקב אזהרה ו-return `()`, אז פריימוורק חמיץ אף פעם לוקח תהליך שגם מהמרות אחרים. + **`instrument("crewai")` במכונה שאין בה CrewAI לא זורק חריגה.** הוא רושם אזהרה בלוג ומחזיר `()`, כך שפריימוורק אחד חסר לעולם לא מפיל תהליך שמבצע אינסטרומנטציה גם לפריימוורקים אחרים. - האזהרה נוצא ה-`ImportError` בקדמה, וזה הודעה שם את פקודת התקנה מדויקת — כך התיקון בלוגים שלך, לא מוסתר. + האזהרה כוללת את ה-`ImportError` המקורי, וההודעה שלו מציינת את פקודת ההתקנה המדויקת — כך שהתיקון נמצא בלוגים שלך, ולא מוסתר. ```text ImportError: failproofai_sdk: cannot instrument 'crewai' because 'crewai.events' is not importable. Install it with: pip install 'failproofai_sdk[crewai]' ``` - ערכה `FAILPROOFAI_SDK_STRICT=1` כדי יש לו מגביל במקום. זה דגל קורא **פעם אחת ו-cached**, אז ייצוא זה לפני התהליך מתחיל במקום קביעה mid-run. + הגדר `FAILPROOFAI_SDK_STRICT=1` כדי שבמקום זאת תיזרק חריגה. הדגל הזה נקרא **פעם אחת ונשמר במטמון**, לכן הגדר אותו בסביבה לפני שהתהליך מתחיל, ולא באמצע ההרצה. - **`instrument()` חייב לבוא **אחרי** ייבוא הפריימוורק שלך.** גילוי אוטומטי קורא `sys.modules`, אז קריאה ערומה מעל הייבוא מוצא כלום, מתקן כלום, וחוזר `()`. + **הקריאה ל-`instrument()` חייבת לבוא *אחרי* ייבוא הפריימוורק.** הזיהוי האוטומטי קורא את `sys.modules`, כך שקריאה בלי ארגומנטים מעל הייבוא לא מוצאת כלום, לא מתקינה כלום ומחזירה `()`. -```python שגוי +```python Wrong import failproofai_sdk -failproofai_sdk.instrument() # sys.modules אין langchain עדיין -> () +failproofai_sdk.instrument() # sys.modules has no langchain yet -> () -import langchain # מאוחר מדי, כלום לא חווט +import langchain # too late, nothing is wired ``` -```python נכון -import langchain # ייבוא הפריימוורק ראשון +```python Right +import langchain # import the framework first import failproofai_sdk -failproofai_sdk.instrument() # מוצא זה -> ('langchain',) +failproofai_sdk.instrument() # finds it -> ('langchain',) ``` -```python נכון, order-proof +```python Right, order-proof import failproofai_sdk -# שם זה ייבוא את המתאם על בקשה, אז זה עובד מכל מקום. +# Naming it imports the adapter on request, so this works from anywhere. failproofai_sdk.instrument("langchain") ``` -קבל את זה שגוי והתהליך פועל עם ה-SDK ייובא, המתאם לכאורה מותקן, ו**לא אירוע אחד פלט**. זה עוקב אזהרה אומר בדיוק זה — אז בדוק לוגים ראשון כאשר run רושם כלום. +אם הסדר שגוי, התהליך רץ עם ה-SDK מיובא, המתאם מותקן לכאורה, **ואף אירוע לא נפלט**. נרשמת בלוג אזהרה שאומרת בדיוק את זה — לכן כשהרצה לא מתעדת כלום, בדוק קודם את הלוגים. - + ```mermaid flowchart LR - A["הסוכן שלך"] --> B["מתאם"] - B --> C["כותב
תור בזיכרון"] - C -->|"כל 0.5s"| D["Spool
JSONL בדיסק"] + A["Your agent"] --> B["Adapter"] + B --> C["Writer
in-memory queue"] + C -->|"every 0.5s"| D["Spool
JSONL on disk"] D --> E["Failproof daemon"] E -->|"HTTPS"| F["Cloud"] ``` -| שלב | משימה | פועל בתוך | +| שלב | תפקיד | היכן רץ | | --- | --- | --- | -| מתאם | תרגם callback פריימוורק לתוך אחד מ-15 סוגי אירוע | התהליך שלך | -| כותב | תור, אצווה, כתיבה JSONL אטומית | התהליך שלך, חוט רקע | -| Spool | Durable handoff, שורד התהליך יציאה | דיסק מקומי | -| Daemon | שומר spool, משלח אצוות, מוחק מה-shipped | המכונה שלך | -| Ingest | מקצה שורה id ו-dedup key, מקדם שאלה כולוניות | Cloud | +| מתאם | מתרגם callback של הפריימוורק לאחד מ-15 סוגי האירועים | התהליך שלך | +| Writer | מכניס לתור, מאגד לאצוות וכותב JSONL באופן אטומי | התהליך שלך, בחוט רקע | +| Spool | נקודת מסירה עמידה, ששורדת גם את היציאה של התהליך שלך | הדיסק המקומי | +| Daemon | עוקב אחרי ה-spool, שולח אצוות ומוחק את מה שנשלח | המכונה שלך | +| Ingest | מקצה מזהה שורה ומפתח dedup, ומקדם שדות לעמודות שאפשר לתשאל | Cloud | -ה-spool הוא מה עושה זה בטוח: סוכן שלך אף פעם לא חסום על הרשת, וCloud outage אומר ספריה גדלה במקום קביעה אירועים. +ה-spool הוא מה שהופך את זה לבטוח: הסוכן שלך אף פעם לא נחסם בהמתנה לרשת, והשבתה של Cloud פירושה תיקייה שהולכת וגדלה, ולא אירועים שאבדו. -כל flush כתוב קובץ אצווה אחד, `.tmp` ראשון, ואז `fsync`, ואז atomic rename: +כל flush כותב קובץ אצווה אחד: קודם `.tmp`, אחר כך `fsync`, ולבסוף שינוי שם אטומי: ```text ~/.failproofai/custom-agents/events/ event-2026-08-20T10-15-00-123Z-48213-0.jsonl ``` -ה-daemon רק עוזב `.jsonl`, אז זה לא יכול אף פעם קרא חצי כתוב קובץ. הגזע נוצא timestamp, process id וסדר מספר, אז שני תהליכים flush בה-millisecond לא יכול להתנגש. התור כובל בחסום 10,000 אירועים; העבר זה זה טיפל הוקדם וrelog. +ה-daemon אוסף רק קבצי `.jsonl`, כך שלעולם לא יקרא קובץ שנכתב רק בחלקו. שם הקובץ כולל חותמת זמן, מזהה תהליך ומספר רץ, כך ששני תהליכים שמבצעים flush באותה אלפית שנייה לא יכולים להתנגש. התור מוגבל ל-10,000 אירועים; מעבר לכך הוא משליך את הישנים ביותר ורושם זאת בלוג. - **`collector.redact` עושה לא חל ל-SDK אירועים שלך.** זה אף פעם לא רואה אותם. + **ברירת המחדל של `collector.redact` היא `minimal` גם עבור אירועי SDK.** ה-SDK + מבצע השחרה לפני שהוא כותב אצווה לדיסק, וה-daemon מריץ שוב את אותו מעבר + דטרמיניסטי לפני ההעלאה, כך שגם אצוות מגרסאות SDK ישנות מוגנות. -ה-daemon **משלח** אצוות שלך. זה לא פתוח או לשכתב אותם. +ה-daemon קורא כל אצווה ומחיל עליה השחרה בזיכרון לפני ההעלאה. הוא לא משכתב את +קובץ ה-spool שקרא. -| אירועים | כתוב על ידי | Redacted על ידי `collector.redact`? | +| אירועים | נכתבים על ידי | היכן רצה ההשחרה המינימלית | | --- | --- | --- | -| CLI session תחקירי | Daemon | כן | -| וו פעילות | Daemon | כן | -| **הכל ה-SDK פלט** | **התהליך שלך** | **לא** | +| תמלילי sessions של CLI | ה-daemon | לפני שה-daemon כותב את האצווה | +| פעילות hooks | ה-daemon | לפני שה-daemon כותב את האצווה | +| **כל מה שה-SDK פולט** | **התהליך שלך** | **לפני שה-SDK כותב את האצווה, ושוב לפני שה-daemon מעלה אותה** | -Redaction פועל איפה ה-daemon **כתוב** שלהם אירועים — לא איפה אצוות **משודרים**. כך prompt או tool argument מחזיק API key עדיין מחזיק זה בהגעה. - -זה כוונתי. אלה בעצמך מעקב קריאות, וכתיבה מחדש בטרנזיט יומר את אירועים אתה קבל הם לא אירועים אתה פלט. +הגדר את `collector.redact` ל-`off` רק כשיש דרישה מפורשת לשמור payloads כלשונם; +גם ה-SDK וגם ה-daemon מכבדים את ההגדרה הזו. השחרה מינימלית תופסת מפתחות API +נפוצים, אסימוני bearer, אסימוני JWT והשמה של סודות למשתנים. היא לא יכולה לזהות +מידע רגיש שמנוסח כטקסט חופשי. - **אתה שלוט בפעילויות ב-source, בשני מקומות:** + **אתה שולט ב-payloads כבר במקור, בשני מקומות:** - - כבה לכידת תוכן על המתאם. **שם אפשרות שונה, ומתאם אחד אין אחד** — זה לא אחד כללי אוניברסלי מתג: + - כבה את לכידת התוכן במתאם. **שם האפשרות שונה ממתאם למתאם, ולאחד המתאמים אין אפשרות כזו בכלל** — זה לא מתג אוניברסלי אחד: - LangChain / LangGraph, Pydantic AI — `capture_content=False` - LlamaIndex — `capture_messages=False` - - CrewAI — **אין מתג תוכן בכל**; `session_id` היא רק אפשרות שהיא קורא, אז prompts ו-completions תמיד רשום. + - CrewAI — **אין שום מתג תוכן**; `session_id` היא האפשרות היחידה שהוא קורא, ולכן ההנחיות והתשובות של המודל תמיד נרשמות. - `instrument()` טיול אפשרויות מתאם לא קורא, אז עברור שם שגוי מגביל כלום ושינויים כלום. - - אל תעביר את הסוד ל-`input=` בראשון מקום. + `instrument()` משמיט אפשרויות שהמתאם לא קורא, כך שהעברת שם שגוי לא זורקת שום חריגה וגם לא משנה דבר. + - מלכתחילה, אל תעביר את הסוד ל-`input=`. - `collector.redact` הוא לא תחליף לאף אחד מאלה. + `collector.redact` הוא הגנה לעומק, ולא תחליף לאף אחד משני אלה. - **ספריה spool ריקה היא המדינה הבריאה.** אל תשתמש בזה כדי בדוק משלוח. + **תיקיית spool ריקה היא המצב התקין.** אל תשתמש בה כדי לבדוק אם האירועים נמסרו. -ה-daemon מוחק כל אצווה בתוך milliseconds משליחה, אז `ls` מרוצים collector וש fraction של מה אתה פלט — לא ניתנת להבחנה מ-SDK ש קיבוץ כלום. +ה-daemon מוחק כל אצווה תוך אלפיות שנייה מרגע שליחתה, כך ש-`ls` מתחרה ב-collector ומציג רק חלק קטן ממה שפלטת — ואי אפשר להבחין בין זה לבין SDK שלא תיעד כלום. -לאשר אירועים באמת נחתו, בדוק את ה-dashboard. לצפות ה-spool תמלא, עצור את ה-daemon ראשון. +כדי לוודא שהאירועים באמת הגיעו, בדוק ב-dashboard. כדי לראות את ה-spool מתמלא, עצור קודם את ה-daemon. - + -כל callback פועל בתוך wrapper שלה יחידה משימה היא להגביל מחדש, אז קריאה שלך יושבת בדיוק אחד `try` והכל SDK עושה קורה מחוץ אותה. +כל callback רץ בתוך עוטף שתפקידו היחיד הוא לזרוק חריגות מחדש, כך שהקריאה שלך נמצאת בתוך `try` אחד בדיוק, וכל מה שה-SDK עושה קורה מחוצה לו. -| מה קורה | תוצאה | +| מה קורה | התוצאה | | --- | --- | -| hook מגביל | עיתון פעם עם traceback. קריאה שלך לא השפעה | -| אותו hook מגביל שלוש פעמים | זה hook אחד משוביץ לנו התהליך, עם שורה טעות אחד | -| `FAILPROOFAI_SDK_STRICT=1` הוא קביעה | החריגה הוא re-raised במקום | -| פריימוורק גרסה חוץ בדוקו טווח | הזהרות פעם, מהמרות בכל זאת | -| יחיד יכולת היא חמיץ | זה חוק אחד משוביץ, אף פעם כל מתאם | +| hook זורק חריגה | החריגה נרשמת בלוג פעם אחת, יחד עם ה-traceback שלה. הקריאה שלך לא מושפעת | +| אותו hook זורק חריגה שלוש פעמים | ה-hook הזה בלבד מושבת עד סוף חיי התהליך, ונרשמת שורת שגיאה אחת | +| `FAILPROOFAI_SDK_STRICT=1` מוגדר | במקום זאת, החריגה נזרקת מחדש | +| גרסת הפריימוורק מחוץ לטווח שנבדק | אזהרה אחת, והאינסטרומנטציה מתבצעת בכל זאת | +| יכולת בודדת חסרה | רק ה-hook הזה מושבת, אף פעם לא המתאם כולו | -ה-default הוא ימין בייצור וחצי בזמן debug, כי זה יכול רק אי פעם הוכח אתה לא קרס. קביעה `FAILPROOFAI_SDK_STRICT=1` לעשות בוליט כשל קול. +ברירת המחדל נכונה ב-production ושגויה בזמן דיבוג, כי כל מה שהיא יכולה להוכיח הוא ש"זה לא קרס". הגדר `FAILPROOFAI_SDK_STRICT=1` כדי שכשל שהיה נבלע בשקט יתריע בקול רם. @@ -702,37 +705,37 @@ Redaction פועל איפה ה-daemon **כתוב** שלהם אירועים — ## בעיות נפוצות - - אירוע פותח אין אחד סוגר: `model_request` ללא `model_response`, או `tool_use` ללא `tool_result`. השתמש הטווחים, אשר ערובה הזוג אפילו כאשר הגוף מגביל. אם אתה קורא את שיטות האירוע ישירות, השתמש `try` ו-`finally`. + + לאירוע פתיחה אין אירוע סגירה: `model_request` בלי `model_response`, או `tool_use` בלי `tool_result`. השתמש בהיקפים, שמבטיחים את הזוג גם כשגוף הבלוק זורק חריגה. אם אתה קורא לשיטות האירועים ישירות, השתמש ב-`try` וב-`finally`. - - זה נמדד מה-opening תואם אירוע, אז זה דחוי ב-`tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. זה קבול ב-`model_response`, כי רק אתה יודע ה-real provider latency, וזה חייב להיות integer. + + הערך נמדד מאירוע הפתיחה התואם, ולכן הוא נדחה ב-`tool_result`, `hook_completed`, `agent_resume` ו-`human_input`. הוא מתקבל ב-`model_response`, כי רק אתה יודע מה ה-latency האמיתי של הספק, ושם הוא חייב להיות מספר שלם. - - החוט לא אף פעם inherited ה-context. עטוף את ה-callable ב-`failproofai_sdk.propagate()`. ראה [חוטים ו-async](#threads-and-async). + + החוט לא ירש את ההקשר. עטוף את ה-callable ב-`failproofai_sdk.propagate()`. ראה [חוטים ו-async](#חוטים-ו-async). - - שדות תוספת מיזוג אחרון, אז אחד שנקרא כמו שדה אמיתי כמו `model` או `outcome` היה כתוב על זה ו-שינוי כלונה שמור. Namespace שלך; המתאמים משתמשים `fw_` קידומת. + + שדות נוספים ממוזגים אחרונים, כך ששדה ששמו זהה לשדה אמיתי, כמו `model` או `outcome`, ידרוס אותו וישנה עמודה שמורה. תן לשדות שלך קידומת ייחודית; המתאמים משתמשים בקידומת `fw_`. - - `agent_id` היא low-cardinality facet ו-אתה שים run id בזה. השתמש תפקיד או node שם ו-שים ה-ID אמיתי בשדה payload. + + `agent_id` הוא facet בעל קרדינליות נמוכה, והכנסת אליו מזהה הרצה. השתמש בשם של תפקיד או של צומת, ושמור את המזהה האמיתי בשדה של ה-payload. -## הבא +## מה הלאה - זוגות, ids, session lifecycle, ו-delivery. + זוגות, מזהים, מחזור החיים של session ומסירה. - - עקוב סיבתיות דרך ה-session אתה רק תפוסה. + + עקוב אחרי שרשרת הסיבתיות ב-session שזה עתה לכדת. - LangGraph, CrewAI, LlamaIndex, ו-Pydantic AI. + LangGraph, CrewAI, LlamaIndex ו-Pydantic AI. - \ No newline at end of file + From e02e14f8ff5f095e27f6575fc966f509b70e0132 Mon Sep 17 00:00:00 2001 From: NiveditJain Date: Tue, 15 Sep 2026 11:06:53 +0530 Subject: [PATCH 7/8] docs: add the changelog entry for #797 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NrdeSVKcfqXd1H2BwP45Ad --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b4e197a..5a6e50b2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ ## 1.0.6-beta.0 — 2026-09-15 +### Docs + +- Translate the English documentation changes from #788 and #791 into all 14 locales, including the new evaluation pages and SDK event redaction on the custom-agents page, and point translated fragment links at their translated headings (#797) + ### Dependencies - yaml 2.9.0 → 2.9.1, and rustls 0.23.43 → 0.23.45 (with rustls-webpki 0.103.13 → 0.103.15) in `Cargo.lock`, closing RUSTSEC-2026-0285 (5.3, fixed in 0.23.45). The advisory turned the Supply Chain gate red on `main` itself, not through any PR's change; rustls is transitive-only, via `reqwest` in `failproofaid` and `fpai-collect` (#803) From 2869e3025a64a637cdc9078ad66016500c46c7a6 Mon Sep 17 00:00:00 2001 From: NiveditJain Date: Tue, 15 Sep 2026 11:11:16 +0530 Subject: [PATCH 8/8] docs: fix the Turkish instrument() warning and the last pt-br anchor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit main's Turkish custom-agents page, which the first fix commit kept, has the same garbled troubleshooting sentence CodeRabbit flagged in the Sep 12 retranslation: "tek bir olayı yayınla olmayan ile çalışır", and a closing clause that says to check the logs when a run records something. It now says what the English does: the process runs with the SDK and adapter apparently installed but emits no events, logs a warning saying so, and the logs are the first place to look. pt-br/audits/findings-and-issues became a PR-touched page when its cloud-cli#issues link was repaired, so its cloud-cli#audits link, broken on main as well, now points at the pt-br heading too. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NrdeSVKcfqXd1H2BwP45Ad --- docs/pt-br/audits/findings-and-issues.mdx | 2 +- docs/tr/start/integrations/custom-agents.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pt-br/audits/findings-and-issues.mdx b/docs/pt-br/audits/findings-and-issues.mdx index 4da6206c..e27fca9b 100644 --- a/docs/pt-br/audits/findings-and-issues.mdx +++ b/docs/pt-br/audits/findings-and-issues.mdx @@ -47,7 +47,7 @@ Uma constatação é a declaração baseada em evidências da auditoria sobre um Use `fp issues subscribe `, `fp issues unsubscribe ` e `fp issues subscribers ` para gerenciar observadores. - Consulte a [referência da Cloud CLI para auditorias e problemas](/pt-br/reference/cloud-cli#audits) para constatações de auditoria e [`fp issues`](/pt-br/reference/cloud-cli#problemas) para gerenciamento de problemas. + Consulte a [referência da Cloud CLI para auditorias e problemas](/pt-br/reference/cloud-cli#auditorias) para constatações de auditoria e [`fp issues`](/pt-br/reference/cloud-cli#problemas) para gerenciamento de problemas. diff --git a/docs/tr/start/integrations/custom-agents.mdx b/docs/tr/start/integrations/custom-agents.mdx index c150af50..827d5f1d 100644 --- a/docs/tr/start/integrations/custom-agents.mdx +++ b/docs/tr/start/integrations/custom-agents.mdx @@ -606,7 +606,7 @@ failproofai_sdk.instrument("langchain") ``` -Bunu yanlış yapın ve işlem SDK'yı içe aktarılmış, adaptör görünüşte yüklenmiş ve **tek bir olayı yayınla olmayan** ile çalışır. Bu tam olarak söyleyen bir uyarı kaydeder — çalışma hiçbir şey kaydedildiğinde loglarınızı ilk kontrol edin. +Bunu yanlış yaparsanız süreç, SDK içe aktarılmış ve adaptör görünüşte kurulmuş hâlde çalışır, ama **tek bir olay bile yayınlanmaz**. Tam olarak bunu söyleyen bir uyarı günlüğe yazılır; bu yüzden bir çalışma hiçbir şey kaydetmediğinde önce günlüklerinize bakın.