วิธีทดสอบ Tool Calls ของ AI Agent ด้วย Apidog ก่อนเกิดปัญหาใน Production

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

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

เอเจนต์ทำอะไรที่เลเยอร์ API จริงๆ

เมื่อตัดส่วนขอบออกไป ลูปของเอเจนต์ก็ง่ายๆ:

1. โมเดลได้รับเป้าหมายของผู้ใช้และรายการเครื่องมือ
2. มันจะคืนค่าการเรียกใช้เครื่องมือ: ชื่อเครื่องมือพร้อมกับอาร์กิวเมนต์ JSON
3. โค้ดของคุณจะดำเนินการเรียกใช้นั้น; โดยปกติจะเป็นคำขอ HTTP ไปยัง API บางอย่าง
4. ผลลัพธ์จะถูกส่งกลับไปยังโมเดล
5. โมเดลจะเรียกใช้เครื่องมืออื่นหรือตอบกลับ

ความล้มเหลวที่น่าสนใจทุกอย่างเกิดขึ้นที่ขั้นตอนที่ 3 และขั้นตอนที่ 4 โมเดลสร้างอาร์กิวเมนต์หลอน, API คืนค่า 422, โครงสร้างการตอบสนองเปลี่ยนไป, การเรียกใช้หมดเวลา, หรือการจำกัดอัตราการเรียกใช้เกิดขึ้นกลางลูป หากคุณเคยอ่านเกี่ยวกับ เอเจนต์ AI ในฐานะผู้บริโภค API รายใหม่ นี่คือเวอร์ชันที่เป็นรูปธรรมของแนวคิดนั้น: เอเจนต์ของคุณคือไคลเอ็นต์ที่เรียกใช้ API ของคุณ และสมควรได้รับการทดสอบที่เข้มงวดเช่นเดียวกับไคลเอ็นต์อื่นๆ

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

ขั้นตอนที่ 1: ออกแบบเครื่องมือเป็น API operations ที่แท้จริง

ก่อนที่คุณจะเขียนโค้ดเอเจนต์แม้แต่บรรทัดเดียว ให้กำหนดเครื่องมือแต่ละอย่างเป็นปลายทาง API ใน Apidog ปฏิบัติต่อโครงสร้างเครื่องมือและโครงสร้าง API เป็นสิ่งเดียวกัน เพราะมันคือสิ่งเดียวกัน เครื่องมือ get_weather และปลายทาง GET /weather มีข้อตกลงร่วมกัน: พารามิเตอร์เดียวกัน, รูปแบบการตอบสนองเดียวกัน

ใน Apidog สร้างปลายทางสำหรับเครื่องมือแต่ละอย่างด้วยโครงสร้าง OpenAPI ของมัน; พาธ, พารามิเตอร์คิวรีและบอดี้, และการตอบสนองที่มีประเภท สิ่งนี้จะให้สามสิ่งฟรีๆ:

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

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

ขั้นตอนที่ 2: จำลองเครื่องมือเพื่อให้คุณสามารถสร้างแบบออฟไลน์ได้

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

สิ่งนี้จะเปลี่ยนวิธีการสร้างเอเจนต์ของคุณ คุณสามารถ:

• พัฒนาลูปเอเจนต์ทั้งหมดก่อนที่ API จริงจะพร้อมใช้งาน โดยใช้ข้อมูลจำลองที่ตรงกับข้อตกลงที่ตกลงกันไว้
• เรียกใช้การทดสอบการรวมระบบใน CI ที่ไม่เคยแตะปลายทางที่ต้องเสียเงิน
• บังคับการตอบสนองเฉพาะเจาะจง; ผลลัพธ์ว่างเปล่า, 500, ฟิลด์ผิดรูปแบบ; เพื่อดูว่าเอเจนต์ของคุณตอบสนองอย่างไร

ชี้ตัวดำเนินการเครื่องมือของเอเจนต์ของคุณไปยัง URL พื้นฐานของการจำลองระหว่างการพัฒนา โมเดลเรียก get_weather, โค้ดของคุณเรียกใช้ Apidog mock, และการตอบสนองที่ถูกต้องจะกลับมาทันที เมื่อคุณพร้อมสำหรับของจริง ให้สลับ URL พื้นฐานผ่านตัวแปรสภาพแวดล้อม การจำลองคือสิ่งที่ทำให้การพัฒนาเอเจนต์รวดเร็วและกำหนดได้; แนวทางเดียวกันนี้ใช้ในการทำงาน การทดสอบเอเจนต์ AI ที่จริงจังทุกรูปแบบ

ขั้นตอนที่ 3: เชื่อมต่อเอเจนต์เพื่อเรียกใช้เครื่องมือ

