Interactions API

Interactions API เป็นมาตรฐานใหม่สำหรับการสร้างด้วย Gemini และเราขอแนะนำให้ใช้กับโปรเจ็กต์ใหม่ทั้งหมด โดยได้รับการเพิ่มประสิทธิภาพสำหรับเวิร์กโฟลว์แบบ Agent การจัดการสถานะฝั่งเซิร์ฟเวอร์ และการสนทนาแบบหลายโมดอลและหลายรอบที่ซับซ้อน เรายังคงรองรับ API ของ generateContent เดิมอย่างเต็มรูปแบบ

เหตุใดจึงควรใช้ Interactions API

  • การจัดการประวัติฝั่งเซิร์ฟเวอร์: ลดความซับซ้อนของโฟลว์แบบหลายรอบผ่าน previous_interaction_id เซิร์ฟเวอร์จะเปิดใช้สถานะโดยค่าเริ่มต้น (store=true) แต่คุณเลือกใช้ลักษณะการทำงานแบบไม่มีสถานะได้โดยการตั้งค่า store=false
  • ขั้นตอนการดำเนินการที่สังเกตได้: ขั้นตอนที่พิมพ์ทำให้การแก้ไขข้อบกพร่องของโฟลว์ที่ซับซ้อนเป็นเรื่องง่าย และแสดงผล UI สำหรับเหตุการณ์ระดับกลาง (เช่น ความคิดหรือวิดเจ็ตการค้นหา)
  • สร้างขึ้นสำหรับเวิร์กโฟลว์แบบ Agentic: รองรับการใช้เครื่องมือแบบหลายขั้นตอน การประสานงาน และการให้เหตุผลที่ซับซ้อนผ่านขั้นตอนการดำเนินการที่พิมพ์
  • งานที่ทำอยู่เบื้องหลังและใช้เวลานาน: รองรับการส่งต่อการดำเนินการที่ใช้เวลานาน เช่น Deep Think และ Deep Research ไปยังกระบวนการเบื้องหลังโดยใช้ background=true
  • สิทธิ์เข้าถึงโมเดลและความสามารถใหม่ๆ: ในอนาคต โมเดลใหม่ๆ ที่นอกเหนือจากตระกูลหลัก รวมถึงความสามารถด้าน Agentic AI และเครื่องมือใหม่ๆ จะเปิดตัวใน Interactions API เท่านั้น

ใช้ Interactions API หากคุณกำลังเริ่มโปรเจ็กต์ใหม่ สร้างแอปพลิเคชันแบบเอเจนต์ หรือต้องการการจัดการการสนทนาฝั่งเซิร์ฟเวอร์ ใช้ generateContent หากคุณมีการผสานรวมอยู่แล้วซึ่งตรงกับความต้องการ หรือหากคุณต้องการฟีเจอร์ที่ยังไม่พร้อมใช้งานใน Interactions API เช่น Batch API หรือการแคชอย่างชัดเจน

เริ่มต้นใช้งาน

  • ตั้งค่าเอเจนต์การเขียนโค้ด: เชื่อมต่อกับ MCP ของเอกสาร Gemini แล้วติดตั้งgemini-interactions-apiทักษะเพื่อให้ผู้ช่วยเข้าถึงเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์และแนวทางปฏิบัติแนะนำล่าสุดได้โดยตรง ตั้งค่า Agent การเขียนโค้ด →
  • ย้ายข้อมูลจาก generateContent: หากมีการผสานรวมอยู่แล้ว โปรดทำตามคำแนะนำในการย้ายข้อมูลเพื่อ เปลี่ยนไปใช้ Interactions API
  • ลองใช้การเริ่มต้นอย่างรวดเร็ว: เริ่มต้นใช้งานด้วยตัวอย่างการทำงานขั้นต่ำในการเริ่มต้นอย่างรวดเร็วของ Interactions API

คำแนะนำฟีเจอร์

สำรวจความสามารถเฉพาะของ Interactions API ผ่านคำแนะนำเหล่านี้ คุณใช้ปุ่มเปิด/ปิดในหน้าเหล่านี้เพื่อสลับระหว่าง API ของฟังก์ชัน generateContent กับ API ของฟังก์ชัน Interactions ได้

วิธีการทำงานของ Interactions API

