การสอน CLI ให้สื่อสารกับ Agent

นี่คือบทความ 10 ตอนที่แชร์ว่า Apidog พัฒนา Apidog CLI ซึ่งเป็นเครื่องมือบรรทัดคำสั่งสำหรับการทดสอบ API และการจัดการวงจรชีวิต API ได้อย่างไร อ่านตามลำดับหรือข้ามไปบทความที่คุณสนใจ:

ผลลัพธ์ CLI แบบดั้งเดิมมีไว้สำหรับมนุษย์ Agent ต้องการผลลัพธ์ที่มีโครงสร้าง เหตุผลของความล้มเหลว และข้อเสนอแนะสำหรับขั้นตอนต่อไป agentHints เปลี่ยนประสบการณ์ผลิตภัณฑ์ให้เป็นคำแนะนำที่เครื่องอ่านได้

ช่องว่างของผลลัพธ์ CLI

ผลลัพธ์ CLI แบบดั้งเดิมถูกออกแบบมาสำหรับ มนุษย์

สิ่งนี้ใช้ได้ผลสำหรับคน เพราะมนุษย์สามารถ:

• ตีความข้อความที่ไม่ชัดเจนได้
• ตัดสินใจว่าจะทำอะไรต่อไปได้
• จดจำบริบทจากคำสั่งก่อนหน้าได้
• ประยุกต์ใช้ความรู้เฉพาะทางเพื่อดำเนินการต่อไปได้

แต่ Agent ทำงานต่างออกไป

สิ่งที่ Agent ต้องการจริงๆ

Agent ไม่ได้แค่อ่านผลลัพธ์เท่านั้น พวกเขาต้องการ เชื่อมโยงผลลัพธ์เข้ากับห่วงโซ่งานถัดไป

มนุษย์เห็น "Resource created successfully" และรู้ว่า: "ฉันน่าจะตรวจสอบสิ่งที่ถูกสร้างขึ้น แล้วอาจจะทำการทดสอบบางอย่าง"

Agent เห็น "Resource created successfully" และ... ไม่รู้ว่าจะทำอะไรต่อไป

agentHints: ทางออก

Apidog CLI เพิ่ม agentHints ลงในผลลัพธ์ของมัน

นี่คือลักษณะการตอบสนองทั่วไป:

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "กรณีทดสอบถูกสร้างสำเร็จแล้ว",
    "nextSteps": [
      "อ่านกรณีทดสอบที่สร้างขึ้นกลับเพื่อยืนยันโครงสร้าง",
      "เพิ่มการยืนยัน (assertions) หากกรณีทดสอบต้องการการตรวจสอบการตอบสนอง",
      "เพิ่มกรณีทดสอบนี้ลงในสถานการณ์ทดสอบ (test scenario) สำหรับการทดสอบการรวมระบบ",
      "เรียกใช้การทดสอบที่เกี่ยวข้องหลังจากเพิ่มลงในสถานการณ์"
    ]
  }
}

สามองค์ประกอบ:

ปัญหาความเฉื่อยของการดำเนินการ

นี่คือปัญหาจริงที่เราพบ:

หลังจากสร้างทรัพยากรสำเร็จแล้ว โมเดลมักจะดำเนินการสร้างงานเขียนถัดไปโดยตรง

ตัวอย่าง:

Agent: สร้างกรณีทดสอบ
CLI: ส่งคืนความสำเร็จ
Agent: สร้างสถานการณ์ทดสอบทันที (โดยไม่อ่านกลับ)
Agent: เรียกใช้การทดสอบทันที
ผลลัพธ์: สถานการณ์มีโครงสร้างผิดพลาด การทดสอบล้มเหลว

ในกระบวนการทางธุรกิจที่ซับซ้อน การดำเนินการต่อเนื่องเชิงกลไม่เหมาะสม

แนวทางที่ถูกต้องที่สุดมักจะเป็น:

1. สร้างทรัพยากร
2. อ่านกลับก่อน
3. ยืนยันโครงสร้าง
4. แล้วจึงดำเนินการต่อ

ทำไมการอ่านกลับจึงสำคัญ

การข้ามการอ่านกลับทำให้เกิดปัญหาจริง:

หากโครงสร้างจริงไม่ถูกอ่านกลับ Agent จะดำเนินการเขียนต่อไปตามการคาดเดาของตนเองได้อย่างง่ายดาย ซึ่งไม่ใช่ข้อมูลจริง

agentHints ในฐานะผู้นำทาง

agentHints เปลี่ยนประสบการณ์ผลิตภัณฑ์ให้เป็นคำแนะนำขั้นตอนต่อไปที่เครื่องอ่านได้

มันปรากฏขึ้น ตรงจุดที่ Agent ต้องการทำการตัดสินใจ

ตัวอย่างหลังจากสร้างกรณีทดสอบ:

{
  "agentHints": {
    "nextSteps": [
      "อ่านกรณีทดสอบที่สร้างขึ้นกลับด้วยแฟล็ก --with-case-detail",
      "ตรวจสอบการอัปเดตใดๆ ด้วย cli-schema ก่อนเขียน",
      "เรียกใช้การทดสอบหลังจากเสร็จสิ้นสถานการณ์ทดสอบ"
    ]
  }
}

Agent จะ:

1. อ่านผลลัพธ์
2. แยกวิเคราะห์ agentHints
3. ทำตาม nextSteps[0]: อ่านกรณีทดสอบกลับ
4. ยืนยันโครงสร้างจริง
5. แล้วจึงดำเนินการต่อด้วยข้อมูลที่ถูกต้อง

