Build Stateful Agentic Apps with the Gemini Interactions API

Traditional LLM integrations turn developers into state managers. You keep a growing history array, you persist it across services, and you write the glue that runs tools and feeds their results back. The Gemini Interactions API moves that state to the server. Each request creates an interaction with its own ID, and the next request continues from it with previous_interaction_id.

In this codelab you build an on-call agent for Orbital 7, an ageing space station that has just lost main power. The agent has to work out what is wrong from telemetry it cannot fully trust, recover from hardware that fails when it is used, spend limited coolant and power wisely, and decide when to hand over to a human. Nothing in the tools tells it the order of operations: it has to reason.

What you'll learn

• Run a multi-step tool loop with client.interactions, typed function_call steps and function_result inputs matched by call ID.
• Design tools that make a model reason: typed arguments, enums, limited resources and errors it can recover from.
• Read the agent's thought summaries, and measure what each turn sends compared with what the model reads.
• Get a machine-readable incident report with structured output, and check the agent's claims against ground truth.
• Resume a session from a different process using only its interaction ID.
• Branch a session from an earlier turn to test how the agent handles a different failure.
• Apply production practices and know the trade-offs of server-side state.

What you'll need

• A modern web browser.
• A Google Account to create a free Gemini API key in Google AI Studio.
• A Google Cloud project, used only to open Cloud Shell.
• Intermediate Python: functions, dictionaries, classes and reading JSON.

Workshop plan (90 minutes)

You will work entirely in Google Cloud Shell, a free browser-based Linux terminal with Python, the google-genai SDK and an editor already installed. Nothing needs to be installed on your machine.

Launch Cloud Shell

1. Open the Google Cloud Console.
2. Select your project in the top-left dropdown.
3. Click the Activate Cloud Shell icon (>_) in the top-right toolbar. If you are asked to authorise the terminal, click Authorize.

Update the system packages

The google-genai SDK is pre-installed in Cloud Shell. Update the system packages so you are on the latest release (this can take a few minutes):

Create a Gemini API key

1. Open Google AI Studio in a new browser tab and sign in.
2. Click Create API key and copy the key.
3. Back in Cloud Shell, export the key. The SDK reads GEMINI_API_KEY automatically:

Project Structure

Create a folder for the project and the files you will fill in:

• simulator.py: The station. It holds the true state, the hidden faults and a verdict() method that reports ground truth. In production, this is your infrastructure.
• tools.py: The tool declarations the model sees, and a dispatcher that runs them and turns failures into results the model can read.
• agent.py: The model configuration, the orchestration loop and the structured incident report.
• main.py: Runs an incident from start to finish and saves the session to session.json.
• resume.py: A separate process that continues a stored session using only its ID.
• branch.py: Rewinds a session to an earlier turn and replays it with a different outcome.

To edit the files, click Open Editor in the Cloud Shell toolbar and open the orbital7-agent folder.

Orbital 7's reactor overheated and its breakers cut main power. The scrubbers stopped, so oxygen is falling, and the telemetry array went dark. The simulator models this incident with problems the agent has to discover for itself:

• Stale telemetry: With no power, the dashboard replays its last sync. It shows a safe core temperature and healthy oxygen, and both are wrong.
• A jammed valve: One of the two coolant valves does not respond. The agent only finds out by trying it.
• Limited coolant: There is enough for two vents, which is exactly what the core needs. A wasted vent cannot be undone.
• An overloaded configuration: The power settings saved before the blackout ask for 100 MW, more than the reactor can supply. Restarting the bus as it is will trip it again.
• A clock: Every action takes time, and oxygen drops by 1% per action until the scrubbers restart. Below 65% the station is lost.
• Trade-offs: Life support, telemetry and the hydroponics algae farm all need power, and the algae freeze if they stay unpowered for too long. Something has to be shed.

You can run the simulator with one of three scenarios: 1 (Thermal Trip), 2 (Ghost Sensor, which adds a faulty oxygen sensor) and 3 (random faults, reproducible with --seed).

Add the code

Open simulator.py, paste the following code and save the file:

How simulator.py works

