Sxnan opened a new issue, #778: URL: https://github.com/apache/flink-agents/issues/778
### Search before asking - [x] I searched in the [issues](https://github.com/apache/flink-agents/issues) and found nothing similar. ### Description Found during react_agent doc verification (#741). Collection of doc-quality improvements for `docs/content/docs/development/react_agent.md`: 1. **Overview punctuation** (line 27): trailing period missing on the sentence ending "the LLM will decide how to achieve the goal and take actions autonomously". 2. **Snippets are not self-contained** — `ReActAgent`, `ResourceDescriptor`, `ResourceName`, `Prompt`, `ChatMessage`, `MessageRole`, `BaseModel`, `RowTypeInfo`, `BasicTypeInfo` are all used without imports. The repo has `python/flink_agents/examples/quickstart/react_agent_example.py` and `examples/.../ReActAgentExample.java` as full runnable examples, but the doc never points at them. Add imports inside snippets and a "for an end-to-end example see ..." pointer at the top of the page. 3. **Tools must be pre-registered, but that step is missing from snippets** — the chat-model descriptor (lines 71-89) includes `tools=["my_tool1", "my_tool2"]`, which assumes those tools have already been registered on the `AgentsExecutionEnvironment` via `add_resource(...)` (or via a YAML file). A new user copying the snippet gets a "resource not found" error at runtime. Add a note showing the registration step. 4. **Prompt structure description is overly restrictive** (lines 96-97): > The prompt should contain two messages. The first message tells the > agent what to do, and gives the input and output example. The second > message tells how to convert input element to text string. `Prompt.format_messages` returns every message in the template (after substitution); the schema-prompt injection logic also tolerates a missing SYSTEM message (`find_first_system_message` returns `-1` and the schema prompt is prepended). The doc should describe the typical pattern as a recommendation rather than a hard constraint. 5. **Placeholder substitution rules are not explained** — the USER-message example uses `{id}` and `{review}` placeholders, but the doc never says where those names come from. From `ReActAgent.start_action`: - primitive input → single `{input}` placeholder - `Row` input → fields from `row.as_dict()` (Python) / `row.getFieldNames()` (Java) - `dict` input → keys directly - `BaseModel` / Pojo input → fields from the object's serialized form Add a small section describing how field names flow from the input element to the placeholders. 6. **"BaseModel or RowTypeInfo" misleads Java users** (line 183): > The output schema should be `BaseModel` or `RowTypeInfo`. `BaseModel` is Python-only. The Java tab actually uses a plain Pojo class (`MyBaseModelDataType.class`). Rephrase as "BaseModel (Python) / Pojo class (Java) / RowTypeInfo (both)" or move the line into per-language tabs. ### Where to fix `docs/content/docs/development/react_agent.md`. ### Version and environment Flink Agents 0.3.0 (`main`). ### Are you willing to submit a PR? - [ ] I'm willing to submit a PR! -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
