การกำหนดเวอร์ชัน API สำหรับ AI Agents: รับมือกับการเปลี่ยนแปลงที่ส่งผลกระทบ

ทีม API ได้เปลี่ยนชื่อฟิลด์จาก customer_name เป็น customer_full_name พวกเขาประกาศเรื่องนี้ อัปเดตเอกสารประกอบ และไคลเอนต์ที่ดูแลโดยมนุษย์ทุกรายได้รับคำขอพูล (pull request) แต่เอเจนต์ของคุณไม่ได้รับอะไรเลย เพราะไม่มีใครคิดว่ามันเป็นไคลเอนต์ มันยังคงส่งฟิลด์เก่า API ก็ยังคงรับคำขอและละเว้นคีย์ที่ไม่รู้จัก และเป็นเวลาสองสัปดาห์ที่ทุกบันทึกที่สร้างขึ้นมีชื่อว่างเปล่า

เอเจนต์คือผู้ใช้ API ที่มีความสามารถน้อยที่สุดในการสังเกตเห็นการเปลี่ยนแปลง และมีแนวโน้มที่จะมองข้ามไป ไคลเอนต์ที่เป็นมนุษย์จะแจ้งข้อผิดพลาด (exception) แต่เอเจนต์จะอ่านค่า 200 ตัดสินใจว่าการเรียกใช้งานสำเร็จ และดำเนินการต่อไป บางครั้งมันก็ปรับปรุงแก้ไขปัญหาเฉพาะหน้าในลักษณะที่ดูเหมือนจะสำเร็จ

คู่มือนี้ครอบคลุมเหตุผลที่เอเจนต์มีความเปราะบางเป็นพิเศษต่อการเปลี่ยนแปลง API การเปลี่ยนแปลงใดบ้างที่ทำให้เอเจนต์พังซึ่งจะไม่ทำให้ไคลเอนต์ทั่วไปพัง วิธีการกำหนดเวอร์ชันและตรวจจับเวอร์ชัน และวิธีตรวจจับการเปลี่ยนแปลงใน CI ก่อนที่จะมีการรัน โพสต์ของเราเกี่ยวกับ สาเหตุที่เอเจนต์ AI ล้มเหลวในการทำงานจริง ครอบคลุมถึงรูปแบบความล้มเหลว นี่คือสิ่งหนึ่งที่มาจากภายนอกโค้ดเบสของคุณ

Apidog มีความสำคัญที่นี่ เนื่องจากการตรวจจับเป็นปัญหาของสเปก หากคุณมี API definition เวอร์ชันก่อนหน้าและเวอร์ชันปัจจุบัน การเปรียบเทียบความแตกต่าง (diff) ก็เป็นเรื่องทางกลไก

ทำไมเอเจนต์ถึงสังเกตเห็นน้อยกว่าที่ไคลเอนต์ทำ

คุณสมบัติสี่ประการรวมกันแล้วเกิดปัญหา

การยอมรับแบบเงียบๆ API ส่วนใหญ่จะละเว้นฟิลด์ที่ไม่รู้จักในเนื้อหาคำขอ ฟิลด์ที่เปลี่ยนชื่อหมายความว่าฟิลด์ใหม่ไม่มีอยู่ และฟิลด์เก่าถูกละทิ้ง โดยมีรหัส 200 ส่งกลับไป ไม่มีสิ่งใดถูกยกขึ้น (raise error)

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

คำอธิบายในพรอมต์ คำอธิบายเครื่องมือของเอเจนต์จะเข้ารหัสข้อสมมติฐานเกี่ยวกับ API ในรูปแบบข้อความ เมื่อ API เปลี่ยนแปลง คำอธิบายเหล่านั้นก็จะผิดพลาดเล็กน้อย และคำอธิบายที่ผิดพลาดจะทำให้เกิดการเรียกใช้งานที่ผิดพลาดโดยไม่มีโค้ดเข้ามาเกี่ยวข้อง โพสต์ของเราเกี่ยวกับ การออกแบบ schema ของเครื่องมือ ครอบคลุมว่าพฤติกรรมส่วนใหญ่ขึ้นอยู่กับข้อความนั้นมากเพียงใด

