Improper Python sample codes and API mismatches in graph workflow documentation

[chaotingxuan]

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 (<CityTime.time_info from lookup_time_function>) 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