google / google/adk-python

Feature Request: Declarative initial session state for `adk web`

Abierto
#4,961 1 comentario 0 reacciones 1 asignado Reclamado por @GWeale Ver en GitHub
needs review web
Lenguaje dominante
Python
Estrellas
21.5k
Forks
4k
Merge medio
1 d 14 h
PR fusionados (30 d)
37

Descripción

## 🔴 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: https://github.com/google/adk-python/discussions/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
```

```json
{
"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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.