ไม่มีคอมไพเลอร์ ไคลเอนต์ที่มีการกำหนดประเภท (typed client) จะเกิดข้อผิดพลาดในขณะคอมไพล์ (build time) เมื่อฟิลด์หายไป สัญญาของเอเจนต์อยู่ใน JSON schema และข้อความทั่วไป และไม่มีสิ่งใดตรวจสอบได้จนกว่าการเรียกใช้งานจะล้มเหลว หรือที่แย่กว่านั้นคือ จนกว่ามันจะไม่ล้มเหลวอย่างเงียบๆ

สรุปคือ: การเปลี่ยนแปลงที่ปลอดภัยสำหรับไคลเอนต์ทั่วไปมักจะไม่ปลอดภัยสำหรับเอเจนต์ และคุณควรจัดหมวดหมู่แยกกัน

การเปลี่ยนแปลงใดบ้างที่ทำให้เอเจนต์พังจริงๆ

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

เป็นการเปลี่ยนแปลงที่ทำลายอย่างแท้จริงสำหรับทุกคน การลบ endpoint, การลบฟิลด์, การเปลี่ยนชื่อฟิลด์, การเปลี่ยนประเภท, การทำให้พารามิเตอร์เสริมเป็นพารามิเตอร์ที่จำเป็น, การเปลี่ยน URL เอเจนต์จะพังที่นี่ด้วย เพียงแต่จะเงียบกว่า

ปลอดภัยสำหรับไคลเอนต์ที่มีการกำหนดประเภท แต่เสี่ยงสำหรับเอเจนต์:

• ฟิลด์ใหม่ที่จำเป็น ผู้เรียกใช้งานที่มีอยู่ทุกรายจะพัง แต่เอเจนต์จะพังด้วยข้อผิดพลาดในการตรวจสอบความถูกต้อง ซึ่งมันอาจพยายามแก้ไขโดยการสร้างค่าขึ้นมาเอง นั่นแย่กว่าความล้มเหลวอย่างรุนแรง
• ค่า enum ใหม่ ไคลเอนต์ทั่วไปจะละเว้นสิ่งที่พวกเขาไม่สามารถจัดการได้ เอเจนต์อาจให้เหตุผลเกี่ยวกับค่าที่ไม่คุ้นเคยและสรุปผลที่ผลิตภัณฑ์ของคุณไม่เคยตั้งใจให้เป็น
• กฎการตรวจสอบที่เข้มงวดขึ้น ฟิลด์ที่เคยรับสตริงใดๆ ได้ ตอนนี้ต้องใช้รูปแบบ (pattern) เอเจนต์ไม่มีทางเรียนรู้รูปแบบได้เลยยกเว้นจะล้มเหลว ซึ่งเป็นเหตุผลว่าทำไมกฎนี้จึงควรอยู่ในข้อความแสดงข้อผิดพลาด ดังที่ครอบคลุมในโพสต์ของเราเกี่ยวกับ การออกแบบข้อความแสดงข้อผิดพลาดของ API สำหรับเอเจนต์ AI
• ค่าเริ่มต้นที่เปลี่ยนแปลงไป ค่าเริ่มต้นของการแบ่งหน้าลดลงจาก 100 เป็น 20 และเอเจนต์ซึ่งไม่เคยส่งค่า limit ตอนนี้เห็นข้อมูลเพียงหนึ่งในห้าและรายงานราวกับว่าสมบูรณ์
• เอกสารที่เขียนใหม่ ไม่มีการเปลี่ยนแปลงพฤติกรรมใดๆ เลย แต่ถ้าเครื่องมือของคุณถูกสร้างขึ้นจากสเปก เช่นเดียวกับในคู่มือของเราเกี่ยวกับการ เปลี่ยน OpenAPI spec ให้เป็นเครื่องมือของเอเจนต์ ข้อความอธิบายจะเปลี่ยนไป และการเลือกเครื่องมือก็สามารถเปลี่ยนแปลงตามไปด้วยได้