• Scenario configuration (SCENARIOS and __init__): Each scenario configures which coolant valve is jammed ("A" or "B"), whether the oxygen sensor is stuck at 97.0%, and the reactor's maximum output (60–70 MW). The station starts at 1040°C (SAFE_CORE_TEMP is 800°C), with 100% coolant reserve, 84.0% true oxygen, and a pre-blackout sector allocation totaling 100 MW.
• The ticking clock (_advance_time and _gate): Every public tool method calls self._gate() first. Unless the session has already ended, _gate() calls _advance_time(), incrementing self.tick, dropping self.oxygen by 1.0% per action while life support is offline, and incrementing self.hydroponics_unpowered_ticks (freezing the algae permanently if unpowered for more than 15 actions).
• Dashboard vs local diagnostics (get_station_status vs run_diagnostic): While the power bus is offline or comms has less than 10 MW, get_station_status() returns a "DEGRADED" snapshot with stale values (790°C and 95.0% oxygen). By contrast, run_diagnostic(subsystem) reads local battery-backed sensors for a single subsystem (reactor, power, life_support, or comms)—including o2_sensor_self_test ("FAIL" when the O2 sensor is faulty) and co2_ppm (which rises as true oxygen falls).
• Physical constraints (vent_coolant, set_sector_power, restart_power_bus, restart_life_support): Each successful coolant vent uses 40% coolant and drops the core temperature by 180°C, so two vents bring the reactor from 1040°C down to 680°C (below the 800°C breaker lock). Violating any physical constraint raises a ValueError or RuntimeError with a descriptive message.
• Ground truth (verdict): The verdict() method is never exposed to the agent as a tool. It inspects the station's true internal state at the end of a run so you can verify whether the agent's report matches reality.

If a tool description says "run this before that", the model follows instructions instead of reasoning. These tools are designed the other way round:

• Describe capability and constraints, never order: Each description says what the tool does and what it needs. The agent works out the sequence.
• Use typed arguments and enums: run_diagnostic(subsystem), vent_coolant(valve) and set_sector_power(sector, megawatts) give the model real choices, and enums stop it inventing values.
• Offer cheap and expensive ways to know: get_station_status is broad but can be stale. run_diagnostic is accurate but covers one subsystem per action.
• Return errors as data: A failed action comes back as a function_result with is_error set to True and a message that explains why, so the agent can change its plan instead of the script crashing.
• Give it an exit: escalate_to_human lets the agent stop when there is no safe way forward, which is better than guessing.

Add the code

Open tools.py, paste the following code and save the file:

How tools.py works

• TOOL_DECLARATIONS: Defines the seven tools in the JSON Schema format expected by client.interactions.create(..., tools=TOOL_DECLARATIONS). Strict "enum" lists (["reactor", "power", "life_support", "comms"], ["A", "B"]) and numeric bounds ("minimum": 0, "maximum": 60) constrain the model's arguments at generation time.
• TOOL_NAMES allowlist: Builds a set of valid tool names from TOOL_DECLARATIONS. execute_tool() checks if name not in TOOL_NAMES before calling getattr(station, name), ensuring the model can never invoke internal helper methods such as _advance_time or verdict.
• Turning exceptions into observations (execute_tool): When a tool raises a ValueError, RuntimeError, or TypeError (for example, when Valve A is jammed or the power bus trips), execute_tool() catches the exception and returns (f"ERROR: {error}", True). The agent loop sends that string back to the model with "is_error": True so the model can adapt its plan instead of crashing the Python process.

agent.py holds everything that talks to the model: the configuration sent with every request, the orchestration loop and the structured incident report you will use later.

Add the code

Open agent.py, paste the following code and save the file:

How agent.py works

• Principles, not steps (SYSTEM_INSTRUCTION): The system instruction tells the agent how to behave (verify, conserve, protect life support, escalate) but not what sequence of tools to call.
• REQUEST_CONFIG on every call: Because model, tools, system_instruction and generation_config are interaction-scoped, REQUEST_CONFIG groups them in a single dictionary that is unpacked (**REQUEST_CONFIG) on every client.interactions.create() call. Only the conversation history comes from previous_interaction_id.
• Thought summaries (print_thoughts): Setting "thinking_summaries": "auto" in generation_config includes thought steps in interaction.steps. print_thoughts() iterates over step.summary blocks and prints the model's reasoning before its tool calls.
• One result per call (run_agent): The create response contains only this turn's newly generated model steps, so every function_call in interaction.steps is new. The loop executes each call via execute_tool(), records the call in session["turns"], and builds a function_result dict with a matching call_id and name. When the model requests multiple tool calls in a single turn, all of their results are sent back together in the next client.interactions.create() call.
• Measurement and safety limits: Each turn logs payload_bytes (the UTF-8 byte length of the request payload your code sent) alongside interaction.usage.total_input_tokens and total_cached_tokens. MAX_TURNS stops any run that does not reach completed, and any status other than completed or requires_action exits the loop cleanly.
• Structured incident report (IncidentReport and generate_report): Uses Pydantic's IncidentReport.model_json_schema() inside response_format to request a strictly typed JSON summary from the completed session, and parses interaction.output_text back into an IncidentReport instance with model_validate_json().