เมื่อมีปลายทางและการจำลองพร้อมแล้ว โค้ดเอเจนต์ก็ยังคงบางเบา นี่คือรูปแบบของลูปการเรียกใช้เครื่องมือโดยใช้ Claude Messages API; คำจำกัดความของเครื่องมือสะท้อนโครงสร้างที่คุณสร้างใน Apidog

import anthropic, requests, os

client = anthropic.Anthropic()
TOOL_BASE = os.environ["TOOL_BASE_URL"]  # Apidog mock during dev, real API in prod

tools = [{
    "name": "get_weather",
    "description": "Get current weather for a city",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

def run_tool(name, args):
    if name == "get_weather":
        r = requests.get(f"{TOOL_BASE}/weather", params={"city": args["city"]}, timeout=10)
        r.raise_for_status()
        return r.json()

messages = [{"role": "user", "content": "What should I wear in Tokyo today?"}]
while True:
    resp = client.messages.create(
        model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages
    )
    if resp.stop_reason == "tool_use":
        block = next(b for b in resp.content if b.type == "tool_use")
        result = run_tool(block.name, block.input)
        messages.append({"role": "assistant", "content": resp.content})
        messages.append({"role": "user", "content": [{
            "type": "tool_result", "tool_use_id": block.id,
            "content": str(result),
        }]})
    else:
        print(resp.content[0].text)
        break

บรรทัด timeout=10 และ raise_for_status() มีความสำคัญมากกว่าการเรียกใช้โมเดล สิ่งเหล่านี้คือความแตกต่างระหว่างเอเจนต์ที่ล้มเหลวเสียงดัง กับเอเจนต์ที่ส่งคำขอที่ค้างหรือมีข้อผิดพลาดกลับเข้าสู่ลูปอย่างเงียบๆ สำหรับมุมมองที่กว้างขึ้นว่าเอเจนต์เข้ากันได้กับเวิร์กโฟลว์ API อย่างไร รูปแบบใน 5 เอเจนต์ AI สำหรับเวิร์กโฟลว์ API ของคุณ เป็นคู่มือที่มีประโยชน์

ขั้นตอนที่ 4: ทดสอบการเรียกใช้เครื่องมือ ไม่ใช่แค่ความรู้สึก

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

สำหรับปลายทางเครื่องมือแต่ละตัว ให้ยืนยัน:

• สถานะเป็น 200 สำหรับอินพุตที่ถูกต้อง
• เนื้อหาการตอบกลับตรงกับโครงสร้าง; Apidog จะตรวจสอบความถูกต้องของการตอบกลับกับคำจำกัดความ OpenAPI ของคุณโดยอัตโนมัติ
• ฟิลด์ที่จำเป็นที่โมเดลจะอ่านต้องมีอยู่และมีประเภทที่ถูกต้อง
• เวลาตอบกลับอยู่ภายในเวลาที่เอเจนต์ของคุณกำหนด

จากนั้นทดสอบเส้นทางที่ไม่สมบูรณ์ เพราะนั่นคือที่ที่เอเจนต์ทำงานผิดปกติ:

• ส่งอาร์กิวเมนต์ที่ผิดรูปแบบที่โมเดลอาจสร้างหลอน; city ที่ว่างเปล่า, ตัวเลขที่ควรจะเป็นสตริง; และยืนยันว่าคุณได้ 400/422 ที่สะอาด ไม่ใช่ 500
• บังคับการตอบสนองข้อผิดพลาดจากการจำลองและยืนยันว่า run_tool ของเอเจนต์ของคุณจะเกิดข้อผิดพลาดแทนที่จะคืนค่าขยะ
• ทดสอบผลลัพธ์ที่ว่างเปล่าและตรวจสอบว่าเอเจนต์จัดการกับ "ไม่มีข้อมูล" แทนที่จะสร้างคำตอบขึ้นมาเอง

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

ขั้นตอนที่ 5: จัดการการลองใหม่ (retries), การหมดเวลา (timeouts) และการจำกัดอัตรา (rate limits)

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

• การหมดเวลา (Timeouts) กำหนดเวลาหมดเวลาที่ชัดเจนสำหรับการเรียกใช้เครื่องมือทุกครั้ง ดังตัวอย่างข้างต้น จากนั้นใช้ Apidog เพื่อจำลองปลายทางที่ช้าและยืนยันว่าไคลเอ็นต์ของคุณยุติการทำงานอย่างสะอาดแทนที่จะทำให้ลูปทั้งหมดค้าง
• การลองใหม่พร้อมการถอยหลัง (Retries with backoff) ลองใหม่สำหรับความล้มเหลวชั่วคราว แต่กำหนดขีดจำกัดจำนวนครั้งและถอยหลัง ทดสอบกับข้อมูลจำลองที่ล้มเหลวสองครั้งแล้วจึงสำเร็จ และยืนยันว่าเอเจนต์ของคุณสามารถกู้คืนได้แทนที่จะวนลูปไปเรื่อยๆ
• การจำกัดอัตรา (Rate limits) คาดการณ์ 429 ภายใต้โหลด จำลองการตอบสนองที่มีการจำกัดอัตราและตรวจสอบว่าเอเจนต์ของคุณรอและลองใหม่แทนที่จะรัวเรียก หากคุณเคยจัดการกับปัญหานี้บน API ของโมเดลดิบ; ดู การจำกัดอัตรา API ของ GPT สำหรับปัญหาในประเภทเดียวกัน; เวอร์ชันเอเจนต์นั้นเข้มงวดกว่าเนื่องจากลูปจะเพิ่มจำนวนการเรียกแต่ละครั้ง
• การตัดวงจร (Circuit breaking) หลังจากความล้มเหลว N ครั้งของเครื่องมือ ให้หยุดเรียกใช้และให้เอเจนต์รายงานความล้มเหลวแทนที่จะหมุนวนไปเรื่อยๆ ทดสอบว่าตัวตัดวงจรทำงาน

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

ขั้นตอนที่ 6: รันแบบครบวงจรกับข้อมูลจำลองใน CI

เชื่อมโยงทุกอย่างเข้าด้วยกัน ใน CI ให้เริ่มต้นเอเจนต์ของคุณโดยชี้ไปยัง Apidog mock server ป้อนเป้าหมายผู้ใช้ชุดที่กำหนดไว้ และยืนยันผลลัพธ์สุดท้ายและลำดับการเรียกใช้เครื่องมือ เนื่องจากข้อมูลจำลองนั้นเป็นแบบกำหนดได้ อินพุตเดียวกันจะสร้างการเรียกใช้เครื่องมือเดียวกันทุกครั้งที่รัน ดังนั้นการทดสอบเอเจนต์ของคุณจึงไม่เกิดความไม่แน่นอน เมื่อคุณมั่นใจแล้ว ให้เปลี่ยน URL พื้นฐานเป็น API จริงสำหรับการทดสอบ smoke test สดขนาดเล็ก การแบ่งส่วนนี้; ข้อมูลจำลองที่กำหนดได้สำหรับการทดสอบส่วนใหญ่, การตรวจสอบสดแบบบางๆ สำหรับความเป็นจริง; คือสิ่งที่ทำให้ การทดสอบ AI แบบเอเจนต์ เป็นไปได้ในทางปฏิบัติ แทนที่จะเป็นเพียงความใฝ่ฝัน

รายการตรวจสอบสำหรับเอเจนต์ที่น่าเชื่อถือ

• [ ] เครื่องมือทุกอย่างถูกกำหนดเป็น API operation จริงพร้อมโครงสร้าง OpenAPI
• [ ] มีข้อมูลจำลองสำหรับเครื่องมือทุกอย่างเพื่อให้คุณสามารถสร้างและทดสอบแบบออฟไลน์ได้
• [ ] ปลายทางเครื่องมือแต่ละตัวมีการยืนยันสถานะ, โครงสร้าง, และเวลา
• [ ] เส้นทางที่ไม่สมบูรณ์; อาร์กิวเมนต์ไม่ถูกต้อง, ข้อผิดพลาด, ผลลัพธ์ว่างเปล่า; ได้รับการทดสอบอย่างชัดเจน
• [ ] การหมดเวลา, การลองใหม่พร้อมการถอยหลัง, และการจัดการการจำกัดอัตราอยู่ในโค้ดและได้รับการทดสอบแล้ว
• [ ] การรันแบบครบวงจรใน CI ดำเนินการลูปทั้งหมดกับข้อมูลจำลองที่กำหนดได้

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

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

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

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

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

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

สิ่งนี้ใช้ได้กับเฟรมเวิร์กอย่าง LangChain หรือ Claude Agent SDK หรือไม่? ได้ เลเยอร์เครื่องมือเป็นเพียง HTTP ไม่ว่าเฟรมเวิร์กใดจะขับเคลื่อนลูป ให้ชี้การเรียกใช้เครื่องมือไปยังข้อมูลจำลองของ Apidog สำหรับการทดสอบ และไปยังปลายทางจริงสำหรับการใช้งานจริง ดู คู่มือ Claude Code SDK สำหรับหนึ่งในลูปดังกล่าว

สรุป

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