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-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-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.

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.

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.

wenjin272

Hi, @addu390, thanks for your work.

Personally, I think this PR is nearly complete. I left one remaining comment. However, this PR has far-reaching implications, so I’ll also ask others to review it.

The current commit history is somewhat disorganized, which may make it difficult for others to review. If possible, please reorganize the commits. For example, organize the changes into two commits: one for event refactoring and another for test and example adaptations. Python and Java can also be separated.

wenjin272 · 2026-04-24T13:56:18Z

I think this should be changed to ChatRequestEvent.fromEvent(event). The same applies to other actions, including built-in actions, as well as actions in tests and examples. I've checked, and it seems that everything on the Python side has been handled.

addu390 · 2026-05-02T16:48:35Z

@wenjin272 Thanks again for the quick reviews, I have addressed the comments and organized the commits, do have a look again! And agreed on the far-reaching implications, @xintongsong could you do a review as well?

wenjin272

Hi, @addu390. Sorry for the delayed reply due to the holiday. I left a few comments regarding the details.

This PR introduces significant changes to the framework, please take a look at your convenience @xintongsong.

wenjin272 · 2026-05-06T08:37:29Z

@@ -41,7 +41,7 @@ public static Action getToolCallAction() throws Exception {
                        ToolCallAction.class,
                        "processToolRequest",
                        new Class[] {ToolRequestEvent.class, RunnerContext.class}),


Here, we constrain the first parameter of processToolRequest to be of type ToolRequestEvent. However, in cross-language invocations, only generic Event objects are passed rather than specific subclasses, which results in an argument type mismatch error.

I think this can be aligned with ChatModelAction by changing the parameter type to Event and calling ToolRequestEvent.fromEvent(event) within the function to convert the Event into a ToolRequestEvent.

Yes, that's the pattern. I thought I fixed this in all places, I'll do another full sweep again.

wenjin272 · 2026-05-06T08:50:33Z

+                }
+            }
+        }
+        return new ChatRequestEvent(model, messages, event.getAttr("output_schema"));


Here, we do not copy the event's id. Therefore, ChatRequestEvent generates a new random id, which causes the same ChatRequestEvent to have different id on the sender and receiver sides.

This issue also exists for other built-in Event subclasses.

wenjin272 · 2026-05-06T09:10:05Z

The purpose of ActionState is to enable action-level recovery after a job failover. However, the HashMap storing attributes does not guarantee strict consistency in key order before and after a JVM restart, which may lead to inconsistent UUIDs.

After the Event refactoring, it seems that there is no distinction made for InputEvent here. I think we can unify it into

return String.valueOf( UUID.nameUUIDFromBytes(MAPPER.writeValueAsBytes(event.getAttributes())));

And the MAPPER needs to have sorting enabled.

private static final ObjectMapper MAPPER = JsonMapper.builder() .configure(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS, true) .configure(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY, true) .build();

Nice find! Now that all event data lives in attributes, can unify the branches and use a sorted ObjectMapper for key ordering. Updated.

xintongsong

@addu390 @wenjin272

Thank you both for working on this. I have no more comments except for the following two.

