AutoGen Tutorial (Python): persisting agent state for beginners

This tutorial shows how to persist an AutoGen agent’s state to disk and load it back in a later Python run. You need this when you want an agent to remember prior work across restarts, not just within a single process.

What You'll Need

• •Python 3.10+
• •autogen-agentchat
• •autogen-ext[openai]
• •An OpenAI API key in OPENAI_API_KEY
• •Basic familiarity with AssistantAgent and UserProxyAgent
• •A writable local directory for saving state files

Step-by-Step

1. •Start by installing the packages and setting your API key. This example uses the OpenAI model client from AutoGen’s extension package.

pip install autogen-agentchat autogen-ext[openai]
export OPENAI_API_KEY="your-api-key"

2. •Create a small assistant agent and wire it to an OpenAI model client. Keep the model name explicit so your saved state is reproducible across runs.

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() -> None:
    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.",
    )

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

3. •Run one interaction, then save the agent state to JSON. The important part is that the state file captures the conversation and internal agent state you want to restore later.

import asyncio
import json
import os
from pathlib import Path

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

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

async def main() -> None:
    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.",
    )

    response = await agent.run(task="Remember that our refund policy is 30 days.")
    print(response.messages[-1].content)

    state = await agent.save_state()
    STATE_FILE.write_text(json.dumps(state, indent=2), encoding="utf-8")

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

4. •In a new process, load the saved state before asking follow-up questions. This is what makes persistence useful: the agent starts from where it left off instead of a blank slate.

import asyncio
import json
import os
from pathlib import Path

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

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

async def main() -> None:
    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.",
    )

    saved_state = json.loads(STATE_FILE.read_text(encoding="utf-8"))
    await agent.load_state(saved_state)

    response = await agent.run(task="What is our refund policy?")
    print(response.messages[-1].content)

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

5. •If you want a cleaner workflow, wrap save/load in helper functions. That keeps persistence logic out of your business code and makes it easy to reuse across multiple agents.

import json
from pathlib import Path
from typing import Any

def save_agent_state(agent: Any, path: str) -> None:
    state = asyncio.run(agent.save_state())
    Path(path).write_text(json.dumps(state, indent=2), encoding="utf-8")

def load_agent_state(agent: Any, path: str) -> None:
    raw = Path(path).read_text(encoding="utf-8")
    state = json.loads(raw)
    asyncio.run(agent.load_state(state))

Testing It

Run the first script once and confirm that support_agent_state.json is created on disk. Then run the second script in a separate process and check whether the assistant answers with awareness of the earlier refund-policy message.

A good test is to change the follow-up prompt slightly and see if the response still reflects stored context. If it behaves like a fresh assistant every time, you are either not loading state or you are recreating the wrong agent configuration.

Also verify that the same name, system_message, and model setup are used on both save and load paths. State loading works best when those pieces stay stable between runs.

Next Steps

• •Persist more than one agent and coordinate them through a shared storage layer.
• •Add versioning to your saved state so older snapshots can be migrated safely.
• •Move from local JSON files to Redis or Postgres when you need multi-process or production-grade persistence.

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.