‫Interactions API (میانای برنامه‌سازی کاربردی تعاملات)

«میانای برنامه‌سازی کاربردی تعامل‌ها» بهترین روش برای ساختن با مدل‌های Gemini و عامل‌ها است. از ژوئن ۲۰۲۶، این ویژگی «عموماً دردسترس» است و برای همه پروژه‌های جدید توصیه می‌شود. اگرچه اکنون قدیمی درنظر گرفته می‌شود، اما generateContent میانای برنامه‌سازی کاربردی اصلی همچنان به‌طور کامل پشتیبانی می‌شود.

چرا از Interactions API استفاده کنیم؟

• میانای جهانی برای همه برنامه‌ها: به‌عنوان میانای استاندارد برای هر مورد استفاده‌ای، ازجمله تولید نوشتار تک‌نوبتی، درک چندحالته، بروندادهای ساختاریافته، هماهنگی ابزار، و گردش‌های کار عامل طراحی شده است.
• میانای برنامه‌سازی کاربردی واحد برای مدل‌ها و کارگزاران: یک نقطه پایانی و الگوی یکپارچه برای فراخوانی مستقیم مدل‌های استاندارد Gemini و همچنین کارگزاران تخصصی (مانند Deep Research و کارگزاران مدیریت‌شده سفارشی).
• قابلیت‌های جدید آماده استفاده: ویژگی‌هایی مثل وضعیت اختیاری مکالمه در سمت سرور بااستفاده از previous_interaction_id، مراحل اجرای قابل‌مشاهده برای اشکال‌زدایی و پرداز میانای کاربر، و اجرای پس‌زمینه برای کارهای طولانی‌مدت بااستفاده از background=true.
• هزینه کمتر با نرخ اصابت حافظه نهان بالاتر: هنگام استفاده از مکالمه‌های چند نوبتی، مدیریت وضعیت اختیاری در سمت سرور امکان ذخیره کردن زمینه‌های مکالمه در حافظه نهان را در نوبت‌های مختلف به‌طور کارآمدتر فراهم می‌کند و هزینه نشان‌ها را کاهش می‌دهد.
• محل راه‌اندازی ویژگی‌های جدید: ازاین‌پس، همه مدل‌های جدید، قابلیت‌های چندوجهی، ابزارها، و ویژگی‌های عامل در «میاناهای برنامه‌سازی کاربردی تعاملات» راه‌اندازی خواهند شد.

به‌طور پیش‌فرض، «میانای برنامه‌سازی کاربردی تعاملات» درخواست‌ها را ذخیره می‌کند تا بتوانید بااستفاده از previous_interaction_id از ویژگی‌های مدیریت وضعیت سمت سرور بهره ببرید. با تنظیم store=false می‌توانید رفتار بدون حالت را انتخاب کنید. برای جزئیات، بخش نگهداری داده‌ها را ببینید.

شروع کنید

• راه‌اندازی عامل کدنویسی: به Gemini Docs MCP متصل شوید و مهارت gemini-api-dev را نصب کنید تا دستیارتان به جدیدترین اسناد توسعه‌دهنده و روال‌های مطلوب دسترسی مستقیم داشته باشد. برای مراحل دقیق، به راهنمای راه‌اندازی عامل کدنویسی مراجعه کنید
• انتقال از generateContent: اگر یک ادغام موجود دارید، برای انتقال به Interactions API، راهنمای انتقال را دنبال کنید.
• شروع به کار: مراحل موجود در راهنمای شروع به کار Interactions API را دنبال کنید.

راهنمای ویژگی‌ها

ازطریق این راهنماها، قابلیت‌های خاص «میانای برنامه‌سازی کاربردی تعاملات» را کاوش کنید. می‌توانید از کلید تغییر وضعیت در این صفحه‌ها برای جابه‌جایی بین generateContent و Interactions API استفاده کنید:

