Cross Language Unified Event by addu390 · Pull Request #631 · apache/flink-agents

addu390 · 2026-04-15T15:04:44Z

Linked issue: #424

Purpose of change

Add unified event support. Users can create events with a type string and attributes map instead of defining subclasses. Enables string-based event routing and JSON-based cross-language transport. Migrates/removes backward compatible with existing subclassed events.

Tests

New unit tests in Java (EventTest, EventLogRecordJsonSerdeTest) and Python (test_event, test_decorators, test_agent_plan, test_local_execution_environment) covering unified event creation, serialization, routing, and backward compatibility.

API

Yes. Event class (Java/Python) gains type, attributes, getType()/get_type(). @Action annotation gains listenEventTypes().

More details about the design in the issue #424

Documentation

doc-needed
doc-not-needed
doc-included

addu390 · 2026-04-16T00:27:06Z

Hi @wenjin272, I closed the PR #561 and opened this.
I'll clean-up the PR a bit more, but up for a review otherwise.

Do take a first pass when you get a chance.

wenjin272

Hi, @addu390, thanks for you work. Refactoring the Event will have a significant impact on the framework; therefore, this work requires careful design and attention to numerous details. Thanks Again.

I think though some details still need to be addressed, the current Python event design aligns with my expectations, including

action listen to event.type
json based DeSer
remove PythonEvent in java, unified in Event
Subclasses of Event provide from_event method to validate and reconstruct specific event object.

However, the Java event design does not appear to be aligned with the Python approach. In fact, after completing the Event refactoring, we will continue to support cross-language usage of Actions. This means a Python event sent by a Python action may be delivered to a Java action. Therefore, Python events and Java events must maintain consistency in both design and usage.

By the way, there are some conflicts between the PR and the main branch, likely because the main branch was recently reformatted.

wenjin272 · 2026-04-16T13:54:14Z

     * @return Array of Event classes that this action listens to
     */
-    Class<? extends Event>[] listenEvents();
+    Class<? extends Event>[] listenEvents() default {};


On the Python side, actions only support listening to event string identifiers; on the Java side, we should align with this behavior.

wenjin272 · 2026-04-16T14:15:35Z

