1. Добро пожаловать, разработчик Gemini!

В этой практической работе вы узнаете, как создавать приложения с ИИ нового поколения на Java с помощью Gemini Interactions SDK.
Что такое Gemini Interactions API?
Традиционные API больших языковых моделей не сохраняют состояние и работают по принципу "запрос – ответ". Чтобы создать многоэтапного чат-помощника или сложный цикл агента, разработчикам приходилось управлять состоянием разговора, усечением истории, оркестрацией вызовов инструментов и циклами выполнения полностью в коде клиентского приложения.
Gemini Interactions API переносит эту сложность на сервер. Это API с сохранением состояния на основе сеансов, в котором инфраструктура Google размещает граф разговора и управляет им. Один объект Interaction представляет сеанс с сохранением состояния. При взаимодействии с ним API возвращает подробную структурированную хронологию, состоящую из полиморфных шагов, таких как:
ThoughtStep– внутренний процесс рассуждения модели.ModelOutputStep: текстовый, аудио- или графический контент, сгенерированный моделью.ToolCallStepиToolResultStep– вызовы инструментов, инициированные системой или моделью.UserInteractionStep– точки, в которых система приостанавливает работу, чтобы запросить ввод или одобрение человека.
Что такое управляемые агенты?
Управление автономными агентами, включая циклы, логику повторных попыток, среды выполнения инструментов и управление состоянием, – это сложная задача.
Управляемые агенты – это решение на уровне платформы, предоставляемое Gemini Interactions API. Вместо того чтобы запускать циклы агентов локально, вы можете развернуть специализированных агентов непосредственно в инфраструктуре Google:
- Встроенные агенты. Готовые к использованию специализированные агенты, такие как агент Deep Research, который выполняет многоэтапный поиск в интернете, агрегирует результаты и создает подробные отчеты.
- Специальные управляемые агенты. Автономные сущности, которые вы определяете. Вы предоставляете системные инструкции, подключаете инструменты (например, Google Поиск или среду выполнения Bash) и настраиваете Cloud Sandbox – безопасную изолированную контейнеризированную среду выполнения с настраиваемыми правилами исходящего трафика (например, разрешающими доступ только к определенным доменам, таким как GitHub).
С помощью Gemini Interactions Java SDK вы можете легко запускать управляемых агентов, координировать их работу и взаимодействовать с ними в стандартных приложениях Java.
Что вы узнаете
- Как ориентироваться в новой полиморфной архитектуре на основе
Step. - Как транслировать выразительную речь, синтезированную из текста (TTS), напрямую в колонки.
- Как генерировать музыку (MP3 + текст) с помощью Lyria.
- Как создавать визуальные заметки с помощью Gemini 3 Pro Image.
- Как управлять агентом Deep Research с помощью совместного планирования.
- Как настроить специального агента с правилами исходящего трафика и инструментами.
Что вам понадобится
- Java 21 или более поздней версии.
- Apache Maven.
- Текстовый редактор или интегрированная среда разработки (IntelliJ IDEA, VS Code и т. д.).
- Ключ Gemini API (из Google AI Studio).
2. Настройка: проект и ключ API
Создать проект Maven
Создайте новый проект Maven в терминале с помощью следующей команды:
mvn archetype:generate \
-DgroupId=com.example \
-DartifactId=gemini-interactions-demo \
-DarchetypeGroupId=org.apache.maven.archetypes \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DarchetypeVersion=1.5 \
-DinteractiveMode=false
Перейдите в каталог созданного проекта:
cd gemini-interactions-demo
Откройте файл pom.xml и настройте его:
- Обновите свойства версии Java, чтобы использовать Java 21:
<properties> <maven.compiler.source>21</maven.compiler.source> <maven.compiler.target>21</maven.compiler.target> </properties> - Добавьте зависимость SDK в блок
:<dependency> <groupId>io.github.glaforge</groupId> <artifactId>gemini-interactions-api-sdk</artifactId> <version>0.10.1</version> </dependency>
Настроить ключ API
Получите ключ Gemini API в Google AI Studio.
Установите ключ в качестве переменной среды в терминале:
macOS и Linux:
export GEMINI_API_KEY="your_actual_api_key"
Windows (командная строка):
set GEMINI_API_KEY="your_actual_api_key"
3. Hello World: навигация по архитектуре шагов
В Interactions API используется полиморфная пошаговая архитектура хронологии. Вместо простого списка выходных данных API возвращает последовательность типизированных объектов Step (например, ModelOutputStep, ThoughtStep, FunctionCallStep).
На этом шаге вы напишете простой запрос, чтобы понять, как извлечь из этой структуры окончательный результат работы модели.
Создать HelloInteractions.java
Создайте файл src/main/java/com/example/HelloInteractions.java со следующим содержимым:
package com.example;
import io.github.glaforge.gemini.interactions.GeminiInteractionsClient;
import io.github.glaforge.gemini.interactions.model.*;
import io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;
public class HelloInteractions {
public static void main(String[] args) {
// 1. Initialize the client
GeminiInteractionsClient client = GeminiInteractionsClient.builder()
.apiKey(System.getenv("GEMINI_API_KEY"))
.build();
// 2. Build the request
ModelInteractionParams request = ModelInteractionParams.builder()
.model("gemini-3.5-flash")
.input("Explain the difference between a library and a framework in one sentence.")
.build();
// 3. Send request
Interaction response = client.create(request);
// 4. Navigate the step-based architecture to get the output
response.steps().stream()
.filter(step -> step instanceof Step.ModelOutputStep)
.map(step -> (Step.ModelOutputStep) step)
.findFirst()
.ifPresent(step -> System.out.println(step.content().get(0)));
}
}
Выполните код
Скомпилируйте и запустите класс:
mvn compile exec:java -Dexec.mainClass=com.example.HelloInteractions
4. Управляемое аудио: потоковое выразительное озвучивание текста
В Gemini 3.1 Flash появился управляемый синтез речи. Вы можете управлять темпом, тоном и окружением голоса с помощью запросов, а также использовать теги эмоций (например, [excitedly] или [whispers]) в середине предложения.
На этом шаге вы сгенерируете выразительное аудио и передадите его непосредственно на динамики.
Создать StreamingDJ.java
Создайте файл src/main/java/com/example/StreamingDJ.java со следующим содержимым:
package com.example;
import io.github.glaforge.gemini.interactions.GeminiInteractionsClient;
import io.github.glaforge.gemini.interactions.model.*;
import io.github.glaforge.gemini.interactions.model.Config.SpeechConfig;
import io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;
import javax.sound.sampled.*;
import java.util.Base64;
import java.util.stream.Stream;
public class StreamingDJ {
public static void main(String[] args) throws Exception {
GeminiInteractionsClient client = GeminiInteractionsClient.builder()
.apiKey(System.getenv("GEMINI_API_KEY"))
.build();
// Prompt defining the voice profile and emotional tags
String prompt = """
# AUDIO PROFILE: Jaz R.
## THE SCENE: London Studio
### DIRECTOR'S NOTES
Accent: Jaz is a DJ from Brixton, London.
Style: Bouncy, energetic, high-speed delivery.
#### TRANSCRIPT
[excitedly] Yes, massive vibes in the studio!
[whispers] But keep it down, the boss is coming...
[shouting] Turn this up! Let's go!
""";
ModelInteractionParams request = ModelInteractionParams.builder()
.model("gemini-3.1-flash-tts-preview")
.input(prompt)
.responseModalities(Interaction.Modality.AUDIO)
.speechConfig(new SpeechConfig("Algenib", "en-GB"))
.stream(true) // Enable streaming
.build();
System.out.println("Streaming audio from Gemini...");
try (Stream<Events> eventStream = client.stream(request)) {
// Configure the Java Audio System for 24kHz Mono 16-bit PCM
AudioFormat format = new AudioFormat(24000, 16, 1, true, false);
DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
try (SourceDataLine line = (SourceDataLine) AudioSystem.getLine(info)) {
line.open(format);
line.start();
// Process the stream and play audio chunks as they arrive
eventStream.forEach(event -> {
if (event instanceof Events.StepDelta cd && cd.delta() instanceof Events.AudioDelta audioDelta) {
byte[] audioData = Base64.getDecoder().decode(audioDelta.data());
line.write(audioData, 0, audioData.length);
}
});
line.drain();
}
}
}
}
Выполните код
mvn compile exec:java -Dexec.mainClass=com.example.StreamingDJ
Прослушивание выходного сигнала
Вот пример аудио, которое вы услышите при запуске кода (используется голос Algenib с тегами эмоций):
5. Генератор музыки с Lyria 3
С помощью модели DeepMind Lyria 3 можно генерировать музыку и джинглы. Запросив два режима ответа (AUDIO и TEXT), вы можете получить как сгенерированное аудио (MP3), так и текст песни.
Создать MusicGenerator.java
Создайте файл src/main/java/com/example/MusicGenerator.java со следующим содержимым:
package com.example;
import io.github.glaforge.gemini.interactions.GeminiInteractionsClient;
import io.github.glaforge.gemini.interactions.model.*;
import io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;
import io.github.glaforge.gemini.interactions.model.Content.AudioContent;
import java.nio.file.Files;
import java.nio.file.Paths;
public class MusicGenerator {
public static void main(String[] args) throws Exception {
GeminiInteractionsClient client = GeminiInteractionsClient.builder()
.apiKey(System.getenv("GEMINI_API_KEY"))
.build();
ModelInteractionParams request = ModelInteractionParams.builder()
.model("models/lyria-3-clip-preview") // 30-second clip
.input("An uplifting rock song with acoustic guitars about coding in Java.")
.responseModalities(
Interaction.Modality.AUDIO,
Interaction.Modality.TEXT) // Request both MP3 and Lyrics
.build();
System.out.println("Generating music (this might take a moment)...");
Interaction response = client.create(request);
// 1. Print the lyrics (TEXT output)
System.out.println("\n--- Generated Lyrics ---");
response.steps().stream()
.filter(step -> step instanceof Step.ModelOutputStep)
.flatMap(step -> ((Step.ModelOutputStep) step).content().stream())
.filter(content -> content instanceof Content.TextContent)
.forEach(content -> System.out.println(((Content.TextContent) content).text()));
// 2. Save the MP3 (AUDIO output)
response.steps().stream()
.filter(step -> step instanceof Step.ModelOutputStep)
.flatMap(step -> ((Step.ModelOutputStep) step).content().stream())
.filter(content -> content instanceof AudioContent)
.map(content -> (AudioContent) content)
.findFirst()
.ifPresent(audio -> {
try {
Files.write(Paths.get("coding_song.mp3"), audio.data());
System.out.println("\nSuccess: Song saved to coding_song.mp3");
} catch (Exception e) {
e.printStackTrace();
}
});
}
}
Выполните код
mvn compile exec:java -Dexec.mainClass=com.example.MusicGenerator
Послушайте сгенерированный трек
Вот сгенерированный MP3-файл (coding_song.mp3) с музыкой и текстом:
6. Визуализация с помощью Sketchnotes (Nano Banana Pro)
Gemini 3 Pro Image (также известная как Nano Banana Pro) может генерировать изображения. Запросив модальность IMAGE, вы можете генерировать инфографику, диаграммы или скетчи на основе текстовых запросов.
На этом шаге вы создадите краткий пересказ статьи об управляемых агентах в виде скетчноута и сохраните его в формате PNG.
Создать ImageGenerator.java
Создайте файл src/main/java/com/example/ImageGenerator.java со следующим содержимым:
package com.example;
import io.github.glaforge.gemini.interactions.GeminiInteractionsClient;
import io.github.glaforge.gemini.interactions.model.*;
import io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;
import io.github.glaforge.gemini.interactions.model.Content.ImageContent;
import java.nio.file.Files;
import java.nio.file.Paths;
public class ImageGenerator {
public static void main(String[] args) throws Exception {
GeminiInteractionsClient client = GeminiInteractionsClient.builder()
.apiKey(System.getenv("GEMINI_API_KEY"))
.build();
String articleSummary = """
Managed Agents in the Gemini API allow developers to run autonomous agents
that reason, plan, use tools, and execute code inside isolated cloud sandboxes.
The Gemini API handles the infrastructure (containers, network, runtime).
It is powered by the Antigravity agent running on Gemini 3.5 Flash.
The Java Interactions SDK supports these capabilities, utilizing a Step-based
architecture to model the execution timeline.
""";
ModelInteractionParams request = ModelInteractionParams.builder()
.model("gemini-3-pro-image-preview")
.input(String.format("""
Create a hand-drawn and hand-written sketchnote
style summary infographic, with a pure white background,
about the following information:
%s
""", articleSummary))
.responseModalities(Interaction.Modality.IMAGE) // Request IMAGE modality
.build();
System.out.println("Generating sketchnote (this might take a moment)...");
Interaction response = client.create(request);
// Save the generated image
response.steps().stream()
.filter(step -> step instanceof Step.ModelOutputStep)
.flatMap(step -> ((Step.ModelOutputStep) step).content().stream())
.filter(content -> content instanceof ImageContent)
.map(content -> (ImageContent) content)
.findFirst()
.ifPresent(image -> {
try {
Files.write(Paths.get("sketchnote.png"), image.data());
System.out.println("Success: Sketchnote saved to sketchnote.png");
} catch (Exception e) {
e.printStackTrace();
}
});
}
}
Выполните код
mvn compile exec:java -Dexec.mainClass=com.example.ImageGenerator
Сгенерированная заметка
Вот скетч-заметка (sketchnote.png), созданная моделью:

