Repository navigation
Pass RunContextWrapper[T] to Session methods #2072
Description
Feature Request: Pass RunContextWrapper[T] to Session methods
Summary
Right now, Session methods (get_items, add_items, pop_item, etc.) don’t receive the agent’s RunContextWrapper[T].
Passing the wrapper directly would let a custom session manage both conversation history and context together.
Proposed Change
Add wrapper as an optional argument to session methods:
async def get_items(self, limit: int | None = None, wrapper: RunContextWrapper[T] | None = None) -> list[dict]:
...
async def add_items(self, items: list[dict], wrapper: RunContextWrapper[T] | None = None) -> None:
...This allows custom sessions to decide how to store or update the wrapper along with messages.
Benefits
- Gives custom sessions full control over context and history
- Makes multi-turn, stateful agents easier to implement
Question / Concern
In the non-streaming interface, I noticed that add_items is only called after handoffs are complete.
This means if an agent is switched mid-session, the session can’t save info like the agent’s name or other context until the very end.
Is there a recommended way to handle this, or should add_items be triggered more incrementally to capture agent-specific information during handoff?
Activity
seratch commentedon Nov 18, 2025
Adding the second parameter makes sense but we need to keep backward-compatibility for all existing sessions store implementations. If we deliver without breaking changes for existing code, this would be a good addition.
feat: add optional wrapper parameter to Session methods
nileshpatil6 commentedon Apr 17, 2026
Hi! I'd love to tackle this. Based on seratch's comment about backward-compatibility, I'm planning to add
wrapper: RunContextWrapper[T] | None = Noneas an optional keyword-only argument toget_items,add_items, andpop_itemon theSessionbase class — defaulting toNoneso all existing session implementations keep working with zero changes. Would a PR in that direction be welcome?feat: pass run context wrapper to session get_items/add_items
fede-kamel commentedon Jun 25, 2026
Following up on the backward-compatibility concern raised above — here's a concrete approach that adds
RunContextWrapperaccess without breaking any existingSessionimplementation, before I open a PR:Mechanism: opt-in via introspection,
Sessionprotocol left unchanged.The runtime passes
run_contextto a session method only if that method's signature accepts it (arun_contextparameter, or**kwargs). Existing sessions — including the built-ins and any third-partySession— keep their current signatures and are called exactly as today.Custom sessions opt in simply by adding the parameter:
The
SessionProtocol/SessionABCsignatures stay as-is, so this introduces no new structural-typing requirement on existing implementations (adding the param to the Protocol itself would breakmypyconformance for every current custom session, which is what we want to avoid).A couple of decisions I'd like to confirm before implementing:
run_context(holds theRunContextWrapper)? Or do you preferwrapperas in the original request?get_items/add_items/pop_item/clear_session), or start withget_items+add_itemswhere the context is most useful?If this approach looks right, I'm happy to put up the PR (with tests covering both an opt-in session and an existing session that ignores the new arg).
sujikathir commentedon Jul 27, 2026
I checked current
mainand found no open PR for this issue. I’d like to take this forward with the compatibility constraint from @seratch as the primary requirement.I’ll keep the existing
Sessionprotocol and legacy method call shapes working unchanged. Context-aware session implementations will opt in via an optional keyword-onlyrun_context, and the runner will pass it only where the implementation supports it. I’ll cover both streamed and non-streamed runs, plus regression tests proving existing custom sessions still work without modification.I’ll keep the change focused on making the current run context available to session operations; incremental persistence timing and new session semantics will remain out of scope.