agent-sandbox في Kubernetes: يقدّم مستودع kubernetes-sigs/agent-sandbox موردًا مخصصًا باسم Sandbox مع متحكم (controller) لتشغيل أحمال معزولة ذات حالة وبنسخة واحدة، مثل بيئة تشغيل (runtime) وكيل ذكاء اصطناعي ينفّذ شيفرة أنتجها نموذج. يُستضاف المشروع ضمن منظمة Kubernetes SIGs تحت مظلة SIG Apps. تعرض صفحة المستودع نحو 4400 نجمة ونحو 590 فرعًا (fork) في 29 أكتوبر 2026، بترخيص Apache 2.0.
بالنسبة لمهندس SRE أو فريق المنصة، السؤال مزدوج. أولًا، ماذا يفعل هذا المتحكم فعلًا وماذا لا يفعل؟ ثانيًا، عندما تُنشأ عشرات أو مئات البيئات المعزولة (sandboxes) وتُحذف كل دقيقة، كيف تعرف أنها تبدأ بسرعة، وأنها تنتهي كما هو مخطط، وأن المتحكم يتحمل الحمل؟ يتبع هذا المقال ملف README ووثائق المستودع وموقع agent-sandbox.sigs.k8s.io.
توضيح للأمانة: لم تثبّت span.observer أداة agent-sandbox. الأوامر مأخوذة من README ووثائق المشروع؛ واللقطات تعيد مقاطع من المستودع أو مأخوذة منه مباشرة.
agent-sandbox في Kubernetes: ماذا يقول المستودع
- المشروع: يقدّم README أداة agent-sandbox على أنها CRD باسم
Sandboxومتحكم Kubernetes مطوَّران ضمن SIG Apps. واجهة API المقدَّمة هيagents.x-k8s.io/v1beta1؛ وتشير خارطة الطريق إلى أنv1beta1أصبح الإصدار الوحيد المقدَّم وأنv1alpha1أُزيل. - الترخيص واللغة: Apache 2.0، تم التحقق منه في ملف LICENSE بالمستودع في 29 أكتوبر 2026. المتحكم مكتوب بلغة Go؛ وتتوفر SDK للغتي Go وPython.
- الإصدار: تعرض صفحة الإصدارات v1.0.8 بوصفه الإصدار الأخير، صدر في 22 أكتوبر 2026، مع إصدارات أسبوعية منذ نهاية سبتمبر. أما Helm chart في المستودع فبالإصدار 0.1.4.
- النطاق: README صريح، agent-sandbox منسّق (orchestrator) للبيئات المعزولة. أما العزل فيُفوَّض إلى بيئة تشغيل آمنة مثل gVisor أو Kata Containers، تُختار عبر
RuntimeClassفي قالب الـ pod. ومن دون هذه البيئة، يكون Sandbox مجرد pod عادي. - حالات الاستخدام المذكورة: بيئات تشغيل وكلاء الذكاء الاصطناعي التي تنفّذ شيفرة غير موثوقة، وحلقات التعلم المعزز، وبيئات التطوير، ودفاتر notebooks، والخدمات ذات النسخة الواحدة.
جولة في ملفات manifest
يشبه Sandbox كائن StatefulSet بحجم 1 مع دورة حياة خاصة. وفق README، يحصل كل Sandbox على اسم مضيف ثابت، ويمكنه الحصول على تخزين دائم، ويمكن إيقافه مؤقتًا ثم استئنافه. ومثال البداية في README لا يتجاوز عشرة أسطر.

تضيف وحدة extensions ثلاثة موارد في المجموعة extensions.agents.x-k8s.io/v1beta1:
SandboxTemplate: قالب قابل لإعادة الاستخدام لإنشاء Sandboxes متشابهة؛SandboxWarmPool: مجمّع (pool) من Sandboxes مسخّنة مسبقًا وجاهزة للتخصيص؛SandboxClaim: طلب Sandbox، يُلبّى من مجمّع عندما يكون ذلك ممكنًا.
يشرح quickstart المستودع الآلية: ينشئ المجمّع Sandboxes موسومة بـ agents.x-k8s.io/warm-pool-sandbox، ثم تتبنّى SandboxClaim واحدًا منها، ويُنشئ المجمّع بديلًا للحفاظ على عدد النسخ. ويعلن المستند نفسه عن تخصيص في أقل من ثانيتين مع المجمّع، مقابل 10 إلى 30 ثانية من دونه (سحب الصورة وبدء الحاوية أو الآلة الافتراضية). هذه أرقام المشروع، لا قياس من span.observer.
أما ما يفعله الوكيل بعد ذلك داخل البيئة المعزولة فيعتمد على الصورة. يعرض مثال analytics-tool في المستودع وكيلًا يولّد شيفرة pandas وmatplotlib، وينفّذها في pod الخاص بـ Sandbox، ويعيد رسمًا بيانيًا مرمّزًا بـ base64.

