كيف تعمل المكتبة من الداخل؟

استخدم البنية لتحديد مكان القرار

لتطوير التطبيق، ابدأ بـتصميم الإعداد. هذا المرجع لفهم موضع فرض السلوك أو تتبّع خطأ داخل المكتبة مفتوحة المصدر.

في مثال الحجز، يفحص الـ Compiler العلاقات بين الـ Tools وينشئ تعريفًا للـ AI Model وتعريفًا للتنفيذ. يحدد الـ Router العملية المقصودة، ويدير الـ Runtime خطوات الـ Dependencies وحالات المتابعة. بعد ذلك يجهّز الـ Mapper طلب HTTP، ويتولى الـ Executor إرساله، ويضمن الـ Store معالجة التفاعلات بالتتابع.

تجيب كل طبقة عن سؤال مختلف. يثبت اختبار compiler رفض إعداد غير آمن، ويثبت اختبار mapper القيمة الخارجة، ويثبت اختبار Runtime عدم الكتابة قبل الموافقة، ويثبت اختبار Provider معالجة البروتوكول. لا يغني أي منها عن اختبار صلاحيات API في تطبيقك.

تتبّع تغيير إعداد واحد

تؤثر إضافة depends_on.map في تجهيز الـ Config وتنفيذها: يخفي الـ Compiler حقول المستوى الأول التي توفرها الـ Dependency عن الـ Input المعروض للـ AI Model، ثم يملؤها الـ Runtime من البيانات التي جلبها. وتضيف confirmation.required توقفًا بعد تجهيز الـ Request لانتظار الموافقة. أما response.model_view فتغيّر البيانات المتاحة لصياغة الرد، ولا تغيّر طلب HTTP أو شكل الـ Response الأصلي من الـ API.

عند فحص مشكلة، حدّد أي تعريف أو قواعد تغيّرت، ثم أعد إنتاج المشكلة في الوحدة المسؤولة عنها قبل تتبّع النظام كاملًا. تساعدك خريطة المصدر أدناه في الوصول إلى الكود المعني.

تصميم بطبقات

┌─────────────────────────────────────────────┐
│ Host application                            │
│ web · Discord · CLI · MCP                   │
└───────────────────┬─────────────────────────┘
                    │
┌───────────────────▼─────────────────────────┐
│ AgentRuntime API                            │
│ chat · invoke · select · confirm · cancel   │
└───────────────────┬─────────────────────────┘
                    │
┌───────────────────▼─────────────────────────┐
│ Session + explicit state machine            │
│ history · facts · frames · refs · pending   │
└───────────────────┬─────────────────────────┘
                    │
┌───────────────────▼─────────────────────────┐
│ Hybrid routing                              │
│ lexical → semantic recall → model selection │
└───────────────────┬─────────────────────────┘
                    │
┌───────────────────▼─────────────────────────┐
│ Deterministic orchestration                 │
│ input → dependencies → selection → confirm  │
└───────────────────┬─────────────────────────┘
                    │
┌───────────────────▼─────────────────────────┐
│ Execution boundary                          │
│ mapping → auth → HTTP → validate → redact   │
└───────────────────┬─────────────────────────┘
                    │
┌───────────────────▼─────────────────────────┐
│ Existing REST APIs                          │
│ authentication · authorization · business   │
└─────────────────────────────────────────────┘

الفصل أثناء compilation

يتحوّل تعريف الـ Tool في YAML إلى تمثيلين داخل Runtime:

                 tool config
                     │
          ┌──────────┴──────────┐
          ▼                     ▼
model-facing registry      execution registry
name                       URL/method
summary                    auth
input schema               mappings
                           dependencies
                           retries
                           effect/confirmation
                           output validation

يقلّل هذا الفصل المعلومات التي يحتاج الـ AI Model إلى رؤيتها.

وحدات المصدر الأساسية

src/v2/
  config/           strict schema + compiler + migration
  conversation/     safe no-tool conversation/presentation prompts
  execution/        explicit value-source mapping
  http/             bounded transport, retry, circuit breaker
  mcp/              protocol-independent tools/list + tools/call adapter
  models/           model capability interface + provider adapters
  observability/    rate limiter, hooks, metrics
  runtime/          AgentRuntime orchestration + state transitions
  security/         redaction
  session/          state, facts, frames, transaction contract
  tools/            lexical retrieval, semantic recall, routing, evals

حدود الثقة

الـ AI Model

يُوثق به لتفسير اللغة ضمن Schemas يجري التحقق منها. ولا يُوثق به لبيانات الاعتماد أو IDs التي يملكها الخادم أو صلاحية التنفيذ أو حقائق العمل التي لم يتلقّها.

Runtime

يُوثق به لتطبيق القواعد التي جهّزها الـ Compiler، واستمرارية الـ Session، والـ Mapping، والـ Confirmation، وضوابط النقل، وحجب البيانات الحساسة.

التطبيق المضيف

يربط التطبيق المضيف كل Session ID بالمستخدم الفعلي، ويوفر السياق وبيانات الاعتماد الخاصة بكل Request.

API المستقبِلة

هي المرجع للـ Auth والصلاحيات وصحة البيانات والآثار الفعلية على العمل.

لماذا يهم هذا الفصل؟

يضبط Runtime في V2 ما يمكن تنفيذه وفق الـ Config. يشارك الـ AI Model في فهم اللغة، بينما يطبق الـ Runtime قواعد محددة في الخطوات التي تؤثر على الأمان وصحة النتائج. لذلك تتجاوز وظيفته مجرد إتاحة fetch للـ AI Model.