diff --git a/docs/ar/agenteye/python-sdk.mdx b/docs/ar/agenteye/python-sdk.mdx index 23e4364d..232d5e89 100644 --- a/docs/ar/agenteye/python-sdk.mdx +++ b/docs/ar/agenteye/python-sdk.mdx @@ -1,13 +1,13 @@ --- title: "Python SDK" -description: "اطّلع بالضبط على ما فعله وكلاؤك الذين يعملون بالذكاء الاصطناعي في الإنتاج: كل تشغيل للوكيل، واستدعاء الأداة، وطلب النموذج، والخطاف، والتدخل البشري." +description: "شاهد بالضبط ما فعلته وكلاء الذكاء الاصطناعي الخاص بك في الإنتاج: كل تشغيل للوكيل، واستدعاء الأداة، وطلب النموذج، والخطاف، والتدخل البشري." --- -اطّلع بالضبط على ما فعله وكلاؤك الذين يعملون بالذكاء الاصطناعي في الإنتاج: كل تشغيل للوكيل، واستدعاء الأداة، وطلب النموذج، والخطاف، والتدخل البشري. يسجل Failproof AI Observability Python SDK هذا المسار من داخل رمز الوكيل الخاص بك حتى تتمكن من تصحيح الأخطاء والتدقيق والتقييم لما حدث. استخدمه كلما أردت أن تراقب Failproof AI Observability وكلاءك. +شاهد بالضبط ما فعلته وكلاء الذكاء الاصطناعي الخاص بك في الإنتاج: كل تشغيل للوكيل، واستدعاء الأداة، وطلب النموذج، والخطاف، والتدخل البشري. يسجل SDK قابلية المراقبة Failproof AI هذا المسار من داخل كود الوكيل الخاص بك حتى تتمكن من تصحيح الأخطاء والتدقيق والتقييم لما حدث. استخدمه في أي وقت تريد فيه Failproof AI Observability مراقبة وكلائك. -تحت الغطاء، يكتب SDK الأحداث المنظمة إلى ملفات JSONL محلية، وتلتقط خيط جمع البيانات الخلفي تلك الملفات وترسلها إلى المنصة تلقائياً. لا تدير تلك الملفات بنفسك. +تحت الغطاء، يكتب SDK أحداثًا منظمة إلى ملفات JSONL محلية، ويلتقطها عفريت المجمع ويرسلها إلى النظام الأساسي تلقائيًا. لا تحتاج إلى إدارة تلك الملفات بنفسك. -> **نصيحة:** هل أنت جديد في Failproof AI Observability؟ هذه الصفحة هي مرجع أحداث SDK كاملة. +> **نصيحة:** جديد على Failproof AI Observability؟ هذه الصفحة هي مرجع حدث SDK الكامل.
@@ -17,15 +17,15 @@ description: "اطّلع بالضبط على ما فعله وكلاؤك الذي ## التثبيت -يتم توزيع SDK على العملاء كعجلة خاصة بدلاً من فهرس الحزم العام. يغطي الإعداد الخاص بك كيفية الحصول عليها وتثبيتها وتثبيتها — تحدث مع جهة الاتصال Failproof AI الخاصة بك إذا كنت بحاجة إلى الوصول. +يتم توزيع SDK للعملاء كعجلة خاصة بدلاً من فهرس حزمة عام. يغطي الإعداد الخاص بك كيفية الحصول عليه وتثبيته وتثبيت الإصدار — تحدث إلى جهة الاتصال Failproof AI الخاصة بك إذا كنت بحاجة إلى الوصول. -بمجرد تثبيتها، أكّد أن لديك: +بمجرد تثبيته، تحقق من وجوده: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -هل تفضل ترك وكيل ترميز يقوم بالتكامل كله؟ تعرف [مهارة Python SDK Agent](/ar/agenteye/python-sdk-skill) مسار التثبيت، وتخطط نقاط الآلة، وتكتبها، وتتحقق من وصول الأحداث. +هل تفضل السماح لوكيل البرمجة بالقيام بالتكامل بالكامل؟ يعرف [Python SDK Agent Skill](/ar/agenteye/python-sdk-skill) مسار التثبيت، وينظم نقاط الأداة، ويكتبها، ويتحقق من وصول الأحداث. --- @@ -57,9 +57,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### آلات استدعاء حقيقية +### صك استدعاء حقيقي -في الممارسة العملية، تغلف رمز الوكيل الموجود. ضع قوس نموذج استدعاء باستخدام `model_request` قبل و `model_response` بعد، بحيث يمتد الحدثان على الطلب الحقيقي ويمكن لـ Failproof AI Observability إقرانهما: +في الممارسة العملية، تقوم بلف كود الوكيل الموجود لديك. قم بوضع استدعاء نموذج مع `model_request` قبل و `model_response` بعد ذلك، بحيث يمتد الحدثان على الطلب الحقيقي ويمكن لـ Failproof AI Observability إقرانهما: ```python import anthropic @@ -94,11 +94,11 @@ agenteye.event.model_response( ) ``` -غلف استدعاءات الأداة بنفس الطريقة باستخدام `tool_use` و `tool_result`، وأعد استخدام واحد `tool_call_id` عبر الزوج. +قم بلف استدعاءات الأداة بنفس الطريقة باستخدام `tool_use` و `tool_result`، وأعد استخدام واحد `tool_call_id` عبر الزوج. -إليك كيف تبدو تلك الأحداث بمجرد وصولها إلى لوحة التحكم، مع ترميز ألوان حسب النوع وقابلة للتصفية حسب البيئة والوكيل والجلسة: +إليك ما تبدو عليه تلك الأحداث عند وصولها إلى لوحة المعلومات، مع رموز ملونة حسب النوع وقابلة للتصفية حسب البيئة والوكيل والجلسة: -![تدفق الأحداث المباشر، مع ترميز ألوان حسب نوع الحدث وقابل للتصفية حسب البيئة والوكيل والجلسة](/agenteye/images/events-stream.png) +![دفق الأحداث المباشر، مع رموز ملونة حسب نوع الحدث وقابل للتصفية حسب البيئة والوكيل والجلسة](/agenteye/images/events-stream.png) --- @@ -112,18 +112,17 @@ agenteye.configure( ) ``` -اتصل مرة واحدة قبل أي استدعاء `event.*`. آمن للحذف؛ الإعدادات الافتراضية تعمل في الصندوق. جميع الحجج كلمات رئيسية فقط؛ مررها بالاسم كما هو موضح أعلاه. +اتصل مرة واحدة قبل أي استدعاء `event.*`. من الآمن حذفه؛ الإعدادات الافتراضية تعمل بشكل صحيح. جميع الوسائط مفتاحة فقط؛ مررها بالاسم كما هو موضح أعلاه. -عندما يكون `base_dir` هو `None` (الافتراضي)، يقرأ SDK `$AGENTEYE_HOME` إذا تم تعيينها، -وإلا يعود إلى `~/.agenteye`. هذا يطابق دقة جامع البيانات الخاصة به، -لذا يكون متغير `AGENTEYE_HOME` env واحد يهيئ spool الحدث المشترك لكل من -SDK وجامع البيانات. +عندما يكون `base_dir` هو `None` (الافتراضي)، يقرأ SDK `$AGENTEYE_HOME` إذا كان معينًا، +وإلا فإنه يعود إلى `~/.agenteye`. هذا يطابق دقة المجمع الخاصة به، +لذلك متغير بيئة واحد `AGENTEYE_HOME` يكون SDK والمجمع. --- ## البيئة -ضع تسمية على كل حدث ببيئة نشر (`production`, `staging`, `qa`, `canary`, إلخ). اضبطها مرة واحدة؛ يرفق SDK تلقائياً بكل حدث. +قم بتسمية كل حدث ببيئة نشر (`production`, `staging`, `qa`, `canary`, إلخ). اضبطه مرة واحدة؛ يرفق SDK به تلقائيًا إلى كل حدث. **الخيار 1: عبر `configure()`:** @@ -137,36 +136,36 @@ agenteye.configure(environment="production") export AGENTEYE_ENVIRONMENT=production ``` -**الأولوية:** `configure(environment=...)` يفوز على متغير البيئة. إذا لم يتم تعيين أي منهما، فإنه يعود افتراضياً إلى `"dev"`. +**الأولوية:** `configure(environment=...)` يفوز على متغير البيئة. إذا لم يتم تعيين أي منهما، فالافتراضي هو `"dev"`. -تظهر قيمة البيئة كمرشح من الدرجة الأولى في لوحة التحكم وتُخزن على الخادم للاستعلامات السريعة. +تظهر قيمة البيئة كمرشح من الدرجة الأولى في لوحة المعلومات وتُخزن على الخادم للاستعلامات السريعة. -> **تحذير:** قيم البيئة يجب ألا تحتوي على فاصلة `,` حرفية. تستخدم مرشحات لوحة التحكم متعدد الاختيار مفصول بفواصل على السلك (`?environment=prod,staging`)، لذا ستقسم بيئة مسماة `prod,blue` إلى قيمتين. يتم رفض الأحداث ذات البيئات التي تحتوي على فواصل عند وقت الحقن. +> **تحذير:** قيم البيئة يجب ألا تحتوي على فاصلة حرفية `,`. تستخدم مرشحات لوحة المعلومات الاختيار المتعدد المفصول بفواصل على السلك (`?environment=prod,staging`)، لذلك ستُقسم بيئة باسم `prod,blue` إلى قيمتين. يتم رفض الأحداث ذات البيئات التي تحتوي على فواصل في وقت الالتقاط. --- ## البيانات والخصوصية -يسجل SDK فقط الحقول التي تمررها بشكل صريح. يتم التقاط الأوامر والرسائل ومدخلات الأداة ومخرجاتها ومحتوى النموذج فقط لأنك تمررها إلى استدعاء `event.*`. لا يتم قراءة أي شيء من عمليتك أو التقاطه ضمنياً. أي حقل تتركه غير معين يُحذف من الحدث بالكامل؛ لم تُكتب إلى القرص. +يسجل SDK فقط الحقول التي تمررها بشكل صريح. يتم التقاط المطالبات والرسائل والمدخلات والمخرجات الأداة ومحتوى النموذج فقط لأنك تسلمها إلى استدعاء `event.*`. لا يتم قراءة أي شيء من العملية الخاصة بك أو التقاطه بشكل ضمني. أي حقل لم تقم بتعيينه يتم حذفه من الحدث بالكامل؛ لم يتم كتابته إلى القرص. -هذا يجعل التنقية خيارك ومسؤوليتك. إذا كان الأمر أو حمولة الأداة تحتوي على PII أو أسرار كنت تفضل عدم تخزينها، قم بتجريدها أو إخفاؤها قبل أن تمررها إلى طريقة الحدث. +هذا يجعل التحرير من عدم الكشف عن الهوية خيارك ومسؤوليتك. إذا كانت المطالبة أو حمولة الأداة تحتوي على معلومات تعريف شخصية أو أسرار لا تريد تخزينها، قم بإزالتها أو إخفاؤها قبل تمريرها إلى طريقة الحدث. --- ## مرجع الحدث -معظم الأحداث تأتي في أزواج البداية / النهاية التي تشارك معرّف ارتباط: `tool_use` و `tool_result` يشاركان `tool_call_id`، `hook_triggered` و `hook_completed` يشاركان `hook_id`، و `human_wait` و `human_input` يشاركان `input_id`. أصدر حدث البداية، قم بالعمل، ثم أصدر حدث النهاية بنفس المعرّف. تطابق Failproof AI Observability الزوج وحساب `duration_ms` لك، لذا لا تمرر `duration_ms` بنفسك. +تأتي معظم الأحداث في أزواج start/end التي تشارك معرف الارتباط: `tool_use` و `tool_result` يشاركان `tool_call_id`, `hook_triggered` و `hook_completed` يشاركان `hook_id`, و `human_wait` و `human_input` يشاركان `input_id`. أصدر حدث البداية، قم بالعمل، ثم أصدر حدث النهاية بنفس المعرف. يطابق Failproof AI Observability الزوج ويحسب `duration_ms` لك، لذلك لا تمرر `duration_ms` بنفسك أبدًا. -![رسم بياني لتنفيذ نمط git للجلسة بجانب خط زمني الحدث الخاص به، تم إعادة بنائه من الأحداث المقترنة، مع لوحة تقسيم الأداة / النموذج / الخطاف](/agenteye/images/session-detail.png) +![رسم بياني لتنفيذ جلسة بنمط git بجانب الخط الزمني للحدث الخاص بها، تم إعادة بناؤه من الأحداث المقترنة، مع لوحة تفصيل الأداة/النموذج/الخطاف](/agenteye/images/session-detail.png) تتطلب جميع طرق الحدث هذين الحقلين: | الحقل | النوع | الوصف | |---|---|---| | `session_id` | `str` | يحدد تشغيل الوكيل من المستوى الأعلى | -| `agent_id` | `str` | يحدد الوكيل الذي أصدر الحدث ضمن الجلسة | +| `agent_id` | `str` | يحدد الوكيل الذي أصدر الحدث | -تقبل جميع الطرق أيضاً `**kwargs` عشوائياً للبيانات الوصفية المخصصة (انظر [Custom Fields](#custom-fields)). +تقبل جميع الطرق أيضًا `**kwargs` عشوائي للبيانات الوصفية المخصصة (انظر [Custom Fields](#custom-fields)). --- @@ -202,7 +201,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -يتم إصداره عندما يستدعي الوكيل أداة. اقرن مع `tool_result`؛ يحسب SDK تلقائياً `duration_ms`. +يتم إصداره عندما يستدعي الوكيل أداة. ارتبط مع `tool_result`؛ يحسب SDK تلقائيًا `duration_ms`. ```python agenteye.event.tool_use( @@ -218,7 +217,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -يتم إصداره عندما تعود أداة. يرتبط مع `tool_use` عبر `tool_call_id`. +يتم إصداره عندما تعيد أداة. يرتبط مع `tool_use` عبر `tool_call_id`. ```python agenteye.event.tool_result( @@ -236,7 +235,7 @@ agenteye.event.tool_result( ### `event.model_request()` -يتم إصداره قبل إرسال فوري إلى LLM مباشرة. +يتم إصداره قبل إرسال مطالبة إلى LLM مباشرة. ```python agenteye.event.model_request( @@ -253,13 +252,13 @@ agenteye.event.model_request( ) ``` -تقبل إدخالات `messages` إما محتوى سلسلة عادية `content` أو Anthropic-style list-of-blocks `content`. يمكن تمرير معاملات العينات (`temperature`, `max_tokens`, إلخ) كـ kwargs إضافية. +تقبل إدخالات `messages` إما محتوى سلسلة عادي `content` أو محتوى قائمة الكتل بنمط Anthropic `content`. يمكن تمرير معاملات أخذ العينات (`temperature`, `max_tokens`, إلخ) كـ kwargs إضافية. --- ### `event.model_response()` -يتم إصداره عندما يعود LLM برد. +يتم إصداره عندما يُرجع LLM استجابة. ```python agenteye.event.model_response( @@ -276,13 +275,13 @@ agenteye.event.model_response( ) ``` -يقبل `content` إما سلسلة عادية (موفري عام) أو قائمة كتل محتوى نمط Anthropic. تعيش استدعاءات الأداة داخل `content` كـ `{"type": "tool_use", ...}` كتل، بدون حقل `tool_calls` منفصل. +يقبل `content` إما سلسلة عادية (موفرون عام) أو قائمة كتل محتوى بنمط Anthropic. استدعاءات الأداة تعيش داخل `content` كـ `{"type": "tool_use", ...}` كتل، بدون حقل `tool_calls` منفصل. --- ### `event.hook_triggered()` -يتم إصداره عندما يطلق خطاف. اقرن مع `hook_completed`؛ يحسب SDK تلقائياً `duration_ms`. +يتم إصداره عندما يطلق خطاف. ارتبط مع `hook_completed`؛ يحسب SDK تلقائيًا `duration_ms`. ```python agenteye.event.hook_triggered( @@ -299,7 +298,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -يتم إصداره عندما ينتهي الخطاف. يرتبط مع `hook_triggered` عبر `hook_id`. +يتم إصداره عندما ينتهي خطاف. يرتبط مع `hook_triggered` عبر `hook_id`. ```python agenteye.event.hook_completed( @@ -318,7 +317,7 @@ agenteye.event.hook_completed( ### `event.error()` -يتم إصداره عندما يحدث خطأ لم يتم معالجته. +يتم إصداره عندما يحدث خطأ لم يتم التعامل معه. ```python agenteye.event.error( @@ -332,13 +331,13 @@ agenteye.event.error( --- -## أحداث العنصر البشري في الحلقة +## أحداث الإنسان في الحلقة -تمنحك أحداث العنصر البشري في الحلقة الإشراف على اللحظات التي يتدخل فيها شخص في تنفيذ الوكيل (في انتظار الموافقة، أو توفير المدخلات، أو إيقاف الوكيل مؤقتاً، أو إيقافه). تتيح لك قياس مدى استغراق البشر للاستجابة (يحسب SDK تلقائياً `duration_ms` على الأحداث المقترنة)، ودقق من قام بإيقاف الوكيل أو مقاطعته، وبناء مسارات موافقة وإشراف التي تظهر في لوحة التحكم. +توفر أحداث الإنسان في الحلقة لك الإشراف على اللحظات التي يخطو فيها شخص ما إلى تنفيذ الوكيل (انتظار الموافقة، توفير المدخلات، الإيقاف المؤقت، أو إيقاف الوكيل). تتيح لك قياس المدة التي يستغرقها البشر للرد (يحسب SDK تلقائيًا `duration_ms` على الأحداث المقترنة)، تدقيق من أيقف أو قاطع الوكيل، وبناء تدفقات الموافقة والإشراف التي تظهر في لوحة المعلومات. ### `event.human_wait()` -يتم إصداره عندما يعلق الوكيل التنفيذ في انتظار بشري لتوفير المدخلات. اقرن مع `human_input`؛ يحسب SDK تلقائياً `duration_ms` (مدة استجابة البشر). +يتم إصداره عندما يوقف الوكيل التنفيذ للانتظار حتى يوفر الإنسان المدخلات. ارتبط مع `human_input`؛ يحسب SDK تلقائيًا `duration_ms` (المدة التي استغرقها الإنسان للرد). ```python agenteye.event.human_wait( @@ -353,7 +352,7 @@ agenteye.event.human_wait( ### `event.human_input()` -يتم إصداره عندما يوفر بشري مدخلات ويستأنف الوكيل. يرتبط مع `human_wait` عبر `input_id`. يتم حساب `duration_ms` تلقائياً ولا يجب أن يمرره المتصل. +يتم إصداره عندما يوفر الإنسان المدخلات ويستأنف الوكيل. يرتبط مع `human_wait` عبر `input_id`. يتم حساب `duration_ms` تلقائيًا ولا يجب تمريره من قبل المتصل. ```python agenteye.event.human_input( @@ -367,7 +366,7 @@ agenteye.event.human_input( ### `event.human_pause()` -يتم إصداره عندما يعلق بشري الوكيل بنشاط (على سبيل المثال عبر تحكم لوحة التحكم). يتم تعليق الوكيل ولكن لم يتم إنهاؤه. +يتم إصداره عندما يوقف الإنسان الوكيل بنشاط (على سبيل المثال عبر تحكم لوحة المعلومات). تم إيقاف الوكيل مؤقتًا لكن لم يتم إنهاؤه. ```python agenteye.event.human_pause( @@ -380,7 +379,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -يتم إصداره عندما يوقف بشري الوكيل بنشاط أثناء التنفيذ. بخلاف `human_pause`، يتم إنهاء عمل الوكيل بدلاً من تعليقه. +يتم إصداره عندما يوقف الإنسان الوكيل بنشاط أثناء التنفيذ. بخلاف `human_pause`، يتم إنهاء عمل الوكيل بدلاً من تعليقه. ```python agenteye.event.human_interrupt( @@ -394,9 +393,9 @@ agenteye.event.human_interrupt( --- -## الحقول المخصصة +## حقول مخصصة -يتم إضافة أي حجج كلمات رئيسية إضافية إلى الحدث بعد الحقول القياسية: +يتم إضافة أي وسائط كلمات رئيسية إضافية إلى الحدث بعد الحقول القياسية: ```python agenteye.event.tool_use( @@ -409,25 +408,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`، `type`، و `environment` محجوزة وترفع `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) إذا تم تمريرها كحقول مخصصة. `session_id` و `agent_id` معاملات مطلوبة في كل طريقة حدث ولا يمكن توريدها مرة أخرى؛ Python يرفع `TypeError` إذا فعلت. اضبط البيئة باستخدام `configure(environment=...)` (أو متغير `AGENTEYE_ENVIRONMENT`) بدلاً من ذلك. +`timestamp` و `type` و `environment` محجوزة وتثير `ValueError` (حقول الأسماء المحجوزة لا يمكن استخدامها كحقول مخصصة: [...]) إذا تم تمريرها كحقول مخصصة. `session_id` و `agent_id` معاملات مطلوبة على كل طريقة حدث ولا يمكن توريدها مرة ثانية؛ Python يرفع `TypeError` إذا فعلت ذلك. اضبط البيئة بـ `configure(environment=...)` (أو متغير `AGENTEYE_ENVIRONMENT`) بدلاً من ذلك. + +احفظ الحمولات كـ JSON منظم عندما تريد الاستعلام عن حقولها. يتم تحويل القيم التي لا يدعمها JSON أصلاً — مثل datetimes و UUIDs و decimals و sets و bytes أو كائنات النموذج — إلى سلاسل بحيث يستمر التسجيل بأمان. --- -## كيفية كتابة الأحداث +## كيف يتم كتابة الأحداث -يتم تخزين الأحداث مؤقتاً في العملية وغسلها إلى القرص كل `flush_interval` ثانية (500 مللي ثانية افتراضياً). يكتب كل غسل ملف JSONL واحد: +يتم حفظ الأحداث في الذاكرة المؤقتة داخل العملية وحفظها على القرص كل `flush_interval` ثانية (افتراضي 500 مللي ثانية). يكتب كل حفظ ملف JSONL واحد: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -يراقب جامع البيانات هذا الدليل ويرفع الملفات تلقائياً. لا تحتاج إلى إدارة هذه الملفات مباشرة. +يراقب المجمع هذا الدليل ويحمل الملفات تلقائيًا. لا تحتاج إلى إدارة هذه الملفات مباشرة. -يتم كتابة كل ملف بشكل ذري: يكتب SDK إلى ملف مؤقت ثم يعيد تسميته في مكانه، بحيث لا يرى جامع البيانات ملف مكتوب بنصف. يعمل غسل نهائي أيضاً عندما تخرج عمليتك، بحيث لا تُفقد الأحداث المخزنة مؤقتاً في الفترة الأخيرة. إذا كان جامع البيانات في وضع عدم الاتصال، فإن الأحداث تتراكم ببساطة كملفات على القرص وتُرسل بمجرد عودته. +يتم كتابة كل ملف بشكل ذري: يكتب SDK إلى ملف مؤقت ثم يعيد تسميته في مكانه، لذلك لا يرى المجمع أبدًا ملفًا مكتوبًا جزئيًا. يعمل الحفظ النهائي أيضًا عند خروج العملية الخاصة بك، لذلك لا تُفقد الأحداث المخزنة مؤقتًا في الفاصل الأخير. إذا كان المجمع غير متصل، فإن الأحداث تتراكم ببساطة كملفات على القرص وترسل بمجرد عودتها. --- ## الخطوات التالية -- [Event stream](/ar/agenteye/event-stream): اطّلع على وصول تلك الأحداث مباشرة، مع ترميز ألوان وقابلة للتصفية حسب البيئة والوكيل والجلسة. -- [Sessions](/ar/agenteye/sessions): اطّلع على كيفية إعادة بناء الأحداث المقترنة كل تشغيل وكيل كرسم بياني للتنفيذ وجدول زمني. \ No newline at end of file +- [Event stream](/ar/agenteye/event-stream): شاهد هذه الأحداث تصل مباشرة، مع رموز ملونة وقابلة للتصفية حسب البيئة والوكيل والجلسة. +- [Sessions](/ar/agenteye/sessions): شاهد كيف تعيد الأحداث المقترنة بناء كل تشغيل للوكيل كرسم بياني للتنفيذ وخط زمني. \ No newline at end of file diff --git a/docs/de/agenteye/python-sdk.mdx b/docs/de/agenteye/python-sdk.mdx index 8823389e..c734589e 100644 --- a/docs/de/agenteye/python-sdk.mdx +++ b/docs/de/agenteye/python-sdk.mdx @@ -1,12 +1,12 @@ --- title: "Python SDK" -description: "Sehen Sie genau, was Ihre KI-Agenten in der Produktion getan haben: jeden Agentenlauf, Tool-Aufruf, Modellanfrage, Hook und menschlichen Eingriff." +description: "Beobachten Sie genau, was Ihre KI-Agenten in der Produktion getan haben: jeden Agentenlauf, Tool-Aufruf, Modellanfrage, Hook und menschlichen Eingriff." --- -Sehen Sie genau, was Ihre KI-Agenten in der Produktion getan haben: jeden Agentenlauf, Tool-Aufruf, Modellanfrage, Hook und menschlichen Eingriff. Das Failproof AI Observability Python SDK zeichnet diesen Verlauf direkt aus Ihrem Agenten-Code auf, damit Sie debuggen, prüfen und nachvollziehen können, was passiert ist. Verwenden Sie es immer dann, wenn Failproof AI Observability Ihre Agenten beobachten soll. +Beobachten Sie genau, was Ihre KI-Agenten in der Produktion getan haben: jeden Agentenlauf, Tool-Aufruf, Modellanfrage, Hook und menschlichen Eingriff. Das Failproof AI Observability Python SDK zeichnet diesen Verlauf direkt aus Ihrem Agenten-Code auf, damit Sie debuggen, prüfen und nachvollziehen können, was passiert ist. Verwenden Sie es immer dann, wenn Failproof AI Observability Ihre Agenten beobachten soll. -Intern schreibt das SDK strukturierte Events in lokale JSONL-Dateien, und der Collector-Daemon liest diese ein und übermittelt sie automatisch an die Plattform. Sie müssen diese Dateien nicht selbst verwalten. +Im Hintergrund schreibt das SDK strukturierte Events in lokale JSONL-Dateien; der Collector-Daemon liest diese ein und übermittelt sie automatisch an die Plattform. Sie müssen diese Dateien nicht selbst verwalten. > **Tipp:** Neu bei Failproof AI Observability? Diese Seite ist die vollständige SDK-Event-Referenz. @@ -18,7 +18,7 @@ Intern schreibt das SDK strukturierte Events in lokale JSONL-Dateien, und der Co ## Installation -Das SDK wird Kunden als privates Wheel ausgeliefert und nicht über einen öffentlichen Paketindex verteilt. Ihr Onboarding erklärt, wie Sie es erhalten, installieren und versionieren – wenden Sie sich an Ihren Failproof AI-Ansprechpartner, wenn Sie Zugang benötigen. +Das SDK wird Kunden als privates Wheel und nicht über einen öffentlichen Paketindex bereitgestellt. Ihr Onboarding erklärt, wie Sie es beziehen, installieren und versionieren — sprechen Sie Ihren Failproof AI-Ansprechpartner an, wenn Sie Zugang benötigen. Sobald es installiert ist, überprüfen Sie die Installation: @@ -26,11 +26,11 @@ Sobald es installiert ist, überprüfen Sie die Installation: python -c "import agenteye; print(agenteye.__version__)" ``` -Möchten Sie lieber einen Coding-Agenten die gesamte Integration durchführen lassen? Der [Python SDK Agent Skill](/de/agenteye/python-sdk-skill) kennt den Installationspfad, plant die Instrumentierungspunkte, implementiert sie und überprüft, ob die Events ankommen. +Möchten Sie die gesamte Integration lieber von einem Coding-Agenten erledigen lassen? Der [Python SDK Agent Skill](/de/agenteye/python-sdk-skill) kennt den Installationspfad, plant die Instrumentierungspunkte, schreibt sie und verifiziert, dass die Events ankommen. --- -## Quick Start +## Schnellstart ```python import agenteye @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### Einen echten Aufruf instrumentieren -In der Praxis umschließen Sie Ihren bestehenden Agenten-Code. Klammern Sie einen Modellaufruf mit `model_request` davor und `model_response` danach ein, damit die beiden Events die echte Anfrage umspannen und Failproof AI Observability sie einander zuordnen kann: +In der Praxis wrappen Sie Ihren bestehenden Agenten-Code. Umschließen Sie einen Modellaufruf mit `model_request` davor und `model_response` danach, sodass die beiden Events die eigentliche Anfrage umspannen und Failproof AI Observability sie einander zuordnen kann: ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -Umschließen Sie Tool-Aufrufe auf dieselbe Weise mit `tool_use` und `tool_result`, und verwenden Sie dabei eine gemeinsame `tool_call_id` für das Paar. +Wrappen Sie Tool-Aufrufe auf dieselbe Weise mit `tool_use` und `tool_result`, wobei Sie eine `tool_call_id` für das jeweilige Paar wiederverwenden. -So sehen diese Events aus, sobald sie das Dashboard erreichen – farbcodiert nach Typ und filterbar nach Umgebung, Agent und Session: +So sehen diese Events aus, sobald sie das Dashboard erreichen — farblich nach Typ kodiert und nach Umgebung, Agent und Session filterbar: -![Der Live-Events-Stream, farbcodiert nach Event-Typ und filterbar nach Umgebung, Agent und Session](/agenteye/images/events-stream.png) +![Der Live-Events-Stream, farblich nach Event-Typ kodiert und nach Umgebung, Agent und Session filterbar](/agenteye/images/events-stream.png) --- @@ -113,26 +113,26 @@ agenteye.configure( ) ``` -Einmalig vor jedem `event.*`-Aufruf aufrufen. Kann weggelassen werden; die Standardwerte funktionieren sofort. Alle Argumente sind nur als Schlüsselwortargumente verwendbar; übergeben Sie sie wie oben gezeigt mit Namen. +Einmal vor dem ersten `event.*`-Aufruf aufrufen. Kann weggelassen werden; die Standardwerte funktionieren sofort. Alle Argumente sind Keyword-only; übergeben Sie sie wie oben gezeigt mit Namen. Wenn `base_dir` `None` ist (Standard), liest das SDK `$AGENTEYE_HOME`, falls gesetzt, -und fällt andernfalls auf `~/.agenteye` zurück. Dies entspricht der Auflösung des Collectors, -sodass eine einzige `AGENTEYE_HOME`-Umgebungsvariable den gemeinsamen Event-Spool für sowohl -das SDK als auch den Collector konfiguriert. +und fällt andernfalls auf `~/.agenteye` zurück. Dies entspricht der eigenen Auflösungslogik des Collectors, +sodass eine einzelne `AGENTEYE_HOME`-Umgebungsvariable den gemeinsamen Event-Spool für +das SDK und den Collector konfiguriert. --- ## Umgebung -Versehen Sie jedes Event mit einem Deployment-Umgebungs-Label (`production`, `staging`, `qa`, `canary` usw.). Einmal gesetzt, hängt das SDK es automatisch an jedes Event an. +Versehen Sie jedes Event mit einem Deployment-Environment-Label (`production`, `staging`, `qa`, `canary` usw.). Einmal setzen; das SDK hängt es automatisch an jedes Event an. -**Option 1: via `configure()`:** +**Option 1: über `configure()`:** ```python agenteye.configure(environment="production") ``` -**Option 2: via Umgebungsvariable:** +**Option 2: über Umgebungsvariable:** ```bash export AGENTEYE_ENVIRONMENT=production @@ -140,40 +140,40 @@ export AGENTEYE_ENVIRONMENT=production **Priorität:** `configure(environment=...)` hat Vorrang vor der Umgebungsvariable. Wenn keines von beidem gesetzt ist, wird standardmäßig `"dev"` verwendet. -Der Umgebungswert erscheint als erstklassiger Filter im Dashboard und wird serverseitig für schnelle Abfragen gespeichert. +Der Environment-Wert erscheint als erstklassiger Filter im Dashboard und wird für schnelle Abfragen auf dem Server gespeichert. -> **Warnung:** Umgebungswerte dürfen kein literales `,`-Komma enthalten. Die Dashboard-Filter verwenden kommagetrennte Mehrfachauswahl über den HTTP-Parameter (`?environment=prod,staging`), sodass eine Umgebung namens `prod,blue` in zwei Werte aufgeteilt würde. Events mit kommaenthaltenden Umgebungswerten werden beim Einlesen abgelehnt. +> **Warnung:** Environment-Werte dürfen kein wörtliches `,`-Komma enthalten. Die Dashboard-Filter verwenden kommagetrennte Mehrfachauswahl in der URL (`?environment=prod,staging`), sodass ein Environment namens `prod,blue` in zwei Werte aufgeteilt würde. Events mit Komma-enthaltenden Environments werden beim Ingest abgelehnt. --- ## Daten und Datenschutz -Das SDK zeichnet nur die Felder auf, die Sie explizit übergeben. Prompts, Nachrichten, Tool-Eingaben und -Ausgaben sowie Modell-Inhalte werden ausschließlich deshalb erfasst, weil Sie sie an einen `event.*`-Aufruf übergeben. Aus Ihrem Prozess wird nichts gelesen und nichts implizit erfasst. Jedes Feld, das Sie nicht setzen, wird vollständig aus dem Event weggelassen und nicht auf Disk geschrieben. +Das SDK zeichnet nur die Felder auf, die Sie explizit übergeben. Prompts, Nachrichten, Tool-Eingaben und -Ausgaben sowie Modellinhalt werden ausschließlich erfasst, weil Sie sie einem `event.*`-Aufruf übergeben. Es wird nichts aus Ihrem Prozess gelesen oder implizit erfasst. Jedes Feld, das Sie weglassen, wird vollständig aus dem Event ausgelassen; es wird nicht auf die Festplatte geschrieben. -Damit liegt die Bereinigung in Ihrer Hand und Verantwortung. Wenn ein Prompt oder ein Tool-Payload personenbezogene Daten oder Geheimnisse enthält, die Sie nicht speichern möchten, filtern oder maskieren Sie diese, bevor Sie sie an die Event-Methode übergeben. +Das macht die Schwärzung zu Ihrer Wahl und Verantwortung. Wenn ein Prompt oder ein Tool-Payload personenbezogene Daten oder Geheimnisse enthält, die Sie lieber nicht speichern möchten, entfernen oder maskieren Sie diese, bevor Sie sie an die Event-Methode übergeben. --- ## Event-Referenz -Die meisten Events kommen in Start/End-Paaren, die eine Korrelations-ID teilen: `tool_use` und `tool_result` teilen eine `tool_call_id`, `hook_triggered` und `hook_completed` teilen eine `hook_id`, und `human_wait` und `human_input` teilen eine `input_id`. Senden Sie das Start-Event, führen Sie die Arbeit durch und senden Sie dann das End-Event mit derselben ID. Failproof AI Observability ordnet das Paar einander zu und berechnet `duration_ms` für Sie – Sie übergeben `duration_ms` also nie selbst. +Die meisten Events kommen in Start/End-Paaren, die eine Korrelations-ID teilen: `tool_use` und `tool_result` teilen eine `tool_call_id`, `hook_triggered` und `hook_completed` teilen eine `hook_id`, und `human_wait` und `human_input` teilen eine `input_id`. Senden Sie das Start-Event, führen Sie die Arbeit aus und senden Sie dann das End-Event mit derselben ID. Failproof AI Observability ordnet das Paar zu und berechnet `duration_ms` für Sie — Sie übergeben `duration_ms` daher nie selbst. -![Der git-artige Ausführungsgraph einer Session neben ihrer Event-Zeitachse, rekonstruiert aus den gepaarten Events, mit dem Tool/Model/Hook-Übersichtspanel](/agenteye/images/session-detail.png) +![Ein git-ähnlicher Ausführungsgraph einer Session neben ihrer Event-Zeitleiste, rekonstruiert aus den gepaarten Events, mit dem Tool/Model/Hook-Aufschlüsselungspanel](/agenteye/images/session-detail.png) -Alle Event-Methoden erfordern diese zwei Felder: +Alle Event-Methoden erfordern diese beiden Felder: | Feld | Typ | Beschreibung | |---|---|---| | `session_id` | `str` | Identifiziert den übergeordneten Agentenlauf | | `agent_id` | `str` | Identifiziert, welcher Agent innerhalb der Session das Event ausgelöst hat | -Alle Methoden akzeptieren außerdem beliebige `**kwargs` für benutzerdefinierte Metadaten (siehe [Benutzerdefinierte Felder](#custom-fields)). +Alle Methoden akzeptieren auch beliebige `**kwargs` für benutzerdefinierte Metadaten (siehe [Benutzerdefinierte Felder](#custom-fields)). --- ### `event.agent_start()` -Wird ausgelöst, wenn ein Agent seine Arbeit beginnt. +Wird ausgelöst, wenn ein Agent mit der Arbeit beginnt. ```python agenteye.event.agent_start( @@ -188,7 +188,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Wird ausgelöst, wenn ein Agent seine Arbeit beendet. +Wird ausgelöst, wenn ein Agent die Arbeit beendet. ```python agenteye.event.agent_end( @@ -203,7 +203,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -Wird ausgelöst, wenn ein Agent ein Tool aufruft. Mit `tool_result` paaren; das SDK berechnet `duration_ms` automatisch. +Wird ausgelöst, wenn ein Agent ein Tool aufruft. In Kombination mit `tool_result` verwendet; das SDK berechnet `duration_ms` automatisch. ```python agenteye.event.tool_use( @@ -219,7 +219,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -Wird ausgelöst, wenn ein Tool zurückkehrt. Korreliert mit `tool_use` über `tool_call_id`. +Wird ausgelöst, wenn ein Tool eine Antwort zurückgibt. Korreliert mit `tool_use` über `tool_call_id`. ```python agenteye.event.tool_result( @@ -237,7 +237,7 @@ agenteye.event.tool_result( ### `event.model_request()` -Wird ausgelöst, kurz bevor ein Prompt an ein LLM gesendet wird. +Wird unmittelbar vor dem Senden eines Prompts an ein LLM ausgelöst. ```python agenteye.event.model_request( @@ -254,7 +254,7 @@ agenteye.event.model_request( ) ``` -`messages`-Einträge akzeptieren entweder einen einfachen String als `content` oder Anthropic-artigen Listen-von-Blöcken als `content`. Sampling-Parameter (`temperature`, `max_tokens` usw.) können als zusätzliche kwargs übergeben werden. +`messages`-Einträge akzeptieren entweder einen einfachen String als `content` oder Anthropic-Stil Listen von Content-Blöcken als `content`. Sampling-Parameter (`temperature`, `max_tokens` usw.) können als zusätzliche kwargs übergeben werden. --- @@ -277,13 +277,13 @@ agenteye.event.model_response( ) ``` -`content` akzeptiert entweder einen einfachen String (generische Anbieter) oder eine Liste von Anthropic-artigen Content-Blöcken. Tool-Aufrufe befinden sich innerhalb von `content` als `{"type": "tool_use", ...}`-Blöcke, ohne ein separates `tool_calls`-Feld. +`content` akzeptiert entweder einen einfachen String (generische Provider) oder eine Liste von Anthropic-Stil Content-Blöcken. Tool-Aufrufe befinden sich innerhalb von `content` als `{"type": "tool_use", ...}`-Blöcke, ohne ein separates `tool_calls`-Feld. --- ### `event.hook_triggered()` -Wird ausgelöst, wenn ein Hook feuert. Mit `hook_completed` paaren; das SDK berechnet `duration_ms` automatisch. +Wird ausgelöst, wenn ein Hook feuert. In Kombination mit `hook_completed` verwendet; das SDK berechnet `duration_ms` automatisch. ```python agenteye.event.hook_triggered( @@ -335,11 +335,11 @@ agenteye.event.error( ## Human-in-the-Loop-Events -Human-in-the-Loop-Events geben Ihnen Kontrolle über die Momente, in denen eine Person in die Ausführung des Agenten eingreift (auf Genehmigung warten, Eingaben bereitstellen, pausieren oder den Agenten stoppen). Sie ermöglichen es Ihnen, zu messen, wie lange Menschen für eine Reaktion benötigen (das SDK berechnet `duration_ms` bei gepaarten Events automatisch), nachzuverfolgen, wer einen Agenten pausiert oder unterbrochen hat, und Genehmigungs- und Überwachungs-Workflows zu erstellen, die im Dashboard angezeigt werden. +Human-in-the-Loop-Events geben Ihnen Einblick in die Momente, in denen eine Person in die Ausführung des Agenten eingreift (warten auf Genehmigung, Eingaben bereitstellen, pausieren oder den Agenten stoppen). Sie ermöglichen es Ihnen zu messen, wie lange Menschen für eine Antwort benötigen (das SDK berechnet `duration_ms` bei gepaarten Events automatisch), zu prüfen, wer einen Agenten pausiert oder unterbrochen hat, und Genehmigungs- und Überwachungs-Workflows zu erstellen, die im Dashboard angezeigt werden. ### `event.human_wait()` -Wird ausgelöst, wenn der Agent die Ausführung unterbricht, um auf eine menschliche Eingabe zu warten. Mit `human_input` paaren; das SDK berechnet `duration_ms` (wie lange der Mensch für eine Antwort brauchte) automatisch. +Wird ausgelöst, wenn der Agent die Ausführung unterbricht, um auf eine menschliche Eingabe zu warten. In Kombination mit `human_input` verwendet; das SDK berechnet `duration_ms` (wie lange der Mensch für eine Antwort benötigte) automatisch. ```python agenteye.event.human_wait( @@ -354,7 +354,7 @@ agenteye.event.human_wait( ### `event.human_input()` -Wird ausgelöst, wenn ein Mensch eine Eingabe macht und der Agent die Ausführung fortsetzt. Korreliert mit `human_wait` über `input_id`. `duration_ms` wird automatisch berechnet und darf vom Aufrufer nicht übergeben werden. +Wird ausgelöst, wenn ein Mensch eine Eingabe bereitstellt und der Agent die Ausführung fortsetzt. Korreliert mit `human_wait` über `input_id`. `duration_ms` wird automatisch berechnet und darf nicht vom Aufrufer übergeben werden. ```python agenteye.event.human_input( @@ -397,7 +397,7 @@ agenteye.event.human_interrupt( ## Benutzerdefinierte Felder -Alle zusätzlichen Schlüsselwortargumente werden nach den Standardfeldern an das Event angehängt: +Alle zusätzlichen Keyword-Argumente werden nach den Standardfeldern an das Event angehängt: ```python agenteye.event.tool_use( @@ -410,13 +410,15 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` und `environment` sind reserviert und lösen einen `ValueError` aus (`Reserved field names cannot be used as custom fields: [...]`), wenn sie als benutzerdefinierte Felder übergeben werden. `session_id` und `agent_id` sind erforderliche Parameter jeder Event-Methode und können nicht ein zweites Mal angegeben werden; Python löst in diesem Fall einen `TypeError` aus. Setzen Sie die Umgebung stattdessen mit `configure(environment=...)` (oder der `AGENTEYE_ENVIRONMENT`-Variable). +`timestamp`, `type` und `environment` sind reserviert und lösen einen `ValueError` aus (`Reserved field names cannot be used as custom fields: [...]`), wenn sie als benutzerdefinierte Felder übergeben werden. `session_id` und `agent_id` sind Pflichtparameter bei jeder Event-Methode und können nicht ein zweites Mal übergeben werden; Python löst in diesem Fall einen `TypeError` aus. Setzen Sie die Umgebung stattdessen mit `configure(environment=...)` (oder der `AGENTEYE_ENVIRONMENT`-Variable). + +Halten Sie Payloads als strukturiertes JSON, wenn Sie deren Felder abfragen möchten. Werte, die JSON nicht nativ unterstützt — wie Datetimes, UUIDs, Decimals, Sets, Bytes oder Modell-Objekte — werden in Strings konvertiert, damit die Aufzeichnung sicher fortgesetzt werden kann. --- ## Wie Events geschrieben werden -Events werden prozessintern gepuffert und alle `flush_interval` Sekunden auf Disk geschrieben (Standard: 500 ms). Jeder Flush schreibt eine JSONL-Datei: +Events werden prozessintern gepuffert und alle `flush_interval` Sekunden (Standard: 500 ms) auf die Festplatte geschrieben. Jeder Flush schreibt eine JSONL-Datei: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl @@ -424,11 +426,11 @@ Events werden prozessintern gepuffert und alle `flush_interval` Sekunden auf Dis Der Collector überwacht dieses Verzeichnis und lädt Dateien automatisch hoch. Sie müssen diese Dateien nicht direkt verwalten. -Jede Datei wird atomar geschrieben: Das SDK schreibt in eine temporäre Datei und benennt sie dann an die endgültige Position um, sodass der Collector nie eine unvollständig geschriebene Datei sieht. Ein abschließender Flush wird auch beim Beenden Ihres Prozesses ausgeführt, damit Events, die im letzten Intervall gepuffert wurden, nicht verloren gehen. Wenn der Collector offline ist, akkumulieren sich Events einfach als Dateien auf Disk und werden übertragen, sobald er wieder online ist. +Jede Datei wird atomar geschrieben: Das SDK schreibt in eine temporäre Datei und benennt sie dann an den endgültigen Ort um, sodass der Collector nie eine halbfertige Datei sieht. Ein abschließender Flush wird auch beim Beenden Ihres Prozesses ausgeführt, sodass im letzten Intervall gepufferte Events nicht verloren gehen. Wenn der Collector offline ist, sammeln sich Events einfach als Dateien auf der Festplatte an und werden übermittelt, sobald er wieder verfügbar ist. --- ## Nächste Schritte -- [Event-Stream](/de/agenteye/event-stream): Beobachten Sie, wie diese Events live eintreffen – farbcodiert und filterbar nach Umgebung, Agent und Session. -- [Sessions](/de/agenteye/sessions): Sehen Sie, wie die gepaarten Events jeden Agentenlauf als Ausführungsgraph und Zeitachse rekonstruieren. \ No newline at end of file +- [Event-Stream](/de/agenteye/event-stream): Beobachten Sie, wie diese Events live ankommen, farblich kodiert und nach Umgebung, Agent und Session filterbar. +- [Sessions](/de/agenteye/sessions): Sehen Sie, wie die gepaarten Events jeden Agentenlauf als Ausführungsgraph und Zeitleiste rekonstruieren. \ No newline at end of file diff --git a/docs/es/agenteye/python-sdk.mdx b/docs/es/agenteye/python-sdk.mdx index 8ed6c990..81c07254 100644 --- a/docs/es/agenteye/python-sdk.mdx +++ b/docs/es/agenteye/python-sdk.mdx @@ -1,14 +1,14 @@ --- title: "Python SDK" -description: "Observa exactamente qué hicieron tus agentes de IA en producción: cada ejecución de agente, llamada a herramienta, solicitud al modelo, hook e intervención humana." +description: "Ve exactamente qué hicieron tus agentes de IA en producción: cada ejecución de agente, llamada a herramienta, solicitud al modelo, hook e intervención humana." --- -Observa exactamente qué hicieron tus agentes de IA en producción: cada ejecución de agente, llamada a herramienta, solicitud al modelo, hook e intervención humana. El SDK de observabilidad de Failproof AI registra ese rastro desde dentro del código de tu agente para que puedas depurar, auditar y evaluar lo que ocurrió. Úsalo siempre que quieras que Failproof AI Observability observe a tus agentes. +Ve exactamente qué hicieron tus agentes de IA en producción: cada ejecución de agente, llamada a herramienta, solicitud al modelo, hook e intervención humana. El SDK de observabilidad Python de Failproof AI registra ese rastro desde dentro del código de tu agente para que puedas depurar, auditar y evaluar lo que ocurrió. Úsalo cuando quieras que Failproof AI Observability observe tus agentes. -Internamente, el SDK escribe eventos estructurados en archivos JSONL locales, y el daemon colector los recoge y los envía a la plataforma automáticamente. No necesitas gestionar esos archivos tú mismo. +Internamente, el SDK escribe eventos estructurados en archivos JSONL locales, y el daemon recolector los recoge y los envía a la plataforma automáticamente. No necesitas gestionar esos archivos tú mismo. -> **Consejo:** ¿Eres nuevo en Failproof AI Observability? Esta página es la referencia completa de eventos del SDK. +> **Consejo:** ¿Es tu primera vez con Failproof AI Observability? Esta página es la referencia completa de eventos del SDK.
@@ -18,7 +18,7 @@ Internamente, el SDK escribe eventos estructurados en archivos JSONL locales, y ## Instalación -El SDK se distribuye a los clientes como un wheel privado, no desde un índice de paquetes público. El proceso de incorporación cubre cómo obtenerlo, instalarlo y fijarlo — habla con tu contacto en Failproof AI si necesitas acceso. +El SDK se distribuye a los clientes como una wheel privada en lugar de desde un índice de paquetes público. Tu proceso de incorporación cubre cómo obtenerla, instalarla y fijar la versión — habla con tu contacto de Failproof AI si necesitas acceso. Una vez instalado, confirma que lo tienes: @@ -26,11 +26,11 @@ Una vez instalado, confirma que lo tienes: python -c "import agenteye; print(agenteye.__version__)" ``` -¿Prefieres que un agente de código haga toda la integración? La [Python SDK Agent Skill](/es/agenteye/python-sdk-skill) conoce la ruta de instalación, planifica los puntos de instrumentación, los escribe y verifica que los eventos lleguen. +¿Prefieres dejar que un agente de código haga toda la integración? La [Python SDK Agent Skill](/es/agenteye/python-sdk-skill) conoce la ruta de instalación, planifica los puntos de instrumentación, los escribe y verifica que los eventos lleguen correctamente. --- -## Inicio rápido +## Inicio Rápido ```python import agenteye @@ -97,9 +97,9 @@ agenteye.event.model_response( Envuelve las llamadas a herramientas de la misma manera con `tool_use` y `tool_result`, reutilizando un mismo `tool_call_id` en el par. -Así se ven esos eventos una vez que llegan al dashboard, codificados por color según su tipo y filtrables por entorno, agente y sesión: +Así se ven esos eventos una vez que llegan al dashboard, con código de colores por tipo y filtrables por entorno, agente y sesión: -![El flujo de eventos en vivo, codificado por colores según el tipo de evento y filtrable por entorno, agente y sesión](/agenteye/images/events-stream.png) +![El flujo de eventos en vivo, con código de colores por tipo de evento y filtrable por entorno, agente y sesión](/agenteye/images/events-stream.png) --- @@ -113,12 +113,12 @@ agenteye.configure( ) ``` -Llámalo una vez antes de cualquier llamada a `event.*`. Se puede omitir; los valores predeterminados funcionan sin configuración adicional. Todos los argumentos son de solo palabra clave; pásalos por nombre como se muestra arriba. +Llámalo una vez antes de cualquier llamada a `event.*`. Es seguro omitirlo; los valores predeterminados funcionan de inmediato. Todos los argumentos son solo de palabra clave; pásalos por nombre como se muestra arriba. -Cuando `base_dir` es `None` (el valor predeterminado), el SDK lee `$AGENTEYE_HOME` si está definida, -y si no, usa `~/.agenteye`. Esto coincide con la resolución propia del colector, -de modo que una sola variable de entorno `AGENTEYE_HOME` configura el spool de eventos compartido tanto -para el SDK como para el colector. +Cuando `base_dir` es `None` (el valor predeterminado), el SDK lee `$AGENTEYE_HOME` si está definido, +y en caso contrario recurre a `~/.agenteye`. Esto coincide con la resolución propia del recolector, +por lo que una sola variable de entorno `AGENTEYE_HOME` configura el spool de eventos compartido tanto +para el SDK como para el recolector. --- @@ -140,34 +140,34 @@ export AGENTEYE_ENVIRONMENT=production **Prioridad:** `configure(environment=...)` tiene precedencia sobre la variable de entorno. Si ninguno está configurado, el valor predeterminado es `"dev"`. -El valor del entorno aparece como filtro de primera clase en el dashboard y se almacena en el servidor para consultas rápidas. +El valor del entorno aparece como un filtro de primer nivel en el dashboard y se almacena en el servidor para consultas rápidas. -> **Advertencia:** Los valores de entorno no deben contener una coma literal `,`. Los filtros del dashboard usan selección múltiple separada por comas en la URL (`?environment=prod,staging`), por lo que un entorno llamado `prod,blue` se dividiría en dos valores. Los eventos con entornos que contienen comas son rechazados en el momento de la ingesta. +> **Advertencia:** Los valores de entorno no deben contener una coma literal `,`. Los filtros del dashboard usan selección múltiple separada por comas en la URL (`?environment=prod,staging`), por lo que un entorno llamado `prod,blue` se dividiría en dos valores. Los eventos con entornos que contengan comas son rechazados en el momento de la ingesta. --- ## Datos y privacidad -El SDK registra únicamente los campos que tú pasas explícitamente. Los prompts, mensajes, entradas y salidas de herramientas, y el contenido del modelo se capturan solo porque tú los proporcionas en una llamada a `event.*`. Nada se lee de tu proceso ni se captura de forma implícita. Cualquier campo que dejes sin definir se omite por completo del evento; no se escribe en disco. +El SDK registra únicamente los campos que pasas explícitamente. Los prompts, mensajes, entradas y salidas de herramientas, y el contenido del modelo se capturan únicamente porque tú los entregas a una llamada `event.*`. Nada se lee de tu proceso ni se captura implícitamente. Cualquier campo que dejes sin definir se omite completamente del evento; no se escribe en disco. -Esto hace que la redacción sea tu elección y tu responsabilidad. Si un prompt o una carga útil de herramienta contiene PII o secretos que prefieres no almacenar, elimínalos o enmascáralos antes de pasarlos al método de evento. +Esto hace que la redacción sea tu elección y tu responsabilidad. Si un prompt o carga útil de herramienta contiene PII o secretos que prefieres no almacenar, elimínalos o enmascáralos antes de pasarlos al método de evento. --- -## Referencia de eventos +## Referencia de Eventos -La mayoría de los eventos vienen en pares de inicio/fin que comparten un ID de correlación: `tool_use` y `tool_result` comparten un `tool_call_id`, `hook_triggered` y `hook_completed` comparten un `hook_id`, y `human_wait` y `human_input` comparten un `input_id`. Emite el evento de inicio, realiza el trabajo y luego emite el evento de fin con el mismo ID. Failproof AI Observability empareja los eventos y calcula el `duration_ms` por ti, por lo que nunca debes pasar `duration_ms` manualmente. +La mayoría de los eventos vienen en pares inicio/fin que comparten un ID de correlación: `tool_use` y `tool_result` comparten un `tool_call_id`, `hook_triggered` y `hook_completed` comparten un `hook_id`, y `human_wait` y `human_input` comparten un `input_id`. Emite el evento de inicio, realiza el trabajo y luego emite el evento de fin con el mismo ID. Failproof AI Observability empareja el par y calcula `duration_ms` por ti, por lo que nunca necesitas pasarlo tú mismo. -![El gráfico de ejecución estilo git de una sesión junto a su línea de tiempo de eventos, reconstruida a partir de los eventos emparejados, con el panel de desglose de herramientas/modelos/hooks](/agenteye/images/session-detail.png) +![El gráfico de ejecución estilo git de una sesión junto a su línea de tiempo de eventos, reconstruido a partir de los eventos emparejados, con el panel de desglose de herramientas/modelos/hooks](/agenteye/images/session-detail.png) -Todos los métodos de eventos requieren estos dos campos: +Todos los métodos de evento requieren estos dos campos: | Campo | Tipo | Descripción | |---|---|---| -| `session_id` | `str` | Identifica la ejecución del agente de nivel superior | +| `session_id` | `str` | Identifica la ejecución de agente de nivel superior | | `agent_id` | `str` | Identifica qué agente dentro de la sesión emitió el evento | -Todos los métodos también aceptan `**kwargs` arbitrarios para metadatos personalizados (ver [Campos personalizados](#custom-fields)). +Todos los métodos también aceptan `**kwargs` arbitrarios para metadatos personalizados (ver [Campos Personalizados](#custom-fields)). --- @@ -203,7 +203,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -Se emite cuando un agente invoca una herramienta. Se empareja con `tool_result`; el SDK calcula automáticamente el `duration_ms`. +Se emite cuando un agente invoca una herramienta. Emparejar con `tool_result`; el SDK calcula `duration_ms` automáticamente. ```python agenteye.event.tool_use( @@ -219,7 +219,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -Se emite cuando una herramienta devuelve un resultado. Se correlaciona con `tool_use` mediante `tool_call_id`. +Se emite cuando una herramienta devuelve un resultado. Correlaciona con `tool_use` mediante `tool_call_id`. ```python agenteye.event.tool_result( @@ -254,7 +254,7 @@ agenteye.event.model_request( ) ``` -Las entradas de `messages` aceptan tanto un `content` de cadena simple como un `content` de lista de bloques al estilo Anthropic. Los parámetros de muestreo (`temperature`, `max_tokens`, etc.) se pueden pasar como kwargs adicionales. +Las entradas de `messages` aceptan tanto un `content` de cadena simple como un `content` de lista de bloques al estilo Anthropic. Los parámetros de muestreo (`temperature`, `max_tokens`, etc.) pueden pasarse como kwargs adicionales. --- @@ -277,13 +277,13 @@ agenteye.event.model_response( ) ``` -`content` acepta tanto una cadena simple (proveedores genéricos) como una lista de bloques de contenido al estilo Anthropic. Las llamadas a herramientas se encuentran dentro de `content` como bloques `{"type": "tool_use", ...}`, sin un campo `tool_calls` separado. +`content` acepta tanto una cadena simple (proveedores genéricos) como una lista de bloques de contenido al estilo Anthropic. Las llamadas a herramientas viven dentro de `content` como bloques `{"type": "tool_use", ...}`, sin un campo `tool_calls` separado. --- ### `event.hook_triggered()` -Se emite cuando se activa un hook. Se empareja con `hook_completed`; el SDK calcula automáticamente el `duration_ms`. +Se emite cuando se activa un hook. Emparejar con `hook_completed`; el SDK calcula `duration_ms` automáticamente. ```python agenteye.event.hook_triggered( @@ -300,7 +300,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Se emite cuando un hook finaliza. Se correlaciona con `hook_triggered` mediante `hook_id`. +Se emite cuando un hook finaliza. Correlaciona con `hook_triggered` mediante `hook_id`. ```python agenteye.event.hook_completed( @@ -333,13 +333,13 @@ agenteye.event.error( --- -## Eventos de intervención humana +## Eventos de Supervisión Humana -Los eventos de intervención humana te ofrecen supervisión sobre los momentos en que una persona participa en la ejecución del agente (esperando aprobación, proporcionando información, pausando o deteniendo el agente). Te permiten medir cuánto tardan los humanos en responder (el SDK calcula automáticamente el `duration_ms` en los eventos emparejados), auditar quién pausó o interrumpió a un agente, y construir flujos de trabajo de aprobación y supervisión que se muestran en el dashboard. +Los eventos de supervisión humana te permiten tener visibilidad sobre los momentos en que una persona interviene en la ejecución del agente (esperando aprobación, proporcionando información, pausando o deteniendo el agente). Te permiten medir cuánto tardan los humanos en responder (el SDK calcula `duration_ms` automáticamente en los eventos emparejados), auditar quién pausó o interrumpió un agente, y construir flujos de trabajo de aprobación y supervisión que se reflejan en el dashboard. ### `event.human_wait()` -Se emite cuando el agente pausa la ejecución para esperar que un humano proporcione información. Se empareja con `human_input`; el SDK calcula automáticamente el `duration_ms` (cuánto tardó el humano en responder). +Se emite cuando el agente pausa su ejecución para esperar que un humano proporcione información. Emparejar con `human_input`; el SDK calcula `duration_ms` automáticamente (cuánto tardó el humano en responder). ```python agenteye.event.human_wait( @@ -354,7 +354,7 @@ agenteye.event.human_wait( ### `event.human_input()` -Se emite cuando un humano proporciona información y el agente se reanuda. Se correlaciona con `human_wait` mediante `input_id`. El `duration_ms` se calcula automáticamente y no debe ser pasado por el llamador. +Se emite cuando un humano proporciona información y el agente se reanuda. Correlaciona con `human_wait` mediante `input_id`. `duration_ms` se calcula automáticamente y no debe ser pasado por el llamador. ```python agenteye.event.human_input( @@ -368,7 +368,7 @@ agenteye.event.human_input( ### `event.human_pause()` -Se emite cuando un humano pausa activamente al agente (por ejemplo, mediante un control del dashboard). El agente queda suspendido pero no finalizado. +Se emite cuando un humano pausa activamente el agente (por ejemplo, mediante un control del dashboard). El agente queda suspendido pero no terminado. ```python agenteye.event.human_pause( @@ -381,7 +381,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -Se emite cuando un humano detiene activamente al agente durante su ejecución. A diferencia de `human_pause`, el trabajo del agente se termina en lugar de suspenderse. +Se emite cuando un humano detiene activamente el agente durante su ejecución. A diferencia de `human_pause`, el trabajo del agente se termina en lugar de suspenderse. ```python agenteye.event.human_interrupt( @@ -395,7 +395,7 @@ agenteye.event.human_interrupt( --- -## Campos personalizados +## Campos Personalizados Cualquier argumento de palabra clave adicional se añade al evento después de los campos estándar: @@ -410,25 +410,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` y `environment` son campos reservados y lanzan `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) si se pasan como campos personalizados. `session_id` y `agent_id` son parámetros obligatorios en cada método de evento y no pueden proporcionarse una segunda vez; Python lanza `TypeError` si lo haces. Configura el entorno con `configure(environment=...)` (o la variable `AGENTEYE_ENVIRONMENT`) en su lugar. +`timestamp`, `type` y `environment` están reservados y lanzan `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) si se pasan como campos personalizados. `session_id` y `agent_id` son parámetros requeridos en todos los métodos de evento y no pueden suministrarse una segunda vez; Python lanza `TypeError` si lo haces. Configura el entorno con `configure(environment=...)` (o la variable `AGENTEYE_ENVIRONMENT`) en su lugar. + +Mantén las cargas útiles como JSON estructurado cuando quieras consultar sus campos. Los valores que JSON no admite de forma nativa — como datetimes, UUIDs, decimales, conjuntos, bytes u objetos de modelo — se convierten a cadenas para que el registro continúe de forma segura. --- -## Cómo se escriben los eventos +## Cómo Se Escriben los Eventos -Los eventos se almacenan en búfer dentro del proceso y se vacían a disco cada `flush_interval` segundos (500 ms por defecto). Cada vaciado escribe un archivo JSONL: +Los eventos se almacenan en búfer en el proceso y se vacían a disco cada `flush_interval` segundos (500 ms por defecto). Cada vaciado escribe un archivo JSONL: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -El colector observa este directorio y sube los archivos automáticamente. No necesitas gestionar estos archivos directamente. +El recolector vigila este directorio y sube los archivos automáticamente. No necesitas gestionar estos archivos directamente. -Cada archivo se escribe de forma atómica: el SDK escribe en un archivo temporal y luego lo renombra en su lugar, por lo que el colector nunca ve un archivo a medio escribir. También se ejecuta un vaciado final cuando tu proceso termina, de modo que los eventos almacenados en el búfer durante el último intervalo no se pierden. Si el colector está desconectado, los eventos simplemente se acumulan como archivos en disco y se envían una vez que vuelve a estar en línea. +Cada archivo se escribe de forma atómica: el SDK escribe en un archivo temporal y luego lo renombra en su lugar, por lo que el recolector nunca ve un archivo escrito a medias. También se ejecuta un vaciado final cuando tu proceso termina, de modo que los eventos almacenados en el último intervalo no se pierden. Si el recolector está desconectado, los eventos simplemente se acumulan como archivos en disco y se envían una vez que vuelva a estar en línea. --- ## Próximos pasos -- [Flujo de eventos](/es/agenteye/event-stream): observa cómo llegan estos eventos en vivo, codificados por colores y filtrables por entorno, agente y sesión. +- [Flujo de eventos](/es/agenteye/event-stream): observa cómo llegan estos eventos en tiempo real, con código de colores y filtrables por entorno, agente y sesión. - [Sesiones](/es/agenteye/sessions): ve cómo los eventos emparejados reconstruyen cada ejecución de agente como un gráfico de ejecución y una línea de tiempo. \ No newline at end of file diff --git a/docs/fr/agenteye/python-sdk.mdx b/docs/fr/agenteye/python-sdk.mdx index 19c35b3c..7e39ba8b 100644 --- a/docs/fr/agenteye/python-sdk.mdx +++ b/docs/fr/agenteye/python-sdk.mdx @@ -1,14 +1,14 @@ --- title: "Python SDK" -description: "Observez exactement ce que vos agents IA ont fait en production : chaque exécution d'agent, appel d'outil, requête de modèle, hook et intervention humaine." +description: "Voyez exactement ce que vos agents IA ont fait en production : chaque exécution d'agent, appel d'outil, requête de modèle, hook et intervention humaine." --- -Observez exactement ce que vos agents IA ont fait en production : chaque exécution d'agent, appel d'outil, requête de modèle, hook et intervention humaine. Le SDK Python Failproof AI Observability enregistre cette trace depuis l'intérieur de votre code d'agent afin que vous puissiez déboguer, auditer et évaluer ce qui s'est passé. Utilisez-le chaque fois que vous souhaitez que Failproof AI Observability observe vos agents. +Voyez exactement ce que vos agents IA ont fait en production : chaque exécution d'agent, appel d'outil, requête de modèle, hook et intervention humaine. Le SDK Python d'observabilité Failproof AI enregistre cette trace depuis l'intérieur de votre code d'agent afin que vous puissiez déboguer, auditer et évaluer ce qui s'est passé. Utilisez-le chaque fois que vous souhaitez que Failproof AI Observability observe vos agents. En coulisses, le SDK écrit des événements structurés dans des fichiers JSONL locaux, et le démon collecteur les récupère et les envoie automatiquement vers la plateforme. Vous n'avez pas à gérer ces fichiers vous-même. -> **Conseil :** Vous débutez avec Failproof AI Observability ? Cette page est la référence complète des événements du SDK. +> **Conseil :** Vous découvrez Failproof AI Observability ? Cette page constitue la référence complète des événements du SDK.
@@ -18,15 +18,15 @@ En coulisses, le SDK écrit des événements structurés dans des fichiers JSONL ## Installation -Le SDK est distribué aux clients sous forme de wheel privé plutôt que depuis un index de paquets public. Votre processus d'intégration explique comment l'obtenir, l'installer et le figer — contactez votre interlocuteur Failproof AI si vous avez besoin d'un accès. +Le SDK est distribué aux clients sous forme de wheel privé plutôt que depuis un index de packages public. Votre onboarding explique comment l'obtenir, l'installer et le fixer à une version — contactez votre interlocuteur Failproof AI si vous avez besoin d'un accès. -Une fois installé, vérifiez que vous l'avez bien : +Une fois installé, vérifiez qu'il est bien présent : ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Vous préférez laisser un agent de code gérer toute l'intégration ? La [compétence Python SDK Agent](/fr/agenteye/python-sdk-skill) connaît le chemin d'installation, planifie les points d'instrumentation, les écrit et vérifie que les événements arrivent bien. +Vous préférez laisser un agent de code gérer toute l'intégration ? La [compétence Agent Python SDK](/fr/agenteye/python-sdk-skill) connaît le chemin d'installation, planifie les points d'instrumentation, les écrit et vérifie que les événements arrivent bien. --- @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### Instrumenter un vrai appel -En pratique, vous enveloppez votre code d'agent existant. Encadrez un appel de modèle avec `model_request` avant et `model_response` après, afin que les deux événements couvrent la vraie requête et que Failproof AI Observability puisse les associer : +En pratique, vous encapsulez votre code d'agent existant. Encadrez un appel de modèle avec `model_request` avant et `model_response` après, afin que les deux événements couvrent la vraie requête et que Failproof AI Observability puisse les associer : ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -Enveloppez les appels d'outils de la même façon avec `tool_use` et `tool_result`, en réutilisant le même `tool_call_id` pour la paire. +Encapsulez les appels d'outils de la même manière avec `tool_use` et `tool_result`, en réutilisant le même `tool_call_id` pour la paire. -Voici à quoi ressemblent ces événements une fois qu'ils arrivent dans le tableau de bord, colorés par type et filtrables par environnement, agent et session : +Voici à quoi ressemblent ces événements une fois qu'ils atteignent le tableau de bord, codés par couleur selon leur type et filtrables par environnement, agent et session : -![Le flux d'événements en direct, coloré par type d'événement et filtrable par environnement, agent et session](/agenteye/images/events-stream.png) +![Le flux d'événements en direct, codé par couleur selon le type d'événement et filtrable par environnement, agent et session](/agenteye/images/events-stream.png) --- @@ -113,18 +113,18 @@ agenteye.configure( ) ``` -À appeler une seule fois avant tout appel à `event.*`. Peut être omis sans risque ; les valeurs par défaut fonctionnent telles quelles. Tous les arguments sont uniquement par mot-clé ; passez-les par nom comme indiqué ci-dessus. +À appeler une fois avant tout appel `event.*`. Peut être omis ; les valeurs par défaut fonctionnent immédiatement. Tous les arguments sont passés par mot-clé uniquement ; utilisez leur nom comme indiqué ci-dessus. -Lorsque `base_dir` vaut `None` (la valeur par défaut), le SDK lit `$AGENTEYE_HOME` s'il est défini, -sinon il revient à `~/.agenteye`. Cela correspond à la propre résolution du collecteur, -de sorte qu'une seule variable d'environnement `AGENTEYE_HOME` configure le spool d'événements partagé -pour le SDK et le collecteur. +Lorsque `base_dir` vaut `None` (valeur par défaut), le SDK lit `$AGENTEYE_HOME` si défini, +sinon il revient à `~/.agenteye`. Cela correspond à la résolution propre du collecteur, +de sorte qu'une seule variable d'environnement `AGENTEYE_HOME` configure le spool d'événements +partagé entre le SDK et le collecteur. --- ## Environnement -Étiquetez chaque événement avec un environnement de déploiement (`production`, `staging`, `qa`, `canary`, etc.). Définissez-le une fois ; le SDK l'associe automatiquement à chaque événement. +Étiquetez chaque événement avec un environnement de déploiement (`production`, `staging`, `qa`, `canary`, etc.). Définissez-le une seule fois ; le SDK l'attache automatiquement à chaque événement. **Option 1 : via `configure()` :** @@ -140,23 +140,23 @@ export AGENTEYE_ENVIRONMENT=production **Priorité :** `configure(environment=...)` prend le dessus sur la variable d'environnement. Si aucun des deux n'est défini, la valeur par défaut est `"dev"`. -La valeur d'environnement apparaît comme un filtre de premier ordre dans le tableau de bord et est stockée sur le serveur pour des requêtes rapides. +La valeur d'environnement apparaît comme un filtre de premier plan dans le tableau de bord et est stockée sur le serveur pour des requêtes rapides. -> **Avertissement :** Les valeurs d'environnement ne doivent pas contenir une virgule `,` littérale. Les filtres du tableau de bord utilisent une multi-sélection séparée par des virgules sur le fil (`?environment=prod,staging`), donc un environnement nommé `prod,blue` serait divisé en deux valeurs. Les événements dont les environnements contiennent des virgules sont rejetés à l'ingestion. +> **Avertissement :** Les valeurs d'environnement ne doivent pas contenir de virgule `,` littérale. Les filtres du tableau de bord utilisent une sélection multiple séparée par des virgules sur le fil (`?environment=prod,staging`), donc un environnement nommé `prod,blue` serait divisé en deux valeurs. Les événements dont l'environnement contient une virgule sont rejetés lors de l'ingestion. --- ## Données et confidentialité -Le SDK n'enregistre que les champs que vous passez explicitement. Les prompts, messages, entrées et sorties d'outils, et le contenu des modèles sont capturés uniquement parce que vous les transmettez à un appel `event.*`. Rien n'est lu depuis votre processus ni capturé implicitement. Tout champ que vous laissez non défini est omis de l'événement ; il n'est pas écrit sur le disque. +Le SDK n'enregistre que les champs que vous passez explicitement. Les prompts, messages, entrées et sorties d'outils, et le contenu du modèle sont capturés uniquement parce que vous les transmettez à un appel `event.*`. Rien n'est lu depuis votre processus ni capturé implicitement. Tout champ que vous laissez non renseigné est omis de l'événement ; il n'est pas écrit sur le disque. -La suppression des données est donc votre choix et votre responsabilité. Si un prompt ou une charge utile d'outil contient des données personnelles ou des secrets que vous préférez ne pas stocker, nettoyez-les ou masquez-les avant de les passer à la méthode d'événement. +La redaction relève donc de votre choix et de votre responsabilité. Si un prompt ou un payload d'outil contient des données personnelles ou des secrets que vous préférez ne pas stocker, nettoyez-les ou masquez-les avant de les passer à la méthode d'événement. --- ## Référence des événements -La plupart des événements viennent par paires début/fin qui partagent un identifiant de corrélation : `tool_use` et `tool_result` partagent un `tool_call_id`, `hook_triggered` et `hook_completed` partagent un `hook_id`, et `human_wait` et `human_input` partagent un `input_id`. Émettez l'événement de début, effectuez le travail, puis émettez l'événement de fin avec le même identifiant. Failproof AI Observability associe la paire et calcule `duration_ms` pour vous, vous n'avez donc jamais à le passer vous-même. +La plupart des événements se présentent par paires début/fin partageant un identifiant de corrélation : `tool_use` et `tool_result` partagent un `tool_call_id`, `hook_triggered` et `hook_completed` partagent un `hook_id`, et `human_wait` et `human_input` partagent un `input_id`. Émettez l'événement de début, effectuez le travail, puis émettez l'événement de fin avec le même identifiant. Failproof AI Observability associe la paire et calcule automatiquement `duration_ms` pour vous ; vous n'avez donc jamais à passer `duration_ms` vous-même. ![Le graphe d'exécution de style git d'une session à côté de sa chronologie d'événements, reconstruit à partir des événements appariés, avec le panneau de répartition outil/modèle/hook](/agenteye/images/session-detail.png) @@ -173,7 +173,7 @@ Toutes les méthodes acceptent également des `**kwargs` arbitraires pour des m ### `event.agent_start()` -Émis quand un agent commence à travailler. +Émis lorsqu'un agent commence à travailler. ```python agenteye.event.agent_start( @@ -188,7 +188,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Émis quand un agent termine son travail. +Émis lorsqu'un agent termine son travail. ```python agenteye.event.agent_end( @@ -203,7 +203,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -Émis quand un agent invoque un outil. À associer avec `tool_result` ; le SDK calcule automatiquement `duration_ms`. +Émis lorsqu'un agent invoque un outil. À associer avec `tool_result` ; le SDK calcule automatiquement `duration_ms`. ```python agenteye.event.tool_use( @@ -219,7 +219,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -Émis quand un outil retourne un résultat. Corrélé avec `tool_use` via `tool_call_id`. +Émis lorsqu'un outil retourne un résultat. Corrélé avec `tool_use` via `tool_call_id`. ```python agenteye.event.tool_result( @@ -254,13 +254,13 @@ agenteye.event.model_request( ) ``` -Les entrées `messages` acceptent soit un `content` sous forme de chaîne simple, soit un `content` sous forme de liste de blocs de style Anthropic. Les paramètres d'échantillonnage (`temperature`, `max_tokens`, etc.) peuvent être passés comme kwargs supplémentaires. +Les entrées `messages` acceptent soit une chaîne `content` simple, soit un `content` de type liste de blocs au format Anthropic. Les paramètres d'échantillonnage (`temperature`, `max_tokens`, etc.) peuvent être passés en kwargs supplémentaires. --- ### `event.model_response()` -Émis quand le LLM retourne une réponse. +Émis lorsque le LLM retourne une réponse. ```python agenteye.event.model_response( @@ -277,13 +277,13 @@ agenteye.event.model_response( ) ``` -`content` accepte soit une chaîne simple (fournisseurs génériques) soit une liste de blocs de contenu de style Anthropic. Les appels d'outils se trouvent dans `content` sous forme de blocs `{"type": "tool_use", ...}`, sans champ `tool_calls` séparé. +`content` accepte soit une chaîne simple (fournisseurs génériques), soit une liste de blocs de contenu au style Anthropic. Les appels d'outils se trouvent dans `content` sous forme de blocs `{"type": "tool_use", ...}`, sans champ `tool_calls` séparé. --- ### `event.hook_triggered()` -Émis quand un hook se déclenche. À associer avec `hook_completed` ; le SDK calcule automatiquement `duration_ms`. +Émis lorsqu'un hook se déclenche. À associer avec `hook_completed` ; le SDK calcule automatiquement `duration_ms`. ```python agenteye.event.hook_triggered( @@ -300,7 +300,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Émis quand un hook se termine. Corrélé avec `hook_triggered` via `hook_id`. +Émis lorsqu'un hook se termine. Corrélé avec `hook_triggered` via `hook_id`. ```python agenteye.event.hook_completed( @@ -319,7 +319,7 @@ agenteye.event.hook_completed( ### `event.error()` -Émis quand une erreur non gérée se produit. +Émis lorsqu'une erreur non gérée se produit. ```python agenteye.event.error( @@ -333,13 +333,13 @@ agenteye.event.error( --- -## Événements humains dans la boucle +## Événements Human-in-the-Loop -Les événements humains dans la boucle vous donnent une visibilité sur les moments où une personne intervient dans l'exécution de l'agent (en attente d'approbation, en fournissant une entrée, en mettant en pause ou en arrêtant l'agent). Ils vous permettent de mesurer le temps que les humains mettent à répondre (le SDK calcule automatiquement `duration_ms` sur les événements appariés), d'auditer qui a mis en pause ou interrompu un agent, et de construire des flux d'approbation et de supervision qui apparaissent dans le tableau de bord. +Les événements human-in-the-loop vous donnent une visibilité sur les moments où une personne intervient dans l'exécution de l'agent (attente d'une approbation, saisie d'une entrée, mise en pause ou arrêt de l'agent). Ils vous permettent de mesurer le temps que les humains mettent à répondre (le SDK calcule automatiquement `duration_ms` sur les événements appariés), d'auditer qui a mis en pause ou interrompu un agent, et de construire des workflows d'approbation et de supervision qui apparaissent dans le tableau de bord. ### `event.human_wait()` -Émis quand l'agent suspend son exécution pour attendre une entrée humaine. À associer avec `human_input` ; le SDK calcule automatiquement `duration_ms` (le temps que l'humain a mis à répondre). +Émis lorsque l'agent interrompt son exécution pour attendre qu'un humain fournisse une entrée. À associer avec `human_input` ; le SDK calcule automatiquement `duration_ms` (le temps que l'humain a mis à répondre). ```python agenteye.event.human_wait( @@ -354,7 +354,7 @@ agenteye.event.human_wait( ### `event.human_input()` -Émis quand un humain fournit une entrée et que l'agent reprend. Corrélé avec `human_wait` via `input_id`. `duration_ms` est calculé automatiquement et ne doit pas être passé par l'appelant. +Émis lorsqu'un humain fournit une entrée et que l'agent reprend. Corrélé avec `human_wait` via `input_id`. `duration_ms` est calculé automatiquement et ne doit pas être passé par l'appelant. ```python agenteye.event.human_input( @@ -368,7 +368,7 @@ agenteye.event.human_input( ### `event.human_pause()` -Émis quand un humain met activement l'agent en pause (par exemple via un contrôle du tableau de bord). L'agent est suspendu mais pas terminé. +Émis lorsqu'un humain met activement en pause l'agent (par exemple via un contrôle du tableau de bord). L'agent est suspendu mais pas arrêté. ```python agenteye.event.human_pause( @@ -381,7 +381,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -Émis quand un humain arrête activement l'agent en cours d'exécution. Contrairement à `human_pause`, le travail de l'agent est terminé plutôt que suspendu. +Émis lorsqu'un humain arrête activement l'agent en cours d'exécution. Contrairement à `human_pause`, le travail de l'agent est terminé plutôt que suspendu. ```python agenteye.event.human_interrupt( @@ -397,7 +397,7 @@ agenteye.event.human_interrupt( ## Champs personnalisés -Tout argument par mot-clé supplémentaire est ajouté à l'événement après les champs standard : +Tout argument mot-clé supplémentaire est ajouté à l'événement après les champs standard : ```python agenteye.event.tool_use( @@ -410,7 +410,9 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` et `environment` sont réservés et lèvent une `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) s'ils sont passés comme champs personnalisés. `session_id` et `agent_id` sont des paramètres obligatoires sur chaque méthode d'événement et ne peuvent pas être fournis une deuxième fois ; Python lève une `TypeError` si vous le faites. Définissez l'environnement avec `configure(environment=...)` (ou la variable `AGENTEYE_ENVIRONMENT`) à la place. +`timestamp`, `type` et `environment` sont réservés et lèvent une `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) s'ils sont passés comme champs personnalisés. `session_id` et `agent_id` sont des paramètres obligatoires sur chaque méthode d'événement et ne peuvent pas être fournis une seconde fois ; Python lève une `TypeError` si vous le faites. Définissez l'environnement avec `configure(environment=...)` (ou la variable `AGENTEYE_ENVIRONMENT`) à la place. + +Conservez les payloads sous forme de JSON structuré lorsque vous souhaitez interroger leurs champs. Les valeurs que JSON ne prend pas nativement en charge — telles que les datetimes, UUIDs, décimaux, ensembles, octets ou objets de modèle — sont converties en chaînes pour que l'enregistrement se poursuive en toute sécurité. --- @@ -422,13 +424,13 @@ Les événements sont mis en mémoire tampon dans le processus et vidés sur le ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -Le collecteur surveille ce répertoire et télécharge les fichiers automatiquement. Vous n'avez pas besoin de gérer ces fichiers directement. +Le collecteur surveille ce répertoire et télécharge les fichiers automatiquement. Vous n'avez pas à gérer ces fichiers directement. -Chaque fichier est écrit de manière atomique : le SDK écrit dans un fichier temporaire puis le renomme à sa place, de sorte que le collecteur ne voit jamais un fichier partiellement écrit. Un vidage final est également effectué à la fermeture de votre processus, afin que les événements mis en mémoire tampon dans le dernier intervalle ne soient pas perdus. Si le collecteur est hors ligne, les événements s'accumulent simplement sous forme de fichiers sur le disque et sont envoyés dès qu'il revient en ligne. +Chaque fichier est écrit de manière atomique : le SDK écrit dans un fichier temporaire puis le renomme à sa place définitive, de sorte que le collecteur ne voit jamais un fichier à moitié écrit. Un vidage final s'exécute également à la fermeture de votre processus, afin que les événements mis en tampon dans le dernier intervalle ne soient pas perdus. Si le collecteur est hors ligne, les événements s'accumulent simplement sous forme de fichiers sur le disque et sont envoyés dès qu'il revient en ligne. --- ## Prochaines étapes -- [Flux d'événements](/fr/agenteye/event-stream) : observez ces événements arriver en direct, colorés et filtrables par environnement, agent et session. +- [Flux d'événements](/fr/agenteye/event-stream) : regardez ces événements arriver en direct, codés par couleur et filtrables par environnement, agent et session. - [Sessions](/fr/agenteye/sessions) : voyez comment les événements appariés reconstituent chaque exécution d'agent sous forme de graphe d'exécution et de chronologie. \ No newline at end of file diff --git a/docs/he/agenteye/python-sdk.mdx b/docs/he/agenteye/python-sdk.mdx index 9e93cdc0..a9992e42 100644 --- a/docs/he/agenteye/python-sdk.mdx +++ b/docs/he/agenteye/python-sdk.mdx @@ -1,14 +1,13 @@ --- title: "Python SDK" -description: "ראו בדיוק מה שסוכני ה-AI שלכם עשו בסביבת הייצור: כל הרצת סוכן, קריאת כלי, בקשת מודל, hook, והתערבות אדם." +description: "ראה בדיוק מה עשו הסוכנים ה-AI שלך בייצור: כל הרצת סוכן, קריאת כלי, בקשת מודל, ווק והתערבות אנושית." --- +ראה בדיוק מה עשו הסוכנים ה-AI שלך בייצור: כל הרצת סוכן, קריאת כלי, בקשת מודל, hook והתערבות אנושית. ה-Python SDK של Failproof AI Observability מתעד את השביל הזה מתוך קוד הסוכן שלך כדי שתוכל לתקן, לבדוק ולהעריך מה קרה. השתמש בו בכל פעם שאתה רוצה ש-Failproof AI Observability יעקוב אחר הסוכנים שלך. -ראו בדיוק מה שסוכני ה-AI שלכם עשו בסביבת הייצור: כל הרצת סוכן, קריאת כלי, בקשת מודל, hook, והתערבות אדם. ה-Python SDK של Failproof AI Observability מתעד את זה הכל מתוך קוד הסוכן שלכם כדי שתוכלו לבצע debug, audit, והערכה של מה שקרה. השתמשו בו בכל פעם שתרצו ש-Failproof AI Observability יעקוב אחר הסוכנים שלכם. +תחת המכסה, ה-SDK כותב אירועים מובנים לקבצי JSONL מקומיים, ודימון הקולט אוסף אותם ושולח אותם לפלטפורמה באופן אוטומטי. אתה לא מנהל את הקבצים האלה בעצמך. -בעומק המערכת, ה-SDK כותב אירועים מובנים לקבצי JSONL מקומיים, וה-collector daemon אוסף אותם ותופר אותם לפלטפורמה באופן אוטומטי. אתם לא מנהלים את הקבצים הללו בעצמכם. - -> **Tip:** חדשים ב-Failproof AI Observability? דף זה הוא הפניה השלמה של אירועי SDK. +> **טיפ:** חדש ב-Failproof AI Observability? דף זה היא ההתייחסות לאירועי ה-SDK המלאה.
@@ -16,21 +15,21 @@ description: "ראו בדיוק מה שסוכני ה-AI שלכם עשו בסבי --- -## Installation +## התקנה -ה-SDK מופץ ללקוחות כחבילת wheel פרטית ולא מ-index ציבורי של חבילות. ה-onboarding שלכם מכסה כיצד להשיג אותה, להתקין אותה, ולהצמיד אותה — דברו עם איש הקשר שלכם ב-Failproof AI אם אתם זקוקים לגישה. +ה-SDK מופץ ללקוחות כקובץ wheel פרטי במקום מאינדקס חבילות ציבורי. ההטמעה שלך מכסה כיצד להשיג אותו, להתקין אותו ולהצמיד אותו — דבר עם אנשי הקשר של Failproof AI שלך אם אתה צריך גישה. -ברגע שהוא מותקן, אשרו שיש לכם אותו: +לאחר התקנתו, אמת שיש לך אותו: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -עדיפות לתת לסוכן קידוד לעשות את כל ההשתלבות? ה-[Python SDK Agent Skill](/he/agenteye/python-sdk-skill) יודע את נתיב ההתקנה, מתכננת את נקודות ההשתלבות, כותבת אותן, ומוודאת שהאירועים מגיעים. +עדיף לתן לסוכן קודינג לעשות את כל ההשתלבות? ה-[Python SDK Agent Skill](/he/agenteye/python-sdk-skill) מכיר את נתיב ההתקנה, מתכננת את נקודות ההשתלבות, כותבת אותן ומאמתת שהאירועים מגיעים. --- -## Quick Start +## התחלה מהירה ```python import agenteye @@ -58,9 +57,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### Instrumenting a real call +### השתלבות בקריאה אמיתית -בפועל אתם עוטפים את קוד הסוכן הקיים שלכם. הקיפו קריאת מודל עם `model_request` לפני ו-`model_response` אחרי, כך ששני האירועים משתרעים על הבקשה הממשית וה-Failproof AI Observability יכול להתאים ביניהם: +בפועל אתה עוטף את קוד הסוכן הקיים שלך. תחום קריאת מודל עם `model_request` לפני ו`model_response` אחרי, כך שני האירועים משתרעים על הבקשה האמיתית וה-Failproof AI Observability יכול להזדווג עם הם: ```python import anthropic @@ -95,11 +94,11 @@ agenteye.event.model_response( ) ``` -עטפו קריאות כלים בדרך זהה עם `tool_use` ו-`tool_result`, תוך שימוש חוזר ב-`tool_call_id` אחד על פני הזוג. +עטוף קריאות כלים באותו אופן עם `tool_use` ו`tool_result`, וודא שימוש באחד `tool_call_id` בכל הזוג. -הנה איך נראים אותם אירועים ברגע שהם מגיעים לדשבורד, מצוידים בצבעים לפי סוג וניתנים לסינון לפי environment, סוכן, ו-session: +הנה איך נראים האירועים האלה ברגע שהם מגיעים לדשבורד, מקודדים בצבע לפי סוג וניתנים לסינון לפי סביבה, סוכן וסדרת: -![The live Events stream, colour-coded by event type and filterable by environment, agent, and session](/agenteye/images/events-stream.png) +![ה-Events stream החי, מקודד בצבע לפי סוג אירוע וניתן לסינון לפי סביבה, סוכן וסדרת](/agenteye/images/events-stream.png) --- @@ -113,67 +112,67 @@ agenteye.configure( ) ``` -קראו פעם אחת לפני כל קריאה `event.*`. בטוח להשמיט; ערכי ברירת מחדל עובדים מחוץ לקופסה. כל הארגומנטים הם keyword-only; העבירו אותם לפי שם כמוצג למעלה. +התקשר פעם אחת לפני כל קריאת `event.*`. בטוח להשמיט; הערכות ברירת המחדל עובדות מהקופסה. כל הטיעונים הם רק מילות מפתח; העבור אותם בשם כפי שמוצג למעלה. כאשר `base_dir` הוא `None` (ברירת המחדל), ה-SDK קורא `$AGENTEYE_HOME` אם הוגדר, -אחרת חוזר ל-`~/.agenteye`. זה תואם את ההחלטה של ה-collector שלו, -כך שמשתנה `AGENTEYE_HOME` יחיד מגדיר את ה-event spool המשותף לשניהם -ל-SDK וגם לאספן. +אחרת חוזר ל`~/.agenteye`. זה תואם את הרזולוציה של הקולט עצמו, +כך שמשתנה סביבה `AGENTEYE_HOME` יחיד מגדיר את ה-spool של אירועים משותפים לשניהם +ה-SDK והקולט. --- -## Environment +## סביבה -תייגו כל אירוע עם environment פיתוח (`production`, `staging`, `qa`, `canary`, וכו'). הגדירו אותו פעם אחת; ה-SDK מצרף אותו לכל אירוע באופן אוטומטי. +תווית כל אירוע עם סביבת הפריסה (`production`, `staging`, `qa`, `canary` וכו'). הגדר אותה פעם אחת; ה-SDK מצרף אותה לכל אירוע באופן אוטומטי. -**Option 1: via `configure()`:** +**אפשרות 1: דרך `configure()`:** ```python agenteye.configure(environment="production") ``` -**Option 2: via environment variable:** +**אפשרות 2: דרך משתנה סביבה:** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**Priority:** `configure(environment=...)` מנצח על משתנה הסביבה. אם לא הוגדר אף אחד, ברירת המחדל היא `"dev"`. +**עדיפות:** `configure(environment=...)` מנצחת על משתנה הסביבה. אם לא הגדרת אף אחד מהם, ברירת המחדל היא `"dev"`. -ערך ה-environment מופיע כמסנן מדרגה ראשונה בדשבורד ומאוחסן בשרת לשאילתות מהירות. +ערך הסביבה מופיע כמסנן מהדרגה הראשונה בדשבורד וניתן לאחסון בשרת לשאילתות מהירות. -> **Warning:** ערכי Environment לא חייבים להכיל פסיק `,` ממשי. מסנני הדשבורד משתמשים בבחירה מרובה מופרדת בפסיקים על החוט (`?environment=prod,staging`), כך שמבחינה שנקראת `prod,blue` תיחלק לשני ערכים. אירועים עם environments המכילים פסיקים נדחים בזמן ingest. +> **אזהרה:** ערכי סביבה חייבים לא להכיל פסיק תחתוני `,`. מסננים הדשבורד משתמשים בבחירה מרובה המופרדת בפסיקים ברשת (`?environment=prod,staging`), כך שסביבה בשם `prod,blue` היתה מחולקת לשני ערכים. אירועים עם סביבות המכילות פסיקים נדחים בזמן הצגת. --- -## Data and privacy +## נתונים וסודיות -ה-SDK מתעד רק את השדות שאתם מעבירים במפורש. Prompts, messages, tool inputs and outputs, ותוכן מודל נתפסים אך ורק משום שהעברתם אותם לקריאת `event.*`. שום דבר לא נקרא מתהליך שלכם או נתפס באופן סתוי. כל שדה שאתם משאירים לא מוגדר הוא מושמט מהאירוע לגמרי; הוא לא כתוב לדיסק. +ה-SDK מתעד רק את השדות שאתה מעביר במפורש. הנושאים, ההודעות, תשומות וביצוע הכלים, ותוכן המודל נלכדים אך ורק מפני שאתה מעביר אותם לקריאת `event.*`. שום דבר לא נקרא מתהליך שלך או נלכד במובלע. כל שדה שאתה משאיר לא מוגדר מושמט מהאירוע לחלוטין; הוא לא כתוב לדיסק. -זה הופך את ה-redaction לבחירה שלכם ולאחריות שלכם. אם prompt או tool payload מכיל PII או secrets שלא תרצו לאחסן, הסירו או מוסכו זאת לפני שהעברתם אותה לשיטת האירוע. +זה הופך את ההחלפה לבחירה שלך ולאחריות שלך. אם הנושא או עומס הכלים מכיל PII או סודות שלא היית רוצה לאחסן, הסר או הכסה אותו לפני שאתה מעביר אותו לשיטת האירוע. --- -## Event Reference +## התייחסות לאירועים -רוב האירועים מגיעים בזוגות start/end שחולקים מזהה מתאם: `tool_use` ו-`tool_result` חולקים `tool_call_id`, `hook_triggered` ו-`hook_completed` חולקים `hook_id`, ו-`human_wait` ו-`human_input` חולקים `input_id`. פלטו את אירוע ה-start, בצעו את העבודה, ואז פלטו את אירוע ה-end עם אותו מזהה. Failproof AI Observability תתאים את הזוג ותחשב `duration_ms` עבורכם, אז אתם לעולם לא תעברו `duration_ms` בעצמכם. +רוב האירועים באים בזוגות התחלה/סיום שחולקים מזהה מתאם: `tool_use` ו`tool_result` חולקים `tool_call_id`, `hook_triggered` ו`hook_completed` חולקים `hook_id`, ו`human_wait` ו`human_input` חולקים `input_id`. פלוט את אירוע ההתחלה, בצע את העבודה, ואז פלוט את אירוע הסיום עם אותו מזהה. Failproof AI Observability תואם את הזוג ומחשב את `duration_ms` עבורך, כך שלעולם לא תעביר את `duration_ms` בעצמך. -![A session's git-style execution graph beside its event timeline, reconstructed from the paired events, with the tool/model/hook breakdown panel](/agenteye/images/session-detail.png) +![גרף הביצוע בסגנון git של סדרה ליד ציר הזמן של האירועים שלה, שנבנה מחדש מהאירועים המזווגים, עם לוח התמוספיה/מודל/ווק](/agenteye/images/session-detail.png) -כל שיטות האירוע דורשות שני שדות אלה: +כל שיטות האירוע דורשות את שני השדות הבאים: -| Field | Type | Description | +| שדה | סוג | תיאור | |---|---|---| | `session_id` | `str` | מזהה את הרצת הסוכן ברמה העליונה | -| `agent_id` | `str` | מזהה איזה סוכן בתוך ה-session פלט את האירוע | +| `agent_id` | `str` | מזהה איזה סוכן בתוך הסדרה פלט את האירוע | -כל השיטות גם מקבלות `**kwargs` שרירותיים עבור metadata מותאם (ראו [Custom Fields](#custom-fields)). +כל השיטות גם קבלות `**kwargs` שרירותי לנתונים מטא מותאם אישית (ראה [שדות מותאם אישית](#custom-fields)). --- ### `event.agent_start()` -פלט כאשר סוכן מתחיל לעבוד. +מתפוצץ כאשר סוכן מתחיל עבודה. ```python agenteye.event.agent_start( @@ -188,7 +187,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -פלט כאשר סוכן מסיים לעבוד. +מתפוצץ כאשר סוכן סיים את העבודה. ```python agenteye.event.agent_end( @@ -203,7 +202,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -פלט כאשר סוכן משתמש בכלי. תאימו עם `tool_result`; ה-SDK מחשב באופן אוטומטי `duration_ms`. +מתפוצץ כאשר סוכן משדל כלי. זווג עם `tool_result`; ה-SDK מחשב באופן אוטומטי את `duration_ms`. ```python agenteye.event.tool_use( @@ -219,7 +218,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -פלט כאשר כלי חוזר. מתאים עם `tool_use` דרך `tool_call_id`. +מתפוצץ כאשר כלי חוזר. מתאם עם `tool_use` דרך `tool_call_id`. ```python agenteye.event.tool_result( @@ -237,7 +236,7 @@ agenteye.event.tool_result( ### `event.model_request()` -פלט רגע לפני שליחת prompt ל-LLM. +מתפוצץ ממש לפני שליחת הנושא ל-LLM. ```python agenteye.event.model_request( @@ -254,13 +253,13 @@ agenteye.event.model_request( ) ``` -ערכי `messages` מקבלים ממשי `content` של מחרוזת או Anthropic-style list-of-blocks `content`. פרמטרים sampling (`temperature`, `max_tokens`, וכו') יכולים להיות מועברים כ-kwargs נוספים. +ערכי `messages` מקבלים או `content` של מחרוזת רגילה או Anthropic בסגנון רשימה-בלוקים `content`. פרמטרים של דגימה (`temperature`, `max_tokens` וכו') יכולים להיות מועברים כ-kwargs נוספים. --- ### `event.model_response()` -פלט כאשר ה-LLM מחזיר תגובה. +מתפוצץ כאשר ה-LLM חוזר בתגובה. ```python agenteye.event.model_response( @@ -277,13 +276,13 @@ agenteye.event.model_response( ) ``` -`content` מקבל או מחרוזת פשוטה (ספקים גנריים) או רשימה של Anthropic-style content blocks. קריאות כלים חיות בתוך `content` כ-`{"type": "tool_use", ...}` blocks, ללא שדה `tool_calls` נפרד. +`content` מקבל או מחרוזת רגילה (ספקים גנריים) או רשימה של בלוקי תוכן בסגנון Anthropic. קריאות כלים חיות בתוך `content` כבלוקים של `{"type": "tool_use", ...}`, ללא שדה נפרד של `tool_calls`. --- ### `event.hook_triggered()` -פלט כאשר hook יורה. תאימו עם `hook_completed`; ה-SDK מחשב באופן אוטומטי `duration_ms`. +מתפוצץ כאשר ווק דולק. זווג עם `hook_completed`; ה-SDK מחשב באופן אוטומטי את `duration_ms`. ```python agenteye.event.hook_triggered( @@ -300,7 +299,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -פלט כאשר hook מסיים. מתאים עם `hook_triggered` דרך `hook_id`. +מתפוצץ כאשר ווק מסיים. מתאם עם `hook_triggered` דרך `hook_id`. ```python agenteye.event.hook_completed( @@ -319,7 +318,7 @@ agenteye.event.hook_completed( ### `event.error()` -פלט כאשר שגיאה לא מטופלת מתרחשת. +מתפוצץ כאשר שגיאה לא טופלת מתרחשת. ```python agenteye.event.error( @@ -333,13 +332,13 @@ agenteye.event.error( --- -## Human-in-the-Loop Events +## אירועי אדם-בתוך-לולאה -אירועי human-in-the-loop נותנים לכם פיקוח על הרגעים שבהם אדם צעד לתוך ההוצאה של הסוכן (מחכה לאישור, הנתינת input, השהיה, או עצירת הסוכן). הם מאפשרים לכם למדוד כמה זמן אנשים לוקחים להגיב (ה-SDK מחשב באופן אוטומטי `duration_ms` על אירועים מזווגים), audit מי השהה או הפריע לסוכן, ובנו זרימות אישור וניגוח שמופיעות בדשבורד. +אירועי אדם-בתוך-לולאה נותנים לך פיקוח על הרגעים בהם אדם צועד לביצוע הסוכן (מחכה לאישור, מספק קלט, משהה או עוצר את הסוכן). הם מאפשרים לך למדוד כמה זמן אנשים לוקחים להגיב (ה-SDK מחשב באופן אוטומטי את `duration_ms` על האירועים המזווגים), בדוק את מי השהה או הפסיק סוכן, ובנה זרימות אישור וניהול שמשטחות בדשבורד. ### `event.human_wait()` -פלט כאשר הסוכן עוצר את ההוצאה כדי להמתין לאדם שיספק input. תאימו עם `human_input`; ה-SDK מחשב באופן אוטומטי `duration_ms` (כמה זמן האדם לקח להגיב). +מתפוצץ כאשר הסוכן משהה את הביצוע בהמתנה לאדם לספק קלט. זווג עם `human_input`; ה-SDK מחשב באופן אוטומטי את `duration_ms` (כמה זמן האדם לקח להגיב). ```python agenteye.event.human_wait( @@ -354,7 +353,7 @@ agenteye.event.human_wait( ### `event.human_input()` -פלט כאשר אדם מספק input והסוכן חוזר להמשך. מתאים עם `human_wait` דרך `input_id`. `duration_ms` מחושב באופן אוטומטי ולא חייב להיות מועבר על ידי הקורא. +מתפוצץ כאשר אדם מספק קלט והסוכן מתחדש. מתאם עם `human_wait` דרך `input_id`. `duration_ms` מחושב באופן אוטומטי ולא יכול להיות מעביר על ידי הקורא. ```python agenteye.event.human_input( @@ -368,7 +367,7 @@ agenteye.event.human_input( ### `event.human_pause()` -פלט כאשר אדם באופן פעיל משהה את הסוכן (למשל דרך בקרת דשבורד). הסוכן הוא מושעה אך לא מוסדר. +מתפוצץ כאשר אדם משהה באופן פעיל את הסוכן (למשל דרך בקרה בדשבורד). הסוכן מושעה אך לא מסתיים. ```python agenteye.event.human_pause( @@ -381,7 +380,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -פלט כאשר אדם באופן פעיל עוצר את הסוכן בהוצאה ביניים. בניגוד ל-`human_pause`, עבודת הסוכן מסיימת ולא משהה. +מתפוצץ כאשר אדם עוצר באופן פעיל את הסוכן באמצע הביצוע. בניגוד ל`human_pause`, עבודת הסוכן מסתיימת במקום להיות משעה. ```python agenteye.event.human_interrupt( @@ -395,9 +394,9 @@ agenteye.event.human_interrupt( --- -## Custom Fields +## שדות מותאם אישית -כל keyword arguments נוספים מוסתרים לאירוע אחרי השדות הסטנדרטיים: +כל טיעונים מילת מפתח נוספים מצורפים לאירוע אחרי השדות הסטנדרטיים: ```python agenteye.event.tool_use( @@ -410,25 +409,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type`, ו-`environment` שמורים והעלאה `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) אם מועברים כ-custom fields. `session_id` ו-`agent_id` הם required parameters על כל שיטת אירוע ולא יכולים להיות מסופקים פעם שנייה; Python מעלה `TypeError` אם תעשו זאת. הגדירו את ה-environment עם `configure(environment=...)` (או משתנה `AGENTEYE_ENVIRONMENT`) במקום זאת. +`timestamp`, `type` ו`environment` שמורים ויגרום `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) אם מועברים כשדות מותאם אישית. `session_id` ו`agent_id` הם פרמטרים נדרשים בכל שיטת אירוע ולא ניתן לספק אותם פעם שנייה; Python מעלה `TypeError` אם אתה עושה זאת. הגדר את הסביבה עם `configure(environment=...)` (או המשתנה `AGENTEYE_ENVIRONMENT`) במקום. + +שמור משא כמו JSON מובנה כאשר אתה רוצה לשאול את השדות שלהם. ערכים שה-JSON לא תומך במקום בהם — כגון datetimes, UUIDs, decimals, sets, bytes, או אובייקטי מודל — מומרים למחרוזות כדי להמשיך בהקלטה בבטחה. --- -## How Events Are Written +## כיצד אירועים כתובים -אירועים מחולצים בתהליך ומשטפים לדיסק כל `flush_interval` שניות (ברירת מחדל 500 ms). כל flush כותב קובץ JSONL אחד: +אירועים מאוחסנים בתהליך ודחפו לדיסק כל שניות `flush_interval` (ברירת מחדל 500 ms). כל דחיפה כותבת קובץ JSONL אחד: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -ה-collector צופה בתיקייה זו ועולה קבצים באופן אוטומטי. אתם לא צריכים לנהל את הקבצים האלה ישירות. +הקולט צופה בתיקייה זו וטוען קבצים באופן אוטומטי. אתה לא צריך לנהל את הקבצים האלה ישירות. -כל קובץ נכתב בצורה אטומית: ה-SDK כותב לקובץ זמני ואז משנה את שמו למקום, כך שה-collector לא רואה קובץ חצי כתוב. flush סופי גם פועל כאשר התהליך שלכם יוצא, אז אירועים מחולצים במרווח האחרון לא אבדים. אם ה-collector הוא במצב אפילו, אירועים פשוט נצברים כקבצים על הדיסק ותופרים ברגע שחוזר. +כל קובץ כתוב בצורה אטומית: ה-SDK כותב לקובץ זמני ואחר כך שינה שם אותו למקום, כך שהקולט לעולם לא רואה קובץ שחצי כתוב. דחיפה סופית גם רצה כאשר התהליך שלך יוצא, כך שאירועים מאוחסנים במרווח האחרון לא אבדים. אם הקולט במצב לא מקוון, אירועים פשוט מצטברים כקבצים בדיסק וחומר ברגע שהוא חוזר. --- -## Next steps +## שלבים הבאים -- [Event stream](/he/agenteye/event-stream): צפו באירועים אלה מגיעים בחי, צבוע קודם וניתנים לסינון לפי environment, סוכן, ו-session. -- [Sessions](/he/agenteye/sessions): ראו כיצד אירועים מזווגים בנו מחדש כל הרצת סוכן כגרף הוצאה וציר זמן. \ No newline at end of file +- [Event stream](/he/agenteye/event-stream): צפה באירועים אלה להגיע בשידור חי, מקודדים בצבע וניתנים לסינון לפי סביבה, סוכן וסדרת. +- [Sessions](/he/agenteye/sessions): ראה כיצד האירועים המזווגים בנו מחדש כל הרצת סוכן כגרף ביצוע וציר זמן. \ No newline at end of file diff --git a/docs/hi/agenteye/python-sdk.mdx b/docs/hi/agenteye/python-sdk.mdx index 2d244383..9b5ac3ac 100644 --- a/docs/hi/agenteye/python-sdk.mdx +++ b/docs/hi/agenteye/python-sdk.mdx @@ -1,33 +1,32 @@ --- ---- title: "Python SDK" description: "देखें कि आपके AI एजेंट्स प्रोडक्शन में क्या करते हैं: हर एजेंट रन, टूल कॉल, मॉडल रिक्वेस्ट, हुक, और मानव हस्तक्षेप।" --- -देखें कि आपके AI एजेंट्स प्रोडक्शन में क्या करते हैं: हर एजेंट रन, टूल कॉल, मॉडल रिक्वेस्ट, हुक, और मानव हस्तक्षेप। Failproof AI Observability Python SDK आपके एजेंट कोड के अंदर से उस ट्रेल को रिकॉर्ड करता है ताकि आप डीबग, ऑडिट, और मूल्यांकन कर सकें कि क्या हुआ। जब भी आप चाहते हैं कि Failproof AI Observability आपके एजेंट्स को observe करे, इसका उपयोग करें। +देखें कि आपके AI एजेंट्स प्रोडक्शन में क्या करते हैं: हर एजेंट रन, टूल कॉल, मॉडल रिक्वेस्ट, हुक, और मानव हस्तक्षेप। Failproof AI Observability Python SDK आपके एजेंट कोड के अंदर से उस ट्रेल को रिकॉर्ड करता है ताकि आप डीबग, ऑडिट, और मूल्यांकन कर सकें कि क्या हुआ। जब भी आप चाहते हैं कि Failproof AI Observability आपके एजेंट्स को देखे, इसका उपयोग करें। -बैकग्राउंड में, SDK संरचित इवेंट्स को स्थानीय JSONL फाइलों में लिखता है, और collector daemon स्वचालित रूप से उन्हें उठाता है और प्लेटफॉर्म को भेजता है। आपको इन फाइलों को स्वयं प्रबंधित करने की आवश्यकता नहीं है। +हुड के तहत, SDK स्ट्रक्चर्ड इवेंट्स को लोकल JSONL फाइलों में लिखता है, और कलेक्टर डेमन उन्हें स्वचालित रूप से प्लेटफॉर्म पर भेजता है। आप इन फाइलों को स्वयं प्रबंधित नहीं करते हैं। -> **टिप:** Failproof AI Observability में नए हैं? यह पृष्ठ पूर्ण SDK इवेंट संदर्भ है। +> **Tip:** Failproof AI Observability में नए हैं? यह पृष्ठ संपूर्ण SDK इवेंट संदर्भ है।
- +
--- ## इंस्टॉलेशन -SDK को ग्राहकों के लिए एक निजी व्हील के रूप में वितरित किया जाता है, न कि सार्वजनिक पैकेज इंडेक्स से। आपकी ऑनबोर्डिंग में इसे कैसे प्राप्त करें, इंस्टॉल करें, और पिन करें यह शामिल है — यदि आपको एक्सेस की आवश्यकता है तो अपने Failproof AI संपर्क से बात करें। +SDK को ग्राहकों को एक निजी व्हील के रूप में वितरित किया जाता है न कि एक सार्वजनिक पैकेज इंडेक्स से। आपके ऑनबोर्डिंग में बताया गया है कि इसे कैसे प्राप्त करें, इंस्टॉल करें, और पिन करें — यदि आपको एक्सेस की आवश्यकता है तो अपने Failproof AI संपर्क से बात करें। -एक बार इंस्टॉल हो जाने के बाद, पुष्टि करें कि आपके पास यह है: +एक बार यह इंस्टॉल हो जाने पर, पुष्टि करें कि आपके पास यह है: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -क्या आप एक कोडिंग एजेंट को पूरा इंटीग्रेशन करने देना पसंद करते हैं? [Python SDK Agent Skill](/hi/agenteye/python-sdk-skill) इंस्टॉल पाथ जानता है, इंस्ट्रूमेंटेशन पॉइंट्स की योजना बनाता है, उन्हें लिखता है, और इवेंट्स को वेरिफाई करता है। +क्या आप एक कोडिंग एजेंट को संपूर्ण एकीकरण करने देना पसंद करते हैं? [Python SDK Agent Skill](/hi/agenteye/python-sdk-skill) इंस्टॉल पाथ को जानता है, इंस्ट्रूमेंटेशन पॉइंट्स की योजना बनाता है, उन्हें लिखता है, और इवेंट्स के आने की पुष्टि करता है। --- @@ -41,7 +40,7 @@ agenteye.configure(environment="production") agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query") agenteye.event.tool_use( - session_id="run-001", + session_id="run-002", agent_id="planner", tool_name="web_search", tool_call_id="toolu_01", @@ -59,9 +58,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### वास्तविक कॉल को इंस्ट्रूमेंट करना +### एक वास्तविक कॉल को इंस्ट्रूमेंट करना -व्यवहार में, आप अपने मौजूदा एजेंट कोड को लपेटते हैं। `model_request` से पहले और `model_response` के बाद एक मॉडल कॉल को ब्रैकेट करें, ताकि दोनों इवेंट्स वास्तविक रिक्वेस्ट को span करें और Failproof AI Observability उन्हें जोड़ी सके: +व्यावहारिक रूप से आप अपने मौजूदा एजेंट कोड को लपेटते हैं। एक मॉडल कॉल को `model_request` से पहले और `model_response` के बाद ब्रैकेट करें, ताकि दोनों इवेंट्स वास्तविक रिक्वेस्ट को स्पैन करें और Failproof AI Observability उन्हें जोड़ी सके: ```python import anthropic @@ -96,11 +95,11 @@ agenteye.event.model_response( ) ``` -टूल कॉल्स को `tool_use` और `tool_result` के साथ एक ही तरीके से लपेटें, जोड़ी के पार एक ही `tool_call_id` का पुन: उपयोग करें। +टूल कॉल्स को `tool_use` और `tool_result` से समान तरीके से लपेटें, जोड़ी के बीच एक ही `tool_call_id` का पुनः उपयोग करें। -यहाँ बताया गया है कि एक बार ये इवेंट्स डैशबोर्ड तक पहुँचने के बाद कैसे दिखते हैं, प्रकार के अनुसार रंग-कोडित और पर्यावरण, एजेंट, और सेशन द्वारा फ़िल्टर किए जा सकते हैं: +एक बार जब वे इवेंट्स डैशबोर्ड पर पहुंचते हैं तो वे कैसे दिखते हैं, टाइप के अनुसार रंग-कोडित और पर्यावरण, एजेंट, और सेशन द्वारा फ़िल्टर करने योग्य: -![लाइव इवेंट्स स्ट्रीम, इवेंट प्रकार के अनुसार रंग-कोडित और पर्यावरण, एजेंट, और सेशन द्वारा फ़िल्टर किए जा सकते हैं](/agenteye/images/events-stream.png) +![लाइव इवेंट स्ट्रीम, इवेंट टाइप के अनुसार रंग-कोडित और पर्यावरण, एजेंट, और सेशन द्वारा फ़िल्टर करने योग्य](/agenteye/images/events-stream.png) --- @@ -108,23 +107,23 @@ agenteye.event.model_response( ```python agenteye.configure( - base_dir=None, # Path | str | None. डिफ़ॉल्ट: $AGENTEYE_HOME या ~/.agenteye - flush_interval=0.5, # float, flush cycles के बीच सेकंड - environment=None, # str | None. डिप्लॉयमेंट पर्यावरण लेबल + base_dir=None, # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye + flush_interval=0.5, # float, seconds between flush cycles + environment=None, # str | None. Deployment environment label ) ``` -किसी भी `event.*` कॉल से पहले एक बार कॉल करें। छोड़ना सुरक्षित है; डिफ़ॉल्ट्स तुरंत काम करते हैं। सभी arguments केवल keyword हैं; उन्हें ऊपर दिखाए अनुसार नाम से pass करें। +किसी भी `event.*` कॉल से पहले एक बार कॉल करें। छोड़ना सुरक्षित है; डिफॉल्ट्स बॉक्स से बाहर काम करते हैं। सभी आर्गुमेंट्स केवल कीवर्ड हैं; उन्हें ऊपर दिखाए गए अनुसार नाम से पास करें। -जब `base_dir` `None` है (डिफ़ॉल्ट), SDK `$AGENTEYE_HOME` को पढ़ता है यदि सेट है, -अन्यथा `~/.agenteye` पर वापस आता है। यह collector के स्वयं के संकल्प से मेल खाता है, -इसलिए एक एकल `AGENTEYE_HOME` env var SDK और collector दोनों के लिए साझा इवेंट spool को कॉन्फ़िगर करता है। +जब `base_dir` `None` है (डिफॉल्ट), SDK `$AGENTEYE_HOME` को पढ़ता है यदि सेट है, +अन्यथा `~/.agenteye` पर वापस जाता है। यह कलेक्टर के अपने रेजोल्यूशन से मेल खाता है, +इसलिए एक एकल `AGENTEYE_HOME` env var SDK और कलेक्टर दोनों के लिए साझी इवेंट स्पूल को कॉन्फ़िगर करता है। --- ## पर्यावरण -हर इवेंट को एक डिप्लॉयमेंट पर्यावरण (`production`, `staging`, `qa`, `canary`, आदि) से लेबल करें। इसे एक बार सेट करें; SDK स्वचालित रूप से इसे हर इवेंट को attach करता है। +हर इवेंट को एक डिप्लॉयमेंट पर्यावरण (`production`, `staging`, `qa`, `canary`, आदि) के साथ लेबल करें। इसे एक बार सेट करें; SDK इसे हर इवेंट से स्वचालित रूप से जोड़ता है। **विकल्प 1: `configure()` के माध्यम से:** @@ -132,48 +131,48 @@ agenteye.configure( agenteye.configure(environment="production") ``` -**विकल्प 2: environment variable के माध्यम से:** +**विकल्प 2: पर्यावरण चर के माध्यम से:** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**प्राथमिकता:** `configure(environment=...)` environment variable पर जीतता है। यदि कोई भी सेट नहीं है, तो डिफ़ॉल्ट `"dev"` है। +**प्राथमिकता:** `configure(environment=...)` पर्यावरण चर को हराता है। यदि कोई भी सेट नहीं है, तो डिफॉल्ट `"dev"` है। -पर्यावरण मान डैशबोर्ड में एक first-class फ़िल्टर के रूप में दिखाई देता है और तेज़ क्वेरी के लिए सर्वर पर संग्रहीत होता है। +पर्यावरण मान डैशबोर्ड में फर्स्ट-क्लास फ़िल्टर के रूप में दिखाई देता है और तेजी से क्वेरी के लिए सर्वर पर संग्रहीत है। -> **चेतावनी:** पर्यावरण मानों में literal `,` comma नहीं होना चाहिए। डैशबोर्ड फ़िल्टर्स वायर पर comma-separated multi-select का उपयोग करते हैं (`?environment=prod,staging`), इसलिए `prod,blue` नामित एक पर्यावरण को दो मानों में विभाजित किया जाएगा। Comma-containing environments वाले इवेंट्स को ingest समय पर अस्वीकार कर दिया जाता है। +> **Warning:** पर्यावरण मानों में शाब्दिक `,` कोमा नहीं होना चाहिए। डैशबोर्ड फ़िल्टर्स वायर पर कॉमा-सेपरेटेड मल्टी-सिलेक्ट का उपयोग करते हैं (`?environment=prod,staging`), इसलिए `prod,blue` नाम का एक पर्यावरण दो मानों में विभाजित हो जाएगा। कोमा-युक्त पर्यावरण वाले इवेंट्स इनजेस्ट समय पर अस्वीकार किए जाते हैं। --- ## डेटा और गोपनीयता -SDK केवल वे फील्ड्स रिकॉर्ड करता है जो आप स्पष्ट रूप से pass करते हैं। Prompts, messages, tool inputs और outputs, और model content को केवल capture किया जाता है क्योंकि आप उन्हें `event.*` कॉल में hand करते हैं। कुछ भी आपके process से नहीं पढ़ा जाता है या implicitly capture नहीं होता है। कोई भी फील्ड जो आप unset छोड़ते हैं वह पूरी तरह से इवेंट से छोड़ दिया जाता है; इसे डिस्क में नहीं लिखा जाता है। +SDK केवल उन फील्ड्स को रिकॉर्ड करता है जो आप स्पष्ट रूप से पास करते हैं। प्रॉम्प्ट्स, संदेश, टूल इनपुट्स और आउटपुट्स, और मॉडल कंटेंट केवल इसलिए कैप्चर किए जाते हैं क्योंकि आप उन्हें `event.*` कॉल में हाथ देते हैं। आपकी प्रक्रिया से कुछ भी नहीं पढ़ी जाती है या निहित रूप से कैप्चर नहीं किया जाता है। कोई भी फील्ड जिसे आप सेट नहीं करते हैं वह पूरी तरह से इवेंट से छोड़ दी जाती है; इसे डिस्क पर नहीं लिखा जाता है। -यह redaction को आपकी पसंद और आपकी जिम्मेदारी बनाता है। यदि एक prompt या tool payload में PII या secrets हैं जो आप store नहीं करना चाहते, उन्हें event method को pass करने से पहले strip या mask करें। +यह रिडैक्शन को आपकी पसंद और आपकी जिम्मेदारी बनाता है। यदि कोई प्रॉम्प्ट या टूल पेलोड में PII या सीक्रेट्स हैं जिन्हें आप स्टोर नहीं करना चाहते हैं, तो इसे इवेंट मेथड में पास करने से पहले स्ट्रिप या मास्क करें। --- ## इवेंट संदर्भ -अधिकांश इवेंट्स start/end pairs में आते हैं जो एक correlation ID साझा करते हैं: `tool_use` और `tool_result` एक `tool_call_id` साझा करते हैं, `hook_triggered` और `hook_completed` एक `hook_id` साझा करते हैं, और `human_wait` और `human_input` एक `input_id` साझा करते हैं। Start event emit करें, काम करें, फिर same ID के साथ end event emit करें। Failproof AI Observability जोड़ी को match करता है और `duration_ms` को आपके लिए compute करता है, इसलिए आप स्वयं `duration_ms` कभी pass नहीं करते हैं। +अधिकांश इवेंट्स स्टार्ट/एंड पेयर्स में आते हैं जो एक कोरिलेशन ID शेयर करते हैं: `tool_use` और `tool_result` एक `tool_call_id` शेयर करते हैं, `hook_triggered` और `hook_completed` एक `hook_id` शेयर करते हैं, और `human_wait` और `human_input` एक `input_id` शेयर करते हैं। स्टार्ट इवेंट एमिट करें, काम करें, फिर एंड इवेंट को समान ID के साथ एमिट करें। Failproof AI Observability पेयर को मेल करता है और आपके लिए `duration_ms` की गणना करता है, इसलिए आप कभी `duration_ms` को स्वयं पास नहीं करते हैं। -![एक सेशन का git-style execution graph उसकी event timeline के साथ, paired events से reconstructed, tool/model/hook breakdown panel के साथ](/agenteye/images/session-detail.png) +![एक सेशन का git-स्टाइल एक्सीक्यूशन ग्राफ इसकी इवेंट टाइमलाइन के बगल में, पेयर्ड इवेंट्स से पुनर्निर्मित, टूल/मॉडल/हुक ब्रेकडाउन पैनल के साथ](/agenteye/images/session-detail.png) -सभी event methods को ये दो फील्ड्स की आवश्यकता है: +सभी इवेंट मेथड्स को ये दो फील्ड्स की आवश्यकता है: -| फील्ड | प्रकार | विवरण | +| फील्ड | टाइप | विवरण | |---|---|---| -| `session_id` | `str` | top-level agent run को पहचानता है | -| `agent_id` | `str` | पहचानता है कि सेशन के अंदर कौन सा एजेंट इवेंट emit किया है | +| `session_id` | `str` | टॉप-लेवल एजेंट रन को पहचानता है | +| `agent_id` | `str` | पहचानता है कि सेशन के भीतर कौन सा एजेंट इवेंट एमिट करता है | -सभी methods arbitrary `**kwargs` को custom metadata के लिए भी स्वीकार करते हैं ([Custom Fields](#custom-fields) देखें)। +सभी मेथड्स कस्टम मेटाडेटा के लिए मनमाने `**kwargs` भी स्वीकार करते हैं ([कस्टम फील्ड्स](#custom-fields) देखें)। --- ### `event.agent_start()` -Emit होता है जब एक एजेंट काम शुरू करता है। +जब कोई एजेंट काम शुरू करता है तो एमिट किया जाता है। ```python agenteye.event.agent_start( @@ -188,7 +187,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Emit होता है जब एक एजेंट काम पूरा करता है। +जब कोई एजेंट काम समाप्त करता है तो एमिट किया जाता है। ```python agenteye.event.agent_end( @@ -203,7 +202,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -Emit होता है जब एक एजेंट एक टूल को invoke करता है। `tool_result` के साथ pair करें; SDK auto-computes `duration_ms`। +जब कोई एजेंट टूल को आमंत्रित करता है तो एमिट किया जाता है। `tool_result` के साथ पेयर करें; SDK स्वचालित रूप से `duration_ms` की गणना करता है। ```python agenteye.event.tool_use( @@ -219,17 +218,17 @@ agenteye.event.tool_use( ### `event.tool_result()` -Emit होता है जब एक टूल return करता है। `tool_call_id` के माध्यम से `tool_use` से correlate करता है। +जब कोई टूल रिटर्न करता है तो एमिट किया जाता है। `tool_call_id` के माध्यम से `tool_use` से संबंधित। ```python agenteye.event.tool_result( session_id="run-001", agent_id="planner", tool_name="web_search", - tool_call_id="toolu_01", # prior tool_use से match होना चाहिए + tool_call_id="toolu_01", # prior tool_use से मेल खाना चाहिए output={"results": ["..."]}, # Any | None error=None, # str | None - यदि टूल ने raise किया तो सेट करें - # duration_ms automatically compute होता है - इसे pass न करें + # duration_ms स्वचालित रूप से गणना की जाती है - इसे पास न करें ) ``` @@ -237,36 +236,36 @@ agenteye.event.tool_result( ### `event.model_request()` -Emit होता है LLM को prompt भेजने से ठीक पहले। +LLM को प्रॉम्प्ट भेजने से ठीक पहले एमिट किया जाता है। ```python agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - कोई भी provider/model string; validate नहीं किया जाता + model="claude-sonnet-4-6", # str | None - कोई भी प्रोवाइडर/मॉडल स्ट्रिंग; सत्यापित नहीं messages=[ # list[dict] | None - conversation turns {"role": "user", "content": "..."}, ], system="You are helpful.", # Any | None - str या content blocks की list - tools=[ # list[dict] | None - tool schemas जो मॉडल को offered हैं + tools=[ # list[dict] | None - मॉडल को दिए गए tool schemas {"name": "search", "input_schema": {"type": "object"}}, ], ) ``` -`messages` entries plain string `content` या Anthropic-style list-of-blocks `content` को स्वीकार करते हैं। Sampling params (`temperature`, `max_tokens`, आदि) को extra kwargs के रूप में pass किया जा सकता है। +`messages` एंट्रीज़ या तो सादा स्ट्रिंग `content` या Anthropic-स्टाइल list-of-blocks `content` स्वीकार करते हैं। सैंपलिंग पैरामीटर्स (`temperature`, `max_tokens`, आदि) को अतिरिक्त kwargs के रूप में पास किया जा सकता है। --- ### `event.model_response()` -Emit होता है जब LLM एक response return करता है। +जब LLM एक response रिटर्न करता है तो एमिट किया जाता है। ```python agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - कोई भी provider/model string; validate नहीं किया जाता + model="claude-sonnet-4-6", # str | None - कोई भी प्रोवाइडर/मॉडल स्ट्रिंग; सत्यापित नहीं stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None @@ -277,13 +276,13 @@ agenteye.event.model_response( ) ``` -`content` plain string (generic providers) या Anthropic-style content blocks की list को स्वीकार करता है। Tool calls `content` के अंदर `{"type": "tool_use", ...}` blocks के रूप में रहते हैं, कोई अलग `tool_calls` फील्ड के साथ नहीं। +`content` या तो सादा स्ट्रिंग (generic providers) या Anthropic-स्टाइल content blocks की एक list स्वीकार करता है। टूल कॉल्स `content` के अंदर `{"type": "tool_use", ...}` ब्लॉक्स के रूप में रहते हैं, अलग `tool_calls` फील्ड के साथ नहीं। --- ### `event.hook_triggered()` -Emit होता है जब एक hook fires। `hook_completed` के साथ pair करें; SDK auto-computes `duration_ms`। +जब कोई हुक फायर होता है तो एमिट किया जाता है। `hook_completed` के साथ पेयर करें; SDK स्वचालित रूप से `duration_ms` की गणना करता है। ```python agenteye.event.hook_triggered( @@ -300,18 +299,18 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Emit होता है जब एक hook समाप्त होता है। `hook_id` के माध्यम से `hook_triggered` से correlate करता है। +जब कोई हुक समाप्त होता है तो एमिट किया जाता है। `hook_id` के माध्यम से `hook_triggered` से संबंधित। ```python agenteye.event.hook_completed( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", - hook_id="hook-abc", # prior hook_triggered से match होना चाहिए + hook_id="hook-abc", # prior hook_triggered से मेल खाना चाहिए outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # duration_ms automatically compute होता है - इसे pass न करें + # duration_ms स्वचालित रूप से गणना की जाती है - इसे पास न करें ) ``` @@ -319,7 +318,7 @@ agenteye.event.hook_completed( ### `event.error()` -Emit होता है जब एक unhandled error होता है। +जब कोई अनहैंडल्ड error होता है तो एमिट किया जाता है। ```python agenteye.event.error( @@ -333,13 +332,13 @@ agenteye.event.error( --- -## मानव-लूप में इवेंट्स +## मानव-इन-द-लूप इवेंट्स -Human-in-the-loop इवेंट्स आपको उन क्षणों पर निरीक्षण देते हैं जहाँ एक व्यक्ति एजेंट के execution में step करता है (approval के लिए प्रतीक्षा कर रहे हैं, input provide कर रहे हैं, pause कर रहे हैं, या एजेंट को stop कर रहे हैं)। वे आपको यह मापने देते हैं कि मानव को respond करने में कितना समय लगता है (SDK paired events पर `duration_ms` auto-computes करता है), audit करते हैं कि किसने एजेंट को pause या interrupt किया है, और approval और oversight workflows build करते हैं जो डैशबोर्ड में surface होते हैं। +मानव-इन-द-लूप इवेंट्स आपको उन क्षणों पर नज़र देते हैं जहाँ कोई व्यक्ति एजेंट के एक्सीक्यूशन में कदम रखता है (अनुमोदन की प्रतीक्षा करना, इनपुट प्रदान करना, रोकना, या एजेंट को रोकना)। वे आपको यह मापने देते हैं कि मानव को प्रतिक्रिया देने में कितना समय लगता है (SDK स्वचालित रूप से पेयर्ड इवेंट्स पर `duration_ms` की गणना करता है), ऑडिट करते हैं कि किसने एजेंट को रोका या बाधित किया, और अनुमोदन और निरीक्षण वर्कफ्लो बनाते हैं जो डैशबोर्ड में सतह पर आते हैं। ### `event.human_wait()` -Emit होता है जब एजेंट execution को pause करता है एक मानव के लिए input provide करने के लिए प्रतीक्षा करने के लिए। `human_input` के साथ pair करें; SDK auto-computes `duration_ms` (मानव को respond करने में कितना समय लगा)। +जब एजेंट एक्सीक्यूशन को एक मानव के लिए इनपुट प्रदान करने की प्रतीक्षा करने के लिए रोकता है तो एमिट किया जाता है। `human_input` के साथ पेयर करें; SDK स्वचालित रूप से `duration_ms` की गणना करता है (मानव को प्रतिक्रिया देने में कितना समय लगा)। ```python agenteye.event.human_wait( @@ -347,49 +346,49 @@ agenteye.event.human_wait( agent_id="planner", input_id="inp-abc", # str, required - matching human_input के लिए correlation key prompt="Do you approve this action?", # str | None - मानव को दिखाया गया सवाल - options=["approve", "reject", "defer"], # list[str] | None - मानव को presented options + options=["approve", "reject", "defer"], # list[str] | None - मानव को दिए गए विकल्प reason="approval_required", # str | None - एजेंट क्यों प्रतीक्षा कर रहा है ) ``` ### `event.human_input()` -Emit होता है जब एक मानव input provide करता है और एजेंट resumes। `input_id` के माध्यम से `human_wait` से correlate करता है। `duration_ms` auto-computed है और caller द्वारा pass नहीं किया जाना चाहिए। +जब कोई मानव इनपुट प्रदान करता है और एजेंट फिर से शुरू होता है तो एमिट किया जाता है। `input_id` के माध्यम से `human_wait` से संबंधित। `duration_ms` स्वचालित रूप से गणना की जाती है और कॉलर द्वारा पास नहीं की जानी चाहिए। ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - prior human_wait से match होना चाहिए - response="approve", # str | None - मानव का उत्तर (free text या selected option) - # duration_ms automatically compute होता है - इसे pass न करें + input_id="inp-abc", # str, required - prior human_wait से मेल खाना चाहिए + response="approve", # str | None - मानव का उत्तर (मुक्त पाठ या चयनित विकल्प) + # duration_ms स्वचालित रूप से गणना की जाती है - इसे पास न करें ) ``` ### `event.human_pause()` -Emit होता है जब एक मानव सक्रिय रूप से एजेंट को pause करता है (उदाहरण के लिए एक डैशबोर्ड control के माध्यम से)। एजेंट suspended है लेकिन terminated नहीं है। +जब कोई मानव सक्रिय रूप से एजेंट को रोकता है तो एमिट किया जाता है (उदा. डैशबोर्ड कंट्रोल के माध्यम से)। एजेंट निलंबित है लेकिन समाप्त नहीं। ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - किसने एजेंट को pause किया + user_id="usr_42", # str | None - किसने एजेंट को रोका ) ``` ### `event.human_interrupt()` -Emit होता है जब एक मानव सक्रिय रूप से एजेंट को mid-execution में stop करता है। `human_pause` के विपरीत, एजेंट का काम suspended करने के बजाय terminated है। +जब कोई मानव एजेंट को mid-execution में सक्रिय रूप से रोकता है तो एमिट किया जाता है। `human_pause` के विपरीत, एजेंट का काम निलंबित होने के बजाय समाप्त हो जाता है। ```python agenteye.event.human_interrupt( session_id="run-001", agent_id="planner", reason="output_incorrect", # str | None - user_id="usr_42", # str | None - किसने एजेंट को interrupt किया - at_step="tool_use:web_search", # str | None - एजेंट stop किए जाने पर क्या कर रहा था + user_id="usr_42", # str | None - किसने एजेंट को बाधित किया + at_step="tool_use:web_search", # str | None - एजेंट क्या कर रहा था जब रोका गया ) ``` @@ -397,7 +396,7 @@ agenteye.event.human_interrupt( ## कस्टम फील्ड्स -कोई भी extra keyword arguments standard fields के बाद append किए जाते हैं: +कोई भी अतिरिक्त कीवर्ड आर्गुमेंट्स स्टैंडर्ड फील्ड्स के बाद इवेंट में जोड़े जाते हैं: ```python agenteye.event.tool_use( @@ -410,25 +409,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type`, और `environment` reserved हैं और `ValueError` raise करते हैं (`Reserved field names cannot be used as custom fields: [...]`) यदि custom fields के रूप में pass किए जाएँ। `session_id` और `agent_id` हर event method पर required parameters हैं और दूसरी बार supply नहीं किए जा सकते; Python `TypeError` raise करता है यदि आप ऐसा करते हैं। `configure(environment=...)` (या `AGENTEYE_ENVIRONMENT` variable) के साथ environment set करें। +`timestamp`, `type`, और `environment` आरक्षित हैं और `ValueError` को बढ़ाते हैं (`Reserved field names cannot be used as custom fields: [...]`) यदि कस्टम फील्ड्स के रूप में पास किए जाते हैं। `session_id` और `agent_id` हर इवेंट मेथड पर आवश्यक पैरामीटर्स हैं और दूसरी बार आपूर्ति नहीं किए जा सकते हैं; यदि आप ऐसा करते हैं तो Python `TypeError` बढ़ाता है। इसके बजाय `configure(environment=...)` (या `AGENTEYE_ENVIRONMENT` वेरिएबल) के साथ पर्यावरण सेट करें। + +जब आप उनकी फील्ड्स को क्वेरी करना चाहते हैं तो पेलोड्स को स्ट्रक्चर्ड JSON के रूप में रखें। जो मान JSON मूल रूप से समर्थन नहीं करता है - जैसे datetimes, UUIDs, decimals, sets, bytes, या model objects - को स्ट्रिंग्स में कन्वर्ट किया जाता है ताकि रिकॉर्डिंग सुरक्षित रूप से जारी रहे। --- -## इवेंट्स कैसे लिखे जाते हैं +## इवेंट्स कैसे लिखी जाती हैं -इवेंट्स in-process में buffered होते हैं और हर `flush_interval` सेकंड में (default 500 ms) disk को flush होते हैं। हर flush एक JSONL file लिखता है: +इवेंट्स को प्रोसेस में बफर किया जाता है और हर `flush_interval` सेकंड (डिफॉल्ट 500 ms) में डिस्क पर फ्लश किया जाता है। प्रत्येक फ्लश एक JSONL फाइल लिखता है: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -Collector इस directory को watch करता है और automatically files upload करता है। आपको इन files को directly manage करने की आवश्यकता नहीं है। +कलेक्टर इस डिरेक्टरी को देखता है और फाइलों को स्वचालित रूप से अपलोड करता है। आपको इन फाइलों को सीधे प्रबंधित करने की आवश्यकता नहीं है। -हर file atomically लिखी जाती है: SDK एक temporary file को लिखता है और फिर उसे place में rename करता है, इसलिए collector कभी half-written file नहीं देखता है। एक final flush भी चलता है जब आपकी process exits, इसलिए last interval में buffered events खोए नहीं जाते हैं। यदि collector offline है, तो इवेंट्स simply disk पर files के रूप में accumulate होते हैं और एक बार यह वापस आने पर ship होते हैं। +प्रत्येक फाइल एटमिकली लिखी जाती है: SDK एक अस्थायी फाइल में लिखता है और फिर इसे जगह पर रीनेम करता है, इसलिए कलेक्टर कभी आधी-लिखी गई फाइल नहीं देखता है। जब आपकी प्रक्रिया बाहर निकलती है तो एक अंतिम फ्लश भी चलता है, इसलिए अंतिम अंतराल में बफर किए गए इवेंट्स खोए नहीं जाते हैं। यदि कलेक्टर ऑफलाइन है, तो इवेंट्स डिस्क पर फाइलों के रूप में जमा हो जाते हैं और एक बार जब यह वापस आता है तो भेजते हैं। --- ## अगले कदम -- [Event stream](/hi/agenteye/event-stream): इन इवेंट्स को लाइव arrive होते देखें, environment, agent, और session द्वारा रंग-कोडित और filterable। -- [Sessions](/hi/agenteye/sessions): देखें कि कैसे paired events हर agent run को एक execution graph और timeline के रूप में reconstruct करते हैं। \ No newline at end of file +- [इवेंट स्ट्रीम](/hi/agenteye/event-stream): इन इवेंट्स को लाइव आते हुए देखें, रंग-कोडित और पर्यावरण, एजेंट, और सेशन द्वारा फ़िल्टर करने योग्य। +- [सेशन्स](/hi/agenteye/sessions): देखें कि कैसे पेयर्ड इवेंट्स प्रत्येक एजेंट रन को एक्सीक्यूशन ग्राफ और टाइमलाइन के रूप में पुनर्निर्माण करते हैं। diff --git a/docs/it/agenteye/python-sdk.mdx b/docs/it/agenteye/python-sdk.mdx index d8c3e909..02b3515b 100644 --- a/docs/it/agenteye/python-sdk.mdx +++ b/docs/it/agenteye/python-sdk.mdx @@ -1,11 +1,12 @@ --- title: "Python SDK" -description: "Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell'agente, chiamata di tool, richiesta al modello, hook e intervento umano." +description: "Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione di agente, chiamata di strumento, richiesta di modello, hook e intervento umano." --- -Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell'agente, chiamata di tool, richiesta al modello, hook e intervento umano. L'SDK Python per l'Observability di Failproof AI registra questa traccia dall'interno del codice dell'agente così puoi eseguire il debug, l'audit e valutare cosa è successo. Usalo ogni volta che vuoi che Failproof AI Observability osservi i tuoi agenti. -Dietro le quinte, l'SDK scrive eventi strutturati in file JSONL locali, e il daemon del collector li raccoglie e li spedisce automaticamente alla piattaforma. Non devi gestire questi file tu stesso. +Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione di agente, chiamata di strumento, richiesta di modello, hook e intervento umano. Failproof AI Observability Python SDK registra quella traccia dall'interno del tuo codice di agente così puoi eseguire il debug, fare audit e valutare cosa è successo. Utilizzalo ogni volta che vuoi che Failproof AI Observability osservi i tuoi agenti. + +Sotto il cofano, l'SDK scrive eventi strutturati su file JSONL locali, e il daemon del collector li raccoglie e li invia automaticamente alla piattaforma. Non gestisci questi file direttamente. > **Tip:** Nuovo a Failproof AI Observability? Questa pagina è il riferimento completo degli eventi SDK. @@ -17,15 +18,15 @@ Dietro le quinte, l'SDK scrive eventi strutturati in file JSONL locali, e il dae ## Installazione -L'SDK è distribuito ai clienti come wheel privato piuttosto che da un indice di pacchetti pubblico. Il tuo onboarding copre come ottenerlo, installarlo e bloccarlo — contatta il tuo referente Failproof AI se hai bisogno di accesso. +L'SDK è distribuito ai clienti come wheel privato piuttosto che da un indice di pacchetti pubblico. L'onboarding copre come ottenerlo, installarlo e bloccarlo — contatta il tuo referente Failproof AI se hai bisogno di accesso. -Una volta installato, conferma che ce l'hai: +Una volta installato, verifica di averlo: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Preferisci lasciare che un agente di coding faccia l'intera integrazione? La [Python SDK Agent Skill](/it/agenteye/python-sdk-skill) conosce il percorso di installazione, pianifica i punti di strumentazione, li scrive e verifica che gli eventi arrivino. +Preferisci lasciare che un agente di codifica faccia l'intera integrazione? [Python SDK Agent Skill](/it/agenteye/python-sdk-skill) conosce il percorso di installazione, pianifica i punti di strumentazione, li scrive e verifica che gli eventi arrivino. --- @@ -59,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### Strumentazione di una chiamata reale -In pratica racchiudi il codice dell'agente esistente. Delimita una chiamata al modello con `model_request` prima e `model_response` dopo, così i due eventi abbracciano la richiesta reale e Failproof AI Observability può abbinarli: +In pratica avvolgi il tuo codice di agente esistente. Racchiudi una chiamata di modello con `model_request` prima e `model_response` dopo, così i due eventi coprono la richiesta reale e Failproof AI Observability può associarli: ```python import anthropic @@ -94,11 +95,11 @@ agenteye.event.model_response( ) ``` -Racchiudi le chiamate di tool allo stesso modo con `tool_use` e `tool_result`, riutilizzando lo stesso `tool_call_id` sulla coppia. +Avvolgi le chiamate di strumento allo stesso modo con `tool_use` e `tool_result`, riutilizzando lo stesso `tool_call_id` per la coppia. -Ecco come appaiono questi eventi una volta che arrivano al dashboard, con codifica cromatica per tipo e filtrabili per ambiente, agente e sessione: +Ecco come appaiono questi eventi una volta che raggiungono il dashboard, con codice colore per tipo e filtrabile per ambiente, agente e sessione: -![Lo stream di Eventi live, codificato cromaticamente per tipo di evento e filtrabile per ambiente, agente e sessione](/agenteye/images/events-stream.png) +![Lo stream di eventi live, con codice colore per tipo di evento e filtrabile per ambiente, agente e sessione](/agenteye/images/events-stream.png) --- @@ -106,21 +107,24 @@ Ecco come appaiono questi eventi una volta che arrivano al dashboard, con codifi ```python agenteye.configure( - base_dir=None, # Path | str | None. Default: $AGENTEYE_HOME o ~/.agenteye - flush_interval=0.5, # float, secondi tra i cicli di flush - environment=None, # str | None. Etichetta dell'ambiente di deployment + base_dir=None, # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye + flush_interval=0.5, # float, seconds between flush cycles + environment=None, # str | None. Deployment environment label ) ``` -Chiamalo una volta prima di qualsiasi chiamata `event.*`. È sicuro ometterlo; i valori di default funzionano subito. Tutti gli argomenti sono solo per parola chiave; passali per nome come mostrato sopra. +Chiama una volta prima di qualsiasi chiamata `event.*`. Sicuro da omettere; i default funzionano subito. Tutti gli argomenti sono solo keyword; passali per nome come mostrato sopra. -Quando `base_dir` è `None` (il default), l'SDK legge `$AGENTEYE_HOME` se impostato, altrimenti ritorna a `~/.agenteye`. Questo corrisponde alla risoluzione del collector stesso, così una singola variabile d'ambiente `AGENTEYE_HOME` configura lo spool di eventi condiviso per sia l'SDK che il collector. +Quando `base_dir` è `None` (il default), l'SDK legge `$AGENTEYE_HOME` se impostato, +altrimenti ricade a `~/.agenteye`. Questo corrisponde alla risoluzione del collector stesso, +così una singola variabile di ambiente `AGENTEYE_HOME` configura lo spool di eventi condiviso per entrambi +l'SDK e il collector. --- ## Ambiente -Etichetta ogni evento con un ambiente di deployment (`production`, `staging`, `qa`, `canary`, ecc.). Impostalo una volta; l'SDK lo allega a ogni evento automaticamente. +Etichetta ogni evento con un ambiente di distribuzione (`production`, `staging`, `qa`, `canary`, ecc.). Impostalo una volta; l'SDK lo allega a ogni evento automaticamente. **Opzione 1: via `configure()`:** @@ -128,55 +132,55 @@ Etichetta ogni evento con un ambiente di deployment (`production`, `staging`, `q agenteye.configure(environment="production") ``` -**Opzione 2: via variabile d'ambiente:** +**Opzione 2: via variabile di ambiente:** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**Priorità:** `configure(environment=...)` vince sulla variabile d'ambiente. Se nessuno è impostato, il default è `"dev"`. +**Priorità:** `configure(environment=...)` vince sulla variabile di ambiente. Se nessuno dei due è impostato, usa il default `"dev"`. -Il valore dell'ambiente appare come filtro di prima classe nel dashboard ed è archiviato sul server per query veloci. +Il valore dell'ambiente appare come filtro di prima classe nel dashboard ed è memorizzato sul server per query veloci. -> **Warning:** I valori dell'ambiente non devono contenere una virgola letterale `,`. I filtri del dashboard usano multi-selezione separata da virgola sul wire (`?environment=prod,staging`), quindi un ambiente denominato `prod,blue` sarebbe diviso in due valori. Gli eventi con ambienti contenenti virgole vengono rifiutati al momento dell'ingest. +> **Warning:** I valori di ambiente non devono contenere una virgola letterale `,`. I filtri del dashboard usano multi-select separato da virgole sulla rete (`?environment=prod,staging`), quindi un ambiente denominato `prod,blue` sarebbe suddiviso in due valori. Gli eventi con ambienti contenenti virgole sono rifiutati al momento dell'inserimento. --- ## Dati e privacy -L'SDK registra solo i campi che passi esplicitamente. I prompt, i messaggi, gli input e output dei tool e il contenuto del modello vengono catturati unicamente perché li passi a una chiamata `event.*`. Nulla viene letto dal tuo processo o catturato implicitamente. Qualsiasi campo che non imposti viene omesso completamente dall'evento; non viene scritto su disco. +L'SDK registra solo i campi che passi esplicitamente. I prompt, i messaggi, gli input e output degli strumenti e i contenuti del modello sono catturati unicamente perché li passi a una chiamata `event.*`. Nulla viene letto dal tuo processo o catturato implicitamente. Qualsiasi campo non impostato è omesso completamente dall'evento; non è scritto su disco. -Questo rende la redazione tua scelta e tua responsabilità. Se un prompt o un payload di tool contiene PII o segreti che preferisci non archiviare, spoglialo o mascheralo prima di passarlo al metodo dell'evento. +Questo rende la redazione una tua scelta e responsabilità. Se un prompt o un payload di strumento contiene PII o segreti che preferirebbe non archiviare, rimuovilo o mascherarlo prima di passarlo al metodo dell'evento. --- -## Riferimento degli Eventi +## Riferimento degli eventi -La maggior parte degli eventi arrivano in coppie start/end che condividono un ID di correlazione: `tool_use` e `tool_result` condividono un `tool_call_id`, `hook_triggered` e `hook_completed` condividono un `hook_id`, e `human_wait` e `human_input` condividono un `input_id`. Emetti l'evento di inizio, fai il lavoro, poi emetti l'evento di fine con lo stesso ID. Failproof AI Observability abbina la coppia e calcola `duration_ms` per te, così non devi mai passare `duration_ms` tu stesso. +La maggior parte degli eventi arriva in coppie start/end che condividono un ID di correlazione: `tool_use` e `tool_result` condividono un `tool_call_id`, `hook_triggered` e `hook_completed` condividono un `hook_id`, e `human_wait` e `human_input` condividono un `input_id`. Emetti l'evento di inizio, fai il lavoro, quindi emetti l'evento di fine con lo stesso ID. Failproof AI Observability associa la coppia e calcola `duration_ms` per te, così non passi mai `duration_ms` da solo. -![Il grafo di esecuzione in stile git di una sessione accanto alla sua timeline di eventi, ricostruito dagli eventi abbinati, con il pannello di breakdown tool/model/hook](/agenteye/images/session-detail.png) +![Il grafo di esecuzione git-style di una sessione accanto alla sua timeline di eventi, ricostruito dagli eventi associati, con il pannello di breakdown tool/model/hook](/agenteye/images/session-detail.png) -Tutti i metodi dell'evento richiedono questi due campi: +Tutti i metodi di evento richiedono questi due campi: | Campo | Tipo | Descrizione | |---|---|---| -| `session_id` | `str` | Identifica l'esecuzione dell'agente di primo livello | -| `agent_id` | `str` | Identifica quale agente nella sessione ha emesso l'evento | +| `session_id` | `str` | Identifica l'esecuzione di agente di livello superiore | +| `agent_id` | `str` | Identifica quale agente all'interno della sessione ha emesso l'evento | -Tutti i metodi accettano anche `**kwargs` arbitrari per metadati personalizzati (vedi [Custom Fields](#custom-fields)). +Tutti i metodi accettano anche arbitrari `**kwargs` per metadati personalizzati (vedi [Custom Fields](#custom-fields)). --- ### `event.agent_start()` -Emesso quando un agente inizia a lavorare. +Emesso quando un agente inizia il lavoro. ```python agenteye.event.agent_start( session_id="run-001", agent_id="planner", goal="answer user query", # str | None - parent_id=None, # str | None - parent agent_id per agenti annidati + parent_id=None, # str | None - parent agent_id for nested agents ) ``` @@ -184,7 +188,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Emesso quando un agente finisce di lavorare. +Emesso quando un agente finisce il lavoro. ```python agenteye.event.agent_end( @@ -199,14 +203,14 @@ agenteye.event.agent_end( ### `event.tool_use()` -Emesso quando un agente richiama uno strumento. Abbina con `tool_result`; l'SDK calcola automaticamente `duration_ms`. +Emesso quando un agente invoca uno strumento. Associa con `tool_result`; l'SDK calcola automaticamente `duration_ms`. ```python agenteye.event.tool_use( session_id="run-001", agent_id="planner", tool_name="web_search", # str, required - tool_call_id="toolu_01", # str, required - chiave di correlazione per il tool_result corrispondente + tool_call_id="toolu_01", # str, required - correlation key for the matching tool_result input={"query": "..."}, # dict | None ) ``` @@ -222,10 +226,10 @@ agenteye.event.tool_result( session_id="run-001", agent_id="planner", tool_name="web_search", - tool_call_id="toolu_01", # deve corrispondere al precedente tool_use + tool_call_id="toolu_01", # must match the prior tool_use output={"results": ["..."]}, # Any | None - error=None, # str | None - imposta se lo strumento ha sollevato un'eccezione - # duration_ms viene calcolato automaticamente - non passarlo + error=None, # str | None - set if the tool raised + # duration_ms is computed automatically - do not pass it ) ``` @@ -239,18 +243,18 @@ Emesso appena prima di inviare un prompt a un LLM. agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - qualsiasi stringa provider/modello; non validata - messages=[ # list[dict] | None - turni di conversazione + model="claude-sonnet-4-6", # str | None - any provider/model string; not validated + messages=[ # list[dict] | None - conversation turns {"role": "user", "content": "..."}, ], - system="You are helpful.", # Any | None - str o lista di blocchi di contenuto - tools=[ # list[dict] | None - schemi di tool offerti al modello + system="You are helpful.", # Any | None - str or list of content blocks + tools=[ # list[dict] | None - tool schemas offered to the model {"name": "search", "input_schema": {"type": "object"}}, ], ) ``` -Le voci di `messages` accettano sia un semplice `content` di stringa o Anthropic-style list-of-blocks `content`. I parametri di sampling (`temperature`, `max_tokens`, ecc.) possono essere passati come kwargs extra. +Le voci `messages` accettano `content` di stringa semplice o Anthropic-style con list-of-blocks `content`. I parametri di campionamento (`temperature`, `max_tokens`, ecc.) possono essere passati come kwargs extra. --- @@ -262,31 +266,31 @@ Emesso quando l'LLM ritorna una risposta. agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - qualsiasi stringa provider/modello; non validata + model="claude-sonnet-4-6", # str | None - any provider/model string; not validated stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None - content=[ # Any | None - str, o lista di blocchi di contenuto + content=[ # Any | None - str, or list of content blocks {"type": "text", "text": "..."}, ], role="assistant", # str | None ) ``` -`content` accetta sia una stringa semplice (provider generici) o una lista di blocchi di contenuto in stile Anthropic. Le chiamate di tool vivono dentro `content` come blocchi `{"type": "tool_use", ...}`, senza un campo `tool_calls` separato. +`content` accetta una stringa semplice (provider generici) o una lista di blocchi di contenuto Anthropic-style. Le chiamate di strumento vivono all'interno di `content` come blocchi `{"type": "tool_use", ...}`, senza un campo `tool_calls` separato. --- ### `event.hook_triggered()` -Emesso quando un hook si attiva. Abbina con `hook_completed`; l'SDK calcola automaticamente `duration_ms`. +Emesso quando un hook si attiva. Associa con `hook_completed`; l'SDK calcola automaticamente `duration_ms`. ```python agenteye.event.hook_triggered( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", # str, required - hook_id="hook-abc", # str, required - chiave di correlazione + hook_id="hook-abc", # str, required - correlation key trigger_event="tool_use", # str | None input={"tool": "search"}, # Any | None ) @@ -303,11 +307,11 @@ agenteye.event.hook_completed( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", - hook_id="hook-abc", # deve corrispondere al precedente hook_triggered + hook_id="hook-abc", # must match the prior hook_triggered outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # duration_ms viene calcolato automaticamente - non passarlo + # duration_ms is computed automatically - do not pass it ) ``` @@ -329,63 +333,63 @@ agenteye.event.error( --- -## Eventi Human-in-the-Loop +## Eventi di Human-in-the-Loop -Gli eventi human-in-the-loop ti danno supervisione sui momenti in cui una persona entra nell'esecuzione dell'agente (in attesa di approvazione, fornendo input, mettendo in pausa o fermando l'agente). Ti permettono di misurare quanto tempo impiegano gli umani a rispondere (l'SDK calcola automaticamente `duration_ms` negli eventi accoppiati), audit di chi ha messo in pausa o interrotto un agente, e costruire workflow di approvazione e supervisione che compaiono nel dashboard. +Gli eventi human-in-the-loop ti danno supervisione sui momenti in cui una persona interviene nell'esecuzione dell'agente (in attesa di approvazione, fornitura di input, pausa o arresto dell'agente). Ti permettono di misurare quanto tempo gli umani impiegano per rispondere (l'SDK calcola automaticamente `duration_ms` negli eventi associati), fare audit di chi ha messo in pausa o interrotto un agente, e costruire flussi di approvazione e supervisione che emergono nel dashboard. ### `event.human_wait()` -Emesso quando l'agente sospende l'esecuzione per aspettare che un umano fornisca input. Abbina con `human_input`; l'SDK calcola automaticamente `duration_ms` (quanto tempo l'umano ha impiegato a rispondere). +Emesso quando l'agente pausa l'esecuzione per attendere un input umano. Associa con `human_input`; l'SDK calcola automaticamente `duration_ms` (quanto tempo l'umano ha impiegato per rispondere). ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - chiave di correlazione per il corrispondente human_input - prompt="Do you approve this action?", # str | None - la domanda mostrata all'umano - options=["approve", "reject", "defer"], # list[str] | None - scelte presentate all'umano - reason="approval_required", # str | None - perché l'agente sta aspettando + input_id="inp-abc", # str, required - correlation key for the matching human_input + prompt="Do you approve this action?", # str | None - the question shown to the human + options=["approve", "reject", "defer"], # list[str] | None - choices presented to the human + reason="approval_required", # str | None - why the agent is waiting ) ``` ### `event.human_input()` -Emesso quando un umano fornisce input e l'agente riprende. Si correla con `human_wait` via `input_id`. `duration_ms` è auto-calcolato e non deve essere passato dal chiamante. +Emesso quando un umano fornisce input e l'agente riprende. Si correla con `human_wait` via `input_id`. `duration_ms` è calcolato automaticamente e non deve essere passato dal chiamante. ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - deve corrispondere al precedente human_wait - response="approve", # str | None - la risposta dell'umano (testo libero o opzione selezionata) - # duration_ms viene calcolato automaticamente - non passarlo + input_id="inp-abc", # str, required - must match the prior human_wait + response="approve", # str | None - the human's answer (free text or selected option) + # duration_ms is computed automatically - do not pass it ) ``` ### `event.human_pause()` -Emesso quando un umano mette attivamente in pausa l'agente (es. tramite un controllo del dashboard). L'agente è sospeso ma non terminato. +Emesso quando un umano mette attivamente in pausa l'agente (ad es. tramite un controllo del dashboard). L'agente è sospeso ma non terminato. ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - chi ha messo in pausa l'agente + user_id="usr_42", # str | None - who paused the agent ) ``` ### `event.human_interrupt()` -Emesso quando un umano ferma attivamente l'agente durante l'esecuzione. A differenza di `human_pause`, il lavoro dell'agente viene terminato piuttosto che sospeso. +Emesso quando un umano ferma attivamente l'agente durante l'esecuzione. A differenza di `human_pause`, il lavoro dell'agente è terminato piuttosto che sospeso. ```python agenteye.event.human_interrupt( session_id="run-001", agent_id="planner", reason="output_incorrect", # str | None - user_id="usr_42", # str | None - chi ha interrotto l'agente - at_step="tool_use:web_search", # str | None - cosa stava facendo l'agente quando è stato fermato + user_id="usr_42", # str | None - who interrupted the agent + at_step="tool_use:web_search", # str | None - what the agent was doing when stopped ) ``` @@ -406,25 +410,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` e `environment` sono riservati e sollevano `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) se passati come custom fields. `session_id` e `agent_id` sono parametri obbligatori su ogni metodo evento e non possono essere forniti una seconda volta; Python solleva `TypeError` se lo fai. Imposta l'ambiente con `configure(environment=...)` (o la variabile `AGENTEYE_ENVIRONMENT`) invece. +`timestamp`, `type` e `environment` sono riservati e generano `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) se passati come campi personalizzati. `session_id` e `agent_id` sono parametri richiesti su ogni metodo di evento e non possono essere forniti una seconda volta; Python genera `TypeError` se lo fai. Impostare l'ambiente con `configure(environment=...)` (o la variabile `AGENTEYE_ENVIRONMENT`) invece. + +Mantieni i payload come JSON strutturato quando vuoi interrogare i loro campi. I valori che JSON non supporta nativamente—come datetime, UUID, decimali, set, byte o oggetti modello—vengono convertiti in stringhe così la registrazione continua in sicurezza. --- -## Come gli Eventi Vengono Scritti +## Come vengono scritti gli eventi -Gli eventi sono bufferizzati in-process e flushed su disco ogni `flush_interval` secondi (default 500 ms). Ogni flush scrive un file JSONL: +Gli eventi sono bufferizzati in-process e scaricati su disco ogni `flush_interval` secondi (default 500 ms). Ogni scaricamento scrive un file JSONL: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -Il collector guarda questa directory e carica i file automaticamente. Non hai bisogno di gestire questi file direttamente. +Il collector osserva questa directory e carica i file automaticamente. Non hai bisogno di gestire questi file direttamente. -Ogni file viene scritto atomicamente: l'SDK scrive su un file temporaneo e poi lo rinomina in posizione, così il collector non vede mai un file mezzo scritto. Un flush finale viene eseguito anche quando il tuo processo esce, così gli eventi bufferizzati nell'ultimo intervallo non vengono persi. Se il collector è offline, gli eventi semplicemente si accumulano come file su disco e vengono spediti una volta che torna online. +Ogni file viene scritto atomicamente: l'SDK scrive su un file temporaneo e poi lo rinomina in posizione, così il collector non vede mai un file mezzo scritto. Un ultimo scaricamento viene eseguito anche quando il tuo processo esce, così gli eventi bufferizzati nell'ultimo intervallo non vanno persi. Se il collector è offline, gli eventi semplicemente si accumulano come file su disco e vengono spediti una volta che ritorna online. --- ## Prossimi passi -- [Event stream](/it/agenteye/event-stream): guarda questi eventi arrivare live, codificati cromaticamente e filtrabili per ambiente, agente e sessione. -- [Sessions](/it/agenteye/sessions): vedi come gli eventi abbinati ricostruiscono ogni esecuzione dell'agente come grafo di esecuzione e timeline. \ No newline at end of file +- [Event stream](/it/agenteye/event-stream): osserva questi eventi arrivare live, con codice colore e filtrabile per ambiente, agente e sessione. +- [Sessions](/it/agenteye/sessions): vedi come gli eventi associati ricostruiscono ogni esecuzione di agente come un grafo di esecuzione e una timeline. \ No newline at end of file diff --git a/docs/ja/agenteye/python-sdk.mdx b/docs/ja/agenteye/python-sdk.mdx index 8affaee7..61b7b711 100644 --- a/docs/ja/agenteye/python-sdk.mdx +++ b/docs/ja/agenteye/python-sdk.mdx @@ -1,14 +1,14 @@ --- title: "Python SDK" -description: "AIエージェントが本番環境で行ったすべてのことを正確に把握する：エージェントの実行、ツール呼び出し、モデルリクエスト、フック、そして人間による介入。" +description: "本番環境でのAIエージェントの動作をすべて把握する：エージェントの実行、ツール呼び出し、モデルリクエスト、フック、人間の介入をすべて記録します。" --- -AIエージェントが本番環境で行ったすべてのことを正確に把握できます：エージェントの実行、ツール呼び出し、モデルリクエスト、フック、そして人間による介入。Failproof AI オブザーバビリティ Python SDKは、エージェントコードの内部からその記録を取得し、何が起きたかをデバッグ・監査・評価できるようにします。エージェントをFailproof AIオブザーバビリティで観測したい場合にご利用ください。 +本番環境でのAIエージェントの動作をすべて把握する：エージェントの実行、ツール呼び出し、モデルリクエスト、フック、人間の介入をすべて記録します。Failproof AI Observability Python SDKは、エージェントコードの内部からその実行記録を取得し、デバッグ、監査、動作の評価を可能にします。Failproof AI Observabilityでエージェントを監視したい場合にご利用ください。 -内部的には、SDKが構造化イベントをローカルのJSONLファイルに書き込み、コレクターデーモンがそれらを自動的に拾い上げてプラットフォームに送信します。これらのファイルを直接管理する必要はありません。 +内部では、SDKが構造化イベントをローカルのJSONLファイルに書き込み、コレクターデーモンがそれらを自動的に取得してプラットフォームに送信します。これらのファイルを手動で管理する必要はありません。 -> **ヒント:** Failproof AIオブザーバビリティを初めてお使いですか？このページがSDKイベントの完全なリファレンスです。 +> **ヒント:** Failproof AI Observabilityを初めてご利用の方は、このページがSDKイベントリファレンスの完全版です。
@@ -18,15 +18,15 @@ AIエージェントが本番環境で行ったすべてのことを正確に把 ## インストール -SDKは公開パッケージインデックスではなく、プライベートホイールとしてお客様に配布されます。取得・インストール・バージョン固定の方法はオンボーディング時にご案内します。アクセスが必要な場合は、Failproof AIの担当者にお問い合わせください。 +SDKは公開パッケージインデックスではなく、プライベートホイールとしてお客様に配布されます。取得方法、インストール方法、バージョン固定の方法はオンボーディング時にご説明します。アクセスが必要な場合は、Failproof AIの担当者にお問い合わせください。 -インストール後、以下で確認できます： +インストール後、以下のコマンドで確認してください： ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -コーディングエージェントに統合全体を任せたい場合は、[Python SDK Agent Skill](/ja/agenteye/python-sdk-skill)がインストールパスの把握、計装ポイントの計画・実装、イベントの到達確認まで行います。 +コーディングエージェントに統合作業を全部任せたい場合は、[Python SDK Agent Skill](/ja/agenteye/python-sdk-skill)がインストールパスの把握、計装ポイントの計画・実装、イベントの到達確認まで対応します。 --- @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### 実際の呼び出しへの計装 -実際には、既存のエージェントコードをラップします。モデル呼び出しの前に `model_request`、後に `model_response` を置いて、2つのイベントが実際のリクエストにまたがるようにすることで、Failproof AIオブザーバビリティがそれらを対応付けられます： +実際には、既存のエージェントコードをラップして使用します。モデル呼び出しの前後を `model_request` と `model_response` で囲むことで、2つのイベントが実際のリクエストをまたぎ、Failproof AI Observabilityがペアとして紐付けられます： ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -ツール呼び出しも同様に `tool_use` と `tool_result` でラップし、ペア間で同じ `tool_call_id` を使用してください。 +ツール呼び出しも同様に、`tool_use` と `tool_result` でラップし、ペア間で同じ `tool_call_id` を使用してください。 -ダッシュボードに到達したイベントの外観は次のとおりです。タイプ別に色分けされ、環境・エージェント・セッションでフィルタリングできます： +ダッシュボードに届いたイベントは、種別ごとに色分けされ、環境・エージェント・セッションでフィルタリングできます： -![ライブイベントストリーム。イベントタイプ別に色分けされ、環境・エージェント・セッションでフィルタリング可能](/agenteye/images/events-stream.png) +![ライブイベントストリーム：イベント種別ごとに色分けされ、環境・エージェント・セッションでフィルタリング可能](/agenteye/images/events-stream.png) --- @@ -108,69 +108,69 @@ agenteye.event.model_response( ```python agenteye.configure( base_dir=None, # Path | str | None. デフォルト: $AGENTEYE_HOME または ~/.agenteye - flush_interval=0.5, # float、フラッシュサイクルの間隔（秒） - environment=None, # str | None。デプロイ環境のラベル + flush_interval=0.5, # float、フラッシュ間隔（秒） + environment=None, # str | None。デプロイ環境ラベル ) ``` -`event.*` を呼び出す前に一度だけ呼び出します。省略しても安全で、デフォルト値はそのまま機能します。すべての引数はキーワード専用です。上記のように名前を指定して渡してください。 +`event.*` を呼び出す前に一度だけ呼び出してください。省略しても構いません。デフォルト値はそのまま動作します。すべての引数はキーワード引数専用です。上記のように名前を指定して渡してください。 -`base_dir` が `None`（デフォルト）の場合、SDKは `$AGENTEYE_HOME` が設定されていればそれを読み取り、設定されていなければ `~/.agenteye` にフォールバックします。これはコレクター自身の解決方法と一致するため、`AGENTEYE_ENVIRONMENT` 環境変数一つで、SDKとコレクター両方の共有イベントスプールを設定できます。 +`base_dir` が `None`（デフォルト）の場合、SDKは `$AGENTEYE_HOME` が設定されていればそれを使用し、設定されていなければ `~/.agenteye` にフォールバックします。これはコレクター自身の解決ロジックと一致しているため、`AGENTEYE_HOME` 環境変数を1つ設定するだけで、SDKとコレクター両方の共有イベントスプールを設定できます。 --- ## 環境 -すべてのイベントにデプロイ環境（`production`、`staging`、`qa`、`canary` など）のラベルを付けます。一度設定するだけで、SDKがすべてのイベントに自動的に付与します。 +すべてのイベントにデプロイ環境ラベル（`production`、`staging`、`qa`、`canary` など）を付与します。一度設定すると、SDKが以降のすべてのイベントに自動的に付加します。 -**オプション1：`configure()` を使用：** +**オプション1：`configure()` を使用する方法：** ```python agenteye.configure(environment="production") ``` -**オプション2：環境変数を使用：** +**オプション2：環境変数を使用する方法：** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**優先度：** `configure(environment=...)` が環境変数より優先されます。どちらも設定されていない場合、デフォルトは `"dev"` になります。 +**優先順位：** `configure(environment=...)` が環境変数より優先されます。どちらも設定されていない場合は `"dev"` がデフォルトになります。 -環境の値はダッシュボードのファーストクラスフィルターとして表示され、高速クエリのためサーバーに保存されます。 +環境の値はダッシュボードのファーストクラスフィルターとして表示され、高速クエリのためにサーバー上に保存されます。 -> **警告：** 環境の値にリテラルのカンマ `,` を含めることはできません。ダッシュボードフィルターはワイヤー上でカンマ区切りのマルチセレクトを使用（`?environment=prod,staging`）するため、`prod,blue` という名前の環境は2つの値に分割されてしまいます。カンマを含む環境のイベントは、インジェスト時に拒否されます。 +> **警告:** 環境の値にカンマ（`,`）をそのまま含めることはできません。ダッシュボードフィルターはカンマ区切りのマルチセレクト方式を使用しているため（`?environment=prod,staging`）、`prod,blue` という環境名は2つの値に分割されてしまいます。カンマを含む環境名のイベントはインジェスト時に拒否されます。 --- ## データとプライバシー -SDKは明示的に渡したフィールドのみを記録します。プロンプト、メッセージ、ツールの入出力、モデルコンテンツは、`event.*` の呼び出しに渡した場合にのみキャプチャされます。プロセスから暗黙的に読み取ったり、キャプチャしたりすることは一切ありません。設定しなかったフィールドはイベントから完全に除外され、ディスクに書き込まれることもありません。 +SDKは、明示的に渡したフィールドのみを記録します。プロンプト、メッセージ、ツールの入出力、モデルのコンテンツは、`event.*` 呼び出しに渡した場合にのみキャプチャされます。プロセスから暗黙的に読み取られたり、自動的にキャプチャされることはありません。設定しなかったフィールドはイベントから完全に省略され、ディスクにも書き込まれません。 -そのため、難読化はお客様の判断と責任で行っていただく必要があります。プロンプトやツールのペイロードに保存したくないPIIやシークレットが含まれている場合は、イベントメソッドに渡す前にストリップまたはマスクしてください。 +そのため、リダクション（機密情報の除去）はお客様自身の判断と責任で行ってください。プロンプトやツールのペイロードに保存したくないPIIや機密情報が含まれている場合は、イベントメソッドに渡す前にマスクまたは削除してください。 --- ## イベントリファレンス -ほとんどのイベントは相関IDを共有する開始/終了のペアで構成されます：`tool_use` と `tool_result` は `tool_call_id` を共有し、`hook_triggered` と `hook_completed` は `hook_id` を共有し、`human_wait` と `human_input` は `input_id` を共有します。開始イベントを発行し、処理を行い、同じIDで終了イベントを発行してください。Failproof AIオブザーバビリティがペアを照合し `duration_ms` を自動計算するため、`duration_ms` を自分で渡す必要はありません。 +ほとんどのイベントは、相関IDを共有する開始/終了のペアで構成されています：`tool_use` と `tool_result` は `tool_call_id` を共有し、`hook_triggered` と `hook_completed` は `hook_id` を共有し、`human_wait` と `human_input` は `input_id` を共有します。開始イベントを発行し、処理を行い、同じIDで終了イベントを発行してください。Failproof AI Observabilityがペアを照合し、`duration_ms` を自動計算します。`duration_ms` を自分で渡す必要はありません。 -![セッションのgitスタイルの実行グラフとイベントタイムライン。ペアのイベントから再構築され、ツール/モデル/フックの内訳パネルを備えています](/agenteye/images/session-detail.png) +![ペアイベントから再構築されたセッションのgitスタイル実行グラフとイベントタイムライン、ツール・モデル・フック内訳パネルを含む](/agenteye/images/session-detail.png) -すべてのイベントメソッドには次の2つのフィールドが必要です： +すべてのイベントメソッドで以下の2つのフィールドが必須です： | フィールド | 型 | 説明 | |---|---|---| | `session_id` | `str` | トップレベルのエージェント実行を識別する | | `agent_id` | `str` | セッション内でイベントを発行したエージェントを識別する | -すべてのメソッドはカスタムメタデータ用の任意の `**kwargs` も受け付けます（[カスタムフィールド](#custom-fields)を参照）。 +すべてのメソッドはカスタムメタデータ用の任意の `**kwargs` も受け付けます（[カスタムフィールド](#custom-fields) を参照）。 --- ### `event.agent_start()` -エージェントが処理を開始したときに発行されます。 +エージェントが処理を開始したときに発行します。 ```python agenteye.event.agent_start( @@ -185,7 +185,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -エージェントが処理を完了したときに発行されます。 +エージェントが処理を完了したときに発行します。 ```python agenteye.event.agent_end( @@ -200,7 +200,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -エージェントがツールを呼び出したときに発行されます。`tool_result` とペアにしてください。SDKが `duration_ms` を自動計算します。 +エージェントがツールを呼び出すときに発行します。`tool_result` とペアにすることで、SDKが `duration_ms` を自動計算します。 ```python agenteye.event.tool_use( @@ -216,7 +216,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -ツールが結果を返したときに発行されます。`tool_call_id` を通じて `tool_use` と関連付けられます。 +ツールが結果を返したときに発行します。`tool_call_id` を通じて `tool_use` と対応付けられます。 ```python agenteye.event.tool_result( @@ -226,7 +226,7 @@ agenteye.event.tool_result( tool_call_id="toolu_01", # 先行する tool_use と一致させること output={"results": ["..."]}, # Any | None error=None, # str | None - ツールが例外を発生させた場合に設定 - # duration_ms は自動計算されます - 渡さないこと + # duration_ms は自動計算されます。渡さないでください ) ``` @@ -234,14 +234,14 @@ agenteye.event.tool_result( ### `event.model_request()` -LLMにプロンプトを送信する直前に発行されます。 +LLMにプロンプトを送信する直前に発行します。 ```python agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - プロバイダー/モデル文字列（検証なし） - messages=[ # list[dict] | None - 会話のターン + model="claude-sonnet-4-6", # str | None - プロバイダー/モデルの文字列（バリデーションなし） + messages=[ # list[dict] | None - 会話ターン {"role": "user", "content": "..."}, ], system="You are helpful.", # Any | None - 文字列またはコンテンツブロックのリスト @@ -251,19 +251,19 @@ agenteye.event.model_request( ) ``` -`messages` エントリには、プレーン文字列の `content` またはAnthropicスタイルのブロックリスト形式の `content` が使用できます。サンプリングパラメータ（`temperature`、`max_tokens` など）は追加のkwargsとして渡すことができます。 +`messages` のエントリは、プレーン文字列の `content` またはAnthropicスタイルのコンテンツブロックリストの `content` のどちらも受け付けます。サンプリングパラメーター（`temperature`、`max_tokens` など）は追加のkwargsとして渡せます。 --- ### `event.model_response()` -LLMがレスポンスを返したときに発行されます。 +LLMが応答を返したときに発行します。 ```python agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - プロバイダー/モデル文字列（検証なし） + model="claude-sonnet-4-6", # str | None - プロバイダー/モデルの文字列（バリデーションなし） stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None @@ -274,13 +274,13 @@ agenteye.event.model_response( ) ``` -`content` にはプレーン文字列（汎用プロバイダー向け）またはAnthropicスタイルのコンテンツブロックのリストが使用できます。ツール呼び出しは `content` 内の `{"type": "tool_use", ...}` ブロックとして含まれ、別途 `tool_calls` フィールドは存在しません。 +`content` はプレーン文字列（汎用プロバイダー）またはAnthropicスタイルのコンテンツブロックリストのどちらも受け付けます。ツール呼び出しは `content` 内に `{"type": "tool_use", ...}` ブロックとして含まれ、独立した `tool_calls` フィールドはありません。 --- ### `event.hook_triggered()` -フックが発火したときに発行されます。`hook_completed` とペアにしてください。SDKが `duration_ms` を自動計算します。 +フックが発火したときに発行します。`hook_completed` とペアにすることで、SDKが `duration_ms` を自動計算します。 ```python agenteye.event.hook_triggered( @@ -297,7 +297,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -フックが完了したときに発行されます。`hook_id` を通じて `hook_triggered` と関連付けられます。 +フックが完了したときに発行します。`hook_id` を通じて `hook_triggered` と対応付けられます。 ```python agenteye.event.hook_completed( @@ -308,7 +308,7 @@ agenteye.event.hook_completed( outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # duration_ms は自動計算されます - 渡さないこと + # duration_ms は自動計算されます。渡さないでください ) ``` @@ -316,7 +316,7 @@ agenteye.event.hook_completed( ### `event.error()` -未処理エラーが発生したときに発行されます。 +未処理のエラーが発生したときに発行します。 ```python agenteye.event.error( @@ -332,11 +332,11 @@ agenteye.event.error( ## ヒューマン・イン・ザ・ループイベント -ヒューマン・イン・ザ・ループイベントは、エージェントの実行に人間が介入する瞬間（承認待ち、入力提供、一時停止、またはエージェントの停止）を監視する機能を提供します。ペアのイベントで人間が応答するまでの時間を計測（SDKが `duration_ms` を自動計算）したり、エージェントを一時停止または中断した担当者を監査したり、ダッシュボードに表示される承認・監視ワークフローを構築したりすることができます。 +ヒューマン・イン・ザ・ループイベントは、人間がエージェントの実行に介入するタイミング（承認待ち、入力提供、一時停止、エージェント停止）を監視します。これにより、人間の応答にかかった時間の計測（SDKがペアイベントの `duration_ms` を自動計算）、誰がエージェントを一時停止または中断したかの監査、ダッシュボードに表示される承認・監視ワークフローの構築が可能になります。 ### `event.human_wait()` -エージェントが人間からの入力を待つために実行を一時停止したときに発行されます。`human_input` とペアにしてください。SDKが `duration_ms`（人間が応答するまでの時間）を自動計算します。 +エージェントが人間からの入力を待つために実行を一時停止したときに発行します。`human_input` とペアにすることで、SDKが `duration_ms`（人間が応答するまでの時間）を自動計算します。 ```python agenteye.event.human_wait( @@ -345,47 +345,47 @@ agenteye.event.human_wait( input_id="inp-abc", # str、必須 - 対応する human_input との相関キー prompt="Do you approve this action?", # str | None - 人間に表示される質問 options=["approve", "reject", "defer"], # list[str] | None - 人間に提示される選択肢 - reason="approval_required", # str | None - エージェントが待機している理由 + reason="approval_required", # str | None - 待機理由 ) ``` ### `event.human_input()` -人間が入力を提供してエージェントが再開したときに発行されます。`input_id` を通じて `human_wait` と関連付けられます。`duration_ms` は自動計算されるため、呼び出し元が渡してはいけません。 +人間が入力を提供してエージェントが再開したときに発行します。`input_id` を通じて `human_wait` と対応付けられます。`duration_ms` は自動計算されるため、呼び出し元が渡してはなりません。 ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", input_id="inp-abc", # str、必須 - 先行する human_wait と一致させること - response="approve", # str | None - 人間の回答（フリーテキストまたは選択された選択肢） - # duration_ms は自動計算されます - 渡さないこと + response="approve", # str | None - 人間の回答（自由記述または選択肢から選択） + # duration_ms は自動計算されます。渡さないでください ) ``` ### `event.human_pause()` -人間がエージェントを能動的に一時停止したとき（例：ダッシュボードの操作により）に発行されます。エージェントは停止ではなく、中断された状態になります。 +人間がエージェントを能動的に一時停止したとき（ダッシュボードのコントロールなどを通じて）に発行します。エージェントは停止ではなく中断されます。 ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - エージェントを一時停止した担当者 + user_id="usr_42", # str | None - エージェントを一時停止したユーザー ) ``` ### `event.human_interrupt()` -人間がエージェントの実行中に能動的に停止したときに発行されます。`human_pause` とは異なり、エージェントの処理は中断ではなく終了されます。 +人間がエージェントの実行途中で能動的に停止したときに発行します。`human_pause` と異なり、エージェントの処理は中断ではなく終了されます。 ```python agenteye.event.human_interrupt( session_id="run-001", agent_id="planner", reason="output_incorrect", # str | None - user_id="usr_42", # str | None - エージェントを中断した担当者 + user_id="usr_42", # str | None - エージェントを中断したユーザー at_step="tool_use:web_search", # str | None - 停止時にエージェントが実行していた処理 ) ``` @@ -394,7 +394,7 @@ agenteye.event.human_interrupt( ## カスタムフィールド -追加のキーワード引数は標準フィールドの後にイベントに付加されます： +追加のキーワード引数はすべて、標準フィールドの後にイベントに追加されます： ```python agenteye.event.tool_use( @@ -407,13 +407,15 @@ agenteye.event.tool_use( ) ``` -`timestamp`、`type`、`environment` は予約済みで、カスタムフィールドとして渡すと `ValueError`（`Reserved field names cannot be used as custom fields: [...]`）が発生します。`session_id` と `agent_id` はすべてのイベントメソッドの必須パラメータであり、2回目の指定はできません。2回指定するとPythonが `TypeError` を発生させます。環境は `configure(environment=...)` または `AGENTEYE_ENVIRONMENT` 変数で設定してください。 +`timestamp`、`type`、`environment` は予約済みであり、カスタムフィールドとして渡すと `ValueError`（`Reserved field names cannot be used as custom fields: [...]`）が発生します。`session_id` と `agent_id` はすべてのイベントメソッドで必須パラメーターであり、2度目に指定するとPythonが `TypeError` を発生させます。環境は `configure(environment=...)` または `AGENTEYE_ENVIRONMENT` 変数で設定してください。 + +フィールドをクエリしたい場合は、ペイロードを構造化JSONとして保持してください。JSONがネイティブにサポートしない値（日時、UUID、小数、セット、バイト、モデルオブジェクトなど）は文字列に変換されるため、記録は安全に継続されます。 --- ## イベントの書き込み方法 -イベントはプロセス内にバッファリングされ、`flush_interval` 秒ごと（デフォルト500ミリ秒）にディスクにフラッシュされます。各フラッシュで1つのJSONLファイルが書き込まれます： +イベントはプロセス内でバッファリングされ、`flush_interval` 秒ごと（デフォルト500ms）にディスクにフラッシュされます。各フラッシュで1つのJSONLファイルが書き込まれます： ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl @@ -421,11 +423,11 @@ agenteye.event.tool_use( コレクターはこのディレクトリを監視し、ファイルを自動的にアップロードします。これらのファイルを直接管理する必要はありません。 -各ファイルはアトミックに書き込まれます：SDKが一時ファイルに書き込み、その後リネームして所定の場所に配置するため、コレクターが半書き込み状態のファイルを見ることはありません。最終フラッシュはプロセス終了時にも実行されるため、最後のインターバルでバッファリングされたイベントが失われることもありません。コレクターがオフラインの場合、イベントはディスク上にファイルとして蓄積され、オンラインに戻った時点で送信されます。 +各ファイルはアトミックに書き込まれます：SDKは一時ファイルに書き込んだ後、所定の場所にリネームするため、コレクターが書き込み途中のファイルを読み取ることはありません。プロセス終了時にも最終フラッシュが実行されるため、最後のインターバルでバッファリングされたイベントも失われません。コレクターがオフラインの場合、イベントはディスク上のファイルとして蓄積され、コレクターが復帰すると自動的に送信されます。 --- ## 次のステップ -- [イベントストリーム](/ja/agenteye/event-stream): これらのイベントがライブで到達する様子を確認できます。タイプ別に色分けされ、環境・エージェント・セッションでフィルタリング可能です。 -- [セッション](/ja/agenteye/sessions): ペアのイベントから各エージェントの実行が実行グラフとタイムラインとしてどのように再構築されるかを確認できます。 \ No newline at end of file +- [イベントストリーム](/ja/agenteye/event-stream)：イベントがライブで届く様子を、種別ごとに色分けし環境・エージェント・セッションでフィルタリングしながら確認できます。 +- [セッション](/ja/agenteye/sessions)：ペアイベントが各エージェント実行を実行グラフとタイムラインとして再構築する様子を確認できます。 \ No newline at end of file diff --git a/docs/ko/agenteye/python-sdk.mdx b/docs/ko/agenteye/python-sdk.mdx index 97f371a9..85b9f702 100644 --- a/docs/ko/agenteye/python-sdk.mdx +++ b/docs/ko/agenteye/python-sdk.mdx @@ -1,14 +1,14 @@ --- title: "Python SDK" -description: "AI 에이전트가 프로덕션에서 수행한 모든 작업을 정확히 파악하세요: 모든 에이전트 실행, 도구 호출, 모델 요청, 훅, 그리고 사람의 개입까지." +description: "프로덕션에서 AI 에이전트가 수행한 모든 작업을 확인하세요: 에이전트 실행, 도구 호출, 모델 요청, 훅, 그리고 사람의 개입까지." --- -AI 에이전트가 프로덕션에서 수행한 모든 작업을 정확히 파악하세요: 모든 에이전트 실행, 도구 호출, 모델 요청, 훅, 그리고 사람의 개입까지. Failproof AI Observability Python SDK는 에이전트 코드 내부에서 해당 흔적을 기록하여 발생한 일을 디버그하고, 감사하고, 평가할 수 있도록 합니다. Failproof AI Observability로 에이전트를 관찰하고 싶을 때마다 사용하세요. +프로덕션에서 AI 에이전트가 수행한 모든 작업을 확인하세요: 에이전트 실행, 도구 호출, 모델 요청, 훅, 그리고 사람의 개입까지. Failproof AI Observability Python SDK는 에이전트 코드 내부에서 해당 기록을 남겨 디버깅, 감사, 동작 평가에 활용할 수 있도록 합니다. Failproof AI Observability로 에이전트를 관측하고 싶을 때 사용하세요. -내부적으로 SDK는 구조화된 이벤트를 로컬 JSONL 파일에 기록하며, 수집기 데몬이 이를 감지하여 자동으로 플랫폼에 전송합니다. 해당 파일을 직접 관리할 필요는 없습니다. +내부적으로 SDK는 구조화된 이벤트를 로컬 JSONL 파일에 기록하며, 컬렉터 데몬이 이 파일을 감지해 플랫폼으로 자동 전송합니다. 해당 파일을 직접 관리할 필요는 없습니다. -> **팁:** Failproof AI Observability가 처음이신가요? 이 페이지는 완전한 SDK 이벤트 레퍼런스입니다. +> **팁:** Failproof AI Observability를 처음 사용하시나요? 이 페이지는 SDK 이벤트 전체 레퍼런스입니다.
@@ -18,15 +18,15 @@ AI 에이전트가 프로덕션에서 수행한 모든 작업을 정확히 파 ## 설치 -SDK는 공개 패키지 인덱스가 아닌 프라이빗 wheel 파일로 고객에게 배포됩니다. 온보딩 과정에서 획득, 설치, 버전 고정 방법을 안내합니다. 접근 권한이 필요하시면 Failproof AI 담당자에게 문의하세요. +SDK는 공개 패키지 인덱스가 아닌 프라이빗 wheel 파일로 고객에게 배포됩니다. 획득 방법, 설치 방법, 버전 고정 방법은 온보딩 과정에서 안내됩니다. 접근 권한이 필요하시면 Failproof AI 담당자에게 문의하세요. -설치 후 다음 명령어로 확인하세요: +설치 후 다음 명령으로 확인하세요: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -코딩 에이전트가 전체 통합을 처리하도록 하고 싶으신가요? [Python SDK Agent Skill](/ko/agenteye/python-sdk-skill)은 설치 경로를 파악하고, 계측 지점을 계획하여 작성한 뒤, 이벤트가 정상적으로 수신되는지 검증합니다. +코딩 에이전트가 전체 통합 작업을 처리하도록 하고 싶으신가요? [Python SDK Agent Skill](/ko/agenteye/python-sdk-skill)은 설치 경로를 파악하고, 계측 지점을 계획하여 코드를 작성한 뒤 이벤트가 정상적으로 수신되는지 검증합니다. --- @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### 실제 호출 계측하기 -실제로는 기존 에이전트 코드를 감싸는 방식으로 사용합니다. 모델 호출 전에 `model_request`, 호출 후에 `model_response`로 감싸면 두 이벤트가 실제 요청을 포괄하게 되며, Failproof AI Observability가 두 이벤트를 쌍으로 연결할 수 있습니다: +실제로는 기존 에이전트 코드를 감싸는 방식으로 사용합니다. 모델 호출 전에 `model_request`를, 호출 후에 `model_response`를 작성하면 두 이벤트가 실제 요청 구간을 감싸게 되고, Failproof AI Observability가 이 둘을 연결할 수 있습니다: ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -도구 호출도 동일한 방식으로 `tool_use`와 `tool_result`로 감싸되, 쌍을 이루는 두 이벤트에 동일한 `tool_call_id`를 사용하세요. +도구 호출도 동일한 방식으로 `tool_use`와 `tool_result`로 감싸며, 하나의 `tool_call_id`를 두 이벤트에 공유합니다. -다음은 해당 이벤트들이 대시보드에 도착했을 때의 모습으로, 이벤트 유형별로 색상이 구분되며 환경, 에이전트, 세션별로 필터링할 수 있습니다: +아래는 이 이벤트들이 대시보드에 도착한 모습입니다. 이벤트 유형별로 색상이 구분되며, 환경, 에이전트, 세션별로 필터링할 수 있습니다: -![이벤트 유형별로 색상이 구분되고 환경, 에이전트, 세션별로 필터링 가능한 실시간 이벤트 스트림](/agenteye/images/events-stream.png) +![이벤트 유형별 색상 코딩과 환경·에이전트·세션 필터를 제공하는 실시간 이벤트 스트림](/agenteye/images/events-stream.png) --- @@ -113,66 +113,64 @@ agenteye.configure( ) ``` -`event.*` 호출 전에 한 번만 호출하세요. 생략해도 안전하며, 기본값으로 바로 동작합니다. 모든 인수는 키워드 전용이므로 위에 표시된 것처럼 이름으로 전달하세요. +`event.*` 호출 전에 한 번 호출하세요. 생략해도 안전하며, 기본값만으로도 바로 동작합니다. 모든 인자는 키워드 전용이므로 위와 같이 이름을 명시해 전달하세요. -`base_dir`가 `None`(기본값)인 경우, SDK는 `$AGENTEYE_HOME`이 설정되어 있으면 해당 값을 읽고, -그렇지 않으면 `~/.agenteye`로 폴백합니다. 이는 수집기 자체의 경로 결정 방식과 동일하므로, -`AGENTEYE_HOME` 환경 변수 하나로 SDK와 수집기 모두의 공유 이벤트 스풀을 설정할 수 있습니다. +`base_dir`가 `None`(기본값)이면 SDK는 `$AGENTEYE_HOME` 환경 변수가 설정된 경우 이를 사용하고, 그렇지 않으면 `~/.agenteye`로 폴백합니다. 이는 컬렉터의 경로 해석 방식과 동일하므로, `AGENTEYE_HOME` 환경 변수 하나로 SDK와 컬렉터가 공유하는 이벤트 스풀을 설정할 수 있습니다. --- -## 환경 +## 환경(Environment) -모든 이벤트에 배포 환경(`production`, `staging`, `qa`, `canary` 등)을 레이블로 지정하세요. 한 번만 설정하면 SDK가 모든 이벤트에 자동으로 첨부합니다. +모든 이벤트에 배포 환경(`production`, `staging`, `qa`, `canary` 등)을 레이블로 붙이세요. 한 번 설정하면 SDK가 모든 이벤트에 자동으로 포함합니다. -**방법 1: `configure()`를 통해:** +**방법 1: `configure()`를 통한 설정:** ```python agenteye.configure(environment="production") ``` -**방법 2: 환경 변수를 통해:** +**방법 2: 환경 변수를 통한 설정:** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**우선순위:** `configure(environment=...)`가 환경 변수보다 우선합니다. 둘 다 설정되지 않으면 기본값은 `"dev"`입니다. +**우선순위:** `configure(environment=...)`가 환경 변수보다 우선합니다. 둘 다 설정되지 않은 경우 `"dev"`가 기본값입니다. -환경 값은 대시보드에서 1급 필터로 표시되며, 빠른 쿼리를 위해 서버에 저장됩니다. +환경 값은 대시보드의 1순위 필터로 표시되며, 빠른 쿼리를 위해 서버에 저장됩니다. -> **주의:** 환경 값에는 리터럴 `,` 쉼표를 포함할 수 없습니다. 대시보드 필터는 URL에서 쉼표로 구분된 다중 선택 방식을 사용하므로(`?environment=prod,staging`), `prod,blue`라는 이름의 환경은 두 개의 값으로 분리됩니다. 쉼표가 포함된 환경의 이벤트는 수집 시점에 거부됩니다. +> **경고:** 환경 값에는 쉼표(`,`)를 사용할 수 없습니다. 대시보드 필터는 와이어에서 쉼표로 구분된 다중 선택을 사용하므로(`?environment=prod,staging`), `prod,blue`와 같이 쉼표가 포함된 환경 이름은 두 개의 값으로 분리됩니다. 쉼표가 포함된 환경 값의 이벤트는 수집 시 거부됩니다. --- ## 데이터와 개인정보 보호 -SDK는 명시적으로 전달한 필드만 기록합니다. 프롬프트, 메시지, 도구 입력/출력, 모델 콘텐츠는 오직 `event.*` 호출에 직접 전달했기 때문에 캡처됩니다. 프로세스에서 아무것도 읽거나 암묵적으로 캡처하지 않습니다. 설정하지 않은 필드는 이벤트에서 완전히 생략되며, 디스크에도 기록되지 않습니다. +SDK는 명시적으로 전달한 필드만 기록합니다. 프롬프트, 메시지, 도구 입출력, 모델 콘텐츠는 오직 `event.*` 호출에 직접 전달할 때만 캡처됩니다. 프로세스에서 아무것도 암묵적으로 읽거나 캡처하지 않습니다. 설정하지 않은 필드는 이벤트에서 완전히 생략되며, 디스크에도 기록되지 않습니다. -따라서 데이터 제거는 사용자의 선택이자 책임입니다. 프롬프트나 도구 페이로드에 저장하고 싶지 않은 PII나 시크릿이 포함되어 있다면, 이벤트 메서드에 전달하기 전에 제거하거나 마스킹하세요. +따라서 데이터 마스킹은 사용자의 선택이자 책임입니다. 프롬프트나 도구 페이로드에 저장하지 않을 개인정보(PII)나 시크릿이 포함된 경우, 이벤트 메서드에 전달하기 전에 제거하거나 마스킹하세요. --- ## 이벤트 레퍼런스 -대부분의 이벤트는 상관 ID를 공유하는 시작/종료 쌍으로 구성됩니다: `tool_use`와 `tool_result`는 `tool_call_id`를 공유하고, `hook_triggered`와 `hook_completed`는 `hook_id`를 공유하며, `human_wait`와 `human_input`은 `input_id`를 공유합니다. 시작 이벤트를 발생시키고, 작업을 수행한 뒤, 동일한 ID로 종료 이벤트를 발생시키세요. Failproof AI Observability가 쌍을 매칭하고 `duration_ms`를 자동으로 계산하므로, `duration_ms`를 직접 전달할 필요가 없습니다. +대부분의 이벤트는 상관 ID를 공유하는 시작/종료 쌍으로 이루어집니다: `tool_use`와 `tool_result`는 `tool_call_id`를, `hook_triggered`와 `hook_completed`는 `hook_id`를, `human_wait`와 `human_input`는 `input_id`를 공유합니다. 시작 이벤트를 발행하고 작업을 수행한 뒤, 동일한 ID로 종료 이벤트를 발행하세요. Failproof AI Observability가 쌍을 매칭하고 `duration_ms`를 자동으로 계산하므로, `duration_ms`를 직접 전달할 필요가 없습니다. -![쌍을 이루는 이벤트로 재구성된 에이전트 실행의 git 스타일 실행 그래프와 이벤트 타임라인, 그리고 도구/모델/훅 분류 패널](/agenteye/images/session-detail.png) +![페어 이벤트로 재구성된 에이전트 실행 그래프와 이벤트 타임라인, 도구/모델/훅 분석 패널이 나란히 표시된 세션 상세 화면](/agenteye/images/session-detail.png) -모든 이벤트 메서드에는 다음 두 필드가 필요합니다: +모든 이벤트 메서드는 다음 두 필드를 필수로 요구합니다: | 필드 | 타입 | 설명 | |---|---|---| | `session_id` | `str` | 최상위 에이전트 실행을 식별합니다 | -| `agent_id` | `str` | 세션 내에서 이벤트를 발생시킨 에이전트를 식별합니다 | +| `agent_id` | `str` | 세션 내에서 이벤트를 발행한 에이전트를 식별합니다 | -모든 메서드는 사용자 정의 메타데이터를 위한 임의의 `**kwargs`도 허용합니다([사용자 정의 필드](#custom-fields) 참고). +모든 메서드는 커스텀 메타데이터를 위한 임의의 `**kwargs`도 허용합니다([커스텀 필드](#커스텀-필드) 참조). --- ### `event.agent_start()` -에이전트가 작업을 시작할 때 발생합니다. +에이전트가 작업을 시작할 때 발행됩니다. ```python agenteye.event.agent_start( @@ -187,7 +185,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -에이전트가 작업을 완료할 때 발생합니다. +에이전트가 작업을 완료할 때 발행됩니다. ```python agenteye.event.agent_end( @@ -202,7 +200,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -에이전트가 도구를 호출할 때 발생합니다. `tool_result`와 쌍을 이루며, SDK가 `duration_ms`를 자동으로 계산합니다. +에이전트가 도구를 호출할 때 발행됩니다. `tool_result`와 쌍을 이루며, SDK가 `duration_ms`를 자동 계산합니다. ```python agenteye.event.tool_use( @@ -218,7 +216,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -도구가 반환될 때 발생합니다. `tool_call_id`를 통해 `tool_use`와 연결됩니다. +도구가 결과를 반환할 때 발행됩니다. `tool_call_id`를 통해 `tool_use`와 연결됩니다. ```python agenteye.event.tool_result( @@ -236,7 +234,7 @@ agenteye.event.tool_result( ### `event.model_request()` -LLM에 프롬프트를 전송하기 직전에 발생합니다. +LLM에 프롬프트를 전송하기 직전에 발행됩니다. ```python agenteye.event.model_request( @@ -253,13 +251,13 @@ agenteye.event.model_request( ) ``` -`messages` 항목은 일반 문자열 `content`와 Anthropic 스타일의 블록 리스트 `content` 모두 허용합니다. 샘플링 파라미터(`temperature`, `max_tokens` 등)는 추가 kwargs로 전달할 수 있습니다. +`messages` 항목의 `content`는 일반 문자열 또는 Anthropic 스타일의 블록 리스트를 모두 허용합니다. 샘플링 파라미터(`temperature`, `max_tokens` 등)는 추가 kwargs로 전달할 수 있습니다. --- ### `event.model_response()` -LLM이 응답을 반환할 때 발생합니다. +LLM이 응답을 반환할 때 발행됩니다. ```python agenteye.event.model_response( @@ -276,13 +274,13 @@ agenteye.event.model_response( ) ``` -`content`는 일반 문자열(범용 제공자) 또는 Anthropic 스타일의 콘텐츠 블록 리스트 모두 허용합니다. 도구 호출은 별도의 `tool_calls` 필드 없이 `content` 안에 `{"type": "tool_use", ...}` 블록으로 포함됩니다. +`content`는 일반 문자열(범용 제공자) 또는 Anthropic 스타일의 콘텐츠 블록 리스트를 허용합니다. 도구 호출은 별도의 `tool_calls` 필드 없이 `content` 내부의 `{"type": "tool_use", ...}` 블록으로 포함됩니다. --- ### `event.hook_triggered()` -훅이 실행될 때 발생합니다. `hook_completed`와 쌍을 이루며, SDK가 `duration_ms`를 자동으로 계산합니다. +훅이 실행될 때 발행됩니다. `hook_completed`와 쌍을 이루며, SDK가 `duration_ms`를 자동 계산합니다. ```python agenteye.event.hook_triggered( @@ -299,7 +297,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -훅이 완료될 때 발생합니다. `hook_id`를 통해 `hook_triggered`와 연결됩니다. +훅이 완료될 때 발행됩니다. `hook_id`를 통해 `hook_triggered`와 연결됩니다. ```python agenteye.event.hook_completed( @@ -318,7 +316,7 @@ agenteye.event.hook_completed( ### `event.error()` -처리되지 않은 오류가 발생할 때 방출됩니다. +처리되지 않은 오류가 발생할 때 발행됩니다. ```python agenteye.event.error( @@ -332,13 +330,13 @@ agenteye.event.error( --- -## 사람 개입 이벤트 +## 사람 참여(Human-in-the-Loop) 이벤트 -사람 개입 이벤트는 사람이 에이전트 실행에 개입하는 순간(승인 대기, 입력 제공, 일시 중지, 에이전트 중단)에 대한 감시 기능을 제공합니다. 이를 통해 사람이 응답하는 데 걸리는 시간을 측정하고(SDK가 쌍을 이루는 이벤트에서 `duration_ms`를 자동으로 계산), 누가 에이전트를 일시 중지하거나 중단했는지 감사하며, 대시보드에 표시되는 승인 및 감시 워크플로우를 구축할 수 있습니다. +사람 참여 이벤트는 사람이 에이전트 실행에 개입하는 순간(승인 대기, 입력 제공, 일시 중지, 에이전트 중단)에 대한 감독 기능을 제공합니다. 이를 통해 사람이 응답하는 데 걸린 시간을 측정하고(SDK가 페어 이벤트의 `duration_ms`를 자동 계산), 누가 에이전트를 일시 중지하거나 중단했는지 감사하며, 대시보드에 표시되는 승인 및 감독 워크플로우를 구축할 수 있습니다. ### `event.human_wait()` -에이전트가 사람의 입력을 기다리기 위해 실행을 일시 중지할 때 발생합니다. `human_input`과 쌍을 이루며, SDK가 `duration_ms`(사람이 응답하는 데 걸린 시간)를 자동으로 계산합니다. +에이전트가 사람의 입력을 기다리기 위해 실행을 일시 중지할 때 발행됩니다. `human_input`과 쌍을 이루며, SDK가 `duration_ms`(사람이 응답하는 데 걸린 시간)를 자동 계산합니다. ```python agenteye.event.human_wait( @@ -353,7 +351,7 @@ agenteye.event.human_wait( ### `event.human_input()` -사람이 입력을 제공하고 에이전트가 재개될 때 발생합니다. `input_id`를 통해 `human_wait`와 연결됩니다. `duration_ms`는 자동으로 계산되므로 호출자가 전달하면 안 됩니다. +사람이 입력을 제공하고 에이전트가 재개될 때 발행됩니다. `input_id`를 통해 `human_wait`와 연결됩니다. `duration_ms`는 자동으로 계산되므로 호출자가 전달해서는 안 됩니다. ```python agenteye.event.human_input( @@ -367,7 +365,7 @@ agenteye.event.human_input( ### `event.human_pause()` -사람이 에이전트를 능동적으로 일시 중지할 때 발생합니다(예: 대시보드 컨트롤을 통해). 에이전트는 중단되지 않고 일시 중지됩니다. +사람이 에이전트를 능동적으로 일시 중지할 때(예: 대시보드 컨트롤을 통해) 발행됩니다. 에이전트는 중단되지 않고 일시 정지됩니다. ```python agenteye.event.human_pause( @@ -380,7 +378,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -사람이 실행 중인 에이전트를 능동적으로 중단할 때 발생합니다. `human_pause`와 달리 에이전트의 작업이 일시 중지가 아닌 종료됩니다. +사람이 에이전트를 실행 도중 능동적으로 중단할 때 발행됩니다. `human_pause`와 달리, 에이전트의 작업이 일시 정지가 아닌 종료됩니다. ```python agenteye.event.human_interrupt( @@ -394,9 +392,9 @@ agenteye.event.human_interrupt( --- -## 사용자 정의 필드 +## 커스텀 필드 -추가 키워드 인수는 표준 필드 뒤에 이벤트에 추가됩니다: +추가 키워드 인자는 표준 필드 뒤에 이벤트에 추가됩니다: ```python agenteye.event.tool_use( @@ -409,25 +407,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type`, `environment`는 예약된 이름으로, 사용자 정의 필드로 전달하면 `ValueError`가 발생합니다(`Reserved field names cannot be used as custom fields: [...]`). `session_id`와 `agent_id`는 모든 이벤트 메서드의 필수 파라미터이므로 두 번 제공할 수 없으며, 그렇게 하면 Python이 `TypeError`를 발생시킵니다. 환경은 `configure(environment=...)`(또는 `AGENTEYE_ENVIRONMENT` 변수)로 설정하세요. +`timestamp`, `type`, `environment`는 예약된 이름으로, 커스텀 필드로 전달하면 `ValueError`(`Reserved field names cannot be used as custom fields: [...]`)가 발생합니다. `session_id`와 `agent_id`는 모든 이벤트 메서드의 필수 파라미터이므로 두 번 지정할 수 없으며, 중복 지정 시 Python이 `TypeError`를 발생시킵니다. 환경은 `configure(environment=...)`(또는 `AGENTEYE_ENVIRONMENT` 변수)로 설정하세요. + +필드를 나중에 쿼리하려면 페이로드를 구조화된 JSON 형태로 유지하세요. JSON이 기본적으로 지원하지 않는 값(datetime, UUID, decimal, set, bytes, 모델 객체 등)은 문자열로 변환되어 안전하게 기록됩니다. --- ## 이벤트 기록 방식 -이벤트는 프로세스 내에서 버퍼링되고 `flush_interval` 초마다(기본값 500ms) 디스크에 플러시됩니다. 각 플러시는 하나의 JSONL 파일을 생성합니다: +이벤트는 프로세스 내에서 버퍼링되어 `flush_interval`초마다(기본값 500ms) 디스크에 플러시됩니다. 각 플러시는 하나의 JSONL 파일을 생성합니다: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -수집기는 이 디렉터리를 감시하며 파일을 자동으로 업로드합니다. 이 파일들을 직접 관리할 필요는 없습니다. +컬렉터가 이 디렉토리를 감시하며 파일을 자동으로 업로드합니다. 이 파일들을 직접 관리할 필요가 없습니다. -각 파일은 원자적으로 기록됩니다: SDK가 임시 파일에 기록한 뒤 해당 위치로 이름을 변경하므로, 수집기는 절반만 기록된 파일을 볼 수 없습니다. 프로세스가 종료될 때도 최종 플러시가 실행되므로, 마지막 인터벌에 버퍼링된 이벤트는 손실되지 않습니다. 수집기가 오프라인 상태인 경우, 이벤트는 디스크에 파일로 쌓여 있다가 수집기가 복구되면 전송됩니다. +각 파일은 원자적으로 기록됩니다: SDK가 임시 파일에 먼저 쓰고 완료 후 제자리로 이름을 변경하므로, 컬렉터가 절반만 쓰인 파일을 읽는 일이 없습니다. 프로세스 종료 시에도 최종 플러시가 실행되므로 마지막 인터벌에 버퍼링된 이벤트가 손실되지 않습니다. 컬렉터가 오프라인 상태이면 이벤트는 디스크에 파일 형태로 쌓이다가 컬렉터가 복구되는 즉시 전송됩니다. --- ## 다음 단계 -- [이벤트 스트림](/ko/agenteye/event-stream): 이벤트 유형별로 색상이 구분되고 환경, 에이전트, 세션별로 필터링 가능한 실시간 이벤트 도착을 확인하세요. -- [세션](/ko/agenteye/sessions): 쌍을 이루는 이벤트가 각 에이전트 실행을 실행 그래프와 타임라인으로 어떻게 재구성하는지 확인하세요. \ No newline at end of file +- [이벤트 스트림](/ko/agenteye/event-stream): 이벤트 유형별 색상 코딩과 환경·에이전트·세션 필터를 제공하는 실시간 이벤트 스트림을 확인하세요. +- [세션](/ko/agenteye/sessions): 페어 이벤트가 각 에이전트 실행을 실행 그래프와 타임라인으로 재구성하는 방식을 확인하세요. \ No newline at end of file diff --git a/docs/pt-br/agenteye/python-sdk.mdx b/docs/pt-br/agenteye/python-sdk.mdx index 97bdb8e2..31dea23a 100644 --- a/docs/pt-br/agenteye/python-sdk.mdx +++ b/docs/pt-br/agenteye/python-sdk.mdx @@ -1,14 +1,14 @@ --- title: "Python SDK" -description: "Veja exatamente o que seus agentes de IA fizeram em produção: cada execução de agente, chamada de ferramenta, requisição de modelo, hook e intervenção humana." +description: "Veja exatamente o que seus agentes de IA fizeram em produção: cada execução de agente, chamada de ferramenta, requisição ao modelo, hook e intervenção humana." --- -Veja exatamente o que seus agentes de IA fizeram em produção: cada execução de agente, chamada de ferramenta, requisição de modelo, hook e intervenção humana. O Python SDK de Observabilidade do Failproof AI registra esse rastro de dentro do código do seu agente para que você possa depurar, auditar e avaliar o que aconteceu. Use-o sempre que quiser que a Observabilidade do Failproof AI monitore seus agentes. +Veja exatamente o que seus agentes de IA fizeram em produção: cada execução de agente, chamada de ferramenta, requisição ao modelo, hook e intervenção humana. O Python SDK de Observabilidade do Failproof AI registra esse rastro a partir do código do seu agente para que você possa depurar, auditar e avaliar o que aconteceu. Use-o sempre que quiser que a Observabilidade do Failproof AI monitore seus agentes. -Internamente, o SDK grava eventos estruturados em arquivos JSONL locais, e o daemon coletor os captura e os envia automaticamente para a plataforma. Você não precisa gerenciar esses arquivos diretamente. +Por baixo dos panos, o SDK escreve eventos estruturados em arquivos JSONL locais, e o daemon coletor os captura e os envia automaticamente para a plataforma. Você não precisa gerenciar esses arquivos diretamente. -> **Dica:** Está começando com a Observabilidade do Failproof AI? Esta página é a referência completa de eventos do SDK. +> **Dica:** Novo na Observabilidade do Failproof AI? Esta página é a referência completa de eventos do SDK.
@@ -18,15 +18,15 @@ Internamente, o SDK grava eventos estruturados em arquivos JSONL locais, e o dae ## Instalação -O SDK é distribuído aos clientes como um wheel privado, e não por um índice de pacotes público. O processo de onboarding cobre como obtê-lo, instalá-lo e fixar sua versão — fale com seu contato no Failproof AI se precisar de acesso. +O SDK é distribuído aos clientes como um wheel privado, e não por meio de um índice de pacotes público. O processo de onboarding cobre como obtê-lo, instalá-lo e fixar sua versão — fale com seu contato do Failproof AI se precisar de acesso. -Depois de instalado, confirme que está disponível: +Após a instalação, confirme que ele está disponível: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Prefere deixar um agente de código fazer toda a integração? O [Python SDK Agent Skill](/pt-br/agenteye/python-sdk-skill) conhece o caminho de instalação, planeja os pontos de instrumentação, os implementa e verifica se os eventos chegam corretamente. +Prefere deixar um agente de codificação fazer toda a integração? A [Python SDK Agent Skill](/pt-br/agenteye/python-sdk-skill) conhece o caminho de instalação, planeja os pontos de instrumentação, os implementa e verifica se os eventos chegam corretamente. --- @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### Instrumentando uma chamada real -Na prática, você envolve o código do agente existente. Delimite uma chamada de modelo com `model_request` antes e `model_response` depois, para que os dois eventos abranjam a requisição real e a Observabilidade do Failproof AI possa correlacioná-los: +Na prática, você envolve seu código de agente existente. Enquadre uma chamada ao modelo com `model_request` antes e `model_response` depois, para que os dois eventos abranjam a requisição real e a Observabilidade do Failproof AI possa correlacioná-los: ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -Envolva chamadas de ferramentas da mesma forma com `tool_use` e `tool_result`, reutilizando um único `tool_call_id` para o par. +Envolva as chamadas de ferramentas da mesma forma com `tool_use` e `tool_result`, reutilizando o mesmo `tool_call_id` no par. -Veja como esses eventos ficam no dashboard, com código de cores por tipo e filtráveis por ambiente, agente e sessão: +Veja como esses eventos aparecem no dashboard, com codificação de cores por tipo e filtráveis por ambiente, agente e sessão: -![O stream de eventos ao vivo, com código de cores por tipo de evento e filtráveis por ambiente, agente e sessão](/agenteye/images/events-stream.png) +![O stream de eventos ao vivo, com codificação de cores por tipo de evento e filtrável por ambiente, agente e sessão](/agenteye/images/events-stream.png) --- @@ -113,18 +113,18 @@ agenteye.configure( ) ``` -Chame uma vez antes de qualquer chamada a `event.*`. Pode ser omitido com segurança; os padrões funcionam imediatamente. Todos os argumentos são somente por palavra-chave; passe-os pelo nome conforme mostrado acima. +Chame uma vez antes de qualquer chamada `event.*`. É seguro omitir; os valores padrão funcionam sem configuração adicional. Todos os argumentos são somente por nome de chave; passe-os pelo nome conforme mostrado acima. -Quando `base_dir` é `None` (o padrão), o SDK lê `$AGENTEYE_HOME` se definido, -caso contrário usa `~/.agenteye`. Isso corresponde à resolução do próprio coletor, -portanto uma única variável de ambiente `AGENTEYE_HOME` configura o spool de eventos -compartilhado tanto para o SDK quanto para o coletor. +Quando `base_dir` é `None` (o padrão), o SDK lê `$AGENTEYE_HOME` se estiver definido, +caso contrário recorre a `~/.agenteye`. Isso corresponde à própria resolução do coletor, +então uma única variável de ambiente `AGENTEYE_HOME` configura o spool de eventos compartilhado +tanto para o SDK quanto para o coletor. --- ## Ambiente -Rotule cada evento com um ambiente de implantação (`production`, `staging`, `qa`, `canary`, etc.). Defina uma vez; o SDK o anexa a cada evento automaticamente. +Rotule cada evento com um ambiente de implantação (`production`, `staging`, `qa`, `canary`, etc.). Defina uma vez; o SDK o anexa a todos os eventos automaticamente. **Opção 1: via `configure()`:** @@ -138,33 +138,33 @@ agenteye.configure(environment="production") export AGENTEYE_ENVIRONMENT=production ``` -**Prioridade:** `configure(environment=...)` tem precedência sobre a variável de ambiente. Se nenhum dos dois estiver definido, o padrão é `"dev"`. +**Prioridade:** `configure(environment=...)` tem precedência sobre a variável de ambiente. Se nenhum dos dois for definido, o padrão é `"dev"`. O valor do ambiente aparece como um filtro de primeira classe no dashboard e é armazenado no servidor para consultas rápidas. -> **Aviso:** Os valores de ambiente não devem conter uma vírgula literal `,`. Os filtros do dashboard usam seleção múltipla separada por vírgulas na requisição (`?environment=prod,staging`), portanto um ambiente chamado `prod,blue` seria dividido em dois valores. Eventos com ambientes contendo vírgulas são rejeitados no momento da ingestão. +> **Aviso:** Os valores de ambiente não devem conter uma vírgula `,` literal. Os filtros do dashboard usam seleção múltipla separada por vírgulas na requisição (`?environment=prod,staging`), então um ambiente chamado `prod,blue` seria dividido em dois valores. Eventos com ambientes contendo vírgulas são rejeitados no momento da ingestão. --- ## Dados e privacidade -O SDK registra apenas os campos que você passa explicitamente. Prompts, mensagens, entradas e saídas de ferramentas, e conteúdo de modelo são capturados exclusivamente porque você os entrega a uma chamada `event.*`. Nada é lido do seu processo ou capturado implicitamente. Qualquer campo que você deixar sem definir é omitido do evento completamente; ele não é gravado em disco. +O SDK registra apenas os campos que você passa explicitamente. Prompts, mensagens, entradas e saídas de ferramentas e conteúdo do modelo são capturados somente porque você os entrega a uma chamada `event.*`. Nada é lido do seu processo ou capturado implicitamente. Qualquer campo que você deixar sem definir é omitido do evento completamente; ele não é gravado em disco. -Isso torna a redação sua escolha e sua responsabilidade. Se um prompt ou payload de ferramenta contiver PII ou segredos que você preferiria não armazenar, remova ou mascare-os antes de passá-los ao método de evento. +Isso torna a redação sua escolha e sua responsabilidade. Se um prompt ou payload de ferramenta contiver PII ou segredos que você prefere não armazenar, filtre ou mascare-os antes de passá-los ao método de evento. --- ## Referência de Eventos -A maioria dos eventos vem em pares início/fim que compartilham um ID de correlação: `tool_use` e `tool_result` compartilham um `tool_call_id`, `hook_triggered` e `hook_completed` compartilham um `hook_id`, e `human_wait` e `human_input` compartilham um `input_id`. Emita o evento de início, execute o trabalho e, em seguida, emita o evento de fim com o mesmo ID. A Observabilidade do Failproof AI correlaciona o par e calcula `duration_ms` para você, portanto você nunca passa `duration_ms` diretamente. +A maioria dos eventos vem em pares início/fim que compartilham um ID de correlação: `tool_use` e `tool_result` compartilham um `tool_call_id`, `hook_triggered` e `hook_completed` compartilham um `hook_id`, e `human_wait` e `human_input` compartilham um `input_id`. Emita o evento de início, execute o trabalho e então emita o evento de fim com o mesmo ID. A Observabilidade do Failproof AI correlaciona o par e calcula `duration_ms` para você, então você nunca passa `duration_ms` diretamente. -![O gráfico de execução no estilo git de uma sessão ao lado de sua linha do tempo de eventos, reconstruído a partir dos eventos pareados, com o painel de detalhamento ferramenta/modelo/hook](/agenteye/images/session-detail.png) +![O grafo de execução no estilo git de uma sessão ao lado de sua linha do tempo de eventos, reconstruído a partir dos eventos pareados, com o painel de detalhamento ferramenta/modelo/hook](/agenteye/images/session-detail.png) -Todos os métodos de evento exigem estes dois campos: +Todos os métodos de evento requerem estes dois campos: | Campo | Tipo | Descrição | |---|---|---| -| `session_id` | `str` | Identifica a execução do agente de nível superior | +| `session_id` | `str` | Identifica a execução de agente de nível superior | | `agent_id` | `str` | Identifica qual agente dentro da sessão emitiu o evento | Todos os métodos também aceitam `**kwargs` arbitrários para metadados personalizados (consulte [Campos Personalizados](#custom-fields)). @@ -173,7 +173,7 @@ Todos os métodos também aceitam `**kwargs` arbitrários para metadados persona ### `event.agent_start()` -Emitido quando um agente inicia seu trabalho. +Emitido quando um agente começa a trabalhar. ```python agenteye.event.agent_start( @@ -188,7 +188,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Emitido quando um agente conclui seu trabalho. +Emitido quando um agente termina seu trabalho. ```python agenteye.event.agent_end( @@ -203,7 +203,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -Emitido quando um agente invoca uma ferramenta. Pare com `tool_result`; o SDK calcula `duration_ms` automaticamente. +Emitido quando um agente invoca uma ferramenta. Pareie com `tool_result`; o SDK calcula `duration_ms` automaticamente. ```python agenteye.event.tool_use( @@ -237,7 +237,7 @@ agenteye.event.tool_result( ### `event.model_request()` -Emitido logo antes de enviar um prompt para um LLM. +Emitido imediatamente antes de enviar um prompt a um LLM. ```python agenteye.event.model_request( @@ -254,7 +254,7 @@ agenteye.event.model_request( ) ``` -As entradas de `messages` aceitam tanto um `content` em string simples quanto um `content` no estilo lista-de-blocos do Anthropic. Parâmetros de amostragem (`temperature`, `max_tokens`, etc.) podem ser passados como kwargs extras. +As entradas de `messages` aceitam tanto uma `content` como string simples quanto `content` no estilo Anthropic como lista de blocos. Parâmetros de amostragem (`temperature`, `max_tokens`, etc.) podem ser passados como kwargs extras. --- @@ -283,7 +283,7 @@ agenteye.event.model_response( ### `event.hook_triggered()` -Emitido quando um hook é acionado. Pare com `hook_completed`; o SDK calcula `duration_ms` automaticamente. +Emitido quando um hook é acionado. Pareie com `hook_completed`; o SDK calcula `duration_ms` automaticamente. ```python agenteye.event.hook_triggered( @@ -300,7 +300,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Emitido quando um hook é concluído. Correlaciona com `hook_triggered` via `hook_id`. +Emitido quando um hook termina. Correlaciona com `hook_triggered` via `hook_id`. ```python agenteye.event.hook_completed( @@ -319,7 +319,7 @@ agenteye.event.hook_completed( ### `event.error()` -Emitido quando um erro não tratado ocorre. +Emitido quando ocorre um erro não tratado. ```python agenteye.event.error( @@ -333,13 +333,13 @@ agenteye.event.error( --- -## Eventos de Humano no Loop +## Eventos de Humano no Ciclo -Os eventos de humano no loop oferecem visibilidade sobre os momentos em que uma pessoa intervém na execução do agente (aguardando aprovação, fornecendo entrada, pausando ou interrompendo o agente). Eles permitem medir quanto tempo os humanos levam para responder (o SDK calcula `duration_ms` automaticamente nos eventos pareados), auditar quem pausou ou interrompeu um agente, e construir fluxos de trabalho de aprovação e supervisão que aparecem no dashboard. +Os eventos de humano no ciclo (human-in-the-loop) oferecem supervisão sobre os momentos em que uma pessoa intervém na execução do agente (aguardando aprovação, fornecendo entrada, pausando ou interrompendo o agente). Eles permitem medir quanto tempo os humanos levam para responder (o SDK calcula `duration_ms` automaticamente nos eventos pareados), auditar quem pausou ou interrompeu um agente, e construir fluxos de trabalho de aprovação e supervisão que aparecem no dashboard. ### `event.human_wait()` -Emitido quando o agente pausa a execução para aguardar que um humano forneça entrada. Pare com `human_input`; o SDK calcula `duration_ms` automaticamente (quanto tempo o humano levou para responder). +Emitido quando o agente pausa a execução para aguardar que um humano forneça entrada. Pareie com `human_input`; o SDK calcula `duration_ms` automaticamente (quanto tempo o humano levou para responder). ```python agenteye.event.human_wait( @@ -368,7 +368,7 @@ agenteye.event.human_input( ### `event.human_pause()` -Emitido quando um humano pausa ativamente o agente (por exemplo, via um controle no dashboard). O agente é suspenso, mas não encerrado. +Emitido quando um humano pausa ativamente o agente (por exemplo, via controle no dashboard). O agente é suspenso, mas não encerrado. ```python agenteye.event.human_pause( @@ -381,7 +381,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -Emitido quando um humano para ativamente o agente no meio da execução. Ao contrário de `human_pause`, o trabalho do agente é encerrado em vez de suspenso. +Emitido quando um humano para ativamente o agente durante a execução. Diferente de `human_pause`, o trabalho do agente é encerrado em vez de suspenso. ```python agenteye.event.human_interrupt( @@ -397,7 +397,7 @@ agenteye.event.human_interrupt( ## Campos Personalizados -Quaisquer argumentos de palavra-chave extras são anexados ao evento após os campos padrão: +Quaisquer argumentos de palavra-chave extras são acrescentados ao evento após os campos padrão: ```python agenteye.event.tool_use( @@ -410,25 +410,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` e `environment` são reservados e lançam `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) se passados como campos personalizados. `session_id` e `agent_id` são parâmetros obrigatórios em cada método de evento e não podem ser fornecidos uma segunda vez; o Python lança `TypeError` se isso ocorrer. Defina o ambiente com `configure(environment=...)` (ou a variável `AGENTEYE_ENVIRONMENT`) em vez disso. +`timestamp`, `type` e `environment` são reservados e geram `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) se passados como campos personalizados. `session_id` e `agent_id` são parâmetros obrigatórios em todos os métodos de evento e não podem ser fornecidos uma segunda vez; o Python gera `TypeError` se você tentar. Defina o ambiente com `configure(environment=...)` (ou a variável `AGENTEYE_ENVIRONMENT`) em vez disso. + +Mantenha os payloads como JSON estruturado quando quiser consultar seus campos. Valores que o JSON não suporta nativamente — como datetimes, UUIDs, decimais, sets, bytes ou objetos de modelo — são convertidos para strings para que o registro continue com segurança. --- ## Como os Eventos São Gravados -Os eventos são armazenados em buffer no processo e liberados para disco a cada `flush_interval` segundos (padrão: 500 ms). Cada liberação grava um arquivo JSONL: +Os eventos são armazenados em buffer no processo e descarregados em disco a cada `flush_interval` segundos (padrão: 500 ms). Cada descarga grava um arquivo JSONL: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -O coletor monitora esse diretório e faz o upload dos arquivos automaticamente. Você não precisa gerenciar esses arquivos diretamente. +O coletor monitora este diretório e faz o upload dos arquivos automaticamente. Você não precisa gerenciar esses arquivos diretamente. -Cada arquivo é gravado atomicamente: o SDK grava em um arquivo temporário e depois o renomeia para o local correto, portanto o coletor nunca vê um arquivo gravado pela metade. Uma liberação final também é executada quando o processo é encerrado, para que os eventos armazenados em buffer no último intervalo não sejam perdidos. Se o coletor estiver offline, os eventos simplesmente se acumulam como arquivos em disco e são enviados assim que ele retornar. +Cada arquivo é gravado atomicamente: o SDK escreve em um arquivo temporário e então o renomeia para o local final, de modo que o coletor nunca veja um arquivo gravado pela metade. Uma descarga final também é executada quando seu processo sai, para que os eventos armazenados em buffer no último intervalo não sejam perdidos. Se o coletor estiver offline, os eventos simplesmente se acumulam como arquivos em disco e são enviados assim que ele voltar. --- ## Próximos passos -- [Stream de eventos](/pt-br/agenteye/event-stream): acompanhe esses eventos chegando ao vivo, com código de cores e filtráveis por ambiente, agente e sessão. -- [Sessões](/pt-br/agenteye/sessions): veja como os eventos pareados reconstroem cada execução de agente como um gráfico de execução e linha do tempo. \ No newline at end of file +- [Stream de eventos](/pt-br/agenteye/event-stream): acompanhe esses eventos chegando ao vivo, com codificação de cores e filtrável por ambiente, agente e sessão. +- [Sessões](/pt-br/agenteye/sessions): veja como os eventos pareados reconstroem cada execução de agente como um grafo de execução e linha do tempo. \ No newline at end of file diff --git a/docs/ru/agenteye/python-sdk.mdx b/docs/ru/agenteye/python-sdk.mdx index 1db497bb..552dd767 100644 --- a/docs/ru/agenteye/python-sdk.mdx +++ b/docs/ru/agenteye/python-sdk.mdx @@ -1,12 +1,12 @@ --- title: "Python SDK" -description: "Узнайте ровно, что делали ваши AI-агенты в production: каждый запуск агента, вызов инструмента, запрос модели, хук и человеческое вмешательство." +description: "Смотрите точно, что делали ваши AI-агенты в production: каждый запуск агента, вызов инструмента, запрос к модели, хук и человеческое вмешательство." --- -Узнайте ровно, что делали ваши AI-агенты в production: каждый запуск агента, вызов инструмента, запрос модели, хук и человеческое вмешательство. Failproof AI Observability Python SDK записывает этот след изнутри кода вашего агента, чтобы вы могли отлаживать, проверять и оценивать происходящее. Используйте его всякий раз, когда хотите, чтобы Failproof AI Observability отслеживал ваши агенты. +Смотрите точно, что делали ваши AI-агенты в production: каждый запуск агента, вызов инструмента, запрос к модели, хук и человеческое вмешательство. Failproof AI Observability Python SDK записывает эту цепь событий изнутри кода вашего агента, чтобы вы могли отлаживать, аудировать и оценивать происходящее. Используйте его каждый раз, когда хотите, чтобы Failproof AI Observability наблюдал за вашими агентами. -Под капотом SDK записывает структурированные события в локальные JSONL-файлы, а демон сборщика подхватывает их и автоматически отправляет их на платформу. Вам не нужно самостоятельно управлять этими файлами. +Под капотом SDK записывает структурированные события в локальные JSONL файлы, а демон сборщика подхватывает их и автоматически отправляет на платформу. Вы сами не управляете этими файлами. > **Совет:** Новичок в Failproof AI Observability? Эта страница — полный справочник событий SDK. @@ -18,15 +18,15 @@ description: "Узнайте ровно, что делали ваши AI-аге ## Установка -SDK распространяется клиентам как приватный wheel, а не из публичного индекса пакетов. Ваш процесс подключения содержит инструкции по его получению, установке и закреплению версии — обратитесь к контакту Failproof AI, если вам нужен доступ. +SDK распространяется клиентам как приватный wheel вместо публичного индекса пакетов. Информация о том, как его получить, установить и закрепить версию, описана в вашем onboarding — обратитесь к контакту Failproof AI, если вам нужен доступ. -Проверьте, что он установлен: +После установки убедитесь в её успехе: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Хотите, чтобы кодирующий агент провел всю интеграцию? [Python SDK Agent Skill](/ru/agenteye/python-sdk-skill) знает путь установки, планирует точки инструментирования, записывает их и проверяет, что события попадают. +Хотите предоставить это делать кодирующему агенту? [Python SDK Agent Skill](/ru/agenteye/python-sdk-skill) знает путь установки, планирует точки инструментирования, пишет их и проверяет, что события доходят. --- @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### Инструментирование реального вызова -На практике вы оборачиваете существующий код агента. Заключите вызов модели между `model_request` до и `model_response` после, чтобы два события охватывали реальный запрос и Failproof AI Observability мог их связать: +На практике вы оборачиваете ваш существующий код агента. Заключите вызов модели между `model_request` до и `model_response` после, чтобы два события охватывали реальный запрос и Failproof AI Observability мог их сопоставить: ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -Оборачивайте вызовы инструментов аналогично: `tool_use` и `tool_result`, переиспользуя один `tool_call_id` в паре. +Оборачивайте вызовы инструментов так же с помощью `tool_use` и `tool_result`, переиспользуя один и тот же `tool_call_id` для обеих событий. -Вот как выглядят эти события в панели управления, окрашенные по типам и фильтруемые по окружению, агенту и сеансу: +Вот как выглядят эти события на панели управления — раскрашены по типам и фильтруются по окружению, агенту и сеансу: -![Поток живых событий, окрашенный по типам событий и фильтруемый по окружению, агенту и сеансу](/agenteye/images/events-stream.png) +![Живой поток событий Events, раскрашенный по типам событий и фильтруемый по окружению, агенту и сеансу](/agenteye/images/events-stream.png) --- @@ -108,23 +108,23 @@ agenteye.event.model_response( ```python agenteye.configure( base_dir=None, # Path | str | None. По умолчанию: $AGENTEYE_HOME или ~/.agenteye - flush_interval=0.5, # float, секунды между циклами сброса - environment=None, # str | None. Метка окружения развертывания + flush_interval=0.5, # float, секунды между циклами очистки + environment=None, # str | None. Метка окружения развёртывания ) ``` -Вызовите один раз перед любым вызовом `event.*`. Безопасно опустить; значения по умолчанию работают из коробки. Все аргументы только именованные; передавайте их по имени, как показано выше. +Вызовите один раз перед любым вызовом `event.*`. Безопасно опустить; значения по умолчанию работают из коробки. Все аргументы только с именованием; передавайте их по имени, как показано выше. -Когда `base_dir` имеет значение `None` (по умолчанию), SDK читает `$AGENTEYE_HOME`, если он установлен, +Если `base_dir` — `None` (по умолчанию), SDK читает `$AGENTEYE_HOME`, если установлен, иначе возвращается к `~/.agenteye`. Это совпадает с собственным разрешением сборщика, -поэтому одна переменная среды `AGENTEYE_HOME` настраивает общую очередь событий для -SDK и сборщика. +поэтому одна переменная окружения `AGENTEYE_HOME` конфигурирует общий очередь событий для SDK +и сборщика. --- ## Окружение -Обозначьте каждое событие окружением развертывания (`production`, `staging`, `qa`, `canary` и т. д.). Установите один раз; SDK автоматически прикрепляет его к каждому событию. +Помечайте каждое событие окружением развёртывания (`production`, `staging`, `qa`, `canary` и т. д.). Установите один раз; SDK автоматически прикрепляет его к каждому событию. **Вариант 1: через `configure()`:** @@ -132,40 +132,40 @@ SDK и сборщика. agenteye.configure(environment="production") ``` -**Вариант 2: через переменную среды:** +**Вариант 2: через переменную окружения:** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**Приоритет:** `configure(environment=...)` победит переменную среды. Если ни один не установлен, по умолчанию — `"dev"`. +**Приоритет:** `configure(environment=...)` имеет приоритет над переменной окружения. Если ничего не установлено, по умолчанию — `"dev"`. -Значение окружения отображается как фильтр первого класса в панели управления и хранится на сервере для быстрых запросов. +Значение окружения появляется как фильтр первого уровня в панели управления и хранится на сервере для быстрых запросов. -> **Предупреждение:** Значения окружения не должны содержать буквальную запятую `,`. Фильтры панели управления используют многовыборочную запятой разделенные значения на проводе (`?environment=prod,staging`), поэтому окружение с названием `prod,blue` будет разделено на два значения. События с окружениями, содержащими запятые, отклоняются при приеме. +> **Предупреждение:** Значения окружения не должны содержать буквальную запятую `,`. Фильтры панели управления используют множественный выбор через запятую на уровне протокола (`?environment=prod,staging`), поэтому окружение с именем `prod,blue` было бы разделено на два значения. События с окружениями, содержащими запятые, отклоняются при приёме. --- ## Данные и конфиденциальность -SDK записывает только поля, которые вы явно передаете. Подсказки, сообщения, входные и выходные данные инструментов, а также содержимое модели захватываются только потому, что вы передаете их вызову `event.*`. Ничто не читается из вашего процесса и не захватывается неявно. Любое поле, которое вы не установили, полностью пропускается из события; оно не записывается на диск. +SDK записывает только те поля, которые вы явно передали. Подсказки, сообщения, входные и выходные данные инструментов, содержимое модели захватываются исключительно потому, что вы их передали в вызов `event.*`. Ничего не считывается из вашего процесса и не захватывается неявно. Любое поле, которое вы не устанавливали, полностью опускается из события; оно не записывается на диск. -Это делает редактирование вашей ответственностью и вашим выбором. Если подсказка или полезная нагрузка инструмента содержит PII или секреты, которые вы предпочитаете не хранить, очистите или замаскируйте их перед передачей методу события. +Это делает редактирование вашим выбором и вашей ответственностью. Если подсказка или полезная нагрузка инструмента содержит PII или секреты, которые вы предпочли бы не сохранять, удалите или замаскируйте их перед передачей в метод события. --- ## Справочник событий -Большинство событий поступают в парах начала/конца, которые имеют общий ID корреляции: `tool_use` и `tool_result` имеют `tool_call_id`, `hook_triggered` и `hook_completed` имеют `hook_id`, а `human_wait` и `human_input` имеют `input_id`. Испустите начальное событие, выполните работу, затем испустите конечное событие с тем же ID. Failproof AI Observability сопоставляет пару и вычисляет `duration_ms` для вас, поэтому вы никогда не передаете `duration_ms` самостоятельно. +Большинство событий идут парами старт/конец, которые делят ID корреляции: `tool_use` и `tool_result` делят `tool_call_id`, `hook_triggered` и `hook_completed` делят `hook_id`, и `human_wait` и `human_input` делят `input_id`. Отправьте стартовое событие, сделайте работу, затем отправьте конечное событие с тем же ID. Failproof AI Observability сопоставляет пару и вычисляет `duration_ms` для вас, поэтому вы никогда не передаёте `duration_ms` сами. -![График выполнения сеанса в git-подобном стиле рядом с его шкалой времени событий, восстановленной из парных событий, с панелью разбиения инструмента/модели/хука](/agenteye/images/session-detail.png) +![График исполнения сеанса в стиле git рядом с его временной шкалой событий, восстановленные из парных событий, с разбивкой по инструментам/модели/хукам](/agenteye/images/session-detail.png) Все методы событий требуют эти два поля: | Поле | Тип | Описание | |---|---|---| | `session_id` | `str` | Идентифицирует запуск агента верхнего уровня | -| `agent_id` | `str` | Идентифицирует, какой агент в сеансе испустил событие | +| `agent_id` | `str` | Идентифицирует, какой агент в сеансе отправил событие | Все методы также принимают произвольные `**kwargs` для пользовательских метаданных (см. [Пользовательские поля](#пользовательские-поля)). @@ -173,14 +173,14 @@ SDK записывает только поля, которые вы явно п ### `event.agent_start()` -Испускается, когда агент начинает работу. +Отправляется, когда агент начинает работу. ```python agenteye.event.agent_start( session_id="run-001", agent_id="planner", goal="answer user query", # str | None - parent_id=None, # str | None - parent_id для вложенных агентов + parent_id=None, # str | None - parent agent_id для вложенных агентов ) ``` @@ -188,7 +188,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Испускается, когда агент завершает работу. +Отправляется, когда агент завершает работу. ```python agenteye.event.agent_end( @@ -203,14 +203,14 @@ agenteye.event.agent_end( ### `event.tool_use()` -Испускается, когда агент вызывает инструмент. Сопоставьте с `tool_result`; SDK автоматически вычисляет `duration_ms`. +Отправляется, когда агент вызывает инструмент. Сопаруйте с `tool_result`; SDK автоматически вычисляет `duration_ms`. ```python agenteye.event.tool_use( session_id="run-001", agent_id="planner", - tool_name="web_search", # str, обязательно - tool_call_id="toolu_01", # str, обязательно - ключ корреляции для сопоставления tool_result + tool_name="web_search", # str, обязательное + tool_call_id="toolu_01", # str, обязательное - ключ корреляции для соответствующего tool_result input={"query": "..."}, # dict | None ) ``` @@ -219,7 +219,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -Испускается, когда инструмент возвращает результат. Соотносится с `tool_use` через `tool_call_id`. +Отправляется, когда инструмент возвращает результат. Коррелирует с `tool_use` через `tool_call_id`. ```python agenteye.event.tool_result( @@ -228,7 +228,7 @@ agenteye.event.tool_result( tool_name="web_search", tool_call_id="toolu_01", # должен совпадать с предыдущим tool_use output={"results": ["..."]}, # Any | None - error=None, # str | None - установить, если инструмент вызвал исключение + error=None, # str | None - установите, если инструмент вызвал ошибку # duration_ms вычисляется автоматически - не передавайте его ) ``` @@ -237,14 +237,14 @@ agenteye.event.tool_result( ### `event.model_request()` -Испускается непосредственно перед отправкой подсказки в LLM. +Отправляется непосредственно перед отправкой подсказки на LLM. ```python agenteye.event.model_request( session_id="run-001", agent_id="planner", model="claude-sonnet-4-6", # str | None - любая строка провайдера/модели; не валидируется - messages=[ # list[dict] | None - ходы беседы + messages=[ # list[dict] | None - раунды беседы {"role": "user", "content": "..."}, ], system="You are helpful.", # Any | None - str или список блоков содержимого @@ -254,13 +254,13 @@ agenteye.event.model_request( ) ``` -Записи `messages` принимают либо простое строковое `content`, либо Anthropic-подобный список блоков `content`. Параметры выборки (`temperature`, `max_tokens` и т. д.) могут быть переданы как дополнительные kwargs. +Записи `messages` принимают либо простую строку `content`, либо Anthropic-подобный список блоков `content`. Параметры выборки (`temperature`, `max_tokens` и т. д.) можно передать как дополнительные kwargs. --- ### `event.model_response()` -Испускается, когда LLM возвращает ответ. +Отправляется, когда LLM возвращает ответ. ```python agenteye.event.model_response( @@ -270,27 +270,27 @@ agenteye.event.model_response( stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None - content=[ # Any | None - str или список блоков содержимого в стиле Anthropic + content=[ # Any | None - str или список блоков содержимого Anthropic-подобного типа {"type": "text", "text": "..."}, ], role="assistant", # str | None ) ``` -`content` принимает либо простую строку (универсальные провайдеры), либо список блоков содержимого в стиле Anthropic. Вызовы инструментов живут внутри `content` как блоки `{"type": "tool_use", ...}`, без отдельного поля `tool_calls`. +`content` принимает либо простую строку (для универсальных провайдеров), либо список блоков содержимого подобно Anthropic. Вызовы инструментов находятся внутри `content` как блоки `{"type": "tool_use", ...}` без отдельного поля `tool_calls`. --- ### `event.hook_triggered()` -Испускается, когда срабатывает хук. Сопоставьте с `hook_completed`; SDK автоматически вычисляет `duration_ms`. +Отправляется, когда срабатывает хук. Сопаруйте с `hook_completed`; SDK автоматически вычисляет `duration_ms`. ```python agenteye.event.hook_triggered( session_id="run-001", agent_id="planner", - hook_name="pre_tool_use", # str, обязательно - hook_id="hook-abc", # str, обязательно - ключ корреляции + hook_name="pre_tool_use", # str, обязательное + hook_id="hook-abc", # str, обязательное - ключ корреляции trigger_event="tool_use", # str | None input={"tool": "search"}, # Any | None ) @@ -300,7 +300,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Испускается, когда хук завершается. Соотносится с `hook_triggered` через `hook_id`. +Отправляется, когда хук завершает работу. Коррелирует с `hook_triggered` через `hook_id`. ```python agenteye.event.hook_completed( @@ -319,48 +319,48 @@ agenteye.event.hook_completed( ### `event.error()` -Испускается, когда происходит необработанная ошибка. +Отправляется при возникновении необработанной ошибки. ```python agenteye.event.error( session_id="run-001", agent_id="planner", - error_type="TimeoutError", # str, обязательно - message="timed out", # str, обязательно + error_type="TimeoutError", # str, обязательное + message="timed out", # str, обязательное traceback="Traceback...", # str | None ) ``` --- -## События с участием человека +## События человека в цикле -События с участием человека дают вам контроль над моментами, когда человек вмешивается в выполнение агента (ожидание одобрения, ввод данных, приостановка или остановка агента). Они позволяют измерить, сколько времени люди тратят на ответ (SDK автоматически вычисляет `duration_ms` на парных событиях), проверить, кто приостановил или прервал агента, и создавать рабочие процессы одобрения и контроля, которые отображаются на панели управления. +События человека в цикле дают вам надзор над моментами, когда человек вступает в исполнение агента (ожидание одобрения, предоставление входных данных, пауза или остановка агента). Они позволяют вам измерять, сколько времени люди тратят на ответ (SDK автоматически вычисляет `duration_ms` на парных событиях), аудировать, кто сделал паузу или прервал агента, и строить рабочие процессы одобрения и надзора, которые отображаются в панели управления. ### `event.human_wait()` -Испускается, когда агент приостанавливает выполнение в ожидании ввода человека. Сопоставьте с `human_input`; SDK автоматически вычисляет `duration_ms` (как долго человек отвечал). +Отправляется, когда агент приостанавливает исполнение в ожидании, пока человек предоставит входные данные. Сопаруйте с `human_input`; SDK автоматически вычисляет `duration_ms` (как долго человек ждал, чтобы ответить). ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, обязательно - ключ корреляции для сопоставления human_input - prompt="Do you approve this action?", # str | None - вопрос, показываемый человеку - options=["approve", "reject", "defer"], # list[str] | None - варианты, предоставляемые человеку - reason="approval_required", # str | None - почему агент ждет + input_id="inp-abc", # str, обязательное - ключ корреляции для соответствующего human_input + prompt="Do you approve this action?", # str | None - вопрос, показанный человеку + options=["approve", "reject", "defer"], # list[str] | None - варианты, представленные человеку + reason="approval_required", # str | None - почему агент ждёт ) ``` ### `event.human_input()` -Испускается, когда человек предоставляет ввод и агент возобновляет работу. Соотносится с `human_wait` через `input_id`. `duration_ms` вычисляется автоматически и не должен быть передан вызывающей стороной. +Отправляется, когда человек предоставляет входные данные и агент возобновляет работу. Коррелирует с `human_wait` через `input_id`. `duration_ms` вычисляется автоматически и не должен передаваться вызывающей стороной. ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, обязательно - должен совпадать с предыдущим human_wait + input_id="inp-abc", # str, обязательное - должен совпадать с предыдущим human_wait response="approve", # str | None - ответ человека (свободный текст или выбранный вариант) # duration_ms вычисляется автоматически - не передавайте его ) @@ -368,20 +368,20 @@ agenteye.event.human_input( ### `event.human_pause()` -Испускается, когда человек активно приостанавливает агента (например, через элемент управления панели управления). Агент приостановлен, но не завершен. +Отправляется, когда человек активно ставит агента на паузу (напр. через элемент управления панели управления). Агент приостанавливается, но не завершается. ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - кто приостановил агента + user_id="usr_42", # str | None - кто сделал паузу агента ) ``` ### `event.human_interrupt()` -Испускается, когда человек активно останавливает агента во время выполнения. В отличие от `human_pause`, работа агента завершается, а не приостанавливается. +Отправляется, когда человек активно останавливает агента во время исполнения. В отличие от `human_pause`, работа агента завершается, а не приостанавливается. ```python agenteye.event.human_interrupt( @@ -397,7 +397,7 @@ agenteye.event.human_interrupt( ## Пользовательские поля -Любые дополнительные именованные аргументы добавляются к событию после стандартных полей: +Любые дополнительные аргументы ключевого слова добавляются к событию после стандартных полей: ```python agenteye.event.tool_use( @@ -410,25 +410,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` и `environment` зарезервированы и вызывают `ValueError` (если переданы как пользовательские поля. `session_id` и `agent_id` — обязательные параметры для каждого метода события и не могут быть поданы второй раз; Python вызовет `TypeError`, если вы это сделаете. Вместо этого установите окружение с помощью `configure(environment=...)` (или переменной `AGENTEYE_ENVIRONMENT`). +`timestamp`, `type` и `environment` зарезервированы и вызывают `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) при передаче как пользовательские поля. `session_id` и `agent_id` — обязательные параметры в каждом методе события и не могут быть предоставлены второй раз; Python вызывает `TypeError`, если вы это сделаете. Установите окружение с помощью `configure(environment=...)` (или переменной `AGENTEYE_ENVIRONMENT`) вместо этого. + +Сохраняйте полезные нагрузки как структурированный JSON, когда хотите запрашивать их поля. Значения, которые JSON не поддерживает в нативном виде, такие как даты/время, UUID, десятичные числа, наборы, байты или объекты модели, преобразуются в строки, чтобы запись продолжалась безопасно. --- ## Как записываются события -События буферизируются в процессе и сбрасываются на диск каждые `flush_interval` секунд (по умолчанию 500 мс). Каждый сброс записывает один JSONL-файл: +События буферизируются в процессе и очищаются на диск каждые `flush_interval` секунд (по умолчанию 500 мс). Каждая очистка записывает один JSONL файл: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -Сборщик отслеживает этот каталог и автоматически загружает файлы. Вам не нужно напрямую управлять этими файлами. +Сборщик следит за этим каталогом и автоматически загружает файлы. Вам не нужно напрямую управлять этими файлами. -Каждый файл записывается атомарно: SDK записывает во временный файл, а затем переименовывает его на место, поэтому сборщик никогда не видит полузаписанный файл. Окончательный сброс также запускается при выходе вашего процесса, поэтому события, буферизованные в последнем интервале, не теряются. Если сборщик отключен, события просто накапливаются как файлы на диске и отправляются, как только он вернется в сеть. +Каждый файл записывается атомарно: SDK пишет во временный файл, а затем переименовывает его на место, поэтому сборщик никогда не видит частично записанный файл. Финальная очистка также выполняется при выходе процесса, поэтому события, буферизированные в последний интервал, не теряются. Если сборщик находится в автономном режиме, события просто накапливаются в виде файлов на диске и отправляются, как только он вернётся в сеть. --- ## Дальнейшие шаги -- [Поток событий](/ru/agenteye/event-stream): смотрите, как эти события прибывают в реальном времени, окрашенные и фильтруемые по окружению, агенту и сеансу. -- [Сеансы](/ru/agenteye/sessions): посмотрите, как парные события восстанавливают каждый запуск агента как граф выполнения и шкалу времени. \ No newline at end of file +- [Поток событий](/ru/agenteye/event-stream): смотрите, как эти события приходят в реальном времени, раскрашенные и фильтруемые по окружению, агенту и сеансу. +- [Сеансы](/ru/agenteye/sessions): смотрите, как парные события восстанавливают каждый запуск агента как граф исполнения и временную шкалу. \ No newline at end of file diff --git a/docs/tr/agenteye/python-sdk.mdx b/docs/tr/agenteye/python-sdk.mdx index f9bf6ab5..60a583ea 100644 --- a/docs/tr/agenteye/python-sdk.mdx +++ b/docs/tr/agenteye/python-sdk.mdx @@ -1,32 +1,32 @@ --- title: "Python SDK" -description: "Üretim ortamındaki AI ajanlarınızın tam olarak ne yaptığını görün: her ajan çalıştırması, araç çağrısı, model isteği, kancası ve insan müdahalesi." +description: "Üretimdeki AI ajanlarınızın tam olarak ne yaptığını görün: her ajanlı çalıştırma, araç çağrısı, model isteği, hook ve insan müdahalesi." --- -Üretim ortamındaki AI ajanlarınızın tam olarak ne yaptığını görün: her ajan çalıştırması, araç çağrısı, model isteği, kancası ve insan müdahalesi. Failproof AI Observability Python SDK bu iz kaydını ajan kodunuzun içinden kaydettiği için hata ayıklama, denetim ve ne olduğunu değerlendirme yapabilirsiniz. Failproof AI Observability'nin ajanlarınızı gözlemlemesini istediğinizde kullanabilirsiniz. +Üretimdeki AI ajanlarınızın tam olarak ne yaptığını görün: her ajanlı çalıştırma, araç çağrısı, model isteği, hook ve insan müdahalesi. Failproof AI Observability Python SDK, ajanlı kodunuzun içinden bu izleri kaydeder ve böylece ne olduğunu hata ayıklayabilir, denetleyebilir ve değerlendirebilirsiniz. Failproof AI Observability'nin ajanlarınızı gözlemlemesini istediğiniz her zaman bunu kullanın. -Arka planda, SDK yapılandırılmış olayları yerel JSONL dosyalarına yazıyor ve toplayıcı daemon otomatik olarak onları alıyor ve platforma gönderiyor. Bu dosyaları kendiniz yönetmiyorsunuz. +Arka planda SDK, yapılandırılmış olayları yerel JSONL dosyalarına yazar ve toplayıcı daemon bunları alır ve otomatik olarak platforma gönderir. Bu dosyaları kendiniz yönetmenize gerek yoktur. > **İpucu:** Failproof AI Observability'ye yeni misiniz? Bu sayfa tam SDK olay referansıdır.
- +
--- ## Kurulum -SDK müşterilere ortak bir paket dizininden değil, özel bir wheel olarak dağıtılmaktadır. Onboarding süreciniz nasıl elde edileceğini, kurulacağını ve sürümünün sabitleneceğini kapsar — erişim gerekiyorsa Failproof AI iletişim kişinize danışın. +SDK müşterilere özel bir wheel olarak dağıtılır ve genel paket dizininden değil. Onboarding'iniz nasıl elde edileceğini, kurulacağını ve sabitleneceğini kapsar — erişime ihtiyacınız varsa Failproof AI temsilcinize başvurun. -Kurulduktan sonra sahip olduğunuzu doğrulayın: +Kurulduktan sonra bunu kontrol edin: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Bir kodlama ajanının tüm entegrasyonu yapmasını mı tercih edersiniz? [Python SDK Agent Skill](/tr/agenteye/python-sdk-skill) kurulum yolunu biliyor, enstrümantasyon noktalarını planlıyor, yazıyor ve olayların geldiğini doğruluyor. +Bir kodlama ajanının tüm entegrasyonu yapmasını mı tercih edersiniz? [Python SDK Agent Skill](/tr/agenteye/python-sdk-skill) kurulum yolunu bilir, enstrümantasyon noktalarını planlar, yazar ve olayların ulaştığını doğrular. --- @@ -58,9 +58,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### Gerçek bir çağrıyı enstrümente etme +### Gerçek bir çağrıyı enstrümante etme -Pratikte var olan ajan kodunuzu sarmalarsınız. Bir model çağrısını `model_request` ile köşeli parantez içine alın ve sonra `model_response` yapın, böylece iki olay gerçek isteği kapsar ve Failproof AI Observability onları eşleştirebilir: +Uygulamada mevcut ajanlı kodunuzu sararsınız. Bir model çağrısını `model_request` ile başlatıp `model_response` ile bitirerek, iki olay gerçek istek üzerinde aralığı kaplar ve Failproof AI Observability bunları eşleştirebilir: ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -Araç çağrılarını da aynı şekilde `tool_use` ve `tool_result` ile sarmalayın, çift arasında bir `tool_call_id` yeniden kullanın. +Araç çağrılarını da aynı şekilde `tool_use` ve `tool_result` ile sarın, çift içinde aynı `tool_call_id` kullanarak. -İşte bu olayların pano üzerinde nasıl göründüğü, türe göre renklendirilmiş ve ortam, ajan ve oturum tarafından filtrelenebilir: +İşte bu olayların pano üzerinde göründüğü hali, türe göre renk kodlanmış ve ortam, ajan ve oturum tarafından filtrelenebilir: -![Canlı Olaylar akışı, olay türüne göre renklendirilmiş ve ortam, ajan ve oturuma göre filtrelenebilir](/agenteye/images/events-stream.png) +![Canlı Events akışı, olay türüne göre renk kodlanmış ve ortam, ajan ve oturum tarafından filtrelenebilir](/agenteye/images/events-stream.png) --- @@ -107,23 +107,23 @@ Araç çağrılarını da aynı şekilde `tool_use` ve `tool_result` ile sarmala ```python agenteye.configure( - base_dir=None, # Path | str | None. Varsayılan: $AGENTEYE_HOME veya ~/.agenteye - flush_interval=0.5, # float, flush döngüleri arasında saniye - environment=None, # str | None. Dağıtım ortamı etiketi + base_dir=None, # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye + flush_interval=0.5, # float, seconds between flush cycles + environment=None, # str | None. Deployment environment label ) ``` -Herhangi bir `event.*` çağrısından önce bir kez çağırın. Atlamak güvenlidir; varsayılanlar kutudan çıkarak çalışır. Tüm bağımsız değişkenler yalnızca anahtar kelimedir; yukarıda gösterildiği gibi isimle geçirin. +Herhangi bir `event.*` çağrısından önce bir kez çağırın. Çıkarmak güvenlidir; varsayılanlar kutudan çıkabilir durumda çalışır. Tüm argümanlar yalnızca anahtar sözcüklerdir; yukarıda gösterildiği gibi ada göre geçirin. -`base_dir` `None` olduğunda (varsayılan), SDK `$AGENTEYE_HOME` okur (ayarlandıysa), -aksi takdirde `~/.agenteye` dosyasına geri döner. Bu, toplayıcının kendi çözümlemesiyle eşleştiğinden, -tek bir `AGENTEYE_HOME` ortam değişkeni SDK ve toplayıcı için paylaşılan olay makalesini yapılandırır. +`base_dir` `None` (varsayılan) olduğunda, SDK `$AGENTEYE_HOME` ayarlanmışsa okur, +aksi takdirde `~/.agenteye` olarak geri döner. Bu, toplayıcının kendi çözünürlüğüyle eşleşir, +böylece tek bir `AGENTEYE_HOME` ortam değişkeni hem SDK hem de toplayıcı için paylaşılan olay sürüsünü yapılandırır. --- ## Ortam -Her olayı bir dağıtım ortamı (`production`, `staging`, `qa`, `canary` vb.) ile etiketleyin. Bunu bir kez ayarlayın; SDK bunu otomatik olarak her olaya ekler. +Her olayı dağıtım ortamı (`production`, `staging`, `qa`, `canary`, vb.) ile etiketleyin. Bir kez ayarlayın; SDK bunu otomatik olarak her olaya ekler. **Seçenek 1: `configure()` aracılığıyla:** @@ -139,47 +139,47 @@ export AGENTEYE_ENVIRONMENT=production **Öncelik:** `configure(environment=...)` ortam değişkenini geçersiz kılar. İkisi de ayarlanmamışsa, varsayılan olarak `"dev"` olur. -Ortam değişkeni panoda birinci sınıf bir filtre olarak görünür ve hızlı sorgular için sunucuda depolanır. +Ortam değişkeni, pano üzerinde birinci sınıf filtre olarak görüntülenir ve hızlı sorgular için sunucuda depolanır. -> **Uyarı:** Ortam değerleri değişmez bir `,` virgül içermemelidir. Pano filtreleri tel üzerinde virgülle ayrılmış çoklu seçim kullanırlar (`?environment=prod,staging`), bu nedenle `prod,blue` adlı bir ortam iki değere bölünecektir. Virgül içeren ortamların olayları alındığında reddedilir. +> **Uyarı:** Ortam değerleri gerçek virgül `,` içermemelidir. Pano filtreleri tel üzerinde virgülle ayrılmış çoklu seçim kullanır (`?environment=prod,staging`), bu nedenle `prod,blue` adlı bir ortam iki değere bölünür. Virgül içeren ortamlara sahip olaylar alım sırasında reddedilir. --- ## Veri ve Gizlilik -SDK yalnızca açıkça geçtiğiniz alanları kaydeder. İstemler, iletiler, araç girişleri ve çıkışları ve model içeriği yalnızca onları bir `event.*` çağrısına verdiğiniz için yakalanır. Hiçbir şey işleminizden okunmaz veya örtülü olarak yakalanmaz. Ayarlamadığınız herhangi bir alan, olaydan tamamen atlanır; diske yazılmaz. +SDK yalnızca açıkça geçtiğiniz alanları kaydeder. İstemleri, mesajları, araç girdilerini ve çıktılarını ve model içeriğini, bunları bir `event.*` çağrısına verdiğiniz için yakalarsınız. İşleminizden hiçbir şey okunmaz veya örtülü olarak yakalanmaz. Ayarlamadığınız herhangi bir alan, olaydan tamamen atlanır; diske yazılmaz. -Bu, redaksiyonu seçiminiz ve sorumluluğunuz yapar. İstem veya araç yükü PII veya depolamak istemeyen sırlar içeriyorsa, bunları olay yöntemine geçmeden önce çıkarın veya maskeyin. +Bu, redaksiyonu sizin seçiminiz ve sorumluluğunuz yapar. Bir istem veya araç yükü KKT veya sırlar içeriyorsa ve bunları depolamak istemiyorsanız, event yöntemine geçirmeden önce bunu çıkarın veya maskeleyin. --- ## Olay Referansı -Çoğu olay, bir korelasyon kimliği paylaşan başlangıç/bitiş çiftleri halinde gelir: `tool_use` ve `tool_result` bir `tool_call_id` paylaşır, `hook_triggered` ve `hook_completed` bir `hook_id` paylaşır ve `human_wait` ve `human_input` bir `input_id` paylaşır. Başlangıç olayını yayın, işi yapın, sonra sonlandırma olayını aynı kimlikle yayın. Failproof AI Observability çifti eşleştirir ve `duration_ms` sizin için hesaplar, bu nedenle `duration_ms` hiçbir zaman kendiniz geçmezsiniz. +Çoğu olay, korelasyon kimliğini paylaşan başlangıç/bitiş çiftleri olarak gelir: `tool_use` ve `tool_result` bir `tool_call_id` paylaşır, `hook_triggered` ve `hook_completed` bir `hook_id` paylaşır ve `human_wait` ve `human_input` bir `input_id` paylaşır. Başlangıç olayını yayın, işi yapın, sonra bitiş olayını aynı kimlikle yayın. Failproof AI Observability çifti eşleştirir ve `duration_ms` sizin için hesaplar, bu yüzden `duration_ms` hiç geçmezsiniz. -![Bir oturumun git benzeri yürütme grafiği, eşleştirilmiş olaylardan yeniden oluşturulan olay zaman çizelgesi ve araç/model/kanca dökümü paneli](/agenteye/images/session-detail.png) +![Bir oturumun, eşleştirilmiş olaylardan yeniden yapılandırılan git tarzı yürütme grafiği, olay zaman çizelgesi ve araç/model/hook dağılım paneli](/agenteye/images/session-detail.png) -Tüm olay yöntemleri bu iki alanı gerektirir: +Tüm olay yöntemleri şu iki alanı gerekli kılar: | Alan | Tür | Açıklama | |---|---|---| -| `session_id` | `str` | Üst düzey ajan çalıştırmasını tanımlar | -| `agent_id` | `str` | Oturum içinde olayı hangi ajanın yayınladığını tanımlar | +| `session_id` | `str` | Üst düzey ajanlı çalıştırmayı tanımlar | +| `agent_id` | `str` | Oturumda olayı yayan ajanı tanımlar | -Tüm yöntemler ayrıca özel meta veriler için rastgele `**kwargs` kabul eder (bkz. [Özel Alanlar](#custom-fields)). +Tüm yöntemler ayrıca özel meta veriler için rasgele `**kwargs` kabul eder (bkz. [Özel Alanlar](#custom-fields)). --- ### `event.agent_start()` -Bir ajan çalışmaya başladığında yayınlanır. +Bir ajan çalışmaya başladığında yayılır. ```python agenteye.event.agent_start( session_id="run-001", agent_id="planner", goal="answer user query", # str | None - parent_id=None, # str | None - iç içe ajanlar için ana agent_id + parent_id=None, # str | None - nested ajanlar için üst agent_id ) ``` @@ -187,7 +187,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Bir ajan çalışmayı bitirdiğinde yayınlanır. +Bir ajan çalışmayı bitirdiğinde yayılır. ```python agenteye.event.agent_end( @@ -202,14 +202,14 @@ agenteye.event.agent_end( ### `event.tool_use()` -Bir ajan araç kullandığında yayınlanır. `tool_result` ile eşleştirin; SDK otomatik olarak `duration_ms` hesaplar. +Bir ajan bir araç çağırdığında yayılır. `tool_result` ile eşleştirin; SDK otomatik olarak `duration_ms` hesaplar. ```python agenteye.event.tool_use( session_id="run-001", agent_id="planner", - tool_name="web_search", # str, gerekli - tool_call_id="toolu_01", # str, gerekli - eşleşen tool_result için korelasyon anahtarı + tool_name="web_search", # str, required + tool_call_id="toolu_01", # str, required - matching tool_result için korelasyon anahtarı input={"query": "..."}, # dict | None ) ``` @@ -218,17 +218,17 @@ agenteye.event.tool_use( ### `event.tool_result()` -Araç döndüğünde yayınlanır. `tool_call_id` aracılığıyla `tool_use` ile ilişkilidir. +Bir araç döndüğünde yayılır. `tool_call_id` aracılığıyla `tool_use` ile ilişkilendir. ```python agenteye.event.tool_result( session_id="run-001", agent_id="planner", tool_name="web_search", - tool_call_id="toolu_01", # önceki tool_use ile eşleşmelidir + tool_call_id="toolu_01", # prior tool_use ile eşleşmelidir output={"results": ["..."]}, # Any | None - error=None, # str | None - araç yükseltilirse ayarlayın - # duration_ms otomatik olarak hesaplanır - geçmeyin + error=None, # str | None - araç ortaya koyduysa ayarlayın + # duration_ms otomatik olarak hesaplanır - bunu geçmeyin ) ``` @@ -236,60 +236,60 @@ agenteye.event.tool_result( ### `event.model_request()` -Yalnızca bir istem bir LLM'ye gönderilmeden önce yayınlanır. +Bir LLM'ye istem göndermeden hemen önce yayılır. ```python agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - herhangi bir sağlayıcı/model dizesi; doğrulanmaz - messages=[ # list[dict] | None - konuşma dönüşleri + model="claude-sonnet-4-6", # str | None - any provider/model string; not validated + messages=[ # list[dict] | None - conversation turns {"role": "user", "content": "..."}, ], - system="You are helpful.", # Any | None - str veya içerik bloğu listesi - tools=[ # list[dict] | None - modele sunulan araç şemaları + system="You are helpful.", # Any | None - str or list of content blocks + tools=[ # list[dict] | None - tool schemas offered to the model {"name": "search", "input_schema": {"type": "object"}}, ], ) ``` -`messages` girişleri düz dize `content` veya Anthropic tarzı blok listesi `content` kabul eder. Örnekleme parametreleri (`temperature`, `max_tokens` vb.) ekstra kwargs olarak geçirilebilir. +`messages` girişleri düz dize `content` veya Anthropic tarzı blok listesi `content` kabul eder. Örnekleme parametreleri (`temperature`, `max_tokens`, vb.) ek kwargs olarak geçilebilir. --- ### `event.model_response()` -LLM bir yanıt döndürdüğünde yayınlanır. +LLM bir yanıt döndüğünde yayılır. ```python agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - herhangi bir sağlayıcı/model dizesi; doğrulanmaz + model="claude-sonnet-4-6", # str | None - any provider/model string; not validated stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None - content=[ # Any | None - str veya içerik bloğu listesi + content=[ # Any | None - str, or list of content blocks {"type": "text", "text": "..."}, ], role="assistant", # str | None ) ``` -`content` düz dize (genel sağlayıcılar) veya Anthropic tarzı içerik bloklı liste kabul eder. Araç çağrıları, `content` içinde `{"type": "tool_use", ...}` blokları olarak yaşar ve ayrı `tool_calls` alanı yoktur. +`content` düz dize (genel sağlayıcılar) veya Anthropic tarzı içerik bloklarının listesini kabul eder. Araç çağrıları `{"type": "tool_use", ...}` blokları olarak `content` içinde yaşar, ayrı `tool_calls` alanı yoktur. --- ### `event.hook_triggered()` -Bir kanca harekete geçtiğinde yayınlanır. `hook_completed` ile eşleştirin; SDK otomatik olarak `duration_ms` hesaplar. +Bir hook ateşlendiğinde yayılır. `hook_completed` ile eşleştirin; SDK otomatik olarak `duration_ms` hesaplar. ```python agenteye.event.hook_triggered( session_id="run-001", agent_id="planner", - hook_name="pre_tool_use", # str, gerekli - hook_id="hook-abc", # str, gerekli - korelasyon anahtarı + hook_name="pre_tool_use", # str, required + hook_id="hook-abc", # str, required - korelasyon anahtarı trigger_event="tool_use", # str | None input={"tool": "search"}, # Any | None ) @@ -299,18 +299,18 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Bir kanca bittiğinde yayınlanır. `hook_id` aracılığıyla `hook_triggered` ile ilişkilidir. +Bir hook bittiğinde yayılır. `hook_id` aracılığıyla `hook_triggered` ile ilişkilendir. ```python agenteye.event.hook_completed( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", - hook_id="hook-abc", # önceki hook_triggered ile eşleşmelidir + hook_id="hook-abc", # prior hook_triggered ile eşleşmelidir outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # duration_ms otomatik olarak hesaplanır - geçmeyin + # duration_ms otomatik olarak hesaplanır - bunu geçmeyin ) ``` @@ -318,14 +318,14 @@ agenteye.event.hook_completed( ### `event.error()` -İşlenmeyen bir hata oluştuğunda yayınlanır. +İşlenmeyen bir hata oluştuğunda yayılır. ```python agenteye.event.error( session_id="run-001", agent_id="planner", - error_type="TimeoutError", # str, gerekli - message="timed out", # str, gerekli + error_type="TimeoutError", # str, required + message="timed out", # str, required traceback="Traceback...", # str | None ) ``` @@ -334,61 +334,61 @@ agenteye.event.error( ## İnsan-in-the-Loop Olayları -İnsan-in-the-loop olayları bir kişinin ajanın yürütümesine müdahale ettiği anları (onay bekleme, giriş sağlama, durdurma veya ajanı durdurma) hakkında size gözetim verir. Bunlar insanların yanıt vermesinin ne kadar sürdüğünü ölçmenizi (SDK, eşleştirilmiş olaylarda `duration_ms` otomatik olarak hesaplar), kim bir ajanı durdurduğunu veya kesintiye uğrattığını denetlemenizi ve panoda ortaya çıkan onay ve gözetim iş akışları oluşturmanızı sağlar. +İnsan-in-the-loop olayları, bir kişinin ajanın yürütülmesine adım attığı anlar üzerinde gözetim sağlar (onay bekleme, giriş sağlama, duraklatma veya ajanı durdurma). İnsanların yanıt vermesinin ne kadar sürdüğünü ölçmenize (SDK eşleştirilmiş olaylarda otomatik olarak `duration_ms` hesaplar), kimin bir ajanı durduğunu veya kesintiye uğrattığını denetlemenize ve pano üzerinde yüzey alan onay ve gözetim iş akışları oluşturmanıza olanak tanır. ### `event.human_wait()` -Ajan bir insanın giriş sağlamasını beklemek için yürütmeyi duraklatırken yayınlanır. `human_input` ile eşleştirin; SDK otomatik olarak `duration_ms` hesaplar (insanın yanıt vermesi için geçen süre). +Ajan insan tarafından giriş sağlanması için beklemeye yürütmeyi duraklattığında yayılır. `human_input` ile eşleştirin; SDK otomatik olarak `duration_ms` hesaplar (insanın yanıt vermesi ne kadar sürdü). ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, gerekli - eşleşen human_input için korelasyon anahtarı + input_id="inp-abc", # str, required - matching human_input için korelasyon anahtarı prompt="Do you approve this action?", # str | None - insana gösterilen soru options=["approve", "reject", "defer"], # list[str] | None - insana sunulan seçenekler - reason="approval_required", # str | None - ajanın neden beklediğinin nedeni + reason="approval_required", # str | None - ajanın neden beklediği ) ``` ### `event.human_input()` -Bir insan giriş sağladığında ve ajan devam ettiğinde yayınlanır. `input_id` aracılığıyla `human_wait` ile ilişkilidir. `duration_ms` otomatik olarak hesaplanır ve çağıran tarafından geçirilmemelidir. +Bir insan giriş sağladığında ve ajan devam ettiğinde yayılır. `input_id` aracılığıyla `human_wait` ile ilişkilendir. `duration_ms` otomatik olarak hesaplanır ve arayan tarafından geçilmemelidir. ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, gerekli - önceki human_wait ile eşleşmelidir + input_id="inp-abc", # str, required - prior human_wait ile eşleşmelidir response="approve", # str | None - insanın cevabı (serbest metin veya seçili seçenek) - # duration_ms otomatik olarak hesaplanır - geçmeyin + # duration_ms otomatik olarak hesaplanır - bunu geçmeyin ) ``` ### `event.human_pause()` -Bir insan ajanı aktif olarak durdurursa yayınlanır (örn. pano kontrolü aracılığıyla). Ajan askıya alınırken sonlandırılmaz. +Bir insan ajanı aktif olarak duraklattığında yayılır (örn. pano kontrolü aracılığıyla). Ajan askıya alınır ancak sonlandırılmaz. ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - ajanı duraklatanın + user_id="usr_42", # str | None - ajanı kimin durduğu ) ``` ### `event.human_interrupt()` -Bir insan yürütme sırasında ajanı aktif olarak durdurduğunda yayınlanır. `human_pause` (ajan askıya alınmak yerine sonlandırılır) öğesinden farklıdır. +Bir insan yürütme sırasında ajanı aktif olarak durdurduğunda yayılır. `human_pause` aksine, ajanın çalışması askıya alınmak yerine sonlandırılır. ```python agenteye.event.human_interrupt( session_id="run-001", agent_id="planner", reason="output_incorrect", # str | None - user_id="usr_42", # str | None - ajanı kesintiye uğratanın - at_step="tool_use:web_search", # str | None - durdurulurken ajanın ne yaptığı + user_id="usr_42", # str | None - ajanı kimin kesintiye uğrattığı + at_step="tool_use:web_search", # str | None - durdurulduğu sırada ajan ne yapıyordu ) ``` @@ -396,7 +396,7 @@ agenteye.event.human_interrupt( ## Özel Alanlar -Herhangi bir ek anahtar kelime bağımsız değişkeni standart alanlardan sonra olaya eklenir: +Herhangi bir ek anahtar sözcük argümanı standart alanların ardından olaya eklenir: ```python agenteye.event.tool_use( @@ -404,30 +404,32 @@ agenteye.event.tool_use( agent_id="planner", tool_name="db_query", tool_call_id="toolu_02", - tenant_id="acme", # özel alan - region="us-east-1", # özel alan + tenant_id="acme", # custom field + region="us-east-1", # custom field ) ``` -`timestamp`, `type` ve `environment` ayrılmıştır ve özel alanlar olarak geçirilirse `ValueError` yükseltir (`Reserved field names cannot be used as custom fields: [...]`). `session_id` ve `agent_id` her olay yönteminde zorunlu parametrelerdir ve ikinci kez sağlanamazlar; bunu yaparsanız Python `TypeError` yükseltir. Bunun yerine `configure(environment=...)` (veya `AGENTEYE_ENVIRONMENT` değişkeni) ile ortamı ayarlayın. +`timestamp`, `type` ve `environment` ayrılmıştır ve özel alanlar olarak geçirilirse `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) oluşturur. `session_id` ve `agent_id`, her olay yönteminde gerekli parametrelerdir ve ikinci kez sağlanamazlar; bunu yaparsanız Python `TypeError` oluşturur. Bunun yerine ortamı `configure(environment=...)` (veya `AGENTEYE_ENVIRONMENT` değişkeni) ile ayarlayın. + +Alanlarını sorgulamak istediğinizde yüklemleri yapılandırılmış JSON olarak tutun. JSON'un yerel olarak desteklemediği değerler—tarihler, UU'lar, ondalıklar, kümeler, baytlar veya model nesneleri gibi—kayıt güvenle devam edebilsin diye dizelere dönüştürülür. --- ## Olaylar Nasıl Yazılır -Olaylar işlem içi olarak arabelleğe alınır ve her `flush_interval` saniyede diske boşaltılır (varsayılan 500 ms). Her boşaltma bir JSONL dosyası yazar: +Olaylar işlemde arabelleğe alınır ve `flush_interval` saniye (varsayılan 500 ms) her blokta diske temizlenir. Her temizleme bir JSONL dosyası yazar: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -Toplayıcı bu dizini izler ve dosyaları otomatik olarak yükler. Bu dosyaları doğrudan yönetmek zorunda değilsiniz. +Toplayıcı bu dizini izler ve dosyaları otomatik olarak yükler. Bu dosyaları doğrudan yönetmenize gerek yoktur. -Her dosya atomik olarak yazılır: SDK geçici bir dosyaya yazar ve sonra yerine yeniden adlandırır, bu nedenle toplayıcı asla yarı yazılmış bir dosya görmez. İşleminiz çıktığında son bir boşaltma da çalışır, bu nedenle son aralıkta arabelleğe alınan olaylar kaybolmaz. Toplayıcı çevrimdışıysa, olaylar diskte dosya olarak birikir ve çevrimiçi olduğunda gönderilir. +Her dosya atomik olarak yazılır: SDK geçici bir dosyaya yazar ve ardından yerinde yeniden adlandırır, böylece toplayıcı asla yarım yazılmış bir dosya görmez. Son temizleme işleminiz çıktığında da çalışır, bu yüzden son aralıkta arabelleğe alınan olaylar kaybolmaz. Toplayıcı çevrimdışıysa, olaylar diske dosya olarak basitçe biriktikçe ve tekrar geldiğinde gönderilir. --- -## Sonraki Adımlar +## Sonraki adımlar -- [Olay akışı](/tr/agenteye/event-stream): bu olayları canlı olarak izleyin, olay türüne göre renklendirilmiş ve ortam, ajan ve oturuma göre filtrelenebilir. -- [Oturumlar](/tr/agenteye/sessions): eşleştirilmiş olayların her ajan çalıştırmasını yürütme grafiği ve zaman çizelgesi olarak nasıl yeniden oluşturduğunu görün. \ No newline at end of file +- [Event stream](/tr/agenteye/event-stream): bu olayları canlı olarak izleyin, ortam, ajan ve oturum tarafından renk kodlanmış ve filtrelenebilir. +- [Sessions](/tr/agenteye/sessions): eşleştirilmiş olayların her ajanlı çalıştırmayı bir yürütme grafiği ve zaman çizelgesi olarak nasıl yeniden yapılandırdığını görün. \ No newline at end of file diff --git a/docs/vi/agenteye/python-sdk.mdx b/docs/vi/agenteye/python-sdk.mdx index 1e1b1b64..af06fe61 100644 --- a/docs/vi/agenteye/python-sdk.mdx +++ b/docs/vi/agenteye/python-sdk.mdx @@ -1,13 +1,13 @@ --- title: "Python SDK" -description: "Xem chính xác những gì các AI agent của bạn đã làm trong production: mọi lần chạy agent, lệnh gọi công cụ, yêu cầu mô hình, hook và can thiệp của con người." +description: "Xem chính xác những gì các agent AI của bạn đã làm trong production: mọi agent run, tool call, model request, hook, và human intervention." --- -Xem chính xác những gì các AI agent của bạn đã làm trong production: mọi lần chạy agent, lệnh gọi công cụ, yêu cầu mô hình, hook và can thiệp của con người. SDK Observability Python của Failproof AI ghi lại dấu vết đó từ bên trong mã agent của bạn để bạn có thể gỡ lỗi, kiểm toán và đánh giá những gì đã xảy ra. Sử dụng nó bất cứ khi nào bạn muốn Failproof AI Observability theo dõi các agent của mình. +Xem chính xác những gì các agent AI của bạn đã làm trong production: mọi agent run, tool call, model request, hook, và human intervention. Failproof AI Observability Python SDK ghi lại toàn bộ quá trình này từ trong code agent của bạn để bạn có thể debug, audit, và đánh giá những gì đã xảy ra. Sử dụng nó bất cứ khi nào bạn muốn Failproof AI Observability quan sát các agent của mình. -Về cơ bản, SDK ghi các sự kiện có cấu trúc vào các tệp JSONL cục bộ, và trình daemon bộ sưu tập sẽ chọn chúng và gửi đến nền tảng tự động. Bạn không cần quản lý các tệp đó. +Bên dưới, SDK ghi các sự kiện có cấu trúc vào các tệp JSONL cục bộ, và daemon collector sẽ lấy chúng và gửi lên platform một cách tự động. Bạn không cần phải quản lý những tệp này. -> **Tip:** Mới làm quen với Failproof AI Observability? Trang này là tài liệu tham khảo sự kiện SDK hoàn chỉnh. +> **Tip:** Mới bắt đầu với Failproof AI Observability? Trang này là tài liệu tham khảo sự kiện SDK hoàn chỉnh.
@@ -17,19 +17,19 @@ Về cơ bản, SDK ghi các sự kiện có cấu trúc vào các tệp JSONL c ## Cài đặt -SDK được phân phối cho khách hàng dưới dạng wheel riêng tư thay vì từ một chỉ mục gói công cộng. Quá trình onboarding của bạn bao gồm cách lấy nó, cài đặt nó và ghim nó — hãy liên hệ với nhân viên Failproof AI của bạn nếu bạn cần truy cập. +SDK được phân phối cho khách hàng dưới dạng private wheel thay vì từ public package index. Phần onboarding của bạn sẽ hướng dẫn cách lấy, cài đặt và fix phiên bản — liên hệ với Failproof AI contact của bạn nếu bạn cần truy cập. -Sau khi cài đặt, hãy xác nhận rằng bạn có nó: +Khi đã cài đặt, hãy xác nhận bạn có nó: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Thích để cho một coding agent thực hiện toàn bộ tích hợp? [Python SDK Agent Skill](/vi/agenteye/python-sdk-skill) biết đường dẫn cài đặt, lập kế hoạch cho các điểm công cụ, viết chúng và xác minh rằng các sự kiện đó được đặt. +Thích để cho một coding agent làm toàn bộ tích hợp? [Python SDK Agent Skill](/vi/agenteye/python-sdk-skill) biết đường dẫn cài đặt, lên kế hoạch các điểm instrumentation, viết chúng và xác minh các sự kiện được ghi lại. --- -## Khởi động nhanh +## Bắt đầu nhanh ```python import agenteye @@ -57,9 +57,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### Công cụ hóa một lệnh gọi thực tế +### Instrumentation cho một cuộc gọi thực -Trong thực tế, bạn bao bọc mã agent hiện có của mình. Đặt một lệnh gọi mô hình giữa `model_request` trước và `model_response` sau, để hai sự kiện này kéo dài toàn bộ yêu cầu thực tế và Failproof AI Observability có thể ghép chúng lại: +Trong thực tế, bạn bao quanh code agent hiện có của bạn. Đặt một model call giữa `model_request` trước và `model_response` sau, để hai sự kiện bao quanh yêu cầu thực và Failproof AI Observability có thể ghép chúng: ```python import anthropic @@ -94,11 +94,11 @@ agenteye.event.model_response( ) ``` -Bao bọc các lệnh gọi công cụ theo cách tương tự với `tool_use` và `tool_result`, tái sử dụng một `tool_call_id` trên cặp. +Bao quanh tool calls theo cách tương tự với `tool_use` và `tool_result`, sử dụng lại một `tool_call_id` giống nhau cho cả hai. -Đây là những gì các sự kiện đó trông như thế nào sau khi đến bảng điều khiển, được mã hóa màu theo loại và có thể lọc theo môi trường, agent và phiên: +Đây là cách những sự kiện đó trông như thế nào khi chúng đến dashboard, có mã màu theo loại và có thể lọc theo environment, agent, và session: -![Luồng Sự kiện trực tiếp, được mã hóa màu theo loại sự kiện và có thể lọc theo môi trường, agent và phiên](/agenteye/images/events-stream.png) +![The live Events stream, colour-coded by event type and filterable by environment, agent, and session](/agenteye/images/events-stream.png) --- @@ -112,67 +112,64 @@ agenteye.configure( ) ``` -Gọi một lần trước bất kỳ lệnh gọi `event.*` nào. An toàn khi bỏ qua; các giá trị mặc định hoạt động ngay lập tức. Tất cả các đối số chỉ là từ khóa; truyền chúng theo tên như hiển thị ở trên. +Gọi một lần trước bất kỳ lệnh gọi `event.*` nào. An toàn để bỏ qua; mặc định hoạt động ngay lập tức. Tất cả các tham số đều là keyword-only; hãy truyền chúng theo tên như được hiển thị ở trên. -Khi `base_dir` là `None` (mặc định), SDK đọc `$AGENTEYE_HOME` nếu được đặt, -nếu không sẽ quay lại `~/.agenteye`. Điều này khớp với độ phân giải của chính bộ sưu tập, -vì vậy một biến env `AGENTEYE_HOME` duy nhất cấu hình bộ sưu tập sự kiện được chia sẻ cho cả -SDK và bộ sưu tập. +Khi `base_dir` là `None` (mặc định), SDK sẽ đọc `$AGENTEYE_HOME` nếu được đặt, nếu không sẽ quay lại `~/.agenteye`. Điều này phù hợp với cách phân giải của chính collector, vì vậy một biến env `AGENTEYE_HOME` duy nhất sẽ cấu hình shared event spool cho cả SDK và collector. --- -## Môi trường +## Environment -Gắn nhãn mọi sự kiện với một môi trường triển khai (`production`, `staging`, `qa`, `canary`, v.v.). Đặt nó một lần; SDK đính kèm nó vào mọi sự kiện tự động. +Gắn nhãn mọi sự kiện với một environment triển khai (`production`, `staging`, `qa`, `canary`, v.v.). Đặt nó một lần; SDK sẽ tự động đính kèm nó vào mọi sự kiện. -**Tùy chọn 1: qua `configure()`:** +**Option 1: thông qua `configure()`:** ```python agenteye.configure(environment="production") ``` -**Tùy chọn 2: qua biến môi trường:** +**Option 2: thông qua biến environment:** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**Ưu tiên:** `configure(environment=...)` thắng trên biến môi trường. Nếu không có bộ nào được đặt, mặc định là `"dev"`. +**Ưu tiên:** `configure(environment=...)` sẽ được ưu tiên hơn biến environment. Nếu không có cái nào được đặt, mặc định là `"dev"`. -Giá trị môi trường xuất hiện dưới dạng bộ lọc hạng nhất trong bảng điều khiển và được lưu trữ trên máy chủ để truy vấn nhanh. +Giá trị environment xuất hiện như một bộ lọc hạng nhất trong dashboard và được lưu trữ trên máy chủ để truy vấn nhanh. -> **Warning:** Giá trị Môi trường không được chứa dấu phẩy `,` theo nghĩa đen. Các bộ lọc bảng điều khiển sử dụng đa lựa chọn được phân tách bằng dấu phẩy trên dây (`?environment=prod,staging`), vì vậy một môi trường có tên `prod,blue` sẽ bị chia thành hai giá trị. Các sự kiện với các môi trường chứa dấu phẩy bị từ chối vào thời điểm tiếp nhận. +> **Warning:** Giá trị environment không được chứa dấu phẩy `,` theo nghĩa đen. Bộ lọc dashboard sử dụng multi-select được phân tách bằng dấu phẩy trên wire (`?environment=prod,staging`), vì vậy một environment được đặt tên `prod,blue` sẽ bị chia thành hai giá trị. Các sự kiện có environment chứa dấu phẩy bị từ chối tại thời gian ingest. --- -## Dữ liệu và quyền riêng tư +## Data and privacy -SDK chỉ ghi lại các trường bạn rõ ràng truyền. Prompts, messages, tool inputs và outputs, và nội dung mô hình được capture chỉ vì bạn trao chúng cho một lệnh gọi `event.*`. Không có gì được đọc từ quá trình của bạn hoặc captured ngầm định. Bất kỳ trường nào bạn để không đặt sẽ được bỏ qua hoàn toàn từ sự kiện; nó không được ghi vào đĩa. +SDK chỉ ghi lại các trường bạn tường minh truyền. Prompts, messages, tool inputs và outputs, và model content chỉ được capture vì bạn chuyển chúng đến một cuộc gọi `event.*`. Không có gì được đọc từ process của bạn hoặc được capture ngầm. Bất kỳ trường nào bạn để không được đặt đều bị bỏ qua khỏi sự kiện hoàn toàn; nó không được ghi vào disk. -Điều đó làm cho việc redact là lựa chọn và trách nhiệm của bạn. Nếu một prompt hoặc tool payload chứa PII hoặc secrets mà bạn không muốn lưu trữ, hãy tách hoặc che bao trước khi bạn truyền nó đến phương thức sự kiện. +Điều đó làm cho redaction là lựa chọn và trách nhiệm của bạn. Nếu một prompt hoặc tool payload chứa PII hoặc secrets mà bạn không muốn lưu trữ, hãy xóa hoặc che nó trước khi chuyển nó đến phương thức event. --- -## Tham chiếu Sự kiện +## Event Reference -Hầu hết các sự kiện đến theo các cặp start/end chia sẻ một ID tương quan: `tool_use` và `tool_result` chia sẻ một `tool_call_id`, `hook_triggered` và `hook_completed` chia sẻ một `hook_id`, và `human_wait` và `human_input` chia sẻ một `input_id`. Phát ra sự kiện bắt đầu, thực hiện công việc, sau đó phát ra sự kiện kết thúc với cùng một ID. Failproof AI Observability khớp cặp và tính toán `duration_ms` cho bạn, vì vậy bạn không bao giờ truyền `duration_ms` chính mình. +Hầu hết các sự kiện đều có cặp start/end chia sẻ một correlation ID: `tool_use` và `tool_result` chia sẻ một `tool_call_id`, `hook_triggered` và `hook_completed` chia sẻ một `hook_id`, và `human_wait` và `human_input` chia sẻ một `input_id`. Phát hành sự kiện start, thực hiện công việc, sau đó phát hành sự kiện end với cùng một ID. Failproof AI Observability khớp cặp và tính toán `duration_ms` cho bạn, vì vậy bạn không bao giờ tự truyền `duration_ms`. -![Biểu đồ thực thi kiểu git của phiên bên cạnh dòng thời gian sự kiện của nó, được xây dựng lại từ các sự kiện được ghép nối, với bảng phân tích công cụ/mô hình/hook](/agenteye/images/session-detail.png) +![A session's git-style execution graph beside its event timeline, reconstructed from the paired events, with the tool/model/hook breakdown panel](/agenteye/images/session-detail.png) -Tất cả các phương thức sự kiện yêu cầu hai trường này: +Tất cả các phương thức event yêu cầu hai trường này: -| Trường | Loại | Mô tả | +| Field | Type | Description | |---|---|---| -| `session_id` | `str` | Xác định lần chạy agent cấp cao nhất | -| `agent_id` | `str` | Xác định agent nào trong phiên đã phát ra sự kiện | +| `session_id` | `str` | Xác định agent run cấp top-level | +| `agent_id` | `str` | Xác định agent nào trong session phát hành sự kiện | -Tất cả các phương thức cũng chấp nhận `**kwargs` tùy ý cho siêu dữ liệu tùy chỉnh (xem [Trường Tùy chỉnh](#custom-fields)). +Tất cả các phương thức cũng chấp nhận `**kwargs` tùy ý cho metadata tùy chỉnh (xem [Custom Fields](#custom-fields)). --- ### `event.agent_start()` -Phát ra khi một agent bắt đầu làm việc. +Phát hành khi một agent bắt đầu làm việc. ```python agenteye.event.agent_start( @@ -187,7 +184,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Phát ra khi một agent kết thúc công việc. +Phát hành khi một agent kết thúc công việc. ```python agenteye.event.agent_end( @@ -202,7 +199,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -Phát ra khi một agent gọi một công cụ. Ghép với `tool_result`; SDK tự động tính toán `duration_ms`. +Phát hành khi một agent gọi một tool. Ghép với `tool_result`; SDK tự động tính toán `duration_ms`. ```python agenteye.event.tool_use( @@ -218,7 +215,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -Phát ra khi một công cụ trả về. Tương quan với `tool_use` thông qua `tool_call_id`. +Phát hành khi một tool trả về. Tương quan với `tool_use` thông qua `tool_call_id`. ```python agenteye.event.tool_result( @@ -236,7 +233,7 @@ agenteye.event.tool_result( ### `event.model_request()` -Phát ra ngay trước khi gửi một prompt đến LLM. +Phát hành ngay trước khi gửi một prompt đến LLM. ```python agenteye.event.model_request( @@ -253,13 +250,13 @@ agenteye.event.model_request( ) ``` -Các mục `messages` chấp nhận `content` đơn giản hoặc `content` kiểu danh sách khối của Anthropic. Các tham số lấy mẫu (`temperature`, `max_tokens`, v.v.) có thể được truyền dưới dạng kwargs bổ sung. +Các mục `messages` chấp nhận hoặc content `content` dạng chuỗi đơn hoặc Anthropic-style list-of-blocks `content`. Các tham số sampling (`temperature`, `max_tokens`, v.v.) có thể được chuyển dưới dạng extra kwargs. --- ### `event.model_response()` -Phát ra khi LLM trả về một phản hồi. +Phát hành khi LLM trả về một response. ```python agenteye.event.model_response( @@ -276,13 +273,13 @@ agenteye.event.model_response( ) ``` -`content` chấp nhận hoặc một chuỗi đơn giản (nhà cung cấp chung) hoặc một danh sách các khối nội dung kiểu Anthropic. Các lệnh gọi công cụ nằm trong `content` dưới dạng khối `{"type": "tool_use", ...}`, không có trường `tool_calls` riêng biệt. +`content` chấp nhận hoặc chuỗi đơn (generic providers) hoặc danh sách các content blocks kiểu Anthropic. Tool calls sống bên trong `content` dưới dạng các khối `{"type": "tool_use", ...}`, không có trường `tool_calls` riêng biệt. --- ### `event.hook_triggered()` -Phát ra khi một hook kích hoạt. Ghép với `hook_completed`; SDK tự động tính toán `duration_ms`. +Phát hành khi một hook kích hoạt. Ghép với `hook_completed`; SDK tự động tính toán `duration_ms`. ```python agenteye.event.hook_triggered( @@ -299,7 +296,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Phát ra khi một hook kết thúc. Tương quan với `hook_triggered` thông qua `hook_id`. +Phát hành khi một hook kết thúc. Tương quan với `hook_triggered` thông qua `hook_id`. ```python agenteye.event.hook_completed( @@ -318,7 +315,7 @@ agenteye.event.hook_completed( ### `event.error()` -Phát ra khi xảy ra lỗi không được xử lý. +Phát hành khi một lỗi không được xử lý xảy ra. ```python agenteye.event.error( @@ -332,13 +329,13 @@ agenteye.event.error( --- -## Sự kiện Loại Người trong Vòng lặp +## Human-in-the-Loop Events -Các sự kiện con người trong vòng lặp mang lại cho bạn giám sát những khoảnh khắc mà một người bước vào quá trình thực thi của agent (chờ phê duyệt, cung cấp đầu vào, tạm dừng hoặc dừng agent). Chúng cho phép bạn đo lường thời gian con người thực hiện để phản hồi (SDK tự động tính toán `duration_ms` trên các sự kiện được ghép nối), kiểm toán ai đã tạm dừng hoặc gián đoạn agent và xây dựng công việc phê duyệt và giám sát mà bề mặt trong bảng điều khiển. +Các sự kiện human-in-the-loop cho bạn sự giám sát các khoảnh khắc mà một người bước vào quá trình thực thi của agent (chờ phê duyệt, cung cấp input, tạm dừng hoặc dừng agent). Chúng cho phép bạn đo lường thời gian con người mất để phản hồi (SDK tự động tính toán `duration_ms` trên các sự kiện ghép), audit ai đã tạm dừng hoặc gián đoạn một agent, và xây dựng các workflow phê duyệt và giám sát hiển thị trong dashboard. ### `event.human_wait()` -Phát ra khi agent tạm dừng quá trình thực thi để chờ con người cung cấp đầu vào. Ghép với `human_input`; SDK tự động tính toán `duration_ms` (con người mất bao lâu để phản hồi). +Phát hành khi agent tạm dừng thực thi để chờ một người cung cấp input. Ghép với `human_input`; SDK tự động tính toán `duration_ms` (thời gian con người mất để phản hồi). ```python agenteye.event.human_wait( @@ -353,7 +350,7 @@ agenteye.event.human_wait( ### `event.human_input()` -Phát ra khi con người cung cấp đầu vào và agent tiếp tục. Tương quan với `human_wait` thông qua `input_id`. `duration_ms` được tính toán tự động và không được truyền bởi người gọi. +Phát hành khi một người cung cấp input và agent tiếp tục. Tương quan với `human_wait` thông qua `input_id`. `duration_ms` được tự động tính toán và không được gọi truyền bởi người gọi. ```python agenteye.event.human_input( @@ -367,7 +364,7 @@ agenteye.event.human_input( ### `event.human_pause()` -Phát ra khi con người chủ động tạm dừng agent (ví dụ: qua kiểm soát bảng điều khiển). Agent bị tạm dừng nhưng không bị chấm dứt. +Phát hành khi một người chủ động tạm dừng agent (ví dụ: thông qua điều khiển dashboard). Agent bị tạm dừng nhưng không bị chấm dứt. ```python agenteye.event.human_pause( @@ -380,7 +377,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -Phát ra khi con người chủ động dừng agent trong quá trình thực thi. Không giống như `human_pause`, công việc của agent bị chấm dứt thay vì bị tạm dừng. +Phát hành khi một người chủ động dừng agent giữa quá trình thực thi. Không giống như `human_pause`, công việc của agent bị chấm dứt thay vì bị tạm dừng. ```python agenteye.event.human_interrupt( @@ -394,9 +391,9 @@ agenteye.event.human_interrupt( --- -## Trường Tùy chỉnh +## Custom Fields -Bất kỳ đối số từ khóa bổ sung nào được thêm vào sự kiện sau các trường tiêu chuẩn: +Bất kỳ keyword arguments bổ sung nào cũng được thêm vào sự kiện sau các trường tiêu chuẩn: ```python agenteye.event.tool_use( @@ -409,25 +406,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` và `environment` được dành riêng và tăng `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) nếu được truyền dưới dạng các trường tùy chỉnh. `session_id` và `agent_id` là các tham số bắt buộc trên mọi phương thức sự kiện và không thể được cung cấp lần thứ hai; Python tăng `TypeError` nếu bạn làm. Đặt môi trường với `configure(environment=...)` (hoặc biến `AGENTEYE_ENVIRONMENT`) để thay thế. +`timestamp`, `type`, và `environment` được dự trữ và tăng `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) nếu được chuyển dưới dạng custom fields. `session_id` và `agent_id` là tham số bắt buộc trên mọi phương thức event và không thể được cung cấp lần thứ hai; Python tăng `TypeError` nếu bạn làm. Đặt environment với `configure(environment=...)` (hoặc biến `AGENTEYE_ENVIRONMENT`) thay thế. + +Giữ payloads dưới dạng JSON có cấu trúc khi bạn muốn truy vấn các trường của chúng. Các giá trị mà JSON không hỗ trợ nguyên bản—chẳng hạn như datetimes, UUIDs, decimals, sets, bytes, hoặc model objects—được chuyển đổi thành chuỗi sao cho ghi lại tiếp tục an toàn. --- -## Cách Sự kiện Được Viết +## How Events Are Written -Các sự kiện được đệm trong quá trình và xóa vào đĩa mỗi giây `flush_interval` (mặc định 500 ms). Mỗi lần xóa ghi một tệp JSONL: +Các sự kiện được đệm trong quá trình và được flush vào disk mỗi `flush_interval` giây (mặc định 500 ms). Mỗi flush ghi một tệp JSONL: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -Bộ sưu tập xem dõi thư mục này và tải lên các tệp tự động. Bạn không cần quản lý các tệp này trực tiếp. +Collector theo dõi thư mục này và tải các tệp lên tự động. Bạn không cần phải quản lý các tệp này trực tiếp. -Mỗi tệp được ghi một cách nguyên tử: SDK ghi vào một tệp tạm thời và sau đó đổi tên nó vào vị trí, vì vậy bộ sưu tập không bao giờ thấy một tệp nửa được viết. Một xóa cuối cùng cũng chạy khi quá trình của bạn thoát, vì vậy các sự kiện được đệm trong khoảng thời gian cuối cùng không bị mất. Nếu bộ sưu tập ngoại tuyến, các sự kiện đơn giản chỉ tích lũy dưới dạng các tệp trên đĩa và gửi khi nó quay lại trực tuyến. +Mỗi tệp được ghi một cách nguyên tử: SDK ghi vào một tệp tạm thời và sau đó đổi tên nó vào chỗ, vì vậy collector không bao giờ thấy một tệp nửa ghi. Một flush cuối cùng cũng chạy khi quy trình của bạn thoát, vì vậy các sự kiện được đệm trong khoảng cuối cùng không bị mất. Nếu collector ngoại tuyến, các sự kiện chỉ đơn giản tích lũy dưới dạng các tệp trên disk và ship khi nó quay lại. --- ## Các bước tiếp theo -- [Event stream](/vi/agenteye/event-stream): xem các sự kiện này đến trực tiếp, được mã hóa màu và có thể lọc theo môi trường, agent và phiên. -- [Sessions](/vi/agenteye/sessions): xem cách các sự kiện được ghép nối xây dựng lại mỗi lần chạy agent như một biểu đồ thực thi và dòng thời gian. \ No newline at end of file +- [Event stream](/vi/agenteye/event-stream): xem những sự kiện này đến trực tiếp, có mã màu và có thể lọc theo environment, agent, và session. +- [Sessions](/vi/agenteye/sessions): xem cách các sự kiện ghép tái tạo mỗi agent run dưới dạng execution graph và timeline. \ No newline at end of file diff --git a/docs/zh/agenteye/python-sdk.mdx b/docs/zh/agenteye/python-sdk.mdx index fee3371f..ec61e623 100644 --- a/docs/zh/agenteye/python-sdk.mdx +++ b/docs/zh/agenteye/python-sdk.mdx @@ -1,14 +1,14 @@ --- title: "Python SDK" -description: "精确掌握 AI 智能体在生产环境中的每一步：每次运行、工具调用、模型请求、hook 及人工干预。" +description: "精确了解您的 AI 智能体在生产环境中的每一步操作：每次智能体运行、工具调用、模型请求、hook 及人工干预。" --- -精确掌握 AI 智能体在生产环境中的每一步：每次运行、工具调用、模型请求、hook 及人工干预。Failproof AI Observability Python SDK 在智能体代码内部记录完整的执行轨迹，让你能够调试、审计和评估发生的一切。凡是需要 Failproof AI Observability 监控智能体时，均可使用它。 +精确了解您的 AI 智能体在生产环境中的每一步操作：每次智能体运行、工具调用、模型请求、hook 及人工干预。Failproof AI 可观测性 Python SDK 从您的智能体代码内部记录这些轨迹，便于您调试、审计和评估发生了什么。每当您希望 Failproof AI 可观测性监控您的智能体时，请使用此 SDK。 -SDK 底层将结构化事件写入本地 JSONL 文件，采集器守护进程会自动拾取并上传至平台。你无需自行管理这些文件。 +在底层，SDK 将结构化事件写入本地 JSONL 文件，采集器守护进程会自动拾取并上传至平台。您无需自行管理这些文件。 -> **提示：** 初次使用 Failproof AI Observability？本页是完整的 SDK 事件参考文档。 +> **提示：** 刚开始使用 Failproof AI 可观测性？本页是完整的 SDK 事件参考文档。
@@ -18,15 +18,15 @@ SDK 底层将结构化事件写入本地 JSONL 文件，采集器守护进程会 ## 安装 -SDK 作为私有 wheel 包分发给客户，不在公共包索引中提供。具体的获取方式、安装步骤及版本锁定方法在入门培训中均有说明——如需访问权限，请联系你的 Failproof AI 对接人。 +SDK 以私有 wheel 包的形式分发给客户，而非通过公开的包索引获取。您的入门流程中会介绍如何获取、安装和固定版本——如需获取访问权限，请联系您的 Failproof AI 对接人。 -安装完成后，可通过以下命令确认： +安装完成后，通过以下命令确认安装成功： ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -想让编程智能体完成整个集成过程？[Python SDK Agent Skill](/zh/agenteye/python-sdk-skill) 了解安装路径，能够规划插桩点、编写代码并验证事件是否成功上报。 +希望让编码智能体完成整个集成工作？[Python SDK Agent Skill](/zh/agenteye/python-sdk-skill) 了解安装路径，能够规划埋点位置、编写代码并验证事件是否正常上报。 --- @@ -58,9 +58,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### 对真实调用进行插桩 +### 对真实调用进行埋点 -实际使用时，你需要对现有智能体代码进行包装。在模型调用前发送 `model_request`，调用后发送 `model_response`，使这两个事件覆盖真实请求的完整时间段，Failproof AI Observability 便能将它们关联配对： +在实际场景中，您需要对现有的智能体代码进行包装。在模型调用前后分别使用 `model_request` 和 `model_response` 包裹，使这两个事件覆盖真实请求的完整周期，Failproof AI 可观测性便能将它们配对： ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -工具调用同理，使用 `tool_use` 和 `tool_result` 进行包装，并在一对事件中复用同一个 `tool_call_id`。 +工具调用同样采用相同方式，用 `tool_use` 和 `tool_result` 包裹，两者共用同一个 `tool_call_id`。 -以下是这些事件在仪表板中的呈现效果——按类型色彩编码，可按环境、智能体和会话筛选： +以下是这些事件到达仪表盘后的效果，按类型显示不同颜色，并支持按环境、智能体和会话进行筛选： -![实时事件流，按事件类型色彩编码，可按环境、智能体和会话筛选](/agenteye/images/events-stream.png) +![实时事件流，按事件类型颜色编码，支持按环境、智能体和会话筛选](/agenteye/images/events-stream.png) --- @@ -107,21 +107,21 @@ agenteye.event.model_response( ```python agenteye.configure( - base_dir=None, # Path | str | None. 默认：$AGENTEYE_HOME 或 ~/.agenteye - flush_interval=0.5, # float，刷新周期（秒） + base_dir=None, # Path | str | None. 默认值：$AGENTEYE_HOME 或 ~/.agenteye + flush_interval=0.5, # float，刷新周期间隔（秒） environment=None, # str | None. 部署环境标签 ) ``` -在任何 `event.*` 调用之前调用一次。可以省略，默认配置开箱即用。所有参数均为关键字参数，须按如上所示按名称传入。 +在任何 `event.*` 调用之前调用一次。可省略；默认配置开箱即用。所有参数均为仅关键字参数；请按上方示例使用参数名传递。 -当 `base_dir` 为 `None`（默认值）时，SDK 优先读取 `$AGENTEYE_HOME` 环境变量（若已设置），否则回退到 `~/.agenteye`。这与采集器自身的路径解析逻辑一致，因此只需设置一个 `AGENTEYE_HOME` 环境变量，即可同时为 SDK 和采集器配置共享的事件缓冲目录。 +当 `base_dir` 为 `None`（默认值）时，SDK 会读取 `$AGENTEYE_HOME`（如已设置），否则回退至 `~/.agenteye`。此行为与采集器的解析方式一致，因此只需设置一个 `AGENTEYE_HOME` 环境变量，即可同时为 SDK 和采集器配置共享的事件缓冲目录。 --- ## 环境 -为每个事件打上部署环境标签（如 `production`、`staging`、`qa`、`canary` 等）。只需设置一次，SDK 会自动将其附加到每个事件上。 +为每个事件添加部署环境标签（`production`、`staging`、`qa`、`canary` 等）。设置一次后，SDK 会自动将其附加到每个事件上。 **方式一：通过 `configure()` 设置：** @@ -135,34 +135,34 @@ agenteye.configure(environment="production") export AGENTEYE_ENVIRONMENT=production ``` -**优先级：** `configure(environment=...)` 的优先级高于环境变量。若两者均未设置，默认为 `"dev"`。 +**优先级：** `configure(environment=...)` 优先于环境变量。若两者均未设置，默认值为 `"dev"`。 -环境值在仪表板中作为一级筛选条件显示，并存储在服务端以支持快速查询。 +环境值在仪表盘中作为一级筛选条件，并存储在服务器上以支持快速查询。 -> **警告：** 环境值中不得包含英文逗号 `,`。仪表板筛选器在传输时使用逗号分隔的多选格式（`?environment=prod,staging`），因此名为 `prod,blue` 的环境会被拆分为两个值。包含逗号的环境值在采集时会被拒绝。 +> **警告：** 环境值不得包含英文逗号 `,`。仪表盘筛选器在网络传输时使用逗号分隔的多选格式（`?environment=prod,staging`），因此名为 `prod,blue` 的环境会被拆分为两个值。包含逗号的环境值的事件将在入库时被拒绝。 --- ## 数据与隐私 -SDK 仅记录你显式传入的字段。提示词、消息、工具输入输出及模型内容，只有在你将其传给 `event.*` 方法时才会被捕获。SDK 不会从你的进程中读取任何内容，也不会隐式捕获任何数据。未设置的字段将从事件中完全省略，不会写入磁盘。 +SDK 仅记录您明确传入的字段。提示词、消息、工具输入/输出及模型内容，只有在您将其传递给 `event.*` 调用时才会被捕获。SDK 不会读取您的进程数据，也不会隐式捕获任何内容。您未填写的字段将完全从事件中省略，不会写入磁盘。 -因此，数据脱敏是你的选择，也是你的责任。如果提示词或工具载荷中包含你不希望存储的个人信息或密钥，请在传入事件方法之前进行脱敏或遮蔽处理。 +数据脱敏由您自行决定并承担相应责任。如果提示词或工具负载中包含您不希望存储的个人信息（PII）或密钥，请在传递给事件方法之前进行去除或脱敏处理。 --- ## 事件参考 -大多数事件以开始/结束配对形式出现，并通过关联 ID 绑定：`tool_use` 与 `tool_result` 共享 `tool_call_id`，`hook_triggered` 与 `hook_completed` 共享 `hook_id`，`human_wait` 与 `human_input` 共享 `input_id`。发送开始事件，执行操作，然后用相同的 ID 发送结束事件。Failproof AI Observability 会自动匹配配对并为你计算 `duration_ms`，无需你手动传入。 +大多数事件以开始/结束配对的形式出现，并共享一个关联 ID：`tool_use` 和 `tool_result` 共享 `tool_call_id`，`hook_triggered` 和 `hook_completed` 共享 `hook_id`，`human_wait` 和 `human_input` 共享 `input_id`。发送开始事件，执行相关操作，然后使用相同 ID 发送结束事件。Failproof AI 可观测性会自动匹配配对事件并计算 `duration_ms`，您无需自行传入。 -![会话的 git 风格执行图及其事件时间线，由配对事件重建而成，附有工具/模型/hook 细分面板](/agenteye/images/session-detail.png) +![会话的 git 风格执行图与事件时间线，由配对事件重建而成，以及工具/模型/hook 细分面板](/agenteye/images/session-detail.png) 所有事件方法都需要以下两个字段： -| 字段 | 类型 | 说明 | +| 字段 | 类型 | 描述 | |---|---|---| | `session_id` | `str` | 标识顶层智能体运行 | -| `agent_id` | `str` | 标识会话内发出事件的智能体 | +| `agent_id` | `str` | 标识会话中哪个智能体发出了该事件 | 所有方法还接受任意 `**kwargs` 用于自定义元数据（参见[自定义字段](#custom-fields)）。 @@ -170,7 +170,7 @@ SDK 仅记录你显式传入的字段。提示词、消息、工具输入输出 ### `event.agent_start()` -智能体开始工作时发送。 +智能体开始工作时发出。 ```python agenteye.event.agent_start( @@ -185,7 +185,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -智能体完成工作时发送。 +智能体完成工作时发出。 ```python agenteye.event.agent_end( @@ -200,7 +200,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -智能体调用工具时发送。与 `tool_result` 配对使用，SDK 自动计算 `duration_ms`。 +智能体调用工具时发出。与 `tool_result` 配对；SDK 自动计算 `duration_ms`。 ```python agenteye.event.tool_use( @@ -216,17 +216,17 @@ agenteye.event.tool_use( ### `event.tool_result()` -工具返回结果时发送。通过 `tool_call_id` 与 `tool_use` 关联。 +工具返回结果时发出。通过 `tool_call_id` 与 `tool_use` 关联。 ```python agenteye.event.tool_result( session_id="run-001", agent_id="planner", tool_name="web_search", - tool_call_id="toolu_01", # 必须与前序 tool_use 匹配 + tool_call_id="toolu_01", # 必须与之前的 tool_use 匹配 output={"results": ["..."]}, # Any | None error=None, # str | None - 工具抛出异常时设置 - # duration_ms 自动计算，无需传入 + # duration_ms 自动计算 - 请勿传入 ) ``` @@ -234,13 +234,13 @@ agenteye.event.tool_result( ### `event.model_request()` -向 LLM 发送提示词之前发送。 +向 LLM 发送提示词之前发出。 ```python agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - 任意提供商/模型字符串，不作验证 + model="claude-sonnet-4-6", # str | None - 任意提供商/模型字符串；不做验证 messages=[ # list[dict] | None - 对话轮次 {"role": "user", "content": "..."}, ], @@ -251,19 +251,19 @@ agenteye.event.model_request( ) ``` -`messages` 中的条目支持纯字符串 `content` 或 Anthropic 风格的内容块列表 `content`。采样参数（`temperature`、`max_tokens` 等）可作为额外 kwargs 传入。 +`messages` 条目的 `content` 可以是普通字符串，也可以是 Anthropic 风格的内容块列表。采样参数（`temperature`、`max_tokens` 等）可作为额外 kwargs 传入。 --- ### `event.model_response()` -LLM 返回响应时发送。 +LLM 返回响应时发出。 ```python agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - 任意提供商/模型字符串，不作验证 + model="claude-sonnet-4-6", # str | None - 任意提供商/模型字符串；不做验证 stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None @@ -274,13 +274,13 @@ agenteye.event.model_response( ) ``` -`content` 支持纯字符串（通用提供商）或 Anthropic 风格的内容块列表。工具调用以 `{"type": "tool_use", ...}` 块的形式嵌入 `content` 中，无单独的 `tool_calls` 字段。 +`content` 可以是普通字符串（通用提供商）或 Anthropic 风格的内容块列表。工具调用以 `{"type": "tool_use", ...}` 块的形式存在于 `content` 中，没有单独的 `tool_calls` 字段。 --- ### `event.hook_triggered()` -hook 触发时发送。与 `hook_completed` 配对使用，SDK 自动计算 `duration_ms`。 +hook 触发时发出。与 `hook_completed` 配对；SDK 自动计算 `duration_ms`。 ```python agenteye.event.hook_triggered( @@ -297,18 +297,18 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -hook 执行完成时发送。通过 `hook_id` 与 `hook_triggered` 关联。 +hook 完成时发出。通过 `hook_id` 与 `hook_triggered` 关联。 ```python agenteye.event.hook_completed( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", - hook_id="hook-abc", # 必须与前序 hook_triggered 匹配 + hook_id="hook-abc", # 必须与之前的 hook_triggered 匹配 outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # duration_ms 自动计算，无需传入 + # duration_ms 自动计算 - 请勿传入 ) ``` @@ -316,7 +316,7 @@ agenteye.event.hook_completed( ### `event.error()` -发生未处理错误时发送。 +发生未处理的错误时发出。 ```python agenteye.event.error( @@ -332,40 +332,40 @@ agenteye.event.error( ## 人工干预事件 -人工干预事件让你能够监控人员介入智能体执行的关键时刻（等待审批、提供输入、暂停或停止智能体）。借助这些事件，你可以：衡量人工响应所需时长（SDK 自动计算配对事件的 `duration_ms`）、审计是谁暂停或中断了智能体，以及构建在仪表板中可见的审批和监督工作流。 +人工干预事件让您能够监控人员介入智能体执行流程的关键时刻（等待审批、提供输入、暂停或停止智能体）。通过这些事件，您可以衡量人类响应所需的时间（SDK 对配对事件自动计算 `duration_ms`），审计谁暂停或中断了智能体，并构建在仪表盘中可见的审批和监督工作流。 ### `event.human_wait()` -智能体暂停执行、等待人工输入时发送。与 `human_input` 配对使用，SDK 自动计算 `duration_ms`（即人工响应所需时长）。 +智能体暂停执行、等待人工输入时发出。与 `human_input` 配对；SDK 自动计算 `duration_ms`（即人类响应所需时间）。 ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", input_id="inp-abc", # str，必填 - 与对应 human_input 的关联键 - prompt="Do you approve this action?", # str | None - 向人工展示的问题 - options=["approve", "reject", "defer"], # list[str] | None - 提供给人工的选项 - reason="approval_required", # str | None - 等待原因 + prompt="Do you approve this action?", # str | None - 展示给人类的问题 + options=["approve", "reject", "defer"], # list[str] | None - 呈现给人类的选项 + reason="approval_required", # str | None - 智能体等待的原因 ) ``` ### `event.human_input()` -人工提供输入、智能体恢复执行时发送。通过 `input_id` 与 `human_wait` 关联。`duration_ms` 自动计算，调用方不得传入。 +人类提供输入且智能体恢复执行时发出。通过 `input_id` 与 `human_wait` 关联。`duration_ms` 自动计算，调用方不得传入。 ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str，必填 - 必须与前序 human_wait 匹配 - response="approve", # str | None - 人工的回答（自由文本或所选选项） - # duration_ms 自动计算，无需传入 + input_id="inp-abc", # str，必填 - 必须与之前的 human_wait 匹配 + response="approve", # str | None - 人类的回答（自由文本或所选选项） + # duration_ms 自动计算 - 请勿传入 ) ``` ### `event.human_pause()` -人工主动暂停智能体时发送（例如通过仪表板控件）。智能体被挂起但未终止。 +人类主动暂停智能体时发出（例如通过仪表盘控制）。智能体被挂起但未终止。 ```python agenteye.event.human_pause( @@ -378,7 +378,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -人工在执行过程中主动停止智能体时发送。与 `human_pause` 不同，此事件表示智能体的工作被终止而非挂起。 +人类在智能体执行过程中主动停止智能体时发出。与 `human_pause` 不同，智能体的工作被终止而非挂起。 ```python agenteye.event.human_interrupt( @@ -386,7 +386,7 @@ agenteye.event.human_interrupt( agent_id="planner", reason="output_incorrect", # str | None user_id="usr_42", # str | None - 执行中断操作的用户 - at_step="tool_use:web_search", # str | None - 被停止时智能体正在执行的操作 + at_step="tool_use:web_search", # str | None - 停止时智能体正在执行的操作 ) ``` @@ -394,7 +394,7 @@ agenteye.event.human_interrupt( ## 自定义字段 -任何额外的关键字参数都会附加到标准字段之后： +任何额外的关键字参数都会追加到事件的标准字段之后： ```python agenteye.event.tool_use( @@ -407,25 +407,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`、`type` 和 `environment` 为保留字段，若作为自定义字段传入会引发 `ValueError`（`Reserved field names cannot be used as custom fields: [...]`）。`session_id` 和 `agent_id` 是每个事件方法的必填参数，不能重复传入；若重复传入，Python 会引发 `TypeError`。请通过 `configure(environment=...)` 或 `AGENTEYE_ENVIRONMENT` 变量来设置环境值。 +`timestamp`、`type` 和 `environment` 为保留字段，若作为自定义字段传入，将抛出 `ValueError`（`Reserved field names cannot be used as custom fields: [...]`）。`session_id` 和 `agent_id` 是每个事件方法的必填参数，不能再次传入；若重复传入，Python 会抛出 `TypeError`。请使用 `configure(environment=...)` 或 `AGENTEYE_ENVIRONMENT` 变量来设置环境值。 + +如果您希望对字段内容进行查询，请以结构化 JSON 格式传入负载。JSON 原生不支持的值类型——例如 datetime、UUID、decimal、集合、字节或模型对象——将被转换为字符串，以确保记录能够安全继续。 --- ## 事件写入方式 -事件在进程内缓冲，每隔 `flush_interval` 秒（默认 500 毫秒）刷新到磁盘。每次刷新写入一个 JSONL 文件： +事件在进程内缓冲，并每隔 `flush_interval` 秒（默认 500 毫秒）刷新到磁盘。每次刷新写入一个 JSONL 文件： ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -采集器监控此目录并自动上传文件，你无需直接管理这些文件。 +采集器监视此目录并自动上传文件，您无需直接管理这些文件。 -每个文件采用原子写入方式：SDK 先写入临时文件，再重命名到目标位置，确保采集器不会读取到半写状态的文件。进程退出时还会执行一次最终刷新，避免最后一个间隔内缓冲的事件丢失。如果采集器处于离线状态，事件会以文件形式在磁盘上累积，待采集器恢复后自动上传。 +每个文件以原子方式写入：SDK 先写入临时文件，再重命名到目标路径，因此采集器不会看到写入了一半的文件。进程退出时还会执行一次最终刷新，确保最后一个间隔内缓冲的事件不会丢失。如果采集器离线，事件会以文件形式在磁盘上积累，待采集器恢复后自动上传。 --- ## 后续步骤 -- [事件流](/zh/agenteye/event-stream)：实时查看事件到达情况，按类型色彩编码，可按环境、智能体和会话筛选。 +- [事件流](/zh/agenteye/event-stream)：实时查看这些事件，按类型显示不同颜色，支持按环境、智能体和会话筛选。 - [会话](/zh/agenteye/sessions)：了解配对事件如何将每次智能体运行重建为执行图和时间线。 \ No newline at end of file