การเปลี่ยนบทบาทของ CLI

สิ่งนี้เปลี่ยนความหมายของ CLI ในเวิร์กโฟลว์ของ Agent

CLI กลายเป็นตัวนำทางสถานะที่มีน้ำหนักเบา

โครงสร้างเวิร์กโฟลว์ในตัว

Apidog CLI มี เวิร์กโฟลว์แบบต้นไม้หลายพันรายการ ที่สร้างขึ้นมาในตัว

สิ่งเหล่านี้ไม่ใช่แค่คำแนะนำที่ฮาร์ดโค้ดไว้เท่านั้น แต่ยังเป็น:

ตัวอย่างหลังจากอัปเดตสถานการณ์ทดสอบสำเร็จ:

{
  "agentHints": {
    "summary": "สถานการณ์ทดสอบอัปเดตสำเร็จแล้ว",
    "nextSteps": [
      "เรียกใช้สถานการณ์ทดสอบเพื่อตรวจสอบการเปลี่ยนแปลง",
      "ตรวจสอบรายงานการทดสอบสำหรับข้อผิดพลาดใดๆ",
      "หากเกิดข้อผิดพลาด ให้อ่านขั้นตอนสถานการณ์กลับเพื่อแก้ไขข้อบกพร่อง"
    ]
  }
}

ตัวอย่างหลังจากความล้มเหลวในการตรวจสอบความถูกต้อง:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "ฟิลด์ 'comparator' มีค่าไม่ถูกต้อง",
    "details": [...]
  },
  "agentHints": {
    "summary": "การตรวจสอบความถูกต้องล้มเหลว แก้ไขข้อผิดพลาดและตรวจสอบซ้ำ",
    "nextSteps": [
      "ตรวจสอบรายละเอียดข้อผิดพลาดในผลลัพธ์",
      "ปรับไฟล์ JSON ตามคำแนะนำข้อผิดพลาด",
      "เรียกใช้ cli-schema validate ซ้ำก่อนเขียน"
    ]
  }
}

แม้แต่ความล้มเหลวก็ยังสามารถนำทางได้

วนลูปที่ปลอดภัยยิ่งขึ้นด้วย agentHints

มาติดตามเวิร์กโฟลว์ที่สมบูรณ์ด้วย agentHints กัน:

ขั้นตอนที่ 1: Agent สร้างกรณีทดสอบ
        ↓
ผลลัพธ์ CLI: success + agentHints
        ↓
agentHints.nextSteps[0]: "อ่านกรณีทดสอบที่สร้างขึ้นกลับ"
        ↓
ขั้นตอนที่ 2: Agent อ่านกลับ (พร้อมโครงสร้างจริง)
        ↓
ผลลัพธ์ CLI: โครงสร้างกรณีทดสอบ + agentHints
        ↓
agentHints.nextSteps[0]: "เพิ่ม assertions หากจำเป็น"
        ↓
ขั้นตอนที่ 3: Agent เพิ่ม assertions (อิงตามโครงสร้างจริง)
        ↓
ผลลัพธ์ CLI: success + agentHints
        ↓
agentHints.nextSteps[0]: "เรียกใช้การทดสอบ"
        ↓
ขั้นตอนที่ 4: Agent เรียกใช้การทดสอบ
        ↓
ผลลัพธ์ CLI: รายงานการทดสอบ

ทุกขั้นตอนถูกนำทาง ไม่มีการกระโดดแบบไม่รู้ทิศทาง ไม่มีการคาดเดา

เปรียบเทียบ: มีและไม่มี agentHints

อะไรจะเกิดขึ้นต่อไป

ตอนนี้ CLI สามารถนำทาง Agent ผ่านขั้นตอนต่อไปได้แล้ว คำถามที่เหลือคือ:

Agent รู้ได้อย่างไรว่าควรจะตามเวิร์กโฟลว์ใดตั้งแต่แรก?

ในตอนที่ 5, SKILL: การส่งมอบประสบการณ์การทำงานในรูปแบบ Code เราจะสำรวจว่า SKILL บรรจุความรู้เวิร์กโฟลว์อย่างไร – เมื่อใดควรใช้คำสั่งใด, ลำดับใดที่ควรปฏิบัติตาม, และฟิลด์ใดที่ไม่ควรคาดเดา

ประเด็นสำคัญ

• ผลลัพธ์ CLI แบบดั้งเดิมมุ่งเน้นมนุษย์; Agent ต้องการคำแนะนำที่มีโครงสร้าง
• agentHints ให้สรุป + ข้อเสนอแนะขั้นตอนต่อไปในรูปแบบ JSON
• ความเฉื่อยของการดำเนินการทำให้ Agent ข้ามการอ่านกลับ; agentHints ป้องกันปัญหานี้
• CLI เปลี่ยนบทบาทจากผู้ดำเนินการเป็นผู้นำทาง
• โครงสร้างเวิร์กโฟลว์ในตัวทำให้ทุกขั้นตอนสามารถนำทางได้
• แม้แต่ความล้มเหลวก็ยังสามารถดำเนินการได้ด้วย agentHints

ดาวน์โหลด Apidog เพื่อ ออกแบบ, จำลอง, ทดสอบ, และ จัดทำเอกสาร API ในพื้นที่ทำงานเดียว เรียนรู้เพิ่มเติมเกี่ยวกับ Apidog CLI สำหรับการทดสอบ API ด้วยบรรทัดคำสั่ง, การทำงานอัตโนมัติ CI, และเวิร์กโฟลว์ AI Agent