ปลอดภัยสำหรับเอเจนต์ด้วย การเพิ่มฟิลด์ที่ไม่บังคับ, การเพิ่ม endpoint, การเพิ่มพารามิเตอร์ที่ไม่บังคับพร้อมค่าเริ่มต้นที่คงไว้, การคลายกฎการตรวจสอบ

รายการตรงกลางนั้นคือสิ่งที่ต้องจับตาดู เพราะไม่มีสิ่งใดในการตรวจสอบการเปลี่ยนแปลงมาตรฐานที่จะแจ้งเตือนได้

กำหนดเวอร์ชันไว้เสมอ

การป้องกันแรกคือการปฏิเสธที่จะเปลี่ยนแปลงโดยปริยาย

ส่งเวอร์ชันที่ชัดเจนในทุกคำขอ ไม่ว่าจะด้วยกลไกใดๆ ที่ API เสนอ: ส่วนของพาธ, ส่วนหัว (header), หรือการกำหนดเวอร์ชันระดับบัญชี เอกสาร การกำหนดเวอร์ชัน API ของ GitHub ใช้ส่วนหัวที่เป็นวันที่ และ Stripe กำหนดเวอร์ชันต่อบัญชีด้วยขั้นตอนการอัปเกรดที่ชัดเจน ทั้งสองวิธีให้คุณสมบัติเดียวกัน: ไม่มีสิ่งใดเปลี่ยนแปลงโดยที่คุณไม่ตัดสินใจ

DEFAULT_HEADERS = {
    "X-API-Version": "2026-06-01",
    "User-Agent": "billing-agent/1.4 (+https://example.com/agents)",
}

User-Agent มีคุณค่าพอๆ กับการกำหนดเวอร์ชัน เมื่อผู้ให้บริการ API ต้องการเตือนผู้เรียกใช้งานเกี่ยวกับการเลิกใช้งาน พวกเขาจะดูที่การรับส่งข้อมูล เอเจนต์ที่ระบุตัวตนจะได้รับอีเมล; ส่วนเอเจนต์ที่ส่งสตริงไลบรารีเริ่มต้นจะไม่ได้รับ

หากคุณเป็นเจ้าของ API ให้เผยแพร่เวอร์ชันและคงไว้ คู่มือของเราเกี่ยวกับ กลยุทธ์การกำหนดเวอร์ชัน API ที่ดีที่สุด ครอบคลุมถึงตัวเลือกต่างๆ และ การจัดการการกำหนดเวอร์ชัน API ใน Apidog ครอบคลุมถึงการเก็บหลายเวอร์ชันให้ใช้งานพร้อมกัน

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

ตรวจจับการเปลี่ยนแปลงก่อนที่จะมีการรัน

การกำหนดเวอร์ชันช่วยยืดเวลาได้ มันไม่ได้หยุดการอัปเกรดในที่สุด และไม่ได้ช่วยอะไรเลยสำหรับ API ที่เปลี่ยนแปลงโดยไม่มีการกำหนดเวอร์ชัน ดังนั้น จงตรวจจับ

เปรียบเทียบความแตกต่างของสเปกตามกำหนดเวลา หากผู้ให้บริการเผยแพร่เอกสาร OpenAPI ให้ดึงข้อมูลมาทุกวันและเปรียบเทียบกับสำเนาที่คุณใช้สร้างเครื่องมือ ฟิลด์ที่ถูกลบ, ประเภทที่เปลี่ยนแปลง, ข้อกำหนดที่เพิ่มเข้ามา, enum ที่ขยาย, คำอธิบายที่แก้ไข ใน Apidog คุณสามารถเก็บ definition ที่นำเข้าไว้ในโปรเจกต์และดูว่าอะไรเปลี่ยนแปลงไประหว่างเวอร์ชัน ซึ่งจะเปลี่ยนคำถาม “มีอะไรเปลี่ยนแปลงหรือไม่” ให้กลายเป็นรายงานแทนที่จะเป็นการสืบสวน

