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

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

ลองใช้ Apidog วันนี้

	หัวข้อ	จุดเน้น
1	เราสร้างเครื่องมือ MCP 126 ชิ้น แต่มันไม่ใช่ทางออกที่ดีที่สุดสำหรับ Agent	การค้นพบปัญหา
2	ทำไมเราถึงพัฒนา Apidog CLI ใหม่ทั้งหมด	การพัฒนาสถาปัตยกรรม
3	กฎทอง: CLI สร้างข้อเท็จจริง, Model ทำงานตามข้อเท็จจริง	ปรัชญาหลัก
4	agentHints: การสอน CLI ให้สื่อสารกับ Agent	ผลลัพธ์ที่มีโครงสร้าง
5	SKILL: การส่งมอบประสบการณ์การทำงานในรูปแบบ Code	ประสบการณ์การทำงาน
6	ตัวเลขไม่โกหก: เรียกใช้เครื่องมือน้อยลง 30%, ใช้โทเค็นน้อยลง 25%	ผลลัพธ์เชิงปริมาณ
7	จาก PRD สู่ Testing Loop: เวิร์กโฟลว์ Agent ที่สมบูรณ์แบบด้วย Apidog CLI	บทแนะนำเชิงปฏิบัติ
8	ทำไมความเข้ากันได้กับ CI/CD จึงเป็นสิ่งที่ไม่สามารถต่อรองได้สำหรับเครื่องมือ Agent	มุมมอง DevOps
9	AI Branch: การเปลี่ยนแปลงโปรเจกต์ที่ปลอดภัยยิ่งขึ้นด้วย AI Agents	ชั้นความปลอดภัย
10	Spec-First เป็นเรื่องเมื่อวานนี้ ยินดีต้อนรับสู่ Skill-First.	วิสัยทัศน์และอนาคต

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

---

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

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

ความสำเร็จ	ความล้มเหลว
พิมพ์ “สำเร็จ” หรือ “เสร็จสิ้น”	พิมพ์ข้อความข้อผิดพลาด
อาจแสดงทรัพยากรที่สร้างขึ้น	อาจแสดง Stack Trace
มนุษย์อ่านและตัดสินใจขั้นตอนต่อไป	มนุษย์อ่านและแก้ไขข้อผิดพลาด

รูปแบบนี้ใช้ได้กับคน เพราะมนุษย์สามารถ:

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

แต่ Agent ไม่ควรต้อง “เดา” จากข้อความลักษณะนี้

---

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

Agent ไม่ได้แค่อ่านผลลัพธ์ แต่ต้องนำผลลัพธ์ไปต่อกับงานถัดไปใน workflow ได้ทันที

สิ่งที่ Agent ต้องการ	เหตุผล
ผลลัพธ์ที่มีโครงสร้าง	ต้อง parse ด้วยโปรแกรมได้
เหตุผลของความล้มเหลว	ต้องรู้สาเหตุที่เฉพาะเจาะจง ไม่ใช่ข้อความทั่วไป
ข้อเสนอแนะสำหรับขั้นตอนต่อไป	ต้องรู้ว่าควรทำอะไรต่อ

ตัวอย่างเช่น มนุษย์เห็นข้อความ:

Resource created successfully

แล้วเข้าใจได้เองว่า:

ควรอ่าน resource ที่สร้างขึ้นกลับมาตรวจสอบ แล้วค่อยเพิ่ม test หรือ run test ต่อ

แต่ Agent เห็นข้อความเดียวกันแล้วอาจไม่รู้ว่าต้องอ่านกลับก่อน หรือควรสร้างงานถัดไปทันที

---

agentHints: ทางออก

Apidog CLI เพิ่ม agentHints ลงในผลลัพธ์ เพื่อให้ Agent เข้าใจทั้งผลลัพธ์และทิศทางถัดไป

ตัวอย่าง response หลังสร้าง test case:

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

โครงสร้างหลักมี 3 ส่วน:

