Add Transient Model Input Context to RunConfig

[nicolasmota]

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_context is 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" and include_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

1. 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.

2. 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.

3. Using get_session_config

   get_session_config controls 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]] to RunConfig.
• 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.Content values.

[adk-bot]

GitHub Issue #5990 Analysis: Add Transient Model Input Context to RunConfig

Executive Summary

1. What is broken? There is currently no off-the-box, first-class mechanism in ADK to pass transient, request-scoped context (e.g., user profiles, entitlement context, metadata) to the LLM for a single invocation without persisting this context in the durable session.events.
2. Is there a linked PR that fixes this issue? Yes, PR #5991 is open and successfully addresses this issue.
3. Recommendation: Should Fix (High Priority). This is a critical enhancement for production-grade agent architectures that manage request-level metadata or dynamic context constraints outside the durable session timeline. Implementing first-class support prevents persistent session pollution and maintains clean message boundaries.

Detailed Analysis

1. Root Cause Analysis ("What is broken?")

1. The Issue: Agent runners and hosts must frequently supply context (such as middleware-resolved metadata, temporal summaries, or API tokens) to the model for a single query.
2. Current Limitations:
   • Applying SessionService.append_event() works but permanently pollutes the conversation history, which degrades performance and confuses the model during subsequent turns.
   • Injecting application context directly into the user message conflates developer inputs with actual end-user queries and requires custom parsing and formatting schemes.
3. The Solution Path:
   • RunConfig needs a dedicated field, model_input_context, which accepts a list of google.genai.types.Content objects.
   • When constructing the LLM request contents in contents.py, this context should be deep-copied and inserted immediately before the final active user input block.
   • Because these contents are only injected into LlmRequest during construction and never saved to the database via session_service, they remain fully transient across tool loops/steps but disappear when the invocation concludes.

Relevant Code Components

• run_config.py — Defines runtime configurations for runner executions (RunConfig).
• contents.py — Constructing LlmRequest contents in _ContentLlmRequestProcessor.run_async where transient context should be injected.

---

2. Existing Pull Requests ("Is there a linked PR that fixes this issue?")

• Linked PR: Pull Request #5991 - feat(run_config): add model_input_context for transient context in LLM requests (State: OPEN)
• PR URL: feat(run_config): add model_input_context for transient context in LLM requests #5991
• Analysis:
  • Adds model_input_context: Optional[list[types.Content]] = None to RunConfig.
  • Safely performs a deep-copy of model_input_context and inserts it before the invocation user content inside contents.py.
  • Keeps this path separate from instructions so transient context maintains correct sequential layout across tool-call loops and multi-agent runs where include_contents="none".
  • Comprehensive unit test coverage has been added verification for persistence, position stability under tool-loops, and sub-agent settings.

---

3. Recommendation

• Recommendation: Should Fix (High Priority).
• Rationale:
  • High Impact: Enhances clean architectural boundaries in host applications where developer context stays cleanly separated from conversation logs.
  • Low Complexity: The proposed solution is highly focused, minimally disruptive, has elegant backwards compatibility,