ทดสอบสัญญาของ endpoint ที่คุณเรียกใช้ สำหรับเครื่องมือแต่ละชิ้นที่เอเจนต์มี ให้ส่งคำขอที่ทราบว่าถูกต้องและยืนยันรูปแบบการตอบกลับ: ฟิลด์ที่จำเป็นมีอยู่, ประเภทถูกต้อง, ค่า enum อยู่ในชุดที่คุณคาดหวัง สิ่งนี้จะตรวจจับการเปลี่ยนแปลงใน API ที่ไม่ได้เผยแพร่สเปกเลย ซึ่งส่วนใหญ่เป็นเช่นนั้น คู่มือ การทดสอบสัญญา API ของเราครอบคลุมถึงรูปแบบนี้ และ การทดสอบสัญญาแบบสองทิศทาง ครอบคลุมถึงการรันจากทั้งสองฝั่ง

ยืนยันรูปแบบในขณะรันไทม์ ตรวจสอบการตอบกลับใน tool wrapper กับ schema ที่คุณคาดหวัง และบันทึกคำเตือนเมื่อมีสิ่งที่ไม่คาดคิดปรากฏขึ้น นี่คือแนวป้องกันสุดท้าย และเป็นสิ่งที่ตรวจจับการเปลี่ยนแปลงที่ไม่มีใครประกาศ

def check_shape(tool_name, payload, expected):
    missing = [f for f in expected["required"] if f not in payload]
    extra = [f for f in payload if f not in expected["properties"]]
    if missing:
        log.error("api_drift", tool=tool_name, missing=missing)
        raise ApiDriftError(f"{tool_name}: missing fields {missing}")
    if extra:
        log.warning("api_new_fields", tool=tool_name, fields=extra)
    return payload

ล้มเหลวเมื่อขาดหาย, เตือนเมื่อเกิน ฟิลด์ที่จำเป็นขาดหายไปหมายความว่าเอเจนต์กำลังจะทำงานกับข้อมูลที่ไม่สมบูรณ์ ซึ่งเป็นความล้มเหลวที่ควรหยุดเพื่อแก้ไข ฟิลด์ใหม่มักจะเป็นส่วนเพิ่มเติมและควรรับทราบโดยไม่ขัดจังหวะการทำงาน ส่งทั้งสองอย่างไปยังบันทึกการติดตามที่อธิบายไว้ในโพสต์ของเราเกี่ยวกับการ ติดตามการเรียกใช้เครื่องมือของเอเจนต์ AI

เฝ้าดูพฤติกรรม ไม่ใช่แค่ schema การเปลี่ยนแปลงบางอย่างนั้นมองไม่เห็นในการตรวจสอบรูปแบบ: ค่าเริ่มต้นที่เปลี่ยนไป, อัตราการจำกัดที่เข้มงวดขึ้น, การตอบสนองที่ช้าลง ติดตามจำนวนการเรียกใช้งานต่อภารกิจที่เสร็จสมบูรณ์, อัตราการลองใหม่ต่อ endpoint และขนาดการตอบสนองเฉลี่ยต่อเครื่องมือ การเปลี่ยนแปลงอย่างกะทันหันในสิ่งใดสิ่งหนึ่งมักจะหมายความว่ามีบางอย่างเปลี่ยนแปลงจากต้นทาง

การอัปเกรดโดยไม่ทำให้เอเจนต์พัง

เมื่อคุณย้ายไปเวอร์ชันใหม่ ให้ถือว่าเป็นการเปลี่ยนแปลงเอเจนต์ เพราะมันเป็นเช่นนั้น

สร้างเครื่องมือใหม่แทนที่จะแก้ไขด้วยมือ เพื่อให้คำอธิบายและ schema ไปด้วยกัน จากนั้นอ่านความแตกต่างของคำจำกัดความเครื่องมือที่สร้างขึ้น ความแตกต่างนั้นคือรัศมีการระเบิดที่แท้จริง และมักจะเล็กหรือใหญ่กว่าที่ changelog ของ API บ่งบอก

