Next ‘26 Developer Keynote: Debugging Agents At Scale

1. บทนำ

ใน Codelab นี้ คุณจะได้เรียนรู้วิธีแก้ไขข้อบกพร่องของ AI Agent ที่ทำงานใน Google Cloud คุณจะติดตั้งใช้งาน Agent จำลองใน Agent Runtime, ใช้ Cloud Observability เพื่อตรวจหาปัญหา และใช้ Gemini Cloud Assist และ Antigravity IDE เพื่อหาสาเหตุและแก้ไขข้อผิดพลาดแบบเรียลไทม์

arch

สมมติฐานของการสาธิตนี้คือเราเพิ่งเพิ่ม ADK EventCompaction ลงใน Simulator Agent ซึ่งจะช่วยให้เครื่องจำลองสรุปเวิร์กโฟลว์เป็นระยะๆ โดยใช้ Gemini ซึ่งจะช่วยลดบริบททั้งหมดที่ส่งไปยังโมเดลในแต่ละรอบ จึงช่วยปรับปรุงคุณภาพการตอบกลับและลดต้นทุนโดยรวม แต่เราจะพบว่า EventCompactionConfig มีข้อบกพร่องซึ่งทำให้เกิดข้อผิดพลาดในเอเจนต์ Codelab นี้จะอธิบายวิธีค้นหาปัญหาประเภทดังกล่าวและแก้ไขอย่างรวดเร็ว

การบดอัด

สิ่งที่คุณต้องดำเนินการ

  • ทำให้ใช้งานได้กับ Agent Runtime
  • ตั้งค่าการแจ้งเตือนของ Cloud Monitoring เพื่อตรวจหาข้อผิดพลาดของตัวแทน
  • ตรวจสอบข้อผิดพลาดโดยใช้ Cloud Trace และ Gemini Cloud Assist
  • ระบุสาเหตุหลักและแก้ไขข้อบกพร่องของเอเจนต์โดยใช้ Antigravity และ MCP

สิ่งที่คุณต้องมี

  • เว็บเบราว์เซอร์ เช่น Chrome
  • บัญชี Google
  • Antigravity (รองรับ Mac, Linux และ Windows)
  • Python 3.13 ขึ้นไป
  • uv (เครื่องมือจัดการแพ็กเกจ Python)

ระยะเวลาโดยประมาณ: 45 นาที

ค่าใช้จ่ายโดยประมาณ: น้อยกว่า $5 USD

2. ก่อนเริ่มต้น

สร้างโปรเจ็กต์ Google Cloud

  1. ในคอนโซล Google Cloud ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud
  2. ตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์แล้ว

ตั้งค่าสภาพแวดล้อม

เปิด Antigravity แล้วลงชื่อเข้าใช้ จากนั้นเปิดเทอร์มินัลโดยกด cmd-shift-P (หรือ ctrl-shift-P) แล้วพิมพ์ "สร้างเทอร์มินัลใหม่"

เทอร์มินัล

  1. ตรวจสอบสิทธิ์กับ Google Cloud จากเทอร์มินัลโดยทำดังนี้
gcloud auth login
gcloud auth application-default login
  1. ตั้งค่ารหัสโปรเจ็กต์
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

เปิดใช้ API

เรียกใช้คำสั่งต่อไปนี้เพื่อเปิดใช้ Google Cloud APIs ที่จำเป็น

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. ตั้งค่า Simulator Agent

ในขั้นตอนนี้ คุณจะโคลนที่เก็บข้อมูลเดโมและกำหนดค่าตัวแปรสภาพแวดล้อมสำหรับ Simulator Agent

โคลนที่เก็บ

โคลนที่เก็บ next-26-keynotes แล้วไปที่ไดเรกทอรีการสาธิต

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

กำหนดค่าตัวแปรสภาพแวดล้อม

เอเจนต์จำลองใช้ไฟล์ .env สำหรับการกำหนดค่า

ค้นหาไฟล์ sample.env ทางด้านซ้ายของหน้าต่าง Antigravity (Explorer)

explorer

เปิด sample.env และอัปเดตฟิลด์ GCP_PROJECT_ID ด้วยรหัสโปรเจ็กต์ Google Cloud จริงของคุณ ไฟล์ควรมีลักษณะคล้ายกับตัวอย่างต่อไปนี้

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

