Sessions and State
Understand conversation continuity, native transcripts and working files across requests and replicas.
Pass the same session_id to continue a conversation. Use a new ID for independent work, and enforce the relationship between the authenticated caller and the session in your application. A session ID by itself is not authorization.
Know which state you are storing
| State | Owner and recovery boundary |
|---|---|
| Agno run/session records | The configured database stores status, content, captured messages and tool results. |
| Native conversation | The harness owns its transcript format and context management. Claude and Codex restoration differ. |
| Stream events | The event transport supports live reconnect; stored run events provide retained-event replay after transport expiry. Token deltas are skipped by default. |
| Workspace | Local files, dependencies and processes need their own lifecycle and persistence policy. |
| Credentials and extensions | Provision independently of conversation state. |
The first-service guides use SQLite locally. A multi-replica deployment requires shared production storage; use Postgres for the configuration in Deploy and Operate.
Claude native transcripts
With a supported database, the default Agno integration persists the Claude session identity and provides the SDK's transcript store. Claude writes native transcripts locally and mirrors entries into that store. A clean replica can materialize the transcript from the store for native resume; ordinary Agno display history is a separate record.
Native transcripts can include environment context such as working directory, platform, shell and Git branch, as well as session-context reminders such as a user email. Apply your access, retention and deletion policies to the transcript store as well as the ordinary run history.
The SDK defaults to batched mirroring. Eager flushing reduces the interval between local writes and external persistence but remains asynchronous. A crash before a successful append can lose the unmirrored portion. A transcript_persistence_failed warning means completed output may be available while native recovery state is incomplete; do not automatically repeat successful external tool effects to repair a mirror.
Agno does not attach its transcript store when the database lacks transcript methods, a custom session_store is supplied, or native file checkpointing is enabled. Verify these settings before relying on cross-replica native resume. Keep the agent ID or explicit project_key stable across replicas.
Codex native threads
Agno stores codex_thread_id with the session and requests native resume on later turns. Codex's native thread state remains filesystem-backed. If the native thread is missing, the adapter starts a new thread seeded with bounded Agno history.
That fallback can preserve conversational context, but does not reproduce all native transcript details or compaction state. Other errors, including an active native writer, are surfaced instead of silently replacing the thread. ephemeral=True does not retain a native thread for later resume.
Serialize turns within a session
The durable queue serializes eligible harness turns within a session in queue acceptance order. Waiting turns remain PENDING with attempt zero; waiting does not consume the retry budget. If your application requires a particular conversation order, submit turns in that order and wait for acceptance. See Retries and Tool Effects for queue behavior.
For foreground requests, wait for the current turn to finish before submitting the next turn in the same session. A busy-session error returns 409 for a nonstreaming request or a RunError event after streaming starts. The local busy-session guard and database check are not a distributed lock. Coordinate foreground submissions across application replicas and avoid overlapping them with queued turns. Independent sessions can run concurrently.
Working files are separate
Restoring a transcript does not restore edited files, installed dependencies, running processes, credentials or plugins. Give execution an explicit writable location and a cleanup policy. A local cwd or native permission setting does not allocate a session sandbox or provide tenant isolation.
If a workflow uses only remote MCP business operations, keep local scratch state disposable and persist business state in the tool service. If it depends on local files across turns, define a workspace storage and recovery strategy before moving the session between machines.
Check your recovery contract
For the exact SDK versions and deployment you use, test a follow-up turn after replacing the execution process and removing disposable native state. Check both the answer and native session/thread identity. Test a separately created workspace file independently of conversational recall. A recovered fact does not establish workspace recovery or exact native continuity.