diff --git a/docs/ar/index.mdx b/docs/ar/index.mdx index 217b561b2..0887d98c1 100644 --- a/docs/ar/index.mdx +++ b/docs/ar/index.mdx @@ -1,19 +1,20 @@ --- -title: "اجعل وكيلك آمناً من الأعطال" -description: "المراقبة والإنفاذ لكل بيئة تشغيل يعمل بها وكيلك — واجهات سطر الأوامر للترميز، بوابات الدردشة، المساعدات المستضافة ذاتياً، ووكلاؤك المجهزون بأدوات المراقبة." +--- +title: "اجعل وكيلك آمنًا تماماً" +description: "قابلية الملاحظة والتطبيق لكل بيئة تشغيل يعمل فيها وكيلك — واجهات سطر الأوامر للترميز، بوابات الدردشة، المساعدات المستضافة ذاتياً، والوكلاء المزودين بأدوات المراقبة الخاصة بك." icon: "shield-check" --- -يساعد Failproof AI الفرق على فهم ما فعله الوكيل، واكتشاف مكان فشله، ونشر الحماية قبل تكرار السلوك نفسه مرة أخرى. +Failproof AI يساعد الفرق على فهم ما فعله الوكلاء، والعثور على أماكن فشلهم، ونشر الحماية قبل حدوث نفس السلوك مرة أخرى. -**البيئة التشغيلية** هي ما يعمل وكيلك بداخله فعلياً. يتصل Failproof AI بـ 12 منها — واجهات سطر الأوامر للترميز مثل Claude Code و Codex، بوابات الدردشة مثل Hermes، المساعدات المستضافة ذاتياً مثل OpenClaw — وتطبق الأحداث والسياسات وسجل الجلسات نفسه على كل واحدة منها. يرسل الوكلاء بدون بيئة تشغيلية البيانات من خلال [Python SDK](/ar/reference/custom-agents)، الذي يتتبع ويدقق فيها؛ لإنفاذ سياسة هناك تحتاج إلى hook في runtime الخاص بك. +**البيئة التشغيلية** هي أي شيء يعمل فيه وكيلك بالفعل. Failproof AI يربط 12 منها — واجهات سطر أوامر للترميز مثل Claude Code و Codex، وبوابات دردشة مثل Hermes، ومساعدات مستضافة ذاتياً مثل OpenClaw — وتنطبق نفس الأحداث والسياسات وسجل الجلسات على كل واحدة منها. الوكلاء الذين ليس لديهم بيئة تشغيلية يقدمون تقارير من خلال [Python SDK](/ar/reference/custom-agents)، الذي يتتبعهم ويقومون بتدقيقهم؛ تطبيق سياسة هناك يتطلب خطاف في وقت التشغيل الخاص بك. - - استخدم المهارة لتجهيز مشروعك، واتصل به، وتحقق من وصول سجلات الوكيل. + + استخدم المهارة لأتمتة مشروعك وتوصيله والتحقق من وصول سجلات الوكيل. - حلل واستعلم وأنشئ لوحات معلومات وقم بعمليات تدقيق باللغة الطبيعية على سجلات الوكيل. + حلل واستعلم وقم ببناء لوحات معلومات وتشغيل عمليات التدقيق باللغة الطبيعية على سجلات وكيلك. @@ -22,20 +23,20 @@ icon: "shield-check" تابع استدعاءات النموذج والأدوات والأخطاء والمدخلات البشرية والكمون وقرارات السياسة في جلسة واحدة. - دقق مجموعة محددة من الجلسات، راجع النتائج المدعومة بالأدلة، وتتبع التصحيح كمشاكل. + قم بتدقيق مجموعة محددة من الجلسات وراجع النتائج المدعومة بالأدلة وتابع الإصلاح كمشاكل. - حول طريقة فشل معروفة إلى سياسة، راقب تأثيرها، ونشرها عبر أسطولك. + حول وضع فشل معروف إلى سياسة وراقب تأثيره ونشره عبر أسطولك. -> **الجلسة → التدقيق → البحث → المشكلة → السياسة**
-> تتبع ما حدث، ابحث عن الفشل، أدر الاستجابة، ثم منع السلوك نفسه في الأدوار المستقبلية. +> **جلسة → تدقيق → نتيجة → مشكلة → سياسة**
+> تتبع ما حدث، أوجد الفشل، أدر الاستجابة، ثم منع نفس السلوك في التشغيلات المستقبلية. ## ابدأ من هنا -إذا كنت تنشر وكيلك المجهز بأدوات المراقبة للمرة الأولى، ابدأ بـ [الدليل السريع](/ar/start/quickstart). إذا كانت البيانات تصل بالفعل، افتح [الجلسات](/ar/sessions/overview) وفتش عملية تشغيل حقيقية قبل تكوين عمليات التدقيق أو السياسات. +إذا كنت تنشر وكيلك المزود بأدوات المراقبة للمرة الأولى، فابدأ بـ [البدء السريع](/ar/start/quickstart). إذا كانت البيانات تصل بالفعل، فافتح [الجلسات](/ar/sessions/overview) وتفحص تشغيلاً حقيقياً قبل تكوين عمليات التدقيق أو السياسات. - - أكمل سير العمل الشامل من الالتقاط إلى سياسة تم نشرها بأمان. + + أكمل سير العمل من الطرف إلى الطرف الآخر من المراقبة إلى سياسة آمنة ومنشورة. \ No newline at end of file diff --git a/docs/ar/policies/deploy.mdx b/docs/ar/policies/deploy.mdx index ea2ad5828..8cc7efbea 100644 --- a/docs/ar/policies/deploy.mdx +++ b/docs/ar/policies/deploy.mdx @@ -1,7 +1,7 @@ --- --- title: "نشر السياسات" -description: "طرح نسخة سياسة تم مراجعتها على الأجهزة المستهدفة." +description: "إطلاق نسخة سياسة تم مراجعتها إلى الأجهزة المقصودة." icon: "cloud-upload" --- @@ -11,38 +11,42 @@ icon: "cloud-upload" - 1. انتقل إلى **المسؤول → الإنفاذ**، ابحث عن الجهاز، وقم بتوسيع صفه. - 2. اختر **تعديل**، أضف نسخة السياسة المراجعة، واختر **مراقبة** أو تأثيرها الإنفاذي. - 3. طبّق التغيير، ثم انتظر الفحص التالي للجهاز وأكّد حالة النشر والتغطية. - 4. انتقل إلى **مراقبة → سياسة** لفحص القرارات المباشرة. + 1. انتقل إلى **Admin → enforcement**، ابحث عن الجهاز، وقم بتوسيع صفه. + 2. اختر **edit**، أضف نسخة السياسة المراجعة، واختر **observe** أو تأثيرها الإجباري. + 3. طبّق التغيير، ثم انتظر فحص الجهاز التالي وتأكد من حالة نشره وتغطيته. + 4. انتقل إلى **Observe → policy** للفحص القرارات المباشرة. - ![محرر نشر الجهاز يعرض نسخ السياسات وتأثيرات الإنفاذ والمراقبة وإجراء تطبيق النشر.](/images/dashboard/enforcement-editor.png) + ![محرر نشر الجهاز مع نسخ السياسات، وتأثيرات الفرض والمراقبة، وإجراء تطبيق النشر.](/images/dashboard/enforcement-editor.png) - لا يتم عن قصد كشف نقاط نهاية النشر السحابي كأوامر `fp` عادية. تحقق من الجهاز محليًا، ثم قم بالنشر عبر لوحة التحكم: + قم بالنشر من واجهة سطر الأوامر باستخدام `fp fleet`. راجع مجموعة النتائج قبل تطبيقها — يطبع `deploy` الخطة الكاملة ويسأل **فقط على محطة تفاعلية بدون `--json`**. تحت `--json`، مع `--yes`، أو مع إعادة توجيه stdin (خطوة CI، سكريبت، وكيل يشغل shell) يتم التطبيق فوراً بدون خطة وبدون مطالبة — لذا قم بتشغيل `fp fleet show ` أولاً إذا كنت تريد المراجعة: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - استخدم `fp sessions --env production --since 24h` و `fp events --event-type hook_completed` بعد النشر للتحقق من وصول النشاط إلى Cloud. + يعرض `fp fleet diff ` النية مقابل التسليم (يُقرأ الجهاز كـ `behind` حتى يقوم بالاستطلاع التالي)، `fp fleet history ` يسرد الأجيال، و `fp fleet rollback ` يستعيد واحداً — يرفض إذا كان هذا الجيل يسمي سياسة تم تعطيلها أو حذفها. + + تحقق من الجهاز نفسه باستخدام `failproofai config --status`، واستخدم `fp sessions --env production --since 24h` و `fp events --event-type hook_completed` بعد النشر للتحقق من وصول النشاط إلى Cloud. - قم بنشر نسخة تم مراجعتها وليس مسودة قابلة للتغيير، بدءًا بجهاز غير إنتاجي أو مجموعة صغيرة يمكنك فحص جلساتها. + قم بنشر نسخة تم مراجعتها، وليس مسودة قابلة للتغيير، بدءاً بجهاز غير إنتاجي أو مجموعة صغيرة يمكنك فحص جلساتها. - - راجع المطابقات والأسباب والأدوات المتأثرة والإيجابيات الخاطئة دون حجب العمل. + + راجع التطابقات والأسباب والأدوات المتأثرة والإيجابيات الكاذبة بدون حجب العمل. - - قم بالترقية بعد أن تفصل المطابقات المراقبة الإجراءات غير الآمنة عن الإجراءات الصحيحة، ثم تأكد من أن كل جهاز مستهدف قد سحب النشر ويُبلّغ عن القرارات. + + قم بالترقية بعد المطابقات المرصودة التي تفصل الإجراءات غير الآمنة عن الإجراءات الصحيحة، ثم تأكد من أن كل جهاز مقصود قد سحب النشر ويقدم التقارير عن القرارات. -تحتاج الأجهزة إلى قدرة `policies:pull`. يتم التحكم في تقارير الأحداث بشكل منفصل بواسطة `events:add`؛ تحقق من كليهما عندما تتوقع تحليل الـ Cloud والإنفاذ. +تحتاج الأجهزة إلى القدرة على `policies:pull`. يتم التحكم في الإبلاغ عن الأحداث بشكل منفصل بواسطة `events:add`؛ تحقق من كليهما عندما تتوقع تحليل Cloud والفرض. - إدارة الإنفاذ هي عملية سير عمل إدارية في الـ Cloud. لا تتعامل مع مسارات الإنفاذ الحصرية للجذر كنقاط نهاية `/v1` API عادية للعملاء. + إدارة الفرض هي سير عمل إداري في Cloud. لا تعامل مسارات الفرض للمسؤول الجذر فقط كنقاط نهاية API عادية للعملاء `/v1`. \ No newline at end of file diff --git a/docs/ar/policies/editor.mdx b/docs/ar/policies/editor.mdx index 54a17a217..ed6ed1238 100644 --- a/docs/ar/policies/editor.mdx +++ b/docs/ar/policies/editor.mdx @@ -1,48 +1,50 @@ --- --- title: "محرر السياسات" -description: "إنشاء وتعديل السياسات ذات الإصدارات من نمط فشل مؤكد." +description: "إنشاء ومراجعة السياسات ذات الإصدارات من نمط فشل مؤكد." icon: "file-pen-line" --- -استخدم محرر السياسات لتحويل نتيجة بحث أو مشكلة إلى قاعدة قابلة للنشر. حافظ على فصل عملية التأليف عن النشر بحيث لا يمكن لمسودة أن تغيّر السلوك المباشر بصمت. +استخدم محرر السياسات لتحويل نتيجة بحث أو مشكلة إلى قاعدة قابلة للنشر. احتفظ بالتأليف منفصلاً عن النشر بحيث لا يمكن لمسودة أن تغيّر السلوك الحي بصمت. -عندما تكون لديك مشكلة بها نمط إجراء قابل للتكرار، افتحها ضمن **Analyze → issues** واختر **generate policy**. يشرح Failproof AI أولاً ما إذا كانت السياسة يمكنها التعبير عن المشكلة، ثم ينقل النية المراجعة وسياق البحث إلى المحرر. يبقى المصدر المُنشأ مسودة إلى أن تنشره. +عندما تكون لديك مشكلة بها نمط إجراء قابل للتكرار، افتحها تحت **Analyze → issues** واختر **generate policy**. يشرح Failproof AI أولاً ما إذا كانت السياسة يمكنها التعبير عن المشكلة، ثم تنقل النية المراجعة وسياق النتيجة إلى المحرر. يبقى المصدر المُنتج كمسودة حتى تنشره. ## نشر إصدار السياسة - - 1. انتقل إلى **Admin → policy editor** وفي **compose**، صِف نمط الفشل أو الصق مصدر سياسة JavaScript. - 2. تحقق من صحة المصدر وأصلح كل خطأ مُبلّغ عنه. - 3. أدخل هوية السياسة ونشرها، ثم استخدم **library** للمقارنة أو تعطيل الإصدارات. - 4. اختر **enforcement** عندما يكون الإصدار جاهزاً لطرح آلي على الآلات. + + 1. انتقل إلى **Admin → policy editor** وفي **compose**، وصف نمط الفشل أو الصق مصدر سياسة JavaScript. + 2. تحقق من صحة المصدر وأصلح كل خطأ يتم الإبلاغ عنه. + 3. أدخل هوية السياسة وانشرها، ثم استخدم **library** للمقارنة أو تعطيل الإصدارات. + 4. اختر **enforcement** عندما يكون الإصدار جاهزاً لنشر الآلة. - ![عرض محرر السياسات مع هوية السياسة والتأليف بمساعدة الذكاء الاصطناعي والتحقق من صحة المصدر وعناصر التحكم في النشر.](/images/dashboard/policy-editor.png) + ![عرض compose في محرر السياسات يتضمن هوية السياسة والتأليف بمساعدة الذكاء الاصطناعي والتحقق من المصدر وعناصر التحكم في النشر.](/images/dashboard/policy-editor.png) - لا ينشر Cloud CLI إصدارات السياسات. تحقق من صحة المصدر محلياً قبل نسخه إلى المحرر: + انشر من واجهة سطر الأوامر باستخدام `fp policies publish`. تُنشئ **إصدار جديد** ولا تحرر واحداً موجوداً، وتتحقق من المصدر باستخدام node قبل الإرسال — لا يفعل ذلك شيء آخر في المراحل اللاحقة، لذا كان خطأ بناء الجملة قد يظهر على الآلة في وقت الفرض: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - انشر الإصدار المراجع من **Admin → policy editor**. + النشر لا ينشر أي شيء — يبقى إصدار جديد غير مستخدم حتى يضعه `fp fleet deploy` على آلة. يقوم `fp policies compose ""` بصياغة المصدر بمساعدة مساعد Cloud ويطبعه للمراجعة بدلاً من نشره. + + لتثبيت سياسة في وكيل CLI محلي بدلاً من ذلك (وليس Cloud)، استخدم `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. -## قائمة فحص التأليف +## قائمة التحقق من التأليف -1. سمّ نمط الفشل باستخدام لغة تشغيلية. -2. اختر أحداث الخطاف والأدوات التي توفر أدلة كافية للقرار. -3. اكتب الشرط الأضيق الذي يطابق السلوك غير الآمن. -4. أرجع سبباً يخبر الوكيل أو المشغل بما يجب فعله بعد ذلك. -5. أضف أمثلة يجب أن تطابق والأمثلة التي يجب أن تبقى مسموحة. -6. احفظ إصدارة جديدة وطلب مراجعة. +1. سمّ نمط الفشل باللغة التشغيلية. +2. اختر أحداث الخطاف والأدوات التي تحتوي على أدلة كافية للقرار. +3. اكتب أضيق شرط يطابق السلوك غير الآمن. +4. أرجع سبباً يخبر الوكيل أو المشغل ما يجب فعله بعد ذلك. +5. أضف أمثلة يجب أن تطابق وأمثلة يجب أن تبقى مسموحة. +6. احفظ إصدار جديد واطلب مراجعة. -استخدم `instruct` عندما يمكن للوكيل تصحيح المسار بأمان. استخدم `deny` عندما يؤدي السماح بالإجراء إلى إنشاء خطر غير مقبول أو لا يمكن عكسه. +استخدم `instruct` عندما يمكن للوكيل تصحيح المسار بأمان. استخدم `deny` عندما يؤدي السماح بالإجراء إلى خلق خطر غير مقبول أو غير قابل للعكس. - إصدارات السياسات عبارة عن مدخلات نشر ثابتة. تحرير مسودة ينشئ إصدارة جديدة؛ يجب ألا يعيد كتابة الإصدار المُعيَّن بالفعل للآلات. + إصدارات السياسة هي مدخلات نشر غير قابلة للتغيير. يؤدي تحرير مسودة إلى إنشاء إصدار جديد؛ لا ينبغي أن يعيد كتابة الإصدار المعين بالفعل للآلات. \ No newline at end of file diff --git a/docs/ar/reference/cloud-cli.mdx b/docs/ar/reference/cloud-cli.mdx index 6daae59c4..5c9e415ad 100644 --- a/docs/ar/reference/cloud-cli.mdx +++ b/docs/ar/reference/cloud-cli.mdx @@ -1,12 +1,12 @@ --- -title: "واجهة سطر أوامر Failproof Cloud" -description: "مرجع شامل للاستعلام وإدارة Failproof AI Cloud باستخدام fp." +title: "واجهة سطر الأوامر Failproof Cloud" +description: "مرجع شامل للاستعلام عن Failproof AI Cloud وإدارته باستخدام fp." icon: "cloud-cog" --- -استخدم `fp` للتحقق من تلمترية Cloud وإدارة عمليات التدقيق والنتائج والمشاكل والتنبيهات والمفاتيح والمستخدمين والاستعلامات والإعدادات. استخدم [`failproofai`](/ar/reference/failproof-cli) للتعاملات المحلية والسياسات والالتقاط وتسجيل الأجهزة. +استخدم `fp` لفحص بيانات Cloud الوصفية وإدارة الفرض المدار بواسطة السحابة (السياسات وعمليات نشر الأسطول وقرارات الحماية) وإدارة التدقيق والنتائج والقضايا والتنبيهات والمفاتيح والمستخدمين والاستعلامات والإعدادات. استخدم [`failproofai`](/ar/reference/failproof-cli) للخطافات المحلية والسياسات والالتقاط وتسجيل الماكينات. -قم بتثبيت واجهة سطر الأوامر السحابية المُصدرة كأداة معزولة: +ثبّت Cloud CLI المُصدرة كأداة معزولة: ```bash uv tool install fp-cloud-cli @@ -20,7 +20,7 @@ fp login fp whoami ``` -## الصيغة +## بناء الجملة ```text fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] @@ -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,30 +57,34 @@ 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`. | +| `--env ` | مرشح البيئة؛ كرّر أو افصل القيم بفواصل. | +| `--event-type ` | مرشح نوع الحدث؛ كرّر أو افصل القيم بفواصل. | +| `--agent-id ` | مرشح الوكيل؛ كرّر أو افصل القيم بفواصل. | +| `--session-id ` | مرشح الجلسة؛ كرّر أو افصل القيم بفواصل. | +| `--search ` | بحث نصي في الحمل الأولي؛ قابل للتكرار، مع مطابقة أي حد. | +| `--order asc\|desc` | ترتيب الوقت. الافتراضي: الأحدث أولاً. | +| `--all` | صفحة تلقائية تصل إلى `--limit`. | | `--cursor ` | استئنف من مؤشر معتم. | -| `--page-size ` | صفوف لكل طلب مع `--all`؛ بحد أقصى `200`. | -| `--full` | قم بتضمين الحمولات الخام من خلال نقطة الحدث الأثقل. | -| `--fields ` | إرجاع الحقول المحددة فقط؛ طلب `payload` يفعل الوضع الكامل. | +| `--page-size ` | الصفوف لكل طلب مع `--all`؛ الحد الأقصى `200`. | +| `--full` | ضمّن الأحمال الأولية عبر نقطة الحدث الأثقل وزناً. | +| `--fields ` | أرجع الحقول المحددة فقط؛ يتطلب طلب `payload` وضع المحرّر الكامل. | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` + + `--all` ينقّح **حتى `--limit`**، والذي يأتي بقيمة افتراضية تبلغ **50** — لذلك `--all` بمفردها تتوقف عند 50 صفاً. عندما تتوقف مبكراً، تحمل الاستجابة `next_cursor` للاستئناف منها؛ `"next_cursor": null` تعني أن الخلاصة استُنفدت حقاً. + + ### الجلسات ```text @@ -89,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`. | -| `--fields ` | إرجاع الحقول المحددة فقط. | -| `--full-ids` | لا تقصر معرفات الجلسة في مخرجات الطرفية. | -| `--agents` | قم بتوسيع قائمة الوكلاء لجلسات الوكلاء المتعددين. | +| `--page-size ` | الصفوف لكل طلب مع `--all`؛ الحد الأقصى `200`. | +| `--fields ` | أرجع الحقول المحددة فقط. | +| `--full-ids` | لا تختصر معرّفات الجلسة في إخراج المحطة الطرفية. | +| `--agents` | وسّع قائمة الوكيل لجلسات متعددة الوكلاء. | ### التقييمات @@ -111,15 +115,15 @@ fp evals [OPTIONS] | الخيار | الوصف | | --- | --- | -| `--aggregate` | اعرض الإجماليات والإحصائيات لكل نقاط بدلاً من التقييمات الفردية. | +| `--aggregate` | اعرض الإجماليات والإحصائيات حسب الدرجة بدلاً من التقييمات الفردية. | | `--limit`, `-n ` | الحد الأقصى لصفوف القائمة. الافتراضي: `50`. | -| `--since`, `--from`, `--to` | اختر نطاق الوقت. | +| `--since`, `--from`, `--to` | حدّد النطاق الزمني. | | `--env`, `--status`, `--agent-id`, `--session-id` | ضيّق إلى قيمة واحدة محددة لكل مرشح. | -| `--score KEY:MIN..MAX` | نطاق النقاط؛ قابل للتكرار ويجب أن تتطابق جميع النطاقات. | -| `--all`, `--cursor`, `--page-size` | التحكم في ترقيم قائمة. | -| `--fields ` | إرجاع الحقول المحددة فقط. | -| `--full-ids` | اعرض معرفات الجلسة الكاملة. | -| `--scores-full` | اعرض كل نقطة في مخرجات الطرفية. | +| `--score KEY:MIN..MAX` | نطاق الدرجة؛ قابل للتكرار ويجب أن تتطابق جميع النطاقات. | +| `--all`, `--cursor`, `--page-size` | تحكم في ترقيم قائمة الصفحات. | +| `--fields ` | أرجع الحقول المحددة فقط. | +| `--full-ids` | اعرض معرّفات الجلسة الكاملة. | +| `--scores-full` | اعرض كل درجة في إخراج المحطة الطرفية. | ### الأخطاء @@ -129,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` | اعرض معرفات الجلسة الكاملة. | +| `--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 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 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 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 create NAME` | أنشئ تنبيه. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | +| `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 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 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 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` | غيّر الموجز أو عناوين 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 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 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 ` مطلوب | #### خيارات إنشاء التدقيق @@ -257,95 +261,139 @@ fp audits create checkout-reliability \ | الخيار | الوصف | | --- | --- | -| `--file ` | استند التعريف على JSON أو استخدم `-` للمدخلات المعيارية. الأعلام الصريحة تتجاوز قيم الملف. | +| `--file ` | اعتمد التعريف على JSON، أو استخدم `-` لـ stdin. الأعلام الصريحة تتجاوز قيم الملف. | | `--description ` | اذكر سؤال الفشل أو الغرض. | -| `--enabled` / `--disabled` | ابدأ الجدولة قيد التشغيل أو الإيقاف. الافتراضي: مُفعّل. | +| `--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 عام؛ كرر حتى خمس مرات. | +| `--sensitivity low\|medium\|high` | اضبط حساسية الإبلاغ. الافتراضي: `medium`. | +| `--channels ''` | مصفوفة قناة الإخطار. | +| `--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 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`. +حالات القضايا الصحيحة هي `firing`, `acknowledged`, و `resolved`. درجات القضايا المستقلة هي `info`, `warning`, و `critical`. -### مساعد Cloud +### مساعد السحابة | الأمر | الغرض | الخيارات | | --- | --- | --- | -| `fp agent health` | تحقق من توفر المساعد والإعدادات. | — | -| `fp agent models` | اعرض قائمة نماذج المساعد المتاحة. | — | -| `fp agent chats` | اعرض قائمة الدردشات المحفوظة. | — | -| `fp agent ask [MESSAGE]` | ابدأ أو تابع دردشة؛ اقرأ من stdin عند حذف الرسالة. | `--chat`; `--model`; `--page-context` | +| `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 rename CHAT_ID` | أعد تسمية محادثة. | `--title` مطلوب | | `fp agent delete CHAT_ID` | احذف محادثة. | `--yes`, `-y` | -## أعلام عامة +### السياسات + +إصدارات السياسات المدارة بواسطة السحابة. **جلسة فقط** — كل أمر هنا ينتهي برمز `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 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 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. | +| `--quiet`, `-q` | كبّت إخراج الحالة على stderr. | | `--no-color` | عطّل الإخراج الملون. | | `--insecure` / `--secure` | عطّل أو استعد التحقق من شهادة TLS. | -| `--version` | اطبع الإصدار غير المعبأ وخرج. | +| `--version` | اطبع الإصدار الصريح والخروج. | | `--help`, `-h` | اعرض المساعدة. | -`--api-key` مقصود للأتمتة. تتطلب عمليات تسجيل الدخول وتبديل المنظمة والأوامر المساعدة جلسة مستخدم. +`--api-key` مخصص للأتمتة. تسجيل الدخول وتبديل المؤسسة وأوامر المساعد تتطلب جلسة مستخدم. ## متغيرات البيئة -| المتغير | المكافئ أو الغرض | +| المتغير | ما يعادله أو الغرض | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | أعد تحديد موقع مجلد إعدادات CLI الحالي. | -| `AGENTEYE_ANALYTICS_DISABLED` أو `DO_NOT_TRACK` | عطّل تحليلات CLI المجهولة. | +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `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` | عطّل الإخراج الملون. | -تتجاوز الأعلام الصريحة متغيرات البيئة، التي تتجاوز الإعدادات المحفوظة. في وضع مفتاح API، اختر المستأجر بوضوح مع `--org` أو `AGENTEYE_ORG`. +الأعلام الصريحة تتجاوز متغيرات البيئة، التي تتجاوز التكوين المحفوظ. في وضع مفتاح API، حدّد المستأجر بشكل صريح باستخدام `--org` أو `FP_ORG`. + + + تهجئات `AGENTEYE_*` لهذه **لا يتم قراءتها بواسطة `fp`** ولم تكن أبداً — يصرّح CLI بـ `FP_*` (`fp_cli/app.py`)، والمتغير غير المعروف ليس خطأ. تعيين `AGENTEYE_DASHBOARD_URL` لا يعيد استهداف CLI؛ يتم تجاهله والأمر يعمل بصمت ضد لوحة القيادة المحفوظة بدلاً من ذلك. + + `AGENTEYE_HOME` و `AGENTEYE_ENVIRONMENT` موجودة بعد، لكنها تنتمي إلى **جامع و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 1a23541dd..0e8e23129 100644 --- a/docs/ar/reference/custom-agents.mdx +++ b/docs/ar/reference/custom-agents.mdx @@ -1,47 +1,43 @@ --- -title: "وكلاء مخصصون" -description: "قم بتتبع الآثار من الوكلاء المخصصين باستخدام Failproof AI حتى يتمكن من إعادة بناء التشغيلات والعثور على الأخطاء." +--- +title: "الوكلاء المخصصون" +description: "التكوين وفهرس الأحداث وقواعد الارتباط والتسليم لـ failproofai-sdk." icon: "python" --- -قم بتتبع الآثار من وكيل مخصص باستخدام `failproofai-sdk` بحيث يمكن لـ Failproof AI إعادة بناء كل تشغيل، وتدقيق سلوكه، والعثور على الأخطاء المدعومة بالأدلة. يكتب SDK أحداثًا منظمة لـ Failproof daemon لتسليمها إلى Cloud. يتطلب Python 3.10 أو أحدث. - -يجعل التتبع الوكلاء المخصصين قابلين للملاحظة والتدقيق. يتطلب منع إجراء غير آمن قبل تنفيذه أيضًا خطاف إنفاذ في وقت التشغيل الخاص بك. - - - لفرض السياسات في إعداد وكيل مخصص، [اتصل بـ Failproof AI](mailto:support@befailproof.ai). سنساعدك في ربط نموذج وقت التشغيل الخاص بك والأداة وحدود دورة الحياة بـ policy hooks. - +شرح لكل إعدادات وطرق وحقول. إذا كنت تقوم بالأداة لأول مرة، ابدأ بالدليل — هذه الصفحة مخصصة للبحث عن معلومات محددة. -
- -
+ + + التثبيت والأداة وطرق الأحداث ومثال عملي والمشاكل الشائعة. + + + LangChain و CrewAI و LlamaIndex و Pydantic AI توفر الأداة لنفسها بنداء واحد. + + -## تثبيت `failproofai-sdk` +Python 3.10 أو أحدث. بدون تبعيات وقت التشغيل. -يتم توزيع SDK حاليًا كعجلة خاصة. اطلب من جهة اتصالك في Failproof AI الحصول على الإصدار الحالي وإمكانية التنزيل. +## التثبيت ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -مع `uv`، قم بتنزيل العجلة أولاً وقم بتشغيل `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl`. قم بتثبيت العجلة في مستودع آثار خاص أو قفل التبعيات. +يتم تثبيت الحزمة باسم `failproofai-sdk` واستيرادها في Python باسم `failproofai_sdk`. ملحقات الأطر مثل `failproofai-sdk[langgraph]` تثبت الإطار نفسه؛ المحولات تأتي دائماً في عجلة القاعدة. -يتم تثبيت الحزمة باسم `failproofai-sdk` وتُستورد في Python باسم `failproofai`. - -## توصيل Failproof daemon +## توصيل خادم Failproof - - 1. انتقل إلى **Admin → Keys** وأنشئ مفتاحًا باستخدام `events:add`. - 2. [وصّل Failproof daemon إلى Cloud](/ar/start/setup#connect-a-machine-to-cloud) على جهاز الوكيل. - 3. قم بتشغيل جلسة واحدة مزودة بتتبع، ثم ابحث عن معرّفها الدقيق ضمن **Observe → Events**. - 4. انتقل إلى **Observe → Sessions**، واختر نفس البيئة، وافتح الآثار المعاد بناؤها. + + 1. انتقل إلى **Admin → Keys** وأنشئ مفتاحاً بصلاحية `events:add`. + 2. [وصّل خادم Failproof إلى السحابة](/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) - + ```bash failproofai config \ --connect https://app.befailproof.ai \ @@ -51,102 +47,84 @@ python -c "import failproofai; print(failproofai.__version__)" -## تتبع تشغيل كامل - -استدع `configure()` مرة واحدة أثناء بدء العملية. كل استدعاء حدث هو keyword-only ويتطلب `session_id` و `agent_id` مستقرة. +## التكوين ```python -import traceback -import uuid +import failproofai_sdk + +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -import failproofai +| المعامل | الوظيفة | +| --- | --- | +| `environment` | التسمية على كل حدث — `production` أو `staging` أو `prod-eu`. القيمة الافتراضية `dev`. | +| `flush_interval` | مدى تكرار كتابة الخيط الخلفي إلى القرص، بالثواني. القيمة الافتراضية `0.5`. | +| `base_dir` | مكان الكتابة. القيمة الافتراضية سpool الخادم، وهو ما تريده ما لم تعرف خلاف ذلك. | -failproofai.configure(environment="production") +اضبط عن طريق متغير البيئة بدلاً من ذلك: -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +| المتغير | الوظيفة | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | يضبط `environment` دون تغيير الكود، عندما تكون التسمية تابعة للنشر وليس التطبيق. معامل `configure()` يتفوق عليه. | +| `FAILPROOFAI_HOME` | ينقل جذر Failproof AI الذي يحتوي على spool. | +| `FAILPROOFAI_SDK_STRICT` | `1` يجعل أخطاء الأداة ترفع استثناءات بدلاً من تسجيلها. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` يجعل مشكلة توافق الإطار ترفع استثناءً بدلاً من تحذير والمتابعة. | -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) + + **بدون فواصل في `environment`.** يقسم الاستيعاب هذا الحقل على الفواصل لبناء مرشحاته، وينطبق أي حدث يحتوي التسمية على واحد — لذا قد يختفي التشغيل الكامل بصمت. اكتب `prod-eu` وليس `prod,eu`. -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + `configure(environment="prod,eu")` يرفع الاستثناء لتكتشف على الفور. `AGENTEYE_ENVIRONMENT` لا يمكنه الرفع — لا أحد يناديك — لذا يحذر مرة واحدة ويعود إلى `dev`. + + +تُصف الأحداث في الذاكرة وتُكتب في الخلفية كل `flush_interval` ثانية، مع كتابة نهائية عند خروج المفسّر. العملية المقتولة مباشرة تفقد أي شيء لم يُكتب بعد. -أصدر `agent_start` مرة واحدة لكل فاعل. بالنسبة للوكلاء الفرعيين، أعد استخدام `session_id` الخاص بالأب، وأعط كل فاعل `agent_id` مميز، واضبط `parent_id` على معرّف الوكيل الأب، وليس معرّف الجلسة. +## الهوية -## مرجع التكوين +ينتمي كل حدث إلى جلسة ووكيل. **النطاقات تملأ كليهما**، لذا نادراً ما تمرّرهما: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| الإعداد | السلوك | -| --- | --- | -| `base_dir` | جذر spool صريح. يأخذ الأولوية على جميع متغيرات البيئة. | -| `flush_interval` | الثواني بين الكتابات في الخلفية من الذاكرة إلى JSONL. الافتراضي: `0.5`. | -| `environment` | تسمية النشر على كل حدث. الافتراضي هو `dev`. | -| `FAILPROOFAI_HOME` | يغير جذر Failproof AI الذي يحتوي على spool `custom-agents`. | - -يكتب SDK إلى `base_dir` الصريح عند تعيينه. وإلا، فإنه يستخدم spool `custom-agents` الخاص بـ Failproof daemon ضمن `FAILPROOFAI_HOME` أو `~/.failproofai`. +إمرار `session_id` أو `agent_id` صراحةً يعمل أيضاً ويتفوق. بدون ربط أو تمرير، يرفع النداء `TypeError` بدلاً من إطلاق حدث قد تتجاهله السحابة. -يقوم SDK بطلب الاستدعاءات في الذاكرة ويكتب دفعات على سلسلة خيط في الخلفية. كما يحاول التنظيف النهائي من خلال معالجة Python `atexit`. بالنسبة للعمال قصيري الأجل، اسمح بإيقاف المترجم الطبيعي؛ قد يؤدي إنهاء العملية الثابتة إلى فقدان الأحداث التي لا تزال في الذاكرة. + + الهوية تعمل على متغيرات السياق. تتبع مهام `asyncio` تلقائياً، لكن **ليس** الخيوط الجديدة — غلّف عامل في `failproofai_sdk.propagate()` أو أحداثه ستنفصل. + ## فهرس الأحداث -جميع الطرق ترجع `None`. يتم حذف الحقول المتروكة كـ `None` بدلاً من كتابتها كـ JSON `null`. +خمس عشرة طريقة. معظمها يأتي في **أزواج** — تستدعي المفتاح، ثم الإغلاق، و 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` | + +ثلاثة تقف بمفردها: `error` و `human_pause` و `human_interrupt`. + + + +كل طريقة تأخذ أيضاً `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,29 +135,66 @@ failproofai.configure( | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -استخدم `outcome="failed"`، `"error"`، `"timeout"`، أو `"rejected"` عندما يجب أن تُعتبر عملية الإكمال بمثابة فشل. القيم الأخرى، بما فيها `"failure"`، لا تُصنف كفشل من قبل backend الحالي. + + + + لتحديد تشغيل كفاشل، يجب أن يكون `outcome` واحداً من `failed` أو `error` أو `timeout` أو `rejected`. أي شيء آخر — بما فيه الحالة القريبة `"failure"` — يُحسب كنجاح. + + +## الاقتران والمدة + +**قاعدة واحدة: أعطِ حدث الإغلاق نفس المعرّف الذي لفاتح.** هذا هو ما يقترنها، وما يسمح لـ SDK بقياس الفجوة. + +| الزوج | مطابق على | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**لا تمرّر `duration_ms` بنفسك.** يقيسها SDK، وتمريرها يرفع `ValueError`. -## قواعد الارتباط والمدة +الاستثناء الوحيد هو `model_response`، حيث أنت وحدك تعرف زمن الكمون الفعلي للمزود. مرّر عدداً صحيحاً من الميلي ثانية — العدد العشري يرفع، لأن العمود عدد صحيح 32 بت وقد ينتهي به الحال فارغاً. -- أعد استخدام نفس `tool_call_id` أو `hook_id` أو `pause_id` أو `input_id` لحدث الإكمال المطابق. -- يحسب SDK `duration_ms` لـ `tool_result` و `hook_completed` و `agent_resume` و `human_input`. تمرير قيمة بنفسك إلى تلك الطرق يرفع `ValueError`. -- معرفات الأداة والخطاف تشترك في خريطة انتظار واحدة على مستوى العملية. اجعلها فريدة عالميًا عبر الجلسات المتزامنة وعبر كلا المساحة؛ معرّفات الموفر أو UUIDs هي الأكثر أمانًا. -- الزوج المنقسم عبر العمليات لا يزال يرتبط بالتطبيق، لكن SDK لا يمكنه حساب مدته داخل العملية. -- تحتفظ خريطة الانتظار بـ 10000 بداية على الأكثر وتزيل الإدخال الأقدم عند امتلاء الحد. + -## الحقول المخصصة والبيانات الضخمة +- **المعرّفات تحتاج فقط إلى أن تكون فريدة لكل نوع، لكل جلسة.** استدعاء أداة وخطاف قد يشاركان واحداً؛ جلستان تعملان في نفس الوقت قد تعيد استخدام نفس المعرّفات دون تصادم. +- **لا يتم تحديد نطاقها لوكيل.** زوج فُتح تحت وكيل واحد وأُغلق تحت آخر يطابق أيضاً — وهذه هي الحالة الطبيعية في كود متعدد الوكلاء. +- **`request_id` اختياري لكن موصى به.** بدونه، تقترن أحداث النموذج بالترتيب الذي تصل، لذا نداءان متزامنان في نفس الوكيل قد يقترنان خطأً. +- **زوج مقسم عبر العمليات** يطابق أيضاً في السحابة، لكن SDK لا يمكنه قياسه — لا شيء في أي عملية رأى كلا النصفين. +- **على الأكثر 10000 فاتح ينتظر أقرب في نفس الوقت.** بعد ذلك الأقدم يُحذف، لذا تسريب لا يمكنه النمو بدون حد. -كل حدث يقبل حقول keyword إضافية. استخدم القيم المتوافقة مع JSON عندما تحتاج الاستعلامات الموضوعية إلى البنية. الأوراق غير المدعومة مثل UUIDs والتواريخ والكسور العشرية والمجموعات والبايتات وكائنات النموذج يتم تحويلها إلى نصوص من قبل الكاتب. + -الأسماء المخصصة المحجوزة هي `timestamp` و `session_id` و `agent_id` و `type` و `environment`. الأخطاء المطبعية في الحقول الاختيارية يتم قبولها كحقول مخصصة جديدة، لذلك قم بمراجعة JSON المُرسل عندما لا يظهر حقل قياسي في Cloud. +## حقولك الخاصة + +أي كلمة مفتاح إضافية تمررها يتم تخزينها مع الحدث: + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # خاصة بك +) +``` + +فضّل أنواع JSON إذا أردت الاستعلام عنها لاحقاً. أي شيء آخر — UUID أو datetime أو `Decimal` أو set أو bytes أو كائن نموذج — يُخزّن كسلسلة نصية. + + + **اجعل أسماء حقولك بادئة.** الإضافات تُطبق أخيراً، لذا حقل يُسمى `model` أو `tool_name` أو `outcome` يستبدل الحقل الحقيقي بصمت. محولات الإطار تستخدم `fw_`؛ افعل الشيء نفسه ولا شيء قد يصطدم. + + هذا هو أيضاً السبب في أن حقل اختياري خاطئ الإملاء لا يرفع أخطاء أبداً — يصبح حقل مخصص جديد. إذا كان حقل قياسي مفقوداً في السحابة، تحقق من الإملاء أولاً. + + +هذه الأسماء الخمسة مreserved وترفع مباشرة: `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 @@ -189,10 +204,14 @@ failproofai.configure( -إذا كانت Cloud فارغة، فافحص `$FAILPROOFAI_HOME/custom-agents/events`، وإلا `~/.failproofai/custom-agents/events`. ملفات JSONL تثبت انبعاث SDK؛ يشير spool متزايد إلى تكوين daemon أو تسليم، بينما يشير spool فارغ إلى تتبع أو عمر العملية. +إذا كانت السحابة فارغة، افحص `$FAILPROOFAI_HOME/custom-agents/events`، وإلا `~/.failproofai/custom-agents/events`. ملفات JSONL تثبت إطلاق SDK؛ spool متنامٍ يشير إلى تكوين الخادم أو التسليم، بينما spool فارغ يشير إلى الأداة أو عمر العملية. + + + افحص spool فقط عندما يكون الخادم متوقفاً. بينما يعمل، يجمع ويحذف كل دفعة في ميلي ثانية، لذا قائمة دليل تتسابق مع المجمّع وتظهر أحداثاً أقل بكثير مما تم إطلاقه. + ## منع الأخطاء في وقت تشغيل مخصص -استخدم النتائج المدققة والآثار المرتبطة لتحديد الإجراء غير الآمن والأدلة المطلوبة والاستجابة المقصودة. يجب أن يكشف تكامل الإنفاذ المخصص الإجراء قبل التنفيذ، وتمرير مدخلاته المنظمة إلى محرك السياسة، وتطبيق قرار allow أو instruct أو deny الناتج. +استخدم نتائج التدقيق والتتبعات المرتبطة لتحديد الإجراء غير الآمن والأدلة المطلوبة والاستجابة المقصودة. يجب على التكامل الإنفاذ المخصص أن يعرّض الإجراء قبل التنفيذ ويمرّ إدخاله المهيكل إلى محرك السياسة ويطبّق قرار allow أو instruct أو deny الناتج. -أرسل بريدًا إلى [support@befailproof.ai](mailto:support@befailproof.ai) لتصميم والتحقق من هذا التكامل لوقت التشغيل الخاص بك. \ No newline at end of file +[اتصل بـ Failproof AI](mailto:support@befailproof.ai) وسنساعدك في ربط حدود النموذج والأداة ودورة حياة وقت التشغيل بـ policy hooks، ثم التحقق من التكامل معك. \ No newline at end of file diff --git a/docs/ar/reference/events-and-configuration.mdx b/docs/ar/reference/events-and-configuration.mdx index 2a6e0c29e..2ed5c272f 100644 --- a/docs/ar/reference/events-and-configuration.mdx +++ b/docs/ar/reference/events-and-configuration.mdx @@ -1,41 +1,41 @@ --- title: "الأحداث والتكوين" -description: "مرجعية نموذج الحدث والبيئات والتخزين المحلي وحدود التكوين." +description: "مرجعية نموذج الأحداث والبيئات والتخزين المحلي وحدود التكوين." icon: "list-tree" --- ## عائلات الأحداث -- بدء الوكيل وإنهاؤه والإيقاف المؤقت واستئناف التشغيل -- طلب النموذج والاستجابة +- بدء الوكيل وإنهاؤه وإيقافه مؤقتًا واستئنافه +- طلب واستجابة النموذج - استخدام الأداة والنتيجة -- تشغيل الخطاف واكتماله +- تفعيل Hook واكتماله - انتظار الإنسان والإدخال والإيقاف المؤقت والمقاطعة - الأخطاء الصريحة -كل حدث يحمل طابع زمني ومعرّف جلسة ومعرّف وكيل ونوع حدث وبيئة. تحتوي الحقول الخاصة بالحدث على بيانات النموذج والأداة والارتباط والنتيجة والمحتوى والمدة أو الخطأ. +يحمل كل حدث طابع زمني ومعرّف الجلسة ومعرّف الوكيل ونوع الحدث والبيئة. تحتوي الحقول الخاصة بالحدث على بيانات النموذج أو الأداة أو الارتباط أو النتيجة أو المحتوى أو المدة أو الخطأ. ## فحص عقد الحدث - + 1. افتح **Observe → Events**. 2. عيّن نافذة زمنية قصيرة وقم بالتصفية حسب البيئة والوكيل ونوع الحدث. - 3. حدد حدثًا لفحص حقوله المعايرة والحمولة الأولية، ثم افتح جلسته لرؤية سياق التنفيذ. - 4. إذا كانت المدة المقترنة مفقودة، تحقق من أن أحداث البداية والاكتمال تستخدم نفس معرّف الارتباط. + 3. حدد حدثًا لفحص حقوله المعيارية والحمل الأولي، ثم افتح جلسته لرؤية سياق التنفيذ. + 4. إذا كانت المدة المرتبطة مفقودة، تحقق من أن أحداث البدء والاكتمال تستخدم نفس معرّف الارتباط. - استخدم تدفق الأحداث لتضييق البيانات إلى تشغيل وكيل واحد وفحص حقول الحدث المعايرة. + استخدم مجرى الأحداث لتضييق البيانات على تشغيل وكيل واحد وفحص حقول الأحداث المعيارية. - ![تدفق الأحداث المباشر مع عوامل تصفية للبيئة والوكيل والجلسة ونوع الحدث.](/images/dashboard/events-stream.png) + ![مجرى الأحداث المباشر مع مرشحات للبيئة والوكيل والجلسة ونوع الحدث.](/images/dashboard/events-stream.png) - ثم اتبع الحدث إلى جلسته. يُظهر التتبع ما حدث مباشرة قبله وبعده، وهو ضروري عندما تكون الحمولة وحدها غامضة. + ثم اتبع الحدث إلى جلسته. يوضح التتبع ما حدث قبل الحدث وبعده مباشرة، وهذا ضروري عندما يكون الحمل الأولي غامضًا بمفرده. ![تتبع الجلسة المرتبط المستخدم لفحص الحدث في سياق التنفيذ.](/images/dashboard/session-detail.png) - قارن معرّفات الارتباط والطوابع الزمنية عبر كلا العرضين عندما يكون حدث مقترن أو مدة مفقودة. + قارن معرّفات الارتباط والطوابع الزمنية عبر كلا العرضين عندما يكون الحدث أو المدة المقترنة مفقودة. - اكتشف قيم التصفية الصالحة، ثم احصل على حمولات الأحداث الكاملة لجلسة واحدة: + اكتشف قيم المرشح الصحيحة، ثم احصل على حمولات الأحداث الكاملة لجلسة واحدة: ```bash fp list event_types @@ -47,32 +47,32 @@ icon: "list-tree" --full ``` - استخدم `fp --json events ... --fields ts,event_type,session_id,payload` للفحص الذي يمكن قراءته بواسطة الآلات. + استخدم `fp --json events ... --fields ts,event_type,session_id,payload` للفحص القابل للقراءة الآلية. ## حقول SDK المحجوزة -لا تستخدم `timestamp` أو `session_id` أو `agent_id` أو `type` أو `environment` كحقول Python SDK مخصصة. يتم حساب مدات الأحداث المقترنة مثل مدة نتيجة الأداة بواسطة SDK ولا يمكن توفيرها يدويًا. +لا تستخدم `timestamp` أو `session_id` أو `agent_id` أو `type` أو `environment` كحقول Python SDK مخصصة. يتم حساب مدد الأحداث المرتبطة مثل مدة نتيجة الأداة من قبل SDK ولا يمكن توفيرها يدويًا. ## الحدود المحلية -- يعيش Failproof AI تحت `~/.failproofai` ما لم يتم تكوينها بشكل صريح بخلاف ذلك. -- يستخدم `failproofai-sdk` `AGENTEYE_HOME` لتجاوز دليل البداية الخاص به القديم. -- يمكن تعيين تسميات البيئة من خلال تكوين SDK أو `AGENTEYE_ENVIRONMENT`. -- يتم تخزين بيانات اعتماد الخادم بشكل منفصل عن الإعدادات غير السرية. +- تعيش حالة Failproof AI تحت `~/.failproofai` ما لم يتم تكوينها بشكل صريح بخلاف ذلك. +- يقوم `failproofai-sdk` دائمًا بإعادة التوجيه تحت `~/.failproofai/custom-agents`. ينقل `FAILPROOFAI_HOME` هذا المنزل؛ يتم إلحاق مقطع `custom-agents` دائمًا، وبالتالي لا يمكن وضع التوجيه خارجه. فقط `configure(base_dir=...)` الخاص بـ SDK يكتب في مكان آخر. يتم قراءة `AGENTEYE_HOME` من قبل `agenteye-collector` الأقدم لاختيار ما يجب مراقبته، وليس له تأثير بعد الآن على مكان كتابة SDK. +- يمكن تعيين علامات البيئة من خلال تكوين SDK أو `AGENTEYE_ENVIRONMENT`. +- يتم تخزين بيانات اعتماد Daemon بشكل منفصل عن الإعدادات غير السرية. -استخدم أسماء بيئة مستقرة وقليلة الأساسية. الفواصل المنقوطة غير مدعومة في تسميات بيئة خادم Failproof AI. +استخدم أسماء بيئات مستقرة منخفضة الأساسية. لا يتم دعم الفواصل في علامات بيئة daemon. -## تغيير تسمية البيئة +## تغيير علامة البيئة - - يتم تعيين تسميات البيئة بواسطة SDK الباعث أو خادم Failproof AI. بعد تغيير أحدها، افتح **Observe → Sessions** واستخدم عامل تصفية البيئة للتأكد من أن الجلسات الجديدة تحمل القيمة الجديدة. تحتفظ الجلسات الموجودة بالبيئة الأصلية. + + يتم تعيين علامات البيئة من قبل SDK الذي ينبعث منه أو من Failproof daemon. بعد تغيير واحد، افتح **Observe → Sessions** واستخدم مرشح البيئة للتأكد من أن الجلسات الجديدة تحمل القيمة الجديدة. تحتفظ الجلسات الموجودة ببيئتها الأصلية. - بالنسبة إلى `failproofai-sdk`، قم بتكوين البيئة في الكود أو باستخدام متغير البيئة القديم الخاص به. أعد تشغيل تكوين الخادم عند تغيير الإعدادات على مستوى الجهاز. + بالنسبة إلى `failproofai-sdk`، قم بتكوين البيئة في الكود أو باستخدام متغير البيئة الخاص به. أعد تشغيل تكوين daemon عند تغيير الإعدادات على مستوى الجهاز. ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/ar/reference/harnesses.mdx b/docs/ar/reference/harnesses.mdx index 2b54b50c2..d2ad35c84 100644 --- a/docs/ar/reference/harnesses.mdx +++ b/docs/ar/reference/harnesses.mdx @@ -1,72 +1,72 @@ --- --- -title: "خوادم الوكيل" -description: "التقط الجلسات وفرض السياسات عبر 12 خادم وكيل مدعوم." +title: "أدوات تشغيل الوكلاء" +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 | المستخدم والمشروع والمحلي | +| Codex و GitHub Copilot CLI و Cursor و OpenCode و Pi | المستخدم والمشروع | +| Factory Droid و Devin CLI و Antigravity CLI و Goose | المستخدم والمشروع | +| Hermes و OpenClaw | المستخدم | -تقوم كل عملية دمج بتطبيع أسماء أحداث الخطاف الأصلية وأسماء الأدوات وحقول إدخال الأدوات قبل تطبيق السياسات. لا يمكن لأي سياسة التصرف إلا على الأحداث التي يكشفها الخادم؛ اختبر السلوك في نهاية الدور والتعليمات على الخادم والإصدار بالضبط الذي تنشره. +يقوم كل تكامل بتطبيع أسماء أحداث الخطاف الأصلية وأسماء الأدوات وحقول إدخال الأدوات قبل تشغيل السياسات. يمكن للسياسة التصرف فقط على الأحداث التي تكشفها أداة التشغيل؛ اختبر السلوك في نهاية الدور والتعليمات على أداة التشغيل والإصدار المحددة بالضبط التي تنشرها. -## قدرة الإنفاذ +## القدرة على الإنفاذ -"البلوك" يعني أن الحكم المرتجع من المحول الحالي يتم استهلاكه بواسطة الخادم المسمى. قد يستبدل الحجب بعد الأداة النتيجة المعروضة للنموذج ولكن لا يمكنه الرجوع في تأثير جانبي للأداة حدث بالفعل. +"حجب" يعني أن الحكم المُعاد من محول التكيف الحالي يتم استهلاكه بواسطة أداة التشغيل المسماة. قد يحل الحجب بعد الأداة محل النتيجة المعروضة على النموذج لكنه لا يمكنه التراجع عن تأثير جانبي للأداة حدث بالفعل. -| الخادم | أحداث الحجب المتحقق منها | تحذيرات الملاحظة فقط أو عدم الحجب | +| أداة التشغيل | أحداث الحجب المتحقق منها | تحذيرات الملاحظة فقط أو عدم الحجب | | --- | --- | --- | -| 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) - ثبت الخطافات لكل خادم مكتشف: + تثبيت الخطافات لكل أداة تشغيل تم اكتشافها: ```bash failproofai config \ @@ -75,7 +75,7 @@ icon: "plug-zap" failproofai policies --install ``` - أو استهدف خوادم بأسماء ونطاق إعدادات: + أو استهدف أدوات تشغيل مسماة ونطاق إعدادات: ```bash failproofai policies --install \ @@ -83,7 +83,7 @@ icon: "plug-zap" --scope user ``` - يحتفظ نطاق المشروع بتكوين الخطاف مع مستودع. يغطي النطاق ذو المستخدم العمل عبر المستودعات. Claude Code يدعم أيضاً النطاق المحلي؛ يختلف الدعم حسب الخادم ويرفض CLI المجموعات غير المدعومة. + يحتفظ نطاق المشروع بتكوين الخطاف مع مستودع. يغطي نطاق المستخدم العمل عبر المستودعات. Claude Code يدعم أيضًا نطاق محلي؛ يختلف الدعم حسب أداة التشغيل و CLI يرفض المجموعات غير المدعومة. تحقق من الجهاز وأحداثه: @@ -95,16 +95,16 @@ icon: "plug-zap" -## أضف مسار جلسة غير افتراضي +## إضافة مسار جلسة غير افتراضي - يتم تسجيل المسارات الإضافية على الجهاز، وليس في السحابة. بعد إضافة واحد، افتح **مراقبة → الجلسات**، وصفّي بيئة الجهاز، وأكد ظهور الجلسات من المسار الجديد. افتح جلسة وتحقق من الوكيل والخادم وطوابع زمن الحدث قبل الاعتماد عليها في تدقيق. + يتم تسجيل المسارات الإضافية على الجهاز وليس في السحابة. بعد إضافة واحد، افتح **ملاحظة → الجلسات**، صفي حسب بيئة الجهاز، وأكد أن الجلسات من المسار الجديد تظهر. افتح جلسة وتحقق من الوكيل ويتم أداة التشغيل وطوابع زمن الأحداث قبل الاعتماد عليها في التدقيق. - ![قائمة الجلسات المصفاة إلى البيئة التي تتلقى البيانات من مسار التقاط إضافي.](/images/dashboard/sessions-list.png) + ![قائمة الجلسات مصفاة إلى البيئة التي تستقبل البيانات من مسار الالتقاط الإضافي.](/images/dashboard/sessions-list.png) - أضف مساراً مع تسمية اختيارية، ثم فتش المسارات المكونة: + أضف مسارًا بعلامة اختيارية ثم افحص المسارات المكونة: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -113,10 +113,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 ecefd2f6a..aa9b5f2ab 100644 --- a/docs/ar/reference/overview.mdx +++ b/docs/ar/reference/overview.mdx @@ -1,61 +1,65 @@ --- +--- title: "التكاملات والمراجع" -description: "قم بتوصيل أجهزة التشغيل المدعومة والمكتبات البرمجية وواجهات سطر الأوامر وواجهة HTTP API." +description: "توصيل أجهزة عمل الوكلاء المدعومة و SDK و CLI و HTTP API." icon: "braces" --- اختر التكامل الأقرب إلى المكان الذي يعمل فيه وكيلك بالفعل. - - قم بتثبيت الخطافات لأجهزة التشغيل المدعومة لوكلاء الترميز والوكلاء المستقلين. + + ثبّت الخطافات لأدوات سطر أوامر وكلاء الترميز والوكلاء المستقلين المدعومة. + + + أداة LangGraph و CrewAI و LlamaIndex و Pydantic AI أو وكيل مخصص. - - قم بتتبع الآثار لاكتشاف الأعطال في الوكلاء المخصصة، ثم اتصل بنا لإضافة الوقاية إلى وقت التشغيل الخاص بك. + + التكوين وكتالوج الأحداث وقواعد الارتباط والتسليم. - راجع المشاريع المحلية والجلسات ونشاط السياسة والتدقيق دون اتصال. + راجع المشاريع المحلية والجلسات ونشاط السياسة والتدقيق غير المتصل. - قم بتكوين الالتقاط المحلي والخطافات والسياسات والتدقيق والتسليم وحالة الآلة. + كوّن الالتقاط المحلي والخطافات والسياسات والتدقيق والتسليم وحالة الجهاز. - الاستعلام عن جلسات Cloud وإدارتها والتدقيق والمشاكل والتنبيهات والمفاتيح والمستخدمين والإعدادات. + الاستعلام عن جلسات Cloud والتدقيق والمشاكل والتنبيهات والمفاتيح والمستخدمين والإعدادات والإدارة. - قيّم الجلسات المكتملة أو غير النشطة باستخدام خدمة FastAPI. + تقدير الجلسات المكتملة أو غير النشطة باستخدام خدمة FastAPI. - قم بتأليف واختبار قرارات allow و instruct و deny خاصة بسير العمل. + قم بتأليف واختبار قرارات allow و instruct و deny خاصة بسير عمل محدد. - نشر لوحة التحكم في 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`، وانسخ السر. - 2. قم بتكوين التكامل باستخدام الصفحة المطابقة أعلاه. - 3. افتح **Observe → Events** للتأكد من وصول الأحداث، ثم **Observe → Sessions** للتأكد من تشكيل عمليات تشغيل كاملة. - 4. قم بالتصفية بناءً على بيئة التكامل وتفتيش جلسة واحدة للحصول على نموذج وأداة وخطأ وحقول السياسة التي يحتاجها التدقيق. + 1. افتح **الإدارة → المفاتيح**، أنشئ مفتاحًا باستخدام `events:add` و `policies:pull`، وانسخ السر. + 2. كوّن التكامل باستخدام الصفحة المطابقة أعلاه. + 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، والتحقق من الجلسة الأولى. + أنشئ مفتاح جهاز، وصّل Failproof daemon، والتحقق من الجلسة الأولى. ```bash fp keys create agent-production \ @@ -73,6 +77,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/troubleshooting.mdx b/docs/ar/reference/troubleshooting.mdx index 4c1a710c5..198bcf17b 100644 --- a/docs/ar/reference/troubleshooting.mdx +++ b/docs/ar/reference/troubleshooting.mdx @@ -1,17 +1,16 @@ --- ---- title: "استكشاف الأخطاء" -description: "تشخيص الجلسات المفقودة والسياسات المفقودة وفشل التسليم والإجراءات المحظورة للوكيل." +description: "تشخيص الجلسات المفقودة والسياسات المفقودة والتسليم الفاشل والإجراءات المحجوبة للوكيل." icon: "wrench" --- - + - افتح **الإدارة → المفاتيح** وتأكد من أن مفتاح الجهاز نشط وعليه صلاحية `events:add`. ثم افتح **مراقبة → الأحداث**، وسّع نطاق الوقت، وامسح عوامل التصفية للبيئة والوكيل. إذا كانت هناك أحداث، ابحث عن معرّف الجلسة ثم تحقق من **مراقبة → الجلسات** للتجميع. إذا لم تكن هناك أحداث، قم بتشخيص daemon Failproof من سطر الأوامر. + افتح **Administration → Keys** وتأكد من أن مفتاح الجهاز نشط وله صلاحية `events:add`. ثم افتح **Observe → Events**، وسّع نطاق الوقت، وامسح عوامل تصفية البيئة والوكيل. إذا كانت هناك أحداث، ابحث عن معرّف الجلسة ثم تحقق من **Observe → Sessions** لتجميع البيانات. إذا لم تكن هناك أحداث، قم بتشخيص مستقبِل Failproof من سطر الأوامر. - ![مجرى الأحداث المباشر مع عوامل التصفية الأساسية والأحداث الحديثة للوكيل.](/images/dashboard/events-stream-current.png) + ![تدفق الأحداث المباشر مع عوامل التصفية الأساسية الخاصة به وأحداث الوكيل الأخيرة التي تصل.](/images/dashboard/events-stream-current.png) ```bash @@ -22,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - تأكد من تفعيل الالتقاط والمفتاح المُعد له صلاحية `events:add` وأن عامل التصفية في لوحة التحكم يطابق البيئة المُرسلة. + تأكد من تفعيل الالتقاط، وأن المفتاح المكوَّن له صلاحية `events:add`، وأن عامل تصفية لوحة التحكم يطابق البيئة المُرسلة. - امسح عوامل التصفية في **مراقبة → الأحداث** وابحث عن معرّف جلسة SDK الدقيق. إذا لم يظهر شيء، افحص سبول SDK و daemon Failproof على جهاز المصدر. + امسح عوامل التصفية في **Observe → Events** وابحث عن معرّف جلسة SDK الدقيق. إذا لم يظهر شيء، افحص ملف الطبقة والمستقبِل Failproof على الجهاز المصدر. ```bash @@ -37,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - تأكد من أن عملية الوكيل تضبط `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` وأن `$FAILPROOFAI_HOME/custom-agents` أو `~/.failproofai/custom-agents` موجودة قبل بدء SDK. + تأكد من أن المستقبِل يعمل ومتصل — يقوم SDK بتخزين البيانات سواء كان متصلاً أم لا. لا يلزم أن يكون دليل الطبقة موجوداً مسبقاً (الكاتب ينشئه)، ولا يوجد متغير بيئة يختاره: `$FAILPROOFAI_HOME/custom-agents`، وإلا فهو `~/.failproofai/custom-agents`، هو الجذر الوحيد، و`configure(base_dir=...)` هو التجاوز الوحيد. إذا تم إيقاف العملية قسراً بـ `SIGKILL` أو قتلها بسبب نقص الذاكرة، فقد فُقد كل ما كان مصطفاً — تعامل مع `SIGTERM` لتحديد ذلك. - + - افتح **الإدارة → الإنفاذ**، حدد الجهاز، وقارن إصداراته المعينة والمُبلغ عنها والسابقة. تأكد من أن نطاق النشر يشمل الجهاز وأن مفتاحه له صلاحية `policies:pull`. يمكن أن يعمل الالتقاط حتى عند عدم تسليم السياسة. + افتح **Admin → enforcement**، حدّد الجهاز، وقارن بين إصداراته المخصصة والمُبلغ عنها والسابقة. تأكد من أن نطاق النشر يتضمن الجهاز وأن مفتاحه له صلاحية `policies:pull`. يمكن أن يعمل الاستيعاب حتى عندما لا يعمل تسليم السياسة. @@ -54,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - تأكد من تطابق معرّف الجهاز والعلامة مع هدف لوحة التحكم. أعد الاتصال باستخدام مفتاح قادر على السياسات إذا كان بيان الاعتماد الحالي يمنح الالتقاط فقط. + تأكد من أن معرّف الجهاز والعلامة يطابقان هدف لوحة التحكم. أعد الاتصال باستخدام مفتاح قادر على السياسة إذا كانت بيانات الاعتماد الموجودة تمنح فقط استيعاب الأحداث. - + - افتح **الإدارة → الإنفاذ** وافحص آخر وقت ظهور الجهاز والإصدار المُبلغ عنه. إذا كان الجهاز قديماً، عامله كمشكلة daemon محلية. لا تضعف السياسة المنشورة فقط لتجاوز daemon غير متاح. + افتح **Admin → enforcement** وافحص آخر وقت رآه الجهاز والإصدار المُبلغ عنه. إذا كان الجهاز قديماً، تعامل مع هذا باعتباره مشكلة مستقبِل محلية. لا تُضعّف السياسة المنشورة فقط لتجاوز مستقبِل غير متاح. @@ -72,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - أعد تشغيل أو حدّث `failproofaid`؛ أعد تشغيل التكوين عند اختلاف إصدارات بروتوكول CLI و daemon. مسار daemon المُعد يفشل بشكل مقفول بالتصميم. + أعد تشغيل أو حدّث `failproofaid`؛ أعد تشغيل التكوين عندما تختلف إصدارات بروتوكول CLI والمستقبِل. مسار المستقبِل المُكوَّن يفشل بالتصميم بشكل آمن. - للسياسة المُنشأة في السحابة، افتح **الإدارة → محرر السياسات**، حدد المسودة، واستعرض أخطاء التحقق قبل النشر. للسياسة المحلية، استخدم CLI للتحقق منها، ثم افتح **مراقبة → السياسة** بعد إجراء اختبار لتأكيد وصول القرارات. + بالنسبة إلى السياسة المُنشأة في Cloud، افتح **Admin → policy editor**، حدّد المسودة، واستعرض أخطاء التحقق قبل النشر. بالنسبة إلى السياسة المحلية، استخدم CLI للتحقق منها، ثم افتح **Observe → policy** بعد إجراء اختبار لتأكيد وصول القرارات. - تأكد من أن اسم الملف ينتهي بـ `policies.js` أو `policies.mjs` أو `policies.ts`، وأن الوحدة تستدعي `customPolicies.add(...)`، والـ imports تُحل من ملف السياسة. + تأكد من أن اسم الملف ينتهي بـ `policies.js` أو `policies.mjs` أو `policies.ts`، وأن الوحدة تستدعي `customPolicies.add(...)`، وأن الاستيرادات تُحل من ملف السياسة. ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -92,14 +91,14 @@ icon: "wrench" - + - افتح **تحليل → التدقيقات**، حدد التشغيل، وتحقق مما إذا تم تشغيل تحليل النموذج. ثم قارن نطاقه وإطاره الزمني مع **مراقبة → الجلسات** وافتح آثاراً تمثيلية من تلك المجموعة. + افتح **Analyze → audits**، حدّد المسار، وتحقق مما إذا كان تحليل النموذج قد تم تشغيله. ثم قارن نطاقه والنافذة الزمنية مع **Observe → sessions** وافتح الآثار الممثلة من تلك المجموعة. - النتيجة الصفر ذات معنى فقط عند نجاح التحليل. إذا تم تخطي التحليل أو فشل، ينتج التشغيل بلا نتائج ويُبقي النافذة غير المحللة مفتوحة للتشغيل الناجح المستقبلي. إذا تم تعطيل تحليل النموذج، ينتج التدقيق أيضاً بلا نتائج لأن المسح الحتمي للبيانات الاعتماديّة والشخصية يسجل الإحصائيات فقط لكن لا يرفع بعد الآن النتائج. + النتيجة الصفرية لها معنى فقط عندما يتم تشغيل التحليل بنجاح. إذا تم تخطي التحليل أو فشل، ينتج المسار بدون نتائج ويُبقي النافذة التي لم يتم تحليلها مفتوحة لمسار ناجح في المستقبل. إذا تم تعطيل تحليل النموذج، ينتج التدقيق أيضاً بدون نتائج لأن مسح بيانات الاعتماد والمعلومات الشخصية المحدد يسجل الإحصائيات ولم يعد يرفع نتائج. - ![نموذج التدقيق حيث البيئة والوكيل والتكرار ونافذة الكنس تحدد مجموعة الجلسات.](/images/dashboard/audit-new.png) + ![نموذج التدقيق حيث تحدد البيئة والوكيل والتكرار ونافذة المسح مجموعة الجلسات.](/images/dashboard/audit-new.png) ```bash @@ -111,31 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - إذا بقي التشغيل في طابور الانتظار، انتظر قدرة audit-agent أو اطلب من مشغل النشر فحص أسطول التدقيق. التدقيق في الطابور يُعاد محاولته؛ لا يتم تخطيه فوراً. + إذا بقي المسار في الانتظار، انتظر سعة وكيل التدقيق أو اطلب من مشغّل النشر فحص أسطول التدقيق. يُعيد محاولة التدقيق المصطف؛ لا يتم تخطيه على الفور. - + - افتح جلسة مكتملة وتحقق مما إذا كان التقييم اليدوي ناجحاً. السحابة المستضافة حالياً لا تحتوي على تحكم في نقطة نهاية المُقيّم في لوحة التحكم؛ يجب على مشغل الخادم تكوينها. + افتح جلسة مكتملة وتحقق مما إذا كان التقييم اليدوي ناجحاً. الـ Cloud الموجه حالياً لا يحتوي على تحكم نقطة نهاية المُقيّم في لوحة التحكم؛ يجب على مشغّل الخادم تكوينها. - تحقق من المُقيّم نفسه، ثم افحص حالات التقييم الحديثة: + تحقق من المُقيّم نفسه، ثم افحص حالات التقييم الأخيرة: ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - على السحابة ذاتية الاستضافة، تأكد من وجود `EVALUATOR_ENDPOINT` على الخادم و`EVALUATOR_TOKEN` يطابق المُقيّم. يتم تعطيل التقييم التلقائي عند عدم وجود نقطة النهاية. + على Cloud ذاتي الاستضافة، تأكد من وجود `EVALUATOR_ENDPOINT` على الخادم وتطابق `EVALUATOR_TOKEN` للمُقيّم. يتم تعطيل التقييم التلقائي عندما تكون النقطة النهائية غائبة. - استخدم مبدّل المنظمة وتأكد من الاختصار والصلاحيات المتوقعة قبل مقارنة النتائج مع CLI. + استخدم محول المنظمة وأكد على الاسم المختصر والصلاحيات المتوقعة قبل مقارنة النتائج مع CLI. ```bash @@ -144,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - في وضع مفتاح API، حدد `fp --org --api-key ...` أو اضبط `AGENTEYE_ORG`. حالة منظمة جلسة الإنسان المحفوظة يتم تجاهلها بشكل مقصود لطلبات مفتاح API. + في وضع مفتاح API، حدّد `fp --org --api-key ...` أو اضبط `AGENTEYE_ORG`. حالة منظمة جلسة الإنسان المحفوظة يتم تجاهلها عن قصد لطلبات مفتاح API. - + - افتح **مراقبة → السياسة**، احفظ القرار والجلسة المرتبطة، وحدد حالة الموجب الخاطئ. ثم افتح **الإدارة → الإنفاذ** وأرجع الأجهزة المتضررة إلى الإصدار السابق. أنشئ إصداراً أضيق في **محرر السياسات**، اختبره على نطاق صغير، وتوسع فقط بعد نجاح العمل الصحيح. + افتح **Observe → policy**، احفظ القرار والجلسة المرتبطة، وحدّد شرط الإيجابية الكاذبة. ثم افتح **Admin → enforcement** وأرجع الأجهزة المتأثرة إلى الإصدار السابق. أنشئ نسخة أكثر دقة في **Policy editor**، اختبرها على نطاق صغير، وسّع فقط بعد نجاح العمل الصحيح. - استرجاع نشر السحابة للإصدار السابق هو dashboard فقط. إيقاف جلسة محلية لا يعطل السياسات المُدارة بالسحابة. إذا كانت لوحة التحكم غير متاحة، التقط حالة الجهاز والنشر واستعد وصول لوحة التحكم بدلاً من إعادة محاولة الإجراء المحظور بشكل متكرر. + استرجاع نشر Cloud متاح فقط من لوحة التحكم. إيقاف جلسة محلية لا يعطّل السياسات المُدارة من Cloud. إذا كانت لوحة التحكم غير متاحة، احفظ حالة الجهاز والنشر وأعِد الوصول إلى لوحة التحكم بدلاً من إعادة محاولة الإجراء المحجوب بشكل متكرر. ```bash failproofai config --status @@ -165,4 +164,4 @@ icon: "wrench" -عند الاتصال بالدعم، أرفق إصدار CLI والأداة والبيئة ومعرّف الجلسة أو النشر ذي الصلة ومخرجات `failproofai config --status` مع حذف الأسرار. \ No newline at end of file +عند الاتصال بالدعم، أدرج إصدار CLI والأداة والبيئة ومعرّف الجلسة أو النشر ذي الصلة وناتج `failproofai config --status` مع إزالة الأسرار. \ No newline at end of file diff --git a/docs/ar/sessions/live-events.mdx b/docs/ar/sessions/live-events.mdx index 807f8ea44..28e467d9a 100644 --- a/docs/ar/sessions/live-events.mdx +++ b/docs/ar/sessions/live-events.mdx @@ -1,11 +1,11 @@ --- --- title: "الأحداث المباشرة" -description: "شاهد نشاط الوكيل يصل أثناء تشغيل الجلسة." +description: "راقب نشاط الوكيل وهو يصل أثناء تشغيل الجلسة." icon: "radio" --- -تساعدك الأحداث المباشرة على تأكيد الأداة المساعدة ومراقبة عملية محفوفة بالمخاطر دون انتظار انتهاء الجلسة. +تساعدك الأحداث المباشرة على تأكيد التنسيق ومراقبة التشغيل المحفوف بالمخاطر دون انتظار انتهاء الجلسة. ## مراقبة النشاط @@ -13,10 +13,10 @@ icon: "radio" 1. انتقل إلى **Observe → Events**. 2. ابدأ بنطاق الوقت الحالي وبدون مرشحات لتأكيد وصول البيانات. - 3. صفّي حسب البيئة أو نوع الحدث أو الوكيل أو الجلسة. استخدم البحث لنص الحمولة. - 4. اختر حدثاً لفحص ملخصه والتفاصيل. اتبع رابط الجلسة للحصول على التتبع الكامل. + 3. قم بتصفية حسب البيئة أو نوع الحدث أو الوكيل أو الجلسة. استخدم البحث لنصوص الحمول. + 4. حدد حدثاً لفحص ملخصه والتفاصيل. اتبع رابط الجلسة للحصول على التتبع الكامل. - ![تيار الأحداث المباشر يعرض حركة المرور من بوابة محادثة Hermes إلى جانب عمليات تشغيل الترميز عبر سطر الأوامر، مفصولة حسب الوقت والبيئة ونوع الحدث والوكيل والنموذج والسياق والجلسة.](/images/dashboard/events-stream-current.png) + ![دفق الأحداث المباشرة يعرض حركة المرور من بوابة دردشة Hermes إلى جانب تشغيلات coding-CLI، مصفاة حسب الوقت والبيئة ونوع الحدث والوكيل والنموذج والسياق والجلسة.](/images/dashboard/events-stream-current.png) ```bash @@ -25,22 +25,22 @@ icon: "radio" fp --json events --full --session-id --all ``` - يحذف العرض الافتراضي الحمولات الخام. استخدم `--full` فقط للتحقيق في جلسة محدودة. + يتجاهل الخلاصة الافتراضية الحمول الخام. استخدم `--full` فقط للتحقيق في جلسة محدودة. -استخدم تيار الأحداث للإجابة على ثلاثة أسئلة فورية: +استخدم دفق الأحداث للإجابة على ثلاثة أسئلة فورية: -- هل الوكيل المتوقع يبلّغ عن البيئة الصحيحة؟ -- هل تصل استدعاءات النموذج واستدعاءات الأداة وقرارات السياسة بالترتيب الصحيح؟ -- هل توقفت الجلسة عن إحراز تقدم أم بدأت في تكرار إجراء ما؟ +- هل يقدم الوكيل المتوقع التقارير إلى البيئة الصحيحة؟ +- هل وصلت استدعاءات النموذج واستدعاءات الأداة وقرارات السياسة بالترتيب؟ +- هل توقفت الجلسة عن إحراز تقدم أم بدأت تكرار إجراء؟ -تتضمن أنواع الأحداث أحداث دورة حياة الوكيل وطلبات واستجابات النموذج واستخدام الأداة والنتائج وتنفيذ الخطاف والانتظارات البشرية والمقاطعات والأخطاء الصريحة. تجمع معرّفات الارتباط بين الأحداث المقترنة مثل استدعاء الأداة ونتيجتها. +تشمل أنواع الأحداث أحداث دورة حياة الوكيل وطلبات واستجابات النموذج واستخدام الأداة والنتائج وتنفيذ الخطاف والانتظار البشري والمقاطعات والأخطاء الصريحة. تربط معرفات الارتباط الأحداث المقترنة مثل استدعاء الأداة ونتيجتها. - احتفظ بالعرض المباشر واسعاً أثناء التحقق من تكامل جديد. أضف مرشحات فقط بعد رؤية الحدث الأول؛ يمكن لمرشح غير صحيح أن يبدو وكأنه فشل في الاستقبال. + حافظ على العرض المباشر واسعاً أثناء التحقق من تكامل جديد. أضف المرشحات فقط بعد رؤية الحدث الأول؛ يمكن أن يبدو المرشح غير الصحيح وكأنه فشل في البث. -إذا لم تظهر أحداث، قم بتشغيل `failproofai config --status`، ثم [استكشف أخطاء الاستقبال](/ar/reference/troubleshooting). +إذا لم تظهر أي أحداث، قم بتشغيل `failproofai config --status`، ثم [استكشف أخطاء البث](/ar/reference/troubleshooting). -الوكلاء الذين لا يعملون في أحد الـ 12 [الأطر العمل](/ar/reference/harnesses) المدعومة يبلّغون عن نفس أنواع الأحداث من خلال [Python SDK](/ar/reference/custom-agents)، بما في ذلك أحداث التفاعل البشري (`human_wait` و `human_input` و `human_interrupt`) التي تعتمد عليها وكلاء البوابة والإنتاج. \ No newline at end of file +الوكلاء الذين لا يعملون في أحد [الأطر](/ar/reference/harnesses) الـ 12 المدعومة يقدمون نفس أنواع الأحداث من خلال [Python SDK](/ar/reference/custom-agents)، بما في ذلك أحداث التفاعل البشري (`human_wait`، `human_input`، `human_interrupt`) التي تعتمد عليها الوكلاء الموجودون في البوابة والإنتاج. \ No newline at end of file diff --git a/docs/ar/start/first-policy.mdx b/docs/ar/start/first-policy.mdx index 867e24d60..b3eb9bca4 100644 --- a/docs/ar/start/first-policy.mdx +++ b/docs/ar/start/first-policy.mdx @@ -1,34 +1,34 @@ --- --- title: "منع فشلك الأول باستخدام سياسة" -description: "أنشئ نسخة سياسة، ونشرها في وضع المراقبة، ثم فعّلها." +description: "قم بتأليف نسخة من السياسة، ونشرها في وضع المراقبة، ثم فرضها." icon: "shield-check" --- استخدم السياسة فقط بعد أن تتمكن من وصف الإجراء غير الآمن والإجراءات المشروعة التي يجب أن تبقى مسموحة. - + - - انتقل إلى **المسؤول → محرر السياسة**. ابدأ بسياسة العرض التوضيحي، واستعرض أو عدّل مصدرها، ثم اختر **نشر النسخة**. يُنشئ النشر النسخة الثابتة التي يمكنك نشرها على الأجهزة. + + انتقل إلى **Admin → policy editor**. ابدأ بسياسة العرض التوضيحي، وراجع أو عدّل المصدر الخاص بها، ثم حدد **publish version**. ينشئ النشر النسخة غير القابلة للتغيير التي يمكنك نشرها على الأجهزة. - ![عرض محرر السياسة مع سياسة العرض التوضيحي جاهزة للنشر كنسخة ثابتة.](/images/dashboard/policy-editor.png) + ![عرض محرر السياسة مع سياسة عرض توضيحي جاهزة للنشر كنسخة غير قابلة للتغيير.](/images/dashboard/policy-editor.png) - انتقل إلى **المسؤول → الإنفاذ**، وقم بتوسيع الجهاز المستهدف، واختر **تعديل هذا الجهاز**. أضف سياسة العرض التوضيحي المنشورة، وثبّت نسختها، واختر **مراقبة**، ثم طبّق النشر. + انتقل إلى **Admin → enforcement**، وقم بتوسيع الجهاز المستهدف، وحدد **edit this machine**. أضف سياسة العرض التوضيحي المنشورة، وثبّت نسختها، واختر **observe**، ثم طبّق النشر. ![محرر نشر الجهاز مع نسخة سياسة منشورة محددة في وضع المراقبة قبل تطبيق النشر.](/images/dashboard/enforcement-editor.png) - - قم بتشغيل جلسة وكيل جديدة على هذا الجهاز، ثم افتح **المراقبة → السياسة**. حدد الجهاز وأكّد أن سياسة العرض التوضيحي تظهر في تعيين السياسة وجدول القرارات. يسجّل وضع المراقبة ما ستفعله السياسة دون حجب الإجراء. + + قم بتشغيل جلسة وكيل جديدة على هذا الجهاز، ثم افتح **Observe → policy**. حدد الجهاز وتأكد من ظهور سياسة العرض التوضيحي في تعيين السياسة وجدول أحداث القرار. يسجل وضع المراقبة ما ستفعله السياسة دون حجب الإجراء. - ![صفحة السياسة تعرض إجمالي القرارات ونشاط الإنفاذ بمرور الوقت وتعيينات السياسات المحلية والمُدارة من السحابة.](/images/dashboard/policy-observe.png) + ![صفحة السياسة التي تعرض إجمالي القرارات وأنشطة الفرض بمرور الوقت وتعيينات السياسات المحلية والمدارة من السحابة.](/images/dashboard/policy-observe.png) - - تأليف السياسة السحابية ونشر الأسطول هما سير عمل إدارية. استخدم واجهة سطر الأوامر المحلية للتحقق من صحة نفس السياسة قبل نشرها: + + تأليف سياسات السحابة ونشر الأسطول هي سير عمل إدارية. استخدم واجهة سطر الأوامر المحلية للتحقق من نفس السياسة قبل نشرها: ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -36,13 +36,13 @@ icon: "shield-check" failproofai config --status ``` - استخدم `fp` للتفتيش عن قرارات السياسة المرئية للسحابة: + استخدم `fp` للتحقق من قرارات السياسة المرئية من السحابة: ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - لا تكشف واجهة سطر أوامر السحابة عن مسارات نشر الإنفاذ التي يقتصر الوصول إليها على المسؤول. انشر النسخ من **المسؤول → محرر السياسة** وانشرها من **المسؤول → الإنفاذ**. + كلتا الخطوتين متاحتان أيضًا من واجهة سطر الأوامر: `fp policies publish ` تنشئ نسخة و `fp fleet deploy --add ` توضعها على جهاز. المعادلات على لوحة التحكم هي **Admin → policy editor** و **Admin → enforcement**. \ No newline at end of file diff --git a/docs/ar/start/integrations.mdx b/docs/ar/start/integrations.mdx new file mode 100644 index 000000000..b789e01c5 --- /dev/null +++ b/docs/ar/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "الاستخدام الكامل لعاملك" +sidebarTitle: "الأطر" +description: "قم بتوصيل أي إطار عمل مدعوم للعامل مع Failproof AI باستدعاء واحد." +icon: "plug" +--- + +عاملك ينتج بالفعل كل ما يستحق التسجيل — استدعاءات النموذج، استدعاءات الأدوات، حدود العقد، انتظارات العاملين، الأخطاء. الإطار يتخلص منها. SDK يحتفظ بها. + + + + عامل كتبته بنفسك، أو واحد غير مدرج هنا. + + + الرسوم البيانية، العقد، الأدوات، أدوات المسترجعات، النماذج. + + + الطواقم، التدفقات، العوامل حسب الدور، الأدوات. + + + سير العمل، الخطوات، عوامل الدوال، أدوات المسترجعات. + + + عوامل مكتوبة، القدرات، الأدوات، المحاولات الجديدة. + + + +## ثلاثة أسطر، أي إطار عمل كان + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # detects the frameworks you imported + +with failproofai_sdk.session(): + ... # your existing agent call, unchanged +``` + +لا توجد مزخرفات على وظائفك، لا رد نداء يتم تمريره لاستدعاءاتك، لا معرفات يتم خيطها عبر الكود. فقط الاستدعاء داخل الجلسة يختلف: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # under `async with failproofai_sdk.session():` + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +التثبيت الإضافي يثبت **الإطار**. كل محول يأتي في عجلة النقل الأساسية، لذلك المشروع الذي يمتلك بالفعل إطار العمل لا يحتاج إلى أي شيء إضافي على الإطلاق. + +## تحقق من وصوله + +قم بتشغيل جلسة واحدة مزودة بالأدوات، ثم افتح **Observe → Sessions** وحدد بيئتك. يظهر التشغيل كتتبع معاد الإنشاء. + +إذا لم يصل شيء، تأكد من اتصال الجهاز باستخدام `failproofai config --status`. انظر [إعداد المراقبة](/ar/start/setup). + + + لا تتحقق من دليل الاسطوانة لتأكيد التسليم. يجمع مجند Failproof كل دفعة ويحذفها في غضون ميلي ثانية، لذا يسبق القارئ الجامع ويظهر أحداثًا أقل بكثير من تلك المنبعثة. + + +## التالي + +كل سريع بدء أعلاه يرتبط بدليله الكامل — ما يتم تسجيله، والخيارات، والبث، وتسمية النطاق، والمشاكل التي يواجهها الناس بالفعل. يعيشون تحت **Trace Agents → Plug in your agent**. + + + + نموذج البيانات، المعرفات، أنواع الأحداث، وكيف تصل الأحداث إلى السحابة. + + + اتبع السببية عبر جلسة بدلاً من السجلات المنفصلة. + + + قم بمراجعة الجلسات التي التقطتها للتو. + + \ No newline at end of file diff --git a/docs/ar/start/integrations/crewai.mdx b/docs/ar/start/integrations/crewai.mdx new file mode 100644 index 000000000..16861f7bf --- /dev/null +++ b/docs/ar/start/integrations/crewai.mdx @@ -0,0 +1,225 @@ +--- +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "تجهيز الفرق والتدفقات والوكلاء حسب الدور والأدوات والذاكرة وردود الفعل البشرية." +icon: "/images/frameworks/crewai.svg" +--- + +## التثبيت + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +الإصدارات المدعومة: `crewai` من 1.13 إلى 2.0. الإصدار 1.13 هو الذي أضاف `started_event_id` وعادّ استخدام الرموز، وكلاهما يعتمد عليه المحول لربط الأحداث والإبلاغ عن الرموز. + +## التجهيز + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +يسجل `instrument()` مستمعًا على ناقل الأحداث على مستوى الوحدة في CrewAI ويشترك في معالج واحد لكل فئة حدث. لا يتغير شيء حول فريقك أو الوكلاء أو المهام أو الأدوات. + +## ما يتم تسجيله + +| CrewAI | حدث Failproof | +| --- | --- | +| بدء Crew | `agent_start`, `agent_end` | +| `Agent.kickoff()` (وكيل خفيف بدون فريق) | `agent_start`, `agent_end`، مع `agent_id` من الدور | +| بدء وإنهاء التدفق | `agent_start`, `agent_end`؛ يتم تداخل فريق تم بدؤه داخل طريقة التدفق تحته | +| تنفيذ الوكيل | `agent_start`, `agent_end` متداخل، مع `agent_id` من الدور. تحت عملية هرمية يتم تداخل الزميل المفوّض تحت المدير وليس بجانبه | +| المهمة | لا شيء؛ يتم تسجيله كرابط بحيث تنحل الأطفال للفريق | +| طريقة التدفق والحماية | `hook_triggered`, `hook_completed` | +| استخدام الأداة | `tool_use`, `tool_result` | +| عمليات الذاكرة والمعرفة | `tool_use`, `tool_result`، مسمى للسطح المصاب | +| استدعاء LLM | `model_request`, `model_response`، مع استخدام الرموز | +| جزء البث | مدمج في الاستجابة كعدد الأجزاء والوقت للرمز الأول | +| طلب ردود فعل بشرية | `human_wait`, `agent_pause` | +| استقبال ردود فعل بشرية | `agent_resume`, `human_input` | +| خطأ تنفيذ الوكيل | `error`، ثم `agent_end` مع نتيجة `failed` | + +المهمة لا تصدر شيئًا بقصد. مهمة CrewAI هي مجموعة فرعية من تنفيذ الوكيل الذي يشغلها، لذا فإن إصدار كليهما سيضاعف كل صف ويجعلها تبدو كأخوات. بدلاً من ذلك، يتم نقل معرف المهمة واسمها على أحداث الوكيل نفسه. + +يتم تسجيل عمليات الذاكرة والمعرفة كأدوات، مسماة للسطح الذي يصيبونه، بحيث تظهر بجانب أدواتك الحقيقية حيث يمكنك مقارنة زمن استجابتها. + +في الفريق الهرمي، التداخل هو الذي يجعل التتبع قابلاً للقراءة: + +```text +crew +└─ manager + ├─ researcher delegated + └─ writer delegated +``` + +يربط CrewAI التنفيذ المفوّض على حدث أداة **`delegate_work_to_coworker`** وليس على المدير مباشرة، لذا يتبع المحول هذا الرابط. بدونه، كل وكيل يخرج كأخ لكل وكيل آخر وتضيع هيكل التفويض. + +## مثال + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # becomes agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +المرحلة الانتقالية مرئية في التتبع: يغلق امتداد `analyst`، ويفتح امتداد `writer`، وكلاهما يقع داخل امتداد `crew` واحد. + +## قم بتسمية امتدادات الشبكة الخاصة بك + +يأتي `agent_id` من `Agent(role=...)`، وهذا هو ما يجعله وجهة نظر لوحة معلومات قابلة للقراءة. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # one facet entry per run +``` + +`agent_id` هي عمود منخفض الأساسية. الدور الذي يحتوي على معرف التشغيل أو الطابع الزمني يقلل منه لكل استعلام يشغله أي شخص. إذا بدا الدور كمعرف، فإن المحول يرفضه ويضع القيمة الحقيقية في حقل الحمولة بدلاً من ذلك. + +## التحكم في الجلسة + +تم حلها بهذا الترتيب، أول تطابق يفوز: + +1. `instrument("crewai", session_id=...)` +2. نطاق `failproofai_sdk.session()` المغلف +3. معرف `uuid4().hex` تم إنشاؤه، مرة واحدة لكل فريق أو تدفق + +لف البدء للتحكم فيه لكل تشغيل: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## الخيارات + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # pin every run to one session id +) +``` + +`session_id` هو الخيار الوحيد الذي يقرأه هذا المحول. يتم تسجيل الطلبات والإكمالات دائمًا، مع القطع إلى ميزانية الحمولة. + +## البشر في الحلقة + +يحتوي CrewAI على **سطحين** من أسطح البشر في الحلقة، وكلاهما يتم تسجيله نفس الأحداث الأربعة. + +يمر `@human_feedback` على طريقة التدفق عبر ناقل أحداث CrewAI: يصدر وقت التشغيل حدثًا قبل انسداده على شخص وآخر بعد الإجابة. + +لا يفعل `Task(human_input=True)`. يستدعي `input()` داخل مزود الإدخال الخاص بـ CrewAI ولا يصدر أي حدث من أي نوع، لذا يلف المحول مزود الإدخال هذا مباشرة — بدونه كانت انتظار الإنسان بأكمله غير مرئي وتم محاسبته كوقت وكيل نشط. + +بأي طريقة تحصل على: + +```text +human_wait the prompt and its options +agent_pause starts the paused-time clock +agent_resume stops it +human_input the answer, with the wait measured +``` + +`agent_pause` إلى `agent_resume` هو الزوج الوحيد الذي يطعم الوقت المتوقف. بدونه، ينتظر الإنسان لمدة عشر دقائق يتم محاسبته كعشر دقائق من وقت الوكيل النشط. + + + لا يقوم CrewAI بتعيين معرف ارتباط على حدث ردود الفعل البشرية، لذا يقرن المحول بينهما على اسم التدفق والطريقة، مع العودة إلى آخر توقف تم فتحه. هذا صحيح لأن موجه وحدة التحكم ينسد. إذا قمت ببناء مزود ردود فعل متزامن، فقم بتعيين `request_id` على كلا الحدثين. + + + + نظرًا لأن مسار `Task(human_input=True)` هو غلاف حول مزود إدخال CrewAI بدلاً من اشتراك في الأحداث، يتم استعادته على `uninstrument()` وإعادة رفع ما يرفعه `input()`، بما في ذلك `KeyboardInterrupt` بدون تغيير. + + +## المشاكل الشائعة + + + + يحتوي `role` على معرف UUID أو طابع زمني أو لاحقة لكل تشغيل. استخدم دورًا بشريًا مستقرًا وضع معرف التشغيل المحدد في وصف المهمة بدلاً من ذلك. + + + + ناقل الأحداث غير متزامن، و `kickoff()` يعود قبل تشغيل آخر المعالجات. استنزف أولاً: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + هذه خاصية CrewAI وليست خاصية SDK. + + + + يفرض `agent_end` إغلاق التوقفات المفتوحة ولكن ليس الأدوات أو النماذج، لذا فإن التشغيل الذي يموت داخل استدعاء أداة يترك هذا الامتداد مفتوحًا. يغلق الهدم الطبيعي أي شيء لا يزال مفتوحًا ويضع علامة عليه كناقص. فقط `SIGKILL` يتركها معلقة، لأنه لا يمكن لأحد أن يركض. + + + + تحقق بهذا الترتيب: `instrument()` يركض قبل `kickoff()`؛ هناك `with failproofai_sdk.session():` حوله؛ `crewai` هو 1.13 أو أحدث؛ تم تعيين `FAILPROOFAI_SDK_STRICT=1`، بحيث يرفع Hook المتدهور بدلاً من الابتلاع. + + + +## التالي + + + + الأزواج والمعرفات ودورة حياة الجلسة والتسليم. + + + اتبع السببية عبر الجلسة التي التقطتها للتو. + + + LangGraph و LlamaIndex و Pydantic AI والوكلاء المخصصين. + + \ No newline at end of file diff --git a/docs/ar/start/integrations/custom-agents.mdx b/docs/ar/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..6e5db3c23 --- /dev/null +++ b/docs/ar/start/integrations/custom-agents.mdx @@ -0,0 +1,737 @@ +--- +title: "الوكلاء المخصصون" +sidebarTitle: "الوكلاء المخصصون" +description: "أدرج وكيلاً كتبته بنفسك، أو إطار عمل لا يوجد له محول في Failproof AI." +icon: "code" +--- + +لوكيل كتبته بنفسك، أو إطار عمل لا يوجد له محول في Failproof AI. لا شيء يجب إدراجه: أنت تصدر الأحداث. + +هذا هو نفس API الذي يستدعيه محولات الأطر الأربعة. وهي جداول ترجمة فوقه. + +## التثبيت + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # one tool call +``` + +اقرأه من الأعلى إلى الأسفل وسيخبرك بما يعنيه: + +| غلف فيه | للقول | +| --- | --- | +| `session()` | هذه الأحداث تنتمي إلى نفس التشغيل | +| `agent()` | شيء ما يقوم بالعمل — أعطه اسماً ستتعرف عليه في القائمة | +| `tool_call()` | هذه أداة واحدة، وإليك ما أرجعته | + +وما يصدره كل واحد فعلياً: + +| النطاق | يصدر | الغرض | +| --- | --- | --- | +| `session()` | لا شيء | يربط معرف الجلسة، مجموعة تشغيل واحدة | +| `agent()` | `agent_start`, `agent_end` | يحيط بوحدة عمل واحدة | +| `tool_call()` | `tool_use`, `tool_result` | يحيط بأداة واحدة ويقيسها | + +كل شيء بالداخل يمكن أن يحذف `session_id` و `agent_id`. تربط النطاقات الهوية على متغيرات السياق وكل نداء حدث يقرأها مرة أخرى، لذلك لا تمرر أبداً المعرفات من خلال وظائفك. + +تعمل الثلاثة جميعاً مع `async with` وكذلك مع `with`. + +يبني التداخل للوكلاء الشجرة. يتم حساب `parent_id` والعمق من المكدس: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## كيف يغلق النطاق + +`agent()` يتعامل مع الاستثناءات لك: + +| ما حدث | الأحداث | النتيجة | +| --- | --- | --- | +| لم يحدث شيء | `agent_end` | `success` | +| `Exception` | `error`، ثم `agent_end` | `failed` | +| `KeyboardInterrupt`, `SystemExit` | `error`، ثم `agent_end` | `failed` | +| `CancelledError`, `GeneratorExit` | `agent_end` فقط | `cancelled` | + +يتم إصدار الخطأ قبل `agent_end`، لأن لوحة التحكم تغلق الامتداد في `agent_end` وأي شيء بعده يُنسب إلى لا شيء. الإلغاء ليس فشلاً، لذلك لا تلوث التشغيلات الملغاة سطح الأخطاء. يتم إعادة رفع الاستثناء دائماً: النطاق لا يبتلعه أبداً. + +## طرق الحدث + +خمسة عشر طريقة في ست عائلات. معظمها يأتي في أزواج — تصدر الفاتحة، ثم الأغلق، و 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` | +| **الأعطال** | — | — | `error` | + + + فضّل النطاقات — `agent()` و `tool_call()` — أينما كانت مناسبة. إنها تضمن حدث الإغلاق حتى عندما يرفع الجسم. تصل إلى هذه الطرق مباشرة عندما لا يتداخل تدفق التحكم، مثل نداء نموذج داخل مساعد. + + + +```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 النماذج +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 الخطافات +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 البشر +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 الأعطال +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **العائلتان البشريتان تشير في اتجاهين متعاكسين.** + + | الطرق | المعنى | + | --- | --- | + | `human_wait` / `human_input` | **الوكيل طلب من شخص** — بوابة موافقة، سؤال توضيحي | + | `human_pause` / `human_interrupt` | **شخص تصرف على الوكيل** — زر إيقاف، توقف المشغل | + + لا يشير أي إطار عمل إلى الزوج الثاني، لذا فهو دائماً لك لإصداره. + + + + **مرر `request_id` عندما تعمل نداءات النموذج بالتزامن.** بدونه، تتزاوج طلبات الاستجابات بترتيب الوصول لكل وكيل — والنداءات المتزامنة تتزاوج بشكل خاطئ، مرفقة كل استجابة بالطلب الخاطئ. + + +## مثال + +حلقة استدعاء الأداة مقابل OpenAI API، بدون إطار عمل وكيل: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +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 + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +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 + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +ينتج عن هذا نفس أنواع الأحداث الستة التي سيعطيك المحول. الإصدار الكامل القابل للتشغيل، مع تعريفات الأداة، يأتي في مستودع SDK تحت `docs/manual/examples/`. + +## الخيوط و async + +تنتشر متغيرات السياق في مهام asyncio تلقائياً. لا تنتشر في خيوط جديدة، لأن الخيط يبدأ بسياق فارغ. + +```python +# asyncio: nothing to do +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# 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` تسمي الإصلاح بدلاً من الهبوط على جلسة لا شيء. هذا متعمد: حدث بدون جلسة يتم تخطيه بواسطة ingest والإجابة `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) + ``` + + + في أي مكان يستدعيه الإطار غلاف أداة أو برنامج وسيط. + + ```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(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **لديك عقدة أو خطوة أو حدود برنامج وسيط تستحق الرؤية؟** غلفها في زوج خطاف — `hook_triggered` / `hook_completed` — وليس `agent()` متداخل. `agent_id` هو جانب cardinality منخفض، وإدخال واحد لكل عقدة يغرقه. تُعرض امتدادات الخطاف بنفس الطريقة وتمنحك زمن الكمون لكل عقدة. + + + + **اليدوي والتلقائي يتكونان.** يدخل محول يعمل داخل نطاق مكتوب يدوياً تلك الجلسة والآباء إلى ذلك الوكيل، حتى تحصل على شجرة واحدة بدلاً من شجرتين — مفيد عندما تدرج إطار عمل بنفسك إلى جانب واحد مدعوم. + + + + سببان، والفتحات الثلاثة أعلاه هي الإجابة على كليهما: + + - `autogen-core` لم يتم صيانته منذ سبتمبر 2025. + - AG2 لا يعرض نقطة تسجيل على مستوى العملية تعادل خطافات أطر العمل الأخرى، لذا فإن إدراجها يعني تغليف كل وكيل في كل موقع البناء. + + يسجل رسم الفتحات يدوياً نفس الأحداث، بنفس الدقة، كما سيفعل محول مشحون. + + +## الذهاب أعمق + +كيف يعمل التسجيل فعلياً. لا شيء من هذا مطلوب للبدء. + + + + + +كل تسجيل له نفس الشكل: يفتح امتداد، يتداخل العمل بداخله، وكل حدث افتتاحي يحصل على حدث إغلاق. + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + C --> E(["agent_end"]) +``` + +**الزوج** هو الوحدة. كل حدث إغلاق يحمل مدة يقيسها SDK من الحدث الافتتاحي الخاص به. + +فيما يلي تشغيل واحد حقيقي لكل إطار عمل — مأخوذ من الأمثلة المشحونة مع SDK، اسم النموذج معياري. لاحظ كم يعود من نداء واحد. + + + + ```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 out-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 14 +5.721s agent_end LangGraph · success + ``` + + تصبح العقد أزواج خطاف، لذا تحصل على زمن الكمون لكل عقدة بدون أن تزحمها قائمة الوكيل. + + + + ```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 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 out-tok + 9 +5.727s agent_end analyst · success + 10 +5.739s agent_end crew · success + ``` + + يصبح `role` لكل وكيل اسم امتداده، لذا ينقسم زمن الكمون ومصروف الرمز حسب الدور. + + + + ```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 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 + ... second iteration + 26 +7.038s agent_end Agent · success + ``` + + حلقة الوكيل نفسها مرئية، ليس فقط نداءاته النموذجية. + + + + ```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 + 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 + 8 +8.119s agent_end agent · success + ``` + + لا توجد أزواج خطاف: Pydantic AI لا يملك حد عقدة أو خطوة للإحاطة به. + + + + ```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 out-tok + 6 +0.000s agent_end main · success + ``` + + أنت تصدر هذه بنفسك. نفس أنواع الأحداث، نفس الدقة — إنه يكلفك مواقع الاستدعاء. + + + + + + + +**لا توجد حدث نهاية الجلسة.** الجلسة ليست شيء تغلقه — إنها مجموعة من الأحداث تشترك في `session_id`. + +يتم استخلاص الحالة من شكل التتبع: + +| الحالة | متى | +| --- | --- | +| `ongoing` | لا يزال امتداد واحد على الأقل مفتوحاً | +| `paused` | `agent_pause` بدون `agent_resume` مطابقة | +| `error` | لا شيء مفتوح، وحدث واحد على الأقل فشل | +| `done` | لا شيء مفتوح، وشيء فشل | + +لذلك تنتهي الجلسة عندما يتم إغلاق كل زوج. يصدر المحولات `agent_end` لك، وعند الهدم يغلقون أي شيء لا يزال مفتوحاً ويوقعونه كغير كامل — يستقر التشغيل المتعطل كـ `done` بفجوة مرئية بدلاً من التعليق. + + + هذا هو السبب في أن الجلسة يمكن أن تمتد على نداءين. يوقف `interrupt()` في LangGraph التشغيل، يبقى الامتداد الجذري مفتوحاً عن قصد، والنداء المستأنف يغلقه. كلا النداءين جلسة واحدة. + + + + + + +`session_id` و `agent_id` اختياريان في كل طريقة حدث. محذوفاً، يحلان من النطاق المرفق: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") +``` + +تمريرهما بشكل صريح يعمل بعد ذلك ويأخذ الأسبقية. بدون شيء مرتبط وبدون شيء تم تمريره، يرفع الاستدعاء `TypeError` تسمية الإصلاح بدلاً من إصدار حدث بدون جلسة، والتي ستقفزها ingest مع الإجابة `200`. + +تربط النطاقات الهوية على متغيرات السياق. تلك تنتشر في مهام 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` + +أول تطابق يفوز: + +1. `session_id` خيار صريح +2. البيانات الوصفية لكل نداء +3. نطاق `session()` المرفق +4. بيانات إطار العمل الوصفية +5. معرف التشغيل الخاص بإطار العمل + +لا يتم اختراعه أبداً مع وجود أحد تلك — معرف مركب سيقسم تشغيل واحد عبر عدة جلسات. + +#### حافظ على `agent_id` على cardinality منخفضة + +إنه الجانب الأساسي على كل سطح لوحة تحكم، وعمود `LowCardinality(String)`. تقلل القيمة لكل تشغيل العمود وتملأ قائمة القائمة المنسدلة بإدخال واحد لكل تشغيل. + +تحافظ المحولات على هذا العمود لك: + +| يسلم الإطار | مسجل باسم | لماذا | +| --- | --- | --- | +| `3f9a1c2b-…` (معرف فريد) | `main` | لا شيء يمكن قراءته للاحتفاظ به | +| سلسلة سادسة عشرية طويلة عارية | `main` | نفس | +| `agent-3f9a1c2b-…` | `agent` | تم تجريد معرف لكل تشغيل، تم الاحتفاظ بالجزء القابل للقراءة | +| `agent-v2` | `agent-v2` | تُترك الأجزاء القصيرة وحدها | +| `step-3` | `step-3` | نفس | + +المعرف الحقيقي يبقى على `fw_agent_id` / `fw_run_id`، حيث يبقى قابلاً للاستعلام بدون أن يكون جانباً. + + + **هذا الحراس يلمس فقط التسميات التي اختارها *الإطار*.** `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` | +| الأعطال | `error` | + +أي إطار عمل يسجل ماذا، مقاس من التشغيلات أعلاه: + +| الحدث | LangGraph | CrewAI | LlamaIndex | Pydantic AI | مخصص | +| --- | :--: | :--: | :--: | :--: | :--: | +| بداية الوكيل والنهاية | نعم | نعم | نعم | نعم | أنت | +| نموذج الطلب والاستجابة | نعم | نعم | نعم | نعم | أنت | +| استخدام الأداة والنتيجة | نعم | نعم | نعم | نعم | أنت | +| تم تشغيل الخطاف واكتمل | عقدة | مهمة | خطوة | — | أنت | +| خطأ | نعم | نعم | نعم | نعم | تلقائي | +| الانتظار البشري والمدخلات | نعم | نعم | نعم | — | أنت | +| الوكيل يوقف ويستأنف | نعم | نعم | نعم | — | أنت | + +الشرطة تعني أن الإطار ليس لديه مثل هذا المفهوم. `human_pause` و `human_interrupt` تصف *شخص* يتصرف على الوكيل، الذي لا يشير إليه أي إطار — انبعث بنفسك. + + + + + +حدث لا يصل وحده أبداً. يفتح أحدهما امتداد، يغلقه الآخر، والحدث الإغلاق يحمل مدة يقيسها 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` | الإجابة، وكم استغرق الشخص | + + + حدث افتتاحي بدون حدث إغلاق هو امتداد لا ينتهي أبداً. تُرسّم الجلسة كما لا تزال قيد التشغيل، إلى الأبد، ومدتها النشطة تستمر في النمو. هذا هو فشل العرض الذي يجب مراقبته عند الإدراج يدوياً. + + +#### قواعد الارتباط + +- أعد استخدام نفس `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` يثبت كل شيء، كل المحولات الأربعة مضمونة. تسحب الإضافات **الإطار**، وليس المحول. + +```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`. + + + لا يوجد `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 +``` + +| الاسم | يقبل أيضاً | +| --- | --- | +| `langchain` | `langgraph`, `langchain_core` | +| `crewai` | — | +| `llama_index` | `llamaindex`, `llama-index` | +| `pydantic_ai` | `pydantic-ai`, `pydanticai` | + +قراءة الكشف التلقائي `sys.modules`، وليس قائمة الحزمة المثبتة، لذا فإن إطار عمل لديك مثبت لكن لم تستورده أبداً لا يتم إدراجه ولا يتم استيراده نيابة عنك. لرؤية ما هو موصول: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +active() # ('langchain',) +``` + + + **`instrument("crewai")` على جهاز بدون CrewAI لا يرفع.** يسجل تحذيراً ويرجع `()`، حتى أحد إطر العمل المفقودة لا تأخذ عملية تدرج أيضاً آخرين. + + التحذير يحمل `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` لإرفاعه بدلاً من ذلك. تُقرأ تلك العلم **مرة واحدة وتُخزن مؤقتاً**، لذا يصدرها قبل بدء العملية بدلاً من تعيينها في منتصف التشغيل. + + + + **`instrument()` يجب أن يأتي *بعد* استيراد إطار العمل الخاص بك.** قراءة الكشف التلقائي `sys.modules`، لذا نداء عارٍ فوق الاستيراد يجد لا شيء، يثبت لا شيء، ويرجع `()`. + + + +```python خطأ +import failproofai_sdk +failproofai_sdk.instrument() # sys.modules has no langchain yet -> () + +import langchain # too late, nothing is wired +``` + +```python صحيح +import langchain # import the framework first +import failproofai_sdk + +failproofai_sdk.instrument() # finds it -> ('langchain',) +``` + +```python صحيح، مستقل الترتيب +import failproofai_sdk + +# Naming it imports the adapter on request, so this works from anywhere. +failproofai_sdk.instrument("langchain") +``` + + +احصل على هذا خطأ والعملية تعمل مع SDK مستوردة، المحول يبدو مثبتاً، و **حدث واحد لم يُصدر**. يسجل تحذيراً يقول بالضبط ذلك — لذا تحقق من السجلات أولاً عندما لا يسجل التشغيل شيئاً. + + + + + +```mermaid +flowchart LR + A["وكيلك"] --> B["محول"] + B --> C["كاتب
قائمة الذاكرة"] + C -->|"كل 0.5s"| D["ملف
JSONL على القرص"] + D --> E["مراقب Failproof"] + E -->|"HTTPS"| F["السحابة"] +``` + +| المرحلة | الوظيفة | يعمل في | +| --- | --- | --- | +| محول | ترجمة رد اتصال الإطار إلى أحد أنواع الأحداث 15 | عمليتك | +| كاتب | طوابير، دفعات، كتابة JSONL ذرية | عمليتك، خيط الخلفية | +| ملف | نقل دائم، ينجو من خروج عملية | القرص المحلي | +| مراقب | يراقب الملف، سفن دفعات، حذف ما ينقله | آلتك | +| استقبال | يعين معرف صف و dedup key، يرقي أعمدة قابلة للاستعلام | السحابة | + +الملف هو ما يجعل هذا آمناً: وكيلك لا يسد أبداً على الشبكة، وانقطاع السحابة يعني دليل ينمو بدلاً من فقدان الأحداث. + +كل تنظيف يكتب ملف دفعة واحدة، `.tmp` أولاً، ثم `fsync`، ثم إعادة تسمية ذرية: + +```text +~/.failproofai/custom-agents/events/ + event-2026-08-20T10-15-00-123Z-48213-0.jsonl +``` + +يختار المراقب فقط `.jsonl`، لذا لا يمكن أبداً قراءة ملف نصف مكتوب. الجذع يحمل طابع زمني، معرف العملية ورقم التسلسل، لذا لا يمكن لعمليتين تنظيف في نفس الميلي ثانية أن تصطدما. تُغطى القائمة بـ 10,000 حدث؛ بعد ذلك تسقط الأقدم وتسجل. + + + **`collector.redact` لا ينطبق على أحداث SDK الخاصة بك.** لا يراها أبداً. + + +المراقب **ينقل** دفعاتك. إنه لا يفتحها أو يعيد كتابتها. + +| الأحداث | مكتوب بواسطة | معاد بواسطة `collector.redact`؟ | +| --- | --- | --- | +| نصوص جلسة CLI | المراقب | نعم | +| نشاط الخطاف | المراقب | نعم | +| **كل ما يصدره SDK** | **عمليتك** | **لا** | + +التعديل يعمل حيث **يكتب** المراقب أحداثه الخاصة — وليس حيث تُنقل الدفعات. لذا طلب أو حجة أداة تحمل مفتاح API لا تزال تحمله عند الوصول. + +هذا مقصود. هذه هي نداءات الإدراج الخاصة بك، وإعادة الكتابة في الحركة ستعني أن الأحداث التي تستقبلها ليست الأحداث التي أصدرتها. + + + **أنت تتحكم في الحمولات من المصدر، في مكانين:** + + - أوقف التقاط المحتوى على المحول. **اسم الخيار يختلف، ومحول واحد لا يملك أي** — هذا ليس مفتاح عام واحد: + - LangChain / LangGraph, Pydantic AI — `capture_content=False` + - LlamaIndex — `capture_messages=False` + - CrewAI — **لا مفتاح محتوى على الإطلاق**؛ `session_id` هو الخيار الوحيد الذي يقرأه، لذا يتم تسجيل الطلبات والإكمالات دائماً. + + `instrument()` يسقط الخيارات التي لا يقرأها محول، لذا تمرير الاسم الخاطئ لا يرفع شيء ولا يغير شيء. + - لا تسلم السر إلى `input=` في المقام الأول. + + `collector.redact` ليس بديلاً عن أي منهما. + + + + **دليل ملف فارغ هو الحالة الصحية.** لا تستخدمه للتحقق من التسليم. + + +يحذف المراقب كل دفعة في غضون ميلي ثانية من نقلها، لذا فإن `ls` يتسابق المجمع ويظهر جزء من ما أصدرته — لا يمكن تمييزه عن SDK لم يسجل شيء. + +للتأكد من أن الأحداث هبطت فعلاً، تحقق من لوحة التحكم. لمراقبة امتلاء الملف، توقف المراقب أولاً. + + + + + +كل رد اتصال يعمل داخل غلاف وظيفته الوحيدة هي إعادة الرفع، لذا استدعاؤك يجلس في `try` واحدة بالضبط وكل شيء SDK يحدث خارجها. + +| ما يحدث | النتيجة | +| --- | --- | +| خطاف يرفع | مسجل مرة واحدة مع traceback الخاص به. استدعاؤك غير متأثر | +| نفس الخطاف يرفع ثلاث مرات | يتم تعطيل ذاك الخطاف للعملية المتبقية، مع سطر خطأ واحد | +| `FAILPROOFAI_SDK_STRICT=1` معين | يتم إعادة رفع الاستثناء بدلاً من ذلك | +| إصدار إطار عمل خارج النطاق المختبر | يحذر مرة واحدة، يدرج على أي حال | +| قدرة واحدة مفقودة | يتم تعطيل ذاك الخطاف فقط، لا أبداً محول كامل | + +الافتراضي صحيح في الإنتاج وخاطئ أثناء التصحيح، لأنه لا يمكن أبداً إثبات أنه لم يتعطل. اضبط `FAILPROOFAI_SDK_STRICT=1` لإسكات الفشل المبتلع. + + + + + +## مشاكل شائعة + + + + حدث افتتاحي بدون حدث إغلاق: `model_request` بدون `model_response`، أو `tool_use` بدون `tool_result`. استخدم النطاقات، التي تضمن الزوج حتى عندما يرفع الجسم. إذا استدعيت طرق الحدث مباشرة، استخدم `try` و `finally`. + + + + يتم قياسه من حدث الافتتاح المطابق، لذا يتم رفضه على `tool_result` و `hook_completed` و `agent_resume` و `human_input`. يتم قبوله على `model_response`، لأن فقط أنت تعرف زمن المزود الحقيقي، ويجب أن يكون عدداً صحيحاً. + + + + الخيط لم يرث السياق أبداً. غلف الدالة في `failproofai_sdk.propagate()`. انظر [الخيوط و async](#threads-and-async). + + + + الحقول الإضافية تدمج آخراً، لذا أحد باسم مثل حقل حقيقي مثل `model` أو `outcome` سيكتب فوقه ويغير عمود مخزن. مساحة أسماء لك؛ المحولات تستخدم بادئة `fw_`. + + + + `agent_id` هو جانب cardinality منخفض وأنت وضعت معرف تشغيل فيه. استخدم دوراً أو اسم عقدة وضع المعرف الحقيقي في حقل الحمولة. + + + +## التالي + + + + الأزواج والمعرفات ودورة حياة الجلسة والتسليم. + + + اتبع السببية عبر الجلسة التي التقطتها للتو. + + + LangGraph و CrewAI و LlamaIndex و Pydantic AI. + + \ No newline at end of file diff --git a/docs/ar/start/integrations/langchain.mdx b/docs/ar/start/integrations/langchain.mdx new file mode 100644 index 000000000..c6f9eee46 --- /dev/null +++ b/docs/ar/start/integrations/langchain.mdx @@ -0,0 +1,245 @@ +--- +--- +title: "LangChain و LangGraph" +sidebarTitle: "LangChain و LangGraph" +description: "قم بتتبع الرسوم البيانية والعقد والأدوات والمسترجعات واستدعاءات النموذج برمز واحد." +icon: "/images/frameworks/langchain.svg" +--- + +محول واحد يخدم كليهما. يعمل LangGraph على مدير الاستدعاءات (callback manager) الخاص بـ `langchain-core`، لذا فإن تتبع أحدهما يتابع الآخر. + +## التثبيت + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +للحصول على LangChain بدون LangGraph، استخدم `failproofai-sdk[langchain]`. + +المدعوم: `langchain-core` 1.4.7 إلى 2.0، `langgraph` 1.2 إلى 2.0. خارج هذا النطاق، يتم تثبيت المحول وإصدار تحذير مرة واحدة. + +## التتبع + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +يسجل `instrument()` محلل التتبع عبر `langchain_core.tracers.context.register_configure_hook`. يقوم LangChain بحقنه في كل مدير استدعاءات يقوم ببنائه، بحيث يتم التقاط الرسوم البيانية والأدوات والنماذج دون تغيير موقع الاستدعاء — بما في ذلك تلك الموجودة داخل المكتبات التي لم تكتبها. + +## ما يتم تسجيله + +| LangChain أو LangGraph | حدث Failproof | +| --- | --- | +| التشغيل الجذري | `agent_start`، `agent_end` | +| عقدة LangGraph | `hook_triggered`، `hook_completed` | +| رسم بياني فرعي مترجم | `agent_start` و `agent_end` متداخلة | +| تشغيل الأداة | `tool_use`، `tool_result` | +| تشغيل المسترجع | `tool_use`، `tool_result`، الإخراج مختصر | +| تشغيل نموذج الدردشة أو LLM | `model_request`، `model_response`، مع استخدام الرموز | +| الرموز المرسلة | مطوية في الاستجابة كعدد القطع والوقت للرمز الأول. تحتاج عدادات الرموز إلى `ChatOpenAI(stream_usage=True)` — انظر أدناه | +| `interrupt()` | `human_wait`، `agent_pause` | +| `Command(resume=...)` | `agent_resume`، `human_input`، مرتبطة على `Interrupt.id` — بما في ذلك عند حدوث الاستئناف في عملية مختلفة ضد نفس checkpointer | +| استثناء غير معالج | `error`، ثم `agent_end` مع نتيجة `failed` | + +**تصبح العقدة hook وليس وكيلاً متداخلاً.** `agent_id` هي الجانب الأساسي عبر كل سطح لوحة التحكم — تعزيز `retrieve` و `grade_documents` و `should_continue` إلى وكلاء سيغرقها، ويعنون الجلسة بعد أي عقدة تحدث لتعمل أولاً. + +تعرض رسوم Hook بنفس الطريقة وتعطيك عرض الكمون لكل عقدة. + + + **سمّ عقدك كما تريد.** يتم تحديد تشغيل العقدة من خلال *شكلها* — تشغيل غير ورقة يحمل LangGraph الخاص بـ step tag — لا من خلال اسمها أبداً. + + +| ما تكتبه | ما يتم تسجيله | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | الأداة | +| `add_node("ChatOpenAI", ...)` | استدعاء النموذج | + +استخدام اسم العقدة بعد الشيء الذي يعمل عليه قد يؤدي إلى اختفاء أحداث الشيء. لم يعد الحال كذلك. + +### البث + +لا تصدر `.stream()` و `.astream()` أحداث لكل رمز. يتم طيها في `model_response` الختامي: + +| الحقل | يحمل | +| --- | --- | +| `fw_chunks` | عدد القطع التي وصلت | +| `fw_ttft_ms` | الوقت للرمز الأول | + +### عدادات الرموز على استجابة مرسلة + +مسألة منفصلة، وسهلة الإغفال: يرسل OpenAI الاستخدام على استجابة مرسلة **عند طلبها فقط**. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # بدون هذا، لا توجد رموز +``` + +يسجل المحول ما يسلمه الإطار له. بدون هذا الخيار لا يوجد شيء للتسجيل، و `model_response` يصل بدون عدادات الرموز. + +## مثال + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## سمّ رسومك البيانية + +بشكل افتراضي، تأخذ رسالة الجذر اسم الرسم البياني الخاص به. قم بلفها للحصول على تسمية اخترتها: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +للإعدادات متعددة الوكلاء، أدرج النطاقات. يصبح كل عامل رسمة فرعية تحمل `parent_id`: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +حافظ على `agent_id` بقليل من الاختلاف. استخدم دوراً أو اسم عقدة، أبداً UUID أو سلسلة نصية لكل تشغيل. + +## التحكم في الجلسة + +معرّف الجلسة يتم حله بهذا الترتيب، المطابقة الأولى تفوز: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. نطاق `failproofai_sdk.session()` المحيط +4. `metadata["session_id"]` أو `metadata["conversation_id"]` أو `metadata["thread_id"]` +5. معرّف التشغيل الجذري + +لا يتم إنشاؤها من الصفر أبداً، لأن معرّف صناعي يقسم تشغيل واحد عبر عدة جلسات. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## الخيارات + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # ثبّت كل تشغيل إلى معرّف جلسة واحد + include_chains=set(), # قائمة بيضاء للسلاسل الوسيطة كأزواج hooks + capture_content=True, # False يسقط الأوامر والإكمالات من الحمولات + graph_callbacks=True, # مقاطعة واستئناف من الدرجة الأولى، تحتاج langgraph 1.2+ +) +``` + +عيّن `capture_content=False` للبيانات المنظمة. الهيكل والتوقيتات وعدادات الرموز وأسماء الأدوات والنتائج لا تزال مسجلة؛ أجسام الرسائل لا. + +`include_chains` ينطبق على التشغيلات **المتداخلة** فقط. runnable الذي تستدعيه على المستوى الأعلى هو جذر الجلسة، بحيث يصبح رسمة الوكيل بدلاً من زوج hook، والتسمية هنا ليس لها تأثير. + +## الإنسان في الحلقة + +`interrupt()` ينتج أربعة أحداث، وليس أي زوج مكرراً: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +يحمل `human_wait` إلى `human_input` الأمر والإجابة (كلاهما مُسقط تحت `capture_content=False`، جنباً إلى جنب مع مصادر وثائق الاسترجاع — ينجو عدد الوثائق). `agent_pause` إلى `agent_resume` هو الزوج الوحيد الذي يعطي الوقت المتوقف، لذا بدونه فإن انتظار إنساني لمدة عشر دقائق يتم تحديده كوقت وكيل نشط. تبقى الرسالة الجذرية مفتوحة عبر الفجوة، مما يبقي كلا الاستدعاءات في جلسة واحدة. + +## المشاكل الشائعة + + + + `create_react_agent` تنشر الاستثناء. للسماح للنموذج برؤية الفشل والمتابعة، قم بإنشاء عقدة الأداة بشكل صريح: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + يتم تسجيل الفشل كـ `tool_result` يحمل خطأ في كلا الحالتين. هذا يقرر فقط ما إذا كان التشغيل ينجو منه. + + + + `llm.invoke()` مباشر خارج أي رسم بياني ليس له تشغيل أب، لذا فإنه يفتح رسمة جذرية ويصدر زوج النموذج الخاص به داخلها. لوحة التحكم تربط الأوراق بوكيل مفتوح، بحيث تكون الرسمة مقصودة. سمّها: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + لقد مررت معالج Failproof في `config={"callbacks": [...]}` بالإضافة إلى استدعاء `instrument()`. قم بإزالته. يغطي خطاف التكوين بالفعل كل مدير استدعاءات في العملية. + + + + لا تفعل. يرفع LangGraph `GraphInterrupt` عبر نفس المسار مثل استثناء حقيقي، لذا كل توقف يصل إلى المتتبع كرد استدعاء خطأ. يتم التعامل مع أي فئة فرعية من `GraphBubbleUp` كتدفق تحكم بدلاً من ذلك، لذا فإن موافقة لا تطلي خطأ أحمر. + + + + تحقق بهذا الترتيب: `instrument()` تشغل قبل تنفيذ الرسم البياني؛ هناك `with failproofai_sdk.session():` حول الاستدعاء؛ تم ضبط `FAILPROOFAI_SDK_STRICT=1`، لذا يرفع خطاف منخفض بدلاً من امتصاصه. + + + +## التالي + + + + الأزواج والمعرّفات ودورة حياة الجلسة والتسليم. + + + اتبع السببية عبر الجلسة التي التقطتها للتو. + + + CrewAI وLlamaIndex وPydantic AI والوكلاء المخصصون. + + \ No newline at end of file diff --git a/docs/ar/start/integrations/llamaindex.mdx b/docs/ar/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..76bd857d4 --- /dev/null +++ b/docs/ar/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "ضبط سير العمل والخطوات والوكلاء الوظيفيين والمسترجعات." +icon: "/images/frameworks/llamaindex.svg" +--- + +## التثبيت + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +مدعوم: `llama-index-core` 0.14.23 إلى 0.15. 0.14.23 هو الإصدار حيث بدأ تدفق سير العمل بنقل أحداث الوكيل المكتوبة بشكل صريح التي يقرأها هذا المحول. تحته، تختفي أسماء النموذج وهيكل الوكيل معاً. + +## الضبط + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +واجهة برمجة التطبيقات للوكيل في LlamaIndex غير متزامنة. كل نطاق يعمل تحت `async with` وكذلك `with` وينتج أحداثاً متطابقة. + +`instrument()` تربط معالج حدث ومعالج امتداد لموزع LlamaIndex العام. معاً يجعلان حلقة الوكيل مرئية، وليس فقط استدعاءات نموذجه. + + + بدون وسيطة إضافية على نموذجك، كل عدد رموز في تتبعك قيمته null. انظر [عدد الرموز](#token-counts) أدناه. + + +## عدد الرموز + +`FunctionAgent` يستدعي `astream_chat`، و`llama-index-llms-openai` لا يرسل `stream_options={"include_usage": True}` عند البث. المزود بالتالي لا يرسل أبداً مقطع الاستخدام، ولا شيء لأي أداة ضبط لقراءته. + +هذا سلوك LlamaIndex الأساسي. قم بالاشتراك في نموذجك: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +تم القياس في نفس التشغيل والنموذج: + +| | رموز الإدخال | رموز الإخراج | +| --- | --- | --- | +| بدون | `null` | `null` | +| مع | 148 | 17 | + +استدعاءات البث غير المتزامن (`llm.chat`, `llm.achat`) تقرر الاستخدام بدون تكوين. فقط مسار البث، وهو المسار الافتراضي للوكيل، يحتاج إلى هذا. + +## ما يتم تسجيله + +| LlamaIndex | حدث Failproof | +| --- | --- | +| `Workflow.run` امتداد الجذر | جلسة، `agent_start`، `agent_end` | +| امتداد `Workflow.run` المتداخل | `agent_start` متداخل، `agent_end` | +| امتداد خطوة سير العمل | `hook_triggered`، `hook_completed` | +| بداية ونهاية دردشة LLM | `model_request`، `model_response` | +| امتداد `FunctionTool.call` | `tool_use`، `tool_result` | +| بداية ونهاية الاسترجاع | `tool_use`، `tool_result`، الناتج المختصر | +| التضمينات | لا شيء، إلا إذا كان `embeddings=True` | +| أداة تنتظر شخصاً | `human_wait`، `agent_pause`، ثم `agent_resume`، `human_input` | +| مسلمة `AgentWorkflow` | `agent_start` متداخل، `agent_end` لكل وكيل، مرتبط بسير العمل | +| الاستثناء | `error`، ثم `agent_end` مع النتيجة `failed`، و`agent_end.summary` يسميها | +| `handler.cancel_run()` | `agent_end` مع النتيجة `cancelled` وبدون `error` — زر الإيقاف ليس فشلاً | + +`agent_id` هو `FunctionAgent.name` عندما تحدده، واسم فئة سير العمل وإلا. تحت `AgentWorkflow`، كل وكيل يأخذ دوره يحصل على امتداده الخاص المتداخل تحت سير العمل، لذا تُقرأ المسلمة كوكيلين بدلاً من واحد. + +الناتج من الاسترجاع مختصر بدلاً من أن يُرمى. يعيد المسترجع المستندات، وتخزينها في الحمل سيضع مجموعة النصوص الخاصة بك في مخزن الأحداث مرة واحدة لكل استعلام. يتم الاحتفاظ بالعدد، نطاق النقاط، والمقاطع المختصرة بدلاً من ذلك. + +## مثال + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +تظهر حلقة الوكيل في التتبع كأزواج hook: `init_run`، `setup_agent`، `run_agent_step`، `parse_agent_output`، `call_tool`، و`aggregate_tool_results`. إنها حلقة الإطار نفسه، لذا فهي hooks بدلاً من وكلاء، مما يحافظ على معنى `agent_id`. + +## سمِّ امتدادك + +`agent_id` هو `FunctionAgent.name` عندما تحدده، واسم فئة سير العمل وإلا. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +في `AgentWorkflow`، هذا الاسم هو أيضاً ما يتم تسجيل كل مسلمة تحته: + +```text +AgentWorkflow امتداد الأب +├─ city_analyst الدور 1 +├─ cost_analyst الدور 2 +└─ city_analyst الدور 3 — دور جديد، وليس دور معاد فتحه +``` + +إذاً `agent_id` يخبرك **أي وكيل** قام بالعمل و`parent_id` يخبرك **أي سير عمل** انتمى إليه. يفتح الوكيل الذي يسلم التحكم لاحقاً دوره الثاني بدلاً من إعادة فتح الأول. + +لف التشغيل لتجاوزه، أو لتجميع عدة وكلاء تحت أب واحد: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +أبق `agent_id` ذو كاردينالية منخفضة. إنها الجانب الأساسي على كل سطح لوحة معلومات، لذا استخدم دوراً أو اسم سير عمل، لا تستخدم UUID أو سلسلة لكل تشغيل. + +## تحكم في الجلسة + +هذا المحول **لا يأخذ خيار `session_id`**. تأتي الجلسة من النطاق المحيط، وإلا `uuid4().hex` مُولدة لكل تشغيل سير عمل: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## الخيارات + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True يسجل استدعاءات التضمين كأزواج أدوات + steps=True, # False يسقط أزواج hook خطوة سير العمل + capture_messages=True, # False يسقط EVERY الحمل: المحفزات، الإكمالات، + # وسائط الأداة والناتج، إدخال وإخراج الخطوة، استعلامات + # الاسترجاع، الهدف والإجابة النهائية + capture_limit=8192, # الأحرف المحتفظ بها لكل قيمة مقبوضة + stale_after=600.0, # ثواني قبل إغلاق أوراق الشجر المهجورة بقوة + reaper_interval=30.0, # عدد مرات كنس الحاصد؛ 0 يعطله +) +``` + +| الخيار | لماذا قد تغيره | +| --- | --- | +| `embeddings` | قم بالتشغيل فقط عند تصحيح كمون أو تكلفة التضمين. بناء فهرس مجموعي هو آلاف الاستدعاءات وسيدفن المخطط الزمني. | +| `steps` | أطفئه إذا كنت تريد فقط أحداث النموذج والأداة وتجد حلقة الوكيل مزعجة. | +| `capture_messages` | أطفئه للبيانات المنظمة. كل حمل يتوقف عن التسجيل — المحفزات، إكمال النموذج، وسائط الأداة وقيم الإرجاع، إدخال وإخراج خطوة سير العمل، استعلامات الاسترجاع، هدف الوكيل وإجابته النهائية. الهيكل والتوقيتات والرموز والنتائج لا تزال مسجلة. | +| `capture_limit` | الأحرف المحتفظ بها لكل قيمة مقبوضة قبل الاقتطاع. ارفعه عندما يصل محفز RAG أو السياق المسترجع مقطوعاً. | +| `stale_after` | الثواني قبل إغلاق ورقة شجر مهجورة بقوة — استجابة بث لم يستهلكها أحد، امتداد نموذج أو أداة لم يصل إغلاقه — بحيث تستقر الجلسة بدلاً من قراءة `ongoing` للأبد. هذا **لا** يغلق التشغيل المهجور نفسه: سير عمل تم إلغاء مهمته دون أن يرى الموزع مخرجاً يحتفظ بـ `agent_start` مفتوح حتى `uninstrument()`. | +| `reaper_interval` | تكرار المسح. اضبطه على `0` لتعطيل الحاصد كلياً. | + +## الإنسان في الحلقة + +يتم الالتقاط عند حدوث الانتظار داخل أداة: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +`ctx.wait_for_event` في خطوة سير عمل عادية لا يتم التقاطها. يمسك وقت التشغيل بالقطرة قبل وصولها للموزع، لذا تخرج الخطوة وتعاد لاحقاً بدون إشارة لمفتاح الإيقاف عليها. نمط FunctionAgent، الذي توثقه LlamaIndex، ينتظر داخل أداة ويتم التقاطه بالكامل. + +## مشاكل شائعة + + + + أضف `additional_kwargs={"stream_options": {"include_usage": True}}` إلى نموذجك. انظر [عدد الرموز](#token-counts). + + + + LlamaIndex لا يملك حقل استخدام قياسي. يحاول المحول عدة أشكال معروفة، والتكامل الذي يسمي العدادات الخاصة به بشيء جديد لن يطابق أي منها. + + يشحن القاموس الخام دائماً، لذا تحقق من `usage` في الحمل لترى ما سماه مزودك. + + `usage` مملوء بجانب أعمدة رموز فارغة مقصود — يفوق عدداً خاطئاً واثقاً. + + + + هذه حلقة FunctionAgent، مجموعة واحدة لكل تكرار. صفِّ حسب اسم hook على لوحة المعلومات. توقيتات الخطوة هذه عادة ما تكون السبب لاستخدام هذا المحول بدلاً من محول نموذج فقط. + + + + تحقق بهذا الترتيب: `instrument()` تم تشغيله قبل التشغيل؛ هناك `async with failproofai_sdk.session():` حول `await`؛ `llama-index-core` هو 0.14.23 أو أحدث؛ `FAILPROOFAI_SDK_STRICT=1` مضبوط، لذا يرفع hook متدهور بدلاً من أن يبتلع. + + + +## التالي + + + + الأزواج والمعرفات ودورة حياة الجلسة والتسليم. + + + اتبع السببية عبر الجلسة التي استقطتها للتو. + + + LangGraph، CrewAI، Pydantic AI، والوكلاء المخصصين. + + \ No newline at end of file diff --git a/docs/ar/start/integrations/pydantic-ai.mdx b/docs/ar/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..1474a95be --- /dev/null +++ b/docs/ar/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "أدوات تجسيد العملاء المكتوبة والأدوات واستدعاءات النموذج والمحاولات المتكررة." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## التثبيت + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +مدعوم: `pydantic-ai-slim` 2.0 إلى 3.0. أزال الإصدار 2.0 `Agent(instrument=...)` وأدخل بروتوكول الإمكانيات الذي يُبنى عليه هذا المحول، لذلك لا يمكن تجسيد 1.x بهذه الطريقة. + +## التجسيد + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # قبل بناء أي Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + يجب أن يتم تشغيل `instrument()` قبل بناء `Agent`. تُضاف الإمكانية عند البناء، لذا فإن وكيل مبني مسبقاً لا يحمل أي إمكانية ولا يسجل شيئاً، بدون خطأ لأنه لم يحدث شيء خاطئ. هذا هو السبب الأكثر شيوعاً للحصول على تتبع فارغ مع هذا المحول. + + +الوكلاء في نطاق الوحدة هم حيث يحدث المشكلة: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # مبني في وقت الاستيراد + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # شغل هذا أولاً +import agents # الآن يحصل الوكيل على الإمكانية +``` + +تأكد من أنه نجح: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +يدمج Pydantic AI القائمة التي تمررها في `root_capability` واحد، لذا لا توجد خاصية `agent.capabilities` للقراءة. + +الوكلاء المبنيون أثناء التجسيد يحافظون على الإمكانية، لذا يمكنك `uninstrument()` وإعادة التجسيد دون إعادة بناء. + +## ما يتم تسجيله + +| Pydantic AI | حدث Failproof | +| --- | --- | +| تشغيل الوكيل | `agent_start`, `agent_end` | +| طلب النموذج | `model_request`, `model_response`، مع استخدام الرموز | +| استدعاء الأداة | `tool_use`, `tool_result`، مع المعاملات التي أرسلها النموذج | +| `ModelRetry` من أداة | `tool_result` يحمل خطأ | +| استثناء غير معالج | `error`، ثم `agent_end` بنتيجة `failed` | + +لا توجد زوج خطاف ولا زوج موارد بشرية هنا. Pydantic AI لا يحتوي على حد عقدة أو خطوة ليتم وضع قوس حوله ولا توقف بشري مدمج، لذا لا يوجد شيء للتعيين. إذا بنيت أياً منهما، أطلق الأحداث بنفسك — انظر [Custom agents](/ar/reference/custom-agents). + +`output_type` لا يختلف عن التتبع. تشغيل مكتوب وتشغيل سلسلة ينتجان نفس الأحداث. + +## مثال + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +في التتبع، تظهر `restock_eta` كـ `tool_result` تحمل خطأ، متبوعة باستدعاء نموذج آخر حيث يعمل الوكيل حوله، والتشغيل ينتهي بـ `success`. يتم الاحتفاظ بالحقائق. + +## الأخطاء والمحاولات المتكررة والتحكم في التدفق + +يرفع Pydantic AI استثناءات لثلاثة أشياء مختلفة، والمحول يفصل بينها: + +| الاستثناء | يُعتبر | النتيجة | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | فشل أداة حقيقي | `tool_result` مع خطأ؛ التشغيل قد ينتهي بـ `success` | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | تحكم في التدفق | ليس خطأ؛ يتم توجيه التشغيل | +| أي شيء آخر | فشل | `error`، ثم `agent_end` بنتيجة `failed` | + +`ModelRetry` في المجموعة الأولى عن قصد. يعني أن محاولة فشلت بحقيقة وطُلب من النموذج المحاولة مجدداً، وهذا هو المقصود من حقل خطأ نطاق الأداة. تصنيفها كتحكم في التدفق سيخفي أخطاء الأداة الحقيقية خلف تشغيل أخضر. + +## سمّ امتدادات الأحداث الخاصة بك + +امتداد التشغيل الخاص بـ Pydantic AI نفسه باسم `agent`. قم بالتفاف الاستدعاء لإعطاؤه تسمية اخترتها: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +امتداد الإطار ثم يتداخل تحت `inventory`، وهذا هو المكان الذي يتعلق به أحداث النموذج والأداة. + +احتفظ بـ `agent_id` بتنوع منخفض. إنه الجانب الأساسي على كل سطح لوحة معلومات، لذا استخدم اسم دور، لا تستخدم UUID أو سلسلة لكل تشغيل. + +## التحكم في الجلسة + +تم حلها بهذا الترتيب، أولى المطابقات تفوز: + +1. `instrument("pydantic_ai", session_id=...)` +2. نطاق `failproofai_sdk.session()` المضمن +3. `conversation_id` للتشغيل، ثم `run_id` الخاص به +4. معرف UUID مولّد `uuid4().hex` + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## الخيارات + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # ثبّت كل تشغيل على معرف جلسة واحد + capture_content=True, # False يسقط المطالبات والإكمالات من الحمولات +) +``` + +## المشاكل الشائعة + + + + تم بناء `Agent` قبل تشغيل `instrument()`. انظر التحذير أعلاه، وتحقق من `agent.root_capability.capabilities`. + + + + تنتشر `raise` العارية؛ هذا هو تصميم Pydantic AI. للسماح للنموذج بالعمل حوله، ارفع `ModelRetry` برسالة يمكنه التصرف بناءً عليها. يتم تسجيل الفشل بأي حال. + + + + هذا الطفل هو امتداد التشغيل الخاص بـ Pydantic AI، وهذا هو المكان الذي يتعلق به أحداث النموذج والأداة. أسقط نطاقك الخاص إذا كنت تريد امتداداً واحداً، على حساب الاسم المخصص. + + + + رسم بياني غير المتزامن من Pydantic AI أطول من حد حقل الحمولة، والسطر الأخير من التتبع هو الاستثناء نفسه. يتم قص هذا الحقل من الأمام وليس من الخلف، لذا يبقى السطر الذي تحتاجه. + + + +## التالي + + + + الأزواج والمعرفات ودورة حياة الجلسة والتسليم. + + + اتبع السببية من خلال الجلسة التي التقطتها للتو. + + + LangGraph و CrewAI و LlamaIndex والوكلاء المخصصين. + + \ No newline at end of file diff --git a/docs/ar/start/quickstart.mdx b/docs/ar/start/quickstart.mdx index b6b9c2a15..0932384ee 100644 --- a/docs/ar/start/quickstart.mdx +++ b/docs/ar/start/quickstart.mdx @@ -1,15 +1,16 @@ --- +--- 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 في وقت التشغيل. +**أي المسار يناسبك؟** إذا كان وكيلك يعمل في أحد الأدوات 12 المدعومة [harnesses](/ar/reference/harnesses) — واجهة أوامر للبرمجة أو بوابة مثل Hermes أو OpenClaw — اتبع الخطوات أدناه؛ تحتاج إلى Node.js 20.9 أو أحدث. إذا كان وكيلك لا يملك أداة، قم بتجهيزه باستخدام [Python SDK](/ar/reference/custom-agents) للتتبع والتدقيق، ثم عد إلى [تشغيل فحص الفشل الأول](/ar/start/first-audit)؛ يتطلب التنفيذ في هذا المسار خطاف في وقت التشغيل الخاص بك. - + ```bash @@ -21,16 +22,16 @@ 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) وأنشئ حساباً أو سجل الدخول باستخدام بريدك الإلكتروني للعمل. +1. افتح [لوحة تحكم Failproof AI](https://app.befailproof.ai) وأنشئ حساباً أو سجل الدخول ببريدك الإلكتروني للعمل. 2. انتقل إلى **Administration → Keys** وأنشئ مفتاحاً باستخدام `events:add` و `policies:pull`. -3. انسخ السر لمرة واحدة وقم بتخزينه على الجهاز المستهدف: +3. انسخ السر لمرة واحدة واحفظه على الجهاز المستهدف: ```bash export FAILPROOFAI_KEY="" @@ -39,15 +40,15 @@ export FAILPROOFAI_KEY="" ## التثبيت - + ```bash npm install -g failproofai failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - يتم إرسال نصوص الجلسات بشكل افتراضي. أضف `--no-transcripts` للإبلاغ عن نشاط hook وقرارات السياسة دون محتوى النص. + يتم إرسال نصوص الجلسة بشكل افتراضي. أضف `--no-transcripts` للإبلاغ عن نشاط الخطاف وقرارات السياسة دون محتوى النصوص. - إذا كان لدى هذا الجهاز بالفعل سجل وكيل، معاينة واستيراد آخر سبعة أيام، ثم انتظر انتهاء التسليم. تخطَّ هذه الخطوة على جهاز جديد. + إذا كان هذا الجهاز يحتوي بالفعل على سجل وكيل، معاينة واستيراد آخر سبعة أيام، ثم انتظر انتهاء التسليم. تخطى هذه الخطوة على جهاز جديد. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +56,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - افتح **Sessions** في Failproof AI واختر جلسة مستوردة. + افتح **Sessions** في Failproof AI وحدد جلسة مستوردة. - - يربط Failproof AI بإطار العمل الخاص بك وينصب السياسات المدمجة الـ 40. استخدمها لرؤية قرارات السياسة المحلية وجرب الإنفاذ قبل أن يقوم Failproof AI بتدقيق جلساتك وكتابة السياسات لوكلائك. + + يقوم هذا بربط Failproof AI بأداتك وتثبيت 40 سياسة مدمجة. استخدمها لرؤية قرارات السياسة المحلية وتجربة التنفيذ قبل أن يقوم Failproof AI بتدقيق جلساتك وكتابة السياسات لوكلائك. - دع المثبت يكتشف إطار العمل الخاص بك، أو قم بتسمية واحد صراحةً. كل واحد من الـ 12 هو قيمة `--cli` صحيحة — `claude`، `codex`، `copilot`، `cursor`، `opencode`، `pi`، `hermes`، `openclaw`، `factory`، `devin`، `antigravity`، `goose`. + دع برنامج التثبيت يكتشف أداتك، أو قم بتسمية واحدة صراحة. كل واحد من الـ 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) للمصفوفة لكل أداة. - - اتبع [تشغيل فحص الفشل الأول](/ar/start/first-audit). استخدم هدفاً ملموساً مثل "ابحث عن الجلسات حيث أعاد الوكيل محاولة أداة فاشلة دون تغيير نهجه." + + اتبع [تشغيل فحص الفشل الأول](/ar/start/first-audit). استخدم هدفاً محدداً مثل "ابحث عن الجلسات حيث أعاد الوكيل محاولة أداة فاشلة دون تغيير نهجه." - اتبع [منع فشلك الأول بسياسة](/ar/start/first-policy). ابدأ بوضع المراقبة، افحص المطابقات، ثم طبق الإصدار المراجع. + اتبع [منع الفشل الأول باستخدام سياسة](/ar/start/first-policy). ابدأ في وضع المراقبة، افحص المطابقات، ثم نفذ الإصدار المراجع. - قم بتشغيل `failproofai config --status`. يبلغ الإعداد الصحي عن اتصال السحابة وحالة daemon وما إذا كان الإنفاذ معلقاً. + شغّل `failproofai config --status`. يقدم الإعداد الصحي تقرير الاتصال بالسحابة وحالة الخادم والقوى العاملة وما إذا كان التنفيذ موقوفاً. \ No newline at end of file diff --git a/docs/ar/start/quickstarts/crewai.mdx b/docs/ar/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..d948814b2 --- /dev/null +++ b/docs/ar/start/quickstarts/crewai.mdx @@ -0,0 +1,38 @@ +--- +--- +title: "CrewAI" +description: "قم بالتثبيت والمراقبة وشاهد أول تتبع لك." +icon: "/images/frameworks/crewai.svg" +--- + +ثلاث خطوات للوصول إلى أول تتبع CrewAI الخاص بك. لمعرفة ما يحمله كل حدث والتدفقات واستكشاف الأخطاء، اطلع على [الدليل الكامل](/ar/start/integrations/crewai). + +## التثبيت + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## المراقبة + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +لا يتغير شيء في فريقك أو الوكلاء أو المهام أو الأدوات. تقوم `instrument()` بالاشتراك في حافلة الأحداث على مستوى الوحدة في CrewAI. + +## تحقق من وصوله + +قم بتشغيله مرة واحدة، ثم افتح **Observe → Sessions** وحدد بيئتك. ستظهر عملية التشغيل الخاصة بك كتتبع معاد بناؤه. + +إذا لم يصل شيء، تأكد من اتصال الجهاز باستخدام `failproofai config --status`. + + + ما يتم تسجيله والتدفقات واستخدام الرموز وتسمية الامتدادات والخيارات والمشاكل الشائعة. + \ No newline at end of file diff --git a/docs/ar/start/quickstarts/custom-agents.mdx b/docs/ar/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..e5b6d2347 --- /dev/null +++ b/docs/ar/start/quickstarts/custom-agents.mdx @@ -0,0 +1,51 @@ +--- +--- +title: "وكلاء مخصصون" +description: "غلّف وكيلك في ثلاث كتل `with` وسيبدأ التسجيل." +icon: "code" +--- + +لوكيل كتبته بنفسك، أو إطار عمل لا يملك Failproof AI محول له. + +تغلّف العمل الذي تقوم به بالفعل في كتل `with`. كل واحد منها يسجل متى بدأ، ومتى انتهى، والوقت المستغرق — لا تستدعي أي شيء آخر. + +## التثبيت + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # one tool call +``` + +اقرأه من الأعلى للأسفل وسيخبرك بما يعنيه: + +| غلّفه في | للقول | +| --- | --- | +| `session()` | هذه الأحداث تنتمي إلى نفس التشغيل | +| `agent()` | شيء ما يقوم بعمل — أعطه اسماً ستتعرف عليه في القائمة | +| `tool_call()` | هذا هو أداة واحدة، وإليك ما أرجعته | + +غلّفها بأي طريقة يتداخل بها الكود. لا تمرر المعرفات حول: كل كتلة تتذكر ما بداخلها، لذا أي شيء تسجله يلتقط التشغيل الصحيح والوكيل الصحيح تلقائياً. `async with` يعمل بنفس الطريقة تماماً. + +## تحقق من وصوله + +شغّله مرة واحدة، ثم افتح **Observe → Sessions** واختر بيئتك. سيظهر تشغيلك كأثر مُعاد بناؤه. + +إذا لم يصل شيء، تأكد من اتصال الجهاز باستخدام `failproofai config --status`. + + + كل طريقة حدث، ما يحدث عندما يرفع الكود استثناء، مثال عملي، الخيوط والعمليات غير المتزامنة، وأداة إطار عمل بدون محول. + \ No newline at end of file diff --git a/docs/ar/start/quickstarts/langchain.mdx b/docs/ar/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..b16ccee4b --- /dev/null +++ b/docs/ar/start/quickstarts/langchain.mdx @@ -0,0 +1,40 @@ +--- +--- +title: "LangChain و LangGraph" +description: "التثبيت والأداة والحصول على أول تتبع لديك." +icon: "/images/frameworks/langchain.svg" +--- + +ثلاث خطوات للحصول على أول تتبع LangChain أو LangGraph لديك. لمعرفة المزيد عن البث والتدخل البشري وتسمية الامتدادات والخيارات، اطّلع على [الدليل الكامل](/ar/start/integrations/langchain). + +## التثبيت + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +لـ LangChain بدون LangGraph، استخدم `failproofai-sdk[langchain]`. + +## الأداة + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +لا توجد تغييرات في موقع الاستدعاء. تسجل `instrument()` أداة تتبع يحقنها LangChain في كل مدير استدعاء ينشئه، لذلك يتم التقاط الرسوم البيانية والأدوات والنماذج — بما في ذلك تلك الموجودة داخل المكتبات التي لم تكتبها. + +## تحقق من وصولها + +قم بتشغيله مرة واحدة، ثم افتح **Observe → Sessions** واختر بيئتك. يظهر التشغيل لديك كأثر معاد بناؤه. + +إذا لم يصل شيء، تأكد من أن الجهاز متصل باستخدام `failproofai config --status`. + + + ما يتم تسجيله والبث وعدد الرموز وتسمية الامتدادات والتحكم في الجلسة والخيارات والتدخل البشري. + \ No newline at end of file diff --git a/docs/ar/start/quickstarts/llamaindex.mdx b/docs/ar/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..ebe8a41cc --- /dev/null +++ b/docs/ar/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "ثبّت وأدرج وشاهد أول تتبع لك." +icon: "/images/frameworks/llamaindex.svg" +--- + +ثلاث خطوات للوصول إلى أول تتبع LlamaIndex لديك. للاطلاع على خطوات سير العمل والاسترجاع والخيارات، راجع [الدليل الكامل](/ar/start/integrations/llamaindex). + +## التثبيت + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## الإدراج + +واجهة برمجة تطبيقات عامل LlamaIndex غير متزامنة. كل نطاق يعمل تحت `async with` وكذلك `with`. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + بدون حجة إضافية واحدة على نموذجك اللغوي، كل عدد رموز في تتبعك يكون فارغًا — `llama-index-llms-openai` لا يطلب الاستخدام عند البث. انظر [عدد الرموز](/ar/start/integrations/llamaindex#token-counts). + + +## تحقق من وصوله + +قم بتشغيله مرة واحدة، ثم افتح **Observe → Sessions** واختر بيئتك. يظهر تشغيلك كتتبع معاد بناؤه. + +إذا لم يصل شيء، أكد أن الآلة متصلة باستخدام `failproofai config --status`. + + + عدد الرموز وما يتم تسجيله وخطوات سير العمل والاسترجاع والخيارات والمشاكل الشائعة. + \ No newline at end of file diff --git a/docs/ar/start/quickstarts/pydantic-ai.mdx b/docs/ar/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..3028f5003 --- /dev/null +++ b/docs/ar/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "ثبّت وأدرج وشاهد أول تتبع لك." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +ثلاث خطوات للوصول إلى أول تتبع Pydantic AI. للأدوات والمحاولات الجديدة والبث والخيارات، انظر [الدليل الكامل](/ar/start/integrations/pydantic-ai). + +## التثبيت + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## الإدراج + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + يجب أن يعمل `instrument()` **قبل** أن تقوم بإنشاء `Agent`. تُضاف الإمكانية عند الإنشاء، لذلك الوكيل المبني مسبقاً لن يسجل أي شيء — بدون أخطاء، لأن لا شيء حدث بشكل خاطئ. هذا هو السبب الأكثر شيوعاً لتتبع فارغ مع هذا المحول، والوكلاء في نطاق الوحدة هم حيث يحدث المشكلة: استورد failproofai_sdk واستدعِ `instrument()` قبل استيراد الوحدة التي تبنيهم. + + +## تحقق من وصوله + +شغّله مرة واحدة، ثم افتح **Observe → Sessions** واختر بيئتك. يظهر تشغيلك كتتبع معاد بناؤه. + +إذا لم يصل شيء، تأكد من اتصال الجهاز بـ `failproofai config --status`. + + + ما يتم تسجيله والأدوات والمحاولات الجديدة والبث وتسمية الامتدادات والخيارات والمشاكل الشائعة. + \ No newline at end of file diff --git a/docs/de/index.mdx b/docs/de/index.mdx index ea94372ad..341f2856d 100644 --- a/docs/de/index.mdx +++ b/docs/de/index.mdx @@ -1,41 +1,41 @@ --- -title: "Mach deinen Agenten ausfallsicher" -description: "Observability und Durchsetzung für jede Umgebung, in der deine Agenten laufen — Coding-CLIs, Chat-Gateways, selbstgehostete Assistenten und eigene instrumentierte Agenten." +title: "Machen Sie Ihren Agenten fehlersicher" +description: "Observability und Durchsetzung für jede Harness, in der Ihre Agenten laufen — Coding-CLIs, Chat-Gateways, selbst gehostete Assistenten und Ihre eigenen instrumentierten Agenten." icon: "shield-check" --- -Failproof AI hilft Teams dabei zu verstehen, was Agenten getan haben, herauszufinden, wo sie gescheitert sind, und Schutzmaßnahmen einzurichten, bevor dasselbe Verhalten erneut auftritt. +Failproof AI hilft Teams dabei zu verstehen, was Agenten getan haben, wo sie gescheitert sind, und Sicherheitsmechanismen zu implementieren, bevor dasselbe Verhalten erneut auftritt. -Ein **Harness** ist die Umgebung, in der dein Agent tatsächlich ausgeführt wird. Failproof AI unterstützt 12 davon — Coding-CLIs wie Claude Code und Codex, Chat-Gateways wie Hermes, selbstgehostete Assistenten wie OpenClaw — und dieselben Ereignisse, dieselben Richtlinien und dieselbe Sitzungshistorie gelten für alle. Agenten ohne Harness melden sich über das [Python SDK](/de/reference/custom-agents) an, das sie verfolgt und prüft; die Durchsetzung einer Richtlinie dort erfordert einen Hook in deiner eigenen Laufzeitumgebung. +Eine **Harness** ist das, in dem Ihr Agent tatsächlich ausgeführt wird. Failproof AI bindet 12 davon ein — Coding-CLIs wie Claude Code und Codex, Chat-Gateways wie Hermes, selbst gehostete Assistenten wie OpenClaw — und dieselben Events, dieselben Policies und dieselbe Session-Historie gelten für alle. Agenten ohne Harness berichten über das [Python SDK](/de/reference/custom-agents), das sie trackt und auditiert; um dort eine Policy durchzusetzen, wird ein Hook in Ihrer eigenen Runtime benötigt. - Nutze die Skill-Funktion, um dein Projekt zu instrumentieren, es zu verbinden und zu überprüfen, dass Agenten-Logs ankommen. + Nutzen Sie die Skill, um Ihr Projekt zu instrumentieren, es zu verbinden und zu überprüfen, ob Agent-Logs ankommen. - Analysiere, frage ab, erstelle Dashboards und führe Audits in natürlicher Sprache auf deinen Agenten-Logs durch. + Analysieren, abfragen, Dashboards erstellen und Audits in natürlicher Sprache auf Ihren Agent-Logs durchführen. - Verfolge Modellaufrufe, Tools, Fehler, menschliche Eingaben, Latenz und Richtlinienentscheidungen in einer einzigen Sitzung. + Modellaufrufe, Tools, Fehler, Benutzereingaben, Latenz und Policy-Entscheidungen in einer einzigen Session nachverfolgen. - Prüfe eine definierte Menge von Sitzungen, überprüfe evidenzbasierte Befunde und verfolge die Behebung als Issues. + Eine definierte Menge von Sessions auditieren, beleggestützte Findings prüfen und die Behebung als Issues verfolgen. - Wandle einen bekannten Fehlerfall in eine Richtlinie um, beobachte ihre Wirkung und setze sie in deiner gesamten Flotte ein. + Einen bekannten Fehlerfall in eine Policy umwandeln, deren Auswirkung beobachten und sie in Ihrer gesamten Fleet deployen. -> **Sitzung → Audit → Befund → Issue → Richtlinie**
-> Verfolge, was passiert ist, finde den Fehler, steuere die Reaktion und verhindere dasselbe Verhalten in zukünftigen Ausführungen. +> **Session → Audit → Finding → Issue → Policy**
+> Nachvollziehen, was passiert ist, den Fehler finden, die Reaktion steuern und dasselbe Verhalten in zukünftigen Läufen verhindern. -## Hier starten +## Hier beginnen -Wenn du deinen ersten instrumentierten Agenten bereitstellst, beginne mit dem [Quickstart](/de/start/quickstart). Wenn bereits Daten eingehen, öffne [Sessions](/de/sessions/overview) und untersuche einen echten Durchlauf, bevor du Audits oder Richtlinien konfigurierst. +Wenn Sie Ihren ersten instrumentierten Agenten deployen, starten Sie mit dem [Quickstart](/de/start/quickstart). Wenn bereits Daten eintreffen, öffnen Sie [Sessions](/de/sessions/overview) und untersuchen Sie einen echten Lauf, bevor Sie Audits oder Policies konfigurieren. - Durchlaufe den End-to-End-Workflow von der Erfassung bis zur sicher eingesetzten Richtlinie. + Den End-to-End-Workflow von der Erfassung bis zu einer sicher deployten Policy durchführen. \ No newline at end of file diff --git a/docs/de/policies/deploy.mdx b/docs/de/policies/deploy.mdx index 9ec02976a..cde4384ab 100644 --- a/docs/de/policies/deploy.mdx +++ b/docs/de/policies/deploy.mdx @@ -1,47 +1,51 @@ --- -title: "Richtlinien deployen" -description: "Eine geprüfte Richtlinienversion auf die vorgesehenen Maschinen ausrollen." +title: "Richtlinien bereitstellen" +description: "Eine geprüfte Richtlinienversion auf den vorgesehenen Maschinen ausrollen." icon: "cloud-upload" --- -Ein Deployment verbindet eine oder mehrere Richtlinienversionen mit einer Zielgruppe eingetragener Maschinen. +Eine Bereitstellung verbindet eine oder mehrere Richtlinienversionen mit einer Zielgruppe eingetragener Maschinen. -## Ein Deployment anwenden +## Eine Bereitstellung anwenden - 1. Gehe zu **Admin → Durchsetzung**, suche die Maschine und klappe ihre Zeile auf. + 1. Gehe zu **Admin → Durchsetzung**, finde die Maschine und klappe ihre Zeile aus. 2. Wähle **Bearbeiten**, füge die geprüfte Richtlinienversion hinzu und wähle **Beobachten** oder den durchsetzenden Effekt. - 3. Wende die Änderung an, warte dann auf das nächste Check-in der Maschine und bestätige ihren Deployment- und Coverage-Status. - 4. Gehe zu **Beobachten → Richtlinie**, um Live-Entscheidungen einzusehen. + 3. Wende die Änderung an, warte dann auf den nächsten Check-in der Maschine und bestätige ihren Bereitstellungs- und Abdeckungsstatus. + 4. Gehe zu **Beobachten → Richtlinie**, um Live-Entscheidungen zu prüfen. - ![Der Maschinen-Deployment-Editor mit Richtlinienversionen, Durchsetzungs- und Beobachtungseffekten sowie der Aktion zum Anwenden des Deployments.](/images/dashboard/enforcement-editor.png) + ![Der Maschinen-Bereitstellungseditor mit Richtlinienversionen, Durchsetzen- und Beobachten-Effekten sowie der Aktion zur Anwendung der Bereitstellung.](/images/dashboard/enforcement-editor.png) - Cloud-Deployment-Endpunkte sind bewusst nicht als gewöhnliche `fp`-Befehle verfügbar. Überprüfe die Maschine lokal und deploye dann über das Dashboard: + Bereitstellen über die CLI mit `fp fleet`. Überprüfe die resultierende Konfiguration, bevor du sie anwendest – `deploy` gibt den vollständigen Plan aus und fragt **nur in einem interaktiven Terminal ohne `--json`** nach. Mit `--json`, mit `--yes` oder bei umgeleitetem stdin (ein CI-Schritt, ein Skript, ein Agent) wird die Konfiguration sofort ohne Plan und ohne Bestätigung angewendet – führe daher zuerst `fp fleet show ` aus, wenn du prüfen möchtest: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - Verwende nach dem Deployment `fp sessions --env production --since 24h` und `fp events --event-type hook_completed`, um zu überprüfen, ob Aktivität die Cloud erreicht. + `fp fleet diff ` zeigt Soll-/Ist-Zustand (eine Maschine gilt als `behind`, 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 die betreffende Generation eine inzwischen deaktivierte oder gelöschte Richtlinie referenziert. + + Überprüfe die Maschine selbst mit `failproofai config --status` und nutze nach der Bereitstellung `fp sessions --env production --since 24h` sowie `fp events --event-type hook_completed`, um sicherzustellen, dass Aktivitäten die Cloud erreichen. - - Deploye eine geprüfte Version – keinen veränderbaren Entwurf – und beginne mit einer Nicht-Produktionsmaschine oder einer kleinen Gruppe, deren Sitzungen du einsehen kannst. + + Stelle eine geprüfte Version bereit, keinen veränderlichen Entwurf. Beginne mit einer Maschine außerhalb der Produktion oder einer kleinen Gruppe, deren Sitzungen du einsehen kannst. - Überprüfe Treffer, Begründungen, betroffene Tools und Falsch-Positive, ohne die Arbeit zu blockieren. + Prüfe Treffer, Begründungen, betroffene Tools und Fehlerkennungen, ohne die Arbeit zu blockieren. - - Stufe hoch, sobald beobachtete Treffer unsichere Aktionen von gültigen trennen, und bestätige dann, dass jede vorgesehene Maschine das Deployment abgerufen hat und Entscheidungen meldet. + + Stufe die Richtlinie hoch, nachdem beobachtete Treffer unsichere Aktionen von gültigen getrennt haben. Bestätige dann, dass jede vorgesehene Maschine die Bereitstellung abgerufen hat und Entscheidungen meldet. -Maschinen benötigen die Berechtigung `policies:pull`. Das Ereignis-Reporting wird separat durch `events:add` gesteuert; überprüfe beides, wenn du Cloud-Analyse und Durchsetzung erwartest. +Maschinen benötigen die Berechtigung `policies:pull`. Die Ereignisberichterstattung wird separat durch `events:add` gesteuert; überprüfe beides, wenn du Cloud-Analyse und -Durchsetzung erwartest. - Die Verwaltung der Durchsetzung ist ein administrativer Cloud-Workflow. Behandle Root-Only-Durchsetzungsrouten nicht als gewöhnliche Kunden-Endpunkte unter `/v1`. + Das Enforcement-Management ist ein administrativer Cloud-Workflow. Behandle rein administrative Durchsetzungsrouten nicht wie gewöhnliche Kunden-Endpunkte unter `/v1`. \ No newline at end of file diff --git a/docs/de/policies/editor.mdx b/docs/de/policies/editor.mdx index 146e8a99d..77ab4898a 100644 --- a/docs/de/policies/editor.mdx +++ b/docs/de/policies/editor.mdx @@ -1,47 +1,49 @@ --- title: "Policy-Editor" -description: "Erstellen und überarbeiten Sie versionierte Policies aus einem bestätigten Fehlerfall." +description: "Erstelle und überarbeite versionierte Richtlinien auf Basis eines bestätigten Fehlermusters." icon: "file-pen-line" --- -Verwenden Sie den Policy-Editor, um einen Fund oder ein Problem in eine einsatzfähige Regel umzuwandeln. Halten Sie das Erstellen und das Ausrollen voneinander getrennt, damit ein Entwurf das Live-Verhalten nicht unbemerkt verändern kann. +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. -Wenn ein Problem ein wiederholbares Aktionsmuster aufweist, öffnen Sie es unter **Analyze → issues** und wählen Sie **generate policy**. Failproof AI erläutert zunächst, ob sich das Problem als Policy ausdrücken lässt, und überträgt dann den geprüften Anlass sowie den Kontext des Funds in den Editor. Der generierte Quellcode bleibt ein Entwurf, bis Sie ihn veröffentlichen. +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 Policy-Version veröffentlichen +## Eine Richtlinienversion veröffentlichen - 1. Gehen Sie zu **Admin → policy editor** und beschreiben Sie unter **compose** den Fehlerfall, oder fügen Sie den JavaScript-Policy-Quellcode ein. - 2. Validieren Sie den Quellcode und beheben Sie alle gemeldeten Fehler. - 3. Geben Sie die Policy-Identität ein und veröffentlichen Sie sie. Verwenden Sie anschließend **library**, um Versionen zu vergleichen oder zu deaktivieren. - 4. Wählen Sie **enforcement**, wenn die Version für ein maschinelles Rollout bereit ist. + 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. - ![Die Compose-Ansicht des Policy-Editors mit Policy-Identität, KI-gestütztem Entwurf, Quellcode-Validierung und Veröffentlichungssteuerung.](/images/dashboard/policy-editor.png) + ![Die Compose-Ansicht des Policy-Editors mit Richtlinienidentität, KI-gestützter Erstellung, Quellvalidierung und Veröffentlichungssteuerung.](/images/dashboard/policy-editor.png) - Die Cloud CLI veröffentlicht keine Policy-Versionen. Validieren Sie den Quellcode lokal, bevor Sie ihn in den Editor kopieren: + 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: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - Veröffentlichen Sie die geprüfte Version über **Admin → policy editor**. + 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`. ## Checkliste für die Erstellung -1. Benennen Sie den Fehlerfall in operativer Sprache. -2. Wählen Sie die Hook-Events und Tools aus, die ausreichend Kontext für eine Entscheidung liefern. -3. Formulieren Sie die engstmögliche Bedingung, die unsicheres Verhalten erkennt. -4. Geben Sie eine Begründung zurück, die dem Agent oder Operator mitteilt, wie er als Nächstes vorgehen soll. -5. Fügen Sie Beispiele hinzu, die übereinstimmen sollen, sowie Beispiele, die weiterhin erlaubt bleiben müssen. -6. Speichern Sie eine neue Version und fordern Sie eine Überprüfung an. +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. -Verwenden Sie `instruct`, wenn der Agent sicher korrigieren kann. Verwenden Sie `deny`, wenn das Zulassen der Aktion ein inakzeptables oder unumkehrbares Risiko darstellen würde. +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. - Policy-Versionen sind unveränderliche Deployment-Eingaben. Das Bearbeiten eines Entwurfs erstellt eine neue Version; dabei sollte die bereits Maschinen zugewiesene Version nicht überschrieben werden. + 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 diff --git a/docs/de/reference/cloud-cli.mdx b/docs/de/reference/cloud-cli.mdx index bea0d6deb..a8ad37f39 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 zum Abfragen und Verwalten 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 zu untersuchen sowie Audits, Findings, Issues, Alerts, Schlüssel, Benutzer, Abfragen und Einstellungen zu verwalten. Nutze [`failproofai`](/de/reference/failproof-cli) für lokale Hooks, Richtlinien, Capture und die Geräteregistrierung. +Verwende `fp`, um Cloud-Telemetrie einzusehen, cloudseitig verwaltete Durchsetzung (Richtlinien, Fleet-Deployments, Guardrail-Entscheidungen) zu verwalten sowie Audits, Befunde, Issues, Alerts, Schlüssel, Benutzer, Abfragen und Einstellungen zu administrieren. Nutze [`failproofai`](/de/reference/failproof-cli) für lokale Hooks, Richtlinien, Aufzeichnung und Machine-Enrollment. -Installiere die veröffentlichte Cloud CLI als isoliertes Tool: +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` aus, um die Terminal-Hilfe anzuzeigen. +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` aus, um die Termi | Befehl | Zweck | Optionen | | --- | --- | --- | -| `fp login` | Anmelden mit einem per E-Mail zugesandten Einmalcode und Auswählen einer Organisation. | `--email`, `-e`; `--org`; `--force` | +| `fp login` | Anmelden 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 auf oberster Befehlsebene anzeigen. | — | +| `fp help` | Hilfe zu Befehlen auf oberster Ebene anzeigen. | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,30 +57,34 @@ fp whoami fp events [OPTIONS] ``` -Listet einzelne Agenten-Ereignisse auf. Der standardmäßige Light-Feed schließt rohe Payloads aus; verwende `--full` nur für eine begrenzte Untersuchung. +Listet einzelne Agent-Ereignisse auf. Der standardmäßige einfache Feed schließt Raw-Payloads aus; verwende `--full` nur für eine begrenzte Untersuchung. | Option | Beschreibung | | --- | --- | | `--limit`, `-n ` | Maximale Gesamtzahl der 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 ` | Ereignistypfilter; Werte wiederholen oder kommagetrennt angeben. | -| `--agent-id ` | Agentenfilter; Werte wiederholen oder kommagetrennt angeben. | -| `--session-id ` | Sitzungsfilter; Werte wiederholen oder kommagetrennt angeben. | -| `--search ` | Payload-Textsuche; wiederholbar, ein beliebiger Begriff muss übereinstimmen. | -| `--order asc\|desc` | Zeitliche Reihenfolge. Standard: neueste zuerst. | -| `--all` | Automatisch bis zu `--limit` paginieren. | -| `--cursor ` | Ab einem undurchsichtigen Cursor fortsetzen. | -| `--page-size ` | Zeilen pro Anfrage mit `--all`; Maximum `200`. | -| `--full` | Rohe Payloads über den aufwändigeren Ereignis-Endpunkt einschließen. | -| `--fields ` | Nur ausgewählte Felder zurückgeben; die Anforderung von `payload` aktiviert den vollständigen Modus. | +| `--env ` | Umgebungsfilter; wiederholbar oder kommagetrennte Werte. | +| `--event-type ` | Ereignistypfilter; wiederholbar oder kommagetrennte Werte. | +| `--agent-id ` | Agent-Filter; wiederholbar oder kommagetrennte Werte. | +| `--session-id ` | Sitzungsfilter; wiederholbar oder kommagetrennte Werte. | +| `--search ` | Volltextsuche im Payload; wiederholbar, ein beliebiger Begriff reicht. | +| `--order asc\|desc` | Zeitreihenfolge. Standard: neueste zuerst. | +| `--all` | Automatische Paginierung bis zu `--limit`. | +| `--cursor ` | Fortsetzen ab einem undurchsichtigen Cursor. | +| `--page-size ` | Zeilen pro Anfrage bei `--all`; maximal `200`. | +| `--full` | Raw-Payloads über den umfangreicheren Ereignis-Endpunkt einschließen. | +| `--fields ` | Nur ausgewählte Felder zurückgeben; durch Angabe von `payload` wird der Full-Modus aktiviert. | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` + + `--all` paginiert **bis zu `--limit`**, was standardmäßig **50** ist — daher stoppt `--all` allein 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 ist. + + ### Sitzungen ```text @@ -92,16 +96,16 @@ fp sessions [OPTIONS] | `--limit`, `-n ` | Maximale Gesamtzahl der 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 ` | Ab einem undurchsichtigen Cursor fortsetzen. | -| `--page-size ` | Zeilen pro Anfrage mit `--all`; Maximum `200`. | +| `--env ` | Umgebungsfilter; wiederholbar oder kommagetrennte Werte. | +| `--status ` | `done`, `error` oder `timeout`; wiederholbar oder kommagetrennte Werte. | +| `--agent-id ` | Sitzungen einschließen, an denen ein ausgewählter Agent beteiligt ist. | +| `--session-id ` | Sitzungsfilter; wiederholbar oder kommagetrennte Werte. | +| `--all` | Automatische Paginierung bis zu `--limit`. | +| `--cursor ` | Fortsetzen ab einem undurchsichtigen Cursor. | +| `--page-size ` | Zeilen pro Anfrage bei `--all`; maximal `200`. | | `--fields ` | Nur ausgewählte Felder zurückgeben. | -| `--full-ids` | Sitzungs-IDs in der Terminal-Ausgabe nicht kürzen. | -| `--agents` | Den Agenten-Kader für Multi-Agenten-Sitzungen ausklappen. | +| `--full-ids` | Sitzungs-IDs in der Terminalausgabe nicht kürzen. | +| `--agents` | Die Agent-Liste für Multi-Agent-Sitzungen aufklappen. | ### Auswertungen @@ -114,12 +118,12 @@ fp evals [OPTIONS] | `--aggregate` | Gesamtwerte und Statistiken pro Score anstelle einzelner Auswertungen anzeigen. | | `--limit`, `-n ` | Maximale Listenzeilen. Standard: `50`. | | `--since`, `--from`, `--to` | Zeitbereich auswählen. | -| `--env`, `--status`, `--agent-id`, `--session-id` | Auf genau einen Wert pro Filter einschränken. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Auf einen exakten Wert pro Filter einschränken. | | `--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. | -| `--scores-full` | Alle Scores in der Terminal-Ausgabe anzeigen. | +| `--scores-full` | Alle Scores in der Terminalausgabe anzeigen. | ### Fehler @@ -132,9 +136,9 @@ fp errors [OPTIONS] | `--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` | Fehlerpopulation einschränken. | | `--search ` | Payload-Text durchsuchen; wiederholbar. | -| `--order asc\|desc` | Zeitliche Reihenfolge. | +| `--order asc\|desc` | Zeitreihenfolge. | | `--all`, `--cursor`, `--page-size` | Listenpaginierung steuern. | | `--fields ` | Nur ausgewählte Felder zurückgeben. | | `--full-ids` | Vollständige Sitzungs-IDs anzeigen. | @@ -144,8 +148,8 @@ fp errors [OPTIONS] | Befehl | Zweck | | --- | --- | | `fp usage` | Nutzung für das aktuelle Abrechnungsfenster anzeigen. | -| `fp list envs` | Beobachtete Umgebungen auflisten. | -| `fp list agents` | Beobachtete Agenten-IDs auflisten. | +| `fp list envs` | Erkannte Umgebungen auflisten. | +| `fp list agents` | Erkannte Agent-IDs auflisten. | | `fp list event_types` | Ereignistypen auflisten. | | `fp list score_filters` | Score-Schlüssel für Auswertungen auflisten. | | `fp list models` | Modellnamen auflisten. | @@ -158,8 +162,8 @@ fp errors [OPTIONS] | Befehl | Zweck | | --- | --- | | `fp orgs list` | Zugängliche Organisationen auflisten. | -| `fp orgs switch [SLUG]` | Eine aktive Organisation speichern; wird bei Auslassung abgefragt. | -| `fp orgs current` | Die aktive Organisation anzeigen. | +| `fp orgs switch [SLUG]` | Eine aktive Organisation speichern; bei Auslassung wird nachgefragt. | +| `fp orgs current` | Aktive Organisation anzeigen. | | `fp orgs perms` | Eigene Berechtigungen in der aktiven Organisation anzeigen. | ### API-Schlüssel @@ -173,7 +177,7 @@ fp errors [OPTIONS] | `fp keys regenerate NAME` | Das Geheimnis rotieren und den Ersatz einmalig anzeigen. | `--yes`, `-y` | | `fp keys disable NAME` | Einen Schlüssel dauerhaft widerrufen. | `--yes`, `-y` | -Berechtigungs-Tokens verwenden das Format `resource:action`, z. B. `events:add`. Wiederhole `--add`, trenne Tokens durch Kommas oder verwende Punkt-Notation wie `events:read.add`. +Berechtigungs-Tokens verwenden das Format `resource:action`, z. B. `events:add`. `--add` kann wiederholt, Tokens kommagetrennt oder mit gepunkteten Aktionen wie `events:read.add` angegeben werden. ### Abfragen @@ -185,7 +189,7 @@ Berechtigungs-Tokens verwenden das Format `resource:action`, z. B. `events:add`. | `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 @@ -204,7 +208,7 @@ Berechtigungs-Tokens verwenden das Format `resource:action`, z. B. `events:add`. | --- | --- | --- | | `fp settings list` | Organisationseinstellungen und aktuelle Werte auflisten. | — | | `fp settings schema` | Zulässige Werte und Beschreibungen anzeigen. | — | -| `fp settings set KEY` | Eine vorhandene Einstellung ändern. | genau eine von `--value`, `--json-value`, `--file`; optional `--yes`, `-y` | +| `fp settings set KEY` | Eine bestehende Einstellung ändern. | genau eines von `--value`, `--json-value`, `--file`; optional `--yes`, `-y` | ### Alerts @@ -213,7 +217,7 @@ Berechtigungs-Tokens verwenden das Format `resource:action`, z. B. `events:add`. | `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 update NAME` | Einen Alert aktualisieren oder umbenennen. | Create-Optionen plus `--name`; `--yes`, `-y` | | `fp alerts delete NAME` | Einen Alert löschen. | `--yes`, `-y` | | `fp alerts test NAME` | Eine Testbenachrichtigung senden. | `--channels`; `--yes`, `-y` | @@ -224,25 +228,25 @@ Alert-Schweregrade sind `info`, `warning` und `critical`. Trigger-Arten sind `me | Befehl | Zweck | Optionen | | --- | --- | --- | | `fp audits list` | Audits auflisten. | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | Eine Audit-Definition und ihren Status anzeigen. | — | -| `fp audits create NAME` | Ein Audit erstellen und sofort die erste Ausführung in die Warteschlange stellen. | 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` | Ein Audit, seine Findings und den Ausführungsverlauf löschen. | `--yes`, `-y` | -| `fp audits run NAME` | Eine manuelle Ausführung in die Warteschlange stellen. | — | +| `fp audits show NAME` | Eine Audit-Definition und ihren Zustand anzeigen. | — | +| `fp audits create NAME` | Ein Audit erstellen und sofort den ersten Durchlauf in die Warteschlange stellen. | Siehe [Create-Optionen](#audit-create-options). | +| `fp audits edit NAME` | Audit-Einstellungen ersetzen, ohne nicht angegebene Werte zu verändern. | Definitions-Optionen für Create; `--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 Durchlauf in die Warteschlange stellen. | — | | `fp audits runs NAME` | Ausführungsverlauf auflisten. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | Den Kurztext und den Abrufstatus der Referenz-URLs anzeigen. | — | -| `fp audits context-set NAME` | Den Kurztext oder Referenz-URLs ändern. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-show NAME` | Das Briefing und den Abrufstatus der Referenz-URLs anzeigen. | — | +| `fp audits context-set NAME` | Das Briefing oder Referenz-URLs ändern. | `--text`; `--text-file`; `--url`; `--clear-urls` | | `fp audits context-refresh NAME` | Referenz-URLs erneut abrufen. | — | -| `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 findings` | Befunde auflisten. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | +| `fp audits finding FINDING_ID` | Einen Befund und seine Beweise anzeigen. | — | +| `fp audits ack FINDING_ID` | Einen Befund 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` | Ein Finding als behoben markieren, ohne künftige Unterdrückung. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | Ein Finding in die aktive Warteschlange zurückgeben und die Unterdrückung aufheben. | — | -| `fp audits assign FINDING_ID` | Den Verantwortlichen für ein Finding festlegen. | erforderlich: `--to ` | +| `fp audits resolve FINDING_ID` | Einen Befund als behoben markieren, ohne zukünftige Unterdrückung. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | Einen Befund in die aktive Warteschlange zurückführen und Unterdrückung aufheben. | — | +| `fp audits assign FINDING_ID` | Den Verantwortlichen für einen Befund festlegen. | Pflichtangabe `--to ` | -#### Audit-Erstellungsoptionen +#### Audit-Create-Optionen ```bash fp audits create checkout-reliability \ @@ -257,27 +261,27 @@ fp audits create checkout-reliability \ | Option | Beschreibung | | --- | --- | -| `--file ` | Definition auf JSON basieren oder `-` für stdin verwenden. Explizite Flags überschreiben Dateiwerte. | -| `--description ` | Die Fehlerfrage oder den Zweck angeben. | -| `--enabled` / `--disabled` | Planung aktiviert oder deaktiviert starten. Standard: aktiviert. | +| `--file ` | Definition auf JSON basieren, oder `-` für stdin verwenden. Explizite Flags überschreiben Dateiwerte. | +| `--description ` | Die Fehlerfrage oder den Zweck beschreiben. | +| `--enabled` / `--disabled` | Zeitplanung aktivieren oder deaktivieren. Standard: aktiviert. | | `--schedule-interval-secs ` | `3600`–`604800`. Standard: `86400`. | -| `--schedule-anchor ` | Feste UTC-Phase im ISO 8601-Format. Standard: nächstes 09:00 UTC. | +| `--schedule-anchor ` | Feste UTC-Phase 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 rollendes 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 kommagetrennt. | | `--llm` / `--no-llm` | Agentische Analyse aktivieren oder deaktivieren. Standard: aktiviert. | -| `--top-k ` | `1`–`500` Findings behalten. Standard: `50`. | -| `--sensitivity low\|medium\|high` | Meldeempfindlichkeit festlegen. Standard: `medium`. | +| `--top-k ` | `1`–`500` Befunde behalten. Standard: `50`. | +| `--sensitivity low\|medium\|high` | Berichtssensitivität festlegen. Standard: `medium`. | | `--channels ''` | Array der Benachrichtigungskanäle. | -| `--text ` | Inline-Kurztext, maximal 8.192 Zeichen. | -| `--text-file ` | Kurztext aus einer Datei lesen; schließt sich mit `--text` gegenseitig aus. | +| `--text ` | Inlines Briefing, maximal 8.192 Zeichen. | +| `--text-file ` | Briefing aus einer Datei lesen; schließt sich gegenseitig mit `--text` aus. | | `--url ` | Eine öffentliche HTTPS-Referenz hinzufügen; bis zu fünfmal wiederholbar. | -Kontext bei der Erstellung angeben, wenn die erste Ausführung ihn benötigt. Die Erstellung schreibt Definition und Kontext gemeinsam fest, bevor die geplante Ausführung beginnt. +Füge Kontext während der Erstellung hinzu, wenn der erste Durchlauf ihn benötigt. Die Erstellung schreibt die Definition und den Kontext gemeinsam fest, bevor der eingereihte Durchlauf beginnt. - `fp audits run` ist asynchron. Überprüfe `fp audits runs NAME` so lange, bis die neueste Ausführung erfolgreich war oder fehlgeschlagen ist, bevor du die Findings liest. + `fp audits run` ist asynchron. Warte mit `fp audits runs NAME`, bis der letzte Durchlauf erfolgreich abgeschlossen ist oder fehlschlägt, bevor du die Befunde liest. ### Issues @@ -287,15 +291,15 @@ Kontext bei der Erstellung angeben, wenn die erste Ausführung ihn benötigt. Di | `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 alert-verknüpftes Issue öffnen. | erforderlich: `--summary`; optional: `--title`, `--alert-id`, `--severity` | +| `fp issues open` | Ein manuelles oder alert-verknüpftes Issue öffnen. | Pflichtangabe `--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, um sie zu entfernen. | wiederholbares `--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 subscribe INCIDENT_ID` | Dich 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`. @@ -307,11 +311,49 @@ Gültige Issue-Zustände sind `firing`, `acknowledged` und `resolved`. Schweregr | `fp agent health` | Verfügbarkeit und Konfiguration des Assistenten prüfen. | — | | `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 fehlt. | `--chat`; `--model`; `--page-context` | +| `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` | Ein gespeichertes Gespräch anzeigen. | — | -| `fp agent rename CHAT_ID` | Ein Gespräch umbenennen. | erforderlich: `--title` | +| `fp agent rename CHAT_ID` | Ein Gespräch umbenennen. | Pflichtangabe `--title` | | `fp agent delete CHAT_ID` | Ein Gespräch löschen. | `--yes`, `-y` | +### Policies + +Cloudseitig verwaltete Richtlinienversionen. **Nur für Sitzungen** — 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 absichtlich nicht in `/v1` vorhanden sind. + +| Befehl | Zweck | Optionen | +| --- | --- | --- | +| `fp policies list` | Richtlinienversionen auflisten. | `--json` | +| `fp policies show POLICY_ID` | Eine Richtlinie mit ihrem Quellcode anzeigen. | — | +| `fp policies publish NAME PATH` | Eine Version aus einer lokalen `.mjs`-Datei erstellen. | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | Sie jedem Deployment hinzufügen, aus dem sie entfernt wurde, und dabei in jedem eine neue Generation prägen. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | Sie aus jedem Deployment entfernen, das sie enthält, und dabei in jedem eine neue Generation prägen. | `--yes`, `-y` | +| `fp policies delete POLICY_ID` | Eine Richtlinienversion löschen. | `--yes`, `-y` | +| `fp policies test PATH` | Eine Richtlinie lokal gegen einen synthetischen Kontext testen. Wendet den `match`-Filter jeder Richtlinie an; eine Richtlinie, die das gegebene Ereignis/Tool nicht abdeckt, wird als `skipped` gemeldet statt ausgeführt. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | +| `fp policies compose PROMPT` | Eine Richtlinie mit dem Assistenten entwerfen. Benötigt `policies:write`. | — | + +### Fleet + +Welche Machines welche Richtlinien ausführen. **Nur für Sitzungen**, aus demselben Grund wie oben. + +| Befehl | Zweck | Optionen | +| --- | --- | --- | +| `fp fleet list` | Eingeschriebene Machines und ihre Deployment-Generation auflisten. | — | +| `fp fleet show MACHINE_ID` | Den aktuell von einer Machine ausgeführten Richtliniensatz anzeigen. | — | +| `fp fleet deploy MACHINE_ID` | **Ersetzt den gesamten Richtliniensatz der Machine.** Gibt den Plan aus und fragt nur auf einem interaktiven Terminal ohne `--json` nach. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | Eine Machine mit einem anderen Deployment vergleichen. | — | +| `fp fleet history MACHINE_ID` | Vergangene Deployments für eine Machine anzeigen. | — | +| `fp fleet rollback MACHINE_ID` | Ein vorheriges Deployment wiederherstellen. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | Einer Machine einen lesbaren Namen geben. | Pflichtangabe `--name` | + +### Guardrails + +Was die Durchsetzung tatsächlich getan hat. **Nur für Sitzungen**, aus demselben Grund wie oben. + +| Befehl | Zweck | Optionen | +| --- | --- | --- | +| `fp guardrails summary` | Abdeckung, blockierte/ausgewertete Gesamtwerte, eine Deny-Sparkline und die Tabelle pro Richtlinie. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Entscheidungen im Zeitfenster zusammengefasst, summiert über alle Richtlinienquellen. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | + ## Globale Flags | Flag | Beschreibung | @@ -319,13 +361,13 @@ Gültige Issue-Zustände sind `firing`, `acknowledged` und `resolved`. Schweregr | `--json` | Maschinenlesbares JSON ausgeben. | | `--base-url ` | Ein selbst gehostetes oder Entwicklungs-Dashboard verwenden. | | `--org ` | Eine Organisation für diesen Aufruf auswählen. | -| `--token ` | Das gespeicherte Benutzersitzungs-Token überschreiben. | +| `--token ` | Das gespeicherte Benutzersitzungstoken überschreiben. | | `--api-key ` | Automatisierung mit einem API-Schlüssel authentifizieren; wird nie gespeichert. | | `--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. | +| `--version` | Die Version ausgeben und beenden. | | `--help`, `-h` | Hilfe anzeigen. | `--api-key` ist für die Automatisierung vorgesehen. Anmeldung, Organisationswechsel und Assistentenbefehle erfordern eine Benutzersitzung. @@ -334,18 +376,24 @@ Gültige Issue-Zustände sind `firing`, `acknowledged` und `resolved`. Schweregr | Variable | Entsprechung oder Zweck | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | Das aktuelle CLI-Konfigurationsverzeichnis verschieben. | -| `AGENTEYE_ANALYTICS_DISABLED` oder `DO_NOT_TRACK` | Anonyme CLI-Analysen deaktivieren. | +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `FP_API_KEY` | `--api-key` | +| `FP_JSON` | `--json` | +| `FP_INSECURE` | `--insecure` | +| `FP_HOME` | Konfigurationsverzeichnis des CLI 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 `AGENTEYE_ORG` auswählen. +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 nie — das CLI deklariert `FP_*` (`fp_cli/app.py`), und eine unbekannte Variable ist kein Fehler. Das Setzen von `AGENTEYE_DASHBOARD_URL` richtet das CLI nicht neu aus; es wird ignoriert und der Befehl läuft stillschweigend gegen das gespeicherte Dashboard. + + `AGENTEYE_HOME` und `AGENTEYE_ENVIRONMENT` existieren weiterhin, gehören aber zum **Collector und dem Telemetrie-SDK**, nicht zu diesem CLI. + - Befehle, die Konfigurationen löschen, widerrufen, unterdrücken, auflösen oder ersetzen, fordern standardmäßig zur Bestätigung auf. Verwende `--yes` erst nach Überprüfung der aktiven Organisation und des Ziels. + Befehle, die Konfigurationen löschen, widerrufen, unterdrücken, auflösen oder ersetzen, fragen standardmäßig nach. Verwende `--yes` erst nach Überprüfung der aktiven Organisation und des Ziels. \ No newline at end of file diff --git a/docs/de/reference/custom-agents.mdx b/docs/de/reference/custom-agents.mdx index 27164accf..88bb99902 100644 --- a/docs/de/reference/custom-agents.mdx +++ b/docs/de/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- -title: "Benutzerdefinierte Agenten" -description: "Instrumentiere Traces von benutzerdefinierten Agenten, damit Failproof AI Ausführungen rekonstruieren und Fehler finden kann." +title: "Eigene Agenten" +description: "Konfiguration, der Event-Katalog, Korrelationsregeln und Zustellung für failproofai-sdk." icon: "python" --- -Instrumentiere Traces eines benutzerdefinierten Agenten mit `failproofai-sdk`, damit Failproof AI jeden Lauf rekonstruieren, sein Verhalten prüfen und belegbare Fehler finden kann. Das SDK schreibt strukturierte Ereignisse, die der Failproof-Daemon an Cloud weiterleitet. Es setzt Python 3.10 oder neuer voraus. +Was jede Einstellung, Methode und jedes Feld bewirkt. Wenn Sie zum ersten Mal instrumentieren, beginnen Sie mit der Anleitung — diese Seite dient zum Nachschlagen. -Tracing macht benutzerdefinierte Agenten beobachtbar und auditierbar. Um eine unsichere Aktion vor ihrer Ausführung zu verhindern, ist zusätzlich ein Enforcement-Hook in deiner Laufzeitumgebung erforderlich. + + + 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. + + - - Um Richtlinien in einer benutzerdefinierten Agenten-Umgebung durchzusetzen, [kontaktiere Failproof AI](mailto:support@befailproof.ai). Wir helfen dabei, die Modell-, Tool- und Lifecycle-Grenzen deiner Laufzeitumgebung auf Policy-Hooks abzubilden. - +Python 3.10 oder neuer. Keine Laufzeit-Abhängigkeiten. -
- -
- -## `failproofai-sdk` installieren - -Das SDK wird derzeit als privates Wheel vertrieben. Wende dich an deinen Failproof AI-Ansprechpartner, um die aktuelle Version und Zugang zum Download zu erhalten. +## Installation ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -Mit `uv` lade das Wheel zunächst herunter und führe `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl` aus. Fixiere das Wheel in einem privaten Artefakt-Repository oder einer Dependency-Lock-Datei. - -Das Paket wird als `failproofai-sdk` installiert und in Python als `failproofai` importiert. +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. ## Failproof-Daemon verbinden - 1. Gehe zu **Admin → Keys** und erstelle einen Schlüssel mit `events:add`. - 2. [Verbinde den Failproof-Daemon mit Cloud](/de/start/setup#connect-a-machine-to-cloud) auf der Agenten-Maschine. - 3. Führe eine instrumentierte Sitzung aus und suche dann deren genaue ID unter **Observe → Events**. - 4. Gehe zu **Observe → Sessions**, wähle dieselbe Umgebung und öffne den rekonstruierten Trace. + 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 dem Agenten-Rechner. + 3. Führen Sie eine instrumentierte Sitzung aus und suchen Sie deren 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-Agenten-Sitzung, rekonstruiert als Ausführungsgraph und geordneter Ereignis-Trace.](/images/dashboard/session-detail.png) + ![Eine eigene Python-Agenten-Sitzung, rekonstruiert als Ausführungsgraph und geordnete Event-Folge.](/images/dashboard/session-detail.png) ```bash @@ -51,102 +46,84 @@ Das Paket wird als `failproofai-sdk` installiert und in Python als `failproofai` -## Einen vollständigen Lauf instrumentieren - -Rufe `configure()` einmal beim Prozessstart auf. Jeder Ereignisaufruf ist keyword-only und erfordert eine stabile `session_id` und `agent_id`. +## Konfiguration ```python -import traceback -import uuid +import failproofai_sdk + +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -import failproofai +| Argument | Bedeutung | +| --- | --- | +| `environment` | Die Bezeichnung auf jedem Event — `production`, `staging`, `prod-eu`. Standard: `dev`. | +| `flush_interval` | Wie oft der Hintergrund-Thread auf die Festplatte schreibt, in Sekunden. Standard: `0.5`. | +| `base_dir` | Schreibziel. Standard ist der Spool des Daemons, was in der Regel das Richtige ist. | -failproofai.configure(environment="production") +Alternativ per Umgebungsvariable setzen: -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +| Variable | Bedeutung | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Setzt `environment` ohne Code-Änderung — für den Fall, dass die Bezeichnung zur Deployment-Umgebung 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 als Ausnahme auslösen statt sie nur zu protokollieren. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` lässt ein Framework-Kompatibilitätsproblem als Ausnahme auslösen statt nur eine Warnung auszugeben. | -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) + + **Kein Komma in `environment`.** Die Ingest-Komponente teilt dieses Feld an Kommas auf, um Filter zu erstellen, und überspringt jeden Event, dessen Bezeichnung ein Komma enthält — ein ganzer Lauf verschwindet dann lautlos. Schreiben Sie `prod-eu`, nicht `prod,eu`. -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + `configure(environment="prod,eu")` löst sofort eine Ausnahme aus. `AGENTEYE_ENVIRONMENT` kann das nicht — niemand ruft Sie zurück — daher wird einmalig eine Warnung ausgegeben und auf `dev` zurückgefallen. + + +Events werden im Speicher gepuffert 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. -Sende `agent_start` einmal pro Akteur. Für Sub-Agenten verwende die `session_id` des Elternagenten erneut, weise jedem Akteur eine eigene `agent_id` zu und setze `parent_id` auf die **Agent-ID** des Elternagenten – nicht auf die Session-ID. +## Identität -## Konfigurationsreferenz +Jeder Event gehört zu einer Sitzung und einem Agenten. **Die Scopes füllen beides aus**, daher müssen sie selten übergeben werden: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| Einstellung | Verhalten | -| --- | --- | -| `base_dir` | Explizites Spool-Verzeichnis. Hat Vorrang vor allen Umgebungsvariablen. | -| `flush_interval` | Sekunden zwischen Hintergrundschreibvorgängen aus dem Speicher in JSONL. Standard: `0.5`. | -| `environment` | Deployment-Label für jedes Ereignis. Standard: `dev`. | -| `FAILPROOFAI_HOME` | Ändert das Failproof AI-Stammverzeichnis, das den `custom-agents`-Spool enthält. | +`session_id` oder `agent_id` explizit zu übergeben funktioniert nach wie vor und hat Vorrang. Wenn weder ein Scope gebunden noch ein Wert übergeben wurde, löst der Aufruf einen `TypeError` aus, anstatt einen Event zu emittieren, den Cloud stillschweigend verwerfen würde. -Das SDK schreibt in das explizite `base_dir`, falls gesetzt. Andernfalls verwendet es den `custom-agents`-Spool des Failproof-Daemons unter `FAILPROOFAI_HOME` oder `~/.failproofai`. + + Die Identität wird über Kontextvariablen übertragen. Sie folgt `asyncio`-Tasks automatisch, aber **nicht** neuen Threads — umhüllen Sie einen Worker mit `failproofai_sdk.propagate()`, sonst landen seine Events ohne Zuordnung. + -Das SDK reiht Aufrufe im Speicher ein und schreibt Batches in einem Hintergrund-Thread. Es versucht außerdem einen abschließenden Flush über Pythons `atexit`-Mechanismus. Für kurzlebige Worker sollte ein normales Interpreter-Shutdown ermöglicht werden; ein harter Prozessabbruch kann Ereignisse verlieren, die sich noch im Speicher befinden. +## Event-Katalog -## Ereigniskatalog +Fünfzehn Methoden. Die meisten kommen in **Paaren** — Sie rufen den Öffner auf, dann den Schließer, und das SDK misst die Zeitspanne dazwischen. -Alle Methoden geben `None` zurück. Felder, die als `None` belassen werden, werden weggelassen statt als JSON `null` geschrieben. +| | Öffnet | Schließt | +| --- | --- | --- | +| **Agenten** | `agent_start` | `agent_end` | +| | `agent_pause` | `agent_resume` | +| **Modelle** | `model_request` | `model_response` | +| **Tools** | `tool_use` | `tool_result` | +| **Hooks** | `hook_triggered` | `hook_completed` | +| **Menschen** | `human_wait` | `human_input` | + +Drei stehen für sich allein: `error`, `human_pause`, `human_interrupt`. + + -| Methode | Pflichtfelder (über Identität hinaus) | Optionale Felder | +Jede Methode akzeptiert außerdem `session_id` und `agent_id`, die die Scopes automatisch ausfüllen. Alles, was als `None` übergeben wird, wird weggelassen statt als JSON `null` gesendet, und jede Methode gibt `None` zurück. + +| Methode | Pflichtfelder | Optionale Felder | | --- | --- | --- | | `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ Alle Methoden geben `None` zurück. Felder, die als `None` belassen werden, werd | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -Verwende `outcome="failed"`, `"error"`, `"timeout"` oder `"rejected"`, wenn eine Ausführung als Fehler gewertet werden soll. Andere Werte, einschließlich `"failure"`, werden vom aktuellen Backend nicht als Fehler klassifiziert. + + + + Um einen Lauf als fehlgeschlagen zu markieren, muss `outcome` einen der folgenden Werte haben: `failed`, `error`, `timeout` oder `rejected`. Alles andere — einschließlich des nahezu übereinstimmenden `"failure"` — wird als Erfolg gewertet. + + +## Paarbildung 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. + +| Paar | Verknüpft über | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**Übergeben Sie `duration_ms` nicht selbst.** Das SDK misst es, und eine Übergabe löst einen `ValueError` aus. -## Korrelations- und Dauerregeln +Die einzige Ausnahme ist `model_response`, wo nur Sie die tatsächliche Provider-Latenz kennen. Übergeben Sie eine ganze Anzahl Millisekunden — ein Float löst eine Ausnahme aus, da die Spalte ein 32-Bit-Integer ist und sonst leer bliebe. -- Verwende dieselbe `tool_call_id`, `hook_id`, `pause_id` oder `input_id` für das zugehörige Abschlussereignis. -- Das SDK berechnet `duration_ms` für `tool_result`, `hook_completed`, `agent_resume` und `human_input`. Wenn du diesen Wert selbst an diese Methoden übergibst, wird ein `ValueError` ausgelöst. -- Tool- und Hook-IDs teilen sich eine prozessweite Pending-Map. Mache sie global eindeutig – über gleichzeitige Sitzungen hinweg und über beide Namespaces; Provider-IDs oder UUIDs sind die sicherste Wahl. -- Ein Paar, das über Prozesse hinweg aufgeteilt ist, korreliert trotzdem nachgelagert, aber das SDK kann seine prozessinterne Dauer nicht berechnen. -- Die Pending-Map hält maximal 10.000 Einträge und verdrängt den ältesten Eintrag, wenn sie voll ist. + -## Benutzerdefinierte Felder und Nutzdaten +- **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 wiederverwenden, ohne zu kollidieren. +- **Sie sind nicht auf einen Agenten beschränkt.** Ein Paar, das unter einem Agenten geöffnet und unter einem anderen geschlossen wurde, wird trotzdem verknüpft — was bei Multi-Agenten-Code der Normalfall ist. +- **`request_id` ist optional, aber empfohlen.** Ohne sie werden Modell-Events in der Reihenfolge ihres Eingangs gepaart, sodass zwei gleichzeitige Aufrufe im selben Agenten falsch zugeordnet werden können. +- **Ein Paar, das über Prozesse aufgeteilt ist**, wird in Cloud trotzdem verknüpft, 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, sodass ein Leak nicht unbegrenzt wachsen kann. -Jedes Ereignis akzeptiert zusätzliche Keyword-Felder. Verwende JSON-kompatible Werte, wenn nachgelagerte Abfragen Struktur benötigen. Nicht unterstützte Typen wie UUIDs, Datetimes, Decimals, Sets, Bytes und Modellobjekte werden vom Writer in Strings umgewandelt. + -Reservierte benutzerdefinierte Namen sind `timestamp`, `session_id`, `agent_id`, `type` und `environment`. Tippfehler bei optionalen Feldern werden als neue benutzerdefinierte Felder akzeptiert – überprüfe daher das ausgegebene JSON, wenn ein Standardfeld nicht in Cloud erscheint. +## Eigene Felder -## Zustellen und überprüfen +Jedes zusätzliche Schlüsselwortargument wird mit dem Event gespeichert: + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # eigene Felder +) +``` + +Bevorzugen Sie JSON-Typen, wenn Sie die Werte später abfragen möchten. Alles andere — eine UUID, ein Datetime, ein `Decimal`, ein Set, Bytes, ein Modell-Objekt — wird als Zeichenkette gespeichert. + + + **Versehen Sie Ihre Feldnamen mit einem Präfix.** 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. + + 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. + + +Diese fünf Namen sind reserviert und werden grundsätzlich abgelehnt: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. + +## Zustellung und Überprüfung - Überprüfe unter **Observe → Events**, ob `agent_start` als erstes und `agent_end` als letztes Ereignis vorhanden ist. Öffne dann **Observe → Sessions** und bestätige, dass Modell-, Tool-, Human-, Hook- und Fehlerereignisse in der vorgesehenen Reihenfolge erscheinen. Verwende die Session-ID als primären Schlüssel bei der Fehlersuche. + Überprüfen Sie unter **Observe → Events**, ob `agent_start` als erstes und `agent_end` als letztes vorhanden ist. Öffnen Sie dann **Observe → Sessions** und bestätigen Sie, dass Modell-, Tool-, Human-, Hook- und Error-Events in der vorgesehenen Reihenfolge erscheinen. Verwenden Sie die Sitzungs-ID als primären Schlüssel zur Fehlersuche. ```bash @@ -189,10 +203,14 @@ Reservierte benutzerdefinierte Namen sind `timestamp`, `session_id`, `agent_id`, -Wenn Cloud leer ist, überprüfe `$FAILPROOFAI_HOME/custom-agents/events`, andernfalls `~/.failproofai/custom-agents/events`. JSONL-Dateien belegen die SDK-Ausgabe; ein wachsender Spool deutet auf ein Problem mit der Daemon-Konfiguration oder Zustellung hin, während ein leerer Spool auf ein Problem mit der Instrumentierung oder der Prozesslebensdauer 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 Problem mit der Daemon-Konfiguration oder Zustellung hin, während ein leerer Spool auf die Instrumentierung oder die Prozesslebensdauer hindeutet. + + + Untersuchen Sie den Spool nur, wenn der Daemon gestoppt ist. Während er läuft, sammelt und löscht er jeden Batch innerhalb von Millisekunden, sodass eine Verzeichnisauflistung mit dem Collector in einem Race Condition steht und weit weniger Events zeigt als tatsächlich emittiert wurden. + -## Fehler in einer benutzerdefinierten Laufzeitumgebung verhindern +## Fehler in einer eigenen Laufzeitumgebung verhindern -Nutze Audit-Ergebnisse und verknüpfte Traces, um die unsichere Aktion, die erforderlichen Belege und die beabsichtigte Reaktion zu definieren. Eine benutzerdefinierte Enforcement-Integration muss die Aktion vor ihrer Ausführung offenlegen, ihre strukturierten Eingaben 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 übergeben und die daraus resultierende allow-, instruct- oder deny-Entscheidung anwenden. -Schreibe an [support@befailproof.ai](mailto:support@befailproof.ai), um diese Integration für deine Laufzeitumgebung zu entwerfen und zu validieren. \ No newline at end of file +[Kontaktieren Sie Failproof AI](mailto:support@befailproof.ai) und wir helfen Ihnen dabei, die Modell-, Tool- und Lebenszyklus-Grenzen Ihrer Laufzeitumgebung auf Policy-Hooks abzubilden und die Integration anschließend gemeinsam mit Ihnen zu validieren. \ No newline at end of file diff --git a/docs/de/reference/events-and-configuration.mdx b/docs/de/reference/events-and-configuration.mdx index 62dea5cef..963d36253 100644 --- a/docs/de/reference/events-and-configuration.mdx +++ b/docs/de/reference/events-and-configuration.mdx @@ -1,41 +1,41 @@ --- title: "Events und Konfiguration" -description: "Referenz für das Ereignismodell, Umgebungen, lokalen Speicher und Konfigurationsgrenzen." +description: "Referenz zum Event-Modell, Umgebungen, lokalem Speicher und Konfigurationsgrenzen." icon: "list-tree" --- -## Ereignisfamilien +## Event-Familien -- Agent start, end, pause und resume +- Agent-Start, -Ende, -Pause und -Fortsetzung - Modellanfrage und -antwort -- Tool-Verwendung und -Ergebnis +- Tool-Nutzung und -Ergebnis - Hook ausgelöst und abgeschlossen - Menschliches Warten, Eingabe, Pause und Unterbrechung - Explizite Fehler -Jedes Ereignis enthält einen Zeitstempel, eine Sitzungs-ID, eine Agenten-ID, einen Ereignistyp und eine Umgebung. Ereignisspezifische Felder enthalten Modell-, Tool-, Korrelations-, Ergebnis-, Inhalts-, Dauer- oder Fehlerdaten. +Jedes Event enthält einen Zeitstempel, eine Session-ID, eine Agent-ID, einen Event-Typ und eine Umgebung. Event-spezifische Felder enthalten Modell-, Tool-, Korrelations-, Ergebnis-, Inhalts-, Dauer- oder Fehlerdaten. -## Einen Ereignisvertrag untersuchen +## Einen Event-Vertrag inspizieren - 1. Öffnen Sie **Observe → Events**. - 2. Legen Sie ein kurzes Zeitfenster fest und filtern Sie nach Umgebung, Agent und Ereignistyp. - 3. Wählen Sie ein Ereignis aus, um seine normalisierten Felder und die Roh-Payload zu untersuchen, und öffnen Sie dann die zugehörige Sitzung, um den Ausführungskontext zu sehen. - 4. Wenn eine zugehörige Dauer fehlt, vergewissern Sie sich, dass Start- und Abschlussereignisse dieselbe Korrelations-ID verwenden. + 1. Öffne **Observe → Events**. + 2. Setze ein kurzes Zeitfenster und filtere nach Umgebung, Agent und Event-Typ. + 3. Wähle ein Event aus, um seine normalisierten Felder und die Rohdaten zu prüfen, und öffne dann die zugehörige Session, um den Ausführungskontext zu sehen. + 4. Wenn eine zugehörige Dauer fehlt, prüfe, ob Start- und Abschluss-Event dieselbe Korrelations-ID verwenden. - Verwenden Sie den Events-Stream, um die Daten auf einen einzelnen Agentendurchlauf einzugrenzen und die normalisierten Ereignisfelder zu untersuchen. + Verwende den Events-Stream, um die Daten auf einen einzigen Agent-Lauf einzugrenzen und die normalisierten Event-Felder zu inspizieren. - ![Der Live-Events-Stream mit Filtern für Umgebung, Agent, Sitzung und Ereignistyp.](/images/dashboard/events-stream.png) + ![Der Live-Events-Stream mit Filtern für Umgebung, Agent, Session und Event-Typ.](/images/dashboard/events-stream.png) - Folgen Sie dann dem Ereignis in seine Sitzung. Der Trace zeigt, was unmittelbar davor und danach passiert ist – dies ist notwendig, wenn die Payload allein mehrdeutig ist. + Folge dem Event dann in seine Session. Der Trace zeigt, was unmittelbar davor und danach passiert ist – das ist notwendig, wenn das Payload allein mehrdeutig ist. - ![Der verknüpfte Sitzungs-Trace zur Untersuchung des Ereignisses im Ausführungskontext.](/images/dashboard/session-detail.png) + ![Der verknüpfte Session-Trace zur Inspektion des Events im Ausführungskontext.](/images/dashboard/session-detail.png) - Vergleichen Sie Korrelations-IDs und Zeitstempel in beiden Ansichten, wenn ein gekoppeltes Ereignis oder eine Dauer fehlt. + Vergleiche Korrelations-IDs und Zeitstempel in beiden Ansichten, wenn ein zugehöriges Event oder eine Dauer fehlt. - Gültige Filterwerte ermitteln und dann vollständige Ereignis-Payloads für eine Sitzung abrufen: + Gültige Filterwerte ermitteln, dann vollständige Event-Payloads für eine Session abrufen: ```bash fp list event_types @@ -47,32 +47,32 @@ Jedes Ereignis enthält einen Zeitstempel, eine Sitzungs-ID, eine Agenten-ID, ei --full ``` - Verwenden Sie `fp --json events ... --fields ts,event_type,session_id,payload` für maschinenlesbare Inspektion. + Verwende `fp --json events ... --fields ts,event_type,session_id,payload` für maschinenlesbare Inspektion. ## Reservierte SDK-Felder -Verwenden Sie `timestamp`, `session_id`, `agent_id`, `type` oder `environment` nicht als benutzerdefinierte Python-SDK-Felder. Gekoppelte Ereignisdauern wie die Tool-Ergebnis-Dauer werden vom SDK berechnet und können nicht manuell angegeben werden. +Verwende `timestamp`, `session_id`, `agent_id`, `type` oder `environment` nicht als benutzerdefinierte Python-SDK-Felder. Gepaarte Event-Dauern wie die Dauer eines Tool-Ergebnisses werden vom SDK berechnet und können nicht manuell angegeben werden. ## Lokale Grenzen - Der Failproof AI-Zustand liegt unter `~/.failproofai`, sofern nicht explizit anders konfiguriert. -- `failproofai-sdk` verwendet `AGENTEYE_HOME` für die Legacy-Überschreibung des Basisverzeichnisses. -- Umgebungsbezeichnungen können über die SDK-Konfiguration oder `AGENTEYE_ENVIRONMENT` gesetzt werden. -- Daemon-Anmeldeinformationen werden getrennt von nicht geheimen Einstellungen gespeichert. +- `failproofai-sdk` speichert stets unter `~/.failproofai/custom-agents`. `FAILPROOFAI_HOME` verlagert dieses Verzeichnis; das Segment `custom-agents` wird immer angehängt, sodass der Spool-Bereich nicht außerhalb davon platziert werden kann. Nur das eigene `configure(base_dir=...)` des SDK schreibt an einen anderen Ort. `AGENTEYE_HOME` wird vom älteren `agenteye-collector` gelesen, um den Beobachtungsbereich festzulegen, und hat keinen Einfluss mehr darauf, wohin das SDK schreibt. +- Umgebungs-Labels können über die SDK-Konfiguration oder `AGENTEYE_ENVIRONMENT` gesetzt werden. +- Daemon-Zugangsdaten werden getrennt von nicht geheimen Einstellungen gespeichert. -Verwenden Sie stabile Umgebungsnamen mit niedriger Kardinalität. Kommas werden in Daemon-Umgebungsbezeichnungen nicht unterstützt. +Verwende stabile Umgebungsnamen mit geringer Kardinalität. Kommas werden in Daemon-Umgebungs-Labels nicht unterstützt. -## Eine Umgebungsbezeichnung ändern +## Ein Umgebungs-Label ändern - Umgebungsbezeichnungen werden vom ausgebenden SDK oder Failproof-Daemon zugewiesen. Öffnen Sie nach einer Änderung **Observe → Sessions** und verwenden Sie den Umgebungsfilter, um zu bestätigen, dass neue Sitzungen den neuen Wert tragen. Bestehende Sitzungen behalten ihre ursprüngliche Umgebung. + Umgebungs-Labels werden vom sendenden SDK oder Failproof-Daemon vergeben. Öffne nach einer Änderung **Observe → Sessions** und verwende den Umgebungsfilter, um zu bestätigen, dass neue Sessions den neuen Wert tragen. Bestehende Sessions behalten ihre ursprüngliche Umgebung. - Für `failproofai-sdk` konfigurieren Sie die Umgebung im Code oder mit der zugehörigen Legacy-Umgebungsvariablen. Führen Sie die Daemon-Konfiguration erneut aus, wenn Sie Einstellungen auf Maschinenebene ändern. + Konfiguriere bei `failproofai-sdk` die Umgebung im Code oder über die veraltete Umgebungsvariable. Führe die Daemon-Konfiguration erneut aus, wenn du Einstellungen auf Maschinenebene änderst. ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/de/reference/harnesses.mdx b/docs/de/reference/harnesses.mdx index 8f8c281b1..382903137 100644 --- a/docs/de/reference/harnesses.mdx +++ b/docs/de/reference/harnesses.mdx @@ -6,12 +6,12 @@ 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: -- **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) +- **Coding CLIs** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **Chat- und Assistent-Gateways** (2) — Hermes (Slack, Telegram, Cron), OpenClaw (selbstgehosteter Assistent) -Dieselben Richtlinien und dieselbe Sitzungshistorie gelten unabhängig davon, in welchem Harness ein Agent ausgeführt wird. Eine Adapterschicht bildet die nativen Ereignisnamen, Tool-Namen und Tool-Eingabefelder jedes Harnesses 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 Adapter-Schicht überführt die nativen Ereignisnamen, Tool-Namen und Tool-Eingabefelder jedes Harness in 29 kanonische Ereignisse, bevor eine Richtlinie ausgeführt 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 es lohnt sich, dies klar zu benennen: Das SDK liefert Tracing, Sitzungen, Evaluierungen und Audits — **es setzt Richtlinien nicht eigenständig durch.** Um eine unsichere Aktion zu blockieren, bevor sie ausgeführt wird, ist ein Enforcement-Hook an der Tool-Grenze Ihrer Laufzeitumgebung erforderlich. [Kontaktieren Sie uns](mailto:support@befailproof.ai), und wir werden die Zuordnung vornehmen. +Ein Agent, der in **keinem** der zwölf Harnesses läuft, wird direkt über das [Python SDK](/de/reference/custom-agents) instrumentiert. Das ist ein anderer Vertrag, und er sollte klar benannt werden: Das SDK liefert Tracing, Sitzungen, Evaluierungen und Audits — **es setzt Richtlinien jedoch nicht eigenständig durch.** Das Blockieren einer unsicheren Aktion, bevor sie ausgeführt wird, erfordert einen Durchsetzungs-Hook an der Tool-Grenze Ihrer Laufzeitumgebung; [kontaktieren Sie uns](mailto:support@befailproof.ai) und wir werden es einrichten. | Harness | Unterstützte Hook-Scopes | | --- | --- | @@ -20,49 +20,49 @@ 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 Ende eines Turns und das Verhalten bei Anweisungen auf dem genauen Harness und der genauen Version, die Sie einsetzen. +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 exponiert; testen Sie das End-of-Turn- und Instruction-Verhalten auf dem genauen Harness und der Version, die Sie deployen. -## Durchsetzungsfähigkeit +## Durchsetzungsfä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, aber keine Tool-Nebenwirkung rückgängig machen, die bereits eingetreten ist. +„Blockieren" bedeutet, dass das zurückgegebene Urteil des aktuellen Adapters vom angegebenen Harness verarbeitet wird. Post-Tool-Blocking kann das dem Modell angezeigte Ergebnis ersetzen, aber einen bereits eingetretenen Tool-Nebeneffekt nicht rückgängig machen. -| Harness | Verifizierte Blockierungsereignisse | Nur-Beobachtungs- oder nicht-blockierende Hinweise | +| Harness | Verifizierte Blockierungsereignisse | Nur-Beobachtungs- oder Nicht-Blockierungs-Hinweise | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` und mehrere Task-/Konfigurationsereignisse | `PostToolUse`, Sitzungslebenszyklus, Benachrichtigungen und Post-Fehler-Ereignisse sind 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 beobachtend. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blockierung ersetzt das Ergebnis nach der Ausführung; Sitzungs- und Benachrichtigungsereignisse sind beobachtend. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` und Sitzungsereignisse sind beobachtend. | -| OpenCode | `PreToolUse` | Post-Tool- und Lebenszyklusereignisse sind beobachtend; die aktuelle Stop-Behandlung ist eine Empfehlung für einen späteren Turn, kein verifiziertes Gate. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Post-Tool- und Lebenszyklusereignisse sind beobachtend; Stop-Empfehlungen gelten für einen späteren Turn. | +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` sowie mehrere Task-/Konfigurationsereignisse | `PostToolUse`, Sitzungslebenszyklus, Benachrichtigungen und Post-Failure-Ereignisse sind nur beobachtend. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blocking ersetzt das Ergebnis nach der Ausführung; Sitzungsstart- und Compact-Ereignisse sind im aktuellen Adapter nur beobachtend. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blocking ersetzt das Ergebnis nach der Ausführung; Sitzungs- und Benachrichtigungsereignisse sind nur beobachtend. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` und Sitzungsereignisse sind nur beobachtend. | +| OpenCode | `PreToolUse` | Post-Tool- und Lifecycle-Ereignisse sind nur beobachtend; die aktuelle Stop-Behandlung ist eine Anleitung für einen späteren Turn, kein verifiziertes Gate. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Post-Tool- und Lifecycle-Ereignisse sind nur beobachtend; Stop-Anleitung gilt für einen späteren Turn. | | 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 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 Sitzungsereignisse sind beobachtend. | -| Antigravity CLI | `PreToolUse`, `Stop` | User-Prompt- und Post-Tool-Urteile sind beobachtend; Prompt-Anweisungen können weiterhin injiziert werden. | -| Goose | `PreToolUse` | User-Prompt-, Post-Tool- und Sitzungsereignisse sind beobachtend. Ein nativer blockierender Stop-Hook existiert im Upstream, wird aber vom aktuellen Adapter nicht installiert. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Post-Tool-, Sitzungs-, Subagent-Stop- und Kompaktierungsereignisse sind nur beobachtend. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Post-Tool- und Subagent-Stop-Urteile sind nur beobachtend. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, bedingtes `PermissionRequest` | Permission-Hooks laufen nicht in jedem Permission-Modus; Post-Tool- und Sitzungsereignisse sind nur beobachtend. | +| Antigravity CLI | `PreToolUse`, `Stop` | User-Prompt- und Post-Tool-Urteile sind nur beobachtend; Prompt-Anweisungen können trotzdem injiziert werden. | +| Goose | `PreToolUse` | User-Prompt-, Post-Tool- und Sitzungsereignisse sind nur beobachtend. Ein nativer blockierender Stop-Hook existiert vorgelagert, wird aber vom aktuellen Adapter nicht installiert. | -Die 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 statt auf das übliche Pre-Tool-Gate angewiesen ist. +Die Fähigkeiten sind versionsabhängig. Führen Sie nach einem Upgrade eines Agent-CLI erneute Tests durch, insbesondere wenn eine Richtlinie auf Prompt-, Stop-, Permission- oder Post-Tool-Verhalten anstatt auf das übliche Pre-Tool-Gate angewiesen ist. ## Capture- und Policy-Hooks installieren - 1. Öffnen Sie **Verwaltung → Schlüssel** und erstellen Sie einen Schlüssel mit `events:add` und `policies:pull`, benannt nach der Maschine oder Umgebung. + 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 **Beobachten → Ereignisse**. - 4. Öffnen Sie **Beobachten → Richtlinie** 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 dann 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 ist. - 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 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 Schublade für neue API-Schlüssel zum Erteilen von Ereigniserfassungs- und Richtlinienlieferberechtigungen.](/images/dashboard/key-create.png) + ![Die Drawer-Ansicht für neue API-Schlüssel zum Erteilen von Ereignisaufnahme- und Richtlinienlieferungsberechtigungen.](/images/dashboard/key-create.png) Nach der Installation der Hooks sollte der Ereignis-Stream neue Ereignisse von der verbundenen Maschine und Umgebung anzeigen. - ![Der Live-Ereignis-Stream zur Bestätigung, dass ein neu installierter Harness meldet.](/images/dashboard/events-stream.png) + ![Der Live-Ereignis-Stream zum Bestätigen, 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. - ![Die Richtlinienseite zur Überprüfung von Richtlinienentscheidungen eines neu verbundenen Harnesses.](/images/dashboard/policy-observe.png) + ![Die Policy-Seite zum Überprüfen von Richtlinienentscheidungen eines neu verbundenen Harness.](/images/dashboard/policy-observe.png) Hooks für alle erkannten Harnesses installieren: @@ -74,7 +74,7 @@ Die Fähigkeiten sind versionsabhängig. Führen Sie nach dem Upgrade einer Agen failproofai policies --install ``` - Oder gezielt benannte Harnesses und einen Konfigurationsscope angeben: + Oder gezielt benannte Harnesses und einen Konfigurationsscope ansprechen: ```bash failproofai policies --install \ @@ -82,9 +82,9 @@ Die Fähigkeiten sind versionsabhängig. Führen Sie nach dem Upgrade einer Agen --scope user ``` - Der Project-Scope hält 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 hält die Hook-Konfiguration bei einem Repository. Der User-Scope deckt die Arbeit über Repositories hinweg ab. Claude Code unterstützt außerdem den Local-Scope; die Unterstützung variiert je nach Harness, und die CLI lehnt nicht unterstützte Kombinationen ab. - Maschine und ihre Ereignisse überprüfen: + Die Maschine und ihre Ereignisse überprüfen: ```bash failproofai config --status @@ -94,16 +94,16 @@ Die Fähigkeiten sind versionsabhängig. Führen Sie nach dem Upgrade einer Agen -## Einen 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 **Beobachten → Sitzungen**, 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 Ereigniszeitstempel, bevor Sie ihn in einem Audit verwenden. + Zusätzliche Pfade werden auf der Maschine registriert, nicht in der Cloud. Nach dem Hinzufügen ö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-Timestamps, bevor Sie sie in einem Audit verwenden. - ![Die Sitzungsliste, gefiltert nach der Umgebung, die Daten aus dem zusätzlichen Capture-Pfad empfängt.](/images/dashboard/sessions-list.png) + ![Die Sitzungsliste gefiltert nach der Umgebung, die Daten aus dem zusätzlichen Capture-Pfad empfängt.](/images/dashboard/sessions-list.png) - Einen Pfad mit optionalem Label hinzufügen und die konfigurierten Pfade anzeigen: + Einen Pfad mit optionalem Label hinzufügen und dann die konfigurierten Pfade prüfen: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -117,5 +117,5 @@ Die Fähigkeiten sind versionsabhängig. Führen Sie nach dem Upgrade einer Agen - Führen Sie nach der Installation eine neue Sitzung aus. Überprüfen Sie sowohl den Live-Ereignis-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-Ereignis-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 84911bf93..a045ba491 100644 --- a/docs/de/reference/overview.mdx +++ b/docs/de/reference/overview.mdx @@ -1,61 +1,64 @@ --- title: "Integrationen und Referenz" -description: "Unterstützte Agent-Harnesses, SDKs, CLIs und die HTTP API verbinden." +description: "Unterstützte Agent-Harnesses, SDKs, CLIs und die HTTP-API verbinden." icon: "braces" --- -Wählen Sie die Integration, die am nächsten an der Umgebung liegt, in der Ihr Agent bereits läuft. +Wählen Sie die Integration, die am besten zu Ihrer bestehenden Agent-Umgebung passt. Hooks für unterstützte Coding- und autonome Agent-CLIs installieren. - - Traces instrumentieren, um Fehler in eigenen Agenten zu finden, und uns anschließend kontaktieren, um Prävention in Ihre Runtime einzubinden. + + LangGraph, CrewAI, LlamaIndex, Pydantic AI oder einen benutzerdefinierten Agenten instrumentieren. + + + Konfiguration, der Event-Katalog, Korrelationsregeln und Zustellung. - Lokale Projekte, Sitzungen, Policy-Aktivitäten und Offline-Audits einsehen. + Lokale Projekte, Sitzungen, Policy-Aktivität und Offline-Audits einsehen. - Lokale Erfassung, Hooks, Policies, Audits, Delivery und Maschinenstatus konfigurieren. + Lokale Erfassung, Hooks, Policies, Audits, Zustellung und Maschinenstatus konfigurieren. - Cloud-Sitzungen, Audits, Issues, Alerts, Keys, Benutzer und Einstellungen abfragen und verwalten. + Cloud-Sitzungen, Audits, Issues, Alerts, Schlüssel, Benutzer und Einstellungen abfragen und verwalten. Abgeschlossene oder inaktive Sitzungen mit einem FastAPI-Dienst bewerten. - + Workflow-spezifische allow-, instruct- und deny-Entscheidungen erstellen und testen. - Die Cloud-Control-Plane auf einem kundenverwalteten Kubernetes-Cluster betreiben. + 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 umfassen 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 verfasste Seiten erläutern Workflows, die mehrere Endpunkte umfassen oder administrative Schnittstellen außerhalb dieser öffentlichen Oberfläche verwenden. -## Agenten verbinden und Daten verifizieren +## 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 anhand 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 sie vollständige Runs bilden. - 4. Filtern Sie nach der Umgebung der Integration und prüfen Sie eine Sitzung auf die Felder für Modell, Tool, Fehler und Policy, die für Audits benötigt werden. + 1. Öffnen Sie **Administration → Keys**, erstellen Sie einen Schlüssel mit `events:add` und `policies:pull`, und kopieren Sie das Secret. + 2. Konfigurieren Sie die Integration über die entsprechende Seite oben. + 3. Öffnen Sie **Observe → Events**, um den Eingang von Events zu bestätigen, dann **Observe → Sessions**, um zu bestätigen, dass diese vollständige Ausführungen bilden. + 4. Filtern Sie nach der Umgebung der Integration und prüfen Sie eine Sitzung auf die für Audits benötigten Felder: Modell, Tool, Fehler und Policy. - Beginnen Sie mit dem Key-Drawer. Die ausgewählten Berechtigungen bestimmen, ob die Maschine Events senden und Cloud-verwaltete Policies empfangen kann. + Beginnen Sie mit dem Schlüssel-Drawer. Die ausgewählten Berechtigungen bestimmen, ob die Maschine Events senden und Cloud-verwaltete Policies empfangen kann. - ![Das neue API-Key-Drawer zum Erteilen von Berechtigungen für Event-Ingestion und Policy-Delivery.](/images/dashboard/key-create.png) + ![Der neue API-Schlüssel-Drawer zum Erteilen von Berechtigungen für die Event-Aufnahme und Policy-Zustellung.](/images/dashboard/key-create.png) - Nach dem Verbinden der Integration können Sie die Sitzungsliste verwenden, um zu bestätigen, dass die Events in der erwarteten Umgebung zu vollständigen Runs zusammengefasst werden. + Verwenden Sie nach dem Verbinden der Integration die Sitzungsliste, um zu bestätigen, dass die Events in der erwarteten Umgebung zu vollständigen Ausführungen gruppiert werden. - ![Die Sitzungsliste zur Überprüfung, ob eine neu verbundene Integration vollständige Agent-Runs meldet.](/images/dashboard/sessions-list.png) + ![Die Sitzungsliste zur Überprüfung, ob eine neu verbundene Integration vollständige Agent-Ausführungen meldet.](/images/dashboard/sessions-list.png) - Öffnen Sie eine dieser Sitzungen, 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. + Öffnen Sie eine dieser Sitzungen, bevor Sie die Integration als abgeschlossen betrachten. Der Trace sollte das Modell, Tool, den Fehler und die Policy-Nachweise enthalten, die Ihre Audits benötigen. - Erstellen Sie einen Machine-Key, verbinden Sie den Failproof-Daemon und verifizieren Sie die erste Sitzung. + Erstellen Sie einen Maschinenschlüssel, verbinden Sie den Failproof-Daemon und überprüfen Sie die erste Sitzung. ```bash fp keys create agent-production \ @@ -71,8 +74,8 @@ Die generierte [HTTP-API-Referenz](/de/reference/http-api) deckt die öffentlich fp events --since 1h --env production --limit 20 ``` - Verwenden Sie `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 angegeben werden. + 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. - 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). + Weitere Informationen finden Sie in der [Failproof AI CLI-Referenz](/de/reference/failproof-cli) für lokale Befehle und in der [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/troubleshooting.mdx b/docs/de/reference/troubleshooting.mdx index c0a4acfe8..f4eb3a0d0 100644 --- a/docs/de/reference/troubleshooting.mdx +++ b/docs/de/reference/troubleshooting.mdx @@ -1,6 +1,6 @@ --- title: "Fehlerbehebung" -description: "Diagnose fehlender Sitzungen, fehlender Richtlinien, fehlgeschlagener Übertragungen und blockierter Agenten-Aktionen." +description: "Diagnose von fehlenden Sitzungen, fehlenden Richtlinien, fehlgeschlagener Zustellung und blockierten Agent-Aktionen." icon: "wrench" --- @@ -8,9 +8,9 @@ icon: "wrench" - Öffne **Verwaltung → Schlüssel** und bestätige, dass der Maschinenschlüssel aktiv ist und die Berechtigung `events:add` besitzt. Öffne dann **Beobachten → Ereignisse**, erweitere den Zeitraum und entferne Umgebungs- und Agenten-Filter. Falls Ereignisse vorhanden sind, suche nach der Sitzungs-ID und prüfe anschließend **Beobachten → Sitzungen** auf Gruppierungen. Falls keine Ereignisse vorhanden sind, diagnostiziere den Failproof-Daemon über die CLI. + Öffne **Administration → Schlüssel** und prüfe, ob der Maschinenschlüssel aktiv ist und `events:add` besitzt. Öffne dann **Beobachten → Ereignisse**, erweitere den Zeitraum und entferne Umgebungs- und Agent-Filter. Wenn Ereignisse vorhanden sind, suche nach der Sitzungs-ID und prüfe dann **Beobachten → Sitzungen** auf Gruppierungen. Wenn keine Ereignisse vorhanden sind, diagnostiziere den Failproof-Daemon über die CLI. - ![Der Live-Ereignisstream mit seinen primären Filtern und aktuell eintreffenden Agenten-Ereignissen.](/images/dashboard/events-stream-current.png) + ![Der Live-Ereignisstrom mit den primären Filtern und aktuell eintreffenden Agent-Ereignissen.](/images/dashboard/events-stream-current.png) ```bash @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - Bestätige, dass die Erfassung aktiviert ist, der konfigurierte Schlüssel `events:add` besitzt und der Dashboard-Filter mit der ausgesendeten Umgebung übereinstimmt. + Bestätige, dass die Erfassung aktiviert ist, der konfigurierte Schlüssel `events:add` besitzt und der Dashboard-Filter zur emittierten Umgebung passt. - + - Entferne Filter unter **Beobachten → Ereignisse** und suche nach der genauen SDK-Sitzungs-ID. Falls nichts erscheint, untersuche den SDK-Spool und den Failproof-Daemon auf dem Quellrechner. + Entferne Filter unter **Beobachten → Ereignisse** und suche nach der exakten SDK-Sitzungs-ID. Wenn nichts erscheint, untersuche den SDK-Spool und den Failproof-Daemon auf dem Quellrechner. ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - Bestätige, dass der Agenten-Prozess `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` setzt und dass `$FAILPROOFAI_HOME/custom-agents` – andernfalls `~/.failproofai/custom-agents` – vorhanden ist, bevor das SDK startet. + Bestätige, dass ein Daemon läuft und verbunden ist – das SDK spult unabhängig davon, ob einer vorhanden ist. Das Spool-Verzeichnis muss **nicht** vorab existieren (der Schreiber erstellt es), und keine Umgebungsvariable wählt es aus: `$FAILPROOFAI_HOME/custom-agents`, andernfalls `~/.failproofai/custom-agents`, ist der einzige Wurzelpfad, und `configure(base_dir=...)` ist die einzige Überschreibungsmöglichkeit. Wenn der Prozess per `SIGKILL` oder durch OOM beendet wurde, gehen noch in der Warteschlange befindliche Daten verloren – verarbeite `SIGTERM`, um das zu begrenzen. - Öffne **Admin → Durchsetzung**, wähle den Rechner aus und vergleiche dessen zugewiesene, gemeldete und vorherige Versionen. Bestätige, dass der Deployment-Geltungsbereich den Rechner einschließt und sein Schlüssel `policies:pull` besitzt. Die Erfassung kann funktionieren, auch wenn die Richtlinienübertragung fehlschlägt. + Öffne **Admin → Durchsetzung**, wähle den Rechner aus und vergleiche dessen zugewiesene, gemeldete und frühere Versionen. Prüfe, ob der Deployment-Scope den Rechner einschließt und sein Schlüssel `policies:pull` besitzt. Die Ereignisaufnahme kann funktionieren, auch wenn die Richtlinienlieferung nicht funktioniert. @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - Bestätige, dass Rechner-ID und -Bezeichnung mit dem Dashboard-Ziel übereinstimmen. Stelle die Verbindung mit einem richtlinienfähigen Schlüssel wieder her, falls der vorhandene Schlüssel nur die Ereigniserfassung erlaubt. + Prüfe, ob Maschinen-ID und Bezeichnung mit dem Dashboard-Ziel übereinstimmen. Stelle bei Bedarf die Verbindung mit einem richtlinienfähigen Schlüssel her, wenn die vorhandenen Anmeldedaten nur die Ereignisaufnahme erlauben. - Öffne **Admin → Durchsetzung** und prüfe den Zeitpunkt der letzten Aktivität und die gemeldete Version des Rechners. Falls der Rechner veraltet ist, handelt es sich um ein lokales Daemon-Problem. Schwäche die bereitgestellte Richtlinie nicht allein deshalb ab, um einen nicht verfügbaren Daemon zu umgehen. + Öffne **Admin → Durchsetzung** und überprüfe den Zeitpunkt der letzten Verbindung des Rechners sowie die gemeldete Version. Wenn der Rechner veraltet ist, handelt es sich um ein lokales Daemon-Problem. Schwäche die bereitgestellte Richtlinie nicht allein aus, um einen nicht verfügbaren Daemon zu umgehen. @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - Starte `failproofaid` neu oder aktualisiere es; führe die Konfiguration erneut aus, wenn sich die Protokollversionen von CLI und Daemon unterscheiden. Der konfigurierte Daemon-Pfad schlägt planmäßig auf sichere Weise fehl. + Starte `failproofaid` neu oder aktualisiere es; führe die Konfiguration erneut aus, wenn sich die Protokollversionen von CLI und Daemon unterscheiden. Der konfigurierte Daemon-Pfad schlägt by design auf Sperrung fehl. - Für eine Cloud-erstellte Richtlinie: Öffne **Admin → Richtlinien-Editor**, wähle den Entwurf aus und prüfe Validierungsfehler vor der Veröffentlichung. Für eine lokale Richtlinie: Validiere sie über die CLI und öffne anschließend **Beobachten → Richtlinie** nach einer Testaktion, um zu bestätigen, dass Entscheidungen ankommen. + Öffne bei einer Cloud-erstellten Richtlinie den **Admin → Richtlinien-Editor**, wähle den Entwurf aus und überprüfe Validierungsfehler vor der Veröffentlichung. Validiere bei einer lokalen Richtlinie diese über die CLI und öffne dann nach einer Testüberprüfung **Beobachten → Richtlinien**, um zu bestätigen, dass Entscheidungen ankommen. - Stelle sicher, dass der Dateiname auf `policies.js`, `policies.mjs` oder `policies.ts` endet, das Modul `customPolicies.add(...)` aufruft und Importe aus der Richtliniendatei auflösbar sind. + Stelle sicher, dass der Dateiname auf `policies.js`, `policies.mjs` oder `policies.ts` endet, das Modul `customPolicies.add(...)` aufruft und Imports aus der Richtliniendatei auflösbar sind. ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -94,11 +94,11 @@ icon: "wrench" - Öffne **Analysieren → Audits**, wähle den Lauf aus und prüfe, ob die Modellanalyse ausgeführt wurde. Vergleiche anschließend Geltungsbereich und Zeitfenster mit **Beobachten → Sitzungen** und öffne repräsentative Traces aus dieser Population. + Öffne **Analysieren → Audits**, wähle den Durchlauf aus und prüfe, ob die Modellanalyse ausgeführt wurde. Vergleiche dann Scope und Zeitfenster mit **Beobachten → Sitzungen** und öffne repräsentative Traces aus dieser Population. - Ein Nullergebnis ist nur dann aussagekräftig, wenn die Analyse erfolgreich durchgeführt wurde. Falls die Analyse übersprungen oder fehlgeschlagen ist, liefert der Lauf keine Ergebnisse und hält das nicht analysierte Zeitfenster für einen künftigen erfolgreichen Lauf offen. Falls die Modellanalyse deaktiviert ist, liefert das Audit ebenfalls keine Ergebnisse, da der deterministische Anmeldedaten- und PII-Scan nur Statistiken erfasst, aber keine Befunde mehr meldet. + Ein Null-Ergebnis ist nur dann aussagekräftig, wenn die Analyse erfolgreich durchgeführt wurde. Wenn die Analyse übersprungen wurde oder fehlgeschlagen ist, produziert der Durchlauf keine Ergebnisse und hält das nicht analysierte Fenster für einen zukünftigen erfolgreichen Durchlauf offen. Wenn die Modellanalyse deaktiviert ist, produziert das Audit ebenfalls keine Ergebnisse, da der deterministische Credential- und PII-Scan nur Statistiken aufzeichnet, aber keine Befunde mehr meldet. - ![Das Audit-Formular, in dem Umgebung, Agent, Kadenz und Sweep-Zeitfenster die Sitzungspopulation definieren.](/images/dashboard/audit-new.png) + ![Das Audit-Formular, in dem Umgebung, Agent, Kadenz und Zeitfenster die Sitzungspopulation definieren.](/images/dashboard/audit-new.png) ```bash @@ -110,31 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - Falls der Lauf in der Warteschlange verblieben ist, warte auf freie Audit-Agenten-Kapazität oder bitte den Deployment-Operator, die Audit-Flotte zu prüfen. Ein in der Warteschlange befindliches Audit wird wiederholt; es wird nicht sofort übersprungen. + Wenn der Durchlauf in der Warteschlange verblieben ist, warte auf Audit-Agent-Kapazität oder bitte den Deployment-Betreiber, die Audit-Flotte zu überprüfen. Ein Audit in der Warteschlange wird erneut versucht; es wird nicht sofort übersprungen. - + - Öffne eine abgeschlossene Sitzung und prüfe, ob eine manuelle Evaluierung erfolgreich ist. Im gehosteten Cloud-Betrieb gibt es derzeit keine Steuerung des Evaluator-Endpunkts im Dashboard; der Server-Operator muss dies konfigurieren. + Öffne eine abgeschlossene Sitzung und prüfe, ob eine manuelle Auswertung erfolgreich ist. Hosted Cloud bietet derzeit keine Kontrolle über den Evaluator-Endpunkt im Dashboard; der Server-Betreiber muss dies konfigurieren. - Überprüfe den Evaluator selbst und untersuche dann aktuelle Evaluierungszustände: + Überprüfe zunächst den Evaluator selbst und untersuche dann die aktuellen Auswertungszustände: ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - Bei selbst gehosteter Cloud: Bestätige, dass `EVALUATOR_ENDPOINT` auf dem Server vorhanden ist und `EVALUATOR_TOKEN` mit dem Evaluator übereinstimmt. Die automatische Evaluierung ist deaktiviert, wenn der Endpunkt fehlt. + Stelle bei selbst gehostetem Cloud sicher, dass `EVALUATOR_ENDPOINT` auf dem Server vorhanden ist und `EVALUATOR_TOKEN` mit dem Evaluator übereinstimmt. Die automatische Auswertung ist deaktiviert, wenn der Endpunkt fehlt. - Nutze den Organisations-Umschalter und bestätige den erwarteten Slug sowie die Berechtigungen, bevor du die Ergebnisse mit der CLI vergleichst. + Verwende den Organisationswechsler und bestätige den erwarteten Slug und die Berechtigungen, bevor du die Ergebnisse mit der CLI vergleichst. ```bash @@ -143,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - Im API-Schlüssel-Modus: Gib `fp --org --api-key ...` an oder setze `AGENTEYE_ORG`. Der gespeicherte Organisationszustand einer Human-Session wird für API-Schlüssel-Anfragen absichtlich ignoriert. + Gib im API-Schlüsselmodus `fp --org --api-key ...` an oder setze `AGENTEYE_ORG`. Der gespeicherte Organisationsstatus einer menschlichen Sitzung wird bei API-Schlüssel-Anfragen absichtlich ignoriert. - Öffne **Beobachten → Richtlinie**, bewahre die Entscheidung und die verknüpfte Sitzung und identifiziere die False-Positive-Bedingung. Öffne dann **Admin → Durchsetzung** und setze die betroffenen Rechner auf die vorherige Version zurück. Erstelle eine engere Version im **Richtlinien-Editor**, teste sie auf einem kleinen Geltungsbereich und erweitere ihn erst, wenn legitime Arbeit erfolgreich ausgeführt wird. + Öffne **Beobachten → Richtlinien**, sichere die Entscheidung und die verknüpfte Sitzung und identifiziere die False-Positive-Bedingung. Öffne dann **Admin → Durchsetzung** und setze die betroffenen Rechner auf die vorherige Version zurück. Erstelle eine engere Version im **Richtlinien-Editor**, teste sie auf einem kleinen Scope und erweitere ihn erst, wenn legitime Arbeit erfolgreich ist. - Ein Rollback der Cloud-Bereitstellung ist ausschließlich über das Dashboard möglich. Eine lokale Sitzungspause deaktiviert Cloud-verwaltete Richtlinien nicht. Falls das Dashboard nicht verfügbar ist, erfasse den Rechner- und Deployment-Zustand und stelle den Dashboard-Zugang wieder her, anstatt die blockierte Aktion wiederholt zu versuchen. + Das Zurücksetzen von Cloud-Deployments ist nur über das Dashboard möglich. Eine lokale Sitzungspause deaktiviert Cloud-verwaltete Richtlinien nicht. Wenn das Dashboard nicht verfügbar ist, erfasse den Rechner- und Deployment-Status und stelle den Dashboard-Zugang wieder her, anstatt die blockierte Aktion wiederholt zu versuchen. ```bash failproofai config --status @@ -164,4 +164,4 @@ icon: "wrench" -Wenn du den Support kontaktierst, gib die CLI-Version, das Harness, die Umgebung, die relevante Sitzungs- oder Deployment-ID sowie die Ausgabe von `failproofai config --status` (ohne vertrauliche Informationen) an. \ No newline at end of file +Wenn du den Support kontaktierst, gib die CLI-Version, den Harness, die Umgebung, die relevante Sitzungs- oder Deployment-ID sowie die Ausgabe von `failproofai config --status` mit entfernten Geheimnissen an. \ No newline at end of file diff --git a/docs/de/sessions/live-events.mdx b/docs/de/sessions/live-events.mdx index 1111f15ab..555191564 100644 --- a/docs/de/sessions/live-events.mdx +++ b/docs/de/sessions/live-events.mdx @@ -1,21 +1,21 @@ --- title: "Live-Events" -description: "Beobachte Agenten-Aktivität in Echtzeit, während eine Sitzung läuft." +description: "Beobachte Agenten-Aktivitäten in Echtzeit während einer laufenden Session." icon: "radio" --- -Live-Events helfen dir, die Instrumentierung zu bestätigen und einen riskanten Lauf zu beobachten, ohne auf das Ende der Sitzung warten zu müssen. +Live-Events helfen dir, die Instrumentierung zu bestätigen und einen riskanten Durchlauf zu beobachten, ohne auf das Ende der Session warten zu müssen. ## Aktivität beobachten 1. Gehe zu **Observe → Events**. - 2. Beginne mit dem aktuellen Zeitfenster und ohne Filter, um zu bestätigen, dass Daten ankommen. - 3. Filtere nach Umgebung, Event-Typ, Agent oder Sitzung. Nutze die Suche für Payload-Text. - 4. Wähle ein Event aus, um dessen Zusammenfassung und Details einzusehen. Folge dem Sitzungslink für den vollständigen Trace. + 2. Starte mit dem aktuellen Zeitfenster und ohne Filter, um zu bestätigen, dass Daten ankommen. + 3. Filtere nach Umgebung, Event-Typ, Agent oder Session. Verwende die Suche für Payload-Text. + 4. Wähle ein Event aus, um seine Zusammenfassung und Details einzusehen. Folge dem Session-Link für den vollständigen Trace. - ![Der Live-Events-Stream zeigt Traffic von einem Hermes-Chat-Gateway neben Coding-CLI-Läufen, gefiltert nach Zeit, Umgebung, Event-Typ, Agent, Modell, Kontext und Sitzung.](/images/dashboard/events-stream-current.png) + ![Der Live-Events-Stream zeigt Traffic von einem Hermes-Chat-Gateway neben Coding-CLI-Läufen, gefiltert nach Zeit, Umgebung, Event-Typ, Agent, Modell, Kontext und Session.](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +24,22 @@ Live-Events helfen dir, die Instrumentierung zu bestätigen und einen riskanten fp --json events --full --session-id --all ``` - Der Standard-Feed lässt rohe Payloads aus. Verwende `--full` nur für eine zeitlich begrenzte Sitzungsuntersuchung. + Der Standard-Feed lässt rohe Payloads weg. Verwende `--full` nur für eine eingegrenzte Session-Untersuchung. Nutze den Event-Stream, um drei unmittelbare Fragen zu beantworten: -- Meldet sich der erwartete Agent in der richtigen Umgebung? +- Meldet sich der erwartete Agent an die richtige Umgebung? - Kommen Modellaufrufe, Tool-Aufrufe und Policy-Entscheidungen in der richtigen Reihenfolge an? -- Hat die Sitzung aufgehört, Fortschritte zu machen, oder beginnt sie, eine Aktion zu wiederholen? +- Hat die Session aufgehört, Fortschritte zu machen, oder wiederholt sie eine Aktion? -Event-Typen umfassen Agent-Lifecycle-Events, Modellanfragen und -antworten, Tool-Nutzung und -Ergebnisse, Hook-Ausführung, Human-Waits und Interrupts sowie explizite Fehler. Korrelations-IDs verbinden zusammengehörige Events, wie etwa einen Tool-Aufruf und sein Ergebnis. +Event-Typen umfassen Agent-Lifecycle-Events, Modellanfragen und -antworten, Tool-Nutzung und -Ergebnisse, Hook-Ausführung, menschliche Wartezeiten und Unterbrechungen sowie explizite Fehler. Korrelations-IDs verbinden zusammengehörige Events, wie etwa einen Tool-Aufruf und sein Ergebnis. - Halte die Live-Ansicht zunächst breit gefächert, wenn du eine neue Integration überprüfst. Füge Filter erst hinzu, nachdem du das erste Event gesehen hast – ein falscher Filter kann wie eine fehlgeschlagene Datenaufnahme aussehen. + Lass die Live-Ansicht zunächst breit, während du eine neue Integration verifizierst. Füge Filter erst hinzu, nachdem du das erste Event gesehen hast – ein falscher Filter kann wie eine fehlgeschlagene Ingestion aussehen. -Falls keine Events erscheinen, führe `failproofai config --status` aus und [behebe Ingestion-Probleme](/de/reference/troubleshooting). +Wenn keine Events erscheinen, führe `failproofai config --status` aus und [behebe Ingestion-Probleme](/de/reference/troubleshooting). -Agenten, die nicht in einem der 12 unterstützten [Harnesses](/de/reference/harnesses) laufen, melden dieselben Event-Typen über das [Python SDK](/de/reference/custom-agents), einschließlich der Human-in-the-Loop-Events (`human_wait`, `human_input`, `human_interrupt`), auf die Gateway- und Produktionsagenten angewiesen sind. \ No newline at end of file +Agents, die nicht in einem der 12 unterstützten [Harnesses](/de/reference/harnesses) laufen, melden dieselben Event-Typen über das [Python SDK](/de/reference/custom-agents), einschließlich der Human-in-the-Loop-Events (`human_wait`, `human_input`, `human_interrupt`), auf die Gateway- und Produktions-Agents angewiesen sind. \ No newline at end of file diff --git a/docs/de/start/first-policy.mdx b/docs/de/start/first-policy.mdx index 1b36e7445..656025812 100644 --- a/docs/de/start/first-policy.mdx +++ b/docs/de/start/first-policy.mdx @@ -1,33 +1,33 @@ --- title: "Verhindern Sie Ihren ersten Fehler mit einer Policy" -description: "Erstellen Sie eine Policy-Version, stellen Sie sie im Beobachtungsmodus bereit und setzen Sie sie anschließend durch." +description: "Erstellen Sie eine Policy-Version, stellen Sie sie im Beobachtungsmodus bereit und setzen Sie sie dann durch." icon: "shield-check" --- -Verwenden Sie eine Policy erst dann, wenn Sie die unsichere Aktion und die legitimen Aktionen, die weiterhin erlaubt bleiben müssen, klar beschreiben können. +Verwenden Sie eine Policy erst, wenn Sie die unsichere Aktion und die legitimen Aktionen, die weiterhin erlaubt bleiben müssen, beschreiben können. - - Gehen Sie zu **Admin → Policy-Editor**. Beginnen Sie mit der Demo-Policy, überprüfen oder bearbeiten Sie deren Quellcode und wählen Sie dann **Version veröffentlichen**. Durch die Veröffentlichung wird die unveränderliche Version erstellt, die Sie auf Maschinen bereitstellen können. + + Gehen Sie zu **Admin → Policy-Editor**. Starten Sie mit der Demo-Policy, prüfen oder bearbeiten Sie den Quellcode und wählen Sie dann **Version veröffentlichen**. Das Veröffentlichen erstellt die unveränderliche Version, die Sie auf Maschinen bereitstellen können. - ![Die Compose-Ansicht des Policy-Editors mit einer Demo-Policy, die als unveränderliche Version veröffentlicht werden soll.](/images/dashboard/policy-editor.png) + ![Die Compose-Ansicht des Policy-Editors mit einer Demo-Policy, die bereit zur Veröffentlichung als unveränderliche Version ist.](/images/dashboard/policy-editor.png) - - Gehen Sie zu **Admin → Durchsetzung**, erweitern Sie die Zielmaschine und wählen Sie **Diese Maschine bearbeiten**. Fügen Sie die veröffentlichte Demo-Policy hinzu, fixieren Sie deren Version, wählen Sie **Beobachten** und wenden Sie die Bereitstellung an. + + Gehen Sie zu **Admin → Durchsetzung**, erweitern Sie die Zielmaschine und wählen Sie **diese Maschine bearbeiten**. Fügen Sie die veröffentlichte Demo-Policy hinzu, fixieren Sie deren Version, wählen Sie **Beobachten** und wenden Sie die Bereitstellung an. - ![Der Editor für die Maschinenbereitstellung mit einer ausgewählten veröffentlichten Policy-Version im Beobachtungsmodus, bevor die Bereitstellung angewendet wird.](/images/dashboard/enforcement-editor.png) + ![Der Maschinen-Bereitstellungseditor mit einer ausgewählten veröffentlichten Policy-Version im Beobachtungsmodus, bevor die Bereitstellung angewendet wird.](/images/dashboard/enforcement-editor.png) - - Führen Sie eine neue Agent-Sitzung auf dieser Maschine aus und öffnen Sie dann **Beobachten → Policy**. Wählen Sie die Maschine aus und bestätigen Sie, dass die Demo-Policy in der Policy-Zuordnung und der Entscheidungszeitlinie angezeigt wird. Der Beobachtungsmodus zeichnet auf, was die Policy tun würde, ohne die Aktion zu blockieren. + + Starten Sie eine neue Agent-Sitzung auf dieser Maschine und öffnen Sie dann **Beobachten → Policy**. Wählen Sie die Maschine aus und bestätigen Sie, dass die Demo-Policy in der Policy-Zuordnung und der Entscheidungszeitachse erscheint. Der Beobachtungsmodus zeichnet auf, was die Policy tun würde, ohne die Aktion zu blockieren. ![Die Policy-Seite mit Entscheidungsgesamtzahlen, Durchsetzungsaktivität im Zeitverlauf sowie lokalen und Cloud-verwalteten Policy-Zuordnungen.](/images/dashboard/policy-observe.png) - Die Erstellung von Cloud-Policies und die Fleet-Bereitstellung sind administrative Workflows. Verwenden Sie die lokale CLI, um dieselbe Policy vor der Veröffentlichung zu validieren: + Das Erstellen von Cloud-Policies und die Fleet-Bereitstellung sind administrative Workflows. Verwenden Sie die lokale CLI, um dieselbe Policy vor der Veröffentlichung zu validieren: ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -35,13 +35,13 @@ Verwenden Sie eine Policy erst dann, wenn Sie die unsichere Aktion und die legit failproofai config --status ``` - Verwenden Sie `fp`, um Cloud-sichtbare Policy-Entscheidungen zu prüfen: + Verwenden Sie `fp`, um in der Cloud sichtbare Policy-Entscheidungen zu prüfen: ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - Die Cloud CLI stellt keine Routen für die ausschließlich durch Administratoren verwaltete Durchsetzungsbereitstellung bereit. Veröffentlichen Sie Versionen über **Admin → Policy-Editor** und stellen Sie sie über **Admin → Durchsetzung** bereit. + Beide Schritte sind auch über die CLI verfügbar: `fp policies publish ` erstellt eine Version und `fp fleet deploy --add ` stellt sie auf einer Maschine bereit. Die entsprechenden Dashboard-Funktionen sind **Admin → Policy-Editor** und **Admin → Durchsetzung**. \ No newline at end of file diff --git a/docs/de/start/integrations.mdx b/docs/de/start/integrations.mdx new file mode 100644 index 000000000..ce249e457 --- /dev/null +++ b/docs/de/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "Agent instrumentieren" +sidebarTitle: "Frameworks" +description: "Jedes unterstützte Agent-Framework mit einem einzigen Aufruf mit Failproof AI verbinden." +icon: "plug" +--- + +Dein Agent erzeugt bereits alles, was es wert ist, aufgezeichnet zu werden — Modellaufrufe, Tool-Aufrufe, Node-Grenzen, menschliche Wartezeiten, Fehler. Das Framework wirft es weg. Das SDK behält es. + + + + Ein selbst geschriebener Agent oder einer, der hier nicht aufgelistet ist. + + + Graphs, Nodes, Tools, Retriever, Modelle. + + + Crews, Flows, Agenten nach Rolle, Tools. + + + Workflows, Steps, Funktionsagenten, Retriever. + + + Typisierte Agenten, Fähigkeiten, Tools, Wiederholungsversuche. + + + +## Drei Zeilen, egal welches Framework + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # erkennt die importierten Frameworks automatisch + +with failproofai_sdk.session(): + ... # dein bestehender Agent-Aufruf, unverändert +``` + +Keine Dekoratoren auf deinen Funktionen, kein Callback-Parameter, keine IDs, die durch deinen Code gefädelt werden. Nur der Aufruf innerhalb der Session unterscheidet sich: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # unter `async with failproofai_sdk.session():` + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +Das Extra-Paket installiert das **Framework**. Jeder Adapter ist im Basis-Wheel enthalten, sodass ein Projekt, das sein Framework bereits hat, kein zusätzliches Paket benötigt. + +## Prüfen, ob Daten angekommen sind + +Führe eine instrumentierte Session aus und öffne dann **Observe → Sessions**, um deine Umgebung auszuwählen. Der Lauf erscheint als rekonstruierter Trace. + +Wenn nichts ankommt, prüfe die Verbindung des Rechners mit `failproofai config --status`. Siehe [Capture einrichten](/de/start/setup). + + + Prüfe nicht das Spool-Verzeichnis, um die Zustellung zu bestätigen. Der Failproof-Daemon erfasst und löscht jeden Batch innerhalb von Millisekunden — beim Lesen konkurrierst du daher mit dem Collector und siehst weit weniger Events, als tatsächlich gesendet wurden. + + +## Nächste Schritte + +Jeder oben verlinkte Quickstart führt zum vollständigen Guide — was aufgezeichnet wird, Optionen, Streaming, Span-Benennung und typische Probleme, auf die man stößt. Diese Guides befinden sich unter **Trace Agents → Plug in your agent**. + + + + Das Datenmodell, die IDs, die Event-Typen und wie Events die Cloud erreichen. + + + Kausalität durch eine Session verfolgen statt durch unzusammenhängende Logs. + + + Die gerade erfassten Sessions auditieren. + + \ No newline at end of file diff --git a/docs/de/start/integrations/crewai.mdx b/docs/de/start/integrations/crewai.mdx new file mode 100644 index 000000000..4c5ffde81 --- /dev/null +++ b/docs/de/start/integrations/crewai.mdx @@ -0,0 +1,224 @@ +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "Instrumentiere Crews, Flows, Agents nach Rolle, Tools, Speicher und menschlichem Feedback." +icon: "/images/frameworks/crewai.svg" +--- + +## Installation + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +Unterstützt: `crewai` 1.13 bis 2.0. Version 1.13 ist das Release, das `started_event_id` und normalisierte Token-Nutzung eingeführt hat – beides wird vom Adapter benötigt, um Ereignisse zuzuordnen und Tokens zu erfassen. + +## Instrumentierung + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` registriert einen Listener auf dem modulweiten Ereignis-Bus von CrewAI und abonniert je einen Handler pro Ereignisklasse. An deiner Crew, den Agents, Tasks oder Tools ändert sich nichts. + +## Was aufgezeichnet wird + +| CrewAI | Failproof-Ereignis | +| --- | --- | +| Crew-Kickoff | `agent_start`, `agent_end` | +| `Agent.kickoff()` (Lite-Agent ohne Crew) | `agent_start`, `agent_end`, mit `agent_id` aus der Rolle | +| Flow-Start und -Ende | `agent_start`, `agent_end`; eine innerhalb einer Flow-Methode gestartete Crew wird darunter verschachtelt | +| Agent-Ausführung | Verschachteltes `agent_start`, `agent_end`, mit `agent_id` aus der Rolle. Bei einem hierarchischen Prozess wird ein delegierter Mitarbeiter unter dem Manager verschachtelt, nicht neben ihm | +| Task | Nichts; als Link aufgezeichnet, sodass Kinder auf die Crew aufgelöst werden | +| Flow-Methode, Guardrail | `hook_triggered`, `hook_completed` | +| Tool-Nutzung | `tool_use`, `tool_result` | +| Speicher- und Wissensoperationen | `tool_use`, `tool_result`, benannt nach der betroffenen Oberfläche | +| LLM-Aufruf | `model_request`, `model_response`, mit Token-Nutzung | +| Stream-Chunk | Im Response zusammengefasst als Chunk-Anzahl und Zeit bis zum ersten Token | +| Menschliches Feedback angefordert | `human_wait`, `agent_pause` | +| Menschliches Feedback erhalten | `agent_resume`, `human_input` | +| Agent-Ausführungsfehler | `error`, dann `agent_end` mit Ergebnis `failed` | + +Ein Task erzeugt bewusst keine Ereignisse. Ein CrewAI-Task ist ein Teilbereich der Agent-Ausführung, die ihn ausführt – würde man beides erfassen, würde jede Zeile doppelt erscheinen und als Geschwister dargestellt. Die Task-ID und der Name werden stattdessen in den eigenen Ereignissen des Agents mitgeführt. + +Speicher- und Wissensoperationen werden als Tools aufgezeichnet, benannt nach der betroffenen Oberfläche, damit sie neben deinen echten Tools erscheinen und deren Latenz verglichen werden kann. + +Bei einer hierarchischen Crew macht die Verschachtelung den Trace lesbar: + +```text +crew +└─ manager + ├─ researcher delegiert + └─ writer delegiert +``` + +CrewAI ordnet eine delegierte Ausführung dem `delegate_work_to_coworker`-**Tool-Ereignis** zu, nicht direkt dem Manager – der Adapter folgt diesem Link entsprechend. Ohne ihn würde jeder Agent als Geschwister jedes anderen erscheinen und die Delegierungsstruktur ginge verloren. + +## Beispiel + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # wird zu agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +Die Übergabe ist im Trace sichtbar: Der `analyst`-Span schließt sich, der `writer`-Span öffnet sich, und beide liegen innerhalb eines einzigen `crew`-Spans. + +## Spans benennen + +`agent_id` stammt aus `Agent(role=...)`, was ihn zu einer lesbaren Dashboard-Facette macht. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # ein Facetten-Eintrag pro Run +``` + +`agent_id` ist eine Spalte mit geringer Kardinalität. Eine Rolle, die eine Run-ID oder einen Zeitstempel enthält, verschlechtert sie für jede Abfrage. Sieht eine Rolle wie eine ID aus, lehnt der Adapter sie ab und legt den tatsächlichen Wert stattdessen in einem Payload-Feld ab. + +## Session steuern + +Wird in dieser Reihenfolge aufgelöst, erster Treffer gewinnt: + +1. `instrument("crewai", session_id=...)` +2. Der umschließende `failproofai_sdk.session()`-Scope +3. Eine generierte `uuid4().hex`, einmal pro Crew oder Flow + +Umhülle den Kickoff, um ihn pro Run zu steuern: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## Optionen + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # jeden Run an eine feste Session-ID binden +) +``` + +`session_id` ist die einzige Option, die dieser Adapter liest. Prompts und Completions werden immer aufgezeichnet, auf das Payload-Budget gekürzt. + +## Human in the Loop + +CrewAI hat **zwei** Human-in-the-Loop-Oberflächen, und beide werden als dieselben vier Ereignisse aufgezeichnet. + +`@human_feedback` auf einer Flow-Methode läuft über den Ereignis-Bus von CrewAI: Die Laufzeit sendet ein Ereignis, bevor sie auf eine Person wartet, und ein weiteres nach der Antwort. + +`Task(human_input=True)` hingegen nicht. Es ruft `input()` im eigenen Input-Provider von CrewAI auf und sendet keinerlei Ereignis – daher umhüllt der Adapter diesen Provider direkt. Ohne diese Maßnahme wäre das gesamte menschliche Warten unsichtbar und würde als aktive Agent-Zeit abgerechnet. + +In beiden Fällen erhältst du: + +```text +human_wait der Prompt und seine Optionen +agent_pause startet die Pausenzeitr uhr +agent_resume stoppt sie +human_input die Antwort, mit gemessener Wartezeit +``` + +`agent_pause` bis `agent_resume` ist das einzige Paar, das Pausenzeit erfasst. Ohne es wird ein zehnminütiges menschliches Warten als zehn Minuten aktive Agent-Zeit abgerechnet. + + + CrewAI setzt keine Korrelations-ID auf einem der beiden Human-Feedback-Ereignisse, sodass der Adapter sie anhand des Flow- und Methodennamens zuordnet und auf die zuletzt geöffnete Pause zurückfällt. Das ist korrekt, da eine Konsoleneingabe blockiert. Wenn du einen nebenläufigen Feedback-Provider baust, setze `request_id` auf beiden Ereignissen. + + + + Da der `Task(human_input=True)`-Pfad den Input-Provider von CrewAI umhüllt statt ein Ereignis zu abonnieren, wird er bei `uninstrument()` wiederhergestellt und gibt jede Ausnahme von `input()` unverändert weiter – einschließlich `KeyboardInterrupt`. + + +## Häufige Probleme + + + + Eine `role` enthält eine UUID, einen Zeitstempel oder ein lauf-spezifisches Suffix. Verwende eine stabile, menschenlesbare Rolle und lege die lauf-spezifische ID stattdessen in der Task-Beschreibung ab. + + + + Der Ereignis-Bus ist asynchron, und `kickoff()` kehrt zurück, bevor die letzten Handler durchgelaufen sind. Leere ihn zuerst: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + Dies ist eine Eigenschaft von CrewAI, nicht des SDK. + + + + `agent_end` schließt offene Pausen zwangsweise, aber nicht Tools oder Modelle – ein Run, der innerhalb eines Tool-Aufrufs abbricht, lässt diesen Span offen. Ein normaler Teardown schließt alles noch Offene und markiert es als unvollständig. Nur ein `SIGKILL` lässt es hängen, da dann kein Code mehr ausgeführt werden kann. + + + + Prüfe in dieser Reihenfolge: `instrument()` wurde vor `kickoff()` aufgerufen; es gibt ein `with failproofai_sdk.session():` darum; `crewai` ist Version 1.13 oder neuer; `FAILPROOFAI_SDK_STRICT=1` ist gesetzt, damit ein fehlerhafter Hook eine Ausnahme auslöst statt stillschweigend ignoriert zu werden. + + + +## Weiter + + + + Paare, IDs, Session-Lebenszyklus und Übermittlung. + + + Verfolge die Kausalität durch die soeben aufgezeichnete Session. + + + LangGraph, LlamaIndex, Pydantic AI und individuelle Agents. + + \ No newline at end of file diff --git a/docs/de/start/integrations/custom-agents.mdx b/docs/de/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..824fb42f3 --- /dev/null +++ b/docs/de/start/integrations/custom-agents.mdx @@ -0,0 +1,739 @@ +--- +title: "Eigene Agenten" +sidebarTitle: "Eigene Agenten" +description: "Instrumentiere einen selbst geschriebenen Agenten oder ein Framework ohne Adapter." +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. + +Das ist dieselbe API, die die vier Framework-Adapter im Hintergrund nutzen. Sie sind lediglich Übersetzungsschichten darüber. + +## Installation + +```bash +pip install failproofai-sdk +``` + +Keine Extras, keine Abhängigkeiten. + +## Instrumentierung + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # ein Durchlauf + with failproofai_sdk.agent("planner"): # eine Arbeitseinheit + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) # ein Tool-Aufruf +``` + +Von oben nach unten gelesen, sagt es genau das, was es bedeutet: + +| Umschließen mit | Bedeutet | +| --- | --- | +| `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 | + +Und was jeder Scope 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 | + +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`. + +Verschachtelte Agenten bilden den Baum. `parent_id` und Tiefe werden aus dem Stack berechnet: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## Wie ein Scope schließt + +`agent()` behandelt Exceptions für dich: + +| Was passiert ist | Events | Ergebnis | +| --- | --- | --- | +| Keine Exception | `agent_end` | `success` | +| `Exception` | `error`, dann `agent_end` | `failed` | +| `KeyboardInterrupt`, `SystemExit` | `error`, dann `agent_end` | `failed` | +| `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. + +## 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. + +| Familie | Öffnet | Schließt | Eigenständig | +| --- | --- | --- | --- | +| **Agenten** | `agent_start` | `agent_end` | — | +| | `agent_pause` | `agent_resume` | — | +| **Modelle** | `model_request` | `model_response` | — | +| **Tools** | `tool_use` | `tool_result` | — | +| **Hooks** | `hook_triggered` | `hook_completed` | — | +| **Menschen** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **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. + + + +```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 Models +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 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 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 Failures +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **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 – das musst du immer selbst 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. + + +## Beispiel + +Eine Tool-Calling-Schleife gegen die OpenAI API, ohne Agent-Framework: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +MODEL = "gpt-4o-mini" + + +def turn(messages: list): + """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 + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +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 + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +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 + +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: 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. + +## 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. + +| Der Nahtpunkt | Was du schreibst | Was landet | +| --- | --- | --- | +| Der Durchlauf | `session()` + `agent()` | `agent_start`, `agent_end` | +| 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 was auch immer das Framework als Tool-Wrapper oder Middleware bezeichnet. + + ```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(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **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. + + + + **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 Nahtpunkte 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. + + Das manuelle Mappen der Nahtpunkte zeichnet dieselben Events mit derselben Genauigkeit auf wie ein mitgelieferter Adapter. + + +## Tiefer eintauchen + +Wie die Aufzeichnung tatsächlich funktioniert. Nichts davon ist nötig, um loszulegen. + + + + + +Jede Aufzeichnung hat dieselbe Form: Ein Span öffnet sich, Arbeit wird darin verschachtelt, und jedes öffnende Event bekommt ein schließendes. + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + 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. + +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. + + + + ```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 out-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 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. + + + + ```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 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 out-tok + 9 +5.727s agent_end analyst · success + 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. + + + + ```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 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 + ... zweite Iteration + 26 +7.038s agent_end Agent · success + ``` + + Die Agent-Schleife selbst ist sichtbar, nicht nur ihre Modellaufrufe. + + + + ```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 + 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 + 8 +8.119s agent_end agent · success + ``` + + Keine Hook-Paare: Pydantic AI hat keine Node- oder Step-Grenzen zum Einrahmen. + + + + ```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 out-tok + 6 +0.000s agent_end main · success + ``` + + 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 du schließt – sie ist eine Gruppe von Events, die eine `session_id` teilen. + +Der Status wird aus der Form der Trace abgeleitet: + +| Status | Wann | +| --- | --- | +| `ongoing` | Mindestens ein Span ist noch offen | +| `paused` | Ein `agent_pause` hat kein passendes `agent_resume` | +| `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. + + + 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. + + + + + + +`session_id` und `agent_id` sind bei jeder Event-Methode optional. Werden sie weggelassen, werden sie aus dem umschließenden Scope aufgelöst: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + 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. + +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 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 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 + +Der erste Treffer gewinnt: + +1. Eine explizite `session_id`-Option +2. Metadaten pro Aufruf +3. Der umschließende `session()`-Scope +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. + +#### `agent_id` niedrig 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. + +Adapter schützen diese Spalte für dich: + +| Was das Framework liefert | Aufgezeichnet als | Warum | +| --- | --- | --- | +| `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-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. + + + **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 | +| --- | --- | +| Agenten | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| Modelle | `model_request`, `model_response` | +| Tools | `tool_use`, `tool_result` | +| Hooks | `hook_triggered`, `hook_completed` | +| Menschen | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| Fehler | `error` | + +Welches Framework was aufzeichnet, gemessen aus den obigen Durchläufen: + +| 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 | +| Error | Ja | Ja | Ja | Ja | Automatisch | +| 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 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 | +| --- | --- | --- | +| `agent_start` | `agent_end` | `outcome`, `summary` | +| `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 | + + + 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 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 ziehen das **Framework** nach, nicht den Adapter. + +```python +import failproofai_sdk # lädt nichts außerhalb der Standardbibliothek +failproofai_sdk.instrument() # importiert nur die Adapter, die du tatsächlich brauchst +``` + +`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()`. + + +```python +failproofai_sdk.instrument() # jedes bereits importierte Framework +failproofai_sdk.instrument("crewai") # genau eines, nach Name +failproofai_sdk.uninstrument("crewai") # rückgängig machen +``` + +| Name | Akzeptiert auch | +| --- | --- | +| `langchain` | `langgraph`, `langchain_core` | +| `crewai` | — | +| `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: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +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. + + 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`, 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* 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. + + + +```python Wrong +import failproofai_sdk +failproofai_sdk.instrument() # sys.modules hat noch kein langchain -> () + +import langchain # zu spät, nichts ist verdrahtet +``` + +```python Right +import langchain # Framework zuerst importieren +import failproofai_sdk + +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. +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. + + + + + +```mermaid +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"] + 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 | +| 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 | + +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: + +```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. + + + **`collector.redact` gilt nicht für deine SDK-Events.** Es sieht sie nie. + + +Der Daemon **versendet** deine Batches. Er öffnet oder überschreibt sie nicht. + +| Events | Geschrieben von | Durch `collector.redact` bereinigt? | +| --- | --- | --- | +| CLI-Session-Transkripte | Dem Daemon | Ja | +| Hook-Aktivität | Dem Daemon | Ja | +| **Alles, was das SDK sendet** | **Deinem Prozess** | **Nein** | + +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:** + + - 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 – Prompts und Completions werden also 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. + + `collector.redact` ist kein Ersatz für beides. + + + + **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 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 den Daemon zuerst. + + + + + +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 | 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 „es ist nicht abgestürzt". Setze `FAILPROOFAI_SDK_STRICT=1`, um einen verschluckten Fehler laut zu machen. + + + + + +## Häufige Probleme + + + + 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 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()` ein. Siehe [Threads und Async](#threads-und-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_`. + + + + `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. + + + Folge der Kausalität durch die soeben aufgezeichnete Session. + + + LangGraph, CrewAI, LlamaIndex und Pydantic AI. + + \ No newline at end of file diff --git a/docs/de/start/integrations/langchain.mdx b/docs/de/start/integrations/langchain.mdx new file mode 100644 index 000000000..ccf8901b0 --- /dev/null +++ b/docs/de/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain and LangGraph" +sidebarTitle: "LangChain and LangGraph" +description: "Graphs, Nodes, Tools, Retriever und Modellaufrufe mit einem einzigen Aufruf instrumentieren." +icon: "/images/frameworks/langchain.svg" +--- + +Ein Adapter für beide. LangGraph läuft auf dem Callback-Manager von `langchain-core`, daher instrumentiert das Einbinden des einen automatisch auch das andere. + +## Installation + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Für LangChain ohne LangGraph: `failproofai-sdk[langchain]`. + +Unterstützt: `langchain-core` 1.4.7 bis 2.0, `langgraph` 1.2 bis 2.0. Außerhalb dieses Bereichs wird der Adapter trotzdem installiert und gibt einmalig eine Warnung aus. + +## Instrumentierung + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` registriert einen Tracer über `langchain_core.tracers.context.register_configure_hook`. LangChain fügt ihn in jeden Callback-Manager ein, den es erstellt – Graphs, Tools und Modelle werden also aufgezeichnet, ohne dass eine Aufrufstelle geändert werden muss, auch nicht in Bibliotheken, die man selbst nicht geschrieben hat. + +## Was aufgezeichnet wird + +| LangChain oder LangGraph | Failproof-Ereignis | +| --- | --- | +| Root-Run | `agent_start`, `agent_end` | +| LangGraph-Node | `hook_triggered`, `hook_completed` | +| Kompilierter Subgraph | Verschachteltes `agent_start`, `agent_end` | +| Tool-Run | `tool_use`, `tool_result` | +| Retriever-Run | `tool_use`, `tool_result`, Ausgabe zusammengefasst | +| Chat-Modell oder LLM-Run | `model_request`, `model_response`, mit Token-Nutzung | +| Gestreamte Tokens | Als Chunk-Anzahl und Zeit bis zum ersten Token in die Antwort eingefaltet. Token-Counts benötigen `ChatOpenAI(stream_usage=True)` – siehe unten | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, korreliert über die `Interrupt.id` – auch wenn das Resume in einem anderen Prozess gegen denselben Checkpointer erfolgt | +| Unbehandelte Ausnahme | `error`, dann `agent_end` mit Ergebnis `failed` | + +**Ein Node wird zu einem Hook, nicht zu einem verschachtelten Agent.** `agent_id` ist das primäre Merkmal auf jeder Dashboard-Oberfläche – `retrieve`, `grade_documents` und `should_continue` zu Agents zu befördern würde die Ansicht überladen und die Session nach dem Node benennen, der zufällig als Erstes ausgeführt wurde. + +Hook-Spans werden gleich dargestellt und bieten dennoch eine knotenspezifische Latenzsicht. + + + **Nodes können beliebig benannt werden.** Ein Node-Run wird anhand seiner *Form* identifiziert – ein Nicht-Blatt-Run mit LangGraphs eigenem Step-Tag – niemals anhand seines Namens. + + +| Eigener Code | Was aufgezeichnet wird | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | Das Tool | +| `add_node("ChatOpenAI", ...)` | Der Modellaufruf | + +Einen Node nach dem darin ausgeführten Objekt zu benennen ließ dessen Ereignisse früher verschwinden. Das ist nicht mehr der Fall. + +### Streaming + +`.stream()` und `.astream()` erzeugen keine Token-Ereignisse. Sie werden in das abschließende `model_response` eingefaltet: + +| Feld | Inhalt | +| --- | --- | +| `fw_chunks` | Anzahl der eingegangenen Chunks | +| `fw_ttft_ms` | Zeit bis zum ersten Token | + +### Token-Counts bei gestreamten Antworten + +Ein separates Thema, das leicht übersehen wird: OpenAI sendet die Nutzung bei einer gestreamten Antwort **nur auf Anfrage**. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # ohne dies keine Tokens +``` + +Der Adapter zeichnet auf, was das Framework liefert. Ohne dieses Flag gibt es nichts aufzuzeichnen, und `model_response` kommt ohne Token-Counts an. + +## Beispiel + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## Spans benennen + +Standardmäßig übernimmt der Root-Span den eigenen Namen des Graphs. Durch ein Wrapping lässt sich ein selbst gewähltes Label vergeben: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +Bei Multi-Agent-Setups werden die Scopes verschachtelt. Jeder Worker wird zu einem Child-Span mit `parent_id`: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +`agent_id` sollte eine niedrige Kardinalität haben. Rolle oder Node-Name verwenden, niemals eine UUID oder einen run-spezifischen String. + +## Session steuern + +Die Session-ID wird in folgender Reihenfolge aufgelöst, wobei der erste Treffer gewinnt: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. Der umschließende `failproofai_sdk.session()`-Scope +4. `metadata["session_id"]`, `metadata["conversation_id"]` oder `metadata["thread_id"]` +5. Die Root-Run-ID + +Sie wird niemals von Grund auf neu generiert, da eine synthetisierte ID einen Run auf mehrere Sessions aufteilt. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## Optionen + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # jeden Run an eine Session-ID pinnen + include_chains=set(), # Allowlist für intermediäre Chains als Hook-Paare + capture_content=True, # False entfernt Prompts und Completions aus den Payloads + graph_callbacks=True, # erstklassige Interrupt- und Resume-Unterstützung, benötigt langgraph 1.2+ +) +``` + +`capture_content=False` für regulierte Daten verwenden. Struktur, Timings, Token-Counts, Tool-Namen und Ergebnisse werden weiterhin aufgezeichnet; Nachrichteninhalte nicht. + +`include_chains` gilt nur für **verschachtelte** Runs. Ein Runnable, das auf der obersten Ebene aufgerufen wird, ist die Root der Session und wird daher zum Agent-Span statt zum Hook-Paar – eine Benennung hier hat keinen Effekt. + +## Human in the Loop + +`interrupt()` erzeugt vier Ereignisse, und keines der Paare ist redundant: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +`human_wait` bis `human_input` enthält den Prompt und die Antwort (beides wird bei `capture_content=False` weggelassen, ebenso wie Retrieval-Dokumentquellen – die Dokumentanzahl bleibt erhalten). `agent_pause` bis `agent_resume` ist das einzige Paar, das die Pause-Zeit erfasst; ohne es wird eine zehnminütige menschliche Wartezeit als aktive Agent-Zeit gewertet. Der Root-Span bleibt über die Pause hinweg offen und hält beide Aufrufe in einer Session. + +## Häufige Probleme + + + + `create_react_agent` propagiert die Ausnahme. Um dem Modell zu ermöglichen, den Fehler zu sehen und fortzufahren, den Tool-Node explizit aufbauen: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + Der Fehler wird in jedem Fall als `tool_result` mit einem Fehler aufgezeichnet. Das entscheidet nur, ob der Run ihn überlebt. + + + + Ein direktes `llm.invoke()` außerhalb eines Graphs hat keinen übergeordneten Run und öffnet daher einen Root-Span, in dem das Modellpaar ausgegeben wird. Das Dashboard ordnet Blätter einem offenen Agent zu, daher ist der Span beabsichtigt. Benennen: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + Es wurde ein Failproof-Handler in `config={"callbacks": [...]}` übergeben und zusätzlich `instrument()` aufgerufen. Den Handler entfernen. Der Configure-Hook deckt bereits jeden Callback-Manager im Prozess ab. + + + + Das ist nicht der Fall. LangGraph löst `GraphInterrupt` über denselben Pfad wie eine echte Ausnahme aus, weshalb jede Pause den Tracer als Fehler-Callback erreicht. Jede `GraphBubbleUp`-Unterklasse wird stattdessen als Kontrollfluss behandelt, sodass eine Genehmigung keinen roten Fehler erzeugt. + + + + In dieser Reihenfolge prüfen: `instrument()` wurde vor der Graph-Ausführung aufgerufen; ein `with failproofai_sdk.session():` umschließt den Aufruf; `FAILPROOFAI_SDK_STRICT=1` ist gesetzt, sodass ein fehlerhafter Hook eine Ausnahme auslöst statt unterdrückt zu werden. + + + +## Weiter + + + + Paare, IDs, Session-Lebenszyklus und Zustellung. + + + Kausalität durch die gerade aufgezeichnete Session verfolgen. + + + CrewAI, LlamaIndex, Pydantic AI und benutzerdefinierte Agents. + + \ No newline at end of file diff --git a/docs/de/start/integrations/llamaindex.mdx b/docs/de/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..1c6ed1ff3 --- /dev/null +++ b/docs/de/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "Workflows, Steps, Function-Agents und Retriever instrumentieren." +icon: "/images/frameworks/llamaindex.svg" +--- + +## Installation + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +Unterstützt: `llama-index-core` 0.14.23 bis 0.15. Ab 0.14.23 überträgt der Workflow-Stream die typisierten Agent-Events, die dieser Adapter liest. Darunter fehlen sowohl Modellnamen als auch die Agent-Struktur. + +## Instrumentierung + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +Die Agent-API von LlamaIndex ist asynchron. Jeder Scope funktioniert sowohl mit `async with` als auch mit `with` und erzeugt identische Events. + +`instrument()` hängt einen Event-Handler und einen Span-Handler an den globalen Dispatcher von LlamaIndex. Gemeinsam machen sie die Agent-Schleife sichtbar – nicht nur deren Modellaufrufe. + + + Ohne ein zusätzliches Argument an Ihrem LLM ist jede Token-Anzahl im Trace null. Siehe [Token-Anzahlen](#token-counts) weiter unten. + + +## Token-Anzahlen + +`FunctionAgent` ruft `astream_chat` auf, und `llama-index-llms-openai` sendet beim Streamen kein `stream_options={"include_usage": True}`. Der Provider sendet daher niemals den Usage-Chunk, und es gibt nichts, das eine Instrumentierung lesen könnte. + +Dies ist ein vorgelagertes LlamaIndex-Verhalten. Aktivieren Sie es an Ihrem LLM: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +Gemessen am selben Run und Modell: + +| | Eingabe-Token | Ausgabe-Token | +| --- | --- | --- | +| Ohne | `null` | `null` | +| Mit | 148 | 17 | + +Nicht-Streaming-Aufrufe (`llm.chat`, `llm.achat`) melden die Nutzung ohne Konfiguration. Nur der Streaming-Pfad – der Standard-Agent-Pfad – benötigt dies. + +## Was aufgezeichnet wird + +| LlamaIndex | Failproof-Event | +| --- | --- | +| `Workflow.run`-Root-Span | Session, `agent_start`, `agent_end` | +| Verschachtelter `Workflow.run`-Span | Verschachteltes `agent_start`, `agent_end` | +| Workflow-Step-Span | `hook_triggered`, `hook_completed` | +| LLM-Chat-Start und -Ende | `model_request`, `model_response` | +| `FunctionTool.call`-Span | `tool_use`, `tool_result` | +| Retrieval-Start und -Ende | `tool_use`, `tool_result`, Ausgabe zusammengefasst | +| Embeddings | Nichts, außer `embeddings=True` | +| Ein Tool wartet auf eine Person | `human_wait`, `agent_pause`, dann `agent_resume`, `human_input` | +| `AgentWorkflow`-Handoff | Ein verschachteltes `agent_start`, `agent_end` pro Agent, dem Workflow zugeordnet | +| Exception | `error`, dann `agent_end` mit Ergebnis `failed` und `agent_end.summary` mit dessen Namen | +| `handler.cancel_run()` | `agent_end` mit Ergebnis `cancelled` ohne `error` – ein Stopp-Button ist kein Fehler | + +`agent_id` ist der `FunctionAgent.name`, wenn Sie einen gesetzt haben, andernfalls der Workflow-Klassenname. Unter einem `AgentWorkflow` erhält jeder Agent, der an die Reihe kommt, seinen eigenen verschachtelten Span unter dem Workflow – ein Handoff erscheint daher als zwei Agenten statt als einer. + +Die Retrieval-Ausgabe wird zusammengefasst statt vollständig ausgegeben. Ein Retriever gibt Dokumente zurück, und deren vollständige Speicherung im Payload würde Ihr Korpus bei jeder Anfrage einmal im Event-Store ablegen. Stattdessen werden Anzahl, Score-Bereich und gekürzte Ausschnitte gespeichert. + +## Beispiel + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +Die Agent-Schleife erscheint im Trace als Hook-Paare: `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool` und `aggregate_tool_results`. Da es sich um die eigene Schleife des Frameworks handelt, sind sie Hooks statt Agents – das hält `agent_id` aussagekräftig. + +## Spans benennen + +`agent_id` ist der `FunctionAgent.name`, wenn Sie einen gesetzt haben, andernfalls der Workflow-Klassenname. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +In einem `AgentWorkflow` ist dieser Name auch der, unter dem jeder Handoff aufgezeichnet wird: + +```text +AgentWorkflow parent span +├─ city_analyst turn 1 +├─ cost_analyst turn 2 +└─ city_analyst turn 3 — a new turn, not a reopened one +``` + +`agent_id` zeigt also **welcher Agent** die Arbeit erledigt hat, und `parent_id` zeigt **welchem Workflow** er angehörte. Ein Agent, der die Kontrolle später zurückgibt, öffnet einen zweiten Turn statt seinen ersten wieder aufzunehmen. + +Umschließen Sie den Run, um dies zu überschreiben oder mehrere Agenten unter einem gemeinsamen Parent zu gruppieren: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +Halten Sie `agent_id` mit niedriger Kardinalität. Es ist die primäre Facette auf jeder Dashboard-Oberfläche – verwenden Sie also einen Rollen- oder Workflow-Namen, niemals eine UUID oder einen pro-Run-generierten String. + +## Session steuern + +Dieser Adapter hat **keine `session_id`-Option**. Die Session kommt aus dem umschließenden Scope, andernfalls wird pro Workflow-Run ein `uuid4().hex` generiert: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## Optionen + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True zeichnet Embedding-Aufrufe als Tool-Paare auf + steps=True, # False verwirft Workflow-Step-Hook-Paare + capture_messages=True, # False verwirft JEDEN Payload: Prompts, Completions, + # Tool-Argumente und -Ausgaben, Step-I/O, Retrieval- + # Anfragen, Ziel und finale Antwort + capture_limit=8192, # Zeichen pro erfasstem Wert + stale_after=600.0, # Sekunden, bevor ein verlassenes LEAF zwangsweise geschlossen wird + reaper_interval=30.0, # wie oft der Reaper durchläuft; 0 deaktiviert ihn +) +``` + +| Option | Wann Sie sie ändern würden | +| --- | --- | +| `embeddings` | Nur beim Debuggen von Embedding-Latenz oder -Kosten einschalten. Ein Bulk-Index-Build umfasst Tausende von Aufrufen und begräbt die Timeline. | +| `steps` | Ausschalten, wenn Sie nur Modell- und Tool-Events wünschen und die Agent-Schleife als störend empfinden. | +| `capture_messages` | Für regulierte Daten ausschalten. Jeder Payload wird nicht mehr aufgezeichnet – Prompts, die Completion des Modells, Tool-Argumente und Rückgabewerte, Workflow-Step-Ein- und -Ausgabe, Retrieval-Anfragen, das Ziel des Agenten und seine finale Antwort. Struktur, Timings, Token und Ergebnisse werden weiterhin aufgezeichnet. | +| `capture_limit` | Zeichen pro erfasstem Wert vor dem Kürzen. Erhöhen Sie diesen Wert, wenn ein RAG-Prompt oder ein abgerufener Kontext abgeschnitten ankommt. | +| `stale_after` | Sekunden, bevor ein verlassenes **Leaf** – eine gestreamte Antwort, die niemand konsumiert hat, ein Modell- oder Tool-Span, dessen Schließung nie ankam – zwangsweise geschlossen wird, damit die Session sich auflöst statt dauerhaft `ongoing` zu bleiben. Dies schließt **nicht** einen verlassenen Run selbst: Ein Workflow, dessen Task ohne einen Exit-Signal des Dispatchers abgebrochen wird, lässt seinen `agent_start` offen bis `uninstrument()`. | +| `reaper_interval` | Sweep-Frequenz. Auf `0` setzen, um den Reaper vollständig zu deaktivieren. | + +## Human in the Loop + +Wird erfasst, wenn das Warten innerhalb eines Tools stattfindet: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +`ctx.wait_for_event` in einem gewöhnlichen Workflow-Step wird nicht erfasst. Die Runtime fängt den Drop ab, bevor er den Dispatcher erreicht – der Step beendet sich und läuft später erneut, ohne ein Signal, auf das eine Pause gestützt werden könnte. Das FunctionAgent-Muster, das LlamaIndex dokumentiert, wartet innerhalb eines Tools und wird vollständig erfasst. + +## Häufige Probleme + + + + Fügen Sie `additional_kwargs={"stream_options": {"include_usage": True}}` zu Ihrem LLM hinzu. Siehe [Token-Anzahlen](#token-counts). + + + + LlamaIndex hat kein standardisiertes Usage-Feld. Der Adapter versucht mehrere bekannte Strukturen, und eine Integration, die ihre Zähler anders benennt, passt zu keiner davon. + + Das rohe Dict wird immer mitgeschickt – prüfen Sie `usage` im Payload, um zu sehen, wie Ihr Provider sie nennt. + + Ein befülltes `usage` bei gleichzeitig leeren Token-Spalten ist beabsichtigt – das ist besser als eine sichere, aber falsche Zahl. + + + + Das ist die FunctionAgent-Schleife, ein Satz pro Iteration. Filtern Sie nach Hook-Namen im Dashboard. Diese Step-Timings sind meist der Grund, diesen Adapter statt eines reinen Modell-Adapters zu verwenden. + + + + Prüfen Sie in dieser Reihenfolge: `instrument()` wurde vor dem Run aufgerufen; ein `async with failproofai_sdk.session():` umschließt das `await`; `llama-index-core` ist 0.14.23 oder neuer; `FAILPROOFAI_SDK_STRICT=1` ist gesetzt, damit ein fehlerhafter Hook eine Exception wirft statt verschluckt zu werden. + + + +## Weiter + + + + Paare, IDs, Session-Lebenszyklus und Zustellung. + + + Die Kausalität durch die soeben erfasste Session verfolgen. + + + LangGraph, CrewAI, Pydantic AI und eigene Agenten. + + \ No newline at end of file diff --git a/docs/de/start/integrations/pydantic-ai.mdx b/docs/de/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..43ee97f52 --- /dev/null +++ b/docs/de/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "Typisierte Agenten, Tools, Modellaufrufe und Wiederholungsversuche instrumentieren." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## Installation + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +Unterstützt: `pydantic-ai-slim` 2.0 bis 3.0. Version 2.0 hat `Agent(instrument=...)` entfernt und das Capability-Protokoll eingeführt, auf dem dieser Adapter aufbaut. Version 1.x kann daher auf diese Weise nicht instrumentiert werden. + +## Instrumentierung + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` muss ausgeführt werden, bevor ein `Agent` erstellt wird. Die Capability wird beim Erstellen angehängt – ein vorher erstellter Agent enthält keine und zeichnet nichts auf, ohne dass ein Fehler ausgegeben wird, da technisch nichts schiefgelaufen ist. Dies ist die häufigste Ursache für einen leeren Trace mit diesem Adapter. + + +Agenten auf Modulebene sind dabei besonders tückisch: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # constructed at import time + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # run this FIRST +import agents # now the agent gets the capability +``` + +Zur Überprüfung: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI fasst die übergebene Liste zu einer einzelnen `root_capability` zusammen, daher gibt es kein `agent.capabilities`-Attribut zum Auslesen. + +Agenten, die während der Instrumentierung erstellt wurden, behalten die Capability – `uninstrument()` und erneutes Instrumentieren sind ohne Neuerstellung möglich. + +## Was aufgezeichnet wird + +| Pydantic AI | Failproof-Ereignis | +| --- | --- | +| Agent-Ausführung | `agent_start`, `agent_end` | +| Modellanfrage | `model_request`, `model_response`, mit Token-Nutzung | +| Tool-Aufruf | `tool_use`, `tool_result`, mit den vom Modell gesendeten Argumenten | +| `ModelRetry` aus einem Tool | `tool_result` mit einem Fehler | +| Unbehandelte Ausnahme | `error`, dann `agent_end` mit Ergebnis `failed` | + +Es gibt hier kein Hook-Paar und kein Human-in-the-Loop-Paar. Pydantic AI hat keine Node- oder Schrittgrenze zum Einklammern und keine eingebaute menschliche Pause – daher gibt es nichts zuzuordnen. Falls Sie beides implementieren, senden Sie die Ereignisse selbst – siehe [Benutzerdefinierte Agenten](/de/reference/custom-agents). + +`output_type` hat keinen Einfluss auf den Trace. Ein typisierter Lauf und ein String-Lauf erzeugen dieselben Ereignisse. + +## Beispiel + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +Im Trace erscheint `restock_eta` als `tool_result` mit einem Fehler, gefolgt von einem weiteren Modellaufruf, bei dem der Agent damit umgeht – der Lauf endet dennoch mit `success`. Beide Informationen werden festgehalten. + +## Fehler, Wiederholungsversuche und Kontrollfluss + +Pydantic AI wirft Ausnahmen für drei verschiedene Fälle, und der Adapter unterscheidet zwischen ihnen: + +| Ausnahme | Behandlung | Ergebnis | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | Echter Tool-Fehler | `tool_result` mit einem Fehler; der Lauf kann dennoch mit `success` enden | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | Kontrollfluss | Kein Fehler; der Lauf wird gesteuert | +| Alles andere | Ein Fehler | `error`, dann `agent_end` mit Ergebnis `failed` | + +`ModelRetry` gehört bewusst zur ersten Gruppe. Es bedeutet, dass ein Versuch tatsächlich fehlgeschlagen ist und das Modell aufgefordert wurde, es erneut zu versuchen – genau dafür ist das Fehlerfeld eines Tool-Spans gedacht. Eine Einordnung als Kontrollfluss würde echte Tool-Fehler hinter einem grünen Lauf verbergen. + +## Spans benennen + +Pydantic AIs eigener Run-Span heißt `agent`. Umschließen Sie den Aufruf, um ihm einen selbst gewählten Namen zu geben: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +Der Framework-Span wird dann unter `inventory` eingebettet, und dort hängen die Modell- und Tool-Ereignisse. + +Halten Sie `agent_id` mit geringer Kardinalität. Es ist die primäre Facette auf jeder Dashboard-Oberfläche – verwenden Sie daher einen Rollennamen, niemals eine UUID oder einen laufspezifischen String. + +## Session steuern + +Wird in dieser Reihenfolge aufgelöst, der erste Treffer gewinnt: + +1. `instrument("pydantic_ai", session_id=...)` +2. Der umschließende `failproofai_sdk.session()`-Scope +3. Die `conversation_id` des Laufs, dann dessen `run_id` +4. Eine generierte `uuid4().hex` + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## Optionen + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # pin every run to one session id + capture_content=True, # False drops prompts and completions from payloads +) +``` + +## Häufige Probleme + + + + Der `Agent` wurde erstellt, bevor `instrument()` ausgeführt wurde. Siehe den Hinweis oben und prüfen Sie `agent.root_capability.capabilities`. + + + + Ein bloßes `raise` wird weitergegeben – das ist das Design von Pydantic AI. Damit das Modell damit umgehen kann, verwenden Sie `ModelRetry` mit einer Nachricht, auf die es reagieren kann. Der Fehler wird in jedem Fall aufgezeichnet. + + + + Dieser untergeordnete Span ist Pydantic AIs eigener Run-Span, und dort hängen die Modell- und Tool-Ereignisse. Entfernen Sie Ihren eigenen Scope, wenn Sie einen einzelnen Span möchten – auf Kosten des benutzerdefinierten Namens. + + + + Pydantic AIs asynchroner Graph-Stack ist länger als das Feldlimit der Nutzlast, und die letzte Zeile eines Tracebacks ist die Ausnahme selbst. Dieses Feld wird von vorne statt von hinten gekürzt, sodass die benötigte Zeile erhalten bleibt. + + + +## Weiter + + + + Paare, IDs, Session-Lebenszyklus und Übertragung. + + + Kausalität durch die gerade aufgezeichnete Session verfolgen. + + + LangGraph, CrewAI, LlamaIndex und benutzerdefinierte Agenten. + + \ No newline at end of file diff --git a/docs/de/start/quickstart.mdx b/docs/de/start/quickstart.mdx index 80a72bdcf..515080a89 100644 --- a/docs/de/start/quickstart.mdx +++ b/docs/de/start/quickstart.mdx @@ -1,27 +1,27 @@ --- -title: "Schnellstart" -description: "Zeichne eine Agent-Session auf, finde einen Fehler und beginne, ihn zu verhindern." +title: "Quickstart" +description: "Erfasse eine Agent-Session, finde einen Fehler und verhindere ihn." icon: "zap" --- -Dieser Schnellstart bringt eine Maschine dazu, Sessions zu melden, führt ein Audit durch und stellt eine Policy bereit. Nutze die Skill-Methode oder folge den manuellen Schritten. +Dieser Quickstart richtet eine Maschine zum Melden von Sessions ein, führt ein Audit durch und stellt eine Policy bereit. Nutze die Skill-Option oder folge den manuellen Schritten. -**Welchen Weg nimmst du?** 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 [Führe deine erste Fehlerprüfung durch](/de/start/first-audit) wieder ein; Enforcement auf diesem Pfad erfordert einen Hook in deiner Laufzeitumgebung. +**Welcher Weg ist deiner?** 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 neuer. Wenn dein Agent kein Harness hat, instrumentiere ihn mit dem [Python SDK](/de/reference/custom-agents) für Tracing und Audits und steig dann bei [Ersten Fehlercheck ausführen](/de/start/first-audit) wieder ein; für Durchsetzung auf diesem Weg ist ein Hook in deiner Runtime erforderlich. - + ```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. ``` - Dein Agent untersucht das Projekt, wählt die passende Integration, führt das Setup durch und verifiziert es. Im [FailproofAI Skills-Repository](https://github.com/FailproofAI/skills) findest du einzelne Skills und erweiterte Installationsoptionen. + Dein Agent analysiert das Projekt, wählt die passende Integration, führt das Setup durch und überprüft es. Siehe das [FailproofAI Skills-Repository](https://github.com/FailproofAI/skills) für einzelne Skills und erweiterte Installationsoptionen. @@ -30,13 +30,13 @@ Dieser Schnellstart bringt eine Maschine dazu, Sessions zu melden, führt ein Au 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 Key mit `events:add` und `policies:pull`. -3. Kopiere das einmalige Secret und speichere es auf der Zielmaschine: +3. Kopiere das Einmal-Secret und speichere es auf der Zielmaschine: ```bash export FAILPROOFAI_KEY="" ``` - ## Installation + ## Installieren @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Session-Transkripte werden standardmäßig gesendet. Füge `--no-transcripts` hinzu, um Hook-Aktivitäten und Policy-Entscheidungen ohne Transkriptinhalt zu melden. + Session-Transkripte werden standardmäßig übertragen. Füge `--no-transcripts` hinzu, um Hook-Aktivitäten und Policy-Entscheidungen ohne Transkriptinhalte zu melden. - Wenn diese Maschine bereits Agent-Verlauf hat, kannst du die letzten sieben Tage vorab ansehen und importieren — warte dann, bis die Übertragung abgeschlossen ist. Überspringe diesen Schritt auf einer neuen Maschine. + Falls diese Maschine bereits Agent-Verlaufsdaten hat, zeige die letzten sieben Tage in der Vorschau an und importiere sie, dann warte bis die Übertragung abgeschlossen ist. Überspringe diesen Schritt auf einer neuen Maschine. ```bash failproofai backfill --since 7d --dry-run @@ -58,27 +58,27 @@ export FAILPROOFAI_KEY="" Öffne **Sessions** in Failproof AI und wähle eine importierte Session aus. - Damit wird Failproof AI an dein Harness angebunden und die 40 integrierten Policies werden installiert. Nutze sie, um lokale Policy-Entscheidungen zu sehen und Enforcement auszuprobieren, bevor Failproof AI deine Sessions auditiert und Policies für deine Agents schreibt. + Dadurch wird Failproof AI mit deinem Harness verbunden und die 40 integrierten Policies werden installiert. Nutze sie, um lokale Policy-Entscheidungen zu sehen und Durchsetzung auszuprobieren, bevor Failproof AI deine Sessions auditiert und Policies für deine Agents schreibt. - Lass den Installer dein Harness 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`. + Lass den Installer dein Harness erkennen oder gib eines explizit an. Jedes der 12 ist ein gültiger `--cli`-Wert — `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-Calls vor der Ausführung ist auf allen 12 verifiziert. Turn-End-Gates sind auf 8 verifiziert — siehe [Enforcement-Fähigkeiten](/de/reference/harnesses#enforcement-capability) für die harness-spezifische Matrix. + Das Blockieren eines Tool-Calls vor der Ausführung wird auf allen 12 unterstützt. Turn-End-Gates werden auf 8 unterstützt — siehe [Durchsetzungsfähigkeit](/de/reference/harnesses#enforcement-capability) für die Harness-spezifische Matrix. - Folge [Führe deine erste Fehlerprüfung durch](/de/start/first-audit). Verwende ein konkretes Ziel, z. B. „Finde Sessions, in denen der Agent ein fehlgeschlagenes Tool wiederholt hat, ohne seine Vorgehensweise zu ändern." + Folge [Ersten Fehlercheck ausführen](/de/start/first-audit). Nutze ein konkretes Ziel, zum Beispiel: „Sessions finden, in denen der Agent einen fehlschlagenden Tool-Call erneut versucht hat, ohne seinen Ansatz zu ändern." - Folge [Verhindere deinen ersten Fehler mit einer Policy](/de/start/first-policy). Beginne im Beobachtungsmodus, prüfe die Treffer und erzwinge dann die überprüfte Version. + Folge [Ersten Fehler mit einer Policy verhindern](/de/start/first-policy). Starte im Beobachtungsmodus, prüfe Treffer und setze dann die überprüfte Version durch. - Führe `failproofai config --status` aus. Ein gesundes Setup meldet die Cloud-Verbindung, den Daemon-Status und ob Enforcement pausiert ist. + Führe `failproofai config --status` aus. Ein gesundes Setup meldet die Cloud-Verbindung, den Daemon-Status und ob die Durchsetzung pausiert ist. \ No newline at end of file diff --git a/docs/de/start/quickstarts/crewai.mdx b/docs/de/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..8bb4c2479 --- /dev/null +++ b/docs/de/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "Installieren, instrumentieren und Ihren ersten Trace sehen." +icon: "/images/frameworks/crewai.svg" +--- + +Drei Schritte zu Ihrem ersten CrewAI-Trace. Informationen zu den Inhalten der einzelnen Events, Flows und zur Fehlerbehebung finden Sie in der [vollständigen Anleitung](/de/start/integrations/crewai). + +## Installation + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## Instrumentierung + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +An Ihrer Crew, Ihren Agents, Tasks oder Tools ändert sich nichts. `instrument()` abonniert den modulweiten Event-Bus von CrewAI. + +## Überprüfung des Eingangs + +Führen Sie es einmal aus und öffnen Sie dann **Observe → Sessions**, und wählen Sie Ihre Umgebung aus. Ihr Durchlauf erscheint als rekonstruierter Trace. + +Falls nichts ankommt, überprüfen Sie mit `failproofai config --status`, ob die Maschine verbunden ist. + + + Was aufgezeichnet wird, Flows, Token-Nutzung, Span-Benennung, Optionen und häufige Probleme. + \ No newline at end of file diff --git a/docs/de/start/quickstarts/custom-agents.mdx b/docs/de/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..7f85b72e1 --- /dev/null +++ b/docs/de/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "Eigene Agenten" +description: "Füge deinem Agenten drei `with`-Blöcke hinzu und er beginnt mit der Aufzeichnung." +icon: "code" +--- + +Für Agenten, die du selbst entwickelt hast, oder Frameworks, für die Failproof AI keinen Adapter anbietet. + +Du wrappst die bestehende Arbeit in `with`-Blöcke. Jeder Block zeichnet auf, wann er gestartet und beendet wurde und wie lange er gedauert hat — du musst sonst nichts aufrufen. + +## Installation + +```bash +pip install failproofai-sdk +``` + +Keine Extras, keine Abhängigkeiten. + +## Instrumentierung + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # ein Durchlauf + with failproofai_sdk.agent("planner"): # eine Arbeitseinheit + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) # ein Tool-Aufruf +``` + +Von oben nach unten gelesen erklärt sich der Code von selbst: + +| Wrapping-Block | Bedeutung | +| --- | --- | +| `session()` | Diese Events gehören zum selben Durchlauf | +| `agent()` | Eine Komponente erledigt Arbeit — gib ihr einen Namen, den du in einer Liste wiedererkennen würdest | +| `tool_call()` | Das ist ein Tool-Aufruf, und das ist sein Rückgabewert | + +Verschachtele die Blöcke so, wie dein Code es erfordert. IDs musst du nicht weitergeben: Jeder Block merkt sich, in welchem Kontext er sich befindet, sodass alles, was du aufzeichnest, automatisch dem richtigen Durchlauf und dem richtigen Agenten zugeordnet wird. `async with` funktioniert auf dieselbe Weise. + +## Überprüfung des Eingangs + +Führe den Code einmal aus, öffne dann **Observe → Sessions** und wähle deine Umgebung aus. Dein Durchlauf erscheint als rekonstruierter Trace. + +Wenn nichts ankommt, prüfe mit `failproofai config --status`, ob die Maschine verbunden ist. + + + Alle Event-Methoden, Verhalten bei Ausnahmen im Code, ein ausgearbeitetes Beispiel, Threads und Async sowie die Instrumentierung von Frameworks ohne Adapter. + \ No newline at end of file diff --git a/docs/de/start/quickstarts/langchain.mdx b/docs/de/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..216cbccb4 --- /dev/null +++ b/docs/de/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain und LangGraph" +description: "Installieren, instrumentieren und den ersten Trace ansehen." +icon: "/images/frameworks/langchain.svg" +--- + +Drei Schritte zu Ihrem ersten LangChain- oder LangGraph-Trace. Informationen zu Streaming, Human-in-the-Loop, Span-Benennung und weiteren Optionen finden Sie im [vollständigen Leitfaden](/de/start/integrations/langchain). + +## Installieren + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Für LangChain ohne LangGraph verwenden Sie `failproofai-sdk[langchain]`. + +## Instrumentieren + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +Keine Änderungen an den Aufrufstellen. `instrument()` registriert einen Tracer, den LangChain in jeden Callback-Manager injiziert, den es erstellt – so werden Graphs, Tools und Modelle erfasst, einschließlich solcher, die sich in Bibliotheken befinden, die Sie nicht selbst geschrieben haben. + +## Prüfen, ob alles angekommen ist + +Führen Sie die Anwendung einmal aus und öffnen Sie anschließend **Observe → Sessions**, um Ihre Umgebung auszuwählen. Ihr Durchlauf erscheint als rekonstruierter Trace. + +Falls nichts ankommt, überprüfen Sie die Verbindung des Rechners mit `failproofai config --status`. + + + Was aufgezeichnet wird, Streaming, Token-Zählungen, Span-Benennung, Session-Steuerung, Optionen und Human-in-the-Loop. + \ No newline at end of file diff --git a/docs/de/start/quickstarts/llamaindex.mdx b/docs/de/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..2b329ec43 --- /dev/null +++ b/docs/de/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "Installieren, instrumentieren und Ihren ersten Trace anzeigen." +icon: "/images/frameworks/llamaindex.svg" +--- + +Drei Schritte zu Ihrem ersten LlamaIndex-Trace. Informationen zu Workflow-Schritten, Retrieval, dem Reaper und weiteren Optionen finden Sie in [der vollständigen Anleitung](/de/start/integrations/llamaindex). + +## Installation + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## Instrumentierung + +Die Agent-API von LlamaIndex ist asynchron. Jeder Scope funktioniert sowohl mit `async with` als auch mit `with`. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + Ohne ein zusätzliches Argument an Ihrem LLM ist jede Token-Anzahl in Ihrem Trace null — `llama-index-llms-openai` fordert bei Streaming keine Nutzungsdaten an. Siehe [Token-Anzahlen](/de/start/integrations/llamaindex#token-counts). + + +## Überprüfen, ob die Daten angekommen sind + +Führen Sie es einmal aus und öffnen Sie dann **Observe → Sessions**, um Ihre Umgebung auszuwählen. Ihr Durchlauf erscheint als rekonstruierter Trace. + +Falls nichts ankommt, überprüfen Sie die Verbindung des Rechners mit `failproofai config --status`. + + + Token-Anzahlen, was aufgezeichnet wird, Workflow-Schritte, Retrieval, Optionen und häufige Probleme. + \ No newline at end of file diff --git a/docs/de/start/quickstarts/pydantic-ai.mdx b/docs/de/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..303f588b3 --- /dev/null +++ b/docs/de/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "Installieren, instrumentieren und den ersten Trace anzeigen." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +Drei Schritte bis zu Ihrem ersten Pydantic AI Trace. Für Tools, Wiederholungsversuche, Streaming und Optionen siehe [die vollständige Anleitung](/de/start/integrations/pydantic-ai). + +## Installieren + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## Instrumentieren + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` muss ausgeführt werden, **bevor** Sie einen `Agent` erstellen. Die Fähigkeit wird bei der Konstruktion angehängt, sodass ein zuvor erstellter Agent nichts aufzeichnet – ohne Fehlermeldung, da technisch nichts schiefgelaufen ist. Dies ist die häufigste Ursache für einen leeren Trace mit diesem Adapter. Besonders betroffen sind Agents auf Modulebene: Importieren Sie `failproofai_sdk` und rufen Sie `instrument()` auf, bevor Sie das Modul importieren, das die Agents erstellt. + + +## Überprüfen, ob die Daten ankamen + +Führen Sie die Anwendung einmal aus und öffnen Sie dann **Observe → Sessions**, um Ihre Umgebung auszuwählen. Ihr Durchlauf erscheint als rekonstruierter Trace. + +Falls keine Daten ankommen, überprüfen Sie die Verbindung des Rechners mit `failproofai config --status`. + + + Was aufgezeichnet wird, Tools und Wiederholungsversuche, Streaming, Span-Benennung, Optionen und häufige Probleme. + \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index 2f94a0d7a..37d3a58a8 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -241,7 +241,18 @@ "zh/start/first-audit", "zh/start/first-policy", "zh/start/setup", - "zh/start/concepts" + "zh/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "zh/start/quickstarts/custom-agents", + "zh/start/quickstarts/langchain", + "zh/start/quickstarts/crewai", + "zh/start/quickstarts/llamaindex", + "zh/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -266,6 +277,16 @@ "zh/sessions/dashboards", "zh/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "zh/start/integrations/custom-agents", + "zh/start/integrations/langchain", + "zh/start/integrations/crewai", + "zh/start/integrations/llamaindex", + "zh/start/integrations/pydantic-ai" + ] } ] }, @@ -352,11 +373,6 @@ "zh/reference/events-and-configuration", "zh/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -379,7 +395,18 @@ "ja/start/first-audit", "ja/start/first-policy", "ja/start/setup", - "ja/start/concepts" + "ja/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "ja/start/quickstarts/custom-agents", + "ja/start/quickstarts/langchain", + "ja/start/quickstarts/crewai", + "ja/start/quickstarts/llamaindex", + "ja/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -404,6 +431,16 @@ "ja/sessions/dashboards", "ja/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "ja/start/integrations/custom-agents", + "ja/start/integrations/langchain", + "ja/start/integrations/crewai", + "ja/start/integrations/llamaindex", + "ja/start/integrations/pydantic-ai" + ] } ] }, @@ -490,11 +527,6 @@ "ja/reference/events-and-configuration", "ja/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -517,7 +549,18 @@ "ko/start/first-audit", "ko/start/first-policy", "ko/start/setup", - "ko/start/concepts" + "ko/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "ko/start/quickstarts/custom-agents", + "ko/start/quickstarts/langchain", + "ko/start/quickstarts/crewai", + "ko/start/quickstarts/llamaindex", + "ko/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -542,6 +585,16 @@ "ko/sessions/dashboards", "ko/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "ko/start/integrations/custom-agents", + "ko/start/integrations/langchain", + "ko/start/integrations/crewai", + "ko/start/integrations/llamaindex", + "ko/start/integrations/pydantic-ai" + ] } ] }, @@ -628,11 +681,6 @@ "ko/reference/events-and-configuration", "ko/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -655,7 +703,18 @@ "es/start/first-audit", "es/start/first-policy", "es/start/setup", - "es/start/concepts" + "es/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "es/start/quickstarts/custom-agents", + "es/start/quickstarts/langchain", + "es/start/quickstarts/crewai", + "es/start/quickstarts/llamaindex", + "es/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -680,6 +739,16 @@ "es/sessions/dashboards", "es/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "es/start/integrations/custom-agents", + "es/start/integrations/langchain", + "es/start/integrations/crewai", + "es/start/integrations/llamaindex", + "es/start/integrations/pydantic-ai" + ] } ] }, @@ -766,11 +835,6 @@ "es/reference/events-and-configuration", "es/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -793,7 +857,18 @@ "pt-br/start/first-audit", "pt-br/start/first-policy", "pt-br/start/setup", - "pt-br/start/concepts" + "pt-br/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "pt-br/start/quickstarts/custom-agents", + "pt-br/start/quickstarts/langchain", + "pt-br/start/quickstarts/crewai", + "pt-br/start/quickstarts/llamaindex", + "pt-br/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -818,6 +893,16 @@ "pt-br/sessions/dashboards", "pt-br/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "pt-br/start/integrations/custom-agents", + "pt-br/start/integrations/langchain", + "pt-br/start/integrations/crewai", + "pt-br/start/integrations/llamaindex", + "pt-br/start/integrations/pydantic-ai" + ] } ] }, @@ -904,11 +989,6 @@ "pt-br/reference/events-and-configuration", "pt-br/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -931,7 +1011,18 @@ "de/start/first-audit", "de/start/first-policy", "de/start/setup", - "de/start/concepts" + "de/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "de/start/quickstarts/custom-agents", + "de/start/quickstarts/langchain", + "de/start/quickstarts/crewai", + "de/start/quickstarts/llamaindex", + "de/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -956,6 +1047,16 @@ "de/sessions/dashboards", "de/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "de/start/integrations/custom-agents", + "de/start/integrations/langchain", + "de/start/integrations/crewai", + "de/start/integrations/llamaindex", + "de/start/integrations/pydantic-ai" + ] } ] }, @@ -1042,11 +1143,6 @@ "de/reference/events-and-configuration", "de/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -1069,7 +1165,18 @@ "fr/start/first-audit", "fr/start/first-policy", "fr/start/setup", - "fr/start/concepts" + "fr/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "fr/start/quickstarts/custom-agents", + "fr/start/quickstarts/langchain", + "fr/start/quickstarts/crewai", + "fr/start/quickstarts/llamaindex", + "fr/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -1094,6 +1201,16 @@ "fr/sessions/dashboards", "fr/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "fr/start/integrations/custom-agents", + "fr/start/integrations/langchain", + "fr/start/integrations/crewai", + "fr/start/integrations/llamaindex", + "fr/start/integrations/pydantic-ai" + ] } ] }, @@ -1180,11 +1297,6 @@ "fr/reference/events-and-configuration", "fr/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -1207,7 +1319,18 @@ "ru/start/first-audit", "ru/start/first-policy", "ru/start/setup", - "ru/start/concepts" + "ru/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "ru/start/quickstarts/custom-agents", + "ru/start/quickstarts/langchain", + "ru/start/quickstarts/crewai", + "ru/start/quickstarts/llamaindex", + "ru/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -1232,6 +1355,16 @@ "ru/sessions/dashboards", "ru/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "ru/start/integrations/custom-agents", + "ru/start/integrations/langchain", + "ru/start/integrations/crewai", + "ru/start/integrations/llamaindex", + "ru/start/integrations/pydantic-ai" + ] } ] }, @@ -1318,11 +1451,6 @@ "ru/reference/events-and-configuration", "ru/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -1345,7 +1473,18 @@ "hi/start/first-audit", "hi/start/first-policy", "hi/start/setup", - "hi/start/concepts" + "hi/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "hi/start/quickstarts/custom-agents", + "hi/start/quickstarts/langchain", + "hi/start/quickstarts/crewai", + "hi/start/quickstarts/llamaindex", + "hi/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -1370,6 +1509,16 @@ "hi/sessions/dashboards", "hi/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "hi/start/integrations/custom-agents", + "hi/start/integrations/langchain", + "hi/start/integrations/crewai", + "hi/start/integrations/llamaindex", + "hi/start/integrations/pydantic-ai" + ] } ] }, @@ -1456,11 +1605,6 @@ "hi/reference/events-and-configuration", "hi/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -1483,7 +1627,18 @@ "tr/start/first-audit", "tr/start/first-policy", "tr/start/setup", - "tr/start/concepts" + "tr/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "tr/start/quickstarts/custom-agents", + "tr/start/quickstarts/langchain", + "tr/start/quickstarts/crewai", + "tr/start/quickstarts/llamaindex", + "tr/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -1508,6 +1663,16 @@ "tr/sessions/dashboards", "tr/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "tr/start/integrations/custom-agents", + "tr/start/integrations/langchain", + "tr/start/integrations/crewai", + "tr/start/integrations/llamaindex", + "tr/start/integrations/pydantic-ai" + ] } ] }, @@ -1594,11 +1759,6 @@ "tr/reference/events-and-configuration", "tr/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -1621,7 +1781,18 @@ "vi/start/first-audit", "vi/start/first-policy", "vi/start/setup", - "vi/start/concepts" + "vi/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "vi/start/quickstarts/custom-agents", + "vi/start/quickstarts/langchain", + "vi/start/quickstarts/crewai", + "vi/start/quickstarts/llamaindex", + "vi/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -1646,6 +1817,16 @@ "vi/sessions/dashboards", "vi/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "vi/start/integrations/custom-agents", + "vi/start/integrations/langchain", + "vi/start/integrations/crewai", + "vi/start/integrations/llamaindex", + "vi/start/integrations/pydantic-ai" + ] } ] }, @@ -1732,11 +1913,6 @@ "vi/reference/events-and-configuration", "vi/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -1759,7 +1935,18 @@ "it/start/first-audit", "it/start/first-policy", "it/start/setup", - "it/start/concepts" + "it/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "it/start/quickstarts/custom-agents", + "it/start/quickstarts/langchain", + "it/start/quickstarts/crewai", + "it/start/quickstarts/llamaindex", + "it/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -1784,6 +1971,16 @@ "it/sessions/dashboards", "it/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "it/start/integrations/custom-agents", + "it/start/integrations/langchain", + "it/start/integrations/crewai", + "it/start/integrations/llamaindex", + "it/start/integrations/pydantic-ai" + ] } ] }, @@ -1870,11 +2067,6 @@ "it/reference/events-and-configuration", "it/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -1897,7 +2089,18 @@ "ar/start/first-audit", "ar/start/first-policy", "ar/start/setup", - "ar/start/concepts" + "ar/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "ar/start/quickstarts/custom-agents", + "ar/start/quickstarts/langchain", + "ar/start/quickstarts/crewai", + "ar/start/quickstarts/llamaindex", + "ar/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -1922,6 +2125,16 @@ "ar/sessions/dashboards", "ar/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "ar/start/integrations/custom-agents", + "ar/start/integrations/langchain", + "ar/start/integrations/crewai", + "ar/start/integrations/llamaindex", + "ar/start/integrations/pydantic-ai" + ] } ] }, @@ -2008,11 +2221,6 @@ "ar/reference/events-and-configuration", "ar/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } @@ -2035,7 +2243,18 @@ "he/start/first-audit", "he/start/first-policy", "he/start/setup", - "he/start/concepts" + "he/start/concepts", + { + "group": "Starter templates", + "expanded": false, + "pages": [ + "he/start/quickstarts/custom-agents", + "he/start/quickstarts/langchain", + "he/start/quickstarts/crewai", + "he/start/quickstarts/llamaindex", + "he/start/quickstarts/pydantic-ai" + ] + } ] } ] @@ -2060,6 +2279,16 @@ "he/sessions/dashboards", "he/sessions/queries" ] + }, + { + "group": "Plug in your agent", + "pages": [ + "he/start/integrations/custom-agents", + "he/start/integrations/langchain", + "he/start/integrations/crewai", + "he/start/integrations/llamaindex", + "he/start/integrations/pydantic-ai" + ] } ] }, @@ -2146,11 +2375,6 @@ "he/reference/events-and-configuration", "he/reference/troubleshooting" ] - }, - { - "group": "HTTP API", - "expanded": false, - "openapi": "reference/openapi.json" } ] } diff --git a/docs/es/index.mdx b/docs/es/index.mdx index cc99067a9..72b24fa4f 100644 --- a/docs/es/index.mdx +++ b/docs/es/index.mdx @@ -1,16 +1,16 @@ --- title: "Haz que tu agente sea infalible" -description: "Observabilidad y control de cumplimiento para cada entorno en que se ejecutan tus agentes — CLIs de codificación, gateways de chat, asistentes autoalojados y tus propios agentes instrumentados." +description: "Observabilidad y control para cada entorno en que se ejecutan tus agentes — CLIs de programación, gateways de chat, asistentes autoalojados y tus propios agentes instrumentados." icon: "shield-check" --- Failproof AI ayuda a los equipos a entender qué hicieron los agentes, encontrar dónde fallaron y desplegar salvaguardas antes de que el mismo comportamiento vuelva a ocurrir. -Un **entorno de ejecución** (harness) es el contexto donde tu agente corre realmente. Failproof AI se conecta a 12 de ellos — CLIs de codificación como Claude Code y Codex, gateways de chat como Hermes, asistentes autoalojados como OpenClaw — y los mismos eventos, las mismas políticas y el mismo historial de sesiones se aplican a todos. Los agentes sin harness reportan a través del [SDK de Python](/es/reference/custom-agents), que los rastrea y audita; aplicar una política en ese caso requiere un hook en tu propio entorno de ejecución. +Un **entorno de ejecución** (harness) es lo que contiene y ejecuta tu agente. Failproof AI se integra con 12 de ellos — CLIs de programación como Claude Code y Codex, gateways de chat como Hermes, asistentes autoalojados como OpenClaw — y los mismos eventos, las mismas políticas y el mismo historial de sesiones aplican a todos. Los agentes sin entorno de ejecución se comunican a través del [SDK de Python](/es/reference/custom-agents), que los rastrea y audita; aplicar una política en ese caso requiere un hook en tu propio runtime. - Usa la skill para instrumentar tu proyecto, conectarlo y verificar que los registros del agente lleguen correctamente. + Usa la habilidad para instrumentar tu proyecto, conectarlo y verificar que los registros del agente lleguen correctamente. Analiza, consulta, crea dashboards y ejecuta auditorías en lenguaje natural sobre los registros de tu agente. @@ -18,24 +18,24 @@ Un **entorno de ejecución** (harness) es el contexto donde tu agente corre real - - Sigue las llamadas al modelo, herramientas, errores, entrada humana, latencia y decisiones de política en una sola sesión. + + Sigue las llamadas al modelo, herramientas, errores, entradas del usuario, latencia y decisiones de política en una sola sesión. - - Audita un conjunto definido de sesiones, revisa hallazgos respaldados por evidencia y haz seguimiento de la corrección como issues. + + Audita un conjunto definido de sesiones, revisa hallazgos respaldados por evidencia y realiza seguimiento de la remediación como incidencias. - Convierte un fallo conocido en una política, observa su impacto y despliégala en toda tu flota. + Convierte un modo de fallo conocido en una política, observa su impacto y despliégala en toda tu flota. -> **Sesión → Auditoría → Hallazgo → Issue → Política**
+> **Sesión → Auditoría → Hallazgo → Incidencia → Política**
> Rastrea lo que ocurrió, encuentra el fallo, gestiona la respuesta y previene el mismo comportamiento en ejecuciones futuras. ## Empieza aquí -Si estás desplegando tu primer agente instrumentado, comienza con el [inicio rápido](/es/start/quickstart). Si los datos ya están llegando, abre [Sesiones](/es/sessions/overview) e inspecciona una ejecución real antes de configurar auditorías o políticas. +Si estás desplegando tu primer agente instrumentado, comienza con la [guía de inicio rápido](/es/start/quickstart). Si los datos ya están llegando, abre [Sesiones](/es/sessions/overview) e inspecciona una ejecución real antes de configurar auditorías o políticas. - Completa el flujo de trabajo de extremo a extremo desde la captura hasta una política desplegada de forma segura. + Completa el flujo de trabajo de extremo a extremo, desde la captura hasta el despliegue seguro de una política. \ No newline at end of file diff --git a/docs/es/policies/deploy.mdx b/docs/es/policies/deploy.mdx index 96cdbbad8..d3df4df49 100644 --- a/docs/es/policies/deploy.mdx +++ b/docs/es/policies/deploy.mdx @@ -1,30 +1,34 @@ --- title: "Desplegar políticas" -description: "Publica una versión de política revisada en las máquinas objetivo." +description: "Distribuye una versión de política revisada a las máquinas previstas." icon: "cloud-upload" --- -Un despliegue conecta una o más versiones de política con un conjunto objetivo de máquinas registradas. +Un despliegue conecta una o más versiones de política a un conjunto de máquinas enroladas. ## Aplicar un despliegue - 1. Ve a **Admin → enforcement**, localiza la máquina y despliega su fila. - 2. Selecciona **edit**, añade la versión de política revisada y elige el efecto **observe** o uno de aplicación forzosa. - 3. Aplica el cambio, espera al próximo check-in de la máquina y confirma su estado de despliegue y cobertura. + 1. Ve a **Admin → enforcement**, busca 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 de aplicación forzada. + 3. Aplica el cambio, luego espera al próximo check-in de la máquina y confirma su estado de despliegue y cobertura. 4. Ve a **Observe → policy** para inspeccionar las decisiones en tiempo real. - ![El editor de despliegue de máquinas con versiones de política, efectos de aplicación y observación, 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 enforce y observe, y la acción de aplicar despliegue.](/images/dashboard/enforcement-editor.png) - Los endpoints de despliegue en la nube no están expuestos deliberadamente como comandos ordinarios de `fp`. Verifica la máquina localmente y luego despliega a través del panel de control: + Despliega desde la CLI con `fp fleet`. Revisa el conjunto resultante antes de aplicarlo — `deploy` imprime el plan completo y solicita confirmación **únicamente en una terminal interactiva sin `--json`**. Con `--json`, con `--yes`, o con stdin redirigido (un paso de CI, un script, un agente que ejecuta comandos) se aplica de inmediato sin plan ni confirmación, por lo que ejecuta `fp fleet show ` primero si deseas revisarlo: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - Usa `fp sessions --env production --since 24h` y `fp events --event-type hook_completed` tras el despliegue para verificar que la actividad llega a Cloud. + `fp fleet diff ` muestra la intención frente a la entrega (una máquina aparece como `behind` hasta su próximo sondeo), `fp fleet history ` lista las generaciones, y `fp fleet rollback ` restaura una de ellas — rechaza la operación si esa generación hace referencia a una política que ha sido deshabilitada o eliminada. + + Comprueba la propia 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 verificar que la actividad llega a Cloud. @@ -33,15 +37,15 @@ Un despliegue conecta una o más versiones de política con un conjunto objetivo 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. - Revisa las coincidencias, razones, herramientas afectadas y falsos positivos sin bloquear el trabajo. + Revisa coincidencias, motivos, herramientas afectadas y falsos positivos sin bloquear el trabajo. - - Promociona tras comprobar que las coincidencias observadas separan las acciones inseguras de las válidas, y confirma que cada máquina prevista ha recibido el despliegue y está registrando decisiones. + + Promueve tras confirmar que las coincidencias observadas distinguen acciones inseguras de las válidas; luego verifica que cada máquina prevista ha obtenido el despliegue y está 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 de políticas en Cloud. +Las máquinas necesitan la capacidad `policies:pull`. El reporte de eventos está controlado por separado mediante `events:add`; verifica ambos cuando esperes análisis y aplicación forzada en Cloud. - La gestión de la aplicación de políticas 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. + La gestión de enforcement es un flujo de trabajo administrativo de Cloud. No trates las rutas de enforcement exclusivas de root como endpoints de API `/v1` ordinarios para clientes. \ No newline at end of file diff --git a/docs/es/policies/editor.mdx b/docs/es/policies/editor.mdx index 647321d27..750c16530 100644 --- a/docs/es/policies/editor.mdx +++ b/docs/es/policies/editor.mdx @@ -4,44 +4,46 @@ description: "Crea y revisa políticas versionadas a partir de un modo de fallo icon: "file-pen-line" --- -Usa el editor de políticas para convertir un hallazgo o problema 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. +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. -Cuando un problema tiene un patrón de acción repetible, ábrelo 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. +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. ## Publicar una versión de política 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 todos los errores reportados. + 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 automático. + 4. Selecciona **enforcement** cuando la versión esté lista para un despliegue en máquinas. ![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 CLI en la nube no publica versiones de políticas. Valida el código fuente localmente antes de copiarlo en el editor: + 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: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - Publica la versión revisada desde **Admin → policy editor**. + 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`. ## Lista de verificación para la autoría 1. Nombra el modo de fallo en lenguaje operacional. -2. Selecciona los eventos de hook y las herramientas que contengan evidencia suficiente para decidir. -3. Escribe la condición más restrictiva que coincida con el comportamiento inseguro. -4. Devuelve una razón que indique al agente o al operador qué hacer a continuación. -5. Añade ejemplos que deban coincidir y ejemplos que deban permanecer permitidos. +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. -Usa `instruct` cuando el agente pueda corregir su curso de forma segura. Usa `deny` cuando permitir la acción supondría un riesgo inaceptable o irreversible. +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. - Las versiones de políticas 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. + 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 diff --git a/docs/es/reference/cloud-cli.mdx b/docs/es/reference/cloud-cli.mdx index 56642cb40..ec6b3d115 100644 --- a/docs/es/reference/cloud-cli.mdx +++ b/docs/es/reference/cloud-cli.mdx @@ -4,7 +4,7 @@ description: "Referencia completa para consultar y administrar Failproof AI Clou icon: "cloud-cog" --- -Usa `fp` para inspeccionar la telemetría de Cloud y gestionar auditorías, hallazgos, incidencias, alertas, claves, usuarios, consultas y configuración. Usa [`failproofai`](/es/reference/failproof-cli) para hooks locales, políticas, captura e inscripción de máquinas. +Usa `fp` para inspeccionar la telemetría de Cloud, gestionar la aplicación de políticas gestionada en la nube (políticas, despliegues de flota, decisiones de guardrail), así como auditorías, hallazgos, incidencias, alertas, claves, usuarios, consultas y configuración. Utiliza [`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: @@ -34,7 +34,7 @@ fp --json sessions --since 24h Ejecuta `fp COMMAND --help` o `fp COMMAND SUBCOMMAND --help` para obtener ayuda en la terminal. -## Comandos del CLI +## Comandos de la CLI ### Autenticación @@ -43,11 +43,11 @@ Ejecuta `fp COMMAND --help` o `fp COMMAND SUBCOMMAND --help` para obtener ayuda | `fp login` | Inicia sesión con un código de un solo uso enviado por correo y selecciona una organización. | `--email`, `-e`; `--org`; `--force` | | `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 del CLI. | — | -| `fp help` | Muestra la ayuda de comandos de nivel superior. | — | +| `fp version` | Muestra la versión instalada de la CLI. | — | +| `fp help` | Muestra la ayuda de los comandos de nivel superior. | — | ```bash -fp login --email tu@ejemplo.com --org equipo-de-fiabilidad +fp login --email tu@ejemplo.com --org reliability-team fp whoami ``` @@ -61,26 +61,30 @@ Lista eventos individuales de agentes. El feed ligero predeterminado excluye los | Opción | Descripción | | --- | --- | -| `--limit`, `-n ` | Máximo total de filas. Predeterminado: `50`. | +| `--limit`, `-n ` | Máximo de filas totales. Por defecto: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` o `7d`. | -| `--from ` / `--to ` | Rango UTC ISO 8601; reemplaza `--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 `--since`. | +| `--env ` | Filtro de entorno; repite o separa por comas. | +| `--event-type ` | Filtro de tipo de evento; repite o separa por comas. | +| `--agent-id ` | Filtro de agente; repite o separa por comas. | +| `--session-id ` | Filtro de sesión; repite o separa por 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 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 completo. | | `--fields ` | Devuelve solo los campos seleccionados; solicitar `payload` activa el modo completo. | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` + + `--all` pagina **hasta `--limit`**, que por defecto es **50** — así que `--all` por sí solo se detiene en 50 filas. Cuando se detiene antes, la respuesta incluye un `next_cursor` para reanudar; `"next_cursor": null` indica que el feed realmente se ha agotado. + + ### Sesiones ```text @@ -89,19 +93,19 @@ fp sessions [OPTIONS] | Opción | Descripción | | --- | --- | -| `--limit`, `-n ` | Máximo total de filas. Predeterminado: `50`. | +| `--limit`, `-n ` | Máximo de filas totales. Por defecto: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` o `7d`. | -| `--from ` / `--to ` | Rango UTC ISO 8601; reemplaza `--since`. | -| `--env ` | Filtro de entorno; repite o separa valores con comas. | -| `--status ` | `done`, `error` o `timeout`; repite o separa valores con comas. | -| `--agent-id ` | Coincide con sesiones que involucran 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 `--since`. | +| `--env ` | Filtro de entorno; repite o separa por comas. | +| `--status ` | `done`, `error` o `timeout`; repite o separa por comas. | +| `--agent-id ` | Coincide con sesiones que involucran al agente seleccionado. | +| `--session-id ` | Filtro de sesión; repite o separa por 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 de la terminal. | -| `--agents` | Expande el listado de agentes para sesiones multiagente. | +| `--agents` | Expande el registro de agentes para sesiones multiagente. | ### Evaluaciones @@ -112,11 +116,11 @@ 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`. | +| `--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` | Restringe 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. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Filtra a un único valor exacto por filtro. | +| `--score KEY:MIN..MAX` | Rango de puntuación; repetible, todos los rangos deben coincidir. | +| `--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 de la terminal. | @@ -130,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`. | +| `--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` | Restringe la población de errores. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Filtra la población 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. | @@ -151,7 +155,7 @@ fp errors [OPTIONS] | `fp list models` | Lista los nombres de modelos. | | `fp list hooks` | Lista los nombres de hooks. | | `fp list tools` | Lista los nombres de herramientas. | -| `fp list error_types` | Lista los tipos de errores. | +| `fp list error_types` | Lista los tipos de error. | ### Organizaciones @@ -170,10 +174,10 @@ fp errors [OPTIONS] | `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. | `--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 una clave de forma permanente. | `--yes`, `-y` | +| `fp keys regenerate NAME` | Rota el secreto y revela el de 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 los tokens con comas, o usa acciones con punto como `events:read.add`. +Los tokens de permiso usan el formato `resource:action`, por ejemplo `events:add`. Repite `--add`, separa los tokens por comas, o usa acciones con punto como `events:read.add`. ### Consultas @@ -184,7 +188,7 @@ Los tokens de permiso usan el formato `recurso:acción`, por ejemplo `events:add | `fp query create NAME` | Guarda una consulta. | `--sql `; `--description` | | `fp query update NAME` | Actualiza o renombra una consulta. | `--name`; `--sql`; `--description`; `--yes`, `-y` | | `fp query delete NAME` | Elimina una consulta guardada. | `--yes`, `-y` | -| `fp query run [NAME]` | Ejecuta una consulta guardada o SQL ad-hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query run [NAME]` | Ejecuta una consulta guardada o SQL ad hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | | `fp query schema [TABLE]` | Lista las tablas consultables o inspecciona una tabla. | — | ### Usuarios @@ -193,18 +197,18 @@ Los tokens de permiso usan el formato `recurso:acción`, por ejemplo `events:add | --- | --- | --- | | `fp users list` | Lista los miembros de la organización. | `--active-only`; `--show-id` | | `fp users show EMAIL` | Muestra un miembro y sus permisos. | — | -| `fp users create EMAIL` | Agrega un miembro. | `--permission-set`; `--add`; `--remove` | +| `fp users create EMAIL` | Añade 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` | Rehabilita el inicio de sesión. | `--yes`, `-y` | +| `fp users enable EMAIL` | Vuelve a habilitar el inicio de sesión. | `--yes`, `-y` | ### Configuración | Comando | Propósito | Opciones | | --- | --- | --- | -| `fp settings list` | Lista los ajustes de la organización y sus valores actuales. | — | +| `fp settings list` | Lista la configuración de la organización y los valores actuales. | — | | `fp settings schema` | Muestra los valores aceptados y sus descripciones. | — | -| `fp settings set KEY` | Modifica un ajuste existente. | exactamente uno de `--value`, `--json-value`, `--file`; `--yes`, `-y` opcional | +| `fp settings set KEY` | Modifica una configuración existente. | exactamente una de `--value`, `--json-value`, `--file`; opcional `--yes`, `-y` | ### Alertas @@ -217,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 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. +Las severidades de alerta son `info`, `warning` y `critical`. Los tipos de trigger 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 @@ -225,24 +229,24 @@ 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 encola inmediatamente su primera ejecución. | Ver [opciones de creación](#audit-create-options). | -| `fp audits edit NAME` | Reemplaza los ajustes de la auditoría conservando los valores no especificados. | opciones de definición de creación; `--name`; `--yes`, `-y` | +| `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 edit NAME` | Reemplaza la configuración de auditoría manteniendo 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` | Encola una ejecución manual. | — | +| `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 las 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 la URL 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` | Confirma la recepción de 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 corregido 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` | Asigna el propietario del hallazgo. | `--to ` requerido | +| `fp audits assign FINDING_ID` | Establece el propietario del hallazgo. | `--to ` requerido | -#### Opciones de creación de auditoría +#### Opciones de creación de auditorías ```bash fp audits create checkout-reliability \ @@ -258,26 +262,26 @@ fp audits create checkout-reliability \ | Opción | Descripción | | --- | --- | | `--file ` | Basa la definición en JSON, o usa `-` para stdin. Las flags explícitas reemplazan los valores del archivo. | -| `--description ` | Indica la pregunta de fallo o el propósito. | -| `--enabled` / `--disabled` | Inicia la programación activada o desactivada. Predeterminado: habilitado. | -| `--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 después de 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 errores; repite o separa con comas. | -| `--llm` / `--no-llm` | Activa o desactiva el análisis agéntico. Predeterminado: habilitado. | -| `--top-k ` | Conserva entre `1` y `500` hallazgos. Predeterminado: `50`. | -| `--sensitivity low\|medium\|high` | Establece la sensibilidad de reporte. Predeterminado: `medium`. | +| `--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 variable. 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; repite o separa por comas. | +| `--llm` / `--no-llm` | Activa o desactiva el análisis agéntico. Por defecto: activado. | +| `--top-k ` | Retiene `1`–`500` hallazgos. Por defecto: `50`. | +| `--sensitivity low\|medium\|high` | Establece la sensibilidad de reporte. Por defecto: `medium`. | | `--channels ''` | Array de canales de notificación. | -| `--text ` | Resumen en línea, máximo 8.192 caracteres. | +| `--text ` | Resumen en línea, máximo 8 192 caracteres. | | `--text-file ` | Lee el resumen desde un archivo; mutuamente exclusivo con `--text`. | -| `--url ` | Agrega una referencia HTTPS pública; repite hasta cinco veces. | +| `--url ` | Añade una referencia HTTPS pública; repite 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. +Incluye el contexto durante la creación cuando la primera ejecución lo necesita. 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. Consulta `fp audits runs NAME` hasta que la última ejecución tenga éxito o falle antes de leer sus hallazgos. ### Incidencias @@ -285,67 +289,111 @@ Incluye el contexto durante la creación cuando la primera ejecución lo necesit | Comando | Propósito | Opciones | | --- | --- | --- | | `fp issues list` | Lista las incidencias. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | Cuenta las incidencias abiertas o los estados de incidencia seleccionados. | `--state` | +| `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` | Confirma la recepción de una incidencia. | — | +| `fp issues ack INCIDENT_ID` | Confirma una incidencia. | — | | `fp issues assign INCIDENT_ID` | Reemplaza los asignados; omite 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` | Agrega un comentario. | exactamente uno de `--body`, `--file` | +| `fp issues comment-add INCIDENT_ID` | Añade un comentario. | exactamente una 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 o a otro operador. | `--email` | +| `fp issues subscribe INCIDENT_ID` | Te suscribe a ti u otro operador. | `--email` | | `fp issues unsubscribe INCIDENT_ID` | Elimina una suscripción. | `--email` | -Los estados válidos de incidencia son `firing`, `acknowledged` y `resolved`. Las severidades de incidencias independientes son `info`, `warning` y `critical`. +Los estados de incidencia válidos son `firing`, `acknowledged` y `resolved`. Las severidades de incidencia independiente son `info`, `warning` y `critical`. -### Asistente en la nube +### Asistente cloud | Comando | Propósito | Opciones | | --- | --- | --- | -| `fp agent health` | Verifica la disponibilidad y configuración del asistente. | — | +| `fp agent health` | Comprueba la disponibilidad y la 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 ask [MESSAGE]` | Inicia o continúa un chat; lee stdin si 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 delete CHAT_ID` | Elimina una conversación. | `--yes`, `-y` | +### Políticas + +Versiones de políticas gestionadas 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 exclusivas de 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 código 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 añade de nuevo 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 lleva, 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 cubre el evento/herramienta dado se reporta como `skipped` en lugar de ejecutarse. | `--event`; `--tool`; `--command`; `--file-path`; `--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 las anteriores. + +| 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 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 | + +### Guardrails + +Lo que realmente hizo la aplicación. **Solo para sesión**, por la misma razón que las anteriores. + +| Comando | Propósito | Opciones | +| --- | --- | --- | +| `fp guardrails summary` | Cobertura, totales bloqueados/evaluados, una gráfica de denegaciones y la tabla por política. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Decisiones agrupadas en la ventana temporal, sumadas por cada fuente de política. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | + ## Flags globales | Flag | Descripción | | --- | --- | | `--json` | Emite JSON legible por máquina. | -| `--base-url ` | Usa un dashboard autoalojado o de desarrollo. | +| `--base-url ` | Usa un dashboard alojado localmente o de desarrollo. | | `--org ` | Selecciona una organización para esta invocación. | | `--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`. | +| `--api-key ` | Autentica automatización con una clave de API; nunca se guarda. | +| `--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 color. | -| `--insecure` / `--secure` | Deshabilita o restaura la verificación del certificado TLS. | +| `--no-color` | Deshabilita la salida en color. | +| `--insecure` / `--secure` | Deshabilita o restaura la verificación de certificados TLS. | | `--version` | Imprime la versión y sale. | | `--help`, `-h` | Muestra la ayuda. | -`--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. +`--api-key` está pensado para automatización. El inicio de sesión, el cambio de organización y los comandos del asistente requieren una sesión de usuario. ## Variables de entorno | Variable | Equivalente o propósito | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | Reubica el directorio de configuración actual del CLI. | -| `AGENTEYE_ANALYTICS_DISABLED` o `DO_NOT_TRACK` | Deshabilita las analíticas anónimas del CLI. | -| `NO_COLOR` | Deshabilita la salida con color. | - -Las flags explícitas reemplazan las variables de entorno, que a su vez reemplazan la configuración guardada. En el modo de clave de API, selecciona el tenant explícitamente con `--org` o `AGENTEYE_ORG`. +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `FP_API_KEY` | `--api-key` | +| `FP_JSON` | `--json` | +| `FP_INSECURE` | `--insecure` | +| `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 en color. | + +Las flags explícitas reemplazan las variables de entorno, que a su vez reemplazan la configuración guardada. En modo de clave de API, selecciona el tenant explícitamente con `--org` o `FP_ORG`. + + + 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 genera 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` todavía existen, pero pertenecen al **colector y al SDK de telemetría**, no a esta CLI. + - Los comandos que eliminan, revocan, suprimen, resuelven o reemplazan configuración solicitan confirmación de forma predeterminada. 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. Usa `--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 b99a2591a..2afefeb9b 100644 --- a/docs/es/reference/custom-agents.mdx +++ b/docs/es/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- title: "Agentes personalizados" -description: "Instrumenta trazas de agentes personalizados para que Failproof AI pueda reconstruir ejecuciones y detectar fallos." +description: "Configuración, el catálogo de eventos, reglas de correlación y entrega para failproofai-sdk." icon: "python" --- -Instrumenta trazas de un agente personalizado con `failproofai-sdk` para que Failproof AI pueda reconstruir cada ejecución, auditar su comportamiento y encontrar fallos respaldados por evidencia. El SDK escribe eventos estructurados para que el daemon de Failproof los envíe a Cloud. Requiere Python 3.10 o superior. +Qué hace cada parámetro, método y campo. Si es la primera vez que instrumentas, comienza con la guía — esta página es para consultar referencias. -El rastreo hace que los agentes personalizados sean observables y auditables. Para bloquear una acción insegura antes de que se ejecute también se necesita un hook de aplicación en tu runtime. + + + Instalación, instrumentación, los métodos de eventos, un ejemplo completo y problemas frecuentes. + + + LangChain, CrewAI, LlamaIndex y Pydantic AI se instrumentan solos con una sola llamada. + + - - Para aplicar políticas en un entorno con agentes personalizados, [contacta con Failproof AI](mailto:support@befailproof.ai). Te ayudaremos a mapear los límites de modelo, herramienta y ciclo de vida de tu runtime a hooks de política. - +Python 3.10 o superior. Sin dependencias en tiempo de ejecución. -
- -
- -## Instalar `failproofai-sdk` - -El SDK se distribuye actualmente como un wheel privado. Contacta con tu representante de Failproof AI para obtener la versión actual y acceso de descarga. +## Instalación ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -Con `uv`, descarga primero el wheel y ejecuta `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl`. Fija el wheel en un repositorio privado de artefactos o en el archivo de bloqueo de dependencias. - -El paquete se instala como `failproofai-sdk` y se importa en Python como `failproofai`. +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 se incluyen en el wheel base. ## Conectar el daemon de Failproof - + 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 busca 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 encuentra 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) + ![Sesión de un agente Python personalizado reconstruida como grafo de ejecución y traza de eventos ordenada.](/images/dashboard/session-detail.png) ```bash @@ -51,102 +46,84 @@ El paquete se instala como `failproofai-sdk` y se importa en Python como `failpr -## Instrumentar una ejecución completa - -Llama a `configure()` una sola vez durante el inicio del proceso. Todas las llamadas a eventos son solo por nombre de parámetro y requieren un `session_id` y un `agent_id` estables. +## Configuración ```python -import traceback -import uuid +import failproofai_sdk -import failproofai +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -failproofai.configure(environment="production") +| Argumento | Qué hace | +| --- | --- | +| `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 usa el spool del daemon, que es lo que quieres salvo que sepas lo que estás haciendo. | -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +También se puede configurar mediante variables de entorno: -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) +| Variable | Qué hace | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Define `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 excepciones en lugar de solo registrarse. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` hace que un problema de compatibilidad con un framework lance una excepción en lugar de advertir y continuar. | -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + + **No uses comas en `environment`.** El sistema de ingesta divide ese campo por comas para construir sus filtros, y descarta cualquier evento cuya etiqueta contenga una — con lo que toda una ejecución desaparece silenciosamente. Escribe `prod-eu`, no `prod,eu`. + + `configure(environment="prod,eu")` lanza una excepción para que lo descubras de inmediato. `AGENTEYE_ENVIRONMENT` no puede lanzar — nadie te está llamando — así que advierte una vez y vuelve a `dev`. + -Emite `agent_start` una vez por actor. Para sub-agentes, reutiliza el `session_id` del padre, asigna a cada actor un `agent_id` distinto y establece `parent_id` como el **ID del agente** padre, no el ID de sesión. +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 terminado abruptamente pierde lo que aún no se había escrito. -## Referencia de configuración +## Identidad + +Cada evento pertenece a una sesión y a un agente. **Los scopes rellenan ambos**, por lo que rara vez necesitas pasarlos explícitamente: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| Parámetro | Comportamiento | -| --- | --- | -| `base_dir` | Directorio raíz de spool explícito. Tiene precedencia sobre todas las variables de entorno. | -| `flush_interval` | Segundos entre escrituras en segundo plano desde memoria a JSONL. Valor predeterminado: `0.5`. | -| `environment` | Etiqueta de despliegue en cada evento. Por defecto es `dev`. | -| `FAILPROOFAI_HOME` | Cambia la raíz de Failproof AI que contiene el spool `custom-agents`. | - -El SDK escribe en el `base_dir` explícito cuando está definido. De lo contrario, utiliza el spool `custom-agents` del daemon de Failproof bajo `FAILPROOFAI_HOME` o `~/.failproofai`. +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. -El SDK encola llamadas en memoria y escribe lotes en un hilo en segundo plano. También realiza un flush final a través del mecanismo `atexit` de Python. Para workers de vida corta, permite un cierre normal del intérprete; la terminación forzada del proceso puede provocar la pérdida de eventos que aún estén en memoria. + + 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 asociar. + ## Catálogo de eventos -Todos los métodos devuelven `None`. Los campos con valor `None` se omiten en lugar de escribirse como `null` en JSON. +Quince métodos. La mayoría vienen en **pares** — llamas al de apertura, luego al de cierre, y el SDK mide el intervalo. -| Método | Campos requeridos además de la identidad | Campos opcionales | +| | Abre | Cierra | +| --- | --- | --- | +| **Agentes** | `agent_start` | `agent_end` | +| | `agent_pause` | `agent_resume` | +| **Modelos** | `model_request` | `model_response` | +| **Herramientas** | `tool_use` | `tool_result` | +| **Hooks** | `hook_triggered` | `hook_completed` | +| **Humanos** | `human_wait` | `human_input` | + +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 omite en lugar de enviarse como JSON `null`, y todos los métodos devuelven `None`. + +| Método | Obligatorio | Opcional | | --- | --- | --- | | `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ Todos los métodos devuelven `None`. Los campos con valor `None` se omiten en lu | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -Usa `outcome="failed"`, `"error"`, `"timeout"` o `"rejected"` cuando una finalización deba contabilizarse como un fallo. Otros valores, incluido `"failure"`, no son clasificados como fallos por el backend actual. + + + + Para marcar una ejecución como fallida, `outcome` debe ser uno de `failed`, `error`, `timeout` o `rejected`. Cualquier otro valor — incluido el casi correcto `"failure"` — se considera un éxito. + + +## Emparejamiento y duración + +**Una regla: dale al evento de cierre el mismo id que a su apertura.** Eso es lo que los empareja y lo que permite al SDK medir el intervalo. + +| Par | Se empareja por | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**No pases `duration_ms` manualmente.** El SDK lo mide, y pasarlo lanza `ValueError`. -## Reglas de correlación y duración +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. -- Reutiliza el mismo `tool_call_id`, `hook_id`, `pause_id` o `input_id` para el evento de finalización correspondiente. -- El SDK calcula `duration_ms` para `tool_result`, `hook_completed`, `agent_resume` y `human_input`. Pasarlo manualmente a esos métodos lanza `ValueError`. -- Los IDs de herramientas y hooks comparten un mapa de pendientes a nivel de proceso. Hazlos globalmente únicos en sesiones concurrentes y entre ambos espacios de nombres; los IDs de proveedor o UUIDs son la opción más segura. -- Un par dividido entre procesos sigue correlacionándose en el backend, pero el SDK no puede calcular su duración dentro del proceso. -- El mapa de pendientes admite un máximo de 10.000 entradas y elimina la más antigua cuando se llena. + -## Campos personalizados y payloads +- **Los ids solo necesitan ser únicos por tipo y por sesión.** Una llamada a una herramienta y un hook pueden compartir uno; dos sesiones ejecutándose 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 normal en código multi-agente. +- **`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 medirlo — ninguno de los dos procesos vio ambas mitades. +- **Como máximo 10 000 aperturas esperan un cierre a la vez.** A partir de ahí se descarta la más antigua, para que una fuga no crezca sin límite. -Todos los eventos aceptan campos adicionales por nombre de parámetro. Usa valores compatibles con JSON cuando las consultas downstream necesiten estructura. Los tipos no compatibles como UUIDs, datetimes, decimales, conjuntos, bytes y objetos de modelo se convierten a cadena de texto por el escritor. + -Los nombres personalizados reservados son `timestamp`, `session_id`, `agent_id`, `type` y `environment`. Los errores tipográficos en campos opcionales se aceptan como nuevos campos personalizados, así que revisa el JSON emitido si un campo estándar no aparece en Cloud. +## Tus propios campos -## Entregar y verificar +Cualquier palabra clave adicional que pases se almacena con el evento: + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # los tuyos +) +``` + +Usa 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. + + + **Pon prefijo a 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, comprueba primero la ortografía. + + +Estos cinco nombres están reservados y se rechazan directamente: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. + +## Entrega y verificación - - En **Observe → Events**, verifica que `agent_start` exista primero y `agent_end` al final. Luego abre **Observe → Sessions** y confirma que los eventos de modelo, herramienta, persona, hook y error 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` exista primero y `agent_end` exista al final. Luego abre **Observe → Sessions** y confirma que los eventos de modelo, herramienta, humano, hook y error aparecen en el orden previsto. Usa el ID de sesión como clave principal de resolución de problemas. ```bash @@ -189,10 +203,14 @@ Los nombres personalizados reservados son `timestamp`, `session_id`, `agent_id`, -Si Cloud está vacío, inspecciona `$FAILPROOFAI_HOME/custom-agents/events`; de lo contrario, revisa `~/.failproofai/custom-agents/events`. Los archivos JSONL confirman la emisión del SDK; un spool en crecimiento 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. +Si Cloud está vacío, inspecciona `$FAILPROOFAI_HOME/custom-agents/events`; en caso contrario, `~/.failproofai/custom-agents/events`. Los archivos JSONL confirman la emisión del SDK; un spool creciente apunta a configuración del daemon o entrega, mientras que un spool vacío apunta a instrumentación o ciclo de vida del proceso. + + + Inspecciona el spool solo cuando el daemon esté detenido. Mientras se ejecuta, recoge y elimina cada lote en cuestión de milisegundos, por lo que un listado de directorio compite con el colector y mostrará muchos menos eventos de los que se emitieron. + ## Prevenir fallos en un runtime personalizado -Usa los hallazgos de auditoría y las trazas vinculadas para definir la acción insegura, la evidencia requerida y la respuesta esperada. Una integración de aplicación 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: allow, instruct o deny. +Usa los hallazgos de auditoría y los traces vinculados para definir la acción no segura, la evidencia requerida y la respuesta esperada. Una integración de enforcement 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: allow, instruct o deny. -Escribe a [support@befailproof.ai](mailto:support@befailproof.ai) para diseñar y validar esta integración en tu runtime. \ 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 los hooks de política, y luego a validar la integración contigo. \ No newline at end of file diff --git a/docs/es/reference/events-and-configuration.mdx b/docs/es/reference/events-and-configuration.mdx index 6652d4faa..653065124 100644 --- a/docs/es/reference/events-and-configuration.mdx +++ b/docs/es/reference/events-and-configuration.mdx @@ -6,36 +6,36 @@ icon: "list-tree" ## Familias de eventos -- Inicio, fin, pausa y reanudación de agente +- Inicio, fin, pausa y reanudación del agente - Solicitud y respuesta del modelo - Uso de herramienta y resultado - Hook activado y completado -- Espera humana, entrada, pausa e interrupción +- Espera, entrada, pausa e interrupción humana - Errores explícitos -Cada evento incluye una marca de tiempo, ID de sesión, ID de agente, tipo de evento y entorno. Los campos específicos de cada evento contienen datos de modelo, herramienta, correlación, resultado, contenido, duración o error. +Cada evento incluye una marca de tiempo, ID de sesión, ID de agente, tipo de evento y entorno. Los campos específicos del evento contienen datos sobre el modelo, la herramienta, la correlación, el resultado, el contenido, la duración o el error. ## Inspeccionar un contrato de evento 1. Abre **Observe → Events**. - 2. Define una ventana de tiempo corta y filtra por entorno, agente y tipo de evento. - 3. Selecciona un evento para inspeccionar sus campos normalizados y el payload en bruto, luego abre su sesión para ver el contexto de ejecución. - 4. Si falta la duración de un par, verifica que los eventos de inicio y finalización usen el mismo ID de correlación. + 2. Establece una ventana de tiempo reducida y filtra por entorno, agente y tipo de evento. + 3. Selecciona un evento para inspeccionar sus campos normalizados y el payload sin procesar; luego abre su sesión para ver el contexto de ejecución. + 4. Si falta una duración emparejada, verifica que los eventos de inicio y finalización usen el mismo ID de correlación. - Usa el flujo de Events para reducir los datos a una sola ejecución de agente e inspeccionar los campos de evento normalizados. + Usa el flujo de Events para acotar los datos a una ejecución de agente e inspeccionar los campos de evento normalizados. - ![El flujo en vivo de Events con filtros por entorno, agente, sesión y tipo de evento.](/images/dashboard/events-stream.png) + ![El flujo de Events en vivo con filtros por entorno, agente, sesión y tipo de evento.](/images/dashboard/events-stream.png) - Luego sigue el evento hasta su sesión. El trazado muestra qué ocurrió inmediatamente antes y después, lo cual es necesario cuando el payload por sí solo resulta ambiguo. + Luego sigue el evento hasta su sesión. El trazado muestra qué ocurrió inmediatamente antes y después, lo cual es necesario cuando el payload por sí solo es ambiguo. ![El trazado de sesión vinculado para inspeccionar el evento en su contexto de ejecución.](/images/dashboard/session-detail.png) - Compara los IDs de correlación y las marcas de tiempo en ambas vistas cuando falte un evento par o una duración. + Compara los IDs de correlación y las marcas de tiempo en ambas vistas cuando falte un evento emparejado o una duración. - Descubre los valores de filtro válidos y luego obtén los payloads completos de los eventos para una sesión: + Descubre los valores de filtro válidos y luego obtén los payloads completos de los eventos de una sesión: ```bash fp list event_types @@ -53,26 +53,26 @@ Cada evento incluye una marca de tiempo, ID de sesión, ID de agente, tipo de ev ## Campos reservados del SDK -No uses `timestamp`, `session_id`, `agent_id`, `type` ni `environment` como campos personalizados del SDK de Python. Las duraciones de eventos pareados, como la duración del resultado de una herramienta, son calculadas por el SDK y no pueden proporcionarse manualmente. +No uses `timestamp`, `session_id`, `agent_id`, `type` ni `environment` como campos personalizados del SDK de Python. Las duraciones de eventos emparejados, como la duración del resultado de una herramienta, son calculadas por el SDK y no pueden proporcionarse manualmente. ## Límites locales -- El estado de Failproof AI reside en `~/.failproofai` a menos que se configure explícitamente de otro modo. -- `failproofai-sdk` usa `AGENTEYE_HOME` para su variable de anulación del directorio base heredada. -- Las etiquetas de entorno pueden definirse mediante la configuración del SDK o con `AGENTEYE_ENVIRONMENT`. -- Las credenciales del daemon se almacenan de forma separada de los ajustes no confidenciales. +- El estado de Failproof AI reside en `~/.failproofai` a menos que se configure explícitamente de otra manera. +- `failproofai-sdk` siempre escribe en el spool bajo `~/.failproofai/custom-agents`. `FAILPROOFAI_HOME` reubica ese directorio raíz; el segmento `custom-agents` siempre se añade, por lo que el spool no puede colocarse fuera de él. Solo el propio `configure(base_dir=...)` del SDK escribe en otro lugar. `AGENTEYE_HOME` es leído por el antiguo `agenteye-collector` para determinar qué observar, y ya no afecta dónde escribe el SDK. +- Las etiquetas de entorno pueden establecerse mediante la configuración del SDK o con `AGENTEYE_ENVIRONMENT`. +- Las credenciales del daemon se almacenan de forma separada de la configuración no secreta. -Usa nombres de entorno estables y de baja cardinalidad. No se admiten comas en las etiquetas de entorno del daemon. +Usa nombres de entorno estables y de baja cardinalidad. Las comas no están admitidas en las etiquetas de entorno del daemon. ## Cambiar una etiqueta de entorno - Las etiquetas de entorno son asignadas por el SDK emisor o por el daemon de Failproof. Después de cambiar una, abre **Observe → Sessions** y usa el filtro de entorno para confirmar que las nuevas sesiones llevan el nuevo valor. Las sesiones existentes conservan su entorno original. + Las etiquetas de entorno son asignadas por el SDK emisor o el daemon de Failproof. Tras cambiar una, abre **Observe → Sessions** y usa el filtro de entorno para confirmar que las nuevas sesiones llevan el nuevo valor. Las sesiones existentes conservan su entorno original. - Para `failproofai-sdk`, configura el entorno en el código o mediante su variable de entorno heredada. Vuelve a ejecutar la configuración del daemon al cambiar ajustes a nivel de máquina. + Para `failproofai-sdk`, configura el entorno en el código o mediante su variable de entorno heredada. Vuelve a ejecutar la configuración del daemon cuando cambies ajustes a nivel de máquina. ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/es/reference/harnesses.mdx b/docs/es/reference/harnesses.mdx index 9cee78170..0b833f918 100644 --- a/docs/es/reference/harnesses.mdx +++ b/docs/es/reference/harnesses.mdx @@ -1,71 +1,71 @@ --- -title: "Entornos de agente" -description: "Captura sesiones y aplica políticas en los 12 entornos de agente compatibles." +title: "Arneses de agentes" +description: "Captura sesiones y aplica políticas en los 12 arneses de agentes compatibles." icon: "plug-zap" --- -Un entorno es el contexto en el que tu agente se ejecuta realmente. Failproof AI es compatible con doce de ellos, en dos categorías: +Un arnes es el entorno en el que tu agente se ejecuta realmente. Failproof AI admite doce de ellos, en dos categorías: -- **CLIs de codificació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 autoalojado) +- **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 asistentes** (2) — Hermes (Slack, Telegram, cron), OpenClaw (asistente auto-hospedado) -Las mismas políticas y el mismo historial de sesiones se aplican independientemente del entorno en que se ejecute un agente. Una capa de adaptador mapea los nombres de eventos nativos, nombres de herramientas y campos de entrada de herramientas de cada entorno a 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 arnes en el que se ejecute un agente. Una capa de adaptador mapea los nombres de eventos nativos, nombres de herramientas y campos de entrada de herramientas de cada arnes sobre 29 eventos canónicos antes de que se ejecute cualquier política. -Un agente que no se ejecuta en **ninguno** de los doce se instrumenta directamente con el [SDK de Python](/es/reference/custom-agents). Ese es un contrato diferente, y vale la pena dejarlo claro: el SDK proporciona trazado, sesiones, evaluaciones y auditorías — **pero no aplica políticas por sí solo.** Bloquear una acción no segura antes de que se ejecute requiere un hook de aplicación en el límite de herramientas de tu entorno de ejecución; [contáctanos](mailto:support@befailproof.ai) y lo mapearemos. +Un agente que no se ejecuta 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 indicarlo claramente: el SDK proporciona trazabilidad, sesiones, evaluaciones y auditorías — **no aplica políticas por sí solo.** Bloquear una acción insegura antes de que se ejecute requiere un hook de cumplimiento en el límite de herramientas de tu entorno de ejecución; [contáctanos](mailto:support@befailproof.ai) y lo mapearemos. -| Entorno | Ámbitos de hook compatibles | +| Arnes | Ámbitos de hook compatibles | | --- | --- | -| 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 | +| 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 | -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 expone el entorno; prueba el comportamiento de fin de turno e instrucciones en el entorno y versión exactos que despliegues. +Cada integración normaliza los 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 arnes expone; prueba el comportamiento de fin de turno e instrucciones en el arnes y versión exactos que despliegues. ## Capacidad 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 se produjo. +"Bloquear" significa que el veredicto devuelto por el adaptador actual es consumido por el arnes indicado. El bloqueo post-herramienta puede reemplazar el resultado mostrado al modelo, pero no puede deshacer un efecto secundario de herramienta que ya ocurrió. -| Entorno | Eventos de bloqueo verificados | Observación o advertencias sin bloqueo | +| Arnes | 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 observacionales. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | El bloqueo post-herramienta reemplaza el resultado después de 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 después de la ejecución; los eventos de sesión y notificación 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 detención actual es orientación para un turno posterior, no una puerta verificada. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Los eventos post-herramienta y de ciclo de vida son observacionales; la orientación de detención se aplica a un turno posterior. | -| Hermes | `PreToolUse` | Los veredictos post-herramienta, de sesión y de subagent-stop no son puertas. | -| 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 prompt de usuario y post-herramienta son observacionales; las instrucciones de prompt aún pueden inyectarse. | -| Goose | `PreToolUse` | Los eventos de prompt de usuario, post-herramienta y de sesión son observacionales. Existe un hook de detención de bloqueo nativo upstream, pero el adaptador actual no lo instala. | +| OpenCode | `PreToolUse` | Los eventos post-herramienta y de ciclo de vida son observacionales; el manejo actual de stop es orientación para un turno posterior, no una puerta verificada. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Los eventos post-herramienta y de ciclo de vida son observacionales; la orientación de stop se aplica a un turno posterior. | +| Hermes | `PreToolUse` | Los veredictos post-herramienta, de sesión y de subagente-stop no son puertas. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Los eventos post-herramienta, de sesión, subagente-stop y compactación son observacionales. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Los veredictos post-herramienta y de subagente-stop son observacionales. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condicional | Los hooks de permisos no se ejecutan en todos los modos de permisos; los eventos post-herramienta y de sesión son observacionales. | +| Antigravity CLI | `PreToolUse`, `Stop` | Los veredictos de prompt de usuario y post-herramienta son observacionales; las instrucciones de prompt pueden seguir inyectándose. | +| Goose | `PreToolUse` | Los eventos de prompt de usuario, post-herramienta y de sesión son observacionales. Existe un hook de stop nativo bloqueante en sentido ascendente, pero el adaptador actual no lo instala. | -Las capacidades dependen de la versión. Vuelve a probar tras actualizar una CLI de agente, especialmente cuando una política depende del comportamiento de prompt, detención, permiso o post-herramienta en lugar de la puerta pre-herramienta habitual. +Las capacidades dependen de la versión. Vuelve a realizar las pruebas tras actualizar una CLI de agente, especialmente cuando una política depende del comportamiento de prompt, stop, permisos o post-herramienta en lugar de la puerta pre-herramienta común. -## Instalar hooks de captura y políticas +## Instalar hooks de captura y política - 1. Abre **Administración → Claves** y crea una clave con `events:add` y `policies:pull`, con un nombre para la máquina o entorno. - 2. En la máquina de destino, conecta la 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 nombre para la máquina o entorno. + 2. En la máquina de destino, conecta la CLI local con la clave mostrada e instala los hooks del arnes. 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 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. - ![El panel de creación de clave API usado para conceder permisos de ingesta de eventos y entrega de políticas.](/images/dashboard/key-create.png) + ![El cajón de nueva clave de API usado para conceder 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 el entorno que conectaste. + Después de instalar los hooks, el flujo de Eventos debería mostrar nuevos eventos de la máquina y el entorno que conectaste. - ![El flujo de Eventos en vivo usado para confirmar que un entorno recién instalado está reportando.](/images/dashboard/events-stream.png) + ![El flujo de Eventos en vivo usado para confirmar que un arnes 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 actividad de políticas además de eventos de trazado. + Finalmente, verifica que las decisiones de política estén atribuidas a la misma máquina. Esto confirma que el arnes está reportando actividad de políticas además de eventos de trazado. - ![La página de Política usada para verificar decisiones de política de un entorno recién conectado.](/images/dashboard/policy-observe.png) + ![La página de Política usada para verificar decisiones de política de un arnes recién conectado.](/images/dashboard/policy-observe.png) - Instala hooks para todos los entornos detectados: + Instala hooks para todos los arneses detectados: ```bash failproofai config \ @@ -74,7 +74,7 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar una CLI failproofai policies --install ``` - O apunta a entornos específicos y un ámbito de configuración: + O apunta a arneses específicos y un ámbito de configuración: ```bash failproofai policies --install \ @@ -82,7 +82,7 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar una CLI --scope user ``` - El ámbito de proyecto mantiene la configuración de hooks con un repositorio. El ámbito de usuario cubre el trabajo a través de repositorios. Claude Code también admite ámbito local; el soporte varía según el entorno y la CLI rechaza las combinaciones no compatibles. + El ámbito de proyecto mantiene la configuración de hooks junto a un repositorio. El ámbito de usuario cubre el trabajo en varios repositorios. Claude Code también admite ámbito local; la compatibilidad varía según el arnes y la CLI rechaza las combinaciones no admitidas. Verifica la máquina y sus eventos: @@ -94,16 +94,16 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar una 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. Después de añadir una, abre **Observar → Sesiones**, filtra al entorno de la máquina y confirma que aparecen sesiones de la nueva ruta. Abre una sesión y comprueba 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 la nube. Después de agregar 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 comprueba el agente, el arnes y las marcas de tiempo de los eventos antes de usarla 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 +117,5 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar una 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 nueva sesión después de la instalación. Verifica tanto el flujo de eventos en vivo 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 a33717608..a8fd4fdc5 100644 --- a/docs/es/reference/overview.mdx +++ b/docs/es/reference/overview.mdx @@ -8,10 +8,13 @@ Elige la integración más cercana al entorno donde ya se ejecuta tu agente. - Instala hooks para CLIs de agentes de codificación y autónomos compatibles. + Instala hooks para CLIs de agentes de código y autónomos compatibles. - - Instrumenta trazas para encontrar fallos en agentes personalizados y contáctanos para añadir prevención a tu runtime. + + Instrumenta LangGraph, CrewAI, LlamaIndex, Pydantic AI o un agente personalizado. + + + Configuración, el catálogo de eventos, reglas de correlación y entrega. Revisa proyectos locales, sesiones, actividad de políticas y auditorías sin conexión. @@ -20,20 +23,20 @@ Elige la integración más cercana al entorno 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 configuraciones en la nube. + Consulta y administra sesiones de Cloud, auditorías, incidencias, alertas, claves, usuarios y configuraciones. Puntúa sesiones completas o inactivas con un servicio FastAPI. - Crea y prueba decisiones de allow, instruct y deny específicas para tu flujo de trabajo. + Crea y prueba decisiones allow, instruct y deny específicas para tu flujo de trabajo. - - Despliega el plano de control en la nube sobre un clúster de Kubernetes gestionado por el cliente. + + Despliega el plano de control de Cloud en un clúster de 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 a mano 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 manualmente explican flujos de trabajo que abarcan múltiples endpoints o utilizan interfaces administrativas fuera de esa superficie pública. ## Conectar un agente y verificar los datos @@ -41,21 +44,21 @@ La [referencia de la API HTTP](/es/reference/http-api) generada cubre la superfi 1. Abre **Administración → Claves**, crea una clave con `events:add` y `policies:pull`, y copia el secreto. 2. Configura la integración utilizando la página correspondiente indicada arriba. - 3. Abre **Observar → Eventos** para confirmar que llegan eventos y, a continuación, **Observar → Sesiones** para confirmar que se agrupan en ejecuciones completas. + 3. Abre **Observar → Eventos** para confirmar que los eventos llegan, 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 por el panel de claves. Los permisos seleccionados determinan si la máquina puede enviar eventos y recibir políticas gestionadas en la nube. + Comienza con el panel de claves. Los permisos seleccionados determinan si la máquina puede enviar eventos y recibir políticas gestionadas desde Cloud. - ![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 conceder permisos de ingesta de eventos y entrega de políticas.](/images/dashboard/key-create.png) - 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. + 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. - ![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) + ![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 como completada; la traza debe contener el modelo, la herramienta, el error y la evidencia de política que necesitan tus auditorías. + Abre una de estas sesiones antes de dar la integración por completa; el trazado 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 demonio de Failproof y verifica la primera sesión. + Crea una clave de máquina, conecta el daemon de Failproof y verifica la primera sesión. ```bash fp keys create agent-production \ @@ -71,8 +74,8 @@ La [referencia de la API HTTP](/es/reference/http-api) generada cubre la superfi fp events --since 1h --env production --limit 20 ``` - Usa `fp --json sessions ...` cuando otro programa vaya a consumir el resultado. Las opciones globales como `--json`, `--org` y `--base-url` deben ir antes del comando. + Usa `fp --json sessions ...` cuando otro programa vaya a consumir el resultado. Los flags globales como `--json`, `--org` y `--base-url` deben ir antes del comando. - Consulta la [referencia del CLI de Failproof AI](/es/reference/failproof-cli) para comandos locales y la [referencia del CLI de Failproof Cloud](/es/reference/cloud-cli#cli-commands) para comandos `fp`. + Consulta la [referencia del CLI de Failproof AI](/es/reference/failproof-cli) para los comandos locales y la [referencia del CLI de Failproof Cloud](/es/reference/cloud-cli#cli-commands) para los comandos `fp`. \ No newline at end of file diff --git a/docs/es/reference/troubleshooting.mdx b/docs/es/reference/troubleshooting.mdx index 3485e4a02..cadda7682 100644 --- a/docs/es/reference/troubleshooting.mdx +++ b/docs/es/reference/troubleshooting.mdx @@ -8,7 +8,7 @@ icon: "wrench" - Abre **Administración → Claves** y confirma que la clave de máquina está activa y tiene `events:add`. Luego abre **Observar → Eventos**, amplía el rango de tiempo y borra los filtros de entorno y agente. Si existen eventos, busca el ID de sesión y comprueba **Observar → Sesiones** para ver la agrupación. Si no hay eventos, diagnostica el daemon de Failproof desde la CLI. + Abre **Administration → Keys** y confirma que la clave de máquina está activa y tiene `events:add`. Luego abre **Observe → Events**, amplía el rango de tiempo y limpia los filtros de entorno y agente. Si existen eventos, busca el ID de sesión y luego comprueba **Observe → Sessions** para la agrupación. Si no existen eventos, diagnostica el daemon de Failproof desde la CLI. ![El flujo de eventos en vivo con sus filtros principales visibles y eventos de agente recientes llegando.](/images/dashboard/events-stream-current.png) @@ -28,7 +28,7 @@ icon: "wrench" - Borra los filtros en **Observar → Eventos** y busca el ID de sesión exacto del SDK. Si no aparece nada, inspecciona el spool del SDK y el daemon de Failproof en la máquina de origen. + Limpia los filtros en **Observe → Events** y busca el ID de sesión exacto del SDK. Si no aparece nada, inspecciona el spool del SDK y el daemon de Failproof en la máquina de origen. ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - Confirma que el proceso del agente establece `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` y que `$FAILPROOFAI_HOME/custom-agents`, o en su defecto `~/.failproofai/custom-agents`, existe antes de que el SDK se inicie. + Confirma que hay un daemon en ejecución y conectado — el SDK hace spool independientemente de si hay uno activo. El directorio de spool **no** necesita existir de antemano (el escritor lo crea), y ninguna variable de entorno lo selecciona: `$FAILPROOFAI_HOME/custom-agents` o, en su defecto, `~/.failproofai/custom-agents` es la única raíz, y `configure(base_dir=...)` es la única forma de sobreescribirlo. Si el proceso fue terminado con `SIGKILL` o por falta de memoria, todo lo que estaba en cola se pierde — maneja `SIGTERM` para acotar esa situación. - Abre **Admin → aplicación**, selecciona la máquina y compara sus versiones asignada, reportada y anterior. Confirma que el alcance de despliegue incluye la máquina y que su clave tiene `policies:pull`. La ingesta puede funcionar aunque la entrega de políticas no lo haga. + Abre **Admin → enforcement**, selecciona la máquina y compara sus versiones asignada, reportada y anterior. Confirma que el alcance de despliegue incluye la máquina y que su clave tiene `policies:pull`. La ingesta puede funcionar aunque la entrega de políticas falle. @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - Confirma que el ID y la etiqueta de la máquina coinciden con el objetivo del dashboard. Reconéctate con una clave que admita políticas si la credencial existente solo permite la ingesta de eventos. + Confirma que el ID y la etiqueta de la máquina coinciden con el objetivo en el dashboard. Reconéctate con una clave habilitada para políticas si la credencial actual solo permite la ingesta de eventos. - Abre **Admin → aplicación** e inspecciona la última vez que se vio la máquina y la versión reportada. Si la máquina está desactualizada, trátalo como un problema local del daemon. No debilites la política desplegada únicamente para eludir un daemon no disponible. + Abre **Admin → enforcement** e inspecciona la última vez que se vio la máquina y su versión reportada. Si la máquina está desactualizada, trátalo como un problema local del daemon. No debilites la política desplegada solo para eludir un daemon no disponible. @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - Reinicia o actualiza `failproofaid`; vuelve a ejecutar la configuración cuando las versiones de protocolo de la CLI y el daemon difieran. El daemon configurado falla de forma cerrada por diseño. + Reinicia o actualiza `failproofaid`; vuelve a ejecutar la configuración cuando las versiones de protocolo de la CLI y del daemon difieran. La ruta de daemon configurada falla de forma cerrada por diseño. - + - Para una política creada en Cloud, abre **Admin → editor de políticas**, selecciona el borrador y revisa los errores de validación antes de publicar. Para una política local, valídala desde la CLI y luego abre **Observar → política** tras una acción de prueba para confirmar que llegan las decisiones. + Para una política creada en Cloud, abre **Admin → policy editor**, selecciona el borrador y revisa los errores de validación antes de publicar. Para una política local, valídala con la CLI y luego abre **Observe → policy** tras una acción de prueba para confirmar que llegan las decisiones. - Confirma que el nombre del archivo termina en `policies.js`, `policies.mjs` o `policies.ts`, que el módulo llama a `customPolicies.add(...)` y que las importaciones se resuelven desde el archivo de política. + Confirma que el nombre de archivo termina en `policies.js`, `policies.mjs` o `policies.ts`, que el módulo llama a `customPolicies.add(...)` y que las importaciones se resuelven desde el archivo de política. ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -91,12 +91,12 @@ icon: "wrench" - + - Abre **Analizar → auditorías**, selecciona la ejecución y comprueba si se realizó el análisis del modelo. Luego compara su alcance y ventana con **Observar → sesiones** y abre trazas representativas de esa población. + Abre **Analyze → audits**, selecciona la ejecución y comprueba si el análisis del modelo se ejecutó. Luego compara su alcance y ventana con **Observe → sessions** y abre trazas representativas de esa población. - Un resultado cero solo es significativo cuando el análisis se completó correctamente. Si el análisis fue omitido o falló, la ejecución no produce hallazgos y mantiene la ventana sin analizar abierta para una futura ejecución exitosa. Si el análisis del modelo está deshabilitado, la auditoría tampoco produce hallazgos, ya que el escaneo determinista de credenciales e información personal solo registra estadísticas sin generar alertas. + Un resultado en cero solo es significativo cuando el análisis se ejecutó correctamente. Si el análisis fue omitido o falló, la ejecución no produce resultados y mantiene la ventana sin analizar abierta para una futura ejecución exitosa. Si el análisis del modelo está deshabilitado, la auditoría tampoco produce resultados, ya que el análisis determinista de credenciales y PII registra estadísticas pero ya no genera hallazgos. ![El formulario de auditoría donde el entorno, el agente, la cadencia y la ventana de barrido definen la población de sesiones.](/images/dashboard/audit-new.png) @@ -110,14 +110,14 @@ icon: "wrench" fp audits findings --audit ``` - Si la ejecución permaneció en cola, espera a que haya capacidad del agente de auditoría o pide al operador del despliegue que inspeccione la flota de auditorías. Una auditoría en cola reintenta; no se omite de inmediato. + Si la ejecución permaneció en cola, espera a que haya capacidad del agente de auditoría o pide al operador de despliegue que inspeccione la flota de auditoría. Una auditoría en cola reintenta; no se omite de inmediato. - Abre una sesión completada y comprueba si una evaluación manual tiene éxito. El Cloud alojado actualmente no ofrece control del endpoint del evaluador en el dashboard; el operador del servidor debe configurarlo. + Abre una sesión completada y comprueba si una evaluación manual tiene éxito. El Cloud alojado actualmente no tiene control del endpoint del evaluador en el dashboard; el operador del servidor debe configurarlo. Verifica el evaluador en sí y luego inspecciona los estados de evaluación recientes: @@ -127,7 +127,7 @@ icon: "wrench" fp evals --since 1h ``` - En Cloud autoalojado, confirma que `EVALUATOR_ENDPOINT` está presente en el servidor y que `EVALUATOR_TOKEN` coincide con el evaluador. La evaluación automática está deshabilitada cuando el endpoint no está presente. + En Cloud autoalojado, confirma que `EVALUATOR_ENDPOINT` está presente en el servidor y que `EVALUATOR_TOKEN` coincide con el evaluador. La evaluación automática se deshabilita cuando el endpoint está ausente. @@ -150,11 +150,11 @@ icon: "wrench" - Abre **Observar → política**, conserva la decisión y la sesión vinculada, e identifica la condición de falso positivo. Luego abre **Admin → aplicación** y revierte las máquinas afectadas a la versión anterior. Crea una versión más restrictiva en el **Editor de políticas**, pruébala en un alcance reducido y amplíala solo cuando el trabajo válido tenga éxito. + Abre **Observe → policy**, preserva la decisión y la sesión vinculada, e identifica la condición de falso positivo. Luego abre **Admin → enforcement** y revierte las máquinas afectadas a la versión anterior. Crea una versión más restrictiva en **Policy editor**, pruébala en un alcance reducido y amplíala solo después de que el trabajo válido tenga éxito. - La reversión del despliegue en Cloud es exclusiva del dashboard. Pausar una sesión local no deshabilita las políticas gestionadas por Cloud. Si el dashboard no está disponible, captura el estado de la máquina y del despliegue y restablece el acceso al dashboard en lugar de reintentar repetidamente la acción bloqueada. + La reversión del despliegue en Cloud es exclusiva del dashboard. Pausar una sesión local no deshabilita las políticas gestionadas por Cloud. Si el dashboard no está disponible, captura el estado de la máquina y del despliegue y restaura el acceso al dashboard en lugar de reintentar repetidamente la acción bloqueada. ```bash failproofai config --status diff --git a/docs/es/sessions/live-events.mdx b/docs/es/sessions/live-events.mdx index 5a4e668cc..c3326a43e 100644 --- a/docs/es/sessions/live-events.mdx +++ b/docs/es/sessions/live-events.mdx @@ -1,21 +1,21 @@ --- title: "Eventos en vivo" -description: "Observa la actividad del agente en tiempo real mientras se ejecuta una sesión." +description: "Observa la actividad del agente en tiempo real mientras una sesión está en ejecución." icon: "radio" --- -Los eventos en vivo te permiten confirmar la instrumentación y supervisar una ejecución de riesgo sin tener que esperar a que la sesión termine. +Los eventos en vivo te ayudan a confirmar la instrumentación y supervisar una ejecución de riesgo sin esperar a que la sesión finalice. ## Ver actividad - + 1. Ve a **Observe → Events**. 2. Comienza con la ventana de tiempo actual y sin filtros para confirmar que los datos están llegando. 3. Filtra por entorno, tipo de evento, agente o sesión. Usa la búsqueda para texto en el payload. - 4. Selecciona un evento para inspeccionar su resumen y detalles. Sigue el enlace de sesión para ver el trazado completo. + 4. Selecciona un evento para inspeccionar su resumen y detalles. Sigue el enlace de su sesión para ver el seguimiento completo. - ![El flujo en vivo de Events mostrando tráfico de una gateway de chat Hermes junto con ejecuciones de la CLI de codificación, filtrado por tiempo, entorno, tipo de evento, agente, modelo, contexto y sesión.](/images/dashboard/events-stream-current.png) + ![El flujo de eventos en vivo mostrando tráfico desde una pasarela de chat Hermes junto con ejecuciones de la CLI de codificación, filtrado por tiempo, entorno, tipo de evento, agente, modelo, contexto y sesión.](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +24,22 @@ Los eventos en vivo te permiten confirmar la instrumentación y supervisar una e fp --json events --full --session-id --all ``` - El feed predeterminado omite los payloads sin procesar. Usa `--full` solo para investigar una sesión acotada. + El feed por defecto omite los payloads sin procesar. Usa `--full` únicamente para una investigación de sesión acotada. -Utiliza el flujo de eventos para responder tres preguntas inmediatas: +Usa el flujo de eventos para responder tres preguntas inmediatas: - ¿El agente esperado está reportando al entorno correcto? -- ¿Están llegando en orden las llamadas al modelo, las llamadas a herramientas y las decisiones de políticas? -- ¿La sesión ha dejado de avanzar o ha empezado a repetir una acción? +- ¿Las llamadas al modelo, las llamadas a herramientas y las decisiones de política están llegando en orden? +- ¿La sesión ha dejado de avanzar o ha comenzado a repetir una acción? -Los tipos de eventos incluyen eventos del ciclo de vida del agente, solicitudes y respuestas del modelo, uso de herramientas y resultados, ejecución de hooks, esperas e interrupciones humanas, y errores explícitos. Los IDs de correlación enlazan eventos pareados, como una llamada a herramienta y su resultado. +Los tipos de eventos incluyen eventos del ciclo de vida del agente, solicitudes y respuestas del modelo, uso de herramientas y sus resultados, ejecución de hooks, esperas e interrupciones humanas, y errores explícitos. Los IDs de correlación vinculan eventos emparejados, como una llamada a herramienta y su resultado. - Mantén la vista en vivo sin filtros mientras verificas una nueva integración. Agrega filtros solo después de ver el primer evento; un filtro incorrecto puede parecer un fallo de ingesta. + Mantén la vista en vivo amplia mientras verificas una nueva integración. Añade filtros solo después de ver el primer evento; un filtro incorrecto puede parecer un fallo de ingesta. -Si no aparecen eventos, ejecuta `failproofai config --status` y luego [soluciona problemas de ingesta](/es/reference/troubleshooting). +Si no aparece ningún evento, ejecuta `failproofai config --status` y luego [soluciona problemas de ingesta](/es/reference/troubleshooting). -Los agentes que no se ejecutan en uno de los 12 [harnesses](/es/reference/harnesses) compatibles reportan los mismos tipos de eventos a través del [Python SDK](/es/reference/custom-agents), incluidos los eventos de human-in-the-loop (`human_wait`, `human_input`, `human_interrupt`) de los que dependen los agentes de gateway y producción. \ No newline at end of file +Los agentes que no se ejecutan en uno de los 12 [harnesses](/es/reference/harnesses) compatibles reportan los mismos tipos de eventos a través del [SDK de Python](/es/reference/custom-agents), incluidos los eventos de human-in-the-loop (`human_wait`, `human_input`, `human_interrupt`) de los que dependen los agentes de pasarela y producción. \ No newline at end of file diff --git a/docs/es/start/first-policy.mdx b/docs/es/start/first-policy.mdx index 5b217ede1..603020d3c 100644 --- a/docs/es/start/first-policy.mdx +++ b/docs/es/start/first-policy.mdx @@ -1,10 +1,10 @@ --- -title: "Evita tu primer fallo con una política" +title: "Previene tu primer fallo con una política" description: "Crea una versión de política, despliégala en modo observación y luego aplícala." icon: "shield-check" --- -Utiliza una política solo cuando puedas describir la acción no segura y las acciones legítimas que deben seguir permitidas. +Usa una política solo cuando puedas describir la acción insegura y las acciones legítimas que deben seguir permitidas. @@ -12,17 +12,17 @@ Utiliza una política solo cuando puedas describir la acción no segura y las ac Ve a **Admin → editor de políticas**. Empieza con la política de demostración, revisa o edita su código fuente y luego selecciona **publicar versión**. Al publicar se crea la versión inmutable que podrás desplegar en las máquinas. - ![La vista de composición del editor de políticas con una política de demostración lista para publicarse como versión inmutable.](/images/dashboard/policy-editor.png) + ![Vista de composición del editor de políticas con una política de demostración lista para publicarse como versión inmutable.](/images/dashboard/policy-editor.png) - Ve a **Admin → aplicación**, expande la máquina de destino y selecciona **editar esta máquina**. Añade la política de demostración publicada, fija su versión, elige **observar** y aplica el despliegue. + Ve a **Admin → enforcement**, expande la máquina de destino y selecciona **editar esta máquina**. Añade la política de demostración publicada, fija su versión, elige **observe** y aplica el despliegue. - ![El editor de despliegue de máquina con una versión de política publicada seleccionada en modo observación antes de aplicar el despliegue.](/images/dashboard/enforcement-editor.png) + ![El editor de despliegue de máquinas con una versión de política publicada seleccionada en modo observación antes de aplicar el despliegue.](/images/dashboard/enforcement-editor.png) - Ejecuta una nueva sesión de agente en esa máquina y luego abre **Observar → política**. Selecciona la máquina y confirma que la política de demostración aparece en el mapeo de políticas y en la línea de tiempo de decisiones. El modo observación registra lo que haría la política sin bloquear la acción. + Ejecuta una nueva sesión de agente en esa máquina y luego abre **Observe → policy**. Selecciona la máquina y confirma que la política de demostración aparece en el mapeo de políticas y en la línea de tiempo de decisiones. El modo observación registra lo que haría la política sin bloquear la acción. - ![La página de políticas mostrando totales de decisiones, actividad de aplicación a lo largo del tiempo y mappings de políticas locales y gestionadas en la nube.](/images/dashboard/policy-observe.png) + ![La página de política mostrando los totales de decisiones, la actividad de enforcement a lo largo del tiempo y los mapeos de políticas locales y gestionadas en la nube.](/images/dashboard/policy-observe.png) @@ -42,6 +42,6 @@ Utiliza una política solo cuando puedas describir la acción no segura y las ac fp sessions --env production --since 24h ``` - La CLI de la nube no expone las rutas de despliegue de aplicación exclusivas del administrador. Publica versiones desde **Admin → editor de políticas** y despliégalas desde **Admin → aplicación**. + Ambos pasos también están disponibles desde la CLI: `fp policies publish ` genera una versión y `fp fleet deploy --add ` la instala en una máquina. Los equivalentes en el panel de control son **Admin → editor de políticas** y **Admin → enforcement**. \ No newline at end of file diff --git a/docs/es/start/integrations.mdx b/docs/es/start/integrations.mdx new file mode 100644 index 000000000..1dd56c4aa --- /dev/null +++ b/docs/es/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "Instrumenta tu agente" +sidebarTitle: "Frameworks" +description: "Conecta cualquier framework de agentes compatible con Failproof AI con una sola llamada." +icon: "plug" +--- + +Tu agente ya produce todo lo que vale la pena registrar: llamadas a modelos, llamadas a herramientas, límites de nodos, esperas humanas y fallos. El framework lo descarta. El SDK lo conserva. + + + + Un agente que escribiste tú mismo, o uno que no aparece aquí. + + + Grafos, nodos, herramientas, retrievers, modelos. + + + Crews, flujos, agentes por rol, herramientas. + + + Workflows, pasos, agentes de funciones, retrievers. + + + Agentes tipados, capacidades, herramientas, reintentos. + + + +## Tres líneas, cualquiera que sea el framework + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # detecta los frameworks que importaste + +with failproofai_sdk.session(): + ... # tu llamada al agente existente, sin cambios +``` + +Sin decoradores en tus funciones, sin callbacks pasados a tus llamadas, sin ids propagados por tu código. Solo difiere la llamada dentro de la sesión: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # bajo `async with failproofai_sdk.session():` + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +El extra instala el **framework**. Cada adaptador viene incluido en el paquete base, por lo que un proyecto que ya tenga su framework no necesita ningún extra en absoluto. + +## Verifica que llegó + +Ejecuta una sesión instrumentada y luego abre **Observe → Sessions** y selecciona tu entorno. La ejecución aparece como una traza reconstruida. + +Si no llega nada, confirma que la máquina está conectada con `failproofai config --status`. Consulta [Configurar la captura](/es/start/setup). + + + No compruebes el directorio de spool para confirmar la entrega. El daemon de Failproof recopila y elimina cada lote en cuestión de milisegundos, por lo que leerlo compite con el recolector y muestra muchos menos eventos de los que se emitieron. + + +## Siguientes pasos + +Cada quickstart de arriba enlaza a su guía completa: qué se registra, opciones, streaming, nombres de spans y los problemas que la gente realmente encuentra. Se encuentran en **Trace Agents → Plug in your agent**. + + + + El modelo de datos, los ids, los tipos de eventos y cómo los eventos llegan a Cloud. + + + Sigue la causalidad a través de una sesión en lugar de logs desconectados. + + + Audita las sesiones que acabas de capturar. + + \ No newline at end of file diff --git a/docs/es/start/integrations/crewai.mdx b/docs/es/start/integrations/crewai.mdx new file mode 100644 index 000000000..784c2f52b --- /dev/null +++ b/docs/es/start/integrations/crewai.mdx @@ -0,0 +1,224 @@ +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "Instrumenta crews, flows, agentes por rol, herramientas, memoria y retroalimentación humana." +icon: "/images/frameworks/crewai.svg" +--- + +## Instalación + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +Compatible con: `crewai` 1.13 a 2.0. La versión 1.13 fue la que introdujo `started_event_id` y normalizó el uso de tokens, dos características de las que depende el adaptador para emparejar eventos e informar tokens. + +## Instrumentación + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` registra un listener en el bus de eventos a nivel de módulo de CrewAI y suscribe un handler por clase de evento. Nada en tu crew, agentes, tareas o herramientas cambia. + +## Qué se registra + +| CrewAI | Evento Failproof | +| --- | --- | +| Kickoff de crew | `agent_start`, `agent_end` | +| `Agent.kickoff()` (agente ligero, sin crew) | `agent_start`, `agent_end`, con `agent_id` obtenido del rol | +| Inicio y fin de flow | `agent_start`, `agent_end`; un crew lanzado dentro de un método de flow se anida bajo él | +| Ejecución de agente | `agent_start`, `agent_end` anidados, con `agent_id` obtenido del rol. En un proceso jerárquico, un colaborador delegado se anida bajo el manager, no a su mismo nivel | +| Tarea | Nada; se registra como enlace para que los hijos resuelvan al crew | +| Método de flow, guardrail | `hook_triggered`, `hook_completed` | +| Uso de herramientas | `tool_use`, `tool_result` | +| Operaciones de memoria y conocimiento | `tool_use`, `tool_result`, nombradas según la superficie accedida | +| Llamada LLM | `model_request`, `model_response`, con uso de tokens | +| Fragmento de stream | Se integra en la respuesta como conteo de fragmentos y tiempo hasta el primer token | +| Retroalimentación humana solicitada | `human_wait`, `agent_pause` | +| Retroalimentación humana recibida | `agent_resume`, `human_input` | +| Error en ejecución de agente | `error`, luego `agent_end` con resultado `failed` | + +Una tarea no emite nada de forma deliberada. Una tarea de CrewAI es un subconjunto de la ejecución del agente que la ejecuta; emitir ambas duplicaría cada fila y las mostraría como hermanas. El id y nombre de la tarea viajan en los propios eventos del agente. + +Las operaciones de memoria y conocimiento se registran como herramientas, nombradas según la superficie a la que acceden, de modo que aparecen junto a tus herramientas reales donde puedes comparar su latencia. + +En un crew jerárquico, el anidamiento es lo que hace legible el trace: + +```text +crew +└─ manager + ├─ researcher delegated + └─ writer delegated +``` + +CrewAI asocia una ejecución delegada al evento de herramienta **`delegate_work_to_coworker`**, no al manager directamente, por lo que el adaptador sigue ese enlace. Sin él, todos los agentes quedarían como hermanos entre sí y se perdería la estructura de delegación. + +## Ejemplo + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # becomes agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +El traspaso es visible en el trace: el span del `analyst` se cierra, el span del `writer` se abre, y ambos están dentro de un único span `crew`. + +## Nombra tus spans + +`agent_id` proviene de `Agent(role=...)`, lo que lo convierte en una faceta legible en el dashboard. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # una entrada de faceta por ejecución +``` + +`agent_id` es una columna de baja cardinalidad. Un rol que contenga un id de ejecución o timestamp la degrada para todas las consultas. Si un rol parece un id, el adaptador lo rechaza y coloca el valor real en un campo de payload en su lugar. + +## Controla la sesión + +Se resuelve en este orden, ganando el primer resultado: + +1. `instrument("crewai", session_id=...)` +2. El scope de `failproofai_sdk.session()` que lo envuelve +3. Un `uuid4().hex` generado, una vez por crew o flow + +Envuelve el kickoff para controlarlo por ejecución: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## Opciones + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # fija cada ejecución a un session id +) +``` + +`session_id` es la única opción que lee este adaptador. Los prompts y completions siempre se registran, truncados al presupuesto de payload. + +## Human in the loop + +CrewAI tiene **dos** superficies de human-in-the-loop, y ambas se registran con los mismos cuatro eventos. + +`@human_feedback` en un método de flow pasa por el bus de eventos de CrewAI: el runtime emite un evento antes de bloquearse esperando a una persona y otro después de recibir la respuesta. + +`Task(human_input=True)` no lo hace. Llama a `input()` dentro del propio proveedor de entrada de CrewAI y no emite ningún evento, por lo que el adaptador envuelve directamente ese proveedor — sin ello, toda la espera humana era invisible y se facturaba como tiempo activo del agente. + +En cualquier caso obtienes: + +```text +human_wait the prompt and its options +agent_pause starts the paused-time clock +agent_resume stops it +human_input the answer, with the wait measured +``` + +El par `agent_pause` a `agent_resume` es el único que alimenta el tiempo en pausa. Sin él, una espera humana de diez minutos se factura como diez minutos de tiempo activo del agente. + + + CrewAI no establece ningún id de correlación en ninguno de los eventos de human-feedback, por lo que el adaptador los empareja usando el nombre del flow y del método, recurriendo en su defecto a la pausa abierta más recientemente. Esto es correcto porque un prompt de consola bloquea la ejecución. Si construyes un proveedor de feedback concurrente, establece `request_id` en ambos eventos. + + + + Dado que la ruta `Task(human_input=True)` es un wrapper alrededor del proveedor de entrada de CrewAI en lugar de una suscripción a eventos, se restaura al llamar a `uninstrument()` y vuelve a lanzar cualquier excepción que lance `input()`, incluyendo `KeyboardInterrupt`, sin modificarla. + + +## Problemas comunes + + + + Un `role` contiene un UUID, timestamp o sufijo por ejecución. Usa un rol humano estable y coloca el id específico de la ejecución en la descripción de la tarea. + + + + El bus de eventos es asíncrono y `kickoff()` retorna antes de que terminen de ejecutarse los últimos handlers. Drénalo primero: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + Esto es una característica de CrewAI, no del SDK. + + + + `agent_end` fuerza el cierre de pausas abiertas pero no de herramientas ni modelos, por lo que una ejecución que muere dentro de una llamada a herramienta deja ese span abierto. El cierre normal cierra lo que quede abierto y lo marca como incompleto. Solo un `SIGKILL` lo deja colgado, porque nada puede ejecutarse. + + + + Verifica en este orden: `instrument()` se ejecutó antes que `kickoff()`; hay un `with failproofai_sdk.session():` alrededor; `crewai` es 1.13 o más reciente; `FAILPROOFAI_SDK_STRICT=1` está definido, para que un hook degradado lance una excepción en lugar de ser silenciado. + + + +## Siguientes pasos + + + + 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, LlamaIndex, Pydantic AI y agentes personalizados. + + \ No newline at end of file diff --git a/docs/es/start/integrations/custom-agents.mdx b/docs/es/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..09d79215c --- /dev/null +++ b/docs/es/start/integrations/custom-agents.mdx @@ -0,0 +1,739 @@ +--- +title: "Agentes personalizados" +sidebarTitle: "Agentes personalizados" +description: "Instrumenta un agente que escribiste tú mismo, o un framework sin adaptador." +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. + +## Instalación + +```bash +pip install failproofai-sdk +``` + +Sin extras ni dependencias. + +## Instrumentación + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # una ejecución + with failproofai_sdk.agent("planner"): # una unidad de trabajo + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) # una llamada a herramienta +``` + +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á 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 cada uno emite realmente: + +| Ámbito | Emite | Propósito | +| --- | --- | --- | +| `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 lee de vuelta, por lo que nunca necesitas pasar ids a través de tus funciones. + +Los tres funcionan tanto con `async with` como con `with`. + +Anidar agentes construye el árbol. `parent_id` y la profundidad se calculan desde la pila: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## Cómo se cierra un ámbito + +`agent()` gestiona las excepciones por ti: + +| Qué ocurrió | Eventos | Resultado | +| --- | --- | --- | +| No se lanzó nada | `agent_end` | `success` | +| `Exception` | `error`, luego `agent_end` | `failed` | +| `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. + +## 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. + +| Familia | Abre | Cierra | Independiente | +| --- | --- | --- | --- | +| **Agentes** | `agent_start` | `agent_end` | — | +| | `agent_pause` | `agent_resume` | — | +| **Modelos** | `model_request` | `model_response` | — | +| **Herramientas** | `tool_use` | `tool_result` | — | +| **Hooks** | `hook_triggered` | `hook_completed` | — | +| **Humanos** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **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. + + + +```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 Models +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 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 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 Failures +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **Las dos familias de humanos apuntan en direcciones opuestas.** + + | 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 | + + Ningún framework señaliza el segundo par, por lo que siempre es tuya la responsabilidad de 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. + + +## Ejemplo + +Un bucle de llamada a herramientas contra la API de OpenAI, sin ningún framework de agentes: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +MODEL = "gpt-4o-mini" + + +def turn(messages: list): + """Una llamada al modelo, delimitada por el par.""" + failproofai_sdk.event.model_request(model=MODEL, messages=messages) + reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) + usage = reply.usage + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +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 + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +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 + +Las variables de contexto se propagan automáticamente a las tareas de asyncio. No se propagan a nuevos hilos, porque un hilo comienza con un contexto vacío. + +```python +# asyncio: nada que hacer +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# hilos: envuelve el 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) +``` + +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 + +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 resulta | +| --- | --- | --- | +| La ejecución | `session()` + `agent()` | `agent_start`, `agent_end` | +| Cada herramienta | `tool_call()` | `tool_use`, `tool_result` | +| Cada llamada al modelo | El par `model_*` | `model_request`, `model_response` | + + + + ```python + with failproofai_sdk.session(): + with failproofai_sdk.agent(agent_name, goal=task): + result = framework.run(task) + ``` + + + En lo que el framework llame wrapper de herramienta o 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(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **¿Tienes un límite de nodo, paso o middleware que vale la pena ver?** Envuélvelo en un par de hooks — `hook_triggered` / `hook_completed` — no en un `agent()` anidado. `agent_id` es una faceta de baja cardinalidad, y una entrada por nodo la satura. Los spans de hooks se renderizan igual y te dan latencia por nodo. + + + + **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 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. + + +## Profundizando + +Cómo funciona la grabación realmente. 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. + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + 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. + +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. + + + + ```text 14 eventos + 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 + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 14 +5.721s agent_end LangGraph · success + ``` + + Los nodos se convierten en pares de hooks, por lo que obtienes latencia por nodo sin que saturen la lista de agentes. + + + + ```text 10 eventos + 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 + 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 + 9 +5.727s agent_end analyst · success + 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. + + + + ```text 26 eventos + 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 + 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 + ... segunda iteración + 26 +7.038s agent_end Agent · success + ``` + + El propio bucle del agente es visible, no solo sus llamadas al modelo. + + + + ```text 8 eventos + 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 + 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 + 8 +8.119s agent_end agent · success + ``` + + Sin pares de hooks: Pydantic AI no tiene límite de nodo o paso que delimitar. + + + + ```text 6 eventos + 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 + 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. + + + + + + + +**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: + +| Estado | Cuándo | +| --- | --- | +| `ongoing` | Al menos un span sigue abierto | +| `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 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 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: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + 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`. + +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 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, 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` + +Gana la primera coincidencia: + +1. Una opción `session_id` explícita +2. Metadatos por llamada +3. El ámbito `session()` que lo contiene +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. + +#### 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. + +Los adaptadores protegen esa columna por ti: + +| 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 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 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 | +| --- | --- | +| Agentes | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| Modelos | `model_request`, `model_response` | +| Herramientas | `tool_use`, `tool_result` | +| Hooks | `hook_triggered`, `hook_completed` | +| Humanos | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| Fallos | `error` | + +Qué registra cada framework, medido desde 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ú | +| 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ú | + +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 de apertura. + +| Abre | Cierra | El evento de cierre lleva | +| --- | --- | --- | +| `agent_start` | `agent_end` | `outcome`, `summary` | +| `model_request` | `model_response` | tokens, `stop_reason`, latencia | +| `tool_use` | `tool_result` | `output` o `error`, duración | +| `hook_triggered` | `hook_completed` | `outcome`, duración | +| `agent_pause` | `agent_resume` | cuánto duró la pausa | +| `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. + + +#### Reglas de correlación + +- 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 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, 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 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 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") # deshacerlo +``` + +| Nombre | También acepta | +| --- | --- | +| `langchain` | `langgraph`, `langchain_core` | +| `crewai` | — | +| `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: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +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. + + 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 inicie tu proceso, no lo establezcas a mitad de 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 `()`. + + + +```python Wrong +import failproofai_sdk +failproofai_sdk.instrument() # sys.modules aún no tiene langchain -> () + +import langchain # demasiado tarde, nada está conectado +``` + +```python Right +import langchain # importa el framework primero +import failproofai_sdk + +failproofai_sdk.instrument() # lo encuentra -> ('langchain',) +``` + +```python Right, order-proof +import failproofai_sdk + +# Nombrarlo importa el adaptador bajo demanda, así que esto funciona desde cualquier lugar. +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. + + + + + +```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"] + 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 | + +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 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 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. + + +El daemon **envía** tus lotes. No los abre ni los reescribe. + +| Eventos | Escritos por | ¿Redactados por `collector.redact`? | +| --- | --- | --- | +| Transcripciones de sesión CLI | El daemon | Sí | +| Actividad de hooks | El daemon | Sí | +| **Todo lo que emite el SDK** | **Tu proceso** | **No** | + +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:** + + - 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. + + `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. + + + + **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. + +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 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 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 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. + + + + + +## Problemas comunes + + + + 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`. + + + + Se mide desde el evento de apertura correspondiente, por lo que se rechaza en `tool_result`, `hook_completed`, `agent_resume` y `human_input`. Se acepta en `model_response`, porque solo tú conoces la latencia real del proveedor, y debe ser un entero. + + + + 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. 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 rol o nombre de nodo y guarda el id real en un campo del payload. + + + +## Siguiente paso + + + + 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/integrations/langchain.mdx b/docs/es/start/integrations/langchain.mdx new file mode 100644 index 000000000..e58d93276 --- /dev/null +++ b/docs/es/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain y LangGraph" +sidebarTitle: "LangChain y LangGraph" +description: "Instrumenta grafos, nodos, herramientas, retrievers y llamadas a modelos con una sola llamada." +icon: "/images/frameworks/langchain.svg" +--- + +Un único adaptador sirve para ambos. LangGraph funciona sobre el gestor de callbacks de `langchain-core`, por lo que instrumentar uno instrumenta el otro. + +## Instalación + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Para LangChain sin LangGraph, usa `failproofai-sdk[langchain]`. + +Compatible con: `langchain-core` 1.4.7 a 2.0, `langgraph` 1.2 a 2.0. Fuera de ese rango, el adaptador se instala igualmente y emite una advertencia única. + +## Instrumentar + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` registra un tracer a través de `langchain_core.tracers.context.register_configure_hook`. LangChain lo inyecta en cada gestor de callbacks que construye, de modo que grafos, herramientas y modelos quedan capturados sin modificar ningún punto de llamada — incluidos los que están dentro de bibliotecas que no escribiste tú. + +## Qué se registra + +| LangChain o LangGraph | Evento Failproof | +| --- | --- | +| Ejecución raíz | `agent_start`, `agent_end` | +| Nodo de LangGraph | `hook_triggered`, `hook_completed` | +| Subgrafo compilado | `agent_start`, `agent_end` anidados | +| Ejecución de herramienta | `tool_use`, `tool_result` | +| Ejecución de retriever | `tool_use`, `tool_result`, salida resumida | +| Ejecución de chat model o LLM | `model_request`, `model_response`, con uso de tokens | +| Tokens en streaming | Agrupados en la respuesta como conteo de chunks y tiempo hasta el primer token. Los conteos de tokens requieren `ChatOpenAI(stream_usage=True)` — ver más abajo | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, correlacionados con el `Interrupt.id` — incluso cuando el resume ocurre en un proceso diferente contra el mismo checkpointer | +| Excepción no controlada | `error`, seguido de `agent_end` con resultado `failed` | + +**Un nodo se convierte en un hook, no en un agente anidado.** `agent_id` es la faceta principal en todas las vistas del dashboard — promover `retrieve`, `grade_documents` y `should_continue` a agentes lo saturaría y etiquetaría la sesión según el nodo que se ejecutara primero. + +Los spans de hook se renderizan igual y siguen ofreciendo una vista de latencia por nodo. + + + **Nombra tus nodos como quieras.** La ejecución de un nodo se identifica por su *forma* — una ejecución no hoja que lleva la etiqueta de paso propia de LangGraph — nunca por su nombre. + + +| Lo que escribes | Lo que se registra | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | La herramienta | +| `add_node("ChatOpenAI", ...)` | La llamada al modelo | + +Nombrar un nodo con el nombre de lo que ejecuta solía hacer desaparecer los eventos de ese elemento. Ya no lo hace. + +### Streaming + +`.stream()` y `.astream()` no emiten eventos por token. Se agrupan en el `model_response` de cierre: + +| Campo | Contiene | +| --- | --- | +| `fw_chunks` | Cuántos chunks llegaron | +| `fw_ttft_ms` | Tiempo hasta el primer token | + +### Conteos de tokens en una respuesta en streaming + +Es un asunto aparte y fácil de pasar por alto: OpenAI solo envía el uso en una respuesta en streaming **cuando se le solicita**. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # sin esto, no hay tokens +``` + +El adaptador registra lo que el framework le entrega. Sin ese parámetro no hay nada que registrar, y `model_response` llega sin conteos de tokens. + +## Ejemplo + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## Nombra tus spans + +Por defecto, el span raíz toma el nombre propio del grafo. Envuélvelo para obtener la etiqueta que elijas: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +Para configuraciones multi-agente, anida los contextos. Cada worker se convierte en un span hijo con `parent_id`: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +Mantén `agent_id` con baja cardinalidad. Usa un rol o nombre de nodo, nunca un UUID ni una cadena generada por ejecución. + +## Controla la sesión + +El id de sesión se resuelve en este orden, ganando el primer match: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. El contexto envolvente `failproofai_sdk.session()` +4. `metadata["session_id"]`, `metadata["conversation_id"]`, o `metadata["thread_id"]` +5. El id de la ejecución raíz + +Nunca se genera desde cero, porque un id sintetizado divide una ejecución en varias sesiones. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## Opciones + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # fija cada ejecución a un session id + include_chains=set(), # lista de permitidos de cadenas intermedias como pares de hooks + capture_content=True, # False elimina prompts y completions de los payloads + graph_callbacks=True, # interrupt y resume de primera clase, requiere langgraph 1.2+ +) +``` + +Usa `capture_content=False` para datos regulados. La estructura, tiempos, conteos de tokens, nombres de herramientas y resultados siguen registrándose; los cuerpos de los mensajes no. + +`include_chains` aplica **solo** a ejecuciones anidadas. Un runnable que invoques en el nivel superior es la raíz de la sesión, por lo que se convierte en el span del agente en lugar de un par de hooks, y nombrarlo aquí no tiene efecto. + +## Human in the loop + +`interrupt()` produce cuatro eventos, y ninguno de los dos pares es redundante: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +De `human_wait` a `human_input` se lleva el prompt y la respuesta (ambos se eliminan con `capture_content=False`, junto con las fuentes de documentos de recuperación — el conteo de documentos sobrevive). El par `agent_pause` a `agent_resume` es el único que registra el tiempo en pausa, por lo que sin él una espera humana de diez minutos se contabiliza como tiempo activo del agente. El span raíz permanece abierto durante el intervalo, manteniendo ambas llamadas en una sola sesión. + +## Problemas comunes + + + + `create_react_agent` propaga la excepción. Para permitir que el modelo vea el fallo y continúe, construye el nodo de herramientas explícitamente: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + El fallo se registra como un `tool_result` con error en cualquier caso. Esto solo decide si la ejecución sobrevive al error. + + + + Un `llm.invoke()` directo fuera de cualquier grafo no tiene ejecución padre, por lo que abre un span raíz y emite su par de modelo dentro de él. El dashboard asigna las hojas a un agente abierto, así que el span es intencional. Nómbralo: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + Pasaste un handler de Failproof en `config={"callbacks": [...]}` además de llamar a `instrument()`. Elimínalo. El configure hook ya cubre todos los gestores de callbacks del proceso. + + + + No es así. LangGraph lanza `GraphInterrupt` por el mismo camino que una excepción real, por lo que cada pausa llega al tracer como un callback de error. Sin embargo, cualquier subclase de `GraphBubbleUp` se trata como flujo de control, así que una aprobación no genera un error en rojo. + + + + Verifica en este orden: que `instrument()` se ejecutó antes del grafo; que hay un `with failproofai_sdk.session():` alrededor de la llamada; que `FAILPROOFAI_SDK_STRICT=1` está configurado, para que un hook degradado lance error en lugar de ser silenciado. + + + +## Siguientes pasos + + + + Pares, ids, ciclo de vida de sesión y entrega. + + + Sigue la causalidad a través de la sesión que acabas de capturar. + + + CrewAI, LlamaIndex, Pydantic AI y agentes personalizados. + + \ No newline at end of file diff --git a/docs/es/start/integrations/llamaindex.mdx b/docs/es/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..7928088d9 --- /dev/null +++ b/docs/es/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "Instrumenta workflows, steps, agentes de funciones y retrievers." +icon: "/images/frameworks/llamaindex.svg" +--- + +## Instalación + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +Compatible con: `llama-index-core` 0.14.23 a 0.15. La versión 0.14.23 es la release donde el stream del workflow comenzó a incluir los eventos de agente tipados que este adaptador lee. Por debajo de esa versión, los nombres de los modelos y la estructura del agente desaparecen. + +## Instrumentación + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +La API de agentes de LlamaIndex es asíncrona. Todos los scopes funcionan tanto con `async with` como con `with` y producen eventos idénticos. + +`instrument()` adjunta un manejador de eventos y un manejador de spans al dispatcher global de LlamaIndex. Juntos hacen visible el bucle del agente, no solo sus llamadas al modelo. + + + Sin un argumento adicional en tu LLM, cada contador de tokens en tu traza será nulo. Consulta [Conteo de tokens](#token-counts) a continuación. + + +## Conteo de tokens + +`FunctionAgent` llama a `astream_chat`, y `llama-index-llms-openai` no envía `stream_options={"include_usage": True}` al hacer streaming. Por tanto, el proveedor nunca envía el chunk de uso y no hay nada que ninguna instrumentación pueda leer. + +Este es un comportamiento upstream de LlamaIndex. Actívalo en tu LLM de forma explícita: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +Medido en la misma ejecución y modelo: + +| | Tokens de entrada | Tokens de salida | +| --- | --- | --- | +| Sin configurar | `null` | `null` | +| Con configuración | 148 | 17 | + +Las llamadas sin streaming (`llm.chat`, `llm.achat`) reportan el uso sin ninguna configuración. Solo la ruta de streaming, que es la ruta predeterminada del agente, necesita esto. + +## Qué se registra + +| LlamaIndex | Evento Failproof | +| --- | --- | +| Span raíz de `Workflow.run` | Session, `agent_start`, `agent_end` | +| Span anidado de `Workflow.run` | `agent_start`, `agent_end` anidados | +| Span de paso del workflow | `hook_triggered`, `hook_completed` | +| Inicio y fin del chat LLM | `model_request`, `model_response` | +| Span de `FunctionTool.call` | `tool_use`, `tool_result` | +| Inicio y fin de recuperación | `tool_use`, `tool_result`, salida resumida | +| Embeddings | Nada, a menos que `embeddings=True` | +| Una herramienta esperando a una persona | `human_wait`, `agent_pause`, luego `agent_resume`, `human_input` | +| Transferencia de `AgentWorkflow` | Un `agent_start`, `agent_end` anidado por agente, con el workflow como padre | +| Excepción | `error`, luego `agent_end` con resultado `failed`, y `agent_end.summary` nombrándola | +| `handler.cancel_run()` | `agent_end` con resultado `cancelled` y sin `error` — un botón de detención no es un fallo | + +`agent_id` es el `FunctionAgent.name` cuando se define uno, y el nombre de la clase del workflow en caso contrario. Dentro de un `AgentWorkflow`, cada agente que toma un turno obtiene su propio span anidado bajo el workflow, por lo que una transferencia aparece como dos agentes en lugar de uno. + +La salida de recuperación se resume en lugar de volcarse completa. Un retriever devuelve documentos, y almacenarlos en el payload introduciría tu corpus en el almacén de eventos una vez por consulta. En su lugar, se conservan el recuento, el rango de puntuaciones y fragmentos truncados. + +## Ejemplo + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +El bucle del agente aparece en la traza como pares de hooks: `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool` y `aggregate_tool_results`. Son el propio bucle del framework, por lo que se registran como hooks en lugar de agentes, lo que mantiene `agent_id` con un significado claro. + +## Nombra tus spans + +`agent_id` es el `FunctionAgent.name` cuando se define uno, y el nombre de la clase del workflow en caso contrario. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +En un `AgentWorkflow`, ese nombre es también el que se usa para registrar cada transferencia: + +```text +AgentWorkflow span padre +├─ city_analyst turno 1 +├─ cost_analyst turno 2 +└─ city_analyst turno 3 — un nuevo turno, no uno reabierto +``` + +Así, `agent_id` indica **qué agente** realizó el trabajo y `parent_id` indica **a qué workflow** pertenecía. Un agente que devuelve el control más adelante abre un segundo turno en lugar de reabrir el primero. + +Envuelve la ejecución para sobreescribirlo, o para agrupar varios agentes bajo un mismo padre: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +Mantén `agent_id` con baja cardinalidad. Es la faceta principal en todas las vistas del dashboard, así que usa un rol o nombre de workflow, nunca un UUID ni una cadena generada por ejecución. + +## Controla la sesión + +Este adaptador **no tiene opción `session_id`**. La sesión proviene del scope que la envuelve y, en caso contrario, se genera un `uuid4().hex` por cada ejecución del workflow: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## Opciones + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True registra las llamadas de embedding como pares de herramientas + steps=True, # False elimina los pares de hooks de pasos del workflow + capture_messages=True, # False elimina TODOS los payloads: prompts, completions, + # argumentos y salida de herramientas, E/S de pasos, consultas + # de recuperación, el objetivo y la respuesta final + capture_limit=8192, # caracteres conservados por valor capturado + stale_after=600.0, # segundos antes de forzar el cierre de una HOJA abandonada + reaper_interval=30.0, # frecuencia de barrido del reaper; 0 lo desactiva +) +``` + +| Opción | Cuándo cambiarla | +| --- | --- | +| `embeddings` | Actívala solo cuando depures latencia o coste de embeddings. Una indexación masiva genera miles de llamadas y enterrará la línea de tiempo. | +| `steps` | Desactívala si solo quieres eventos de modelo y herramientas y el bucle del agente resulta ruidoso. | +| `capture_messages` | Desactívala para datos regulados. Deja de registrarse cualquier payload — prompts, la completación del modelo, argumentos y valores de retorno de herramientas, entrada y salida de pasos del workflow, consultas de recuperación, el objetivo del agente y su respuesta final. La estructura, los tiempos, los tokens y los resultados siguen registrándose. | +| `capture_limit` | Caracteres conservados por valor capturado antes del truncamiento. Auméntalo cuando un prompt RAG o un contexto recuperado llegue recortado. | +| `stale_after` | Segundos antes de forzar el cierre de una **hoja** abandonada — una respuesta en streaming que nadie consumió, un span de modelo o herramienta cuyo cierre nunca llegó — para que la sesión se resuelva en lugar de leerse como `ongoing` indefinidamente. **No** cierra una ejecución abandonada en sí: un workflow cuya tarea se cancela sin que el dispatcher vea una salida mantiene su `agent_start` abierto hasta `uninstrument()`. | +| `reaper_interval` | Frecuencia de barrido. Ponlo a `0` para desactivar el reaper por completo. | + +## Humano en el bucle + +Se captura cuando la espera ocurre dentro de una herramienta: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +`ctx.wait_for_event` en un paso de workflow normal no se captura. El runtime intercepta la interrupción antes de que llegue al dispatcher, por lo que el paso termina y se vuelve a ejecutar más tarde sin ninguna señal con la que identificar una pausa. El patrón FunctionAgent, que LlamaIndex documenta, espera dentro de una herramienta y se captura completamente. + +## Problemas comunes + + + + Añade `additional_kwargs={"stream_options": {"include_usage": True}}` a tu LLM. Consulta [Conteo de tokens](#token-counts). + + + + LlamaIndex no tiene un campo de uso estándar. El adaptador prueba varias formas conocidas, y una integración que nombre sus contadores de forma diferente no coincidirá con ninguna de ellas. + + El dict sin procesar siempre se envía, así que revisa `usage` en el payload para ver cómo los denominó tu proveedor. + + Un `usage` disponible junto a columnas de tokens vacías es intencionado — es preferible a mostrar un número incorrecto con confianza. + + + + Ese es el bucle de FunctionAgent, un conjunto por iteración. Filtra por nombre de hook en el dashboard. Estos tiempos de paso suelen ser la razón principal para usar este adaptador en lugar de uno solo de modelo. + + + + Comprueba en este orden: que `instrument()` se ejecutó antes de la ejecución; que hay un `async with failproofai_sdk.session():` alrededor del `await`; que `llama-index-core` es 0.14.23 o más reciente; que `FAILPROOFAI_SDK_STRICT=1` está definido, para que un hook degradado lance una excepción en lugar de ser silenciado. + + + +## A continuación + + + + 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, Pydantic AI y agentes personalizados. + + \ No newline at end of file diff --git a/docs/es/start/integrations/pydantic-ai.mdx b/docs/es/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..9456522de --- /dev/null +++ b/docs/es/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "Instrumenta agentes tipados, herramientas, llamadas a modelos y reintentos." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## Instalación + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +Compatible con: `pydantic-ai-slim` 2.0 a 3.0. La versión 2.0 eliminó `Agent(instrument=...)` e introdujo el protocolo de capacidades en el que se basa este adaptador, por lo que la versión 1.x no puede instrumentarse de esta manera. + +## Instrumentar + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` debe ejecutarse antes de construir un `Agent`. La capacidad se agrega en el momento de la construcción, por lo que un agente creado antes no tendrá ninguna y no registrará nada, sin producir ningún error. Esta es la causa más común de una traza vacía con este adaptador. + + +Los agentes de alcance de módulo son donde esto puede causar problemas: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # constructed at import time + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # run this FIRST +import agents # now the agent gets the capability +``` + +Verifica que se aplicó correctamente: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI combina la lista que proporcionas en un único `root_capability`, por lo que no existe un atributo `agent.capabilities` que puedas leer directamente. + +Los agentes construidos mientras está activa la instrumentación conservan la capacidad, así que puedes ejecutar `uninstrument()` y volver a instrumentar sin necesidad de reconstruirlos. + +## Qué se registra + +| Pydantic AI | Evento de Failproof | +| --- | --- | +| Ejecución de agente | `agent_start`, `agent_end` | +| Solicitud al modelo | `model_request`, `model_response`, con uso de tokens | +| Llamada a herramienta | `tool_use`, `tool_result`, con los argumentos enviados por el modelo | +| `ModelRetry` desde una herramienta | `tool_result` con un error | +| Excepción no controlada | `error`, luego `agent_end` con resultado `failed` | + +No hay par de hooks ni par de intervención humana. Pydantic AI no tiene un límite de nodo o paso que delimitar ni una pausa humana integrada, por lo que no hay nada que mapear. Si construyes alguno de estos, emite los eventos manualmente — consulta [Agentes personalizados](/es/reference/custom-agents). + +El `output_type` no afecta la traza. Una ejecución tipada y una ejecución de cadena producen los mismos eventos. + +## Ejemplo + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +En la traza, `restock_eta` aparece como un `tool_result` con un error, seguido de otra llamada al modelo donde el agente lo resuelve, y la ejecución termina igualmente con `success`. Ambos hechos quedan registrados. + +## Errores, reintentos y flujo de control + +Pydantic AI lanza excepciones por tres motivos diferentes, y el adaptador los distingue: + +| Excepción | Tratada como | Resultado | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | Un fallo real de herramienta | `tool_result` con un error; la ejecución aún puede terminar con `success` | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | Flujo de control | No es un error; la ejecución está siendo dirigida | +| Cualquier otra cosa | Un fallo | `error`, luego `agent_end` con resultado `failed` | + +`ModelRetry` pertenece deliberadamente al primer grupo. Significa que un intento falló genuinamente y se pidió al modelo que lo intentara de nuevo, que es exactamente para lo que sirve el campo de error de un span de herramienta. Clasificarlo como flujo de control ocultaría fallos reales de herramientas detrás de una ejecución exitosa. + +## Nombra tus spans + +El span de ejecución propio de Pydantic AI se llama `agent`. Envuelve la llamada para asignarle una etiqueta personalizada: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +El span del framework queda entonces anidado bajo `inventory`, y ahí es donde se ubican los eventos del modelo y las herramientas. + +Mantén `agent_id` con baja cardinalidad. Es la faceta principal en todas las vistas del panel, así que usa un nombre de rol, nunca un UUID ni una cadena por ejecución. + +## Controla la sesión + +Se resuelve en este orden, ganando la primera coincidencia: + +1. `instrument("pydantic_ai", session_id=...)` +2. El alcance del `failproofai_sdk.session()` envolvente +3. El `conversation_id` de la ejecución, luego su `run_id` +4. Un `uuid4().hex` generado automáticamente + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## Opciones + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # pin every run to one session id + capture_content=True, # False drops prompts and completions from payloads +) +``` + +## Problemas comunes + + + + El `Agent` fue construido antes de que se ejecutara `instrument()`. Consulta la advertencia anterior y verifica `agent.root_capability.capabilities`. + + + + Un `raise` sin más se propaga; así está diseñado Pydantic AI. Para que el modelo pueda resolverlo, lanza `ModelRetry` con un mensaje que pueda procesar. El fallo queda registrado en cualquier caso. + + + + Ese hijo es el span de ejecución propio de Pydantic AI, y es donde se ubican los eventos del modelo y las herramientas. Elimina tu propio alcance si quieres un único span, a cambio de perder el nombre personalizado. + + + + La pila del grafo asíncrono de Pydantic AI es más larga que el límite del campo de payload, y la última línea de un traceback es la excepción en sí. Este campo se recorta desde el principio en lugar del final, por lo que la línea que necesitas se conserva. + + + +## Siguiente + + + + Pares, identificadores, 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 agentes personalizados. + + \ No newline at end of file diff --git a/docs/es/start/quickstart.mdx b/docs/es/start/quickstart.mdx index 194b72d8a..9c330db2e 100644 --- a/docs/es/start/quickstart.mdx +++ b/docs/es/start/quickstart.mdx @@ -1,35 +1,35 @@ --- title: "Inicio rápido" -description: "Captura una sesión de agente, encuentra un fallo y empieza a prevenirlo." +description: "Captura una sesión de agente, detecta un fallo y empieza a prevenirlo." icon: "zap" --- -Este inicio rápido te permite tener una máquina reportando sesiones, ejecutar una auditoría e implementar una política. Usa el skill para configurar Failproof, o sigue los pasos manuales. +Este inicio rápido configura una máquina para que reporte sesiones, ejecuta una auditoría y despliega una política. Usa la skill para configurar Failproof o sigue los pasos manuales. -**¿Cuál es tu camino?** Si tu agente se ejecuta en uno de los 12 [harnesses](/es/reference/harnesses) compatibles — una CLI de codificación, o un gateway como Hermes o OpenClaw — sigue los pasos a continuación; necesitas Node.js 20.9 o posterior. Si tu agente no tiene harness, instrumétalo 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 ese camino requiere un hook en tu runtime. +**¿Cuál es tu camino?** Si tu agente se ejecuta en uno de los 12 [harnesses](/es/reference/harnesses) compatibles — una CLI de codificación, o una gateway como Hermes u OpenClaw — sigue los pasos a continuación; necesitas Node.js 20.9 o posterior. Si tu agente no tiene harness, instrumértalo con el [SDK de Python](/es/reference/custom-agents) para trazado y auditorías, y luego continúa en [Ejecuta tu primera verificación de fallos](/es/start/first-audit); el control de acceso en esa ruta requiere un hook en tu 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. ``` - Tu agente inspecciona el proyecto, elige la integración relevante, 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. + Tu agente inspecciona el proyecto, elige la integración correspondiente, 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. ## Antes de empezar -1. Abre el [dashboard de Failproof AI](https://app.befailproof.ai) y crea una cuenta o inicia sesión con tu correo de trabajo. -2. Ve a **Administración → Claves** y crea una clave con `events:add` y `policies:pull`. +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: ```bash @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Las transcripciones de sesión se envían de forma predeterminada. Agrega `--no-transcripts` para reportar la actividad de hooks y las decisiones de políticas sin el contenido de la transcripción. + Las transcripciones de sesiones se envían por defecto. Añade `--no-transcripts` para reportar la actividad de hooks y las decisiones de políticas sin el contenido de la transcripción. - Si esta máquina ya tiene historial de agente, previsualiza e importa los últimos siete días, luego espera a que la entrega finalice. Omite este paso en una máquina nueva. + 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. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Abre **Sesiones** en Failproof AI y selecciona una sesión importada. + Abre **Sessions** en Failproof AI y selecciona una sesión importada. - Esto conecta Failproof AI a tu harness e instala las 40 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. + Esto conecta Failproof AI a tu harness e instala las 40 políticas integradas. Úsalas para ver las decisiones de políticas locales y probar el control de acceso antes de que Failproof AI audite tus sesiones y escriba políticas para tus agentes. - Deja que el instalador detecte tu harness, o especifica uno explícitamente. Cada uno de los 12 es un valor válido para `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Deja que el instalador detecte tu harness, o indícalo 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`. ```bash failproofai policies --install --cli claude --scope user # una CLI de codificación - failproofai policies --install --cli hermes --scope user # un gateway de Slack/Telegram + failproofai policies --install --cli hermes --scope user # una gateway de Slack/Telegram ``` - El bloqueo de una llamada a herramienta antes de que se ejecute está verificado en los 12. Las verificaciones 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 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 control de acceso](/es/reference/harnesses#enforcement-capability) para ver la matriz por harness. - Sigue [Ejecuta tu primera verificació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 [Ejecuta tu primera verificació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). Empieza en modo observación, inspecciona las coincidencias y luego aplica la versión revisada. + Sigue [Previene tu primer fallo con una política](/es/start/first-policy). Empieza en modo de observación, inspecciona las coincidencias y luego aplica la versión revisada. - Ejecuta `failproofai config --status`. Una configuración saludable reporta la conexión en la nube, el estado del daemon y si la aplicación de políticas está pausada. + Ejecuta `failproofai config --status`. Una configuración correcta reporta la conexión en la nube, el estado del daemon y si el control de acceso está pausado. \ No newline at end of file diff --git a/docs/es/start/quickstarts/crewai.mdx b/docs/es/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..67361d731 --- /dev/null +++ b/docs/es/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "Instala, instrumenta y ve tu primera traza." +icon: "/images/frameworks/crewai.svg" +--- + +Tres pasos para tu primera traza de CrewAI. Para conocer qué incluye cada evento, los flujos y la solución de problemas, consulta [la guía completa](/es/start/integrations/crewai). + +## Instalar + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## Instrumentar + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +Tu crew, agentes, tareas y herramientas no cambian en absoluto. `instrument()` se suscribe al bus de eventos a nivel de módulo de CrewAI. + +## Verificar que llegó + +Ejecútalo una vez, luego abre **Observe → Sessions** y selecciona tu entorno. Tu ejecución aparece como una traza reconstruida. + +Si no llega nada, confirma que la máquina está conectada con `failproofai config --status`. + + + Qué se registra, flujos, uso de tokens, nomenclatura de spans, opciones y problemas frecuentes. + \ No newline at end of file diff --git a/docs/es/start/quickstarts/custom-agents.mdx b/docs/es/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..8e6d3b6e4 --- /dev/null +++ b/docs/es/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "Agentes personalizados" +description: "Envuelve tu agente en tres bloques `with` y comenzará a registrar." +icon: "code" +--- + +Para un agente que escribiste tú mismo, o un framework para el que Failproof AI no tiene adaptador. + +Envuelves el trabajo que ya realizas en bloques `with`. Cada uno registra cuándo comenzó, cuándo terminó y cuánto tardó — no necesitas llamar a nada más. + +## Instalación + +```bash +pip install failproofai-sdk +``` + +Sin extras ni dependencias. + +## Instrumentación + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # una ejecución + with failproofai_sdk.agent("planner"): # una unidad de trabajo + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) # una llamada a herramienta +``` + +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á realizando trabajo — dale un nombre que reconocerías en una lista | +| `tool_call()` | Esta es una herramienta, y esto es lo que devolvió | + +Anída los bloques como anidas tu código. Nunca tienes que pasar ids entre ellos: cada bloque recuerda en qué contexto está, de modo que todo lo que registres recoge automáticamente la ejecución correcta y el agente correcto. `async with` funciona exactamente igual. + +## Comprueba que llegó + +Ejecútalo una vez, luego abre **Observe → Sessions** y selecciona tu entorno. Tu ejecución aparecerá como una traza reconstruida. + +Si no llega nada, confirma que la máquina está conectada con `failproofai config --status`. + + + Todos los métodos de eventos, qué ocurre cuando tu código lanza una excepción, un ejemplo práctico, hilos y async, e instrumentación de un framework sin adaptador. + \ No newline at end of file diff --git a/docs/es/start/quickstarts/langchain.mdx b/docs/es/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..15410641f --- /dev/null +++ b/docs/es/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain y LangGraph" +description: "Instala, instrumenta y visualiza tu primera traza." +icon: "/images/frameworks/langchain.svg" +--- + +Tres pasos para tu primera traza con LangChain o LangGraph. Para streaming, human-in-the-loop, nomenclatura de spans y otras opciones, consulta [la guía completa](/es/start/integrations/langchain). + +## Instalar + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Para LangChain sin LangGraph, usa `failproofai-sdk[langchain]`. + +## Instrumentar + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +Sin cambios en los puntos de llamada. `instrument()` registra un tracer que LangChain inyecta en cada gestor de callbacks que construye, de modo que grafos, herramientas y modelos quedan capturados — incluidos los que se encuentran dentro de bibliotecas que no escribiste tú. + +## Verificar que llegó + +Ejecútalo una vez, luego abre **Observe → Sessions** y selecciona tu entorno. Tu ejecución aparecerá como una traza reconstruida. + +Si no llega nada, confirma que la máquina está conectada con `failproofai config --status`. + + + Qué se registra, streaming, conteo de tokens, nomenclatura de spans, control de sesiones, opciones y human in the loop. + \ No newline at end of file diff --git a/docs/es/start/quickstarts/llamaindex.mdx b/docs/es/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..92ad54c9e --- /dev/null +++ b/docs/es/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "Instala, instrumenta y visualiza tu primera traza." +icon: "/images/frameworks/llamaindex.svg" +--- + +Tres pasos para obtener tu primera traza con LlamaIndex. Para ver los pasos de flujo de trabajo, recuperación, el reaper y las opciones disponibles, consulta [la guía completa](/es/start/integrations/llamaindex). + +## Instalación + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## Instrumentación + +La API de agentes de LlamaIndex es asíncrona. Todos los ámbitos funcionan tanto con `async with` como con `with`. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + Sin un argumento adicional en tu LLM, cada conteo de tokens en tu traza será nulo — `llama-index-llms-openai` no solicita el uso cuando transmite en streaming. Consulta [Conteo de tokens](/es/start/integrations/llamaindex#token-counts). + + +## Verifica que llegó + +Ejecútalo una vez, luego abre **Observe → Sessions** y selecciona tu entorno. Tu ejecución aparecerá como una traza reconstruida. + +Si no llega nada, confirma que la máquina está conectada con `failproofai config --status`. + + + Conteo de tokens, qué se registra, pasos de flujo de trabajo, recuperación, opciones y problemas comunes. + \ No newline at end of file diff --git a/docs/es/start/quickstarts/pydantic-ai.mdx b/docs/es/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..22a0b7563 --- /dev/null +++ b/docs/es/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "Instala, instrumenta y visualiza tu primer trace." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +Tres pasos para obtener tu primer trace con Pydantic AI. Para herramientas, reintentos, streaming y opciones, consulta [la guía completa](/es/start/integrations/pydantic-ai). + +## Instalación + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## Instrumentación + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` debe ejecutarse **antes** de construir un `Agent`. La capacidad de instrumentación se añade en el momento de la construcción, por lo que un agente creado previamente no registrará nada — sin ningún error, porque técnicamente no ocurrió nada incorrecto. Esta es la causa más frecuente de un trace vacío con este adaptador, y los agentes definidos en el ámbito del módulo son donde más duele: importa `failproofai_sdk` y llama a `instrument()` antes de importar el módulo que los construye. + + +## Verifica que llegó + +Ejecútalo una vez y luego abre **Observe → Sessions** y selecciona tu entorno. Tu ejecución aparecerá como un trace reconstruido. + +Si no llega nada, confirma que la máquina está conectada con `failproofai config --status`. + + + Qué se registra, herramientas y reintentos, streaming, nomenclatura de spans, opciones y problemas comunes. + \ No newline at end of file diff --git a/docs/fr/index.mdx b/docs/fr/index.mdx index 6deaaacbb..79a501c38 100644 --- a/docs/fr/index.mdx +++ b/docs/fr/index.mdx @@ -1,41 +1,41 @@ --- title: "Rendez votre agent infaillible" -description: "Observabilité et mise en application pour chaque environnement d'exécution de vos agents — CLI de codage, passerelles de chat, assistants auto-hébergés et vos propres agents instrumentés." +description: "Observabilité et application des règles pour chaque environnement d'exécution de vos agents — CLIs de codage, passerelles de chat, assistants auto-hébergés et vos propres agents instrumentés." icon: "shield-check" --- -Failproof AI aide les équipes à comprendre ce que les agents ont fait, à identifier là où ils ont échoué, et à déployer des garde-fous avant que le même comportement ne se reproduise. +Failproof AI aide les équipes à comprendre ce que les agents ont fait, à identifier où ils ont échoué et à déployer des garde-fous avant que le même comportement ne se reproduise. -Un **harness** est l'environnement dans lequel votre agent s'exécute réellement. Failproof AI s'intègre à 12 d'entre eux — des CLI de codage comme Claude Code et Codex, des passerelles de chat comme Hermes, des assistants auto-hébergés comme OpenClaw — et les mêmes événements, les mêmes politiques et le même historique de session s'appliquent à chacun. Les agents sans harness remontent leurs données via le [SDK Python](/fr/reference/custom-agents), qui les trace et les audite ; l'application d'une politique dans ce cas nécessite un hook dans votre propre environnement d'exécution. +Un **harness** est l'environnement dans lequel votre agent s'exécute réellement. Failproof AI s'intègre à 12 d'entre eux — des CLIs de codage comme Claude Code et Codex, des passerelles de chat comme Hermes, des assistants auto-hébergés comme OpenClaw — et les mêmes événements, les mêmes politiques et le même historique de session s'appliquent à chacun. Les agents sans harness remontent leurs données via le [SDK Python](/fr/reference/custom-agents), qui les trace et les audite ; l'application d'une politique dans ce cas nécessite un hook dans votre propre runtime. - Utilisez la compétence pour instrumenter votre projet, le connecter et vérifier que les logs d'agents arrivent bien. + Utilisez le skill pour instrumenter votre projet, le connecter et vérifier que les logs de l'agent arrivent bien. - Analysez, interrogez, créez des tableaux de bord et lancez des audits en langage naturel sur vos logs d'agents. + Analysez, interrogez, créez des tableaux de bord et lancez des audits en langage naturel sur vos logs d'agent. - - Suivez les appels de modèle, les outils, les erreurs, les saisies humaines, la latence et les décisions de politique au sein d'une même session. + + Suivez les appels de modèle, les outils, les erreurs, les entrées humaines, la latence et les décisions de politique dans une seule session. - + Auditez un ensemble défini de sessions, examinez les conclusions étayées par des preuves et suivez la remédiation sous forme de tickets. - Transformez un mode d'échec connu en politique, observez son impact et déployez-la sur l'ensemble de votre flotte. + Transformez un mode de défaillance connu en politique, observez son impact et déployez-la sur l'ensemble de votre flotte. > **Session → Audit → Constat → Ticket → Politique**
-> Tracez ce qui s'est passé, identifiez l'échec, gérez la réponse, puis évitez que le même comportement ne se reproduise lors des prochaines exécutions. +> Tracez ce qui s'est passé, identifiez la défaillance, gérez la réponse, puis empêchez le même comportement lors des prochaines exécutions. ## Par où commencer -Si vous déployez votre premier agent instrumenté, commencez par le [démarrage rapide](/fr/start/quickstart). Si des données arrivent déjà, ouvrez [Sessions](/fr/sessions/overview) et inspectez une exécution réelle avant de configurer des audits ou des politiques. +Si vous déployez votre premier agent instrumenté, commencez par le [démarrage rapide](/fr/start/quickstart). Si des données arrivent déjà, ouvrez [Sessions](/fr/sessions/overview) et inspectez une vraie exécution avant de configurer des audits ou des politiques. - - Parcourez le flux de travail de bout en bout, de la capture à une politique déployée en toute sécurité. + + Parcourez le workflow de bout en bout, de la capture jusqu'au déploiement sécurisé d'une politique. \ No newline at end of file diff --git a/docs/fr/policies/deploy.mdx b/docs/fr/policies/deploy.mdx index b9bc4109c..f6626c610 100644 --- a/docs/fr/policies/deploy.mdx +++ b/docs/fr/policies/deploy.mdx @@ -4,27 +4,31 @@ description: "Déployez une version de politique révisée sur les machines cibl icon: "cloud-upload" --- -Un déploiement associe une ou plusieurs versions de politique à un ensemble de machines enrollées cibles. +Un déploiement associe une ou plusieurs versions de politique à un ensemble de machines enrôlées cibles. ## Appliquer un déploiement - 1. Allez dans **Admin → enforcement**, trouvez la machine et développez sa ligne. - 2. Sélectionnez **edit**, ajoutez la version de politique révisée, puis choisissez l'effet **observe** ou un effet d'application. - 3. Appliquez le changement, puis attendez le prochain check-in de la machine et confirmez son état de déploiement et de couverture. - 4. Allez dans **Observe → policy** pour inspecter les décisions en temps réel. + 1. Accédez à **Admin → application**, trouvez la machine et développez sa ligne. + 2. Sélectionnez **modifier**, ajoutez la version de politique révisée, puis choisissez l'effet **observer** ou un effet d'application. + 3. Appliquez la modification, attendez le prochain enregistrement de la machine et confirmez son état de déploiement et de couverture. + 4. Accédez à **Observer → politique** pour inspecter les décisions en temps réel. - ![L'éditeur de déploiement de machine avec les versions de politique, les effets enforce et observe, et l'action d'application du déploiement.](/images/dashboard/enforcement-editor.png) + ![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) - Les points de terminaison de déploiement Cloud ne sont intentionnellement pas exposés en tant que commandes `fp` ordinaires. Vérifiez la machine localement, puis déployez via le tableau de bord : + Déployez depuis la CLI avec `fp fleet`. Vérifiez l'ensemble résultant avant de l'appliquer — `deploy` affiche le plan complet et demande une confirmation **uniquement sur un terminal interactif sans `--json`**. Avec `--json`, `--yes`, ou avec stdin redirigé (une étape CI, un script, un agent exécutant un shell), l'application est immédiate, sans plan ni invite — exécutez donc `fp fleet show ` au préalable si vous souhaitez réviser : ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - Utilisez `fp sessions --env production --since 24h` et `fp events --event-type hook_completed` après le déploiement pour vérifier que l'activité remonte bien vers Cloud. + `fp fleet diff ` affiche l'écart entre l'intention et la livraison (une machine apparaît comme `behind` jusqu'à son prochain polling), `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 depuis désactivée ou supprimée. + + Vérifiez la machine elle-même avec `failproofai config --status`, et utilisez `fp sessions --env production --since 24h` ainsi que `fp events --event-type hook_completed` après le déploiement pour confirmer que l'activité remonte bien vers Cloud. @@ -33,15 +37,15 @@ Un déploiement associe une ou plusieurs versions de politique à un ensemble de Déployez une version révisée, et non un brouillon modifiable, en commençant par une machine hors production ou un petit groupe dont vous pouvez inspecter les sessions. - Examinez les correspondances, les raisons, les outils concernés et les faux positifs sans bloquer le travail. + Examinez les correspondances, les motifs, les outils concernés et les faux positifs sans bloquer le travail. - Promouvez après que les correspondances observées distinguent les actions non sécurisées des actions valides, puis confirmez que chaque machine ciblée a bien récupéré le déploiement et rapporte les décisions. + Passez en mode application une fois que les correspondances observées permettent de distinguer les actions non sécurisées des actions valides, puis confirmez que chaque machine cible a bien récupéré le déploiement et signale ses décisions. -Les machines nécessitent 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. +Les machines ont besoin 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. - La gestion de l'application est un workflow Cloud administratif. Ne traitez pas les routes d'application réservées au root comme des points de terminaison API `/v1` ordinaires. + 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 endpoints 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 b17575327..644a8ec7c 100644 --- a/docs/fr/policies/editor.mdx +++ b/docs/fr/policies/editor.mdx @@ -4,44 +4,46 @@ description: "Créez et révisez des politiques versionnées à partir d'un mode icon: "file-pen-line" --- -Utilisez l'éditeur de politiques pour transformer un constat ou un problème en règle déployable. Séparez la création du déploiement afin qu'un brouillon ne puisse pas modifier silencieusement le comportement en production. +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. -Lorsqu'un problème présente un schéma d'action répétable, ouvrez-le dans **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 examinée et le contexte du constat dans l'éditeur. Le source généré reste un brouillon jusqu'à sa publication. +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. ## Publier une version de politique - 1. Accédez à **Admin → policy editor** et, dans **compose**, décrivez le mode de défaillance ou collez le source de politique JavaScript. - 2. Validez le source et corrigez chaque erreur signalée. + 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 automatisé. + 4. Sélectionnez **enforcement** lorsque la version est prête pour un déploiement sur les machines. - ![La vue de composition de l'éditeur de politiques avec l'identité de la politique, la rédaction assistée par IA, la validation du source et les contrôles de publication.](/images/dashboard/policy-editor.png) + ![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) - Le CLI Cloud ne publie pas les versions de politiques. Validez le source localement avant de le copier dans l'éditeur : + 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 : ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - Publiez la version examinée depuis **Admin → policy editor**. + 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`. -## Liste de vérification pour la création +## Liste de contrôle pour la rédaction -1. Nommez le mode de défaillance en termes opérationnels. +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 possible qui correspond au comportement non sécurisé. -4. Retournez une raison indiquant à l'agent ou à l'opérateur la marche à suivre. +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 revue. +6. Enregistrez une nouvelle version et demandez une révision. -Utilisez `instruct` lorsque l'agent peut corriger son comportement en toute sécurité. Utilisez `deny` lorsque l'autorisation de l'action créerait un risque inacceptable ou irréversible. +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. - Les versions de politiques 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. + 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 diff --git a/docs/fr/reference/cloud-cli.mdx b/docs/fr/reference/cloud-cli.mdx index ab7a4e633..3fa9aa304 100644 --- a/docs/fr/reference/cloud-cli.mdx +++ b/docs/fr/reference/cloud-cli.mdx @@ -4,9 +4,9 @@ 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 et gérer les audits, les résultats, les incidents, les alertes, les clés, les utilisateurs, les requêtes et les 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 en flotte, décisions de garde-fous), et gérer 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 version publiée du Cloud CLI en tant qu'outil isolé : +Installez le Cloud CLI publié en tant qu'outil isolé : ```bash uv tool install fp-cloud-cli @@ -26,13 +26,13 @@ fp whoami fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` -Les options globales doivent être placées avant la commande : +Les options globales doivent précéder la commande : ```bash fp --json sessions --since 24h ``` -Exécutez `fp COMMAND --help` ou `fp COMMAND SUBCOMMAND --help` pour obtenir l'aide dans le terminal. +Exécutez `fp COMMAND --help` ou `fp COMMAND SUBCOMMAND --help` pour l'aide dans le terminal. ## Commandes CLI @@ -41,7 +41,7 @@ Exécutez `fp COMMAND --help` ou `fp COMMAND SUBCOMMAND --help` pour obtenir l'a | Commande | Objectif | Options | | --- | --- | --- | | `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 logout` | Révoquer et supprimer la session utilisateur sauvegardée. | — | | `fp whoami` | Afficher l'identité actuelle, le mode d'authentification, l'organisation et les permissions. | — | | `fp version` | Afficher la version du CLI installée. | — | | `fp help` | Afficher l'aide des commandes de premier niveau. | — | @@ -57,30 +57,34 @@ fp whoami fp events [OPTIONS] ``` -Liste les événements individuels des agents. Le flux léger par défaut exclut les charges utiles brutes ; n'utilisez `--full` que pour une investigation délimitée. +Liste les événements individuels des agents. Le flux léger par défaut exclut les charges utiles brutes ; utilisez `--full` uniquement pour une investigation délimitée. | Option | Description | | --- | --- | -| `--limit`, `-n ` | Nombre total maximum de lignes. Par 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 ISO 8601 UTC ; remplace `--since`. | +| `--from ` / `--to ` | Plage UTC ISO 8601 ; remplace `--since`. | | `--env ` | Filtre d'environnement ; répétable ou séparé par des virgules. | | `--event-type ` | Filtre de type d'événement ; répétable ou séparé par des virgules. | | `--agent-id ` | Filtre d'agent ; répétable ou séparé par des virgules. | | `--session-id ` | Filtre de session ; répétable ou séparé par des virgules. | -| `--search ` | Recherche dans le texte des charges utiles ; répétable, avec correspondance sur n'importe quel terme. | -| `--order asc\|desc` | Ordre chronologique. Par défaut : plus récent en premier. | +| `--search ` | Recherche dans le texte de la charge utile ; répétable, avec 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 depuis un curseur opaque. | | `--page-size ` | Lignes par requête avec `--all` ; maximum `200`. | -| `--full` | Inclure les charges utiles brutes via le point de terminaison d'événements plus lourd. | +| `--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. | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +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. 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 ```text @@ -89,19 +93,19 @@ fp sessions [OPTIONS] | Option | Description | | --- | --- | -| `--limit`, `-n ` | Nombre total maximum de lignes. Par 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 ISO 8601 UTC ; remplace `--since`. | +| `--from ` / `--to ` | Plage UTC ISO 8601 ; remplace `--since`. | | `--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 ` | Faire correspondre les sessions impliquant l'un des agents sélectionnés. | +| `--agent-id ` | Correspond aux sessions impliquant l'agent sélectionné. | | `--session-id ` | Filtre de session ; répétable ou séparé par des virgules. | | `--all` | Pagination automatique jusqu'à `--limit`. | | `--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. | +| `--full-ids` | Ne pas abréger les identifiants de session dans la sortie terminal. | +| `--agents` | Développer le registre des agents pour les sessions multi-agents. | ### Évaluations @@ -111,11 +115,11 @@ fp evals [OPTIONS] | Option | Description | | --- | --- | -| `--aggregate` | Afficher les totaux et les statistiques par score au lieu des évaluations individuelles. | +| `--aggregate` | Afficher les totaux et les statistiques par score plutôt que les évaluations individuelles. | | `--limit`, `-n ` | Nombre maximum de lignes dans la liste. Par défaut : `50`. | -| `--since`, `--from`, `--to` | Sélectionner la plage de temps. | +| `--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 scores ; 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. | @@ -131,9 +135,9 @@ fp errors [OPTIONS] | --- | --- | | `--aggregate` | Résumer les erreurs correspondantes au lieu de lister les lignes. | | `--limit`, `-n ` | Nombre maximum de lignes dans la liste. Par défaut : `50`. | -| `--since`, `--from`, `--to` | Sélectionner la plage de temps. | +| `--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 des charges utiles ; répétable. | +| `--search ` | Rechercher dans le texte de la charge utile ; répétable. | | `--order asc\|desc` | Ordre chronologique. | | `--all`, `--cursor`, `--page-size` | Contrôler la pagination de la liste. | | `--fields ` | Retourner uniquement les champs sélectionnés. | @@ -143,14 +147,14 @@ fp errors [OPTIONS] | Commande | Objectif | | --- | --- | -| `fp usage` | Afficher l'utilisation pour la fenêtre de mesure actuelle. | +| `fp usage` | Afficher l'utilisation pour la fenêtre de mesure en cours. | | `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. | -| `fp list score_filters` | Lister les clés de scores d'évaluation. | -| `fp list models` | Lister les noms des modèles. | -| `fp list hooks` | Lister les noms des hooks. | -| `fp list tools` | Lister les noms des outils. | +| `fp list score_filters` | Lister les clés de score d'évaluation. | +| `fp list models` | Lister les noms de modèles. | +| `fp list hooks` | Lister les noms de hooks. | +| `fp list tools` | Lister les noms d'outils. | | `fp list error_types` | Lister les types d'erreurs. | ### Organisations @@ -158,7 +162,7 @@ fp errors [OPTIONS] | Commande | Objectif | | --- | --- | | `fp orgs list` | Lister les organisations accessibles. | -| `fp orgs switch [SLUG]` | Enregistrer une organisation active ; invite à en choisir une si omise. | +| `fp orgs switch [SLUG]` | Enregistrer une organisation active ; invite à la saisir si omise. | | `fp orgs current` | Afficher l'organisation active. | | `fp orgs perms` | Afficher vos permissions dans l'organisation active. | @@ -179,12 +183,12 @@ Les jetons de permission utilisent le format `resource:action`, par exemple `eve | Commande | Objectif | Options | | --- | --- | --- | -| `fp query list` | Lister les requêtes enregistrées. | `--show-id` ; `--fields ` | +| `fp query list` | Lister les requêtes sauvegardées. | `--show-id` ; `--fields ` | | `fp query show NAME` | Afficher une requête. | — | -| `fp query create NAME` | Enregistrer une requête. | `--sql ` ; `--description` | +| `fp query create NAME` | Sauvegarder une requête. | `--sql ` ; `--description` | | `fp query update NAME` | Mettre à jour ou renommer une requête. | `--name` ; `--sql` ; `--description` ; `--yes`, `-y` | -| `fp query delete NAME` | Supprimer une requête enregistrée. | `--yes`, `-y` | -| `fp query run [NAME]` | Exécuter une requête enregistrée ou du SQL ad hoc. | `--sql` ; `--limit` ; `--all` ; `--arg`, `--param` | +| `fp query delete NAME` | Supprimer une requête sauvegardée. | `--yes`, `-y` | +| `fp query run [NAME]` | Exécuter une requête sauvegardée ou un SQL ad hoc. | `--sql` ; `--limit` ; `--all` ; `--arg`, `--param` | | `fp query schema [TABLE]` | Lister les tables interrogeables ou inspecter une table. | — | ### Utilisateurs @@ -204,7 +208,7 @@ Les jetons de permission utilisent le format `resource:action`, par exemple `eve | --- | --- | --- | | `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 des options `--value`, `--json-value`, `--file` ; `--yes`, `-y` en option | +| `fp settings set KEY` | Modifier un paramètre existant. | exactement l'une de `--value`, `--json-value`, `--file` ; `--yes`, `-y` optionnel | ### Alertes @@ -217,7 +221,7 @@ Les jetons de permission utilisent le format `resource:action`, par exemple `eve | `fp alerts delete NAME` | Supprimer une alerte. | `--yes`, `-y` | | `fp alerts test NAME` | Envoyer une notification de test. | `--channels` ; `--yes`, `-y` | -Les niveaux de gravité des alertes sont `info`, `warning` et `critical`. Les types de déclencheur sont `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` et `per_event`. Les intervalles d'évaluation doivent être compris entre 30 et 86 400 secondes. +Les sévérités d'alerte sont `info`, `warning` et `critical`. Les types de déclencheurs sont `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` et `per_event`. Les intervalles d'évaluation doivent être compris entre 30 et 86 400 secondes. ### Audits @@ -227,7 +231,7 @@ Les niveaux de gravité des alertes sont `info`, `warning` et `critical`. Les ty | `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 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 delete NAME` | Supprimer un audit, ses résultats et l'historique des exécutions. | `--yes`, `-y` | | `fp audits run NAME` | Mettre en file d'attente une exécution manuelle. | — | | `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. | — | @@ -240,7 +244,7 @@ Les niveaux de gravité des alertes sont `info`, `warning` et `critical`. Les ty | `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 ` requis | +| `fp audits assign FINDING_ID` | Définir le propriétaire du résultat. | `--to ` requis | #### Options de création d'audit @@ -257,18 +261,18 @@ fp audits create checkout-reliability \ | Option | Description | | --- | --- | -| `--file ` | Baser la définition sur du JSON, ou utiliser `-` pour stdin. Les options explicites remplacent les valeurs du fichier. | +| `--file ` | Baser la définition sur un JSON, ou utiliser `-` pour stdin. Les flags 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. 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. | +| `--schedule-anchor ` | Phase UTC fixe en 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 autres champs de portée pris en charge. | | `--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é du rapport. Par défaut : `medium`. | +| `--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`. | @@ -280,38 +284,76 @@ Incluez le contexte lors de la création si la première exécution en a besoin. `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. -### Incidents +### Problèmes | Commande | Objectif | Options | | --- | --- | --- | -| `fp issues list` | Lister les incidents. | `--state` ; `--alert-id` ; `--limit`, `-n` ; `--show-id` | -| `fp issues count` | Compter les incidents ouverts ou selon les états sélectionnés. | `--state` | -| `fp issues show INCIDENT_ID` | Afficher les détails d'un incident, ses commentaires, abonnés et activité. | — | -| `fp issues open` | Ouvrir un incident manuel ou lié à une alerte. | `--summary` requis ; `--title`, `--alert-id`, `--severity` en option | -| `fp issues ack INCIDENT_ID` | Accuser réception d'un incident. | — | -| `fp issues assign INCIDENT_ID` | Remplacer les responsables ; omettre l'option pour les effacer. | `--assignee` répétable | -| `fp issues resolve INCIDENT_ID` | Résoudre un incident. | `--yes`, `-y` | +| `fp issues list` | Lister les problèmes. | `--state` ; `--alert-id` ; `--limit`, `-n` ; `--show-id` | +| `fp issues count` | Compter les problèmes ouverts ou dans les états sélectionnés. | `--state` | +| `fp issues show INCIDENT_ID` | Afficher les détails, commentaires, abonnés et activité d'un problème. | — | +| `fp issues open` | Ouvrir un problème manuel ou lié à une alerte. | `--summary` requis ; `--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 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 des options `--body`, `--file` | +| `fp issues comment-add INCIDENT_ID` | Ajouter un commentaire. | exactement l'une 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` | | `fp issues unsubscribe INCIDENT_ID` | Supprimer un abonnement. | `--email` | -Les états d'incident valides sont `firing`, `acknowledged` et `resolved`. Les niveaux de gravité des incidents autonomes sont `info`, `warning` et `critical`. +Les états de problème valides sont `firing`, `acknowledged` et `resolved`. Les sévérités des problèmes autonomes sont `info`, `warning` et `critical`. -### Assistant Cloud +### Assistant cloud | Commande | Objectif | Options | | --- | --- | --- | | `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 chats` | Lister les conversations sauvegardées. | — | | `fp agent ask [MESSAGE]` | Démarrer ou continuer une conversation ; lit stdin si le message est omis. | `--chat` ; `--model` ; `--page-context` | -| `fp agent show CHAT_ID` | Afficher une conversation enregistrée. | — | +| `fp agent show CHAT_ID` | Afficher une conversation sauvegardée. | — | | `fp agent rename CHAT_ID` | Renommer une conversation. | `--title` requis | | `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`. + +| 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 sur chacun. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | La retirer de chaque déploiement qui la contient, 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, 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-path` ; `--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. + +| 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 pour une machine. | — | +| `fp fleet rollback MACHINE_ID` | Restaurer un déploiement précédent. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | Donner un nom lisible à une machine. | `--name` requis | + +### Garde-fous + +Ce que l'application a réellement fait. **Session uniquement**, même raison que ci-dessus. + +| Commande | Objectif | Options | +| --- | --- | --- | +| `fp guardrails summary` | Couverture, totaux bloqués/évalués, un graphique sparkline des refus et le tableau par politique. | `--since` (`1h`, `6h`, `24h`, `7d`) ; `--machine` | +| `fp guardrails timeline` | Décisions regroupées sur la fenêtre, agrégées pour toutes les sources de politiques. | `--since` (`1h`, `6h`, `24h`, `7d`) ; `--machine` | + ## Options globales | Option | Description | @@ -319,33 +361,39 @@ Les états d'incident valides sont `firing`, `acknowledged` et `resolved`. Les n | `--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. | +| `--token ` | Remplacer le jeton de session utilisateur sauvegardé. | +| `--api-key ` | Authentifier l'automatisation avec une clé API ; jamais sauvegardée. | | `--timeout ` | Délai d'expiration HTTP ; doit être positif. Par défaut : `30`. | -| `--quiet`, `-q` | Supprimer la sortie d'état sur stderr. | +| `--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. | +| `--insecure` / `--secure` | Désactiver ou restaurer la vérification des certificats TLS. | | `--version` | Afficher la version et quitter. | | `--help`, `-h` | Afficher l'aide. | -`--api-key` est destiné à l'automatisation. Les commandes de connexion, de changement d'organisation et d'assistant nécessitent une session utilisateur. +`--api-key` est destiné à l'automatisation. La connexion, le changement d'organisation et les commandes d'assistant nécessitent une session utilisateur. ## Variables d'environnement | Variable | Équivalent ou objectif | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | Déplacer le répertoire de configuration CLI actuel. | -| `AGENTEYE_ANALYTICS_DISABLED` ou `DO_NOT_TRACK` | Désactiver l'analytique CLI anonyme. | +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `FP_API_KEY` | `--api-key` | +| `FP_JSON` | `--json` | +| `FP_INSECURE` | `--insecure` | +| `FP_HOME` | Déplacer le répertoire de configuration du 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 options explicites remplacent les variables d'environnement, qui remplacent la configuration enregistrée. En mode clé API, sélectionnez le tenant explicitement avec `--org` ou `AGENTEYE_ORG`. +Les flags explicites remplacent les variables d'environnement, qui remplacent la configuration sauvegardée. En mode clé API, sélectionnez explicitement le locataire avec `--org` ou `FP_ORG`. + + + Les variantes `AGENTEYE_*` de ces variables **ne sont pas lues par `fp`** et ne l'ont jamais été — le 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 le CLI ; elle est ignorée et la commande s'exécute silencieusement contre le tableau de bord sauvegardé. + + `AGENTEYE_HOME` et `AGENTEYE_ENVIRONMENT` existent encore, mais elles appartiennent au **collecteur et au SDK de télémétrie**, pas à ce 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, réduisent au silence, 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. \ No newline at end of file diff --git a/docs/fr/reference/custom-agents.mdx b/docs/fr/reference/custom-agents.mdx index 2c13a294f..5e72fed92 100644 --- a/docs/fr/reference/custom-agents.mdx +++ b/docs/fr/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- title: "Agents personnalisés" -description: "Instrumentez les traces de vos agents personnalisés afin que Failproof AI puisse reconstruire les exécutions et identifier les défaillances." +description: "Configuration, catalogue d'événements, règles de corrélation et livraison pour failproofai-sdk." icon: "python" --- -Instrumentez les traces d'un agent personnalisé avec `failproofai-sdk` afin que Failproof AI puisse reconstruire chaque exécution, auditer son comportement et détecter les défaillances avec preuves à l'appui. Le SDK écrit des événements structurés que le daemon Failproof transmet au Cloud. Il requiert Python 3.10 ou une version ultérieure. +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. -Le traçage rend les agents personnalisés observables et auditables. Pour bloquer une action non sécurisée avant son exécution, il faut également un hook d'application dans votre runtime. + + + Installation, instrumentation, méthodes d'événements, exemple concret et problèmes courants. + + + LangChain, CrewAI, LlamaIndex et Pydantic AI s'instrumentent eux-mêmes en un seul appel. + + - - Pour appliquer des politiques dans une configuration d'agent personnalisé, [contactez Failproof AI](mailto:support@befailproof.ai). Nous vous aiderons à mapper les frontières de modèle, d'outil et de cycle de vie de votre runtime sur des hooks de politique. - +Python 3.10 ou supérieur. Aucune dépendance à l'exécution. -
- -
- -## Installer `failproofai-sdk` - -Le SDK est actuellement distribué sous forme de wheel privé. Contactez votre interlocuteur Failproof AI pour obtenir la version actuelle et l'accès au téléchargement. +## Installation ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -Avec `uv`, téléchargez d'abord le wheel puis exécutez `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl`. Épinglez le wheel dans un dépôt d'artefacts privé ou un fichier de verrouillage des dépendances. - -Le package est installé sous le nom `failproofai-sdk` et importé en Python sous le nom `failproofai`. +Le paquet 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 le wheel de base. -## Connecter le daemon Failproof +## Connexion au daemon Failproof - 1. Accédez à **Admin → Clés** et créez une clé avec `events:add`. + 1. Allez dans **Admin → Clés** 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. Exécutez une session instrumentée, puis retrouvez son identifiant exact dans **Observer → Événements**. - 4. Accédez à **Observer → Sessions**, sélectionnez le même environnement et ouvrez la trace reconstruite. + 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. - ![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) ```bash @@ -51,102 +46,84 @@ Le package est installé sous le nom `failproofai-sdk` et importé en Python sou -## Instrumenter une exécution complète - -Appelez `configure()` une seule fois au démarrage du processus. Chaque appel d'événement est exclusivement par mot-clé et requiert un `session_id` et un `agent_id` stables. +## Configuration ```python -import traceback -import uuid +import failproofai_sdk -import failproofai +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -failproofai.configure(environment="production") +| Argument | Ce qu'il fait | +| --- | --- | +| `environment` | Le libellé appliqué à 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` | Emplacement d'écriture. Par défaut : le spool du daemon, ce qui convient sauf cas particulier. | -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +Peut également être défini via des variables d'environnement : -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) +| 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 priorité sur cette variable. | +| `FAILPROOFAI_HOME` | Déplace la racine Failproof AI qui contient le spool. | +| `FAILPROOFAI_SDK_STRICT` | La valeur `1` fait lever une exception sur les erreurs d'instrumentation au lieu de les journaliser. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | La valeur `1` fait lever une exception en cas de problème de compatibilité avec un framework, au lieu d'avertir et de continuer. | -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + + **Pas de virgules dans `environment`.** L'ingestion divise ce champ sur les virgules pour construire ses filtres, et ignore tout événement dont le libellé en contient une — une exécution entière peut ainsi disparaître silencieusement. Écrivez `prod-eu`, pas `prod,eu`. + + `configure(environment="prod,eu")` lève une exception afin que vous le découvriez immédiatement. `AGENTEYE_ENVIRONMENT` ne peut pas lever d'exception — rien ne vous appelle — donc il avertit une fois et bascule sur `dev`. + -Émettez `agent_start` une seule fois par acteur. Pour les sous-agents, réutilisez le `session_id` du parent, attribuez un `agent_id` distinct à chaque acteur et définissez `parent_id` sur l'**identifiant d'agent** du parent, et non sur l'identifiant de session. +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 interrompu brutalement perd tout ce qui n'a pas encore été écrit. -## Référence de configuration +## Identité + +Chaque événement appartient à une session et à un agent. **Les scopes renseignent les deux**, vous n'avez donc rarement besoin de les passer : ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| Paramètre | Comportement | -| --- | --- | -| `base_dir` | Racine de spool explicite. Prioritaire sur toutes les variables d'environnement. | -| `flush_interval` | Secondes entre les écritures en arrière-plan de la mémoire vers le JSONL. Par défaut : `0.5`. | -| `environment` | Libellé de déploiement sur chaque événement. Par défaut : `dev`. | -| `FAILPROOFAI_HOME` | Modifie la racine Failproof AI qui contient le spool `custom-agents`. | - -Le SDK écrit dans le `base_dir` explicite lorsqu'il est défini. Sinon, il utilise le spool `custom-agents` du daemon Failproof sous `FAILPROOFAI_HOME` ou `~/.failproofai`. +Passer `session_id` ou `agent_id` explicitement fonctionne toujours et a priorité. Si ni l'un ni l'autre n'est lié ni passé, l'appel lève `TypeError` plutôt que d'émettre un événement que Cloud ignorerait silencieusement. -Le SDK met les appels en file d'attente en mémoire et écrit des lots sur un thread en arrière-plan. Il tente également un vidage final via le mécanisme `atexit` de Python. Pour les workers à courte durée de vie, autorisez l'arrêt normal de l'interpréteur ; une terminaison brutale du processus peut entraîner la perte des événements encore en mémoire. + + L'identité repose sur 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 seront perdus. + ## Catalogue d'événements -Toutes les méthodes retournent `None`. Les champs laissés à `None` sont omis plutôt qu'écrits comme JSON `null`. +Quinze méthodes. La plupart viennent en **paires** — vous appelez l'ouvrante, puis la fermante, et le SDK mesure l'écart. -| Méthode | Champs requis au-delà de l'identité | Champs optionnels | +| | Ouvre | Ferme | +| --- | --- | --- | +| **Agents** | `agent_start` | `agent_end` | +| | `agent_pause` | `agent_resume` | +| **Modèles** | `model_request` | `model_response` | +| **Outils** | `tool_use` | `tool_result` | +| **Hooks** | `hook_triggered` | `hook_completed` | +| **Humains** | `human_wait` | `human_input` | + +Trois sont autonomes : `error`, `human_pause`, `human_interrupt`. + + + +Chaque méthode accepte également `session_id` et `agent_id`, que les scopes renseignent pour vous. Tout champ laissé à `None` est omis plutôt qu'envoyé comme JSON `null`, et chaque méthode retourne `None`. + +| Méthode | Requis | Optionnel | | --- | --- | --- | | `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ Toutes les méthodes retournent `None`. Les champs laissés à `None` sont omis | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -Utilisez `outcome="failed"`, `"error"`, `"timeout"` ou `"rejected"` lorsqu'une complétion doit être comptabilisée comme un échec. Les autres valeurs, y compris `"failure"`, ne sont pas classifiées comme des échecs par le backend actuel. + + + + 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 fermant le même identifiant que son ouvrant.** C'est ce qui les apparie et ce qui permet au SDK de mesurer l'écart. + +| Paire | Mise en correspondance sur | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**Ne passez pas `duration_ms` vous-même.** Le SDK le mesure, et le passer lève une `ValueError`. -## Règles de corrélation et de durée +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. -- 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 manuellement à ces méthodes lève une `ValueError`. -- Les identifiants d'outils et de hooks partagent une même table de correspondance des starts en attente au niveau du processus. Rendez-les globalement uniques entre les sessions concurrentes et entre les deux espaces de noms ; les identifiants de fournisseur ou les UUID sont les plus sûrs. -- Une paire répartie sur plusieurs processus reste corrélée en aval, mais le SDK ne peut pas calculer sa durée interne au processus. -- La table de correspondance conserve au maximum 10 000 démarrages et évince l'entrée la plus ancienne lorsqu'elle est pleine. + -## Champs personnalisés et payloads +- **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 tout de 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 appairés dans l'ordre d'arrivée, ce qui peut mener à des appariements incorrects pour deux appels simultanés dans le même agent. +- **Une paire répartie entre deux processus** est quand même mise en correspondance dans Cloud, mais le SDK ne peut pas la chronométrer — aucun des deux processus n'a vu les deux moitiés. +- **Au maximum 10 000 ouvrantes attendent une fermante à la fois.** Au-delà, la plus ancienne est supprimée, de sorte qu'une fuite ne peut pas croître indéfiniment. -Chaque événement accepte des champs de mot-clé supplémentaires. Utilisez des valeurs compatibles JSON lorsque les requêtes en aval nécessitent une structure. Les types non pris en charge tels que les UUID, les datetime, les decimals, les ensembles, les bytes et les objets de modèle sont convertis en chaîne par le writer. + -Les noms personnalisés réservés sont `timestamp`, `session_id`, `agent_id`, `type` et `environment`. Les fautes de frappe sur les champs optionnels sont acceptées comme de nouveaux champs personnalisés ; vérifiez donc le JSON émis lorsqu'un champ standard n'apparaît pas dans le Cloud. +## Vos propres champs -## Livrer et vérifier +Tout mot-clé supplémentaire que vous passez est stocké avec l'événement : + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # les vôtres +) +``` + +Privilégiez les types JSON si vous souhaitez les interroger ultérieurement. Tout autre type — un UUID, un datetime, un `Decimal`, un set, des bytes, un objet de 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 la vraie valeur. Les adaptateurs de framework utilisent `fw_` ; faites de même et aucune collision ne sera possible. + + 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 absent dans Cloud, vérifiez d'abord l'orthographe. + + +Ces cinq noms sont réservés et rejetés d'office : `timestamp`, `session_id`, `agent_id`, `type`, `environment`. + +## Livraison et vérification - Dans **Observer → Événements**, vérifiez que `agent_start` apparaît en premier et `agent_end` en dernier. Ouvrez ensuite **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é de dépannage principale. + Dans **Observer → Événements**, vérifiez que `agent_start` existe en premier et `agent_end` en dernier. Puis 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. ```bash @@ -189,10 +203,14 @@ Les noms personnalisés réservés sont `timestamp`, `session_id`, `agent_id`, ` -Si le Cloud est vide, inspectez `$FAILPROOFAI_HOME/custom-agents/events`, sinon `~/.failproofai/custom-agents/events`. Les fichiers JSONL confirment l'émission par le SDK ; un spool qui grossit indique un problème de configuration ou de livraison du daemon, 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 qui grossit pointe vers la configuration du daemon ou la livraison, tandis qu'un spool vide pointe vers l'instrumentation ou la durée de vie du processus. + + + 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 ceux qui ont été émis. + ## Prévenir les défaillances dans un runtime personnalisé -Utilisez les résultats d'audit et les traces associées pour définir l'action non sécurisée, les preuves requises et la réponse prévue. Une intégration d'application 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. +Utilisez les résultats d'audit et les traces associées pour définir l'action non sécurisée, les preuves requises et la réponse prévue. Une intégration d'application 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 résultante : allow, instruct ou deny. -Envoyez un email à [support@befailproof.ai](mailto:support@befailproof.ai) pour concevoir et valider cette intégration pour votre runtime. \ No newline at end of file +[Contactez Failproof AI](mailto:support@befailproof.ai) et nous vous aiderons à mapper les limites de modèle, d'outil et de cycle de vie de votre runtime sur des hooks de politique, puis à valider l'intégration avec vous. \ No newline at end of file diff --git a/docs/fr/reference/events-and-configuration.mdx b/docs/fr/reference/events-and-configuration.mdx index 684be8e09..f5644f0e2 100644 --- a/docs/fr/reference/events-and-configuration.mdx +++ b/docs/fr/reference/events-and-configuration.mdx @@ -6,36 +6,36 @@ icon: "list-tree" ## Familles d'événements -- Démarrage, fin, pause et reprise d'un agent +- Démarrage, fin, pause et reprise d'agent - Requête et réponse du modèle -- Utilisation d'outil et résultat -- Déclenchement et complétion d'un hook +- Utilisation et résultat d'outil +- Déclenchement et achèvement de hook - Attente humaine, saisie, pause et interruption - Erreurs explicites -Chaque événement comporte un horodatage, un ID de session, un ID d'agent, un type d'événement et un environnement. Les champs spécifiques à l'événement contiennent des données relatives au modèle, à l'outil, à la corrélation, au résultat, au contenu, à la durée ou à l'erreur. +Chaque événement porte un horodatage, un identifiant de session, un identifiant d'agent, un type d'événement et un environnement. Les champs spécifiques à l'événement contiennent des données de modèle, d'outil, de corrélation, de résultat, de contenu, de durée ou d'erreur. ## Inspecter un contrat d'événement - 1. Ouvrez **Observer → Événements**. - 2. Définissez une fenêtre temporelle courte et filtrez par environnement, agent et type d'événement. - 3. Sélectionnez un événement pour inspecter ses champs normalisés et sa charge utile brute, puis ouvrez sa session pour visualiser le contexte d'exécution. - 4. Si une durée associée est manquante, vérifiez que les événements de début et de fin utilisent le même ID de corrélation. + 1. Ouvrez **Observe → Events**. + 2. Définissez une courte fenêtre temporelle et filtrez par environnement, agent et type d'événement. + 3. Sélectionnez un événement pour inspecter ses champs normalisés et sa charge utile brute, puis ouvrez sa session pour voir le contexte d'exécution. + 4. Si une durée appariée est manquante, vérifiez que les événements de début et de fin utilisent le même identifiant de corrélation. - Utilisez le flux d'événements pour restreindre les données à une seule exécution d'agent et inspecter les champs d'événement normalisés. + Utilisez le flux Events pour restreindre les données à une seule exécution d'agent et inspecter les champs d'événement normalisés. - ![Le flux d'événements en direct avec des filtres pour l'environnement, l'agent, la session et le type d'événement.](/images/dashboard/events-stream.png) + ![Le flux Events en direct avec des filtres pour l'environnement, l'agent, la session et le type d'événement.](/images/dashboard/events-stream.png) - Suivez ensuite l'événement dans sa session. La trace indique ce qui s'est passé immédiatement avant et après, ce qui est indispensable lorsque la charge utile seule est ambiguë. + Suivez ensuite l'événement dans sa session. La trace montre ce qui s'est passé juste avant et après, ce qui est nécessaire lorsque la charge utile seule est ambiguë. ![La trace de session liée utilisée pour inspecter l'événement dans son contexte d'exécution.](/images/dashboard/session-detail.png) - Comparez les ID de corrélation et les horodatages dans les deux vues lorsqu'un événement associé ou une durée est manquant. + Comparez les identifiants de corrélation et les horodatages dans les deux vues lorsqu'un événement apparié ou une durée est manquant. - Découvrez les valeurs de filtre valides, puis récupérez les charges utiles complètes d'une session : + Découvrez les valeurs de filtre valides, puis récupérez les charges utiles complètes des événements pour une session : ```bash fp list event_types @@ -53,22 +53,22 @@ Chaque événement comporte un horodatage, un ID de session, un ID d'agent, un t ## Champs réservés du SDK -N'utilisez pas `timestamp`, `session_id`, `agent_id`, `type` ou `environment` comme champs personnalisés du SDK Python. Les durées d'événements associés, telles que la durée du résultat d'outil, sont calculées par le SDK et ne peuvent pas être fournies manuellement. +N'utilisez pas `timestamp`, `session_id`, `agent_id`, `type` ou `environment` comme champs Python SDK personnalisés. Les durées d'événements appariés, telles que la durée du résultat d'outil, sont calculées par le SDK et ne peuvent pas être fournies manuellement. ## Limites locales -- L'état de Failproof AI réside sous `~/.failproofai`, sauf configuration explicite contraire. -- `failproofai-sdk` utilise `AGENTEYE_HOME` pour son remplacement hérité du répertoire de base. -- Les étiquettes d'environnement peuvent être définies via la configuration du SDK ou `AGENTEYE_ENVIRONMENT`. -- Les identifiants du daemon sont stockés séparément des paramètres non confidentiels. +- L'état de Failproof AI réside sous `~/.failproofai` sauf configuration explicite contraire. +- `failproofai-sdk` spooule toujours sous `~/.failproofai/custom-agents`. `FAILPROOFAI_HOME` déplace ce répertoire home ; le segment `custom-agents` est toujours ajouté, de sorte que le spool ne peut pas être placé en dehors de celui-ci. Seul le propre `configure(base_dir=...)` du SDK écrit ailleurs. `AGENTEYE_HOME` est lu par l'ancien `agenteye-collector` pour choisir ce qu'il surveille, et n'affecte plus l'endroit où le SDK écrit. +- Les labels d'environnement peuvent être définis via la configuration du SDK ou `AGENTEYE_ENVIRONMENT`. +- Les identifiants du daemon sont stockés séparément des paramètres non secrets. -Utilisez des noms d'environnement stables à faible cardinalité. Les virgules ne sont pas prises en charge dans les étiquettes d'environnement du daemon. +Utilisez des noms d'environnement stables et à faible cardinalité. Les virgules ne sont pas prises en charge dans les labels d'environnement du daemon. -## Modifier une étiquette d'environnement +## Modifier un label d'environnement - Les étiquettes d'environnement sont assignées par le SDK émetteur ou le daemon Failproof. Après en avoir modifié une, ouvrez **Observer → Sessions** et utilisez le filtre d'environnement pour confirmer que les nouvelles sessions portent bien la nouvelle valeur. Les sessions existantes conservent leur environnement d'origine. + Les labels d'environnement sont assignés par le SDK émetteur ou le daemon Failproof. Après en avoir modifié un, ouvrez **Observe → Sessions** et utilisez le filtre d'environnement pour confirmer que les nouvelles sessions portent la nouvelle valeur. Les sessions existantes conservent leur environnement d'origine. diff --git a/docs/fr/reference/harnesses.mdx b/docs/fr/reference/harnesses.mdx index 170d592a5..a7210c4f8 100644 --- a/docs/fr/reference/harnesses.mdx +++ b/docs/fr/reference/harnesses.mdx @@ -1,68 +1,68 @@ --- -title: "Harnais d'agents" -description: "Capturez les sessions et appliquez des politiques sur l'ensemble des 12 harnais d'agents pris en charge." +title: "Harnais d'agent" +description: "Capturez les sessions et appliquez des politiques sur l'ensemble des 12 harnais d'agent pris en charge." icon: "plug-zap" --- -Un harnais est l'environnement dans lequel votre agent s'exécute concrètement. Failproof AI en prend en charge douze, répartis en deux catégories : +Un harnais correspond à l'environnement dans lequel votre agent s'exécute concrètement. Failproof AI en prend en charge douze, répartis en deux catégories : - **CLI 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 session s'appliquent quel que soit le harnais utilisé. Une couche d'adaptation mappe les noms d'événements natifs, les noms d'outils et les champs d'entrée propres à chaque harnais vers 29 événements canoniques, avant toute exécution de politique. +Les mêmes politiques et le même historique de session 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 toute exécution de politique. -Un agent qui ne tourne dans **aucun** des douze harnais est instrumenté directement via le [SDK Python](/fr/reference/custom-agents). Ce contrat est différent, et mérite d'être énoncé 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 qu'elle ne s'exécute nécessite un hook d'application à la frontière 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 harnais est instrumenté directement via 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 de politiques par lui-même.** Pour bloquer une action non sûre avant son exécution, un hook d'application est nécessaire à la frontière des outils de votre environnement d'exécution ; [contactez-nous](mailto:support@befailproof.ai) et nous l'adapterons. -| Harnais | Scopes de hook pris en charge | +| Harnais | Portées de hook prises en charge | | --- | --- | | 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 | -Chaque intégration normalise ses noms d'événements de hook natifs, ses noms d'outils et ses champs d'entrée 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 le comportement des 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é. Un blocage post-outil peut remplacer le résultat présenté au modèle, mais ne peut pas annuler un effet de bord d'outil qui s'est déjà produit. +« 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. -| Harnais | Événements de blocage vérifiés | Mises en garde observation seule ou non-bloquant | +| Harnais | Événements de blocage vérifiés | Mises en garde : observation seule ou non bloquant | | --- | --- | --- | -| 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 en mode observation. | -| 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 en mode observation 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 en mode observation. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` et les événements de session sont en mode observation. | -| OpenCode | `PreToolUse` | Les événements post-outil et de cycle de vie sont en mode observation ; la gestion de l'arrêt actuelle constitue une recommandation pour un tour ultérieur plutôt qu'une véritable barrière. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Les événements post-outil et de cycle de vie sont en mode observation ; les recommandations d'arrêt s'appliquent à un tour ultérieur. | +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, et plusieurs événements de tâche/configuration | `PostToolUse`, le cycle de vie des sessions, 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 est une recommandation 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 ; les recommandations d'arrêt s'appliquent à un tour ultérieur. | | Hermes | `PreToolUse` | Les verdicts post-outil, de session et d'arrêt de sous-agent ne constituent pas des barrières. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Les événements post-outil, de session, d'arrêt de sous-agent et de compaction sont en mode observation. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Les verdicts post-outil et d'arrêt de sous-agent sont en mode observation. | -| 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 en mode observation. | -| Antigravity CLI | `PreToolUse`, `Stop` | Les verdicts de prompt utilisateur et post-outil sont en mode observation ; les instructions de prompt peuvent tout de même être injectées. | -| Goose | `PreToolUse` | Les événements de prompt utilisateur, post-outil et de session sont en mode observation. Un hook d'arrêt bloquant natif existe en amont mais n'est pas installé par l'adaptateur actuel. | +| 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 de prompt utilisateur et post-outil sont observationnels ; les instructions de prompt peuvent toujours être injectées. | +| Goose | `PreToolUse` | Les événements de prompt utilisateur, post-outil et de session sont observationnels. Un hook d'arrêt bloquant natif existe en amont, mais n'est pas installé par l'adaptateur actuel. | -Les capacités dépendent de la version. Retestez après la mise à niveau d'un CLI d'agent, en particulier lorsqu'une politique repose sur le comportement du prompt, de l'arrêt, des permissions ou post-outil plutôt que sur la barrière pré-outil commune. +Les capacités sont sensibles à la version. Retestez après la mise à jour d'un CLI d'agent, en particulier lorsqu'une politique repose sur le comportement du prompt, de l'arrêt, des permissions ou du post-outil plutôt que sur la barrière pré-outil commune. ## Installer les hooks de capture et de politique - 1. Ouvrez **Administration → Clés** et créez une clé avec les permissions `events:add` et `policies:pull`, nommée en fonction de la machine ou de l'environnement. - 2. Sur la machine cible, connectez le CLI local avec la clé affichée et installez les hooks du harnais. + 1. Ouvrez **Administration → Clés** et créez une clé avec les permissions `events:add` et `policies:pull`, nommée selon la machine ou l'environnement. + 2. Sur la machine cible, connectez le CLI local avec la clé affichée et installez les hooks de 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 fenêtre temporelle et confirmez qu'une décision de politique est attribuée à la machine. - La connexion démarre avec une clé machine. Vérifiez qu'elle inclut bien les permissions d'ingestion et de livraison de politiques avant de copier son secret. + La connexion commence par une clé de machine. Vérifiez qu'elle inclut bien les permissions d'ingestion et de livraison de politique avant de copier son secret. - ![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 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 doit afficher de nouveaux événements provenant de la machine et de l'environnement connectés. + 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 utilisé pour confirmer qu'un harnais nouvellement installé remonte bien des données.](/images/dashboard/events-stream.png) + ![Le flux d'événements en direct permettant de confirmer qu'un harnais nouvellement installé remonte 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 remonte 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 remonte bien l'activité de politique ainsi que les événements de trace. - ![La page Politique utilisée pour vérifier les décisions de politique d'un harnais nouvellement connecté.](/images/dashboard/policy-observe.png) + ![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 : @@ -74,7 +74,7 @@ Les capacités dépendent de la version. Retestez après la mise à niveau d'un failproofai policies --install ``` - Ou ciblez des harnais précis et un scope de configuration : + Ou ciblez des harnais spécifiques et une portée de configuration : ```bash failproofai policies --install \ @@ -82,7 +82,7 @@ Les capacités dépendent de la version. Retestez après la mise à niveau d'un --scope user ``` - Le scope project conserve la configuration des hooks avec un dépôt. Le scope user couvre le travail sur plusieurs dépôts. Claude Code prend également en charge le scope local ; 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 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. Vérifiez la machine et ses événements : @@ -94,16 +94,16 @@ Les capacités dépendent de la version. Retestez après la mise à niveau d'un -## Ajouter un chemin de session non-défaut +## Ajouter un chemin de session non par défaut - 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 vérifiez que les sessions provenant du nouveau chemin apparaissent. Ouvrez une session et vérifiez l'agent, le harnais et les horodatages des événements avant de l'utiliser 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 d'événements avant de vous y fier dans un audit. ![La liste des sessions filtrée sur l'environnement recevant les 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 : + Ajoutez un chemin avec un label optionnel, puis inspectez les chemins configurés : ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -117,5 +117,5 @@ Les capacités dépendent de la version. Retestez après la mise à niveau d'un - Lancez une nouvelle session après l'installation. Vérifiez à la fois le flux d'événements en direct et une décision de politique effective avant d'étendre le déploiement. + Exécutez une nouvelle session après l'installation. Vérifiez à la fois le flux d'événements en direct et une décision de politique effective avant d'élargir le déploiement. \ No newline at end of file diff --git a/docs/fr/reference/overview.mdx b/docs/fr/reference/overview.mdx index e833be9c5..63b5d7d04 100644 --- a/docs/fr/reference/overview.mdx +++ b/docs/fr/reference/overview.mdx @@ -1,39 +1,42 @@ --- title: "Intégrations et référence" -description: "Connectez les harnais d'agents, les SDKs, les CLIs et l'API HTTP pris en charge." +description: "Connectez les agents, SDK, CLI et l'API HTTP pris en charge." icon: "braces" --- Choisissez l'intégration la plus proche de l'environnement dans lequel votre agent s'exécute déjà. - - Installez des hooks pour les CLIs d'agents de codage et autonomes pris en charge. + + Installez des hooks pour les CLI d'agents autonomes et de codage pris en charge. - - Instrumentez des traces pour identifier les échecs dans vos agents personnalisés, puis contactez-nous pour ajouter une prévention à votre runtime. + + Instrumentez LangGraph, CrewAI, LlamaIndex, Pydantic AI ou un agent personnalisé. + + + Configuration, catalogue d'événements, règles de corrélation et livraison. - Consultez les projets locaux, les sessions, l'activité des politiques et les audits hors ligne. + Examinez les projets locaux, les sessions, l'activité des politiques et les audits hors ligne. - + Configurez la capture locale, les hooks, les politiques, les audits, la livraison et l'état de la machine. - + Interrogez et administrez les sessions Cloud, les audits, les problèmes, les alertes, les clés, les utilisateurs et les paramètres. É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. + Rédigez 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`. Les 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`. Les pages rédigées manuellement expliquent les workflows qui s'étendent sur plusieurs endpoints ou utilisent des interfaces administratives en dehors de cette surface publique. ## Connecter un agent et vérifier les données @@ -41,21 +44,21 @@ La [référence de l'API HTTP](/fr/reference/http-api) générée couvre la surf 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 par l'environnement de l'intégration et inspectez une session pour y trouver les champs de modèle, d'outil, d'erreur et de politique requis par les audits. + 3. Ouvrez **Observer → Événements** pour confirmer l'arrivée des événements, puis **Observer → Sessions** pour confirmer qu'ils constituent des exécutions complètes. + 4. Filtrez selon l'environnement de l'intégration et inspectez une session pour les champs modèle, outil, erreur et politique requis par les audits. - Commencez par le tiroir des 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 le Cloud. + Commencez par le tiroir des clés. 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 tiroir de création de clé API permettant d'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. + Après avoir connecté l'intégration, utilisez la liste des Sessions pour confirmer que ses événements sont bien regroupés en exécutions complètes dans l'environnement attendu. - ![La liste des Sessions permettant de 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 rapporte des exécutions d'agents 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, connectez le daemon Failproof et vérifiez la première session. ```bash fp keys create agent-production \ @@ -71,8 +74,8 @@ La [référence de l'API HTTP](/fr/reference/http-api) générée couvre la surf fp events --since 1h --env production --limit 20 ``` - 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. + Utilisez `fp --json sessions ...` lorsqu'un autre outil doit consommer le résultat. Les options globales telles que `--json`, `--org` et `--base-url` doivent être placées avant la commande. - Consultez la [référence du Failproof AI CLI](/fr/reference/failproof-cli) pour les commandes locales et la [référence du Failproof Cloud CLI](/fr/reference/cloud-cli#cli-commands) pour les commandes `fp`. + Consultez la [référence CLI Failproof AI](/fr/reference/failproof-cli) pour les commandes locales et la [référence CLI Failproof Cloud](/fr/reference/cloud-cli#cli-commands) pour les commandes `fp`. \ No newline at end of file diff --git a/docs/fr/reference/troubleshooting.mdx b/docs/fr/reference/troubleshooting.mdx index 00be4a83c..b6a3808e4 100644 --- a/docs/fr/reference/troubleshooting.mdx +++ b/docs/fr/reference/troubleshooting.mdx @@ -5,10 +5,10 @@ icon: "wrench" --- - + - Ouvrez **Administration → Clés** et confirmez que la clé machine est active et dispose de `events:add`. Ouvrez ensuite **Observer → Événements**, élargissez la plage temporelle et effacez les filtres d'environnement et d'agent. Si des événements existent, recherchez l'ID de session puis vérifiez **Observer → Sessions** pour le regroupement. Si aucun événement n'existe, diagnostiquez le démon Failproof depuis la CLI. + Ouvrez **Administration → Clés** et confirmez que la clé machine est active et dispose de `events:add`. Ouvrez ensuite **Observer → Événements**, élargissez la plage temporelle et supprimez les filtres d'environnement et d'agent. Si des événements existent, recherchez l'ID de session puis consultez **Observer → Sessions** pour le regroupement. Si aucun événement n'existe, diagnostiquez le daemon Failproof depuis la CLI. ![Le flux d'événements en direct avec ses filtres principaux visibles et des événements d'agent récents qui arrivent.](/images/dashboard/events-stream-current.png) @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - Confirmez que la capture est activée, que la clé configurée dispose de `events:add`, et que le filtre du tableau de bord correspond à l'environnement émis. + Vérifiez que la capture est activée, que la clé configurée dispose de `events:add` et que le filtre du tableau de bord correspond à l'environnement émis. - + - Effacez les filtres dans **Observer → Événements** et recherchez l'ID de session SDK exact. Si rien n'apparaît, inspectez le spool du SDK et le démon Failproof sur la machine source. + Supprimez les filtres dans **Observer → Événements** et recherchez l'ID de session SDK exact. Si rien n'apparaît, inspectez le spool du SDK et le daemon Failproof sur la machine source. ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - Confirmez que le processus agent définit `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` et que `$FAILPROOFAI_HOME/custom-agents`, ou sinon `~/.failproofai/custom-agents`, existe avant le démarrage du SDK. + Vérifiez qu'un daemon est en cours d'exécution et connecté — le SDK met en spool qu'un daemon soit présent ou non. Le répertoire de spool n'a **pas** besoin d'exister au préalable (l'écrivain le crée), et aucune variable d'environnement ne le sélectionne : `$FAILPROOFAI_HOME/custom-agents`, ou sinon `~/.failproofai/custom-agents`, est la seule racine, et `configure(base_dir=...)` est le seul moyen de la remplacer. Si le processus a été tué par `SIGKILL` ou par un OOM, tout ce qui était encore en file d'attente est perdu — gérez `SIGTERM` pour limiter cela. - Ouvrez **Admin → Application**, sélectionnez la machine et comparez ses versions assignée, signalée et précédente. Confirmez que le périmètre de déploiement inclut la machine et que sa clé dispose de `policies:pull`. L'ingestion peut fonctionner même lorsque la livraison des politiques ne fonctionne pas. + Ouvrez **Admin → application des politiques**, sélectionnez la machine et comparez ses versions assignée, rapportée et précédente. Vérifiez que le périmètre de déploiement inclut la machine et que sa clé dispose de `policies:pull`. L'ingestion peut fonctionner même lorsque la livraison des politiques ne fonctionne pas. @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - Confirmez que l'ID et le libellé de la machine correspondent à la cible dans le tableau de bord. Reconnectez-vous avec une clé compatible avec les politiques si le credential existant n'accorde que l'ingestion d'événements. + Vérifiez que l'ID et le libellé de la machine correspondent à la cible dans le tableau de bord. Reconnectez-vous avec une clé compatible avec les politiques si les identifiants existants n'autorisent que l'ingestion d'événements. - + - Ouvrez **Admin → Application** et inspectez l'heure de dernière activité et la version signalée de la machine. Si la machine est obsolète, traitez cela comme un problème de démon local. N'affaiblissez pas la politique déployée uniquement pour contourner un démon indisponible. + Ouvrez **Admin → application des politiques** et inspectez l'heure de dernière connexion et la version rapportée de la machine. Si la machine est obsolète, traitez cela comme un problème de daemon local. N'affaiblissez pas la politique déployée uniquement pour contourner un daemon indisponible. @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - Redémarrez ou mettez à jour `failproofaid` ; relancez la configuration lorsque les versions de protocole de la CLI et du démon diffèrent. Le chemin du démon configuré échoue de façon fermée par conception. + Redémarrez ou mettez à jour `failproofaid` ; relancez la configuration lorsque les versions de protocole de la CLI et du daemon diffèrent. Le chemin du daemon configuré échoue en mode fermé par conception. - Pour une politique créée dans Cloud, ouvrez **Admin → Éditeur de politiques**, sélectionnez le brouillon et examinez les erreurs de validation avant de publier. Pour une politique locale, utilisez la CLI pour la valider, puis ouvrez **Observer → Politique** après une action de test pour confirmer que les décisions arrivent. + Pour une politique créée dans le Cloud, ouvrez **Admin → éditeur de politiques**, sélectionnez le brouillon et examinez les erreurs de validation avant de publier. Pour une politique locale, utilisez la CLI pour la valider, puis ouvrez **Observer → politique** après une action de test pour confirmer que les décisions arrivent. - Confirmez que le nom de fichier se termine par `policies.js`, `policies.mjs` ou `policies.ts`, que le module appelle `customPolicies.add(...)`, et que les imports sont résolus depuis le fichier de politique. + Vérifiez que le nom du fichier se termine par `policies.js`, `policies.mjs` ou `policies.ts`, que le module appelle `customPolicies.add(...)` et que les imports se résolvent depuis le fichier de politique. ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -94,9 +94,9 @@ icon: "wrench" - Ouvrez **Analyser → Audits**, sélectionnez l'exécution et vérifiez si l'analyse du modèle s'est effectuée. Comparez ensuite son périmètre et sa fenêtre avec **Observer → Sessions** et ouvrez des traces représentatives de cette population. + Ouvrez **Analyser → audits**, sélectionnez l'exécution et vérifiez si l'analyse par modèle a été lancée. Comparez ensuite son périmètre et sa fenêtre avec **Observer → sessions** et ouvrez des traces représentatives de cette population. - Un résultat nul n'est significatif que lorsque l'analyse s'est exécutée avec succès. Si l'analyse a été ignorée ou a échoué, l'exécution ne produit aucun résultat et maintient la fenêtre non analysée ouverte pour une prochaine exécution réussie. Si l'analyse du modèle est désactivée, l'audit ne produit également aucun résultat, car le scan déterministe des credentials et des PII enregistre des statistiques mais ne génère plus de résultats. + Un résultat nul n'est significatif que si l'analyse s'est terminée avec succès. Si l'analyse a été ignorée ou a échoué, l'exécution ne produit aucun résultat et conserve la fenêtre non analysée pour une future exécution réussie. Si l'analyse par modèle est désactivée, l'audit ne produit également aucun résultat, car le scan déterministe des identifiants et des PII enregistre des statistiques mais ne génère plus de résultats. ![Le formulaire d'audit où l'environnement, l'agent, la cadence et la fenêtre de balayage définissent la population de sessions.](/images/dashboard/audit-new.png) @@ -110,14 +110,14 @@ icon: "wrench" fp audits findings --audit ``` - Si l'exécution est restée en file d'attente, attendez que de la capacité d'agent d'audit soit disponible ou demandez à l'opérateur de déploiement d'inspecter la flotte d'audit. Un audit en file d'attente est retenté ; il n'est pas immédiatement ignoré. + Si l'exécution est restée en file d'attente, attendez que la capacité de l'agent d'audit soit disponible ou demandez à l'opérateur du déploiement d'inspecter la flotte d'audit. Un audit en file d'attente réessaie ; il n'est pas immédiatement ignoré. - Ouvrez une session terminée et vérifiez si une évaluation manuelle réussit. Le Cloud hébergé ne dispose actuellement d'aucun contrôle de point de terminaison d'évaluateur dans le tableau de bord ; l'opérateur serveur doit le configurer. + Ouvrez une session terminée et vérifiez si une évaluation manuelle réussit. Le Cloud hébergé ne dispose actuellement d'aucun contrôle de point de terminaison d'évaluateur dans le tableau de bord ; l'opérateur du serveur doit le configurer. Vérifiez l'évaluateur lui-même, puis inspectez les états d'évaluation récents : @@ -131,7 +131,7 @@ icon: "wrench" - + Utilisez le sélecteur d'organisation et confirmez le slug et les permissions attendus avant de comparer les résultats avec la CLI. @@ -150,11 +150,11 @@ icon: "wrench" - Ouvrez **Observer → Politique**, conservez la décision et la session liée, et identifiez la condition de faux positif. Ouvrez ensuite **Admin → Application** et revenez à la version précédente pour les machines concernées. Créez une version plus restrictive dans l'**Éditeur de politiques**, testez-la sur un périmètre restreint, et étendez-la uniquement après que le travail valide réussisse. + Ouvrez **Observer → politique**, conservez la décision et la session liée, et identifiez la condition de faux positif. Ouvrez ensuite **Admin → application des politiques** et revenez aux machines affectées à la version précédente. Créez une version plus précise dans l'**éditeur de politiques**, testez-la sur un périmètre restreint et élargissez uniquement après que le travail valide réussit. - Le retour arrière lors d'un déploiement Cloud se fait uniquement via le tableau de bord. La mise en pause d'une session locale ne désactive pas les politiques gérées par Cloud. Si le tableau de bord est indisponible, capturez l'état de la machine et du déploiement, et rétablissez l'accès au tableau de bord plutôt que de retenter indéfiniment l'action bloquée. + La restauration du déploiement Cloud se fait uniquement depuis le tableau de bord. Une pause de session locale ne désactive pas les politiques gérées par le Cloud. Si le tableau de bord est indisponible, capturez l'état de la machine et du déploiement et rétablissez l'accès au tableau de bord plutôt que de réessayer répétitivement l'action bloquée. ```bash failproofai config --status @@ -164,4 +164,4 @@ icon: "wrench" -Lorsque vous contactez le support, incluez la version de la CLI, le harnais, l'environnement, l'ID de session ou de déploiement pertinent, ainsi que la sortie de `failproofai config --status` avec les secrets supprimés. \ No newline at end of file +Lorsque vous contactez le support, incluez la version de la CLI, le harnais, l'environnement, l'ID de session ou de déploiement concerné, ainsi que la sortie de `failproofai config --status` avec les secrets supprimés. \ No newline at end of file diff --git a/docs/fr/sessions/live-events.mdx b/docs/fr/sessions/live-events.mdx index 71c6558e6..f455c5ba2 100644 --- a/docs/fr/sessions/live-events.mdx +++ b/docs/fr/sessions/live-events.mdx @@ -4,7 +4,7 @@ description: "Observez l'activité de l'agent en temps réel pendant qu'une sess icon: "radio" --- -Les événements en direct vous permettent de valider l'instrumentation et de surveiller une exécution à risque sans attendre la fin de la session. +Les événements en direct vous permettent de confirmer l'instrumentation et de surveiller une exécution à risque sans attendre la fin de la session. ## Surveiller l'activité @@ -13,9 +13,9 @@ Les événements en direct vous permettent de valider l'instrumentation et de su 1. Accédez à **Observe → Events**. 2. Commencez avec la fenêtre temporelle actuelle sans filtres pour confirmer que les données arrivent. 3. Filtrez par environnement, type d'événement, agent ou session. Utilisez la recherche pour le texte des charges utiles. - 4. Sélectionnez un événement pour inspecter son résumé et ses détails. Suivez le lien de la session pour obtenir la trace complète. + 4. Sélectionnez un événement pour en inspecter le résumé et les détails. Suivez le lien de sa session pour accéder à la trace complète. - ![Le flux d'événements en direct affichant le trafic d'une passerelle de chat Hermes aux côtés d'exécutions de l'interface CLI de programmation, filtré par heure, environnement, type d'événement, agent, modèle, contexte et session.](/images/dashboard/events-stream-current.png) + ![Le flux d'événements en direct affichant le trafic d'une passerelle de chat Hermes aux côtés d'exécutions de l'interface CLI de codage, filtré par heure, environnement, type d'événement, agent, modèle, contexte et session.](/images/dashboard/events-stream-current.png) ```bash @@ -24,17 +24,17 @@ Les événements en direct vous permettent de valider l'instrumentation et de su fp --json events --full --session-id --all ``` - Le flux par défaut omet les charges utiles brutes. N'utilisez `--full` que pour l'investigation d'une session délimitée. + Le flux par défaut omet les charges utiles brutes. N'utilisez `--full` que pour une investigation ciblée sur une session délimitée. Utilisez le flux d'événements pour répondre à trois questions immédiates : -- L'agent attendu rapporte-t-il au bon environnement ? -- Les appels de modèle, les appels d'outils et les décisions de politique arrivent-ils dans l'ordre ? +- L'agent attendu envoie-t-il ses données au bon environnement ? +- Les appels de modèle, les appels d'outil et les décisions de politique arrivent-ils dans l'ordre ? - La session a-t-elle cessé de progresser ou a-t-elle commencé à répéter une action ? -Les types d'événements comprennent les événements du cycle de vie de l'agent, les requêtes et réponses du modèle, l'utilisation des outils et leurs résultats, l'exécution des hooks, les attentes et interruptions humaines, ainsi que les erreurs explicites. Les identifiants de corrélation relient les événements appariés, comme un appel d'outil et son résultat. +Les types d'événements incluent les événements du cycle de vie de l'agent, les requêtes et réponses du modèle, l'utilisation des outils et leurs résultats, l'exécution des hooks, les attentes et interruptions humaines, ainsi que les erreurs explicites. Les identifiants de corrélation relient les événements associés, comme un appel d'outil et son résultat. Gardez la vue en direct large lors de la vérification d'une nouvelle intégration. N'ajoutez des filtres qu'après avoir vu le premier événement ; un filtre incorrect peut ressembler à un échec d'ingestion. @@ -42,4 +42,4 @@ Les types d'événements comprennent les événements du cycle de vie de l'agent Si aucun événement n'apparaît, exécutez `failproofai config --status`, puis [résolvez les problèmes d'ingestion](/fr/reference/troubleshooting). -Les agents qui ne s'exécutent pas dans l'un des 12 [harnais](/fr/reference/harnesses) pris en charge rapportent les mêmes types d'événements via le [SDK Python](/fr/reference/custom-agents), y compris les événements de supervision humaine (`human_wait`, `human_input`, `human_interrupt`) dont dépendent les agents de passerelle et de production. \ No newline at end of file +Les agents qui ne s'exécutent pas dans l'un des 12 [harnais](/fr/reference/harnesses) pris en charge rapportent les mêmes types d'événements via le [SDK Python](/fr/reference/custom-agents), y compris les événements human-in-the-loop (`human_wait`, `human_input`, `human_interrupt`) dont dépendent les agents de passerelle et de production. \ No newline at end of file diff --git a/docs/fr/start/first-policy.mdx b/docs/fr/start/first-policy.mdx index f953bc04e..4103ffc4e 100644 --- a/docs/fr/start/first-policy.mdx +++ b/docs/fr/start/first-policy.mdx @@ -1,33 +1,33 @@ --- -title: "Évitez votre premier incident avec une politique" -description: "Rédigez une version de politique, déployez-la en mode observation, puis appliquez-la." +title: "Prévenez votre première défaillance avec une politique" +description: "Créez une version de politique, déployez-la en mode observation, puis appliquez-la." icon: "shield-check" --- -N'utilisez une politique qu'une fois que vous êtes en mesure de décrire l'action non sécurisée et les actions légitimes qui doivent rester autorisées. +N'utilisez une politique qu'après avoir clairement identifié l'action non sécurisée et les actions légitimes qui doivent rester autorisées. - - Accédez à **Admin → éditeur de politiques**. Commencez par la politique de démonstration, examinez ou modifiez son code source, puis sélectionnez **publier la version**. La publication crée la version immuable que vous pouvez déployer sur les machines. + + Accédez à **Admin → éditeur de politiques**. Partez de la politique de démonstration, examinez ou modifiez son code source, puis sélectionnez **publier la version**. La publication crée la version immuable que vous pouvez déployer sur les machines. - ![L'éditeur de politiques en mode composition avec une politique de démonstration prête à être publiée en tant que version immuable.](/images/dashboard/policy-editor.png) + ![La vue de composition de l'éditeur de politiques avec une politique de démonstration prête à être publiée en tant que version immuable.](/images/dashboard/policy-editor.png) - - Accédez à **Admin → application**, développez la machine cible, puis sélectionnez **modifier cette machine**. Ajoutez la politique de démonstration publiée, épinglez sa version, choisissez **observer**, et appliquez le déploiement. + + Accédez à **Admin → application**, développez la machine cible et sélectionnez **modifier cette machine**. Ajoutez la politique de démonstration publiée, épinglez sa version, choisissez **observer**, puis appliquez le déploiement. - ![L'éditeur de déploiement de machine avec une version de politique publiée sélectionnée en mode observation avant l'application du déploiement.](/images/dashboard/enforcement-editor.png) + ![L'éditeur de déploiement machine avec une version de politique publiée sélectionnée en mode observation avant d'appliquer le déploiement.](/images/dashboard/enforcement-editor.png) - - Lancez une nouvelle session d'agent sur cette machine, puis ouvrez **Observer → politique**. Sélectionnez la machine et confirmez que la politique de démonstration apparaît dans la cartographie des politiques et la chronologie des décisions. Le mode observation enregistre ce que la politique ferait sans bloquer l'action. + + Lancez une nouvelle session d'agent sur cette machine, puis ouvrez **Observer → politique**. Sélectionnez la machine et confirmez que la politique de démonstration apparaît dans le mappage des politiques et la chronologie des décisions. Le mode observation enregistre ce que la politique ferait sans bloquer l'action. - ![La page Politique affichant les totaux de décisions, l'activité d'application dans le temps, ainsi que les cartographies de politiques locales et gérées par le Cloud.](/images/dashboard/policy-observe.png) + ![La page Politique affichant le total des décisions, l'activité d'application dans le temps et les mappages de politiques locaux et gérés dans le cloud.](/images/dashboard/policy-observe.png) - La rédaction de politiques Cloud et le déploiement sur une flotte sont des flux de travail d'administration. Utilisez le CLI local pour valider la même politique avant de la publier : + La création de politiques cloud et le déploiement sur une flotte sont des workflows d'administration. Utilisez le CLI local pour valider la même politique avant de la publier : ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -35,13 +35,13 @@ N'utilisez une politique qu'une fois que vous êtes en mesure de décrire l'acti failproofai config --status ``` - Utilisez `fp` pour inspecter les décisions de politique visibles dans le Cloud : + Utilisez `fp` pour inspecter les décisions de politique visibles depuis le cloud : ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - Le CLI Cloud n'expose pas les routes de déploiement d'application réservées aux administrateurs. Publiez les versions depuis **Admin → éditeur de politiques** et déployez-les depuis **Admin → application**. + Ces deux étapes sont également disponibles depuis le CLI : `fp policies publish ` crée une version et `fp fleet deploy --add ` la déploie sur une machine. Les équivalents dans le tableau de bord sont **Admin → éditeur de politiques** et **Admin → application**. \ No newline at end of file diff --git a/docs/fr/start/integrations.mdx b/docs/fr/start/integrations.mdx new file mode 100644 index 000000000..9ba863784 --- /dev/null +++ b/docs/fr/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "Instrumentez votre agent" +sidebarTitle: "Frameworks" +description: "Connectez n'importe quel framework d'agent supporté à Failproof AI en un seul appel." +icon: "plug" +--- + +Votre agent produit déjà tout ce qui mérite d'être enregistré — appels de modèle, appels d'outils, limites de nœuds, attentes humaines, échecs. Le framework les jette. Le SDK les conserve. + + + + Un agent que vous avez écrit vous-même, ou un agent qui ne figure pas dans cette liste. + + + Graphes, nœuds, outils, retrievers, modèles. + + + Crews, flows, agents par rôle, outils. + + + Workflows, étapes, agents de fonction, retrievers. + + + Agents typés, capacités, outils, tentatives. + + + +## Trois lignes, quel que soit le framework + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # détecte les frameworks que vous avez importés + +with failproofai_sdk.session(): + ... # votre appel d'agent existant, inchangé +``` + +Pas de décorateurs sur vos fonctions, pas de callback passé à vos appels, pas d'identifiants propagés dans votre code. Seul l'appel à l'intérieur de la session diffère : + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # sous `async with failproofai_sdk.session():` + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +L'installation supplémentaire ajoute le **framework**. Chaque adaptateur est inclus dans le wheel de base, donc un projet qui dispose déjà de son framework n'a besoin d'aucune installation supplémentaire. + +## Vérifier que les données sont bien reçues + +Exécutez une session instrumentée, puis ouvrez **Observe → Sessions** et sélectionnez votre environnement. L'exécution apparaît sous forme de trace reconstruite. + +Si rien n'arrive, vérifiez que la machine est connectée avec `failproofai config --status`. Consultez [Configurer la capture](/fr/start/setup). + + + Ne vérifiez pas le répertoire spool pour confirmer la livraison. Le daemon Failproof collecte et supprime chaque lot en quelques millisecondes, donc lire ce répertoire entre en compétition avec le collecteur et affiche bien moins d'événements que ce qui a été émis. + + +## Étape suivante + +Chaque démarrage rapide ci-dessus renvoie à son guide complet — ce qui est enregistré, les options, le streaming, le nommage des spans, et les problèmes que les gens rencontrent réellement. Ils se trouvent sous **Trace Agents → Plug in your agent**. + + + + Le modèle de données, les identifiants, les types d'événements, et comment les événements atteignent le Cloud. + + + Suivez la causalité à travers une session plutôt que des logs déconnectés. + + + Auditez les sessions que vous venez de capturer. + + \ No newline at end of file diff --git a/docs/fr/start/integrations/crewai.mdx b/docs/fr/start/integrations/crewai.mdx new file mode 100644 index 000000000..93074cf0c --- /dev/null +++ b/docs/fr/start/integrations/crewai.mdx @@ -0,0 +1,224 @@ +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "Instrumentez les crews, flows, agents par rôle, outils, mémoire et retours humains." +icon: "/images/frameworks/crewai.svg" +--- + +## Installation + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +Versions supportées : `crewai` 1.13 à 2.0. La version 1.13 est celle qui a introduit `started_event_id` et normalisé l'utilisation des tokens, deux éléments dont l'adaptateur dépend pour associer les événements et rapporter les tokens. + +## Instrumentation + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` enregistre un écouteur sur le bus d'événements de niveau module de CrewAI et abonne un gestionnaire par classe d'événement. Votre crew, vos agents, vos tâches et vos outils restent inchangés. + +## Ce qui est enregistré + +| CrewAI | Événement Failproof | +| --- | --- | +| Démarrage du crew | `agent_start`, `agent_end` | +| `Agent.kickoff()` (agent léger, sans crew) | `agent_start`, `agent_end`, avec `agent_id` issu du rôle | +| Démarrage et fin d'un flow | `agent_start`, `agent_end` ; un crew démarré dans une méthode de flow s'imbrique sous celui-ci | +| Exécution d'un agent | `agent_start`, `agent_end` imbriqués, avec `agent_id` issu du rôle. Dans un processus hiérarchique, un collaborateur délégué s'imbrique sous le manager et non à côté | +| Tâche | Rien ; enregistrée comme lien pour que les enfants se rattachent au crew | +| Méthode de flow, guardrail | `hook_triggered`, `hook_completed` | +| Utilisation d'un outil | `tool_use`, `tool_result` | +| Opérations de mémoire et de connaissance | `tool_use`, `tool_result`, nommés selon la surface touchée | +| Appel LLM | `model_request`, `model_response`, avec utilisation des tokens | +| Fragment de stream | Fusionné dans la réponse sous forme de nombre de fragments et de temps jusqu'au premier token | +| Retour humain demandé | `human_wait`, `agent_pause` | +| Retour humain reçu | `agent_resume`, `human_input` | +| Erreur d'exécution d'un agent | `error`, puis `agent_end` avec le résultat `failed` | + +Une tâche n'émet délibérément aucun événement. Une tâche CrewAI est un sous-ensemble de l'exécution de l'agent qui la traite ; émettre les deux doublerait chaque ligne et les rendrait comme des éléments frères. L'identifiant et le nom de la tâche sont transmis avec les propres événements de l'agent. + +Les opérations de mémoire et de connaissance sont enregistrées comme des outils, nommés selon la surface qu'elles touchent, afin d'apparaître à côté de vos vrais outils et de permettre la comparaison de leur latence. + +Dans un crew hiérarchique, l'imbrication est ce qui rend la trace lisible : + +```text +crew +└─ manager + ├─ researcher délégué + └─ writer délégué +``` + +CrewAI rattache une exécution déléguée à l'événement d'**outil** `delegate_work_to_coworker`, et non directement au manager ; l'adaptateur suit donc ce lien. Sans cela, chaque agent apparaîtrait comme frère de tous les autres et la structure de délégation serait perdue. + +## Exemple + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # devient agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +La passation est visible dans la trace : le span `analyst` se ferme, le span `writer` s'ouvre, et les deux se trouvent à l'intérieur d'un même span `crew`. + +## Nommez vos spans + +`agent_id` provient de `Agent(role=...)`, ce qui en fait une facette lisible dans le tableau de bord. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # une entrée de facette par exécution +``` + +`agent_id` est une colonne à faible cardinalité. Un rôle contenant un identifiant d'exécution ou un horodatage la dégrade pour toutes les requêtes. Si un rôle ressemble à un identifiant, l'adaptateur le refuse et place la valeur réelle dans un champ de payload. + +## Contrôler la session + +Résolution dans cet ordre, avec le premier résultat retenu : + +1. `instrument("crewai", session_id=...)` +2. Le scope `failproofai_sdk.session()` englobant +3. Un `uuid4().hex` généré, une fois par crew ou flow + +Enveloppez le kickoff pour le contrôler par exécution : + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## Options + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # fixe chaque exécution à un identifiant de session +) +``` + +`session_id` est la seule option que cet adaptateur prend en compte. Les prompts et les complétions sont toujours enregistrés, tronqués selon le budget du payload. + +## Humain dans la boucle + +CrewAI dispose de **deux** surfaces d'interaction humaine dans la boucle, toutes deux enregistrées sous les quatre mêmes événements. + +`@human_feedback` sur une méthode de flow passe par le bus d'événements de CrewAI : le runtime émet un événement avant de bloquer en attendant une réponse humaine, puis un autre après. + +`Task(human_input=True)` ne le fait pas. Cette option appelle `input()` dans le propre fournisseur d'entrée de CrewAI sans émettre aucun événement, c'est pourquoi l'adaptateur enveloppe directement ce fournisseur — sans quoi l'attente humaine était invisible et comptée comme du temps actif de l'agent. + +Dans les deux cas, vous obtenez : + +```text +human_wait le prompt et ses options +agent_pause démarre le chronomètre de temps en pause +agent_resume l'arrête +human_input la réponse, avec le temps d'attente mesuré +``` + +La paire `agent_pause` / `agent_resume` est la seule qui alimente le temps en pause. Sans elle, une attente humaine de dix minutes est comptabilisée comme dix minutes de temps actif de l'agent. + + + CrewAI n'associe aucun identifiant de corrélation aux événements de retour humain ; l'adaptateur les apparie donc sur le nom du flow et de la méthode, en se rabattant sur la pause ouverte la plus récente. Cela est fiable car une invite console bloque l'exécution. Si vous construisez un fournisseur de retour concurrent, définissez `request_id` sur les deux événements. + + + + Comme le chemin `Task(human_input=True)` est un wrapper autour du fournisseur d'entrée de CrewAI plutôt qu'un abonnement à un événement, il est restauré lors de `uninstrument()` et propage telles quelles toutes les exceptions levées par `input()`, y compris `KeyboardInterrupt`. + + +## Problèmes courants + + + + Un `role` contient un UUID, un horodatage ou un suffixe propre à une exécution. Utilisez un rôle humain stable et placez l'identifiant spécifique à l'exécution dans la description de la tâche. + + + + Le bus d'événements est asynchrone et `kickoff()` retourne avant que les derniers gestionnaires aient été exécutés. Videz-le d'abord : + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + Il s'agit d'un comportement propre à CrewAI, non au SDK. + + + + `agent_end` force la fermeture des pauses ouvertes, mais pas des outils ni des modèles ; une exécution qui se termine au milieu d'un appel d'outil laisse donc ce span ouvert. Un arrêt normal ferme tout ce qui est encore ouvert et le marque comme incomplet. Seul un `SIGKILL` laisse un span en suspens, car rien ne peut s'exécuter. + + + + Vérifiez dans cet ordre : `instrument()` a été appelé avant `kickoff()` ; un `with failproofai_sdk.session():` l'englobe ; `crewai` est en version 1.13 ou supérieure ; `FAILPROOFAI_SDK_STRICT=1` est défini pour qu'un hook dégradé lève une exception plutôt que d'être ignoré silencieusement. + + + +## Étapes suivantes + + + + Paires, identifiants, cycle de vie des sessions et livraison. + + + Suivez la causalité dans la session que vous venez de capturer. + + + LangGraph, LlamaIndex, Pydantic AI et agents personnalisés. + + \ No newline at end of file diff --git a/docs/fr/start/integrations/custom-agents.mdx b/docs/fr/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..0fd0f1cd0 --- /dev/null +++ b/docs/fr/start/integrations/custom-agents.mdx @@ -0,0 +1,737 @@ +--- +title: "Agents personnalisés" +sidebarTitle: "Agents personnalisés" +description: "Instrumentez un agent que vous avez écrit 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. + +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 + +```bash +pip install failproofai-sdk +``` + +Aucun extra, aucune dépendance. + +## Instrumentation + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # une exécution + with failproofai_sdk.agent("planner"): # une unité de travail + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) # un appel d'outil +``` + +Lisez-le de haut en bas et il dit ce qu'il signifie : + +| À encadrer | 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é | + +Et ce que chacun émet réellement : + +| Portée | Émet | Objectif | +| --- | --- | --- | +| `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 | + +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 avec `async with` comme avec `with`. + +L'imbrication d'agents construit l'arbre. `parent_id` et la profondeur sont calculés à partir de la pile : + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## Comment une portée se ferme + +`agent()` gère les exceptions pour vous : + +| Ce qui s'est passé | Événements | Résultat | +| --- | --- | --- | +| Aucune exception levée | `agent_end` | `success` | +| `Exception` | `error`, puis `agent_end` | `failed` | +| `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. + +## 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. + +| Famille | Ouvre | Ferme | Autonome | +| --- | --- | --- | --- | +| **Agents** | `agent_start` | `agent_end` | — | +| | `agent_pause` | `agent_resume` | — | +| **Modèles** | `model_request` | `model_response` | — | +| **Outils** | `tool_use` | `tool_result` | — | +| **Hooks** | `hook_triggered` | `hook_completed` | — | +| **Humains** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **É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. + + + +```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 Models +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 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 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 Failures +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **Les deux familles humaines pointent dans des directions opposées.** + + | Méthodes | Signification | + | --- | --- | + | `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. + + + + **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'appel d'outils contre l'API OpenAI, sans framework d'agent : + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +MODEL = "gpt-4o-mini" + + +def turn(messages: list): + """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 + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +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 + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +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 + +Les variables de contexte se propagent automatiquement dans les tâches asyncio. Elles ne se propagent pas dans les nouveaux threads, car un thread démarre avec un contexte vide. + +```python +# asyncio : rien à faire +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# 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 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 + +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'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 + 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(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **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. + + + + **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'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, ce qui fait qu'instrumenter AG2 implique d'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. + + +## Aller plus loin + +Comment l'enregistrement fonctionne réellement. Rien de tout cela n'est nécessaire pour démarrer. + + + + + +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 + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + 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. + +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. + + + + ```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 out-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 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. + + + + ```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 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 out-tok + 9 +5.727s agent_end analyst · success + 10 +5.739s agent_end crew · success + ``` + + Le `role` de chaque agent devient son nom de span, la latence et la consommation de tokens se décomposent donc par rôle. + + + + ```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 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 + ... deuxième itération + 26 +7.038s agent_end Agent · success + ``` + + La boucle de l'agent elle-même est visible, pas seulement ses appels de modèles. + + + + ```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 + 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 + 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. + + + + ```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 out-tok + 6 +0.000s agent_end main · success + ``` + + Vous émettez ceux-ci vous-même. Mêmes types d'événements, même fidélité — cela vous coûte les sites d'appel. + + + + + + + +**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érivé de la forme de la trace : + +| Statut | Quand | +| --- | --- | +| `ongoing` | Au moins un span est encore ouvert | +| `paused` | Un `agent_pause` n'a pas de `agent_resume` correspondant | +| `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. + + + 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. S'ils sont omis, ils sont résolus depuis la portée englobante : + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + 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 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 + +| Id | Créé 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` | +| `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 | + +#### Comment les adaptateurs résolvent `session_id` + +Le premier match 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 + +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 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` | 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` | Idem | + +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 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 | +| --- | --- | +| Agents | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| Modèles | `model_request`, `model_response` | +| Outils | `tool_use`, `tool_result` | +| Hooks | `hook_triggered`, `hook_completed` | +| Humains | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| Échecs | `error` | + +Quel framework enregistre quoi, mesuré depuis les exécutions ci-dessus : + +| Événement | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | +| --- | :--: | :--: | :--: | :--: | :--: | +| Démarrage et fin d'agent | Oui | Oui | Oui | Oui | Vous | +| Requête et réponse de modèle | Oui | Oui | Oui | Oui | Vous | +| 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 | +| 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. + + + + + +Un événement n'arrive jamais seul. Un ouvre un span, un le ferme, et l'événement de fermeture porte une durée que le SDK mesure depuis l'événement d'ouverture. + +| Ouvre | Ferme | L'événement de fermeture porte | +| --- | --- | --- | +| `agent_start` | `agent_end` | `outcome`, `summary` | +| `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 | + + + 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 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 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. + + + + + +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, 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'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() # tous les frameworks déjà importés +failproofai_sdk.instrument("crewai") # exactement un, par nom +failproofai_sdk.uninstrument("crewai") # le remettre comme avant +``` + +| Nom | Accepte aussi | +| --- | --- | +| `langchain` | `langgraph`, `langchain_core` | +| `crewai` | — | +| `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é : + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +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. + + 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 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 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 `()`. + + + +```python Wrong +import failproofai_sdk +failproofai_sdk.instrument() # sys.modules n'a pas encore langchain -> () + +import langchain # trop tard, rien n'est câblé +``` + +```python Right +import langchain # importer le framework en premier +import failproofai_sdk + +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ù. +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. + + + + + +```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"] + 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 | + +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 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 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. + + +Le daemon **envoie** vos batches. Il ne les ouvre ni ne les réécrit. + +| Événements | Écrits par | Traités par `collector.redact` ? | +| --- | --- | --- | +| Transcriptions de sessions CLI | Le daemon | Oui | +| Activité des hooks | Le daemon | Oui | +| **Tout ce que le SDK émet** | **Votre processus** | **Non** | + +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, 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` + - LlamaIndex — `capture_messages=False` + - 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. + + `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 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. + + + + + +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 | +| --- | --- | +| Un hook lève une exception | Enregistré une fois avec sa trace. Votre appel n'est pas affecté | +| Le même hook lève trois fois | Ce hook est désactivé pour le reste du processus, avec une ligne d'erreur | +| `FAILPROOFAI_SDK_STRICT=1` est défini | L'exception est re-levée à la place | +| 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é. + + + + + +## Problèmes courants + + + + 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, 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 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 id d'exécution. Utilisez un nom de rôle ou de nœud et mettez le vrai id dans un champ de payload. + + + +## Étapes suivantes + + + + Paires, ids, cycle de vie des sessions et livraison. + + + Suivez la causalité à travers la session que vous venez de capturer. + + + LangGraph, CrewAI, LlamaIndex et Pydantic AI. + + \ No newline at end of file diff --git a/docs/fr/start/integrations/langchain.mdx b/docs/fr/start/integrations/langchain.mdx new file mode 100644 index 000000000..0a2fc074c --- /dev/null +++ b/docs/fr/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain and LangGraph" +sidebarTitle: "LangChain and LangGraph" +description: "Instrumentez graphes, nœuds, outils, retrievers et appels de modèles en un seul appel." +icon: "/images/frameworks/langchain.svg" +--- + +Un seul adaptateur pour les deux. LangGraph s'appuie sur le gestionnaire de callbacks de `langchain-core`, donc instrumenter l'un instrumente automatiquement l'autre. + +## Installation + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Pour LangChain sans LangGraph, utilisez `failproofai-sdk[langchain]`. + +Versions supportées : `langchain-core` 1.4.7 à 2.0, `langgraph` 1.2 à 2.0. En dehors de cette plage, l'adaptateur s'installe quand même et émet un avertissement unique. + +## Instrumentation + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` enregistre un tracer via `langchain_core.tracers.context.register_configure_hook`. LangChain l'injecte dans chaque gestionnaire de callbacks qu'il crée, ce qui permet de capturer graphes, outils et modèles sans modifier un seul point d'appel — y compris ceux au sein de bibliothèques tierces. + +## Ce qui est enregistré + +| LangChain ou LangGraph | Événement Failproof | +| --- | --- | +| Exécution racine | `agent_start`, `agent_end` | +| Nœud LangGraph | `hook_triggered`, `hook_completed` | +| Sous-graphe compilé | `agent_start`, `agent_end` imbriqués | +| Exécution d'outil | `tool_use`, `tool_result` | +| Exécution de retriever | `tool_use`, `tool_result`, sortie résumée | +| Chat model ou LLM | `model_request`, `model_response`, avec comptage de tokens | +| Tokens en streaming | Regroupés dans la réponse sous forme de nombre de chunks et de temps jusqu'au premier token. Le comptage de tokens nécessite `ChatOpenAI(stream_usage=True)` — voir ci-dessous | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, corrélés sur l'`Interrupt.id` — y compris lorsque la reprise s'effectue dans un processus différent sur le même checkpointer | +| Exception non gérée | `error`, puis `agent_end` avec l'issue `failed` | + +**Un nœud devient un hook, pas un agent imbriqué.** `agent_id` est la facette principale sur toutes les vues du tableau de bord — promouvoir `retrieve`, `grade_documents` et `should_continue` en agents noierait cette facette et étiquerait la session d'après le nœud exécuté en premier. + +Les spans de hooks s'affichent de la même manière et offrent quand même une vue de latence par nœud. + + + **Nommez vos nœuds comme vous le souhaitez.** L'exécution d'un nœud est identifiée par sa *forme* — une exécution non-feuille portant le tag de step LangGraph — jamais par son nom. + + +| Ce que vous écrivez | Ce qui est enregistré | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | L'outil | +| `add_node("ChatOpenAI", ...)` | L'appel au modèle | + +Nommer un nœud d'après ce qu'il exécute faisait autrefois disparaître les événements de cet élément. Ce n'est plus le cas. + +### Streaming + +`.stream()` et `.astream()` n'émettent aucun événement par token. Ils sont regroupés dans le `model_response` final : + +| Champ | Contenu | +| --- | --- | +| `fw_chunks` | Nombre de chunks reçus | +| `fw_ttft_ms` | Temps jusqu'au premier token | + +### Comptage de tokens sur une réponse streamée + +Point distinct, facile à manquer : OpenAI n'envoie l'usage sur une réponse streamée **que si on le lui demande explicitement**. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # without this, no tokens +``` + +L'adaptateur enregistre ce que le framework lui transmet. Sans ce flag, il n'y a rien à enregistrer, et `model_response` arrive sans comptage de tokens. + +## Exemple + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## Nommer vos spans + +Par défaut, le span racine prend le nom propre du graphe. Enveloppez-le pour lui attribuer le libellé de votre choix : + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +Pour les configurations multi-agents, imbriquez les scopes. Chaque worker devient un span enfant portant un `parent_id` : + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +Gardez `agent_id` à faible cardinalité. Utilisez un rôle ou un nom de nœud, jamais un UUID ou une chaîne générée à chaque exécution. + +## Contrôler la session + +L'identifiant de session est résolu dans cet ordre, la première correspondance l'emportant : + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. Le scope englobant `failproofai_sdk.session()` +4. `metadata["session_id"]`, `metadata["conversation_id"]`, ou `metadata["thread_id"]` +5. L'identifiant de l'exécution racine + +Il n'est jamais généré de toutes pièces, car un identifiant synthétisé fragmenterait une exécution en plusieurs sessions. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## Options + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # pin every run to one session id + include_chains=set(), # allowlist intermediate chains as hook pairs + capture_content=True, # False drops prompts and completions from payloads + graph_callbacks=True, # first-class interrupt and resume, needs langgraph 1.2+ +) +``` + +Définissez `capture_content=False` pour les données réglementées. La structure, les timings, les comptages de tokens, les noms d'outils et les issues sont toujours enregistrés ; les corps de messages ne le sont pas. + +`include_chains` s'applique uniquement aux exécutions **imbriquées**. Un runnable invoqué au niveau supérieur est la racine de la session — il devient donc le span agent plutôt qu'une paire de hooks, et le nommer ici n'a aucun effet. + +## Human in the loop + +`interrupt()` produit quatre événements, et aucune paire n'est redondante : + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +De `human_wait` à `human_input`, la paire transporte la question et la réponse (toutes deux supprimées avec `capture_content=False`, ainsi que les sources des documents de retrieval — le nombre de documents est conservé). La paire `agent_pause` vers `agent_resume` est la seule qui alimente le temps en pause ; sans elle, une attente humaine de dix minutes est comptabilisée comme temps actif de l'agent. Le span racine reste ouvert entre les deux appels, les maintenant dans une même session. + +## Problèmes courants + + + + `create_react_agent` propage l'exception. Pour que le modèle voie l'échec et puisse continuer, construisez le nœud d'outil explicitement : + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + L'échec est enregistré comme un `tool_result` portant une erreur dans les deux cas. Ce paramètre décide uniquement si l'exécution survit à l'erreur. + + + + Un appel direct `llm.invoke()` en dehors de tout graphe n'a pas d'exécution parente, il ouvre donc un span racine et émet sa paire de modèle à l'intérieur. Le tableau de bord rattache les feuilles à un agent ouvert, ce span est donc intentionnel. Nommez-le : + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + Vous avez passé un handler Failproof dans `config={"callbacks": [...]}` tout en appelant `instrument()`. Supprimez-le. Le configure hook couvre déjà tous les gestionnaires de callbacks du processus. + + + + Ce n'est pas le cas. LangGraph lève `GraphInterrupt` par le même chemin qu'une vraie exception, donc chaque pause atteint le tracer comme un callback d'erreur. Toute sous-classe de `GraphBubbleUp` est traitée comme un flux de contrôle, donc une approbation n'est pas marquée en rouge. + + + + Vérifiez dans cet ordre : `instrument()` a été appelé avant l'exécution du graphe ; il y a un `with failproofai_sdk.session():` autour de l'appel ; `FAILPROOFAI_SDK_STRICT=1` est défini, ce qui fait qu'un hook dégradé lève une exception au lieu d'être ignoré silencieusement. + + + +## Étapes suivantes + + + + Paires, identifiants, cycle de vie de session et livraison. + + + Suivez la causalité à travers la session que vous venez de capturer. + + + CrewAI, LlamaIndex, Pydantic AI et agents personnalisés. + + \ No newline at end of file diff --git a/docs/fr/start/integrations/llamaindex.mdx b/docs/fr/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..51c96e5dc --- /dev/null +++ b/docs/fr/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "Instrumentez les workflows, les étapes, les agents fonctionnels et les retrievers." +icon: "/images/frameworks/llamaindex.svg" +--- + +## Installation + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +Versions supportées : `llama-index-core` 0.14.23 à 0.15. La version 0.14.23 est celle où le stream de workflow a commencé à transporter les événements d'agent typés que cet adaptateur lit. En dessous, les noms de modèles et la structure de l'agent disparaissent tous les deux. + +## Instrumentation + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +L'API agent de LlamaIndex est asynchrone. Chaque scope fonctionne avec `async with` aussi bien qu'avec `with` et produit des événements identiques. + +`instrument()` attache un gestionnaire d'événements et un gestionnaire de spans au dispatcher global de LlamaIndex. Ensemble, ils rendent la boucle agent visible, pas seulement ses appels au modèle. + + + Sans un argument supplémentaire sur votre LLM, tous les comptages de tokens dans votre trace seront null. Consultez [Comptage de tokens](#token-counts) ci-dessous. + + +## Comptage de tokens + +`FunctionAgent` appelle `astream_chat`, et `llama-index-llms-openai` n'envoie pas `stream_options={"include_usage": True}` lors du streaming. Le fournisseur n'envoie donc jamais le chunk d'utilisation, et il n'y a rien à lire pour aucune instrumentation. + +Il s'agit d'un comportement LlamaIndex en amont. Activez l'option sur votre LLM : + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +Mesuré sur la même exécution et le même modèle : + +| | Tokens en entrée | Tokens en sortie | +| --- | --- | --- | +| Sans | `null` | `null` | +| Avec | 148 | 17 | + +Les appels non-streaming (`llm.chat`, `llm.achat`) rapportent l'utilisation sans configuration. Seul le chemin streaming, qui est le chemin agent par défaut, en a besoin. + +## Ce qui est enregistré + +| LlamaIndex | Événement Failproof | +| --- | --- | +| Span racine `Workflow.run` | Session, `agent_start`, `agent_end` | +| Span `Workflow.run` imbriqué | `agent_start`, `agent_end` imbriqués | +| Span d'étape de workflow | `hook_triggered`, `hook_completed` | +| Début et fin de chat LLM | `model_request`, `model_response` | +| Span `FunctionTool.call` | `tool_use`, `tool_result` | +| Début et fin de retrieval | `tool_use`, `tool_result`, sortie résumée | +| Embeddings | Rien, sauf si `embeddings=True` | +| Un outil en attente d'une personne | `human_wait`, `agent_pause`, puis `agent_resume`, `human_input` | +| Transfert `AgentWorkflow` | Un `agent_start`, `agent_end` imbriqué par agent, rattaché au workflow | +| Exception | `error`, puis `agent_end` avec outcome `failed`, et `agent_end.summary` le nommant | +| `handler.cancel_run()` | `agent_end` avec outcome `cancelled` et sans `error` — un bouton stop n'est pas un échec | + +`agent_id` correspond au `FunctionAgent.name` si vous en définissez un, sinon au nom de la classe du workflow. Sous un `AgentWorkflow`, chaque agent qui prend un tour obtient sa propre span imbriquée sous le workflow, de sorte qu'un transfert se lit comme deux agents plutôt qu'un. + +La sortie du retrieval est résumée plutôt que vidée. Un retriever retourne des documents, et les stocker dans le payload mettrait votre corpus dans le store d'événements à chaque requête. Le nombre, la plage de scores et des extraits tronqués sont conservés à la place. + +## Exemple + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +La boucle agent apparaît dans la trace sous forme de paires de hooks : `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool` et `aggregate_tool_results`. Ce sont les boucles propres au framework, donc ce sont des hooks plutôt que des agents, ce qui permet à `agent_id` de rester significatif. + +## Nommez vos spans + +`agent_id` correspond au `FunctionAgent.name` si vous en définissez un, sinon au nom de la classe du workflow. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +Dans un `AgentWorkflow`, ce nom est également celui sous lequel chaque transfert est enregistré : + +```text +AgentWorkflow span parente +├─ city_analyst tour 1 +├─ cost_analyst tour 2 +└─ city_analyst tour 3 — un nouveau tour, pas une réouverture +``` + +Ainsi, `agent_id` indique **quel agent** a effectué le travail et `parent_id` indique **à quel workflow** il appartenait. Un agent qui a rendu le contrôle ouvre un second tour plutôt que de rouvrir le premier. + +Enveloppez l'exécution pour le remplacer, ou pour regrouper plusieurs agents sous un même parent : + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +Gardez `agent_id` à faible cardinalité. C'est la facette principale sur toutes les surfaces du tableau de bord, donc utilisez un rôle ou un nom de workflow, jamais un UUID ou une chaîne propre à une exécution. + +## Contrôler la session + +Cet adaptateur ne prend **pas d'option `session_id`**. La session provient du scope englobant, sinon un `uuid4().hex` généré par exécution de workflow : + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## Options + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True enregistre les appels d'embedding comme des paires d'outils + steps=True, # False supprime les paires de hooks d'étapes de workflow + capture_messages=True, # False supprime TOUTES les charges utiles : prompts, complétions, + # arguments et sorties des outils, E/S des étapes, requêtes + # de retrieval, l'objectif et la réponse finale + capture_limit=8192, # caractères conservés par valeur capturée + stale_after=600.0, # secondes avant qu'une FEUILLE abandonnée soit forcée à se fermer + reaper_interval=30.0, # fréquence de balayage du reaper ; 0 le désactive +) +``` + +| Option | Pourquoi vous la modifieriez | +| --- | --- | +| `embeddings` | À activer uniquement lors du débogage de la latence ou du coût des embeddings. Une construction d'index en masse représente des milliers d'appels et noiera la timeline. | +| `steps` | À désactiver si vous ne voulez que les événements de modèle et d'outil et trouvez la boucle agent trop verbeuse. | +| `capture_messages` | À désactiver pour les données réglementées. L'enregistrement de toutes les charges utiles s'arrête — prompts, complétions du modèle, arguments et valeurs de retour des outils, entrée et sortie des étapes de workflow, requêtes de retrieval, l'objectif de l'agent et sa réponse finale. La structure, les timings, les tokens et les outcomes sont toujours enregistrés. | +| `capture_limit` | Caractères conservés par valeur capturée avant troncature. Augmentez-le quand un prompt RAG ou un contexte récupéré arrive tronqué. | +| `stale_after` | Secondes avant qu'une **feuille** abandonnée — une réponse streaming que personne n'a consommée, une span de modèle ou d'outil dont la fermeture n'est jamais arrivée — soit forcée à se fermer, afin que la session se stabilise au lieu de rester `ongoing` indéfiniment. Cela ne ferme **pas** une exécution abandonnée elle-même : un workflow dont la tâche est annulée sans que le dispatcher voie une sortie garde son `agent_start` ouvert jusqu'à `uninstrument()`. | +| `reaper_interval` | Fréquence de balayage. Définissez à `0` pour désactiver entièrement le reaper. | + +## Humain dans la boucle + +Capturé quand l'attente se produit à l'intérieur d'un outil : + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +`ctx.wait_for_event` dans une étape de workflow classique n'est pas capturé. Le runtime intercepte l'abandon avant qu'il n'atteigne le dispatcher, donc l'étape se termine et se réexécute plus tard sans signal pour déclencher une pause. Le pattern FunctionAgent, que LlamaIndex documente, attend à l'intérieur d'un outil et est capturé entièrement. + +## Problèmes courants + + + + Ajoutez `additional_kwargs={"stream_options": {"include_usage": True}}` à votre LLM. Voir [Comptage de tokens](#token-counts). + + + + LlamaIndex n'a pas de champ d'utilisation standard. L'adaptateur essaie plusieurs formes connues, et une intégration qui nomme ses compteurs différemment ne correspondra à aucune d'elles. + + Le dict brut est toujours transmis, vérifiez donc `usage` dans la charge utile pour voir comment votre fournisseur les a nommés. + + Un `usage` renseigné avec des colonnes de tokens vides est délibéré — c'est préférable à un chiffre erroné affiché avec confiance. + + + + C'est la boucle FunctionAgent, un ensemble par itération. Filtrez par nom de hook sur le tableau de bord. Ces timings d'étapes sont généralement la raison d'utiliser cet adaptateur plutôt qu'un adaptateur modèle uniquement. + + + + Vérifiez dans cet ordre : `instrument()` a été exécuté avant l'exécution ; il y a un `async with failproofai_sdk.session():` autour du `await` ; `llama-index-core` est en version 0.14.23 ou plus récente ; `FAILPROOFAI_SDK_STRICT=1` est défini, de sorte qu'un hook dégradé lève une exception plutôt que d'être ignoré silencieusement. + + + +## Suite + + + + Paires, ids, cycle de vie de session et livraison. + + + Suivez la causalité à travers la session que vous venez de capturer. + + + LangGraph, CrewAI, Pydantic AI et agents personnalisés. + + \ No newline at end of file diff --git a/docs/fr/start/integrations/pydantic-ai.mdx b/docs/fr/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..ded788604 --- /dev/null +++ b/docs/fr/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "Instrumentez les agents typés, les outils, les appels de modèle et les tentatives de réessai." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## Installation + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +Versions supportées : `pydantic-ai-slim` 2.0 à 3.0. La version 2.0 a supprimé `Agent(instrument=...)` et introduit le protocole de capacité sur lequel repose cet adaptateur — la version 1.x ne peut donc pas être instrumentée de cette façon. + +## Instrumentation + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # avant de construire tout Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` doit être exécuté avant la construction d'un `Agent`. La capacité est ajoutée au moment de la construction : un agent créé avant ne disposera d'aucune capacité et n'enregistrera rien, sans aucune erreur puisque rien ne s'est mal passé. C'est la cause la plus fréquente d'une trace vide avec cet adaptateur. + + +Les agents définis au niveau du module sont la source habituelle de ce problème : + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # construit au moment de l'import + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # exécuter CECI EN PREMIER +import agents # l'agent reçoit alors la capacité +``` + +Pour vérifier que l'instrumentation a bien fonctionné : + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI fusionne la liste passée en une unique `root_capability`, il n'existe donc pas d'attribut `agent.capabilities` accessible directement. + +Les agents construits pendant la période d'instrumentation conservent la capacité : vous pouvez appeler `uninstrument()` puis ré-instrumenter sans avoir à les reconstruire. + +## Ce qui est enregistré + +| Pydantic AI | Événement Failproof | +| --- | --- | +| Exécution d'agent | `agent_start`, `agent_end` | +| Requête au modèle | `model_request`, `model_response`, avec l'utilisation des tokens | +| Appel d'outil | `tool_use`, `tool_result`, avec les arguments envoyés par le modèle | +| `ModelRetry` depuis un outil | `tool_result` portant une erreur | +| Exception non gérée | `error`, puis `agent_end` avec le résultat `failed` | + +Il n'y a ni paire de hooks ni paire humain-dans-la-boucle ici. Pydantic AI ne dispose pas de frontière de nœud ou d'étape à délimiter, ni de pause humaine intégrée — il n'y a donc rien à mapper. Si vous en implémentez, émettez les événements vous-même — voir [Agents personnalisés](/fr/reference/custom-agents). + +`output_type` n'a aucune incidence sur la trace. Une exécution typée et une exécution retournant une chaîne produisent les mêmes événements. + +## Exemple + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +Dans la trace, `restock_eta` apparaît comme un `tool_result` portant une erreur, suivi d'un nouvel appel au modèle où l'agent trouve une alternative, et l'exécution se termine tout de même en `success`. Les deux informations sont conservées. + +## Erreurs, réessais et flux de contrôle + +Pydantic AI lève des exceptions pour trois situations distinctes, que l'adaptateur différencie : + +| Exception | Traitement | Résultat | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | Véritable échec d'outil | `tool_result` avec une erreur ; l'exécution peut tout de même se terminer en `success` | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | Flux de contrôle | Pas une erreur ; l'exécution est simplement guidée | +| Toute autre exception | Échec | `error`, puis `agent_end` avec le résultat `failed` | + +`ModelRetry` appartient délibérément au premier groupe. Il indique qu'une tentative a réellement échoué et que le modèle a été invité à réessayer — c'est précisément ce à quoi sert le champ d'erreur d'un span d'outil. Le classifier comme flux de contrôle masquerait de vrais échecs d'outils derrière une exécution affichant un succès. + +## Nommez vos spans + +Le span d'exécution propre à Pydantic AI s'appelle `agent`. Encapsulez l'appel pour lui donner le libellé de votre choix : + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +Le span du framework s'imbrique alors sous `inventory`, et c'est là que se rattachent les événements de modèle et d'outil. + +Gardez `agent_id` à faible cardinalité. C'est la facette principale sur toutes les surfaces du tableau de bord — utilisez un nom de rôle, jamais un UUID ou une chaîne générée par exécution. + +## Contrôler la session + +Résolution dans cet ordre, la première correspondance l'emporte : + +1. `instrument("pydantic_ai", session_id=...)` +2. Le contexte `failproofai_sdk.session()` englobant +3. Le `conversation_id` de l'exécution, puis son `run_id` +4. Un `uuid4().hex` généré automatiquement + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## Options + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # fixer toutes les exécutions à un même identifiant de session + capture_content=True, # False supprime les prompts et completions des payloads +) +``` + +## Problèmes courants + + + + L'`Agent` a été construit avant l'exécution de `instrument()`. Consultez l'avertissement ci-dessus et vérifiez `agent.root_capability.capabilities`. + + + + Un `raise` nu se propage — c'est le comportement voulu par Pydantic AI. Pour permettre au modèle de s'en sortir, levez `ModelRetry` avec un message sur lequel il peut agir. L'échec est enregistré dans tous les cas. + + + + Cet enfant est le span d'exécution propre à Pydantic AI, et c'est là que se rattachent les événements de modèle et d'outil. Supprimez votre propre contexte si vous souhaitez un span unique, au prix du nom personnalisé. + + + + La pile asynchrone de Pydantic AI dépasse la limite du champ de payload, et la dernière ligne d'une trace de pile est l'exception elle-même. Ce champ est rogné depuis le début plutôt que depuis la fin, de sorte que la ligne dont vous avez besoin est préservée. + + + +## Étapes suivantes + + + + Paires, identifiants, cycle de vie des sessions et livraison. + + + Suivre la causalité à travers la session que vous venez de capturer. + + + LangGraph, CrewAI, LlamaIndex et agents personnalisés. + + \ No newline at end of file diff --git a/docs/fr/start/quickstart.mdx b/docs/fr/start/quickstart.mdx index 3f5bd4b59..b3ea096f3 100644 --- a/docs/fr/start/quickstart.mdx +++ b/docs/fr/start/quickstart.mdx @@ -1,27 +1,27 @@ --- title: "Démarrage rapide" -description: "Capturez une session d'agent, identifiez une défaillance et commencez à la prévenir." +description: "Capturez une session d'agent, identifiez un échec et commencez à le prévenir." icon: "zap" --- -Ce démarrage rapide permet de configurer une machine pour qu'elle rapporte des sessions, d'effectuer un audit et de déployer une politique. Utilisez le skill pour configurer Failproof, ou suivez les étapes manuelles. +Ce guide de démarrage rapide vous permet de configurer une machine pour qu'elle transmette 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 aurez besoin de Node.js 20.9 ou version ultérieure. Si votre agent ne dispose pas de harnais, instrumentez-le avec le [SDK Python](/fr/reference/custom-agents) pour le traçage et les audits, puis rejoignez la section [Effectuer votre premier contrôle de défaillance](/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 développement, ou une passerelle comme Hermes ou OpenClaw — suivez les étapes ci-dessous ; vous avez besoin de Node.js 20.9 ou version ultérieure. Si votre agent ne possède 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écutez votre premier contrôle d'échec](/fr/start/first-audit) ; l'application des politiques sur cette voie nécessite un hook dans votre environnement d'exécution. - + - + ```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 la vérifie. 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 vérifie son bon fonctionnement. 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. @@ -45,7 +45,7 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - 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. + Les transcriptions de sessions sont envoyées par défaut. Ajoutez `--no-transcripts` pour transmettre l'activité des hooks et les décisions de politique sans le contenu des transcriptions. 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,28 +57,28 @@ export FAILPROOFAI_KEY="" Ouvrez **Sessions** dans Failproof AI et sélectionnez une session importée. - - Ceci attache Failproof AI à votre harnais et installe les 40 politiques intégrées. Utilisez-les pour observer les décisions de politique locales et tester l'application des règles avant que Failproof AI n'audite vos sessions et n'écrive des politiques pour vos agents. + + Cette étape attache Failproof AI à votre harnais et installe les 40 politiques intégrées. Utilisez-les pour observer 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. Chacun des 12 est une valeur `--cli` valide — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Laissez l'installateur détecter votre harnais automatiquement, ou nommez-en un explicitement. 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 claude --scope user # une CLI de développement 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 portes 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 harnais. Les contrôles 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. - Suivez [Effectuer votre premier contrôle de défaillance](/fr/start/first-audit). Utilisez un objectif concret, par exemple « trouver les sessions où l'agent a réessayé un outil défaillant sans modifier son approche ». + Suivez [Exécutez 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 première défaillance avec une politique](/fr/start/first-policy). Commencez en mode observation, inspectez les correspondances, puis appliquez la version révisée. + + Suivez [Prévenez votre premier échec avec une politique](/fr/start/first-policy). Commencez en mode observation, inspectez les correspondances, puis appliquez la version révisée. - Exécutez `failproofai config --status`. Une configuration saine rapporte la connexion au cloud, l'état du daemon et indique si l'application des politiques est en pause. + Exécutez `failproofai config --status`. Une configuration saine indique la connexion au cloud, l'état du démon et si l'application des politiques est en pause. \ No newline at end of file diff --git a/docs/fr/start/quickstarts/crewai.mdx b/docs/fr/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..c134fba8d --- /dev/null +++ b/docs/fr/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "Installez, instrumentez et observez votre première trace." +icon: "/images/frameworks/crewai.svg" +--- + +Trois étapes pour obtenir votre première trace CrewAI. Pour le détail de chaque événement, les flux et le dépannage, consultez [le guide complet](/fr/start/integrations/crewai). + +## Installer + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## Instrumenter + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +Votre crew, vos agents, vos tâches et vos outils ne changent pas. `instrument()` s'abonne au bus d'événements au niveau du module de CrewAI. + +## Vérifier que ça arrive + +Exécutez-le une fois, puis ouvrez **Observe → Sessions** et sélectionnez votre environnement. Votre exécution apparaît sous forme de trace reconstruite. + +Si rien n'arrive, vérifiez que la machine est connectée avec `failproofai config --status`. + + + Ce qui est enregistré, les flux, l'utilisation des tokens, le nommage des spans, les options et les problèmes courants. + \ No newline at end of file diff --git a/docs/fr/start/quickstarts/custom-agents.mdx b/docs/fr/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..094bac579 --- /dev/null +++ b/docs/fr/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "Agents personnalisés" +description: "Enveloppez votre agent dans trois blocs `with` et il commence à enregistrer." +icon: "code" +--- + +Pour un agent que vous avez écrit vous-même, ou un framework pour lequel Failproof AI ne dispose pas d'adaptateur. + +Vous enveloppez le travail que vous effectuez déjà dans des blocs `with`. Chacun enregistre quand il a démarré, quand il s'est terminé, et combien de temps il a duré — vous n'avez rien d'autre à appeler. + +## Installation + +```bash +pip install failproofai-sdk +``` + +Aucun supplément, ni aucune dépendance. + +## Instrumentation + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # une exécution + with failproofai_sdk.agent("planner"): # une unité de travail + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) # un appel d'outil +``` + +Lisez-le de haut en bas et il dit ce qu'il signifie : + +| Enveloppez dans | 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()` | Ceci est un outil, et voici ce qu'il a retourné | + +Imbriquez-les selon la façon dont votre code s'imbrique. Vous n'avez jamais à transmettre des identifiants : chaque bloc se souvient dans quel contexte il se trouve, donc tout ce que vous enregistrez récupère automatiquement la bonne exécution et le bon agent. `async with` fonctionne exactement de la même façon. + +## Vérifier que les données sont arrivées + +Exécutez-le une fois, puis ouvrez **Observe → Sessions** et sélectionnez votre environnement. Votre exécution apparaît sous forme de trace reconstituée. + +Si rien n'arrive, vérifiez que la machine est connectée avec `failproofai config --status`. + + + Chaque méthode d'événement, ce qui se passe lorsque votre code lève une exception, un exemple concret, les threads et l'async, ainsi que l'instrumentation d'un framework sans adaptateur. + \ No newline at end of file diff --git a/docs/fr/start/quickstarts/langchain.mdx b/docs/fr/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..395d8e991 --- /dev/null +++ b/docs/fr/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain et LangGraph" +description: "Installez, instrumentez et visualisez votre première trace." +icon: "/images/frameworks/langchain.svg" +--- + +Trois étapes pour obtenir votre première trace LangChain ou LangGraph. Pour le streaming, le human-in-the-loop, le nommage des spans et les options, consultez [le guide complet](/fr/start/integrations/langchain). + +## Installer + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Pour LangChain sans LangGraph, utilisez `failproofai-sdk[langchain]`. + +## Instrumenter + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +Aucune modification aux sites d'appel. `instrument()` enregistre un traceur que LangChain injecte dans chaque gestionnaire de callbacks qu'il instancie, de sorte que les graphes, les outils et les modèles sont capturés — y compris ceux présents dans des bibliothèques que vous n'avez pas écrites. + +## Vérifier que les données sont bien arrivées + +Exécutez-le une fois, puis ouvrez **Observe → Sessions** et sélectionnez votre environnement. Votre exécution apparaît sous forme de trace reconstruite. + +Si rien n'arrive, vérifiez que la machine est connectée avec `failproofai config --status`. + + + Ce qui est enregistré, le streaming, le comptage de tokens, le nommage des spans, le contrôle de session, les options et le human-in-the-loop. + \ No newline at end of file diff --git a/docs/fr/start/quickstarts/llamaindex.mdx b/docs/fr/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..afe95546c --- /dev/null +++ b/docs/fr/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "Installez, instrumentez et visualisez votre première trace." +icon: "/images/frameworks/llamaindex.svg" +--- + +Trois étapes pour obtenir votre première trace LlamaIndex. Pour les étapes de workflow, la récupération, le reaper et les options, consultez [le guide complet](/fr/start/integrations/llamaindex). + +## Installation + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## Instrumentation + +L'API agent de LlamaIndex est asynchrone. Chaque portée fonctionne aussi bien avec `async with` qu'avec `with`. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + Sans un argument supplémentaire sur votre LLM, chaque comptage de tokens dans votre trace sera null — `llama-index-llms-openai` ne demande pas les données d'utilisation lors du streaming. Consultez [Comptage de tokens](/fr/start/integrations/llamaindex#token-counts). + + +## Vérifier la réception + +Exécutez-le une fois, puis ouvrez **Observe → Sessions** et sélectionnez votre environnement. Votre exécution apparaît sous forme de trace reconstruite. + +Si rien n'arrive, vérifiez que la machine est connectée avec `failproofai config --status`. + + + Comptage de tokens, ce qui est enregistré, étapes de workflow, récupération, options et problèmes courants. + \ No newline at end of file diff --git a/docs/fr/start/quickstarts/pydantic-ai.mdx b/docs/fr/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..ccb83e16a --- /dev/null +++ b/docs/fr/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "Installez, instrumentez et visualisez votre première trace." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +Trois étapes pour votre première trace Pydantic AI. Pour les outils, les nouvelles tentatives, le streaming et les options, consultez [le guide complet](/fr/start/integrations/pydantic-ai). + +## Installer + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## Instrumenter + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` doit être appelé **avant** la construction d'un `Agent`. La capacité est ajoutée lors de la construction, donc un agent créé auparavant n'enregistre rien — sans erreur, car rien ne s'est mal passé. C'est la cause la plus fréquente d'une trace vide avec cet adaptateur, et les agents définis au niveau du module en sont les principales victimes : importez `failproofai_sdk` et appelez `instrument()` avant d'importer le module qui les construit. + + +## Vérifier la réception + +Exécutez-le une fois, puis ouvrez **Observe → Sessions** et sélectionnez votre environnement. Votre exécution apparaît sous forme de trace reconstituée. + +Si rien n'arrive, vérifiez que la machine est connectée avec `failproofai config --status`. + + + Ce qui est enregistré, les outils et nouvelles tentatives, le streaming, la dénomination des spans, les options et les problèmes courants. + \ No newline at end of file diff --git a/docs/he/index.mdx b/docs/he/index.mdx index 486a88702..243ea489b 100644 --- a/docs/he/index.mdx +++ b/docs/he/index.mdx @@ -1,42 +1,42 @@ --- --- -title: "הפוך את הסוכן שלך לחסין כשלים" -description: "צפייה ואכיפה לכל סביבה בה הסוכנים שלך רצים — CLIs קוד, שערי צ'ט, עוזרים בתדירות עצמית, וסוכנים מעוצבים שלך." +title: "הפוך את ה-Agent שלך לבטוח לחלוטין" +description: "Observability והטמעת אכיפה עבור כל harness שה-agents שלך רץ בתוכו — CLIs קידוד, gateways צ'אט, עוזרים self-hosted, וה-agents שלך עם instrumentation." icon: "shield-check" --- -Failproof AI עוזר לצוותים להבין מה עשו הסוכנים, למצוא היכן הם נכשלו, והקימו הגנות לפני שאותה התנהגות תחזור לחזור. +Failproof AI עוזר לצוותים להבין מה עשו ה-agents, למצוא היכן הם נכשלו, והיישם safeguards לפני שאותו ההתנהגות תקרה שוב. -**סביבה** היא כל מה שהסוכן שלך בעצם רץ בתוכה. Failproof AI מתחבר ל-12 מהן — CLIs קוד כמו Claude Code ו-Codex, שערי צ'ט כמו Hermes, עוזרים בתדירות עצמית כמו OpenClaw — ואותם אירועים, אותן מדיניויות, ואותו היסטוריון של סשן חלים על כל אחד מהם. סוכנים ללא סביבה מדווחים דרך ה-[Python SDK](/he/reference/custom-agents), שעוקב אחריהם ובוחן אותם; אכיפת מדיניות שם דורשת hook בזמן ההוראה שלך. +**harness** הוא בעצם מה שה-agent שלך רץ בפנים. Failproof AI חוקר 12 מהם — CLIs קידוד כמו Claude Code ו-Codex, chat gateways כמו Hermes, עוזרים self-hosted כמו OpenClaw — וכל האירועים, אותן policies, וההיסטוריית ההפעלה זהה עבור כל אחד. Agents ללא harness דיווחים דרך ה-[Python SDK](/he/reference/custom-agents), שעוקבים אחריהם ומבצעים ביקורת; הטמעת policy שם דורשת hook בה-runtime שלך. - השתמש בכישור כדי לעצב את הפרויקט שלך, להתחבר, וכדי לאמת שרישומי סוכן מגיעים. + השתמש בכישור כדי לבצע instrumentation בפרויקט שלך, התחבר, וודא שלוגים של agents הגיעו. - - נתח, שאל שאלות, בנה לוחות מחוונים, והפעל ביקורות בשפה טבעית על רישומי הסוכן שלך. + + בצע ניתוח, שאלה, בנה dashboards, והפעל ביקורות בשפה טבעית על לוגים של agents. - - עקוב אחרי קריאות מודל, כלים, שגיאות, קלט אנושי, זמן תגובה, והחלטות מדיניות בסשן אחד. + + עקוב אחר קריאות מודל, כלים, שגיאות, קלט אנושי, latency, והחלטות policies בהפעלה אחת. - - בדוק קבוצה מוגדרת של סשנים, בדוק ממצאים מתומכים בראיות, וועד את הסידור כבעיות. + + בצע ביקורת על סט מוגדר של הפעלות, בדוק ממצאים מבוססי ראיות, ועקוב אחר תיקון כבעיות. - הפוך מצב כשל ידוע לנתינה, צפה בהשפעתו, והגדר אותו על פני הצי שלך. + הפוך מצב כשל ידוע לpolicy, בחן את השפעתו, והטמע אותו בכל ה-fleet שלך. > **Session → Audit → Finding → Issue → Policy**
-> עקוב מה קרה, מצא את הכשל, נהל את התגובה, ואז מנע את אותה התנהגות בהפעלות עתידיות. +> עקוב מה קרה, מצא את הכשל, נהל את התגובה, ואז מנע את אותה ההתנהגות בהפעלות עתידיות. ## התחל כאן -אם אתה משדר את הסוכן המעוצב הראשון שלך, התחל עם ה-[quickstart](/he/start/quickstart). אם נתונים כבר מגיעים, פתח את [Sessions](/he/sessions/overview) וחקור הפעלה אמיתית לפני הגדרת ביקורות או מדיניויות. +אם אתה מטמיע את ה-agent בעל instrumentation הראשון שלך, התחל עם ה-[quickstart](/he/start/quickstart). אם נתונים כבר הגיעו, פתח את [Sessions](/he/sessions/overview) וביקור בריצה אמיתית לפני שתגדיר ביקורות או policies. - השלם את זרימת העבודה מקצה לקצה מ-capture למדיניות שיש בה בטיחות משודרת. + השלם את זרימת העבודה end-to-end מ-capture לpolicy שהוטמע בבטחה. \ No newline at end of file diff --git a/docs/he/policies/deploy.mdx b/docs/he/policies/deploy.mdx index f876e9c67..2c0e3ee63 100644 --- a/docs/he/policies/deploy.mdx +++ b/docs/he/policies/deploy.mdx @@ -1,47 +1,52 @@ --- +--- title: "הצגת מדיניות" -description: "הפצת גרסת מדיניות שנבדקה לכלי המחשבים המיועדים." +description: "הפצה של גרסת מדיניות שנבדקה לשרתים המעוניינים." icon: "cloud-upload" --- -הצגה מחברת גרסת מדיניות אחת או יותר לקבוצת כלי המחשבים המנויים המיועדים. +הצגה מחברת גרסת מדיניות אחת או יותר לקבוצת שרתים שנרשמו ליעד. ## החלת הצגה - 1. עבור ל- **Admin → enforcement**, מצא את כלי המחשב והרחב את השורה שלו. - 2. בחר ב- **edit**, הוסף את גרסת המדיניות שנבדקה, ובחר ב- **observe** או בהשפעת ההאכיפה שלו. - 3. החל את השינוי, ואז חכה לבדיקה הבאה של כלי המחשב וודא את מצב ההצגה והכיסוי שלו. - 4. עבור ל- **Observe → policy** לבדיקת החלטות חיות. + 1. עבור אל **Admin → enforcement**, מצא את השרת והרחב את השורה שלו. + 2. בחר **edit**, הוסף את גרסת המדיניות שנבדקה, ובחר **observe** או את ההשפעה האוכפת שלה. + 3. החל את השינוי, ואז המתן לבדיקה הבאה של השרת וודא את מצב ההצגה והכיסוי שלו. + 4. עבור אל **Observe → policy** כדי לבדוק החלטות חיות. - ![עורך הצגת כלי המחשב עם גרסות מדיניות, השפעות enforce ו- observe, וביצוע הפעולה של הצגה.](/images/dashboard/enforcement-editor.png) + ![עורך הצגת השרת עם גרסאות מדיניות, השפעות אכיפה ותצפית, וההצגה של פעולת ההצגה.](/images/dashboard/enforcement-editor.png) - נקודות קצה של הצגה בענן אינן חשופות בכוונה כפקודות `fp` רגילות. בדוק את כלי המחשב באופן מקומי, ואז הצג דרך לוח המחוונים: + הצג מה-CLI עם `fp fleet`. בדוק את הקבוצה המתקבלת לפני החלתה — `deploy` מדפיס את התוכנית המלאה ושואל **רק בטרמינל אינטראקטיבי ללא `--json`**. תחת `--json`, עם `--yes`, או עם stdin מופנה לאחרים (שלב CI, סקריפט, agent shelling out) הוא מיישם מיד ללא תוכנית ללא הנמקה — אז הפעל `fp fleet show ` תחילה אם אתה רוצה ביקורת: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - השתמש ב- `fp sessions --env production --since 24h` וב- `fp events --event-type hook_completed` אחרי ההצגה לאימות שפעילות מגיעה ל- Cloud. + `fp fleet diff ` מציג את כוונה לעומת הספקה (שרת קורא כ-`behind` עד שהוא הסוקר הבא), `fp fleet history ` רשימות הדורות, ו-`fp fleet rollback ` משחזר אחד — הוא מסרב אם הדור הזה שם מדיניות מאז מובטל או מחוקק. + + בדוק את השרת עצמו עם `failproofai config --status`, והשתמש ב-`fp sessions --env production --since 24h` ו-`fp events --event-type hook_completed` לאחר הצגה כדי לוודא שפעילות מגיעה ל-Cloud. - הצג גרסה שנבדקה, לא טיוטה הניתנת לשינוי, החל מכלי מחשב שאינו בייצור או קוהורטה קטנה שאתה יכול לבדוק את ההפעלות שלה. + הצג גרסה שנבדקה, לא טיוטה משתנה, החל מ-non-production machine או קוהורט קטן שסשן שלו תוכל לבדוק. - - בדוק התאמות, סיבות, כלים מושפעים וחיוביים שווא ללא חסימת עבודה. + + בדוק התאמות, סיבות, כלים מושפעים וחיובי שווא ללא חסימת עבודה. - - קדם לאחר התאמות שנצפו הפרדות בין פעולות לא בטוחות לפעולות תקפות, ואז אשר שלכל כלי מחשב המיועד הורדה ההצגה ודיווח החלטות. + + קדם לאחר התאמות שצופו להפריד בין פעולות בלתי בטוחות לבין תקפות, ואז אשר שכל שרת המתכוון שלך שלף את ההצגה ודיווח החלטות. -כלי המחשב זקוקים ליכולת `policies:pull`. דיווח אירועים נשלט בנפרד על ידי `events:add`; אמת את שניהם כאשר אתה מצפה לניתוח וניהול אכיפה בענן. +שרתים זקוקים ל-`policies:pull` capability. דיווח אירועים נשלט בנפרד על ידי `events:add`; אמת את שניהם כאשר אתה מצפה לניתוח ואכיפה בענן. - ניהול אכיפה הוא זרימת עבודה בענן מנהלית. אל תתייחס לנתבי אכיפה בעלי הרשאות root בלבד כנקודות קצה רגילות `/v1` API של הלקוח. + ניהול אכיפה הוא זרימת עבודה ניהולית בענן. אל תתייחס למסלולי אכיפה root-only כנקודות קצה רגילות של `/v1` API של לקוח. \ No newline at end of file diff --git a/docs/he/policies/editor.mdx b/docs/he/policies/editor.mdx index 82084fbe4..d6b917ad5 100644 --- a/docs/he/policies/editor.mdx +++ b/docs/he/policies/editor.mdx @@ -1,47 +1,49 @@ --- -title: "עורך המדיניות" -description: "צור וערוך מדיניות בגרסאות מקודדות מתוך מצב כישלון מאומת." +title: "עורך המדיניויות" +description: "יצירה ותיקון של מדיניויות גרסאות מתוך מצב כשל מאושר." icon: "file-pen-line" --- -השתמש בעורך המדיניות כדי להפוך ממצא או בעיה לכלל ניתן לפריסה. שמור על הפרדה בין יצירת התוכן לבין פריסה, כך שטיוטה לא תשנה בשקט התנהגות פעילה. +השתמש בעורך המדיניויות כדי להפוך ממצא או בעיה לכלל הניתן להטמעה. שמור על הפרדה בין יצירת מדיניות להטמעה כך שטיוטה לא תוכל שינוי שקט בהתנהגות בתחום הפעול. -כאשר לבעיה יש דפוס פעולה חוזר, פתח אותה תחת **Analyze → issues** ובחר **generate policy**. Failproof AI תסביר תחילה האם מדיניות יכולה להביע את הבעיה, ואז תעביר את הכוונה המבוקרת והקשר הממצא לעורך. הקוד שנוצר נשאר כטיוטה עד שתפרסם אותו. +כאשר לבעיה יש דפוס פעולה חוזר, פתח אותה תחת **Analyze → issues** ובחר **generate policy**. Failproof AI מסביר תחילה האם מדיניות יכולה להביע את הבעיה, ואז מעביר את הכוונה המתוקנת והקשר המציאות לעורך. המקור שנוצר נשאר טיוטה עד שתפרסם אותו. ## פרסום גרסת מדיניות - 1. עבור אל **Admin → policy editor** ובחלק **compose**, תאר את מצב הכישלון או הדבק את קוד ה-JavaScript של המדיניות. - 2. אמת את הקוד ותקן כל שגיאה שדווחה. - 3. הזן את זהות המדיניות ופרסם אותה, ואז השתמש ב-**library** כדי להשוות או להשבית גרסאות. - 4. בחר **enforcement** כאשר הגרסה מוכנה לגלגול מכונה. + 1. עבור אל **Admin → policy editor** ובעמודת **compose**, תאר את מצב הכשל או הדבק את מקור ה-JavaScript policy. + 2. אמת את המקור ותקן כל שגיאה שדווחה. + 3. הזן את זהות המדיניות ופרסם אותה, לאחר מכן השתמש ב-**library** כדי להשוות או להשבית גרסאות. + 4. בחר **enforcement** כאשר הגרסה מוכנה לפרישה בתוך המכונה. - ![תצוגת compose של עורך המדיניות עם זהות המדיניות, יצירה בעזרת AI, אימות קוד והגדרות פרסום.](/images/dashboard/policy-editor.png) + ![תצוגת הרכבה של עורך המדיניויות עם זהות מדיניות, טיוטה בסיוע AI, אימות מקור, ובקרי פרסום.](/images/dashboard/policy-editor.png) - ה-Cloud CLI אינו מפרסם גרסאות של מדיניות. אמת את הקוד באופן מקומי לפני העתקתו לעורך: + פרסם מ-CLI באמצעות `fp policies publish`. זה יוצר **גרסה חדשה** ולעולם לא עורך אחת במקום, והוא בודק ניתוח מקור עם node לפני השליחה — שום דבר בהמשך לא עושה זאת, כך ששגיאת תחביר הייתה מופיעה אחרת במכונה בזמן הטמעה: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - פרסם את הגרסה המבוקרת מ-**Admin → policy editor**. + פרסום לא מטמיע דבר — גרסה חדשה יושבת ללא שימוש עד ש-`fp fleet deploy` מניחה אותה במכונה. `fp policies compose ""` יוצרת טיוטת מקור בעזרת Cloud assistant והדפסה אותה לבדיקה ולא מפרסמת אותה. + + כדי להתקין מדיניות לתוך agent CLI מקומי במקום זאת (לא Cloud), השתמש ב-`failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. -## רשימת בדיקה לכתיבה +## רשימת בדיקה של יצירה -1. תן שם למצב הכישלון בשפה תפעולית. +1. שם את מצב הכשל בשפה תפעולית. 2. בחר את אירועי ה-hook והכלים המכילים ראיות מספיקות להחלטה. -3. כתוב את התנאי הצר ביותר התואם התנהגות לא בטוחה. -4. החזר סיבה שתגיד לסוכן או למפעיל מה לעשות בשלב הבא. -5. הוסף דוגמאות שצריכות להתאים ודוגמאות שחייבות להישמר כמותרות. -6. שמור גרסה חדשה ובקש ביקורת. +3. כתוב את התנאי הצר ביותר התואם להתנהגות לא בטוחה. +4. החזר סיבה שמספרת לסוכן או למפעיל מה לעשות בשלב הבא. +5. הוסף דוגמאות שצריכות להתאים ודוגמאות שחייבות להישאר מותרות. +6. שמור גרסה חדשה וביקש ביקורת. -השתמש ב-`instruct` כאשר הסוכן יכול לתקן בבטחה את המסלול. השתמש ב-`deny` כאשר אישור הפעולה יהווה סיכון לא קביל או בלתי הפיך. +השתמש ב-`instruct` כאשר הסוכן יכול בתוקף תיקון הקורס. השתמש ב-`deny` כאשר ההתרת הפעולה תיצור סיכון בלתי קביל או בלתי הפיך. - גרסאות מדיניות הן קלטים פריסה בלתי שינויים. עריכת טיוטה יוצרת גרסה חדשה; היא לא צריכה לכתוב מחדש את הגרסה שכבר הוקצתה למכונות. + גרסאות מדיניות הן קלטי פריסה בלתי שינויים. עריכת טיוטה יוצרת גרסה חדשה; היא לא צריכה לשכתב את הגרסה שכבר הוקצתה למכונות. \ No newline at end of file diff --git a/docs/he/reference/cloud-cli.mdx b/docs/he/reference/cloud-cli.mdx index a896396b1..81a74f136 100644 --- a/docs/he/reference/cloud-cli.mdx +++ b/docs/he/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` לבחינת טלמטריה בענן וניהול ביקורות, ממצאים, בעיות, התראות, מפתחות, משתמשים, שאילתות והגדרות. השתמש ב-[`failproofai`](/he/reference/failproof-cli) לוו-קישורים מקומיים, מדיניות, לכידה ורישום מכונות. +השתמש ב־`fp` כדי לבדוק טלמטריה של Cloud, לנהל אכיפה מנוהלת בענן (מדיניות, פריסות fleet, החלטות guardrail), ולנהל ביקורות, ממצאים, בעיות, התראות, מפתחות, משתמשים, שאילתות והגדרות. השתמש ב־[`failproofai`](/he/reference/failproof-cli) עבור hooks מקומיים, מדיניות, capture והרשמת מכונה. -התקן את 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 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,30 +57,34 @@ 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` מאפשרת מצב מלא. | +| `--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` מאפשרת מצב מלא. | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` + + `--all` עמודים **עד `--limit`**, שברירת מחדל לו **50** — כך ש־`--all` בפני עצמו עוצר ב־50 שורות. כשהוא עוצר מוקדם, התגובה נושאת `next_cursor` כדי להמשיך ממנו; `"next_cursor": null` אומר שהרד אכן מותש. + + ### הפעלות ```text @@ -89,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`. | +| `--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` | הרחב את רשימת הסוכנים לעבור הפעלות מרובות סוכנים. | +| `--agents` | הרחב את רשימת הסוכנים עבור הפעלות מרובות סוכנים. | ### הערכות @@ -112,11 +116,11 @@ fp evals [OPTIONS] | אפשרות | תיאור | | --- | --- | | `--aggregate` | הצג סכומים וסטטיסטיקות לפי ניקוד במקום הערכות בודדות. | -| `--limit`, `-n ` | סך הכל שורות רשימה. ברירת מחדל: `50`. | +| `--limit`, `-n ` | שורות רשימה מרביות. ברירת מחדל: `50`. | | `--since`, `--from`, `--to` | בחר את טווח הזמן. | -| `--env`, `--status`, `--agent-id`, `--session-id` | צמצום לערך מדויק אחד לכל סנן. | -| `--score KEY:MIN..MAX` | טווח ניקוד; חוזר והכל טווחים חייבים להיות תואמים. | -| `--all`, `--cursor`, `--page-size` | בקרה על עימוד רשימה. | +| `--env`, `--status`, `--agent-id`, `--session-id` | צמצם לערך אחד בדיוק לכל מסנן. | +| `--score KEY:MIN..MAX` | טווח ניקוד; ניתן לחזור וכל הטווחים חייבים להתאים. | +| `--all`, `--cursor`, `--page-size` | שלוט בעמוד רשימה. | | `--fields ` | החזר רק שדות נבחרים. | | `--full-ids` | הצג מזהי הפעלה שלמים. | | `--scores-full` | הצג כל ניקוד בפלט טרמינל. | @@ -130,12 +134,12 @@ fp errors [OPTIONS] | אפשרות | תיאור | | --- | --- | | `--aggregate` | סכם שגיאות תואמות במקום רשימת שורות. | -| `--limit`, `-n ` | סך הכל שורות רשימה. ברירת מחדל: `50`. | +| `--limit`, `-n ` | שורות רשימה מרביות. ברירת מחדל: `50`. | | `--since`, `--from`, `--to` | בחר את טווח הזמן. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | צמצום אוכלוסיית השגיאות. | -| `--search ` | חיפוש טקסט עומס; חוזר. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | צמצם את אוכלוסיית השגיאות. | +| `--search ` | חפש טקסט בעומס; ניתן לחזור. | | `--order asc\|desc` | סדר זמן. | -| `--all`, `--cursor`, `--page-size` | בקרה על עימוד רשימה. | +| `--all`, `--cursor`, `--page-size` | שלוט בעמוד רשימה. | | `--fields ` | החזר רק שדות נבחרים. | | `--full-ids` | הצג מזהי הפעלה שלמים. | @@ -143,13 +147,13 @@ fp errors [OPTIONS] | פקודה | מטרה | | --- | --- | -| `fp usage` | הצג שימוש לחלון המדידה הנוכחי. | +| `fp usage` | הצג שימוש בחלון המדידה הנוכחי. | | `fp list envs` | רשום סביבות שנצפו. | | `fp list agents` | רשום מזהי סוכנים שנצפו. | | `fp list event_types` | רשום סוגי אירועים. | | `fp list score_filters` | רשום מפתחות ניקוד הערכה. | -| `fp list models` | רשום שמות דגמים. | -| `fp list hooks` | רשום שמות וו-קישור. | +| `fp list models` | רשום שמות מודלים. | +| `fp list hooks` | רשום שמות hook. | | `fp list tools` | רשום שמות כלים. | | `fp list error_types` | רשום סוגי שגיאות. | @@ -157,8 +161,8 @@ fp errors [OPTIONS] | פקודה | מטרה | | --- | --- | -| `fp orgs list` | רשום ארגונים שניתן לגשת אליהם. | -| `fp orgs switch [SLUG]` | שמור ארגון פעיל; מכריח כשהוא מושמט. | +| `fp orgs list` | רשום ארגונים נגישים. | +| `fp orgs switch [SLUG]` | שמור ארגון פעיל; הודע כשהושמט. | | `fp orgs current` | הצג את הארגון הפעיל. | | `fp orgs perms` | הצג את ההרשאות שלך בארגון הפעיל. | @@ -167,44 +171,44 @@ fp errors [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 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 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 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]` | רשום טבלאות ניתנות לשאילתה או בדוק טבלה אחת. | — | ### משתמשים | פקודה | מטרה | אפשרויות | | --- | --- | --- | | `fp users list` | רשום חברי ארגון. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | הצג חבר וההנחות שלהם. | — | +| `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 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 schema` | הצג ערכים מקובלים ותיאורים. | — | +| `fp settings set KEY` | שנה הגדרה קיימת. | בדיוק אחד מ־`--value`, `--json-value`, `--file`; `--yes`, `-y` אופציונלי | ### התראות @@ -213,34 +217,34 @@ 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 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 context-refresh NAME` | קבל מחדש כתובות URL ייחוס. | — | +| `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 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 dismiss FINDING_ID` | סמן דפוס כלא פעיל וכבה אותו. | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | סמן ממצא כתוקן ללא דיכוי עתידי. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | החזר ממצא לתור החי וביטל דיכוי. | — | +| `fp audits assign FINDING_ID` | הגדר בעל ממצא. | נדרש `--to ` | #### אפשרויות יצירת ביקורת @@ -257,27 +261,27 @@ fp audits create checkout-reliability \ | אפשרות | תיאור | | --- | --- | -| `--file ` | בסיס ההגדרה על JSON, או השתמש ב-`-` עבור stdin. דגלים מפורשים מעקפים ערכי קובץ. | +| `--file ` | בסיס ההגדרה על JSON, או השתמש ב־`-` עבור stdin. דגלים מפורשים דורסים ערכי קובץ. | | `--description ` | ציין את שאלת ההכשל או המטרה. | -| `--enabled` / `--disabled` | התחל תזמון או מחוזק. ברירת מחדל: מופעל. | +| `--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 תווים. | +| `--scope ''` | סנן לפי `environments`, `agent_ids`, או שדות scope אחרים תומכים. | +| `--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; חזור עד חמש פעמים. | +| `--url ` | הוסף הפניה ציבורית HTTPS; חזור עד חמש פעמים. | -כלול הקשר במהלך יצירה כאשר הריצה הראשונה זקוקה לה. יצירה מחייבת את ההגדרה וההקשר יחדיו לפני תחילת הריצה בתור. +כלול הקשר במהלך יצירה כאשר ההרצה הראשונה זקוקה לו. יצירה מחייבת את ההגדרה וההקשר יחד לפני תחילת ההרצה בתור. - `fp audits run` הוא אסינכרוני. סקור `fp audits runs NAME` עד שהריצה האחרונה תצליח או תיכשל לפני קריאת הממצאים שלה. + `fp audits run` הוא אסינכרוני. סקור `fp audits runs NAME` עד שההרצה האחרונה תהיה מוצלחת או כושלת לפני קריאת הממצאים שלה. ### בעיות @@ -285,67 +289,111 @@ fp audits create checkout-reliability \ | פקודה | מטרה | אפשרויות | | --- | --- | --- | | `fp issues list` | רשום בעיות. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | ספור פתוח או סטטוסי בעיה נבחרים. | `--state` | +| `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 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-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`. +מצבי בעיה חוקיים הם `firing`, `acknowledged`, ו־`resolved`. חומרות בעיה עצמאיות הן `info`, `warning`, ו־`critical`. -### עוזר בענן +### עוזר Cloud | פקודה | מטרה | אפשרויות | | --- | --- | --- | -| `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`. + +| פקודה | מטרה | אפשרויות | +| --- | --- | --- | +| `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`. | — | + +### Fleet + +אילו מכונות מריצות אילו מדיניות. **הפעלה בלבד**, אותה סיבה כמו למעלה. + +| פקודה | מטרה | אפשרויות | +| --- | --- | --- | +| `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` | + +### Guardrails + +מה שאכיפה למעשה עשתה. **הפעלה בלבד**, אותה סיבה כמו למעלה. + +| פקודה | מטרה | אפשרויות | +| --- | --- | --- | +| `fp guardrails summary` | כיסוי, חסומים/הערכות סכומות, ניצוץ deny, וטבלת לפי מדיניות. | `--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` | הדפס את הגרסה הלא מעוטפת וצא. | +| `--json` | פלוט JSON קריא למכונה. | +| `--base-url ` | השתמש בדDashboard משודר או פיתוח. | +| `--org ` | בחר ארגון להפעלה זו. | +| `--token ` | דרס את אסימון ההפעלה של המשתמש השמור. | +| `--api-key ` | אימות אוטומציה עם מפתח API; לעולם לא שמור. | +| `--timeout ` | HTTP timeout; חייב להיות חיובי. ברירת מחדל: `30`. | +| `--quiet`, `-q` | דכא פלט מצב ב־stderr. | +| `--no-color` | בטל פלט צבוע. | +| `--insecure` / `--secure` | בטל או שחזר אימות תעודה TLS. | +| `--version` | הדפס את הגרסה ללא תיבה וצא. | | `--help`, `-h` | הצג עזרה. | -`--api-key` מיועד לאוטומציה. התחברות, עברת ארגון, ופקודות עוזר דורשות הפעלת משתמש. +`--api-key` מיועד לאוטומציה. התחברות, החלפת ארגון, ופקודות עוזר דורשות הפעלת משתמש. ## משתנים סביבה | משתנה | שקול או מטרה | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | העבר מחדש את ספריית תצורת CLI הנוכחית. | -| `AGENTEYE_ANALYTICS_DISABLED` או `DO_NOT_TRACK` | השבת ניתוח CLI אנונימי. | -| `NO_COLOR` | השבת פלט צבעוני. | - -דגלים מפורשים משבים משתנים סביבה, המשבים תצורה משומרת. במצב מפתח API, בחר את השוכר מפורשות עם `--org` או `AGENTEYE_ORG`. +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `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` | בטל פלט צבוע. | + +דגלים מפורשים דורסים משתנים סביבה, המדרסים קונפיגורציה שמורה. במצב מפתח API, בחר את הדייר במפורש עם `--org` או `FP_ORG`. + + + ההוקעות של `AGENTEYE_*` אלה **אינן קריאות על ידי `fp`** ולעולם לא היו — ה־CLI מצהיר `FP_*` (`fp_cli/app.py`), ומשתנה לא ידוע אינו שגיאה. הגדרת `AGENTEYE_DASHBOARD_URL` לא משנה את יעד ה־CLI; היא מתעלמת והפקודה פועלת בשקט כנגד לוח הבקרה השמור במקום. + + `AGENTEYE_HOME` ו־`AGENTEYE_ENVIRONMENT` עדיין קיימים, אך הם שייכים ל־**Collector וה־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 f5eeb89f0..0f2d9402f 100644 --- a/docs/he/reference/custom-agents.mdx +++ b/docs/he/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- title: "סוכנים מותאמים" -description: "מכוונן עקבות מסוכנים מותאמים כדי ש-Failproof AI יוכל לשחזר הרצות ולמצוא כשלים." +description: "תצורה, קטלוג האירועים, כללי קורלציה והמסירה עבור failproofai-sdk." icon: "python" --- -כוונן עקבות מסוכן מותאם באמצעות `failproofai-sdk` כדי ש-Failproof AI יוכל לשחזר כל הרצה, לבדוק את ההתנהגות שלה ולמצוא כשלים מסומכים בראיות. ה-SDK כותב אירועים מובנים עבור Failproof daemon להעביר ל-Cloud. זה דורש Python 3.10 או חדש יותר. +מה שכל הגדרה, שיטה ושדה עושים. אם אתה מבצע קביעה לראשונה, התחל עם המדריך — הדף הזה מיועד לחיפוש מידע. -Tracing הופך סוכנים מותאמים לניתני תצפית ולביקורת. מניעת פעולה לא בטוחה לפני שהיא מתבצעת דורשת גם hook אכיפה בזמן ריצה שלך. + + + התקנה, קביעה, שיטות האירועים, דוגמה מעבודה, ובעיות נפוצות. + + + LangChain, CrewAI, LlamaIndex ו-Pydantic AI מבצעים קביעה עצמית בקריאה אחת. + + - - כדי אכוף מדיניויות בהגדרת סוכן מותאמת, [צור קשר עם Failproof AI](mailto:support@befailproof.ai). אנחנו נעזור למפות את גבולות המודל, הכלים וחיי המחזור של זמן הריצה שלך לאגוזי מדיניות. - +Python 3.10 ומעלה. אין תלויות זמן ריצה. -
- -
- -## התקן את `failproofai-sdk` - -ה-SDK מופץ כרגע כגלגל פרטי. בקש מאחד ה-Failproof AI שלך את הגרסה הנוכחית וגישה להורדה. +## התקנה ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -עם `uv`, הורד את הגלגל תחילה והרץ `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl`. קבע את הגלגל במאגר חפצים פרטי או בנעילת תלות. - -החבילה מותקנת כ-`failproofai-sdk` ומיובאת בפייתון כ-`failproofai`. +החבילה מותקנת כ-`failproofai-sdk` ומיובאת ב-Python כ-`failproofai_sdk`. הרחבות פריימוורק כמו `failproofai-sdk[langgraph]` מתקינות את הפריימוורק עצמו; המתאמים תמיד משלוחים בגלגל הבסיס. -## חבר את Failproof daemon +## חיבור ל-Failproof daemon - - 1. עבור אל **Admin → Keys** וצור מפתח עם `events:add`. - 2. [חבר את Failproof daemon לCloud](/he/start/setup#connect-a-machine-to-cloud) על מכונת הסוכן. - 3. הרץ הפעלה מכוונת אחת, ואז מצא את המזהה המדויק שלה תחת **Observe → Events**. - 4. עבור אל **Observe → Sessions**, בחר באותה סביבה ופתח את העקבה שחוזרה. + + 1. עבור ל-**Admin → Keys** וצור מפתח עם `events:add`. + 2. [חבר את Failproof daemon ל-Cloud](/he/start/setup#connect-a-machine-to-cloud) על מכונת הסוכן. + 3. הפעל סשן אחד עם קביעה, ואז מצא את ה-ID המדויק שלו תחת **Observe → Events**. + 4. עבור ל-**Observe → Sessions**, בחר את אותה סביבה, ופתח את ה-trace שעוקב מחדש. - ![הפעלה של סוכן Python מותאמת שחוזרה כגרף ביצוע ועקבה של אירועים מסודרת.](/images/dashboard/session-detail.png) + ![סשן סוכן Python מותאם שעוקב מחדש כגרף ביצוע וטבלת אירועים מסודרת.](/images/dashboard/session-detail.png) ```bash @@ -51,102 +46,84 @@ python -c "import failproofai; print(failproofai.__version__)" -## כוונן הרצה שלמה - -קרא ל-`configure()` פעם אחת בעת התחלת התהליך. כל קריאת אירוע היא keyword-only ודורשת `session_id` ו-`agent_id` יציבים. +## תצורה ```python -import traceback -import uuid +import failproofai_sdk -import failproofai +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -failproofai.configure(environment="production") +| ארגומנט | מה זה עושה | +| --- | --- | +| `environment` | התווית בכל אירוע — `production`, `staging`, `prod-eu`. ברירת המחדל היא `dev`. | +| `flush_interval` | כמה קרוב לעתים קרובות ה-thread ברקע כותב לדיסק, בשניות. ברירת המחדל היא `0.5`. | +| `base_dir` | איפה לכתוב. ברירת המחדל היא ה-spool של ה-daemon, וזה מה שאתה רוצה אלא אם אתה יודע אחרת. | -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +הגדר באמצעות משתנה סביבה במקום: -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) +| משתנה | מה זה עושה | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | קובע את `environment` ללא שינוי קוד, לכאשר התווית שייכת להצגה ולא לאפליקציה. ארגומנט `configure()` מנצח עליו. | +| `FAILPROOFAI_HOME` | מעביר את שורש Failproof AI שמחזיק את ה-spool. | +| `FAILPROOFAI_SDK_STRICT` | `1` גורם לשגיאות קביעה להעלות חריגות במקום להיות רשומות. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` גורם לבעיית תאימות פריימוורק להעלות חריגות במקום להזהיר ולהמשיך הלאה. | -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + + **אין פסיקים ב-`environment`.** Ingest מפצל את השדה הזה בפסיקים כדי לבנות את המסננים שלו, ודילג על כל אירוע שהתווית שלו מכילה אחד — אז ריצה שלמה נעלמת בשקט. כתוב `prod-eu`, לא `prod,eu`. + + `configure(environment="prod,eu")` מעלה חריגות כדי שתגלה מיד. `AGENTEYE_ENVIRONMENT` לא יכול להעלות חריגות — שום דבר לא קורא לך — אז זה מזהיר פעם אחת וחוזר ל-`dev`. + -פלוט `agent_start` פעם אחת לכל שחקן. עבור תת-סוכנים, השתמש חוזר ב-`session_id` של ההורה, תן לכל שחקן `agent_id` מובחן, והגדר `parent_id` ל-**agent ID** של ההורה, לא למזהה ההפעלה. +אירועים מעומדים בזיכרון ונכתבים ברקע כל `flush_interval` שניות, עם flush סופי ביציאת המפרש. תהליך שהוכה לחלוטין הולך לאבד כל מה שטרם נכתב. -## התייחסות תצורה +## זהות + +כל אירוע שייך לסשן ולסוכן. **ההיקפים מילאו את שניהם**, אז רק לעתים קרובות אתה עובר אותם: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| הגדרה | התנהגות | -| --- | --- | -| `base_dir` | שורש ספול מפורש. קודם לכל משתנים של סביבה. | -| `flush_interval` | שניות בין כתיבות רקע מזיכרון ל-JSONL. ברירת מחדל: `0.5`. | -| `environment` | תווית פריסה בכל אירוע. ברירת מחדל ל-`dev`. | -| `FAILPROOFAI_HOME` | משנה את שורש Failproof AI המכיל את ה-`custom-agents` spool. | - -ה-SDK כותב ל-`base_dir` המפורש כשהוא מוגדר. אחרת, הוא משתמש בספול `custom-agents` של Failproof daemon תחת `FAILPROOFAI_HOME` או `~/.failproofai`. +העברה מפורשת של `session_id` או `agent_id` עדיין עובדת ומנצחת. בלי קשור או העברה, הקריאה מעלה `TypeError` במקום פליטת אירוע ש-Cloud יודה בשקט. -ה-SDK תוור קריאות בזיכרון וכותב אצווות בחוט רקע. הוא גם מנסה flush סופי דרך טיפול `atexit` של Python. עבור עובדים קצרי חיים, אפשר כיבוי מתורגם רגיל; סיום תהליך קשה יכול לאבד אירועים עדיין בזיכרון. + + הזהות רוכבת על משתני הקשר. היא עוקבת אחרי משימות `asyncio` באופן אוטומטי, אך **לא** threads חדש — עטוף עובד ב-`failproofai_sdk.propagate()` או האירועים שלו נוחתים בלא חיבור. + ## קטלוג אירועים -כל השיטות מחזירות `None`. שדות שנותרו כ-`None` מושמטים ולא כתובים כ-JSON `null`. +חמש עשרה שיטות. רובן באים בזוגות — אתה קורא לפותח, ואז לסוגר, וה-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` | + +שלוש עומדות לבד: `error`, `human_pause`, `human_interrupt`. + + + +כל שיטה גם לוקחת `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ failproofai.configure( | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -השתמש ב-`outcome="failed"`, `"error"`, `"timeout"`, או `"rejected"` כאשר השלמה צריכה להיספר ככישלון. ערכים אחרים, כולל `"failure"`, אינם מסווגים ככשלים על ידי ה-backend הנוכחי. + + + + כדי לסמן ריצה כנכשלה, `outcome` חייב להיות אחד מ-`failed`, `error`, `timeout` או `rejected`. כל דבר אחר — כולל הנוער הקרוב `"failure"` — נחשב להצלחה. + + +## זיווג ומשך + +**כלל אחד: תן לאירוע הסגירה את אותו id כמו לפותח שלו.** זה מה שמזווג אותם, וזה מה שמאפשר ל-SDK למדוד את הפער. + +| זוג | התאימו על | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**אל תעביר `duration_ms` בעצמך.** ה-SDK מודד זאת, והעברה שלו מעלה `ValueError`. -## כללי קורלציה ומשך זמן +היוצא דופן הוא `model_response`, כאשר רק אתה יודע את זמן ההשהיה של הספק האמיתי. העבר מספר שלם של אלפיות שנייה — float מעלה חריגות, כי העמודה היא מספר שלם של 32 ביט והיתה נוחתת ריקה אחרת. -- השתמש חוזר באותו `tool_call_id`, `hook_id`, `pause_id`, או `input_id` עבור אירוע ההשלמה המתאים. -- ה-SDK מחשב `duration_ms` עבור `tool_result`, `hook_completed`, `agent_resume`, ו-`human_input`. העברתו בעצמך לשיטות אלה מעלה `ValueError`. -- זיהויים של כלים וחישוקים חולקים מפת pending אחת בחוץ תהליך. הפוך אותם ייחודיים בעולם על פני הפעלות בו-זמנית ועל פני שני מרחבי השמות; זיהויים מספקי או UUIDs הם בטוחים ביותר. -- זוג מפוצל על פני תהליכים עדיין מתייחסות במורד הזרם, אך ה-SDK אינו יכול לחשב את משך ה-in-process שלו. -- מפת ההמתנה מחזיקה לכל היותר 10,000 התחלות וסילוקי הכניסה הישנה ביותר כשהיא מלאה. + -## שדות וטעימות מותאמים +- **Ids רק צריכים להיות ייחודיים לסוג, לכל סשן.** כלי וקוק יכולים לחלוק אחד; שני סשנים הפועלים בו זמנית יכולים לעשות שימוש חוזר בנתונים הלא מתנגשים. +- **הם לא מתוחמים לסוכן.** זוג שנפתח תחת סוכן אחד וסגור תחת אחר עדיין מתאים — שזו המקרה הנורמלי בקוד רב-סוכן. +- **`request_id` אופציונלי אבל מומלץ.** בלעדיו, אירועי מודל מזווגים בסדר שהם מגיעים, אז שתי קריאות בו זמנית באותו סוכן יכולות להזדווג בשגיאה. +- **זוג מחולק בין תהליכים** עדיין תואם בעננן, אבל ה-SDK לא יכול למדוד זאת — שום דבר בשום תהליך ראה את שני החצאים. +- **לכל היותר 10,000 פותחים מחכים לסוגר בו זמנית.** מעבר לזה הקדום דלק, אז דמות לא יכולה גדלה ללא קשור. -כל אירוע מקבל שדות keyword נוספים. השתמש בערכים תואמים JSON כאשר שאילתות במורד הזרם צריכות מבנה. עלים לא נתמכים כגון UUIDs, datetimes, decimals, sets, bytes, and model objects מחרוזים על ידי הכותב. + -שמות מותאמים שמורים הם `timestamp`, `session_id`, `agent_id`, `type`, ו-`environment`. שגיאות באות field אופציונלית מתקבלות כשדות מותאמים חדשים, לכן בדוק את ה-JSON המופץ כאשר שדה סטנדרטי לא מופיע בCloud. +## השדות שלך -## העבר ובדוק +כל מילת מפתח נוספת שאתה עובר מאוחסנת עם האירוע: + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # שלך +) +``` + +העדיף סוגי JSON אם אתה רוצה לשאול אותם מאוחר יותר. כל דבר אחר — UUID, datetime, `Decimal`, set, bytes, אובייקט מודל — מאוחסן כמחרוזת. + + + **קדיסה את שמות השדות שלך.** הוספות מיושמות אחרון, אז שדה בשם `model`, `tool_name` או `outcome` דורך בשקט את האמיתי. מתאמי הפריימוורק משתמשים ב-`fw_`; עשה את אותו הדבר ושום דבר לא יכול להתנגש. + + זה גם למה שדה אופציונלי שגוי לעולם לא שגוי — הוא פשוט הופך לשדה מותאם חדש. אם שדה סטנדרטי חסר בעננן, בדוק תחילה את האיות. + + +חמש השמות הבאים שמורים ודחוקים לחלוטין: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. + +## מסור והאמן - - ב-**Observe → Events**, בדוק תחילה שקיים `agent_start` ו-`agent_end` קיים אחרון. לאחר מכן פתח **Observe → Sessions** ובדוק שמודל, כלים, אנוש, חישוק ואירועי שגיאה מופיעים בסדר הנדרש. השתמש במזהה ההפעלה כמפתח בעיות עיקרי. + + ב-**Observe → Events**, אמת ש-`agent_start` קיים תחילה ו-`agent_end` קיים אחרון. ואז פתח **Observe → Sessions** ואשר שמודל, כלי, אדם, תריס ואירועי שגיאה מופיעים בסדר המיועד. השתמש בזהות הסשן כמפתח פתרון בעיות ראשוני. ```bash @@ -189,10 +203,14 @@ failproofai.configure( -אם Cloud ריק, בדוק `$FAILPROOFAI_HOME/custom-agents/events`, אחרת `~/.failproofai/custom-agents/events`. קבצי JSONL מוכיחים פליטת SDK; ספול גדל מצביע על תצורת daemon או מסירה, בעוד שספול ריק מצביע על כיוונון או חיי תהליך. +אם ענן ריק, בדוק `$FAILPROOFAI_HOME/custom-agents/events`, אחרת `~/.failproofai/custom-agents/events`. קובצי JSONL מוכיחים פליטת SDK; spool גדל מצביע על תצורת daemon או הפקה, בעוד spool ריק מצביע על קביעה או אורך חיי תהליך. + + + בדוק את ה-spool רק כאשר ה-daemon עוצר. בזמן שהוא פועל, הוא אוסף ודל כל קבוצה תוך אלפיות שנייה, אז רשימת ספרייה מתחרה בקולט ומראה הרבה פחות אירועים מאשר פלטו. + ## מנע כשלים בזמן ריצה מותאם -השתמש בממצאי ביקורת ובעקבות משובצות להגדרת הפעולה הלא בטוחה, ההוכחה הנדרשת והתגובה המכוונת. אינטגרציה אכיפה מותאמת חייבת לחשוף את הפעולה לפני ביצוע, להעביר את הקלט המובנה שלה לנוע המדיניות, וליישם את ההחלטה המותרת, הוראה, או סירוב. +השתמש בממצאי ביקורת ובעקבות מקושרות כדי להגדיר את הפעולה הבלתי בטוחה, הראיות הנדרשות, והתגובה המיועדת. אינטגרציה אכיפה מותאמת חייבת לחשוף את הפעולה לפני ביצוע, להעביר את הקלט המובנה שלה למנוע המדיניות, ולהחיל את החלטת ה-allow, instruct, או deny שהתקבלה. -שלח דוא"ל [support@befailproof.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/events-and-configuration.mdx b/docs/he/reference/events-and-configuration.mdx index 4fd0ca59b..cc5165e26 100644 --- a/docs/he/reference/events-and-configuration.mdx +++ b/docs/he/reference/events-and-configuration.mdx @@ -1,42 +1,41 @@ --- ---- title: "אירועים וקונפיגורציה" -description: "הפניה למודל האירוע, סביבות, אחסון מקומי וגבולות קונפיגורציה." +description: "התייחסות למודל אירועים, סביבות, אחסון מקומי וגבולות קונפיגורציה." icon: "list-tree" --- ## משפחות אירועים -- התחלה, סיום, השהייה וחידוש של Agent -- בקשה ותגובה של מודל -- שימוש בכלי וביצוע -- Hook הופעל והסתיים -- המתנה אנושית, קלט, השהייה והפסקה -- שגיאות ברורות +- התחלת סוכן, סיום, השהייה וחידוש +- בקשת דגם והתגובה +- שימוש בכלים והתוצאה +- התפעיל ההוק והושלם +- המתן אדם, קלט, השהייה והפסקה +- שגיאות מפורשות -כל אירוע נושא חותמת זמן, מזהה סשן, מזהה agent, סוג אירוע וסביבה. שדות ספציפיים לאירוע מכילים נתוני מודל, כלי, קורלציה, תוצאה, תוכן, משך זמן או שגיאה. +כל אירוע נושא חתימת זמן, מזהה הפעלה, מזהה סוכן, סוג אירוע וסביבה. שדות ספציפיים לאירוע מכילים נתונים של דגם, כלי, קורלציה, תוצאה, תוכן, משך זמן או שגיאה. ## בדוק חוזה אירוע - 1. פתח את **Observe → Events**. - 2. הגדר חלון זמן קצר וסנן לפי סביבה, agent וסוג אירוע. - 3. בחר אירוע כדי לבדוק את השדות המנורמלים שלו ותשלום גולמי, ואז פתח את הסשן שלו כדי לראות את הקשר ההוצאה לפועל. - 4. אם משך זמן מזוגג חסר, בדוק שאירועי ההתחלה והסיום משתמשים באותו מזהה קורלציה. + 1. פתח **Observe → Events**. + 2. הגדר חלון זמן קצר וסנן לפי סביבה, סוכן וסוג אירוע. + 3. בחר אירוע כדי לבדוק את השדות המנורמלים שלו ותשלום גולמי, ולאחר מכן פתח את ההפעלה שלו כדי לראות את הקשר ההוצאה לפועל. + 4. אם משך זמן מזוודה חסר, אמת שהאירועים של התחלה והשלמה משתמשים באותו מזהה קורלציה. - השתמש בזרם Events כדי לצמצם את הנתונים לריצת agent אחת ובדוק את שדות האירוע המנורמלים. + השתמש בזרם Events כדי לצמצם את הנתונים לריצת סוכן אחת ובדוק את השדות האירוע המנורמלים. - ![זרם Events חי עם מסננים לסביבה, agent, סשן וסוג אירוע.](/images/dashboard/events-stream.png) + ![זרם האירועים החי עם פילטרים לסביבה, סוכן, הפעלה וסוג אירוע.](/images/dashboard/events-stream.png) - לאחר מכן עקוב אחר האירוע לתוך הסשן שלו. העקבות מציגים מה קרה מיד לפני ואחרי זה, וזה הכרחי כאשר התשלום לבדו דו משמעי. + לאחר מכן עקוב אחר האירוע להפעלה שלו. העקיבה מראה מה קרה מיד לפני ואחרי זה, וזה הכרחי כאשר התשלום לבדו אינו חד משמעי. - ![שקע הסשן המקושר המשמש לבדוק את האירוע בהקשר הוצאה לפועל.](/images/dashboard/session-detail.png) + ![עקיבת ההפעלה המקושרת המשמשת לבדוק את האירוע בהקשר הביצוע.](/images/dashboard/session-detail.png) - השווה מזהי קורלציה וחותמות זמן בשתי התצוגות כאשר אירוע מזוגג או משך זמן חסר. + השוו מזהי קורלציה וחתימות זמן בשתי התצוגות כאשר אירוע מזוודה או משך זמן חסר. - גלה ערכי מסנן תקפים, ואז אחזר עומסי אירוע מלאים לסשן אחד: + גלה ערכי סינון חוקיים, ולאחר מכן אחזר תשלומי אירוע מלאים להפעלה אחת: ```bash fp list event_types @@ -48,32 +47,32 @@ icon: "list-tree" --full ``` - השתמש ב-`fp --json events ... --fields ts,event_type,session_id,payload` לבדיקה קריאה-מכונה. + השתמש ב-`fp --json events ... --fields ts,event_type,session_id,payload` לבדיקה הניתנת לקריאה של מכונה. ## שדות SDK שמורים -אל תשתמש ב-`timestamp`, `session_id`, `agent_id`, `type` או `environment` כשדות Python SDK מותאמים אישית. משכי אירוע מזוגגים כמו משך זמן של תוצאת כלי מחושבים על ידי ה-SDK ואינם יכולים להיות מסופקים ידנית. +אל תשתמש ב-`timestamp`, `session_id`, `agent_id`, `type` או `environment` כשדות SDK מותאמים אישית ב-Python. משכי אירועים מזווגים כמו משך זמן תוצאת כלי מחושבים על ידי ה-SDK ולא ניתן לספק אותם ידנית. ## גבולות מקומיים -- מצב Failproof AI חי תחת `~/.failproofai` אלא אם צוין אחרת במפורש. -- `failproofai-sdk` משתמש ב-`AGENTEYE_HOME` להחלפת ספריית הבסיס המורשת שלו. -- ניתן להגדיר תוויות סביבה דרך קונפיגורציה SDK או `AGENTEYE_ENVIRONMENT`. +- מצב Failproof AI גר תחת `~/.failproofai` אלא אם כן מוגדר אחרת בבירור. +- `failproofai-sdk` תמיד משדר תחת `~/.failproofai/custom-agents`. `FAILPROOFAI_HOME` מעביר את הבית הזה; הקטע `custom-agents` תמיד מוצמד, ולכן לא ניתן למקם את הספול מחוצה לו. רק ה-`configure(base_dir=...)` שלו כתב במקום אחר. `AGENTEYE_HOME` נקרא על ידי ה-`agenteye-collector` הישן כדי לבחור מה לצפות, וכבר לא משפיע על המקום בו ה-SDK כותב. +- ניתן להגדיר תוויות סביבה דרך קונפיגורציית SDK או `AGENTEYE_ENVIRONMENT`. - אישורי Daemon מאוחסנים בנפרד מהגדרות שאינן סודיות. -השתמש בשמות סביבה יציבים ונמוכים בקרדינליות. פסיקים אינם נתמכים בתוויות סביבת daemon. +השתמש בשמות סביבה יציבים וקטנים-קרדינליות. פסיקים אינם נתמכים בתוויות סביבת daemon. ## שנה תווית סביבה - תוויות סביבה מוקצות על ידי ה-SDK או ה-Failproof daemon הפולט. לאחר שינוי אחד, פתח את **Observe → Sessions** והשתמש במסנן הסביבה כדי לאשר שסשנים חדשים נושאים את הערך החדש. סשנים קיימים שומרים על הסביבה המקורית שלהם. + תוויות סביבה מוקצות על ידי ה-SDK הפולט או daemon של Failproof. לאחר שינוי אחד, פתח **Observe → Sessions** והשתמש בפילטר הסביבה כדי לאשר שהפעלות חדשות נושאות את הערך החדש. הפעלות קיימות שומרות על הסביבה המקורית שלהן. - עבור `failproofai-sdk`, קונפיגור את הסביבה בקוד או עם משתנה הסביבה המורשה שלו. הפעל מחדש קונפיגורציה daemon בעת שינוי הגדרות ברמת המכונה. + עבור `failproofai-sdk`, קונפיגור את הסביבה בקוד או עם משתנה הסביבה הישן שלו. הפעל מחדש את קונפיגורציית daemon בעת שינוי הגדרות ברמת מכונה. ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/he/reference/harnesses.mdx b/docs/he/reference/harnesses.mdx index 92486fa39..e2919803b 100644 --- a/docs/he/reference/harnesses.mdx +++ b/docs/he/reference/harnesses.mdx @@ -1,72 +1,71 @@ --- ---- -title: "הנתונים של סוכנים" -description: "תפוס הפעלות והטל מדיניות על כל 12 נתונים נתמך." +title: "חיבורי סוכנים" +description: "תפוס הפעלות והטל מדיניות על פני 12 חיבורים נתמכים." icon: "plug-zap" --- -נתון הוא כל מה שהסוכן שלך בעצם פועל בתוכו. Failproof AI תומך בשנים עשר מהם, בשתי קטגוריות: +חיבור הוא כל מה שהסוכן שלך בעצם רץ בתוכו. Failproof AI תומך בשנים עשר מהם, בשתי קטגוריות: -- **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 אירועים קנוניים לפני שמדיניות כלשהי פועלת. +אותן מדיניות ואותו היסטוריית הפעלה חלים על כל חיבור שהסוכן רץ בתוכו. שכבת מתאם אחת ממפה את שמות האירועים המקוריים של כל חיבור, שמות הכלים ושדות קלט כלים על 29 אירועים קנוניים לפני הפעלת כל מדיניות. -סוכן שפועל ב**אף אחד** מהשנים עשר מותקן ישירות עם [Python SDK](/he/reference/custom-agents). זו חוזה אחרת, וראוי לציין זאת בבהירות: ה-SDK מספק עקיבה, הפעלות, הערכות וביקורות — **הוא אינו אוכף מדיניות בעצמו.** חסימת פעולה לא בטוחה לפני שהיא מתבצעת דורשת hook אכיפה בגבול הכלים של הזמן ריצה שלך; [צור איתנו קשר](mailto:support@befailproof.ai) ואנו נממפה אותו. +סוכן שרץ בשום אחד מהשנים עשר מתורגם ישירות עם [Python SDK](/he/reference/custom-agents). זה חוזה שונה, וכדאי להציג בבירור: ה-SDK מספק עקיבה, הפעלות, הערכות וביקורות — **הוא לא אוכף מדיניות בעצמו.** חסימת פעולה בלתי בטוחה לפני ביצוע דורשת חוק אכיפה בגבול הכלים של זמן הריצה שלך; [צור קשר איתנו](mailto:support@befailproof.ai) ואנחנו נממפה את זה. -| נתון | ההיקף של hook שנתמך | +| חיבור | טווח חוקים נתמך | | --- | --- | | Claude Code | משתמש, פרויקט, מקומי | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | משתמש, פרויקט | | Factory Droid, Devin CLI, Antigravity CLI, Goose | משתמש, פרויקט | | Hermes, OpenClaw | משתמש | -כל אינטגרציה מנרמלת את שמות אירועי ה-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` מותנה | hook הרשאה אינו פועל בכל מצב הרשאה; אירועי לאחר כלי והפעלה הם תצפייתיים. | -| Antigravity CLI | `PreToolUse`, `Stop` | גזרי הנחת משתמש ולאחר כלי הם תצפייתיים; הוראות הנחה עדיין יכולות להיות מוזרקות. | -| Goose | `PreToolUse` | אירועי הנחת משתמש, לאחר כלי והפעלה הם תצפייתיים. hook עצירה חסימה מקומי קיים במעלה הזרם אך לא מותקן על ידי המתאם הנוכחי. | - -יכולות תלויות בגרסה. בדוק מחדש אחרי שדרוג סוכן CLI, במיוחד כשמדיניות מסתמכת על התנהגות של הנחה, עצירה, הרשאה או לאחר כלי ולא על שער לפני כלי נפוץ. - -## התקן capture ו-policy hooks +| 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 המקומי עם המפתח המוצג והתקן את hook-ים של הנתון. - 3. התחל הפעלה חדשה של סוכן, ואז אשר את hook שלה ואירועי הפעלה תחת **Observe → Events**. - 4. פתח **Observe → policy** עבור אותה חלון זמן ואשר שהחלטת מדיניות מיוחסת למכונה. + + 1. פתח **ניהול → מפתחות** וצור מפתח עם `events:add` ו-`policies:pull`, בשם המכונה או הסביבה. + 2. במכונת היעד, חבר את ה-CLI המקומי עם המפתח המוצג והתקן את חיבורי החוק. + 3. התחל הפעלת סוכן חדשה, ואז אשר את אירועי החוק וההפעלה שלה תחת **צפוי → אירועים**. + 4. פתח **צפוי → מדיניות** לאותו חלון זמן ואשר שהחלטת מדיניות מיוחסת למכונה. - החיבור מתחיל עם מפתח של מכונה. אשר שהוא כולל הן הרשאות הזנה והן הרשאות הספקת מדיניות לפני שתעתיק את הסוד שלו. + החיבור מתחיל עם מפתח מכונה. אשר שהוא כולל הן הרשאות הטלה וקבלת מדיניות לפני העתקת הסוד שלו. - ![מגירת המפתח החדשה של API המשמשת להעניית הרשאות הזנה ואספקת מדיניות.](/images/dashboard/key-create.png) + ![המגירה מפתח API החדשה המשמשת להעניק הרשאות הטלה ושילוח מדיניות.](/images/dashboard/key-create.png) - לאחר התקנת hook-ים, זרם Events צריך להציג אירועים חדשים מהמכונה והסביבה שחיברת. + לאחר התקנת החוקים, זרם האירועים צריך להראות אירועים חדשים מהמכונה והסביבה שחיברת. - ![זרם Events חי המשמש לאישור שנתון שהתקנת זה מדווח.](/images/dashboard/events-stream.png) + ![זרם האירועים הלייב המשמש לאישור הדוח החדש של חיבור.](/images/dashboard/events-stream.png) - לבסוף, אמת שהחלטות מדיניות מיוחסות לאותה מכונה. זה מאשר שהנתון מדווח פעילות מדיניות כמו גם אירועי עקיבה. + לבסוף, אשר שהחלטות מדיניות מיוחסות לאותה מכונה. זה מאשר שהחיבור דוגל בפעילות מדיניות כמו גם אירועי עקיבה. - ![דף Policy המשמש לאימות החלטות מדיניות מנתון שחובר לאחרונה.](/images/dashboard/policy-observe.png) + ![דף המדיניות המשמש לאימות החלטות מדיניות מחיבור מחובר חדש.](/images/dashboard/policy-observe.png) - התקן hook-ים עבור כל נתון שגילה: + התקן חוקים לכל חיבור שזוהה: ```bash failproofai config \ @@ -75,7 +74,7 @@ icon: "plug-zap" failproofai policies --install ``` - או היעד נתוני בשם וההיקף של תצורה: + או עבור חיבורים ממוקדים וטווח קונפיגורציה: ```bash failproofai policies --install \ @@ -83,9 +82,9 @@ icon: "plug-zap" --scope user ``` - היקף פרויקט שומר על תצורת hook עם מחסן. היקף משתמש מכסה עבודה על פני מחסנים. Claude Code גם תומך בהיקף מקומי; התמיכה משתנה לפי נתון וה-CLI דוחה שילובים לא נתמכים. + טווח פרויקט שומר קונפיגורציה חוק עם מאגר. טווח משתמש מכסה עבודה על פני מאגרים. Claude Code תומך גם בטווח מקומי; התמיכה משתנה לפי חיבור וה-CLI דוחה שילובים בלתי נתמכים. - אמת את המכונה ואירועיה: + אשר את המכונה והאירועים שלה: ```bash failproofai config --status @@ -98,10 +97,10 @@ icon: "plug-zap" ## הוסף נתיב הפעלה שאינו ברירת מחדל - - נתיבים נוספים רשומים על המכונה, לא בענן. לאחר הוספת אחד, פתח **Observe → Sessions**, סנן לסביבת המכונה ואשר שהפעלות מהנתיב החדש מופיעות. פתח הפעלה ובדוק את הסוכן, הנתון וחותמות הזמן של אירועים לפני שתסתמך על כך בביקורת. + + נתיבים נוספים רשומים במכונה, לא בקלאוד. לאחר הוספת אחד, פתח **צפוי → הפעלות**, סנן לסביבת המכונה, ואשר שהפעלות מהנתיב החדש מופיעות. פתח הפעלה וחפש את הסוכן, החיבור וחותמות הזמן של אירועים לפני הסתמכות עליה בביקורת. - ![רשימת Sessions מסוננת לסביבה המקבלת נתונים מנתיב הלכידה הנוסף.](/images/dashboard/sessions-list.png) + ![רשימת ההפעלות מסוננת לסביבה המקבלת נתונים מנתיב התפיסה הנוסף.](/images/dashboard/sessions-list.png) הוסף נתיב עם תווית אופציונלית, ואז בדוק את הנתיבים המוגדרים: @@ -118,5 +117,5 @@ icon: "plug-zap" - הרץ הפעלה חדשה אחת לאחר ההתקנה. אמת גם את זרם האירוע החי וגם החלטת מדיניות בפועל לפני הרחבת ההצגה. + הפעל הפעלה חדשה אחת לאחר התקנה. אשר גם את זרם האירועים הלייב וגם החלטת מדיניות בפועל לפני הרחבת ההוצאה. \ No newline at end of file diff --git a/docs/he/reference/overview.mdx b/docs/he/reference/overview.mdx index b9063c72d..85161436e 100644 --- a/docs/he/reference/overview.mdx +++ b/docs/he/reference/overview.mdx @@ -1,61 +1,64 @@ --- -title: "אינטגרציות והפניה" -description: "חבר harnesses של agents, SDKs, CLIs ו-HTTP API שנתמכים." +title: "אינטגרציות והפניות" +description: "חבר מכונות תמיכה בסוכנים, SDKs, CLIs, וה-HTTP API." icon: "braces" --- -בחר את האינטגרציה הקרובה ביותר למקום בו ה-agent שלך כבר רץ. +בחר באינטגרציה הקרובה ביותר למקום בו הסוכן שלך כבר פועל. - - התקן hooks עבור CLIs של coding ו-autonomous agents שנתמכים. + + התקן hooks עבור CLIs של סוכנים קודים וחכמים נתמכים. - - צור traces כדי למצוא כשלים בـ agents מותאמים אישית, ואז צור קשר איתנו כדי להוסיף prevention לממשקי הזמן שלך. + + שלב את LangGraph, CrewAI, LlamaIndex, Pydantic AI, או סוכן מותאם אישית. - - בדוק פרויקטים מקומיים, sessions, פעילות policies ו-audits במצב offline. + + תצורה, קטלוג האירועים, כללי קורלציה והעברה. + + + בדוק פרויקטים מקומיים, הפעלות, פעילות מדיניות וביקורות במצב לא מקוון. - הגדר capture מקומי, hooks, policies, audits, delivery ומצב מכונה. + הגדר לכידה מקומית, hooks, מדיניות, ביקורות, העברה וזיכרון מכונה. - בצע שאילתות וניהול Cloud sessions, audits, issues, alerts, keys, users והגדרות. + שאל וניהול Cloud sessions, ביקורות, בעיות, התראות, מפתחות, משתמשים והגדרות. - הערך sessions שלמות או לא פעילות באמצעות שירות FastAPI. + דרג sessions שלמות או לא פעילות עם שירות FastAPI. - - כתוב ובדוק החלטות allow, instruct ו-deny ספציפיות לזרימת העבודה. + + כתוב ובדוק החלטות allow, instruct ו-deny ספציפיות לזרימת עבודה. - - פרוס את מישור הבקרה של Cloud על cluster Kubernetes המנוהל על ידי לקוח. + + פרוס את מישור הבקרה של Cloud על אשכול Kubernetes המנוהל על ידי הלקוח. -[ההפניה HTTP API](/he/reference/http-api) שנוצרה מכסה את פני השטח הציבורי `/v1`. דפים שנכתבו ביד מסבירים זרימות עבודה המשתרעות על פני נקודות קצה מרובות או משתמשים בממשקי ניהול מחוץ לפני השטח הציבורי הזה. +ה-[HTTP API reference](/he/reference/http-api) שנוצר מכסה את פני השטח הציבוריים `/v1`. עמודים כתובים ביד מסבירים זרימות עבודה המשתרעות על פני מספר endpoints או משתמשים בממשקי ניהול מחוץ לפני השטח הציבוריים הללו. -## חבר agent וודא נתונים +## חבר סוכן ואמת נתונים - - 1. פתח **Administration → Keys**, צור key עם `events:add` ו-`policies:pull`, והעתק את הסוד. - 2. הגדר את האינטגרציה באמצעות הדף התואם למעלה. - 3. פתח **Observe → Events** כדי לאשר שהאירועים הגיעו, ואז **Observe → Sessions** כדי לאשר שהם יוצרים runs שלמות. - 4. סנן לסביבה של האינטגרציה ובידוק session אחד עבור שדות המודל, כלי, שגיאה ו-policy הדרושים לאודיטים. + + 1. פתח **Administration → Keys**, צור מפתח עם `events:add` ו-`policies:pull`, והעתק את הסוד. + 2. הגדר את האינטגרציה באמצעות העמוד התואם למעלה. + 3. פתח **Observe → Events** כדי לאשר שאירועים מגיעים, ואז **Observe → Sessions** כדי לאשר שהם יוצרים הפעלות שלמות. + 4. סנן לסביבה של האינטגרציה ובדוק session אחד עבור שדות המודל, הכלי, השגיאה והמדיניות הנחוצים לביקורות. - התחל עם מגירת הרכוש. ההענקות שנבחרו קובעות אם המכונה יכולה לשלוח אירועים וקבל policies המנוהלים על ידי Cloud. + התחל עם מגירת המפתחות. ההנחות שנבחרו קובעות האם המכונה יכולה לשלוח אירועים ולקבל מדיניות המנוהלת על ידי Cloud. - ![מגירת ה-API key החדשה המשמשת להענקת הרשאות של event ingestion ו-policy delivery.](/images/dashboard/key-create.png) + ![מגירת המפתח הציבוריים החדשה המשמשת להנחת הרשאות ספיגת אירועים והעברת מדיניות.](/images/dashboard/key-create.png) - לאחר חיבור האינטגרציה, השתמש בשימוש ב-Sessions list כדי לאשר שהאירועים שלה מקובצים לתוך runs שלמות בסביבה הצפויה. + לאחר חיבור האינטגרציה, השתמש ברשימת Sessions כדי לאשר שהאירועים שלה מקובצים לתוך הפעלות שלמות בסביבה הצפויה. - ![רשימת Sessions המשמשת לאימות שאינטגרציה שזה עתה התחברה מדווחת agent runs שלמות.](/images/dashboard/sessions-list.png) + ![רשימת Sessions המשמשת לאימות שאינטגרציה המחוברת לאחרונה מדווחת על הפעלות סוכן שלמות.](/images/dashboard/sessions-list.png) - פתח את אחת מהסעיפים הללו לפני שתשקול את האינטגרציה כשלמה; ה-trace צריך להכיל את הראיות של מודל, כלי, שגיאה ו-policy שאודיטים שלך צריכים. + פתח את אחת מההפעלות הללו לפני שתשקול שהאינטגרציה שלמה; העקבה צריכה להכיל את המודל, הכלי, השגיאה והראיות המדיניות שהביקורות שלך זקוקות להן. - צור machine key, חבר את ה-Failproof daemon, ואמת את ה-session הראשון. + צור מפתח מכונה, חבר את daemon ה-Failproof, ואמת את ה-session הראשון. ```bash fp keys create agent-production \ @@ -71,8 +74,8 @@ icon: "braces" 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](/he/reference/failproof-cli) לפקודות מקומיות ו-[ההפניה Failproof Cloud CLI](/he/reference/cloud-cli#cli-commands) לפקודות `fp`. + ראה את [הפניית Failproof AI CLI](/he/reference/failproof-cli) עבור פקודות מקומיות ו-[הפניית Failproof Cloud CLI](/he/reference/cloud-cli#cli-commands) עבור פקודות `fp`. \ No newline at end of file diff --git a/docs/he/reference/troubleshooting.mdx b/docs/he/reference/troubleshooting.mdx index d9a52f8d7..2e26c30e0 100644 --- a/docs/he/reference/troubleshooting.mdx +++ b/docs/he/reference/troubleshooting.mdx @@ -1,16 +1,16 @@ --- title: "פתרון בעיות" -description: "אבחון של הפעלות חסרות, מדיניויות חסרות, כשלי מסירה וצעדי סוכן חסומים." +description: "אבחון של הפעלות חסרות, מדיניויות חסרות, כשל בהעברה וביצועים חסומים של סוכנים." icon: "wrench" --- - + - - פתח את **Administration → Keys** והאשר שמפתח המכונה פעיל ויש לו `events:add`. לאחר מכן פתח את **Observe → Events**, הרחב את טווח הזמן וטהר את מסננים הסביבה וסוכן. אם קיימות אירועים, חפש את מזהה ההפעלה ובדוק את **Observe → Sessions** לקבוצה. אם אין אירועים, בצע אבחון של ה-daemon של Failproof מ-CLI. + + פתח **Administration → Keys** ובדוק שמפתח המכונה פעיל ויש לו הרשאת `events:add`. לאחר מכן פתח **Observe → Events**, הרחב את טווח הזמן, והסר מסננים של סביבה וסוכן. אם קיימים אירועים, חפש את ID ההפעלה ולאחר מכן בדוק את **Observe → Sessions** לקיבוץ. אם אין אירועים, בצע אבחון של ה-Failproof daemon מה-CLI. - ![זרם ה-Events הכמי עם המסננים העיקריים שלו גלויים ואירועי סוכן אחרונים שמגיעים.](/images/dashboard/events-stream-current.png) + ![ה-Events stream החי עם המסננים הראשיים שלו גלויים ואירועי סוכן עדכניים מגיעים.](/images/dashboard/events-stream-current.png) ```bash @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - אשר שהלכידה מופעלת, שלמפתח המוגדר יש `events:add`, וש-dashboard filter תואם את הסביבה שפולטת. + בדוק שהקיפול מופעל, ללמפתח המוגדר יש `events:add`, והמסנן ב-dashboard תואם את הסביבה שנשלחה. - + - - טהר מסננים ב-**Observe → Events** וחפש את מזהה ההפעלה של ה-SDK. אם שום דבר לא מופיע, בדוק את ה-SDK spool ו-daemon של Failproof במכונת המקור. + + הסר מסננים ב-**Observe → Events** וחפש את ID ההפעלה המדויק של ה-SDK. אם שום דבר לא מופיע, בדוק את ה-SDK spool ו-Failproof daemon במכונת המקור. ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - אשר שתהליך הסוכן מגדיר `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` וש-`$FAILPROOFAI_HOME/custom-agents`, אחרת `~/.failproofai/custom-agents`, קיים לפני הפעלת ה-SDK. + בדוק ש-daemon מורץ ומחובר — ה-SDK משמור תמיד בין אם כן או לא. תיקיית ה-spool **לא** צריכה להתקיים מראש (הכותב יוצר אותה), ואף משתנה סביבה לא בוחר בה: `$FAILPROOFAI_HOME/custom-agents`, או `~/.failproofai/custom-agents`, היא הרק שורש, ו-`configure(base_dir=...)` הוא ההחלפה היחידה. אם התהליך נעצר ב-`SIGKILL` או הוצא מהזיכרון, כל מה שעדיין בתור הושמד — טפל ב-`SIGTERM` כדי להגביל זאת. - - פתח את **Admin → enforcement**, בחר את המכונה והשווה בין הגרסאות שלה שהוקצו, דווח והקודמות. אשר שטווח ההפצה כולל את המכונה ולמפתחה יש `policies:pull`. הערה יכולה לעבוד גם כאשר מסירת המדיניות לא עובדת. + + פתח **Admin → enforcement**, בחר את המכונה, והשווה בין הגרסאות המוקצות, המדווחות והקודמות שלה. בדוק שטווח ההצבה כולל את המכונה וההרשאה `policies:pull` למפתח שלה. ספיגה יכולה לעבוד גם כאשר העברת מדיניות לא. @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - אשר שמזהה המכונה ותווית תואמים את יעד ה-dashboard. התחבר מחדש עם מפתח המסוגל למדיניות אם האישור הקיים מעניק רק הערה של אירועים. + בדוק שה-ID והתווית של המכונה תואמים את היעד ב-dashboard. התחבר מחדש עם מפתח המסוגל להתמודד עם מדיניויות אם הפנייה הקיימת מעניקה רק ספיגת אירועים. - + - - פתח את **Admin → enforcement** ובדוק את זמן האחרון שנראתה המכונה וגרסה דווח. אם המכונה ישנה, התייחס לזה כבעיית daemon מקומית. אל תחלש את המדיניות המפותחת רק כדי לעקוף daemon אינו זמין. + + פתח **Admin → enforcement** ובדוק את זמן הראייה האחרון והגרסה המדווחת של המכונה. אם המכונה ישנה, התייחס לכך כבעיה ב-daemon מקומי. אל תחלול את המדיניות המפוותרת רק כדי לעקוף daemon לא זמין. @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - הפעל מחדש או עדכן את `failproofaid`; הפעל מחדש את ההגדרות כאשר גרסאות פרוטוקול ה-CLI ו-daemon שונות. נתיב ה-daemon המוגדר נכשל בתכנון סגור. + הפעל מחדש או עדכן את `failproofaid`; הרץ תצורה מחדש כאשר גרסאות פרוטוקול CLI ו-daemon שונות. נתיב ה-daemon המוגדר נכשל בעיצוב סגור. - - עבור מדיניות שנכתבה בענן, פתח את **Admin → policy editor**, בחר את הטיוטה וסקור שגיאות אימות לפני פרסום. עבור מדיניות מקומית, השתמש ב-CLI לאימות, ופתח את **Observe → policy** לאחר פעולת בדיקה כדי להשתמע בהחלטות. + + למדיניות שנכתבה בענן, פתח **Admin → policy editor**, בחר את הטיוטה, ובדוק שגיאות אימות לפני פרסום. למדיניות מקומית, השתמש ב-CLI לאימות שלה, לאחר מכן פתח **Observe → policy** אחרי פעולת בדיקה כדי לאשר שהחלטות מגיעות. - אשר שם הקובץ מסתיים ב-`policies.js`, `policies.mjs`, או `policies.ts`, המודול קורא ל-`customPolicies.add(...)`, והיבואים מתפזרים מקובץ המדיניות. + בדוק שהשם הקובץ מסתיים ב-`policies.js`, `policies.mjs`, או `policies.ts`, המודול מקרא את `customPolicies.add(...)`, וההורדות מתחברות מקובץ המדיניות. ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -91,14 +91,14 @@ icon: "wrench" - + - - פתח את **Analyze → audits**, בחר את ההפעלה וודא אם ניתוח מודל רץ. לאחר מכן השווה את הטווח והחלון שלו עם **Observe → sessions** ופתח עקבות מייצגים מאוכלוסיית זו. + + פתח **Analyze → audits**, בחר את ההרצה, ובדוק אם ניתוח דגם רץ. לאחר מכן השווה את ההיקף והחלון שלו עם **Observe → sessions** ופתח עקבות מייצגות מאותה אוכלוסייה. - תוצאה אפסית היא משמעותית רק כאשר הניתוח רץ בהצלחה. אם הניתוח דולג או נכשל, ההפעלה לא מייצרת ממצאים ושומרת על החלון שלא נותחה לפעולה בעתיד. אם ניתוח מודל אינו מופעל, הביקורת גם לא מייצרת ממצאים מכיוון שסריקת הרגלים ו-PII רושמות קבוע אך כבר לא מעלות ממצאים. + תוצאה של אפס היא משמעותית רק כאשר הניתוח רץ בהצלחה. אם הניתוח דולג או נכשל, ההרצה לא מייצרת ממצאים ושומרת את החלון שלא נותח פתוח להרצה מוצלחת בעתיד. אם ניתוח דגם מכובה, הביקורת גם לא מייצרת ממצאים מכיוון שסריקת פנייה וPII קובעת סטטיסטיקות אבל כבר לא מעלה ממצאים. - ![טופס הביקורת שבו סביבה, סוכן, קצב ותופעה חלון סיקור מגדירים את אוכלוסיית ההפעלה.](/images/dashboard/audit-new.png) + ![טופס הביקורת שבו סביבה, סוכן, קצב וחלון הסריקה מגדירים את אוכלוסיית ההפעלה.](/images/dashboard/audit-new.png) ```bash @@ -110,31 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - אם ההפעלה נשארה בתור, חכה לקיבולת audit-agent או בקש מ-deployment operator לבדוק את צי הביקורת. ביקורת בתור ניסיונות; היא לא מדלגת מיד. + אם ההרצה נשארה בתור, המתן לקיבולת audit-agent או בקש מפעיל ההצבה לבדוק את צי הביקורת. ביקורת בתור מנסה שוב; היא לא דלגה מיד. - - פתח הפעלה שהושלמה וודא אם הערכה ידנית מצליחה. ענן Cloud המצוי כרגע אין שליטה בנקודת קצה של פולט בלוח הבקרה; מפעיל השרת חייב להגדיר אותה. + + פתח הפעלה שהושלמה ובדוק אם הערכה ידנית הצליחה. Cloud המתוחזקת בענן כרגע אין שליטה של נקודת קצה מעריך בדאשבורד; על מפעיל השרת להגדיר אותה. - אמת את מעריך עצמו, ואז בדוק מצבי הערכה אחרונים: + אמת את המעריך עצמו, ולאחר מכן בדוק מצבי הערכה עדכניים: ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - ב-Cloud שעות עצמיות, אשר ש`EVALUATOR_ENDPOINT` נוכח בשרת ו-`EVALUATOR_TOKEN` תואם את המעריך. הערכה אוטומטית אינה מופעלת כאשר נקודת הקצה חסרה. + בענן Cloud המכובד עצמי, בדוק ש-`EVALUATOR_ENDPOINT` קיים על השרת ו-`EVALUATOR_TOKEN` תואם את המעריך. הערכה אוטומטית מכובה כאשר נקודת הקצה חסרה. - + - - השתמש בבורר הארגון והשתכנע בסלאג וההרשאות הצפויים לפני השוואה של תוצאות עם CLI. + + השתמש במחליף הארגון וודא את ה-slug וההרשאות הצפויים לפני השוואת תוצאות עם ה-CLI. ```bash @@ -143,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - במצב מפתח API, ציין `fp --org --api-key ...` או הגדר `AGENTEYE_ORG`. מצב ארגון הפעלה אדם שנשמר בכוונה מתעלם בבקשות מפתח API. + במצב מפתח API, ציין `fp --org --api-key ...` או הגדר את `AGENTEYE_ORG`. מצב ארגון הפעלות אדם שמור מתעלמים כוונה לבקשות מפתח API. - - פתח את **Observe → policy**, שמור על ההחלטה ההפעלה המקושרת, וזהה את מצב חיובי כוזב. לאחר מכן פתח את **Admin → enforcement** והחזר את המכונות המושפעות לגרסה הקודמת. צור גרסה צרה יותר ב-**Policy editor**, בדוק אותה בטווח קטן, והרחב רק לאחר שעבודה תקפה מצליחה. + + פתח **Observe → policy**, שמור את ההחלטה וההפעלה המקושרת, וזהה את תנאי החיובי השקר. לאחר מכן פתח **Admin → enforcement** והחזר את המכונות המושפעות לגרסה הקודמת. צור גרסה צרה יותר ב-**Policy editor**, בדוק אותה על היקף קטן, והרחב רק אחרי שעבודה תקפה הצליחה. - חזרה של Cloud הוא רק לוח בקרה. השהיית הפעלה מקומית לא משבית מדיניויות מנוהלות בענן. אם לוח הבקרה אינו זמין, תפוס את מצב המכונה וההצטיידות ותרחקת גישה לוח בקרה ולא חזור על פעולה החסומה. + רולבק של הצבת ענן הוא רק דאשבורד. השהיית הפעלה מקומית לא מבטלת מדיניויות שמנוהלות בענן. אם הדאשבורד לא זמין, תפוס את מצב המכונה וההצבה והחזר גישה לדאשבורד במקום להשתמש ללא הרף בפעולה החסומה. ```bash failproofai config --status @@ -164,4 +164,4 @@ icon: "wrench" -כשפונים לתמיכה, כללו את גרסת CLI, הרתקה, סביבה, מזהה הפעלה או הצטיידות רלוונטיות, ותפוקת `failproofai config --status` עם סודות מוסרים. \ No newline at end of file +כאשר פונים לתמיכה, כלול את גרסת CLI, הכלי, הסביבה, ID הפעלה או הצבה רלוונטי, והפלט של `failproofai config --status` עם סודות שהוסרו. \ No newline at end of file diff --git a/docs/he/sessions/live-events.mdx b/docs/he/sessions/live-events.mdx index da65ff055..69c384c01 100644 --- a/docs/he/sessions/live-events.mdx +++ b/docs/he/sessions/live-events.mdx @@ -1,21 +1,22 @@ --- +--- title: "אירועים בזמן אמת" -description: "צפו בפעילות הסוכן תוך כדי ריצה של התא." +description: "צפה בפעילות הסוכן כשמושב פעיל." icon: "radio" --- -אירועים בזמן אמת עוזרים לכם לאשר את הקביעה וללמוד על ריצה בסיכון ללא צפייה להסתיום של התא. +אירועים בזמן אמת עוזרים לך לאשר כי הגדרת הקצה עובדת וצפה בהרצה בסיכון גבוה ללא צורך להמתין לסיום המושב. -## צפייה בפעילות +## צפיה בפעילות - 1. עברו ל-**Observe → Events**. - 2. התחילו עם חלון הזמן הנוכחי ללא סינונים כדי לאשר שנתונים הגיעים. - 3. סננו לפי סביבה, סוג אירוע, סוכן או תא. השתמשו בחיפוש לטקסט של payload. - 4. בחרו באירוע כדי לבדוק את סיכומו ופרטיו. עקבו אחרי קישור התא שלו כדי לראות את העקבות המלאים. + 1. עבור אל **Observe → Events**. + 2. התחל עם חלון הזמן הנוכחי וללא מסננים כדי לאשר שנתונים מגיעים. + 3. סנן לפי סביבה, סוג אירוע, סוכן או מושב. השתמש בחיפוש לטקסט בעומס השליטה. + 4. בחר באירוע כדי לבדוק את הסיכום והפרטים שלו. עקוב אחר קישור המושב שלו כדי לראות את העקיבה המלאה. - ![זרם Events בזמן אמת המציג תעבורה מ-Hermes chat gateway ותוך כדי ריצות coding-CLI, מסוננת לפי זמן, סביבה, סוג אירוע, סוכן, מודל, קונטקסט ותא.](/images/dashboard/events-stream-current.png) + ![זרם אירועים חי המציג תעבורה משער שיחה Hermes לצד הרצות coding-CLI, מסונן לפי זמן, סביבה, סוג אירוע, סוכן, מודל, הקשר ומושב.](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +25,22 @@ icon: "radio" fp --json events --full --session-id --all ``` - הזרם ברירת המחדל משמיט payloads גולמיים. השתמשו ב-`--full` רק לחקירה של תא מוגבל. + הזרם הדברתי מוגדר כברירת מחדל להשמיט עומסים גולמיים. השתמש ב-`--full` רק לחקירת מושב מוגבל. -השתמשו בזרם האירועים כדי לענות על שלוש שאלות מיידיות: +השתמש בזרם האירועים כדי לענות על שלוש שאלות מיידיות: - האם הסוכן הצפוי מדווח לסביבה הנכונה? -- האם קריאות מודל, קריאות כלים והחלטות מדיניות הגיעו בסדר? -- האם התא הפסיק להתקדם או התחיל לחזור על פעולה? +- האם קריאות מודל, קריאות כלים והחלטות מדיניות מגיעות בסדר? +- האם המושב הפסיק להתקדם או התחיל לחזור על אותה פעולה? -סוגי אירועים כוללים אירועי מחזור חיים של סוכן, בקשות ותגובות מודל, שימוש בכלים ותוצאות, ביצוע hook, המתנות והפרעות אנושיות, וטעויות מפורשות. מזהי מתאם חיברו אירועים זוגיים כמו קריאת כלי והתוצאה שלה. +סוגי אירועים כוללים אירועי מחזור חיים של סוכנים, בקשות ותגובות של מודל, שימוש בכלים והתוצאות שלהם, ביצוע hook, המתנה אנושית והפסקות, וטעויות מפורשות. מזהי מתאם מחברים אירועים מזווגים כמו קריאת כלי והתוצאה שלה. - שמרו על התצוגה החי רחבה בעת אימות אינטגרציה חדשה. הוסיפו סינונים רק אחרי שתראו את האירוע הראשון; סינון לא נכון יכול להיראות כמו קליטה שהנכשלה. + שמור על התצוגה החיה כללית בעת אימות שילוב חדש. הוסף מסננים רק לאחר שאתה רואה את האירוע הראשון; מסנן שגוי יכול להיראות כאל כישלון בערגון. -אם לא מופיעים אירועים, הריצו `failproofai config --status`, ואז [פתרו בעיות בקליטה](/he/reference/troubleshooting). +אם לא מופיעים אירועים, הרץ `failproofai config --status`, ואז [פתור בעיות בערגון](/he/reference/troubleshooting). -סוכנים שלא פועלים באחד ממ-12 ה-[harnesses](/he/reference/harnesses) הנתמכים מדווחים על אותם סוגי אירועים דרך ה-[Python SDK](/he/reference/custom-agents), כולל אירועי האנוש-בתוך-התא (`human_wait`, `human_input`, `human_interrupt`) שגטוויי וסוכנים בייצור מסתמכים עליהם. \ No newline at end of file +סוכנים שלא פועלים באחד מ-12 [harnesses](/he/reference/harnesses) הנתמכים מדווחים על אותם סוגי אירועים דרך [Python SDK](/he/reference/custom-agents), כולל אירועי הלולאה האנושית (`human_wait`, `human_input`, `human_interrupt`) שסערי שער וסוכנים ייצור תלויים בהם. \ No newline at end of file diff --git a/docs/he/start/first-policy.mdx b/docs/he/start/first-policy.mdx index bbcc47039..8a83d4e4b 100644 --- a/docs/he/start/first-policy.mdx +++ b/docs/he/start/first-policy.mdx @@ -1,34 +1,34 @@ --- --- -title: "מנע את ההוכחה הראשונה שלך באמצעות מדיניות" -description: "כתוב גרסת מדיניות, פרוס אותה במצב התבוננות, ואז אכוף אותה." +title: "מנעו את הכשל הראשון שלכם באמצעות מדיניות" +description: "כתבו גרסת מדיניות, פרסמו אותה במצב צפייה, ולאחר מכן אכפו אותה." icon: "shield-check" --- -השתמש במדיניות רק לאחר שתוכל לתאר את הפעולה הלא בטוחה ואת הפעולות החוקיות שחייבות להישאר מורשות. +השתמשו במדיניות רק לאחר שתוכלו לתאר את הפעולה הלא בטוחה ואת הפעולות החוקיות שחייבות להישאר מותרות. - - עבור אל **Admin → policy editor**. התחל עם מדיניות הדוגמה, בדוק או ערוך את קוד המקור שלה, ואז בחר **publish version**. הפרסום יוצר גרסה שלא ניתן לשנות שאתה יכול לפרוס על מכונות. + + עברו אל **Admin → policy editor**. התחילו עם מדיניות ההדגמה, בדקו או ערכו את קוד המקור שלה, ואז בחרו **publish version**. פרסום יוצר את הגרסה הבלתי ניתנת לשינוי שתוכלו לפרוס למכונות. - ![The Policy editor compose view with a demo policy ready to publish as an immutable version.](/images/dashboard/policy-editor.png) + ![תצוגת ההרכבה של עורך המדיניות עם מדיניות הדגמה מוכנה לפרסום כגרסה בלתי ניתנת לשינוי.](/images/dashboard/policy-editor.png) - - עבור אל **Admin → enforcement**, הרחב את המכונה היעד, ובחר **edit this machine**. הוסף את מדיניות הדוגמה המפורסמת, קבע את גרסתה, בחר **observe**, והחל את הפרסום. + + עברו אל **Admin → enforcement**, הרחיבו את המכונה היעד, ובחרו **edit this machine**. הוסיפו את מדיניות ההדגמה המפורסמת, קבעו את גרסתה, בחרו **observe**, והחילו את הפרסום. - ![The machine deployment editor with a published policy version selected in observe mode before applying the deployment.](/images/dashboard/enforcement-editor.png) + ![עורך פרסום המכונה עם גרסת מדיניות מפורסמת שנבחרה במצב צפייה לפני החלת הפרסום.](/images/dashboard/enforcement-editor.png) - - הפעל סשן סוכן חדש על אותה מכונה, ואז פתח **Observe → policy**. בחר את המכונה וודא שמדיניות הדוגמה מופיעה במיפוי המדיניות וציר הזמן של ההחלטות. מצב התבוננות מתעד מה המדיניות הייתה עושה ללא חסימת הפעולה. + + הריצו סשן סוכן חדש באותה מכונה, ואז פתחו את **Observe → policy**. בחרו את המכונה וודאו שמדיניות ההדגמה מופיעה במיפוי המדיניות ובציר הזמן של ההחלטות. מצב צפייה רושם מה המדיניות הייתה עושה ללא חסימת הפעולה. - ![The Policy page showing decision totals, enforcement activity over time, and local and Cloud-managed policy mappings.](/images/dashboard/policy-observe.png) + ![עמוד Policy המציג סכומי החלטות, פעילות אכיפה לאורך זמן, ומיפויי מדיניות מנוהלים מקומיים וקלאוד.](/images/dashboard/policy-observe.png) - כתיבת מדיניות בענן ופרסום לחברה הם זרימות עבודה ניהוליות. השתמש ב-CLI המקומי כדי לאמת את אותה מדיניות לפני הפרסום: + כתיבת מדיניות קלאוד ופרסום צי הן זרימות עבודה ניהוליות. השתמשו ב-CLI המקומי לאימות של אותה מדיניות לפני פרסומה: ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -36,13 +36,13 @@ icon: "shield-check" failproofai config --status ``` - השתמש ב-`fp` כדי לבדוק החלטות מדיניות הנראות בענן: + השתמשו ב-`fp` לבדיקת החלטות מדיניות גלויות בקלאוד: ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - ה-CLI של ענן לא חושף נתיבי פרסום אכיפה של root בלבד. פרסם גרסות מ-**Admin → policy editor** ופרוס אותן מ-**Admin → enforcement**. + שני השלבים זמינים גם מה-CLI: `fp policies publish ` יוצר גרסה ו-`fp fleet deploy --add ` שם אותה על מכונה. השקילים של לוח הבקרה הם **Admin → policy editor** ו-**Admin → enforcement**. \ No newline at end of file diff --git a/docs/he/start/integrations.mdx b/docs/he/start/integrations.mdx new file mode 100644 index 000000000..5c13c59bd --- /dev/null +++ b/docs/he/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "כלי-עזר לאגנט שלך" +sidebarTitle: "Frameworks" +description: "חבר כל framework אגנט נתמך ל-Failproof AI עם קריאה אחת." +icon: "plug" +--- + +האגנט שלך כבר מייצר הכל שכדאי להקליט — קריאות למודל, קריאות לכלים, גבולות צמתים, חיכויים לאדם, כשלים. ה-framework זורק את זה. ה-SDK שומר על זה. + + + + אגנט שכתבת בעצמך, או אחד שלא רשום כאן. + + + גרפים, צמתים, כלים, retriever-ים, מודלים. + + + צוותים, זרימות, אגנטים לפי תפקיד, כלים. + + + סדרי עבודה, שלבים, function agents, retriever-ים. + + + אגנטים מטיפוסים, יכולות, כלים, ניסיונות חוזרים. + + + +## שלוש שורות, איזה framework שלא יהיה + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # detects the frameworks you imported + +with failproofai_sdk.session(): + ... # your existing agent call, unchanged +``` + +אין דקורטורים על הפונקציות שלך, אין callback שעוברת לקריאות שלך, אין ids המשודרים בקוד שלך. רק הקריאה בתוך ה-session שונה: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # under `async with failproofai_sdk.session():` + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +ההתקנה הנוספת היא ל-**framework**. כל adapter משודר בגלגל הבסיס, כך שפרויקט שכבר יש לו את ה-framework שלו לא צריך שום דבר נוסף בכלל. + +## בדוק שהגיע + +הפעל session אחד עם כלי-עזר, ואז פתח **Observe → Sessions** ובחר את ה-environment שלך. ה-run מופיע כ-trace שנבנה מחדש. + +אם לא הגיע כלום, אשר שהמכונה מחוברת עם `failproofai config --status`. ראה [Set up capture](/he/start/setup). + + + אל תבדוק את ספיריית ה-spool כדי לאשר משלוח. ה-Failproof daemon אוגר ומוחק כל batch תוך אלפיות שנייה, כך שקריאתו מהיר מהאוסף ומראה הרבה פחות אירועים מאלה שנקלטו. + + +## הבא + +כל quickstart למעלה מקשר להנחיה המלאה שלו — מה מתרשם, אפשרויות, streaming, קביעת שם span, והבעיות שאנשים באמת פוגשים. הם יושבים תחת **Trace Agents → Plug in your agent**. + + + + מודל הנתונים, ה-ids, סוגי האירועים, וכיצד אירועים מגיעים ל-Cloud. + + + עקוב אחר סיבתיות דרך session במקום יומנים מנותקים. + + + בדוק את ה-sessions שזה עתה תפסת. + + \ No newline at end of file diff --git a/docs/he/start/integrations/crewai.mdx b/docs/he/start/integrations/crewai.mdx new file mode 100644 index 000000000..c58033a42 --- /dev/null +++ b/docs/he/start/integrations/crewai.mdx @@ -0,0 +1,225 @@ +--- +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "ניהול צוות, זרימות, סוכנים לפי תפקיד, כלים, זיכרון ומשוב אנושי." +icon: "/images/frameworks/crewai.svg" +--- + +## התקנה + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +נתמך: `crewai` גרסאות 1.13 עד 2.0. גרסה 1.13 היא הגרסה שהוספה `started_event_id` והנורמליזציה של שימוש בטוקנים, ששניהם מהם המתאם תלוי כדי להתאים אירועים ולדווח על טוקנים. + +## ערוך + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` רושם מאזין על אפיק האירועים ברמת המודול של CrewAI וממנוי מטפל אחד לכל מחלקת אירועים. כלום לגבי הצוות, הסוכנים, המשימות או הכלים שלך לא משתנה. + +## מה מתועד + +| CrewAI | אירוע Failproof | +| --- | --- | +| Crew kickoff | `agent_start`, `agent_end` | +| `Agent.kickoff()` (סוכן קל, ללא צוות) | `agent_start`, `agent_end`, עם `agent_id` מהתפקיד | +| Flow start and finish | `agent_start`, `agent_end`; צוות שעלה על אדמה בתוך שיטת זרימה מקננת תחתיו | +| ביצוע סוכן | `agent_start`, `agent_end` מקונן, עם `agent_id` מהתפקיד. בתהליך היררכי עמית מומנה מקנן תחת המנהל, לא לצדו | +| משימה | כלום; מתועד כקישור כדי שילדים יתפקדו לצוות | +| שיטת Flow, guardrail | `hook_triggered`, `hook_completed` | +| שימוש בכלי | `tool_use`, `tool_result` | +| פעולות זיכרון וידע | `tool_use`, `tool_result`, בשם לפני השטח שהוכה | +| קריאת LLM | `model_request`, `model_response`, עם שימוש בטוקנים | +| Stream chunk | מקופל לתוך התגובה כמספר chunk וזמן לאסימון ראשון | +| משוב אנושי מבוקש | `human_wait`, `agent_pause` | +| משוב אנושי התקבל | `agent_resume`, `human_input` | +| שגיאת ביצוע סוכן | `error`, ואז `agent_end` עם תוצאה `failed` | + +משימה לא משדרת כלום בכוונה. משימת CrewAI היא תת-קבוצה של ביצוע הסוכן שמריץ אותה, ולכן פליטה של שניהם תשדר כל שורה פעמיים ותיצור אותם כאחים. מזהה המשימה והשם מיזעקים לאירועים של הסוכן עצמו. + +פעולות זיכרון וידע מתועדות ככלים, שנקראו על פני השטח שהם פוגעים בהם, כדי שהם יופיעו ליד הכלים האמיתיים שלך כאשר אתה יכול להשוות את ההשהיית שלהם. + +בצוות היררכי, קינון הוא מה שהופך את ההעקבות לקריאות: + +```text +crew +└─ manager + ├─ researcher delegated + └─ writer delegated +``` + +CrewAI הורה לביצוע מומנה על אירוע כלי **`delegate_work_to_coworker`**, לא ישירות על המנהל, ולכן המתאם עוקב אחרי הקישור הזה. ללא זה כל סוכן יוצא אח של כל אחד אחר והמבנה ההנחיה אבוד. + +## דוגמה + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # becomes agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +ההעברה גלויה בעקבות: ה-`analyst` span נסגר, ה-`writer` span נפתח, ושניהם יושבים בתוך span `crew` אחד. + +## תן שם ל-spans שלך + +`agent_id` מגיע מ-`Agent(role=...)`, זה מה שהופך אותו לפן יוקרה קריא על הלוח. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # one facet entry per run +``` + +`agent_id` הוא עמודה בעלת קרדינליות נמוכה. תפקיד המכיל מזהה ריצה או חותמת זמן מורידו לכל שאילתה שמישהו מריץ. אם תפקיד נראה כמו מזהה, המתאם מסרב אותו ושם את הערך האמיתי בשדה payload במקום. + +## שלוט בסדר הישיבה + +מסודר בסדר זה, התאמה ראשונה זוכה: + +1. `instrument("crewai", session_id=...)` +2. ההיקף `failproofai_sdk.session()` המקיף +3. `uuid4().hex` שנוצר, פעם אחת לכל crew או flow + +לעטוף את ה-kickoff כדי לשלוט בו לכל ריצה: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## אפשרויות + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # pin every run to one session id +) +``` + +`session_id` היא האפשרות היחידה שמתאם זה קורא. הנושאות והשלמות תמיד מתועדות, מקוצצות לתקציב ה-payload. + +## אדם בלולאה + +CrewAI יש **שני** משטחי אדם-בלולאה, ושניהם מתועדים כאותם ארבע אירועים. + +`@human_feedback` בשיטת זרימה עובר דרך אפיק האירועים של CrewAI: ה-runtime משדר אירוע לפני שהוא חוסם על אדם ועוד אחד לאחר התשובה. + +`Task(human_input=True)` לא. זה קוראה `input()` בתוך ספק הקלט של CrewAI עצמו ואינו משדר אירוע מכל סוג, כך המתאם עוטף ישירות את ספק הזה — ללא זה כל ההמתנה האנושית הייתה בלתי נראית וחויבת כזמן סוכן פעיל. + +כך או כך אתה מקבל: + +```text +human_wait the prompt and its options +agent_pause starts the paused-time clock +agent_resume stops it +human_input the answer, with the wait measured +``` + +`agent_pause` ל-`agent_resume` היא הזוג היחיד שמזין זמן מושהה. ללא זה, עשר דקות של המתנה אנושית חויבות כעשר דקות של זמן סוכן פעיל. + + + CrewAI לא מגדיר מזהה מתאם על שום אירוע משוב אנושי, כך המתאם משדבר אותם בשם הזרימה והשיטה, ונופל בחזרה ללחץ שנפתח לאחרונה. זה סביר כי הנושא של קונסול חוסם. אם אתה בונה ספק משוב במקביל, קבע `request_id` בשני האירועים. + + + + מכיוון שנתיב `Task(human_input=True)` הוא עטיפה סביב ספק הקלט של CrewAI ולא מנוי על אירועים, הוא מוחזר בעת `uninstrument()` ו-re-raises כל מה ש-`input()` raises, `KeyboardInterrupt` כלול, ללא שינוי. + + +## בעיות נפוצות + + + + `role` מכיל UUID, חותמת זמן או סיומת לכל ריצה. השתמש בתפקיד אנושי יציב והצב את המזהה הספציפי לריצה בתיאור המשימה במקום. + + + + אפיק האירועים אסינכרוני, ו-`kickoff()` חוזר לפני הפעלת המטפלים האחרונים. ניקז אותו קודם: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + זה תכונה של CrewAI, לא של ה-SDK. + + + + `agent_end` כופה-סוגר השהיות פתוחות אך לא כלים או דגמים, כך שריצה המתה בתוך קריאת כלי משאירה את ה-span פתוח. הפירוק הרגיל סוגר כל מה שעדיין פתוח ומסמן אותו לא שלם. רק `SIGKILL` משאיר אותו תלוי, כי שום דבר לא יכול להריץ. + + + + בדוק בסדר זה: `instrument()` רץ לפני `kickoff()`; יש `with failproofai_sdk.session():` סביבו; `crewai` הוא 1.13 או חדש יותר; `FAILPROOFAI_SDK_STRICT=1` קבוע, כך ווו מופחת מעלה במקום להיספג. + + + +## הבא + + + + זוגות, מזהים, מחזור חיים של סדר ישיבה והעברה. + + + עקוב אחרי סיבתיות דרך הסדר ישיבה שרק תפסת. + + + LangGraph, LlamaIndex, Pydantic AI, וסוכנים מותאמים אישית. + + \ No newline at end of file diff --git a/docs/he/start/integrations/custom-agents.mdx b/docs/he/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..a7c187155 --- /dev/null +++ b/docs/he/start/integrations/custom-agents.mdx @@ -0,0 +1,738 @@ +--- +title: "סוכנים מותאמים אישית" +sidebarTitle: "סוכנים מותאמים אישית" +description: "הוסף מעקב לסוכן שכתבת בעצמך, או לפריימוורק ללא מתאם." +icon: "code" +--- + +לסוכן שכתבת בעצמך, או לפריימוורק של Failproof AI אין לו מתאם. אין כלום להוסיף: אתה פולט את האירועים. + +זה אותו API שארבעת מתאמי הפריימוורק קוראים תחתיו. הם טבלאות תרגום עליו. + +## התקנה + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # קריאת כלי אחת +``` + +קרא זאת מלמעלה למטה והיא אומרת מה זה אומר: + +| עטוף אותו ב | כדי לומר | +| --- | --- | +| `session()` | האירועים הללו שייכים לאותה הרצה | +| `agent()` | משהו עושה עבודה — תן לו שם שהיית מזהה ברשימה | +| `tool_call()` | זהו כלי אחד, וזה מה שהוא החזיר | + +ומה כל אחד מהם למעשה פולט: + +| טווח | פולט | מטרה | +| --- | --- | --- | +| `session()` | כלום | קושר מזהה session, ומקבץ הרצה אחת | +| `agent()` | `agent_start`, `agent_end` | תוחם יחידת עבודה | +| `tool_call()` | `tool_use`, `tool_result` | תוחם כלי אחד ומודד אותו | + +הכל בתוך יכול להשמיט `session_id` ו-`agent_id`. הטווחים קושרים זהות על משתנות context ותוך כל קריאת event היא קוראת אותה חזרה, כך שאתה אף פעם לא מחליק מזהים דרך הפונקציות שלך. + +כל השלושה עובדים תחת `async with` כמו גם תחת `with`. + +קינון סוכנים בונה את העץ. `parent_id` והעמוק מחושבים מהערימה: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## כיצד טווח סוגר + +`agent()` מטפל בחריגות עבורך: + +| מה קרה | אירועים | תוצאה | +| --- | --- | --- | +| כלום לא הוגבה | `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` וכל דבר אחרי זה מיוחס לכלום. ביטול אינו כשל, כך שהרצות מבולות לא מזוהמות על משטח השגיאות. החריגה תמיד מוגבה מחדש: טווח אף פעם לא בולע. + +## שיטות האירוע + +חמש עשרה שיטות בשש משפחות. רובן מגיעות בזוגות — אתה פולט את הפותח, ואז את הסוגר, והSDK מודד את ה-span ביניהם. + +| משפחה | פותח | סוגר | עצמאי | +| --- | --- | --- | --- | +| **סוכנים** | `agent_start` | `agent_end` | — | +| | `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` | +| **כשלים** | — | — | `error` | + + + העדף את הטווחים — `agent()` ו-`tool_call()` — בכל מקום שהם מתאימים. הם מבטיחים את אירוע הסיום גם כאשר הגוף מגביל. פנה לשיטות אלה ישירות כאשר זרימת הבקרה שלך לא קינה, כמו קריאה למודל בתוך עוזר. + + + +```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 מודלים +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 וו +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 בני אדם +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 כשלים +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **שתי משפחות בני אדם מצביעות בכיוונים מנוגדים.** + + | שיטות | משמעות | + | --- | --- | + | `human_wait` / `human_input` | **הסוכן שאל אדם** — שער אישור, שאלה הבהרה | + | `human_pause` / `human_interrupt` | **אדם פעל על הסוכן** — כפתור עצור, השהיית מפעיל | + + אף פריימוורק לא משדר את הזוג השני, כך שתמיד שלך להפליט. + + + + **עבור `request_id` כאשר קריאות מודל פועלות במקביל.** בלעדיו, בקשות ותגובות מתזווגות בסדר הגעה לכל סוכן — וקריאות מקבילות מתזווגות בצורה שגויה, ומצרפות כל תגובה לבקשה הלא נכונה. + + +## דוגמה + +לולאת קריאת כלי כנגד ה-OpenAI API, ללא פריימוורק סוכנים: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +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 + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +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 + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +זה מייצר את אותם ששת סוגי אירוע שמתאם היה נותן לך. הגרסה הרצה המלאה, עם הגדרות הכלים, משפנה ב-SDK repository תחת +`docs/manual/examples/`. + +## חוטים ו-async + +משתנות context מתפשטות לתוך asyncio tasks באופן אוטומטי. הן לא מתפשטות לתוך חוטים חדשים, כי חוט מתחיל עם context ריק. + +```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 מדולל על ידי ingest וענות `200`, שזה הכשל שקט שלנו שה-identity layer קיים כדי למנוע. + +## הוסף מעקב לפריימוורק ללא מתאם + +כל סוכן פריימוורק נותן לך את אותם שלושה seams. מפה אותם ויש לך עקבות מלא — ארבעת המתאמים המספקים לא עושים יותר מזה. + +| ה-seam | מה שאתה כותב | מה נחיתה | +| --- | --- | --- | +| ה-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) + ``` + + + בכל מה שהפריימוורק קורא 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(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **יש node, step או middleware boundary שחייב להיות נראה?** עטוף אותו בזוג hook — `hook_triggered` / `hook_completed` — לא nested `agent()`. `agent_id` הוא facet low-cardinality, והערך אחד לכל node טובע אותו. Hook spans מתרנדרים בדרך זהה וגם נותנים לך לטנציה לכל node. + + + + **ידני והאוטומטי מרכיבים.** מתאם שנמצא בתוך scope כתוב ביד מצטרף לשיוך זה ומוריש לסוכן זה, כך שאתה מקבל עץ אחד ולא שניים — שימושי כאשר אתה מעביר מסגרת אחת בעצמך לצד אחד בעל תמיכה. + + + + שתי סיבות, והשלושת ה-seams למעלה הן התשובה לשניהם: + + - `autogen-core` לא תופסת תחזוקה מ-September 2025. + - AG2 לא חושף נקודת רישום כללית תהליך שווה ערך למשדרים של פריימוורקים אחרים, כך שהוספת מעקב אומר עטיפת כל סוכן בכל אתר בנייה. + + מיפוי ה-seams ביד רושם את אותם אירועים, בדיוק זהה, שמתאם משודר היה עושה. + + +## עומק יותר + +איך ההקלטה למעשה עובדת. כלום מזה לא נחוץ כדי להתחיל. + + + + + +לכל הקלטה אותו צורה: span נפתח, עבודה קינה בתוכו, ולכל אירוע פותח יש אירוע סוגר אחד. + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + C --> E(["agent_end"]) +``` + +ה**זוג** הוא היחידה. כל אירוע סוגר נושא משך זמן SDK מודד מה-opening שלו. + +להלן הרצה אמיתית אחת לכל פריימוורק — תפוסה מהדוגמאות שנמצאות עם ה-SDK, שם מודל מנורמל. שים לב כמה חוזר מקריאה יחידה. + + + + ```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 out-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 14 +5.721s agent_end LangGraph · success + ``` + + Nodes הופכים לזוגות hook, כך שאתה מקבל לטנציה לכל node ללא טביעת הרשימה סוכנים. + + + + ```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 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 out-tok + 9 +5.727s agent_end analyst · success + 10 +5.739s agent_end crew · success + ``` + + `role` של כל סוכן הופך לשם ה-span שלו, כך שלטנציה ו-token spend מתפרקים לפי תפקיד. + + + + ```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 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 + ... second iteration + 26 +7.038s agent_end Agent · success + ``` + + לולאת סוכן עצמה נראית, לא רק קריאות המודל שלו. + + + + ```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 + 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 + 8 +8.119s agent_end agent · success + ``` + + אין זוגות hook: ל-Pydantic AI אין node או step boundary לתחום. + + + + ```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 out-tok + 6 +0.000s agent_end main · success + ``` + + אתה פולט אלה בעצמך. אותם סוגי אירוע, דיוק זהה — זה עולה לך לאתרי קריאה. + + + + + + + +**אין אירוע session-end.** session אינה משהו שאתה סוגר — היא קבוצה של אירועים השיתוף `session_id`. + +סטטוס נגזר מצורת העקבות: + +| סטטוס | מתי | +| --- | --- | +| `ongoing` | לפחות span אחד עדיין פתוח | +| `paused` | `agent_pause` אין לו matching `agent_resume` | +| `error` | כלום לא פתוח, ולפחות אירוע אחד נכשל | +| `done` | כלום לא פתוח, וכלום לא נכשל | + +כך שsession מסתיים כאשר כל זוג סוגר. המתאמים פולטים `agent_end` עבורך, והם סוגרים כל דבר עדיין פתוח ומסימנים אותו לא שלם — הרצה קרוסה מתפזרת כ-`done` עם פער גלוי במקום תלויה לנצח. + + + זה למה session יכול להקיף שתי קריאות. LangGraph `interrupt()` השהה את ה-run, ה-root span בכוונה נשאר פתוח, והקריאה הממשיכה סוגרת אותה. שתי הקריאות הן session אחד. + + + + + + +`session_id` ו-`agent_id` הם אופציונליים בכל שיטת event. בהשמטה, הם מתפזרים מהטווח שוקע: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") +``` + +העברתם בגלוי עדיין עובדת ולוקחת עדיפות. ללא כלום קשור וכלום עברר, הקריאה מגבילה `TypeError` שם את התיקון במקום הפקת אירוע ללא session, אשר ingest היה דלל תוך התשובה `200`. + +טווחים קושרים זהות על משתנות context. אלה מתפשטות לתוך asyncio tasks באופן אוטומטי אך לא לתוך חוטים חדשים — עטוף עובד ב-`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` + +תאימה ראשונה זוכה: + +1. ערך `session_id` מפורש +2. metadata לכל קריאה +3. טווח `session()` שוקע +4. framework metadata +5. framework's שלהם run id + +זה אף פעם לא המצוי בזמן אחד מאלה קיים — id סינתטי היה מפלג הרצה אחת על פני מספר sessions. + +#### שמור `agent_id` low cardinality + +זה ה-facet ראשי בכל משטח dashboard, ו-`LowCardinality(String)` כולונה. ערך לכל run מורידה את הכולונה ומלאה את ה-filter dropdown בערך אחד לכל run. + +מתאמים בטחון כולונה זו עבורך: + +| הפריימוורק מוביל על | הוקלט כ | למה | +| --- | --- | --- | +| `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`, איפה זה נשאר queryable ללא להיות facet. + + + **שמירה זו רק נוגעת בתוויות **הפריימוורק** בחר.** `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` | +| וו | `hook_triggered`, `hook_completed` | +| בני אדם | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| כשלים | `error` | + +איזה פריימוורק רושם מה, נמדד מה-runs למעלה: + +| אירוע | LangGraph | CrewAI | LlamaIndex | Pydantic AI | מותאם אישית | +| --- | :--: | :--: | :--: | :--: | :--: | +| תחילת וסוף סוכן | כן | כן | כן | כן | אתה | +| בקשת מודל ותגובה | כן | כן | כן | כן | אתה | +| שימוש בכלי ותוצאה | כן | כן | כן | כן | אתה | +| וו מתוגבר וסיום | Node | משימה | Step | — | אתה | +| שגיאה | כן | כן | כן | כן | אוטומטי | +| חכיית אדם וקלט | כן | כן | כן | — | אתה | +| השהיית סוכן וחידוש | כן | כן | כן | — | אתה | + +dash פירושו הפריימוורק אין לו כזה קונספט. `human_pause` ו-`human_interrupt` תארו **אדם** פועל על סוכן, אשר אף פריימוורק משדר — הפלוט אלה בעצמך. + + + + + +אירוע אף פעם לא מגיע בודד. אחד פותח span, אחד סוגר אותו, ואירוע הסיום נוצא משך זמן SDK מודד מה-opening. + +| פותח | סוגר | אירוע הסיום נוצא | +| --- | --- | --- | +| `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` | התשובה, וכמה זמן האדם לקח | + + + אירוע פותח ללא סוגר אחד הוא span שלא סיים. השיוך מתרנדר כעדיין פעיל, לנצח, וה-active duration שלו ממשיך לגדול. זה כשל mode לצפות בו כאשר אתה מוסיף מעקב ביד. + + +#### כללי קורלציה + +- חזור על אותו `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` מתקנת הכל, כל ארבעת המתאמים כלול. ה-extras משדרים את **הפריימוורק**, לא את המתאם. + +```python +import failproofai_sdk # עומס כלום חוץ מה-standard library +failproofai_sdk.instrument() # ייבוא רק המתאמים אתה בעצם צריך +``` + +`import failproofai_sdk` הוא חוזה אפס תלויות, אינפורמציה על ידי בדיקה שמתקנת את הגלגלון עם `--no-deps` ועוד שמוכיח אף פריימוורק מגיע ל-`sys.modules`. + + + אין `failproofai_sdk.crewai` תכונה. מתאמים בכוונת לא חשוף על הפרה עליונה חבילה: לוגע אחד היה ייבוא הפריימוורק כ-side effect של גישה תכונה, שבירת אפס תלויות הבטחה. השתמש `instrument()`. + + +```python +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`, לא את רשימת חבילה מותקנת, אז פריימוורק שיש לך מותקן אבל אף פעם לא ייבוא הוא לא מוכן והוא אף פעם לא ייובא בשמך. להראות מה חווט למעלה: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +active() # ('langchain',) +``` + + + **`instrument("crewai")` על מכונה ללא CrewAI לא מגביל.** זה עוקב אזהרה ו-return `()`, אז פריימוורק חמיץ אף פעם לוקח תהליך שגם מהמרות אחרים. + + האזהרה נוצא ה-`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. + + + + **`instrument()` חייב לבוא **אחרי** ייבוא הפריימוורק שלך.** גילוי אוטומטי קורא `sys.modules`, אז קריאה ערומה מעל הייבוא מוצא כלום, מתקן כלום, וחוזר `()`. + + + +```python שגוי +import failproofai_sdk +failproofai_sdk.instrument() # sys.modules אין langchain עדיין -> () + +import langchain # מאוחר מדי, כלום לא חווט +``` + +```python נכון +import langchain # ייבוא הפריימוורק ראשון +import failproofai_sdk + +failproofai_sdk.instrument() # מוצא זה -> ('langchain',) +``` + +```python נכון, order-proof +import failproofai_sdk + +# שם זה ייבוא את המתאם על בקשה, אז זה עובד מכל מקום. +failproofai_sdk.instrument("langchain") +``` + + +קבל את זה שגוי והתהליך פועל עם ה-SDK ייובא, המתאם לכאורה מותקן, ו**לא אירוע אחד פלט**. זה עוקב אזהרה אומר בדיוק זה — אז בדוק לוגים ראשון כאשר run רושם כלום. + + + + + +```mermaid +flowchart LR + A["הסוכן שלך"] --> B["מתאם"] + B --> C["כותב
תור בזיכרון"] + C -->|"כל 0.5s"| D["Spool
JSONL בדיסק"] + D --> E["Failproof daemon"] + E -->|"HTTPS"| F["Cloud"] +``` + +| שלב | משימה | פועל בתוך | +| --- | --- | --- | +| מתאם | תרגם callback פריימוורק לתוך אחד מ-15 סוגי אירוע | התהליך שלך | +| כותב | תור, אצווה, כתיבה JSONL אטומית | התהליך שלך, חוט רקע | +| Spool | Durable handoff, שורד התהליך יציאה | דיסק מקומי | +| Daemon | שומר spool, משלח אצוות, מוחק מה-shipped | המכונה שלך | +| Ingest | מקצה שורה id ו-dedup key, מקדם שאלה כולוניות | Cloud | + +ה-spool הוא מה עושה זה בטוח: סוכן שלך אף פעם לא חסום על הרשת, וCloud outage אומר ספריה גדלה במקום קביעה אירועים. + +כל flush כתוב קובץ אצווה אחד, `.tmp` ראשון, ואז `fsync`, ואז atomic rename: + +```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. + + + **`collector.redact` עושה לא חל ל-SDK אירועים שלך.** זה אף פעם לא רואה אותם. + + +ה-daemon **משלח** אצוות שלך. זה לא פתוח או לשכתב אותם. + +| אירועים | כתוב על ידי | Redacted על ידי `collector.redact`? | +| --- | --- | --- | +| CLI session תחקירי | Daemon | כן | +| וו פעילות | Daemon | כן | +| **הכל ה-SDK פלט** | **התהליך שלך** | **לא** | + +Redaction פועל איפה ה-daemon **כתוב** שלהם אירועים — לא איפה אצוות **משודרים**. כך prompt או tool argument מחזיק API key עדיין מחזיק זה בהגעה. + +זה כוונתי. אלה בעצמך מעקב קריאות, וכתיבה מחדש בטרנזיט יומר את אירועים אתה קבל הם לא אירועים אתה פלט. + + + **אתה שלוט בפעילויות ב-source, בשני מקומות:** + + - כבה לכידת תוכן על המתאם. **שם אפשרות שונה, ומתאם אחד אין אחד** — זה לא אחד כללי אוניברסלי מתג: + - LangChain / LangGraph, Pydantic AI — `capture_content=False` + - LlamaIndex — `capture_messages=False` + - CrewAI — **אין מתג תוכן בכל**; `session_id` היא רק אפשרות שהיא קורא, אז prompts ו-completions תמיד רשום. + + `instrument()` טיול אפשרויות מתאם לא קורא, אז עברור שם שגוי מגביל כלום ושינויים כלום. + - אל תעביר את הסוד ל-`input=` בראשון מקום. + + `collector.redact` הוא לא תחליף לאף אחד מאלה. + + + + **ספריה spool ריקה היא המדינה הבריאה.** אל תשתמש בזה כדי בדוק משלוח. + + +ה-daemon מוחק כל אצווה בתוך milliseconds משליחה, אז `ls` מרוצים collector וש fraction של מה אתה פלט — לא ניתנת להבחנה מ-SDK ש קיבוץ כלום. + +לאשר אירועים באמת נחתו, בדוק את ה-dashboard. לצפות ה-spool תמלא, עצור את ה-daemon ראשון. + + + + + +כל callback פועל בתוך wrapper שלה יחידה משימה היא להגביל מחדש, אז קריאה שלך יושבת בדיוק אחד `try` והכל SDK עושה קורה מחוץ אותה. + +| מה קורה | תוצאה | +| --- | --- | +| hook מגביל | עיתון פעם עם traceback. קריאה שלך לא השפעה | +| אותו hook מגביל שלוש פעמים | זה hook אחד משוביץ לנו התהליך, עם שורה טעות אחד | +| `FAILPROOFAI_SDK_STRICT=1` הוא קביעה | החריגה הוא re-raised במקום | +| פריימוורק גרסה חוץ בדוקו טווח | הזהרות פעם, מהמרות בכל זאת | +| יחיד יכולת היא חמיץ | זה חוק אחד משוביץ, אף פעם כל מתאם | + +ה-default הוא ימין בייצור וחצי בזמן debug, כי זה יכול רק אי פעם הוכח אתה לא קרס. קביעה `FAILPROOFAI_SDK_STRICT=1` לעשות בוליט כשל קול. + + + + + +## בעיות נפוצות + + + + אירוע פותח אין אחד סוגר: `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. + + + + החוט לא אף פעם inherited ה-context. עטוף את ה-callable ב-`failproofai_sdk.propagate()`. ראה [חוטים ו-async](#threads-and-async). + + + + שדות תוספת מיזוג אחרון, אז אחד שנקרא כמו שדה אמיתי כמו `model` או `outcome` היה כתוב על זה ו-שינוי כלונה שמור. Namespace שלך; המתאמים משתמשים `fw_` קידומת. + + + + `agent_id` היא low-cardinality facet ו-אתה שים run id בזה. השתמש תפקיד או node שם ו-שים ה-ID אמיתי בשדה payload. + + + +## הבא + + + + זוגות, ids, session lifecycle, ו-delivery. + + + עקוב סיבתיות דרך ה-session אתה רק תפוסה. + + + LangGraph, CrewAI, LlamaIndex, ו-Pydantic AI. + + \ No newline at end of file diff --git a/docs/he/start/integrations/langchain.mdx b/docs/he/start/integrations/langchain.mdx new file mode 100644 index 000000000..c48208782 --- /dev/null +++ b/docs/he/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain ו-LangGraph" +sidebarTitle: "LangChain ו-LangGraph" +description: "התקן גרפים, צמתים, כלים, retrievers וקריאות מודלים בקריאה אחת." +icon: "/images/frameworks/langchain.svg" +--- + +מתאם אחד משרת את שניהם. LangGraph פועל על מנהל ה-callback של `langchain-core`, כך שהתקנת אחד משלושים מתקינה את השני. + +## התקנה + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +עבור LangChain ללא LangGraph, השתמש ב-`failproofai-sdk[langchain]`. + +נתמך: `langchain-core` 1.4.7 עד 2.0, `langgraph` 1.2 עד 2.0. מחוץ לטווח זה, המתאם עדיין מותקן ומוציא אזהרה פעם אחת. + +## התקנה + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` רושם tracer דרך `langchain_core.tracers.context.register_configure_hook`. LangChain מזריק אותו לכל מנהל callback שהוא בונה, כך שגרפים, כלים ומודלים נתפסים ללא שינוי באתר הקריאה — כולל אלה בתוך ספריות שלא כתבת. + +## מה מתועד + +| LangChain או LangGraph | אירוע Failproof | +| --- | --- | +| ריצה שורש | `agent_start`, `agent_end` | +| צומת LangGraph | `hook_triggered`, `hook_completed` | +| תת-גרף מקומפל | `agent_start`, `agent_end` מקוננים | +| ריצת כלי | `tool_use`, `tool_result` | +| ריצת retriever | `tool_use`, `tool_result`, פלט מסוכם | +| ריצת מודל צ'אט או LLM | `model_request`, `model_response`, עם שימוש בטוקנים | +| טוקנים זורמים | מקופלים לתוך התגובה כספירת חתיכות וזמן לטוקן ראשון. ספירות טוקנים דורשות `ChatOpenAI(stream_usage=True)` — ראה להלן | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, בקורלציה על ה-`Interrupt.id` — כולל כאשר ה-resume מתרחש בתהליך אחר מול אותו checkpointer | +| חריגה לא מטופלת | `error`, אחר כך `agent_end` עם תוצאה `failed` | + +**צומת הופך לכן, לא לסוכן מקונן.** `agent_id` הוא ההיבט הראשוני בכל משטח לוח מחוונים — קידום `retrieve`, `grade_documents` ו-`should_continue` לסוכנים יטביע אותו, ויתייג את ההפעלה לאחר איזה צומת שקרה להריץ תחילה. + +טווחי Hook משדרים באותו אופן ועדיין נותנים לך תצוגת חביון לכל צומת. + + + **שם את הצמתים שלך כל דבר שאתה אוהב.** ריצה של צומת מזוהה על ידי ה*צורה* שלה — ריצה שאינה עלה הנושאת את תג הצעד של LangGraph בעצמו — לעולם לא על ידי שמה. + + +| אתה כותב | מה מתועד | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | הכלי | +| `add_node("ChatOpenAI", ...)` | קריאת המודל | + +שם צומת אחרי הדבר שהוא מריץ היה גורם לאירועי הדבר הזה להיעלם. זה כבר לא קורה. + +### זרימה + +`.stream()` ו-.astream()` אינם פולטים אירועים לכל טוקן. הם משתקללים לתוך `model_response` הסגירה: + +| שדה | נושא | +| --- | --- | +| `fw_chunks` | כמה חתיכות הגיעו | +| `fw_ttft_ms` | זמן לטוקן ראשון | + +### ספירות טוקנים בתגובה זורמת + +עניין נפרד, וקל להחמיץ: OpenAI שולח שימוש רק בתגובה זורמת **כאשר מבוקש**. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # ללא זה, אין טוקנים +``` + +המתאם מתעד מה הכלי הנותן אותו. ללא הדגל הזה, אין כלום להתעד, ו-`model_response` מגיע ללא ספירות טוקנים. + +## דוגמה + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## שם את הטווחים שלך + +כברירת מחדל, הטווח השורש לוקח את שם הגרף בעצמו. עטפו אותו כדי לקבל תווית שבחרת: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +עבור הגדרות רבות סוכנים, קנן את ההיקפים. כל עובד הופך לטווח ילד הנושא `parent_id`: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +שמור על `agent_id` בעלי קרדינליות נמוכה. השתמש בתפקיד או שם צומת, לעולם לא UUID או מחרוזת לכל ריצה. + +## שלוט בהפעלה + +מזהה ההפעלה מתפתר בסדר זה, התאמה ראשונה מנצחת: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. הטווח הסוגר `failproofai_sdk.session()` +4. `metadata["session_id"]`, `metadata["conversation_id"]`, או `metadata["thread_id"]` +5. מזהה הריצה של השורש + +הוא לעולם לא נוצר מאפס, כי מזהה סינתטי מפצל ריצה אחת על פני מספר הפעלות. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## אפשרויות + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # pin every run to one session id + include_chains=set(), # allowlist intermediate chains as hook pairs + capture_content=True, # False drops prompts and completions from payloads + graph_callbacks=True, # first-class interrupt and resume, needs langgraph 1.2+ +) +``` + +קבע `capture_content=False` עבור נתונים מוסדרים. מבנה, תזמוני, ספירות טוקנים, שמות כלים ותוצאות עדיין מתועדות; גופי הודעות אינם. + +`include_chains` חל על ריצות **מקוננות** בלבד. runnable שאתה משדר ברמה העליונה הוא השורש של ההפעלה, כך שהוא הופך לטווח הסוכן ולא לזוג כן, ושמה כאן אין השפעה. + +## בן אדם בלולאה + +`interrupt()` מייצר ארבעה אירועים, וגם זוג אינו עודף: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +`human_wait` ל-`human_input` נושא את הנושא והתשובה (שניהם נשמטים תחת `capture_content=False`, יחד עם מקורות מסמכי retrieval — ספירת המסמכים שורדת). `agent_pause` ל-`agent_resume` הוא הזוג היחיד שמזין זמן מושהה, אז ללא זה מתן אדם בן עשר דקות מחויב כזמן סוכן פעיל. הטווח השורש נשאר פתוח על פני הפער, שומר על שתי הקריאות בהפעלה אחת. + +## בעיות נפוצות + + + + `create_react_agent` מפיץ את החריגה. כדי לתת למודל לראות את הכישלון ולהמשיך, בנה את צומת הכלי במפורש: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + הכישלון מתועד כ-`tool_result` הנושא שגיאה בכל מקרה. זה רק קובע אם הריצה שורדת אותה. + + + + `llm.invoke()` ישיר מחוץ לגרף כלשהו אין ריצת הורה, כך שהוא פותח טווח שורש ופולט זוג המודל שלו בתוכו. לוח המחוונים משדר עלים לסוכן פתוח, כך שהטווח הוא כוונתי. שם אותו: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + עברת טוכן Failproof ב-`config={"callbacks": [...]}` וגם קראת `instrument()`. הסר אותו. ה-configure hook כבר מכסה כל מנהל callback בתהליך. + + + + הם לא. LangGraph מעלה `GraphInterrupt` דרך אותה נתיב כמו חריגה אמיתית, כך שכל השהיה מגיעה לעוקב כקריאת שגיאה. כל תת-סוג `GraphBubbleUp` מטופל כזרימת בקרה במקום זאת, כך שאישור לא צובע שגיאה אדומה. + + + + בדוק בסדר זה: `instrument()` רץ לפני שהגרף הוצא; יש `with failproofai_sdk.session():` סביב הקריאה; `FAILPROOFAI_SDK_STRICT=1` קבוע, כך שכן שהוגדל מעלה במקום להיות ספוג. + + + +## הבא + + + + זוגות, מזהים, מחזור חיי ההפעלה וההופעה. + + + עקוב את הסיבתיות דרך ההפעלה שרק תפסת. + + + CrewAI, LlamaIndex, Pydantic AI וסוכנים מותאמים אישית. + + \ No newline at end of file diff --git a/docs/he/start/integrations/llamaindex.mdx b/docs/he/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..267cc8c80 --- /dev/null +++ b/docs/he/start/integrations/llamaindex.mdx @@ -0,0 +1,250 @@ +--- +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "Instrument workflows, steps, function agents, and retrievers." +icon: "/images/frameworks/llamaindex.svg" +--- + +## התקנה + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +תומך: `llama-index-core` מגרסה 0.14.23 עד 0.15. 0.14.23 היא הגרסה בה stream זרימת workflows התחיל לשאת אירועי agent מסוגים שהמתאם קורא. מתחתיו, שמות מודלים ומבנה agent שניהם חסרים. + +## Instrument + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +ממשק ה-agent של LlamaIndex הוא async. כל scope עובד תחת `async with` וגם `with` ומייצר אירועים זהים. + +`instrument()` מצרף event handler ו-span handler ל-global dispatcher של LlamaIndex. ביחד הם הופכים את agent loop לנראה, לא רק את קריאות המודל שלו. + + + ללא ארגומנט נוסף אחד ב-LLM שלך, כל ספירת tokens בעקבות שלך היא null. ראה [Token counts](#token-counts) למטה. + + +## ספירת Tokens + +`FunctionAgent` קורא ל-`astream_chat`, ו-`llama-index-llms-openai` לא שולח `stream_options={"include_usage": True}` כשהוא משדר. ספק זה לכן לעולם לא שולח את usage chunk, ואין לשום instrumentation מה לקרוא. + +זו התנהגות upstream של LlamaIndex. הצטרף לשימוש ב-LLM שלך: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +נמדד באותה הרצה ומודל: + +| | Input tokens | Output tokens | +| --- | --- | --- | +| Without | `null` | `null` | +| With | 148 | 17 | + +קריאות ללא streaming (`llm.chat`, `llm.achat`) דווחו על usage ללא תצורה. רק נתיב ה-streaming, שהוא נתיב ה-agent ברירת המחדל, זקוק לזה. + +## מה מתועד + +| LlamaIndex | Failproof event | +| --- | --- | +| `Workflow.run` root span | Session, `agent_start`, `agent_end` | +| Nested `Workflow.run` span | Nested `agent_start`, `agent_end` | +| Workflow step span | `hook_triggered`, `hook_completed` | +| LLM chat start and end | `model_request`, `model_response` | +| `FunctionTool.call` span | `tool_use`, `tool_result` | +| Retrieval start and end | `tool_use`, `tool_result`, output summarized | +| Embeddings | Nothing, unless `embeddings=True` | +| A tool waiting on a person | `human_wait`, `agent_pause`, then `agent_resume`, `human_input` | +| `AgentWorkflow` handoff | A nested `agent_start`, `agent_end` per agent, parented to the workflow | +| Exception | `error`, then `agent_end` with outcome `failed`, and `agent_end.summary` naming it | +| `handler.cancel_run()` | `agent_end` with outcome `cancelled` and no `error` — a stop button is not a failure | + +`agent_id` הוא `FunctionAgent.name` כאשר אתה קובע אחד, ושם מחלקת workflow אחרת. תחת `AgentWorkflow`, כל agent שלוקח תור מקבל span nested משלו תחת workflow, כך handoff קורא כשני agents ולא אחד. + +פלט retrieval מסוכם ולא מודפס. retriever מחזיר מסמכים, והשמירה שלהם ב-payload תשים את הקורפוס שלך בחנות ארועים פעם אחת לכל שאילתה. הספירה, טווח ציון וקטעי קוד קצוצים נשמרים במקום. + +## דוגמה + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +agent loop מופיע ב-trace כזוגות hook: `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool`, ו-`aggregate_tool_results`. הם הלולאה של הפריימוורק שלו, כך שהם hooks ולא agents, שמשמר את `agent_id` משמעותי. + +## שם את Spans שלך + +`agent_id` הוא `FunctionAgent.name` כאשר אתה קובע אחד, ושם מחלקת workflow אחרת. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +ב-`AgentWorkflow`, שם זה הוא גם מה שכל handoff מתועד תחתיו: + +```text +AgentWorkflow parent span +├─ city_analyst turn 1 +├─ cost_analyst turn 2 +└─ city_analyst turn 3 — a new turn, not a reopened one +``` + +אז `agent_id` אומר לך **איזה agent** עשה את העבודה ו-`parent_id` אומר לך **איזה workflow** הוא שייך. agent שהחזיר שליטה מאוחר יותר פותח תור שני ולא מפתח מחדש את הראשון שלו. + +עטף את ההרצה כדי לעקוף זאת, או לקבץ כמה agents תחת parent אחד: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +שמור `agent_id` cardinality נמוכה. זה הפן הראשי על כל משטח dashboard, אז השתמש בתפקיד או שם workflow, לעולם לא UUID או per-run string. + +## שלוט בסשן + +מתאם זה **לא לוקח אפשרות `session_id`**. הסשן מגיע מ-scope המקיף, ואחרת generated `uuid4().hex` לכל workflow run: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## אפשרויות + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True records embedding calls as tool pairs + steps=True, # False drops workflow-step hook pairs + capture_messages=True, # False drops EVERY payload: prompts, completions, + # tool arguments and output, step I/O, retrieval + # queries, the goal and the final answer + capture_limit=8192, # characters kept per captured value + stale_after=600.0, # seconds before an abandoned LEAF is force-closed + reaper_interval=30.0, # how often the reaper sweeps; 0 disables it +) +``` + +| Option | Why you would change it | +| --- | --- | +| `embeddings` | הפעל רק כשאתה ניפוי שגיאות latency או עלות embedding. בנייה של bulk index היא אלפים של קריאות וקוברת את ציר הזמן. | +| `steps` | כבה אם אתה רוצה רק אירועי מודל וכלים ומוצא את agent loop רועש. | +| `capture_messages` | כבה עבור נתונים מוסדרים. כל payload מפסיק להיות מתועד — prompts, השלמה המודל, ארגומנטי כלים וערכי החזרה, workflow-step input ו-output, sherieval queries, goal של agent ותשובתו הסופית. מבנה, timings, tokens ו-outcomes עדיין מתועדים. | +| `capture_limit` | תווים שמורים לכל ערך מתועד לפני קיצוץ. הרם אותו כאשר RAG prompt או context שהוחזר הגיע קטום. | +| `stale_after` | שניות לפני **leaf** שנטוש — תגובה streaming שלא אחד צרך, מודל או tool span ש-close שלו לעולם לא הגיע — force-closed, אז הסשן מתישב בעדו קריאה `ongoing` לנצח. זה **לא** סוגר run שנטוש עצמו: workflow שהמשימה שלו בוטלה ללא dispatcher שרואה exit מישמרת את `agent_start` שלה פתוח עד `uninstrument()`. | +| `reaper_interval` | תדר כינוס. קבע ל-`0` כדי להשבית את reaper לחלוטין. | + +## Human in the loop + +מתועד כאשר ההמתנה קורית בתוך כלי: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +`ctx.wait_for_event` בשלב workflow רגיל לא מתועד. runtime תופס את הירידה לפני שהוא מגיע ל-dispatcher, כך שהשלב יוצא וריצה מחדש מאוחר יותר ללא אות לקבוע pause על. דפוס FunctionAgent, שלמי אינדקס תיעוד, מחכה בתוך כלי ומתועד במלואו. + +## בעיות נפוצות + + + + הוסף `additional_kwargs={"stream_options": {"include_usage": True}}` ל-LLM שלך. ראה [Token counts](#token-counts). + + + + LlamaIndex אין שדה usage סטנדרטי. המתאם מנסה כמה צורות ידועות, ואינטגרציה שקוראת לדלפקים שלה משהו חדש לא תתאים לאחד מהם. + + dict גולמי תמיד משלח, אז בדוק `usage` ב-payload כדי לראות מה הספק קרא להם. + + `usage` מלא לצד עמודות token ריקות הוא בכוונה — זה הביס מספר שגוי בטוח. + + + + זה הלולאה FunctionAgent, סט אחד לכל איטרציה. סנן לפי hook name בדשבורד. timings שלב אלה בדרך כלל הסיבה להשתמש במתאם זה ולא באחד רק-מודל. + + + + בדוק בסדר זה: `instrument()` רץ לפני ההרצה; יש `async with failproofai_sdk.session():` סביב `await`; `llama-index-core` הוא 0.14.23 או יותר חדש; `FAILPROOFAI_SDK_STRICT=1` מוגדר, אז hook משוער מעלה במקום להיבלע. + + + +## הבא + + + + Pairs, ids, session lifecycle, and delivery. + + + עקוב סיבתיות דרך הסשן שזה עתה תפסת. + + + LangGraph, CrewAI, Pydantic AI, and custom agents. + + \ No newline at end of file diff --git a/docs/he/start/integrations/pydantic-ai.mdx b/docs/he/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..685b36d59 --- /dev/null +++ b/docs/he/start/integrations/pydantic-ai.mdx @@ -0,0 +1,209 @@ +--- +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "הגן על אג'נטים מוקלדים, כלים, קריאות מודל וניסיונות חוזרים." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## התקנה + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +נתמך: `pydantic-ai-slim` 2.0 עד 3.0. גרסה 2.0 הסירה את `Agent(instrument=...)` והציגה את פרוטוקול ההיכולת שעליו בנוי המתאם הזה, ולכן לא ניתן לבצע אינסטרומנטציה של 1.x בדרך זו. + +## אינסטרומנטציה + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # לפני בנייה של Agent כלשהו + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` חייב להריץ לפני שאתה בונה `Agent`. ההיכולת מתווספת בזמן הבנייה, ולכן אג'נט שנבנה קודם לכן לא נושא אחת וכלל לא מתעד דבר, ללא שגיאה כיוון שלא קרה שום דבר רע. זו הסיבה השכיחה ביותר לעקבה ריקה עם המתאם הזה. + + +אג'נטים בהיקף מודול הם המקום שבו זה משתולל: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # בנוי בזמן ייבוא + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # הרץ את זה ראשון +import agents # עכשיו האג'נט מקבל את ההיכולת +``` + +אשר שזה עבד: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI מציבה את הרשימה שאתה מעביר להיכולת `root_capability` יחידה, ולכן אין תכונת `agent.capabilities` שניתן לקרוא. + +אג'נטים שנבנו תוך כדי אינסטרומנטציה שומרים על ההיכולת, ולכן תוכל להפעיל `uninstrument()` ולהמשיך לאינסטרומנטציה ללא בנייה מחדש. + +## מה מתעד + +| Pydantic AI | אירוע Failproof | +| --- | --- | +| הרצת אג'נט | `agent_start`, `agent_end` | +| בקשת מודל | `model_request`, `model_response`, עם שימוש בטוקנים | +| קריאת כלי | `tool_use`, `tool_result`, עם הטיעונים שהמודל שלח | +| `ModelRetry` מכלי | `tool_result` המנשא שגיאה | +| חריג שלא טופל | `error`, ואז `agent_end` עם תוצאה `failed` | + +אין כאן זוג hook ואין זוג human-in-the-loop. Pydantic AI אין לו גבול node או step שיש לתחום ואין הפסקה בנויה של בן אדם, ולכן אין מה למפות. אם תבנה כל אחד מהם, פלוט את האירועים בעצמך — ראה [אג'נטים מותאמים אישית](/he/reference/custom-agents). + +`output_type` לא משנה את העקבה. ריצה מוקלדת וריצה של מחרוזת מייצרות את אותם אירועים. + +## דוגמה + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +בעקבה, `restock_eta` מופיע כ-`tool_result` המנשא שגיאה, ואחריו קריאת מודל נוספת שבה האג'נט עובד סביב זה, והריצה עדיין מסתיימת ב-`success`. שני העובדות נשמרות. + +## שגיאות, ניסיונות חוזרים וזרימת בקרה + +Pydantic AI משמיע חריגים בשלוש דברים שונים, והמתאם מפריד ביניהם: + +| חריג | מטופל כ | תוצאה | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | כשל כלי אמיתי | `tool_result` עם שגיאה; הריצה עדיין יכולה להסתיים ב-`success` | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | זרימת בקרה | לא שגיאה; הריצה מונחית | +| כל דבר אחר | כשל | `error`, ואז `agent_end` עם תוצאה `failed` | + +`ModelRetry` נמצא בקבוצה הראשונה בכוונה. זה אומר שניסיון באמת נכשל ובמודל בקשו לנסות שוב, וזה בדיוק מה ששדה השגיאה של span של כלי מיועד לעשות. סיווג זה כזרימת בקרה היה מסתיר כשלי כלי אמיתיים מאחורי ריצה ירוקה. + +## שמות את ה-spans שלך + +ה-span של ריצה של Pydantic AI עצמו נקרא `agent`. עטוף את הקריאה כדי לתן לה תווית שבחרת: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +ה-span של הframe-work אז קינן תחת `inventory`, וזה המקום שבו אירועי המודל והכלים תלויים. + +שמור `agent_id` בקרדינליות נמוכה. זו הפן הראשוני על כל משטח לוח מחוונים, ולכן השתמש בשם תפקיד, אפילו לעולם לא UUID או מחרוזת לכל ריצה. + +## שלוט בחסות + +הורה בסדר זה, ההתאמה הראשונה ניצחת: + +1. `instrument("pydantic_ai", session_id=...)` +2. היקף `failproofai_sdk.session()` המקיף +3. ה-`conversation_id` של הריצה, ואז ה-`run_id` שלה +4. `uuid4().hex` שנוצר + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## אפשרויות + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # הצמד כל ריצה לזיהוי חסות אחד + capture_content=True, # False מוריד הנמכות ותשלומים מעומסים +) +``` + +## בעיות נפוצות + + + + ה-`Agent` בנוי לפני שה-`instrument()` הופעל. ראה את ההתראה לעיל, ובדוק את `agent.root_capability.capabilities`. + + + + `raise` חשוף הוא מתפשט; זה עיצוב של Pydantic AI. כדי לתת למודל לעבוד סביב זה, הרם `ModelRetry` עם הודעה שהיא יכולה לפעול עליה. הכשל מתועד בכל מקרה. + + + + הילד הוא span ריצה של Pydantic AI עצמו, וזה המקום שבו אירועי המודל והכלים תלויים. שחרר את ההיקף שלך אם אתה רוצה span יחיד, במחיר השם המותאם. + + + + ערימת הגרף האסינכרונית של Pydantic AI ארוכה יותר מגבול שדה העומס, וקו האחרון של traceback הוא החריג עצמו. שדה זה קוצץ מהחזית ולא מהגב, ולכן הקו שאתה צריך שורד. + + + +## הבא + + + + זוגות, מזהים, מחזור חיים של חסות וסילוק. + + + עקוב אחר סיבתיות דרך החסות שרק תפסת. + + + LangGraph, CrewAI, LlamaIndex, ואג'נטים מותאמים אישית. + + \ No newline at end of file diff --git a/docs/he/start/quickstart.mdx b/docs/he/start/quickstart.mdx index f384baed7..2e27d13e5 100644 --- a/docs/he/start/quickstart.mdx +++ b/docs/he/start/quickstart.mdx @@ -1,53 +1,53 @@ --- title: "התחלה מהירה" -description: "תפסו הפעלת סוכן, מצאו כשל וקחו צעדים למנוע אותו." +description: "תופס סשן של סוכן, מוצא כשל, והתחל למנוע אותו." icon: "zap" --- -התחלה מהירה זו מגדירה מכונה אחת לדיווח הפעלות, מריצה ביקורת ויוצרת פריסה של מדיניות. השתמשו בכישוריות כדי להגדיר את Failproof AI, או עקבו אחר השלבים הידניים. +התחלה מהירה זו מגבילה מכונה אחת לדיווח סשנים, מפעילה ביקורת, וממשנת מדיניות. השתמש בכישרון כדי להגדיר את Failproof AI, או עקוב אחר השלבים הידניים. -**איזה מסלול שלך?** אם הסוכן שלך פועל באחד מ-12 [harnesses](/he/reference/harnesses) הנתמכים — CLI קידוד, או gateway כמו Hermes או OpenClaw — עקבו אחר השלבים להלן; אתם זקוקים ל-Node.js 20.9 או חדש יותר. אם לסוכן שלך אין harness, אנו מציעים לכם להשתמש ב-[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 ``` - + ```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. העתק את הסוד החד-פעמי ושמור אותו במכונת היעד: ```bash export FAILPROOFAI_KEY="" ``` - ## התקנה + ## התקן - + ```bash npm install -g failproofai failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - תמלילי הפעלות נשלחים כברירת מחדל. הוסיפו `--no-transcripts` כדי לדווח על פעילות hook והחלטות מדיניות ללא תוכן תמלילים. + תמלילי סשן נשלחים כברירת מחדל. הוסף `--no-transcripts` כדי לדווח על פעילות hook והחלטות מדיניות ללא תוכן תמלילים. - אם למכונה זו כבר יש היסטוריה של סוכן, הצג בחזקה ויבוא את שבעת הימים האחרונים, ואז חכו להשלמת המסירה. דלגו על שלב זה במכונה חדשה. + אם למכונה זו יש כבר היסטוריה של סוכן, תצפה וייבא את שבעת הימים האחרונים, ואז חכה שההסגרה תסתיים. דלג על שלב זה במכונה חדשה. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - פתחו את **Sessions** ב-Failproof AI ובחרו בהפעלה מיובאת. + פתח את **Sessions** ב-Failproof AI ובחר סשן שיובא. - - זה מחבר את Failproof AI ל-harness שלכם ומתקין את 40 המדיניות המובנות. השתמשו בהן כדי לראות החלטות מדיניות מקומיות ולנסות אכיפה לפני שFailproof AI מבקרת בהפעלות שלכם ורושמת מדיניות לסוכנים שלכם. + + זה מחבר את Failproof AI למנשק שלך ומתקין את 40 המדיניויות המובנות. השתמש בהם כדי לראות החלטות מדיניות מקומיות ולנסות אוכיפוי לפני שFailproof AI מבקר בסשנים שלך וכותב מדיניויות לסוכנים שלך. - תנו להתקנה לזהות את ה-harness שלכם, או שמו אחד בבירור. כל אחד מ-12 הוא ערך חוקי של `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + תן למתקין לגלות את המנשק שלך, או תן שם למשהו באופן מפורש. כל אחד מ-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 — ראו [יכולת אכיפה](/he/reference/harnesses#enforcement-capability) למטריקס לפי harness. + חסימת קריאת כלי לפני שהיא פועלת מתאומתת בכל 12. שערי סוף תור מתאומתים ב-8 — ראה [יכולת אוכיפוי](/he/reference/harnesses#enforcement-capability) למטריצת ההפעלה לכל מנשק. - - עקבו אחר [הריצה של בדיקת הכשל הראשונה שלכם](/he/start/first-audit). השתמשו במטרה קונקרטית כמו "מצאו הפעלות שבהן הסוכן ניסה מחדש כלי שנכשל ללא שינוי בגישתו." + + עקוב אחר [הפעל את בדיקת הכשל הראשונה שלך](/he/start/first-audit). השתמש במטרה קונקרטית כגון "מצא סשנים שבהם הסוכן ניסה שוב כלי שנכשל ללא שינוי בגישתו." - - עקבו אחר [מנעו את הכשל הראשון שלכם עם מדיניות](/he/start/first-policy). התחילו במצב צפייה, בדקו התאמות, ואז אכוף את הגרסה שבדקתם. + + עקוב אחר [מנע את הכשל הראשון שלך עם מדיניות](/he/start/first-policy). התחל במצב צפייה, בדוק התאמות, ואז אוכף את הגרסה שנבדקה. - הריצו `failproofai config --status`. הגדרה בריאה מדווחת על חיבור הענן, מצב הדימון ואם אכיפה מושהית. + הפעל `failproofai config --status`. הגדרה בריאה מדווחת על חיבור הענן, מצב daemon, ואם אוכיפוי מושהה. \ No newline at end of file diff --git a/docs/he/start/quickstarts/crewai.mdx b/docs/he/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..249bad079 --- /dev/null +++ b/docs/he/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "התקן, כיול, וראה את העקבות הראשונים שלך." +icon: "/images/frameworks/crewai.svg" +--- + +שלוש שלבים לעקבות CrewAI הראשונים שלך. לקבלת פרטים על כל אירוע, זרימות וטיפול בבעיות, ראה [את המדריך המלא](/he/start/integrations/crewai). + +## התקנה + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## כיול + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +שום דבר בקבוצה, סוכנים, משימות או כלים שלך לא משתנה. `instrument()` מירתם לאוטובוס האירועים ברמת המודול של CrewAI. + +## בדוק שהגיע + +הרץ פעם אחת, ואז פתח **Observe → Sessions** ובחר את הסביבה שלך. ההרצה שלך מופיעה כעקבות משוחזר. + +אם כלום לא הגיע, אשר שהמכונה מחוברת עם `failproofai config --status`. + + + מה מתועד, זרימות, שימוש בטוקנים, שמות span, אפשרויות, והבעיות הנפוצות. + \ No newline at end of file diff --git a/docs/he/start/quickstarts/custom-agents.mdx b/docs/he/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..b4330229f --- /dev/null +++ b/docs/he/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "סוכנים מותאמים" +description: "עטוף את הסוכן שלך בשלוש בלוקי `with` והוא יתחיל להקליט." +icon: "code" +--- + +עבור סוכן שכתבת בעצמך, או framework שלFailproof AI אין לו adapter עבורו. + +אתה עוטף את העבודה שכבר עושה בבלוקי `with`. כל אחד מהם מקליט מתי התחיל, מתי סיים, וכמה זמן זה לקח — אתה לא קורא לשום דבר אחר. + +## התקנה + +```bash +pip install failproofai-sdk +``` + +ללא extras, וללא dependencies. + +## 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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # one tool call +``` + +קרא את זה מלמעלה למטה וזה אומר מה זה אומר: + +| עטוף את זה ב | כדי לומר | +| --- | --- | +| `session()` | אירועים אלה שייכים לאותו run | +| `agent()` | משהו עושה עבודה — תן לו שם שהיית מזהה ברשימה | +| `tool_call()` | זה כלי אחד, וזה מה שהוא החזיר | + +קנן אותם איך שהקוד שלך קנן. אתה לא עובר ids סביב: כל בלוק זוכר מה הוא בתוך זה, אז כל דבר שאתה מקליט בוחר את ה-run הנכון ואת הסוכן הנכון בעצמו. `async with` עובד בדיוק אותו הדבר. + +## בדוק שהגיע + +הרץ את זה פעם אחת, ואז פתח **Observe → Sessions** ובחר את הסביבה שלך. ה-run שלך מופיע כ-trace משוחזר. + +אם שום דבר לא מגיע, אשר שהמכונה מחוברת עם `failproofai config --status`. + + + כל שיטת אירוע, מה קורה כשהקוד שלך מעלה חריגות, דוגמה מעובדת, threads ו-async, וביצוע instrument של framework ללא adapter. + \ No newline at end of file diff --git a/docs/he/start/quickstarts/langchain.mdx b/docs/he/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..2186b2364 --- /dev/null +++ b/docs/he/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain ו-LangGraph" +description: "התקנה, אינסטרומנטציה וצפייה בעקבות הראשון שלך." +icon: "/images/frameworks/langchain.svg" +--- + +שלוש שלבים לעקבות LangChain או LangGraph הראשון שלך. עבור streaming, human-in-the-loop, span naming ואפשרויות נוספות, ראה [את המדריך המלא](/he/start/integrations/langchain). + +## התקנה + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +עבור LangChain ללא LangGraph, השתמש ב-`failproofai-sdk[langchain]`. + +## אינסטרומנטציה + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +ללא שינויים בנקודות הקריאה. `instrument()` רושם tracer שמוזן ב-LangChain לכל callback manager שהוא בונה, כך שגרפים, כלים ומודלים נתפסים — כולל אלה בתוך ספריות שלא כתבת. + +## בדוק שהגיע + +הרץ פעם אחת, ואז פתח את **Observe → Sessions** ובחר את הסביבה שלך. ההרצה שלך מופיעה כעקבות שפורקו. + +אם לא הגיע דבר, אשר שהמחשב מחובר עם `failproofai config --status`. + + + מה מתועד, streaming, token counts, span naming, session control, אפשרויות ו-human in the loop. + \ No newline at end of file diff --git a/docs/he/start/quickstarts/llamaindex.mdx b/docs/he/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..53d33f4c0 --- /dev/null +++ b/docs/he/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "התקנה, כלי עבודה, וראה את העקבה הראשונה שלך." +icon: "/images/frameworks/llamaindex.svg" +--- + +שלוש שלבים לעקבה LlamaIndex הראשונה שלך. עבור שלבי זרימת עבודה, אחזור, ה-reaper, ואפשרויות, ראה [את המדריך המלא](/he/start/integrations/llamaindex). + +## התקנה + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## כלי עבודה + +ה-agent API של LlamaIndex הוא אסינכרוני. כל scope עובד גם תחת `async with` וגם `with`. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + ללא ארגומנט נוסף אחד ב-LLM שלך, כל ספירת tokens בעקבה שלך היא null — `llama-index-llms-openai` לא מבקש שימוש כאשר הוא משדר. ראה [ספירות tokens](/he/start/integrations/llamaindex#token-counts). + + +## בדוק שזה הגיע + +הרץ זה פעם אחת, ואז פתח **Observe → Sessions** ובחר את הסביבה שלך. ההרצה שלך מופיעה כעקבה משוחזרת. + +אם לא מגיע כלום, אשר שהמכונה מחוברת עם `failproofai config --status`. + + + ספירות tokens, מה מתועד, שלבי זרימת עבודה, אחזור, אפשרויות, ובעיות נפוצות. + \ No newline at end of file diff --git a/docs/he/start/quickstarts/pydantic-ai.mdx b/docs/he/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..0fe4a9248 --- /dev/null +++ b/docs/he/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "התקן, הגדר instrumentation, וראה את ה-trace הראשון שלך." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +שלוש צעדים ל-trace של Pydantic AI הראשון שלך. עבור tools, retries, streaming, ואפשרויות נוספות, ראה [את המדריך המלא](/he/start/integrations/pydantic-ai). + +## התקנה + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## Instrumentation + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # לפני בניית Agent כלשהו + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` חייב לרוץ **לפני** שאתה בונה `Agent`. היכולת מתווספת בעת הבנייה, כך שעבור agent שנבנה קודם לכן לא יתועד שום דבר — בלא שגיאה, כי לא קרה שום דבר לא תקין. זו הסיבה הנפוצה ביותר ל-trace ריק עם ה-adapter הזה, וזה קורה במיוחד עם agents בהיקף המודול: import את `failproofai_sdk` וקרא ל-`instrument()` לפני import של המודול שבונה אותם. + + +## בדוק שהגיע + +הרץ אותו פעם אחת, ואז פתח **Observe → Sessions** ובחר את ה-environment שלך. ה-run שלך מופיע כ-trace שנבנה מחדש. + +אם כלום לא הגיע, אשר שהמכונה מחוברת עם `failproofai config --status`. + + + מה מתעד, tools ו-retries, streaming, naming של spans, אפשרויות, ובעיות נפוצות. + \ No newline at end of file diff --git a/docs/hi/index.mdx b/docs/hi/index.mdx index f91279504..eced1749e 100644 --- a/docs/hi/index.mdx +++ b/docs/hi/index.mdx @@ -1,42 +1,42 @@ --- --- -title: "अपने एजेंट को विफलता-प्रतिरोधी बनाएं" -description: "प्रत्येक हार्नेस के लिए अवलोकनशीलता और प्रवर्तन जिसमें आपके एजेंट चलते हैं — कोडिंग CLIs, चैट गेटवे, स्वयं-होस्ट किए गए सहायक, और आपके स्वयं के साधन एजेंट।" +title: "अपने एजेंट को फेलप्रूफ बनाएं" +description: "प्रत्येक हार्नेस के लिए अवलोकनीयता और प्रवर्तन जिसमें आपके एजेंट चलते हैं — कोडिंग CLIs, चैट गेटवे, स्व-होस्ट किए गए सहायक, और आपके स्वयं के इंस्ट्रूमेंटेड एजेंट।" icon: "shield-check" --- -Failproof AI टीमों को यह समझने में मदद करता है कि एजेंट ने क्या किया, वह कहां विफल हुआ, और समान व्यवहार होने से पहले सुरक्षा उपाय तैनात करें। +Failproof AI टीमों को यह समझने में मदद करता है कि एजेंट ने क्या किया, वह कहां विफल हुए, और एक ही व्यवहार दोबारा होने से पहले सुरक्षा उपाय तैनात करें। -एक **हार्नेस** वह है जिसके अंदर आपका एजेंट वास्तव में चलता है। Failproof AI 12 में हुक करता है — कोडिंग CLIs जैसे Claude Code और Codex, चैट गेटवे जैसे Hermes, स्वयं-होस्ट किए गए सहायक जैसे OpenClaw — और समान इवेंट, समान नीतियां, और समान सेशन इतिहास सभी पर लागू होते हैं। कोई हार्नेस न होने वाले एजेंट [Python SDK](/hi/reference/custom-agents) के माध्यम से रिपोर्ट करते हैं, जो उन्हें ट्रेस और ऑडिट करता है; वहां एक नीति को लागू करने के लिए आपके स्वयं के रनटाइम में एक हुक की आवश्यकता है। +एक **हार्नेस** वह है जिसमें आपका एजेंट वास्तव में चलता है। Failproof AI 12 को हुक करता है — कोडिंग CLIs जैसे Claude Code और Codex, चैट गेटवे जैसे Hermes, स्व-होस्ट किए गए सहायक जैसे OpenClaw — और समान घटनाएं, समान नीतियां, और समान सत्र इतिहास हर एक पर लागू होते हैं। बिना हार्नेस वाले एजेंट [Python SDK](/hi/reference/custom-agents) के माध्यम से रिपोर्ट करते हैं, जो उन्हें ट्रेस और ऑडिट करता है; वहां एक नीति को लागू करने के लिए आपके स्वयं के रनटाइम में एक हुक की आवश्यकता होती है। - - अपनी परियोजना को साधन करने, इसे कनेक्ट करने, और यह सत्यापित करने के लिए कौशल का उपयोग करें कि एजेंट लॉग आते हैं। + + अपनी परियोजना को इंस्ट्रूमेंट करने, इसे कनेक्ट करने और एजेंट लॉग आने की पुष्टि करने के लिए कौशल का उपयोग करें। - अपने एजेंट लॉग पर प्राकृतिक भाषा में विश्लेषण करें, क्वेरी करें, डैशबोर्ड बनाएं, और ऑडिट चलाएं। + प्राकृतिक भाषा में अपने एजेंट लॉग पर विश्लेषण करें, प्रश्न पूछें, डैशबोर्ड बनाएं, और ऑडिट चलाएं। - - एक सेशन में मॉडल कॉल, टूल, त्रुटियां, मानव इनपुट, लेटेंसी, और नीति निर्णयों का अनुसरण करें। + + मॉडल कॉल, उपकरण, त्रुटियां, मानव इनपुट, विलंबता, और नीति निर्णयों को एक सत्र में अनुसरण करें। - सेशन के एक परिभाषित समूह को ऑडिट करें, साक्ष्य-समर्थित निष्कर्षों की समीक्षा करें, और उपचार को समस्याओं के रूप में ट्रैक करें। + सत्रों के एक परिभाषित सेट का ऑडिट करें, साक्ष्य-समर्थित निष्कर्षों की समीक्षा करें, और उपचार को मुद्दों के रूप में ट्रैक करें। - एक ज्ञात विफलता मोड को नीति में बदलें, इसके प्रभाव को देखें, और इसे अपने पूरे बेड़े में तैनात करें। + एक ज्ञात विफलता मोड को एक नीति में बदलें, इसके प्रभाव का अवलोकन करें, और इसे अपने पूरे बेड़े में तैनात करें। -> **सेशन → ऑडिट → खोज → समस्या → नीति**
-> ट्रेस करें कि क्या हुआ, विफलता खोजें, प्रतिक्रिया प्रबंधित करें, फिर भविष्य के रन में समान व्यवहार को रोकें। +> **सत्र → ऑडिट → निष्कर्ष → मुद्दा → नीति**
+> ट्रेस करें कि क्या हुआ, विफलता खोजें, प्रतिक्रिया का प्रबंधन करें, फिर भविष्य के रन में समान व्यवहार को रोकें। -## यहां से शुरू करें +## यहाँ से शुरू करें -यदि आप अपने पहले साधन एजेंट को तैनात कर रहे हैं, तो [quickstart](/hi/start/quickstart) के साथ शुरू करें। यदि डेटा पहले से आ रहा है, तो [सेशन](/hi/sessions/overview) खोलें और ऑडिट या नीतियों को कॉन्फ़िगर करने से पहले एक वास्तविक रन का निरीक्षण करें। +यदि आप अपना पहला इंस्ट्रूमेंटेड एजेंट तैनात कर रहे हैं, तो [quickstart](/hi/start/quickstart) से शुरू करें। यदि डेटा पहले से आ रहा है, तो [Sessions](/hi/sessions/overview) खोलें और ऑडिट या नीतियों को कॉन्फ़िगर करने से पहले एक वास्तविक रन का निरीक्षण करें। - - कैप्चर से सुरक्षित रूप से तैनात नीति तक अंत-से-अंत वर्कफ़्लो पूरा करें। + + कैप्चर से सुरक्षित रूप से तैनात नीति तक संपूर्ण अंत-से-अंत वर्कफ़्लो को पूरा करें। \ No newline at end of file diff --git a/docs/hi/policies/deploy.mdx b/docs/hi/policies/deploy.mdx index 2d5cc916f..daf69fa9a 100644 --- a/docs/hi/policies/deploy.mdx +++ b/docs/hi/policies/deploy.mdx @@ -1,47 +1,51 @@ --- -title: "policies को deploy करें" -description: "समीक्षा की गई policy version को intended machines पर roll out करें।" +title: "नीतियों को तैनात करें" +description: "समीक्षित नीति संस्करण को इच्छित मशीनों पर रोल आउट करें।" icon: "cloud-upload" --- -एक deployment एक या अधिक policy versions को enrolled machines के target set से जोड़ता है। +एक तैनाती एक या अधिक नीति संस्करणों को नामांकित मशीनों के एक लक्ष्य सेट से जोड़ती है। -## एक deployment apply करें +## तैनाती लागू करें - 1. **Admin → enforcement** पर जाएं, machine को खोजें, और इसकी row को expand करें। - 2. **edit** चुनें, समीक्षा की गई policy version जोड़ें, और **observe** या इसके enforcing effect को चुनें। - 3. change को apply करें, फिर machine के अगले check-in का wait करें और deployment तथा coverage state को confirm करें। - 4. **Observe → policy** पर जाएं live decisions को inspect करने के लिए। + 1. **Admin → enforcement** पर जाएं, मशीन खोजें, और इसकी पंक्ति को विस्तृत करें। + 2. **edit** का चयन करें, समीक्षित नीति संस्करण जोड़ें, और **observe** या इसके लागू करने वाले प्रभाव को चुनें। + 3. परिवर्तन लागू करें, फिर मशीन के अगले चेक-इन की प्रतीक्षा करें और इसकी तैनाती और कवरेज स्थिति की पुष्टि करें। + 4. **Observe → policy** पर जाएं और लाइव निर्णयों का निरीक्षण करें। - ![Machine deployment editor जिसमें policy versions, enforce और observe effects, और apply deployment action दिखाए गए हैं।](/images/dashboard/enforcement-editor.png) + ![नीति संस्करणों, लागू करने और observe प्रभावों, और तैनाती लागू करने की कार्रवाई के साथ मशीन तैनाती संपादक।](/images/dashboard/enforcement-editor.png) - Cloud deployment endpoints intentionally सामान्य `fp` commands के रूप में expose नहीं किए गए हैं। Machine को locally check करें, फिर dashboard के माध्यम से deploy करें: + `fp fleet` के साथ CLI से तैनात करें। लागू करने से पहले परिणामी सेट की समीक्षा करें — `deploy` पूर्ण योजना प्रिंट करता है और **केवल `--json` के बिना एक इंटरैक्टिव टर्मिनल पर** पूछता है। `--json` के तहत, `--yes` के साथ, या stdin को रीडायरेक्ट के साथ (एक CI चरण, एक स्क्रिप्ट, एक एजेंट शेल आउट) यह कोई योजना और कोई संकेत के साथ तुरंत लागू करता है — इसलिए यदि आप समीक्षा चाहते हैं तो पहले `fp fleet show ` चलाएं: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - Deployment के बाद activity को Cloud तक पहुंचने को verify करने के लिए `fp sessions --env production --since 24h` और `fp events --event-type hook_completed` का use करें। + `fp fleet diff ` इरादा बनाम डिलीवरी दिखाता है (एक मशीन जब तक अगला पोल न करे तब तक `behind` के रूप में पढ़ी जाती है), `fp fleet history ` पीढ़ियों को सूचीबद्ध करता है, और `fp fleet rollback ` एक को पुनः स्थापित करता है — यह अस्वीकार करता है यदि वह पीढ़ी एक ऐसी नीति का नाम देती है जब से अक्षम या हटाई गई है। + + मशीन को स्वयं के साथ जांचें `failproofai config --status`, और तैनाती के बाद `fp sessions --env production --since 24h` और `fp events --event-type hook_completed` का उपयोग करें यह सत्यापित करने के लिए कि गतिविधि Cloud तक पहुंचती है। - - एक समीक्षा की गई version को deploy करें, mutable draft को नहीं, एक non-production machine या छोटे cohort से शुरुआत करते हुए जिसके sessions को आप inspect कर सकें। + + एक समीक्षित संस्करण तैनात करें, न कि एक परिवर्तनशील ड्राफ्ट, एक गैर-उत्पादन मशीन या छोटे समूह से शुरू करें जिसके सत्रों का आप निरीक्षण कर सकते हैं। - - Matches, reasons, affected tools, और false positives को review करें बिना work को block किए। + + मिलान, कारण, प्रभावित उपकरण, और बिना काम को अवरुद्ध किए गलत सकारात्मक परिणामों की समीक्षा करें। - - Promote करें जब observed matches unsafe actions को valid ones से अलग करें, फिर confirm करें कि हर intended machine ने deployment को pull किया है और decisions को report कर रहा है। + + देखे गए मिलान के बाद प्रोन्नत करें असुरक्षित कार्यों को वैध लोगों से अलग करते हैं, फिर पुष्टि करें कि हर इच्छित मशीन ने तैनाती को खींचा है और निर्णयों की रिपोर्ट कर रही है। -Machines को `policies:pull` capability की जरूरत है। Event reporting को separately `events:add` से control किया जाता है; दोनों को verify करें जब आप Cloud analysis और enforcement की उम्मीद करते हैं। +मशीनों को `policies:pull` क्षमता की आवश्यकता है। इवेंट रिपोर्टिंग को अलग से `events:add` द्वारा नियंत्रित किया जाता है; दोनों को सत्यापित करें जब आप Cloud विश्लेषण और प्रवर्तन की अपेक्षा करते हैं। - Enforcement management एक administrative Cloud workflow है। Root-only enforcement routes को सामान्य customer `/v1` API endpoints के रूप में treat न करें। + प्रवर्तन प्रबंधन एक प्रशासनिक Cloud वर्कफ़्लो है। रूट-केवल प्रवर्तन मार्गों को सामान्य ग्राहक `/v1` API एंडपॉइंट के रूप में मत मानें। \ No newline at end of file diff --git a/docs/hi/policies/editor.mdx b/docs/hi/policies/editor.mdx index 57cb13a9e..291097505 100644 --- a/docs/hi/policies/editor.mdx +++ b/docs/hi/policies/editor.mdx @@ -1,48 +1,49 @@ --- ---- title: "नीति संपादक" -description: "एक पुष्टि किए गए विफलता मोड से संस्करणित नीतियों को बनाएं और संशोधित करें।" +description: "एक पुष्ट विफलता मोड से संस्करणित नीतियां बनाएं और संशोधित करें।" icon: "file-pen-line" --- -नीति संपादक का उपयोग एक खोज या समस्या को एक तैनाती योग्य नियम में बदलने के लिए करें। लेखन को तैनाती से अलग रखें ताकि ड्राफ्ट लाइव व्यवहार को चुपचाप बदल न सके। +किसी खोज या समस्या को एक तैनाती योग्य नियम में बदलने के लिए नीति संपादक का उपयोग करें। लेखन को तैनाती से अलग रखें ताकि एक ड्राफ्ट जीवंत व्यवहार को चुप्पी से बदल न सके। -जब किसी समस्या का एक दोहराए जाने योग्य कार्य पैटर्न हो, तो इसे **Analyze → issues** के तहत खोलें और **generate policy** का चयन करें। Failproof AI पहले समझाता है कि क्या एक नीति समस्या को व्यक्त कर सकती है, फिर समीक्षित इरादे और खोज संदर्भ को संपादक में ले जाता है। जेनरेट किया गया स्रोत तब तक ड्राफ्ट रहता है जब तक आप इसे प्रकाशित नहीं करते। +जब किसी समस्या का एक दोहराए जाने योग्य कार्य पैटर्न हो, तो इसे **विश्लेषण → समस्याएं** के तहत खोलें और **नीति उत्पन्न करें** का चयन करें। Failproof AI पहले समझाता है कि क्या कोई नीति समस्या को व्यक्त कर सकती है, फिर समीक्षित इरादे और खोज संदर्भ को संपादक में ले जाता है। जेनरेट किया गया स्रोत तब तक ड्राफ्ट रहता है जब तक आप इसे प्रकाशित न करें। ## नीति संस्करण प्रकाशित करें - - 1. **Admin → policy editor** पर जाएं और **compose** में, विफलता मोड का वर्णन करें या JavaScript नीति स्रोत पेस्ट करें। - 2. स्रोत को सत्यापित करें और प्रत्येक रिपोर्ट की गई त्रुटि को ठीक करें। - 3. नीति पहचान दर्ज करें और इसे प्रकाशित करें, फिर संस्करणों की तुलना करने या अक्षम करने के लिए **library** का उपयोग करें। - 4. जब संस्करण मशीन रोलआउट के लिए तैयार हो तो **enforcement** का चयन करें। + + 1. **व्यवस्थापक → नीति संपादक** पर जाएं और **रचना** में, विफलता मोड का वर्णन करें या JavaScript नीति स्रोत पेस्ट करें। + 2. स्रोत को मान्य करें और रिपोर्ट की गई प्रत्येक त्रुटि को ठीक करें। + 3. नीति पहचान दर्ज करें और इसे प्रकाशित करें, फिर संस्करणों की तुलना या अक्षम करने के लिए **लाइब्रेरी** का उपयोग करें। + 4. जब संस्करण एक मशीन रोलआउट के लिए तैयार हो तो **प्रवर्तन** का चयन करें। - ![नीति पहचान, AI-सहायता प्राप्त ड्राफ्टिंग, स्रोत सत्यापन और प्रकाशन नियंत्रण के साथ पॉलिसी संपादक कंपोज़ दृश्य।](/images/dashboard/policy-editor.png) + ![नीति पहचान, AI-सहायता प्राप्त ड्राफ्टिंग, स्रोत सत्यापन और प्रकाशन नियंत्रण के साथ नीति संपादक रचना दृश्य।](/images/dashboard/policy-editor.png) - Cloud CLI नीति संस्करण प्रकाशित नहीं करता। संपादक में इसे कॉपी करने से पहले स्थानीय रूप से स्रोत को सत्यापित करें: + `fp policies publish` के साथ CLI से प्रकाशित करें। यह एक **नया संस्करण** बनाता है और कभी भी किसी को जगह पर संपादित नहीं करता है, और यह प्रकाशन से पहले node के साथ स्रोत को पार्स-जांच करता है — डाउनस्ट्रीम में कुछ भी ऐसा नहीं करता है, इसलिए एक सिंटैक्स त्रुटि अन्यथा प्रवर्तन समय पर मशीन पर सामने आती: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - **Admin → policy editor** से समीक्षित संस्करण प्रकाशित करें। + प्रकाशन कुछ भी तैनात नहीं करता — एक नया संस्करण अप्रयुक्त बैठता है जब तक `fp fleet deploy` इसे मशीन पर नहीं डालता। `fp policies compose ""` Cloud सहायक के साथ स्रोत का ड्राफ्ट करता है और इसे प्रकाशित करने के बजाय समीक्षा के लिए प्रिंट करता है। + + इसके बजाय एक स्थानीय एजेंट CLI में कोई नीति स्थापित करने के लिए (Cloud नहीं), `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project` का उपयोग करें। ## लेखन चेकलिस्ट 1. विफलता मोड को परिचालन भाषा में नाम दें। -2. हुक इवेंट और उपकरण चुनें जिनमें निर्णय लेने के लिए पर्याप्त साक्ष्य हो। -3. सबसे संकीर्ण स्थिति लिखें जो असुरक्षित व्यवहार से मेल खाती हो। -4. एक कारण दें जो एजेंट या ऑपरेटर को बताए कि अगला क्या करना है। -5. उदाहरण जोड़ें जो मेल खाने चाहिए और उदाहरण जो अनुमत रहने चाहिए। +2. हुक घटनाएं और उपकरण चुनें जिनमें निर्णय लेने के लिए पर्याप्त सबूत हो। +3. सबसे संकीर्ण शर्त लिखें जो असुरक्षित व्यवहार से मेल खाती हो। +4. एक कारण लौटाएं जो एजेंट या ऑपरेटर को बताता है कि आगे क्या करना है। +5. ऐसे उदाहरण जोड़ें जो मेल खाएं और ऐसे उदाहरण जो अनुमत रहने चाहिए। 6. एक नया संस्करण सहेजें और समीक्षा का अनुरोध करें। -`instruct` का उपयोग करें जब एजेंट सुरक्षित रूप से दिशा सुधार सकता है। `deny` का उपयोग करें जब कार्य को अनुमति देने से अस्वीकार्य या अपरिवर्तनीय जोखिम उत्पन्न हो। +जब एजेंट सुरक्षित रूप से पाठ्यक्रम सुधार सकता है तो `instruct` का उपयोग करें। जब कार्य की अनुमति देने से अस्वीकार्य या अपरिवर्तनीय जोखिम पैदा होता है तो `deny` का उपयोग करें। - नीति संस्करण अपरिवर्तनीय तैनाती इनपुट हैं। ड्राफ्ट को संपादित करने से एक नया संस्करण बनता है; इसे पहले से ही मशीनों को निर्दिष्ट संस्करण को फिर से नहीं लिखना चाहिए। + नीति संस्करण अपरिवर्तनीय तैनाती इनपुट हैं। एक ड्राफ्ट को संपादित करना एक नया संस्करण बनाता है; इसे पहले से ही मशीनों को निर्दिष्ट संस्करण को फिर से लिखना नहीं चाहिए। \ No newline at end of file diff --git a/docs/hi/reference/cloud-cli.mdx b/docs/hi/reference/cloud-cli.mdx index 2b3b5419f..0f6957761 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" --- -`fp` का उपयोग Cloud टेलीमेट्री का निरीक्षण करने और ऑडिट, फाइंडिंग, समस्याएं, अलर्ट, कुंजियाँ, उपयोगकर्ता, क्वेरी और सेटिंग्स को प्रबंधित करने के लिए करें। स्थानीय हुक, नीतियां, कैप्चर और मशीन नामांकन के लिए [`failproofai`](/hi/reference/failproof-cli) का उपयोग करें। +`fp` का उपयोग Cloud टेलीमेट्री निरीक्षण करने, क्लाउड-प्रबंधित प्रवर्तन (policies, fleet deployments, guardrail निर्णय) प्रबंधित करने, और 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,13 +26,13 @@ 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` चलाएं। +टर्मिनल help के लिए `fp COMMAND --help` या `fp COMMAND SUBCOMMAND --help` चलाएं। ## CLI कमांड @@ -40,48 +40,52 @@ fp --json sessions --since 24h | कमांड | उद्देश्य | विकल्प | | --- | --- | --- | -| `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 और हटाएं। | — | +| `fp whoami` | वर्तमान identity, authentication mode, organization, और permissions दिखाएं। | — | +| `fp version` | Installed CLI version दिखाएं। | — | +| `fp help` | Top-level command help दिखाएं। | — | ```bash fp login --email you@example.com --org reliability-team fp whoami ``` -### घटनाएं +### Events ```text fp events [OPTIONS] ``` -व्यक्तिगत एजेंट घटनाओं को सूचीबद्ध करता है। डिफ़ॉल्ट light फीड raw पेलोड को बाहर करता है; `--full` का उपयोग केवल सीमित जांच के लिए करें। +व्यक्तिगत agent events की सूची बनाता है। डिफ़ॉल्ट light feed raw payloads को exclude करता है; `--full` का उपयोग केवल bounded investigation के लिए करें। | विकल्प | विवरण | | --- | --- | -| `--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` | भारी इवेंट एंडपॉइंट के माध्यम से raw पेलोड शामिल करें। | -| `--fields ` | केवल चयनित फ़ील्ड लौटाएं; `payload` का अनुरोध full मोड को सक्षम करता है। | +| `--from ` / `--to ` | ISO 8601 UTC range; `--since` को override करता है। | +| `--env ` | Environment filter; values को repeat या comma-separate करें। | +| `--event-type ` | Event-type filter; repeat या comma-separate। | +| `--agent-id ` | Agent filter; repeat या comma-separate। | +| `--session-id ` | Session filter; repeat या comma-separate। | +| `--search ` | Payload text search; repeatable, किसी भी term के साथ matching। | +| `--order asc\|desc` | Time order। डिफ़ॉल्ट: newest first। | +| `--all` | `--limit` तक auto-paginate करें। | +| `--cursor ` | Opaque cursor से resume करें। | +| `--page-size ` | `--all` के साथ rows per request; अधिकतम `200`। | +| `--full` | Heavier event endpoint के माध्यम से raw payloads शामिल करें। | +| `--fields ` | केवल चयनित fields return करें; `payload` requesting full mode को सक्षम करता है। | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` -### सत्र + + `--all` **`--limit` तक** पaginates करता है, जिसका डिफ़ॉल्ट **50** है — इसलिए `--all` अकेले 50 rows पर रुकता है। जब यह जल्दी रुकता है तो response एक `next_cursor` carry करता है; `"next_cursor": null` का मतलब है कि feed वास्तव में exhausted था। + + +### Sessions ```text fp sessions [OPTIONS] @@ -89,21 +93,21 @@ fp sessions [OPTIONS] | विकल्प | विवरण | | --- | --- | -| `--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; repeat या comma-separate। | +| `--status ` | `done`, `error`, या `timeout`; repeat या comma-separate। | +| `--agent-id ` | किसी भी चयनित agent को शामिल करने वाले sessions को match करें। | +| `--session-id ` | Session filter; repeat या comma-separate। | +| `--all` | `--limit` तक auto-paginate करें। | +| `--cursor ` | Opaque cursor से resume करें। | +| `--page-size ` | `--all` के साथ rows per request; अधिकतम `200`। | +| `--fields ` | केवल चयनित fields return करें। | +| `--full-ids` | Terminal output में session IDs को shorten न करें। | +| `--agents` | Multi-agent sessions के लिए agent roster को expand करें। | + +### Evaluations ```text fp evals [OPTIONS] @@ -111,17 +115,17 @@ fp evals [OPTIONS] | विकल्प | विवरण | | --- | --- | -| `--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` | Time range select करें। | +| `--env`, `--status`, `--agent-id`, `--session-id` | प्रत्येक filter के लिए एक exact value तक narrow करें। | +| `--score KEY:MIN..MAX` | Score range; repeatable और सभी ranges को match करना होगा। | +| `--all`, `--cursor`, `--page-size` | List pagination को control करें। | +| `--fields ` | केवल चयनित fields return करें। | +| `--full-ids` | पूर्ण session IDs दिखाएं। | +| `--scores-full` | Terminal output में हर score दिखाएं। | + +### Errors ```text fp errors [OPTIONS] @@ -129,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` | संपूर्ण सत्र IDs दिखाएं। | - -### उपयोग और फ़िल्टर मान +| `--aggregate` | Rows को list करने के बजाय matching errors को summarize करें। | +| `--limit`, `-n ` | अधिकतम list rows। डिफ़ॉल्ट: `50`। | +| `--since`, `--from`, `--to` | Time range select करें। | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Error population को narrow करें। | +| `--search ` | Payload text को search करें; repeatable। | +| `--order asc\|desc` | Time order। | +| `--all`, `--cursor`, `--page-size` | List pagination को control करें। | +| `--fields ` | केवल चयनित fields return करें। | +| `--full-ids` | पूर्ण session IDs दिखाएं। | + +### उपयोग और filter values | कमांड | उद्देश्य | | --- | --- | -| `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 की सूची बनाएं। | +| `fp list agents` | Observed agent IDs की सूची बनाएं। | +| `fp list event_types` | Event types की सूची बनाएं। | +| `fp list score_filters` | Evaluation score keys की सूची बनाएं। | +| `fp list models` | Model names की सूची बनाएं। | +| `fp list hooks` | Hook names की सूची बनाएं। | +| `fp list tools` | Tool names की सूची बनाएं। | +| `fp list error_types` | Error types की सूची बनाएं। | + +### Organizations | कमांड | उद्देश्य | | --- | --- | -| `fp orgs list` | सुलभ संगठनों को सूचीबद्ध करें। | -| `fp orgs switch [SLUG]` | एक सक्रिय संगठन को सहेजें; छोड़ा जाने पर प्रॉम्प्ट करता है। | -| `fp orgs current` | सक्रिय संगठन दिखाएं। | -| `fp orgs perms` | सक्रिय संगठन में आपकी अनुमतियां दिखाएं। | +| `fp orgs list` | Accessible organizations की सूची बनाएं। | +| `fp orgs switch [SLUG]` | Active organization को save करें; omit होने पर prompt करें। | +| `fp orgs current` | Active organization दिखाएं। | +| `fp orgs perms` | Active organization में अपनी permissions दिखाएं। | -### API कुंजियां +### API keys | कमांड | उद्देश्य | विकल्प | | --- | --- | --- | -| `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 की सूची बनाएं। | `--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 को revoke करें। | `--yes`, `-y` | -अनुमति टोकन `resource:action` का उपयोग करते हैं, जैसे `events:add`। `--add` को दोहराएं, टोकन को कॉमा से अलग करें, या `events:read.add` जैसी डॉटेड कार्रवाई का उपयोग करें। +Permission tokens `resource:action` का उपयोग करते हैं, जैसे `events:add`। `--add` को repeat करें, tokens को comma-separate करें, या dotted actions जैसे `events:read.add` का उपयोग करें। -### क्वेरीज़ +### Queries | कमांड | उद्देश्य | विकल्प | | --- | --- | --- | -| `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]` | सहेजी गई क्वेरी या ad-hoc SQL चलाएं। | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | क्वेरी योग्य तालिकाओं को सूचीबद्ध करें या एक तालिका का निरीक्षण करें। | — | +| `fp query list` | Saved queries की सूची बनाएं। | `--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 चलाएं। | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query schema [TABLE]` | Queryable tables की सूची बनाएं या एक table को inspect करें। | — | -### उपयोगकर्ता +### Users | कमांड | उद्देश्य | विकल्प | | --- | --- | --- | -| `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 की सूची बनाएं। | `--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 | कमांड | उद्देश्य | विकल्प | | --- | --- | --- | -| `fp settings list` | संगठन सेटिंग्स और वर्तमान मान सूचीबद्ध करें। | — | -| `fp settings schema` | स्वीकृत मान और विवरण दिखाएं। | — | -| `fp settings set KEY` | मौजूदा सेटिंग बदलें। | `--value`, `--json-value`, `--file` में से बिल्कुल एक; वैकल्पिक `--yes`, `-y` | +| `fp settings list` | Organization settings और current values की सूची बनाएं। | — | +| `fp settings schema` | Accepted values और descriptions दिखाएं। | — | +| `fp settings set KEY` | एक existing setting को change करें। | `--value`, `--json-value`, `--file` में से बिल्कुल एक; optional `--yes`, `-y` | -### अलर्ट +### Alerts | कमांड | उद्देश्य | विकल्प | | --- | --- | --- | -| `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 की सूची बनाएं। | `--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 | कमांड | उद्देश्य | विकल्प | | --- | --- | --- | -| `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 की सूची बनाएं। | `--enabled-only`; `--show-id` | +| `fp audits show NAME` | एक audit definition और state दिखाएं। | — | +| `fp audits create NAME` | एक audit बनाएं और तुरंत इसका पहला 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 की सूची बनाएं। | `--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 की सूची बनाएं। | `--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 को भविष्य के suppression के बिना fixed के रूप में mark करें। | `--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 \ @@ -257,95 +261,139 @@ fp audits create checkout-reliability \ | विकल्प | विवरण | | --- | --- | -| `--file ` | परिभाषा को JSON पर आधारित करें, या stdin के लिए `-` का उपयोग करें। स्पष्ट फ्लैग फ़ाइल मान को ओवरराइड करते हैं। | -| `--description ` | विफलता प्रश्न या उद्देश्य बताएं। | -| `--enabled` / `--disabled` | शेड्यूलिंग को चालू या बंद से शुरू करें। डिफ़ॉल्ट: सक्षम। | +| `--file ` | JSON पर definition को base करें, या stdin के लिए `-` का उपयोग करें। Explicit flags file values को override करते हैं। | +| `--description ` | Failure question या purpose को state करें। | +| `--enabled` / `--disabled` | On या off पर scheduling को 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। डिफ़ॉल्ट: अगला 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 करें; up to पांच बार repeat करें। | + +Creation के दौरान context को शामिल करें जब पहले run को इसकी आवश्यकता हो। Creation definition और context को एक साथ commit करता है queued run शुरू होने से पहले। - `fp audits run` अतुल्यकालिक है। `fp audits runs NAME` तक पोल करें जब तक कि नवीनतम चलाना सफल या विफल न हो जाए इससे पहले इसकी फाइंडिंग पढ़ें। + `fp audits run` asynchronous है। `fp audits runs NAME` को poll करें जब तक latest run succeed या fail न हो जाए। -### समस्याएं +### 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 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 की सूची बनाएं। | `--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 की सूची बनाएं। | — | +| `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 की सूची बनाएं। | — | +| `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 | कमांड | उद्देश्य | विकल्प | | --- | --- | --- | -| `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 की सूची बनाएं। | — | +| `fp agent chats` | Saved chats की सूची बनाएं। | — | +| `fp agent ask [MESSAGE]` | एक chat को start या continue करें; message omit होने पर 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 -| फ्लैग | विवरण | +क्लाउड-प्रबंधित policy versions। **Session-only** — यहां हर कमांड एक API key के तहत `2` exit करता है, किसी भी request से पहले, क्योंकि ये deliberately root-only write routes हैं जो `/v1` से absent हैं। + +| कमांड | उद्देश्य | विकल्प | +| --- | --- | --- | +| `fp policies list` | Policy versions की सूची बनाएं। | `--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 करें जहां से यह हटाया गया था, प्रत्येक पर नया 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` | एक policy को locally एक synthetic context के विरुद्ध चलाएं। प्रत्येक policy के `match` filter को apply करता है, इसलिए एक जो दिए गए event/tool को cover नहीं करता है, `skipped` के रूप में reported है चलाने के बजाय। | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | +| `fp policies compose PROMPT` | Assistant के साथ एक policy को draft करें। `policies:write` की आवश्यकता है। | — | + +### Fleet + +कौन सी machines कौन सी policies चलाती हैं। **Session-only**, ऊपर जैसा कारण। + +| कमांड | उद्देश्य | विकल्प | +| --- | --- | --- | +| `fp fleet list` | Enrolled machines और उनके deployment generation की सूची बनाएं। | — | +| `fp fleet show MACHINE_ID` | Machine currently जो policy set चलाता है। | — | +| `fp fleet deploy MACHINE_ID` | **Machine के पूरे policy set को replace करता है।** Plan को print करता है और एक interactive terminal पर `--json` के बिना only पूछता है। | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | एक machine को दूसरे deployment के विरुद्ध compare करें। | — | +| `fp fleet history MACHINE_ID` | एक machine के लिए past deployments। | — | +| `fp fleet rollback MACHINE_ID` | एक previous deployment को restore करें। | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | एक machine को एक readable name दें। | required `--name` | + +### Guardrails + +Enforcement ने वास्तव में क्या किया। **Session-only**, ऊपर जैसा कारण। + +| कमांड | उद्देश्य | विकल्प | +| --- | --- | --- | +| `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 में summed। | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | + +## Global flags + +| Flag | विवरण | | --- | --- | -| `--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 ` | Automation को एक API key के साथ 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 | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | वर्तमान CLI कॉन्फ़िगरेशन निर्देशिका को पुनः स्थापित करें। | -| `AGENTEYE_ANALYTICS_DISABLED` या `DO_NOT_TRACK` | अनाम CLI विश्लेषण को अक्षम करें। | -| `NO_COLOR` | रंगीन आउटपुट को अक्षम करें। | - -स्पष्ट फ्लैग पर्यावरण चर को ओवरराइड करते हैं, जो सहेजे गए कॉन्फ़िगरेशन को ओवरराइड करते हैं। API-कुंजी मोड में, `--org` या `AGENTEYE_ORG` के साथ किरायेदार को स्पष्ट रूप से चुनें। +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `FP_API_KEY` | `--api-key` | +| `FP_JSON` | `--json` | +| `FP_INSECURE` | `--insecure` | +| `FP_HOME` | CLI configuration directory को relocate करें (डिफ़ॉल्ट `~/.failproofai/fpcli`)। | +| `FP_ANALYTICS_DISABLED` या `DO_NOT_TRACK` | Anonymous CLI analytics को disable करें। | +| `NO_COLOR` | Colored output को disable करें। | + +Explicit flags environment variables को override करते हैं, जो saved configuration को override करते हैं। API-key mode में, `--org` या `FP_ORG` के साथ tenant को explicitly select करें। + + + इन के `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 के विरुद्ध चलता है। + + `AGENTEYE_HOME` और `AGENTEYE_ENVIRONMENT` अभी भी exist करते हैं, लेकिन वे **collector और telemetry SDK** को belong करते हैं, इस CLI को नहीं। + - कमांड जो हटाते हैं, रद्द करते हैं, दबाते हैं, हल करते हैं, या कॉन्फ़िगरेशन को बदलते हैं डिफ़ॉल्ट रूप से प्रॉम्प्ट करते हैं। सक्रिय संगठन और लक्ष्य को सत्यापित करने के बाद ही `--yes` का उपयोग करें। + कमांड जो delete, revoke, suppress, resolve, या replace configuration करते हैं, डिफ़ॉल्ट रूप से prompt करते हैं। Active organization और target को verify करने के बाद only `--yes` का उपयोग करें। \ No newline at end of file diff --git a/docs/hi/reference/custom-agents.mdx b/docs/hi/reference/custom-agents.mdx index ad993ee59..8056e3244 100644 --- a/docs/hi/reference/custom-agents.mdx +++ b/docs/hi/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- -title: "कस्टम एजेंट" -description: "कस्टम एजेंट से ट्रेस इंस्ट्रूमेंट करें ताकि Failproof AI रन को पुनर्निर्मित कर सके और विफलताओं को खोज सके।" +title: "कस्टम एजेंट्स" +description: "failproofai-sdk के लिए कॉन्फ़िगरेशन, ईवेंट कैटलॉग, सहसंबंध नियम, और डिलीवरी।" icon: "python" --- -`failproofai-sdk` के साथ कस्टम एजेंट से ट्रेस इंस्ट्रूमेंट करें ताकि Failproof AI प्रत्येक रन को पुनर्निर्मित कर सके, इसके व्यवहार का ऑडिट कर सके, और साक्ष्य-समर्थित विफलताओं को खोज सके। SDK Failproof डेमॉन को Cloud में डिलीवर करने के लिए संरचित इवेंट लिखता है। इसके लिए Python 3.10 या नए संस्करण की आवश्यकता है। +हर सेटिंग, मेथड और फील्ड क्या करते हैं। अगर आप पहली बार इंस्ट्रूमेंटेशन कर रहे हैं, तो गाइड से शुरुआत करें — यह पृष्ठ संदर्भ के लिए है। -ट्रेसिंग कस्टम एजेंट को अवलोकनीय और ऑडिट योग्य बनाता है। किसी असुरक्षित कार्य को निष्पादित होने से पहले रोकने के लिए आपके रनटाइम में एक एनफोर्समेंट हुक की भी आवश्यकता है। + + + इंस्टॉल, इंस्ट्रूमेंट, ईवेंट मेथड्स, एक व्यावहारिक उदाहरण, और सामान्य समस्याएं। + + + LangChain, CrewAI, LlamaIndex और Pydantic AI एक कॉल के साथ अपने आप को इंस्ट्रूमेंट करते हैं। + + - - कस्टम एजेंट सेटअप में नीतियों को लागू करने के लिए, [Failproof AI से संपर्क करें](mailto:support@befailproof.ai)। हम आपके रनटाइम के मॉडल, टूल, और लाइफसाइकिल सीमाओं को नीति हुक के साथ मैप करने में मदद करेंगे। - +Python 3.10 या नया। कोई रनटाइम डिपेंडेंसीज नहीं। -
- -
- -## `failproofai-sdk` इंस्टॉल करें - -SDK वर्तमान में एक निजी व्हील के रूप में वितरित किया जाता है। अपने Failproof AI संपर्क से वर्तमान संस्करण और डाउनलोड एक्सेस के लिए पूछें। +## इंस्टॉल करें ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -`uv` के साथ, पहले व्हील डाउनलोड करें और `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl` चलाएं। व्हील को एक निजी आर्टिफैक्ट रिपोजिटरी में या डिपेंडेंसी लॉक में पिन करें। - -पैकेज `failproofai-sdk` के रूप में इंस्टॉल किया जाता है और Python में `failproofai` के रूप में आयात किया जाता है। +पैकेज को `failproofai-sdk` के रूप में इंस्टॉल किया जाता है और Python में `failproofai_sdk` के रूप में इम्पोर्ट किया जाता है। `failproofai-sdk[langgraph]` जैसी फ्रेमवर्क एक्सट्रास फ्रेमवर्क को स्वयं इंस्टॉल करते हैं; एडेप्टर हमेशा बेस व्हील में आते हैं। -## Failproof डेमॉन से कनेक्ट करें +## Failproof डेमन कनेक्ट करें 1. **Admin → Keys** पर जाएं और `events:add` के साथ एक कुंजी बनाएं। - 2. एजेंट मशीन पर [Failproof डेमॉन को Cloud से कनेक्ट करें](/hi/start/setup#connect-a-machine-to-cloud)। - 3. एक इंस्ट्रूमेंटेड सेशन चलाएं, फिर **Observe → Events** के अंतर्गत इसका सटीक ID खोजें। - 4. **Observe → Sessions** पर जाएं, समान वातावरण चुनें, और पुनर्निर्मित ट्रेस खोलें। + 2. [एजेंट मशीन पर Failproof डेमन को Cloud से कनेक्ट करें](/hi/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) ```bash @@ -51,102 +46,84 @@ python -c "import failproofai; print(failproofai.__version__)" -## एक संपूर्ण रन को इंस्ट्रूमेंट करें - -प्रक्रिया स्टार्टअप के दौरान एक बार `configure()` कॉल करें। प्रत्येक इवेंट कॉल केवल कीवर्ड है और एक स्थिर `session_id` और `agent_id` की आवश्यकता है। +## कॉन्फ़िगरेशन ```python -import traceback -import uuid +import failproofai_sdk + +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -import failproofai +| आर्गुमेंट | यह क्या करता है | +| --- | --- | +| `environment` | हर ईवेंट पर लेबल — `production`, `staging`, `prod-eu`। डिफ़ॉल्ट `dev` है। | +| `flush_interval` | पृष्ठभूमि थ्रेड कितनी बार डिस्क पर लिखता है, सेकंड में। डिफ़ॉल्ट `0.5` है। | +| `base_dir` | कहां लिखना है। डिफ़ॉल्ट डेमन के स्पूल, जो आप चाहते हैं जब तक कि आप अन्यथा न जानते हों। | -failproofai.configure(environment="production") +इसके बजाय पर्यावरण चर द्वारा सेट करें: -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +| चर | यह क्या करता है | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | कोड परिवर्तन के बिना `environment` सेट करता है, जब लेबल डिप्लॉयमेंट के बजाय ऐप से संबंधित हो। एक `configure()` आर्गुमेंट इसे जीतता है। | +| `FAILPROOFAI_HOME` | Failproof AI रूट को स्थानांतरित करता है जो स्पूल को धारण करता है। | +| `FAILPROOFAI_SDK_STRICT` | `1` इंस्ट्रूमेंटेशन त्रुटियों को लॉग करने के बजाय उठाता है। | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` एक फ्रेमवर्क-संगतता समस्या को चेतावनी दिए जाने और जारी रहने के बजाय उठाता है। | -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) + + **`environment` में कोई अल्पविराम नहीं।** इनजेस्ट अपने फिल्टर बनाने के लिए उस फील्ड को अल्पविराम पर विभाजित करता है, और किसी भी ईवेंट को छोड़ देता है जिसका लेबल एक युक्त है — इसलिए एक पूरा रन चुप चाप गायब हो जाता है। `prod-eu` लिखें, `prod,eu` नहीं। -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + `configure(environment="prod,eu")` उठाता है ताकि आप तुरंत खोज लें। `AGENTEYE_ENVIRONMENT` उठा नहीं सकता — कोई आपको कॉल नहीं कर रहा है — इसलिए यह एक बार चेतावनी देता है और `dev` पर वापस आता है। + + +ईवेंट्स मेमोरी में कतारबद्ध हैं और हर `flush_interval` सेकंड में पृष्ठभूमि में लिखे जाते हैं, इंटरप्रेटर एक्जिट पर एक अंतिम फ्लश के साथ। एक प्रक्रिया जो सीधे मारी जाती है, वह कुछ भी खो देती है जो अभी तक लिखी नहीं गई थी। -प्रति अभिनेता एक बार `agent_start` उत्सर्जित करें। उप-एजेंट के लिए, माता-पिता के `session_id` का पुनः उपयोग करें, प्रत्येक अभिनेता को एक अलग `agent_id` दें, और `parent_id` को माता-पिता के **agent ID** पर सेट करें, सेशन ID पर नहीं। +## पहचान -## कॉन्फ़िगरेशन संदर्भ +हर ईवेंट एक सेशन और एक एजेंट से संबंधित है। **स्कोप दोनों को भरते हैं**, इसलिए आप शायद ही कभी उन्हें पास करते हैं: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| सेटिंग | व्यवहार | -| --- | --- | -| `base_dir` | स्पष्ट स्पूल रूट। सभी पर्यावरण चर को प्राथमिकता देता है। | -| `flush_interval` | मेमोरी से JSONL तक बैकग्राउंड लेखन के बीच सेकंड। डिफ़ॉल्ट: `0.5`। | -| `environment` | प्रत्येक इवेंट पर डिप्लॉयमेंट लेबल। डिफ़ॉल्ट `dev` है। | -| `FAILPROOFAI_HOME` | Failproof AI रूट को बदलता है जिसमें `custom-agents` स्पूल है। | +`session_id` या `agent_id` को स्पष्ट रूप से पास करना अभी भी काम करता है और जीतता है। न तो बाउंड और न ही पास के साथ, कॉल `TypeError` उठाता है बजाय एक ईवेंट उत्सर्जित करने के जो Cloud चुप चाप त्यागता है। -SDK सेट होने पर स्पष्ट `base_dir` में लिखता है। अन्यथा, यह `FAILPROOFAI_HOME` या `~/.failproofai` के अंतर्गत Failproof डेमॉन के `custom-agents` स्पूल का उपयोग करता है। + + पहचान संदर्भ चर पर सवारी करती है। यह `asyncio` कार्यों को स्वचालित रूप से अनुसरण करता है, लेकिन **नए थ्रेड्स नहीं** — एक वर्कर को `failproofai_sdk.propagate()` में लपेटें या इसके ईवेंट्स अनलगाए रहते हैं। + -SDK कॉल को मेमोरी में कतार में रखता है और बैकग्राउंड थ्रेड पर बैच लिखता है। यह Python के `atexit` हैंडलिंग के माध्यम से एक अंतिम फ्लश का भी प्रयास करता है। अल्पकालिक वर्कर के लिए सामान्य दुभाषिया शटडाउन की अनुमति दें; हार्ड प्रक्रिया समाप्ति मेमोरी में अभी भी इवेंट खो सकती है। +## ईवेंट कैटलॉग -## इवेंट कैटलॉग +पंद्रह मेथड्स। अधिकांश **जोड़े** में आते हैं — आप ओपनर को कॉल करते हैं, फिर क्लोजर को, और SDK अंतराल को समय करता है। -सभी विधियां `None` लौटाती हैं। `None` के रूप में छोड़े गए फील्ड JSON `null` के रूप में लिखे जाने के बजाय छोड़ दिए जाते हैं। +| | खुलता है | बंद करता है | +| --- | --- | --- | +| **एजेंट्स** | `agent_start` | `agent_end` | +| | `agent_pause` | `agent_resume` | +| **मॉडल्स** | `model_request` | `model_response` | +| **टूल्स** | `tool_use` | `tool_result` | +| **हुक्स** | `hook_triggered` | `hook_completed` | +| **मानव** | `human_wait` | `human_input` | + +तीन अकेले खड़े हैं: `error`, `human_pause`, `human_interrupt`। + + -| विधि | पहचान से परे आवश्यक फील्ड | वैकल्पिक फील्ड | +हर मेथड भी `session_id` और `agent_id` लेता है, जिन्हें स्कोप आपके लिए भरते हैं। कुछ भी `None` के रूप में छोड़ दिया गया JSON `null` के रूप में भेजने के बजाय dropped है, और हर मेथड `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ SDK कॉल को मेमोरी में कतार में रख | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -`outcome="failed"`, `"error"`, `"timeout"`, या `"rejected"` का उपयोग करें जब कोई पूरा होना विफलता के रूप में गिना जाना चाहिए। अन्य मान, `"failure"` सहित, वर्तमान बैकएंड द्वारा विफलता के रूप में वर्गीकृत नहीं हैं। + + + + एक रन को विफल के रूप में चिह्नित करने के लिए, `outcome` `failed`, `error`, `timeout` या `rejected` में से एक होना चाहिए। कुछ भी अन्य — निकट-मिस `"failure"` सहित — एक सफलता के रूप में गिना जाता है। + + +## पेयरिंग और अवधि + +**एक नियम: क्लोजिंग ईवेंट को अपने ओपनर के समान ID दें।** यह वह है जो उन्हें जोड़ता है, और क्या SDK को अंतराल को समय देता है। + +| जोड़ी | मिलान किया गया | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**`duration_ms` को स्वयं पास न करें।** SDK इसे मापता है, और इसे पास करना `ValueError` उठाता है। -## सहसंबंध और अवधि नियम +एक अपवाद `model_response` है, जहां केवल आप वास्तविक प्रदाता विलंबता जानते हैं। मिलीसेकंड की एक पूरी संख्या पास करें — एक फ्लोट उठाता है, क्योंकि कॉलम एक 32-बिट पूर्णांक है और अन्यथा खाली रहेगा। -- मिलान पूरा होने वाली इवेंट के लिए समान `tool_call_id`, `hook_id`, `pause_id`, या `input_id` का पुनः उपयोग करें। -- SDK `tool_result`, `hook_completed`, `agent_resume`, और `human_input` के लिए `duration_ms` की गणना करता है। इसे स्वयं उन विधियों को पास करने से `ValueError` उठता है। -- टूल और हुक ID एक प्रक्रिया-व्यापी लंबित मानचित्र साझा करते हैं। उन्हें समवर्ती सेशन और दोनों नामस्थानों में विश्व स्तर पर अद्वितीय बनाएं; प्रदाता ID या UUID सबसे सुरक्षित हैं। -- एक जोड़ी को प्रक्रियाओं में विभाजित करने पर भी डाउनस्ट्रीम सहसंबंध होता है, लेकिन SDK इसकी प्रक्रिया-में अवधि की गणना नहीं कर सकता। -- लंबित मानचित्र सर्वाधिक 10,000 शुरुआत रखता है और पूर्ण होने पर सबसे पुरानी प्रविष्टि को निष्कासित करता है। + -## कस्टम फील्ड और पेलोड +- **Ids को केवल प्रति प्रकार, प्रति सेशन में अद्वितीय होने की आवश्यकता है।** एक टूल कॉल और एक हुक एक साझा कर सकते हैं; एक साथ चलने वाले दो सेशन बिना टकराए समान IDs पुन: उपयोग कर सकते हैं। +- **वे एक एजेंट के लिए स्कोप नहीं हैं।** एक जोड़ी एक एजेंट के तहत खुली और दूसरे के तहत बंद अभी भी मेल खाती है — जो बहु-एजेंट कोड में सामान्य मामला है। +- **`request_id` वैकल्पिक है लेकिन अनुशंसित है।** इसके बिना, मॉडल ईवेंट्स उस क्रम में जोड़ी बनाते हैं जिस क्रम में वे आते हैं, इसलिए एक ही एजेंट में दो समवर्ती कॉल्स गलत जोड़ी बना सकते हैं। +- **एक जोड़ी प्रक्रियाओं के पार विभाजित** अभी भी Cloud में मेल खाती है, लेकिन SDK इसे समय नहीं कर सकता — कोई भी प्रक्रिया दोनों आधे नहीं देखे। +- **अधिकतम 10,000 ओपनर्स एक साथ क्लोजर की प्रतीक्षा करते हैं।** उसके बाद सबसे पुराना dropped है, इसलिए एक रिसाव बिना सीमा के विकसित नहीं हो सकता। -प्रत्येक इवेंट अतिरिक्त कीवर्ड फील्ड स्वीकार करता है। डाउनस्ट्रीम क्वेरी को संरचना की आवश्यकता होने पर JSON-संगत मान का उपयोग करें। UUID, दिनांक, दशमलव, सेट, बाइट, और मॉडल ऑब्जेक्ट जैसे समर्थित नहीं पत्ते लेखक द्वारा स्ट्रिंगिफाई किए जाते हैं। + -आरक्षित कस्टम नाम `timestamp`, `session_id`, `agent_id`, `type`, और `environment` हैं। वैकल्पिक-फील्ड टाइपो को नए कस्टम फील्ड के रूप में स्वीकार किया जाता है, इसलिए जब कोई मानक फील्ड Cloud में दिखाई न दे तो उत्सर्जित JSON की समीक्षा करें। +## आपके अपने फील्ड्स -## डिलीवर और सत्यापित करें +कोई भी अतिरिक्त कीवर्ड जो आप पास करते हैं ईवेंट के साथ संग्रहीत है: + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # आपके अपने +) +``` + +अगर आप बाद में उन्हें क्वेरी करना चाहते हैं तो JSON प्रकारों को वरीयता दें। कुछ भी अन्य — एक UUID, एक datetime, एक `Decimal`, एक सेट, बाइट्स, एक मॉडल ऑब्जेक्ट — एक स्ट्रिंग के रूप में संग्रहीत है। + + + **अपने फील्ड नामों को प्रीफिक्स करें।** एक्सट्रास आखिरी लागू होते हैं, इसलिए `model`, `tool_name` या `outcome` कहा जाने वाला एक फील्ड चुप चाप वास्तविक को ओवरराइट करता है। फ्रेमवर्क एडेप्टर `fw_` का उपयोग करते हैं; वही करें और कुछ भी टकरा नहीं सकता। + + यही कारण है कि एक गलत वर्तनी वाली वैकल्पिक फील्ड कभी त्रुटि नहीं करती — यह सिर्फ एक नया कस्टम फील्ड बन जाती है। अगर एक मानक फील्ड Cloud में लापता है, तो पहले वर्तनी की जांच करें। + + +ये पांच नाम आरक्षित हैं और तुरंत अस्वीकार कर दिए गए हैं: `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 @@ -189,10 +203,14 @@ SDK कॉल को मेमोरी में कतार में रख -यदि Cloud खाली है, तो `$FAILPROOFAI_HOME/custom-agents/events` निरीक्षण करें, अन्यथा `~/.failproofai/custom-agents/events`। JSONL फाइलें SDK उत्सर्जन साबित करती हैं; एक बढ़ता हुआ स्पूल डेमॉन कॉन्फ़िगरेशन या डिलीवरी की ओर इशारा करता है, जबकि एक खाली स्पूल इंस्ट्रूमेंटेशन या प्रक्रिया जीवनकाल की ओर इशारा करता है। +अगर Cloud खाली है, तो `$FAILPROOFAI_HOME/custom-agents/events` की जांच करें, अन्यथा `~/.failproofai/custom-agents/events`। JSONL फाइलें SDK उत्सर्जन साबित करती हैं; एक बढ़ता हुआ स्पूल डेमन कॉन्फ़िगरेशन या डिलीवरी की ओर इशारा करता है, जबकि एक खाली स्पूल इंस्ट्रूमेंटेशन या प्रक्रिया जीवनकाल की ओर इशारा करता है। + + + स्पूल की जांच केवल तभी करें जब डेमन रुका हो। जब यह चलता है, तो यह मिलीसेकंड के भीतर प्रत्येक बैच को एकत्र और हटाता है, इसलिए एक निर्देशिका सूची कलेक्टर के साथ दौड़ लगाती है और उत्सर्जित की तुलना में बहुत कम ईवेंट्स दिखाती है। + -## कस्टम रनटाइम में विफलताओं को रोकें +## एक कस्टम रनटाइम में विफलताओं को रोकें -असुरक्षित कार्य, आवश्यक साक्ष्य, और अभीष्ट प्रतिक्रिया को परिभाषित करने के लिए ऑडिट निष्कर्ष और लिंक किए गए ट्रेस का उपयोग करें। एक कस्टम एनफोर्समेंट एकीकरण को निष्पादन से पहले कार्य को उजागर करना चाहिए, इसके संरचित इनपुट को नीति इंजन में पास करना चाहिए, और परिणामी allow, instruct, या deny निर्णय लागू करना चाहिए। +असुरक्षित कार्य, आवश्यक साक्ष्य, और इरादे की प्रतिक्रिया को परिभाषित करने के लिए ऑडिट निष्कर्ष और लिंक किए गए ट्रेस का उपयोग करें। एक कस्टम प्रवर्तन एकीकरण को निष्पादन से पहले कार्रवाई को उजागर करना चाहिए, इसके संरचित इनपुट को नीति इंजन में पास करना चाहिए, और परिणामी allow, instruct, या deny निर्णय लागू करना चाहिए। -अपने रनटाइम के लिए इस एकीकरण को डिज़ाइन और मान्य करने के लिए [support@befailproof.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/hi/reference/events-and-configuration.mdx b/docs/hi/reference/events-and-configuration.mdx index ebab89986..c217b7269 100644 --- a/docs/hi/reference/events-and-configuration.mdx +++ b/docs/hi/reference/events-and-configuration.mdx @@ -1,41 +1,41 @@ --- -title: "इवेंट्स और कॉन्फ़िगरेशन" -description: "इवेंट मॉडल, एनवायरनमेंट्स, लोकल स्टोरेज और कॉन्फ़िगरेशन सीमाओं को संदर्भित करें।" +title: "Events और configuration" +description: "Event model, environments, local storage, और configuration boundaries को reference करें।" icon: "list-tree" --- -## इवेंट फ़ैमिलीज़ +## Event families -- एजेंट स्टार्ट, एंड, पॉज़ और रिज़्यूम -- मॉडल रिक्वेस्ट और रिस्पांस -- टूल यूज़ और रिज़ल्ट -- हुक ट्रिगर्ड और कंप्लीटेड -- ह्यूमन वेट, इनपुट, पॉज़ और इंटरप्ट -- एक्सप्लिसिट एरर्स +- Agent start, end, pause, और resume +- Model request और response +- Tool use और result +- Hook triggered और completed +- Human wait, input, pause, और interrupt +- Explicit errors -हर इवेंट एक टाइमस्टैम्प, सेशन ID, एजेंट ID, इवेंट टाइप और एनवायरनमेंट ले जाता है। इवेंट-स्पेसिफिक फील्ड्स में मॉडल, टूल, कोरिलेशन, आउटकम, कंटेंट, ड्यूरेशन या एरर डेटा होता है। +हर event के साथ एक timestamp, session ID, agent ID, event type, और environment होता है। Event-specific fields में model, tool, correlation, outcome, content, duration, या error data होता है। -## एक इवेंट कॉन्ट्रैक्ट का निरीक्षण करें +## Event contract को inspect करें - - 1. **Observe → Events** खोलें। - 2. एक छोटी समय विंडो सेट करें और एनवायरनमेंट, एजेंट और इवेंट टाइप से फ़िल्टर करें। - 3. एक इवेंट चुनें इसके नॉर्मलाइज़्ड फील्ड्स और raw पेलोड का निरीक्षण करने के लिए, फिर इसके सेशन को खोलें एक्सीक्यूशन कॉन्टेक्स्ट देखने के लिए। - 4. यदि कोई पेयर्ड ड्यूरेशन मिसिंग है, तो वेरिफ़ाई करें कि स्टार्ट और कंप्लीशन इवेंट्स एक ही कोरिलेशन ID का उपयोग करते हैं। + + 1. **Observe → Events** को open करें। + 2. एक short time window सेट करें और environment, agent, और event type के आधार पर filter करें। + 3. किसी event को select करें इसके normalized fields और raw payload को inspect करने के लिए, फिर execution context देखने के लिए इसके session को open करें। + 4. अगर कोई paired duration missing है, तो verify करें कि start और completion events एक ही correlation ID use कर रहे हैं। - डेटा को एक एजेंट रन तक संकुचित करने के लिए इवेंट्स स्ट्रीम का उपयोग करें और नॉर्मलाइज़्ड इवेंट फील्ड्स का निरीक्षण करें। + Events stream को use करके data को एक agent run तक narrow करें और normalized event fields को inspect करें। - ![एनवायरनमेंट, एजेंट, सेशन और इवेंट टाइप के लिए फ़िल्टर्स के साथ लाइव इवेंट्स स्ट्रीम।](/images/dashboard/events-stream.png) + ![Live Events stream जिसमें environment, agent, session, और event type के लिए filters हैं।](/images/dashboard/events-stream.png) - फिर इवेंट को इसके सेशन में फॉलो करें। ट्रेस दिखाता है कि इससे तुरंत पहले और बाद में क्या हुआ, जो आवश्यक है जब पेलोड अकेले अस्पष्ट हो। + फिर event को इसके session में follow करें। Trace दिखाता है कि इससे तुरंत पहले और बाद में क्या हुआ, जो तब आवश्यक है जब payload अकेले ambiguous हो। - ![एक्सीक्यूशन कॉन्टेक्स्ट में इवेंट का निरीक्षण करने के लिए उपयोग किया गया लिंक्ड सेशन ट्रेस।](/images/dashboard/session-detail.png) + ![Event को execution context में inspect करने के लिए इस्तेमाल किया गया linked session trace।](/images/dashboard/session-detail.png) - जब कोई पेयर्ड इवेंट या ड्यूरेशन मिसिंग हो तो दोनों व्यूज़ में कोरिलेशन ID और टाइमस्टैम्प की तुलना करें। + जब कोई paired event या duration missing है तो दोनों views में correlation IDs और timestamps की तुलना करें। - वैलिड फ़िल्टर वैल्यूज़ की खोज करें, फिर एक सेशन के लिए पूर्ण इवेंट पेलोड्स फेच करें: + Valid filter values को discover करें, फिर एक session के लिए full event payloads को fetch करें: ```bash fp list event_types @@ -47,32 +47,32 @@ icon: "list-tree" --full ``` - मशीन-रीडेबल इंस्पेक्शन के लिए `fp --json events ... --fields ts,event_type,session_id,payload` का उपयोग करें। + Machine-readable inspection के लिए `fp --json events ... --fields ts,event_type,session_id,payload` को use करें। -## रिज़र्व्ड SDK फील्ड्स +## Reserved SDK fields -कस्टम Python SDK फील्ड्स के रूप में `timestamp`, `session_id`, `agent_id`, `type` या `environment` का उपयोग न करें। पेयर्ड इवेंट ड्यूरेशन्स जैसे टूल रिज़ल्ट ड्यूरेशन SDK द्वारा कैलकुलेट किए जाते हैं और मैनुअली सप्लाई नहीं किए जा सकते। +`timestamp`, `session_id`, `agent_id`, `type`, या `environment` को custom Python SDK fields के रूप में use न करें। Tool result duration जैसे paired event durations को SDK द्वारा calculate किया जाता है और manually supply नहीं किया जा सकता। -## लोकल बाउंड्रीज़ +## Local boundaries -- Failproof AI स्टेट `~/.failproofai` के तहत रहता है जब तक कि एक्सप्लिसिटली अन्यथा कॉन्फ़िगर न किया जाए। -- `failproofai-sdk` अपने लीगेसी बेस-डायरेक्टरी ओवरराइड के लिए `AGENTEYE_HOME` का उपयोग करता है। -- एनवायरनमेंट लेबल्स SDK कॉन्फ़िगरेशन या `AGENTEYE_ENVIRONMENT` के माध्यम से सेट किए जा सकते हैं। -- डेमन क्रेडेंशियल्स नॉन-सीक्रेट सेटिंग्स से अलग से स्टोर किए जाते हैं। +- Failproof AI state `~/.failproofai` के अंतर्गत रहता है जब तक कि स्पष्ट रूप से अन्यथा configured न किया जाए। +- `failproofai-sdk` हमेशा `~/.failproofai/custom-agents` के अंतर्गत spool करता है। `FAILPROOFAI_HOME` उस home को relocate करता है; `custom-agents` segment हमेशा appended होता है, इसलिए spool को इसके बाहर place नहीं किया जा सकता। केवल SDK का अपना `configure(base_dir=...)` कहीं और लिखता है। `AGENTEYE_HOME` को पुराने `agenteye-collector` द्वारा पढ़ा जाता है यह चुनने के लिए कि क्या देखना है, और यह अब प्रभावित नहीं करता कि SDK कहां लिखता है। +- Environment labels को SDK configuration या `AGENTEYE_ENVIRONMENT` के माध्यम से सेट किया जा सकता है। +- Daemon credentials को non-secret settings से अलग से store किया जाता है। -स्टेबल, लो-कार्डिनेलिटी एनवायरनमेंट नेम्स का उपयोग करें। कॉमा डेमन एनवायरनमेंट लेबल्स में सपोर्टेड नहीं हैं। +Stable, low-cardinality environment names का use करें। Daemon environment labels में commas को support नहीं किया जाता है। -## एक एनवायरनमेंट लेबल बदलें +## Environment label को change करें - - एनवायरनमेंट लेबल्स एमिटिंग SDK या Failproof डेमन द्वारा असाइन किए जाते हैं। एक को बदलने के बाद, **Observe → Sessions** खोलें और एनवायरनमेंट फ़िल्टर का उपयोग करके कन्फर्म करें कि नए सेशन नई वैल्यू ले जाते हैं। एक्जिस्टिंग सेशन्स अपने ओरिजिनल एनवायरनमेंट को रिटेन करते हैं। + + Environment labels को emitting SDK या Failproof daemon द्वारा assign किया जाता है। एक को change करने के बाद, **Observe → Sessions** को open करें और environment filter को use करके confirm करें कि नए sessions नई value carry कर रहे हैं। Existing sessions अपने original environment को retain करते हैं। - `failproofai-sdk` के लिए, कोड में या इसके लीगेसी एनवायरनमेंट वेरिएबल के साथ एनवायरनमेंट कॉन्फ़िगर करें। मशीन-लेवल सेटिंग्स बदलते समय डेमन कॉन्फ़िगरेशन को री-रन करें। + `failproofai-sdk` के लिए, environment को code में या इसके legacy environment variable के साथ configure करें। Machine-level settings को change करते समय daemon configuration को rerun करें। ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/hi/reference/harnesses.mdx b/docs/hi/reference/harnesses.mdx index f372280e1..53e2c6897 100644 --- a/docs/hi/reference/harnesses.mdx +++ b/docs/hi/reference/harnesses.mdx @@ -1,71 +1,71 @@ --- -title: "एजेंट हार्नेसेस" -description: "सभी 12 समर्थित एजेंट हार्नेसेस में सत्र कैप्चर करें और नीतियों को लागू करें।" +title: "एजेंट हार्नेस" +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 (स्व-होस्टेड असिस्टेंट) -एक ही नीतियाँ और एक ही सत्र इतिहास वही लागू होता है चाहे कोई एजेंट किसी में भी चले। एक एडेप्टर लेयर प्रत्येक हार्नेस की मूल घटना नामों, उपकरण नामों, और उपकरण-इनपुट फ़ील्ड को 29 विहित घटनाओं में मैप करती है, इससे पहले कि कोई नीति चले। +एक ही नीतियां और एक ही सेशन हिस्ट्री लागू होती हैं, चाहे एजेंट किसी भी हार्नेस में चलता हो। एक एडाप्टर लेयर प्रत्येक हार्नेस के मूल इवेंट नामों, टूल नामों और टूल-इनपुट फ़ील्ड को किसी भी नीति के चलने से पहले 29 canonical इवेंट्स में मैप करता है। -एक एजेंट जो बारह में से **किसी में** नहीं चलता है, उसे [Python SDK](/hi/reference/custom-agents) के साथ सीधे संचालित किया जाता है। यह एक अलग अनुबंध है, और स्पष्ट रूप से कहना योग्य है: SDK ट्रेसिंग, सत्र, मूल्यांकन और ऑडिट प्रदान करता है — **यह अपने आप पर नीतियों को लागू नहीं करता है।** किसी असुरक्षित कार्यवाही को निष्पादित करने से पहले ब्लॉक करने के लिए आपके रनटाइम के टूल सीमा पर एक प्रवर्तन हुक की आवश्यकता होती है; [हमसे संपर्क करें](mailto:support@befailproof.ai) और हम इसे मैप करेंगे। +एक एजेंट जो बारह में से **किसी** में भी नहीं चलता है, वह [Python SDK](/hi/reference/custom-agents) के साथ सीधे instrumented होता है। यह एक अलग अनुबंध है, और स्पष्ट रूप से कहने के लिए महत्वपूर्ण है: SDK ट्रेसिंग, सेशन, मूल्यांकन और ऑडिट प्रदान करता है — **यह अपने आप नीतियों को लागू नहीं करता।** किसी असुरक्षित कार्य को निष्पादन से पहले ब्लॉक करने के लिए आपके runtime के टूल बाउंड्री पर enforcement hook की आवश्यकता है; [हमसे संपर्क करें](mailto:support@befailproof.ai) और हम इसे मैप करेंगे। -| हार्नेस | समर्थित हुक स्कोप | +| हार्नेस | समर्थित hook स्कोप | | --- | --- | -| 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 | -प्रत्येक एकीकरण नीतियों के चलने से पहले अपनी मूल हुक घटना नामों, उपकरण नामों, और उपकरण-इनपुट फ़ील्ड को सामान्य करता है। एक नीति केवल वही घटनाओं पर कार्य कर सकती है जो हार्नेस प्रदर्शित करता है; जिस सटीक हार्नेस और संस्करण को आप तैनात करते हैं, उस पर अंत-में-बदल और निर्देश व्यवहार का परीक्षण करें। +प्रत्येक एकीकरण नीतियों के चलने से पहले अपने मूल hook इवेंट नामों, टूल नामों और टूल-इनपुट फ़ील्ड को सामान्य करता है। एक नीति केवल उन इवेंट्स पर कार्य कर सकती है जो हार्नेस expose करता है; turn के अंत और instruction behavior को सटीक हार्नेस और version पर परीक्षण करें जिसे आप deploy करते हैं। -## प्रवर्तन क्षमता +## Enforcement क्षमता -"ब्लॉक" का मतलब है कि वर्तमान एडेप्टर का रिटर्न किया गया निर्णय नामित हार्नेस द्वारा खपत किया जाता है। पोस्ट-टूल ब्लॉकिंग मॉडल को दिखाया गया परिणाम बदल सकता है लेकिन एक टूल साइड इफेक्ट को पूर्ववत नहीं कर सकता जो पहले से ही घटित हुई हो। +"Block" का मतलब है कि वर्तमान एडाप्टर का returned verdict named हार्नेस द्वारा उपभोग किया जाता है। Post-tool blocking परिणाम को प्रतिस्थापित कर सकता है जो मॉडल को दिखाया जाता है लेकिन ऐसे tool side effect को पूर्ववत नहीं कर सकता जो पहले से ही हो चुका हो। -| हार्नेस | सत्यापित ब्लॉकिंग घटनाएँ | केवल अवलोकन या गैर-ब्लॉकिंग चेतावनियाँ | +| हार्नेस | Verified blocking events | अवलोकन-केवल या non-blocking चेतावनियां | | --- | --- | --- | -| 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`, और कई task/config events | `PostToolUse`, session lifecycle, notifications, और post-failure events अवलोकन योग्य हैं। | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Post-tool blocking निष्पादन के बाद परिणाम को प्रतिस्थापित करता है; session-start और compact events वर्तमान एडाप्टर में अवलोकन योग्य हैं। | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Post-tool blocking निष्पादन के बाद परिणाम को प्रतिस्थापित करता है; session और notification events अवलोकन योग्य हैं। | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` और session events अवलोकन योग्य हैं। | +| OpenCode | `PreToolUse` | Post-tool और lifecycle events अवलोकन योग्य हैं; वर्तमान stop handling बाद के turn के लिए निर्देशन के बजाय verified gate है। | +| Pi | `PreToolUse`, `UserPromptSubmit` | Post-tool और lifecycle events अवलोकन योग्य हैं; stop guidance बाद के turn पर लागू होती है। | +| Hermes | `PreToolUse` | Post-tool, session, और subagent-stop verdicts gates नहीं हैं। | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Post-tool, session, subagent-stop, और compaction events अवलोकन योग्य हैं। | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Post-tool और subagent-stop verdicts अवलोकन योग्य हैं। | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, conditional `PermissionRequest` | Permission hooks हर permission mode में नहीं चलते; post-tool और session events अवलोकन योग्य हैं। | +| Antigravity CLI | `PreToolUse`, `Stop` | User-prompt और post-tool verdicts अवलोकन योग्य हैं; prompt instructions अभी भी inject किए जा सकते हैं। | +| Goose | `PreToolUse` | User-prompt, post-tool, और session events अवलोकन योग्य हैं। एक मूल blocking stop hook upstream में मौजूद है लेकिन वर्तमान एडाप्टर द्वारा स्थापित नहीं है। | + +क्षमताएं version-sensitive हैं। एजेंट CLI को अपग्रेड करने के बाद फिर से परीक्षण करें, विशेषकर जब कोई नीति prompt, stop, permission, या post-tool behavior के बजाय common pre-tool gate पर निर्भर करती है। + +## कैप्चर और नीति hooks स्थापित करें - - 1. **प्रशासन → कुंजियाँ** खोलें और `events:add` और `policies:pull` के साथ एक कुंजी बनाएँ, मशीन या वातावरण के लिए नामित। - 2. लक्ष्य मशीन पर, प्रदर्शित कुंजी के साथ स्थानीय CLI को कनेक्ट करें और हार्नेस हुक स्थापित करें। - 3. एक नया एजेंट सत्र शुरू करें, फिर **अवलोकन → घटनाएँ** के तहत इसकी हुक और सत्र घटनाओं की पुष्टि करें। - 4. **अवलोकन → नीति** खोलें एक ही समय विंडो के लिए और पुष्टि करें कि एक नीति निर्णय मशीन को जिम्मेदार है। + + 1. **Administration → Keys** खोलें और `events:add` और `policies:pull` के साथ एक key बनाएं, मशीन या वातावरण के लिए नाम दें। + 2. लक्ष्य मशीन पर, प्रदर्शित key के साथ स्थानीय CLI को जोड़ें और harness hooks स्थापित करें। + 3. एक नया एजेंट सेशन शुरू करें, फिर **Observe → Events** के तहत इसके hook और session events की पुष्टि करें। + 4. **Observe → policy** खोलें एक ही समय विंडो के लिए और पुष्टि करें कि कोई नीति निर्णय मशीन को जिम्मेदार है। - कनेक्शन एक मशीन कुंजी के साथ शुरू होता है। पुष्टि करें कि इसमें अपनी गुप्त को कॉपी करने से पहले इनजेस्ट और नीति-वितरण दोनों अनुमतियाँ शामिल हैं। + कनेक्शन एक मशीन key से शुरू होता है। पुष्टि करें कि इसमें अपने secret को कॉपी करने से पहले ingestion और policy-delivery दोनों अनुमतियां शामिल हैं। - ![नई API कुंजी ड्रॉअर घटना इनजेस्ट और नीति वितरण अनुमतियाँ देने के लिए।](/images/dashboard/key-create.png) + ![नई API key ड्रॉवर event ingestion और policy delivery अनुमतियां प्रदान करने के लिए उपयोग की जाती है।](/images/dashboard/key-create.png) - हुक स्थापित करने के बाद, घटनाएँ स्ट्रीम आपके द्वारा कनेक्ट की गई मशीन और वातावरण से नई घटनाएँ दिखाना चाहिए। + Hooks स्थापित करने के बाद, Events stream को उस मशीन और वातावरण से नई events दिखानी चाहिए जिसे आपने जोड़ा है। - ![लाइव घटनाएँ स्ट्रीम एक नए स्थापित हार्नेस की रिपोर्टिंग की पुष्टि करने के लिए।](/images/dashboard/events-stream.png) + ![लाइव Events stream एक नए स्थापित harness की reporting की पुष्टि करने के लिए उपयोग किया जाता है।](/images/dashboard/events-stream.png) - अंत में, सत्यापित करें कि नीति निर्णय एक ही मशीन को जिम्मेदार हैं। यह पुष्टि करता है कि हार्नेस ट्रेस घटनाओं के साथ-साथ नीति गतिविधि की रिपोर्ट कर रहा है। + अंत में, सत्यापित करें कि नीति निर्णय एक ही मशीन को जिम्मेदार हैं। यह पुष्टि करता है कि harness trace events के साथ-साथ policy activity की रिपोर्ट कर रहा है। - ![नीति पृष्ठ नए कनेक्ट किए गए हार्नेस से नीति निर्णय सत्यापित करने के लिए।](/images/dashboard/policy-observe.png) + ![Policy page नए जुड़े हुए harness से नीति निर्णयों को सत्यापित करने के लिए उपयोग किया जाता है।](/images/dashboard/policy-observe.png) - प्रत्येक पता लगाए गए हार्नेस के लिए हुक स्थापित करें: + हर पाए गए harness के लिए hooks स्थापित करें: ```bash failproofai config \ @@ -74,7 +74,7 @@ icon: "plug-zap" failproofai policies --install ``` - या नामित हार्नेसेस और कॉन्फ़िगरेशन स्कोप को लक्ष्य करें: + या named harnesses और एक configuration scope को लक्ष्य करें: ```bash failproofai policies --install \ @@ -82,9 +82,9 @@ icon: "plug-zap" --scope user ``` - प्रोजेक्ट स्कोप हुक कॉन्फ़िगरेशन को एक रिपॉजिटरी के साथ रखता है। उपयोगकर्ता स्कोप रिपॉजिटरीज में काम को कवर करता है। Claude Code स्थानीय स्कोप को भी समर्थन करता है; समर्थन हार्नेस द्वारा भिन्न होता है और CLI असमर्थित संयोजनों को अस्वीकार करता है। + Project scope hook configuration को एक repository के साथ रखता है। User scope repositories में काम को कवर करता है। Claude Code भी local scope को समर्थन देता है; समर्थन harness द्वारा भिन्न होता है और CLI असमर्थित संयोजनों को अस्वीकार करता है। - मशीन और इसकी घटनाओं को सत्यापित करें: + मशीन और इसके events को सत्यापित करें: ```bash failproofai config --status @@ -94,16 +94,16 @@ icon: "plug-zap" -## एक गैर-डिफ़ॉल्ट सत्र पथ जोड़ें +## एक non-default session path जोड़ें - - अतिरिक्त पथ मशीन पर पंजीकृत होते हैं, क्लाउड में नहीं। एक जोड़ने के बाद, **अवलोकन → सत्र** खोलें, मशीन के वातावरण के लिए फ़िल्टर करें, और पुष्टि करें कि नए पथ से सत्र प्रदर्शित होते हैं। एक सत्र खोलें और ऑडिट में इस पर भरोसा करने से पहले एजेंट, हार्नेस, और घटना टाइमस्टैम्प की जांच करें। + + अतिरिक्त paths मशीन पर registered होते हैं, Cloud में नहीं। एक को जोड़ने के बाद, **Observe → Sessions** खोलें, मशीन के वातावरण के लिए filter करें, और नए path से sessions दिखाई दें। एक session खोलें और agent, harness, और event timestamps को जांचें इसे audit में उपयोग करने पर निर्भर होने से पहले। - ![सत्र सूची अतिरिक्त कैप्चर पथ से डेटा प्राप्त करने वाले वातावरण के लिए फ़िल्टर की गई।](/images/dashboard/sessions-list.png) + ![Sessions list को अतिरिक्त capture path से डेटा प्राप्त करने वाले वातावरण के लिए filtered।](/images/dashboard/sessions-list.png) - एक वैकल्पिक लेबल के साथ एक पथ जोड़ें, फिर कॉन्फ़िगर किए गए पथों का निरीक्षण करें: + एक optional label के साथ path जोड़ें, फिर configured paths inspect करें: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -112,10 +112,10 @@ icon: "plug-zap" failproofai backfill --since 7d ``` - `failproofai harness remove-path claude checkout` के साथ एक पथ हटाएँ। + `failproofai harness remove-path claude checkout` के साथ एक path को हटाएं। - स्थापना के बाद एक नया सत्र चलाएँ। रोलआउट को विस्तारित करने से पहले लाइव घटना स्ट्रीम और एक वास्तविक नीति निर्णय दोनों को सत्यापित करें। + स्थापन के बाद एक नया सेशन चलाएं। लाइव event stream और एक वास्तविक नीति निर्णय दोनों को सत्यापित करें rollout को expand करने से पहले। \ No newline at end of file diff --git a/docs/hi/reference/overview.mdx b/docs/hi/reference/overview.mdx index 4202af57d..8c36b54a2 100644 --- a/docs/hi/reference/overview.mdx +++ b/docs/hi/reference/overview.mdx @@ -1,61 +1,64 @@ --- title: "एकीकरण और संदर्भ" -description: "समर्थित एजेंट हार्नेस, SDK, CLI, और HTTP API को कनेक्ट करें।" +description: "समर्थित एजेंट harnesses, SDKs, CLIs, और HTTP API को कनेक्ट करें।" icon: "braces" --- -वह एकीकरण चुनें जो आपके एजेंट के वर्तमान स्थान के सबसे करीब हो। +वह एकीकरण चुनें जो आपके एजेंट के चलने वाले स्थान के सबसे करीब हो। - समर्थित कोडिंग और स्वायत्त एजेंट CLI के लिए हुक इंस्टॉल करें। + समर्थित कोडिंग और autonomous agent CLIs के लिए hooks इंस्टॉल करें। - - कस्टम एजेंट में विफलता खोजने के लिए ट्रेस को इंस्ट्रूमेंट करें, फिर अपने रनटाइम में रोकथाम जोड़ने के लिए हमसे संपर्क करें। + + LangGraph, CrewAI, LlamaIndex, Pydantic AI, या कस्टम एजेंट को इंस्ट्रूमेंट करें। - - स्थानीय प्रोजेक्ट, सेशन, नीति गतिविधि और ऑफ़लाइन ऑडिट की समीक्षा करें। + + कॉन्फ़िगरेशन, event catalog, correlation rules, और delivery। + + + स्थानीय projects, sessions, policy activity, और offline audits की समीक्षा करें। - स्थानीय कैप्चर, हुक, नीति, ऑडिट, डिलीवरी और मशीन स्थिति को कॉन्फ़िगर करें। + स्थानीय capture, hooks, policies, audits, delivery, और machine state को कॉन्फ़िगर करें। - Cloud सेशन, ऑडिट, समस्या, अलर्ट, कुंजी, उपयोगकर्ता और सेटिंग को क्वेरी और प्रशासित करें। + Cloud sessions, audits, issues, alerts, keys, users, और settings को क्वेरी और प्रशासित करें। - FastAPI सेवा के साथ पूर्ण या निष्क्रिय सेशन को स्कोर करें। + FastAPI service के साथ complete या inactive sessions को score करें। - - वर्कफ़्लो-विशिष्ट allow, instruct, और deny निर्णय लिखें और परीक्षण करें। + + workflow-specific allow, instruct, और deny निर्णय लिखें और परीक्षण करें। - Cloud नियंत्रण विमान को ग्राहक-प्रबंधित Kubernetes क्लस्टर पर परिनियोजित करें। + Cloud control plane को customer-managed Kubernetes cluster पर deploy करें। -जेनरेट किया गया [HTTP API संदर्भ](/hi/reference/http-api) सार्वजनिक `/v1` सतह को कवर करता है। हाथ से लिखित पृष्ठ वर्कफ़्लो की व्याख्या करते हैं जो कई एंडपॉइंट में फैले हुए हैं या उस सार्वजनिक सतह के बाहर प्रशासकीय इंटरफेस का उपयोग करते हैं। +जेनरेट किया गया [HTTP API संदर्भ](/hi/reference/http-api) सार्वजनिक `/v1` surface को कवर करता है। हाथ से लिखे गए पृष्ठ ऐसे workflows की व्याख्या करते हैं जो कई endpoints को span करते हैं या उस सार्वजनिक surface के बाहर प्रशासनिक इंटरफेस का उपयोग करते हैं। -## एजेंट को कनेक्ट करें और डेटा सत्यापित करें +## एजेंट को कनेक्ट करें और डेटा को सत्यापित करें - 1. **Administration → Keys** खोलें, `events:add` और `policies:pull` के साथ एक कुंजी बनाएं, और गोपनीय को कॉपी करें। - 2. ऊपर दिए गए मिलान पृष्ठ का उपयोग करके एकीकरण को कॉन्फ़िगर करें। - 3. **Observe → Events** खोलें यह पुष्टि करने के लिए कि घटनाएं आती हैं, फिर **Observe → Sessions** खोलें यह पुष्टि करने के लिए कि वे पूर्ण रन बनाती हैं। - 4. एकीकरण के पर्यावरण में फ़िल्टर करें और ऑडिट के लिए आवश्यक मॉडल, टूल, त्रुटि और नीति फ़ील्ड के लिए एक सेशन की जांच करें। + 1. **Administration → Keys** खोलें, `events:add` और `policies:pull` के साथ एक key बनाएं, और secret को कॉपी करें। + 2. ऊपर दिए गए मिलते-जुलते पृष्ठ का उपयोग करके एकीकरण को कॉन्फ़िगर करें। + 3. **Observe → Events** खोलें ताकि confirm करें कि events आ रहे हैं, फिर **Observe → Sessions** खोलें ताकि confirm करें कि वे complete runs बनाते हैं। + 4. एकीकरण के environment को फ़िल्टर करें और model, tool, error, और policy fields के लिए one session का निरीक्षण करें जो audits द्वारा आवश्यक हैं। - कुंजी ड्रॉअर से शुरू करें। चयनित अनुदान यह निर्धारित करते हैं कि क्या मशीन घटनाएं भेज सकती है और Cloud-प्रबंधित नीति प्राप्त कर सकती है। + key drawer से शुरू करें। चयनित grants यह निर्धारित करते हैं कि क्या मशीन events भेज सकती है और Cloud-managed policies प्राप्त कर सकती है। - ![नई API कुंजी ड्रॉअर जिसका उपयोग घटना सेवन और नीति वितरण अनुमति प्रदान करने के लिए किया जाता है।](/images/dashboard/key-create.png) + ![नया API key drawer जो event ingestion और policy delivery permissions प्रदान करने के लिए उपयोग किया जाता है।](/images/dashboard/key-create.png) - एकीकरण को कनेक्ट करने के बाद, यह पुष्टि करने के लिए सेशन सूची का उपयोग करें कि इसकी घटनाएं अपेक्षित पर्यावरण में पूर्ण रन में समूहीकृत की जा रही हैं। + एकीकरण को कनेक्ट करने के बाद, Sessions list का उपयोग करके confirm करें कि इसके events को expected environment में complete runs में group किया जा रहा है। - ![सेशन सूची जिसका उपयोग यह सत्यापित करने के लिए किया जाता है कि नव जुड़ा हुआ एकीकरण पूर्ण एजेंट रन की रिपोर्ट कर रहा है।](/images/dashboard/sessions-list.png) + ![Sessions list जो verify करने के लिए उपयोग किया जाता है कि एक नया-कनेक्ट किया गया एकीकरण complete agent runs की रिपोर्ट कर रहा है।](/images/dashboard/sessions-list.png) - एकीकरण को पूर्ण मानने से पहले इनमें से एक सेशन खोलें; ट्रेस में मॉडल, टूल, त्रुटि और नीति साक्ष्य होना चाहिए जो आपके ऑडिट को चाहिए। + एकीकरण को complete मानने से पहले इनमें से एक session को खोलें; trace में model, tool, error, और policy evidence होना चाहिए जो आपके audits को चाहिए। - एक मशीन कुंजी बनाएं, Failproof डेमन को कनेक्ट करें, और पहला सेशन सत्यापित करें। + एक machine key बनाएं, Failproof daemon को कनेक्ट करें, और पहले session को verify करें। ```bash fp keys create agent-production \ @@ -71,8 +74,8 @@ icon: "braces" fp events --since 1h --env production --limit 20 ``` - जब कोई अन्य टूल परिणाम का उपभोग करेगा तो `fp --json sessions ...` का उपयोग करें। `--json`, `--org`, और `--base-url` जैसे वैश्विक फ़्लैग कमांड से पहले आने चाहिए। + जब कोई अन्य tool परिणाम का उपभोग करेगा तो `fp --json sessions ...` का उपयोग करें। Global flags जैसे `--json`, `--org`, और `--base-url` को command से पहले आना चाहिए। - स्थानीय कमांड के लिए [Failproof AI CLI संदर्भ](/hi/reference/failproof-cli) और `fp` कमांड के लिए [Failproof Cloud CLI संदर्भ](/hi/reference/cloud-cli#cli-commands) देखें। + स्थानीय commands के लिए [Failproof AI CLI संदर्भ](/hi/reference/failproof-cli) और `fp` commands के लिए [Failproof Cloud CLI संदर्भ](/hi/reference/cloud-cli#cli-commands) देखें। \ No newline at end of file diff --git a/docs/hi/reference/troubleshooting.mdx b/docs/hi/reference/troubleshooting.mdx index ca25b3d53..6ff0f8c68 100644 --- a/docs/hi/reference/troubleshooting.mdx +++ b/docs/hi/reference/troubleshooting.mdx @@ -1,16 +1,16 @@ --- title: "समस्या निवारण" -description: "गायब सेशन, गायब नीतियों, विफल डिलीवरी और अवरुद्ध एजेंट कार्यों का निदान करें।" +description: "लापता सेशन, लापता नीतियों, विफल डिलीवरी और ब्लॉक किए गए एजेंट कार्यों का निदान करें।" icon: "wrench" --- - + - **Administration → Keys** खोलें और पुष्टि करें कि मशीन की कुंजी सक्रिय है और इसके पास `events:add` है। फिर **Observe → Events** खोलें, समय सीमा को चौड़ा करें, और पर्यावरण और एजेंट फ़िल्टर साफ़ करें। यदि ईवेंट मौजूद हैं, तो सेशन ID खोजें और फिर समूहीकरण के लिए **Observe → Sessions** जांचें। यदि कोई ईवेंट नहीं हैं, तो CLI से Failproof डेमॉन का निदान करें। + **Administration → Keys** खोलें और पुष्टि करें कि मशीन की कुंजी सक्रिय है और इसके पास `events:add` है। फिर **Observe → Events** खोलें, समय सीमा को चौड़ा करें और परिवेश तथा एजेंट फ़िल्टर को साफ़ करें। यदि イベंट मौजूद हैं, तो सेशन ID खोजें और फिर समूहीकरण के लिए **Observe → Sessions** देखें। यदि कोई इवेंट नहीं हैं, तो CLI से Failproof डेमन का निदान करें। - ![लाइव ईवेंट स्ट्रीम अपने प्राथमिक फ़िल्टर और हाल के एजेंट ईवेंट के साथ दिखाई दे रही है।](/images/dashboard/events-stream-current.png) + ![लाइव Events स्ट्रीम अपने प्राथमिक फ़िल्टर और हाल की एजेंट इवेंट के साथ दिखाई दे रहे हैं।](/images/dashboard/events-stream-current.png) ```bash @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - पुष्टि करें कि कैप्चर सक्षम है, कॉन्फ़िगर की गई कुंजी के पास `events:add` है, और डैशबोर्ड फ़िल्टर उत्सर्जित पर्यावरण से मेल खाता है। + पुष्टि करें कि कैप्चर सक्षम है, कॉन्फ़िगर की गई कुंजी के पास `events:add` है, और डैशबोर्ड फ़िल्टर उत्सर्जित परिवेश से मेल खाता है। - + - **Observe → Events** में फ़िल्टर साफ़ करें और सटीक SDK सेशन ID खोजें। यदि कुछ नहीं दिखता, तो स्रोत मशीन पर SDK स्पूल और Failproof डेमॉन का निरीक्षण करें। + **Observe → Events** में फ़िल्टर साफ़ करें और सटीक SDK सेशन ID खोजें। यदि कुछ नहीं दिखाई देता, तो स्रोत मशीन पर SDK स्पूल और Failproof डेमन की जांच करें। ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - पुष्टि करें कि एजेंट प्रक्रिया `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` सेट करती है और SDK शुरू होने से पहले `$FAILPROOFAI_HOME/custom-agents`, अन्यथा `~/.failproofai/custom-agents`, मौजूद है। + पुष्टि करें कि एक डेमन चल रहा है और जुड़ा हुआ है — SDK स्पूल करता है चाहे कोई हो या न हो। स्पूल डायरेक्टरी को पहले से मौजूद होने की **आवश्यकता नहीं** है (लेखक इसे बनाता है), और कोई पर्यावरण चर इसे नहीं चुनता: `$FAILPROOFAI_HOME/custom-agents`, अन्यथा `~/.failproofai/custom-agents` ही एकमात्र रूट है, और `configure(base_dir=...)` एकमात्र ओवरराइड है। यदि प्रक्रिया `SIGKILL` की गई थी या OOM-killed की गई थी, तो जो कुछ भी अभी भी कतारबद्ध था, वह खो गया — `SIGTERM` को हैंडल करें। - + - **Admin → enforcement** खोलें, मशीन का चयन करें, और इसके असाइन किए गए, रिपोर्ट किए गए और पिछले संस्करणों की तुलना करें। पुष्टि करें कि तैनाती का दायरा मशीन को शामिल करता है और इसकी कुंजी के पास `policies:pull` है। इंजेस्ट तब भी काम कर सकता है जब नीति डिलीवरी न हो। + **Admin → enforcement** खोलें, मशीन का चयन करें और इसके असाइन किए गए, रिपोर्ट किए गए और पिछले संस्करणों की तुलना करें। पुष्टि करें कि तैनाती का दायरा मशीन को शामिल करता है और इसकी कुंजी के पास `policies:pull` है। इनजेस्ट तब भी काम कर सकता है जब नीति डिलीवरी न हो। @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - पुष्टि करें कि मशीन ID और लेबल डैशबोर्ड लक्ष्य से मेल खाते हैं। यदि मौजूदा क्रेडेंशियल केवल ईवेंट इंजेस्ट देता है, तो नीति-सक्षम कुंजी से फिर से कनेक्ट करें। + पुष्टि करें कि मशीन ID और लेबल डैशबोर्ड लक्ष्य से मेल खाते हैं। यदि मौजूदा क्रेडेंशियल केवल इवेंट इनजेस्शन देता है, तो नीति-सक्षम कुंजी के साथ फिर से कनेक्ट करें। - + - **Admin → enforcement** खोलें और मशीन के अंतिम-देखे गए समय और रिपोर्ट किए गए संस्करण का निरीक्षण करें। यदि मशीन पुरानी है, तो इसे एक स्थानीय डेमॉन समस्या के रूप में मानें। अनुपलब्ध डेमॉन को बायपास करने के लिए तैनात की गई नीति को कमजोर न करें। + **Admin → enforcement** खोलें और मशीन के अंतिम-देखे गए समय और रिपोर्ट किए गए संस्करण की जांच करें। यदि मशीन पुरानी है, तो इसे स्थानीय डेमन समस्या के रूप में मानें। अनुपलब्ध डेमन को बायपास करने के लिए तैनात नीति को कमजोर न करें। @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - `failproofaid` को पुनः शुरू या अपडेट करें; जब CLI और डेमॉन प्रोटोकॉल संस्करण भिन्न हों तो कॉन्फ़िगरेशन दोबारा चलाएं। कॉन्फ़िगर किया गया डेमॉन पाथ डिज़ाइन द्वारा विफल हो जाता है। + `failproofaid` को पुनः प्रारंभ या अपडेट करें; जब CLI और डेमन प्रोटोकॉल संस्करण भिन्न हों तो कॉन्फ़िगरेशन को फिर से चलाएं। कॉन्फ़िगर किया गया डेमन पाथ डिजाइन से विफल रहता है। - + - Cloud-लेखक नीति के लिए, **Admin → policy editor** खोलें, ड्राफ्ट का चयन करें, और प्रकाशित करने से पहले सत्यापन त्रुटियों की समीक्षा करें। स्थानीय नीति के लिए, इसे सत्यापित करने के लिए CLI का उपयोग करें, फिर परीक्षण कार्य के बाद निर्णय आने की पुष्टि करने के लिए **Observe → policy** खोलें। + Cloud द्वारा लिखी गई नीति के लिए, **Admin → policy editor** खोलें, ड्राफ्ट का चयन करें और प्रकाशित करने से पहले सत्यापन त्रुटियों की समीक्षा करें। स्थानीय नीति के लिए, CLI का उपयोग करके इसे सत्यापित करें, फिर परीक्षण कार्य के बाद **Observe → policy** खोलें यह पुष्टि करने के लिए कि निर्णय आए हैं। - पुष्टि करें कि फ़ाइलनाम `policies.js`, `policies.mjs` या `policies.ts` में समाप्त होता है, मॉड्यूल `customPolicies.add(...)` को कॉल करता है, और आयात नीति फ़ाइल से हल होते हैं। + पुष्टि करें कि फ़ाइल नाम `policies.js`, `policies.mjs`, या `policies.ts` में समाप्त होता है, मॉड्यूल `customPolicies.add(...)` को कॉल करता है, और आयात नीति फ़ाइल से हल होते हैं। ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -91,12 +91,12 @@ icon: "wrench" - + - **Analyze → audits** खोलें, रन का चयन करें, और जांचें कि क्या मॉडल विश्लेषण चला। फिर इसके दायरे और विंडो की तुलना **Observe → sessions** से करें और उस जनसंख्या से प्रतिनिधि ट्रेस खोलें। + **Analyze → audits** खोलें, रन का चयन करें और जांचें कि क्या मॉडल विश्लेषण चला। फिर इसके दायरे और विंडो की तुलना **Observe → sessions** के साथ करें और उस जनसंख्या से प्रतिनिधि ट्रेस खोलें। - शून्य परिणाम तभी अर्थपूर्ण है जब विश्लेषण सफलतापूर्वक चला हो। यदि विश्लेषण छोड़ दिया गया था या विफल रहा, तो रन कोई निष्कर्ष नहीं देता और अविश्लेषित विंडो को भविष्य के सफल रन के लिए खुला रखता है। यदि मॉडल विश्लेषण अक्षम है, तो ऑडिट भी कोई निष्कर्ष नहीं देता क्योंकि नियतात्मक क्रेडेंशियल और PII स्कैन आँकड़े रिकॉर्ड करते हैं लेकिन अब निष्कर्ष नहीं उठाते। + एक शून्य परिणाम तभी सार्थक है जब विश्लेषण सफलतापूर्वक चले। यदि विश्लेषण छोड़ा गया था या विफल रहा था, तो रन कोई खोज नहीं देता है और अविश्लेषित विंडो को भविष्य के सफल रन के लिए खुला रखता है। यदि मॉडल विश्लेषण अक्षम है, तो ऑडिट भी कोई खोज नहीं देता है क्योंकि नियतकालिक क्रेडेंशियल और PII स्कैन सांख्यिकी रिकॉर्ड करता है लेकिन अब निष्कर्ष नहीं निकालता है। ![ऑडिट फॉर्म जहां पर्यावरण, एजेंट, कैडेंस और स्वीप विंडो सेशन जनसंख्या को परिभाषित करते हैं।](/images/dashboard/audit-new.png) @@ -110,31 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - यदि रन कतारबद्ध रहा, तो ऑडिट-एजेंट क्षमता के लिए प्रतीक्षा करें या तैनाती ऑपरेटर से ऑडिट फ्लीट का निरीक्षण करने के लिए कहें। कतारबद्ध ऑडिट पुनः प्रयास करता है; इसे तुरंत छोड़ा नहीं जाता। + यदि रन कतारबद्ध रहा, तो ऑडिट-एजेंट क्षमता की प्रतीक्षा करें या तैनाती ऑपरेटर को ऑडिट फ्लीट का निरीक्षण करने के लिए कहें। एक कतारबद्ध ऑडिट पुनः प्रयास करता है; यह तुरंत छोड़ा नहीं जाता है। - + - एक पूर्ण सेशन खोलें और जांचें कि क्या मैनुअल मूल्यांकन सफल होता है। होस्ट किए गए Cloud में वर्तमान में डैशबोर्ड में कोई मूल्यांकनकर्ता एंडपॉइंट नियंत्रण नहीं है; सर्वर ऑपरेटर को इसे कॉन्फ़िगर करना चाहिए। + एक पूर्ण सेशन खोलें और जांचें कि क्या मैनुअल मूल्यांकन सफल होता है। होस्ट किया गया Cloud वर्तमान में डैशबोर्ड में कोई मूल्यांकनकर्ता एंडपॉइंट नियंत्रण नहीं है; सर्वर ऑपरेटर को इसे कॉन्फ़िगर करना होगा। - मूल्यांकनकर्ता को सत्यापित करें, फिर हाल की मूल्यांकन अवस्थाओं का निरीक्षण करें: + मूल्यांकनकर्ता को सत्यापित करें, फिर हाल की मूल्यांकन स्थितियों का निरीक्षण करें: ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - स्वयं-होस्ट किए गए Cloud पर, पुष्टि करें कि `EVALUATOR_ENDPOINT` सर्वर पर मौजूद है और `EVALUATOR_TOKEN` मूल्यांकनकर्ता से मेल खाता है। जब एंडपॉइंट अनुपस्थित हो तो स्वचालित मूल्यांकन अक्षम होता है। + स्व-होस्ट किए गए Cloud पर, पुष्टि करें कि `EVALUATOR_ENDPOINT` सर्वर पर मौजूद है और `EVALUATOR_TOKEN` मूल्यांकनकर्ता से मेल खाता है। जब एंडपॉइंट अनुपस्थित हो तो स्वचालित मूल्यांकन अक्षम है। - + - संगठन स्विचर का उपयोग करें और CLI के साथ परिणामों की तुलना करने से पहले अपेक्षित स्लग और अनुमतियों की पुष्टि करें। + संगठन स्विचर का उपयोग करें और CLI के साथ परिणामों की तुलना करने से पहले अपेक्षित slug और अनुमतियों की पुष्टि करें। ```bash @@ -143,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - API-कुंजी मोड में, `fp --org --api-key ...` निर्दिष्ट करें या `AGENTEYE_ORG` सेट करें। सहेजी गई मानव-सेशन संगठन अवस्था जानबूझकर API-कुंजी अनुरोधों के लिए अनदेखी की जाती है। + API-कुंजी मोड में, `fp --org --api-key ...` निर्दिष्ट करें या `AGENTEYE_ORG` सेट करें। सहेजी गई मानव-सेशन संगठन स्थिति जानबूझकर API-कुंजी अनुरोधों के लिए अनदेखी की जाती है। - + - **Observe → policy** खोलें, निर्णय और लिंक किए गए सेशन को संरक्षित करें, और गलत-सकारात्मक स्थिति की पहचान करें। फिर **Admin → enforcement** खोलें और प्रभावित मशीनों को पिछले संस्करण पर रोल बैक करें। **Policy editor** में एक संकीर्ण संस्करण बनाएं, इसे छोटे दायरे पर परीक्षण करें, और केवल तभी विस्तारित करें जब वैध कार्य सफल हो। + **Observe → policy** खोलें, निर्णय और जुड़े सेशन को सुरक्षित रखें और झूठी-सकारात्मक स्थिति की पहचान करें। फिर **Admin → enforcement** खोलें और प्रभावित मशीनों को पिछले संस्करण पर रोल करें। **Policy editor** में एक संकीर्ण संस्करण बनाएं, इसे एक छोटे दायरे पर परीक्षण करें और केवल वैध कार्य के सफल होने के बाद ही विस्तार करें। - Cloud तैनाती रोलबैक केवल डैशबोर्ड-केवल है। एक स्थानीय सेशन विराम Cloud-प्रबंधित नीतियों को अक्षम नहीं करता है। यदि डैशबोर्ड अनुपलब्ध है, तो मशीन और तैनाती अवस्था को कैप्चर करें और डैशबोर्ड पहुंच को बहाल करें बजाय अवरुद्ध कार्य को बार-बार दोबारा करने के। + Cloud तैनाती रोलबैक केवल डैशबोर्ड है। स्थानीय सेशन पॉज़ Cloud-प्रबंधित नीतियों को अक्षम नहीं करता है। यदि डैशबोर्ड उपलब्ध नहीं है, तो मशीन और तैनाती स्थिति को कैप्चर करें और डैशबोर्ड पहुंच को पुनः स्थापित करें बजाय बार-बार ब्लॉक किए गए कार्य को फिर से प्रयास करने के। ```bash failproofai config --status @@ -164,4 +164,4 @@ icon: "wrench" -समर्थन से संपर्क करते समय, CLI संस्करण, हार्नेस, पर्यावरण, प्रासंगिक सेशन या तैनाती ID, और गुप्त जानकारी हटाकर `failproofai config --status` का आउटपुट शामिल करें। \ No newline at end of file +सहायता से संपर्क करते समय, CLI संस्करण, हार्नेस, पर्यावरण, प्रासंगिक सेशन या तैनाती ID और `failproofai config --status` का आउटपुट शामिल करें (गोपनीयता सामग्री को हटाकर)। \ No newline at end of file diff --git a/docs/hi/sessions/live-events.mdx b/docs/hi/sessions/live-events.mdx index 1066917c0..9d38df797 100644 --- a/docs/hi/sessions/live-events.mdx +++ b/docs/hi/sessions/live-events.mdx @@ -1,21 +1,21 @@ --- -title: "लाइव events" -description: "किसी सत्र के चलते हुए agent activity को देखें।" +title: "लाइव इवेंट्स" +description: "सेशन चलते हुए एजेंट की गतिविधि को देखें।" icon: "radio" --- -लाइव events आपको instrumentation की पुष्टि करने और जोखिम भरे run को देखने में मदद करते हैं, बिना सत्र के समाप्त होने का इंतजार किए। +लाइव इवेंट्स आपको instrumentation की पुष्टि करने और सेशन समाप्त होने की प्रतीक्षा किए बिना एक जोखिम भरे रन को देखने में मदद करते हैं। -## Activity देखें +## गतिविधि देखें 1. **Observe → Events** पर जाएं। - 2. वर्तमान समय विंडो के साथ शुरू करें और डेटा आने की पुष्टि करने के लिए कोई फ़िल्टर न रखें। - 3. Environment, event type, agent, या session के आधार पर फ़िल्टर करें। Payload text के लिए search का उपयोग करें। - 4. एक event चुनें इसके सारांश और विवरण को देखने के लिए। पूरी trace के लिए इसके session link को फॉलो करें। + 2. वर्तमान समय विंडो से शुरू करें और डेटा आने की पुष्टि करने के लिए कोई फ़िल्टर न लागू करें। + 3. वातावरण, इवेंट प्रकार, एजेंट, या सेशन के आधार पर फ़िल्टर करें। पेलोड टेक्स्ट के लिए सर्च का उपयोग करें। + 4. किसी इवेंट को चुनकर इसका सारांश और विवरण देखें। पूर्ण ट्रेस के लिए इसके सेशन लिंक का अनुसरण करें। - ![लाइव Events stream जो Hermes chat gateway से traffic दिखा रहा है साथ ही coding-CLI runs, समय, environment, event type, agent, model, context, और session के आधार पर फ़िल्टर किए गए।](/images/dashboard/events-stream-current.png) + ![लाइव Events स्ट्रीम जो Hermes chat gateway से आने वाली ट्रैफ़िक और coding-CLI रन को दिखाती है, समय, वातावरण, इवेंट प्रकार, एजेंट, मॉडल, संदर्भ और सेशन के आधार पर फ़िल्टर की गई है।](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +24,22 @@ icon: "radio" fp --json events --full --session-id --all ``` - डिफ़ॉल्ट feed raw payloads को छोड़ देता है। `--full` का उपयोग केवल bounded session investigation के लिए करें। + डिफ़ॉल्ट फीड raw पेलोड्स को छोड़ता है। `--full` का उपयोग केवल एक सीमित सेशन की जांच के लिए करें। -तीन तुरंत सवालों के जवाब देने के लिए event stream का उपयोग करें: +इवेंट स्ट्रीम का उपयोग करके तीन तत्काल सवालों के जवाब दें: -- क्या अपेक्षित agent सही environment को रिपोर्ट कर रहा है? -- क्या model calls, tool calls, और policy decisions क्रम में आ रहे हैं? -- क्या सत्र प्रगति करना बंद कर गया है या किसी action को दोहराना शुरू कर दिया है? +- क्या अपेक्षित एजेंट सही वातावरण को रिपोर्ट कर रहा है? +- क्या मॉडल कॉल, टूल कॉल और नीति निर्णय क्रम में आ रहे हैं? +- क्या सेशन ने प्रगति करना बंद कर दिया है या किसी क्रिया को दोहराना शुरू कर दिया है? -Event types में agent lifecycle events, model requests और responses, tool use और results, hook execution, human waits और interrupts, और explicit errors शामिल हैं। Correlation IDs जोड़ी गई events को जोड़ते हैं जैसे कि एक tool call और इसका result। +इवेंट प्रकारों में एजेंट लाइफसाइकल इवेंट्स, मॉडल अनुरोध और प्रतिक्रियाएं, टूल का उपयोग और परिणाम, हुक निष्पादन, मानव प्रतीक्षा और बाधाएं, और स्पष्ट त्रुटियां शामिल हैं। Correlation ID को एक टूल कॉल और इसके परिणाम जैसी युग्मित इवेंट्स को जोड़ता है। - किसी नए integration को सत्यापित करते समय लाइव view को व्यापक रखें। पहले event को देखने के बाद ही फ़िल्टर जोड़ें; एक गलत फ़िल्टर विफल ingestion जैसा दिख सकता है। + नए integration की पुष्टि करते समय लाइव दृश्य को व्यापक रखें। पहली इवेंट दिखने के बाद ही फ़िल्टर जोड़ें; एक गलत फ़िल्टर विफल ingestion की तरह दिख सकता है। -यदि कोई events दिखाई न दें, तो `failproofai config --status` चलाएं, फिर [troubleshoot ingestion](/hi/reference/troubleshooting)। +यदि कोई इवेंट्स दिखाई न दें, तो `failproofai config --status` चलाएं, फिर [ingestion troubleshoot करें](/hi/reference/troubleshooting)। -Agents जो 12 समर्थित [harnesses](/hi/reference/harnesses) में से किसी एक में नहीं चलते हैं, [Python SDK](/hi/reference/custom-agents) के माध्यम से एक ही event types रिपोर्ट करते हैं, जिनमें human-in-the-loop events (`human_wait`, `human_input`, `human_interrupt`) शामिल हैं जो gateway और production agents पर निर्भर हैं। \ No newline at end of file +एजेंट जो समर्थित 12 [harnesses](/hi/reference/harnesses) में से किसी में भी चलते नहीं हैं, [Python SDK](/hi/reference/custom-agents) के माध्यम से समान इवेंट प्रकार की रिपोर्ट करते हैं, जिसमें मानव-इन-द-लूप इवेंट्स (`human_wait`, `human_input`, `human_interrupt`) शामिल हैं जो gateway और production एजेंट पर निर्भर हैं। \ No newline at end of file diff --git a/docs/hi/start/first-policy.mdx b/docs/hi/start/first-policy.mdx index acaede7ed..e57f6b174 100644 --- a/docs/hi/start/first-policy.mdx +++ b/docs/hi/start/first-policy.mdx @@ -1,34 +1,34 @@ --- --- title: "अपनी पहली विफलता को एक नीति के साथ रोकें" -description: "एक नीति संस्करण तैयार करें, इसे observe मोड में तैनात करें, और फिर इसे लागू करें।" +description: "एक नीति संस्करण लेखन करें, इसे observe मोड में तैनात करें, और फिर इसे लागू करें।" icon: "shield-check" --- -किसी नीति का उपयोग केवल तभी करें जब आप असुरक्षित कार्रवाई और उन वैध कार्रवाइयों का वर्णन कर सकें जिन्हें अनुमति दी जानी चाहिए। +किसी नीति का उपयोग केवल तभी करें जब आप असुरक्षित कार्रवाई और उन वैध कार्रवाइयों का वर्णन कर सकें जिन्हें अनुमत रहना चाहिए। - - **Admin → policy editor** पर जाएं। डेमो नीति से शुरुआत करें, इसके स्रोत की समीक्षा करें या संपादित करें, फिर **publish version** का चयन करें। प्रकाशन एक अपरिवर्तनीय संस्करण बनाता है जिसे आप मशीनों पर तैनात कर सकते हैं। + + **Admin → policy editor** पर जाएं। डेमो नीति से शुरुआत करें, इसके स्रोत की समीक्षा करें या संपादित करें, फिर **publish version** चुनें। प्रकाशन एक अपरिवर्तनीय संस्करण बनाता है जिसे आप मशीनों पर तैनात कर सकते हैं। - ![नीति संपादक compose दृश्य एक अपरिवर्तनीय संस्करण के रूप में प्रकाशित करने के लिए तैयार डेमो नीति के साथ।](/images/dashboard/policy-editor.png) + ![पॉलिसी एडिटर कंपोज़ व्यू एक डेमो नीति के साथ एक अपरिवर्तनीय संस्करण के रूप में प्रकाशित करने के लिए तैयार है।](/images/dashboard/policy-editor.png) - **Admin → enforcement** पर जाएं, लक्ष्य मशीन को विस्तारित करें, और **edit this machine** का चयन करें। प्रकाशित डेमो नीति जोड़ें, इसके संस्करण को pin करें, **observe** चुनें, और तैनाती लागू करें। + **Admin → enforcement** पर जाएं, लक्ष्य मशीन को विस्तारित करें, और **edit this machine** चुनें। प्रकाशित डेमो नीति जोड़ें, इसके संस्करण को पिन करें, **observe** चुनें, और तैनाती लागू करें। - ![मशीन तैनाती संपादक जिसमें observe मोड में तैनाती लागू करने से पहले एक प्रकाशित नीति संस्करण चयनित है।](/images/dashboard/enforcement-editor.png) + ![मशीन तैनाती संपादक एक प्रकाशित नीति संस्करण के साथ observe मोड में तैनाती लागू करने से पहले चुना गया है।](/images/dashboard/enforcement-editor.png) - - उस मशीन पर एक नया agent सेशन चलाएं, फिर **Observe → policy** खोलें। मशीन का चयन करें और पुष्टि करें कि डेमो नीति नीति मैपिंग और निर्णय टाइमलाइन में दिखाई देती है। Observe मोड रिकॉर्ड करता है कि नीति क्या करेगी, लेकिन कार्रवाई को ब्लॉक नहीं करती। + + उस मशीन पर एक नया एजेंट सत्र चलाएं, फिर **Observe → policy** खोलें। मशीन चुनें और पुष्टि करें कि डेमो नीति नीति मानचित्रण और निर्णय समयरेखा में दिखाई देती है। Observe मोड रिकॉर्ड करता है कि नीति क्या करेगी बिना कार्रवाई को ब्लॉक किए। - ![नीति पृष्ठ जो निर्णय कुल, समय के साथ प्रवर्तन गतिविधि, और स्थानीय और Cloud-प्रबंधित नीति मैपिंग दिखाता है।](/images/dashboard/policy-observe.png) + ![पॉलिसी पेज निर्णय योग, समय के साथ प्रवर्तन गतिविधि, और स्थानीय और क्लाउड-प्रबंधित नीति मानचित्रण दिखा रहा है।](/images/dashboard/policy-observe.png) - Cloud नीति लेखन और fleet तैनाती प्रशासनिक कार्यप्रवाह हैं। इसे प्रकाशित करने से पहले स्थानीय CLI का उपयोग करके समान नीति को सत्यापित करें: + क्लाउड नीति लेखन और फ्लीट तैनाती प्रशासनिक वर्कफ़्लो हैं। इसे प्रकाशित करने से पहले स्थानीय CLI का उपयोग करके एक ही नीति को मान्य करें: ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -36,13 +36,13 @@ icon: "shield-check" failproofai config --status ``` - Cloud-दृश्यमान नीति निर्णयों का निरीक्षण करने के लिए `fp` का उपयोग करें: + क्लाउड-दृश्यमान नीति निर्णयों का निरीक्षण करने के लिए `fp` का उपयोग करें: ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - Cloud CLI रूट-केवल प्रवर्तन तैनाती मार्ग को उजागर नहीं करता है। **Admin → policy editor** से संस्करण प्रकाशित करें और **Admin → enforcement** से उन्हें तैनात करें। + दोनों चरण CLI से भी उपलब्ध हैं: `fp policies publish ` एक संस्करण बनाता है और `fp fleet deploy --add ` इसे एक मशीन पर रखता है। डैशबोर्ड समकक्ष **Admin → policy editor** और **Admin → enforcement** हैं। \ No newline at end of file diff --git a/docs/hi/start/integrations.mdx b/docs/hi/start/integrations.mdx new file mode 100644 index 000000000..4aa18fa23 --- /dev/null +++ b/docs/hi/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "अपने एजेंट को इंस्ट्रूमेंट करें" +sidebarTitle: "फ्रेमवर्क" +description: "किसी भी समर्थित एजेंट फ्रेमवर्क को Failproof AI से एक कॉल के साथ कनेक्ट करें।" +icon: "plug" +--- + +आपका एजेंट पहले से ही सब कुछ तैयार करता है जो रिकॉर्ड करने योग्य है — मॉडल कॉल, टूल कॉल, नोड बाउंड्रीज़, मानव प्रतीक्षा, विफलताएं। फ्रेमवर्क इसे फेंक देता है। SDK इसे रखता है। + + + + एक एजेंट जो आपने स्वयं लिखा है, या यहाँ सूचीबद्ध नहीं है। + + + ग्राफ़, नोड्स, टूल्स, रिट्रीवर्स, मॉडल्स। + + + क्रूज़, फ्लोज़, भूमिका के अनुसार एजेंट, टूल्स। + + + वर्कफ्लोज़, स्टेप्स, फंक्शन एजेंट्स, रिट्रीवर्स। + + + टाइप्ड एजेंट्स, क्षमताएं, टूल्स, रिट्राइज़। + + + +## तीन लाइनें, कोई भी फ्रेमवर्क + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # आपके द्वारा इंपोर्ट किए गए फ्रेमवर्क को डिटेक्ट करता है + +with failproofai_sdk.session(): + ... # आपकी मौजूदा एजेंट कॉल, अपरिवर्तित +``` + +आपके फंक्शन्स पर कोई डेकोरेटर नहीं, आपकी कॉल्स को कोई कॉलबैक पास नहीं, आपके कोड के माध्यम से कोई आईडी नहीं। केवल सेशन के अंदर की कॉल अलग है: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # `async with failproofai_sdk.session():` के तहत + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +अतिरिक्त इंस्टॉल **फ्रेमवर्क** करता है। हर एडेप्टर बेस व्हील में शामिल है, इसलिए एक प्रोजेक्ट जिसके पास पहले से ही अपना फ्रेमवर्क है, उसे बिल्कुल कोई अतिरिक्त की ज़रूरत नहीं है। + +## जाँचें कि यह पहुँचा + +एक इंस्ट्रूमेंटेड सेशन चलाएं, फिर **Observe → Sessions** खोलें और अपना एनवायरनमेंट चुनें। रन एक पुनर्निर्मित ट्रेस के रूप में दिखाई देता है। + +यदि कुछ नहीं आता है, तो `failproofai config --status` के साथ पुष्टि करें कि मशीन कनेक्ट है। [कैप्चर सेट अप करें](/hi/start/setup) देखें। + + + डिलीवरी की पुष्टि करने के लिए स्पूल डायरेक्टरी को चेक न करें। Failproof डेमन मिलीसेकंड के भीतर प्रत्येक बैच को एकत्र करता है और हटाता है, इसलिए इसे पढ़ना कलेक्टर के साथ दौड़ता है और उत्सर्जित इवेंट्स की तुलना में बहुत कम दिखाता है। + + +## अगला + +प्रत्येक क्विकस्टार्ट ऊपर अपनी पूर्ण गाइड से लिंक करता है — क्या रिकॉर्ड किया जाता है, विकल्प, स्ट्रीमिंग, स्पैन नामकरण, और जो समस्याएं लोग वास्तव में मारते हैं। वे **Trace Agents → अपने एजेंट को प्लग इन करें** के तहत रहते हैं। + + + + डेटा मॉडल, आईडी, इवेंट प्रकार, और इवेंट्स कैसे क्लाउड तक पहुँचते हैं। + + + विच्छिन्न लॉग्स के बजाय एक सेशन के माध्यम से कारणता का अनुसरण करें। + + + आपके द्वारा अभी कैप्चर किए गए सेशन्स का ऑडिट करें। + + \ No newline at end of file diff --git a/docs/hi/start/integrations/crewai.mdx b/docs/hi/start/integrations/crewai.mdx new file mode 100644 index 000000000..0ed13312e --- /dev/null +++ b/docs/hi/start/integrations/crewai.mdx @@ -0,0 +1,225 @@ +--- +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "Crews, flows, agents को भूमिका, tools, memory और human feedback द्वारा instrument करें।" +icon: "/images/frameworks/crewai.svg" +--- + +## इंस्टॉल करें + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +समर्थित: `crewai` 1.13 से 2.0 तक। 1.13 वह रिलीज़ है जिसने `started_event_id` जोड़ा और token usage को normalize किया, दोनों जो adapter को events को pair करने और tokens की रिपोर्ट करने के लिए आवश्यक हैं। + +## Instrument करें + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` CrewAI के module-level event bus पर एक listener रजिस्टर करता है और प्रत्येक event class के लिए एक handler subscribe करता है। आपके crew, agents, tasks या tools के बारे में कुछ नहीं बदलता। + +## क्या रिकॉर्ड होता है + +| CrewAI | Failproof event | +| --- | --- | +| Crew kickoff | `agent_start`, `agent_end` | +| `Agent.kickoff()` (एक lite agent, कोई crew नहीं) | `agent_start`, `agent_end`, role से `agent_id` के साथ | +| Flow start और finish | `agent_start`, `agent_end`; एक flow method के अंदर kicked off crew इसके अंतर्गत nest करता है | +| Agent execution | Nested `agent_start`, `agent_end`, role से `agent_id` के साथ। एक hierarchical process के अंतर्गत एक delegated coworker manager के अंतर्गत nest करता है, इसके बगल में नहीं | +| Task | कुछ नहीं; एक link के रूप में रिकॉर्ड किया जाता है ताकि children crew को resolve करें | +| Flow method, guardrail | `hook_triggered`, `hook_completed` | +| Tool usage | `tool_use`, `tool_result` | +| Memory और knowledge operations | `tool_use`, `tool_result`, surface hit के लिए नामित | +| LLM call | `model_request`, `model_response`, token usage के साथ | +| Stream chunk | Response में chunk count और time to first token के रूप में folded | +| Human feedback requested | `human_wait`, `agent_pause` | +| Human feedback received | `agent_resume`, `human_input` | +| Agent execution error | `error`, फिर `agent_end` outcome `failed` के साथ | + +एक task जानबूझकर कुछ नहीं emit करता। एक CrewAI task उस agent execution का एक subset है जो इसे चलाता है, इसलिए दोनों को emit करने से हर row duplicate होगी और उन्हें siblings के रूप में render करेगा। Task id और name agent के अपने events पर सवारी करते हैं। + +Memory और knowledge operations को tools के रूप में रिकॉर्ड किया जाता है, जो surface के लिए नामित होते हैं जहां वे hit करते हैं, इसलिए वे आपके real tools के बगल में दिखाई देते हैं जहां आप उनकी latency की तुलना कर सकते हैं। + +एक hierarchical crew पर, nesting ही है जो trace को readable बनाता है: + +```text +crew +└─ manager + ├─ researcher delegated + └─ writer delegated +``` + +CrewAI एक delegated execution को `delegate_work_to_coworker` **tool event** पर parent करता है, सीधे manager पर नहीं, इसलिए adapter उस link को follow करता है। इसके बिना हर agent हर दूसरे का sibling बनता है और delegation structure खो जाती है। + +## उदाहरण + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # becomes agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +Handoff trace में दिखाई देता है: `analyst` span बंद होता है, `writer` span खुलता है, और दोनों एक `crew` span के अंदर बैठते हैं। + +## अपने spans को नाम दें + +`agent_id` `Agent(role=...)` से आता है, जो इसे एक readable dashboard facet बनाता है। + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # one facet entry per run +``` + +`agent_id` एक low-cardinality column है। एक role जिसमें एक run id या timestamp है, हर query को degrade करता है जो किसी को भी चलाना है। अगर एक role एक id जैसा लगता है, तो adapter इसे refuse करता है और real value को एक payload field में डालता है। + +## Session को नियंत्रित करें + +इस क्रम में resolved, पहला match जीतता है: + +1. `instrument("crewai", session_id=...)` +2. Enclosing `failproofai_sdk.session()` scope +3. एक generated `uuid4().hex`, प्रति crew या flow + +Kickoff को wrap करें इसे per run नियंत्रित करने के लिए: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## विकल्प + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # pin every run to one session id +) +``` + +`session_id` एकमात्र विकल्प है जो यह adapter पढ़ता है। Prompts और completions हमेशा रिकॉर्ड होते हैं, payload budget के लिए truncated। + +## Human in the loop + +CrewAI के पास **दो** human-in-the-loop surfaces हैं, और दोनों same चार events के रूप में रिकॉर्ड होते हैं। + +एक flow method पर `@human_feedback` CrewAI के event bus के माध्यम से जाता है: runtime एक event emit करता है इससे पहले कि यह एक person पर block करे और जवाब के बाद एक और। + +`Task(human_input=True)` नहीं करता। यह CrewAI के अपने input provider के अंदर `input()` को call करता है और किसी भी प्रकार का event emit नहीं करता, इसलिए adapter उस provider को सीधे wrap करता है — इसके बिना पूरा human wait invisible था और active agent time के रूप में बिल किया गया था। + +किसी भी तरीके से आप पाते हैं: + +```text +human_wait prompt और इसके options +agent_pause paused-time clock शुरू करता है +agent_resume इसे बंद करता है +human_input answer, measured wait के साथ +``` + +`agent_pause` से `agent_resume` एकमात्र pair है जो paused time को feed करता है। इसके बिना, एक दस-मिनट का human wait दस मिनट की active agent time के रूप में बिल होता है। + + + CrewAI किसी भी human-feedback event पर कोई correlation id set नहीं करता, इसलिए adapter उन्हें flow और method name पर pair करता है, सबसे हाल ही में खोले गए pause पर fallback करते हुए। यह sound है क्योंकि एक console prompt blocks करता है। अगर आप एक concurrent feedback provider build करते हैं, तो दोनों events पर `request_id` set करें। + + + + क्योंकि `Task(human_input=True)` path CrewAI के input provider के चारों ओर एक wrapper है न कि एक event subscription, यह `uninstrument()` पर restored होता है और जो कुछ भी `input()` raise करता है, `KeyboardInterrupt` included, unchanged को re-raise करता है। + + +## सामान्य समस्याएं + + + + एक `role` में एक UUID, timestamp या per-run suffix है। एक stable human role use करें और run-specific id को task description में रखें। + + + + Event bus asynchronous है, और `kickoff()` last handlers run होने से पहले return करता है। इसे पहले drain करें: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + यह CrewAI की एक property है, SDK की नहीं। + + + + `agent_end` open pauses को force-close करता है लेकिन tools या models को नहीं, इसलिए एक run जो एक tool call के अंदर dies वह span open छोड़ता है। Normal teardown जो कुछ भी still open है उसे close करता है और इसे incomplete mark करता है। केवल एक `SIGKILL` इसे hanging छोड़ता है, क्योंकि कुछ भी run नहीं हो सकता। + + + + इस क्रम में check करें: `instrument()` `kickoff()` से पहले ran; `with failproofai_sdk.session():` इसके चारों ओर है; `crewai` 1.13 या newer है; `FAILPROOFAI_SDK_STRICT=1` set है, इसलिए एक degraded hook raise करता है instead of swallowed होने के। + + + +## अगला + + + + Pairs, ids, session lifecycle और delivery। + + + आपने अभी जो session capture किया है उसके माध्यम से causality को follow करें। + + + LangGraph, LlamaIndex, Pydantic AI और custom agents। + + \ No newline at end of file diff --git a/docs/hi/start/integrations/custom-agents.mdx b/docs/hi/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..52b1fcc46 --- /dev/null +++ b/docs/hi/start/integrations/custom-agents.mdx @@ -0,0 +1,737 @@ +--- +title: "कस्टम एजेंट" +sidebarTitle: "कस्टम एजेंट" +description: "एक एजेंट को इंस्ट्रूमेंट करें जिसे आपने स्वयं लिखा है, या एक फ्रेमवर्क जिसके लिए कोई एडेप्टर नहीं है।" +icon: "code" +--- + +एक एजेंट के लिए जिसे आपने स्वयं लिखा है, या एक फ्रेमवर्क जिसके लिए Failproof AI के पास कोई एडेप्टर नहीं है। इंस्ट्रूमेंट करने के लिए कुछ नहीं है: आप ईवेंट उत्सर्जित करते हैं। + +यह वही API है जिसे चारों फ्रेमवर्क एडेप्टर अंदर से कॉल करते हैं। वे इसके ऊपर अनुवाद तालिकाएं हैं। + +## इंस्टॉल करें + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # एक टूल कॉल +``` + +इसे ऊपर से नीचे पढ़ें और यह कहता है कि इसका मतलब क्या है: + +| इसे लपेटें | कहने के लिए | +| --- | --- | +| `session()` | ये ईवेंट एक ही रन से संबंधित हैं | +| `agent()` | कुछ काम कर रहा है — इसे एक नाम दें जिसे आप सूची में पहचान सकें | +| `tool_call()` | यह एक टूल है, और यहां यह क्या लौटाया है | + +और प्रत्येक वास्तव में क्या उत्सर्जित करता है: + +| स्कोप | उत्सर्जन | उद्देश्य | +| --- | --- | --- | +| `session()` | कुछ नहीं | एक सेशन id बांधता है, एक रन को समूहीकृत करता है | +| `agent()` | `agent_start`, `agent_end` | काम की एक यूनिट को ब्रैकेट करता है | +| `tool_call()` | `tool_use`, `tool_result` | एक टूल को ब्रैकेट करता है और इसे मापता है | + +अंदर सब कुछ `session_id` और `agent_id` को छोड़ सकता है। स्कोप संदर्भ चर पर पहचान बांधते हैं और हर ईवेंट कॉल इसे वापस पढ़ता है, इसलिए आप अपने फ़ंक्शन के माध्यम से कभी id का धागा नहीं डालते। + +तीनों `async with` और `with` दोनों के तहत काम करते हैं। + +एजेंट को नेस्ट करने से पेड़ बनता है। `parent_id` और गहराई को स्टैक से गणना की जाती है: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## एक स्कोप कैसे बंद होता है + +`agent()` आपके लिए अपवाद संभालता है: + +| क्या हुआ | ईवेंट | परिणाम | +| --- | --- | --- | +| कुछ नहीं उठा | `agent_end` | `success` | +| `Exception` | `error`, फिर `agent_end` | `failed` | +| `KeyboardInterrupt`, `SystemExit` | `error`, फिर `agent_end` | `failed` | +| `CancelledError`, `GeneratorExit` | केवल `agent_end` | `cancelled` | + +त्रुटि `agent_end` से पहले उत्सर्जित होती है, क्योंकि डैशबोर्ड `agent_end` पर स्पान को बंद करता है और इसके बाद कुछ भी कुछ भी में जिम्मेदार नहीं है। एक रद्दीकरण एक विफलता नहीं है, इसलिए रद्द किए गए रन त्रुटि सतह को प्रदूषित नहीं करते। अपवाद हमेशा फिर से उठाया जाता है: एक स्कोप कभी निगल नहीं लेता। + +## ईवेंट विधियां + +छह परिवारों में पंद्रह विधियां। अधिकतर जोड़े में आते हैं — आप ओपनर उत्सर्जित करते हैं, फिर क्लोजर, और 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` | +| **विफलताएं** | — | — | `error` | + + + स्कोप को प्राथमिकता दें — `agent()` और `tool_call()` — जहां वे फिट हों। वे बंद होने वाली ईवेंट की गारंटी देते हैं यहां तक कि जब बॉडी उठे। इन विधियों को सीधे तब पकड़ें जब आपका नियंत्रण प्रवाह नेस्ट न हो, जैसे कि एक हेल्पर के अंदर एक मॉडल कॉल। + + + +```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 मॉडल +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 हुक +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 मनुष्य +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 विफलताएं +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **दो मानव परिवार विपरीत दिशा में इंगित करते हैं।** + + | विधियां | अर्थ | + | --- | --- | + | `human_wait` / `human_input` | **एजेंट ने एक व्यक्ति से पूछा** — एक अनुमोदन गेट, एक स्पष्ट प्रश्न | + | `human_pause` / `human_interrupt` | **किसी व्यक्ति ने एजेंट पर कार्य किया** — एक स्टॉप बटन, एक ऑपरेटर पॉज़ | + + कोई फ्रेमवर्क दूसरी जोड़ी का संकेत नहीं देता, इसलिए यह हमेशा आपकी है कि उत्सर्जन करें। + + + + **जब मॉडल कॉल समवर्ती रूप से चलते हैं तो `request_id` पास करें।** इसके बिना, अनुरोध और प्रतिक्रियाएं प्रति एजेंट आगमन क्रम में जोड़ी होती हैं — और समवर्ती कॉल गलत जोड़ी बनाते हैं, प्रत्येक प्रतिक्रिया को गलत अनुरोध से जोड़ते हैं। + + +## उदाहरण + +OpenAI API के विरुद्ध एक टूल-कॉलिंग लूप, कोई एजेंट फ्रेमवर्क के बिना: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +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 + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="price report"): + for _ in range(4): # सीमाबद्ध; एक असीमित एजेंट लूप इसका अपना बग है + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +यह छह ईवेंट प्रकार का उत्पादन करता है जो एक एडेप्टर आपको देगा। पूर्ण चलने योग्य संस्करण, टूल परिभाषाओं के साथ, SDK रिपोजिटरी में `docs/manual/examples/` के तहत शिप होता है। + +## थ्रेड्स और async + +संदर्भ चर asyncio कार्यों में स्वचालित रूप से प्रसारित होते हैं। वे नए थ्रेड में प्रसारित नहीं होते, क्योंकि एक थ्रेड एक खाली संदर्भ के साथ शुरू होता है। + +```python +# asyncio: कुछ भी नहीं करना है +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# थ्रेड्स: कॉलेबल को लपेटें +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` उत्तर दिया जाता है, जो मूक विफलता है जिसे पहचान परत रोकने के लिए मौजूद है। + +## एडेप्टर के बिना एक फ्रेमवर्क इंस्ट्रूमेंट करें + +हर एजेंट फ्रेमवर्क आपको एक ही तीन सीम देता है। उन्हें मैप करें और आपके पास एक पूर्ण ट्रेस है — चारों शिप किए गए एडेप्टर इससे अधिक कुछ नहीं करते। + +| सीम | आप क्या लिखते हैं | क्या उतरता है | +| --- | --- | --- | +| रन | `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: + call.output = original(**args) + ``` + + + ```python + failproofai_sdk.event.model_request(model=model, messages=messages) + reply = provider.complete(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **एक नोड, स्टेप या मिडलवेयर सीमा देखने योग्य है?** इसे एक हुक जोड़ी में लपेटें — `hook_triggered` / `hook_completed` — एक नेस्ट किए गए `agent()` में नहीं। `agent_id` कम-कार्डिनलिटी पहलू है, और प्रति नोड एक प्रविष्टि इसे डुबो देती है। हुक स्पान एक ही तरह से प्रस्तुत होते हैं और आपको प्रति-नोड विलंबता देते हैं। + + + + **मैनुअल और स्वचालित मिश्रित होते हैं।** एक एडेप्टर एक हाथ से लिखे गए स्कोप के अंदर चल रहा है उस सेशन से जुड़ता है और उस एजेंट का माता-पिता बनता है, इसलिए आपको एक पेड़ मिलता है दो के बजाय — उपयोगी जब आप एक फ्रेमवर्क को स्वयं एक समर्थित के साथ इंस्ट्रूमेंट करते हैं। + + + + दो कारण, और ऊपर दिए गए तीन सीम दोनों का उत्तर हैं: + + - `autogen-core` सितंबर 2025 के बाद से अरक्षित है। + - AG2 अन्य फ्रेमवर्क के हुक के समकक्ष कोई प्रक्रिया-व्यापी पंजीकरण बिंदु नहीं उजागर करता है, इसलिए इसे इंस्ट्रूमेंट करने का अर्थ हर निर्माण साइट पर हर एजेंट को लपेटना है। + + सीम को हाथ से मैप करना एक ही ईवेंट को एक ही निष्ठा पर रिकॉर्ड करता है जो एक शिप किया गया एडेप्टर होगा। + + +## गहराई में जाना + +रिकॉर्डिंग वास्तव में कैसे काम करती है। शुरुआत करने के लिए इसमें से कोई भी आवश्यक नहीं है। + + + + + +हर रिकॉर्डिंग का एक ही आकार है: एक स्पान खुलता है, काम इसके अंदर नेस्ट होता है, और हर ओपनिंग ईवेंट को एक क्लोजिंग ईवेंट मिलता है। + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + C --> E(["agent_end"]) +``` + +**जोड़ी** यूनिट है। प्रत्येक क्लोजिंग ईवेंट एक अवधि ले जाता है जो SDK इसके ओपनिंग वाले से मापता है। + +नीचे एक वास्तविक रन प्रति फ्रेमवर्क है — SDK के साथ शिप किए गए उदाहरणों से कैप्चर किया गया, मॉडल नाम सामान्यीकृत। ध्यान दें कि एक एकल कॉल से कितना वापस आता है। + + + + ```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 आउट-टोक + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 आउट-टोक + 13 +5.720s hook_completed agent + 14 +5.721s agent_end LangGraph · success + ``` + + नोड्स हुक जोड़ी बन जाते हैं, इसलिए आप प्रति-नोड विलंबता प्राप्त करते हैं बिना उन्हें एजेंट सूची में भीड़ किए। + + + + ```text 10 ईवेंट + 1 +0.000s agent_start 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 आउट-टोक + 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 आउट-टोक + 9 +5.727s agent_end analyst · success + 10 +5.739s agent_end crew · success + ``` + + प्रत्येक एजेंट का `role` इसका स्पान नाम बनता है, इसलिए विलंबता और टोकन खर्च प्रति भूमिका में विभाजित होते हैं। + + + + ```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 आउट-टोक + 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 ईवेंट + 1 +0.000s agent_start agent + 2 +0.001s model_request gpt-4o-mini + 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 आउट-टोक + 8 +8.119s agent_end agent · success + ``` + + कोई हुक जोड़ी नहीं: Pydantic AI के पास कोई नोड या स्टेप सीमा नहीं है कि ब्रैकेट करने के लिए। + + + + ```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 आउट-टोक + 6 +0.000s agent_end main · success + ``` + + आप स्वयं इन्हें उत्सर्जित करते हैं। एक ही ईवेंट प्रकार, एक ही निष्ठा — इसका मतलब कॉल साइट है। + + + + + + + +**कोई सेशन-अंत ईवेंट नहीं है।** एक सेशन कुछ ऐसा नहीं है जिसे आप बंद करते हैं — यह एक `session_id` साझा करने वाली ईवेंट का एक समूह है। + +स्थिति ट्रेस के आकार से प्राप्त की जाती है: + +| स्थिति | कब | +| --- | --- | +| `ongoing` | कम से कम एक स्पान अभी भी खुला है | +| `paused` | एक `agent_pause` का कोई मिलान `agent_resume` नहीं है | +| `error` | कुछ नहीं खुला है, और कम से कम एक ईवेंट विफल रहा | +| `done` | कुछ नहीं खुला है, और कुछ भी विफल नहीं रहा | + +तो एक सेशन तब समाप्त होता है जब हर जोड़ी बंद हो जाती है। एडेप्टर आपके लिए `agent_end` उत्सर्जित करते हैं, और टियरडाउन पर वे कुछ भी अभी भी खुला बंद करते हैं और इसे अधूरा चिह्नित करते हैं — एक क्रैश किया गया रन `done` बैठता है एक दृश्यमान अंतराल के साथ बजाय हैंगिंग के। + + + यह है कि एक सेशन दो कॉल पर फैल सकता है। एक LangGraph `interrupt()` रन को रोकता है, रूट स्पान जानबूझकर खुला रहता है, और पुनरारंभ करने वाली कॉल इसे बंद करती है। दोनों कॉल एक सेशन हैं। + + + + + + +`session_id` और `agent_id` हर ईवेंट विधि पर वैकल्पिक हैं। छोड़ा गया, वे एनक्लोजिंग स्कोप से समाधान करते हैं: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") +``` + +उन्हें स्पष्ट रूप से पास करने से अभी भी काम करता है और प्राथमिकता लेता है। कुछ भी बांधा नहीं और कुछ भी पारित नहीं, कॉल एक `TypeError` उठाता है जो सुधार का नाम देता है बजाय कोई सेशन के साथ एक ईवेंट उत्सर्जित करने के, जिसे ingest `200` का उत्तर देते हुए छोड़ देगा। + +स्कोप संदर्भ चर पर पहचान बांधते हैं। वे 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` कैसे समाधान करते हैं + +पहला मैच जीता: + +1. एक स्पष्ट `session_id` विकल्प +2. प्रति-कॉल मेटाडेटा +3. एनक्लोजिंग `session()` स्कोप +4. फ्रेमवर्क मेटाडेटा +5. फ्रेमवर्क का अपना रन id + +इसे कभी आविष्कार नहीं किया जाता है जबकि इनमें से एक मौजूद है — एक संश्लेषित id एक रन को कई सेशन में विभाजित करेगा। + +#### `agent_id` को कम कार्डिनलिटी रखें + +यह हर डैशबोर्ड सतह पर प्राथमिक पहलू है, और एक `LowCardinality(String)` कॉलम। एक प्रति-रन मान कॉलम को खराब करता है और फ़िल्टर ड्रॉपडाउन को प्रति रन एक प्रविष्टि से भरता है। + +एडेप्टर उस कॉलम की रक्षा करते हैं: + +| फ्रेमवर्क सौंपता है | रिकॉर्ड किया गया | क्यों | +| --- | --- | --- | +| `3f9a1c2b-…` (एक UUID) | `main` | कुछ पठनीय नहीं रखने के लिए | +| एक लंबी नंगी हेक्स स्ट्रिंग | `main` | वही | +| `agent-3f9a1c2b-…` | `agent` | प्रति-रन id छीन लिया गया, पठनीय भाग रखा गया | +| `agent-v2` | `agent-v2` | छोटे सेगमेंट अकेले छोड़ दिए जाते हैं | +| `step-3` | `step-3` | वही | + +असली id `fw_agent_id` / `fw_run_id` पर रखा जाता है, जहां यह एक पहलू बने बिना पूछताछ योग्य रहता है। + + + **यह गार्ड केवल *फ्रेमवर्क* द्वारा चुने गए लेबल को छूता है।** एक `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` | +| विफलताएं | `error` | + +कौन सा फ्रेमवर्क क्या रिकॉर्ड करता है, ऊपर से रन से मापा गया: + +| ईवेंट | LangGraph | CrewAI | LlamaIndex | Pydantic AI | कस्टम | +| --- | :--: | :--: | :--: | :--: | :--: | +| एजेंट शुरु और अंत | हां | हां | हां | हां | आप | +| मॉडल अनुरोध और प्रतिक्रिया | हां | हां | हां | हां | आप | +| टूल उपयोग और परिणाम | हां | हां | हां | हां | आप | +| हुक ट्रिगर और पूर्ण | नोड | कार्य | स्टेप | — | आप | +| त्रुटि | हां | हां | हां | हां | स्वचालित | +| मानव प्रतीक्षा और इनपुट | हां | हां | हां | — | आप | +| एजेंट पॉज़ और पुनरारंभ | हां | हां | हां | — | आप | + +एक डैश का मतलब फ्रेमवर्क के पास कोई ऐसी अवधारणा नहीं है। `human_pause` और `human_interrupt` एक *व्यक्ति* द्वारा एजेंट पर कार्य करने का वर्णन करते हैं, जिसका कोई फ्रेमवर्क संकेत नहीं देता — स्वयं उत्सर्जन करें। + + + + + +एक ईवेंट कभी अकेले नहीं आता। एक स्पान खुलता है, एक बंद होता है, और क्लोजिंग ईवेंट एक अवधि ले जाता है जो 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` | उत्तर, और व्यक्ति को कितना समय लगा | + + + कोई क्लोजिंग के साथ एक ओपनिंग ईवेंट कभी खत्म नहीं होने वाला एक स्पान है। सेशन हमेशा चल रहे के रूप में प्रस्तुत होता है, हमेशा के लिए, और इसकी सक्रिय अवधि बढ़ती रहती है। यह वह विफलता मोड है जिसे हाथ से इंस्ट्रूमेंट करते समय देखने के लिए है। + + +#### सहसंबंध नियम + +- मिलान पूर्णता ईवेंट के लिए एक ही `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` इंस्टॉल करने से सब कुछ इंस्टॉल होता है, सभी चार एडेप्टर शामिल हैं। अतिरिक्त एडेप्टर नहीं, **फ्रेमवर्क** खींचते हैं। + +```python +import failproofai_sdk # मानक पुस्तकालय के बाहर कुछ भी लोड नहीं करता है +failproofai_sdk.instrument() # केवल एडेप्टर आयात करता है जिसकी आपको वास्तव में आवश्यकता है +``` + +`import failproofai_sdk` अनुबंध शून्य-निर्भरता है, एक परीक्षण द्वारा प्रवर्तित जो निर्मित व्हील को `--no-deps` के साथ इंस्टॉल करता है और एक और जो साबित करता है कि कोई फ्रेमवर्क `sys.modules` तक नहीं पहुंचता है। + + + कोई `failproofai_sdk.crewai` विशेषता नहीं है। एडेप्टर जानबूझकर शीर्ष-स्तरीय पैकेज पर प्रदर्शित नहीं होते हैं: एक को छूना एक विशेषता पहुंच के दुष्प्रभाव के रूप में फ्रेमवर्क आयात करेगा, शून्य-निर्भरता प्रतिश्रुति को तोड़ते हुए। `instrument()` का उपयोग करें। + + +```python +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` को पढ़ता है, न कि इंस्टॉल किए गए पैकेज सूची को, इसलिए एक फ्रेमवर्क जिसे आपने इंस्टॉल किया है लेकिन कभी आयात नहीं किया वह इंस्ट्रूमेंट नहीं है और आपकी ओर से कभी आयात नहीं किया जाता है। यह देखने के लिए कि क्या वायर्ड है: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +active() # ('langchain',) +``` + + + **बिना CrewAI वाली मशीन पर `instrument("crewai")` नहीं उठाता।** यह एक चेतावनी लॉग करता है और `()` लौटाता है, इसलिए एक लापता फ्रेमवर्क कभी एक प्रक्रिया को नीचे नहीं लाता है जो अन्य को भी इंस्ट्रूमेंट करता है। + + चेतावनी अंतर्निहित `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` सेट करें। वह झंडा **एक बार पढ़ा जाता है और कैश किया जाता है**, इसलिए मध्य-रन सेट करने के बजाय अपनी प्रक्रिया शुरू होने से पहले निर्यात करें। + + + + **`instrument()` *आपके फ्रेमवर्क आयात के बाद* आना चाहिए।** ऑटो-डिटेक्शन `sys.modules` को पढ़ता है, इसलिए आयात के ऊपर एक नंगा कॉल कुछ भी नहीं खोजता है, कुछ भी इंस्टॉल नहीं करता है, और `()` लौटाता है। + + + +```python गलत +import failproofai_sdk +failproofai_sdk.instrument() # sys.modules के पास अभी तक कोई langchain नहीं है -> () + +import langchain # बहुत देर हो गई, कुछ भी वायर्ड नहीं है +``` + +```python सही +import langchain # पहले फ्रेमवर्क आयात करें +import failproofai_sdk + +failproofai_sdk.instrument() # इसे खोजता है -> ('langchain',) +``` + +```python सही, क्रम-प्रूफ +import failproofai_sdk + +# इसका नाम देने से एडेप्टर अनुरोध पर आयात होता है, इसलिए यह कहीं से भी काम करता है। +failproofai_sdk.instrument("langchain") +``` + + +यह गलत प्राप्त करें और प्रक्रिया SDK आयातित, एडेप्टर स्पष्ट रूप से इंस्टॉल, और **कोई भी ईवेंट उत्सर्जित नहीं** के साथ चलता है। यह एक चेतावनी लॉग करता है जो बिल्कुल ऐसा कहता है — इसलिए एक रन रिकॉर्ड नहीं करते समय पहले अपने लॉग जांचें। + + + + + +```mermaid +flowchart LR + A["आपका एजेंट"] --> B["एडेप्टर"] + B --> C["राइटर
इन-मेमोरी कतार"] + C -->|"हर 0.5s"| D["स्पूल
डिस्क पर JSONL"] + D --> E["Failproof डेमन"] + E -->|"HTTPS"| F["क्लाउड"] +``` + +| चरण | काम | में चलता है | +| --- | --- | --- | +| एडेप्टर | एक फ्रेमवर्क कॉलबैक को 15 ईवेंट प्रकारों में से एक में अनुवाद करता है | आपकी प्रक्रिया | +| राइटर | कतार, बैच, JSONL परमाणु रूप से लिखता है | आपकी प्रक्रिया, पृष्ठभूमि थ्रेड | +| स्पूल | टिकाऊ हस्तांतरण, आपकी प्रक्रिया से बचता है | स्थानीय डिस्क | +| डेमन | स्पूल देखता है, बैच भेजता है, जो भेजा गया है उसे हटाता है | आपकी मशीन | +| Ingest | एक पंक्ति id और dedup कुंजी असाइन करता है, पूछताछ योग्य कॉलम को बढ़ावा देता है | क्लाउड | + +स्पूल वह है जो इसे सुरक्षित बनाता है: आपका एजेंट कभी नेटवर्क पर ब्लॉक नहीं होता है, और एक क्लाउड आउटेज एक बढ़ती डायरेक्टरी का मतलब है खोई हुई ईवेंट के बजाय। + +प्रत्येक फ्लश एक बैच फाइल लिखता है, पहले `.tmp`, फिर `fsync`, फिर एक परमाणु नाम बदलना: + +```text +~/.failproofai/custom-agents/events/ + event-2026-08-20T10-15-00-123Z-48213-0.jsonl +``` + +डेमन केवल `.jsonl` उठाता है, इसलिए यह कभी आधी-लिखी गई फाइल नहीं पढ़ सकता। स्टेम एक टाइमस्टैम्प, प्रक्रिया id और अनुक्रम संख्या ले जाता है, इसलिए दो प्रक्रियाएं एक ही मिलीसेकंड में फ्लश करना संघर्ष नहीं कर सकती हैं। कतार 10,000 ईवेंट पर capped है; इसके बाद यह सबसे पुरानी को बंद करता है और लॉग करता है। + + + **`collector.redact` आपकी SDK ईवेंट पर लागू नहीं होता है।** यह कभी उन्हें नहीं देखता है। + + +डेमन आपकी बैच **भेजता है**। वह उन्हें खोलता या फिर से लिखता नहीं है। + +| ईवेंट | द्वारा लिखा गया | `collector.redact` से संरक्षित? | +| --- | --- | --- | +| CLI सेशन प्रतिलेख | डेमन | हां | +| हुक गतिविधि | डेमन | हां | +| **SDK जो कुछ भी उत्सर्जित करता है** | **आपकी प्रक्रिया** | **नहीं** | + +संपादन जहां डेमन अपनी स्वयं की ईवेंट **लिखता है** — जहां बैच **भेजे जाते हैं** नहीं। इसलिए एक प्रॉम्प्ट या एक टूल तर्क जिसमें एक API कुंजी होती है अभी भी आगमन पर रखती है। + +यह जानबूझकर है। ये आपके स्वयं के इंस्ट्रूमेंटेशन कॉल हैं, और पारगमन में उन्हें फिर से लिखने का अर्थ होगा कि आप जो ईवेंट प्राप्त करते हैं वे ईवेंट नहीं हैं जो आपने उत्सर्जित किए हैं। + + + **आप स्रोत पर पेलोड को नियंत्रित करते हैं, दो जगहों में:** + + - एडेप्टर पर सामग्री कैप्चर बंद करें। **विकल्प नाम भिन्न होता है, और एक एडेप्टर के पास कोई नहीं है** — यह एक एकल सार्वभौमिक स्विच नहीं है: + - LangChain / LangGraph, Pydantic AI — `capture_content=False` + - LlamaIndex — `capture_messages=False` + - CrewAI — **कोई सामग्री स्विच नहीं**; `session_id` एकमात्र विकल्प है यह पढ़ता है, इसलिए प्रॉम्प्ट और पूर्ति हमेशा रिकॉर्ड किए जाते हैं। + + `instrument()` एडेप्टर द्वारा पढ़ी जाने वाली विकल्प को छोड़ता है, इसलिए गलत नाम पास करने से कुछ नहीं उठाया जाता है और कुछ भी नहीं बदलता है। + - पहली जगह में रहस्य को `input=` को हाथ न सौंपें। + + `collector.redact` किसी के लिए विकल्प नहीं है। + + + + **एक खाली स्पूल डायरेक्टरी स्वस्थ स्थिति है।** इसे डिलीवरी की जांच करने के लिए न बनाएं। + + +डेमन इसे भेजने के मिलीसेकंड के भीतर प्रत्येक बैच को हटा देता है, इसलिए एक `ls` रेस एकत्रकर्ता और आपने जो उत्सर्जित किया उसका एक अंश दिखाता है — एक SDK से अप्रभेद्य जो कुछ भी रिकॉर्ड नहीं करता है। + +ईवेंट वास्तव में उतरे हैं यह पुष्टि करने के लिए, डैशबोर्ड की जांच करें। स्पूल को भरते हुए देखने के लिए, पहले डेमन को रोकें। + + + + + +हर कॉलबैक एक रैपर के अंदर चलता है जिसका एकमात्र काम पुनः उठाना है, इसलिए आपकी कॉल ठीक एक `try` में बैठता है और सब कुछ SDK करता है इसके बाहर होता है। + +| क्या होता है | परिणाम | +| --- | --- | +| एक हुक उठाता है | अपने ट्रेसबैक के साथ एक बार लॉग किया गया। आपकी कॉल अप्रभावित है | +| एक ही हुक तीन बार उठाता है | वह एक हुक बाकी के लिए अक्षम हो जाता है, एक त्रुटि पंक्ति के साथ | +| `FAILPROOFAI_SDK_STRICT=1` सेट है | अपवाद के बजाय फिर से उठाया जाता है | +| एक फ्रेमवर्क संस्करण परीक्षित सीमा के बाहर है | एक बार चेतावनी, किसी भी तरह इंस्ट्रूमेंट | +| एक एकल क्षमता लापता है | वह एक हुक अक्षम है, संपूर्ण एडेप्टर कभी नहीं | + +डिफ़ॉल्ट उत्पादन में सही है और डीबग करते समय गलत है, क्योंकि यह केवल यह साबित कर सकता है कि यह क्रैश नहीं हुआ। डीबग करते समय इसे जोर देने के लिए `FAILPROOFAI_SDK_STRICT=1` सेट करें। + + + + + +## सामान्य समस्याएं + + + + एक ओपनिंग ईवेंट का कोई क्लोजिंग नहीं है: एक `model_request` के बिना `model_response`, या एक `tool_use` के बिना `tool_result`। स्कोप का उपयोग करें, जो शरीर उठाए जाने पर भी जोड़ी की गारंटी देते हैं। यदि आप ईवेंट विधियों को सीधे कॉल करते हैं, तो `try` और `finally` का उपयोग करें। + + + + यह मिलान ओपनिंग ईवेंट से मापा जाता है, इसलिए यह `tool_result`, `hook_completed`, `agent_resume`, और `human_input` पर अस्वीकार किया जाता है। यह `model_response` पर स्वीकार किया जाता है, क्योंकि केवल आप असली प्रदाता विलंबता जानते हैं, और यह एक पूर्णांक होना चाहिए। + + + + थ्रेड ने कभी संदर्भ को विरासत में नहीं दिया। कॉलेबल को `failproofai_sdk.propagate()` में लपेटें। [थ्रेड्स और async](#threads-and-async) देखें। + + + + अतिरिक्त फील्ड आखिरी में मर्ज होते हैं, इसलिए `model` या `outcome` जैसे वास्तविक फील्ड का नाम इसे अधिलेखित करेगा और एक संग्रहीत कॉलम बदल देगा। अपना नामस्थान; एडेप्टर एक `fw_` उपसर्ग का उपयोग करते हैं। + + + + `agent_id` कम-कार्डिनलिटी पहलू है और आपने एक रन id में डाल दिया। एक भूमिका या नोड नाम का उपयोग करें और असली id को एक पेलोड फील्ड में डालें। + + + +## अगला + + + + जोड़ी, id, सेशन जीवनचक्र, और डिलीवरी। + + + आपके द्वारा अभी कैप्चर किए गए सेशन के माध्यम से कारणात्मकता का पालन करें। + + + LangGraph, CrewAI, LlamaIndex, और Pydantic AI। + + \ No newline at end of file diff --git a/docs/hi/start/integrations/langchain.mdx b/docs/hi/start/integrations/langchain.mdx new file mode 100644 index 000000000..8a7b09fc9 --- /dev/null +++ b/docs/hi/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain और LangGraph" +sidebarTitle: "LangChain और LangGraph" +description: "ग्राफ, नोड्स, टूल्स, रिट्रीवर्स और मॉडल कॉल को एक कॉल से इंस्ट्रूमेंट करें।" +icon: "/images/frameworks/langchain.svg" +--- + +एक ऐडेप्टर दोनों को सर्व करता है। LangGraph `langchain-core` के कॉलबैक मैनेजर पर चलता है, इसलिए एक को इंस्ट्रूमेंट करने से दूसरा भी इंस्ट्रूमेंट हो जाता है। + +## इंस्टॉल करें + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +LangGraph के बिना LangChain के लिए, `failproofai-sdk[langchain]` का उपयोग करें। + +समर्थित: `langchain-core` 1.4.7 से 2.0, `langgraph` 1.2 से 2.0। इस रेंज के बाहर ऐडेप्टर अभी भी इंस्टॉल होता है और एक बार चेतावनी देता है। + +## इंस्ट्रूमेंट करें + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` `langchain_core.tracers.context.register_configure_hook` के माध्यम से एक ट्रेसर पंजीकृत करता है। LangChain इसे हर कॉलबैक मैनेजर में इंजेक्ट करता है जो वह बनाता है, इसलिए ग्राफ, टूल्स और मॉडल्स कॉल साइट को बदले बिना कैप्चर किए जाते हैं — जिनमें वे भी शामिल हैं जो आपके द्वारा न लिखे गए लाइब्रेरीज़ के अंदर हैं। + +## क्या रिकॉर्ड होता है + +| LangChain या LangGraph | Failproof इवेंट | +| --- | --- | +| रूट रन | `agent_start`, `agent_end` | +| LangGraph नोड | `hook_triggered`, `hook_completed` | +| कम्पाइल्ड सबग्राफ | नेस्टेड `agent_start`, `agent_end` | +| टूल रन | `tool_use`, `tool_result` | +| रिट्रीवर रन | `tool_use`, `tool_result`, आउटपुट सारांशित | +| चैट मॉडल या LLM रन | `model_request`, `model_response`, टोकन उपयोग के साथ | +| स्ट्रीम किए गए टोकन | रिस्पांस में चंक काउंट और टाइम टू फर्स्ट टोकन के रूप में फोल्ड किए गए। टोकन काउंट को `ChatOpenAI(stream_usage=True)` की आवश्यकता है — नीचे देखें | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, `Interrupt.id` पर सहसंबद्ध — जिसमें वह भी शामिल है जब रिज्यूम एक अलग प्रक्रिया में समान चेकपॉइंटर के विरुद्ध होता है | +| अनहैंडल्ड एक्सेप्शन | `error`, फिर `agent_end` आउटकम `failed` के साथ | + +**एक नोड हुक बन जाता है, नेस्टेड एजेंट नहीं।** `agent_id` हर डैशबोर्ड सर्फेस पर प्राथमिक पहलू है — `retrieve`, `grade_documents` और `should_continue` को एजेंट्स में प्रमोट करना इसे डूब देगा, और सेशन को उस नोड के नाम पर लेबल करेगा जो पहले चलने के लिए हुआ। + +हुक स्पैन्स एक ही तरह से रेंडर होते हैं और अभी भी आपको प्रति-नोड लेटेंसी व्यू देते हैं। + + + **अपने नोड्स का नाम जो चाहें रखें।** एक नोड का रन इसके *आकार* से पहचाना जाता है — एक नॉन-लीफ रन जो LangGraph का खुद का स्टेप टैग ले जाता है — कभी इसके नाम से नहीं। + + +| आप लिखते हैं | क्या रिकॉर्ड होता है | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | टूल | +| `add_node("ChatOpenAI", ...)` | मॉडल कॉल | + +किसी नोड का नाम उस चीज़ के नाम पर रखना जो वह चलाता है, उस चीज़ के इवेंट्स को गायब करने के लिए करता था। अब नहीं करता। + +### स्ट्रीमिंग + +`.stream()` और `.astream()` कोई प्रति-टोकन इवेंट्स नहीं देते हैं। वे क्लोजिंग `model_response` में फोल्ड होते हैं: + +| फील्ड | ले जाता है | +| --- | --- | +| `fw_chunks` | कितने चंक आए | +| `fw_ttft_ms` | पहले टोकन का समय | + +### स्ट्रीम किए गए रिस्पांस पर टोकन काउंट्स + +अलग मामला, और मिस करना आसान है: OpenAI स्ट्रीम किए गए रिस्पांस पर उपयोग तभी भेजता है **जब पूछा जाता है**। + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # इसके बिना, कोई टोकन नहीं +``` + +ऐडेप्टर वह रिकॉर्ड करता है जो फ्रेमवर्क इसे देता है। उस फ्लैग के बिना रिकॉर्ड करने के लिए कुछ नहीं है, और `model_response` टोकन काउंट्स के बिना आता है। + +## उदाहरण + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## अपने स्पैन्स का नाम दें + +डिफ़ॉल्ट रूप से रूट स्पैन ग्राफ का अपना नाम लेता है। इसे आपके चुने हुए लेबल के लिए रैप करें: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +मल्टी-एजेंट सेटअप के लिए, स्कोप्स को नेस्ट करें। प्रत्येक वर्कर एक चाइल्ड स्पैन बन जाता है जो `parent_id` ले जाता है: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +`agent_id` को कम कार्डिनैलिटी रखें। एक भूमिका या नोड नाम का उपयोग करें, कभी UUID या प्रति-रन स्ट्रिंग नहीं। + +## सेशन को नियंत्रित करें + +सेशन आईडी इस क्रम में रिज़ॉल्व होता है, पहला मैच जीतता है: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. एनक्लोजिंग `failproofai_sdk.session()` स्कोप +4. `metadata["session_id"]`, `metadata["conversation_id"]`, या `metadata["thread_id"]` +5. रूट रन आईडी + +यह कभी स्क्रैच से जेनरेट नहीं होता है, क्योंकि एक सिंथेसाइज़्ड आईडी एक रन को कई सेशन्स में विभाजित करता है। + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## विकल्प + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # हर रन को एक सेशन आईडी पर पिन करें + include_chains=set(), # इंटरमीडिएट चेन्स को हुक पेयर्स के रूप में अनुमति सूची में डालें + capture_content=True, # False प्रॉम्प्ट्स और कम्पलीशन्स को पेलोड्स से ड्रॉप करता है + graph_callbacks=True, # फर्स्ट-क्लास इंटरप्ट और रिज्यूम, langgraph 1.2+ की आवश्यकता है +) +``` + +नियंत्रित डेटा के लिए `capture_content=False` सेट करें। संरचना, टाइमिंग्स, टोकन काउंट्स, टूल नाम्स, और आउटकम्स अभी भी रिकॉर्ड किए जाते हैं; मैसेज बॉडीज़ नहीं। + +`include_chains` **नेस्टेड** रन्स के लिए ही लागू होता है। एक रनेबल जो आप टॉप लेवल पर इनवोक करते हैं वह सेशन का रूट है, इसलिए यह एजेंट स्पैन बन जाता है न कि हुक पेयर, और इसे यहाँ नाम देने का कोई प्रभाव नहीं है। + +## लूप में मनुष्य + +`interrupt()` चार इवेंट्स प्रोड्यूस करता है, और न ही कोई पेयर रिडंडेंट है: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +`human_wait` से `human_input` प्रॉम्प्ट और उत्तर दोनों ले जाता है (`capture_content=False` के तहत ड्रॉप किए जाते हैं, साथ ही रिट्रीवल डॉक्यूमेंट सोर्सेस के साथ — डॉक्यूमेंट काउंट बचा रहता है)। `agent_pause` से `agent_resume` एकमात्र पेयर है जो पॉज़्ड टाइम फीड करता है, इसलिए इसके बिना दस मिनट की मानवीय प्रतीक्षा सक्रिय एजेंट समय के रूप में बिल होती है। रूट स्पैन अंतराल भर में खुला रहता है, दोनों कॉल्स को एक सेशन में रखता है। + +## सामान्य समस्याएं + + + + `create_react_agent` एक्सेप्शन को प्रोपेगेट करता है। मॉडल को विफलता को देखने और जारी रखने देने के लिए, टूल नोड को स्पष्ट रूप से बनाएं: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + विफलता दोनों तरीकों से `tool_result` के रूप में रिकॉर्ड की जाती है जो एक त्रुटि ले जाता है। यह केवल निर्णय लेता है कि क्या रन इससे बचता है। + + + + किसी भी ग्राफ के बाहर एक डायरेक्ट `llm.invoke()` का कोई पैरेंट रन नहीं है, इसलिए यह एक रूट स्पैन खोलता है और इसके अंदर इसके मॉडल पेयर को एमिट करता है। डैशबोर्ड पत्तियों को एक खुले एजेंट को पैरेंट करता है, इसलिए स्पैन जानबूझकर है। इसका नाम दें: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + आपने `config={"callbacks": [...]}` में एक Failproof हैंडलर पास किया साथ ही `instrument()` को कॉल किया। इसे हटाएं। कॉन्फ़िगर हुक पहले से ही प्रक्रिया में हर कॉलबैक मैनेजर को कवर करता है। + + + + वे नहीं देते हैं। LangGraph `GraphInterrupt` को एक वास्तविक एक्सेप्शन के समान पथ के माध्यम से उठाता है, इसलिए हर पॉज़ ट्रेसर तक एक एरर कॉलबैक के रूप में पहुंचता है। कोई भी `GraphBubbleUp` सबक्लास नियंत्रण प्रवाह के बजाय माना जाता है, इसलिए एक अनुमोदन लाल त्रुटि को पेंट नहीं करता है। + + + + इस क्रम में जाँचें: `instrument()` ग्राफ के निष्पादन से पहले चला; `failproofai_sdk.session():` के साथ कॉल के चारों ओर एक है; `FAILPROOFAI_SDK_STRICT=1` सेट है, इसलिए एक डिग्रेडेड हुक इसके बजाय उठाया जाता है। + + + +## अगला + + + + पेयर्स, आईडी, सेशन लाइफसाइकल, और डिलीवरी। + + + उस सेशन के माध्यम से कार्यकारणता का अनुसरण करें जो आपने अभी कैप्चर किया है। + + + CrewAI, LlamaIndex, Pydantic AI, और कस्टम एजेंट्स। + + \ No newline at end of file diff --git a/docs/hi/start/integrations/llamaindex.mdx b/docs/hi/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..aa6233ce8 --- /dev/null +++ b/docs/hi/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "वर्कफ़्लो, स्टेप्स, फ़ंक्शन एजेंट और रिट्रीवर्स को इंस्ट्रूमेंट करें।" +icon: "/images/frameworks/llamaindex.svg" +--- + +## इंस्टॉल करें + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +समर्थित: `llama-index-core` 0.14.23 से 0.15। 0.14.23 वह रिलीज़ है जहां वर्कफ़्लो स्ट्रीम टाइप्ड एजेंट इवेंट्स ले जाना शुरू करता है जिन्हें यह एडाप्टर पढ़ता है। इससे नीचे, मॉडल नाम और एजेंट स्ट्रक्चर दोनों गायब हो जाते हैं। + +## इंस्ट्रूमेंट करें + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +LlamaIndex का एजेंट API अतुल्यकालिक है। हर स्कोप `async with` के साथ-साथ `with` के तहत काम करता है और समान इवेंट्स तैयार करता है। + +`instrument()` LlamaIndex के ग्लोबल डिस्पैचर को एक इवेंट हैंडलर और एक स्पैन हैंडलर से जोड़ता है। साथ में वे एजेंट लूप को दृश्यमान बनाते हैं, केवल इसके मॉडल कॉल्स नहीं। + + + आपके LLM पर एक अतिरिक्त आर्गुमेंट के बिना, आपके ट्रेस में हर टोकन काउंट null है। नीचे [Token counts](#token-counts) देखें। + + +## टोकन काउंट्स + +`FunctionAgent` को `astream_chat` कॉल करता है, और `llama-index-llms-openai` स्ट्रीम करते समय `stream_options={"include_usage": True}` नहीं भेजता है। प्रोवाइडर इसलिए कभी भी उपयोग चंक नहीं भेजता है, और किसी भी इंस्ट्रूमेंटेशन के लिए पढ़ने के लिए कुछ नहीं है। + +यह अपस्ट्रीम LlamaIndex व्यवहार है। अपने LLM पर ऑप्ट इन करें: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +समान रन और मॉडल पर मापा गया: + +| | इनपुट टोकन्स | आउटपुट टोकन्स | +| --- | --- | --- | +| बिना | `null` | `null` | +| साथ | 148 | 17 | + +गैर-स्ट्रीमिंग कॉल्स (`llm.chat`, `llm.achat`) बिना कॉन्फ़िगरेशन के उपयोग की रिपोर्ट करते हैं। केवल स्ट्रीमिंग पाथ, जो डिफ़ॉल्ट एजेंट पाथ है, को इसकी आवश्यकता है। + +## क्या रिकॉर्ड होता है + +| LlamaIndex | Failproof इवेंट | +| --- | --- | +| `Workflow.run` रूट स्पैन | Session, `agent_start`, `agent_end` | +| नेस्टेड `Workflow.run` स्पैन | नेस्टेड `agent_start`, `agent_end` | +| वर्कफ़्लो स्टेप स्पैन | `hook_triggered`, `hook_completed` | +| LLM चैट शुरुआत और अंत | `model_request`, `model_response` | +| `FunctionTool.call` स्पैन | `tool_use`, `tool_result` | +| रिट्रीवल शुरुआत और अंत | `tool_use`, `tool_result`, आउटपुट सारांशित | +| एम्बेडिंग्स | कुछ नहीं, जब तक `embeddings=True` | +| एक टूल एक व्यक्ति की प्रतीक्षा कर रहा हो | `human_wait`, `agent_pause`, फिर `agent_resume`, `human_input` | +| `AgentWorkflow` हैंडऑफ | एक नेस्टेड `agent_start`, `agent_end` प्रति एजेंट, वर्कफ़्लो के लिए माता-पिता | +| अपवाद | `error`, फिर `agent_end` परिणाम `failed` के साथ, और `agent_end.summary` इसे नामित करता है | +| `handler.cancel_run()` | `agent_end` परिणाम `cancelled` के साथ और कोई `error` नहीं — एक स्टॉप बटन एक विफलता नहीं है | + +`agent_id` जब आप एक सेट करते हैं तो `FunctionAgent.name` है, अन्यथा वर्कफ़्लो क्लास नाम है। एक `AgentWorkflow` के तहत, प्रत्येक एजेंट जो एक मोड़ लेता है वर्कफ़्लो के तहत अपना नेस्टेड स्पैन मिलता है, इसलिए एक हैंडऑफ दो एजेंट के रूप में पढ़ता है एक के बजाय। + +रिट्रीवल आउटपुट डंप करने के बजाय सारांशित है। एक रिट्रीवर दस्तावेज़ लौटाता है, और उन्हें पेलोड में संग्रहीत करने से आपका कॉर्पस प्रति क्वेरी इवेंट्स स्टोर में एक बार जाएगा। काउंट, स्कोर रेंज, और ट्रंकेटेड स्निपेट्स बजाय संरक्षित हैं। + +## उदाहरण + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +एजेंट लूप हुक जोड़ी के रूप में ट्रेस में दिखाई देता है: `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool`, और `aggregate_tool_results`। वे फ्रेमवर्क का अपना लूप हैं, इसलिए वे एजेंट के बजाय हुक हैं, जो `agent_id` को सार्थक रखता है। + +## अपने स्पैन्स को नाम दें + +`agent_id` जब आप एक सेट करते हैं तो `FunctionAgent.name` है, अन्यथा वर्कफ़्लो क्लास नाम है। + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +एक `AgentWorkflow` में, वह नाम भी वह है जिसके तहत प्रत्येक हैंडऑफ रिकॉर्ड किया जाता है: + +```text +AgentWorkflow parent span +├─ city_analyst turn 1 +├─ cost_analyst turn 2 +└─ city_analyst turn 3 — a new turn, not a reopened one +``` + +तो `agent_id` आपको बताता है **कौन सा एजेंट** काम किया और `parent_id` आपको बताता है **कौन सा वर्कफ़्लो** इसका था। एक एजेंट जो नियंत्रण बाद में वापस लाया गया वह एक दूसरा मोड़ खोलता है बजाय इसके अपना पहला फिर से खोलने के। + +रन को ओवरराइड करने के लिए, या कई एजेंट्स को एक माता-पिता के तहत समूहीकृत करने के लिए रैप करें: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +`agent_id` को कम कार्डिनलिटी रखें। यह हर डैशबोर्ड सर्फेस पर प्राथमिक पहलू है, इसलिए एक भूमिका या वर्कफ़्लो नाम का उपयोग करें, कभी UUID या प्रति-रन स्ट्रिंग नहीं। + +## सत्र को नियंत्रित करें + +यह एडाप्टर **कोई `session_id` विकल्प नहीं लेता है**। सत्र संलग्न स्कोप से आता है, अन्यथा प्रति वर्कफ़्लो रन `uuid4().hex` का जनन किया गया: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## विकल्प + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True records embedding calls as tool pairs + steps=True, # False drops workflow-step hook pairs + capture_messages=True, # False drops EVERY payload: prompts, completions, + # tool arguments and output, step I/O, retrieval + # queries, the goal and the final answer + capture_limit=8192, # characters kept per captured value + stale_after=600.0, # seconds before an abandoned LEAF is force-closed + reaper_interval=30.0, # how often the reaper sweeps; 0 disables it +) +``` + +| विकल्प | आप इसे क्यों बदलेंगे | +| --- | --- | +| `embeddings` | केवल एम्बेडिंग लेटेंसी या लागत डीबग करते समय चालू करें। एक बल्क इंडेक्स बिल्ड हजारों कॉल्स हैं और टाइमलाइन को दफन कर देगा। | +| `steps` | यदि आप केवल मॉडल और टूल इवेंट्स चाहते हैं और एजेंट लूप को शोर मानते हैं तो बंद करें। | +| `capture_messages` | विनियमित डेटा के लिए बंद करें। हर पेलोड रिकॉर्ड करना बंद हो जाता है — प्रॉम्प्ट्स, मॉडल का समापन, टूल आर्गुमेंट्स और रिटर्न वैल्यूज़, वर्कफ़्लो-स्टेप इनपुट और आउटपुट, रिट्रीवल क्वेरीज़, एजेंट का लक्ष्य और इसका अंतिम उत्तर। संरचना, समय, टोकन्स, और परिणाम अभी भी रिकॉर्ड किए जाते हैं। | +| `capture_limit` | ट्रंकेशन से पहले प्रति कैप्चर किए गए वैल्यू रखे गए वर्ण। इसे बढ़ाएं जब एक RAG प्रॉम्प्ट या पुनः प्राप्त संदर्भ क्लिप आ रहा हो। | +| `stale_after` | एक परित्यक्त **पत्ती** — एक स्ट्रीमिंग प्रतिक्रिया जिसे कोई नहीं खपाया, एक मॉडल या टूल स्पैन जिसका क्लोज कभी नहीं आया — को बल से बंद किए जाने से पहले सेकंड, ताकि सत्र व्यवस्थित हो जाए बजाय `ongoing` को हमेशा पढ़ने के। यह एक परित्यक्त रन को स्वयं बंद नहीं करता है: एक वर्कफ़्लो जिसका कार्य रद्द किया जाता है डिस्पैचर को देखे बिना एक निकास अपना `agent_start` `uninstrument()` तक खुला रखता है। | +| `reaper_interval` | स्वीप फ्रीक्वेंसी। रीपर को पूरी तरह अक्षम करने के लिए `0` पर सेट करें। | + +## मानव लूप में + +जब प्रतीक्षा एक टूल के अंदर होती है तो कैप्चर किया जाता है: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +एक सादे वर्कफ़्लो स्टेप में `ctx.wait_for_event` कैप्चर नहीं है। रनटाइम डिस्पैचर तक पहुंचने से पहले ड्रॉप को पकड़ता है, इसलिए स्टेप निकलता है और बाद में पुनः चलता है कोई संकेत के बिना एक विराम पर कुंजी लगाने के लिए। FunctionAgent पैटर्न, जिसे LlamaIndex दस्तावेज़ करता है, एक टूल के अंदर प्रतीक्षा करता है और पूरी तरह कैप्चर है। + +## सामान्य समस्याएं + + + + अपने LLM में `additional_kwargs={"stream_options": {"include_usage": True}}` जोड़ें। [Token counts](#token-counts) देखें। + + + + LlamaIndex के पास कोई मानक उपयोग फील्ड नहीं है। एडाप्टर कई ज्ञात आकार की कोशिश करता है, और एक इंटीग्रेशन जो अपने काउंटर को कुछ नया नाम देता है वह उनमें से कोई भी मेल नहीं खाएगा। + + कच्चा dict हमेशा शिप किया जाता है, इसलिए पेलोड में `usage` को चेक करें यह देखने के लिए कि आपके प्रोवाइडर ने उन्हें क्या कहा। + + खाली टोकन कॉलम के साथ एक भरा हुआ `usage` जानबूझकर है — यह एक आत्मविश्वास गलत संख्या से बेहतर है। + + + + यह FunctionAgent लूप है, प्रति पुनरावृत्ति एक सेट। डैशबोर्ड पर हुक नाम द्वारा फ़िल्टर करें। ये स्टेप समय आमतौर पर इस एडाप्टर का उपयोग करने का कारण हैं मॉडल-केवल के बजाय। + + + + इस क्रम में जांचें: `instrument()` रन से पहले चला; एक `async with failproofai_sdk.session():` है `await` के चारों ओर; `llama-index-core` 0.14.23 या नवीनतर है; `FAILPROOFAI_SDK_STRICT=1` सेट है, इसलिए एक degraded हुक निगला जाने के बजाय बढ़ता है। + + + +## अगला + + + + जोड़ी, आईडी, सत्र जीवनचक्र, और डिलीवरी। + + + आप अभी-अभी कैप्चर किए गए सत्र के माध्यम से कार्य-कारण का पालन करें। + + + LangGraph, CrewAI, Pydantic AI, और कस्टम एजेंट्स। + + \ No newline at end of file diff --git a/docs/hi/start/integrations/pydantic-ai.mdx b/docs/hi/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..9c7b8a921 --- /dev/null +++ b/docs/hi/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "टाइप किए गए एजेंट, टूल्स, मॉडल कॉल और रिट्राई को इंस्ट्रूमेंट करें।" +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## इंस्टॉल करें + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +समर्थित: `pydantic-ai-slim` 2.0 से 3.0 तक। 2.0 ने `Agent(instrument=...)` को हटाया और capability protocol को पेश किया जिस पर यह एडेप्टर बनाया गया है, इसलिए 1.x को इस तरीके से इंस्ट्रूमेंट नहीं किया जा सकता। + +## इंस्ट्रूमेंट करें + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # किसी भी Agent को बनाने से पहले + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` को किसी भी `Agent` को बनाने से पहले चलना चाहिए। क्षमता निर्माण के समय जोड़ी जाती है, इसलिए पहले बनाया गया एजेंट कोई भी रिकॉर्ड नहीं करता है, कोई त्रुटि के बिना क्योंकि कुछ गलत नहीं हुआ। यह इस एडेप्टर के साथ खाली ट्रेस का सबसे आम कारण है। + + +मॉड्यूल-स्कोप एजेंट्स वह जगह हैं जहां यह समस्या होती है: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # आयात समय पर बनाया गया + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # इसे पहले चलाएं +import agents # अब एजेंट को क्षमता मिलती है +``` + +पुष्टि करें कि यह काम करता है: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI आप द्वारा पारित सूची को एक एकल `root_capability` में विलय करता है, इसलिए पढ़ने के लिए कोई `agent.capabilities` विशेषता नहीं है। + +इंस्ट्रूमेंट करते समय बने एजेंट्स क्षमता को बनाए रखते हैं, इसलिए आप `uninstrument()` कर सकते हैं और उन्हें फिर से बनाए बिना फिर से इंस्ट्रूमेंट कर सकते हैं। + +## क्या रिकॉर्ड किया जाता है + +| Pydantic AI | Failproof इवेंट | +| --- | --- | +| Agent रन | `agent_start`, `agent_end` | +| मॉडल अनुरोध | `model_request`, `model_response`, टोकन उपयोग के साथ | +| टूल कॉल | `tool_use`, `tool_result`, तर्कों के साथ जो मॉडल ने भेजे | +| एक टूल से `ModelRetry` | `tool_result` एक त्रुटि ले जाता है | +| अनहैंडल्ड अपवाद | `error`, फिर `agent_end` परिणाम `failed` के साथ | + +यहाँ कोई हुक जोड़ी नहीं है और कोई मानव-इन-द-लूप जोड़ी नहीं है। Pydantic AI के पास ब्रैकेट करने के लिए कोई नोड या स्टेप सीमा नहीं है और कोई अंतर्निहित मानव विराम नहीं है, इसलिए मैप करने के लिए कुछ भी नहीं है। यदि आप कोई भी बनाते हैं, तो इवेंट्स स्वयं उत्सर्जित करें — [कस्टम एजेंट्स](/hi/reference/custom-agents) देखें। + +`output_type` ट्रेस में कोई अंतर नहीं बनाता है। एक टाइप किया गया रन और एक स्ट्रिंग रन समान इवेंट्स उत्पन्न करते हैं। + +## उदाहरण + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """एक आइटम की यूनिट कीमत। वैध: widget, gadget।""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """स्टॉक में यूनिट्स। वैध: widget, gadget।""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """रीस्टॉक ETA। उपलब्ध नहीं है।""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +ट्रेस में, `restock_eta` एक `tool_result` के रूप में दिखाई देता है जो एक त्रुटि ले जाता है, इसके बाद एक और मॉडल कॉल जहां एजेंट इसके चारों ओर काम करता है, और रन अभी भी `success` के साथ समाप्त होता है। दोनों तथ्य संरक्षित हैं। + +## त्रुटियां, रिट्राई और नियंत्रण प्रवाह + +Pydantic AI तीन अलग-अलग चीजों के लिए अपवाद उठाता है, और एडेप्टर उन्हें अलग करता है: + +| अपवाद | मानक | परिणाम | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | एक वास्तविक टूल विफलता | `tool_result` एक त्रुटि के साथ; रन अभी भी `success` के साथ समाप्त हो सकता है | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | नियंत्रण प्रवाह | एक त्रुटि नहीं; रन को निर्देशित किया जा रहा है | +| कुछ और | एक विफलता | `error`, फिर `agent_end` परिणाम `failed` के साथ | + +`ModelRetry` पहले समूह में जानबूझकर है। इसका अर्थ है कि एक प्रयास वास्तविक रूप से विफल हुआ और मॉडल को फिर से प्रयास करने के लिए कहा गया, जो एक टूल स्पैन के त्रुटि क्षेत्र के लिए है। इसे नियंत्रण प्रवाह के रूप में वर्गीकृत करने से वास्तविक टूल विफलताएं हरे रन के पीछे छिप जाएंगी। + +## अपने स्पैन्स को नाम दें + +Pydantic AI का अपना रन स्पैन `agent` नाम दिया गया है। इसे अपनी पसंद का लेबल देने के लिए कॉल को लपेटें: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +फ्रेमवर्क का स्पैन फिर `inventory` के अंतर्गत नेस्ट होता है, और यह वह जगह है जहां मॉडल और टूल इवेंट्स लटकते हैं। + +`agent_id` को कम कार्डिनैलिटी रखें। यह हर डैशबोर्ड सतह पर प्राथमिक पहलू है, इसलिए एक भूमिका नाम का उपयोग करें, कभी UUID या प्रति-रन स्ट्रिंग नहीं। + +## सेशन को नियंत्रित करें + +इस क्रम में हल किया गया, पहला मिलान जीतता है: + +1. `instrument("pydantic_ai", session_id=...)` +2. संलग्न `failproofai_sdk.session()` स्कोप +3. रन का `conversation_id`, फिर इसका `run_id` +4. एक उत्पन्न `uuid4().hex` + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## विकल्प + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # हर रन को एक सेशन आईडी पर पिन करें + capture_content=True, # False पेलोड्स से प्रॉम्प्ट्स और कंपलीशन्स को छोड़ता है +) +``` + +## सामान्य समस्याएं + + + + `Agent` को `instrument()` चलने से पहले बनाया गया था। ऊपर की चेतावनी देखें, और `agent.root_capability.capabilities` जांचें। + + + + एक बेयर `raise` प्रसारित होता है; यह Pydantic AI का डिज़ाइन है। मॉडल को इसके चारों ओर काम करने देने के लिए, `ModelRetry` को एक संदेश के साथ उठाएं जिस पर वह कार्य कर सकता है। विफलता किसी भी तरीके से रिकॉर्ड की जाती है। + + + + वह चाइल्ड Pydantic AI का अपना रन स्पैन है, और यह वह जगह है जहां मॉडल और टूल इवेंट्स लटकते हैं। अपना स्कोप छोड़ें यदि आप एक एकल स्पैन चाहते हैं, कस्टम नाम की कीमत पर। + + + + Pydantic AI का एसिंक ग्राफ स्टैक पेलोड फील्ड लिमिट से लंबा है, और ट्रेसबैक की अंतिम पंक्ति अपवाद ही है। यह फील्ड पीछे की ओर से बजाय आगे की ओर से ट्रिम की जाती है, इसलिए आपको जो पंक्ति चाहिए वह बची रहती है। + + + +## आगे + + + + जोड़ी, आईडी, सेशन लाइफसाइकल और डिलीवरी। + + + आपने जो सेशन कैप्चर किया उस के माध्यम से कार्य-कारण का अनुसरण करें। + + + LangGraph, CrewAI, LlamaIndex, और कस्टम एजेंट्स। + + \ No newline at end of file diff --git a/docs/hi/start/quickstart.mdx b/docs/hi/start/quickstart.mdx index dde14048c..16a83d5a0 100644 --- a/docs/hi/start/quickstart.mdx +++ b/docs/hi/start/quickstart.mdx @@ -5,50 +5,50 @@ description: "एक एजेंट सेशन कैप्चर करे icon: "zap" --- -यह त्वरित शुरुआत एक मशीन को सेशन रिपोर्ट करने, एक ऑडिट चलाने और एक नीति तैनात करने के लिए प्राप्त करती है। Failproof को सेट अप करने के लिए कौशल का उपयोग करें, या मैनुअल चरणों का पालन करें। +यह त्वरित शुरुआत एक मशीन को सेशन रिपोर्ट करने, एक ऑडिट चलाने और एक नीति तैनात करने के लिए सेट अप करती है। Failproof AI को सेट करने के लिए कौशल का उपयोग करें, या मैनुअल चरणों का पालन करें। -**आपका पथ कौन सा है?** यदि आपका एजेंट 12 समर्थित [harnesses](/hi/reference/harnesses) में से एक में चलता है — एक कोडिंग CLI, या Hermes या OpenClaw जैसा गेटवे — नीचे दिए गए चरणों का पालन करें; आपको Node.js 20.9 या बाद का संस्करण चाहिए। यदि आपके एजेंट के पास कोई harness नहीं है, तो इसे ट्रेसिंग और ऑडिट के लिए [Python SDK](/hi/reference/custom-agents) के साथ instrument करें, फिर [अपनी पहली विफलता जांच चलाएं](/hi/start/first-audit) पर फिर से जुड़ें; उस पथ पर प्रवर्तन के लिए आपके रनटाइम में एक हुक की आवश्यकता है। +**आपका पथ कौन सा है?** यदि आपका एजेंट 12 समर्थित [हार्नेस](/hi/reference/harnesses) में से एक में चलता है — एक कोडिंग CLI, या Hermes या OpenClaw जैसा गेटवे — नीचे दिए गए चरणों का पालन करें; आपको Node.js 20.9 या बाद का संस्करण चाहिए। यदि आपके एजेंट के पास कोई हार्नेस नहीं है, तो ट्रेसिंग और ऑडिट के लिए इसे [Python SDK](/hi/reference/custom-agents) से इंस्ट्रूमेंट करें, फिर [अपनी पहली विफलता जांच चलाएं](/hi/start/first-audit) पर फिर से शामिल हों; उस पथ पर enforcement के लिए आपके runtime में एक 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. ``` - आपका एजेंट प्रोजेक्ट का निरीक्षण करता है, प्रासंगिक integration चुनता है, सेटअप निष्पादित करता है और इसे सत्यापित करता है। व्यक्तिगत कौशल और उन्नत स्थापना विकल्पों के लिए [FailproofAI कौशल रिपॉजिटरी](https://github.com/FailproofAI/skills) देखें। + आपका एजेंट प्रोजेक्ट का निरीक्षण करता है, प्रासंगिक एकीकरण चुनता है, सेटअप करता है, और इसे सत्यापित करता है। व्यक्तिगत कौशल और उन्नत इंस्टॉलेशन विकल्पों के लिए [FailproofAI कौशल रिपोजिटरी](https://github.com/FailproofAI/skills) देखें। ## शुरू करने से पहले -1. [Failproof AI डैशबोर्ड](https://app.befailproof.ai) खोलें और एक खाता बनाएं या अपने काम के ईमेल से साइन इन करें। +1. [Failproof AI डैशबोर्ड](https://app.befailproof.ai) खोलें और एक खाता बनाएं या अपने कार्य ईमेल से साइन इन करें। 2. **Administration → Keys** पर जाएं और `events:add` और `policies:pull` के साथ एक कुंजी बनाएं। -3. एकबारी secret की प्रतिलिपि बनाएं और इसे लक्ष्य मशीन पर संग्रहीत करें: +3. एकबारी गुप्त को कॉपी करें और इसे लक्ष्य मशीन पर संग्रहीत करें: ```bash export FAILPROOFAI_KEY="" ``` - ## स्थापित करें + ## इंस्टॉल करें - + ```bash npm install -g failproofai failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - सेशन transcripts डिफ़ॉल्ट रूप से भेजे जाते हैं। transcript सामग्री के बिना हुक गतिविधि और नीति निर्णयों की रिपोर्ट करने के लिए `--no-transcripts` जोड़ें। + सेशन ट्रांसक्रिप्ट डिफ़ॉल्ट रूप से भेजी जाती हैं। `--no-transcripts` जोड़ें ताकि ट्रांसक्रिप्ट सामग्री के बिना hook activity और नीति निर्णय रिपोर्ट किए जाएं। - यदि इस मशीन के पास पहले से एजेंट history है, तो पिछले सात दिनों का पूर्वावलोकन और आयात करें, फिर डिलीवरी समाप्त होने का प्रतीक्षा करें। एक नई मशीन पर इस चरण को छोड़ें। + यदि इस मशीन के पास पहले से एजेंट history है, तो पिछले सात दिनों का पूर्वावलोकन करें और आयात करें, फिर delivery समाप्त होने का इंतजार करें। नई मशीन पर इस चरण को छोड़ें। ```bash failproofai backfill --since 7d --dry-run @@ -58,28 +58,28 @@ export FAILPROOFAI_KEY="" Failproof AI में **Sessions** खोलें और एक आयातित सेशन चुनें। - - यह Failproof AI को आपके harness से जोड़ता है और 40 built-in नीतियां स्थापित करता है। उन्हें स्थानीय नीति निर्णय देखने और Failproof AI आपके सेशन का ऑडिट करने और आपके एजेंट के लिए नीतियां लिखने से पहले प्रवर्तन आजमाने के लिए उपयोग करें। + + यह Failproof AI को आपके हार्नेस से जोड़ता है और 40 built-in नीतियां इंस्टॉल करता है। उन्हें स्थानीय नीति निर्णय देखने और Failproof AI आपके सेशन ऑडिट करने और आपके एजेंट के लिए नीतियां लिखने से पहले enforcement आजमाने के लिए उपयोग करें। - installer को अपने harness का पता लगाने दें, या एक को स्पष्ट रूप से नाम दें। 12 में से प्रत्येक एक वैध `--cli` मान है — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`। + इंस्टॉलर को अपने हार्नेस को detect करने दें, या एक को explicitly नाम दें। 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 पर सत्यापित हैं — प्रति-harness मैट्रिक्स के लिए [प्रवर्तन क्षमता](/hi/reference/harnesses#enforcement-capability) देखें। + एक tool call को चलने से पहले block करना सभी 12 पर verified है। Turn-end gates 8 पर verified हैं — per-harness matrix के लिए [enforcement capability](/hi/reference/harnesses#enforcement-capability) देखें। - - [अपनी पहली विफलता जांच चलाएं](/hi/start/first-audit) का पालन करें। एक ठोस लक्ष्य का उपयोग करें जैसे यह खोजना कि सेशन कहां एजेंट ने अपने दृष्टिकोण को बदले बिना एक विफल tool को पुन: प्रयास किया। + + [अपनी पहली विफलता जांच चलाएं](/hi/start/first-audit) का पालन करें। एक ठोस लक्ष्य का उपयोग करें जैसे कि "ऐसे सेशन खोजें जहां एजेंट ने अपने दृष्टिकोण को बदले बिना एक विफल tool को फिर से try किया।" - [एक नीति के साथ अपनी पहली विफलता को रोकें](/hi/start/first-policy) का पालन करें। observe मोड में शुरू करें, मिलान का निरीक्षण करें, फिर समीक्षा किए गए संस्करण को लागू करें। + [एक नीति के साथ अपनी पहली विफलता को रोकें](/hi/start/first-policy) का पालन करें। observe mode में शुरू करें, matches को inspect करें, फिर reviewed संस्करण को enforce करें। - `failproofai config --status` चलाएं। एक स्वस्थ सेटअप क्लाउड कनेक्शन, daemon स्थिति और प्रवर्तन रोका गया है या नहीं यह रिपोर्ट करता है। + `failproofai config --status` चलाएं। एक स्वस्थ सेटअप क्लाउड कनेक्शन, daemon state, और क्या enforcement को paused किया गया है यह रिपोर्ट करता है। \ No newline at end of file diff --git a/docs/hi/start/quickstarts/crewai.mdx b/docs/hi/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..67bee8d3c --- /dev/null +++ b/docs/hi/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "इंस्टॉल करें, इंस्ट्रूमेंट करें, और अपना पहला ट्रेस देखें।" +icon: "/images/frameworks/crewai.svg" +--- + +आपके पहले CrewAI ट्रेस के लिए तीन चरण। प्रत्येक इवेंट क्या ले जाता है, फ्लो कैसे होता है, और समस्या निवारण के लिए, [पूरी गाइड](/hi/start/integrations/crewai) देखें। + +## इंस्टॉल करें + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## इंस्ट्रूमेंट करें + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +आपके crew, agents, tasks, या tools में कुछ नहीं बदलता है। `instrument()` CrewAI के मॉड्यूल-स्तर की इवेंट बस को सब्सक्राइब करता है। + +## जांचें कि यह पहुंचा या नहीं + +इसे एक बार चलाएं, फिर **Observe → Sessions** खोलें और अपना environment चुनें। आपका रन एक पुनर्निर्मित ट्रेस के रूप में दिखाई देता है। + +अगर कुछ नहीं आता है, तो `failproofai config --status` से पुष्टि करें कि मशीन कनेक्ट है। + + + क्या रिकॉर्ड होता है, फ्लो कैसे होता है, टोकन उपयोग, स्पैन नामकरण, विकल्प, और सामान्य समस्याएं। + \ No newline at end of file diff --git a/docs/hi/start/quickstarts/custom-agents.mdx b/docs/hi/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..f24a69fe5 --- /dev/null +++ b/docs/hi/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "Custom agents" +description: "अपने agent को तीन `with` ब्लॉकों में wrap करें और यह recording शुरू कर देता है।" +icon: "code" +--- + +एक agent के लिए जो आपने स्वयं लिखा है, या एक framework जिसके लिए Failproof AI के पास adapter नहीं है। + +आप जो काम पहले से करते हैं उसे `with` ब्लॉकों में wrap करते हैं। प्रत्येक ब्लॉक यह record करता है कि यह कब शुरू हुआ, कब समाप्त हुआ, और कितना समय लगा — आप कुछ और नहीं कहते। + +## Install + +```bash +pip install failproofai-sdk +``` + +कोई अतिरिक्त packages नहीं, और कोई dependencies नहीं। + +## 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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # one tool call +``` + +इसे ऊपर से नीचे तक पढ़ें और यह बताता है कि इसका क्या मतलब है: + +| इसे wrap करें | यह कहने के लिए | +| --- | --- | +| `session()` | ये सभी events एक ही run से संबंधित हैं | +| `agent()` | कुछ काम कर रहा है — इसे एक ऐसा नाम दें जिसे आप किसी list में पहचान सकें | +| `tool_call()` | यह एक tool है, और यहाँ इसने क्या return किया | + +उन्हें जैसे भी आपका code nest करता है nest करें। आप कभी भी ids के चारों ओर pass नहीं करते: प्रत्येक ब्लॉक याद रखता है कि यह किसके अंदर है, इसलिए कोई भी चीज़ जो आप record करते हैं वह खुद ही सही run और सही agent को pick करती है। `async with` बिल्कुल उसी तरह काम करता है। + +## जांचें कि यह पहुँचा या नहीं + +इसे एक बार चलाएं, फिर **Observe → Sessions** खोलें और अपना environment चुनें। आपका run एक reconstructed trace के रूप में दिखाई देता है। + +अगर कुछ नहीं पहुँचता, तो `failproofai config --status` के साथ confirm करें कि machine connected है। + + + हर event method, जब आपका code raise करता है तब क्या होता है, एक worked example, threads और async, और एक framework को instrument करना जिसके पास adapter नहीं है। + \ No newline at end of file diff --git a/docs/hi/start/quickstarts/langchain.mdx b/docs/hi/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..1bf59cb05 --- /dev/null +++ b/docs/hi/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain और LangGraph" +description: "इंस्टॉल करें, इंस्ट्रूमेंट करें, और अपना पहला ट्रेस देखें।" +icon: "/images/frameworks/langchain.svg" +--- + +आपके पहले LangChain या LangGraph ट्रेस के लिए तीन चरण। स्ट्रीमिंग, मानव-इन-द-लूप, स्पैन नामकरण, और विकल्पों के लिए, [पूर्ण गाइड](/hi/start/integrations/langchain) देखें। + +## इंस्टॉल करें + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +LangGraph के बिना LangChain के लिए, `failproofai-sdk[langchain]` का उपयोग करें। + +## इंस्ट्रूमेंट करें + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +कोई कॉल साइट परिवर्तन नहीं। `instrument()` एक ट्रेसर पंजीकृत करता है जिसे LangChain हर कॉलबैक मैनेजर में इंजेक्ट करता है जो यह बनाता है, इसलिए ग्राफ़, टूल्स, और मॉडल्स को कैप्चर किया जाता है — उन लोगों सहित जो उन पुस्तकालयों के अंदर हैं जिन्हें आपने नहीं लिखा है। + +## जांचें कि यह पहुंचा + +इसे एक बार चलाएं, फिर **Observe → Sessions** खोलें और अपने वातावरण को चुनें। आपका रन एक पुनर्निर्मित ट्रेस के रूप में प्रदर्शित होता है। + +यदि कुछ नहीं पहुंचता है, तो पुष्टि करें कि मशीन `failproofai config --status` के साथ जुड़ी हुई है। + + + क्या रिकॉर्ड किया जाता है, स्ट्रीमिंग, टोकन काउंट, स्पैन नामकरण, सत्र नियंत्रण, विकल्प, और मानव इन द लूप। + \ No newline at end of file diff --git a/docs/hi/start/quickstarts/llamaindex.mdx b/docs/hi/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..78f199c30 --- /dev/null +++ b/docs/hi/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "इंस्टॉल करें, इंस्ट्रूमेंट करें, और अपना पहला ट्रेस देखें।" +icon: "/images/frameworks/llamaindex.svg" +--- + +आपके पहले LlamaIndex ट्रेस के लिए तीन स्टेप्स। वर्कफ़्लो स्टेप्स, रिट्रीवल, रीपर, और विकल्पों के लिए, [पूर्ण गाइड](/hi/start/integrations/llamaindex) देखें। + +## इंस्टॉल करें + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## इंस्ट्रूमेंट करें + +LlamaIndex का एजेंट API एसिंक है। हर स्कोप `async with` के साथ-साथ `with` के अंतर्गत भी काम करता है। + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + आपके LLM पर एक अतिरिक्त आर्गुमेंट के बिना, आपके ट्रेस में हर टोकन काउंट null है — `llama-index-llms-openai` स्ट्रीमिंग करते समय उपयोग की मांग नहीं करता। [टोकन काउंट्स](/hi/start/integrations/llamaindex#token-counts) देखें। + + +## जांचें कि यह पहुंचा + +इसे एक बार चलाएं, फिर **Observe → Sessions** खोलें और अपना एनवायरनमेंट चुनें। आपका रन एक पुनर्निर्मित ट्रेस के रूप में दिखाई देता है। + +अगर कुछ नहीं आता है, तो `failproofai config --status` के साथ पुष्टि करें कि मशीन कनेक्टेड है। + + + टोकन काउंट्स, क्या रिकॉर्ड होता है, वर्कफ़्लो स्टेप्स, रिट्रीवल, विकल्प, और सामान्य समस्याएं। + \ No newline at end of file diff --git a/docs/hi/start/quickstarts/pydantic-ai.mdx b/docs/hi/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..c44b331a8 --- /dev/null +++ b/docs/hi/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "इंस्टॉल करें, इंस्ट्रूमेंट करें, और अपना पहला trace देखें।" +icon: "/images/frameworks/pydantic-ai.svg" +--- + +आपके पहले Pydantic AI trace के लिए तीन चरण। टूल्स, रिट्राइज, स्ट्रीमिंग और विकल्पों के लिए, [पूर्ण गाइड](/hi/start/integrations/pydantic-ai) देखें। + +## इंस्टॉल करें + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## इंस्ट्रूमेंट करें + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # किसी भी Agent को बनाने से पहले + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` को आपके द्वारा `Agent` बनाने से **पहले** चलना चाहिए। यह क्षमता निर्माण के समय जोड़ी जाती है, इसलिए पहले बनाया गया एक agent कुछ भी रिकॉर्ड नहीं करता — कोई त्रुटि के बिना, क्योंकि कोई समस्या नहीं हुई। यह इस एडेप्टर के साथ खाली trace का सबसे आम कारण है, और मॉड्यूल-स्कोप agents वह जगह है जहां यह काटता है: `failproofai_sdk` को इंपोर्ट करें और उन्हें बनाने वाले मॉड्यूल को इंपोर्ट करने से पहले `instrument()` को कॉल करें। + + +## जांचें कि यह पहुंचा + +इसे एक बार चलाएं, फिर **Observe → Sessions** खोलें और अपना environment चुनें। आपका रन एक पुनर्निर्मित trace के रूप में दिखाई देता है। + +यदि कुछ नहीं पहुंचता है, तो `failproofai config --status` के साथ मशीन के कनेक्ट होने की पुष्टि करें। + + + क्या रिकॉर्ड किया जाता है, tools और retries, streaming, span नामकरण, विकल्प, और सामान्य समस्याएं। + \ No newline at end of file diff --git a/docs/i18n/README.ar.md b/docs/i18n/README.ar.md index cc4e496e6..408fc74ea 100644 --- a/docs/i18n/README.ar.md +++ b/docs/i18n/README.ar.md @@ -22,8 +22,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) -**المراقبة والفرض لكل محاولة يشغلها وكلاؤك.** -أينما يعمل وكلاؤك، نحن نراهم — ويمكننا أن نرفضهم. يتصل failproofai بـ 12 محاولة وكيل — واجهات برمجة الترميز مثل Claude Code و Codex، بوابات الدردشة مثل Hermes، المساعدين المستضافين ذاتيًا مثل OpenClaw — ويلتقط كل عملية ويحجب استدعاءات الأدوات الخطرة قبل تنفيذها. 40 سياسة مدمجة. بدون كمون. يعمل محليًا. +**قابلية الملاحظة والفرض لكل بيئة تقنية يعمل فيها وكيلك الذكي.** أينما يعمل وكيلك +الذكي، نحن نراه — ويمكننا الرفض. يتصل failproofai بـ 12 بيئة تقنية — واجهات سطر +أوامر البرمجة مثل Claude Code و Codex، بوابات الدردشة مثل Hermes، المساعدات ذاتية +الاستضافة مثل OpenClaw — لالتقاط كل عملية وحجب استدعاءات الأدوات الخطيرة قبل تنفيذها. +40 سياسة مدمجة. بدون تأخير. يعمل محليًا. @@ -33,11 +36,15 @@ --- -## المحاولات المدعومة +## البيئات التقنية المدعومة -اثنا عشر محاولة في فئتين — عشرة واجهات برمجة ترميز، وبوابتين للدردشة والمساعدين (Hermes و OpenClaw). نفس الأحداث، نفس السياسات، نفس سجل الجلسة، أيًا كانت المحاولة التي يعمل فيها وكيلك. +اثنتا عشرة بيئة تقنية في فئتين — عشر واجهات سطر أوامر برمجة، وبوابتا دردشة ومساعد +(Hermes، OpenClaw). نفس الأحداث، نفس السياسات، نفس سجل الجلسة، أيًا كانت البيئة التي +يعمل فيها وكيلك الذكي. -الوكلاء الذين لا يعملون في أي منها يبلغون من خلال [Python SDK](https://docs.befailproof.ai/reference/python-sdk)، والذي يوفر لك التتبع والجلسات والتدقيق. يتطلب الفرض هناك دخل في وقتك — [تحدث إلينا](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 @@ -137,37 +144,38 @@ ```sh npm install -g failproofai -failproofai policies --install # أو ما عليك سوى تشغيل `failproofai` وقبول موجه التشغيل الأول +failproofai policies --install # أو قم بتشغيل `failproofai` فقط واقبل رسالة التشغيل الأول failproofai ``` -تنشط 40 سياسة مدمجة فورًا. لوحة معلومات في `localhost:8020`. عطّل موجه التشغيل الأول باستخدام `FAILPROOFAI_NO_FIRST_RUN=1`. +40 سياسة مدمجة تتفعل فورًا. لوحة التحكم في `localhost:8020`. عطّل رسالة التشغيل الأول باستخدام `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## ما يوقفه +## ما يمنعه | السياسة | ما يحجبه | |---|---| -| `sanitize-api-keys` | مفاتيح API التي تتسرب إلى سياق الوكيل | +| `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` | حذف الملفات العودي | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` غير المحدود | +| `block-terraform` / `block-kubectl` | التغييرات غير المراجعة للبنية الأساسية الحية | +| `block-rm-rf` | حذف الملفات بشكل متكرر | | `block-force-push` / `block-push-master` | `git push --force`، الدفع المباشر إلى `main` | -ينطبق الخمسة الأولى على أي وكيل يمكنه استدعاء أداة. الثلاثة الأخيرة هي المفضلة لدى المطورين — واجهات برمجة الترميز هي فئة المحاولة التي نغطيها بعمق. +تنطبق أول خمسة على أي وكيل يمكنه استدعاء أداة. الثلاثة الأخيرة هي المفضلة لدى المطورين — +واجهات سطر أوامر البرمجة هي الفئة من البيئات التقنية التي نغطيها بعمق أكثر. -→ [جميع السياسات المدمجة 40](https://docs.befailproof.ai/policies/builtin) +→ [جميع السياسات المدمجة البالغ عددها 40](https://docs.befailproof.ai/policies/builtin) --- ## سياساتك الخاصة -أفلت ملف إلى `.failproofai/policies/` — يتم تحميله تلقائيًا، بدون حاجة لأعلام. -تأكد منه والفريق بأكمله يحصل عليه في السحب التالي. +ضع ملفًا في `.failproofai/policies/` — يتم تحميله تلقائيًا، لا توجد حاجة لعلامات. +قم بارتكابه وستحصل الفريق بأكمله عليه في الجلب التالي. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -183,29 +191,39 @@ customPolicies.add({ }); ``` -ثلاثة قرارات متاحة لكل سياسة: +هناك ثلاثة قرارات متاحة لكل سياسة: | القرار | التأثير | |---|---| | `allow()` | السماح بالعملية | -| `deny(message)` | حجبها — تعود الرسالة إلى الوكيل | -| `instruct(message)` | دعها تمر، لكن أضف سياقًا إلى موجه الوكيل التالي | +| `deny(message)` | حجبها — يعود الرسالة إلى الوكيل | +| `instruct(message)` | السماح بها، لكن أضف سياقًا إلى المحفز التالي للوكيل | → [دليل السياسات المخصصة](https://docs.befailproof.ai/policies/custom) --- -## المراقبة +## قابلية الملاحظة -الفرض نصف واحد. النصف الآخر هو رؤية ما فعله الوكيل بالفعل. +الفرض نصف واحد. النصف الآخر هو رؤية ما فعله الوكيل فعلاً. -قم بتشغيل `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/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) · @@ -217,46 +235,50 @@ customPolicies.add({ | ابدأ | | |---|---| -| [البدء السريع](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/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) | جميع السياسات 40 مع المعاملات | +| [السياسات المدمجة](https://docs.befailproof.ai/policies/builtin) | جميع السياسات الـ 40 مع المعاملات | | [السياسات المخصصة](https://docs.befailproof.ai/policies/custom) | اكتب الخاصة بك | | [التكوين](https://docs.befailproof.ai/policies/local-configuration) | نطاقات التكوين وقواعد الدمج | -| أداتك الخاصة بوكيل | | +| أداة وكيلك الخاص | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | التقرير يعمل من وكيل بدون محاولة | -| [سياسة 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/`. انظر -> [البناء قبل أن تعمل خطافات المطورين داخل المستودع](../../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) في SF و Bengaluru. +تم البناء بـ ❤️ بواسطة [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 355183698..1707c9d21 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 jede Umgebung, in der deine Agents laufen.** -Egal wo deine Agents ausgeführt werden – wir sehen es, und wir können eingreifen. Failproof hooks 12 Agent-Harnesses – 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. 40 eingebaute Policies. Null Latenz. Läuft lokal. +**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 Durchlauf und blockiert gefährliche Tool-Aufrufe, bevor sie ausgeführt werden. 40 eingebaute Richtlinien. Keine Latenz. Läuft lokal. @@ -33,9 +33,9 @@ Egal wo deine Agents ausgeführt werden – wir sehen es, und wir können eingre ## Unterstützte Harnesses -Zwölf Harnesses in zwei Klassen – zehn Coding-CLIs und zwei Chat- und Assistenten-Gateways (Hermes, OpenClaw). Dieselben Events, dieselben Policies, dieselbe Session-Historie – egal in welchem Harness dein Agent läuft. +Zwölf Harnesses in zwei Klassen – zehn Coding-CLIs und zwei Chat- und Assistenz-Gateways (Hermes, OpenClaw). Dieselben Events, dieselben Richtlinien, dieselbe Sitzungshistorie – unabhängig davon, welchen Harness dein Agent verwendet. -Agents, die in keinem davon laufen, berichten über das [Python SDK](https://docs.befailproof.ai/reference/python-sdk), das Tracing, Sessions und Audits bereitstellt. Für die Durchsetzung ist dort ein Hook in deiner eigenen Runtime erforderlich – [sprich uns an](mailto:support@befailproof.ai) und wir finden gemeinsam eine Lösung. +Agenten, die in keinem davon laufen, können über das [Python SDK](https://docs.befailproof.ai/reference/custom-agents) berichten – es bietet Tracing, Sessions und Audits. Durchsetzung erfordert dort einen Hook in deiner eigenen Laufzeitumgebung – [sprich uns an](mailto:support@befailproof.ai) und wir erarbeiten 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 +135,36 @@ Agents, die in keinem davon laufen, berichten über das [Python SDK](https://doc ```sh npm install -g failproofai -failproofai policies --install # oder einfach `failproofai` ausführen und die Erststart-Aufforderung bestätigen +failproofai policies --install # oder einfach `failproofai` ausführen und den Erststart-Dialog bestätigen failproofai ``` -40 eingebaute Policies werden sofort aktiviert. Dashboard unter `localhost:8020`. Die Erststart-Aufforderung lässt sich mit `FAILPROOFAI_NO_FIRST_RUN=1` deaktivieren. +40 eingebaute Richtlinien werden sofort aktiviert. Dashboard unter `localhost:8020`. Den Erststart-Dialog deaktivieren mit `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## Was blockiert wird +## Was es verhindert -| Policy | Was sie blockiert | +| Richtlinie | Was sie blockiert | |---|---| -| `sanitize-api-keys` | API-Keys, die in den Kontext des Agents gelangen | -| `block-env-files` | Lesezugriffe auf `.env`- und andere Secret-Dateien | -| `warn-repeated-tool-calls` | Endlosschleifen des Agents beim selben Aufruf | -| `block-sudo` | Privilege Escalation | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, unbegrenzte `DELETE`-Operationen | -| `block-terraform` / `block-kubectl` | Nicht überprüfte Änderungen an Live-Infrastruktur | +| `sanitize-api-keys` | API-Schlüssel, die in den Kontext des Agenten gelangen | +| `block-env-files` | Lesezugriffe auf `.env` und andere Secret-Dateien | +| `warn-repeated-tool-calls` | Den Agenten, der denselben Aufruf in einer Schleife wiederholt | +| `block-sudo` | Privilege-Escalation | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, unbegrenzte `DELETE`-Abfragen | +| `block-terraform` / `block-kubectl` | Nicht geprüfte Änderungen an Live-Infrastruktur | | `block-rm-rf` | Rekursives Löschen von Dateien | | `block-force-push` / `block-push-master` | `git push --force`, direkte Pushes auf `main` | -Die ersten fünf gelten für jeden Agent, der Tools aufrufen kann. Die letzten drei sind die Favoriten der Entwickler – Coding-CLIs sind die Harness-Klasse, die wir am tiefsten abdecken. +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 umfassendsten abdecken. -→ [Alle 40 eingebauten Policies](https://docs.befailproof.ai/policies/builtin) +→ [Alle 40 eingebauten Richtlinien](https://docs.befailproof.ai/policies/builtin) --- -## Eigene Policies +## Eigene Richtlinien -Lege eine Datei in `.failproofai/policies/` ab – sie wird automatisch geladen, ohne 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 zusätzliche Flags. Committe sie und das gesamte Team erhält sie beim nächsten Pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -180,29 +180,29 @@ customPolicies.add({ }); ``` -Drei Entscheidungen stehen jeder Policy zur Verfügung: +Drei Entscheidungen stehen jeder Richtlinie zur Verfügung: | Entscheidung | Wirkung | |---|---| | `allow()` | Operation erlauben | -| `deny(message)` | Blockieren – die Nachricht wird an den Agent zurückgegeben | -| `instruct(message)` | Durchlassen, aber Kontext zum nächsten Prompt des Agents hinzufügen | +| `deny(message)` | Blockieren – die Nachricht wird an den Agenten zurückgegeben | +| `instruct(message)` | Durchlassen, aber dem nächsten Prompt des Agenten Kontext hinzufügen | -→ [Leitfaden für eigene Policies](https://docs.befailproof.ai/policies/custom) +→ [Leitfaden für eigene Richtlinien](https://docs.befailproof.ai/policies/custom) --- ## Observability -Durchsetzung ist nur die eine Hälfte. Die andere Hälfte ist zu sehen, was der Agent tatsächlich getan hat. +Durchsetzung ist die eine Hälfte. Die andere Hälfte ist zu sehen, was der Agent tatsächlich getan hat. -Führe `failproofai` ohne Argumente aus und es startet ein Dashboard auf `localhost:8020`, das die bereits auf deinem Rechner gespeicherte Ausführungshistorie auswertet – kein Account, keine Registrierung, nichts verlässt den Rechner. Du siehst die Session-Liste, die Abfolge von Modell-Aufrufen, Tool-Aufrufen und Hook-Entscheidungen innerhalb jedes Laufs, was blockiert wurde und was die Policy dem Agent mitgeteilt hat, sowie ein Offline-Audit (`failproofai audit`), das deine Historie auf riskante Muster scannt und Policies vorschlägt, um diese zu unterbinden. +Starte `failproofai` ohne Argumente, und es stellt ein Dashboard unter `localhost:8020` bereit, das die bereits auf deinem Rechner vorhandene 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 Durchlaufs, was blockiert wurde und was die Richtlinie dem Agenten mitgeteilt hat, sowie ein Offline-Audit (`failproofai audit`), das deine Historie nach riskanten Mustern durchsucht 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 Agents auf einer ganzen Flotte betreiben: jeder Lauf aus jedem Harness an einem Ort, ein Ausführungsgraph mit parallelen Sub-Agents auf eigenen Spuren, p50/p95/p99-Latenz für Modelle, Tools und Hooks, kosten- und Kontextfenster-Tracking pro Modell, Fehler-Tracking, SQL über deine eigenen Traces mit teilbaren Dashboards, Evaluierungen bewertet durch deinen eigenen Dienst, 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 über eine gesamte Flotte hinweg betreiben: alle Durchläufe aus allen Harnesses 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 Kontextfensterverfolgung, Fehlerverfolgung, SQL über eigene Traces mit teilbaren Dashboards, Evaluierungen bewertet durch deinen eigenen Dienst, geplante Audits, die wiederkehrende Fehler in evidenzgestützte Befunde umwandeln, sowie Benachrichtigungen über 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) · [Audits](https://docs.befailproof.ai/audits/overview) · @@ -214,43 +214,43 @@ Führe `failproofai` ohne Argumente aus und es startet ein Dashboard auf `localh | Einstieg | | |---|---| -| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Installieren, Harness verbinden, ersten Lauf sehen | +| [Schnellstart](https://docs.befailproof.ai/start/quickstart) | Installieren, einen Harness verbinden, den ersten Durchlauf 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 einzelne durchsetzen kann | +| [Unterstützte Harnesses](https://docs.befailproof.ai/reference/harnesses) | Alle 12 und was jeder davon durchsetzen kann | | Beobachten | | |---|---| -| [Sessions](https://docs.befailproof.ai/sessions/overview) | Einen Lauf verfolgen: Modelle, Tools, Fehler, Latenz | +| [Sessions](https://docs.befailproof.ai/sessions/overview) | Einen Durchlauf 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 Sessions hinweg finden | -| [Lokales Dashboard](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, kein Account erforderlich | +| [Audits](https://docs.befailproof.ai/audits/overview) | Fehlermuster über viele Sessions hinweg erkennen | +| [Lokales Dashboard](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, kein Konto erforderlich | | Durchsetzen | | |---|---| -| [Eingebaute Policies](https://docs.befailproof.ai/policies/builtin) | Alle 40 Policies mit Parametern | -| [Eigene Policies](https://docs.befailproof.ai/policies/custom) | Eigene schreiben | -| [Konfiguration](https://docs.befailproof.ai/policies/local-configuration) | Konfig-Scopes und Merge-Regeln | +| [Eingebaute Richtlinien](https://docs.befailproof.ai/policies/builtin) | Alle 40 Richtlinien mit Parametern | +| [Eigene Richtlinien](https://docs.befailproof.ai/policies/custom) | Eigene schreiben | +| [Konfiguration](https://docs.befailproof.ai/policies/local-configuration) | Konfigurations-Scopes und Zusammenführungsregeln | -| Eigenen Agent instrumentieren | | +| Eigenen Agenten instrumentieren | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | Läufe eines Agents ohne Harness melden | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Referenz für `allow` / `deny` / `instruct` | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Durchläufe von einem Agenten ohne Harness melden | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` Referenz | --- ## Lizenz -MIT mit [Commons Clause](https://commonsclause.com/) – kostenlos für den internen und privaten Einsatz; 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 persönlichen Gebrauch; der kommerzielle Weiterverkauf von failproofai selbst erfordert eine separate Vereinbarung. Den vollständigen Text findest du unter [LICENSE](../../LICENSE). --- ## Mitwirken -Siehe [CONTRIBUTING.md](../../CONTRIBUTING.md). Neue Policies, Edge Cases und Übersetzungen sind herzlich willkommen. +Siehe [CONTRIBUTING.md](../../CONTRIBUTING.md). Neue Richtlinien, Grenzfälle und Übersetzungen sind herzlich willkommen. -> **Vor dem Start bauen.** Führe zuerst `bun install && bun run build` aus. Dieses Repository verwendet failproofais eigene Hooks auf sich selbst, 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 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 > [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Gebaut mit ❤️ von [befailproof.ai](https://befailproof.ai) in SF und Bengaluru. +Mit ❤️ gebaut von [befailproof.ai](https://befailproof.ai) in SF und Bengaluru. diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md index d22f9edca..746a8887a 100644 --- a/docs/i18n/README.es.md +++ b/docs/i18n/README.es.md @@ -21,7 +21,7 @@ **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 para cada entorno en el que corren tus agentes.** -Dondequiera que ejecutes tus agentes, nosotros lo vemos — y podemos decir que no. Failproof engancha 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. 40 políticas integradas. Cero latencia. Funciona localmente. +Donde sea que corran tus agentes, nosotros lo vemos — y podemos decir que no. Failproof intercepta 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 peligrosas a herramientas antes de que se ejecuten. 40 políticas integradas. Cero latencia. Se ejecuta localmente. @@ -33,9 +33,9 @@ Dondequiera que ejecutes tus agentes, nosotros lo vemos — y podemos decir que ## Entornos compatibles -Doce entornos en dos clases — diez CLIs de codificación y dos pasarelas de chat y asistentes (Hermes, OpenClaw). Los mismos eventos, las mismas políticas, el mismo historial de sesiones, sin importar en cuál ejecutes tu agente. +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, sin importar en cuál de ellos corra tu agente. -Los agentes que no corren en ninguno de ellos reportan a través del [SDK de Python](https://docs.befailproof.ai/reference/python-sdk), que ofrece trazas, sesiones y auditorías. Para aplicar controles en esos casos se necesita un hook en tu propio runtime — [contáctanos](mailto:support@befailproof.ai) y lo mapeamos juntos. +Los agentes que no se ejecuten en ninguno de estos entornos pueden reportar a través del [SDK de Python](https://docs.befailproof.ai/reference/custom-agents), que ofrece trazas, sesiones y auditorías. Para aplicar controles en esos casos se necesita un hook en tu propio runtime — [contáctanos](mailto:support@befailproof.ai) y lo diseñamos 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,11 @@ Los agentes que no corren en ninguno de ellos reportan a través del [SDK de Pyt ```sh npm install -g failproofai -failproofai policies --install # o simplemente ejecuta `failproofai` y acepta el aviso de primera ejecución +failproofai policies --install # o simplemente ejecuta `failproofai` y acepta el aviso del primer inicio failproofai ``` -40 políticas integradas se activan de inmediato. Panel de control en `localhost:8020`. Desactiva el aviso de primera ejecución con `FAILPROOFAI_NO_FIRST_RUN=1`. +40 políticas integradas se activan de inmediato. Panel de control en `localhost:8020`. Desactiva el aviso del primer inicio con `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -149,14 +149,14 @@ failproofai |---|---| | `sanitize-api-keys` | Claves de API que se filtran al contexto del agente | | `block-env-files` | Lecturas de `.env` y otros archivos con secretos | -| `warn-repeated-tool-calls` | El agente en bucle sobre la misma llamada | +| `warn-repeated-tool-calls` | El agente haciendo un bucle con la misma llamada | | `block-sudo` | Escalada de privilegios | | `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sin condiciones | -| `block-terraform` / `block-kubectl` | Cambios no revisados en infraestructura en producción | +| `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 tres últimas son las favoritas de los desarrolladores — las CLIs de codificación son la clase de entorno que cubrimos con mayor profundidad. +Las primeras cinco se aplican a cualquier agente que pueda llamar a 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. → [Las 40 políticas integradas](https://docs.befailproof.ai/policies/builtin) @@ -165,7 +165,7 @@ Las primeras cinco aplican a cualquier agente que pueda invocar una herramienta. ## Tus propias políticas Coloca un archivo en `.failproofai/policies/` — se carga automáticamente, sin necesidad de flags. -Haz commit y todo el equipo lo recibirá en el próximo pull. +Confírmalo en el repositorio y todo el equipo lo recibirá en el próximo pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -197,13 +197,14 @@ Tres decisiones disponibles para cada política: El control es una mitad. La otra mitad es ver qué hizo realmente el agente. -Ejecuta `failproofai` sin argumentos y levanta 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, las llamadas a herramientas y las decisiones de los hooks dentro de cada ejecución, qué fue bloqueado y qué le dijo la política al agente, además de una auditoría offline (`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 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 del hook 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 arriesgados y sugiere políticas para detenerlos. → [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 la parte alojada del mismo modelo de datos, para equipos que ejecutan agentes en una flota: todas las ejecuciones de todos los entornos en un único lugar, un grafo de ejecución con subagentes paralelos en sus propios carriles, 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, email 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) · @@ -213,44 +214,44 @@ Ejecuta `failproofai` sin argumentos y levanta un panel de control en `localhost ## Documentación -| Comenzar | | +| Empezar | | |---|---| -| [Inicio rápido](https://docs.befailproof.ai/start/quickstart) | Instala, conecta un entorno y observa la primera ejecución | +| [Inicio rápido](https://docs.befailproof.ai/start/quickstart) | Instalar, conectar un entorno, ver 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 entornos y qué puede aplicar cada uno | +| [Entornos compatibles](https://docs.befailproof.ai/reference/harnesses) | Los 12, y qué puede controlar cada uno | | Observar | | |---|---| -| [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 dice el grafo de ejecución | -| [Auditorías](https://docs.befailproof.ai/audits/overview) | Encuentra patrones de fallo en múltiples sesiones | -| [Panel local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sin necesidad de cuenta | +| [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) | Qué te está diciendo el grafo de ejecución | +| [Auditorías](https://docs.befailproof.ai/audits/overview) | Encontrar patrones de fallo en muchas sesiones | +| [Panel local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sin cuenta necesaria | -| Aplicar controles | | +| Controlar | | |---|---| | [Políticas integradas](https://docs.befailproof.ai/policies/builtin) | Las 40 políticas con sus parámetros | -| [Políticas personalizadas](https://docs.befailproof.ai/policies/custom) | Escribe las tuyas propias | +| [Políticas personalizadas](https://docs.befailproof.ai/policies/custom) | Escribe las tuyas | | [Configuración](https://docs.befailproof.ai/policies/local-configuration) | Ámbitos de configuración y reglas de fusión | -| Instrumenta tu propio agente | | +| Instrumentar tu propio agente | | |---|---| -| [SDK de Python](https://docs.befailproof.ai/reference/python-sdk) | Reporta ejecuciones desde un agente sin entorno | +| [SDK de Python](https://docs.befailproof.ai/reference/custom-agents) | Reportar ejecuciones desde un agente sin entorno propio | | [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 aparte. Consulta [LICENSE](../../LICENSE) para el texto completo. +MIT con [Commons Clause](https://commonsclause.com/) — gratuito 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). Se aceptan nuevas políticas, casos límite y traducciones. +Consulta [CONTRIBUTING.md](../../CONTRIBUTING.md). Se aceptan con gusto nuevas políticas, casos límite y traducciones. -> **Compila antes de empezar.** Ejecuta primero `bun install && bun run build`. 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 previa obtendrás errores de hook `Cannot find package 'failproofai'`. Vuelve a compilar tras modificar `src/`. Consulta [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Compila antes de empezar.** Ejecuta primero `bun install && bun run build`. Este repositorio ejecuta sus propios hooks de failproofai sobre sí mismo, y resuelven la importación de `failproofai` contra el bundle compilado en `dist/` — sin una compilación previa obtendrás errores de hook `Cannot find package 'failproofai'`. Recompila tras modificar `src/`. Consulta [Compila antes de que funcionen los hooks de desarrollo del repositorio](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Creado con ❤️ por [befailproof.ai](https://befailproof.ai) en SF y Bengaluru. +Construido con ❤️ por [befailproof.ai](https://befailproof.ai) en SF y Bengaluru. diff --git a/docs/i18n/README.fr.md b/docs/i18n/README.fr.md index 309ea5575..5e1aa4673 100644 --- a/docs/i18n/README.fr.md +++ b/docs/i18n/README.fr.md @@ -21,7 +21,7 @@ **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'exécution 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 — en capturant chaque exécution et en bloquant les appels d'outils dangereux avant qu'ils ne s'effectuent. 40 politiques intégrées. Aucune latence. Fonctionne en local. +Où que vos agents s'exécutent, nous le voyons — et nous pouvons dire non. Failproof s'intègre à 12 environnements d'exécution 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 — en capturant chaque exécution et en bloquant les appels d'outils dangereux avant qu'ils ne s'exécutent. 40 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 d'exécution pris en charge -Douze environnements répartis en deux catégories — dix CLI de développement, et deux passerelles de chat et d'assistant (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 d'exécution en deux catégories — dix CLI de développement, et deux passerelles de chat et d'assistant (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. -Les agents qui n'utilisent aucun d'entre eux peuvent remonter leurs données via le [SDK Python](https://docs.befailproof.ai/reference/python-sdk), qui vous offre le traçage, la gestion des sessions et les audits. L'application des politiques dans ce cas nécessite un hook dans votre propre environnement d'exécution — [contactez-nous](mailto:support@befailproof.ai) et nous l'adapterons ensemble. +Les agents qui ne s'exécutent dans aucun d'eux envoient leurs données via le [SDK Python](https://docs.befailproof.ai/reference/custom-agents), qui vous offre le traçage, la gestion des sessions et les audits. L'application des politiques dans ce cas nécessite un hook dans votre propre runtime — [contactez-nous](mailto:support@befailproof.ai) et nous l'adapterons. {/* 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 @@ -145,18 +145,18 @@ failproofai ## Ce que ça bloque -| Politique | Ce qui est bloqué | +| 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 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 condition | -| `block-terraform` / `block-kubectl` | Les modifications non vérifiées d'une infrastructure en production | +| `block-terraform` / `block-kubectl` | Les modifications non examinées sur l'infrastructure en production | | `block-rm-rf` | La suppression récursive de fichiers | -| `block-force-push` / `block-push-master` | `git push --force`, les push directs vers `main` | +| `block-force-push` / `block-push-master` | `git push --force`, les pushs directs vers `main` | -Les cinq 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 sont la catégorie d'environnement que nous couvrons le plus en profondeur. +Les cinq 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 sont la catégorie d'environnements que nous couvrons le plus en profondeur. → [Les 40 politiques intégrées](https://docs.befailproof.ai/policies/builtin) @@ -164,8 +164,8 @@ Les cinq premières s'appliquent à tout agent capable d'appeler un outil. Les t ## Vos propres politiques -Déposez un fichier dans `.failproofai/policies/` — il se charge automatiquement, sans aucun paramètre. -Commitez-le et toute l'équipe en bénéficie au prochain pull. +Déposez un fichier dans `.failproofai/policies/` — il se charge automatiquement, sans aucun flag. +Commitez-le et toute l'équipe en bénéficie dès le prochain pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -187,7 +187,7 @@ 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) @@ -195,15 +195,15 @@ Trois décisions disponibles pour chaque politique : ## Observabilité -L'application des politiques n'est qu'une moitié du tableau. L'autre moitié, c'est de voir ce que l'agent a réellement fait. +L'application des politiques n'est qu'une moitié. L'autre moitié consiste à voir ce que l'agent a réellement fait. -Lancez `failproofai` sans arguments et il sert un tableau de bord sur `localhost:8020` qui lit l'historique des exécutions déjà présent sur votre machine — sans compte, sans inscription, sans rien quitter votre poste. Vous obtenez la liste des sessions, la séquence des appels au modèle, les appels d'outils et les décisions des hooks dans chaque exécution, ce qui a été bloqué et ce que la politique a communiqué à 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 y remédier. +Lancez `failproofai` sans argument et il sert un tableau de bord sur `localhost:8020` en lisant l'historique d'exécution déjà présent sur votre machine — sans compte, sans inscription, sans rien quitter votre poste. Vous obtenez la liste des sessions, la séquence des appels de modèles, les appels d'outils et les décisions de hook à l'intérieur de chaque exécution, ce qui a été bloqué et ce que la politique a dit à l'agent, ainsi qu'un audit hors ligne (`failproofai audit`) qui analyse votre historique à la recherche de patterns risqués et suggère des politiques pour les arrêter. → [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 de machines : toutes les exécutions de tous les environnements au même 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, des requêtes SQL sur vos propres traces avec des tableaux de bord partageables, des évaluations scoré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 dans le plan Enterprise. +**Failproof AI Observability** est la version hébergée du même modèle de données, pour les équipes qui exécutent des agents sur une flotte : 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 du coût 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 conclusions étayées 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 avec le plan Enterprise. → [Sessions](https://docs.befailproof.ai/sessions/overview) · [Audits](https://docs.befailproof.ai/audits/overview) · @@ -213,9 +213,9 @@ Lancez `failproofai` sans arguments 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 d'exécution, voir la première exécution | +| [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 | | [Environnements pris en charge](https://docs.befailproof.ai/reference/harnesses) | Les 12 environnements et ce que chacun peut appliquer | @@ -223,19 +223,19 @@ Lancez `failproofai` sans arguments et il sert un tableau de bord sur `localhost |---|---| | [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 indique | -| [Audits](https://docs.befailproof.ai/audits/overview) | Identifier des schémas d'échec sur de nombreuses sessions | -| [Tableau de bord local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sans compte requis | +| [Audits](https://docs.befailproof.ai/audits/overview) | Identifier les patterns d'échec sur de nombreuses sessions | +| [Tableau de bord local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sans compte nécessaire | -| Appliquer des politiques | | +| Appliquer | | |---|---| | [Politiques intégrées](https://docs.befailproof.ai/policies/builtin) | Les 40 politiques avec leurs paramètres | -| [Politiques personnalisées](https://docs.befailproof.ai/policies/custom) | Écrivez les vô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 | | Instrumenter votre propre agent | | |---|---| -| [SDK Python](https://docs.befailproof.ai/reference/python-sdk) | Remonter les exécutions d'un agent sans environnement dédié | -| [SDK de politique](https://docs.befailproof.ai/reference/policy-sdk) | Référence `allow` / `deny` / `instruct` | +| [SDK Python](https://docs.befailproof.ai/reference/custom-agents) | Rapporter les exécutions d'un agent sans environnement d'exécution | +| [SDK de politiques](https://docs.befailproof.ai/reference/policy-sdk) | Référence `allow` / `deny` / `instruct` | --- @@ -247,11 +247,11 @@ MIT avec [Commons Clause](https://commonsclause.com/) — gratuit pour un usage ## Contribuer -Consultez [CONTRIBUTING.md](../../CONTRIBUTING.md). Les nouvelles politiques, les cas limites et les traductions sont les bienvenus. +Voir [CONTRIBUTING.md](../../CONTRIBUTING.md). Nouvelles politiques, cas limites et traductions sont les bienvenus. -> **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 +> **Compilez avant de commencer.** Exécutez d'abord `bun install && bun run build`. Ce dépôt fait tourner les propres hooks de failproofai sur lui-même, et ils résolvent l'import `failproofai` par rapport au bundle `dist/` compilé — 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) à SF et Bengaluru. +Fait 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 6c8f9aef7..d19bb49c8 100644 --- a/docs/i18n/README.he.md +++ b/docs/i18n/README.he.md @@ -22,8 +22,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 כלים לסוכנים — ממשקי שורת פקודה לקידוד כמו Claude Code ו־Codex, שערי צ'אט כמו Hermes, עוזרים בעצמם מתארחים כמו OpenClaw — לוכדים כל הרצה וחוסמים קריאות כלים מסוכנות לפני שהן מתבצעות. 40 מדיניויות מובנות. אפס עיכוב. פועל ברמה מקומית. +**ניטור והטלת אכיפה לכל קוסם שהסוכנים שלך רצים בו.** +איפה שהסוכנים שלך רצים, אנחנו רואים את זה — ואנחנו יכולים להגיד לא. Failproof מתחבר ל-12 קוסמים של סוכנים — ממשקי שורת פקודה לקידוד כמו Claude Code ו-Codex, שערי צ'אט כמו Hermes, עוזרים ממוחזקים עצמאיים כמו OpenClaw — תופסים כל הרצה וחוסמים קריאות כלים מסוכנות לפני שהן מתבצעות. 40 מדיניות מובנות. זמן אפס. רץ בעמדה מקומית. @@ -33,11 +33,12 @@ --- -## כלים נתמכים +## קוסמים נתמכים -שנים עשר כלים בשתי מחלקות — עשרה ממשקי שורת פקודה לקידוד, ושתי שערי צ'אט ועוזרים (Hermes, OpenClaw). אותם אירועים, אותן מדיניויות, אותו היסטוריון הפעלה, בכל אחד מהם שהסוכן פועל בו. +שנים עשר קוסמים בשתי מחלקות — עשרה ממשקי שורת פקודה לקידוד, ושני שערי צ'אט ועוזרים (Hermes, OpenClaw). אותם האירועים, אותן המדיניויות, אותו ההיסטוריה של הפגישה, בכל אחד מהקוסמים שהסוכן שלך רץ בו. -סוכנים שפועלים ללא קשר לאחד מהם מדווחים דרך ה־[Python SDK](https://docs.befailproof.ai/reference/python-sdk), המספק לך עקיבה, הפעלות וביקורות. הגבור שם דורש וו בסביבת הריצה שלך — [דברו אתנו](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 @@ -137,11 +138,11 @@ ```sh npm install -g failproofai -failproofai policies --install # או פשוט הריצו `failproofai` וקבלו את ההנחיה בהתחלה הראשונה +failproofai policies --install failproofai ``` -40 מדיניויות מובנות פעילות מיד. לוח תצוגה ב־`localhost:8020`. השבית את הנחיית ההתחלה הראשונה עם `FAILPROOFAI_NO_FIRST_RUN=1`. +40 מדיניויות מובנות מופעלות מיידית. לוח בקרה ב-`localhost:8020`. השבת את הנושא בהרצה ראשונה עם `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -149,16 +150,16 @@ failproofai | מדיניות | מה היא חוסמת | |---|---| -| `sanitize-api-keys` | דליפת מפתחות API להקשר של הסוכן | +| `sanitize-api-keys` | מפתחות API שדולפים להקשר של הסוכן | | `block-env-files` | קריאות של קבצי `.env` וקבצי סודות אחרים | -| `warn-repeated-tool-calls` | הסוכן לולאה על אותה קריאה | -| `block-sudo` | הסלקלציה של הרשאות | +| `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-terraform` / `block-kubectl` | שינויים ללא ביקורת לתשתית חיה | +| `block-rm-rf` | מחיקה רקורסיבית של קבצים | +| `block-force-push` / `block-push-master` | `git push --force`, דחיפה ישירה ל-`main` | -חמשת הראשונות חלות על כל סוכן שיכול לקרוא כלי. שלוש האחרונות הן המועדפות של המפתחים — ממשקי שורת פקודה לקידוד הם מחלקת הכלים שאנחנו מכסים הכי עמוק. +חמשת הראשונים חלים על כל סוכן שיכול לקרוא לכלי. השלוש אחרונות הן אהובות על המפתחים — ממשקי שורת פקודה לקידוד הם מחלקת הקוסם שאנחנו מכסים את העומק ביותר. → [כל 40 המדיניויות המובנות](https://docs.befailproof.ai/policies/builtin) @@ -166,8 +167,8 @@ failproofai ## המדיניויות שלך -זרוק קובץ ל־`.failproofai/policies/` — הוא נטען באופן אוטומטי, ללא צורך בדגלים. -בצע commit וכל הצוות שלך מקבל זאת בעדכון הבא. +שחרר קובץ ל-`.failproofai/policies/` — הוא טוען באופן אוטומטי, אין צורך בדגלים. +העלו את זה והצוות כולו מקבל את זה בשלימת הבא. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -188,75 +189,90 @@ customPolicies.add({ | החלטה | השפעה | |---|---| | `allow()` | אפשר את הפעולה | -| `deny(message)` | חסום אותה — ההודעה חוזרת לסוכן | -| `instruct(message)` | תן לזה להעבור, אבל הוסף הקשר להנחיה הבאה של הסוכן | +| `deny(message)` | חסום את זה — ההודעה חוזרת לסוכן | +| `instruct(message)` | תן את זה דרך, אבל הוסף הקשר להנמקה הבאה של הסוכן | -→ [מדריך מדיניויות מותאם אישית](https://docs.befailproof.ai/policies/custom) +→ [מדריך מדיניויות מותאמות](https://docs.befailproof.ai/policies/custom) --- -## ניהול +## ניטור -הגבור הוא חצי אחד. החצי השני הוא לראות מה הסוכן בעצם עשה. +אכיפה היא חצי אחד. החצי השני הוא לראות מה הסוכן בעצם עשה. -הריצו `failproofai` ללא ארגומנטים והוא משרת לוח תצוגה ב־`localhost:8020` קורא את היסטוריית ההרצה שכבר על המכונה שלך — ללא חשבון, ללא הרשמה, שום דבר לא עוזב את התיבה. אתה מקבל את רשימת ההפעלות, את רצף קריאות המודל, קריאות כלים והחלטות וו בתוך כל הרצה, מה היה חסום ומה אמרה המדיניות לסוכן, וביקורת offline (`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/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 חתום. Self-hosting בקלסטר שלך זמין בתוכנית Enterprise. +**Failproof AI Observability** היא הצד המארח של אותו מודל נתונים, לצוותים +המריצים סוכנים על פני צי: כל ריצה מכל קוסם במקום אחד, גרף ביצוע עם תת-סוכנים מקבילים +בנתיבים שלהם, זמן פעולה p50/p95/p99 לדגמים, כלים וקרסים, +עלות לכל דגם ועקבוב חלון הקשר, עקבוב שגיאות, SQL על העקבות שלך +עם לוחות בקרה ניתנים לשיתוף, הערכות המדורגות על ידי השירות שלך, +ביקורות מתוזמנות המהפכות כשלים חוזרים לממצאים המבוססים על עדויות, +והתנעות המנותבות ל-Slack, דוא"ל או webhook חתום. אירוח עצמי בקבוצה שלך +זמין בתוכנית 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) --- ## תיעוד -| התחלה | | +| התחל | | |---|---| -| [התחלה מהירה](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) | כל 40 המדיניויות עם פרמטרים | -| [מדיניויות מותאם אישית](https://docs.befailproof.ai/policies/custom) | כתוב שלך | -| [קביעת תצורה](https://docs.befailproof.ai/policies/local-configuration) | ההיקפים ותכניות ההתמזגות | +| [מדיניויות מותאמות](https://docs.befailproof.ai/policies/custom) | כתוב שלך | +| [תצורה](https://docs.befailproof.ai/policies/local-configuration) | טווחי תצורה וכללי מיזוג | -| תאם את הסוכן שלך | | +| הנתק את הסוכן שלך | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | דוח הרצות מסוכן ללא כלי | -| [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` ראשית. מאגר זה מריץ את הווים שלו בעצמו עליו, והם פותרים את ה־import של failproofai כנגד ה־bundle של `dist/` המורכב — ללא בנייה תפגע ב־`Cannot find package 'failproofai'` שגיאות וו. בנה מחדש לאחר שינוי `src/`. ראה -> [בנה לפני שהווים הפיתוח בתוך-מאגר יעבדו](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **בנה לפני שתתחיל.** הרץ `bun install && bun run build` תחילה. ריפו זה מריץ +> את הקרסים שלו על עצמו, והם פותרים את ה-`failproofai` import מול +> ה-`dist/` bundle המורכב — ללא בנייה תפגע בשגיאות קרס `Cannot find package 'failproofai'`. +> בנה מחדש לאחר שינוי `src/`. ראה +> [בנה לפני שקרסי dev בתוך הריפו יעבדו](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -בנוי עם ❤️ על ידי [befailproof.ai](https://befailproof.ai) ב־SF וBengaluru. +בנוי עם ❤️ על ידי [befailproof.ai](https://befailproof.ai) ב-SF ו-Bengaluru. \ No newline at end of file diff --git a/docs/i18n/README.hi.md b/docs/i18n/README.hi.md index ac0d45c19..c99c91261 100644 --- a/docs/i18n/README.hi.md +++ b/docs/i18n/README.hi.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) -**आपके एजेंट्स द्वारा चलाए जाने वाले हर हार्नेस के लिए दृश्यमानता और प्रवर्तन।** -आपके एजेंट्स जहां भी चलते हैं, हम उन्हें देखते हैं — और हम मना कर सकते हैं। failproofai 12 एजेंट -हार्नेस को हुक करता है — Claude Code और Codex जैसे कोडिंग CLIs, Hermes जैसे चैट गेटवे, -OpenClaw जैसे self-hosted असिस्टेंट — हर रन को कैप्चर करता है और खतरनाक -टूल कॉल्स को निष्पादन से पहले ब्लॉक करता है। 40 बिल्ट-इन नीतियां। शून्य लेटेंसी। स्थानीय रूप से चलता है। +**हर harness के लिए निरीक्षण और प्रवर्तन जहाँ आपके agents चलते हैं।** +जहाँ भी आपके agents चलते हैं, हम देख सकते हैं — और हम मना कर सकते हैं। Failproof 12 agent +harnesses को hook करता है — Claude Code और Codex जैसे coding CLIs, Hermes जैसे chat +gateways, OpenClaw जैसे self-hosted assistants — हर run को capture करता है और +खतरनाक tool calls को execute होने से पहले रोकता है। 40 built-in policies। Zero latency। Locally चलता है। @@ -34,15 +34,15 @@ OpenClaw जैसे self-hosted असिस्टेंट — हर रन --- -## समर्थित हार्नेस +## समर्थित harnesses -दो वर्गों में बारह हार्नेस — दस कोडिंग CLIs, और दो चैट और असिस्टेंट -गेटवे (Hermes, OpenClaw)। एक ही ईवेंट्स, एक ही नीतियां, एक ही सेशन हिस्ट्री, -चाहे आपका एजेंट किसी में भी चले। +दो classes में बारह harnesses — दस coding CLIs, और दो chat और assistant +gateways (Hermes, OpenClaw)। एक जैसी events, एक जैसी policies, एक जैसी session history, +चाहे आपका agent उनमें से कोई भी हो। -जो एजेंट्स इनमें से किसी में भी नहीं चलते हैं, वे [Python SDK](https://docs.befailproof.ai/reference/python-sdk) के माध्यम से रिपोर्ट करते हैं, -जो आपको ट्रेसिंग, सेशन और ऑडिट देता है। वहां प्रवर्तन के लिए -आपके अपने रनटाइम में एक हुक की आवश्यकता है — [हमसे संपर्क करें](mailto:support@befailproof.ai) और हम इसे मैप कर देंगे। +Agents जो इनमें से किसी में भी नहीं चलते वे [Python SDK](https://docs.befailproof.ai/reference/custom-agents) के +माध्यम से report करते हैं, जो आपको tracing, sessions और audits देता है। वहाँ प्रवर्तन के लिए आपके +own 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 @@ -138,42 +138,42 @@ OpenClaw जैसे self-hosted असिस्टेंट — हर रन -## इंस्टॉल करें +## स्थापना ```sh npm install -g failproofai -failproofai policies --install # या सिर्फ `failproofai` चलाएं और पहली बार के प्रॉम्प्ट को स्वीकार करें +failproofai policies --install # या बस `failproofai` चलाएँ और पहली बार के प्रॉम्प्ट को स्वीकार करें failproofai ``` -40 बिल्ट-इन नीतियां तुरंत सक्रिय हो जाती हैं। डैशबोर्ड `localhost:8020` पर। `FAILPROOFAI_NO_FIRST_RUN=1` के साथ पहली बार के प्रॉम्प्ट को अक्षम करें। +40 built-in policies तुरंत सक्रिय हो जाती हैं। Dashboard `localhost:8020` पर है। पहली बार के प्रॉम्प्ट को `FAILPROOFAI_NO_FIRST_RUN=1` से अक्षम करें। --- ## यह क्या रोकता है -| नीति | यह क्या ब्लॉक करता है | +| Policy | क्या यह ब्लॉक करता है | |---|---| -| `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` में पुश | +| `sanitize-api-keys` | API keys का agent के context में leak होना | +| `block-env-files` | `.env` और अन्य secret files का read होना | +| `warn-repeated-tool-calls` | Agent का एक ही call पर loop करना | +| `block-sudo` | Privilege escalation | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, unbounded `DELETE` | +| `block-terraform` / `block-kubectl` | Live infrastructure में unreviewed changes | +| `block-rm-rf` | Recursive file deletion | +| `block-force-push` / `block-push-master` | `git push --force`, `main` को direct pushes | -पहले पाँच किसी भी एजेंट पर लागू होते हैं जो एक टूल कॉल कर सकता है। अंतिम तीन -डेवलपर के पसंदीदा हैं — कोडिंग CLIs हार्नेस क्लास है जिसे हम सबसे गहराई से कवर करते हैं। +पहली पाँच किसी भी agent पर लागू होती हैं जो एक tool को call कर सकता है। अंतिम तीन +developer पसंदीदा हैं — coding CLIs वह harness class हैं जिसे हम सबसे गहराई से cover करते हैं। -→ [सभी 40 बिल्ट-इन नीतियां](https://docs.befailproof.ai/policies/builtin) +→ [सभी 40 built-in policies](https://docs.befailproof.ai/policies/builtin) --- -## आपकी अपनी नीतियां +## आपकी अपनी policies -`.failproofai/policies/` में एक फ़ाइल रखें — यह स्वचालित रूप से लोड हो जाती है, कोई फ्लैग की आवश्यकता नहीं। -इसे कमिट करें और पूरी टीम को अगले पुल में मिल जाएगी। +`.failproofai/policies/` में एक फाइल डालें — यह automatically load हो जाती है, कोई flags की जरूरत नहीं। +इसे commit करें और पूरी team को अगले pull पर यह मिल जाएगी। ```js import { customPolicies, deny, allow } from "failproofai"; @@ -189,77 +189,90 @@ customPolicies.add({ }); ``` -तीन निर्णय हर नीति के लिए उपलब्ध हैं: +हर policy के लिए तीन निर्णय उपलब्ध हैं: | निर्णय | प्रभाव | |---|---| -| `allow()` | ऑपरेशन को अनुमति दें | -| `deny(message)` | इसे ब्लॉक करें — संदेश एजेंट को वापस जाता है | -| `instruct(message)` | इसे आगे बढ़ने दें, लेकिन एजेंट के अगले प्रॉम्प्ट में संदर्भ जोड़ें | +| `allow()` | Operation को permit करें | +| `deny(message)` | इसे ब्लॉक करें — message agent को वापस जाता है | +| `instruct(message)` | इसे through होने दें, लेकिन agent के अगले prompt में context जोड़ें | -→ [कस्टम नीतियां गाइड](https://docs.befailproof.ai/policies/custom) +→ [Custom policies guide](https://docs.befailproof.ai/policies/custom) --- -## दृश्यमानता +## निरीक्षण -प्रवर्तन एक आधा है। दूसरा आधा यह देखना है कि एजेंट ने वास्तव में क्या किया। +प्रवर्तन एक आधा है। दूसरा आधा यह देखना है कि agent ने वास्तव में क्या किया। -`failproofai` को बिना किसी आर्गुमेंट के चलाएं और यह आपकी मशीन पर पहले से मौजूद रन हिस्ट्री को पढ़ते हुए `localhost:8020` पर एक डैशबोर्ड सर्व करता है — कोई खाता नहीं, कोई साइन अप नहीं, कुछ भी बॉक्स से बाहर नहीं जाता। आपको सेशन सूची, प्रत्येक रन के अंदर मॉडल कॉल्स, टूल कॉल्स और हुक निर्णयों का क्रम, क्या ब्लॉक किया गया और नीति ने एजेंट को क्या बताया, और एक ऑफलाइन ऑडिट (`failproofai audit`) मिलता है जो आपकी हिस्ट्री को जोखिमपूर्ण पैटर्न के लिए स्कैन करता है और उन्हें रोकने के लिए नीतियों का सुझाव देता है। +बिना किसी argument के `failproofai` चलाएँ और यह `localhost:8020` पर एक dashboard serve करता है +जो आपकी machine पर पहले से मौजूद run history को read करता है — कोई account नहीं, कोई signup नहीं, कुछ भी +बाहर नहीं जाता। आपको session list, हर run के अंदर model calls, tool calls और hook decisions का sequence, +क्या block किया गया और policy ने agent को क्या बताया, और एक offline audit (`failproofai audit`) जो +आपके history को risky patterns के लिए scan करता है और policies सुझाता है उन्हें रोकने के लिए। -→ [स्थानीय डैशबोर्ड](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 Observability** एक पूरे फ्लीट में एजेंट्स चलाने वाली टीमों के लिए एक ही डेटा मॉडल का होस्टेड पक्ष है: हर हार्नेस से हर रन एक ही स्थान पर, समानांतर sub-agents अपनी अपनी लेन पर एक एक्सीक्यूशन ग्राफ, मॉडल्स, टूल्स और हुक्स के लिए p50/p95/p99 लेटेंसी, प्रति-मॉडल कॉस्ट और कॉन्टेक्स्ट-विंडो ट्रैकिंग, एरर ट्रैकिंग, आपके अपने ट्रेस पर SQL साझा योग्य डैशबोर्ड के साथ, आपकी अपनी सेवा द्वारा स्कोर किए गए मूल्यांकन, शेड्यूल किए गए ऑडिट जो आवर्ती विफलताओं को साक्ष्य-समर्थित निष्कर्षों में बदलते हैं, और Slack, ईमेल या एक हस्ताक्षरित वेबहुक पर रूट किए गए अलर्ट। Enterprise प्लान पर आपके अपने क्लस्टर में self-hosting उपलब्ध है। +**Failproof AI Observability** एक team के लिए hosted side है जो एक fleet में agents चला रहे हैं: +हर harness से हर run एक ही जगह, parallel sub-agents के अपने lanes के साथ एक execution graph, +models, tools और hooks के लिए p50/p95/p99 latency, per-model cost और context-window tracking, error +tracking, आपके own traces पर SQL shareable dashboards के साथ, आपकी own service द्वारा scored +evaluations, scheduled audits जो recurring failures को evidence-backed findings में turn करते हैं, +और alerts जो Slack, email या एक signed webhook को route करते हैं। आपके own cluster में self-hosting +Enterprise plan पर उपलब्ध है। -→ [सेशन](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) | सभी 40 नीतियां पैरामीटर के साथ | -| [कस्टम नीतियां](https://docs.befailproof.ai/policies/custom) | अपनी खुद की लिखें | -| [कॉन्फ़िगरेशन](https://docs.befailproof.ai/policies/local-configuration) | कॉन्फ़िग स्कोप और मर्ज नियम | +| [Built-in policies](https://docs.befailproof.ai/policies/builtin) | सभी 40 policies parameters के साथ | +| [Custom policies](https://docs.befailproof.ai/policies/custom) | अपनी खुद की policies लिखें | +| [Configuration](https://docs.befailproof.ai/policies/local-configuration) | Config scopes और merge rules | -| अपने एजेंट को इंस्ट्रूमेंट करें | | +| अपने agent को instrument करें | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | कोई हार्नेस नहीं वाले एजेंट से रन रिपोर्ट करें | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` संदर्भ | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | कोई harness वाले agent से runs report करें | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` reference | --- ## लाइसेंस -MIT with [Commons Clause](https://commonsclause.com/) — आंतरिक और व्यक्तिगत उपयोग के लिए मुक्त; failproofai के वाणिज्यिक पुनर्विक्रय के लिए एक अलग समझौते की आवश्यकता है। पूर्ण पाठ के लिए [LICENSE](../../LICENSE) देखें। +MIT with [Commons Clause](https://commonsclause.com/) — internal और personal use के लिए free; failproofai +के commercial resale के लिए एक separate agreement की जरूरत है। पूरे text के लिए [LICENSE](../../LICENSE) देखें। --- ## योगदान -[CONTRIBUTING.md](../../CONTRIBUTING.md) देखें। नई नीतियां, edge cases, और अनुवाद सभी स्वागत हैं। +[CONTRIBUTING.md](../../CONTRIBUTING.md) देखें। नई policies, edge cases, और translations सभी स्वागत हैं। -> **शुरू करने से पहले बिल्ड करें।** पहले `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)। +> **शुरू करने से पहले build करें।** पहले `bun install && bun run build` चलाएँ। यह repo failproofai की अपनी +> hooks को अपने पर चलाता है, और वे `failproofai` import को compiled `dist/` bundle के विरुद्ध resolve करते हैं — +> build के बिना आपको `Cannot find package 'failproofai'` hook errors का सामना करना पड़ेगा। `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) द्वारा ❤️ के साथ बनाया गया। +SF और Bengaluru में [befailproof.ai](https://befailproof.ai) द्वारा ❤️ के साथ built। diff --git a/docs/i18n/README.it.md b/docs/i18n/README.it.md index 76e3ef06b..249498bdc 100644 --- a/docs/i18n/README.it.md +++ b/docs/i18n/README.it.md @@ -20,26 +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 harness su cui i tuoi agenti vengono eseguiti.** -Ovunque i tuoi agenti vengono eseguiti, noi lo vediamo — e possiamo dire di no. Failproof si aggancia a 12 harness per agenti — CLI di codifica come Claude Code e Codex, gateway di chat come Hermes, assistenti self-hosted come OpenClaw — acquisendo ogni esecuzione e bloccando le chiamate agli strumenti pericolose prima che vengano eseguite. 40 politiche integrate. Zero latenza. Eseguito localmente. +**Osservabilità e applicazione per ogni esecuzione dei tuoi agenti.** +Ovunque gli agenti vengono eseguiti, noi li vediamo — e possiamo dire di no. Failproof si aggancia a 12 ambienti di esecuzione per agenti — CLI di codifica come Claude Code e Codex, gateway di chat come Hermes, assistenti self-hosted come OpenClaw — catturando ogni esecuzione e bloccando le chiamate di strumenti pericolose prima che vengano eseguite. 40 politiche integrate. Latenza zero. Esecuzione locale.

- Failproof AI in azione + Failproof AI in action

--- -## Harness supportati +## Ambienti di esecuzione supportati -Dodici harness in due categorie — dieci CLI di codifica e due gateway di chat e assistenti -(Hermes, OpenClaw). Gli stessi eventi, le stesse politiche, la stessa cronologia delle sessioni, -indipendentemente da quale harness il tuo agente esegue. +Dodici ambienti in due categorie — dieci CLI di codifica e due gateway di chat e assistenti (Hermes, OpenClaw). Gli stessi eventi, le stesse politiche, la stessa cronologia delle sessioni, indipendentemente da quale ambiente il tuo agente utilizza. -Gli agenti che non vengono eseguiti in nessuno di questi reportano tramite l'[SDK Python](https://docs.befailproof.ai/reference/python-sdk), -che ti offre tracciamento, sessioni e audit. L'applicazione dei criteri richiede un hook nel -tuo runtime — [contattaci](mailto:support@befailproof.ai) e lo mapperemo. +Gli agenti che non vengono eseguiti in nessuno di questi si collegano tramite l'[SDK Python](https://docs.befailproof.ai/reference/custom-agents), che ti offre tracciamento, sessioni e audit. L'applicazione 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 @@ -139,11 +135,11 @@ tuo runtime — [contattaci](mailto:support@befailproof.ai) e lo mapperemo. ```sh npm install -g failproofai -failproofai policies --install # oppure esegui semplicemente `failproofai` e accetta il prompt al primo avvio +failproofai policies --install # oppure esegui `failproofai` e accetta il prompt al primo avvio failproofai ``` -40 politiche integrate si attivano immediatamente. Dashboard disponibile su `localhost:8020`. Disabilita il prompt al primo avvio con `FAILPROOFAI_NO_FIRST_RUN=1`. +40 politiche integrate si attivano immediatamente. Dashboard su `localhost:8020`. Disabilita il prompt al primo avvio con `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -151,25 +147,24 @@ failproofai | Politica | Cosa blocca | |---|---| -| `sanitize-api-keys` | Chiavi API che fuoriescono nel contesto dell'agente | +| `sanitize-api-keys` | Perdite 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 blocca sulla stessa chiamata | -| `block-sudo` | Escalation di privilegi | +| `block-sudo` | Escalation dei privilegi | | `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` illimitati | -| `block-terraform` / `block-kubectl` | Modifiche non revisionate all'infrastruttura live | -| `block-rm-rf` | Eliminazione ricorsiva di file | +| `block-terraform` / `block-kubectl` | Modifiche non riviste all'infrastruttura in produzione | +| `block-rm-rf` | Cancellazione 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 può chiamare uno strumento. Gli ultimi tre sono i preferiti -degli sviluppatori — le CLI di codifica sono la classe di harness che copriamo più a fondo. +I primi cinque si applicano a qualsiasi agente che possa chiamare uno strumento. Gli ultimi tre sono i preferiti dagli sviluppatori — le CLI di codifica sono la categoria di ambienti che copriamo più a fondo. -→ [Tutte le 40 politiche integrate](https://docs.befailproof.ai/policies/builtin) +→ [Tutte e 40 le politiche integrate](https://docs.befailproof.ai/policies/builtin) --- -## Le tue politiche personalizzate +## Le tue politiche personali -Deposita un file in `.failproofai/policies/` — si carica automaticamente, nessun flag necessario. +Rilascia un file in `.failproofai/policies/` — si carica automaticamente, non servono flag. Eseguine il commit e l'intero team lo riceverà al prossimo pull. ```js @@ -180,7 +175,7 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Le scritture su percorsi di produzione sono bloccate."); + return deny("Writes to production paths are blocked."); return allow(); }, }); @@ -192,7 +187,7 @@ Tre decisioni disponibili per ogni politica: |---|---| | `allow()` | Consenti l'operazione | | `deny(message)` | Bloccala — il messaggio torna all'agente | -| `instruct(message)` | Lasciarla passare, ma aggiungere contesto al prossimo prompt dell'agente | +| `instruct(message)` | Lasciala passare, ma aggiungi contesto al prossimo prompt dell'agente | → [Guida alle politiche personalizzate](https://docs.befailproof.ai/policies/custom) @@ -200,26 +195,15 @@ Tre decisioni disponibili per ogni politica: ## Osservabilità -L'applicazione dei criteri è una parte. L'altra parte è vedere cosa ha effettivamente fatto l'agente. +L'applicazione è una metà. L'altra metà è vedere cosa ha veramente fatto l'agente. -Esegui `failproofai` senza argomenti e servirà un dashboard su `localhost:8020` -leggendo la cronologia delle esecuzioni già presente sulla tua macchina — nessun account, nessuna iscrizione, nulla -che lascia il box. Ottieni l'elenco delle sessioni, la sequenza di chiamate ai modelli, chiamate agli strumenti -e decisioni degli hook all'interno di ogni esecuzione, cosa è stato bloccato e cosa la politica ha detto -all'agente, e un audit offline (`failproofai audit`) che scansiona la tua cronologia per -modelli rischiosi e suggerisce politiche per fermarli. +Esegui `failproofai` senza argomenti e servirà un dashboard su `localhost:8020` leggendo la cronologia delle esecuzioni già presente sulla tua macchina — nessun account, nessuna registrazione, nulla che esce dal sistema. Ottieni l'elenco delle sessioni, la sequenza di chiamate di modello, chiamate di strumenti e decisioni di hook all'interno di ogni esecuzione, cosa è stato bloccato e cosa la politica ha detto all'agente, e un audit offline (`failproofai audit`) che scansiona la tua cronologia per modelli rischiosi e suggerisce politiche per bloccarli. → [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 ospitato dello stesso modello di dati, per i team -che eseguono agenti in un fleet: ogni esecuzione da ogni harness in un unico posto, un -grafico di esecuzione con sub-agenti paralleli su corsie proprie, latenza p50/p95/p99 -per modelli, strumenti e hook, costo per modello e tracciamento della finestra di contesto, tracciamento degli errori, SQL sulle tue tracce -con dashboard condivisibili, valutazioni valutate dal tuo servizio, audit programmati che trasformano i fallimenti -ricorrenti in risultati supportati da prove, e avvisi instradati a Slack, email o un webhook firmato. L'auto-hosting nel tuo -cluster è disponibile nel piano Enterprise. +**Failproof AI Observability** è il lato ospitato dello stesso modello di dati, per team che eseguono agenti su una flotta: ogni esecuzione da ogni ambiente in un unico posto, un grafo di esecuzione con sub-agenti paralleli sui propri percorsi, latenza p50/p95/p99 per modelli, strumenti e hook, costo 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 i fallimenti ricorrenti in risultati basati su prove, e avvisi instradati a Slack, email o un 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) · @@ -229,17 +213,17 @@ cluster è disponibile nel piano Enterprise. ## Documentazione -| Inizia | | +| Inizio | | |---|---| -| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Installa, connetti un harness, vedi la prima esecuzione | +| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Installa, connetti un ambiente, vedi la prima esecuzione | | [Concetti](https://docs.befailproof.ai/start/concepts) | Come funziona il sistema di hook | -| [Harness supportati](https://docs.befailproof.ai/reference/harnesses) | Tutti i 12 e cosa ciascuno può applicare | +| [Ambienti di esecuzione supportati](https://docs.befailproof.ai/reference/harnesses) | Tutti e 12, e cosa ciascuno può applicare | | Osserva | | |---|---| | [Sessioni](https://docs.befailproof.ai/sessions/overview) | Segui un'esecuzione: modelli, strumenti, 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 modelli di fallimento in molte sessioni | +| [Leggi una traccia](https://docs.befailproof.ai/sessions/read-a-trace) | Cosa il grafo di esecuzione ti sta dicendo | +| [Audit](https://docs.befailproof.ai/audits/overview) | Trova modelli di fallimento su molte sessioni | | [Dashboard locale](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, nessun account necessario | | Applica | | @@ -250,27 +234,23 @@ cluster è disponibile nel piano Enterprise. | Strumenta il tuo agente | | |---|---| -| [SDK Python](https://docs.befailproof.ai/reference/python-sdk) | Riporta esecuzioni da un agente senza harness | +| [SDK Python](https://docs.befailproof.ai/reference/custom-agents) | Segnala esecuzioni da un agente senza ambiente | | [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Riferimento `allow` / `deny` / `instruct` | --- ## Licenza -MIT con [Commons Clause](https://commonsclause.com/) — gratuito per uso interno e personale; la rivendita commerciale di failproofai richiede un accordo separato. Vedi [LICENSE](../../LICENSE) per il testo completo. +MIT con [Commons Clause](https://commonsclause.com/) — libera per uso interno e personale; la rivendita commerciale di failproofai stesso richiede un accordo separato. Vedi [LICENSE](../../LICENSE) per il testo completo. --- ## Contribuire -Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md). Nuove politiche, casi edge e traduzioni sono tutti benvenuti. +Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md). Nuove politiche, casi limite e traduzioni sono tutti benvenuti. -> **Compila 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'importazione di `failproofai` rispetto al -> bundle compilato `dist/` — senza una build otterrai errori di hook `Cannot find package 'failproofai'`. -> Ricompila dopo aver modificato `src/`. Vedi -> [Compila prima che gli hook di sviluppo in-repo funzionino](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Compila prima di iniziare.** Esegui prima `bun install && bun run build`. Questo repository esegue i propri hook di failproofai su se stesso, e risolvono l'importazione di `failproofai` contro il bundle compilato `dist/` — senza una build avrai errori di 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). --- -Realizzato con ❤️ da [befailproof.ai](https://befailproof.ai) a SF e Bengaluru. +Realizzato con ❤️ da [befailproof.ai](https://befailproof.ai) a San Francisco e Bengaluru. diff --git a/docs/i18n/README.ja.md b/docs/i18n/README.ja.md index 748fc4d9e..f079f001d 100644 --- a/docs/i18n/README.ja.md +++ b/docs/i18n/README.ja.md @@ -8,7 +8,7 @@ failproof ai -FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -18,10 +18,10 @@ [![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://docs.befailproof.ai/) [![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](../../LICENSE) -**翻訳:** [简体中文](../../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) +**翻訳版:** [简体中文](../../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 などのセルフホスト型アシスタントに対応。すべての実行を記録し、危険なツール呼び出しを実行前にブロックします。組み込みポリシー40件。レイテンシーゼロ。ローカルで動作。 +**あらゆるハーネスで動くエージェントに、オブザーバビリティと制御を。** +エージェントがどこで動いていても、Failproofはすべてを把握し、必要なときに「ノー」と言えます。Failproofは12のエージェントハーネスにフックし — Claude Code や Codex などのコーディングCLI、Hermes などのチャットゲートウェイ、OpenClaw などのセルフホスト型アシスタント — すべての実行を記録し、危険なツール呼び出しを実行前にブロックします。40の組み込みポリシー。レイテンシゼロ。ローカル動作。 @@ -33,9 +33,9 @@ ## 対応ハーネス -2カテゴリ12ハーネス — コーディング CLI が10種、チャット・アシスタントゲートウェイ（Hermes、OpenClaw）が2種。エージェントがどのハーネスで動いていても、同一のイベント・ポリシー・セッション履歴が使えます。 +2つのクラスに分かれた12のハーネス — 10のコーディングCLIと、2つのチャット・アシスタントゲートウェイ（Hermes、OpenClaw）。どのハーネスを使っても、同じイベント、同じポリシー、同じセッション履歴が利用できます。 -これらのハーネスをどれも使用しないエージェントは [Python SDK](https://docs.befailproof.ai/reference/python-sdk) 経由でレポートできます。トレーシング・セッション・監査機能を利用可能です。その環境でのエンフォースメントには独自ランタイムへのフック設置が必要です — [お問い合わせ](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,36 +135,36 @@ ```sh npm install -g failproofai -failproofai policies --install # または `failproofai` を実行して初回プロンプトに承諾 +failproofai policies --install # または `failproofai` を実行して初回プロンプトに従うだけでもOK failproofai ``` -40件の組み込みポリシーが即座に有効化されます。ダッシュボードは `localhost:8020` で確認できます。`FAILPROOFAI_NO_FIRST_RUN=1` を設定すると初回プロンプトを無効化できます。 +40の組み込みポリシーが即座に有効化されます。ダッシュボードは `localhost:8020` で確認できます。初回プロンプトを無効にするには `FAILPROOFAI_NO_FIRST_RUN=1` を設定してください。 --- -## ブロックできるもの +## ブロックできる操作 -| ポリシー | ブロック内容 | +| ポリシー | ブロック対象 | |---|---| -| `sanitize-api-keys` | エージェントのコンテキストへの APIキー漏洩 | +| `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-terraform` / `block-kubectl` | 本番インフラへの未レビュー変更 | | `block-rm-rf` | 再帰的なファイル削除 | | `block-force-push` / `block-push-master` | `git push --force`、`main` への直接プッシュ | -最初の5件はツール呼び出し可能なすべてのエージェントに適用されます。残りの3件は開発者に特に人気があり、コーディング CLI はもっとも深くカバーしているハーネスクラスです。 +最初の5つはツールを呼び出せるあらゆるエージェントに適用されます。残りの3つは開発者に特に人気のポリシーで、コーディングCLIはもっとも深くカバーしているハーネスクラスです。 -→ [組み込みポリシー全40件](https://docs.befailproof.ai/policies/builtin) +→ [組み込みポリシー一覧（40件）](https://docs.befailproof.ai/policies/builtin) --- -## 独自ポリシー +## カスタムポリシー -`.failproofai/policies/` にファイルを置くだけで自動的に読み込まれます。フラグ不要。コミットすれば、次の pull でチーム全員に反映されます。 +`.failproofai/policies/` にファイルを置くだけで自動的に読み込まれます。フラグ不要。コミットすればチーム全員が次のプルで使えます。 ```js import { customPolicies, deny, allow } from "failproofai"; @@ -180,29 +180,29 @@ customPolicies.add({ }); ``` -すべてのポリシーで使用できる3つの判定: +各ポリシーで使用できる3つの判断： -| 判定 | 効果 | +| 判断 | 効果 | |---|---| | `allow()` | 操作を許可する | -| `deny(message)` | ブロックする — メッセージがエージェントに返される | -| `instruct(message)` | 通過させつつ、エージェントの次のプロンプトにコンテキストを追加する | +| `deny(message)` | ブロックする — メッセージはエージェントに返される | +| `instruct(message)` | 通過させるが、エージェントの次のプロンプトにコンテキストを追加する | → [カスタムポリシーガイド](https://docs.befailproof.ai/policies/custom) --- -## 可観測性 +## オブザーバビリティ -エンフォースメントは機能の半分です。もう半分は、エージェントが実際に何をしたかを把握することです。 +エンフォースメントは半分にすぎません。もう半分は、エージェントが実際に何をしたかを把握することです。 -`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 へのアラート通知。自社クラスターへのセルフホスティングはエンタープライズプランで利用可能です。 +**Failproof AI Observability** は同じデータモデルのホスト型サービスで、フリートでエージェントを運用するチーム向けです。全ハーネスのすべての実行を一か所に集約し、並列サブエージェントを独立レーンで表示する実行グラフ、モデル・ツール・フックのp50/p95/p99レイテンシ、モデルごとのコストとコンテキストウィンドウのトラッキング、エラートラッキング、共有可能なダッシュボード付きSQLクエリ、独自サービスによるスコアリング評価、繰り返す失敗をエビデンスに基づく知見に変える定期監査、そしてSlack・メール・署名付きWebhookへのアラートルーティングを提供します。自社クラスターへのセルフホスティングはEnterpriseプランで利用可能です。 → [セッション](https://docs.befailproof.ai/sessions/overview) · [監査](https://docs.befailproof.ai/audits/overview) · @@ -212,44 +212,44 @@ customPolicies.add({ ## ドキュメント -| 始め方 | | +| はじめに | | |---|---| -| [クイックスタート](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/read-a-trace) | 実行グラフが示す情報 | -| [監査](https://docs.befailproof.ai/audits/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/reference/local-dashboard) | `localhost:8020`、アカウント不要 | -| エンフォースメント | | +| 制御する | | |---|---| | [組み込みポリシー](https://docs.befailproof.ai/policies/builtin) | パラメータ付き全40ポリシー | -| [カスタムポリシー](https://docs.befailproof.ai/policies/custom) | 独自ポリシーの作成 | +| [カスタムポリシー](https://docs.befailproof.ai/policies/custom) | 独自ポリシーを作成する | | [設定](https://docs.befailproof.ai/policies/local-configuration) | 設定スコープとマージルール | -| 独自エージェントのインストルメント | | +| 独自エージェントを計測する | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | ハーネスなしのエージェントから実行をレポート | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` リファレンス | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | ハーネスなしのエージェントから実行をレポートする | +| [ポリシーSDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` リファレンス | --- ## ライセンス -MIT に [Commons Clause](https://commonsclause.com/) を付加したライセンス — 社内利用・個人利用は無償。failproofai 自体の商業的な再販には別途契約が必要です。全文は [LICENSE](../../LICENSE) をご覧ください。 +MIT with [Commons Clause](https://commonsclause.com/) — 社内利用・個人利用は無料。failproofai 自体の商業的な再販には別途契約が必要です。全文は [LICENSE](../../LICENSE) をご覧ください。 --- -## コントリビュート +## コントリビューション -[CONTRIBUTING.md](../../CONTRIBUTING.md) をご参照ください。新しいポリシー、エッジケースへの対応、翻訳はいずれも歓迎します。 +[CONTRIBUTING.md](../../CONTRIBUTING.md) をご参照ください。新しいポリシー、エッジケースの対応、翻訳の追加はいずれも歓迎します。 -> **作業を始める前にビルドしてください。** まず `bun install && bun run build` を実行してください。このリポジトリは 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) をご参照ください。 +> **作業前にビルドしてください。** まず `bun install && bun run build` を実行してください。このリポジトリはfailproofai自身のフックを自分自身に適用しており、フックはコンパイル済みの `dist/` バンドルに対して `failproofai` インポートを解決します。ビルドなしで実行すると `Cannot find package 'failproofai'` というフックエラーが発生します。`src/` を変更した後は再ビルドしてください。詳細は [リポジトリ内の開発用フックを動作させるためのビルド手順](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) をご覧ください。 --- -[befailproof.ai](https://befailproof.ai) チームが SF とベンガルールから ❤️ を込めて開発。 +SFとベンガルールのチームが ❤️ を込めて開発。[befailproof.ai](https://befailproof.ai) diff --git a/docs/i18n/README.ko.md b/docs/i18n/README.ko.md index 7064258aa..c154bc49c 100644 --- a/docs/i18n/README.ko.md +++ b/docs/i18n/README.ko.md @@ -8,7 +8,7 @@ failproof ai -FailproofAI%2Ffailproofai | Trendshift +FailproofAI%2Ffailproofai | Trendshift [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai) [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions) @@ -20,11 +20,10 @@ **번역:** [简体中文](../../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 같은 자체 호스팅 어시스턴트 — 모든 실행을 캡처하고 위험한 툴 호출이 -실행되기 전에 차단합니다. 내장 정책 40개. 레이턴시 제로. 로컬 실행. +**에이전트가 실행되는 모든 하네스에 대한 관찰 가능성과 정책 적용.** +에이전트가 어디서 실행되든 우리는 확인하고 — 필요하다면 차단합니다. Failproof는 12개의 에이전트 +하네스에 훅을 연결합니다 — Claude Code, Codex 같은 코딩 CLI, Hermes 같은 채팅 게이트웨이, +OpenClaw 같은 자체 호스팅 어시스턴트 — 모든 실행을 캡처하고 위험한 도구 호출을 실행 전에 차단합니다. 기본 제공 정책 40개. 레이턴시 제로. 로컬 실행. @@ -36,9 +35,9 @@ OpenClaw 같은 자체 호스팅 어시스턴트 — 모든 실행을 캡처하 ## 지원 하네스 -두 가지 분류의 12개 하네스 — 코딩 CLI 10개, 채팅·어시스턴트 게이트웨이 2개(Hermes, OpenClaw). 어떤 하네스에서 에이전트가 실행되든 동일한 이벤트, 동일한 정책, 동일한 세션 기록이 적용됩니다. +두 가지 유형의 하네스 12개 — 코딩 CLI 10개, 채팅 및 어시스턴트 게이트웨이(Hermes, OpenClaw) 2개. 에이전트가 어느 하네스에서 실행되든 동일한 이벤트, 동일한 정책, 동일한 세션 히스토리가 적용됩니다. -이 중 어느 하네스도 사용하지 않는 에이전트는 [Python SDK](https://docs.befailproof.ai/reference/python-sdk)를 통해 보고할 수 있으며, 트레이싱·세션·감사 기능을 제공합니다. 해당 환경에서의 정책 집행은 런타임에 훅을 직접 추가해야 합니다 — [문의하시면](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 @@ -138,38 +137,37 @@ OpenClaw 같은 자체 호스팅 어시스턴트 — 모든 실행을 캡처하 ```sh npm install -g failproofai -failproofai policies --install # 또는 `failproofai`를 실행하고 첫 실행 프롬프트에서 수락 +failproofai policies --install # 또는 `failproofai`를 실행하고 최초 실행 프롬프트에서 수락 failproofai ``` -내장 정책 40개가 즉시 활성화됩니다. 대시보드는 `localhost:8020`에서 확인하세요. `FAILPROOFAI_NO_FIRST_RUN=1`로 첫 실행 프롬프트를 비활성화할 수 있습니다. +기본 제공 정책 40개가 즉시 활성화됩니다. 대시보드는 `localhost:8020`에서 확인할 수 있습니다. `FAILPROOFAI_NO_FIRST_RUN=1`로 최초 실행 프롬프트를 비활성화할 수 있습니다. --- -## 차단 목록 +## 차단 항목 -| 정책 | 차단 대상 | +| 정책 | 차단 내용 | |---|---| | `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-terraform` / `block-kubectl` | 검토 없는 라이브 인프라 변경 | | `block-rm-rf` | 재귀적 파일 삭제 | | `block-force-push` / `block-push-master` | `git push --force`, `main` 브랜치 직접 푸시 | -처음 다섯 가지는 툴을 호출할 수 있는 모든 에이전트에 적용됩니다. 나머지 세 가지는 -개발자들이 가장 선호하는 정책으로, 코딩 CLI는 우리가 가장 깊이 지원하는 하네스 분류입니다. +처음 다섯 가지는 도구를 호출할 수 있는 모든 에이전트에 적용됩니다. 나머지 세 가지는 개발자들이 가장 선호하는 정책으로 — 코딩 CLI는 우리가 가장 깊이 지원하는 하네스 유형입니다. -→ [내장 정책 40개 전체 목록](https://docs.befailproof.ai/policies/builtin) +→ [기본 제공 정책 40개 전체 보기](https://docs.befailproof.ai/policies/builtin) --- ## 커스텀 정책 -`.failproofai/policies/` 디렉터리에 파일을 넣으면 별도 플래그 없이 자동으로 로드됩니다. -커밋하면 팀 전체가 다음 pull 시 적용받습니다. +`.failproofai/policies/` 디렉토리에 파일을 추가하면 자동으로 로드됩니다 — 별도 플래그 불필요. +커밋하면 팀 전체가 다음 풀 시 적용받습니다. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -185,32 +183,29 @@ customPolicies.add({ }); ``` -모든 정책에서 사용할 수 있는 세 가지 결정: +모든 정책에서 사용 가능한 세 가지 결정: | 결정 | 효과 | |---|---| | `allow()` | 작업 허용 | -| `deny(message)` | 차단 — 메시지가 에이전트에게 반환됨 | +| `deny(message)` | 차단 — 메시지가 에이전트로 반환됨 | | `instruct(message)` | 통과시키되, 에이전트의 다음 프롬프트에 컨텍스트 추가 | → [커스텀 정책 가이드](https://docs.befailproof.ai/policies/custom) --- -## 가시성 +## 관찰 가능성 -정책 집행은 절반입니다. 나머지 절반은 에이전트가 실제로 무엇을 했는지 확인하는 것입니다. +정책 적용은 절반입니다. 나머지 절반은 에이전트가 실제로 무엇을 했는지 파악하는 것입니다. -인수 없이 `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·이메일·서명된 웹훅으로 라우팅되는 알림. 자체 클러스터에서의 셀프호스팅은 Enterprise 플랜에서 이용 가능합니다. +**Failproof AI Observability**는 동일한 데이터 모델의 호스팅 버전으로, 여러 머신에서 에이전트를 운영하는 팀을 위한 서비스입니다: 모든 하네스에서 실행된 전체 기록을 한 곳에서 확인, 독립 레인에서 병렬 서브에이전트가 표시되는 실행 그래프, 모델·도구·훅의 p50/p95/p99 레이턴시, 모델별 비용 및 컨텍스트 윈도우 추적, 에러 추적, 공유 가능한 대시보드가 포함된 자체 트레이스 SQL 쿼리, 자체 서비스로 채점하는 평가, 반복 실패를 근거 있는 발견으로 전환하는 정기 감사, Slack·이메일·서명된 웹훅으로 알림 라우팅. 자체 클러스터 셀프호스팅은 Enterprise 플랜에서 제공됩니다. → [세션](https://docs.befailproof.ai/sessions/overview) · [감사](https://docs.befailproof.ai/audits/overview) · @@ -222,44 +217,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/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) | 파라미터 포함 40개 정책 전체 | +| [기본 제공 정책](https://docs.befailproof.ai/policies/builtin) | 파라미터가 포함된 40개 정책 전체 | | [커스텀 정책](https://docs.befailproof.ai/policies/custom) | 직접 작성하기 | -| [설정](https://docs.befailproof.ai/policies/local-configuration) | 설정 범위 및 병합 규칙 | +| [설정](https://docs.befailproof.ai/policies/local-configuration) | 설정 스코프 및 병합 규칙 | -| 직접 에이전트 계측 | | +| 에이전트 직접 계측 | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | 하네스 없이 에이전트에서 실행 보고 | +| [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/`를 수정한 후에는 다시 빌드하세요. 자세한 내용은 +> **시작 전에 먼저 빌드하세요.** `bun install && bun run build`를 먼저 실행해야 합니다. 이 저장소는 +> failproofai 자체 훅을 스스로에 적용하며, 훅은 `failproofai` 임포트를 컴파일된 `dist/` 번들에서 +> 해석합니다 — 빌드 없이 실행하면 `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 842c67216..fd57fd733 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 todos os ambientes em que seus agentes rodam.** -Onde quer que seus agentes executem, nós enxergamos — e podemos dizer não. O Failproof conecta-se a 12 ambientes de agentes — CLIs de programaçã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. 40 políticas integradas. Latência zero. Roda localmente. +**Observabilidade e controle para cada ambiente em que seus agentes rodam.** +Onde quer que seus agentes estejam, a gente enxerga — e pode 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 ferramenta perigosas antes que aconteçam. 40 políticas embutidas. Zero latência. Roda localmente. @@ -33,9 +33,9 @@ Onde quer que seus agentes executem, nós enxergamos — e podemos dizer não. O ## Ambientes suportados -Doze ambientes em duas categorias — dez CLIs de programação, e dois gateways de chat e assistentes (Hermes, OpenClaw). Mesmos eventos, mesmas políticas, mesmo histórico de sessões, independentemente de qual o seu agente utilize. +Doze ambientes em duas categorias — dez CLIs de codificação e dois gateways de chat e assistentes (Hermes, OpenClaw). Mesmos eventos, mesmas políticas, mesmo histórico de sessão, independentemente de qual o seu agente utiliza. -Agentes que não rodam em nenhum deles reportam pelo [Python SDK](https://docs.befailproof.ai/reference/python-sdk), que oferece rastreamento, sessões e auditorias. O controle nesses casos exige um hook no seu próprio runtime — [fale conosco](mailto:support@befailproof.ai) e mapeamos juntos. +Agentes que não rodam em nenhum deles reportam por meio do [Python SDK](https://docs.befailproof.ai/reference/custom-agents), que oferece rastreamento, sessões e auditorias. Para aplicar controles nesses casos, é necessário 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,11 @@ Agentes que não rodam em nenhum deles reportam pelo [Python SDK](https://docs.b ```sh npm install -g failproofai -failproofai policies --install # ou apenas execute `failproofai` e aceite o prompt inicial +failproofai policies --install # ou apenas execute `failproofai` e aceite o prompt da primeira execução failproofai ``` -40 políticas integradas são ativadas imediatamente. Dashboard em `localhost:8020`. Desative o prompt inicial com `FAILPROOFAI_NO_FIRST_RUN=1`. +40 políticas embutidas são ativadas imediatamente. Dashboard em `localhost:8020`. Desative o prompt da primeira execução com `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -147,24 +147,25 @@ failproofai | Política | O que bloqueia | |---|---| -| `sanitize-api-keys` | Vazamento de chaves de API no contexto do agente | -| `block-env-files` | Leitura de arquivos `.env` e outros arquivos de segredos | -| `warn-repeated-tool-calls` | O agente em loop na mesma chamada | +| `sanitize-api-keys` | Vazamento de chaves de API para o contexto do agente | +| `block-env-files` | Leitura de `.env` e outros arquivos com segredos | +| `warn-repeated-tool-calls` | O agente entrando em loop na mesma chamada | | `block-sudo` | Escalada de privilégios | | `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sem cláusula WHERE | | `block-terraform` / `block-kubectl` | Alterações não revisadas em infraestrutura em produção | | `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 — as CLIs de programação são a categoria de ambiente que cobrimos com mais profundidade. +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 em que temos a cobertura mais profunda. -→ [Todas as 40 políticas integradas](https://docs.befailproof.ai/policies/builtin) +→ [Todas as 40 políticas embutidas](https://docs.befailproof.ai/policies/builtin) --- ## Suas próprias políticas -Coloque um arquivo em `.failproofai/policies/` — ele é carregado automaticamente, sem nenhuma flag necessária. Faça commit e toda a equipe receberá na próxima atualização. +Coloque um arquivo em `.failproofai/policies/` — ele é carregado automaticamente, sem necessidade de flags. +Faça commit e toda a equipe recebe na próxima atualização. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -185,7 +186,7 @@ Três decisões disponíveis para cada política: | Decisão | Efeito | |---|---| | `allow()` | Permite a operação | -| `deny(message)` | Bloqueia — a mensagem é enviada de volta ao agente | +| `deny(message)` | Bloqueia — a mensagem é devolvida 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) @@ -194,19 +195,19 @@ Três decisões disponíveis para cada política: ## Observabilidade -O controle é uma metade. A outra metade é enxergar o que o agente realmente fez. +Controle é uma metade. A outra é enxergar 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á presente na sua máquina — sem conta, sem cadastro, nada sai da máquina. Você tem a lista de sessões, a sequência de chamadas ao modelo, chamadas de ferramentas e decisões de hook em cada execução, o que foi bloqueado e o que a política informou ao agente, além de uma auditoria offline (`failproofai audit`) que examina seu histórico em busca de padrões arriscados e sugere políticas para contê-los. +Execute `failproofai` sem argumentos e ele serve um dashboard em `localhost:8020` lendo o histórico de execuções já disponível na sua máquina — sem conta, sem cadastro, nada sai do seu ambiente. Você tem a lista de sessões, a sequência de chamadas ao modelo, chamadas de ferramenta e decisões de hook 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 contê-los. → [Dashboard local](https://docs.befailproof.ai/reference/local-dashboard) · [Lendo um trace](https://docs.befailproof.ai/sessions/read-a-trace) · [Auditoria local](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** é a versão hospedada do mesmo modelo de dados, para equipes que rodam agentes em múltiplas máquinas: todas as execuções de todos os ambientes em um só lugar, um grafo de execução com sub-agentes paralelos em suas próprias raias, 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 descobertas baseadas 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 múltiplas máquinas: todas as execuções de todos os ambientes em um só lugar, um grafo de execução com sub-agentes paralelos em suas próprias raias, 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 descobertas com 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) · -[Agendar uma demo](https://befailproof.ai/get-a-demo) +[Agende uma demo](https://befailproof.ai/get-a-demo) --- @@ -214,33 +215,33 @@ Execute `failproofai` sem argumentos e ele serve um dashboard em `localhost:8020 | Início | | |---|---| -| [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 ambiente e 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 controlar | +| [Ambientes suportados](https://docs.befailproof.ai/reference/harnesses) | Todos os 12 e o que cada um pode controlar | | 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á indicando | -| [Auditorias](https://docs.befailproof.ai/audits/overview) | Encontre padrões de falha em várias sessões | +| [Lendo um trace](https://docs.befailproof.ai/sessions/read-a-trace) | O que o grafo de execução está te dizendo | +| [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 conta necessária | | Controlar | | |---|---| -| [Políticas integradas](https://docs.befailproof.ai/policies/builtin) | Todas as 40 políticas com parâmetros | +| [Políticas embutidas](https://docs.befailproof.ai/policies/builtin) | Todas as 40 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 | -| Instrumentar seu próprio agente | | +| Instrumente seu próprio agente | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | Reporte execuções de um agente sem ambiente definido | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Reporte execuções de um agente sem ambiente | | [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Referência de `allow` / `deny` / `instruct` | --- ## Licença -MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso interno e pessoal; a revenda comercial do failproofai em si exige um acordo separado. Veja o [LICENSE](../../LICENSE) para o texto completo. +MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso interno e pessoal; a revenda comercial do failproofai em si requer um acordo separado. Veja [LICENSE](../../LICENSE) para o texto completo. --- @@ -248,7 +249,7 @@ MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso inter Veja [CONTRIBUTING.md](../../CONTRIBUTING.md). Novas políticas, casos extremos e traduções são 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ê encontrará erros de hook com `Cannot find package 'failproofai'`. Refaça o build após alterar `src/`. Veja +> **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). --- diff --git a/docs/i18n/README.ru.md b/docs/i18n/README.ru.md index c02709e02..e3e988829 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 AI интегрируется с 12 платформами для работы с агентами — средствами разработки кода, такими как Claude Code и Codex, шлюзами чата, такими как Hermes, и самостоятельно развёрнутыми помощниками, такими как OpenClaw — перехватывая каждый запуск и блокируя опасные вызовы инструментов перед их выполнением. 40 встроенных политик. Нулевая задержка. Работает локально. +**Видимость и контроль для каждого окружения, в котором работают ваши агенты.** +Где бы ни работали ваши агенты, мы это видим — и можем сказать нет. failproofai подключается к 12 окружениям агентов — coding CLI, таким как Claude Code и Codex, шлюзам чата, таким как Hermes, самостоятельным помощникам, таким как OpenClaw — перехватывая каждый запуск и блокируя опасные вызовы инструментов перед их выполнением. 40 встроенных политик. Нулевая задержка. Работает локально. @@ -31,12 +31,11 @@ --- -## Поддерживаемые платформы +## Поддерживаемые окружения -Двенадцать платформ в двух классах — десять средств разработки кода и два шлюза чата и помощников (Hermes, OpenClaw). Одинаковые события, одинаковые политики, одинаковая история сессий, в какой бы платформе ни работал ваш агент. +Двенадцать окружений в двух категориях — десять coding CLI и два шлюза для чата и ассистентов (Hermes, OpenClaw). Одни и те же события, одни и те же политики, одна и та же история сессий, независимо от того, в каком из них работает ваш агент. -Агенты, которые работают ни в одной из них, отправляют данные через [Python SDK](https://docs.befailproof.ai/reference/python-sdk), -что даёт вам трассировку, сессии и аудит. Управление там требует хука в вашей собственной среде выполнения — [напишите нам](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 @@ -136,11 +135,11 @@ ```sh npm install -g failproofai -failproofai policies --install # или просто запустите `failproofai` и подтвердите первичный запрос +failproofai policies --install # или просто запустите `failproofai` и примите запрос при первом запуске failproofai ``` -40 встроенных политик активируются немедленно. Панель управления доступна на `localhost:8020`. Отключите первичный запрос с помощью `FAILPROOFAI_NO_FIRST_RUN=1`. +40 встроенных политик активируются сразу же. Панель управления на `localhost:8020`. Отключите запрос при первом запуске с помощью `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -148,16 +147,16 @@ failproofai | Политика | Что она блокирует | |---|---| -| `sanitize-api-keys` | Утечка API-ключей в контекст агента | +| `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` | Непроверенные изменения инфраструктуры | +| `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`, прямые push в `main` | -Первые пять применяются к любому агенту, который может вызывать инструменты. Последние три — фавориты разработчиков — средства разработки кода являются классом платформ, который мы покрываем наиболее глубоко. +Первые пять применяются к любому агенту, который может вызывать инструмент. Последние три — фавориты разработчиков — coding CLI — это класс окружения, который мы поддерживаем наиболее глубоко. → [Все 40 встроенных политик](https://docs.befailproof.ai/policies/builtin) @@ -165,8 +164,8 @@ failproofai ## Ваши собственные политики -Разместите файл в `.failproofai/policies/` — он загружается автоматически без каких-либо флагов. -Добавьте его в репозиторий и вся команда получит его при следующем пуле. +Просто разместите файл в `.failproofai/policies/` — он загружается автоматически, флаги не требуются. +Закоммитьте его и вся команда получит его при следующем pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -187,26 +186,24 @@ customPolicies.add({ | Решение | Эффект | |---|---| | `allow()` | Разрешить операцию | -| `deny(message)` | Заблокировать её — сообщение вернётся агенту | -| `instruct(message)` | Разрешить, но добавить контекст в следующий запрос агента | +| `deny(message)` | Заблокировать её — сообщение вернется агенту | +| `instruct(message)` | Пропустить, но добавить контекст в следующий запрос агента | → [Руководство по пользовательским политикам](https://docs.befailproof.ai/policies/custom) --- -## Наблюдаемость +## Видимость -Управление — это одна половина. Другая половина — видеть то, что на самом деле сделал агент. +Контроль — это одна половина. Другая половина — это видение того, что на самом деле сделал агент. -Запустите `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, по электронной почте или на подписанный вебхук. Самостоятельное хостирование в вашем собственном кластере доступно в плане Enterprise. +**Failproof AI Observability** — это хостированная часть той же модели данных для команд, работающих с агентами на флоте: каждый запуск от каждого окружения в одном месте, граф выполнения с параллельными под-агентами на своих полосах, латентность p50/p95/p99 для моделей, инструментов и подключений, стоимость на модель и отслеживание окна контекста, отслеживание ошибок, SQL над вашими собственными трассировками с общими панелями управления, оценки, оцениваемые вашим сервисом, запланированные аудиты, которые превращают повторяющиеся сбои в подтвержденные выводы, и оповещения, направляемые в Slack, электронную почту или подписанный вебхук. Самостоятельный хостинг в вашем собственном кластере доступен в плане Enterprise. → [Сессии](https://docs.befailproof.ai/sessions/overview) · [Аудиты](https://docs.befailproof.ai/audits/overview) · @@ -218,26 +215,26 @@ 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/reference/local-dashboard) | `localhost:8020`, без необходимости учётной записи | +| [Аудиты](https://docs.befailproof.ai/audits/overview) | Найдите паттерны сбоев в разных сессиях | +| [Локальная панель управления](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, аккаунт не требуется | -| Управление | | +| Контроль | | |---|---| | [Встроенные политики](https://docs.befailproof.ai/policies/builtin) | Все 40 политик с параметрами | | [Пользовательские политики](https://docs.befailproof.ai/policies/custom) | Напишите свои собственные | -| [Конфигурация](https://docs.befailproof.ai/policies/local-configuration) | Области конфигурации и правила объединения | +| [Конфигурация](https://docs.befailproof.ai/policies/local-configuration) | Области конфигурации и правила слияния | -| Инструментируйте свой собственный агент | | +| Подключите свой собственный агент | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | Отправляйте запуски от агента без платформы | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Отправляйте запуски от агента без окружения | | [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Справочник `allow` / `deny` / `instruct` | --- @@ -248,13 +245,13 @@ MIT с [Commons Clause](https://commonsclause.com/) — бесплатно дл --- -## Участие +## Вклад -См. [CONTRIBUTING.md](../../CONTRIBUTING.md). Новые политики, граничные случаи и переводы приветствуются. +См. [CONTRIBUTING.md](../../CONTRIBUTING.md). Новые политики, граничные случаи и переводы всегда приветствуются. -> **Соберите проект перед началом.** Сначала запустите `bun install && bun run build`. Этот репозиторий запускает собственные хуки failproofai на себе, и они разрешают импорт `failproofai` в скомпилированный пакет `dist/` — без сборки вы получите ошибки хука `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). +> **Постройте перед началом работы.** Сначала запустите `bun install && bun run build`. Этот репозиторий запускает собственные подключения failproofai для себя, и они разрешают импорт `failproofai` к скомпилированному пакету `dist/` — без сборки вы получите ошибки подключения `Cannot find package 'failproofai'`. Перестройте после изменения `src/`. См. раздел +> [Постройте перед тем, как будут работать in-repo dev подключения](../../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/i18n/README.tr.md b/docs/i18n/README.tr.md index 204602ff2..7e7cd39f0 100644 --- a/docs/i18n/README.tr.md +++ b/docs/i18n/README.tr.md @@ -20,8 +20,8 @@ **Ç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) -**Aracılarınızın çalıştığı her ortam için gözlenebilirlik ve zorlama.** -Aracılarınız nerede çalışırsa çalışsın, biz görebiliriz — ve hayır diyebiliriz. Failproof, 12 aracı ortamına bağlanır — Claude Code ve Codex gibi kodlama CLI'leri, Hermes gibi sohbet ağ geçitleri, OpenClaw gibi kendi kendine barındırılan asistanlar — her çalıştırmayı yakalar ve tehlikeli araç çağrılarını yürütülmeden önce engeller. 40 yerleşik ilke. Sıfır gecikme. Yerel olarak çalışır. +**Ajanların çalıştığı her ortamda gözlemlenebilirlik ve uygulama.** +Ajanların nerede çalıştığını görebiliriz — ve hayır diyebiliriz. Failproof, Claude Code ve Codex gibi kodlama CLI'ları, Hermes gibi sohbet ağ geçitleri, OpenClaw gibi kendi kendine barındırılan asistanlar olmak üzere 12 ajan ortamını kancalamakta, her çalışmayı yakalamakta ve tehlikeli araç çağrılarını yürütülmeden önce engellemektedir. 40 yerleşik politika. Sıfır gecikme. Yerel olarak çalışır. @@ -33,9 +33,9 @@ Aracılarınız nerede çalışırsa çalışsın, biz görebiliriz — ve hayı ## Desteklenen ortamlar -İki sınıfta on iki ortam — on kodlama CLI'si ve iki sohbet ve asistan ağ geçidi (Hermes, OpenClaw). Aynı olaylar, aynı ilkeler, aynı oturum geçmişi, aracınız hangisinde çalışırsa çalışsın. +İki sınıfta on iki ortam — on kodlama CLI'sı ve iki sohbet ve asistan ağ geçidi (Hermes, OpenClaw). Aynı olaylar, aynı politikalar, aynı oturum geçmişi, ajan hangi ortamda çalışırsa çalışsın. -Bunlardan hiçbirinde çalışmayan aracılar [Python SDK](https://docs.befailproof.ai/reference/python-sdk) aracılığıyla rapor verir; bu size izleme, oturumlar ve denetim sağlar. Orada zorlama, kendi çalışma zamanınızda bir kancaya ihtiyaç duyar — [bizimle iletişime geçin](mailto:support@befailproof.ai) ve biz bunu eşleştireceğiz. +Bunların hiçbirinde çalışmayan Ajanlar [Python SDK](https://docs.befailproof.ai/reference/custom-agents) aracılığıyla rapor verir; bu size izleme, oturumlar ve denetim yeteneği sağlar. Orada uygulama, kendi çalışma ortamınızda bir kanca gerektirir — [bize yazın](mailto:support@befailproof.ai) ve biz bunu 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 @@ -131,7 +131,7 @@ Bunlardan hiçbirinde çalışmayan aracılar [Python SDK](https://docs.befailpr -## Yükle +## Kurulum ```sh npm install -g failproofai @@ -139,33 +139,33 @@ failproofai policies --install # veya sadece `failproofai` çalıştırın ve failproofai ``` -40 yerleşik ilke hemen etkinleşir. Pano `localhost:8020` adresinde. İlk çalıştırma istemini `FAILPROOFAI_NO_FIRST_RUN=1` ile devre dışı bırakın. +40 yerleşik politika hemen etkinleştirilir. Pano şu adreste bulunur: `localhost:8020`. İlk çalıştırma istemini `FAILPROOFAI_NO_FIRST_RUN=1` ile devre dışı bırakın. --- -## Neyi engeller +## Neleri engeller -| İlke | Neyi engeller | +| Politika | Neyi engeller | |---|---| -| `sanitize-api-keys` | API anahtarlarının aracının bağlamına sızması | +| `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` | Aracının aynı çağrıda döngüye girmesi | +| `warn-repeated-tool-calls` | Ajanın aynı çağrıda döngüye girmesi | | `block-sudo` | Ayrıcalık yükseltme | | `warn-destructive-sql` | `DROP`, `TRUNCATE`, sınırsız `DELETE` | -| `block-terraform` / `block-kubectl` | Gözden geçirilmemiş canlı altyapı değişiklikleri | -| `block-rm-rf` | Özyinelemeli dosya silme | -| `block-force-push` / `block-push-master` | `git push --force`, `main` ağacına doğrudan gönderim | +| `block-terraform` / `block-kubectl` | Canlı altyapıya incelenmemiş değişiklikler | +| `block-rm-rf` | Yinelemeli dosya silme | +| `block-force-push` / `block-push-master` | `git push --force`, `main` öğesine doğrudan push işlemleri | -İlk beş, araç çağırabilen herhangi bir aracı için geçerlidir. Son üç, geliştirici favorileridir — kodlama CLI'leri, en derin kapsama sahip ortam sınıfıdır. +İlk beş tanesinin herhangi bir araç çağırabilen ajan için geçerlidir. Son üçü geliştirici favori notları — kodlama CLI'ları, en derinlemesine kapsadığımız ortam sınıfıdır. -→ [Tüm 40 yerleşik ilke](https://docs.befailproof.ai/policies/builtin) +→ [40 yerleşik politikanın tümü](https://docs.befailproof.ai/policies/builtin) --- -## Kendi ilkeleriniz +## Kendi politikalarınız -`.failproofai/policies/` dosyasına bir dosya bırakın — otomatik olarak yüklenir, hiçbir bayrak gerekmez. -Bunu taahhüt edin ve tüm takım sonraki çekişte bunu alır. +`.failproofai/policies/` klasörüne bir dosya bırakın — bayrak gerekli olmaksızın otomatik olarak yüklenir. +İşleyin ve tüm takım bunu sonraki pull'da alır. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -175,82 +175,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("Production yollarına yazma işlemleri engellenir."); return allow(); }, }); ``` -Her ilkeye açık olan üç karar vardır: +Her politika için kullanılabilir üç karar: | Karar | Etki | |---|---| | `allow()` | İşleme izin ver | -| `deny(message)` | Engelle — mesaj aracıya geri dönüşür | -| `instruct(message)` | İzin ver, ancak bağlam aracının sonraki istemiyle ekle | +| `deny(message)` | Engelle — ileti ajana geri gider | +| `instruct(message)` | Bunu geçir, ancak ajanın sonraki istemine bağlam ekle | -→ [Özel ilkeler rehberi](https://docs.befailproof.ai/policies/custom) +→ [Özel politikalar rehberi](https://docs.befailproof.ai/policies/custom) --- -## Gözlenebilirlik +## Gözlemlenebilirlik -Zorlama bir yarısı. Diğer yarısı, aracının gerçekten ne yaptığını görmektir. +Uygulama bir yarısı. Diğer yarısı ise ajanın gerçekte ne yaptığını görmektir. -`failproofai` komutunu hiçbir argüman olmadan çalıştırın ve `localhost:8020` adresinde makinenizde zaten bulunan çalıştırma geçmişini okuyan bir pano sunar — hesap yok, kaydolma yok, kutu dışına hiçbir şey çıkmaz. Oturum listesini, her çalıştırma içindeki model çağrılarının sırasını, araç çağrılarını ve kanca kararlarını, engellenenleri ve ilkenin aracıya söylediklerini, ve risky desenler için geçmişinizi tarayacak ve onları durdurmak için ilkeler önerecek çevrimdışı bir denetimi (`failproofai audit`) alırsınız. +`failproofai` parametresiz çalıştırın ve makinenizde zaten bulunan çalışma geçmişini okuyan `localhost:8020` adresinde bir pano sunar — hesap yok, kayıt yok, hiçbir şey kutudan dışarı çıkmaz. Oturum listesini, model çağrılarının sırasını, her çalışma içindeki araç çağrılarını ve kanca kararlarını, neyin engellendiğini ve politikanın ajana söylediklerini, ve risky desenleri için çalışma geçmişinizi taraması yapan ve onları durdurmak için politikalar önerenin çevrimdışı denetimini (`failproofai audit`) alırsınız. → [Yerel pano](https://docs.befailproof.ai/reference/local-dashboard) · -[İzleme oku](https://docs.befailproof.ai/sessions/read-a-trace) · +[İz oku](https://docs.befailproof.ai/sessions/read-a-trace) · [Yerel denetim](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Gözlenebilirlik**, aynı veri modelinin barındırılan tarafıdır ve bir filo genelinde aracı çalıştıran takımlar içindir: her ortamdan her çalıştırma bir yerde, paralel alt-aracıların kendi şeritlerinde bulunduğu bir yürütme grafiği, modeller, araçlar ve kancalar için p50/p95/p99 gecikme, model başına maliyet ve bağlam penceresinin izlenmesi, hata izleme, kendi izlemenizin üzerinde SQL paylaşılabilir panolarla, kendi hizmetiniz tarafından puanlanan değerlendirmeler, periyodik hataları kanıta dayalı bulgulara dönüştüren planlanan denetimler ve Slack, e-posta veya imzalı webhook'a yönlendirilen uyarılar. Kendi kümenizde kendi kendine barındırma Enterprise planında mevcuttur. +**Failproof AI Gözlemlenebilirliği**, bir filo arasında ajanlar çalıştıran takımlar için aynı veri modelinin barındırılan tarafıdır: her ortamdan her çalışma tek bir yerde, kendi şeritlerinde paralel alt-ajanlar içeren bir yürütme grafiği, modeller, araçlar ve kancalar için p50/p95/p99 gecikmesi, model başına maliyet ve bağlam penceresi izlemesi, hata izlemesi, kendi izlemeleri üzerinden SQL paylaşılabilir panolarla, kendi hizmetiniz tarafından puanlandırılan değerlendirmeler, yinelenen hataları kanıta dayalı bulgulara dönüştüren planlanan denetimler ve Slack, e-posta veya imzalı webhooks'a yönlendirilen uyarılar. Kendi kümenizde kendi kendine barındırma, Enterprise planında kullanılabilir. → [Oturumlar](https://docs.befailproof.ai/sessions/overview) · [Denetimler](https://docs.befailproof.ai/audits/overview) · -[Demo rezervasyonu yap](https://befailproof.ai/get-a-demo) +[Demo ayırtın](https://befailproof.ai/get-a-demo) --- -## Belgeler +## Belgeleme -| Başlayın | | +| Başlangıç | | |---|---| -| [Hızlı başlangıç](https://docs.befailproof.ai/start/quickstart) | Yükle, bir ortamı bağla, ilk çalıştırmayı gör | +| [Hızlı başlangıç](https://docs.befailproof.ai/start/quickstart) | Kurulum yapın, bir ortamı bağlayın, ilk çalışmayı görün | | [Kavramlar](https://docs.befailproof.ai/start/concepts) | Kanca sistemi nasıl çalışır | -| [Desteklenen ortamlar](https://docs.befailproof.ai/reference/harnesses) | Tüm 12'si ve her birinin ne uygulayabileceği | +| [Desteklenen ortamlar](https://docs.befailproof.ai/reference/harnesses) | Tümü 12 ve her birinin uygulayabileceği | -| Gözlemle | | +| Gözlemleyin | | |---|---| -| [Oturumlar](https://docs.befailproof.ai/sessions/overview) | Bir çalıştırmayı takip et: modeller, araçlar, hatalar, gecikme | -| [İzleme 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 hata desenlerini bul | -| [Yerel pano](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, hesap gerekmez | +| [Oturumlar](https://docs.befailproof.ai/sessions/overview) | Bir çalışmayı izleyin: modeller, araçlar, hatalar, gecikme | +| [İz oku](https://docs.befailproof.ai/sessions/read-a-trace) | Yürütme grafiği size ne anlatıyor | +| [Denetimler](https://docs.befailproof.ai/audits/overview) | Birçok oturumdaki başarısızlık desenleri bulun | +| [Yerel pano](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, hesap gerekli değil | -| Zorla | | +| Uygulayın | | |---|---| -| [Yerleşik ilkeler](https://docs.befailproof.ai/policies/builtin) | Tüm 40 ilke parametrelerle | -| [Özel ilkeler](https://docs.befailproof.ai/policies/custom) | Kendi ilkelerini yaz | +| [Yerleşik politikalar](https://docs.befailproof.ai/policies/builtin) | Tüm 40 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ı | -| Kendi aracını enstrüman et | | +| Kendi ajanınızı enstrüman edin | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | Ortamı olmayan bir aracıdan çalıştırmaları rapor et | -| [İlke SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` referansı | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Ortamı olmayan bir ajanın çalışmalarını raporlayın | +| [Politika SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` başvurusu | --- ## Lisans -[Commons Clause](https://commonsclause.com/) ile MIT — iç ve kişisel kullanım için ücretsiz; failproofai'nin kendisinin ticari yeniden satışı ayrı bir anlaşma gerektirir. Tam metin için [LICENSE](../../LICENSE) dosyasına bakın. +MIT ile [Commons Clause](https://commonsclause.com/) — dahili ve kişisel kullanım için ücretsiz; failproofai'nin kendisinin ticari yeniden satışı ayrı bir anlaşma gerektirir. Tam metin için [LICENSE](../../LICENSE) dosyasına bakın. --- -## Katkıda bulunun +## Katkı -[CONTRIBUTING.md](../../CONTRIBUTING.md) dosyasına bakın. Yeni ilkeler, uç durumlar ve çeviriler hepsi hoş geldiniz. +[CONTRIBUTING.md](../../CONTRIBUTING.md) dosyasına bakın. Yeni politikalar, kenar durumları ve çeviriler hepsi hoş geldiniz. -> **Başlamadan önce derle.** Önce `bun install && bun run build` komutunu çalıştırın. Bu depo, failproofai'nin kendi kancalarını kendisi üzerinde çalıştırır ve `failproofai` içeri aktarımını derlenmiş `dist/` paketine göre çözerler — bir derleme olmadan, `Cannot find package 'failproofai'` kanca hatalarıyla karşılaşırsınız. `src/` değiştirdikten sonra yeniden derleyin. [Repo içi geliştirme kancaları çalışması için önce derleyin](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) dosyasına bakın. +> **Başlamadan önce derleyin.** Önce `bun install && bun run build` çalıştırın. Bu depo failproofai'nin kendi kancalarını kendisinde çalıştırır ve bunlar `failproofai` ithalatını derlenmiş `dist/` paketine karşı çözer — derleme olmadan `Cannot find package 'failproofai'` kanca hatalarına çarparsınız. `src/` dosyalarını değiştirdikten sonra yeniden derleyin. Bkz. [In-repo dev kankaları çalışacak şekilde Derle](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Sevgiyle [befailproof.ai](https://befailproof.ai) tarafından SF ve Bengaluru'da yapılmıştır. +San Francisco ve Bengaluru'da [befailproof.ai](https://befailproof.ai) tarafından ❤️ ile yapılmıştır. diff --git a/docs/i18n/README.vi.md b/docs/i18n/README.vi.md index 313331fa1..2d302fe42 100644 --- a/docs/i18n/README.vi.md +++ b/docs/i18n/README.vi.md @@ -20,22 +20,29 @@ **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 của bạn chạy.** -Bất kể agents của bạn chạy ở đâu, chúng tôi đều nhìn thấy — và chúng tôi có thể từ chối. Failproof kết nối 12 agent harness — các CLI viết mã 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 công cụ nguy hiểm trước khi chúng thực thi. 40 chính sách tích hợp sẵn. Độ trễ bằng không. Chạy cục bộ. +**Quan sát và thực thi mọi công cụ chạy trên agents của bạn.** +Bất cứ nơi nào agents chạy, chúng tôi đều thấy được — và chúng tôi có thể từ chối. Failproof kết nối với 12 công cụ agent +— các CLI lập trình như Claude Code và Codex, các cổng 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 thực thi. 40 chính sách được tích hợp sẵn. Độ trễ bằng không. Chạy cục bộ.

- Failproof AI in action + Failproof AI hoạt động

--- -## Các harness được hỗ trợ +## Các công cụ được hỗ trợ -Mười hai harness trong hai lớp — mười CLI viết mã, và hai cổng chat và trợ lý (Hermes, OpenClaw). Cùng các sự kiện, cùng chính sách, cùng lịch sử phiên, bất kể agents của bạn chạy trong cái nào. +Mười hai công cụ trong hai lớp — mười CLI lập trình, và hai cổng chat và trợ lý +(Hermes, OpenClaw). Cùng các sự kiện, cùng chính sách, cùng lịch sử phiên làm việc, +bất kể công cụ nào mà agent chạy trên đó. -Các agents chạy trong cái nào đó khác báo cáo thông qua [Python SDK](https://docs.befailproof.ai/reference/python-sdk), cung cấp cho bạn theo dõi, phiên và kiểm toán. Thực thi ở đó cần một hook trong runtime của riêng bạn — [liên hệ với chúng tôi](mailto:support@befailproof.ai) và chúng tôi sẽ ánh xạ nó. +Các agents chạy trên không có công cụ nào báo cáo thông qua [Python SDK](https://docs.befailproof.ai/reference/custom-agents), +nó cung cấp cho bạn tracing, phiên làm việc và kiểm toán. Thực thi ở đó cần một hook trong +runtime của riêng bạn — [hãy 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 @@ -139,7 +146,7 @@ failproofai policies --install # hoặc chỉ chạy `failproofai` và chấp failproofai ``` -40 chính sách tích hợp sẵn sẽ kích hoạt ngay lập tức. Dashboard tại `localhost:8020`. Tắt lời nhắc lần đầu với `FAILPROOFAI_NO_FIRST_RUN=1`. +40 chính sách được tích hợp sẵn sẽ kích hoạt ngay lập tức. Bảng điều khiển tại `localhost:8020`. Vô hiệu hóa lời nhắc lần đầu bằng `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -147,24 +154,26 @@ failproofai | Chính sách | Những gì nó chặn | |---|---| -| `sanitize-api-keys` | Các khóa API bị rò rỉ vào bối cảnh của agent | -| `block-env-files` | Đọc các tệp `.env` và tệp bí mật khác | +| `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 | | `warn-repeated-tool-calls` | Agent lặp lại trên cùng một lệnh gọi | | `block-sudo` | Nâng cao đặc quyền | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` không bị giới hạn | -| `block-terraform` / `block-kubectl` | Thay đổi không được xem xét đối với cơ sở hạ tầng trực tiếp | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` không giới hạn | +| `block-terraform` / `block-kubectl` | Các thay đổi không được xem xét đối với cơ sở hạ tầng trực tiếp | | `block-rm-rf` | Xóa tệp đệ quy | -| `block-force-push` / `block-push-master` | `git push --force`, đẩy trực tiếp đến `main` | +| `block-force-push` / `block-push-master` | `git push --force`, các lần đẩ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 ưa thích của nhà phát triển — các CLI viết mã là lớp harness mà chúng tôi bao quát sâu nhất. +Năm chính sách đầu tiên áp dụng cho bất kỳ agent nào có thể gọi một công cụ. Ba chính sách cuối cùng là những yêu thích +của nhà phát triển — CLI lập trình là lớp công cụ mà chúng tôi bao phủ sâu nhất. -→ [Tất cả 40 chính sách tích hợp sẵn](https://docs.befailproof.ai/policies/builtin) +→ [Tất cả 40 chính sách được tích hợp sẵn](https://docs.befailproof.ai/policies/builtin) --- ## 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ờ. Cam kết nó và toàn bộ nhóm của bạn sẽ nhận được nó khi pull tiếp theo. +Thả một tệp vào `.failproofai/policies/` — nó sẽ tải tự động, không cần bất kỳ cờ nào. +Commit nó và toàn bộ đội sẽ nhận được nó khi kéo xuống tiếp theo. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -182,29 +191,40 @@ customPolicies.add({ Ba quyết định có sẵn cho mọi chính sách: -| Quyết định | Hiệu ứng | +| Quyết định | Hiệu quả | |---|---| | `allow()` | Cho phép hoạt động | -| `deny(message)` | Chặn nó — thông báo được gửi lại cho agent | -| `instruct(message)` | Cho phép nó thực hiện, nhưng thêm ngữ cảnh vào lời nhắc tiếp theo của agent | +| `deny(message)` | Chặn nó — tin nhắn quay lại agent | +| `instruct(message)` | Cho phép nó tiếp tục, 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) --- -## Quan sát +## Khả năng quan sát -Thực thi là một nửa. Nửa còn lại là xem agent thực sự đã làm gì. +Thực thi là một nửa. Nửa còn lại là thấy được agent thực sự đã làm gì. -Chạy `failproofai` mà không có đối số và nó sẽ phục vụ một dashboard tại `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 sẽ nhận được danh sách phiên, chuỗi 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à chính sách nói với agent điều gì, và kiểm toán 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 ý các chính sách để dừng chúng. +Chạy `failproofai` không có đối số và nó phục vụ một 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 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à chính sách nói với agent, và một kiểm toán 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 ý các chính sách để ngăn chặn chúng. -→ [Dashboard cục bộ](https://docs.befailproof.ai/reference/local-dashboard) · +→ [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 toán cục bộ](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** là phía được lưu trữ của cùng một mô hình dữ liệu, dành cho các nhóm chạy agents trên một lfleet: mọi lần chạy từ mọi harness ở một nơi, một biểu đồ thực thi với các sub-agents song song trên làn đường riêng của họ, độ trễ p50/p95/p99 cho các mô hình, công cụ và hook, theo dõi chi phí mỗi mô hình và 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 các dashboard có thể chia sẻ, các đánh giá được tính điểm bởi dịch vụ của riêng bạn, các kiểm toán được lên lịch biến các lỗi định kỳ thành các phát hiện được hỗ trợ bằng bằng chứng, và cảnh báo được định tuyến đến Slack, email hoặc một webhook đã 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 lưu trữ của cùng một mô hình dữ liệu, cho các đội +chạy agents trên một đội: mỗi lần chạy từ mỗi công cụ ở một nơi, biểu đồ thực thi +với các sub-agents song song trên các làn riêng của chúng, độ trễ p50/p95/p99 +cho mô hình, công cụ và hook, chi phí cho 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ẻ, các đánh giá được chấm bởi +dịch vụ của riêng bạn, các kiểm toán định kỳ biến các lỗi định kỳ thành những phát hiện được hỗ trợ bằng bằng chứng, và các cảnh báo +được định tuyến đến Slack, email hoặc webhook được ký. Tự lưu trữ trong cluster của riêng bạn +có sẵn trong gói Enterprise. -→ [Phiên](https://docs.befailproof.ai/sessions/overview) · +→ [Phiên làm việc](https://docs.befailproof.ai/sessions/overview) · [Kiểm toán](https://docs.befailproof.ai/audits/overview) · [Đặt lịch demo](https://befailproof.ai/get-a-demo) @@ -214,33 +234,33 @@ Chạy `failproofai` mà không có đối số và nó sẽ phục vụ một d | 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 hoạt động của hệ thống hook | -| [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 nhanh](https://docs.befailproof.ai/start/quickstart) | Cài đặt, kết nối một công cụ, 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 công cụ được hỗ trợ](https://docs.befailproof.ai/reference/harnesses) | Tất cả 12, và những gì mỗi công cụ có thể thực thi | | Quan sát | | |---|---| -| [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ễ | +| [Phiên làm việc](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) | Những gì biểu đồ thực thi đang cho bạn biết | | [Kiểm toán](https://docs.befailproof.ai/audits/overview) | Tìm các mẫu lỗi trên nhiều phiên | -| [Dashboard cục bộ](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, không cần tài khoả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 tích hợp sẵn](https://docs.befailproof.ai/policies/builtin) | Tất cả 40 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 của riêng bạn | -| [Cấu hình](https://docs.befailproof.ai/policies/local-configuration) | Các phạm vi cấu hình và quy tắc hợp nhất | +| [Chính sách được tích hợp sẵn](https://docs.befailproof.ai/policies/builtin) | Tất cả 40 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 | -| Cài đặt agent của riêng bạn | | +| Thiết lập agents của riêng bạn | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | Báo cáo các lần chạy từ một agent mà không có harness | -| [Policy SDK](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 các lần chạy từ một agent không có công cụ | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Tham khảo `allow` / `deny` / `instruct` | --- ## Giấy phép -MIT với [Commons Clause](https://commonsclause.com/) — miễn phí cho mục đích 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. +MIT với [Commons Clause](https://commonsclause.com/) — miễn phí để sử dụng nội bộ và cá nhân; bán lại 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. --- @@ -248,9 +268,12 @@ MIT với [Commons Clause](https://commonsclause.com/) — miễn phí cho mục Xem [CONTRIBUTING.md](../../CONTRIBUTING.md). Các chính sách mới, trường hợp cạnh 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. Kho này chạy các hook của failproofai trên chính nó, và chúng giải quyết nhập `failproofai` so với gói `dist/` được biên dịch — mà không cần xây dựng bạn sẽ gặp `Cannot find package 'failproofai'` lỗi hook. Xây dựng lại sau khi thay đổi `src/`. Xem -> [Xây dựng trước khi các hook dev trong repo sẽ hoạt động](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Build trước khi bạn bắt đầu.** Chạy `bun install && bun run build` trước. 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` dựa trên +> bundled `dist/` được biên dịch — nếu không có build bạn sẽ gặp lỗi hook `Cannot find package 'failproofai'`. +> Xây dựng lại sau khi thay đổi `src/`. Xem +> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Được xây dựng với ❤️ bởi [befailproof.ai](https://befailproof.ai) tại 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 1f4265aba..a7799b293 100644 --- a/docs/i18n/README.zh.md +++ b/docs/i18n/README.zh.md @@ -18,11 +18,10 @@ [![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://docs.befailproof.ai/) [![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](../../LICENSE) -**翻译：** [简体中文](../../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) +**翻译版本：** [简体中文](../../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 -运行框架——包括 Claude Code、Codex 等编码 CLI，Hermes 等聊天网关，以及 OpenClaw 等自托管助手——捕获每一次运行，并在危险工具调用执行前将其拦截。40 条内置策略，零延迟，本地运行。 +**为每一个 Agent 运行环境提供可观测性与执行管控。** +无论你的 Agent 在哪里运行，我们都能看到——并且可以说不。Failproof 接入了 12 个 Agent 运行框架——包括 Claude Code、Codex 等编程 CLI，Hermes 等聊天网关，以及 OpenClaw 等自托管助手——捕获每一次运行，并在危险工具调用执行前将其拦截。40 条内置策略，零延迟，本地运行。 @@ -34,9 +33,9 @@ ## 支持的运行框架 -共 12 个运行框架，分为两类——10 个编码 CLI，以及 2 个聊天与助手网关（Hermes、OpenClaw）。无论你的 Agent 运行在哪个框架中，事件、策略、会话历史完全一致。 +共十二个框架，分为两类——十个编程 CLI，以及两个聊天与助手网关（Hermes、OpenClaw）。无论你的 Agent 运行在哪个框架中，事件、策略和会话历史完全一致。 -如果 Agent 不运行在上述任何框架中，可通过 [Python SDK](https://docs.befailproof.ai/reference/python-sdk) 上报数据，提供追踪、会话和审计能力。在自定义运行时中实现执行控制需要接入 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 @@ -136,28 +135,28 @@ ```sh npm install -g failproofai -failproofai policies --install # 或直接运行 `failproofai` 并在首次运行提示中确认 +failproofai policies --install # 或直接运行 `failproofai` 并在首次运行提示时确认 failproofai ``` -40 条内置策略立即生效。控制台地址：`localhost:8020`。如需禁用首次运行提示，设置 `FAILPROOFAI_NO_FIRST_RUN=1`。 +40 条内置策略立即生效。Dashboard 地址：`localhost:8020`。可通过设置 `FAILPROOFAI_NO_FIRST_RUN=1` 禁用首次运行提示。 --- -## 能拦截什么 +## 拦截范围 | 策略 | 拦截内容 | |---|---| -| `sanitize-api-keys` | API 密钥泄漏到 Agent 上下文中 | +| `sanitize-api-keys` | API 密钥泄露到 Agent 上下文 | | `block-env-files` | 读取 `.env` 及其他密钥文件 | -| `warn-repeated-tool-calls` | Agent 在同一调用上陷入循环 | +| `warn-repeated-tool-calls` | Agent 在同一调用上循环执行 | | `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`、直接推送到 `main` | -前五条适用于任何能调用工具的 Agent，后三条是开发者最爱——编码 CLI 是我们覆盖最深入的框架类别。 +前五条适用于任何可以调用工具的 Agent，后三条是开发者最爱——编程 CLI 是我们覆盖最深入的框架类型。 → [全部 40 条内置策略](https://docs.befailproof.ai/policies/builtin) @@ -165,7 +164,7 @@ failproofai ## 自定义策略 -将文件放入 `.failproofai/policies/` 目录即可自动加载，无需任何参数。提交到代码库后，团队所有成员在下次拉取时即可生效。 +将文件放入 `.failproofai/policies/` 目录即可自动加载，无需任何参数。提交到代码仓库后，全团队在下次拉取时即可生效。 ```js import { customPolicies, deny, allow } from "failproofai"; @@ -186,8 +185,8 @@ customPolicies.add({ | 决策 | 效果 | |---|---| | `allow()` | 允许该操作 | -| `deny(message)` | 拦截操作——消息回传给 Agent | -| `instruct(message)` | 放行，但在 Agent 的下一个提示词中追加上下文 | +| `deny(message)` | 拦截操作——消息返回给 Agent | +| `instruct(message)` | 放行操作，但在 Agent 的下一次提示中附加上下文信息 | → [自定义策略指南](https://docs.befailproof.ai/policies/custom) @@ -195,18 +194,18 @@ customPolicies.add({ ## 可观测性 -执行控制是一半，另一半是看清 Agent 实际做了什么。 +执行管控是一半，另一半是看清 Agent 实际做了什么。 -不带参数运行 `failproofai`，它会在 `localhost:8020` 提供一个控制台，读取已保存在本机的运行历史——无需账号，无需注册，数据不离开本机。你可以查看会话列表、每次运行中的模型调用序列、工具调用与 Hook 决策，以及哪些操作被拦截、策略向 Agent 传达了什么内容；还有离线审计功能（`failproofai audit`），可扫描历史记录中的风险模式并推荐相应策略。 +不带任何参数运行 `failproofai`，它会在 `localhost:8020` 启动一个 Dashboard，读取已存储在本机的运行历史——无需账户，无需注册，数据不离开本机。你可以查看会话列表、每次运行中模型调用和工具调用的序列、hook 决策记录、哪些操作被拦截、策略向 Agent 传达了什么，以及离线审计（`failproofai audit`）——它会扫描你的历史记录，发现风险模式并推荐相应策略。 -→ [本地控制台](https://docs.befailproof.ai/reference/local-dashboard) · -[解读追踪记录](https://docs.befailproof.ai/sessions/read-a-trace) · +→ [本地 Dashboard](https://docs.befailproof.ai/reference/local-dashboard) · +[读取追踪记录](https://docs.befailproof.ai/sessions/read-a-trace) · [本地审计](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI 可观测性**是同一数据模型的托管版本，面向在多台机器上运行 Agent 的团队：所有框架的每一次运行汇聚一处，带并行子 Agent 独立泳道的执行图，模型、工具与 Hook 的 p50/p95/p99 延迟，按模型统计的费用与上下文窗口追踪，错误追踪，基于自有追踪数据的 SQL 查询与可分享的控制台，由你自己的服务评分的评测，将重复失败转化为有据可查结论的定期审计，以及路由至 Slack、邮件或签名 Webhook 的告警。企业版支持在自有集群中自托管。 +**Failproof AI 可观测性**是同一数据模型的托管端，面向在集群中跨多个框架运行 Agent 的团队：所有框架的每次运行集中呈现，带有并行子 Agent 独立泳道的执行图，模型、工具和 hook 的 p50/p95/p99 延迟，按模型的费用和上下文窗口跟踪，错误追踪，基于自有 trace 数据的 SQL 查询与可分享 Dashboard，由你自己的服务评分的评估结果，将重复失败转化为有据可查发现的定时审计，以及路由到 Slack、邮件或签名 Webhook 的告警。在企业版计划中支持在你自己的集群中自托管部署。 -→ [会话](https://docs.befailproof.ai/sessions/overview) · -[审计](https://docs.befailproof.ai/audits/overview) · +→ [Sessions](https://docs.befailproof.ai/sessions/overview) · +[Audits](https://docs.befailproof.ai/audits/overview) · [预约演示](https://befailproof.ai/get-a-demo) --- @@ -215,43 +214,42 @@ customPolicies.add({ | 入门 | | |---|---| -| [快速开始](https://docs.befailproof.ai/start/quickstart) | 安装、接入运行框架、查看第一次运行 | +| [快速开始](https://docs.befailproof.ai/start/quickstart) | 安装、接入框架、查看首次运行结果 | | [核心概念](https://docs.befailproof.ai/start/concepts) | Hook 系统的工作原理 | -| [支持的运行框架](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/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) | 跟踪运行过程：模型、工具、错误、延迟 | +| [读取追踪记录](https://docs.befailproof.ai/sessions/read-a-trace) | 执行图所反映的信息 | +| [Audits](https://docs.befailproof.ai/audits/overview) | 跨多个会话发现失败模式 | +| [本地 Dashboard](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`，无需账户 | -| 执行控制 | | +| 执行管控 | | |---|---| | [内置策略](https://docs.befailproof.ai/policies/builtin) | 全部 40 条策略及参数说明 | | [自定义策略](https://docs.befailproof.ai/policies/custom) | 编写你自己的策略 | -| [配置](https://docs.befailproof.ai/policies/local-configuration) | 配置作用域与合并规则 | +| [配置说明](https://docs.befailproof.ai/policies/local-configuration) | 配置作用域与合并规则 | -| 接入你自己的 Agent | | +| 接入自定义 Agent | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/python-sdk) | 从无框架的 Agent 上报运行数据 | -| [策略 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`。本仓库会将 failproofai 自身的 Hook 应用于自身，这些 Hook 会从编译后的 `dist/` 包中解析 `failproofai` 导入——如果未构建，你会遇到 `Cannot find package 'failproofai'` 的 Hook 错误。修改 `src/` 后请重新构建。详见 -> [构建后才能使用仓库内开发 Hook](../../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/` 后需重新构建。详见 [Build before the in-repo dev hooks will work](../../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/index.mdx b/docs/it/index.mdx index 5a38b7ebc..06b415eba 100644 --- a/docs/it/index.mdx +++ b/docs/it/index.mdx @@ -1,40 +1,40 @@ --- -title: "Rendi il tuo agente a prova di errore" -description: "Osservabilità e enforcement per ogni harness in cui i tuoi agenti vengono eseguiti — coding CLI, gateway di chat, assistenti self-hosted e i tuoi agenti strumentati." +title: "Rendi il tuo agent failproof" +description: "Osservabilità e enforcement per ogni harness che i tuoi agent eseguono — coding CLI, chat gateway, assistenti self-hosted e i tuoi agent strumentati." icon: "shield-check" --- -Failproof AI aiuta i team a capire cosa hanno fatto gli agenti, a individuare dove hanno fallito e a distribuire protezioni prima che lo stesso comportamento si ripeta. +Failproof AI aiuta i team a capire cosa hanno fatto gli agent, trovare dove hanno fallito e implementare salvaguardie prima che lo stesso comportamento si ripeta. -Un **harness** è ciò in cui il tuo agente viene effettivamente eseguito. Failproof AI si integra con 12 di essi — coding CLI come Claude Code e Codex, gateway di chat come Hermes, assistenti self-hosted come OpenClaw — e gli stessi eventi, le stesse policy e la stessa cronologia delle sessioni si applicano a tutti. Gli agenti senza harness inviano report attraverso l'[SDK Python](/it/reference/custom-agents), che li traccia e li audita; l'enforcement di una policy lì richiede un hook nel tuo runtime. +Un **harness** è tutto ciò in cui il tuo agent effettivamente esegue. Failproof AI si aggancia a 12 di essi — coding CLI come Claude Code e Codex, chat gateway come Hermes, assistenti self-hosted come OpenClaw — e gli stessi eventi, le stesse policy e la stessa cronologia sessione si applicano a ognuno. Gli agent senza harness inviano i dati tramite l'[SDK Python](/it/reference/custom-agents), che li traccia e audita; per applicare una policy lì serve un hook nel tuo runtime. - Usa lo skill per strumentare il tuo progetto, collegarlo e verificare che i log degli agenti arrivino. + Usa lo skill per strumentare il tuo progetto, connetterlo e verificare che i log degli agent arrivino. - Analizza, interroga, crea dashboard ed esegui audit nel linguaggio naturale sui log dei tuoi agenti. + Analizza, interroga, crea dashboard ed esegui audit in linguaggio naturale sui log dei tuoi agent. - - Segui le chiamate ai modelli, i tool, gli errori, l'input umano, la latenza e le decisioni delle policy in una sessione. + + Segui chiamate ai modelli, tool, errori, input umano, latenza e decisioni di policy in una sessione. - Audita una serie definita di sessioni, rivedi i risultati supportati da prove e traccia la remediation come issue. + Audita un set definito di sessioni, rivedi i risultati supportati da evidenze e traccia la correzione come issue. - Trasforma una modalità di fallimento nota in una policy, osserva il suo impatto e distribuiscila tra la tua flotta. + Trasforma una modalità di fallimento nota in una policy, osserva il suo impatto e distribuiscila nella tua flotta. > **Sessione → Audit → Risultato → Issue → Policy**
-> Traccia cosa è successo, trova il fallimento, gestisci la risposta, quindi previeni lo stesso comportamento nelle esecuzioni future. +> Traccia cosa è successo, trova il fallimento, gestisci la risposta, poi previeni lo stesso comportamento nelle esecuzioni future. -## Inizia da qui +## Inizia qui -Se stai distribuendo il tuo primo agente strumentato, inizia con la [guida rapida](/it/start/quickstart). Se i dati stanno già arrivando, apri [Sessioni](/it/sessions/overview) e ispeziona un'esecuzione reale prima di configurare gli audit o le policy. +Se stai distribuendo il tuo primo agent strumentato, inizia con la [quickstart](/it/start/quickstart). Se i dati stanno già arrivando, apri [Sessions](/it/sessions/overview) e ispeziona un'esecuzione reale prima di configurare audit o policy. Completa il workflow end-to-end dalla cattura a una policy distribuita in modo sicuro. diff --git a/docs/it/policies/deploy.mdx b/docs/it/policies/deploy.mdx index 838e478c1..b4f86a2f3 100644 --- a/docs/it/policies/deploy.mdx +++ b/docs/it/policies/deploy.mdx @@ -1,47 +1,51 @@ --- title: "Distribuire i criteri" -description: "Implementa una versione di criterio revisione sulle macchine designate." +description: "Distribuisci una versione di criterio rivista alle macchine di destinazione." icon: "cloud-upload" --- -Una distribuzione collega una o più versioni di criterio a un set di macchine iscritte designate. +Una distribuzione collega una o più versioni di criterio a un set mirato di macchine registrate. ## Applicare una distribuzione 1. Vai a **Admin → enforcement**, trova la macchina ed espandi la sua riga. - 2. Seleziona **edit**, aggiungi la versione di criterio revisionata e scegli **observe** o il suo effetto di applicazione. - 3. Applica la modifica, quindi attendi il prossimo check-in della macchina e conferma lo stato della sua distribuzione e copertura. + 2. Seleziona **edit**, aggiungi la versione di criterio rivista e scegli **observe** o il suo effetto di applicazione. + 3. Applica la modifica, quindi attendi il successivo check-in della macchina e conferma lo stato di distribuzione e copertura. 4. Vai a **Observe → policy** per ispezionare le decisioni in tempo reale. - ![L'editor di distribuzione della macchina con versioni di criteri, effetti enforce e observe, e l'azione di applicazione della distribuzione.](/images/dashboard/enforcement-editor.png) + ![L'editor di distribuzione della macchina con versioni dei criteri, effetti enforce e observe e l'azione di distribuzione applicata.](/images/dashboard/enforcement-editor.png) - Gli endpoint di distribuzione Cloud non sono intenzionalmente esposti come comandi `fp` ordinari. Controlla la macchina localmente, quindi esegui la distribuzione tramite il dashboard: + Distribuisci dalla CLI con `fp fleet`. Rivedi il set risultante prima di applicarlo — `deploy` stampa il piano completo e chiede **solo su un terminale interattivo senza `--json`**. Con `--json`, con `--yes`, o con stdin reindirizzato (un step CI, uno script, un agente che si avvia) applica immediatamente senza piano e senza prompt — quindi esegui prima `fp fleet show ` se desideri una revisione: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - Utilizza `fp sessions --env production --since 24h` e `fp events --event-type hook_completed` dopo la distribuzione per verificare che l'attività raggiunga Cloud. + `fp fleet diff ` mostra l'intenzione rispetto alla consegna (una macchina si legge come `behind` finché non esegue il successivo polling), `fp fleet history ` elenca le generazioni, e `fp fleet rollback ` ripristina una — rifiuta se quella generazione nomina un criterio da allora disabilitato o eliminato. + + 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. - - Distribuisci una versione revisionata, non una bozza mutabile, iniziando da una macchina non in produzione o un piccolo gruppo le cui sessioni puoi ispezionare. + + Distribuisci una versione rivista, non una bozza mutabile, iniziando con una macchina non in produzione o un piccolo gruppo le cui sessioni puoi ispezionare. - Esamina i match, i motivi, gli strumenti interessati e i falsi positivi senza bloccare il lavoro. + Rivedi i match, i motivi, gli strumenti interessati e i falsi positivi senza bloccare il lavoro. - Promuovi dopo che i match osservati separano le azioni non sicure da quelle valide, quindi conferma che ogni macchina designata ha scaricato la distribuzione e sta segnalando le decisioni. + Promuovi dopo che i match osservati separano le azioni non sicure da quelle valide, quindi conferma che ogni macchina prevista ha scaricato la distribuzione e sta segnalando le decisioni. -Le macchine necessitano della capacità `policies:pull`. La segnalazione degli eventi è controllata separatamente da `events:add`; verifica entrambe quando prevedi analisi e applicazione Cloud. +Le macchine necessitano della capacità `policies:pull`. La segnalazione degli eventi è controllata separatamente da `events:add`; verifica entrambe quando prevedi analisi e applicazione di Cloud. - La gestione dell'applicazione è un flusso di lavoro Cloud amministrativo. Non trattare le route di applicazione solo root come endpoint API `/v1` ordinari dei clienti. + La gestione dell'applicazione è un flusso di lavoro amministrativo di Cloud. Non trattare le route di applicazione di sola root come endpoint API `/v1` ordinari per i clienti. \ No newline at end of file diff --git a/docs/it/policies/editor.mdx b/docs/it/policies/editor.mdx index 2cdea2675..2c85e5970 100644 --- a/docs/it/policies/editor.mdx +++ b/docs/it/policies/editor.mdx @@ -1,47 +1,49 @@ --- -title: "Editor di criteri" -description: "Crea e rivedi criteri versionati partendo da una modalità di errore confermata." +title: "Editor criteri" +description: "Crea e rivedi i criteri con versione a partire da una modalità di errore confermata." icon: "file-pen-line" --- -Usa l'editor di 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. +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. -Quando un problema presenta un modello di azione ripetibile, aprilo da **Analyze → issues** e seleziona **generate policy**. Failproof AI spiega innanzitutto se un criterio può esprimere il problema, quindi trasporta l'intento revisionato e il contesto del risultato nell'editor. Il sorgente generato rimane una bozza finché non lo pubblichi. +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. ## Pubblica una versione del criterio - 1. Vai a **Admin → policy editor** e, in **compose**, descrivi la modalità di errore o incolla il sorgente della politica JavaScript. - 2. Valida il sorgente e correggi ogni errore segnalato. - 3. Inserisci l'identità del criterio e pubblicalo, quindi usa **library** per confrontare o disabilitare versioni. - 4. Seleziona **enforcement** quando la versione è pronta per un rollout delle macchine. + 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. - ![La vista compose dell'editor di criteri con identità del criterio, redazione assistita da IA, convalida del sorgente e controlli di pubblicazione.](/images/dashboard/policy-editor.png) + ![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 Cloud CLI non pubblica versioni dei criteri. Valida il sorgente localmente prima di copiarlo nell'editor: + 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: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - Pubblica la versione revisionata da **Admin → policy editor**. + 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`. ## Checklist di creazione -1. Nomina la modalità di errore in linguaggio operativo. +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 dica all'agente o all'operatore cosa fare dopo. +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. -Usa `instruct` quando l'agente può correggere il corso in modo sicuro. Usa `deny` quando consentire l'azione comporterebbe un rischio inaccettabile o irreversibile. +Utilizza `instruct` quando l'agente può correggere il corso in modo sicuro. Utilizza `deny` quando consentire l'azione comporterebbe un rischio inaccettabile o irreversibile. - Le versioni dei criteri sono input di distribuzione immutabili. Modificare una bozza crea una nuova versione; non dovrebbe riscrivere la versione già assegnata alle macchine. + 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 diff --git a/docs/it/reference/cloud-cli.mdx b/docs/it/reference/cloud-cli.mdx index 22349ae90..ab847d685 100644 --- a/docs/it/reference/cloud-cli.mdx +++ b/docs/it/reference/cloud-cli.mdx @@ -4,9 +4,9 @@ description: "Riferimento completo per interrogare e amministrare Failproof AI C icon: "cloud-cog" --- -Usa `fp` per ispezionare la telemetria Cloud e gestire audit, findings, issues, alert, chiavi, utenti, query e impostazioni. Usa [`failproofai`](/it/reference/failproof-cli) per hook locali, policies, capture e enrollment delle macchine. +Usa `fp` per ispezionare la telemetria Cloud, gestire l'enforcement gestito dal cloud (politiche, deployment di flotta, decisioni di guardrail) e gestire audit, risultati, problemi, avvisi, chiavi, utenti, query e impostazioni. Usa [`failproofai`](/it/reference/failproof-cli) per hook locali, politiche, acquisizione e iscrizione di macchine. -Installa la CLI Cloud rilasciata come strumento isolato: +Installa la Cloud CLI rilasciata come strumento isolato: ```bash uv tool install fp-cloud-cli @@ -32,7 +32,7 @@ Le opzioni globali devono precedere il 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 la guida del terminale. ## Comandi CLI @@ -40,11 +40,11 @@ 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 via email e seleziona un'organizzazione. | `--email`, `-e`; `--org`; `--force` | +| `fp login` | Accedi con un codice monouso inviato per posta 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 version` | Mostra la versione CLI installata. | — | -| `fp help` | Mostra l'aiuto per i comandi di primo livello. | — | +| `fp version` | Mostra la versione della CLI installata. | — | +| `fp help` | Mostra la guida dei comandi di livello superiore. | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,30 +57,34 @@ fp whoami fp events [OPTIONS] ``` -Elenca i singoli eventi degli agent. Il feed leggero predefinito esclude i payload grezzi; usa `--full` solo per un'indagine delimitata. +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 ` | 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. | +| `--env ` | Filtro ambiente; ripeti o separa con virgola i valori. | +| `--event-type ` | Filtro tipo evento; ripeti o separa con virgola i valori. | +| `--agent-id ` | Filtro agente; ripeti o separa con virgola i valori. | +| `--session-id ` | Filtro sessione; ripeti o separa con virgola i valori. | | `--search ` | Ricerca testo nel payload; ripetibile, qualsiasi termine corrisponde. | -| `--order asc\|desc` | Ordine temporale. Predefinito: più recente per primo. | -| `--all` | Auto-paginazione fino a `--limit`. | +| `--order asc\|desc` | Ordine temporale. Predefinito: più recenti per primi. | +| `--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 tramite l'endpoint evento più pesante. | | `--fields ` | Restituisci solo i campi selezionati; richiedere `payload` abilita la modalità completa. | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` + + `--all` esegue la paginazione **fino a `--limit`**, che per impostazione predefinita è **50** — quindi `--all` da solo si ferma a 50 righe. Quando si ferma anticipatamente, la risposta contiene un `next_cursor` per riprendere; `"next_cursor": null` significa che il feed è effettivamente esaurito. + + ### Sessioni ```text @@ -92,16 +96,16 @@ fp sessions [OPTIONS] | `--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. | +| `--env ` | Filtro ambiente; ripeti o separa con virgola i valori. | | `--status ` | `done`, `error`, o `timeout`; ripeti o separa con virgola i valori. | -| `--agent-id ` | Abbina sessioni che coinvolgono un agent selezionato qualsiasi. | -| `--session-id ` | Filtro per sessione; ripeti o separa con virgola i valori. | -| `--all` | Auto-paginazione fino a `--limit`. | +| `--agent-id ` | Corrisponde a sessioni che coinvolgono qualsiasi agente selezionato. | +| `--session-id ` | Filtro sessione; ripeti o separa con virgola i valori. | +| `--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 sessione nell'output del terminale. | -| `--agents` | Espandi il roster degli agent per sessioni multi-agent. | +| `--agents` | Espandi l'elenco degli agenti per sessioni multi-agente. | ### Valutazioni @@ -112,10 +116,10 @@ fp evals [OPTIONS] | Opzione | Descrizione | | --- | --- | | `--aggregate` | Mostra totali e statistiche per punteggio invece di valutazioni individuali. | -| `--limit`, `-n ` | Numero massimo di righe nell'elenco. Predefinito: `50`. | +| `--limit`, `-n ` | Numero massimo di righe dell'elenco. Predefinito: `50`. | | `--since`, `--from`, `--to` | Seleziona l'intervallo di tempo. | -| `--env`, `--status`, `--agent-id`, `--session-id` | Ristretti a un valore esatto per filtro. | -| `--score KEY:MIN..MAX` | Intervallo punteggi; 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 di 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 sessione completi. | @@ -130,9 +134,9 @@ fp errors [OPTIONS] | Opzione | Descrizione | | --- | --- | | `--aggregate` | Riassumi gli errori corrispondenti invece di elencare le righe. | -| `--limit`, `-n ` | Numero massimo di righe nell'elenco. Predefinito: `50`. | +| `--limit`, `-n ` | Numero massimo di righe dell'elenco. Predefinito: `50`. | | `--since`, `--from`, `--to` | Seleziona l'intervallo di tempo. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Restringi la popolazione di errori. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Limita la popolazione di errori. | | `--search ` | Ricerca testo nel payload; ripetibile. | | `--order asc\|desc` | Ordine temporale. | | `--all`, `--cursor`, `--page-size` | Controlla la paginazione dell'elenco. | @@ -143,9 +147,9 @@ fp errors [OPTIONS] | Comando | Scopo | | --- | --- | -| `fp usage` | Mostra l'utilizzo per la finestra di conteggio corrente. | +| `fp usage` | Mostra l'utilizzo per la finestra di misurazione attuale. | | `fp list envs` | Elenca gli ambienti osservati. | -| `fp list agents` | Elenca gli ID 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 dei punteggi di valutazione. | | `fp list models` | Elenca i nomi dei modelli. | @@ -158,7 +162,7 @@ fp errors [OPTIONS] | Comando | Scopo | | --- | --- | | `fp orgs list` | Elenca le organizzazioni accessibili. | -| `fp orgs switch [SLUG]` | Salva un'organizzazione attiva; chiede quando omesso. | +| `fp orgs switch [SLUG]` | Salva un'organizzazione attiva; richiede quando omesso. | | `fp orgs current` | Mostra l'organizzazione attiva. | | `fp orgs perms` | Mostra i tuoi permessi nell'organizzazione attiva. | @@ -167,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 le sue concessioni. | — | +| `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 le concessioni. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `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 la sostituzione una volta. | `--yes`, `-y` | | `fp keys disable NAME` | Revoca permanentemente una chiave. | `--yes`, `-y` | -I token di permesso usano il formato `resource:action`, come `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`, separa con virgola i token o usa azioni puntate come `events:read.add`. ### Query @@ -184,17 +188,17 @@ I token di permesso usano il formato `resource:action`, come `events:add`. Ripet | `fp query create NAME` | Salva una query. | `--sql `; `--description` | | `fp query update NAME` | Aggiorna o rinomina una query. | `--name`; `--sql`; `--description`; `--yes`, `-y` | | `fp query delete NAME` | Elimina una query salvata. | `--yes`, `-y` | -| `fp query run [NAME]` | Esegui una query salvata o SQL ad hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | -| `fp query schema [TABLE]` | Elenca le tabelle interrogabili o ispezionane una. | — | +| `fp query run [NAME]` | Esegui una query salvata o SQL ad-hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query schema [TABLE]` | Elenca le tabelle interrogabili o ispeziona una tabella. | — | ### Utenti | Comando | Scopo | Opzioni | | --- | --- | --- | | `fp users list` | Elenca i membri dell'organizzazione. | `--active-only`; `--show-id` | -| `fp users show EMAIL` | Mostra un membro e le sue concessioni. | — | +| `fp users show EMAIL` | Mostra un membro e i suoi grant. | — | | `fp users create EMAIL` | Aggiungi un membro. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | Cambia le concessioni di un membro. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users update EMAIL` | Cambia i grant 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` | @@ -202,22 +206,22 @@ I token di permesso usano il formato `resource:action`, come `events:add`. Ripet | Comando | Scopo | Opzioni | | --- | --- | --- | -| `fp settings list` | Elenca le impostazioni dell'organizzazione e i valori correnti. | — | +| `fp settings list` | Elenca le impostazioni dell'organizzazione e i valori attuali. | — | | `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`; opzionale `--yes`, `-y` | -### Alert +### Avvisi | Comando | Scopo | Opzioni | | --- | --- | --- | -| `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 delete NAME` | Elimina un alert. | `--yes`, `-y` | +| `fp alerts list` | Elenca le regole di avviso. | `--show-id` | +| `fp alerts show NAME` | Mostra un avviso. | — | +| `fp alerts create NAME` | Crea un avviso. | `--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window` | +| `fp alerts update NAME` | Aggiorna o rinomina un avviso. | opzioni di creazione più `--name`; `--yes`, `-y` | +| `fp alerts delete NAME` | Elimina un avviso. | `--yes`, `-y` | | `fp alerts test NAME` | Invia una notifica di test. | `--channels`; `--yes`, `-y` | -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. +Le severità di avviso 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 @@ -225,24 +229,24 @@ 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 il suo stato. | — | -| `fp audits create NAME` | Crea un audit e accodati immediatamente la sua prima esecuzione. | Vedi [opzioni di creazione](#audit-create-options). | -| `fp audits edit NAME` | Sostituisci le impostazioni dell'audit mantenendo i valori non specificati. | opzioni di definizione della creazione; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | Elimina un audit, i suoi findings e la cronologia delle esecuzioni. | `--yes`, `-y` | +| `fp audits create NAME` | Crea un audit e accodaci 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 della creazione; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | Elimina un audit, i suoi risultati e la cronologia delle esecuzioni. | `--yes`, `-y` | | `fp audits run NAME` | Accoda un'esecuzione manuale. | — | | `fp audits runs NAME` | Elenca la cronologia delle esecuzioni. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | Mostra il brief e lo stato di recupero dell'URL di riferimento. | — | -| `fp audits context-set NAME` | Cambia il brief o gli URL di riferimento. | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | Ri-scarica 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 le sue prove. | — | -| `fp audits ack FINDING_ID` | Riconosci un finding. | `--reason` | +| `fp audits context-show NAME` | Mostra il breve e lo stato di recupero dell'URL di riferimento. | — | +| `fp audits context-set NAME` | Cambia il breve o gli URL di riferimento. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-refresh NAME` | Recupera nuovamente gli URL di riferimento. | — | +| `fp audits findings` | Elenca i risultati. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | +| `fp audits finding FINDING_ID` | Mostra un risultato e le sue prove. | — | +| `fp audits ack FINDING_ID` | Riconosci un risultato. | `--reason` | | `fp audits mute FINDING_ID` | Sopprimere un pattern ricorrente. | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | Contrassegna un pattern come non attuabile e sopprimilo. | `--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 attiva e cancella la soppressione. | — | -| `fp audits assign FINDING_ID` | Imposta il proprietario del finding. | `--to ` obbligatorio | +| `fp audits dismiss FINDING_ID` | Contrassegna un pattern come non azionabile e sopprimilo. | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | Contrassegna un risultato come risolto senza soppressione futura. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | Restituisci un risultato alla coda in diretta e cancella la soppressione. | — | +| `fp audits assign FINDING_ID` | Imposta il proprietario del risultato. | `--to ` obbligatorio | -#### Opzioni di creazione dell'audit +#### Opzioni di creazione audit ```bash fp audits create checkout-reliability \ @@ -259,93 +263,137 @@ fp audits create checkout-reliability \ | --- | --- | | `--file ` | Basa la definizione su JSON, o usa `-` per stdin. I flag espliciti sostituiscono i valori del file. | | `--description ` | Dichiara la domanda di fallimento o lo scopo. | -| `--enabled` / `--disabled` | Avvia la pianificazione attiva o disattivata. Predefinito: abilitato. | +| `--enabled` / `--disabled` | Avvia la pianificazione attivata o disattivata. 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 formato 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 i tipi di errore; ripeti o separa con virgola. | -| `--llm` / `--no-llm` | Abilita o disabilita l'analisi agentica. Predefinito: abilitato. | -| `--top-k ` | Mantieni `1`–`500` findings. Predefinito: `50`. | -| `--sensitivity low\|medium\|high` | Imposta la sensibilità di segnalazione. Predefinito: `medium`. | +| `--scope ''` | Filtra per `environments`, `agent_ids` o altri campi di scope supportati. | +| `--ignore-error-type ` | Escludi tipi di errore; ripeti o separa con virgola. | +| `--llm` / `--no-llm` | Abilita o disabilita l'analisi agentiva. Predefinito: abilitato. | +| `--top-k ` | Mantieni risultati `1`–`500`. Predefinito: `50`. | +| `--sensitivity low\|medium\|high` | Imposta la sensibilità del reporting. Predefinito: `medium`. | | `--channels ''` | Array di canali di notifica. | -| `--text ` | Brief inline, massimo 8.192 caratteri. | -| `--text-file ` | Leggi il brief da un file; mutuamente esclusivo con `--text`. | +| `--text ` | Breve inline, massimo 8.192 caratteri. | +| `--text-file ` | Leggi il 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 confirma la definizione e il contesto insieme prima che l'esecuzione in coda inizi. +Includi il contesto durante la creazione quando la prima esecuzione lo necessita. La creazione esegue il commit della definizione e del contesto insieme prima che inizi l'esecuzione in coda. - `fp audits run` è asincrono. Esegui il polling di `fp audits runs NAME` finché l'esecuzione più recente non riesce o fallisce prima di leggere i suoi findings. + `fp audits run` è asincrono. Esegui il polling di `fp audits runs NAME` fino a quando l'ultima esecuzione non riesce o non fallisce prima di leggerne i risultati. -### Issues +### Problemi | Comando | Scopo | Opzioni | | --- | --- | --- | -| `fp issues list` | Elenca le issues. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | Conta le issues aperte o i stati selezionati. | `--state` | -| `fp issues show INCIDENT_ID` | Mostra i dettagli dell'issue, i commenti, i sottoscritti e l'attività. | — | -| `fp issues open` | Apri una issue manuale o collegata a un alert. | `--summary` obbligatorio; opzionale `--title`, `--alert-id`, `--severity` | -| `fp issues ack INCIDENT_ID` | Riconosci una issue. | — | +| `fp issues list` | Elenca i problemi. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | Conta gli stati di problema aperti o selezionati. | `--state` | +| `fp issues show INCIDENT_ID` | Mostra i dettagli del problema, i commenti, gli abbonati e l'attività. | — | +| `fp issues open` | Apri un problema manuale o collegato a un avviso. | `--summary` obbligatorio; opzionali `--title`, `--alert-id`, `--severity` | +| `fp issues ack INCIDENT_ID` | Riconosci un problema. | — | | `fp issues assign INCIDENT_ID` | Sostituisci gli assegnatari; ometti l'opzione per cancellarli. | `--assignee` ripetibile | -| `fp issues resolve INCIDENT_ID` | Risolvi una issue. | `--yes`, `-y` | +| `fp issues resolve INCIDENT_ID` | Risolvi un problema. | `--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-delete INCIDENT_ID COMMENT_ID` | Elimina un commento. | `--yes`, `-y` | -| `fp issues subscribers INCIDENT_ID` | Elenca i sottoscritti. | — | -| `fp issues subscribe INCIDENT_ID` | Sottoscrivi te stesso o un altro operatore. | `--email` | -| `fp issues unsubscribe INCIDENT_ID` | Rimuovi una sottoscrizione. | `--email` | +| `fp issues subscribers INCIDENT_ID` | Elenca gli abbonati. | — | +| `fp issues subscribe INCIDENT_ID` | Abbonati a te stesso o a un altro operatore. | `--email` | +| `fp issues unsubscribe INCIDENT_ID` | Rimuovi un abbonamento. | `--email` | -Gli stati validi delle issues sono `firing`, `acknowledged` e `resolved`. Le severità delle issues autonome sono `info`, `warning` e `critical`. +Gli stati di problema validi sono `firing`, `acknowledged` e `resolved`. Le severità di problema autonomo sono `info`, `warning` e `critical`. -### Assistente Cloud +### Assistente cloud | Comando | Scopo | Opzioni | | --- | --- | --- | | `fp agent health` | Verifica la disponibilità e la configurazione dell'assistente. | — | -| `fp agent models` | Elenca i modelli dell'assistente disponibili. | — | +| `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; leggi stdin quando il messaggio viene omesso. | `--chat`; `--model`; `--page-context` | +| `fp agent ask [MESSAGE]` | Inizia o continua una chat; legge 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. | `--title` obbligatorio | | `fp agent delete CHAT_ID` | Elimina una conversazione. | `--yes`, `-y` | +### Politiche + +Versioni di politica gestite dal cloud. **Solo per 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`. + +| Comando | Scopo | Opzioni | +| --- | --- | --- | +| `fp policies list` | Elenca le versioni di politica. | `--json` | +| `fp policies show POLICY_ID` | Mostra una politica, con la sua fonte. | — | +| `fp policies publish NAME PATH` | Conia una versione da un `.mjs` locale. | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | Aggiungila nuovamente a ogni deployment da cui è stata rimossa, coniando una nuova generazione su ciascuna. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | Rimuovila da ogni deployment che la contiene, coniando 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 rispetto a un contesto sintetico. Applica il filtro `match` di ciascuna politica, quindi una che non copre l'evento/strumento specificato viene segnalata come `skipped` piuttosto che eseguita. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | +| `fp policies compose PROMPT` | Bozza una politica con l'assistente. Necessita `policies:write`. | — | + +### Flotta + +Quali macchine eseguono quali politiche. **Solo per sessione**, stesso motivo sopra. + +| Comando | Scopo | Opzioni | +| --- | --- | --- | +| `fp fleet list` | Elenca le macchine iscritte e la loro generazione di deployment. | — | +| `fp fleet show MACHINE_ID` | L'insieme di politiche che una macchina attualmente esegue. | — | +| `fp fleet deploy MACHINE_ID` | **Sostituisce l'intero insieme 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 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. | `--name` obbligatorio | + +### Guardrail + +Quello che l'enforcement ha effettivamente fatto. **Solo per sessione**, stesso motivo sopra. + +| Comando | Scopo | Opzioni | +| --- | --- | --- | +| `fp guardrails summary` | Copertura, totali bloccati/valutati, una sparkline di rifiuto e la tabella per politica. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Decisioni suddivise per la finestra, sommate in 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 self-hosted o di sviluppo. | -| `--org ` | Seleziona un'organizzazione per questa invocazione. | -| `--token ` | Sostituisci il token di sessione utente salvato. | +| `--org ` | Seleziona un'organizzazione per questo invocazione. | +| `--token ` | Sostituisci il token della sessione utente salvato. | | `--api-key ` | Autentica l'automazione con una chiave API; mai salvata. | | `--timeout ` | Timeout HTTP; deve essere positivo. Predefinito: `30`. | | `--quiet`, `-q` | Sopprimere l'output di stato su stderr. | | `--no-color` | Disabilita l'output colorato. | | `--insecure` / `--secure` | Disabilita o ripristina la verifica del certificato TLS. | -| `--version` | Stampa la versione non racchiusa ed esci. | -| `--help`, `-h` | Mostra l'aiuto. | +| `--version` | Stampa la versione non contenuta ed esci. | +| `--help`, `-h` | Mostra la guida. | -`--api-key` è destinato all'automazione. L'accesso, il passaggio di organizzazione e i comandi dell'assistente richiedono una sessione utente. +`--api-key` è destinato all'automazione. L'accesso, il cambio di organizzazione e i comandi di assistente richiedono una sessione utente. -## Variabili di ambiente +## Variabili d'ambiente | Variabile | Equivalente o scopo | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | Rilocalizza la directory di configurazione CLI corrente. | -| `AGENTEYE_ANALYTICS_DISABLED` o `DO_NOT_TRACK` | Disabilita l'analytics CLI anonima. | +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `FP_API_KEY` | `--api-key` | +| `FP_JSON` | `--json` | +| `FP_INSECURE` | `--insecure` | +| `FP_HOME` | Riloca la directory di configurazione della CLI (predefinito `~/.failproofai/fpcli`). | +| `FP_ANALYTICS_DISABLED` o `DO_NOT_TRACK` | Disabilita l'analittica CLI anonima. | | `NO_COLOR` | Disabilita l'output colorato. | -I flag espliciti sostituiscono le variabili di ambiente, che sostituiscono la configurazione salvata. In modalità chiave API, seleziona il tenant esplicitamente con `--org` o `AGENTEYE_ORG`. +I flag espliciti sostituiscono le variabili d'ambiente, che sostituiscono la configurazione salvata. In modalità chiave API, seleziona esplicitamente il tenant con `--org` o `FP_ORG`. + + + Le ortografie `AGENTEYE_*` di questi **non sono lette da `fp`** e non lo sono mai state — la CLI dichiara `FP_*` (`fp_cli/app.py`), e una variabile sconosciuta non è un errore. L'impostazione di `AGENTEYE_DASHBOARD_URL` non reindirizza la CLI; viene ignorata e il comando esegue silenziosamente il reindirizzamento rispetto al dashboard salvato. + + `AGENTEYE_HOME` e `AGENTEYE_ENVIRONMENT` esistono ancora, ma appartengono al **collector e all'SDK di telemetria**, non a questa CLI. + - I comandi che eliminano, revocano, sopprimono, risolvono o sostituiscono la configurazione chiedono per impostazione predefinita. Usa `--yes` solo dopo aver verificato l'organizzazione attiva e il target. + I comandi che eliminano, revocano, sopprimono, risolvono o sostituiscono la configurazione richiedono per impostazione predefinita. Usa `--yes` solo dopo aver verificato l'organizzazione attiva e il target. \ No newline at end of file diff --git a/docs/it/reference/custom-agents.mdx b/docs/it/reference/custom-agents.mdx index 6142a3c39..7432290ca 100644 --- a/docs/it/reference/custom-agents.mdx +++ b/docs/it/reference/custom-agents.mdx @@ -1,46 +1,40 @@ --- ---- title: "Agenti personalizzati" -description: "Strumenta le tracce da agenti personalizzati affinché Failproof AI possa ricostruire le esecuzioni e trovare errori." +description: "Configurazione, il catalogo degli eventi, le regole di correlazione e la consegna per failproofai-sdk." icon: "python" --- -Strumenta le tracce da un agente personalizzato con `failproofai-sdk` affinché Failproof AI possa ricostruire ogni esecuzione, controllarne il comportamento e trovare errori supportati da prove. L'SDK scrive eventi strutturati per il daemon Failproof da consegnare al Cloud. Richiede Python 3.10 o versioni successive. - -L'instrumentazione rende gli agenti personalizzati osservabili e controllabili. Prevenire un'azione non sicura prima della sua esecuzione richiede anche un hook di enforcement nel tuo runtime. - - - Per applicare le policy in una configurazione con agente personalizzato, [contatta Failproof AI](mailto:support@befailproof.ai). Ti aiuteremo a mappare i confini del modello, dello strumento e del ciclo di vita del tuo runtime ai hook delle policy. - +Cosa fanno ogni impostazione, metodo e campo. Se stai strumentando per la prima volta, inizia con la guida — questa pagina è per cercare le cose. -
- -
+ + + Installazione, strumentazione, i metodi degli eventi, un esempio pratico e problemi comuni. + + + LangChain, CrewAI, LlamaIndex e Pydantic AI si strumentano da soli con una sola chiamata. + + -## Installa `failproofai-sdk` +Python 3.10 o più recente. Nessuna dipendenza runtime. -L'SDK è attualmente distribuito come wheel privato. Chiedi al tuo contatto Failproof AI la versione attuale e l'accesso al download. +## Installazione ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -Con `uv`, scarica prima il wheel ed esegui `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl`. Fissa il wheel in un repository di artefatti privato o un lock di dipendenze. +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 sono sempre presenti nel wheel di base. -Il pacchetto viene installato come `failproofai-sdk` e importato in Python come `failproofai`. - -## Connetti il daemon Failproof +## Connettere il daemon Failproof - 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 instrumentata, quindi trova il suo ID esatto in **Observe → Events**. - 4. Vai a **Observe → Sessions**, seleziona lo stesso ambiente e apri la traccia ricostruita. + 1. Vai su **Admin → Keys** e crea una chiave con `events:add`. + 2. [Connetti il daemon Failproof a 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. - ![Una sessione di agente Python personalizzato ricostruita come un grafico di esecuzione e una traccia di eventi ordinati.](/images/dashboard/session-detail.png) + ![Una sessione di agente Python personalizzata ricostruita come un grafo di esecuzione e una traccia di eventi ordinata.](/images/dashboard/session-detail.png) ```bash @@ -52,102 +46,84 @@ Il pacchetto viene installato come `failproofai-sdk` e importato in Python come -## Strumenta un'esecuzione completa - -Chiama `configure()` una sola volta durante l'avvio del processo. Ogni chiamata di evento è solo con parole chiave e richiede un `session_id` e un `agent_id` stabili. +## Configurazione ```python -import traceback -import uuid +import failproofai_sdk + +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -import failproofai +| Argomento | Cosa fa | +| --- | --- | +| `environment` | L'etichetta su ogni evento — `production`, `staging`, `prod-eu`. Il valore predefinito è `dev`. | +| `flush_interval` | Con che frequenza 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. | -failproofai.configure(environment="production") +Imposta tramite variabile d'ambiente: -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +| Variabile | Cosa fa | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Imposta `environment` senza una modifica del codice, per quando l'etichetta appartiene alla distribuzione piuttosto che all'app. Un argomento `configure()` la prevale. | +| `FAILPROOFAI_HOME` | Sposta la radice Failproof AI che contiene lo spool. | +| `FAILPROOFAI_SDK_STRICT` | `1` fa sì che gli errori di strumentazione vengano lanciati invece di essere registrati. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` fa sì che un problema di compatibilità del framework venga lanciato invece di avvisare e continuare. | -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) + + **Nessuna virgola in `environment`.** L'ingestione divide quel campo sulle virgole per costruire i suoi filtri e salta qualsiasi evento la cui etichetta ne contiene una — quindi un'intera esecuzione svanisce silenziosamente. Scrivi `prod-eu`, non `prod,eu`. -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + `configure(environment="prod,eu")` genera un'eccezione per farti sapere immediatamente. `AGENTEYE_ENVIRONMENT` non può generare un'eccezione — niente ti sta chiamando — quindi avvisa una volta e ritorna a `dev`. + + +Gli eventi sono messi in coda in memoria e scritti in background ogni `flush_interval` secondi, con uno scarico finale all'uscita dell'interprete. Un processo terminato brutalmente perde tutto ciò che non era stato ancora scritto. -Emetti `agent_start` una sola volta per attore. Per sub-agenti, riutilizza il `session_id` del genitore, assegna a ogni attore un `agent_id` distinto e imposta `parent_id` sull'ID dell'agente genitore, non sull'ID della sessione. +## Identità -## Riferimento configurazione +Ogni evento appartiene a una sessione e un agente. **Gli scope compilano entrambi**, quindi raramente li passi: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| Impostazione | Comportamento | -| --- | --- | -| `base_dir` | Radice dello spool esplicita. Ha la precedenza su tutte le variabili di ambiente. | -| `flush_interval` | Secondi tra le scritture in background dalla memoria al JSONL. Impostazione predefinita: `0.5`. | -| `environment` | Etichetta di distribuzione su ogni evento. Impostazione predefinita: `dev`. | -| `FAILPROOFAI_HOME` | Cambia la radice Failproof AI che contiene lo spool `custom-agents`. | - -L'SDK scrive nello `base_dir` esplicito quando è impostato. In caso contrario, utilizza lo spool `custom-agents` del daemon Failproof in `FAILPROOFAI_HOME` o `~/.failproofai`. +Passare `session_id` o `agent_id` esplicitamente funziona ancora e prevale. Senza nessuno vincolato né passato, la chiamata genera `TypeError` piuttosto che emettere un evento che Cloud scartererebbe silenziosamente. -L'SDK accoda le chiamate in memoria e scrive i batch su un thread di background. Tenta anche un flush finale tramite la gestione `atexit` di Python. Per i worker di breve durata, consenti lo spegnimento normale dell'interprete; l'interruzione forzata del processo può perdere gli eventi ancora in memoria. + + L'identità si basa su variabili di contesto. Segue automaticamente i task di `asyncio`, ma **non** i nuovi thread — avvolgi un worker in `failproofai_sdk.propagate()` o i suoi eventi finiscono scollati. + ## Catalogo degli eventi -Tutti i metodi restituiscono `None`. I campi lasciati come `None` vengono omessi anziché scritti come JSON `null`. +Quindici metodi. La maggior parte viene in **coppie** — chiami l'apertura, poi la chiusura, e l'SDK misura il divario. -| Metodo | Campi obbligatori oltre all'identità | Campi opzionali | +| | Apre | Chiude | +| --- | --- | --- | +| **Agenti** | `agent_start` | `agent_end` | +| | `agent_pause` | `agent_resume` | +| **Modelli** | `model_request` | `model_response` | +| **Strumenti** | `tool_use` | `tool_result` | +| **Hook** | `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 compilano per te. Qualsiasi cosa lasciata come `None` viene scartata piuttosto che inviata come JSON `null`, e ogni metodo restituisce `None`. + +| Metodo | Obbligatorio | Opzionale | | --- | --- | --- | | `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -158,27 +134,64 @@ Tutti i metodi restituiscono `None`. I campi lasciati come `None` vengono omessi | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -Usa `outcome="failed"`, `"error"`, `"timeout"` o `"rejected"` quando un completamento dovrebbe contare come errore. Altri valori, incluso `"failure"`, non vengono classificati come errori dal backend attuale. + + + + Per contrassegnare un'esecuzione come fallita, `outcome` deve essere uno di `failed`, `error`, `timeout` o `rejected`. Qualsiasi altra cosa — incluso il quasi mancato `failure` — conta come un successo. + + +## Accoppiamento e durata + +**Una regola: dai all'evento di chiusura lo stesso id dell'apertura.** È quello che li accoppia, e cosa consente all'SDK di misurare il divario. + +| Coppia | Abbinato su | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**Non passare `duration_ms` da solo.** L'SDK lo misura, e passarlo genera `ValueError`. -## Regole di correlazione e durata +L'unica eccezione è `model_response`, dove solo tu conosci la reale latenza del provider. Passa un numero intero di millisecondi — un float genera un'eccezione, perché la colonna è un intero a 32 bit e altrimenti finirebbe vuota. -- 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 tu stesso a questi metodi genera `ValueError`. -- Gli ID degli strumenti e degli hook condividono una mappa di sospensione a livello di processo. Rendili univoci globalmente tra le sessioni simultanee e tra entrambi gli spazi dei nomi; gli ID del provider o gli UUID sono i più sicuri. -- Una coppia divisa tra processi si correla comunque a valle, ma l'SDK non può calcolare la sua durata in-process. -- La mappa di sospensione contiene al massimo 10.000 inizi ed elimina la voce più vecchia quando piena. + -## Campi personalizzati e payload +- **Gli id devono essere univoci solo per tipo, per sessione.** Una chiamata a uno strumento e un hook possono condividere uno; due sessioni in esecuzione contemporaneamente possono riutilizzare gli stessi id senza collisioni. +- **Non sono vincolati a un agente.** Una coppia aperta sotto un agente e chiusa sotto un altro si abbina 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 in cui arrivano, quindi due chiamate concorrenti nello stesso agente possono accoppiarsi male. +- **Una coppia divisa tra processi** si abbina comunque in Cloud, ma l'SDK non può misurarla — niente in nessuno dei due processi ha visto entrambe le metà. +- **Al massimo 10.000 aperture attendono una chiusura contemporaneamente.** Oltre a quello, la più vecchia viene scartata, quindi una perdita non può crescere illimitatamente. -Ogni evento accetta campi con parole chiave aggiuntive. Utilizza valori compatibili con JSON quando le query a valle necessitano di struttura. Le foglie non supportate come UUID, datetime, decimali, set, byte e oggetti modello vengono stringificate dal writer. + -I nomi personalizzati riservati sono `timestamp`, `session_id`, `agent_id`, `type` e `environment`. Gli errori di battitura nei campi opzionali vengono accettati come nuovi campi personalizzati, quindi rivedi il JSON emesso quando un campo standard non viene visualizzato nel Cloud. +## I tuoi campi personalizzati + +Qualsiasi extra che passi viene memorizzato con l'evento: + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # i tuoi +) +``` + +Preferisci tipi JSON se vuoi interrogarli in seguito. Qualsiasi altra cosa — un UUID, un datetime, un `Decimal`, un set, bytes, un oggetto modello — viene memorizzato come stringa. + + + **Aggiungi un prefisso ai 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 niente può entrare in conflitto. + + È anche per questo che un campo opzionale con errore di ortografia non genera mai un errore — diventa solo un nuovo campo personalizzato. Se un campo standard manca in Cloud, controlla prima l'ortografia. + + +Questi cinque nomi sono riservati e respinti esplicitamente: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. ## Consegna e verifica - 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 di modello, strumento, umano, hook e errore appaiano nell'ordine previsto. Utilizza l'ID della sessione come chiave primaria per la risoluzione dei problemi. + 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 del modello, dello strumento, umani, hook e di errore appaiano nell'ordine previsto. Usa l'ID della sessione come chiave di troubleshooting primaria. ```bash @@ -190,10 +203,14 @@ I nomi personalizzati riservati sono `timestamp`, `session_id`, `agent_id`, `typ -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 indica una configurazione del daemon o un problema di consegna, mentre uno spool vuoto indica un problema di instrumentazione o di durata del processo. +Se Cloud è vuoto, ispeziona `$FAILPROOFAI_HOME/custom-agents/events`, altrimenti `~/.failproofai/custom-agents/events`. I file JSONL provano l'emissione SDK; uno spool crescente indica un problema di configurazione del daemon o di consegna, mentre uno spool vuoto indica un problema di strumentazione o di durata del processo. + + + 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 raccoglitore e mostra molti meno eventi di quanti ne siano stati emessi. + -## Previeni errori in un runtime personalizzato +## Prevenire guasti in un runtime personalizzato -Utilizza 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 policy e applicare la decisione risultante di allow, instruct o deny. +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 dei criteri e applicare la decisione risultante di allow, instruct o deny. -Invia un'email a [support@befailproof.ai](mailto:support@befailproof.ai) per progettare e convalidare questa integrazione per il tuo runtime. \ 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 ai ganci dei criteri, quindi convalidare l'integrazione con te. \ No newline at end of file diff --git a/docs/it/reference/events-and-configuration.mdx b/docs/it/reference/events-and-configuration.mdx index d32be9031..3378b5abc 100644 --- a/docs/it/reference/events-and-configuration.mdx +++ b/docs/it/reference/events-and-configuration.mdx @@ -1,41 +1,41 @@ --- title: "Eventi e configurazione" -description: "Consulta il modello di evento, gli ambienti, l'archiviazione locale e i confini di configurazione." +description: "Fai riferimento al modello di evento, agli ambienti, all'archiviazione locale e ai confini della configurazione." icon: "list-tree" --- ## Famiglie di eventi -- Avvio, fine, pausa e ripresa dell'agente +- Inizio, fine, pausa e ripresa dell'agente - Richiesta e risposta del modello -- Utilizzo dello strumento e risultato +- Uso dello strumento e risultato - Hook attivato e completato -- Attesa umana, input, pausa e interruzione +- Attesa umana, input, pausa e interrupt - Errori espliciti -Ogni evento contiene un timestamp, un ID di sessione, un ID di agente, un tipo di evento e un ambiente. I campi specifici dell'evento contengono dati relativi a modello, strumento, correlazione, risultato, contenuto, durata o errore. +Ogni evento contiene un timestamp, un ID sessione, un ID agente, un tipo di evento e un ambiente. I campi specifici dell'evento contengono dati su modello, strumento, correlazione, risultato, contenuto, durata o errore. -## Ispezionare un contratto di evento +## Ispeziona un contratto di evento 1. Apri **Observe → Events**. 2. Imposta una finestra temporale breve e filtra per ambiente, agente e tipo di evento. - 3. Seleziona un evento per ispezionare i suoi campi normalizzati e il payload grezzo, quindi apri la sua sessione per vedere il contesto di esecuzione. + 3. Seleziona un evento per ispezionare i suoi campi normalizzati e il payload grezzo, quindi apri la sua sessione per visualizzare il contesto di esecuzione. 4. Se manca una durata accoppiata, verifica che gli eventi di inizio e completamento utilizzino lo stesso ID di correlazione. - Utilizza il flusso Events per restringere i dati a un'esecuzione di un agente e ispezionare i campi di evento normalizzati. + Utilizza il flusso Events per restringere i dati a un'esecuzione di un agente e ispezionare i campi dell'evento normalizzati. - ![Il flusso live Events con filtri per ambiente, agente, sessione e tipo di evento.](/images/dashboard/events-stream.png) + ![Il flusso Events live con filtri per ambiente, agente, sessione e tipo di evento.](/images/dashboard/events-stream.png) Quindi segui l'evento nella sua sessione. La traccia mostra cosa è accaduto immediatamente prima e dopo, il che è necessario quando il payload da solo è ambiguo. - ![La traccia di sessione collegata utilizzata per ispezionare l'evento nel contesto di esecuzione.](/images/dashboard/session-detail.png) + ![La traccia della sessione collegata utilizzata per ispezionare l'evento nel contesto di esecuzione.](/images/dashboard/session-detail.png) - Confronta gli ID di correlazione e i timestamp in entrambe le visualizzazioni quando manca un evento accoppiato o una durata. + Confronta gli ID di correlazione e i timestamp in entrambe le viste quando manca un evento accoppiato o una durata. - Scopri i valori di filtro validi, quindi recupera i payload completi degli eventi per una sessione: + Scopri i valori di filtro validi, quindi recupera i payload degli eventi completi per una sessione: ```bash fp list event_types @@ -53,26 +53,26 @@ Ogni evento contiene un timestamp, un ID di sessione, un ID di agente, un tipo d ## Campi SDK riservati -Non utilizzare `timestamp`, `session_id`, `agent_id`, `type` o `environment` come campi personalizzati dell'SDK Python. Le durate degli eventi accoppiati come la durata del risultato dello strumento vengono calcolate dall'SDK e non possono essere fornite manualmente. +Non utilizzare `timestamp`, `session_id`, `agent_id`, `type` o `environment` come campi SDK Python personalizzati. Le durate degli eventi accoppiati come la durata del risultato dello strumento sono calcolate dall'SDK e non possono essere fornite manualmente. ## Confini locali -- Lo stato di Failproof AI risiede in `~/.failproofai` a meno che non sia esplicitamente configurato diversamente. -- `failproofai-sdk` utilizza `AGENTEYE_HOME` per l'override della directory di base legacy. -- Le etichette di ambiente possono essere impostate tramite la configurazione SDK o `AGENTEYE_ENVIRONMENT`. -- Le credenziali del daemon vengono archiviate separatamente dalle impostazioni non segrete. +- Lo stato di Failproof AI risiede in `~/.failproofai` a meno che non sia configurato diversamente. +- `failproofai-sdk` esegue sempre lo spool in `~/.failproofai/custom-agents`. `FAILPROOFAI_HOME` sposta quella home; il segmento `custom-agents` viene sempre aggiunto, quindi lo spool non può essere posizionato al di fuori di esso. Solo l'SDK stesso `configure(base_dir=...)` scrive altrove. `AGENTEYE_HOME` viene letto dal vecchio `agenteye-collector` per scegliere cosa monitorare e non influisce più su dove scrive l'SDK. +- Le etichette dell'ambiente possono essere impostate tramite la configurazione SDK o `AGENTEYE_ENVIRONMENT`. +- Le credenziali del daemon sono archiviate separatamente dalle impostazioni non segrete. -Utilizza nomi di ambiente stabili e a bassa cardinalità. Le virgole non sono supportate nelle etichette di ambiente del daemon. +Utilizza nomi di ambiente stabili e a bassa cardinalità. Le virgole non sono supportate nelle etichette dell'ambiente del daemon. -## Modificare un'etichetta di ambiente +## Modifica un'etichetta di ambiente - Le etichette di ambiente vengono assegnate dall'SDK o dal daemon Failproof che emette. Dopo aver modificato un'etichetta, apri **Observe → Sessions** e utilizza il filtro dell'ambiente per confermare che le nuove sessioni contengono il nuovo valore. Le sessioni esistenti mantengono l'ambiente originale. + Le etichette dell'ambiente vengono assegnate dall'SDK emittente o dal daemon Failproof. Dopo averne modificata una, apri **Observe → Sessions** e utilizza il filtro dell'ambiente per confermare che le nuove sessioni contengono il nuovo valore. Le sessioni esistenti mantengono il loro ambiente originale. - Per `failproofai-sdk`, configura l'ambiente nel codice o con la sua variabile di ambiente legacy. Esegui di nuovo la configurazione del daemon quando modifichi le impostazioni a livello di macchina. + Per `failproofai-sdk`, configura l'ambiente nel codice o con la sua variabile d'ambiente legacy. Riesegui la configurazione del daemon quando modifichi le impostazioni a livello di macchina. ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/it/reference/harnesses.mdx b/docs/it/reference/harnesses.mdx index f0c9df2e1..764eb6ff0 100644 --- a/docs/it/reference/harnesses.mdx +++ b/docs/it/reference/harnesses.mdx @@ -1,68 +1,68 @@ --- title: "Harness per agenti" -description: "Cattura sessioni e applica policy su tutti e 12 gli harness di agenti supportati." +description: "Cattura sessioni e applica politiche su tutti i 12 harness di agenti supportati." icon: "plug-zap" --- -Un harness è l'ambiente in cui il tuo agente effettivamente viene eseguito. Failproof AI supporta dodici di essi, divisi in due categorie: +Un harness è l'ambiente in cui il tuo agente effettivamente viene eseguito. Failproof AI supporta dodici di loro, divisi in due classi: -- **IDE e CLI per la 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) +- **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 auto-ospitato) -Le stesse policy e la stessa cronologia delle sessioni si applicano indipendentemente da quale harness esegue l'agente. Un livello di adapter mappa i nomi degli eventi nativi di ogni harness, i nomi degli strumenti e i campi degli 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 harness esegue l'agente. Un livello di adattatore mappa i nomi di eventi nativi di ogni harness, i nomi degli strumenti e i campi di input degli strumenti su 29 eventi canonici prima che qualsiasi politica venga eseguita. -Un agente che viene eseguito in **nessuno** dei dodici harness viene instrumentato direttamente con l'[SDK Python](/it/reference/custom-agents). Si tratta di un contratto diverso, e vale la pena affermarlo chiaramente: l'SDK fornisce tracciamento, sessioni, valutazioni e audit — **non applica policy autonomamente.** Bloccare un'azione non sicura prima della sua esecuzione richiede un hook di enforcement al confine degli strumenti del tuo runtime; [contattaci](mailto:support@befailproof.ai) e lo mapperemo. +Un agente che non viene eseguito in **nessuno** dei dodici è strumentato direttamente con l'[SDK Python](/it/reference/custom-agents). Si tratta di un contratto diverso, e vale la pena affermarlo chiaramente: l'SDK fornisce tracciamento, sessioni, valutazioni e audit — **non applica le politiche da solo.** Bloccare un'azione non sicura prima della sua esecuzione richiede un hook di imposizione al confine degli strumenti del tuo runtime; [contattaci](mailto:support@befailproof.ai) e lo mapperemo. -| Harness | Scope hook supportati | +| Harness | 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 nativi degli eventi hook, i nomi degli strumenti e i campi degli input degli strumenti prima che le policy vengano eseguite. Una policy può agire solo su eventi esposti dall'harness; testa il comportamento di fine turno e istruzioni esattamente sull'harness e sulla versione 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 che l'harness espone; testa il comportamento di fine turno e le istruzioni sull'harness esatto e la versione che distribuisci. -## Capacità di enforcement +## Capacità di imposizione -"Blocca" significa che il verdetto restituito dall'adapter corrente è consumato dall'harness denominato. Il blocco post-strumento può sostituire il risultato mostrato al modello ma non può annullare un effetto collaterale dello strumento già avvenuto. +"Bloccare" significa che il verdetto restituito dall'adattatore corrente viene consumato dall'harness indicato. Il blocco post-strumento può sostituire il risultato mostrato al modello ma non può annullare un effetto collaterale dello strumento che si è già verificato. -| Harness | Eventi di blocco verificati | Caveat solo osservativi o non bloccanti | +| Harness | Eventi di blocco verificati | Avvertenze di sola osservazione o non bloccanti | | --- | --- | --- | -| 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 compattamento sono osservativi nell'adapter corrente. | +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` e vari eventi di attività/configurazione | `PostToolUse`, ciclo di vita della sessione, notifiche e 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 compattamento 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 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 ciclo di vita sono osservativi; la guida di stop si applica a un turno successivo. | +| 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 di 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 compattamento 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 permission non vengono eseguiti in ogni modalità di permesso; gli eventi post-strumento e sessione sono osservativi. | -| Antigravity CLI | `PreToolUse`, `Stop` | I verdetti di user-prompt e post-strumento sono osservativi; le istruzioni di prompt possono comunque essere iniettate. | -| Goose | `PreToolUse` | Gli eventi di user-prompt, post-strumento e sessione sono osservativi. Esiste uno hook di stop bloccante nativo upstream ma non è installato dall'adapter corrente. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condizionato | Gli hook di autorizzazione non vengono eseguiti in ogni modalità di autorizzazione; 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 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 agent CLI, specialmente quando una policy si basa su comportamento di prompt, stop, permission o post-strumento piuttosto che il comune gate pre-strumento. +Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un CLI di agente, specialmente quando una politica si basa su prompt, stop, autorizzazione o comportamento post-strumento piuttosto che sul gate pre-strumento comune. -## Installa hook di capture e policy +## 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 target, connetti la CLI locale con la chiave visualizzata e installa gli hook dell'harness. - 3. Avvia una nuova sessione di agente, quindi conferma i suoi eventi di hook e sessione in **Observe → Events**. - 4. Apri **Observe → policy** per la stessa finestra temporale e conferma che una decisione di policy è attribuita alla macchina. + 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 agente, quindi conferma gli eventi hook e sessione in **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 i permessi di ingestion che di policy-delivery prima di copiare il suo secret. + La connessione inizia con una chiave di macchina. Conferma che includa sia le autorizzazioni di ingestione che di consegna delle politiche prima di copiare il suo segreto. - ![Il drawer della nuova chiave API utilizzato per concedere i permessi di ingestion degli eventi e policy delivery.](/images/dashboard/key-create.png) + ![Il cassetto della nuova chiave API utilizzato per concedere autorizzazioni di ingestione degli eventi e consegna delle politiche.](/images/dashboard/key-create.png) - Dopo aver installato gli hook, lo stream degli 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. - ![Lo stream live degli Events utilizzato per confermare che un harness appena installato sta generando report.](/images/dashboard/events-stream.png) + ![Il flusso Events dal vivo utilizzato per confermare che un harness 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 generando report sia dell'attività di policy che degli eventi di traccia. + Infine, verifica che le decisioni di politica siano attribuite alla stessa macchina. Questo conferma che l'harness sta segnalando l'attività delle politiche così come gli eventi di traccia. - ![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 harness appena connesso.](/images/dashboard/policy-observe.png) Installa gli hook per ogni harness rilevato: @@ -74,7 +74,7 @@ Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un ag failproofai policies --install ``` - Oppure scegli harness specifici e uno scope di configurazione: + Oppure scegli harness specifici e un ambito di configurazione: ```bash failproofai policies --install \ @@ -82,7 +82,7 @@ Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un ag --scope user ``` - Lo scope project mantiene la configurazione dell'hook con un repository. Lo scope user copre il lavoro tra repository. Claude Code supporta anche lo scope local; il supporto varia in base all'harness e la CLI rifiuta combinazioni non supportate. + L'ambito di progetto mantiene la configurazione dell'hook con un repository. L'ambito di utente copre il lavoro tra i repository. Claude Code supporta anche l'ambito locale; il supporto varia in base all'harness e la CLI rifiuta le combinazioni non supportate. Verifica la macchina e i suoi eventi: @@ -98,9 +98,9 @@ Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un ag - I percorsi extra vengono registrati sulla macchina, non nel Cloud. Dopo aver aggiunto uno, apri **Observe → Sessions**, filtra all'ambiente della macchina e conferma che le sessioni dal nuovo percorso appaiono. Apri una sessione e verifica l'agente, l'harness e i timestamp degli eventi prima di affidarti a essa in un audit. + 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 appaiano. Apri una sessione e verifica l'agente, l'harness e i timestamp degli eventi prima di affidarti ad essa in un audit. - ![L'elenco delle Sessions filtrato all'ambiente che riceve dati dal percorso di capture aggiuntivo.](/images/dashboard/sessions-list.png) + ![L'elenco Sessioni filtrato per l'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 +117,5 @@ Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un ag - Esegui una nuova sessione dopo l'installazione. Verifica sia lo stream degli 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 dal vivo che una decisione di politica effettiva prima di espandere il rollout. \ No newline at end of file diff --git a/docs/it/reference/overview.mdx b/docs/it/reference/overview.mdx index 41d20b8eb..a1cbcf03d 100644 --- a/docs/it/reference/overview.mdx +++ b/docs/it/reference/overview.mdx @@ -1,23 +1,26 @@ --- -title: "Integrazioni e riferimenti" -description: "Connetti harness di agenti supportati, SDK, CLI e l'API HTTP." +title: "Integrazioni e riferimento" +description: "Connetti harness di agent supportati, SDK, CLI e l'API HTTP." icon: "braces" --- -Scegli l'integrazione più vicina a dove il tuo agente è già in esecuzione. +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 le tracce per trovare i guasti negli agenti personalizzati, quindi contattaci per aggiungere la prevenzione al tuo runtime. + + Strumenta LangGraph, CrewAI, LlamaIndex, Pydantic AI o un agent personalizzato. + + + Configurazione, catalogo degli eventi, regole di correlazione e consegna. - Esamina progetti locali, sessioni, attività delle policy e audit offline. + Rivedi progetti locali, sessioni, attività di policy e audit offline. - Configura cattura locale, hook, policy, audit, distribuzione 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. @@ -33,29 +36,29 @@ Scegli l'integrazione più vicina a dove il tuo agente è già in esecuzione. -Il [riferimento 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`. Pagine scritte manualmente spiegano flussi di lavoro che attraversano 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 secret. - 2. Configura l'integrazione utilizzando la pagina corrispondente qui sopra. - 3. Apri **Observe → Events** per confermare che gli eventi arrivano, poi **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. + 1. Apri **Administration → Keys**, crea una chiave con `events:add` e `policies:pull`, e copia il segreto. + 2. Configura l'integrazione usando la pagina corrispondente sopra. + 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. - Inizia con il cassetto delle chiavi. I diritti selezionati determinano se la macchina può inviare eventi e ricevere policy gestite da Cloud. + Inizia con il cassetto delle chiavi. I grant selezionati determinano se la macchina può inviare eventi e ricevere policy gestite da Cloud. - ![Il cassetto della nuova chiave API utilizzato per concedere i permessi di inserimento degli eventi e di distribuzione delle policy.](/images/dashboard/key-create.png) + ![Il cassetto della nuova chiave API utilizzato per concedere permessi di acquisizione degli eventi e consegna delle policy.](/images/dashboard/key-create.png) - Dopo aver connesso l'integrazione, utilizza l'elenco Sessions per confermare che i suoi eventi vengono raggruppati in esecuzioni complete nell'ambiente previsto. + Dopo aver connesso l'integrazione, usa l'elenco Sessions 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 Sessions utilizzato per verificare che un'integrazione appena connessa stia segnalando esecuzioni complete di agent.](/images/dashboard/sessions-list.png) - Apri una di queste sessioni prima di considerare l'integrazione completata; la traccia dovrebbe contenere le prove di model, tool, error e policy necessarie ai tuoi audit. + Apri una di queste sessioni prima di considerare l'integrazione completa; la traccia dovrebbe contenere le prove di modello, strumento, errore e policy di cui i tuoi audit hanno bisogno. - Crea una chiave macchina, connetti il daemon Failproof e verifica la prima sessione. + Crea una chiave di macchina, connetti il daemon Failproof e verifica la prima sessione. ```bash fp keys create agent-production \ @@ -71,7 +74,7 @@ Il [riferimento API HTTP](/it/reference/http-api) generato copre la superficie p fp events --since 1h --env production --limit 20 ``` - 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. + Usa `fp --json sessions ...` quando un altro strumento consumerà il risultato. I flag globali come `--json`, `--org` e `--base-url` devono precedere il comando. Consulta il [riferimento Failproof AI CLI](/it/reference/failproof-cli) per i comandi locali e il [riferimento Failproof Cloud CLI](/it/reference/cloud-cli#cli-commands) per i comandi `fp`. diff --git a/docs/it/reference/troubleshooting.mdx b/docs/it/reference/troubleshooting.mdx index 15411ef3c..81ff9bda8 100644 --- a/docs/it/reference/troubleshooting.mdx +++ b/docs/it/reference/troubleshooting.mdx @@ -1,6 +1,6 @@ --- title: "Risoluzione dei problemi" -description: "Diagnostica sessioni mancanti, policy mancanti, mancate consegne e azioni agent bloccate." +description: "Diagnostica sessioni mancanti, politiche mancanti, errori di consegna e azioni dell'agente bloccate." icon: "wrench" --- @@ -8,9 +8,9 @@ icon: "wrench" - Apri **Administration → Keys** e conferma che la chiave della macchina sia attiva e abbia `events:add`. Quindi apri **Observe → Events**, amplia l'intervallo di tempo e cancella i filtri per ambiente e agent. Se esistono eventi, cerca l'ID della sessione e controlla quindi **Observe → Sessions** per il raggruppamento. Se non esistono eventi, diagnostica il daemon Failproof dalla CLI. + Apri **Administration → Keys** e conferma che la chiave della macchina è attiva e ha `events:add`. Quindi apri **Observe → Events**, allarga l'intervallo di tempo e cancella i filtri di ambiente e agente. Se gli eventi esistono, cerca l'ID della sessione e poi verifica **Observe → Sessions** per il raggruppamento. Se non ci sono eventi, diagnostica il daemon Failproof dalla CLI. - ![Il flusso eventi live con i suoi filtri principali visibili e i recenti eventi degli agent in arrivo.](/images/dashboard/events-stream-current.png) + ![Lo stream di eventi live con i suoi filtri principali visibili e gli eventi recenti dell'agente in arrivo.](/images/dashboard/events-stream-current.png) ```bash @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - Conferma che l'acquisizione sia abilitata, che la chiave configurata abbia `events:add` e che il filtro del dashboard corrisponda all'ambiente emesso. + Conferma che la cattura è abilitata, la chiave configurata ha `events:add` e il filtro del dashboard corrisponde all'ambiente emesso. - + - Cancella i filtri in **Observe → Events** e cerca l'ID esatto della sessione SDK. Se non appare nulla, ispeziona lo spool dell'SDK e il daemon Failproof sulla macchina di origine. + Cancella i filtri in **Observe → Events** e cerca l'ID di sessione SDK esatto. Se non appare nulla, ispeziona lo spool SDK e il daemon Failproof sulla macchina di origine. ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - Conferma che il processo dell'agent imposti `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` e che `$FAILPROOFAI_HOME/custom-agents`, altrimenti `~/.failproofai/custom-agents`, esista prima che l'SDK si avvii. + Conferma che un daemon è in esecuzione e connesso — SDK accoda i dati indipendentemente da ciò. La directory dello spool **non** deve pre-esistere (lo scrittore la crea), e nessuna variabile d'ambiente la seleziona: `$FAILPROOFAI_HOME/custom-agents`, altrimenti `~/.failproofai/custom-agents`, è l'unica radice, e `configure(base_dir=...)` è l'unico override. Se il processo è stato terminato con `SIGKILL` o eliminato per OOM, tutto ciò che era ancora in coda è stato perso — gestisci `SIGTERM` per limitare questo. - + - Apri **Admin → enforcement**, seleziona la macchina e confronta le versioni assegnate, segnalate e precedenti. Conferma che l'ambito della distribuzione includa la macchina e che la sua chiave abbia `policies:pull`. L'ingestione può funzionare anche quando la consegna delle policy non funziona. + Apri **Admin → enforcement**, seleziona la macchina e confronta le versioni assegnate, segnalate e precedenti. Conferma che l'ambito di distribuzione include la macchina e che la sua chiave ha `policies:pull`. L'acquisizione può funzionare anche quando la consegna delle politiche non funziona. @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - Conferma che l'ID e l'etichetta della macchina corrispondano al target del dashboard. Riconnettiti con una chiave in grado di gestire le policy se le credenziali esistenti concedono solo l'ingestione degli eventi. + Conferma che l'ID della macchina e l'etichetta corrispondono all'obiettivo del dashboard. Riconnettiti con una chiave in grado di ricevere le politiche se le credenziali esistenti concedono solo l'acquisizione di eventi. - Apri **Admin → enforcement** e ispeziona l'ultimo orario di visualizzazione della macchina e la versione segnalata. Se la macchina è obsoleta, tratta questo come un problema del daemon locale. Non indebolire la policy distribuita solo per aggirare un daemon non disponibile. + Apri **Admin → enforcement** e ispeziona l'ora dell'ultimo accesso della macchina e la versione segnalata. Se la macchina è obsoleta, trattalo come un problema del daemon locale. Non indebolire la politica distribuita esclusivamente per aggirare un daemon non disponibile. @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - Riavvia o aggiorna `failproofaid`; esegui nuovamente la configurazione quando le versioni del protocollo CLI e daemon differiscono. Il percorso del daemon configurato fallisce in chiuso per progettazione. + Riavvia o aggiorna `failproofaid`; riesegui la configurazione quando le versioni del protocollo CLI e daemon differiscono. Il percorso del daemon configurato fallisce chiuso per design. - + - Per una policy creata in Cloud, apri **Admin → policy editor**, seleziona la bozza e rivedi gli errori di convalida prima di pubblicare. Per una policy locale, usa la CLI per convalidarla, quindi apri **Observe → policy** dopo un'azione di test per confermare che gli ordini arrivino. + Per una politica creata in Cloud, apri **Admin → policy editor**, seleziona la bozza e rivedi gli errori di convalida prima di pubblicare. Per una politica locale, usa la CLI per convalidarla, quindi apri **Observe → policy** dopo un'azione di test per confermare che le decisioni arrivano. - Conferma che il nome del file termini con `policies.js`, `policies.mjs` o `policies.ts`, che il modulo chiami `customPolicies.add(...)` e che gli import si risolvano dal file della policy. + Conferma che il nome del file termina con `policies.js`, `policies.mjs` o `policies.ts`, il modulo chiama `customPolicies.add(...)` e gli import si risolvono dal file della politica. ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -91,14 +91,14 @@ icon: "wrench" - + - Apri **Analyze → audits**, seleziona l'esecuzione e verifica se l'analisi del modello è stata eseguita. Quindi confronta il suo ambito e finestra con **Observe → sessions** e apri tracce rappresentative da quella popolazione. + Apri **Analyze → audits**, seleziona l'esecuzione e verifica se l'analisi del modello è stata eseguita. Quindi confronta l'ambito e la finestra con **Observe → sessions** e apri tracce rappresentative da quella popolazione. - Un risultato pari a zero è significativo solo quando l'analisi è stata eseguita con successo. Se l'analisi è stata saltata o non è riuscita, l'esecuzione non produce risultati e mantiene la finestra non analizzata aperta per un'esecuzione futura riuscita. Se l'analisi del modello è disabilitata, l'audit non produce risultati perché la scansione deterministica delle credenziali e della PII registra statistiche ma non genera più risultati. + Un risultato nullo è significativo solo quando l'analisi è stata eseguita correttamente. Se l'analisi è stata saltata o non è riuscita, l'esecuzione non produce risultati e mantiene aperta la finestra non analizzata per un'esecuzione riuscita futura. Se l'analisi del modello è disabilitata, l'audit non produce risultati perché la scansione deterministica delle credenziali e PII registra statistiche ma non genera più risultati. - ![Il modulo di audit in cui ambiente, agent, cadenza e finestra di sweep definiscono la popolazione della sessione.](/images/dashboard/audit-new.png) + ![Il modulo di audit dove ambiente, agente, cadenza e finestra di sweep definiscono la popolazione di sessioni.](/images/dashboard/audit-new.png) ```bash @@ -110,31 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - Se l'esecuzione rimane in coda, aspetta la capacità dell'audit-agent o chiedi all'operatore della distribuzione di ispezionare la flotta di audit. Un audit in coda si ripete; non viene saltato immediatamente. + Se l'esecuzione rimane in coda, attendi la capacità dell'audit-agent o chiedi all'operatore di distribuzione di ispezionare la flotta di audit. Un audit in coda riprova; non viene immediatamente saltato. - Apri una sessione completata e verifica se una valutazione manuale ha esito positivo. Cloud ospitato attualmente non ha alcun controllo dell'endpoint dell'evaluator nel dashboard; l'operatore del server deve configurarlo. + Apri una sessione completata e verifica se una valutazione manuale riesce. Cloud ospitato attualmente non ha alcun controllo dell'endpoint del valutatore nel dashboard; l'operatore del server deve configurarlo. - Verifica l'evaluator stesso, quindi ispeziona gli stati di valutazione recenti: + Verifica il valutatore stesso, quindi ispeziona gli stati di valutazione recenti: ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - Su Cloud auto-ospitato, conferma che `EVALUATOR_ENDPOINT` sia presente sul server e che `EVALUATOR_TOKEN` corrisponda all'evaluator. La valutazione automatica è disabilitata quando l'endpoint è assente. + Su Cloud self-hosted, conferma che `EVALUATOR_ENDPOINT` è presente sul server e `EVALUATOR_TOKEN` corrisponde al valutatore. La valutazione automatica è disabilitata quando l'endpoint è assente. - + - Usa il selettore di organizzazione e conferma lo slug e i permessi previsti prima di confrontare i risultati con la CLI. + Usa il selettore dell'organizzazione e conferma lo slug e le autorizzazioni previste prima di confrontare i risultati con la CLI. ```bash @@ -143,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - In modalità chiave API, specifica `fp --org --api-key ...` o imposta `AGENTEYE_ORG`. Lo stato dell'organizzazione della sessione umana salvata viene intenzionalmente ignorato per le richieste con chiave API. + In modalità chiave API, specifica `fp --org --api-key ...` o imposta `AGENTEYE_ORG`. Lo stato dell'organizzazione della sessione umana salvato viene intenzionalmente ignorato per le richieste con chiave API. - + - Apri **Observe → policy**, conserva la decisione e la sessione collegata e identifica la condizione di falso positivo. Quindi apri **Admin → enforcement** ed esegui il rollback delle macchine interessate alla versione precedente. Crea una versione più ristretta in **Policy editor**, testala su un piccolo ambito e espandi solo dopo il successo del lavoro valido. + Apri **Observe → policy**, conserva la decisione e la sessione collegata, e identifica la condizione di falso positivo. Quindi apri **Admin → enforcement** e ripristina le macchine interessate alla versione precedente. Crea una versione più ristretta in **Policy editor**, testala su un ambito ridotto e espandi solo dopo che il lavoro valido avrà successo. - Il rollback della distribuzione Cloud è solo dashboard. Una pausa della sessione locale non disabilita le policy gestite da Cloud. Se il dashboard non è disponibile, acquisisci lo stato della macchina e della distribuzione e ripristina l'accesso al dashboard invece di riprovare ripetutamente l'azione bloccata. + Il rollback della distribuzione Cloud è solo dal dashboard. Una pausa locale della sessione non disabilita le politiche gestite da Cloud. Se il dashboard non è disponibile, acquisici lo stato della macchina e della distribuzione e ripristina l'accesso al dashboard piuttosto che riprovare ripetutamente l'azione bloccata. ```bash failproofai config --status @@ -164,4 +164,4 @@ icon: "wrench" -Quando contatti il supporto, includi la versione della CLI, l'harness, l'ambiente, l'ID sessione o distribuzione rilevante e l'output di `failproofai config --status` con i segreti rimossi. \ No newline at end of file +Quando contatti il supporto, includi la versione CLI, l'harness, l'ambiente, l'ID della sessione o distribuzione pertinente e l'output di `failproofai config --status` con i segreti rimossi. \ No newline at end of file diff --git a/docs/it/sessions/live-events.mdx b/docs/it/sessions/live-events.mdx index f982c517e..c2c0720bd 100644 --- a/docs/it/sessions/live-events.mdx +++ b/docs/it/sessions/live-events.mdx @@ -1,21 +1,21 @@ --- -title: "Eventi in diretta" -description: "Osserva l'attività dell'agent mentre la sessione è in corso." +title: "Eventi live" +description: "Visualizza l'attività dell'agente mentre una sessione è in esecuzione." icon: "radio" --- -Gli eventi in diretta ti aiutano a confermare la strumentazione e a monitorare un'esecuzione rischiosa senza attendere il completamento della sessione. +Gli eventi live ti aiutano a confermare la strumentazione e a osservare un'esecuzione rischiosa senza attendere il completamento della sessione. -## Monitora l'attività +## Visualizzare l'attività - 1. Vai a **Observe → Events**. - 2. Inizia con la finestra temporale attuale e nessun filtro per confermare che i dati stanno arrivando. - 3. Filtra per ambiente, tipo di evento, agent o sessione. Usa la ricerca per il testo del payload. - 4. Seleziona un evento per ispezionarne il riepilogo e i dettagli. Segui il collegamento della sua sessione per la traccia completa. + 1. Vai su **Observe → Events**. + 2. Inizia con la finestra temporale corrente e nessun filtro per confermare l'arrivo dei dati. + 3. Filtra per ambiente, tipo di evento, agente o sessione. Usa la ricerca per il testo del payload. + 4. Seleziona un evento per ispezionare il suo riassunto e i dettagli. Segui il link della sessione per la traccia completa. - ![Il flusso Events in diretta che mostra il traffico da un gateway di chat Hermes insieme alle esecuzioni di coding-CLI, filtrato per ora, ambiente, tipo di evento, agent, modello, contesto e sessione.](/images/dashboard/events-stream-current.png) + ![Il flusso di eventi live che mostra il traffico da un gateway di chat Hermes insieme alle esecuzioni di coding-CLI, filtrato per ora, ambiente, tipo di evento, agente, modello, contesto e sessione.](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +24,22 @@ Gli eventi in diretta ti aiutano a confermare la strumentazione e a monitorare u fp --json events --full --session-id --all ``` - Il feed predefinito omette i payload grezzi. Usa `--full` solo per un'indagine di sessione limitata. + Il feed predefinito omette i payload grezzi. Usa `--full` solo per un'indagine su una sessione limitata. Usa il flusso di eventi per rispondere a tre domande immediate: -- L'agent previsto sta segnalando all'ambiente corretto? -- Le chiamate ai modelli, le chiamate agli strumenti e le decisioni sulle policy arrivano in ordine? +- L'agente previsto sta segnalando all'ambiente corretto? +- Le chiamate ai modelli, le chiamate ai tool e le decisioni delle policy arrivano in ordine? - La sessione ha smesso di fare progressi o ha iniziato a ripetere un'azione? -I tipi di evento includono eventi del ciclo di vita dell'agent, richieste e risposte dei modelli, utilizzo e risultati degli strumenti, esecuzione degli hook, attese umane e interrupt, ed errori espliciti. Gli ID di correlazione collegano eventi associati come una chiamata a uno strumento e il suo risultato. +I tipi di evento includono eventi del ciclo di vita dell'agente, richieste e risposte dei modelli, uso dei tool e risultati, esecuzione degli hook, attese umane e interrupt, ed errori espliciti. Gli ID di correlazione collegano gli eventi accoppiati come una chiamata a un tool e il suo risultato. - Mantieni la vista in diretta ampia durante la verifica di una nuova integrazione. Aggiungi filtri solo dopo aver visto il primo evento; un filtro errato potrebbe sembrare un'acquisizione fallita. + Mantieni la visualizzazione live ampia durante la verifica di una nuova integrazione. Aggiungi filtri solo dopo aver visto il primo evento; un filtro non corretto potrebbe sembrare un'acquisizione fallita. -Se non vengono visualizzati eventi, esegui `failproofai config --status`, quindi [risolvi i problemi di acquisizione](/it/reference/troubleshooting). +Se non appaiono eventi, esegui `failproofai config --status`, quindi [risolvi i problemi di acquisizione](/it/reference/troubleshooting). -Gli agent che non vengono eseguiti in uno dei 12 [harness](/it/reference/harnesses) supportati segnalano gli stessi tipi di evento tramite [Python SDK](/it/reference/custom-agents), inclusi gli eventi di interazione umana (`human_wait`, `human_input`, `human_interrupt`) su cui dipendono gli agent del gateway e di produzione. \ No newline at end of file +Gli agenti che non vengono eseguiti in uno dei 12 [harness](/it/reference/harnesses) supportati segnalano gli stessi tipi di evento attraverso [Python SDK](/it/reference/custom-agents), inclusi gli eventi di interazione umana (`human_wait`, `human_input`, `human_interrupt`) da cui dipendono gli agenti gateway e di produzione. \ No newline at end of file diff --git a/docs/it/start/first-policy.mdx b/docs/it/start/first-policy.mdx index 91d48d042..fb754c73b 100644 --- a/docs/it/start/first-policy.mdx +++ b/docs/it/start/first-policy.mdx @@ -1,7 +1,6 @@ --- ---- -title: "Previeni il tuo primo errore con una policy" -description: "Crea una versione di policy, distribuiscila in modalità observe e poi applicala." +title: "Evita il tuo primo fallimento con una policy" +description: "Scrivi una versione della policy, distribuiscila in modalità observe, quindi applicala." icon: "shield-check" --- @@ -10,25 +9,25 @@ Utilizza una policy solo dopo aver descritto l'azione non sicura e le azioni leg - - Vai su **Admin → policy editor**. Inizia con la demo policy, rivedi o modifica il suo codice sorgente, quindi seleziona **publish version**. La pubblicazione crea la versione immutabile che puoi distribuire alle macchine. + + Vai su **Admin → policy editor**. Inizia con la policy demo, rivedi o modifica il suo codice sorgente, quindi seleziona **publish version**. La pubblicazione crea la versione immutabile che puoi distribuire sulle macchine. - ![L'editor di policy con una demo policy pronta per la pubblicazione come versione immutabile.](/images/dashboard/policy-editor.png) + ![La vista di composizione dell'editor delle policy con una policy demo pronta per essere pubblicata come versione immutabile.](/images/dashboard/policy-editor.png) - - Vai su **Admin → enforcement**, espandi la macchina target, e seleziona **edit this machine**. Aggiungi la demo policy pubblicata, fissa la sua versione, scegli **observe**, e applica la distribuzione. + + Vai su **Admin → enforcement**, espandi la macchina di destinazione e seleziona **edit this machine**. Aggiungi la policy demo pubblicata, fissa la sua versione, scegli **observe**, e applica la distribuzione. - ![L'editor di distribuzione della macchina con una versione di policy pubblicata selezionata in modalità observe prima di applicare la distribuzione.](/images/dashboard/enforcement-editor.png) + ![L'editor di distribuzione della macchina con una versione della policy pubblicata selezionata in modalità observe prima di applicare la distribuzione.](/images/dashboard/enforcement-editor.png) - Esegui una nuova sessione agent su quella macchina, quindi apri **Observe → policy**. Seleziona la macchina e conferma che la demo policy appare nella mappatura della policy e nella timeline delle decisioni. La modalità observe registra cosa farebbe la policy senza bloccare l'azione. + Esegui una nuova sessione agente su quella macchina, quindi apri **Observe → policy**. Seleziona la macchina e conferma che la policy demo appare nella mappatura delle policy e nella timeline delle decisioni. La modalità observe registra ciò che la policy farebbe senza bloccare l'azione. - ![La pagina Policy che mostra i totali delle decisioni, l'attività di enforcement nel tempo, e le mappature delle policy locali e gestite dal Cloud.](/images/dashboard/policy-observe.png) + ![La pagina Policy che mostra i totali delle decisioni, l'attività di applicazione nel tempo, e le mappature delle policy locali e gestite dal Cloud.](/images/dashboard/policy-observe.png) - L'authoring delle policy del Cloud e la distribuzione della flotta sono flussi di lavoro amministrativi. Utilizza la CLI locale per validare la stessa policy prima di pubblicarla: + La creazione delle policy Cloud e la distribuzione della flotta sono flussi di lavoro amministrativi. Usa la CLI locale per convalidare la stessa policy prima di pubblicarla: ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -36,13 +35,13 @@ Utilizza una policy solo dopo aver descritto l'azione non sicura e le azioni leg failproofai config --status ``` - Usa `fp` per ispezionare le decisioni di policy visibili dal Cloud: + Usa `fp` per ispezionare le decisioni delle policy visibili nel Cloud: ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - La CLI del Cloud non espone i percorsi di distribuzione dell'enforcement solo per root. Pubblica le versioni da **Admin → policy editor** e distribuiscile da **Admin → enforcement**. + Entrambi i passaggi sono disponibili anche dalla CLI: `fp policies publish ` crea una versione e `fp fleet deploy --add ` la inserisce su una macchina. Gli equivalenti del dashboard sono **Admin → policy editor** e **Admin → enforcement**. \ No newline at end of file diff --git a/docs/it/start/integrations.mdx b/docs/it/start/integrations.mdx new file mode 100644 index 000000000..02e76b691 --- /dev/null +++ b/docs/it/start/integrations.mdx @@ -0,0 +1,121 @@ +--- +--- +title: "Strumenta il tuo agente" +sidebarTitle: "Framework" +description: "Collega qualsiasi framework di agenti supportato a Failproof AI con una sola chiamata." +icon: "plug" +--- + +Il tuo agente produce già tutto ciò che vale la pena registrare — chiamate di modello, chiamate di strumenti, limiti dei nodi, attese umane, errori. Il framework lo butta via. L'SDK lo conserva. + + + + Un agente che hai scritto tu stesso, o uno non elencato qui. + + + Grafi, nodi, strumenti, retriever, modelli. + + + Crew, flussi, agenti per ruolo, strumenti. + + + Workflow, step, agenti di funzione, retriever. + + + Agenti tipizzati, capacità, strumenti, nuovi tentativi. + + + +## Tre righe, qualsiasi framework + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Agenti personalizzati +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # rileva i framework che hai importato + +with failproofai_sdk.session(): + ... # la tua chiamata di agente esistente, invariata +``` + +Nessun decoratore sulle tue funzioni, nessun callback passato alle tue chiamate, nessun id thread nel tuo codice. Solo la chiamata all'interno della sessione differisce: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # under `async with failproofai_sdk.session():` + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +L'extra installa il **framework**. Ogni adapter è incluso nella wheel di base, quindi un progetto che ha già il suo framework non necessita di extra. + +## Verifica l'arrivo + +Esegui una sessione strumentata, quindi apri **Observe → Sessions** e seleziona il tuo ambiente. L'esecuzione appare come una traccia ricostruita. + +Se nulla arriva, conferma che la macchina è connessa con `failproofai config --status`. Vedi [Configura la cattura](/it/start/setup). + + + Non controllare la directory di spool per confermare la consegna. Il daemon Failproof raccoglie ed elimina ogni batch entro millisecondi, quindi leggerlo gara con il collettore e mostra molti meno eventi di quelli emessi. + + +## Prossimo + +Ogni quickstart sopra rimanda alla sua guida completa — cosa viene registrato, opzioni, streaming, denominazione span e i problemi che le persone effettivamente riscontrano. Vivono sotto **Trace Agents → Plug in your agent**. + + + + Il modello di dati, gli id, i tipi di evento e come gli eventi raggiungono Cloud. + + + Segui la causalità attraverso una sessione invece di log disconnessi. + + + Controlla le sessioni che hai appena catturato. + + \ No newline at end of file diff --git a/docs/it/start/integrations/crewai.mdx b/docs/it/start/integrations/crewai.mdx new file mode 100644 index 000000000..e8c025ca8 --- /dev/null +++ b/docs/it/start/integrations/crewai.mdx @@ -0,0 +1,224 @@ +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "Strumenta equipaggi, flussi, agenti per ruolo, strumenti, memoria e feedback umano." +icon: "/images/frameworks/crewai.svg" +--- + +## Installazione + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +Supportato: `crewai` dalla 1.13 alla 2.0. La 1.13 è la versione che ha aggiunto `started_event_id` e normalizzato l'utilizzo dei token, entrambi elementi su cui l'adapter si basa per abbinare gli eventi e segnalare i token. + +## Strumentazione + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` registra un listener sul bus degli eventi a livello di modulo di CrewAI e sottoscrive un gestore per ogni classe di evento. Nulla cambia nel tuo equipaggio, agenti, compiti o strumenti. + +## Cosa viene registrato + +| CrewAI | Evento Failproof | +| --- | --- | +| Crew kickoff | `agent_start`, `agent_end` | +| `Agent.kickoff()` (un agente leggero, senza equipaggio) | `agent_start`, `agent_end`, con `agent_id` dal ruolo | +| Inizio e fine del flusso | `agent_start`, `agent_end`; un equipaggio avviato all'interno di un metodo di flusso si annida sotto di esso | +| Esecuzione dell'agente | `agent_start`, `agent_end` annidati, con `agent_id` dal ruolo. In un processo gerarchico un collega delegato si annida sotto il manager, non accanto ad esso | +| Compito | Niente; registrato come collegamento in modo che i figli si risolvano nell'equipaggio | +| Metodo di flusso, guardrail | `hook_triggered`, `hook_completed` | +| Utilizzo dello strumento | `tool_use`, `tool_result` | +| Operazioni di memoria e conoscenza | `tool_use`, `tool_result`, denominati dalla superficie colpita | +| Chiamata LLM | `model_request`, `model_response`, con utilizzo dei token | +| Chunk di stream | Incorporato nella risposta come conteggio dei chunk e tempo al primo token | +| Feedback umano richiesto | `human_wait`, `agent_pause` | +| Feedback umano ricevuto | `agent_resume`, `human_input` | +| Errore di esecuzione dell'agente | `error`, quindi `agent_end` con risultato `failed` | + +Un compito non emette nulla di proposito. Un compito CrewAI è un sottoinsieme dell'esecuzione dell'agente che lo esegue, quindi emettere entrambi comporterebbe il raddoppio di ogni riga e li renderebbe fratelli. L'id e il nome del compito viaggiano invece sugli eventi dell'agente stesso. + +Le operazioni di memoria e conoscenza vengono registrate come strumenti, denominati dalla superficie che colpiscono, in modo che vengano visualizzate accanto ai tuoi veri strumenti dove puoi confrontare la loro latenza. + +Su un equipaggio gerarchico, l'annidamento è ciò che rende la traccia leggibile: + +```text +crew +└─ manager + ├─ researcher delegated + └─ writer delegated +``` + +CrewAI rende genitore un'esecuzione delegata sull'evento **strumento** `delegate_work_to_coworker`, non direttamente sul manager, quindi l'adapter segue quel collegamento. Senza di esso ogni agente risulta fratello di ogni altro e la struttura della delega viene persa. + +## Esempio + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # becomes agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +Il passaggio è visibile nella traccia: lo span `analyst` si chiude, lo span `writer` si apre, e entrambi si trovano all'interno di uno span `crew`. + +## Nomina i tuoi span + +`agent_id` proviene da `Agent(role=...)`, che è quello che lo rende una sfaccettatura leggibile del dashboard. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # one facet entry per run +``` + +`agent_id` è una colonna a bassa cardinalità. Un ruolo contenente un id di esecuzione o un timestamp lo degrada per ogni query che chiunque esegue. Se un ruolo sembra un id, l'adapter lo rifiuta e mette il valore reale in un campo del payload. + +## Controlla la sessione + +Risolto in questo ordine, il primo risultato vince: + +1. `instrument("crewai", session_id=...)` +2. L'ambito `failproofai_sdk.session()` che lo racchiude +3. Un `uuid4().hex` generato, una volta per equipaggio o flusso + +Avvolgi il kickoff per controllarlo per ogni esecuzione: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## Opzioni + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # pin every run to one session id +) +``` + +`session_id` è l'unica opzione che questo adapter legge. I prompt e i completamenti vengono sempre registrati, troncati al budget del payload. + +## Ciclo umano nel ciclo + +CrewAI ha **due** superfici di ciclo umano nel ciclo, e entrambe vengono registrate come i medesimi quattro eventi. + +`@human_feedback` su un metodo di flusso passa attraverso il bus degli eventi di CrewAI: il runtime emette un evento prima di bloccarsi su una persona e un altro dopo la risposta. + +`Task(human_input=True)` no. Chiama `input()` all'interno del provider di input di CrewAI e non emette alcun evento, quindi l'adapter avvolge quel provider direttamente — senza di esso l'intera attesa umana era invisibile e fatturata come tempo attivo dell'agente. + +In entrambi i casi ottieni: + +```text +human_wait the prompt and its options +agent_pause starts the paused-time clock +agent_resume stops it +human_input the answer, with the wait measured +``` + +Da `agent_pause` a `agent_resume` è l'unica coppia che alimenta il tempo di pausa. Senza di essa, un'attesa umana di dieci minuti viene fatturata come dieci minuti di tempo attivo dell'agente. + + + CrewAI non imposta alcun id di correlazione su nessun evento di feedback umano, quindi l'adapter li abbina in base al nome del flusso e del metodo, tornando alla pausa aperta più di recente. Questo è valido perché un prompt della console blocca. Se costruisci un provider di feedback concorrente, imposta `request_id` su entrambi gli eventi. + + + + Poiché il percorso `Task(human_input=True)` è un wrapper attorno al provider di input di CrewAI piuttosto che una sottoscrizione di evento, viene ripristinato su `uninstrument()` e ri-genera qualsiasi cosa `input()` generi, `KeyboardInterrupt` incluso, invariato. + + +## Problemi comuni + + + + Un `role` contiene un UUID, un timestamp o un suffisso per esecuzione. Usa un ruolo umano stabile e metti l'id specifico dell'esecuzione nella descrizione del compito. + + + + Il bus degli eventi è asincrono e `kickoff()` ritorna prima che gli ultimi gestori vengano eseguiti. Svuotalo prima: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + Questa è una proprietà di CrewAI, non dell'SDK. + + + + `agent_end` forza la chiusura delle pause aperte ma non degli strumenti o dei modelli, quindi un'esecuzione che muore dentro una chiamata di strumento lascia quello span aperto. Lo spegnimento normale chiude tutto ciò che è ancora aperto e lo contrassegna come incompleto. Solo un `SIGKILL` lo lascia in sospeso, perché nulla può essere eseguito. + + + + Verifica in questo ordine: `instrument()` è stato eseguito prima di `kickoff()`; c'è un `with failproofai_sdk.session():` attorno; `crewai` è versione 1.13 o più recente; `FAILPROOFAI_SDK_STRICT=1` impostato, quindi un hook degradato genera un'eccezione anziché essere ingoiato. + + + +## Avanti + + + + Coppie, id, ciclo di vita della sessione e consegna. + + + Segui la causalità attraverso la sessione che hai appena acquisito. + + + LangGraph, LlamaIndex, Pydantic AI e agenti personalizzati. + + \ No newline at end of file diff --git a/docs/it/start/integrations/custom-agents.mdx b/docs/it/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..9e2f43611 --- /dev/null +++ b/docs/it/start/integrations/custom-agents.mdx @@ -0,0 +1,737 @@ +--- +title: "Agenti personalizzati" +sidebarTitle: "Agenti personalizzati" +description: "Strumenta un agente che hai scritto tu stesso, o un framework per il quale Failproof AI non ha un adapter." +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. + +## Installa + +```bash +pip install failproofai-sdk +``` + +Nessun extra, nessuna dipendenza. + +## Strumenta + +```python +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # una chiamata dello strumento +``` + +Leggi da cima a fondo e dice quello che significa: + +| Avvolgi con | Per dire | +| --- | --- | +| `session()` | Questi eventi appartengono alla stessa esecuzione | +| `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 cosa emette effettivamente ciascuno: + +| Ambito | Emette | Scopo | +| --- | --- | --- | +| `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 è 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 sia con `async with` che con `with`. + +L'annidamento di agenti costruisce l'albero. `parent_id` e profondità sono calcolati dalla stack: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## Come un ambito si chiude + +`agent()` gestisce le eccezioni per te: + +| Cosa è successo | Eventi | Risultato | +| --- | --- | --- | +| 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 è 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 evento + +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 | Indipendente | +| --- | --- | --- | --- | +| **Agenti** | `agent_start` | `agent_end` | — | +| | `agent_pause` | `agent_resume` | — | +| **Modelli** | `model_request` | `model_response` | — | +| **Strumenti** | `tool_use` | `tool_result` | — | +| **Hook** | `hook_triggered` | `hook_completed` | — | +| **Umani** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **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. + + + +```python Agenti +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 Modelli +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```python Strumenti +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 Hook +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 Umani +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 Fallimenti +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **Le due famiglie umane puntano in direzioni opposte.** + + | Metodi | Significato | + | --- | --- | + | `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. + + + + **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 chiamata di strumenti contro l'API di OpenAI, senza framework di agenti: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +MODEL = "gpt-4o-mini" + + +def turn(messages: list): + """Una chiamata di modello, racchiusa dalla coppia.""" + failproofai_sdk.event.model_request(model=MODEL, messages=messages) + reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) + usage = reply.usage + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +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 + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +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 task asyncio automaticamente. Non si propagano nei nuovi thread, perché un thread inizia con un contesto vuoto. + +```python +# asyncio: nulla da fare +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# 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 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 giunzioni. Mappale e hai una traccia completa — i quattro adapter forniti non fanno nulla di più che questo. + +| La giunzione | Quello che scrivi | Quello che atterra | +| --- | --- | --- | +| L'esecuzione | `session()` + `agent()` | `agent_start`, `agent_end` | +| Ogni strumento | `tool_call()` | `tool_use`, `tool_result` | +| Ogni chiamata di modello | La coppia `model_*` | `model_request`, `model_response` | + + + + ```python + with failproofai_sdk.session(): + with failproofai_sdk.agent(agent_name, goal=task): + result = framework.run(task) + ``` + + + In qualsiasi cosa il framework chiami wrapper di strumento o 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(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **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 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 motivi, e le tre giunzioni sopra sono la risposta ad entrambi: + + - `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 giunzioni a mano registra gli stessi eventi, con la stessa fedeltà, che un adapter fornito darebbe. + + +## Approfondisci + +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 ne ottiene uno di chiusura. + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + C --> E(["agent_end"]) +``` + +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. + + + + ```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 token-out + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 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. + + + + ```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 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 token-out + 9 +5.727s agent_end analyst · success + 10 +5.739s agent_end crew · success + ``` + + Il `role` di ogni agente diventa il nome del suo span, quindi la latenza e la spesa di token si dividono per ruolo. + + + + ```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 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 + ... seconda iterazione + 26 +7.038s agent_end Agent · success + ``` + + Il ciclo dell'agente stesso è visibile, non solo le sue chiamate di modello. + + + + ```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 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 token-out + 8 +8.119s agent_end agent · success + ``` + + Nessuna coppia di hook: Pydantic AI non ha un confine di nodo o passo da racchiudere. + + + + ```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 token-out + 6 +0.000s agent_end main · success + ``` + + Tu emetti questi. 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`. + +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 | + +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. + + + 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 in ogni metodo evento. Omessi, si risolvono dall'ambito che li racchiude: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + 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`. + +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 conia quale id + +| Id | Coniato 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 | + +#### 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 +4. Metadati del framework +5. L'id di esecuzione proprio del framework + +Non è mai inventato mentre uno di questi 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. + +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 | + +L'id reale è conservato su `fw_agent_id` / `fw_run_id`, dove rimane interrogabile senza essere una sfaccettatura. + + + **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. + + + + + + +| Gruppo | Eventi | +| --- | --- | +| Agenti | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| Modelli | `model_request`, `model_response` | +| Strumenti | `tool_use`, `tool_result` | +| Hook | `hook_triggered`, `hook_completed` | +| Umani | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| Fallimenti | `error` | + +Quale framework registra cosa, misurato dalle esecuzioni sopra: + +| Evento | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Personalizzato | +| --- | :--: | :--: | :--: | :--: | :--: | +| 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 | +| Errore | Sì | Sì | Sì | Sì | Automatico | +| 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 — emettili 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. + +| Apre | Chiude | L'evento di chiusura porta | +| --- | --- | --- | +| `agent_start` | `agent_end` | `outcome`, `summary` | +| `model_request` | `model_response` | token, `stop_reason`, latenza | +| `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 | + + + 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 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. + + + + + +Installare `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` è 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()`. + + +```python +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 | +| --- | --- | +| `langchain` | `langgraph`, `langchain_core` | +| `crewai` | — | +| `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: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +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. + + 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` 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* 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 non ha langchain ancora -> () + +import langchain # troppo tardi, nulla è cablato +``` + +```python Giusto +import langchain # importa il framework per primo +import failproofai_sdk + +failproofai_sdk.instrument() # lo trova -> ('langchain',) +``` + +```python Giusto, order-proof +import failproofai_sdk + +# Nominarlo importa l'adapter su richiesta, quindi questo funziona da qualsiasi parte. +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. + + + + + +```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"] + E -->|"HTTPS"| F["Cloud"] +``` + +| Fase | Compito | Eseguita 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 | + +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` 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 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. + + +Il daemon **spedisce** i tuoi batch. Non li apre o li riscrive. + +| Eventi | Scritti da | Redatti da `collector.redact`? | +| --- | --- | --- | +| Trascritti di sessione CLI | Il daemon | Sì | +| Attività hook | Il daemon | Sì | +| **Tutto ciò che l'SDK emette** | **Il tuo processo** | **No** | + +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 sorgente, 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: + - 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. + + `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. + + + + **Una directory spool vuota è lo stato salutistico.** 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. + +Per confermare che gli eventi effettivamente atterrano, controlla il dashboard. Per osservare lo spool riempirsi, ferma prima il daemon. + + + + + +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 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 | + +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. + + + + + +## Problemi comuni + + + + 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`. + + + + È 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](#thread-e-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_`. + + + + `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. + + + +## Avanti + + + + Coppie, id, ciclo di vita della sessione, e consegna. + + + 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/integrations/langchain.mdx b/docs/it/start/integrations/langchain.mdx new file mode 100644 index 000000000..cad0c1176 --- /dev/null +++ b/docs/it/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain e LangGraph" +sidebarTitle: "LangChain e LangGraph" +description: "Strumenta grafi, nodi, tool, retriever e chiamate ai modelli con una sola chiamata." +icon: "/images/frameworks/langchain.svg" +--- + +Un unico adattatore serve entrambi. LangGraph viene eseguito sul gestore di callback di `langchain-core`, quindi strumentare uno significa strumentare anche l'altro. + +## Installazione + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Per LangChain senza LangGraph, usa `failproofai-sdk[langchain]`. + +Supportati: `langchain-core` dalla versione 1.4.7 a 2.0, `langgraph` dalla versione 1.2 a 2.0. Al di fuori di questo intervallo l'adattatore si installa comunque e avvisa una sola volta. + +## Strumentazione + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` registra un tracer attraverso `langchain_core.tracers.context.register_configure_hook`. LangChain lo injetta in ogni gestore di callback che crea, quindi grafi, tool e modelli vengono catturati senza modificare alcun sito di chiamata — inclusi quelli dentro librerie che non hai scritto. + +## Cosa viene registrato + +| LangChain o LangGraph | Evento Failproof | +| --- | --- | +| Esecuzione radice | `agent_start`, `agent_end` | +| Nodo LangGraph | `hook_triggered`, `hook_completed` | +| Sottografo compilato | `agent_start`, `agent_end` annidati | +| Esecuzione tool | `tool_use`, `tool_result` | +| Esecuzione retriever | `tool_use`, `tool_result`, output riassunto | +| Esecuzione chat model o LLM | `model_request`, `model_response`, con utilizzo token | +| Token in streaming | Incorporati nella risposta come numero di chunk e tempo al primo token. I conteggi dei token richiedono `ChatOpenAI(stream_usage=True)` — vedi sotto | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, correlati su `Interrupt.id` — incluso quando il resume avviene in un processo diverso rispetto allo stesso checkpoint | +| Eccezione non gestita | `error`, poi `agent_end` con outcome `failed` | + +**Un nodo diventa un hook, non un agente annidato.** `agent_id` è la facet principale in ogni superficie del dashboard — promuovere `retrieve`, `grade_documents` e `should_continue` ad agenti creerebbe confusione, etichettando la sessione in base a qualunque nodo si esegua per primo. + +Gli span hook vengono renderizzati allo stesso modo e ti forniscono comunque una vista della latenza per nodo. + + + **Nomina i tuoi nodi come preferisci.** L'esecuzione di un nodo è identificata dalla sua *forma* — un'esecuzione non-leaf che porta il proprio tag di step di LangGraph — mai dal suo nome. + + +| Quello che scrivi | Quello che viene registrato | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | Lo strumento | +| `add_node("ChatOpenAI", ...)` | La chiamata al modello | + +Nominare un nodo in base a ciò che esegue causava la scomparsa degli eventi di quel elemento. Non succede più. + +### Streaming + +`.stream()` e `.astream()` non emettono eventi per token. Si incorporano nel `model_response` di chiusura: + +| Campo | Contiene | +| --- | --- | +| `fw_chunks` | Quanti chunk sono arrivati | +| `fw_ttft_ms` | Tempo al primo token | + +### Conteggi token su una risposta in streaming + +È una questione separata e facile da trascurare: OpenAI invia l'utilizzo solo su una risposta in streaming **quando richiesto**. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # senza questo, nessun token +``` + +L'adattatore registra ciò che il framework gli consegna. Senza quel flag non c'è nulla da registrare, e `model_response` arriva senza conteggi di token. + +## Esempio + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Restituisce il prezzo unitario di un articolo in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Restituisce le unità di un articolo attualmente in magazzino.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## Nomina i tuoi span + +Per impostazione predefinita lo span radice prende il nome del grafo stesso. Racchiudilo per ottenere un'etichetta a tua scelta: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +Per configurazioni multi-agente, annida gli scope. Ogni worker diventa uno span figlio che porta `parent_id`: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +Mantieni `agent_id` con bassa cardinalità. Usa un ruolo o un nome di nodo, mai un UUID o una stringa per-esecuzione. + +## Controlla la sessione + +L'id della sessione viene risolto in questo ordine, il primo match vince: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. Lo scope `failproofai_sdk.session()` che lo circonda +4. `metadata["session_id"]`, `metadata["conversation_id"]`, o `metadata["thread_id"]` +5. L'id di esecuzione radice + +Non viene mai generato da zero, perché un id sintetizzato dividerebbe un'esecuzione su più sessioni. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## Opzioni + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # fissa ogni esecuzione a un id di sessione + include_chains=set(), # lista di permessi delle catene intermedie come coppie di hook + capture_content=True, # False rimuove prompt e completamenti dai payload + graph_callbacks=True, # interrupt e resume di prima classe, richiede langgraph 1.2+ +) +``` + +Imposta `capture_content=False` per dati regolamentati. Struttura, tempi, conteggi token, nomi di tool e risultati vengono comunque registrati; i corpi dei messaggi no. + +`include_chains` si applica solo alle esecuzioni **annidate**. Un runnable che invochi a livello superiore è la radice della sessione, quindi diventa lo span dell'agente piuttosto che una coppia di hook, e nominarlo qui non ha effetto. + +## Uomo nel ciclo + +`interrupt()` produce quattro eventi, e nessuna coppia è ridondante: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +`human_wait` a `human_input` porta il prompt e la risposta (entrambi vengono scartati sotto `capture_content=False`, insieme alle fonti dei documenti di recupero — il numero di documenti sopravvive). `agent_pause` a `agent_resume` è l'unica coppia che comunica il tempo di pausa, quindi senza di essa un'attesa umana di dieci minuti viene addebitata come tempo di agente attivo. Lo span radice rimane aperto durante il gap, mantenendo entrambe le chiamate in una sessione. + +## Problemi comuni + + + + `create_react_agent` propaga l'eccezione. Per far sì che il modello veda il fallimento e continui, costruisci il nodo tool esplicitamente: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + Il fallimento viene registrato come `tool_result` che contiene un errore comunque. Questo decide solo se l'esecuzione sopravvive. + + + + Un `llm.invoke()` diretto al di fuori di qualsiasi grafo non ha esecuzione padre, quindi apre uno span radice ed emette la sua coppia di modelli al suo interno. Il dashboard assegna le foglie a un agente aperto, quindi lo span è intenzionale. Nominalo: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + Hai passato un handler Failproof in `config={"callbacks": [...]}` e hai anche chiamato `instrument()`. Rimuovilo. L'hook di configurazione copre già ogni gestore di callback nel processo. + + + + Non è così. LangGraph lancia `GraphInterrupt` attraverso lo stesso percorso di un'eccezione reale, quindi ogni pausa raggiunge il tracer come callback di errore. Qualsiasi sottoclasse di `GraphBubbleUp` è invece trattata come flusso di controllo, quindi un'approvazione non dipinge un errore rosso. + + + + Controlla in questo ordine: `instrument()` è stato eseguito prima dell'esecuzione del grafo; c'è un `with failproofai_sdk.session():` intorno alla chiamata; `FAILPROOFAI_SDK_STRICT=1` è impostato, quindi un hook degradato solleva un'eccezione invece di essere inghiottito. + + + +## Passaggi successivi + + + + Coppie, id, ciclo di vita della sessione e consegna. + + + Segui la causalità attraverso la sessione che hai appena catturato. + + + CrewAI, LlamaIndex, Pydantic AI e agenti personalizzati. + + \ No newline at end of file diff --git a/docs/it/start/integrations/llamaindex.mdx b/docs/it/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..51d71538a --- /dev/null +++ b/docs/it/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "Strumenta flussi di lavoro, passaggi, agenti di funzioni e retriever." +icon: "/images/frameworks/llamaindex.svg" +--- + +## Installazione + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +Supportato: `llama-index-core` dalla versione 0.14.23 alla 0.15. La 0.14.23 è la versione in cui il flusso di lavoro ha iniziato a trasportare gli eventi tipizzati dell'agente che questo adapter legge. Nelle versioni precedenti, sia i nomi dei modelli che la struttura dell'agente vanno perduti. + +## Strumentazione + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +L'API dell'agente di LlamaIndex è asincrona. Ogni ambito funziona sia con `async with` che con `with` e produce eventi identici. + +`instrument()` allega un gestore di eventi e un gestore di span al dispatcher globale di LlamaIndex. Insieme rendono visibile il ciclo dell'agente, non solo le sue chiamate ai modelli. + + + Senza un argomento aggiuntivo sul tuo LLM, ogni conteggio di token nella tua traccia è null. Vedi [Conteggi di token](#conteggi-di-token) di seguito. + + +## Conteggi di token + +`FunctionAgent` chiama `astream_chat`, e `llama-index-llms-openai` non invia `stream_options={"include_usage": True}` quando effettua lo streaming. Il provider quindi non invia mai il chunk di utilizzo, e non c'è niente da leggere per alcuna strumentazione. + +Questo è il comportamento a monte di LlamaIndex. Attiva il consenso sul tuo LLM: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +Misurato sulla stessa esecuzione e modello: + +| | Token di input | Token di output | +| --- | --- | --- | +| Senza | `null` | `null` | +| Con | 148 | 17 | + +Le chiamate non in streaming (`llm.chat`, `llm.achat`) segnalano l'utilizzo senza configurazione. Solo il percorso di streaming, che è il percorso dell'agente predefinito, necessita di questo. + +## Cosa viene registrato + +| LlamaIndex | Evento Failproof | +| --- | --- | +| `Workflow.run` span radice | Sessione, `agent_start`, `agent_end` | +| Span `Workflow.run` annidato | `agent_start`, `agent_end` annidati | +| Span del passaggio del flusso di lavoro | `hook_triggered`, `hook_completed` | +| Inizio e fine della chat LLM | `model_request`, `model_response` | +| Span di `FunctionTool.call` | `tool_use`, `tool_result` | +| Inizio e fine del retrieval | `tool_use`, `tool_result`, output riassunto | +| Incorporamenti | Nulla, a meno che `embeddings=True` | +| Un tool in attesa di una persona | `human_wait`, `agent_pause`, poi `agent_resume`, `human_input` | +| Passaggio di `AgentWorkflow` | Un `agent_start`, `agent_end` annidato per agente, figlio del flusso di lavoro | +| Eccezione | `error`, quindi `agent_end` con risultato `failed`, e `agent_end.summary` che lo nomina | +| `handler.cancel_run()` | `agent_end` con risultato `cancelled` e nessun `error` — un pulsante di stop non è un fallimento | + +`agent_id` è il `FunctionAgent.name` quando lo imposti, altrimenti il nome della classe del flusso di lavoro. Sotto un `AgentWorkflow`, ogni agente che prende un turno ottiene il suo span annidato sotto il flusso di lavoro, quindi un passaggio di controllo si legge come due agenti anziché uno. + +L'output del retrieval è riassunto anziché scaricato. Un retriever restituisce documenti, e archiviarli nel payload metterebbe il tuo corpus nell'archivio degli eventi una volta per query. Vengono mantenuti il conteggio, l'intervallo dei punteggi e i frammenti troncati. + +## Esempio + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +Il ciclo dell'agente appare nella traccia come coppie di hook: `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool`, e `aggregate_tool_results`. Sono il ciclo proprio del framework, quindi sono hook anziché agenti, il che mantiene `agent_id` significativo. + +## Nomina i tuoi span + +`agent_id` è il `FunctionAgent.name` quando lo imposti, altrimenti il nome della classe del flusso di lavoro. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +In un `AgentWorkflow`, quel nome è anche quello sotto il quale ogni passaggio di controllo è registrato: + +```text +AgentWorkflow span padre +├─ city_analyst turno 1 +├─ cost_analyst turno 2 +└─ city_analyst turno 3 — un nuovo turno, non uno riaperto +``` + +Quindi `agent_id` ti dice **quale agente** ha svolto il lavoro e `parent_id` ti dice **quale flusso di lavoro** gli apparteneva. Un agente che restituisce il controllo in seguito apre un secondo turno anziché riaprire il primo. + +Avvolgi l'esecuzione per sovrascriverlo, o per raggruppare più agenti sotto un genitore comune: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +Mantieni `agent_id` a bassa cardinalità. È la sfaccettatura principale su ogni superficie di dashboard, quindi usa un ruolo o un nome di flusso di lavoro, mai un UUID o una stringa per esecuzione. + +## Controlla la sessione + +Questo adapter non accetta **alcuna opzione `session_id`**. La sessione proviene dall'ambito racchiudente, altrimenti un `uuid4().hex` generato per esecuzione del flusso di lavoro: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## Opzioni + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True registra le chiamate di embedding come coppie di tool + steps=True, # False elimina le coppie di hook del passaggio del flusso di lavoro + capture_messages=True, # False elimina OGNI payload: prompt, completamenti, + # argomenti e output del tool, I/O dei passaggi, query + # di retrieval, l'obiettivo e la risposta finale + capture_limit=8192, # caratteri mantenuti per valore catturato + stale_after=600.0, # secondi prima che una LEAF abbandonata sia forzatamente chiusa + reaper_interval=30.0, # con quale frequenza il reaper scansiona; 0 lo disabilita +) +``` + +| Opzione | Perché la modificheresti | +| --- | --- | +| `embeddings` | Attiva solo durante il debug della latenza o del costo degli incorporamenti. Una costruzione di indice in blocco è migliaia di chiamate e seppellirà la timeline. | +| `steps` | Disattiva se vuoi solo eventi di modello e tool e trovi il ciclo dell'agente rumoroso. | +| `capture_messages` | Disattiva per dati regolamentati. Ogni payload smette di essere registrato — prompt, il completamento del modello, gli argomenti e i valori di restituzione del tool, l'input e l'output del passaggio del flusso di lavoro, le query di retrieval, l'obiettivo dell'agente e la sua risposta finale. La struttura, i tempi, i token e i risultati sono ancora registrati. | +| `capture_limit` | Caratteri mantenuti per valore catturato prima del troncamento. Aumentalo quando un prompt RAG o un contesto recuperato arrivano ritagliati. | +| `stale_after` | Secondi prima che una **foglia** abbandonata — una risposta in streaming che nessuno ha consumato, un span di modello o tool il cui close non è mai arrivato — sia forzatamente chiusa, affinché la sessione si stabilizzi anziché leggere `ongoing` per sempre. NON chiude un'esecuzione abbandonata stessa: un flusso di lavoro il cui compito è cancellato senza che il dispatcher veda un'uscita mantiene il suo `agent_start` aperto fino a `uninstrument()`. | +| `reaper_interval` | Frequenza di scansione. Imposta su `0` per disabilitare completamente il reaper. | + +## Umano nel ciclo + +Catturato quando l'attesa accade all'interno di un tool: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +`ctx.wait_for_event` in un passaggio di flusso di lavoro semplice non è catturato. Il runtime raccoglie il drop prima che raggiunga il dispatcher, quindi il passaggio esce e viene rieseguito in seguito senza segnale per basare una pausa su. Il pattern FunctionAgent, che LlamaIndex documenta, aspetta dentro un tool ed è catturato in pieno. + +## Problemi comuni + + + + Aggiungi `additional_kwargs={"stream_options": {"include_usage": True}}` al tuo LLM. Vedi [Conteggi di token](#conteggi-di-token). + + + + LlamaIndex non ha un campo di utilizzo standard. L'adapter prova diverse forme note, e un'integrazione che nomina i suoi contatori con qualcosa di nuovo non corrisponderà a nessuna di esse. + + Il dict grezzo è sempre spedito, quindi controlla `usage` nel payload per vedere come il tuo provider li ha nominati. + + Un `usage` popolato insieme a colonne di token vuote è intenzionale — è meglio di un numero confidentemente sbagliato. + + + + Questo è il ciclo FunctionAgent, un set per iterazione. Filtra per nome di hook sul dashboard. Questi tempi dei passaggi sono di solito il motivo per usare questo adapter anziché uno solo per modelli. + + + + Controlla in questo ordine: `instrument()` è stato eseguito prima dell'esecuzione; c'è un `async with failproofai_sdk.session():` intorno all'`await`; `llama-index-core` è 0.14.23 o più recente; `FAILPROOFAI_SDK_STRICT=1` è impostato, quindi un hook degradato genera un'eccezione anziché essere inghiottito. + + + +## Successivo + + + + Coppie, id, ciclo di vita della sessione e consegna. + + + Segui la causalità attraverso la sessione appena catturata. + + + LangGraph, CrewAI, Pydantic AI e agenti personalizzati. + + \ No newline at end of file diff --git a/docs/it/start/integrations/pydantic-ai.mdx b/docs/it/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..5d2868362 --- /dev/null +++ b/docs/it/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "Strumenta agenti tipizzati, tool, chiamate di modello e retry." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## Installazione + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +Supportato: `pydantic-ai-slim` 2.0 to 3.0. La versione 2.0 ha rimosso `Agent(instrument=...)` e introdotto il protocollo di capacità su cui questo adapter è costruito, quindi la versione 1.x non può essere strumentata in questo modo. + +## Strumentazione + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # prima di costruire qualsiasi Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` deve essere eseguito prima di costruire un `Agent`. La capacità viene aggiunta al momento della costruzione, quindi un agente costruito in precedenza non ne possiede nessuna e non registra nulla, senza errore perché nulla è andato storto. Questa è la causa più comune di una traccia vuota con questo adapter. + + +Gli agenti a livello di modulo sono dove questo diventa problematico: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # costruito al momento dell'importazione + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # esegui questo PER PRIMO +import agents # ora l'agente ottiene la capacità +``` + +Verifica che abbia funzionato: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI unisce l'elenco che passi in una singola `root_capability`, quindi non esiste un attributo `agent.capabilities` da leggere. + +Gli agenti costruiti mentre strumentati mantengono la capacità, quindi puoi `uninstrument()` e re-strumentare senza ricostruirli. + +## Cosa viene registrato + +| Pydantic AI | Evento Failproof | +| --- | --- | +| Esecuzione dell'agente | `agent_start`, `agent_end` | +| Richiesta di modello | `model_request`, `model_response`, con utilizzo dei token | +| Chiamata di tool | `tool_use`, `tool_result`, con gli argomenti inviati dal modello | +| `ModelRetry` da un tool | `tool_result` che contiene un errore | +| Eccezione non gestita | `error`, seguito da `agent_end` con esito `failed` | + +Non esiste una coppia di hook e nessuna coppia human-in-the-loop qui. Pydantic AI non ha un confine di nodo o passo da delimitare e nessuna pausa umana integrata, quindi non c'è nulla da mappare. Se ne costruisci uno, emetti gli eventi tu stesso — vedi [Agenti personalizzati](/it/reference/custom-agents). + +`output_type` non fa differenza nella traccia. Un'esecuzione tipizzata e un'esecuzione di stringa producono gli stessi eventi. + +## Esempio + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +Nella traccia, `restock_eta` appare come un `tool_result` che contiene un errore, seguito da un'altra chiamata di modello dove l'agente lo aggira, e l'esecuzione termina comunque con `success`. Entrambi i fatti sono registrati. + +## Errori, retry e flusso di controllo + +Pydantic AI genera eccezioni per tre cose diverse, e l'adapter le separa: + +| Eccezione | Trattata come | Risultato | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | Un vero fallimento di tool | `tool_result` con un errore; l'esecuzione può ancora terminare con `success` | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | Flusso di controllo | Non è un errore; l'esecuzione viene indirizzata | +| Qualsiasi altro | Un fallimento | `error`, seguito da `agent_end` con esito `failed` | + +`ModelRetry` è nel primo gruppo deliberatamente. Significa che un tentativo è veramente fallito e il modello è stato chiesto di riprovare, che è esattamente per cosa serve il campo errore di uno span di tool. Classificarlo come flusso di controllo nasconderebbe i veri fallimenti di tool dietro un'esecuzione verde. + +## Nomina i tuoi span + +Lo span di esecuzione proprio di Pydantic AI è denominato `agent`. Avvolgi la chiamata per assegnargli un'etichetta che hai scelto: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +Lo span del framework allora si annida sotto `inventory`, e è lì che gli eventi di modello e tool sono collegati. + +Mantieni `agent_id` a bassa cardinalità. È il facet principale su ogni superficie della dashboard, quindi usa un nome di ruolo, mai un UUID o una stringa per-esecuzione. + +## Controlla la sessione + +Risolto in questo ordine, il primo corrispondente vince: + +1. `instrument("pydantic_ai", session_id=...)` +2. Lo scope `failproofai_sdk.session()` che lo contiene +3. `conversation_id` dell'esecuzione, poi il suo `run_id` +4. Un `uuid4().hex` generato + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## Opzioni + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # fissa ogni esecuzione a un id di sessione + capture_content=True, # False rimuove i prompt e i completamenti dai payload +) +``` + +## Problemi comuni + + + + L'`Agent` è stato costruito prima che `instrument()` fosse eseguito. Vedi l'avvertenza sopra e controlla `agent.root_capability.capabilities`. + + + + Un `raise` semplice si propaga; è il design di Pydantic AI. Per consentire al modello di aggirarla, solleva `ModelRetry` con un messaggio su cui possa agire. Il fallimento è registrato comunque. + + + + Quel figlio è lo span di esecuzione proprio di Pydantic AI, ed è dove gli eventi di modello e tool sono collegati. Elimina il tuo scope se vuoi un singolo span, al costo del nome personalizzato. + + + + Lo stack del grafo asincrono di Pydantic AI è più lungo del limite del campo payload, e l'ultima riga di una traceback è l'eccezione stessa. Questo campo viene ritagliato dalla parte anteriore piuttosto che da quella posteriore, quindi la riga di cui hai bisogno sopravvive. + + + +## Prossimo + + + + Coppie, id, ciclo di vita della sessione e consegna. + + + Segui la causalità attraverso la sessione che hai appena catturato. + + + LangGraph, CrewAI, LlamaIndex e agenti personalizzati. + + \ No newline at end of file diff --git a/docs/it/start/quickstart.mdx b/docs/it/start/quickstart.mdx index f47b3a05e..482f7805a 100644 --- a/docs/it/start/quickstart.mdx +++ b/docs/it/start/quickstart.mdx @@ -1,15 +1,15 @@ --- title: "Avvio rapido" -description: "Acquisisci una sessione di agente, trova un errore e inizia a prevenirlo." +description: "Cattura una sessione di agente, trova un errore e inizia a prevenirlo." icon: "zap" --- -Questo avvio rapido configura una macchina per segnalare sessioni, esegue un audit e distribuisce una policy. Utilizza la skill per configurare Failproof, oppure segui i passaggi manuali. +Questo avvio rapido mette una macchina a inviare sessioni, esegue un audit e distribuisce una policy. Usa la skill per configurare Failproof, oppure segui i passaggi manuali. -**Quale percorso è il tuo?** Se il tuo agente gira 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 l'[SDK Python](/it/reference/custom-agents) per il tracing e gli audit, quindi riprendi da [Esegui il tuo primo controllo di errore](/it/start/first-audit); l'enforcement su quel percorso necessita 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 programmazione o un gateway come Hermes o OpenClaw — segui i passaggi qui sotto; hai bisogno di Node.js 20.9 o successivo. Se il tuo agente non ha un harness, strumentalo con l'[SDK Python](/it/reference/custom-agents) per il tracing e gli audit, quindi riprendi da [Esegui il tuo primo controllo di errore](/it/start/first-audit); l'enforcement su quel percorso richiede un hook nel tuo runtime. - + ```bash @@ -21,22 +21,22 @@ Questo avvio rapido configura una macchina per segnalare sessioni, esegue un aud 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 pertinente, esegue la configurazione e la verifica. Consulta il [repository delle skill FailproofAI](https://github.com/FailproofAI/skills) per le singole skill 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 di FailproofAI](https://github.com/FailproofAI/skills) per le skill individuali e le opzioni di installazione avanzate. ## Prima di iniziare -1. Apri la [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 secret monouso e salvalo sulla macchina target: +1. Apri la [dashboard Failproof AI](https://app.befailproof.ai) e crea un account oppure accedi con la tua email di lavoro. +2. Vai su **Administration → Keys** e crea una chiave con `events:add` e `policies:pull`. +3. Copia il segreto monouso e conservalo sulla macchina di destinazione: ```bash export FAILPROOFAI_KEY="" ``` - ## Installazione + ## Installa @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - I transcript di sessione vengono inviati per impostazione predefinita. Aggiungi `--no-transcripts` per segnalare l'attività dell'hook e le decisioni delle policy senza contenuto di transcript. + I transcript di sessione vengono inviati per impostazione predefinita. Aggiungi `--no-transcripts` per segnalare l'attività degli hook e le decisioni delle policy senza il contenuto dei transcript. - 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 macchina nuova. + Se questa macchina ha già una cronologia di agenti, visualizza un'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,23 +57,23 @@ export FAILPROOFAI_KEY="" Apri **Sessions** in Failproof AI e seleziona una sessione importata. - - Questo collega Failproof AI al tuo harness e installa le 40 policy built-in. Utilizzale per vedere le decisioni di policy locali e provare l'enforcement prima che Failproof AI auditi le tue sessioni e scrivi policy per i tuoi agenti. + + Questo collega Failproof AI al tuo harness e installa le 40 policy integrate. 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. - Lascia che il programma di installazione rilevi il tuo harness, oppure specificane uno esplicitamente. Ognuno dei 12 è un valore `--cli` valido — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Lascia che l'installer rilevi il tuo harness, oppure specifica uno esplicitamente. 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 # una CLI di coding - failproofai policies --install --cli hermes --scope user # un gateway Slack/Telegram + 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 tool prima dell'esecuzione è verificato su tutti e 12. I gate di fine turno sono verificati su 8 — consulta [capacità di enforcement](/it/reference/harnesses#enforcement-capability) per la matrice per-harness. + Il blocco di una chiamata di tool prima dell'esecuzione è verificato su tutti e 12. I gate di fine turno sono verificati su 8 — vedi [capacità di enforcement](/it/reference/harnesses#enforcement-capability) per la matrice per-harness. - Segui [Esegui il tuo primo controllo di errore](/it/start/first-audit). Utilizza un obiettivo concreto come ad esempio "trovare sessioni dove l'agente ha ritentato uno strumento non riuscito senza cambiare il suo approccio." + Segui [Esegui il tuo primo controllo di errore](/it/start/first-audit). Usa un obiettivo concreto come "trova sessioni in cui l'agente ha ritentato uno strumento non riuscito senza cambiare il suo approccio." - Segui [Previeni il tuo primo errore con una policy](/it/start/first-policy). Inizia in modalità di osservazione, ispeziona i corrispondenti, quindi applica l'enforce della versione revisionata. + Segui [Previeni il tuo primo errore con una policy](/it/start/first-policy). Inizia in modalità osservazione, ispeziona i match, quindi applica la versione revisionata. diff --git a/docs/it/start/quickstarts/crewai.mdx b/docs/it/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..33592822e --- /dev/null +++ b/docs/it/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "Installa, strumenta e visualizza la tua prima traccia." +icon: "/images/frameworks/crewai.svg" +--- + +Tre passaggi per la tua prima traccia CrewAI. Per ulteriori dettagli su cosa contiene ogni evento, i flussi e la risoluzione dei problemi, consulta [la guida completa](/it/start/integrations/crewai). + +## Installa + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## Strumenta + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +Nulla cambia nel tuo crew, negli agenti, nei task o negli strumenti. `instrument()` si iscrive al bus degli eventi a livello di modulo di CrewAI. + +## Verifica l'arrivo + +Eseguilo una volta, quindi apri **Observe → Sessions** e seleziona il tuo ambiente. La tua esecuzione appare come una traccia ricostruita. + +Se nulla arriva, conferma che la macchina è connessa con `failproofai config --status`. + + + Cosa viene registrato, flussi, utilizzo dei token, denominazione degli span, opzioni e problemi comuni. + \ No newline at end of file diff --git a/docs/it/start/quickstarts/custom-agents.mdx b/docs/it/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..71fabe31f --- /dev/null +++ b/docs/it/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "Agenti personalizzati" +description: "Racchiudi il tuo agente in tre blocchi `with` e inizia a registrare." +icon: "code" +--- + +Per un agente che hai scritto tu stesso, o per un framework per cui Failproof AI non ha un adapter. + +Racchiudi il lavoro che fai già in blocchi `with`. Ognuno registra quando è iniziato, quando è finito e quanto tempo ha impiegato — non devi chiamare nient'altro. + +## Installazione + +```bash +pip install failproofai-sdk +``` + +Niente extra, niente dipendenze. + +## Strumentazione + +```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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # one tool call +``` + +Leggilo da cima a fondo e dice quello che significa: + +| Racchiudilo in | Per dire | +| --- | --- | +| `session()` | Questi eventi appartengono alla stessa esecuzione | +| `agent()` | Qualcosa sta svolgendo un lavoro — assegnagli un nome che riconosceresti in un elenco | +| `tool_call()` | Questo è uno strumento, e ecco cosa ha restituito | + +Annidali comunque il tuo codice si annida. Non passi mai id in giro: ogni blocco ricorda di cosa è dentro, quindi tutto ciò che registri raccoglie automaticamente l'esecuzione giusta e l'agente giusto. `async with` funziona esattamente allo stesso modo. + +## Verifica che sia arrivato + +Eseguilo una volta, poi apri **Observe → Sessions** e seleziona il tuo ambiente. La tua esecuzione appare come una traccia ricostruita. + +Se non arriva nulla, conferma che la macchina è connessa con `failproofai config --status`. + + + Ogni metodo di evento, cosa accade quando il tuo codice genera un errore, un esempio pratico, thread e async, e strumentazione di un framework senza adapter. + \ No newline at end of file diff --git a/docs/it/start/quickstarts/langchain.mdx b/docs/it/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..473332274 --- /dev/null +++ b/docs/it/start/quickstarts/langchain.mdx @@ -0,0 +1,40 @@ +--- +--- +title: "LangChain e LangGraph" +description: "Installa, strumenta e visualizza la tua prima traccia." +icon: "/images/frameworks/langchain.svg" +--- + +Tre passaggi per ottenere la tua prima traccia LangChain o LangGraph. Per lo streaming, human-in-the-loop, denominazione degli span e opzioni, consulta [la guida completa](/it/start/integrations/langchain). + +## Installa + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Per LangChain senza LangGraph, usa `failproofai-sdk[langchain]`. + +## Strumenta + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +Nessuna modifica al sito di chiamata. `instrument()` registra un tracer che LangChain inietta in ogni callback manager che costruisce, quindi i grafi, gli strumenti e i modelli vengono catturati — inclusi quelli all'interno delle librerie che non hai scritto. + +## Verifica l'arrivo + +Eseguilo una volta, quindi apri **Observe → Sessions** e seleziona il tuo ambiente. La tua esecuzione appare come una traccia ricostruita. + +Se nulla arriva, conferma che la macchina è connessa con `failproofai config --status`. + + + Cosa viene registrato, streaming, conteggi dei token, denominazione degli span, controllo della sessione, opzioni e human in the loop. + \ No newline at end of file diff --git a/docs/it/start/quickstarts/llamaindex.mdx b/docs/it/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..e238db35e --- /dev/null +++ b/docs/it/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "Installa, strumenta e visualizza la tua prima traccia." +icon: "/images/frameworks/llamaindex.svg" +--- + +Tre passaggi per la tua prima traccia LlamaIndex. Per i passaggi del workflow, il recupero, il reaper e le opzioni, vedi [la guida completa](/it/start/integrations/llamaindex). + +## Installa + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## Strumenta + +L'API agente di LlamaIndex è asincrona. Ogni scope funziona sia con `async with` che con `with`. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + Senza un argomento aggiuntivo sul tuo LLM, ogni conteggio di token nella tua traccia è null — `llama-index-llms-openai` non richiede l'utilizzo quando effettua lo streaming. Vedi [Conteggi dei token](/it/start/integrations/llamaindex#token-counts). + + +## Verifica l'arrivo + +Eseguilo una volta, quindi apri **Observe → Sessions** e seleziona il tuo ambiente. La tua esecuzione appare come una traccia ricostruita. + +Se non arriva nulla, conferma che la macchina è connessa con `failproofai config --status`. + + + Conteggi dei token, cosa viene registrato, passaggi del workflow, recupero, opzioni e problemi comuni. + \ No newline at end of file diff --git a/docs/it/start/quickstarts/pydantic-ai.mdx b/docs/it/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..089ae9460 --- /dev/null +++ b/docs/it/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "Installa, strumenta e visualizza la tua prima traccia." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +Tre passi per la tua prima traccia Pydantic AI. Per strumenti, tentativi, streaming e opzioni, consulta [la guida completa](/it/start/integrations/pydantic-ai). + +## Installa + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## Strumenta + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # prima di costruire qualsiasi Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` deve essere eseguito **prima** che tu costruisca un `Agent`. La funzionalità viene aggiunta al momento della costruzione, quindi un agent creato in precedenza non registra nulla — senza errore, perché non è successo niente di sbagliato. Questa è la causa più comune di una traccia vuota con questo adapter, e gli agent a livello di modulo sono dove il problema si manifesta: importa `failproofai_sdk` e chiama `instrument()` prima di importare il modulo che li costruisce. + + +## Verifica l'arrivo + +Eseguilo una volta, poi apri **Observe → Sessions** e seleziona il tuo ambiente. La tua esecuzione appare come una traccia ricostruita. + +Se non arriva nulla, conferma che la macchina è connessa con `failproofai config --status`. + + + Cosa viene registrato, strumenti e tentativi, streaming, denominazione degli span, opzioni e problemi comuni. + \ No newline at end of file diff --git a/docs/ja/index.mdx b/docs/ja/index.mdx index ace749914..42337393d 100644 --- a/docs/ja/index.mdx +++ b/docs/ja/index.mdx @@ -1,41 +1,41 @@ --- -title: "エージェントをフェイルプルーフにする" -description: "コーディングCLI、チャットゲートウェイ、セルフホスト型アシスタント、独自のインストルメント済みエージェントなど、あらゆるハーネスに対応したオブザーバビリティと制御の仕組みです。" +title: "エージェントを failproof にする" +description: "あらゆるハーネスで動作するエージェントの可観測性と制御 — コーディング CLI、チャットゲートウェイ、セルフホスト型アシスタント、独自にインストルメント化されたエージェントに対応。" icon: "shield-check" --- -Failproof AI は、エージェントが何をしたかを把握し、どこで失敗したかを特定し、同じ問題が再発する前に安全策を展開するためのツールです。 +Failproof AI は、エージェントが何をしたかを把握し、失敗箇所を特定し、同じ挙動が再発する前にセーフガードを展開するためのツールです。 -**ハーネス**とは、エージェントが実際に動作する実行環境のことです。Failproof AI は Claude Code や Codex などのコーディングCLI、Hermes などのチャットゲートウェイ、OpenClaw などのセルフホスト型アシスタントを含む12種類のハーネスに対応しており、すべてに同じイベント・ポリシー・セッション履歴が適用されます。ハーネスを使用しないエージェントは [Python SDK](/ja/reference/custom-agents) 経由でトレースと監査を行いますが、そこでポリシーを強制するには独自のランタイムにフックを実装する必要があります。 +**ハーネス**とは、エージェントが実際に動作する環境のことです。Failproof AI は 12 種類のハーネスに対応しています。Claude Code や Codex などのコーディング CLI、Hermes などのチャットゲートウェイ、OpenClaw などのセルフホスト型アシスタントが含まれており、すべてに同じイベント・ポリシー・セッション履歴が適用されます。ハーネスを持たないエージェントは [Python SDK](/ja/reference/custom-agents) 経由でレポートを送信し、トレースと監査が行われます。その場合のポリシー適用には、独自ランタイム内でのフックが必要です。 - - スキルを使ってプロジェクトをインストルメントし、接続して、エージェントログが届いていることを確認します。 + + スキルを使ってプロジェクトをインストルメント化し、接続して、エージェントのログが届いていることを確認します。 - - エージェントログに対して自然言語で分析・クエリ・ダッシュボード作成・監査を実行します。 + + エージェントログに対して自然言語で分析・クエリ・ダッシュボード構築・監査を実行します。 - - モデル呼び出し、ツール、エラー、人間の入力、レイテンシ、ポリシーの判断を1つのセッションで追跡します。 + + モデルの呼び出し、ツール、エラー、人間の入力、レイテンシ、ポリシーの判定を 1 つのセッションで追跡します。 - - 定義されたセッションセットを監査し、根拠に基づく知見をレビューし、課題として修正状況を追跡します。 + + 定義されたセッション群を監査し、証拠に基づく知見をレビューし、問題として修正状況を追跡します。 - - 既知の障害パターンをポリシーに変換し、その影響を観察して、フリート全体に展開します。 + + 既知の障害パターンをポリシーに変換し、影響を観察してフリート全体に展開します。 -> **セッション → 監査 → 知見 → 課題 → ポリシー**
-> 何が起きたかをトレースし、障害を特定し、対応を管理して、将来の実行で同じ問題が起きないようにします。 +> **セッション → 監査 → 知見 → 問題 → ポリシー**
+> 何が起きたかをトレースし、失敗を発見し、対応を管理して、同じ挙動を将来の実行で防止します。 -## はじめに +## まずここから -初めてインストルメント済みエージェントをデプロイする場合は、[クイックスタート](/ja/start/quickstart)から始めてください。データがすでに届いている場合は、[セッション](/ja/sessions/overview)を開いて、監査やポリシーを設定する前に実際の実行結果を確認してください。 +初めてインストルメント化されたエージェントをデプロイする場合は、[クイックスタート](/ja/start/quickstart) から始めてください。すでにデータが届いている場合は、[セッション](/ja/sessions/overview) を開き、監査やポリシーを設定する前に実際の実行内容を確認してください。 - + キャプチャから安全にデプロイされたポリシーまで、エンドツーエンドのワークフローを完了します。 \ No newline at end of file diff --git a/docs/ja/policies/deploy.mdx b/docs/ja/policies/deploy.mdx index 806debd3b..fe854c3a7 100644 --- a/docs/ja/policies/deploy.mdx +++ b/docs/ja/policies/deploy.mdx @@ -4,44 +4,48 @@ description: "レビュー済みのポリシーバージョンを対象マシン icon: "cloud-upload" --- -デプロイメントは、1つ以上のポリシーバージョンを登録済みマシンの対象セットに紐付けます。 +デプロイメントは、1つ以上のポリシーバージョンを登録済みマシンのターゲットセットに紐付けます。 ## デプロイメントの適用 1. **Admin → enforcement** に移動し、対象マシンを見つけて行を展開します。 - 2. **edit** を選択し、レビュー済みのポリシーバージョンを追加して、**observe** またはエンフォースメント効果を選択します。 + 2. **edit** を選択し、レビュー済みのポリシーバージョンを追加して、**observe** または適用する効果を選択します。 3. 変更を適用し、マシンの次回チェックインを待ってデプロイメントとカバレッジの状態を確認します。 - 4. **Observe → policy** に移動してライブの判定を確認します。 + 4. **Observe → policy** に移動してリアルタイムの判断内容を確認します。 - ![ポリシーバージョン、エンフォースと観察の効果、デプロイメント適用アクションが表示されたマシンデプロイメントエディター。](/images/dashboard/enforcement-editor.png) + ![ポリシーバージョン、enforce・observe の効果、デプロイメント適用アクションを備えたマシンデプロイメントエディタ。](/images/dashboard/enforcement-editor.png) - クラウドデプロイメントのエンドポイントは、通常の `fp` コマンドとして意図的に公開されていません。マシンをローカルで確認した後、ダッシュボードからデプロイしてください。 + `fp fleet` を使用して CLI からデプロイします。適用前に結果セットを確認してください — `deploy` は全プランを出力し、**`--json` なしのインタラクティブなターミナルでのみ**確認を求めます。`--json` 指定時、`--yes` 指定時、または stdin がリダイレクトされている場合（CI ステップ、スクリプト、エージェントからのシェル呼び出しなど）は、プランや確認プロンプトなしに即座に適用されます。レビューを行いたい場合は、事前に `fp fleet show ` を実行してください： ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - デプロイ後は `fp sessions --env production --since 24h` と `fp events --event-type hook_completed` を使用して、アクティビティがクラウドに届いているかを確認してください。 + `fp fleet diff ` は意図と実際の配信状況の差分を表示します（マシンは次回ポーリングまで `behind` と表示されます）。`fp fleet history ` は世代の一覧を表示し、`fp fleet rollback ` で特定の世代に戻すことができます — ただし、その世代が無効化または削除済みのポリシーを参照している場合は拒否されます。 + + マシン自体の状態は `failproofai config --status` で確認し、デプロイ後は `fp sessions --env production --since 24h` および `fp events --event-type hook_completed` を使用してアクティビティが Cloud に届いているかを検証してください。 - 変更可能なドラフトではなく、レビュー済みのバージョンをデプロイしてください。最初は非本番マシンまたはセッションを監視できる小さなコホートから始めてください。 + 変更可能なドラフトではなく、レビュー済みのバージョンをデプロイします。最初は本番環境以外のマシン、またはセッションを確認できる小規模なグループから始めてください。 - - 作業をブロックせずに、マッチ内容・理由・影響を受けるツール・誤検知を確認します。 + + 作業をブロックせずに、マッチ結果・理由・影響を受けるツール・誤検知を確認します。 - - 観察されたマッチが安全でないアクションと有効なアクションを区別できたら昇格させ、意図したすべてのマシンがデプロイメントを取得して判定を報告していることを確認します。 + + 観察されたマッチが安全でないアクションと正当なアクションを区別できるようになってから昇格させ、意図した全マシンがデプロイメントを取得して判断内容を報告していることを確認します。 -マシンには `policies:pull` 機能が必要です。イベントレポートは `events:add` によって個別に制御されます。クラウドでの分析とエンフォースメントを期待する場合は、両方を確認してください。 +マシンには `policies:pull` 機能が必要です。イベントレポートは `events:add` によって個別に制御されます。Cloud による分析と適用を期待する場合は、両方を確認してください。 - エンフォースメント管理は管理者向けのクラウドワークフローです。root 専用のエンフォースメントルートを通常の顧客向け `/v1` API エンドポイントとして扱わないでください。 + エンフォースメント管理は管理者向けの Cloud ワークフローです。root 専用のエンフォースメントルートを一般的なカスタマー向け `/v1` API エンドポイントとして扱わないでください。 \ No newline at end of file diff --git a/docs/ja/policies/editor.mdx b/docs/ja/policies/editor.mdx index 3c779a1a5..9e23dc514 100644 --- a/docs/ja/policies/editor.mdx +++ b/docs/ja/policies/editor.mdx @@ -1,47 +1,49 @@ --- title: "ポリシーエディター" -description: "確認された障害モードからバージョン管理されたポリシーを作成・修正します。" +description: "確認された失敗パターンからバージョン管理されたポリシーを作成・改訂します。" icon: "file-pen-line" --- -ポリシーエディターを使用して、発見した問題をデプロイ可能なルールに変換します。下書きが本番の動作を知らないうちに変更しないよう、作成とデプロイは分けて管理してください。 +ポリシーエディターを使用して、検出された問題をデプロイ可能なルールへと変換します。下書きがライブの動作をサイレントに変更しないよう、作成とデプロイを分離しています。 -問題に再現可能なアクションパターンがある場合は、**Analyze → issues** から該当の問題を開き、**generate policy** を選択します。Failproof AI はまずそのポリシーで問題を表現できるかどうかを説明し、レビュー済みの意図と発見内容のコンテキストをエディターに引き継ぎます。生成されたソースはパブリッシュするまで下書きのままです。 +問題に繰り返し可能なアクションパターンがある場合は、**Analyze → issues** で該当の問題を開き、**generate policy** を選択してください。Failproof AI はまずそのポリシーで問題を表現できるかどうかを説明し、レビュー済みのインテントと検出コンテキストをエディターに引き継ぎます。生成されたソースは公開するまで下書きのままです。 -## ポリシーバージョンのパブリッシュ +## ポリシーバージョンの公開 - 1. **Admin → policy editor** に移動し、**compose** で障害モードを説明するか、JavaScript ポリシーのソースを貼り付けます。 + 1. **Admin → policy editor** に移動し、**compose** で失敗モードを説明するか、JavaScript ポリシーソースを貼り付けます。 2. ソースを検証し、報告されたすべてのエラーを修正します。 - 3. ポリシーの識別情報を入力してパブリッシュし、**library** を使用してバージョンの比較や無効化を行います。 - 4. バージョンをマシンへのロールアウトに使用する準備ができたら **enforcement** を選択します。 + 3. ポリシーの識別情報を入力して公開し、**library** を使用してバージョンの比較や無効化を行います。 + 4. マシンへのロールアウトの準備ができたら **enforcement** を選択します。 - ![ポリシー識別情報、AI支援による下書き作成、ソース検証、パブリッシュコントロールを備えたポリシーエディターのコンポーズビュー。](/images/dashboard/policy-editor.png) + ![ポリシーの識別情報、AI支援による下書き、ソース検証、公開コントロールを備えたポリシーエディターのcomposeビュー。](/images/dashboard/policy-editor.png) - Cloud CLI はポリシーバージョンをパブリッシュできません。エディターにコピーする前に、ソースをローカルで検証してください。 + CLI から `fp policies publish` を使用して公開します。このコマンドは**新しいバージョン**を作成するのみで、既存のバージョンをその場で編集することはありません。また、送信前に node でソースの構文チェックを行います。下流では誰もチェックしないため、構文エラーがあるとエンフォースメント時にマシン上で表面化してしまいます。 ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - レビュー済みのバージョンは **Admin → policy editor** からパブリッシュしてください。 + 公開してもデプロイは行われません。新しいバージョンは `fp fleet deploy` でマシンに配備されるまで未使用のままです。`fp policies compose ""` は Cloud アシスタントを使ってソースの下書きを生成し、公開せずにレビュー用として出力します。 + + Cloud ではなくローカルのエージェント CLI にポリシーをインストールするには、`failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project` を使用してください。 ## 作成チェックリスト -1. 運用上の言葉で障害モードを命名する。 -2. 判断に必要な十分な情報を持つフックイベントとツールを選択する。 -3. 安全でない動作に一致する最も絞り込まれた条件を記述する。 +1. 運用上の言葉で失敗モードを明名する。 +2. 判断に十分な証拠を含むフックイベントとツールを選択する。 +3. 安全でない動作に一致する最も狭い条件を記述する。 4. エージェントまたはオペレーターが次に何をすべきかを伝える理由を返す。 -5. 一致すべき例と、許可したままにすべき例を追加する。 -6. 新しいバージョンを保存し、レビューを依頼する。 +5. 一致すべき例と、許可されたままであるべき例を追加する。 +6. 新しいバージョンを保存してレビューを依頼する。 -エージェントが安全にコースを修正できる場合は `instruct` を使用します。アクションを許可すると受け入れ難い、または取り返しのつかないリスクが生じる場合は `deny` を使用します。 +エージェントが安全に軌道修正できる場合は `instruct` を使用します。そのアクションを許可することが受け入れがたいリスクや取り返しのつかない結果をもたらす場合は `deny` を使用します。 - ポリシーバージョンはイミュータブルなデプロイ入力です。下書きを編集すると新しいバージョンが作成されます。マシンにすでに割り当てられているバージョンを上書きしないようにしてください。 + ポリシーバージョンはイミュータブルなデプロイ入力です。下書きを編集すると新しいバージョンが作成されます。すでにマシンに割り当てられているバージョンを上書きしないようにしてください。 \ No newline at end of file diff --git a/docs/ja/reference/cloud-cli.mdx b/docs/ja/reference/cloud-cli.mdx index 4c2ef304e..e2b5ce3b0 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` を使用して、クラウドのテレメトリを検査し、クラウド管理の強制適用（ポリシー、フリートデプロイ、ガードレール判定）を管理し、監査、検知、問題、アラート、キー、ユーザー、クエリ、設定を管理します。ローカルフック、ポリシー、キャプチャ、マシン登録には [`failproofai`](/ja/reference/failproof-cli) を使用してください。 -リリース済みの 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,9 +40,9 @@ fp --json sessions --since 24h | コマンド | 目的 | オプション | | --- | --- | --- | -| `fp login` | メールで受け取るワンタイムコードでサインインし、組織を選択します。 | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | 保存されたユーザーセッションを失効・削除します。 | — | -| `fp whoami` | 現在の ID・認証モード・組織・権限を表示します。 | — | +| `fp login` | メールで送付されるワンタイムコードでサインインし、組織を選択します。 | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | 保存されたユーザーセッションを失効させ削除します。 | — | +| `fp whoami` | 現在の ID、認証モード、組織、権限を表示します。 | — | | `fp version` | インストール済みの CLI バージョンを表示します。 | — | | `fp help` | トップレベルのコマンドヘルプを表示します。 | — | @@ -57,30 +57,34 @@ fp whoami fp events [OPTIONS] ``` -個々のエージェントイベントを一覧表示します。デフォルトの軽量フィードは生ペイロードを除外します。`--full` は対象を絞った調査のみに使用してください。 +個別のエージェントイベントを一覧表示します。デフォルトの軽量フィードは生のペイロードを除外します。`--full` は範囲を限定した調査にのみ使用してください。 | オプション | 説明 | | --- | --- | -| `--limit`, `-n ` | 最大取得行数。デフォルト: `50`。 | -| `--since ` | `all`、`15m`、`1h`、`6h`、`24h`、または `7d`。 | +| `--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` まで自動ページネーション。 | | `--cursor ` | 不透明なカーソルから再開。 | | `--page-size ` | `--all` 使用時のリクエストあたりの行数。最大 `200`。 | -| `--full` | より重いイベントエンドポイントから生ペイロードを含めて取得。 | -| `--fields ` | 指定したフィールドのみを返す。`payload` を指定するとフルモードが有効になります。 | +| `--full` | より重いイベントエンドポイントを通じて生のペイロードを含めます。 | +| `--fields ` | 選択したフィールドのみ返します。`payload` を指定するとフルモードが有効になります。 | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` + + `--all` は **`--limit` まで**ページネーションしますが、デフォルトは **50** です。つまり `--all` 単独では 50 行で停止します。途中で停止した場合、レスポンスには再開用の `next_cursor` が含まれます。`"next_cursor": null` はフィードが完全に消化されたことを意味します。 + + ### セッション ```text @@ -89,19 +93,19 @@ fp sessions [OPTIONS] | オプション | 説明 | | --- | --- | -| `--limit`, `-n ` | 最大取得行数。デフォルト: `50`。 | -| `--since ` | `all`、`15m`、`1h`、`6h`、`24h`、または `7d`。 | +| `--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`。 | -| `--fields ` | 指定したフィールドのみを返す。 | -| `--full-ids` | ターミナル出力でセッション ID を短縮しない。 | -| `--agents` | マルチエージェントセッションのエージェント一覧を展開表示。 | +| `--fields ` | 選択したフィールドのみ返します。 | +| `--full-ids` | ターミナル出力でセッション ID を短縮しません。 | +| `--agents` | マルチエージェントセッションのエージェントリストを展開します。 | ### 評価 @@ -111,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` | ターミナル出力にすべてのスコアを表示します。 | ### エラー @@ -129,118 +133,118 @@ fp errors [OPTIONS] | オプション | 説明 | | --- | --- | -| `--aggregate` | 行を一覧表示する代わりに、一致するエラーを集計。 | +| `--aggregate` | 行を列挙する代わりに一致するエラーを集計します。 | | `--limit`, `-n ` | 最大リスト行数。デフォルト: `50`。 | -| `--since`, `--from`, `--to` | 時間範囲を選択。 | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | エラーの対象を絞り込み。 | -| `--search ` | ペイロードテキストを検索。繰り返し可能。 | +| `--since`, `--from`, `--to` | 時間範囲を選択します。 | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | エラーの対象範囲を絞り込みます。 | +| `--search ` | ペイロードのテキストを検索します。繰り返し指定可能。 | | `--order asc\|desc` | 時間順。 | -| `--all`, `--cursor`, `--page-size` | リストのページネーションを制御。 | -| `--fields ` | 指定したフィールドのみを返す。 | -| `--full-ids` | セッション ID を完全表示。 | +| `--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 キー | コマンド | 目的 | オプション | | --- | --- | --- | -| `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` | +| `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` | -権限トークンは `resource:action` の形式を使用します（例: `events:add`）。`--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` | アラートを更新または名前変更。 | 作成オプションに加えて `--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` | アラートを更新または名前変更します。 | 作成オプションに加え `--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` | 指定されていない値を保持しながら監査設定を置き換えます。 | 定義作成オプション; `--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 ` 必須 | #### 監査作成オプション @@ -257,95 +261,139 @@ fp audits create checkout-reliability \ | オプション | 説明 | | --- | --- | -| `--file ` | JSON をもとに定義するか、stdin には `-` を使用。明示的なフラグがファイルの値を上書きします。 | -| `--description ` | 障害の質問または目的を記述。 | -| `--enabled` / `--disabled` | スケジューリングをオン/オフで開始。デフォルト: 有効。 | -| `--schedule-interval-secs ` | `3600`〜`604800`。デフォルト: `86400`。 | +| `--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 ''` | 通知チャンネルの配列。 | +| `--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 参照を追加。最大5回繰り返し可能。 | +| `--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` | - -有効な課題の状態は `firing`、`acknowledged`、`resolved` です。スタンドアロン課題の重大度は `info`、`warning`、`critical` です。 - -### Cloud アシスタント +| `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` です。 + +### クラウドアシスタント | コマンド | 目的 | オプション | | --- | --- | --- | -| `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` に意図的に存在しないルート専用の書き込みルートであるためです。 + +| コマンド | 目的 | オプション | +| --- | --- | --- | +| `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 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 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` は自動化を目的としています。ログイン、組織の切り替え、アシスタントコマンドにはユーザーセッションが必要です。 ## 環境変数 -| 変数 | 対応するフラグまたは目的 | +| 変数 | 相当するオプションまたは目的 | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | 現在の CLI 設定ディレクトリを移動。 | -| `AGENTEYE_ANALYTICS_DISABLED` または `DO_NOT_TRACK` | 匿名 CLI アナリティクスを無効化。 | -| `NO_COLOR` | カラー出力を無効化。 | - -明示的なフラグは環境変数より優先され、環境変数は保存された設定より優先されます。API キーモードでは、`--org` または `AGENTEYE_ORG` でテナントを明示的に選択してください。 +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `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` | カラー出力を無効にします。 | + +明示的なフラグが環境変数より優先され、環境変数が保存された設定より優先されます。API キーモードでは、`--org` または `FP_ORG` でテナントを明示的に指定してください。 + + + これらの `AGENTEYE_*` の名称は **`fp` では読み込まれません**。以前も読み込まれていませんでした。CLI は `FP_*` を宣言しており（`fp_cli/app.py`）、未知の変数はエラーになりません。`AGENTEYE_DASHBOARD_URL` を設定しても CLI のターゲットは変わらず、無視されてコマンドは保存されたダッシュボードに対してサイレントに実行されます。 + + `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 dae8a2d8e..3e8aacfea 100644 --- a/docs/ja/reference/custom-agents.mdx +++ b/docs/ja/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- title: "カスタムエージェント" -description: "カスタムエージェントのトレースをインストルメント化し、Failproof AI が実行を再構築して障害を検出できるようにします。" +description: "failproofai-sdk の設定、イベントカタログ、相関ルール、および配信について。" icon: "python" --- -`failproofai-sdk` を使用してカスタムエージェントのトレースをインストルメント化することで、Failproof AI が各実行を再構築し、その動作を監査し、根拠に基づく障害を検出できるようになります。SDK は構造化イベントを書き込み、Failproof デーモンがそれをクラウドに配信します。Python 3.10 以上が必要です。 +各設定・メソッド・フィールドの役割を説明します。初めてインストルメント化を行う場合は、まずガイドをご参照ください。このページはリファレンスとして利用してください。 -トレースによってカスタムエージェントを観測可能かつ監査可能にできます。安全でないアクションが実行される前に防止するには、ランタイムに enforcement hook も必要です。 + + + インストール、インストルメント化、イベントメソッド、実践例、よくある問題について説明します。 + + + LangChain、CrewAI、LlamaIndex、Pydantic AI は1回の呼び出しで自動的にインストルメント化されます。 + + - - カスタムエージェント環境でポリシーを適用するには、[Failproof AI にお問い合わせください](mailto:support@befailproof.ai)。ランタイムのモデル、ツール、ライフサイクルの境界をポリシーフックにマッピングするお手伝いをします。 - +Python 3.10 以降が必要です。実行時の依存関係はありません。 -
- -
- -## `failproofai-sdk` のインストール - -SDK は現在プライベートホイールとして配布されています。最新バージョンとダウンロードアクセスについては、Failproof AI の担当者にお問い合わせください。 +## インストール ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -`uv` を使用する場合は、まずホイールをダウンロードしてから `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl` を実行してください。ホイールはプライベートアーティファクトリポジトリまたは依存関係ロックファイルに固定してください。 - -パッケージは `failproofai-sdk` としてインストールされ、Python では `failproofai` としてインポートします。 +パッケージは `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 回実行し、その正確な ID を **Observe → Events** で確認します。 + 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) ```bash @@ -51,102 +46,84 @@ python -c "import failproofai; print(failproofai.__version__)" -## 完全な実行のインストルメント化 - -プロセス起動時に `configure()` を一度呼び出します。すべてのイベント呼び出しはキーワード専用で、安定した `session_id` と `agent_id` が必要です。 +## 設定 ```python -import traceback -import uuid +import failproofai_sdk -import failproofai +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -failproofai.configure(environment="production") +| 引数 | 説明 | +| --- | --- | +| `environment` | すべてのイベントに付与されるラベルです（例：`production`、`staging`、`prod-eu`）。デフォルトは `dev` です。 | +| `flush_interval` | バックグラウンドスレッドがディスクへ書き込む頻度（秒単位）です。デフォルトは `0.5` です。 | +| `base_dir` | 書き込み先のディレクトリです。デフォルトはデーモンのスプールになります。特別な理由がない限り変更不要です。 | -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +環境変数で設定することも可能です： -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) +| 変数 | 説明 | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | コード変更なしで `environment` を設定します。ラベルがアプリではなくデプロイメントに属する場合に便利です。`configure()` の引数が優先されます。 | +| `FAILPROOFAI_HOME` | スプールを保持する Failproof AI のルートディレクトリを変更します。 | +| `FAILPROOFAI_SDK_STRICT` | `1` に設定すると、インストルメント化エラーがログ記録ではなく例外として発生します。 | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` に設定すると、フレームワークの互換性問題が警告を出して続行するのではなく、例外として発生します。 | -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + + **`environment` にカンマを使用しないでください。** インジェスト処理はこのフィールドをカンマで分割してフィルターを構築します。ラベルにカンマが含まれるとそのイベント全体が無視され、実行結果がサイレントに消えてしまいます。`prod,eu` ではなく `prod-eu` と記述してください。 + + `configure(environment="prod,eu")` は即座に例外を発生させるので、すぐに気づくことができます。一方 `AGENTEYE_ENVIRONMENT` は呼び出し元がないため例外を発生させられず、1度警告を出した後 `dev` にフォールバックします。 + -`agent_start` はアクターごとに一度だけ発行してください。サブエージェントの場合は、親の `session_id` を再利用し、各アクターに異なる `agent_id` を与え、`parent_id` にはセッション ID ではなく親の **エージェント ID** を設定します。 +イベントはメモリ内にキューイングされ、`flush_interval` 秒ごとにバックグラウンドで書き込まれます。インタープリター終了時には最終フラッシュが実行されます。プロセスが強制終了された場合、未書き込みのデータは失われます。 -## 設定リファレンス +## ID 管理 + +すべてのイベントはセッションとエージェントに紐づきます。**スコープが両方を自動的に設定する**ため、通常は手動で渡す必要はありません： ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| 設定 | 動作 | -| --- | --- | -| `base_dir` | 明示的なスプールルート。すべての環境変数より優先されます。 | -| `flush_interval` | メモリから JSONL へのバックグラウンド書き込み間隔（秒）。デフォルト: `0.5`。 | -| `environment` | すべてのイベントに付与されるデプロイメントラベル。デフォルトは `dev`。 | -| `FAILPROOFAI_HOME` | `custom-agents` スプールを含む Failproof AI ルートを変更します。 | - -SDK は `base_dir` が設定されている場合はそこに書き込みます。それ以外は、`FAILPROOFAI_HOME` または `~/.failproofai` 配下にある Failproof デーモンの `custom-agents` スプールを使用します。 +`session_id` や `agent_id` を明示的に渡すことも可能で、その場合はそちらが優先されます。スコープも渡された値もない場合は、クラウドが静かに破棄するイベントを送信するのではなく、`TypeError` が発生します。 -SDK は呼び出しをメモリにキューイングし、バックグラウンドスレッドでバッチ書き込みを行います。また、Python の `atexit` ハンドリングを通じて最終フラッシュも試みます。短命なワーカーの場合は、通常のインタープリタシャットダウンを許容してください。プロセスの強制終了を行うと、メモリ上のイベントが失われる可能性があります。 + + ID はコンテキスト変数で管理されます。`asyncio` タスクには自動的に引き継がれますが、**新しいスレッドには引き継がれません**。ワーカースレッドを `failproofai_sdk.propagate()` でラップしないと、そのスレッドのイベントは未関連付けのままになります。 + ## イベントカタログ -すべてのメソッドは `None` を返します。`None` のままのフィールドは、JSON の `null` として書き込まれるのではなく省略されます。 +15種類のメソッドがあります。ほとんどは**ペア**で提供されており、オープナーを呼び出した後にクローザーを呼び出すと、SDK が間隔を計測します。 -| メソッド | ID 以外の必須フィールド | オプションフィールド | +| | オープン | クローズ | +| --- | --- | --- | +| **エージェント** | `agent_start` | `agent_end` | +| | `agent_pause` | `agent_resume` | +| **モデル** | `model_request` | `model_response` | +| **ツール** | `tool_use` | `tool_result` | +| **フック** | `hook_triggered` | `hook_completed` | +| **ヒューマン** | `human_wait` | `human_input` | + +単独で使用するものが3つあります：`error`、`human_pause`、`human_interrupt`。 + + + +すべてのメソッドには `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ SDK は呼び出しをメモリにキューイングし、バックグラウン | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -完了を失敗としてカウントする場合は、`outcome="failed"`、`"error"`、`"timeout"`、または `"rejected"` を使用してください。`"failure"` を含むその他の値は、現在のバックエンドでは失敗として分類されません。 + + + + 実行を失敗としてマークするには、`outcome` に `failed`、`error`、`timeout`、`rejected` のいずれかを指定する必要があります。これ以外の値（`"failure"` のような惜しい値も含む）はすべて成功として扱われます。 + + +## ペアリングと所要時間 + +**ルールはひとつ：クローズイベントにはオープナーと同じIDを渡すこと。** これによってペアが紐づけられ、SDK が時間を計測できます。 + +| ペア | 照合キー | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**`duration_ms` を自分で渡さないでください。** SDK が自動計測します。渡した場合は `ValueError` が発生します。 -## 相関とデュレーションのルール +唯一の例外は `model_response` です。実際のプロバイダーのレイテンシはあなた自身しか知り得ないためです。この場合、ミリ秒単位の整数値を渡してください。浮動小数点数を渡すと例外が発生します（このカラムは32ビット整数であり、そうでなければ空になってしまうためです）。 -- 対応する完了イベントには、同じ `tool_call_id`、`hook_id`、`pause_id`、または `input_id` を再利用してください。 -- SDK は `tool_result`、`hook_completed`、`agent_resume`、`human_input` の `duration_ms` を自動計算します。これらのメソッドに自分で渡すと `ValueError` が発生します。 -- ツールとフックの ID はプロセス全体の pending マップを共有します。並行セッション間および両方の名前空間をまたいでグローバルに一意にしてください。プロバイダー ID や UUID が最も安全です。 -- ペアがプロセスをまたいで分割されている場合でも、ダウンストリームで相関は行われますが、SDK はプロセス内のデュレーションを計算できません。 -- pending マップは最大 10,000 件の開始エントリを保持し、満杯になると最も古いエントリを退出させます。 + -## カスタムフィールドとペイロード +- **IDはイベントの種類とセッション単位でユニークであれば十分です。** ツール呼び出しとフックが同じIDを共有しても問題ありません。また、同時に実行中の2つのセッションが同じIDを再利用しても衝突しません。 +- **IDはエージェントにスコープされません。** あるエージェントでオープンされたペアが別のエージェントでクローズされても、正しく照合されます。マルチエージェントコードではこれが通常の動作です。 +- **`request_id` は任意ですが推奨されます。** 指定しない場合、モデルイベントは到着順にペアリングされるため、同一エージェント内で並行する2つの呼び出しのペアが入れ違いになる可能性があります。 +- **プロセスをまたいで分割されたペア**もクラウド上では照合されますが、SDK はその時間を計測できません（どちらのプロセスも両方のイベントを見ていないためです）。 +- **同時に待機できるオープナーは最大10,000件です。** これを超えると最も古いものから破棄されるため、リークが無限に増大することはありません。 -すべてのイベントは追加のキーワードフィールドを受け付けます。ダウンストリームクエリで構造が必要な場合は、JSON 互換の値を使用してください。UUID、datetime、Decimal、set、bytes、モデルオブジェクトなど、サポートされていないリーフ型はライターによって文字列化されます。 + -予約済みのカスタム名は `timestamp`、`session_id`、`agent_id`、`type`、`environment` です。オプションフィールドのタイプミスは新しいカスタムフィールドとして受け入れられるため、標準フィールドがクラウドに表示されない場合は、発行された JSON を確認してください。 +## カスタムフィールド -## 配信と検証 +イベントに追加のキーワードを渡すと、そのままイベントと一緒に保存されます： + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # カスタムフィールド +) +``` + +後でクエリを実行したい場合は、JSON で表現可能な型を使用することをお勧めします。UUID、datetime、`Decimal`、set、bytes、モデルオブジェクトなど、それ以外の値は文字列として保存されます。 + + + **フィールド名にプレフィックスを付けてください。** カスタムフィールドは最後に適用されるため、`model`、`tool_name`、`outcome` といった名前のフィールドは、実際の値を黙って上書きしてしまいます。フレームワークアダプターは `fw_` プレフィックスを使用しています。同様にすれば衝突は起こりません。 + + これは、任意フィールドのスペルミスがエラーにならない理由でもあります。新しいカスタムフィールドとして扱われてしまいます。クラウドで標準フィールドが見当たらない場合は、まずスペルを確認してください。 + + +以下の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 @@ -189,10 +203,14 @@ SDK は呼び出しをメモリにキューイングし、バックグラウン -クラウドが空の場合は、`$FAILPROOFAI_HOME/custom-agents/events`、それ以外は `~/.failproofai/custom-agents/events` を確認してください。JSONL ファイルは SDK の発行を証明します。スプールが増加している場合はデーモンの設定や配信の問題、スプールが空の場合はインストルメント化またはプロセスライフタイムの問題を示しています。 +クラウドにデータが届いていない場合は、`$FAILPROOFAI_HOME/custom-agents/events`（未設定の場合は `~/.failproofai/custom-agents/events`）を確認してください。JSONL ファイルが存在すれば SDK からの送信は成功しています。スプールが増え続けている場合はデーモンの設定や配信の問題です。スプールが空の場合はインストルメント化またはプロセスのライフタイムに問題があります。 + + + スプールを確認するのはデーモンが停止しているときだけにしてください。デーモンが稼働中は、各バッチを数ミリ秒以内に収集・削除するため、ディレクトリ一覧をコレクターと競合して確認すると、実際に送信されたイベントよりもはるかに少ない件数しか表示されません。 + ## カスタムランタイムでの障害防止 -監査結果とリンクされたトレースを使用して、安全でないアクション、必要な証拠、および意図した応答を定義します。カスタム enforcement インテグレーションは、実行前にアクションを公開し、その構造化された入力をポリシーエンジンに渡し、結果として得られる allow、instruct、または deny の決定を適用する必要があります。 +監査結果とリンクされたトレースを使用して、安全でないアクション、必要なエビデンス、意図された応答を定義します。カスタムエンフォースメントインテグレーションは、実行前にアクションを公開し、構造化された入力をポリシーエンジンに渡し、その結果である allow、instruct、または deny の判定を適用する必要があります。 -[support@befailproof.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/events-and-configuration.mdx b/docs/ja/reference/events-and-configuration.mdx index 0cb7d95dd..4276db284 100644 --- a/docs/ja/reference/events-and-configuration.mdx +++ b/docs/ja/reference/events-and-configuration.mdx @@ -4,38 +4,38 @@ description: "イベントモデル、環境、ローカルストレージ、設 icon: "list-tree" --- -## イベントの種類 +## イベントファミリー -- エージェントの開始・終了・一時停止・再開 +- エージェントの開始、終了、一時停止、再開 - モデルのリクエストとレスポンス - ツールの使用と結果 - フックのトリガーと完了 -- 人間の待機・入力・一時停止・割り込み +- 人間の待機、入力、一時停止、割り込み - 明示的なエラー -すべてのイベントには、タイムスタンプ、セッションID、エージェントID、イベントタイプ、環境が含まれます。イベント固有のフィールドには、モデル、ツール、相関関係、結果、コンテンツ、所要時間、またはエラーデータが含まれます。 +すべてのイベントには、タイムスタンプ、セッションID、エージェントID、イベントタイプ、および環境が含まれます。イベント固有のフィールドには、モデル、ツール、相関、結果、コンテンツ、継続時間、またはエラーのデータが含まれます。 -## イベントコントラクトの確認 +## イベントコントラクトを調べる 1. **Observe → Events** を開きます。 - 2. 短い時間ウィンドウを設定し、環境・エージェント・イベントタイプでフィルタリングします。 + 2. 短い時間範囲を設定し、環境、エージェント、イベントタイプでフィルタリングします。 3. イベントを選択して正規化されたフィールドと生のペイロードを確認し、セッションを開いて実行コンテキストを確認します。 - 4. ペアになっている所要時間が欠けている場合は、開始イベントと完了イベントが同じ相関IDを使用しているか確認してください。 + 4. ペアの継続時間が見つからない場合は、開始イベントと完了イベントが同じ相関IDを使用しているか確認してください。 - Eventsストリームを使って、データを1つのエージェント実行に絞り込み、正規化されたイベントフィールドを確認します。 + Eventsストリームを使用してデータを1つのエージェント実行に絞り込み、正規化されたイベントフィールドを調べます。 - ![環境・エージェント・セッション・イベントタイプのフィルターが付いたライブのEventsストリーム。](/images/dashboard/events-stream.png) + ![環境、エージェント、セッション、イベントタイプのフィルターが付いたライブEventsストリーム。](/images/dashboard/events-stream.png) - 次に、イベントからそのセッションへと追っていきます。トレースには、そのイベントの直前と直後に何が起きたかが示されており、ペイロードだけでは判断が難しい場合に役立ちます。 + 次に、イベントからそのセッションへと進みます。トレースには、そのイベントの直前と直後に何が起きたかが表示されます。これは、ペイロードだけでは判断が難しい場合に必要な情報です。 - ![実行コンテキストでイベントを確認するためのリンク済みセッショントレース。](/images/dashboard/session-detail.png) + ![実行コンテキストでイベントを調べるために使用されるリンクされたセッショントレース。](/images/dashboard/session-detail.png) - ペアになったイベントや所要時間が欠けている場合は、両方のビューで相関IDとタイムスタンプを比較してください。 + ペアになったイベントや継続時間が見つからない場合は、両方のビューで相関IDとタイムスタンプを比較してください。 - 有効なフィルター値を確認した後、1つのセッションの完全なイベントペイロードを取得します： + 有効なフィルター値を確認し、1つのセッションのイベントペイロード全体を取得します： ```bash fp list event_types @@ -47,32 +47,32 @@ icon: "list-tree" --full ``` - 機械可読な形式で確認するには `fp --json events ... --fields ts,event_type,session_id,payload` を使用してください。 + 機械可読な形式での確認には `fp --json events ... --fields ts,event_type,session_id,payload` を使用してください。 -## SDKの予約フィールド +## 予約済みSDKフィールド -`timestamp`、`session_id`、`agent_id`、`type`、`environment` をPython SDKのカスタムフィールドとして使用しないでください。ツール結果の所要時間などのペアになったイベントの所要時間はSDKによって計算されるため、手動で指定することはできません。 +`timestamp`、`session_id`、`agent_id`、`type`、`environment` をカスタムPython SDKフィールドとして使用しないでください。ツール結果の継続時間などのペアイベントの継続時間はSDKによって計算されるため、手動で設定することはできません。 ## ローカルの境界 -- Failproof AI の状態は、明示的に設定が変更されない限り `~/.failproofai` 以下に保存されます。 -- `failproofai-sdk` はレガシーのベースディレクトリ上書き用として `AGENTEYE_HOME` を使用します。 -- 環境ラベルはSDK設定または `AGENTEYE_ENVIRONMENT` を通じて設定できます。 -- デーモンの認証情報はシークレットでない設定とは別に保存されます。 +- Failproof AI の状態は、明示的に別の設定をしない限り `~/.failproofai` 以下に保存されます。 +- `failproofai-sdk` は常に `~/.failproofai/custom-agents` にスプールします。`FAILPROOFAI_HOME` でホームディレクトリを変更できますが、`custom-agents` セグメントは常に追加されるため、スプールをその外に配置することはできません。SDKの `configure(base_dir=...)` のみが別の場所に書き込みます。`AGENTEYE_HOME` は古い `agenteye-collector` が監視対象を決定するために読み取るものであり、SDKの書き込み先には影響しません。 +- 環境ラベルはSDK設定または `AGENTEYE_ENVIRONMENT` で設定できます。 +- デーモンの認証情報は、非シークレット設定とは別に保存されます。 -安定した低カーディナリティの環境名を使用してください。デーモンの環境ラベルではカンマはサポートされていません。 +安定した、カーディナリティの低い環境名を使用してください。デーモンの環境ラベルにカンマは使用できません。 -## 環境ラベルの変更 +## 環境ラベルを変更する - 環境ラベルは、発行元のSDKまたはFailproofデーモンによって割り当てられます。変更後は **Observe → Sessions** を開き、環境フィルターを使って新しいセッションに新しい値が付いていることを確認してください。既存のセッションは元の環境を保持します。 + 環境ラベルは、送信するSDKまたは Failproof デーモンによって割り当てられます。変更後は、**Observe → Sessions** を開き、環境フィルターを使用して新しいセッションに新しい値が反映されていることを確認してください。既存のセッションは元の環境を保持します。 - `failproofai-sdk` の場合は、コード内または旧来の環境変数を使って環境を設定します。マシンレベルの設定を変更した場合はデーモン設定を再実行してください。 + `failproofai-sdk` の場合は、コード内またはレガシーの環境変数で環境を設定します。マシンレベルの設定を変更する場合はデーモンの設定を再実行してください。 ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/ja/reference/harnesses.mdx b/docs/ja/reference/harnesses.mdx index 160c598fa..89c6bb3b1 100644 --- a/docs/ja/reference/harnesses.mdx +++ b/docs/ja/reference/harnesses.mdx @@ -4,14 +4,14 @@ description: "サポートされている12のエージェントハーネス全 icon: "plug-zap" --- -ハーネスとは、エージェントが実際に動作する環境のことです。Failproof AI は12種類のハーネスを2つのクラスに分けてサポートしています。 +ハーネスとは、エージェントが実際に動作する環境のことです。Failproof AI は12種類のハーネスをサポートしており、2つのクラスに分類されます。 -- **コーディング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の標準イベントにマッピングしてから、ポリシーが実行されます。 +エージェントがどのハーネスで動作していても、同じポリシーと同じセッション履歴が適用されます。アダプター層が各ハーネスのネイティブイベント名、ツール名、ツール入力フィールドを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)いただければ、マッピング対応いたします。 | ハーネス | サポートされているフックスコープ | | --- | --- | @@ -20,47 +20,47 @@ 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` | ポストツール、セッション、サブエージェントストップの判定はゲートとして機能しません。 | +| 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` の権限を持つキーをマシンまたは環境の名前で作成します。 + 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) @@ -82,7 +82,7 @@ icon: "plug-zap" --scope user ``` - プロジェクトスコープはフック設定をリポジトリと一緒に保持します。ユーザースコープはリポジトリをまたいだ作業をカバーします。Claude Code はローカルスコープもサポートしていますが、サポート状況はハーネスによって異なり、CLIはサポートされていない組み合わせを拒否します。 + プロジェクトスコープはリポジトリと共にフック設定を保持します。ユーザースコープはリポジトリをまたいだ作業をカバーします。Claude Code はローカルスコープもサポートしていますが、サポート状況はハーネスによって異なり、サポートされていない組み合わせはCLIが拒否します。 マシンとそのイベントを確認します。 @@ -94,16 +94,16 @@ icon: "plug-zap" -## デフォルト以外のセッションパスの追加 +## デフォルト以外のセッションパスを追加する - 追加パスはクラウドではなくマシン上で登録されます。追加した後、**Observe → Sessions** を開き、マシンの環境でフィルタリングして、新しいパスからのセッションが表示されることを確認します。監査で使用する前に、セッションを開いてエージェント、ハーネス、イベントのタイムスタンプを確認してください。 + 追加パスはクラウドではなくマシン上に登録されます。追加後は **Observe → Sessions** を開き、マシンの環境でフィルタリングして、新しいパスからのセッションが表示されることを確認します。セッションを開いて、監査に使用する前にエージェント、ハーネス、イベントのタイムスタンプを確認してください。 - ![追加のキャプチャパスからデータを受信している環境にフィルタリングされたSessionsリスト。](/images/dashboard/sessions-list.png) + ![追加キャプチャパスからのデータを受信している環境でフィルタリングされたセッションリスト。](/images/dashboard/sessions-list.png) - オプションのラベルを付けてパスを追加し、設定済みのパスを確認します。 + オプションのラベルを付けてパスを追加し、設定されたパスを確認します。 ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -112,10 +112,10 @@ icon: "plug-zap" failproofai backfill --since 7d ``` - パスを削除するには `failproofai harness remove-path claude checkout` を使用します。 + `failproofai harness remove-path claude checkout` でパスを削除できます。 - インストール後に新しいセッションを1つ実行してください。ロールアウトを拡大する前に、ライブイベントストリームと実際のポリシー決定の両方を確認してください。 + インストール後に新しいセッションを1回実行してください。ロールアウトを拡大する前に、ライブイベントストリームと実際のポリシー決定の両方を確認してください。 \ No newline at end of file diff --git a/docs/ja/reference/overview.mdx b/docs/ja/reference/overview.mdx index 704ad6f7b..bc2a2dcda 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" --- @@ -10,52 +10,55 @@ icon: "braces" 対応するコーディング・自律エージェント CLI 向けにフックをインストールします。 - - カスタムエージェントの障害を検出するためにトレースを計装し、ランタイムへの防止策の追加についてお問い合わせください。 + + LangGraph、CrewAI、LlamaIndex、Pydantic AI、またはカスタムエージェントを計装します。 + + + 設定、イベントカタログ、相関ルール、デリバリーについて説明します。 ローカルプロジェクト、セッション、ポリシーアクティビティ、オフライン監査を確認します。 - ローカルキャプチャ、フック、ポリシー、監査、配信、マシン状態を設定します。 + ローカルキャプチャ、フック、ポリシー、監査、デリバリー、マシン状態を設定します。 - Cloud のセッション、監査、Issues、アラート、キー、ユーザー、設定をクエリ・管理します。 + クラウドのセッション、監査、問題、アラート、キー、ユーザー、設定を照会・管理します。 - + 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. **Administration → Keys** を開き、`events:add` と `policies:pull` 権限を持つキーを作成してシークレットをコピーします。 - 2. 上記の対応するページを参照してインテグレーションを設定します。 - 3. **Observe → Events** を開いてイベントが届いていることを確認し、続いて **Observe → Sessions** でイベントが完全な実行として形成されていることを確認します。 - 4. インテグレーションの環境でフィルタリングし、監査に必要なモデル、ツール、エラー、ポリシーのフィールドが含まれているセッションを 1 つ確認します。 + 1. **Administration → Keys** を開き、`events:add` と `policies:pull` の権限を持つキーを作成してシークレットをコピーします。 + 2. 上記の対応するページを使用してインテグレーションを設定します。 + 3. **Observe → Events** を開いてイベントが届いていることを確認し、次に **Observe → Sessions** でそれらが完全な実行として形成されていることを確認します。 + 4. インテグレーションの環境でフィルタリングし、監査に必要なモデル、ツール、エラー、ポリシーのフィールドを確認するためにセッションを 1 件開きます。 - まずキードロワーから始めてください。選択した権限によって、マシンがイベントを送信し、Cloud 管理のポリシーを受信できるかどうかが決まります。 + まずキードロワーから始めてください。選択した権限によって、マシンがイベントを送信したり Cloud 管理のポリシーを受信したりできるかどうかが決まります。 - ![イベントインジェストとポリシー配信の権限を付与するための新規 API キードロワー。](/images/dashboard/key-create.png) + ![イベント取り込みとポリシーデリバリーの権限を付与するための新しい API キードロワー。](/images/dashboard/key-create.png) - インテグレーションを接続したら、セッションリストを使用して、イベントが期待される環境で完全な実行としてグループ化されていることを確認してください。 + インテグレーションを接続したら、Sessions リストを使ってイベントが期待する環境で完全な実行としてグループ化されていることを確認します。 - ![新しく接続されたインテグレーションが完全なエージェント実行を報告しているかを確認するためのセッションリスト。](/images/dashboard/sessions-list.png) + ![新しく接続されたインテグレーションが完全なエージェント実行を報告していることを確認するための Sessions リスト。](/images/dashboard/sessions-list.png) - インテグレーションが完了と見なす前にこれらのセッションの 1 つを開いてください。トレースには、監査に必要なモデル、ツール、エラー、ポリシーの証跡が含まれているはずです。 + インテグレーションが完了したとみなす前に、これらのセッションのいずれかを開いてください。トレースには、監査に必要なモデル、ツール、エラー、ポリシーのエビデンスが含まれているはずです。 - マシンキーを作成し、Failproof デーモンを接続して、最初のセッションを検証します。 + マシンキーを作成し、Failproof デーモンを接続して、最初のセッションを確認します。 ```bash fp keys create agent-production \ @@ -71,7 +74,7 @@ icon: "braces" 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) を参照してください。 diff --git a/docs/ja/reference/troubleshooting.mdx b/docs/ja/reference/troubleshooting.mdx index 46b457a6a..88a799c55 100644 --- a/docs/ja/reference/troubleshooting.mdx +++ b/docs/ja/reference/troubleshooting.mdx @@ -5,12 +5,12 @@ icon: "wrench" --- - + - **Administration → Keys** を開き、マシンキーがアクティブで `events:add` 権限を持っていることを確認します。次に **Observe → Events** を開き、時間範囲を広げ、環境フィルターとエージェントフィルターをクリアします。イベントが存在する場合は、セッション ID を検索し、**Observe → Sessions** でグループ化を確認します。イベントが存在しない場合は、CLI から Failproof デーモンを診断してください。 + **Administration → Keys** を開き、マシンキーがアクティブで `events:add` 権限を持っていることを確認します。次に **Observe → Events** を開き、時間範囲を広げ、環境とエージェントのフィルターをクリアします。イベントが存在する場合は、セッション ID を検索し、**Observe → Sessions** でグループ化を確認します。イベントが存在しない場合は、CLI から Failproof デーモンを診断してください。 - ![主要なフィルターが表示され、最近のエージェントイベントが届いているライブイベントストリーム。](/images/dashboard/events-stream-current.png) + ![主要フィルターが表示され、最近のエージェントイベントが届いているライブイベントストリーム。](/images/dashboard/events-stream-current.png) ```bash @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - キャプチャが有効になっていること、設定済みのキーに `events:add` があること、そしてダッシュボードのフィルターが送出された環境と一致していることを確認してください。 + キャプチャが有効であること、設定済みキーが `events:add` を持っていること、ダッシュボードのフィルターが送出された環境と一致していることを確認します。 - + - **Observe → Events** のフィルターをクリアし、SDK セッション ID を正確に検索します。何も表示されない場合は、ソースマシン上の SDK スプールと Failproof デーモンを調査してください。 + **Observe → Events** のフィルターをクリアし、正確な SDK セッション ID を検索します。何も表示されない場合は、ソースマシン上の SDK スプールと Failproof デーモンを確認してください。 ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - エージェントプロセスで `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` が設定されており、SDK 起動前に `$FAILPROOFAI_HOME/custom-agents`（未設定の場合は `~/.failproofai/custom-agents`）が存在することを確認してください。 + デーモンが起動・接続されていることを確認してください。SDK はデーモンの有無にかかわらずスプールします。スプールディレクトリはあらかじめ存在している必要は**ありません**（ライターが作成します）。環境変数によるスプール先の選択はできません。`$FAILPROOFAI_HOME/custom-agents`、なければ `~/.failproofai/custom-agents` が唯一のルートであり、`configure(base_dir=...)` が唯一のオーバーライド手段です。プロセスが `SIGKILL` または OOM キルされた場合、キュー内に残っていたものは失われます。これを防ぐには `SIGTERM` を処理してください。 - **Admin → enforcement** を開き、マシンを選択して、割り当て済みバージョン、報告済みバージョン、および以前のバージョンを比較します。デプロイメントスコープにそのマシンが含まれており、キーに `policies:pull` 権限があることを確認してください。ポリシーの配信が機能していない場合でも、インジェストは動作することがあります。 + **Admin → enforcement** を開き、マシンを選択して、割り当て済み・報告済み・以前のバージョンを比較します。デプロイメントスコープにそのマシンが含まれており、キーが `policies:pull` を持っていることを確認します。ポリシーの配信が機能していない場合でも、インジェストは正常に動作することがあります。 @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - マシン ID とラベルがダッシュボードのターゲットと一致していることを確認してください。既存の認証情報がイベントインジェストのみを許可している場合は、ポリシー対応のキーで再接続してください。 + マシン ID とラベルがダッシュボードのターゲットと一致していることを確認します。既存のクレデンシャルがイベントインジェストのみを許可している場合は、ポリシー対応キーで再接続してください。 - **Admin → enforcement** を開き、マシンの最終確認時刻と報告済みバージョンを確認します。マシンが古い状態の場合は、ローカルデーモンの問題として扱ってください。デーモンが利用できないことを回避するためだけに、デプロイ済みポリシーを弱めないでください。 + **Admin → enforcement** を開き、マシンの最終確認日時と報告されたバージョンを確認します。マシンが古い状態の場合は、ローカルデーモンの問題として対処してください。デーモンが利用できないことを回避するためだけにデプロイ済みポリシーを弱めないでください。 @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - `failproofaid` を再起動または更新し、CLI とデーモンのプロトコルバージョンが異なる場合は設定を再実行してください。設定済みのデーモンパスは、設計上フェイルクローズ（安全側への失敗）します。 + `failproofaid` を再起動または更新し、CLI とデーモンのプロトコルバージョンが異なる場合は設定を再実行してください。設定されたデーモンパスは、設計上フェールクローズ（安全側に倒す）動作をします。 - クラウドで作成されたポリシーの場合は、**Admin → policy editor** を開き、下書きを選択してから公開前に検証エラーを確認します。ローカルポリシーの場合は、CLI を使用して検証し、テストアクション後に **Observe → policy** を開いて決定が届いていることを確認してください。 + クラウドで作成したポリシーの場合は、**Admin → policy editor** を開き、ドラフトを選択して、公開前にバリデーションエラーを確認します。ローカルポリシーの場合は、CLI でバリデーションを行い、テストアクション後に **Observe → policy** を開いて、判断結果が届いているか確認します。 - ファイル名が `policies.js`、`policies.mjs`、または `policies.ts` で終わっていること、モジュールが `customPolicies.add(...)` を呼び出していること、そしてポリシーファイルからのインポートが解決されることを確認してください。 + ファイル名が `policies.js`、`policies.mjs`、または `policies.ts` で終わっていること、モジュールが `customPolicies.add(...)` を呼び出していること、ポリシーファイルからインポートが解決できることを確認します。 ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -91,14 +91,14 @@ icon: "wrench" - + - **Analyze → audits** を開き、実行を選択して、モデル分析が実行されたかどうかを確認します。次に、そのスコープとウィンドウを **Observe → sessions** と比較し、その母集団から代表的なトレースを開きます。 + **Analyze → audits** を開き、実行を選択して、モデル分析が実行されたかどうかを確認します。次に、スコープとウィンドウを **Observe → sessions** と比較し、その母集団から代表的なトレースを開きます。 - ゼロ結果が意味を持つのは、分析が正常に実行された場合のみです。分析がスキップまたは失敗した場合、実行は結果を生成せず、未分析のウィンドウを将来の正常な実行のために開いたままにします。モデル分析が無効になっている場合、決定論的な認証情報と PII スキャンは統計を記録しますが、もはや結果を生成しないため、監査でも結果は生成されません。 + ゼロ件の結果が意味を持つのは、分析が正常に実行された場合のみです。分析がスキップまたは失敗した場合、実行は検出結果を生成せず、未分析のウィンドウを将来の正常な実行に向けて開いたままにします。モデル分析が無効になっている場合も、統計は記録されますが検出結果は生成されないため、監査の検出結果はゼロになります。 - ![環境、エージェント、ケイデンス、スイープウィンドウでセッション母集団を定義する監査フォーム。](/images/dashboard/audit-new.png) + ![環境、エージェント、頻度、スイープウィンドウによってセッション母集団を定義する監査フォーム。](/images/dashboard/audit-new.png) ```bash @@ -110,31 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - 実行がキューに残っている場合は、監査エージェントの容量を待つか、デプロイメントオペレーターに監査フリートの調査を依頼してください。キューに入った監査は再試行されます。即座にスキップされることはありません。 + 実行がキューに留まっている場合は、監査エージェントのキャパシティが空くのを待つか、デプロイメントオペレーターに監査フリートの確認を依頼してください。キューに入った監査はリトライされます。即座にスキップされることはありません。 - 完了済みのセッションを開き、手動評価が成功するかどうかを確認します。ホステッドクラウドでは現在、ダッシュボードに評価エンドポイントのコントロールはありません。サーバーオペレーターが設定する必要があります。 + 完了したセッションを開き、手動評価が成功するか確認します。ホスト型クラウドでは、現在ダッシュボード上での評価エンドポイント制御はサポートされていません。サーバーオペレーターが設定する必要があります。 - 評価エバリュエーター自体を確認し、最近の評価状態を調査します： + 評価エンドポイント自体を確認し、最近の評価状態を確認します。 ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - セルフホスト型クラウドの場合は、サーバー上に `EVALUATOR_ENDPOINT` が存在し、`EVALUATOR_TOKEN` が評価エバリュエーターと一致していることを確認してください。エンドポイントが存在しない場合、自動評価は無効になります。 + セルフホスト型クラウドでは、サーバーに `EVALUATOR_ENDPOINT` が設定されており、`EVALUATOR_TOKEN` が評価エンドポイントと一致していることを確認します。エンドポイントが存在しない場合、自動評価は無効になります。 - + - organizationスイッチャーを使用し、CLI との結果比較を行う前に、期待されるスラッグと権限を確認してください。 + 組織スイッチャーを使用し、CLI と結果を比較する前に、想定されるスラッグと権限を確認します。 ```bash @@ -143,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - API キーモードでは、`fp --org --api-key ...` を指定するか、`AGENTEYE_ORG` を設定してください。保存された人間セッションのorganization状態は、API キーリクエストでは意図的に無視されます。 + API キーモードでは、`fp --org --api-key ...` を指定するか、`AGENTEYE_ORG` を設定します。保存された人間セッションの組織状態は、API キーリクエストでは意図的に無視されます。 - **Observe → policy** を開き、決定とリンクされたセッションを保存して、誤検知の条件を特定します。次に **Admin → enforcement** を開き、影響を受けたマシンを以前のバージョンにロールバックします。**Policy editor** でより狭いバージョンを作成し、小さなスコープでテストを行い、正当な作業が成功した後にのみ拡大してください。 + **Observe → policy** を開き、判断結果とリンクされたセッションを保存し、誤検知の条件を特定します。次に **Admin → enforcement** を開き、影響を受けたマシンを以前のバージョンにロールバックします。**Policy editor** でより絞り込んだバージョンを作成し、小さなスコープでテストして、正当な作業が成功した場合のみスコープを拡大してください。 - クラウドデプロイメントのロールバックはダッシュボードからのみ実施できます。ローカルセッションの一時停止では、クラウド管理のポリシーは無効になりません。ダッシュボードが利用できない場合は、マシンとデプロイメントの状態をキャプチャし、ブロックされたアクションを繰り返し再試行するのではなく、ダッシュボードへのアクセスを復元してください。 + クラウドデプロイメントのロールバックはダッシュボードからのみ可能です。ローカルセッションの一時停止では、クラウド管理のポリシーは無効になりません。ダッシュボードが利用できない場合は、マシンとデプロイメントの状態を記録し、ブロックされたアクションを繰り返し再試行するのではなく、ダッシュボードへのアクセスを復元してください。 ```bash failproofai config --status @@ -164,4 +164,4 @@ icon: "wrench" -サポートへの問い合わせ時は、CLI バージョン、ハーネス、環境、関連するセッションまたはデプロイメント ID、およびシークレットを除去した `failproofai config --status` の出力を含めてください。 \ No newline at end of file +サポートに連絡する際は、CLI バージョン、ハーネス、環境、関連するセッションまたはデプロイメント ID、およびシークレットを除いた `failproofai config --status` の出力を含めてください。 \ No newline at end of file diff --git a/docs/ja/sessions/live-events.mdx b/docs/ja/sessions/live-events.mdx index b74e4edcd..80609d83d 100644 --- a/docs/ja/sessions/live-events.mdx +++ b/docs/ja/sessions/live-events.mdx @@ -4,18 +4,18 @@ description: "セッション実行中にエージェントのアクティビテ icon: "radio" --- -ライブイベントを使用すると、インストルメンテーションの確認や、リスクのある実行をセッション終了を待たずに監視できます。 +ライブイベントを使うと、インストルメンテーションの動作確認や、リスクの高い実行をセッション完了を待たずに監視できます。 ## アクティビティの監視 1. **Observe → Events** に移動します。 - 2. 現在の時間ウィンドウでフィルターなしから始め、データが届いていることを確認します。 - 3. 環境、イベントタイプ、エージェント、またはセッションでフィルタリングします。ペイロードテキストの検索にはサーチを使用してください。 - 4. イベントを選択して概要と詳細を確認します。セッションリンクをたどると完全なトレースが表示されます。 + 2. まず現在の時間ウィンドウでフィルターなしの状態から始め、データが届いていることを確認します。 + 3. 環境、イベントタイプ、エージェント、またはセッションでフィルタリングします。ペイロードのテキスト検索も利用できます。 + 4. イベントを選択すると、サマリーと詳細を確認できます。セッションリンクをたどると全トレースが表示されます。 - ![Hermes チャットゲートウェイのトラフィックとコーディング CLI の実行をリアルタイムで表示するイベントストリーム。時間、環境、イベントタイプ、エージェント、モデル、コンテキスト、セッションでフィルタリング可能。](/images/dashboard/events-stream-current.png) + ![Hermes チャットゲートウェイとコーディング CLI 実行からのトラフィックを表示するライブイベントストリーム。時間、環境、イベントタイプ、エージェント、モデル、コンテキスト、セッションでフィルタリングされています。](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +24,22 @@ icon: "radio" fp --json events --full --session-id --all ``` - デフォルトのフィードでは生のペイロードは省略されます。`--full` は範囲を限定したセッション調査のみに使用してください。 + デフォルトのフィードでは生のペイロードは省略されます。`--full` は範囲が限定されたセッションの調査時のみ使用してください。 -イベントストリームを使用して、次の3つの即時的な疑問に答えられます。 +イベントストリームを使って、次の3つの疑問にすぐ答えられます。 -- 期待されるエージェントが正しい環境に報告しているか？ -- モデル呼び出し、ツール呼び出し、ポリシー決定が順番に届いているか？ -- セッションが進行を停止したり、同じアクションを繰り返し始めていないか？ +- 期待するエージェントが正しい環境に報告しているか？ +- モデル呼び出し、ツール呼び出し、ポリシー判定が順番に届いているか？ +- セッションが進行を停止したり、同じアクションを繰り返したりしていないか？ -イベントタイプには、エージェントのライフサイクルイベント、モデルのリクエストとレスポンス、ツールの使用と結果、フックの実行、ヒューマンウェイトと割り込み、明示的なエラーが含まれます。ツール呼び出しとその結果などのペアイベントは相関IDで紐付けられます。 +イベントタイプには、エージェントライフサイクルイベント、モデルのリクエストとレスポンス、ツールの使用と結果、フック実行、ヒューマンウェイトと割り込み、明示的なエラーが含まれます。ツール呼び出しとその結果など、対になるイベントはコリレーション ID で紐付けられます。 - 新しいインテグレーションを検証する際は、ライブビューを広い範囲で表示したままにしてください。最初のイベントを確認してからフィルターを追加してください。誤ったフィルターはインジェスションの失敗と見分けがつかないことがあります。 + 新しいインテグレーションを確認する際は、ライブビューを広い範囲で表示したままにしてください。最初のイベントを確認してからフィルターを追加しましょう。誤ったフィルターを設定すると、インジェストに失敗しているように見えてしまいます。 -イベントが表示されない場合は、`failproofai config --status` を実行してから、[インジェスションのトラブルシューティング](/ja/reference/troubleshooting)を参照してください。 +イベントが表示されない場合は、`failproofai config --status` を実行してから、[インジェストのトラブルシューティング](/ja/reference/troubleshooting)を参照してください。 -サポートされている12種類の[ハーネス](/ja/reference/harnesses)のいずれかで実行されないエージェントも、[Python SDK](/ja/reference/custom-agents) を通じて同じイベントタイプを報告します。ゲートウェイや本番エージェントが依存するヒューマン・イン・ザ・ループイベント（`human_wait`、`human_input`、`human_interrupt`）も含まれます。 \ No newline at end of file +サポートされている12種類の[ハーネス](/ja/reference/harnesses)のいずれかで実行されないエージェントも、[Python SDK](/ja/reference/custom-agents) を通じて同じイベントタイプを報告します。ゲートウェイや本番環境のエージェントが依存するヒューマンインザループイベント（`human_wait`、`human_input`、`human_interrupt`）も含まれます。 \ No newline at end of file diff --git a/docs/ja/start/first-policy.mdx b/docs/ja/start/first-policy.mdx index f18503191..4db2f7206 100644 --- a/docs/ja/start/first-policy.mdx +++ b/docs/ja/start/first-policy.mdx @@ -1,33 +1,33 @@ --- title: "ポリシーで最初の失敗を防ぐ" -description: "ポリシーのバージョンを作成し、オブザーブモードでデプロイしてから適用します。" +description: "ポリシーのバージョンを作成し、オブザーブモードでデプロイして、その後強制適用します。" icon: "shield-check" --- -安全でないアクションと、引き続き許可すべき正当なアクションを明確に説明できるようになってからポリシーを使用してください。 +ポリシーを使用するのは、安全でないアクションと、引き続き許可すべき正当なアクションを明確に説明できるようになってからにしてください。 - **Admin → policy editor** に移動します。デモポリシーから始め、ソースを確認または編集してから、**publish version** を選択します。公開すると、マシンにデプロイできる不変のバージョンが作成されます。 + **Admin → policy editor** に移動します。デモポリシーから始め、ソースを確認または編集して、**publish version** を選択します。公開すると、マシンにデプロイできるイミュータブルなバージョンが作成されます。 - ![公開済みの不変バージョンとしてデモポリシーが準備されたポリシーエディタの作成ビュー。](/images/dashboard/policy-editor.png) + ![デモポリシーがイミュータブルなバージョンとして公開される準備が整ったポリシーエディターの作成ビュー。](/images/dashboard/policy-editor.png) - **Admin → enforcement** に移動し、対象マシンを展開して **edit this machine** を選択します。公開済みのデモポリシーを追加し、バージョンを固定して **observe** を選択し、デプロイを適用します。 + **Admin → enforcement** に移動し、対象のマシンを展開して **edit this machine** を選択します。公開済みのデモポリシーを追加し、バージョンをピン留めして、**observe** を選択し、デプロイメントを適用します。 - ![デプロイを適用する前に、オブザーブモードで公開済みポリシーバージョンが選択されたマシンデプロイメントエディタ。](/images/dashboard/enforcement-editor.png) + ![デプロイメントを適用する前に、オブザーブモードで公開済みポリシーバージョンが選択されたマシンデプロイメントエディター。](/images/dashboard/enforcement-editor.png) - - そのマシンで新しいエージェントセッションを実行し、**Observe → policy** を開きます。マシンを選択し、デモポリシーがポリシーマッピングと決定タイムラインに表示されることを確認します。オブザーブモードでは、アクションをブロックせずにポリシーが行う処理を記録します。 + + そのマシンで新しいエージェントセッションを実行し、**Observe → policy** を開きます。マシンを選択し、デモポリシーがポリシーマッピングと決定タイムラインに表示されることを確認します。オブザーブモードでは、アクションをブロックせずにポリシーが行う動作を記録します。 - ![決定の合計数、経時的な適用アクティビティ、ローカルおよびクラウド管理のポリシーマッピングを表示するポリシーページ。](/images/dashboard/policy-observe.png) + ![決定の集計、時系列の強制適用アクティビティ、ローカルおよびクラウド管理のポリシーマッピングを表示するポリシーページ。](/images/dashboard/policy-observe.png) - クラウドのポリシー作成とフリートデプロイメントは管理者向けのワークフローです。公開前に同じポリシーを検証するには、ローカル CLI を使用してください： + クラウドでのポリシー作成とフリートへのデプロイは管理者向けのワークフローです。公開前に同じポリシーをローカルの CLI で検証するには、以下を使用します。 ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -35,13 +35,13 @@ icon: "shield-check" failproofai config --status ``` - クラウドで確認できるポリシーの決定を検査するには `fp` を使用してください： + クラウドから参照できるポリシーの決定を確認するには `fp` を使用します。 ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - クラウド CLI はルート専用の適用デプロイメントルートを公開していません。**Admin → policy editor** からバージョンを公開し、**Admin → enforcement** からデプロイしてください。 + どちらのステップも CLI から実行できます。`fp policies publish ` でバージョンを発行し、`fp fleet deploy --add ` でマシンに適用します。ダッシュボードでの対応操作はそれぞれ **Admin → policy editor** と **Admin → enforcement** です。 \ No newline at end of file diff --git a/docs/ja/start/integrations.mdx b/docs/ja/start/integrations.mdx new file mode 100644 index 000000000..8c3d15e6a --- /dev/null +++ b/docs/ja/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "エージェントをインストルメント化する" +sidebarTitle: "フレームワーク" +description: "サポートされている任意のエージェントフレームワークを、1回の呼び出しで Failproof AI に接続します。" +icon: "plug" +--- + +あなたのエージェントはすでに記録すべきすべてのデータを生成しています — モデル呼び出し、ツール呼び出し、ノードの境界、人間の待機、失敗。フレームワークはそれを捨ててしまいます。SDKはそれを保持します。 + + + + 自分で書いたエージェント、またはここに記載されていないエージェント。 + + + グラフ、ノード、ツール、リトリーバー、モデル。 + + + クルー、フロー、役割別エージェント、ツール。 + + + ワークフロー、ステップ、ファンクションエージェント、リトリーバー。 + + + 型付きエージェント、ケイパビリティ、ツール、リトライ。 + + + +## どのフレームワークでも3行で + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # インポートしたフレームワークを自動検出 + +with failproofai_sdk.session(): + ... # 既存のエージェント呼び出し、変更不要 +``` + +関数へのデコレーター不要、呼び出しへのコールバック渡し不要、コード全体へのID受け渡し不要。変わるのはセッション内の呼び出しだけです： + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # `async with failproofai_sdk.session():` の下で + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +追加インストールは**フレームワーク**をインストールします。すべてのアダプターはベースホイールに同梱されているため、すでにフレームワークを持つプロジェクトは追加インストールが不要です。 + +## 到達確認 + +インストルメント化したセッションを1回実行し、**Observe → Sessions** を開いて環境を選択します。実行結果が再構成されたトレースとして表示されます。 + +何も届かない場合は、`failproofai config --status` でマシンの接続を確認してください。[キャプチャのセットアップ](/ja/start/setup) を参照してください。 + + + 配信確認のためにスプールディレクトリを確認しないでください。Failproof デーモンは各バッチをミリ秒以内に収集・削除するため、ディレクトリを読み取るとコレクターと競合し、実際に送出されたイベントよりはるかに少ないイベントしか表示されません。 + + +## 次のステップ + +上記の各クイックスタートはフルガイドへのリンクです — 記録される内容、オプション、ストリーミング、スパン名、実際によく起きる問題について説明しています。これらは **Trace Agents → Plug in your agent** の下にあります。 + + + + データモデル、ID、イベントタイプ、そしてイベントがクラウドに到達する仕組み。 + + + 切り離されたログではなく、セッション全体の因果関係を追う。 + + + キャプチャしたセッションを監査する。 + + \ No newline at end of file diff --git a/docs/ja/start/integrations/crewai.mdx b/docs/ja/start/integrations/crewai.mdx new file mode 100644 index 000000000..46ec7b01e --- /dev/null +++ b/docs/ja/start/integrations/crewai.mdx @@ -0,0 +1,224 @@ +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "クルー、フロー、エージェントをロール、ツール、メモリ、人間フィードバックで計装します。" +icon: "/images/frameworks/crewai.svg" +--- + +## インストール + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +対応バージョン: `crewai` 1.13 〜 2.0。1.13 は `started_event_id` の追加とトークン使用量の正規化が行われたリリースであり、アダプターはイベントの対応付けとトークンレポートにこれらを利用しています。 + +## 計装 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` は CrewAI のモジュールレベルのイベントバスにリスナーを登録し、イベントクラスごとに 1 つのハンドラーを購読します。クルー、エージェント、タスク、ツールには一切変更が加わりません。 + +## 記録される内容 + +| CrewAI | Failproof イベント | +| --- | --- | +| クルーのキックオフ | `agent_start`、`agent_end` | +| `Agent.kickoff()`（ライトエージェント、クルーなし） | `agent_start`、`agent_end`（`agent_id` はロールから取得） | +| フローの開始と終了 | `agent_start`、`agent_end`；フローメソッド内でキックオフされたクルーはその配下にネストされる | +| エージェントの実行 | ネストされた `agent_start`、`agent_end`（`agent_id` はロールから取得）。階層型プロセスでは委任されたコワーカーはマネージャーの配下にネストされ、並列にはならない | +| タスク | なし；リンクとして記録され、子要素がクルーに解決される | +| フローメソッド、ガードレール | `hook_triggered`、`hook_completed` | +| ツールの使用 | `tool_use`、`tool_result` | +| メモリおよびナレッジ操作 | `tool_use`、`tool_result`（アクセスしたサーフェスの名前が付く） | +| LLM 呼び出し | `model_request`、`model_response`（トークン使用量付き） | +| ストリームチャンク | レスポンスにチャンク数と最初のトークンまでの時間として折り込まれる | +| 人間フィードバックのリクエスト | `human_wait`、`agent_pause` | +| 人間フィードバックの受信 | `agent_resume`、`human_input` | +| エージェント実行エラー | `error`、続いて結果 `failed` の `agent_end` | + +タスクが意図的に何も発行しないのには理由があります。CrewAI のタスクはそれを実行するエージェント実行のサブセットであるため、両方を発行すると全行が二重になり、兄弟として表示されてしまいます。タスクの id と名前は、エージェント自身のイベントに付随します。 + +メモリおよびナレッジ操作はツールとして記録され、アクセスしたサーフェスの名前が付くため、実際のツールの隣に並んでレイテンシを比較できます。 + +階層型クルーでは、ネスト構造によってトレースが読みやすくなります: + +```text +crew +└─ manager + ├─ researcher 委任 + └─ writer 委任 +``` + +CrewAI は委任された実行を、マネージャー直下ではなく `delegate_work_to_coworker` **ツールイベント** の配下に親付けするため、アダプターもそのリンクに従います。これがないと、すべてのエージェントが並列になり委任の構造が失われます。 + +## 使用例 + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # becomes agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +引き継ぎはトレースで確認できます: `analyst` スパンが閉じ、`writer` スパンが開き、両方が 1 つの `crew` スパンの内側に収まります。 + +## スパンに名前を付ける + +`agent_id` は `Agent(role=...)` から取得されるため、ダッシュボードのファセットとして読みやすくなります。 + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # 実行ごとに別ファセットエントリが作成される +``` + +`agent_id` は低カーディナリティのカラムです。実行 id やタイムスタンプを含むロールは、あらゆるクエリのパフォーマンスを低下させます。ロールが id のように見える場合、アダプターはそれを拒否し、実際の値をペイロードフィールドに格納します。 + +## セッションを制御する + +以下の順序で解決され、最初に一致したものが使用されます: + +1. `instrument("crewai", session_id=...)` +2. 囲んでいる `failproofai_sdk.session()` スコープ +3. クルーまたはフローごとに 1 回生成される `uuid4().hex` + +実行ごとに制御するには、キックオフをラップします: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## オプション + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # すべての実行を 1 つのセッション id に固定する +) +``` + +`session_id` はこのアダプターが読み取る唯一のオプションです。プロンプトとコンプリーションは常に記録され、ペイロード予算内でトランケートされます。 + +## ヒューマン・イン・ザ・ループ + +CrewAI には **2 つ** のヒューマン・イン・ザ・ループのサーフェスがあり、どちらも同じ 4 つのイベントとして記録されます。 + +フローメソッド上の `@human_feedback` は CrewAI のイベントバスを経由します: ランタイムは人間の応答待ちに入る前にイベントを発行し、回答後にもう 1 つのイベントを発行します。 + +`Task(human_input=True)` はそうではありません。CrewAI 自身の入力プロバイダー内で `input()` を呼び出し、いかなるイベントも発行しないため、アダプターはそのプロバイダーを直接ラップします。これがないと、人間の待機時間が完全に不可視となり、アクティブなエージェント時間として計上されます。 + +どちらの場合も次のイベントが記録されます: + +```text +human_wait プロンプトとその選択肢 +agent_pause 一時停止時間のクロックを開始 +agent_resume 一時停止時間のクロックを停止 +human_input 回答（待機時間の計測付き） +``` + +`agent_pause` から `agent_resume` の間だけが一時停止時間としてカウントされます。これがないと、10 分間の人間待機が 10 分間のアクティブなエージェント時間として計上されます。 + + + CrewAI はどちらの人間フィードバックイベントにも相関 id を設定しないため、アダプターはフローとメソッド名を基にペアリングし、直近に開かれた一時停止にフォールバックします。コンソールプロンプトはブロッキングであるため、この方法は健全です。並行フィードバックプロバイダーを構築する場合は、両方のイベントに `request_id` を設定してください。 + + + + `Task(human_input=True)` のパスはイベント購読ではなく CrewAI の入力プロバイダーへのラッパーであるため、`uninstrument()` 時に元に戻され、`input()` が送出した例外（`KeyboardInterrupt` を含む）はそのまま再送出されます。 + + +## よくある問題 + + + + `role` に UUID、タイムスタンプ、または実行ごとのサフィックスが含まれています。安定した人間可読のロールを使用し、実行固有の id はタスクの説明に入れるようにしてください。 + + + + イベントバスは非同期であり、`kickoff()` は最後のハンドラーが実行される前に返ります。先にドレインしてください: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + これは CrewAI の特性であり、SDK の問題ではありません。 + + + + `agent_end` は開いている一時停止を強制終了しますが、ツールやモデルは終了しません。そのため、ツール呼び出しの途中で実行が終了すると、そのスパンが開いたままになります。通常のティアダウンでは、まだ開いているものをすべて閉じて未完了としてマークします。`SIGKILL` の場合のみ、何も実行できないため開いたままになります。 + + + + 以下の順で確認してください: `instrument()` が `kickoff()` の前に実行されているか；`with failproofai_sdk.session():` で囲まれているか；`crewai` が 1.13 以降か；`FAILPROOFAI_SDK_STRICT=1` が設定されている場合、劣化したフックは握りつぶされずに例外を送出します。 + + + +## 次のステップ + + + + ペア、id、セッションライフサイクル、デリバリーについて。 + + + キャプチャしたセッションの因果関係を追う。 + + + LangGraph、LlamaIndex、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 new file mode 100644 index 000000000..38782e56a --- /dev/null +++ b/docs/ja/start/integrations/custom-agents.mdx @@ -0,0 +1,737 @@ +--- +title: "カスタムエージェント" +sidebarTitle: "カスタムエージェント" +description: "自作のエージェント、またはアダプターのないフレームワークにインストルメンテーションを追加する。" +icon: "code" +--- + +自作のエージェント、またはFailproof AIがアダプターを提供していないフレームワーク向けの説明です。インストルメンテーションの設定は不要です。イベントを自分で送出するだけです。 + +これは、4つのフレームワークアダプターが内部で呼び出しているのと同じAPIです。それらのアダプターは、このAPIの変換テーブルにすぎません。 + +## インストール + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # 1回のツール呼び出し +``` + +上から読んでいくと、その意味がそのまま伝わります： + +| ラップする対象 | 意味 | +| --- | --- | +| `session()` | これらのイベントは同じ実行に属する | +| `agent()` | 何かが作業をしている — リストで認識できる名前を付ける | +| `tool_call()` | これは1つのツールであり、その返り値がここにある | + +各スコープが実際に送出するイベント： + +| スコープ | 送出するイベント | 目的 | +| --- | --- | --- | +| `session()` | なし | セッションIDをバインドし、1回の実行をグループ化する | +| `agent()` | `agent_start`、`agent_end` | 作業単位の前後を囲む | +| `tool_call()` | `tool_use`、`tool_result` | 1つのツールを囲み、計測する | + +スコープ内のコードは `session_id` や `agent_id` を省略できます。スコープはコンテキスト変数にIDをバインドし、すべてのイベント呼び出しがそこから読み取るため、関数にIDを引き回す必要はありません。 + +3つのスコープはいずれも `async with` と `with` の両方で動作します。 + +エージェントをネストするとツリーが構築されます。`parent_id` と深さはスタックから自動計算されます： + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## スコープの終了方法 + +`agent()` は例外を自動で処理します： + +| 発生したこと | イベント | 結果 | +| --- | --- | --- | +| 例外なし | `agent_end` | `success` | +| `Exception` | `error`、次に `agent_end` | `failed` | +| `KeyboardInterrupt`、`SystemExit` | `error`、次に `agent_end` | `failed` | +| `CancelledError`、`GeneratorExit` | `agent_end` のみ | `cancelled` | + +エラーは `agent_end` の前に送出されます。これはダッシュボードが `agent_end` でスパンを閉じるため、それ以降に発生したイベントはどのスパンにも帰属しなくなるためです。キャンセルは失敗ではないため、キャンセルされた実行はエラーサーフェスを汚染しません。例外は常に再送出されます。スコープが例外を握りつぶすことはありません。 + +## イベントメソッド + +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` | +| **失敗** | — | — | `error` | + + + 可能な限りスコープ — `agent()` と `tool_call()` — を優先してください。本体が例外を送出した場合でも、クローズイベントの送出を保証します。制御フローがネストされない場合（ヘルパー内のモデル呼び出しなど）は、これらのメソッドを直接使用してください。 + + + +```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 Models +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 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 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 Failures +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **2つの人間ファミリーは方向が逆です。** + + | メソッド | 意味 | + | --- | --- | + | `human_wait` / `human_input` | **エージェントが人間に問いかけた** — 承認ゲート、確認のための質問 | + | `human_pause` / `human_interrupt` | **人間がエージェントに働きかけた** — 停止ボタン、オペレーターによる一時停止 | + + どのフレームワークも後者のペアを通知しないため、常に自分で送出する必要があります。 + + + + **モデル呼び出しを並行実行する場合は `request_id` を渡してください。** 指定しない場合、リクエストとレスポンスはエージェントごとの受信順にペアリングされます。並行呼び出しでは順序が保証されないため、各レスポンスが誤ったリクエストに紐付く可能性があります。 + + +## 使用例 + +エージェントフレームワークなしで、OpenAI APIに対してツール呼び出しループを実行する例： + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +MODEL = "gpt-4o-mini" + + +def turn(messages: list): + """1回のモデル呼び出し。ペアで囲む。""" + failproofai_sdk.event.model_request(model=MODEL, messages=messages) + reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) + usage = reply.usage + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="price report"): + for _ in range(4): # 上限あり。無制限のエージェントループはそれ自体がバグ + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +これにより、アダプターが生成するのと同じ6種類のイベントタイプが生成されます。ツール定義を含む完全な実行可能バージョンは、SDKリポジトリの `docs/manual/examples/` に含まれています。 + +## スレッドと非同期 + +コンテキスト変数はasyncioタスクに自動的に伝播します。新しいスレッドには伝播しません。スレッドは空のコンテキストで開始されるためです。 + +```python +# asyncio: 特別な操作不要 +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# スレッド: 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レイヤーが存在します。 + +## アダプターのないフレームワークへのインストルメンテーション + +どのエージェントフレームワークにも同じ3つの接合点があります。それらをマッピングすれば、完全なトレースが得られます — 4つの既存アダプターもこれ以上のことはしていません。 + +| 接合点 | 書くコード | 記録されるイベント | +| --- | --- | --- | +| 実行 | `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: + call.output = original(**args) + ``` + + + ```python + failproofai_sdk.event.model_request(model=model, messages=messages) + reply = provider.complete(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **ノード、ステップ、ミドルウェア境界を可視化したい場合は？** ネストされた `agent()` ではなく、フックペア — `hook_triggered` / `hook_completed` — でラップしてください。`agent_id` は低カーディナリティのファセットであり、ノードごとに1エントリ追加するとすぐに埋め尽くされます。フックスパンは同様にレンダリングされ、ノードごとのレイテンシを確認できます。 + + + + **手動計装と自動計装は組み合わせ可能です。** 手書きスコープ内で実行されるアダプターは、そのセッションに参加し、そのエージェントを親として設定します。2つのツリーではなく1つのツリーが得られるため、対応フレームワークと独自フレームワークを同時に計装する際に便利です。 + + + + 2つの理由があります。上記の3つの接合点が、その両方に対する答えです： + + - `autogen-core` は2025年9月以降メンテナンスされていません。 + - AG2には他のフレームワークのフックに相当するプロセス全体の登録ポイントがないため、計装するにはすべての構築箇所でエージェントをラップする必要があります。 + + 接合点を手動でマッピングすることで、既存アダプターと同じイベントが同じ精度で記録されます。 + + +## 詳細 + +記録の実際の仕組みについて。始めるために必要な知識ではありません。 + + + + + +すべての記録は同じ形をしています。スパンが開き、その中に作業がネストされ、各オープンイベントに対応するクローズイベントがあります。 + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + C --> E(["agent_end"]) +``` + +**ペア**が基本単位です。各クローズイベントには、SDKがオープンイベントからの経過時間として計測したdurationが含まれます。 + +以下は各フレームワークの実際の1回の実行 — SDKに同梱されているサンプルから取得、モデル名は正規化済み。1回の呼び出しでどれだけ多くの情報が返されるかに注目してください。 + + + + ```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 out-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 14 +5.721s agent_end LangGraph · success + ``` + + ノードがフックペアになるため、エージェントリストを埋め尽くすことなくノードごとのレイテンシを確認できます。 + + + + ```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 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 out-tok + 9 +5.727s agent_end analyst · success + 10 +5.739s agent_end crew · success + ``` + + 各エージェントの `role` がスパン名になるため、レイテンシとトークン消費をロールごとに分析できます。 + + + + ```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 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 + ... 2回目のイテレーション + 26 +7.038s agent_end Agent · success + ``` + + エージェントループ自体が可視化され、モデル呼び出しだけでなくループ全体が見えます。 + + + + ```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 + 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 + 8 +8.119s agent_end agent · success + ``` + + フックペアなし: Pydantic AIにはブラケットで囲むべきノードやステップ境界がありません。 + + + + ```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 out-tok + 6 +0.000s agent_end main · success + ``` + + これらを自分で送出します。同じイベントタイプ、同じ精度 — 呼び出し箇所を書くコストがかかります。 + + + + + + + +**セッション終了イベントは存在しません。** セッションは閉じるものではなく、同じ `session_id` を共有するイベントのグループです。 + +ステータスはトレースの形状から導出されます： + +| ステータス | 条件 | +| --- | --- | +| `ongoing` | 少なくとも1つのスパンがまだ開いている | +| `paused` | `agent_pause` に対応する `agent_resume` がない | +| `error` | 開いているスパンがなく、少なくとも1つのイベントが失敗した | +| `done` | 開いているスパンがなく、失敗もない | + +つまり、すべてのペアが閉じられるとセッションが終了します。アダプターは `agent_end` を自動送出し、テアダウン時にはまだ開いているものをすべて閉じてincompleteとしてマークします — クラッシュした実行は永遠にハングするのではなく、visible gapを持つ `done` として落ち着きます。 + + + これが、1つのセッションが2回の呼び出しにまたがれる理由です。LangGraphの `interrupt()` は実行を一時停止し、ルートスパンを意図的に開いたままにします。再開する呼び出しがそれを閉じます。両方の呼び出しが1つのセッションです。 + + + + + + +`session_id` と `agent_id` はすべてのイベントメソッドでオプションです。省略した場合、囲んでいるスコープから解決されます： + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") +``` + +明示的に渡すことも可能で、その場合は優先されます。何もバインドされておらず何も渡されない場合、セッションなしでイベントを送出する代わりに、修正方法を示す `TypeError` が発生します（インジェストはセッションなしのイベントをスキップしつつ `200` を返します）。 + +スコープはコンテキスト変数にIDをバインドします。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** | **Cloud（インジェスト時）** | SDKは送出しない | +| **`dedup_key`** | **Cloud（インジェスト時）** | org、session、timestamp、type、payloadのハッシュ。これが実際のID — 再試行されたバッチが重複する代わりに折りたたまれる | + +#### アダプターが `session_id` を解決する方法 + +最初のマッチが優先されます： + +1. 明示的な `session_id` オプション +2. 呼び出しごとのメタデータ +3. 囲んでいる `session()` スコープ +4. フレームワークのメタデータ +5. フレームワーク独自の実行ID + +これらのいずれかが存在する間は、IDが新規生成されることはありません — 合成されたIDは1回の実行を複数のセッションに分割してしまうためです。 + +#### `agent_id` は低カーディナリティに保つ + +すべてのダッシュボードサーフェスの主要ファセットであり、`LowCardinality(String)` カラムです。実行ごとの値を使用するとカラムが劣化し、フィルターのドロップダウンが実行1件につき1エントリで埋まります。 + +アダプターはそのカラムを守ります： + +| フレームワークが渡す値 | 記録される値 | 理由 | +| --- | --- | --- | +| `3f9a1c2b-…`（UUID） | `main` | 読める情報がない | +| 長い16進数文字列 | `main` | 同上 | +| `agent-3f9a1c2b-…` | `agent` | 実行IDを削除し、読める部分を保持 | +| `agent-v2` | `agent-v2` | 短いセグメントはそのまま残す | +| `step-3` | `step-3` | 同上 | + +実際のIDは `fw_agent_id` / `fw_run_id` に保持されるため、ファセットにならずともクエリ可能です。 + + + **このガードは*フレームワーク*が選んだラベルにのみ適用されます。** `event.*` や `failproofai_sdk.agent(...)` に自分で渡す `agent_id` は、渡したとおりに記録されます。明示的な引数を暗黙的に書き換えることは、防ごうとするカーディナリティの問題よりも悪いため、スパン名は適切に命名してください。 + + + + + + +| グループ | イベント | +| --- | --- | +| エージェント | `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 | カスタム | +| --- | :--: | :--: | :--: | :--: | :--: | +| エージェント開始・終了 | あり | あり | あり | あり | 自前 | +| モデルリクエスト・レスポンス | あり | あり | あり | あり | 自前 | +| ツール使用・結果 | あり | あり | あり | あり | 自前 | +| フックトリガー・完了 | ノード | タスク | ステップ | — | 自前 | +| エラー | あり | あり | あり | あり | 自動 | +| 人間の待機・入力 | あり | あり | あり | — | 自前 | +| エージェント一時停止・再開 | あり | あり | あり | — | 自前 | + +ダッシュはそのフレームワークにその概念がないことを意味します。`human_pause` と `human_interrupt` は*人間*がエージェントに働きかけることを表しており、どのフレームワークも通知しません — これらは自分で送出してください。 + + + + + +イベントは単独では届きません。1つがスパンを開き、1つが閉じます。クローズイベントには、SDKがオープンイベントからの経過時間として計測したdurationが含まれます。 + +| 開く | 閉じる | クローズイベントが持つ値 | +| --- | --- | --- | +| `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 | +| `agent_pause` | `agent_resume` | 一時停止の継続時間 | +| `human_wait` | `human_input` | 回答、および人間が要した時間 | + + + クローズイベントのないオープンイベントは、永遠に終わらないスパンです。セッションはずっと実行中としてレンダリングされ、アクティブdurationが増え続けます。これは手動で計装する際に注意すべき失敗パターンです。 + + +#### 相関ルール + +- マッチするクロージングイベントには同じ `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エントリを保持し、満杯になると最古のエントリを削除します。 + + + + + +`failproofai-sdk` をインストールすると、4つのアダプターを含むすべてがインストールされます。extrasが引き込むのはアダプターではなく**フレームワーク**です。 + +```python +import failproofai_sdk # 標準ライブラリ以外は何もロードしない +failproofai_sdk.instrument() # 実際に必要なアダプターのみインポートする +``` + +`import failproofai_sdk` は契約上ゼロ依存であり、`--no-deps` でビルド済みwheelをインストールするテストと、どのフレームワークも `sys.modules` に到達しないことを証明するテストによって強制されます。 + + + `failproofai_sdk.crewai` という属性は存在しません。アダプターはトップレベルパッケージに意図的に公開されていません。属性アクセスの副作用としてフレームワークがインポートされ、ゼロ依存の約束が破られるためです。`instrument()` を使用してください。 + + +```python +failproofai_sdk.instrument() # インポート済みのすべてのフレームワーク +failproofai_sdk.instrument("crewai") # 名前で1つだけ指定 +failproofai_sdk.uninstrument("crewai") # 元に戻す +``` + +| 名前 | 別名 | +| --- | --- | +| `langchain` | `langgraph`、`langchain_core` | +| `crewai` | — | +| `llama_index` | `llamaindex`、`llama-index` | +| `pydantic_ai` | `pydantic-ai`、`pydanticai` | + +自動検出はインストール済みパッケージリストではなく `sys.modules` を読み取ります。インストールはしてあるがインポートしていないフレームワークは計装されず、代わりにインポートされることもありません。現在の状態を確認するには： + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +active() # ('langchain',) +``` + + + **CrewAIがインストールされていないマシンで `instrument("crewai")` を呼び出しても例外は発生しません。** 警告をログに記録して `()` を返すため、1つのフレームワークが欠けていても他を計装するプロセスが停止することはありません。 + + 警告には元の `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` を設定してください。このフラグは**一度だけ読み取られてキャッシュされます**。実行中に設定するのではなく、プロセス起動前にエクスポートしてください。 + + + + **`instrument()` はフレームワークのインポートの*後*に呼び出す必要があります。** 自動検出は `sys.modules` を読み取るため、インポートより前に呼び出すと何も見つからず、何もインストールされず、`()` が返されます。 + + + +```python Wrong +import failproofai_sdk +failproofai_sdk.instrument() # sys.modulesにlangchainがまだない -> () + +import langchain # 遅すぎる。何もワイヤリングされない +``` + +```python Right +import langchain # 先にフレームワークをインポート +import failproofai_sdk + +failproofai_sdk.instrument() # 検出される -> ('langchain',) +``` + +```python Right, order-proof +import failproofai_sdk + +# 名前を指定するとアダプターが要求時にインポートされるため、どこからでも動作する +failproofai_sdk.instrument("langchain") +``` + + +これを誤ると、SDKがインポートされアダプターが一見インストールされているのに、**イベントが1件も送出されない**状態になります。ログにその旨の警告が記録されます — 実行が何も記録しない場合、まずログを確認してください。 + + + + + +```mermaid +flowchart LR + A["エージェント"] --> B["アダプター"] + B --> C["Writer
インメモリキュー"] + C -->|"0.5秒ごと"| D["Spool
ディスク上のJSONL"] + D --> E["Failproofデーモン"] + E -->|"HTTPS"| F["Cloud"] +``` + +| ステージ | 役割 | 実行場所 | +| --- | --- | --- | +| アダプター | フレームワークのコールバックを15種類のイベントタイプに変換 | プロセス内 | +| Writer | キューに追加、バッチ化、JSONLをアトミックに書き込む | プロセス内（バックグラウンドスレッド） | +| Spool | 耐久性のある引き渡し。プロセス終了後も保存される | ローカルディスク | +| デーモン | Spoolを監視し、バッチを送信し、送信済みを削除する | マシン上 | +| インジェスト | 行IDとdedup keyを割り当て、クエリ可能なカラムに昇格させる | Cloud | + +Spoolがこれを安全にする理由です。エージェントはネットワークをブロックすることなく動作し、Cloudの障害は消失したイベントではなくディレクトリの増大として現れます。 + +各フラッシュは1つのバッチファイルを書き込みます。`.tmp` で書き始め、次に `fsync`、そしてアトミックリネームを行います： + +```text +~/.failproofai/custom-agents/events/ + event-2026-08-20T10-15-00-123Z-48213-0.jsonl +``` + +デーモンは `.jsonl` のみを読み取るため、書き込み途中のファイルを読むことは決してありません。ファイル名にはタイムスタンプ、プロセスID、シーケンス番号が含まれるため、2つのプロセスが同じミリ秒にフラッシュしても衝突しません。キューの上限は10,000イベントで、それを超えると最古のものを削除してログに記録します。 + + + **`collector.redact` はSDKイベントには適用されません。** SDKイベントは `collector.redact` の処理対象外です。 + + +デーモンはバッチを**送信**します。バッチを開いたり書き換えたりしません。 + +| イベント | 書き込み者 | `collector.redact` による編集 | +| --- | --- | --- | +| CLIセッションのトランスクリプト | デーモン | あり | +| フックのアクティビティ | デーモン | あり | +| **SDKが送出するすべてのイベント** | **プロセス** | **なし** | + +編集はデーモンが自身のイベントを*書き込む*場所で実行されます — バッチが*送信される*場所ではありません。そのため、APIキーを含むプロンプトやツール引数は、到着時もそのままの状態です。 + +これは意図的な設計です。これらはご自身の計装コールであり、送受信中に書き換えることは、送出したイベントと受け取るイベントが異なるものになることを意味します。 + + + **ペイロードはソースの2箇所で制御できます：** + + - アダプターでコンテンツキャプチャを無効にする。**オプション名はアダプターによって異なり、対応していないアダプターもあります** — 共通の単一スイッチではありません： + - LangChain / LangGraph、Pydantic AI — `capture_content=False` + - LlamaIndex — `capture_messages=False` + - CrewAI — **コンテンツスイッチなし**。読み取るオプションは `session_id` のみのため、プロンプトと補完は常に記録されます。 + + `instrument()` はアダプターが読み取らないオプションを無視するため、誤った名前を渡しても何も起きず、何も変わりません。 + - そもそもシークレットを `input=` に渡さない。 + + `collector.redact` はどちらの代替手段にもなりません。 + + + + **Spoolディレクトリが空の状態が正常です。** 配信確認のために使用しないでください。 + + +デーモンは送信後数ミリ秒以内に各バッチを削除するため、`ls` はコレクターと競合し、実際に送出したイベントのごく一部しか表示されません — 何も記録していないSDKと区別がつきません。 + +イベントが実際に届いたかどうかはダッシュボードで確認してください。Spoolが埋まる様子を観察するには、先にデーモンを停止してください。 + + + + + +すべてのコールバックは再送出のみを行うラッパー内で実行されます。コードは1つの `try` の中に置かれ、SDKが行うすべての処理はその外側で実行されます。 + +| 発生したこと | 結果 | +| --- | --- | +| フックが例外を送出した | トレースバック付きで1回ログに記録される。コードは影響を受けない | +| 同じフックが3回例外を送出した | そのフックはプロセスの残り時間中無効化され、1行のエラーログが記録される | +| `FAILPROOFAI_SDK_STRICT=1` が設定されている | 代わりに例外が再送出される | +| フレームワークのバージョンがテスト済み範囲外 | 1回警告が出されるが、計装は続行される | +| 1つの機能が欠けている | そのフックのみ無効化される。アダプター全体は無効化されない | + +デフォルトは本番環境では適切ですが、デバッグ時には不適切です。「クラッシュしなかった」ことしか証明できないためです。隠れた失敗を顕在化させるには `FAILPROOFAI_SDK_STRICT=1` を設定してください。 + + + + + +## よくある問題 + + + + オープンイベントに対応するクローズイベントがありません。`model_request` に `model_response` がない、または `tool_use` に `tool_result` がない状態です。スコープを使用してください。本体が例外を送出した場合でもペアが保証されます。イベントメソッドを直接呼び出す場合は `try` と `finally` を使用してください。 + + + + `tool_result`、`hook_completed`、`agent_resume`、`human_input` では、対応するオープンイベントからの経過時間として計測されるため拒否されます。`model_response` では受け付けられます。実際のプロバイダーレイテンシを知っているのが呼び出し側だけだからです。整数でなければなりません。 + + + + スレッドがコンテキストを継承していません。callableを `failproofai_sdk.propagate()` でラップしてください。[スレッドと非同期](#threads-and-async) を参照してください。 + + + + 追加フィールドは最後にマージされます。`model` や `outcome` など実際のフィールドと同じ名前を使用すると上書きされ、保存されるカラムが変わります。独自フィールドには名前空間を付けてください。アダプターは `fw_` プレフィックスを使用しています。 + + + + `agent_id` は低カーディナリティのファセットですが、実行IDを設定しています。ロール名やノード名を使用し、実際のIDはペイロードフィールドに格納してください。 + + + +## 次のステップ + + + + ペア、ID、セッションのライフサイクル、配信の詳細。 + + + 記録したセッションの因果関係をたどる。 + + + LangGraph、CrewAI、LlamaIndex、Pydantic AI。 + + \ No newline at end of file diff --git a/docs/ja/start/integrations/langchain.mdx b/docs/ja/start/integrations/langchain.mdx new file mode 100644 index 000000000..bc711fc0f --- /dev/null +++ b/docs/ja/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain と LangGraph" +sidebarTitle: "LangChain と LangGraph" +description: "グラフ、ノード、ツール、リトリーバー、モデル呼び出しを1回の呼び出しでインストルメント化します。" +icon: "/images/frameworks/langchain.svg" +--- + +アダプターは両方に対応しています。LangGraph は `langchain-core` のコールバックマネージャー上で動作するため、一方をインストルメント化すればもう一方も自動的にインストルメント化されます。 + +## インストール + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +LangGraph を使わない LangChain のみの場合は `failproofai-sdk[langchain]` を使用してください。 + +対応バージョン: `langchain-core` 1.4.7〜2.0、`langgraph` 1.2〜2.0。この範囲外でもアダプターはインストールされ、一度だけ警告が表示されます。 + +## インストルメント化 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` は `langchain_core.tracers.context.register_configure_hook` を通じてトレーサーを登録します。LangChain はビルドするすべてのコールバックマネージャーにこれを注入するため、グラフ、ツール、モデルは呼び出し箇所を変更することなくキャプチャされます。自分で書いていないライブラリ内部の呼び出しも含まれます。 + +## 記録される内容 + +| LangChain または LangGraph | Failproof イベント | +| --- | --- | +| ルート実行 | `agent_start`、`agent_end` | +| LangGraph ノード | `hook_triggered`、`hook_completed` | +| コンパイル済みサブグラフ | ネストされた `agent_start`、`agent_end` | +| ツール実行 | `tool_use`、`tool_result` | +| リトリーバー実行 | `tool_use`、`tool_result`、出力はサマリー化 | +| チャットモデルまたは LLM 実行 | `model_request`、`model_response`（トークン使用量含む） | +| ストリームトークン | チャンク数と最初のトークンまでの時間としてレスポンスに統合 。トークン数には `ChatOpenAI(stream_usage=True)` が必要 — 以下参照 | +| `interrupt()` | `human_wait`、`agent_pause` | +| `Command(resume=...)` | `agent_resume`、`human_input`。`Interrupt.id` で相関付け — 同じチェックポインターに対して別プロセスでレジュームが発生した場合も含む | +| 未処理の例外 | `error`、その後 `outcome` が `failed` の `agent_end` | + +**ノードはネストされたエージェントではなく、フックになります。** `agent_id` はすべてのダッシュボード画面における主要なファセットです。`retrieve`、`grade_documents`、`should_continue` をエージェントに昇格させると識別が困難になり、最初に実行されたノードの名前でセッションがラベル付けされてしまいます。 + +フックスパンは同じ方法でレンダリングされ、ノードごとのレイテンシビューも提供されます。 + + + **ノードの名前は自由に付けられます。** ノードの実行は、その*形状*（LangGraph 独自のステップタグを持つ非リーフ実行）によって識別されます — 名前では識別されません。 + + +| 記述内容 | 記録される内容 | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | ツール | +| `add_node("ChatOpenAI", ...)` | モデル呼び出し | + +以前は、実行するものにちなんでノードに名前を付けると、そのもののイベントが消えてしまっていました。現在はそのような問題はありません。 + +### ストリーミング + +`.stream()` および `.astream()` はトークンごとのイベントを発行しません。クロージング `model_response` にまとめられます: + +| フィールド | 内容 | +| --- | --- | +| `fw_chunks` | 到着したチャンク数 | +| `fw_ttft_ms` | 最初のトークンまでの時間 | + +### ストリームレスポンスのトークン数 + +別の問題であり、見落としやすい点です: OpenAI はストリームレスポンスで使用量を送信するのは**リクエストした場合のみ**です。 + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # このフラグがないとトークン数が記録されません +``` + +アダプターはフレームワークから渡された内容を記録します。このフラグがないと記録するものがなく、`model_response` はトークン数なしで届きます。 + +## サンプル + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## スパンの名前付け + +デフォルトでは、ルートスパンにグラフ自身の名前が使用されます。任意のラベルを付けるにはラップしてください: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +マルチエージェント構成の場合はスコープをネストします。各ワーカーは `parent_id` を持つ子スパンになります: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +`agent_id` のカーディナリティは低く保ってください。ロール名やノード名を使用し、UUID や実行ごとの文字列は使わないでください。 + +## セッションの制御 + +セッション ID は以下の順序で解決され、最初に一致したものが使用されます: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. 囲んでいる `failproofai_sdk.session()` スコープ +4. `metadata["session_id"]`、`metadata["conversation_id"]`、または `metadata["thread_id"]` +5. ルート実行 ID + +セッション ID はゼロから生成されることはありません。合成 ID は1つの実行を複数のセッションに分割してしまうためです。 + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## オプション + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # すべての実行を1つのセッション ID に固定 + include_chains=set(), # 中間チェーンをフックペアとしてアローリスト登録 + capture_content=True, # False にするとプロンプトと補完をペイロードから除外 + graph_callbacks=True, # interrupt と resume をファーストクラスで扱う。langgraph 1.2+ が必要 +) +``` + +規制対象データには `capture_content=False` を設定してください。構造、タイミング、トークン数、ツール名、結果は引き続き記録されますが、メッセージ本文は記録されません。 + +`include_chains` は**ネストされた**実行にのみ適用されます。トップレベルで呼び出す Runnable はセッションのルートとなるため、フックペアではなくエージェントスパンになります。ここで名前を指定しても効果はありません。 + +## ヒューマン・イン・ザ・ループ + +`interrupt()` は4つのイベントを生成し、どちらのペアも冗長ではありません: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait、agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume、human_input +``` + +`human_wait` から `human_input` にはプロンプトと回答が含まれます（`capture_content=False` の場合は両方が除外されます。リトリーバルのドキュメントソースも同様ですが、ドキュメント数は残ります）。`agent_pause` から `agent_resume` は一時停止時間を計測する唯一のペアであるため、これがないと10分間の人間の待機がアクティブなエージェント時間として計上されます。ルートスパンは間隔を超えて開いたままになり、両方の呼び出しが1つのセッションに保たれます。 + +## よくある問題 + + + + `create_react_agent` は例外を伝播させます。モデルが失敗を確認して継続できるようにするには、ツールノードを明示的に構築してください: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + いずれの場合も、失敗はエラーを含む `tool_result` として記録されます。これは実行がその失敗から回復するかどうかだけを決定します。 + + + + グラフ外での直接的な `llm.invoke()` には親実行がないため、ルートスパンが開かれ、その中にモデルペアが発行されます。ダッシュボードはリーフを開いているエージェントの子として扱うため、このスパンは意図的なものです。名前を付けてください: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + `instrument()` を呼び出した上に、`config={"callbacks": [...]}` で Failproof ハンドラーも渡しています。それを削除してください。configure フック はプロセス内のすべてのコールバックマネージャーをすでにカバーしています。 + + + + そうはなりません。LangGraph は `GraphInterrupt` を実際の例外と同じパスで発生させるため、すべての一時停止がエラーコールバックとしてトレーサーに到達します。`GraphBubbleUp` のサブクラスはコントロールフローとして扱われるため、承認が赤いエラーとして表示されることはありません。 + + + + 以下の順序で確認してください: `instrument()` がグラフ実行前に呼び出されているか；呼び出しを囲む `with failproofai_sdk.session():` があるか；`FAILPROOFAI_SDK_STRICT=1` が設定されている場合、デグレードしたフックは握りつぶされずに例外を発生させます。 + + + +## 次のステップ + + + + ペア、ID、セッションライフサイクル、デリバリーについて。 + + + キャプチャしたセッションの因果関係を追う。 + + + CrewAI、LlamaIndex、Pydantic AI、カスタムエージェント。 + + \ No newline at end of file diff --git a/docs/ja/start/integrations/llamaindex.mdx b/docs/ja/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..51a44027a --- /dev/null +++ b/docs/ja/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "ワークフロー、ステップ、ファンクションエージェント、リトリーバーをインストルメントします。" +icon: "/images/frameworks/llamaindex.svg" +--- + +## インストール + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +対応バージョン: `llama-index-core` 0.14.23 〜 0.15。0.14.23 は、このアダプターが読み取る型付きエージェントイベントをワークフローストリームが運ぶようになったリリースです。それより前のバージョンでは、モデル名とエージェント構造の両方が欠落します。 + +## インストルメント + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +LlamaIndex のエージェント API は非同期です。すべてのスコープは `async with` と `with` の両方で動作し、同一のイベントを生成します。 + +`instrument()` は LlamaIndex のグローバルディスパッチャーにイベントハンドラーとスパンハンドラーをアタッチします。これにより、モデルの呼び出しだけでなく、エージェントループ全体が可視化されます。 + + + LLM に追加の引数を指定しないと、トレース内のすべてのトークン数が null になります。下記の[トークン数](#token-counts)を参照してください。 + + +## トークン数 + +`FunctionAgent` は `astream_chat` を呼び出しますが、`llama-index-llms-openai` はストリーミング時に `stream_options={"include_usage": True}` を送信しません。そのため、プロバイダーは usage チャンクを送信せず、いかなるインストルメンテーションも読み取るデータがありません。 + +これは上流の LlamaIndex の挙動です。LLM 側でオプトインしてください: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +同じ実行・同じモデルでの計測結果: + +| | 入力トークン | 出力トークン | +| --- | --- | --- | +| なし | `null` | `null` | +| あり | 148 | 17 | + +非ストリーミング呼び出し（`llm.chat`、`llm.achat`）は設定なしで usage を報告します。この設定が必要なのは、デフォルトのエージェントパスであるストリーミングパスのみです。 + +## 記録される内容 + +| LlamaIndex | Failproof イベント | +| --- | --- | +| `Workflow.run` ルートスパン | Session、`agent_start`、`agent_end` | +| ネストされた `Workflow.run` スパン | ネストされた `agent_start`、`agent_end` | +| ワークフローステップスパン | `hook_triggered`、`hook_completed` | +| LLM チャット開始・終了 | `model_request`、`model_response` | +| `FunctionTool.call` スパン | `tool_use`、`tool_result` | +| リトリーバル開始・終了 | `tool_use`、`tool_result`（出力は要約） | +| エンベディング | `embeddings=True` を指定しない限り記録なし | +| ツールが人間の応答を待機 | `human_wait`、`agent_pause`、その後 `agent_resume`、`human_input` | +| `AgentWorkflow` のハンドオフ | エージェントごとにネストされた `agent_start`、`agent_end`（ワークフロー配下） | +| 例外 | `error`、その後 outcome が `failed` の `agent_end`、および例外名を含む `agent_end.summary` | +| `handler.cancel_run()` | outcome が `cancelled` の `agent_end`（`error` なし）— 停止ボタンは失敗ではない | + +`agent_id` は `FunctionAgent.name` を設定した場合はその値、未設定の場合はワークフローのクラス名になります。`AgentWorkflow` 配下では、ターンを取得した各エージェントがワークフロー下に独立したネストスパンを持つため、ハンドオフは1つのエージェントではなく2つのエージェントとして記録されます。 + +リトリーバルの出力は、そのまま格納するのではなく要約されます。リトリーバーはドキュメントを返しますが、ペイロードにそのまま格納するとクエリのたびにコーパス全体がイベントストアに入ってしまいます。代わりに件数、スコアの範囲、切り詰めたスニペットが保持されます。 + +## サンプル + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +エージェントループはトレース内にフックペアとして表示されます: `init_run`、`setup_agent`、`run_agent_step`、`parse_agent_output`、`call_tool`、`aggregate_tool_results`。これらはフレームワーク自身のループであるため、エージェントではなくフックとして扱われ、`agent_id` の意味が保たれます。 + +## スパンに名前を付ける + +`agent_id` は `FunctionAgent.name` を設定した場合はその値、未設定の場合はワークフローのクラス名になります。 + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +`AgentWorkflow` 内では、その名前が各ハンドオフの記録名にもなります: + +```text +AgentWorkflow 親スパン +├─ city_analyst ターン 1 +├─ cost_analyst ターン 2 +└─ city_analyst ターン 3 — 新しいターン（最初のターンの再開ではない） +``` + +つまり、`agent_id` は**どのエージェント**が作業を行ったかを示し、`parent_id` は**どのワークフロー**に属していたかを示します。後でコントロールを引き継いだエージェントは、最初のターンを再開するのではなく、新しいターンを開始します。 + +実行をラップしてオーバーライドしたり、複数のエージェントを1つの親にまとめることもできます: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +`agent_id` は低カーディナリティに保ってください。これはすべてのダッシュボード画面における主要なファセットです。UUID や実行ごとの文字列ではなく、ロール名やワークフロー名を使用してください。 + +## セッションの制御 + +このアダプターには **`session_id` オプションはありません**。セッションは外側のスコープから取得され、指定がない場合はワークフロー実行ごとに生成された `uuid4().hex` が使用されます: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## オプション + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True にするとエンベディング呼び出しをツールペアとして記録 + steps=True, # False にするとワークフローステップのフックペアを省略 + capture_messages=True, # False にするとすべてのペイロードを省略: プロンプト、補完、 + # ツールの引数と出力、ステップの I/O、リトリーバル + # クエリ、ゴール、最終回答 + capture_limit=8192, # キャプチャされる値ごとに保持する文字数 + stale_after=600.0, # 放棄されたリーフを強制クローズするまでの秒数 + reaper_interval=30.0, # リーパーのスイープ間隔（秒）。0 で無効化 +) +``` + +| オプション | 変更が必要なケース | +| --- | --- | +| `embeddings` | エンベディングのレイテンシやコストをデバッグする場合のみ有効化。大量インデックス構築は数千回の呼び出しになり、タイムラインが埋め尽くされます。 | +| `steps` | モデルとツールのイベントだけが必要で、エージェントループのノイズが不要な場合に無効化。 | +| `capture_messages` | 規制データを扱う場合に無効化。プロンプト、モデルの補完、ツールの引数と戻り値、ワークフローステップの入出力、リトリーバルクエリ、エージェントのゴールと最終回答がすべて記録されなくなります。構造、タイミング、トークン数、アウトカムは引き続き記録されます。 | +| `capture_limit` | キャプチャされる値ごとの切り詰め前の文字数。RAG プロンプトや取得コンテキストが途中で切れている場合は増やしてください。 | +| `stale_after` | 放棄された**リーフ**（誰も消費しなかったストリーミングレスポンス、クローズが届かなかったモデルまたはツールのスパン）を強制クローズするまでの秒数。これによりセッションが永遠に `ongoing` のままにならずに確定します。放棄された実行自体はクローズ**されません**: ディスパッチャーが終了を検知できずにキャンセルされたタスクのワークフローは、`uninstrument()` が呼ばれるまで `agent_start` が開いたままになります。 | +| `reaper_interval` | スイープの頻度。`0` に設定するとリーパーを完全に無効化します。 | + +## ヒューマン・イン・ザ・ループ + +待機がツール内で発生した場合にキャプチャされます: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +通常のワークフローステップ内の `ctx.wait_for_event` はキャプチャされません。ランタイムがディスパッチャーに到達する前に中断を検知するため、ステップは終了し、一時停止のシグナルがないまま後で再実行されます。LlamaIndex がドキュメントで紹介している FunctionAgent パターンはツール内で待機するため、完全にキャプチャされます。 + +## よくある問題 + + + + LLM に `additional_kwargs={"stream_options": {"include_usage": True}}` を追加してください。[トークン数](#token-counts)を参照してください。 + + + + LlamaIndex には標準の usage フィールドがありません。アダプターはいくつかの既知の形式を試みますが、カウンターを異なる名前で定義しているインテグレーションはいずれにも一致しません。 + + 生の dict は常に送信されるため、ペイロード内の `usage` を確認してプロバイダーがどのような名前を使用しているか確認してください。 + + `usage` が入力されているにもかかわらずトークンの列が空になるのは意図的な挙動です — 誤った数値を自信を持って表示するよりも適切です。 + + + + これは FunctionAgent ループで、イテレーションごとに1セット表示されます。ダッシュボードでフック名によるフィルタリングを行ってください。これらのステップのタイミングは、モデルのみのアダプターではなくこのアダプターを使用する主な理由であることが多いです。 + + + + 以下の順序で確認してください: `instrument()` が実行前に呼び出されているか; `await` の周囲に `async with failproofai_sdk.session():` があるか; `llama-index-core` が 0.14.23 以上か; `FAILPROOFAI_SDK_STRICT=1` が設定されていれば、劣化したフックが握り潰される代わりに例外を送出します。 + + + +## 次のステップ + + + + ペア、ID、セッションライフサイクル、デリバリーについて。 + + + キャプチャしたセッションの因果関係を追う。 + + + LangGraph、CrewAI、Pydantic AI、カスタムエージェント。 + + \ No newline at end of file diff --git a/docs/ja/start/integrations/pydantic-ai.mdx b/docs/ja/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..88fd60e72 --- /dev/null +++ b/docs/ja/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "型付きエージェント、ツール、モデル呼び出し、リトライを計測します。" +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## インストール + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +対応バージョン：`pydantic-ai-slim` 2.0〜3.0。バージョン 2.0 で `Agent(instrument=...)` が削除され、このアダプターが依拠するケイパビリティプロトコルが導入されたため、1.x はこの方法では計測できません。 + +## 計測の設定 + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` は `Agent` を構築する前に実行する必要があります。ケイパビリティは構築時に付与されるため、それより前に作成されたエージェントにはケイパビリティが存在せず、何も記録されません。エラーも発生しないため原因が分かりにくいですが、このアダプターで空のトレースになる最も多い原因はこれです。 + + +モジュールスコープのエージェントはこの問題が起きやすい典型例です： + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # constructed at import time + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # run this FIRST +import agents # now the agent gets the capability +``` + +正しく設定されたか確認するには： + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI は渡したリストを単一の `root_capability` にマージするため、`agent.capabilities` 属性は存在しません。 + +計測中に構築されたエージェントはケイパビリティを保持するため、`uninstrument()` して再計測してもエージェントを再構築する必要はありません。 + +## 記録される内容 + +| Pydantic AI | Failproof イベント | +| --- | --- | +| エージェントの実行 | `agent_start`、`agent_end` | +| モデルリクエスト | `model_request`、`model_response`（トークン使用量含む） | +| ツール呼び出し | `tool_use`、`tool_result`（モデルが送信した引数含む） | +| ツールからの `ModelRetry` | エラーを持つ `tool_result` | +| 未処理の例外 | `error`、その後 `agent_end`（結果: `failed`） | + +このアダプターにはフックペアやヒューマン・イン・ザ・ループのペアはありません。Pydantic AI にはブラケット対象となるノードやステップの境界がなく、組み込みの人間による一時停止機能もないため、対応するものが存在しません。いずれかを実装する場合は、イベントを自分で発行してください — [カスタムエージェント](/ja/reference/custom-agents)を参照。 + +`output_type` はトレースに影響しません。型付き実行と文字列実行では同じイベントが生成されます。 + +## 使用例 + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +トレースでは、`restock_eta` はエラーを持つ `tool_result` として表示され、その後にエージェントが回避策を取る別のモデル呼び出しが続き、実行は最終的に `success` で終了します。両方の事実が保存されます。 + +## エラー、リトライ、制御フロー + +Pydantic AI は 3 種類の例外を発生させますが、アダプターはそれらを区別します： + +| 例外 | 扱い | 結果 | +| --- | --- | --- | +| `ModelRetry`、`ToolRetryError`、`ToolFailedError` | 実際のツール失敗 | エラーを持つ `tool_result`；実行は `success` で終了する場合あり | +| `SkipToolExecution`、`SkipToolValidation`、`SkipModelRequest`、`CallDeferred`、`ApprovalRequired` | 制御フロー | エラーではない；実行が誘導されている状態 | +| その他すべて | 失敗 | `error`、その後 `agent_end`（結果: `failed`） | + +`ModelRetry` を意図的に最初のグループに含めているのは、それが「試行が実際に失敗し、モデルに再試行が要求された」ことを意味するためです。これはまさにツールスパンのエラーフィールドが想定する内容です。制御フローとして分類してしまうと、実際のツール失敗が成功した実行の陰に隠れてしまいます。 + +## スパンに名前を付ける + +Pydantic AI 独自の実行スパンは `agent` という名前です。任意のラベルを付けるには呼び出しをラップします： + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +フレームワークのスパンは `inventory` の配下にネストされ、モデルとツールのイベントはそこに紐付けられます。 + +`agent_id` は低カーディナリティに保ってください。すべてのダッシュボード画面での主要なファセットとして使用されるため、UUID や実行ごとの文字列ではなくロール名を使用してください。 + +## セッションの制御 + +以下の順序で解決され、最初に一致したものが使用されます： + +1. `instrument("pydantic_ai", session_id=...)` +2. 囲む `failproofai_sdk.session()` スコープ +3. 実行の `conversation_id`、次に `run_id` +4. 生成された `uuid4().hex` + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## オプション + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # pin every run to one session id + capture_content=True, # False drops prompts and completions from payloads +) +``` + +## よくある問題 + + + + `instrument()` が実行される前に `Agent` が構築されています。上記の警告を確認し、`agent.root_capability.capabilities` をチェックしてください。 + + + + 裸の `raise` はそのまま伝播します。これは Pydantic AI の設計によるものです。モデルに回避させるには、対処できるメッセージと共に `ModelRetry` を raise してください。失敗はどちらの場合でも記録されます。 + + + + その子スパンは Pydantic AI 独自の実行スパンであり、モデルとツールのイベントはそこに紐付けられます。カスタム名を犠牲にして単一スパンにしたい場合は、自分のスコープを省略してください。 + + + + Pydantic AI の非同期グラフスタックはペイロードフィールドの上限より長く、トレースバックの最後の行は例外そのものです。このフィールドは末尾ではなく先頭から切り詰められるため、必要な行は残ります。 + + + +## 次のステップ + + + + ペア、ID、セッションのライフサイクル、デリバリーについて。 + + + 取得したセッションを通じて因果関係を追跡します。 + + + LangGraph、CrewAI、LlamaIndex、カスタムエージェント。 + + \ No newline at end of file diff --git a/docs/ja/start/quickstart.mdx b/docs/ja/start/quickstart.mdx index 1591069a1..66e728db7 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) から再合流してください。この場合の強制実行にはランタイムへのフックが必要です。 +**どちらのパスを選びますか？** エージェントが12種類のサポート対象[ハーネス](/ja/reference/harnesses)のいずれかで動作している場合（コーディングCLI、またはHermesやOpenClawなどのゲートウェイ）、以下の手順に従ってください。Node.js 20.9以降が必要です。エージェントにハーネスがない場合は、[Python SDK](/ja/reference/custom-agents)でトレースと監査を計装し、[最初の障害チェックを実行する](/ja/start/first-audit)から再合流してください。このパスでの強制実行にはランタイムへのフックが必要です。 @@ -16,21 +16,21 @@ 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. ワンタイムシークレットをコピーして、対象マシンに保存します： ```bash export FAILPROOFAI_KEY="" @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - セッションのトランスクリプトはデフォルトで送信されます。トランスクリプトの内容を除き、フックアクティビティとポリシー決定のみをレポートするには `--no-transcripts` を追加してください。 + セッションのトランスクリプトはデフォルトで送信されます。トランスクリプトの内容を含めずにフックアクティビティとポリシー決定のみをレポートするには、`--no-transcripts` を追加してください。 - このマシンにすでにエージェントの履歴がある場合は、過去7日間のデータをプレビューしてインポートし、配信が完了するまで待ちます。新しいマシンではこの手順をスキップしてください。 + このマシンにすでにエージェントの履歴がある場合は、過去7日分をプレビューしてインポートし、配信が完了するまで待ちます。新しいマシンではこの手順をスキップしてください。 ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Failproof AI の **Sessions** を開き、インポートしたセッションを選択します。 + Failproof AI の **Sessions** を開き、インポートされたセッションを選択します。 - - これにより Failproof AI がハーネスにアタッチされ、40の組み込みポリシーがインストールされます。Failproof AI がセッションを監査してエージェント用のポリシーを作成する前に、ローカルでのポリシー決定を確認したり強制実行を試したりするのに活用してください。 + + これにより Failproof AI がハーネスにアタッチされ、40種類の組み込みポリシーがインストールされます。Failproof AI がセッションを監査してエージェント向けのポリシーを作成する前に、ローカルでのポリシー決定を確認したり、強制実行を試したりするために使用してください。 - インストーラーにハーネスを自動検出させるか、明示的に指定することもできます。12種類すべてが有効な `--cli` 値です。`claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose`。 + インストーラーにハーネスを自動検出させるか、明示的に指定することもできます。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 ゲートウェイ + failproofai policies --install --cli claude --scope user # コーディングCLI + failproofai policies --install --cli hermes --scope user # Slack/Telegramゲートウェイ ``` - ツール呼び出しの実行前ブロックは全12種類で検証済みです。ターン終了ゲートは8種類で検証済みです。ハーネスごとのマトリックスは [強制実行機能](/ja/reference/harnesses#enforcement-capability) を参照してください。 + 実行前のツール呼び出しのブロックは全12種類で検証済みです。ターン終了ゲートは8種類で検証済みです — ハーネスごとのマトリクスは[強制実行機能](/ja/reference/harnesses#enforcement-capability)を参照してください。 - [最初の障害チェックを実行する](/ja/start/first-audit) に従ってください。「エージェントがアプローチを変えずに失敗したツールを再試行したセッションを見つける」などの具体的な目標を設定してください。 + [最初の障害チェックを実行する](/ja/start/first-audit)に従ってください。「エージェントがアプローチを変えずに失敗したツールを再試行したセッションを見つける」など、具体的な目標を設定してください。 - [ポリシーを使って最初の障害を防止する](/ja/start/first-policy) に従ってください。オブザーブモードで開始し、マッチを確認してから、レビュー済みのバージョンを強制実行します。 + [ポリシーで最初の障害を防止する](/ja/start/first-policy)に従ってください。まずオブザーブモードで開始し、マッチを確認してから、レビュー済みのバージョンを強制実行します。 - `failproofai config --status` を実行してください。正常なセットアップでは、クラウド接続、デーモンの状態、および強制実行が一時停止されているかどうかが表示されます。 + `failproofai config --status` を実行してください。正常なセットアップでは、クラウド接続、デーモンの状態、および強制実行が一時停止中かどうかが表示されます。 \ No newline at end of file diff --git a/docs/ja/start/quickstarts/crewai.mdx b/docs/ja/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..339b8a330 --- /dev/null +++ b/docs/ja/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "インストール、計測設定、最初のトレースの確認。" +icon: "/images/frameworks/crewai.svg" +--- + +最初の CrewAI トレースまで3ステップです。各イベントの内容、フロー、トラブルシューティングについては[完全ガイド](/ja/start/integrations/crewai)をご覧ください。 + +## インストール + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## 計測設定 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +クルー、エージェント、タスク、ツールの設定は何も変更する必要はありません。`instrument()` は CrewAI のモジュールレベルのイベントバスにサブスクライブします。 + +## 到着を確認する + +一度実行したら、**Observe → Sessions** を開いて環境を選択してください。実行結果が再構築されたトレースとして表示されます。 + +何も表示されない場合は、`failproofai config --status` でマシンが接続されているか確認してください。 + + + 記録される内容、フロー、トークン使用量、スパン名、オプション、よくある問題について説明します。 + \ No newline at end of file diff --git a/docs/ja/start/quickstarts/custom-agents.mdx b/docs/ja/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..2bd40bcc4 --- /dev/null +++ b/docs/ja/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "カスタムエージェント" +description: "エージェントを3つの `with` ブロックで囲むだけで、記録が始まります。" +icon: "code" +--- + +自作のエージェント、またはFailproof AIにアダプターが用意されていないフレームワーク向けです。 + +既存の処理を `with` ブロックで囲むだけです。各ブロックは開始時刻・終了時刻・所要時間を自動的に記録します。他に呼び出すものは何もありません。 + +## インストール + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # 1回のツール呼び出し +``` + +上から順に読むと、そのまま意味が伝わります。 + +| ブロック | 意味 | +| --- | --- | +| `session()` | これらのイベントは同一の実行に属する | +| `agent()` | 何かが作業を行っている — リストで見たときにわかる名前をつける | +| `tool_call()` | これは1つのツールであり、返した値がこれである | + +コードの構造に合わせて自由にネストできます。IDを受け渡す必要は一切ありません。各ブロックが自分の位置を把握しているため、記録した内容は自動的に正しい実行・正しいエージェントに紐付けられます。`async with` もまったく同じように動作します。 + +## 到着を確認する + +一度実行したら、**Observe → Sessions** を開いて環境を選択してください。再構築されたトレースとして実行結果が表示されます。 + +何も届かない場合は、`failproofai config --status` でマシンの接続状態を確認してください。 + + + すべてのイベントメソッド、コードが例外を発生させた場合の動作、実践的なサンプル、スレッドと非同期処理、アダプターのないフレームワークへの計装方法を詳しく解説しています。 + \ No newline at end of file diff --git a/docs/ja/start/quickstarts/langchain.mdx b/docs/ja/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..9071a6bc6 --- /dev/null +++ b/docs/ja/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain と LangGraph" +description: "インストール、計装、そして最初のトレースを確認する。" +icon: "/images/frameworks/langchain.svg" +--- + +LangChain または LangGraph の最初のトレースまで3ステップです。ストリーミング、human-in-the-loop、スパン命名、オプションについては[完全ガイド](/ja/start/integrations/langchain)をご覧ください。 + +## インストール + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +LangGraph なしで LangChain のみを使用する場合は `failproofai-sdk[langchain]` を使用してください。 + +## 計装 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +呼び出し箇所の変更は不要です。`instrument()` はトレーサーを登録し、LangChain がビルドするすべてのコールバックマネージャーにそれを注入します。これにより、グラフ、ツール、モデルはすべて自動でキャプチャされます — 自分で書いていないライブラリ内のものも含めて。 + +## 到達を確認する + +一度実行したら、**Observe → Sessions** を開いて環境を選択してください。実行結果が再構成されたトレースとして表示されます。 + +何も届かない場合は、`failproofai config --status` でマシンが接続されているか確認してください。 + + + 記録される内容、ストリーミング、トークン数、スパン命名、セッション制御、オプション、human in the loop について。 + \ No newline at end of file diff --git a/docs/ja/start/quickstarts/llamaindex.mdx b/docs/ja/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..0b092d128 --- /dev/null +++ b/docs/ja/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "インストール、計装、最初のトレースを確認する。" +icon: "/images/frameworks/llamaindex.svg" +--- + +最初の LlamaIndex トレースまで3ステップ。ワークフローのステップ、検索、リーパー、オプションについては[完全なガイド](/ja/start/integrations/llamaindex)をご覧ください。 + +## インストール + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## 計装 + +LlamaIndex のエージェント API は非同期です。すべてのスコープは `async with` と `with` の両方で動作します。 + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + LLM に追加の引数を一つ指定しないと、トレース内のすべてのトークン数が null になります — `llama-index-llms-openai` はストリーミング時に使用量を要求しません。詳しくは[トークン数](/ja/start/integrations/llamaindex#token-counts)をご覧ください。 + + +## 到着を確認する + +一度実行したら、**Observe → Sessions** を開いて環境を選択してください。実行結果が再構築されたトレースとして表示されます。 + +何も届かない場合は、`failproofai config --status` でマシンが接続されているか確認してください。 + + + トークン数、記録される内容、ワークフローのステップ、検索、オプション、よくある問題。 + \ No newline at end of file diff --git a/docs/ja/start/quickstarts/pydantic-ai.mdx b/docs/ja/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..a2096acaf --- /dev/null +++ b/docs/ja/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "インストール、計測、最初のトレースを確認する。" +icon: "/images/frameworks/pydantic-ai.svg" +--- + +最初の Pydantic AI トレースまで3ステップです。ツール、リトライ、ストリーミング、オプションについては[完全ガイド](/ja/start/integrations/pydantic-ai)をご覧ください。 + +## インストール + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## 計測 + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` は `Agent` を構築する**前**に実行する必要があります。この機能は構築時に付加されるため、それより前に生成されたエージェントは何も記録しません。エラーも発生しないため、問題が起きたように見えません。これはこのアダプターで空のトレースになる最も一般的な原因であり、モジュールスコープのエージェントで特に問題になります。`failproofai_sdk` をインポートし、エージェントを構築するモジュールをインポートする前に `instrument()` を呼び出してください。 + + +## 到達を確認する + +一度実行したら、**Observe → Sessions** を開いて環境を選択してください。実行結果が再構築されたトレースとして表示されます。 + +何も届かない場合は、`failproofai config --status` でマシンの接続状態を確認してください。 + + + 記録される内容、ツールとリトライ、ストリーミング、スパンの命名、オプション、よくある問題。 + \ No newline at end of file diff --git a/docs/ko/index.mdx b/docs/ko/index.mdx index 0d0af6a7b..1ee717973 100644 --- a/docs/ko/index.mdx +++ b/docs/ko/index.mdx @@ -1,41 +1,41 @@ --- -title: "에이전트를 안전하게 만드세요" -description: "코딩 CLI, 채팅 게이트웨이, 자체 호스팅 어시스턴트, 직접 계측한 에이전트 등 모든 하네스에 대한 관찰 가능성과 정책 적용." +title: "에이전트를 failproof하게 만들기" +description: "에이전트가 실행되는 모든 환경에 대한 관찰 가능성 및 정책 집행 — 코딩 CLI, 채팅 게이트웨이, 자체 호스팅 어시스턴트, 그리고 직접 구성한 에이전트까지." icon: "shield-check" --- -Failproof AI는 팀이 에이전트가 무엇을 했는지 파악하고, 어디서 실패했는지 찾아내며, 동일한 동작이 다시 발생하기 전에 안전장치를 배포할 수 있도록 도와줍니다. +Failproof AI는 팀이 에이전트의 행동을 이해하고, 실패 지점을 파악하며, 동일한 문제가 재발하기 전에 안전장치를 배포할 수 있도록 돕습니다. -**하네스**는 에이전트가 실제로 실행되는 환경을 의미합니다. Failproof AI는 Claude Code, Codex 같은 코딩 CLI, Hermes 같은 채팅 게이트웨이, OpenClaw 같은 자체 호스팅 어시스턴트 등 12가지 하네스를 지원하며, 동일한 이벤트, 동일한 정책, 동일한 세션 히스토리가 모든 하네스에 적용됩니다. 하네스가 없는 에이전트는 [Python SDK](/ko/reference/custom-agents)를 통해 보고하며, 이를 통해 추적 및 감사가 이루어집니다. 해당 환경에서 정책을 적용하려면 자체 런타임에 훅을 추가해야 합니다. +**harness**는 에이전트가 실제로 실행되는 환경을 의미합니다. Failproof AI는 12가지 환경을 지원합니다 — Claude Code, Codex 같은 코딩 CLI, Hermes 같은 채팅 게이트웨이, OpenClaw 같은 자체 호스팅 어시스턴트 — 그리고 동일한 이벤트, 동일한 정책, 동일한 세션 기록이 모든 환경에 적용됩니다. harness 없이 동작하는 에이전트는 [Python SDK](/ko/reference/custom-agents)를 통해 보고하며, 추적 및 감사가 이루어집니다. 해당 환경에서 정책을 적용하려면 자체 런타임에 훅을 추가해야 합니다. - 스킬을 사용해 프로젝트를 계측하고, 연결하고, 에이전트 로그가 도착하는지 확인하세요. + 스킬을 사용해 프로젝트를 구성하고 연결한 후, 에이전트 로그가 정상적으로 수신되는지 확인하세요. - - 에이전트 로그를 자연어로 분석하고, 쿼리하고, 대시보드를 만들고, 감사를 실행하세요. + + 에이전트 로그를 자연어로 분석, 쿼리, 대시보드 구성, 감사 실행까지 수행하세요. - - 하나의 세션에서 모델 호출, 툴, 오류, 사람의 입력, 지연 시간, 정책 결정을 한눈에 확인하세요. + + 하나의 세션에서 모델 호출, 도구, 오류, 사용자 입력, 지연 시간, 정책 결정을 한눈에 확인하세요. - 정의된 세션 집합을 감사하고, 근거가 뒷받침된 발견 사항을 검토하며, 이슈로 해결 진행 상황을 추적하세요. + 정해진 세션 집합을 감사하고, 근거 기반 발견 사항을 검토하며, 이슈로 관리하세요. - 알려진 실패 패턴을 정책으로 전환하고, 영향을 관찰하며, 전체 플릿에 배포하세요. + 알려진 실패 패턴을 정책으로 전환하고, 영향을 관찰한 후 전체 플릿에 배포하세요. -> **세션 → 감사 → 발견 사항 → 이슈 → 정책**
-> 무슨 일이 있었는지 추적하고, 실패를 찾아내고, 대응을 관리한 다음, 이후 실행에서 동일한 동작이 반복되지 않도록 방지하세요. +> **세션 → 감사 → 발견 → 이슈 → 정책**
+> 발생한 일을 추적하고, 실패를 찾고, 대응을 관리한 후, 향후 실행에서 동일한 동작을 방지하세요. ## 시작하기 -처음으로 계측된 에이전트를 배포하는 경우, [퀵스타트](/ko/start/quickstart)부터 시작하세요. 데이터가 이미 들어오고 있다면 [Sessions](/ko/sessions/overview)를 열어 감사나 정책을 설정하기 전에 실제 실행 결과를 먼저 확인하세요. +처음으로 구성된 에이전트를 배포하는 경우, [퀵스타트](/ko/start/quickstart)부터 시작하세요. 데이터가 이미 수신되고 있다면, [Sessions](/ko/sessions/overview)를 열어 감사나 정책을 설정하기 전에 실제 실행 기록을 먼저 살펴보세요. - - 캡처에서 안전하게 배포된 정책까지 전체 엔드투엔드 워크플로우를 완료하세요. + + 캡처부터 안전하게 배포된 정책까지, 전체 워크플로를 완료하세요. \ No newline at end of file diff --git a/docs/ko/policies/deploy.mdx b/docs/ko/policies/deploy.mdx index 5df943e90..c0880a64b 100644 --- a/docs/ko/policies/deploy.mdx +++ b/docs/ko/policies/deploy.mdx @@ -1,47 +1,51 @@ --- title: "정책 배포" -description: "검토된 정책 버전을 대상 머신에 롤아웃합니다." +description: "검토된 정책 버전을 대상 머신에 배포합니다." icon: "cloud-upload" --- -배포는 하나 이상의 정책 버전을 등록된 대상 머신 집합에 연결합니다. +배포는 하나 이상의 정책 버전을 등록된 머신 대상 집합에 연결합니다. ## 배포 적용 - 1. **Admin → enforcement**으로 이동하여 머신을 찾고 해당 행을 펼칩니다. - 2. **edit**을 선택하고 검토된 정책 버전을 추가한 후 **observe** 또는 강제 적용 효과를 선택합니다. - 3. 변경 사항을 적용한 다음 머신의 다음 체크인을 기다리며 배포 및 커버리지 상태를 확인합니다. + 1. **Admin → enforcement**로 이동하여 머신을 찾고 해당 행을 펼칩니다. + 2. **edit**를 선택하고 검토된 정책 버전을 추가한 후 **observe** 또는 강제 적용 효과를 선택합니다. + 3. 변경 사항을 적용한 뒤 머신의 다음 체크인을 기다리며 배포 및 커버리지 상태를 확인합니다. 4. **Observe → policy**로 이동하여 실시간 결정 사항을 검사합니다. - ![정책 버전, 강제 적용 및 관찰 효과, 배포 적용 액션이 포함된 머신 배포 편집기.](/images/dashboard/enforcement-editor.png) + ![정책 버전, enforce 및 observe 효과, 배포 적용 액션이 표시된 머신 배포 편집기.](/images/dashboard/enforcement-editor.png) - 클라우드 배포 엔드포인트는 의도적으로 일반 `fp` 명령으로 노출되지 않습니다. 머신을 로컬에서 확인한 후 대시보드를 통해 배포하세요: + `fp fleet`를 사용하여 CLI에서 배포합니다. 적용하기 전에 결과 집합을 검토하세요 — `deploy`는 전체 계획을 출력하며 **`--json` 없이 대화형 터미널에서만** 확인을 요청합니다. `--json` 옵션 사용 시, `--yes` 옵션 사용 시, 또는 stdin이 리다이렉트된 경우(CI 단계, 스크립트, 에이전트 셸 실행)에는 계획 및 프롬프트 없이 즉시 적용됩니다 — 따라서 검토가 필요하다면 먼저 `fp fleet show `을 실행하세요: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - 배포 후 `fp sessions --env production --since 24h` 및 `fp events --event-type hook_completed`를 사용하여 활동이 클라우드에 도달하는지 확인합니다. + `fp fleet diff `는 의도와 실제 전달 간의 차이를 보여주며(머신이 다음 폴링 전까지 `behind`로 표시됨), `fp fleet history `는 세대 목록을 나열하고, `fp fleet rollback `은 특정 세대로 복원합니다 — 해당 세대가 비활성화 또는 삭제된 정책을 참조하는 경우 거부됩니다. + + `failproofai config --status`로 머신 자체를 확인하고, 배포 후 `fp sessions --env production --since 24h` 및 `fp events --event-type hook_completed`를 사용하여 활동이 Cloud에 도달하는지 검증하세요. - 수정 가능한 초안이 아닌 검토된 버전을 배포하며, 세션을 검사할 수 있는 비프로덕션 머신이나 소규모 그룹부터 시작합니다. + 변경 가능한 초안이 아닌 검토된 버전을 배포하며, 세션을 검사할 수 있는 비프로덕션 머신이나 소규모 그룹부터 시작하세요. - 작업을 차단하지 않고 매칭 결과, 사유, 영향을 받는 도구, 오탐(false positive)을 검토합니다. + 작업을 차단하지 않고 매칭 항목, 이유, 영향받은 도구, 오탐지 등을 검토합니다. - - 관찰된 매칭이 안전하지 않은 작업과 유효한 작업을 구분한 후 승격하고, 대상 머신 전체가 배포를 가져왔으며 결정 사항을 보고하고 있는지 확인합니다. + + 관찰된 매칭이 안전하지 않은 작업과 유효한 작업을 구분한 후 승격하고, 모든 대상 머신이 배포를 가져와 결정 사항을 보고하는지 확인합니다. -머신에는 `policies:pull` 권한이 필요합니다. 이벤트 보고는 `events:add`로 별도로 제어되므로, 클라우드 분석 및 강제 적용을 기대하는 경우 두 가지 모두 확인하세요. +머신에는 `policies:pull` 권한이 필요합니다. 이벤트 보고는 `events:add`로 별도 제어됩니다. Cloud 분석 및 강제 적용을 기대하는 경우 두 가지 모두 확인하세요. - 강제 적용 관리는 관리자 클라우드 워크플로우입니다. 루트 전용 강제 적용 경로를 일반 고객 `/v1` API 엔드포인트로 취급하지 마세요. + 강제 적용 관리는 관리자 전용 Cloud 워크플로입니다. 루트 전용 강제 적용 경로를 일반 고객용 `/v1` API 엔드포인트로 취급하지 마세요. \ No newline at end of file diff --git a/docs/ko/policies/editor.mdx b/docs/ko/policies/editor.mdx index d38f4603a..e41618824 100644 --- a/docs/ko/policies/editor.mdx +++ b/docs/ko/policies/editor.mdx @@ -1,47 +1,49 @@ --- title: "정책 편집기" -description: "확인된 장애 유형으로부터 버전 관리된 정책을 생성하고 수정합니다." +description: "확인된 실패 모드에서 버전 관리되는 정책을 생성하고 수정합니다." icon: "file-pen-line" --- -정책 편집기를 사용해 발견된 문제를 배포 가능한 규칙으로 전환하세요. 초안이 운영 중인 동작을 몰래 변경하지 않도록 작성과 배포를 분리하여 관리합니다. +정책 편집기를 사용하여 발견된 문제나 이슈를 배포 가능한 규칙으로 변환합니다. 초안이 라이브 동작을 조용히 변경하지 않도록 작성과 배포를 분리하여 유지합니다. -문제에 반복 가능한 행동 패턴이 있다면, **Analyze → issues**에서 해당 문제를 열고 **generate policy**를 선택하세요. Failproof AI는 먼저 정책으로 해당 문제를 표현할 수 있는지 설명한 후, 검토된 의도와 발견 컨텍스트를 편집기로 가져옵니다. 생성된 소스는 게시하기 전까지 초안 상태로 유지됩니다. +이슈에 반복 가능한 액션 패턴이 있는 경우, **Analyze → issues** 에서 해당 이슈를 열고 **generate policy**를 선택합니다. Failproof AI는 먼저 정책이 해당 문제를 표현할 수 있는지 설명한 다음, 검토된 의도와 발견 컨텍스트를 편집기로 가져옵니다. 생성된 소스는 게시하기 전까지 초안 상태로 유지됩니다. -## 정책 버전 게시 +## 정책 버전 게시하기 - 1. **Admin → policy editor**로 이동한 후 **compose**에서 장애 유형을 설명하거나 JavaScript 정책 소스를 붙여넣습니다. - 2. 소스를 유효성 검사하고 보고된 모든 오류를 수정합니다. - 3. 정책 식별 정보를 입력하고 게시한 다음, **library**를 사용해 버전을 비교하거나 비활성화합니다. - 4. 버전이 머신 롤아웃에 준비되면 **enforcement**를 선택합니다. + 1. **Admin → policy editor**로 이동하여 **compose**에서 실패 모드를 설명하거나 JavaScript 정책 소스를 붙여넣습니다. + 2. 소스를 검증하고 보고된 모든 오류를 수정합니다. + 3. 정책 ID를 입력하고 게시한 다음, **library**를 사용하여 버전을 비교하거나 비활성화합니다. + 4. 버전이 머신 롤아웃 준비가 되면 **enforcement**를 선택합니다. - ![정책 식별 정보, AI 지원 초안 작성, 소스 유효성 검사, 게시 컨트롤이 포함된 정책 편집기 compose 화면.](/images/dashboard/policy-editor.png) + ![정책 ID, AI 지원 초안 작성, 소스 검증, 게시 컨트롤이 포함된 정책 편집기 compose 뷰.](/images/dashboard/policy-editor.png) - Cloud CLI는 정책 버전을 게시하지 않습니다. 편집기에 복사하기 전에 소스를 로컬에서 유효성 검사하세요: + `fp policies publish`를 사용하여 CLI에서 게시합니다. 이 명령은 **새 버전**을 생성하며 기존 버전을 직접 수정하지 않습니다. 또한 전송 전에 node로 소스의 파싱 오류를 확인합니다. 다운스트림에서는 이 검사를 수행하지 않으므로, 구문 오류가 있을 경우 시행 시점에 머신에서 오류가 발생할 수 있습니다: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - 검토된 버전은 **Admin → policy editor**에서 게시합니다. + 게시는 아무것도 배포하지 않습니다. 새 버전은 `fp fleet deploy`가 머신에 적용하기 전까지 미사용 상태로 유지됩니다. `fp policies compose ""`는 Cloud 어시스턴트를 사용하여 소스 초안을 작성하고, 게시하지 않고 검토를 위해 출력합니다. + + 로컬 에이전트 CLI(Cloud가 아닌)에 정책을 설치하려면 `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`를 사용합니다. ## 작성 체크리스트 -1. 운영 언어로 장애 유형의 이름을 지정합니다. +1. 실패 모드를 운영 언어로 명명합니다. 2. 판단에 충분한 증거를 포함하는 훅 이벤트와 도구를 선택합니다. 3. 안전하지 않은 동작과 일치하는 가장 좁은 조건을 작성합니다. -4. 에이전트 또는 운영자에게 다음에 무엇을 해야 하는지 알려주는 이유를 반환합니다. -5. 일치해야 하는 예시와 반드시 허용되어야 하는 예시를 추가합니다. +4. 에이전트 또는 운영자에게 다음 조치를 알려주는 이유를 반환합니다. +5. 일치해야 하는 예시와 허용된 상태로 유지되어야 하는 예시를 추가합니다. 6. 새 버전을 저장하고 검토를 요청합니다. -에이전트가 안전하게 방향을 수정할 수 있을 때는 `instruct`를 사용하세요. 해당 작업을 허용하면 용납할 수 없거나 되돌릴 수 없는 위험이 생길 때는 `deny`를 사용하세요. +에이전트가 안전하게 방향을 수정할 수 있을 때는 `instruct`를 사용합니다. 액션을 허용하면 용납할 수 없거나 되돌릴 수 없는 위험이 발생할 때는 `deny`를 사용합니다. - 정책 버전은 변경 불가능한 배포 입력값입니다. 초안을 편집하면 새 버전이 생성되며, 이미 머신에 할당된 버전을 덮어쓰지 않습니다. + 정책 버전은 변경 불가능한 배포 입력입니다. 초안을 편집하면 새 버전이 생성되며, 이미 머신에 할당된 버전을 덮어쓰지 않아야 합니다. \ No newline at end of file diff --git a/docs/ko/reference/cloud-cli.mdx b/docs/ko/reference/cloud-cli.mdx index 09b056e02..13b75ea18 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 텔레메트리를 검사하고 감사(audit), 발견 사항(finding), 이슈, 알림, 키, 사용자, 쿼리, 설정을 관리하세요. 로컬 훅, 정책, 캡처, 머신 등록에는 [`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 @@ -40,9 +40,9 @@ fp --json sessions --since 24h | 명령어 | 목적 | 옵션 | | --- | --- | --- | -| `fp login` | 이메일로 전송된 일회용 코드로 로그인하고 조직을 선택합니다. | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | 저장된 사용자 세션을 취소하고 제거합니다. | — | -| `fp whoami` | 현재 ID, 인증 모드, 조직, 권한을 표시합니다. | — | +| `fp login` | 이메일로 발송된 일회용 코드로 로그인하고 조직을 선택합니다. | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | 저장된 사용자 세션을 폐기하고 제거합니다. | — | +| `fp whoami` | 현재 신원, 인증 모드, 조직, 권한을 표시합니다. | — | | `fp version` | 설치된 CLI 버전을 표시합니다. | — | | `fp help` | 최상위 명령어 도움말을 표시합니다. | — | @@ -57,30 +57,34 @@ 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` | 시간 정렬 순서. 기본값: 최신 항목 먼저. | +| `--from ` / `--to ` | ISO 8601 UTC 범위; `--since`를 재정의합니다. | +| `--env ` | 환경 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--event-type ` | 이벤트 유형 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--agent-id ` | 에이전트 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--session-id ` | 세션 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--search ` | 페이로드 텍스트 검색; 반복 가능하며, 어떤 조건이든 일치하면 반환됩니다. | +| `--order asc\|desc` | 시간 순서. 기본값: 최신 항목 먼저. | | `--all` | `--limit`까지 자동 페이지네이션. | -| `--cursor ` | 불투명 커서에서 재개. | +| `--cursor ` | 불투명 커서에서 재개합니다. | | `--page-size ` | `--all` 사용 시 요청당 행 수; 최대 `200`. | -| `--full` | 더 무거운 이벤트 엔드포인트를 통해 원시 페이로드 포함. | -| `--fields ` | 선택한 필드만 반환; `payload` 요청 시 전체 모드 활성화. | +| `--full` | 더 무거운 이벤트 엔드포인트를 통해 원시 페이로드를 포함합니다. | +| `--fields ` | 선택한 필드만 반환합니다; `payload`를 요청하면 전체 모드가 활성화됩니다. | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` + + `--all`은 **`--limit`까지** 페이지네이션하며, 기본값은 **50**입니다 — 따라서 `--all`만 단독으로 사용하면 50행에서 멈춥니다. 일찍 멈출 경우 응답에 재개를 위한 `next_cursor`가 포함됩니다; `"next_cursor": null`은 피드가 실제로 소진되었음을 의미합니다. + + ### 세션 ```text @@ -89,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 ` | 세션 필터; 반복하거나 쉼표로 구분된 값 사용. | +| `--from ` / `--to ` | ISO 8601 UTC 범위; `--since`를 재정의합니다. | +| `--env ` | 환경 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--status ` | `done`, `error`, 또는 `timeout`; 반복하거나 쉼표로 구분하여 값을 지정합니다. | +| `--agent-id ` | 선택한 에이전트가 포함된 세션을 매칭합니다. | +| `--session-id ` | 세션 필터; 반복하거나 쉼표로 구분하여 값을 지정합니다. | | `--all` | `--limit`까지 자동 페이지네이션. | -| `--cursor ` | 불투명 커서에서 재개. | +| `--cursor ` | 불투명 커서에서 재개합니다. | | `--page-size ` | `--all` 사용 시 요청당 행 수; 최대 `200`. | -| `--fields ` | 선택한 필드만 반환. | -| `--full-ids` | 터미널 출력에서 세션 ID를 단축하지 않음. | -| `--agents` | 멀티 에이전트 세션의 에이전트 목록 펼침. | +| `--fields ` | 선택한 필드만 반환합니다. | +| `--full-ids` | 터미널 출력에서 세션 ID를 축약하지 않습니다. | +| `--agents` | 멀티 에이전트 세션의 에이전트 목록을 펼쳐 표시합니다. | ### 평가 @@ -111,15 +115,15 @@ fp evals [OPTIONS] | 옵션 | 설명 | | --- | --- | -| `--aggregate` | 개별 평가 대신 전체 합계 및 점수별 통계 표시. | +| `--aggregate` | 개별 평가 대신 총계 및 점수별 통계를 표시합니다. | | `--limit`, `-n ` | 최대 목록 행 수. 기본값: `50`. | -| `--since`, `--from`, `--to` | 시간 범위 선택. | -| `--env`, `--status`, `--agent-id`, `--session-id` | 필터당 정확히 하나의 값으로 범위 좁히기. | -| `--score KEY:MIN..MAX` | 점수 범위; 반복 가능하며 모든 범위가 일치해야 함. | -| `--all`, `--cursor`, `--page-size` | 목록 페이지네이션 제어. | -| `--fields ` | 선택한 필드만 반환. | -| `--full-ids` | 완전한 세션 ID 표시. | -| `--scores-full` | 터미널 출력에서 모든 점수 표시. | +| `--since`, `--from`, `--to` | 시간 범위를 선택합니다. | +| `--env`, `--status`, `--agent-id`, `--session-id` | 필터당 정확히 하나의 값으로 범위를 좁힙니다. | +| `--score KEY:MIN..MAX` | 점수 범위; 반복 가능하며 모든 범위가 일치해야 합니다. | +| `--all`, `--cursor`, `--page-size` | 목록 페이지네이션을 제어합니다. | +| `--fields ` | 선택한 필드만 반환합니다. | +| `--full-ids` | 전체 세션 ID를 표시합니다. | +| `--scores-full` | 터미널 출력에서 모든 점수를 표시합니다. | ### 오류 @@ -129,120 +133,120 @@ 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 키 | 명령어 | 목적 | 옵션 | | --- | --- | --- | -| `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` | -권한 토큰은 `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 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` | 알림을 업데이트하거나 이름을 변경합니다. | 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 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 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` | 브리프와 참조 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 ` | + +#### 감사 create 옵션 ```bash fp audits create checkout-reliability \ @@ -257,24 +261,24 @@ 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 참조 추가; 최대 다섯 번 반복 가능. | +| `--text ` | 인라인 브리프, 최대 8,192자. | +| `--text-file ` | 파일에서 브리프를 읽습니다; `--text`와 상호 배타적입니다. | +| `--url ` | 공개 HTTPS 참조를 추가합니다; 최대 5번 반복 가능합니다. | -첫 번째 실행에 컨텍스트가 필요한 경우 생성 시 포함하세요. 생성은 대기열에 추가된 실행이 시작되기 전에 정의와 컨텍스트를 함께 커밋합니다. +첫 번째 실행에 컨텍스트가 필요한 경우 생성 시에 포함하세요. 생성은 대기열에 추가된 실행이 시작되기 전에 정의와 컨텍스트를 함께 커밋합니다. `fp audits run`은 비동기입니다. 발견 사항을 읽기 전에 `fp audits runs NAME`을 폴링하여 최신 실행이 성공하거나 실패할 때까지 기다리세요. @@ -284,68 +288,112 @@ fp audits create checkout-reliability \ | 명령어 | 목적 | 옵션 | | --- | --- | --- | -| `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 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 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`에 의도적으로 없는 루트 전용 쓰기 경로이기 때문입니다. + +| 명령어 | 목적 | 옵션 | +| --- | --- | --- | +| `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 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 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` | 도움말 표시. | +| `--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`는 자동화용입니다. 로그인, 조직 전환, 어시스턴트 명령어는 사용자 세션이 필요합니다. ## 환경 변수 -| 변수 | 동등한 옵션 또는 목적 | +| 변수 | 동등한 플래그 또는 목적 | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | 현재 CLI 구성 디렉토리 위치 변경. | -| `AGENTEYE_ANALYTICS_DISABLED` 또는 `DO_NOT_TRACK` | 익명 CLI 분석 비활성화. | -| `NO_COLOR` | 색상 출력 비활성화. | - -명시적 플래그는 환경 변수를 재정의하고, 환경 변수는 저장된 구성을 재정의합니다. API 키 모드에서는 `--org` 또는 `AGENTEYE_ORG`로 테넌트를 명시적으로 선택하세요. +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `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` | 색상 출력을 비활성화합니다. | + +명시적 플래그는 환경 변수를 재정의하고, 환경 변수는 저장된 구성을 재정의합니다. API 키 모드에서는 `--org` 또는 `FP_ORG`로 테넌트를 명시적으로 선택하세요. + + + 이 변수들의 `AGENTEYE_*` 형식은 **`fp`에서 읽히지 않으며** 원래부터 그랬습니다 — CLI는 `FP_*`를 선언하며 (`fp_cli/app.py`), 알 수 없는 변수는 오류가 아닙니다. `AGENTEYE_DASHBOARD_URL`을 설정해도 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 b49d7b1db..89cebf002 100644 --- a/docs/ko/reference/custom-agents.mdx +++ b/docs/ko/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- title: "커스텀 에이전트" -description: "커스텀 에이전트의 트레이스를 계측하여 Failproof AI가 실행을 재구성하고 장애를 발견할 수 있도록 합니다." +description: "failproofai-sdk의 설정, 이벤트 카탈로그, 상관 관계 규칙 및 전달 방식." icon: "python" --- -`failproofai-sdk`를 사용해 커스텀 에이전트의 트레이스를 계측하면 Failproof AI가 각 실행을 재구성하고, 동작을 감사하며, 근거 기반의 장애를 발견할 수 있습니다. SDK는 Failproof 데몬이 Cloud로 전달할 구조화된 이벤트를 기록합니다. Python 3.10 이상이 필요합니다. +모든 설정, 메서드, 필드가 무엇을 하는지 설명합니다. 처음 계측을 시작하는 경우라면 가이드부터 시작하세요 — 이 페이지는 참조용입니다. -트레이싱을 통해 커스텀 에이전트를 관측 가능하고 감사 가능한 상태로 만들 수 있습니다. 실행 전에 안전하지 않은 동작을 차단하려면 런타임에 별도의 강제 실행 훅도 필요합니다. + + + 설치, 계측, 이벤트 메서드, 실제 예제, 그리고 자주 발생하는 문제들. + + + LangChain, CrewAI, LlamaIndex, Pydantic AI는 한 번의 호출로 스스로 계측합니다. + + - - 커스텀 에이전트 설정에서 정책을 적용하려면 [Failproof AI에 문의](mailto:support@befailproof.ai)하세요. 런타임의 모델, 도구, 라이프사이클 경계를 정책 훅에 매핑하는 작업을 도와드립니다. - +Python 3.10 이상. 런타임 의존성 없음. -
- -
- -## `failproofai-sdk` 설치 - -SDK는 현재 프라이빗 휠로 배포됩니다. 현재 버전 및 다운로드 접근 권한은 Failproof AI 담당자에게 문의하세요. +## 설치 ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -`uv`를 사용하는 경우, 먼저 휠을 다운로드한 후 `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl`을 실행하세요. 프라이빗 아티팩트 저장소 또는 의존성 잠금 파일에 휠을 고정하세요. - -패키지는 `failproofai-sdk`로 설치되며, Python에서는 `failproofai`로 임포트합니다. +패키지는 `failproofai-sdk`로 설치되며 Python에서 `failproofai_sdk`로 임포트합니다. `failproofai-sdk[langgraph]` 같은 프레임워크 extras는 해당 프레임워크 자체를 함께 설치하지만, 어댑터는 항상 기본 wheel에 포함되어 있습니다. ## Failproof 데몬 연결 - 1. **Admin → Keys**로 이동하여 `events:add` 권한이 있는 키를 생성합니다. + 1. **Admin → Keys**로 이동해 `events:add` 권한으로 키를 생성합니다. 2. 에이전트 머신에서 [Failproof 데몬을 Cloud에 연결](/ko/start/setup#connect-a-machine-to-cloud)합니다. - 3. 계측된 세션을 한 번 실행한 후, **Observe → Events**에서 정확한 ID를 확인합니다. - 4. **Observe → Sessions**로 이동하여 동일한 환경을 선택하고 재구성된 트레이스를 엽니다. + 3. 계측된 세션을 한 번 실행한 뒤, **Observe → Events**에서 정확한 ID를 확인합니다. + 4. **Observe → Sessions**로 이동해 동일한 환경을 선택하고, 재구성된 트레이스를 엽니다. - ![실행 그래프와 순서화된 이벤트 트레이스로 재구성된 커스텀 Python 에이전트 세션.](/images/dashboard/session-detail.png) + ![커스텀 Python 에이전트 세션이 실행 그래프와 순서가 있는 이벤트 트레이스로 재구성된 모습.](/images/dashboard/session-detail.png) ```bash @@ -51,102 +46,84 @@ python -c "import failproofai; print(failproofai.__version__)" -## 전체 실행 계측 - -프로세스 시작 시 `configure()`를 한 번 호출합니다. 모든 이벤트 호출은 키워드 전용이며, 안정적인 `session_id`와 `agent_id`가 필요합니다. +## 설정 ```python -import traceback -import uuid +import failproofai_sdk -import failproofai +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -failproofai.configure(environment="production") +| 인자 | 역할 | +| --- | --- | +| `environment` | 모든 이벤트에 붙는 레이블 — `production`, `staging`, `prod-eu`. 기본값은 `dev`. | +| `flush_interval` | 백그라운드 스레드가 디스크에 쓰는 주기(초). 기본값은 `0.5`. | +| `base_dir` | 쓰기 경로. 기본값은 데몬의 스풀 디렉터리로, 특별한 이유가 없는 한 이 값을 그대로 사용하면 됩니다. | -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +환경 변수로 대신 설정할 수도 있습니다: -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) +| 변수 | 역할 | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | 코드 변경 없이 `environment`를 설정합니다. 레이블이 앱이 아닌 배포 환경에 속할 때 유용합니다. `configure()` 인자가 이 값보다 우선합니다. | +| `FAILPROOFAI_HOME` | 스풀을 보관하는 Failproof AI 루트 디렉터리를 변경합니다. | +| `FAILPROOFAI_SDK_STRICT` | `1`로 설정하면 계측 오류가 로깅 대신 예외를 발생시킵니다. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1`로 설정하면 프레임워크 호환성 문제가 경고 후 계속 진행하는 대신 예외를 발생시킵니다. | -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + + **`environment`에 쉼표를 사용하지 마세요.** 수집기는 해당 필드를 쉼표 기준으로 분할하여 필터를 구성하며, 레이블에 쉼표가 포함된 이벤트는 모두 건너뜁니다 — 즉, 실행 전체가 조용히 사라질 수 있습니다. `prod,eu`가 아닌 `prod-eu`로 작성하세요. + + `configure(environment="prod,eu")`는 즉시 예외를 발생시켜 바로 알 수 있습니다. `AGENTEYE_ENVIRONMENT`는 예외를 발생시킬 수 없으므로 — 호출자가 없기 때문에 — 한 번 경고를 출력하고 `dev`로 폴백합니다. + -액터당 `agent_start`를 한 번 발행합니다. 서브 에이전트의 경우 부모의 `session_id`를 재사용하고, 각 액터에 고유한 `agent_id`를 부여하며, `parent_id`는 세션 ID가 아닌 부모 **에이전트 ID**로 설정합니다. +이벤트는 메모리에 큐잉되고 `flush_interval`초마다 백그라운드에서 기록되며, 인터프리터 종료 시 최종 flush가 실행됩니다. 프로세스가 강제 종료되면 아직 기록되지 않은 이벤트는 손실됩니다. -## 설정 레퍼런스 +## 식별자 + +모든 이벤트는 세션과 에이전트에 속합니다. **스코프가 둘 다 자동으로 채워주므로** 직접 전달할 일은 거의 없습니다: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| 설정 | 동작 | -| --- | --- | -| `base_dir` | 명시적 스풀 루트. 모든 환경 변수보다 우선합니다. | -| `flush_interval` | 메모리에서 JSONL로의 백그라운드 쓰기 간격(초). 기본값: `0.5`. | -| `environment` | 모든 이벤트에 붙는 배포 레이블. 기본값은 `dev`. | -| `FAILPROOFAI_HOME` | `custom-agents` 스풀이 포함된 Failproof AI 루트를 변경합니다. | - -`base_dir`가 설정된 경우 SDK는 해당 경로에 기록합니다. 그렇지 않으면 `FAILPROOFAI_HOME` 또는 `~/.failproofai` 아래 Failproof 데몬의 `custom-agents` 스풀을 사용합니다. +`session_id`나 `agent_id`를 명시적으로 전달하는 방식도 여전히 유효하며, 이 경우 해당 값이 우선합니다. 스코프에도 바인딩되지 않고 직접 전달하지도 않으면, Cloud가 조용히 버릴 이벤트를 내보내는 대신 `TypeError`가 발생합니다. -SDK는 메모리에 호출을 큐에 저장하고 백그라운드 스레드에서 배치를 기록합니다. Python의 `atexit` 핸들링을 통해 최종 플러시도 시도합니다. 수명이 짧은 워커의 경우 정상적인 인터프리터 종료를 허용하세요. 강제 프로세스 종료 시 메모리에 남아있는 이벤트가 손실될 수 있습니다. + + 식별자는 컨텍스트 변수를 통해 전달됩니다. `asyncio` 태스크는 자동으로 따라가지만, **새 스레드는 그렇지 않습니다** — 워커를 `failproofai_sdk.propagate()`로 감싸지 않으면 해당 이벤트가 연결되지 않은 상태로 기록됩니다. + ## 이벤트 카탈로그 -모든 메서드는 `None`을 반환합니다. `None`으로 남겨진 필드는 JSON `null`로 기록되지 않고 생략됩니다. +총 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` | + +단독으로 사용하는 세 가지: `error`, `human_pause`, `human_interrupt`. + + + +모든 메서드는 `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ SDK는 메모리에 호출을 큐에 저장하고 백그라운드 스레드에 | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -완료가 실패로 분류되어야 하는 경우 `outcome="failed"`, `"error"`, `"timeout"`, 또는 `"rejected"`를 사용하세요. `"failure"`를 포함한 다른 값은 현재 백엔드에서 실패로 분류되지 않습니다. + + + + 실행을 실패로 표시하려면 `outcome`이 반드시 `failed`, `error`, `timeout`, `rejected` 중 하나여야 합니다. 비슷해 보이는 `"failure"`를 포함하여 그 외의 값은 모두 성공으로 처리됩니다. + + +## 쌍 매칭과 시간 측정 + +**규칙은 하나: 종료 이벤트에 시작 이벤트와 동일한 id를 전달하세요.** 이것이 둘을 연결하고 SDK가 간격을 측정하는 기준입니다. + +| 쌍 | 매칭 기준 | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**`duration_ms`를 직접 전달하지 마세요.** SDK가 측정하며, 직접 전달하면 `ValueError`가 발생합니다. -## 상관관계 및 지속 시간 규칙 +유일한 예외는 `model_response`로, 실제 공급자 지연 시간을 오직 여러분만 알 수 있습니다. 정수 밀리초 값을 전달하세요 — float는 예외가 발생합니다. 해당 컬럼은 32비트 정수이므로 float를 전달하면 값이 비어 있는 채로 저장됩니다. -- 매칭되는 완료 이벤트에는 동일한 `tool_call_id`, `hook_id`, `pause_id`, 또는 `input_id`를 재사용하세요. -- SDK는 `tool_result`, `hook_completed`, `agent_resume`, `human_input`의 `duration_ms`를 자동으로 계산합니다. 해당 메서드에 직접 전달하면 `ValueError`가 발생합니다. -- 도구 및 훅 ID는 프로세스 전체의 단일 대기 맵을 공유합니다. 동시 세션과 두 네임스페이스 모두에서 전역적으로 고유하게 만드세요. 프로바이더 ID나 UUID를 사용하는 것이 가장 안전합니다. -- 프로세스가 분리된 쌍도 다운스트림에서는 상관관계가 유지되지만, SDK는 프로세스 내 지속 시간을 계산할 수 없습니다. -- 대기 맵은 최대 10,000개의 시작 항목을 보유하며, 가득 차면 가장 오래된 항목을 제거합니다. + -## 커스텀 필드 및 페이로드 +- **Id는 종류별, 세션별로만 고유하면 됩니다.** 툴 호출과 훅이 같은 id를 공유해도 되며, 동시에 실행 중인 두 세션이 같은 id를 재사용해도 충돌하지 않습니다. +- **에이전트에 스코프가 지정되지 않습니다.** 한 에이전트에서 시작하고 다른 에이전트에서 종료된 쌍도 정상적으로 매칭됩니다 — 멀티 에이전트 코드에서 일반적인 경우입니다. +- **`request_id`는 선택 사항이지만 권장합니다.** 없으면 모델 이벤트가 도착 순서대로 쌍을 이루므로, 동일한 에이전트에서 두 개의 동시 호출이 잘못 매칭될 수 있습니다. +- **프로세스를 넘나드는 쌍**은 Cloud에서 여전히 매칭되지만, SDK는 시간을 측정할 수 없습니다 — 어느 프로세스도 양쪽을 모두 보지 못했기 때문입니다. +- **최대 10,000개의 시작 이벤트가 종료를 기다릴 수 있습니다.** 이를 초과하면 가장 오래된 것이 제거되므로, 누수가 무한히 증가하지는 않습니다. -모든 이벤트는 추가 키워드 필드를 받을 수 있습니다. 다운스트림 쿼리에서 구조가 필요한 경우 JSON 호환 값을 사용하세요. UUID, datetime, decimal, set, bytes, 모델 객체 등 지원되지 않는 리프 타입은 작성기가 문자열로 변환합니다. + -예약된 커스텀 이름은 `timestamp`, `session_id`, `agent_id`, `type`, `environment`입니다. 선택 필드의 오타는 새로운 커스텀 필드로 허용되므로, 표준 필드가 Cloud에 표시되지 않을 때는 발행된 JSON을 확인하세요. +## 커스텀 필드 -## 전달 및 검증 +추가로 전달한 키워드는 이벤트와 함께 저장됩니다: + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # your own +) +``` + +나중에 쿼리하려면 JSON 타입을 사용하는 것이 좋습니다. UUID, datetime, `Decimal`, set, bytes, 모델 객체 등 그 외의 값은 문자열로 저장됩니다. + + + **필드 이름에 접두사를 붙이세요.** extras는 마지막에 적용되므로, `model`, `tool_name`, `outcome` 같은 이름의 필드는 실제 값을 조용히 덮어씁니다. 프레임워크 어댑터는 `fw_`를 사용합니다. 같은 방식을 따르면 충돌이 발생하지 않습니다. + + 이것이 잘못 입력한 선택 필드가 오류를 발생시키지 않는 이유이기도 합니다 — 단순히 새 커스텀 필드가 됩니다. Cloud에서 표준 필드가 보이지 않는다면 먼저 철자를 확인하세요. + + +다음 다섯 가지 이름은 예약되어 있으며 사용이 거부됩니다: `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 @@ -189,10 +203,14 @@ SDK는 메모리에 호출을 큐에 저장하고 백그라운드 스레드에 -Cloud가 비어 있는 경우, `$FAILPROOFAI_HOME/custom-agents/events`를 확인하거나 해당 경로가 없으면 `~/.failproofai/custom-agents/events`를 확인하세요. JSONL 파일이 존재하면 SDK가 이벤트를 발행한 것이고, 스풀이 계속 증가하면 데몬 설정 또는 전달 문제를, 스풀이 비어 있으면 계측 또는 프로세스 수명 문제를 의심하세요. +Cloud가 비어 있다면 `$FAILPROOFAI_HOME/custom-agents/events`를, 그렇지 않으면 `~/.failproofai/custom-agents/events`를 확인하세요. JSONL 파일이 있으면 SDK가 이벤트를 내보냈음을 증명합니다. 스풀이 계속 증가하면 데몬 설정이나 전달 문제를, 스풀이 비어 있으면 계측 또는 프로세스 수명 문제를 의심하세요. + + + 데몬이 중지되었을 때만 스풀을 검사하세요. 실행 중에는 밀리초 단위로 각 배치를 수집하고 삭제하므로, 디렉터리 목록이 실제로 내보낸 이벤트 수보다 훨씬 적게 보일 수 있습니다. + ## 커스텀 런타임에서 장애 방지 -감사 결과와 연결된 트레이스를 활용하여 안전하지 않은 동작, 필요한 근거, 의도된 응답을 정의합니다. 커스텀 강제 실행 통합은 실행 전에 동작을 노출하고, 구조화된 입력을 정책 엔진에 전달하며, 결과로 나오는 allow, instruct, 또는 deny 결정을 적용해야 합니다. +감사 결과와 연결된 트레이스를 활용해 안전하지 않은 액션, 필요한 증거, 의도된 응답을 정의하세요. 커스텀 적용 통합은 실행 전에 액션을 노출하고, 구조화된 입력을 정책 엔진에 전달한 뒤, 결과로 나온 allow, instruct, deny 결정을 적용해야 합니다. -런타임에 맞는 통합을 설계하고 검증하려면 [support@befailproof.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/events-and-configuration.mdx b/docs/ko/reference/events-and-configuration.mdx index ba9b6b096..6d18009b0 100644 --- a/docs/ko/reference/events-and-configuration.mdx +++ b/docs/ko/reference/events-and-configuration.mdx @@ -1,19 +1,19 @@ --- title: "이벤트 및 구성" -description: "이벤트 모델, 환경, 로컬 스토리지, 구성 경계에 대한 참조 문서입니다." +description: "이벤트 모델, 환경, 로컬 스토리지, 구성 경계를 참조합니다." icon: "list-tree" --- ## 이벤트 패밀리 -- 에이전트 시작, 종료, 일시 중지, 재개 +- 에이전트 시작, 종료, 일시 정지, 재개 - 모델 요청 및 응답 - 도구 사용 및 결과 - 훅 트리거 및 완료 -- 사람 대기, 입력, 일시 중지, 중단 +- 대기, 입력, 일시 정지, 중단 - 명시적 오류 -모든 이벤트에는 타임스탬프, 세션 ID, 에이전트 ID, 이벤트 유형, 환경 정보가 포함됩니다. 이벤트별 필드에는 모델, 도구, 상관 관계, 결과, 콘텐츠, 지속 시간, 오류 데이터가 담깁니다. +모든 이벤트에는 타임스탬프, 세션 ID, 에이전트 ID, 이벤트 유형, 환경이 포함됩니다. 이벤트별 필드에는 모델, 도구, 상관관계, 결과, 콘텐츠, 지속 시간, 오류 데이터가 담겨 있습니다. ## 이벤트 계약 검사 @@ -21,21 +21,21 @@ icon: "list-tree" 1. **Observe → Events**를 엽니다. 2. 짧은 시간 범위를 설정하고 환경, 에이전트, 이벤트 유형으로 필터링합니다. - 3. 이벤트를 선택하여 정규화된 필드와 원시 페이로드를 검사한 다음, 해당 세션을 열어 실행 컨텍스트를 확인합니다. - 4. 페어링된 지속 시간이 누락된 경우, 시작 및 완료 이벤트가 동일한 상관 관계 ID를 사용하는지 확인합니다. + 3. 이벤트를 선택해 정규화된 필드와 원시 페이로드를 검사한 다음, 해당 세션을 열어 실행 컨텍스트를 확인합니다. + 4. 쌍을 이루는 지속 시간이 없는 경우, 시작 이벤트와 완료 이벤트가 동일한 상관관계 ID를 사용하는지 확인합니다. - Events 스트림을 사용하여 데이터를 단일 에이전트 실행으로 좁히고 정규화된 이벤트 필드를 검사합니다. + Events 스트림을 사용해 데이터를 단일 에이전트 실행으로 좁히고 정규화된 이벤트 필드를 검사합니다. ![환경, 에이전트, 세션, 이벤트 유형 필터가 적용된 실시간 Events 스트림.](/images/dashboard/events-stream.png) - 그런 다음 이벤트에서 해당 세션으로 이동합니다. 트레이스는 이벤트 직전과 직후에 발생한 내용을 보여주며, 페이로드만으로는 판단이 모호할 때 필요합니다. + 그런 다음 이벤트를 따라 해당 세션으로 이동합니다. 트레이스는 이벤트 바로 전후에 일어난 일을 보여주며, 페이로드만으로는 판단이 모호할 때 반드시 확인해야 합니다. ![실행 컨텍스트에서 이벤트를 검사하는 데 사용되는 연결된 세션 트레이스.](/images/dashboard/session-detail.png) - 페어링된 이벤트 또는 지속 시간이 누락된 경우, 두 뷰 간의 상관 관계 ID와 타임스탬프를 비교하세요. + 쌍을 이루는 이벤트나 지속 시간이 없을 때는 두 뷰에서 상관관계 ID와 타임스탬프를 비교합니다. - 유효한 필터 값을 확인한 다음, 특정 세션의 전체 이벤트 페이로드를 가져옵니다: + 유효한 필터 값을 확인한 다음, 단일 세션의 전체 이벤트 페이로드를 가져옵니다: ```bash fp list event_types @@ -47,32 +47,32 @@ icon: "list-tree" --full ``` - 머신이 읽을 수 있는 형식으로 검사하려면 `fp --json events ... --fields ts,event_type,session_id,payload`를 사용하세요. + 머신 가독 형식으로 검사하려면 `fp --json events ... --fields ts,event_type,session_id,payload`를 사용합니다. ## 예약된 SDK 필드 -Python SDK의 커스텀 필드로 `timestamp`, `session_id`, `agent_id`, `type`, `environment`는 사용하지 마세요. 도구 결과 지속 시간과 같은 페어링된 이벤트 지속 시간은 SDK가 계산하며, 수동으로 지정할 수 없습니다. +`timestamp`, `session_id`, `agent_id`, `type`, `environment`는 커스텀 Python SDK 필드로 사용하지 마십시오. 도구 결과 지속 시간과 같은 쌍 이벤트 지속 시간은 SDK가 자동으로 계산하며, 수동으로 지정할 수 없습니다. ## 로컬 경계 -- Failproof AI 상태는 명시적으로 다르게 구성하지 않는 한 `~/.failproofai` 아래에 저장됩니다. -- `failproofai-sdk`는 레거시 기본 디렉터리 재정의를 위해 `AGENTEYE_HOME`을 사용합니다. +- Failproof AI 상태는 명시적으로 다르게 구성하지 않는 한 `~/.failproofai` 하위에 저장됩니다. +- `failproofai-sdk`는 항상 `~/.failproofai/custom-agents` 하위에 스풀링됩니다. `FAILPROOFAI_HOME`을 설정하면 홈 위치가 변경되지만, `custom-agents` 세그먼트는 항상 추가되므로 스풀을 그 외부에 배치할 수 없습니다. SDK 자체의 `configure(base_dir=...)`만 다른 위치에 쓸 수 있습니다. `AGENTEYE_HOME`은 이전 버전의 `agenteye-collector`가 감시 대상을 결정할 때 읽는 변수로, 더 이상 SDK가 쓰는 위치에는 영향을 미치지 않습니다. - 환경 레이블은 SDK 구성 또는 `AGENTEYE_ENVIRONMENT`를 통해 설정할 수 있습니다. -- 데몬 자격 증명은 비밀이 아닌 설정과 별도로 저장됩니다. +- 데몬 자격증명은 비밀이 아닌 설정과 별도로 저장됩니다. -안정적이고 카디널리티가 낮은 환경 이름을 사용하세요. 데몬 환경 레이블에는 쉼표가 지원되지 않습니다. +안정적이고 카디널리티가 낮은 환경 이름을 사용하십시오. 데몬 환경 레이블에는 쉼표를 사용할 수 없습니다. ## 환경 레이블 변경 - 환경 레이블은 이벤트를 내보내는 SDK 또는 Failproof 데몬이 할당합니다. 레이블을 변경한 후 **Observe → Sessions**를 열고 환경 필터를 사용하여 새 세션에 새 값이 반영되는지 확인합니다. 기존 세션은 원래 환경을 그대로 유지합니다. + 환경 레이블은 이벤트를 발신하는 SDK 또는 Failproof 데몬이 지정합니다. 레이블을 변경한 후에는 **Observe → Sessions**를 열고 환경 필터를 사용해 새 세션에 변경된 값이 적용되는지 확인합니다. 기존 세션은 원래 환경을 그대로 유지합니다. - `failproofai-sdk`의 경우, 코드에서 환경을 구성하거나 레거시 환경 변수를 사용하세요. 머신 수준 설정을 변경할 때는 데몬 구성을 다시 실행하세요. + `failproofai-sdk`의 경우, 코드 내에서 환경을 구성하거나 레거시 환경 변수를 사용합니다. 머신 수준 설정을 변경할 때는 데몬 구성을 다시 실행합니다. ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/ko/reference/harnesses.mdx b/docs/ko/reference/harnesses.mdx index e0d5d1c38..66fb50e16 100644 --- a/docs/ko/reference/harnesses.mdx +++ b/docs/ko/reference/harnesses.mdx @@ -1,47 +1,47 @@ --- 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)를 통해 연락주시면 매핑을 도와드리겠습니다. -| 하네스 | 지원되는 훅 스코프 | +| 하네스 | 지원되는 훅 범위 | | --- | --- | | 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)"은 현재 어댑터가 반환한 판정을 지정된 하네스가 수용함을 의미합니다. 도구 사후 차단(Post-tool blocking)은 모델에 표시되는 결과를 교체할 수 있지만, 이미 발생한 도구 부작용을 되돌릴 수는 없습니다. +"차단(Block)"은 현재 어댑터가 반환한 판정을 해당 하네스가 소비함을 의미합니다. 도구 사후 차단은 모델에 표시되는 결과를 대체할 수 있지만, 이미 발생한 도구 부작용을 되돌릴 수는 없습니다. -| 하네스 | 검증된 차단 이벤트 | 관찰 전용 또는 비차단 주의 사항 | +| 하네스 | 검증된 차단 이벤트 | 관찰 전용 또는 비차단 주의사항 | | --- | --- | --- | -| 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` | 도구 사후 차단은 실행 후 결과를 교체하며, 세션 및 알림 이벤트는 관찰 전용입니다. | +| 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` | 도구 사후, 세션, subagent-stop 판정은 게이트로 작동하지 않습니다. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | 도구 사후, 세션, subagent-stop, compaction 이벤트는 관찰 전용입니다. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | 도구 사후 및 subagent-stop 판정은 관찰 전용입니다. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, 조건부 `PermissionRequest` | 권한 훅은 모든 권한 모드에서 실행되지 않으며, 도구 사후 및 세션 이벤트는 관찰 전용입니다. | -| Antigravity CLI | `PreToolUse`, `Stop` | 사용자 프롬프트 및 도구 사후 판정은 관찰 전용이나, 프롬프트 명령 주입은 여전히 가능합니다. | -| Goose | `PreToolUse` | 사용자 프롬프트, 도구 사후, 세션 이벤트는 관찰 전용입니다. 네이티브 차단 stop 훅이 상위에 존재하지만 현재 어댑터에는 설치되어 있지 않습니다. | +| 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를 업그레이드한 후, 특히 공통 도구 사전 게이트(pre-tool gate)가 아닌 프롬프트, stop, 권한, 도구 사후 동작에 의존하는 정책이 있는 경우 반드시 재테스트하세요. +기능은 버전에 따라 달라집니다. 특히 정책이 일반적인 도구 사전 게이트가 아닌 프롬프트, 중지, 권한, 도구 사후 동작에 의존하는 경우, 에이전트 CLI를 업그레이드한 후 반드시 재테스트하시기 바랍니다. ## 캡처 및 정책 훅 설치 @@ -49,23 +49,23 @@ icon: "plug-zap" 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) - 훅을 설치한 후 Events 스트림에 연결한 머신 및 환경의 새 이벤트가 표시되어야 합니다. + 훅을 설치한 후 Events 스트림에 연결한 머신과 환경에서 새 이벤트가 표시되어야 합니다. ![새로 설치된 하네스가 보고 중임을 확인하는 데 사용되는 실시간 Events 스트림.](/images/dashboard/events-stream.png) - 마지막으로, 동일한 머신에 정책 결정이 귀속되는지 확인합니다. 이를 통해 하네스가 트레이스 이벤트뿐만 아니라 정책 활동도 보고하고 있음을 확인할 수 있습니다. + 마지막으로, 정책 결정이 동일한 머신에 귀속되는지 확인합니다. 이를 통해 하네스가 추적 이벤트뿐만 아니라 정책 활동도 보고하고 있음을 확인할 수 있습니다. - ![새로 연결된 하네스의 정책 결정을 검증하는 데 사용되는 Policy 페이지.](/images/dashboard/policy-observe.png) + ![새로 연결된 하네스의 정책 결정을 확인하는 데 사용되는 Policy 페이지.](/images/dashboard/policy-observe.png) - 감지된 모든 하네스에 훅 설치: + 감지된 모든 하네스에 훅을 설치합니다: ```bash failproofai config \ @@ -74,7 +74,7 @@ icon: "plug-zap" failproofai policies --install ``` - 또는 특정 하네스와 설정 스코프를 지정하여 설치: + 또는 특정 하네스와 설정 범위를 지정합니다: ```bash failproofai policies --install \ @@ -82,9 +82,9 @@ icon: "plug-zap" --scope user ``` - Project 스코프는 훅 설정을 리포지토리에 함께 보관합니다. User 스코프는 리포지토리 전반의 작업을 포괄합니다. Claude Code는 local 스코프도 지원하며, 지원 여부는 하네스마다 다르고 CLI는 지원되지 않는 조합을 거부합니다. + 프로젝트 범위는 훅 설정을 리포지토리와 함께 유지합니다. 사용자 범위는 리포지토리 전반의 작업을 포괄합니다. Claude Code는 로컬 범위도 지원하며, 지원 여부는 하네스마다 다르고 CLI는 지원하지 않는 조합을 거부합니다. - 머신 및 이벤트 확인: + 머신과 이벤트를 확인합니다: ```bash failproofai config --status @@ -98,7 +98,7 @@ icon: "plug-zap" - 추가 경로는 클라우드가 아닌 머신에 등록됩니다. 경로를 추가한 후 **Observe → Sessions**을 열고, 해당 머신의 환경으로 필터링하여 새 경로의 세션이 표시되는지 확인합니다. 감사에 활용하기 전에 세션을 열어 에이전트, 하네스, 이벤트 타임스탬프를 점검하세요. + 추가 경로는 Cloud가 아닌 머신에 등록됩니다. 경로를 추가한 후 **Observe → Sessions**를 열고 머신의 환경으로 필터링하여 새 경로의 세션이 표시되는지 확인합니다. 감사에 활용하기 전에 세션을 열어 에이전트, 하네스, 이벤트 타임스탬프를 확인하세요. ![추가 캡처 경로에서 데이터를 수신하는 환경으로 필터링된 Sessions 목록.](/images/dashboard/sessions-list.png) @@ -117,5 +117,5 @@ icon: "plug-zap" - 설치 후 새 세션을 한 번 실행해 보세요. 롤아웃을 확대하기 전에 실시간 이벤트 스트림과 실제 정책 결정 모두를 확인하세요. + 설치 후 새 세션을 한 번 실행해 보세요. 롤아웃을 확장하기 전에 실시간 이벤트 스트림과 실제 정책 결정을 모두 확인하시기 바랍니다. \ No newline at end of file diff --git a/docs/ko/reference/overview.mdx b/docs/ko/reference/overview.mdx index 0868e02bd..a65ecf919 100644 --- a/docs/ko/reference/overview.mdx +++ b/docs/ko/reference/overview.mdx @@ -1,6 +1,6 @@ --- -title: "통합 및 레퍼런스" -description: "지원되는 에이전트 하네스, SDK, CLI, HTTP API를 연결하세요." +title: "통합 및 참조" +description: "지원되는 에이전트 하네스, SDK, CLI, HTTP API를 연결합니다." icon: "braces" --- @@ -8,54 +8,57 @@ icon: "braces" - 지원되는 코딩 및 자율 에이전트 CLI에 훅을 설치하세요. + 지원되는 코딩 및 자율 에이전트 CLI에 훅을 설치합니다. - - 커스텀 에이전트의 실패를 찾기 위해 트레이스를 계측하고, 런타임에 방지 기능을 추가하려면 저희에게 문의하세요. + + LangGraph, CrewAI, LlamaIndex, Pydantic AI 또는 커스텀 에이전트를 계측합니다. + + + 설정, 이벤트 카탈로그, 상관관계 규칙, 전달 방식을 안내합니다. - 로컬 프로젝트, 세션, 정책 활동, 오프라인 감사를 검토하세요. + 로컬 프로젝트, 세션, 정책 활동, 오프라인 감사를 검토합니다. - 로컬 캡처, 훅, 정책, 감사, 전송, 머신 상태를 구성하세요. + 로컬 캡처, 훅, 정책, 감사, 전달, 머신 상태를 구성합니다. - Cloud 세션, 감사, 이슈, 알림, 키, 사용자, 설정을 조회하고 관리하세요. + 클라우드 세션, 감사, 이슈, 알림, 키, 사용자, 설정을 조회하고 관리합니다. - FastAPI 서비스를 사용해 완료되었거나 비활성 상태인 세션을 평가하세요. + FastAPI 서비스를 사용해 완료된 세션이나 비활성 세션을 채점합니다. - 워크플로우에 특화된 allow, instruct, deny 결정을 작성하고 테스트하세요. + 워크플로우별 allow, instruct, deny 결정을 작성하고 테스트합니다. - 고객이 관리하는 Kubernetes 클러스터에 Cloud 컨트롤 플레인을 배포하세요. + 고객 관리 Kubernetes 클러스터에 클라우드 컨트롤 플레인을 배포합니다. -자동 생성된 [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. 통합 환경으로 필터링하고, 감사에 필요한 모델, 도구, 오류, 정책 필드를 확인하기 위해 세션 하나를 열어보세요. + 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 데몬을 연결한 뒤, 첫 번째 세션을 확인하세요. + 머신 키를 생성하고, Failproof 데몬을 연결한 후, 첫 번째 세션을 확인합니다. ```bash fp keys create agent-production \ @@ -71,8 +74,8 @@ icon: "braces" 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/troubleshooting.mdx b/docs/ko/reference/troubleshooting.mdx index 10df6153f..32c13f53f 100644 --- a/docs/ko/reference/troubleshooting.mdx +++ b/docs/ko/reference/troubleshooting.mdx @@ -1,16 +1,16 @@ --- title: "문제 해결" -description: "누락된 세션, 누락된 정책, 전달 실패, 차단된 에이전트 작업을 진단합니다." +description: "누락된 세션, 누락된 정책, 전달 실패, 차단된 에이전트 동작을 진단합니다." icon: "wrench" --- - + - **Administration → Keys**를 열고 머신 키가 활성 상태이며 `events:add` 권한이 있는지 확인하세요. 그런 다음 **Observe → Events**를 열고 시간 범위를 넓히고 환경 및 에이전트 필터를 초기화하세요. 이벤트가 존재하면 세션 ID를 검색한 후 **Observe → Sessions**에서 그룹화를 확인하세요. 이벤트가 없다면 CLI에서 Failproof 데몬을 진단하세요. + **Administration → Keys**를 열어 머신 키가 활성 상태이고 `events:add` 권한이 있는지 확인합니다. 그런 다음 **Observe → Events**를 열고 시간 범위를 넓히고 환경 및 에이전트 필터를 초기화합니다. 이벤트가 존재한다면 세션 ID를 검색한 후 **Observe → Sessions**에서 그룹화를 확인합니다. 이벤트가 없다면 CLI에서 Failproof 데몬을 진단합니다. - ![기본 필터가 표시되고 최근 에이전트 이벤트가 들어오는 라이브 이벤트 스트림.](/images/dashboard/events-stream-current.png) + ![기본 필터가 표시되고 최근 에이전트 이벤트가 수신되는 라이브 Events 스트림.](/images/dashboard/events-stream-current.png) ```bash @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - 캡처가 활성화되어 있는지, 설정된 키에 `events:add` 권한이 있는지, 대시보드 필터가 전송된 환경과 일치하는지 확인하세요. + 캡처가 활성화되어 있는지, 설정된 키에 `events:add` 권한이 있는지, 대시보드 필터가 전송된 환경과 일치하는지 확인합니다. - **Observe → Events**에서 필터를 초기화하고 정확한 SDK 세션 ID를 검색하세요. 아무것도 표시되지 않으면 소스 머신에서 SDK 스풀과 Failproof 데몬을 확인하세요. + **Observe → Events**에서 필터를 초기화하고 정확한 SDK 세션 ID를 검색합니다. 아무것도 표시되지 않으면 소스 머신에서 SDK 스풀과 Failproof 데몬을 확인합니다. ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - 에이전트 프로세스가 `AGENTEYE_SPOOL_TO_FAILPROOFAI=1`을 설정하고 있는지, SDK 시작 전에 `$FAILPROOFAI_HOME/custom-agents`(없으면 `~/.failproofai/custom-agents`)가 존재하는지 확인하세요. + 데몬이 실행 중이고 연결되어 있는지 확인하십시오 — SDK는 데몬 존재 여부와 관계없이 스풀링합니다. 스풀 디렉토리는 미리 존재할 필요가 **없으며**(작성자가 생성), 이를 선택하는 환경 변수도 없습니다. 유일한 루트는 `$FAILPROOFAI_HOME/custom-agents`이고, 없을 경우 `~/.failproofai/custom-agents`이며, 유일한 재정의 방법은 `configure(base_dir=...)`입니다. 프로세스가 `SIGKILL` 또는 OOM으로 종료된 경우 아직 큐에 남아 있던 데이터는 손실됩니다 — 이를 방지하려면 `SIGTERM`을 처리하십시오. - **Admin → enforcement**를 열고 머신을 선택한 후 할당된 버전, 보고된 버전, 이전 버전을 비교하세요. 배포 범위에 해당 머신이 포함되어 있는지, 키에 `policies:pull` 권한이 있는지 확인하세요. 정책 전달이 실패해도 수집은 정상적으로 작동할 수 있습니다. + **Admin → enforcement**를 열고 머신을 선택한 후 할당된 버전, 보고된 버전, 이전 버전을 비교합니다. 배포 범위에 해당 머신이 포함되어 있는지, 키에 `policies:pull` 권한이 있는지 확인합니다. 이벤트 수집은 정책 전달이 실패하더라도 작동할 수 있습니다. @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - 머신 ID와 레이블이 대시보드 대상과 일치하는지 확인하세요. 기존 자격 증명이 이벤트 수집만 허용하는 경우 정책 권한이 있는 키로 다시 연결하세요. + 머신 ID와 레이블이 대시보드 대상과 일치하는지 확인합니다. 기존 자격 증명이 이벤트 수집 권한만 부여하는 경우 정책 지원 키로 재연결하십시오. - + - **Admin → enforcement**를 열고 머신의 마지막 확인 시간과 보고된 버전을 확인하세요. 머신이 오래된 상태라면 로컬 데몬 문제로 처리하세요. 사용할 수 없는 데몬을 우회하기 위해 배포된 정책을 약화시키지 마세요. + **Admin → enforcement**를 열고 머신의 마지막 접속 시간과 보고된 버전을 확인합니다. 머신이 오래된 상태라면 이를 로컬 데몬 문제로 처리합니다. 데몬을 사용할 수 없다는 이유만으로 배포된 정책을 약화시키지 마십시오. @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - `failproofaid`를 재시작하거나 업데이트하세요. CLI와 데몬 프로토콜 버전이 다를 경우 설정을 다시 실행하세요. 설정된 데몬 경로는 설계상 폐쇄 방향으로 실패합니다. + `failproofaid`를 재시작하거나 업데이트하고, CLI와 데몬 프로토콜 버전이 다를 경우 구성을 다시 실행합니다. 설정된 데몬 경로는 설계상 실패 시 차단(fail closed) 방식으로 동작합니다. - 클라우드에서 작성한 정책의 경우 **Admin → policy editor**를 열고 초안을 선택한 후 게시 전에 유효성 검사 오류를 검토하세요. 로컬 정책의 경우 CLI로 유효성을 검사한 다음 테스트 작업 후 **Observe → policy**를 열어 결정이 도착하는지 확인하세요. + Cloud에서 작성한 정책의 경우 **Admin → policy editor**를 열고 초안을 선택한 후 게시 전에 유효성 검사 오류를 검토합니다. 로컬 정책의 경우 CLI로 유효성을 검사한 다음 테스트 동작 후 **Observe → policy**를 열어 결정이 도착하는지 확인합니다. - 파일 이름이 `policies.js`, `policies.mjs`, 또는 `policies.ts`로 끝나는지, 모듈이 `customPolicies.add(...)`를 호출하는지, 정책 파일에서 임포트가 정상적으로 해석되는지 확인하세요. + 파일 이름이 `policies.js`, `policies.mjs`, 또는 `policies.ts`로 끝나는지, 모듈이 `customPolicies.add(...)`를 호출하는지, 정책 파일에서 임포트가 올바르게 해석되는지 확인합니다. ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -91,14 +91,14 @@ icon: "wrench" - + - **Analyze → audits**를 열고 실행을 선택한 후 모델 분석이 실행되었는지 확인하세요. 그런 다음 범위와 기간을 **Observe → sessions**과 비교하고 해당 모집단에서 대표적인 트레이스를 여세요. + **Analyze → audits**를 열고 실행을 선택한 후 모델 분석이 실행되었는지 확인합니다. 그런 다음 범위와 기간을 **Observe → sessions**와 비교하고 해당 모집단에서 대표적인 트레이스를 엽니다. - 분석이 성공적으로 실행되었을 때만 결과가 없는 것이 의미 있습니다. 분석을 건너뛰었거나 실패한 경우, 실행은 결과를 생성하지 않고 향후 성공적인 실행을 위해 미분석 기간을 열어둡니다. 모델 분석이 비활성화된 경우에도 결과가 생성되지 않는데, 이는 결정론적 자격 증명 및 PII 스캔이 통계만 기록하고 더 이상 결과를 발생시키지 않기 때문입니다. + 결과가 0인 경우는 분석이 성공적으로 실행된 경우에만 의미가 있습니다. 분석이 건너뛰어졌거나 실패한 경우 실행에서 발견 항목이 생성되지 않으며 분석되지 않은 기간이 향후 성공적인 실행을 위해 열린 상태로 유지됩니다. 모델 분석이 비활성화된 경우에도 감사에서 발견 항목이 생성되지 않는데, 이는 결정론적 자격 증명 및 PII 스캔이 통계는 기록하지만 더 이상 발견 항목을 발생시키지 않기 때문입니다. - ![환경, 에이전트, 주기, 스윕 기간으로 세션 모집단을 정의하는 감사 양식.](/images/dashboard/audit-new.png) + ![환경, 에이전트, 주기 및 스윕 기간이 세션 모집단을 정의하는 감사 양식.](/images/dashboard/audit-new.png) ```bash @@ -110,31 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - 실행이 대기 중 상태로 유지되면 감사 에이전트 용량이 확보될 때까지 기다리거나 배포 운영자에게 감사 플릿을 점검하도록 요청하세요. 대기 중인 감사는 재시도되며 즉시 건너뛰지 않습니다. + 실행이 큐에 계속 남아 있다면 감사 에이전트 용량이 확보될 때까지 기다리거나 배포 운영자에게 감사 플릿을 확인해 달라고 요청하십시오. 큐에 있는 감사는 재시도되며 즉시 건너뛰어지지 않습니다. - 완료된 세션을 열고 수동 평가가 성공하는지 확인하세요. 호스팅된 클라우드는 현재 대시보드에서 평가자 엔드포인트 제어를 지원하지 않으며, 서버 운영자가 직접 설정해야 합니다. + 완료된 세션을 열고 수동 평가가 성공하는지 확인합니다. 호스팅된 Cloud는 현재 대시보드에서 평가자 엔드포인트를 제어하는 기능이 없으므로 서버 운영자가 이를 설정해야 합니다. - 평가자 자체를 확인한 후 최근 평가 상태를 점검하세요: + 평가자 자체를 확인한 다음 최근 평가 상태를 검사합니다: ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - 셀프 호스팅 클라우드에서는 서버에 `EVALUATOR_ENDPOINT`가 설정되어 있는지, `EVALUATOR_TOKEN`이 평가자와 일치하는지 확인하세요. 엔드포인트가 없으면 자동 평가가 비활성화됩니다. + 셀프 호스팅 Cloud의 경우 서버에 `EVALUATOR_ENDPOINT`가 설정되어 있고 `EVALUATOR_TOKEN`이 평가자와 일치하는지 확인합니다. 엔드포인트가 없으면 자동 평가가 비활성화됩니다. - + - 조직 전환기를 사용하여 예상 슬러그와 권한을 확인한 후 CLI 결과와 비교하세요. + 조직 전환기를 사용하여 예상된 슬러그와 권한을 확인한 후 CLI와 결과를 비교합니다. ```bash @@ -143,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - API 키 모드에서는 `fp --org --api-key ...`를 지정하거나 `AGENTEYE_ORG`를 설정하세요. API 키 요청에서는 저장된 사용자 세션의 조직 상태가 의도적으로 무시됩니다. + API 키 모드에서는 `fp --org --api-key ...`를 지정하거나 `AGENTEYE_ORG`를 설정합니다. 저장된 사람 세션의 조직 상태는 API 키 요청에서는 의도적으로 무시됩니다. - **Observe → policy**를 열고 결정 및 연결된 세션을 보존하면서 오탐 조건을 파악하세요. 그런 다음 **Admin → enforcement**를 열고 영향받은 머신을 이전 버전으로 롤백하세요. **Policy editor**에서 더 좁은 범위의 버전을 만들고 소규모로 테스트한 후, 유효한 작업이 성공한 경우에만 범위를 확장하세요. + **Observe → policy**를 열고 결정과 연결된 세션을 보존한 후 거짓 양성 조건을 파악합니다. 그런 다음 **Admin → enforcement**를 열고 영향을 받는 머신을 이전 버전으로 롤백합니다. **Policy editor**에서 더 좁은 버전을 만들고 소규모 범위에서 테스트한 후 유효한 작업이 성공했을 때만 확장합니다. - 클라우드 배포 롤백은 대시보드에서만 가능합니다. 로컬 세션 일시 중지는 클라우드 관리 정책을 비활성화하지 않습니다. 대시보드를 사용할 수 없는 경우 머신 및 배포 상태를 캡처하고 차단된 작업을 반복적으로 재시도하는 대신 대시보드 접근을 복구하세요. + Cloud 배포 롤백은 대시보드에서만 가능합니다. 로컬 세션 일시 중지는 Cloud 관리 정책을 비활성화하지 않습니다. 대시보드를 사용할 수 없는 경우 머신 및 배포 상태를 캡처하고 차단된 동작을 반복해서 재시도하는 대신 대시보드 접근을 복원하십시오. ```bash failproofai config --status @@ -164,4 +164,4 @@ icon: "wrench" -지원팀에 문의할 때는 CLI 버전, 하네스, 환경, 관련 세션 또는 배포 ID, 그리고 시크릿을 제거한 `failproofai config --status` 출력 결과를 포함해 주세요. \ No newline at end of file +지원팀에 문의할 때는 CLI 버전, 하네스, 환경, 관련 세션 또는 배포 ID, 그리고 시크릿을 제거한 `failproofai config --status` 출력을 포함하십시오. \ No newline at end of file diff --git a/docs/ko/sessions/live-events.mdx b/docs/ko/sessions/live-events.mdx index 146f00efd..fbaf62688 100644 --- a/docs/ko/sessions/live-events.mdx +++ b/docs/ko/sessions/live-events.mdx @@ -1,21 +1,21 @@ --- title: "라이브 이벤트" -description: "세션이 실행되는 동안 에이전트 활동을 실시간으로 확인하세요." +description: "세션이 실행 중인 동안 에이전트 활동을 실시간으로 확인합니다." icon: "radio" --- -라이브 이벤트를 통해 계측이 올바르게 작동하는지 확인하고, 세션이 완료될 때까지 기다리지 않고 위험한 실행을 실시간으로 모니터링할 수 있습니다. +라이브 이벤트를 통해 계측 설정을 확인하고, 세션이 완료될 때까지 기다리지 않고도 위험한 실행을 실시간으로 모니터링할 수 있습니다. ## 활동 모니터링 1. **Observe → Events**로 이동합니다. - 2. 데이터가 수신되는지 확인하려면 현재 시간 범위에서 필터 없이 시작하세요. - 3. 환경, 이벤트 유형, 에이전트, 또는 세션으로 필터링합니다. 페이로드 텍스트는 검색을 사용하세요. - 4. 이벤트를 선택하면 요약 및 세부 정보를 확인할 수 있습니다. 세션 링크를 따라가면 전체 트레이스를 볼 수 있습니다. + 2. 데이터가 정상적으로 유입되는지 확인하려면 현재 시간 범위를 선택하고 필터를 적용하지 않은 상태로 시작합니다. + 3. 환경, 이벤트 유형, 에이전트, 세션으로 필터링합니다. 페이로드 텍스트는 검색을 활용하세요. + 4. 이벤트를 선택하면 요약 및 상세 정보를 확인할 수 있습니다. 세션 링크를 따라가면 전체 트레이스를 볼 수 있습니다. - ![시간, 환경, 이벤트 유형, 에이전트, 모델, 컨텍스트, 세션으로 필터링된 라이브 이벤트 스트림 — Hermes 채팅 게이트웨이와 코딩 CLI 실행의 트래픽이 표시됩니다.](/images/dashboard/events-stream-current.png) + ![Hermes 채팅 게이트웨이의 트래픽과 코딩-CLI 실행 결과가 시간, 환경, 이벤트 유형, 에이전트, 모델, 컨텍스트, 세션으로 필터링되어 표시된 라이브 이벤트 스트림.](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +24,22 @@ icon: "radio" fp --json events --full --session-id --all ``` - 기본 피드에는 원시 페이로드가 포함되지 않습니다. `--full` 옵션은 범위가 정해진 세션 조사에서만 사용하세요. + 기본 피드에는 원시 페이로드가 포함되지 않습니다. `--full` 옵션은 특정 세션을 집중적으로 조사할 때만 사용하세요. -이벤트 스트림을 활용해 다음 세 가지 즉각적인 질문에 답할 수 있습니다: +이벤트 스트림을 통해 다음 세 가지 사항을 즉시 확인할 수 있습니다: -- 예상된 에이전트가 올바른 환경에 보고하고 있는가? -- 모델 호출, 툴 호출, 정책 결정이 순서대로 수신되고 있는가? -- 세션이 진행을 멈추거나 동일한 작업을 반복하고 있지는 않은가? +- 예상한 에이전트가 올바른 환경에 보고하고 있는가? +- 모델 호출, 도구 호출, 정책 결정이 순서대로 유입되고 있는가? +- 세션이 진행을 멈추거나 동일한 작업을 반복하기 시작했는가? -이벤트 유형에는 에이전트 라이프사이클 이벤트, 모델 요청 및 응답, 툴 사용 및 결과, 훅 실행, 사람의 대기 및 인터럽트, 명시적 오류가 포함됩니다. 상관 관계 ID는 툴 호출과 그 결과처럼 쌍을 이루는 이벤트를 연결합니다. +이벤트 유형에는 에이전트 생명주기 이벤트, 모델 요청 및 응답, 도구 사용 및 결과, 훅 실행, 사람 대기 및 인터럽트, 명시적 오류가 포함됩니다. 상관 ID(Correlation ID)는 도구 호출과 그 결과처럼 쌍을 이루는 이벤트를 연결합니다. - 새로운 통합을 검증할 때는 라이브 뷰를 넓게 유지하세요. 첫 번째 이벤트가 확인된 후에만 필터를 추가하세요. 잘못된 필터를 적용하면 수집 실패처럼 보일 수 있습니다. + 새로운 통합을 검증할 때는 라이브 뷰를 광범위하게 유지하세요. 첫 번째 이벤트가 확인된 후에만 필터를 추가하세요. 잘못된 필터를 적용하면 데이터 수집에 실패한 것처럼 보일 수 있습니다. 이벤트가 표시되지 않으면 `failproofai config --status`를 실행한 후 [수집 문제 해결](/ko/reference/troubleshooting)을 참고하세요. -지원되는 12개의 [하네스](/ko/reference/harnesses) 중 하나에서 실행되지 않는 에이전트는 [Python SDK](/ko/reference/custom-agents)를 통해 동일한 이벤트 유형을 보고하며, 게이트웨이 및 프로덕션 에이전트가 의존하는 human-in-the-loop 이벤트(`human_wait`, `human_input`, `human_interrupt`)도 포함됩니다. \ No newline at end of file +지원되는 12개의 [하네스](/ko/reference/harnesses) 중 하나에서 실행되지 않는 에이전트는 [Python SDK](/ko/reference/custom-agents)를 통해 동일한 이벤트 유형을 보고하며, 여기에는 게이트웨이 및 프로덕션 에이전트가 의존하는 휴먼-인-더-루프 이벤트(`human_wait`, `human_input`, `human_interrupt`)도 포함됩니다. \ No newline at end of file diff --git a/docs/ko/start/first-policy.mdx b/docs/ko/start/first-policy.mdx index 203b4bb94..c866ce629 100644 --- a/docs/ko/start/first-policy.mdx +++ b/docs/ko/start/first-policy.mdx @@ -1,6 +1,6 @@ --- -title: "정책으로 첫 번째 장애를 예방하세요" -description: "정책 버전을 작성하고, 관찰 모드로 배포한 다음, 실제로 적용하세요." +title: "정책으로 첫 번째 실패 예방하기" +description: "정책 버전을 작성하고, 관찰 모드로 배포한 다음, 실제로 적용합니다." icon: "shield-check" --- @@ -10,24 +10,24 @@ icon: "shield-check" - **Admin → policy editor**로 이동합니다. 데모 정책에서 시작하여 소스를 검토하거나 편집한 다음, **publish version**을 선택합니다. 게시하면 머신에 배포할 수 있는 변경 불가능한 버전이 생성됩니다. + **Admin → policy editor**로 이동합니다. 데모 정책으로 시작하여 소스를 검토하거나 편집한 후 **publish version**을 선택합니다. 게시하면 변경 불가능한 버전이 생성되며, 이 버전을 머신에 배포할 수 있습니다. - ![변경 불가능한 버전으로 게시할 준비가 된 데모 정책이 표시된 Policy editor 작성 화면.](/images/dashboard/policy-editor.png) + ![게시 준비가 된 데모 정책이 표시된 Policy editor 작성 화면.](/images/dashboard/policy-editor.png) - **Admin → enforcement**로 이동하여 대상 머신을 펼치고 **edit this machine**을 선택합니다. 게시된 데모 정책을 추가하고 버전을 고정한 다음, **observe**를 선택하고 배포를 적용합니다. + **Admin → enforcement**로 이동하여 대상 머신을 펼치고 **edit this machine**을 선택합니다. 게시된 데모 정책을 추가하고, 버전을 고정한 후 **observe**를 선택하고 배포를 적용합니다. - ![배포를 적용하기 전, 관찰 모드에서 게시된 정책 버전이 선택된 머신 배포 편집기.](/images/dashboard/enforcement-editor.png) + ![배포 적용 전에 observe 모드로 게시된 정책 버전이 선택된 머신 배포 편집기 화면.](/images/dashboard/enforcement-editor.png) - 해당 머신에서 새 에이전트 세션을 실행한 다음, **Observe → policy**를 엽니다. 머신을 선택하고 데모 정책이 정책 매핑 및 결정 타임라인에 표시되는지 확인합니다. 관찰 모드는 실제로 동작을 차단하지 않고 정책이 어떻게 동작할지를 기록합니다. + 해당 머신에서 새 에이전트 세션을 실행한 후 **Observe → policy**를 엽니다. 머신을 선택하고 데모 정책이 정책 매핑 및 결정 타임라인에 표시되는지 확인합니다. Observe 모드는 실제로 동작을 차단하지 않고, 정책이 어떻게 작동할지를 기록합니다. - ![결정 총계, 시간 경과에 따른 적용 활동, 로컬 및 클라우드 관리 정책 매핑을 보여주는 Policy 페이지.](/images/dashboard/policy-observe.png) + ![결정 합계, 시간별 실행 활동, 로컬 및 클라우드 관리 정책 매핑이 표시된 Policy 페이지.](/images/dashboard/policy-observe.png) - 클라우드 정책 작성 및 플릿 배포는 관리자 워크플로입니다. 로컬 CLI를 사용하여 게시하기 전에 동일한 정책을 검증할 수 있습니다: + 클라우드 정책 작성 및 플릿 배포는 관리자 워크플로우입니다. 로컬 CLI를 사용하여 게시하기 전에 동일한 정책을 검증하세요: ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -35,13 +35,13 @@ icon: "shield-check" failproofai config --status ``` - `fp`를 사용하여 클라우드에 표시되는 정책 결정을 검사하세요: + `fp`를 사용하여 클라우드에서 확인 가능한 정책 결정을 검사합니다: ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - 클라우드 CLI는 루트 전용 적용 배포 경로를 노출하지 않습니다. **Admin → policy editor**에서 버전을 게시하고 **Admin → enforcement**에서 배포하세요. + 두 단계 모두 CLI에서도 사용할 수 있습니다. `fp policies publish `로 버전을 생성하고, `fp fleet deploy --add `로 머신에 배포합니다. 대시보드에서는 **Admin → policy editor**와 **Admin → enforcement**를 통해 동일한 작업을 수행할 수 있습니다. \ No newline at end of file diff --git a/docs/ko/start/integrations.mdx b/docs/ko/start/integrations.mdx new file mode 100644 index 000000000..80e471aa2 --- /dev/null +++ b/docs/ko/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "에이전트 계측하기" +sidebarTitle: "프레임워크" +description: "지원되는 에이전트 프레임워크를 Failproof AI에 한 번의 호출로 연결하세요." +icon: "plug" +--- + +에이전트는 이미 기록할 가치가 있는 모든 것을 생성합니다 — 모델 호출, 툴 호출, 노드 경계, 사람의 대기, 실패. 프레임워크는 이를 버립니다. SDK는 이를 보존합니다. + + + + 직접 작성한 에이전트이거나 여기에 나열되지 않은 에이전트. + + + 그래프, 노드, 툴, 리트리버, 모델. + + + 크루, 플로우, 역할별 에이전트, 툴. + + + 워크플로우, 스텝, 함수 에이전트, 리트리버. + + + 타입 에이전트, 기능, 툴, 재시도. + + + +## 어떤 프레임워크든 세 줄이면 됩니다 + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # 임포트한 프레임워크를 자동으로 감지합니다 + +with failproofai_sdk.session(): + ... # 기존 에이전트 호출 코드, 변경 없음 +``` + +함수에 데코레이터를 달거나, 호출에 콜백을 전달하거나, 코드 전체에 ID를 삽입할 필요가 없습니다. 달라지는 것은 세션 안의 호출뿐입니다: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # `async with failproofai_sdk.session():` 내부에서 + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +추가 설치는 **프레임워크** 자체를 위한 것입니다. 모든 어댑터는 기본 패키지에 포함되어 있으므로, 이미 프레임워크가 설치된 프로젝트는 추가 패키지가 전혀 필요하지 않습니다. + +## 수집 확인하기 + +계측된 세션을 한 번 실행한 후 **Observe → Sessions**를 열고 환경을 선택하세요. 실행 결과가 재구성된 트레이스로 나타납니다. + +아무것도 도착하지 않는다면 `failproofai config --status`로 머신이 연결되어 있는지 확인하세요. [캡처 설정](/ko/start/setup)을 참고하세요. + + + 스풀 디렉토리를 확인해서 전달 여부를 판단하지 마세요. Failproof 데몬은 각 배치를 수 밀리초 내에 수집하고 삭제하므로, 이를 읽으면 수집기와 경쟁 상태가 발생해 실제로 생성된 이벤트보다 훨씬 적게 표시됩니다. + + +## 다음 단계 + +위의 각 퀵스타트는 해당 전체 가이드로 연결됩니다 — 기록되는 항목, 옵션, 스트리밍, 스팬 이름 지정, 그리고 실제로 자주 발생하는 문제들을 다룹니다. 이 가이드들은 **Trace Agents → Plug in your agent** 아래에 있습니다. + + + + 데이터 모델, ID, 이벤트 타입, 그리고 이벤트가 Cloud에 도달하는 방법. + + + 단절된 로그 대신 세션 전체의 인과 관계를 따라가세요. + + + 방금 캡처한 세션을 감사하세요. + + \ No newline at end of file diff --git a/docs/ko/start/integrations/crewai.mdx b/docs/ko/start/integrations/crewai.mdx new file mode 100644 index 000000000..6b9dbfaf2 --- /dev/null +++ b/docs/ko/start/integrations/crewai.mdx @@ -0,0 +1,224 @@ +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "역할, 도구, 메모리, 사람 피드백 기반으로 크루, 플로우, 에이전트를 계측합니다." +icon: "/images/frameworks/crewai.svg" +--- + +## 설치 + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +지원 버전: `crewai` 1.13 ~ 2.0. 1.13은 `started_event_id`를 추가하고 토큰 사용량을 정규화한 릴리스로, 어댑터가 이벤트를 쌍으로 묶고 토큰을 보고하는 데 의존하는 두 기능이 모두 포함되어 있습니다. + +## 계측 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()`는 CrewAI의 모듈 수준 이벤트 버스에 리스너를 등록하고 이벤트 클래스마다 하나의 핸들러를 구독합니다. 크루, 에이전트, 태스크, 도구는 아무것도 변경되지 않습니다. + +## 기록되는 항목 + +| CrewAI | Failproof 이벤트 | +| --- | --- | +| 크루 킥오프 | `agent_start`, `agent_end` | +| `Agent.kickoff()` (크루 없는 단독 에이전트) | `agent_start`, `agent_end`, 역할에서 가져온 `agent_id` | +| 플로우 시작 및 종료 | `agent_start`, `agent_end`; 플로우 메서드 내에서 킥오프된 크루는 그 아래에 중첩됨 | +| 에이전트 실행 | 중첩된 `agent_start`, `agent_end`, 역할에서 가져온 `agent_id`. 계층적 프로세스에서 위임된 동료는 매니저 옆이 아니라 그 아래에 중첩됨 | +| 태스크 | 없음; 자식이 크루로 귀결되도록 링크로 기록됨 | +| 플로우 메서드, 가드레일 | `hook_triggered`, `hook_completed` | +| 도구 사용 | `tool_use`, `tool_result` | +| 메모리 및 지식 작업 | `tool_use`, `tool_result`, 히트한 표면 이름으로 명명됨 | +| LLM 호출 | `model_request`, `model_response`, 토큰 사용량 포함 | +| 스트림 청크 | 청크 수 및 첫 번째 토큰까지의 시간으로 응답에 통합됨 | +| 사람 피드백 요청됨 | `human_wait`, `agent_pause` | +| 사람 피드백 수신됨 | `agent_resume`, `human_input` | +| 에이전트 실행 오류 | `error`, 이후 결과가 `failed`인 `agent_end` | + +태스크는 의도적으로 아무것도 발행하지 않습니다. CrewAI 태스크는 이를 실행하는 에이전트 실행의 하위 집합이므로, 둘 다 발행하면 모든 행이 중복되고 형제 관계로 표시됩니다. 태스크 id와 이름은 에이전트 자체 이벤트에 함께 포함됩니다. + +메모리 및 지식 작업은 히트한 표면 이름으로 명명된 도구로 기록되므로, 실제 도구 옆에 표시되어 레이턴시를 비교할 수 있습니다. + +계층적 크루에서는 중첩 구조가 트레이스를 읽기 쉽게 만듭니다: + +```text +crew +└─ manager + ├─ researcher delegated + └─ writer delegated +``` + +CrewAI는 위임된 실행을 매니저에 직접 연결하지 않고 `delegate_work_to_coworker` **도구 이벤트**에 연결하므로, 어댑터는 해당 링크를 따릅니다. 이것 없이는 모든 에이전트가 서로 형제 관계로 나타나 위임 구조가 사라집니다. + +## 예제 + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # becomes agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +트레이스에서 핸드오프가 명확히 보입니다: `analyst` 스팬이 닫히고 `writer` 스팬이 열리며, 둘 다 하나의 `crew` 스팬 안에 위치합니다. + +## 스팬 이름 지정 + +`agent_id`는 `Agent(role=...)`에서 가져오며, 이것이 대시보드 패싯을 읽기 쉽게 만드는 요소입니다. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # 실행마다 별도의 패싯 항목 생성 +``` + +`agent_id`는 카디널리티가 낮은 컬럼입니다. 실행 id나 타임스탬프가 포함된 역할은 모든 쿼리의 성능을 저하시킵니다. 역할이 id처럼 보이면 어댑터는 이를 거부하고 실제 값을 페이로드 필드에 대신 저장합니다. + +## 세션 제어 + +다음 순서로 결정되며, 첫 번째로 일치하는 항목이 사용됩니다: + +1. `instrument("crewai", session_id=...)` +2. 감싸고 있는 `failproofai_sdk.session()` 스코프 +3. 크루 또는 플로우 단위로 생성된 `uuid4().hex` + +실행별로 세션을 제어하려면 킥오프를 다음과 같이 감쌉니다: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## 옵션 + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # 모든 실행을 하나의 세션 id에 고정 +) +``` + +`session_id`는 이 어댑터가 읽는 유일한 옵션입니다. 프롬프트와 완성 결과는 항상 기록되며, 페이로드 한도에 맞게 잘립니다. + +## 사람 참여 루프 + +CrewAI에는 **두 가지** 사람 참여 루프 방식이 있으며, 둘 다 동일한 네 가지 이벤트로 기록됩니다. + +플로우 메서드의 `@human_feedback`은 CrewAI의 이벤트 버스를 통해 처리됩니다: 런타임이 사람의 입력을 기다리기 전에 이벤트를 발행하고, 답변을 받은 후 또 다른 이벤트를 발행합니다. + +`Task(human_input=True)`는 그렇지 않습니다. CrewAI 자체의 입력 프로바이더 내에서 `input()`을 호출하며 어떠한 이벤트도 발행하지 않으므로, 어댑터는 해당 프로바이더를 직접 감쌉니다 — 이것 없이는 전체 사람 대기 시간이 보이지 않고 활성 에이전트 시간으로 청구됩니다. + +어느 방식이든 다음과 같이 기록됩니다: + +```text +human_wait 프롬프트와 옵션 +agent_pause 일시 정지 시간 측정 시작 +agent_resume 측정 종료 +human_input 답변 및 측정된 대기 시간 +``` + +`agent_pause`에서 `agent_resume`까지만 일시 정지 시간으로 집계됩니다. 이것 없이는 10분간의 사람 대기 시간이 10분의 활성 에이전트 시간으로 청구됩니다. + + + CrewAI는 두 사람 피드백 이벤트 모두에 상관 관계 id를 설정하지 않으므로, 어댑터는 플로우와 메서드 이름으로 이벤트를 쌍으로 묶고, 가장 최근에 열린 일시 정지를 폴백으로 사용합니다. 콘솔 프롬프트가 블로킹되므로 이 방식은 안전합니다. 동시 피드백 프로바이더를 구축하는 경우 두 이벤트 모두에 `request_id`를 설정하세요. + + + + `Task(human_input=True)` 경로는 이벤트 구독이 아닌 CrewAI의 입력 프로바이더를 감싸는 방식이기 때문에, `uninstrument()` 시 복원되며 `input()`이 발생시키는 모든 예외(예: `KeyboardInterrupt` 포함)를 그대로 다시 발생시킵니다. + + +## 자주 발생하는 문제 + + + + `role`에 UUID, 타임스탬프 또는 실행별 접미사가 포함되어 있습니다. 안정적인 사람이 읽을 수 있는 역할을 사용하고, 실행별 id는 태스크 설명에 넣으세요. + + + + 이벤트 버스는 비동기식이며, `kickoff()`는 마지막 핸들러가 실행되기 전에 반환됩니다. 먼저 드레인하세요: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + 이것은 SDK가 아닌 CrewAI의 특성입니다. + + + + `agent_end`는 열려 있는 일시 정지를 강제 종료하지만 도구나 모델은 그렇지 않습니다. 따라서 도구 호출 중에 실행이 중단되면 해당 스팬이 열린 채로 남습니다. 일반적인 종료 시 열려 있는 모든 항목이 닫히고 불완전으로 표시됩니다. `SIGKILL`의 경우에만 아무것도 실행될 수 없으므로 스팬이 열린 채로 남습니다. + + + + 다음 순서로 확인하세요: `instrument()`가 `kickoff()` 이전에 실행되었는지; `with failproofai_sdk.session():`으로 감싸져 있는지; `crewai`가 1.13 이상인지; `FAILPROOFAI_SDK_STRICT=1`이 설정되어 있으면 저하된 훅이 무시되는 대신 예외를 발생시킵니다. + + + +## 다음 단계 + + + + 페어링, id, 세션 생명주기, 전달 방식. + + + 방금 캡처한 세션을 통해 인과 관계를 추적합니다. + + + LangGraph, LlamaIndex, Pydantic AI, 커스텀 에이전트. + + \ No newline at end of file diff --git a/docs/ko/start/integrations/custom-agents.mdx b/docs/ko/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..4fea8d3c6 --- /dev/null +++ b/docs/ko/start/integrations/custom-agents.mdx @@ -0,0 +1,737 @@ +--- +title: "커스텀 에이전트" +sidebarTitle: "커스텀 에이전트" +description: "직접 작성한 에이전트나 어댑터가 없는 프레임워크에 계측을 적용하세요." +icon: "code" +--- + +직접 작성한 에이전트나 Failproof AI에 어댑터가 없는 프레임워크에 사용합니다. 별도로 계측할 것은 없습니다. 이벤트를 직접 발행하면 됩니다. + +이는 네 가지 프레임워크 어댑터가 내부적으로 호출하는 것과 동일한 API입니다. 어댑터들은 이 API에 대한 변환 테이블입니다. + +## 설치 + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # 하나의 도구 호출 +``` + +위에서 아래로 읽으면 그 의미가 그대로 드러납니다: + +| 감싸는 것 | 의미 | +| --- | --- | +| `session()` | 이 이벤트들은 동일한 실행에 속합니다 | +| `agent()` | 무언가 작업을 수행하고 있습니다 — 목록에서 알아볼 수 있는 이름을 붙이세요 | +| `tool_call()` | 이것은 하나의 도구이며, 반환한 값입니다 | + +각각이 실제로 발행하는 이벤트: + +| 스코프 | 발행 이벤트 | 목적 | +| --- | --- | --- | +| `session()` | 없음 | 세션 id를 바인딩하여 하나의 실행을 그룹화합니다 | +| `agent()` | `agent_start`, `agent_end` | 작업 단위를 괄호로 묶습니다 | +| `tool_call()` | `tool_use`, `tool_result` | 하나의 도구를 괄호로 묶고 측정합니다 | + +내부의 모든 코드는 `session_id`와 `agent_id`를 생략할 수 있습니다. 스코프는 컨텍스트 변수에 식별자를 바인딩하며, 모든 이벤트 호출이 이를 읽어오므로 함수를 통해 id를 전달할 필요가 없습니다. + +세 가지 모두 `with`뿐만 아니라 `async with`에서도 동작합니다. + +에이전트를 중첩하면 트리가 만들어집니다. `parent_id`와 깊이는 스택에서 자동으로 계산됩니다: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## 스코프가 닫히는 방식 + +`agent()`는 예외를 자동으로 처리합니다: + +| 발생한 상황 | 이벤트 | 결과 | +| --- | --- | --- | +| 예외 없음 | `agent_end` | `success` | +| `Exception` | `error`, 이후 `agent_end` | `failed` | +| `KeyboardInterrupt`, `SystemExit` | `error`, 이후 `agent_end` | `failed` | +| `CancelledError`, `GeneratorExit` | `agent_end`만 | `cancelled` | + +`agent_end` 이전에 오류가 발행되는 이유는, 대시보드가 `agent_end`에서 스팬을 닫고 그 이후의 이벤트는 아무것에도 귀속되지 않기 때문입니다. 취소는 실패가 아니므로 취소된 실행은 오류 목록을 오염시키지 않습니다. 예외는 항상 다시 발생됩니다. 스코프는 예외를 삼키지 않습니다. + +## 이벤트 메서드 + +여섯 가지 계열에 걸쳐 열다섯 가지 메서드가 있습니다. 대부분은 쌍으로 이루어져 있으며, 여는 이벤트를 발행한 뒤 닫는 이벤트를 발행하면 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` | +| **실패** | — | — | `error` | + + + 가능하면 `agent()`와 `tool_call()` 스코프를 사용하세요. 본문에서 예외가 발생해도 닫는 이벤트를 보장합니다. 제어 흐름이 중첩되지 않는 경우, 예를 들어 헬퍼 함수 내부의 모델 호출처럼 스코프가 맞지 않을 때는 이벤트 메서드를 직접 사용하세요. + + + +```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 Models +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 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 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 Failures +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **두 가지 사람 관련 계열은 방향이 반대입니다.** + + | 메서드 | 의미 | + | --- | --- | + | `human_wait` / `human_input` | **에이전트가 사람에게 요청** — 승인 게이트, 확인 질문 | + | `human_pause` / `human_interrupt` | **사람이 에이전트에 개입** — 중지 버튼, 운영자 일시 정지 | + + 두 번째 쌍은 어떤 프레임워크도 신호를 보내지 않으므로, 항상 직접 발행해야 합니다. + + + + **모델 호출이 동시에 실행될 때는 `request_id`를 전달하세요.** 전달하지 않으면 에이전트별로 요청과 응답이 도착 순서대로 쌍을 이루기 때문에, 동시 호출 시 잘못된 요청에 응답이 연결될 수 있습니다. + + +## 예시 + +에이전트 프레임워크 없이 OpenAI API를 사용하는 도구 호출 루프: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +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 + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +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 + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +이 코드는 어댑터가 생성하는 것과 동일한 여섯 가지 이벤트 타입을 생성합니다. 도구 정의를 포함한 완전히 실행 가능한 버전은 SDK 저장소의 `docs/manual/examples/` 경로에 포함되어 있습니다. + +## 스레드와 비동기 + +컨텍스트 변수는 asyncio 태스크에 자동으로 전파됩니다. 하지만 새 스레드는 빈 컨텍스트로 시작하기 때문에 스레드로는 자동 전파되지 않습니다. + +```python +# asyncio: 별도 작업 불필요 +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# 스레드: 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`으로 응답되는데, 이는 식별자 레이어가 방지하려는 무음 실패이기 때문입니다. + +## 어댑터 없이 프레임워크 계측하기 + +모든 에이전트 프레임워크는 동일한 세 가지 연결 지점을 제공합니다. 이를 매핑하면 완전한 트레이스를 얻을 수 있습니다. 출시된 네 가지 어댑터도 이것 이상을 하지 않습니다. + +| 연결 지점 | 작성할 코드 | 생성되는 이벤트 | +| --- | --- | --- | +| 실행 | `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: + call.output = original(**args) + ``` + + + ```python + failproofai_sdk.event.model_request(model=model, messages=messages) + reply = provider.complete(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **노드, 스텝, 미들웨어 경계를 추적하고 싶다면?** 중첩된 `agent()` 대신 훅 쌍(`hook_triggered` / `hook_completed`)으로 감싸세요. `agent_id`는 저기수성 패싯이라 노드마다 항목이 생기면 목록이 넘쳐납니다. 훅 스팬은 동일하게 렌더링되면서 노드별 레이턴시를 제공합니다. + + + + **수동 계측과 자동 계측은 함께 동작합니다.** 직접 작성한 스코프 안에서 실행되는 어댑터는 해당 세션에 참여하고 해당 에이전트의 하위에 위치하므로, 두 개의 트리가 아닌 하나의 트리를 얻을 수 있습니다. 지원되는 프레임워크와 함께 다른 프레임워크를 직접 계측할 때 유용합니다. + + + + 두 가지 이유가 있으며, 위의 세 가지 연결 지점이 두 경우 모두에 대한 답입니다: + + - `autogen-core`는 2025년 9월 이후 유지 관리가 중단되었습니다. + - AG2는 다른 프레임워크들의 훅에 해당하는 프로세스 수준의 등록 지점을 제공하지 않기 때문에, 계측하려면 에이전트를 생성하는 모든 위치에서 래핑해야 합니다. + + 연결 지점을 직접 매핑하면 출시된 어댑터와 동일한 이벤트를, 동일한 정밀도로 기록할 수 있습니다. + + +## 더 깊이 알아보기 + +레코딩이 실제로 동작하는 방식입니다. 시작하는 데 필요한 내용은 아닙니다. + + + + + +모든 레코딩은 동일한 형태를 가집니다. 스팬이 열리고, 그 안에 작업이 중첩되며, 각 열린 이벤트에 닫는 이벤트가 생깁니다. + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + C --> E(["agent_end"]) +``` + +**쌍**이 기본 단위입니다. 각 닫는 이벤트는 SDK가 여는 이벤트부터 측정한 지속 시간을 가집니다. + +아래는 프레임워크별 실제 실행 결과입니다. SDK와 함께 제공되는 예시에서 캡처했으며 모델 이름은 정규화했습니다. 단 한 번의 호출에서 얼마나 많은 정보가 반환되는지 확인해 보세요. + + + + ```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 out-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 14 +5.721s agent_end LangGraph · success + ``` + + 노드가 훅 쌍이 되므로, 에이전트 목록을 복잡하게 만들지 않고도 노드별 레이턴시를 얻을 수 있습니다. + + + + ```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 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 out-tok + 9 +5.727s agent_end analyst · success + 10 +5.739s agent_end crew · success + ``` + + 각 에이전트의 `role`이 스팬 이름이 되므로, 레이턴시와 토큰 사용량을 역할별로 분석할 수 있습니다. + + + + ```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 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 + ... second iteration + 26 +7.038s agent_end Agent · success + ``` + + 에이전트 루프 자체가 보이며, 모델 호출만 보이는 것이 아닙니다. + + + + ```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 + 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 + 8 +8.119s agent_end agent · success + ``` + + 훅 쌍 없음: Pydantic AI에는 괄호로 묶을 노드나 스텝 경계가 없습니다. + + + + ```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 out-tok + 6 +0.000s agent_end main · success + ``` + + 직접 발행합니다. 동일한 이벤트 타입, 동일한 정밀도 — 호출 위치를 직접 작성하는 비용이 있습니다. + + + + + + + +**세션 종료 이벤트는 없습니다.** 세션은 닫는 것이 아니라, `session_id`를 공유하는 이벤트들의 그룹입니다. + +상태는 트레이스의 형태에서 도출됩니다: + +| 상태 | 조건 | +| --- | --- | +| `ongoing` | 적어도 하나의 스팬이 아직 열려 있음 | +| `paused` | `agent_pause`에 대응하는 `agent_resume`이 없음 | +| `error` | 열린 스팬이 없고, 적어도 하나의 이벤트가 실패함 | +| `done` | 열린 스팬이 없고, 실패한 이벤트도 없음 | + +즉, 모든 쌍이 닫히면 세션이 종료됩니다. 어댑터는 `agent_end`를 자동으로 발행하며, 종료 시 아직 열려 있는 것들을 닫고 불완전으로 표시합니다. 충돌한 실행은 보이는 공백과 함께 `done`으로 정리되며 영원히 대기 상태로 남지 않습니다. + + + 이것이 세션이 두 번의 호출에 걸쳐 있을 수 있는 이유입니다. LangGraph의 `interrupt()`는 실행을 일시 정지하고, 루트 스팬은 의도적으로 열린 상태를 유지하며, 재개하는 호출이 그것을 닫습니다. 두 호출은 하나의 세션입니다. + + + + + + +`session_id`와 `agent_id`는 모든 이벤트 메서드에서 선택 사항입니다. 생략하면 감싸는 스코프에서 해결됩니다: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") +``` + +명시적으로 전달하면 여전히 동작하며 우선순위를 가집니다. 바인딩된 것도 없고 전달된 것도 없으면, 세션 없이 이벤트를 발행하는 대신 수정 방법을 알려주는 `TypeError`가 발생합니다. 세션 없는 이벤트는 인제스트에서 건너뛰어지고 `200`으로 응답됩니다. + +스코프는 컨텍스트 변수에 식별자를 바인딩합니다. 이는 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** | **클라우드, 인제스트 시** | SDK는 발행하지 않음 | +| **`dedup_key`** | **클라우드, 인제스트 시** | 조직, 세션, 타임스탬프, 타입, 페이로드의 해시. 이것이 실제 식별자로, 재시도된 배치가 중복 대신 하나로 합쳐지게 함 | + +#### 어댑터가 `session_id`를 해결하는 방식 + +첫 번째 매칭이 우선: + +1. 명시적인 `session_id` 옵션 +2. 호출별 메타데이터 +3. 감싸는 `session()` 스코프 +4. 프레임워크 메타데이터 +5. 프레임워크 자체 실행 id + +이 중 하나가 존재하는 동안에는 임의로 생성되지 않습니다. 합성된 id는 하나의 실행을 여러 세션으로 분리하게 됩니다. + +#### `agent_id`는 저기수성으로 유지하세요 + +모든 대시보드 화면의 주요 패싯이며 `LowCardinality(String)` 컬럼입니다. 실행별 값을 사용하면 컬럼 성능이 저하되고 필터 드롭다운에 실행마다 하나씩 항목이 쌓입니다. + +어댑터는 이 컬럼을 자동으로 보호합니다: + +| 프레임워크가 전달한 값 | 기록되는 값 | 이유 | +| --- | --- | --- | +| `3f9a1c2b-…` (UUID) | `main` | 보존할 읽기 가능한 부분 없음 | +| 긴 순수 16진수 문자열 | `main` | 동일 | +| `agent-3f9a1c2b-…` | `agent` | 실행별 id 제거, 읽기 가능한 부분 유지 | +| `agent-v2` | `agent-v2` | 짧은 세그먼트는 그대로 유지 | +| `step-3` | `step-3` | 동일 | + +실제 id는 `fw_agent_id` / `fw_run_id`에 보존되어 패싯이 되지 않으면서도 쿼리 가능합니다. + + + **이 보호는 프레임워크가 선택한 레이블에만 적용됩니다.** `event.*` 또는 `failproofai_sdk.agent(...)`에 직접 전달한 `agent_id`는 그대로 기록됩니다. 명시적인 인자를 조용히 재작성하는 것은 방지하려는 기수성 문제보다 더 나쁘기 때문입니다. 직접 작성하는 스팬 이름에 주의하세요. + + + + + + +| 그룹 | 이벤트 | +| --- | --- | +| 에이전트 | `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 | 커스텀 | +| --- | :--: | :--: | :--: | :--: | :--: | +| 에이전트 시작/종료 | 예 | 예 | 예 | 예 | 직접 | +| 모델 요청/응답 | 예 | 예 | 예 | 예 | 직접 | +| 도구 사용/결과 | 예 | 예 | 예 | 예 | 직접 | +| 훅 시작/완료 | 노드 | 태스크 | 스텝 | — | 직접 | +| 오류 | 예 | 예 | 예 | 예 | 자동 | +| 사람 대기/입력 | 예 | 예 | 예 | — | 직접 | +| 에이전트 일시정지/재개 | 예 | 예 | 예 | — | 직접 | + +대시(—)는 프레임워크에 해당 개념이 없음을 의미합니다. `human_pause`와 `human_interrupt`는 에이전트에 _사람_이 개입하는 것을 나타내며, 어떤 프레임워크도 신호를 보내지 않으므로 직접 발행해야 합니다. + + + + + +이벤트는 단독으로 도착하지 않습니다. 하나가 스팬을 열고, 하나가 닫으며, 닫는 이벤트는 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` | 응답, 응답까지 걸린 시간 | + + + 닫는 이벤트가 없는 여는 이벤트는 영원히 끝나지 않는 스팬입니다. 세션은 계속 실행 중으로 표시되고 활성 지속 시간이 계속 증가합니다. 이것이 수동 계측 시 주의해야 할 실패 패턴입니다. + + +#### 상관관계 규칙 + +- 매칭되는 완료 이벤트에 동일한 `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 # 표준 라이브러리 외 아무것도 로드하지 않음 +failproofai_sdk.instrument() # 실제로 필요한 어댑터만 임포트 +``` + +`import failproofai_sdk`는 계약상 의존성이 없으며, `--no-deps`로 빌드된 wheel을 설치하는 테스트와 어떤 프레임워크도 `sys.modules`에 없음을 증명하는 테스트로 강제됩니다. + + + `failproofai_sdk.crewai` 속성은 없습니다. 어댑터는 의도적으로 최상위 패키지에 노출되지 않습니다. 하나를 건드리면 속성 접근의 부작용으로 프레임워크가 임포트되어 의존성 없음 약속이 깨집니다. `instrument()`를 사용하세요. + + +```python +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`를 읽으므로, 설치했지만 임포트하지 않은 프레임워크는 계측되지 않으며 임의로 임포트되지도 않습니다. 현재 연결된 것을 확인하려면: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +active() # ('langchain',) +``` + + + **CrewAI가 없는 머신에서 `instrument("crewai")`를 호출해도 예외가 발생하지 않습니다.** 경고를 로그에 남기고 `()`를 반환하므로, 하나의 프레임워크가 없어도 다른 프레임워크를 계측하는 프로세스가 중단되지 않습니다. + + 경고에는 기본 `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`을 설정하세요. 이 플래그는 **한 번 읽히고 캐시되므로**, 실행 중에 설정하지 말고 프로세스 시작 전에 내보내세요. + + + + **`instrument()`는 프레임워크 임포트 *이후*에 와야 합니다.** 자동 탐지는 `sys.modules`를 읽으므로, 임포트 전에 빈 호출을 하면 아무것도 찾지 못하고, 아무것도 설치하지 않고, `()`를 반환합니다. + + + +```python Wrong +import failproofai_sdk +failproofai_sdk.instrument() # sys.modules에 langchain 없음 -> () + +import langchain # 너무 늦음, 아무것도 연결되지 않음 +``` + +```python Right +import langchain # 프레임워크를 먼저 임포트 +import failproofai_sdk + +failproofai_sdk.instrument() # 찾음 -> ('langchain',) +``` + +```python Right, order-proof +import failproofai_sdk + +# 이름으로 지정하면 요청 시 어댑터를 임포트하므로 어디서든 동작합니다. +failproofai_sdk.instrument("langchain") +``` + + +잘못하면 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"] +``` + +| 단계 | 역할 | 실행 위치 | +| --- | --- | --- | +| 어댑터 | 프레임워크 콜백을 15가지 이벤트 타입 중 하나로 변환 | 사용자 프로세스 | +| 라이터 | 큐에 넣고, 배치로 묶어, JSONL을 원자적으로 쓰기 | 사용자 프로세스, 백그라운드 스레드 | +| 스풀 | 프로세스 종료에도 살아남는 내구성 있는 전달 지점 | 로컬 디스크 | +| 데몬 | 스풀을 감시하고, 배치를 전송하고, 전송한 것을 삭제 | 사용자 머신 | +| 인제스트 | 행 id와 dedup 키를 부여하고, 쿼리 가능한 컬럼으로 승격 | 클라우드 | + +스풀이 안전성의 핵심입니다. 에이전트는 네트워크에서 절대 차단되지 않으며, 클라우드 장애 시 이벤트가 유실되는 대신 디렉터리가 커집니다. + +각 플러시는 하나의 배치 파일을 씁니다. `.tmp`로 먼저 쓰고, `fsync`한 뒤, 원자적으로 이름을 변경합니다: + +```text +~/.failproofai/custom-agents/events/ + event-2026-08-20T10-15-00-123Z-48213-0.jsonl +``` + +데몬은 `.jsonl`만 읽으므로 절반만 쓰인 파일을 읽을 수 없습니다. 파일명에 타임스탬프, 프로세스 id, 시퀀스 번호가 포함되어 있어 두 프로세스가 같은 밀리초에 플러시해도 충돌하지 않습니다. 큐는 10,000개 이벤트로 제한되며, 초과 시 가장 오래된 것을 삭제하고 로그를 남깁니다. + + + **`collector.redact`는 SDK 이벤트에 적용되지 않습니다.** 절대 해당 이벤트를 볼 수 없습니다. + + +데몬은 배치를 **전송**합니다. 열거나 다시 쓰지 않습니다. + +| 이벤트 | 작성자 | `collector.redact` 적용 여부 | +| --- | --- | --- | +| CLI 세션 트랜스크립트 | 데몬 | 예 | +| 훅 활동 | 데몬 | 예 | +| **SDK가 발행하는 모든 것** | **사용자 프로세스** | **아니오** | + +리댁션은 데몬이 자체 이벤트를 *쓰는* 곳에서 실행됩니다. 배치가 *전송*되는 곳이 아닙니다. 따라서 API 키를 포함한 프롬프트나 도구 인자는 도착 시에도 그대로입니다. + +이는 의도적입니다. 이것은 사용자 자신의 계측 호출이며, 전송 중에 이를 재작성하면 받은 이벤트가 발행한 이벤트와 다르게 됩니다. + + + **페이로드는 소스에서 두 곳에서 제어할 수 있습니다:** + + - 어댑터에서 콘텐츠 캡처를 끄세요. **옵션 이름이 다르며, 하나의 어댑터에는 옵션이 없습니다.** 이것은 단일 범용 스위치가 아닙니다: + - LangChain / LangGraph, Pydantic AI — `capture_content=False` + - LlamaIndex — `capture_messages=False` + - CrewAI — **콘텐츠 스위치 없음**; `session_id`가 읽는 유일한 옵션이므로 프롬프트와 완성은 항상 기록됩니다. + + `instrument()`는 어댑터가 읽지 않는 옵션을 무시하므로, 잘못된 이름을 전달해도 오류 없이 아무 변화도 없습니다. + - 처음부터 `input=`에 비밀을 전달하지 마세요. + + `collector.redact`는 두 경우 중 어느 것도 대체하지 않습니다. + + + + **빈 스풀 디렉터리가 정상 상태입니다.** 전달 여부 확인에 사용하지 마세요. + + +데몬은 각 배치를 전송 후 수 밀리초 내에 삭제하므로, `ls`를 실행하면 수집기와 경쟁하게 되어 발행한 것의 일부만 보입니다. 아무것도 기록하지 않은 SDK와 구분할 수 없습니다. + +이벤트가 실제로 도달했는지 확인하려면 대시보드를 확인하세요. 스풀이 채워지는 것을 관찰하려면 먼저 데몬을 중지하세요. + + + + + +모든 콜백은 재발생만을 담당하는 래퍼 안에서 실행됩니다. 따라서 호출은 정확히 하나의 `try` 안에 있고, SDK가 하는 모든 것은 그 밖에서 일어납니다. + +| 발생한 상황 | 결과 | +| --- | --- | +| 훅이 예외 발생 | 트레이스백과 함께 한 번 로그됨. 호출에는 영향 없음 | +| 같은 훅이 세 번 예외 발생 | 해당 훅만 프로세스 나머지 동안 비활성화, 오류 한 줄 | +| `FAILPROOFAI_SDK_STRICT=1` 설정됨 | 예외가 대신 다시 발생 | +| 프레임워크 버전이 테스트 범위 밖 | 한 번 경고, 그래도 계측 진행 | +| 단일 기능이 없음 | 해당 훅만 비활성화, 어댑터 전체는 아님 | + +기본값은 프로덕션에서는 맞고 디버깅 시에는 맞지 않습니다. "충돌하지 않았다"는 것만 증명할 수 있기 때문입니다. 삼켜진 실패를 드러내려면 `FAILPROOFAI_SDK_STRICT=1`을 설정하세요. + + + + + +## 자주 발생하는 문제 + + + + 여는 이벤트에 닫는 이벤트가 없는 경우입니다. `model_request`에 `model_response`가 없거나 `tool_use`에 `tool_result`가 없는 경우입니다. 본문에서 예외가 발생해도 쌍을 보장하는 스코프를 사용하세요. 이벤트 메서드를 직접 호출한다면 `try`와 `finally`를 사용하세요. + + + + 매칭되는 여는 이벤트부터 측정되므로, `tool_result`, `hook_completed`, `agent_resume`, `human_input`에서는 거부됩니다. `model_response`에서는 허용되며, 실제 프로바이더 레이턴시는 사용자만 알기 때문입니다. 정수여야 합니다. + + + + 스레드가 컨텍스트를 상속받지 못했습니다. callable을 `failproofai_sdk.propagate()`로 감싸세요. [스레드와 비동기](#threads-and-async)를 참고하세요. + + + + 추가 필드는 마지막에 병합되므로, `model`이나 `outcome` 같은 실제 필드와 같은 이름이면 덮어쓰고 저장된 컬럼을 변경합니다. 네임스페이스를 사용하세요. 어댑터는 `fw_` 접두사를 사용합니다. + + + + `agent_id`는 저기수성 패싯인데 실행 id를 넣었습니다. 역할이나 노드 이름을 사용하고 실제 id는 페이로드 필드에 넣으세요. + + + +## 다음 단계 + + + + 쌍, id, 세션 생명주기, 전달 방식. + + + 방금 캡처한 세션의 인과관계를 따라가세요. + + + LangGraph, CrewAI, LlamaIndex, Pydantic AI. + + \ No newline at end of file diff --git a/docs/ko/start/integrations/langchain.mdx b/docs/ko/start/integrations/langchain.mdx new file mode 100644 index 000000000..90c6dc225 --- /dev/null +++ b/docs/ko/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain and LangGraph" +sidebarTitle: "LangChain and LangGraph" +description: "한 번의 호출로 그래프, 노드, 도구, 리트리버, 모델 호출을 계측합니다." +icon: "/images/frameworks/langchain.svg" +--- + +하나의 어댑터로 둘 다 지원합니다. LangGraph는 `langchain-core`의 콜백 매니저 위에서 동작하므로, 하나를 계측하면 나머지도 함께 계측됩니다. + +## 설치 + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +LangGraph 없이 LangChain만 사용하는 경우에는 `failproofai-sdk[langchain]`을 사용하세요. + +지원 범위: `langchain-core` 1.4.7 ~ 2.0, `langgraph` 1.2 ~ 2.0. 이 범위를 벗어나도 어댑터는 설치되며 경고를 한 번 출력합니다. + +## 계측 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()`는 `langchain_core.tracers.context.register_configure_hook`를 통해 트레이서를 등록합니다. LangChain은 이를 생성하는 모든 콜백 매니저에 자동으로 주입하므로, 직접 작성하지 않은 라이브러리 내부의 그래프, 도구, 모델까지 호출 지점을 수정하지 않고도 캡처됩니다. + +## 기록되는 항목 + +| LangChain 또는 LangGraph | Failproof 이벤트 | +| --- | --- | +| 루트 실행 | `agent_start`, `agent_end` | +| LangGraph 노드 | `hook_triggered`, `hook_completed` | +| 컴파일된 서브그래프 | 중첩된 `agent_start`, `agent_end` | +| 도구 실행 | `tool_use`, `tool_result` | +| 리트리버 실행 | `tool_use`, `tool_result`, 출력 요약 포함 | +| 채팅 모델 또는 LLM 실행 | `model_request`, `model_response`, 토큰 사용량 포함 | +| 스트리밍 토큰 | 응답에 청크 수와 첫 토큰까지의 시간으로 합산됨. 토큰 수는 `ChatOpenAI(stream_usage=True)` 필요 — 아래 참조 | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, `Interrupt.id` 기준으로 연결 — 동일한 체크포인터를 대상으로 다른 프로세스에서 재개하는 경우 포함 | +| 처리되지 않은 예외 | `error`, 이후 outcome이 `failed`인 `agent_end` | + +**노드는 중첩 에이전트가 아닌 훅으로 처리됩니다.** `agent_id`는 모든 대시보드 화면에서 주요 구분자입니다. `retrieve`, `grade_documents`, `should_continue`를 에이전트로 승격하면 이 값이 범람하고, 가장 먼저 실행된 노드 이름이 세션 레이블이 되어버립니다. + +훅 스팬도 동일하게 렌더링되며, 노드별 지연 시간 뷰를 그대로 제공합니다. + + + **노드 이름은 자유롭게 지정하세요.** 노드 실행은 이름이 아닌 *형태* — LangGraph 자체 스텝 태그를 포함하는 리프가 아닌 실행 — 로 식별됩니다. + + +| 작성 코드 | 기록되는 항목 | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | 도구 | +| `add_node("ChatOpenAI", ...)` | 모델 호출 | + +노드를 실행하는 대상과 같은 이름으로 지정하면 해당 이벤트가 사라지던 문제는 더 이상 발생하지 않습니다. + +### 스트리밍 + +`.stream()`과 `.astream()`은 토큰별 이벤트를 발생시키지 않습니다. 최종 `model_response`에 다음과 같이 합산됩니다: + +| 필드 | 내용 | +| --- | --- | +| `fw_chunks` | 수신된 청크 수 | +| `fw_ttft_ms` | 첫 토큰까지의 시간 | + +### 스트리밍 응답의 토큰 수 + +별도로 처리해야 하는 사항으로, 놓치기 쉽습니다. OpenAI는 스트리밍 응답에서 **명시적으로 요청할 때만** 사용량을 전송합니다. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # 이 옵션 없이는 토큰 정보 없음 +``` + +어댑터는 프레임워크가 전달하는 값만 기록합니다. 해당 플래그 없이는 기록할 정보가 없으므로 `model_response`에 토큰 수가 포함되지 않습니다. + +## 예시 + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## 스팬 이름 지정 + +기본적으로 루트 스팬은 그래프 자체의 이름을 사용합니다. 원하는 레이블을 지정하려면 다음과 같이 래핑하세요: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +멀티 에이전트 구성의 경우 스코프를 중첩하세요. 각 워커는 `parent_id`를 가진 자식 스팬이 됩니다: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +`agent_id`는 낮은 카디널리티를 유지하세요. 역할이나 노드 이름을 사용하고, UUID나 실행별 문자열은 사용하지 마세요. + +## 세션 제어 + +세션 id는 다음 순서로 결정되며, 첫 번째로 매칭되는 항목이 사용됩니다: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. 감싸는 `failproofai_sdk.session()` 스코프 +4. `metadata["session_id"]`, `metadata["conversation_id"]`, 또는 `metadata["thread_id"]` +5. 루트 실행 id + +합성된 id는 하나의 실행을 여러 세션으로 분리하므로, id를 새로 생성하는 방식은 사용하지 않습니다. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## 옵션 + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # 모든 실행을 하나의 세션 id에 고정 + include_chains=set(), # 중간 체인을 훅 쌍으로 허용 목록에 추가 + capture_content=True, # False로 설정하면 페이로드에서 프롬프트와 완성 내용 제외 + graph_callbacks=True, # interrupt 및 resume 일급 처리, langgraph 1.2+ 필요 +) +``` + +규제 대상 데이터의 경우 `capture_content=False`로 설정하세요. 구조, 타이밍, 토큰 수, 도구 이름, 결과는 계속 기록되며 메시지 본문만 제외됩니다. + +`include_chains`는 **중첩된** 실행에만 적용됩니다. 최상위에서 직접 호출하는 runnable은 세션의 루트이므로 훅 쌍이 아닌 에이전트 스팬이 되며, 여기서 이름을 지정해도 효과가 없습니다. + +## 휴먼 인 더 루프 + +`interrupt()`는 네 가지 이벤트를 생성하며, 두 쌍 모두 중복이 아닙니다: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +`human_wait`에서 `human_input`까지는 프롬프트와 답변을 포함합니다(`capture_content=False` 시 리트리버 문서 출처와 함께 제외되지만 문서 수는 유지됨). `agent_pause`에서 `agent_resume`까지는 일시 정지 시간을 기록하는 유일한 쌍으로, 이 쌍이 없으면 10분간의 대기 시간이 활성 에이전트 시간으로 청구됩니다. 루트 스팬은 간격을 가로질러 열린 상태를 유지하며, 두 호출을 동일한 세션으로 묶습니다. + +## 자주 발생하는 문제 + + + + `create_react_agent`는 예외를 전파합니다. 모델이 실패를 인식하고 계속 진행하도록 하려면 도구 노드를 명시적으로 구성하세요: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + 어느 쪽이든 실패는 오류를 포함한 `tool_result`로 기록됩니다. 이 설정은 실행이 실패를 극복할 수 있는지만 결정합니다. + + + + 그래프 외부에서 직접 호출한 `llm.invoke()`는 부모 실행이 없으므로 루트 스팬을 열고 그 안에 모델 쌍을 기록합니다. 대시보드는 리프를 열린 에이전트의 자식으로 배치하므로 이 스팬은 의도된 동작입니다. 이름을 지정하려면: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + `instrument()`를 호출하면서 동시에 `config={"callbacks": [...]}`에 Failproof 핸들러를 전달했습니다. 핸들러를 제거하세요. configure 훅은 이미 프로세스 내 모든 콜백 매니저를 커버합니다. + + + + 그렇지 않습니다. LangGraph는 실제 예외와 동일한 경로로 `GraphInterrupt`를 발생시키므로, 모든 일시 정지는 트레이서에 오류 콜백으로 전달됩니다. 하지만 `GraphBubbleUp`의 모든 서브클래스는 제어 흐름으로 처리되므로, 승인은 빨간색 오류로 표시되지 않습니다. + + + + 다음 순서로 확인하세요: 그래프 실행 전에 `instrument()`가 호출되었는지; 호출을 감싸는 `with failproofai_sdk.session():`이 있는지; `FAILPROOFAI_SDK_STRICT=1`이 설정되어 있어 오류가 무시되지 않고 발생하는지. + + + +## 다음 단계 + + + + 쌍, id, 세션 라이프사이클, 전달 방식. + + + 방금 캡처한 세션에서 인과관계를 따라가 보세요. + + + CrewAI, LlamaIndex, Pydantic AI, 커스텀 에이전트. + + \ No newline at end of file diff --git a/docs/ko/start/integrations/llamaindex.mdx b/docs/ko/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..20d054d73 --- /dev/null +++ b/docs/ko/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "워크플로우, 스텝, 함수 에이전트, 리트리버를 계측합니다." +icon: "/images/frameworks/llamaindex.svg" +--- + +## 설치 + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +지원 버전: `llama-index-core` 0.14.23 ~ 0.15. 0.14.23은 워크플로우 스트림이 이 어댑터가 읽는 타입드 에이전트 이벤트를 포함하기 시작한 릴리즈입니다. 그 이전 버전에서는 모델 이름과 에이전트 구조가 모두 누락됩니다. + +## 계측 + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +LlamaIndex의 에이전트 API는 비동기입니다. 모든 스코프는 `async with`와 `with` 모두에서 동일하게 작동하며 동일한 이벤트를 생성합니다. + +`instrument()`는 LlamaIndex의 전역 디스패처에 이벤트 핸들러와 스팬 핸들러를 연결합니다. 이를 통해 에이전트 루프 전체가 모델 호출뿐만 아니라 가시적으로 드러납니다. + + + LLM에 인수 하나를 추가하지 않으면 트레이스의 모든 토큰 카운트가 null이 됩니다. 아래의 [토큰 카운트](#token-counts)를 참고하세요. + + +## 토큰 카운트 + +`FunctionAgent`는 `astream_chat`을 호출하는데, `llama-index-llms-openai`는 스트리밍 시 `stream_options={"include_usage": True}`를 전송하지 않습니다. 따라서 프로바이더는 사용량 청크를 전송하지 않고, 어떤 계측 도구도 이를 읽을 수 없습니다. + +이는 업스트림 LlamaIndex의 동작입니다. LLM에서 다음과 같이 직접 활성화하세요: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +동일한 실행 및 모델 기준 측정 결과: + +| | 입력 토큰 | 출력 토큰 | +| --- | --- | --- | +| 미적용 | `null` | `null` | +| 적용 | 148 | 17 | + +비스트리밍 호출(`llm.chat`, `llm.achat`)은 별도 설정 없이 사용량을 보고합니다. 기본 에이전트 경로인 스트리밍 경로에서만 이 설정이 필요합니다. + +## 기록되는 항목 + +| LlamaIndex | Failproof 이벤트 | +| --- | --- | +| `Workflow.run` 루트 스팬 | Session, `agent_start`, `agent_end` | +| 중첩된 `Workflow.run` 스팬 | 중첩된 `agent_start`, `agent_end` | +| 워크플로우 스텝 스팬 | `hook_triggered`, `hook_completed` | +| LLM 채팅 시작 및 종료 | `model_request`, `model_response` | +| `FunctionTool.call` 스팬 | `tool_use`, `tool_result` | +| 검색 시작 및 종료 | `tool_use`, `tool_result`, 출력 요약 | +| 임베딩 | `embeddings=True`가 아니면 기록 없음 | +| 사람을 기다리는 도구 | `human_wait`, `agent_pause`, 이후 `agent_resume`, `human_input` | +| `AgentWorkflow` 핸드오프 | 워크플로우에 부모가 지정된 에이전트별 중첩 `agent_start`, `agent_end` | +| 예외 | `error`, 이후 결과가 `failed`인 `agent_end`, 예외를 명시하는 `agent_end.summary` | +| `handler.cancel_run()` | 결과가 `cancelled`이고 `error` 없는 `agent_end` — 중지 버튼은 실패가 아님 | + +`agent_id`는 설정한 경우 `FunctionAgent.name`이 되고, 그렇지 않으면 워크플로우 클래스 이름이 됩니다. `AgentWorkflow` 하에서 턴을 가지는 각 에이전트는 워크플로우 아래 별도의 중첩 스팬을 가지므로, 핸드오프는 하나가 아닌 두 에이전트로 기록됩니다. + +검색 출력은 전체 덤프 대신 요약됩니다. 리트리버는 문서를 반환하는데, 페이로드에 저장하면 쿼리마다 코퍼스 전체가 이벤트 스토어에 저장됩니다. 대신 문서 수, 점수 범위, 잘린 스니펫이 저장됩니다. + +## 예제 + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +에이전트 루프는 트레이스에 훅 쌍으로 나타납니다: `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool`, `aggregate_tool_results`. 이들은 프레임워크 자체의 루프이므로 에이전트가 아닌 훅으로 분류되어 `agent_id`가 의미 있게 유지됩니다. + +## 스팬 이름 지정 + +`agent_id`는 설정한 경우 `FunctionAgent.name`이 되고, 그렇지 않으면 워크플로우 클래스 이름이 됩니다. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +`AgentWorkflow`에서 이 이름은 각 핸드오프가 기록되는 이름이기도 합니다: + +```text +AgentWorkflow parent span +├─ city_analyst turn 1 +├─ cost_analyst turn 2 +└─ city_analyst turn 3 — a new turn, not a reopened one +``` + +따라서 `agent_id`는 **어떤 에이전트**가 작업했는지를, `parent_id`는 **어떤 워크플로우**에 속했는지를 알려줍니다. 나중에 제어권을 돌려받은 에이전트는 첫 번째 턴을 재개하는 것이 아니라 두 번째 턴을 새로 시작합니다. + +재정의하거나 여러 에이전트를 하나의 부모 아래 묶으려면 실행을 감싸세요: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +`agent_id`는 낮은 카디널리티로 유지하세요. 모든 대시보드 화면의 기본 패싯이므로 UUID나 실행별 문자열이 아닌 역할 또는 워크플로우 이름을 사용하세요. + +## 세션 제어 + +이 어댑터는 **`session_id` 옵션을 받지 않습니다**. 세션은 감싸는 스코프에서 가져오며, 없을 경우 워크플로우 실행마다 생성된 `uuid4().hex`가 사용됩니다: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## 옵션 + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True로 설정하면 임베딩 호출을 툴 쌍으로 기록 + steps=True, # False로 설정하면 워크플로우 스텝 훅 쌍 제거 + capture_messages=True, # False로 설정하면 모든 페이로드 제거: 프롬프트, 완성, + # 툴 인수 및 출력, 스텝 I/O, 검색 + # 쿼리, 목표 및 최종 답변 + capture_limit=8192, # 캡처된 값당 유지되는 문자 수 + stale_after=600.0, # 중단된 LEAF가 강제 종료되기까지의 초 + reaper_interval=30.0, # 리퍼가 스윕하는 주기; 0이면 비활성화 +) +``` + +| 옵션 | 변경 이유 | +| --- | --- | +| `embeddings` | 임베딩 지연 또는 비용을 디버깅할 때만 활성화하세요. 대량 인덱스 빌드는 수천 건의 호출을 발생시켜 타임라인을 가득 채웁니다. | +| `steps` | 모델 및 툴 이벤트만 원하고 에이전트 루프가 노이즈로 느껴질 때 비활성화하세요. | +| `capture_messages` | 규제 데이터에 대해 비활성화하세요. 모든 페이로드 기록이 중단됩니다 — 프롬프트, 모델 완성, 툴 인수 및 반환값, 워크플로우 스텝 입출력, 검색 쿼리, 에이전트 목표 및 최종 답변. 구조, 타이밍, 토큰, 결과는 계속 기록됩니다. | +| `capture_limit` | 잘림 전에 캡처된 값당 유지되는 문자 수입니다. RAG 프롬프트나 검색된 컨텍스트가 잘려서 도착할 때 늘리세요. | +| `stale_after` | 중단된 **리프** — 소비되지 않은 스트리밍 응답, 종료 신호가 도착하지 않은 모델 또는 툴 스팬 — 가 강제 종료되기까지의 초입니다. 이를 통해 세션이 `ongoing`으로 영원히 읽히지 않고 종결됩니다. 중단된 실행 자체는 종료하지 않습니다: 디스패처가 종료를 감지하지 못한 채 태스크가 취소된 워크플로우는 `uninstrument()`까지 `agent_start`가 열린 상태로 유지됩니다. | +| `reaper_interval` | 스윕 빈도입니다. `0`으로 설정하면 리퍼를 완전히 비활성화합니다. | + +## 휴먼 인 더 루프 + +대기가 툴 내부에서 발생할 때 캡처됩니다: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +일반 워크플로우 스텝에서의 `ctx.wait_for_event`는 캡처되지 않습니다. 런타임이 디스패처에 도달하기 전에 드롭을 감지하여 스텝이 종료되고 나중에 일시 정지 신호 없이 재실행됩니다. LlamaIndex가 문서화한 FunctionAgent 패턴은 툴 내부에서 대기하므로 완전히 캡처됩니다. + +## 일반적인 문제 + + + + LLM에 `additional_kwargs={"stream_options": {"include_usage": True}}`를 추가하세요. [토큰 카운트](#token-counts)를 참고하세요. + + + + LlamaIndex에는 표준 usage 필드가 없습니다. 어댑터는 알려진 여러 형태를 시도하는데, 카운터 이름이 다른 인테그레이션은 어디에도 매칭되지 않습니다. + + 원시 딕셔너리는 항상 전송되므로 페이로드의 `usage`를 확인하여 프로바이더가 어떤 이름을 사용했는지 확인하세요. + + 채워진 `usage`와 빈 토큰 컬럼이 공존하는 것은 의도된 동작입니다 — 잘못된 숫자를 자신있게 표시하는 것보다 낫습니다. + + + + 이것은 반복마다 한 세트씩 생성되는 FunctionAgent 루프입니다. 대시보드에서 훅 이름으로 필터링하세요. 이 스텝 타이밍은 보통 모델 전용 어댑터 대신 이 어댑터를 사용하는 이유가 됩니다. + + + + 다음 순서로 확인하세요: `instrument()`가 실행 전에 호출되었는지; `await` 주변에 `async with failproofai_sdk.session():`이 있는지; `llama-index-core`가 0.14.23 이상인지; `FAILPROOFAI_SDK_STRICT=1`이 설정된 경우 저하된 훅이 삼켜지는 대신 예외를 발생시키는지. + + + +## 다음 단계 + + + + 쌍, ID, 세션 라이프사이클, 전달 방식. + + + 방금 캡처한 세션에서 인과 관계를 따라가 보세요. + + + LangGraph, CrewAI, Pydantic AI, 커스텀 에이전트. + + \ No newline at end of file diff --git a/docs/ko/start/integrations/pydantic-ai.mdx b/docs/ko/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..12f6b836d --- /dev/null +++ b/docs/ko/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "타입이 지정된 에이전트, 도구, 모델 호출, 재시도를 계측합니다." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## 설치 + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +지원 버전: `pydantic-ai-slim` 2.0~3.0. 2.0에서 `Agent(instrument=...)`가 제거되고 이 어댑터가 기반으로 하는 capability 프로토콜이 도입되었으므로, 1.x는 이 방식으로 계측할 수 없습니다. + +## 계측 + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # Agent를 생성하기 전에 호출 + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()`는 반드시 `Agent`를 생성하기 전에 실행되어야 합니다. capability는 생성 시점에 추가되므로, 이전에 생성된 에이전트는 capability를 가지지 않으며 아무것도 기록하지 않습니다. 오류도 발생하지 않아 문제를 알아채기 어렵습니다. 이것이 이 어댑터에서 빈 트레이스가 나타나는 가장 흔한 원인입니다. + + +모듈 스코프 에이전트에서 이 문제가 자주 발생합니다: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # 임포트 시점에 생성됨 + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # 이것을 먼저 실행 +import agents # 이제 에이전트가 capability를 얻음 +``` + +적용 여부 확인: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI는 전달한 목록을 단일 `root_capability`로 병합하므로, 읽을 수 있는 `agent.capabilities` 속성은 없습니다. + +계측 중에 생성된 에이전트는 capability를 유지하므로, 에이전트를 다시 빌드하지 않고도 `uninstrument()` 후 재계측할 수 있습니다. + +## 기록되는 항목 + +| Pydantic AI | Failproof 이벤트 | +| --- | --- | +| 에이전트 실행 | `agent_start`, `agent_end` | +| 모델 요청 | `model_request`, `model_response` (토큰 사용량 포함) | +| 도구 호출 | `tool_use`, `tool_result` (모델이 전달한 인자 포함) | +| 도구에서 발생한 `ModelRetry` | 오류를 담은 `tool_result` | +| 처리되지 않은 예외 | `error`, 이후 결과가 `failed`인 `agent_end` | + +훅 페어와 휴먼-인-더-루프 페어는 없습니다. Pydantic AI는 브래킷을 감쌀 수 있는 노드나 스텝 경계가 없고 내장된 휴먼 일시정지 기능도 없으므로 매핑할 대상이 없습니다. 이를 직접 구현하는 경우 이벤트를 직접 발행하세요 — [커스텀 에이전트](/ko/reference/custom-agents)를 참고하세요. + +`output_type`은 트레이스에 영향을 주지 않습니다. 타입이 지정된 실행과 문자열 실행은 동일한 이벤트를 생성합니다. + +## 예제 + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +트레이스에서 `restock_eta`는 오류를 담은 `tool_result`로 나타나고, 이후 에이전트가 이를 우회하는 모델 호출이 이어지며 실행은 `success`로 종료됩니다. 두 사실 모두 기록됩니다. + +## 오류, 재시도, 제어 흐름 + +Pydantic AI는 세 가지 서로 다른 상황에서 예외를 발생시키며, 어댑터는 이를 구분합니다: + +| 예외 | 처리 방식 | 결과 | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | 실제 도구 실패 | 오류가 담긴 `tool_result`; 실행은 여전히 `success`로 끝날 수 있음 | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | 제어 흐름 | 오류 아님; 실행이 조율되고 있는 상태 | +| 그 외 | 실패 | `error`, 이후 결과가 `failed`인 `agent_end` | + +`ModelRetry`는 의도적으로 첫 번째 그룹에 포함됩니다. 이는 시도가 실제로 실패하여 모델에게 재시도를 요청한 것으로, 도구 스팬의 오류 필드가 담당하는 역할입니다. 이를 제어 흐름으로 분류하면 실제 도구 실패가 성공한 실행 뒤에 숨겨집니다. + +## 스팬 이름 지정 + +Pydantic AI의 자체 실행 스팬은 `agent`로 명명됩니다. 원하는 레이블을 부여하려면 호출을 래핑하세요: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +그러면 프레임워크의 스팬이 `inventory` 아래에 중첩되고, 모델과 도구 이벤트가 거기에 연결됩니다. + +`agent_id`는 낮은 카디널리티를 유지하세요. 이는 모든 대시보드 화면의 기본 패싯이므로 역할 이름을 사용하고 UUID나 실행별 문자열은 사용하지 마세요. + +## 세션 제어 + +다음 순서로 결정되며, 첫 번째로 일치하는 것이 적용됩니다: + +1. `instrument("pydantic_ai", session_id=...)` +2. 감싸고 있는 `failproofai_sdk.session()` 스코프 +3. 실행의 `conversation_id`, 이후 `run_id` +4. 생성된 `uuid4().hex` + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## 옵션 + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # 모든 실행을 하나의 세션 id에 고정 + capture_content=True, # False로 설정하면 페이로드에서 프롬프트와 완성 결과를 제외 +) +``` + +## 자주 발생하는 문제 + + + + `Agent`가 `instrument()` 실행 이전에 생성된 경우입니다. 위의 경고를 참고하고 `agent.root_capability.capabilities`를 확인하세요. + + + + 단순한 `raise`는 그대로 전파됩니다. 이것이 Pydantic AI의 설계입니다. 모델이 이를 우회할 수 있도록 하려면 모델이 활용할 수 있는 메시지와 함께 `ModelRetry`를 발생시키세요. 어느 경우든 실패는 기록됩니다. + + + + 해당 자식 스팬은 Pydantic AI 자체의 실행 스팬으로, 모델과 도구 이벤트가 연결되는 곳입니다. 커스텀 이름을 포기하는 대신 단일 스팬을 원한다면 자체 스코프를 제거하세요. + + + + Pydantic AI의 비동기 그래프 스택이 페이로드 필드 제한보다 길며, 트레이스백의 마지막 줄은 예외 자체입니다. 이 필드는 뒤가 아닌 앞에서 잘리므로 필요한 줄은 유지됩니다. + + + +## 다음 단계 + + + + 페어, id, 세션 생명주기, 전달 방식. + + + 방금 캡처한 세션에서 인과관계를 추적합니다. + + + LangGraph, CrewAI, LlamaIndex, 커스텀 에이전트. + + \ No newline at end of file diff --git a/docs/ko/start/quickstart.mdx b/docs/ko/start/quickstart.mdx index 8ef251856..58f8d2e03 100644 --- a/docs/ko/start/quickstart.mdx +++ b/docs/ko/start/quickstart.mdx @@ -1,12 +1,12 @@ --- title: "빠른 시작" -description: "에이전트 세션을 캡처하고, 실패를 발견하고, 이를 예방하기 시작합니다." +description: "에이전트 세션을 캡처하고, 실패를 찾아 예방하세요." icon: "zap" --- -이 빠른 시작 가이드에서는 하나의 머신이 세션을 보고하도록 설정하고, 감사를 실행하고, 정책을 배포합니다. 스킬을 사용하거나 수동 단계를 따르세요. +이 빠른 시작 가이드는 하나의 머신에서 세션을 보고하고, 감사를 실행하며, 정책을 배포하는 과정을 안내합니다. 스킬을 사용하거나 수동 단계를 따라 Failproof AI를 설정하세요. -**어떤 방법이 맞나요?** 에이전트가 지원되는 12개 [하네스](/ko/reference/harnesses) 중 하나(코딩 CLI, 또는 Hermes나 OpenClaw 같은 게이트웨이)에서 실행된다면, 아래 단계를 따르세요. Node.js 20.9 이상이 필요합니다. 에이전트에 하네스가 없다면 [Python SDK](/ko/reference/custom-agents)로 트레이싱과 감사를 위한 계측을 추가한 후, [첫 번째 실패 검사 실행](/ko/start/first-audit)에서 다시 합류하세요. 이 경우 적용을 위해서는 런타임에 훅이 필요합니다. +**어떤 방법을 선택하시겠습니까?** 에이전트가 12개의 지원 [하네스](/ko/reference/harnesses) 중 하나에서 실행되는 경우 — 코딩 CLI, 또는 Hermes나 OpenClaw 같은 게이트웨이 — 아래 단계를 따르세요. Node.js 20.9 이상이 필요합니다. 에이전트에 하네스가 없다면, 추적 및 감사를 위해 [Python SDK](/ko/reference/custom-agents)로 계측한 후 [첫 번째 실패 검사 실행](/ko/start/first-audit)에서 다시 합류하세요. 이 경로에서 적용(enforcement)을 사용하려면 런타임에 훅이 필요합니다. @@ -21,16 +21,16 @@ 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. **관리 → 키**로 이동하여 `events:add`와 `policies:pull` 권한이 있는 키를 생성합니다. -3. 일회용 시크릿을 복사하여 대상 머신에 저장합니다: +1. [Failproof AI 대시보드](https://app.befailproof.ai)를 열고 계정을 생성하거나 회사 이메일로 로그인하세요. +2. **관리 → 키**로 이동하여 `events:add` 및 `policies:pull` 권한이 있는 키를 생성하세요. +3. 일회용 시크릿을 복사하여 대상 머신에 저장하세요: ```bash export FAILPROOFAI_KEY="" @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - 세션 기록은 기본적으로 전송됩니다. 기록 내용 없이 훅 활동과 정책 결정만 보고하려면 `--no-transcripts`를 추가하세요. + 세션 트랜스크립트는 기본적으로 전송됩니다. 트랜스크립트 내용 없이 훅 활동 및 정책 결정만 보고하려면 `--no-transcripts`를 추가하세요. - 이 머신에 이미 에이전트 기록이 있다면, 최근 7일 치를 미리 보고 가져온 후 전송이 완료될 때까지 기다리세요. 새 머신이라면 이 단계를 건너뛰세요. + 이 머신에 이미 에이전트 기록이 있는 경우, 최근 7일치를 미리 보고 가져온 후 전송이 완료될 때까지 기다리세요. 새 머신에서는 이 단계를 건너뛰세요. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Failproof AI에서 **세션**을 열고 가져온 세션을 선택합니다. + Failproof AI에서 **세션**을 열고 가져온 세션을 선택하세요. - 이 단계에서는 Failproof AI를 하네스에 연결하고 40개의 기본 제공 정책을 설치합니다. Failproof AI가 세션을 감사하고 에이전트에 맞는 정책을 작성하기 전에, 로컬 정책 결정을 확인하고 적용을 시험해 볼 수 있습니다. + 이 단계는 Failproof AI를 하네스에 연결하고 40개의 내장 정책을 설치합니다. Failproof AI가 세션을 감사하고 에이전트에 맞는 정책을 작성하기 전에, 이를 사용하여 로컬 정책 결정을 확인하고 적용을 시험해 볼 수 있습니다. - 설치 프로그램이 하네스를 자동으로 감지하도록 하거나 직접 지정할 수 있습니다. 지원되는 12개 모두 유효한 `--cli` 값입니다 — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + 설치 프로그램이 하네스를 자동으로 감지하도록 하거나, 명시적으로 지정할 수 있습니다. 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)을 참조하세요. [첫 번째 실패 검사 실행](/ko/start/first-audit)을 따르세요. "에이전트가 접근 방식을 바꾸지 않고 실패한 도구를 재시도한 세션 찾기"와 같이 구체적인 목표를 사용하세요. - [정책으로 첫 번째 실패 예방](/ko/start/first-policy)을 따르세요. 관찰 모드에서 시작하여 매칭 결과를 검토한 후, 검토된 버전을 적용하세요. + [정책으로 첫 번째 실패 예방](/ko/start/first-policy)을 따르세요. 관찰 모드로 시작하여 매칭 항목을 검토한 후, 검토된 버전을 적용하세요. - `failproofai config --status`를 실행하세요. 정상적인 설정은 클라우드 연결 상태, 데몬 상태, 그리고 적용이 일시 중지되었는지 여부를 보고합니다. + `failproofai config --status`를 실행하세요. 정상적인 설정은 클라우드 연결 상태, 데몬 상태, 적용이 일시 중지되었는지 여부를 보고합니다. \ No newline at end of file diff --git a/docs/ko/start/quickstarts/crewai.mdx b/docs/ko/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..47cf6c85d --- /dev/null +++ b/docs/ko/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "설치, 계측, 그리고 첫 번째 트레이스 확인." +icon: "/images/frameworks/crewai.svg" +--- + +첫 번째 CrewAI 트레이스를 확인하기까지 세 단계입니다. 각 이벤트의 데이터, 흐름, 문제 해결 방법은 [전체 가이드](/ko/start/integrations/crewai)를 참고하세요. + +## 설치 + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## 계측 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +크루, 에이전트, 태스크, 툴은 아무것도 변경할 필요가 없습니다. `instrument()`는 CrewAI의 모듈 레벨 이벤트 버스를 구독합니다. + +## 도착 여부 확인 + +한 번 실행한 후 **Observe → Sessions**를 열고 환경을 선택하세요. 실행 결과가 재구성된 트레이스로 표시됩니다. + +아무것도 표시되지 않는다면 `failproofai config --status`로 머신이 연결되어 있는지 확인하세요. + + + 기록되는 항목, 흐름, 토큰 사용량, 스팬 명명 규칙, 옵션, 그리고 일반적인 문제들. + \ No newline at end of file diff --git a/docs/ko/start/quickstarts/custom-agents.mdx b/docs/ko/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..91a1988db --- /dev/null +++ b/docs/ko/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "커스텀 에이전트" +description: "에이전트를 세 개의 `with` 블록으로 감싸면 바로 기록이 시작됩니다." +icon: "code" +--- + +직접 작성한 에이전트나 Failproof AI 어댑터가 없는 프레임워크에 사용합니다. + +이미 작성한 코드를 `with` 블록으로 감싸기만 하면 됩니다. 각 블록은 시작 시간, 종료 시간, 소요 시간을 자동으로 기록합니다 — 별도로 호출할 필요가 없습니다. + +## 설치 + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # 하나의 툴 호출 +``` + +위에서 아래로 읽으면 의미가 그대로 드러납니다: + +| 감싸는 블록 | 의미 | +| --- | --- | +| `session()` | 이 이벤트들은 같은 실행에 속합니다 | +| `agent()` | 무언가 작업을 수행 중입니다 — 목록에서 식별할 수 있는 이름을 지정하세요 | +| `tool_call()` | 하나의 툴이며, 반환값이 무엇인지 기록합니다 | + +코드 구조에 맞게 자유롭게 중첩할 수 있습니다. ID를 직접 전달할 필요가 없습니다. 각 블록이 자신이 속한 컨텍스트를 기억하므로, 기록하는 모든 내용은 자동으로 올바른 실행과 에이전트에 연결됩니다. `async with`도 동일하게 작동합니다. + +## 데이터 수신 확인 + +한 번 실행한 뒤 **Observe → Sessions**를 열고 환경을 선택하세요. 실행 결과가 재구성된 트레이스로 표시됩니다. + +데이터가 수신되지 않으면 `failproofai config --status`로 머신 연결 상태를 확인하세요. + + + 모든 이벤트 메서드, 코드에서 예외가 발생했을 때의 동작, 실제 예제, 스레드와 비동기 처리, 그리고 어댑터가 없는 프레임워크 계측 방법을 다룹니다. + \ No newline at end of file diff --git a/docs/ko/start/quickstarts/langchain.mdx b/docs/ko/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..464d0189c --- /dev/null +++ b/docs/ko/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain and LangGraph" +description: "설치, 계측, 첫 번째 트레이스 확인." +icon: "/images/frameworks/langchain.svg" +--- + +LangChain 또는 LangGraph 트레이스를 시작하는 세 가지 단계입니다. 스트리밍, human-in-the-loop, 스팬 명명, 옵션에 대한 자세한 내용은 [전체 가이드](/ko/start/integrations/langchain)를 참고하세요. + +## 설치 + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +LangGraph 없이 LangChain만 사용하는 경우 `failproofai-sdk[langchain]`을 사용하세요. + +## 계측 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +호출 지점을 변경할 필요가 없습니다. `instrument()`는 LangChain이 모든 콜백 매니저를 생성할 때 주입하는 트레이서를 등록하므로, 그래프, 도구, 모델이 자동으로 캡처됩니다 — 직접 작성하지 않은 라이브러리 내부의 것들도 포함해서요. + +## 도착 여부 확인 + +한 번 실행한 후 **Observe → Sessions**를 열고 환경을 선택하세요. 실행 결과가 재구성된 트레이스로 나타납니다. + +아무것도 도착하지 않으면 `failproofai config --status`로 머신이 연결되어 있는지 확인하세요. + + + 기록되는 항목, 스트리밍, 토큰 수, 스팬 명명, 세션 제어, 옵션, human in the loop. + \ No newline at end of file diff --git a/docs/ko/start/quickstarts/llamaindex.mdx b/docs/ko/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..b10d3d4d3 --- /dev/null +++ b/docs/ko/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "설치, 계측, 첫 번째 트레이스 확인." +icon: "/images/frameworks/llamaindex.svg" +--- + +첫 번째 LlamaIndex 트레이스를 위한 세 가지 단계입니다. 워크플로 단계, 검색, reaper, 옵션에 대해서는 [전체 가이드](/ko/start/integrations/llamaindex)를 참고하세요. + +## 설치 + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## 계측 + +LlamaIndex의 에이전트 API는 비동기입니다. 모든 스코프는 `async with`와 `with` 모두에서 동작합니다. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + LLM에 인수를 하나 더 추가하지 않으면, 트레이스의 모든 토큰 수가 null이 됩니다 — `llama-index-llms-openai`는 스트리밍 시 사용량을 요청하지 않습니다. [토큰 수](/ko/start/integrations/llamaindex#token-counts)를 참고하세요. + + +## 도착 확인 + +한 번 실행한 후 **Observe → Sessions**를 열고 환경을 선택하세요. 실행 결과가 재구성된 트레이스로 표시됩니다. + +아무것도 도착하지 않으면 `failproofai config --status`로 머신이 연결되어 있는지 확인하세요. + + + 토큰 수, 기록되는 항목, 워크플로 단계, 검색, 옵션, 일반적인 문제. + \ No newline at end of file diff --git a/docs/ko/start/quickstarts/pydantic-ai.mdx b/docs/ko/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..d7978be4c --- /dev/null +++ b/docs/ko/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "설치, 계측, 그리고 첫 번째 트레이스 확인." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +세 단계로 첫 번째 Pydantic AI 트레이스를 확인하세요. 툴, 재시도, 스트리밍, 옵션에 대한 자세한 내용은 [전체 가이드](/ko/start/integrations/pydantic-ai)를 참고하세요. + +## 설치 + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## 계측 + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()`은 반드시 `Agent`를 생성하기 **전에** 실행되어야 합니다. 계측 기능은 생성 시점에 추가되므로, 그 이전에 만들어진 에이전트는 아무것도 기록하지 않습니다 — 오류도 발생하지 않기 때문에 문제를 인지하기 어렵습니다. 이는 이 어댑터에서 트레이스가 비어 있는 가장 흔한 원인이며, 모듈 스코프에서 에이전트를 생성하는 경우에 특히 주의가 필요합니다. 해당 모듈을 임포트하기 전에 `failproofai_sdk`를 임포트하고 `instrument()`를 호출하세요. + + +## 도착 여부 확인 + +한 번 실행한 뒤 **Observe → Sessions**를 열고 환경을 선택하세요. 실행 결과가 재구성된 트레이스로 표시됩니다. + +아무것도 표시되지 않는다면, `failproofai config --status` 명령으로 머신이 연결되어 있는지 확인하세요. + + + 기록되는 항목, 툴과 재시도, 스트리밍, 스팬 네이밍, 옵션, 그리고 자주 발생하는 문제. + \ No newline at end of file diff --git a/docs/pt-br/index.mdx b/docs/pt-br/index.mdx index a972a3048..bf023e855 100644 --- a/docs/pt-br/index.mdx +++ b/docs/pt-br/index.mdx @@ -1,19 +1,19 @@ --- title: "Torne seu agente à prova de falhas" -description: "Observabilidade e aplicação de regras para cada ambiente em que seus agentes rodam — CLIs de codificação, gateways de chat, assistentes auto-hospedados e seus próprios agentes instrumentados." +description: "Observabilidade e controle para cada harness em que seus agentes rodam — CLIs de codificação, gateways de chat, assistentes self-hosted e seus próprios agentes instrumentados." icon: "shield-check" --- O Failproof AI ajuda equipes a entender o que os agentes fizeram, identificar onde falharam e implantar salvaguardas antes que o mesmo comportamento se repita. -Um **harness** é o ambiente no qual seu agente efetivamente roda. O Failproof AI se integra a 12 deles — CLIs de codificação como Claude Code e Codex, gateways de chat como Hermes, assistentes auto-hospedados como OpenClaw — e os mesmos eventos, as mesmas políticas e o mesmo histórico de sessões se aplicam a todos. Agentes sem harness se reportam por meio do [Python SDK](/pt-br/reference/custom-agents), que os rastreia e audita; para aplicar uma política nesses casos, é necessário um hook no seu próprio runtime. +Um **harness** é o ambiente em que seu agente realmente executa. O Failproof AI se conecta a 12 deles — CLIs de codificação como Claude Code e Codex, gateways de chat como Hermes, assistentes self-hosted como OpenClaw — e os mesmos eventos, as mesmas políticas e o mesmo histórico de sessões se aplicam a todos. Agentes sem harness se reportam por meio do [SDK Python](/pt-br/reference/custom-agents), que os rastreia e audita; aplicar uma política nesse caso exige um hook no seu próprio runtime. - Use a skill para instrumentar seu projeto, conectá-lo e verificar que os logs do agente estão chegando. + Use a skill para instrumentar seu projeto, conectá-lo e verificar se os logs do agente estão chegando. - - Analise, consulte, crie dashboards e execute auditorias em linguagem natural sobre os logs do seu agente. + + Analise, consulte, crie dashboards e execute auditorias em linguagem natural nos logs do seu agente. @@ -37,5 +37,5 @@ Um **harness** é o ambiente no qual seu agente efetivamente roda. O Failproof A Se você está implantando seu primeiro agente instrumentado, comece pelo [quickstart](/pt-br/start/quickstart). Se os dados já estão chegando, abra [Sessions](/pt-br/sessions/overview) e inspecione uma execução real antes de configurar auditorias ou políticas. - Complete o fluxo de trabalho completo, da captura até a implantação segura de uma política. + Complete o fluxo de trabalho de ponta a ponta, desde a captura até uma política implantada com segurança. \ No newline at end of file diff --git a/docs/pt-br/policies/deploy.mdx b/docs/pt-br/policies/deploy.mdx index fe328da36..a7e4085b7 100644 --- a/docs/pt-br/policies/deploy.mdx +++ b/docs/pt-br/policies/deploy.mdx @@ -1,47 +1,51 @@ --- -title: "Fazer deploy de políticas" -description: "Publique uma versão de política revisada para as máquinas desejadas." +title: "Implantar políticas" +description: "Publique uma versão de política revisada nas máquinas de destino." icon: "cloud-upload" --- -Um deployment conecta uma ou mais versões de política a um conjunto de máquinas registradas. +Uma implantação conecta uma ou mais versões de política a um conjunto alvo de máquinas cadastradas. -## Aplicar um deployment +## Aplicar uma implantação 1. Acesse **Admin → enforcement**, localize a máquina e expanda sua linha. - 2. Selecione **edit**, adicione a versão de política revisada e escolha **observe** ou seu efeito 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. + 2. Selecione **edit**, adicione a versão de política revisada e escolha o efeito **observe** ou de imposição. + 3. Aplique a alteração, aguarde o próximo check-in da máquina e confirme o estado de implantação e cobertura. 4. Acesse **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) + ![O editor de implantação de máquina com versões de política, efeitos enforce e observe, e a ação de aplicar implantação.](/images/dashboard/enforcement-editor.png) - Os endpoints de deployment na nuvem não são expostos intencionalmente como comandos `fp` comuns. Verifique a máquina localmente e faça o deploy pelo dashboard: + Implante pela CLI com `fp fleet`. Revise o conjunto resultante antes de aplicar — `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 ou um agente executando comandos), a aplicação ocorre imediatamente sem plano nem prompt — portanto, execute `fp fleet show ` primeiro se desejar revisar: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - Use `fp sessions --env production --since 24h` e `fp events --event-type hook_completed` após o deployment para verificar se a atividade chega ao Cloud. + `fp fleet diff ` mostra a intenção versus a entrega (uma máquina aparece como `behind` até sua próxima consulta), `fp fleet history ` lista as gerações e `fp fleet rollback ` restaura uma delas — a operação é recusada se a geração referenciada nomear uma política que foi desativada ou excluída. + + Verifique a própria máquina com `failproofai config --status` e use `fp sessions --env production --since 24h` e `fp events --event-type hook_completed` após a implantação para confirmar que a atividade está chegando ao 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. + Implante uma versão revisada, não um rascunho mutável, começando por uma máquina fora de produção ou um grupo pequeno cujas sessões você possa inspecionar. - Revise correspondências, razões, ferramentas afetadas e falsos positivos sem bloquear o trabalho. + Analise correspondências, razões, ferramentas afetadas e falsos positivos sem bloquear o trabalho. - - Promova após as correspondências observadas separarem ações inseguras das válidas e, em seguida, confirme que cada máquina pretendida obteve o deployment e está reportando decisões. + + Promova após as correspondências observadas separarem ações inseguras das válidas e confirme que cada máquina prevista recebeu a implantação e está reportando decisões. -As máquinas precisam da capacidade `policies:pull`. O reporte de eventos é controlado separadamente por `events:add`; verifique ambos quando esperar análise e aplicação no Cloud. +As máquinas precisam da capacidade `policies:pull`. O reporte de eventos é controlado separadamente por `events:add`; verifique ambos quando você esperar análise e imposição pelo Cloud. - O gerenciamento de enforcement é um fluxo administrativo do Cloud. Não trate as rotas de enforcement restritas ao root como endpoints comuns de `/v1` da API para clientes. + O gerenciamento de imposição é um fluxo administrativo do Cloud. Não trate as rotas de imposição exclusivas de root como endpoints comuns da API `/v1` para clientes. \ No newline at end of file diff --git a/docs/pt-br/policies/editor.mdx b/docs/pt-br/policies/editor.mdx index 64cd4c9b8..2a5ac419a 100644 --- a/docs/pt-br/policies/editor.mdx +++ b/docs/pt-br/policies/editor.mdx @@ -4,44 +4,46 @@ description: "Crie e revise políticas versionadas a partir de um modo de falha icon: "file-pen-line" --- -Use o editor de políticas para transformar um achado ou problema em uma regra implantável. Mantenha a autoria separada da implantação para que um rascunho não possa alterar silenciosamente o comportamento em produção. +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. -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 consegue expressar o problema e, em seguida, leva o contexto do achado e a intenção revisada para o editor. O código-fonte gerado permanece como rascunho até que você o publique. +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. ## Publicar uma versão de política - 1. Vá para **Admin → policy editor** e, em **compose**, descreva o modo de falha ou cole o código-fonte JavaScript da política. + 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. Informe a identidade da política e publique-a; use **library** para comparar ou desativar versões. + 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. - ![A visão de composição do editor de políticas, com identidade da política, elaboração assistida por IA, validação do código-fonte e controles de publicação.](/images/dashboard/policy-editor.png) + ![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) - O CLI na nuvem não publica versões de política. Valide o código-fonte localmente antes de copiá-lo para o editor: + 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: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - Publique a versão revisada a partir de **Admin → policy editor**. + 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`. -## Lista de verificação para autoria +## Lista de verificação para criação de políticas -1. Nomeie o modo de falha com linguagem operacional. +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 justificativa que indique ao agente ou operador qual é o próximo passo. -5. Adicione exemplos que devem corresponder e exemplos que precisam continuar permitidos. +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. 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. - Versões de política são entradas de implantação imutáveis. Editar um rascunho cria uma nova versão; isso não deve reescrever a versão já atribuída às máquinas. + 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 diff --git a/docs/pt-br/reference/cloud-cli.mdx b/docs/pt-br/reference/cloud-cli.mdx index ca54f59ef..1098616b9 100644 --- a/docs/pt-br/reference/cloud-cli.mdx +++ b/docs/pt-br/reference/cloud-cli.mdx @@ -1,19 +1,19 @@ --- title: "Failproof Cloud CLI" -description: "Referência completa para consultas e administração do Failproof AI Cloud com fp." +description: "Referência completa para consultar e administrar o Failproof AI Cloud com fp." icon: "cloud-cog" --- -Use `fp` para inspecionar telemetria Cloud e gerenciar auditorias, achados, 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. +Use `fp` para inspecionar telemetria do Cloud, gerenciar a aplicação de políticas gerenciadas na nuvem (policies, implantações de frota, decisões de guardrail) e administrar auditorias, findings, issues, alertas, chaves, usuários, queries 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 publicado como uma ferramenta isolada: ```bash uv tool install fp-cloud-cli fp version ``` -## Autenticar +## Login ```bash fp login @@ -32,22 +32,22 @@ As opções globais devem vir antes do comando: fp --json sessions --since 24h ``` -Execute `fp COMMAND --help` ou `fp COMMAND SUBCOMMAND --help` para ajuda no terminal. +Execute `fp COMMAND --help` ou `fp COMMAND SUBCOMMAND --help` para obter ajuda no terminal. -## Comandos da CLI +## Comandos do CLI ### Autenticação | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp login` | Entrar com um código de uso ú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 ajuda de comandos de nível superior. | — | +| `fp login` | Faz login com um código de uso ú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 do CLI. | — | +| `fp help` | Exibe a ajuda de comandos de nível superior. | — | ```bash -fp login --email voce@exemplo.com --org equipe-confiabilidade +fp login --email you@example.com --org reliability-team fp whoami ``` @@ -57,30 +57,34 @@ fp whoami fp events [OPTIONS] ``` -Lista eventos individuais de agentes. O feed padrão simplificado exclui payloads brutos; use `--full` apenas para investigações delimitadas. +Lista eventos individuais de agentes. O feed leve padrão exclui os payloads brutos; use `--full` apenas para investigações com escopo delimitado. | Opção | Descrição | | --- | --- | -| `--limit`, `-n ` | Total máximo de linhas. Padrão: `50`. | +| `--limit`, `-n ` | Máximo de linhas totais. Padrão: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` ou `7d`. | -| `--from ` / `--to ` | Intervalo UTC ISO 8601; substitui `--since`. | -| `--env ` | Filtro de ambiente; repita ou separe por vírgula. | -| `--event-type ` | Filtro de tipo de evento; repita ou separe por vírgula. | -| `--agent-id ` | Filtro de agente; repita ou separe por vírgula. | -| `--session-id ` | Filtro de sessão; repita ou separe por vírgula. | -| `--search ` | Busca em texto do payload; repetível, com correspondência de qualquer termo. | -| `--order asc\|desc` | Ordem temporal. Padrão: mais recente primeiro. | -| `--all` | Paginação automática até `--limit`. | -| `--cursor ` | Retomar a partir de um cursor opaco. | +| `--from ` / `--to ` | Intervalo ISO 8601 UTC; 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 textual no payload; repetível, com correspondência em qualquer termo. | +| `--order asc\|desc` | Ordem temporal. Padrão: mais recentes 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` | Incluir payloads brutos pelo endpoint de eventos completo. | -| `--fields ` | Retornar apenas os campos selecionados; solicitar `payload` ativa o modo completo. | +| `--full` | Inclui payloads brutos pelo endpoint de eventos mais pesado. | +| `--fields ` | Retorna apenas os campos selecionados; solicitar `payload` ativa o modo full. | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +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 esperado, a resposta carrega um `next_cursor` para retomar; `"next_cursor": null` significa que o feed realmente foi esgotado. + + ### Sessões ```text @@ -89,19 +93,19 @@ fp sessions [OPTIONS] | Opção | Descrição | | --- | --- | -| `--limit`, `-n ` | Total máximo de linhas. Padrão: `50`. | +| `--limit`, `-n ` | Máximo de linhas totais. Padrão: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h` ou `7d`. | -| `--from ` / `--to ` | Intervalo UTC ISO 8601; substitui `--since`. | -| `--env ` | Filtro de ambiente; repita ou separe por vírgula. | -| `--status ` | `done`, `error` ou `timeout`; repita ou separe por vírgula. | -| `--agent-id ` | Corresponde sessões que envolvam qualquer agente selecionado. | -| `--session-id ` | Filtro de sessão; repita ou separe por vírgula. | -| `--all` | Paginação automática até `--limit`. | -| `--cursor ` | Retomar a partir de um cursor opaco. | +| `--from ` / `--to ` | Intervalo ISO 8601 UTC; 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 ` | Filtra 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 ` | 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 em sessões multi-agente. | +| `--fields ` | Retorna apenas os campos selecionados. | +| `--full-ids` | Não abrevia os IDs de sessão na saída do terminal. | +| `--agents` | Expande o conjunto de agentes para sessões multiagente. | ### Avaliações @@ -111,15 +115,15 @@ fp evals [OPTIONS] | Opção | Descrição | | --- | --- | -| `--aggregate` | Exibir totais e estatísticas por pontuação em vez de avaliações individuais. | +| `--aggregate` | Exibe 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. | +| `--since`, `--from`, `--to` | Seleciona o intervalo de tempo. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Restringe 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` | 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. | +| `--all`, `--cursor`, `--page-size` | Controla a paginação da listagem. | +| `--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. | ### Erros @@ -129,93 +133,93 @@ fp errors [OPTIONS] | Opção | Descrição | | --- | --- | -| `--aggregate` | Resumir os erros correspondentes em vez de listar linhas. | +| `--aggregate` | Resume os 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 a população de erros. | -| `--search ` | Buscar no texto do payload; repetível. | +| `--since`, `--from`, `--to` | Seleciona o intervalo de tempo. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Restringe o conjunto de erros. | +| `--search ` | Busca textual no payload; repetível. | | `--order asc\|desc` | Ordem temporal. | -| `--all`, `--cursor`, `--page-size` | Controlar a paginação da listagem. | -| `--fields ` | Retornar apenas os campos selecionados. | -| `--full-ids` | Exibir IDs de sessão completos. | +| `--all`, `--cursor`, `--page-size` | Controla a paginação da listagem. | +| `--fields ` | Retorna apenas os campos selecionados. | +| `--full-ids` | Exibe IDs de sessão completos. | ### Uso e valores de filtro | Comando | Finalidade | | --- | --- | -| `fp usage` | Exibir o uso para a 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. | +| `fp usage` | Exibe o uso na 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. | ### Organizações | Comando | Finalidade | | --- | --- | -| `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. | +| `fp orgs list` | Lista as organizações acessíveis. | +| `fp orgs switch [SLUG]` | Salva uma organização ativa; solicita quando omitida. | +| `fp orgs current` | Exibe a organização ativa. | +| `fp orgs perms` | Exibe suas permissões na organização ativa. | ### Chaves de API | Comando | Finalidade | Opções | | --- | --- | --- | -| `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` | +| `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 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` | -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`. +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`. -### Consultas +### Queries | Comando | Finalidade | Opções | | --- | --- | --- | -| `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. | — | +| `fp query list` | Lista as queries salvas. | `--show-id`; `--fields ` | +| `fp query show NAME` | Exibe uma query. | — | +| `fp query create NAME` | Salva uma query. | `--sql `; `--description` | +| `fp query update NAME` | Atualiza ou renomeia uma query. | `--name`; `--sql`; `--description`; `--yes`, `-y` | +| `fp query delete NAME` | Exclui uma query salva. | `--yes`, `-y` | +| `fp query run [NAME]` | Executa uma query salva ou SQL ad hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query schema [TABLE]` | Lista as tabelas consultáveis ou inspeciona uma tabela específica. | — | ### Usuários | Comando | Finalidade | Opções | | --- | --- | --- | -| `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` | Desativar o acesso. | `--yes`, `-y` | -| `fp users enable EMAIL` | Reativar o acesso. | `--yes`, `-y` | +| `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` | ### Configurações | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp settings list` | Listar configurações da organização e valores atuais. | — | -| `fp settings schema` | Exibir valores aceitos e descrições. | — | -| `fp settings set KEY` | Alterar uma configuração existente. | exatamente uma de `--value`, `--json-value`, `--file`; `--yes`, `-y` opcional | +| `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`; opcional `--yes`, `-y` | ### Alertas | Comando | Finalidade | Opções | | --- | --- | --- | -| `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` | +| `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` | 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. @@ -223,24 +227,24 @@ As severidades de alerta são `info`, `warning` e `critical`. Os tipos de gatilh | Comando | Finalidade | Opções | | --- | --- | --- | -| `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 imediatamente enfileirar sua primeira execução. | Veja [opções de criação](#audit-create-options). | -| `fp audits edit NAME` | Substituir configurações de 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, seus achados e 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 briefing e o estado de busca das URLs de referência. | — | -| `fp audits context-set NAME` | Alterar o briefing ou as URLs de referência. | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | Rebuscar URLs de referência. | — | -| `fp audits findings` | Listar achados. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | Exibir um achado e suas evidências. | — | -| `fp audits ack FINDING_ID` | Confirmar o recebimento de um achado. | `--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 um achado como corrigido sem supressão futura. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | Retornar um achado à fila ativa e limpar a supressão. | — | -| `fp audits assign FINDING_ID` | Definir o responsável pelo achado. | `--to ` obrigatório | +| `fp audits list` | Lista as auditorias. | `--enabled-only`; `--show-id` | +| `fp audits show NAME` | Exibe a definição e o estado de uma auditoria. | — | +| `fp audits create NAME` | Cria uma auditoria e enfileira imediatamente 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 da URL 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` | Reconhece 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 para a fila ativa e limpa a supressão. | — | +| `fp audits assign FINDING_ID` | Define o responsável pelo finding. | `--to ` obrigatório | #### Opções de criação de auditoria @@ -257,94 +261,138 @@ fp audits create checkout-reliability \ | Opção | Descrição | | --- | --- | -| `--file ` | Basear a definição em JSON, ou use `-` para stdin. Flags explícitas substituem os valores do arquivo. | -| `--description ` | Descrever a pergunta de falha ou o propósito. | -| `--enabled` / `--disabled` | Iniciar o agendamento ativado ou desativado. Padrão: ativado. | +| `--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 a finalidade. | +| `--enabled` / `--disabled` | Inicia o agendamento ativado ou desativado. Padrão: ativado. | | `--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` | Continuar após a última janela completamente analisada ou inspecionar repetidamente uma janela contínua. Padrão: `since_last`. | +| `--window-mode since_last\|fixed` | Continua após a última janela totalmente analisada ou inspeciona repetidamente uma janela deslizante. Padrão: `since_last`. | | `--lookback-window-secs ` | `3600`–`7776000`. Padrão: `604800`. | -| `--scope ''` | Filtrar por `environments`, `agent_ids` ou outros campos de escopo suportados. | -| `--ignore-error-type ` | Excluir tipos de erros; repita ou separe por vírgula. | -| `--llm` / `--no-llm` | Ativar ou desativar a análise agêntica. Padrão: ativado. | -| `--top-k ` | Manter `1`–`500` achados. Padrão: `50`. | -| `--sensitivity low\|medium\|high` | Definir a sensibilidade dos relatórios. Padrão: `medium`. | +| `--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` | Ativa ou desativa a análise agêntica. Padrão: ativado. | +| `--top-k ` | Retém `1`–`500` findings. Padrão: `50`. | +| `--sensitivity low\|medium\|high` | Define a sensibilidade dos relatórios. Padrão: `medium`. | | `--channels ''` | Array de canais de notificação. | | `--text ` | Briefing inline, máximo de 8.192 caracteres. | -| `--text-file ` | Ler o briefing de um arquivo; mutuamente exclusivo com `--text`. | -| `--url ` | Adicionar uma referência HTTPS pública; repita até cinco vezes. | +| `--text-file ` | Lê o briefing de um arquivo; mutuamente exclusivo com `--text`. | +| `--url ` | Adiciona 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 de a execução enfileirada começar. +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 do início da execução enfileirada. - `fp audits run` é assíncrono. Consulte `fp audits runs NAME` até que a execução mais recente seja concluída com sucesso ou falhe antes de ler seus achados. + `fp audits run` é assíncrono. Consulte `fp audits runs NAME` até que a execução mais recente seja concluída com sucesso ou falha antes de ler seus findings. -### Problemas +### Issues | Comando | Finalidade | Opções | | --- | --- | --- | -| `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 um alerta. | `--summary` obrigatório; `--title`, `--alert-id`, `--severity` opcionais | -| `fp issues ack INCIDENT_ID` | Confirmar o recebimento de 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 uma 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` | Assinar 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 Cloud +| `fp issues list` | Lista as issues. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | Conta issues abertas ou estados selecionados. | `--state` | +| `fp issues show INCIDENT_ID` | Exibe detalhes, comentários, assinantes e atividade de uma issue. | — | +| `fp issues open` | Abre uma issue manual ou vinculada a um alerta. | `--summary` obrigatório; `--title`, `--alert-id`, `--severity` opcionais | +| `fp issues ack INCIDENT_ID` | Reconhece uma issue. | — | +| `fp issues assign INCIDENT_ID` | Substitui os responsáveis; omita a opção para limpá-los. | `--assignee` repetível | +| `fp issues resolve INCIDENT_ID` | Resolve uma 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` | Inscreve 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 issue avulsa são `info`, `warning` e `critical`. + +### Assistente de nuvem | Comando | Finalidade | Opções | | --- | --- | --- | -| `fp agent health` | Verificar a 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` | +| `fp agent health` | Verifica a disponibilidade e a 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` | + +### Policies + +Versões de políticas gerenciadas na 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`. + +| Comando | Finalidade | Opções | +| --- | --- | --- | +| `fp policies list` | Lista as 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 carrega, 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; uma política que não cobre o evento/ferramenta fornecido é reportada como `skipped` em vez de executada. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | +| `fp policies compose PROMPT` | Rascunha uma política com o assistente. Requer `policies:write`. | — | + +### Fleet + +Quais máquinas executam quais políticas. **Somente sessão**, pelo mesmo motivo acima. + +| Comando | Finalidade | Opções | +| --- | --- | --- | +| `fp fleet list` | Lista as 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 um 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 | + +### Guardrails + +O que a aplicação de políticas realmente fez. **Somente sessão**, pelo mesmo motivo acima. + +| Comando | Finalidade | Opções | +| --- | --- | --- | +| `fp guardrails summary` | Cobertura, totais de bloqueios/avaliações, 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íticas. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | ## Flags globais | Flag | Descrição | | --- | --- | -| `--json` | Emitir JSON legível por máquina. | -| `--base-url ` | Usar um dashboard 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 ` | Tempo limite HTTP; deve ser positivo. Padrão: `30`. | -| `--quiet`, `-q` | Suprimir saída de status no stderr. | -| `--no-color` | Desativar saída colorida. | -| `--insecure` / `--secure` | Desativar ou restaurar a verificação de certificado TLS. | -| `--version` | Imprimir a versão e sair. | -| `--help`, `-h` | Exibir ajuda. | - -`--api-key` é destinado a automações. Login, troca de organização e comandos do assistente requerem uma sessão de usuário. +| `--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. | +| `--timeout ` | Timeout HTTP; deve ser positivo. Padrão: `30`. | +| `--quiet`, `-q` | Suprime a saída de status no stderr. | +| `--no-color` | Desativa a saída colorida. | +| `--insecure` / `--secure` | Desativa ou restaura a verificação do certificado TLS. | +| `--version` | Imprime a versão instalada e encerra. | +| `--help`, `-h` | Exibe a ajuda. | + +`--api-key` é destinado à automação. Login, troca de organização e comandos do assistente requerem uma sessão de usuário. ## Variáveis de ambiente | Variável | Equivalente ou finalidade | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | Realocar o diretório de configuração atual da CLI. | -| `AGENTEYE_ANALYTICS_DISABLED` ou `DO_NOT_TRACK` | Desativar analytics anônimas da CLI. | -| `NO_COLOR` | Desativar 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 `AGENTEYE_ORG`. +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `FP_API_KEY` | `--api-key` | +| `FP_JSON` | `--json` | +| `FP_INSECURE` | `--insecure` | +| `FP_HOME` | Reposiciona o diretório de configuração do CLI (padrão `~/.failproofai/fpcli`). | +| `FP_ANALYTICS_DISABLED` ou `DO_NOT_TRACK` | Desativa a telemetria anônima do CLI. | +| `NO_COLOR` | Desativa a 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`. + + + As variantes `AGENTEYE_*` dessas variáveis **não são lidas pelo `fp`** e nunca foram — o CLI declara `FP_*` (`fp_cli/app.py`), e uma variável desconhecida não é um erro. Definir `AGENTEYE_DASHBOARD_URL` não redireciona o CLI; ela é ignorada e o comando executa silenciosamente contra o dashboard salvo. + + `AGENTEYE_HOME` e `AGENTEYE_ENVIRONMENT` ainda existem, mas pertencem ao **coletor e ao SDK de telemetria**, não a este 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. diff --git a/docs/pt-br/reference/custom-agents.mdx b/docs/pt-br/reference/custom-agents.mdx index 7b8e15834..23bb44313 100644 --- a/docs/pt-br/reference/custom-agents.mdx +++ b/docs/pt-br/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- -title: "Agentes personalizados" -description: "Instrumente traces de agentes personalizados para que o Failproof AI possa reconstruir execuções e encontrar falhas." +title: "Agentes customizados" +description: "Configuração, catálogo de eventos, regras de correlação e entrega para failproofai-sdk." icon: "python" --- -Instrumente traces de um agente personalizado com `failproofai-sdk` para que o Failproof AI possa reconstruir cada execução, auditar seu comportamento e encontrar falhas com evidências. O SDK grava eventos estruturados para que o daemon do Failproof os entregue ao Cloud. Requer Python 3.10 ou mais recente. +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. -O tracing torna agentes personalizados observáveis e auditáveis. Para impedir que uma ação insegura seja executada, também é necessário um hook de aplicação no seu runtime. + + + Instalação, instrumentação, métodos de evento, um exemplo prático e problemas comuns. + + + LangChain, CrewAI, LlamaIndex e Pydantic AI se instrumentam com uma única chamada. + + - - Para aplicar políticas em uma configuração de agente personalizado, [entre em contato com o Failproof AI](mailto:support@befailproof.ai). Vamos ajudá-lo a mapear os limites de modelo, ferramenta e ciclo de vida do seu runtime para hooks de política. - +Python 3.10 ou superior. Sem dependências em tempo de execução. -
- -
- -## Instalar o `failproofai-sdk` - -O SDK é distribuído atualmente como um wheel privado. Consulte seu contato no Failproof AI para obter a versão atual e acesso ao download. +## Instalação ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -Com `uv`, faça o download do wheel primeiro e execute `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl`. Fixe o wheel em um repositório de artefatos privado ou em um arquivo de lock de dependências. - -O pacote é instalado como `failproofai-sdk` e importado no Python como `failproofai`. +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 acompanham o pacote base. ## Conectar o daemon do Failproof 1. Acesse **Admin → Keys** e crie uma chave com `events:add`. - 2. [Conecte o daemon do Failproof ao Cloud](/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 dela em **Observe → Events**. - 4. Acesse **Observe → Sessions**, selecione o mesmo ambiente e abra o trace reconstruído. + 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. Vá em **Observe → Sessions**, selecione o mesmo ambiente e abra o trace reconstruído. - ![Uma sessão de agente Python personalizado reconstruída como grafo de execução e trace de eventos ordenado.](/images/dashboard/session-detail.png) + ![Uma sessão de agente Python customizado reconstruída como grafo de execução e trace de eventos ordenados.](/images/dashboard/session-detail.png) ```bash @@ -51,102 +46,84 @@ O pacote é instalado como `failproofai-sdk` e importado no Python como `failpro -## Instrumentar uma execução completa - -Chame `configure()` uma vez na inicialização do processo. Toda chamada de evento usa apenas argumentos nomeados e requer um `session_id` e um `agent_id` estáveis. +## Configuração ```python -import traceback -import uuid +import failproofai_sdk -import failproofai +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -failproofai.configure(environment="production") +| Argumento | O que faz | +| --- | --- | +| `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 que você quer, a menos que saiba o contrário. | -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +Defina via variável de ambiente: -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) +| Variável | O que faz | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Define `environment` sem alterar o código, para quando o rótulo pertence ao deploy 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 erros de instrumentação lançar exceções em vez de apenas serem registrados. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` faz um problema de compatibilidade com framework lançar exceção em vez de apenas avisar e continuar. | -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + + **Sem vírgulas em `environment`.** A ingestão divide esse campo por vírgulas para construir seus filtros e ignora qualquer evento cujo rótulo contenha uma — portanto, uma execução inteira pode desaparecer silenciosamente. Escreva `prod-eu`, não `prod,eu`. + + `configure(environment="prod,eu")` lança uma exceção para que você descubra imediatamente. `AGENTEYE_ENVIRONMENT` não pode lançar — nada está chamando você — então ele emite um aviso uma vez e volta para `dev`. + -Emita `agent_start` uma vez por ator. Para sub-agentes, reutilize o `session_id` do pai, atribua a cada ator um `agent_id` distinto e defina `parent_id` como o **ID do agente** pai, não o ID da sessão. +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 que ainda não havia sido gravado. -## Referência de configuração +## Identidade + +Cada evento pertence a uma sessão e a um agente. **Os escopos preenchem ambos automaticamente**, portanto raramente é necessário passá-los: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| Configuração | Comportamento | -| --- | --- | -| `base_dir` | Raiz do spool explícita. Tem precedência sobre todas as variáveis de ambiente. | -| `flush_interval` | Segundos entre gravações em segundo plano da memória para JSONL. Padrão: `0.5`. | -| `environment` | Rótulo de implantação em cada evento. Padrão: `dev`. | -| `FAILPROOFAI_HOME` | Altera a raiz do Failproof AI que contém o spool de `custom-agents`. | - -O SDK grava no `base_dir` explícito quando definido. Caso contrário, usa o spool `custom-agents` do daemon do Failproof sob `FAILPROOFAI_HOME` ou `~/.failproofai`. +Passar `session_id` ou `agent_id` explicitamente ainda funciona e tem precedência. Sem nenhum dos dois definido nem passado, a chamada lança `TypeError` em vez de emitir um evento que a Nuvem descartaria silenciosamente. -O SDK enfileira chamadas na memória e grava lotes em uma thread em segundo plano. Ele também tenta um flush final por meio do mecanismo `atexit` do Python. Para workers de curta duração, permita o encerramento normal do interpretador; uma finalização forçada do processo pode perder eventos ainda na memória. + + A identidade trafega em variáveis de contexto. Ela segue tarefas `asyncio` automaticamente, mas **não** novas threads — envolva um worker com `failproofai_sdk.propagate()` ou seus eventos chegarão desvinculados. + ## Catálogo de eventos -Todos os métodos retornam `None`. Campos definidos como `None` são omitidos em vez de serem gravados como `null` no JSON. +Quinze métodos. A maioria vem em **pares** — você chama o abridor, depois o fechador, e o SDK mede o intervalo. -| Método | Campos obrigatórios além da identidade | Campos opcionais | +| | Abre | Fecha | +| --- | --- | --- | +| **Agentes** | `agent_start` | `agent_end` | +| | `agent_pause` | `agent_resume` | +| **Modelos** | `model_request` | `model_response` | +| **Ferramentas** | `tool_use` | `tool_result` | +| **Hooks** | `hook_triggered` | `hook_completed` | +| **Humanos** | `human_wait` | `human_input` | + +Três são independentes: `error`, `human_pause`, `human_interrupt`. + + + +Cada método também aceita `session_id` e `agent_id`, que os escopos preenchem para você. Qualquer campo deixado como `None` é descartado em vez de enviado como `null` em JSON, e cada método retorna `None`. + +| Método | Obrigatório | Opcional | | --- | --- | --- | | `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ Todos os métodos retornam `None`. Campos definidos como `None` são omitidos em | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -Use `outcome="failed"`, `"error"`, `"timeout"` ou `"rejected"` quando uma conclusão deve ser contabilizada como falha. Outros valores, incluindo `"failure"`, não são classificados como falhas pelo backend atual. + + + + Para marcar uma execução como falha, `outcome` deve ser um dos valores: `failed`, `error`, `timeout` ou `rejected`. Qualquer outro valor — incluindo o quase-certo `"failure"` — é contado como sucesso. + + +## Pareamento e duração + +**Uma regra: forneça ao evento de fechamento o mesmo id do seu abridor.** É isso que os vincula e permite ao SDK medir o intervalo. + +| Par | Correspondência por | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**Não passe `duration_ms` você mesmo.** O SDK o mede, e passá-lo lança `ValueError`. -## Regras de correlação e duração +A única exceção é `model_response`, onde só 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. -- 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`. Passar esse valor manualmente para esses métodos gera `ValueError`. -- IDs de ferramentas e hooks compartilham um mapa de pendências único por processo. Torne-os globalmente únicos entre sessões concorrentes e entre ambos os namespaces; IDs de provedores ou UUIDs são as opções mais seguras. -- Um par dividido entre processos ainda se correlaciona downstream, mas o SDK não consegue calcular sua duração em processo. -- O mapa de pendências armazena no máximo 10.000 inícios e descarta a entrada mais antiga quando estiver cheio. + -## Campos e payloads personalizados +- **Os ids precisam ser únicos apenas por tipo, por sessão.** Uma chamada de ferramenta e um hook podem compartilhar o mesmo id; duas sessões rodando simultaneamente 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 corresponde — o que é o caso normal em código multi-agente. +- **`request_id` é opcional, mas recomendado.** Sem ele, os eventos de modelo são pareados na ordem em que chegam, então duas chamadas concorrentes no mesmo agente podem ser pareadas incorretamente. +- **Um par dividido entre processos** ainda corresponde na Nuvem, mas o SDK não consegue medi-lo — 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, para que um vazamento não cresça indefinidamente. -Todos os eventos aceitam campos de palavras-chave extras. Use valores compatíveis com JSON quando consultas downstream precisarem de estrutura. Tipos não suportados como UUIDs, datetimes, decimals, sets, bytes e objetos de modelo são convertidos para string pelo writer. + -Nomes personalizados reservados são `timestamp`, `session_id`, `agent_id`, `type` e `environment`. Erros de digitação em campos opcionais são aceitos como novos campos personalizados, portanto, revise o JSON emitido quando um campo padrão não aparecer no Cloud. +## Seus próprios campos + +Qualquer palavra-chave extra que você passar é armazenada com o 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 +) +``` + +Prefira tipos JSON se quiser consultá-los posteriormente. Qualquer outro tipo — um UUID, um datetime, um `Decimal`, um set, bytes, um objeto de modelo — é armazenado como string. + + + **Use um prefixo nos nomes dos seus campos.** Os extras são aplicados por último, portanto um campo chamado `model`, `tool_name` ou `outcome` sobrescreve silenciosamente o real. Os adaptadores de framework usam `fw_`; faça o mesmo e nada entrará em conflito. + + É também por isso que um campo opcional com erro de digitação nunca gera erro — ele simplesmente se torna um novo campo customizado. 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`. ## Entregar e verificar - 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 pretendida. Use o ID de sessão como chave primária para resolução de problemas. + 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 pretendida. Use o ID da sessão como chave primária de diagnóstico. ```bash @@ -189,10 +203,14 @@ Nomes personalizados reservados são `timestamp`, `session_id`, `agent_id`, `typ -Se o Cloud estiver vazio, inspecione `$FAILPROOFAI_HOME/custom-agents/events`, caso contrário `~/.failproofai/custom-agents/events`. Arquivos JSONL comprovam a emissão pelo SDK; um spool crescente indica problema de configuração do daemon ou de entrega, enquanto um spool vazio indica problema de instrumentação ou de 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 comprovam 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 executa, coleta e exclui cada lote em milissegundos, portanto uma listagem do diretório disputará com o coletor e mostrará muito menos eventos do que foram emitidos. + -## Prevenir falhas em um runtime personalizado +## Prevenir falhas em um runtime customizado -Use os resultados 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 aplicação personalizada deve expor a ação antes da execução, passar sua entrada estruturada para o 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 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. -Envie um e-mail para [support@befailproof.ai](mailto:support@befailproof.ai) para projetar e validar essa integração para o seu runtime. \ No newline at end of file +[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 então validar a integração com você. \ No newline at end of file diff --git a/docs/pt-br/reference/events-and-configuration.mdx b/docs/pt-br/reference/events-and-configuration.mdx index 28ca448cd..ac623a378 100644 --- a/docs/pt-br/reference/events-and-configuration.mdx +++ b/docs/pt-br/reference/events-and-configuration.mdx @@ -6,14 +6,14 @@ icon: "list-tree" ## Famílias de eventos -- Início, fim, pausa e retomada de agente +- Início, fim, pausa e retomada do agente - Requisição e resposta do modelo - Uso de ferramenta e resultado - Hook acionado e concluído - Espera humana, entrada, pausa e interrupção - Erros explícitos -Todo evento carrega um timestamp, ID de sessão, ID de agente, tipo de evento e ambiente. Campos específicos do evento contêm dados de modelo, ferramenta, correlação, resultado, conteúdo, duração ou erro. +Cada evento carrega um timestamp, ID de sessão, ID do agente, tipo de evento e ambiente. Os campos específicos do evento contêm dados de modelo, ferramenta, correlação, resultado, conteúdo, duração ou erro. ## Inspecionar um contrato de evento @@ -21,21 +21,21 @@ Todo evento carrega um timestamp, ID de sessão, ID de agente, tipo de evento e 1. Abra **Observe → Events**. 2. Defina uma janela de tempo curta e filtre por ambiente, agente e tipo de evento. - 3. Selecione um evento para inspecionar seus campos normalizados e payload bruto, depois abra sua sessão para ver o contexto de execução. - 4. Se uma duração pareada estiver ausente, verifique se os eventos de início e conclusão usam o mesmo correlation ID. + 3. Selecione um evento para inspecionar seus campos normalizados e o payload bruto, depois abra sua sessão para ver o contexto de execução. + 4. Se uma duração pareada estiver ausente, verifique se os eventos de início e conclusão usam o mesmo ID de correlação. - Use o stream de Events para restringir os dados a uma execução de agente e inspecione os campos de evento normalizados. + Use o stream de Events para restringir os dados a uma execução de agente e inspecionar os campos de evento normalizados. ![O stream de Events ao vivo com filtros para ambiente, agente, sessão e tipo de evento.](/images/dashboard/events-stream.png) - Em seguida, siga o evento até sua sessão. O trace mostra o que aconteceu imediatamente antes e depois dele, o que é necessário quando o payload sozinho é ambíguo. + Em seguida, siga o evento até sua sessão. O trace mostra o que aconteceu imediatamente antes e depois dele, o que é necessário quando o payload por si só é ambíguo. ![O trace de sessão vinculado usado para inspecionar o evento no contexto de execução.](/images/dashboard/session-detail.png) - Compare os correlation IDs e timestamps em ambas as visualizações quando um evento pareado ou duração estiver ausente. + Compare os IDs de correlação e timestamps nas duas visualizações quando um evento pareado ou duração estiver ausente. - Descubra os valores de filtro válidos e busque os payloads completos dos eventos de uma sessão: + Descubra valores de filtro válidos e depois busque payloads completos de eventos para uma sessão: ```bash fp list event_types @@ -53,13 +53,13 @@ Todo evento carrega um timestamp, ID de sessão, ID de agente, tipo de evento e ## Campos reservados do SDK -Não use `timestamp`, `session_id`, `agent_id`, `type` ou `environment` como campos personalizados do Python SDK. Durações de eventos pareados, como a duração do resultado de ferramenta, são calculadas pelo SDK e não podem ser fornecidas manualmente. +Não use `timestamp`, `session_id`, `agent_id`, `type` ou `environment` como campos personalizados do SDK Python. As durações de eventos pareados, como a duração do resultado de ferramenta, são calculadas pelo SDK e não podem ser fornecidas manualmente. ## Limites locais -- O estado do Failproof AI fica em `~/.failproofai`, a menos que configurado explicitamente de outra forma. -- O `failproofai-sdk` usa `AGENTEYE_HOME` para substituir o diretório base legado. -- Os rótulos de ambiente podem ser definidos por meio da configuração do SDK ou com `AGENTEYE_ENVIRONMENT`. +- O estado do Failproof AI fica em `~/.failproofai`, salvo configuração explícita em contrário. +- O `failproofai-sdk` sempre cria o spool em `~/.failproofai/custom-agents`. A variável `FAILPROOFAI_HOME` realoca esse diretório home; o segmento `custom-agents` é sempre acrescentado, portanto o spool não pode ser colocado fora dele. Apenas o próprio `configure(base_dir=...)` do SDK grava em outro local. A variável `AGENTEYE_HOME` é lida pelo `agenteye-collector` mais antigo para escolher o que monitorar, e não afeta mais onde o SDK escreve. +- Os rótulos de ambiente podem ser definidos por meio da configuração do SDK ou via `AGENTEYE_ENVIRONMENT`. - As credenciais do daemon são armazenadas separadamente das configurações não secretas. Use nomes de ambiente estáveis e de baixa cardinalidade. Vírgulas não são suportadas nos rótulos de ambiente do daemon. @@ -68,7 +68,7 @@ Use nomes de ambiente estáveis e de baixa cardinalidade. Vírgulas não são su - Os rótulos de ambiente são atribuídos pelo SDK emissor ou pelo daemon Failproof. Após alterar um, abra **Observe → Sessions** e use o filtro de ambiente para confirmar que as novas sessões carregam o novo valor. As sessões existentes mantêm seu ambiente original. + Os rótulos de ambiente são atribuídos pelo SDK emissor ou pelo daemon do Failproof. Após alterar um rótulo, abra **Observe → Sessions** e use o filtro de ambiente para confirmar que as novas sessões carregam o novo valor. As sessões existentes mantêm seu ambiente original. diff --git a/docs/pt-br/reference/harnesses.mdx b/docs/pt-br/reference/harnesses.mdx index 1294811ba..d960caedb 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 em que seu agente efetivamente executa. O Failproof AI suporta doze deles, em duas categorias: +Um harness é o ambiente em que seu agente realmente executa. O Failproof AI suporta doze deles, em duas classes: - **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 assistente** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistente auto-hospedado) -As mesmas políticas e o mesmo histórico de sessões se aplicam independentemente do harness em que o agente é executado. 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. +As mesmas políticas e o mesmo histórico de sessões se aplicam independentemente do harness em que um agente executa. 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 é executado em **nenhum** dos doze é instrumentado diretamente com o [Python SDK](/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 de sua execução requer um hook de aplicação na fronteira de ferramenta do seu runtime; [entre em contato conosco](mailto:support@befailproof.ai) e faremos o mapeamento. +Um agente que não executa em **nenhum** dos doze é instrumentado diretamente com o [Python SDK](/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 no limite de ferramenta do seu runtime; [entre em contato conosco](mailto:support@befailproof.ai) e faremos o mapeamento. | Harness | Escopos de hook suportados | | --- | --- | @@ -20,49 +20,49 @@ Um agente que não é executado em **nenhum** dos doze é instrumentado diretame | Factory Droid, Devin CLI, Antigravity CLI, Goose | Usuário, projeto | | Hermes, OpenClaw | Usuário | -Cada integração normaliza seus nomes de eventos de hook nativos, nomes de ferramentas e campos de entrada de ferramentas antes da execução das políticas. Uma política só pode atuar 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 seus 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 na versão exatos que você implanta. ## Capacidade de aplicação -"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 consegue 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 apenas ou não bloqueantes | +| 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 da sessão, notificações e eventos pós-falha são apenas observacionais. | +| 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. | | 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, e não uma barreira verificada. | +| OpenCode | `PreToolUse` | Eventos pós-ferramenta e de ciclo de vida são observacionais; o tratamento de stop atual é orientação para um turno posterior, não uma barreira verificada. | | 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` | Os veredictos de pós-ferramenta, sessão e subagent-stop não são barreiras. | -| 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` | Os veredictos pós-ferramenta e subagent-stop são observacionais. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condicional | Os 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` | Os 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. Um hook de stop de bloqueio nativo existe upstream, mas não é instalado pelo adaptador atual. | +| Hermes | `PreToolUse` | Veredictos pós-ferramenta, de sessão e de subagent-stop não são barreiras. | +| 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` | Veredictos pós-ferramenta e de 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` | Veredictos 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. Um hook de stop nativo com bloqueio existe upstream, mas não é instalado pelo adaptador atual. | -As capacidades são sensíveis à versão. Refaça os testes após atualizar um CLI de agente, especialmente quando uma política depende do comportamento de prompt, stop, permissão ou pós-ferramenta em vez da barreira comum pré-ferramenta. +As capacidades dependem da versão. Realize testes novamente 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 da barreira pré-ferramenta comum. ## Instalar hooks de captura e política - 1. Abra **Administração → Chaves** e crie uma chave com `events:add` e `policies:pull`, nomeada para a máquina ou ambiente. - 2. Na máquina de destino, conecte o CLI local com a chave exibida e instale os hooks de harness. + 1. Abra **Administração → Chaves** e crie uma chave com `events:add` e `policies:pull`, com nome referente à máquina ou ambiente. + 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 **Observar → Eventos**. - 4. Abra **Observar → política** para a mesma janela de tempo e confirme que uma decisão de política está atribuída à máquina. + 4. Abra **Observar → política** para o mesmo intervalo de tempo e confirme que uma decisão de política está atribuída à máquina. - A conexão começa com uma chave de máquina. Confirme que ela inclui permissões de ingestão e de entrega de políticas antes de copiar o segredo. + A conexão começa com uma chave de máquina. Confirme que ela inclui permissões de ingestão e entrega de políticas antes de copiar o segredo. - ![O painel 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) + ![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 Eventos deve mostrar novos eventos da máquina e do ambiente que você conectou. + Após instalar os hooks, o stream de Eventos deve exibir novos eventos da máquina e do ambiente que você conectou. ![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ítica, além de eventos de rastreamento. - ![A página de Política usada para verificar as decisões de política de um harness recém-conectado.](/images/dashboard/policy-observe.png) + ![A página de Política 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: @@ -74,7 +74,7 @@ As capacidades são sensíveis à versão. Refaça os testes após atualizar um failproofai policies --install ``` - Ou selecione harnesses específicos e um escopo de configuração: + Ou direcione harnesses específicos e um escopo de configuração: ```bash failproofai policies --install \ @@ -82,7 +82,7 @@ As capacidades são sensíveis à versão. Refaça os testes após atualizar um --scope user ``` - O escopo de projeto mantém a configuração de hook junto com um repositório. O escopo de usuário cobre o trabalho em todos os repositórios. Claude Code também suporta escopo local; o suporte varia por harness e o CLI rejeita combinações não suportadas. + O escopo de projeto mantém a configuração de hooks com um 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,12 +98,12 @@ As capacidades são sensíveis à versão. Refaça os testes após atualizar um - Caminhos extras são registrados na máquina, não na nuvem. Após adicionar um, abra **Observar → Sessões**, 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. + Caminhos extras são registrados na máquina, não na nuvem. Após adicionar um, abra **Observar → Sessões**, 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 dos eventos antes de utilizá-la em uma auditoria. - ![A lista de Sessões filtrada pelo ambiente que está recebendo dados do caminho de captura adicional.](/images/dashboard/sessions-list.png) + ![A lista de Sessões filtrada para o ambiente que recebe dados do caminho de captura adicional.](/images/dashboard/sessions-list.png) - Adicione um caminho com um rótulo opcional e, em seguida, inspecione os caminhos configurados: + Adicione um caminho com um rótulo opcional e inspecione os caminhos configurados: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -117,5 +117,5 @@ As capacidades são sensíveis à versão. Refaça os testes após atualizar um - Execute uma nova sessão após a instalação. Verifique tanto o stream de eventos ao vivo quanto uma decisão de política real antes de expandir o rollout. + Execute uma nova sessão após a instalação. Verifique tanto o stream de eventos ao vivo quanto uma decisão de política real antes de expandir a implantação. \ No newline at end of file diff --git a/docs/pt-br/reference/overview.mdx b/docs/pt-br/reference/overview.mdx index 53315c312..8da36d7b0 100644 --- a/docs/pt-br/reference/overview.mdx +++ b/docs/pt-br/reference/overview.mdx @@ -1,32 +1,35 @@ --- title: "Integrações e referência" -description: "Conecte harnesses de agentes, SDKs, CLIs e a API HTTP compatíveis." +description: "Conecte harnesses de agentes, SDKs, CLIs e a API HTTP suportados." icon: "braces" --- -Escolha a integração mais próxima de onde seu agente já está sendo executado. +Escolha a integração mais próxima de onde seu agente já está em execução. - Instale hooks para CLIs de agentes autônomos e de codificação compatíveis. + Instale hooks para CLIs de codificação e agentes autônomos suportados. - - Instrumente traces para encontrar falhas em agentes personalizados e entre em contato conosco para adicionar prevenção ao seu runtime. + + Instrumente LangGraph, CrewAI, LlamaIndex, Pydantic AI ou um agente personalizado. + + + Configuração, catálogo de eventos, regras de correlação e entrega. Revise projetos locais, sessões, atividade de políticas e auditorias offline. - + 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. - + Pontue sessões completas ou inativas com um serviço FastAPI. - Crie e teste decisões de allow, instruct e deny específicas para seu fluxo de trabalho. + Crie e teste decisões de allow, instruct e deny específicas para cada fluxo de trabalho. Implante o plano de controle do Cloud em um cluster Kubernetes gerenciado pelo cliente. @@ -35,24 +38,24 @@ Escolha a integração mais próxima de onde seu agente já está sendo executad 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 dados +## Conectar um agente e verificar os 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 chegam, 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 pelas auditorias. + 3. Abra **Observe → Events** para confirmar que os eventos chegam, depois **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 as 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 chave. As permissões selecionadas determinam se a máquina pode enviar eventos e receber políticas gerenciadas pelo Cloud. - ![O painel 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) + ![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 os 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 do agente.](/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 trace deve conter o modelo, a ferramenta, o erro e as evidências de política necessárias para suas auditorias. + Abra uma dessas sessões antes de considerar a integração concluída; o trace 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. @@ -71,8 +74,8 @@ A [referência da API HTTP](/pt-br/reference/http-api) gerada cobre a superfíci fp events --since 1h --env production --limit 20 ``` - Use `fp --json sessions ...` quando outro utilitário consumir o resultado. Flags globais como `--json`, `--org` e `--base-url` devem vir antes do comando. + Use `fp --json sessions ...` quando outra ferramenta precisar consumir o resultado. Flags globais como `--json`, `--org` e `--base-url` devem vir antes do comando. - Consulte a [referência do Failproof AI CLI](/pt-br/reference/failproof-cli) para comandos locais e a [referência do Failproof Cloud CLI](/pt-br/reference/cloud-cli#cli-commands) para comandos `fp`. + Consulte a [referência da CLI do Failproof AI](/pt-br/reference/failproof-cli) para comandos locais e a [referência da CLI do Failproof Cloud](/pt-br/reference/cloud-cli#cli-commands) para comandos `fp`. \ No newline at end of file diff --git a/docs/pt-br/reference/troubleshooting.mdx b/docs/pt-br/reference/troubleshooting.mdx index 637b92802..864d450c8 100644 --- a/docs/pt-br/reference/troubleshooting.mdx +++ b/docs/pt-br/reference/troubleshooting.mdx @@ -1,16 +1,16 @@ --- title: "Solução de Problemas" -description: "Diagnostique sessões ausentes, políticas ausentes, falhas na entrega e ações bloqueadas do agente." +description: "Diagnose sessões ausentes, políticas ausentes, falhas de entrega e ações de agente bloqueadas." icon: "wrench" --- - + - Abra **Administração → Chaves** e confirme que a chave da máquina está ativa e possui `events:add`. Em seguida, abra **Observar → Eventos**, amplie o intervalo de tempo e limpe os filtros de ambiente e agente. Se houver eventos, pesquise o ID da sessão e verifique **Observar → Sessões** para agrupamento. Se não houver eventos, diagnostique o daemon do Failproof pela CLI. + Abra **Administração → Keys** e confirme que a chave da máquina está ativa e possui `events:add`. Em seguida, abra **Observe → Events**, amplie o intervalo de tempo e limpe os filtros de ambiente e agente. Se existirem eventos, pesquise o ID da sessão e verifique **Observe → Sessions** para agrupamento. Se não houver eventos, diagnostique o daemon do Failproof pela CLI. - ![O stream de Eventos ao vivo com seus filtros principais visíveis e eventos recentes do agente chegando.](/images/dashboard/events-stream-current.png) + ![O stream de eventos ao vivo com seus filtros principais visíveis e eventos de agentes recentes chegando.](/images/dashboard/events-stream-current.png) ```bash @@ -25,10 +25,10 @@ icon: "wrench" - + - Limpe os filtros em **Observar → Eventos** e pesquise o ID exato da sessão do SDK. Se nada aparecer, inspecione o spool do SDK e o daemon do Failproof na máquina de origem. + Limpe os filtros em **Observe → Events** e pesquise pelo ID exato da sessão do SDK. Se nada aparecer, inspecione o spool do SDK e o daemon do Failproof na máquina de origem. ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - Confirme que o processo do agente define `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` e que `$FAILPROOFAI_HOME/custom-agents`, ou `~/.failproofai/custom-agents`, existe antes de o SDK ser iniciado. + Confirme que um daemon está em execução e conectado — o SDK faz spool independentemente disso. O diretório de spool **não** precisa existir previamente (o escritor o cria), e nenhuma variável de ambiente o seleciona: `$FAILPROOFAI_HOME/custom-agents`, ou `~/.failproofai/custom-agents` como alternativa, é a única raiz, e `configure(base_dir=...)` é a única substituição. Se o processo foi encerrado com `SIGKILL` ou por falta de memória (OOM), tudo que ainda estava na fila foi perdido — trate `SIGTERM` para limitar esse risco. - Abra **Admin → enforcement**, selecione a máquina e compare suas versões atribuída, reportada e anterior. Confirme que o escopo de implantação inclui a máquina e que sua chave possui `policies:pull`. A ingestão pode funcionar mesmo quando a entrega de políticas não funciona. + Abra **Admin → enforcement**, selecione a máquina e compare as versões atribuída, reportada e anterior. Confirme que o escopo de implantação inclui a máquina e que sua chave possui `policies:pull`. A ingestão pode funcionar mesmo quando a entrega de políticas falha. @@ -60,7 +60,7 @@ icon: "wrench" - Abra **Admin → enforcement** e inspecione o horário da última visualização da máquina e a versão reportada. Se a máquina estiver desatualizada, trate isso como um problema local do daemon. Não enfraqueça a política implantada apenas para contornar um daemon indisponível. + Abra **Admin → enforcement** e inspecione o horário da última vez que a máquina foi vista e a versão reportada. Se a máquina estiver desatualizada, trate isso como um problema de daemon local. Não enfraqueça a política implantada apenas para contornar um daemon indisponível. @@ -71,14 +71,14 @@ icon: "wrench" failproofai config --status ``` - Reinicie ou atualize o `failproofaid`; execute novamente a configuração quando as versões de protocolo da CLI e do daemon diferirem. O caminho do daemon configurado falha de forma fechada por design. + Reinicie ou atualize o `failproofaid`; execute novamente a configuração quando as versões de protocolo da CLI e do daemon forem diferentes. O caminho de daemon configurado falha de forma fechada por design. - Para uma política criada na Cloud, abra **Admin → policy editor**, selecione o rascunho e revise os erros de validação antes de publicar. Para uma política local, use a CLI para validá-la e, em seguida, abra **Observar → policy** após uma ação de teste para confirmar que as decisões chegam. + Para uma política criada no Cloud, abra **Admin → policy editor**, selecione o rascunho e revise os erros de validação antes de publicar. Para uma política local, use a CLI para validá-la e abra **Observe → policy** após uma ação de teste para confirmar que as decisões chegam. @@ -91,12 +91,12 @@ icon: "wrench" - + - Abra **Analisar → auditorias**, selecione a execução e verifique se a análise do modelo foi executada. Em seguida, compare seu escopo e janela com **Observar → sessões** e abra rastros representativos dessa população. + Abra **Analyze → audits**, selecione a execução e verifique se a análise do modelo foi executada. Em seguida, compare seu escopo e janela com **Observe → sessions** e abra traces representativos dessa população. - Um resultado zero só é significativo quando a análise foi executada com sucesso. Se a análise foi ignorada ou falhou, a execução não produz resultados e mantém a janela não analisada aberta para uma futura execução bem-sucedida. Se a análise do modelo estiver desabilitada, a auditoria também não produz resultados, pois a verificação determinística de credenciais e PII registra estatísticas, mas não gera mais resultados. + Um resultado zero só é significativo quando a análise foi executada com sucesso. Se a análise foi ignorada ou falhou, a execução não produz nenhuma descoberta e mantém a janela não analisada aberta para uma futura execução bem-sucedida. Se a análise do modelo estiver desabilitada, a auditoria também não produz nenhuma descoberta, pois o escaneamento determinístico de credenciais e PII registra estatísticas, mas não gera mais descobertas. ![O formulário de auditoria onde ambiente, agente, cadência e janela de varredura definem a população de sessões.](/images/dashboard/audit-new.png) @@ -110,31 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - Se a execução ficou na fila, aguarde a capacidade do agente de auditoria ou peça ao operador de implantação para inspecionar a frota de auditoria. Uma auditoria na fila é reexecutada; ela não é descartada imediatamente. + Se a execução ficou na fila, aguarde a capacidade do agente de auditoria ou peça ao operador de implantação para inspecionar a frota de auditoria. Uma auditoria na fila é reprocessada; ela não é ignorada imediatamente. - Abra uma sessão concluída e verifique se uma avaliação manual é bem-sucedida. A Cloud hospedada atualmente não possui controle de endpoint do avaliador no dashboard; o operador do servidor deve configurá-lo. + Abra uma sessão concluída e verifique se uma avaliação manual é bem-sucedida. O Cloud hospedado atualmente não possui controle de endpoint do avaliador no dashboard; o operador do servidor deve configurá-lo. - Verifique o próprio avaliador e, em seguida, inspecione os estados de avaliação recentes: + Verifique o próprio avaliador e inspecione os estados de avaliação recentes: ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - Na Cloud auto-hospedada, confirme que `EVALUATOR_ENDPOINT` está presente no servidor e que `EVALUATOR_TOKEN` corresponde ao avaliador. A avaliação automática é desabilitada quando o endpoint está ausente. + No Cloud auto-hospedado, confirme que `EVALUATOR_ENDPOINT` está presente no servidor e que `EVALUATOR_TOKEN` corresponde ao avaliador. A avaliação automática é desabilitada quando o endpoint está ausente. - + - Use o seletor de organização e confirme o slug e as permissões esperados antes de comparar os resultados com a CLI. + Use o seletor de organização e confirme o slug esperado e as permissões antes de comparar os resultados com a CLI. ```bash @@ -143,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - No modo de chave de API, especifique `fp --org --api-key ...` ou defina `AGENTEYE_ORG`. O estado de organização de sessão humana salvo é intencionalmente ignorado para requisições com chave de API. + No modo de chave de API, especifique `fp --org --api-key ...` ou defina `AGENTEYE_ORG`. O estado de organização de sessão humana salva é intencionalmente ignorado para requisições com chave de API. - Abra **Observar → policy**, preserve a decisão e a sessão vinculada, e identifique a condição de falso positivo. Em seguida, abra **Admin → enforcement** e reverta as máquinas afetadas para a versão anterior. Crie uma versão mais restrita no **Policy editor**, teste-a em um escopo pequeno e expanda apenas após o trabalho válido ser bem-sucedido. + Abra **Observe → policy**, preserve a decisão e a sessão vinculada, e identifique a condição de falso positivo. Em seguida, abra **Admin → enforcement** e faça o rollback das máquinas afetadas para a versão anterior. Crie uma versão mais restrita no **Policy editor**, teste-a em um escopo pequeno e expanda somente após o trabalho válido ser bem-sucedido. - O rollback de implantação na Cloud é exclusivo do dashboard. Uma pausa de sessão local não desabilita políticas gerenciadas pela Cloud. Se o dashboard estiver indisponível, capture o estado da máquina e da implantação e restaure o acesso ao dashboard em vez de tentar repetidamente a ação bloqueada. + O rollback de implantação no Cloud é feito exclusivamente pelo dashboard. Uma pausa de sessão local não desabilita as políticas gerenciadas pelo Cloud. Se o dashboard estiver indisponível, capture o estado da máquina e da implantação e restaure o acesso ao dashboard em vez de repetir continuamente a ação bloqueada. ```bash failproofai config --status @@ -164,4 +164,4 @@ icon: "wrench" -Ao entrar em contato com o suporte, inclua a versão da CLI, o harness, o ambiente, o ID relevante da sessão ou implantação, e a saída de `failproofai config --status` com os segredos removidos. \ No newline at end of file +Ao entrar em contato com o suporte, inclua a versão da CLI, o harness, o ambiente, o ID de sessão ou implantação relevante e a saída de `failproofai config --status` com os segredos removidos. \ No newline at end of file diff --git a/docs/pt-br/sessions/live-events.mdx b/docs/pt-br/sessions/live-events.mdx index 96309bb15..8382f1df1 100644 --- a/docs/pt-br/sessions/live-events.mdx +++ b/docs/pt-br/sessions/live-events.mdx @@ -1,21 +1,21 @@ --- -title: "Eventos em tempo real" -description: "Acompanhe a atividade do agente enquanto uma sessão está em execução." +title: "Eventos ao vivo" +description: "Acompanhe a atividade do agente em tempo real enquanto uma sessão está em execução." icon: "radio" --- -Os eventos em tempo real ajudam você a confirmar a instrumentação e acompanhar uma execução arriscada sem precisar aguardar o término da sessão. +Os eventos ao vivo ajudam você a confirmar a instrumentação e acompanhar uma execução de risco sem precisar esperar o término da sessão. -## Monitorar atividade +## Acompanhar atividade 1. Acesse **Observe → Events**. 2. Comece com a janela de tempo atual e sem filtros para confirmar que os dados estão chegando. - 3. Filtre por ambiente, tipo de evento, agente ou sessão. Use a busca para texto no payload. - 4. Selecione um evento para inspecionar seu resumo e detalhes. Siga o link da sessão para o rastreamento completo. + 3. Filtre por ambiente, tipo de evento, agente ou sessão. Use a busca para pesquisar texto no payload. + 4. Selecione um evento para inspecionar seu resumo e detalhes. Siga o link da sessão para ver o rastreamento completo. - ![O stream de eventos ao vivo mostrando tráfego de um gateway de chat Hermes ao lado de execuções de CLI de codificação, filtrado por tempo, ambiente, tipo de evento, agente, modelo, contexto e sessão.](/images/dashboard/events-stream-current.png) + ![O stream de eventos ao vivo exibindo tráfego de um gateway de chat Hermes junto com execuções do coding-CLI, filtrado por tempo, ambiente, tipo de evento, agente, modelo, contexto e sessão.](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +24,22 @@ Os eventos em tempo real ajudam você a confirmar a instrumentação e acompanha fp --json events --full --session-id --all ``` - O feed padrão omite os payloads brutos. Use `--full` apenas para investigações limitadas a uma sessão específica. + O feed padrão omite os payloads brutos. Use `--full` apenas para investigar uma sessão com escopo delimitado. Use o stream de eventos para responder três perguntas imediatas: -- O agente esperado está reportando ao ambiente correto? +- O agente esperado está reportando para o ambiente correto? - As chamadas de modelo, chamadas de ferramenta e decisões de política estão chegando na ordem correta? - A sessão parou de progredir ou começou a repetir uma ação? -Os tipos de evento incluem eventos de ciclo de vida do agente, requisições e respostas de modelo, uso de ferramentas e resultados, execução de hooks, esperas e interrupções humanas, e erros explícitos. IDs de correlação conectam eventos pareados, como uma chamada de ferramenta e seu resultado. +Os tipos de evento incluem eventos do ciclo de vida do agente, requisições e respostas de modelo, uso de ferramentas e resultados, execução de hooks, esperas e interrupções humanas, e erros explícitos. IDs de correlação associam eventos pareados, como uma chamada de ferramenta e seu resultado. Mantenha a visualização ao vivo ampla enquanto verifica uma nova integração. Adicione filtros somente após ver o primeiro evento; um filtro incorreto pode parecer uma falha na ingestão. -Se nenhum evento aparecer, execute `failproofai config --status` e depois [solucione problemas de ingestão](/pt-br/reference/troubleshooting). +Se nenhum evento aparecer, execute `failproofai config --status` e então [solucione problemas de ingestão](/pt-br/reference/troubleshooting). -Agentes que não executam em um dos 12 [harnesses](/pt-br/reference/harnesses) suportados reportam os mesmos tipos de evento através do [Python SDK](/pt-br/reference/custom-agents), incluindo os eventos de humano no loop (`human_wait`, `human_input`, `human_interrupt`) dos quais os agentes de gateway e produção dependem. \ No newline at end of file +Agentes que não executam em um dos 12 [harnesses](/pt-br/reference/harnesses) suportados reportam os mesmos tipos de evento por meio do [Python SDK](/pt-br/reference/custom-agents), incluindo os eventos de human-in-the-loop (`human_wait`, `human_input`, `human_interrupt`) dos quais os agentes de gateway e produção dependem. \ No newline at end of file diff --git a/docs/pt-br/start/first-policy.mdx b/docs/pt-br/start/first-policy.mdx index b80bf64d6..a9d8a50ce 100644 --- a/docs/pt-br/start/first-policy.mdx +++ b/docs/pt-br/start/first-policy.mdx @@ -1,28 +1,28 @@ --- title: "Previna sua primeira falha com uma política" -description: "Crie uma versão de política, implante-a no modo de observação e depois aplique a execução." +description: "Crie uma versão de política, implante-a em modo de observação e depois a aplique." icon: "shield-check" --- -Use uma política somente depois que você conseguir descrever a ação insegura e as ações legítimas que precisam continuar permitidas. +Use uma política somente depois de conseguir descrever a ação insegura e as ações legítimas que devem continuar sendo permitidas. - - Acesse **Admin → editor de políticas**. Comece com a política de demonstração, revise ou edite o código-fonte e selecione **publicar versão**. A publicação cria a versão imutável que você pode implantar nas máquinas. + + Vá para **Admin → policy editor**. Comece com a política de demonstração, revise ou edite seu código-fonte e, em seguida, selecione **publish version**. A publicação cria a versão imutável que você pode implantar nas máquinas. - ![A visão de composição do editor de políticas com uma política de demonstração pronta para ser publicada como uma versão imutável.](/images/dashboard/policy-editor.png) + ![The Policy editor compose view with a demo policy ready to publish as an immutable version.](/images/dashboard/policy-editor.png) - - Acesse **Admin → enforcement**, expanda a máquina de destino e selecione **editar esta máquina**. Adicione a política de demonstração publicada, fixe sua versão, escolha **observe** e aplique a implantação. + + Vá para **Admin → enforcement**, expanda a máquina de destino e selecione **edit this machine**. Adicione a política de demonstração publicada, fixe sua versão, escolha **observe** e aplique a implantação. - ![O editor de implantação de máquina com uma versão de política publicada selecionada no modo de observação antes de aplicar a implantação.](/images/dashboard/enforcement-editor.png) + ![The machine deployment editor with a published policy version selected in observe mode before applying the deployment.](/images/dashboard/enforcement-editor.png) - - Execute uma nova sessão de agente nessa máquina e abra **Observe → política**. Selecione a máquina e confirme que a política de demonstração aparece no mapeamento de políticas e na linha do tempo de decisões. O modo de observação registra o que a política faria sem bloquear a ação. + + Execute uma nova sessão de agente nessa máquina e, em seguida, abra **Observe → policy**. Selecione a máquina e confirme que a política de demonstração aparece no mapeamento de políticas e na linha do tempo de decisões. O modo de observação registra o que a política faria sem bloquear a ação. - ![A página de Política mostrando totais de decisões, atividade de execução ao longo do tempo e mapeamentos de políticas locais e gerenciadas pela nuvem.](/images/dashboard/policy-observe.png) + ![The Policy page showing decision totals, enforcement activity over time, and local and Cloud-managed policy mappings.](/images/dashboard/policy-observe.png) @@ -35,13 +35,13 @@ Use uma política somente depois que você conseguir descrever a ação insegura failproofai config --status ``` - Use `fp` para inspecionar as decisões de política visíveis na nuvem: + Use `fp` para inspecionar decisões de política visíveis na nuvem: ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - O CLI da nuvem não expõe rotas de implantação de execução exclusivas para administradores. Publique versões em **Admin → editor de políticas** e implante-as em **Admin → enforcement**. + Ambas as etapas também estão disponíveis pelo CLI: `fp policies publish ` cria uma versão e `fp fleet deploy --add ` a coloca em uma máquina. Os equivalentes no dashboard são **Admin → policy editor** e **Admin → enforcement**. \ No newline at end of file diff --git a/docs/pt-br/start/integrations.mdx b/docs/pt-br/start/integrations.mdx new file mode 100644 index 000000000..c35fd1cb7 --- /dev/null +++ b/docs/pt-br/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "Instrumente seu agente" +sidebarTitle: "Frameworks" +description: "Conecte qualquer framework de agente compatível ao Failproof AI com uma única chamada." +icon: "plug" +--- + +Seu agente já produz tudo que vale a pena registrar — chamadas de modelo, chamadas de ferramenta, limites de nós, esperas humanas, falhas. O framework descarta tudo isso. O SDK preserva. + + + + Um agente que você mesmo escreveu, ou um que não está listado aqui. + + + Grafos, nós, ferramentas, retrievers, modelos. + + + Crews, fluxos, agentes por papel, ferramentas. + + + Workflows, etapas, function agents, retrievers. + + + Agentes tipados, capacidades, ferramentas, retentativas. + + + +## Três linhas, qualquer framework + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # detecta os frameworks que você importou + +with failproofai_sdk.session(): + ... # sua chamada de agente existente, sem alterações +``` + +Sem decoradores nas suas funções, sem callbacks passados para suas chamadas, sem IDs espalhados pelo seu código. Apenas a chamada dentro da sessão é diferente: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # dentro de `async with failproofai_sdk.session():` + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +O extra instala o **framework**. Todos os adaptadores já estão incluídos no pacote base, então um projeto que já possui seu framework não precisa de nenhum extra. + +## Verifique se chegou + +Execute uma sessão instrumentada e, em seguida, abra **Observe → Sessions** e selecione seu ambiente. A execução aparece como um trace reconstruído. + +Se nada chegar, confirme que a máquina está conectada com `failproofai config --status`. Consulte [Configurar captura](/pt-br/start/setup). + + + Não verifique o diretório de spool para confirmar a entrega. O daemon do Failproof coleta e exclui cada lote em milissegundos, então ler esse diretório compete com o coletor e exibe muito menos eventos do que foram emitidos. + + +## Próximos passos + +Cada quickstart acima leva ao seu guia completo — o que é registrado, opções, streaming, nomenclatura de spans e os problemas que as pessoas realmente encontram. Eles ficam em **Trace Agents → Plug in your agent**. + + + + O modelo de dados, os IDs, os tipos de eventos e como os eventos chegam à Cloud. + + + Acompanhe a causalidade ao longo de uma sessão em vez de logs desconectados. + + + Audite as sessões que você acabou de capturar. + + \ No newline at end of file diff --git a/docs/pt-br/start/integrations/crewai.mdx b/docs/pt-br/start/integrations/crewai.mdx new file mode 100644 index 000000000..33adadabb --- /dev/null +++ b/docs/pt-br/start/integrations/crewai.mdx @@ -0,0 +1,224 @@ +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "Instrumente crews, flows, agentes por papel, ferramentas, memória e feedback humano." +icon: "/images/frameworks/crewai.svg" +--- + +## Instalação + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +Suportado: `crewai` 1.13 a 2.0. A versão 1.13 foi a que adicionou `started_event_id` e normalizou o uso de tokens — ambos os quais o adaptador utiliza para parear eventos e reportar tokens. + +## Instrumentação + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` registra um listener no barramento de eventos de nível de módulo do CrewAI e inscreve um handler por classe de evento. Nada na sua crew, agentes, tarefas ou ferramentas é alterado. + +## O que é registrado + +| CrewAI | Evento Failproof | +| --- | --- | +| Kickoff de crew | `agent_start`, `agent_end` | +| `Agent.kickoff()` (agente lite, sem crew) | `agent_start`, `agent_end`, com `agent_id` derivado do papel | +| Início e fim de flow | `agent_start`, `agent_end`; uma crew iniciada dentro de um método de flow é aninhada sob ele | +| Execução de agente | `agent_start`, `agent_end` aninhados, com `agent_id` derivado do papel. Em um processo hierárquico, um colaborador delegado é aninhado sob o gerente, não ao lado dele | +| Tarefa | Nada; registrada como link para que os filhos resolvam para a crew | +| Método de flow, guardrail | `hook_triggered`, `hook_completed` | +| Uso de ferramenta | `tool_use`, `tool_result` | +| Operações de memória e conhecimento | `tool_use`, `tool_result`, nomeados pela camada acessada | +| Chamada LLM | `model_request`, `model_response`, com uso de tokens | +| Chunk de stream | Incorporado na resposta como contagem de chunks e tempo até o primeiro token | +| Feedback humano solicitado | `human_wait`, `agent_pause` | +| Feedback humano recebido | `agent_resume`, `human_input` | +| Erro na execução do agente | `error`, seguido de `agent_end` com resultado `failed` | + +Uma tarefa não emite nada intencionalmente. Uma tarefa do CrewAI é um subconjunto da execução do agente que a executa; emitir ambos duplicaria cada linha e os renderizaria como irmãos. O id e o nome da tarefa são carregados nos próprios eventos do agente. + +Operações de memória e conhecimento são registradas como ferramentas, nomeadas pela camada que acessam, para que apareçam ao lado das suas ferramentas reais e você possa comparar a latência. + +Em uma crew hierárquica, o aninhamento é o que torna o trace legível: + +```text +crew +└─ manager + ├─ researcher delegado + └─ writer delegado +``` + +O CrewAI associa uma execução delegada ao evento de **ferramenta** `delegate_work_to_coworker`, não diretamente ao gerente, então o adaptador segue esse link. Sem ele, cada agente aparece como irmão de todos os outros e a estrutura de delegação se perde. + +## Exemplo + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # torna-se agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +A transição entre agentes fica visível no trace: o span do `analyst` fecha, o span do `writer` abre, e ambos ficam dentro de um único span `crew`. + +## Nomeie seus spans + +`agent_id` vem de `Agent(role=...)`, o que o torna uma faceta legível no dashboard. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # uma entrada de faceta por execução +``` + +`agent_id` é uma coluna de baixa cardinalidade. Um papel que contenha um id de execução ou timestamp a degrada para todas as consultas que qualquer pessoa execute. Se um papel parecer um id, o adaptador o rejeita e coloca o valor real em um campo de payload. + +## Controle a sessão + +Resolvido nesta ordem, prevalecendo a primeira correspondência: + +1. `instrument("crewai", session_id=...)` +2. O escopo `failproofai_sdk.session()` envolvente +3. Um `uuid4().hex` gerado automaticamente, uma vez por crew ou flow + +Envolva o kickoff para controlar por execução: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## Opções + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # fixa todas as execuções em um único session id +) +``` + +`session_id` é a única opção que este adaptador lê. Prompts e completions são sempre registrados, truncados ao limite de payload. + +## Human in the loop + +O CrewAI possui **duas** superfícies de human-in-the-loop, e ambas são registradas com os mesmos quatro eventos. + +`@human_feedback` em um método de flow passa pelo barramento de eventos do CrewAI: o runtime emite um evento antes de aguardar uma pessoa e outro após a resposta. + +`Task(human_input=True)` não. Ele chama `input()` dentro do próprio provedor de entrada do CrewAI e não emite nenhum evento, portanto o adaptador envolve esse provedor diretamente — sem isso, toda a espera humana ficaria invisível e seria contabilizada como tempo ativo do agente. + +De qualquer forma, você obtém: + +```text +human_wait o prompt e suas opções +agent_pause inicia o contador de tempo pausado +agent_resume para o contador +human_input a resposta, com a espera medida +``` + +O par `agent_pause` / `agent_resume` é o único que alimenta o tempo pausado. Sem ele, uma espera humana de dez minutos é contabilizada como dez minutos de tempo ativo do agente. + + + O CrewAI não define um id de correlação em nenhum dos eventos de human-feedback, portanto o adaptador os emparelha pelo nome do flow e do método, recorrendo à pausa mais recentemente aberta como fallback. Isso é válido porque um prompt de console bloqueia. Se você implementar um provedor de feedback concorrente, defina `request_id` em ambos os eventos. + + + + Como o caminho `Task(human_input=True)` é um wrapper em torno do provedor de entrada do CrewAI — e não uma assinatura de evento —, ele é restaurado no `uninstrument()` e repropaga qualquer exceção que `input()` lance, incluindo `KeyboardInterrupt`, sem alterações. + + +## Problemas comuns + + + + Um `role` contém um UUID, timestamp ou sufixo por execução. Use um papel humano estável e coloque o id específico da execução na descrição da tarefa. + + + + O barramento de eventos é assíncrono, e `kickoff()` retorna antes que os últimos handlers sejam executados. Esvazie-o primeiro: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + Isso é uma característica do CrewAI, não do SDK. + + + + `agent_end` força o fechamento de pausas abertas, mas não de ferramentas ou modelos; portanto, uma execução que falha dentro de uma chamada de ferramenta deixa aquele span aberto. O encerramento normal fecha tudo que ainda estiver aberto e o marca como incompleto. Apenas um `SIGKILL` o deixa pendente, porque nada mais consegue executar. + + + + Verifique nesta ordem: `instrument()` foi chamado antes de `kickoff()`; há um `with failproofai_sdk.session():` ao redor; `crewai` é 1.13 ou mais recente; `FAILPROOFAI_SDK_STRICT=1` está definido, para que um hook degradado lance uma exceção em vez de ser silenciado. + + + +## Próximos passos + + + + Pares, ids, ciclo de vida da sessão e entrega. + + + Siga a causalidade pela sessão que você acabou de capturar. + + + LangGraph, LlamaIndex, Pydantic AI e agentes customizados. + + \ 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 new file mode 100644 index 000000000..fd1ab4f06 --- /dev/null +++ b/docs/pt-br/start/integrations/custom-agents.mdx @@ -0,0 +1,739 @@ +--- +title: "Agentes personalizados" +sidebarTitle: "Agentes personalizados" +description: "Instrumente um agente que você mesmo escreveu, ou um framework sem adaptador." +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. + +Esta é a mesma API que os quatro adaptadores de framework utilizam internamente. Eles são tabelas de tradução sobre ela. + +## Instalação + +```bash +pip install failproofai-sdk +``` + +Sem extras e sem dependências. + +## Instrumentação + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # uma execução + with failproofai_sdk.agent("planner"): # uma unidade de trabalho + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) # uma chamada de ferramenta +``` + +Leia de cima para baixo e o código diz o que significa: + +| Envolva em | Para dizer | +| --- | --- | +| `session()` | Esses eventos pertencem à mesma execução | +| `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: + +| Escopo | Emite | Propósito | +| --- | --- | --- | +| `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 mede sua duração | + +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`. + +Aninhar agentes constrói a árvore. `parent_id` e profundidade são calculados a partir da pilha: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## Como um escopo é fechado + +`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` | + +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 span entre eles. + +| Família | Abre | Fecha | Independente | +| --- | --- | --- | --- | +| **Agentes** | `agent_start` | `agent_end` | — | +| | `agent_pause` | `agent_resume` | — | +| **Modelos** | `model_request` | `model_response` | — | +| **Ferramentas** | `tool_use` | `tool_result` | — | +| **Hooks** | `hook_triggered` | `hook_completed` | — | +| **Humanos** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **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. + + + +```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 Models +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 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 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 Failures +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **As duas famílias de humanos apontam em direções opostas.** + + | 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 | + + Nenhum framework sinaliza o segundo par, então sempre cabe 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. + + +## Exemplo + +Um loop de chamada de ferramentas contra a API da OpenAI, sem framework de agentes: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +MODEL = "gpt-4o-mini" + + +def turn(messages: list): + """Uma chamada de modelo, delimitada pelo par.""" + failproofai_sdk.event.model_request(model=MODEL, messages=messages) + reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS) + usage = reply.usage + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="price report"): + for _ in range(4): # limitado; um loop de agente sem limite é um bug por si só + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +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 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 +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# threads: envolva o 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) +``` + +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 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 registra | +| --- | --- | --- | +| A execução | `session()` + `agent()` | `agent_start`, `agent_end` | +| Cada ferramenta | `tool_call()` | `tool_use`, `tool_result` | +| Cada chamada de modelo | O par `model_*` | `model_request`, `model_response` | + + + + ```python + with failproofai_sdk.session(): + with failproofai_sdk.agent(agent_name, goal=task): + result = framework.run(task) + ``` + + + 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(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **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 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` 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 fornecido faria. + + +## Indo mais fundo + +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. + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + C --> E(["agent_end"]) +``` + +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. + + + + ```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 out-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 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. + + + + ```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 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 out-tok + 9 +5.727s agent_end analyst · success + 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. + + + + ```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 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 + ... segunda iteração + 26 +7.038s agent_end Agent · success + ``` + + O loop do agente em si fica visível, não apenas suas chamadas de modelo. + + + + ```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 + 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 + 8 +8.119s agent_end agent · success + ``` + + Sem pares de hook: Pydantic AI não possui limite de nó ou passo para delimitar. + + + + ```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 out-tok + 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. + + + + + + + +**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: + +| Status | Quando | +| --- | --- | +| `ongoing` | Pelo menos um span ainda está aberto | +| `paused` | Um `agent_pause` não tem `agent_resume` correspondente | +| `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. + + + É 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: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + 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`. + +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 gera qual id + +| Id | Gerado por | Observações | +| --- | --- | --- | +| `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 adaptadores resolvem `session_id` + +O primeiro match vence: + +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 + +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 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 protegem essa coluna para você: + +| O framework entrega | Gravado como | Por quê | +| --- | --- | --- | +| `3f9a1c2b-…` (um UUID) | `main` | Nada legível para manter | +| 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` | Igual | + +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. + + + + + + +| Grupo | Eventos | +| --- | --- | +| Agentes | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| Modelos | `model_request`, `model_response` | +| Ferramentas | `tool_use`, `tool_result` | +| Hooks | `hook_triggered`, `hook_completed` | +| Humanos | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| Falhas | `error` | + +O que cada framework registra, medido a partir das execuções acima: + +| Evento | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Custom | +| --- | :--: | :--: | :--: | :--: | :--: | +| 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ê | +| 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 evento nunca chega sozinho. Um abre um span, outro o fecha, e o evento de fechamento carrega uma duração que o SDK mede a partir do evento de abertura. + +| Abre | Fecha | O evento de fechamento carrega | +| --- | --- | --- | +| `agent_start` | `agent_end` | `outcome`, `summary` | +| `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 | +| `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. + + +#### 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. +- 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. + + + + + +Instalar `failproofai-sdk` instala tudo, incluindo os quatro adaptadores. Os extras instalam o **framework**, não o adaptador. + +```python +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`. + + + 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") # desfaz +``` + +| Nome | Também aceita | +| --- | --- | +| `langchain` | `langgraph`, `langchain_core` | +| `crewai` | — | +| `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: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +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. + + ```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. + + + + **`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 não tem langchain ainda -> () + +import langchain # tarde demais, nada está conectado +``` + +```python Right +import langchain # importe o framework primeiro +import failproofai_sdk + +failproofai_sdk.instrument() # encontra -> ('langchain',) +``` + +```python Right, order-proof +import failproofai_sdk + +# Nomear importa o adaptador sob demanda, então isso 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. + + + + + +```mermaid +flowchart LR + A["Seu agente"] --> B["Adaptador"] + B --> C["Writer
fila em memória"] + C -->|"a cada 0,5s"| D["Spool
JSONL em disco"] + D --> E["Daemon Failproof"] + E -->|"HTTPS"| F["Cloud"] +``` + +| 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 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 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ó 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ê. + + +O daemon **envia** seus lotes. Ele não os abre nem os reescreve. + +| Eventos | Escritos por | Redacted por `collector.redact`? | +| --- | --- | --- | +| Transcrições de sessão CLI | O daemon | Sim | +| Atividade de hook | O daemon | Sim | +| **Tudo que o SDK emite** | **Seu processo** | **Não** | + +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 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 interruptor 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. + + `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. + + + + **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. + +Para confirmar que os eventos realmente chegaram, verifique o dashboard. Para observar o spool 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. + +| 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 | +| `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 | + +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. + + + + + +## Problemas comuns + + + + 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`. + + + + É 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()`. 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 nos 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. + + + +## Próximos passos + + + + Pares, ids, ciclo de vida da sessão e entrega. + + + Siga a causalidade pela sessão que você acabou de capturar. + + + LangGraph, CrewAI, LlamaIndex e Pydantic AI. + + \ No newline at end of file diff --git a/docs/pt-br/start/integrations/langchain.mdx b/docs/pt-br/start/integrations/langchain.mdx new file mode 100644 index 000000000..e9f01919f --- /dev/null +++ b/docs/pt-br/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain e LangGraph" +sidebarTitle: "LangChain e LangGraph" +description: "Instrumente grafos, nós, ferramentas, retrievers e chamadas de modelo com uma única chamada." +icon: "/images/frameworks/langchain.svg" +--- + +Um único adaptador serve para ambos. O LangGraph roda sobre o gerenciador de callbacks do `langchain-core`, então instrumentar um instrumento o outro. + +## Instalação + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Para LangChain sem LangGraph, use `failproofai-sdk[langchain]`. + +Suportado: `langchain-core` 1.4.7 a 2.0, `langgraph` 1.2 a 2.0. Fora desse intervalo, o adaptador ainda instala e emite um aviso uma vez. + +## Instrumentar + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` registra um tracer através do `langchain_core.tracers.context.register_configure_hook`. O LangChain o injeta em cada gerenciador de callbacks que constrói, então grafos, ferramentas e modelos são capturados sem alterar nenhum ponto de chamada — incluindo os que estão dentro de bibliotecas que você não escreveu. + +## O que é registrado + +| LangChain ou LangGraph | Evento Failproof | +| --- | --- | +| Run raiz | `agent_start`, `agent_end` | +| Nó LangGraph | `hook_triggered`, `hook_completed` | +| Subgrafo compilado | `agent_start`, `agent_end` aninhados | +| Run de ferramenta | `tool_use`, `tool_result` | +| Run de retriever | `tool_use`, `tool_result`, saída resumida | +| Run de chat model ou LLM | `model_request`, `model_response`, com uso de tokens | +| Tokens em streaming | Consolidados na resposta como contagem de chunks e tempo até o primeiro token. Contagens de tokens precisam de `ChatOpenAI(stream_usage=True)` — veja abaixo | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, correlacionados no `Interrupt.id` — inclusive quando o resume acontece em um processo diferente com o mesmo checkpointer | +| Exceção não tratada | `error`, seguido de `agent_end` com resultado `failed` | + +**Um nó se torna um hook, não um agente aninhado.** `agent_id` é a faceta principal em todas as superfícies do dashboard — promover `retrieve`, `grade_documents` e `should_continue` a agentes afogaria isso e rotularia a sessão com o nome do nó que aconteceu de rodar primeiro. + +Spans de hook são renderizados da mesma forma e ainda oferecem uma visão de latência por nó. + + + **Nomeie seus nós como quiser.** O run de um nó é identificado pela sua *forma* — um run não-folha carregando a própria tag de step do LangGraph — nunca pelo seu nome. + + +| Você escreve | O que é registrado | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | A ferramenta | +| `add_node("ChatOpenAI", ...)` | A chamada ao modelo | + +Nomear um nó com o nome da coisa que ele executa costumava fazer os eventos dessa coisa desaparecerem. Isso não acontece mais. + +### Streaming + +`.stream()` e `.astream()` não emitem eventos por token. Eles são consolidados no `model_response` de fechamento: + +| Campo | Contém | +| --- | --- | +| `fw_chunks` | Quantos chunks chegaram | +| `fw_ttft_ms` | Tempo até o primeiro token | + +### Contagens de tokens em uma resposta em streaming + +Assunto separado e fácil de perder: a OpenAI só envia o uso em uma resposta em streaming **quando solicitado**. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # sem isso, sem tokens +``` + +O adaptador registra o que o framework entrega. Sem esse flag não há nada a registrar, e `model_response` chega sem contagens de tokens. + +## Exemplo + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## Nomeie seus spans + +Por padrão, o span raiz usa o próprio nome do grafo. Envolva-o para obter um rótulo de sua escolha: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +Para configurações multi-agente, aninhe os escopos. Cada worker se torna um span filho carregando `parent_id`: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +Mantenha `agent_id` com baixa cardinalidade. Use um papel ou nome de nó, nunca um UUID ou uma string gerada por run. + +## Controle a sessão + +O id de sessão é resolvido nesta ordem, vencendo o primeiro match: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. O escopo `failproofai_sdk.session()` envolvente +4. `metadata["session_id"]`, `metadata["conversation_id"]`, ou `metadata["thread_id"]` +5. O id do run raiz + +Ele nunca é gerado do zero, porque um id sintetizado divide um único run em várias sessões. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## Opções + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # fixa todo run a um id de sessão + include_chains=set(), # allowlist de chains intermediárias como pares de hook + capture_content=True, # False remove prompts e completions dos payloads + graph_callbacks=True, # interrupt e resume de primeira classe, requer langgraph 1.2+ +) +``` + +Defina `capture_content=False` para dados regulamentados. Estrutura, tempos, contagens de tokens, nomes de ferramentas e resultados ainda são registrados; os corpos das mensagens não são. + +`include_chains` se aplica **apenas** a runs aninhados. Um runnable invocado no nível superior é a raiz da sessão, então se torna o span do agente em vez de um par de hook, e nomeá-lo aqui não tem efeito. + +## Humano no loop + +`interrupt()` produz quatro eventos, e nenhum par é redundante: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +De `human_wait` a `human_input` carrega o prompt e a resposta (ambos são removidos com `capture_content=False`, assim como fontes de documentos de retrieval — a contagem de documentos sobrevive). De `agent_pause` a `agent_resume` é o único par que alimenta o tempo em pausa, então sem ele uma espera humana de dez minutos é contabilizada como tempo ativo do agente. O span raiz permanece aberto durante o intervalo, mantendo ambas as chamadas em uma única sessão. + +## Problemas comuns + + + + `create_react_agent` propaga a exceção. Para que o modelo veja a falha e continue, construa o nó de ferramenta explicitamente: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + A falha é registrada como um `tool_result` carregando um erro em ambos os casos. Isso apenas decide se o run sobrevive a ela. + + + + Um `llm.invoke()` direto fora de qualquer grafo não tem run pai, então abre um span raiz e emite seu par de modelo dentro dele. O dashboard parenteia folhas a um agente aberto, então o span é intencional. Nomeie-o: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + Você passou um handler Failproof em `config={"callbacks": [...]}` além de chamar `instrument()`. Remova-o. O configure hook já cobre todos os gerenciadores de callback no processo. + + + + Não aparecem. O LangGraph lança `GraphInterrupt` pelo mesmo caminho que uma exceção real, então toda pausa chega ao tracer como um callback de erro. Qualquer subclasse de `GraphBubbleUp` é tratada como fluxo de controle em vez disso, então uma aprovação não pinta um erro vermelho. + + + + Verifique nesta ordem: `instrument()` foi executado antes do grafo; há um `with failproofai_sdk.session():` em torno da chamada; `FAILPROOFAI_SDK_STRICT=1` está definido, para que um hook degradado lance em vez de ser engolido silenciosamente. + + + +## Próximos passos + + + + Pares, ids, ciclo de vida da sessão e entrega. + + + Siga a causalidade pela sessão que você acabou de capturar. + + + CrewAI, LlamaIndex, Pydantic AI e agentes customizados. + + \ No newline at end of file diff --git a/docs/pt-br/start/integrations/llamaindex.mdx b/docs/pt-br/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..c37940510 --- /dev/null +++ b/docs/pt-br/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "Instrumente workflows, steps, function agents e retrievers." +icon: "/images/frameworks/llamaindex.svg" +--- + +## Instalação + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +Compatível com: `llama-index-core` 0.14.23 a 0.15. A versão 0.14.23 é onde o stream do workflow passou a incluir os eventos de agente tipados que este adaptador lê. Em versões anteriores, os nomes dos modelos e a estrutura dos agentes ficam ausentes. + +## Instrumentação + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +A API de agentes do LlamaIndex é assíncrona. Todos os escopos funcionam tanto com `async with` quanto com `with` e produzem eventos idênticos. + +`instrument()` adiciona um handler de eventos e um handler de spans ao dispatcher global do LlamaIndex. Juntos, eles tornam o loop do agente visível, não apenas as chamadas ao modelo. + + + Sem um argumento extra no seu LLM, toda contagem de tokens no seu trace será nula. Veja [Contagem de tokens](#token-counts) abaixo. + + +## Contagem de tokens + +`FunctionAgent` chama `astream_chat`, e o `llama-index-llms-openai` não envia `stream_options={"include_usage": True}` ao fazer streaming. O provedor, portanto, nunca envia o chunk de uso, e não há nada para qualquer instrumentação ler. + +Esse é um comportamento do próprio LlamaIndex. Ative no seu LLM: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +Medido na mesma execução e modelo: + +| | Tokens de entrada | Tokens de saída | +| --- | --- | --- | +| Sem | `null` | `null` | +| Com | 148 | 17 | + +Chamadas sem streaming (`llm.chat`, `llm.achat`) reportam o uso sem configuração adicional. Apenas o caminho de streaming, que é o caminho padrão do agente, precisa disso. + +## O que é registrado + +| LlamaIndex | Evento Failproof | +| --- | --- | +| Span raiz de `Workflow.run` | Session, `agent_start`, `agent_end` | +| Span aninhado de `Workflow.run` | `agent_start`, `agent_end` aninhados | +| Span de step do workflow | `hook_triggered`, `hook_completed` | +| Início e fim do chat LLM | `model_request`, `model_response` | +| Span de `FunctionTool.call` | `tool_use`, `tool_result` | +| Início e fim da recuperação | `tool_use`, `tool_result`, saída resumida | +| Embeddings | Nada, a menos que `embeddings=True` | +| Uma ferramenta aguardando uma pessoa | `human_wait`, `agent_pause`, depois `agent_resume`, `human_input` | +| Transferência de `AgentWorkflow` | Um `agent_start`, `agent_end` aninhado por agente, vinculado ao workflow | +| Exceção | `error`, depois `agent_end` com resultado `failed`, e `agent_end.summary` identificando-a | +| `handler.cancel_run()` | `agent_end` com resultado `cancelled` e sem `error` — um botão de parada não é uma falha | + +`agent_id` é o `FunctionAgent.name` quando você define um, e o nome da classe do workflow caso contrário. Em um `AgentWorkflow`, cada agente que assume o controle recebe seu próprio span aninhado sob o workflow, então uma transferência aparece como dois agentes em vez de um. + +A saída da recuperação é resumida em vez de despejada integralmente. Um retriever retorna documentos, e armazená-los no payload colocaria seu corpus no store de eventos a cada consulta. Em vez disso, são mantidos a contagem, o intervalo de scores e trechos truncados. + +## Exemplo + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +O loop do agente aparece no trace como pares de hooks: `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool` e `aggregate_tool_results`. Eles fazem parte do próprio loop do framework, por isso são hooks em vez de agentes, o que mantém o `agent_id` com significado claro. + +## Nomeie seus spans + +`agent_id` é o `FunctionAgent.name` quando você define um, e o nome da classe do workflow caso contrário. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +Em um `AgentWorkflow`, esse nome também é usado para registrar cada transferência: + +```text +AgentWorkflow span pai +├─ city_analyst turno 1 +├─ cost_analyst turno 2 +└─ city_analyst turno 3 — um novo turno, não uma reabertura +``` + +Portanto, `agent_id` indica **qual agente** realizou o trabalho e `parent_id` indica **a qual workflow** ele pertencia. Um agente que devolve o controle posteriormente abre um segundo turno em vez de reabrir o primeiro. + +Envolva a execução para sobrescrever isso, ou para agrupar vários agentes sob um mesmo pai: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +Mantenha o `agent_id` com baixa cardinalidade. Ele é a faceta primária em todas as superfícies do dashboard, portanto use um papel ou nome de workflow, nunca um UUID ou string por execução. + +## Controle a sessão + +Este adaptador **não aceita a opção `session_id`**. A sessão vem do escopo envolvente e, caso contrário, é gerado um `uuid4().hex` por execução do workflow: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## Opções + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True registra chamadas de embedding como pares de ferramentas + steps=True, # False remove os pares de hooks de steps do workflow + capture_messages=True, # False remove TODOS os payloads: prompts, completions, + # argumentos e saída de ferramentas, I/O de steps, consultas + # de recuperação, o objetivo e a resposta final + capture_limit=8192, # caracteres mantidos por valor capturado + stale_after=600.0, # segundos antes de uma FOLHA abandonada ser forçada a fechar + reaper_interval=30.0, # frequência da varredura do reaper; 0 desativa +) +``` + +| Opção | Quando alterar | +| --- | --- | +| `embeddings` | Ative apenas ao depurar latência ou custo de embeddings. Uma indexação em massa gera milhares de chamadas e vai soterrar o timeline. | +| `steps` | Desative se você só quer eventos de modelo e ferramenta e achar o loop do agente ruidoso. | +| `capture_messages` | Desative para dados regulados. Todos os payloads deixam de ser registrados — prompts, a completion do modelo, argumentos e valores de retorno de ferramentas, entrada e saída de steps do workflow, consultas de recuperação, o objetivo do agente e sua resposta final. Estrutura, tempos, tokens e resultados continuam sendo registrados. | +| `capture_limit` | Caracteres mantidos por valor capturado antes do truncamento. Aumente quando um prompt RAG ou contexto recuperado estiver chegando cortado. | +| `stale_after` | Segundos antes de uma **folha** abandonada — uma resposta em streaming que ninguém consumiu, um span de modelo ou ferramenta cujo fechamento nunca chegou — ser forçada a fechar, para que a sessão se resolva em vez de ficar como `ongoing` para sempre. **Não** fecha uma execução abandonada em si: um workflow cujo task é cancelado sem que o dispatcher veja uma saída mantém seu `agent_start` aberto até `uninstrument()`. | +| `reaper_interval` | Frequência da varredura. Defina como `0` para desativar o reaper completamente. | + +## Human in the loop + +Capturado quando a espera acontece dentro de uma ferramenta: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +`ctx.wait_for_event` em um step comum de workflow não é capturado. O runtime intercepta o drop antes que ele chegue ao dispatcher, então o step sai e é executado novamente mais tarde sem sinal para identificar uma pausa. O padrão FunctionAgent, que o LlamaIndex documenta, aguarda dentro de uma ferramenta e é capturado por completo. + +## Problemas comuns + + + + Adicione `additional_kwargs={"stream_options": {"include_usage": True}}` ao seu LLM. Veja [Contagem de tokens](#token-counts). + + + + O LlamaIndex não possui um campo de uso padronizado. O adaptador tenta várias estruturas conhecidas, e uma integração que nomeia seus contadores de forma diferente não vai corresponder a nenhuma delas. + + O dict bruto sempre é enviado, então verifique `usage` no payload para ver como seu provedor os nomeou. + + Um `usage` preenchido junto com colunas de tokens vazias é intencional — é melhor do que um número errado exibido com confiança. + + + + Esse é o loop do FunctionAgent, um conjunto por iteração. Filtre pelo nome do hook no dashboard. Esses tempos de step costumam ser o principal motivo para usar este adaptador em vez de um focado apenas no modelo. + + + + Verifique nesta ordem: `instrument()` foi chamado antes da execução; há um `async with failproofai_sdk.session():` em torno do `await`; o `llama-index-core` é 0.14.23 ou mais recente; `FAILPROOFAI_SDK_STRICT=1` está definido, para que um hook degradado lance exceção em vez de ser suprimido. + + + +## Próximos passos + + + + Pares, ids, ciclo de vida da sessão e entrega. + + + Siga a causalidade pela sessão que você acabou de capturar. + + + LangGraph, CrewAI, Pydantic AI e agentes personalizados. + + \ No newline at end of file diff --git a/docs/pt-br/start/integrations/pydantic-ai.mdx b/docs/pt-br/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..b48376724 --- /dev/null +++ b/docs/pt-br/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "Instrumente agentes tipados, ferramentas, chamadas de modelo e retentativas." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## Instalação + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +Compatível com: `pydantic-ai-slim` 2.0 a 3.0. A versão 2.0 removeu `Agent(instrument=...)` e introduziu o protocolo de capacidade no qual este adaptador é construído, portanto a versão 1.x não pode ser instrumentada dessa forma. + +## Instrumentar + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # antes de construir qualquer Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` deve ser executado antes de você construir um `Agent`. A capacidade é adicionada no momento da construção, portanto um agente criado anteriormente não terá nenhuma e não registrará nada, sem emitir erros porque nada deu errado. Esta é a causa mais comum de um trace vazio com este adaptador. + + +Agentes com escopo de módulo são onde isso ocorre com mais frequência: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # constructed at import time + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # run this FIRST +import agents # now the agent gets the capability +``` + +Confirme se funcionou: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +O Pydantic AI mescla a lista passada em um único `root_capability`, portanto não existe um atributo `agent.capabilities` para ser lido. + +Agentes construídos enquanto a instrumentação estava ativa mantêm a capacidade, então você pode chamar `uninstrument()` e reinstrumentar sem precisar recriá-los. + +## O que é registrado + +| Pydantic AI | Evento Failproof | +| --- | --- | +| Execução do agente | `agent_start`, `agent_end` | +| Requisição ao modelo | `model_request`, `model_response`, com uso de tokens | +| Chamada de ferramenta | `tool_use`, `tool_result`, com os argumentos enviados pelo modelo | +| `ModelRetry` originado de uma ferramenta | `tool_result` contendo um erro | +| Exceção não tratada | `error`, seguido de `agent_end` com resultado `failed` | + +Não há par de hooks nem par de interação humana aqui. O Pydantic AI não possui limite de nó ou etapa para delimitar e nem pausa humana integrada, portanto não há nada a mapear. Se você implementar qualquer um desses recursos, emita os eventos manualmente — veja [Custom agents](/pt-br/reference/custom-agents). + +`output_type` não faz diferença no trace. Uma execução tipada e uma execução com string produzem os mesmos eventos. + +## Exemplo + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +No trace, `restock_eta` aparece como um `tool_result` contendo um erro, seguido de outra chamada ao modelo onde o agente contorna o problema, e a execução ainda termina com `success`. Ambas as informações são preservadas. + +## Erros, retentativas e fluxo de controle + +O Pydantic AI lança exceções para três situações distintas, e o adaptador as separa: + +| Exceção | Tratada como | Resultado | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | Falha real da ferramenta | `tool_result` com um erro; a execução ainda pode terminar com `success` | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | Fluxo de controle | Não é um erro; a execução está sendo direcionada | +| Qualquer outra coisa | Uma falha | `error`, seguido de `agent_end` com resultado `failed` | + +`ModelRetry` está no primeiro grupo intencionalmente. Significa que uma tentativa genuinamente falhou e o modelo foi solicitado a tentar novamente, que é exatamente para isso que serve o campo de erro de um span de ferramenta. Classificá-lo como fluxo de controle ocultaria falhas reais de ferramentas por trás de uma execução bem-sucedida. + +## Nomeie seus spans + +O próprio span de execução do Pydantic AI é chamado de `agent`. Envolva a chamada para atribuir um rótulo de sua escolha: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +O span do framework então fica aninhado sob `inventory`, e é lá que os eventos de modelo e ferramenta ficam pendurados. + +Mantenha `agent_id` com baixa cardinalidade. Ele é a faceta principal em todas as superfícies do dashboard, portanto use um nome de função, nunca um UUID ou uma string específica por execução. + +## Controle a sessão + +Resolvido nesta ordem, com o primeiro match vencendo: + +1. `instrument("pydantic_ai", session_id=...)` +2. O escopo `failproofai_sdk.session()` envolvente +3. O `conversation_id` da execução, depois seu `run_id` +4. Um `uuid4().hex` gerado automaticamente + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## Opções + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # pin every run to one session id + capture_content=True, # False drops prompts and completions from payloads +) +``` + +## Problemas comuns + + + + O `Agent` foi construído antes de `instrument()` ser executado. Veja o aviso acima e verifique `agent.root_capability.capabilities`. + + + + Um `raise` sem tratamento se propaga; esse é o design do Pydantic AI. Para permitir que o modelo contorne o problema, levante `ModelRetry` com uma mensagem que ele possa usar. A falha é registrada de qualquer forma. + + + + Esse filho é o próprio span de execução do Pydantic AI, e é onde os eventos de modelo e ferramenta ficam. Remova seu próprio escopo se quiser um único span, ao custo do nome personalizado. + + + + O stack do grafo assíncrono do Pydantic AI é mais longo do que o limite do campo de payload, e a última linha de um traceback é a própria exceção. Este campo é cortado a partir do início, e não do final, para que a linha que você precisa seja preservada. + + + +## Próximos passos + + + + Pares, ids, ciclo de vida da sessão e entrega. + + + Siga a causalidade através da sessão que você acabou de capturar. + + + LangGraph, CrewAI, LlamaIndex e agentes personalizados. + + \ No newline at end of file diff --git a/docs/pt-br/start/quickstart.mdx b/docs/pt-br/start/quickstart.mdx index 3b6814987..b43f7e460 100644 --- a/docs/pt-br/start/quickstart.mdx +++ b/docs/pt-br/start/quickstart.mdx @@ -1,17 +1,17 @@ --- title: "Início Rápido" -description: "Capture uma sessão de agente, encontre uma falha e comece a preveni-la." +description: "Capture uma sessão de agente, encontre uma falha e comece a evitá-la." 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 ou siga os passos manuais. +Este início rápido faz com que uma máquina reporte sessões, executa uma auditoria e implanta uma política. Use a skill para configurar o Failproof AI, ou siga os passos manuais. -**Qual é o seu caminho?** 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, depois 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ê precisa do Node.js 20.9 ou superior. Se o seu agente não tem harness, instrumente-o com o [SDK Python](/pt-br/reference/custom-agents) para rastreamento e auditorias, e então junte-se novamente em [Execute sua primeira verificação de falha](/pt-br/start/first-audit); a aplicação nesse caminho precisa de um hook no seu runtime. - + ```bash npx skills add FailproofAI/skills ``` @@ -21,33 +21,33 @@ Este início rápido configura uma máquina para reportar sessões, executa uma Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Seu agente inspeciona o projeto, escolhe a integração adequada, realiza a configuração e verifica o funcionamento. Consulte o [repositório de skills do FailproofAI](https://github.com/FailproofAI/skills) para skills individuais e opções avançadas de instalação. + Seu agente inspeciona o projeto, escolhe a integração relevante, realiza a configuração e verifica o resultado. Veja o [repositório de skills do FailproofAI](https://github.com/FailproofAI/skills) para skills individuais e opções avançadas de instalação. ## Antes de começar -1. Abra o [dashboard do Failproof AI](https://app.befailproof.ai) e crie uma conta ou faça login com seu e-mail corporativo. +1. Abra o [painel do Failproof AI](https://app.befailproof.ai) e crie uma conta ou entre com seu e-mail de trabalho. 2. Acesse **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 secret de uso único e armazene-o na máquina de destino: ```bash export FAILPROOFAI_KEY="" ``` - ## Instalação + ## Instalar - + ```bash npm install -g failproofai failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - As transcrições de sessão 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. + Os transcritos de sessão são enviados por padrão. Adicione `--no-transcripts` para reportar atividade de hook e decisões de política sem o conteúdo do transcrito. - Se esta máquina já possui histórico de agente, visualize e importe os últimos sete dias e aguarde a entrega ser concluída. Pule este passo em uma máquina nova. + Se esta máquina já possui histórico de agente, visualize e importe os últimos sete dias e aguarde a conclusão da entrega. Pule esta etapa em uma máquina nova. ```bash failproofai backfill --since 7d --dry-run @@ -57,28 +57,28 @@ 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 40 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 escreva políticas para seus agentes. + + Isso conecta o Failproof AI ao seu harness e instala as 40 políticas integradas. Use-as para ver as decisões de política locais e experimentar a aplicação antes que o Failproof AI audite suas sessões e escreva políticas para seus agentes. - Deixe o instalador detectar seu harness automaticamente ou especifique um explicitamente. Todos os 12 são valores válidos para `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + 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`. ```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. 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 sua execução é verificado em todos os 12. Os gates de fim de turno são verificados em 8 — veja a [capacidade de aplicação](/pt-br/reference/harnesses#enforcement-capability) para a matriz por harness. - - 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 repetiu uma ferramenta com falha sem mudar sua abordagem". + + Siga [Execute sua primeira verificação de falha](/pt-br/start/first-audit). Use um objetivo concreto, como "encontrar sessões onde o agente repetiu 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 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 a nuvem, o estado do daemon e se a aplicação está pausada. \ No newline at end of file diff --git a/docs/pt-br/start/quickstarts/crewai.mdx b/docs/pt-br/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..59e6306ee --- /dev/null +++ b/docs/pt-br/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "Instale, instrumente e veja seu primeiro trace." +icon: "/images/frameworks/crewai.svg" +--- + +Três passos para o seu primeiro trace com CrewAI. Para detalhes sobre o que cada evento carrega, fluxos e solução de problemas, consulte [o guia completo](/pt-br/start/integrations/crewai). + +## Instalar + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## Instrumentar + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +Nada na sua crew, agentes, tarefas ou ferramentas muda. `instrument()` se inscreve no barramento de eventos em nível de módulo do CrewAI. + +## Verificar se chegou + +Execute uma vez, depois abra **Observe → Sessions** e selecione seu ambiente. Sua execução aparece como um trace reconstruído. + +Se nada aparecer, confirme que a máquina está conectada com `failproofai config --status`. + + + O que é registrado, fluxos, uso de tokens, nomenclatura de spans, opções e problemas comuns. + \ No newline at end of file diff --git a/docs/pt-br/start/quickstarts/custom-agents.mdx b/docs/pt-br/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..83d0352f1 --- /dev/null +++ b/docs/pt-br/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "Agentes personalizados" +description: "Envolva seu agente em três blocos `with` e ele começa a registrar." +icon: "code" +--- + +Para um agente que você mesmo escreveu, ou um framework para o qual o Failproof AI não possui adaptador. + +Você envolve o trabalho que já realiza em blocos `with`. Cada um registra quando começou, quando terminou e quanto tempo levou — você não precisa chamar mais nada. + +## Instalação + +```bash +pip install failproofai-sdk +``` + +Sem extras e sem dependências. + +## Instrumentação + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # uma execução + with failproofai_sdk.agent("planner"): # uma unidade de trabalho + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) # uma chamada de ferramenta +``` + +Leia de cima para baixo e o significado fica claro: + +| Envolva com | Para indicar | +| --- | --- | +| `session()` | Estes eventos pertencem à mesma execução | +| `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 | + +Aninhe-os da forma que seu código aninhar. Você nunca precisa passar ids manualmente: cada bloco se lembra do contexto em que está inserido, então tudo que você registrar automaticamente associa a execução e o agente corretos. `async with` funciona exatamente da mesma forma. + +## Verifique se chegou + +Execute uma vez, depois abra **Observe → Sessions** e selecione seu ambiente. Sua execução aparece como um trace reconstruído. + +Se nada chegar, confirme que a máquina está conectada com `failproofai config --status`. + + + Todos os métodos de eventos, o que acontece quando seu código lança uma exceção, um exemplo completo, threads e async, e como instrumentar um framework sem adaptador. + \ No newline at end of file diff --git a/docs/pt-br/start/quickstarts/langchain.mdx b/docs/pt-br/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..78c947931 --- /dev/null +++ b/docs/pt-br/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain e LangGraph" +description: "Instale, instrumente e veja seu primeiro trace." +icon: "/images/frameworks/langchain.svg" +--- + +Três passos para o seu primeiro trace com LangChain ou LangGraph. Para streaming, human-in-the-loop, nomenclatura de spans e opções, consulte [o guia completo](/pt-br/start/integrations/langchain). + +## Instalar + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Para LangChain sem LangGraph, use `failproofai-sdk[langchain]`. + +## Instrumentar + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +Sem alterações nos pontos de chamada. `instrument()` registra um tracer que o LangChain injeta em cada callback manager que ele cria, de modo que grafos, ferramentas e modelos são capturados — incluindo os que estão dentro de bibliotecas que você não escreveu. + +## Verificar se chegou + +Execute uma vez, depois abra **Observe → Sessions** e selecione seu ambiente. Sua execução aparece como um trace reconstruído. + +Se nada chegar, confirme que a máquina está conectada com `failproofai config --status`. + + + O que é registrado, streaming, contagem de tokens, nomenclatura de spans, controle de sessão, opções e human in the loop. + \ No newline at end of file diff --git a/docs/pt-br/start/quickstarts/llamaindex.mdx b/docs/pt-br/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..36f09673b --- /dev/null +++ b/docs/pt-br/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "Instale, instrumente e veja seu primeiro trace." +icon: "/images/frameworks/llamaindex.svg" +--- + +Três passos para o seu primeiro trace com LlamaIndex. Para etapas de workflow, recuperação, o reaper e opções, consulte [o guia completo](/pt-br/start/integrations/llamaindex). + +## Instalar + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## Instrumentar + +A API de agente do LlamaIndex é assíncrona. Todo escopo funciona tanto com `async with` quanto com `with`. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + Sem um argumento extra no seu LLM, toda contagem de tokens no seu trace será nula — o `llama-index-llms-openai` não solicita o uso ao realizar streaming. Consulte [Contagem de tokens](/pt-br/start/integrations/llamaindex#token-counts). + + +## Verificar se chegou + +Execute uma vez, depois abra **Observe → Sessions** e selecione seu ambiente. Sua execução aparece como um trace reconstruído. + +Se nada chegar, confirme que a máquina está conectada com `failproofai config --status`. + + + Contagem de tokens, o que é registrado, etapas de workflow, recuperação, opções e problemas comuns. + \ No newline at end of file diff --git a/docs/pt-br/start/quickstarts/pydantic-ai.mdx b/docs/pt-br/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..7e5f11f79 --- /dev/null +++ b/docs/pt-br/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "Instale, instrumente e veja seu primeiro trace." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +Três passos para o seu primeiro trace com Pydantic AI. Para ferramentas, retries, streaming e opções, consulte [o guia completo](/pt-br/start/integrations/pydantic-ai). + +## Instalar + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## Instrumentar + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` deve ser executado **antes** de você construir um `Agent`. A capacidade de rastreamento é adicionada no momento da construção, portanto um agente criado anteriormente não registra nada — sem nenhum erro, pois tecnicamente nada deu errado. Essa é a causa mais comum de um trace vazio com este adaptador, e agentes criados no escopo do módulo são onde isso costuma acontecer: importe `failproofai_sdk` e chame `instrument()` antes de importar o módulo que os constrói. + + +## Verificar se chegou + +Execute uma vez, depois abra **Observe → Sessions** e selecione o seu ambiente. Sua execução aparecerá como um trace reconstruído. + +Se nada aparecer, confirme que a máquina está conectada com `failproofai config --status`. + + + O que é registrado, ferramentas e retries, streaming, nomenclatura de spans, opções e problemas comuns. + \ No newline at end of file diff --git a/docs/ru/index.mdx b/docs/ru/index.mdx index e36270bce..a2c139268 100644 --- a/docs/ru/index.mdx +++ b/docs/ru/index.mdx @@ -1,41 +1,42 @@ --- -title: "Сделайте вашего агента надежным" -description: "Наблюдаемость и управление для каждой среды, в которой работают ваши агенты — кодовые CLI, шлюзы чатов, самоуправляемые ассистенты и ваши собственные инструментированные агенты." +--- +title: "Сделайте вашего агента отказоустойчивым" +description: "Наблюдаемость и контроль для каждого окружения, в котором работают ваши агенты — кодирующие CLI, чат-шлюзы, самостоятельно развертываемые ассистенты и ваши собственные инструментированные агенты." icon: "shield-check" --- -Failproof AI помогает командам понять, что сделали агенты, найти причины отказов и развернуть защиту до того, как такое поведение повторится. +Failproof AI помогает командам понять, что делали агенты, найти, где они потерпели неудачу, и развернуть защиту до того, как то же поведение повторится. -**Среда** — это то, в чем работает ваш агент. Failproof AI интегрируется с 12 средами — кодовыми CLI вроде Claude Code и Codex, шлюзами чатов вроде Hermes, самоуправляемыми ассистентами вроде OpenClaw — и одни и те же события, политики и история сеанса применяются ко всем. Агенты без среды отправляют отчеты через [Python SDK](/ru/reference/custom-agents), который их отслеживает и проверяет; для применения политики там нужен хук в вашем собственном runtime. +**Окружение** — это то, в чем на самом деле работает ваш агент. Failproof AI подключается к 12 из них — кодирующие CLI, такие как Claude Code и Codex, чат-шлюзы, такие как Hermes, самостоятельно развертываемые ассистенты, такие как OpenClaw — и одни и те же события, политики и история сеансов применяются ко всем. Агенты без окружения отправляют отчеты через [Python SDK](/ru/reference/custom-agents), который отслеживает и проверяет их; для применения политики требуется хук в вашем собственном runtime. - Используйте инструмент для инструментирования проекта, подключите его и убедитесь, что логи агентов поступают. + Используйте инструмент для инструментирования вашего проекта, подключения и проверки получения логов агента. - - Анализируйте, выполняйте запросы, создавайте панели мониторинга и проводите аудиты на естественном языке по логам вашего агента. + + Анализируйте, запрашивайте, создавайте панели управления и проводите аудиты на естественном языке по логам вашего агента. - Отслеживайте вызовы моделей, инструменты, ошибки, ввод от пользователя, задержку и решения по политикам в одном сеансе. + Отслеживайте вызовы модели, инструменты, ошибки, ввод человека, задержку и решения по политикам в одном сеансе. - - Проверьте определенный набор сеансов, просмотрите выводы с доказательствами и отслеживайте исправления как задачи. + + Проверьте определенный набор сеансов, просмотрите выводы с подтверждением, отследите исправление как проблемы. - Превратите известный режим отказа в политику, наблюдайте ее влияние и разверните ее по всему вашему парку. + Преобразуйте известный режим отказа в политику, наблюдайте за его влиянием и разверните его во всем парке. -> **Сеанс → Аудит → Вывод → Задача → Политика**
-> Отследите, что произошло, найдите отказ, управляйте ответом, затем предотвратите такое же поведение в будущих запусках. +> **Сеанс → Аудит → Вывод → Проблема → Политика**
+> Отследите, что произошло, найдите сбой, управляйте откликом, затем предотвратите то же поведение в будущих запусках. -## С чего начать +## Начните отсюда -Если вы развертываете свой первый инструментированный агент, начните с [быстрого старта](/ru/start/quickstart). Если данные уже поступают, откройте [Сеансы](/ru/sessions/overview) и проверьте реальный запуск перед настройкой аудитов или политик. +Если вы развертываете свой первый инструментированный агент, начните с [краткого руководства](/ru/start/quickstart). Если данные уже поступают, откройте [Сеансы](/ru/sessions/overview) и проверьте реальный запуск перед настройкой аудитов или политик. - - Пройдите полный рабочий процесс от сбора до безопасного развертывания политики. + + Завершите сквозной рабочий процесс от захвата до безопасно развернутой политики. \ No newline at end of file diff --git a/docs/ru/policies/deploy.mdx b/docs/ru/policies/deploy.mdx index c814d9ab2..f321ce272 100644 --- a/docs/ru/policies/deploy.mdx +++ b/docs/ru/policies/deploy.mdx @@ -1,47 +1,51 @@ --- title: "Развертывание политик" -description: "Развернуть проверенную версию политики на целевые машины." +description: "Развертните проверенную версию политики на предусмотренных машинах." icon: "cloud-upload" --- Развертывание связывает одну или несколько версий политики с целевым набором зарегистрированных машин. -## Применить развертывание +## Применение развертывания - 1. Перейдите в **Admin → enforcement**, найдите машину и разверните ее строку. - 2. Выберите **edit**, добавьте проверенную версию политики и выберите **observe** или режим принудительного применения. - 3. Примените изменение, затем дождитесь следующей проверки машины и подтвердите состояние развертывания и охвата. - 4. Перейдите в **Observe → policy**, чтобы просмотреть активные решения. + 1. Перейдите в **Admin → enforcement**, найдите машину и разверните её строку. + 2. Выберите **edit**, добавьте проверенную версию политики и выберите режим **observe** или её действие принудительного применения. + 3. Примените изменение, подождите следующей регистрации машины и подтвердите состояние её развертывания и охвата. + 4. Перейдите в **Observe → policy** для проверки решений в реальном времени. - ![Редактор развертывания машины с версиями политик, режимами enforce и observe, а также действием применения развертывания.](/images/dashboard/enforcement-editor.png) + ![Редактор развертывания машины с версиями политик, режимами enforce и observe, и действием применения развертывания.](/images/dashboard/enforcement-editor.png) - Облачные конечные точки развертывания намеренно не предоставляются в виде обычных команд `fp`. Проверьте машину локально, а затем разверните через панель управления: + Развертывайте из CLI с помощью `fp fleet`. Просмотрите полученный набор перед применением — `deploy` выводит полный план и запрашивает подтверждение **только в интерактивном терминале без `--json`**. При использовании `--json`, с флагом `--yes` или при перенаправлении stdin (шаг CI, скрипт, агент, вызывающий shell) развертывание применяется немедленно без плана и запроса — поэтому сначала выполните `fp fleet show `, если хотите просмотреть изменения: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - Используйте `fp sessions --env production --since 24h` и `fp events --event-type hook_completed` после развертывания для проверки доставки активности в облако. + `fp fleet diff ` показывает намерение относительно доставки (машина отображается как `behind` до следующего опроса), `fp fleet history ` выводит список поколений, а `fp fleet rollback ` восстанавливает поколение — откажет, если это поколение ссылается на отключённую или удалённую политику. + + Проверьте саму машину с помощью `failproofai config --status` и используйте `fp sessions --env production --since 24h` и `fp events --event-type hook_completed` после развертывания для проверки того, что активность поступает в Cloud. - Разверните проверенную версию, а не изменяемый черновик, начиная с машины без production или небольшой группы, сессии которой вы можете проверить. + Развертывайте проверенную версию, не черновик, начиная с непроизводственной машины или небольшой группы, сессии которой вы можете проверить. - Проверьте совпадения, причины, затронутые инструменты и ложные срабатывания без блокировки работы. + Просмотрите совпадения, причины, затронутые инструменты и ложные срабатывания без блокирования работы. - - Переходите к принудительному применению после того, как наблюдаемые совпадения разделят небезопасные действия от допустимых, затем подтвердите, что каждая целевая машина получила развертывание и сообщает решения. + + Повысьте уровень после того, как наблюдаемые совпадения отделят небезопасные действия от допустимых, затем подтвердите, что каждая целевая машина получила развертывание и сообщает о решениях. -Машины должны иметь возможность `policies:pull`. Отчетность о событиях контролируется отдельно через `events:add`; проверьте обе возможности, если вы ожидаете анализа и принудительного применения в облаке. +Машины должны иметь возможность `policies:pull`. Отчётность о событиях отдельно контролируется параметром `events:add`; проверьте оба параметра, когда вы ожидаете анализ и применение политик в Cloud. - Управление принудительным применением — это административный рабочий процесс облака. Не рассматривайте маршруты принудительного применения только для root как обычные конечные точки API `/v1` для клиентов. + Управление принудительным применением является административным процессом Cloud. Не рассматривайте маршруты принудительного применения, доступные только root, как обычные конечные точки API `/v1` для клиентов. \ No newline at end of file diff --git a/docs/ru/policies/editor.mdx b/docs/ru/policies/editor.mdx index c2210cd7a..279cecc18 100644 --- a/docs/ru/policies/editor.mdx +++ b/docs/ru/policies/editor.mdx @@ -4,44 +4,46 @@ description: "Создавайте и пересматривайте верси icon: "file-pen-line" --- -Используйте редактор политик, чтобы превратить обнаруженную проблему в развертываемое правило. Разделяйте создание политик от их развертывания, чтобы черновик не мог незаметно изменить поведение работающей системы. +Используйте редактор политик для преобразования обнаруженной проблемы в развертываемое правило. Отделите создание от развертывания, чтобы черновик не мог скрытно изменить поведение в боевой среде. -Когда проблема имеет повторяемую последовательность действий, откройте её в разделе **Analyze → issues** и выберите **generate policy**. Failproof AI сначала объяснит, может ли политика выразить проблему, затем перенесет проверенное намерение и контекст обнаружения в редактор. Созданный исходный код остается черновиком, пока вы его не опубликуете. +Когда проблема имеет повторяющийся паттерн действий, откройте ее в **Analyze → issues** и выберите **generate policy**. Failproof AI сначала объясняет, может ли политика выразить проблему, затем переносит проверенное намерение и контекст обнаружения в редактор. Созданный источник остается черновиком до его публикации. ## Опубликуйте версию политики 1. Перейдите в **Admin → policy editor** и в разделе **compose** опишите режим отказа или вставьте исходный код политики JavaScript. - 2. Проверьте исходный код и исправьте все об­на­ру­жен­ные ошибки. - 3. Введите идентификатор политики и опубликуйте её, затем используйте **library** для сравнения или отключения версий. - 4. Выберите **enforcement**, когда версия готова к развертыванию на машины. + 2. Проверьте источник и исправьте все сообщенные ошибки. + 3. Введите идентификатор политики и опубликуйте ее, затем используйте **library** для сравнения или отключения версий. + 4. Выберите **enforcement**, когда версия готова к машинному развертыванию. - ![Представление compose редактора политик с идентификатором политики, ассистируемым созданием и элементами управления проверкой и публикацией.](/images/dashboard/policy-editor.png) + ![Представление compose редактора политик с идентификатором политики, автоматизированным созданием черновиков, проверкой источника и элементами управления публикацией.](/images/dashboard/policy-editor.png) - Cloud CLI не публикует версии политик. Проверьте исходный код локально перед копированием в редактор: + Опубликуйте из CLI с помощью `fp policies publish`. Эта команда создает **новую версию** и никогда не редактирует существующую на месте, а также проверяет синтаксис источника с помощью node перед отправкой — никакой другой компонент этого не делает, поэтому синтаксическая ошибка иначе появилась бы на машине во время развертывания: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - Опубликуйте проверенную версию из **Admin → policy editor**. + Публикация не развертывает ничего — новая версия остается неиспользованной до тех пор, пока `fp fleet deploy` не поместит ее на машину. `fp policies compose ""` создает источник с помощью облачного ассистента и выводит его для проверки вместо публикации. + + Чтобы установить политику в локальный агент CLI (не облако), используйте `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`. -## Контрольный список создания политики +## Контрольный список создания 1. Назовите режим отказа на операционном языке. -2. Выберите события hook и инструменты, которые содержат достаточно доказательств для решения. -3. Напишите самое узкое условие, которое соответствует небезопасному поведению. -4. Верните причину, которая подскажет агенту или оператору, что делать дальше. -5. Добавьте примеры, которые должны совпадать, и примеры, которые должны остаться разрешёнными. -6. Сохраните новую версию и запросите рецензию. +2. Выберите события hook и инструменты, которые содержат достаточно доказательств для принятия решения. +3. Напишите наиболее узкое условие, которое соответствует небезопасному поведению. +4. Вернитесь к причине, которая подскажет агенту или оператору, что делать дальше. +5. Добавьте примеры, которые должны совпадать, и примеры, которые должны остаться разрешенными. +6. Сохраните новую версию и запросите проверку. -Используйте `instruct`, когда агент может безопасно откорректировать курс. Используйте `deny`, когда разрешение действия создает неприемлемый или необратимый риск. +Используйте `instruct`, когда агент может безопасно изменить курс. Используйте `deny`, когда разрешение действия создаст неприемлемый или необратимый риск. - Версии политик являются неизменяемыми входными данными для развертывания. Редактирование черновика создает новую версию; она не должна переписывать версию, уже назначенную машинам. + Версии политик являются неизменяемыми входными данными для развертывания. Редактирование черновика создает новую версию; он не должен переписывать версию, уже назначенную машинам. \ No newline at end of file diff --git a/docs/ru/reference/cloud-cli.mdx b/docs/ru/reference/cloud-cli.mdx index 4c5742702..4275b84c2 100644 --- a/docs/ru/reference/cloud-cli.mdx +++ b/docs/ru/reference/cloud-cli.mdx @@ -1,11 +1,10 @@ --- ---- title: "Failproof Cloud CLI" -description: "Полный справочник для запросов и управления Failproof AI Cloud с помощью fp." +description: "Полный справочник по запросам и администрированию Failproof AI Cloud с помощью fp." icon: "cloud-cog" --- -Используйте `fp` для проверки телеметрии Cloud и управления аудитами, выводами, проблемами, оповещениями, ключами, пользователями, запросами и параметрами. Используйте [`failproofai`](/ru/reference/failproof-cli) для локальных хуков, политик, захвата и регистрации машин. +Используйте `fp` для проверки телеметрии Cloud, управления облачным принудительным применением (политики, развертывания флота, решения guardrail) и управления аудитами, находками, проблемами, оповещениями, ключами, пользователями, запросами и параметрами. Используйте [`failproofai`](/ru/reference/failproof-cli) для локальных хуков, политик, захвата и регистрации машин. Установите выпущенный Cloud CLI как изолированный инструмент: @@ -41,8 +40,8 @@ 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` | Показать справку по командам верхнего уровня. | — | @@ -58,30 +57,34 @@ 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`. | -| `--full` | Включить необработанные данные через более тяжёлую конечную точку событий. | -| `--fields ` | Возвращать только выбранные поля; запрос `payload` включает полный режим. | +| `--page-size ` | Строк на запрос с `--all`; максимум `200`. | +| `--full` | Включить необработанные полезные нагрузки через более тяжелую конечную точку события. | +| `--fields ` | Вернуть только выбранные поля; запрос `payload` включает полный режим. | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` + + `--all` пагинирует **до `--limit`**, который по умолчанию равен **50** — так что `--all` сам по себе останавливается на 50 строках. Когда останавливается рано, ответ несет `next_cursor` для возобновления; `"next_cursor": null` означает, что канал действительно исчерпан. + + ### Сеансы ```text @@ -93,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`. | -| `--fields ` | Возвращать только выбранные поля. | -| `--full-ids` | Не сокращать идентификаторы сеансов в выводе терминала. | -| `--agents` | Развернуть состав агентов для сеансов с несколькими агентами. | +| `--page-size ` | Строк на запрос с `--all`; максимум `200`. | +| `--fields ` | Вернуть только выбранные поля. | +| `--full-ids` | Не сокращать ID сеансов в выводе терминала. | +| `--agents` | Расширить список агентов для многоагентных сеансов. | ### Оценки @@ -113,13 +116,13 @@ fp evals [OPTIONS] | Параметр | Описание | | --- | --- | | `--aggregate` | Показать итоги и статистику по оценкам вместо отдельных оценок. | -| `--limit`, `-n ` | Максимальное количество строк списка. По умолчанию: `50`. | -| `--since`, `--from`, `--to` | Выберите диапазон времени. | -| `--env`, `--status`, `--agent-id`, `--session-id` | Сузить до одного точного значения за фильтр. | -| `--score KEY:MIN..MAX` | Диапазон оценок; повторяемый, все диапазоны должны совпадать. | +| `--limit`, `-n ` | Максимум строк списка. По умолчанию: `50`. | +| `--since`, `--from`, `--to` | Выбрать временной диапазон. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Сузить до одного точного значения на фильтр. | +| `--score KEY:MIN..MAX` | Диапазон оценки; повторяется, все диапазоны должны совпадать. | | `--all`, `--cursor`, `--page-size` | Управление пагинацией списка. | -| `--fields ` | Возвращать только выбранные поля. | -| `--full-ids` | Показать полные идентификаторы сеансов. | +| `--fields ` | Вернуть только выбранные поля. | +| `--full-ids` | Показать полные ID сеансов. | | `--scores-full` | Показать все оценки в выводе терминала. | ### Ошибки @@ -130,28 +133,28 @@ fp errors [OPTIONS] | Параметр | Описание | | --- | --- | -| `--aggregate` | Суммировать совпадающие ошибки вместо списка строк. | -| `--limit`, `-n ` | Максимальное количество строк списка. По умолчанию: `50`. | -| `--since`, `--from`, `--to` | Выберите диапазон времени. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Сузить совокупность ошибок. | -| `--search ` | Поиск текста данных; повторяемый. | -| `--order asc\|desc` | Временной порядок. | +| `--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` | Показать полные идентификаторы сеансов. | +| `--fields ` | Вернуть только выбранные поля. | +| `--full-ids` | Показать полные ID сеансов. | ### Использование и значения фильтров | Команда | Назначение | | --- | --- | -| `fp usage` | Показать использование для текущего окна расчётов. | +| `fp usage` | Показать использование для текущего окна расчета. | | `fp list envs` | Список наблюдаемых окружений. | -| `fp list agents` | Список наблюдаемых идентификаторов агентов. | +| `fp list agents` | Список наблюдаемых ID агентов. | | `fp list event_types` | Список типов событий. | -| `fp list score_filters` | Список ключей оценок оценок. | -| `fp list models` | Список названий моделей. | -| `fp list hooks` | Список названий хуков. | -| `fp list tools` | Список названий инструментов. | +| `fp list score_filters` | Список ключей оценки оценок. | +| `fp list models` | Список имен моделей. | +| `fp list hooks` | Список имен хуков. | +| `fp list tools` | Список имен инструментов. | | `fp list error_types` | Список типов ошибок. | ### Организации @@ -159,34 +162,34 @@ fp errors [OPTIONS] | Команда | Назначение | | --- | --- | | `fp orgs list` | Список доступных организаций. | -| `fp orgs switch [SLUG]` | Сохранить активную организацию; подсказать при пропуске. | +| `fp orgs switch [SLUG]` | Сохранить активную организацию; запросить при отсутствии. | | `fp orgs current` | Показать активную организацию. | | `fp orgs perms` | Показать ваши разрешения в активной организации. | -### API ключи +### Ключи 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 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]` | Выполнить сохранённый запрос или ad-hoc 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]` | Список запрашиваемых таблиц или проверить одну таблицу. | — | ### Пользователи @@ -205,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` | ### Оповещения @@ -214,36 +217,36 @@ 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` | Обновить или переименовать оповещение. | параметры create плюс `--name`; `--yes`, `-y` | +| `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 и 86400 секундами. +Серьезность оповещений: `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` | Создать аудит и сразу же поставить его первый запуск в очередь. | См. [параметры create](#audit-create-options). | -| `fp audits edit NAME` | Заменить параметры аудита, сохраняя неуказанные значения. | параметры определения create; `--name`; `--yes`, `-y` | -| `fp audits delete NAME` | Удалить аудит, его выводы и историю запусков. | `--yes`, `-y` | -| `fp audits run NAME` | Поставить ручной запуск в очередь. | — | +| `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 ` | -#### Параметры create аудита +#### Параметры создания аудита ```bash fp audits create checkout-reliability \ @@ -259,26 +262,26 @@ 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. | +| `--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 ''` | Фильтровать по `environments`, `agent_ids` или другим поддерживаемым полям области. | | `--ignore-error-type ` | Исключить типы ошибок; повторяйте или разделяйте запятыми. | -| `--llm` / `--no-llm` | Включить или отключить анализ агентом. По умолчанию: включено. | -| `--top-k ` | Сохранить `1`–`500` выводов. По умолчанию: `50`. | -| `--sensitivity low\|medium\|high` | Установить чувствительность отчётов. По умолчанию: `medium`. | +| `--llm` / `--no-llm` | Включить или отключить анализ с помощью агентов. По умолчанию: включено. | +| `--top-k ` | Сохранить `1`–`500` находок. По умолчанию: `50`. | +| `--sensitivity low\|medium\|high` | Установить чувствительность отчетности. По умолчанию: `medium`. | | `--channels ''` | Массив канала уведомлений. | | `--text ` | Встроенное краткое описание, максимум 8192 символа. | -| `--text-file ` | Прочитать краткое описание из файла; взаимно исключающий с `--text`. | -| `--url ` | Добавить открытую справочную ссылку HTTPS; повторите до пяти раз. | +| `--text-file ` | Прочитать краткое описание из файла; взаимоисключающие с `--text`. | +| `--url ` | Добавить публичную справку HTTPS; повторяйте до пяти раз. | -Включите контекст во время создания, если первый запуск его требует. Создание фиксирует определение и контекст вместе перед началом поставленного в очередь запуска. +Включите контекст при создании, когда первый запуск его нужен. Создание фиксирует определение и контекст вместе перед началом поставленного в очередь запуска. - `fp audits run` асинхронный. Опрашивайте `fp audits runs NAME` до тех пор, пока последний запуск не успеет или не завершится ошибкой перед чтением его выводов. + `fp audits run` асинхронный. Опрашивайте `fp audits runs NAME` до тех пор, пока последний запуск не завершится успехом или неудачей, перед чтением его находок. ### Проблемы @@ -286,11 +289,11 @@ fp audits create checkout-reliability \ | Команда | Назначение | Параметры | | --- | --- | --- | | `fp issues list` | Список проблем. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | Подсчёт открытых или выбранных состояний проблемы. | `--state` | +| `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` | @@ -299,54 +302,98 @@ fp audits create checkout-reliability \ | `fp issues subscribe INCIDENT_ID` | Подписать себя или другого оператора. | `--email` | | `fp issues unsubscribe INCIDENT_ID` | Удалить подписку. | `--email` | -Допустимые состояния проблемы: `firing`, `acknowledged` и `resolved`. Серьёзность отдельной проблемы: `info`, `warning` и `critical`. +Допустимые состояния проблем: `firing`, `acknowledged` и `resolved`. Серьезность автономной проблемы: `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 delete CHAT_ID` | Удалить разговор. | `--yes`, `-y` | + +### Политики + +Версии управляемых облаком политик. **Только для сеанса** — каждая команда здесь выходит с `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`. | — | + +### Флот -### Cloud ассистент +Какие машины запускают какие политики. **Только для сеанса**, по той же причине, что и выше. | Команда | Назначение | Параметры | | --- | --- | --- | -| `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 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` | + +### Guardrails + +Что принудительное применение на самом деле сделало. **Только для сеанса**, по той же причине, что и выше. + +| Команда | Назначение | Параметры | +| --- | --- | --- | +| `fp guardrails summary` | Охват, заблокированные/оцененные итоги, спарклайн запретов и таблица на политику. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Решения распределены по окну, суммированы по каждому источнику политики. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | ## Глобальные флаги | Флаг | Описание | | --- | --- | -| `--json` | Выдать машиночитаемый JSON. | -| `--base-url ` | Использовать самостоятельно размещённую или развивающую панель управления. | +| `--json` | Вывести машиночитаемый JSON. | +| `--base-url ` | Использовать самохостируемую или разработческую панель управления. | | `--org ` | Выбрать организацию для этого вызова. | -| `--token ` | Переопределить сохранённый токен пользовательского сеанса. | +| `--token ` | Переопределить сохраненный маркер сеанса пользователя. | | `--api-key ` | Аутентифицировать автоматизацию с помощью ключа API; никогда не сохраняется. | | `--timeout ` | Тайм-аут HTTP; должен быть положительным. По умолчанию: `30`. | -| `--quiet`, `-q` | Подавить выход статуса на stderr. | +| `--quiet`, `-q` | Подавить статус-выход на stderr. | | `--no-color` | Отключить цветной вывод. | | `--insecure` / `--secure` | Отключить или восстановить проверку сертификата TLS. | -| `--version` | Напечатать развёрнутую версию и выйти. | +| `--version` | Вывести расширенную версию и выйти. | | `--help`, `-h` | Показать справку. | -`--api-key` предназначен для автоматизации. Вход, переключение организации и команды ассистента требуют пользовательский сеанс. +`--api-key` предназначен для автоматизации. Вход, переключение организации и команды помощника требуют сеанс пользователя. ## Переменные окружения | Переменная | Эквивалент или назначение | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | Переместить текущий каталог конфигурации CLI. | -| `AGENTEYE_ANALYTICS_DISABLED` или `DO_NOT_TRACK` | Отключить анонимную аналитику CLI. | +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `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` | Отключить цветной вывод. | -Явные флаги переопределяют переменные окружения, которые переопределяют сохранённую конфигурацию. В режиме ключа API явно выберите тенанта с помощью `--org` или `AGENTEYE_ORG`. +Явные флаги переопределяют переменные окружения, которые переопределяют сохраненную конфигурацию. В режиме ключа API выберите тенанта явно с `--org` или `FP_ORG`. + + + Варианты `AGENTEYE_*` этих переменных **не читаются `fp`** и никогда не читались — CLI объявляет `FP_*` (`fp_cli/app.py`), и неизвестная переменная не является ошибкой. Установка `AGENTEYE_DASHBOARD_URL` не перенацеливает 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 6ae1f56d4..50d9f5b52 100644 --- a/docs/ru/reference/custom-agents.mdx +++ b/docs/ru/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- title: "Пользовательские агенты" -description: "Инструментируйте трассировки пользовательских агентов, чтобы Failproof AI мог восстановить их выполнение и найти сбои." +description: "Конфигурация, каталог событий, правила корреляции и доставка для failproofai-sdk." icon: "python" --- -Инструментируйте трассировки пользовательского агента с помощью `failproofai-sdk`, чтобы Failproof AI мог восстановить каждое выполнение, проверить его поведение и найти подтвержденные доказательства сбоев. SDK записывает структурированные события, которые демон Failproof доставляет в Cloud. Требуется Python 3.10 или новее. +Что делает каждый параметр, метод и поле. Если вы впервые настраиваете инструментарий, начните с руководства — эта страница предназначена для справок. -Трассировка делает пользовательские агенты наблюдаемыми и проверяемыми. Для предотвращения небезопасного действия перед его выполнением также требуется хук принудительного применения в вашей среде выполнения. + + + Установка, инструментирование, методы событий, полный пример и частые проблемы. + + + LangChain, CrewAI, LlamaIndex и Pydantic AI автоматически инструментируются одним вызовом. + + - - Чтобы применить политики в пользовательской установке агента, [свяжитесь с Failproof AI](mailto:support@befailproof.ai). Мы поможем отобразить границы модели, инструментов и жизненного цикла вашей среды выполнения на хуки политик. - +Python 3.10 или новее. Без зависимостей в рантайме. -
- -
- -## Установите `failproofai-sdk` - -SDK в настоящее время распространяется как приватный wheel. Попросите текущую версию и доступ к загрузке у вашего контакта в Failproof AI. +## Установка ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -С `uv` сначала загрузите wheel и выполните `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl`. Зафиксируйте wheel в приватном репозитории артефактов или в блокировке зависимостей. - -Пакет устанавливается как `failproofai-sdk` и импортируется в Python как `failproofai`. +Пакет устанавливается как `failproofai-sdk` и импортируется в Python как `failproofai_sdk`. Расширения для фреймворков, такие как `failproofai-sdk[langgraph]`, устанавливают сам фреймворк; адаптеры всегда идут в базовом пакете. -## Подключите демон Failproof +## Подключение демона Failproof - + 1. Перейдите в **Admin → Keys** и создайте ключ с `events:add`. - 2. [Подключите демон Failproof к Cloud](/ru/start/setup#connect-a-machine-to-cloud) на машине агента. - 3. Запустите один инструментированный сеанс, затем найдите его точный ID в **Observe → Events**. - 4. Перейдите в **Observe → Sessions**, выберите ту же среду и откройте восстановленную трассировку. + 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) ```bash @@ -51,102 +46,84 @@ python -c "import failproofai; print(failproofai.__version__)" -## Инструментируйте полное выполнение - -Вызовите `configure()` один раз при запуске процесса. Каждый вызов события требует только именованные аргументы и требует стабильных `session_id` и `agent_id`. +## Конфигурация ```python -import traceback -import uuid +import failproofai_sdk -import failproofai +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -failproofai.configure(environment="production") +| Аргумент | Что это делает | +| --- | --- | +| `environment` | Метка на каждом событии — `production`, `staging`, `prod-eu`. По умолчанию `dev`. | +| `flush_interval` | Как часто фоновый поток записывает на диск, в секундах. По умолчанию `0.5`. | +| `base_dir` | Где записывать. По умолчанию используется очередь демона, что верно, если вы не знаете иное. | -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +Установите через переменную окружения: -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) +| Переменная | Что это делает | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | Устанавливает `environment` без изменения кода, когда метка принадлежит развёртыванию, а не приложению. Аргумент `configure()` имеет приоритет. | +| `FAILPROOFAI_HOME` | Перемещает корень Failproof AI, содержащий очередь. | +| `FAILPROOFAI_SDK_STRICT` | `1` заставляет ошибки инструментирования вызывать исключение вместо логирования. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` заставляет проблему совместимости фреймворка вызывать исключение вместо предупреждения и продолжения работы. | -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + + **Без запятых в `environment`.** Ingest разделяет это поле по запятым для построения фильтров и пропускает любое событие, чья метка содержит запятую — вся сессия молча исчезает. Напишите `prod-eu`, а не `prod,eu`. + + `configure(environment="prod,eu")` вызывает исключение, чтобы вы сразу об этом узнали. `AGENTEYE_ENVIRONMENT` не может вызвать исключение — никто вас не вызывает — поэтому выдаёт предупреждение один раз и возвращается к `dev`. + -Выпускайте `agent_start` один раз за участника. Для подагентов повторно используйте `session_id` родителя, дайте каждому участнику отдельный `agent_id` и установите `parent_id` на **ID агента** родителя, а не на ID сеанса. +События ставятся в очередь в памяти и записываются в фоне каждые `flush_interval` секунд, с финальной записью при выходе из интерпретатора. Процесс, убитый насильно, теряет всё, что ещё не было записано. -## Справочник по конфигурации +## Идентификация + +Каждое событие принадлежит сессии и агенту. **Области видимости заполняют обе**, поэтому вы редко их передаёте: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| Параметр | Поведение | -| --- | --- | -| `base_dir` | Явный корень очереди. Имеет приоритет над всеми переменными окружения. | -| `flush_interval` | Секунды между фоновыми записями из памяти в JSONL. По умолчанию: `0.5`. | -| `environment` | Метка развертывания для каждого события. По умолчанию `dev`. | -| `FAILPROOFAI_HOME` | Изменяет корень Failproof AI, который содержит очередь `custom-agents`. | - -SDK записывает в явный `base_dir` при его установке. В противном случае используется очередь `custom-agents` демона Failproof в `FAILPROOFAI_HOME` или `~/.failproofai`. +Явное прохождение `session_id` или `agent_id` по-прежнему работает и имеет приоритет. Без привязанных или переданных значений вызов вызывает `TypeError` вместо отправки события, которое облако молча отбросит. -SDK ставит вызовы в очередь в памяти и записывает пакеты на фоновом потоке. Он также пытается выполнить финальную промывку через обработку `atexit` Python. Для недолгоживущих рабочих процессов позвольте нормальному завершению интерпретатора; принудительное завершение процесса может привести к потере событий, оставшихся в памяти. + + Идентификация работает на контекстных переменных. Она автоматически следует за задачами `asyncio`, но **не** за новыми потоками — оборните рабочий процесс в `failproofai_sdk.propagate()` или его события будут не присоединены. + ## Каталог событий -Все методы возвращают `None`. Поля, оставленные как `None`, опускаются вместо того, чтобы быть написанными как JSON `null`. +Пятнадцать методов. Большинство идут **парами** — вы вызываете открывающий метод, затем закрывающий, и 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` | + +Три работают отдельно: `error`, `human_pause`, `human_interrupt`. + + + +Каждый метод также принимает `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ SDK ставит вызовы в очередь в памяти и записы | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -Используйте `outcome="failed"`, `"error"`, `"timeout"` или `"rejected"` когда завершение должно считаться сбоем. Другие значения, включая `"failure"`, не классифицируются как сбои текущим бэкендом. + + + + Чтобы отметить сессию как неудачную, `outcome` должен быть одним из `failed`, `error`, `timeout` или `rejected`. Всё остальное — включая почти совпадающее `"failure"` — считается успехом. + + +## Парирование и длительность + +**Одно правило: передайте закрывающему событию такой же id, как его открывающему.** Это то, что их связывает, и что позволяет SDK отмерить разницу. + +| Пара | Совпадение по | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**Не передавайте `duration_ms` самостоятельно.** SDK измеряет его, и передача вызывает `ValueError`. -## Правила корреляции и длительности +Единственное исключение — `model_response`, где только вы знаете реальную задержку провайдера. Передайте целое число миллисекунд — float вызовет ошибку, потому что столбец является 32-битным целым числом и иначе останется пустым. -- Повторно используйте один и тот же `tool_call_id`, `hook_id`, `pause_id` или `input_id` для соответствующего события завершения. -- SDK вычисляет `duration_ms` для `tool_result`, `hook_completed`, `agent_resume` и `human_input`. Передача его самостоятельно этим методам вызывает `ValueError`. -- ID инструментов и хуков используют один глобальный процесс-широкий map ожидающих. Сделайте их уникальными по всем параллельным сеансам и во всех пространствах имен; ID поставщиков или UUID безопаснее всего. -- Пара, разделенная между процессами, по-прежнему коррелирует в нижестоящем направлении, но SDK не может вычислить его длительность внутри процесса. -- Карта ожидания содержит не более 10000 начал и вытесняет самую старую запись при заполнении. + -## Пользовательские поля и полезные нагрузки +- **Ids должны быть уникальными только для вида, для сессии.** Вызов инструмента и хук могут их делить; две сессии, работающие одновременно, могут повторно использовать одни и те же ids без столкновений. +- **Они не привязаны к агенту.** Пара, открытая под одним агентом и закрытая под другим, всё ещё совпадает — это нормальный случай в многоагентном коде. +- **`request_id` опциональный, но рекомендуется.** Без него события модели соединяются в порядке поступления, поэтому два одновременных вызова в одном агенте могут неправильно соединиться. +- **Пара, разделённая между процессами**, всё ещё совпадает в облаке, но SDK не может её отмерить — ничто в любом процессе не видело обе половины. +- **Не более 10 000 открывающих ждёт закрывающего одновременно.** После этого самое старое выбрасывается, поэтому утечка не может расти без границ. -Каждое событие принимает дополнительные поля ключевых слов. Используйте значения, совместимые с JSON, когда нижестоящим запросам требуется структура. Неподдерживаемые листья, такие как UUID, даты-времени, десятичные числа, наборы, байты и объекты модели, преобразуются в строки средством записи. + -Зарезервированные пользовательские имена: `timestamp`, `session_id`, `agent_id`, `type` и `environment`. Опечатки в необязательных полях принимаются как новые пользовательские поля, поэтому проверьте выпущенный JSON, когда стандартное поле не появляется в Cloud. +## Ваши собственные поля + +Любое дополнительное ключевое слово, которое вы передаёте, сохраняется с событием: + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # ваши собственные +) +``` + +Предпочитайте JSON типы, если позже захотите их запросить. Всё остальное — UUID, datetime, `Decimal`, set, bytes, объект модели — сохраняется как строка. + + + **Добавляйте префикс к названиям полей.** Дополнительные поля применяются последними, поэтому поле, названное `model`, `tool_name` или `outcome`, молча перезаписывает реальное. Адаптеры фреймворков используют `fw_`; делайте то же самое и ничто не может столкнуться. + + Это также объясняет, почему опечатка в опциональном поле никогда не ошибается — она просто становится новым пользовательским полем. Если стандартное поле отсутствует в облаке, сначала проверьте правописание. + + +Эти пять названий зарезервированы и отклоняются сразу: `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 @@ -189,10 +203,14 @@ SDK ставит вызовы в очередь в памяти и записы -Если 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. -Отправьте письмо на адрес [support@befailproof.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/events-and-configuration.mdx b/docs/ru/reference/events-and-configuration.mdx index fb25c4417..b99b08076 100644 --- a/docs/ru/reference/events-and-configuration.mdx +++ b/docs/ru/reference/events-and-configuration.mdx @@ -6,36 +6,36 @@ icon: "list-tree" ## Семейства событий -- Запуск, остановка, пауза и возобновление агента +- Запуск, завершение, пауза и возобновление агента - Запрос и ответ модели - Использование инструмента и результат -- Запуск и завершение хука +- Hook запущен и завершен - Ожидание человека, ввод, пауза и прерывание - Явные ошибки -Каждое событие содержит временную метку, ID сессии, ID агента, тип события и окружение. События также содержат поля, специфичные для типа события: данные о модели, инструменте, корреляции, исходе, содержимом, длительности или ошибке. +Каждое событие содержит временную метку, ID сессии, ID агента, тип события и окружение. Поля, специфичные для события, содержат данные о модели, инструменте, корреляции, результате, содержимом, длительности или ошибке. ## Проверка контракта события 1. Откройте **Observe → Events**. - 2. Установите короткий временной диапазон и отфильтруйте по окружению, агенту и типу события. - 3. Выберите событие для проверки его нормализованных полей и необработанной полезной нагрузки, затем откройте его сессию, чтобы увидеть контекст выполнения. - 4. Если отсутствует парное событие длительности, убедитесь, что события начала и завершения используют один и тот же ID корреляции. + 2. Установите короткий временной интервал и отфильтруйте по окружению, агенту и типу события. + 3. Выберите событие, чтобы проверить его нормализованные поля и исходный полезный груз, затем откройте его сессию, чтобы увидеть контекст выполнения. + 4. Если отсутствует парная длительность, убедитесь, что события запуска и завершения используют один и тот же ID корреляции. - Используйте поток Events для сужения данных до одного запуска агента и проверки нормализованных полей события. + Используйте поток Events, чтобы сузить данные до одного запуска агента и проверить нормализованные поля события. ![Живой поток Events с фильтрами по окружению, агенту, сессии и типу события.](/images/dashboard/events-stream.png) - Затем перейдите к событию в его сессию. Трассировка показывает, что произошло непосредственно до и после него, что необходимо, когда только полезной нагрузки недостаточно для понимания. + Затем перейдите к событию в его сессию. Трасса показывает, что произошло непосредственно до и после него, что необходимо, когда полезный груз сам по себе неоднозначен. - ![Связанная трассировка сессии для проверки события в контексте выполнения.](/images/dashboard/session-detail.png) + ![Связанная трасса сессии для проверки события в контексте выполнения.](/images/dashboard/session-detail.png) - Сравните ID корреляции и временные метки в обоих представлениях, если отсутствует парное событие или длительность. + Сравните ID корреляции и временные метки в обоих представлениях, когда отсутствует парное событие или длительность. - Обнаружьте допустимые значения фильтров, затем получите полные полезные нагрузки событий для одной сессии: + Откройте действительные значения фильтров, затем получите полные полезные грузы событий для одной сессии: ```bash fp list event_types @@ -47,32 +47,32 @@ icon: "list-tree" --full ``` - Используйте `fp --json events ... --fields ts,event_type,session_id,payload` для проверки в формате, читаемом машиной. + Используйте `fp --json events ... --fields ts,event_type,session_id,payload` для проверки в машиночитаемом формате. ## Зарезервированные поля SDK -Не используйте `timestamp`, `session_id`, `agent_id`, `type` или `environment` в качестве пользовательских полей Python SDK. Длительности парных событий, такие как длительность результата инструмента, рассчитываются SDK и не могут быть предоставлены вручную. +Не используйте `timestamp`, `session_id`, `agent_id`, `type` или `environment` как пользовательские поля Python SDK. Парные длительности событий, такие как длительность результата инструмента, рассчитываются SDK и не могут быть предоставлены вручную. ## Локальные границы -- Состояние Failproof AI находится в `~/.failproofai`, если не указано иное. -- `failproofai-sdk` использует `AGENTEYE_HOME` для своего переопределения базовой директории в режиме совместимости. +- Состояние Failproof AI хранится в `~/.failproofai`, если не настроено иное. +- `failproofai-sdk` всегда буферизирует под `~/.failproofai/custom-agents`. `FAILPROOFAI_HOME` перемещает этот домашний каталог; сегмент `custom-agents` всегда добавляется, поэтому буфер не может быть размещен вне него. Только собственная функция `configure(base_dir=...)` SDK записывает в другие места. `AGENTEYE_HOME` читается устаревшим `agenteye-collector` для выбора того, что наблюдать, и больше не влияет на место записи SDK. - Метки окружений можно установить через конфигурацию SDK или `AGENTEYE_ENVIRONMENT`. -- Учетные данные демона хранятся отдельно от параметров без тайны. +- Учетные данные демона хранятся отдельно от параметров без секретов. -Используйте стабильные имена окружений с низкой кардинальностью. Запятые не поддерживаются в метках окружений демона. +Используйте стабильные, низкокардинальные названия окружений. Запятые не поддерживаются в метках окружений демона. ## Изменение метки окружения - Метки окружений назначаются эмитирующим SDK или демоном Failproof. После изменения откройте **Observe → Sessions** и используйте фильтр окружений, чтобы подтвердить, что новые сессии содержат новое значение. Существующие сессии сохраняют свое исходное окружение. + Метки окружений назначаются излучающим SDK или демоном Failproof. После изменения откройте **Observe → Sessions** и используйте фильтр окружения, чтобы подтвердить, что новые сессии содержат новое значение. Существующие сессии сохраняют свое исходное окружение. - Для `failproofai-sdk` настройте окружение в коде или с помощью его переменной окружения в режиме совместимости. Перезапустите конфигурацию демона при изменении параметров на уровне машины. + Для `failproofai-sdk` настройте окружение в коде или с помощью его устаревшей переменной окружения. Повторно запустите конфигурацию демона при изменении параметров на уровне машины. ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/ru/reference/harnesses.mdx b/docs/ru/reference/harnesses.mdx index 839f7de17..b80d1761f 100644 --- a/docs/ru/reference/harnesses.mdx +++ b/docs/ru/reference/harnesses.mdx @@ -1,71 +1,72 @@ --- +--- title: "Адаптеры агентов" 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 -- **Шлюзы чата и ассистентов** (2) — Hermes (Slack, Telegram, cron), OpenClaw (самостоятельно развёрнутый ассистент) +- **Chat и assistant гейтвеи** (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 предоставляет трассировку, сессии, оценки и аудиты — **он не применяет политики самостоятельно.** Для блокировки опасного действия до его выполнения необходим хук принудительного исполнения на границе инструментов вашего runtime; [свяжитесь с нами](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` | Блокировка после инструмента заменяет результат после выполнения; события начала сессии и уплотнения доступны только для наблюдения в текущем адаптере. | -| 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. Откройте **Administration → Keys** и создайте ключ с правами `events:add` и `policies:pull`, назвав его по имени машины или окружения. - 2. На целевой машине подключите локальный CLI с отображённым ключом и установите перехваты адаптера. - 3. Запустите новую сессию агента, а затем подтвердите события перехвата и сессии в разделе **Observe → Events**. - 4. Откройте **Observe → policy** для того же временного окна и подтвердите, что решение политики атрибутировано машине. + + 1. Откройте **Administration → Keys** и создайте ключ с разрешениями `events:add` и `policies:pull`, названный для машины или окружения. + 2. На целевой машине подключите локальный CLI с отображаемым ключом и установите хуки адаптера. + 3. Запустите новую сессию агента, затем подтвердите его хуки и события сессии в разделе **Observe → Events**. + 4. Откройте **Observe → policy** для того же временного окна и подтвердите, что решение политики привязано к машине. - Соединение начинается с ключа машины. Убедитесь, что он включает оба разрешения на приём и доставку политик перед копированием его секрета. + Подключение начинается с ключа машины. Подтвердите, что он включает как разрешения на ингestion, так и доставку политик перед копированием его секрета. - ![Ящик нового ключа API, используемый для предоставления разрешений на приём событий и доставку политик.](/images/dashboard/key-create.png) + ![Новый ящик API-ключа, используемый для предоставления разрешений на ингestion событий и доставку политик.](/images/dashboard/key-create.png) - После установки перехватов поток событий должен показать новые события от машины и окружения, которые вы подключили. + После установки хуков поток событий должен показывать новые события с машины и окружения, которые вы подключили. - ![Живой поток событий, используемый для подтверждения того, что вновь установленный адаптер сообщает данные.](/images/dashboard/events-stream.png) + ![Живой поток событий, используемый для подтверждения того, что вновь установленный адаптер отправляет отчёты.](/images/dashboard/events-stream.png) - Наконец, убедитесь, что решения политик атрибутируются той же машине. Это подтверждает, что адаптер сообщает как о деятельности политик, так и о событиях трассировки. + Наконец, проверьте, что решения политик привязаны к одной и той же машине. Это подтверждает, что адаптер отправляет отчёты как о действии политики, так и о событиях трассировки. - ![Страница политики, используемая для проверки решений политик от вновь подключённого адаптера.](/images/dashboard/policy-observe.png) + ![Страница Policy, используемая для проверки решений политик из вновь подключённого адаптера.](/images/dashboard/policy-observe.png) - Установите перехваты для каждого обнаруженного адаптера: + Установите хуки для каждого обнаруженного адаптера: ```bash failproofai config \ @@ -74,7 +75,7 @@ icon: "plug-zap" failproofai policies --install ``` - Или выберите именованные адаптеры и область конфигурации: + Или направьте именованные адаптеры и область конфигурации: ```bash failproofai policies --install \ @@ -82,7 +83,7 @@ icon: "plug-zap" --scope user ``` - Область проекта хранит конфигурацию перехвата в репозитории. Область пользователя охватывает работу между репозиториями. Claude Code также поддерживает локальную область; поддержка варьируется по адаптерам и CLI отклоняет неподдерживаемые комбинации. + Область project хранит конфигурацию хука с репозиторием. Область user охватывает работу в разных репозиториях. Claude Code также поддерживает область local; поддержка варьируется в зависимости от адаптера и CLI отклоняет неподдерживаемые комбинации. Проверьте машину и её события: @@ -94,16 +95,16 @@ icon: "plug-zap" -## Добавьте нестандартный путь сессии +## Добавьте неstandard путь сессии - - Дополнительные пути регистрируются на машине, а не в облаке. После добавления откройте **Observe → Sessions**, отфильтруйте по окружению машины и подтвердите, что сессии с нового пути появляются. Откройте сессию и проверьте агента, адаптер и временные метки событий перед использованием в аудите. + + Дополнительные пути регистрируются на машине, а не в Cloud. После добавления откройте **Observe → Sessions**, отфильтруйте по окружению машины и подтвердите, что появляются сессии с нового пути. Откройте сессию и проверьте агента, адаптер и временные метки событий перед использованием в аудите. - ![Список сессий, отфильтрованный по окружению, получающему данные из дополнительного пути захвата.](/images/dashboard/sessions-list.png) + ![Список Sessions, отфильтрованный по окружению, получающему данные с дополнительного пути захвата.](/images/dashboard/sessions-list.png) - Добавьте путь с необязательной меткой, затем проверьте настроенные пути: + Добавьте путь с дополнительной меткой, затем проверьте настроенные пути: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -117,5 +118,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 fba160296..abd24ff8b 100644 --- a/docs/ru/reference/overview.mdx +++ b/docs/ru/reference/overview.mdx @@ -1,20 +1,23 @@ --- title: "Интеграции и справочник" -description: "Подключите поддерживаемые harness'ы агентов, SDK, CLI и HTTP API." +description: "Подключите поддерживаемые фреймворки агентов, SDK, CLI и HTTP API." icon: "braces" --- -Выберите интеграцию, которая лучше всего соответствует месту запуска вашего агента. +Выберите интеграцию, которая наиболее подходит для вашего агента. - - Установите hooks для поддерживаемых CLI для кодирования и автономных агентов. + + Установите hooks для поддерживаемых CLI кодирования и автономных агентов. - - Инструментируйте traces для выявления ошибок в пользовательских агентах, затем свяжитесь с нами, чтобы добавить предотвращение в вашу среду выполнения. + + Интегрируйте LangGraph, CrewAI, LlamaIndex, Pydantic AI или пользовательского агента. - - Просматривайте локальные проекты, сессии, активность политик и автономные аудиты. + + Конфигурация, каталог событий, правила корреляции и доставка. + + + Просмотрите локальные проекты, сессии, активность политик и автономные аудиты. Настройте локальное захватывание, hooks, политики, аудиты, доставку и состояние машины. @@ -23,36 +26,36 @@ icon: "braces" Запрашивайте и администрируйте облачные сессии, аудиты, проблемы, оповещения, ключи, пользователей и параметры. - Оценивайте полные или неактивные сессии с помощью сервиса FastAPI. + Оцените полные или неактивные сессии с помощью FastAPI сервиса. - - Создавайте и тестируйте решения allow, instruct и deny для конкретных рабочих процессов. + + Создавайте и тестируйте решения allow, instruct и deny для специфичных рабочих процессов. - - Разверните плоскость управления Cloud на управляемом клиентом кластере Kubernetes. + + Разверните управляющую плоскость Cloud на управляемом клиентом кластере Kubernetes. -Сгенерированный [справочник HTTP API](/ru/reference/http-api) охватывает общедоступную поверхность `/v1`. Написанные вручную страницы объясняют рабочие процессы, охватывающие несколько конечных точек или использующие административные интерфейсы, находящиеся вне этой общедоступной поверхности. +Созданный [справочник HTTP API](/ru/reference/http-api) охватывает поверхность `/v1`. Отдельные страницы объясняют рабочие процессы, которые охватывают несколько endpoint'ов или используют административные интерфейсы вне этой поверхности. ## Подключите агента и проверьте данные - - 1. Откройте **Administration → Keys**, создайте ключ с разрешениями `events:add` и `policies:pull`, и скопируйте секрет. + + 1. Откройте **Administration → Keys**, создайте ключ с разрешениями `events:add` и `policies:pull` и скопируйте секрет. 2. Настройте интеграцию, используя соответствующую страницу выше. - 3. Откройте **Observe → Events**, чтобы подтвердить получение событий, затем **Observe → Sessions**, чтобы подтвердить, что они образуют полные запуски. - 4. Отфильтруйте по окружению интеграции и проверьте одну сессию на наличие полей модели, инструмента, ошибки и политики, необходимых для аудитов. + 3. Откройте **Observe → Events** чтобы подтвердить поступление событий, затем **Observe → Sessions** чтобы подтвердить, что они формируют полные запуски. + 4. Отфильтруйте по окружению интеграции и проверьте одну сессию на наличие полей model, tool, error и policy, необходимых для аудитов. Начните с ящика ключей. Выбранные разрешения определяют, может ли машина отправлять события и получать управляемые облаком политики. - ![Новое окно создания 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) - Откройте одну из этих сессий перед тем, как считать интеграцию завершённой; трасса должна содержать доказательства модели, инструмента, ошибки и политики, которые нужны вашим аудитам. + Откройте одну из этих сессий перед тем, как считать интеграцию полностью настроенной; трассировка должна содержать доказательства model, tool, error и policy, необходимые вашим аудитам. Создайте машинный ключ, подключите демон Failproof и проверьте первую сессию. @@ -71,8 +74,8 @@ icon: "braces" 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](/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-commands) для команд `fp`. \ No newline at end of file diff --git a/docs/ru/reference/troubleshooting.mdx b/docs/ru/reference/troubleshooting.mdx index cec546fea..aad40478d 100644 --- a/docs/ru/reference/troubleshooting.mdx +++ b/docs/ru/reference/troubleshooting.mdx @@ -1,16 +1,16 @@ --- -title: "Устранение неполадок" -description: "Диагностика отсутствующих сеансов, отсутствующих политик, сбоев доставки и заблокированных действий агента." +title: "Диагностика проблем" +description: "Диагностируйте отсутствующие сеансы, отсутствующие политики, ошибки доставки и заблокированные действия агента." icon: "wrench" --- - + - Откройте **Administration → Keys** и убедитесь, что ключ машины активен и имеет разрешение `events:add`. Затем откройте **Observe → Events**, расширьте диапазон времени и очистите фильтры окружения и агента. Если события существуют, выполните поиск по ID сеанса и проверьте **Observe → Sessions** для группировки. Если событий нет, диагностируйте демон Failproof из CLI. + Откройте **Administration → Keys** и убедитесь, что ключ машины активен и имеет разрешение `events:add`. Затем откройте **Observe → Events**, расширьте диапазон времени и очистите фильтры окружения и агента. Если события существуют, найдите ID сеанса и проверьте **Observe → Sessions** для группировки. Если событий нет, диагностируйте демон Failproof из CLI. - ![Поток живых событий с видимыми основными фильтрами и поступающими недавними событиями агента.](/images/dashboard/events-stream-current.png) + ![Живой поток событий с основными фильтрами и недавними событиями агента.](/images/dashboard/events-stream-current.png) ```bash @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - Убедитесь, что захват включен, настроенный ключ имеет разрешение `events:add`, и фильтр панели управления соответствует переданному окружению. + Убедитесь, что захват включен, настроенный ключ имеет разрешение `events:add` и фильтр панели управления совпадает с переданным окружением. - Очистите фильтры в **Observe → Events** и выполните поиск по точному ID сеанса SDK. Если ничего не появляется, проверьте буфер SDK и демон Failproof на исходной машине. + Очистите фильтры в **Observe → Events** и найдите точный ID сеанса SDK. Если ничего не появляется, проверьте очередь SDK и демон Failproof на исходной машине. ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - Убедитесь, что процесс агента устанавливает `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` и что `$FAILPROOFAI_HOME/custom-agents`, в противном случае `~/.failproofai/custom-agents`, существует перед запуском SDK. + Убедитесь, что демон запущен и подключен — SDK использует очередь независимо от этого. Директория очереди **не** обязательно должна существовать заранее (ее создает писатель), и нет переменной окружения, которая бы выбирала её: `$FAILPROOFAI_HOME/custom-agents`, в противном случае `~/.failproofai/custom-agents` — единственный корень, и `configure(base_dir=...)` — единственное переопределение. Если процесс был убит через `SIGKILL` или OOM, всё, что было в очереди, потеряно — обрабатывайте `SIGTERM` для ограничения этого. - Откройте **Admin → enforcement**, выберите машину и сравните назначенные, полученные и предыдущие версии. Подтвердите, что область развертывания включает машину и что ее ключ имеет разрешение `policies:pull`. Прием может работать даже когда доставка политик не работает. + Откройте **Admin → enforcement**, выберите машину и сравните назначенные, сообщённые и предыдущие версии. Убедитесь, что область развёртывания включает машину и её ключ имеет разрешение `policies:pull`. Приём событий может работать даже когда доставка политик не работает. @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - Убедитесь, что ID машины и метка соответствуют целевой машине на панели управления. Переподключитесь с ключом, способным обрабатывать политики, если существующее учетное данные предоставляет только прием событий. + Убедитесь, что ID и метка машины совпадают с целью на панели управления. Переподключитесь с ключом, поддерживающим политики, если существующие учётные данные предоставляют только приём событий. - + - Откройте **Admin → enforcement** и проверьте время последнего обращения машины и полученную версию. Если машина устарела, рассмотрите это как локальную проблему демона. Не ослабляйте развернутую политику только для обхода недоступного демона. + Откройте **Admin → enforcement** и проверьте время последнего обращения и сообщённую версию машины. Если машина устарела, рассматривайте это как проблему локального демона. Не ослабляйте развёрнутую политику только для обхода недоступного демона. @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - Перезагрузите или обновите `failproofaid`; перезапустите конфигурацию, когда версии протокола CLI и демона различаются. Настроенный путь демона по умолчанию отказывает в доступе. + Перезагрузите или обновите `failproofaid`; переустановите конфигурацию, когда версии протокола CLI и демона отличаются. Путь демона по умолчанию отказывает по дизайну. - Для политики, созданной в облаке, откройте **Admin → policy editor**, выберите черновик и изучите ошибки валидации перед публикацией. Для локальной политики используйте CLI для ее валидации, затем откройте **Observe → policy** после тестового действия, чтобы подтвердить поступление решений. + Для политики, созданной в Cloud, откройте **Admin → policy editor**, выберите черновик и проверьте ошибки валидации перед публикацией. Для локальной политики используйте CLI для её валидации, затем откройте **Observe → policy** после тестового действия для подтверждения получения решений. - Убедитесь, что имя файла заканчивается на `policies.js`, `policies.mjs` или `policies.ts`, модуль вызывает `customPolicies.add(...)`, и импорты разрешены из файла политики. + Убедитесь, что имя файла заканчивается на `policies.js`, `policies.mjs` или `policies.ts`, модуль вызывает `customPolicies.add(...)` и импорты разрешаются из файла политики. ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -94,11 +94,11 @@ icon: "wrench" - Откройте **Analyze → audits**, выберите запуск и проверьте, был ли запущен анализ модели. Затем сравните его область и окно с **Observe → sessions** и откройте репрезентативные трассы из этой популяции. + Откройте **Analyze → audits**, выберите запуск и проверьте, работал ли анализ модели. Затем сравните его область и окно с **Observe → sessions** и откройте репрезентативные трассы из этой совокупности. - Нулевой результат имеет смысл только когда анализ прошел успешно. Если анализ был пропущен или не прошел, запуск не выдает результаты и оставляет неанализированное окно открытым для будущего успешного запуска. Если анализ модели отключен, аудит также не выдает результаты, потому что детерминированное сканирование учетных данных и PII записывает статистику, но больше не выдает результаты. + Нулевой результат имеет смысл только когда анализ успешно выполнился. Если анализ был пропущен или не выполнен, запуск не выдаёт результаты и оставляет неанализированное окно открытым для будущего успешного запуска. Если анализ модели отключён, аудит также не выдаёт результатов, потому что детерминированное сканирование учётных данных и PII записывает статистику, но больше не выдаёт результатов. - ![Форма аудита, где окружение, агент, кадентность и окно развертки определяют популяцию сеансов.](/images/dashboard/audit-new.png) + ![Форма аудита, где окружение, агент, кадр и окно сканирования определяют совокупность сеансов.](/images/dashboard/audit-new.png) ```bash @@ -110,31 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - Если запуск остался в очереди, дождитесь емкости audit-agent или попросите оператора развертывания проверить флот аудитов. Аудит в очереди повторяется; он не пропускается немедленно. + Если запуск остался в очереди, дождитесь свободного места на аудит-агенте или попросите оператора развёртывания проверить флот аудитов. Аудит в очереди повторяется; он не пропускается сразу же. - + - Откройте завершенный сеанс и проверьте, завершается ли ручная оценка успешно. На размещенном облаке Cloud в настоящее время нет управления конечной точкой оценки на панели управления; оператор сервера должен ее настроить. + Откройте завершённый сеанс и проверьте, успешна ли ручная оценка. Размещённый Cloud в настоящее время не имеет управления конечной точкой оценщика на панели управления; оператор сервера должен его настроить. - Проверьте саму оценку, затем проверьте недавние состояния оценки: + Проверьте сам оценщик, затем проверьте недавние состояния оценок: ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - На самостоятельно размещенном облаке Cloud убедитесь, что `EVALUATOR_ENDPOINT` присутствует на сервере и `EVALUATOR_TOKEN` совпадает с оценкой. Автоматическая оценка отключена, когда конечная точка отсутствует. + На самостоятельно размещённом Cloud подтвердите, что `EVALUATOR_ENDPOINT` присутствует на сервере и `EVALUATOR_TOKEN` совпадает с оценщиком. Автоматическая оценка отключена когда конечная точка отсутствует. - Используйте переключатель организации и подтвердите ожидаемый слаг и разрешения перед сравнением результатов с CLI. + Используйте переключатель организации и подтвердите ожидаемые значок и разрешения перед сравнением результатов с CLI. ```bash @@ -143,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - В режиме API-ключа укажите `fp --org --api-key ...` или установите `AGENTEYE_ORG`. Сохраненное состояние организации человеческой сессии намеренно игнорируется для запросов API-ключа. + В режиме API-ключа укажите `fp --org --api-key ...` или установите `AGENTEYE_ORG`. Сохранённое состояние организации для сеанса человека намеренно игнорируется для запросов с API-ключом. - Откройте **Observe → policy**, сохраните решение и связанный сеанс, и определите условие ложного срабатывания. Затем откройте **Admin → enforcement** и откатите затронутые машины до предыдущей версии. Создайте более узкую версию в **Policy editor**, протестируйте ее на небольшой области и расширьте только после того, как допустимая работа завершится успешно. + Откройте **Observe → policy**, сохраните решение и связанный сеанс, и определите условие ложного срабатывания. Затем откройте **Admin → enforcement** и откатите затронутые машины к предыдущей версии. Создайте более узкую версию в **Policy editor**, протестируйте на небольшой области и расширяйте только после успеха допустимой работы. - Откат развертывания облака доступен только с панели управления. Локальная пауза сеанса не отключает управляемые облаком политики. Если панель управления недоступна, захватите состояние машины и развертывания и восстановите доступ к панели управления вместо того, чтобы повторно повторять заблокированное действие. + Откат развёртывания Cloud доступен только через панель управления. Локальная пауза сеанса не отключает управляемые Cloud политики. Если панель управления недоступна, сохраните состояние машины и развёртывания и восстановите доступ к панели управления вместо повторных попыток заблокированного действия. ```bash failproofai config --status @@ -164,4 +164,4 @@ icon: "wrench" -При обращении в службу поддержки укажите версию CLI, привязку, окружение, соответствующий ID сеанса или развертывания и выходные данные `failproofai config --status` с удаленными секретами. \ No newline at end of file +При обращении в поддержку включите версию CLI, среду выполнения, окружение, релевантный ID сеанса или развёртывания и результат `failproofai config --status` с удалёнными секретами. \ No newline at end of file diff --git a/docs/ru/sessions/live-events.mdx b/docs/ru/sessions/live-events.mdx index cbe05469c..9ab8d15a7 100644 --- a/docs/ru/sessions/live-events.mdx +++ b/docs/ru/sessions/live-events.mdx @@ -1,10 +1,10 @@ --- -title: "Live events" -description: "Наблюдайте за активностью агента в реальном времени во время выполнения сеанса." +title: "Прямые события" +description: "Наблюдайте за активностью агента в реальном времени во время сеанса." icon: "radio" --- -Live events помогут вам подтвердить инструментирование и отследить рискованный запуск без ожидания завершения сеанса. +Прямые события помогают подтвердить инструментирование и отследить рискованный запуск, не дожидаясь завершения сеанса. ## Наблюдение за активностью @@ -12,10 +12,10 @@ Live events помогут вам подтвердить инструменти 1. Перейдите в **Observe → Events**. 2. Начните с текущего временного окна и без фильтров, чтобы подтвердить поступление данных. - 3. Фильтруйте по окружению, типу события, агенту или сеансу. Используйте поиск по тексту полезной нагрузки. - 4. Выберите событие, чтобы проинспектировать его резюме и детали. Перейдите по ссылке сеанса для полной трассировки. + 3. Фильтруйте по окружению, типу события, агенту или сеансу. Используйте поиск для текста полезной нагрузки. + 4. Выберите событие, чтобы просмотреть его краткое описание и подробности. Перейдите по ссылке сеанса для полной трассировки. - ![Поток Live Events, показывающий трафик от шлюза Hermes chat рядом с запусками coding-CLI, отфильтрованный по времени, окружению, типу события, агенту, модели, контексту и сеансу.](/images/dashboard/events-stream-current.png) + ![Поток прямых событий, показывающий трафик от шлюза чата Hermes наряду с запусками coding-CLI, отфильтрованные по времени, окружению, типу события, агенту, модели, контексту и сеансу.](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +24,22 @@ Live events помогут вам подтвердить инструменти fp --json events --full --session-id --all ``` - Поток по умолчанию исключает исходные полезные нагрузки. Используйте `--full` только для ограниченного расследования сеанса. + Поток по умолчанию исключает сырые полезные нагрузки. Используйте `--full` только для расследования ограниченного сеанса. -Используйте поток событий, чтобы ответить на три срочных вопроса: +Используйте поток событий для ответа на три критических вопроса: -- Отправляет ли ожидаемый агент отчёты в правильное окружение? -- Поступают ли вызовы модели, вызовы инструментов и решения политики в порядке? -- Остановил ли сеанс прогресс или начал повторять действие? +- Сообщает ли ожидаемый агент в правильное окружение? +- Поступают ли вызовы моделей, вызовы инструментов и решения политик по порядку? +- Остановился ли сеанс в прогрессе или начал повторять действие? -Типы событий включают события жизненного цикла агента, запросы и ответы модели, использование и результаты инструментов, выполнение хуков, ожидание человека и прерывания, а также явные ошибки. ID корреляции связывают парные события, такие как вызов инструмента и его результат. +Типы событий включают события жизненного цикла агента, запросы и ответы модели, использование и результаты инструментов, выполнение хуков, ожидание человека и прерывания, а также явные ошибки. Идентификаторы корреляции связывают парные события, такие как вызов инструмента и его результат. - Держите live view широким при проверке новой интеграции. Добавляйте фильтры только после того, как вы увидите первое событие; неправильный фильтр может выглядеть как неудачное поглощение. + Держите прямой просмотр широким при проверке новой интеграции. Добавляйте фильтры только после того, как увидите первое событие; неправильный фильтр может выглядеть как сбой приема данных. -Если события не появляются, выполните `failproofai config --status`, затем [устраните неполадки с поглощением](/ru/reference/troubleshooting). +Если события не появляются, запустите `failproofai config --status`, затем [устраните неполадки приема данных](/ru/reference/troubleshooting). -Агенты, которые не работают в одном из 12 поддерживаемых [harnesses](/ru/reference/harnesses), отправляют те же типы событий через [Python SDK](/ru/reference/custom-agents), включая события взаимодействия с человеком (`human_wait`, `human_input`, `human_interrupt`), на которые полагаются шлюзовые и производственные агенты. \ No newline at end of file +Агенты, которые не работают в одном из 12 поддерживаемых [harnesses](/ru/reference/harnesses), сообщают об одинаковых типах событий через [Python SDK](/ru/reference/custom-agents), включая события взаимодействия человека (`human_wait`, `human_input`, `human_interrupt`), которые используют шлюзовые и производственные агенты. \ No newline at end of file diff --git a/docs/ru/start/first-policy.mdx b/docs/ru/start/first-policy.mdx index 065a88296..b82e96dc3 100644 --- a/docs/ru/start/first-policy.mdx +++ b/docs/ru/start/first-policy.mdx @@ -1,34 +1,33 @@ --- ---- -title: "Предотвратьте первый отказ с помощью политики" -description: "Напишите версию политики, разверните её в режиме наблюдения, а затем включите её применение." +title: "Предотвратите первый отказ с помощью политики" +description: "Создайте версию политики, разверните её в режиме наблюдения, а затем включите её проверку." icon: "shield-check" --- -Используйте политику только после того, как сможете описать небезопасное действие и легитимные действия, которые должны остаться разрешёнными. +Используйте политику только после того, как сможете описать небезопасное действие и законные действия, которые должны остаться разрешёнными. - Перейдите в **Admin → policy editor**. Начните с демо-политики, проверьте или отредактируйте её исходный код, затем выберите **publish version**. Публикация создаёт неизменяемую версию, которую вы можете развернуть на машинах. + Перейдите в **Admin → policy editor**. Начните с демо-политики, проверьте или отредактируйте её исходный код, затем выберите **publish version**. Публикация создаёт неизменяемую версию, которую можно развернуть на машинах. - ![Представление редактора политик с демо-политикой, готовой к публикации как неизменяемую версию.](/images/dashboard/policy-editor.png) + ![Представление редактора политик с демо-политикой, готовой к публикации в виде неизменяемой версии.](/images/dashboard/policy-editor.png) - Перейдите в **Admin → enforcement**, разверните целевую машину и выберите **edit this machine**. Добавьте опубликованную демо-политику, закрепите её версию, выберите **observe** и примените развёртывание. + Перейдите в **Admin → enforcement**, раскройте целевую машину и выберите **edit this machine**. Добавьте опубликованную демо-политику, зафиксируйте её версию, выберите **observe** и примените развёртывание. ![Редактор развёртывания машины с выбранной опубликованной версией политики в режиме наблюдения перед применением развёртывания.](/images/dashboard/enforcement-editor.png) - Запустите новый сеанс агента на этой машине, затем откройте **Observe → policy**. Выберите машину и подтвердите, что демо-политика отображается в распределении политик и временной шкале решений. Режим наблюдения записывает, что сделала бы политика, без блокировки действия. + Запустите новый сеанс агента на этой машине, затем откройте **Observe → policy**. Выберите машину и подтвердите, что демо-политика отображается в сопоставлении политик и временной шкале решений. Режим наблюдения записывает, что политика делала бы, не блокируя действие. - ![Страница Policy, отображающая итоги решений, активность применения политики с течением времени, а также локальные и облачно-управляемые распределения политик.](/images/dashboard/policy-observe.png) + ![Страница Policy, показывающая итоги решений, активность применения политики во времени, локальные и управляемые облаком сопоставления политик.](/images/dashboard/policy-observe.png) - Создание облачных политик и развёртывание флота являются административными рабочими процессами. Используйте локальный CLI для проверки той же политики перед её публикацией: + Создание облачных политик и развёртывание парка — это административные рабочие процессы. Используйте локальный CLI для проверки той же политики перед её публикацией: ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -36,13 +35,13 @@ icon: "shield-check" failproofai config --status ``` - Используйте `fp` для проверки решений по политикам, видимых облаком: + Используйте `fp` для проверки видимых облаком решений политики: ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - Cloud CLI не предоставляет маршруты развёртывания применения, доступные только root. Публикуйте версии из **Admin → policy editor** и развёртывайте их из **Admin → enforcement**. + Оба шага доступны и через CLI: `fp policies publish ` создаёт версию, а `fp fleet deploy --add ` размещает её на машине. Эквивалентные действия в dashboard — **Admin → policy editor** и **Admin → enforcement**. \ No newline at end of file diff --git a/docs/ru/start/integrations.mdx b/docs/ru/start/integrations.mdx new file mode 100644 index 000000000..51dab1e92 --- /dev/null +++ b/docs/ru/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "Инструментируй свой агент" +sidebarTitle: "Frameworks" +description: "Подключи любой поддерживаемый фреймворк агента к Failproof AI одним вызовом." +icon: "plug" +--- + +Твой агент уже производит всё, что стоит записывать — вызовы модели, вызовы инструментов, границы узлов, ожидания пользователя, ошибки. Фреймворк выбрасывает это. SDK сохраняет. + + + + Агент, который ты написал сам, или один из тех, что здесь не перечислены. + + + Графы, узлы, инструменты, ретриверы, модели. + + + Команды, потоки, агенты по ролям, инструменты. + + + Рабочие процессы, шаги, функциональные агенты, ретриверы. + + + Типизированные агенты, возможности, инструменты, повторы. + + + +## Три строки, любой фреймворк + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # обнаруживает импортированные фреймворки + +with failproofai_sdk.session(): + ... # твой существующий вызов агента, без изменений +``` + +Без декораторов на функциях, без коллбэка, передаваемого вызовам, без идентификаторов, пропущенных через твой код. Только вызов внутри сессии отличается: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # под `async with failproofai_sdk.session():` + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +Дополнительная установка — это **фреймворк**. Каждый адаптер поставляется в базовом пакете, поэтому проект, который уже имеет свой фреймворк, не нуждается ни в чём дополнительном. + +## Проверь доставку + +Запусти одну инструментированную сессию, затем открой **Observe → Sessions** и выбери твоё окружение. Запуск появится как восстановленная трасса. + +Если ничего не поступило, проверь, подключена ли машина командой `failproofai config --status`. Смотри [Настройка захвата](/ru/start/setup). + + + Не проверяй директорию спула для подтверждения доставки. Daemon Failproof собирает и удаляет каждый пакет в течение миллисекунд, поэтому чтение спула гонится с коллектором и показывает гораздо меньше событий, чем было испущено. + + +## Дальше + +Каждый быстрый старт выше ссылается на его полное руководство — что записывается, опции, потоковая передача, именование спанов и проблемы, с которыми люди на самом деле сталкиваются. Они находятся в разделе **Trace Agents → Plug in your agent**. + + + + Модель данных, идентификаторы, типы событий и как события достигают Cloud. + + + Проследи причинность через сессию вместо разрозненных логов. + + + Проверь сессии, которые ты только что захватил. + + \ No newline at end of file diff --git a/docs/ru/start/integrations/crewai.mdx b/docs/ru/start/integrations/crewai.mdx new file mode 100644 index 000000000..67004ea67 --- /dev/null +++ b/docs/ru/start/integrations/crewai.mdx @@ -0,0 +1,225 @@ +--- +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "Оркестрируйте команды, потоки, агентов по ролям, инструменты, память и обратную связь от пользователей." +icon: "/images/frameworks/crewai.svg" +--- + +## Установка + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +Поддерживается: `crewai` версии 1.13 до 2.0. 1.13 — это релиз, добавивший `started_event_id` и нормализовавший использование токенов, на которые полагается адаптер для сопоставления событий и отчётности о токенах. + +## Инструментирование + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` регистрирует слушатель на шине событий CrewAI на уровне модуля и подписывает один обработчик на класс событий. Ничего не меняется в вашей команде, агентах, задачах или инструментах. + +## Что записывается + +| CrewAI | Failproof событие | +| --- | --- | +| Запуск команды | `agent_start`, `agent_end` | +| `Agent.kickoff()` (облегчённый агент без команды) | `agent_start`, `agent_end`, с `agent_id` из роли | +| Начало и завершение потока | `agent_start`, `agent_end`; команда, запущенная внутри метода потока, вложена в него | +| Выполнение агента | Вложенные `agent_start`, `agent_end`, с `agent_id` из роли. При иерархическом процессе делегированный коллега вложен в менеджера, а не рядом с ним | +| Задача | Ничего; записывается как ссылка, чтобы дочерние элементы разрешались к команде | +| Метод потока, guardrail | `hook_triggered`, `hook_completed` | +| Использование инструмента | `tool_use`, `tool_result` | +| Операции с памятью и знаниями | `tool_use`, `tool_result`, названные по поверхности, которая была затронута | +| Вызов LLM | `model_request`, `model_response`, с использованием токенов | +| Фрагмент потока | Свёрнут в ответ как количество фрагментов и время до первого токена | +| Запрос обратной связи от пользователя | `human_wait`, `agent_pause` | +| Получена обратная связь от пользователя | `agent_resume`, `human_input` | +| Ошибка при выполнении агента | `error`, затем `agent_end` с результатом `failed` | + +Задача ничего не испускает намеренно. Задача CrewAI — это подмножество выполнения агента, который её запускает, поэтому испускание обоих означало бы удвоение каждой строки и отображение их как сиблингов. Вместо этого id и имя задачи находятся на собственных событиях агента. + +Операции с памятью и знаниями записываются как инструменты, названные по поверхности, которую они затрагивают, поэтому они появляются рядом с вашими реальными инструментами, где вы можете сравнить их латентность. + +В иерархической команде вложенность делает трассу читаемой: + +```text +crew +└─ manager + ├─ researcher delegated + └─ writer delegated +``` + +CrewAI родитель делегированного выполнения на **инструментальном событии** `delegate_work_to_coworker`, а не на менеджере напрямую, поэтому адаптер следует этой ссылке. Без неё каждый агент выходит сиблингом каждого другого и структура делегирования теряется. + +## Пример + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # becomes agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +Передача видна в трассе: спан `analyst` закрывается, спан `writer` открывается, и оба находятся внутри одного спана `crew`. + +## Назовите ваши спаны + +`agent_id` происходит из `Agent(role=...)`, что делает его читаемым аспектом панели управления. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # one facet entry per run +``` + +`agent_id` — колонка низкой кардинальности. Роль, содержащая id запуска или отметку времени, деградирует её для каждого запроса, который кто-либо выполняет. Если роль выглядит как id, адаптер отказывает в её использовании и помещает реальное значение в поле полезной нагрузки вместо этого. + +## Управление сеансом + +Разрешается в этом порядке, первое совпадение побеждает: + +1. `instrument("crewai", session_id=...)` +2. Охватывающая область `failproofai_sdk.session()` +3. Сгенерированный `uuid4().hex`, один раз на команду или поток + +Оберните kickoff, чтобы управлять им за запуск: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## Параметры + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # pin every run to one session id +) +``` + +`session_id` — единственный параметр, который читает этот адаптер. Подсказки и завершения всегда записываются, усечены до бюджета полезной нагрузки. + +## Человек в цикле + +CrewAI имеет **две** поверхности человека в цикле, и обе записываются как одни и те же четыре события. + +`@human_feedback` на методе потока проходит через шину событий CrewAI: среда выполнения испускает событие перед блокировкой на человеке и другое после ответа. + +`Task(human_input=True)` не проходит. Она вызывает `input()` внутри собственного поставщика входных данных CrewAI и не испускает событие никакого рода, поэтому адаптер оборачивает этого поставщика напрямую — без этого вся ожидание человека было невидимым и учитывалось как активное время агента. + +В любом случае вы получаете: + +```text +human_wait prompt и его опции +agent_pause запускает таймер паузы +agent_resume останавливает его +human_input ответ с измеренным временем ожидания +``` + +`agent_pause` в `agent_resume` — единственная пара, которая питает время паузы. Без неё десятиминутное ожидание человека учитывается как десять минут активного времени агента. + + + CrewAI не устанавливает корреляционный id на события обратной связи от человека, поэтому адаптер сопоставляет их по имени потока и метода, переходя к наиболее недавно открытой паузе. Это корректно, потому что консольный запрос блокирует. Если вы создаёте конкурентного поставщика обратной связи, установите `request_id` на оба события. + + + + Поскольку путь `Task(human_input=True)` — это обёртка вокруг поставщика входных данных CrewAI, а не подписка на события, он восстанавливается на `uninstrument()` и повторно вызывает всё, что вызывает `input()`, включая `KeyboardInterrupt`, без изменений. + + +## Общие проблемы + + + + `role` содержит UUID, отметку времени или суффикс для каждого запуска. Используйте стабильную человеческую роль и поместите id для конкретного запуска в описание задачи вместо этого. + + + + Шина событий асинхронна, и `kickoff()` возвращает значение перед запуском последних обработчиков. Сначала осушите её: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + Это свойство CrewAI, а не SDK. + + + + `agent_end` принудительно закрывает открытые паузы, но не инструменты или модели, поэтому запуск, который умирает внутри вызова инструмента, оставляет этот спан открытым. Нормальное завершение закрывает всё, что ещё открыто, и помечает его как неполное. Только `SIGKILL` оставляет его зависшим, потому что ничего не может запуститься. + + + + Проверьте по порядку: `instrument()` запустился перед `kickoff()`; есть `with failproofai_sdk.session():` вокруг него; `crewai` версии 1.13 или новее; `FAILPROOFAI_SDK_STRICT=1` установлен, поэтому деградированный хук вызывает исключение вместо его подавления. + + + +## Далее + + + + Пары, ids, жизненный цикл сеанса и доставка. + + + Следите за причинно-следственной связью через сеанс, который вы только что захватили. + + + LangGraph, LlamaIndex, Pydantic AI и пользовательские агенты. + + \ No newline at end of file diff --git a/docs/ru/start/integrations/custom-agents.mdx b/docs/ru/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..17b107d24 --- /dev/null +++ b/docs/ru/start/integrations/custom-agents.mdx @@ -0,0 +1,737 @@ +--- +title: "Пользовательские агенты" +sidebarTitle: "Пользовательские агенты" +description: "Инструментируйте агента, который вы написали сами, или фреймворк без адаптера." +icon: "code" +--- + +Для агента, который вы написали сами, или фреймворка, для которого у Failproof AI нет адаптера. Инструментировать нечего — вы сами генерируете события. + +Это тот же API, который используют четыре адаптера фреймворков. Они — таблицы трансляции над ним. + +## Установка + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # один вызов инструмента +``` + +Читайте сверху вниз — и станет ясно, что это означает: + +| Оберните в | Чтобы сказать | +| --- | --- | +| `session()` | Эти события принадлежат одному запуску | +| `agent()` | Что-то выполняет работу — дайте ему имя, которое вы узнаете в списке | +| `tool_call()` | Это один инструмент и вот что он вернул | + +И что каждый из них фактически генерирует: + +| Область | Генерирует | Назначение | +| --- | --- | --- | +| `session()` | Ничего | Привязывает session id, группируя один запуск | +| `agent()` | `agent_start`, `agent_end` | Ограничивает единицу работы | +| `tool_call()` | `tool_use`, `tool_result` | Ограничивает один инструмент и его результат | + +Всё внутри может опустить `session_id` и `agent_id`. Области привязывают идентификацию на переменные контекста и каждый вызов события читает её обратно, поэтому вам никогда не нужно передавать id через функции. + +Все три работают с `async with` наравне с `with`. + +Вложенные агенты строят дерево. `parent_id` и глубина вычисляются из стека: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## Как закрывается область + +`agent()` обрабатывает исключения за вас: + +| Что произошло | События | Результат | +| --- | --- | --- | +| Ничего не возникло | `agent_end` | `success` | +| `Exception` | `error`, затем `agent_end` | `failed` | +| `KeyboardInterrupt`, `SystemExit` | `error`, затем `agent_end` | `failed` | +| `CancelledError`, `GeneratorExit` | только `agent_end` | `cancelled` | + +Ошибка генерируется перед `agent_end`, потому что панель управления закрывает span при `agent_end` и всё после этого не атрибутируется ничему. Отмена — не ошибка, поэтому отменённые запуски не загромождают поверхность ошибок. Исключение всегда переиспускается: область никогда его не подавляет. + +## Методы события + +Пятнадцать методов в шести семействах. Большинство идут парами — вы генерируете открывающее событие, затем закрывающее, и SDK измеряет промежуток между ними. + +| Семейство | Открывает | Закрывает | Самостоятельное | +| --- | --- | --- | --- | +| **Agents** | `agent_start` | `agent_end` | — | +| | `agent_pause` | `agent_resume` | — | +| **Models** | `model_request` | `model_response` | — | +| **Tools** | `tool_use` | `tool_result` | — | +| **Hooks** | `hook_triggered` | `hook_completed` | — | +| **Humans** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **Failures** | — | — | `error` | + + + Предпочитайте области — `agent()` и `tool_call()` — везде, где они подходят. Они гарантируют закрывающее событие даже когда тело выбрасывает исключение. Обращайтесь к этим методам напрямую, когда ваш управляющий поток не вложен, например вызов модели внутри вспомогательной функции. + + + +```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 Models +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 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 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 Failures +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **Два семейства human указывают в противоположных направлениях.** + + | Методы | Значение | + | --- | --- | + | `human_wait` / `human_input` | **Агент попросил человека** — ворота одобрения, уточняющий вопрос | + | `human_pause` / `human_interrupt` | **Человек действовал на агента** — кнопка остановки, пауза оператора | + + Ни один фреймворк не сигнализирует вторую пару, поэтому её всегда нужно генерировать вам. + + + + **Передавайте `request_id` когда вызовы модели выполняются одновременно.** Без него запросы и ответы сопряжаются в порядке поступления за агента — и одновременные вызовы неправильно сопрягаются, присоединяя каждый ответ к неправильному запросу. + + +## Пример + +Цикл вызовов инструментов против OpenAI API без фреймворка агента: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +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 + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="price report"): + for _ in range(4): # ограниченное количество; бесконечный цикл агента — его собственная ошибка + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +Это генерирует те же шесть типов событий, которые даст адаптер. Полная рабочая версия с определениями инструментов поставляется в репозитории SDK в `docs/manual/examples/`. + +## Потоки и async + +Переменные контекста автоматически распространяются в 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`, что — это скрытый отказ, который существует уровень идентификации чтобы предотвратить. + +## Инструментирование фреймворка без адаптера + +Каждый фреймворк агента даёт вам те же три точки. Отобразите их — и у вас есть полная трассировка. Четыре поставляемых адаптера делают ровно это. + +| Точка | Что вы пишете | Что попадает | +| --- | --- | --- | +| Запуск | `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 + 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(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **Есть граница узла, шага или middleware, достойная внимания?** Оберните её в пару hook — `hook_triggered` / `hook_completed` — а не вложенный `agent()`. `agent_id` — низко-кардинальный фасет, и одна запись на узел его захламляет. Span-ы hook отображаются так же и дают вам задержку за узел. + + + + **Ручное и автоматическое взаимодействуют.** Адаптер, работающий внутри ручной области, присоединяется к этой session и становится родителем этого агента, поэтому вы получаете одно дерево вместо двух — это полезно когда вы инструментируете один фреймворк сами наряду с поддерживаемым. + + + + Две причины, и три точки выше — ответ на обе: + + - `autogen-core` не обслуживается с сентября 2025. + - AG2 не раскрывает точку регистрации масштаба процесса, эквивалентную хукам других фреймворков, поэтому инструментирование означает обёртывание каждого агента на каждом месте конструирования. + + Ручное отображение точек записывает те же события с той же точностью, что и поставляемый адаптер. + + +## Глубже + +Как запись фактически работает. Ничего из этого не требуется для начала. + + + + + +Каждая запись имеет одну форму: span открывается, работа вложена внутри, и каждому открывающему событию соответствует закрывающее. + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + C --> E(["agent_end"]) +``` + +**Пара** — это единица. Каждое закрывающее событие несёт длительность, которую SDK измеряет от открывающего. + +Ниже один реальный запуск на фреймворк — захвачен из примеров, которые поставляются с SDK, имя модели нормализовано. Обратите внимание, сколько возвращается из одного вызова. + + + + ```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 out-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 14 +5.721s agent_end LangGraph · success + ``` + + Узлы становятся парами hook, поэтому вы получаете задержку за узел без того, чтобы они загромождали список агентов. + + + + ```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 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 out-tok + 9 +5.727s agent_end analyst · success + 10 +5.739s agent_end crew · success + ``` + + Каждый `role` агента становится имя span-а, поэтому задержка и трата токенов разбиваются по role. + + + + ```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 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 + ... second iteration + 26 +7.038s agent_end Agent · success + ``` + + Цикл агента сам видим, не только его вызовы модели. + + + + ```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 + 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 + 8 +8.119s agent_end agent · success + ``` + + Нет пар hook: Pydantic AI не имеет границы узла или шага для ограничения. + + + + ```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 out-tok + 6 +0.000s agent_end main · success + ``` + + Вы генерируете их сами. Те же типы событий, та же точность — это стоит вам мест вызовов. + + + + + + + +**Нет события завершения session.** Session — это не то, что вы закрываете — это группа событий, разделяющих `session_id`. + +Статус выводится из формы трассировки: + +| Статус | Когда | +| --- | --- | +| `ongoing` | По крайней мере один span всё ещё открыт | +| `paused` | `agent_pause` не имеет соответствующей `agent_resume` | +| `error` | Ничего не открыто и по крайней мере одно событие не прошло | +| `done` | Ничего не открыто и ничего не провалилось | + +Поэтому session заканчивается когда каждая пара закрыта. Адаптеры генерируют `agent_end` для вас, и при завершении они закрывают всё ещё открытое и отмечают его неполным — упавший запуск урегулируется как `done` с видимым пробелом вместо вечного зависания. + + + Вот почему session может охватывать два вызова. `interrupt()` LangGraph пауза запуска, root span намеренно остаётся открыт, и возобновляющий вызов его закрывает. Оба вызова — одна session. + + + + + + +`session_id` и `agent_id` опциональны для каждого метода события. Опущены — они разрешаются из вмещающей области: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") +``` + +Их явная передача всё ещё работает и имеет приоритет. Без привязанного и без переданного вызов выбросит `TypeError` с названием исправления вместо того чтобы генерировать событие без session, которое ingest пропустит при ответе `200`. + +Области привязывают идентификацию на переменные контекста. Они распространяются в 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 запуска фреймворка, вот почему пары выживают переходы через потоки | +| **Event id** | **Cloud at ingest** | SDK не генерирует | +| **`dedup_key`** | **Cloud at ingest** | Хеш org, session, timestamp, type и payload. Это реальная идентификация — делает повторённую партию коллапсом вместо дублирования | + +#### Как адаптеры разрешают `session_id` + +Первое совпадение выигрывает: + +1. Явная опция `session_id` +2. Per-call метаданные +3. Вмещающая область `session()` +4. Метаданные фреймворка +5. Собственный run id фреймворка + +Она никогда не синтезируется пока одна из них существует — синтезированный id расколол бы один запуск на несколько session. + +#### Держите `agent_id` низко-кардинальным + +Это первичный фасет на каждой поверхности панели управления и `LowCardinality(String)` колонка. Per-run значение деградирует колонку и заполняет выпадающий фильтр одной записью за запуск. + +Адаптеры защищают эту колонку для вас: + +| Фреймворк передаёт | Записано как | Почему | +| --- | --- | --- | +| `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`, где остаётся queryable без того чтобы быть фасетом. + + + **Эта защита только трогает ярлыки, которые **фреймворк** выбрал.** `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` | +| Hooks | `hook_triggered`, `hook_completed` | +| Humans | `human_wait`, `human_input`, `human_pause`, `human_interrupt` | +| Failures | `error` | + +Какой фреймворк что записывает, измеренный от запусков выше: + +| События | 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 | + +Тире означает фреймворк не имеет такой концепции. `human_pause` и `human_interrupt` описывают **человека**, действующего на агента, что ни один фреймворк не сигнализирует — генерируйте их сами. + + + + + +Событие никогда не приходит одно. Одно открывает 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` | ответ и как долго человек занимал | + + + Открывающее событие без закрывающего — это 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 для чего-либо ещё. +- Ключи корреляции ограничены видом и session, поэтому вызов инструмента и hook могут безопасно разделить id, и две одновременные session могут переиспользовать те же id без столкновения. Они не ограничены агентом: пара открытая под одним агентом и закрытая под другим всё ещё коррелирует, это обычный случай в multi-agent фреймворках. +- `request_id` сопрягает `model_request` с `model_response`. Без него события модели сопрягаются в порядке за агента, поэтому одновременные вызовы неправильно сопрягаются. +- Пара разделённая через процессы всё ещё коррелирует downstream, но SDK не может вычислить её in-process длительность. +- Ожидающая карта держит максимум 10,000 стартов и вытеснит самую старую запись когда полна. + + + + + +Установка `failproofai-sdk` устанавливает всё, все четыре адаптера включены. Extras вытягивают **фреймворк**, а не адаптер. + +```python +import failproofai_sdk # загружает ничего вне стандартной библиотеки +failproofai_sdk.instrument() # импортирует только адаптеры, которые вам фактически нужны +``` + +`import failproofai_sdk` контрактно ноль-зависимости, принудительно тестом который устанавливает построенное колесо с `--no-deps` и другое которое доказывает что ни один фреймворк не достигает `sys.modules`. + + + Нет атрибута `failproofai_sdk.crewai`. Адаптеры намеренно не раскрыты на пакете верхнего уровня: трогание одного импортировало бы фреймворк как побочный эффект доступа атрибута, ломая ноль-зависимость обещание. Используйте `instrument()`. + + +```python +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` | + +Auto-detection читает `sys.modules`, не список установленных пакетов, поэтому фреймворк, который вы установили но никогда не импортировали, не инструментируется и никогда не импортируется от вашего имени. Чтобы увидеть что подключено: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +active() # ('langchain',) +``` + + + **`instrument("crewai")` на машине без CrewAI не выбросит.** Это логирует предупреждение и возвращает `()`, поэтому один отсутствующий фреймворк никогда не возьмёт процесс который также инструментирует других. + + Предупреждение несёт базовую `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. + + + + **`instrument()` должен прийти *после* вашего импорта фреймворка.** Auto-detection читает `sys.modules`, поэтому чистый вызов выше импорта находит ничего, устанавливает ничего, и возвращает `()`. + + + +```python Wrong +import failproofai_sdk +failproofai_sdk.instrument() # sys.modules ещё не имеет langchain -> () + +import langchain # слишком поздно, ничего не подключено +``` + +```python Right +import langchain # импортируйте фреймворк первым +import failproofai_sdk + +failproofai_sdk.instrument() # находит его -> ('langchain',) +``` + +```python Right, order-proof +import failproofai_sdk + +# Называние этого импортирует адаптер по запросу, поэтому это работает отовсюду. +failproofai_sdk.instrument("langchain") +``` + + +Получите это неправильно и процесс работает с импортированным 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"] +``` + +| Этап | Работа | Работает в | +| --- | --- | --- | +| Adapter | Переводит обратный вызов фреймворка в один из 15 типов событий | Ваш процесс | +| Writer | Очереди, батчи, писать JSONL атомарно | Ваш процесс, фоновый поток | +| Spool | Прочная передача, выживает выход вашего процесса | Локальный диск | +| Daemon | Следит за spool, доставляет батчи, удаляет то что он доставил | Ваша машина | +| Ingest | Присваивает row id и dedup key, рекламирует queryable колонки | Cloud | + +Spool — это то что делает это безопасным: ваш агент никогда не блокируется на сети, и Cloud outage означает растущую директорию вместо потерянных событий. + +Каждый 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 событиями; сверх этого она отбрасывает самое старое и логирует. + + + **`collector.redact` не применяется к вашим SDK событиям.** Он их никогда не видит. + + +Daemon **доставляет** ваши батчи. Он их не открывает и не переписывает. + +| События | Написано | Отредактировано `collector.redact`? | +| --- | --- | --- | +| CLI session транскрипты | Daemon | Yes | +| Hook activity | Daemon | Yes | +| **Всё что SDK генерирует** | **Ваш процесс** | **No** | + +Редакция работает где daemon **пишет** его собственные события — не где батчи **доставляются**. Поэтому prompt или инструмент argument держащий API key всё ещё держит его по прибытии. + +Это намеренно. Это ваши собственные вызовы инструментирования, и переписывание их в пути бы означало события которые вы получаете не события которые вы генерировали. + + + **Вы контролируете payloads на источнике в двух местах:** + + - Выключите захват контента на адаптере. **Имя опции отличается и один адаптер не имеет** — это не один универсальный переключатель: + - LangChain / LangGraph, Pydantic AI — `capture_content=False` + - LlamaIndex — `capture_messages=False` + - CrewAI — **no content switch at all**; `session_id` единственная опция, которую он читает, поэтому prompts и completions всегда записываются. + + `instrument()` отбрасывает опции адаптер не читает, поэтому передача неправильного имени выбросит ничего и изменит ничего. + - Не передавайте secret в `input=` в первую очередь. + + `collector.redact` не является заменой для обоих. + + + + **Пустая spool директория — здоровое состояние.** Не используйте её для проверки доставки. + + +Daemon удаляет каждый батч в миллисекундах доставки, поэтому `ls` гонится по collector и показывает fraction того что вы генерировали — неразличимый от SDK который ничего не записал. + +Чтобы подтвердить события действительно приземлились, проверьте панель управления. Чтобы看着 spool заполняться, сначала остановите daemon. + + + + + +Каждый обратный вызов работает внутри обёртки чья единственная работа переиспустить, поэтому ваш вызов сидит в ровно одном `try` и всё что SDK делает происходит вне его. + +| Что происходит | Результат | +| --- | --- | +| Hook выбросит | Логировано один раз с его traceback. Ваш вызов не затронут | +| Тот же hook выбросит трижды | Тот хук отключен для остатка процесса, с одной линией ошибки | +| `FAILPROOFAI_SDK_STRICT=1` установлен | Исключение переиспущено вместо этого | +| Версия фреймворка вне протестированного диапазона | Предупреждает один раз, инструментирует всё равно | +| Один capability отсутствует | Тот хук отключен, никогда весь адаптер | + +Default правильный в production и неправильный при debugging, потому что может только когда-либо доказать that it did not crash. Установите `FAILPROOFAI_SDK_STRICT=1` чтобы сделать проглоченную ошибку громкой. + + + + + +## Частые проблемы + + + + Открывающее событие не имеет закрывающего: `model_request` без `model_response` или `tool_use` без `tool_result`. Используйте области, которые гарантируют пару даже когда тело выбросит. Если вы вызываете методы события напрямую, используйте `try` и `finally`. + + + + Это измеряется от соответствующего открывающего события, поэтому отклоняется на `tool_result`, `hook_completed`, `agent_resume` и `human_input`. Принято на `model_response`, потому что только вы знаете реальную задержку провайдера, и это должно быть целое число. + + + + Поток никогда не наследовал контекст. Оберните callable в `failproofai_sdk.propagate()`. См. [Потоки и async](#threads-and-async). + + + + Дополнительные поля слияны последние, поэтому одно названное как реальное поле такое как `model` или `outcome` переписало бы его и изменило сохранённую колонку. Пространство имён ваши; адаптеры используют префикс `fw_`. + + + + `agent_id` — низко-кардинальный фасет и вы положили в него run id. Используйте role или имя узла и положите реальный id в поле payload. + + + +## Дальше + + + + Пары, id, жизненный цикл session и доставка. + + + Следите за причинностью через session которую вы только что захватили. + + + LangGraph, CrewAI, LlamaIndex и Pydantic AI. + + \ No newline at end of file diff --git a/docs/ru/start/integrations/langchain.mdx b/docs/ru/start/integrations/langchain.mdx new file mode 100644 index 000000000..0e465d9c9 --- /dev/null +++ b/docs/ru/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain и LangGraph" +sidebarTitle: "LangChain и LangGraph" +description: "Инструментируйте графы, узлы, инструменты, ретриверы и вызовы моделей одним вызовом." +icon: "/images/frameworks/langchain.svg" +--- + +Один адаптер подходит для обоих. LangGraph работает на менеджере обратных вызовов `langchain-core`, поэтому инструментирование одного инструментирует другое. + +## Установка + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Для LangChain без LangGraph используйте `failproofai-sdk[langchain]`. + +Поддерживается: `langchain-core` 1.4.7 до 2.0, `langgraph` 1.2 до 2.0. За пределами этого диапазона адаптер всё ещё устанавливается и выдаёт предупреждение один раз. + +## Инструментирование + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` регистрирует трассировщик через `langchain_core.tracers.context.register_configure_hook`. LangChain внедряет его в каждый менеджер обратных вызовов, который он создаёт, поэтому графы, инструменты и модели захватываются без изменения точки вызова — включая те, которые находятся внутри библиотек, которые вы не писали. + +## Что записывается + +| LangChain или LangGraph | Событие Failproof | +| --- | --- | +| Корневой запуск | `agent_start`, `agent_end` | +| Узел LangGraph | `hook_triggered`, `hook_completed` | +| Скомпилированный подграф | Вложенные `agent_start`, `agent_end` | +| Запуск инструмента | `tool_use`, `tool_result` | +| Запуск ретривера | `tool_use`, `tool_result`, вывод суммирован | +| Запуск модели чата или LLM | `model_request`, `model_response`, с использованием токенов | +| Потоковые токены | Встроены в ответ как количество фрагментов и время до первого токена. Подсчёт токенов требует `ChatOpenAI(stream_usage=True)` — см. ниже | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, коррелирует по `Interrupt.id` — включая случаи, когда возобновление происходит в другом процессе против того же контрольного фреймворка | +| Необработанное исключение | `error`, затем `agent_end` с результатом `failed` | + +**Узел становится хуком, а не вложенным агентом.** `agent_id` является основным аспектом на каждой поверхности панели инструментов — повышение `retrieve`, `grade_documents` и `should_continue` до агентов было бы перегруженным и помечало бы сеанс по тому узлу, который произошёл первым. + +Диапазоны хуков отображаются так же и по-прежнему дают вам вид задержки для каждого узла. + + + **Называйте ваши узлы как угодно.** Запуск узла идентифицируется по его *форме* — нелистовой запуск, несущий собственный шаг LangGraph — никогда по его имени. + + +| Вы пишете | Что записывается | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | Инструмент | +| `add_node("ChatOpenAI", ...)` | Вызов модели | + +Назвать узел в честь того, что он запускает, раньше заставляло события этого объекта исчезнуть. Теперь это больше не происходит. + +### Потоковая передача + +`.stream()` и `.astream()` не генерируют события для каждого токена. Они встроены в завершающий `model_response`: + +| Поле | Содержит | +| --- | --- | +| `fw_chunks` | Сколько фрагментов пришло | +| `fw_ttft_ms` | Время до первого токена | + +### Подсчёт токенов на потоковом ответе + +Отдельный вопрос и легко упустить: OpenAI отправляет использование на потоковом ответе **только при запросе**. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # без этого нет токенов +``` + +Адаптер записывает то, что фреймворк ему передал. Без этого флага нечего записывать, и `model_response` приходит без подсчёта токенов. + +## Пример + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Возвращает цену единицы товара в USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Возвращает количество единиц товара в наличии.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## Назовите ваши диапазоны + +По умолчанию корневой диапазон принимает имя самого графа. Оберните его, чтобы получить выбранную вами метку: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +Для многоагентных настроек вложите области. Каждый рабочий становится дочерним диапазоном с `parent_id`: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +Держите `agent_id` низкой мощности. Используйте роль или имя узла, никогда UUID или строку для каждого запуска. + +## Контролируйте сеанс + +ID сеанса разрешается в этом порядке, первое совпадение побеждает: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. Охватывающая область `failproofai_sdk.session()` +4. `metadata["session_id"]`, `metadata["conversation_id"]` или `metadata["thread_id"]` +5. ID корневого запуска + +Он никогда не генерируется с нуля, потому что синтезированный ID разбивает один запуск на несколько сеансов. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## Опции + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # привязать каждый запуск к одному ID сеанса + include_chains=set(), # список разрешённых промежуточных цепочек как пары хуков + capture_content=True, # False исключает подсказки и дополнения из полезных нагрузок + graph_callbacks=True, # первоклассный interrupt и resume, требует langgraph 1.2+ +) +``` + +Установите `capture_content=False` для регулируемых данных. Структура, синхронизация, подсчёт токенов, имена инструментов и результаты по-прежнему записываются; тела сообщений нет. + +`include_chains` применяется только к **вложенным** запускам. Запускаемый, который вы вызываете на верхнем уровне, является корнем сеанса, поэтому он становится диапазоном агента, а не парой хуков, и название его здесь не имеет эффекта. + +## Человек в цикле + +`interrupt()` производит четыре события, и ни одна пара не является избыточной: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +`human_wait` в `human_input` содержит подсказку и ответ (оба исключены под `capture_content=False`, наряду с источниками документов ретривера — количество документов сохраняется). `agent_pause` в `agent_resume` — единственная пара, которая подаёт время паузы, поэтому без неё десятиминутное ожидание человека будет учтено как активное время агента. Корневой диапазон остаётся открытым на протяжении разрыва, удерживая оба вызова в одном сеансе. + +## Частые проблемы + + + + `create_react_agent` распространяет исключение. Чтобы позволить модели увидеть отказ и продолжить, постройте узел инструмента явно: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + Отказ записывается как `tool_result` с ошибкой в любом случае. Это только решает, выживает ли запуск после этого. + + + + Прямой `llm.invoke()` вне любого графа не имеет родительского запуска, поэтому он открывает корневой диапазон и генерирует внутри него пару моделей. Панель инструментов размещает листья открытому агенту, поэтому диапазон намеренный. Назовите его: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + Вы передали обработчик Failproof в `config={"callbacks": [...]}`, а также вызвали `instrument()`. Удалите его. Хук конфигурации уже охватывает каждый менеджер обратных вызовов в процессе. + + + + Это неправда. LangGraph вызывает `GraphInterrupt` по тому же пути, что и реальное исключение, поэтому каждая пауза достигает трассировщика как обратный вызов ошибки. Любой подкласс `GraphBubbleUp` вместо этого рассматривается как поток управления, поэтому одобрение не окрашивает красную ошибку. + + + + Проверьте в этом порядке: `instrument()` запустился перед выполнением графа; вокруг вызова стоит `with failproofai_sdk.session():`; `FAILPROOFAI_SDK_STRICT=1` установлен, поэтому деградированный хук вызывает исключение вместо поглощения. + + + +## Далее + + + + Пары, ID, жизненный цикл сеанса и доставка. + + + Проследите причинность через захваченный сеанс. + + + CrewAI, LlamaIndex, Pydantic AI и пользовательские агенты. + + \ No newline at end of file diff --git a/docs/ru/start/integrations/llamaindex.mdx b/docs/ru/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..d2283c984 --- /dev/null +++ b/docs/ru/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "Инструментируйте workflows, steps, function agents и retrievers." +icon: "/images/frameworks/llamaindex.svg" +--- + +## Установка + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +Поддерживается: `llama-index-core` версии 0.14.23 до 0.15. 0.14.23 — это релиз, где поток workflow начал переносить типизированные события агента, которые читает этот адаптер. Ниже него отсутствуют и имена моделей, и структура агента. + +## Инструментирование + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +API агента LlamaIndex является асинхронным. Каждая область работает под `async with`, а также под `with` и производит идентичные события. + +`instrument()` присоединяет обработчик событий и обработчик spans к глобальному диспетчеру LlamaIndex. Вместе они делают цикл агента видимым, а не только его вызовы модели. + + + Без одного дополнительного аргумента на вашей LLM каждый подсчет токенов в вашем трассировании будет null. См. [Подсчеты токенов](#подсчеты-токенов) ниже. + + +## Подсчеты токенов + +`FunctionAgent` вызывает `astream_chat`, и `llama-index-llms-openai` не отправляет `stream_options={"include_usage": True}` при потоковой передаче. Поставщик поэтому никогда не отправляет chunk использования, и нечего читать никакому инструментированию. + +Это поведение вышестоящего LlamaIndex. Отключите на вашей LLM: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +Измерено на одном прогоне и модели: + +| | Входные токены | Выходные токены | +| --- | --- | --- | +| Без | `null` | `null` | +| С | 148 | 17 | + +Вызовы без потоковой передачи (`llm.chat`, `llm.achat`) сообщают об использовании без конфигурации. Только путь потоковой передачи, который является путем агента по умолчанию, требует этого. + +## Что записывается + +| LlamaIndex | Failproof событие | +| --- | --- | +| `Workflow.run` корневой span | Session, `agent_start`, `agent_end` | +| Вложенный `Workflow.run` span | Вложенные `agent_start`, `agent_end` | +| Workflow step span | `hook_triggered`, `hook_completed` | +| LLM chat начало и конец | `model_request`, `model_response` | +| `FunctionTool.call` span | `tool_use`, `tool_result` | +| Retrieval начало и конец | `tool_use`, `tool_result`, выход суммирован | +| Embeddings | Ничего, если только `embeddings=True` | +| Инструмент, ожидающий человека | `human_wait`, `agent_pause`, затем `agent_resume`, `human_input` | +| `AgentWorkflow` handoff | Вложенные `agent_start`, `agent_end` на агента, относящиеся к workflow | +| Exception | `error`, затем `agent_end` с исходом `failed` и `agent_end.summary` его названием | +| `handler.cancel_run()` | `agent_end` с исходом `cancelled` и без `error` — кнопка остановки — это не сбой | + +`agent_id` — это `FunctionAgent.name`, когда вы его установили, и имя класса workflow в противном случае. Под `AgentWorkflow` каждый агент, который берет ход, получает свой собственный вложенный span под workflow, поэтому handoff читается как два агента, а не один. + +Выход retrieval суммируется, а не выводится. Retriever возвращает документы, и их сохранение в payload поместит ваш корпус в хранилище событий один раз за запрос. Вместо этого сохраняются количество, диапазон оценок и усеченные фрагменты. + +## Пример + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +Цикл агента появляется в трассировании как пары hook: `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool` и `aggregate_tool_results`. Это собственный цикл framework, поэтому это hooks, а не agents, что делает `agent_id` значимым. + +## Назовите ваши spans + +`agent_id` — это `FunctionAgent.name`, когда вы его установили, и имя класса workflow в противном случае. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +В `AgentWorkflow` это имя также записывается для каждого handoff: + +```text +AgentWorkflow родительский span +├─ city_analyst ход 1 +├─ cost_analyst ход 2 +└─ city_analyst ход 3 — новый ход, не переоткрытый +``` + +Поэтому `agent_id` говорит вам **какой агент** выполнил работу, а `parent_id` говорит вам **к какому workflow** он принадлежал. Агент, который позже вернул управление, открывает второй ход, а не переоткрывает свой первый. + +Оберните run, чтобы переопределить его или сгруппировать несколько агентов под одним родителем: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +Держите `agent_id` с низкой кардинальностью. Это основной аспект на каждой поверхности приборной панели, поэтому используйте имя роли или workflow, никогда UUID или строку за запуск. + +## Контроль session + +Этот адаптер **не принимает опцию `session_id`**. Session поступает из окружающей области или в противном случае генерируется `uuid4().hex` на запуск workflow: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## Опции + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True записывает вызовы embedding как пары инструментов + steps=True, # False отбрасывает пары hook workflow-step + capture_messages=True, # False отбрасывает КАЖДЫЙ payload: prompts, completions, + # аргументы и выход инструмента, ввод и вывод step, + # запросы retrieval, цель и финальный ответ + capture_limit=8192, # символы сохраняются на захваченное значение + stale_after=600.0, # секунды до принудительного закрытия заброшенного LEAF + reaper_interval=30.0, # как часто reaper выполняет sweep; 0 отключает его +) +``` + +| Опция | Почему вы бы ее изменили | +| --- | --- | +| `embeddings` | Включите только при отладке latency embedding или стоимости. Массовое создание индекса — это тысячи вызовов и похоронит временную шкалу. | +| `steps` | Отключите, если вам нужны только события модели и инструмента и вы находите цикл агента шумным. | +| `capture_messages` | Отключите для регулируемых данных. Каждый payload перестает записываться — prompts, выход модели, аргументы и возвращаемые значения инструмента, ввод и вывод workflow-step, запросы retrieval, цель агента и его финальный ответ. Структура, timings, токены и outcomes все еще записываются. | +| `capture_limit` | Символы сохраняются на захваченное значение перед усечением. Увеличьте его, когда RAG prompt или извлеченный контекст приходят обрезанными. | +| `stale_after` | Секунды до принудительного закрытия заброшенного **leaf** — потока ответа, который никто не потреблял, span модели или инструмента, чье закрытие никогда не пришло — чтобы session установилась вместо чтения `ongoing` вечно. Это **не** закрывает заброшенный run себя: workflow, чья задача отменена без exit, видимого диспетчером, держит свой `agent_start` открытым до `uninstrument()`. | +| `reaper_interval` | Частота sweep. Установите `0`, чтобы полностью отключить reaper. | + +## Human in the loop + +Захватывается, когда ожидание происходит внутри инструмента: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +`ctx.wait_for_event` в простом workflow step не захватывается. Runtime ловит drop до того, как он достигнет диспетчера, поэтому step выходит и переустанавливается позже без сигнала на ключ pause. Паттерн FunctionAgent, который документирует LlamaIndex, ждет внутри инструмента и захватывается полностью. + +## Частые проблемы + + + + Добавьте `additional_kwargs={"stream_options": {"include_usage": True}}` к вашей LLM. См. [Подсчеты токенов](#подсчеты-токенов). + + + + LlamaIndex не имеет стандартного поля usage. Адаптер пробует несколько известных форм, и интеграция, которая называет свои счетчики чем-то новым, не будет соответствовать ни одной из них. + + Сырой dict всегда отправляется, поэтому проверьте `usage` в payload, чтобы увидеть, как ваш поставщик их назвал. + + Заполненное `usage` рядом с пустыми столбцами токенов преднамеренно — это лучше, чем уверенное неправильное число. + + + + Это цикл FunctionAgent, один набор за итерацию. Фильтруйте по имени hook на приборной панели. Эти timings step обычно являются причиной использовать этот адаптер, а не только адаптер модели. + + + + Проверьте по порядку: `instrument()` запустился перед run; есть `async with failproofai_sdk.session():` вокруг `await`; `llama-index-core` версии 0.14.23 или новее; `FAILPROOFAI_SDK_STRICT=1` установлено, поэтому деградированный hook вызывает исключение вместо проглатывания. + + + +## Далее + + + + Пары, ids, session lifecycle и delivery. + + + Следите за причинностью через session, который вы только что захватили. + + + LangGraph, CrewAI, Pydantic AI и custom agents. + + \ No newline at end of file diff --git a/docs/ru/start/integrations/pydantic-ai.mdx b/docs/ru/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..ed33d2b76 --- /dev/null +++ b/docs/ru/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "Инструментируйте типизированные агенты, инструменты, вызовы моделей и повторные попытки." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## Установка + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +Поддерживаются версии `pydantic-ai-slim` с 2.0 по 3.0. В версии 2.0 был удалён параметр `Agent(instrument=...)` и введён протокол возможностей, на котором строится этот адаптер, поэтому версия 1.x не может быть инструментирована таким образом. + +## Инструментирование + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # перед созданием любого Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + Функция `instrument()` должна быть вызвана до создания `Agent`. Возможность добавляется при конструировании, поэтому агент, созданный ранее, не будет иметь её и ничего не будет записывать, без ошибок, так как ничего не пошло не так. Это наиболее частая причина пустой трассировки при использовании этого адаптера. + + +Чаще всего проблема возникает с агентами на уровне модуля: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # создан при импорте + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # запустите это ПЕРВЫМ +import agents # теперь агент получит возможность +``` + +Убедитесь, что это сработало: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI объединяет переданный вами список в единственный `root_capability`, поэтому нет атрибута `agent.capabilities` для чтения. + +Агенты, созданные во время инструментирования, сохраняют возможность, поэтому вы можете вызвать `uninstrument()` и повторно инструментировать без пересоздания. + +## Что записывается + +| Pydantic AI | Событие failproofai | +| --- | --- | +| Запуск агента | `agent_start`, `agent_end` | +| Запрос модели | `model_request`, `model_response`, с использованием токенов | +| Вызов инструмента | `tool_use`, `tool_result`, с аргументами, отправленными моделью | +| `ModelRetry` из инструмента | `tool_result` с ошибкой | +| Необработанное исключение | `error`, затем `agent_end` с результатом `failed` | + +Здесь нет пары hook и нет пары human-in-the-loop. Pydantic AI не имеет границы узла или шага для заключения и не имеет встроенной паузы для человека, поэтому нечего преобразовывать. Если вы создадите что-либо из этого, генерируйте события самостоятельно — см. [Пользовательские агенты](/ru/reference/custom-agents). + +Значение `output_type` никак не влияет на трассировку. Типизированный запуск и запуск со строкой создают одинаковые события. + +## Пример + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +В трассировке `restock_eta` отображается как `tool_result` с ошибкой, за которым следует другой вызов модели, где агент её обходит, и запуск всё ещё заканчивается `success`. Оба факта фиксируются. + +## Ошибки, повторные попытки и управление потоком + +Pydantic AI вызывает исключения для трёх разных вещей, и адаптер их разделяет: + +| Исключение | Трактуется как | Результат | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | Реальный отказ инструмента | `tool_result` с ошибкой; запуск всё ещё может закончиться `success` | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | Управление потоком | Не ошибка; запуск управляется | +| Что-либо другое | Отказ | `error`, затем `agent_end` с результатом `failed` | + +`ModelRetry` намеренно находится в первой группе. Это означает, что попытка действительно не удалась и модель была попрошена попробовать снова, что именно то, для чего предназначено поле ошибки инструмента. Классификация её как управления потоком скрыла бы реальные отказы инструментов за зелёным запуском. + +## Назовите ваши span-ы + +Собственный span запуска Pydantic AI называется `agent`. Заключите вызов в контекст, чтобы дать ему выбранный вами ярлык: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +Span фреймворка затем вложен в `inventory`, и именно там висят события модели и инструмента. + +Держите `agent_id` с низкой кардинальностью. Это первичный аспект на каждой поверхности панели, поэтому используйте имя роли, никогда UUID или строку для каждого запуска. + +## Управление сеансом + +Разрешается в этом порядке, первое совпадение побеждает: + +1. `instrument("pydantic_ai", session_id=...)` +2. Содержащий `failproofai_sdk.session()` scope +3. `conversation_id` запуска, затем его `run_id` +4. Сгенерированный `uuid4().hex` + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## Опции + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # закрепите каждый запуск на одном session id + capture_content=True, # False удаляет подсказки и завершения из полезной нагрузки +) +``` + +## Распространённые проблемы + + + + `Agent` был создан до запуска `instrument()`. См. предупреждение выше и проверьте `agent.root_capability.capabilities`. + + + + Простой `raise` распространяется; это дизайн Pydantic AI. Чтобы позволить модели его обойти, вызовите `ModelRetry` с сообщением, на которое она может действовать. Отказ записывается в любом случае. + + + + Этот дочерний элемент — собственный span запуска Pydantic AI, и именно там висят события модели и инструмента. Отбросьте собственный scope, если хотите один span, ценой пользовательского имени. + + + + Граф асинхронного стека Pydantic AI длиннее предела поля полезной нагрузки, и последняя строка трассировки — это само исключение. Это поле обрезается спереди, а не сзади, поэтому нужная вам строка выживает. + + + +## Далее + + + + Пары, идентификаторы, жизненный цикл сеанса и доставка. + + + Следите за причинностью через только что захватанный сеанс. + + + LangGraph, CrewAI, LlamaIndex и пользовательские агенты. + + \ No newline at end of file diff --git a/docs/ru/start/quickstart.mdx b/docs/ru/start/quickstart.mdx index f063cd84e..ce3425de2 100644 --- a/docs/ru/start/quickstart.mdx +++ b/docs/ru/start/quickstart.mdx @@ -1,18 +1,17 @@ --- ---- 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 поддерживаемых [хранилищ](/ru/reference/harnesses) — кодирующий CLI или шлюз вроде Hermes или OpenClaw — следуйте приведённым ниже шагам; вам нужен Node.js 20.9 или позже. Если ваш агент не имеет хранилища, инструментируйте его с помощью [Python SDK](/ru/reference/custom-agents) для трассировки и аудитов, затем вернитесь к [Запуск первой проверки ошибок](/ru/start/first-audit); принудительное применение на этом пути требует перехватчика в вашей среде выполнения. - + - + ```bash npx skills add FailproofAI/skills ``` @@ -22,14 +21,14 @@ 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) и создайте аккаунт или войдите со своей рабочей почтой. +1. Откройте [панель управления Failproof AI](https://app.befailproof.ai) и создайте аккаунт или войдите с помощью рабочей электронной почты. 2. Перейдите в **Administration → Keys** и создайте ключ с правами `events:add` и `policies:pull`. 3. Скопируйте одноразовый секрет и сохраните его на целевой машине: @@ -46,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Транскрипты сеансов отправляются по умолчанию. Добавьте `--no-transcripts` для отправки активности хуков и решений политик без содержимого транскриптов. + Расшифровки сеансов отправляются по умолчанию. Добавьте `--no-transcripts` для отправки активности перехватчиков и решений по политикам без содержимого расшифровок. - Если на этой машине уже есть история агента, просмотрите и импортируйте последние семь дней, затем дождитесь завершения доставки. Пропустите этот шаг на новой машине. + Если на этой машине уже есть история агента, выполните предпросмотр и импортируйте последние семь дней, затем дождитесь завершения доставки. Пропустите этот шаг на новой машине. ```bash failproofai backfill --since 7d --dry-run @@ -58,28 +57,28 @@ export FAILPROOFAI_KEY="" Откройте **Sessions** в Failproof AI и выберите импортированный сеанс. - - Это подключит Failproof AI к вашей оболочке и установит 40 встроенных политик. Используйте их для просмотра локальных решений политик и тестирования принудительного применения до того, как Failproof AI проведёт аудит ваших сеансов и напишет политики для ваших агентов. + + Это подключит Failproof AI к вашему хранилищу и установит 40 встроенных политик. Используйте их для просмотра локальных решений по политикам и попробуйте принудительное применение перед тем, как Failproof AI проведёт аудит ваших сеансов и напишет политики для ваших агентов. - Позвольте установщику обнаружить вашу оболочку или укажите её явно. Каждая из 12 является допустимым значением `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Позвольте установщику определить ваше хранилище или укажите его явно. Каждое из 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 + failproofai policies --install --cli claude --scope user # a coding CLI + failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - Блокирование вызова инструмента перед его запуском проверяется на всех 12. Врата конца хода проверяются на 8 — смотрите [возможность принудительного применения](/ru/reference/harnesses#enforcement-capability) для матрицы по оболочкам. + Блокировка вызова инструмента перед его выполнением проверяется на всех 12 хранилищах. Завершающие вентили проверяются на 8 — см. [возможности принудительного применения](/ru/reference/harnesses#enforcement-capability) для матрицы по хранилищам. - Следуйте разделу [Запустите первую проверку сбоев](/ru/start/first-audit). Используйте конкретную цель, такую как "найти сеансы, где агент повторил неудачный вызов инструмента без изменения своего подхода." + Следуйте инструкциям [Запуск первой проверки ошибок](/ru/start/first-audit). Используйте конкретную цель, такую как поиск сеансов, где агент повторил неудачный инструмент без изменения подхода. - - Следуйте разделу [Предотвратите первый сбой с помощью политики](/ru/start/first-policy). Начните в режиме наблюдения, проверьте совпадения, затем примените проверенную версию. + + Следуйте инструкциям [Предотвратить первую ошибку с помощью политики](/ru/start/first-policy). Начните с режима наблюдения, проверьте совпадения, затем примените просмотренную версию. - Запустите `failproofai config --status`. Здоровая установка сообщает о подключении облака, состоянии демона и о том, приостановлено ли принудительное применение. + Запустите `failproofai config --status`. Здоровая установка выведет облачное соединение, состояние демона и информацию о том, приостановлено ли принудительное применение. \ No newline at end of file diff --git a/docs/ru/start/quickstarts/crewai.mdx b/docs/ru/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..0164c5a13 --- /dev/null +++ b/docs/ru/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "Установите, инструментируйте и получите первый трейс." +icon: "/images/frameworks/crewai.svg" +--- + +Три шага к вашему первому трейсу CrewAI. Для информации о том, что несет каждое событие, потоках данных и устранении неполадок, см. [полное руководство](/ru/start/integrations/crewai). + +## Установка + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## Инструментирование + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +Ничего не изменится в вашей команде, агентах, задачах или инструментах. `instrument()` подписывает вас на шину событий CrewAI на уровне модуля. + +## Проверьте доставку + +Запустите один раз, затем откройте **Observe → Sessions** и выберите вашу среду. Ваш запуск появляется как восстановленный трейс. + +Если ничего не приходит, подтвердите, что машина подключена, с помощью `failproofai config --status`. + + + Что записывается, потоки данных, использование токенов, именование спанов, параметры и распространенные проблемы. + \ No newline at end of file diff --git a/docs/ru/start/quickstarts/custom-agents.mdx b/docs/ru/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..b743a5c1d --- /dev/null +++ b/docs/ru/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "Пользовательские агенты" +description: "Оберните вашего агента в три блока `with` и он начнет записывать данные." +icon: "code" +--- + +Для агента, который вы написали сами, или фреймворка, для которого у Failproof AI нет адаптера. + +Вы оборачиваете работу, которую уже делаете, в блоки `with`. Каждый из них записывает, когда начался, когда закончился и сколько времени занял — больше ничего вызывать не нужно. + +## Установка + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # один вызов инструмента +``` + +Прочитайте сверху вниз и это скажет, что это означает: + +| Оберните в | Чтобы сказать | +| --- | --- | +| `session()` | Эти события принадлежат одному запуску | +| `agent()` | Что-то работает — дайте ему имя, которое вы узнаете в списке | +| `tool_call()` | Это один инструмент и вот что он вернул | + +Вкладывайте их так, как вложены в вашем коде. Вы никогда не передаете идентификаторы: каждый блок помнит, внутри чего он находится, поэтому все, что вы записываете, автоматически получает правильный запуск и правильного агента. `async with` работает точно так же. + +## Проверьте прибытие данных + +Запустите один раз, затем откройте **Observe → Sessions** и выберите вашу среду. Ваш запуск появится как восстановленная трассировка. + +Если ничего не приходит, убедитесь, что машина подключена, с помощью `failproofai config --status`. + + + Каждый метод события, что происходит, когда ваш код выбрасывает исключение, рабочий пример, потоки и async, а также инструментирование фреймворка без адаптера. + \ No newline at end of file diff --git a/docs/ru/start/quickstarts/langchain.mdx b/docs/ru/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..5b9d5a6cc --- /dev/null +++ b/docs/ru/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain и LangGraph" +description: "Установите, инструментируйте и получите свой первый трейс." +icon: "/images/frameworks/langchain.svg" +--- + +Три шага к вашему первому трейсу LangChain или LangGraph. Для потоковой передачи, управления человеком в цикле, именования спанов и других опций см. [полное руководство](/ru/start/integrations/langchain). + +## Установка + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Для LangChain без LangGraph используйте `failproofai-sdk[langchain]`. + +## Инструментирование + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +Не требуются изменения кода на месте вызова. `instrument()` регистрирует трейсер, который LangChain внедряет в каждый диспетчер обратных вызовов, который он создаёт, поэтому графы, инструменты и модели захватываются — включая те, что находятся внутри библиотек, которые вы не писали. + +## Проверьте, что данные поступили + +Запустите один раз, затем откройте **Observe → Sessions** и выберите вашу среду. Ваш запуск появится как реконструированный трейс. + +Если данные не поступают, проверьте соединение машины командой `failproofai config --status`. + + + Что записывается, потоковая передача, подсчёт токенов, именование спанов, управление сеансом, опции и управление человеком в цикле. + \ No newline at end of file diff --git a/docs/ru/start/quickstarts/llamaindex.mdx b/docs/ru/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..9a2e8a753 --- /dev/null +++ b/docs/ru/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "Установите, инструментируйте и посмотрите на первую трассировку." +icon: "/images/frameworks/llamaindex.svg" +--- + +Три шага к первой трассировке LlamaIndex. Для шагов workflow, retrieval, reaper и опций см. [полное руководство](/ru/start/integrations/llamaindex). + +## Установка + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## Инструментирование + +API агента LlamaIndex является асинхронным. Каждая область работает как с `async with`, так и с `with`. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + Без одного дополнительного аргумента в вашей LLM каждый подсчет токенов в вашей трассировке будет null — `llama-index-llms-openai` не запрашивает использование при потоковой передаче. См. [Подсчет токенов](/ru/start/integrations/llamaindex#token-counts). + + +## Проверьте, что это пришло + +Запустите один раз, затем откройте **Observe → Sessions** и выберите вашу среду. Ваш запуск появится как восстановленная трассировка. + +Если ничего не появляется, подтвердите подключение машины с помощью `failproofai config --status`. + + + Подсчет токенов, что записывается, шаги workflow, retrieval, опции и распространенные проблемы. + \ No newline at end of file diff --git a/docs/ru/start/quickstarts/pydantic-ai.mdx b/docs/ru/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..03e9e7bdf --- /dev/null +++ b/docs/ru/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "Установите, инструментируйте и просмотрите вашу первую трассировку." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +Три шага к вашей первой трассировке Pydantic AI. Информацию о инструментах, повторных попытках, потоковой передаче и опциях см. в [полном руководстве](/ru/start/integrations/pydantic-ai). + +## Установка + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## Инструментирование + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # перед созданием любого Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` должна выполняться **перед** созданием `Agent`. Возможность добавляется при создании, поэтому агент, созданный ранее, не записывает ничего — и это не приводит к ошибке, потому что ошибки нет. Это наиболее частая причина пустой трассировки с этим адаптером, и именно модульные агенты создают эту проблему: импортируйте `failproofai_sdk` и вызовите `instrument()` перед импортом модуля, который их создает. + + +## Проверьте доставку + +Запустите один раз, затем откройте **Observe → Sessions** и выберите вашу среду. Ваш запуск появится как восстановленная трассировка. + +Если ничего не приходит, убедитесь, что машина подключена, используя `failproofai config --status`. + + + Что записывается, инструменты и повторные попытки, потоковая передача, именование диапазонов, опции и типичные проблемы. + \ No newline at end of file diff --git a/docs/tr/index.mdx b/docs/tr/index.mdx index 08ac33a8d..6cf994c56 100644 --- a/docs/tr/index.mdx +++ b/docs/tr/index.mdx @@ -1,42 +1,42 @@ --- --- -title: "Aracınızı failproof yapın" -description: "Aracılarınızın çalıştığı her ortam için gözlemlenebilirlik ve zorlama — kodlama CLI'ları, sohbet ağ geçitleri, kendi kendini barındıran asistanlar ve kendi enstrümente edilmiş aracılarınız." +title: "Aracınızı hatasız hale getirin" +description: "Aracılarınızın çalıştığı her ortam için gözlemlenebilirlik ve uygulama — kodlama CLI'ları, sohbet ağ geçitleri, kendi barındırılan yardımcılar ve kendi enstrümente edilmiş aracılarınız." icon: "shield-check" --- -Failproof AI, ekiplerin aracılarının ne yaptığını anlamalarına, nerede başarısız olduklarını bulmalarına ve aynı davranış tekrar gerçekleşmeden önce güvenlik önlemleri almalarına yardımcı olur. +Failproof AI, ekiplerin aracıların ne yaptığını anlamasına, nerede başarısız olduklarını bulmasına ve aynı davranışın tekrar olmasından önce koruyucu önlemler almalarına yardımcı olur. -Bir **harness**, aracılarınızın gerçekten çalıştığı ortamdır. Failproof AI bunlardan 12 tanesine bağlanır — Claude Code ve Codex gibi kodlama CLI'ları, Hermes gibi sohbet ağ geçitleri, OpenClaw gibi kendi kendini barındıran asistanlar — ve aynı olaylar, aynı politikalar ve aynı oturum geçmişi tümünde uygulanır. Harnessi olmayan aracılar [Python SDK](/tr/reference/custom-agents) üzerinden rapor verir; bu rapor izlenir ve denetlenir; bir politika burada uygulamak için kendi çalışma zamanınızda bir kanca gerekir. +Bir **harness**, aracınızın gerçekten çalıştığı ortamdır. Failproof AI bunlardan 12 tanesine bağlanır — Claude Code ve Codex gibi kodlama CLI'ları, Hermes gibi sohbet ağ geçitleri, OpenClaw gibi kendi barındırılan yardımcılar — ve aynı olaylar, aynı politikalar ve aynı oturum geçmişi her birinde geçerlidir. Harness'i olmayan aracılar [Python SDK](/tr/reference/custom-agents) aracılığıyla rapor verir; bu da onları izler ve denetler; orada bir politika uygulamak kendi runtime'ınızda bir bağlantı gerektirir. - Projenizi enstrümente etmek, bağlamak ve aracı günlüklerinin geldiğini doğrulamak için beceriyi kullanın. + Projenizi enstrümente etmek, bağlamak ve aracı günlüklerinin geldiğini doğrulamak için skill'i kullanın. - Aracı günlüklerinizi doğal dilde analiz edin, sorgulayın, panolar oluşturun ve denetimler çalıştırın. + Aracı günlükleriniz üzerinde doğal dilde analiz yapın, sorgulayın, panolar oluşturun ve denetimler çalıştırın. - Model çağrılarını, araçları, hataları, insan girdisini, gecikmesini ve politika kararlarını bir oturumda izleyin. + Model çağrılarını, araçları, hataları, insan girişini, gecikmeyi ve politika kararlarını bir oturumda izleyin. - - Tanımlanmış bir oturum kümesini denetleyin, kanıtla desteklenen bulguları gözden geçirin ve düzeltmeyi sorun olarak izleyin. + + Tanımlanmış bir oturum setini denetleyin, kanıta dayalı bulguları gözden geçirin ve çözümü sorun olarak izleyin. - Bilinen bir başarısızlık modunu bir politikaya dönüştürün, etkisini gözlemleyin ve tüm filoğunuzda dağıtın. + Bilinen bir hata modunu politikaya dönüştürün, etkisini gözlemleyin ve bunu tüm filosunda dağıtın. > **Oturum → Denetim → Bulgu → Sorun → Politika**
-> Ne olduğunu izleyin, başarısızlığı bulun, yanıtı yönetin, ardından gelecekteki çalışmalarda aynı davranışı önleyin. +> Ne olduğunu izleyin, hatayı bulun, yanıtı yönetin, ardından gelecekteki çalıştırmalarda aynı davranışı önleyin. ## Buradan başlayın -İlk enstrümente edilmiş aracılarınızı dağıtıyorsanız, [hızlı başlangıç](/tr/start/quickstart) ile başlayın. Eğer veriler zaten geliyorsa, denetimler veya politikalar yapılandırmadan önce gerçek bir çalıştırmayı incelemek üzere [Oturumlar](/tr/sessions/overview)'ı açın. +İlk enstrümente edilmiş aracınızı dağıtıyorsanız, [hızlı başlangıç](/tr/start/quickstart) ile başlayın. Veriler zaten geliyorsa, [Oturumlar](/tr/sessions/overview)'ı açın ve denetimleri veya politikaları yapılandırmadan önce gerçek bir çalıştırmayı inceleyin. - - Yakalamadan güvenli bir şekilde dağıtılan bir politikaya kadar uçtan uca iş akışını tamamlayın. + + Yakalama işleminden güvenli bir şekilde dağıtılan bir politikaya kadar uçtan uca iş akışını tamamlayın. \ No newline at end of file diff --git a/docs/tr/policies/deploy.mdx b/docs/tr/policies/deploy.mdx index e074caca8..b275cfc11 100644 --- a/docs/tr/policies/deploy.mdx +++ b/docs/tr/policies/deploy.mdx @@ -1,47 +1,51 @@ --- -title: "Politikaları dağıtma" -description: "İncelenen bir politika sürümünü hedeflenen makinelere dağıtın." +title: "İlkeleri dağıtın" +description: "İncelenen bir ilke sürümünü hedeflenen makinelere aktarın." icon: "cloud-upload" --- -Bir dağıtım, bir veya daha fazla politika sürümünü, kaydedilmiş makinelerin hedef kümesine bağlar. +Bir dağıtım, bir veya daha fazla ilke sürümünü kayıtlı makinelerin hedef kümesine bağlar. -## Dağıtımı uygulama +## Dağıtım uygulayın 1. **Admin → enforcement** bölümüne gidin, makineyi bulun ve satırını genişletin. - 2. **edit** seçeneğini seçin, incelenen politika sürümünü ekleyin ve **observe** veya uygulama etkisini seçin. - 3. Değişikliği uygulayın, ardından makinenin bir sonraki check-in işlemini bekleyin ve dağıtım ile kapsama durumunu onaylayın. + 2. **edit** seçeneğini tıklayın, incelenen ilke sürümünü ekleyin ve **observe** veya zorlayıcı etkisini seçin. + 3. Değişikliği uygulayın, ardından makinenin sonraki kontrolünü bekleyin ve dağıtım ile kapsama durumunu doğrulayın. 4. Canlı kararları incelemek için **Observe → policy** bölümüne gidin. - ![Politika sürümleri, enforce ve observe etkileri ve dağıtım uygulama eylemiyle makine dağıtım editörü.](/images/dashboard/enforcement-editor.png) + ![İlke sürümleri, enforce ve observe efektleri ile dağıtım editörü ve dağıtım uygulaması aksiyonu.](/images/dashboard/enforcement-editor.png) - Bulut dağıtım uç noktaları kasıtlı olarak sıradan `fp` komutları olarak sunulmaz. Makineyi yerel olarak kontrol edin, ardından dashboard aracılığıyla dağıtın: + CLI'dan `fp fleet` komutuyla dağıtım yapın. Uygulamadan önce ortaya çıkan kümesini gözden geçirin — `deploy` tam planı yazdırır ve **yalnızca `--json` olmayan etkileşimli terminalde** sorar. `--json` altında, `--yes` ile veya stdin yönlendirildiğinde (bir CI adımı, bir betik, bir aracı shell komutu) plan ve istem olmadan hemen uygulanır — bu nedenle gözden geçirmek istiyorsanız önce `fp fleet show ` çalıştırın: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - Dağıtımdan sonra aktivitenin Bulut'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. + `fp fleet diff ` amaç ile teslimatı gösterir (bir makine sonraki yoklamasına kadar `behind` olarak okunur), `fp fleet history ` nesilleri listeler ve `fp fleet rollback ` birini geri yükler — devre dışı bırakılan veya silinen bir ilkeyi adlandıran nesil varsa reddeder. + + Makineyi `failproofai config --status` ile kontrol edin ve dağıtımdan sonra `fp sessions --env production --since 24h` ile `fp events --event-type hook_completed` kullanarak aktivitenin Cloud'a ulaştığını doğrulayın. - Değişken 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. + Değişken bir taslak değil, incelenen bir sürümü dağıtın; oturumlarını inceleyebileceğiniz üretim dışı bir makine veya küçük bir grupla başlayın. - İşi engellememek için eşleşmeleri, nedenleri, etkilenen araçları ve yanlış pozitifleri gözden geçirin. + Eşleşmeleri, nedenleri, etkilenen araçları ve yanlış pozitif sonuçları işi engellemeden gözden geçirin. - - Gözlemlenen eşleşmeler güvensiz eylemleri geçerli olanlardan ayırdıktan sonra yükseltin, ardından her hedeflenen makinenin dağıtımı çektiğini ve kararları rapor ettiğini onaylayın. + + Gözlenen eşleşmeler güvenli olmayan eylemleri geçerli olanlardan ayırdıktan sonra promosyon yapın, ardından her hedeflenen makinenin dağıtımı çektiğini ve kararları raporladığını doğrulayın. -Makinelerin `policies:pull` yeteneğine ihtiyacı vardır. Olay raporlaması ayrı olarak `events:add` tarafından kontrol edilir; Bulut analizi ve uygulaması beklediğinizde her ikisini de doğrulayın. +Makinelerin `policies:pull` yeteneğine ihtiyacı vardır. Olay raporlaması `events:add` tarafından ayrıca kontrol edilir; Cloud analizi ve zorlama beklediğinizde her ikisini de doğrulayın. - Uygulamayı yönetme, bir yönetici Bulut iş akışıdır. Yalnızca kök erişimi gerektiren uygulamayı yönetme rotalarını sıradan müşteri `/v1` API uç noktaları olarak değerlendirmeyin. + Zorlama yönetimi, idari bir Cloud iş akışıdır. Yalnızca root erişimli zorlama rotalarını sıradan müşteri `/v1` API uç noktaları olarak değerlendirmeyin. \ No newline at end of file diff --git a/docs/tr/policies/editor.mdx b/docs/tr/policies/editor.mdx index 14ab40f5a..376cdf63c 100644 --- a/docs/tr/policies/editor.mdx +++ b/docs/tr/policies/editor.mdx @@ -1,48 +1,49 @@ --- ---- -title: "İlke editörü" -description: "Onaylı bir hata modundan sürümlendirilmiş ilkeler oluşturun ve gözden geçirin." +title: "Policy editor" +description: "Onaylanmış bir hata modundan sürümlü politikalar oluşturun ve gözden geçirin." icon: "file-pen-line" --- -İlke editörünü kullanarak bir bulguyu veya sorunu dağıtılabilir bir kurala dönüştürün. Yazarlık işlemini dağıtımdan ayrı tutun, böylece taslak sessizce canlı davranışı değiştiremez. +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 sorun tekrarlanabilir bir işlem desenine sahip olduğunda, **Analyze → issues** altında açın ve **generate policy** seçeneğini tıklayın. Failproof AI öncelikle bir ilkenin 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ınlayana kadar taslak olarak kalır. +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. -## İlke sürümü yayınlayın +## Bir politika sürümünü yayımlayın - 1. **Admin → policy editor** sayfasına gidin ve **compose** bölümünde hata modunu açıklayın veya JavaScript ilkesi kaynağını yapıştırın. + 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. İlke kimliğini girin ve yayınlayın, ardından sürümleri karşılaştırmak veya devre dışı bırakmak için **library** kullanın. - 4. Sürüm makine dağıtımı için hazır olduğunda **enforcement** seçeneğini belirleyin. + 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. - ![İlke kimliği, yapay zeka destekli taslak yazarlığı, kaynak doğrulama ve yayınlama kontrolleri ile birlikte İlke editörü oluşturma görünümü.](/images/dashboard/policy-editor.png) + ![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) - Cloud CLI ilke sürümlerini yayınlamaz. Editöre kopyalamadan önce kaynağı yerel olarak doğrulayın: + 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: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - Gözden geçirilen sürümü **Admin → policy editor** sayfasından yayınlayın. + 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. -## Yazarlık kontrol listesi +## Yazım kontrol listesi -1. Hata modunu operasyonel dilde adlandırın. -2. Karar vermek için yeterli kanıt içeren kanca olaylarını ve araçları seçin. +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 sonra ne yapacağını söyleyen bir neden döndürün. -5. Eşleşmesi gereken örnekler ve izin verilmiş kalması gereken örnekler ekleyin. -6. Yeni bir sürüm kaydedin ve inceleme isteyin. +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. -Ajan güvenli bir şekilde düzeltebildiğinde `instruct` kullanın. İşleme izin verilmesi kabul edilemez veya geri döndürülemez bir risk oluşturacaksa `deny` kullanın. +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. - İlke sürümleri değişmez dağıtım girdileridir. Taslağı düzenlemek yeni bir sürüm oluşturur; zaten makinelere atanmış olan sürümü yeniden yazmamalıdır. + 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 diff --git a/docs/tr/reference/cloud-cli.mdx b/docs/tr/reference/cloud-cli.mdx index 3768518e0..30d4e9a3d 100644 --- a/docs/tr/reference/cloud-cli.mdx +++ b/docs/tr/reference/cloud-cli.mdx @@ -1,19 +1,19 @@ --- title: "Failproof Cloud CLI" -description: "Failproof AI Cloud ile sorgulamak ve yönetmek için fp komut satırı arabiriminin tam başvurusu." +description: "Failproof AI Cloud ile fp kullanarak sorgu yapma ve yönetim için tam referans." icon: "cloud-cog" --- -Bulut telemetrisini incelemek ve denetimler, bulgular, sorunlar, uyarılar, anahtarlar, kullanıcılar, sorgular ve ayarları yönetmek için `fp` kullanın. Yerel kancalar, politikalar, yakalama ve makine kaydı için [`failproofai`](/tr/reference/failproof-cli) komutunu kullanın. +`fp` aracılığıyla Cloud telemetrisi inceleyebilir, bulut tarafından yönetilen zorlama (politikalar, filo dağıtımları, guardrail kararları) yönetebilir, denetimler, bulgular, sorunlar, uyarılar, anahtarlar, kullanıcılar, sorgular ve ayarları yönetebilirsiniz. Yerel kancalar, politikalar, yakalama ve makine kaydı için [`failproofai`](/tr/reference/failproof-cli) kullanın. -Yayınlanan Bulut CLI'yi izole bir araç olarak yükleyin: +Yayınlanan Cloud CLI'yi izole bir araç olarak yükleyin: ```bash uv tool install fp-cloud-cli fp version ``` -## Oturum aç +## Oturum açma ```bash fp login @@ -26,13 +26,13 @@ fp whoami fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` -Global seçenekler komuttan önce gelmelidir: +Küresel seçenekler komuttan önce gelmelidir: ```bash 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ı @@ -40,9 +40,9 @@ Terminal yardımı için `fp COMMAND --help` veya `fp COMMAND SUBCOMMAND --help` | Komut | Amaç | Seçenekler | | --- | --- | --- | -| `fp login` | E-posta ile gönderilen tek kullanımlık kod ile oturum açın ve kuruluş seçin. | `--email`, `-e`; `--org`; `--force` | -| `fp logout` | Kaydedilen kullanıcı oturumunu iptal edin ve kaldırın. | — | -| `fp whoami` | Geçerli kimliği, kimlik doğrulama modunu, kuruluşu ve izinleri gösterin. | — | +| `fp login` | E-posta ile gönderilen bir kerelik kod ile oturum açın ve bir kuruluş seçin. | `--email`, `-e`; `--org`; `--force` | +| `fp logout` | Kaydedilen kullanıcı oturumunu iptal edin ve silin. | — | +| `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. | — | @@ -64,23 +64,27 @@ Bireysel aracı olaylarını listeler. Varsayılan hafif akış ham yükleri har | `--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 tekrar edin veya virgülle ayırın. | -| `--event-type ` | Olay türü filtresi; tekrar edin veya virgülle ayırın. | -| `--agent-id ` | Aracı filtresi; tekrar edin veya virgülle ayırın. | -| `--session-id ` | Oturum filtresi; tekrar edin 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 yeniler önce. | -| `--all` | `--limit` ile otomatik sayfalandırma. | -| `--cursor ` | Opak imleyiciden devam edin. | +| `--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 ` | 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 metin araması; tekrarlanabilir, herhangi bir terim eşleştirilir. | +| `--order asc\|desc` | Zaman sırası. Varsayılan: en yeni önce. | +| `--all` | `--limit` değerine kadar otomatik sayfalandırma. | +| `--cursor ` | Opak imleçten devam edin. | | `--page-size ` | `--all` ile istek başına satır; maksimum `200`. | -| `--full` | Daha ağır olay uç noktası aracılığıyla ham yükleri ekleyin. | -| `--fields ` | Yalnızca seçilen alanları döndürün; `payload` istemek tam modu etkinleştirir. | +| `--full` | Daha ağır olay 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 -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` + + `--all` **`--limit` değerine kadar** sayfalandırır, bu varsayılan olarak **50**'dir — bu nedenle `--all` yalnızca başında 50 satırda durur. Erken durduğunda yanıt, devam etmek için bir `next_cursor` içerir; `"next_cursor": null` akışın gerçekten tükendiği anlamına gelir. + + ### Oturumlar ```text @@ -92,16 +96,16 @@ fp sessions [OPTIONS] | `--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; tekrar edin veya virgülle ayırın. | -| `--status ` | `done`, `error` veya `timeout`; tekrar edin veya virgülle ayırın. | -| `--agent-id ` | Seçilen herhangi bir aracıyı içeren oturumları eşleştirin. | -| `--session-id ` | Oturum filtresi; tekrar edin veya virgülle ayırın. | -| `--all` | `--limit` ile otomatik sayfalandırma. | -| `--cursor ` | Opak imleyiciden devam edin. | +| `--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 aracıyı içeren oturumları eşleştirin. | +| `--session-id ` | Oturum filtresi; tekrarlayın veya virgülle ayırın. | +| `--all` | `--limit` değerine kadar otomatik sayfalandırma. | +| `--cursor ` | Opak imleçten devam edin. | | `--page-size ` | `--all` ile istek başına satır; maksimum `200`. | -| `--fields ` | Yalnızca seçilen alanları döndürün. | -| `--full-ids` | Terminal çıktısında oturum kimliklerini kısaltmayın. | -| `--agents` | Çoklu aracılı oturumlar için aracı listesini genişletin. | +| `--fields ` | Yalnızca seçili alanları döndürün. | +| `--full-ids` | Terminal çıkışında oturum kimliklerini kısaltmayın. | +| `--agents` | Çok aracılı oturumlar için aracı rosteri genişletin. | ### Değerlendirmeler @@ -112,14 +116,14 @@ fp evals [OPTIONS] | Seçenek | Açıklama | | --- | --- | | `--aggregate` | Bireysel değerlendirmeler yerine toplamları ve puan başına istatistikleri gösterin. | -| `--limit`, `-n ` | Maksimum liste satırları. Varsayılan: `50`. | +| `--limit`, `-n ` | Maksimum liste satırı. Varsayılan: `50`. | | `--since`, `--from`, `--to` | Zaman aralığını seçin. | | `--env`, `--status`, `--agent-id`, `--session-id` | Filtre başına bir tam değere daraltın. | -| `--score KEY:MIN..MAX` | Puan aralığı; tekrarlanabilir ve tüm aralıklar eşleşmelidir. | +| `--score KEY:MIN..MAX` | Puan aralığı; tekrarlanabilir ve tüm aralıklar eşleşmeli. | | `--all`, `--cursor`, `--page-size` | Liste sayfalandırmasını kontrol edin. | -| `--fields ` | Yalnızca seçilen alanları döndürün. | +| `--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 @@ -130,20 +134,20 @@ fp errors [OPTIONS] | Seçenek | Açıklama | | --- | --- | | `--aggregate` | Satırları listelemek yerine eşleşen hataları özetleyin. | -| `--limit`, `-n ` | Maksimum liste satırları. Varsayılan: `50`. | +| `--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 araması; tekrarlanabilir. | +| `--search ` | Yük metni arayın; tekrarlanabilir. | | `--order asc\|desc` | Zaman sırası. | | `--all`, `--cursor`, `--page-size` | Liste sayfalandırmasını kontrol edin. | -| `--fields ` | Yalnızca seçilen alanları döndürün. | +| `--fields ` | Yalnızca seçili alanları döndürün. | | `--full-ids` | Tam oturum kimliklerini gösterin. | ### Kullanım ve filtre değerleri | Komut | Amaç | | --- | --- | -| `fp usage` | Geçerli ölçüm penceresi için kullanımı gösterin. | +| `fp usage` | Mevcut ölçüm penceresi için kullanımı gösterin. | | `fp list envs` | Gözlemlenen ortamları listeleyin. | | `fp list agents` | Gözlemlenen aracı kimliklerini listeleyin. | | `fp list event_types` | Olay türlerini listeleyin. | @@ -158,7 +162,7 @@ fp errors [OPTIONS] | Komut | Amaç | | --- | --- | | `fp orgs list` | Erişilebilir kuruluşları listeleyin. | -| `fp orgs switch [SLUG]` | Etkin kuruluş kaydedin; atlanırsa sorar. | +| `fp orgs switch [SLUG]` | Etkin bir kuruluşu kaydedin; atlanırsa sor. | | `fp orgs current` | Etkin kuruluşu gösterin. | | `fp orgs perms` | Etkin kuruluştaki izinlerinizi gösterin. | @@ -167,24 +171,24 @@ fp errors [OPTIONS] | 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 create NAME` | Bir anahtar oluşturun ve gizli bilgisini bir kez ortaya çıkarın. | `--permission-set`; `--add`; `--remove` | -| `fp keys update NAME` | İzin kümesini değiştirin veya izinleri ayarlayın. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | -| `fp keys regenerate NAME` | Gizli bilgiyi döndürün ve değiştirileni bir kez ortaya çıkarın. | `--yes`, `-y` | +| `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 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 tokenleri `resource:action` biçimini (örneğin `events:add`) kullanır. `--add` seçeneğini tekrarlayın, tokenleri virgülle ayırın veya `events:read.add` gibi noktalı eylemler kullanın. +İzin jetonları `resource:action` biçimini kullanır, örneğin `events:add`. `--add` seçeneğini tekrarlayın, jetonları virgülle ayırın veya `events:read.add` gibi noktalı eylemler kullanın. ### Sorgular | Komut | Amaç | Seçenekler | | --- | --- | --- | -| `fp query list` | Kaydedilmiş sorguları listeleyin. | `--show-id`; `--fields ` | +| `fp query list` | Kayıtlı sorguları listeleyin. | `--show-id`; `--fields ` | | `fp query show NAME` | Bir sorguyu gösterin. | — | -| `fp query create NAME` | Bir sorgu kaydedin. | `--sql `; `--description` | +| `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 ad hoc SQL'i çalıştırın. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query run [NAME]` | Kaydedilmiş bir 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 @@ -192,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 show EMAIL` | Bir üyeyi ve onların yetkilerini gösterin. | — | | `fp users create EMAIL` | Bir üye ekleyin. | `--permission-set`; `--add`; `--remove` | -| `fp users update EMAIL` | Bir üyenin izinlerini değiştirin. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users update EMAIL` | Bir ü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` | @@ -202,9 +206,9 @@ fp errors [OPTIONS] | Komut | Amaç | Seçenekler | | --- | --- | --- | -| `fp settings list` | Kuruluş ayarlarını ve geçerli değerleri listeleyin. | — | +| `fp settings list` | Kuruluş ayarlarını ve mevcut 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 tam olarak biri; isteğe bağlı `--yes`, `-y` | +| `fp settings set KEY` | Mevcut bir ayarı değiştirin. | tam olarak `--value`, `--json-value`, `--file` seçeneklerinden biri; isteğe bağlı `--yes`, `-y` | ### Uyarılar @@ -213,36 +217,36 @@ 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 ile `--name`; `--yes`, `-y` | +| `fp alerts update NAME` | Bir uyarıyı güncelleyin veya yeniden adlandırın. | oluştur 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 test NAME` | Test bildirimi gönderin. | `--channels`; `--yes`, `-y` | -Uyarı önem dereceleri `info`, `warning` ve `critical` olur. Tetikleme 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` şeklindedir. Tetik türleri `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound` ve `per_event` şeklindedir. Değerlendirme aralıkları 30 ile 86.400 saniye arasında olmalıdır. ### Denetimler | Komut | Amaç | Seçenekler | | --- | --- | --- | | `fp audits list` | Denetimleri listeleyin. | `--enabled-only`; `--show-id` | -| `fp audits show NAME` | Bir denetim tanımı ve durumunu gösterin. | — | -| `fp audits create NAME` | Bir denetim oluşturun ve ilk çalıştırmasını hemen kuyruğa alın. | Bkz. [oluşturma seçenekleri](#audit-create-options). | -| `fp audits edit NAME` | Denetim ayarlarını değiştirirken belirtilmemiş değerleri koruyun. | tanım seçeneklerini oluşturun; `--name`; `--yes`, `-y` | +| `fp audits show NAME` | Bir denetim tanımını ve durumunu gösterin. | — | +| `fp audits create NAME` | Bir denetim oluşturun ve hemen ilk çalıştırmasını kuyruğa alın. | Bkz. [oluştur seçenekleri](#audit-create-options). | +| `fp audits edit NAME` | Denetim ayarlarını değiştirin belirtilmeyen değerleri koruyarak. | tanım seçenekleri oluştur; `--name`; `--yes`, `-y` | | `fp audits delete NAME` | Bir denetimi, bulgularını ve çalıştırma geçmişini silin. | `--yes`, `-y` | -| `fp audits run NAME` | Manuel çalıştırma kuyruğu. | — | +| `fp audits run NAME` | Manuel çalıştırma kuyruğa alın. | — | | `fp audits runs NAME` | Çalıştırma geçmişini listeleyin. | `--limit`, `-n`; `--show-id` | -| `fp audits context-show NAME` | Özet ve referans URL getirme durumunu gösterin. | — | +| `fp audits context-show NAME` | Özeti ve referans URL alma durumunu gösterin. | — | | `fp audits context-set NAME` | Özeti veya referans URL'lerini değiştirin. | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | Referans URL'lerini yeniden getirin. | — | +| `fp audits context-refresh NAME` | Referans 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ıtlarını gösterin. | — | -| `fp audits ack FINDING_ID` | Bir bulguyu kabul edin. | `--reason` | -| `fp audits mute FINDING_ID` | Yinelenen deseni bastırın. | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | Deseni işlem yapılabilir olmayan olarak işaretleyin ve bastırın. | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | Bir bulguyu düzeltilmiş olarak işaretleyin ve gelecekteki bastırmayı yapılmayın. | `--yes`, `-y` | +| `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 işlem yapılamaz olarak işaretleyin ve bastırın. | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | Bir bulguyu düzeltilmiş olarak işaretleyin, gelecekte bastırma yapılmaz. | `--yes`, `-y` | | `fp audits reopen FINDING_ID` | Bir bulguyu canlı kuyruğa döndürün ve bastırmayı temizleyin. | — | | `fp audits assign FINDING_ID` | Bulgu sahibini ayarlayın. | gerekli `--to ` | -#### Denetim oluşturma seçenekleri +#### Denetim oluştur seçenekleri ```bash fp audits create checkout-reliability \ @@ -258,26 +262,26 @@ fp audits create checkout-reliability \ | Seçenek | Açıklama | | --- | --- | | `--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 ` | Hata sorusunu veya amacı belirtin. | -| `--enabled` / `--disabled` | Planlamayı açık veya kapalı başlatın. Varsayılan: etkin. | +| `--description ` | Hata sorusunu veya amacını belirtin. | +| `--enabled` / `--disabled` | Zamanlamayı açık veya kapalı şekilde başlatın. Varsayılan: etkin. | | `--schedule-interval-secs ` | `3600`–`604800`. Varsayılan: `86400`. | -| `--schedule-anchor ` | ISO 8601 biçiminde sabit UTC aşaması. Varsayılan: sonraki 09:00 UTC. | -| `--window-mode since_last\|fixed` | Son tam analiz edilen pencereden sonra devam edin veya tekrar tekrar haddeleme penceresini inceleyin. Varsayılan: `since_last`. | +| `--schedule-anchor ` | ISO 8601 biçiminde sabit UTC fazı. Varsayılan: sonraki 09:00 UTC. | +| `--window-mode since_last\|fixed` | Son tam analiz edilen pencereden sonra devam edin veya tekrar tekrar bir kayan pencereyi 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; tekrar edin veya virgülle ayırın. | +| `--ignore-error-type ` | Hata türlerini hariç tutun; tekrarlayın veya virgülle ayırın. | | `--llm` / `--no-llm` | Aracı analizi etkinleştirin veya devre dışı bırakın. Varsayılan: etkin. | -| `--top-k ` | `1`–`500` bulguyu tutun. Varsayılan: `50`. | -| `--sensitivity low\|medium\|high` | Raporlama hassasiyetini ayarlayın. Varsayılan: `medium`. | +| `--top-k ` | `1`–`500` bulgu saklayın. 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 karşılıklı olarak birbirini dışlar. | -| `--url ` | Genel HTTPS referansı ekleyin; en fazla beş kez tekrarlayın. | +| `--text-file ` | Özeti bir dosyadan okuyun; `--text` seçeneği ile karşılıklı olarak özel. | +| `--url ` | Genel HTTPS referansı ekleyin; beş kez tekrarlayın. | -İlk çalıştırmaya ihtiyacı olduğunda oluşturma sırasında bağlam ekleyin. Oluşturma tanımı ve bağlamı kuyruğa alınan çalıştırma başlamadan önce birlikte kaydeder. +İlk çalıştırmaya ihtiyacı olduğunda oluşturma sırasında bağlam ekleyin. Oluşturma, kuyruğa alınan çalıştırma başlamadan önce tanımı ve bağlamı birlikte kaydeder. - `fp audits run` asenkrondur. Bulgularını okumadan önce en son çalıştırmanın başarılı veya başarısız olmasını `fp audits runs NAME` ile yoklayın. + `fp audits run` eşzamansızdır. En son çalıştırma başarılı veya başarısız olana kadar `fp audits runs NAME` seçeneğini yoklayın, ardından bulgularını okuyun. ### Sorunlar @@ -285,67 +289,111 @@ fp audits create checkout-reliability \ | Komut | Amaç | Seçenekler | | --- | --- | --- | | `fp issues list` | Sorunları listeleyin. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | Açık veya seçilen sorun durumlarını sayın. | `--state` | -| `fp issues show INCIDENT_ID` | Sorun ayrıntılarını, açıklamaları, abone üyeleri ve etkinliği gösterin. | — | -| `fp issues open` | Manuel veya uyarıya bağlı sorun açın. | gerekli `--summary`; isteğe bağlı `--title`, `--alert-id`, `--severity` | -| `fp issues ack INCIDENT_ID` | Bir sorunu kabul edin. | — | -| `fp issues assign INCIDENT_ID` | Atanmışları değiştirin; temizlemek için seçeneği atlayın. | tekrarlanabilir `--assignee` | +| `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 listesini ve etkinliği gösterin. | — | +| `fp issues open` | El ile 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` | Atayan kişileri değiştirin; temizlemek için seçeneği atlayın. | tekrarlanabilir `--assignee` | | `fp issues resolve INCIDENT_ID` | Bir sorunu çözün. | `--yes`, `-y` | -| `fp issues comment-list INCIDENT_ID` | Açıklamaları listeleyin. | — | -| `fp issues comment-add INCIDENT_ID` | Bir açıklama ekleyin. | `--body`, `--file` seçeneklerinden tam olarak biri | -| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Bir açıklamayı silin. | `--yes`, `-y` | -| `fp issues subscribers INCIDENT_ID` | Abone üyeleri listeleyin. | — | +| `fp issues comment-list INCIDENT_ID` | Yorumları listeleyin. | — | +| `fp issues comment-add INCIDENT_ID` | Yorum ekleyin. | tam olarak `--body`, `--file` seçeneklerinden biri | +| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Bir yorumu silin. | `--yes`, `-y` | +| `fp issues subscribers INCIDENT_ID` | Abone listesini gösterin. | — | | `fp issues subscribe INCIDENT_ID` | Kendinizi veya başka bir operatörü abone yapın. | `--email` | -| `fp issues unsubscribe INCIDENT_ID` | Abone üyeliğini kaldırın. | `--email` | +| `fp issues unsubscribe INCIDENT_ID` | Bir 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` şeklindedir. Bağımsız sorun önem dereceleri `info`, `warning` ve `critical` şeklindedir. ### Bulut yardımcısı | Komut | Amaç | Seçenekler | | --- | --- | --- | -| `fp agent health` | Yardımcı kullanılabilirliğini ve yapılandırmasını kontrol edin. | — | -| `fp agent models` | Mevcut yardımcı modellerini listeleyin. | — | +| `fp agent health` | Asistan kullanılabilirliğini ve yapılandırmasını kontrol edin. | — | +| `fp agent models` | Mevcut asistan modellerini listeleyin. | — | | `fp agent chats` | Kaydedilmiş sohbetleri listeleyin. | — | -| `fp agent ask [MESSAGE]` | Bir sohbeti başlatın veya devam edin; ileti atlanırsa stdin'i okuyun. | `--chat`; `--model`; `--page-context` | +| `fp agent ask [MESSAGE]` | Bir sohbet başlatın veya devam ettirin; ileti atlanırsa 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` | -## Genel bayraklar +### Politikalar + +Bulut tarafından yönetilen politika sürümleri. **Yalnızca oturum** — buradaki her komut bir API anahtarı altında çıkış `2` verir, herhangi bir istekten önce, çünkü bunlar kasıtlı olarak `/v1` seçeneğinden yoksun olan yalnızca root yazma rotalarıdır. + +| Komut | Amaç | Seçenekler | +| --- | --- | --- | +| `fp policies list` | Politika sürümlerini listeleyin. | `--json` | +| `fp policies show POLICY_ID` | Bir politikayı kaynağı ile gösterin. | — | +| `fp policies publish NAME PATH` | Yerel `.mjs` dosyasından bir sürüm oluşturun. | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | Çıkarıldığı her dağıtıma geri ekleyin, her birinde yeni bir nesil oluşturun. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | Taşıdığı her dağıtımdan çıkarın, her birinde yeni bir nesil oluşturun. | `--yes`, `-y` | +| `fp policies delete POLICY_ID` | Bir politika sürümünü silin. | `--yes`, `-y` | +| `fp policies test PATH` | Sentetik bir bağlama karşı yerel olarak bir politika çalıştırın. Her politikanın `match` filtresini uygular, bu nedenle verilen olay/araç kapsamında yer almayan bir politika çalıştırılmak yerine `skipped` olarak rapor edilir. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | +| `fp policies compose PROMPT` | Asistan ile bir politika taslaklayın. `policies:write` gerekir. | — | + +### Filo + +Hangi makinelerin hangi politikaları çalıştırdığı. **Yalnızca oturum**, yukarıdakiyle aynı nedenle. + +| Komut | Amaç | Seçenekler | +| --- | --- | --- | +| `fp fleet list` | Kayıtlı makineleri ve dağıtım kuşağını listeleyin. | — | +| `fp fleet show MACHINE_ID` | Bir makinenin şu anda çalıştırdığı politika seti. | — | +| `fp fleet deploy MACHINE_ID` | **Makinenin tüm politika setini değiştirin.** Planı yazdırır ve `--json` olmadan etkileşimli bir terminalde yalnızca sorular. | `--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 history MACHINE_ID` | Bir makine için eski 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` | + +### Guardrails + +Zorlama aslında ne yaptı. **Yalnızca oturum**, yukarıdakiyle aynı nedenle. + +| Komut | Amaç | Seçenekler | +| --- | --- | --- | +| `fp guardrails summary` | Kapsama, engellenen/değerlendirilen toplamlar, bir reddetme sparkline'ı ve politika başına tablo. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Pencere üzerinde kova halinde karar, her politika kaynağında toplanmış. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | + +## Küresel bayraklar | Bayrak | Açıklama | | --- | --- | -| `--json` | Makine tarafından okunabilir JSON yayın. | -| `--base-url ` | Kendi barındırılan veya geliştirme panosunu kullanın. | -| `--org ` | Bu çalıştırma için bir kuruluş seçin. | -| `--token ` | Kaydedilen kullanıcı oturumu tokenini geçersiz kılın. | -| `--api-key ` | Otomasyon ile kimlik doğrulayın bir API anahtarı ile; asla kaydedilmez. | +| `--json` | Makine tarafından okunabilir JSON yayınlayın. | +| `--base-url ` | Kendi barındırılan veya geliştirme panosu kullanın. | +| `--org ` | Bu çağırma için bir kuruluş seçin. | +| `--token ` | Kaydedilen kullanıcı oturumu jetonunu geçersiz kılın. | +| `--api-key ` | Otomasyon kimliğini API anahtarı ile doğrulayın; 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. | -| `--insecure` / `--secure` | TLS sertifika doğrulamasını devre dışı bırakın veya geri yükleyin. | -| `--version` | Kutulu sürümü yazdırın ve çıkı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` | Kutu 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ş geçişi ve yardımcı komutları bir kullanıcı oturumu gerektirir. +`--api-key`, otomasyon için tasarlanmıştır. Oturum açma, kuruluş geçişi ve asistan komutları kullanıcı oturumu gerektirir. ## Ortam değişkenleri | Değişken | Eşdeğer veya amaç | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | Geçerli CLI yapılandırma dizinini yeniden konumlandırın. | -| `AGENTEYE_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. | - -Açık bayraklar ortam değişkenlerini geçersiz kılar, ortam değişkenleri kaydedilen yapılandırmayı geçersiz kılar. API anahtarı modunda, kiracıyı `--org` veya `AGENTEYE_ORG` ile açıkça seçin. +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `FP_API_KEY` | `--api-key` | +| `FP_JSON` | `--json` | +| `FP_INSECURE` | `--insecure` | +| `FP_HOME` | CLI yapılandırma dizinini yeniden konumlandırın (varsayılan `~/.failproofai/fpcli`). | +| `FP_ANALYTICS_DISABLED` veya `DO_NOT_TRACK` | Anonim CLI analitiğini 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, bunlar ise kaydedilmiş yapılandırmayı geçersiz kılar. API anahtarı modunda, kiracıyı `--org` veya `FP_ORG` ile açıkça seçin. + + + Bu yazımların `AGENTEYE_*` biçimleri **`fp` tarafından okunmaz** ve hiçbir zaman okunmamıştır — CLI `FP_*` bildirir (`fp_cli/app.py`), ve bilinmeyen bir değişken bir hata değildir. `AGENTEYE_DASHBOARD_URL` ayarlaması CLI'yı yeniden hedeflemez; göz ardı edilir ve komut sessizce kaydedilmiş pano yerine çalışır. + + `AGENTEYE_HOME` ve `AGENTEYE_ENVIRONMENT` hala var, ancak bunlar bu CLI değil **toplayıcı ve telemetri SDK'sı** aittir. + - Yapılandırmayı silen, iptal eden, bastıran, çözen veya değiştiren komutlar varsayılan olarak sor. Etkin kuruluşu ve hedefi doğruladıktan sonra `--yes` kullanın. + 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. \ No newline at end of file diff --git a/docs/tr/reference/custom-agents.mdx b/docs/tr/reference/custom-agents.mdx index fa1f5905e..be289f4c9 100644 --- a/docs/tr/reference/custom-agents.mdx +++ b/docs/tr/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- title: "Özel ajanlar" -description: "Özel ajanlardan alınan izlemeleri işaretle; böylece Failproof AI çalıştırmaları yeniden oluşturabilir ve hataları bulabilir." +description: "failproofai-sdk için yapılandırma, olay kataloğu, korelasyon kuralları ve teslimat." icon: "python" --- -`failproofai-sdk` ile özel bir ajanın izlemelerini işaretleyin; böylece Failproof AI her çalıştırmayı yeniden oluşturabilir, davranışını denetleyebilir ve kanıtla desteklenen hataları bulabilir. SDK, Failproof daemon'ının buluta göndermesi için yapılandırılmış olayları yazar. Python 3.10 veya daha yeni bir sürüm gerekir. +Her ayarın, metodun ve alanın ne işe yaradığı. İlk kez enstrümantasyon yapıyorsanız, rehberle başlayın — bu sayfa referans amaçlıdır. -İzleme, özel ajanları gözlemlenebilir ve denetlenebilir hale getirir. Güvensiz bir eylemi yürütülmeden önce engellemek, çalışma zamanında bir zorlama kancası gerektirir. + + + Kurulum, enstrümantasyon, olay metodları, çalışan bir örnek ve yaygın sorunlar. + + + LangChain, CrewAI, LlamaIndex ve Pydantic AI kendilerini tek bir çağrıyla enstrümente eder. + + - - Özel bir ajan kurulumunda ilkeleri uygulamak için [Failproof AI ile iletişime geçin](mailto:support@befailproof.ai). Çalışma zamanının model, araç ve yaşam döngüsü sınırlarını ilke kancalarıyla eşleştirmenize yardımcı olacağız. - +Python 3.10 veya daha yeni sürüm. Çalışma zamanı bağımlılığı yok. -
- -
- -## `failproofai-sdk` yükleyin - -SDK şu anda özel bir wheel olarak dağıtılmaktadır. Mevcut sürüm ve indirme erişimi için Failproof AI temsilcinize başvurun. +## Kurulum ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -`uv` ile, wheel'i indirin ve `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl` komutunu çalıştırın. Wheel'i özel bir artifact deposunda sabitleyin veya bağımlılık kilidinde tutun. - -Paket `failproofai-sdk` olarak yüklenir ve Python'da `failproofai` olarak içe aktarılır. +Paket `failproofai-sdk` olarak kurulur ve Python'da `failproofai_sdk` olarak içe aktarılır. `failproofai-sdk[langgraph]` gibi framework eklentileri framework'ün kendisini kurar; adaptörler her zaman temel wheel'de gönderilir. -## Failproof daemon'ını bağlayın +## Failproof daemon'unu bağlayın - 1. **Admin → Anahtarlar** 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. İşaretlenmiş bir oturumu çalıştırın, sonra **Gözlemle → Olaylar** bölümünde tam kimliğini bulun. - 4. **Gözlemle → Oturumlar** bölümüne gidin, aynı ortamı seçin ve yeniden oluşturulan izlemeyi açın. + 1. **Admin → Keys** bölümüne gidin ve `events:add` ile bir anahtar oluşturun. + 2. Ajan makinesinde [Failproof daemon'unu Cloud'a bağlayın](/tr/start/setup#connect-a-machine-to-cloud). + 3. Bir enstrümante oturum çalıştırın, ardından **Observe → Events** altında tam kimliğini bulun. + 4. **Observe → Sessions** bölümüne gidin, aynı ortamı seçin ve yeniden oluşturulan trace'i açın. - ![Yürütme grafiği ve sıralanmış olay izlemesi olarak yeniden oluşturulan özel bir Python ajan oturumu.](/images/dashboard/session-detail.png) + ![Bir özel Python ajan oturumu, yürütme grafiği ve sıralı olay trace'i olarak yeniden oluşturulmuş.](/images/dashboard/session-detail.png) ```bash @@ -51,102 +46,84 @@ Paket `failproofai-sdk` olarak yüklenir ve Python'da `failproofai` olarak içe -## Tam bir çalıştırmayı işaretleyin - -İşlem başlangıcında `configure()` öğesini bir kez çağırın. Her olay çağrısı yalnızca anahtar sözcüktür ve kararlı bir `session_id` ve `agent_id` gerektirir. +## Yapılandırma ```python -import traceback -import uuid +import failproofai_sdk -import failproofai +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -failproofai.configure(environment="production") +| Argument | Ne işe yarar | +| --- | --- | +| `environment` | Her olayın etiketi — `production`, `staging`, `prod-eu`. Varsayılan olarak `dev`. | +| `flush_interval` | Arka plan iş parçacığının diske yazma sıklığı, saniye cinsinden. Varsayılan olarak `0.5`. | +| `base_dir` | Yazılacak yer. Varsayılan olarak daemon'un spool'u, aksi takdirde bilmiyorsanız bunu istiyorsunuz. | -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +Bunun yerine ortam değişkeni ile ayarlayın: -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) +| Değişken | Ne işe yarar | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | `environment` değerini kod değişikliği olmadan ayarlar, etiket uygulamaya değil dağıtıma aitse. Bir `configure()` argümanı bunu geçersiz kılar. | +| `FAILPROOFAI_HOME` | Spool'u tutan Failproof AI köküne taşır. | +| `FAILPROOFAI_SDK_STRICT` | `1` yapıldığında, enstrümantasyon hataları kaydedilmek yerine atılır. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` yapıldığında, framework uyumluluğu sorunu uyarı yerine atılır. | -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + + **`environment` içinde virgül yok.** Alım bu alanı virgülle bölerek filtreler oluşturur ve bir virgül içeren herhangi bir olayı atlar — tüm çalıştırma sessizce kaybolur. `prod,eu` değil `prod-eu` yazın. + + `configure(environment="prod,eu")` hata atarak sizi hemen haberdar eder. `AGENTEYE_ENVIRONMENT` atamaz — sizin çağıran bir şey olmadığını — bu yüzden bir kez uyarır ve `dev` değerine geri döner. + -Aktör başına bir kez `agent_start` gönderin. Alt ajanlar için ebeveynin `session_id` öğesini yeniden kullanın, her aktöre farklı bir `agent_id` verin ve `parent_id` öğesini üst öğenin **agent ID** öğesine ayarlayın (oturum kimliğine değil). +Olaylar bellek içinde sıraya alınır ve arka planda her `flush_interval` saniyede yazılır; interpreter çıkışında son bir temizleme yapılır. Doğrudan kapatılan bir işlem henüz yazılmamış her şeyi kaybeder. -## Yapılandırma başvurusu +## Kimlik + +Her olay bir oturum ve bir ajana aittir. **Kapsamlar her ikisini de doldurur**, bu nedenle nadiren bunları geçersiniz: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| Ayar | Davranış | -| --- | --- | -| `base_dir` | Açık spool kökü. Tüm ortam değişkenlerine göre önceliklidir. | -| `flush_interval` | Bellekten JSONL'ye arka plan yazmaları arasındaki saniye sayısı. Varsayılan: `0.5`. | -| `environment` | Her olaydaki dağıtım etiketi. `dev` olarak varsayılan değer. | -| `FAILPROOFAI_HOME` | `custom-agents` spool'unu içeren Failproof AI kökünü değiştirir. | - -SDK, ayarlandığında açık `base_dir` öğesine yazar. Aksi takdirde, `FAILPROOFAI_HOME` veya `~/.failproofai` altında Failproof daemon'ının `custom-agents` spool'unu kullanır. +`session_id` veya `agent_id` açıkça geçirmek hala işe yarar ve öncelik alır. Bağlı veya geçirilmediğinde, çağrı `TypeError` atar ve Cloud'un sessizce atıp atacağı bir olayı yayınlamak yerine. -SDK çağrıları bellekte sıraya alır ve arka plan iş parçacığında toplu işler yazar. Ayrıca Python'ın `atexit` işlemesi aracılığıyla son bir temizleme girişiminde bulunur. Kısa ömürlü işçiler için normal yorumlayıcı kapatmasına izin verin; sabit işlem sonlandırması bellekte kalan olayları kaybedebilir. + + Kimlik bağlam değişkenleri üzerinde sürüklenir. `asyncio` görevlerini otomatik olarak takip eder, ancak **yeni iş parçacıklarını takip etmez** — bir çalışanı `failproofai_sdk.propagate()` ile sarın veya olayları ektisiz tutulur. + ## Olay kataloğu -Tüm yöntemler `None` döndürür. `None` olarak bırakılan alanlar JSON `null` olarak yazılmak yerine çıkarılır. +On beş metod. Çoğu **çiftler** halinde gelir — açan metodunu çağırır, ardından kapatıcıyı çağırır ve SDK boşluğu zamanlar. -| Yöntem | Kimlik ötesinde gerekli alanlar | İsteğe bağlı alanlar | +| | Açan | Kapatan | +| --- | --- | --- | +| **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` | + +Üçü bağımsızdır: `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 her şey JSON `null` yerine gönderilmez ve her metod `None` döndürür. + +| Metod | Gerekli | İsteğe bağlı | | --- | --- | --- | | `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ Tüm yöntemler `None` döndürür. `None` olarak bırakılan alanlar JSON `null | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -Bir tamamlama hata olarak sayılması gereken durumlarda `outcome="failed"`, `"error"`, `"timeout"` veya `"rejected"` kullanın. `"failure"` dahil diğer değerler geçerli arka uç tarafından hata olarak sınıflandırılmaz. + + + + 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 — örneğin yakın kaçamak olan `"failure"` — başarı olarak sayılır. + + +## Eşleştirme ve süre + +**Bir kural: kapatma olayına açan ile aynı kimliği verin.** İşte bu onları eşleştirir ve SDK'nın boşluğu zamanlamasına olanak tanır. + +| Çift | Eşleşme | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**`duration_ms` kendiniz geçmeyin.** SDK bunu ölçer ve geçirmek `ValueError` atar. -## Korelasyon ve süre kuralları +Tek istisna `model_response`'dir; burada sadece siz gerçek sağlayıcı gecikme süresiyle ilgilidir. Milisaniye cinsinden tam bir sayı geçirin — bir float atar, çünkü sütun 32-bit tamsayıdır ve aksi takdirde boş kalacaktır. -- Eşleştirme tamamlama olayı için aynı `tool_call_id`, `hook_id`, `pause_id` veya `input_id` öğesini yeniden kullanın. -- SDK, `tool_result`, `hook_completed`, `agent_resume` ve `human_input` için `duration_ms` öğesini hesaplar. Bunu kendiniz bu yöntemlere aktarmak `ValueError` yükseltir. -- Araç ve kanca kimlikleri bir işlem genelinde bekleyen harita paylaşır. Bunları eşzamanlı oturumlar ve her iki ad alanı genelinde genel olarak benzersiz yapın; sağlayıcı kimlikleri veya UUID'ler en güvenlidir. -- Süreçler arasında bölünmüş bir çift yine de aşağı akış olarak ilişkilendirir, ancak SDK işlem içi süresini hesaplayamaz. -- Bekleyen harita en fazla 10.000 başlama barındırır ve dolu olduğunda en eski girişi çıkarır. + -## Özel alanlar ve yükler +- **Kimlikler sadece türü başına, oturum başına benzersiz olması gerekir.** Bir araç çağrısı ve bir kanca birini paylaşabilir; aynı anda çalışan iki oturum çarpışma olmadan aynı kimlikleri yeniden kullanabilir. +- **Bir ajana kapsamlı değildirler.** Bir çift bir ajan altında açılıp başka bir ajan altında kapatılsa bile — çok ajanlarla kodda normal durumu — hala eşleşir. +- **`request_id` isteğe bağlıdır ama önerilen.** Olmadan, model olayları geldikleri sırayla eşleşir, bu yüzden aynı ajan içinde iki eş zamanlı çağrı yanlış eşleşme yapabilir. +- **İşlemler arası bölünmüş çift** Cloud'da hala eşleşir, ancak SDK bunu zamanlamaz — hiçbir işlem her iki yarıyı da görmedi. +- **En fazla 10.000 açan aynı anda bir kapatıcıyı bekler.** Ondan sonra en eski bırakılır, bu nedenle bir sızıntı sınırsız büyüyemez. -Her olay ekstra anahtar sözcük alanlarını kabul eder. Aşağı akış sorgularında yapı gerektiğinde JSON uyumlu değerleri kullanın. UUID'ler, tarihler, ondalıklar, kümeler, baytlar ve model nesneleri gibi desteklenmeyen yapraklar yazar tarafından dizeleştirilir. + -Ayrılmış özel adlar `timestamp`, `session_id`, `agent_id`, `type` ve `environment` öğeleridir. İsteğe bağlı alan yazım hataları yeni özel alanlar olarak kabul edilir, bu nedenle standart bir alan Cloud'da görünmediğinde yayılan JSON'u gözden geçirin. +## Kendi alanlarınız + +Geçirdiğiniz herhangi bir fazladan anahtar olayla depolanır: + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # sizinki +) +``` + +Daha sonra sorgulamak istiyorsanız JSON türlerini tercih edin. Başka bir şey — bir UUID, bir datetime, bir `Decimal`, bir set, bytes, bir model nesnesi — string olarak depolanır. + + + **Alan adlarınızı önek ekleyin.** Ekstralar en son uygulanır, bu yüzden `model`, `tool_name` veya `outcome` olarak adlandırılan bir alan gerçek olanı sessizce üzerine yazar. Framework adaptörleri `fw_` kullanır; aynısını yapın ve hiçbir şey çarpışamaz. + + Bu aynı zamanda neden yanlış yazılan isteğe bağlı bir alan asla hata vermediğidir — sadece yeni bir özel alan olur. Standart bir alan Cloud'da eksikse, önce yazımı kontrol edin. + + +Bu beş ad ayrılmıştır ve doğrudan reddedilir: `timestamp`, `session_id`, `agent_id`, `type`, `environment`. ## Teslimat ve doğrulama - **Gözlemle → Olaylar** bölümünde, önce `agent_start` öğesinin var olduğunu, sonra `agent_end` öğesinin son olduğunu doğrulayın. Sonra **Gözlemle → Oturumlar** 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 kimliğini birincil sorun giderme anahtarı olarak kullanın. + **Observe → Events** içinde, önce `agent_start` var olduğunu, sonra `agent_end` var olduğunu doğrulayın. Ardından **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 kimliğini birincil sorun giderme anahtarı olarak kullanın. ```bash @@ -189,10 +203,14 @@ Ayrılmış özel adlar `timestamp`, `session_id`, `agent_id`, `type` ve `enviro -Cloud boşsa, `$FAILPROOFAI_HOME/custom-agents/events` öğesini inceleyin; aksi takdirde `~/.failproofai/custom-agents/events` öğesini inceleyin. JSONL dosyaları SDK emisyonunu kanıtlar; büyüyen bir spool daemon yapılandırması veya teslimata işaret ederken, boş bir spool araçlar veya işlem ömrüne işaret eder. +Cloud boşsa, `$FAILPROOFAI_HOME/custom-agents/events` konumunu inceleyin, aksi takdirde `~/.failproofai/custom-agents/events` konumunu inceleyin. JSONL dosyaları SDK yayınını kanıtlar; büyüyen bir spool, daemon yapılandırması veya teslimat sorununu işaret ederken, boş bir spool enstrümantasyon veya işlem ömrü sorunu işaret eder. + + + Spool'u sadece daemon durmuşken inceleyin. Çalışırken, her toplu işi milisaniye içinde toplar ve siler, bu yüzden bir dizin listesi toplayıcıyla yarışır ve yayınlanan olaylardan çok daha azını gösterir. + -## Özel bir çalışma zamanında hataları önleyin +## Özel çalışma zamanında 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ğlı izlemeleri kullanın. Özel bir zorlama entegrasyonu, eylemi yürütülmeden önce ortaya koymak, yapılandırılmış girdisini ilke motoruna geçirmek ve sonuç allow, instruct veya deny kararını uygulamalıdır. +Güvensiz eylemi, gerekli kanıtı ve amaçlanan tepkiyi tanımlamak için denetim bulgularını ve bağlantılı trace'leri kullanın. Özel bir yaptırım entegrasyonu, eylemi yürütmeden önce ifşa etmeli, yapılandırılmış girdisini politika motoruna geçirmeli ve sonuçlanan allow, instruct veya deny kararını uygulamalıdır. -Çalışma zamanınız için bu entegrasyonu tasarlamak ve doğrulamak amacıyla [support@befailproof.ai](mailto:support@befailproof.ai) adresine e-posta gönderin. \ No newline at end of file +[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ı politika kancalarına eşleştirmeye yardımcı olacağız, ardından entegrasyonu sizinle doğrulayacağız. \ No newline at end of file diff --git a/docs/tr/reference/events-and-configuration.mdx b/docs/tr/reference/events-and-configuration.mdx index f9170f8b6..a836e6293 100644 --- a/docs/tr/reference/events-and-configuration.mdx +++ b/docs/tr/reference/events-and-configuration.mdx @@ -1,41 +1,41 @@ --- -title: "Etkinlikler ve yapılandırma" -description: "Etkinlik modelini, ortamları, yerel depolamayı ve yapılandırma sınırlarını referans alın." +title: "Olaylar ve yapılandırma" +description: "Olay modelini, ortamları, yerel depolamayı ve yapılandırma sınırlarını referans alın." icon: "list-tree" --- -## Etkinlik aileleri +## Olay aileleri -- Agent başlama, bitme, duraklatma ve devam ettirme +- Ajan başlama, bitme, duraklatma ve devam ettirme - Model isteği ve yanıtı -- Tool kullanımı ve sonucu +- Araç kullanımı ve sonucu - Hook tetikleme ve tamamlama -- İnsan bekleme, girdi, duraklatma ve kesme +- İnsan bekleme, girdi, duraklatma ve kesintiye uğratma - Açık hatalar -Her etkinlik bir zaman damgası, oturum kimliği, agent kimliği, etkinlik türü ve ortam taşır. Etkinliğe özgü alanlar model, tool, korelasyon, sonuç, içerik, süre veya hata verilerini içerir. +Her olay bir zaman damgası, oturum kimliği, ajan kimliği, olay türü ve ortam taşır. Olaya özgü alanlar model, araç, korelasyon, sonuç, içerik, süre veya hata verilerini içerir. -## Bir etkinlik sözleşmesini inceleyin +## Bir olay sözleşmesini inceleyin - 1. **Observe → Events** bölümünü açın. - 2. Kısa bir zaman penceresi ayarlayın ve ortam, agent ve etkinlik türüne göre filtreleyin. - 3. Bir etkinliği seçerek normalleştirilmiş alanlarını ve ham yükünü inceleyin, ardından yürütme bağlamını görmek için oturumunu açın. - 4. Eşleştirilmiş bir süre eksikse, başlangıç ve tamamlama etkinliklerinin aynı korelasyon kimliğini kullandığını doğrulayın. + 1. **Observe → Events** öğesini açın. + 2. Kısa bir zaman penceresi ayarlayın ve ortam, ajan ve olay türüne göre filtreleyin. + 3. Normalleştirilmiş alanlarını ve ham yükünü incelemek için bir olayı seçin, ardından yürütme bağlamını görmek için oturumunu açın. + 4. Eşleştirilmiş bir süre eksikse, başlama ve tamamlama olaylarının aynı korelasyon kimliğini kullandığını doğrulayın. - Etkinlikler akışını kullanarak verileri bir agent çalışmasına daraltın ve normalleştirilmiş etkinlik alanlarını inceleyin. + Verileri tek bir ajan çalışmasına daraltmak ve normalleştirilmiş olay alanlarını incelemek için Events akışını kullanın. - ![Ortam, agent, oturum ve etkinlik türü için filtreler içeren canlı Events akışı.](/images/dashboard/events-stream.png) + ![Ortam, ajan, oturum ve olay türü filtreleriyle birlikte canlı Events akışı.](/images/dashboard/events-stream.png) - Ardından etkinliği oturumuna takip edin. İz, onun hemen öncesinde ve sonrasında ne olduğunu gösterir; bu, yük tek başına belirsiz olduğunda gereklidir. + Ardından olayı oturumunun içine takip edin. İz, bundan hemen önce ve sonra ne olduğunu gösterir; bu, yükün tek başına belirsiz olduğunda gereklidir. - ![Yürütme bağlamında etkinliği incelemek için kullanılan bağlantılı oturum izlemesi.](/images/dashboard/session-detail.png) + ![Olayı yürütme bağlamında incelemek için kullanılan bağlantılı oturum izi.](/images/dashboard/session-detail.png) - Eşleştirilmiş bir etkinlik veya süre eksik olduğunda her iki görünüm arasında korelasyon kimliklerini ve zaman damgalarını karşılaştırın. + Eşleştirilmiş bir olay veya süre eksikse her iki görünümde de korelasyon kimlikleri ve zaman damgalarını karşılaştırın. - Geçerli filtre değerlerini bulun, ardından bir oturum için tam etkinlik yüklerini getirin: + Geçerli filtre değerlerini keşfedin, ardından tek bir oturum için tam olay yüklerini getirin: ```bash fp list event_types @@ -47,32 +47,32 @@ Her etkinlik bir zaman damgası, oturum kimliği, agent kimliği, etkinlik tür --full ``` - Makine tarafından okunabilir inceleme için `fp --json events ... --fields ts,event_type,session_id,payload` kullanın. + Makine tarafından okunabilir inceleme için `fp --json events ... --fields ts,event_type,session_id,payload` komutunu kullanın. ## Ayrılmış SDK alanları -`timestamp`, `session_id`, `agent_id`, `type` veya `environment` alanlarını özel Python SDK alanları olarak kullanmayın. Tool sonuç süresi gibi eşleştirilmiş etkinlik süreleri SDK tarafından hesaplanır ve manuel olarak sağlanamaz. +`timestamp`, `session_id`, `agent_id`, `type` veya `environment` öğelerini özel Python SDK alanları olarak kullanmayın. Tool result süresi gibi eşleştirilmiş olay süreleri SDK tarafından hesaplanır ve el ile sağlanamaz. ## Yerel sınırlar -- Failproof AI durumu, aksi takdirde açıkça yapılandırılmadığı sürece `~/.failproofai` altında yaşar. -- `failproofai-sdk`, eski base-directory geçersiz kılması için `AGENTEYE_HOME` kullanır. +- Failproof AI durumu, açıkça başka şekilde yapılandırılmadığı sürece `~/.failproofai` altında bulunur. +- `failproofai-sdk` her zaman `~/.failproofai/custom-agents` altında spool yapar. `FAILPROOFAI_HOME` bu ana dizini yeniden konumlandırır; `custom-agents` segmenti her zaman eklenir, bu nedenle spool bunun dışına yerleştirilemez. Yalnızca SDK'nın kendi `configure(base_dir=...)` öğesi başka yerlere yazar. `AGENTEYE_HOME`, eski `agenteye-collector` tarafından izlenecek öğeleri seçmek için okunur ve SDK'nın yazacağı yeri artık etkilemez. - Ortam etiketleri SDK yapılandırması veya `AGENTEYE_ENVIRONMENT` aracılığıyla ayarlanabilir. -- Daemon kimlik bilgileri gizli olmayan ayarlardan ayrı olarak depolanır. +- Daemon kimlik bilgileri, gizli olmayan ayarlardan ayrı olarak depolanır. -İstikrarlı, düşük kardinaliteli ortam adları kullanın. Daemon ortam etiketlerinde virgüller desteklenmiyor. +Kararlı, düşük kardinaliteli ortam adlarını kullanın. Daemon ortam etiketlerinde virgüller desteklenmez. ## Bir ortam etiketini değiştirin - Ortam etiketleri, gönderen SDK veya Failproof daemon tarafından atanır. Bir tanesini değiştirdikten sonra **Observe → Sessions** bölümünü açın ve yeni oturumların yeni değeri taşıdığını doğrulamak için ortam filtresini kullanın. Mevcut oturumlar özgün ortamlarını koruyor. + Ortam etiketleri, yayan SDK veya Failproof daemon tarafından atanır. Değiştirdikten sonra **Observe → Sessions** öğesini açın ve ortam filtresini kullanarak yeni oturumların yeni değeri taşıdığını onaylayın. Mevcut oturumlar orijinal ortamlarını korurlar. - `failproofai-sdk` için ortamı kod içinde veya eski ortam değişkeniyle yapılandırın. Makine düzeyinde ayarları değiştirirken daemon yapılandırmasını yeniden çalıştırın. + `failproofai-sdk` için ortamı kodda veya eski ortam değişkeni ile yapılandırın. Makine düzeyindeki ayarları değiştirirken daemon yapılandırmasını yeniden çalıştırın. ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/tr/reference/harnesses.mdx b/docs/tr/reference/harnesses.mdx index ce0ada19d..4abff4010 100644 --- a/docs/tr/reference/harnesses.mdx +++ b/docs/tr/reference/harnesses.mdx @@ -1,71 +1,72 @@ --- -title: "Ajan donanımları" -description: "Oturumları yakala ve desteklenen 12 ajan donanımının tümü arasında politikaları uygula." +--- +title: "Agent harnesses" +description: "Capture sessions and enforce policies across all 12 supported agent harnesses." icon: "plug-zap" --- -Donanım, ajanınızın gerçekte çalıştığı her şeydir. Failproof AI, bunlardan on ikisini destekler ve iki sınıfa ayrılırlar: +Harness, ajanınızın gerçekten çalıştığı ortamdır. Failproof AI on iki harness'i destekler ve bunlar iki kategoriye ayrılır: -- **Kodlama CLI'leri** (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) +- **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) -Bir ajan hangi donanımda çalışırsa çalışsın, aynı politikalar ve aynı oturum geçmişi geçerlidir. Bir adaptör katmanı, her donanımın yerel olay adlarını, araç adlarını ve araç giriş alanlarını herhangi bir politika çalıştırılmadan önce 29 kanonik olaya eşler. +Aynı politikalar ve aynı oturum geçmişi, ajanın hangi harness içinde çalıştığına bakılmaksızın geçerlidir. Tek bir adaptör katmanı, her harness'in yerel olay adlarını, araç adlarını ve araç-giriş alanlarını herhangi bir politika çalışmadan önce 29 canonical olaya eşler. -On ikisinden **hiçbirinde** çalışmayan bir ajan, [Python SDK](/tr/reference/custom-agents) ile doğrudan enstrümante edilir. Bu farklı bir sözleşmedir ve açıkça belirtilmeye 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 uygulama kancası gerekir; [bizimle iletişime geçin](mailto:support@befailproof.ai) ve bunu eşleştireceğiz. +On iki harness'in **hiçbirinde** çalışmayan bir ajan doğrudan [Python SDK](/tr/reference/custom-agents) ile enstrüman edilir. Bu farklı bir sözleşmedir ve açıkça belirtilmelidir: SDK, tracing, oturumlar, değerlendirmeler ve denetimler sağlar — **kendi başına politikaları zorlamaz.** Güvensiz bir eylemi yürütülmeden önce engellemek, runtime'ınızın araç sınırında bir enforcement hook gerektirir; [bize ulaşın](mailto:support@befailproof.ai) ve bunu eşleyelim. -| Donanım | Desteklenen kanca kapsamları | +| Harness | Desteklenen hook scopes | | --- | --- | -| 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ı | +| 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 | -Her entegrasyon, politikalar çalıştırılmadan önce yerel kanca olay adlarını, araç adlarını ve araç giriş alanlarını normalleştirir. Bir politika yalnızca donanımın açığa çıkardığı olaylara etki edebilir; tam olarak dağıtacağınız donanımda ve sürümde turun sonu ve talimat davranışını test edin. +Her entegrasyon, politikalar çalışmadan önce yerel hook olay adlarını, araç adlarını ve araç-giriş alanlarını normalleştirir. Bir politika, yalnızca harness'in ortaya koyduğu olaylara etki edebilir; dağıttığınız kesin harness ve sürümde end-of-turn ve instruction davranışını test edin. -## Uygulama yeteneği +## Enforcement capability -"Engelle" anlamı, adlandırılan donanım tarafından tüketilen geçerli adaptörün dönüş kararıdır. Araç sonrası engelleme, modele gösterilen sonucu değiştirebilir ancak zaten gerçekleşen bir araç yan etkisini geri alamaz. +"Block" (bloke et), adlandırılan harness tarafından tüketilen current adapter'ın döndürülen kararı anlamına gelir. Post-tool blocking, modele gösterilen sonucu değiştirebilir ancak zaten gerçekleşmiş bir araç yan etkisini geri alamaz. -| Donanım | Doğrulanmış engelleme olayları | Yalnızca gözlem veya engellemeyen uyarılar | +| Harness | Verified blocking events | Observe-only or non-blocking caveats | | --- | --- | --- | -| 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 görev sonrası olaylar gözlemseldir. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Araç sonrası engelleme yürütülmeden sonra sonucu değiştirir; oturum başlatma ve kompakt olaylar geçerli adaptörde gözlemseldir. | -| 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özlemseldir. | +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` ve birkaç task/config olayı | `PostToolUse`, oturum lifecycle, bildirimler ve post-failure olayları gözlemseldir. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Post-tool blocking yürütülmesinden sonra sonucu değiştirir; oturum-başlangıç ve compact olayları current adapter'da gözlemseldir. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Post-tool blocking yürütülmesinden sonra sonucu değiştirir; oturum ve bildirim olayları gözlemseldir. | | Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` ve oturum olayları gözlemseldir. | -| OpenCode | `PreToolUse` | Araç sonrası ve yaşam döngüsü olayları gözlemseldir; geçerli durdurma işlemi doğrulanmış bir kapı yerine daha sonraki bir turun rehberidir. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Araç sonrası ve yaşam döngüsü olayları gözlemseldir; durdurma rehberi daha sonraki bir turla ilgilidir. | -| Hermes | `PreToolUse` | Araç sonrası, oturum ve alt ajan durdurma kararları kapı değildir. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Araç sonrası, oturum, alt ajan durdurma ve sıkıştırma olayları gözlemseldir. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Araç sonrası ve alt ajan durdurma kararları gözlemseldir. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, koşullu `PermissionRequest` | İzin kancaları her izin modunda çalışmaz; araç sonrası ve oturum olayları gözlemseldir. | -| Antigravity CLI | `PreToolUse`, `Stop` | Kullanıcı istemi ve araç sonrası kararları gözlemseldir; hızlı talimatlar yine de enjekte edilebilir. | -| Goose | `PreToolUse` | Kullanıcı istemi, araç sonrası ve oturum olayları gözlemseldir. Yukarıda yerleşik bir engelleme durdurma kancası vardır ancak geçerli adaptör tarafından yüklenmez. | +| OpenCode | `PreToolUse` | Post-tool ve lifecycle olayları gözlemseldir; current stop handling bir sonraki turn için rehberliktir, verified gate değildir. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Post-tool ve lifecycle olayları gözlemseldir; stop rehberliği bir sonraki turn'e uygulanır. | +| Hermes | `PreToolUse` | Post-tool, oturum ve subagent-stop kararları kapı değildir. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Post-tool, oturum, subagent-stop ve compaction olayları gözlemseldir. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Post-tool ve subagent-stop kararları gözlemseldir. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, conditional `PermissionRequest` | Permission hooks her permission mode'da çalışmaz; post-tool ve oturum olayları gözlemseldir. | +| Antigravity CLI | `PreToolUse`, `Stop` | User-prompt ve post-tool kararları gözlemseldir; prompt instructions yine de enjekte edilebilir. | +| Goose | `PreToolUse` | User-prompt, post-tool ve oturum olayları gözlemseldir. Upstream'de yerel bir blocking stop hook vardır ancak current adapter tarafından yüklenmez. | -Yetenekler sürüme duyarlıdır. Bir ajan CLI'sini yükselttikten sonra yeniden test edin, özellikle bir politika yaygın ön araç kapısından ziyade hızlı, durdurma, izin veya araç sonrası davranışına dayanıyorsa. +Capabilities versiyon-hassastır. Bir agent CLI'ı yükselttikten sonra, özellikle bir politika common pre-tool gate yerine prompt, stop, permission veya post-tool davranışına güveniyorsa yeniden test edin. -## Yakalama ve politika kancalarını yükleyin +## Install capture and policy hooks - - 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'yi gösterilen anahtarla bağlayın ve donanım kancalarını yükleyin. - 3. Yeni bir ajan oturumu başlatın, ardından **Gözlemle → Olaylar**'ın altında kanca ve oturum olaylarını onaylayın. - 4. Aynı zaman penceresi için **Gözlemle → politika**'yı açın ve politika kararının makineye atandığını onaylayın. + + 1. **Administration → Keys** açın ve `events:add` ve `policies:pull` izinleriyle makine veya ortam için adlandırılmış bir anahtar oluşturun. + 2. Hedef makinede, local CLI'ı görüntülenen anahtarla bağlayın ve harness hook'larını kurun. + 3. Yeni bir agent oturumu başlatın, ardından **Observe → Events** altında hook ve oturum olaylarını onaylayın. + 4. Aynı zaman penceresi için **Observe → policy** açın ve bir politika kararının makineye atfedildiğini onaylayın. - Bağlantı bir makine anahtarıyla başlar. Sırrını kopyalamadan önce hem alım hem de politika teslimi izinlerini içerdiğini onaylayın. + Bağlantı bir makine anahtarıyla başlar. İts sırrını kopyalamadan önce hem ingestion hem de policy-delivery izinlerini içerdiğini onaylayın. - ![Olay alımı ve politika teslimi izinleri vermek için kullanılan yeni API anahtar çekmeceği.](/images/dashboard/key-create.png) + ![Olay ingestion ve policy delivery izinleri vermek için kullanılan yeni API key drawer.](/images/dashboard/key-create.png) - Kancaları yükledikten sonra, Olaylar akışı bağladığınız makine ve ortamdan yeni olayları göstermelidir. + Hook'ları yükledikten sonra, Events stream bağladığınız makineden ve ortamdan yeni olayları göstermelidir. - ![Yeni yüklenen donanımın raporladığını onaylamak için kullanılan canlı Olaylar akışı.](/images/dashboard/events-stream.png) + ![Yeni yüklenen bir harness'in raporlama yaptığını onaylamak için kullanılan live Events stream.](/images/dashboard/events-stream.png) - Son olarak, politika kararlarının aynı makineye atandığını doğrulayın. Bu, donanımın izleme olaylarının yanı sıra politika aktivitesini de rapor ettiğini doğrular. + Son olarak, politika kararlarının aynı makineye atfedildiğini doğrulayın. Bu, harness'in trace olaylarının yanı sıra politika aktivitesini de rapor ettiğini doğrular. - ![Yeni bağlanan donanımdan politika kararlarını doğrulamak için kullanılan Politika sayfası.](/images/dashboard/policy-observe.png) + ![Yeni bağlanan bir harness'ten politika kararlarını doğrulamak için kullanılan Policy sayfası.](/images/dashboard/policy-observe.png) - Algılanan her donanım için kancaları yükleyin: + Algılanan her harness için hook'ları kurun: ```bash failproofai config \ @@ -74,7 +75,7 @@ Yetenekler sürüme duyarlıdır. Bir ajan CLI'sini yükselttikten sonra yeniden failproofai policies --install ``` - Veya adlandırılmış donanımlar ve yapılandırma kapsamı hedefleyin: + Veya adlandırılmış harness'leri ve bir configuration scope'unu hedefleyin: ```bash failproofai policies --install \ @@ -82,7 +83,7 @@ Yetenekler sürüme duyarlıdır. Bir ajan CLI'sini yükselttikten sonra yeniden --scope user ``` - Proje kapsamı kanca yapılandırmasını depo ile birlikte tutar. Kullanıcı kapsamı depolar arasında çalışmayı kapsar. Claude Code aynı zamanda yerel kapsamı destekler; destek donanıma göre değişir ve CLI desteklenmeyen kombinasyonları reddeder. + Project scope, hook konfigürasyonunu bir repository'de tutar. User scope, depolarda çalışmaları kapsar. Claude Code ayrıca local scope'u destekler; destek harness'e göre değişir ve CLI desteklenmeyen kombinasyonları reddeder. Makineyi ve olaylarını doğrulayın: @@ -94,16 +95,16 @@ Yetenekler sürüme duyarlıdır. Bir ajan CLI'sini yükselttikten sonra yeniden -## Varsayılan olmayan oturum yolu ekleyin +## Add a non-default session path - - Ek yollar makinede kaydedilir, Bulutla değil. Birini ekledikten sonra, **Gözlemle → Oturumlar**'ı açın, ortamı makineye filtreleyin ve yeni yoldan oturumlar göründüğünü onaylayın. Bir oturumu açın ve bir denetimde buna güvenmeden önce ajan, donanım ve olay zaman damgalarını kontrol edin. + + Ek paths Cloud'da değil makinede kaydedilir. Bir tane ekledikten sonra, **Observe → Sessions** açın, makine ortamına filtre uygulayın ve yeni path'den oturumlar göründüğünü onaylayın. Bir oturumu açın ve agent, harness ve olay timestamps'lerini audit'te güvenmeden önce kontrol edin. - ![Ek yakalama yolundan veri alan ortama filtrelen Oturumlar listesi.](/images/dashboard/sessions-list.png) + ![Ek capture path'den veri alan ortama filtre uygulanan Sessions listesi.](/images/dashboard/sessions-list.png) - İsteğe bağlı bir etiketle yol ekleyin, ardından yapılandırılmış yolları inceleyin: + İsteğe bağlı bir label ile path ekleyin, ardından yapılandırılmış path'leri inceleyin: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -112,10 +113,10 @@ Yetenekler sürüme duyarlıdır. Bir ajan CLI'sini yükselttikten sonra yeniden failproofai backfill --since 7d ``` - `failproofai harness remove-path claude checkout` ile bir yolu kaldırın. + `failproofai harness remove-path claude checkout` ile path'i silin. - 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. + Kuruluştan sonra bir yeni oturum çalıştırın. Rollout'u genişletmeden önce hem live event stream'i 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 f2baf522b..c819c6bd5 100644 --- a/docs/tr/reference/overview.mdx +++ b/docs/tr/reference/overview.mdx @@ -1,61 +1,64 @@ --- title: "Entegrasyonlar ve referans" -description: "Desteklenen agent harness'ları, SDK'ları, CLI'ları ve HTTP API'yi bağlayın." +description: "Desteklenen ajan harneslerini, SDK'ları, CLI'ları ve HTTP API'sini bağlayın." icon: "braces" --- -Agentnizin zaten çalıştığı yere en yakın entegrasyonu seçin. +Ajanınızın zaten çalıştığı yere en yakın entegrasyonu seçin. - - Desteklenen kodlama ve otonom agent CLI'ları için hook'ları kurun. + + Desteklenen kodlama ve özerk ajan CLI'ları için hook'ları kurun. - - Özel agentlerdeki hataları bulacak şekilde trace'leri enstrüman edin, ardından çalışma zamanınıza önleme eklemek için bizimle iletişime geçin. + + LangGraph, CrewAI, LlamaIndex, Pydantic AI veya özel bir ajanı enstrüman edin. - - Yerel projeleri, oturumları, politika aktivitesini ve çevrimdışı denetimleri gözden geçirin. + + Yapılandırma, olay kataloğu, korelasyon kuralları ve teslim. + + + Yerel projeleri, oturumları, politika faaliyetini ve çevrimdışı denetimleri inceleyin. - Yerel yakalamaları, hook'ları, politikaları, denetimleri, teslimatı ve makine durumunu yapılandırın. + Yerel yakalama, hook'lar, politikalar, denetimler, teslim 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 inaktif oturumları FastAPI hizmeti ile puanlayın. + + Tam 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 ile yazılmış sayfalar birden çok uç noktaya yayılan veya bu genel yüzeyin dışındaki yönetim arayüzlerini kullanan iş akışlarını açıklar. +Oluşturulan [HTTP API referansı](/tr/reference/http-api), genel `/v1` yüzeyini kapsar. El yazısı sayfalar, birden fazla uç noktayı kapsayan veya bu genel yüzey dışında yönetim arabirimlerini kullanan iş akışlarını açıklar. -## Bir agent bağlayın ve verileri doğrulayın +## Bir ajanı bağlayın ve verileri doğrulayın - - 1. **Administration → Keys** sayfasını açın, `events:add` ve `policies:pull` izinlerine sahip bir anahtar oluşturun ve gizli anahtarı kopyalayın. + + 1. **Administration → Keys** seçeneğini açın, `events:add` ve `policies:pull` izinlerine sahip bir anahtar oluşturun ve sırrı kopyalayın. 2. Entegrasyonu yukarıdaki eşleşen sayfayı kullanarak yapılandırın. - 3. **Observe → Events** sayfasını açarak olayların geldiğini doğrulayın, ardından **Observe → Sessions** sayfasını açarak tam çalışmaları oluşturduğunu doğrulayın. - 4. Entegrasyonun ortamına göre filtreleyin ve denetimler tarafından gereken model, tool, error ve policy alanlarının bulunduğu bir oturumu inceleyin. + 3. **Observe → Events** seçeneğini açarak olayların geldiğini doğrulayın, ardından **Observe → Sessions** seçeneğini açarak tam çalışmalar oluşturduğunu doğrulayın. + 4. Entegrasyonun ortamına filtre uygulayın ve denetimler tarafından gereken model, aracı, hata ve politika alanları için bir oturumu inceleyin. - Anahtar bölmesi ile başlayın. Seçilen izinler, makinenin olayları gönderebildiğini ve Cloud tarafından yönetilen politikaları alabileceğini belirler. + Anahtar çekmecesinden başlayın. Seçilen izinler, makinenin olayları gönderebilip Cloud tarafından yönetilen politikaları alabilmesini belirler. - ![Etkinlik alımı ve politika teslimatı izinleri verilen yeni API anahtar çekmeceği.](/images/dashboard/key-create.png) + ![Etkinlik alımı ve politika teslim izinlerini vermek için kullanılan yeni API anahtar çekmecesi.](/images/dashboard/key-create.png) - Entegrasyonu bağladıktan sonra, olaylarının beklenen ortamda tam çalışmalara gruplandırıldığını doğrulamak için Sessions listesini kullanın. + Entegrasyonu bağladıktan sonra, olaylarının beklenen ortamda tam ajan çalışmalarında gruplandırıldığını doğrulamak için Oturumlar listesini kullanın. - ![Yeni bağlanan bir entegrasyonun tam agent çalışmaları bildirdiğini doğrulamak için kullanılan Sessions listesi.](/images/dashboard/sessions-list.png) + ![Yeni bağlanan bir entegrasyonun tam ajan çalışmalarını raporladığını doğrulamak için kullanılan Oturumlar listesi.](/images/dashboard/sessions-list.png) - Entegrasyonu tamamlandığı için değerlendirmeden önce bu oturumlardan birini açın; izleme, denetimlerinizin ihtiyaç duyduğu model, tool, error ve policy kanıtlarını içermelidir. + Entegrasyonu tamamlanmış olarak düşünmeden önce bu oturumlardan birini açın; izleme, denetimlerinizin gereken model, aracı, hata ve politika kanıtlarını içermelidir. - Bir makine anahtarı oluşturun, Failproof daemon'ını bağlayın ve ilk oturumu doğrulayın. + Bir makine anahtarı oluşturun, Failproof daemon'u bağlayın ve ilk oturumu doğrulayın. ```bash fp keys create agent-production \ @@ -71,8 +74,8 @@ Oluşturulan [HTTP API referansı](/tr/reference/http-api), genel `/v1` yüzeyin fp events --since 1h --env production --limit 20 ``` - 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. + Başka bir araç sonucu tüketecekse `fp --json sessions ...` kullanın. `--json`, `--org` ve `--base-url` gibi genel bayraklar komuttan önce gelmeli. - Yerel komutlar için [Failproof AI CLI referansını](/tr/reference/failproof-cli), `fp` komutları için [Failproof Cloud CLI referansını](/tr/reference/cloud-cli#cli-commands) görmek için bkz. + Yerel komutlar için [Failproof AI CLI referansına](/tr/reference/failproof-cli) ve `fp` komutları için [Failproof Cloud CLI referansına](/tr/reference/cloud-cli#cli-commands) bakın. \ No newline at end of file diff --git a/docs/tr/reference/troubleshooting.mdx b/docs/tr/reference/troubleshooting.mdx index 2ee7f6051..ed64c113b 100644 --- a/docs/tr/reference/troubleshooting.mdx +++ b/docs/tr/reference/troubleshooting.mdx @@ -1,16 +1,16 @@ --- title: "Sorun Giderme" -description: "Eksik oturumları, eksik politikaları, başarısız teslimatları ve engellenen aracı işlemlerini tanılayın." +description: "Eksik oturumları, eksik politikaları, başarısız teslimatları ve engellenen ajan eylemlerini tanılayın." icon: "wrench" --- - + - - **Administration → Keys** bölümünü açın ve makine anahtarının etkin olduğunu ve `events:add` iznine sahip olduğunu doğrulayın. Ardından **Observe → Events** bölümünü açın, zaman aralığını genişletin ve ortam ile aracı filtrelerini temizleyin. Olaylar varsa, oturum kimliğini arayın ve **Observe → Sessions** bölümünde gruplandırmayı kontrol edin. Hiç olay yoksa, CLI'den Failproof daemon'ını tanılayın. + + **Administration → Keys** açın ve makine anahtarının etkin olduğunu ve `events:add` izinlerine sahip olduğunu doğrulayın. Ardından **Observe → Events** açın, zaman aralığını genişletin ve ortam ile ajan filtrelerini temizleyin. Olaylar varsa, oturum ID'sini arayın ve ardından gruplama için **Observe → Sessions** kontrol edin. Olay yoksa, CLI'den Failproof daemon'ını tanılayın. - ![Canlı Events akışı, ana filtreleri ve yakın zamanda gelen aracı olayları görünüyor.](/images/dashboard/events-stream-current.png) + ![Canlı Events akışı birincil filtreleri ve yakın zamanda gelen ajan olayları göstermektedir.](/images/dashboard/events-stream-current.png) ```bash @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - Yakalama işleminin etkinleştirildiğini, yapılandırılan anahtarın `events:add` iznine sahip olduğunu ve pano filtresinin yayılan ortamla eşleştiğini doğrulayın. + Kaydın etkin olduğunu, yapılandırılan anahtarın `events:add` izinlerine sahip olduğunu ve dashboard filtresinin yayılan ortamla eşleştiğini doğrulayın. - - **Observe → Events** bölümündeki filtreleri temizleyin ve tam SDK oturum kimliğini arayın. Hiçbir şey görünmüyorsa, kaynak makinedeki SDK spool'unu ve Failproof daemon'ını inceleyin. + + **Observe → Events** içindeki filtreleri temizleyin ve tam SDK oturum ID'sini arayın. Hiçbir şey görünmezse, kaynak makinedeki SDK spool ve Failproof daemon'ını inceleyin. ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - Aracı işleminin `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` ayarladığını ve SDK başlamadan önce `$FAILPROOFAI_HOME/custom-agents` veya aksi takdirde `~/.failproofai/custom-agents` dizininin mevcut olduğunu doğrulayın. + Bir daemon'ın çalıştığını ve bağlandığını doğrulayın — SDK, daemon olup olmadığına bakılmaksızın spool yapar. Spool dizini önceden var olması **gerekmez** (yazıcı onu oluşturur) ve hiçbir ortam değişkeni onu seçmez: `$FAILPROOFAI_HOME/custom-agents`, aksi takdirde `~/.failproofai/custom-agents` tek kök dizinidir ve `configure(base_dir=...)` tek geçersiz kılma yoludur. İşlem `SIGKILL` veya OOM tarafından öldürülmüşse, sırada kalan her şey kaybedilir — sınırlamak için `SIGTERM` işleyin. - - **Admin → enforcement** bölümünü açın, makinenin seçilmiş ve bildirilen sürümlerini karşılaştırın. Dağıtım kapsamının makinenin dahil edildiğini ve anahtarının `policies:pull` iznine sahip olduğunu doğrulayın. İngest, politika teslimatı yapılmadığında bile çalışabilir. + + **Admin → enforcement** açın, makinenin seçili versiyonları ve raporlanan versiyonlarını karşılaştırın. Dağıtım kapsamının makineyi içerdiğini ve anahtarın `policies:pull` izinlerine sahip olduğunu doğrulayın. Alım, politika teslimatı çalışmadığında bile çalışabilir. @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - Makine kimliği ve etiketi ile pano hedefinin eşleştiğini doğrulayın. Mevcut kimlik bilgileri yalnızca olay alımı yetkisi veriyorsa, politika yeteneğine sahip bir anahtarla yeniden bağlanın. + Makine ID'si ve etiketi dashboard hedefiyle eşleştiğini doğrulayın. Mevcut kimlik bilgisi yalnızca etkinlik alımı sağlıyorsa, politika yetkili bir anahtarla yeniden bağlanın. - + - - **Admin → enforcement** bölümünü açın ve makinenin son görülme zamanını ve bildirilen sürümünü inceleyin. Makine eski ise, bunu yerel daemon sorunu olarak değerlendirin. Kullanılamayan bir daemon'u atlatmak için yalnızca dağıtılan politikayı zayıflatmayın. + + **Admin → enforcement** açın ve makinenin son görülme saati ile raporlanan versiyonunu inceleyin. Makine eskiyse, bunu yerel daemon sorunu olarak değerlendirin. Kullanılamayan bir daemon'ı atlamak için dağıtılan politikayı zayıflatmayın. @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - `failproofaid` yeniden başlatın veya güncelleyin; CLI ve daemon protokol sürümleri farklı olduğunda yapılandırmayı yeniden çalıştırın. Yapılandırılan daemon yolu tasarım gereği kapalı durumda başarısız olur. + `failproofaid` yeniden başlatın veya güncelleyin; CLI ve daemon protokol versiyonları farklıysa yapılandırma yeniden çalıştırın. Yapılandırılan daemon yolu tasarım gereği kapalı başarısız olur. - - Bulutta yazılan bir politika için, **Admin → policy editor** bölümünü açın, taslağı seçin ve yayınlamadan önce doğrulama hatalarını gözden geçirin. Yerel bir politika için, CLI ile doğrulayın, ardından bir test işleminden sonra kararların geldiğini doğrulamak için **Observe → policy** bölümünü açın. + + Cloud tarafından yazılan bir politika için **Admin → policy editor** açın, taslağı seçin ve yayımlamadan önce doğrulama hatalarını gözden geçirin. Yerel politika için CLI ile doğrulayın, ardından test eyleminden sonra kararların geldiğini doğrulamak için **Observe → policy** açın. - Dosya adının `policies.js`, `policies.mjs` veya `policies.ts` ile bittiğini, modülün `customPolicies.add(...)` öğesini çağırdığını ve içe aktarmaların politika dosyasından çözümlendiğini doğrulayın. + Dosya adının `policies.js`, `policies.mjs` veya `policies.ts` ile bittiğini, modülün `customPolicies.add(...)` çağırdığını ve impoların politika dosyasından çözümlendiğini doğrulayın. ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -91,14 +91,14 @@ icon: "wrench" - + - - **Analyze → audits** bölümünü açın, çalıştırmayı seçin ve model analizi çalışıp çalışmadığını kontrol edin. Ardından kapsamı ve aralığını **Observe → sessions** ile karşılaştırın ve söz konusu popülasyondan temsilci izlemeleri açın. + + **Analyze → audits** açın, çalıştırmayı seçin ve model analizinin çalışıp çalışmadığını kontrol edin. Ardından kapsamını ve penceresini **Observe → sessions** ile karşılaştırın ve bu popülasyondan temsili izlemeleri açın. - Sıfır sonuç, yalnızca analiz başarıyla çalıştırıldığında anlamlıdır. Analiz atlanırsa veya başarısız olursa, çalıştırma sonuç üretmez ve analiz edilmemiş aralığı gelecekteki başarılı bir çalıştırma için açık tutar. Model analizi devre dışıysa, denetim de sonuç üretmez çünkü belirleyici kimlik bilgileri ve PII taraması istatistik kaydeder ancak artık sonuç oluşturmaz. + Sıfır sonuç yalnızca analiz başarıyla çalıştığında anlamlıdır. Analiz atlanırsa veya başarısız olursa, çalıştırma hiçbir sonuç üretmez ve analiz edilmeyen pencereyi gelecek başarılı bir çalıştırma için açık tutar. Model analizi devre dışıysa, denetim de sonuç üretmez çünkü belirleyici kimlik bilgisi ve PII taraması istatistik kaydeder ama artık sonuç yükseltmez. - ![Ortam, aracı, cadence ve tarama aralığının oturum popülasyonunu tanımladığı denetim formu.](/images/dashboard/audit-new.png) + ![Ortam, ajan, kadans ve tarama penceresini tanımlayan denetim formunun gösterimi.](/images/dashboard/audit-new.png) ```bash @@ -110,31 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - Çalıştırma sırada kalırsa, denetim aracı kapasitesini bekleyin veya denetim filosunu incelemesi için dağıtım operatöründen isteyin. Sıraya alınan bir denetim yeniden deneyin; hemen atlanmaz. + Çalıştırma sırada kalırsa, denetim-ajan kapasitesini bekleyin veya dağıtım operatörünün denetim filosunu incelemesini isteyin. Sırada bekleyen bir denetim yeniden denenir; hemen atlanmaz. - - Tamamlanmış bir oturumu açın ve manuel değerlendirmenin başarılı olup olmadığını kontrol edin. Barındırılan Bulut şu anda panoda değerlendirici uç nokta kontrolü yoktur; sunucu operatörü bunu yapılandırmalıdır. + + Tamamlanmış bir oturumu açın ve manuel değerlendirmenin başarılı olup olmadığını kontrol edin. Barındırılan Cloud şu anda dashboard'ta değerlendirici uç noktası kontrolü bulunmamaktadır; sunucu operatörü bunu yapılandırmalıdır. - Değerlendiricinin kendisini doğrulayın, ardından son değerlendirme durumlarını inceleyin: + Değerlendiriciyi doğrulayın, ardından son değerlendirme durumlarını inceleyin: ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - Kendi kendine barındırılan Bulut üzerinde, `EVALUATOR_ENDPOINT` sunucuda mevcut olduğunu ve `EVALUATOR_TOKEN` değerlendiricileri ile eşleştiğini doğrulayın. Uç nokta yoksa otomatik değerlendirme devre dışı bırakılır. + Kendi kendine barındırılan Cloud'da, sunucuda `EVALUATOR_ENDPOINT` bulunduğunu ve `EVALUATOR_TOKEN` ile eşleştiğini doğrulayın. Uç nokta olmadığında otomatik değerlendirme devre dışıdır. - + - - Kuruluş değiştiricisini kullanın ve CLI ile sonuçları karşılaştırmadan önce beklenen slug'ı ve izinleri doğrulayın. + + Kuruluş değiştiricisini kullanın ve CLI ile sonuçları karşılaştırmadan önce beklenen slug ve izinleri doğrulayın. ```bash @@ -143,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - API anahtarı modunda, `fp --org --api-key ...` belirtin veya `AGENTEYE_ORG` ayarlayın. Kaydedilen İnsan oturumu kuruluş durumu, API anahtarı istekleri için kasıtlı olarak yoksayılır. + API anahtarı modunda, `fp --org --api-key ...` belirtin veya `AGENTEYE_ORG` ayarlayın. Kaydedilen insan-oturum kuruluş durumu API anahtarı istekleri için kasıtlı olarak yoksayılır. - + - - **Observe → policy** bölümünü açın, kararı ve bağlantılı oturumu saklayın ve yanlış pozitif koşulunu tanımlayın. Ardından **Admin → enforcement** bölümünü açın ve etkilenen makineleri önceki sürüme geri alın. **Policy editor** bölümünde daha dar bir sürüm oluşturun, küçük bir kapsamda test edin ve geçerli çalışma başarılı olana kadar yalnızca genişletin. + + **Observe → policy** açın, kararı ve bağlantılı oturumu koruyun ve yanlış pozitif koşulu belirleyin. Ardından **Admin → enforcement** açın ve etkilenen makineleri önceki sürüme geri alın. **Policy editor** içinde daha dar bir sürüm oluşturun, küçük kapsamda test edin ve geçerli işlem başarılı olduktan sonra yalnızca genişletin. - Bulut dağıtımı geri alma yalnızca panoda kullanılabilir. Yerel oturum duraklatma, Bulut tarafından yönetilen politikaları devre dışı bırakmaz. Pano kullanılamıyorsa, makine ve dağıtım durumunu yakalayın ve engellenen işlemi tekrar tekrar yeniden denemek yerine pano erişimini geri yükleyin. + Cloud dağıtım geri alma yalnızca dashboard'dadır. Yerel oturum duraklatması Cloud tarafından yönetilen politikaları devre dışı bırakmaz. Dashboard kullanılamıyorsa, makine ve dağıtım durumunu yakalayın ve engellenen eylemi tekrar tekrar denemeyin yerine dashboard erişimini geri yükleyin. ```bash failproofai config --status @@ -164,4 +164,4 @@ icon: "wrench" -Desteğe başvururken CLI sürümü, başlık, ortam, ilgili oturum veya dağıtım kimliği ve gizli dizileri kaldırılmış `failproofai config --status` çıktısını ekleyin. \ No newline at end of file +Destek ekibiyle iletişim kurarken, CLI sürümü, çerçeve, ortam, ilgili oturum veya dağıtım ID'si ve gizli bilgiler kaldırılan `failproofai config --status` çıktısını ekleyin. \ No newline at end of file diff --git a/docs/tr/sessions/live-events.mdx b/docs/tr/sessions/live-events.mdx index 4e41b4659..e5b8d7a0f 100644 --- a/docs/tr/sessions/live-events.mdx +++ b/docs/tr/sessions/live-events.mdx @@ -1,21 +1,21 @@ --- title: "Canlı etkinlikler" -description: "Oturum çalışırken aracı etkinliğini gerçek zamanlı olarak izleyin." +description: "Oturum çalışırken aracı etkinliğini gerçek zamanlı izleyin." icon: "radio" --- -Canlı etkinlikler, enstrümantasyonunuzu doğrulamanıza ve oturumun bitmesini beklemeden riskli bir çalışmayı izlemenize yardımcı olur. +Canlı etkinlikler, enstrümantasyonu doğrulamak ve oturum bitmesini beklemeden riskli bir çalışmayı izlemenize yardımcı olur. -## Etkinliği izle +## Etkinliği izleyin - 1. **Observe → Events** bölümüne gidin. - 2. Verilerin geldiğini doğrulamak için mevcut zaman penceresiyle başlayın ve filtre kullanmayın. + 1. **Observe → Events** kısmına gidin. + 2. Verilerin geldiğini doğrulamak için geçerli zaman penceresiyle başlayın ve filtre uygulamayın. 3. Ortam, etkinlik türü, aracı veya oturum ile filtreleyin. Yük metni için aramayı kullanın. - 4. Bir etkinliği seçerek özet ve ayrıntılarını inceleyin. Tam trace için oturum bağlantısını izleyin. + 4. Bir etkinliği seçerek özeti ve ayrıntılarını inceleyin. Tam izleme için oturum bağlantısını takip edin. - ![Hermes sohbet ağ geçidinden gelen trafik ile kodlama-CLI çalışmalarını gösteren canlı Events akışı, zaman, ortam, etkinlik türü, aracı, model, bağlam ve oturuma göre filtrelenmiş.](/images/dashboard/events-stream-current.png) + ![Hermes sohbet ağ geçidinden gelen trafiği ve kodlama-CLI çalışmalarını gösteren, zaman, ortam, etkinlik türü, aracı, model, bağlam ve oturum ile filtrelenen canlı Etkinlikler akışı.](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +24,22 @@ Canlı etkinlikler, enstrümantasyonunuzu doğrulamanıza ve oturumun bitmesini fp --json events --full --session-id --all ``` - Varsayılan akış ham yüklemleri hariç tutar. `--full` seçeneğini yalnızca sınırlı bir oturum araştırması için kullanın. + Varsayılan akış ham yükleri hariç tutar. `--full` seçeneğini yalnızca sınırlı bir oturum incelemesi için kullanın. -Etkinlik akışını üç acil soruyu cevaplamak için kullanın: +Üç temel soruyu cevaplamak için etkinlik akışını kullanın: -- Beklenen aracı doğru ortama raporlama yapıyor mu? -- Model çağrıları, araç çağrıları ve ilke kararları sırayla geliyorlar mı? -- Oturum ilerleme yapmayı durdurdu mu veya bir işlemi tekrar etmeye başladı mı? +- Beklenen aracı doğru ortama raportu veriyor mu? +- Model çağrıları, araç çağrıları ve politika kararları sırada mı geliyor? +- Oturum ilerlemeyi durdurdu mu yoksa bir eylemi tekrarlamaya mı başladı? -Etkinlik türleri aracı yaşam döngüsü etkinlikleri, model istekleri ve yanıtları, araç kullanımı ve sonuçları, kancacık yürütme, insan bekletme ve kesintileri ve açık hatalar içerir. Korelasyon kimlikleri, araç çağrısı ve sonucu gibi eşleştirilmiş etkinlikleri birleştirir. +Etkinlik türleri aracı yaşam döngüsü etkinliklerini, model isteklerini ve yanıtlarını, araç kullanımını ve sonuçlarını, kanca yürütmesini, insan beklentilerini ve kesintilerini ve açık hataları içerir. Korelasyon kimlikleri araç çağrısı ve sonucu gibi eşleştirilmiş etkinlikleri birleştirir. - Yeni bir entegrasyonu doğrularken canlı görünümü geniş tutun. İlk etkinliği gördükten sonra filtreleri ekleyin; hatalı bir filtre başarısız alım gibi görünebilir. + Yeni bir entegrasyonu doğrularken canlı görünümü geniş tutun. İlk etkinliği gördükten sonra filtre ekleyin; yanlış bir filtre başarısız alımı izlenebilir hale getirebilir. -Hiçbir etkinlik görünmezse, `failproofai config --status` komutunu çalıştırın, ardından [alım sorunlarını giderin](/tr/reference/troubleshooting). +Hiçbir etkinlik görünmezse `failproofai config --status` komutunu çalıştırın, ardından [alımı giderin](/tr/reference/troubleshooting). -Desteklenen 12 [harness](/tr/reference/harnesses) türünden birinde çalışmayan aracılar, insan-döngüde-etkinlikleri (`human_wait`, `human_input`, `human_interrupt`) dahil olmak üzere aynı etkinlik türlerini [Python SDK](/tr/reference/custom-agents) aracılığıyla raporlar. Bu etkinlikler, ağ geçidi ve üretim aracılarının bağlı olduğu etkinliklerdir. \ No newline at end of file +Desteklenen 12 [harnisten](/tr/reference/harnesses) birinde çalışmayan aracılar, insan-döngüde etkinlikleri (`human_wait`, `human_input`, `human_interrupt`) dahil olmak üzere [Python SDK](/tr/reference/custom-agents) aracılığıyla aynı etkinlik türlerini raportar; bu etkinlikler ağ geçidi ve üretim aracılarının bağlı olduğu etkinliklerdir. \ No newline at end of file diff --git a/docs/tr/start/first-policy.mdx b/docs/tr/start/first-policy.mdx index fb16a3a02..5865214da 100644 --- a/docs/tr/start/first-policy.mdx +++ b/docs/tr/start/first-policy.mdx @@ -1,33 +1,33 @@ --- -title: "İlk başarısızlığı bir politika ile önleyin" -description: "Bir politika versiyonu yazın, gözlem modunda dağıtın ve ardından zorunlu kılın." +title: "İlk başarısızlığınızı bir ilke ile önleyin" +description: "Bir ilke sürümü yazın, gözlem modunda dağıtın ve ardından zorunlu kılın." icon: "shield-check" --- -Bir politikayı yalnızca güvenli olmayan eylem ile meşru olarak kalması gereken eylemleri tanımlayabildikten sonra kullanın. +Bir ilkeyi yalnızca güvensiz eylemi ve izin verilmesi gereken yasal eylemleri tanımlayabildikten sonra kullanın. - - **Admin → policy editor** bölümüne gidin. Demo politikasından başlayın, kaynağını gözden geçirin veya düzenleyin, ardından **publish version** seçeneğini seçin. Yayınlama, makinelere dağıtabileceğiniz değişmez versiyonunu oluşturur. + + **Admin → policy editor** adresine gidin. Demo ilkesiyle başlayın, kaynağını gözden geçirin veya düzenleyin, ardından **publish version** seçeneğini tıklayın. Yayınlama, makinelere dağıtabileceğiniz değişmez sürümü oluşturur. - ![Yayınlanmaya hazır bir demo politikası ile birlikte Policy editor compose görünümü.](/images/dashboard/policy-editor.png) + ![Demo ilkesi değişmez bir sürüm olarak yayınlanmaya hazır olan İlke editörü oluşturma görünümü.](/images/dashboard/policy-editor.png) - **Admin → enforcement** bölümüne gidin, hedef makineyi genişletin ve **edit this machine** seçeneğini seçin. Yayınlanmış demo politikasını ekleyin, versiyonunu sabitleyin, **observe** seçeneğini seçin ve dağıtımı uygulayın. + **Admin → enforcement** adresine gidin, hedef makineyi genişletin ve **edit this machine** seçeneğini tıklayın. Yayınlanan demo ilkesini ekleyin, sürümünü sabitleyin, **observe** seçeneğini seçin ve dağıtımı uygulayın. - ![Dağıtım uygulanmadan önce gözlem modunda seçilen yayınlanmış bir politika versiyonu ile birlikte makine dağıtım editörü.](/images/dashboard/enforcement-editor.png) + ![Yayınlanan bir ilke sürümü seçili olan makine dağıtım editörü, dağıtımı uygulamadan önce gözlem modunda.](/images/dashboard/enforcement-editor.png) - - Bu makinede yeni bir agent oturumu çalıştırın, ardından **Observe → policy** bölümünü açın. Makineyi seçin ve demo politikasının politika eşlemesi ve karar zaman çizelgesinde göründüğünü doğrulayın. Gözlem modu, politikanın eylemi bloklamadan ne yapacağını kaydeder. + + O makinede yeni bir agent oturumu çalıştırın, ardından **Observe → policy** açın. Makineyi seçin ve demo ilkesinin ilke eşlemesinde ve karar zaman çizelgesinde görüntülendiğini doğrulayın. Gözlem modu, ilkenin eylemi bloke etmeden ne yapacağını kaydeder. - ![Karar toplamları, zaman içinde zorlama aktivitesi ve yerel ve Cloud tarafından yönetilen politika eşlemelerini gösteren Policy sayfası.](/images/dashboard/policy-observe.png) + ![Karar toplamlarını, zaman içinde zorlama etkinliğini ve yerel ve Bulut tarafından yönetilen ilke eşlemelerini gösteren İlke sayfası.](/images/dashboard/policy-observe.png) - Cloud politika yazarlığı ve filo dağıtımı idari iş akışlarıdır. Yayınlamadan önce aynı politikayı doğrulamak için yerel CLI'yı kullanın: + Bulut ilkesi yazımı ve filo dağıtımı yönetimsel iş akışlarıdır. Yayınlamadan önce aynı ilkeyi doğrulamak için yerel CLI'yi kullanın: ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -35,13 +35,13 @@ Bir politikayı yalnızca güvenli olmayan eylem ile meşru olarak kalması gere failproofai config --status ``` - Cloud tarafında görünen politika kararlarını incelemek için `fp` kullanın: + Bulut tarafından görünen ilke kararlarını incelemek için `fp` kullanın: ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - Cloud CLI, yalnızca root'a ait zorlama dağıtım rotalarını sunmaz. **Admin → policy editor** bölümünden versiyonları yayınlayın ve **Admin → enforcement** bölümünden dağıtın. + Her iki adım da CLI'den kullanılabilir: `fp policies publish ` bir sürüm oluşturur ve `fp fleet deploy --add ` bunu bir makineye yerleştirir. Dashboard eşdeğerleri **Admin → policy editor** ve **Admin → enforcement** adreslerdir. \ No newline at end of file diff --git a/docs/tr/start/integrations.mdx b/docs/tr/start/integrations.mdx new file mode 100644 index 000000000..6ac09d5f4 --- /dev/null +++ b/docs/tr/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "Ajanınızı enstrüman edin" +sidebarTitle: "Frameworks" +description: "Desteklenen herhangi bir ajan çerçevesini Failproof AI'ye tek bir çağrıyla bağlayın." +icon: "plug" +--- + +Ajanınız zaten kaydedilmeye değer her şeyi üretir — model çağrıları, araç çağrıları, düğüm sınırları, insan beklentileri, hatalar. Çerçeve bunu atar. SDK onu tutar. + + + + Kendiniz yazdığınız bir ajan ya da burada listelenmemiş bir ajan. + + + Grafikler, düğümler, araçlar, alıcılar, modeller. + + + Ekipler, akışlar, role göre ajanlar, araçlar. + + + İş akışları, adımlar, fonksiyon ajanları, alıcılar. + + + Yazılı ajanlar, yetenekler, araçlar, yeniden denemeler. + + + +## Hangi çerçeve olursa olsun üç satır + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # içe aktardığınız çerçeveleri algılar + +with failproofai_sdk.session(): + ... # mevcut ajan çağrınız, değişmemiş +``` + +Fonksiyonlarınız üzerinde dekoratör yok, çağrılarınıza iletilen geri arama yok, kodunuzda iliştirilmiş kimlikler yok. Yalnızca oturum içindeki çağrı farklı: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # `async with failproofai_sdk.session():` altında + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +Ekstra yükleme **çerçeveyi** kurar. Her adaptör temel wheel'de gönderilir, bu nedenle zaten çerçevesi olan bir proje hiç ekstraya ihtiyaç duymaz. + +## Geldiğini kontrol edin + +Bir enstrüman edilmiş oturumu çalıştırın, ardından **Observe → Sessions** açın ve ortamınızı seçin. Çalıştırma yeniden oluşturulmuş bir iz olarak görünür. + +Hiçbir şey gelmezse, makinenin `failproofai config --status` ile bağlı olduğunu doğrulayın. Bkz. [Yakalamayı ayarlayın](/tr/start/setup). + + + Teslimatı doğrulamak için spool dizinini kontrol etmeyin. Failproof daemon her bir toplu işi milisaniyeler içinde toplar ve siler, bu nedenle onu okumak toplayıcı ile yarışır ve yayılan olaylardan çok daha azını gösterir. + + +## Sonraki adım + +Yukarıdaki her hızlı başlangıç, tam kılavuzuna bağlantı verir — neler kaydedilir, seçenekler, akış, açıklık adlandırması ve insanların gerçekten karşılaştığı sorunlar. Bunlar **Trace Agents → Ajanınızı bağlayın** altında bulunur. + + + + Veri modeli, kimlikler, olay türleri ve olayların Cloud'a nasıl ulaştığı. + + + Bağlantısız günlüklerin yerine bir oturum aracılığıyla nedenselliği takip edin. + + + Az önce yakaladığınız oturumları denetleyin. + + \ No newline at end of file diff --git a/docs/tr/start/integrations/crewai.mdx b/docs/tr/start/integrations/crewai.mdx new file mode 100644 index 000000000..b632d678f --- /dev/null +++ b/docs/tr/start/integrations/crewai.mdx @@ -0,0 +1,224 @@ +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "Ekipleri, akışları, aracıları role göre, araçları, belleği ve insan geri bildirimini instrumentalize edin." +icon: "/images/frameworks/crewai.svg" +--- + +## Kurulum + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +Desteklenen: `crewai` 1.13 ile 2.0. 1.13, `started_event_id` ekleyen ve token kullanımını normalleştiren sürümdür; bu ikisi de adaptörün olayları eşleştirmesi ve tokenları raporlaması için gereklidir. + +## Instrumentalizasyon + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()`, CrewAI'ın modül düzeyindeki olay otobüsüne bir dinleyici kaydeder ve her olay sınıfı için bir işleyici abone olur. Ekibiniz, aracılarınız, görevleriniz veya araçlarınız hakkında hiçbir şey değişmez. + +## Kayıt edilen öğeler + +| CrewAI | Failproof olayı | +| --- | --- | +| Crew kickoff | `agent_start`, `agent_end` | +| `Agent.kickoff()` (hafif bir aracı, ekip yok) | `agent_start`, `agent_end`, rolden gelen `agent_id` ile | +| Akış başlangıcı ve bitişi | `agent_start`, `agent_end`; bir akış yöntemi içinde devreye alınan ekip bunun altında iç içe geçer | +| Aracı yürütülmesi | İç içe geçmiş `agent_start`, `agent_end`, rolden gelen `agent_id` ile. Hiyerarşik bir süreç altında devredilen bir çalışma arkadaşı yöneticinin yanında değil, altında iç içe geçer | +| Görev | Hiçbir şey; çocuklar ekibe çözülenecek şekilde bir bağlantı olarak kaydedilir | +| Akış yöntemi, güvenlik önlemi | `hook_triggered`, `hook_completed` | +| Araç kullanımı | `tool_use`, `tool_result` | +| Bellek ve bilgi işlemleri | `tool_use`, `tool_result`, ulaşılan yüzey için adlandırılmış | +| LLM çağrısı | `model_request`, `model_response`, token kullanımı ile | +| Akış parçası | Yanıta katlanır, parça sayısı ve ilk tokena kadar olan süre | +| İnsan geri bildirimi istendi | `human_wait`, `agent_pause` | +| İnsan geri bildirimi alındı | `agent_resume`, `human_input` | +| Aracı yürütme hatası | `error`, ardından `agent_end` ve sonuç `failed` ile | + +Bir görev kasıtlı olarak hiçbir şey yayınlamaz. CrewAI görevi, onu çalıştıran aracı yürütülmesinin bir alt kümesidir, bu nedenle her ikisini de yayınlamak her satırı ikiye katlar ve bunları kardeş olarak render eder. Görev kimliği ve adı aracının kendi olaylarında yer alır. + +Bellek ve bilgi işlemleri, ulaştıkları yüzey için adlandırılan araçlar olarak kaydedilir, böylece gerçek araçlarınızın yanında görünür ve gecikme sürelerini karşılaştırabilirsiniz. + +Hiyerarşik bir ekipte, iç içe geçme izlemeyi okunabilir kılan şeydir: + +```text +crew +└─ manager + ├─ researcher devredilen + └─ writer devredilen +``` + +CrewAI, devredilen bir yürütmeyi yöneticinin doğrudan üzerine değil, `delegate_work_to_coworker` **araç olayının** üzerine yerleştirir, bu nedenle adaptör bu bağlantıyı izler. Bunu olmadan her aracı diğerinin kardeşi olarak çıkar ve delegasyon yapısı kaybedilir. + +## Örnek + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """İşletme metriğini ada göre ara. Geçerli: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # agent_id olur + goal="önemli olan sayıları çekip açık şekilde belirt", + backstory="Yaşamını gösterge tablolarını okuyarak geçirirsin.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="sayıları bir yönetici tarafından okunacak üç satıra dönüştür", + backstory="Yönetim kurulu güncelleme yazarsın. Hiçbir zaman dolgu eklemezsin.", + llm=MODEL, +) + +gather = Task( + description="Araç ile 'revenue' ve 'churn' ara.", + expected_output="İki satır, her biri bir metrik.", + agent=analyst, +) +summarise = Task( + description="Yukarıdaki metrikler kullanarak üç satırlık bir yönetim özeti yaz.", + expected_output="Tam olarak üç satır.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +İzlemede devir görünür: `analyst` aralığı kapanır, `writer` aralığı açılır ve her ikisi de bir `crew` aralığı içinde oturur. + +## Aralıklarınızı adlandırın + +`agent_id` `Agent(role=...)` adresinden gelir; bu, onu okunabilir bir pano yönü yapar. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # çalıştırma başına bir yönü girişi +``` + +`agent_id` düşük kardinaliteli bir sütundur. Bir UUID veya zaman damgası içeren rol, her çalıştırılan sorgu için bunu kötüleştirir. Bir rol kimliğe benzerse, adaptör bunu reddeder ve gerçek değeri bunun yerine bir yük alanına koyar. + +## Oturumu kontrol edin + +Bu sırada çözümlenir, ilk eşleşme kazanır: + +1. `instrument("crewai", session_id=...)` +2. Çevreleyen `failproofai_sdk.session()` kapsamı +3. Üretilen `uuid4().hex`, ekip veya akış başına bir kez + +Kickoff'u çalıştırma başına kontrol etmek için sarmalayın: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## Seçenekler + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # her çalıştırmayı bir oturum kimliğine sabitle +) +``` + +`session_id` bu adaptörün okuduğu tek seçenektir. İstemler ve tamamlamalar her zaman kaydedilir, yük bütçesine kesilir. + +## İnsan katılımı + +CrewAI'ın **iki** insan katılımı yüzeyi vardır ve her ikisi de aynı dört olay olarak kaydedilir. + +Bir akış yöntemi üzerindeki `@human_feedback` CrewAI'ın olay otobüsünden geçer: çalışma zamanı bir olayı bir kişiye bloke olmadan önce ve cevaptan sonra başka bir olay yayınlar. + +`Task(human_input=True)` değil. CrewAI'ın kendi giriş sağlayıcısı içinde `input()` çağırır ve hiçbir türde olay yayınlamaz, bu nedenle adaptör bu sağlayıcıyı doğrudan sarmalayarak — bunu olmadan tüm insan bekleme süresi görünmez ve etkin aracı zamanı olarak faturalandırılır. + +Her iki durumda da şunları alırsınız: + +```text +human_wait istem ve seçenekleri +agent_pause duraklatılan zaman saatini başlatır +agent_resume bunu durduruyor +human_input cevap, bekleme ölçülür +``` + +`agent_pause` ile `agent_resume` arasında, pauzlanmış zamanı besleyen tek çifttir. Bunu olmadan on dakikalık bir insan bekleme süresi on dakika etkin aracı zamanı olarak faturalandırılır. + + + CrewAI her iki insan geri bildirimi olayında da korelasyon kimliği ayarlamaz, bu nedenle adaptör bunları akış ve yöntem adında eşleştirir, en yakın açılan duraklamaya geri döner. Bu sesli çünkü konsol istemi bloke olur. Eş zamanlı bir geri bildirim sağlayıcısı inşa ederseniz, her iki olaya da `request_id` ayarlayın. + + + + `Task(human_input=True)` yolu bir olay aboneliği yerine CrewAI'ın giriş sağlayıcısı etrafındaki bir sarmalayıcı olduğundan, `uninstrument()` üzerinde geri yüklenir ve `input()` ne yükselirse `KeyboardInterrupt` de dahil olmak üzere değiştirilmeden yeniden yükseltir. + + +## Yaygın sorunlar + + + + Bir `role` UUID, zaman damgası veya çalıştırma başına son ek içerir. Sabit bir insan rolü kullanın ve çalıştırmaya özgü kimliği bunun yerine görev açıklamasına koyun. + + + + Olay otobüsü zaman uyumsuztur ve `kickoff()` son işleyiciler çalışmadan önce geri döner. Önce bunu boşaltın: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + Bu CrewAI'ın bir özelliğidir, SDK'nın değil. + + + + `agent_end` açık duraklamaları kapatan güçle kapatır ama araçları veya modelleri değil, bu nedenle bir araç çağrısı içinde ölen bir çalıştırma o aralığı açık bırakır. Normal temizleme hala açık olanları kapatır ve eksik olarak işaretler. Sadece `SIGKILL` bunu asılı bırakır, çünkü hiçbir şey çalıştırılamaz. + + + + Bu sırada kontrol edin: `instrument()` `kickoff()` öncesinde çalıştırıldı; `with failproofai_sdk.session():` etrafında bir tane var; `crewai` 1.13 veya daha yeni; `FAILPROOFAI_SDK_STRICT=1` ayarlanmış, bu nedenle kötü bir kancası yutulmak yerine yükseltir. + + + +## İleri + + + + Çiftler, kimlikler, oturum yaşam döngüsü ve teslimat. + + + Az önce yakaladığınız oturumda nedenselliği takip edin. + + + LangGraph, LlamaIndex, Pydantic AI ve özel aracılar. + + \ No newline at end of file diff --git a/docs/tr/start/integrations/custom-agents.mdx b/docs/tr/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..b091505d0 --- /dev/null +++ b/docs/tr/start/integrations/custom-agents.mdx @@ -0,0 +1,737 @@ +--- +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" +--- + +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 onun üzerinde çeviri tablolarıdır. + +## Yükleme + +```bash +pip install failproofai-sdk +``` + +Ek paket yok, bağımlılık yok. + +## Enstrümantasyon + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # bir çalışma + with failproofai_sdk.agent("planner"): # bir iş birimi + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) # bir araç çağrısı +``` + +Baştan sona okuyun, söylediği şey budur: + +| Bunu sarın | Demek için | +| --- | --- | +| `session()` | Bu olaylar aynı çalışmaya ait | +| `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 aslında neyi 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 | + +İç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. + +Üçü de `async with` ve `with` altında çalışı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(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## Bir kapsam nasıl kapanır + +`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` | + +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ı 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 | +| --- | --- | --- | --- | +| **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` | +| **Hatalar** | — | — | `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ı. + + + +```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="onay beklemede") +failproofai_sdk.event.agent_resume(pause_id="p1") +``` + +```python Modeller +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```python Araçlar +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 Kancalar +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 İnsanlar +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="operatör çalışmayı duraklatttı", user_id="dana") +failproofai_sdk.event.human_interrupt(reason="operatör çalışmayı durdurdu", at_step="step_3") +``` + +```python Hatalar +failproofai_sdk.event.error( + error_type="TimeoutError", + message="sağlayıcı 30 saniye sonra zaman aşımına uğradı", + traceback="...", +) +``` + + + + **İki insan ailesi zıt yönleri gösterir.** + + | 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ı | + + 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ı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şı araç çağırma döngüsü, ajan çerçevesi olmadan: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +MODEL = "gpt-4o-mini" + + +def turn(messages: list): + """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 + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +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ı + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +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ılmaz. + +```python +# asyncio: yapılacak bir şey yok +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# 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, 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çeveyi enstrümante edin + +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. + +| 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 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: + call.output = original(**args) + ``` + + + ```python + failproofai_sdk.event.model_request(model=model, messages=messages) + reply = provider.complete(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **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ş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 vardır ve yukarıdaki üç bağlantı noktası her ikisine de cevaptı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. + + Bağlantı noktalarını elle harita yaparak, sevk edilen bir adaptörün yaptığı aynı fidelitede aynı olayları kaydeder. + + +## Daha derine gitme + +Kaydın aslında nasıl çalıştığı. Başlamak için buna ihtiyaç yoktur. + + + + + +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 + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + C --> E(["agent_end"]) +``` + +**Çift** birimdir. Her kapatma olayı SDK'nın açma olayından ölçtüğü bir süre 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. + + + + ```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 çıkış-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 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. + + + + ```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 çı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 çıkış-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. + + + + ```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 çı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 iterasyon + 26 +7.038s agent_end Agent · success + ``` + + Ajan döngüsü kendisi görünür, yalnızca model çağrıları değil. + + + + ```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 çı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 çıkış-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. + + + + ```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 çıkış-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. + + + + + + + +**Oturum sonu olayı yoktur.** Oturum kapattığınız bir şey değil — `session_id` paylaşan bir olay grubudur. + +Durum izlemenin şeklinden türetilir: + +| Durum | Ne zaman | +| --- | --- | +| `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ı | + +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 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ırsa, çevreleyen kapsamdan çözülürler: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + 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. + +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 tarafından basım yapılır + +| Kimlik | Basım yapan | 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 | + +#### Adaptörler `session_id` nasıl çözer + +İ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ı +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. + +#### `agent_id` düşük kardinaliteyi koruyun + +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 | Kaydedilmiş olarak | 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 | +| `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. + + + **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 | +| --- | --- | +| 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` | +| Hatalar | `error` | + +Hangi çerçeve neyi kaydeder, yukarıdaki çalışmalardan ölçülen: + +| Olay | LangGraph | CrewAI | LlamaIndex | Pydantic AI | Özel | +| --- | :--: | :--: | :--: | :--: | :--: | +| 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 | +| Kancanın tetiklenmesi ve tamamlanması | 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 | + +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 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 | +| --- | --- | --- | +| `agent_start` | `agent_end` | `outcome`, `summary` | +| `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üğü | + + + 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. 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` 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() # 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ı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` 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 içe aktarıldı +failproofai_sdk.instrument("crewai") # tam olarak bir, adıyla +failproofai_sdk.uninstrument("crewai") # geri koyun +``` + +| Ad | Ayrıca kabul eder | +| --- | --- | +| `langchain` | `langgraph`, `langchain_core` | +| `crewai` | — | +| `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: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +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. + + 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 yüzden işleminiz başlamadan önce bunu dışa aktarın, çalışma sırasında ayarlamak yerine. + + + + **`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'da 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 failproofai_sdk + +failproofai_sdk.instrument() # onu bulur -> ('langchain',) +``` + +```python Doğru, sıra-kanıtlı +import failproofai_sdk + +# 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ış 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["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ışır | +| --- | --- | --- | +| 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 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 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 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. + + +Daemon **gönderir** topluları. Açmaz veya yeniden yazmaları yapmaz. + +| Olaylar | Tarafından yazılan | `collector.redact` tarafından redakte mi? | +| --- | --- | --- | +| CLI oturum transkriptleri | Daemon | Evet | +| Kancanın aktivitesi | Daemon | Evet | +| **SDK'nin yayınladığı her şey** | **İşleminiz** | **Hayır** | + +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. + + + **Yüklemeleri kaynakta kontrol edersiniz, iki yerde:** + + - 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 — **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 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. + + + + **Boş bir makara dizini sağlıklı durumdur.** Teslimi 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. + +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 ç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 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ğ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. + + + + + +## 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. + + + + 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ığı 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 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 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. + + + +## Sonraki + + + + Çiftler, kimlikler, oturum yaşam döngüsü ve teslim. + + + Az önce yakaladığınız oturum aracılığıyla nedenselliği takip edin. + + + LangGraph, CrewAI, LlamaIndex ve Pydantic AI. + + \ No newline at end of file diff --git a/docs/tr/start/integrations/langchain.mdx b/docs/tr/start/integrations/langchain.mdx new file mode 100644 index 000000000..ab2b48b0b --- /dev/null +++ b/docs/tr/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain ve LangGraph" +sidebarTitle: "LangChain ve LangGraph" +description: "Grafları, düğümleri, araçları, alıcıları ve model çağrılarını tek bir çağrı ile izleyin." +icon: "/images/frameworks/langchain.svg" +--- + +Bir adaptör her ikisine de hizmet verir. LangGraph, `langchain-core`'ün geri çağrı yöneticisinde çalışır, bu nedenle birini izlemek diğerini de izler. + +## Kurulum + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +LangGraph olmadan LangChain için `failproofai-sdk[langchain]` kullanın. + +Desteklenen sürümler: `langchain-core` 1.4.7 ile 2.0, `langgraph` 1.2 ile 2.0 arası. Bu aralık dışında adaptör yine de kurulur ve bir kez uyarı verir. + +## İzleme Yapılandırması + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` bir izleyiciyi `langchain_core.tracers.context.register_configure_hook` aracılığıyla kaydeder. LangChain bunu inşa ettiği her geri çağrı yöneticisine enjekte eder, bu nedenle grafikler, araçlar ve modeller bir çağrı sitesini değiştirmeden yakalanır — yazmadığınız kütüphanelerin içindekiler de dahil olmak üzere. + +## Kaydedilen Veriler + +| LangChain veya LangGraph | Failproof olayı | +| --- | --- | +| Kök çalıştırma | `agent_start`, `agent_end` | +| LangGraph düğümü | `hook_triggered`, `hook_completed` | +| Derlenmiş alt grafik | İç içe `agent_start`, `agent_end` | +| Araç çalıştırması | `tool_use`, `tool_result` | +| Alıcı çalıştırması | `tool_use`, `tool_result`, özet çıktı | +| Chat modeli veya LLM çalıştırması | `model_request`, `model_response`, token kullanımı ile | +| Akışlı jetonlar | Yanıta chunk sayısı ve ilk jetonun zamanı olarak katlanır. Token sayıları `ChatOpenAI(stream_usage=True)` gerektirir — aşağıyı görebilir | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, `Interrupt.id` üzerinde bağlantılı — resume aynı kontrol noktası üzerinde farklı bir işlemde gerçekleştiğinde bile | +| İşlenmemiş istisna | `error`, ardından sonuç `failed` olan `agent_end` | + +**Bir düğüm, iç içe bir ajan değil, bir hook haline gelir.** `agent_id` her pano yüzeyindeki birincil yöntemdir — `retrieve`, `grade_documents` ve `should_continue` ajanlarına yükseltmek bunu boğar ve oturumu hangi düğümün ilk çalıştığına göre etiketlerdi. + +Hook aralıkları aynı şekilde görünür ve yine de size düğüm başına gecikme görünümü sağlar. + + + **Düğümlerinizi istediğiniz gibi adlandırın.** Bir düğümün çalıştırması, adı tarafından değil, *şekli* tarafından tanımlanır — LangGraph'ın kendi adım etiketini taşıyan yaprak olmayan bir çalıştırma. + + +| Yazdığınız | Kaydedilen | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | Araç | +| `add_node("ChatOpenAI", ...)` | Model çağrısı | + +Bir düğümü çalıştırdığı şeyin adını verdikten sonra o şeyin olaylarının kaybolması. Artık bu şekilde değil. + +### Akış + +`.stream()` ve `.astream()` jetonbaşı olay yayınlamaz. Bunlar kapanış `model_response` içine katlanır: + +| Alan | İçeriği | +| --- | --- | +| `fw_chunks` | Kaç chunk geldi | +| `fw_ttft_ms` | İlk jetona kadar zaman | + +### Akışlı yanıttaki token sayıları + +Ayrı bir konu ve kaçırması kolay: OpenAI akışlı yanıtta kullanımı **sadece istendiğinde** gönderir. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # bunu olmadan, token yok +``` + +Adaptör çerçevenin verdiğini kaydeder. Bu bayrak olmadan kaydedilecek bir şey yoktur ve `model_response` token sayıları olmadan gelir. + +## Örnek + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Bir öğenin birim fiyatını USD cinsinden döndürün.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Şu anda stokta olan bir öğenin birimlerini döndürün.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## Aralıklarınızı Adlandırın + +Varsayılan olarak kök aralık grafiğin kendi adını alır. Seçtiğiniz bir etiketi almak için sarın: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +Çok ajanla kurulumlar için kapsamları iç içe geçirin. Her çalışan `parent_id` taşıyan bir alt aralık haline gelir: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +`agent_id` kardinalitesini düşük tutun. Bir rol veya düğüm adı kullanın, asla UUID veya çalıştırma başına bir dize kullanmayın. + +## Oturumu Kontrol Edin + +Oturum kimliği bu sırayla çözümlenir, ilk eşleşme kazanır: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. Kapsayan `failproofai_sdk.session()` kapsamı +4. `metadata["session_id"]`, `metadata["conversation_id"]` veya `metadata["thread_id"]` +5. Kök çalıştırma kimliği + +Hiçbir zaman sıfırdan oluşturulmaz, çünkü sentezlenmiş bir kimlik bir çalıştırmayı birkaç oturum arasında böler. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## Seçenekler + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # her çalıştırmayı bir oturum kimliğine sabitle + include_chains=set(), # ara zincirlerine hook çiftleri olarak izin ver + capture_content=True, # False yönergeleri ve tamamlamaları yüklerden bırakır + graph_callbacks=True, # birinci sınıf kesme ve devam, langgraph 1.2+ gerektirir +) +``` + +Düzenlenmiş veriler için `capture_content=False` ayarlayın. Yapı, zamanlamalar, token sayıları, araç adları ve sonuçlar hala kaydedilir; mesaj gövdeleri değil. + +`include_chains` **sadece iç içe** çalıştırmalara uygulanır. Üst düzeyde çağırdığınız bir runnable oturumun köküdür, bu nedenle hook çiftine değil ajan aralığına dönüşür ve adını buraya vermek hiçbir etkisi olmaz. + +## İnsanın Döngüde Olması + +`interrupt()` dört olay üretir ve hiçbir çift gereksiz değildir: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +`human_wait` ile `human_input` arasında istem ve cevap taşınır (her ikisi de `capture_content=False` altında, alıcı belge kaynakları ile birlikte bırakılır — belge sayısı kalır). `agent_pause` ile `agent_resume` duraklatılan zamanı besleyen tek çifttir, bu nedenle onsuz on dakikalık bir insan bekleme etkin ajan süresi olarak faturalandırılır. Kök aralık boşluk arasında açık kalır ve her iki çağrıyı da bir oturumda tutar. + +## Yaygın Sorunlar + + + + `create_react_agent` istisnayı yayınlar. Modelin hatayı görmesine ve devam etmesine izin vermek için araç düğümünü açıkça oluşturun: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + Hata her iki durumda da bir hata içeren `tool_result` olarak kaydedilir. Bu sadece çalıştırmanın bundan kurtulup kurtulamayacağını belirler. + + + + Herhangi bir grafik dışında doğrudan `llm.invoke()` üst çalıştırmaya sahip değildir, bu nedenle kök aralığı açar ve model çiftini içine yayınlar. Pano yapraklarını açık bir ajana ebeveynle alır, bu nedenle aralık kasıtlıdır. Adlandırın: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + `config={"callbacks": [...]}` içinde bir Failproof işleyicisi geçtiniz ve aynı zamanda `instrument()` çağırdınız. Bunu kaldırın. Configure hook zaten işlemdeki her geri çağrı yöneticisini kapsar. + + + + Değil. LangGraph `GraphInterrupt` oluşturur gerçek bir istisna ile aynı yol üzerinden, bu nedenle her duraklama izleyiciye bir hata geri çağrısı olarak ulaşır. `GraphBubbleUp` alt sınıfından herhangi biri kontrol akışı yerine işlem yapılır, bu nedenle bir onay kırmızı bir hata boyaması yapmaz. + + + + Bu sırayla kontrol edin: `instrument()` grafik yürütülmeden önce çalıştı; çağrının çevresinde bir `with failproofai_sdk.session():` vardır; `FAILPROOFAI_SDK_STRICT=1` ayarlı, bu nedenle bozulmuş bir hook yutulmak yerine yükseltilir. + + + +## Sonraki + + + + Çiftler, kimlikler, oturum yaşam döngüsü ve teslimat. + + + Az önce yakaladığınız oturum aracılığıyla nedenselliği takip edin. + + + CrewAI, LlamaIndex, Pydantic AI ve özel ajanlar. + + \ No newline at end of file diff --git a/docs/tr/start/integrations/llamaindex.mdx b/docs/tr/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..ab8bc34e6 --- /dev/null +++ b/docs/tr/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "İş akışlarını, adımları, fonksiyon aracılarını ve alıcıları enstrüman haline getirin." +icon: "/images/frameworks/llamaindex.svg" +--- + +## Yükleme + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +Desteklenen: `llama-index-core` 0.14.23 ila 0.15. 0.14.23, iş akışı akışının bu adaptörün okuduğu yazılı aracı olaylarını taşımaya başladığı sürümdür. Bunun altında, model adları ve aracı yapısı her ikisi de kaybolur. + +## Enstrümantasyon + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +LlamaIndex'in aracı API'si asenkrondur. Her kapsam `async with` ve `with` altında çalışır ve aynı olayları üretir. + +`instrument()`, bir olay işleyicisi ve bir kapsam işleyicisini LlamaIndex'in genel dağıtıcısına bağlar. Birlikte aracı döngüsünü görünür hale getirirler, sadece model çağrılarını değil. + + + LLM'nizdeki bir ekstra argüman olmadan, izlemenizdeki her token sayısı null olur. Aşağıdaki [Token sayıları](#token-sayıları) bölümüne bakın. + + +## Token sayıları + +`FunctionAgent`, `astream_chat` çağrısı yapar ve `llama-index-llms-openai` akış yaparken `stream_options={"include_usage": True}` göndermez. Sağlayıcı bu nedenle kullanım yığınını asla göndermez ve herhangi bir enstrümantasyonun okuması için bir şey yoktur. + +Bu, yukarı akış LlamaIndex davranışıdır. LLM'nizdeki şunu seçin: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +Aynı çalışma ve model üzerinde ölçüldü: + +| | Giriş token'ları | Çıkış token'ları | +| --- | --- | --- | +| Olmadan | `null` | `null` | +| İle | 148 | 17 | + +Akışlı olmayan çağrılar (`llm.chat`, `llm.achat`) yapılandırma olmadan kullanımı bildirir. Sadece varsayılan aracı yolu olan akış yolu buna gerek duyar. + +## Kaydedilen şeyler + +| LlamaIndex | Failproof olayı | +| --- | --- | +| `Workflow.run` kök kapsamı | Session, `agent_start`, `agent_end` | +| İç içe `Workflow.run` kapsamı | İç içe `agent_start`, `agent_end` | +| İş akışı adımı kapsamı | `hook_triggered`, `hook_completed` | +| LLM sohbet başlangıcı ve sonu | `model_request`, `model_response` | +| `FunctionTool.call` kapsamı | `tool_use`, `tool_result` | +| Alım başlangıcı ve sonu | `tool_use`, `tool_result`, çıkış özetlendi | +| Gömme işlemleri | Hiçbir şey, `embeddings=True` olmadıkça | +| Bir aracı kişi beklerken | `human_wait`, `agent_pause`, sonra `agent_resume`, `human_input` | +| `AgentWorkflow` devretme | İş akışına üst öğe olan aracı başına bir iç içe `agent_start`, `agent_end` | +| İstisna | `error`, sonra sonuç `failed` olan `agent_end` ve bunu adlandıran `agent_end.summary` | +| `handler.cancel_run()` | Sonuç `cancelled` olan `agent_end` ve `error` olmadan — bir durdurma düğmesi başarısızlık değildir | + +`agent_id`, bir tane ayarladığınızda `FunctionAgent.name` ve aksi takdirde iş akışı sınıf adıdır. `AgentWorkflow` altında, sıra alan her aracı iş akışı altında kendi iç içe kapsamını alır, bu nedenle bir devretme iki aracı olarak okunur. + +Alım çıkışı dökülen yerine özetlenir. Bir alıcı belgeler döndürür ve bunları yüklemede depolamak, sorgu başına bir kez külliyatınızı olaylar mağazasına koyar. Sayı, skor aralığı ve kısaltılmış parçacıklar bunun yerine tutulur. + +## Örnek + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +Aracı döngüsü izlemede kanca çiftleri olarak görünür: `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool` ve `aggregate_tool_results`. Bunlar çerçevenin kendi döngüsüdür, bu nedenle aracılar yerine kanca olması `agent_id` anlamlı tutar. + +## Kapsamlarınızı adlandırın + +`agent_id`, bir tane ayarladığınızda `FunctionAgent.name` ve aksi takdirde iş akışı sınıf adıdır. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +`AgentWorkflow` içinde, bu ad aynı zamanda her devretmenin kaydedildiği şeyin de adıdır: + +```text +AgentWorkflow üst span +├─ city_analyst tur 1 +├─ cost_analyst tur 2 +└─ city_analyst tur 3 — yeni bir tur, yeniden açılmış değil +``` + +Bu nedenle `agent_id` size **hangi aracının** işi yaptığını ve `parent_id` **hangi iş akışına** ait olduğunu söyler. Daha sonra kontrol geri veren bir aracı ilk turunu yeniden açmak yerine ikinci bir tur açar. + +Geçersiz kılmak için veya birkaç aracıyı tek bir üst öğe altında gruplandırmak için sarın: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +`agent_id` düşük kardinalitenin tutun. Her pano yüzeyinde birincil fasettir, bu nedenle bir rol veya iş akışı adı kullanın, asla UUID veya çalışma başına dize kullanmayın. + +## Oturumu kontrol edin + +Bu adaptör **`session_id` seçeneği almaz**. Oturum kapsayan kapsamdan gelir, aksi takdirde iş akışı çalışması başına oluşturulan `uuid4().hex` dir: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## Seçenekler + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True, gömme çağrılarını kanca çiftleri olarak kaydeder + steps=True, # False, iş akışı-adımı kanca çiftlerini bırakır + capture_messages=True, # False, HER yükü bırakır: istemler, tamamlamalar, + # araç bağımsız değişkenleri ve çıkışı, adım G/Ç, alım + # sorguları, hedefi ve nihai yanıtı + capture_limit=8192, # yakalanan değer başına tutulan karakterler + stale_after=600.0, # terkedilmiş bir LEAF'i zorla kapatmadan önceki saniyeler + reaper_interval=30.0, # orakçı ne sıklıkla temizlenir; 0 onu devre dışı bırakır +) +``` + +| Seçenek | Neden değiştirirsiniz | +| --- | --- | +| `embeddings` | Yalnızca gömme gecikme süresi veya maliyetinde hata ayıklama yapılırken açın. Toplu bir dizin oluşturması binlerce çağrıdır ve zaman çizelgesini gömecektir. | +| `steps` | Yalnızca model ve araç olaylarını istiyorsanız ve aracı döngüsünü gürültülü bulursanız kapatın. | +| `capture_messages` | Düzenlenmiş veriler için kapatın. Her yük kaydedilmeyi bırakır — istemler, modelin tamamlaması, araç bağımsız değişkenleri ve dönüş değerleri, iş akışı-adımı giriş ve çıkışı, alım sorguları, aracının hedefi ve nihai yanıtı. Yapı, zamanlamalar, jetonlar ve sonuçlar hala kaydedilir. | +| `capture_limit` | Kesilmeden önce yakalanan değer başına tutulan karakterler. RAG istemi veya alınan içerik kırpılmış geldiğinde bunu yükseltin. | +| `stale_after` | Terkedilmiş **yaprak** — hiç kimsenin tüketmediği bir akış yanıtı, kapatılması hiç gelmeyen bir model veya araç kapsamı — zorla kapatılmadan önceki saniyeler, böylece oturum çözülür ve `ongoing` sonsuza kadar okunur. Bu, terkedilmiş bir çalışmanın kendisini kapatmaz: görev görevi gözlemci bir çıkış görmeden iptal edilen bir iş akışı, `uninstrument()` yapılana kadar `agent_start` açık tutar. | +| `reaper_interval` | Temizlik sıklığı. Orakçıyı tamamen devre dışı bırakmak için `0` olarak ayarlayın. | + +## İnsan döngüde + +Bekleme aracının içinde gerçekleştiğinde yakalanır: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +Düz bir iş akışı adımında `ctx.wait_for_event` yakalanmaz. Çalışma zamanı, dağıtıcıya ulaşmadan önce bırakmayı yakalar, bu nedenle adım çıkar ve daha sonra duraklatmak için anahtar yok olarak yeniden çalışır. LlamaIndex'in belgelediği FunctionAgent deseni, bir araç içinde bekler ve tam olarak yakalanır. + +## Yaygın sorunlar + + + + LLM'nizdeki `additional_kwargs={"stream_options": {"include_usage": True}}` ekleyin. Bkz. [Token sayıları](#token-sayıları). + + + + LlamaIndex'in standart bir kullanım alanı yok. Adaptör çeşitli bilinen şekilleri dener ve sayaçlarını yeni bir şey olarak adlandıran bir entegrasyon hiçbiriyle eşleşmez. + + Ham sözlük her zaman gönderilir, bu nedenle sağlayıcıınızın onları ne çağırdığını görmek için yüklemedeki `usage` kontrol edin. + + Dolu bir `usage` boş token sütunları ile birlikte kasıtlıdır — bunun yerine güvenli bir yanlış sayı daha iyidir. + + + + Bu FunctionAgent döngüsüdür, yineleme başına bir set. Kontrol panelde kanca adına göre filtreleyin. Bu adım zamanlamaları, genellikle bu adaptörü yalnızca model içeren bir yerine kullanma nedenidir. + + + + Şu sırayla kontrol edin: `instrument()` çalışmadan önce çalıştı; `await` etrafında bir `async with failproofai_sdk.session():` vardır; `llama-index-core` 0.14.23 veya daha yenisidir; `FAILPROOFAI_SDK_STRICT=1` ayarlanmış, bu nedenle yozlaşmış bir kanca yutulan yerine yükseltilir. + + + +## Sonraki + + + + Çiftler, kimlikler, oturum yaşam döngüsü ve teslimat. + + + Yeni yakaladığınız oturum aracılığıyla nedenselliği izleyin. + + + LangGraph, CrewAI, Pydantic AI ve özel aracılar. + + \ No newline at end of file diff --git a/docs/tr/start/integrations/pydantic-ai.mdx b/docs/tr/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..f4a9eeeed --- /dev/null +++ b/docs/tr/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "Yazılan aracıları, araçları, model çağrılarını ve yeniden denemeleri enstrüman edin." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## Yükle + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +Desteklenen: `pydantic-ai-slim` 2.0 ila 3.0. 2.0, `Agent(instrument=...)` özelliğini kaldırmış ve bu adaptörün üzerine inşa edildiği yetenek protokolünü tanıtmıştır, bu nedenle 1.x bu şekilde enstrüman edilemez. + +## Enstrüman Edin + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # herhangi bir Agent oluşturmadan önce + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` herhangi bir `Agent` oluşturmadan önce çalışmalıdır. Yetenek, oluşturma sırasında eklenir, bu nedenle daha önce oluşturulmuş bir aracı hiçbir şey kaydetmez ve hiçbir hata olmadığı için hata vermez. Bu, bu adaptörle boş bir izlemenin en yaygın nedenidir. + + +Modül kapsamındaki aracılar bunun sorun olduğu yerdir: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # import sırasında oluşturulur + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # bunu ÖNCE çalıştırın +import agents # şimdi aracı yeteneği alır +``` + +Başarılı olduğunu doğrulayın: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI, geçtiğiniz listeyi tek bir `root_capability` olarak birleştirir, bu nedenle okumanız için `agent.capabilities` özniteliği yoktur. + +Enstrüman edilirken oluşturulan Aracılar yeteneği tutar, bu nedenle onları yeniden oluşturmadan `uninstrument()` yapabilir ve yeniden enstrüman edebilirsiniz. + +## Kaydedilenleri + +| Pydantic AI | Failproof olayı | +| --- | --- | +| Aracı çalışması | `agent_start`, `agent_end` | +| Model isteği | `model_request`, `model_response`, belirteç kullanımı ile | +| Araç çağrısı | `tool_use`, `tool_result`, modelin gönderdiği argümanlar ile | +| Bir araçtan `ModelRetry` | hata taşıyan `tool_result` | +| İşlenmeyen istisna | `error`, ardından `failed` sonucu ile `agent_end` | + +Burada hook çifti ve insan-döngü çifti yoktur. Pydantic AI'ın köşeli parantez koymak için düğüm veya adım sınırı yoktur ve yerleşik insan duraklaması yoktur, bu nedenle eşleştirilecek hiçbir şey yoktur. İkisini de oluşturursanız, olayları kendiniz yayın — [Özel aracılar](/tr/reference/custom-agents) bölümüne bakın. + +`output_type`, izlemeyi etkilemez. Yazılı bir çalışma ve bir dize çalışması aynı olayları üretir. + +## Örnek + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +İzlemede, `restock_eta` bir hata taşıyan `tool_result` olarak görünür, ardından modelin bunu geçiştiği başka bir model çağrısı gelir ve çalışma yine de `success` ile biter. Her iki gerçek de kaydedilir. + +## Hatalar, yeniden denemeler ve kontrol akışı + +Pydantic AI üç farklı şey için istisna atar ve adaptör bunları ayırır: + +| İstisna | Şu şekilde Davranılır | Sonuç | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | Gerçek araç hatası | hata taşıyan `tool_result`; çalışma yine de `success` ile bitebilir | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | Kontrol akışı | Hata değil; çalışma yönlendirilmektedir | +| Başka herhangi bir şey | Bir hata | `error`, ardından `failed` sonucu ile `agent_end` | + +`ModelRetry` kasıtlı olarak ilk grupta yer almaktadır. Bu, bir denemesi gerçekten başarısız olduğu ve modelin yeniden denemeyi yapması istendiği anlamına gelir; bu, bir araç aralığının hata alanı için kullanılacak şeydir. Bunu kontrol akışı olarak sınıflandırmak, gerçek araç hatalarını yeşil bir çalışmanın arkasına gizlerdi. + +## Aralıklarınızı adlandırın + +Pydantic AI'ın kendi çalışma aralığı `agent` olarak adlandırılır. Çağrıyı seçtiğiniz bir etiketle vermek için sarın: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +Çerçevenin aralığı, `inventory` altında yuvalanır ve model ile araç olayları buraya bağlanır. + +`agent_id` düşük kardinalite tutun. Her pano yüzeyinde birincil cephe olduğu için, bir rol adı kullanın, asla bir UUID veya çalışma başına dize kullanmayın. + +## Oturumu Kontrol Edin + +Bu sırayla çözülür, ilk eşleşme kazanır: + +1. `instrument("pydantic_ai", session_id=...)` +2. Çevreleyen `failproofai_sdk.session()` kapsamı +3. Çalışmanın `conversation_id`, ardından `run_id` +4. Oluşturulan bir `uuid4().hex` + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## Seçenekler + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # her çalışmayı bir oturum kimliğine sabitle + capture_content=True, # False, istekleri ve tamamlamaları yüklerden bırakır +) +``` + +## Yaygın Sorunlar + + + + `Agent` `instrument()` çalıştırılmadan önce oluşturuldu. Yukarıdaki uyarıya bakın ve `agent.root_capability.capabilities` öğesini kontrol edin. + + + + Bare `raise` yayılır; bu Pydantic AI'ın tasarımıdır. Modelin bunu geçişitmesine izin vermek için, üzerine hareket edebileceği bir iletiyle `ModelRetry` yükseltin. Hata her iki şekilde de kaydedilir. + + + + O çocuk Pydantic AI'ın kendi çalışma aralığı ve model ile araç olaylarının bulunduğu yerdir. Tek bir aralık istiyorsanız kendi kapsamınızı bırakın, özel ad maliyetine katlanın. + + + + Pydantic AI'ın async grafik yığını, yük alanı sınırından daha uzundur ve yığın izinin son satırı özel olarak hata kendisidir. Bu alan, arkasından ziyade ön tarafından kırpılır, bu nedenle ihtiyacınız olan satır hayatta kalır. + + + +## Sonraki + + + + Çiftler, kimlikler, oturum yaşam döngüsü ve teslim. + + + Yeni yakaladığınız oturum aracılığıyla nedenselliği izleyin. + + + LangGraph, CrewAI, LlamaIndex ve özel aracılar. + + \ No newline at end of file diff --git a/docs/tr/start/quickstart.mdx b/docs/tr/start/quickstart.mdx index 6c3d91ff5..a5f8d7af7 100644 --- a/docs/tr/start/quickstart.mdx +++ b/docs/tr/start/quickstart.mdx @@ -1,45 +1,45 @@ --- title: "Hızlı Başlangıç" -description: "Bir agent oturumunu yakalayın, bir hatayı bulun ve onu önlemeye başlayın." +description: "Bir agent oturumunu yakala, bir hatayı bul ve onu önlemeye başla." icon: "zap" --- -Bu hızlı başlangıç, bir makineyi oturum raporlamaya başlatır, bir denetim çalıştırır ve bir politika dağıtır. Failproof AI'ı ayarlamak için beceriyi kullanın veya manuel adımları izleyin. +Bu hızlı başlangıç, bir makinenin oturum raporlaması 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. -**Sizin yolunuz hangisi?** Agent'ınız 12 desteklenen [harness](/tr/reference/harnesses) türünden birinde çalışıyorsa — bir kodlama CLI'si, Hermes veya OpenClaw gibi bir ağ geçidi — aşağıdaki adımları izleyin; Node.js 20.9 veya üzeri sürüme ihtiyacınız vardır. Agent'ınızın harness'i yoksa, izleme ve denetim için [Python SDK](/tr/reference/custom-agents) ile enstrümente edin, ardından [İlk başarısızlık kontrolünü çalıştırın](/tr/start/first-audit) konusunda devam edin; o yoldaki uygulama, çalışma zamanınızda bir hook gerektirir. +**Hangi yol sizin?** Agent'ınız desteklenen 12 [harness](/tr/reference/harnesses) türünden birinde çalışıyorsa — bir kodlama CLI'sı veya Hermes ya da OpenClaw gibi bir gateway — aşağıdaki adımları izleyin; Node.js 20.9 veya daha sonraki bir sürüme ihtiyacınız vardır. Agent'ınızın bir harness'i yoksa, izleme ve denetimler için [Python SDK](/tr/reference/custom-agents) ile araçlandırın, ardından [İlk başarısızlık kontrolünü çalıştır](/tr/start/first-audit) kısmında tekrar başlayın; bu yoldaki zorlamalar çalışma zamanı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. ``` - Agent'ınız projeyi inceler, ilgili entegrasyonu seçer, kurulumu gerçekleştirir ve doğrular. Bireysel beceriler ve ileri kurulum seçenekleri için [FailproofAI beceri deposu](https://github.com/FailproofAI/skills) bölümüne bakın. + Agent'ınız projeyi inceler, ilgili entegrasyonu seçer, kurulumu gerçekleştirir ve doğrular. Bireysel beceriler ve gelişmiş kurulum seçenekleri için [FailproofAI beceriler deposuna](https://github.com/FailproofAI/skills) bakın. ## Başlamadan önce -1. [Failproof AI panosunu](https://app.befailproof.ai) açın ve hesap oluşturun veya iş e-postanızla oturum açın. -2. **Yönetim → Anahtarlar** konusuna gidin ve `events:add` ve `policies:pull` izinleriyle bir anahtar oluşturun. -3. Tek kullanımlık 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` izinleriyle bir anahtar oluşturun. +3. Tek seferlik sırrı kopyalayın ve hedef makinede saklayın: ```bash export FAILPROOFAI_KEY="" ``` - ## Yükleyin + ## Yükle - + ```bash npm install -g failproofai failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" @@ -47,7 +47,7 @@ export FAILPROOFAI_KEY="" Oturum transkriptleri varsayılan olarak gönderilir. Transkript içeriği olmadan hook aktivitesi ve politika kararlarını raporlamak için `--no-transcripts` ekleyin. - Bu makinede zaten agent geçmişi varsa, son yedi günü önizleyin ve içe aktarın, ardından teslimin bitmesini bekleyin. Yeni bir makinede bu adımı atlayın. + Bu makinede zaten agent geçmişi varsa, son yedi günü önizleyin ve içeri aktarın, ardından teslimi bitirmesini bekleyin. Yeni bir makinede bu adımı atlayın. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Failproof AI'da **Oturumlar**'ı açın ve içe aktarılan bir oturumu seçin. + Failproof AI'da **Sessions** bölümünü açın ve içeri aktarılan bir oturumu seçin. - - Bu, Failproof AI'ı harness'inize bağlar ve 40 yerleşik politikayı yükler. Bunları, yerel politika kararlarını görmek ve Failproof AI oturumlarınızı denetlemeden ve agent'larınız için politikalar yazmadan önce uygulamayı denemek için kullanın. + + Bu, Failproof AI'ı harness'inize bağlar ve 40 yerleşik politikayı yükler. Yerel politika kararlarını görmek ve Failproof AI oturumlarınızı denetlemesi ve agent'larınız için politika yazması öncesinde zorlamayı denemek için bunları kullanın. - Yükleyicinin harness'i algılamasına izin verin veya açıkça bir tane 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`. + Yükleyicinin harness'inizi algılamasına izin verin veya açıkça bir tane 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`. ```bash - failproofai policies --install --cli claude --scope user # a coding CLI - failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway + failproofai policies --install --cli claude --scope user # bir kodlama CLI'sı + failproofai policies --install --cli hermes --scope user # bir Slack/Telegram gateway'i ``` - Bir tool çağrısını çalışmadan önce bloke etmek 12'sinde de doğrulanır. Tur sonu geçitleri 8'inde doğrulanır — per-harness matrisi için [uygulama yeteneği](/tr/reference/harnesses#enforcement-capability) bölümüne bakın. + Bir tool çağrısını çalıştırılmadan önce engelleme tüm 12'de doğrulanır. Dönüş sonu kapıları 8'de doğrulanır — harness başına matrix için [enforcement capability](/tr/reference/harnesses#enforcement-capability) bölümüne bakın. - - [İlk başarısızlık kontrolünüzü çalıştırın](/tr/start/first-audit) konusunu izleyin. "Agent'ın yaklaşımını değiştirmeden başarısız olan bir tool'u yeniden denediği oturumları bul" gibi somut bir hedef kullanın. + + [İlk başarısızlık kontrolünü çalıştır](/tr/start/first-audit) bölümünü izleyin. "Agent'ın yaklaşımını değiştirmeden başarısız bir aracı 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) konusunu izleyin. Gözlem modunda başlayın, eşleşmeleri inceleyin, ardından incelenen sürümü uygulayın. + + [İlk başarısızlığı bir politikayla önle](/tr/start/first-policy) bölümünü izleyin. Gözlem modunda başlayın, eşleşmeleri inceleyin, ardından incelenen sürümü uygulayın. - `failproofai config --status` komutunu çalıştırın. Sağlıklı bir kurulum, bulut bağlantısını, daemon durumunu ve uygulamanın duraklatılıp duraklatılmadığını raportar. + `failproofai config --status` komutunu çalıştırın. Sağlıklı bir kurulum bulut bağlantısını, daemon durumunu ve zorlamanın durdurulup durdurulmadığını rapor eder. \ No newline at end of file diff --git a/docs/tr/start/quickstarts/crewai.mdx b/docs/tr/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..bf321c708 --- /dev/null +++ b/docs/tr/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "Kurun, enstrümanı ayarlayın ve ilk izlemenizi göreceğin." +icon: "/images/frameworks/crewai.svg" +--- + +İlk CrewAI izlemenize giden üç adım. Her etkinliğin ne taşıdığı, akışları ve sorun giderme için bkz. [tam kılavuz](/tr/start/integrations/crewai). + +## Kurun + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## Enstrüman ayarlayın + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +Crew'unuzda, ajanlarında, görevlerinde veya araçlarında hiçbir şey değişmez. `instrument()`, CrewAI'nin modül düzeyindeki etkinlik veri yoluna abone olur. + +## Geldiğini kontrol edin + +Bir kez çalıştırın, ardından **Observe → Sessions** öğesini açın ve ortamınızı seçin. Çalışmanız yeniden oluşturulan bir iz olarak görünür. + +Hiçbir şey gelmezse, makine `failproofai config --status` komutu ile bağlı olduğunu doğrulayın. + + + Neyin kaydedildiği, akışları, token kullanımı, span adlandırması, seçenekler ve yaygın sorunlar. + \ No newline at end of file diff --git a/docs/tr/start/quickstarts/custom-agents.mdx b/docs/tr/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..d2e68b870 --- /dev/null +++ b/docs/tr/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "Özel ajanlar" +description: "Ajanınızı üç `with` bloğuna sarın ve kayıt almaya başlayın." +icon: "code" +--- + +Kendiniz yazdığınız bir ajan için, ya da Failproof AI'ın adaptörü olmayan bir framework için. + +Zaten yaptığınız işi `with` bloklarına sararsınız. Her biri ne zaman başladığını, ne zaman bittiğini ve ne kadar sürdüğünü kaydeder — başka bir şey çağırmanıza gerek yoktur. + +## Kurulum + +```bash +pip install failproofai-sdk +``` + +Ekstra hiçbir şey yok, bağımlılık da yok. + +## Enstrümantasyon + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # bir çalışma + with failproofai_sdk.agent("planner"): # bir iş birimi + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) # bir araç çağrısı +``` + +Yukarıdan aşağıya oku ve ne demek istediğini anla: + +| Şununla sar | Demek için | +| --- | --- | +| `session()` | Bu olaylar aynı çalışmaya ait | +| `agent()` | Birisi çalışıyor — bir listede tanıyabileceğin bir ad ver | +| `tool_call()` | Bu bir araçtır ve işte döndüğü değer | + +Kodun nasıl iç içe geçiyorsa öyle iç içe geçir. Hiçbir zaman id'ler geçmezsin: her blok neyin içinde olduğunu hatırlar, bu nedenle kaydettiğin her şey doğru çalışmayı ve doğru ajanı otomatik olarak alır. `async with` tamamen aynı şekilde çalışır. + +## Geldikten sonra kontrol et + +Bir kez çalıştır, sonra **Observe → Sessions** sayfasını aç ve ortamını seç. Çalışmanız yeniden yapılandırılmış bir iz olarak görünür. + +Hiçbir şey gelmezse, makinen `failproofai config --status` ile bağlı olduğunu doğrula. + + + Her olay yöntemi, kodun bir istisna fırlatırsa ne olur, çalışan bir örnek, iş parçacıkları ve async, ve adaptörü olmayan bir framework'ü enstrümante etme. + \ No newline at end of file diff --git a/docs/tr/start/quickstarts/langchain.mdx b/docs/tr/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..43a51a2a2 --- /dev/null +++ b/docs/tr/start/quickstarts/langchain.mdx @@ -0,0 +1,40 @@ +--- +--- +title: "LangChain ve LangGraph" +description: "Kurun, enstrüman edin ve ilk izinizi görün." +icon: "/images/frameworks/langchain.svg" +--- + +İlk LangChain veya LangGraph izinize ulaşmak için üç adım. Streaming, insan müdahalesi, span adlandırması ve seçenekler için [tam kılavuzu](/tr/start/integrations/langchain) inceleyin. + +## Kurun + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +LangGraph olmadan LangChain için `failproofai-sdk[langchain]` kullanın. + +## Enstrüman edin + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +Çağrı sitesinde değişiklik yok. `instrument()`, LangChain'in oluşturduğu her callback yöneticisine enjekte ettiği bir tracer kaydeder, böylece grafikler, araçlar ve modeller (yazmadığınız kütüphanelerin içindekiler dahil) yakalanır. + +## Geldiğini kontrol edin + +Bir kez çalıştırın, sonra **Observe → Sessions** bölümünü açın ve ortamınızı seçin. Çalışmanız yeniden oluşturulmuş bir iz olarak görüntülenir. + +Hiçbir şey gelmezse, `failproofai config --status` komutuyla makinenin bağlı olduğunu doğrulayın. + + + Nelerin kaydedildiği, streaming, token sayıları, span adlandırması, oturum kontrolü, seçenekler ve insan müdahalesi. + \ No newline at end of file diff --git a/docs/tr/start/quickstarts/llamaindex.mdx b/docs/tr/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..8d7eab68f --- /dev/null +++ b/docs/tr/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "Kurun, enstrüman edin ve ilk izinizi görün." +icon: "/images/frameworks/llamaindex.svg" +--- + +İlk LlamaIndex izinize ulaşmak için üç adım. İş akışı adımları, alma, reaper ve seçenekler için bkz. [tam kılavuz](/tr/start/integrations/llamaindex). + +## Kurun + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## Enstrüman Edin + +LlamaIndex'in agent API'si asenkron. Her scope `async with` ve `with` altında da çalışır. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + LLM'nizde ekstra bir argüman olmadan, izinizde her token sayımı null olur — `llama-index-llms-openai` akış halinde kullanım talep etmez. Bkz. [Token sayımları](/tr/start/integrations/llamaindex#token-counts). + + +## Geldiğini Kontrol Edin + +Bir kez çalıştırın, ardından **Observe → Sessions** öğesini açın ve ortamınızı seçin. Çalışmanız yeniden yapılandırılmış bir iz olarak görünür. + +Hiçbir şey gelmezse, makinenin `failproofai config --status` ile bağlı olduğunu doğrulayın. + + + Token sayımları, kaydedilen neler, iş akışı adımları, alma, seçenekler ve yaygın sorunlar. + \ No newline at end of file diff --git a/docs/tr/start/quickstarts/pydantic-ai.mdx b/docs/tr/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..a1fab4ab2 --- /dev/null +++ b/docs/tr/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "Yükleyin, enstrümente edin ve ilk izlemenizi görün." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +İlk Pydantic AI izlemenize kadar üç adım. Araçlar, yeniden denemeler, akış ve seçenekler için bkz. [tam kılavuz](/tr/start/integrations/pydantic-ai). + +## Yükleme + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## Enstrümantasyon + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # herhangi bir Agent oluşturmadan önce + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` bir `Agent` oluşturmadan **önce** çalışmalıdır. Yetenek yapı sırasında eklenir, bu nedenle daha önce oluşturulmuş bir agent hiçbir şey kaydetmez — hata olmadığı için hata da olmaz. Bu, bu adaptör ile boş bir izlenin en yaygın nedenidir ve modül kapsamı ajanlar bu sorunu yaşayan yerdir: `failproofai_sdk` içe aktarın ve `instrument()` öğesini onları oluşturan modülü içe aktarmadan önce çağırın. + + +## Ulaştığını kontrol edin + +Bir kez çalıştırın, ardından **Observe → Sessions** öğesini açın ve ortamınızı seçin. Çalışmanız yeniden yapılandırılmış bir izleme olarak görünür. + +Hiçbir şey gelmezse, `failproofai config --status` ile makinenin bağlı olduğunu doğrulayın. + + + Kaydedilen şey, araçlar ve yeniden denemeler, akış, span adlandırması, seçenekler ve yaygın sorunlar. + \ No newline at end of file diff --git a/docs/vi/index.mdx b/docs/vi/index.mdx index 1eb7e1cb8..3201614f8 100644 --- a/docs/vi/index.mdx +++ b/docs/vi/index.mdx @@ -1,41 +1,42 @@ --- -title: "Làm cho agent của bạn chống lỗi" -description: "Quan sát và thực thi cho mọi harness mà agent của bạn chạy — coding CLI, chat gateway, trợ lý tự lưu trữ, và agent được cấu hình của bạn." +--- +title: "Làm cho agent của bạn không bị lỗi" +description: "Khả năng quan sát và thực thi cho mọi harness mà agent của bạn chạy trên đó — coding CLIs, chat gateways, self-hosted assistants và các agent được instrumented của riêng bạn." icon: "shield-check" --- -Failproof AI giúp các team hiểu agent đã làm gì, tìm ra nơi chúng thất bại, và triển khai các biện pháp bảo vệ trước khi hành động tương tự xảy ra lại. +Failproof AI giúp các team hiểu được agent đã thực hiện những gì, tìm ra nơi nó thất bại, và triển khai các biện pháp bảo vệ trước khi cùng một hành vi xảy ra lại. -**Harness** là bất cứ thứ gì mà agent thực sự chạy bên trong. Failproof AI kết nối 12 harness — coding CLI như Claude Code và Codex, chat gateway như Hermes, trợ lý tự lưu trữ như OpenClaw — và các sự kiện, chính sách và lịch sử session giống nhau áp dụng cho từng cái. Agent không có harness báo cáo thông qua [Python SDK](/vi/reference/custom-agents), được truy vết và kiểm toán; thực thi chính sách ở đó cần một hook trong runtime của bạn. +Một **harness** là bất kỳ thứ gì mà agent của bạn thực sự chạy bên trong. Failproof AI hook 12 trong số chúng — coding CLIs như Claude Code và Codex, chat gateways như Hermes, self-hosted assistants như OpenClaw — và các sự kiện giống nhau, các chính sách giống nhau, cũng như lịch sử phiên làm việc giống nhau áp dụng cho mỗi một. Các Agent không có harness báo cáo thông qua [Python SDK](/vi/reference/custom-agents), cái mà trace và audit chúng; thực thi một chính sách ở đó cần một hook trong runtime của riêng bạn. - Sử dụng công cụ để cấu hình dự án của bạn, kết nối nó, và xác minh rằng nhật ký agent tới. + Sử dụng skill để instrumented dự án của bạn, kết nối nó, và xác minh rằng agent logs đã đến. - Phân tích, truy vấn, xây dựng dashboard, và chạy kiểm toán bằng ngôn ngữ tự nhiên trên nhật ký agent của bạn. + Phân tích, truy vấn, xây dựng dashboard, và chạy audit bằng ngôn ngữ tự nhiên trên agent logs của bạn. - Theo dõi model call, tool, lỗi, input từ con người, độ trễ, và quyết định chính sách trong một session. + Theo dõi model calls, tools, errors, human input, latency, và policy decisions trong một phiên làm việc. - - Kiểm toán một tập hợp session được xác định, xem lại các phát hiện có bằng chứng, và theo dõi khắc phục như các vấn đề. + + Audit một tập hợp định nghĩa các phiên làm việc, xem xét các findings được hỗ trợ bằng chứng cứ, và theo dõi remediation như các issue. - Chuyển một chế độ thất bại đã biết thành chính sách, quan sát tác động của nó, và triển khai nó trên toàn bộ fleet của bạn. + Chuyển một failure mode đã biết thành một chính sách, quan sát tác động của nó, và triển khai nó trên toàn fleet của bạn. > **Session → Audit → Finding → Issue → Policy**
-> Truy vết điều gì đã xảy ra, tìm ra thất bại, quản lý phản ứng, rồi ngăn chặn hành động tương tự trong các lần chạy trong tương lai. +> Trace những gì đã xảy ra, tìm lỗi, quản lý phản hồi, sau đó ngăn chặn cùng một hành vi trong các lần chạy trong tương lai. ## Bắt đầu ở đây -Nếu bạn đang triển khai agent được cấu hình lần đầu tiên, hãy bắt đầu với [hướng dẫn nhanh](/vi/start/quickstart). Nếu dữ liệu đã tới, mở [Sessions](/vi/sessions/overview) và kiểm tra một lần chạy thực tế trước khi cấu hình kiểm toán hoặc chính sách. +Nếu bạn đang triển khai agent được instrumented lần đầu tiên, hãy bắt đầu với [quickstart](/vi/start/quickstart). Nếu dữ liệu đã đến, hãy mở [Sessions](/vi/sessions/overview) và kiểm tra một lần chạy thực tế trước khi cấu hình audit hoặc chính sách. - - Hoàn thành quy trình từ đầu đến cuối từ capture đến một chính sách được triển khai an toàn. + + Hoàn thành quy trình end-to-end từ capture đến một chính sách được triển khai một cách an toàn. \ No newline at end of file diff --git a/docs/vi/policies/deploy.mdx b/docs/vi/policies/deploy.mdx index ccacefe59..03b333920 100644 --- a/docs/vi/policies/deploy.mdx +++ b/docs/vi/policies/deploy.mdx @@ -1,47 +1,51 @@ --- title: "Triển khai chính sách" -description: "Triển khai phiên bản chính sách đã được xem xét tới các máy được chỉ định." +description: "Triển khai một phiên bản chính sách đã xem xét tới các máy tính dự kiến." 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 tới một tập hợp các máy đã được đăng ký. +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 tính đã đăng ký. ## Áp dụng một triển khai - 1. Đi tới **Admin → enforcement**, tìm máy và mở rộng dòng của nó. - 2. Chọn **edit**, thêm phiên bản chính sách đã được 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 đó chờ lần check-in tiếp theo của máy và xác nhận trạng thái triển khai và phạm vi bao phủ của nó. + 1. Đi tới **Admin → enforcement**, tìm máy tính và mở rộng dò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 đó chờ lần check-in tiếp theo của máy tính và xác nhận trạng thái triển khai và phạm vi bảo phủ 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 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) + ![Trình chỉnh sửa triển khai máy tính với các phiên bản chính sách, các hiệu ứng enforce và observe, và hành động áp dụng triển khai.](/images/dashboard/enforcement-editor.png) - Các điểm cuối triển khai Cloud được cố ý không được công khai dưới dạng các lệnh `fp` thông thường. Kiểm tra máy cục bộ, sau đó triển khai qua bảng điều khiển: + 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 nó — `deploy` in ra toàn bộ kế hoạch và chỉ hỏi **trên một thiết bị đầu cuối 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 kịch bản, một agent shell out) 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: ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - Sử dụng `fp sessions --env production --since 24h` và `fp events --event-type hook_completed` sau triển khai để xác minh hoạt động được gửi tới Cloud. + `fp fleet diff ` hiển thị ý định so với giao hàng (một máy tính được đọc là `behind` cho đến khi nó tiếp theo khảo sát), `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 kể từ khi bị vô hiệu hóa hoặc xóa. + + Kiểm tra chính máy tính bằng `failproofai config --status`, và sử dụng `fp sessions --env production --since 24h` và `fp events --event-type hook_completed` sau triển khai để xác minh rằng hoạt động đến đám mây. - Triển khai một phiên bản đã được xem xét, không phải bản nháp có thể thay đổi, bắt đầu với một máy không phải sản xuất hoặc một nhóm nhỏ có phiên làm việc mà bạn có thể kiểm tra. + Triển khai một phiên bản đã xem xét, không phải bản nháp có thể thay đổi, bắt đầu với một máy tính không phải sản xuất hoặc nhóm nhỏ mà bạn có thể kiểm tra các phiên làm việc. - Xem xét các trận đấu, lý do, các công cụ bị ảnh hưởng, và những kết quả sai lệch mà không chặn công việc. + Xem xét các trận đấu, lý do, các công cụ bị ảnh hưởng, và những tích cực giả mà không chặn công việc. - - Nâng cấp sau khi quan sát các trận đấu 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 đều đã kéo triển khai và báo cáo quyết định. + + Thúc đẩy sau khi các trận đấu được quan sát 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 rằng mọi máy tính dự kiến đã kéo triển khai và báo cáo các quyết định. -Máy cần khả năng `policies:pull`. Báo cáo sự kiện được kiểm soát riêng bởi `events:add`; xác minh cả hai khi bạn mong đợi phân tích và thực thi Cloud. +Máy tính 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 dự kiến phân tích và thực thi Cloud. - Quản lý thực thi là một quy trình làm việc quản trị Cloud. Không coi các tuyến thực thi chỉ dành cho root là các điểm cuối API `/v1` thông thường của khách hàng. + Quản lý thực thi là một quy trình làm việc Cloud hành chính. Không coi các tuyến thực thi chỉ dành cho root là các điểm cuối API `/v1` của 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 51892fb58..a65fa1db8 100644 --- a/docs/vi/policies/editor.mdx +++ b/docs/vi/policies/editor.mdx @@ -1,47 +1,49 @@ --- -title: "Trình biên tập chính sách" -description: "Tạo và sửa đổi các chính sách theo phiên bản từ một chế độ lỗi đã được xác nhận." +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." icon: "file-pen-line" --- -Sử dụng trình biên tập 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ữ quá trình soạn thảo tách biệt với triển khai để bản nháp không thể thay đổi trơn tru hành vi trực tiếp. +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. -Khi một vấn đề có mô hình 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 chính sách có thể biểu hiện vấn đề hay không, sau đó đưa ý định đã được xem xét và ngữ cảnh phát hiện vào trình biên tập. Nguồn đã tạo sẽ vẫn là bản nháp cho đến khi bạn xuất bản 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ó. -## Xuất bản phiên bản chính sách +## Xuất bản một phiên bản chính sách - 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 thực nguồn và sửa chữa mọi lỗ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 tắt các phiên bản. + 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. - ![Chế độ xem soạn thảo của Trình biên tập 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à các điều khiển xuất bản.](/images/dashboard/policy-editor.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ợ AI, xác nhận nguồn và kiểm soát xuất bản.](/images/dashboard/policy-editor.png) - Cloud CLI không xuất bản các phiên bản chính sách. Xác thực nguồn cục bộ trước khi sao chép nó vào trình biên tập: + 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: ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - Xuất bản phiên bản đã được xem xét từ **Admin → policy editor**. + 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`. -## Danh sách kiểm tra soạn thảo +## Danh sách kiểm tra tác vụ soạn thảo 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ụ có đủ bằng chứng để quyết định. +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 agent hoặc người vận hành biết phải làm gì tiếp theo. -5. Thêm các ví dụ phải khớp và các ví dụ phải vẫn được phép. -6. Lưu phiên bản mới và yêu cầu xem xét. +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. -Sử dụng `instruct` khi agent có thể an toàn hiệu chỉnh hướng đi. 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ể hoàn tác. +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. - Các phiên bản chính sách là đầu vào triển khai bất biến. Chỉnh sửa bản nháp sẽ tạo 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. + 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 diff --git a/docs/vi/reference/cloud-cli.mdx b/docs/vi/reference/cloud-cli.mdx index b207d2340..e16101b87 100644 --- a/docs/vi/reference/cloud-cli.mdx +++ b/docs/vi/reference/cloud-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof Cloud CLI" -description: "Tham chiếu hoàn chỉnh để truy vấn và quản lý Failproof AI Cloud với fp." +description: "Tài liệu tham khảo đầy đủ để truy vấn và quản trị Failproof AI Cloud bằng fp." icon: "cloud-cog" --- -Sử dụng `fp` để kiểm tra telemetry của Cloud 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 telemetry trên 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ụ riêng lẻ: +Cài đặt Cloud CLI được phát hành như một công cụ độc lập: ```bash uv tool install fp-cloud-cli @@ -26,7 +26,7 @@ fp whoami fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS] ``` -Các tùy chọn toàn cục phải đứng trước lệnh: +Global options phải đứng trước command: ```bash fp --json sessions --since 24h @@ -38,211 +38,215 @@ Chạy `fp COMMAND --help` hoặc `fp COMMAND SUBCOMMAND --help` để xem trợ ### Xác thực -| 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 hạn. | — | +| `fp whoami` | Hiển thị danh tính hiện tại, chế độ xác thực, tổ chức, và quyền. | — | | `fp version` | Hiển thị phiên bản CLI đã cài đặt. | — | -| `fp help` | Hiển thị trợ giúp lệnh cấp cao nhất. | — | +| `fp help` | Hiển thị trợ giúp command ở cấp cao nhất. | — | ```bash 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ẻ. Bộ lọc nhẹ mặc định loại trừ raw payloads; chỉ sử dụng `--full` cho một cuộc điều tra có giới hạn. +Liệt kê các agent events riêng lẻ. Feed light mặc định loại trừ raw payloads; chỉ sử dụng `--full` cho một cuộc điều tra bị giới hạn. -| Tùy chọn | Mô tả | +| Option | Mô tả | | --- | --- | -| `--limit`, `-n ` | Tối đa tổng hàng. Mặc định: `50`. | +| `--limit`, `-n ` | Tổng số hàng tối đa. Mặc định: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, hoặc `7d`. | -| `--from ` / `--to ` | Phạm vi ISO 8601 UTC; 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 ` | Dải ISO 8601 UTC; 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 text payload; có thể lặp lại, bất kỳ thuật ngữ nào cũng khớp. | | `--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ỏ mờ. | +| `--cursor ` | Tiếp tục từ một cursor opaque. | | `--page-size ` | Hàng trên mỗi yêu cầu với `--all`; tối đa `200`. | -| `--full` | Bao gồm raw payloads thông qua điểm cuối sự kiện nặng hơn. | -| `--fields ` | Chỉ trả về các trường được chọn; yêu cầu `payload` kích hoạt chế độ đầy đủ. | +| `--full` | Bao gồm raw payloads thông qua endpoint event nặng hơn. | +| `--fields ` | Chỉ trả về các trường được chọn; yêu cầu `payload` bật chế độ đầy đủ. | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` -### Phiên + + `--all` phân trang **lên đến `--limit`**, mặc định là **50** — vì vậy `--all` một mình dừng ở 50 hàng. Khi nó dừng sớm, phản hồi mang `next_cursor` để tiếp tục; `"next_cursor": null` nghĩa là feed thực sự đã cạn kiệt. + + +### Sessions ```text fp sessions [OPTIONS] ``` -| Tùy chọn | Mô tả | +| Option | Mô tả | | --- | --- | -| `--limit`, `-n ` | Tối đa tổng hàng. Mặc định: `50`. | +| `--limit`, `-n ` | Tổng số hàng tối đa. Mặc định: `50`. | | `--since ` | `all`, `15m`, `1h`, `6h`, `24h`, hoặc `7d`. | -| `--from ` / `--to ` | Phạm vi ISO 8601 UTC; 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 ` | Dải ISO 8601 UTC; 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 được chọn nào. | -| `--session-id ` | Bộ lọc phiên; lặp lại hoặc phân tách bằng dấu phẩy. | +| `--agent-id ` | So khớp các sessions liên quan đến bất kỳ agent được chọn. | +| `--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 đến `--limit`. | -| `--cursor ` | Tiếp tục từ một con trỏ mờ. | +| `--cursor ` | Tiếp tục từ một cursor opaque. | | `--page-size ` | Hàng trên mỗi yêu cầu với `--all`; tối đa `200`. | | `--fields ` | Chỉ trả về các trường được chọn. | -| `--full-ids` | Không rút ngắn ID phiên trong đầu ra terminal. | -| `--agents` | Mở rộng danh sách agent cho các phiên đa-agent. | +| `--full-ids` | Không rút ngắn session IDs trong đầu ra terminal. | +| `--agents` | Mở rộng danh sách agents cho multi-agent sessions. | -### Đá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ẻ. | +| `--aggregate` | Hiển thị tổng và thống kê theo điểm thay vì evaluations riêng lẻ. | | `--limit`, `-n ` | Tối đa hàng danh sách. 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. | -| `--all`, `--cursor`, `--page-size` | Kiểm soát phân trang danh sách. | +| `--since`, `--from`, `--to` | Chọn khoảng thời gian. | +| `--env`, `--status`, `--agent-id`, `--session-id` | Hạn chế một giá trị chính xác trên mỗi bộ lọc. | +| `--score KEY:MIN..MAX` | Dải điểm; có thể lặp lại và tất cả dải phải khớp. | +| `--all`, `--cursor`, `--page-size` | Điều khiển phân trang danh sách. | | `--fields ` | Chỉ trả về các trường được chọn. | -| `--full-ids` | Hiển thị ID phiên đầy đủ. | -| `--scores-full` | Hiển thị mọi điểm trong đầu ra terminal. | +| `--full-ids` | Hiển thị session IDs hoàn chỉnh. | +| `--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 phù hợp thay vì liệt kê hàng. | +| `--aggregate` | Tổng hợp các 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 phạm vi thời gian. | -| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Thu hẹp dân số lỗi. | -| `--search ` | Tìm kiếm văn bản payload; có thể lặp lại. | +| `--since`, `--from`, `--to` | Chọn khoảng thời gian. | +| `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | Thu hẹp phân loại lỗi. | +| `--search ` | Tìm kiếm text 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. | +| `--all`, `--cursor`, `--page-size` | Điều khiển phân trang danh sách. | | `--fields ` | Chỉ trả về các trường được chọn. | -| `--full-ids` | Hiển thị ID phiên đầy đủ. | +| `--full-ids` | Hiển thị session IDs hoàn chỉnh. | -### Sử dụng và giá trị bộ lọc +### Usage và 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 được quan sát. | -| `fp list agents` | Liệt kê các ID agent được quan sát. | -| `fp list event_types` | Liệt kê các loại sự kiện. | -| `fp list score_filters` | Liệt kê các khóa điểm đánh giá. | -| `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 công cụ. | -| `fp list error_types` | Liệt kê các loại lỗi. | - -### Tổ chức - -| Lệnh | Mục đích | +| `fp usage` | Hiển thị usage cho cửa sổ metering hiện tại. | +| `fp list envs` | Liệt kê các environments được quan sát. | +| `fp list agents` | Liệt kê các agent IDs được quan sát. | +| `fp list event_types` | Liệt kê event types. | +| `fp list score_filters` | Liệt kê các khóa evaluation scores. | +| `fp list models` | Liệt kê tên models. | +| `fp list hooks` | Liệt kê tên hooks. | +| `fp list tools` | Liệt kê tên tools. | +| `fp list error_types` | Liệt kê error types. | + +### Organizations + +| 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 khi bỏ qua. | -| `fp orgs current` | Hiển thị 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. | +| `fp orgs list` | Liệt kê các organizations có thể truy cập. | +| `fp orgs switch [SLUG]` | Lưu một organization hoạt động; nhắc khi bị bỏ qua. | +| `fp orgs current` | Hiển thị organization hoạt động. | +| `fp orgs perms` | Hiển thị quyền của bạn trong organization 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 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 bí mật và tiết lộ 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ê organization keys. | `--show-id`; `--fields ` | +| `fp keys show NAME` | Hiển thị một key và các grants của nó. | — | +| `fp keys create NAME` | Tạo một key và tiết lộ secret của nó một lần. | `--permission-set`; `--add`; `--remove` | +| `fp keys update NAME` | Thay thế permission set hoặc điều chỉnh grants. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp keys regenerate NAME` | Xoay vòng secret và tiết lộ cái thay thế một lần. | `--yes`, `-y` | +| `fp keys disable NAME` | Vĩnh viễn thu hồi một key. | `--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 dấu chấm như `events:read.add`. +Permission tokens 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 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. | — | -| `fp query create NAME` | Lưu một truy vấn. | `--sql `; `--description` | -| `fp query update NAME` | Cập nhật hoặc đổi tên một truy vấn. | `--name`; `--sql`; `--description`; `--yes`, `-y` | -| `fp query delete NAME` | Xóa một truy vấn đã lưu. | `--yes`, `-y` | -| `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. | — | +| `fp query list` | Liệt kê các saved queries. | `--show-id`; `--fields ` | +| `fp query show NAME` | Hiển thị một query. | — | +| `fp query create NAME` | Lưu một query. | `--sql `; `--description` | +| `fp query update NAME` | Cập nhật hoặc đổi tên một query. | `--name`; `--sql`; `--description`; `--yes`, `-y` | +| `fp query delete NAME` | Xóa một saved query. | `--yes`, `-y` | +| `fp query run [NAME]` | Chạy một saved query hoặc SQL ad-hoc. | `--sql`; `--limit`; `--all`; `--arg`, `--param` | +| `fp query schema [TABLE]` | Liệt kê các queryable tables 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 list` | Liệt kê thành viên organization. | `--active-only`; `--show-id` | +| `fp users show EMAIL` | Hiển thị một thành viên và các grants 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 một thành viên. | `--permission-set`; `--add`; `--remove`; `--yes`, `-y` | +| `fp users update EMAIL` | Thay đổi grants của một 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` | -### 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 list` | Liệt kê organization settings 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`; `--yes`, `-y` tùy chọn | +| `fp settings set KEY` | Thay đổi một setting 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. | tùy chọn tạo 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 list` | Liệt kê alert rules. | `--show-id` | +| `fp alerts show NAME` | Hiển thị một alert. | — | +| `fp alerts create NAME` | Tạo một alert. | `--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 alert. | create options cộng `--name`; `--yes`, `-y` | +| `fp alerts delete NAME` | Xóa một alert. | `--yes`, `-y` | +| `fp alerts test NAME` | Gửi một test notification. | `--channels`; `--yes`, `-y` | -Mức độ nghiêm trọng của 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 đánh giá phải nằm trong khoảng từ 30 đến 86.400 giây. +Alert severities là `info`, `warning`, và `critical`. Trigger kinds là `metric_threshold`, `custom_sql`, `evaluation_score`, `eval_compound`, và `per_event`. Evaluation intervals phải nằm trong khoảng 30 đến 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 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ài đặt kiểm toán trong khi giữ lại các giá trị không được chỉ định. | 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 một 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ị trang tóm tắt và trạng thái tìm nạp URL tham chiếu. | — | -| `fp audits context-set NAME` | Thay đổi trang tóm tắt hoặc URL tham chiếu. | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | Tìm nạp lại URL tham chiếu. | — | -| `fp audits findings` | Liệt kê các findings. | `--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id` | -| `fp audits finding FINDING_ID` | Hiển thị một finding và các bằng chứng của nó. | — | +| `fp audits list` | Liệt kê audits. | `--enabled-only`; `--show-id` | +| `fp audits show NAME` | Hiển thị một audit definition và state. | — | +| `fp audits create NAME` | Tạo một audit và ngay lập tức xếp hàng đợi cho lần chạy đầu tiên của nó. | Xem [create options](#audit-create-options). | +| `fp audits edit NAME` | Thay thế audit settings trong khi giữ các giá trị không được chỉ định. | create definition options; `--name`; `--yes`, `-y` | +| `fp audits delete NAME` | Xóa một audit, các findings, và run history. | `--yes`, `-y` | +| `fp audits run NAME` | Xếp hàng đợi một manual run. | — | +| `fp audits runs NAME` | Liệt kê run history. | `--limit`, `-n`; `--show-id` | +| `fp audits context-show NAME` | Hiển thị brief và reference URL fetch state. | — | +| `fp audits context-set NAME` | Thay đổi brief hoặc reference URLs. | `--text`; `--text-file`; `--url`; `--clear-urls` | +| `fp audits context-refresh NAME` | Tái tìm nạp reference URLs. | — | +| `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à evidence của nó. | — | | `fp audits ack FINDING_ID` | Xác nhận một finding. | `--reason` | -| `fp audits mute FINDING_ID` | Chặn một mô hình lặp lại. | `--reason`; `--yes`, `-y` | -| `fp audits dismiss FINDING_ID` | Đánh dấu một mô hình không thực hiện được hành động và chặn nó. | `--reason`; `--yes`, `-y` | -| `fp audits resolve FINDING_ID` | Đánh dấu một finding đã sửa chữa mà không có sự chặn trong tương lai. | `--yes`, `-y` | -| `fp audits reopen FINDING_ID` | Trả lại một finding vào hàng đợi trực tiếp và xóa các chặn. | — | -| `fp audits assign FINDING_ID` | Đặt chủ sở hữu finding. | yêu cầu `--to ` | +| `fp audits mute FINDING_ID` | Chặn một mẫu định kỳ. | `--reason`; `--yes`, `-y` | +| `fp audits dismiss FINDING_ID` | Đánh dấu một mẫu không khả thi hành động và chặn nó. | `--reason`; `--yes`, `-y` | +| `fp audits resolve FINDING_ID` | Đánh dấu một finding đã sửa mà không chặn trong tương lai. | `--yes`, `-y` | +| `fp audits reopen FINDING_ID` | Trả về một finding cho hàng đợi live và xóa chặn. | — | +| `fp audits assign FINDING_ID` | Đặt finding owner. | yêu cầu `--to ` | -#### Tùy chọn tạo kiểm toán +#### Audit create options ```bash fp audits create checkout-reliability \ @@ -255,97 +259,141 @@ 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 ` | Trình bày câu hỏi lỗi hoặc mục đích. | -| `--enabled` / `--disabled` | Bắt đầu lên lịch hoặc tắt. Mặc định: bật. | +| `--file ` | Dựa trên định nghĩa JSON, hoặc sử dụng `-` cho stdin. Các cờ rõ ràng ghi đè giá trị file. | +| `--description ` | Nêu rõ câu hỏi thất bại hoặc mục đích. | +| `--enabled` / `--disabled` | Bắt đầu lên lịch trên 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: tiếp theo 09:00 UTC. | -| `--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 cửa sổ lăn. Mặc định: `since_last`. | +| `--schedule-anchor ` | Pha 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 lặp lại kiểm tra cửa sổ lăn động. 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 agent. Mặc định: bật. | -| `--top-k ` | Giữ lại các findings `1`–`500`. 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 tối đa năm lần. | - -Bao gồm bối cảnh trong quá trình tạo khi 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 chạy xếp hàng bắt đầu. +| `--scope ''` | Bộ lọc theo `environments`, `agent_ids`, hoặc các trường scope được hỗ trợ khác. | +| `--ignore-error-type ` | Loại trừ error types; 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 agentic analysis. Mặc định: enabled. | +| `--top-k ` | Giữ lại `1`–`500` findings. Mặc định: `50`. | +| `--sensitivity low\|medium\|high` | Đặt reporting sensitivity. Mặc định: `medium`. | +| `--channels ''` | Mảng notification channel. | +| `--text ` | Brief inline, tối đa 8.192 ký tự. | +| `--text-file ` | Đọc brief từ một file; loại trừ lẫn nhau với `--text`. | +| `--url ` | Thêm một tham chiếu HTTPS công khai; lặp lại lên đến năm lần. | + +Bao gồm context trong quá trình tạo khi lần chạy đầu tiên cần nó. Creation commits định nghĩa và context cùng nhau trước khi lần chạy được xếp hàng đợi bắt đầu. - `fp audits run` là không đồng bộ. Kiểm tra `fp audits runs NAME` cho đến khi 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 các findings của nó. -### Sự cố +### Issues + +| Command | Mục đích | Options | +| --- | --- | --- | +| `fp issues list` | Liệt kê issues. | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | +| `fp issues count` | Đếm open hoặc các issue states được chọn. | `--state` | +| `fp issues show INCIDENT_ID` | Hiển thị issue details, comments, subscribers, và activity. | — | +| `fp issues open` | Mở một manual hoặc alert-linked issue. | yêu cầu `--summary`; tùy chọn `--title`, `--alert-id`, `--severity` | +| `fp issues ack INCIDENT_ID` | Xác nhận một issue. | — | +| `fp issues assign INCIDENT_ID` | Thay thế assignees; bỏ qua option để xóa chúng. | lặp lại `--assignee` | +| `fp issues resolve INCIDENT_ID` | Giải quyết một issue. | `--yes`, `-y` | +| `fp issues comment-list INCIDENT_ID` | Liệt kê comments. | — | +| `fp issues comment-add INCIDENT_ID` | Thêm một comment. | chính xác một trong `--body`, `--file` | +| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Xóa một comment. | `--yes`, `-y` | +| `fp issues subscribers INCIDENT_ID` | Liệt kê subscribers. | — | +| `fp issues subscribe INCIDENT_ID` | Theo dõi chính mình hoặc một operator khác. | `--email` | +| `fp issues unsubscribe INCIDENT_ID` | Xóa một subscription. | `--email` | + +Valid issue states là `firing`, `acknowledged`, và `resolved`. Standalone issue severities là `info`, `warning`, và `critical`. + +### Cloud assistant + +| Command | Mục đích | Options | +| --- | --- | --- | +| `fp agent health` | Kiểm tra assistant availability và configuration. | — | +| `fp agent models` | Liệt kê các available assistant models. | — | +| `fp agent chats` | Liệt kê các saved chats. | — | +| `fp agent ask [MESSAGE]` | Bắt đầu hoặc tiếp tục một chat; đọc stdin khi message bị bỏ qua. | `--chat`; `--model`; `--page-context` | +| `fp agent show CHAT_ID` | Hiển thị một saved conversation. | — | +| `fp agent rename CHAT_ID` | Đổi tên một conversation. | yêu cầu `--title` | +| `fp agent delete CHAT_ID` | Xóa một conversation. | `--yes`, `-y` | + +### Policies + +Cloud-managed policy versions. **Session-only** — mọi command ở đây thoát `2` dưới một API key, trước bất kỳ yêu cầu nào, bởi vì đây là root-only write routes cố ý vắng mặt từ `/v1`. + +| Command | Mục đích | Options | +| --- | --- | --- | +| `fp policies list` | Liệt kê policy versions. | `--json` | +| `fp policies show POLICY_ID` | Hiển thị một policy, với source của nó. | — | +| `fp policies publish NAME PATH` | Mint một version từ một `.mjs` local. | `--description`; `--no-verify` | +| `fp policies enable POLICY_ID` | Thêm nó trở lại mọi deployment nó được loại bỏ, minting một generation mới trên mỗi. | `--yes`, `-y` | +| `fp policies disable POLICY_ID` | Loại bỏ nó khỏi mọi deployment mang nó, minting một generation mới trên mỗi. | `--yes`, `-y` | +| `fp policies delete POLICY_ID` | Xóa một policy version. | `--yes`, `-y` | +| `fp policies test PATH` | Chạy một policy cục bộ so với một context tổng hợp. Áp dụng bộ lọc `match` của mỗi policy, vì vậy một cái không bao gồm event/tool được cho sẽ được báo cáo `skipped` thay vì chạy. | `--event`; `--tool`; `--command`; `--file-path`; `--expect` | +| `fp policies compose PROMPT` | Soạn một policy với assistant. Cần `policies:write`. | — | + +### Fleet + +Những máy nào chạy những policies 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 issues list` | Liệt kê các sự cố. | `--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 sự cố, nhận xét, người đăng ký và hoạt động. | — | -| `fp issues open` | Mở một sự cố thủ công hoặc liên kết cảnh báo. | yêu cầu `--summary`; tùy chọn `--title`, `--alert-id`, `--severity` | -| `fp issues ack INCIDENT_ID` | Xác nhận một sự cố. | — | -| `fp issues assign INCIDENT_ID` | Thay thế những người được giao; 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 sự cố. | `--yes`, `-y` | -| `fp issues comment-list INCIDENT_ID` | Liệt kê nhận xét. | — | -| `fp issues comment-add INCIDENT_ID` | Thêm nhận xét. | chính xác một trong `--body`, `--file` | -| `fp issues comment-delete INCIDENT_ID COMMENT_ID` | Xóa nhận xét. | `--yes`, `-y` | -| `fp issues subscribers INCIDENT_ID` | Liệt kê người đăng ký. | — | -| `fp issues subscribe INCIDENT_ID` | Đăng ký chính bạn hoặc một toán tử khác. | `--email` | -| `fp issues unsubscribe INCIDENT_ID` | Xóa đăng ký. | `--email` | - -Các trạng thái sự cố hợp lệ là `firing`, `acknowledged` và `resolved`. Các mức độ nghiêm trọng sự cố độc lập là `info`, `warning` và `critical`. - -### Trợ lý Cloud - -| Lệnh | Mục đích | Tùy chọn | +| `fp fleet list` | Liệt kê enrolled machines và deployment generation của chúng. | — | +| `fp fleet show MACHINE_ID` | Policy set mà một machine hiện đang chạy. | — | +| `fp fleet deploy MACHINE_ID` | **Thay thế toàn bộ policy set của machine.** In ra kế hoạch và chỉ hỏi trên một terminal tương tác mà không `--json`. | `--add`; `--remove`; `--set`; `--create`; `--yes`, `-y` | +| `fp fleet diff MACHINE_ID` | So sánh một machine với một deployment khác. | — | +| `fp fleet history MACHINE_ID` | Past deployments cho một machine. | — | +| `fp fleet rollback MACHINE_ID` | Khôi phục một deployment trước đó. | `--yes`, `-y` | +| `fp fleet rename MACHINE_ID` | Cho một machine một tên có thể đọc được. | yêu cầu `--name` | + +### Guardrails + +Những gì enforcement thực sự đã làm. **Session-only**, lý do tương tự như trên. + +| Command | Mục đích | Options | | --- | --- | --- | -| `fp agent health` | Kiểm tra sự sẵn có và cấu hình 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 cuộc trò chuyện; đọc stdin khi bỏ qua tin nhắn. | `--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. | yêu cầu `--title` | -| `fp agent delete CHAT_ID` | Xóa một cuộc trò chuyện. | `--yes`, `-y` | +| `fp guardrails summary` | Coverage, blocked/evaluated totals, một deny sparkline, và bảng per-policy. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | +| `fp guardrails timeline` | Decisions bucketed qua cửa sổ, tổng hợp trên mọi policy source. | `--since` (`1h`, `6h`, `24h`, `7d`); `--machine` | -## 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. | -| `--base-url ` | Sử dụng bảng điều khiển 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 ` | Hết thời gian HTTP; phải 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 không được bao quanh và thoát. | +| `--json` | Phát hành machine-readable JSON. | +| `--base-url ` | Sử dụng một self-hosted hoặc development dashboard. | +| `--org ` | Chọn một organization cho lệnh gọi này. | +| `--token ` | Ghi đè saved user-session token. | +| `--api-key ` | Xác thực automation bằng một API key; không bao giờ được lưu. | +| `--timeout ` | HTTP timeout; phải tích cực. Mặc định: `30`. | +| `--quiet`, `-q` | Loại bỏ status output trên stderr. | +| `--no-color` | Vô hiệu hóa colored output. | +| `--insecure` / `--secure` | Vô hiệu hóa hoặc khôi phục TLS certificate verification. | +| `--version` | In phiên bản không hộp và thoát. | | `--help`, `-h` | Hiển thị trợ giúp. | -`--api-key` được 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 một phiên người dùng. +`--api-key` dùng cho automation. Login, organization switching, và assistant commands yêu cầu một user session. -## 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 | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | Chuyển vị trí thư mục cấu hình CLI hiện tại. | -| `AGENTEYE_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 người thuê một cách rõ ràng bằng `--org` hoặc `AGENTEYE_ORG`. +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `FP_API_KEY` | `--api-key` | +| `FP_JSON` | `--json` | +| `FP_INSECURE` | `--insecure` | +| `FP_HOME` | Chuyển 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 anonymous CLI analytics. | +| `NO_COLOR` | Vô hiệu hóa colored output. | + +Explicit flags ghi đè environment variables, cái nào ghi đè saved configuration. Trong API-key mode, chọn tenant rõ ràng với `--org` hoặc `FP_ORG`. + + + Các cách viết `AGENTEYE_*` của những cái 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 unknown variable không phải là lỗi. Thiết lập `AGENTEYE_DASHBOARD_URL` không chuyển hướng CLI; nó bị bỏ qua và lệnh im lặng chạy so với saved dashboard thay vào đó. + + `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, 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. + Các commands mà xóa, thu hồi, chặn, giải quyết, hoặc thay thế configuration nhắc theo mặc định. Sử dụng `--yes` chỉ sau khi xác minh active organization và target. \ No newline at end of file diff --git a/docs/vi/reference/custom-agents.mdx b/docs/vi/reference/custom-agents.mdx index 571570165..6e03d2963 100644 --- a/docs/vi/reference/custom-agents.mdx +++ b/docs/vi/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- -title: "Custom agents" -description: "Instrument traces from custom agents so Failproof AI can reconstruct runs and find failures." +title: "Các tác nhân tùy chỉnh" +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" --- -Instrument traces from a custom agent with `failproofai-sdk` so Failproof AI can reconstruct each run, audit its behavior, and find evidence-backed failures. The SDK writes structured events for the Failproof daemon to deliver to Cloud. It requires Python 3.10 or newer. +Mô tả chức năng của mọi cài đặt, phương thức và trường. Nếu bạn đang thiết lập lần đầu tiên, hãy bắt đầu với hướng dẫn — trang này dùng để tra cứu thông tin. -Tracing makes custom agents observable and auditable. Preventing an unsafe action before it executes also requires an enforcement hook in your runtime. + + + Cài đặt, thiết lập công cụ, các phương thức sự kiện, ví dụ thực tế và những vấn đề phổ biến. + + + LangChain, CrewAI, LlamaIndex và Pydantic AI tự động thiết lập với một lệnh duy nhất. + + - - To enforce policies in a custom agent setup, [contact Failproof AI](mailto:support@befailproof.ai). We will help map your runtime's model, tool, and lifecycle boundaries to policy hooks. - +Python 3.10 hoặc mới hơn. Không có phụ thuộc runtime. -
- -
- -## Cài đặt `failproofai-sdk` - -SDK hiện được phân phối dưới dạng wheel riêng tư. Liên hệ với đối tác Failproof AI của bạn để lấy phiên bản hiện tại và quyền truy cập tải xuống. +## Cài đặt ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -Với `uv`, hãy tải wheel xuống trước và chạy `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl`. Ghim wheel trong kho tạo tác riêng hoặc khóa phụ thuộc. - -Package được cài đặt dưới dạng `failproofai-sdk` và nhập trong Python dưới dạng `failproofai`. +Gói được cài đặt dưới dạng `failproofai-sdk` và được nhập trong Python dưới dạng `failproofai_sdk`. Các bộ mở rộng framework như `failproofai-sdk[langgraph]` cài đặt chính framework; các adapter luôn được đi kèm trong wheel cơ bản. ## Kết nối daemon Failproof - 1. Đi đến **Admin → Keys** và tạo khóa với `events:add`. - 2. [Kết nối daemon Failproof đến Cloud](/vi/start/setup#connect-a-machine-to-cloud) trên máy agent. - 3. Chạy một phiên được instrumented, sau đó tìm ID chính xác của nó trong **Observe → Events**. - 4. Đi đến **Observe → Sessions**, chọn cùng môi trường và mở trace được tái cấu trúc. + 1. Đi tới **Admin → Keys** và tạo một khóa có `events:add`. + 2. [Kết nối daemon Failproof với Cloud](/vi/start/setup#connect-a-machine-to-cloud) trên máy tác nhân. + 3. Chạy một phiên thiết lập công cụ, sau đó tìm ID chính xác của nó trong **Observe → Events**. + 4. Đi tới **Observe → Sessions**, chọn môi trường tương tự và mở trace được tái tạo. - ![A custom Python agent session reconstructed as an execution graph and ordered event trace.](/images/dashboard/session-detail.png) + ![Một phiên tác nhân Python tùy chỉnh được tái tạo dưới dạng biểu đồ thực hiện và dấu vết sự kiện theo thứ tự.](/images/dashboard/session-detail.png) ```bash @@ -51,102 +46,84 @@ Package được cài đặt dưới dạng `failproofai-sdk` và nhập trong P -## Instrument một lần chạy hoàn chỉnh - -Gọi `configure()` một lần trong quá trình khởi động quy trình. Mọi lệnh gọi sự kiện chỉ sử dụng từ khóa và yêu cầu `session_id` và `agent_id` ổn định. +## Cấu hình ```python -import traceback -import uuid +import failproofai_sdk -import failproofai +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -failproofai.configure(environment="production") +| Đối số | Chức năng | +| --- | --- | +| `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à điều bạn muốn trừ khi bạn biết ngược lại. | -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +Đặt theo biến môi trường thay thế: -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) +| 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 chứ không phải ứng dụng. Một đối số `configure()` sẽ ưu tiên hơn nó. | +| `FAILPROOFAI_HOME` | Di chuyển gốc Failproof AI chứa spool. | +| `FAILPROOFAI_SDK_STRICT` | `1` làm cho lỗi thiết lập công cụ nâng cao thay vì được ghi lại. | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | `1` làm cho vấn đề tương thích framework nâng cao thay vì cảnh báo và tiếp tục. | -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + + **Không có dấu phẩy trong `environment`.** Ingest chia trường đó thành dấu phẩy để xây dựng bộ lọc của nó và bỏ qua mọi sự kiện có nhãn chứa một — vì vậy toàn bộ quá trình chạy biến mất im lặng. Viết `prod-eu`, không phải `prod,eu`. + + `configure(environment="prod,eu")` nâng cao để bạn biết ngay lập tức. `AGENTEYE_ENVIRONMENT` không thể nâng cao — 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`. + -Phát `agent_start` một lần cho mỗi diễn viên. Đối với các sub-agent, tái sử dụng `session_id` của cha mẹ, cung cấp cho mỗi diễn viên một `agent_id` riêng biệt và đặt `parent_id` thành **agent ID** của cha mẹ, không phải session ID. +Sự kiện được xếp hàng trong bộ nhớ và ghi trong nền mỗi giây `flush_interval`, có một lần xả 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 mất bất cứ điều gì chưa được ghi. -## Tham chiếu cấu hình +## Nhận dạng + +Mọi sự kiện thuộc về một phiên và một tác nhân. **Phạm vi điền vào cả hai**, vì vậy bạn hiếm khi truyền chúng: ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| Cài đặt | Hành vi | -| --- | --- | -| `base_dir` | Spool root rõ ràng. Ưu tiên hơn tất cả các biến môi trường. | -| `flush_interval` | Giây giữa các ghi nền từ bộ nhớ đến JSONL. Mặc định: `0.5`. | -| `environment` | Nhãn triển khai trên mọi sự kiện. Mặc định là `dev`. | -| `FAILPROOFAI_HOME` | Thay đổi gốc Failproof AI chứa spool `custom-agents`. | - -SDK ghi vào `base_dir` rõ ràng khi được đặt. Nếu không, nó sử dụng spool `custom-agents` của daemon Failproof dưới `FAILPROOFAI_HOME` hoặc `~/.failproofai`. +Truyề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ó ràng buộc hay truyền, cuộc gọi sẽ nâng cao `TypeError` chứ không phải phát ra một sự kiện Cloud sẽ im lặng loại bỏ. -SDK xếp hàng các lệnh gọi trong bộ nhớ và ghi các lô trên một luồng nền. Nó cũng cố gắng flush cuối cùng thông qua xử lý `atexit` của Python. Đối với worker tồn tại ngắn hạn, hãy cho phép tắt trình thông dịch bình thường; kết thúc quy trình cứng có thể làm mất các sự kiện vẫn còn trong bộ nhớ. + + Nhân dạng đi trên các biến bối cảnh. Nó theo `asyncio` tác vụ tự động, nhưng **không** các luồng mới — gói 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 mục sự kiện -Tất cả các phương thức trả về `None`. Các trường để lại là `None` bị bỏ qua chứ không được ghi dưới dạng JSON `null`. +Mười lăm phương thức. Hầu hết đều có **cặp** — bạn gọi trình mở, sau đó trình đóng, và SDK đo khoảng cách. -| Phương thức | Trường bắt buộc ngoài danh tính | Trường tùy chọn | +| | Mở | Đóng | +| --- | --- | --- | +| **Tác nhân** | `agent_start` | `agent_end` | +| | `agent_pause` | `agent_resume` | +| **Mô hình** | `model_request` | `model_response` | +| **Công cụ** | `tool_use` | `tool_result` | +| **Hooks** | `hook_triggered` | `hook_completed` | +| **Con người** | `human_wait` | `human_input` | + +Ba cái đứng riêng: `error`, `human_pause`, `human_interrupt`. + + + +Mọi phương thức cũng lấy `session_id` và `agent_id`, mà các phạm vi điền vào cho bạn. Bất cứ điều gì còn lại là `None` được thả ra chứ không được gửi dưới dạng JSON `null`, và mọi phương thức đều trả về `None`. + +| Phương thức | Bắt buộc | Tùy chọn | | --- | --- | --- | | `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ Tất cả các phương thức trả về `None`. Các trường để lại l | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -Sử dụng `outcome="failed"`, `"error"`, `"timeout"` hoặc `"rejected"` khi một hoàn thành nên được tính là lỗi. Các giá trị khác, bao gồm `"failure"`, không được phân loại là lỗi bởi backend hiện tại. + + + + Để đánh dấu một lần chạy là không thành công, `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ả `failure` gần như — được tính là thành công. + + +## Ghép và thời lượng + +**Một quy tắc: cung cấp cho sự kiện đóng cùng id với trình mở của nó.** Đó là những gì ghép chúng lại, và những gì cho phép SDK đo khoảng cách. + +| Cặp | Phù hợp trên | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**Không tự truyền `duration_ms`.** SDK đo nó, và truyền nó nâng cao `ValueError`. -## Quy tắc tương quan và thời lượng +Ngoại lệ duy nhất là `model_response`, nơi chỉ bạn biết độ trễ nhà cung cấp thực sự. Truyền một số nguyên milliseconds — một float nâng cao, vì cột là một số nguyên 32-bit và sẽ hạ cánh trống. -- 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`. Truyền nó riêng cho các phương thức đó sẽ tạo `ValueError`. -- ID công cụ và hook chia sẻ một bản đồ chờ xử lý trên toàn quy trình. Làm cho chúng toàn cầu duy nhất trong các phiên đồng thời và trong cả hai không gian tên; ID nhà cung cấp hoặc UUID là an toàn nhất. -- Một cặp phân chia trên các quy trình vẫn tương quan ở phía hạ lưu, nhưng SDK không thể tính toán thời lượng trong quy trình của nó. -- Bản đồ chờ xử lý chứa tối đa 10.000 lần bắt đầu và xóa mục nhập cũ nhất khi đầy. + -## Trường tùy chỉnh và tải trọng +- **Ids chỉ cần duy nhất cho mỗi loại, mỗi phiên.** Một lệnh 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ác id tương tự mà không va chạm. +- **Chúng không được xác định phạm vi cho một tác nhân.** Một cặp mở dưới một tác nhân và đóng dưới tác nhân khác vẫn khớp — đó là trường hợp bình thường trong mã đa tác nhân. +- **`request_id` là tùy chọn nhưng được khuyến nghị.** Không có nó, sự kiện mô hình ghép cặp theo thứ tự chúng đến, vì vậy hai cuộc gọi đồng thời trong cùng một tác nhân có thể không ghép cặp. +- **Một cặp chia tách giữa 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 trình mở chờ một trình đóng cùng một lúc.** Quá điểm đó cái cũ 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. -Mỗi sự kiện chấp nhận các trường từ khóa bổ sung. Sử dụng các giá trị tương thích JSON khi các truy vấn ở phía hạ lưu cần cấu trúc. Các lá không được hỗ trợ như UUID, datetimes, decimals, sets, bytes và các đối tượng mô hình được chuỗi hóa bởi writer. + -Tên tùy chỉnh được dự trữ là `timestamp`, `session_id`, `agent_id`, `type` và `environment`. Các lỗi đánh máy trường tùy chọn được chấp nhận như các trường tùy chỉnh mới, vì vậy hãy xem xét JSON phát hành khi trường tiêu chuẩn không xuất hiện trong Cloud. +## Các trường của riêng bạn -## Cung cấp và xác minh +Bất kỳ từ khóa bổ sung nào bạn truyề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 +) +``` + +Ưu tiên các loại JSON nếu bạn muốn truy vấn chúng sau. 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.** Các phụ được áp dụng cuối cùng, vì vậy một trường gọi là `model`, `tool_name` hoặc `outcome` im lặng ghi đè lên cái thực. Các adapter framework sử dụng `fw_`; làm tương tự 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 sai chính tả 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, trước tiên hãy kiểm tra chính tả. + + +Năm cái 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`. + +## 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ự kiến. Sử dụng ID phiên làm khóa xử lý 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 sự kiện mô hình, công cụ, con người, hook và lỗi xuất hiện theo thứ tự dự kiến. Sử dụng ID phiên làm khóa khắc phục sự cố chính. ```bash @@ -189,10 +203,14 @@ Tên tùy chỉnh được dự trữ là `timestamp`, `session_id`, `agent_id`, -Nếu Cloud trống, 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 ngày càng tăng chỉ đến cấu hình daemon hoặc cung cấp, trong khi một spool trống chỉ đến instrumentation hoặc thời gian tồn tại của quy trình. +Nếu Cloud trống, 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 thải SDK; một spool phát triển chỉ đến cấu hình daemon hoặc phân phối, trong khi một spool trống chỉ đến thiết lập công cụ hoặc thời gian sống quy trình. + + + Chỉ kiểm tra spool khi daemon bị dừng. Trong 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 những gì được phát thải. + -## Ngăn chặn lỗi trong thời gian chạy tùy chỉnh +## Ngăn chặn lỗi trong runtime tùy chỉnh -Sử dụng các phát hiện kiểm tra và 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 hồi 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ó 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 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 cần thiết và phản ứng dự định. Tích hợp thực thi tùy chỉnh phải tiết lộ hành động trước khi thực hiện, chuyển đầu vào có cấu trúc của nó cho động cơ chính sách và áp dụng quyết định `allow`, `instruct` hoặc `deny` kết quả. -Email [support@befailproof.ai](mailto:support@befailproof.ai) để thiết kế và xác nhận tích hợp này cho thời gian chạy của bạn. \ No newline at end of file +[Liên hệ với Failproof AI](mailto:support@befailproof.ai) và chúng tôi sẽ giúp bạn ánh xạ ranh giới mô hình, công cụ và vòng đời của runtime của bạn đối với hook 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/events-and-configuration.mdx b/docs/vi/reference/events-and-configuration.mdx index 7a13e37f4..ac25a3d11 100644 --- a/docs/vi/reference/events-and-configuration.mdx +++ b/docs/vi/reference/events-and-configuration.mdx @@ -4,35 +4,35 @@ description: "Tham khảo mô hình sự kiện, môi trường, lưu trữ cụ icon: "list-tree" --- -## Các họ sự kiện +## Các nhóm sự kiện -- Agent bắt đầu, kết thúc, tạm dừng và tiếp tục -- Yêu cầu và phản hồi từ mô hình +- Agent khởi động, kết thúc, tạm dừng và tiếp tục +- Yêu cầu và phản hồi của mô hình - Sử dụng công cụ và kết quả -- Hook được kích hoạt và hoàn tất +- Hook được kích hoạt và hoàn thành - Chờ đợi con người, nhập liệu, tạm dừng và ngắt - Lỗi rõ ràng -Mỗi sự kiện mang theo một dấu thời gian, ID phiên, ID agent, loại sự kiện và môi trường. Các trường riêng cho từng sự kiện chứa dữ liệu về mô hình, công cụ, tương quan, kết quả, nội dung, thời lượng hoặc lỗi. +Mỗi sự kiện mang theo một dấu thời gian, ID phiên, ID agent, loại sự kiện và môi trường. Các trường dành riêng cho sự kiện chứa dữ liệu mô hình, công cụ, tương quan, kết quả, nội dung, thời lượng hoặc lỗi. ## Kiểm tra hợp đồng sự kiện 1. Mở **Observe → Events**. - 2. Đặt một cửa sổ thời gian ngắn và lọc theo môi trường, agent và loại sự kiện. - 3. Chọn một sự kiện để kiểm tra các trường đã chuẩn hóa và payload thô của nó, sau đó mở phiên của nó để xem bối cảnh thực thi. - 4. Nếu thiếu một thời lượng được ghép đôi, hãy xác minh rằng các sự kiện bắt đầu và hoàn tất sử dụng cùng một ID tương quan. + 2. Đặt một khoảng thời gian ngắn và lọc theo môi trường, agent và loại sự kiện. + 3. Chọn một sự kiện để kiểm tra các trường được chuẩn hóa và payload thô của nó, sau đó mở phiên của nó để xem ngữ cảnh thực thi. + 4. Nếu thiếu một thời lượng được ghép nối, hãy xác minh rằng các sự kiện khởi động và hoàn thành sử dụng cùng một ID tương quan. - Sử dụng luồng Events để thu hẹp dữ liệu thành một lần chạy agent và kiểm tra các trường sự kiện đã chuẩn hóa. + Sử dụng luồng Events để thu hẹp dữ liệu thành một lần chạy agent duy nhất và kiểm tra các trường sự kiện được chuẩn hóa. ![Luồng Events trực tiếp với bộ lọc cho môi trường, agent, phiên và loại sự kiện.](/images/dashboard/events-stream.png) - Sau đó, theo dõi sự kiện vào phiên của nó. Dấu vết hiển thị những gì đã xảy ra ngay trước và sau nó, điều này là cần thiết khi payload một mình là không rõ ràng. + Sau đó, theo dõi sự kiện vào phiên của nó. Dấu vết cho thấy những gì đã xảy ra ngay trước và sau nó, điều này là cần thiết khi payload chỉ riêng lẻ gây nhầm lẫn. - ![Dấu vết phiên được liên kết được sử dụng để kiểm tra sự kiện trong bối cảnh thực thi.](/images/dashboard/session-detail.png) + ![Dấu vết phiên được liên kết được sử dụng để kiểm tra sự kiện trong ngữ cảnh thực thi.](/images/dashboard/session-detail.png) - So sánh ID tương quan và dấu thời gian trên cả hai chế độ xem khi một sự kiện được ghép đôi hoặc thời lượng bị thiếu. + So sánh ID tương quan và dấu thời gian trên cả hai chế độ xem khi thiếu một sự kiện hoặc thời lượng được ghép nối. Khám phá các giá trị bộ lọc hợp lệ, sau đó tìm nạp payload sự kiện đầy đủ cho một phiên: @@ -51,16 +51,16 @@ Mỗi sự kiện mang theo một dấu thời gian, ID phiên, ID agent, loại -## Trường SDK được bảo lưu +## Các trường SDK được bảo lưu -Không sử dụng `timestamp`, `session_id`, `agent_id`, `type` hoặc `environment` làm trường SDK Python tùy chỉnh. Các thời lượng sự kiện được ghép đôi như thời lượng kết quả công cụ được tính toán bởi SDK và không thể được cung cấp theo cách thủ công. +Không sử dụng `timestamp`, `session_id`, `agent_id`, `type` hoặc `environment` làm các trường Python SDK tùy chỉnh. Thời lượng sự kiện được ghép nối chẳng hạn như thời lượng kết quả công cụ được SDK tính toán và không thể được cung cấp thủ công. ## Ranh giới cục bộ - Trạng thái Failproof AI nằm dưới `~/.failproofai` trừ khi được cấu hình rõ ràng khác. -- `failproofai-sdk` sử dụng `AGENTEYE_HOME` để ghi đè thư mục cơ sở kế thừa. +- `failproofai-sdk` luôn cấp dưới `~/.failproofai/custom-agents`. `FAILPROOFAI_HOME` chuyển vị trí đó; phân đoạn `custom-agents` luôn được thêm vào, do đó cấp không thể được đặt bên ngoài nó. Chỉ SDK của chính nó `configure(base_dir=...)` ghi ở nơi khác. `AGENTEYE_HOME` được đọc bởi `agenteye-collector` cũ hơn để chọn những gì để xem, và không còn ảnh hưởng đến nơi SDK ghi. - Nhãn môi trường có thể được đặt thông qua cấu hình SDK hoặc `AGENTEYE_ENVIRONMENT`. -- Thông tin xác thực daemon được lưu trữ riêng từ các cài đặt không bí mật. +- Thông tin xác thực daemon được lưu trữ riêng biệt với cài đặt không bí mật. Sử dụng tên môi trường ổn định, cardinality thấp. Dấu phẩy không được hỗ trợ trong nhãn môi trường daemon. @@ -68,11 +68,11 @@ Sử dụng tên môi trường ổn định, cardinality thấp. Dấu phẩy k - Nhãn môi trường được gán bởi SDK phát hành hoặc daemon Failproof. Sau khi thay đổi, mở **Observe → Sessions** và sử dụng bộ lọc môi trường để xác nhận các phiên mới mang giá trị mới. Các phiên hiện tại giữ lại môi trường ban đầu của chúng. + Nhãn môi trường được gán bởi SDK phát hành hoặc daemon Failproof. Sau khi thay đổi, mở **Observe → Sessions** và sử dụng bộ lọc môi trường để xác nhận các phiên mới mang giá trị mới. Các phiên hiện có giữ lại môi trường ban đầu của chúng. - Đối với `failproofai-sdk`, cấu hình môi trường trong mã hoặc với biến môi trường kế thừa của nó. Chạy lại cấu hình daemon khi thay đổi cài đặt cấp máy. + Đối với `failproofai-sdk`, hãy cấu hình môi trường trong mã hoặc với biến môi trường kế thừa của nó. Chạy lại cấu hình daemon khi thay đổi cài đặt cấp máy. ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/vi/reference/harnesses.mdx b/docs/vi/reference/harnesses.mdx index 5a431b5a2..7f9ac3dd8 100644 --- a/docs/vi/reference/harnesses.mdx +++ b/docs/vi/reference/harnesses.mdx @@ -1,72 +1,71 @@ --- ---- -title: "Các harness của Agent" -description: "Ghi lại các phiên làm việc và thực thi các chính sách trên tất cả 12 harness được hỗ trợ." +title: "Agent harnesses" +description: "Capture sessions và enforce policies across all 12 supported agent harnesses." icon: "plug-zap" --- -Harness là bất kỳ thứ gì mà agent thực sự chạy bên trong. Failproof AI hỗ trợ mười hai harness, được chia thành hai loại: +A harness là bất cứ điều gì mà agent của bạn thực sự chạy bên trong. Failproof AI hỗ trợ mười hai harness, đượ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 và assistant gateways** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistant tự lưu trữ) +- **Chat and assistant gateways** (2) — Hermes (Slack, Telegram, cron), OpenClaw (self-hosted assistant) -Các chính sách và lịch sử phiên làm việc tương tự áp dụng cho bất kỳ harness nào mà agent chạy trong đó. Một lớp bộ chuyển đổi ánh xạ tên sự kiện gốc, tên công cụ và các trường đầu vào công cụ của mỗi harness thành 29 sự kiện chuẩn trước khi bất kỳ chính sách nào chạy. +Những policies và session history giống nhau áp dụng cho bất kỳ harness nào mà agent chạy trong đó. Một adapter layer ánh xạ các event names, tool names, và tool-input fields riêng của mỗi harness onto 29 canonical events trước khi bất kỳ policy nào chạy. -Một agent chạy trong **không có** harness nào trong mười hai harness này được định hình trực tiếp bằng [Python SDK](/vi/reference/custom-agents). Đây là một hợp đồng khác, và cần được nêu rõ ràng: SDK cung cấp theo dõi, phiên làm việc, đánh giá và kiểm tra — **nó không thực thi các chính sách của riêng nó.** 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 **none** của mười hai harness này được instrument trực tiếp với [Python SDK](/vi/reference/custom-agents). Đó là một contract khác, và điều đáng lưu ý rõ ràng: SDK cung cấp tracing, sessions, evaluations và audits — **nó không enforce policies riêng lẻ.** Blocking một action không an toàn trước khi nó thực thi cần một enforcement hook tại tool boundary của runtime của bạn; [contact us](mailto:support@befailproof.ai) và chúng tôi sẽ ánh xạ nó. -| Harness | Phạm vi hook được hỗ trợ | +| Harness | Supported hook scopes | | --- | --- | | 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 đầu vào công cụ trước khi các 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à harness tiếp xúc; 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 integration normalize các native hook event names, tool names, và tool-input fields của nó trước khi policies chạy. Một policy chỉ có thể tác động lên các events mà harness expose; test end-of-turn và instruction behavior trên chính xác harness và version mà bạn deploy. -## Khả năng thực thi +## Enforcement capability -"Block" có nghĩa là kết quả trả về của bộ chuyển đổi hiện tại được sử dụng bởi harness được đặt tên. Chặn sau công cụ có thể thay thế kết quả hiển thị cho mô hình nhưng không thể hoàn tác các tác dụng phụ của công cụ đã xảy ra. +"Block" có nghĩa là verdict được trả về của adapter hiện tại được consumed bởi harness được đặt tên. Post-tool blocking có thể thay thế result được hiển thị cho model nhưng không thể undo một tool side effect đã xảy ra. -| Harness | Sự kiện chặn được xác minh | Các lưu ý chỉ quan sát hoặc không chặn | +| Harness | Verified blocking events | Observe-only or non-blocking caveats | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` và một số sự kiện task/config | `PostToolUse`, vòng đời phiên làm việc, thông báo và các sự kiện sau lỗi chỉ 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; các sự kiện session-start và compact chỉ quan sát trong bộ chuyển đổi 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; các sự kiện session và notification chỉ quan sát. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` và các sự kiện session chỉ quan sát. | -| OpenCode | `PreToolUse` | Các sự kiện post-tool và vòng đời chỉ quan sát; xử lý stop hiện tại là hướng dẫn cho một lượt sau chứ không phải là cổng được xác minh. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Các sự kiện post-tool và vòng đời chỉ quan sát; hướng dẫn stop áp dụng cho một lượt sau. | -| Hermes | `PreToolUse` | Các kết luận post-tool, session và subagent-stop không phải là cổng. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Các sự kiện post-tool, session, subagent-stop và compaction chỉ quan sát. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Các kết luận post-tool và subagent-stop chỉ quan sát. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` có điều kiện | Hook permission không chạy trong mọi chế độ permission; các sự kiện post-tool và session chỉ quan sát. | -| Antigravity CLI | `PreToolUse`, `Stop` | Các kết luận user-prompt và post-tool chỉ quan sát; prompt instructions vẫn có thể được tiêm. | -| Goose | `PreToolUse` | Các sự kiện user-prompt, post-tool và session chỉ quan sát. Một hook stop blocking gốc tồn tại phía trên nhưng không được cài đặt bởi bộ chuyển đổi hiện tại. | - -Khả năng phụ thuộc vào phiên bản. Kiểm tra lại sau khi nâng cấp một agent CLI, đặ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. - -## Cài đặt capture và policy hooks +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, và một vài task/config events | `PostToolUse`, session lifecycle, notifications, và post-failure events là observational. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Post-tool blocking thay thế result sau khi execution; session-start và compact events là observational trong adapter hiện tại. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Post-tool blocking thay thế result sau khi execution; session và notification events là observational. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` và session events là observational. | +| OpenCode | `PreToolUse` | Post-tool và lifecycle events là observational; current stop handling là guidance cho một turn sau hơn là một verified gate. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Post-tool và lifecycle events là observational; stop guidance áp dụng cho một turn sau. | +| Hermes | `PreToolUse` | Post-tool, session, và subagent-stop verdicts không phải là gates. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Post-tool, session, subagent-stop, và compaction events là observational. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Post-tool và subagent-stop verdicts là observational. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, conditional `PermissionRequest` | Permission hooks không chạy trong mọi permission mode; post-tool và session events là observational. | +| Antigravity CLI | `PreToolUse`, `Stop` | User-prompt và post-tool verdicts là observational; prompt instructions vẫn có thể được injected. | +| Goose | `PreToolUse` | User-prompt, post-tool, và session events là observational. Một native blocking stop hook tồn tại upstream nhưng không được installed bởi adapter hiện tại. | + +Capabilities phụ thuộc vào version. Re-test sau khi upgrade một agent CLI, đặc biệt là khi một policy dựa trên prompt, stop, permission, hoặc post-tool behavior thay vì common pre-tool gate. + +## Install capture and policy hooks - 1. Mở **Administration → Keys** và tạo một key 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 key được hiển thị và cài đặt hooks harness. - 3. Bắt đầu một phiên agent mới, sau đó xác nhận các sự kiện hook và phiên làm việc của nó dưới **Observe → Events**. - 4. Mở **Observe → policy** cho cùng khoảng thời gian và xác nhận một quyết định chính sách được gán cho máy. + 1. Mở **Administration → Keys** và create một key với `events:add` và `policies:pull`, được đặt tên cho machine hoặc environment. + 2. Trên target machine, connect local CLI với key được hiển thị và install các harness hooks. + 3. Start một new agent session, sau đó confirm hook và session events của nó dưới **Observe → Events**. + 4. Mở **Observe → policy** cho cùng time window và confirm một policy decision được attributed tới machine. - Kết nối bắt đầu với một machine key. Xác nhận rằng nó bao gồm cả quyền ingestion và policy-delivery trước khi sao chép secret của nó. + Kết nối bắt đầu với một machine key. Confirm rằng nó bao gồm cả ingestion và policy-delivery permissions trước khi copy secret của nó. - ![Ngăn kéo API key mới được sử dụng để cấp quyền event ingestion và policy delivery.](/images/dashboard/key-create.png) + ![The new API key drawer used to grant event ingestion and policy delivery permissions.](/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 install các hooks, Events stream sẽ hiển thị new events từ machine và environment mà bạn connected. - ![Luồng Events trực tiếp được sử dụng để xác nhận một harness mới được cài đặt đang báo cáo.](/images/dashboard/events-stream.png) + ![The live Events stream used to confirm a newly installed harness is reporting.](/images/dashboard/events-stream.png) - Cuối cùng, xác minh rằng các 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 harness đang báo cáo cả hoạt động chính sách và các sự kiện trace. + Cuối cùng, verify rằng policy decisions được attributed tới cùng machine. Điều này confirm rằng harness đang reporting policy activity cũng như trace events. - ![Trang Policy được sử dụng để xác minh các quyết định chính sách từ một harness mới được kết nối.](/images/dashboard/policy-observe.png) + ![The Policy page used to verify policy decisions from a newly connected harness.](/images/dashboard/policy-observe.png) - Cài đặt hooks cho mọi harness được phát hiện: + Install hooks cho mọi detected harness: ```bash failproofai config \ @@ -75,7 +74,7 @@ Khả năng phụ thuộc vào phiên bản. Kiểm tra lại sau khi nâng cấ failproofai policies --install ``` - Hoặc nhắm mục tiêu các harness được đặt tên và phạm vi cấu hình: + Hoặc target named harnesses và một configuration scope: ```bash failproofai policies --install \ @@ -83,9 +82,9 @@ Khả năng phụ thuộc vào phiên bản. Kiểm tra lại sau khi nâng cấ --scope user ``` - Phạm vi project giữ cấu hình hook với một repository. Phạm vi user bao quát công việc trong các repository. Claude Code cũng hỗ trợ phạm vi local; hỗ trợ thay đổi theo harness và CLI từ chối các kết hợp không được hỗ trợ. + Project scope giữ hook configuration với một repository. User scope cover work trên repositories. Claude Code cũng hỗ trợ local scope; support varies theo harness và CLI reject unsupported combinations. - Xác minh máy và các sự kiện của nó: + Verify machine và events của nó: ```bash failproofai config --status @@ -95,16 +94,16 @@ Khả năng phụ thuộc vào phiên bản. Kiểm tra lại sau khi nâng cấ -## Thêm một đường dẫn phiên làm việc không mặc định +## Add a non-default session path - 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, harness và dấu thời gian sự kiện trước khi dựa vào nó trong một kiểm tra. + Extra paths được registered trên machine, không trong Cloud. Sau khi thêm một, mở **Observe → Sessions**, filter tới environment của machine, và confirm sessions từ new path xuất hiện. Mở một session và check agent, harness, và event timestamps trước khi dùng nó trong một audit. - ![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) + ![The Sessions list filtered to the environment receiving data from the additional capture path.](/images/dashboard/sessions-list.png) - 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: + Thêm một path với một optional label, sau đó inspect các configured paths: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -113,10 +112,10 @@ Khả năng phụ thuộc vào phiên bản. Kiểm tra lại sau khi nâng cấ failproofai backfill --since 7d ``` - Xóa một đường dẫn với `failproofai harness remove-path claude checkout`. + Xoá một path với `failproofai harness remove-path claude checkout`. - 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à một quyết định chính sách thực tế trước khi mở rộng triển khai. + Run một new session sau installation. Verify cả live event stream và một actual policy decision trước khi expand rollout. \ No newline at end of file diff --git a/docs/vi/reference/overview.mdx b/docs/vi/reference/overview.mdx index 985a95011..348762adf 100644 --- a/docs/vi/reference/overview.mdx +++ b/docs/vi/reference/overview.mdx @@ -1,58 +1,61 @@ --- -title: "Tích hợp và tham chiếu" -description: "Kết nối các harness agent được hỗ trợ, SDK, CLI và HTTP API." +title: "Tích hợp và tham khảo" +description: "Kết nối các agent harness đượ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 đã chạy. +Chọn tích hợp phù hợp nhất với nơi agent của bạn đang chạy. - Cài đặt hook cho các CLI agent coding và autonomous được hỗ trợ. + Cài đặt hook cho các CLI coding và autonomous agent được hỗ trợ. - - Instrumentation traces để tìm lỗi trong custom agent, sau đó liên hệ với chúng tôi để thêm ngăn chặn vào runtime của bạn. + + Tích hợp LangGraph, CrewAI, LlamaIndex, Pydantic AI hoặc một agent tùy chỉnh. - - Xem xét các dự án cục bộ, phiên làm việc, hoạt động chính sách và audit ngoại tuyến. + + Cấu hình, danh sách sự kiện, quy tắc tương quan và gửi dữ liệu. + + + Xem lại các dự án cục bộ, phiên, hoạt động chính sách và kiểm tra ngoại tuyến. - Cấu hình ghi lại cục bộ, hook, chính sách, audit, phân phối và trạng thái máy. + Cấu hình thu thập cục bộ, hook, chính sách, kiểm tra, gửi dữ liệu và trạng thái máy. - Truy vấn và quản trị các phiên Cloud, audit, vấn đề, cảnh báo, khóa, người dùng và cài đặt. + Truy vấn và quản lý các phiên Cloud, kiểm tra, 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. + Đánh giá các phiên đầy đủ hoặc không hoạt động với dịch vụ FastAPI. - - Tạo và kiểm tra quyết định allow, instruct và deny dành riêng cho quy trình làm việc. + + Viết và kiểm tra quyết định allow, instruct và deny riêng cho từng quy trình. - - Triển khai control plane Cloud trên cụm Kubernetes do khách hàng quản lý. + + Triển khai mặt phẳng điều khiển Cloud trên 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 công khai `/v1`. Các trang được viết tay giải thích các quy trình làm việc trải dài nhiều endpoint hoặc sử dụng các giao diện quản trị bên ngoài bề mặt công khai đó. +[Tham khảo HTTP API](/vi/reference/http-api) được tạo tự động bao gồm bề mặt công khai `/v1`. Các trang được viết bằng tay giải thích các quy trình công việc spanning nhiều endpoint hoặc sử dụng các giao diện quản lý 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 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 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àm việc để tìm các trường model, tool, error và policy cần thiết cho audit. + 1. Mở **Administration → Keys**, tạo khóa với `events:add` và `policies:pull`, rồi sao chép bí mật. + 2. Cấu hình tích hợp bằng trang tương ứng ở trên. + 3. Mở **Observe → Events** để xác nhận sự kiện đến, sau đó **Observe → Sessions** để xác nhận chúng tạo thành các 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 cho các trường model, tool, error và policy cần thiết cho các kiểm tra. - Bắt đầu với 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 với ngăn kéo khóa. Các quyền được chọn xác định liệu 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 tạo khóa API mới được sử dụng để cấp quyền nhập sự kiện và phân phố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 cho thu nhận sự kiện và gử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ó đượ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 chạy hoàn chỉnh trong môi trường mong đợi. - ![Danh sách Sessions được sử dụng để xác minh rằng tích hợp mới được 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 chạy agent hoàn chỉnh.](/images/dashboard/sessions-list.png) - Mở một trong các phiên làm việc này trước khi coi tích hợp là hoàn thành; trace phải chứa các bằng chứng model, tool, error và policy mà audit của bạn cần. + Mở một trong những phiên này trước khi coi tích hợp hoàn tất; theo dõi phải chứa bằng chứng model, tool, error và policy mà các kiểm tra 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. @@ -71,8 +74,8 @@ Chọn tích hợp phù hợp nhất với nơi agent của bạn đã chạy. fp events --since 1h --env production --limit 20 ``` - Sử dụng `fp --json sessions ...` khi một công cụ khác sẽ tiêu thụ kết quả. Các cờ toàn cục như `--json`, `--org` và `--base-url` phải đặt trước lệnh. + Sử dụng `fp --json sessions ...` khi một công cụ khác sẽ tiêu thụ kết quả. Các cờ toàn cục như `--json`, `--org` và `--base-url` phải đứng trước lệnh. - Xem [tham chiếu Failproof AI CLI](/vi/reference/failproof-cli) để biết các lệnh cục bộ và [tham chiếu Failproof Cloud CLI](/vi/reference/cloud-cli#cli-commands) để biết các lệnh `fp`. + 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`. \ No newline at end of file diff --git a/docs/vi/reference/troubleshooting.mdx b/docs/vi/reference/troubleshooting.mdx index 6b18c074c..3ccd074f7 100644 --- a/docs/vi/reference/troubleshooting.mdx +++ b/docs/vi/reference/troubleshooting.mdx @@ -1,6 +1,6 @@ --- title: "Khắc phục sự cố" -description: "Chẩn đoán các phiên bị thiếu, chính sách bị thiếu, lỗi gửi và các hành động của agent bị chặn." +description: "Chẩn đoán các phiên bị thiếu, chính sách bị thiếu, lỗi gửi và các hành động agent bị chặn." icon: "wrench" --- @@ -8,9 +8,9 @@ icon: "wrench" - Mở **Administration → Keys** và xác nhận khóa máy đang hoạt động và có `events:add`. Sau đó mở **Observe → Events**, mở rộng phạm vi thời gian và xóa các bộ lọc môi trường và agent. Nếu có sự kiện, tìm kiếm ID phiên và sau đó kiểm tra **Observe → Sessions** để xem nhóm. Nếu không có sự kiện, chẩn đoán daemon Failproof từ CLI. + Mở **Administration → Keys** và xác nhận khóa máy đang hoạt động và có `events:add`. Sau đó mở **Observe → Events**, mở rộng phạm vi thời gian và xóa các bộ lọc environment và agent. Nếu có sự kiện, tìm kiếm ID phiên và sau đó kiểm tra **Observe → Sessions** để xem nhóm. Nếu không có sự kiện nào, hãy chẩn đoán daemon Failproof từ CLI. - ![Luồng Events trực tiếp với các bộ lọc chính và sự kiện agent gần đây đến.](/images/dashboard/events-stream-current.png) + ![Luồng sự kiện trực tiếp với các bộ lọc chính và các sự kiện agent gần đây đang đến.](/images/dashboard/events-stream-current.png) ```bash @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - Xác nhận rằng tính năng capture được bật, khóa được cấu hình có `events:add` và bộ lọc dashboard khớp với môi trường được phát hành. + Xác nhận rằng chế độ thu thập đã được bật, khóa được cấu hình có `events:add` và bộ lọc dashboard phù hợp với environment được phát ra. - + - Xóa các bộ lọc trong **Observe → Events** và tìm kiếm ID phiên SDK chính xác. Nếu không xuất hiện gì, kiểm tra spool SDK và daemon Failproof trên máy nguồn. + Xóa các bộ lọc trong **Observe → Events** và tìm kiếm ID phiên SDK chính xác. Nếu không xuất hiện gì, hãy kiểm tra spool SDK và daemon Failproof trên máy nguồn. ```bash @@ -36,14 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - Xác nhận rằng quy trình agent đặt `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` và `$FAILPROOFAI_HOME/custom-agents`, nếu không thì `~/.failproofai/custom-agents`, tồn tại trước khi SDK khởi động. + Xác nhận một daemon đang chạy và được kết nối — SDK spool bất kể có hay không. Thư mục spool **không** cần tồn tại trước (writer sẽ tạo nó) và không có biến môi trường nào chọn nó: `$FAILPROOFAI_HOME/custom-agents`, nếu không thì `~/.failproofai/custom-agents` là thư mục gốc duy nhất, và `configure(base_dir=...)` là ghi đè duy nhất. Nếu tiến trình bị `SIGKILL` hoặc OOM-killed, bất cứ thứ gì vẫn còn trong hàng đợi đã bị mất — xử lý `SIGTERM` để giới hạn điều đó. - Mở **Admin → enforcement**, chọn máy và so sánh các phiên bản được gán, được báo cáo và phiên bản trước đó của nó. Xác nhận rằng phạm vi triển khai bao gồm máy và khóa của nó có `policies:pull`. Ingest có thể hoạt động ngay cả khi gửi chính sách không hoạt động. + Mở **Admin → enforcement**, chọn máy và so sánh các phiên bản được gán, báo cáo và trước đó của nó. Xác nhận phạm vi triển khai bao gồm máy và khóa của nó có `policies:pull`. Ingest có thể hoạt động ngay cả khi gửi chính sách không hoạt động. @@ -53,14 +53,14 @@ icon: "wrench" failproofai config --status ``` - Xác nhận rằng ID máy và nhãn khớp với mục tiêu dashboard. Kết nối lại bằng khóa có khả năng chính sách nếu thông tin xác thực hiện tại chỉ cấp quyền lấy sự kiện. + Xác nhận ID máy và nhãn phù hợp với mục tiêu dashboard. Kết nối lại với khóa có khả năng chính sách nếu thông tin xác thực hiện tại chỉ cấp quyền ingest sự kiện. - Mở **Admin → enforcement** và kiểm tra thời gian lần cuối máy được nhìn thấy và phiên bản được báo cáo. Nếu máy lỗi thời, xử lý đây là vấn đề daemon cục bộ. Không làm yếu chính sách được triển khai chỉ để bỏ qua một daemon không khả dụng. + Mở **Admin → enforcement** và kiểm tra thời gian cuối cùng được nhìn thấy của máy và phiên bản được báo cáo. Nếu máy đã lỗi thời, hãy coi đây là vấn đề daemon cục bộ. Không làm yếu chính sách triển khai chỉ để bỏ qua daemon không khả dụng. @@ -71,18 +71,18 @@ icon: "wrench" failproofai config --status ``` - Khởi động lại hoặc cập nhật `failproofaid`; chạy lại cấu hình khi phiên bản giao thức CLI và daemon khác nhau. Đường dẫn daemon được cấu hình bị lỗi khi đóng theo thiết kế. + Khởi động lại hoặc cập nhật `failproofaid`; chạy lại cấu hình khi phiên bản giao thức CLI và daemon khác nhau. Đường dẫn daemon được cấu hình tất yếu thất bại theo thiết kế. - + - Đối với chính sách do Cloud tạo, mở **Admin → policy editor**, chọn bản nháp và xem lỗi xác thực trước khi xuất bản. Đối với chính sách cục bộ, sử dụng CLI để xác thực nó, sau đó mở **Observe → policy** sau một hành động kiểm tra để xác nhận các quyết định đến. + Đối với chính sách được tạo trên Cloud, mở **Admin → policy editor**, chọn bản nháp và xem lỗi xác thực trước khi xuất bản. Đối với chính sách cục bộ, sử dụng CLI để xác thực nó, sau đó mở **Observe → policy** sau một hành động kiểm tra để xác nhận quyết định đến. - Xác nhận rằng tên tệp kết thúc bằng `policies.js`, `policies.mjs` hoặc `policies.ts`, mô-đun gọi `customPolicies.add(...)` và nhập được giải quyết từ tệp chính sách. + Xác nhận tên tệp kết thúc bằng `policies.js`, `policies.mjs` hoặc `policies.ts`, mô-đun gọi `customPolicies.add(...)` và các import được phân giải từ tệp chính sách. ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -91,14 +91,14 @@ icon: "wrench" - + - Mở **Analyze → audits**, chọn lần chạy và kiểm tra xem phân tích mô hình có chạy hay không. Sau đó so sánh phạm vi và cửa sổ của nó với **Observe → sessions** và mở các dấu vết đại diện từ dân số đó. + Mở **Analyze → audits**, chọn lần chạy và kiểm tra xem phân tích mô hình có chạy không. Sau đó so sánh phạm vi và cửa sổ của nó với **Observe → sessions** và mở các dấu vết tiêu biểu từ dân số đó. - Kết quả bằng không chỉ có ý nghĩa khi phân tích chạy thành công. Nếu phân tích bị bỏ qua hoặc thất bại, lần chạy không tạo ra kết quả nào và giữ cho cửa sổ chưa được phân tích mở cho lần chạy thành công trong tương lai. Nếu phân tích mô hình bị vô hiệu hóa, kiểm tra cũng không tạo ra kết quả nào vì quét thông tin xác thực xác định và PII ghi lại thống kê nhưng không còn tạo kết quả. + Kết quả bằng không chỉ có ý nghĩa khi phân tích chạy thành công. Nếu phân tích bị bỏ qua hoặc thất bại, lần chạy không tạo ra kết quả và giữ cửa sổ chưa được phân tích mở cho lần chạy thành công trong tương lai. Nếu phân tích mô hình bị vô hiệu hóa, cuộc kiểm toán cũng không tạo ra kết quả vì quét thông tin xác thực xác định và PII ghi lại thống kê nhưng không còn tạo ra kết quả. - ![Biểu mẫu kiểm tra nơi môi trường, agent, tần suất và cửa sổ quét xác định dân số phiên.](/images/dashboard/audit-new.png) + ![Biểu mẫu kiểm toán trong đó environment, agent, nhịp điệu và cửa sổ quét xác định dân số phiên.](/images/dashboard/audit-new.png) ```bash @@ -110,27 +110,31 @@ icon: "wrench" fp audits findings --audit ``` - Nếu lần chạy vẫn trong hàng đợi, chờ dung lượng audit-agent hoặc yêu cầu nhà điều hành triển khai kiểm tra đội kiểm tra. Một kiểm tra trong hàng đợi sẽ thử lại; nó không bị bỏ qua ngay lập tức. + Nếu lần chạy vẫn ở trong hàng đợi, hãy đợi dung lượng audit-agent hoặc yêu cầu toán tử triển khai kiểm tra fleet kiểm toán. Một cuộc kiểm toán ở trong hàng đợi sẽ thử lại; nó không bị bỏ qua ngay lập tức. - + - Mở một phiên đã hoàn tất và kiểm tra xem đánh giá thручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручручurchurchurch्ञरन्र्घ + Mở một phiên đã hoàn thành và kiểm tra xem đánh giá thручручthủ công có thành công không. Cloud được lưu trữ hiện tại không có kiểm soát điểm cuối đánh giá trong dashboard; toán tử máy chủ phải cấu hình nó. + + + Xác minh bộ đánh giá, sau đó kiểm tra các trạng thái đánh giá gần đây: + ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - Trên Cloud tự lưu trữ, xác nhận `EVALUATOR_ENDPOINT` có mặt trên máy chủ và `EVALUATOR_TOKEN` khớp với evaluator. Đánh giá tự động bị vô hiệu hóa khi điểm cuối vắng mặt. + Trên Cloud tự lưu trữ, xác nhận `EVALUATOR_ENDPOINT` có trên máy chủ và `EVALUATOR_TOKEN` khớp với bộ đánh giá. Đánh giá tự động bị vô hiệu hóa khi điểm cuối không có. - Sử dụng trình chuyển đổi tổ chức và xác nhận slug và quyền hạn dự kiến trước khi so sánh kết quả với CLI. + Sử dụng bộ chuyển tổ chức và xác nhận slug dự kiến và quyền trước khi so sánh kết quả với CLI. ```bash @@ -139,18 +143,18 @@ icon: "wrench" fp orgs perms ``` - Ở chế độ khóa API, chỉ định `fp --org --api-key ...` hoặc đặt `AGENTEYE_ORG`. Trạng thái tổ chức phiên con người được lưu có ý định bị bỏ qua đối với yêu cầu khóa API. + Ở chế độ khóa API, chỉ định `fp --org --api-key ...` hoặc đặt `AGENTEYE_ORG`. Trạng thái tổ chức phiên con người đã lưu có chủ ý bị bỏ qua cho các yêu cầu khóa API. - + - Mở **Observe → policy**, bảo tồn quyết định và phiên liên kết, và xác định điều kiện dương tính giả. Sau đó mở **Admin → enforcement** và quay lại các máy bị ảnh hưởng phiên bản trước. Tạo phiên bản hẹp hơn trong **Policy editor**, kiểm tra trên phạm vi nhỏ và chỉ mở rộng sau khi công việc hợp lệ thành công. + Mở **Observe → policy**, bảo toàn quyết định và phiên liên kết, và xác định điều kiện dương tính giả. Sau đó mở **Admin → enforcement** và quay lui các máy bị ảnh hưởng về phiên bản trước đó. Tạo phiên bản hẹp hơn trong **Policy editor**, kiểm tra nó trên phạm vi nhỏ, và chỉ mở rộng sau khi công việc hợp lệ thành công. - Rollback triển khai Cloud chỉ có trên dashboard. Tạm dừng phiên cục bộ không vô hiệu hóa các chính sách do Cloud quản lý. Nếu dashboard không khả dụng, hãy chụp trạng thái máy và triển khai rồi khôi phục quyền truy cập dashboard thay vì cố gắng lại hành động bị chặn nhiều lần. + Quay lui triển khai Cloud chỉ là dashboard. Tạm dừng phiên cục bộ không vô hiệu hóa chính sách do Cloud quản lý. Nếu dashboard không khả dụng, hãy chụp trạng thái máy và triển khai và khôi phục quyền truy cập dashboard thay vì thử lại hành động bị chặn nhiều lần. ```bash failproofai config --status @@ -160,4 +164,4 @@ icon: "wrench" -Khi liên hệ hỗ trợ, hãy bao gồm phiên bản CLI, harness, môi trường, ID phiên hoặc triển khai liên quan và đầu ra của `failproofai config --status` với các bí mật được xóa. \ No newline at end of file +Khi liên hệ với hỗ trợ, hãy bao gồm phiên bản CLI, harness, environment, ID phiên hoặc triển khai liên quan và đầu ra của `failproofai config --status` với các bí mật đã được xóa. \ No newline at end of file diff --git a/docs/vi/sessions/live-events.mdx b/docs/vi/sessions/live-events.mdx index beed226a3..0576f2ac6 100644 --- a/docs/vi/sessions/live-events.mdx +++ b/docs/vi/sessions/live-events.mdx @@ -1,22 +1,21 @@ --- ---- title: "Sự kiện trực tiếp" -description: "Theo dõi hoạt động của agent khi một phiên đang chạy." +description: "Theo dõi hoạt động của agent khi phiên làm việc đang chạy." icon: "radio" --- -Sự kiện trực tiếp giúp bạn xác nhận cơ chế đo lường và theo dõi một lần chạy có rủi ro mà không cần chờ phiên kết thúc. +Sự kiện trực tiếp giúp bạn xác nhận việc thiết lập công cụ và theo dõi các lần chạy có rủi ro mà không cần chờ phiên làm việc kết thúc. ## Theo dõi hoạt động 1. Đi tới **Observe → Events**. - 2. Bắt đầu với cửa sổ thời gian hiện tại và không có bộ lọc để xác nhận dữ liệu đang được nhận. - 3. Lọc theo môi trường, loại sự kiện, agent hoặc phiên. Sử dụng tìm kiếm để tìm văn bản trong tải trọng dữ liệu. - 4. Chọn một sự kiện để kiểm tra tóm tắt và chi tiết của nó. Theo liên kết phiên của nó để xem dấu vết đầy đủ. + 2. Bắt đầu với cửa sổ thời gian hiện tại và không có bộ lọc để xác nhận dữ liệu đang đến. + 3. Lọc theo môi trường, loại sự kiện, agent, hoặc phiên. Sử dụng tìm kiếm cho văn bản tải trọng. + 4. Chọn một sự kiện để kiểm tra tóm tắt và chi tiết của nó. Làm theo liên kết phiên của nó để xem toàn bộ dấu vết. - ![Dòng sự kiện trực tiếp hiển thị lưu lượng từ cổng trò chuyện Hermes cùng với các lần chạy coding-CLI, được lọc theo thời gian, môi trường, loại sự kiện, agent, mô hình, bối cảnh và phiên.](/images/dashboard/events-stream-current.png) + ![Dòng Events trực tiếp cho thấy lưu lượng từ cổng Hermes chat cùng với các lần chạy coding-CLI, được lọc theo thời gian, môi trường, loại sự kiện, agent, mô hình, ngữ cảnh và phiên.](/images/dashboard/events-stream-current.png) ```bash @@ -25,22 +24,22 @@ Sự kiện trực tiếp giúp bạn xác nhận cơ chế đo lường và the fp --json events --full --session-id --all ``` - Luồng mặc định bỏ qua các tải trọng dữ liệu thô. Chỉ sử dụng `--full` cho việc điều tra phiên giới hạn. + Nguồn cấp mặc định bỏ qua các tải trọng thô. Chỉ sử dụng `--full` để điều tra phiên bị ràng buộc. -Sử dụng dòng sự kiện để trả lời ba câu hỏi cấp bách: +Sử dụng dòng sự kiện để trả lời ba câu hỏi ngay lập tức: - Agent mong đợi có đang báo cáo tới môi trường chính xác không? -- Các lệnh gọi mô hình, lệnh gọi công cụ và quyết định chính sách có đến đúng thứ tự không? -- Phiên đã dừng tiến triển hay bắt đầu lặp lại một hành động? +- Các lệnh gọi mô hình, lệnh gọi công cụ và quyết định chính sách có đến theo thứ tự không? +- Phiên có dừng tiến hành hoặc bắt đầu lặp lại một hành động không? -Các loại sự kiện bao gồm sự kiện vòng đời agent, yêu cầu và phản hồi của mô hình, sử dụng công cụ và kết quả, thực thi hook, chờ đợi con người và ngắt, cũng như lỗi rõ ràng. ID tương quan kết hợp các sự kiện được ghép nối như một lệnh gọi công cụ và kết quả của nó. +Các loại sự kiện bao gồm sự kiện vòng đời của agent, yêu cầu và phản hồi mô hình, sử dụng công cụ và kết quả, thực thi hook, chờ đợi và ngắt của con người, và các lỗi rõ ràng. ID tương quan kết nối các sự kiện được ghép nối như lệnh gọi công cụ và kết quả của nó. - Giữ chế độ xem trực tiếp rộng trong khi xác minh một tích hợp mới. Chỉ thêm bộ lọc sau khi bạn thấy sự kiện đầu tiên; một bộ lọc không chính xác có thể trông giống như việc nhập không thành công. + Giữ chế độ xem trực tiếp rộng khi xác minh một tích hợp mới. Chỉ thêm bộ lọc sau khi bạn thấy sự kiện đầu tiên; bộ lọc không chính xác có thể trông giống như việc tiếp nhận dữ liệu không thành công. -Nếu không có sự kiện nào xuất hiện, chạy `failproofai config --status`, sau đó [khắc phục sự cố nhập liệu](/vi/reference/troubleshooting). +Nếu không có sự kiện nào xuất hiện, hãy chạy `failproofai config --status`, sau đó [khắc phục sự cố tiếp nhận dữ liệu](/vi/reference/troubleshooting). -Các agent không chạy trong một trong 12 [harnesses](/vi/reference/harnesses) được hỗ trợ sẽ báo cáo các loại sự kiện giống nhau thông qua [Python SDK](/vi/reference/custom-agents), bao gồm các sự kiện human-in-the-loop (`human_wait`, `human_input`, `human_interrupt`) mà các agent cổng và sản xuất phụ thuộc vào. \ No newline at end of file +Các agent không chạy trong một trong 12 [harnesses](/vi/reference/harnesses) được hỗ trợ báo cáo các loại sự kiện giống nhau thông qua [Python SDK](/vi/reference/custom-agents), bao gồm các sự kiện con người trong vòng lặp (`human_wait`, `human_input`, `human_interrupt`) mà các agent gateway và sản xuất phụ thuộc vào. \ No newline at end of file diff --git a/docs/vi/start/first-policy.mdx b/docs/vi/start/first-policy.mdx index 8f2ae4666..af81d6718 100644 --- a/docs/vi/start/first-policy.mdx +++ b/docs/vi/start/first-policy.mdx @@ -1,34 +1,34 @@ --- --- -title: "Ngăn chặn lỗi đầu tiên của bạn bằng một chính sách" -description: "Tạo một phiên bản chính sách, triển khai nó ở chế độ quan sát, rồi thực thi nó." +title: "Ngăn chặn lần thất bại đầu tiên bằng một chính sách" +description: "Tạo một phiên bản chính sách, triển khai nó ở chế độ quan sát, và sau đó thực thi nó." icon: "shield-check" --- -Chỉ sử dụng một chính sách sau khi bạn có thể mô tả hành động không an toàn và những hành động hợp pháp phải được cho phép. +Chỉ sử dụng một chính sách sau khi bạn có thể mô tả hành động không an toàn và những hành động hợp pháp phải được phép thực hiện. - Đi tới **Admin → policy editor**. Bắt đầu với chính sách demo, xem xét hoặc chỉnh sửa mã nguồn của nó, rồi chọn **publish version**. Xuất bản sẽ tạo phiên bản bất biến mà bạn có thể triển khai cho các máy. + Đi tới **Admin → policy editor**. Bắt đầu với chính sách demo, xem xét hoặc chỉnh sửa mã nguồn của nó, sau đó chọn **publish version**. Xuất bản tạo ra phiên bản bất biến mà bạn có thể triển khai cho các máy. - ![Chế độ soạn của trình chỉnh sửa chính sách với chính sách demo sẵn sàng để xuất bản dưới dạng một phiên bản bất biến.](/images/dashboard/policy-editor.png) + ![Chế độ xác thực của Trình soạn thảo chính sách với một chính sách demo sẵn sàng xuất bản dưới dạng phiên bản bất biến.](/images/dashboard/policy-editor.png) Đi tới **Admin → enforcement**, mở rộng máy mục tiêu, và chọn **edit this machine**. Thêm chính sách demo đã xuất bản, ghim phiên bản của nó, chọn **observe**, và áp dụng triển khai. - ![Trình chỉnh sửa triển khai máy với phiên bản chính sách đã xuất bản được chọn ở chế độ quan sát trước khi áp dụng triển khai.](/images/dashboard/enforcement-editor.png) + ![Trình chỉnh sửa triển khai máy với một phiên bản chính sách đã xuất bản được chọn ở chế độ quan sát trước khi áp dụng triển khai.](/images/dashboard/enforcement-editor.png) - Chạy một phiên làm việc agent mới trên máy đó, rồi mở **Observe → policy**. Chọn máy và xác nhận rằng chính sách demo xuất hiện trong ánh xạ chính sách và dòng thời gian quyết định. Chế độ quan sát ghi lại những gì chính sách sẽ làm mà không chặn hành động. + Chạy một phiên làm việc tác nhân mới trên máy đó, sau đó mở **Observe → policy**. Chọn máy và xác nhận rằng chính sách demo xuất hiện trong ánh xạ chính sách và dòng thời gian quyết định. Chế độ quan sát ghi lại những gì chính sách sẽ làm mà không chặn hành động. - ![Trang Chính sách hiển thị tổng quyết định, hoạt động thực thi theo thời gian, và ánh xạ chính sách được quản lý cục bộ và trên Cloud.](/images/dashboard/policy-observe.png) + ![Trang Chính sách hiển thị tổng số quyết định, hoạt động thực thi theo thời gian, và ánh xạ chính sách do địa phương và Cloud quản lý.](/images/dashboard/policy-observe.png) - Tạo chính sách trên Cloud và triển khai lfleet là các quy trình quản trị. Sử dụng CLI cục bộ để xác thực chính sách tương tự trước khi xuất bản: + Tạo chính sách Cloud và triển khai hfleet là các quy trình làm việc hành chính. Sử dụng CLI cục bộ để xác thực chính sách tương tự trước khi xuất bản nó: ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -36,13 +36,13 @@ Chỉ sử dụng một chính sách sau khi bạn có thể mô tả hành đ failproofai config --status ``` - Sử dụng `fp` để kiểm tra các quyết định chính sách có thể nhìn thấy trên Cloud: + Sử dụng `fp` để kiểm tra các quyết định chính sách nhìn thấy từ Cloud: ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - CLI trên Cloud không hiển thị các tuyến triển khai thực thi chỉ dành cho root. Xuất bản các phiên bản từ **Admin → policy editor** và triển khai chúng từ **Admin → enforcement**. + Cả hai bước đều có sẵn từ CLI: `fp policies publish ` tạo một phiên bản và `fp fleet deploy --add ` đặt nó trên một máy. Các tương đương trong bảng điều khiển là **Admin → policy editor** và **Admin → enforcement**. \ No newline at end of file diff --git a/docs/vi/start/integrations.mdx b/docs/vi/start/integrations.mdx new file mode 100644 index 000000000..e2a0fc92d --- /dev/null +++ b/docs/vi/start/integrations.mdx @@ -0,0 +1,121 @@ +--- +--- +title: "Công cụ hóa agent của bạn" +sidebarTitle: "Frameworks" +description: "Kết nối bất kỳ framework agent được hỗ trợ nào với Failproof AI chỉ bằng một lệnh gọi." +icon: "plug" +--- + +Agent của bạn đã tạo ra mọi thứ đáng ghi lại — các lệnh gọi mô hình, lệnh gọi công cụ, ranh giới nút, chờ đợi con người, lỗi. Framework bỏ nó đi. SDK giữ lại nó. + + + + Một agent bạn viết riêng hoặc agent không được liệt kê ở đây. + + + Graphs, nodes, tools, retrievers, models. + + + Crews, flows, agents by role, tools. + + + Workflows, steps, function agents, retrievers. + + + Typed agents, capabilities, tools, retries. + + + +## Ba dòng, bất kỳ framework nào + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # detects the frameworks you imported + +with failproofai_sdk.session(): + ... # your existing agent call, unchanged +``` + +Không có decorator trên các hàm của bạn, không có callback được truyền đến các lệnh gọi của bạn, không có id được luồng qua mã của bạn. Chỉ lệnh gọi bên trong phiên là khác: + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # under `async with failproofai_sdk.session():` + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +Bộ cài đặt thêm **framework**. Mỗi adapter được gửi trong wheel cơ sở, vì vậy dự án đã có framework của nó không cần thêm gì cả. + +## Xác nhận nó đã tới + +Chạy một phiên công cụ hóa, sau đó mở **Observe → Sessions** và chọn môi trường của bạn. Lần chạy xuất hiện dưới dạng một trace được tái tạo. + +Nếu không có gì tới, hãy xác nhận máy được kết nối bằng `failproofai config --status`. Xem [Set up capture](/vi/start/setup). + + + Không kiểm tra thư mục spool để xác nhận giao hàng. Daemon Failproof thu thập và xóa từng lô trong vòng milliseconds, vì vậy đọc nó sẽ cạnh tranh với collector và hiển thị ít sự kiện hơn nhiều so với những gì đã phát ra. + + +## Tiếp theo + +Mỗi quickstart ở trên liên kết đến hướng dẫn đầy đủ của nó — những gì được ghi lại, tùy chọn, streaming, đặt tên span và những vấn đề mà mọi người thực sự gặp phải. Chúng nằm dưới **Trace Agents → Plug in your agent**. + + + + Mô hình dữ liệu, các id, các loại sự kiện và cách các sự kiện đến Cloud. + + + Theo dõi nhân quả qua một phiên thay vì các bản ghi bị ngắt kết nối. + + + Kiểm tra các phiên bạn vừa thu thập. + + \ No newline at end of file diff --git a/docs/vi/start/integrations/crewai.mdx b/docs/vi/start/integrations/crewai.mdx new file mode 100644 index 000000000..4117c5779 --- /dev/null +++ b/docs/vi/start/integrations/crewai.mdx @@ -0,0 +1,224 @@ +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "Instrument các crews, flows, agents theo role, tools, memory, và human feedback." +icon: "/images/frameworks/crewai.svg" +--- + +## Cài đặt + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +Hỗ trợ: `crewai` 1.13 đến 2.0. 1.13 là bản release đã thêm `started_event_id` và chuẩn hóa token usage, cả hai đều là những gì adapter dựa vào để ghép các events và báo cáo tokens. + +## Instrument + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` đăng ký một listener trên event bus ở mức module của CrewAI và subscribe một handler cho mỗi event class. Không có gì về crew, agents, tasks, hoặc tools của bạn thay đổi. + +## Những gì được ghi lại + +| CrewAI | Failproof event | +| --- | --- | +| Crew kickoff | `agent_start`, `agent_end` | +| `Agent.kickoff()` (một lite agent, không có crew) | `agent_start`, `agent_end`, với `agent_id` từ role | +| Flow start và finish | `agent_start`, `agent_end`; một crew được kickoff bên trong flow method lồng dưới nó | +| Agent execution | Nested `agent_start`, `agent_end`, với `agent_id` từ role. Dưới một hierarchical process, một coworker được delegate lồng dưới manager, không nằm cạnh nó | +| Task | Không có gì; được ghi lại dưới dạng một link để children resolve thành crew | +| Flow method, guardrail | `hook_triggered`, `hook_completed` | +| Tool usage | `tool_use`, `tool_result` | +| Memory và knowledge operations | `tool_use`, `tool_result`, được đặt tên theo surface bị hit | +| LLM call | `model_request`, `model_response`, với token usage | +| Stream chunk | Được gộp vào response dưới dạng chunk count và time to first token | +| Human feedback requested | `human_wait`, `agent_pause` | +| Human feedback received | `agent_resume`, `human_input` | +| Agent execution error | `error`, sau đó `agent_end` với outcome `failed` | + +Một task không phát ra bất cứ thứ gì theo ý định. Một CrewAI task là một tập hợp con của agent execution chạy nó, vì vậy phát ra cả hai sẽ nhân đôi mỗi hàng và hiển thị chúng dưới dạng siblings. Task id và name đi kèm trên các events riêng của agent. + +Memory và knowledge operations được ghi lại dưới dạng tools, được đặt tên theo surface mà chúng hit, vì vậy chúng xuất hiện bên cạnh các tools thực tế của bạn nơi bạn có thể so sánh latency của chúng. + +Trên một hierarchical crew, nesting là thứ làm cho trace có thể đọc được: + +```text +crew +└─ manager + ├─ researcher delegated + └─ writer delegated +``` + +CrewAI parents một delegated execution trên `delegate_work_to_coworker` **tool event**, không phải trên manager trực tiếp, vì vậy adapter theo liên kết đó. Nếu không có nó, mỗi agent đều là sibling của mỗi agent khác và cấu trúc delegation bị mất. + +## Ví dụ + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # becomes agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +Handoff được nhìn thấy trong trace: span `analyst` đóng lại, span `writer` mở ra, và cả hai nằm bên trong một span `crew`. + +## Đặt tên spans của bạn + +`agent_id` đến từ `Agent(role=...)`, đó là thứ làm cho nó trở thành một dashboard facet có thể đọc được. + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # one facet entry per run +``` + +`agent_id` là một cột low-cardinality. Một role chứa run id hoặc timestamp làm giảm nó cho mỗi query bất kỳ ai chạy. Nếu một role trông như một id, adapter từ chối nó và đặt giá trị thực vào một payload field thay thế. + +## Kiểm soát session + +Được giải quyết theo thứ tự này, match đầu tiên chiến thắng: + +1. `instrument("crewai", session_id=...)` +2. Enclosing `failproofai_sdk.session()` scope +3. Một generated `uuid4().hex`, một lần cho mỗi crew hoặc flow + +Bao bọc kickoff để kiểm soát nó cho mỗi lần chạy: + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## Tùy chọn + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # pin every run to one session id +) +``` + +`session_id` là tùy chọn duy nhất adapter này đọc. Prompts và completions luôn được ghi lại, được cắt ngắn để phù hợp với payload budget. + +## Human in the loop + +CrewAI có **hai** human-in-the-loop surfaces, và cả hai đều được ghi lại dưới dạng bốn events giống nhau. + +`@human_feedback` trên một flow method đi qua CrewAI's event bus: runtime phát ra một event trước khi nó chặn một person và một cái khác sau khi có câu trả lời. + +`Task(human_input=True)` thì không. Nó gọi `input()` bên trong CrewAI's own input provider và không phát ra bất kỳ event nào cả, vì vậy adapter bao bọc provider đó trực tiếp — nếu không có nó, toàn bộ human wait là vô hình và được tính toán dưới dạng thời gian agent hoạt động. + +Bằng cách nào đi nữa, bạn nhận được: + +```text +human_wait the prompt and its options +agent_pause starts the paused-time clock +agent_resume stops it +human_input the answer, with the wait measured +``` + +`agent_pause` đến `agent_resume` là cặp duy nhất cung cấp paused time. Nếu không có nó, một human wait mười phút được tính toán dưới dạng mười phút thời gian agent hoạt động. + + + CrewAI không đặt correlation id nào trên human-feedback event, vì vậy adapter ghép chúng trên flow và method name, quay lại pause được mở gần đây nhất. Điều này là sound vì một console prompt chặn. Nếu bạn xây dựng một concurrent feedback provider, đặt `request_id` trên cả hai events. + + + + Vì đường dẫn `Task(human_input=True)` là một wrapper xung quanh CrewAI's input provider hơn là một event subscription, nó được khôi phục trên `uninstrument()` và re-raise bất cứ thứ gì `input()` raise, bao gồm `KeyboardInterrupt`, không thay đổi. + + +## Các vấn đề phổ biến + + + + Một `role` chứa UUID, timestamp, hoặc per-run suffix. Sử dụng một human role ổn định và đặt run-specific id trong task description. + + + + Event bus là asynchronous, và `kickoff()` trả về trước khi các handlers cuối cùng chạy. Drain nó trước: + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + Đây là một thuộc tính của CrewAI, không phải của SDK. + + + + `agent_end` force-closes các pauses mở nhưng không phải tools hoặc models, vì vậy một run chết bên trong một tool call để span đó mở. Teardown bình thường đóng bất cứ thứ gì vẫn mở và đánh dấu nó incomplete. Chỉ một `SIGKILL` để nó hanging, vì không có gì có thể chạy. + + + + Kiểm tra theo thứ tự này: `instrument()` chạy trước `kickoff()`; có một `with failproofai_sdk.session():` xung quanh nó; `crewai` là 1.13 hoặc mới hơn; `FAILPROOFAI_SDK_STRICT=1` đặt, vì vậy một hook degraded raise thay vì được swallowed. + + + +## Tiếp theo + + + + Pairs, ids, session lifecycle, và delivery. + + + Follow causality thông qua session bạn vừa capture. + + + LangGraph, LlamaIndex, Pydantic AI, và custom agents. + + \ No newline at end of file diff --git a/docs/vi/start/integrations/custom-agents.mdx b/docs/vi/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..6a0b9f03c --- /dev/null +++ b/docs/vi/start/integrations/custom-agents.mdx @@ -0,0 +1,737 @@ +--- +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." +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. + +Đâ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 + +```bash +pip install failproofai-sdk +``` + +Không có thêm gì, và không có phụ thuộc. + +## Công cụ hóa + +```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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # one tool call +``` + +Đọc từ trên xuống dưới và nó nói những gì nó có nghĩa: + +| Bao 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ề | + +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ì | 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 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 từ ngăn xếp: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## Cách một phạm vi đóng lại + +`agent()` xử lý ngoại lệ cho bạn: + +| Những gì xảy ra | Sự kiện | Kết quả | +| --- | --- | --- | +| 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`, 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 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 | +| --- | --- | --- | --- | +| **Agents** | `agent_start` | `agent_end` | — | +| | `agent_pause` | `agent_resume` | — | +| **Models** | `model_request` | `model_response` | — | +| **Tools** | `tool_use` | `tool_result` | — | +| **Hooks** | `hook_triggered` | `hook_completed` | — | +| **Humans** | `human_wait` | `human_input` | `human_pause`, `human_interrupt` | +| **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. + + + +```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 Models +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 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 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 Failures +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **Hai gia đình con người chỉ theo hướng ngược lại.** + + | 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 | + + 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 đồ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ụ trên API OpenAI, không có framework agent: + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +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 + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +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 + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +Đ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/`. + +## Luồng 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. + +```python +# asyncio: nothing to do +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# 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()`, 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. + +## Công cụ hóa 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ế. + +| Đường nối | Những gì bạn viết | Những gì hạ cánh | +| --- | --- | --- | +| 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) + ``` + + + Ở 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(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **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. + + + + **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 đườ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 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 đườ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 sự hoạt động. Không cần thiết phải 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. + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + 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ó. + +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. + + + + ```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 out-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 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. + + + + ```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 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 out-tok + 9 +5.727s agent_end analyst · success + 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ò. + + + + ```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 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 + ... second iteration + 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ó. + + + + ```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 + 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 + 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. + + + + ```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 out-tok + 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. + + + + + + + +**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 lấy từ hình dạng của dấu vết: + +| Trạng thái | Khi nào | +| --- | --- | +| `ongoing` | Ít nhất một span vẫn còn mở | +| `paused` | Một `agent_pause` không có `agent_resume` phù hợp | +| `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. + + + Đâ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. Bỏ qua, chúng giải quyết từ phạm vi bao quanh: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + 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`. + +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 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 | + +#### Cách các adapter giải quyết `session_id` + +Trận đấu đầ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 +3. Phạm vi `session()` bao quanh +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 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 + +Đó 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 | Được ghi lại dưới dạng | Tại sao | +| --- | --- | --- | +| `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 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 là một khía cạnh. + + + **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. + + + + + + +| Nhóm | Sự kiện | +| --- | --- | +| Agents | `agent_start`, `agent_end`, `agent_pause`, `agent_resume` | +| Models | `model_request`, `model_response` | +| Tools | `tool_use`, `tool_result` | +| Hooks | `hook_triggered`, `hook_completed` | +| 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: + +| 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 | +| 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 | +| 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 | + +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 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 | +| --- | --- | --- | +| `agent_start` | `agent_end` | `outcome`, `summary` | +| `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 | + + + 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`. 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 **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` đượ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 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() # 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 | +| --- | --- | +| `langchain` | `langgraph`, `langchain_core` | +| `crewai` | — | +| `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: + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +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. + + 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` để 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.** 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 Wrong +import failproofai_sdk +failproofai_sdk.instrument() # sys.modules has no langchain yet -> () + +import langchain # too late, nothing is wired +``` + +```python Right +import langchain # import the framework first +import failproofai_sdk + +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") +``` + + +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 + 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"] +``` + +| 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 | + +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 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ó 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. + + +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 | Được chỉnh sửa bởi `collector.redact`? | +| --- | --- | --- | +| 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** | + +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 tải trọng 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: + - 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. + + `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ả. + + + + **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 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 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 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ó. + +| Những 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 | + +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. + + + + + +## 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`. + + + + 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. + + + + 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 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 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. + + + +## Tiếp theo + + + + Cặp, id, vòng đời phiên và giao hàng. + + + 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/integrations/langchain.mdx b/docs/vi/start/integrations/langchain.mdx new file mode 100644 index 000000000..abadc814a --- /dev/null +++ b/docs/vi/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain và LangGraph" +sidebarTitle: "LangChain và LangGraph" +description: "Instrument các đồ thị, nút, công cụ, trình truy xuất và lệnh gọi mô hình chỉ bằng một lệnh gọi." +icon: "/images/frameworks/langchain.svg" +--- + +Một adapter phục vụ cả hai. LangGraph chạy trên trình quản lý callback của `langchain-core`, vì vậy việc instrument một cái sẽ instrument cái kia. + +## Cài đặt + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Đối với LangChain không có LangGraph, hãy sử dụng `failproofai-sdk[langchain]`. + +Được hỗ trợ: `langchain-core` 1.4.7 đến 2.0, `langgraph` 1.2 đến 2.0. Ngoài phạm vi đó, adapter vẫn cài đặt và cảnh báo một lần. + +## Instrument + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` đăng ký một tracer thông qua `langchain_core.tracers.context.register_configure_hook`. LangChain tiêm nó vào mọi trình quản lý callback mà nó xây dựng, vì vậy các đồ thị, công cụ và mô hình được ghi lại mà không cần thay đổi bất kỳ trang gọi nào — bao gồm những cái bên trong các thư viện mà bạn không viết. + +## Những gì được ghi lại + +| LangChain hoặc LangGraph | Sự kiện Failproof | +| --- | --- | +| Root run | `agent_start`, `agent_end` | +| Nút LangGraph | `hook_triggered`, `hook_completed` | +| Đồ thị con được biên dịch | `agent_start`, `agent_end` lồng nhau | +| Chạy công cụ | `tool_use`, `tool_result` | +| Chạy trình truy xuất | `tool_use`, `tool_result`, output được tóm tắt | +| Chạy mô hình chat hoặc LLM | `model_request`, `model_response`, với sử dụng token | +| Token được phát trực tuyến | Gập vào phản hồi dưới dạng số lượng chunk và thời gian đến token đầu tiên. Số lượng token cần `ChatOpenAI(stream_usage=True)` — xem bên dưới | +| `interrupt()` | `human_wait`, `agent_pause` | +| `Command(resume=...)` | `agent_resume`, `human_input`, tương quan trên `Interrupt.id` — bao gồm khi quá trình tiếp tục xảy ra trong một quy trình khác đối với cùng một checkpointer | +| Ngoại lệ không được xử lý | `error`, sau đó `agent_end` với kết quả `failed` | + +**Một nút trở thành hook, không phải agent lồng nhau.** `agent_id` là khía cạnh chính trên mọi bề mặt dashboard — việc nâng cao `retrieve`, `grade_documents` và `should_continue` thành các agent sẽ làm ngập nó, và gắn nhãn phiên sau bất kỳ nút nào tình cờ chạy trước tiên. + +Các span hook được hiển thị theo cách tương tự và vẫn cung cấp cho bạn chế độ xem độ trễ trên mỗi nút. + + + **Đặt tên các nút tùy thích của bạn.** Một lần chạy của nút được xác định bởi *hình dạng* của nó — một lần chạy không phải lá mang thẻ bước riêng của LangGraph — không bao giờ bằng tên của nó. + + +| Bạn viết | Những gì được ghi lại | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | Công cụ | +| `add_node("ChatOpenAI", ...)` | Lệnh gọi mô hình | + +Đặt tên một nút theo tên của thứ mà nó chạy từng làm cho sự kiện của thứ đó biến mất. Nó không còn làm như vậy nữa. + +### Phát trực tuyến + +`.stream()` và `.astream()` không phát ra các sự kiện trên mỗi token. Chúng gập vào `model_response` đóng: + +| Trường | Mang | +| --- | --- | +| `fw_chunks` | Có bao nhiêu chunk đến | +| `fw_ttft_ms` | Thời gian đến token đầu tiên | + +### Số lượng token trên phản hồi được phát trực tuyến + +Vấn đề riêng biệt, và dễ bị bỏ lỡ: OpenAI chỉ gửi sử dụng trên phản hồi được phát trực tuyến **khi được yêu cầu**. + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # nếu không có cái này, không có token +``` + +Adapter ghi lại những gì framework trao cho nó. Nếu không có cờ đó, không có gì để ghi lại, và `model_response` đến mà không có số lượng token. + +## Ví dụ + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## Đặt tên span của bạn + +Theo mặc định, span gốc lấy tên của chính đồ thị. Bọc nó để có được nhãn mà bạn chọn: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +Đối với các thiết lập đa agent, hãy lồng các phạm vi. Mỗi worker trở thành một span con mang `parent_id`: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +Giữ `agent_id` có độ cardinality thấp. Hãy sử dụng một vai trò hoặc tên nút, không bao giờ một UUID hoặc một chuỗi cho mỗi lần chạy. + +## Kiểm soát phiên + +ID phiên giải quyết theo thứ tự này, trận đấu đầu tiên thắng: + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. Phạm vi `failproofai_sdk.session()` bao quanh +4. `metadata["session_id"]`, `metadata["conversation_id"]`, hoặc `metadata["thread_id"]` +5. ID chạy gốc + +Nó không bao giờ được tạo từ đầu, vì một id tổng hợp chia một lần chạy trên nhiều phiên. + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## Tùy chọn + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # pin every run to one session id + include_chains=set(), # allowlist intermediate chains as hook pairs + capture_content=True, # False drops prompts and completions from payloads + graph_callbacks=True, # first-class interrupt and resume, needs langgraph 1.2+ +) +``` + +Đặt `capture_content=False` cho dữ liệu được quy định. Cấu trúc, thời gian, số lượng token, tên công cụ và kết quả vẫn được ghi lại; nội dung tin nhắn không. + +`include_chains` chỉ áp dụng cho các lần chạy **lồng nhau**. Một runnable mà bạn gọi ở cấp độ top level là root của phiên, vì vậy nó trở thành span agent thay vì cặp hook, và việc đặt tên cho nó ở đây không có hiệu lực. + +## Con người trong vòng lặp + +`interrupt()` tạo ra bốn sự kiện, và không có cặp nào là dư thừa: + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +`human_wait` đến `human_input` mang lời nhắc và câu trả lời (cả hai bị bỏ dưới `capture_content=False`, cùng với nguồn tài liệu truy xuất — số lượng tài liệu vẫn tồn tại). `agent_pause` đến `agent_resume` là cặp duy nhất có nguồn cung cấp thời gian tạm dừng, vì vậy nếu không có nó, một khoảng chờ con người mười phút sẽ được tính là thời gian agent hoạt động. Span gốc vẫn mở trên khoảng cách, giữ cả hai lệnh gọi trong một phiên. + +## Các vấn đề thường gặp + + + + `create_react_agent` truyền bá ngoại lệ. Để cho phép mô hình thấy lỗi và tiếp tục, hãy xây dựng nút công cụ một cách tường minh: + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + Lỗi được ghi lại dưới dạng `tool_result` mang một lỗi theo bất kỳ cách nào. Điều này chỉ quyết định xem lần chạy có tồn tại sau đó hay không. + + + + Một `llm.invoke()` trực tiếp bên ngoài bất kỳ đồ thị nào không có chạy cha, vì vậy nó mở một span gốc và phát ra cặp mô hình của nó bên trong nó. Dashboard cha rời đến một agent mở, vì vậy span là cố ý. Đặt tên cho nó: + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + Bạn đã truyền một trình xử lý Failproof trong `config={"callbacks": [...]}` cũng như gọi `instrument()`. Xóa nó. Hệ thống hook cấu hình đã bao gồm mọi trình quản lý callback trong quy trình. + + + + Họ không. LangGraph tăng `GraphInterrupt` qua cùng một đường dẫn như một ngoại lệ thực sự, vì vậy mỗi lần tạm dừng đều đến với tracer như một callback lỗi. Bất kỳ lớp con nào của `GraphBubbleUp` được coi là luồng điều khiển thay thế, vì vậy việc phê duyệt không vẽ một lỗi màu đỏ. + + + + Kiểm tra theo thứ tự này: `instrument()` chạy trước khi đồ thị thực thi; có một `with failproofai_sdk.session():` xung quanh lệnh gọi; `FAILPROOFAI_SDK_STRICT=1` đặt, vì vậy một hook bị suy giảm sẽ tăng thay vì bị nuốt. + + + +## Tiếp theo + + + + Cặp, id, vòng đời phiên và giao hàng. + + + Làm theo nhân quả thông qua phiên bạn vừa chụp. + + + CrewAI, LlamaIndex, Pydantic AI và các agent tùy chỉnh. + + \ No newline at end of file diff --git a/docs/vi/start/integrations/llamaindex.mdx b/docs/vi/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..f935ffdcd --- /dev/null +++ b/docs/vi/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "Instrument workflows, steps, function agents, and retrievers." +icon: "/images/frameworks/llamaindex.svg" +--- + +## Cài đặt + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +Hỗ trợ: `llama-index-core` 0.14.23 đến 0.15. Phiên bản 0.14.23 là phiên bản nơi workflow stream bắt đầu mang theo các sự kiện agent được gõ mà adapter này đọc. Bên dưới nó, tên mô hình và cấu trúc agent đều bị mất. + +## Instrument + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +API agent của LlamaIndex là async. Mỗi phạm vi hoạt động dưới cả `async with` và `with` và tạo ra các sự kiện giống hệt nhau. + +`instrument()` gắn một event handler và một span handler vào global dispatcher của LlamaIndex. Cùng nhau, chúng làm cho vòng lặp agent có thể nhìn thấy được, không chỉ các model call của nó. + + + Nếu không có một đối số bổ sung trên LLM của bạn, mọi token count trong trace của bạn sẽ là null. Xem [Token counts](#token-counts) bên dưới. + + +## Token counts + +`FunctionAgent` gọi `astream_chat`, và `llama-index-llms-openai` không gửi `stream_options={"include_usage": True}` khi nó streaming. Do đó, nhà cung cấp không bao giờ gửi usage chunk, và không có gì để bất kỳ instrumentation nào đọc. + +Đây là hành vi upstream của LlamaIndex. Opt in trên LLM của bạn: + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +Được đo lường trên cùng một run và mô hình: + +| | Input tokens | Output tokens | +| --- | --- | --- | +| Không có | `null` | `null` | +| Có | 148 | 17 | + +Các lệnh gọi không streaming (`llm.chat`, `llm.achat`) báo cáo usage mà không cần cấu hình. Chỉ đường dẫn streaming, là đường dẫn agent mặc định, cần điều này. + +## Những gì được ghi lại + +| LlamaIndex | Failproof event | +| --- | --- | +| `Workflow.run` root span | Session, `agent_start`, `agent_end` | +| Nested `Workflow.run` span | Nested `agent_start`, `agent_end` | +| Workflow step span | `hook_triggered`, `hook_completed` | +| LLM chat start and end | `model_request`, `model_response` | +| `FunctionTool.call` span | `tool_use`, `tool_result` | +| Retrieval start and end | `tool_use`, `tool_result`, output summarized | +| Embeddings | Không có, trừ khi `embeddings=True` | +| Một tool đang đợi một người | `human_wait`, `agent_pause`, sau đó `agent_resume`, `human_input` | +| `AgentWorkflow` handoff | Một nested `agent_start`, `agent_end` cho mỗi agent, parented đến workflow | +| Exception | `error`, sau đó `agent_end` với outcome `failed`, và `agent_end.summary` đặt tên cho nó | +| `handler.cancel_run()` | `agent_end` với outcome `cancelled` và không có `error` — một nút dừng không phải là thất bại | + +`agent_id` là `FunctionAgent.name` khi bạn đặt một, còn không thì là tên lớp workflow. Dưới một `AgentWorkflow`, mỗi agent nhận được lượt lần lượt có span nested riêng của nó dưới workflow, vì vậy handoff được đọc thành hai agent chứ không phải một. + +Output retrieval được tóm tắt thay vì được dump. Một retriever trả về các tài liệu, và lưu trữ chúng trong payload sẽ đặt corpus của bạn vào event store một lần cho mỗi truy vấn. Thay vào đó, số lượng, phạm vi điểm số và các đoạn trích bị cắt ngắn được giữ lại. + +## Ví dụ + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +Vòng lặp agent xuất hiện trong trace dưới dạng các cặp hook: `init_run`, `setup_agent`, `run_agent_step`, `parse_agent_output`, `call_tool`, và `aggregate_tool_results`. Đây là vòng lặp của chính framework, vì vậy chúng là hooks chứ không phải agents, điều này giữ `agent_id` có ý nghĩa. + +## Đặt tên cho spans của bạn + +`agent_id` là `FunctionAgent.name` khi bạn đặt một, còn không thì là tên lớp workflow. + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +Trong một `AgentWorkflow`, tên đó cũng là tên mà mỗi handoff được ghi lại dưới: + +```text +AgentWorkflow parent span +├─ city_analyst turn 1 +├─ cost_analyst turn 2 +└─ city_analyst turn 3 — a new turn, not a reopened one +``` + +Vì vậy, `agent_id` cho bạn biết **agent nào** đã làm công việc và `parent_id` cho bạn biết **workflow nào** nó thuộc về. Một agent trao lại quyền kiểm soát sau này sẽ mở một lượt thứ hai chứ không phải mở lại lượt đầu tiên của nó. + +Bọc lệnh run để ghi đè nó, hoặc để nhóm nhiều agent dưới một parent: + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +Giữ `agent_id` là low cardinality. Đây là facet chính trên mọi bề mặt dashboard, vì vậy hãy sử dụng tên vai trò hoặc workflow, không bao giờ UUID hoặc chuỗi per-run. + +## Kiểm soát session + +Adapter này **không có tùy chọn `session_id`**. Session được lấy từ phạm vi bao quanh, hoặc là `uuid4().hex` được tạo cho mỗi workflow run: + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## Tùy chọn + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True records embedding calls as tool pairs + steps=True, # False drops workflow-step hook pairs + capture_messages=True, # False drops EVERY payload: prompts, completions, + # tool arguments and output, step I/O, retrieval + # queries, the goal and the final answer + capture_limit=8192, # characters kept per captured value + stale_after=600.0, # seconds before an abandoned LEAF is force-closed + reaper_interval=30.0, # how often the reaper sweeps; 0 disables it +) +``` + +| Tùy chọn | Lý do bạn muốn thay đổi nó | +| --- | --- | +| `embeddings` | Bật khi debug embedding latency hoặc cost. Một bulk index build là hàng ngàn lệnh gọi và sẽ che phủ timeline. | +| `steps` | Tắt nếu bạn chỉ muốn model và tool events và thấy agent loop tạo nhiều tiếng ồn. | +| `capture_messages` | Tắt cho regulated data. Mọi payload dừng được ghi lại — prompts, model completion, tool arguments và return values, workflow-step input và output, retrieval queries, agent goal và final answer. Cấu trúc, timings, tokens, và outcomes vẫn được ghi lại. | +| `capture_limit` | Ký tự được giữ lại cho mỗi captured value trước khi truncation. Nâng lên khi RAG prompt hoặc retrieved context đang tới bị cắt. | +| `stale_after` | Giây trước khi một abandoned **leaf** — một streaming response không ai tiêu thụ, một model hoặc tool span mà close không bao giờ tới — bị force-closed, để session settle thay vì đọc `ongoing` mãi mãi. Nó **không** đóng một abandoned run chính nó: một workflow có tác vụ bị hủy mà không có dispatcher thấy exit giữ `agent_start` mở cho đến `uninstrument()`. | +| `reaper_interval` | Sweep frequency. Đặt thành `0` để vô hiệu hóa reaper hoàn toàn. | + +## Human in the loop + +Được ghi lại khi wait xảy ra bên trong một tool: + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +`ctx.wait_for_event` trong một plain workflow step không được ghi lại. Runtime bắt drop trước khi nó tới dispatcher, vì vậy step exits và re-runs sau này mà không có signal để key một pause. FunctionAgent pattern, mà LlamaIndex documents, waits bên trong một tool và được ghi lại đầy đủ. + +## Vấn đề thường gặp + + + + Thêm `additional_kwargs={"stream_options": {"include_usage": True}}` vào LLM của bạn. Xem [Token counts](#token-counts). + + + + LlamaIndex không có usage field tiêu chuẩn. Adapter cố gắng sử dụng nhiều hình dạng đã biết, và một integration đặt tên các bộ đếm của nó thành cái gì mới sẽ không khớp với bất kỳ cái nào trong số chúng. + + Raw dict luôn ship, vì vậy hãy kiểm tra `usage` trong payload để xem nhà cung cấp của bạn gọi chúng là gì. + + Một `usage` được điền kèm theo các token columns trống là cố ý — nó tốt hơn một số sai lệch tự tin. + + + + Đó là FunctionAgent loop, một set cho mỗi iteration. Filter by hook name trên dashboard. Step timings này thường là lý do để sử dụng adapter này thay vì một model-only. + + + + Kiểm tra theo thứ tự này: `instrument()` chạy trước run; có một `async with failproofai_sdk.session():` xung quanh `await`; `llama-index-core` là 0.14.23 hoặc mới hơn; `FAILPROOFAI_SDK_STRICT=1` set, vì vậy một degraded hook raises thay vì bị swallowed. + + + +## Tiếp theo + + + + Pairs, ids, session lifecycle, và delivery. + + + Theo causality qua session bạn vừa capture. + + + LangGraph, CrewAI, Pydantic AI, và custom agents. + + \ No newline at end of file diff --git a/docs/vi/start/integrations/pydantic-ai.mdx b/docs/vi/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..8cc85cc03 --- /dev/null +++ b/docs/vi/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "Trang bị cho các agent được gõ kiểu dữ liệu, công cụ, lệnh gọi mô hình và thử lại." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## Cài đặt + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +Hỗ trợ: `pydantic-ai-slim` phiên bản 2.0 đến 3.0. Phiên bản 2.0 đã loại bỏ `Agent(instrument=...)` và giới thiệu giao thức khả năng mà adapter này được xây dựng dựa trên, vì vậy phiên bản 1.x không thể được trang bị theo cách này. + +## Trang bị + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # trước khi xây dựng bất kỳ Agent nào + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` phải chạy trước khi bạn xây dựng một `Agent`. Khả năng được thêm vào tại thời điểm xây dựng, vì vậy một agent được xây dựng trước đó sẽ không có khả năng này và không ghi lại gì, mà không có lỗi vì không có gì sai. Đây là nguyên nhân phổ biến nhất gây ra trace rỗng với adapter này. + + +Các agent ở phạm vi module là nơi gặp phải vấn đề này: + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # được xây dựng tại thời điểm import + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # chạy cái này TRƯỚC +import agents # bây giờ agent nhận được khả năng này +``` + +Xác nhận rằng nó đã có hiệu lực: + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI hợp nhất danh sách bạn truyền thành một `root_capability` duy nhất, vì vậy không có thuộc tính `agent.capabilities` để đọc. + +Các agent được xây dựng trong khi được trang bị sẽ giữ lại khả năng này, vì vậy bạn có thể `uninstrument()` và trang bị lại mà không cần xây dựng lại chúng. + +## Những gì được ghi lại + +| Pydantic AI | Sự kiện Failproof | +| --- | --- | +| Agent run | `agent_start`, `agent_end` | +| Model request | `model_request`, `model_response`, với mức sử dụng token | +| Tool call | `tool_use`, `tool_result`, với các đối số mà mô hình đã gửi | +| `ModelRetry` từ một công cụ | `tool_result` mang theo lỗi | +| Ngoại lệ không được xử lý | `error`, sau đó `agent_end` với kết quả `failed` | + +Không có cặp hook và không có cặp human-in-the-loop ở đây. Pydantic AI không có ranh giới node hoặc step để đặt trong dấu ngoặc và không có pause cho người dùng tích hợp, vì vậy không có gì để ánh xạ. Nếu bạn xây dựng một trong hai cái, hãy phát ra các sự kiện tự mình — xem [Custom agents](/vi/reference/custom-agents). + +`output_type` không tạo ra sự khác biệt đối với trace. Một lần chạy được gõ kiểu dữ liệu và một lần chạy chuỗi ký tự tạo ra các sự kiện tương tự. + +## Ví dụ + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +Trong trace, `restock_eta` xuất hiện như một `tool_result` mang theo lỗi, tiếp theo là một lệnh gọi mô hình khác nơi agent giải quyết vấn đề đó, và lần chạy vẫn kết thúc với `success`. Cả hai sự kiện đều được ghi lại. + +## Lỗi, thử lại và luồng điều khiển + +Pydantic AI nâng cao ngoại lệ cho ba điều khác nhau, và adapter tách chúng: + +| Ngoại lệ | Được coi là | Kết quả | +| --- | --- | --- | +| `ModelRetry`, `ToolRetryError`, `ToolFailedError` | Một thất bại công cụ thực sự | `tool_result` với lỗi; lần chạy vẫn có thể kết thúc `success` | +| `SkipToolExecution`, `SkipToolValidation`, `SkipModelRequest`, `CallDeferred`, `ApprovalRequired` | Luồng điều khiển | Không phải lỗi; lần chạy đang được điều hướng | +| Bất cứ điều gì khác | Một thất bại | `error`, sau đó `agent_end` với kết quả `failed` | + +`ModelRetry` nằm trong nhóm đầu tiên một cách cố ý. Điều này có nghĩa là một nỗ lực thực sự đã thất bại và mô hình được yêu cầu thử lại, đó là những gì trường lỗi của span công cụ dành cho. Phân loại nó như luồng điều khiển sẽ che giấu các thất bại công cụ thực sự đằng sau một lần chạy thành công. + +## Đặt tên cho span của bạn + +Span chạy của Pydantic AI được đặt tên là `agent`. Bao quanh lệnh gọi để đặt cho nó một tên bạn chọn: + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +Span của framework sau đó lồng trong `inventory`, và đó là nơi các sự kiện mô hình và công cụ được ghi lại. + +Giữ `agent_id` có thẻ lực thấp. Nó là khía cạnh chính trên mọi bề mặt bảng điều khiển, vì vậy hãy sử dụng tên vai trò, không bao giờ sử dụng UUID hoặc chuỗi mỗi lần chạy. + +## Kiểm soát phiên + +Được giải quyết theo thứ tự này, kết quả phù hợp đầu tiên thắng: + +1. `instrument("pydantic_ai", session_id=...)` +2. Phạm vi `failproofai_sdk.session()` bao quanh +3. `conversation_id` của lần chạy, sau đó là `run_id` của nó +4. Một `uuid4().hex` được tạo + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## Các tùy chọn + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # ghim mọi lần chạy vào một id phiên + capture_content=True, # False loại bỏ lời nhắc và hoàn thành từ payload +) +``` + +## Các vấn đề phổ biến + + + + `Agent` được xây dựng trước khi `instrument()` chạy. Xem cảnh báo ở trên và kiểm tra `agent.root_capability.capabilities`. + + + + Một `raise` trần trụi sẽ lan truyền; đó là thiết kế của Pydantic AI. Để cho phép mô hình giải quyết vấn đề đó, hãy nâng cao `ModelRetry` với một thông báo mà nó có thể hành động. Thất bại được ghi lại dù bằng cách nào. + + + + Đó là span chạy của Pydantic AI, và đó là nơi các sự kiện mô hình và công cụ được ghi lại. Thả phạm vi của riêng bạn nếu bạn muốn một span duy nhất, với chi phí là tên tùy chỉnh. + + + + Ngăn xếp đồ thị không đồng bộ của Pydantic AI dài hơn giới hạn trường payload, và dòng cuối cùng của traceback là ngoại lệ tự nó. Trường này được cắt ngắn từ phía trước chứ không phải từ phía sau, vì vậy dòng bạn cần sẽ được giữ lại. + + + +## Tiếp theo + + + + Các cặp, ID, vòng đời phiên và giao hàng. + + + Theo dõi nhân quả thông qua phiên bạn vừa chụp. + + + LangGraph, CrewAI, LlamaIndex và các agent tùy chỉnh. + + \ No newline at end of file diff --git a/docs/vi/start/quickstart.mdx b/docs/vi/start/quickstart.mdx index 6a551d9a9..2bd072062 100644 --- a/docs/vi/start/quickstart.mdx +++ b/docs/vi/start/quickstart.mdx @@ -1,17 +1,17 @@ --- 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ó." +description: "Ghi lại một phiên làm việc của agent, tìm kiếm lỗi và bắt đầu ngăn chặn nó." icon: "zap" --- -Hướng dẫn bắt đầu nhanh này giú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 chính sách. Sử dụng skill để thiết lập Failproof AI, hoặc làm theo các bước thủ công. +Hướng dẫn bắt đầu nhanh này giúp bạn có 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 skill để thiết lập Failproof AI, hoặc thực hiện theo các bước thủ công. -**Đường dẫn nào là của bạn?** Nếu agent của bạn chạy trong 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 làm theo các bước dưới đây; bạn cần Node.js 20.9 hoặc mới hơn. Nếu agent của bạn không có harness, hãy sử dụng [Python SDK](/vi/reference/custom-agents) để tracing và kiểm toán, sau đó quay lại [Chạy kiểm tra lỗi đầu tiên của bạn](/vi/start/first-audit); việc áp dụng trên đường dẫn đó cần một hook trong runtime của bạn. +**Đây là con đường của bạn?** Nếu agent của bạn chạy trên một trong 12 [harness được hỗ trợ](/vi/reference/harnesses) — một CLI mã hóa hoặc gateway như Hermes hay OpenClaw — hãy làm theo các bước dưới đây; bạn cần Node.js phiên bản 20.9 hoặc mới hơn. Nếu agent của bạn không có harness, hãy thiết lập nó bằng [Python SDK](/vi/reference/custom-agents) để tracing và kiểm toán, sau đó 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 đường đó cần hook trong runtime của bạn. - + ```bash npx skills add FailproofAI/skills ``` @@ -21,15 +21,15 @@ Hướng dẫn bắt đầu nhanh này giúp 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, chọn tích hợp phù hợp, thực hiện thiết lập, và xác minh nó. Xem [kho FailproofAI skills](https://github.com/FailproofAI/skills) để xem các skill riêng lẻ và các tùy chọn cài đặt nâng cao. + Agent của bạn kiểm tra dự án, 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ữ skill FailproofAI](https://github.com/FailproofAI/skills) để tìm các skill riêng lẻ và các tùy chọn cài đặt nâng cao. - ## Trước khi bắt đầu + ## Trước khi bạn 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. Đi tới **Administration → Keys** và tạo một khóa với `events:add` và `policies:pull`. +2. Đi tới **Administration → Keys** và tạo khóa với `events:add` và `policies:pull`. 3. Sao chép mã bí mật một lần và lưu trữ nó trên máy đích: ```bash @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Các bản ghi phiên làm việc được gửi theo mặc định. Thêm `--no-transcripts` để báo cáo hoạt động hook và các quyết định chính sách mà không có nội dung bản ghi. + Bảng thoại phiên được gửi theo mặc định. Thêm `--no-transcripts` để báo cáo hoạt động hook và các quyết định chính sách mà không có nội dung bảng thoại. - Nếu máy này đã có lịch sử agent, hãy xem trước và nhập bảy ngày qua, sau đó chờ quá trình gửi hoàn tất. Bỏ qua bước này trên máy mới. + Nếu máy này đã có lịch sử agent, hãy xem trước và nhập bảy ngày qua, sau đó chờ quá trình gửi hoàn thành. Bỏ qua bước này trên máy mới. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Mở **Sessions** trong Failproof AI và chọn một phiên làm việc đã nhập. + Mở **Sessions** trong Failproof AI và chọn một phiên đã nhập. - - Cách này gắn Failproof AI vào harness của bạn và cài đặt 40 chính sách tích hợp. Sử dụng chúng để xem các quyết định chính sách cục bộ và thử áp dụng trước khi Failproof AI kiểm toán các phiên làm việc của bạn và viết chính sách cho agent của bạn. + + Điều này gắn Failproof AI vào harness của bạn và cài đặt 40 chính sách tích hợp sẵn. 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 phiên của bạn và viết chính sách cho các 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 rõ ràng một. Mỗi một trong 12 cái là một giá trị `--cli` hợp lệ — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Cho phép trình cài đặt phát hiện harness của bạn hoặc đặt tên một cách rõ ràng. Mỗi một trong 12 là 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 tất cả 12. Các cổng ở cuối lượt được xác minh trên 8 — xem [khả năng áp dụng](/vi/reference/harnesses#enforcement-capability) để xem ma trận theo harness. + Chặn lệnh gọi công cụ trước khi nó chạy được xác minh trên cả 12. Cổng cuối lượt được xác minh trên 8 — xem [khả năng thực thi](/vi/reference/harnesses#enforcement-capability) để tìm ma trận theo harness. - Làm 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ể chẳng hạn như "tìm các phiên làm việc nơi agent thử lại một công cụ đang thất bại mà không thay đổi cách tiếp cận của nó." + Theo dõi [Chạy kiểm tra lỗi đầu tiên của bạn](/vi/start/first-audit). Sử dụng mục tiêu cụ thể như tìm các phiên nơi agent thử lại một công cụ thất bại 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 chính sách](/vi/start/first-policy). Bắt đầu ở chế độ quan sát, kiểm tra các kết quả trùng khớp, sau đó áp dụng phiên bản đã được xem xét. + Theo dõi [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 được xem xét. - Chạy `failproofai config --status`. Một thiết lập lành mạnh sẽ báo cáo kết nối đám mây, trạng thái daemon, và liệu áp dụng 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 đám mây, 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/quickstarts/crewai.mdx b/docs/vi/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..1e4eb2195 --- /dev/null +++ b/docs/vi/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "Cài đặt, thiết lập theo dõi, và xem trace đầu tiên của bạn." +icon: "/images/frameworks/crewai.svg" +--- + +Ba bước để có trace CrewAI đầu tiên của bạn. Để tìm hiểu về những gì mỗi sự kiện mang theo, các luồng và khắc phục sự cố, xem [hướng dẫn đầy đủ](/vi/start/integrations/crewai). + +## Cài đặt + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## Thiết lập theo dõi + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +Không có gì thay đổi về crew, agents, tasks, hoặc tools của bạn. `instrument()` đăng ký theo dõi event bus ở cấp độ module của CrewAI. + +## Kiểm tra dữ liệu đã tới + +Chạy một lần, sau đó mở **Observe → Sessions** và chọn môi trường của bạn. Lần chạy của bạn sẽ xuất hiện dưới dạng một trace được tái tạo. + +Nếu không có dữ liệu nào tới, hãy xác nhận máy được kết nối bằng cách chạy `failproofai config --status`. + + + Những gì được ghi lại, các luồng, sử dụng token, đặt tên span, các tùy chọn và các vấn đề thường gặp. + \ No newline at end of file diff --git a/docs/vi/start/quickstarts/custom-agents.mdx b/docs/vi/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..fc4582cb4 --- /dev/null +++ b/docs/vi/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "Các agent tùy chỉnh" +description: "Bọc agent của bạn trong ba khối `with` và nó bắt đầu ghi lại." +icon: "code" +--- + +Dành cho một agent bạn đã viết riêng, hoặc một framework mà Failproof AI không có adapter cho. + +Bạn bọc công việc mà bạn đã làm trong các khối `with`. Mỗi khối ghi lại thời điểm bắt đầu, thời điểm kết thúc và thời gian diễn ra — bạn không cần gọi bất cứ thứ gì khác. + +## Cài đặt + +```bash +pip install failproofai-sdk +``` + +Không có thêm gì, và không có phụ thuộc. + +## Công cụ hóa + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") + +with failproofai_sdk.session(): # một lần chạy + 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) # một lệnh gọi công cụ +``` + +Đọc từ trên xuống dưới và nó nói lên ý nghĩa của nó: + +| 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ái gì đó đang làm công việc — hãy đặt cho nó một 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ề | + +Lồng chúng theo cách mã của bạn lồng nhau. Bạn không bao giờ truyền id xung quanh: mỗi khối nhớ nó nằm bên trong cái gì, vì vậy bất cứ thứ gì bạn ghi lại sẽ tự động nhận được đúng lần chạy và đúng agent. `async with` hoạt động hoàn toàn giống nhau. + +## Kiểm tra nó đã đến + +Chạy nó một lần, sau đó mở **Observe → Sessions** và chọn môi trường của bạn. Lần chạy của bạn xuất hiện dưới dạng một trace được tái tạo. + +Nếu không có gì đến, hãy xác nhận máy được kết nối bằng `failproofai config --status`. + + + Mọi phương thức sự kiện, những gì xảy ra khi mã của bạn tăng lên, một ví dụ có thực tế, luồng và async, và công cụ hóa một framework không có adapter. + \ No newline at end of file diff --git a/docs/vi/start/quickstarts/langchain.mdx b/docs/vi/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..fa9a91e58 --- /dev/null +++ b/docs/vi/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain và LangGraph" +description: "Cài đặt, cấu hình và xem trace đầu tiên của bạn." +icon: "/images/frameworks/langchain.svg" +--- + +Ba bước để có trace LangChain hoặc LangGraph đầu tiên của bạn. Để biết thêm về streaming, human-in-the-loop, đặt tên span và các tùy chọn khác, xem [hướng dẫn đầy đủ](/vi/start/integrations/langchain). + +## Cài đặt + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +Để sử dụng LangChain mà không cần LangGraph, hãy dùng `failproofai-sdk[langchain]`. + +## Cấu hình + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +Không cần thay đổi tại điểm gọi. `instrument()` đăng ký một tracer mà LangChain tiêm vào mọi callback manager mà nó xây dựng, vì vậy các graph, công cụ và mô hình đều bị ghi lại — bao gồm cả những cái bên trong các thư viện bạn không viết. + +## Kiểm tra nó đã tới + +Chạy nó một lần, sau đó mở **Observe → Sessions** và chọn môi trường của bạn. Lần chạy của bạn xuất hiện dưới dạng một trace được tái tạo. + +Nếu không có gì tới, hãy xác nhận máy được kết nối bằng `failproofai config --status`. + + + Những gì được ghi lại, streaming, số lượng token, đặt tên span, kiểm soát phiên và human in the loop. + \ No newline at end of file diff --git a/docs/vi/start/quickstarts/llamaindex.mdx b/docs/vi/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..15516ac59 --- /dev/null +++ b/docs/vi/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "Cài đặt, cấu hình, và xem trace đầu tiên của bạn." +icon: "/images/frameworks/llamaindex.svg" +--- + +Ba bước để có trace LlamaIndex đầu tiên. Để xem các bước quy trình, truy xuất, reaper và các tùy chọn, hãy xem [hướng dẫn đầy đủ](/vi/start/integrations/llamaindex). + +## Cài đặt + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## Cấu hình + +LlamaIndex's agent API là async. Mỗi scope hoạt động dưới `async with` cũng như `with`. + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + Nếu không có một đối số bổ sung trên LLM của bạn, mọi số lượng token trong trace của bạn sẽ là null — `llama-index-llms-openai` không yêu cầu sử dụng khi nó stream. Xem [Token counts](/vi/start/integrations/llamaindex#token-counts). + + +## Kiểm tra việc nhận dữ liệu + +Chạy nó một lần, sau đó mở **Observe → Sessions** và chọn môi trường của bạn. Lần chạy của bạn sẽ xuất hiện dưới dạng trace được tái cấu trúc. + +Nếu không có dữ liệu nào đến, hãy xác nhận máy được kết nối bằng `failproofai config --status`. + + + Token counts, những gì được ghi lại, các bước quy trình, truy xuất, các tùy chọn và các vấn đề phổ biến. + \ No newline at end of file diff --git a/docs/vi/start/quickstarts/pydantic-ai.mdx b/docs/vi/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..48c966635 --- /dev/null +++ b/docs/vi/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "Cài đặt, cấu hình, và xem trace đầu tiên của bạn." +icon: "/images/frameworks/pydantic-ai.svg" +--- + +Ba bước để có trace Pydantic AI đầu tiên của bạn. Để biết về các công cụ, thử lại, streaming và các tùy chọn, xem [hướng dẫn đầy đủ](/vi/start/integrations/pydantic-ai). + +## Cài đặt + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## Cấu hình + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # trước khi tạo Agent nào + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` phải chạy **trước khi** bạn tạo một `Agent`. Khả năng này được thêm vào khi tạo, do đó một agent được tạo trước đó sẽ không ghi lại gì — không có lỗi, vì không có gì sai. Đây là nguyên nhân phổ biến nhất dẫn đến trace trống với adapter này, và các agent ở phạm vi mô-đun là nơi nó xảy ra: hãy nhập `failproofai_sdk` và gọi `instrument()` trước khi nhập mô-đun xây dựng chúng. + + +## Kiểm tra dữ liệu đã đến + +Chạy nó một lần, sau đó mở **Observe → Sessions** và chọn môi trường của bạn. Lần chạy của bạn sẽ xuất hiện dưới dạng một trace được tái tạo. + +Nếu không có gì đến, hãy xác nhận máy được kết nối với `failproofai config --status`. + + + Những gì được ghi lại, các công cụ và thử lại, streaming, đặt tên span, các tùy chọn và các vấn đề thường gặp. + \ No newline at end of file diff --git a/docs/zh/index.mdx b/docs/zh/index.mdx index b708971f3..1fcd9928a 100644 --- a/docs/zh/index.mdx +++ b/docs/zh/index.mdx @@ -1,41 +1,41 @@ --- title: "让你的 agent 万无一失" -description: "为 agent 运行的每种 harness 提供可观测性与执行保障——包括编码 CLI、聊天网关、自托管助手，以及你自己的插桩 agent。" +description: "针对每种 agent 运行环境的可观测性与执行保障——编码 CLI、聊天网关、自托管助手以及你自己的插桩 agent。" icon: "shield-check" --- -Failproof AI 帮助团队了解 agent 的行为、找出失败原因，并在同样的问题再次发生前部署防护措施。 +Failproof AI 帮助团队了解 agent 的行为、找出失败原因，并在同样的问题再次发生之前部署防护措施。 -**harness** 是 agent 实际运行的环境。Failproof AI 支持接入其中 12 种——包括 Claude Code 和 Codex 等编码 CLI、Hermes 等聊天网关、OpenClaw 等自托管助手——所有事件、策略和会话历史对每种环境一视同仁。没有 harness 的 agent 可通过 [Python SDK](/zh/reference/custom-agents) 上报，该 SDK 提供追踪与审计能力；在自有运行时中执行策略则需要在你的代码中添加 hook。 +**运行环境（harness）** 是指 agent 实际运行所在的容器或框架。Failproof AI 支持接入其中 12 种——包括 Claude Code、Codex 等编码 CLI，Hermes 等聊天网关，OpenClaw 等自托管助手——所有环境共享相同的事件、策略和会话历史。没有运行环境的 agent 可通过 [Python SDK](/zh/reference/custom-agents) 接入，该 SDK 提供追踪与审计功能；若要在该环境中执行策略，则需要在你自己的运行时中添加 hook。 - 使用技能对你的项目进行插桩、连接并验证 agent 日志是否正常上报。 + 使用技能为你的项目添加插桩、完成连接，并验证 agent 日志是否正常上报。 - - 用自然语言分析、查询 agent 日志，构建仪表盘并执行审计。 + + 通过自然语言分析、查询 agent 日志，构建仪表盘并执行审计。 - - 在单个会话中追踪模型调用、工具使用、错误、人工输入、延迟和策略决策。 + + 在一个会话中追踪模型调用、工具使用、错误、人工输入、延迟及策略决策。 - - 对指定会话集合进行审计，查看有依据支撑的发现，并以 issue 的形式跟踪修复进度。 + + 对特定会话集合进行审计，审阅有证据支撑的发现，并将问题作为 issue 跟踪处理。 - 将已知的失败模式转化为策略，观察其影响，并在整个 fleet 中部署。 + 将已知的失败模式转化为策略，观察其效果，并在你的整个 agent 集群中部署。 > **会话 → 审计 → 发现 → Issue → 策略**
-> 追踪发生了什么，找出故障，管理响应，然后防止同样的行为在未来的运行中重现。 +> 追踪发生了什么，找出失败原因，管理应对措施，然后防止相同行为在后续运行中重现。 ## 从这里开始 -如果你正在部署第一个插桩 agent，请从 [快速入门](/zh/start/quickstart) 开始。如果数据已经在上报，请打开 [Sessions](/zh/sessions/overview)，先检查一次真实运行，再配置审计或策略。 +如果你正在部署第一个插桩 agent，请从[快速入门](/zh/start/quickstart)开始。如果数据已经在上报，请打开[会话（Sessions）](/zh/sessions/overview)页面，先检查一次真实的运行记录，再配置审计或策略。 - - 完成从数据采集到安全部署策略的端到端工作流。 + + 完成从日志采集到安全部署策略的端到端完整工作流。 \ No newline at end of file diff --git a/docs/zh/policies/deploy.mdx b/docs/zh/policies/deploy.mdx index f82df726c..54e03e0a6 100644 --- a/docs/zh/policies/deploy.mdx +++ b/docs/zh/policies/deploy.mdx @@ -1,47 +1,51 @@ --- title: "部署策略" -description: "将经过审核的策略版本推送到目标机器。" +description: "将经过审核的策略版本下发到目标机器。" icon: "cloud-upload" --- -部署操作将一个或多个策略版本关联到一组已注册的目标机器。 +部署将一个或多个策略版本与一组已注册的目标机器关联起来。 ## 应用部署 - + 1. 前往 **Admin → enforcement**，找到目标机器并展开其行。 - 2. 选择 **edit**，添加已审核的策略版本，并选择 **observe** 或对应的强制执行效果。 - 3. 应用更改，等待机器下次检入，确认其部署状态和覆盖状态。 + 2. 选择 **edit**，添加经过审核的策略版本，并选择 **observe** 或其强制执行效果。 + 3. 应用更改，然后等待机器下次签入，确认其部署和覆盖状态。 4. 前往 **Observe → policy** 查看实时决策。 - ![包含策略版本、enforce 和 observe 效果以及应用部署操作的机器部署编辑器。](/images/dashboard/enforcement-editor.png) + ![带有策略版本、enforce 和 observe 效果以及应用部署操作的机器部署编辑器。](/images/dashboard/enforcement-editor.png) - 云端部署接口有意未作为普通 `fp` 命令暴露。请在本地检查机器状态，再通过控制台进行部署： + 使用 `fp fleet` 通过 CLI 进行部署。在应用之前请检查生成的方案——`deploy` 会打印完整计划，并**仅在没有 `--json` 参数的交互式终端下**进行确认提示。在使用 `--json`、`--yes` 或重定向 stdin（CI 步骤、脚本、Agent 调用）时，命令会立即执行，不显示计划也不提示确认——因此如需审查，请先运行 `fp fleet show `： ```bash - failproofai config --status + fp fleet list + fp fleet show + fp fleet deploy --add no-force-push ``` - 部署完成后，使用 `fp sessions --env production --since 24h` 和 `fp events --event-type hook_completed` 验证活动是否已上报至云端。 + `fp fleet diff ` 显示预期与实际交付之间的差异（机器在下次轮询之前显示为 `behind` 状态），`fp fleet history ` 列出历史版本，`fp fleet rollback ` 回滚到指定版本——若该版本引用的策略已被禁用或删除，则会拒绝回滚。 + + 使用 `failproofai config --status` 检查机器本身的状态，并在部署后使用 `fp sessions --env production --since 24h` 和 `fp events --event-type hook_completed` 验证活动是否已上报至 Cloud。 - 部署已审核的版本而非可变草稿，优先从非生产环境机器或少量机器开始，以便逐一检查其会话。 + 部署经过审核的版本而非可变的草稿，从非生产环境的机器或小批量机器开始，以便检查其会话。 - 在不阻断工作的前提下，审查匹配结果、触发原因、受影响的工具以及误报情况。 + 在不阻塞工作的情况下，审查匹配结果、原因、受影响的工具以及误报情况。 - 在观察到的匹配结果能有效区分不安全操作与合法操作后，再提升为强制执行模式，然后确认每台目标机器均已拉取部署并正在上报决策。 + 在观察到的匹配结果能够区分不安全操作与合法操作之后，再提升为强制执行，然后确认每台目标机器已拉取部署并正在上报决策。 -机器需具备 `policies:pull` 能力。事件上报由 `events:add` 单独控制；当您期望云端进行分析和强制执行时，请同时验证这两项能力。 +机器需要具备 `policies:pull` 能力。事件上报由 `events:add` 单独控制；当您期望 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 834fcbd10..804d0dde8 100644 --- a/docs/zh/policies/editor.mdx +++ b/docs/zh/policies/editor.mdx @@ -1,47 +1,49 @@ --- title: "策略编辑器" -description: "根据已确认的故障模式创建和修订版本化策略。" +description: "从已确认的故障模式创建和修订带版本控制的策略。" icon: "file-pen-line" --- -使用策略编辑器将发现的问题转化为可部署的规则。将编写与部署分离，确保草稿不会在未经确认的情况下改变线上行为。 +使用策略编辑器将发现的问题转化为可部署的规则。将创作与部署分离，确保草稿不会悄然改变已上线的行为。 -当某个问题具有可重复的操作模式时，在 **Analyze → issues** 下打开该问题并选择 **generate policy**。Failproof AI 会先说明该策略是否能够表达此问题，再将经过审查的意图和发现上下文带入编辑器。生成的源代码在发布之前始终保持草稿状态。 +当某个问题具有可重复的操作模式时，在 **Analyze → issues** 下打开该问题并选择 **generate policy**。Failproof AI 会首先说明该问题是否可以用策略来表达，然后将经过审查的意图和问题上下文带入编辑器。生成的源代码在您发布之前始终保持草稿状态。 ## 发布策略版本 - - 1. 进入 **Admin → policy editor**，在 **compose** 中描述故障模式或粘贴 JavaScript 策略源代码。 + + 1. 前往 **Admin → policy editor**，在 **compose** 中描述故障模式或粘贴 JavaScript 策略源代码。 2. 验证源代码并修复所有报告的错误。 - 3. 填写策略标识并发布，然后使用 **library** 比较或禁用版本。 - 4. 确认版本可用于机器部署后，选择 **enforcement**。 + 3. 输入策略标识并发布，然后使用 **library** 比较或禁用各个版本。 + 4. 当版本准备好进行机器部署时，选择 **enforcement**。 - ![策略编辑器的 compose 视图，包含策略标识、AI 辅助起草、源代码验证和发布控件。](/images/dashboard/policy-editor.png) + ![策略编辑器的 compose 视图，包含策略标识、AI 辅助草稿、源代码验证和发布控件。](/images/dashboard/policy-editor.png) - Cloud CLI 不支持发布策略版本。请在本地验证源代码后，再将其复制到编辑器中： + 通过 CLI 使用 `fp policies publish` 发布。该命令会生成一个**新版本**，而不会在原处编辑，并在发送前使用 node 对源代码进行语法检查——否则语法错误只会在部署到机器上执行时才会暴露： ```bash - failproofai policies --install --custom ./checkout.policies.ts \ - --cli claude --scope project + fp policies test ./checkout.policy.mjs --command "git push --force" --expect deny + fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push" ``` - 从 **Admin → policy editor** 发布经过审查的版本。 + 发布本身不会部署任何内容——新版本在 `fp fleet deploy` 将其部署到机器之前不会生效。`fp policies compose ""` 会使用云端助手生成源代码草稿并打印供审阅，而不会直接发布。 + + 如需将策略安装到本地 Agent CLI（而非云端），请使用 `failproofai policies --install --custom ./checkout.policies.ts --cli claude --scope project`。 -## 编写检查清单 +## 创作检查清单 -1. 用操作层面的语言命名故障模式。 -2. 选择包含足够判断依据的钩子事件和工具。 -3. 编写能匹配不安全行为的最窄条件。 -4. 返回一条说明，告知 Agent 或操作员下一步应如何处理。 -5. 添加应匹配的示例以及必须保持允许的示例。 -6. 保存新版本并提交审查。 +1. 用运营语言描述故障模式。 +2. 选择包含足够判断依据的 hook 事件和工具。 +3. 编写能够匹配不安全行为的最精确条件。 +4. 返回一个原因说明，告知 Agent 或操作员下一步应该怎么做。 +5. 添加应当匹配的示例以及必须保持允许状态的示例。 +6. 保存新版本并请求审查。 -当 Agent 能够安全纠正操作方向时使用 `instruct`。当允许该操作会带来不可接受或不可逆的风险时使用 `deny`。 +当 Agent 可以安全地自行纠正时，使用 `instruct`。当允许该操作会带来不可接受或不可逆的风险时，使用 `deny`。 - 策略版本是不可变的部署输入。编辑草稿会创建新版本，而不应覆盖已分配给机器的现有版本。 + 策略版本是不可变的部署输入。编辑草稿会创建新版本；不应重写已分配给机器的版本。 \ No newline at end of file diff --git a/docs/zh/reference/cloud-cli.mdx b/docs/zh/reference/cloud-cli.mdx index 1d6182ae7..74882b450 100644 --- a/docs/zh/reference/cloud-cli.mdx +++ b/docs/zh/reference/cloud-cli.mdx @@ -4,9 +4,9 @@ description: "使用 fp 查询和管理 Failproof AI Cloud 的完整参考文档 icon: "cloud-cog" --- -使用 `fp` 查看 Cloud 遥测数据，以及管理审计、发现项、问题、告警、密钥、用户、查询和设置。使用 [`failproofai`](/zh/reference/failproof-cli) 处理本地钩子、策略、采集和机器注册。 +使用 `fp` 检查 Cloud 遥测数据、管理云端执行策略（策略、机群部署、护栏决策），以及管理审计、发现项、问题、告警、密钥、用户、查询和设置。使用 [`failproofai`](/zh/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 命令 -### 认证 +### 身份验证 | 命令 | 用途 | 选项 | | --- | --- | --- | -| `fp login` | 通过邮件发送的一次性验证码登录，并选择组织。 | `--email`, `-e`; `--org`; `--force` | +| `fp login` | 通过邮件一次性验证码登录并选择组织。 | `--email`, `-e`; `--org`; `--force` | | `fp logout` | 吊销并删除已保存的用户会话。 | — | -| `fp whoami` | 显示当前身份、认证模式、组织和权限。 | — | +| `fp whoami` | 显示当前身份、认证模式、组织及权限。 | — | | `fp version` | 显示已安装的 CLI 版本。 | — | -| `fp help` | 显示顶层命令帮助。 | — | +| `fp help` | 显示顶级命令帮助。 | — | ```bash fp login --email you@example.com --org reliability-team @@ -57,7 +57,7 @@ fp whoami fp events [OPTIONS] ``` -列出单个 Agent 事件。默认的轻量信息流不包含原始载荷；仅在有限范围的调查时使用 `--full`。 +列出单个 Agent 事件。默认轻量数据流不包含原始载荷；仅在有限范围的调查中使用 `--full`。 | 选项 | 描述 | | --- | --- | @@ -70,17 +70,21 @@ fp events [OPTIONS] | `--session-id ` | 会话过滤器；可重复或以逗号分隔多个值。 | | `--search ` | 载荷文本搜索；可重复，任意词条匹配即可。 | | `--order asc\|desc` | 时间排序。默认：最新优先。 | -| `--all` | 自动分页直至达到 `--limit`。 | -| `--cursor ` | 从不透明游标处恢复。 | -| `--page-size ` | 与 `--all` 配合使用时每次请求的行数；最大值 `200`。 | -| `--full` | 通过更重量级的事件端点包含原始载荷。 | -| `--fields ` | 仅返回选定字段；请求 `payload` 将启用完整模式。 | +| `--all` | 自动分页，最多获取 `--limit` 条数据。 | +| `--cursor ` | 从不透明游标处继续。 | +| `--page-size ` | 使用 `--all` 时每次请求的行数；最大 `200`。 | +| `--full` | 通过较重的事件端点包含原始载荷。 | +| `--fields ` | 仅返回选定字段；请求 `payload` 时启用完整模式。 | ```bash -fp events --session-id --order asc --all -fp --json events --full --session-id --all +fp events --session-id --order asc --all --limit 10000 +fp --json events --full --session-id --all --limit 10000 ``` + + `--all` 分页获取的数据**最多不超过 `--limit`**，该值默认为 **50** — 因此单独使用 `--all` 会在 50 行时停止。提前停止时，响应中会携带 `next_cursor` 以供继续获取；`"next_cursor": null` 表示数据流已真正耗尽。 + + ### 会话 ```text @@ -94,11 +98,11 @@ fp sessions [OPTIONS] | `--from ` / `--to ` | ISO 8601 UTC 时间范围；覆盖 `--since`。 | | `--env ` | 环境过滤器；可重复或以逗号分隔多个值。 | | `--status ` | `done`、`error` 或 `timeout`；可重复或以逗号分隔多个值。 | -| `--agent-id ` | 匹配包含任意所选 Agent 的会话。 | +| `--agent-id ` | 匹配涉及所选 Agent 的会话。 | | `--session-id ` | 会话过滤器；可重复或以逗号分隔多个值。 | -| `--all` | 自动分页直至达到 `--limit`。 | -| `--cursor ` | 从不透明游标处恢复。 | -| `--page-size ` | 与 `--all` 配合使用时每次请求的行数；最大值 `200`。 | +| `--all` | 自动分页，最多获取 `--limit` 条数据。 | +| `--cursor ` | 从不透明游标处继续。 | +| `--page-size ` | 使用 `--all` 时每次请求的行数；最大 `200`。 | | `--fields ` | 仅返回选定字段。 | | `--full-ids` | 在终端输出中不缩短会话 ID。 | | `--agents` | 展开多 Agent 会话的 Agent 列表。 | @@ -111,11 +115,11 @@ fp evals [OPTIONS] | 选项 | 描述 | | --- | --- | -| `--aggregate` | 显示总计和每个评分的统计信息，而非单条评估记录。 | +| `--aggregate` | 显示总计和每项评分统计，而非单个评估记录。 | | `--limit`, `-n ` | 最大列表行数。默认值：`50`。 | | `--since`, `--from`, `--to` | 选择时间范围。 | | `--env`, `--status`, `--agent-id`, `--session-id` | 每个过滤器限定为一个精确值。 | -| `--score KEY:MIN..MAX` | 评分范围；可重复，所有范围均须匹配。 | +| `--score KEY:MIN..MAX` | 评分范围；可重复，且所有范围必须同时满足。 | | `--all`, `--cursor`, `--page-size` | 控制列表分页。 | | `--fields ` | 仅返回选定字段。 | | `--full-ids` | 显示完整会话 ID。 | @@ -129,7 +133,7 @@ fp errors [OPTIONS] | 选项 | 描述 | | --- | --- | -| `--aggregate` | 汇总匹配的错误，而非逐行列出。 | +| `--aggregate` | 汇总匹配的错误，而非列出各行。 | | `--limit`, `-n ` | 最大列表行数。默认值：`50`。 | | `--since`, `--from`, `--to` | 选择时间范围。 | | `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` | 缩小错误范围。 | @@ -143,7 +147,7 @@ fp errors [OPTIONS] | 命令 | 用途 | | --- | --- | -| `fp usage` | 显示当前计量窗口的用量。 | +| `fp usage` | 显示当前计量周期的用量。 | | `fp list envs` | 列出已观察到的环境。 | | `fp list agents` | 列出已观察到的 Agent ID。 | | `fp list event_types` | 列出事件类型。 | @@ -158,9 +162,9 @@ fp errors [OPTIONS] | 命令 | 用途 | | --- | --- | | `fp orgs list` | 列出可访问的组织。 | -| `fp orgs switch [SLUG]` | 保存活动组织；省略时会进行提示。 | -| `fp orgs current` | 显示当前活动组织。 | -| `fp orgs perms` | 显示您在活动组织中的权限。 | +| `fp orgs switch [SLUG]` | 保存当前活跃组织；省略时显示提示。 | +| `fp orgs current` | 显示当前活跃组织。 | +| `fp orgs perms` | 显示您在当前活跃组织中的权限。 | ### API 密钥 @@ -168,12 +172,12 @@ fp errors [OPTIONS] | --- | --- | --- | | `fp keys list` | 列出组织密钥。 | `--show-id`; `--fields ` | | `fp keys show NAME` | 显示一个密钥及其授权。 | — | -| `fp keys create NAME` | 创建密钥并一次性显示其密钥值。 | `--permission-set`; `--add`; `--remove` | +| `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 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`。 ### 查询 @@ -181,19 +185,19 @@ fp errors [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 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 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` | @@ -204,17 +208,17 @@ 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` | ### 告警 | 命令 | 用途 | 选项 | | --- | --- | --- | | `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 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 秒之间。 @@ -225,22 +229,22 @@ fp errors [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 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-show NAME` | 显示简报和参考 URL 获取状态。 | — | | `fp audits context-set NAME` | 修改简报或参考 URL。 | `--text`; `--text-file`; `--url`; `--clear-urls` | -| `fp audits context-refresh NAME` | 重新抓取参考 URL。 | — | +| `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 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 ` | #### 审计创建选项 @@ -257,27 +261,27 @@ fp audits create checkout-reliability \ | 选项 | 描述 | | --- | --- | -| `--file ` | 基于 JSON 构建定义，或使用 `-` 从 stdin 读取。显式标志会覆盖文件中的值。 | +| `--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`。 | +| `--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` | 启用或禁用 Agent 式分析。默认：启用。 | +| `--llm` / `--no-llm` | 启用或禁用 Agentic 分析。默认：启用。 | | `--top-k ` | 保留 `1`–`500` 条发现项。默认值：`50`。 | | `--sensitivity low\|medium\|high` | 设置报告敏感度。默认：`medium`。 | | `--channels ''` | 通知渠道数组。 | | `--text ` | 内联简报，最多 8,192 个字符。 | | `--text-file ` | 从文件读取简报；与 `--text` 互斥。 | -| `--url ` | 添加公开的 HTTPS 参考链接；最多重复五次。 | +| `--url ` | 添加公开 HTTPS 参考链接；最多重复五次。 | -在首次运行需要上下文时，请在创建阶段一并包含。创建操作会在队列中的运行开始前，将定义和上下文一起提交。 +首次运行需要上下文时，请在创建时一并提供。创建操作会在排队运行开始前将定义和上下文一起提交。 - `fp audits run` 是异步操作。请轮询 `fp audits runs NAME`，直到最新一次运行成功或失败后，再读取其发现项。 + `fp audits run` 是异步操作。在读取发现项之前，请轮询 `fp audits runs NAME`，直到最新一次运行成功或失败。 ### 问题 @@ -285,14 +289,14 @@ fp audits create checkout-reliability \ | 命令 | 用途 | 选项 | | --- | --- | --- | | `fp issues list` | 列出问题。 | `--state`; `--alert-id`; `--limit`, `-n`; `--show-id` | -| `fp issues count` | 统计开放或指定状态的问题数量。 | `--state` | +| `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 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-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` | @@ -300,52 +304,96 @@ fp audits create checkout-reliability \ 有效的问题状态为 `firing`、`acknowledged` 和 `resolved`。独立问题的严重级别为 `info`、`warning` 和 `critical`。 -### Cloud 助手 +### 云端助手 | 命令 | 用途 | 选项 | | --- | --- | --- | | `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 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` 中暴露。 + +| 命令 | 用途 | 选项 | +| --- | --- | --- | +| `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 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 guardrails summary` | 覆盖率、已拦截/已评估总计、拒绝迷你图及每项策略表格。 | `--since`（`1h`、`6h`、`24h`、`7d`）; `--machine` | +| `fp guardrails timeline` | 按窗口分桶的决策，汇总所有策略来源。 | `--since`（`1h`、`6h`、`24h`、`7d`）; `--machine` | ## 全局标志 | 标志 | 描述 | | --- | --- | | `--json` | 输出机器可读的 JSON。 | -| `--base-url ` | 使用自托管或开发环境的控制台。 | -| `--org ` | 为本次调用选择一个组织。 | +| `--base-url ` | 使用自托管或开发仪表板。 | +| `--org ` | 为本次调用选择组织。 | | `--token ` | 覆盖已保存的用户会话令牌。 | -| `--api-key ` | 使用 API 密钥进行自动化认证；不会被保存。 | -| `--timeout ` | HTTP 超时时间；必须为正数。默认值：`30`。 | -| `--quiet`, `-q` | 抑制 stderr 上的状态输出。 | +| `--api-key ` | 使用 API 密钥对自动化进行身份验证；不会被保存。 | +| `--timeout ` | HTTP 超时；必须为正数。默认值：`30`。 | +| `--quiet`, `-q` | 抑制 stderr 的状态输出。 | | `--no-color` | 禁用彩色输出。 | | `--insecure` / `--secure` | 禁用或恢复 TLS 证书验证。 | -| `--version` | 打印版本号并退出。 | +| `--version` | 打印版本信息并退出。 | | `--help`, `-h` | 显示帮助。 | -`--api-key` 适用于自动化场景。登录、切换组织和助手命令需要用户会话。 +`--api-key` 用于自动化场景。登录、切换组织和助手命令需要用户会话。 ## 环境变量 | 变量 | 等效选项或用途 | | --- | --- | -| `AGENTEYE_DASHBOARD_URL` | `--base-url` | -| `AGENTEYE_ORG` | `--org` | -| `AGENTEYE_CLI_TOKEN` | `--token` | -| `AGENTEYE_CLI_API_KEY` | `--api-key` | -| `AGENTEYE_CLI_JSON` | `--json` | -| `AGENTEYE_INSECURE` | `--insecure` | -| `AGENTEYE_HOME` | 重新定位当前 CLI 配置目录。 | -| `AGENTEYE_ANALYTICS_DISABLED` 或 `DO_NOT_TRACK` | 禁用匿名 CLI 分析。 | +| `FP_DASHBOARD_URL` | `--base-url` | +| `FP_ORG` | `--org` | +| `FP_TOKEN` | `--token` | +| `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` | 禁用彩色输出。 | -显式标志会覆盖环境变量，环境变量会覆盖已保存的配置。在 API 密钥模式下，请使用 `--org` 或 `AGENTEYE_ORG` 显式指定租户。 +显式标志优先于环境变量，环境变量优先于已保存的配置。在 API 密钥模式下，请使用 `--org` 或 `FP_ORG` 显式选择租户。 + + + 这些变量的 `AGENTEYE_*` 写法**不会被 `fp` 读取**，从来如此 — CLI 声明的是 `FP_*`（`fp_cli/app.py`），未知变量不会报错。设置 `AGENTEYE_DASHBOARD_URL` 不会重定向 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 3809954a9..b01801503 100644 --- a/docs/zh/reference/custom-agents.mdx +++ b/docs/zh/reference/custom-agents.mdx @@ -1,45 +1,40 @@ --- -title: "自定义 Agent" -description: "为自定义 Agent 植入追踪能力，使 Failproof AI 能够重建运行记录并发现故障。" +title: "自定义 Agents" +description: "failproofai-sdk 的配置、事件目录、关联规则及数据投递说明。" icon: "python" --- -使用 `failproofai-sdk` 为自定义 Agent 植入追踪能力，让 Failproof AI 能够重建每次运行过程、审计其行为，并找到有据可查的故障。SDK 会写入结构化事件，由 Failproof 守护进程传递至云端。该 SDK 需要 Python 3.10 或更高版本。 +本页面涵盖每项配置、方法和字段的详细说明。如果你是第一次接入，建议先阅读指南——本页面主要用于查阅参考。 -追踪使自定义 Agent 具备可观测性和可审计性。若要在执行前阻止不安全的操作，还需要在运行时中添加执行钩子。 + + + 安装、接入、事件方法、完整示例及常见问题。 + + + LangChain、CrewAI、LlamaIndex 和 Pydantic AI 只需一次调用即可完成接入。 + + - - 如需在自定义 Agent 环境中执行策略，请[联系 Failproof AI](mailto:support@befailproof.ai)。我们将帮助您将运行时的模型、工具和生命周期边界映射到策略钩子。 - +需要 Python 3.10 或更高版本。无运行时依赖。 -
- -
- -## 安装 `failproofai-sdk` - -该 SDK 目前以私有 wheel 包形式分发。请向您的 Failproof AI 联系人索取当前版本及下载权限。 +## 安装 ```bash -VERSION= -pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl" -python -c "import failproofai; print(failproofai.__version__)" +pip install failproofai-sdk ``` -如使用 `uv`，请先下载 wheel 包，然后运行 `uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl`。建议将 wheel 包固定在私有制品仓库或依赖锁文件中。 - -该包以 `failproofai-sdk` 安装，在 Python 中以 `failproofai` 导入。 +该包以 `failproofai-sdk` 形式安装，在 Python 中以 `failproofai_sdk` 导入。框架扩展（如 `failproofai-sdk[langgraph]`）会同时安装对应框架本身；适配器始终包含在基础安装包中。 ## 连接 Failproof 守护进程 1. 前往 **Admin → Keys**，创建一个具有 `events:add` 权限的密钥。 - 2. 在 Agent 所在机器上[将 Failproof 守护进程连接到云端](/zh/start/setup#connect-a-machine-to-cloud)。 - 3. 运行一次已植入追踪的会话，然后在 **Observe → Events** 下找到其确切 ID。 - 4. 前往 **Observe → Sessions**，选择相同环境，打开重建后的追踪记录。 + 2. 在 Agent 所在机器上[将 Failproof 守护进程连接到 Cloud](/zh/start/setup#connect-a-machine-to-cloud)。 + 3. 运行一次已接入的会话，然后在 **Observe → Events** 下找到其精确 ID。 + 4. 前往 **Observe → Sessions**，选择相同环境，打开重建后的追踪视图。 - ![重建为执行图和有序事件追踪的自定义 Python Agent 会话。](/images/dashboard/session-detail.png) + ![以执行图和有序事件追踪形式重建的自定义 Python Agent 会话。](/images/dashboard/session-detail.png) ```bash @@ -51,102 +46,84 @@ python -c "import failproofai; print(failproofai.__version__)" -## 对完整运行进行埋点 - -在进程启动时调用一次 `configure()`。每个事件调用均为仅关键字参数形式，需要提供稳定的 `session_id` 和 `agent_id`。 +## 配置 ```python -import traceback -import uuid +import failproofai_sdk -import failproofai +failproofai_sdk.configure( + base_dir=None, + flush_interval=0.5, + environment="production", +) +``` -failproofai.configure(environment="production") +| 参数 | 说明 | +| --- | --- | +| `environment` | 每条事件上的标签，例如 `production`、`staging`、`prod-eu`，默认为 `dev`。 | +| `flush_interval` | 后台线程写入磁盘的间隔时间（秒），默认为 `0.5`。 | +| `base_dir` | 写入位置，默认为守护进程的 spool 目录，除非有特殊需求，否则无需修改。 | -session_id = uuid.uuid4().hex -agent_id = "checkout-agent" +也可通过环境变量进行设置： -failproofai.event.agent_start( - session_id=session_id, - agent_id=agent_id, - goal="Resolve a failed checkout", -) +| 变量 | 说明 | +| --- | --- | +| `AGENTEYE_ENVIRONMENT` | 无需修改代码即可设置 `environment`，适用于标签由部署环境而非应用代码决定的场景。`configure()` 参数的优先级高于该变量。 | +| `FAILPROOFAI_HOME` | 修改 Failproof AI 根目录（存放 spool 的位置）。 | +| `FAILPROOFAI_SDK_STRICT` | 设为 `1` 时，接入错误会直接抛出异常，而不是仅记录日志。 | +| `FAILPROOFAI_SDK_STRICT_INTEGRATIONS` | 设为 `1` 时，框架兼容性问题会直接抛出异常，而不是仅发出警告后继续运行。 | -try: - tool_call_id = uuid.uuid4().hex - failproofai.event.tool_use( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - input={"order_id": "ord_8421"}, - ) - result = {"status": "payment_failed"} - failproofai.event.tool_result( - session_id=session_id, - agent_id=agent_id, - tool_name="lookup_order", - tool_call_id=tool_call_id, - output=result, - ) -except Exception as exc: - failproofai.event.error( - session_id=session_id, - agent_id=agent_id, - error_type=type(exc).__name__, - message=str(exc), - traceback=traceback.format_exc(), - ) - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="failed", - ) - raise -else: - failproofai.event.agent_end( - session_id=session_id, - agent_id=agent_id, - outcome="success", - summary="Escalated the failed payment", - ) -``` + + **`environment` 中不能包含逗号。** 数据摄取会按逗号分割该字段以构建过滤器，任何标签中包含逗号的事件都会被跳过——导致整个运行任务静默消失。请写 `prod-eu`，而不是 `prod,eu`。 + + `configure(environment="prod,eu")` 会立即抛出异常，方便你及时发现问题。而 `AGENTEYE_ENVIRONMENT` 无法抛出异常（因为没有调用方可接收），因此它只会警告一次并回退到 `dev`。 + -每个执行主体发送一次 `agent_start`。对于子 Agent，复用父级的 `session_id`，为每个执行主体指定唯一的 `agent_id`，并将 `parent_id` 设置为父级的 **agent ID**，而非 session ID。 +事件会先缓存在内存中，后台线程每隔 `flush_interval` 秒写入一次，解释器退出时会执行最后一次 flush。如果进程被强制终止，尚未写入的数据将会丢失。 -## 配置参考 +## 标识 + +每条事件都归属于某个 session 和某个 agent。**使用上下文管理器会自动填充两者**，因此通常无需手动传入： ```python -failproofai.configure( - base_dir=None, - flush_interval=0.5, - environment="production", -) +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") ``` -| 配置项 | 行为说明 | -| --- | --- | -| `base_dir` | 显式指定 spool 根目录，优先于所有环境变量。 | -| `flush_interval` | 后台从内存写入 JSONL 的时间间隔（秒）。默认值：`0.5`。 | -| `environment` | 每个事件上的部署标签，默认为 `dev`。 | -| `FAILPROOFAI_HOME` | 更改包含 `custom-agents` spool 的 Failproof AI 根目录。 | - -设置了显式 `base_dir` 时，SDK 会写入该目录。否则，SDK 将使用 Failproof 守护进程在 `FAILPROOFAI_HOME` 或 `~/.failproofai` 下的 `custom-agents` spool。 +显式传入 `session_id` 或 `agent_id` 同样有效，且优先级更高。如果两者均未绑定也未传入，调用会抛出 `TypeError`，而不是静默发送一条 Cloud 会悄悄丢弃的事件。 -SDK 将调用排队至内存，并通过后台线程批量写入。它还会通过 Python 的 `atexit` 机制尝试最终刷新。对于短生命周期的 worker，应允许解释器正常关闭；强制终止进程可能导致内存中的事件丢失。 + + 标识信息存储在上下文变量中，会自动跟随 `asyncio` 任务传播，但**不会**跟随新线程传播——请用 `failproofai_sdk.propagate()` 包装 worker 线程，否则其事件将无法关联到对应 session。 + ## 事件目录 -所有方法均返回 `None`。值为 `None` 的字段会被省略，而不是写为 JSON `null`。 +共 15 个方法，大多数以**成对**形式出现——先调用开始方法，再调用结束方法，SDK 会自动计算两者之间的耗时。 -| 方法 | 除标识字段外的必填字段 | 可选字段 | +| | 开始 | 结束 | +| --- | --- | --- | +| **Agents** | `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` | + +另有三个独立方法：`error`、`human_pause`、`human_interrupt`。 + + + +每个方法同样接受 `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` | -| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role` | +| `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` | @@ -157,27 +134,64 @@ SDK 将调用排队至内存，并通过后台线程批量写入。它还会通 | `human_pause` | — | `reason`, `user_id` | | `human_interrupt` | — | `reason`, `user_id`, `at_step` | -当某次完成应计为失败时，使用 `outcome="failed"`、`"error"`、`"timeout"` 或 `"rejected"`。其他值（包括 `"failure"`）不会被当前后端识别为失败。 + + + + 要将某次运行标记为失败，`outcome` 必须为以下值之一：`failed`、`error`、`timeout` 或 `rejected`。其他任何值——包括容易混淆的 `"failure"`——都会被视为成功。 + + +## 配对与耗时 + +**一条规则：结束事件的 id 必须与其对应开始事件相同。** 这是配对的依据，也是 SDK 计算耗时的基础。 + +| 配对 | 匹配字段 | +| --- | --- | +| `tool_use` → `tool_result` | `tool_call_id` | +| `hook_triggered` → `hook_completed` | `hook_id` | +| `agent_pause` → `agent_resume` | `pause_id` | +| `human_wait` → `human_input` | `input_id` | +| `model_request` → `model_response` | `request_id` | + +**不要自行传入 `duration_ms`。** SDK 会自动计算，手动传入会抛出 `ValueError`。 -## 关联与时长规则 +唯一例外是 `model_response`——只有你才知道真实的 provider 延迟。请传入整数毫秒值，传入浮点数会抛出异常，因为该列为 32 位整数，否则将会存储为空值。 -- 对匹配的完成事件复用相同的 `tool_call_id`、`hook_id`、`pause_id` 或 `input_id`。 -- SDK 会自动计算 `tool_result`、`hook_completed`、`agent_resume` 和 `human_input` 的 `duration_ms`。如果手动传入这些方法的该字段，将抛出 `ValueError`。 -- 工具 ID 和钩子 ID 共用同一个进程级的待处理映射表。请确保它们在并发会话之间以及两个命名空间内全局唯一；建议使用提供商 ID 或 UUID。 -- 跨进程分割的事件对仍可在下游关联，但 SDK 无法计算其进程内时长。 -- 待处理映射表最多保存 10,000 条起始记录，满时会淘汰最旧的条目。 + -## 自定义字段与载荷 +- **id 只需在同类事件和同一 session 内唯一。** 工具调用和 hook 可以共用同一个 id；同时运行的两个 session 可以复用相同的 id 而不会冲突。 +- **id 不限定于某个 agent 的作用域。** 在一个 agent 下开始、在另一个 agent 下结束的配对仍然可以匹配——这在多 agent 代码中是正常情况。 +- **建议使用 `request_id`，但非必填。** 不传时，模型事件按到达顺序配对，因此同一 agent 中的两个并发调用可能会配对错误。 +- **跨进程的配对**在 Cloud 中仍然可以匹配，但 SDK 无法计算耗时——因为两个进程都只看到了一半。 +- **最多同时等待 10,000 个开始事件。** 超出后最旧的会被丢弃，确保内存泄漏不会无限增长。 -每个事件均接受额外的关键字字段。当下游查询需要结构化数据时，请使用与 JSON 兼容的值。SDK 写入时会将不支持的叶子类型（如 UUID、datetime、Decimal、set、bytes 及模型对象）自动转换为字符串。 + -保留的自定义字段名称为 `timestamp`、`session_id`、`agent_id`、`type` 和 `environment`。可选字段的拼写错误会被当作新的自定义字段接受，因此当某个标准字段未出现在云端时，请检查实际写出的 JSON。 +## 自定义字段 -## 传递与验证 +传入的任何额外关键字参数都会随事件一起存储： + +```python +failproofai_sdk.event.tool_use( + tool_name="search", tool_call_id="c1", + fw_tenant="acme", fw_region="eu-west-1", # 自定义字段 +) +``` + +如果后续需要查询，建议使用 JSON 兼容类型。其他类型——UUID、datetime、`Decimal`、set、bytes、模型对象——都会被转换为字符串存储。 + + + **为自定义字段名添加前缀。** 额外字段会在最后应用，因此名为 `model`、`tool_name` 或 `outcome` 的字段会静默覆盖真正的标准字段。框架适配器使用 `fw_` 前缀；沿用这一约定可以避免任何冲突。 + + 这也解释了为什么拼写错误的可选字段不会报错——它只会变成一个新的自定义字段。如果 Cloud 中某个标准字段缺失，请首先检查拼写。 + + +以下五个字段名为保留字，传入后会直接被拒绝：`timestamp`、`session_id`、`agent_id`、`type`、`environment`。 + +## 数据投递与验证 - 在 **Observe → Events** 中，验证 `agent_start` 是否位于首位，`agent_end` 是否位于末位。然后打开 **Observe → Sessions**，确认模型、工具、人工、钩子和错误事件按预期顺序出现。将 session ID 作为排查问题的主要依据。 + 在 **Observe → Events** 中，确认第一条事件为 `agent_start`，最后一条为 `agent_end`。然后打开 **Observe → Sessions**，确认模型、工具、人工、hook 和错误事件按预期顺序出现。使用 session ID 作为排查问题的首要线索。 ```bash @@ -189,10 +203,14 @@ SDK 将调用排队至内存，并通过后台线程批量写入。它还会通 -如果云端为空，请检查 `$FAILPROOFAI_HOME/custom-agents/events`，否则检查 `~/.failproofai/custom-agents/events`。JSONL 文件证明 SDK 已成功写入事件；spool 持续增长说明问题在于守护进程配置或事件传递，spool 为空则说明问题在于埋点或进程生命周期。 +如果 Cloud 中没有数据，请检查 `$FAILPROOFAI_HOME/custom-agents/events`，否则检查 `~/.failproofai/custom-agents/events`。JSONL 文件的存在证明 SDK 已成功发出事件；spool 持续增长说明问题在于守护进程配置或数据投递，而 spool 为空则说明问题在于接入代码或进程生命周期。 + + + 只在守护进程停止时检查 spool。守护进程运行期间，它会在毫秒内收集并删除每批数据，因此目录列表会与收集器产生竞争，显示的事件数量会远少于实际发出的数量。 + -## 在自定义运行时中阻止故障 +## 在自定义运行时中防止故障 -利用审计发现和关联追踪来定义不安全操作、所需依据及预期响应。自定义执行集成必须在操作执行前将其暴露出来，将其结构化输入传递给策略引擎，并应用 allow、instruct 或 deny 的决策结果。 +利用审计发现和关联追踪来定义不安全操作、所需证据及预期响应。自定义执行集成必须在操作执行前将其暴露出来，将其结构化输入传递给策略引擎，并执行相应的 allow、instruct 或 deny 决策。 -请发送邮件至 [support@befailproof.ai](mailto:support@befailproof.ai)，以便针对您的运行时设计并验证该集成方案。 \ 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/events-and-configuration.mdx b/docs/zh/reference/events-and-configuration.mdx index 9d375007b..b72acc354 100644 --- a/docs/zh/reference/events-and-configuration.mdx +++ b/docs/zh/reference/events-and-configuration.mdx @@ -1,41 +1,41 @@ --- title: "事件与配置" -description: "参考事件模型、环境、本地存储及配置边界。" +description: "事件模型、运行环境、本地存储及配置边界参考。" icon: "list-tree" --- ## 事件类型 -- Agent 启动、结束、暂停和恢复 +- Agent 启动、结束、暂停与恢复 - 模型请求与响应 - 工具调用与结果 - Hook 触发与完成 -- 人工等待、输入、暂停和中断 +- 人工等待、输入、暂停与中断 - 显式错误 -每个事件都包含时间戳、会话 ID、Agent ID、事件类型和环境信息。事件特定字段包含模型、工具、关联、结果、内容、持续时间或错误数据。 +每个事件均包含时间戳、会话 ID、Agent ID、事件类型及运行环境。事件特定字段包含模型、工具、关联、结果、内容、耗时或错误数据。 ## 检查事件契约 1. 打开 **Observe → Events**。 - 2. 设置较短的时间窗口，并按环境、Agent 和事件类型进行过滤。 - 3. 选择一个事件以查看其规范化字段和原始数据，然后进入其会话查看执行上下文。 - 4. 如果缺少配对的持续时间，请验证开始事件和完成事件是否使用相同的关联 ID。 + 2. 设置较短的时间窗口，并按环境、Agent 和事件类型进行筛选。 + 3. 选择一个事件，查看其规范化字段和原始载荷，然后进入其会话以查看执行上下文。 + 4. 如果缺少配对时长，请确认启动事件和完成事件使用了相同的关联 ID。 - 使用 Events 流将数据缩小到单次 Agent 运行，并检查规范化的事件字段。 + 使用事件流将数据范围缩小至单个 Agent 运行，并检查规范化事件字段。 - ![实时 Events 流，支持按环境、Agent、会话和事件类型过滤。](/images/dashboard/events-stream.png) + ![带有环境、Agent、会话和事件类型筛选器的实时事件流。](/images/dashboard/events-stream.png) - 然后从事件跳转到对应的会话。追踪视图会显示该事件前后发生的内容，在仅凭数据内容难以判断时尤为必要。 + 然后从事件跳转至其会话。执行轨迹会显示该事件前后发生的情况，这在仅凭载荷无法判断时尤为必要。 - ![用于在执行上下文中检查事件的关联会话追踪。](/images/dashboard/session-detail.png) + ![用于在执行上下文中检查事件的关联会话轨迹。](/images/dashboard/session-detail.png) - 当缺少配对事件或持续时间时，请在两个视图中对比关联 ID 和时间戳。 + 当配对事件或时长缺失时，可在两个视图中对比关联 ID 和时间戳。 - 先查找有效的过滤条件值，再获取某个会话的完整事件数据： + 先获取有效的筛选值，再拉取指定会话的完整事件载荷： ```bash fp list event_types @@ -53,26 +53,26 @@ icon: "list-tree" ## 保留的 SDK 字段 -请勿将 `timestamp`、`session_id`、`agent_id`、`type` 或 `environment` 用作自定义 Python SDK 字段。工具结果持续时间等配对事件的持续时间由 SDK 自动计算，无法手动提供。 +请勿将 `timestamp`、`session_id`、`agent_id`、`type` 或 `environment` 用作自定义 Python SDK 字段。工具结果耗时等配对事件时长由 SDK 自动计算，不可手动传入。 ## 本地边界 -- Failproof AI 的状态默认存储在 `~/.failproofai` 下，除非显式配置了其他路径。 -- `failproofai-sdk` 使用 `AGENTEYE_HOME` 作为其旧版基础目录的覆盖配置。 +- Failproof AI 的状态默认存储于 `~/.failproofai`，除非显式配置为其他路径。 +- `failproofai-sdk` 始终将数据写入 `~/.failproofai/custom-agents`。`FAILPROOFAI_HOME` 可重定位主目录，但 `custom-agents` 段始终会追加在后，因此写入路径不能位于该目录之外。只有 SDK 自身的 `configure(base_dir=...)` 可将数据写到其他位置。旧版 `agenteye-collector` 会读取 `AGENTEYE_HOME` 以决定监听范围，但该变量不再影响 SDK 的写入位置。 - 环境标签可通过 SDK 配置或 `AGENTEYE_ENVIRONMENT` 进行设置。 -- 守护进程凭证与非敏感设置分开存储。 +- 守护进程凭据与非敏感设置分开存储。 -请使用稳定、低基数的环境名称。守护进程环境标签不支持逗号。 +请使用稳定、低基数的环境名称。守护进程的环境标签不支持逗号。 -## 更改环境标签 +## 修改环境标签 - 环境标签由发送方的 SDK 或 Failproof 守护进程分配。更改后，打开 **Observe → Sessions** 并使用环境过滤器确认新会话已携带新的标签值。已有会话将保留其原始环境标签。 + 环境标签由发送方 SDK 或 Failproof 守护进程指定。修改后，请打开 **Observe → Sessions**，使用环境筛选器确认新会话已使用新标签。已有会话将保留原有的环境标签。 - 对于 `failproofai-sdk`，可在代码中或通过其旧版环境变量配置环境。更改机器级别设置时，需重新运行守护进程配置。 + 对于 `failproofai-sdk`，可在代码中配置环境，或使用其旧版环境变量进行设置。修改机器级别的配置后，请重新运行守护进程配置。 ```bash export AGENTEYE_ENVIRONMENT=production-us-east diff --git a/docs/zh/reference/harnesses.mdx b/docs/zh/reference/harnesses.mdx index 5b1d45720..26847e1bb 100644 --- a/docs/zh/reference/harnesses.mdx +++ b/docs/zh/reference/harnesses.mdx @@ -1,71 +1,71 @@ --- -title: "Agent harnesses" -description: "捕获会话并在所有 12 个支持的 agent harness 中强制执行策略。" +title: "Agent 运行环境" +description: "跨所有 12 种支持的 agent 运行环境捕获会话并执行策略。" icon: "plug-zap" --- -harness 是你的 agent 实际运行的环境。Failproof AI 支持十二种，分为两类： +运行环境（harness）是 agent 实际运行的容器。Failproof AI 支持十二种，分为两类： -- **编程 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（自托管助手） -无论 agent 运行在哪种 harness 中，适用的策略和会话历史都是相同的。一个适配器层会将各 harness 的原生事件名称、工具名称和工具输入字段映射到 29 个规范事件，然后再执行任何策略。 +无论 agent 运行在哪种环境中，同一套策略和同一套会话历史均适用。一个适配器层会在执行任何策略之前，将每种运行环境的原生事件名称、工具名称和工具输入字段映射到 29 个规范化事件上。 -如果 agent **不属于**上述十二种之一，则可直接使用 [Python SDK](/zh/reference/custom-agents) 进行插桩。这是一种不同的契约，有必要明确说明：SDK 提供追踪、会话、评估和审计功能 —— **它本身不强制执行策略。** 若要在不安全操作执行前将其阻断，需要在运行时的工具边界处设置执行钩子；请[联系我们](mailto:support@befailproof.ai)，我们将为你完成映射。 +如果 agent 不在上述十二种环境之中，则可直接使用 [Python SDK](/zh/reference/custom-agents) 进行埋点。这是一种不同的契约，有必要明确说明：SDK 提供追踪、会话、评估和审计功能——**它本身不执行策略。** 若要在不安全操作执行前将其拦截，需要在运行时的工具边界处设置强制执行钩子；请[联系我们](mailto:support@befailproof.ai)，我们将为您完成映射。 -| 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 | 已验证的阻断事件 | 仅观测或非阻断说明 | +| 运行环境 | 已验证的拦截事件 | 仅观察或不可拦截的说明 | | --- | --- | --- | -| 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` | 后置工具、会话和子 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 后请重新测试，尤其是当策略依赖提示、停止、权限或后置工具行为而非通用的前置工具门控时。 - -## 安装捕获和策略钩子 +| 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` | 工具后置、会话及子 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 后请重新测试，尤其是当策略依赖提示、停止、权限或工具后置行为而非通用的工具前置门控时。 + +## 安装捕获与策略钩子 - + 1. 打开 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥，并以机器或环境命名。 - 2. 在目标机器上，使用显示的密钥连接本地 CLI 并安装 harness 钩子。 + 2. 在目标机器上，使用显示的密钥连接本地 CLI 并安装运行环境钩子。 3. 启动一个新的 agent 会话，然后在 **Observe → Events** 下确认其钩子和会话事件。 - 4. 打开同一时间窗口的 **Observe → policy**，确认策略决策已归因到该机器。 + 4. 打开同一时间窗口的 **Observe → policy**，确认某条策略决策已归属于该机器。 - 连接从机器密钥开始。在复制其密钥前，请确认其包含摄取和策略分发权限。 + 连接从机器密钥开始。在复制其密钥前，请确认其包含数据摄取和策略下发两种权限。 - ![用于授予事件摄取和策略分发权限的新 API 密钥抽屉。](/images/dashboard/key-create.png) + ![用于授予事件摄取和策略下发权限的新 API 密钥抽屉。](/images/dashboard/key-create.png) - 安装钩子后，Events 流应显示来自已连接机器和环境的新事件。 + 安装钩子后，Events 数据流应显示来自您所连接的机器和环境的新事件。 - ![用于确认新安装的 harness 正在上报数据的实时 Events 流。](/images/dashboard/events-stream.png) + ![用于确认新安装的运行环境正在上报数据的实时 Events 数据流。](/images/dashboard/events-stream.png) - 最后，验证策略决策已归因到同一台机器。这确认 harness 正在上报策略活动以及追踪事件。 + 最后，确认策略决策已归属于同一台机器。这将验证运行环境不仅在上报追踪事件，也在上报策略活动。 - ![用于验证新连接的 harness 策略决策的 Policy 页面。](/images/dashboard/policy-observe.png) + ![用于验证新连接运行环境策略决策的 Policy 页面。](/images/dashboard/policy-observe.png) - 为所有检测到的 harness 安装钩子： + 为所有检测到的运行环境安装钩子： ```bash failproofai config \ @@ -74,7 +74,7 @@ harness 是你的 agent 实际运行的环境。Failproof AI 支持十二种， failproofai policies --install ``` - 或指定 harness 名称和配置范围： + 或指定特定运行环境和配置作用域： ```bash failproofai policies --install \ @@ -82,7 +82,7 @@ harness 是你的 agent 实际运行的环境。Failproof AI 支持十二种， --scope user ``` - project 范围将钩子配置保留在代码仓库中。user 范围覆盖跨仓库的工作。Claude Code 还支持 local 范围；支持情况因 harness 而异，CLI 会拒绝不支持的组合。 + Project 作用域将钩子配置保存在代码仓库中。User 作用域覆盖跨仓库的工作。Claude Code 还支持 local 作用域；支持情况因运行环境而异，CLI 会拒绝不支持的组合。 验证机器及其事件： @@ -97,13 +97,13 @@ harness 是你的 agent 实际运行的环境。Failproof AI 支持十二种， ## 添加非默认会话路径 - - 额外路径在机器上注册，而非在云端。添加路径后，打开 **Observe → Sessions**，按机器环境过滤，并确认来自新路径的会话出现。打开一个会话，在将其用于审计之前检查 agent、harness 和事件时间戳。 + + 额外路径在机器上注册，而非在云端。添加后，打开 **Observe → Sessions**，筛选到该机器的环境，确认来自新路径的会话已出现。打开一个会话，在将其用于审计之前，检查 agent、运行环境和事件时间戳。 - ![过滤到接收额外捕获路径数据的环境的 Sessions 列表。](/images/dashboard/sessions-list.png) + ![经过筛选以接收来自额外捕获路径数据的环境的 Sessions 列表。](/images/dashboard/sessions-list.png) - 添加带可选标签的路径，然后查看已配置的路径： + 添加一个带可选标签的路径，然后查看已配置的路径： ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -117,5 +117,5 @@ harness 是你的 agent 实际运行的环境。Failproof AI 支持十二种， - 安装后运行一个新会话。在扩大部署范围之前，同时验证实时事件流和实际的策略决策。 + 安装完成后运行一个新会话。在扩大部署范围之前，同时验证实时事件流和实际的策略决策。 \ No newline at end of file diff --git a/docs/zh/reference/overview.mdx b/docs/zh/reference/overview.mdx index 0687cc485..d27b3e17f 100644 --- a/docs/zh/reference/overview.mdx +++ b/docs/zh/reference/overview.mdx @@ -1,6 +1,6 @@ --- title: "集成与参考" -description: "连接支持的 Agent 框架、SDK、CLI 和 HTTP API。" +description: "连接支持的 Agent 框架、SDK、CLI 及 HTTP API。" icon: "braces" --- @@ -8,19 +8,22 @@ icon: "braces" - 为支持的编码和自主 Agent CLI 安装钩子。 + 为支持的编码和自主 Agent CLI 安装 hook。 - - 对自定义 Agent 进行 trace 埋点以发现故障，然后联系我们将防护措施添加到您的运行时。 + + 接入 LangGraph、CrewAI、LlamaIndex、Pydantic AI 或自定义 Agent。 + + + 配置项、事件目录、关联规则及数据投递。 - 查看本地项目、会话、策略活动和离线审计。 + 查看本地项目、会话、策略活动及离线审计。 - 配置本地采集、钩子、策略、审计、数据投递和机器状态。 + 配置本地采集、hook、策略、审计、数据投递及机器状态。 - 查询和管理云端会话、审计、问题、告警、密钥、用户和设置。 + 查询和管理云端会话、审计、问题、告警、密钥、用户及设置。 使用 FastAPI 服务对已完成或非活跃会话进行评分。 @@ -29,33 +32,33 @@ icon: "braces" 编写并测试针对特定工作流的 allow、instruct 和 deny 决策。 - 在客户自管的 Kubernetes 集群上部署云端控制平面。 + 在客户自管理的 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) - 在确认集成完成之前，请打开其中一个会话；trace 中应包含审计所需的模型、工具、错误和策略等信息。 + 在确认集成完成之前，请打开其中一个会话进行检查；追踪记录中应包含审计所需的模型、工具、错误和策略等证据。 - 创建机器密钥，连接 Failproof 守护进程，并验证第一个会话。 + 创建机器密钥，连接 Failproof 守护进程，并验证首个会话。 ```bash fp keys create agent-production \ @@ -71,8 +74,8 @@ icon: "braces" 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)。 + 本地命令请参阅 [Failproof AI CLI 参考](/zh/reference/failproof-cli)，`fp` 命令请参阅 [Failproof Cloud CLI 参考](/zh/reference/cloud-cli#cli-commands)。 \ No newline at end of file diff --git a/docs/zh/reference/troubleshooting.mdx b/docs/zh/reference/troubleshooting.mdx index 67815c31b..c727ddde6 100644 --- a/docs/zh/reference/troubleshooting.mdx +++ b/docs/zh/reference/troubleshooting.mdx @@ -1,16 +1,16 @@ --- -title: "故障排查" -description: "诊断会话缺失、策略缺失、事件投递失败以及 Agent 操作被拦截等问题。" +title: "故障排除" +description: "诊断会话缺失、策略缺失、投递失败及 Agent 操作被阻止等问题。" icon: "wrench" --- - - 打开 **Administration → Keys**，确认机器密钥处于激活状态且具有 `events:add` 权限。然后打开 **Observe → Events**，扩大时间范围，并清除环境和 Agent 过滤器。若存在事件，搜索会话 ID，再前往 **Observe → Sessions** 查看分组情况。若不存在任何事件，请通过 CLI 诊断 Failproof 守护进程。 + + 打开 **Administration → Keys**，确认机器密钥处于活跃状态且具备 `events:add` 权限。然后打开 **Observe → Events**，扩大时间范围，并清除环境和 Agent 过滤器。如果存在事件，搜索会话 ID，然后在 **Observe → Sessions** 中检查分组情况。如果不存在任何事件，请从 CLI 诊断 Failproof 守护进程。 - ![实时事件流，显示主要过滤器及近期 Agent 事件。](/images/dashboard/events-stream-current.png) + ![显示主要过滤器及最新 Agent 事件的实时事件流。](/images/dashboard/events-stream-current.png) ```bash @@ -21,14 +21,14 @@ icon: "wrench" fp sessions --since 24h --limit 20 ``` - 确认已启用数据采集、所配置的密钥具有 `events:add` 权限，并且控制台中的过滤器与实际发出的环境相匹配。 + 确认已启用数据采集、配置的密钥具备 `events:add` 权限，以及仪表板过滤器与发出的环境相匹配。 - + - - 清除 **Observe → Events** 中的过滤器，并搜索确切的 SDK 会话 ID。若未找到任何结果，请在源机器上检查 SDK 缓冲目录和 Failproof 守护进程。 + + 清除 **Observe → Events** 中的过滤器，并搜索确切的 SDK 会话 ID。如果没有结果，请在源机器上检查 SDK 后台队列和 Failproof 守护进程。 ```bash @@ -36,15 +36,14 @@ icon: "wrench" failproofai flush --wait ``` - 确认 Agent 进程已设置 `AGENTEYE_SPOOL_TO_FAILPROOFAI=1`，并且在 SDK 启动前 `$FAILPROOFAI_HOME/custom-agents`（或默认路径 `~/.failproofai/custom-agents`）已存在。 + 确认守护进程正在运行并已连接——无论守护进程是否存在，SDK 都会将数据写入队列。队列目录**无需**预先创建（写入器会自动创建），也没有环境变量可用于选择该目录：`$FAILPROOFAI_HOME/custom-agents`，否则为 `~/.failproofai/custom-agents`，这是唯一的根路径，`configure(base_dir=...)` 是唯一的覆盖方式。如果进程因 `SIGKILL` 或 OOM 被终止，队列中尚未处理的数据将会丢失——请处理 `SIGTERM` 信号以限制损失范围。 - - 打开 **Admin → enforcement**，选中该机器，对比其已分配版本、已上报版本和上一版本。确认部署范围包含该机器，且其密钥具有 `policies:pull` 权限。即使策略下发失败，事件采集仍可正常工作。 - + + 打开 **Admin → enforcement**，选择该机器，并比较其已分配版本、已上报版本和先前版本。确认部署范围包含该机器，且其密钥具备 `policies:pull` 权限。即使策略投递失败，事件采集仍可正常工作。 ```bash @@ -53,15 +52,14 @@ icon: "wrench" failproofai config --status ``` - 确认机器 ID 和标签与控制台中的目标一致。若现有凭据仅具备事件采集权限，请使用支持策略功能的密钥重新连接。 + 确认机器 ID 和标签与仪表板目标匹配。如果现有凭据仅授予事件采集权限，请使用具备策略能力的密钥重新连接。 - - 打开 **Admin → enforcement**，查看该机器的最后在线时间和已上报版本。若机器状态已过期，应将其视为本地守护进程问题处理。不要仅为绕过不可用的守护进程而降低已部署策略的限制级别。 - + + 打开 **Admin → enforcement**，检查机器的最后在线时间和已上报版本。如果机器状态过期，应将其视为本地守护进程问题。不要仅为绕过不可用的守护进程而削弱已部署的策略。 ```bash @@ -71,18 +69,17 @@ icon: "wrench" failproofai config --status ``` - 重启或更新 `failproofaid`；当 CLI 与守护进程协议版本不一致时，重新运行配置命令。已配置的守护进程路径在设计上采用失效关闭（fail-closed）策略。 + 重启或更新 `failproofaid`；当 CLI 与守护进程协议版本不一致时，重新运行配置。已配置的守护进程路径在设计上采用失败关闭（fail-closed）策略。 - - 对于在 Cloud 中编写的策略，打开 **Admin → policy editor**，选中草稿，在发布前查看验证错误信息。对于本地策略，使用 CLI 对其进行验证，然后在执行测试操作后打开 **Observe → policy**，确认决策已正常到达。 - + + 对于在 Cloud 中编写的策略，打开 **Admin → policy editor**，选择草稿，在发布前查看验证错误。对于本地策略，使用 CLI 验证后，触发一次测试操作，然后在 **Observe → policy** 中确认决策是否到达。 - 确认文件名以 `policies.js`、`policies.mjs` 或 `policies.ts` 结尾，模块中调用了 `customPolicies.add(...)`，并且所有 import 均可从策略文件中正确解析。 + 确认文件名以 `policies.js`、`policies.mjs` 或 `policies.ts` 结尾，模块中调用了 `customPolicies.add(...)`，且策略文件中的导入路径均可正确解析。 ```bash failproofai policies --install --custom ./checkout.policies.ts @@ -93,12 +90,12 @@ icon: "wrench" - - 打开 **Analyze → audits**，选中本次运行，检查模型分析是否已执行。然后将其范围和时间窗口与 **Observe → sessions** 进行对比，并打开该样本集中具有代表性的追踪记录。 + + 打开 **Analyze → audits**，选择对应的运行，检查模型分析是否已执行。然后将其范围和时间窗口与 **Observe → sessions** 进行比对，并打开该群体中的代表性追踪记录。 - 只有在分析成功执行的前提下，零结果才具有实际意义。若分析被跳过或失败，本次运行将不产生任何发现，且未分析的时间窗口将保持开放，等待下一次成功运行。若模型分析已被禁用，审计同样不会产生任何发现，因为确定性凭据和 PII 扫描仅记录统计数据，不再触发发现。 + 只有在分析成功执行的情况下，零结果才具有实际意义。如果分析被跳过或失败，该次运行将不产生任何发现，且未分析的时间窗口会保持开放，等待未来一次成功的运行。如果模型分析被禁用，审计同样不会产生任何发现，因为确定性凭据和 PII 扫描仅记录统计数据，不再触发发现。 - ![审计配置表单，通过环境、Agent、周期和扫描窗口定义会话样本集。](/images/dashboard/audit-new.png) + ![审计表单，通过环境、Agent、频率和扫描窗口定义会话群体。](/images/dashboard/audit-new.png) ```bash @@ -110,31 +107,31 @@ icon: "wrench" fp audits findings --audit ``` - 若运行持续处于排队状态，请等待审计 Agent 容量释放，或联系部署运维人员检查审计集群。排队中的审计会自动重试，不会被立即跳过。 + 如果运行停留在排队状态，请等待审计 Agent 容量释放，或联系部署运维人员检查审计集群。排队中的审计会自动重试，不会被立即跳过。 - - 打开一个已完成的会话，检查手动评估是否能够成功执行。当前托管 Cloud 版本的控制台不支持配置评估器端点，需由服务器运维人员进行配置。 + + 打开一个已完成的会话，检查手动评估是否能成功执行。托管 Cloud 目前在仪表板中没有评估器端点控制；服务器运维人员需自行配置。 - 先验证评估器本身，再检查近期评估状态： + 验证评估器本身，然后检查最近的评估状态： ```bash curl https://evaluator.example.com/health fp evals --since 1h ``` - 在自托管 Cloud 环境中，确认服务器上已配置 `EVALUATOR_ENDPOINT`，且 `EVALUATOR_TOKEN` 与评估器匹配。若端点缺失，自动评估将被禁用。 + 在自托管 Cloud 环境中，确认服务器上已设置 `EVALUATOR_ENDPOINT`，且 `EVALUATOR_TOKEN` 与评估器匹配。当端点缺失时，自动评估将被禁用。 - - 使用组织切换器，确认预期的 slug 和权限，再与 CLI 的结果进行对比。 + + 使用组织切换器，确认预期的 slug 和权限，然后再与 CLI 的结果进行比对。 ```bash @@ -143,18 +140,17 @@ icon: "wrench" fp orgs perms ``` - 在 API 密钥模式下，请指定 `fp --org --api-key ...` 或设置 `AGENTEYE_ORG`。对于 API 密钥请求，已保存的人工会话组织状态会被有意忽略。 + 在 API 密钥模式下，通过 `fp --org --api-key ...` 指定组织，或设置 `AGENTEYE_ORG` 环境变量。对于 API 密钥请求，已保存的人工会话组织状态会被有意忽略。 - + - - 打开 **Observe → policy**，保存该决策及关联会话，并定位误报条件。然后打开 **Admin → enforcement**，将受影响的机器回滚至上一版本。在 **Policy editor** 中创建范围更窄的新版本，先在小范围内测试，仅在合法操作通过后再扩大范围。 - + + 打开 **Observe → policy**，保留该决策及关联的会话，并识别误报条件。然后打开 **Admin → enforcement**，将受影响的机器回滚至先前版本。在 **Policy editor** 中创建一个范围更窄的新版本，在小范围内测试，待合法操作成功后再扩大范围。 - Cloud 部署回滚仅支持通过控制台操作。暂停本地会话不会禁用由 Cloud 管理的策略。若控制台不可用，请记录机器和部署状态，优先恢复控制台访问权限，而非反复重试被拦截的操作。 + Cloud 部署回滚仅支持通过仪表板操作。本地暂停会话不会禁用 Cloud 管理的策略。如果仪表板不可用，请记录机器和部署状态，优先恢复仪表板访问，而不是反复重试被阻止的操作。 ```bash failproofai config --status @@ -164,4 +160,4 @@ icon: "wrench" -联系支持团队时，请提供 CLI 版本、运行框架、环境信息、相关会话或部署 ID，以及去除敏感信息后的 `failproofai config --status` 输出内容。 \ No newline at end of file +联系支持时，请提供 CLI 版本、运行框架、环境、相关会话或部署 ID，以及移除机密信息后的 `failproofai config --status` 输出。 \ No newline at end of file diff --git a/docs/zh/sessions/live-events.mdx b/docs/zh/sessions/live-events.mdx index 7e45b1ff9..6bc3aaeec 100644 --- a/docs/zh/sessions/live-events.mdx +++ b/docs/zh/sessions/live-events.mdx @@ -1,21 +1,21 @@ --- title: "实时事件" -description: "在会话运行时观察 agent 活动的实时推送。" +description: "在会话运行时查看 Agent 活动的实时流。" icon: "radio" --- -实时事件可帮助你确认埋点是否正常，并在不等待会话结束的情况下监控高风险的运行过程。 +实时事件帮助你确认埋点是否正常，并在不等待会话结束的情况下监控高风险运行过程。 -## 监控活动 +## 查看活动 1. 前往 **Observe → Events**。 - 2. 先使用当前时间窗口且不设任何过滤条件，确认数据正在正常接入。 - 3. 按环境、事件类型、agent 或会话进行过滤，也可使用搜索功能查找 payload 文本。 - 4. 选择某个事件以查看其摘要和详情，点击会话链接可查看完整追踪记录。 + 2. 从当前时间窗口开始，不添加任何过滤条件，确认数据是否正在到达。 + 3. 按环境、事件类型、Agent 或会话进行过滤，也可通过搜索查找 payload 文本。 + 4. 选择某个事件以查看其摘要和详情，点击会话链接查看完整追踪。 - ![实时 Events 流，展示来自 Hermes 聊天网关及编程 CLI 运行的流量，可按时间、环境、事件类型、agent、模型、上下文和会话进行过滤。](/images/dashboard/events-stream-current.png) + ![实时事件流，显示来自 Hermes 聊天网关的流量以及编码 CLI 运行的记录，可按时间、环境、事件类型、Agent、模型、上下文和会话进行过滤。](/images/dashboard/events-stream-current.png) ```bash @@ -24,22 +24,22 @@ icon: "radio" fp --json events --full --session-id --all ``` - 默认数据流不包含原始 payload。请仅在针对有限范围的会话进行排查时使用 `--full`。 + 默认的事件流不包含原始 payload。`--full` 仅建议在对有限范围的会话进行调查时使用。 -使用事件流可即时回答以下三个问题： +使用事件流可以快速回答以下三个问题： -- 预期的 agent 是否在向正确的环境上报数据？ +- 预期的 Agent 是否在向正确的环境上报数据？ - 模型调用、工具调用和策略决策是否按顺序到达？ -- 会话是否已停止推进，或开始重复某个操作？ +- 会话是否已停止推进，或开始重复执行某个操作？ -事件类型包括：agent 生命周期事件、模型请求与响应、工具使用及结果、hook 执行、人工等待与中断，以及显式错误。关联 ID 会将成对事件（如工具调用与其结果）串联起来。 +事件类型包括：Agent 生命周期事件、模型请求与响应、工具调用及结果、Hook 执行、人工等待与中断，以及显式错误。关联 ID 用于将成对的事件（例如工具调用与其结果）关联在一起。 - 在验证新集成时，建议先保持实时视图的宽泛过滤。待看到第一个事件后再添加过滤条件——错误的过滤条件可能会让数据接入问题看起来像是采集失败。 + 在验证新集成时，建议保持实时视图为宽泛模式。等看到第一个事件后再添加过滤条件——过早设置错误的过滤条件可能会让你误以为数据采集失败。 -若没有事件出现，请运行 `failproofai config --status`，然后参阅[排查数据接入问题](/zh/reference/troubleshooting)。 +如果没有事件出现，请运行 `failproofai config --status`，然后参阅[采集问题排查](/zh/reference/troubleshooting)。 -未运行在 12 种受支持的 [harnesses](/zh/reference/harnesses) 之一中的 agent，可通过 [Python SDK](/zh/reference/custom-agents) 上报相同类型的事件，包括网关和生产环境 agent 所依赖的人机协作事件（`human_wait`、`human_input`、`human_interrupt`）。 \ No newline at end of file +未在 12 个受支持的 [harnesses](/zh/reference/harnesses) 中运行的 Agent，同样可以通过 [Python SDK](/zh/reference/custom-agents) 上报相同类型的事件，包括网关和生产环境 Agent 所依赖的人机交互事件（`human_wait`、`human_input`、`human_interrupt`）。 \ No newline at end of file diff --git a/docs/zh/start/first-policy.mdx b/docs/zh/start/first-policy.mdx index 36e7c18fb..12828301e 100644 --- a/docs/zh/start/first-policy.mdx +++ b/docs/zh/start/first-policy.mdx @@ -1,33 +1,33 @@ --- -title: "通过策略预防第一次失败" -description: "编写策略版本，以观察模式部署，然后执行。" +title: "用策略阻止第一次失误" +description: "编写策略版本，以观察模式部署，然后强制执行。" icon: "shield-check" --- -只有在能够描述不安全操作以及必须保持允许的合法操作之后，才可使用策略。 +只有当你能够描述不安全的操作以及必须继续允许的合法操作时，再使用策略。 - 前往 **Admin → 策略编辑器**。从演示策略开始，查看或编辑其源代码，然后选择 **发布版本**。发布后将创建不可更改的版本，可部署到各台机器。 + 进入 **Admin → policy editor**。从演示策略开始，查看或编辑其源码，然后选择 **publish version**。发布后将创建不可变版本，可部署到机器上。 ![策略编辑器的编写视图，演示策略已准备好发布为不可变版本。](/images/dashboard/policy-editor.png) - - 前往 **Admin → 执行**，展开目标机器，选择 **编辑此机器**。添加已发布的演示策略，固定其版本，选择 **观察**模式，然后应用部署。 + + 进入 **Admin → enforcement**，展开目标机器，选择 **edit this machine**。添加已发布的演示策略，固定其版本，选择 **observe** 模式，然后应用部署。 - ![机器部署编辑器，其中已选择已发布的策略版本并处于观察模式，准备应用部署。](/images/dashboard/enforcement-editor.png) + ![机器部署编辑器，已选择发布的策略版本并处于观察模式，等待应用部署。](/images/dashboard/enforcement-editor.png) - 在该机器上运行新的 agent 会话，然后打开 **Observe → 策略**。选择该机器，确认演示策略出现在策略映射和决策时间线中。观察模式会记录策略的预期行为，但不会阻止操作。 + 在该机器上运行一个新的 Agent 会话，然后打开 **Observe → policy**。选择该机器，确认演示策略出现在策略映射和决策时间线中。观察模式会记录策略将执行的操作，但不会阻止该操作。 - ![策略页面，显示决策总计、随时间变化的执行活动，以及本地和云端管理的策略映射。](/images/dashboard/policy-observe.png) + ![策略页面，显示决策总数、随时间变化的执行活动，以及本地和云端管理的策略映射。](/images/dashboard/policy-observe.png) - 云端策略编写与机群部署属于管理员工作流。在发布之前，可使用本地 CLI 对同一策略进行验证： + 云端策略编写和集群部署属于管理工作流。在发布之前，可使用本地 CLI 验证相同的策略： ```bash failproofai policies --install --custom ./payment-retry.policies.ts \ @@ -35,13 +35,13 @@ icon: "shield-check" failproofai config --status ``` - 使用 `fp` 检查云端可见的策略决策： + 使用 `fp` 查看云端可见的策略决策： ```bash fp events --event-type hook_completed --env production --since 24h fp sessions --env production --since 24h ``` - 云端 CLI 不开放仅限 root 用户的执行部署路由。请从 **Admin → 策略编辑器** 发布版本，并从 **Admin → 执行** 进行部署。 + 这两个步骤也可通过 CLI 完成：`fp policies publish ` 用于创建版本，`fp fleet deploy --add ` 用于将其部署到机器。对应的控制台操作为 **Admin → policy editor** 和 **Admin → enforcement**。 \ No newline at end of file diff --git a/docs/zh/start/integrations.mdx b/docs/zh/start/integrations.mdx new file mode 100644 index 000000000..e8f1accea --- /dev/null +++ b/docs/zh/start/integrations.mdx @@ -0,0 +1,120 @@ +--- +title: "接入你的智能体" +sidebarTitle: "框架" +description: "通过一次调用，将任意受支持的智能体框架连接到 Failproof AI。" +icon: "plug" +--- + +你的智能体已经产生了所有值得记录的内容——模型调用、工具调用、节点边界、人工等待、失败信息。框架会将这些数据丢弃，而 SDK 会将其保留。 + + + + 你自己编写的智能体，或此处未列出的智能体。 + + + 图、节点、工具、检索器、模型。 + + + 团队、流程、按角色划分的智能体、工具。 + + + 工作流、步骤、函数智能体、检索器。 + + + 类型化智能体、能力、工具、重试。 + + + +## 三行代码，适用任意框架 + + +```bash LangGraph +pip install 'failproofai-sdk[langgraph]' +``` + +```bash CrewAI +pip install 'failproofai-sdk[crewai]' +``` + +```bash LlamaIndex +pip install 'failproofai-sdk[llamaindex]' +``` + +```bash Pydantic AI +pip install 'failproofai-sdk[pydantic-ai]' +``` + +```bash Custom agents +pip install failproofai-sdk +``` + + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # 自动检测你已导入的框架 + +with failproofai_sdk.session(): + ... # 你现有的智能体调用，无需任何修改 +``` + +无需在函数上添加装饰器，无需向调用传递回调，也无需在代码中传递 ID。唯一的变化是将调用放在 session 内部： + + + + ```python + graph.invoke({"messages": [HumanMessage("...")]}) + ``` + + + ```python + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() + ``` + + + ```python + await agent.run("...") # 在 `async with failproofai_sdk.session():` 下使用 + ``` + + + ```python + agent.run_sync("...") + ``` + + + ```python + with failproofai_sdk.agent("planner"): + with failproofai_sdk.tool_call("search", input={"q": q}) as t: + t.output = search(q) + ``` + + + +额外安装的是**框架**本身。所有适配器均已内置在基础包中，因此已安装框架的项目无需任何额外依赖。 + +## 验证数据是否已到达 + +运行一次已接入的会话，然后打开 **Observe → Sessions** 并选择你的环境。该运行将以重建的追踪形式显示。 + +如果没有数据到达，请使用 `failproofai config --status` 确认机器已连接。请参阅[设置数据捕获](/zh/start/setup)。 + + + 请勿通过查看缓冲目录来确认数据是否已送达。Failproof 守护进程会在毫秒内收集并删除每个批次，因此读取该目录时会与收集器产生竞争，显示的事件数将远少于实际发出的数量。 + + +## 下一步 + +上方每个快速入门均链接到完整指南——包括记录的内容、选项、流式处理、span 命名以及常见问题。这些内容位于 **Trace Agents → Plug in your agent** 下。 + + + + 数据模型、ID、事件类型，以及事件如何上报至云端。 + + + 通过因果关系串联整个会话，而非查看零散的日志。 + + + 对刚刚捕获的会话进行审计。 + + \ No newline at end of file diff --git a/docs/zh/start/integrations/crewai.mdx b/docs/zh/start/integrations/crewai.mdx new file mode 100644 index 000000000..289f07334 --- /dev/null +++ b/docs/zh/start/integrations/crewai.mdx @@ -0,0 +1,224 @@ +--- +title: "CrewAI" +sidebarTitle: "CrewAI" +description: "对 crew、flow、agent（按角色）、工具、内存和人工反馈进行埋点追踪。" +icon: "/images/frameworks/crewai.svg" +--- + +## 安装 + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +支持版本：`crewai` 1.13 至 2.0。1.13 是引入 `started_event_id` 并规范化 token 用量的版本，适配器依赖这两项特性来配对事件和上报 token 数据。 + +## 埋点 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +`instrument()` 会在 CrewAI 的模块级事件总线上注册一个监听器，并为每个事件类订阅对应的处理器。你的 crew、agent、task 和工具均不会受到任何影响。 + +## 记录内容 + +| CrewAI | Failproof 事件 | +| --- | --- | +| Crew kickoff | `agent_start`、`agent_end` | +| `Agent.kickoff()`（轻量 agent，无 crew） | `agent_start`、`agent_end`，`agent_id` 取自角色名 | +| Flow 启动与结束 | `agent_start`、`agent_end`；在 flow 方法内启动的 crew 会嵌套在其下 | +| Agent 执行 | 嵌套的 `agent_start`、`agent_end`，`agent_id` 取自角色名。在层级流程中，被委派的协作者嵌套在管理者下，而非与其并列 | +| Task | 不记录；以链接形式存储，使子节点可追溯至 crew | +| Flow 方法、guardrail | `hook_triggered`、`hook_completed` | +| 工具调用 | `tool_use`、`tool_result` | +| 内存与知识操作 | `tool_use`、`tool_result`，以命中的层名称命名 | +| LLM 调用 | `model_request`、`model_response`，包含 token 用量 | +| 流式块 | 折叠进响应中，以 chunk 数量和首 token 时间表示 | +| 请求人工反馈 | `human_wait`、`agent_pause` | +| 收到人工反馈 | `agent_resume`、`human_input` | +| Agent 执行错误 | `error`，随后 `agent_end` 结果为 `failed` | + +Task 不发出事件是有意为之。CrewAI 的 task 是运行它的 agent 执行过程的子集，若同时发出两者事件，每行数据都会翻倍并呈兄弟关系。因此 task 的 id 和名称会附在 agent 自身的事件上。 + +内存与知识操作以工具形式记录，并以命中的层命名，因此它们会与真实工具并列显示，方便对比延迟数据。 + +在层级 crew 中，嵌套结构使追踪记录清晰可读： + +```text +crew +└─ manager + ├─ researcher delegated + └─ writer delegated +``` + +CrewAI 将委派执行的父节点挂在 `delegate_work_to_coworker` **工具事件**上，而非直接挂在 manager 上，适配器也遵循这一链路。否则每个 agent 都会变成其他 agent 的兄弟节点，委派结构将完全丢失。 + +## 示例 + +```python +import failproofai_sdk +from crewai import Agent, Crew, Process, Task +from crewai.tools import tool + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +MODEL = "openai/gpt-4o-mini" +METRICS = {"revenue": "$4.2M ARR, up 12% QoQ", "churn": "3.1% monthly, up from 2.4%"} + + +@tool("lookup_metric") +def lookup_metric(name: str) -> str: + """Look up a business metric by name. Valid: revenue, churn.""" + return METRICS.get(name.lower().strip(), "unknown metric") + + +analyst = Agent( + role="analyst", # becomes agent_id + goal="pull the numbers that matter and state them plainly", + backstory="You read dashboards for a living.", + tools=[lookup_metric], + llm=MODEL, +) +writer = Agent( + role="writer", + goal="turn numbers into three lines an exec will read", + backstory="You write board updates. You never pad.", + llm=MODEL, +) + +gather = Task( + description="Look up 'revenue' and 'churn' with the tool.", + expected_output="Two lines, one metric each.", + agent=analyst, +) +summarise = Task( + description="Using the metrics above, write a three-line exec summary.", + expected_output="Exactly three lines.", + agent=writer, + context=[gather], +) + +with failproofai_sdk.session(): + result = Crew( + agents=[analyst, writer], + tasks=[gather, summarise], + process=Process.sequential, + ).kickoff() +``` + +交接过程在追踪记录中清晰可见：`analyst` span 关闭，`writer` span 开启，两者均位于同一个 `crew` span 内。 + +## 为 span 命名 + +`agent_id` 来自 `Agent(role=...)`，这使其成为仪表盘中易读的筛选维度。 + +```python +Agent(role="analyst", ...) # agent_id = "analyst" +Agent(role="analyst-7f3a2b", ...) # 每次运行产生一个独立的维度条目 +``` + +`agent_id` 是低基数列。若角色名包含运行 id 或时间戳，会使每次查询的数据质量下降。如果角色名看起来像一个 id，适配器会拒绝使用它，并将真实值存入 payload 字段。 + +## 控制 session + +按以下顺序解析，第一个匹配项生效： + +1. `instrument("crewai", session_id=...)` +2. 外层的 `failproofai_sdk.session()` 作用域 +3. 自动生成的 `uuid4().hex`，每个 crew 或 flow 生成一次 + +通过包裹 kickoff 来按运行控制 session： + +```python +with failproofai_sdk.session(f"support-{ticket_id}"): + Crew(agents=[...], tasks=[...]).kickoff() +``` + +## 选项 + +```python +failproofai_sdk.instrument( + "crewai", + session_id=None, # 将所有运行固定到同一个 session id +) +``` + +`session_id` 是此适配器读取的唯一选项。Prompt 和补全内容始终会被记录，并截断至 payload 预算上限。 + +## 人工介入 + +CrewAI 有**两种**人工介入方式，两者均记录为相同的四个事件。 + +flow 方法上的 `@human_feedback` 通过 CrewAI 的事件总线处理：运行时在阻塞等待人工输入前后各发出一个事件。 + +`Task(human_input=True)` 则不经过事件总线。它在 CrewAI 自身的 input provider 内部调用 `input()`，不发出任何事件，因此适配器直接包装该 provider——否则整个人工等待过程将不可见，并被计入活跃 agent 时间。 + +无论哪种方式，你都会得到： + +```text +human_wait 提示内容及其选项 +agent_pause 开始计时暂停时长 +agent_resume 停止计时 +human_input 答复内容，包含等待时长 +``` + +`agent_pause` 到 `agent_resume` 是唯一用于统计暂停时间的配对。若缺少此配对，十分钟的人工等待将被计为十分钟的活跃 agent 时间。 + + + CrewAI 在两个人工反馈事件上均未设置关联 id，因此适配器通过 flow 名和方法名进行配对，若失败则回退到最近打开的暂停记录。由于控制台 prompt 会阻塞执行，此方式是可靠的。如果你构建了并发反馈 provider，请在两个事件上设置 `request_id`。 + + + + 由于 `Task(human_input=True)` 路径是对 CrewAI input provider 的包装而非事件订阅，它会在 `uninstrument()` 时还原，并原样重新抛出 `input()` 的任何异常，包括 `KeyboardInterrupt`。 + + +## 常见问题 + + + + 某个 `role` 包含了 UUID、时间戳或每次运行的后缀。请使用稳定的人类可读角色名，将运行专属 id 放在 task 描述中。 + + + + 事件总线是异步的，`kickoff()` 会在最后一个处理器执行完毕前返回。请先排空队列： + + ```python + from crewai.events.event_bus import crewai_event_bus + + crew.kickoff() + crewai_event_bus.flush(timeout=30) + ``` + + 这是 CrewAI 本身的特性，与 SDK 无关。 + + + + `agent_end` 会强制关闭未结束的暂停，但不会关闭工具或模型的 span，因此在工具调用过程中崩溃的运行会留下未关闭的 span。正常的清理流程会关闭所有仍处于打开状态的 span 并标记为未完成。只有 `SIGKILL` 会导致 span 挂起，因为此时没有任何代码可以运行。 + + + + 按以下顺序排查：`instrument()` 是否在 `kickoff()` 之前执行；是否有 `with failproofai_sdk.session():` 包裹；`crewai` 是否为 1.13 或更新版本；是否设置了 `FAILPROOFAI_SDK_STRICT=1`，以便降级的 hook 抛出异常而非被静默吞掉。 + + + +## 下一步 + + + + 配对机制、id、session 生命周期与数据传输。 + + + 沿因果链路浏览刚刚捕获的 session。 + + + LangGraph、LlamaIndex、Pydantic AI 及自定义 agent。 + + \ No newline at end of file diff --git a/docs/zh/start/integrations/custom-agents.mdx b/docs/zh/start/integrations/custom-agents.mdx new file mode 100644 index 000000000..796ddd1b6 --- /dev/null +++ b/docs/zh/start/integrations/custom-agents.mdx @@ -0,0 +1,737 @@ +--- +title: "自定义 agents" +sidebarTitle: "自定义 agents" +description: "为自行编写的 agent 或没有适配器的框架添加埋点。" +icon: "code" +--- + +适用于自行编写的 agent，或 Failproof AI 尚无适配器的框架。无需额外配置——你只需直接发出事件。 + +这与四个框架适配器底层调用的 API 完全相同。适配器不过是对它的封装映射表。 + +## 安装 + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # 一次工具调用 +``` + +从上到下读，含义一目了然： + +| 包裹在 | 表示 | +| --- | --- | +| `session()` | 这些事件属于同一次运行 | +| `agent()` | 某个组件正在执行工作——给它一个在列表中能识别的名称 | +| `tool_call()` | 这是一次工具调用，以及它的返回值 | + +每个作用域实际发出的事件： + +| 作用域 | 发出的事件 | 用途 | +| --- | --- | --- | +| `session()` | 无 | 绑定 session id，将一次运行归组 | +| `agent()` | `agent_start`、`agent_end` | 标记一个工作单元的开始和结束 | +| `tool_call()` | `tool_use`、`tool_result` | 标记一次工具调用并计时 | + +内部的所有内容都可以省略 `session_id` 和 `agent_id`。作用域将身份信息绑定在上下文变量上，每次事件调用都会自动读取，无需在函数间手动传递 id。 + +三者均支持 `async with` 和普通 `with`。 + +嵌套 agent 会构建树形结构。`parent_id` 和深度由调用栈自动计算： + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): # parent_id = "supervisor" + ... +``` + +## 作用域如何关闭 + +`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，之后的事件将无法归属。取消不是失败，因此已取消的运行不会污染错误面板。异常始终会被重新抛出——作用域永远不会吞掉异常。 + +## 事件方法 + +六个类别，共十五个方法。大多数成对出现——你发出开启事件，再发出关闭事件，SDK 会测量两者之间的时间跨度。 + +| 类别 | 开启 | 关闭 | 独立 | +| --- | --- | --- | --- | +| **Agents** | `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` | +| **失败** | — | — | `error` | + + + 在适用的场景下优先使用作用域——`agent()` 和 `tool_call()`。它们能保证即使函数体抛出异常也会发出关闭事件。只有当控制流无法嵌套时（例如在辅助函数内的模型调用）才直接使用这些方法。 + + + +```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 Models +failproofai_sdk.event.model_request( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "..."}], + request_id="req-1", +) +failproofai_sdk.event.model_response( + model="gpt-4o-mini", + content="...", + input_tokens=139, + output_tokens=21, + request_id="req-1", + duration_ms=5202, +) +``` + +```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 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 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 Failures +failproofai_sdk.event.error( + error_type="TimeoutError", + message="provider timed out after 30s", + traceback="...", +) +``` + + + + **两组人工事件的方向相反。** + + | 方法 | 含义 | + | --- | --- | + | `human_wait` / `human_input` | **agent 向人发起请求**——审批门控、澄清问题 | + | `human_pause` / `human_interrupt` | **人对 agent 采取了操作**——停止按钮、运维暂停 | + + 没有任何框架会发出第二对事件，因此始终需要你自己发出。 + + + + **并发执行模型调用时请传入 `request_id`。** 若不传，请求和响应将按每个 agent 的到达顺序配对——并发调用会错配，将每个响应关联到错误的请求。 + + +## 示例 + +一个基于 OpenAI API 的工具调用循环，不使用任何 agent 框架： + +```python +import json + +import failproofai_sdk +from openai import OpenAI + +failproofai_sdk.configure(environment="production") +client = OpenAI() +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 + failproofai_sdk.event.model_response( + model=MODEL, + content=reply.choices[0].message.content or "", + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + return reply.choices[0].message + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="price report"): + for _ in range(4): # 有界循环；无界的 agent 循环本身就是一个 bug + message = turn(messages) + if not message.tool_calls: + break + messages.append(message.model_dump(exclude_none=True)) + for call in message.tool_calls: + args = json.loads(call.function.arguments or "{}") + with failproofai_sdk.tool_call( + call.function.name, tool_call_id=call.id, input=args + ) as handle: + handle.output = run_tool(call.function.name, args) + messages.append({ + "role": "tool", + "tool_call_id": call.id, + "content": str(handle.output), + }) +``` + +这将产生与适配器相同的六种事件类型。包含工具定义的完整可运行版本位于 SDK 仓库的 `docs/manual/examples/` 目录下。 + +## 线程与异步 + +上下文变量会自动传播到 asyncio 任务中，但不会传播到新线程——线程启动时上下文为空。 + +```python +# asyncio：无需任何操作 +async with failproofai_sdk.session(): + await asyncio.gather(worker(1), worker(2)) + +# 线程：包裹可调用对象 +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()` 时，worker 的事件会抛出 `TypeError` 并提示修复方法，而不是静默地落到没有 session 的状态。这是有意为之：没有 session 的事件在摄入时会被跳过并返回 `200`，这正是身份层要防止的静默失败。 + +## 为没有适配器的框架添加埋点 + +每个 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: + call.output = original(**args) + ``` + + + ```python + failproofai_sdk.event.model_request(model=model, messages=messages) + reply = provider.complete(...) + failproofai_sdk.event.model_response( + model=model, + content=text, + input_tokens=usage.prompt_tokens, + output_tokens=usage.completion_tokens, + ) + ``` + + + + + **有值得观测的节点、步骤或中间件边界？** 用 hook 对——`hook_triggered` / `hook_completed`——来包裹，而不是嵌套的 `agent()`。`agent_id` 是低基数维度，每个节点一个条目会使其失效。Hook span 的渲染方式相同，还能提供每节点的延迟数据。 + + + + **手动埋点与自动埋点可以组合使用。** 在手动编写的作用域内运行的适配器会加入该 session 并以该 agent 为父节点，从而形成一棵树而非两棵——当你同时对一个框架手动埋点和使用受支持的框架时非常有用。 + + + + 原因有两点，而上述三个切入点正是对这两点的解答： + + - `autogen-core` 自 2025 年 9 月起已停止维护。 + - AG2 没有提供等同于其他框架 hook 的全局注册点，因此要对其埋点就意味着在每个构建位置包裹每个 agent。 + + 手动映射这三个切入点所记录的事件，与内置适配器的保真度完全相同。 + + +## 深入了解 + +记录机制的工作原理。入门时无需了解这些内容。 + + + + + +每次记录的结构相同：一个 span 开启，工作嵌套在其中，每个开启事件都有对应的关闭事件。 + +```mermaid +flowchart LR + S(["agent_start"]) --> H["hook_triggered"] + H --> M["model_request
model_response"] + H --> T["tool_use
tool_result"] + M --> C["hook_completed"] + T --> C + C --> E(["agent_end"]) +``` + +**事件对**是基本单元。每个关闭事件携带 SDK 从对应开启事件起测量的持续时间。 + +以下是每个框架各一次真实运行的记录——来自 SDK 附带的示例，模型名称已统一。注意单次调用能带回多少信息。 + + + + ```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 out-tok + 5 +3.024s hook_completed agent + 6 +3.024s hook_triggered tools + 7 +3.025s tool_use word_count + 8 +3.025s tool_result word_count · ok + 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 + 13 +5.720s hook_completed agent + 14 +5.721s agent_end LangGraph · success + ``` + + 节点转换为 hook 对，因此你可以获得每节点的延迟，而不会使 agent 列表过于拥挤。 + + + + ```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 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 out-tok + 9 +5.727s agent_end analyst · success + 10 +5.739s agent_end crew · success + ``` + + 每个 agent 的 `role` 成为其 span 名称，因此延迟和 token 消耗可按角色分解。 + + + + ```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 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 + ``` + + agent 循环本身是可见的，不仅仅是它的模型调用。 + + + + ```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 + 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 + 8 +8.119s agent_end agent · success + ``` + + 无 hook 对：Pydantic AI 没有可供包裹的节点或步骤边界。 + + + + ```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 out-tok + 6 +0.000s agent_end main · success + ``` + + 这些事件由你自己发出。事件类型相同，保真度相同——代价是需要手动添加调用点。 + + + + + + + +**没有 session 结束事件。** session 不是你去关闭的东西——它是一组共享同一 `session_id` 的事件。 + +状态由追踪的形态推导： + +| 状态 | 时机 | +| --- | --- | +| `ongoing` | 至少有一个 span 仍处于打开状态 | +| `paused` | `agent_pause` 没有对应的 `agent_resume` | +| `error` | 没有打开的 span，且至少有一个事件失败 | +| `done` | 没有打开的 span，且没有失败 | + +因此，当所有事件对都关闭时，session 即结束。适配器会为你发出 `agent_end`，并在拆卸时关闭所有仍打开的 span 并标记为未完成——崩溃的运行会以 `done` 状态结算，留下一个可见的缺口，而不是永久挂起。 + + + 这就是为什么一个 session 可以跨两次调用。LangGraph 的 `interrupt()` 会暂停运行，根 span 故意保持打开状态，由后续恢复调用来关闭它。两次调用属于同一个 session。 + + + + + + +`session_id` 和 `agent_id` 在每个事件方法中都是可选的。省略时，它们从外层作用域解析： + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("planner"): + failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1") +``` + +显式传入仍然有效且优先级更高。若既没有绑定作用域也没有传入参数，调用会抛出 `TypeError` 并提示修复方法，而不是发出一个没有 session 的事件（这类事件在摄入时会被跳过并返回 `200`）。 + +作用域将身份信息绑定在上下文变量上。这些变量会自动传播到 asyncio 任务中，但不会传播到新线程——需要将 worker 包裹在 `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** | **Cloud，在摄入时** | SDK 不发出此值 | +| **`dedup_key`** | **Cloud，在摄入时** | 组织、session、时间戳、类型和载荷的哈希值。这才是真正的身份标识——它让重试的批次折叠而不是重复 | + +#### 适配器如何解析 `session_id` + +按优先级，第一个匹配生效： + +1. 显式传入的 `session_id` 选项 +2. 每次调用的元数据 +3. 外层的 `session()` 作用域 +4. 框架元数据 +5. 框架自身的运行 id + +在上述任一来源存在时，绝不会凭空生成——合成的 id 会将一次运行拆分到多个 session 中。 + +#### 保持 `agent_id` 的低基数 + +它是每个 dashboard 界面的主要维度，对应一个 `LowCardinality(String)` 列。每次运行一个值会降低该列的效能，并使过滤下拉菜单中充斥着每次运行的单独条目。 + +适配器会为你维护这个列： + +| 框架传入的值 | 记录为 | 原因 | +| --- | --- | --- | +| `3f9a1c2b-…`（UUID） | `main` | 没有可保留的可读内容 | +| 长的纯十六进制字符串 | `main` | 同上 | +| `agent-3f9a1c2b-…` | `agent` | 剥离每次运行的 id，保留可读部分 | +| `agent-v2` | `agent-v2` | 短片段保持不变 | +| `step-3` | `step-3` | 同上 | + +真实 id 保存在 `fw_agent_id` / `fw_run_id` 上，在那里仍可查询，但不作为维度。 + + + **此保护仅作用于框架自动选择的标签。** 你自己传入的 `agent_id`——无论是传给 `event.*` 还是 `failproofai_sdk.agent(...)`——都会原样记录。静默改写显式参数带来的危害比它所防止的基数问题更大，因此请自行为 span 命名。 + + + + + + +| 分组 | 事件 | +| --- | --- | +| Agents | `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` | +| 失败 | `error` | + +基于上述运行数据，各框架记录的事件： + +| 事件 | LangGraph | CrewAI | LlamaIndex | Pydantic AI | 自定义 | +| --- | :--: | :--: | :--: | :--: | :--: | +| Agent 开始和结束 | 是 | 是 | 是 | 是 | 你 | +| 模型请求和响应 | 是 | 是 | 是 | 是 | 你 | +| 工具使用和结果 | 是 | 是 | 是 | 是 | 你 | +| Hook 触发和完成 | 节点 | 任务 | 步骤 | — | 你 | +| 错误 | 是 | 是 | 是 | 是 | 自动 | +| 人工等待和输入 | 是 | 是 | 是 | — | 你 | +| Agent 暂停和恢复 | 是 | 是 | 是 | — | 你 | + +横线表示该框架没有此概念。`human_pause` 和 `human_interrupt` 描述的是人对 agent 采取操作，没有任何框架会发出这类信号——需要你自己发出。 + + + + + +事件从不单独出现。一个开启，一个关闭，关闭事件携带 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` | 答复内容及人的响应时长 | + + + 有开启事件但没有对应关闭事件，意味着一个永远不会结束的 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 个开启事件，满后会驱逐最旧的条目。 + + + + + +安装 `failproofai-sdk` 会安装全部内容，包含四个适配器。extras 拉取的是**框架**，而不是适配器。 + +```python +import failproofai_sdk # 不加载标准库以外的任何内容 +failproofai_sdk.instrument() # 仅导入你实际需要的适配器 +``` + +`import failproofai_sdk` 承诺零依赖，通过以下测试强制保证：一个在不带 `--no-deps` 的情况下安装构建 wheel 的测试，以及另一个证明没有框架进入 `sys.modules` 的测试。 + + + 不存在 `failproofai_sdk.crewai` 属性。适配器故意不在顶层包上暴露：访问它会作为属性访问的副作用导入框架，破坏零依赖承诺。请使用 `instrument()`。 + + +```python +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` 而不是已安装的包列表，因此已安装但从未导入的框架不会被埋点，也不会被代为导入。查看已连接的内容： + +```python +from failproofai_sdk.integrations import active, available + +available() # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') +active() # ('langchain',) +``` + + + **在没有安装 CrewAI 的机器上调用 `instrument("crewai")` 不会抛出异常。** 它会记录一条警告并返回 `()`，因此一个缺失的框架不会拖垮同时埋点其他框架的进程。 + + 警告中包含底层的 `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` 可改为抛出异常。该标志**只读取一次并缓存**，因此请在进程启动前导出它，而不是在运行途中设置。 + + + + **`instrument()` 必须在框架导入**之后**调用。** 自动检测读取 `sys.modules`，因此在导入之前的裸调用什么都找不到，不会安装任何内容，并返回 `()`。 + + + +```python Wrong +import failproofai_sdk +failproofai_sdk.instrument() # sys.modules 中还没有 langchain -> () + +import langchain # 太晚了，什么都没被连接 +``` + +```python Right +import langchain # 先导入框架 +import failproofai_sdk + +failproofai_sdk.instrument() # 找到了 -> ('langchain',) +``` + +```python Right, order-proof +import failproofai_sdk + +# 按名称指定会按需导入适配器，因此在任何位置调用都有效。 +failproofai_sdk.instrument("langchain") +``` + + +如果出错，进程会在 SDK 已导入、适配器看似已安装的情况下运行，但**不会发出任何事件**。它会记录一条明确说明此情况的警告——因此当某次运行没有记录任何内容时，请先检查日志。 + + + + + +```mermaid +flowchart LR + A["你的 agent"] --> B["适配器"] + B --> C["Writer
内存队列"] + C -->|"每 0.5 秒"| D["Spool
磁盘上的 JSONL"] + D --> E["Failproof 守护进程"] + E -->|"HTTPS"| F["Cloud"] +``` + +| 阶段 | 职责 | 运行位置 | +| --- | --- | --- | +| 适配器 | 将框架回调转换为 15 种事件类型之一 | 你的进程 | +| Writer | 排队、批处理、原子写入 JSONL | 你的进程，后台线程 | +| Spool | 持久交接，在你的进程退出后仍然存在 | 本地磁盘 | +| 守护进程 | 监视 spool，发送批次，删除已发送内容 | 你的机器 | +| 摄入 | 分配行 id 和去重键，提升可查询列 | Cloud | + +spool 是确保安全的关键：你的 agent 永远不会因网络而阻塞，Cloud 故障只会导致目录增大，而不是事件丢失。 + +每次刷新写入一个批次文件，先写 `.tmp`，然后 `fsync`，再原子重命名： + +```text +~/.failproofai/custom-agents/events/ + event-2026-08-20T10-15-00-123Z-48213-0.jsonl +``` + +守护进程只处理 `.jsonl` 文件，因此永远不会读到写入一半的文件。文件名包含时间戳、进程 id 和序列号，因此两个进程在同一毫秒内刷新也不会冲突。队列最多容纳 10,000 个事件，超出后会丢弃最旧的并记录日志。 + + + **`collector.redact` 不适用于你的 SDK 事件。** 它根本看不到这些事件。 + + +守护进程**发送**你的批次。它不打开也不重写这些批次。 + +| 事件 | 写入者 | 是否受 `collector.redact` 处理 | +| --- | --- | --- | +| CLI 会话记录 | 守护进程 | 是 | +| Hook 活动 | 守护进程 | 是 | +| **SDK 发出的所有事件** | **你的进程** | **否** | + +脱敏在守护进程**写入**自身事件的地方运行——而不是在批次**发送**的地方。因此，包含 API 密钥的 prompt 或工具参数在到达时仍然包含该密钥。 + +这是有意为之。这些是你自己的埋点调用，在传输过程中改写它们意味着你收到的事件与你发出的不一致。 + + + **你在源头控制载荷，有两种方式：** + + - 在适配器上关闭内容捕获。**选项名称各不相同，且有一个适配器没有此选项**——这不是一个统一的开关： + - LangChain / LangGraph、Pydantic AI——`capture_content=False` + - LlamaIndex——`capture_messages=False` + - CrewAI——**完全没有内容开关**；它只读取 `session_id` 选项，因此 prompt 和补全内容始终会被记录。 + + `instrument()` 会丢弃适配器不读取的选项，因此传入错误的名称不会报错，也不会有任何效果。 + - 一开始就不要将敏感信息传给 `input=`。 + + `collector.redact` 不能替代上述两种方式。 + + + + **spool 目录为空才是健康状态。** 不要用它来检查事件是否已送达。 + + +守护进程在发送批次后的毫秒内就会将其删除，因此 `ls` 命令会与收集器产生竞争，只能看到你实际发出内容的一小部分——与 SDK 什么都没记录的情况无法区分。 + +要确认事件已成功落地，请检查 dashboard。要观察 spool 的填充过程，请先停止守护进程。 + + + + + +每个回调都运行在一个包装器内，其唯一职责是重新抛出异常，因此你的调用恰好位于一个 `try` 中，SDK 的所有操作都在其外部进行。 + +| 发生了什么 | 结果 | +| --- | --- | +| 一个 hook 抛出异常 | 记录一次带有堆栈跟踪的日志。你的调用不受影响 | +| 同一个 hook 抛出三次异常 | 该 hook 在进程剩余生命周期内被禁用，记录一行错误 | +| 设置了 `FAILPROOFAI_SDK_STRICT=1` | 异常被重新抛出 | +| 框架版本不在测试范围内 | 发出一次警告，仍然进行埋点 | +| 单个功能缺失 | 仅禁用该 hook，不影响整个适配器 | + +默认行为在生产环境中是正确的，在调试时是错误的，因为它只能证明"没有崩溃"。设置 `FAILPROOFAI_SDK_STRICT=1` 可让被吞掉的失败变得明显。 + + + + + +## 常见问题 + + + + 某个开启事件没有对应的关闭事件：`model_request` 没有 `model_response`，或 `tool_use` 没有 `tool_result`。请使用作用域，它们能保证即使函数体抛出异常也会发出事件对。如果直接调用事件方法，请使用 `try` 和 `finally`。 + + + + 持续时间由对应的开启事件测量，因此在 `tool_result`、`hook_completed`、`agent_resume` 和 `human_input` 上传入 `duration_ms` 会被拒绝。在 `model_response` 上可以接受，因为只有你知道真实的提供商延迟，且必须是整数。 + + + + 该线程从未继承上下文。请将可调用对象包裹在 `failproofai_sdk.propagate()` 中。参见[线程与异步](#threads-and-async)。 + + + + 额外字段最后合并，因此与真实字段（如 `model` 或 `outcome`）同名的字段会覆盖它，改变存储的列值。请为你的字段加命名空间前缀；适配器使用 `fw_` 前缀。 + + + + `agent_id` 是低基数维度，而你在其中放入了运行 id。请使用角色或节点名称，将真实 id 放入载荷字段。 + + + +## 下一步 + + + + 事件对、id、session 生命周期与事件投递。 + + + 在刚捕获的 session 中沿因果链路追溯。 + + + LangGraph、CrewAI、LlamaIndex 和 Pydantic AI。 + + \ No newline at end of file diff --git a/docs/zh/start/integrations/langchain.mdx b/docs/zh/start/integrations/langchain.mdx new file mode 100644 index 000000000..24f5a6f3d --- /dev/null +++ b/docs/zh/start/integrations/langchain.mdx @@ -0,0 +1,244 @@ +--- +title: "LangChain 和 LangGraph" +sidebarTitle: "LangChain 和 LangGraph" +description: "通过一次调用为图、节点、工具、检索器和模型调用添加追踪。" +icon: "/images/frameworks/langchain.svg" +--- + +一个适配器同时支持两者。LangGraph 运行在 `langchain-core` 的回调管理器之上，因此为其中一个添加追踪即可覆盖另一个。 + +## 安装 + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +如果只使用 LangChain 而不使用 LangGraph，请使用 `failproofai-sdk[langchain]`。 + +支持范围：`langchain-core` 1.4.7 至 2.0，`langgraph` 1.2 至 2.0。超出该范围时，适配器仍可安装，但会发出一次警告。 + +## 添加追踪 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +`instrument()` 通过 `langchain_core.tracers.context.register_configure_hook` 注册一个追踪器。LangChain 会将其注入到所构建的每个回调管理器中，因此图、工具和模型都能被自动捕获，无需修改任何调用点——包括你没有编写的库内部的调用。 + +## 记录内容 + +| LangChain 或 LangGraph | Failproof 事件 | +| --- | --- | +| 根运行 | `agent_start`、`agent_end` | +| LangGraph 节点 | `hook_triggered`、`hook_completed` | +| 已编译子图 | 嵌套的 `agent_start`、`agent_end` | +| 工具运行 | `tool_use`、`tool_result` | +| 检索器运行 | `tool_use`、`tool_result`，输出经过摘要处理 | +| Chat 模型或 LLM 运行 | `model_request`、`model_response`，含 token 用量 | +| 流式 token | 折叠进响应中，以 chunk 数量和首个 token 到达时间表示。Token 计数需要 `ChatOpenAI(stream_usage=True)`——详见下文 | +| `interrupt()` | `human_wait`、`agent_pause` | +| `Command(resume=...)` | `agent_resume`、`human_input`，通过 `Interrupt.id` 关联——包括在不同进程中针对同一个 checkpointer 发生恢复的情况 | +| 未处理异常 | `error`，然后是结果为 `failed` 的 `agent_end` | + +**节点成为 hook，而非嵌套 agent。** `agent_id` 是所有仪表板视图中的主要维度——将 `retrieve`、`grade_documents` 和 `should_continue` 提升为 agent 会使其淹没其中，并以恰好最先运行的节点来标记会话。 + +Hook span 的渲染方式相同，仍然提供逐节点的延迟视图。 + + + **节点可以随意命名。** 节点的运行通过其*形态*来识别——携带 LangGraph 自身步骤标签的非叶子运行——而非通过名称。 + + +| 你的代码 | 记录内容 | +| --- | --- | +| `add_node("lookup_population", ToolNode([...]))` | 工具 | +| `add_node("ChatOpenAI", ...)` | 模型调用 | + +以节点运行的内容命名节点，过去会导致该内容的事件消失，现在不会了。 + +### 流式传输 + +`.stream()` 和 `.astream()` 不会产生逐 token 的事件，它们会折叠进关闭时的 `model_response` 中： + +| 字段 | 内容 | +| --- | --- | +| `fw_chunks` | 收到的 chunk 数量 | +| `fw_ttft_ms` | 首个 token 到达时间 | + +### 流式响应中的 Token 计数 + +这是一个独立的问题，容易被忽略：OpenAI 只在**被明确要求**时才在流式响应中发送用量信息。 + +```python +ChatOpenAI(model="gpt-4o-mini", stream_usage=True) # 不加此参数则无 token 计数 +``` + +适配器只记录框架传递给它的内容。没有该标志则无内容可记录，`model_response` 中将不包含 token 计数。 + +## 示例 + +```python +import failproofai_sdk +from langchain_core.messages import HumanMessage +from langchain_core.tools import tool +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import ToolNode, create_react_agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +@tool +def price_of(item: str) -> float: + """Return the unit price of an item in USD.""" + return {"widget": 42.0, "gadget": 17.5}[item.lower().strip()] + + +@tool +def stock_of(item: str) -> int: + """Return the units of an item currently in stock.""" + return {"widget": 120, "gadget": 0}[item.lower().strip()] + + +tools = ToolNode([price_of, stock_of], handle_tool_errors=True) +graph = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) + +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + result = graph.invoke({ + "messages": [HumanMessage("Price and stock for widget and gadget?")] + }) +``` + +## 为 span 命名 + +默认情况下，根 span 使用图本身的名称。可以包裹一层来使用自定义标签： + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("analyst", goal="price and stock report"): + graph.invoke(...) +``` + +对于多 agent 场景，嵌套各作用域。每个 worker 成为携带 `parent_id` 的子 span： + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("supervisor"): + with failproofai_sdk.agent("researcher"): + research_graph.invoke(...) + with failproofai_sdk.agent("writer"): + writer_graph.invoke(...) +``` + +保持 `agent_id` 低基数。使用角色或节点名称，不要使用 UUID 或每次运行时生成的字符串。 + +## 控制会话 + +会话 id 按以下顺序解析，第一个匹配项生效： + +1. `instrument("langchain", session_id=...)` +2. `config={"metadata": {"failproofai_sdk_session_id": ...}}` +3. 外层的 `failproofai_sdk.session()` 作用域 +4. `metadata["session_id"]`、`metadata["conversation_id"]` 或 `metadata["thread_id"]` +5. 根运行 id + +永远不会从头生成，因为合成的 id 会将一次运行拆分到多个会话中。 + +```python +graph.invoke( + {"messages": [...]}, + config={"metadata": {"failproofai_sdk_session_id": f"chat-{user_id}"}}, +) +``` + +## 选项 + +```python +failproofai_sdk.instrument( + "langchain", + session_id=None, # 将所有运行固定到同一个会话 id + include_chains=set(), # 将中间链加入白名单以作为 hook 对 + capture_content=True, # False 则从载荷中去除提示和补全内容 + graph_callbacks=True, # 原生 interrupt 和 resume，需要 langgraph 1.2+ +) +``` + +对于受监管的数据，设置 `capture_content=False`。结构、时序、token 计数、工具名称和结果仍会被记录；消息正文不会被记录。 + +`include_chains` 仅适用于**嵌套**运行。在顶层调用的 runnable 是会话的根节点，因此它会成为 agent span 而非 hook 对，在此处命名它没有效果。 + +## 人工介入循环 + +`interrupt()` 产生四个事件，两对都不冗余： + +```python +from langgraph.types import Command, interrupt + +def approve(state): + decision = interrupt({"prompt": "Ship it?", "options": ["yes", "no"]}) + return {"approved": decision == "yes"} + +with failproofai_sdk.session(): + graph.invoke(state, config) # human_wait, agent_pause + graph.invoke(Command(resume="yes"), config) # agent_resume, human_input +``` + +`human_wait` 到 `human_input` 携带提示和答案（在 `capture_content=False` 下均会被去除，连同检索文档来源一并去除——文档数量仍会保留）。`agent_pause` 到 `agent_resume` 是唯一能记录暂停时间的一对，如果缺少它，十分钟的人工等待会被计为活跃 agent 时间。根 span 在间隔期间保持打开状态，将两次调用保持在同一个会话中。 + +## 常见问题 + + + + `create_react_agent` 会传播该异常。若要让模型看到失败并继续执行，请显式构建工具节点： + + ```python + from langgraph.prebuilt import ToolNode, create_react_agent + + tools = ToolNode([price_of, stock_of], handle_tool_errors=True) + graph = create_react_agent(model, tools) + ``` + + 无论如何，失败都会以携带错误的 `tool_result` 形式被记录。这里只决定运行是否能在失败后继续。 + + + + 在任何图之外直接调用 `llm.invoke()` 时没有父运行，因此它会打开一个根 span 并在其中发出模型事件对。仪表板会将叶子节点挂到一个已打开的 agent 下，所以这个 span 是有意为之的。可以为其命名： + + ```python + with failproofai_sdk.agent("summariser"): + summary = ChatOpenAI(model="gpt-4o-mini").invoke([HumanMessage(text)]) + ``` + + + + 你在 `config={"callbacks": [...]}` 中传入了 Failproof 处理器，同时又调用了 `instrument()`。请移除前者。configure hook 已经覆盖了进程中的每个回调管理器。 + + + + 并非如此。LangGraph 通过与真实异常相同的路径抛出 `GraphInterrupt`，因此每次暂停都会作为错误回调到达追踪器。任何 `GraphBubbleUp` 子类都被视为控制流，因此审批操作不会标记为红色错误。 + + + + 按以下顺序检查：`instrument()` 在图执行前已运行；调用周围有 `with failproofai_sdk.session():`；是否设置了 `FAILPROOFAI_SDK_STRICT=1`，该设置会使降级的 hook 抛出异常而非被吞掉。 + + + +## 下一步 + + + + 事件对、id、会话生命周期和数据投递。 + + + 跟踪刚捕获的会话中的因果链路。 + + + CrewAI、LlamaIndex、Pydantic AI 以及自定义 agent。 + + \ No newline at end of file diff --git a/docs/zh/start/integrations/llamaindex.mdx b/docs/zh/start/integrations/llamaindex.mdx new file mode 100644 index 000000000..85f8e3e4e --- /dev/null +++ b/docs/zh/start/integrations/llamaindex.mdx @@ -0,0 +1,249 @@ +--- +title: "LlamaIndex" +sidebarTitle: "LlamaIndex" +description: "对工作流、步骤、函数代理和检索器进行埋点。" +icon: "/images/frameworks/llamaindex.svg" +--- + +## 安装 + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +支持版本：`llama-index-core` 0.14.23 至 0.15。0.14.23 是工作流流式传输开始携带本适配器所读取的类型化代理事件的版本。低于此版本时，模型名称和代理结构均会丢失。 + +## 埋点 + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + +LlamaIndex 的代理 API 是异步的。每个作用域在 `async with` 和 `with` 下均可正常工作，并产生相同的事件。 + +`instrument()` 会向 LlamaIndex 的全局调度器附加一个事件处理器和一个 span 处理器。两者共同使代理循环可见，而不仅仅是其模型调用。 + + + 如果不在 LLM 上额外添加一个参数，追踪中的所有 token 计数都将为 null。请参阅下方的 [Token 计数](#token-counts)。 + + +## Token 计数 + +`FunctionAgent` 调用 `astream_chat`，而 `llama-index-llms-openai` 在流式传输时不会发送 `stream_options={"include_usage": True}`。因此，提供方永远不会发送用量数据块，任何埋点工具也无从读取。 + +这是上游 LlamaIndex 的行为。请在你的 LLM 上手动开启： + +```python +from llama_index.llms.openai import OpenAI + +llm = OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, +) +``` + +在相同运行和模型下的对比： + +| | 输入 token | 输出 token | +| --- | --- | --- | +| 未开启 | `null` | `null` | +| 已开启 | 148 | 17 | + +非流式调用（`llm.chat`、`llm.achat`）无需任何配置即可上报用量。只有流式路径（即默认的代理路径）才需要此配置。 + +## 记录的内容 + +| LlamaIndex | Failproof 事件 | +| --- | --- | +| `Workflow.run` 根 span | Session、`agent_start`、`agent_end` | +| 嵌套的 `Workflow.run` span | 嵌套的 `agent_start`、`agent_end` | +| 工作流步骤 span | `hook_triggered`、`hook_completed` | +| LLM 聊天开始和结束 | `model_request`、`model_response` | +| `FunctionTool.call` span | `tool_use`、`tool_result` | +| 检索开始和结束 | `tool_use`、`tool_result`，输出经过摘要处理 | +| 嵌入 | 不记录，除非设置 `embeddings=True` | +| 工具等待人工响应 | `human_wait`、`agent_pause`，随后 `agent_resume`、`human_input` | +| `AgentWorkflow` 移交 | 每个代理各有一个嵌套的 `agent_start`、`agent_end`，并挂载在工作流下 | +| 异常 | `error`，随后 `agent_end`（outcome 为 `failed`），并在 `agent_end.summary` 中标注异常名称 | +| `handler.cancel_run()` | `agent_end`（outcome 为 `cancelled`，无 `error`）——停止按钮不等于失败 | + +当你设置了 `FunctionAgent.name` 时，`agent_id` 取该值，否则取工作流类名。在 `AgentWorkflow` 下，每个轮到的代理都会在工作流下获得自己的嵌套 span，因此一次移交会呈现为两个独立代理，而非同一个。 + +检索输出会经过摘要处理而非直接转储。检索器返回的文档如果完整存储到 payload 中，每次查询都会将你的语料库写入事件存储。因此只保留文档数量、评分范围和截断后的摘要片段。 + +## 示例 + +```python +import asyncio + +import failproofai_sdk +from llama_index.core.agent.workflow import FunctionAgent +from llama_index.core.tools import FunctionTool +from llama_index.llms.openai import OpenAI + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +POP = {"tokyo": "37M", "delhi": "33M"} +AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"} + + +def population(city: str) -> str: + """Population of a city. Valid: tokyo, delhi.""" + return POP.get(city.lower().strip(), "unknown") + + +def area(city: str) -> str: + """Land area of a city. Valid: tokyo, delhi.""" + return AREA.get(city.lower().strip(), "unknown") + + +async def main(): + agent = FunctionAgent( + name="city_analyst", + tools=[ + FunctionTool.from_defaults(fn=population), + FunctionTool.from_defaults(fn=area), + ], + llm=OpenAI( + model="gpt-4o-mini", + additional_kwargs={"stream_options": {"include_usage": True}}, + ), + system_prompt="Use the tools. Be terse.", + ) + + async with failproofai_sdk.session(): + async with failproofai_sdk.agent("city_analyst", goal="compare two cities"): + print(await agent.run("Compare Tokyo and Delhi on population and area.")) + + +asyncio.run(main()) +``` + +代理循环在追踪中以 hook 对的形式呈现：`init_run`、`setup_agent`、`run_agent_step`、`parse_agent_output`、`call_tool` 和 `aggregate_tool_results`。它们属于框架自身的循环，因此记录为 hook 而非 agent，以保持 `agent_id` 的语义清晰。 + +## 为 span 命名 + +当你设置了 `FunctionAgent.name` 时，`agent_id` 取该值，否则取工作流类名。 + +```python +FunctionAgent(name="city_analyst", tools=[...], llm=llm) # agent_id = "city_analyst" +``` + +在 `AgentWorkflow` 中，该名称同样用于记录每次移交： + +```text +AgentWorkflow 父 span +├─ city_analyst 第 1 轮 +├─ cost_analyst 第 2 轮 +└─ city_analyst 第 3 轮 — 新的一轮，而非重新打开的旧轮 +``` + +因此，`agent_id` 告诉你**哪个代理**完成了工作，`parent_id` 告诉你它属于**哪个工作流**。代理在之后重新获得控制权时，会开启第二轮，而不是重新打开第一轮。 + +可通过包装运行来覆盖名称，或将多个代理归入同一父级： + +```python +async with failproofai_sdk.agent("research", goal="compare two cities"): + await agent.run(...) +``` + +请保持 `agent_id` 的低基数。它是所有仪表盘视图的主要分组维度，应使用角色名或工作流名，切勿使用 UUID 或每次运行都不同的字符串。 + +## 控制 Session + +本适配器**不接受 `session_id` 选项**。Session 来自外层作用域，否则每次工作流运行会自动生成一个 `uuid4().hex`： + +```python +async with failproofai_sdk.session(f"chat-{user_id}"): + await agent.run(...) +``` + +## 选项 + +```python +failproofai_sdk.instrument( + "llama_index", + embeddings=False, # True 将嵌入调用记录为 tool 对 + steps=True, # False 丢弃工作流步骤 hook 对 + capture_messages=True, # False 丢弃所有 payload：提示词、补全内容、 + # 工具参数和输出、步骤 I/O、检索查询、 + # 目标和最终答案 + capture_limit=8192, # 每个捕获值保留的字符数 + stale_after=600.0, # 废弃叶子节点被强制关闭前的秒数 + reaper_interval=30.0, # 清理器扫描频率；0 表示禁用 +) +``` + +| 选项 | 修改原因 | +| --- | --- | +| `embeddings` | 仅在调试嵌入延迟或成本时开启。批量索引构建会产生数千次调用，会将时间线淹没。 | +| `steps` | 如果你只关心模型和工具事件，觉得代理循环信息冗余，可关闭此选项。 | +| `capture_messages` | 对受监管的数据关闭此选项。所有 payload 将停止记录——提示词、模型补全、工具参数和返回值、工作流步骤输入输出、检索查询、代理目标及最终答案。结构、时序、token 和结果仍会被记录。 | +| `capture_limit` | 截断前每个捕获值保留的字符数。当 RAG 提示词或检索上下文被截断时，可适当调大。 | +| `stale_after` | **叶子节点**被强制关闭前的秒数——即无人消费的流式响应、未收到关闭信号的模型或工具 span——确保 session 最终结算，而不是一直显示 `ongoing`。该选项**不会**关闭废弃的运行本身：若工作流任务被取消且调度器未收到退出信号，其 `agent_start` 将保持打开状态直到 `uninstrument()`。 | +| `reaper_interval` | 扫描频率。设为 `0` 可完全禁用清理器。 | + +## 人机协作 + +当等待发生在工具内部时会被捕获： + +```python +async def ask_human(question: str) -> str: + """Ask a person and wait for their answer.""" + response = await ctx.wait_for_event(HumanResponseEvent) + return response.answer +``` + +普通工作流步骤中的 `ctx.wait_for_event` 不会被捕获。运行时会在信号到达调度器之前拦截该挂起，导致步骤退出并在之后重新运行，没有任何信号可用于标记暂停点。LlamaIndex 文档中的 FunctionAgent 模式在工具内部等待，可以被完整捕获。 + +## 常见问题 + + + + 在你的 LLM 上添加 `additional_kwargs={"stream_options": {"include_usage": True}}`。参阅 [Token 计数](#token-counts)。 + + + + LlamaIndex 没有标准的 usage 字段。适配器会尝试几种已知的数据结构，若某个集成使用了新的计数器命名，则无法匹配。 + + 原始 dict 始终会随 payload 一起发送，可查看 `usage` 字段了解你的提供方使用的字段名。 + + `usage` 有值但 token 列为空是有意为之——这比给出一个自信的错误数字更好。 + + + + 这是 FunctionAgent 循环的正常表现，每次迭代产生一组。可在仪表盘上按 hook 名称过滤。这些步骤的耗时统计通常正是使用本适配器而非纯模型适配器的意义所在。 + + + + 按此顺序排查：`instrument()` 在运行前已执行；`await` 外层有 `async with failproofai_sdk.session():`；`llama-index-core` 版本为 0.14.23 或更高；已设置 `FAILPROOFAI_SDK_STRICT=1`，以便降级的 hook 抛出异常而非被静默吞掉。 + + + +## 下一步 + + + + Pair、ID、session 生命周期与数据投递。 + + + 在刚捕获的 session 中跟踪因果链路。 + + + LangGraph、CrewAI、Pydantic AI 及自定义代理。 + + \ No newline at end of file diff --git a/docs/zh/start/integrations/pydantic-ai.mdx b/docs/zh/start/integrations/pydantic-ai.mdx new file mode 100644 index 000000000..13f608f84 --- /dev/null +++ b/docs/zh/start/integrations/pydantic-ai.mdx @@ -0,0 +1,208 @@ +--- +title: "Pydantic AI" +sidebarTitle: "Pydantic AI" +description: "对类型化的 Agent、工具、模型调用和重试进行追踪。" +icon: "/images/frameworks/pydantic-ai.svg" +--- + +## 安装 + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +支持版本：`pydantic-ai-slim` 2.0 至 3.0。2.0 移除了 `Agent(instrument=...)` 并引入了本适配器所依赖的 capability 协议，因此 1.x 无法以此方式进行追踪。 + +## 追踪配置 + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` 必须在构建任何 `Agent` 之前运行。Capability 在构建时附加，因此提前创建的 Agent 不会携带任何 capability，也不会记录任何内容，且不会报错——因为并没有出错。这是使用本适配器时出现空追踪记录最常见的原因。 + + +模块级别的 Agent 最容易踩这个坑： + +```python +# agents.py +agent = Agent("openai:gpt-4o-mini") # constructed at import time + +# main.py +import failproofai_sdk +failproofai_sdk.instrument() # run this FIRST +import agents # now the agent gets the capability +``` + +确认配置是否生效： + +```python +print([type(c).__name__ for c in agent.root_capability.capabilities]) +# ['FailproofAI', 'ToolSearch', 'PendingMessageDrainCapability'] +``` + +Pydantic AI 会将传入的列表合并为一个 `root_capability`，因此没有 `agent.capabilities` 属性可供读取。 + +在追踪配置生效期间构建的 Agent 会保留该 capability，因此可以先调用 `uninstrument()`，再重新配置追踪，无需重新构建 Agent。 + +## 记录内容 + +| Pydantic AI | Failproof 事件 | +| --- | --- | +| Agent 运行 | `agent_start`、`agent_end` | +| 模型请求 | `model_request`、`model_response`，包含 token 用量 | +| 工具调用 | `tool_use`、`tool_result`，包含模型发送的参数 | +| 工具中的 `ModelRetry` | 携带错误信息的 `tool_result` | +| 未处理的异常 | `error`，随后是结果为 `failed` 的 `agent_end` | + +此处没有钩子对和人机交互对。Pydantic AI 没有可供标记的节点或步骤边界，也没有内置的人工暂停机制，因此无从映射。如果你自行构建了上述功能，请手动发出对应事件——参见[自定义 Agent](/zh/reference/custom-agents)。 + +`output_type` 不影响追踪记录。类型化运行与字符串运行产生相同的事件。 + +## 示例 + +```python +import failproofai_sdk +from pydantic import BaseModel +from pydantic_ai import Agent, ModelRetry + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +PRICE = {"widget": 42.0, "gadget": 17.5} +STOCK = {"widget": 120, "gadget": 0} + + +class Report(BaseModel): + headline: str + out_of_stock: list[str] + + +agent = Agent( + "openai:gpt-4o-mini", + output_type=Report, + system_prompt="Use the tools for every number. If a tool fails, note it and continue.", +) + + +@agent.tool_plain +def price_of(item: str) -> float: + """Unit price of an item. Valid: widget, gadget.""" + return PRICE[item.lower().strip()] + + +@agent.tool_plain +def stock_of(item: str) -> int: + """Units in stock. Valid: widget, gadget.""" + return STOCK[item.lower().strip()] + + +@agent.tool_plain +def restock_eta(item: str) -> str: + """Restock ETA. Not available.""" + raise ModelRetry(f"no restock schedule for {item!r} — answer without it") + + +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + result = agent.run_sync( + "For widget and gadget, get price and stock. " + "For anything out of stock, try the restock ETA. Then produce the report." + ) +``` + +在追踪记录中，`restock_eta` 以携带错误信息的 `tool_result` 形式出现，紧随其后的是另一次模型调用——Agent 在其中绕过了该错误，整个运行最终仍以 `success` 结束。两个事实均被完整保留。 + +## 错误、重试与控制流 + +Pydantic AI 会为三种不同情况抛出异常，适配器对其进行了区分： + +| 异常 | 处理方式 | 结果 | +| --- | --- | --- | +| `ModelRetry`、`ToolRetryError`、`ToolFailedError` | 视为真实的工具失败 | 携带错误信息的 `tool_result`；运行仍可以 `success` 结束 | +| `SkipToolExecution`、`SkipToolValidation`、`SkipModelRequest`、`CallDeferred`、`ApprovalRequired` | 视为控制流 | 不视为错误；运行正在被引导 | +| 其他所有异常 | 视为失败 | `error`，随后是结果为 `failed` 的 `agent_end` | + +`ModelRetry` 被刻意划入第一组。它意味着某次尝试确实失败了，并要求模型重试，这正是工具 span 的错误字段所要记录的内容。若将其归类为控制流，则会将真实的工具失败隐藏在绿色运行结果之后。 + +## 为 Span 命名 + +Pydantic AI 自身的运行 span 命名为 `agent`。在调用时包裹一层，即可赋予自定义标签： + +```python +with failproofai_sdk.session(): + with failproofai_sdk.agent("inventory", goal="stock report"): + agent.run_sync("...") +``` + +框架的 span 随即嵌套在 `inventory` 之下，模型和工具事件也挂载在此处。 + +保持 `agent_id` 低基数。它是所有仪表盘视图的主要分面，应使用角色名称，而非 UUID 或每次运行生成的字符串。 + +## 控制 Session + +按以下顺序解析，首次匹配生效： + +1. `instrument("pydantic_ai", session_id=...)` +2. 外层的 `failproofai_sdk.session()` 作用域 +3. 运行的 `conversation_id`，其次是 `run_id` +4. 生成的 `uuid4().hex` + +```python +with failproofai_sdk.session(f"chat-{user_id}"): + agent.run_sync("...") +``` + +## 选项 + +```python +failproofai_sdk.instrument( + "pydantic_ai", + session_id=None, # pin every run to one session id + capture_content=True, # False drops prompts and completions from payloads +) +``` + +## 常见问题 + + + + `Agent` 在 `instrument()` 运行之前就已构建。请参阅上方警告，并检查 `agent.root_capability.capabilities`。 + + + + 裸 `raise` 会向上传播——这是 Pydantic AI 的设计。若希望模型能绕过该错误，请改为抛出带有可操作提示信息的 `ModelRetry`。无论哪种方式，失败都会被记录。 + + + + 该子 span 是 Pydantic AI 自己的运行 span，模型和工具事件挂载于此。若希望只有一个 span，可以去掉自定义作用域，但代价是失去自定义名称。 + + + + Pydantic AI 的异步图调用栈超出了负载字段的长度限制，而回溯的最后一行正是异常本身。该字段从头部而非尾部进行截断，因此你所需的那一行会被保留。 + + + +## 下一步 + + + + 事件对、ID、Session 生命周期与数据传递。 + + + 在刚捕获的 Session 中追踪因果关系。 + + + LangGraph、CrewAI、LlamaIndex 及自定义 Agent。 + + \ No newline at end of file diff --git a/docs/zh/start/quickstart.mdx b/docs/zh/start/quickstart.mdx index bd849fe9f..afa417b82 100644 --- a/docs/zh/start/quickstart.mdx +++ b/docs/zh/start/quickstart.mdx @@ -1,12 +1,12 @@ --- -title: "快速入门" -description: "捕获一次 Agent 会话，发现故障，并开始预防它。" +title: "快速开始" +description: "捕获一个 Agent 会话，定位故障，并开始预防它。" icon: "zap" --- -本快速入门将帮助你完成以下操作：让一台机器上报会话、运行审计，并部署策略。你可以使用技能包来配置 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 个受支持的[运行环境](/zh/reference/harnesses)之一——例如编程 CLI，或者 Hermes、OpenClaw 等网关——请按照以下步骤操作；你需要 Node.js 20.9 或更高版本。如果你的 Agent 没有对应的运行环境，请使用 [Python SDK](/zh/reference/custom-agents) 对其进行追踪和审计的插桩，然后从[运行你的第一次故障检查](/zh/start/first-audit)继续；该路径下的执行强制需要在你的运行时中添加 hook。 @@ -16,12 +16,12 @@ 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. ``` - 你的 Agent 会检查项目、选择相关集成、执行配置，并验证会话是否已到达。请参阅 [FailproofAI skills 仓库](https://github.com/FailproofAI/skills)了解各项技能及高级安装选项。 + 你的 Agent 会检查项目、选择相关集成、执行配置并验证结果。有关各项技能和高级安装选项，请参阅 [FailproofAI skills repository](https://github.com/FailproofAI/skills)。 @@ -30,7 +30,7 @@ icon: "zap" 1. 打开 [Failproof AI 控制台](https://app.befailproof.ai)，创建账号或使用工作邮箱登录。 2. 前往 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥。 -3. 复制一次性密钥，并将其存储在目标机器上： +3. 复制一次性密钥，并在目标机器上进行存储： ```bash export FAILPROOFAI_KEY="" @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - 默认情况下会发送会话记录。添加 `--no-transcripts` 可在不包含记录内容的情况下上报 hook 活动和策略决策。 + 默认情况下会发送会话记录。添加 `--no-transcripts` 参数可在不上传记录内容的情况下上报 hook 活动和策略决策。 - 如果该机器上已有 Agent 历史记录，可预览并导入最近七天的数据，然后等待传输完成。在全新机器上可跳过此步骤。 + 如果此机器已有 Agent 历史记录，可预览并导入最近七天的数据，然后等待传输完成。新机器可跳过此步骤。 ```bash failproofai backfill --since 7d --dry-run @@ -57,28 +57,28 @@ export FAILPROOFAI_KEY="" 在 Failproof AI 中打开 **Sessions**，选择一个已导入的会话。 - - 此步骤将 Failproof AI 挂载到你的运行环境，并安装 40 条内置策略。使用这些策略可以查看本地策略决策，并在 Failproof AI 审计你的会话并为 Agent 编写策略之前试用执行能力。 + + 此步骤将 Failproof AI 接入你的运行环境，并安装 40 条内置策略。你可以用它们查看本地策略决策，并在 Failproof AI 审计会话、为你的 Agent 生成策略之前先行体验执行强制功能。 - 可让安装程序自动检测你的运行环境，也可以显式指定一个。12 个运行环境均为有效的 `--cli` 值——`claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose`。 + 可让安装程序自动检测你的运行环境，也可以显式指定。以下 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 claude --scope user # 编程 CLI failproofai policies --install --cli hermes --scope user # Slack/Telegram 网关 ``` - 在工具调用执行前拦截已在全部 12 个运行环境中验证。轮次结束门控在 8 个环境中验证——各运行环境的详细情况请参阅[执行能力](/zh/reference/harnesses#enforcement-capability)矩阵。 + 所有 12 个运行环境均已验证支持在工具调用执行前进行拦截。轮次结束门控已在 8 个运行环境上验证——详见[执行强制能力](/zh/reference/harnesses#enforcement-capability)中的各运行环境矩阵。 - 按照[运行首次故障检查](/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/quickstarts/crewai.mdx b/docs/zh/start/quickstarts/crewai.mdx new file mode 100644 index 000000000..69d0adf6f --- /dev/null +++ b/docs/zh/start/quickstarts/crewai.mdx @@ -0,0 +1,37 @@ +--- +title: "CrewAI" +description: "安装、接入并查看你的第一条追踪记录。" +icon: "/images/frameworks/crewai.svg" +--- + +三步完成你的第一条 CrewAI 追踪。关于每个事件的内容、流程及故障排查，请参阅[完整指南](/zh/start/integrations/crewai)。 + +## 安装 + +```bash +pip install 'failproofai-sdk[crewai]' +``` + +## 接入 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff() +``` + +你的 crew、agents、tasks 或 tools 无需任何改动。`instrument()` 会订阅 CrewAI 的模块级事件总线。 + +## 确认数据已到达 + +运行一次后，打开 **Observe → Sessions** 并选择你的环境。你的运行将以重建的追踪形式出现。 + +如果没有数据到达，请使用 `failproofai config --status` 确认机器已连接。 + + + 记录的内容、流程、Token 用量、Span 命名、配置选项及常见问题。 + \ No newline at end of file diff --git a/docs/zh/start/quickstarts/custom-agents.mdx b/docs/zh/start/quickstarts/custom-agents.mdx new file mode 100644 index 000000000..64238f22f --- /dev/null +++ b/docs/zh/start/quickstarts/custom-agents.mdx @@ -0,0 +1,50 @@ +--- +title: "自定义 Agent" +description: "用三个 `with` 块包裹你的 agent，它就会开始记录。" +icon: "code" +--- + +适用于你自己编写的 agent，或 Failproof AI 尚无适配器的框架。 + +你只需用 `with` 块包裹已有的代码逻辑，每个块会自动记录开始时间、结束时间以及耗时——无需调用任何其他接口。 + +## 安装 + +```bash +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.tool_call("search", input={"q": q}) as t: + t.output = search(q) # 一次工具调用 +``` + +从上到下阅读，一目了然： + +| 包裹方式 | 含义 | +| --- | --- | +| `session()` | 这些事件属于同一次运行 | +| `agent()` | 某个组件正在执行工作——为其取一个便于识别的名称 | +| `tool_call()` | 这是一次工具调用，以及它的返回值 | + +按照代码的嵌套结构自由嵌套即可。你无需手动传递 ID：每个块会自动感知自身所处的上下文，所有记录的事件都会自动关联到正确的运行和 agent。`async with` 的用法完全相同。 + +## 确认数据已到达 + +运行一次后，打开 **Observe → Sessions** 并选择你的环境，运行记录将以重建的追踪链路形式呈现。 + +如果没有数据到达，请通过 `failproofai config --status` 确认当前机器已成功连接。 + + + 包含所有事件方法、代码抛出异常时的处理方式、完整示例、多线程与异步支持，以及如何为无适配器的框架进行埋点。 + \ No newline at end of file diff --git a/docs/zh/start/quickstarts/langchain.mdx b/docs/zh/start/quickstarts/langchain.mdx new file mode 100644 index 000000000..4b9e0e39c --- /dev/null +++ b/docs/zh/start/quickstarts/langchain.mdx @@ -0,0 +1,39 @@ +--- +title: "LangChain 和 LangGraph" +description: "安装、插桩并查看您的第一条追踪记录。" +icon: "/images/frameworks/langchain.svg" +--- + +三步完成您的第一条 LangChain 或 LangGraph 追踪。关于流式传输、human-in-the-loop、span 命名及配置选项，请参阅[完整指南](/zh/start/integrations/langchain)。 + +## 安装 + +```bash +pip install 'failproofai-sdk[langgraph]' +``` + +如果只使用 LangChain 而不使用 LangGraph，请改用 `failproofai-sdk[langchain]`。 + +## 插桩 + +```python +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + +with failproofai_sdk.session(): + graph.invoke({"messages": [HumanMessage("...")]}) +``` + +无需修改调用点。`instrument()` 会注册一个追踪器，LangChain 会将其注入到所创建的每个回调管理器中，因此图、工具和模型都会被捕获——包括您未编写的库中的那些。 + +## 确认数据已到达 + +运行一次后，打开 **Observe → Sessions** 并选择您的环境。您的运行将以重建的追踪形式呈现。 + +如果没有数据到达，请通过 `failproofai config --status` 确认机器已连接。 + + + 记录内容、流式传输、token 计数、span 命名、会话控制、配置选项以及 human in the loop。 + \ No newline at end of file diff --git a/docs/zh/start/quickstarts/llamaindex.mdx b/docs/zh/start/quickstarts/llamaindex.mdx new file mode 100644 index 000000000..d0d53b858 --- /dev/null +++ b/docs/zh/start/quickstarts/llamaindex.mdx @@ -0,0 +1,48 @@ +--- +title: "LlamaIndex" +description: "安装、插桩，并查看您的第一条追踪记录。" +icon: "/images/frameworks/llamaindex.svg" +--- + +三步即可完成您的第一条 LlamaIndex 追踪记录。有关工作流步骤、检索、reaper 及选项，请参阅[完整指南](/zh/start/integrations/llamaindex)。 + +## 安装 + +```bash +pip install 'failproofai-sdk[llamaindex]' +``` + +## 插桩 + +LlamaIndex 的 agent API 是异步的。所有作用域既支持 `async with`，也支持 `with`。 + +```python +import asyncio + +import failproofai_sdk + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() + + +async def main(): + async with failproofai_sdk.session(): + await agent.run("...") + + +asyncio.run(main()) +``` + + + 如果您的 LLM 缺少一个额外参数，追踪记录中的所有 token 计数将为 null——`llama-index-llms-openai` 在流式传输时不会请求用量数据。请参阅 [Token 计数](/zh/start/integrations/llamaindex#token-counts)。 + + +## 确认数据已到达 + +运行一次后，打开 **Observe → Sessions** 并选择您的环境。您的运行将以重建后的追踪记录形式显示。 + +如果没有数据到达，请使用 `failproofai config --status` 确认机器已连接。 + + + Token 计数、记录内容、工作流步骤、检索、选项及常见问题。 + \ No newline at end of file diff --git a/docs/zh/start/quickstarts/pydantic-ai.mdx b/docs/zh/start/quickstarts/pydantic-ai.mdx new file mode 100644 index 000000000..267d01e87 --- /dev/null +++ b/docs/zh/start/quickstarts/pydantic-ai.mdx @@ -0,0 +1,42 @@ +--- +title: "Pydantic AI" +description: "安装、插桩并查看你的第一条追踪记录。" +icon: "/images/frameworks/pydantic-ai.svg" +--- + +三步完成你的第一条 Pydantic AI 追踪。关于工具、重试、流式传输和配置选项，请参阅[完整指南](/zh/start/integrations/pydantic-ai)。 + +## 安装 + +```bash +pip install 'failproofai-sdk[pydantic-ai]' +``` + +## 插桩 + +```python +import failproofai_sdk +from pydantic_ai import Agent + +failproofai_sdk.configure(environment="production") +failproofai_sdk.instrument() # before constructing any Agent + +agent = Agent("openai:gpt-4o-mini", system_prompt="Be terse.") + +with failproofai_sdk.session(): + result = agent.run_sync("...") +``` + + + `instrument()` 必须在构造任何 `Agent` **之前**运行。该能力是在构造时附加的，因此提前创建的 Agent 不会记录任何内容——且不会报错，因为实际上没有出错。这是使用此适配器时出现空追踪的最常见原因，模块级别的 Agent 尤其容易中招：请在导入构建 Agent 的模块之前，先导入 `failproofai_sdk` 并调用 `instrument()`。 + + +## 确认数据已到达 + +运行一次后，打开 **Observe → Sessions** 并选择你的环境，你的运行记录将以重建的追踪形式呈现。 + +如果没有数据到达，请使用 `failproofai config --status` 确认机器已连接。 + + + 记录的内容、工具与重试、流式传输、span 命名、配置选项以及常见问题。 + \ No newline at end of file