docs(aws-strands): cut the documentation to LangGraph's shape, and test what is left - #2620
Closed
ranst91 wants to merge 2 commits into
Closed
docs(aws-strands): cut the documentation to LangGraph's shape, and test what is left#2620ranst91 wants to merge 2 commits into
ranst91 wants to merge 2 commits into
Conversation
Contributor
Python Preview PackagesVersion
Install with uvAdd the TestPyPI index to your [[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
explicit = trueThen install the packages you need: # Core SDK
uv add 'ag-ui-protocol==0.0.0.dev1788434090' --index testpypi
# Integrations (each already depends on the matching ag-ui-protocol preview)
uv add 'ag-ui-langgraph==0.0.0.dev1788434090' --index testpypi
uv add 'ag-ui-crewai==0.0.0.dev1788434090' --index testpypi
# NOTE: ag-ui-agent-spec depends on pyagentspec (git-only, not on PyPI).
# You will need to install pyagentspec separately from its git repo.
uv add 'ag-ui-agent-spec==0.0.0.dev1788434090' --index testpypi
uv add 'ag_ui_adk==0.0.0.dev1788434090' --index testpypi
uv add 'ag_ui_strands==0.0.0.dev1788434090' --index testpypiInstall with pippip install \
--index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple/ \
ag-ui-protocol==0.0.0.dev1788434090
Commit: a06d9e5 |
@ag-ui/a2a-middleware
@ag-ui/a2ui-middleware
@ag-ui/event-throttle-middleware
@ag-ui/mcp-apps-middleware
@ag-ui/mcp-middleware
@ag-ui/a2a
@ag-ui/adk
@ag-ui/ag2
@ag-ui/agno
@ag-ui/aws-strands
@ag-ui/claude-agent-sdk
@ag-ui/claude-managed-agents
@ag-ui/crewai
@ag-ui/langchain
@ag-ui/langgraph
@ag-ui/llamaindex
@ag-ui/mastra
@ag-ui/pydantic-ai
@ag-ui/vercel-ai-sdk
@ag-ui/watsonx
@ag-ui/a2ui-toolkit
create-ag-ui-app
@ag-ui/client
@ag-ui/core
@ag-ui/encoder
@ag-ui/proto
commit: |
ranst91
force-pushed
the
claude/sad-jones-f33548
branch
from
September 3, 2026 11:14
5bfcf8e to
6f3fb19
Compare
ranst91
changed the title
The truth pass on the four Strands documents corrected roughly fifty false claims, in four recurring classes: counted quantities stated in prose, quoted signatures, example-table claims about which hooks a demo uses, and claims about what a package exports. The one class that did not drift is the one class the repository already had a lever for. Six levers, each in the existing test file for its subject. Every value is derived, from the document by parsing a structured region of it and from the source by enumerating it, so none of them carries an expected count or name list beside the test. - The TypeScript README route table against the DEMOS registry, by set and by length, mirroring the Python route-table test that held. - The README's runner and script numerals against the files that carry a standalone runner and the package.json scripts that point at one, plus the named complement so the sentence and the numeral cannot disagree. - Named imports in every ts fence against the real entry namespaces, and the install fence against this package's non-optional peers and the installed Strands SDK's own, with both fence numerals derived from those manifests. - The ARCHITECTURE packaging-surface block against __all__ three ways: the name set, the block size and the prose numeral, so editing the sentence alone cannot satisfy it. - Every signature the documents quote against inspect.signature, as ordered sequences, with the surface taken from __all__. - Each example-table row's identifiers against the primitives the demo actually uses, by AST walk, set-equal so both directions are covered. The example-table lever found two rows wrong by omission, which is the direction a one-way check misses, and both are corrected here: predictive_state_updates.py also uses state_from_args and state_context_builder, and a2ui_recovery.py sets StrandsAgentConfig.a2ui. Every lever was driven red before green, including the cases a weaker test would pass: a duplicated row that is set-equal but the wrong length, a stripped runner whose numeral stays correct, a prose numeral edited to match a shortened block, and a parameter reorder a set comparison accepts.
This integration carried 2,590 lines of documentation across four documents. LangGraph, the reference shape, carries 486. The dojo is the real support surface: spin it up and whatever demo it has is supported, so these documents should be a cheap stand-in for a docs site rather than the docs site itself. 2,590 lines to 765, and the document set now matches LangGraph's exactly. - ARCHITECTURE.md deleted, 382 lines. - python/README.md 764 to 194. - typescript/README.md 1,298 to 277. - python/examples/README.md 146 to 174, gaining the example table. - typescript/examples/README.md added, 120 lines. LangGraph ships one and this integration had none, so its fifteen TypeScript demos were documented only inside the package README. Gone: the AgentCore narration, the citations essays, the per-provider stop-reason surveys, the multi-agent and thread-guard prose, the RAW passthrough sections, the URL-fetch and invocation-state sections, the restated error-code tables, and roughly 300 lines of cross-origin narrative. Where a reader might want an explanation, the document links the demo instead. Three regions moved out of ARCHITECTURE.md before it went, because tests read them: the 32-name packaging surface and the two quoted Python signatures into python/README.md, and the fifteen-row example table into python/examples/README.md. All six documentation levers survive, repointed, and each relocated region was driven red in its new home before green. The cut is bounded by what the suites read. Kept verbatim: the three route tables, the install fence and its two numerals, the Quick Start and Key Files numerals, the corsOrigin table that the CORS fixtures parse in both directions, and the resume shapes, reserved prefix and approval-metadata passage the docs-contract suites anchor on. The new examples README repeated counts that were checked only in the package README, which would have reintroduced the class this branch exists to close, so the numeral lever now reads both documents and also holds the project tree to what is on disk in both directions. Every reference to the deleted file was repointed or removed across error-codes.json, agent.ts and five test files, with the sentence kept wherever it still asserted something true. No runtime string, error code or message text changed; error-codes.json still carries the same 26 codes.
ranst91
force-pushed
the
claude/sad-jones-f33548
branch
from
September 3, 2026 13:28
352049b to
2541908
Compare
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.
Cuts this integration's documentation from 2,590 lines to 765, deletes
ARCHITECTURE.md, and adds tests that read what is left so it cannot drift back.Why
A truth pass on these four documents corrected roughly fifty false claims. The
classes recurred: counted quantities stated in prose, quoted signatures,
example-table claims about which hooks a demo uses, and claims about what the
package exports.
Two things follow from that, and this PR does both.
The first is that the volume was the problem. LangGraph, the reference shape,
documents the same kind of bridge in 486 lines. This integration had 2,590, and
the extra 2,100 were essays nobody read and nothing checked. The dojo is the
real support surface: spin it up and whatever demo it has is supported. These
documents should be a cheap stand-in for a docs site, not the docs site.
The second is that whatever survives needs a reader. The one claim class that
never drifted was the one the repository already had a test for.
The cut
ARCHITECTURE.mdpython/README.mdpython/examples/README.mdtypescript/README.mdtypescript/examples/README.mdThe document set now matches LangGraph's exactly. That includes adding a
TypeScript examples README, which LangGraph ships and this integration did not,
so its fifteen TypeScript demos were documented only inside the package README.
Deleted: the AgentCore narration, the citations essays, the per-provider
stop-reason surveys, the multi-agent and thread-guard prose, the RAW passthrough
sections, the URL-fetch and invocation-state sections, the restated error-code
tables, and about 300 lines of cross-origin narrative. Where a reader might want
an explanation, the document links the demo instead.
Three regions moved out of
ARCHITECTURE.mdbefore it went, because tests readthem: the 32-name packaging surface and the two quoted Python signatures into
python/README.md, and the fifteen-row example table intopython/examples/README.md.The levers
Six, each in the existing test file for its subject. Every value is derived,
from the document by parsing a structured region of it and from the source by
enumerating it. No lever carries an expected count or name list beside the
test, because that is the same drift relocated into a file where it is less
visible than in prose.
DEMOSregistry, by set and by length, so aduplicated row cannot hide inside the set comparison.
runner, and the
package.jsonscripts that point at one, the scripted setderived by relationship rather than by counting. Plus the named complement, so
the sentence and the numeral cannot disagree.
tsfence against the real entry namespaces, withtype-only imports excluded since they are not runtime keys.
installed Strands SDK's own, read off its
package.json, with both fencenumerals derived from those manifests.
__all__three ways: the name set, the blocksize, and the prose numeral, so editing the sentence alone cannot satisfy it
and neither can editing the block alone.
inspect.signature, as ordered sequences, withthe surface taken from
__all__.by AST walk, set-equal so both directions are covered.
What the cut is bounded by
Five test files read these documents, which is what decided where the cut
stopped. Kept verbatim: the three route tables, the install fence, the Quick
Start and Key Files numerals, the
corsOrigintable that the CORS fixturesparse in both directions, and the resume shapes, reserved name prefix and
approval-metadata passage the docs-contract suites anchor on.
The TypeScript README landed at 277 rather than the 220 first targeted. The
regions that had to survive verbatim already total about 240, so going lower
would have meant cutting into a tested region.
Two things this found
direction a one-way check misses.
predictive_state_updates.pynamed onlyPredictStateMappingwhere the demo also usesstate_from_argsandstate_context_builder;a2ui_recovery.pynamed nothing where it setsStrandsAgentConfig.a2ui. Both corrected, in the words the demos' owndocstrings use.
were checked only in the package README, which is exactly the class this
branch exists to close. The numeral lever now reads both documents, and also
holds the project tree to what is on disk in both directions, which is the
direction LangGraph's own tree is stale in today.
Two design notes
Both are places where the corrected text falsified the simpler rule.
config class name drags in
StrandsAgent,StrandsAgentConfig,ToolBehaviorand
tool_behaviors, which every configured demo constructs and no row names,and fails all fifteen rows. It is now one concept per dataclass field, aliased
to the exported type named in that field's annotation, with the container field
skipped because its annotation names
ToolBehavior. Both exclusions arederived, and a guard test fails if the derivation ever yields nothing, since an
empty vocabulary would report fifteen agreements about nothing.
the line" is not enough: a README sentence legitimately opens with
`ToolBehavior(continue_after_frontend_call=False)`, which passes a chosenvalue where the signature names a parameter. A signature is now a span that
opens a list item, and the set of callables the scan finds is pinned so a
signature cannot quietly vanish from the prose instead of failing.
Every assertion is scoped to a structured region: a table row, a fence, an
import statement, a signature span, an anchored sentence. Nothing does an
unscoped substring search over a whole document, and every anchor fails loudly
if the phrase it keys on is reworded rather than silently ceasing to assert.
Deliberately not built
addStrandsExpressEndpoint'soption list needs an AST read of
endpoint.ts.truncation is still a substring, and it goes red on a legitimate paraphrase.
error-codes.jsonor its two table helpers.That file's own
aboutblock records why: it is data, not a reading of eithersource. Its helper weaknesses are a separate hardening task.
and causal claims, or the English-descriptor half of an example-table row.
Those have no in-repo falsifier.
Verification
Every lever was driven red before green: the document, or for the derived side
the source, was broken in the way the class actually drifted, the failure was
confirmed to name the problem, the file was restored, and the test confirmed
green. That includes the cases a weaker test would pass: a duplicated route row
that is set-equal but the wrong length, a stripped runner where the numeral
stays correct and only the complement set changes, a prose numeral edited to
match a shortened block, a parameter reorder that a set comparison accepts, an
example-table row wrong by omission, and a project-tree directory that is right
about what it names but silent about what was added.
Each relocated region was driven red again in its new home after the move.
uv run pytestinintegrations/aws-strands/python: 1,289 passed.pnpm exec vitest runinintegrations/aws-strands/typescript: 1,620 passed.The examples package: 96 passed.
Not changed
No runtime string, error code or message text.
error-codes.jsonstill carriesthe same 26 codes; its only edit is one prose sentence in the
aboutblock thatpointed at the deleted file.
Every reference to
ARCHITECTURE.mdwas repointed or removed acrosserror-codes.json,src/agent.tsand five test files, keeping the sentencewherever it still asserted something true. The
agent.tschange iscomment-only. A repo-wide sweep confirms no dangling reference remains.
One thing did leave the repository: the Python-versus-TypeScript hook-reporting
divergence, nine reported sites on one side and eight on the other, now lives
only in code docstrings rather than in any document.
Unrelated, pre-existing
src/__tests__/cors.test.tsfails roughly one run in six under load, in a testthat binds a real port. Untouched by this branch.