องค์ประกอบ	วัตถุประสงค์
success + data	ผลลัพธ์จริงของคำสั่ง
summary	สรุปที่มนุษย์อ่านได้
nextSteps	คำแนะนำขั้นตอนต่อไปที่ Agent parse ได้

สำหรับการนำไปใช้ใน Agent workflow ให้มอง agentHints.nextSteps เป็น “queue ของการกระทำถัดไป” ไม่ใช่แค่ข้อความประกอบ

---

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

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

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

ตัวอย่าง workflow ที่มีความเสี่ยง:

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

ใน workflow จริงที่ซับซ้อน การทำต่อแบบเชิงกลมักไม่ปลอดภัย แนวทางที่ควรทำคือ:

1. สร้าง resource
2. อ่าน resource กลับ
3. ยืนยันโครงสร้างจริง
4. ดำเนินการขั้นถัดไปจากข้อมูลจริง

---

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

การข้ามขั้นตอน read-back ทำให้ Agent ทำงานต่อจาก assumption แทนที่จะทำงานจาก state จริงของระบบ

ปัญหา	สาเหตุ
ค่าเริ่มต้นผิดพลาด	เซิร์ฟเวอร์เติมค่า default ที่ Agent ไม่ได้ระบุ
รหัสที่เกี่ยวข้องขาดหายไป	การนำเข้าอาจสร้าง internal ID ใหม่
รูปแบบโครงสร้างต่างจากที่คาด	frontend หรือ API อาจ serialize ข้อมูลด้วยรูปแบบเฉพาะ
การคาดเดาที่ไม่ถูกต้อง	Agent ทำงานต่อจาก “จินตนาการ” ของตัวเอง

หลักปฏิบัติที่ปลอดภัยคือ:

write → read → verify → continue

ถ้า Agent ไม่อ่านโครงสร้างจริงกลับมา มันอาจเขียนข้อมูลถัดไปโดยอิงจาก schema ที่คิดว่าใช่ แต่ไม่ใช่ state จริง

---

ใช้ agentHints เป็นตัวนำทาง workflow

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

ตัวอย่างหลังจากสร้าง test case:

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

Agent ควรประมวลผลแบบนี้:

1. อ่านผลลัพธ์ CLI
2. parse agentHints
3. เลือก nextSteps[0]
4. อ่าน test case กลับด้วย option ที่แนะนำ
5. ตรวจสอบโครงสร้างจริง
6. ดำเนินงานถัดไปจากข้อมูลที่ verify แล้ว

Pseudo-code:

const result = await runCliCommand(command);

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

  // ส่ง nextAction เข้า planner ของ Agent
  await agent.plan(nextAction, {
    previousResult: result.data,
    success: result.success
  });
}

จุดสำคัญคือ Agent ไม่ควรใช้แค่ success: true เป็นสัญญาณให้เขียนต่อทันที แต่ควรอ่าน agentHints ก่อนเสมอ

---

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

เมื่อ CLI ส่ง agentHints กลับมา บทบาทของ CLI ใน Agent workflow จะเปลี่ยนจากตัวรันคำสั่งเป็นตัวนำทาง state

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

กล่าวอีกแบบคือ CLI กลายเป็น ตัวนำทางสถานะน้ำหนักเบา ที่ช่วยลดการเดาของ Agent

---

โครงสร้าง workflow ในตัว

Apidog CLI มี workflow แบบต้นไม้หลายพันรายการ ที่สร้างไว้ในตัว เพื่อให้คำแนะนำสอดคล้องกับบริบทของคำสั่ง

คำแนะนำเหล่านี้ไม่ได้เป็นแค่ข้อความ hard-code แบบทั่วไป แต่มีลักษณะดังนี้:

คุณสมบัติ	คำอธิบาย
รับรู้บริบท	คำแนะนำตรงกับ operation ที่เพิ่งทำ
เฉพาะ resource	endpoint, test case และ scenario ได้คำแนะนำต่างกัน
รับรู้ workflow	คำแนะนำสะท้อนลำดับงานที่ควรทำ
แจ้งตามผลลัพธ์	success และ failure ให้คำแนะนำต่างกัน