รันเอเจนต์กับ mock ของเวอร์ชันใหม่ก่อนที่จะชี้ไปยังสิ่งใดๆ ที่ใช้งานจริง นี่คือขั้นตอนที่มีมูลค่าสูงสุดและมักถูกข้ามไปมากที่สุด: mock ที่สร้างขึ้นจากสเปกใหม่ช่วยให้คุณสามารถรันชุดงานทั้งหมดของคุณกับรูปแบบใหม่โดยไม่มีความเสี่ยง ตามโพสต์ของเราเกี่ยวกับการ รันเอเจนต์กับ mock แทนที่จะเป็น production

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

เปิดใช้งานเบื้องหลัง feature flag, ในส่วนหนึ่งของการรับส่งข้อมูล, โดยที่เวอร์ชันเก่ายังคงถูกกำหนดไว้และพร้อมใช้งาน เฝ้าดูตัวเลขสี่ตัวเดียวกันเป็นเวลาหนึ่งวัน การถดถอยของเอเจนต์จะปรากฏให้เห็นจากการเรียกใช้งานที่มากขึ้นต่อภารกิจ และการลองใหม่ที่มากขึ้น นานก่อนที่ใครจะยื่นเรื่องร้องเรียน

การเปลี่ยนแปลงสามอย่างที่เกิดขึ้นในการทำงานจริง

ฟิลด์ที่ถูกเปลี่ยนชื่อ เรื่องราวตอนต้น การตอบกลับ 200 ในทุกการเรียกใช้งาน, ชื่อว่างเปล่าในทุกบันทึก, ถูกค้นพบสองสัปดาห์ต่อมาโดยมนุษย์ที่อ่านรายงาน การตรวจสอบรูปแบบในขณะรันไทม์บนการตอบกลับจะตรวจจับได้ตั้งแต่การเรียกใช้งานครั้งแรก เพราะฟิลด์ที่เอเจนต์คาดว่าจะอ่านกลับหายไป

ค่าเริ่มต้นการแบ่งหน้าที่เข้มงวดขึ้น ผู้ให้บริการลดขนาดหน้าเริ่มต้นจาก 100 เหลือ 20 เอเจนต์ไม่เคยส่งค่า limit ดังนั้นจึงเริ่มเห็นบันทึก 20 รายการและสรุปว่าเป็นชุดข้อมูลที่สมบูรณ์ ไม่มีข้อผิดพลาดใดๆ เกิดขึ้น สรุปนั้นผิดพลาดง่ายๆ ในลักษณะที่ดูเหมือนมั่นใจ การแก้ไขคือโค้ดบรรทัดเดียว คือการส่ง limit ที่ชัดเจน และบทเรียนที่กว้างขึ้นคือ: พึ่งพาค่าเริ่มต้น และคุณจะมี dependency ที่ไม่ประกาศไว้กับการตัดสินใจของคนอื่น

ค่า enum ใหม่ API การชำระเงินเพิ่ม status: "disputed" ไคลเอนต์ที่มีการกำหนดประเภทละเว้นมัน เอเจนต์ให้เหตุผลเกี่ยวกับเรื่องนี้ ตัดสินใจว่าการเรียกเก็บเงินที่มีข้อโต้แย้งถือเป็นการคืนเงิน และรายงานบัญชีที่กระทบยอดแล้วซึ่งไม่เป็นความจริง การตรวจสอบความถูกต้องของ enum อย่างชัดเจนจะแจ้งข้อผิดพลาดเมื่อพบค่าที่ไม่คุ้นเคยแทนที่จะปล่อยให้โมเดลตีความมัน

รูปแบบคือ: การเปลี่ยนแปลงแต่ละอย่างได้รับการประกาศ, แต่ละอย่างเป็นการเพิ่มหรือเปลี่ยนแปลงเล็กน้อยตามการจัดประเภทของผู้ให้บริการเอง, และแต่ละอย่างทำให้เอเจนต์พัง ช่องว่างนั้นคือสิ่งที่เราต้องออกแบบเพื่อรับมือ

พิจารณาการเลิกใช้งานเป็นรายการงาน

