[wenjin272]

Related issues: #1283

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
• doc-included

Was this patch authored or co-authored using generative AI tooling?

• Yes
• No

Generated-by: Codex CLI 0.153.4 (GPT-6)

[sangkyoonnam]

LGTM for the Python runtime and example changes; I didn't review the docs.

I checked Python against Java for lookup order, nested-scope fallback, ownership of inherited resources, and dependency resolution.

I ran the focused tests on a9878cf2: 48 passed in test_resource_cache_inheritance.py, test_eager_materialize.py, test_remote_execution_environment.py, test_multiple_agent_example.py and test_prompt_driven_actions.py. With resource_cache.py, flink_runner_context.py, remote_execution_environment.py and workflow_multiple_agent_example.py reverted to the merge base, 9 tests fail, covering resource fallback, lazy table-environment creation and aggregation with no valid scores.