wenjin272 opened a new pull request, #1287: URL: https://github.com/apache/flink-agents/pull/1287
Related issues: #1258, #1137, #1080. ### Purpose of change Improve the Multi-Agent documentation for 0.4 and fix three Python issues exposed by checking its examples: internal children cannot resolve root resources, DataStream-to-Table conversion fails without an explicit TableEnvironment, and review aggregation divides by zero when no score is valid. The implementation description below covers the Python runtime and example changes. The documentation also clarifies registration, delegation, input schemas, external setups, sessions, results, recovery, monitoring and restrictions, with aligned Java/Python examples. #### Runtime flow - `RemoteAgentBuilder.t_env` creates a missing TableEnvironment from the input DataStream's execution environment and caches it. - `FlinkRunnerContext` gives each internal child's resource cache a reference to the root cache. Lookup checks the child first, then delegates missing registrations to the root. The root creates, caches and closes shared resources. - Review aggregation counts scores in 1–5 and calculates percentages from that count. When the count is zero, it returns five `0.0%` entries while preserving the review reasons. #### Key decisions Root fallback matches the Java child-scope behavior, including nested children. Delegating lookup instead of copying resources preserves root ownership and dependency resolution. Child overrides remain local. Table examples use the actual `pyflink.common.Row` input, and a prompt-action regression uses a real Row. ### Behavioral Semantics #### Interaction decisions | Conditions | Behavior | |---|---| | Child has the requested name and type, root also has it | Child registration wins. | | Child lacks the registration, root has it | Return the root-owned instance; nested children also fall back to the root. | | Neither scope has the name/type | Raise `KeyError`. | | Child provider fails, root has the same registration | Propagate the child error; do not fall back. | | TableEnvironment supplied / omitted | Preserve the supplied environment / create and cache one from the input stream; both schema and output-type declarations work. | | Valid scores mixed with invalid / no valid scores | Normalize over valid scores only / return all-zero percentages; preserve reasons in both cases. | #### Behavioral contracts - Sibling children share the same root resource instance. Closing a child does not close a borrowed root resource. - Child-owned dependencies resolve in the child scope; root-owned dependencies resolve in the root scope. - Nested children can use root connections, and child ReAct calls do not acquire the parent's private prompt. - Implicit Table output remains attached to the input job, and repeated access reuses the TableEnvironment. - Invalid scores do not enter the distribution denominator. Reasons remain available even when all scores are invalid. - Table review actions accept Row fields by name. #### Failure behavior Missing resources still raise `KeyError`; provider and resource-opening errors propagate rather than being hidden by fallback. Table planning/conversion errors retain their existing behavior. The aggregation guard handles only the zero-valid-score case; it does not add general input validation. These changes introduce no external-service retries or error suppression. ### Tests | Contract | Regression coverage | |---|---| | Shared instance and lifecycle ownership | `test_siblings_share_one_parent_instance_without_owning_it` | | Child override and child-scoped dependencies | `test_child_override_and_dependency_lookup_use_child_scope` | | Root-scoped dependencies | `test_shared_resource_dependencies_remain_in_the_root_scope` | | Name/type lookup and missing-resource errors | `test_missing_name_in_existing_type_falls_back_but_wrong_type_does_not` | | Provider failures propagate | `test_child_provider_failure_does_not_silently_fall_back` | | Runtime scope wiring, nesting and overrides | `test_new_child_scopes_can_resolve_root_resources`; parameterized `test_caller_driven_react_subagent` | | Model delegation and parent-prompt isolation | `test_model_driven_react_subagent_delegation` | | Table ownership, caching and explicit/implicit environment | Four cases of `test_datastream_to_table_uses_input_environment` | | Invalid-score denominator, zero count and reasons | Three cases of `test_score_distribution_ignores_out_of_range_scores` | | Row input | Table case in `test_prompt_driven_actions.py` | Validation completed on this change: - 161 focused Python tests for sub-agent APIs, plans and runtime behavior passed. - 13 real Flink sub-agent E2E tests passed, including shared connections, overrides, nesting and prompt isolation. - Four PyFlink Table-planning cases and an actual DataStream → Agent → Table job passed; six example unit cases passed. - Hugo build passed; 239 generated internal links/anchors had no broken targets, and 26 Python snippets parsed. - Ruff and `git diff --check` passed. Not verified: the full repository test suite, the Flink version matrix, live model/remote-agent services, or fresh Java snippet compilation. Real Flink validation used Flink 2.3, Python 3.11 and JDK 21. The documentation's recovery descriptions were checked against source and focused tests; this PR does not add a restart/failover E2E scenario. ### API No public Agent API or YAML format changes. `ResourceCache` gains an optional fallback cache. Python children that previously failed on root-only resources can now resolve them; existing child registrations retain precedence. Java behavior is unchanged. Table input remains Row; its documentation is corrected. The example retains its processing-time streaming windows. ### Documentation - [ ] `doc-needed` - [ ] `doc-not-needed` - [x] `doc-included` ### Was this patch authored or co-authored using generative AI tooling? - [x] Yes - [ ] No Generated-by: Codex CLI 0.153.4 (GPT-6) -- 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]
