feat(run_config): add model_input_context for transient context in LLM requests

[nicolasmota]

Add Transient Model Input Context to RunConfig

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: Add Transient Model Input Context to RunConfig #5990

Problem:

Host applications sometimes need to provide request-scoped context to an agent for a single invocation without persisting that context into session.events.

Before this change, callers had to either append synthetic session events or merge application context into the user message. Both approaches blur the boundary between durable conversation history and transient model input.

Solution:

This change adds RunConfig.model_input_context, a list of google.genai.types.Content values that are injected into the LLM request for the current invocation only.

The context is deep-copied before insertion, added before the invocation user content, and never appended to session.events. The insertion path is separate from instruction-related content so the transient context keeps a stable position across tool-call loops and multi-agent include_contents="none" flows.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Passed locally:

.venv/bin/python -m pytest tests/unittests/agents/test_llm_agent_include_contents.py tests/unittests/agents/test_run_config.py
14 passed

Additional checks:

.venv/bin/pyink --check --diff --config pyproject.toml src/google/adk/flows/llm_flows/contents.py tests/unittests/agents/test_llm_agent_include_contents.py tests/unittests/agents/test_run_config.py
.venv/bin/isort --check-only src/google/adk/flows/llm_flows/contents.py tests/unittests/agents/test_llm_agent_include_contents.py tests/unittests/agents/test_run_config.py src/google/adk/agents/run_config.py
git diff --check

Manual End-to-End (E2E) Tests:

Not run. This change is covered by focused unit tests around LLM request construction and session persistence.

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

The unit coverage verifies that transient context:

• is sent to the model without being persisted to the session;
• stays before the invocation user message after a tool call;
• works for a sub-agent using include_contents="none" in a sequential flow;
• is accepted by RunConfig as types.Content.

[adk-bot]

I have completed a thorough, strictly read-only analysis of PR #5991 and the linked Issue #5990 according to the adk-pr-analyze guidelines.

The full, structured premium report has been compiled and saved as an artifact at:
👉 pr_5991_analysis.md

---

Highlights & Key Decisions

1. State of Google CLA: Verified. The cla/google status check is at state SUCCESS.
2. Feature Assessment: Highly justified. Introducing transient base configuration on RunConfig solves the problem of request-scoped context integration systematically, preventing persistent session pollution and improving prompt lifecycle control.
3. Core Quality: Exceptional. The tests are very robust, following behavior-focused validation boundaries on test_llm_agent_include_contents.py and test_run_config.py without mocking core orchestration entities.
4. Recommendation: Approve (with a single styling nit).

Open Nit / Decision Point

• Mismatched Typings: In run_config.py:L350, the author uses:

  model_input_context: Optional[list[types.Content]] = None

  This should be updated to use modern union types aligning with ADK Python conventions:

  model_input_context: list[types.Content] | None = None

---

Summary of Work Done

• Verified Compliance Gates: Consulted GitHub statusCheckRollup to confirm the Google CLA is signed and successful.
• Retrieved Context: Parsed linked Issue #5990 and examined the PR #5991 diff against local workspace baseline files.
• Conducted Architectural Audit: Inspected contents.py and verified backwards scanning logic robustness.
• Published Report: Synthesized the ultimate analysis checklist inside the workspace artifact directory.

[adk-bot]

I am going to check the instructions for the /adk-pr-analyze command's skill file to analyze PR 5991 correctly. Let's load the skill.I am going to verify the contributor's Contributor License Agreement (CLA) signature by running the triage script for PR 5991 in a read-only manner. This is the mandatory entry gate for the analysis.I will use the fetch_github_pr custom API tool to fetch the details of PR 5991. This is a read-only tool that avoids direct shell commands when possible.I will call the fetch_github_pr tool with just the pr_number parameter to retrieve the PR details correctly.I will now fetch the exact lines changed in the pull request using the GitHub CLI command. This is essential to perform a precise architectural review.I will find and view src/google/adk/agents/run_config.py in the workspace to see the context around the parameters being defined.I will view the src/google/adk/agents/run_config.py file to understand the class structure, Pydantic configuration, and fields of the RunConfig model in the baseline code.I will view the rest of the src/google/adk/agents/run_config.py file to see the RunConfig class definition.I will locate and inspect src/google/adk/flows/llm_flows/contents.py to see where the _add_model_input_context_to_user_content function and invocation are integrated.I will view lines 70 to 120 (and more) in src/google/adk/flows/llm_flows/contents.py to understand the flow within run_async and how the model input context is appended/inserted.I will retrieve the imports of src/google/adk/flows/llm_flows/contents.py to check if copy is imported.I will use grep_search to find def _add_instructions inside contents.py to examine how instructions are added and compare the patterns.I will view the _add_instructions_to_user_content function implementation in src/google/adk/flows/llm_flows/contents.py starting from line 975.I will search for user_content in src/google/adk/agents/invocation_context.py if it exists. Let's first search by name in the codebase.I will view src/google/adk/agents/invocation_context.py to confirm the type and properties of user_content within the InvocationContext class.I will search user_content within invocation_context.py to see its declaration or type.I will fetch the details of the linked Issue #5990 to verify the original gap reported and align the PR analysis with the original business context.I will write the complete premium Pull Request Analysis Report for PR #5991 as a dedicated markdown artifact in the designated artifact directory. This ensures that the report persists and remains easily accessible.I have completed a thorough, strictly read-only analysis of PR #5991 and the linked Issue #5990 according to the adk-pr-analyze guidelines.

The full structured premium report has been compiled and saved as an artifact at:
👉 pr_5991_analysis.md

---

Highlights & Key Decisions

1. State of Google CLA: Verified. The author has signed the Google CLA.
2. Feature Assessment: Highly justified. Introducing transient base configuration on RunConfig solves the problem of request-scoped context integration systematically, preventing persistent session database pollution and improving prompt lifecycle control.
3. Core Quality: Exceptional. The tests are very robust, following behavior-focused validation boundaries on test_llm_agent_include_contents.py and test_run_config.py without mocking core orchestration entities.
4. Recommendation: Approve (with a single styling nit).

Open Nit / Decision Point

• Mismatched Typings: In run_config.py, the author uses:

  model_input_context: Optional[list[types.Content]] = None

  This should be updated to use modern union types aligning with ADK Python conventions:

  model_input_context: list[types.Content] | None = None

---

Summary of Work Done

• Verified Compliance Gates: Confirmed Google CLA is signed.
• Retrieved Context: Fetched and parsed linked Issue #5990 and examined the PR #5991 diff against local baseline files.
• Conducted Architectural Audit: Inspected contents.py and verified backward scanning logic robustness.
• Published Report: Synthesized the ultimate analysis checklist inside the workspace artifact directory.