joeyutong commented on issue #1308: URL: https://github.com/apache/flink-agents/issues/1308#issuecomment-6331611854
### Four additional documentation findings from the walkthrough The following notes come from the second walkthrough at [`0c2388ac`](https://github.com/apache/flink-agents/commit/0c2388acc84a8620bfa0fc97b24fe5ede869b26d). The example-input newline issue was reported separately above. #### 1. Integrate with Flink: document the insert-only Table input requirement **Documentation:** [Table input section](https://github.com/apache/flink-agents/blob/0c2388acc84a8620bfa0fc97b24fe5ede869b26d/docs/content/docs/development/integrate_with_flink.md#L158-L242). The guide explains how to pass a Table to an Agent but does not state that the Table must produce insert-only changes. Internally, [Java fromTable](https://github.com/apache/flink-agents/blob/0c2388acc84a8620bfa0fc97b24fe5ede869b26d/runtime/src/main/java/org/apache/flink/agents/runtime/env/RemoteExecutionEnvironment.java#L164-L177) calls `tableEnv.toDataStream(inputTable)`; [Python from_table](https://github.com/apache/flink-agents/blob/0c2388acc84a8620bfa0fc97b24fe5ede869b26d/python/flink_agents/runtime/remote_execution_environment.py#L395-L413) uses the corresponding `to_data_stream`. **Verification and impact:** in a real Flink 2.3.0 streaming environment, replacing the sample values Table with `groupBy(name).select(name, avg(score))` causes `fromTable(...)` to reject the plan: ```text Table sink '*anonymous_datastream_sink$1*' doesn't support consuming update changes which is produced by node GroupAggregate(groupBy=[name], select=[name, AVG(score) AS EXPR$0]) ``` This rejection happens during Table-to-DataStream conversion, before a job or an Agent is executed. It is the existing conversion API's supported boundary, described in [Flink's Table/DataStream integration guide](https://nightlies.apache.org/flink/flink-docs-release-2.3/docs/dev/table/data_stream_api/#handling-of-insert-only-streams). **Suggested documentation fix:** > The input Table must be insert-only. Tables that produce update or delete changes, such as a continuously updating GROUP BY aggregation in streaming mode, cannot currently be passed directly to an Agent. Supporting update/delete semantics would be separate API/runtime work. The wording should describe the changelog requirement rather than prohibit all aggregations. #### 2. YAML Quickstart: the stated JSON output does not match the print sink **Documentation:** [expected output](https://github.com/apache/flink-agents/blob/0c2388acc84a8620bfa0fc97b24fe5ede869b26d/docs/content/docs/get-started/quickstart/yaml_agent.md#L378-L380) says that one JSON record per input review appears in the TaskManager output log. **Source evidence:** the [Python driver](https://github.com/apache/flink-agents/blob/0c2388acc84a8620bfa0fc97b24fe5ede869b26d/python/flink_agents/examples/quickstart/yaml_workflow_agent_example.py#L73-L87) directly prints the result stream. The Action emits a `ProductReviewAnalysisRes` model. The Java result class likewise has a [toString()](https://github.com/apache/flink-agents/blob/0c2388acc84a8620bfa0fc97b24fe5ede869b26d/examples/src/main/java/org/apache/flink/agents/examples/agents/CustomTypesAndResources.java#L182-L186) that produces `ProductReviewAnalysisRes{...}`. Neither example adds JSON serialization before printing. **Suggested minimal fix:** change the description to “one analysis result per input review,” ideally with a representative output. If JSON is intended, explicitly serialize the output. This is a low-priority output-description mismatch, confirmed by inspecting the result type and sink; it is not a claim that the full model-backed example was executed. #### 3. Single-Agent Quickstart: Python does not explicitly pin parallelism to one **Documentation:** [environment introduction](https://github.com/apache/flink-agents/blob/0c2388acc84a8620bfa0fc97b24fe5ede869b26d/docs/content/docs/get-started/quickstart/create-agent/single-agent.md#L48-L50) says that the job pins parallelism to one. **Source evidence:** the [Python example](https://github.com/apache/flink-agents/blob/0c2388acc84a8620bfa0fc97b24fe5ede869b26d/python/flink_agents/examples/quickstart/workflow_single_agent_example.py#L47-L54) creates the environment and limits async request threads, but contains no `env.set_parallelism(1)`. The Java example does set parallelism. In Python, the effective Flink parallelism therefore depends on the environment/cluster configuration; limiting async request threads is a different setting. **Suggested minimal fix:** add `env.set_parallelism(1)` to the Python snippet and runnable example, or narrow the shared wording. This is a low-priority consistency issue, not proof that every documented cluster runs with parallelism greater than one. #### 4. Quickstart landing page: browser title contains menu markup **Published page:** [Quickstart](https://nightlies.apache.org/flink/flink-agents-docs-main/docs/get-started/quickstart/). A direct HTTP fetch during the 2026-10-22 walkthrough found that the decoded HTML title contains: ```text <div style="font-weight:450;margin-bottom:0.5em">Quickstart</div> | Apache Flink Agents ``` The shared [title helper](https://github.com/apache/flink-agents/blob/0c2388acc84a8620bfa0fc97b24fe5ede869b26d/docs/layouts/partials/docs/title.html#L37-L41) wraps bold titles in a div. The style markup consequently leaks into the browser title. **Suggested fix:** keep the browser title plain text and apply menu styling in the menu rendering path. This is a minor presentation issue and does not block the examples. **Verification scope:** item 1 includes an actual planner rejection; items 2–3 are documentation/source consistency checks; item 4 is based on directly fetched published HTML. Full Ollama-backed Quickstart execution remains unverified because no model service was available. -- 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]