xintongsong · 2026-05-06T13:15:58Z

 {{< tab "Python" >}}
 ```python
-@action(InputEvent)
+@action("_input_event")


In the documentation, we should also use InputEvent.EVENT_TYPE rather than the string literal. Please also check for other occurrences in the documentation.

xintongsong · 2026-05-06T13:16:12Z

@@ -41,7 +41,7 @@ public static Action getToolCallAction() throws Exception {
                        ToolCallAction.class,
                        "processToolRequest",
                        new Class[] {ToolRequestEvent.class, RunnerContext.class}),


xintongsong · 2026-05-06T13:26:04Z

    """

    id: UUID = Field(default=None)
+    type: str | None = Field(default=None)


Why do we allow type to be None?

Not anymore, I'll remove the None support.

addu390 · 2026-05-06T19:18:21Z

@wenjin272 @xintongsong Did a full cross-language consistency sweep, all @Action methods use base Event + fromEvent(), updated docs and JSON fixtures to match. And I resolved a few older comments, so, it's easier to track the open reviews/discussions.

@action

- Standardize Event on type strings and attributes map for cross-language interop - Add Event.fromEvent() base method; subclasses override for typed reconstruction - Store built-in event fields in attributes map with snake_case keys - Add @JsonIgnore on getters to prevent duplicate serialization - Move @JsonCreator type validation into Event constructor - Remove listenEvents() from @action annotation, use listenEventTypes() exclusively - Replace instanceof casts with EVENT_TYPE checks and fromEvent() in built-in actions - Remove EventContext.eventClass; simplify event log deserialization to base Event - Remove PythonEvent wrapper; use unified Event with JSON serde Co-authored-by: Cursor <cursoragent@cursor.com>

@action

- Update all @action annotations from listenEvents to listenEventTypes with EVENT_TYPE - Replace direct event casts with fromEvent() in e2e agents and test assertions - Update JSON test resources for new event format (type strings, attributes map) - Update documentation examples to use string-based event types Co-authored-by: Cursor <cursoragent@cursor.com>

@action

- Standardize Event on type strings and attributes dict for cross-language interop - Remove _type_registry auto-dispatch; require explicit SubClass.from_event() in actions - Add get_attr()/set_attr() to base Event; update property accessors to use them - Enforce string-only @action decorator arguments - Handle JSON round-trip for Row, MemoryRef, OutputSchema, and UUID keys - Remove cloudpickle dependency from event serialization path Co-authored-by: Cursor <cursoragent@cursor.com>

@action

- Update all @action decorators to use EVENT_TYPE string constants - Replace direct event attribute access with SubClass.from_event() pattern - Add return type annotations to staticmethod actions for linting compliance - Update test assertions and JSON resources for new event format Co-authored-by: Cursor <cursoragent@cursor.com>

…s and ActionState ordering

…on scope

wenjin272 · 2026-05-07T09:22:39Z

Hi, @addu390. Some @Action methods in the documentation were not using base Event + fromEvent(). Since they were scattered across various sections, I fixed them directly. Also fixed the conflicts with the main branch.

Thanks for your contribution, merged.

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 force-pushed the feature/custom-event-def-v3 branch from aff5f51 to 744e498 Compare April 17, 2026 23:51

wenjin272 mentioned this pull request Apr 19, 2026

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

Open

2 tasks

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

wenjin272 reviewed Apr 22, 2026

View reviewed changes

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

wenjin272 reviewed Apr 24, 2026

View reviewed changes

addu390 force-pushed the feature/custom-event-def-v3 branch from 42660b0 to 71bce68 Compare May 2, 2026 15:37

addu390 requested a review from wenjin272 May 2, 2026 15:58

addu390 force-pushed the feature/custom-event-def-v3 branch 2 times, most recently from 591b89e to 1389e87 Compare May 2, 2026 16:23

wenjin272 reviewed May 6, 2026

View reviewed changes

github-actions Bot added doc-included Your PR already contains the necessary documentation updates. and removed doc-needed Your PR changes impact docs. labels May 6, 2026

xintongsong reviewed May 6, 2026

View reviewed changes

addu390 requested a review from xintongsong May 6, 2026 17:21

addu390 requested a review from wenjin272 May 6, 2026 17:21

wenjin272 force-pushed the feature/custom-event-def-v3 branch from f4ee31e to 6b9ecb6 Compare May 7, 2026 09:05

addu390 and others added 12 commits May 7, 2026 17:06

Fix Java-Python Consistency for missed classes, use EVENT_TYPE in Doc…

1e127fb

…s and ActionState ordering

Run spotless

1f247bd

Full sweep of the entire cost base to use from_event, outside of Acti…

36b0859

…on scope

Full sweep of docs and test cases

06432e1

Full sweep of docs and test cases

cda53c5

Second sweep for updating docs to reflect to use from_event

b17fe07

Sweep for all JSON fixtures

85298bf

Full sweep of docs.

3f52c6b

wenjin272 force-pushed the feature/custom-event-def-v3 branch from 6b9ecb6 to 3f52c6b Compare May 7, 2026 09:06

fix compile error after rebase.

3b91ad8

wenjin272 approved these changes May 7, 2026

View reviewed changes

wenjin272 merged commit 071c3a0 into apache:main May 7, 2026
67 of 69 checks passed

wenjin272 mentioned this pull request May 7, 2026

[runtime] Support per-event-type configurable log levels for event log #609

Open

1 task

Conversation

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

Uh oh!

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!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

addu390 commented Apr 23, 2026

Uh oh!

wenjin272 commented Apr 24, 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!

addu390 commented May 2, 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!

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!

xintongsong 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

addu390 commented Apr 15, 2026 •

edited by wenjin272

Loading

wenjin272 left a comment •

edited

Loading

addu390 Apr 17, 2026 •

edited

Loading

wenjin272 commented May 7, 2026 •

edited

Loading