kagent وكلاء الذكاء الاصطناعي Kubernetes: الإطار بالتفصيل

kagent وكلاء الذكاء الاصطناعي Kubernetes: وكلاء بصيغة YAML وأدوات MCP واختيار النموذج والتثبيت حسب الوثائق والحدود وتتبعات OpenTelemetry.
kagent agents IA Kubernetes : le framework en détail

kagent وكلاء الذكاء الاصطناعي Kubernetes: يصف مستودع kagent-dev/kagent إطار عمل «أصيلًا في Kubernetes» لبناء وكلاء الذكاء الاصطناعي ونشرهم وإدارتهم. يصبح الوكيل فيه موردًا في Kubernetes، يُعرَّف بصيغة YAML ويُتابَع في Git وتوفّق بينه وبين الحالة الفعلية وحدة تحكم (controller). المستودع بترخيص Apache 2.0، ويقدّم ملف README المشروع على أنه مشروع تابع لـ Cloud Native Computing Foundation.

المشكلة معروفة لدى فرق المنصات. تشغّل كل فرقة وكلاءها بطريقتها، بمفاتيح النماذج والأدوات الخاصة بها، دون رؤية مشتركة. يقترح kagent المرور عبر واجهة Kubernetes البرمجية: النموذج وأدوات MCP وسلوك الوكيل كلها كائنات تصريحية. ماذا يحوي المستودع، وكيف يُثبَّت، وقبل ذلك كله كيف تراقب وكلاء يستدعون أدوات على العنقود (cluster) لديك؟

توضيح للأمانة: لم يثبّت span.observer نظام kagent ولم يشغّله. ما يلي مأخوذ من README ومن مجلد docs/ في المستودع (قُرئ على نسخة مستنسخة في 8 نوفمبر 2026) ومن صفحات الوثائق في kagent.dev. اللقطات مأخوذة من المستودع أو تعيد إنتاج ملفاته.

kagent وكلاء الذكاء الاصطناعي Kubernetes: ما يقوله المستودع

  • الترخيص: يحوي ملف LICENSE نص Apache License 2.0.
  • الجهة المسؤولة: يتبع المستودع منظمة GitHub باسم kagent-dev. ينتهي README بعبارة «kagent is a Cloud Native Computing Foundation project» ولا يسمّي أي ناشر تجاري.
  • اللغات: يضم المستودع وحدة Go (go/ مع go.mod) وحزم Python (python/) وواجهة ويب (ui/) ومخططات Helm. كانت لوحة اللغات في صفحة GitHub فارغة عند القراءة، لذلك لا نذكر أي نسبة مئوية.
  • النجوم: كانت صفحة المستودع تعرض نحو 4.2 ألف نجمة في 8 نوفمبر 2026 (قيمة مقرَّبة). رُفض الوصول إلى GitHub API، فلم تُعَد قراءة أي قيمة دقيقة.
  • الإصدار: لم تعرض صفحة المستودع أي إصدار (release) عند القراءة، ولا نذكر «آخر إصدار» رسميًا. تستخدم وثائق التثبيت للسلسلة 1.x الإصدار v1.0.0-rc3 لأداة CLI: إنه مرشح للإصدار 1.0 وليس إصدارًا نهائيًا.
  • النشاط: يعود آخر commit في النسخة المستنسخة إلى 7 نوفمبر 2026. ويصف README المشروع بأنه «قيد التطوير النشط» مع خارطة طريق على لوحة GitHub.

المفاهيم: الوكلاء والنماذج وأدوات MCP

يسرد README اللبنات. Agent مورد مخصص في Kubernetes. ويحمل AgentTemplate السلوك: موجّه النظام (system prompt) والأدوات والوكلاء الفرعيون والنموذج. ويحدد Harness كيف يعمل الوكيل: بيئات تشغيل Go أو Python الخاصة بـ kagent، أو Codex، أو Claude، أو بيئة تشغيل مخصصة.

تُضبط النماذج في مورد ModelConfig. يذكر README كلًا من OpenAI وAzure OpenAI وAnthropic وGoogle Vertex AI وOllama، إضافة إلى مزوّدين مخصصين خلف بوابة. والخيارات الممكنة تتوقف على Harness المختار.

تمر الأدوات عبر MCP. بحسب README يوفّر kagent خادم MCP بأدوات لـ Kubernetes وIstio وHelm وArgo وPrometheus وGrafana وCilium. ويتصل الوكلاء به عبر موارد RemoteMCPServer التي يمكن مشاركتها بين الوكلاء. وللاطلاع على خطر هذا النموذج اقرأ تسميم أدوات MCP.

تعرض اللقطة الأولى قائمة الوكلاء في واجهة الويب، مأخوذة من صورة GIF في README. وهي من نسخة أقدم من الواجهة، وقد تختلف واجهة الإصدار 1.x عنها.

واجهة ويب kagent مأخوذة من صورة GIF في README: بطاقات وكلاء (gcp-gke-agent وgithub-agent وhashicorp-vault-agent وhelm-agent وistio-agent وk8s-agent وkgateway-agent) مع وصف كل منها والنموذج OpenAI gpt-4.1-mini
Source : github.com

المعمارية: وحدة التحكم وPostgreSQL وSubstrate

تصف وثائق المعمارية مستوى تحكم. يخزّن Kubernetes الإعداد المطلوب (Agent وHarness وAgentTemplate وEgressPolicy وغيرها). ويخزّن PostgreSQL هوية التنفيذ وسجل A2A وحالة دورة الحياة. وتشغّل «Actors» في Substrate عمليات الوكلاء، مع الإيقاف المؤقت والاستئناف واللقطات.

تعرض وحدة التحكم واجهات gRPC وA2A وMCP. تحتفظ الجلسة بالسجل، وتتحدث الوثائق عن نقاط تحقق (checkpoints) لتفريع محادثة. وتسرد الوثائق نفسها ما لم يُنفَّذ بعد: ارتباطات الوكلاء المخصصة، والتفويض بين الجلسات بموجب سياسة، ومشاركة نقاط التحقق، وتنسيق البوابات متعددة النسخ.

تثبيت kagent حسب الوثائق

المتطلبات التي تذكرها صفحة التثبيت للسلسلة 1.x: Kubernetes 1.37 أو أحدث مع واجهتي PodCertificateRequest وClusterTrustBundle؛ وhelm v3 وkubectl؛ ومفتاح API لنموذج. وللعنقود المحلي تذكر الصفحة kind v0.32.0 أو أحدث. ولا يمكن ترقية kagent 1.0 في مكانه انطلاقًا من 0.10.x.

مسار التقييم: أداة CLI

تنشر أداة CLI قاعدة PostgreSQL للتطوير، ثم تثبّت المخططات بالترتيب. أوامر الصفحة (مفتاح وهمي):

kind create cluster --name kagent --image kindest/node:v1.37.0
export OPENAI_API_KEY="your-api-key-here"

curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash -s -- --version v1.0.0-rc3
kagent version

cat > kagent-values.yaml <<EOF
config:
  server:
    grpcReflection: true
EOF
cat > kagent-config.yaml <<EOF
install:
  kagent:
    valuesFiles: [kagent-values.yaml]
EOF

kagent --config kagent-config.yaml install --namespace kagent
kubectl rollout status deployment/kagent-controller -n kagent --timeout=300s

توضح وثائق المستودع أن قاعدة التطوير غير مخصصة للإنتاج، وأن kagent install ينشئ سلطات شهادات صالحة لمدة سنة، ولا شيء يجددها.

مسار الإنتاج: Helm

هنا توفّر أنت PostgreSQL 15 أو أحدث: فالمخططات لا تنشر أي قاعدة. تتسلسل في الصفحة المخططات kagent-crds وsubstrate-crds، ثم مجموعات السلطات ومفاتيح JWT (الإضافة kubectl-ate)، ثم substrate-podcert وsubstrate-atelet وsubstrate، وأخيرًا kagent من oci://ghcr.io/kagent-dev/kagent/helm/kagent. وتبقى ملفات القيم الكاملة في الوثائق الرسمية: لا ننسخها هنا.

التحقق

kubectl get pods -n kagent
kubectl get pods -n ate-system
kubectl get workerpools -n kagent
kubectl port-forward -n kagent svc/kagent-ui 8082:8080

تتوقع الصفحة pods في حالة Running وWorkerPool باسم kagent-default جاهزًا، ثم واجهة على المنفذ المحلي 8082. بعد ذلك ينشئ الدليل «Your first agent» كلًا من Harness وAgentTemplate وAgent، ويتابع الحالة بالأمر kagent agent get.

وكيل معرَّف بصيغة YAML

