Feature Request: Declarative initial session state for adk web #4961

🔴 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