Microsoft Agent Framework (Python) — Sessions & history
AgentSession, HistoryProvider, InMemoryHistoryProvider, FileHistoryProvider, VectorStoreHistoryProvider, FileSessionStore, register_state_type, multi-provider audit logs, and serializing sessions across processes.
A session is one logical conversation with an agent. The framework splits responsibilities cleanly:
| Object | Owns | Lifetime |
|---|---|---|
AgentSession | session_id, optional service_session_id, mutable state: dict | Per conversation |
HistoryProvider (subclass) | The actual messages — read/write to disk, Redis, in-memory, … | Process-long, attached to the agent |
Agent | Orchestrates providers, threads state through them on every run | Process-long |
This page walks the moving parts in agent_framework._sessions and the patterns that fall out of them. AgentSession, HistoryProvider, InMemoryHistoryProvider and register_state_type are stable. FileHistoryProvider is experimental (ExperimentalFeature.FILE_HISTORY) and emits an ExperimentalWarning on first use, as do FileSessionStore (SESSION_STORE) and VectorStoreHistoryProvider (VECTOR_STORES). Examples are checked against agent-framework 1.26.0 (2026-11-19).
import asynciofrom agent_framework import Agent, FileHistoryProviderfrom agent_framework.openai import OpenAIChatClient
async def main() -> None: agent = Agent( client=OpenAIChatClient(), instructions="You are a helpful assistant.", context_providers=[FileHistoryProvider(storage_path="./sessions")], )
session = agent.create_session(session_id="user-42-conversation-1")
# Turn 1 r1 = await agent.run("Remember that my favourite colour is teal.", session=session)
# Turn 2 — history is loaded automatically because the same provider is on the agent r2 = await agent.run("What is my favourite colour?", session=session) print(r2.text)
asyncio.run(main())The provider lives on the agent. The session is just an id + scratchpad — pass it to every run() to opt into persistence for that conversation.
Where history lives when you configure nothing
Section titled “Where history lives when you configure nothing”If you pass a session but configure no history provider, what happens depends on the chat client:
| Client | STORES_BY_DEFAULT | History lives |
|---|---|---|
OpenAIChatClient (Responses API), FoundryChatClient | True | On the service. The response id is written to session.service_session_id and sent back on the next turn; nothing is kept locally. |
OpenAIChatCompletionClient, AnthropicClient, OllamaChatClient, BedrockChatClient, GeminiChatClient, MistralChatClient, FoundryLocalClient | False | In session.state: the agent adds an InMemoryHistoryProvider for you. |
store in the run or agent options overrides the client’s default: default_options={"store": False} on an OpenAIChatClient agent keeps history local (and the auto-added InMemoryHistoryProvider takes over), while store=True forces service-side storage. Any history provider you configure with load_messages=True replaces the automatic one.
Service-side history is convenient, but the conversation then exists only at the provider: you cannot inspect, compact or move it, and it is subject to the provider’s retention rules. Configure a history provider when you need any of that.
AgentSession in one screen
Section titled “AgentSession in one screen”from agent_framework import AgentSession
# Auto-generated UUIDsession = AgentSession()print(session.session_id) # → 'd4f0...e2'
# Stable ids let you correlate across servicessession = AgentSession(session_id="customer-9281")
# `state` is a free-form dict shared with every provider for this sessionsession.state["preferred_currency"] = "EUR"session.state["last_seen_at"] = "2026-04-30T08:42:00Z"Two attributes you may set yourself:
session_id— your stable correlation id (defaults to a UUID when omitted).service_session_id— a service-managed id (e.g. an OpenAI Responses thread id). Set it when the provider owns the conversation server-side and you only want to keep a pointer.
session.state is the cross-provider scratchpad. Each provider keeps its data under its own source_id key; for example InMemoryHistoryProvider stores the transcript in session.state["in_memory"]["messages"]. The framework already registers Message for round-trip serialisation; for your own classes, register them once at startup.
Storing custom types in state
Section titled “Storing custom types in state”Built-in JSON types (str, int, float, bool, None, list, dict) survive to_dict()/from_dict() automatically. For custom types, either implement to_dict/from_dict (any class) or use a Pydantic BaseModel (auto-detected).
from pydantic import BaseModelfrom agent_framework import AgentSession, register_state_type
class UserProfile(BaseModel): user_id: str plan: str org_id: str | None = None
# Register once at startup so cold-start restores work even before the model# has been serialised this process.register_state_type(UserProfile)
session = AgentSession()session.state["profile"] = UserProfile(user_id="u-42", plan="enterprise")
snapshot = session.to_dict() # safe to JSON-encoderestored = AgentSession.from_dict(snapshot)assert isinstance(restored.state["profile"], UserProfile)If you need a different identifier than the lowercase class name, pass type_id= (register_state_type(UserProfile, type_id="profile.v1")), supply encoder= / decoder= callables for a class you can’t change, or define a class method:
from agent_framework import register_state_type
class LegacyOrder: @classmethod def _get_type_identifier(cls) -> str: return "legacy.order.v2"
def to_dict(self) -> dict: ... @classmethod def from_dict(cls, d: dict) -> "LegacyOrder": ...
register_state_type(LegacyOrder)HistoryProvider — the storage seam
Section titled “HistoryProvider — the storage seam”Every persistence backend in the framework subclasses HistoryProvider and implements two coroutines:
class HistoryProvider(ContextProvider): async def get_messages(self, session_id, *, state=None, **kwargs) -> list[Message]: ... async def save_messages(self, session_id, messages, *, state=None, **kwargs) -> None: ...The base class wires before_run/after_run so subclasses do nothing else. The framework ships two:
| Class | Storage | Use when |
|---|---|---|
InMemoryHistoryProvider | session.state["in_memory"]["messages"] | Single-process bots, tests, conversations you serialise with the session |
FileHistoryProvider | One JSONL file per session_id under a directory | Single-host deployments, durable across restarts |
Beta packages add RedisHistoryProvider (agent-framework-redis) and CosmosHistoryProvider (agent-framework-azure-cosmos) with the same interface; see packaged backends below. VectorStoreHistoryProvider (in core) works with any vector store connector.
Configuration flags shared by every history provider
Section titled “Configuration flags shared by every history provider”These come straight from the constructor signature:
| Flag | Default | Effect |
|---|---|---|
load_messages | True | If False, the provider never injects past messages. Use for write-only audit logs. |
store_inputs | True | Whether new user messages get persisted. |
store_outputs | True | Whether assistant responses get persisted. |
store_context_messages | False | Whether messages added by other context providers (skills, RAG, …) get persisted. |
store_context_from | None | When set, only persist context from these source_ids. |
skip_excluded | False | When True, get_messages leaves out messages flagged by compaction (additional_properties["_excluded"] truthy). InMemoryHistoryProvider and FileHistoryProvider have it. |
Pair load_messages=False + store_outputs=True for an audit log, load_messages=True + store_outputs=False for read-only replay, etc.
InMemoryHistoryProvider
Section titled “InMemoryHistoryProvider”Added automatically for clients that don’t store history (see above). Messages live in session.state["in_memory"]["messages"], so they travel with session.to_dict() / from_dict().
import jsonfrom agent_framework import Agent, AgentSession, InMemoryHistoryProviderfrom agent_framework.openai import OpenAIChatClient
history = InMemoryHistoryProvider()
agent = Agent( client=OpenAIChatClient(), instructions="You are a helpful assistant.", context_providers=[history], default_options={"store": False}, # Responses API: don't also keep the conversation server-side)
session = AgentSession()await agent.run("Remember the launch is on 2026-05-12.", session=session)
# Persist the *whole* session somewhere — Redis, a request envelope, anywhere.blob = json.dumps(session.to_dict())print(len(blob), "bytes")
# Later, in a different process:restored = AgentSession.from_dict(json.loads(blob))r = await agent.run("When is the launch?", session=restored)print(r.text)Because the messages live inside the session dict, you don’t need a separate datastore — your existing request/session store handles it. This is the right default for serverless and stateless front-ends where you already have a session cookie or token.
Skipping compacted messages on read
Section titled “Skipping compacted messages on read”A CompactionProvider’s after_strategy rewrites the stored history after each turn by marking older messages as excluded (it keeps them, so the annotations survive). Tell the history provider to skip them on later loads:
from agent_framework import ( Agent, CompactionProvider, InMemoryHistoryProvider, SlidingWindowStrategy,)from agent_framework.openai import OpenAIChatClient
history = InMemoryHistoryProvider(skip_excluded=True)compaction = CompactionProvider(after_strategy=SlidingWindowStrategy(keep_last_groups=20))
agent = Agent( client=OpenAIChatClient(), context_providers=[history, compaction],)Without skip_excluded=True, the next turn re-loads everything compaction trimmed last turn, defeating the strategy.
after_strategy only works on history kept in session.state (it looks for session.state[history_source_id]["messages"], default "in_memory"). It has no effect on FileHistoryProvider, RedisHistoryProvider or other external stores, which never put the transcript in session.state. For those, use before_strategy, which compacts what the model sees on each turn while the stored transcript stays complete. Details are on the compaction page.
FileHistoryProvider
Section titled “FileHistoryProvider”One JSON Lines file per session_id in a single directory, one message per line, appended after each run. (serialization_format="msgpack" is also available.)
from agent_framework import Agent, FileHistoryProviderfrom agent_framework.openai import OpenAIChatClient
history = FileHistoryProvider(storage_path="./conversations") # directory; created automatically
agent = Agent( client=OpenAIChatClient(), instructions="You are a helpful assistant.", context_providers=[history],)
session = agent.create_session(session_id="customer-9281")await agent.run("Hi, I need help with order #4421.", session=session)# Writes ./conversations/customer-9281.jsonlPath-traversal protection
Section titled “Path-traversal protection”session_id flows from your application — sometimes from URL routing, sometimes from headers. FileHistoryProvider uses a plain id such as customer-9281 as the file name (customer-9281.jsonl). Any id that is not safe as a file name (path separators, .., absolute paths, Windows reserved names such as CON) is encoded instead, giving a name like ~session-f5qwe4zpobqxi2a.jsonl inside the storage directory, and the resolved path is checked against the storage root.
So agent.create_session(session_id="../etc/passwd") is safe: it lands inside storage_path. You still need OS-level filesystem permissions (the contents are plaintext unless you add encryption below), and authorisation is yours: anyone who can choose the session_id can read that conversation.
Encrypted-at-rest sessions via dumps/loads
Section titled “Encrypted-at-rest sessions via dumps/loads”Inject your own JSON serialisers to add envelope encryption, schema migration, or PII redaction:
import jsonimport osfrom cryptography.fernet import Fernetfrom agent_framework import Agent, FileHistoryProvider
key = os.environ["AGENT_HISTORY_FERNET_KEY"] # 32-byte urlsafe-b64 keycipher = Fernet(key)
def encrypt_dumps(payload: dict) -> str: # Fernet tokens are already URL-safe base64 — single line, no extra encoding required. plaintext = json.dumps(payload, ensure_ascii=False).encode("utf-8") return cipher.encrypt(plaintext).decode("ascii")
def decrypt_loads(line: str | bytes) -> dict: if isinstance(line, str): line = line.encode("ascii") return json.loads(cipher.decrypt(line).decode("utf-8"))
history = FileHistoryProvider( storage_path="./encrypted-conversations", dumps=encrypt_dumps, loads=decrypt_loads,)Two operational notes:
dumpsmust return a single-linestrorbytes(no\n/\r); otherwise the provider raisesValueError: FileHistoryProvider.dumps must return single-line JSON for JSON Lines storage.The output does not have to be JSON; any single-line representation that round-trips throughloadsto a mapping is accepted, which is what makes this encrypted-token pattern work.- Both callables must round-trip cleanly. Test with
loads(dumps(x)) == xfor a representative payload.
VectorStoreHistoryProvider — history in a vector store
Section titled “VectorStoreHistoryProvider — history in a vector store”VectorStoreHistoryProvider (experimental, added in 1.19.0) keeps the transcript in a vector collection that the provider owns, on any BaseVectorStore: InMemoryStore for tests, or a connector package in production. It works like the other history providers (load before the run, save after), and it can optionally embed every message and give the agent a search_history tool over the full transcript, even when compaction keeps only a slice in context.
from agent_framework import Agent, InMemoryStore, SlidingWindowStrategy, VectorStoreHistoryProviderfrom agent_framework.openai import OpenAIChatClient, OpenAIEmbeddingClient
history = VectorStoreHistoryProvider( InMemoryStore(), application_id="support-app", # required; isolates this app's records agent_id="support-bot", # optional tenant_id= / agent_id= narrow the scope further collection_name="chat-history-v1", # required when embedding_generator is set embedding_generator=OpenAIEmbeddingClient(model="text-embedding-3-small"), embedding_options={"dimensions": 1536}, # required with an embedding generator include_search_tool=True, # adds search_history (needs embeddings) compaction_strategy=SlidingWindowStrategy(keep_last_groups=20), # only affects what is loaded)
agent = Agent( client=OpenAIChatClient(), instructions="Use search_history to recall anything older than the recent turns.", context_providers=[history],)# await history.get_messages(session.session_id) -> full scoped transcript# await history.clear(session.session_id) -> delete itRecords are scoped by application_id + tenant_id + agent_id + source_id + session id. That stops accidental overlap but is not an authorization boundary, so use store credentials scoped to the tenant. contents_format="msgpack" stores message bodies compactly, and the store_inputs / store_outputs / store_context_messages / store_context_from flags work as they do on the other history providers. To let an agent search your domain data (not its own history), use VectorCollectionContextProvider instead.
Agent lifecycle helpers
Section titled “Agent lifecycle helpers”from agent_framework import Agent, FileHistoryProviderfrom agent_framework.openai import OpenAIChatClient
agent = Agent( client=OpenAIChatClient(), context_providers=[FileHistoryProvider(storage_path="./conv")],)
# 1. Create a fresh session — generates a UUIDsession = agent.create_session()
# 2. Create with a stable id (e.g. correlated to your app's user id)session = agent.create_session(session_id="user-42")
# 3. Bind a service-managed conversation thread (e.g. OpenAI Responses)remote = agent.get_session(service_session_id="thread_abc123")get_session(service_session_id, *, session_id=None) is the right entry point when the service owns the history (an OpenAI Responses response id or conversation id, a Foundry conversation) and you stored that id. The local session_id is just a correlation key your code uses; the actual messages stay server-side.
Multi-provider patterns
Section titled “Multi-provider patterns”A HistoryProvider is just a ContextProvider. Stack as many as you like — they run in order, share the session’s state, and can each apply different storage policies.
Primary store + write-only audit log
Section titled “Primary store + write-only audit log”Persist everything to the primary provider; mirror only inputs to the audit log.
from agent_framework import Agent, FileHistoryProviderfrom agent_framework.openai import OpenAIChatClient
primary = FileHistoryProvider(storage_path="./conversations")
audit = FileHistoryProvider( storage_path="./audit", source_id="audit", # different id so it doesn't clash with primary load_messages=False, # write-only — never re-injects past messages store_inputs=True, store_outputs=False,)
agent = Agent( client=OpenAIChatClient(), context_providers=[primary, audit],)Now ./audit/ accumulates a record of every user prompt, separate from the primary conversation store. It is plain files, so it is not tamper-evident on its own; ship it to append-only storage if it has to stand up as evidence.
Logging only specific provider sources
Section titled “Logging only specific provider sources”When you have a RAG provider, a skills provider, and a history provider, you may want to keep RAG-injected context out of the persisted history (it’s reconstituted each turn anyway):
from agent_framework import FileHistoryProvider
audit = FileHistoryProvider( storage_path="./audit", source_id="audit", load_messages=False, store_inputs=True, store_outputs=True, store_context_messages=True, store_context_from={"skills"}, # only persist context from the skills provider)Set store_context_from to whitelist source ids; leave None and set store_context_messages=True to persist every other source’s contribution.
Building your own HistoryProvider
Section titled “Building your own HistoryProvider”Two coroutines, no inheritance gymnastics. Override the storage; the base class handles the load/store flags. (The packaged agent-framework-redis already has a RedisHistoryProvider; this sketch shows the contract with a simple Redis list.)
import jsonfrom collections.abc import Sequencefrom typing import Anyfrom agent_framework import HistoryProvider, Messageimport redis.asyncio as redis
class RedisListHistoryProvider(HistoryProvider): DEFAULT_SOURCE_ID = "redis_list_history"
def __init__(self, url: str, *, ttl_seconds: int | None = None, **kwargs: Any) -> None: super().__init__(source_id=self.DEFAULT_SOURCE_ID, **kwargs) self._client = redis.from_url(url) self._ttl = ttl_seconds
def _key(self, session_id: str | None) -> str: return f"agent:history:{session_id or 'default'}"
async def get_messages(self, session_id: str | None, *, state=None, **kwargs) -> list[Message]: raw = await self._client.lrange(self._key(session_id), 0, -1) return [Message.from_dict(json.loads(item)) for item in raw]
async def save_messages( self, session_id: str | None, messages: Sequence[Message], *, state=None, **kwargs, ) -> None: if not messages: return key = self._key(session_id) pipe = self._client.pipeline() for m in messages: pipe.rpush(key, json.dumps(m.to_dict(), ensure_ascii=False)) if self._ttl: pipe.expire(key, self._ttl) await pipe.execute()That’s it. load_messages, store_inputs, store_outputs, store_context_messages all work — the base class calls your two methods at the right moments.
Packaged backends: Redis and Cosmos DB
Section titled “Packaged backends: Redis and Cosmos DB”For several workers sharing history, use a packaged provider rather than files:
from agent_framework import Agentfrom agent_framework.azure import CosmosHistoryProvider # pip install agent-framework-azure-cosmos --prefrom agent_framework.openai import OpenAIChatCompletionClientfrom agent_framework.redis import RedisHistoryProvider # pip install agent-framework-redis --prefrom azure.identity.aio import DefaultAzureCredential
redis_history = RedisHistoryProvider( redis_url="redis://localhost:6379", application_id="support-app", # with tenant_id / agent_id, scopes the keys max_messages=200, # keep only the most recent 200 messages per session)
cosmos_history = CosmosHistoryProvider( endpoint="https://<account>.documents.azure.com:443/", database_name="agents", container_name="history", credential=DefaultAzureCredential(),)
agent = Agent(client=OpenAIChatCompletionClient(), context_providers=[redis_history])Both take the same load_messages / store_* flags as the built-in providers. RedisHistoryProvider defaults to port 6380 with TLS when you give host= instead of redis_url=. The Redis package also has RedisContextProvider (RedisVL semantic recall of stored context) and RedisStore for the vector-store layer.
Upgrading
RedisContextProviderto 1.24.0: the provider now keeps scope identity (case and punctuation) exactly and rejects an index created with the old raw-scope schema. The context hashes hold the stored content itself, so export or back them up first (or make sure you can rebuild them from another source). Then delete the old context index and its hashes, let the provider create a new index, and re-ingest the content from that backup or source. This affects the context provider only, notRedisHistoryProvider.
Sessions across processes — request handlers and queues
Section titled “Sessions across processes — request handlers and queues”Stateless workers (Lambda, Cloud Run, Container Apps) need to pull the conversation in, run a turn, and push state back out. Two patterns work well.
Pattern 1 — InMemoryHistoryProvider + your existing session store
Section titled “Pattern 1 — InMemoryHistoryProvider + your existing session store”Treat the agent like a pure function. Your web framework already has a session blob; round-trip it through AgentSession.to_dict() / from_dict():
import jsonfrom fastapi import FastAPIfrom agent_framework import Agent, AgentSession, InMemoryHistoryProviderfrom agent_framework.openai import OpenAIChatClient
app = FastAPI()agent = Agent( client=OpenAIChatClient(), instructions="You are a helpful assistant.", context_providers=[InMemoryHistoryProvider()],)
@app.post("/chat")async def chat(payload: dict) -> dict: session = ( AgentSession.from_dict(json.loads(payload["session_blob"])) if payload.get("session_blob") else AgentSession() ) response = await agent.run(payload["message"], session=session) return { "reply": response.text, "session_blob": json.dumps(session.to_dict()), }The blob carries all messages plus any custom state you stored. Sign it (JWT) before returning to the client to make it tamper-evident.
Pattern 2 — Server-side history, client-side ids only
Section titled “Pattern 2 — Server-side history, client-side ids only”Use FileHistoryProvider (or Redis/Cosmos) on the server; the client only sends a stable session_id:
@app.post("/chat")async def chat(payload: dict) -> dict: session = agent.create_session(session_id=payload["session_id"]) # history is loaded by the provider response = await agent.run(payload["message"], session=session) return {"reply": response.text}Apply auth checks in the handler so users can only access sessions they own — FileHistoryProvider only protects you from path traversal, not authorisation.
Pattern 3 — persist whole session snapshots with FileSessionStore
Section titled “Pattern 3 — persist whole session snapshots with FileSessionStore”FileSessionStore (experimental) saves the complete AgentSession, including state and the messages an InMemoryHistoryProvider keeps there, as one file per session id. It’s a single-host alternative to pattern 1 when you don’t want to ship the blob to the client.
from agent_framework import Agent, AgentSession, FileSessionStore, InMemoryHistoryProviderfrom agent_framework.openai import OpenAIChatClient
store = FileSessionStore("./session_snapshots", serialization_format="json") # or "msgpack"agent = Agent(client=OpenAIChatClient(), context_providers=[InMemoryHistoryProvider()])
async def chat(session_id: str, message: str) -> str: session = await store.get(session_id) or AgentSession(session_id=session_id) response = await agent.run(message, session=session) await store.set(session_id, session) return response.textget returns None for an unknown id, and delete is a no-op when the file is missing. Session ids are validated (non-empty, at most 128 characters) and mapped to safe file names, so a hostile id can’t escape storage_path. Writes are atomic (temp file + os.replace), but concurrent writers on different hosts are last-writer-wins and files aren’t encrypted. Custom state types still need register_state_type.
Common pitfalls
Section titled “Common pitfalls”Forgetting to pass session=. Without a session, the agent runs stateless — no history, no state. Easy to miss when refactoring.
Reusing one AgentSession across users. Sessions are per-conversation. Mixing users into one session_id cross-contaminates history.
Forgetting register_state_type for cold restarts. A worker that restarts before the type has been serialised once cannot deserialise sessions that contain it. Register at module import.
Compaction without skip_excluded=True on the history provider. Compaction marks messages as excluded; if the history provider re-loads them on the next turn, you’ve gained nothing.
Expecting after_strategy to shrink a file or Redis transcript. It only rewrites history held in session.state; use before_strategy with external stores.
Assuming the Responses API client keeps history in the session. With OpenAIChatClient and FoundryChatClient, session.to_dict() holds only the service’s response id unless you set store=False or add a history provider.
Single-host JSONL across N replicas. FileHistoryProvider serialises writes with in-process thread locks, not cross-process locks. Multiple replicas writing to the same NFS volume will race. Use Redis or Cosmos for multi-host deployments.
session.state mutation outside an agent run. Providers run in before_run / after_run. Mutating state while a run is in flight is undefined behaviour — do it before/after agent.run(...).
SessionContext — per-run pipeline state
Section titled “SessionContext — per-run pipeline state”SessionContext is created fresh for each agent.run() call and threaded through every ContextProvider in order. It is the channel through which providers inject context, instructions, tools, and middleware before the model is called. You never construct one yourself — the framework creates it and passes it to before_run / after_run.
The most useful methods when writing a custom provider:
| Method | Purpose |
|---|---|
extend_messages(source, messages) | Inject context messages (e.g. RAG results, persona snippets) under a named source key (source may be the provider itself) |
extend_instructions(source_id, instructions) | Append dynamic system-prompt fragments |
extend_tools(source_id, tools) | Register extra tools for this run only |
extend_middleware(source_id, middleware) | Add per-run chat or function middleware |
get_messages(*, sources=None, exclude_sources=None, include_input=False, include_response=False) | Read back all accumulated messages |
get_middleware() | Retrieve the flat list of middleware added by all providers |
Writing a custom ContextProvider
Section titled “Writing a custom ContextProvider”Subclass ContextProvider when you need to inject context that doesn’t map cleanly to history or skills — feature flags, A/B instructions, tenant-scoped prompts, live RAG results:
import asynciofrom typing import Anyfrom agent_framework import Agent, ContextProvider, AgentSession, SessionContextfrom agent_framework import Message, Contentfrom agent_framework.openai import OpenAIChatClient
class TenantContextProvider(ContextProvider): """Injects tenant-specific instructions and a live persona snippet."""
DEFAULT_SOURCE_ID = "tenant_ctx"
def __init__(self) -> None: super().__init__(source_id=self.DEFAULT_SOURCE_ID)
async def before_run( self, *, agent: Any, session: AgentSession, context: SessionContext, state: dict[str, Any], ) -> None: tenant_id: str = session.state.get("tenant_id", "default")
# Append a dynamic system-prompt fragment context.extend_instructions( self.source_id, f"You are serving tenant '{tenant_id}'. Always address them formally.", )
# Inject a context message (appears before the user's message in the model's view) persona = await self._fetch_persona(tenant_id) context.extend_messages( self.source_id, [Message(role="system", contents=[Content.from_text(persona)])], )
async def after_run( self, *, agent: Any, session: AgentSession, context: SessionContext, state: dict[str, Any], ) -> None: # Inspect the response after the run completes. if context.response: session.state["last_response_len"] = len(context.response.text or "")
async def _fetch_persona(self, tenant_id: str) -> str: # Replace with a real DB / cache call personas = { "acme": "ACME Corp persona: formal tone, no jargon.", "default": "Standard persona: helpful and concise.", } return personas.get(tenant_id, personas["default"])
async def main() -> None: agent = Agent( client=OpenAIChatClient(), instructions="You are a helpful assistant.", context_providers=[TenantContextProvider()], )
session = agent.create_session() session.state["tenant_id"] = "acme"
response = await agent.run("Summarise our Q3 results.", session=session) print(response.text) print("response len stored:", session.state["last_response_len"])
asyncio.run(main())Injecting per-run tools from a provider
Section titled “Injecting per-run tools from a provider”extend_tools adds tools dynamically based on per-request state — useful when the tool set varies per tenant, user role, or feature flag:
from typing import Anyfrom agent_framework import Agent, ContextProvider, AgentSession, SessionContext, toolfrom agent_framework.openai import OpenAIChatClient
@tooldef search_crm(query: str) -> str: """Search the internal CRM.""" return f"CRM results for {query!r}"
@tooldef admin_wipe_data(user_id: str) -> str: """Wipe all data for a user (admin only).""" return f"Wiped data for user {user_id}"
class RoleBasedToolProvider(ContextProvider): DEFAULT_SOURCE_ID = "role_tools"
def __init__(self) -> None: super().__init__(source_id=self.DEFAULT_SOURCE_ID)
async def before_run( self, *, agent: Any, session: AgentSession, context: SessionContext, state: dict[str, Any], ) -> None: role = session.state.get("role", "user") tools = [search_crm] if role == "admin": tools.append(admin_wipe_data) context.extend_tools(self.source_id, tools)
agent = Agent( client=OpenAIChatClient(), instructions="You are a CRM assistant.", context_providers=[RoleBasedToolProvider()],)Inspecting accumulated context
Section titled “Inspecting accumulated context”Read back what all providers have contributed, useful for debugging or audit logging. SessionContext.instructions, SessionContext.tools, and SessionContext.context_messages are documented public attributes — not implementation details — and are safe to read in any provider’s after_run:
async def debug_context(agent, session): """Log every context message and instruction after the model run completes.""" from agent_framework import ContextProvider, SessionContext, AgentSession from typing import Any
class ContextDebugger(ContextProvider): def __init__(self): super().__init__(source_id="debugger")
async def before_run(self, *, agent: Any, session: AgentSession, context: SessionContext, state: dict[str, Any]): pass # other providers run first (order matters)
async def after_run(self, *, agent: Any, session: AgentSession, context: SessionContext, state: dict[str, Any]): # Runs after all providers have completed before_run AND the model has responded. all_ctx = context.get_messages(include_input=True, include_response=True) print(f" messages in context: {len(all_ctx)}") print(f" instructions added: {len(context.instructions)}") print(f" extra tools registered: {len(context.tools)}") for source, msgs in context.context_messages.items(): print(f" [{source}] → {len(msgs)} messages")Persisting after every model call
Section titled “Persisting after every model call”When require_per_service_call_history_persistence=True is set on an agent, the framework installs an internal chat middleware that saves history to the configured history providers after every model round trip, not just at the end of the outer agent.run(). This is useful for long-running agentic loops where a process crash mid-run would otherwise lose all intermediate turns. It is also required for handoff orchestrations (see the orchestration page).
from agent_framework import Agent, FileHistoryProviderfrom agent_framework.openai import OpenAIChatClient
history = FileHistoryProvider(storage_path="./conversations")
# Flush history after EVERY model call inside the tool loop, not just after the outer run.agent = Agent( client=OpenAIChatClient(), instructions="You are a research assistant.", context_providers=[history], require_per_service_call_history_persistence=True,)
session = agent.create_session(session_id="long-research-session")# Even if this crashes after 20 tool calls, the next run will resume with all 20 turns already persisted.response = await agent.run( "Research the top 10 papers on diffusion models and summarise each one.", session=session,)The trade-off: every model call now incurs a history write. For short, single-turn agents this is wasted I/O; for multi-tool research agents it protects hours of work from a single process crash.
See also
Section titled “See also”- Compaction — pair a
CompactionStrategywith the history provider for long-running conversations. - Middleware — read/write
AgentContext.sessionfrom agent middleware. - Production guide — deploying stateful sessions across multi-instance services.
Revision history
Section titled “Revision history”| Date | Version | Changes |
|---|---|---|
| 2026-11-02 | 1.24.0 | Added the RedisContextProvider index migration note. |
| 2026-10-24 | 1.22.0 | Added “where history lives by default” (Responses-API clients store server-side; others get an automatic InMemoryHistoryProvider), packaged Redis and Cosmos DB providers, and register_state_type(type_id=, encoder=, decoder=). Corrected the in-memory storage key (state["in_memory"]["messages"]), the path-traversal behaviour (unsafe ids are encoded, not rejected), and the compaction advice: after_strategy has no effect on file or Redis history. |