Place state at the right lifetime boundary

Learning objective

Distinguish per-turn state, persisted sessions, and application artifacts by their lifetime, representation, and owning service. This lesson focuses on placing data at the correct boundary, not on choosing a session backend or designing long-term memory.

Core idea

Use three different containers for three different jobs:

• Per-turn state is a workbench. Keep intermediate values that are useful only while the agent handles the current request.
• A persisted session is a conversation ledger. Keep events and compact state that a later turn in the same conversation must recover.
• An artifact is a versioned file. Keep uploads, generated reports, images, and other file-like or large payloads outside session state.

Classify data by lifetime first, then by shape. A value that must survive the current turn needs a persistent boundary. A large or binary value needs an artifact even if it belongs to only one session.

How it works

Per-turn state

In Agent Development Kit (ADK), per-turn state maps to a temp: state key. Its precise lifetime is one invocation: the work started by one user request and ended by its final response. One invocation can contain several model calls, tool calls, callbacks, and agent calls. Therefore, “per-turn” does not mean “per model call.” ADK discards temp: state when the invocation ends, so it is appropriate for intermediate calculations, routing flags, and retry bookkeeping. See ADK state scopes and the runtime event loop.

Do not keep a value in temp: state if the agent needs it after the user sends another message. The next message starts another invocation.

Persisted sessions

An ADK Session represents one ongoing interaction. It contains a chronological sequence of Event objects and a key-value state collection. An unprefixed state key belongs to the session ID. Use this state for small, serializable values such as a workflow stage, selected record ID, or confirmation status. The ADK conversational-context guide defines the session, state, and service boundaries.

State changes made through a tool or callback context become state deltas on events. The SessionService appends the event and applies its delta. Whether the session survives a process restart depends on the service implementation: an in-memory service does not provide durable storage, while database-backed or managed implementations do. See the ADK state update and persistence guidance.

Persistence does not turn a session into long-term memory. A session remains one conversation thread. Cross-session memory is a separate abstraction.

Application artifacts

Here, an application artifact means file-like data that the application consumes or produces. ADK Artifacts are named and versioned, commonly binary or large, and managed by a separate ArtifactService. Saving an artifact returns a version number; the related event can record a filename-to-version delta, but the artifact service holds the payload itself. The ADK Artifacts guide documents this separation.

A plain filename such as assessment.pdf is session-scoped. A filename with a user: prefix is user-scoped and can be accessed from that user’s other sessions within the application. Neither scope guarantees durability: an in-memory artifact service still loses data when its process ends. Scope answers “who can address this data?” The service implementation answers “where and how durably is it stored?”

Key distinctions and trade-offs

Choosing an artifact is not the same as choosing a longer lifetime. A durable, session-scoped PDF remains an artifact because of its representation and owning service. Likewise, a small workflow checkpoint remains session state even when stored durably.

Artifacts also require explicit loading. Saving a file does not place its bytes in every later model request. Load the needed artifact deliberately, and specify its version when the workflow must reproduce an earlier decision. Loading without a version returns the latest version, which may differ from the one used before. See artifact versioning.

Architecture / decision scenario

An insurance-claim assistant receives a claim form and photos, calls several validation tools, and later asks the customer to confirm the assessment.

During one invocation, the assistant keeps the current fraud-check attempt count and a routing flag in temp: state. These values coordinate the current tool chain and have no value after the response.

The assistant stores claim_id, workflow_stage, and awaiting_customer_confirmation as unprefixed session state. It uses a persistent session service so a later request, possibly handled by another runtime instance, can resume the same conversation.

The assistant stores the uploaded photos, original form, and generated assessment PDF as artifacts. When the assessment affects a later decision, the session checkpoint records the exact filename and version. The next invocation loads that version rather than assuming that the latest file is unchanged.

This design follows two independent tests: workflow checkpoints cross turns, while file payloads use the artifact service regardless of their session scope.

Common exam traps

• Treating one turn as one LLM call. temp: state spans the entire invocation.
• Storing a value needed after the user’s reply in temp: state. It is gone before the next invocation.
• Assuming an in-memory session is persisted because it has a session ID.
• Treating a persisted session as searchable cross-session memory.
• Putting PDF or image bytes in session state because the file belongs to that session. Ownership scope does not change the correct representation.
• Assuming persistent session storage also stores artifacts. SessionService and ArtifactService are separate.
• Assuming every artifact is durable or that loading without a version reproduces the earlier file.

What to remember

• Use temp: state for intermediate data that ends with the invocation.
• Use a persisted session for events and compact state needed by later turns in the same conversation.
• Use artifacts for named, versioned, file-like payloads.
• Decide namespace and storage durability separately.
• Persist the exact filename and version when later work depends on a specific artifact revision.

Knowledge check

References

• Google, Conversational context: Session, State, and Memory
• Google, State: The Session’s Scratchpad
• Google, Runtime event loop
• Google, Artifacts
• Google Cloud, Agent Platform Sessions overview