Release v2.0.0

Gemini Interactions API SDK v2.0.0

Important

Please upgrade directly to v2.0.1!
Version 2.0.0 contained untyped Object return types (such as Trigger.interaction(), Interaction.Turn.content(), InteractionParams.Request.input(), and AgentInteractionParams.environment()) which were properly refactored to type-safe union records (TriggerInteraction, TurnContent, InteractionInput, and BaseEnvironment) in 2.0.1. To avoid unnecessary code churn, we strongly recommend adopting 2.0.1 directly.

A major milestone release aligning the SDK with the latest Google Gemini Interactions API OpenAPI contract and the official Google GenAI Java SDK.

---

⚠️ Breaking Changes & Migration Guide

1. GenerationConfig.toolChoice() returns ToolChoiceConfiguration

• What changed: In io.github.glaforge.gemini.interactions.model.Config.GenerationConfig, the record component toolChoice was changed from Tool.ToolChoiceConfig to ToolChoiceConfiguration to support both preset modes ("auto", "any", "none", "validated") and detailed tool choice configs.
• Migration:
  • If calling generationConfig.toolChoice(), update variable types to ToolChoiceConfiguration.
  • If you need the unwrapped Tool.ToolChoiceConfig, use the new backward-compatible accessor generationConfig.toolChoiceConfig().
  • Builders (GenerationConfig.builder().toolChoice(...)) continue to accept String, Tool.ToolChoiceConfig, and ToolChoiceConfiguration.

2. Trigger.interaction() returns Object (superseded in 2.0.1)

• What changed: In io.github.glaforge.gemini.interactions.model.Trigger, the record component interaction was generalized from InteractionParams.Request to Object. (Note: In 2.0.1, this returns type-safe TriggerInteraction).
• Migration:
  • To inspect the interaction as a request parameter: use trigger.interactionAsRequest().
  • To inspect the interaction as an interaction resource: use trigger.interactionAsInteraction().

3. Record Canonical Constructor Signatures Expanded

• What changed: As part of adding new properties, the canonical constructors of several immutable Java records were expanded:
  • EnvironmentConfig: added environmentId and env.
  • Trigger: added consecutiveFailureCount, lastPauseTime, lastResumeTime, and lastRunTime.
  • Tool.McpServer: added credential.
  • Config.VideoResponseFormat: added aspectRatio, delivery, and duration.
• Migration: Overloaded constructors and fluent builders (.builder()) matching previous signatures are provided. If your code was using record pattern matching/deconstruction or reflection against canonical constructors, update the parameter patterns.

4. Sealed Interface Permitted Subtypes (switch exhaustiveness)

• What changed: Added resilient fallback implementations to sealed interfaces:
  • Tool.UnknownTool added to Tool.
  • Content.UnknownContent added to Content.
  • Step.UnknownStep added to Step.
• Migration: In Java 17/21, exhaustive pattern matching switch expressions/statements over Tool, Content, or Step require a default or fallback branch to compile.

5. Interaction.Status.isFinished() includes INCOMPLETE and BUDGET_EXCEEDED

• What changed: Interaction.Status.isFinished() now returns true for terminal states INCOMPLETE (agent reached max token budget limit) and BUDGET_EXCEEDED in addition to COMPLETED, FAILED, and CANCELLED.
• Migration: To check if an interaction completed successfully without interruption, check status.isCompleted(). To detect token exhaustion, check status.isIncomplete().

---

🚀 Key Features & Enhancements

🔐 Server-Managed Credentials (Provisioning, Injection & Rotation)

Securely provision API keys, OAuth tokens, and environment variables into agent environments and tools without exposing secrets in client code or model context:

• Full CRUD on GeminiInteractionsClient:
  • createCredential(Credential)
  • getCredential(id)
  • listCredentials(pageSize, pageToken)
  • updateCredential(id, CredentialUpdate)
  • deleteCredential(id)
• Support for BearerTokenConfig, OAuth2Config, and EnvironmentVariableConfig.
• Reference credentials in MCP servers via Tool.McpServer.builder().credential("cred-id").
• Reference credentials in container sandboxes via EnvironmentConfig.builder().envCredential("SECRET_ENV", "cred-id").

📁 Direct Sandbox File & Archive Operations

Inspect, transfer, and upload files dynamically into running agent sandbox environments:

• Direct file streaming: client.downloadEnvironmentFile(...)
• Direct byte download: client.downloadEnvironmentFileBytes(...)
• Recursive directory TAR streaming: client.downloadEnvironmentFile(envId, path, true, targetPath)
• File & archive uploading: client.uploadEnvironmentFile(...) and client.uploadEnvironmentArchive(...)
• Snapshot download: client.downloadEnvironment(...)
• Batch local workspace extraction: EnvironmentWorkspace.extractAll(Path targetDirectory)

⏰ Trigger Scheduling & Automation Controls

Comprehensive lifecycle operations for background agent triggers:

• pauseTrigger(id) & resumeTrigger(id)
• runTrigger(id) for immediate manual execution (returns TriggerExecution)
• listTriggers(filter, pageSize, pageToken)
• listTriggerExecutions(triggerId)

🔄 In-Place Environment Credential & Network Refresh

Rotate authentication tokens or update outbound proxy egress rules on active container sandboxes without rebuilding or losing files:

AgentInteractionParams params = AgentInteractionParams.builder()
    .agent("antigravity-preview-09-2026")
    .input("Fetch the latest dataset.")
    .environment(EnvironmentConfig.forExisting(envId, refreshedAllowlist))
    .build();

🧠 Antigravity Agent & Models Parity

• Added constants for AgentOption.ANTIGRAVITY_PREVIEW_09_2026 and AgentOption.ANTIGRAVITY_PREVIEW_05_2026.
• Added models ModelOption.GEMINI_3_8_FLASH, ModelOption.GEMINI_3_5_FLASH_LITE, and ModelOption.ANTIGRAVITY_PREVIEW_09_2026.
• Added fluent AntigravityAgentConfig.Builder with model(...) and maxTotalTokens(...).
• Added cancelInteraction(id) convenience alias on GeminiInteractionsClient.
• Remote environment cloning via client.createEnvironmentFrom(sourceEnvironmentId).

🛡️ Forward-Compatible Polymorphic Deserialization

Jackson @JsonSubTypes now include defaultImpl fallback records (UnknownTool, UnknownContent, UnknownStep) capturing raw payload properties to safeguard against deserialization errors when new types are introduced by the API.

---

📦 Artifacts Published to Maven Central

• io.github.glaforge:gemini-interactions-parent:2.0.0
• io.github.glaforge:gemini-interactions-api-sdk:2.0.0
• io.github.glaforge:gemini-interactions-server:2.0.0