গভীর গবেষণা, জটিল যুক্তি বিশ্লেষণ, বা একাধিক ধাপে এজেন্ট সম্পাদনের মতো দীর্ঘস্থায়ী কাজগুলির ক্ষেত্রে, সংযোগের সময়সীমা শেষ হয়ে গেলে সাধারণ HTTP অনুরোধগুলি (যা সাধারণত ৬০ সেকেন্ড পরে বন্ধ হয়ে যায়) বাধাগ্রস্ত হতে পারে। ইন্টারঅ্যাকশনস এপিআই এই কাজগুলিকে অ্যাসিঙ্ক্রোনাসভাবে চালানোর জন্য ব্যাকগ্রাউন্ড এক্সিকিউশনের সুবিধা প্রদান করে।
সার্ভারে কাজটি সম্পন্ন না হওয়া পর্যন্ত ইন্টারঅ্যাকশনটি চালু রাখতে, ইন্টারঅ্যাকশন তৈরি করার সময় "background": true সেট করুন। এপিআই তাৎক্ষণিকভাবে একটি ইন্টারঅ্যাকশন আইডি ফেরত দেয়, যা ক্লায়েন্ট অ্যাপ্লিকেশনগুলো স্ট্যাটাস পোল করতে, অগ্রগতির স্ট্রিম দেখতে, বা সংযোগ বিচ্ছিন্ন হওয়া স্ট্রিমে পুনরায় সংযোগ করতে ব্যবহার করতে পারে।
স্ট্যান্ডার্ড জেমিনি মডেল (যেমন gemini-3.5-flash এবং gemini-3.1-pro-preview ) এবং ম্যানেজড এজেন্ট (যেমন antigravity-preview-05-2026 )-এর জন্য ব্যাকগ্রাউন্ড এক্সিকিউশন সমর্থিত।
একটি ব্যাকগ্রাউন্ড ইন্টারঅ্যাকশন তৈরি করুন
ব্যাকগ্রাউন্ড ইন্টারঅ্যাকশন শুরু করতে, রিসোর্স তৈরি করার সময় background প্যারামিটারটি ' true তে সেট করুন।
পাইথন
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}")
জাভাস্ক্রিপ্ট
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}`);
বিশ্রাম
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: ক্লায়েন্টের অনুরোধে কার্যক্রমটি বন্ধ করা হয়েছে।
ব্যবহারের ক্ষেত্র
নিম্নলিখিত ক্ষেত্রে ব্যাকগ্রাউন্ড এক্সিকিউশন ব্যবহার করুন:
এজেন্ট এক্সিকিউশন: যেসব কাজের জন্য কোড এক্সিকিউশন, ওয়েব ব্রাউজিং, বা সাব-এজেন্ট অর্কেস্ট্রেশন (যেমন
antigravity-preview-05-2026) প্রয়োজন।গভীর গবেষণা: এটি
deep-research-preview-04-2026অথবাdeep-research-max-preview-04-2026ব্যবহার করে চলে এবং এতে কয়েক মিনিট সময় লাগে।দীর্ঘ যুক্তি: এমন কাজ যেখানে মডেল চিন্তার ধাপগুলো সাধারণ HTTP সংযোগের সীমা অতিক্রম করে।
ফলাফল পুনরুদ্ধার করুন
পোলিং অথবা স্ট্রিমিং ব্যবহার করে ব্যাকগ্রাউন্ড ইন্টারঅ্যাকশনের ফলাফল সংগ্রহ করুন।
পোলিং প্যাটার্ন (নন-ব্লকিং)
পোলিং, নন-ব্লকিং GET অনুরোধ ব্যবহার করে পর্যায়ক্রমে ইন্টারঅ্যাকশনের অবস্থা পরীক্ষা করে, যতক্ষণ না এটি একটি টার্মিনাল অবস্থায় পৌঁছায়।
পাইথন
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}")
জাভাস্ক্রিপ্ট
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}`);
}
বিশ্রাম
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 থাকে। এই ID-টিকে last_event_id হিসেবে পাস করলে সেই ইভেন্ট থেকে স্ট্রিমটি পুনরায় শুরু হয়।
পাইথন
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)
জাভাস্ক্রিপ্ট
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);
বিশ্রাম
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উভয়ই অন্তর্ভুক্ত থাকতে হবে।
নিম্নলিখিত উদাহরণগুলি দেখায় কিভাবে মিথস্ক্রিয়াগুলিকে শৃঙ্খলিত করা যায়:
পাইথন
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
)
জাভাস্ক্রিপ্ট
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
});
বিশ্রাম
# 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ত্রুটি ফেরত দেয়।
পাইথন
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")
জাভাস্ক্রিপ্ট
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");
বিশ্রাম
# 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"
পরবর্তী পদক্ষেপ
- সেশন এবং স্টেট ম্যানেজমেন্ট বুঝতে ইন্টারঅ্যাকশনস এপিআই ওভারভিউটি পড়ুন।
- রিয়েল-টাইম ইভেন্ট আপডেট সম্পর্কে বিস্তারিত জানতে স্ট্রিমিং ইন্টারঅ্যাকশন গাইডটি দেখুন।
- স্টেটফুল মাল্টি-টার্ন এজেন্ট তৈরি করতে ম্যানেজড এজেন্ট কুইকস্টার্টটি দেখুন।