Repository navigation
Description
🔴 Required Information
Is your feature request related to a specific problem?
adk run supports pre-loading session state via the --replay option with a JSON file, but adk web has no equivalent mechanism. When iteratively developing and testing agents that depend on session state, I have to either manually enter state through the Web UI on every new session, or write custom injection logic in callbacks. A simpler, declarative option would improve the development experience.
Related discussion: #2753
Describe the Solution You'd Like
Allow developers to place an initial_state.json file in the agent directory. When adk web creates a new session, it automatically merges the file's contents into the session state.
my_agent/
├── __init__.py
├── agent.py
└── initial_state.json # new
{
"city": "New York",
"time": "10:30"
}- JSON format — consistent with
adk run --replay - Client state takes precedence — values passed from the client overwrite file-based defaults
- Zero impact when absent — if the file doesn't exist, behavior is unchanged
Impact on your work
This would streamline my iterative development workflow. Every time I create a new session in adk web, I currently re-enter the same state values manually. Not critical, but it would be a nice quality-of-life improvement.
Willingness to contribute
Yes — happy to open a PR if this direction looks reasonable.
🟡 Recommended Information
Describe Alternatives You've Considered
- Manual entry via Web UI — works, but repetitive across sessions
before_agent_callback— requires boilerplate code that isn't part of the agent's core logic
Proposed API / Implementation
- Add a
_load_initial_state()method toAdkWebServerthat reads{agents_dir}/{app_name}/initial_state.jsonif present, otherwise returns an empty dict - Merge into
_create_session()with client state taking precedence:{**file_state, **(client_state or {})}
Additional Context
N/A
Activity
sanketpatil06 commentedon Mar 24, 2026
@Koichi73, Thank you for submitting. It’s currently under review by our team, and I’ll keep you posted on any updates. We appreciate your input!
feat: seed adk web sessions from initial_state.json