+     * @param eventJson JSON string with at least a {@code "type"} field
+     * @throws IOException if JSON parsing fails
+     */
+    public void sendUnifiedEvent(String eventJson) throws IOException {


I think the name sendUnifiedEvent is a bit ambiguous. I suggest renaming it to sendEventJson or sentPythonEvent.

wenjin272 · 2026-04-16T15:21:48Z

+    /** Returns the event type string used for routing. */
+    @JsonIgnore
+    public String getType() {
+        return type != null ? type : this.getClass().getName();


I think we can directly require that the type is not null, which would simplify the implementation of Event.

wenjin272 · 2026-04-16T15:23:51Z

+    private final String type;
    private final Map<String, Object> attributes;
    /** The timestamp of the source record. */
    private Long sourceTimestamp;


I think we can remove this field to keep the align between python Event and java Event

sourceTimestamp seems to be used in runtime for timestamp propagation (ActionExecutionOperator, RunnerContextImpl, JavaActionTask, etc.). Safe to remove?

I could however, specifically not use in the cross-language event contract, without any repercussions.

wenjin272 · 2026-04-16T15:36:49Z

+            attributes={
+                "model": model,
+                "messages": messages,
+                "output_schema": output_schema,


We need to ensure consistency between the built-in events on the Python and Java sides, so we must make the same changes on the Java side.

wenjin272 · 2026-04-17T02:34:01Z

+        Key-value properties for the event data.
    """

+    _type_registry: ClassVar[Dict[str, Type["Event"]]] = {}


It appears that this variable is intended to handle the deserialization of subclasses, but it is not currently in use. I think the Event class doesn't need to handle this; deserialization of subclass objects can be managed within the subclass's from_event method. Because subclasses may have certain non-trivial fields that require special handling during deserialization.

wenjin272 · 2026-04-17T02:40:18Z


 def test_action_decorator() -> None:  # noqa D103
-    @action(InputEvent)
+    @action("_input_event")


I think we can use InputEvent.EVENT_TYPE, and the same applies to other places where @action is used.

wenjin272 · 2026-04-17T02:45:33Z

+            err_msg = (
+                "Failed to send event '"
+                + event.get_type()
+                + "' to runner context"


I think we can also add the event json in err_msg.

wenjin272 · 2026-04-17T03:04:54Z

+    event = Event.from_json(event_json)
+    event_class = Event._type_registry.get(event.type)
+    if event_class is not None and hasattr(event_class, "from_event"):
+        return event_class.from_event(event)


Similar to my comment in Event, the framework does not need to be aware of the subclass types of Event. This would require the framework to handle many details of serialization and deserialization.
Fro subclass types of Event, user need use SubClass.from_event() to reconstruct the specific event object in action, like what you do in built-in tool call action and chat action.

addu390 · 2026-04-17T23:16:17Z

@wenjin272 Agreed on consistency between Java and Python, the reasoning was that it was quite a larger change, so, was considering having a follow-up PR.
However, It's a fair call-out, let me actually just do that too in this PR, doing so covers most of the review comments too.

…ex Python types

…UID keys

…vent() in actions

…ibutes field directly

addu390 · 2026-04-19T19:31:50Z

@wenjin272 Thanks again for the review! I’ve addressed the broader concern of consistency between Python and Java implementations, along side other review comments. Please take another look.

wenjin272

Hi, @addu390. I left some comments, mainly because Java's Event lacks the fromEvent method.

wenjin272 · 2026-04-22T02:48:35Z

+    @SuppressWarnings("unchecked")
    public List<ChatMessage> getMessages() {
-        return messages;
+        return (List<ChatMessage>) getAttr("messages");


In the python ChatRequestEvent, we deserialize the messages field in from_event method. But the java Event is missing corresponding method. This may cause ClassCastException.

wenjin272 · 2026-04-22T02:50:23Z


 /** Base class for all event types in the system. */
-public abstract class Event {
+public class Event {


The python Event contains a class method from_event. In this method, we will perform field validation and deserialization. However, Java's event lacks the corresponding method.

wenjin272 · 2026-04-22T02:54:43Z

+    public static Event fromJson(String json) throws IOException {
+        Event event = MAPPER.readValue(json, Event.class);
+        if (event.type == null || event.type.isEmpty()) {
+            throw new IllegalArgumentException("Event JSON must contain a 'type' field.");


I think we can move this validation to the construct method annotated @JsonCreator. This ensures that all code paths constructing an Event will enforce this validation.

wenjin272 · 2026-04-22T03:13:51Z

+     * The fully qualified Java class name used for deserialization. For unified events (no
+     * subclass), this is {@code "org.apache.flink.agents.api.Event"}.
+     */
+    private final String eventClass;


I think EventContext does not need to know the specific event class.

This information will enable us to restore the specific subclass type when reconstructing events from the event log. However, I believe there is no requirement to deserialize events from the event log. Furthermore, being aware of specific event classes will make the framework's implementation more complex.

I think that if users utilize event subclasses instead of the base event directly, they should be responsible for handling event deserialization, specifically by uniformly using from_event/fromEvent.

addu390 · 2026-04-23T21:15:30Z

@wenjin272 I have addressed the comments related to fromEvent, can you take an other pass when you get chance?

wenjin272 · 2026-04-24T06:56:12Z

@wenjin272 I have addressed the comments related to fromEvent, can you take an other pass when you get chance?

Sorry for the delay in reviewing — I'll get to this PR today or tomorrow.

github-actions Bot added doc-needed Your PR changes impact docs. fixVersion/0.3.0 The feature or bug should be implemented/fixed in the 0.3.0 version. priority/major Default priority of the PR or issue. labels Apr 15, 2026

addu390 changed the title ~~Feature/custom event def v3~~ Cross Language Unified Event Apr 15, 2026

github-actions Bot added doc-needed Your PR changes impact docs. and removed doc-needed Your PR changes impact docs. labels Apr 15, 2026

addu390 marked this pull request as ready for review April 16, 2026 00:24

wenjin272 reviewed Apr 17, 2026

View reviewed changes

addu390 added 15 commits April 17, 2026 19:43

Cross Language Unified Event

30faadb

Remove unnecessary comments

9abf12f

Fix lint errors

fe1145e

standardize on using the type string and json SerDe

04e8420

Fix JavaDoc from older descriptions

bdb82c2

Use ClassVar for event_type const

e09d136

Spotless, Used Imports and Doc Strings for Public Methods

ff9a4ab

Remove PythonEvent altogether and deprecate use of cloudPickle

bb40bff

Using subclass linting for cross language support

0c99140

Fix nested model deserialization after JSON event round-trip

e154a94

Use JSON Dump instead of Pydantic

52ee72a

Resolve multiple issues caused by JSON serialization flattening compl…

cacf364

…ex Python types

Fix cross-language JSON serde for Row, MemoryRef, OutputSchema, and U…

98f420f

…UID keys

Remove _type_registry auto-dispatch, require explicit SubClass.from_e…

1786cb6

…vent() in actions

Resolve conflicts and D102

744e498

addu390 force-pushed the feature/custom-event-def-v3 branch from aff5f51 to 744e498 Compare April 17, 2026 23:51

addu390 added 4 commits April 17, 2026 19:58

Fix linting errors

3ae9958

Run spotless

b9444a0

Manually fix spotless errors, no errors on local

9402b89

Fully reprecate listenEvents

d1e40e6

addu390 added 3 commits April 17, 2026 20:51

Manually fix spotless issues

1877fc6

Manually fix spotless issues

fbcb70a

Fix event type usage in Python

e812bfd

wenjin272 mentioned this pull request Apr 19, 2026

[Feature] Support auto resolve memory reference for passing data across actions. #476

Open

2 tasks

addu390 added 4 commits April 19, 2026 15:10

Use same DS in Java as Python, use get_attr instead of accessing attr…

427dea3

…ibutes field directly

Fix spotless issues manually

87d8e27

Fix spotless issues manually

6d98c4a

Fix spotless issues manually

3c4e279

addu390 requested a review from wenjin272 April 19, 2026 19:29

wenjin272 reviewed Apr 22, 2026

View reviewed changes

addu390 added 3 commits April 22, 2026 00:35

Add fromEvent() to Java event subclasses and simplify event log serde

648e433

Apply spotless

b59fa9b

Fix runtime tests and add @JsonIgnore

916518b

addu390 requested a review from wenjin272 April 22, 2026 15:47

Conversation

addu390 commented Apr 15, 2026

Purpose of change

Tests

API

Documentation

Uh oh!

addu390 commented Apr 16, 2026

Uh oh!

wenjin272 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

addu390 Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

addu390 commented Apr 17, 2026

Uh oh!

addu390 commented Apr 19, 2026

Uh oh!

wenjin272 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

addu390 commented Apr 23, 2026

Uh oh!

wenjin272 commented Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wenjin272 left a comment •

edited

Loading

addu390 Apr 17, 2026 •

edited

Loading