Commit 24a1b26
docs(skills): fix broken refs in adk-workflow skill
Merge google#6044
## Summary
Fixes 5 documentation bugs in the `adk-workflow` skill on `v2`. Each is empirically verified against `google-adk==2.2.0` and `v2` source. Full verification transcript inline below.
### Fixes in this PR
1. **`advanced-patterns.md`** — Remove the hard-coded local-filesystem URL `file:///Users/deanchen/Desktop/...` left in a doc link; replace with the relative path `dynamic-nodes.md`.
2. **`testing.md`** — All examples imported from `tests.unittests.*`, which is not in the published `google-adk` wheel. Rewrite to use the public `from google.adk.runners import InMemoryRunner` plus a small inline `run()` helper. Three rewritten snippets (basic workflow, state, parallel worker) were executed end-to-end against `google-adk==2.2.0` and pass. The `MockModel` section is replaced with a `FakeLlm(BaseLlm)` pattern that uses only public symbols.
3. **`llm-agent-nodes.md`** — The doc claims "LlmAgentWrapper outputs `types.Content`, NOT `str`." The source (`_llm_agent_wrapper.process_llm_agent_output`) sets `event.output = text` (a `str`) when `output_schema` is unset, and the validated dict when set. Rewrite the section, the table, and drop the "use `Any` and extract text" workaround that depended on the wrong claim.
4. **`parallel-and-fanout.md` + `import-paths.md`** — Drop `from google.adk.workflow._parallel_worker import ParallelWorker`. The class doesn't exist under that name; only the private `_ParallelWorker` does. The same files already document the public API (`parallel_worker=True` flag on `@node` or `LlmAgent`) — rewrite samples to use it consistently.
5. **`state-and-events.md` (+ one cross-reference in `advanced-patterns.md`)** — Drop `triggered_by`, `in_nodes`, `execution_id`, `retry_count` from the `Context` property tables and code samples. None of them exist on `Context` in v2 source (verified by `grep` in `src/google/adk/agents/context.py`). Rename `retry_count` → `attempt_count` (the live name). Also drop `get_next_child_execution_id` from the methods table for the same reason.
### Scope
All five fixes target the same file tree (`.agents/skills/adk-workflow/references/`) with the same concern: "skill docs reference symbols/imports/paths that don't exist." Per CONTRIBUTING.md "small, focused PRs", they're bundled because each is a surgical edit and they share verification setup. Happy to split if reviewers prefer.
## Testing plan
Doc-only changes. No source code or behavior modified.
1. **Pip-install reproduction** of every bug claimed in a clean venv with `google-adk==2.2.0`. See "Verification details" below for the verbatim `ImportError`, `hasattr == False`, and source quotes that prove each claim.
2. **Rewritten `testing.md` snippets executed end-to-end** against `google-adk==2.2.0`:
- `test_simple_workflow` — PASSED
- `test_state_management` — PASSED
- `test_parallel_worker` — PASSED
3. **Pre-commit hooks** ran clean on the changed files. `mdformat` is excluded for `.agents/` by the repo's `.pre-commit-config.yaml`, and the other hooks (`isort`, `pyink`, `addlicense`) target Python/shell files only.
## Notes for reviewers
- All claims are pinned to `2.2.0` + `v2` HEAD as of the date of this PR.
- The `testing.md` rewrite is the largest delta (~500 lines), but almost every line either drops a `tests.unittests.*` import or replaces a `testing_utils.X` call with public-API equivalents.
- A previously-considered "bug" (parallel-worker naming as `{name}__{index}`) was dropped from this PR after confirming it had already been fixed on v2 to use `{name}@{run_id}` with `run_id` starting at `"1"`.
---
## Verification details
Setup:
```bash
uv venv --python 3.13 .venv && source .venv/bin/activate
uv pip install google-adk
python -c "import google.adk; print(google.adk.__version__)"
# -> 2.2.0
```
### Bug 1 — Hard-coded `file:///` URL
```
$ grep -n 'file:///' .agents/skills/adk-workflow/references/advanced-patterns.md
38:See the dedicated [Dynamic Node Scheduling Reference](file:///Users/deanchen/Desktop/adk-workflow/.agents/skills/adk-workflow/references/dynamic-nodes.md) for detailed rules, examples, and best practices.
```
A developer's local filesystem path leaked into the published skill.
### Bug 2 — `tests.unittests...` imports unreachable from `pip install`
```python
>>> from tests.unittests.workflow import testing_utils
ModuleNotFoundError: No module named 'tests'
>>> from tests.unittests.testing_utils import InMemoryRunner, MockModel
ModuleNotFoundError: No module named 'tests'
```
The `tests/` directory ships only in the source repo, not in the installed `google-adk` wheel. Any user copying these snippets gets `ModuleNotFoundError`. The PR rewrites samples to use the public `from google.adk.runners import InMemoryRunner` and demonstrates a publicly-importable mock pattern (subclass `BaseLlm`).
The three rewritten snippets (basic, state, parallel) were run end-to-end against `google-adk==2.2.0` and all three passed.
### Bug 3 — `LlmAgentWrapper` output type doc is wrong
The skill claims: *"LlmAgentWrapper outputs `types.Content`, NOT `str`."*
The source in both `2.2.0` and `v2` says otherwise. From `src/google/adk/workflow/_llm_agent_wrapper.py`:
```python
def process_llm_agent_output(agent: Any, ctx: Context, event: Event) -> None:
...
text = (
''.join(p.text for p in event.content.parts if p.text and not p.thought)
if event.content.parts else ''
)
if agent.output_schema:
if text.strip():
output = validate_schema(agent.output_schema, text)
else:
output = None
else:
output = text # <-- str, not types.Content
...
event.output = output
```
When `output_schema` is unset, `event.output` is the concatenated string of the model's text parts. When `output_schema=MyModel` is set, it's the validated `model_dump()` dict. The PR rewrites the section, table, and the "use `Any` and extract text" workaround that depended on the wrong claim.
### Bug 4 — `_parallel_worker.ParallelWorker` is not importable
The class doesn't exist under that name — only the underscore-prefixed `_ParallelWorker` does, and that path is private:
```python
>>> from google.adk.workflow._parallel_worker import ParallelWorker
ImportError: cannot import name 'ParallelWorker' from 'google.adk.workflow._parallel_worker'
>>> from google.adk.workflow._parallel_worker import _ParallelWorker
>>> _ParallelWorker
<class 'google.adk.workflow._parallel_worker._ParallelWorker'>
```
The recommended public API is the `parallel_worker=True` flag — already documented as preferred in the same files. Verified end-to-end:
```python
from google.adk.workflow import node, Workflow
@node(parallel_worker=True)
def double(node_input: int) -> int:
return node_input * 2
# Workflow constructs OK; `double` is an internal _ParallelWorker
# under the hood — no user-visible private-API surface needed.
```
PR drops the private import from `parallel-and-fanout.md` and the `import-paths.md` table, and rewrites samples to use the flag.
### Bug 5 — Removed `Context` properties documented as live
```python
>>> from google.adk.agents.context import Context
>>> for name in ['triggered_by', 'in_nodes', 'execution_id', 'retry_count', 'attempt_count']:
... print(name, hasattr(Context, name))
triggered_by False
in_nodes False
execution_id False
retry_count False
attempt_count True
```
The same is true on `v2` source — `grep` for those names in `src/google/adk/agents/context.py` returns nothing, while `attempt_count` has 4 hits.
Code samples using `ctx.retry_count` / `ctx.triggered_by` raise `AttributeError`. PR removes the four absent properties from the docs and renames `retry_count` → `attempt_count` everywhere it's mentioned. `get_next_child_execution_id` is also gone from `Context` on v2; the PR removes it from the methods table for the same reason.
Co-authored-by: Shangjie Chen <deanchen@google.com>
COPYBARA_INTEGRATE_REVIEW=google#6044 from freddypatota:fix/adk-workflow-skill-doc-bugs 4a61d38
PiperOrigin-RevId: 9327700881 parent ffc9677 commit 24a1b26
6 files changed
Lines changed: 348 additions & 361 deletions
File tree
- .agents/skills/adk-agent-builder/references
Lines changed: 9 additions & 4 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| 7 | + | |
7 | 8 | | |
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
11 | 12 | | |
12 | 13 | | |
| 14 | + | |
13 | 15 | | |
14 | 16 | | |
15 | 17 | | |
| |||
46 | 48 | | |
47 | 49 | | |
48 | 50 | | |
49 | | - | |
| 51 | + | |
| 52 | + | |
50 | 53 | | |
51 | 54 | | |
52 | 55 | | |
| |||
80 | 83 | | |
81 | 84 | | |
82 | 85 | | |
83 | | - | |
| 86 | + | |
84 | 87 | | |
85 | 88 | | |
86 | 89 | | |
87 | | - | |
88 | | - | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
89 | 93 | | |
90 | 94 | | |
91 | 95 | | |
| |||
167 | 171 | | |
168 | 172 | | |
169 | 173 | | |
| 174 | + | |
170 | 175 | | |
171 | 176 | | |
172 | 177 | | |
| |||
Lines changed: 20 additions & 10 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2 | 2 | | |
3 | 3 | | |
4 | 4 | | |
| 5 | + | |
5 | 6 | | |
6 | 7 | | |
7 | 8 | | |
| |||
34 | 35 | | |
35 | 36 | | |
36 | 37 | | |
37 | | - | |
38 | | - | |
39 | | - | |
40 | | - | |
41 | | - | |
42 | | - | |
43 | | - | |
44 | | - | |
45 | | - | |
46 | | - | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
47 | 57 | | |
48 | 58 | | |
49 | 59 | | |
| |||
Lines changed: 29 additions & 21 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| 7 | + | |
7 | 8 | | |
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
11 | 12 | | |
12 | 13 | | |
| 14 | + | |
13 | 15 | | |
14 | 16 | | |
15 | 17 | | |
| |||
70 | 72 | | |
71 | 73 | | |
72 | 74 | | |
73 | | - | |
| 75 | + | |
74 | 76 | | |
75 | | - | |
| 77 | + | |
| 78 | + | |
76 | 79 | | |
77 | | - | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
78 | 84 | | |
79 | | - | |
| 85 | + | |
| 86 | + | |
80 | 87 | | |
81 | | - | |
82 | | - | |
83 | | - | |
84 | | - | |
85 | | - | |
86 | | - | |
87 | | - | |
88 | | - | |
89 | | - | |
90 | | - | |
91 | | - | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
92 | 94 | | |
93 | 95 | | |
94 | 96 | | |
| |||
104 | 106 | | |
105 | 107 | | |
106 | 108 | | |
107 | | - | |
| 109 | + | |
108 | 110 | | |
109 | 111 | | |
110 | 112 | | |
111 | 113 | | |
112 | 114 | | |
113 | 115 | | |
114 | | - | |
115 | | - | |
116 | | - | |
117 | | - | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
118 | 120 | | |
119 | | - | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
120 | 126 | | |
121 | 127 | | |
122 | 128 | | |
123 | 129 | | |
| 130 | + | |
124 | 131 | | |
125 | 132 | | |
126 | 133 | | |
| |||
260 | 267 | | |
261 | 268 | | |
262 | 269 | | |
| 270 | + | |
263 | 271 | | |
264 | 272 | | |
265 | 273 | | |
| |||
Lines changed: 18 additions & 29 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| 7 | + | |
7 | 8 | | |
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
11 | 12 | | |
| 13 | + | |
12 | 14 | | |
13 | 15 | | |
14 | 16 | | |
15 | 17 | | |
16 | 18 | | |
17 | 19 | | |
18 | 20 | | |
19 | | - | |
20 | | - | |
21 | | - | |
22 | | - | |
| 21 | + | |
23 | 22 | | |
24 | 23 | | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
25 | 28 | | |
26 | 29 | | |
27 | 30 | | |
| |||
91 | 94 | | |
92 | 95 | | |
93 | 96 | | |
94 | | - | |
| 97 | + | |
95 | 98 | | |
96 | | - | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
97 | 102 | | |
98 | 103 | | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
99 | 107 | | |
100 | 108 | | |
101 | 109 | | |
102 | | - | |
103 | | - | |
104 | 110 | | |
105 | 111 | | |
106 | 112 | | |
107 | 113 | | |
108 | 114 | | |
109 | 115 | | |
110 | 116 | | |
111 | | - | |
| 117 | + | |
112 | 118 | | |
113 | 119 | | |
114 | 120 | | |
115 | 121 | | |
116 | 122 | | |
117 | | - | |
| 123 | + | |
118 | 124 | | |
119 | 125 | | |
120 | 126 | | |
121 | 127 | | |
122 | 128 | | |
123 | | - | |
124 | 129 | | |
125 | 130 | | |
126 | | - | |
127 | | - | |
128 | | - | |
129 | | - | |
130 | | - | |
131 | | - | |
132 | | - | |
133 | | - | |
134 | | - | |
135 | | - | |
136 | | - | |
| 131 | + | |
137 | 132 | | |
138 | | - | |
| 133 | + | |
139 | 134 | | |
140 | 135 | | |
141 | 136 | | |
| |||
155 | 150 | | |
156 | 151 | | |
157 | 152 | | |
158 | | - | |
159 | | - | |
160 | | - | |
161 | | - | |
162 | | - | |
163 | | - | |
164 | 153 | | |
165 | 154 | | |
166 | 155 | | |
| |||
Lines changed: 16 additions & 12 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| 7 | + | |
7 | 8 | | |
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
11 | 12 | | |
12 | 13 | | |
| 14 | + | |
13 | 15 | | |
14 | 16 | | |
15 | 17 | | |
| |||
33 | 35 | | |
34 | 36 | | |
35 | 37 | | |
36 | | - | |
37 | | - | |
38 | | - | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
39 | 41 | | |
40 | 42 | | |
41 | 43 | | |
| |||
57 | 59 | | |
58 | 60 | | |
59 | 61 | | |
60 | | - | |
61 | | - | |
62 | | - | |
63 | | - | |
64 | | - | |
65 | | - | |
66 | | - | |
67 | | - | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
68 | 71 | | |
69 | 72 | | |
70 | 73 | | |
71 | 74 | | |
72 | 75 | | |
73 | 76 | | |
74 | | - | |
75 | 77 | | |
76 | 78 | | |
77 | 79 | | |
| |||
92 | 94 | | |
93 | 95 | | |
94 | 96 | | |
| 97 | + | |
95 | 98 | | |
96 | 99 | | |
97 | 100 | | |
| |||
120 | 123 | | |
121 | 124 | | |
122 | 125 | | |
| 126 | + | |
123 | 127 | | |
124 | 128 | | |
125 | 129 | | |
| |||
0 commit comments