ผู้ให้บริการมักจะเตือนคุณ คำเตือนจะมาใน changelog, อีเมล, หรือ Deprecation header บนการตอบกลับ และเป็นเรื่องง่ายที่สิ่งเหล่านี้จะไปไม่ถึงผู้ดูแลเอเจนต์

เชื่อมโยงสิ่งเหล่านี้เข้ากับคิวงานปกติของคุณ ทั้ง Deprecation header และ Sunset header ล้วนเป็นมาตรฐาน ดังนั้นการตรวจสอบทั่วไปจึงใช้ได้กับผู้ให้บริการทุกราย บันทึกเมื่อปรากฏ และแจ้งเตือนตั้งแต่การพบเห็นครั้งแรก แทนที่จะรอจนถึงครั้งที่หนึ่งพัน ส่วนหัวที่ปรากฏในการเรียกใช้งาน 3 เปอร์เซ็นต์ในวันนี้ จะกลายเป็นการหยุดทำงานทั้งหมดในวันสิ้นสุดการรองรับ

เก็บรายการสินค้าคงคลังด้วย: เอเจนต์ไหน, ผู้ให้บริการไหน, เวอร์ชันไหน, endpoint ไหน และใครเป็นเจ้าของ ไฟล์สิบบรรทัดก็เพียงพอแล้ว เมื่อมีการแจ้งเตือนการเลิกใช้งาน คำถามที่ว่า “สิ่งนี้ส่งผลกระทบต่อเราหรือไม่” ควรใช้เวลาเพียงนาทีเดียว ไม่ใช่นั่งค้นหา (grepping) ตลอดบ่าย

การเปลี่ยนแปลงคือภาระงาน ดังนั้นควรมอบหมายเจ้าของ

การตรวจจับจะสร้างคิวงาน: การเปรียบเทียบสเปก, การทดสอบสัญญาที่ล้มเหลว, Deprecation header ที่เพิ่งพบเห็นเป็นครั้งแรก แต่ละรายการเป็นงานเล็กๆ น้อยๆ ที่มีกำหนดเวลา และรูปแบบความล้มเหลวคือมันจะอยู่ในช่องทางที่ไม่มีใครเป็นเจ้าของจนกว่าจะถึงวันสิ้นสุดการรองรับ

นำสิ่งเหล่านี้ไปไว้ในที่ที่ทีมของคุณติดตามงานอยู่แล้ว หากเอเจนต์ของคุณทำงานในฐานะ coding runtimes แทนที่จะเป็นบริการที่คุณ deploy แพลตฟอร์มที่จัดการพวกมันสามารถปิดลูปได้: Sharkly จะมอบหมายงานให้กับเอเจนต์หรือ Crew และเก็บเป้าหมาย, execution trace, และการตรวจสอบไว้ในที่เดียว ดังนั้น “payments API เลิกใช้งาน endpoint นี้” จะกลายเป็นงานที่ได้รับมอบหมายพร้อมผลลัพธ์ แทนที่จะเป็นข้อความในเธรด ไม่ว่าคุณจะใช้อะไรก็ตาม กฎก็ยังคงเดิม การแจ้งเตือนการเปลี่ยนแปลงที่ไม่มีเจ้าของคือการเลิกใช้งานที่คุณจะต้องพบเจออีกครั้งในวันที่มันพัง

รายการตรวจสอบ

• ทุกคำขอส่ง API version ที่ชัดเจนและ User-Agent ที่ระบุตัวตน
• เอกสารสเปกของบุคคลที่สามจะถูกดึงและเปรียบเทียบความแตกต่างตามกำหนดเวลา
• ทุกเครื่องมือที่เอเจนต์สามารถเรียกใช้ได้มีการทดสอบสัญญาที่ยืนยันรูปแบบการตอบกลับ
• Tool wrapper ตรวจสอบการตอบกลับในขณะรันไทม์: ล้มเหลวเมื่อขาดหาย, เตือนเมื่อมีของใหม่
• เมตริกพฤติกรรมถูกติดตามต่อ endpoint เพื่อให้การเปลี่ยนแปลงแบบเงียบๆ ปรากฏขึ้น
• การอัปเกรดเวอร์ชันจะสร้างเครื่องมือใหม่แทนที่จะแก้ไขด้วยมือ
• ชุดงานและชุดการเลือกทั้งคู่จะรันกับ mock ของเวอร์ชันใหม่ก่อน
• การเปิดใช้งานถูกทำเครื่องหมาย (flagged) และสามารถย้อนกลับได้ โดยที่เวอร์ชันก่อนหน้ายังคงถูกกำหนดไว้

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