ตัวอย่างหลัง update test scenario สำเร็จ:

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

ตัวอย่างหลัง validation ล้มเหลว:

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

สิ่งนี้ทำให้แม้แต่ failure ก็ยัง actionable ได้ เพราะ Agent รู้ว่าควร inspect, fix และ validate ซ้ำอย่างไร

---

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

workflow ที่ปลอดภัยกว่าควรมี read-back และ validation อยู่ใน loop เสมอ:

ขั้นตอนที่ 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: รายงานการทดสอบ

ผลลัพธ์คือทุกขั้นตอนมีทิศทาง:

• ไม่มีการกระโดดข้าม read-back
• ไม่มีการเขียนต่อจาก assumption
• failure มีคำแนะนำในการแก้ไข
• Agent ทำงานกับ state จริงของระบบมากขึ้น

---

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

สถานการณ์	ไม่มี agentHints	มี agentHints
หลังจากสร้าง resource	Agent เขียนงานถัดไปทันที	Agent อ่านกลับก่อน
หลังจาก update	Agent สันนิษฐานว่าสำเร็จ	Agent ตรวจสอบโครงสร้าง
หลัง validation ผ่าน	Agent เขียนทันที	Agent เขียน แล้วอ่านกลับ
หลัง validation ล้มเหลว	Agent สับสนกับข้อผิดพลาด	Agent ได้คำแนะนำในการแก้ไข
หลัง run test	Agent เห็นแค่ผ่าน/ไม่ผ่าน	Agent ได้คำแนะนำในการ debug

---

แนวทางนำไปใช้กับ Agent ของคุณ

ถ้าคุณกำลังออกแบบ CLI หรือ tool สำหรับ Agent ให้เริ่มจาก pattern นี้:

{
  "success": true,
  "data": {},
  "agentHints": {
    "summary": "อธิบายผลลัพธ์แบบสั้น",
    "nextSteps": [
      "ขั้นตอนถัดไปที่ควรทำเป็นอันดับแรก",
      "ขั้นตอนตรวจสอบหรือ validation",
      "ขั้นตอน follow-up หลังจากยืนยันผลแล้ว"
    ]
  }
}

ข้อแนะนำเชิงปฏิบัติ:

1. อย่าส่งแค่ข้อความสำเร็จ

   • ส่ง success, data, และ agentHints เสมอ

2. ทำให้ failure actionable

   • error ควรมี code, message, details
   • agentHints.nextSteps ควรบอกวิธีแก้หรือวิธีตรวจซ้ำ

3. บังคับ read-back ในจุดที่ state อาจเปลี่ยน

   • หลัง create
   • หลัง update
   • หลัง import
   • หลัง operation ที่ server อาจเติม default หรือสร้าง ID

4. ให้คำแนะนำตาม resource

   • test case, endpoint, scenario ไม่ควรใช้ next steps ชุดเดียวกันทั้งหมด

5. ให้ Agent parse ได้ง่าย

   • ใช้ JSON ที่ predictable
   • หลีกเลี่ยงข้อความยาวที่ต้องตีความเอง

---

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

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

Agent รู้ได้อย่างไรว่าควรเริ่มจาก workflow ใดตั้งแต่แรก?

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

---

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

• CLI แบบดั้งเดิมเน้นมนุษย์ แต่ Agent ต้องการผลลัพธ์ที่มีโครงสร้าง
• agentHints ให้ทั้ง summary และ nextSteps ในรูปแบบ JSON
• ปัญหาใหญ่คือ Agent มักข้าม read-back แล้วเขียนต่อจาก assumption
• agentHints ช่วยบังคับ workflow แบบ write → read → verify → continue
• CLI เปลี่ยนบทบาทจากตัวรันคำสั่งเป็นผู้นำทาง workflow
• failure ก็ actionable ได้ ถ้ามี error details และ next steps ที่ชัดเจน

---

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