Skip to content
MfPy

Microsoft Agent Framework (Python) — Agent Harness

The agent harness: TodoProvider, AgentModeProvider, MemoryContextProvider, FileMemoryProvider, FileAccessProvider, BackgroundAgentsProvider, ToolApprovalMiddleware and AgentLoopMiddleware — task lists, modes, long-term memory, agent files, background sub-agents, standing approvals and run-until-done loops.

Stability. TodoProvider, TodoSessionStore, AgentModeProvider and the get_agent_mode / set_agent_mode helpers graduated from experimental in 1.12.0. MemoryContextProvider, MemoryStore / MemoryFileStore, TodoFileStore, FileAccessProvider, BackgroundAgentsProvider and AgentLoopMiddleware are still marked ExperimentalFeature.HARNESS and emit an ExperimentalWarning on first use; they may change between minor releases.

Deprecation (1.26.0). MemoryContextProvider, MemoryFileStore, MemoryStore, MemoryIndexEntry and MemoryTopicRecord are deprecated and will be removed after 31 December 2026. They still import and read existing memories, but creating a MemoryFileStore or MemoryContextProvider, or subclassing MemoryStore, now emits a DeprecationWarning. For new work use FileMemoryProvider with a FileSystemAgentFileStore. It is not a drop-in replacement: it uses a different folder layout, does not extract memories automatically, keeps no transcript history and does not migrate existing files.

Verified against agent-framework 1.26.0 (re-checked 2026-11-19; first written for 1.5.0). The tool names the providers expose were renamed in 1.7.0 (add_todos → todos_add, set_mode → mode_set, and so on); this page uses the current names.

HARNESS providers are a family of ContextProvider implementations that give agents durable, session-scoped capabilities beyond conversation history:

Provider / HelperWhat it adds to the agent
TodoProviderFive tools (todos_add, todos_complete, todos_remove, todos_get_remaining, todos_get_all) + instructions for autonomous task tracking
AgentModeProviderTwo tools (mode_get, mode_set) + instructions for operating in distinct modes (plan / execute, or any custom set)
get_agent_mode / set_agent_modeExternal helpers to read and flip the mode from application code without waiting for the agent to call mode_set
MemoryContextProviderCross-session long-term memory: extracts durable facts after each session and injects relevant topics later
FileMemoryProviderSeven file_memory_* tools: session-scoped (or user-scoped) scratch files with a memories.md index
FileAccessProviderEight file_access_* tools: read/edit a shared AgentFileStore workspace, approval-gated by default
BackgroundAgentsProviderSix background_agents_* tools: start sub-agents concurrently, wait for and collect their results
ToolApprovalMiddlewareAuto-approval rules and “always allow” standing approvals stored in the session
AgentLoopMiddlewareRe-runs the agent until a predicate or an LLM judge says the task is done

The providers plug in via context_providers=, the two middleware classes via middleware=, and they keep their state inside AgentSession.state (or optionally on disk).


TodoProvider injects a structured task list that the agent manages itself. The agent plans, tracks, and completes todo items across multiple turns within the same session.

import asyncio
from agent_framework import Agent, TodoProvider
from agent_framework.openai import OpenAIChatClient
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a project-planning assistant.",
context_providers=[TodoProvider()], # state lives in AgentSession by default
)
async def main() -> None:
session = agent.create_session()
# Turn 1 — the agent adds todos as it plans
r1 = await agent.run(
"Plan a three-day product launch: marketing, engineering, and support tasks.",
session=session,
)
print("Plan:\n", r1.text)
# Turn 2 — the agent checks todos_get_remaining and marks items done as it works
r2 = await agent.run(
"Draft the engineering checklist and mark those tasks complete.",
session=session,
)
print("Progress:\n", r2.text)
asyncio.run(main())

The agent receives default instructions that explain all five tools. It manages the list autonomously — no application code needs to drive it.

Every todo the agent creates becomes a TodoItem. The fields:

FieldTypeDescription
idintAuto-assigned integer ID. Use this in todos_complete([id]) and todos_remove([id]).
titlestrShort task description (non-empty, stripped).
descriptionstr | NoneOptional longer description.
is_completeboolTrue after the agent calls todos_complete.
from agent_framework import TodoItem
item = TodoItem(id=1, title="Write unit tests", description="Cover the auth module", is_complete=False)
print(item) # TodoItem(id=1, title='Write unit tests', ...)
# Serialise / deserialise (used by the stores internally)
d = item.to_dict()
restored = TodoItem.from_dict(d)
assert restored == item

TodoInput — what the agent passes to todos_add

Section titled “TodoInput — what the agent passes to todos_add”

When the agent calls todos_add, it produces a list of TodoInput objects (or raw dicts with title and optional description). You rarely construct TodoInput yourself, but it is useful in tests where you want to pre-seed the store:

from agent_framework._harness._todo import TodoInput # not re-exported from agent_framework
task = TodoInput(title="Review PR #42", description="Focus on error handling")
print(task.title) # "Review PR #42"
print(task.to_dict()) # {"title": "Review PR #42", "description": "Focus on error handling"}

Read the task list without going through the agent. This is useful for dashboards, webhook handlers, and CI status checks:

import asyncio
from agent_framework import (
Agent,
AgentSession,
TodoFileStore,
TodoProvider,
TodoSessionStore,
)
from agent_framework.openai import OpenAIChatClient
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a task assistant.",
context_providers=[TodoProvider()],
)
async def main() -> None:
session = agent.create_session(session_id="sprint-22")
await agent.run("Add tasks: write tests, review PR, deploy to staging.", session=session)
# Read from in-memory store — the same session object holds the state
store = TodoSessionStore()
items, _ = await store.load_state(session, source_id="todo")
for item in items:
status = "✓" if item.is_complete else "·"
desc = f" — {item.description}" if item.description else ""
print(f" {status} [{item.id}] {item.title}{desc}")
pending = [i for i in items if not i.is_complete]
done = [i for i in items if i.is_complete]
print(f"\n{len(pending)} pending, {len(done)} complete")
asyncio.run(main())

TodoFileStore — persist todos across process restarts

