Skip to content

Commit 0a6da26

Browse files
MarkDaoustcopybara-github
authored andcommitted
feat(interactions): add AutomaticContinuation to Interactions.Create in the Go SDK
Foreground `Interactions.Create()` calls are capped per request by the server (32k output tokens unary, 64k streaming) and stop with `status="requires_continuation"` plus a `continuation_token`. `Interactions.Create` now enables automatic continuation by default (configurable per call via `operations.WithAutomaticContinuation(bool)`) and chains continuation hops client-side so a plain `Create()` returns the full decode. Request chaining: - Each hop after the first sends the `continuation_token` from the previous hop. With `Store` enabled (default) it sets `PreviousInteractionID` to the hop that issued the token and omits `Input`; with `Store=false` it resends the original `Input`. - Unary foreground model calls default `GenerationConfig.MaxOutputTokens` to 65536 (`DefaultAutomaticContinuationMaxOutputTokens`) when unset without mutating caller structs (streaming uses the server's 64k default). Explicit values are never overridden. - Stops on `completed`, `incomplete` (token preserved for manual resumption), `requires_action`, `failed`, `cancelled`, a missing token, or a repeated token. Skipped for agent requests and `Background=true`; `Background=true` with `operations.WithAutomaticContinuation(false)` returns `ErrAutomaticContinuationWithBackground`. Unary (`Stream=false`) merging: - Hops are merged into one `Interaction`: `Steps` concatenated in hop order (leading `user_input` steps dropped on later hops), `Usage` counts and per-modality breakdowns summed across hops with `Usage.InitialInputTokens` taken from hop 1, `ID` / `Status` / `ContinuationToken` / `Updated` from the final hop, and `PreviousInteractionID` / `Created` / `Input` from hop 1. - `ContinuationIDs` lists every hop id in order, de-duplicated with any server-provided ids. Derived output properties (`OutputText`, etc.) are recomputed across hop boundaries. Streaming (`Stream=true`): - Events from all hops are yielded verbatim on `stream.EventStream[InteractionSSEEvent]`. Consumers should treat `interaction.completed` with `status="requires_continuation"` as intermediate. - Mid-hop transport drops or premature EOF resume from the latest `interaction.status_update` checkpoint token when no content was yielded since that checkpoint (up to `MaxStreamReconnectsWithoutProgress = 3` reconnects). SSE `error` events are terminal; HTTP status retries stay with SDK retry options. Timeouts and errors: - The `ctx` deadline/cancellation passed to `Create(ctx, ...)` bounds the whole call across hops, while `operations.WithOperationTimeout`, `WithTimeout`, and retry configs apply per hop. - A failure or `ctx` expiry after progress returns `*apierrors.ContinuationInterruptedError` (`Unwrap()` returning `Cause`) carrying `PartialInteraction`, `ContinuationToken`, `InteractionID`, and `ContinuationIDs` so billed work is preserved for manual resumption. First-hop failures return unchanged. Opt-out: - `operations.WithAutomaticContinuation(false)` returns the single server response untouched (no budget injection, no merging) and logs a one-time warning if it stops at `requires_continuation` without a caller-supplied `continuation_token`. Tests: `interactions/continuation_conformance_test.go` (52 conformance cases) and `interactions/continuation_test.go` (ctx deadline/cancellation, per-hop timeout, stream close, non-mutation, and option validation). PiperOrigin-RevId: 1009385691
1 parent 58187ad commit 0a6da26

8 files changed

Lines changed: 1742 additions & 6 deletions

File tree

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
// Copyright 2026 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
//go:build ignore_vet
16+
17+
// Automatic continuation: a long unary decode is transparently continued
18+
// across several server requests ("hops") and merged into one Interaction.
19+
package main
20+
21+
import (
22+
"context"
23+
"errors"
24+
"fmt"
25+
"log"
26+
"os"
27+
28+
"google.golang.org/genai"
29+
"google.golang.org/genai/interactions/models/apierrors"
30+
gaos_interactions "google.golang.org/genai/interactions/models/interactions"
31+
"google.golang.org/genai/interactions/models/operations"
32+
)
33+
34+
func main() {
35+
ctx := context.Background()
36+
client, err := genai.NewClient(ctx, nil)
37+
if err != nil {
38+
log.Fatal(err)
39+
}
40+
41+
if os.Getenv("GOOGLE_GENAI_USE_VERTEXAI") == "true" {
42+
fmt.Println("Interactions API is not yet supported on Vertex AI")
43+
return
44+
}
45+
46+
fmt.Println("Using Gemini Developer API")
47+
48+
body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
49+
Model: gaos_interactions.Model("gemini-flash-latest"),
50+
Input: genai.Ptr(gaos_interactions.NewInteractionsInput(
51+
"Write a very long, detailed story about a lighthouse keeper.")),
52+
})
53+
54+
// Automatic continuation is on by default: if the model stops at the
55+
// per-request decode limit (status requires_continuation), the SDK sends
56+
// further requests and merges the hops.
57+
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})
58+
if err != nil {
59+
// A failure after some hops completed keeps the work done so far.
60+
var interrupted *apierrors.ContinuationInterruptedError
61+
if errors.As(err, &interrupted) {
62+
fmt.Printf("Interrupted after %d hop(s): %v\n", len(interrupted.ContinuationIDs), interrupted.Cause)
63+
if interrupted.PartialInteraction != nil && interrupted.PartialInteraction.OutputText != nil {
64+
fmt.Printf("Partial output: %s\n", *interrupted.PartialInteraction.OutputText)
65+
}
66+
// Resume manually: continuation_token + previous_interaction_id
67+
// (store=true) and no input.
68+
fmt.Printf("Resume with continuation_token=%q previous_interaction_id=%q\n",
69+
interrupted.ContinuationToken, interrupted.InteractionID)
70+
return
71+
}
72+
log.Fatal(err)
73+
}
74+
75+
interaction := res.Interaction
76+
fmt.Printf("Status: %s\n", interaction.Status)
77+
// Every hop's id, in order; the last one is interaction.ID and can be used
78+
// as previous_interaction_id for the next turn.
79+
fmt.Printf("Hops: %v\n", interaction.ContinuationIds)
80+
if interaction.Usage != nil && interaction.Usage.TotalOutputTokens != nil {
81+
fmt.Printf("Output tokens (summed across hops): %d\n", *interaction.Usage.TotalOutputTokens)
82+
}
83+
if interaction.OutputText != nil {
84+
fmt.Printf("Output: %s\n", *interaction.OutputText)
85+
}
86+
87+
// Opting out returns the first server response as-is; if it stopped at
88+
// requires_continuation, continue it yourself with its continuation_token.
89+
raw, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body},
90+
operations.WithAutomaticContinuation(false))
91+
if err != nil {
92+
log.Fatal(err)
93+
}
94+
fmt.Printf("Without automatic continuation: status=%s continuation_token set=%v\n",
95+
raw.Interaction.Status, raw.Interaction.ContinuationToken != nil)
96+
}

0 commit comments

Comments
 (0)