google / google/adk-python

[Feature] Add --state_file to adk run for loading initial session state from JSON

Abierto
#7,083 2 comentarios 0 reacciones 1 asignado Reclamado por @sanketpatil06 Ver en GitHub
core needs review
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` currently supports initial session state through `--state`, but the state must be passed as an inline JSON string:

```bash
adk run path/to/agent --state '{"customer_id": "123", "region": "us"}'
```

For realistic state payloads this becomes hard to use:

- Shell quoting differs across bash, zsh, PowerShell, and cmd.
- Larger state payloads are difficult to read, edit, and reuse.
- Sensitive or environment-specific values can end up in shell history.
- Generated state fixtures cannot be reused directly without wrapping them into a command-line string.

This is especially painful when testing agents that depend on session state, dynamic instructions, or state-backed tools.

I searched for existing issues/PRs targeting this specific CLI feature and did not find one for `--state_file` / `--state-file`. Related but distinct: #4961 proposes declarative initial state for `adk web`; this request is specifically for the `adk run` CLI path.

### Describe the Solution You'd Like

Add a `--state_file` option to `adk run` that loads initial session state from a JSON file:

```bash
adk run path/to/agent --state_file state.json
adk run path/to/agent "hello" --state_file state.json
```

The file should contain a JSON object used as the initial session state.

Expected behavior:

- `--state_file` works in both interactive mode and single-query mode.
- `--state` and `--state_file` are mutually exclusive.
- Invalid JSON should surface the same style of error as invalid `--state` JSON.
- Missing/unreadable files should be reported by Click as a normal CLI input error.

### Impact on your work

This would make local agent development and repeatable testing much smoother for stateful agents. Instead of copying JSON into a shell command, developers could keep reusable fixtures like:

```text
state.customer-a.json
state.debug.json
state.empty-cart.json
```

and run the same agent against each state file.

It also reduces quoting friction on Windows/PowerShell, where inline JSON can be particularly awkward.

### Willingness to contribute

Yes. I can open a small PR if this direction looks reasonable.

---

## 🟡 Recommended Information

### Describe Alternatives You've Considered

- Use `--state` with inline JSON. This works for tiny examples but becomes brittle for realistic payloads and varies by shell.
- Use `--replay`. This creates a session from an input file with queries, but it is a different workflow and not ideal when I only want to seed state and continue interactively or run a single query.
- Add initialization logic in callbacks. This works, but puts local testing/setup state into agent code.

### Proposed API / Implementation

The CLI already forwards `--state` as `state_str` into `run_cli` / `run_once_cli`, where the JSON parsing path already exists.

A minimal implementation could:

1. Add a Click option on `adk run`:

```python
@click.option(
"--state_file",
type=click.Path(exists=True, dir_okay=False, file_okay=True, resolve_path=True),
help="Optional. Path to a JSON file containing initial state for the run.",
)
```

2. Enforce that `--state` and `--state_file` cannot be used together.
3. Read the file as UTF-8 in `cli_run` and pass the contents as `state_str` to the existing `run_cli` / `run_once_cli` calls.
4. Add unit tests under `tests/unittests/cli/utils/test_cli_tools_click.py` covering interactive mode, single-query mode, mutual exclusion, and bad/missing file behavior.

### Additional Context

This is intentionally smaller than a broader declarative state feature. It only makes the existing `adk run --state` capability easier and safer to use with real JSON files.

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.