Interactions API

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

เหตุใดจึงต้องใช้ Interactions API

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

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

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

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

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

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

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

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

เมื่อคุณเรียกใช้ interactions.create คุณกำลัง สร้างทรัพยากร Interaction ใหม่

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

โมเดลและ Agent ที่รองรับ

ชื่อแบบจำลอง ประเภท รหัสโมเดล
Gemini 3.5 Flash โมเดล gemini-3.5-flash
Gemini 3.1 Flash-Lite โมเดล gemini-3.1-flash-lite
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 Clip (เวอร์ชันตัวอย่าง) โมเดล 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 รองรับฟีเจอร์ต่อไปนี้ แต่ ยังไม่ พร้อมใช้งาน ใน Interactions APIgenerateContent

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

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

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

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

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

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

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

ความคิดเห็น

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

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