4. ทำให้ Agent จำลองใช้งานได้กับ Agent Runtime

ตอนนี้คุณจะติดตั้งใช้งาน Agent ใน Agent Runtime โดยใช้ Agent Development Kit (ADK)

ติดตั้งการอ้างอิง

uv sync

ทำให้ใช้งานได้กับ Agent Runtime

  1. เรียกใช้คำสั่ง adk deploy ขั้นตอนนี้จะแพ็กเกจ Agent และติดตั้งใช้งานใน Google Cloud (Agent Runtime)
uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

การดำเนินการนี้อาจใช้เวลาถึง 5 นาที ในที่สุดคุณจะเห็นเอาต์พุตลักษณะนี้

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...
  1. เปิดคอนโซลรันไทม์ของเอเจนต์จากเว็บเบราว์เซอร์ คุณควรเห็น simulator_agent ทำงานใน Agent Runtime โดยเปิดใช้การรวบรวมข้อมูลการวัดและส่งข้อมูล

img

5. ตั้งค่านโยบายการแจ้งเตือน

หากต้องการตรวจหาข้อผิดพลาดรันไทม์ของ Agent โดยอัตโนมัติ คุณจะต้องสร้างการแจ้งเตือนตามบันทึกในคอนโซล Google Cloud

  1. ไปที่คอนโซล Cloud Monitoring - การแจ้งเตือน

img

  1. คลิกแก้ไขช่องทางการแจ้งเตือน เลื่อนลงไปที่ประเภทอีเมล แล้วสร้างช่องการแจ้งเตือนทางอีเมลเพื่อส่งไปยังอีเมลส่วนตัว คลิกบันทึก

img

  1. กลับไปที่แดชบอร์ดการแจ้งเตือน แล้วคลิกสร้างนโยบาย
  2. คลิกสร้างการแจ้งเตือนตามบันทึกที่ด้านขวาของหน้าจอ

img

  1. ระบบจะเปลี่ยนเส้นทางคุณไปยังเครื่องมือสำรวจบันทึก วางการค้นหาบันทึกต่อไปนี้ โดยแทนที่ด้วยรหัสโปรเจ็กต์ของคุณ
resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

img

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

img

  1. กำหนดค่าการแจ้งเตือนตามบันทึก ตั้งชื่อการแจ้งเตือน (ชื่อใดก็ได้) แล้วตั้งระดับความรุนแรงเป็นข้อผิดพลาด

img

  1. คลิกถัดไปสำหรับส่วน "ตั้งค่าความถี่ในการแจ้งเตือน" (คงค่าเริ่มต้นไว้)

img

  1. สำหรับบุคคลที่ควรได้รับการแจ้งเตือน ให้ตั้งค่าการแจ้งเตือนให้ทริกเกอร์ช่องทางการแจ้งเตือนทางอีเมลที่คุณเพิ่งตั้งค่า (เช่น My Email)
  2. คลิกบันทึก

6. ทริกเกอร์เหตุการณ์

ตอนนี้เมื่อติดตั้งใช้งานและตรวจสอบเอเจนต์แล้ว ลองเรียกใช้การจำลองการวิ่งมาราธอนในลักษณะที่ทำให้เกิดข้อผิดพลาด

  1. ในคอนโซล Google Cloud ให้ไปที่คอนโซลรันไทม์ของ Agent
  2. คลิก simulator_agent
  3. จากแถบเครื่องมือด้านบน ให้คลิก Playground ซึ่งจะเป็นการเริ่มเซสชันใหม่กับตัวแทน ADK

img

  1. จากหน้าต่างแชทของเซสชัน ให้พิมพ์ Test Simulation แล้วกด Enter เพื่อส่งพรอมต์

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

  1. ภายใน 1 นาที คุณจะได้รับอีเมลในกล่องจดหมาย ซึ่งแจ้งเตือนถึงเหตุการณ์ใหม่ภายในเอเจนต์

img

คลิกดูเหตุการณ์เพื่อเปิดคอนโซล Cloud Monitoring ไปที่หน้าถัดไปเพื่อตรวจสอบปัญหาภายใน Console

7. ตรวจสอบเหตุการณ์ในคอนโซล

  1. ดูเหตุการณ์ในคอนโซล Cloud Monitoring คุณควรเห็นบันทึกข้อผิดพลาดที่มาจาก Simulator Agent

