Repository navigation
Add Transient Model Input Context to RunConfig #5990
Description
Support Transient Per-Invocation Model Input Context
Required Information
Is your feature request related to a specific problem?
Yes.
Some host applications need to provide request-scoped context to an ADK agent for a single invocation without persisting that context into session.events.
Examples include:
- User profile or entitlement context fetched at request time.
- Notification or trigger metadata relevant only to the current turn.
- External conversation summaries managed outside ADK.
- Middleware-generated context that should guide the model but should not become part of durable conversation history.
Today, applications usually need to work around this by appending synthetic events to the session or by encoding extra context into the user message. Both options are undesirable:
- Appending events pollutes persistent history and can affect future turns.
- Encoding context into the user message mixes application metadata with end-user input.
- Neither option clearly expresses "visible to the model for this invocation only".
Describe the Solution You'd Like
I would like ADK to expose a first-class way to pass transient model input context for a single runner invocation.
The API could live on RunConfig, for example as a field that accepts a list of google.genai.types.Content objects. These contents would be included when ADK builds the LLM request for the current invocation, but they would not be appended to session.events.
Expected behavior:
model_input_contextis visible to the model during the current invocation.- It is not persisted in session history.
- It remains stable across multiple LLM calls in the same invocation, including tool-call loops.
- It works with
include_contents="default"andinclude_contents="none". - It preserves normal session event semantics for actual user/model/tool events.
Impact on your work
This enables applications that manage request-scoped context outside ADK to pass that context into an agent safely, without mutating durable ADK session history.
In my use case, a service layer needs to inject contextual information into the agent flow while keeping the persisted session clean and representative of actual conversation events.
This is important for correctness, observability, replay, and session lifecycle behavior.
Willingness to contribute
Yes. I am willing to help contribute a focused implementation if maintainers agree this API belongs in ADK.
Recommended Information
Describe Alternatives You've Considered
-
Appending synthetic events with
SessionService.append_event()This makes the context visible to the model, but it persists the context into
session.events. That is not appropriate for one-turn context and can affect future invocations. -
Prefixing the user message with context
This keeps session history simpler, but it conflates application-provided context with the actual user input. It also requires every caller to implement its own formatting convention.
-
Using
get_session_configget_session_configcontrols which persisted events are fetched, but it does not provide a way to add non-persistent context to the current model input.
Proposed API / Implementation
One possible API shape:
from google.adk.agents.run_config import RunConfig
from google.genai import types
run_config = RunConfig(
model_input_context=[
types.UserContent("Relevant request-scoped context for this turn")
]
)
runner.run(
user_id=user_id,
session_id=session_id,
new_message=types.UserContent("User question"),
run_config=run_config,
)Expected model input:
user: Relevant request-scoped context for this turn
user: User question
Expected persisted session events:
user: User question
model: Agent response
A possible implementation direction would be:
- Add
model_input_context: Optional[list[types.Content]]toRunConfig. - When building
LlmRequest.contents, deep-copy and insert the transient context before the invocation user content. - Do not append these contents to
session.events. - Keep instruction-related content insertion separate so transient context does not accidentally move after tool/function responses.
Additional Context
This should be covered by tests for:
- Transient context is sent to the model and not persisted.
- Transient context keeps its position across tool-call loops.
- Transient context works with
include_contents="none"in a multi-agent flow. - the selected API accepts transient
types.Contentvalues.
Activity
adk-bot commentedon Jun 5, 2026
GitHub Issue #5990 Analysis: Add Transient Model Input Context to RunConfig
Executive Summary
session.events.Detailed Analysis
1. Root Cause Analysis ("What is broken?")
SessionService.append_event()works but permanently pollutes the conversation history, which degrades performance and confuses the model during subsequent turns.RunConfigneeds a dedicated field,model_input_context, which accepts a list ofgoogle.genai.types.Contentobjects.LlmRequestduring construction and never saved to the database viasession_service, they remain fully transient across tool loops/steps but disappear when the invocation concludes.Relevant Code Components
RunConfig)._ContentLlmRequestProcessor.run_asyncwhere transient context should be injected.2. Existing Pull Requests ("Is there a linked PR that fixes this issue?")
OPEN)model_input_context: Optional[list[types.Content]] = NonetoRunConfig.model_input_contextand inserts it before the invocation user content inside contents.py.include_contents="none".3. Recommendation
sanketpatil06 commentedon Jun 8, 2026
Hi @nicolasmota , Thanks for bringing this and taking time to raise a PR. Your request is currently being reviewed, and we will let you know if anything further is needed. We appreciate your contribution.
feat: add model_input_context for transient context in LLM requests
feat: add model_input_context for transient context in LLM requests