[Feature] Add --state_file to adk run for loading initial session state from JSON
- Ngôn ngữ chính
- Python
- Star
- 21.5k
- Fork
- 4k
- Merge trung bình
- 1 ngày 14 giờ
- Pull request đã merge (30 ngày)
- 37
Mô tả
## 🔴 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.
Hướng dẫn đóng góp
Đánh giá
Issue này chưa được đánh giá.