Repository navigation
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation in python/a2ui_a2a/README.md, python/a2ui_agent/README.md, and python/a2ui_agent/agent_development.md to align with API changes around response parsing, streaming, and state management (such as to_a2a_parts, stream_response_to_parts, and RendererState). The review feedback points out two issues in the code examples within agent_development.md: invalid Python syntax in a placeholder and an undefined capabilities variable in the multi-version support example.
0df8f19 to
cf5db13
Compare
cf5db13 to
6e471f6
Compare
6e471f6 to
74fb3d8
Compare
229788b to
7b4baed
Compare
…d streaming 1. `agent_development.md` explains the chat and canvas lifetimes of a `RendererState`, creating a processor per request from the client's capabilities, and reading a streamed response with `open_stream`, `feed` and `close`. 2. The agent SDK README lists `RendererState` and `ResponseStream`. 3. The `a2ui-a2a` README shows `stream_response_to_parts` with a `ResponseStream` and `to_a2a_parts`. Part of #3262 and #3263. Signed-off-by: Nan Yu <nanyu@google.com>
The LlmAgent example passes an empty tools list instead of a placeholder that isn't Python, and the multi-version example reads the client's capabilities before it creates the processor. Signed-off-by: Nan Yu <nanyu@google.com>
agent_development.md still said the catalogs must be freestanding, and linked to a section of the catalogs guide that no longer exists. Since cross-catalog references are resolved against peer catalogs, it now says which catalogs a reference resolves against and links to Catalog Linking. Signed-off-by: Nan Yu <nanyu@google.com>
…nt inference formats
1. Step 2 no longer loads examples into the prompt with load_examples:
the generator's examples are checked against the request's catalogs
and written into processor.prompt_snippet. It shows how to give the
generator example turns instead.
2. Allowed messages are set on the format factory given to the
generator, not by calling schema_to_prompt, and use the message
names the formats read ("createSurface", "updateComponents").
3. A new "Choose an Inference Format" section: Direct JSON is the
default and the only format that streams; Express needs fewer output
tokens and is parsed whole.
4. Option B says it needs Direct JSON, and that the stream must be
closed after the last chunk, which stream_response_to_parts does.
Signed-off-by: Nan Yu <nanyu@google.com>
7b4baed to
eebbda5
Compare
gspencergoog
left a comment
gspencergoog
left a comment
There was a problem hiding this comment.
Docs-only change (stack #3275, 5 of 6) that rewrites agent_development.md and the a2ui_agent / a2ui_a2a READMEs around per-request processors, open_stream() / feed() / close(), to_a2a_parts / stream_response_to_parts, and the chat-versus-canvas RendererState model. I checked every symbol, import path, keyword argument, exception class, link, and behavioral claim on the changed lines against the source in the checkout (processor.py, generator.py, parser.py, response_stream.py, renderer_state.py, catalog_resolver.py, schema_pruning.py, parts.py, the v0.9 server_to_client.json schema, and the pinned ADK Runner signature), and parsed every Python block on a changed line. All of it matches; no findings.
Two notes for context rather than action. The sentence that custom-components-example starts a new state when the client's catalogs change describes #3272 (next in the stack), which adds that logic in _renderer_state(); the sample on disk at this commit still uses the removed create_parser() API. The allowed_messages=["createSurface", "updateComponents"] example works for v0.9 (prune_messages_schema also matches message keys, and the Express prompt generator accepts both spellings), but the prune_messages_schema docstring only names CreateSurfaceMessage-style names; that docstring is outside this diff.
🤖 Agent-generated
ditman
left a comment
ditman
left a comment
There was a problem hiding this comment.
Optional, while you're in these files:
- agent_development.md L578:
a2ui.a2ahas noA2UI_EXTENSION_URI; useget_a2ui_extension_uri(version). - agent_development.md L663: the v0.9 basic catalog id is
https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json. - agent_development.md L438:
LlmAgent(instruction=instruction, ...)is aSyntaxError, like the placeholder you fixed. python/a2ui_agent/README.mdL61:A2uiTargetNotFoundErrordoesn't exist;errors.pydefines theA2uiCompilation*Errorclasses.
LGTM, these are a bunch of nits.
…e' into docs/python-agent-renderer-state Signed-off-by: Nan Yu <nanyu@google.com>
- Fix code blocks that weren't valid Python or used undefined names: define catalogs in Step 1, name the 4b variable version, guard against message.metadata being None, and drop '...' arguments. - Describe the stream as the code behaves: messages emit as soon as part of them reads and again as they grow, strings heal only for progressive_keys (none by default), change detection is per message. - Read a streamed retry with open_stream(state=stream.state), and say what a failed stream leaves in the state. - Use accepts_state to tell when a kept state no longer fits the request's catalogs, which follow the client's supportedCatalogIds order. - Fix the orchestrator's extension URI, the v0.9 basic catalog id, the unresolved $ref note, v0.8 buffering, inline catalogs, to_message_dicts for create_a2ui_part, and the README notes on open_stream, errors.py and parse_content_to_parts. Signed-off-by: Nan Yu <nanyu@google.com>
nan-yu
left a comment
nan-yu
left a comment
There was a problem hiding this comment.
Thanks @ditman, I also took the optional ones in 2f34d3a:
- The orchestrator compares against
get_a2ui_extension_uri(ProtocolVersion.V0_9). - The proxy uses the real v0.9 basic catalog id,
https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json. LlmAgent(model=..., name="...", instruction=instruction). 4a had the same problem indef __init__(self, agent, ...)andMyAgentExecutor(agent=agent, ...), which are fixed too. Every Python block in the guide and both READMEs now parses.- The README's
errors.pyline listsA2uiCompilationError,A2uiCompilationParseErrorandA2uiCompilationValidationError.
…nt-renderer-state Describe the stream as it now emits: only updateComponents and updateDataModel while they grow, every other message once its object closes, each chunk read once. A v0.8 chat response that never sends beginRendering is rejected. Signed-off-by: Nan Yu <nanyu@google.com>
This branch has not been deployed
3 participants
Part of #3262 and #3263. Stacked on #3270.
Documentation for the changes in #3268, #3269 and #3270.
agent_development.mdexplains creating a processor per request from the client's capabilities, the chat and canvas lifetimes of aRendererState, and reading a streamed response withopen_stream,feedandclose.RendererStateandResponseStreamand describes the stateless parser.a2ui-a2aREADME describesto_a2a_partsandstream_response_to_partswith aResponseStream.a2ui.constantsgainsA2UI_RENDERER_CAPABILITIES_KEY("a2uiRendererCapabilities"), the message metadata key under which the v1.0 A2A extension sends the renderer capabilities; v0.8 and v0.9 useA2UI_CLIENT_CAPABILITIES_KEY. The sample PRs stacked on this one (refactor(samples): per-request processors in restaurant_finder and custom-components-example #3272, refactor(samples): per-request processors in the ADK toolset samples #3274) read it.agent_development.mdsays which messages the direct JSON stream emits while they grow (updateComponentsandupdateDataModel) and that every other message waits for its object to close, as feat(python/agent)!: make the Parser stateless; always validate; add ResponseStream #3269 now does, and that a v0.8 chat response that never sendsbeginRenderingis rejected (feat(python/agent): add RendererState; build validate_payload on it #3268).