API для взаимодействия теперь общедоступн. Мы рекомендуем использовать этот API для доступа ко всем новейшим функциям и моделям.
Отправить отзыв
Начало работы
Это руководство поможет вам начать работу с API Gemini, используя API взаимодействий . Вы совершите свой первый вызов API менее чем за минуту и изучите генерацию текста, понимание мультимодальных данных, генерацию изображений, структурированный вывод, инструменты, вызов функций, агентов и фоновое выполнение.
Используете агента для программирования? Установите навык, чтобы ваш агент всегда был в курсе последних изменений в API взаимодействия:
npx skills add google-gemini/gemini-skills --skill gemini-interactions-api API для взаимодействия доступен через SDK для Python и JavaScript , а также через REST.
1. Получите ключ API. Для использования API Gemini вам потребуется ключ API . Создайте его бесплатно, чтобы начать работу:
Создайте ключ API Gemini
Затем установите его в качестве переменной окружения:
export GEMINI_API_KEY = "YOUR_API_KEY"
2. Установите SDK и совершите свой первый звонок. Установите SDK и генерируйте текст одним вызовом API.
Python Установите SDK:
pip install -U google-genai
Инициализируйте клиент и отправьте запрос:
from google import genai
client = genai . Client ()
interaction = client . interactions . create (
model = "gemini-3.5-flash" ,
input = "Explain how AI works in a few words"
)
print ( interaction . output_text )
JavaScript Установите SDK:
npm install @google/genai
Инициализируйте клиент и отправьте запрос:
import { GoogleGenAI } from "@google/genai" ;
const ai = new GoogleGenAI ({});
const interaction = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
input : "Explain how AI works in a few words" ,
});
console . log ( interaction . output_text );
ОТДЫХ
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"input": "Explain how AI works in a few words"
}'
Ответ:
{
"id" : "v1_ChdpQUFvYXI..." ,
"status" : "completed" ,
"usage" : {
"total_tokens" : 197 ,
"total_input_tokens" : 8 ,
"total_output_tokens" : 12
},
"created" : "2026-06-09T12:01:25Z" ,
"steps" : [
{
"type" : "thought" ,
"signature" : "EvEFCu4FAQw..."
},
{
"type" : "model_output" ,
"content" : [
{
"type" : "text" ,
"text" : "AI learns patterns from data, then uses those patterns to make predictions or decisions on new data."
}
]
}
],
"object" : "interaction" ,
"model" : "gemini-3.5-flash" ,
}
При использовании REST API возвращает полный ресурс Interaction , содержащий метаданные, статистику использования и пошаговую историю хода.
Хотя SDK предоставляют полный ответ, они также предлагают удобные свойства, такие как interaction.output_text и interaction.output_image для прямого доступа к конечным результатам. Подробнее о структуре ответа можно узнать в обзоре взаимодействий или в руководстве по генерации текста, где подробно описаны системные инструкции и конфигурация генерации.
3. Транслируйте ответ в прямом эфире. Для более плавной работы интерактивно передавайте ответ по мере его генерации. Каждое событие step.delta предоставляет фрагмент текста, который можно отобразить немедленно.
Python
from google import genai
client = genai . Client ()
stream = client . interactions . create (
model = "gemini-3.5-flash" ,
input = "Explain how AI works" ,
stream = True
)
for event in stream :
print ( event )
JavaScript
import { GoogleGenAI } from "@google/genai" ;
const ai = new GoogleGenAI ({});
const stream = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
input : "Explain how AI works" ,
stream : true ,
});
for await ( const event of stream ) {
console . log ( event );
}
ОТДЫХ
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
--no-buffer \
-d '{
"model": "gemini-3.5-flash",
"input": "Explain how AI works",
"stream": true
}'
При потоковой передаче сервер отвечает потоком событий, отправляемых сервером (SSE). Каждое событие включает в себя тип и данные в формате JSON.
Ответ:
eve nt : i ntera c t io n .crea te d
da ta : { "interaction" :{ "id" : "v1_Chd..." , "status" : "in_progress" , "model" : "gemini-3.5-flash" }, "event_type" : "interaction.created" }
eve nt : s te p.s tart
da ta : { "index" : 0 , "step" :{ "type" : "thought" }, "event_type" : "step.start" }
eve nt : s te p.del ta
da ta : { "index" : 0 , "delta" :{ "signature" : "EvEFCu4F..." , "type" : "thought_signature" }, "event_type" : "step.delta" }
eve nt : s te p.s t op
da ta : { "index" : 0 , "event_type" : "step.stop" }
eve nt : s te p.s tart
da ta : { "index" : 1 , "step" :{ "type" : "model_output" }, "event_type" : "step.start" }
eve nt : s te p.del ta
da ta : { "index" : 1 , "delta" :{ "text" : "AI " , "type" : "text" }, "event_type" : "step.delta" }
eve nt : s te p.del ta
da ta : { "index" : 1 , "delta" :{ "text" : "works " , "type" : "text" }, "event_type" : "step.delta" }
eve nt : s te p.s t op
da ta : { "index" : 1 , "event_type" : "step.stop" }
eve nt : i ntera c t io n .comple te d
da ta : { "interaction" :{ "id" : "v1_Chd..." , "status" : "completed" , "usage" :{ "total_tokens" : 197 }}, "event_type" : "interaction.completed" }
Для получения более подробной информации об обработке потоковых событий и типов изменений см. руководство по взаимодействию с потоковой передачей данных .
4. Многоэтапные переговоры API для взаимодействия поддерживает многоэтапные диалоги с использованием двух подходов:
С сохранением состояния (рекомендуется) Объединяйте взаимодействия в цепочку, передавая previous_interaction_id . Сервер управляет всей историей переписки за вас.
Python
from google import genai
client = genai . Client ()
# Server-side state (recommended)
interaction1 = client . interactions . create (
model = "gemini-3.5-flash" ,
input = "I have 2 dogs in my house." ,
)
print ( "Response 1:" , interaction1 . output_text )
interaction2 = client . interactions . create (
model = "gemini-3.5-flash" ,
input = "How many paws are in my house?" ,
previous_interaction_id = interaction1 . id ,
)
print ( "Response 2:" , interaction2 . output_text )
JavaScript
import { GoogleGenAI } from "@google/genai" ;
const ai = new GoogleGenAI ({});
// Server-side state (recommended)
const interaction1 = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
input : "I have 2 dogs in my house." ,
});
console . log ( "Response 1:" , interaction1 . output_text );
const interaction2 = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
input : "How many paws are in my house?" ,
previous_interaction_id : interaction1 . id ,
});
console . log ( "Response 2:" , interaction2 . output_text );
ОТДЫХ
RESPONSE1 = $( curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"input": "I have 2 dogs in my house."
}' )
INTERACTION_ID = $( echo " $RESPONSE1 " | jq -r '.id' )
echo "Interaction 1 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' \
-d '{
"model": "gemini-3.5-flash",
"input": "How many paws are in my house?",
"previous_interaction_id": "' $INTERACTION_ID '"
}'
Лица без гражданства Установите store=false и управляйте историей диалога на стороне клиента. Необходимо сохранять и повторно отправлять все шаги, сгенерированные моделью (включая шаги thought и function_call ), в точности так, как они были получены.
Python
from google import genai
client = genai . Client ()
history = [
{
"type" : "user_input" ,
"content" : [{ "type" : "text" , "text" : "I have 2 dogs in my house." }]
}
]
interaction1 = client . interactions . create (
model = "gemini-3.5-flash" ,
store = False ,
input = history
)
print ( "Response 1:" , interaction1 . steps [ - 1 ] . content [ 0 ] . text )
for step in interaction1 . steps :
history . append ( step . model_dump ())
history . append ({
"type" : "user_input" ,
"content" : [{ "type" : "text" , "text" : "How many paws are in my house?" }]
})
interaction2 = client . interactions . create (
model = "gemini-3.5-flash" ,
store = False ,
input = history
)
print ( "Response 2:" , interaction2 . steps [ - 1 ] . content [ 0 ] . text )
JavaScript
import { GoogleGenAI } from "@google/genai" ;
const ai = new GoogleGenAI ({});
const history = [
{
type : "user_input" ,
content : [{ type : "text" , text : "I have 2 dogs in my house." }]
}
];
const interaction1 = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
store : false ,
input : history
});
console . log ( "Response 1:" , interaction1 . steps . at ( - 1 ). content [ 0 ]. text );
history . push (... interaction1 . steps );
history . push ({
type : "user_input" ,
content : [{ type : "text" , text : "How many paws are in my house?" }]
});
const interaction2 = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
store : false ,
input : history
});
console . log ( "Response 2:" , interaction2 . steps . at ( - 1 ). content [ 0 ]. text );
ОТДЫХ
# Turn 1: Send with store: false
RESPONSE1 = $( curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"store": false,
"input": [
{
"type": "user_input",
"content": "I have 2 dogs in my house."
}
]
}' )
MODEL_STEPS = $( echo " $RESPONSE1 " | jq '.steps' )
# Turn 2: Build full history
HISTORY = $( jq -n \
--argjson first_input '[{"type": "user_input", "content": "I have 2 dogs in my house."}]' \
--argjson model_steps " $MODEL_STEPS " \
--argjson second_input '[{"type": "user_input", "content": "How many paws are in my house?"}]' \
'$first_input + $model_steps + $second_input' )
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d "{
\"model\": \"gemini-3.5-flash\",
\"store\": false,
\"input\": $HISTORY
}"
Ответ:
{
"id" : "v2_Chd..." ,
"status" : "completed" ,
"usage" : {
"total_tokens" : 240 ,
"total_input_tokens" : 60 ,
"total_output_tokens" : 20
},
"steps" : [
{
"type" : "model_output" ,
"content" : [
{
"type" : "text" ,
"text" : "There are 8 paws in your house. 2 dogs \u00d7 4 paws = 8 paws."
}
]
}
],
"object" : "interaction" ,
"model" : "gemini-3.5-flash"
}
Второе взаимодействие возвращает полный объект ответа, который включает только новые шаги, но основан на контексте предыдущего хода. Подробнее о поддержании состояния см. в руководстве по многоходовым диалогам или изучите режим без сохранения состояния для управления историей на стороне клиента.
5. Мультимодальное понимание Модели Gemini изначально понимают изображения, аудио, видео и документы. Передавайте медиафайлы вместе с текстом в одном запросе.
Python
import base64
from google import genai
client = genai . Client ()
# Load a local image
with open ( "sample.jpg" , "rb" ) as f :
image_bytes = f . read ()
image_b64 = base64 . b64encode ( image_bytes ) . decode ( "utf-8" )
interaction = client . interactions . create (
model = "gemini-3.5-flash" ,
input = [
{ "type" : "text" , "text" : "Compare this local image and this remote audio file." },
{
"type" : "image" ,
"data" : image_b64 ,
"mime_type" : "image/jpeg"
},
{
"type" : "audio" ,
"uri" : "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3" ,
"mime_type" : "audio/mp3"
}
]
)
print ( interaction . output_text )
JavaScript
import fs from "fs" ;
import { GoogleGenAI } from "@google/genai" ;
const ai = new GoogleGenAI ({});
// Load a local image
const imageBytes = fs . readFileSync ( "sample.jpg" );
const imageB64 = imageBytes . toString ( "base64" );
const interaction = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
input : [
{ type : "text" , text : "Compare this local image and this remote audio file." },
{
type : "image" ,
data : imageB64 ,
mime_type : "image/jpeg"
},
{
type : "audio" ,
uri : "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3" ,
mime_type : "audio/mp3"
}
],
});
console . log ( interaction . output_text );
ОТДЫХ
# Base64-encode local image
BASE64_IMAGE = $( base64 -w 0 sample.jpg)
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": [
{
"type": "text",
"text": "Compare this local image and this remote audio file."
},
{
"type": "image",
"data": "' $BASE64_IMAGE '",
"mime_type": "image/jpeg"
},
{
"type": "audio",
"uri": "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",
"mime_type": "audio/mp3"
}
]
}'
Ответ:
{
"id" : "v1_Chd..." ,
"status" : "completed" ,
"usage" : {
"total_tokens" : 300
},
"steps" : [
{
"type" : "model_output" ,
"content" : [
{
"type" : "text" ,
"text" : "The local image displays a pipe organ while the remote audio file is a sample MP3 clip..."
}
]
}
],
"object" : "interaction" ,
"model" : "gemini-3.5-flash" ,
}
Узнайте, как передавать изображения, видео и аудиофайлы, в руководстве по обработке изображений .
hearing
Понимание звука
Расшифровывайте, пересказывайте или отвечайте на вопросы об аудиофайлах.
videocam Понимание видео
Анализировать видеоконтент, определять события и описывать действия.
description Обработка документов
Извлечение информации из PDF-файлов и других форматов документов.
6. Мультимодальная генерация Gemini может генерировать изображения непосредственно с использованием моделей изображений Nano Banana .
Python
import base64
from google import genai
client = genai . Client ()
interaction = client . interactions . create (
model = "gemini-3.1-flash-image" ,
input = "Generate an image of a futuristic city skyline at sunset" ,
)
with open ( "generated_image.png" , "wb" ) as f :
f . write ( base64 . b64decode ( interaction . output_image . data ))
JavaScript
import { GoogleGenAI } from "@google/genai" ;
import * as fs from "node:fs" ;
const ai = new GoogleGenAI ({});
const interaction = await ai . interactions . create ({
model : "gemini-3.1-flash-image" ,
input : "Generate an image of a futuristic city skyline at sunset" ,
});
const generatedImage = interaction . output_image ;
if ( generatedImage ) {
const buffer = Buffer . from ( generatedImage . data , "base64" );
fs . writeFileSync ( "generated_image.png" , buffer );
}
ОТДЫХ
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.1-flash-image",
"input": [
{"type": "text", "text": "Generate an image of a futuristic city skyline at sunset"}
]
}'
Ответ:
{
"id" : "v1_Chd..." ,
"status" : "completed" ,
"steps" : [
{
"type" : "model_output" ,
"content" : [
{
"type" : "image" ,
"data" : "BASE64_ENCODED_IMAGE" ,
"mime_type" : "image/png"
}
]
}
],
"object" : "interaction" ,
"model" : "gemini-3.1-flash-image" ,
}
Когда модель генерирует изображение, она возвращает данные изображения, закодированные в base64, на шаге внутри массива steps , а также через удобное свойство output_image . Ознакомьтесь с руководством по генерации изображений , чтобы узнать о соотношении сторон, редактировании изображений и ссылках.
record_voice_over
Генерация речи
Создавайте выразительную речь для нескольких говорящих с помощью Gemini 3.1 Flash TTS.
music_note Музыкальное поколение
Создавайте клипы и полные версии песен с помощью Lyria 3.
7. Используйте структурированный вывод. Настройте модель так, чтобы она возвращала JSON, соответствующий определенной вами схеме. Структурированный вывод работает с Pydantic (Python) и Zod (JavaScript).
Python
from google import genai
from pydantic import BaseModel , Field
from typing import List , Optional
class Recipe ( BaseModel ):
recipe_name : str = Field ( description = "Name of the recipe." )
ingredients : List [ str ] = Field ( description = "List of ingredients." )
prep_time_minutes : Optional [ int ] = Field ( description = "Prep time in minutes." )
client = genai . Client ()
interaction = client . interactions . create (
model = "gemini-3.5-flash" ,
input = "Give me a recipe for banana bread" ,
response_format = {
"type" : "text" ,
"mime_type" : "application/json" ,
"schema" : Recipe . model_json_schema ()
},
)
recipe = Recipe . model_validate_json ( interaction . output_text )
print ( recipe )
JavaScript
import { GoogleGenAI } from "@google/genai" ;
import * as z from "zod" ;
const ai = new GoogleGenAI ({});
const recipeJsonSchema = {
type : "object" ,
properties : {
recipe_name : { type : "string" , description : "Name of the recipe." },
ingredients : {
type : "array" ,
items : { type : "string" },
description : "List of ingredients."
},
prep_time_minutes : {
type : "integer" ,
description : "Prep time in minutes."
}
},
required : [ "recipe_name" , "ingredients" ]
};
const recipeSchema = z . fromJSONSchema ( recipeJsonSchema );
const interaction = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
input : "Give me a recipe for banana bread" ,
response_format : {
type : "text" ,
mime_type : "application/json" ,
schema : recipeJsonSchema
},
});
const recipe = recipeSchema . parse ( JSON . parse ( interaction . output_text ));
console . log ( recipe );
ОТДЫХ
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"input": "Give me a recipe for banana bread",
"response_format": {
"type": "text",
"mime_type": "application/json",
"schema": {
"type": "object",
"properties": {
"recipe_name": { "type": "string", "description": "Name of the recipe." },
"ingredients": {
"type": "array",
"items": { "type": "string" },
"description": "List of ingredients."
},
"prep_time_minutes": {
"type": "integer",
"description": "Prep time in minutes."
}
},
"required": ["recipe_name", "ingredients"]
}
}
}'
Ответ:
{
"id" : "v1_Chd..." ,
"status" : "completed" ,
"steps" : [
{
"type" : "model_output" ,
"content" : [
{
"type" : "text" ,
"text" : "{\n \"recipe_name\": \"Classic Banana Bread\",\n \"ingredients\": [\n \"3 ripe bananas, mashed\",\n \"1/3 cup melted butter\",\n \"3/4 cup sugar\",\n \"1 egg, beaten\",\n \"1 teaspoon vanilla extract\",\n \"1 teaspoon baking soda\",\n \"Pinch of salt\",\n \"1.5 cups all-purpose flour\"\n ],\n \"prep_time_minutes\": 15\n}"
}
]
}
],
"object" : "interaction" ,
"model" : "gemini-3.5-flash" ,
}
Выходной текстовый блок содержит допустимую строку JSON, точно соответствующую запрошенной схеме. Чтобы узнать, как определять более сложные структуры и рекурсивные схемы, см. руководство по структурированному выводу .
Обогащайте ответы модели информацией в реальном времени, используя поиск Google. API автоматически выполняет поиск, обрабатывает результаты и возвращает ссылки на источники.
Python
from google import genai
client = genai . Client ()
interaction = client . interactions . create (
model = "gemini-3.5-flash" ,
input = "Who won the euro 2024?" ,
tools = [{ "type" : "google_search" }]
)
print ( interaction . output_text )
# Print citations
for step in interaction . steps :
if step . type == "model_output" :
for content_block in step . content :
if content_block . type == "text" and content_block . annotations :
print ( " \n Citations:" )
for annotation in content_block . annotations :
if annotation . type == "url_citation" :
print ( f " [ { annotation . title } ]( { annotation . url } )" )
JavaScript
import { GoogleGenAI } from "@google/genai" ;
const ai = new GoogleGenAI ({});
const interaction = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
input : "Who won the euro 2024?" ,
tools : [{ type : "google_search" }]
});
console . log ( interaction . output_text );
// Print citations
for ( const step of interaction . steps ) {
if ( step . type === "model_output" ) {
for ( const contentBlock of step . content ) {
if ( contentBlock . type === "text" && contentBlock . annotations ) {
console . log ( "\nCitations:" );
for ( const annotation of contentBlock . annotations ) {
if ( annotation . type === "url_citation" ) {
console . log ( ` [ ${ annotation . title } ]( ${ annotation . url } )` );
}
}
}
}
}
}
ОТДЫХ
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"input": "Who won the euro 2024?",
"tools": [{"type": "google_search"}]
}'
Ответ:
{
"id" : "v1_Chd..." ,
"status" : "completed" ,
"steps" : [
{
"type" : "thought" ,
"signature" : "EvEFCu4F..."
},
{
"type" : "google_search_call" ,
"arguments" : {
"queries" : [ "UEFA Euro 2024 winner" ]
}
},
{
"type" : "google_search_result" ,
"call_id" : "search_001" ,
"result" : [
{
"search_suggestions" : "<!-- HTML and CSS search widget -->"
}
]
},
{
"type" : "model_output" ,
"content" : [
{
"type" : "text" ,
"text" : "Spain won Euro 2024, defeating England 2-1 in the final." ,
"annotations" : [
{
"type" : "url_citation" ,
"url" : "https://www.uefa.com/euro2024" ,
"title" : "uefa.com" ,
"start_index" : 0 ,
"end_index" : 56
}
]
}
]
}
],
"object" : "interaction" ,
"model" : "gemini-3.5-flash" ,
}
Этапы поиска подробно описаны в истории взаимодействия, а итоговый результат включает в себя встроенные ссылки на веб-источники.
Вы можете узнать, как извлекать ссылки из поисковых запросов, в руководстве по основам поиска Google , или посмотреть, как комбинировать несколько инструментов, в руководстве по сочетанию инструментов .
code
Выполнение кода
Запускайте код Python в защищенной изолированной среде Borg.
link контекст URL
Передавайте общедоступные веб-адреса непосредственно в ответы на запросы, содержащиеся в содержимом веб-страницы.
search Поиск файлов
Индексирование и поиск по загруженным документам и медиафайлам.
map Google Карты
Реакции грунта в реальных геопространственных и геолокационных данных.
computer Использование компьютера
Автоматизация браузера и взаимодействие с экраном.
9. Вызывайте собственные функции. Вызов функции позволяет связать модель с вашим кодом. Вы объявляете имя функции и параметры, модель решает, когда ее вызвать, и возвращает структурированные аргументы, а вы выполняете ее локально и отправляете результат обратно.
С сохранением состояния (рекомендуется) Python
import json
from google import genai
client = genai . Client ()
weather_tool = {
"type" : "function" ,
"name" : "get_current_temperature" ,
"description" : "Gets the current temperature for a given location." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"location" : {
"type" : "string" ,
"description" : "The city name, e.g. San Francisco" ,
},
},
"required" : [ "location" ],
},
}
available_functions = {
"get_current_temperature" : lambda location : {
"location" : location , "temperature" : "22" , "unit" : "celsius"
},
}
user_input = "What is the temperature in London?"
previous_id = None
while True :
interaction = client . interactions . create (
model = "gemini-3.5-flash" ,
input = user_input ,
tools = [ weather_tool ],
previous_interaction_id = previous_id ,
)
function_results = []
for step in interaction . steps :
if step . type == "function_call" :
result = available_functions [ step . name ]( ** step . arguments )
print ( f "Called { step . name } ( { step . arguments } ) → { result } " )
function_results . append ({
"type" : "function_result" ,
"name" : step . name ,
"call_id" : step . id ,
"result" : [{ "type" : "text" , "text" : json . dumps ( result )}],
})
if not function_results :
break
user_input = function_results
previous_id = interaction . id
print ( interaction . output_text )
JavaScript
import { GoogleGenAI } from "@google/genai" ;
const ai = new GoogleGenAI ({});
const weatherTool = {
type : "function" ,
name : "get_current_temperature" ,
description : "Gets the current temperature for a given location." ,
parameters : {
type : "object" ,
properties : {
location : {
type : "string" ,
description : "The city name, e.g. San Francisco" ,
},
},
required : [ "location" ],
},
};
const availableFunctions = {
get_current_temperature : ({ location }) = > ({
location , temperature : "22" , unit : "celsius"
}),
};
let input = "What is the temperature in London?" ;
let previousId = null ;
let interaction ;
while ( true ) {
interaction = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
input ,
tools : [ weatherTool ],
previous_interaction_id : previousId ,
});
const functionResults = [];
for ( const step of interaction . steps ) {
if ( step . type === "function_call" ) {
const result = availableFunctions [ step . name ]( step . arguments );
console . log ( `Called ${ step . name } ( ${ JSON . stringify ( step . arguments ) } ) →` , result );
functionResults . push ({
type : "function_result" ,
name : step . name ,
call_id : step . id ,
result : [{ type : "text" , text : JSON . stringify ( result ) }],
});
}
}
if ( functionResults . length === 0 ) break ;
input = functionResults ;
previousId = interaction . id ;
}
console . log ( interaction . output_text );
ОТДЫХ
# Turn 1: Send prompt with function declaration
RESPONSE1 = $( curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"input": "What is the temperature in London?",
"tools": [{
"type": "function",
"name": "get_current_temperature",
"description": "Gets the current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city name"}
},
"required": ["location"]
}
}]
}' )
INTERACTION_ID = $( echo " $RESPONSE1 " | jq -r '.id' )
FC_NAME = $( echo " $RESPONSE1 " | jq -r '.steps[] | select(.type=="function_call") | .name' )
FC_ID = $( echo " $RESPONSE1 " | jq -r '.steps[] | select(.type=="function_call") | .id' )
echo "Function: $FC_NAME , Call ID: $FC_ID "
# Turn 2: Send function result back
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"previous_interaction_id": "' $INTERACTION_ID '",
"input": [{
"type": "function_result",
"name": "' $FC_NAME '",
"call_id": "' $FC_ID '",
"result": [{"type": "text", "text": "{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}"}]
}],
"tools": [{
"type": "function",
"name": "get_current_temperature",
"description": "Gets the current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city name"}
},
"required": ["location"]
}
}]
}'
Лица без гражданства Вы также можете использовать вызов функций в режиме без сохранения состояния, управляя историей разговора на стороне клиента и установив параметр store=false . В режиме без сохранения состояния необходимо передавать полную историю разговора в поле input каждого последующего запроса. Эта история должна включать:
Начальный этап user_input . Все шаги, сгенерированные моделью и возвращенные в первом раунде (включая шаги thought и function_call ), были получены в точности так, как были получены. Шаг function_result содержит результат выполнения вашей функции. Python
import json
from google import genai
client = genai . Client ()
weather_tool = {
"type" : "function" ,
"name" : "get_current_temperature" ,
"description" : "Gets the current temperature for a given location." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"location" : {
"type" : "string" ,
"description" : "The city name, e.g. San Francisco" ,
},
},
"required" : [ "location" ],
},
}
available_functions = {
"get_current_temperature" : lambda location : {
"location" : location , "temperature" : "22" , "unit" : "celsius"
},
}
history = [
{
"type" : "user_input" ,
"content" : [{ "type" : "text" , "text" : "What is the temperature in London?" }]
}
]
while True :
interaction = client . interactions . create (
model = "gemini-3.5-flash" ,
store = False ,
input = history ,
tools = [ weather_tool ],
)
function_results = []
for step in interaction . steps :
history . append ( step . model_dump ())
if step . type == "function_call" :
result = available_functions [ step . name ]( ** step . arguments )
print ( f "Called { step . name } ( { step . arguments } ) → { result } " )
fn_result = {
"type" : "function_result" ,
"name" : step . name ,
"call_id" : step . id ,
"result" : [{ "type" : "text" , "text" : json . dumps ( result )}],
}
function_results . append ( fn_result )
history . append ( fn_result )
if not function_results :
break
print ( interaction . output_text )
JavaScript
import { GoogleGenAI } from "@google/genai" ;
const ai = new GoogleGenAI ({});
const weatherTool = {
type : "function" ,
name : "get_current_temperature" ,
description : "Gets the current temperature for a given location." ,
parameters : {
type : "object" ,
properties : {
location : {
type : "string" ,
description : "The city name, e.g. San Francisco" ,
},
},
required : [ "location" ],
},
};
const availableFunctions = {
get_current_temperature : ({ location }) = > ({
location , temperature : "22" , unit : "celsius"
}),
};
const history = [
{
type : "user_input" ,
content : [{ type : "text" , text : "What is the temperature in London?" }]
}
];
let interaction ;
while ( true ) {
interaction = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
store : false ,
input : history ,
tools : [ weatherTool ],
});
const functionResults = [];
for ( const step of interaction . steps ) {
history . push ( step );
if ( step . type === "function_call" ) {
const result = availableFunctions [ step . name ]( step . arguments );
console . log ( `Called ${ step . name } ( ${ JSON . stringify ( step . arguments ) } ) →` , result );
const fnResult = {
type : "function_result" ,
name : step . name ,
call_id : step . id ,
result : [{ type : "text" , text : JSON . stringify ( result ) }],
};
functionResults . push ( fnResult );
history . push ( fnResult );
}
}
if ( functionResults . length === 0 ) break ;
}
console . log ( interaction . output_text );
ОТДЫХ
# Turn 1: Send request with tools and store: false
RESPONSE1 = $( curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"store": false,
"input": [
{
"type": "user_input",
"content": "What is the temperature in London?"
}
],
"tools": [{
"type": "function",
"name": "get_current_temperature",
"description": "Gets the current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city name"}
},
"required": ["location"]
}
}]
}' )
# Extract model steps (thought, function_call)
MODEL_STEPS = $( echo " $RESPONSE1 " | jq '.steps' )
FC_NAME = $( echo " $RESPONSE1 " | jq -r '.steps[] | select(.type=="function_call") | .name' )
FC_ID = $( echo " $RESPONSE1 " | jq -r '.steps[] | select(.type=="function_call") | .id' )
echo "Function: $FC_NAME , Call ID: $FC_ID "
# Assume local execution returns:
RESULT = "{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}"
# Reconstruct history for Turn 2
HISTORY = $( jq -n \
--argjson first_input '[{"type": "user_input", "content": "What is the temperature in London?"}]' \
--argjson model_steps " $MODEL_STEPS " \
--arg fc_name " $FC_NAME " \
--arg fc_id " $FC_ID " \
--arg result " $RESULT " \
'$first_input + $model_steps + [{"type": "function_result", "name": $fc_name, "call_id": $fc_id, "result": [{"type": "text", "text": $result}]}]' )
# Turn 2: Send the full history
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d "{
\"model\": \"gemini-3.5-flash\",
\"store\": false,
\"input\": $HISTORY ,
\"tools\": [{
\"type\": \"function\",
\"name\": \"get_current_temperature\",
\"description\": \"Gets the current temperature for a given location.\",
\"parameters\": {
\"type\": \"object\",
\"properties\": {
\"location\": {\"type\": \"string\", \"description\": \"The city name\"}
},
\"required\": [\"location\"]
}
}]
}"
Ответ:
В ходе первого хода модель возвращает ответ со статусом requires_action и шагом function_call :
{
"id" : "v1_Chd..." ,
"status" : "requires_action" ,
"steps" : [
{
"type" : "function_call" ,
"id" : "call_abc123" ,
"name" : "get_current_temperature" ,
"arguments" : {
"location" : "London"
}
}
],
"object" : "interaction" ,
"model" : "gemini-3.5-flash"
}
После того, как вы запустите функцию локально и отправите результат (шаг 2), возвращается итоговое завершенное взаимодействие:
{
"id" : "v1_Chd..." ,
"status" : "completed" ,
"steps" : [
{
"type" : "function_call" ,
"id" : "call_abc123" ,
"name" : "get_current_temperature" ,
"arguments" : {
"location" : "London"
}
},
{
"type" : "model_output" ,
"content" : [
{
"type" : "text" ,
"text" : "The temperature in London is currently 22°C."
}
]
}
],
"object" : "interaction" ,
"model" : "gemini-3.5-flash" ,
}
Для получения информации о расширенных функциях, таких как параллельный вызов функций или режимы выбора функций, см. руководство по вызову функций .
10. Запустите управляемый агент. Управляемые агенты работают в удаленной песочнице с доступом к таким инструментам, как выполнение кода и управление файлами. Передайте agent вместо model и установите environment="remote" .
Python
from google import genai
client = genai . Client ()
interaction = client . interactions . create (
agent = "antigravity-preview-05-2026" ,
input = "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents." ,
environment = "remote" ,
)
print ( f "Environment: { interaction . environment_id } " )
print ( interaction . output_text )
JavaScript
import { GoogleGenAI } from "@google/genai" ;
const ai = new GoogleGenAI ({});
const interaction = await ai . interactions . create ({
agent : "antigravity-preview-05-2026" ,
input : "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents." ,
environment : "remote" ,
});
console . log ( `Environment: ${ interaction . environment_id } ` );
console . log ( interaction . output_text );
ОТДЫХ
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"agent": "antigravity-preview-05-2026",
"input": "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
"environment": "remote"
}'
Вы также можете определять и сохранять пользовательских агентов с собственными инструкциями, навыками и источниками данных.
rocket_launch
Быстрый старт
Совершите свой первый звонок агенту, транслируйте ответы и создайте персонализированного агента.
smart_toy Антигравитационный агент
Возможности, инструменты, многомодальный ввод и ценообразование для агента по умолчанию.
experiment Агенты в AI Studio
Визуальная площадка для прототипирования агентов без написания кода.
11. Запуск задач в фоновом режиме. Установите background=True для асинхронного выполнения длительных задач. Для получения результатов используйте interactions.get() .
Python
import time
from google import genai
client = genai . Client ()
interaction = client . interactions . create (
model = "gemini-3.5-flash" ,
input = "Write a detailed analysis of the impact of artificial intelligence on modern healthcare." ,
background = True ,
)
print ( f "Started background task: { interaction . id } " )
print ( f "Status: { interaction . status } " )
# Poll for completion
while True :
result = client . interactions . get ( interaction . id )
print ( f "Status: { result . status } " )
if result . status == "completed" :
print ( f " \n Result: \n { result . output_text } " )
break
elif result . status == "failed" :
print ( f "Failed: { result . error } " )
break
time . sleep ( 5 )
JavaScript
import { GoogleGenAI } from "@google/genai" ;
const ai = new GoogleGenAI ({});
const interaction = await ai . interactions . create ({
model : "gemini-3.5-flash" ,
input : "Write a detailed analysis of the impact of artificial intelligence on modern healthcare." ,
background : true ,
});
console . log ( `Started background task: ${ interaction . id } ` );
console . log ( `Status: ${ interaction . status } ` );
// Poll for completion
while ( true ) {
const result = await ai . interactions . get ( interaction . id );
console . log ( `Status: ${ result . status } ` );
if ( result . status === "completed" ) {
console . log ( `\nResult:\n ${ result . output_text } ` );
break ;
} else if ( result . status === "failed" ) {
console . log ( `Failed: ${ result . error } ` );
break ;
}
await new Promise ( r = > setTimeout ( r , 5000 ));
}
ОТДЫХ
# Start a background task
RESPONSE = $( curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"input": "Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",
"background": true
}' )
INTERACTION_ID = $( echo " $RESPONSE " | jq -r '.id' )
echo "Started background task: $INTERACTION_ID "
# Poll for completion
while true; do
RESULT = $( curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/ $INTERACTION_ID " \
-H "x-goog-api-key: $GEMINI_API_KEY " \
-H "Api-Revision: 2026-05-20" )
STATUS = $( echo " $RESULT " | jq -r '.status' )
echo "Status: $STATUS "
if [ " $STATUS " = "completed" ] ; then
echo " $RESULT " | jq -r '.steps[] | select(.type=="model_output") | .content[] | select(.type=="text") | .text'
break
elif [ " $STATUS " = "failed" ] ; then
echo "Failed"
break
fi
sleep 5
done
Ответ:
Первоначальный ответ возвращается немедленно со статусом in_progress :
{
"id" : "v1_abc123" ,
"status" : "in_progress" ,
"object" : "interaction" ,
"model" : "gemini-3.5-flash"
}
После полного выполнения фоновой задачи проверка состояния взаимодействия возвращает следующий результат:
{
"id" : "v1_abc123" ,
"status" : "completed" ,
"steps" : [
{
"type" : "model_output" ,
"content" : [
{
"type" : "text" ,
"text" : "Artificial intelligence has transformed modern healthcare in several..."
}
]
}
],
"object" : "interaction" ,
"model" : "gemini-3.5-flash" ,
}
Подробнее о запуске моделей и агентов в асинхронном режиме можно прочитать в руководстве по фоновому выполнению .
Что дальше? Генерация текста : системные инструкции, конфигурация генерации и расширенные текстовые шаблоны. Создание изображений : соотношение сторон, редактирование изображений и стилистические ориентиры. Понимание изображений : классификация, обнаружение объектов и визуальные вопросы и ответы. Мышление : Используйте цепочку рассуждений для решения сложных задач. Вызов функций : параллельный, композиционный и ограниченный режимы работы функций. Поиск Google : обоснование, ссылки и подсказки для поиска. Управляемые агенты : Предварительно настроенные агенты с возможностью выполнения кода и управления файлами. Глубокое исследование : Автономное многоэтапное исследование с планированием и синтезом. Структурированный вывод : JSON-схемы, перечисления и определения рекурсивных типов.
Отправить отзыв