• تولید نوشتار
• تولید تصویر
• درک تصویر
• درک صدا
• درک ویدیو
• پردازش سند
• فراخوانی تابع
• برونداد ساختاریافته
• کارگزار Deep Research
• استنتاج انعطاف‌پذیر
• استنباط اولویت

نحوه عملکرد Interactions API

‫Interactions API حول یک منبع اصلی می‌چرخد: Interaction. Interaction نشان‌دهنده یک نوبت کامل در مکالمه یا تکلیف است. این فایل به‌عنوان سابقه جلسه عمل می‌کند و حاوی کل سابقه تعامل به‌عنوان توالی زمانی مراحل اجرا است. این مراحل شامل افکار مدل، تماس‌ها و نتایج ابزار سمت سرور یا سمت مشتری (مثل function_call و function_result)، و model_output نهایی است. منبع ذخیره‌شده (دریافت‌شده ازطریق interactions.get) همچنین شامل user_input مرحله برای بافت کامل است، اگرچه پاسخ interactions.create فقط مراحل تولیدشده توسط مدل را برمی‌گرداند.

وقتی با interactions.create تماس می‌گیرید، منبع Interaction جدیدی ایجاد می‌کنید:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'

مدیریت وضعیت سمت سرور

می‌توانید از id تعامل تکمیل‌شده در تماس بعدی بااستفاده از پارامتر previous_interaction_id برای ادامه مکالمه استفاده کنید. کاربر سرور از این شناسه برای بازیابی سابقه مکالمه استفاده می‌کند و دیگر لازم نیست کل سابقه گپ را دوباره ارسال کنید:

from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}

# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_interaction_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)، و اهداف مشاهده‌پذیری را ساده کند.

• سطح پولی: سیستم تعاملات را برای ۵۵ روز حفظ می‌کند.
• سطح رایگان: سیستم تعاملات را برای ۱ روز حفظ می‌کند.

اگر این را نمی‌خواهید، می‌توانید store=false را در درخواستتان تنظیم کنید. این کنترل از مدیریت وضعیت جدا است؛ می‌توانید برای هر تعاملی از ذخیره‌سازی انصراف دهید. بااین‌حال، توجه داشته باشید که store=false با اجرای پس‌زمینه‌ای سازگار نیست و مانع استفاده از previous_interaction_id برای نوبت‌های بعدی می‌شود.

برای پروژه‌های «سطح پولی»، می‌توانید پنجره نگهداری را در AI Studio پیکربندی کنید تا گزارش‌ها به‌طور خودکار برای حذف از فضای ذخیره‌سازی پروژه پس‌از ۷، ۱۴، ۲۸، یا ۵۵ روز علامت‌گذاری شوند. دوره نگهداری کوتاه‌تر ممکن است بر بازیابی مکالمه‌های قبلی تأثیر بگذارد.

هرزمان بخواهید می‌توانید تعاملات ذخیره‌شده را بااستفاده از delete روش برنامه‌ریزی‌شده حذف کنید، که به شناسه تعامل نیاز دارد. همچنین می‌توانید گزارش‌های تعامل ذخیره‌شده، ازجمله حذف از فضای ذخیره‌سازی پروژه، را در AI Studio مشاهده و مدیریت کنید.

پس‌از پایان دوره نگهداری، داده‌هایتان به‌طور خودکار حذف خواهد شد.

اشیا تعامل براساس شرایط پردازش می‌شوند.

مشاهده تعاملات در AI Studio

«میانای برنامه‌سازی کاربردی» درخواست‌های «میانای برنامه‌سازی کاربردی تعامل‌ها» را که با store=true برای پروژه‌های «سطح پولی» اجرا شده است ذخیره می‌کند. می‌توانید آن‌ها را مستقیماً از صفحه «گزارش‌ها» در Google AI Studio مشاهده کنید. برای اطلاعات بیشتر، راهنمای گزارش‌ها را ببینید.

روال‌های مطلوب