التثبيت خطوة بخطوة
الخطوة 1: المتطلبات
عنقود Kubernetes وأداة kubectl. يقترح دليل التثبيت في الموقع عنقود KinD أو GKE؛ ويطلب quickstart الإصدار 1.28 أو أحدث من kubectl، وللعزل الفعلي، عنقودًا مضبوطًا فيه gVisor أو Kata Containers.
الخطوة 2: تثبيت المتحكم والامتدادات
يوصي README بتثبيت الإصدار للإنتاج ولـ GitOps:
export VERSION="v1.0.8"
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/sandbox-with-extensions.yaml
يتوفر أيضًا ملفا sandbox.yaml (النواة فقط) وextensions.yaml منفصلين. ويُقدَّم Helm chart في مجلد helm/ بالمستودع؛ ويوضح README الخاص به أن image.tag إلزامي وأن Helm لا يحدّث CRD الموجودة في مجلد crds/ أثناء helm upgrade.
الخطوة 3: التحقق
kubectl get crd sandboxes.agents.x-k8s.io
kubectl get deploy agent-sandbox-controller -n agent-sandbox-system
الخطوة 4: إنشاء Sandbox وانتظار Ready
طبّق manifest الموجود في اللقطة مع صورة من اختيارك، ثم انتظر الشرط Ready. توضح صفحة «Status Conditions» في الوثائق أن Ready هو الإشارة المرجعية: ولا يوجد شرط Running عمدًا.
kubectl wait sandbox/my-sandbox --for=condition=Ready --timeout=2m
kubectl get sandbox my-sandbox -o jsonpath='{.status.conditions[?(@.type=="Ready")].reason}'
تتبع SDK المنطق نفسه: pip install k8s-agent-sandbox لـ Python، وgo get sigs.k8s.io/agent-sandbox/clients/go/sandbox@latest لـ Go. وتمر عبر Sandbox Router، وهو reverse proxy اختياري لبروتوكول HTTP يوجّه الطلبات إلى الـ pod، ويفيد عندما لا يتوفر port-forward المباشر مع Kata أو gVisor.
مراقبة البيئات المعزولة: المقاييس والشروط والتتبعات
هنا يتميز المشروع عن كثير من المستودعات الرائجة: قابلية الملاحظة (observability) موثّقة. يسرد ملف docs/metrics.md، المولَّد من الشيفرة، عائلات مقاييس Prometheus التي يعرضها agent-sandbox-controller على --metrics-bind-address (افتراضيًا :8080).