API การโต้ตอบมุ่งเน้นไปที่ทรัพยากรหลัก ซึ่งก็คือ Interaction Interaction หมายถึงการสนทนาหรือการทำงานที่เสร็จสมบูรณ์ โดยจะทำหน้าที่เป็นบันทึกเซสชัน ซึ่งมีประวัติการโต้ตอบทั้งหมดเป็นลำดับขั้นตอนการดำเนินการตามลำดับเวลา ขั้นตอนเหล่านี้รวมถึงความคิดของโมเดล การเรียกใช้เครื่องมือและผลลัพธ์ฝั่งเซิร์ฟเวอร์หรือฝั่งไคลเอ็นต์ (เช่น function_call และ function_result) และ model_output สุดท้าย ทรัพยากรที่จัดเก็บ (ดึงข้อมูลผ่าน interactions.get) ยังมีขั้นตอน user_input สำหรับบริบททั้งหมดด้วย แม้ว่าคำตอบ interactions.create จะแสดงเฉพาะขั้นตอนที่โมเดลสร้างขึ้นก็ตาม

เมื่อโทรหา interactions.create คุณจะ สร้างทรัพยากร Interaction ใหม่

เข้าถึงเอาต์พุตด้วยพร็อพเพอร์ตี้ความสะดวกของ SDK

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

SDK ของ Google GenAI มีพร็อพเพอร์ตี้ความสะดวกโดยตรง ในออบเจ็กต์ Interaction ที่ส่งคืนเพื่อเข้าถึงเอาต์พุตสำหรับรูปแบบต่างๆ

พร็อพเพอร์ตี้ความสะดวกของ SDK ประเภทการแสดงผล คำอธิบาย
interaction.output_text สตริง แสดงบล็อกข้อความสุดท้ายในคำตอบของโมเดล หากคำตอบแยกออกเป็นหลายTextContentบล็อกที่ต่อเนื่องกัน ระบบจะรวมบล็อกเหล่านั้นโดยอัตโนมัติ โดยจะไม่รวมบล็อกข้อความก่อนหน้าซึ่งคั่นด้วยเนื้อหาที่ไม่ใช่ข้อความ (เช่น ความคิด รูปภาพ เสียง หรือการเรียกใช้เครื่องมือ) สำหรับคำตอบแบบมัลติโมดอลที่ซับซ้อนหรือสลับกัน คุณต้องวนซ้ำผ่าน steps ด้วยตนเองแทน
interaction.output_image ImageContent หรือ None แสดงบล็อกรูปภาพสุดท้ายที่โมเดลสร้างขึ้นในคำขอปัจจุบัน
interaction.output_audio AudioContent หรือ None แสดงบล็อกเสียงสุดท้ายที่โมเดลสร้างขึ้นในคำขอปัจจุบัน

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

การจัดการสถานะฝั่งเซิร์ฟเวอร์

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

พารามิเตอร์ previous_interaction_id จะเก็บเฉพาะประวัติการสนทนา (อินพุตและเอาต์พุต) โดยใช้ previous_interaction_id พารามิเตอร์อื่นๆ เป็นระดับการโต้ตอบ และมีผลกับการโต้ตอบเฉพาะที่คุณกําลังสร้างเท่านั้น

  • tools
  • system_instruction
  • generation_config (รวมถึง thinking_level, temperature ฯลฯ)

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

การจัดเก็บและการเก็บรักษาข้อมูล

โดยค่าเริ่มต้น API จะจัดเก็บออบเจ็กต์การโต้ตอบทั้งหมด (store=true) เพื่อลดความซับซ้อนในการใช้ฟีเจอร์การจัดการสถานะฝั่งเซิร์ฟเวอร์ (ด้วย previous_interaction_id), การดำเนินการในเบื้องหลัง (โดยใช้ background=true) และวัตถุประสงค์ด้านความสามารถในการสังเกต

  • ระดับแบบชำระเงิน: ระบบจะเก็บรักษาการโต้ตอบไว้เป็นเวลา 55 วัน
  • รุ่นฟรี: ระบบจะเก็บการโต้ตอบไว้เป็นเวลา 1 วัน

หากไม่ต้องการให้ระบบดำเนินการ คุณ ตั้งค่า store=false ในคำขอได้ การควบคุมนี้แยกจากการจัดการสถานะ คุณเลือกไม่ใช้พื้นที่เก็บข้อมูลสำหรับการโต้ตอบใดก็ได้ อย่างไรก็ตาม โปรดทราบว่า store=false ใช้ร่วมกับ background=true ไม่ได้ และจะป้องกันไม่ให้ใช้ previous_interaction_id ในรอบถัดไป

คุณลบการโต้ตอบที่จัดเก็บไว้ได้ทุกเมื่อโดยใช้วิธีการลบที่อยู่ในเอกสารอ้างอิง API คุณจะลบการโต้ตอบได้ก็ต่อเมื่อ ทราบรหัสการโต้ตอบ

หลังจากระยะเวลาการเก็บรักษาหมดอายุแล้ว ระบบจะลบข้อมูลของคุณโดยอัตโนมัติ

ระบบจะประมวลผลออบเจ็กต์การโต้ตอบตามข้อกำหนด

