API-ja e Ndërveprimeve

API-ja e Interactions është primitivi i ri standard për ndërtimin me Gemini, i rekomanduar për të gjitha projektet e reja. Është i optimizuar për rrjedhat e punës së agjentëve, menaxhimin e gjendjes nga ana e serverit dhe bisedat komplekse shumëmodale me shumë kthesa. API-ja origjinale generateContent mbetet e mbështetur plotësisht.

Pse të përdoret API-ja e Ndërveprimeve?

• Menaxhimi i historikut nga ana e serverit : Flukse të thjeshtuara me shumë kthesa nëpërmjet previous_interaction_id . Serveri aktivizon gjendjen si parazgjedhje ( store=true ), por ju mund të zgjidhni sjelljen pa gjendje duke vendosur store=false .
• Hapat e ekzekutimit të vëzhgueshëm : Hapat e shtypur e bëjnë të lehtë debugimin e rrjedhave komplekse dhe paraqitjen e ndërfaqes së përdoruesit për ngjarje të ndërmjetme (si mendimet ose veglat e kërkimit).
• Ndërtuar për rrjedhat e punës agjentike : Mbështetje vendase për përdorimin e mjeteve me shumë hapa, orkestrimin dhe arsyetimin kompleks që rrjedh përmes hapave të ekzekutimit të tipizuar.
• Detyrat që ekzekutohen gjatë dhe në sfond : Mbështet transferimin e operacioneve që kërkojnë shumë kohë si Deep Think dhe Deep Research në proceset në sfond duke përdorur background=true .
• Qasja në modele dhe aftësi të reja : Duke shkuar përpara, modele të reja përtej familjes kryesore kryesore, së bashku me aftësi dhe mjete të reja agjentësh, do të lançohen ekskluzivisht në Interactions API.

Përdorni API-në e Interactions nëse po filloni një projekt të ri, po ndërtoni aplikacione agjentike ose nëse keni nevojë për menaxhim të bisedave nga ana e serverit. Përdorni generateContent nëse keni një integrim ekzistues që funksionon për nevojat tuaja, ose nëse keni nevojë për një veçori që nuk është ende e disponueshme në API-në e Interactions, siç është API-ja e Batch-it ose ruajtja në memorje të qartë.

Filloni

• Konfiguroni agjentin tuaj të kodimit : Lidhuni me Gemini Docs MCP dhe instaloni aftësinë gemini-interactions-api për t'i dhënë asistentit tuaj akses të drejtpërdrejtë në dokumentet dhe praktikat më të mira më të fundit të zhvilluesit. Konfiguroni agjentin tuaj të kodimit →
• Migroni nga generateContent : Nëse keni një integrim ekzistues, ndiqni Udhëzuesin e Migrimit për të kaluar në API-në e Ndërveprimeve.
• Provoni nisjen e shpejtë : Filloni me një shembull minimal funksional në nisjen e shpejtë të Interactions API .

Udhëzues për veçoritë

Eksploroni aftësitë specifike të Interactions API përmes këtyre udhëzuesve. Mund të përdorni butonin e ndërrimit në këto faqe për të kaluar midis generateContent dhe Interactions API:

• Gjenerimi i tekstit
• Gjenerimi i imazhit
• Kuptimi i imazhit
• Kuptimi i audios
• Kuptimi i videos
• Përpunimi i dokumenteve
• Thirrja e funksionit
• Prodhim i strukturuar
• Agjent i Kërkimeve të Thella
• Përfundim fleksibël
• Përfundimi i përparësisë

Si funksionon API-ja e Ndërveprimeve

API-ja e Ndërveprimeve përqendrohet rreth një burimi kryesor: Interaction . Një Interaction përfaqëson një kthesë të plotë në një bisedë ose detyrë. Ai vepron si një regjistrim sesioni, që përmban të gjithë historinë e një ndërveprimi si një sekuencë kronologjike hapash ekzekutimi . Këta hapa përfshijnë mendime modeli, thirrje dhe rezultate mjetesh nga serveri ose klienti (si function_call dhe function_result ), dhe model_output përfundimtar. Burimi i ruajtur (i marrë nëpërmjet interactions.get ) përfshin gjithashtu hapa user_input për kontekst të plotë, megjithëse përgjigja interactions.create kthen vetëm hapa të gjeneruar nga modeli.

Kur bëni një thirrje në interactions.create , ju po krijoni një burim të ri Interaction .

Menaxhimi i gjendjes nga ana e serverit

Mund të përdorni id në e një bashkëveprimi të përfunduar në një thirrje pasuese duke përdorur parametrin previous_interaction_id për të vazhduar bisedën. Serveri përdor këtë ID për të rimarrë historikun e bisedës, duke ju kursyer nga ridërgimi i të gjithë historikut të bisedës.

Parametri previous_interaction_id ruan vetëm historikun e bisedës (të dhënat hyrëse dhe dalëse) duke përdorur previous_interaction_id . Parametrat e tjerë janë të përcaktuar sipas ndërveprimit dhe zbatohen vetëm për ndërveprimin specifik që po gjeneroni aktualisht:

• tools
• system_instruction
• generation_config (duke përfshirë thinking_level , temperature , etj.)

Kjo do të thotë që duhet t'i rispecifikoni këto parametra në çdo bashkëveprim të ri nëse dëshironi që ato të zbatohen. Ky menaxhim i gjendjes nga ana e serverit është opsional; gjithashtu mund të veproni në modalitetin pa gjendje duke dërguar historikun e plotë të bisedës në çdo kërkesë.