Section titled “TodoFileStore — persist todos across process restarts”

Swap TodoSessionStore (in-memory) for TodoFileStore when todos must survive restarts or span multiple processes:

import asyncio
from agent_framework import Agent, AgentSession, TodoFileStore, TodoProvider
from agent_framework.openai import OpenAIChatClient
# Todos written to ./todos/<session_id>/todos.todo.json ("todo" is the provider's source_id)
store = TodoFileStore(base_path="./todos")
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a long-running task assistant.",
context_providers=[TodoProvider(store=store)],
)
async def main() -> None:
# First run — agent creates todos and persists them
session = agent.create_session(session_id="project-launch-42")
await agent.run("Break the product launch into 8 concrete tasks.", session=session)
# Second run (new process, same session_id) — agent resumes with existing todos
session2 = agent.create_session(session_id="project-launch-42")
r = await agent.run("What tasks are still pending?", session=session2)
print(r.text)
asyncio.run(main())

Multi-user / multi-tenant partitioning with owner_state_key

Section titled “Multi-user / multi-tenant partitioning with owner_state_key”

Pass owner_state_key to shard todos by user or tenant. The store derives a directory segment from session.state[owner_state_key]:

import asyncio
from agent_framework import Agent, AgentSession, TodoFileStore, TodoProvider
from agent_framework.openai import OpenAIChatClient
# Todos written to ./todos/<user_id>/todos/<session_id>/todos.todo.json
store = TodoFileStore(base_path="./todos", owner_state_key="user_id")
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a task assistant.",
context_providers=[TodoProvider(store=store)],
)
async def main() -> None:
# Alice's session
alice_session = agent.create_session(session_id="s1")
alice_session.state["user_id"] = "alice"
await agent.run("I need to write a report.", session=alice_session)
# Bob's session — completely separate directory
bob_session = agent.create_session(session_id="s2")
bob_session.state["user_id"] = "bob"
await agent.run("Prepare the slides for Monday.", session=bob_session)
# Load Alice's todos directly (without running the agent again)
items, _ = await store.load_state(alice_session, source_id="todo")
print(f"Alice has {len(items)} todo(s):", [i.title for i in items])
asyncio.run(main())

Override the default system-prompt block to tune the agent’s behaviour — for example restricting which tools it may use or adjusting the tone:

from agent_framework import Agent, TodoProvider
from agent_framework.openai import OpenAIChatClient
focused_provider = TodoProvider(
instructions=(
"## Task List\n\n"
"You have a task list. Break complex work into ≤5 tasks at a time.\n"
"- Use `todos_add` when planning.\n"
"- Use `todos_complete` when a task is done. Never skip this step.\n"
"- Never remove tasks without the user's explicit instruction.\n"
),
)
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a disciplined sprint assistant.",
context_providers=[focused_provider],
)
TodoProvider(
source_id: str = "todo", # key in session.state; change when stacking multiple providers
*,
instructions: str | None = None, # None = use default instructions text
store: TodoStore | None = None, # None = TodoSessionStore (in-memory)
)

AgentModeProvider — plan / execute and custom modes

Section titled “AgentModeProvider — plan / execute and custom modes”

AgentModeProvider lets an agent operate in distinct named modes — each with its own instructions injected at runtime. Two modes ship by default: plan (interactive, ask questions) and execute (autonomous, minimise interruptions).

Quickstart — default plan / execute modes

Section titled “Quickstart — default plan / execute modes”
import asyncio
from agent_framework import Agent, AgentModeProvider
from agent_framework.openai import OpenAIChatClient
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a database migration assistant.",
context_providers=[AgentModeProvider()], # default modes: "plan" and "execute"
)
async def main() -> None:
session = agent.create_session()
# Phase 1 — planning: the agent asks questions and proposes a plan
r1 = await agent.run(
"I want to migrate our Postgres schema to add a new 'preferences' JSONB column to the users table.",
session=session,
)
print("Plan phase:\n", r1.text)
# Phase 2 — user approves and switches to execute; the agent works autonomously
r2 = await agent.run(
"The plan looks good. Switch to execute mode and run the migration.",
session=session,
)
print("Execute phase:\n", r2.text)
asyncio.run(main())

In plan mode the agent is instructed to ask for clarification before acting. In execute mode it works autonomously and avoids unnecessary check-ins. Both instructions are injected automatically from the provider.

Define your own mode names and descriptions when the defaults don’t fit. Mode names come from the mode_instructions mapping keys:

import asyncio
from agent_framework import Agent, AgentModeProvider
from agent_framework.openai import OpenAIChatClient
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a code-review assistant.",
context_providers=[
AgentModeProvider(
default_mode="review",
mode_instructions={
"review": (
"Read the diff and identify issues. Do not suggest fixes yet. "
"List every issue with a severity label: 🔴 critical, 🟡 minor, 🟢 nit."
),
"suggest": (
"For each issue listed in the review, propose a concrete code fix. "
"Show the diff inline."
),
"approve": (
"All issues are resolved. Write the final approval comment and call mode_set('done')."
),
"done": "Review complete. Do not take any further actions.",
},
)
],
)
async def main() -> None:
session = agent.create_session()
diff = "--- a/auth.py\n+++ b/auth.py\n@@ -10,6 +10,7 @@ def login(username, password):\n+ user = db.query(username) # SQL injection risk\n ..."
# Review phase — model annotates issues only, no fixes
await agent.run(f"Review this diff:\n\n{diff}", session=session)
# Suggest phase — model proposes fixes
await agent.run("Switch to suggest mode and fix the issues.", session=session)
# Approve phase — model writes the approval
await agent.run("All fixes look good. Approve the PR.", session=session)
asyncio.run(main())

Reading and setting mode from application code

Section titled “Reading and setting mode from application code”

get_agent_mode and set_agent_mode are standalone helpers that read/write the session state directly — no agent run needed. Use them to:

  • Read current mode for a dashboard or audit log
  • Trigger an automated mode transition from a CI gate or webhook
