Saving and resuming agent conversations

What to storeCopy Anchor Link

The full ordered list of messages, including tool calls and tool results, plus metadata: user id, model and prompt version, timestamps and token counts. Store one row per message or one document per conversation. Include a version of your message format so old conversations still load after you change it.

Practical rulesCopy Anchor Link

Keep each conversation private to its owner. Redact secrets and personal data you do not need. Add a retention limit. Treat stored history as untrusted: it may contain injected text from earlier tool results.

A worked example: what a saved record looks likeCopy Anchor Link

conversation_id, user_id, created_at, model "sonnet-5-5", prompt_version "v14", messages: [ {role: user, text: ...}, {role: assistant, tool_call: search(...)}, {role: tool, result: ...}, ... ]. When the user returns, load the list, add the new message and send. If it is too long, summarize the oldest part and keep the last few turns.

Resuming, step by stepCopy Anchor Link

1. Load the saved messages by conversation id.
2. Check the owner is the current user.
3. Check the format version and convert old records if needed.
4. Append the new user message and save it right away.
5. Count tokens. If over budget, trim or summarize.
6. Send, then save each reply and tool result as it arrives, not once at the end.

Saving as you go matters. If the process dies midway, you lose one step, not the whole conversation.

What goes wrong: a crash between call and resultCopy Anchor Link

The assistant's tool call was saved, then the server crashed before the tool result was written. On resume, the history has a call with no result. The major provider APIs reject a tool call that has no matching result, so the symptom is an error that only affects conversations that were interrupted. Confirm it by scanning saved conversations for tool calls without a matching result. On load, either drop the dangling call or add a result saying "interrupted before finishing".

Trimming without losing the goalCopy Anchor Link

Suppose a conversation has 40 messages and is too long. Keep the first message, since it holds the original goal. Replace messages 2 to 33 with one summary message. Keep the last 7 turns as they are. That is 1 + 1 + 7 = 9 messages instead of 40. Check that a tool call and its result are kept or dropped together, never split.

Common mistakeCopy Anchor Link

Trimming messages by cutting in the middle of a tool call, leaving a result with no matching call.