img

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

  1. เปิดคอนโซล Agent Runtime อีกครั้ง คลิก simulator_agent แล้วเปิดแท็บ Traces

img

  1. คลิกร่องรอยล่าสุดในรายการ จากนั้นคลิกไทม์ไลน์ที่ด้านขวาบน คุณควรเห็นมุมมองการติดตามที่มี "ช่วง" แต่ละช่วง หนึ่งช่วงคือการเรียกใช้โมเดลหรือเครื่องมือภายในเวิร์กโฟลว์ของเอเจนต์

img

  1. คลิกช่วงสุดท้ายในมุมมองการติดตาม ควรเป็นสีแดง
  2. คลิก Stacktrace คุณควรเห็นบันทึกข้อผิดพลาดที่เกี่ยวข้องกับการเรียกโมเดล Gemini API โดยเฉพาะข้อผิดพลาด 400: Invalid Argument ซึ่งส่งสัญญาณถึงปัญหาที่ระดับคำขอที่มีเพย์โหลดที่ตัวแทนจำลองส่งไปยัง Gemini API

img

8. [ไม่บังคับ] ใช้การตรวจสอบด้วย Cloud Assist เพื่อแก้ไขข้อบกพร่อง

  1. คลิกบันทึกและเหตุการณ์ภายในช่วงที่ล้มเหลว ค้นหาบันทึก "ข้อยกเว้น" ที่มีปุ่มประกายดาวอยู่ข้างๆ จากนั้นคลิกตรวจสอบบันทึก

img

  1. ซึ่งจะเริ่มการตรวจสอบ Cloud Assist จากแถบด้านข้างทางด้านขวาของหน้าจอ โดยจะใช้เวลาโหลดประมาณ 3-5 นาที

img

  1. เมื่อเสร็จแล้ว ให้เปิดการตรวจสอบ

img

  1. ดูสรุปการตรวจสอบ

img

  1. เลื่อนลงและดูสมมติฐาน Gemini Cloud Assist ควรระบุบรรทัดที่เฉพาะเจาะจงในไฟล์ agent.py ของเอเจนต์จำลองที่ทำให้เกิดข้อผิดพลาด 400 ของ Gemini API

img

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

9. ใช้ Antigravity เพื่อหาสาเหตุหลักและแก้ไขปัญหา

  1. เปิด Antigravity อีกครั้ง
  2. เปิดAgent Manager ที่ด้านขวาบนของหน้าจอ

img

  1. ตรวจสอบว่าได้ตั้งค่าโมเดลเป็น Gemini 3 Flash และโหมดการวางแผน

img

  1. ป้อนพรอมต์ต่อไปนี้ แล้วกด Enter
Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.

คุณควรเห็น Antigravity ตรวจสอบโค้ดใน agent.py และค้นหาปัญหาที่เกี่ยวข้องใน GitHub

สาเหตุหลักของข้อผิดพลาด 400 ของ Gemini API คือเราใช้โทเค็นบริบทอินพุตของ Gemini 3 Flash เกินขีดจำกัดที่ประมาณ 1 ล้าน สาเหตุที่เกิดปัญหานี้เนื่องจากเราไม่ได้เรียกใช้ EventCompaction บ่อยพอที่จะสรุปการตอบกลับจำนวนมากจากการเรียกใช้เครื่องมือของ Simulator Agents ได้อย่างมีประสิทธิภาพ

หากต้องการแก้ไขปัญหานี้ Antigravity ควรแนะนําให้เพิ่มพารามิเตอร์ token_threshold ลงใน EventsCompactionConfig เพื่อบีบอัดบริบทเป็นระยะๆ ในการเรียกใช้แต่ละครั้งเมื่อเรามีโทเค็นถึงจํานวนหนึ่ง

img

ซึ่งสอดคล้องกับการแก้ไขที่แนะนำในปัญหา GitHub นี้

ใช้การแก้ไขกับ agent.py.

ตรวจสอบว่าคุณเห็นข้อความคล้ายกับข้อความต่อไปนี้

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

10. ติดตั้งใช้งานอีกครั้งและตรวจสอบการแก้ไข