يحوي مجلد docs/architecture/ مثالًا كاملًا تعيد اللقطة إنتاجه: ModelConfig وRemoteMCPServer في مساحة أسماء مشتركة، وAgentTemplate وAgent في team-a. ويُفترض أن Harness المسمّى runner موجود مسبقًا. الواجهة هي api.kagent.dev/v1alpha3، أي إنها ما زالت نسخة ألفا من واجهة Kubernetes البرمجية.

ملفات YAML من مستودع kagent-dev/kagent: ModelConfig باسم shared-model وRemoteMCPServer باسم shared-tools وAgentTemplate وAgent باسم assistant في مساحة الأسماء team-a مع api.kagent.dev/v1alpha3
Source : github.com

نقاط تستحق التذكر: يشير apiKeySecret إلى Secret في Kubernetes، ويتحكم allowedNamespaces فيمن يستطيع استخدام النموذج أو خادم الأدوات. ومع from: Selector تصل إليه فقط مساحات الأسماء التي تطابق تسمياتها. أما Secret باسم model-auth فيُنشأ على حدة: لا تُنسخ بيانات اعتماده إلى team-a.

الحدود والنقاط المفتوحة

  • النضج: تُقدَّم السلسلة 1.x على أنها مرشح إصدار (rc3 في الوثائق المقروءة)، والواجهة في v1alpha3، ومسار الترحيل من 0.10.x يدوي. وقد يعيد تغيير الإصدار إنشاء اللقطات أو قواعد البيانات (تشير الوثائق إلى عمليات ترحيل غير متوافقة مع الإصدارات السابقة في Substrate).
  • التعقيد: يلزم PostgreSQL وSubstrate وبنية مفاتيح عامة (PKI) داخلية وKubernetes حديث جدًا. ليس مخططًا بسيطًا يكفي تثبيته.
  • صلاحيات RBAC: دون تقييد مساحات الأسماء ينشئ المخطط ClusterRoles وClusterRoleBindings. يميّز README الخاص بـ Helm بين دور مصالحة ودور إدارة يكتب CRD وSecrets وConfigMaps، ويوضح أنه لا يوجد وضع يعطّل هذه الكتابات. قيّد الصلاحيات بـ rbac.namespaces أو global.watchNamespaces.
  • الأسرار: بحسب الوثائق لا توضع مفاتيح النماذج في البيئة المُترجمة: تحقنها بوابة Substrate في ترويسة HTTP الصادرة، مع ذاكرة مؤقتة قد تستغرق حتى خمس دقائق لتتحدث بعد تدوير المفتاح.
  • الأدوات: الوكيل المتصل بخادم أدوات Kubernetes أو Helm يتصرف في العنقود. قيّد صلاحياته ومساحات أسمائه، كما في ضوابط وكلاء الذكاء الاصطناعي في الإنتاج.
  • غير مُتحقَّق منه: الأداء وتكاليف النماذج والسلوك الفعلي للوكلاء. لم نقِس شيئًا.

مراقبة kagent: تتبعات OpenTelemetry

تصف الوثائق تصدير تتبعات OpenTelemetry من وحدة التحكم ومن بيئات تشغيل الوكلاء. لا شيء مفعّل افتراضيًا: يُعرَّف مصدّر OTLP في المخطط. ويقبل الإعداد أيضًا مصدّرين metrics وlogs، لكل منهما endpoint وprotocol (grpc أو http/protobuf) وtimeout.

قيم Helm الخاصة بـ kagent مأخوذة من docs/architecture/telemetry.md: config.telemetry.traces.endpoint نحو controller-collector:4317 وruntimeDefaults.telemetry مع agent-collector:4317 وcaptureContent false وmaxCaptureBytes 16384
Source : github.com

تؤكد صفحة التتبع في kagent.dev أن الكتلة نفسها (block) توضع في config.telemetry (وحدة التحكم) وفي config.runtimeDefaults.telemetry (الوكلاء). وإذا وُضعت في واحد فقط يبقى جزء من المسار دون تتبع. بعد helm upgrade أنشئ جلسة جديدة: فالـ Actor الموجود يحتفظ بالإعداد الذي بدأ به.

يستخدم عقد القياس عن بُعد اصطلاحات GenAI: gen_ai.agent.name وgen_ai.conversation.id وgen_ai.request.model، إضافة إلى سمات kagent.* وa2a.*. وتحمل الـ spans (وحدات العمل داخل التتبع) عمليات مثل invoke_agent وexecute_tool. ولا تُسجَّل الرسائل ووسائط الأدوات إلا إذا فعّلت التقاط المحتوى: أبقِ captureContent: false إلى أن تقيّم الخطر على بياناتك.