import asyncio
from agent_framework import Agent, AgentModeProvider, AgentSession, get_agent_mode, set_agent_mode
from agent_framework.openai import OpenAIChatClient
MODES = ["review", "suggest", "approve", "done"]
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a code-review assistant.",
context_providers=[AgentModeProvider(default_mode="review", mode_instructions={m: m for m in MODES})],
)
async def main() -> None:
session = agent.create_session(session_id="pr-review-88")
# Start in review mode (default)
current = get_agent_mode(session, default_mode="review", available_modes=MODES)
print(f"Initial mode: {current}") # → "review"
# External event: CI passed — advance the mode to suggest automatically
set_agent_mode(session, "suggest", available_modes=MODES)
print(f"After CI gate: {get_agent_mode(session, available_modes=MODES)}") # → "suggest"
# The next agent.run() will see the injected mode-change notification in its context
r = await agent.run("CI has passed. What should we do next?", session=session)
print(r.text)
asyncio.run(main())

When you call set_agent_mode externally, the provider injects a user-role message on the next run() announcing the switch. This is necessary because system instructions alone may not override a model that has seen its own mode_set tool call earlier in the history. Pass notify=False when the agent has already seen the change (for example, you changed the mode from inside a replacement tool whose result the model will read): that skips the announcement and clears any pending one.

AgentModeProvider(
source_id: str = "agent_mode", # session.state partition key
*,
default_mode: str | None = None, # first key in mode_instructions if omitted
mode_instructions: Mapping[str, str] | None = None, # None = {"plan": ..., "execute": ...}
instructions: str | None = None, # override prompt block; supports {available_modes} and {current_mode}
expose_mode_set: bool = True, # register the mode_set tool
expose_mode_get: bool = True, # register the mode_get tool
)

Combining TodoProvider and AgentModeProvider

Section titled “Combining TodoProvider and AgentModeProvider”

The two providers compose naturally: the agent plans in plan mode (adding todos), switches to execute mode, then works through the list autonomously — completing todos as it goes.

import asyncio
from agent_framework import Agent, AgentModeProvider, AgentSession, TodoProvider, set_agent_mode
from agent_framework.openai import OpenAIChatClient
agent = Agent(
client=OpenAIChatClient(),
instructions=(
"You are an autonomous engineering assistant.\n"
"In plan mode: break the user's request into concrete todo items before doing anything.\n"
"In execute mode: work through your todo list, marking each item complete as you finish."
),
context_providers=[
TodoProvider(),
AgentModeProvider(), # default plan/execute
],
)
async def main() -> None:
session = agent.create_session()
# --- Planning turn ---
r_plan = await agent.run(
"I need to add JWT authentication to our FastAPI app.",
session=session,
)
print("Planning:\n", r_plan.text)
# --- Simulated external approval: advance to execute mode ---
set_agent_mode(session, "execute")
# --- Execution turn ---
r_exec = await agent.run(
"Good plan. Now execute it.",
session=session,
)
print("Execution:\n", r_exec.text)
asyncio.run(main())

Pair TodoFileStore with AgentModeProvider for workflows that span multiple process restarts — the todo state survives, and the mode is stored in AgentSession.state which you can also persist using FileHistoryProvider:

import asyncio
from agent_framework import (
Agent,
AgentModeProvider,
AgentSession,
FileHistoryProvider,
TodoFileStore,
TodoProvider,
get_agent_mode,
set_agent_mode,
)
from agent_framework.openai import OpenAIChatClient
store = TodoFileStore(base_path="./workspace/todos")
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a long-running task assistant.",
context_providers=[
FileHistoryProvider(storage_path="./workspace/history"), # persist conversation
TodoProvider(store=store), # persist todos
AgentModeProvider(), # mode stored in session.state
],
)
async def run_planning_session() -> None:
"""First process: plan and create todos."""
session = agent.create_session(session_id="task-001")
await agent.run(
"I need to migrate our Redis cache from v5 to v7. Create a detailed plan.",
session=session,
)
# Transition to execute and save state; mode is in session.state — serialise if needed
set_agent_mode(session, "execute")
print(f"Mode after planning: {get_agent_mode(session)}")
async def run_execution_session() -> None:
"""Second process (same session_id): execute the plan."""
session = agent.create_session(session_id="task-001")
# History loads from disk; todos load from TodoFileStore
# Mode state must be restored from your own persistence layer (e.g. a DB or a JSON file)
set_agent_mode(session, "execute", available_modes=["plan", "execute"])
r = await agent.run("What tasks are remaining?", session=session)
print(r.text)
asyncio.run(run_planning_session())
# In a new process:
asyncio.run(run_execution_session())

Note on mode persistence: AgentModeProvider stores mode in AgentSession.state. If you need mode to survive across processes, persist session.state yourself — for example, write it to your database after each turn and reload it when you create the next session with session.state.update(stored_state).


Mode-triggered todo creation — advanced pattern

Section titled “Mode-triggered todo creation — advanced pattern”

Use a custom AgentModeProvider instruction that ties todo creation to mode entry. The agent automatically creates todos when it enters plan mode and starts executing them when it switches to execute:

import asyncio
from agent_framework import Agent, AgentModeProvider, AgentSession, TodoProvider, set_agent_mode
from agent_framework.openai import OpenAIChatClient
PLAN_INSTRUCTIONS = (
"## Plan Mode\n\n"
"You are in planning mode. Before doing anything else:\n"
"1. Break the user's request into 3–7 concrete, actionable tasks.\n"
"2. Add them with `todos_add` (include a description for each).\n"
"3. Present the full list to the user for review.\n"
"Do NOT execute any tasks. Ask the user to confirm before switching modes."
)
EXECUTE_INSTRUCTIONS = (
"## Execute Mode\n\n"
"You are in execution mode. Work autonomously:\n"
"1. Call `todos_get_remaining` at the start of each turn.\n"
"2. Pick the next incomplete task and execute it.\n"
"3. Mark it done with `todos_complete([id])` immediately after.\n"
"4. Do not ask the user questions. Make reasonable decisions independently.\n"
"5. When all todos are complete, call `mode_set('review')`."
)
REVIEW_INSTRUCTIONS = (
"## Review Mode\n\n"
"All tasks are complete. Summarise what was done and ask the user if they want any changes."
)
agent = Agent(
client=OpenAIChatClient(),
instructions="You are an autonomous software engineering assistant.",
context_providers=[
TodoProvider(),
AgentModeProvider(
default_mode="plan",
mode_instructions={
"plan": PLAN_INSTRUCTIONS,
"execute": EXECUTE_INSTRUCTIONS,
"review": REVIEW_INSTRUCTIONS,
},
),
],
)
async def main() -> None:
session = agent.create_session()
# Trigger planning
await agent.run(
"Add role-based access control (RBAC) to the admin API.",
session=session,
)
# User approves — advance to execute
set_agent_mode(session, "execute")
r = await agent.run("Plan approved. Go ahead.", session=session)
print(r.text)
asyncio.run(main())

