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,AgentModeProviderand theget_agent_mode/set_agent_modehelpers graduated from experimental in 1.12.0.MemoryContextProvider,MemoryStore/MemoryFileStore,TodoFileStore,FileAccessProvider,BackgroundAgentsProviderandAgentLoopMiddlewareare still markedExperimentalFeature.HARNESSand emit anExperimentalWarningon first use; they may change between minor releases.Deprecation (1.26.0).
MemoryContextProvider,MemoryFileStore,MemoryStore,MemoryIndexEntryandMemoryTopicRecordare deprecated and will be removed after 31 December 2026. They still import and read existing memories, but creating aMemoryFileStoreorMemoryContextProvider, or subclassingMemoryStore, now emits aDeprecationWarning. For new work useFileMemoryProviderwith aFileSystemAgentFileStore. 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-framework1.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 / Helper | What it adds to the agent |
|---|---|
TodoProvider | Five tools (todos_add, todos_complete, todos_remove, todos_get_remaining, todos_get_all) + instructions for autonomous task tracking |
AgentModeProvider | Two tools (mode_get, mode_set) + instructions for operating in distinct modes (plan / execute, or any custom set) |
get_agent_mode / set_agent_mode | External helpers to read and flip the mode from application code without waiting for the agent to call mode_set |
MemoryContextProvider | Cross-session long-term memory: extracts durable facts after each session and injects relevant topics later |
FileMemoryProvider | Seven file_memory_* tools: session-scoped (or user-scoped) scratch files with a memories.md index |
FileAccessProvider | Eight file_access_* tools: read/edit a shared AgentFileStore workspace, approval-gated by default |
BackgroundAgentsProvider | Six background_agents_* tools: start sub-agents concurrently, wait for and collect their results |
ToolApprovalMiddleware | Auto-approval rules and “always allow” standing approvals stored in the session |
AgentLoopMiddleware | Re-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 — autonomous task tracking
Section titled “TodoProvider — autonomous task tracking”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.
Quickstart — in-session todos
Section titled “Quickstart — in-session todos”import asynciofrom agent_framework import Agent, TodoProviderfrom 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.
TodoItem dataclass
Section titled “TodoItem dataclass”Every todo the agent creates becomes a TodoItem. The fields:
| Field | Type | Description |
|---|---|---|
id | int | Auto-assigned integer ID. Use this in todos_complete([id]) and todos_remove([id]). |
title | str | Short task description (non-empty, stripped). |
description | str | None | Optional longer description. |
is_complete | bool | True 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 == itemTodoInput — 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"}Inspecting todos from application code
Section titled “Inspecting todos from application code”Read the task list without going through the agent. This is useful for dashboards, webhook handlers, and CI status checks:
import asynciofrom 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 asynciofrom agent_framework import Agent, AgentSession, TodoFileStore, TodoProviderfrom 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 asynciofrom agent_framework import Agent, AgentSession, TodoFileStore, TodoProviderfrom agent_framework.openai import OpenAIChatClient
# Todos written to ./todos/<user_id>/todos/<session_id>/todos.todo.jsonstore = 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())Custom instructions
Section titled “Custom instructions”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, TodoProviderfrom 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 constructor reference
Section titled “TodoProvider constructor reference”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 asynciofrom agent_framework import Agent, AgentModeProviderfrom 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.
Custom mode set
Section titled “Custom mode set”Define your own mode names and descriptions when the defaults don’t fit. Mode names come from the mode_instructions mapping keys:
import asynciofrom agent_framework import Agent, AgentModeProviderfrom 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 asynciofrom agent_framework import Agent, AgentModeProvider, AgentSession, get_agent_mode, set_agent_modefrom 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 constructor reference
Section titled “AgentModeProvider constructor reference”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 asynciofrom agent_framework import Agent, AgentModeProvider, AgentSession, TodoProvider, set_agent_modefrom 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())Stacking with file persistence
Section titled “Stacking with file persistence”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 asynciofrom 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:
AgentModeProviderstores mode inAgentSession.state. If you need mode to survive across processes, persistsession.stateyourself — for example, write it to your database after each turn and reload it when you create the next session withsession.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 asynciofrom agent_framework import Agent, AgentModeProvider, AgentSession, TodoProvider, set_agent_modefrom 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())Reference — TodoStore protocol
Section titled “Reference — TodoStore protocol”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.
How it works
Section titled “How it works”- Injection — at
before_run, the provider loadsMEMORY.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. - 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. - 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.
Quickstart
Section titled “Quickstart”MemoryFileStore partitions memory by owner. Set session.state[owner_state_key] before the first run() call.
import asynciofrom datetime import timedeltafrom agent_framework import Agent, MemoryContextProvider, MemoryFileStorefrom 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())Multi-user isolation
Section titled “Multi-user isolation”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)).textUsing a cheaper model for consolidation
Section titled “Using a cheaper model for consolidation”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 usertopics = 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 topicstore.delete_topic(session, source_id="memory", topic="old-project-x")
# Rebuild the MEMORY.md index after manual editsstore.rebuild_index(session, source_id="memory")Custom MemoryStore backend
Section titled “Custom MemoryStore backend”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, MemoryTopicRecordfrom typing import Anyfrom collections.abc import Mappingfrom 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 MemoryFileStorememory = MemoryContextProvider(store=InMemoryMemoryStore(owner_state_key="user_id"))agent = Agent(client=client, context_providers=[memory])Tools injected into the agent
Section titled “Tools injected into the agent”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 name | Purpose |
|---|---|
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)MemoryFileStore directory layout
Section titled “MemoryFileStore directory layout”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=Noneeach session gets its own folder, derived fromsession_id. Passscope="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 asynciofrom agent_framework import Agent, FileMemoryProvider, FileSystemAgentFileStorefrom 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 — a shared workspace
Section titled “FileAccessProvider — a shared workspace”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 asynciofrom agent_framework import Agent, FileAccessProvider, InMemoryAgentFileStore, ToolApprovalMiddlewarefrom 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())AgentFileStore backends
Section titled “AgentFileStore backends”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.
| Store | Notes |
|---|---|
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:
| Tool | Purpose |
|---|---|
background_agents_start_task | Start a task on a named agent; returns a task id |
background_agents_wait_for_first_completion | Block until the first of several tasks finishes (capped by wait_timeout_seconds) |
background_agents_get_task_results | Read a finished task’s output |
background_agents_get_all_tasks | List tasks and their status (RUNNING, COMPLETED, FAILED, LOST) |
background_agents_continue_task | Send a follow-up to a finished task’s session |
background_agents_clear_completed_task | Free 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 asynciofrom agent_framework import Agent, BackgroundAgentsProvider, InMemoryHistoryProviderfrom 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 asynciofrom 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, AgentResponsefrom 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 structuredJudgeVerdict(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’sTodoProviderhas open items, andbackground_tasks_running()keeps looping whileBackgroundAgentsProvidertasks are still running. Pair them withnext_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_messagefrom 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).
Quick-reference table
Section titled “Quick-reference table”| Class / helper | Import | Notes |
|---|---|---|
TodoProvider | agent_framework | ContextProvider; injects 5 tools + instructions |
TodoItem | agent_framework | Dataclass: id, title, description, is_complete |
TodoInput | agent_framework._harness._todo | Tool argument shape for todos_add |
TodoSessionStore | agent_framework | In-memory store; default for TodoProvider |
TodoFileStore | agent_framework | File-backed; owner_state_key for multi-user |
AgentModeProvider | agent_framework | ContextProvider; injects mode_get/mode_set + instructions |
get_agent_mode | agent_framework | Read current mode from AgentSession.state |
set_agent_mode | agent_framework | Write mode externally; triggers notification on next run() |
MemoryContextProvider | agent_framework | HistoryProvider; long-term memory via extraction + injection |
MemoryFileStore | agent_framework | File-backed memory store; owner_state_key for multi-user |
MemoryStore | agent_framework | Abstract base — subclass for custom backends |
MemoryIndexEntry | agent_framework | One line in MEMORY.md; topic, slug, summary, updated_at |
MemoryTopicRecord | agent_framework | One topic file; topic, memories list, summary, updated_at |
DEFAULT_TODO_SOURCE_ID | agent_framework | "todo" — the default source_id for TodoProvider |
DEFAULT_MODE_SOURCE_ID | agent_framework | "agent_mode" — the default source_id for AgentModeProvider |
DEFAULT_MEMORY_SOURCE_ID | agent_framework | "memory" — the default source_id for MemoryContextProvider |
FileMemoryProvider | agent_framework | ContextProvider; 7 file_memory_* tools, per-session or scope= folder |
FileAccessProvider | agent_framework | ContextProvider; 8 file_access_* tools over a shared store |
AgentFileStore / InMemoryAgentFileStore / FileSystemAgentFileStore | agent_framework | Storage behind the two file providers |
BackgroundAgentsProvider | agent_framework | ContextProvider; 6 background_agents_* tools; call release_session() when done |
ToolApprovalMiddleware | agent_framework | Auto-approval rules + standing approvals; needs an AgentSession |
create_always_approve_tool_response / ..._with_arguments_response | agent_framework | Answer an approval request with a standing rule |
AgentLoopMiddleware | agent_framework | Loop until should_continue is false; .with_judge() for an LLM judge |
todos_remaining / background_tasks_running | agent_framework | Ready-made should_continue predicates for the loop |
Revision history
Section titled “Revision history”| Date | Version | Changes |
|---|---|---|
| 2026-11-16 | 1.26.0 | Marked 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-24 | 1.22.0 | Corrected 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. |