ตอนนี้เราได้ใช้token_thresholdการแก้ไขกับEventCompactionConfigของ ADK Agent แล้ว เราจึงสามารถทำให้ Simulator Agent ใช้งานได้อีกครั้งใน Agent Runtime

  1. เปิด Antigravity –> New Terminal
  2. ตั้งค่าตัวแปรสภาพแวดล้อม AGENT_RUNTIME_ID ควรเป็นชื่อทรัพยากรแบบเต็มของ simulator_agent ซึ่งจะดูได้ในคอนโซลรันไทม์ของตัวแทน - รายการตัวแทน
export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"
  1. ติดตั้งใช้งาน Agent อีกครั้ง
uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

การดำเนินการนี้จะใช้เวลาสักครู่ เมื่อดำเนินการสำเร็จแล้ว คุณควรเห็นสิ่งต่อไปนี้

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...
  1. เปิดคอนโซลรันไทม์ของ Agent เปิด simulator_agent อีกครั้ง คลิก Playground
  2. ป้อนพรอมต์เดียวกัน: Test Simulation จากนั้นกด Enter
  3. การจำลอง Marathon ในแบ็กเอนด์ทั้งหมดควรใช้เวลาไม่กี่นาทีในการเรียกใช้ คุณควรเห็นการเรียกใช้เครื่องมือหลายรายการ ในที่สุด คุณจะเห็นคำตอบดังนี้

img

ซึ่งหมายความว่าเครื่องจำลองทำงานสำเร็จแล้ว ✅

  1. เปิดมุมมองการติดตามสำหรับเซสชัน ADK นั้น
  2. คุณควรเห็นช่วง "สีน้ำเงิน" ทั้งหมดโดยไม่มีข้อผิดพลาดสีแดง โปรดสังเกตว่าจำนวนโทเค็นทั้งหมดของเซสชันเกินขีดจำกัดโทเค็นบริบท 1 ล้านรายการของ Gemini API ไม่เป็นไร เนื่องจากตอนนี้ EventCompaction ทำงานบ่อยพอภายในแต่ละการเรียกใช้ เพื่อหลีกเลี่ยงการเกินขีดจำกัดบริบทโดยรวมสำหรับการเรียกโมเดลแต่ละรายการ

img

🎊 ไชโย! เราได้แก้ไขข้อผิดพลาดในเอเจนต์จำลองแล้ว

11. ล้างข้อมูล

โปรดลบทรัพยากรที่สร้างขึ้นระหว่างการทำ Codelab นี้เพื่อหลีกเลี่ยงการเรียกเก็บเงินจากบัญชี Google Cloud

ลบแอป Agent Runtime

คุณสามารถลบอินสแตนซ์ Reasoning Engine ผ่านคอนโซลหรือใช้คำสั่ง gcloud (หากมีชื่อทรัพยากร) ใช้คอนโซลเพื่อให้ง่ายขึ้น

  1. ไปที่หน้าAgent Runtime
  2. เลือก simulator_agent -> คลิกปุ่ม 3 จุดทางด้านขวา
  3. คลิกลบ

img

ลบนโยบาย Cloud Monitoring

  1. ไปที่คอนโซล Cloud Monitoring -> การแจ้งเตือน
  2. เลื่อนลงไปที่นโยบาย แล้วคลิกปุ่มจุด 3 จุดเพื่อลบนโยบาย

img

12. 🎊 ยินดีด้วย

ยินดีด้วย คุณเพิ่งแก้ไขข้อบกพร่องของ AI Agent ใน Google Cloud เรียบร้อยแล้ว

สิ่งที่คุณได้เรียนรู้

  • วิธีทำให้ Agent ใช้งานได้กับ Agent Runtime
  • วิธีตรวจหาข้อผิดพลาดโดยใช้การแจ้งเตือนของ Cloud Monitoring
  • วิธีสํารวจเหตุการณ์ที่ใช้งานอยู่โดยใช้ Cloud Logging และมุมมองการติดตามของ Agent Runtime
  • วิธีตรวจสอบความล้มเหลวโดยใช้ Gemini Cloud Assist
  • วิธีใช้ Antigravity เพื่อหาสาเหตุหลักและแก้ไขข้อบกพร่องของเอเจนต์
  • วิธีปรับแต่งการลดขนาดเหตุการณ์ ADK เพื่อจัดการการเลี้ยวของ Agent ที่ใช้เครื่องมือหนักและใช้เวลานาน

ขั้นตอนถัดไป