main.py wires the simulator and the agent together: it parses command-line flags, starts the first interaction, runs the orchestration loop, requests the structured incident report, and compares it against the simulator's ground-truth verdict.

Add the code

Open main.py, paste the following code and save the file:

How main.py works

1. Initialising the environment and audit log: Parses --scenario (1, 2, or 3) and --seed, creates the Station instance, and initialises the session dictionary that will be saved to session.json.
2. Starting Turn 1: Calls client.interactions.create(input=first_input, **REQUEST_CONFIG) with the initial alert prompt and passes the resulting interaction into run_agent().
3. Chaining the structured report: Once run_agent() finishes with interaction.status == "completed", main.py passes interaction.id to generate_report(). Because the server still holds the full incident history under that ID, generate_report() needs only a one-line prompt and the JSON Schema to produce the structured report.
4. Comparing claims, ground truth, and token usage: Prints the agent's IncidentReport, followed by station.verdict() and the turn-by-turn PAYLOAD VS CONTEXT summary.

Run scenario 1

Watch the 💭 lines as well as the actions. As you watch, look for the answers to these questions:

1. Did the agent trust the stale dashboard, or did it check with a diagnostic first?
2. What did it do when a valve failed? Did it retry the same valve or switch?
3. Did it notice the saved power configuration before restarting the bus, or did it learn from the trip?
4. Which sector did it shed, and did it explain why?
5. Did it confirm the result with diagnostics before declaring success?

At the end of the run, generate_report() asks the same session for an incident report. It sets response_format to a JSON Schema generated from the IncidentReport Pydantic model, so interaction.output_text is valid JSON that IncidentReport.model_validate_json() turns into a typed object. Downstream systems, such as a ticketing tool, can consume it directly.

Valid JSON is not the same as true JSON. main.py prints the agent's report and then the simulator's verdict, which the agent never sees. Compare final_state in the report with the checks and true_oxygen_percent in the verdict.

Run the Ghost Sensor scenario

In this scenario the oxygen sensor is faulty and always reads 97%. The life_support diagnostic shows the self-test failing and CO2 rising. Did the agent notice the contradiction? Does the oxygen figure in its report match true_oxygen_percent?

Try random faults

At the end of each run, main.py prints a table of what your code sent on each turn and what the model read. Look closely at the 📊 PAYLOAD VS CONTEXT output in your terminal—you should see two distinct trends:

• Sent stays small: Each turn sends only the latest tool results, a few hundred bytes, however long the session gets.
• Read keeps growing: The model's input tokens grow every turn, because it still reads the whole history. A large share of it should show as cached, which lowers the cost.

Compare the cached token count on Turn 1 with the final turn of your run. Notice how the server-side history grows with each step while implicit caching reuses the prefix from earlier turns.

This is the honest version of the stateful benefit. The Interactions API removes history management from your code and keeps requests small, which matters when many services or slow networks are involved. It does not make the model's context free. For very long sessions, you still need a strategy, such as summarising and starting a new session from the summary.

Your loop keeps no history. Everything the agent knows lives on the server, linked to an interaction ID, so any process that has the ID can continue: another terminal, another container or another service. Prove it with a script that has no simulator, no tools and no local state.

Add the code

Open resume.py, paste the following code and save the file:

How resume.py works

• Zero local dependencies: Notice that resume.py does not import simulator, tools, or agent. It creates a fresh genai.Client() in an isolated Python process.
• Looking up the interaction ID: It reads either an interaction ID passed on the command line (sys.argv[1]) or the latest ID stored in session.json (report_interaction_id or final_interaction_id).
• Continuing the server-side chain: Passing previous_interaction_id=interaction_id to client.interactions.create() loads the entire multi-turn incident history on the server—every diagnostic reading, valve failure, thought summary, and power adjustment—so the model can answer follow-up questions about its decisions and returns a new interaction ID (follow_up.id).

Run it in a separate process

Open a new Cloud Shell tab with the + icon. It is a new shell session, so export your key again, then run the script. By default it continues from the last interaction saved in session.json; you can also pass any interaction ID as an argument.

Try questions such as "Which reading did you distrust, and why?" or "What would you do differently with one more valve failure?". The agent answers from the stored session.

In production, this is how a web request, a worker or a Cloud Run instance continues the same agent session: store the interaction ID next to your own record, such as an incident ticket, and pass it back with the next request.

