google / google/adk-python

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

オープン
#7,083 コメント 2 件 リアクション 0 件 担当者 1 名 @sanketpatil06 が担当を希望しています GitHub で見る
core needs review
主要言語
Python
スター
21.5k
フォーク
4k
平均マージ
1日 14時間
マージ済み PR(30日)
37

説明

## 🔴 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.

コントリビューションガイド

コントリビューションガイドを開く

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。