fix(web): allow session resume without new message (#4100)

[Akshat8510]

Description
This PR resolves #4100 by making the new_message field optional in the RunAgentRequest model.

The Problem:
When attempting to resume an agent session via the FastAPI web server, the request would fail with a 422 Unprocessable Entity if new_message was omitted. This prevented "resume-only" workflows where a user just wants to wake up an existing session.

The Solution:
Updated RunAgentRequest.new_message to be Optional[types.Content] = None. The underlying runner.run_async logic already supports None for resuming purposes, so no further logic changes were required.

Verification:
Verified that RunAgentRequest now validates successfully when new_message is missing, defaulting the field to None.

[gemini-code-assist]

Summary of Changes

Hello @Akshat8510, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the flexibility of agent session management by addressing a limitation in the RunAgentRequest model. Previously, resuming an agent session required a new_message field, even when no new input was intended. The change makes this field optional, aligning the web server's request handling with the underlying agent runner's capability to resume sessions with a None message. This modification streamlines the process for users who wish to simply reactivate an existing session.

Highlights

• Optional Message Field: The new_message field in the RunAgentRequest model has been made optional, allowing agent sessions to be resumed without providing a new message.
• Bug Fix: This change resolves an issue where attempting to resume an agent session via the FastAPI web server would result in a 422 Unprocessable Entity error if new_message was omitted.
• Workflow Improvement: The update enables 'resume-only' workflows, where users can reactivate an existing session without needing to send new content.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request correctly addresses the issue of being unable to resume an agent session without a new message. By changing RunAgentRequest.new_message to be optional (Optional[types.Content] = None), the API now properly supports "resume-only" workflows. The change is well-contained and aligns the web server's request model with the existing logic in runner.run_async, which already handles cases where new_message is None for session resumption. The implementation is correct. I have one suggestion to improve test coverage for this new capability.

[gemini-code-assist]

Code Review

This pull request correctly addresses the issue by making the new_message field optional in the RunAgentRequest model. This change allows for agent session resumption without requiring a new message, which is a valuable improvement for 'resume-only' workflows. The implementation is clean and direct. I've added one comment regarding the addition of a test case to ensure this fix is validated and to prevent future regressions.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request correctly makes the new_message field optional in RunAgentRequest to resolve a 422 Unprocessable Entity error when resuming a session. The inclusion of a new unit test to verify this is a good practice. However, the fix is incomplete as it introduces a new runtime error. The new test provides a false positive because it mocks the Runner.run_async method, bypassing a validation check that would cause a ValueError and a 500 error in a real-world scenario. To be complete, the runner logic should also be updated to handle this new 'resume-only' case gracefully.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request correctly addresses the issue of allowing agent session resumption without requiring a new_message. The change to make RunAgentRequest.new_message optional is well-implemented. The corresponding adjustment in runners.py to handle a "no-op resume" by returning early instead of raising an error is a sensible approach. The new test case effectively verifies that the API now accepts requests without a new message. I have a couple of minor suggestions in the test file to improve code cleanliness.

[Akshat8510]

@gemini-code-assist/gemini review

[Akshat8510]

/gemini summary

[gemini-code-assist]

Code Review

This pull request correctly makes the new_message field optional in RunAgentRequest to support 'resume-only' workflows, which is a good enhancement. The changes in the web server model, the runner logic, and the addition of a new test case are all well-aligned with this goal. I have one suggestion to improve observability for the new no-op resume behavior.

[gemini-code-assist]

Summary of Changes

This pull request enhances the flexibility of agent session management by enabling "resume-only" workflows. It addresses a previous limitation where the FastAPI web server would reject requests to resume an agent session if no new_message was provided. The changes involve making the new_message field optional in the request model and updating the underlying runner logic to correctly process such requests as a no-op resume, ensuring a smoother user experience for reactivating existing sessions.

Highlights

• Optional Message Field: The new_message field in the RunAgentRequest model has been made optional, allowing agent sessions to be resumed without providing new content.
• Graceful No-Op Resume: The agent runner logic was modified to gracefully handle 'resume-only' requests where neither a new message nor an invocation ID is provided, preventing ValueError and performing a no-op resume.
• New Test Coverage: A new test case was added to test_fast_api.py to validate the successful handling of agent session resume requests without a new message.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/google/adk/cli/adk_web_server.py
  • The new_message field in the RunAgentRequest model is now Optional[types.Content] = None, making it optional for incoming requests.
• src/google/adk/runners.py
  • The _run_with_trace function now explicitly handles cases where neither invocation_id nor new_message is provided by performing a no-op resume and returning early, instead of raising a ValueError.
• tests/unittests/cli/test_fast_api.py
  • A new test, test_agent_run_resume_without_message, has been added to verify that the /run endpoint correctly processes agent session resume requests when new_message is omitted.

Activity

• gemini-code-assist[bot] provided an initial summary of the pull request.
• gemini-code-assist[bot] suggested adding test cases to verify the optional new_message field and prevent regressions.
• gemini-code-assist[bot] identified an issue with the initial test's mocking strategy and recommended updating the runner logic to properly handle "resume-only" scenarios.
• gemini-code-assist[bot] provided minor suggestions for code readability and test hygiene (removing blank lines, unnecessary logging).
• gemini-code-assist[bot] suggested adding a log message for the no-op resume in the runner for better observability.
• The author, Akshat8510, repeatedly requested reviews and summaries from the bot.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request correctly makes the new_message field optional in the RunAgentRequest to allow for "resume-only" workflows, which is a great enhancement. The changes are well-implemented, including the logic to handle this case as a no-op in the runner and the addition of a new test case.

I have a couple of suggestions to further improve the changes:

• Update the run_async docstring to reflect the new behavior.
• Enhance the new test to cover the full end-to-end logic instead of mocking the runner's behavior.

Overall, this is a solid contribution.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request correctly addresses the issue of allowing session resumption without a new message by making the new_message field optional. The changes to the RunAgentRequest model and the corresponding logic in runners.py are appropriate and well-implemented. The addition of a new test case to verify this behavior is also a great inclusion. I have a couple of minor suggestions to improve the clarity of the documentation and a test comment.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request resolves an issue where resuming an agent session without a new message would fail. The changes make the new_message field in RunAgentRequest optional and update the runner logic to handle this case as a no-op resume, which is a clean solution. The docstrings have been updated to reflect the new behavior, and a new test case has been added to verify the fix. The changes are well-implemented and improve the flexibility of the web API. The code quality is high, and I have no further suggestions for improvement.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[Akshat8510]

@gemini-code-assist/gemini review

[Akshat8510]

/gemini summary

[gemini-code-assist]

Code Review

This pull request correctly implements the ability to resume a session without providing a new message by making new_message optional in RunAgentRequest. The changes are well-contained, touching the web server model, the runner logic, and adding a corresponding test case. My main feedback is to improve the handling of state_delta in the new no-op resume path to avoid silently ignoring user input.

[gemini-code-assist]

Summary of Changes

This pull request enhances the flexibility of agent session management by enabling 'resume-only' workflows. It addresses a previous limitation where the FastAPI web server would reject requests to resume an agent session if no new_message was provided. The changes involve making the new_message field optional in the request model and updating the underlying runner logic to correctly process such requests as a no-op resume, ensuring a smoother user experience for reactivating existing sessions.

Highlights

• Optional Message Field: The new_message field in the RunAgentRequest model is now optional, allowing agent sessions to be resumed without providing new content.
• Bug Fix for Session Resume: The FastAPI web server no longer returns a 422 Unprocessable Entity error when new_message is omitted during an agent session resume request.
• Graceful No-Op Resume: The agent runner logic (_run_with_trace) has been updated to gracefully handle 'resume-only' scenarios by performing a no-op and returning early when neither new_message nor invocation_id is provided, instead of raising a ValueError.
• New Test Coverage: A new test case (test_agent_run_resume_without_message) has been added to verify the successful handling of agent session resume requests without a new message.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/google/adk/cli/adk_web_server.py
  • The new_message field in the RunAgentRequest model is now Optional[types.Content] = None, making it optional for incoming requests.
• src/google/adk/runners.py
  • The docstring for run_async was updated to remove the ValueError clause that previously indicated an error if both invocation_id and new_message were None.
  • The _run_with_trace function now explicitly handles cases where neither invocation_id nor new_message is provided by performing a no-op resume and returning early, instead of raising a ValueError.
  • A logger.info message was added to log when a no-op resume is performed.
• tests/unittests/cli/test_fast_api.py
  • The dummy_run_async mock function was updated to return early if both invocation_id and new_message are None.
  • A new test, test_agent_run_resume_without_message, has been added to verify that the /run endpoint correctly processes agent session resume requests when new_message is omitted.

Activity

• gemini-code-assist[bot] provided an initial summary of the pull request.
• gemini-code-assist[bot] suggested adding test cases to verify the optional new_message field and prevent regressions.
• gemini-code-assist[bot] identified an issue with the initial test's mocking strategy and recommended updating the runner logic to properly handle 'resume-only' scenarios.
• gemini-code-assist[bot] provided minor suggestions for code readability, such as removing blank lines and unnecessary logging.
• gemini-code-assist[bot] suggested adding a log message for the no-op resume in the runner for better observability.
• gemini-code-assist[bot] recommended updating the run_async docstring to reflect the new no-op resume behavior.
• gemini-code-assist[bot] advised removing the mock from the new test to ensure full end-to-end coverage of the 'resume-only' scenario.
• gemini-code-assist[bot] suggested clarifying the Raises section in the docstring and removing an incorrect comment about patch_runner.
• gemini-code-assist[bot] recommended logging a warning if state_delta is provided but ignored during a no-op resume.
• The author, Akshat8510, repeatedly requested reviews and summaries from the bot.
• gemini-code-assist[bot] temporarily reached its daily quota limit.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This is a well-executed fix. Making the new_message field optional in RunAgentRequest is the correct approach to allow for "resume-only" workflows. The changes in runners.py to gracefully handle the absence of both new_message and invocation_id by performing a no-op are clean and logical. I appreciate the addition of a new test case in test_fast_api.py, which effectively verifies the fix and prevents future regressions. Overall, the changes are clear, concise, and well-tested.

[gemini-code-assist]

Code Review

This pull request correctly addresses the issue of allowing agent session resumption without a new message. The changes in adk_web_server.py make the new_message field optional in the RunAgentRequest model, and the logic in runners.py is updated to handle this as a no-op resume, which is a clean solution. The associated test updates, including a new test case to verify this specific workflow, are well-implemented and ensure the fix is robust. Overall, the changes are of high quality and I have no concerns.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request correctly addresses the issue of allowing agent session resumption without requiring a new message. The changes are well-implemented across the API model, the runner logic, and the tests. By making new_message optional in RunAgentRequest and handling the "no-op resume" case gracefully in the runner, the fix is both robust and clean. The addition of a dedicated unit test and updates to the mock implementation ensure the new behavior is verified. The docstring update also accurately reflects the change in the run_async method's behavior. Overall, this is a solid contribution that improves the flexibility of the web server API.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request correctly makes new_message optional to allow resuming agent sessions without a new message, and includes several good typing improvements. However, I've identified two critical bugs in src/google/adk/runners.py. One is an incorrect use of asyncio.Queue for inter-thread communication, and the other is unreachable code that prevents the intended no-op resume logic. I've also included a minor suggestion to simplify a mock function in the new tests.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request correctly makes the new_message field optional in RunAgentRequest to allow for session resumption without a new message, which is a valuable fix. The accompanying new test and various typing improvements are also great additions. My review includes a few suggestions to improve documentation accuracy, address a potential issue with mutable default arguments in a Pydantic model, and clean up some now-redundant code. Overall, these are solid changes.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request aims to allow session resumption without a new message by making new_message optional in RunAgentRequest. The change is correctly applied to the model, and a new test case is added to verify this. The PR also includes several nice type hinting improvements across the codebase.

However, I found a critical issue where the /run endpoint does not pass the invocation_id to the runner, which prevents the session resumption from working on that endpoint. I've left a comment with a suggested fix.

I also found a minor redundancy with a cast that can be removed for cleaner code.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request effectively resolves the issue of resuming an agent session without a new message by making the new_message field optional. The changes are well-implemented and include a new test case to verify the fix. I've also noted several other code quality improvements throughout the PR, such as adding type hints and modernizing type union syntax. My review includes a comment highlighting an important bug fix related to mutable default arguments in a Pydantic model and a suggestion to remove some unused code in the tests. Overall, this is a solid contribution.

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request correctly addresses the issue of resuming an agent session without a new message by making new_message optional in RunAgentRequest. The addition of a new test case to verify this functionality is also great.

I've also noticed several code quality improvements throughout the pull request, such as adding and correcting type hints, and fixing a mutable default argument issue in a Pydantic model. These changes enhance the readability and robustness of the code.

Overall, the changes are well-implemented and I have no further suggestions. Good work!

[Akshat8510]

@gemini-code-assist/gemini review

[gemini-code-assist]

Code Review

This pull request correctly makes the new_message field optional in RunAgentRequest to allow resuming agent sessions without a new message. The addition of invocation_id to the run_agent endpoint call is a good bug fix that aligns it with the streaming endpoint. The new test case effectively verifies the session resume functionality. The other changes, such as adding type hints and updating docstrings, improve code quality. I've suggested a minor change to maintain consistency in type hinting for optional arguments.

[Akshat8510]

/gemini summary

[gemini-code-assist]

Summary of Changes

This pull request addresses a limitation in the FastAPI web server where agent session resume requests would fail with a 422 Unprocessable Entity error if the new_message field was omitted, even when an invocation_id was provided. The core change makes the new_message field optional in the RunAgentRequest model, thereby enabling 'resume-only' workflows where an existing session can be reactivated using its invocation_id without requiring new input. The underlying agent runner logic continues to enforce that either a new_message or an invocation_id must be present for agent execution.

Highlights

• Optional Message Field: The new_message field in the RunAgentRequest model has been made optional, allowing agent sessions to be resumed by providing an invocation_id without a new message.
• API Error Resolution: This change resolves a 422 Unprocessable Entity error that occurred when attempting to resume an agent session via the FastAPI web server if new_message was omitted but an invocation_id was present.
• Improved Type Hinting: Various type hints have been added or updated for internal dictionaries (runner_dict, trace_dict, session_trace_dict) and function parameters (internal_exporters) to enhance code clarity and maintainability.
• Pydantic Default Factory Usage: Pydantic list field defaults in the _MockEvalCaseResult test model now correctly use Field(default_factory=list) to prevent mutable default argument issues.
• New Test Coverage: A new parameterized test (test_agent_run_resume_without_message_success) has been added to verify the successful handling of agent session resume requests without a new message, covering scenarios both with and without state_delta.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/google/adk/cli/adk_web_server.py
  • The new_message field in the RunAgentRequest model was updated to Optional[types.Content] = None, making it optional for incoming requests.
  • Type hints for internal_exporters in _setup_gcp_telemetry and _setup_telemetry_from_env were updated from list[SpanProcessor] = None to list[SpanProcessor] | None = None.
  • Explicit type hints dict[str, Runner] = {} were added for self.runner_dict.
  • Explicit type hints dict[str, Any] = {} and dict[str, list[int]] = {} were added for trace_dict and session_trace_dict respectively.
  • The invocation_id parameter was added to the runner.run_async call within the run_agent function.
• src/google/adk/runners.py
  • The cast type utility was imported from typing.
  • The event_queue initialization was updated with a type hint: event_queue: queue.Queue[Optional[Event]] = queue.Queue().
  • The docstring for run_async was updated to reflect ValueError conditions, specifically if the session is not found or if both invocation_id and new_message are None.
  • A blank line was added before the if not invocation_id and not new_message: check in _run_with_trace.
  • The user_id and session_id parameters were explicitly cast to str when calling _get_or_create_session within run_live.
  • The invocation_id parameter was explicitly cast to str when calling _find_user_message_for_invocation.
  • The conditional import of Self was removed, and the __aenter__ method's return type hint was simplified to 'Runner'.
• tests/unittests/cli/test_fast_api.py
  • The Field class was imported from pydantic.
  • A blank line was added in the dummy_run_async mock function.
  • The _MockEvalCaseResult model's list fields (eval_metric_results, overall_eval_metric_results, eval_metric_result_per_invocation) were updated to use Field(default_factory=list) for their default values.
  • A new parameterized test test_agent_run_resume_without_message_success was added to verify session resume functionality without a new message, covering cases with and without state_delta.

Activity

• gemini-code-assist[bot] provided an initial summary of the pull request.
• gemini-code-assist[bot] suggested adding test cases to verify the optional new_message field and prevent regressions.
• gemini-code-assist[bot] identified an issue with the initial test's mocking strategy and recommended updating the runner logic to properly handle 'resume-only' scenarios.
• gemini-code-assist[bot] provided minor suggestions for code readability (removing blank lines, unnecessary logging).
• gemini-code-assist[bot] suggested adding a log message for the no-op resume in the runner for better observability.
• gemini-code-assist[bot] recommended updating the run_async docstring to reflect the new no-op resume behavior.
• gemini-code-assist[bot] advised removing the mock from the new test to ensure full end-to-end coverage of the 'resume-only' scenario.
• gemini-code-assist[bot] suggested clarifying the Raises section in the docstring and removing an incorrect comment about patch_runner.
• gemini-code-assist[bot] recommended logging a warning if state_delta is provided but ignored during a no-op resume.
• Akshat8510 (author) repeatedly requested reviews and summaries from the bot.
• gemini-code-assist[bot] temporarily reached its daily quota limit on January 17th.
• gemini-code-assist[bot] provided further suggestions for test robustness, such as using caplog for log assertions and parameterizing similar tests.
• ryanaiagent requested fixes for unit tests and formatting errors, and later requested a review from wukath.
• wuliang229 questioned the change from ValueError to no-op in runners.py.
• Akshat8510 responded, explaining the original intent for no-op resume but then stating a reversion of runners.py to its original state.
• gemini-code-assist[bot] identified a critical bug related to asyncio.Queue usage and unreachable code in _run_with_trace (implying the no-op logic was either re-introduced or not fully reverted as stated).
• gemini-code-assist[bot] continued to provide detailed suggestions, including refining docstrings, removing redundant Self imports, correctly using Field(default_factory=list) for Pydantic models, removing redundant cast operations, and removing unused mock functions.
• Akshat8510 confirmed addressing all feedback from manual and AI reviews and marked the PR as ready for review.