• نرخ اصابت حافظه نهان: حافظه نهان ضمنی در هر دو حالت با وضعیت و بدون وضعیت پشتیبانی می‌شود (به راه‌اندازی سریع مراجعه کنید). استفاده از previous_interaction_id (حالت‌دار) برای ادامه مکالمه‌ها به سیستم امکان می‌دهد راحت‌تر از حافظه نهان ضمنی برای سابقه مکالمه استفاده کند، که عملکرد را بهبود می‌بخشد و هزینه‌ها را کاهش می‌دهد.
• ترکیب تعاملات: شما این انعطاف‌پذیری را دارید که تعاملات «عامل» و «مدل» را در یک مکالمه ترکیب کنید و مطابقت دهید. برای مثال، می‌توانید از یک عامل تخصصی، مثل عامل «پژوهش عمیق»، برای جمع‌آوری اولیه داده‌ها استفاده کنید، و سپس از یک مدل استاندارد Gemini برای کارهای پیگیری مثل خلاصه کردن یا قالب‌بندی مجدد استفاده کنید، و این مراحل را با previous_interaction_id پیوند دهید.

مدل‌ها و نمایندگان پشتیبانی‌شده

کیت‌های توسعه نرم‌افزار

برای دسترسی به میانای برنامه‌سازی کاربردی «تعاملات»، می‌توانید از جدیدترین نسخه «کیت‌های توسعه نرم‌افزار هوش مصنوعی زایای Google» استفاده کنید.

• در Python، این google-genai بسته از نسخه 2.3.0 به بعد است.
• در جاوا اسکریپت، این بسته @google/genai از نسخه 2.3.0 به‌بعد است.
• در Go، این بسته google.golang.org/genai است.
• در جاوا، این com.google.genai:google-genai بسته است.

می‌توانید درباره نحوه نصب کیت‌های توسعه نرم‌افزار در صفحه کتابخانه‌ها بیشتر بدانید.

محدودیت‌ها

• ‫MCP از دور: Gemini 3 از MCP از دور پشتیبانی نمی‌کند، این ویژگی به‌زودی ارائه می‌شود.
• سازگاری مدل چندنوبتی: هنگام ترکیب مدل‌های مختلف در یک مکالمه (چه حالت‌دار و چه بدون حالت)، مدل‌های بعدی باید از روش‌های خروجی مدل‌های قبلی به‌عنوان ورودی پشتیبانی کنند. برای مثال، اگر بااستفاده از gemini-3.1-flash-image تصویری تولید کنید، نمی‌توانید آن مکالمه را با مدلی که ورودی تصویر نمی‌پذیرد (مثل مدل فقط نوشتاری یا مدل تولید موسیقی مثل Lyria) ادامه دهید.

ویژگی‌های زیر توسط generateContent API پشتیبانی می‌شوند اما هنوز دردسترس نیستند در Interactions API:

• Batch API
• فراخوانی خودکار تابع (Python)
• ذخیره صریح در حافظه نهان: توجه داشته باشید که ذخیره ضمنی در حافظه نهان سمت سرور در «میانای برنامه‌سازی کاربردی تعامل‌ها» ازطریق previous_interaction_id دردسترس است.
• تنظیمات ایمنی: تنظیمات ایمنی سفارشی در «میانای برنامه‌سازی کاربردی تعاملات» پشتیبانی نمی‌شود.

بازخورد

بازخورد شما برای توسعه «میانای برنامه‌سازی کاربردی تعاملات» بسیار مهم است. در تالار گفتمان انجمن توسعه‌دهندگان هوش مصنوعی Google، نظراتتان را هم‌رسانی کنید، اشکالات را گزارش کنید، یا ویژگی درخواست کنید.

قدم بعدی چیست

• دفترچه شروع سریع «میانای برنامه‌سازی کاربردی تعاملات» را امتحان کنید.
• درباره عامل Gemini Deep Research بیشتر بدانید.