7. Управление агентами: совместное глубокое исследование
Deep Research – это мощный агент, который может выполнять многоэтапные исследовательские задачи. Однако вместо того, чтобы сразу запустить исследование, вы можете использовать совместное планирование, чтобы проверить, изменить и скорректировать план исследования, прежде чем агент начнет собирать данные.
Вы реализуете многоэтапный диалог, в котором для уточнения плана используется одно и то же состояние на стороне сервера (previousInteractionId).
Создать CollaborativeResearch.java
Создайте файл src/main/java/com/example/CollaborativeResearch.java со следующим содержимым:
package com.example;
import io.github.glaforge.gemini.interactions.GeminiInteractionsClient;
import io.github.glaforge.gemini.interactions.model.*;
import io.github.glaforge.gemini.interactions.model.InteractionParams.AgentInteractionParams;
import io.github.glaforge.gemini.interactions.model.Config.DeepResearchAgentConfig;
import io.github.glaforge.gemini.interactions.model.Config.ThinkingSummaries;
import io.github.glaforge.gemini.interactions.model.Config.Visualization;
public class CollaborativeResearch {
public static void main(String[] args) throws Exception {
GeminiInteractionsClient client = GeminiInteractionsClient.builder()
.apiKey(System.getenv("GEMINI_API_KEY"))
.build();
String agentModel = "deep-research-preview-04-2026";
// --- Phase 1: Request a Plan ---
System.out.println("Phase 1: Requesting research plan...");
AgentInteractionParams planParams = AgentInteractionParams.builder()
.agent(agentModel)
.input("Research the latest generations of Google Cloud TPUs (TPU7x and the 8th generation TPU 8t and TPU 8i).")
.agentConfig(new DeepResearchAgentConfig(
"deep-research",
ThinkingSummaries.AUTO,
Visualization.AUTO,
true // TRUE enables collaborative planning
))
.background(true)
.store(true)
.build();
Interaction planInteraction = client.create(planParams);
planInteraction = waitForCompletion(client, planInteraction.id());
System.out.println("\n--- Proposed Plan ---");
printOutputText(planInteraction);
// --- Phase 2: Refine the Plan ---
System.out.println("\nPhase 2: Refining research plan...");
AgentInteractionParams refineParams = AgentInteractionParams.builder()
.agent(agentModel)
.input("Focus on comparing the architectural, performance, and scaling differences between the TPU7x generation and the two flavors of the eighth generation: TPU 8t (optimized for training at scale) and TPU 8i (optimized for low-latency reasoning and inference).")
.agentConfig(new DeepResearchAgentConfig(
"deep-research",
ThinkingSummaries.AUTO,
Visualization.AUTO,
true // Keep collaborative planning TRUE to iterate
))
.previousInteractionId(planInteraction.id()) // Resume session
.background(true)
.store(true)
.build();
Interaction refinedInteraction = client.create(refineParams);
refinedInteraction = waitForCompletion(client, refinedInteraction.id());
System.out.println("\n--- Refined Plan ---");
printOutputText(refinedInteraction);
// --- Phase 3: Approve and Execute ---
System.out.println("\nPhase 3: Approving plan and starting deep research (this will take a few minutes)...");
AgentInteractionParams executeParams = AgentInteractionParams.builder()
.agent(agentModel)
.input("Plan looks good, execute!")
.agentConfig(new DeepResearchAgentConfig(
"deep-research",
ThinkingSummaries.AUTO,
Visualization.AUTO,
false // FALSE approves the plan and executes the research
))
.previousInteractionId(refinedInteraction.id()) // Resume session
.background(true)
.store(true)
.build();
Interaction finalReport = client.create(executeParams);
finalReport = waitForCompletion(client, finalReport.id());
System.out.println("\n--- Final Research Report ---");
printOutputText(finalReport);
}
private static Interaction waitForCompletion(GeminiInteractionsClient client, String id) throws Exception {
Interaction interaction = client.get(id);
while (interaction.status() != Interaction.Status.COMPLETED && interaction.status() != Interaction.Status.FAILED) {
Thread.sleep(5000);
interaction = client.get(id);
}
if (interaction.status() == Interaction.Status.FAILED) {
throw new RuntimeException("Interaction failed. Status: " + interaction.status());
}
return interaction;
}
private static void printOutputText(Interaction interaction) {
interaction.steps().stream()
.filter(step -> step instanceof Step.ModelOutputStep)
.flatMap(step -> ((Step.ModelOutputStep) step).content().stream())
.filter(content -> content instanceof Content.TextContent)
.forEach(content -> System.out.println(((Content.TextContent) content).text()));
}
}
Выполните код
mvn compile exec:java -Dexec.mainClass=com.example.CollaborativeResearch
Выходные данные сгенерированного отчета
Агент Deep Research создаст подробный структурированный отчет. Полный отчет, созданный в результате выполнения примера, можно посмотреть здесь:
Просмотр сгенерированного отчета Deep Research (tpu_history_report.md)
8. Пользовательские агенты и облачные изолированные среды
Для сложных задач разработчиков можно использовать пользовательских агентов. Вы определяете их системные инструкции, оснащаете их инструментами (например, выполнение кода/Bash) и настраиваете их удаленную среду (например, правила исходящего трафика сети).
На этом этапе вы подготовите агента с безопасным доступом к интернету для github.com и поручите ему клонировать репозиторий и проанализировать его файлы конфигурации в облачной песочнице.
Создать GitHubAnalyzer.java
Создайте файл src/main/java/com/example/GitHubAnalyzer.java со следующим содержимым:
package com.example;
import io.github.glaforge.gemini.interactions.GeminiInteractionsClient;
import io.github.glaforge.gemini.interactions.model.*;
import io.github.glaforge.gemini.interactions.model.InteractionParams.AgentInteractionParams;
import java.util.List;
public class GitHubAnalyzer {
public static void main(String[] args) throws Exception {
GeminiInteractionsClient client = GeminiInteractionsClient.builder()
.apiKey(System.getenv("GEMINI_API_KEY"))
.build();
String agentId = "github-analyzer-codelab";
// 1. Define the Custom Agent with Network Egress and Tools
Agent customAgent = Agent.builder()
.id(agentId)
.description("Clones and analyzes GitHub repos.")
.baseAgent("antigravity-preview-09-2026")
.baseEnvironment(new EnvironmentConfig(
new EnvironmentNetworkEgressAllowlist(List.of(
new AllowlistEntry("github.com") // Allow git clone over HTTPS
)),
List.of()
))
.systemInstruction("You are an architect. Clone the repo, inspect files, and write a summary.")
.tools(List.of(
new AgentTool.CodeExecution(), // Enables terminal bash execution in sandbox
new AgentTool.GoogleSearch()
))
.build();
// 2. Provision the Agent
System.out.println("Provisioning custom agent in the cloud...");
client.createAgent(customAgent);
try {
// 3. Start the Interaction
AgentInteractionParams params = AgentInteractionParams.builder()
.agent(agentId)
.input("Clone https://github.com/glaforge/gemini-interactions-api-sdk and explain its pom.xml structure.")
.environment("remote") // Crucial: Run in cloud sandbox
.build();
System.out.println("Starting clone and analysis (polling status)...");
Interaction interaction = client.create(params);
// 4. Poll for completion
while (interaction.status() != Interaction.Status.COMPLETED) {
System.out.println("Agent working... Status: " + interaction.status());
Thread.sleep(5000);
interaction = client.get(interaction.id());
}
// 5. Output the results
System.out.println("\n--- Architectural Analysis ---");
interaction.steps().stream()
.filter(step -> step instanceof Step.ModelOutputStep)
.flatMap(step -> ((Step.ModelOutputStep) step).content().stream())
.filter(content -> content instanceof Content.TextContent)
.forEach(content -> System.out.println(((Content.TextContent) content).text()));
} finally {
// 6. Clean up resources
client.deleteAgent(agentId);
System.out.println("\nCustom agent resource deleted from cloud.");
}
}
}
Выполните код
mvn compile exec:java -Dexec.mainClass=com.example.GitHubAnalyzer
Сгенерированные результаты анализа
Полный отчет об архитектурном анализе, созданный специальным агентом, можно посмотреть после клонирования репозитория здесь:
Просмотр выходных данных GitHub Analyzer (github_analysis_report.md)
9. Поздравляем!
Вы завершили практическую работу и узнали, как создавать сложные мультимодальные агентные рабочие процессы на Java с помощью Gemini Interactions SDK.
Чего вы достигли:
- Использование пошаговой архитектуры. Использовал новую полиморфную пошаговую архитектуру для запроса стандартных моделей.
- Потоковое выразительное озвучивание текста. Использовались примечания режиссера и встроенные теги эмоций для потоковой передачи аудио в реальном времени.
- Сгенерированная музыка. MP3-треки и тексты песен, созданные с помощью Lyria 3.
- Сгенерированные скетчи. Создавайте визуальные сводки с помощью Gemini 3 Pro Image (Nano Banana Pro).
- Управляемый Deep Research. Использование совместного планирования для уточнения планов исследований.
- Предоставленные настраиваемые агенты. Создавайте изолированные среды с настраиваемым управлением исходящим трафиком для безопасного выполнения кода.
Подробные сведения:
- Изучите исходный код SDK и другие тестовые сценарии на GitHub: glaforge/gemini-interactions-api-sdk.
- Подробнее о шаблонах проектирования агентов читайте в блоге Гийома: glaforge.dev.