[Feature][api][runtime] Support auto resolve memory reference for passing data across actions.

[JinkunLiu]

Linked issue: #476

Purpose of change

Add event attachments with automatic MemoryRef wrapping and resolution

Tests

• Java and Python unit tests for resolving and restoring event attachments.
• Event serialization and deserialization tests.
• Cross-language snapshot tests covering Java-to-Python and Python-to-Java event conversion.
• End-to-end tests covering actions that consume and produce MemoryRef attachments.

API

• Add public APIs for event attachments in both Java and Python
• Add JSON serialization/deserialization support to MemoryRef.

Documentation

• doc-needed
  Add docs after review～
• doc-not-needed
• doc-included

[Copilot]

Pull request overview

This PR introduces Event attachments as a first-class, cross-language concept (Java + Python) and wires the runtime so that attachment payloads can be automatically stored as MemoryRefs when events are sent, then resolved back to concrete values before actions run, enabling efficient data passing across action boundaries.

Changes:

• Add an attachments map to the unified Event model in both Java and Python, plus (de)serialization support for MemoryRef in attachments.
• Add runtime utilities to store attachments into sensory memory (store_event_attachments) and resolve them back (load_event_attachments), integrated into both Java and Python runner contexts and the Python action executor bridge.
• Extend unit tests, cross-language snapshot tests, and add an end-to-end integration test covering attachment round-trips.

Reviewed changes