نصيحتان من الوثائق ينبغي تطبيقهما. أولًا، أبقِ أخذ العيّنات في SDK من نوع parent-based AlwaysOn وخذ العيّنات في Collector، وإلا قد تكون التتبعات الموزعة ناقصة. ثانيًا، لا تفعّل انتشار baggage إلا عن علم: فأعضاء المستدعي قد يُرسَلون إلى واجهة النموذج وإلى خوادم MCP.

من جهة SRE يمكن استنتاج بعض مؤشرات مستوى الخدمة (SLI) من هذه الـ spans: مدة invoke_agent ومعدل أخطاء execute_tool وعدد استدعاءات النموذج في كل استدعاء. أما تكلفة الرموز (tokens) فانظر تكلفة وكيل ذكاء اصطناعي بالرموز مع OpenTelemetry. وتبقى سجلات وحدة التحكم هي سجلات الأمر kubectl logs deployment/kagent-controller -n kagent. ولا تصف الوثائق المقروءة قائمة مقاييس للمراقبة: ولا نخترع أي قائمة.

وماذا عن Dynatrace؟

لا يوثّق kagent أي تكامل مع Dynatrace، ولا نفترض وجود تكامل. وبما أن kagent يصدّر بصيغة OTLP، يمكن لـ OpenTelemetry Collector أن يستقبل هذه التتبعات. وما بعد ذلك يعود إلى وثائق Dynatrace: انظر OpenTelemetry Collector نحو Dynatrace عبر OTLP/HTTP. لم نختبر هذا الربط.

ممارسات جيدة

  • قيّم kagent على عنقود kind معزول، بمفتاح نموذج ذي سقف إنفاق.
  • أدرج Agent وAgentTemplate وModelConfig في Git وانشرها كما في Argo CD لـ Kubernetes.
  • اقصر rbac.namespaces وallowedNamespaces على الحد الأدنى اللازم.
  • فعّل التتبعات على وحدة التحكم وعلى بيئات التشغيل، مع تعطيل التقاط المحتوى.
  • أعد قراءة ملاحظات الإصدار قبل كل ترقية: فالواجهة البرمجية ما زالت ألفا.

الأسئلة الشائعة

هل kagent جاهز للإنتاج؟

تقترح الوثائق مسار Helm «للإنتاج»، لكن السلسلة 1.x تظهر بوصفها مرشح إصدار والواجهة في v1alpha3. جرّب أولًا، واقرأ قائمة الوظائف غير المنفذة، وخطّط للترحيل من 0.10.x.

ما النماذج التي يقبلها kagent؟

بحسب README: OpenAI وAzure OpenAI وAnthropic وGoogle Vertex AI وOllama، ومزوّدون مخصصون خلف بوابة، عبر ModelConfig. ويتوقف الدعم الدقيق على Harness المختار.

كيف نتابع ما يفعله الوكيل؟

فعّل تصدير تتبعات OTLP في المخطط، على وحدة التحكم وعلى runtimeDefaults، ثم اقرأ الـ spans من نوع invoke_agent وexecute_tool في الواجهة الخلفية لديك. وتُحفظ الجلسات وسجل المهام أيضًا في PostgreSQL.

الخلاصة

يمنح kagent وكلاء الذكاء الاصطناعي إطارًا من Kubernetes: موارد تصريحية وأدوات MCP ونماذج حسب الاختيار وتتبعات OpenTelemetry. يتطلب بنية ثقيلة وعنقودًا حديثًا، ولا تزال واجهته ألفا. إذا أراد فريق المنصة لديك إدارة الوكلاء كبقية أحمالها، فهو يستحق التجربة على عنقود اختبار.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لمشروع kagent ولا لـ Cloud Native Computing Foundation ولا لشركة Dynatrace LLC. العلامات المذكورة تعود إلى مالكيها. الأدوات تتطور بسرعة: تحقق دائمًا من الأوامر والخيارات في وثائقها الرسمية.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
agent-desktop computer use : piloter un bureau par agent IA

agent-desktop computer use: إدارة سطح المكتب بوكيل ذكاء اصطناعي

Next Post
Formation Dynatrace gratuite : 9 parcours pour débuter

دورة Dynatrace مجانية: 9 مسارات للبدء

Related Posts