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

В этом практическом занятии вы научитесь создавать приложения искусственного интеллекта нового поколения на Java, используя собственный SDK Gemini Interactions .
Что такое API Gemini Interactions?
Традиционные API LLM не имеют состояния и работают по принципу запрос-ответ. Для создания многоходового чат-помощника или сложного агентного цикла разработчикам исторически приходилось управлять состоянием диалога, усечением истории, оркестровкой вызовов инструментов и циклами выполнения полностью в коде клиентского приложения.
API Gemini Interactions переносит эту сложность на сервер. Это API с сохранением состояния и управлением сессиями, где инфраструктура Google размещает и управляет графом диалогов. Отдельное взаимодействие представляет собой сессию с сохранением состояния. При взаимодействии с ним API возвращает подробную структурированную временную шкалу, состоящую из полиморфных шагов , таких как:
-
ThoughtStep: Внутренний процесс рассуждений модели. -
ModelOutputStep: Текстовый, аудио- или графический контент, сгенерированный моделью. -
ToolCallStepиToolResultStep: Вызовы инструментов, инициированные системой или моделью. -
UserInteractionStep: Точки, в которых система приостанавливает работу, чтобы запросить ввод данных или подтверждение от пользователя.
Что такое управляемые агенты?
Организация работы автономных агентов — обработка циклов, логика повторных попыток, среды выполнения инструментов и управление состоянием — является, как известно, чрезвычайно сложной задачей.
Управляемые агенты — это решение платформенного уровня, предоставляемое API Gemini Interactions. Вместо запуска циклов агентов локально, вы можете создавать специализированные агенты непосредственно в инфраструктуре Google:
- Встроенные агенты : готовые к использованию специализированные агенты, такие как агент «Глубокое исследование» , который выполняет многоэтапное веб-исследование, обобщает полученные данные и генерирует исчерпывающие отчеты.
- Пользовательские управляемые агенты : автономные сущности, которые вы определяете. Вы предоставляете системные инструкции, подключаете инструменты (например, поиск Google или среду выполнения Bash) и настраиваете облачную песочницу — безопасную, изолированную и контейнеризированную среду выполнения с настраиваемыми правилами исходящего сетевого трафика (например, разрешающими доступ только к определенным доменам, таким как GitHub).
Используя Java SDK Gemini Interactions, вы можете легко инициализировать, координировать и взаимодействовать с этими управляемыми агентами в стандартных Java-приложениях.
Что вы узнаете
- Как ориентироваться в новой полиморфной архитектуре на основе
Step. - Как передавать выразительный звук синтеза речи напрямую на динамики.
- Как создавать музыку (MP3 + текст) с помощью Lyria.
- Как создавать визуальные скетчноуты с помощью Gemini 3 Pro Image.
- Как управлять агентом Deep Research с помощью совместного планирования.
- Как настроить пользовательского агента с правилами и инструментами для обработки исходящего сетевого трафика.
Что вам понадобится
- Java 21 или выше.
- Apache Maven.
- Текстовый редактор или IDE (IntelliJ IDEA, VS Code и т. д.).
- Ключ API Gemini (из 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
Получите ключ API Gemini в 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: Освоение архитектуры Step
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 появилась управляемая функция преобразования текста в речь (TTS). Вы можете контролировать темп, тон и окружение голоса с помощью подсказок, а также использовать эмоциональные метки (например [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 ), содержащий музыку и текст песни:
Прослушайте сгенерированную музыкальную композицию (coding_song.mp3)
6. Визуализация с помощью скетчноутинга (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 создаст подробный структурированный отчет. Полный отчет, сгенерированный в ходе выполнения примера, можно посмотреть здесь:
Просмотрите сгенерированный подробный исследовательский отчет (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-05-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 с использованием SDK Gemini Interactions.
Чего вы достигли:
- Освоение архитектуры шагов : Использование новой полиморфной архитектуры шагов для запроса стандартных моделей.
- Streamed Expressive TTS : Использовались заметки режиссера и встроенные эмоциональные теги для потоковой передачи звука в реальном времени.
- Сгенерированная музыка : MP3-треки и тексты песен, сгенерированные с помощью Lyria 3.
- Созданные скетчноуты : визуальные резюме были созданы с помощью Gemini 3 Pro Image (Nano Banana Pro).
- Целенаправленное углубленное исследование : Использование совместного планирования для уточнения исследовательских планов.
- Настройка пользовательских агентов : Созданы изолированные среды с настраиваемым контролем исходящего сетевого трафика для безопасного выполнения кода.
Узнать больше:
- Изучите исходный код SDK и дополнительные тестовые примеры на GitHub: glaforge/gemini-interactions-api-sdk
- Подробнее о шаблонах проектирования агентного подхода можно прочитать в блоге Гийома: glaforge.dev