Ruajtja dhe ruajtja e të dhënave

Si parazgjedhje, API ruan të gjitha objektet e Ndërveprimit ( store=true ) për të thjeshtuar përdorimin e veçorive të menaxhimit të gjendjes në anën e serverit (me previous_interaction_id ), ekzekutimin në sfond (duke përdorur background=true ) dhe për qëllime vëzhgueshmërie.

• Niveli i Paguar : Sistemi ruan ndërveprimet për 55 ditë .
• Niveli Falas : Sistemi ruan ndërveprimet për 1 ditë .

Nëse nuk e dëshironi këtë, mund të vendosni store=false në kërkesën tuaj. Ky kontroll është i ndarë nga menaxhimi i gjendjes; mund të zgjidhni të mos përdorni hapësirën e ruajtjes për çdo ndërveprim. Megjithatë, vini re se store=false nuk është i përputhshëm me background=true dhe parandalon përdorimin e previous_interaction_id për raundet pasuese.

Mund t’i fshini ndërveprimet e ruajtura në çdo kohë duke përdorur metodën e fshirjes që gjendet në Referencën API . Mund t’i fshini ndërveprimet vetëm nëse e dini ID-në e ndërveprimit.

Pas skadimit të periudhës së ruajtjes, të dhënat tuaja do të fshihen automatikisht.

Sistemi përpunon objektet e Ndërveprimit sipas termave .

Praktikat më të mira

• Shkalla e klikimeve në memorien e përkohshme : Përdorimi i previous_interaction_id për të vazhduar bisedat i lejon sistemit të përdorë më lehtë ruajtjen implicite në memorien e përkohshme për historikun e bisedave, gjë që përmirëson performancën dhe ul kostot.
• Përzierja e ndërveprimeve : Ju keni fleksibilitetin për të përzier dhe përputhur ndërveprimet e Agjentit dhe Modelit brenda një bisede. Për shembull, mund të përdorni një agjent të specializuar, si agjenti i Kërkimit të Thellë, për mbledhjen fillestare të të dhënave, dhe më pas të përdorni një model standard Gemini për detyra pasuese, të tilla si përmbledhja ose riformatimi, duke i lidhur këto hapa me previous_interaction_id .

Modele dhe agjentë të mbështetur

SDK-të

Mund të përdorni versionin më të fundit të SDK-ve të Google GenAI për të aksesuar API-në e Ndërveprimeve.

• Në Python, kjo është paketa google-genai nga versioni 1.55.0 e tutje.
• Në JavaScript, kjo është paketa @google/genai nga versioni 1.33.0 e tutje.

Mund të mësoni më shumë rreth mënyrës së instalimit të SDK-ve në faqen e Bibliotekave .

Kufizime

• Statusi Beta : API-ja e Ndërveprimeve është në fazën beta/parapamjeje. Karakteristikat dhe skemat mund të ndryshojnë.
• MCP në distancë : Gemini 3 nuk e mbështet MCP në distancë, kjo do të vijë së shpejti.

Karakteristikat e mëposhtme mbështeten nga generateContent API, por nuk janë ende të disponueshme në Interactions API:

• Meta të dhëna videoje : Fusha video_metadata , përdoret për të vendosur intervalet e prerjes dhe shpejtësitë e personalizuara të kuadrove për të kuptuar videon.
• API-ja e grupeve
• Thirrja automatike e funksionit (Python)
• Ruajtja në memorje të qartë : Vini re se ruajtja në memorje e nënkuptuar nga ana e serverit është e disponueshme në Interactions API nëpërmjet previous_interaction_id .

Ndryshime të rëndësishme

API-ja e Ndërveprimeve është aktualisht në një fazë të hershme beta. Ne po zhvillojmë dhe përsosim në mënyrë aktive aftësitë e API-t, skemat e burimeve dhe ndërfaqet e SDK-së bazuar në përdorimin në botën reale dhe reagimet e zhvilluesve. Si rezultat, mund të ndodhin ndryshime të rëndësishme .

Ndryshimet ekzistuese prishëse:

• Skema e hapave : Një varg i ri hapash zëvendëson vargun e rezultateve, duke ofruar një afat kohor të strukturuar për çdo kthesë të ndërveprimit.

Për të mësuar rreth ndryshimit më të fundit shqetësues dhe për të kuptuar se si të migroni, shihni udhëzuesin e migrimit të ndryshimeve shqetësuese (maj 2026) .

Përditësime të tjera të mundshme mund të përfshijnë ndryshime në skemat për hyrjen dhe daljen, nënshkrimet e metodave SDK dhe strukturat e objekteve, si dhe sjelljet specifike të veçorive.

Për ngarkesat e punës në prodhim, duhet të vazhdoni të përdorni API-n standard generateContent . Mbetet rruga e rekomanduar për vendosje të qëndrueshme dhe ne do të vazhdojmë ta zhvillojmë dhe mirëmbajmë atë në mënyrë aktive.

Reagime

Reagimet tuaja janë thelbësore për zhvillimin e API-t të Ndërveprimeve. Ndani mendimet tuaja, raportoni gabime ose kërkoni veçori në Forumin tonë të Komunitetit të Zhvilluesve të IA-së në Google .

Çfarë vjen më pas

• Provo fletoren e nisjes së shpejtë të Interactions API .
• Mësoni më shumë rreth Agjentit të Kërkimeve të Thellë Gemini .