google / google/adk-docs

Improper Python sample codes and API mismatches in graph workflow documentation

Open
#2,170 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
1.5k
Forks
1.3k
Avg merge
7d 1h
Merged PRs (30d)
34

Description

**Describe the bug**

Multiple Python sample codes across the Graph Workflows documentation (`docs/graphs/`) contain code discrepancies, syntax errors, and API mismatches with the surrounding explanatory text and the ADK Python 2.0 runtime:

1. **`docs/graphs/routes.md` (Loop and escalation exit)**:
- The section describes creating iterative loops with back-edges and exit termination routes in a `Workflow`. However, the Python code snippet is an exact duplicate of the forward branching router and contains **no loop, no back-edge, and no exit condition**.

2. **`docs/graphs/human-input.md` (Tool-confirmation: approval prompts in LLM agents)**:
- The text explicitly introduces LLM agent-level **Tool Confirmation** (`FunctionTool` / `tool_context.request_confirmation`) and contrasts it with standalone graph HITL nodes. However, the Python sample code shows an `initial_prompt` workflow function node yielding `RequestInput`, which is a graph-level HITL pause rather than tool confirmation.

3. **`docs/graphs/data-handling.md` (Access structured data in agents)**:
- The text and code introduce an imaginary angle-bracket syntax (``) that does not exist in ADK Python. Furthermore, `START` is unquoted and unimported, and `city_generator_agent` is referenced without definition.

4. **`docs/graphs/dynamic.md` (Loop route)**:
- The `code_workflow` function contains both `yield Event(...)` and `return code` within an `async def`, causing Python to raise a `SyntaxError: 'return' with value in async generator`. It is also missing `rerun_on_resume=True`.

5. **`docs/graphs/dynamic.md` (Nodes / FunctionNode wrapper)**:
- `FunctionNode(my_function_node, ...)` passes the function positionally, but `FunctionNode.__init__` enforces keyword-only arguments (`def __init__(self, *, func: Callable, ...)`), raising a `TypeError` at runtime.

6. **`docs/graphs/data-handling.md` (Session state and state scopes)**:
- Omitted necessary imports (`Context`, `Event`, `Workflow`, `Content`), causing `NameError` when executing the snippet.

---

**To Reproduce**

Steps to reproduce the behavior:
1. Navigate to the following documentation pages:
- `docs/graphs/routes.md#loop-and-escalation-exit`
- `docs/graphs/human-input.md#tool-confirmation-approval-prompts-in-llm-agents`
- `docs/graphs/data-handling.md#access-structured-data-in-agents`
- `docs/graphs/dynamic.md#loop-route`
- `docs/graphs/dynamic.md#node`
2. Compare the code samples with the surrounding text descriptions and run the sample codes in a standard ADK Python 2.0 environment.
3. Observe syntax errors (`SyntaxError`), runtime exceptions (`TypeError`, `NameError`), and functional mismatches with the text.

---

**Expected behavior**

1. `routes.md` should demonstrate an actual loop workflow with a back-edge and terminal route.
2. `human-input.md` should demonstrate static and dynamic tool confirmation (`FunctionTool(..., require_confirmation=True)` and `tool_context.request_confirmation(...)`).
3. `data-handling.md` should demonstrate standard structured data input schemas (`input_schema=CityTime`) with valid prompt instructions without phantom syntax.
4. `dynamic.md` should demonstrate a valid programmatic `while` loop that returns the result cleanly without mixing generator `yield` and `return value` in the same function, and include `rerun_on_resume=True`.
5. `dynamic.md` should use keyword arguments for `FunctionNode(func=...)`.
6. All snippets should be self-contained with complete imports.

---

**Screenshots**

*N/A (Code and documentation issue)*

---

**Versions**

- OS: macOS / Linux / Windows
- ADK version: 2.0.0
- Python version: 3.10+

---

**Additional context**

A complete patch fixing all 6 issues is prepared as attachment

[fix-graphs-docs-code-samples.patch](https://github.com/user-attachments/files/31341857/fix-graphs-docs-code-samples.patch)

Contributor guide

Open the contributing guide

Research direction

Start with the six affected sections in docs/graphs/routes.md, human-input.md, data-handling.md, and dynamic.md, then compare each sample with the surrounding text and the attached patch. Run the snippets in a standard ADK Python 2.0 environment; done means the examples match their explanations, use valid APIs and imports, and execute without the reported syntax or runtime errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
ai, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.