คำถามที่พบบ่อย

ฉันควรตรวจสอบสเปกของบุคคลที่สามสำหรับการเปลี่ยนแปลงบ่อยแค่ไหน? รายวันก็เพียงพอสำหรับส่วนใหญ่ และราคาถูกที่จะทำให้เป็นอัตโนมัติ สำหรับ API ที่ไม่มีสเปกที่เผยแพร่ ให้พึ่งพาการทดสอบสัญญาที่รันใน CI แทน เนื่องจากพวกมันตรวจจับการเปลี่ยนแปลงแบบเดียวกันจากภายนอก

ฉันควรกำหนดเวอร์ชันกับเวอร์ชันที่เก่าที่สุดที่ยังทำงานอยู่เสมอหรือไม่? ไม่ ควรกำหนดเวอร์ชันเพื่อให้การอัปเกรดเป็นไปอย่างตั้งใจ จากนั้นอัปเกรดตามกำหนดเวลา การยึดติดกับเวอร์ชันเก่าจนกว่าจะถูกลบออกจะเปลี่ยนการเปลี่ยนแปลงที่วางแผนไว้ให้กลายเป็นสถานการณ์ฉุกเฉิน

จะเกิดอะไรขึ้นหากเอเจนต์ยังทำงานได้ดีหลังจากการเปลี่ยนแปลง? ตรวจสอบยืนยันแทนที่จะคาดเดา ผลลัพธ์ที่เป็นอันตรายคือผลลัพธ์ที่ยังคงส่งคืน 200 เช่น ฟิลด์ที่เปลี่ยนชื่อแล้วถูกละทิ้งไปอย่างเงียบๆ การยืนยันรูปแบบจะบอกคุณในสิ่งที่การรันที่สำเร็จ (green run) ไม่สามารถบอกได้

ฉันจำเป็นต้องกำหนดเวอร์ชัน API ของตัวเองแตกต่างกันสำหรับเอเจนต์หรือไม่? ไม่ได้แตกต่างกัน แต่เข้มงวดขึ้น ปฏิบัติต่อฟิลด์ใหม่ที่จำเป็น, ค่า enum ใหม่, และค่าเริ่มต้นที่เปลี่ยนแปลงไปว่าเป็นการเปลี่ยนแปลงที่ทำลายสำหรับผู้ใช้เอเจนต์ แม้ว่าจะเป็นการเพิ่มเติมสำหรับไคลเอนต์ที่มีการกำหนดประเภท และประกาศในลักษณะเดียวกัน

ฉันจะทราบได้อย่างไรว่าเอเจนต์ใดเรียกใช้ endpoint ใดบ้าง? จากการติดตาม (traces) ของคุณ ชื่อเครื่องมือบวกกับ endpoint ต่อการรันจะให้แผนผัง dependency แก่คุณ และมันจะบอกคุณว่าใครได้รับผลกระทบจากการเลิกใช้งาน โพสต์ของเราเกี่ยวกับการ ติดตามการเรียกใช้เครื่องมือของเอเจนต์ AI ครอบคลุมถึงรูปแบบบันทึก

เอเจนต์สามารถปรับตัวเข้ากับ API ที่เปลี่ยนแปลงได้ด้วยตัวเองหรือไม่? บางครั้ง แต่คุณไม่ควรพึ่งพามัน โมเดลที่ปรับปรุงแก้ไขเฉพาะหน้าเมื่อฟิลด์หายไปจะสร้างผลลัพธ์ที่ดูสมเหตุสมผลโดยไม่มีสัญญาณว่ามีอะไรผิดพลาด ให้ล้มเหลวอย่างชัดเจนแล้วแก้ไขเครื่องมือแทน