Both TodoSessionStore and TodoFileStore implement TodoStore:

class TodoStore(ABC):
async def load_state(self, session: AgentSession, *, source_id: str) -> tuple[list[TodoItem], int]:
"""Return (items, next_available_id)."""
async def save_state(self, session: AgentSession, items: list[TodoItem], *, next_id: int, source_id: str) -> None:
"""Persist items and the next_id counter."""
async def load_items(self, session: AgentSession, *, source_id: str) -> list[TodoItem]:
"""Convenience: load_state()[0]."""

Subclass TodoStore to use any backend — Redis, Cosmos DB, S3. The only I/O happens in load_state and save_state; the provider handles locking and tool wiring automatically.

from agent_framework import AgentSession, TodoItem, TodoStore
class RedisTodoStore(TodoStore):
def __init__(self, redis_url: str) -> None:
import redis.asyncio as aioredis
self._redis = aioredis.from_url(redis_url)
async def load_state(self, session: AgentSession, *, source_id: str) -> tuple[list[TodoItem], int]:
key = f"todos:{source_id}:{session.session_id}"
raw = await self._redis.get(key)
if raw is None:
return [], 1
import json
payload = json.loads(raw)
items = [TodoItem.from_dict(i) for i in payload.get("items", [])]
next_id = payload.get("next_id", 1)
return items, next_id
async def save_state(
self, session: AgentSession, items: list[TodoItem], *, next_id: int, source_id: str
) -> None:
import json
key = f"todos:{source_id}:{session.session_id}"
payload = json.dumps({
"items": [i.to_dict(exclude_none=False) for i in items],
"next_id": next_id,
})
await self._redis.set(key, payload)

MemoryContextProvider — durable long-term memory

Section titled “MemoryContextProvider — durable long-term memory”

MemoryContextProvider gives agents cross-session recall. It automatically extracts durable facts from transcripts after each session and injects the most relevant topics at the start of future sessions — the agent accumulates knowledge without keeping entire conversation histories in the context window.

It is a HistoryProvider (subtype of ContextProvider) and handles both history persistence and memory extraction in a single provider.

  1. Injection — at before_run, the provider loads MEMORY.md (a keyword-indexed pointer list) and selects the most relevant topic files based on the current conversation. It prepends those as context along with a configurable number of recent turns.
  2. Extraction — at after_run, the provider saves the new turn to a transcript file. When the extraction threshold is met an LLM summarises new durable facts into topic files and updates the index.
  3. Consolidation — periodically (default: every 24 hours, after at least 5 sessions) a consolidation pass merges stale or duplicate topic files to keep the index compact.

MemoryFileStore partitions memory by owner. Set session.state[owner_state_key] before the first run() call.

import asyncio
from datetime import timedelta
from agent_framework import Agent, MemoryContextProvider, MemoryFileStore
from agent_framework.openai import OpenAIChatClient
client = OpenAIChatClient()
store = MemoryFileStore(
base_path="./memory",
owner_state_key="user_id", # session.state["user_id"] partitions per user
)
memory = MemoryContextProvider(
store=store,
recent_turns=2, # inject the 2 most recent conversation turns
selection_limit=3, # load at most 3 topic files per session
max_extractions=5, # extract at most 5 facts per session
consolidation_interval=timedelta(hours=24),
consolidation_min_sessions=5,
)
agent = Agent(
client=client,
instructions="You are a personal assistant with long-term memory.",
context_providers=[memory],
)
async def main() -> None:
# Session 1 — agent learns a preference
s1 = agent.create_session(session_id="user-42-s1")
s1.state["user_id"] = "user-42" # required — drives per-user file partitioning
await agent.run("I prefer concise bullet-point answers.", session=s1)
# Session 2 — preference is recalled from the topic store
s2 = agent.create_session(session_id="user-42-s2")
s2.state["user_id"] = "user-42"
r = await agent.run("Summarise the benefits of asyncio.", session=s2)
print(r.text) # likely uses bullet points — remembered from session 1
asyncio.run(main())

Every distinct owner_state_key value gets its own subtree under base_path. Two users share a single agent and store instance with no cross-contamination:

async def handle_request(user_id: str, message: str) -> str:
session = agent.create_session()
session.state["user_id"] = user_id # → ./memory/memory/<user_id>/memory/MEMORY.md
return (await agent.run(message, session=session)).text

The consolidation pass summarises and merges topics with an LLM call. Pass consolidation_client= to use a faster or cheaper model for that background task without affecting the main agent’s model:

from agent_framework.openai import OpenAIChatClient
main_client = OpenAIChatClient(model="gpt-6.1-sol")
cheap_client = OpenAIChatClient(model="gpt-6-luna")
memory = MemoryContextProvider(
store=store,
consolidation_client=cheap_client, # only used during topic consolidation
)
agent = Agent(client=main_client, context_providers=[memory])

Filtering transcripts before save — history_message_filter

Section titled “Filtering transcripts before save — history_message_filter”

Pass a history_message_filter callback to redact or drop messages before they are written to the transcript store. The callback receives each Message and returns either a modified copy or None to drop the message entirely:

