สำหรับงานที่ใช้เวลานาน เช่น การค้นคว้าอย่างละเอียด การให้เหตุผลที่ซับซ้อน หรือการดำเนินการของเอเจนต์แบบหลายขั้นตอน การหมดเวลาการเชื่อมต่ออาจขัดจังหวะคำขอ HTTP มาตรฐาน (ซึ่งโดยปกติจะปิดหลังจาก 60 วินาที) Interactions API มีการดำเนินการเบื้องหลังเพื่อเรียกใช้งานแบบไม่พร้อมกัน
หากต้องการให้การโต้ตอบทำงานจนกว่าจะทำงานบนเซิร์ฟเวอร์เสร็จสมบูรณ์ ให้ตั้งค่า "background": true เมื่อสร้างการโต้ตอบ API จะแสดงรหัสการโต้ตอบทันที ซึ่งแอปพลิเคชันไคลเอ็นต์สามารถใช้เพื่อสำรวจสถานะ ความคืบหน้าของสตรีม หรือเชื่อมต่อสตรีมที่ถูกตัดการเชื่อมต่ออีกครั้ง
ระบบรองรับการดำเนินการเมื่ออยู่เบื้องหลังสำหรับโมเดล Gemini มาตรฐาน (เช่น gemini-3.5-flash และ gemini-3.1-pro-preview) และเอเจนต์ที่มีการจัดการ (เช่น antigravity-preview-05-2026)
สร้างการโต้ตอบในเบื้องหลัง
หากต้องการเริ่มการโต้ตอบในเบื้องหลัง ให้ตั้งค่าพารามิเตอร์ background เป็น true เมื่อสร้างทรัพยากร
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.5-flash",
input="Write a guide on space exploration.",
background=True,
)
print(f"Created background interaction ID: {interaction.id}")
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.5-flash",
input: "Write a guide on space exploration.",
background: true,
});
console.log(`Created background interaction ID: ${interaction.id}`);
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3.5-flash",
"input": "Write a guide on space exploration.",
"background": true
}'
วิธีการทำงานของการดำเนินการในเบื้องหลัง
เมื่อสร้างการโต้ตอบในเบื้องหลัง งานจะทำงานแบบไม่พร้อมกันในเซิร์ฟเวอร์ การโต้ตอบจะเปลี่ยนสถานะการดำเนินการต่างๆ ดังนี้
in_progress: เซิร์ฟเวอร์กำลังดำเนินการโต้ตอบอยู่ (เช่น การเรียกใช้โค้ดหรือการค้นคว้า)requires_action: การโต้ตอบหยุดชั่วคราวและรอข้อมูลจากไคลเอ็นต์ (เช่น การยืนยันการเรียกใช้เครื่องมือหรือการตอบคำถาม)completed: การโต้ตอบเสร็จสมบูรณ์และเอาต์พุตพร้อมใช้งานแล้วfailed: เกิดข้อผิดพลาดในระหว่างการดำเนินการ (เช่น เครื่องมือล้มเหลวหรือเกินขีดจำกัดอัตรา)cancelled: คำขอของไคลเอ็นต์หยุดการดำเนินการ
กรณีการใช้งาน
ใช้การดำเนินการเมื่ออยู่เบื้องหลังสำหรับรายการต่อไปนี้
การดำเนินการของ Agent: งานที่ต้องมีการเรียกใช้โค้ด การท่องเว็บ หรือการจัดระเบียบ Agent ย่อย (เช่น
antigravity-preview-05-2026)Deep Research: ทำงานโดยใช้
deep-research-preview-04-2026หรือdeep-research-max-preview-04-2026ซึ่งใช้เวลาหลายนาทีการให้เหตุผลแบบยาว: งานที่ขั้นตอนการคิดของโมเดลเกินขีดจำกัดการเชื่อมต่อ HTTP มาตรฐาน
เรียกดูผลลัพธ์
รับผลลัพธ์การโต้ตอบเบื้องหลังโดยใช้การสำรวจหรือการสตรีม
รูปแบบการสำรวจ (ไม่บล็อก)
การสำรวจจะตรวจสอบสถานะการโต้ตอบเป็นระยะๆ โดยใช้คำขอ GET ที่ไม่บล็อกจนกว่าจะถึงสถานะสิ้นสุด
Python
import time
from google import genai
client = genai.Client()
interaction = client.interactions.get(id="YOUR_INTERACTION_ID")
while interaction.status == "in_progress":
time.sleep(5)
interaction = client.interactions.get(id=interaction.id)
if interaction.status == "completed":
print(interaction.output_text)
else:
print(f"Finished with status: {interaction.status}")
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
let interaction = await client.interactions.get("YOUR_INTERACTION_ID");
while (interaction.status === "in_progress") {
await new Promise(resolve => setTimeout(resolve, 5000));
interaction = await client.interactions.get(interaction.id);
}
if (interaction.status === "completed") {
console.log(interaction.output_text);
} else {
console.log(`Finished with status: ${interaction.status}`);
}
REST
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20"
รูปแบบการสตรีม
หากเครือข่ายหยุดทำงานจนทำให้สตรีมถูกตัดขาด สตรีมมิงจะกลับมาทำงานต่อจากเหตุการณ์ล่าสุดที่ได้รับ โดยแต่ละเดลต้าจะมี event_id ที่ไม่ซ้ำกันในเพย์โหลด การส่งรหัสนี้เป็น last_event_id จะทำให้สตรีมเล่นต่อจากเหตุการณ์นั้น
Python
import time
from google import genai
client = genai.Client()
interaction_id = "YOUR_INTERACTION_ID"
def stream_with_reconnect(interaction_id: str):
last_event_id = None
while True:
try:
# Retrieve the stream. If resuming, pass last_event_id
stream = client.interactions.get(
id=interaction_id,
stream=True,
last_event_id=last_event_id
)
for event in stream:
# Log event updates and capture event_id if present
if event.event_id:
last_event_id = event.event_id
if event.event_type == "step.delta" and event.delta.type == "text":
print(event.delta.text, end="", flush=True)
if event.event_type == "interaction.completed":
return
except Exception as e:
print(f"\n[Connection lost: {e}. Reconnecting in 3s...]")
time.sleep(3)
stream_with_reconnect(interaction_id)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interactionId = "YOUR_INTERACTION_ID";
async function streamWithReconnect(id) {
let lastEventId = undefined;
while (true) {
try {
// Retrieve the stream. If resuming, pass last_event_id in options
const stream = await client.interactions.get(id, {
stream: true,
last_event_id: lastEventId
});
for await (const event of stream) {
// Capture event_id if present
const idVal = event.event_id || event.id;
if (idVal) {
lastEventId = idVal;
}
if (event.event_type === "step.delta" && event.delta?.type === "text") {
process.stdout.write(event.delta.text);
}
if (event.event_type === "interaction.completed") {
return;
}
}
} catch (error) {
console.log(`\n[Connection lost: ${error.message}. Reconnecting in 3s...]`);
await new Promise(resolve => setTimeout(resolve, 3000));
}
}
}
await streamWithReconnect(interactionId);
REST
curl -N -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID?stream=true&last_event_id=YOUR_LAST_EVENT_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20"
การสนทนาไปมา
การโต้ตอบในภายหลังจะเชื่อมโยงกับการสนทนาในเบื้องหลังได้โดยใช้ previous_interaction_id โดยขึ้นอยู่กับข้อจำกัดต่อไปนี้
- การดำเนินการที่ใช้งานอยู่จะถูกบล็อก: การเชื่อมต่อการโต้ตอบที่ตามมากับการโต้ตอบที่มี
in_progressสถานะจะแสดงข้อผิดพลาด400 Bad Requestรอให้การโต้ตอบถึงสถานะcompletedก่อนเริ่มการโต้ตอบถัดไป - พารามิเตอร์สภาพแวดล้อมสำหรับเอเจนต์ที่มีการจัดการ: เมื่อเชื่อมโยงการโต้ตอบสำหรับเอเจนต์ที่มีการจัดการ (เช่น
antigravity-preview-05-2026) คำขอต้องมีทั้งprevious_interaction_idและenvironment
ตัวอย่างต่อไปนี้แสดงวิธีเชื่อมโยงการโต้ตอบ
Python
import time
from google import genai
client = genai.Client()
agent_model = "antigravity-preview-05-2026"
# First interaction: Provision sandbox environment and execute first instruction
interaction1 = client.interactions.create(
model=agent_model,
input="Create a folder named project/ and write hello.py inside.",
environment="remote",
background=True
)
# Wait for completion
while True:
check = client.interactions.get(id=interaction1.id)
if check.status != "in_progress":
break
time.sleep(2)
# Second interaction: Chain using previous_interaction_id and environment
interaction2 = client.interactions.create(
model=agent_model,
input="List all files in the project/ directory.",
previous_interaction_id=interaction1.id,
environment="remote",
background=True
)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const agentModel = "antigravity-preview-05-2026";
// First interaction: Provision sandbox environment and execute first instruction
const interaction1 = await client.interactions.create({
model: agentModel,
input: "Create a folder named project/ and write hello.py inside.",
environment: "remote",
background: true
});
// Wait for completion
while (true) {
const check = await client.interactions.get(interaction1.id);
if (check.status !== "in_progress") {
break;
}
await new Promise(resolve => setTimeout(resolve, 2000));
}
// Second interaction: Chain using previous_interaction_id and environment
const interaction2 = await client.interactions.create({
model: agentModel,
input: "List all files in the project/ directory.",
previous_interaction_id: interaction1.id,
environment: "remote",
background: true
});
REST
# Chain second interaction (Make sure FIRST_INTERACTION_ID has status 'completed')
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "antigravity-preview-05-2026",
"input": "List all files in the project/ directory.",
"previous_interaction_id": "FIRST_INTERACTION_ID",
"environment": "remote",
"background": true
}'
การยกเลิกและการลบ
ควบคุมการดำเนินการที่กำลังทำงานและจัดการพื้นที่เก็บข้อมูลโดยใช้คำขอยกเลิกและลบ
- ยกเลิก (
POST /interactions/{id}/cancel): หยุดงานที่กำลังทำงานอยู่ สถานะจะเปลี่ยนเป็นcancelledการดำเนินการล้างข้อมูลในเซิร์ฟเวอร์อาจทำให้เกิดความล่าช้าเล็กน้อยก่อนที่สถานะจะอัปเดตในคำขอ GET ลบ (
DELETE /interactions/{id}): นำบันทึกการโต้ตอบออกจากเซิร์ฟเวอร์ คำขอ GET ที่ตามมาจะแสดงข้อผิดพลาด404 Not Found
Python
from google import genai
client = genai.Client()
# Cancel a running interaction
client.interactions.cancel(id="YOUR_INTERACTION_ID")
# Delete the interaction record entirely
client.interactions.delete(id="YOUR_INTERACTION_ID")
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
// Cancel a running interaction
await client.interactions.cancel("YOUR_INTERACTION_ID");
// Delete the interaction record entirely
await client.interactions.delete("YOUR_INTERACTION_ID");
REST
# Cancel the interaction
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID/cancel" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20"
# Delete the interaction
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20"
ขั้นตอนถัดไป
- อ่านภาพรวมของ Interactions API เพื่อทำความเข้าใจการจัดการเซสชันและสถานะ
- ดูรายละเอียดเกี่ยวกับการอัปเดตกิจกรรมแบบเรียลไทม์ได้ในคำแนะนำเกี่ยวกับการโต้ตอบในการสตรีม
- ดูการเริ่มต้นใช้งานด่วนของ Agent ที่มีการจัดการเพื่อสร้าง Agent แบบหลายรอบที่มีสถานะ