---
title: "Tutorial: Atomic session append with ADK"
description: "Store Google ADK agent session events in Aerospike with safe concurrent appends and no duplicate writes."
---

# Tutorial: Atomic session append with ADK

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

::: note
Developers building AI agent applications with Google ADK.
:::
::: undefined
This tutorial should take between 20 and 35 minutes.
:::

## 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)](https://adk.dev/) 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`](https://github.com/aerospike-community/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.

::: undefined
-   I understand what safe session storage means for ADK agents that share one conversation.
:::

[Next  
Prerequisites](https://aerospike.com/docs/develop/adk-atomic-session-append/step/1/part/0/prerequisites)