Package com.google.genai.gaos

Class Interactions

java.lang.Object
com.google.genai.gaos.Interactions
public class Interactions extends Object

  • Method Details

    • async

      public AsyncInteractions async()
      Switches to the async SDK.
      Returns:
      The async SDK

    • create

      public CreateInteractionRequestBuilder create()
      Creates a new interaction.
      Returns:
      The call builder

    • create

      public CreateInteractionResponse create(@Nonnull CreateInteractionRequestBody body)
      Creates a new interaction.
      Parameters:
      body - The request body.
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails

    • create

      public CreateInteractionResponse create(@Nonnull CreateInteractionRequestBody body, boolean automaticContinuation)
      Creates a new interaction.
      Parameters:
      body - The request body.
      automaticContinuation - Whether to automatically continue decoding across continuation hops; see create(CreateInteractionRequest, Options).
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails

    • create

      public CreateInteractionResponse create(@Nullable String apiVersion, @Nonnull CreateInteractionRequestBody body, @Nullable Options options)
      Creates a new interaction.
      Parameters:
      apiVersion - API version for request routing.
      body - The request body.
      options - additional options
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails

    • create

      public CreateInteractionResponse create(@Nonnull CreateInteractionRequest request)
      Creates a new interaction.
      Parameters:
      request - The request object containing all the parameters for the API call.
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails

    • create

      public CreateInteractionResponse create(@Nonnull CreateInteractionRequest request, @Nullable Options options)
      Creates a new interaction.

      Automatic continuation. request.automaticContinuation() defaults to true. When enabled, the SDK automatically resumes decoding across multiple continuation hops whenever a response or stream stops at the per-request decode token limit (status='requires_continuation' with a continuation_token) until the interaction completes, reaches incomplete (e.g. max_output_tokens), requires action, or fails. Pass automaticContinuation(false) to disable; the server response is then returned as-is (field for field, continuation fields included) so the caller can resume manually, and a one-time warning is logged if it stopped at requires_continuation.

      • For stream=true, events from all continuation hops are yielded sequentially on the returned CreateInteractionResponse.events() stream, verbatim: each hop's own interaction.created and interaction.completed (with status requires_continuation) are included, so check status on interaction.completed rather than treating the first one as the end.
      • For stream=false, each continuation hop is a separate interaction on the server that only contains that hop's output. The SDK merges the hops into one Interaction: steps are concatenated in hop order, usage token counts are summed across hops (with usage.initial_input_tokens set to the first hop's input tokens), and all other fields (id, status, ...) come from the final hop. The final hop's id can be passed as previous_interaction_id to continue the conversation. continuation_ids lists the ids of every hop in order (the last one is id); note that get(id) and delete(id) act on a single hop. previous_interaction_id, created and input come from the first hop.
      • With store=true (the default), each continuation hop sends the hop that issued the continuation_token as previous_interaction_id and omits input (the server already has it). With store=false, the original input is resent with the token.
      • Client-side continuation is skipped for background=true and agent interactions (agent / agent_config), whose loops are managed by the server. background=true with automaticContinuation(false) is rejected with an IllegalArgumentException before any request is sent.
      • Timeouts: request.timeout() is a wall-clock budget for the whole create() call. Once it runs out no further hop starts (and no further stream event is read) and the call stops with ContinuationInterruptedException (see Errors) so the work so far can be resumed. Per-request HTTP timeouts (e.g. HttpOptions.timeout on the client) and RetryConfig apply to each hop separately: transient errors on a continuation hop retry that hop using the latest continuation_token without restarting from the initial request.
      • Billing note: with background=false, each continuation hop re-prefills the conversation and generated prefix, so input tokens are billed on every hop (and summed in usage.total_input_tokens). If an unrecoverable error occurs after one or more hops have completed, those completed hops are still billed. For server-managed continuation without client-side hop loops, use background=true (with store=true).
      • Errors: a failure on the first request is thrown as usual. A failure after progress (a later hop, or a stream after a resumable checkpoint) throws ContinuationInterruptedException (with the failure as cause) carrying continuationToken, interactionId and continuationIds, plus partialInteraction (the completed hops merged, for stream=false), so the output already produced is not lost and the call can be resumed manually. Running out of the per-call timeout after progress is reported the same way.
      Parameters:
      request - The request object containing all the parameters for the API call.
      options - additional options
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails

    • delete

      public DeleteInteractionRequestBuilder delete()
      Deletes the interaction by id.
      Returns:
      The call builder

    • delete

      public DeleteInteractionResponse delete(@Nonnull String id)
      Deletes the interaction by id.
      Parameters:
      id - Required. The name of the interaction to delete.
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails

    • delete

      public DeleteInteractionResponse delete(@Nullable String apiVersion, @Nonnull String id, @Nullable Options options)
      Deletes the interaction by id.
      Parameters:
      apiVersion - API version for request routing.
      id - Required. The name of the interaction to delete.
      options - additional options
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails

    • get

      public GetInteractionByIdRequestBuilder get()
      Retrieves the full details of a single interaction based on its `Interaction.id`.
      Returns:
      The call builder

    • get

      public GetInteractionByIdResponse get(@Nonnull GetInteractionByIdRequest request)
      Retrieves the full details of a single interaction based on its `Interaction.id`.
      Parameters:
      request - The request object containing all the parameters for the API call.
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails

    • get

      public GetInteractionByIdResponse get(@Nonnull GetInteractionByIdRequest request, @Nullable Options options)
      Retrieves the full details of a single interaction based on its `Interaction.id`.
      Parameters:
      request - The request object containing all the parameters for the API call.
      options - additional options
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails

    • cancel

      public CancelInteractionByIdRequestBuilder cancel()
      Cancels an interaction by id. This only applies to background interactions that are still running.
      Returns:
      The call builder

    • cancel

      public CancelInteractionByIdResponse cancel(@Nonnull String id)
      Cancels an interaction by id. This only applies to background interactions that are still running.
      Parameters:
      id - Required. The name of the interaction to cancel.
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails

    • cancel

      public CancelInteractionByIdResponse cancel(@Nullable String apiVersion, @Nonnull String id, @Nullable Options options)
      Cancels an interaction by id. This only applies to background interactions that are still running.
      Parameters:
      apiVersion - API version for request routing.
      id - Required. The name of the interaction to cancel.
      options - additional options
      Returns:
      The response from the API call
      Throws:
      RuntimeException - subclass if the API call fails