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

This tutorial shows how to persist AutoGen agent state in Python so a conversation can stop, restart, and continue without losing context. You need this when your agent runs across multiple jobs, survives process restarts, or has to keep long-running case state for support, claims, or back-office workflows.

What You'll Need

• •Python 3.10+
• •autogen-agentchat
• •autogen-ext
• •An OpenAI API key in OPENAI_API_KEY
• •A writable local directory for checkpoints
• •Basic familiarity with AutoGen agents and asyncio

Install the packages:

pip install autogen-agentchat autogen-ext openai

Step-by-Step

1. •Start by creating a simple assistant agent with a model client. The key point here is that we will later save and reload the agent’s state, so keep the setup deterministic and minimal.

import asyncio
import os

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

MODEL_NAME = "gpt-4o-mini"

async def main():
    model_client = OpenAIChatCompletionClient(
        model=MODEL_NAME,
        api_key=os.environ["OPENAI_API_KEY"],
    )

    agent = AssistantAgent(
        name="support_agent",
        model_client=model_client,
        system_message="You are a concise support assistant.",
    )

    result = await agent.run(task="Remember that the customer prefers email.")
    print(result.messages[-1].content)

if __name__ == "__main__":
    asyncio.run(main())

2. •Next, capture the agent state after the first run. In AutoGen, this is the piece you persist to disk or a database so you can restore the conversation later.

import asyncio
import json
import os

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

MODEL_NAME = "gpt-4o-mini"
STATE_FILE = "agent_state.json"

async def main():
    model_client = OpenAIChatCompletionClient(
        model=MODEL_NAME,
        api_key=os.environ["OPENAI_API_KEY"],
    )

    agent = AssistantAgent(
        name="support_agent",
        model_client=model_client,
        system_message="You are a concise support assistant.",
    )

    await agent.run(task="Remember that the customer prefers email.")
    state = await agent.save_state()

    with open(STATE_FILE, "w", encoding="utf-8") as f:
        json.dump(state, f, indent=2)

    print(f"Saved state to {STATE_FILE}")

if __name__ == "__main__":
    asyncio.run(main())

3. •Now restore that state into a fresh agent instance. This is the part people usually miss: persistence only matters if you can recreate the agent from scratch and load the saved snapshot back in.

import asyncio
import json
import os

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

MODEL_NAME = "gpt-4o-mini"
STATE_FILE = "agent_state.json"

async def main():
    model_client = OpenAIChatCompletionClient(
        model=MODEL_NAME,
        api_key=os.environ["OPENAI_API_KEY"],
    )

    agent = AssistantAgent(
        name="support_agent",
        model_client=model_client,
        system_message="You are a concise support assistant.",
    )

    with open(STATE_FILE, "r", encoding="utf-8") as f:
      state = json.load(f)

    await agent.load_state(state)
    result = await agent.run(task="What communication channel does the customer prefer?")
    print(result.messages[-1].content)

if __name__ == "__main__":
    asyncio.run(main())

4. •If you want something production-friendly, wrap persistence in helper functions and save after each meaningful turn. That gives you a clean checkpointing pattern instead of relying on one-off scripts.

import asyncio
import json
import os
from pathlib import Path

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

MODEL_NAME = "gpt-4o-mini"
STATE_FILE = Path("checkpoints/support_agent_state.json")

async def save_agent(agent: AssistantAgent) -> None:
    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
    with STATE_FILE.open("w", encoding="utf-8") as f:
        json.dump(await agent.save_state(), f, indent=2)

async def load_agent(model_client: OpenAIChatCompletionClient) -> AssistantAgent:
    agent = AssistantAgent(
        name="support_agent",
        model_client=model_client,
        system_message="You are a concise support assistant.",
    )
    if STATE_FILE.exists():
        with STATE_FILE.open("r", encoding="utf-8") as f:
            await agent.load_state(json.load(f))
    return agent

async def main():
    client = OpenAIChatCompletionClient(model=MODEL_NAME, api_key=os.environ["OPENAI_API_KEY"])
    agent = await load_agent(client)
    await agent.run(task="Record that the customer also prefers SMS for urgent updates.")
    await save_agent(agent)

if __name__ == "__main__":
    asyncio.run(main())

5. •Finally, use the restored state in a second process or later execution to prove persistence works end to end. This is what makes it useful for cron jobs, worker restarts, and multi-step case handling.

import asyncio
import json
import os

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

MODEL_NAME = "gpt-4o-mini"

async def main():
    client = OpenAIChatCompletionClient(model=MODEL_NAME, api_key=os.environ["OPENAI_API_KEY"])

    first_run_agent = AssistantAgent(
        name="support_agent",
        model_client=client,
        system_message="You are a concise support assistant.",
    )
    await first_run_agent.run(task="Remember that the customer prefers email.")
    saved_state = await first_run_agent.save_state()

    second_run_agent = AssistantAgent(
        name="support_agent",
        model_client=client,
        system_message="You are a concise support assistant.",
    )
    await second_run_agent.load_state(saved_state)
    response = await second_run_agent.run(task="Summarize what you know about this customer.")
    
if __name__ == "__main__":
    asyncio.run(main())

Testing It

Run the first script once to create agent_state.json, then run the restore script in a separate process. The second run should answer using context from the earlier conversation instead of treating it like a brand-new session.

A good sanity check is to ask for something specific that was only mentioned before saving state, such as “What channel does the customer prefer?” If persistence is working, the answer should reflect the earlier message.

If you’re wiring this into an app server, kill the process after saving state and restart it before loading. If the restored agent still remembers prior facts, your checkpointing path is correct.

Next Steps

• •Move from local JSON files to Redis or Postgres-backed storage for multi-instance deployments.
• •Persist not just one agent but an entire team workflow with shared checkpoints.
• •Add versioning to your saved state so old checkpoints can be migrated safely when your prompts or tools change.

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.