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

api/src/main/java/org/apache/flink/agents/api/Event.java

@@ -21,7 +21,13 @@
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.databind.DeserializationContext;
+import com.fasterxml.jackson.databind.JsonDeserializer;
+import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import org.apache.flink.agents.api.context.MemoryRef;
 
 import java.io.IOException;
 import java.util.HashMap;
@@ -38,6 +44,11 @@ public class Event {
     private final String type;
     private final Map<String, Object> attributes;
 
+    // Keep the annotation on the field as well as the creator parameter so it also applies when
+    // Jackson constructs Event subclasses whose creators do not declare attachments.
+    @JsonDeserialize(contentUsing = AttachmentValueDeserializer.class)
+    private final Map<String, Object> attachments;
+
     /**
      * Runtime-internal timestamp from the source record. Not part of the cross-language event
      * contract; used by the Flink runtime for timestamp propagation.
@@ -46,25 +57,36 @@ public class Event {
 
     /** Unified event with user-defined type and attributes. */
     public Event(String type, Map<String, Object> attributes) {
-        this(UUID.randomUUID(), type, attributes);
+        this(UUID.randomUUID(), type, attributes, new HashMap<>());
     }
 
     /** Unified event with user-defined type and empty attributes. */
     public Event(String type) {
         this(type, new HashMap<>());
     }
 
-    @JsonCreator
     public Event(
             @JsonProperty("id") UUID id,
             @JsonProperty("type") String type,
             @JsonProperty("attributes") Map<String, Object> attributes) {
+        this(id, type, attributes, new HashMap<>());
+    }
+
+    @JsonCreator
+    public Event(
+            @JsonProperty("id") UUID id,
+            @JsonProperty("type") String type,
+            @JsonProperty("attributes") Map<String, Object> attributes,
+            @JsonProperty("attachments")
+                    @JsonDeserialize(contentUsing = AttachmentValueDeserializer.class)
+                    Map<String, Object> attachments) {
         if (type == null || type.isEmpty()) {
             throw new IllegalArgumentException("Event 'type' must not be null or empty.");
         }
         this.id = id;
         this.type = type;
-        this.attributes = attributes != null ? attributes : new HashMap<>();
+        this.attributes = attributes != null ? new HashMap<>(attributes) : new HashMap<>();
+        this.attachments = attachments != null ? new HashMap<>(attachments) : new HashMap<>();
     }
 
     public UUID getId() {
@@ -81,6 +103,10 @@ public Map<String, Object> getAttributes() {
         return attributes;
     }
 
+    public Map<String, Object> getAttachments() {
+        return attachments;
+    }
+
     public Object getAttr(String name) {
         return attributes.get(name);
     }
@@ -89,6 +115,14 @@ public void setAttr(String name, Object value) {
         attributes.put(name, value);
     }
 
+    public Object getAttachment(String name) {
+        return attachments.get(name);
+    }
+
+    public void setAttachment(String name, Object value) {
+        attachments.put(name, value);
+    }
+
     @JsonIgnore
     public boolean hasSourceTimestamp() {
         return sourceTimestamp != null;
@@ -105,12 +139,17 @@ public void setSourceTimestamp(long timestamp) {
     }
 
     /**
-     * Creates a base Event from another Event, copying id, type, and attributes. Subclasses
-     * override this to reconstruct typed event objects with proper field deserialization.
+     * Creates a base Event from another Event, copying id, type, attributes, and attachments.
+     * Subclasses override this to reconstruct typed event objects with proper field
+     * deserialization.
      */
     public static Event fromEvent(Event event) {
         Event copy =
-                new Event(event.getId(), event.getType(), new HashMap<>(event.getAttributes()));
+                new Event(
+                        event.getId(),
+                        event.getType(),
+                        new HashMap<>(event.getAttributes()),
+                        new HashMap<>(event.attachments));
         if (event.hasSourceTimestamp()) {
             copy.setSourceTimestamp(event.getSourceTimestamp());
         }
@@ -128,18 +167,34 @@ public static Event fromJson(String json) throws IOException {
         return MAPPER.readValue(json, Event.class);
     }
 
+    /** Deserializes one attachment value, preserving explicitly tagged memory references. */
+    static final class AttachmentValueDeserializer extends JsonDeserializer<Object> {
+
+        @Override
+        public Object deserialize(JsonParser parser, DeserializationContext context)
+                throws IOException {
+            JsonNode node = parser.getCodec().readTree(parser);
+            if (node.isObject()
+                    && MemoryRef.TYPE_VALUE.equals(node.path(MemoryRef.TYPE_FIELD).asText())) {
+                return parser.getCodec().treeToValue(node, MemoryRef.class);
+            }
+            return parser.getCodec().treeToValue(node, Object.class);
+        }
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
         if (o == null || getClass() != o.getClass()) return false;
         Event other = (Event) o;
         return Objects.equals(this.id, other.id)
                 && Objects.equals(this.getType(), other.getType())
-                && Objects.equals(this.attributes, other.attributes);
+                && Objects.equals(this.attributes, other.attributes)
+                && Objects.equals(this.attachments, other.attachments);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(id, getType(), attributes);
+        return Objects.hash(id, getType(), attributes, attachments);
     }
 }

api/src/main/java/org/apache/flink/agents/api/InputEvent.java

@@ -51,6 +51,7 @@ public InputEvent(
      */
     public static InputEvent fromEvent(Event event) {
         InputEvent result = new InputEvent(event.getId(), new HashMap<>(event.getAttributes()));
+        result.getAttachments().putAll(event.getAttachments());
         if (event.hasSourceTimestamp()) {
             result.setSourceTimestamp(event.getSourceTimestamp());
         }

api/src/main/java/org/apache/flink/agents/api/OutputEvent.java

@@ -54,6 +54,7 @@ public OutputEvent(
      */
     public static OutputEvent fromEvent(Event event) {
         OutputEvent result = new OutputEvent(event.getId(), new HashMap<>(event.getAttributes()));
+        result.getAttachments().putAll(event.getAttachments());
         if (event.hasSourceTimestamp()) {
             result.setSourceTimestamp(event.getSourceTimestamp());
         }

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

@@ -17,17 +17,38 @@
  */
 package org.apache.flink.agents.api.context;
 
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.databind.DeserializationContext;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.SerializerProvider;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.fasterxml.jackson.databind.deser.std.StdDeserializer;
+import com.fasterxml.jackson.databind.ser.std.StdSerializer;
+
+import java.io.IOException;
 import java.io.Serializable;
+import java.util.LinkedHashMap;
+import java.util.Locale;
+import java.util.Map;
 import java.util.Objects;
 
 /**
  * A serializable, persistent reference to a specific data item in Short-Term Memory. It acts as a
  * lightweight pointer, containing the path of the data, allowing for efficient passing of large
  * objects between Actions.
  */
+@JsonSerialize(using = MemoryRef.Serializer.class)
+@JsonDeserialize(using = MemoryRef.Deserializer.class)
 public final class MemoryRef implements Serializable {
     private static final long serialVersionUID = 1L;
 
+    public static final String TYPE_FIELD = "@type";
+    public static final String TYPE_VALUE = "memory_ref";
+    public static final String MEMORY_TYPE_FIELD = "memory_type";
+    public static final String PATH_FIELD = "path";
+
     private final MemoryObject.MemoryType type;
     private final String path;
 
@@ -67,6 +88,55 @@ public String getPath() {
         return path;
     }
 
+    public MemoryObject.MemoryType getType() {
+        return type;
+    }
+
+    /** Serializes a {@link MemoryRef} to JSON. */
+    public static final class Serializer extends StdSerializer<MemoryRef> {
+
+        public Serializer() {
+            super(MemoryRef.class);
+        }
+
+        @Override
+        public void serialize(MemoryRef value, JsonGenerator generator, SerializerProvider provider)
+                throws IOException {
+            Map<String, String> serialized = new LinkedHashMap<>();
+            serialized.put(TYPE_FIELD, TYPE_VALUE);
+            serialized.put(MEMORY_TYPE_FIELD, value.getType().name().toLowerCase(Locale.ROOT));
+            serialized.put(PATH_FIELD, value.getPath());
+            generator.writeObject(serialized);
+        }
+    }
+
+    /** Deserializes a {@link MemoryRef} from JSON. */
+    public static final class Deserializer extends StdDeserializer<MemoryRef> {
+
+        public Deserializer() {
+            super(MemoryRef.class);
+        }
+
+        @Override
+        public MemoryRef deserialize(JsonParser parser, DeserializationContext context)
+                throws IOException {
+            JsonNode node = parser.getCodec().readTree(parser);
+            JsonNode typeNode = node.get(MEMORY_TYPE_FIELD);
+            JsonNode pathNode = node.get(PATH_FIELD);
+            if (typeNode == null || typeNode.isNull() || pathNode == null || pathNode.isNull()) {
+                throw new IllegalArgumentException(
+                        "MemoryRef JSON must contain non-null '"
+                                + MEMORY_TYPE_FIELD
+                                + "' and '"
+                                + PATH_FIELD
+                                + "' fields.");
+            }
+            MemoryObject.MemoryType memoryType =
+                    MemoryObject.MemoryType.valueOf(typeNode.asText().toUpperCase(Locale.ROOT));
+            return create(memoryType, pathNode.asText());
+        }
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;

api/src/main/java/org/apache/flink/agents/api/event/ChatRequestEvent.java

@@ -98,6 +98,7 @@ private static Map<String, Object> normalizeAttributes(Map<String, Object> attri
     public static ChatRequestEvent fromEvent(Event event) {
         ChatRequestEvent result =
                 new ChatRequestEvent(event.getId(), new HashMap<>(event.getAttributes()));
+        result.getAttachments().putAll(event.getAttachments());
         if (event.hasSourceTimestamp()) {
             result.setSourceTimestamp(event.getSourceTimestamp());
         }

api/src/main/java/org/apache/flink/agents/api/event/ChatResponseEvent.java

@@ -77,6 +77,7 @@ private static Map<String, Object> normalizeAttributes(Map<String, Object> attri
     public static ChatResponseEvent fromEvent(Event event) {
         ChatResponseEvent result =
                 new ChatResponseEvent(event.getId(), new HashMap<>(event.getAttributes()));
+        result.getAttachments().putAll(event.getAttachments());
         if (event.hasSourceTimestamp()) {
             result.setSourceTimestamp(event.getSourceTimestamp());
         }

api/src/main/java/org/apache/flink/agents/api/event/ContextRetrievalRequestEvent.java

@@ -62,6 +62,7 @@ public static ContextRetrievalRequestEvent fromEvent(Event event) {
         ContextRetrievalRequestEvent result =
                 new ContextRetrievalRequestEvent(
                         event.getId(), new HashMap<>(event.getAttributes()));
+        result.getAttachments().putAll(event.getAttachments());
         if (event.hasSourceTimestamp()) {
             result.setSourceTimestamp(event.getSourceTimestamp());
         }

api/src/main/java/org/apache/flink/agents/api/event/ContextRetrievalResponseEvent.java

@@ -85,6 +85,7 @@ public static ContextRetrievalResponseEvent fromEvent(Event event) {
         ContextRetrievalResponseEvent result =
                 new ContextRetrievalResponseEvent(
                         event.getId(), new HashMap<>(event.getAttributes()));
+        result.getAttachments().putAll(event.getAttachments());
         if (event.hasSourceTimestamp()) {
             result.setSourceTimestamp(event.getSourceTimestamp());
         }

api/src/main/java/org/apache/flink/agents/api/event/ToolRequestEvent.java

@@ -56,6 +56,7 @@ public ToolRequestEvent(
     public static ToolRequestEvent fromEvent(Event event) {
         ToolRequestEvent result =
                 new ToolRequestEvent(event.getId(), new HashMap<>(event.getAttributes()));
+        result.getAttachments().putAll(event.getAttachments());
         if (event.hasSourceTimestamp()) {
             result.setSourceTimestamp(event.getSourceTimestamp());
         }

api/src/main/java/org/apache/flink/agents/api/event/ToolResponseEvent.java

@@ -100,6 +100,7 @@ private static Map<String, Object> normalizeAttributes(Map<String, Object> attri
     public static ToolResponseEvent fromEvent(Event event) {
         ToolResponseEvent result =
                 new ToolResponseEvent(event.getId(), new HashMap<>(event.getAttributes()));
+        result.getAttachments().putAll(event.getAttachments());
         if (event.hasSourceTimestamp()) {
             result.setSourceTimestamp(event.getSourceTimestamp());
         }