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 . Përditësimet mund të përfshijnë ndryshime në:

• Skemat për të dhënat hyrëse dhe dalëse.
• Nënshkrimet e metodave SDK dhe strukturat e objekteve.
• Sjelljet e karakteristikave specifike.

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 .