google / google/adk-python

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

未关闭
#7,083 2 条评论 0 个 reaction 已指派 1 人 已被 @sanketpatil06 认领 在 GitHub 查看
core needs review
主要语言
Python
星标
21.5k
派生
4k
平均合并
1 天 14 小时
30 天内合并 PR
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 摘要。