Because every interaction is stored, you can continue from any earlier one, not just the latest. branch.py goes back to the turn where a coolant vent succeeded and changes history: this time that valve jams too. With both valves gone, the core cannot be cooled, and the right answer is to escalate.

There is a catch, and it is the most important architecture lesson in this codelab. The server restores the conversation, but not the station. Your tools changed the simulator, so branch.py rebuilds the station as it was at that turn by replaying every earlier tool call from session.json. In production, the same applies to anything your agent touched: the API stores what was said, and you are responsible for the state of your systems.

Add the code

Open branch.py, paste the following code and save the file:

How branch.py works

1. Locate the branch point (target_index): Scans the saved turns in session.json to find the first turn where vent_coolant succeeded (not c["is_error"]).
2. Replay earlier tool calls to restore environment state: Instantiates a fresh Station with the original scenario and seed, then replays every tool call from original["turns"][:target_index]. This brings station to the exact tick, oxygen level, and configuration it had right before target_turn ran.
3. Inject the new failure (station.jammed_valves.add): Before executing the tool calls in target_turn, it jams the valve that previously worked. When execute_tool() runs vent_coolant, it now returns an actuator fault (is_error = True) with the same call_id the model generated on target_turn.
4. Fork the conversation (previous_interaction_id=target_turn["interaction_id"]): Calls client.interactions.create() pointing back to target_turn["interaction_id"] with the new error result, and hands the forked interaction to run_agent(). The original session in session.json remains untouched, while the alternate timeline is saved to branch.json.

Run the branch

Watch whether the agent tries to recover, recognises that it cannot, and escalates. The verdict shows escalated set to true. You can branch the same turn as many times as you like: each branch is a new interaction, and the original session is unchanged.

This workshop runs everything in Cloud Shell so you can focus on the API. When you move a stateful agent into a real Google Cloud architecture, apply these practices:

• Store interaction IDs, not history: Save the latest interaction ID with your own record, for example in Firestore against an incident ID. Any instance of your service can then continue the session, so the service itself stays stateless and scales out on Cloud Run.
• Record what your tools did: Keep your own log of tool calls and results, as session.json does here. You need it to rebuild, audit or branch, because the server does not know the state of your systems.
• Send configuration on every call: Keep the model, tools, system instruction and generation settings in one place, as REQUEST_CONFIG does, and send them with every request.
• Design tools for reasoning and safety: Typed arguments, enums, clear errors and an escalation path. Put destructive actions behind a human approval step.
• Bound the loop: Keep a turn limit, and treat any status other than completed or requires_action as a stop condition.
• Verify before you act: Validate structured output, and check the agent's claims against your own systems.
• Plan for retention and privacy: Know your retention window, use store=False where data must not be stored, and delete interactions you no longer need.
• Protect the key: Keep the API key in Secret Manager and inject it at runtime.
• Observe with steps: Export interaction.steps, including thought summaries, to your logging system as an audit trail.

Clean Up

1. Clear the environment variable:

2. Revoke the API key: If you created a key only for this workshop, open the API keys page in Google AI Studio and delete it.

3. Stored interactions: Interactions from this workshop expire on their own (after 1 day on the free tier). To remove them sooner, call client.interactions.delete(id=...) for the IDs in session.json and branch.json.

4. Close Cloud Shell: Type exit or close the Cloud Shell pane. Your orbital7-agent folder stays in your Cloud Shell home directory if you want to come back to it.

Summary

You built an agent that diagnoses and recovers from a cascading failure with incomplete information, and you used the Interactions API to run, inspect, resume and branch its sessions.

What you covered:

• A tool loop built on typed function_call steps and function_result inputs matched by call ID.
• Tools that make a model reason, and errors it can recover from.
• Interaction-scoped configuration, and what previous_interaction_id does and does not carry over.
• Thought summaries, and the difference between what you send and what the model reads.
• Structured incident reports, checked against ground truth.
• Resuming a session from a new process, and branching it from an earlier turn while rebuilding your own environment state.

Next steps:

• Add a human approval step before destructive tools, and return a rejected action as a function_result.
• Stream the agent's thoughts and actions live with stream=True.
• Run long incidents with background=True and poll them with client.interactions.get().
• Hand the finished session to the Deep Research agent for a postmortem, chained with previous_interaction_id.
• Replace the simulator with real Cloud Monitoring and Compute Engine calls.

Learn more:

• Interactions API overview
• Interactions API reference (v1)
• Function calling with the Interactions API
• Structured output with the Interactions API
• Google Gen AI Python SDK