القراءات المفيدة لهدف مستوى الخدمة (SLO):
agent_sandbox_creation_latency_ms: مدرج تكراري للمدة بين إنشاء Sandbox وأول انتقال له إلى Ready، حسبnamespaceوlaunch_typeوsandbox_template. وتحذر الوثائق من أن دقة الطوابع الزمنية المصدرية هي الثانية.agent_sandbox_claim_startup_latency_msوagent_sandbox_client_claim_startup_latency_ms: المدة من طرف إلى طرف لطلب SandboxClaim، منذ رصده بواسطة webhook أو منذ الطابع الزمني للعميل، حتى Ready. ولا تُسجَّل إلا إذا حمل الطلب التعليق التوضيحي (annotation) المقابل.agent_sandbox_warmpool_size: حجم كل مجمّع، موسومًا بـsandbox_status؛ والمجمّع الذي يفرغ أثناء موجة طلبات يظهر هنا.agent_sandboxes: عدد Sandboxes في العنقود، معready_conditionوexpired.agent_sandbox_expired_totalوagent_sandbox_finished_total: حالات الانتهاء بسببshutdownTimeوالـ pods التي بلغت مرحلة نهائية، مع السبب.agent_sandbox_suspend_latency_msوagent_sandbox_resume_latency_ms: كلفة الإيقاف المؤقت والاستئناف.
تُضاف إلى هذه العائلات مقاييس controller-runtime القياسية، وإذا بقي --enable-rest-client-metrics على true، عائلات rest_client_* من client-go (زمن الطلبات وإعادة المحاولات). ولجمع كل ذلك يكفي OpenTelemetry Collector مع receiver لـ Prometheus؛ انظر OpenTelemetry Collector على Kubernetes وPrometheus وDynatrace على Kubernetes.
على صعيد التتبعات، يفعّل الخيار --enable-tracing (افتراضيًا false) تصدير OTLP من المتحكم. ولا يوجد خيار لعنوان Collector: يقرأ المصدّر المتغيرين القياسيين OTEL_EXPORTER_OTLP_ENDPOINT وOTEL_EXPORTER_OTLP_INSECURE. نقطة تشغيلية يجب تذكرها: إذا فشلت تهيئة المصدّر، يسجّل المتحكم الخطأ ويتوقف عند البدء. وتضع SDK الخاصة بـ Go وPython التعليق التوضيحي opentelemetry.io/trace-context على SandboxClaim، مما يربط تتبّع العميل بتتبّع المتحكم. كما تعرض وثائق SDK الخاصة بـ Python أداة قياس محلية عبر pip install "k8s-agent-sandbox[tracing]" opentelemetry-distro ثم opentelemetry-instrument python main.py.
مع Dynatrace، تُستوعب مقاييس Prometheus هذه وتتبعات OTLP هذه بالطريقة نفسها كأي مكوّن Kubernetes، في SaaS (مع Grail وDQL) كما في Managed (من دون DQL). المتحكم والـ router خدمتان تُراقبان كغيرهما؛ أما ما يجري داخل البيئة المعزولة فمسؤولية الوكيل نفسه، انظر الحواجز الوقائية لوكلاء الذكاء الاصطناعي في الإنتاج.
الحدود ونقاط مفتوحة
- لا يوفر المشروع أي عزل بنفسه: من دون
runtimeClassNameلـ gVisor أو Kata، تعمل الشيفرة التي ولّدها النموذج في حاوية قياسية. ويقول نموذج التهديدات في المستودع ذلك بوضوح ويوصي بفرض بيئة التشغيل عبرSandboxTemplate. - وفق نموذج التهديدات، يُطبَّق وضع «Managed NetworkPolicy» (ingress مقصور على الـ router، وegress من دون شبكات RFC 1918 ولا بيانات cloud الوصفية) عند المرور عبر SandboxTemplate؛ وبالمثل، لا يُفرض
automountServiceAccountTokenعلىfalseإلا في Sandboxes المنشأة من قالب. أماSandboxالمجرد فيجب تأطيره بسياسة admission. - ينشر دليل التثبيت في الموقع الـ router مع تعطيل المصادقة وصورة staging، «للاختبار المحلي فقط» وفق تحذير المشروع.
- حذف CRD يحذف تسلسليًا كل Sandboxes في العنقود، كما يحذر README.
- في خارطة الطريق، ما زال في حالة «planned»: الإيقاف المؤقت التلقائي والتوسع إلى الصفر، وخادم MCP أصلي، وقياسات Prometheus إضافية، وواجهة ويب. وتُظهر الإصدارات الأسبوعية مشروعًا فتيًا ونشطًا: راجع ملاحظات الإصدار قبل كل تحديث.
أفضل الممارسات
- أنشئ تنبيهات على
agent_sandbox_warmpool_sizeوعلى المئين 95 لـagent_sandbox_creation_latency_ms: فهما مؤشرا مستوى الخدمة (SLI) لبدء التشغيل. - أبقِ
--enable-pprof-debugمعطّلًا في الإنتاج؛ فالوثائق تشير إلى أن هذه النقاط تكشف محتوى الذاكرة (heap) والـ goroutines. - حدّد
shutdownTimeوresources.limitsفي كل قالب: فالبيئة المعزولة بلا نهاية ولا حد كلفة وخطر. - اربط أحداث Kubernetes الصادرة عن المتحكم بـ تنبيهاتك على العقد والـ pods والحصص، مع ملاحظة أن
--disable-sandbox-eventsيقطعها عند الحمل المرتفع. - لتوسيع المجمّعات، يحتوي المستودع على مثال
keda-scale-to-zero؛ انظر KEDA للتوسع التلقائي في Kubernetes. ولمقاربة أخرى لبيئات تشغيل الوكلاء، انظر NVIDIA OpenShell.
الأسئلة الشائعة
هل يعزل agent-sandbox الشيفرة التي ينفّذها الوكيل؟
لا، ليس بنفسه. يصفه README بأنه منسّق يفوّض العزل إلى gVisor أو Kata Containers عبر RuntimeClass. ويجب ضبط بيئة التشغيل هذه في قالب الـ pod.
ما المقاييس التي يعرضها المتحكم؟
مقاييس Prometheus على :8080 افتراضيًا، مسرودة في docs/metrics.md: أزمنة الإنشاء والطلب والإيقاف المؤقت والاستئناف، وحجم warm pools، وعدد Sandboxes، وحالات الانتهاء ونهايات الـ pods.
هل يمكن تتبّع العمليات عبر OpenTelemetry؟
نعم. يفعّل --enable-tracing تصدير OTLP من المتحكم، المضبوط عبر OTEL_EXPORTER_OTLP_ENDPOINT. وتنشر SDK سياق التتبّع عبر التعليق التوضيحي opentelemetry.io/trace-context.
الخلاصة
يقدّم agent-sandbox إلى Kubernetes عنصرًا أساسيًا كان ينقص الفرق التي تشغّل وكلاء الذكاء الاصطناعي: pod معزول، ذو اسم، قابل للإيقاف المؤقت، يُقدَّم من مجمّع ساخن. وينشر متحكمه ما يلزم لمراقبته منذ اليوم الأول، شرط معاملته كمكوّن إنتاجي: بيئة تشغيل معزولة مفروضة، ومقاييس مجمَّعة، وتتبعات مفعّلة بحذر. المصادر: مستودع kubernetes-sigs/agent-sandbox ووثائق agent-sandbox.sigs.k8s.io.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.