Skip to content

docs(examples): fix unrunnable Python snippets included by the docs - #2030

Open
GWeale wants to merge 1 commit into
google:mainfrom
GWeale:docs-audit-new-examples
Open

docs(examples): fix unrunnable Python snippets included by the docs#2030
GWeale wants to merge 1 commit into
google:mainfrom
GWeale:docs-audit-new-examples

Conversation

@GWeale

@GWeale GWeale commented Jul 30, 2026

Copy link
Copy Markdown
Contributor

The examples/python/** snippets are pulled into the docs with --8<--, so a
broken snippet renders as broken documentation. 14 of them did not run, and one
did not even parse.

Verified against google/adk-python @ main by importing and introspecting every
symbol, not by reading. Compile sweep over examples/python/**: 50/64 files
parsed before, 64/64 after
.

What was wrong

  • tools/overview/doc_analysis.pyawait inside a plain def, so the whole
    file was a SyntaxError; load_artifact and search_memory are coroutines
    and were not awaited; MemoryEntry.events does not exist (the field is
    content).
  • tools/overview/customer_support_agent.pysub_agents assigned after
    construction, which skips model_post_init's parent linking, so
    parent_agent stayed None.
  • tools/auth/agent_cli.py, tools/built-in-tools/agent_search.py
    create_session is a coroutine and was not awaited, so the run raised
    SessionNotFoundError.
  • tools/auth/tools_and_agent.pytools=toolset.get_tools() passed a
    coroutine, raising TypeError: 'coroutine' object is not iterable.
  • tools/auth/helpers.py — read the function-call arg auth_config, but ADK
    serialises with by_alias=True, so the key is authConfig; the helper always
    raised.
  • tools/built-in-tools/{spanner,bigtable}.py — sync wrappers returned an
    un-awaited coroutine from execute_sql.
  • tools/built-in-tools/agent_search.pygrounding_attributions does not
    exist on types.GroundingMetadata.
  • callbacks/{before,after}_agent_callback.pyevent.is_error() and
    event.error_details have never been part of the Event API.
  • callbacks/after_agent_callback.py — comments said the callback replaces
    the agent's output; it appends a new event.
  • callbacks/after_tool_callback.py — comments said tool_response is
    {"result": <value>}; the callback receives the raw return value.

Also in this PR

  • Files presented as complete runnable code no longer have module-level
    await; the driver is wrapped in async def main() under
    if __name__ == "__main__", matching the pattern already used in each
    directory.
  • 13 unguarded event.content.parts[0].text dereferences under
    is_final_response() now carry the guard already used elsewhere in this repo.
    is_final_response() never inspects content, so the unguarded form crashes
    on safety-blocked turns, state-only events and grounding-only responses.
  • tutorial/agent_team/adk_tutorial.ipynb — the same four defects corrected in
    docs/tutorials/agent-team.md, so the notebook and the page agree.

@netlify

netlify Bot commented Jul 30, 2026

Copy link
Copy Markdown

Deploy Preview for adk-docs-preview ready!

Name Link
🔨 Latest commit 91ec232
🔍 Latest deploy log https://app.netlify.com/projects/adk-docs-preview/deploys/6a6a9f8267f69600089bf9af
😎 Deploy Preview https://deploy-preview-2030--adk-docs-preview.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant