DEV Community

Cover image for `agentHints`: تعليم CLI للتواصل مع Agents
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

`agentHints`: تعليم CLI للتواصل مع Agents

هذه سلسلة من 10 أجزاء تشرح كيف طورت Apidog أداة Apidog CLI، وهي أداة سطر أوامر لاختبار API وإدارة دورة حياة API. اقرأها بالترتيب أو انتقل مباشرة إلى الجزء الذي تحتاجه:

جرّب Apidog اليوم

# العنوان التركيز
1 بنينا 126 MCP Tools. لكنها ليست الحل الأفضل للـ Agent اكتشاف المشكلة
2 لماذا طورنا Apidog CLI جديد تماما تطوير البنية
3 القاعدة الذهبية: CLI ينتج الحقائق، Model يعمل على الحقائق الفلسفة الأساسية
4 agentHints: تعليم CLI للتواصل مع Agents مخرجات منظمة
5 SKILL: شحن التجربة التشغيلية كـ Code التجربة التشغيلية
6 الأرقام لا تكذب: 30% أقل Tool Calls، 25% أقل Tokens نتائج رقمية
7 من PRD إلى Testing Loop: سير عمل Agent كامل مع Apidog CLI دليل تطبيقي
8 لماذا توافق CI/CD غير قابل للتفاوض لأدوات Agent منظور DevOps
9 AI Branch: تغييرات Project أكثر أمانا مع AI Agents طبقة الأمان
10 Spec-First كان في الماضي. مرحبا بك في Skill-First الرؤية والمستقبل

مخرجات CLI التقليدية موجهة للبشر. لكن Agents تحتاج إلى نتائج منظمة، أسباب فشل واضحة، واقتراحات للخطوة التالية. agentHints يحول خبرة المنتج إلى توجيه قابل للقراءة الآلية.

فجوة مخرجات CLI

معظم أدوات CLI تطبع مخرجات مناسبة للإنسان:

الحالة المخرجات المعتادة
النجاح Success أو Done
النجاح عرض المورد الذي تم إنشاؤه أحياناً
الفشل رسالة خطأ عامة
الفشل stack trace أحياناً

هذا كافٍ عندما يكون المستخدم إنساناً، لأنه يستطيع:

  • تفسير الرسائل غير الدقيقة.
  • تحديد الخطوة التالية.
  • تذكر سياق الأوامر السابقة.
  • استخدام معرفة المجال لاتخاذ قرار.

لكن Agent لا يعمل بهذه الطريقة. هو يحتاج إلى مخرجات يمكن تحليلها وتنفيذ خطوة تالية بناءً عليها.

ما الذي تحتاجه Agents فعلاً؟

Agent لا يحتاج فقط إلى معرفة أن الأمر نجح أو فشل. يحتاج إلى ربط النتيجة بسير العمل التالي.

الحاجة لماذا مهمة؟
نتائج منظمة حتى يمكن تحليل المخرجات برمجياً
أسباب فشل محددة حتى لا يعتمد Agent على رسالة عامة
اقتراحات خطوة تالية حتى يعرف ما يجب فعله بعد الأمر الحالي

مثال:

Resource created successfully
Enter fullscreen mode Exit fullscreen mode

الإنسان يفهم غالباً أن عليه قراءة المورد، التحقق من بنيته، ثم تشغيل اختبارات.

أما Agent فقد يتعامل معها كإشارة للانتقال مباشرة إلى الكتابة التالية، وهذا يسبب مشاكل في سير العمل.

agentHints: الحل

Apidog CLI يضيف كائناً باسم agentHints داخل مخرجات JSON.

مثال على استجابة بعد إنشاء test case:

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "Test case created successfully.",
    "nextSteps": [
      "Read the created test case back to confirm structure.",
      "Add assertions if the test case needs response validation.",
      "Add the test case to a test scenario for integration testing.",
      "Run related tests after adding to scenario."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

البنية الأساسية:

الحقل الغرض
success حالة التنفيذ
data البيانات الفعلية الناتجة عن الأمر
agentHints.summary ملخص قابل للقراءة
agentHints.nextSteps خطوات مقترحة يمكن للـ Agent اتباعها

بهذا الشكل، لا يكتفي CLI بإرجاع النتيجة، بل يعطي Agent سياقاً تشغيلياً للخطوة التالية.

مشكلة Execution Inertia

لاحظنا نمطاً متكرراً في سير عمل Agents:

Agent: ينشئ test case
CLI: يعيد success
Agent: ينشئ test scenario مباشرة
Agent: يشغل الاختبارات مباشرة
النتيجة: scenario ببنية خاطئة، والاختبارات تفشل
Enter fullscreen mode Exit fullscreen mode

المشكلة هنا ليست في الأمر نفسه، بل في أن Agent يتابع التنفيذ ميكانيكياً دون قراءة البنية الفعلية التي أعادها الخادم.

السير الأكثر أماناً يكون عادة:

  1. إنشاء المورد.
  2. قراءة المخرجات.
  3. تأكيد البنية الفعلية.
  4. تنفيذ الخطوة التالية بناءً على البيانات الحقيقية.

لماذا قراءة المخرجات مهمة؟

تجاهل المخرجات الفعلية يؤدي إلى أخطاء عملية:

المشكلة السبب
قيم افتراضية غير متوقعة الخادم قد يملأ حقولاً لم يرسلها Agent
IDs مفقودة أو مختلفة الاستيراد أو الإنشاء قد يولد IDs داخلية جديدة
اختلافات في البنية الواجهة أو الـ API قد تعتمد على شكل محدد
افتراضات خاطئة Agent يتابع بناءً على تخمين، لا على البيانات

القاعدة العملية:

إذا لم يقرأ Agent البنية الفعلية، فهو يكتب الخطوة التالية بناءً على افتراضات.

استخدام agentHints كموجه لسير العمل

agentHints يحول معرفة المنتج إلى تعليمات قابلة للاستهلاك من Agent.

مثال بعد إنشاء test case:

{
  "agentHints": {
    "nextSteps": [
      "Read back the created test case with --with-case-detail flag.",
      "Validate any updates with cli-schema before writing.",
      "Run tests after completing test scenario."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

سير التنفيذ المتوقع:

  1. Agent ينفذ الأمر.
  2. يقرأ JSON الناتج.
  3. يستخرج agentHints.nextSteps.
  4. يبدأ بالخطوة الأولى: قراءة test case.
  5. يستخدم البنية الفعلية قبل أي تعديل أو إنشاء لاحق.

مثال منطقي داخل Agent:

const result = await runCliCommand();

if (result.success && result.agentHints?.nextSteps?.length) {
  const firstStep = result.agentHints.nextSteps[0];

  if (firstStep.includes("Read back")) {
    await readCreatedResource(result.data.id);
  }
}
Enter fullscreen mode Exit fullscreen mode

الفكرة ليست أن Agent ينفذ النص حرفياً دائماً، بل أن النص يعطيه إشارة تشغيلية واضحة.

كيف يتغير دور CLI؟

مع agentHints، دور CLI لا يبقى مجرد تنفيذ أوامر.

الدور التقليدي الدور مع agentHints
منفذ أوامر موجه سير عمل
طباعة نتيجة اقتراح خطوة تالية
مخرجات للبشر بنية قابلة للقراءة الآلية
استجابة لمرة واحدة توجيه مستمر عبر الخطوات

بهذا يصبح CLI طبقة خفيفة لإدارة الحالة التشغيلية للـ Agent.

أشجار سير عمل مدمجة

Apidog CLI يحتوي على أشجار سير عمل منظمة تساعد Agent على اتخاذ القرار التالي حسب السياق.

هذه التوجيهات ليست مجرد رسائل ثابتة، بل تعتمد على:

النوع الوصف
السياق الاقتراح يتغير حسب العملية الحالية
نوع المورد endpoint، test case، scenario، وغيرها
تسلسل العمل الاقتراح يعكس الخطوة المنطقية التالية
حالة النجاح أو الفشل الفشل ينتج اقتراحات تصحيح مختلفة

مثال بعد تحديث test scenario بنجاح:

{
  "agentHints": {
    "summary": "Test scenario updated successfully.",
    "nextSteps": [
      "Run the test scenario to verify changes.",
      "Check the test report for any failures.",
      "If failures occur, read back scenario steps for debugging."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

مثال بعد فشل validation:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'comparator' has invalid value",
    "details": []
  },
  "agentHints": {
    "summary": "Validation failed. Fix the errors and re-validate.",
    "nextSteps": [
      "Review the error details in the output.",
      "Adjust the JSON file based on error suggestions.",
      "Re-run cli-schema validate before writing."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

حتى في حالة الفشل، يحصل Agent على مسار تصحيح واضح بدلاً من رسالة خطأ معزولة.

حلقة عمل أكثر أماناً باستخدام agentHints

سير عمل عملي:

1. Agent ينشئ test case
   ↓
2. CLI يعيد success + agentHints
   ↓
3. agentHints.nextSteps[0]:
   "Read back the created test case"
   ↓
4. Agent يقرأ test case بالبنية الفعلية
   ↓
5. CLI يعيد data + agentHints
   ↓
6. agentHints.nextSteps[0]:
   "Add assertions if needed"
   ↓
7. Agent يضيف assertions بناءً على البنية الفعلية
   ↓
8. CLI يعيد success + agentHints
   ↓
9. agentHints.nextSteps[0]:
   "Run tests"
   ↓
10. Agent يشغل الاختبارات
   ↓
11. CLI يعيد تقرير الاختبار
Enter fullscreen mode Exit fullscreen mode

النتيجة: لا قفزات عمياء، ولا متابعة مبنية على افتراضات.

مقارنة: مع وبدون agentHints

السيناريو بدون agentHints مع agentHints
بعد الإنشاء Agent ينتقل مباشرة للكتابة التالية Agent يقرأ المورد أولاً
بعد التحديث Agent يفترض أن البنية صحيحة Agent يتحقق من البنية
بعد نجاح validation Agent يكتب فوراً Agent يكتب ثم يقرأ النتيجة
بعد فشل validation Agent يحاول التخمين Agent يتبع اقتراحات تصحيح
بعد تشغيل الاختبار Agent يرى نجاح/فشل فقط Agent يحصل على توجيه للفحص التالي

نمط تنفيذ عملي للـ Agents

عند بناء Agent يتعامل مع CLI، اجعل قراءة agentHints جزءاً ثابتاً من الحلقة:

async function handleCliResult(result) {
  if (!result.success) {
    console.error(result.error);

    if (result.agentHints?.nextSteps) {
      return {
        action: "fix",
        suggestions: result.agentHints.nextSteps
      };
    }

    return { action: "stop" };
  }

  const nextSteps = result.agentHints?.nextSteps ?? [];

  return {
    action: "continue",
    data: result.data,
    nextSteps
  };
}
Enter fullscreen mode Exit fullscreen mode

ثم استخدمها في كل أمر:

const createResult = await createTestCase();
const decision = await handleCliResult(createResult);

if (decision.nextSteps[0]?.includes("Read")) {
  await readTestCase(decision.data.id);
}
Enter fullscreen mode Exit fullscreen mode

هذا النمط يقلل قرارات التخمين ويجعل كل خطوة مبنية على ناتج الأمر السابق.

ما التالي؟

الآن يمكن لـ CLI توجيه Agents خلال الخطوات التالية. السؤال المتبقي هو:

كيف يعرف Agent أي سير عمل يجب اتباعه من البداية؟

في الجزء 5، SKILL: شحن التجربة التشغيلية كـ Code، سنشرح كيف يحزم SKILL معرفة سير العمل: متى تُستخدم الأوامر، ما التتابع الصحيح، وما المجالات التي لا يجب أن يخمنها Agent.

النقاط الرئيسية

  • مخرجات CLI التقليدية موجهة للبشر، بينما Agents تحتاج إلى توجيه منظم.
  • agentHints يضيف summary و nextSteps إلى مخرجات JSON.
  • قراءة المخرجات بعد كل عملية تمنع استمرار Agent بناءً على افتراضات.
  • CLI يتحول من منفذ أوامر إلى موجه سير عمل.
  • الفشل يصبح actionable عندما يحتوي على أسباب واضحة وخطوات تصحيح.
  • أفضل حلقة عمل: نفّذ، اقرأ، تحقق، ثم تابع.

حمّل Apidog لـ تصميم، mock، اختبار، وتوثيق APIs في مساحة عمل واحدة. تعلّم أكثر عن Apidog CLI لاختبار API من سطر الأوامر، CI automation، وسير عمل AI Agent.

Top comments (0)