	In Browser
	StumbleUpon
	del.icio.us
	Google
	Google Buzz
	reddit
	LinkedIn

	Facebook
	Twitter
	Linkedin
	E-Mail

Generative AI > Google Gemini API > ADK Stateful Agents - Managing State Between Turns

ADK Stateful Agents - Managing State Between Turns

Author: Venkata Sudhakar

ADK session state lets your agent store and retrieve structured data across conversation turns within the same session. This goes beyond the conversation history (which is plain text) ï¿½ session state is a typed key-value store where you can persist numbers, lists, dictionaries, and any serialisable Python object. A shopping cart agent can add items to state on turn 2, check the cart on turn 4, and process checkout on turn 6, all without the user repeating what they added. State is scoped to the session so different users get separate isolated state stores.

Tools access session state via the ToolContext object passed as the last parameter. Reading state uses tool_context.state.get(key, default). Writing state uses tool_context.state[key] = value. State changes are automatically persisted by the session service between turns ï¿½ no manual save needed. When deployed to Agent Engine, session state persists in managed cloud storage. Locally it persists in InMemorySessionService for the lifetime of the process.

The below example builds a multi-turn shopping cart agent where the agent accumulates items across turns, calculates running totals, and processes checkout ï¿½ all using session state to remember what has been added.

from google.adk.agents import Agent
from google.adk.tools.tool_context import ToolContext
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types as genai_types

PRODUCTS = {
    "samsung tv":     {"price": 89990, "name": "Samsung 65-inch QLED TV"},
    "iphone 15 pro":  {"price": 134900, "name": "iPhone 15 Pro 256GB"},
    "airpods pro":    {"price": 24900, "name": "AirPods Pro 2nd Gen"},
    "dell laptop":    {"price": 124999, "name": "Dell XPS 15 Laptop"},
    "sony headphones":{"price": 29990, "name": "Sony WH-1000XM5"}
}

def add_to_cart(product_name: str, quantity: int, tool_context: ToolContext) -> dict:
    # Adds an item to the session cart state
    key = product_name.lower().strip()
    product = PRODUCTS.get(key)
    if not product:
        return {"error": "Product not found: " + product_name}
    cart = tool_context.state.get("cart", [])
    for item in cart:
        if item["key"] == key:
            item["qty"] += quantity
            tool_context.state["cart"] = cart
            return {"added": product["name"], "qty": item["qty"], "cart_size": len(cart)}
    cart.append({"key": key, "name": product["name"],
                 "price": product["price"], "qty": quantity})
    tool_context.state["cart"] = cart
    return {"added": product["name"], "qty": quantity, "cart_size": len(cart)}

def view_cart(tool_context: ToolContext) -> dict:
    # Returns the current cart contents from session state
    cart = tool_context.state.get("cart", [])
    if not cart:
        return {"empty": True, "message": "Cart is empty"}
    total = sum(i["price"] * i["qty"] for i in cart)
    return {"items": cart, "total_inr": total, "item_count": len(cart)}

def checkout(tool_context: ToolContext) -> dict:
    # Processes checkout and clears the cart from session state
    cart = tool_context.state.get("cart", [])
    if not cart:
        return {"error": "Cart is empty"}
    total = sum(i["price"] * i["qty"] for i in cart)
    order_id = "ORD-" + str(abs(hash(str(cart))))[:5]
    tool_context.state["cart"] = []  # clear cart after checkout
    tool_context.state["last_order"] = order_id
    return {"order_id": order_id, "total_inr": total,
            "items_ordered": len(cart), "status": "Confirmed"}

cart_agent = Agent(
    model="gemini-2.0-flash",
    name="shopping_cart_agent",
    instruction=(
        "You are a ShopMax India shopping assistant. "
        "Help customers add products to their cart, review cart contents, "
        "and complete purchases. Use tools to manage the cart. "
        "Always confirm what was added and show the running total."
    ),
    tools=[add_to_cart, view_cart, checkout]
)

Running a multi-turn shopping session to show state persisting across turns,

It gives the following output showing cart state persisting across all turns,

Turn 1: Added Samsung 65-inch QLED TV to your cart! Cart total: Rs 89,990.

Turn 2: Added 2x AirPods Pro to your cart. Running total is now Rs 1,39,780.

Turn 3: Your cart has 2 items:
        1. Samsung 65-inch QLED TV x1 - Rs 89,990
        2. AirPods Pro 2nd Gen x2    - Rs 49,800
        Total: Rs 1,39,790

Turn 4: Added iPhone 15 Pro to your cart.
        Order confirmed! Order ID: ORD-84291
        Items ordered: 3 | Total paid: Rs 2,74,690
        Thank you for shopping with ShopMax!

# Cart state persisted across all 4 turns automatically
# tool_context.state["cart"] survived between each runner.run() call
# Clearing state on checkout prevents stale data in the next session

Session state best practices: keep state values small and serialisable ï¿½ lists and dicts of strings and numbers work best. Avoid storing large objects or binary data in state. Always provide a default when reading state with .get(key, default) since the key may not exist on the first turn. Clear state explicitly when a workflow completes (like clearing the cart after checkout) rather than letting it accumulate indefinitely. For production on Agent Engine, state is persisted in managed cloud storage automatically ï¿½ the same ToolContext pattern works without any code changes between local and cloud deployment.

Send your comments, suggestions or queries regarding this site to [email protected].