sangkyoonnam opened a new pull request, #1356: URL: https://github.com/apache/flink-agents/pull/1356
Closes #1335. ### Purpose of change Callers can set a stable UID with `apply(agent, uid)` or `apply(agentName, uid)` so an upstream topology change does not change the agent operator's identity. Existing calls leave the UID unset. #### Runtime flow The remote builder validates and stores the UID, then passes it to `CompileUtils.connectToAgent`. Compilation sets it on the agent transformation. Python passes the value through the three-argument Java bridge. Table inputs and agents loaded from YAML use the same builders. #### Key decisions The UID belongs to the operator in a job, so it is supplied at `apply` rather than stored on the reusable agent. Existing Java signatures delegate with `null`; their graph construction stays unchanged. ### Behavioral Semantics #### Interaction decisions | Input | Agent selection | UID | Result | |---|---|---|---| | DataStream or Table | Instance or registered name | Non-blank string | Agent transformation has that UID | | DataStream or Table | Instance or registered name | Omitted or null/None | Existing generated operator ID | | DataStream or Table | Valid instance or registered name | Empty or whitespace | Rejected before graph construction | #### Behavioral contracts A supplied UID keeps the agent operator ID stable across changes to upstream topology. Different UIDs produce different IDs. Omitting the UID preserves existing generated IDs. The caller must keep UIDs unique within the job; Flink checks duplicates when building the graph. #### Failure behavior Blank UIDs raise `IllegalArgumentException` in Java and `ValueError` in Python. Python also rejects non-string values. Unknown agent names retain their existing error. Builders that do not override the new Java defaults throw `UnsupportedOperationException`. This adds no retry or recovery mechanism. Java remote builders now reject `apply` after the output stream has been built, with `IllegalStateException`, instead of accepting a configuration that the cached stream would ignore. The existing stream stays unchanged. Python already rejects repeated `apply` calls. ### Tests | Contract | Coverage | |---|---| | UID reaches the agent operator | `AgentOperatorUidTest`: instance, name, Table and loaded YAML; `CompileUtilsTest` overloads | | UID survives upstream topology changes | `sameUidKeepsOperatorIdAcrossUpstreamTopologyChange` | | Distinct UIDs give distinct IDs | `differentUidsGiveDifferentOperatorIds` | | Omitted/null UID preserves existing identity | `omittedUidLeavesGeneratedOperatorIdUnchanged`; before/after graph comparison against main | | Invalid UID fails early | Java parameterized tests; Python blank-UID tests | | Python forwards the UID | Remote builder tests for instance, name, Table, YAML and omitted UID | | Unsupported Java builder rejects the overload | `AgentBuilderApplyByNameTest` | | Built output cannot be silently reconfigured | `rejectsUidChangeAfterBuildingOutput`, `rejectsReapplyingWithoutUidAfterBuildingOutput`; pre-build reconfiguration control | The Python remote-environment suite passed 45 tests in three runs. The Java suite also passed 45 tests in three runs. The Python UID tests fail against main, and three Java reconfiguration cases fail before the guard. Formatting and the repository-pinned Ruff check passed. Not verified: restoring a running job from a savepoint, duplicate-UID rejection in a submitted job, and the full Python-to-Java bridge with a running cluster. Python forwarding tests mock the bridge; Java graph tests cover the receiving overloads. Adding a UID to an existing job does not migrate its saved state. ### API Adds default Java overloads `apply(Agent, String)` and `apply(String, String)`, and an optional Python `uid` parameter. Existing overloads remain available. UID support is for remote execution. ### Documentation - [ ] `doc-needed` - [ ] `doc-not-needed` - [x] `doc-included` Deployment documentation shows Java and Python usage and explains the savepoint migration limit. ### Was this patch authored or co-authored using generative AI tooling? - [x] Yes - [ ] No Generated-by: Claude Code (Claude Sonnet 5.5; tool version not recorded) Generated-by: Codex CLI 0.166.0 (GPT-6; exact model variant not exposed) -- 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]