import re
from agent_framework import Content, Message, MemoryContextProvider, MemoryFileStore
PII_PATTERN = re.compile(r"\b\d{3}-\d{2}-\d{4}\b") # crude SSN pattern
def redact_pii(message: Message) -> Message | None:
"""Return a copy with SSNs redacted, or None to drop the message."""
if message.role == "tool":
return None # don't keep raw tool output in transcripts
new_contents = [
Content.from_text(PII_PATTERN.sub("[REDACTED]", c.text)) if c.type == "text" and c.text else c
for c in message.contents
]
return Message(role=message.role, contents=new_contents, author_name=message.author_name)
memory = MemoryContextProvider(
store=MemoryFileStore(base_path="./memory", owner_state_key="user_id"),
history_message_filter=redact_pii,
)

Injecting recent turns alongside durable memory

Section titled “Injecting recent turns alongside durable memory”

recent_turns injects the most recent N turns from the transcript (not just the current session) as additional context. This gives the agent short-term coherence across sessions without blowing up the context window:

memory = MemoryContextProvider(
store=store,
recent_turns=3, # inject the 3 most recent turns
load_tool_turns=False, # skip tool-call turns in the recency window
)

Set load_tool_turns=False when tool-call rounds are noisy and you only want the user/assistant exchanges.

Inspecting and managing memory files directly

Section titled “Inspecting and managing memory files directly”

MemoryFileStore methods are synchronous — call them from application code (dashboards, admin scripts) without running the agent:

from agent_framework import AgentSession, MemoryFileStore
store = MemoryFileStore(base_path="./memory", owner_state_key="user_id")
session = AgentSession(session_id="admin-view")
session.state["user_id"] = "user-42"
# List all topic records for a user
topics = store.list_topics(session, source_id="memory")
for t in topics:
print(t.topic, "—", t.summary[:60])
# Fetch a specific topic (raises FileNotFoundError if this owner has no such topic)
record = store.get_topic(session, source_id="memory", topic="preferences")
print(record.to_markdown())
# Delete a stale topic
store.delete_topic(session, source_id="memory", topic="old-project-x")
# Rebuild the MEMORY.md index after manual edits
store.rebuild_index(session, source_id="memory")

Subclass MemoryStore to back memory in any storage system — a database, blob storage, or vector DB. All abstract methods are synchronous (the provider wraps them in asyncio.to_thread internally):

from agent_framework import AgentSession, MemoryFileStore, MemoryIndexEntry, MemoryStore, MemoryTopicRecord
from typing import Any
from collections.abc import Mapping
from pathlib import Path
class InMemoryMemoryStore(MemoryStore):
"""Ephemeral in-memory backend — useful for tests."""
def __init__(self, owner_state_key: str) -> None:
self._owner_state_key = owner_state_key
self._topics: dict[str, dict[str, MemoryTopicRecord]] = {} # owner → topic → record
self._state: dict[str, dict[str, Any]] = {}
def get_owner_id(self, session: AgentSession) -> str | None:
return session.state.get(self._owner_state_key)
def _owner(self, session: AgentSession) -> str:
oid = self.get_owner_id(session)
if oid is None:
raise RuntimeError(f"session.state[{self._owner_state_key!r}] must be set")
return str(oid)
def export_provider_state(self, session: AgentSession) -> dict[str, Any]:
return {}
def import_provider_state(self, session: AgentSession, *, state: Mapping[str, Any]) -> None:
pass
def list_topics(self, session: AgentSession, *, source_id: str) -> list[MemoryTopicRecord]:
return list(self._topics.get(self._owner(session), {}).values())
def get_topic(self, session: AgentSession, *, source_id: str, topic: str) -> MemoryTopicRecord:
owner_topics = self._topics.get(self._owner(session), {})
if topic not in owner_topics:
raise FileNotFoundError(f"No memory topic named {topic!r}") # same contract as MemoryFileStore
return owner_topics[topic]
def write_topic(self, session: AgentSession, record: MemoryTopicRecord, *, source_id: str) -> None:
self._topics.setdefault(self._owner(session), {})[record.topic] = record
def delete_topic(self, session: AgentSession, *, source_id: str, topic: str) -> None:
self._topics.get(self._owner(session), {}).pop(topic, None)
def rebuild_index(self, session: AgentSession, *, source_id: str, line_limit: int = 200, line_length: int = 150) -> list[MemoryIndexEntry]:
return [] # index is implicit in list_topics for this backend
def get_index_text(self, session: AgentSession, *, source_id: str, line_limit: int = 200, line_length: int = 150, index_entries=None) -> str:
topics = self.list_topics(session, source_id=source_id)
return "\n".join(f"- {t.topic}: {t.summary[:80]}" for t in topics)
def read_state(self, session: AgentSession, *, source_id: str) -> dict[str, Any]:
return self._state.get(self._owner(session), {})
def write_state(self, session: AgentSession, state: Mapping[str, Any], *, source_id: str) -> None:
self._state[self._owner(session)] = dict(state)
def get_transcripts_directory(self, session: AgentSession, *, source_id: str) -> Path:
raise NotImplementedError("In-memory store does not support transcript directories")
def search_transcripts(
self,
session: AgentSession,
*,
source_id: str,
query: str,
session_id: str | None = None,
limit: int = 20,
) -> list[dict[str, Any]]:
return []
# Wire up like MemoryFileStore
memory = MemoryContextProvider(store=InMemoryMemoryStore(owner_state_key="user_id"))
agent = Agent(client=client, context_providers=[memory])

MemoryContextProvider injects 6 tools that the agent can call at any time to manage its own memory. Your application code does not need to wire these up — the provider handles it automatically:

Tool namePurpose
list_memory_topics()List all known topic names and their summaries
read_memory_topic(topic)Retrieve the full content of one topic file
write_memory(topic, memory)Add or update a fact in a specific topic
delete_memory_topic(topic)Remove a topic file entirely
search_memory_transcripts(query, session_id, limit)Full-text search over saved session transcripts
consolidate_memories()Manually trigger a consolidation pass now

The agent calls these autonomously — for example, searching transcripts before answering a question about past decisions, or explicitly writing a memory when the user says “remember this for next time.” No prompt engineering beyond the default context_prompt is needed to activate them.

MemoryContextProvider constructor reference

