Skip to content

[Docs] Syntax errors and incorrect language code fences in contributing/samples README snippets #7998

Closed

Description

@Anil-Pradhan-web

🔴 Required Information

Describe the Bug:
Multiple README documentation files under contributing/samples/ contain invalid Python syntax in sample code blocks or incorrect Markdown code-fence language specifiers.

Specifically:

  1. Mislabelled Language Tags: Shell installation commands and database connection strings are tagged with python instead of bash or ```text.
  2. Python Syntax Errors: Several sample snippets contain invalid Python syntax such as missing commas between parameters, positional ellipsis (...) placed after keyword arguments, and an orphaned elif block with no preceding if.

These syntax errors break Python AST parsing (including ADK's adk-verify-snippets verification tool) and cause immediate SyntaxError when developers attempt to run or adapt these sample snippets.

Steps to Reproduce:

  1. Mislabelled Shell Commands & URLs:
    • contributing/samples/integrations/langchain_youtube_search_agent/README.md: The bash command uv pip install youtube_search is fenced as ```python.
    • contributing/samples/context_management/postgres_session_service/README.md: The connection URL postgresql+asyncpg://username:password@host:port/database is fenced as ```python.
  2. Python Syntax Errors (Missing commas / Invalid argument ordering):
    • contributing/samples/core/hello_world/README.md (lines 56–68): Missing comma after ... between kwargs in Agent(name='hello_world_agent', ... generate_content_config=...).
    • contributing/samples/hitl/tool_confirmation/README.md (lines 40–45): An isolated elif statement without an enclosing if block.
    • contributing/samples/hitl/tool_confirmation/README.md (lines 58–63): Missing comma after ... before tools=[...].
    • contributing/samples/hitl/request_input_tool/README.md (lines 42–46): Positional ... placed after keyword argument tools=[...].
    • contributing/samples/multi_agent/single_turn_sub_agent/README.md (lines 35–43 & 48–51): Positional ... placed after keyword arguments.
    • contributing/samples/multi_agent/task_sub_agent/README.md (lines 36–42 & 47–52): Positional ... placed after keyword arguments.

Expected Behavior:

  • Shell commands should be fenced with bash or sh.
  • URIs and plain text formats should be fenced with ```text.
  • All code blocks tagged with ```python should be syntactically valid Python code (or properly annotated with <!-- verify-snippets: ignore --> if intended as illustrative pseudo-code fragments).

Observed Behavior:
Parsing these snippets via ast.parse() or executing them raises:

  • SyntaxError: invalid syntax. Perhaps you forgot a comma?
  • SyntaxError: positional argument follows keyword argument
  • SyntaxError: invalid syntax (on orphaned elif)

Environment Details:

  • ADK Library Version: main branch (commit HEAD)
  • Desktop OS: Windows / Linux / macOS
  • Python Version: Python 3.11+

Model Information:

  • Are you using LiteLLM: No
  • Which model is being used: N/A (Documentation issue)

🟡 Optional Information

Minimal Reproduction Code:

import ast

# Example 1: Missing comma in hello_world/README.md
code_1 = """
root_agent = Agent(
    name='hello_world_agent',
    ...
    generate_content_config=types.GenerateContentConfig()
)
"""
ast.parse(code_1)
# Raises: SyntaxError: invalid syntax. Perhaps you forgot a comma?

# Example 2: Positional ellipsis following kwargs in single_turn_sub_agent/README.md
code_2 = """
phone_recommender = Agent(
    name="phone_recommender",
    mode="single_turn",
    input_schema=UserPreferences,
    output_schema=PhoneRecommendation,
    tools=[check_phone_price],
    ...
)
"""
ast.parse(code_2)
# Raises: SyntaxError: positional argument follows keyword argument

How often has this issue occurred?:
Always (100%)

Willingness to contribute:
Yes! I have forked the repository and would like to submit a Pull Request to fix these code fences and sample snippets.

Activity

  1. added a commit that references this issue on Nov 6, 2026
    68ee084
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions