Gemini Interactions API previous_interaction_id Example

Last updated: 2026-05-20

A practical guide to using previous_interaction_id and environment state in Gemini Interactions API workflows.

Quick answer

Best for
The Interactions API matters because it gives developers a clearer way to model stateful Gemini and managed-agent work. The key implementation detail is storing the IDs returned by each request.
Start here
previous_interaction_id is for continuing the same logical conversation or task.
Main workflow
Send the first request and store the returned interaction ID.
Common mistake
If the interaction ID is missing, restart from a compact summary prompt.

Category

ai-coding

Guide Hub

ai-coding-workflows

Last updated

2026-05-20

Summary

The Interactions API matters because it gives developers a clearer way to model stateful Gemini and managed-agent work. The key implementation detail is storing the IDs returned by each request.

Key takeaways

  • previous_interaction_id is for continuing the same logical conversation or task.
  • environment state is separate from prompt history and matters for file or sandbox workflows.
  • Log IDs deliberately because losing them is the easiest way to lose continuity.

What previous_interaction_id does

  • It tells the API which prior interaction the next request should continue from.
  • It reduces the need to resend the entire prompt history for stateful workflows.
  • It should be treated as server-returned state, not as a user-facing session slug.

What environment state does

  • It can represent the sandbox or execution context used by an agent workflow.
  • It is important when generated files, command outputs, or project state should continue.
  • It should be stored separately from normal chat history.

How to store IDs safely

  • Store interaction IDs with the user action or background job that created them.
  • Store environment IDs only for workflows that need file or execution continuity.
  • Avoid exposing raw IDs in public logs or shareable URLs.

How to recover from missing state

  • If the interaction ID is missing, restart from a compact summary prompt.
  • If the environment ID is missing, ask the agent to recreate the last known artifact.
  • If both are missing, start a new task and keep better observability around returned IDs.

Detailed Notes

Additional implementation notes and source-backed context.

Example data model

For a small app, store interaction state separately from user-facing messages:

type GeminiJob = {
  id: string;
  userId: string;
  task: string;
  firstInteractionId: string | null;
  latestInteractionId: string | null;
  environmentId: string | null;
  status: "queued" | "running" | "done" | "failed";
  createdAt: string;
  updatedAt: string;
};

First request and follow-up request

const first = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: "Draft a migration plan from REST endpoints to typed SDK calls.",
});

await saveJobState({
  firstInteractionId: first.id,
  latestInteractionId: first.id,
});

const second = await ai.interactions.create({
  model: "gemini-3.5-flash",
  previous_interaction_id: first.id,
  input: "Turn that migration plan into a 10-step checklist.",
});

For Antigravity Agent work, keep the same pattern but include the agent and environment fields supported by the current docs.

Debugging state loss

If a follow-up call behaves like a fresh request, check these in order:

  1. The ID came from the previous API response.
  2. The previous interaction was created with the same account and project.
  3. The request used the correct field name and API revision.
  4. The interaction or environment has not expired.
  5. Your application did not overwrite latestInteractionId with a local job ID.

Comparison Table

Practical tradeoffs for this topic page, focused on workflow decisions.

State typeWhat it preservesCommon mistake
previous_interaction_idConversation or task continuityPassing a local request ID instead of the API response ID
environment IDSandbox, generated files, and execution state where supportedAssuming every model call has a persistent file environment
Application session IDYour own user or job stateConfusing app sessions with Gemini API interaction state

Practical Workflow

Stateful Interactions API workflow

  1. 1Send the first request and store the returned interaction ID.
  2. 2If the workflow uses an agent environment, store the returned environment ID as a separate field.
  3. 3Send the follow-up request with previous_interaction_id.
  4. 4Attach the environment identifier only when the same environment should continue.
  5. 5Persist final outputs and IDs in your application job log.

Step-by-Step Example

A concrete execution example you can adapt to your own workflow.

Example: Continue a generated project plan

A user asks for a migration plan, then asks the model or agent to convert it into a checklist.

  1. 1.Create the first interaction with the migration prompt.
  2. 2.Save interaction.id to your database or job memory.
  3. 3.Create a second interaction with previous_interaction_id and the checklist request.
  4. 4.Render the final checklist and store the two linked interaction IDs.

Expected outcome: The second request continues the original planning context without stuffing all prior text into a new prompt.

FAQ

Answers based on current implementation intent and source-backed workflow guidance.

Is previous_interaction_id the same as chat history?

No. It is an API-level reference to a previous interaction. Your application can still store its own chat history, summaries, and audit logs.

Do I always need an environment ID?

No. Environment state is most useful for agent workflows that create files, run commands, or keep sandbox state.

What happens if I lose the previous_interaction_id?

You usually need to restart from a summary of the task or from the saved final output. This is why ID logging matters from the first prototype.

Sources

Primary references used for topic evidence and workflow framing.

Google AI for Developersofficial-docs2026-05-20

Gemini API Interactions API

Official Gemini API documentation describes the Interactions API for stateful model and agent workflows, including continuation patterns for previous interactions and environments.

Google AI for Developersofficial-docs2026-05-20

Managed agents quickstart

Official Gemini API quickstart explains how to invoke managed agents, including Antigravity Agent preview workflows, through the Gemini API.

Google AI for Developersofficial-docs2026-05-20

Antigravity Agent

Official developer documentation describes Antigravity Agent as a managed agent for software engineering tasks inside Gemini API workflows.

Document your API state fields

Use the Markdown Previewer to draft a short implementation note for interaction IDs, environment IDs, and application job IDs.

Open Markdown Previewer