Section titled “MemoryContextProvider constructor reference”
MemoryContextProvider(
recent_turns: int = 0, # inject last N turns from transcript into context
load_tool_turns: bool = True, # include tool-call turns in the recency window
*,
store: MemoryStore, # required — MemoryFileStore or custom
source_id: str = "memory", # partition key; change when stacking multiple providers
context_prompt: str | None = None, # override "## Memory\n..." header
index_line_limit: int = 200, # max pointer lines in MEMORY.md
index_line_length: int = 150, # max chars per pointer line
selection_limit: int = 3, # max topic files loaded per session
max_extractions: int = 5, # max memory items extracted per session
consolidation_interval: timedelta = timedelta(hours=24),
consolidation_min_sessions: int = 5, # require N sessions before consolidation runs
extraction_prompt: str | None = None, # override LLM extraction prompt
consolidation_prompt: str | None = None, # override LLM consolidation prompt
consolidation_client: SupportsChatGetResponse | None = None, # cheaper model for consolidation
history_message_filter: Callable[[Message], Message | None] | None = None,
history_dumps: Callable | None = None, # deprecated: custom transcript serialiser
history_loads: Callable | None = None, # deprecated: custom transcript deserialiser
)
base_path/
<source_id>/ ← "memory" by default (the provider's source_id)
<owner_id>/ ← session.state[owner_state_key]
memory/ ← kind=
MEMORY.md ← keyword-indexed topic pointer list
topics/
preferences.md ← one file per extracted topic
coding-style.md
transcripts/
<session_id>.jsonl ← conversation transcript per session
state.json ← maintenance state (last extraction, consolidation timestamps)

Customise directory names at construction time:

store = MemoryFileStore(
base_path="./data",
owner_state_key="tenant_id",
kind="agent-memory", # → ./data/memory/<tenant_id>/agent-memory/
index_file_name="index.md",
topics_directory_name="knowledge",
transcripts_directory_name="logs",
state_file_name="meta.json",
)

FileMemoryProvider — session-scoped scratch files

Section titled “FileMemoryProvider — session-scoped scratch files”

FileMemoryProvider gives the agent a small file system it can use as working memory: park a large API response, a research note or a draft plan in a file and read it back later, instead of keeping everything in the conversation. It registers seven tools (file_memory_write, file_memory_read, file_memory_delete, file_memory_ls, file_memory_grep, file_memory_replace, file_memory_replace_lines) and injects a memories.md index (file names plus the description the agent gave each file, capped at 50 entries) into every turn, so the model knows what it has stored.

FileMemoryProvider(store: AgentFileStore, *, source_id="file_memory",
scope: str | None = None, instructions: str | None = None)
  • Isolation. With scope=None each session gets its own folder, derived from session_id. Pass scope="user-alice" to share one folder across all of that user’s sessions. The scope is an opaque key mapped to a single folder, not a path.
  • Flat namespace. File names can’t contain path separators ("plan.md" is fine, "notes/plan.md" is rejected).
  • Concurrency. Writes, deletes and index rebuilds are serialised through a per-provider asyncio.Lock.
import asyncio
from agent_framework import Agent, FileMemoryProvider, FileSystemAgentFileStore
from agent_framework.openai import OpenAIChatClient
async def main() -> None:
# Disk-backed; every session for user "alice" shares the same folder.
memory = FileMemoryProvider(
store=FileSystemAgentFileStore(root_directory="./agent_memory"),
scope="user-alice",
)
agent = Agent(
client=OpenAIChatClient(),
instructions=(
"You are a personal assistant. Store anything worth remembering in a "
"memory file with a short description; use file_memory_grep before asking the user."
),
context_providers=[memory],
)
await agent.run("I prefer dark mode. Remember that.", session=agent.create_session())
# A different session with the same scope sees the same files.
result = await agent.run("Do I have any stored preferences?", session=agent.create_session())
print(result.text)
asyncio.run(main())

Use InMemoryAgentFileStore() instead of FileSystemAgentFileStore in tests.


FileAccessProvider is the counterpart for shared, persistent files: a workspace the agent reads and edits, such as a repo checkout, a folder of reports or a knowledge base other processes also write to. It exposes eight tools: the read-only file_access_read, file_access_read_lines, file_access_ls and file_access_grep, and the write tools file_access_write, file_access_delete, file_access_replace and file_access_replace_lines.

FileAccessProvider(
store: AgentFileStore,
*,
source_id: str = "file_access",
instructions: str | None = None,
disable_write_tools: bool = False, # advertise only the read-only tools
disable_readonly_tool_approval: bool = False, # read-only tools run without approval
disable_write_tool_approval: bool = False, # write tools run without approval
session_scoped: bool = False, # confine each session to its own folder
scope: str | None = None, # or a named folder (user / tenant id)
)

Every tool defaults to approval_mode="always_require", so either relax that with the two disable_*_approval flags or pair the provider with ToolApprovalMiddleware and one of the two static rule callbacks, FileAccessProvider.read_only_tools_auto_approval_rule and FileAccessProvider.all_tools_auto_approval_rule. They are (function_call) -> bool callables, so pass them without calling them. By default the store is shared by every session. session_scoped=True gives each session its own folder, and a non-empty scope shares one folder across sessions; both behave like FileMemoryProvider’s isolation.

import asyncio
from agent_framework import Agent, FileAccessProvider, InMemoryAgentFileStore, ToolApprovalMiddleware
from agent_framework.openai import OpenAIChatClient
async def main() -> None:
store = InMemoryAgentFileStore()
await store.write("notes.txt", "Q3 budget review: travel spend is 12% over plan.")
agent = Agent(
client=OpenAIChatClient(),
instructions="You can read and edit the team's notes.",
context_providers=[FileAccessProvider(store)],
# Reads run straight away; writes still come back as approval requests.
middleware=[ToolApprovalMiddleware(
auto_approval_rules=[FileAccessProvider.read_only_tools_auto_approval_rule],
)],
)
result = await agent.run("Summarise notes.txt.", session=agent.create_session())
print(result.text)
asyncio.run(main())

Both providers sit on the AgentFileStore ABC: write(path, content, *, overwrite=True), read(path) -> str | None, delete(path) -> bool, list_children(directory="") and search(pattern, *, glob=None, base_dir=""), all async. Paths are always relative: implementations reject .. traversal, and overwrite=False is an atomic exclusive create.

StoreNotes
InMemoryAgentFileStore()Dict-backed, case-insensitive keys, one asyncio.Lock. For tests.
FileSystemAgentFileStore(root_directory)Disk-backed under root_directory (created lazily). Rejects symlinks (O_NOFOLLOW on POSIX).

Subclass AgentFileStore to put agent files in blob storage or a database.


BackgroundAgentsProvider — delegate to concurrent sub-agents

Section titled “BackgroundAgentsProvider — delegate to concurrent sub-agents”

BackgroundAgentsProvider lets a parent agent hand work to named sub-agents that run concurrently, each in its own session, without blocking on them. The parent gets six tools:

ToolPurpose
background_agents_start_taskStart a task on a named agent; returns a task id
background_agents_wait_for_first_completionBlock until the first of several tasks finishes (capped by wait_timeout_seconds)
background_agents_get_task_resultsRead a finished task’s output
background_agents_get_all_tasksList tasks and their status (RUNNING, COMPLETED, FAILED, LOST)
background_agents_continue_taskSend a follow-up to a finished task’s session
background_agents_clear_completed_taskFree a finished task’s session
BackgroundAgentsProvider(agents: Sequence[SupportsAgentRun], *, source_id="background_agents",
instructions: str | None = None, # may contain {background_agents}
wait_timeout_seconds: int = 300)

Each agent needs a unique, non-empty name, and its description is what the parent sees when choosing. Task state is serialised into the session, but the running asyncio.Task objects live in the provider. Call await provider.release_session(session, cancel_running=True, timeout=30.0) when a parent session ends so they don’t leak. A task whose in-process handle was lost (for example after a restart) is reported as LOST.

import asyncio
from agent_framework import Agent, BackgroundAgentsProvider, InMemoryHistoryProvider
from agent_framework.openai import OpenAIChatClient
async def main() -> None:
client = OpenAIChatClient()
python_expert = Agent(client=client, name="python_expert",
description="Answers questions about Python.",
instructions="You are a Python expert. Answer concisely.")
rust_expert = Agent(client=client, name="rust_expert",
description="Answers questions about Rust.",
instructions="You are a Rust expert. Answer concisely.")
background = BackgroundAgentsProvider(agents=[python_expert, rust_expert])
coordinator = Agent(
client=client,
instructions=("Delegate each part of a multi-part question to the right background "
"agent, wait for the results, then combine them."),
context_providers=[InMemoryHistoryProvider(), background],
)
session = coordinator.create_session()
try:
result = await coordinator.run(
"Compare how Python and Rust manage memory.", session=session
)
print(result.text)
finally:
await background.release_session(session, cancel_running=True, timeout=30.0)
asyncio.run(main())

Security. Sub-agents receive text from the parent, which may include untrusted content, and their output flows back into the parent’s context. Only register agents you trust with whatever the parent might pass them.


ToolApprovalMiddleware — standing approvals

Section titled “ToolApprovalMiddleware — standing approvals”

@tool(approval_mode="always_require") turns every call into a function_approval_request that the caller must answer (see Tool approval). ToolApprovalMiddleware adds two things on top: auto-approval rules that answer some requests in code, and standing approvals (“always allow this tool”) that are remembered in the session. It needs an AgentSession and raises RuntimeError without one.

ToolApprovalMiddleware(*, source_id="tool_approval",
auto_approval_rules: Sequence[ToolApprovalRuleCallback] | None = None)

An auto-approval rule is a callable (function_call: Content) -> bool | Awaitable[bool]. To record a standing approval from a pending request, answer it with create_always_approve_tool_response(request), which allows every future call to that tool, or create_always_approve_tool_with_arguments_response(request), which allows only calls with the same arguments:

import asyncio
from agent_framework import (
Agent, Message, ToolApprovalMiddleware, create_always_approve_tool_response, tool,
)
from agent_framework.openai import OpenAIChatClient
READ_ONLY = {"list_reports"}
@tool(approval_mode="always_require")
def list_reports() -> list[str]:
"""List available reports."""
return ["q1.pdf", "q2.pdf"]
@tool(approval_mode="always_require")
def archive_report(name: str) -> str:
"""Archive a report."""
return f"archived {name}"
async def main() -> None:
agent = Agent(
client=OpenAIChatClient(),
tools=[list_reports, archive_report],
middleware=[ToolApprovalMiddleware(
auto_approval_rules=[lambda call: call.name in READ_ONLY],
)],
)
session = agent.create_session()
result = await agent.run("List the reports, then archive q1.pdf.", session=session)
for request in result.user_input_requests: # archive_report is waiting
print("Approving for the rest of the session:", request.function_call.name)
answer = create_always_approve_tool_response(request, reason="operator approved")
result = await agent.run(Message(role="user", contents=[answer]), session=session)
print(result.text)
asyncio.run(main())

Security. Rules and standing approvals match by tool name, and they live in the session, not on the agent. If you reuse a session with a rebuilt agent or a changed tool set (MCP servers especially), a different tool with the same name inherits the approval. Re-check standing approvals before handing an old session to a new tool set.


AgentLoopMiddleware — keep going until the task is done

Section titled “AgentLoopMiddleware — keep going until the task is done”

AgentLoopMiddleware re-runs the agent after each response until a should_continue predicate says stop, or max_iterations is hit. It’s the harness’s answer to “the model stopped halfway”.

AgentLoopMiddleware(
should_continue, # async (**loop_kwargs) -> bool | tuple[bool, str | None]
*,
max_iterations: int | None = 10,
next_message=None, # builds the next user turn; default is a "continue" nudge
record_feedback=None, # appends a line to the progress log after each iteration
inject_progress: bool = True, # feed the progress log back into each iteration
fresh_context: bool = False, # restart each iteration from the original request
return_final_only: bool = False, # return only the last iteration's response
additional_instructions: str | None = None,
)

should_continue and next_message receive keyword arguments: iteration, last_result, messages, original_messages, session, agent, progress and feedback. Return (False, reason) from should_continue to stop with a rationale. With fresh_context=True the session is restored to its pre-loop snapshot between iterations, so only the progress log carries over.

from agent_framework import Agent, AgentLoopMiddleware, AgentResponse
from agent_framework.openai import OpenAIChatClient
async def should_continue(*, iteration: int, last_result: AgentResponse, **_) -> tuple[bool, str | None]:
if "FINAL ANSWER" in last_result.text:
return False, "answered"
return True, f"Iteration {iteration} did not finish; keep going."
agent = Agent(
client=OpenAIChatClient(),
instructions="Work step by step. End with 'FINAL ANSWER: ...' when done.",
middleware=[AgentLoopMiddleware(should_continue, max_iterations=5, return_final_only=True)],
)

Two other ways to build the stop condition:

  • LLM judge. AgentLoopMiddleware.with_judge(judge_client, criteria=[...], max_iterations=5) asks a second model for a structured JudgeVerdict(answered: bool, reasoning: str) after every iteration, and feeds the reasoning back as the next prompt. The judge sees the request and every answer, so point it at a trusted endpoint.
  • Ready-made predicates. todos_remaining(looping_modes=None) keeps looping while the agent’s TodoProvider has open items, and background_tasks_running() keeps looping while BackgroundAgentsProvider tasks are still running. Pair them with next_message=todos_remaining_message / background_tasks_running_message. create_harness_agent(...) wires all of the harness providers plus this loop in one call (next section).

create_harness_agent — everything wired together

Section titled “create_harness_agent — everything wired together”

create_harness_agent(client, ...) returns an ordinary Agent with function invocation, per-call history persistence, compaction (when you give it token budgets), TodoProvider, AgentModeProvider, FileMemoryProvider, SkillsProvider, standing tool approvals and OpenTelemetry already configured. Each piece can be switched off (disable_todo=True, disable_mode=True, disable_file_memory=True, disable_compaction=True, disable_web_search=True) or replaced (todo_provider=, mode_provider=, history_provider=, skills_provider=).

from agent_framework import create_harness_agent, todos_remaining, todos_remaining_message
from agent_framework.openai import OpenAIChatClient
agent = create_harness_agent(
OpenAIChatClient(model="gpt-6.1-sol"),
name="research-agent",
agent_instructions="Focus on primary sources.",
max_context_window_tokens=200_000, # enables context-window compaction
max_output_tokens=32_000,
skills_paths=["./skills"],
loop_should_continue=todos_remaining(), # keep going while todos are open
loop_next_message=todos_remaining_message,
loop_max_iterations=10,
)
session = agent.create_session()
response = await agent.run("Compare three heat-pump designs and write a summary.", session=session)

loop_return_final_only=True (added in 1.26.0, default False) makes a non-streaming agent.run() return only the final loop iteration’s response instead of every iteration’s messages. Streaming behaviour is unchanged.

The function itself is stable, but some features it can switch on are experimental and emit an ExperimentalWarning when used: background agents (background_agents=), file access (file_access_store=), looping (loop_should_continue=) and shell tools (shell_executor=, from the pre-release agent-framework-tools package).


Class / helperImportNotes
TodoProvideragent_frameworkContextProvider; injects 5 tools + instructions
TodoItemagent_frameworkDataclass: id, title, description, is_complete
TodoInputagent_framework._harness._todoTool argument shape for todos_add
TodoSessionStoreagent_frameworkIn-memory store; default for TodoProvider
TodoFileStoreagent_frameworkFile-backed; owner_state_key for multi-user
AgentModeProvideragent_frameworkContextProvider; injects mode_get/mode_set + instructions
get_agent_modeagent_frameworkRead current mode from AgentSession.state
set_agent_modeagent_frameworkWrite mode externally; triggers notification on next run()
MemoryContextProvideragent_frameworkHistoryProvider; long-term memory via extraction + injection
MemoryFileStoreagent_frameworkFile-backed memory store; owner_state_key for multi-user
MemoryStoreagent_frameworkAbstract base — subclass for custom backends
MemoryIndexEntryagent_frameworkOne line in MEMORY.md; topic, slug, summary, updated_at
MemoryTopicRecordagent_frameworkOne topic file; topic, memories list, summary, updated_at
DEFAULT_TODO_SOURCE_IDagent_framework"todo" — the default source_id for TodoProvider
DEFAULT_MODE_SOURCE_IDagent_framework"agent_mode" — the default source_id for AgentModeProvider
DEFAULT_MEMORY_SOURCE_IDagent_framework"memory" — the default source_id for MemoryContextProvider
FileMemoryProvideragent_frameworkContextProvider; 7 file_memory_* tools, per-session or scope= folder
FileAccessProvideragent_frameworkContextProvider; 8 file_access_* tools over a shared store
AgentFileStore / InMemoryAgentFileStore / FileSystemAgentFileStoreagent_frameworkStorage behind the two file providers
BackgroundAgentsProvideragent_frameworkContextProvider; 6 background_agents_* tools; call release_session() when done
ToolApprovalMiddlewareagent_frameworkAuto-approval rules + standing approvals; needs an AgentSession
create_always_approve_tool_response / ..._with_arguments_responseagent_frameworkAnswer an approval request with a standing rule
AgentLoopMiddlewareagent_frameworkLoop until should_continue is false; .with_judge() for an LLM judge
todos_remaining / background_tasks_runningagent_frameworkReady-made should_continue predicates for the loop
DateVersionChanges
2026-11-161.26.0Marked MemoryContextProvider, MemoryFileStore and MemoryStore as deprecated (removal after 2026-12-31) and pointed to FileMemoryProvider. Documented loop_return_final_only on create_harness_agent.
2026-10-241.22.0Corrected the TodoFileStore and MemoryFileStore directory layouts (the provider’s source_id is part of the path and file name) and the history_message_filter example (Message is not a dataclass and its contents are Content objects); marked history_dumps / history_loads deprecated.