[Feature] Cross Language Actions

[addu390]

Context

After #631 (event refactor) and #670 (Function descriptors), the runtime and plan layers already do most of the heavy lifting needed for cross-language actions. #622 covers what's left: pinning down the usage patterns and closing other gaps in SerDe, E2E Tests, Examples and Documentation.

What's already there

JavaFunction and PythonFunction data descriptors in both languages. add_action(func=Function) / addAction(Function) accept cross-language descriptors, and ActionExecutionOperator dispatches by instanceof JavaFunction vs PythonFunction. The YAML loader can already express cross-language actions via type: java|python + function: class:method.

So today, cross-language usage would look like:

class MyAgent(Agent):
    def __init__(self):
        super().__init__()
        self.add_action(
            name="handle",
            events=["my_event"],
            func=JavaFunction(
                qualname="com.example.Handlers",
                method_name="handle",
                parameter_types=["org.apache.flink.agents.api.Event",
                                 "org.apache.flink.agents.api.context.RunnerContext"],
            ),
        )

What's missing

Three gaps:

• Decorator parity. @action / @Action can't declare a foreign target today, only the imperative add_action can.
• SerDe inconsistencies. Either to fix the inconsistencies, or clearly call out the lack of support, backed by comprehensive cross-language tests on built-in events.
• E2E test coverage for cross-language actions. Nothing currently exercises a user-authored Java action consuming an event from a user-authored Python action (or vice versa). Built-in event SerDe is only partially exercised today through the resource path and needs comprehensive coverage to surface issues across all built-in events.

Standardizing the usage pattern

The imperative form already exists, the question is should we and what the decorator form looks like. Two options worth noting down:

Option A, descriptor object:

@action(events=["my_event"], target=JavaFunction(
    qualname="com.example.Handlers",
    method_name="handle",
    parameter_types=[...],
))
def handle(): ... 

Option B, string form (a bit out of convention in the code-base):

@action(events=["my_event"], target="java:com.example.Handlers#handle")
def handle(): ...

Java would mirror whichever shape we pick. Option A, although verbose would be more consistent with existing usage.

SerDe standardization

Cross-language actions work regardless of event payload format, but events also need to be cross-language-safe for the feature to be usable end-to-end. Once events cross the language boundary they go through JSON SerDe, and any built-in event whose Jackson form doesn't line up with its Pydantic form breaks the consumer.

Categories of mismatch worth checking are enum casing, field naming convention (camelCase vs snake_case), and optional/null handling.
The fix is to pick one wire format, snake_case fields, lowercase enum values, and annotate the Java side (@JsonValue on a lowercase accessor, or @JsonProperty per constant) to conform. Python is already in that shape.

So, two paths forward, not mutually exclusive:

• Audit the built-in events (ChatRequestEvent, ChatResponseEvent, ToolRequestEvent, etc.) and align both sides on the same wire format.
• For anything we choose not to support cross-language, document it explicitly and add tests that pin the boundary.

Either way, the gate is comprehensive cross-language tests on built-in events so this stops being a discovery problem.

Signature validation

Same-language signature validation already works (JavaFunction.checkSignature in Java, PythonFunction.check_signature in Python). The cross-language sides are empty stubs right now and worth filling those gaps for the full cross language support.

• Java's PythonFunction.checkSignature, no validation that the Python function takes (Event, RunnerContext).
• Python's JavaFunction.check_signature, no validation that the Java method signature matches the declared parameter_types.

Tests

For each built-in event, two directions: Java-emit / Python-consume and Python-emit / Java-consume. This is the matrix that would have caught the kind of SerDe mismatches discussed above, and is also what signature-validation regression tests sit on top of.

Open questions

• Preferred decorator shape, descriptor object or string or any other?
• Anything else worth surfacing before implementation starts?

[wzhero1]

Hi @addu390, wenjin272 is on vacation, so I'll take a look.

Overall direction looks good — I think this is ready to start. All three gaps (decorator parity, SerDe, E2E tests) are correctly identified and the proposed approach is reasonable. A few details on each gap below.

---

Gap 1 — Decorator parity details

Leaning Option A: it aligns with the existing imperative form add_action(func=JavaFunction(...)), and parameter_types stays a structured field. Option B's string form can't carry parameter_types; squeezing them in would just turn the string into a mini-DSL.

Two follow-ups for landing it:

1. Python @action backward compat

The snippet @action(events=["my_event"], target=...) doesn't actually work against today's signature def action(*listen_events: str) — Python varargs don't accept events= as a keyword, so existing @action("foo") usage would break. Suggest keeping varargs and adding a keyword-only target for zero breakage:

def action(*listen_events: str, *, target: Function | None = None) -> Callable: ...

2. Stub body convention

The def handle(): ... body decorated with @action(target=...) never runs — that's a new wrinkle the decorator form introduces (the imperative add_action doesn't have it since there's no method). Suggest the body be raise NotImplementedError("cross-language stub") so direct calls outside the framework (unit tests, debugging) fail loud rather than silently passing. pass / ... as a fallback.

---

Gap 2 — SerDe inconsistencies details

Pin down audit scope

The full set of built-in events in the repo is 8: InputEvent / OutputEvent / ChatRequest / ChatResponse / ToolRequest / ToolResponse / ContextRetrievalRequest / ContextRetrievalResponse. Suggest classifying each:

• Must support in 0.3: at least ChatRequest / ChatResponse (chat model main path)
• OK to defer past 0.3: probably ToolResponseEvent — both an attr-set divergence and a Map-type divergence (see below); not solvable by simple SerDe tweaks. Document the gap explicitly and add a boundary test pinning the "doesn't work cross-language" state to prevent regression

Wire format spec

The design's 3 categories (snake_case fields, lowercase enum values, optional/null handling) cover naming-level divergences (e.g. MessageRole "USER" vs "user", ChatMessage.toolCalls vs tool_calls).

Suggest adding two more rules to cover schema-level divergences:

• Attribute sets aligned on both sides — e.g. ToolResponseEvent Java has success / error / timestamp (ToolResponseEvent.java:46-49) that Python doesn't (tool_event.py:96-103).
• No Object / Any fallback; Map<K, V> must have matching K and V types — e.g. responses is Map<String, ToolResponse> on Java vs Dict[UUID, Any] on Python; ChatRequestEvent.outputSchema Java uses Object (ChatRequestEvent.java:42).

---

Gap 3 — E2E test coverage details

Test scope = the "must support" list from Gap 2

Test matrix should share the same event list as Gap 2's "must support" tier. Events Gap 2 defers (e.g. ToolResponseEvent) get a boundary test pinning the unsupported state instead of e2e.

Add a user-authored event axis

Built-in events alone aren't enough — user-authored events dominate cross-language action scenarios. Two cases:

• Event(type="my_custom", attributes={...primitive...}) — both sides use base Event
• User defines class MyEvent(Event) in Python with no Java counterpart — test Java-side fallback (base Event reception) degrades gracefully

Form: round-trip + JSON snapshot

Beyond round-trip e2e, also add JSON snapshot tests — pin a fixed wire-format JSON string and have both sides deserialize, then assert typed access. Snapshot turns Gap 2's wire format spec into an executable contract: spec changes → snapshot changes → CI enforces both sides stay in sync.

[addu390]

@wzhero1 Thanks for the added context, on the same page. While going over the implementation today, realized the biggest gap are the tests, so, I'd expect that to be the majority of the PR. I did raise an early PR: #709