Sessions

You do not have to call this

Invoking with a session id that does not exist creates the conversation, so a backend can choose its own id — sess-ada-1 — and never call this. What it adds is STARTING STATE the agent can read on its very first turn, or an id ADK minted for you.

An id already in use is a 409, never a reuse

Creating over an existing conversation would hand somebody's history your starting state. The route looks first and refuses, naming the id.

Conversation-scoped keys only, and the refusal names the key

ADK scopes state by prefix. app: is shared by every user of the agent, user: by every conversation of that user, temp: is never persisted, and agentkit: is the platform's own — so each is refused with a 400 naming it. A key with no prefix belongs to this conversation alone. 64 KiB serialized at most: a file belongs in an artifact, not in state, because state is replayed into every turn.

user makes it one of your customers' — and must match the invoke

Without it the conversation belongs to your own credential. A backend that creates one as itself and then invokes with end_user_id has made two different addresses, and the agent never sees the state you seeded. Pass the same person here as user and the invocation lands in this conversation.

Per agent, and agent is required

A conversation lives in its agent's own database, so there is no listing across agents to ask for — one call per agent you care about.

Whose: yours, or one of your users'

Without user this lists the CALLER's conversations — and a service credential's own list is usually empty, because a backend's conversations belong to the customers it invoked for. user=ada lists theirs, and needs a tenant admin.

state_keys, not state

A page of conversations does not ship every one's state. The listing names the keys; reading one conversation returns the values.

State as ADK hands it to the agent

Including the app: and user: values ADK merges into every session it loads — readable here, never writable through this API. The platform's own agentkit: records are left out: a stored MCP Apps view is a whole HTML document, and it comes back as a surface event from the events route instead.

THE SAME SHAPE AS /ws, ON PURPOSE

Each stored ADK event is classified by the same function the engine classifies a live one with, and its payload is the same dump the engine publishes. A person's own message is a started event carrying payload.text. A client that folds frames into turns needs one fold, not two that agree today and drift the day one is edited.

Each run ends the way it ends live

Terminal events are synthesized, one per run: paused — carrying interrupt_id, interrupt_kind and message — when the run is still waiting, and finished otherwise. So ends_the_run (endsTheRun in Node) ends each turn here exactly as on the socket. A pause that was answered stays in the history as ADK's own paused event, which carries no interrupt_kind, so the same rule reads past it.

MCP Apps views come back where they appeared

A view an agent showed is stored in session state when it is shown and returns here as a surface event at that point in the timeline, so a reopened conversation re-renders it. A view shown before the agent was redeployed onto that runtime was never stored.

Paging: recent opens a long one, after catches up

recent=N is the newest N ADK events — counted BEFORE the synthesized frames are added, so a page carries a few more than N, and its oldest run may begin mid-way without its started. after is seconds since the epoch and is INCLUSIVE (ADK filters >=), so catching up from the newest event you hold returns that event again. seq is numbered per response and cannot dedupe across two reads; compare emitted_at instead. There is no before: reading further back means reading without recent.

What history cannot show

queued, typing and action_requested are the platform's own parallel stream, not ADK events, so they were never stored. segment and target_version are empty. And this is ADK's record of the CONVERSATION, not of each run's fate: a run the platform stopped around ADK — a refused payment, a refused option — may read here as finished, or be absent. GET /v1/runs/{invocation_id} is the record of how a run ended and what it cost.

For workflows, not conversations

A graph's progress is a shape a transcript cannot show — which nodes ran, in what order, and which one is waiting. An agent has no steps and this tells you nothing useful about one.

Order from the events, status from ADK's checkpoint

The checkpoint is a jsonb column, and jsonb re-sorts object keys, so it cannot say what ran first. Steps are deduped on node_info.path, because a replayed node gets a fresh event id. This is the projection rt-service always made, now one function shared by both services.

The runs survive it

What goes is the conversation. The invocations it contained remain in the run history and the warehouse, because they were billed and audited — deleting a conversation is not a way to unbill a run.

Erasure on a customer's request is user=

A tenant admin can delete one of their users' conversations by naming them. Without user, only the caller's own.