🔴 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 to AdkWebServer that reads {agents_dir}/{app_name}/initial_state.json if present, otherwise returns an empty dict
• Merge into _create_session() with client state taking precedence: {**file_state, **(client_state or {})}

Additional Context

N/A