Python: ADR: Unifying Context Management with ContextMiddleware (Python)

[eavanvalkenburg]

Summary

This ADR proposes unifying \ContextProvider, \ChatMessageStore, and \AgentThread\ into a single \ContextMiddleware\ concept for the Python SDK.

Problem

Currently, developers doing 'Context Engineering' must understand multiple abstractions:

• \ContextProvider\ - Injects instructions, messages, and tools
• \ChatMessageStore\ - Stores and retrieves conversation history
• \AgentThread\ - Coordinates between them

Proposed Solution

A unified \ContextMiddleware\ using the onion/wrapper pattern (like existing \AgentMiddleware):

\\python
class RAGMiddleware(ContextMiddleware):
async def process(self, context: SessionContext, next) -> None:
# Pre-processing: add context
docs = await self.retrieve_documents(context.input_messages[-1].text)
context.add_messages(self.source_id, [ChatMessage.system(f'Context: {docs}')])

    await next(context)

    # Post-processing: store/audit
    await self.store_interaction(context.input_messages, context.response_messages)

agent = ChatAgent(
chat_client=client,
context_middleware=[
InMemoryStorageMiddleware('memory'),
RAGMiddleware('rag'),
]
)
\\

Key Decisions

Decision	Rationale
Onion/wrapper pattern	Familiar from existing middleware, natural pre/post processing
Agent owns config, Session owns pipeline	Enables per-session factories
Mandatory \source_id\	Attribution in \context_messages\ dict
Default \InMemoryStorageMiddleware\	Zero-config conversation history
Single \StorageContextMiddleware\ class	Configure for memory/audit/evaluation
Clean break (no shims)	We're in preview

Migration Impact

Current	New
\ContextProvider\	\ContextMiddleware\
\ChatMessageStore\	\StorageContextMiddleware\
\AgentThread\	\AgentSession\

See the full ADR in \docs/decisions/00XX-python-context-middleware.md\ for detailed design, code examples, and implementation workplan.

Related Issues

This ADR addresses the following issues:

• Python: sessions: Rename AgentThread to AgentSession #3587 - Rename AgentThread to AgentSession
• Python: sessions: Add get_new_session, get_session_by_id methods #3588 - Add get_existing_thread, get_new_session, get_session_by_id methods
• Python: sessions: Move serialize method into the agent #3589 - Move serialize method into the agent
• Python: sessions: Design orthogonal ChatMessageStore for service vs local threads #3590 - Design orthogonal ChatMessageStore for service vs local threads
• Python: sessions: Rename ChatMessageStore to ChatHistoryProvider #3601 - Rename ChatMessageStore to ChatHistoryProvider

[Copilot]

Pull request overview

Adds a new ADR proposing a unified ContextMiddleware abstraction for Python to replace ContextProvider, ChatMessageStore, and AgentThread, using an onion/wrapper middleware pipeline pattern.

Changes:

• Introduces a proposed ContextMiddleware + SessionContext + pipeline design for composable context engineering.
• Describes a StorageContextMiddleware approach for loading/storing conversation history and optional auditing.
• Outlines migration impact and a phased implementation/testing plan.