Copilot reviewed 49 out of 49 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
runtime/src/test/java/org/apache/flink/agents/runtime/memory/EventAttachmentUtilsTest.java	Adds Java unit tests for storing/loading attachments via sensory memory.
runtime/src/main/java/org/apache/flink/agents/runtime/python/utils/PythonActionExecutor.java	Resolves attachments on the Python side before invoking Python actions.
runtime/src/main/java/org/apache/flink/agents/runtime/operator/JavaActionTask.java	Resolves attachments before invoking Java actions.
runtime/src/main/java/org/apache/flink/agents/runtime/memory/EventAttachmentUtils.java	Implements Java-side attachment store/load utilities backed by sensory memory.
runtime/src/main/java/org/apache/flink/agents/runtime/context/RunnerContextImpl.java	Automatically stores attachments as MemoryRefs when sending events.
python/flink_agents/runtime/tests/test_event_attachment_utils.py	Adds Python unit tests for storing/loading attachments via sensory memory.
python/flink_agents/runtime/python_java_utils.py	Adds a helper invoked from Java to load attachments before Python actions.
python/flink_agents/runtime/memory/event_attachment_utils.py	Implements Python-side attachment store/load utilities backed by sensory memory.
python/flink_agents/runtime/flink_runner_context.py	Automatically stores attachments when sending events from Python.
python/flink_agents/e2e_tests/e2e_tests_integration/event_attachments_test.py	Adds an e2e test validating attachment round-trip through Flink execution.
python/flink_agents/api/tests/test_event.py	Extends Event API tests to cover attachments getters/setters and JSON behavior.
python/flink_agents/api/tests/test_cross_language_event_snapshots.py	Validates cross-language snapshots include a MemoryRef attachment.
python/flink_agents/api/memory_object.py	Adjusts MemoryType enum representation (notably SENSORY).
python/flink_agents/api/events/tool_event.py	Preserves attachments when reconstructing typed tool events from base events.
python/flink_agents/api/events/event.py	Adds attachments field + accessors; parses MemoryRef objects from JSON attachments.
python/flink_agents/api/events/context_retrieval_event.py	Preserves attachments when reconstructing typed context retrieval events.
python/flink_agents/api/events/chat_event.py	Preserves attachments when reconstructing typed chat events.
e2e-test/cross-language-event-snapshots/python/tool_response_event.json	Updates Python snapshot with attachments section.
e2e-test/cross-language-event-snapshots/python/tool_request_event.json	Updates Python snapshot with attachments section.
e2e-test/cross-language-event-snapshots/python/python_only_subclass_event.json	Updates Python snapshot with attachments section.
e2e-test/cross-language-event-snapshots/python/output_event.json	Updates Python snapshot with attachments section.
e2e-test/cross-language-event-snapshots/python/input_event.json	Updates Python snapshot with attachments section.
e2e-test/cross-language-event-snapshots/python/generic_event_with_attrs.json	Updates Python snapshot with attachments section.
e2e-test/cross-language-event-snapshots/python/context_retrieval_response_event.json	Updates Python snapshot with attachments section.
e2e-test/cross-language-event-snapshots/python/context_retrieval_request_event.json	Updates Python snapshot with attachments section.
e2e-test/cross-language-event-snapshots/python/chat_response_event.json	Updates Python snapshot with attachments section.
e2e-test/cross-language-event-snapshots/python/chat_request_event.json	Updates Python snapshot with attachments section.
e2e-test/cross-language-event-snapshots/java/tool_response_event.json	Updates Java snapshot with attachments section.
e2e-test/cross-language-event-snapshots/java/tool_request_event.json	Updates Java snapshot with attachments section.
e2e-test/cross-language-event-snapshots/java/output_event.json	Updates Java snapshot with attachments section.
e2e-test/cross-language-event-snapshots/java/input_event.json	Updates Java snapshot with attachments section.
e2e-test/cross-language-event-snapshots/java/generic_event_with_attrs.json	Updates Java snapshot with attachments section.
e2e-test/cross-language-event-snapshots/java/context_retrieval_response_event.json	Updates Java snapshot with attachments section.
e2e-test/cross-language-event-snapshots/java/context_retrieval_request_event.json	Updates Java snapshot with attachments section.
e2e-test/cross-language-event-snapshots/java/chat_response_event.json	Updates Java snapshot with attachments section.
e2e-test/cross-language-event-snapshots/java/chat_request_event.json	Updates Java snapshot with attachments section.
api/src/test/java/org/apache/flink/agents/api/EventTest.java	Adds Java tests ensuring attachments (including MemoryRef) survive JSON round-trips.
api/src/test/java/org/apache/flink/agents/api/CrossLanguageEventSnapshotTest.java	Extends Java cross-language snapshot tests to include MemoryRef attachments.
api/src/test/java/org/apache/flink/agents/api/context/MemoryRefJsonTest.java	Adds Java tests for MemoryRef JSON (de)serialization.
api/src/main/java/org/apache/flink/agents/api/OutputEvent.java	Copies attachments when converting from base Event.
api/src/main/java/org/apache/flink/agents/api/InputEvent.java	Copies attachments when converting from base Event.
api/src/main/java/org/apache/flink/agents/api/event/ToolResponseEvent.java	Copies attachments when converting from base Event.
api/src/main/java/org/apache/flink/agents/api/event/ToolRequestEvent.java	Copies attachments when converting from base Event.
api/src/main/java/org/apache/flink/agents/api/event/ContextRetrievalResponseEvent.java	Copies attachments when converting from base Event.
api/src/main/java/org/apache/flink/agents/api/event/ContextRetrievalRequestEvent.java	Copies attachments when converting from base Event.
api/src/main/java/org/apache/flink/agents/api/event/ChatResponseEvent.java	Copies attachments when converting from base Event.
api/src/main/java/org/apache/flink/agents/api/event/ChatRequestEvent.java	Copies attachments when converting from base Event.
api/src/main/java/org/apache/flink/agents/api/Event.java	Adds attachments field + accessors; converts attachment maps into MemoryRef on JSON load.
api/src/main/java/org/apache/flink/agents/api/context/MemoryRef.java	Adds JSON (de)serialization for MemoryRef including memory_type and path.

Suppressed comments (1)

api/src/main/java/org/apache/flink/agents/api/context/MemoryRef.java:143

• MemoryRef.equals/hashCode ignore type, so a SHORT_TERM ref and a SENSORY ref with the same path compare equal. With memory_type now part of the JSON representation and cross-language contract, equality should include both type and path to avoid collisions and incorrect map/set behavior.

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        MemoryRef memoryRef = (MemoryRef) o;
        return path.equals(memoryRef.path);
    }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[JinkunLiu]

Hello @wenjin272, Could you take a look at this PR when you have time? Thank you very much

[wenjin272]

Thanks for taking this on @JinkunLiu. I'll review it ASAP.