AutoGen Tutorial (Python): persisting agent state for advanced developers

This tutorial shows how to persist AutoGen agent state in Python so conversations, memory, and tool context survive process restarts. You need this when you’re building long-running assistants for banking, insurance, or internal ops where losing the agent’s working state means losing auditability and continuity.

What You'll Need

• •Python 3.10+
• •pyautogen installed
• •An OpenAI API key set as OPENAI_API_KEY
• •A writable local directory for saved state
• •Basic familiarity with AssistantAgent, UserProxyAgent, and AutoGen chat loops

Step-by-Step

1. •Start by creating a normal AutoGen agent pair and a small persistence layer.
   The key idea is simple: save the conversation transcript to disk after each run, then reload it before the next run.

import json
from pathlib import Path

from autogen import AssistantAgent, UserProxyAgent

STATE_DIR = Path("agent_state")
STATE_DIR.mkdir(exist_ok=True)
STATE_FILE = STATE_DIR / "chat_state.json"

llm_config = {
    "model": "gpt-4o-mini",
    "api_key": None,
}

assistant = AssistantAgent(
    name="assistant",
    llm_config=llm_config,
)

user_proxy = UserProxyAgent(
    name="user_proxy",
    human_input_mode="NEVER",
    code_execution_config=False,
)

2. •Add helpers to save and load the chat history.
   This example persists the exact message list AutoGen uses internally, which is enough to restore context across restarts for most production workflows.

def save_messages(messages):
    STATE_FILE.write_text(json.dumps(messages, indent=2), encoding="utf-8")

def load_messages():
    if not STATE_FILE.exists():
        return []
    return json.loads(STATE_FILE.read_text(encoding="utf-8"))

def print_last_message(messages):
    if messages:
        print(f"Last saved role: {messages[-1]['role']}")
        print(f"Last saved content: {messages[-1]['content']}")

3. •Restore prior state into both agents before starting a new turn.
   AutoGen agents keep their own internal message buffers, so you need to seed them with the same history after a restart.

messages = load_messages()
print_last_message(messages)

if messages:
    assistant._oai_messages[user_proxy] = messages.copy()
    user_proxy._oai_messages[assistant] = messages.copy()

new_prompt = "Continue from the previous discussion and summarize the outstanding action items."

4. •Run the conversation and persist the updated transcript immediately afterward.
   In production, save after every successful turn so a crash or deployment does not wipe the latest state.

result = user_proxy.initiate_chat(
    assistant,
    message=new_prompt,
)

updated_messages = assistant._oai_messages[user_proxy]
save_messages(updated_messages)

print("Conversation saved.")
print(f"Messages persisted: {len(updated_messages)}")

5. •If you want cleaner isolation, wrap persistence in a small state manager class.
   This keeps file I/O out of your agent orchestration code and makes it easier to swap JSON files for Redis, Postgres, or S3 later.

class JsonChatStateStore:
    def __init__(self, path: Path):
        self.path = path

    def load(self):
        if not self.path.exists():
            return []
        return json.loads(self.path.read_text(encoding="utf-8"))

    def save(self, messages):
        self.path.write_text(json.dumps(messages, indent=2), encoding="utf-8")

store = JsonChatStateStore(STATE_FILE)
messages = store.load()
if messages:
    assistant._oai_messages[user_proxy] = messages.copy()
    user_proxy._oai_messages[assistant] = messages.copy()
store.save(assistant._oai_messages.get(user_proxy, []))

Testing It

Run the script once with a prompt like “Draft a claims escalation checklist.” Then stop the process, rerun it, and send a follow-up prompt like “Refine that for high-value policies only.” If persistence is working, the assistant should respond as if it remembers the earlier checklist instead of starting from scratch.

Check that agent_state/chat_state.json exists and contains a valid JSON array of messages. You should also see the last saved role/content printed before each resumed run.

If you want stronger validation, compare the length of the stored message list before and after each turn. In production systems, add assertions around file writes and log every persistence event with a correlation ID.

Next Steps

• •Replace JSON files with Redis or Postgres for multi-instance deployments.
• •Persist tool outputs separately from chat messages so you can replay workflows deterministically.
• •Add encryption at rest if your agent handles customer data or regulated case notes.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.