Durable agent conversations
Understand reconnectable agent turns, lifecycle completion, storage boundaries, and safe continuation after interruption.
Overview
A durable agent conversation survives a closed tab, refresh, or handoff to another browser. Amarsia stores the conversation lifecycle, latest run state, pending client action, actual messages, and safe progress summaries so a client can reconstruct the current state.
Use durable agents when work can pause for a person, pass through several tool rounds, or reopen from a stable link. Continue using an ordinary v1 conversation for request-and-response chat or token streaming.
How it works
Each agent request advances an active conversation:
active conversation
└─ agent turn
├─ completes and remains active
├─ waits for client action ── accepts results ── continues
└─ is interrupted ── Continue starts a new turn
completed conversation
└─ permanently read-onlyA completed turn normally leaves the conversation active, allowing another turn later. A run_id identifies a persisted paused run and can also be exposed for other persisted run states.
The conversation becomes completed only when all conditions are true:
- Allow conversation completion is enabled on the assistant.
- The model calls
complete_conversation. - No client action is pending.
complete_conversationis the final executed server tool in the run.
The backend defers the state change until the model round ends. A premature completion request is recorded as not_completed; the conversation stays active and the model must finish the remaining work before requesting completion again.
Completion is permanent. Once a conversation changes from active to completed, later start, continue, and resume attempts are rejected and the transcript is read-only.
The setting is off by default. Finishing one agent turn does not complete the conversation.
Reconnect and multiple browsers
Store the conversation_id in your database, application route, or customer link. client.agent.open(conversationId, options) loads messages and lifecycle state, then keeps them current through SDK-managed refresh.
Several clients can open the same conversation. When two clients submit results for the same pending calls:
- The first valid result set is accepted.
- An identical retry is idempotent and returns current state.
- Different outputs for the same call IDs return
409 action_result_conflict.
Refresh after a conflict. A later browser cannot overwrite the accepted answer.
Stored data
Durability extends the existing storage model instead of changing what counts as a message:
| Storage | Purpose |
|---|---|
conversations | Identity, active or completed lifecycle, completion time, metadata, and message count |
workflow_logs | Run ID, run status, pending state, usage, safe progress, and tool_usage_logs |
chat_messages | Actual user and assistant messages |
action_logs | Executions of linked server-side actions |
Client-tool calls and results are tool usage. Linked actions are action logs. Neither is converted into a chat message.
Reconnect state is returned as additive fields on GET /v1/runner/conversation/{id}/messages: conversation_status, completed_at, run_id, run_status, pending_client_actions, tool_summary, and progress.
Lifecycle and retention
Completion changes lifecycle, not retention. It does not delete messages, workflow logs, action logs, tool usage, metadata, or other stored records; normal workspace retention and deletion policies still apply.
The latest blocking client action for an agent request remains pending without the legacy pause expiry. Non-agent v2 client-tool runs retain their existing expiry behavior.
Interrupted continuation
The API executes a continuation in process. If execution is interrupted after tool results are accepted, the run reports interrupted and keeps the accepted results.
Do not replay or change accepted tool results. Reopen the conversation and use SDK or hosted-widget Continue to start a new turn with the stored conversation history.
The SDK refreshes the existing messages resource at a configurable interval, two seconds by default. Your application starts or opens the agent and subscribes to state; the SDK handles refresh, reconnect, matching tool results, and common conflict recovery.
Key terms
| Term | Definition |
|---|---|
| Conversation lifecycle | Whether a conversation is active or permanently completed |
| Run | Persisted execution state for an agent turn |
| Client action | A client tool call waiting for your application or a person |
| Pending tool call | A client action whose result has not been accepted |
| Progress | Safe summaries of run and client-action transitions |
| Tool summary | Names and completion states derived from tool usage |