[AAASM-4590] 📝 (python-sdk-docs): Add missing imports + version-compat notes to quick-start tabs#254
Merged
Chisanan232 merged 6 commits intoJul 14, 2026
Conversation
…ft Agent Framework quickstart snippets The 3 vendored snippets were truncated at `) as ctx:` with no `with` body, making them syntactically invalid Python. Re-vendor each from its upstream examples/python/<framework>/src/main.py so the `with` block has a real body (the standard Agent/Gateway/Mode print block + policy rules) and the try/finally each already opens is properly closed, matching the adapter-cleanup pattern the real examples use. Refs AAASM-4585
Byproduct of the vendored-snippet fix in the previous commit: running scripts/generate_quickstart_tabs.py picks up the completed with-blocks for Google ADK, Pydantic AI, and Microsoft Agent Framework so the rendered doc no longer ends the tab mid-statement. Refs AAASM-4585
Every vendored quickstart_snippets/*.py had zero import lines, so the quick-start page's per-framework tabs never showed what to import, leaving a copy-pasting reader with a NameError on init_assembly and every framework-specific call. Import lines are sourced verbatim from the matching ai-agent-assembly/examples source (origin/master), limited to the lines actually needed by each excerpt's body. Refs AAASM-4590
quickstart_snippets/manifest.json can now carry an optional version_compat_note field per framework entry; render_tab() renders it as a nested "Version compatibility" admonition beneath that framework's code fence. Needed so AAASM-4590's compat notes stay generator-driven (never a hand-edit of the generated region) for frameworks with a real, citable import-path break in their version history. Refs AAASM-4590
…orks Adds a "Version compatibility" admonition to the LangChain, LangChain (Research Agent), LangGraph, LlamaIndex, AutoGen, Haystack, Agno, and smolagents quick-start tabs — each backed by a real, citable official migration guide, changelog, or release entry for a genuine import-path break in that framework's version history (full sources in the PR description). The remaining 8 frameworks got no note: no verifiable break was found for them, and a wrong "helpful" note is worse than none (per ticket AC). docs/quick-start.md is regenerated output only — no hand-edits to the generated region. Refs AAASM-4590
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
…tart snippets governed_run, MOCK_TRAJECTORY, build_tools, NETWORK_ALLOWLIST, governed_invoke, and PLUGIN_NAME were each imported but never referenced by their shown excerpt body. Matches this ticket's own AC: only include import lines actually used by the shown body.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Quick-start §3's 16 framework tabs never showed the SDK's import statement — every vendored
quickstart_snippets/*.pyhad zeroimport/fromlines, so a reader copy-pasting a tab got an immediateNameError. This PR:ai-agent-assembly/examplessource (python/<example>/src/main.py,origin/master), limited to the lines actually needed by each excerpt's body.docs/quick-start.mdis regenerated viascripts/generate_quickstart_tabs.py— no hand-edits to the generated region.!!! note "Version compatibility"admonition beneath 8 of the 16 tabs (LangChain, LangChain (Research Agent), LangGraph, LlamaIndex, AutoGen, Haystack, Agno, smolagents) for frameworks with a real, citable import-path break in their own version history. The remaining 8 got no note — no verifiable break was found for them (Custom has no framework to break; CrewAI/Google ADK/Microsoft Agent Framework/OpenAI Agents SDK/Pydantic AI/Semantic Kernel/Strands Agents either had no evidence of a genuine import-path break or the evidence found was too narrow/unofficial to cite confidently).scripts/generate_quickstart_tabs.pyto support an optionalversion_compat_notefield per manifest entry (a local, python-sdk-only addition — not part of the upstreamexamplesmanifest), so the notes stay 100% generator-driven.Stacked on #253 (AAASM-4585) — this branch is based on that branch's tip since 3 of the 4 currently-truncated
with ... as ctx:snippet bodies (Google ADK, Pydantic AI, Microsoft Agent Framework) live there, and this ticket's AC requires a cleanast.parsepass across all 16 files. Please merge #253 first.Version-compat note sources (cited per framework)
langchain.agents/.chains→langchain_core/langchain_community/langchain_classic(0.1 → 0.3 → 1.0)langgraph.prebuilt.create_react_agent→langchain.agents.create_agent(1.0)llama_index→llama-index-core+ per-provider packages (v0.10, Feb 2024)pyautogen/autogen.agentchat→autogen-agentchat/autogen-core/autogen-ext(v0.2 → v0.4)farm-haystack→haystack-ai, node imports flattened intohaystack.components.*(1.x → 2.0)phi.*→agno.*(Phidata rename)HfApiModel→InferenceClientModel(v1.14.0, Apr 2025; back-compat restored v1.24.0)Known gap (tracked separately, not fixed here)
quickstart_snippets/smolagents-tool-policy.pyhas the same dangling-with-no-body truncation as the 3 files AAASM-4585 fixes, but was not in that ticket's scope. Filed as AAASM-4592 rather than fixed inline here, since this ticket's scope is imports-only and its AC states "no other content in these files changes." As a result,ast.parsesucceeds on 15 of 16 updated files —smolagents-tool-policy.pystill fails until AAASM-4592 lands (the import line added here is still correct; the pre-existing truncated body is the only blocker).Type of Change
Breaking Changes
Related Issues
Testing
ast.parseon all 16 snippet files (15/16 pass; see "Known gap" above),python3 scripts/generate_quickstart_tabs.py --check(zero drift),mkdocs build --strict(clean), Playwright: clicked through Agno/LangChain/LlamaIndex/Google ADK tabs and confirmed the imports render and the two "Version compatibility" admonitions render as real styled callouts (screenshots taken locally).pull_request.pathsallow-list excludesdocs/**andquickstart_snippets/**is not covered by unit tests (verified viapython scripts/generate_quickstart_tabs.py --checkinstead).Checklist