Tutorial: Atomic session append with ADK

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Objectives

By the end of this tutorial, you will be able to:

Give ADK agents durable session storage in Aerospike through AerospikeSessionService, using the standard create_session, append_event, and get_session APIs with no custom persistence layer.
Merge app-, user-, and session-scoped state correctly as turns accumulate, with each event and its state_delta stored in one atomic write.
Let multiple workers append to the same session in parallel and survive retried writes without duplicate events, gaps, or corrupted counts.

Imagine a coordinator agent that delegates work to several sub-agents at once: one researches a topic, another retrieves documents, and a third drafts a summary. Each sub-agent adds messages and state updates to the same conversation. If two workers write at the same time, or if a network retry replays a write, you can lose events, duplicate turns, or merge state in the wrong order.

Google Agent Development Kit (ADK) is Google’s framework for building these multi-step agent applications. ADK tracks each conversation in a session: a durable record of events (user messages, model replies, tool results) plus session state (metadata the agent accumulates across turns). Your code calls append_event to add each turn and get_session to read back session history.

By default, ADK expects a session service to persist that data. When more than one worker updates the same session, or when a network retry replays an append_event call, that service must keep the conversation correct.

Safe session storage

Safe session storage means:

Guarantee	What it protects against
Atomic appends	An event landing without its `state_delta`, or state updating without the event
Idempotent retries	A replayed write updates the same slot without creating a duplicate turn
Correct concurrent writes	Parallel workers causing gaps, duplicate events, or corrupted state counts

Without these guarantees, agents lose context, repeat work, or merge app-, user-, and session-scoped state in the wrong order.

The adk-aerospike package provides AerospikeSessionService, which implements safe session storage in Aerospike Database. Each append is atomic and idempotent, so those guarantees hold under parallel writers and retried calls.

In this tutorial, you deploy Aerospike Database with Docker, install AerospikeSessionService, run a demo script with five sequential appends and then 64 parallel writers on one session, and confirm the service stores every event once with no duplicates or gaps.

Key terms

Term	Meaning
Session	One conversation thread for a given app, user, and session ID. Holds events and its merged state.
Event	A single turn in the conversation (for example, a user message or assistant reply).
Session state	Key-value data the agent updates across turns, such as a turn counter or tenant ID.
`append_event`	ADK API call that adds an event (and optional state changes) to a session.
`get_session`	ADK API call that reads a session’s events and its merged state.
`AerospikeSessionService`	The `adk-aerospike` backend that maps ADK sessions to Aerospike records and enforces safe appends.

When to use this pattern

Use this tutorial when you:

Build ADK agents where more than one worker updates the same session.
Need safe session storage that survives retries without duplicate events or lost turns.
Want to verify concurrent appends on Aerospike before wiring AerospikeSessionService into your own app.

What you do

The demo runs in two phases on one session:

Sequential appends: five events with multi-scope state updates to show how its state merges after each turn.
Concurrent appends: 64 writers each add 1,000 events to stress-test safe session storage under load.

In production, the same pattern applies whenever sub-agents or tool workers append to a shared session. Safe session storage must hold under parallel writes and network retries, not only in a single-threaded demo.

On the next page, you learn how events and state map to Aerospike records before you run the demo.