แนวทางปฏิบัติแนะนำ

  • อัตราการพบแคช: การใช้ previous_interaction_id เพื่อสนทนาต่อ ช่วยให้ระบบใช้แคชโดยนัยสำหรับ ประวัติการสนทนาได้ง่ายขึ้น ซึ่งจะช่วยปรับปรุงประสิทธิภาพและลดต้นทุน
  • การโต้ตอบแบบผสม: คุณสามารถผสมผสานการโต้ตอบของเอเจนต์และโมเดลในการสนทนาได้อย่างยืดหยุ่น ตัวอย่างเช่น คุณสามารถใช้ Agent เฉพาะทาง เช่น Deep Research Agent เพื่อรวบรวมข้อมูลเริ่มต้น จากนั้นใช้โมเดล Gemini มาตรฐานสำหรับงานติดตามผล เช่น การสรุปหรือการจัดรูปแบบใหม่ โดยเชื่อมโยงขั้นตอนเหล่านี้กับ previous_interaction_id

โมเดลและเอเจนต์ที่รองรับ

ชื่อแบบจำลอง ประเภท รหัสโมเดล
Gemini 3.5 Flash รุ่น gemini-3.5-flash
Gemini 3.1 Flash-Lite รุ่น gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite (เวอร์ชันตัวอย่าง) รุ่น gemini-3.1-flash-lite-preview
เวอร์ชันตัวอย่างของ Gemini 3.1 Pro รุ่น gemini-3.1-pro-preview
Gemini 3 Flash (เวอร์ชันตัวอย่าง) รุ่น gemini-3-flash-preview
Gemini 2.5 Pro รุ่น gemini-2.5-pro
Gemini 2.5 Flash รุ่น gemini-2.5-flash
Gemini 2.5 Flash-lite รุ่น gemini-2.5-flash-lite
ตัวอย่างคลิป Lyria 3 รุ่น lyria-3-clip-preview
เวอร์ชันตัวอย่างของ Lyria 3 Pro รุ่น lyria-3-pro-preview
Deep Research เวอร์ชันตัวอย่าง Agent deep-research-pro-preview-12-2025
Deep Research เวอร์ชันตัวอย่าง Agent deep-research-preview-04-2026
Deep Research เวอร์ชันตัวอย่าง Agent deep-research-max-preview-04-2026

SDK

คุณสามารถใช้ Google GenAI SDK เวอร์ชันล่าสุดเพื่อเข้าถึง Interactions API

  • ใน Python นี่คือแพ็กเกจ google-genai ตั้งแต่เวอร์ชัน 1.55.0 เป็นต้นไป
  • ใน JavaScript นี่คือแพ็กเกจ @google/genai จากเวอร์ชัน 1.33.0 เป็นต้นไป

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีติดตั้ง SDK ได้ในหน้าคลัง

ข้อจำกัด

  • สถานะเบต้า: Interactions API อยู่ในเวอร์ชันเบต้า/เวอร์ชันตัวอย่าง ฟีเจอร์และ สคีมาอาจมีการเปลี่ยนแปลง
  • MCP ระยะไกล: Gemini 3 ไม่รองรับ MCP ระยะไกล โดยจะพร้อมใช้งานเร็วๆ นี้

API ของ generateContent รองรับฟีเจอร์ต่อไปนี้ แต่ยังไม่พร้อมใช้งานใน Interactions API

การเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ

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

การเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบที่มีอยู่

  • สคีมาขั้นตอน: อาร์เรย์ขั้นตอนใหม่จะแทนที่อาร์เรย์เอาต์พุต ซึ่งจะแสดงไทม์ไลน์ที่มีโครงสร้างของการโต้ตอบแต่ละรอบ

ดูข้อมูลเกี่ยวกับการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นล่าสุดและวิธีย้ายข้อมูลได้ที่คำแนะนำในการย้ายข้อมูลการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่น (พฤษภาคม 2026)

การอัปเดตอื่นๆ ที่อาจเกิดขึ้นอาจรวมถึงการเปลี่ยนแปลงสคีมาสำหรับอินพุตและเอาต์พุต ลายเซ็นของเมธอด SDK และโครงสร้างออบเจ็กต์ ลักษณะการทำงานของฟีเจอร์ที่เฉพาะเจาะจง

สำหรับภาระงานการผลิต คุณควรใช้ generateContent API มาตรฐานต่อไป ซึ่งยังคงเป็นเส้นทางที่แนะนำสำหรับการติดตั้งใช้งานที่เสถียร และเราจะยังคงพัฒนาและดูแลรักษาต่อไป

ความคิดเห็น

ความคิดเห็นของคุณมีความสำคัญอย่างยิ่งต่อการพัฒนา Interactions API แชร์ความคิดเห็น รายงานข้อบกพร่อง หรือขอฟีเจอร์ได้ในฟอรัมชุมชนนักพัฒนาแอป Google AI

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