You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by xt...@apache.org on 2025/08/07 02:46:20 UTC

(flink-agents) branch main updated: [api][java] Support DataStream / Table as input / output of Flink Agents in Java (#85)

This is an automated email from the ASF dual-hosted git repository.

xtsong pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-agents.git


The following commit(s) were added to refs/heads/main by this push:
     new 6278185  [api][java] Support DataStream / Table as input / output of Flink Agents in Java (#85)
6278185 is described below

commit 6278185bae68615366ae70a654b50ba6f8b04299
Author: Letao Jiang <le...@users.noreply.github.com>
AuthorDate: Wed Aug 6 19:46:15 2025 -0700

    [api][java] Support DataStream / Table as input / output of Flink Agents in Java (#85)
---
 api/pom.xml                                        |  18 +++
 .../org/apache/flink/agents/api/AgentBuilder.java  |  75 ++++++++++
 .../agents/api/AgentsExecutionEnvironment.java     | 161 +++++++++++++++++++++
 examples/pom.xml                                   |  18 +++
 .../examples/DataStreamIntegrationExample.java     |  97 +++++++++++++
 .../apache/flink/agents/examples/SimpleAgent.java  |  82 +++++++++++
 .../agents/examples/TableIntegrationExample.java   |  94 ++++++++++++
 runtime/pom.xml                                    |  12 ++
 .../runtime/env/RemoteExecutionEnvironment.java    | 154 ++++++++++++++++++++
 9 files changed, 711 insertions(+)

diff --git a/api/pom.xml b/api/pom.xml
index 512895a..5ea43c9 100644
--- a/api/pom.xml
+++ b/api/pom.xml
@@ -35,6 +35,24 @@ under the License.
             <version>${flink.version}</version>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+            <groupId>org.apache.flink</groupId>
+            <artifactId>flink-streaming-java</artifactId>
+            <version>${flink.version}</version>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.flink</groupId>
+            <artifactId>flink-table-api-java</artifactId>
+            <version>${flink.version}</version>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.flink</groupId>
+            <artifactId>flink-table-api-java-bridge</artifactId>
+            <version>${flink.version}</version>
+            <scope>provided</scope>
+        </dependency>
     </dependencies>
 
 </project>
\ No newline at end of file
diff --git a/api/src/main/java/org/apache/flink/agents/api/AgentBuilder.java b/api/src/main/java/org/apache/flink/agents/api/AgentBuilder.java
new file mode 100644
index 0000000..3d317c6
--- /dev/null
+++ b/api/src/main/java/org/apache/flink/agents/api/AgentBuilder.java
@@ -0,0 +1,75 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.agents.api;
+
+import org.apache.flink.streaming.api.datastream.DataStream;
+import org.apache.flink.table.api.Schema;
+import org.apache.flink.table.api.Table;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Builder interface for integrating agents with input and output.
+ *
+ * <p>This interface provides a fluent API for configuring agents and producing different types of
+ * outputs from agent execution.
+ */
+public interface AgentBuilder {
+
+    /**
+     * Set agent of AgentBuilder.
+     *
+     * @param agent The agent user defined to run in execution environment.
+     * @return A configured AgentBuilder for method chaining.
+     */
+    AgentBuilder apply(Agent agent);
+
+    /**
+     * Get output list of agent execution.
+     *
+     * <p>The elements in the list represent outputs produced by the agent. Each element is a Map
+     * with key-value pairs where the key represents the identifier for the input data and the value
+     * is the agent's output. This method is primarily used for local execution environments.
+     *
+     * @return List of Map containing outputs from agent execution in the format {key: output}.
+     */
+    List<Map<String, Object>> toList();
+
+    /**
+     * Get output DataStream of agent execution.
+     *
+     * <p>This method converts the agent's output events into a Flink DataStream that can be further
+     * processed in the Flink pipeline.
+     *
+     * @return DataStream containing outputs from agent execution.
+     */
+    DataStream<Object> toDataStream();
+
+    /**
+     * Get output Table of agent execution.
+     *
+     * <p>This method converts the agent's output events into a Flink Table using the provided
+     * schema for structure definition.
+     *
+     * @param schema Schema indicating the structure of the output table.
+     * @return Table containing outputs from agent execution.
+     */
+    Table toTable(Schema schema);
+}
diff --git a/api/src/main/java/org/apache/flink/agents/api/AgentsExecutionEnvironment.java b/api/src/main/java/org/apache/flink/agents/api/AgentsExecutionEnvironment.java
new file mode 100644
index 0000000..e01e0a4
--- /dev/null
+++ b/api/src/main/java/org/apache/flink/agents/api/AgentsExecutionEnvironment.java
@@ -0,0 +1,161 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.agents.api;
+
+import org.apache.flink.api.java.functions.KeySelector;
+import org.apache.flink.streaming.api.datastream.DataStream;
+import org.apache.flink.streaming.api.environment.StreamExecutionEnvironment;
+import org.apache.flink.table.api.Table;
+import org.apache.flink.table.api.bridge.java.StreamTableEnvironment;
+
+import java.util.List;
+
+/**
+ * Base class for agent execution environment.
+ *
+ * <p>This class provides the main entry point for integrating Flink Agents with different types of
+ * Flink data sources (DataStream, Table, or simple lists).
+ */
+public abstract class AgentsExecutionEnvironment {
+
+    /**
+     * Get agents execution environment.
+     *
+     * <p>Factory method that creates an appropriate execution environment based on the provided
+     * StreamExecutionEnvironment. If no environment is provided, a local execution environment is
+     * returned for testing and development.
+     *
+     * <p>When integrating with Flink DataStream/Table APIs, users should pass the Flink
+     * StreamExecutionEnvironment to enable remote execution capabilities.
+     *
+     * @param env Optional StreamExecutionEnvironment for remote execution. If null, a local
+     *     execution environment will be created.
+     * @return AgentsExecutionEnvironment appropriate for the execution context.
+     */
+    public static AgentsExecutionEnvironment getExecutionEnvironment(
+            StreamExecutionEnvironment env) {
+        if (env == null) {
+            // Return local execution environment for testing/development
+            try {
+                Class<?> localEnvClass =
+                        Class.forName(
+                                "org.apache.flink.agents.runtime.env.LocalExecutionEnvironment");
+                return (AgentsExecutionEnvironment)
+                        localEnvClass.getDeclaredConstructor().newInstance();
+            } catch (Exception e) {
+                throw new RuntimeException("Failed to create LocalExecutionEnvironment", e);
+            }
+        } else {
+            // Return remote execution environment for Flink integration
+            try {
+                Class<?> remoteEnvClass =
+                        Class.forName(
+                                "org.apache.flink.agents.runtime.env.RemoteExecutionEnvironment");
+                return (AgentsExecutionEnvironment)
+                        remoteEnvClass
+                                .getDeclaredConstructor(StreamExecutionEnvironment.class)
+                                .newInstance(env);
+            } catch (Exception e) {
+                throw new RuntimeException("Failed to create RemoteExecutionEnvironment", e);
+            }
+        }
+    }
+
+    /**
+     * Convenience method to get execution environment without Flink integration.
+     *
+     * @return Local execution environment for testing and development.
+     */
+    public static AgentsExecutionEnvironment getExecutionEnvironment() {
+        return getExecutionEnvironment(null);
+    }
+
+    /**
+     * Set input for agents from a list. Used for local execution.
+     *
+     * <p>The input list elements should be objects that will be wrapped in InputEvent instances and
+     * processed by the agent.
+     *
+     * @param input List of input objects for agent processing.
+     * @return AgentBuilder for configuring the agent pipeline.
+     */
+    public abstract AgentBuilder fromList(List<Object> input);
+
+    /**
+     * Set input for agents from a DataStream. Used for remote execution.
+     *
+     * <p>This method integrates agents with Flink DataStream API, allowing agents to process
+     * streaming data with optional keying for stateful operations.
+     *
+     * @param input DataStream to be processed by agents.
+     * @param keySelector Optional KeySelector for extracting keys from input records. If null, the
+     *     stream will be processed without keying.
+     * @param <T> Type of elements in the input DataStream.
+     * @param <K> Type of the key extracted by the KeySelector.
+     * @return AgentBuilder for configuring the agent pipeline.
+     */
+    public abstract <T, K> AgentBuilder fromDataStream(
+            DataStream<T> input, KeySelector<T, K> keySelector);
+
+    /**
+     * Set input for agents from a DataStream without keying.
+     *
+     * @param input DataStream to be processed by agents.
+     * @param <T> Type of elements in the input DataStream.
+     * @return AgentBuilder for configuring the agent pipeline.
+     */
+    public <T> AgentBuilder fromDataStream(DataStream<T> input) {
+        return fromDataStream(input, null);
+    }
+
+    /**
+     * Set input for agents from a Table. Used for remote execution.
+     *
+     * <p>This method integrates agents with Flink Table API, converting the table to a DataStream
+     * and processing it through agents.
+     *
+     * @param input Table to be processed by agents.
+     * @param tableEnv StreamTableEnvironment for table-to-stream conversion.
+     * @param keySelector Optional KeySelector for extracting keys from table rows.
+     * @param <K> Type of the key extracted by the KeySelector.
+     * @return AgentBuilder for configuring the agent pipeline.
+     */
+    public abstract <K> AgentBuilder fromTable(
+            Table input, StreamTableEnvironment tableEnv, KeySelector<Object, K> keySelector);
+
+    /**
+     * Set input for agents from a Table without keying.
+     *
+     * @param input Table to be processed by agents.
+     * @param tableEnv StreamTableEnvironment for table-to-stream conversion.
+     * @return AgentBuilder for configuring the agent pipeline.
+     */
+    public AgentBuilder fromTable(Table input, StreamTableEnvironment tableEnv) {
+        return fromTable(input, tableEnv, null);
+    }
+
+    /**
+     * Execute agent pipeline.
+     *
+     * <p>This method triggers the execution of the configured agent pipeline. For local
+     * environments, this runs the agent locally. For remote environments, this delegates to the
+     * underlying Flink execution environment.
+     */
+    public abstract void execute() throws Exception;
+}
diff --git a/examples/pom.xml b/examples/pom.xml
index fa098f3..3ef7c58 100644
--- a/examples/pom.xml
+++ b/examples/pom.xml
@@ -28,4 +28,22 @@ under the License.
     <artifactId>flink-agents-examples</artifactId>
     <name>Flink Agents : Examples</name>
 
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.flink</groupId>
+            <artifactId>flink-agents-api</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.flink</groupId>
+            <artifactId>flink-streaming-java</artifactId>
+            <version>1.18.0</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.flink</groupId>
+            <artifactId>flink-table-api-java-bridge</artifactId>
+            <version>1.18.0</version>
+        </dependency>
+    </dependencies>
+
 </project>
\ No newline at end of file
diff --git a/examples/src/main/java/org/apache/flink/agents/examples/DataStreamIntegrationExample.java b/examples/src/main/java/org/apache/flink/agents/examples/DataStreamIntegrationExample.java
new file mode 100644
index 0000000..c095d61
--- /dev/null
+++ b/examples/src/main/java/org/apache/flink/agents/examples/DataStreamIntegrationExample.java
@@ -0,0 +1,97 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.agents.examples;
+
+import org.apache.flink.agents.api.AgentsExecutionEnvironment;
+import org.apache.flink.api.java.functions.KeySelector;
+import org.apache.flink.streaming.api.datastream.DataStream;
+import org.apache.flink.streaming.api.environment.StreamExecutionEnvironment;
+
+/**
+ * Example demonstrating how to integrate Flink Agents with DataStream API.
+ *
+ * <p>This example shows how to:
+ *
+ * <ul>
+ *   <li>Create a DataStream from a collection
+ *   <li>Apply an agent to process the stream
+ *   <li>Extract output as another DataStream
+ *   <li>Execute the pipeline
+ * </ul>
+ */
+public class DataStreamIntegrationExample {
+
+    /** Simple data class for the example. */
+    public static class ItemData {
+        public final int id;
+        public final String name;
+        public final double value;
+
+        public ItemData(int id, String name, double value) {
+            this.id = id;
+            this.name = name;
+            this.value = value;
+        }
+
+        @Override
+        public String toString() {
+            return String.format("ItemData{id=%d, name='%s', value=%.2f}", id, name, value);
+        }
+    }
+
+    /** Key selector for extracting keys from ItemData. */
+    public static class ItemKeySelector implements KeySelector<ItemData, Integer> {
+        @Override
+        public Integer getKey(ItemData item) {
+            return item.id;
+        }
+    }
+
+    public static void main(String[] args) throws Exception {
+        // Create the execution environment
+        StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment();
+        env.setParallelism(1);
+
+        // Create input DataStream
+        DataStream<ItemData> inputStream =
+                env.fromElements(
+                        new ItemData(1, "item1", 10.5),
+                        new ItemData(2, "item2", 20.0),
+                        new ItemData(3, "item3", 15.7),
+                        new ItemData(1, "item1_updated", 12.3),
+                        new ItemData(2, "item2_updated", 22.1));
+
+        // Create agents execution environment
+        AgentsExecutionEnvironment agentsEnv =
+                AgentsExecutionEnvironment.getExecutionEnvironment(env);
+
+        // Apply agent to the DataStream
+        DataStream<Object> outputStream =
+                agentsEnv
+                        .fromDataStream(inputStream, new ItemKeySelector())
+                        .apply(new SimpleAgent())
+                        .toDataStream();
+
+        // Print the results
+        outputStream.print();
+
+        // Execute the pipeline
+        agentsEnv.execute();
+    }
+}
diff --git a/examples/src/main/java/org/apache/flink/agents/examples/SimpleAgent.java b/examples/src/main/java/org/apache/flink/agents/examples/SimpleAgent.java
new file mode 100644
index 0000000..e992d7a
--- /dev/null
+++ b/examples/src/main/java/org/apache/flink/agents/examples/SimpleAgent.java
@@ -0,0 +1,82 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.agents.examples;
+
+import org.apache.flink.agents.api.Action;
+import org.apache.flink.agents.api.Agent;
+import org.apache.flink.agents.api.Event;
+import org.apache.flink.agents.api.InputEvent;
+import org.apache.flink.agents.api.OutputEvent;
+import org.apache.flink.agents.api.context.RunnerContext;
+
+/**
+ * A simple example agent that demonstrates basic agent functionality.
+ *
+ * <p>This agent processes input events by adding a prefix to the input data and emitting an output
+ * event.
+ */
+public class SimpleAgent extends Agent {
+
+    /** Custom event type for internal agent communication. */
+    public static class ProcessedEvent extends Event {
+        private final String processedData;
+
+        public ProcessedEvent(String processedData) {
+            this.processedData = processedData;
+        }
+
+        public String getProcessedData() {
+            return processedData;
+        }
+    }
+
+    /**
+     * Action that processes incoming input events.
+     *
+     * @param event The input event to process
+     * @param ctx The runner context for sending events
+     */
+    @Action(listenEvents = {InputEvent.class})
+    public void processInput(Event event, RunnerContext ctx) {
+        InputEvent inputEvent = (InputEvent) event;
+        Object input = inputEvent.getInput();
+
+        // Process the input data
+        String processedData = "Processed: " + input.toString();
+
+        // Send a custom event for further processing
+        ctx.sendEvent(new ProcessedEvent(processedData));
+    }
+
+    /**
+     * Action that handles processed events and generates output.
+     *
+     * @param event The processed event
+     * @param ctx The runner context for sending events
+     */
+    @Action(listenEvents = {ProcessedEvent.class})
+    public void generateOutput(Event event, RunnerContext ctx) {
+        ProcessedEvent processedEvent = (ProcessedEvent) event;
+        String processedData = processedEvent.getProcessedData();
+
+        // Generate final output
+        String output = processedData + " [Agent Complete]";
+        ctx.sendEvent(new OutputEvent(output));
+    }
+}
diff --git a/examples/src/main/java/org/apache/flink/agents/examples/TableIntegrationExample.java b/examples/src/main/java/org/apache/flink/agents/examples/TableIntegrationExample.java
new file mode 100644
index 0000000..957e347
--- /dev/null
+++ b/examples/src/main/java/org/apache/flink/agents/examples/TableIntegrationExample.java
@@ -0,0 +1,94 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.agents.examples;
+
+import org.apache.flink.agents.api.AgentsExecutionEnvironment;
+import org.apache.flink.api.java.functions.KeySelector;
+import org.apache.flink.streaming.api.environment.StreamExecutionEnvironment;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.Schema;
+import org.apache.flink.table.api.Table;
+import org.apache.flink.table.api.bridge.java.StreamTableEnvironment;
+import org.apache.flink.types.Row;
+
+/**
+ * Example demonstrating how to integrate Flink Agents with Table API.
+ *
+ * <p>This example shows how to:
+ *
+ * <ul>
+ *   <li>Create a Table from sample data
+ *   <li>Apply an agent to process the table
+ *   <li>Extract output as another Table
+ *   <li>Execute the pipeline
+ * </ul>
+ */
+public class TableIntegrationExample {
+
+    /** Key selector for extracting keys from Row objects. */
+    public static class RowKeySelector implements KeySelector<Object, Integer> {
+        @Override
+        public Integer getKey(Object value) {
+            if (value instanceof Row) {
+                Row row = (Row) value;
+                return (Integer) row.getField(0); // Assuming first field is the ID
+            }
+            return 0;
+        }
+    }
+
+    public static void main(String[] args) throws Exception {
+        // Create the execution environment
+        StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment();
+        env.setParallelism(1);
+
+        // Create the table environment
+        StreamTableEnvironment tableEnv = StreamTableEnvironment.create(env);
+
+        // Create input table from sample data
+        Table inputTable =
+                tableEnv.fromValues(
+                        DataTypes.ROW(
+                                DataTypes.FIELD("id", DataTypes.INT()),
+                                DataTypes.FIELD("name", DataTypes.STRING()),
+                                DataTypes.FIELD("score", DataTypes.DOUBLE())),
+                        Row.of(1, "Alice", 85.5),
+                        Row.of(2, "Bob", 92.0),
+                        Row.of(3, "Charlie", 78.3),
+                        Row.of(1, "Alice", 87.2),
+                        Row.of(2, "Bob", 94.1));
+
+        // Create agents execution environment
+        AgentsExecutionEnvironment agentsEnv =
+                AgentsExecutionEnvironment.getExecutionEnvironment(env);
+
+        // Define output schema
+        Schema outputSchema = Schema.newBuilder().column("result", DataTypes.STRING()).build();
+
+        // Apply agent to the Table
+        Table outputTable =
+                agentsEnv
+                        .fromTable(inputTable, tableEnv, new RowKeySelector())
+                        .apply(new SimpleAgent())
+                        .toTable(outputSchema);
+
+        // Print the results
+        outputTable.execute().print();
+    }
+}
diff --git a/runtime/pom.xml b/runtime/pom.xml
index 387db96..3e5395b 100644
--- a/runtime/pom.xml
+++ b/runtime/pom.xml
@@ -74,6 +74,18 @@ under the License.
             <version>${flink.version}</version>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+            <groupId>org.apache.flink</groupId>
+            <artifactId>flink-table-api-java</artifactId>
+            <version>${flink.version}</version>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.flink</groupId>
+            <artifactId>flink-table-api-java-bridge</artifactId>
+            <version>${flink.version}</version>
+            <scope>provided</scope>
+        </dependency>
         <dependency>
             <groupId>org.apache.flink</groupId>
             <artifactId>flink-test-utils-junit</artifactId>
diff --git a/runtime/src/main/java/org/apache/flink/agents/runtime/env/RemoteExecutionEnvironment.java b/runtime/src/main/java/org/apache/flink/agents/runtime/env/RemoteExecutionEnvironment.java
new file mode 100644
index 0000000..424c2fd
--- /dev/null
+++ b/runtime/src/main/java/org/apache/flink/agents/runtime/env/RemoteExecutionEnvironment.java
@@ -0,0 +1,154 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.agents.runtime.env;
+
+import org.apache.flink.agents.api.Agent;
+import org.apache.flink.agents.api.AgentBuilder;
+import org.apache.flink.agents.api.AgentsExecutionEnvironment;
+import org.apache.flink.agents.plan.AgentPlan;
+import org.apache.flink.agents.runtime.CompileUtils;
+import org.apache.flink.api.java.functions.KeySelector;
+import org.apache.flink.streaming.api.datastream.DataStream;
+import org.apache.flink.streaming.api.environment.StreamExecutionEnvironment;
+import org.apache.flink.table.api.Schema;
+import org.apache.flink.table.api.Table;
+import org.apache.flink.table.api.bridge.java.StreamTableEnvironment;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Implementation of AgentsExecutionEnvironment for remote execution with Flink.
+ *
+ * <p>This environment integrates agents with Flink's streaming runtime, enabling agents to process
+ * DataStreams and Tables within a Flink cluster.
+ */
+public class RemoteExecutionEnvironment extends AgentsExecutionEnvironment {
+
+    private final StreamExecutionEnvironment env;
+
+    public RemoteExecutionEnvironment(StreamExecutionEnvironment env) {
+        this.env = env;
+    }
+
+    @Override
+    public AgentBuilder fromList(List<Object> input) {
+        throw new UnsupportedOperationException(
+                "RemoteExecutionEnvironment does not support fromList. Use fromDataStream or fromTable instead.");
+    }
+
+    @Override
+    public <T, K> AgentBuilder fromDataStream(DataStream<T> input, KeySelector<T, K> keySelector) {
+        return new RemoteAgentBuilder<>(input, keySelector, env);
+    }
+
+    @Override
+    public <K> AgentBuilder fromTable(
+            Table input, StreamTableEnvironment tableEnv, KeySelector<Object, K> keySelector) {
+        return new RemoteAgentBuilder<>(input, tableEnv, keySelector, env);
+    }
+
+    @Override
+    public void execute() throws Exception {
+        env.execute();
+    }
+
+    /** Implementation of AgentBuilder for remote execution environment. */
+    private static class RemoteAgentBuilder<T, K> implements AgentBuilder {
+
+        private final DataStream<T> inputDataStream;
+        private final KeySelector<T, K> keySelector;
+        private final StreamExecutionEnvironment env;
+        private final StreamTableEnvironment tableEnv;
+
+        private AgentPlan agentPlan;
+        private DataStream<Object> outputDataStream;
+
+        // Constructor for DataStream input
+        public RemoteAgentBuilder(
+                DataStream<T> inputDataStream,
+                KeySelector<T, K> keySelector,
+                StreamExecutionEnvironment env) {
+            this.inputDataStream = inputDataStream;
+            this.keySelector = keySelector;
+            this.env = env;
+            this.tableEnv = null;
+        }
+
+        // Constructor for Table input
+        @SuppressWarnings("unchecked")
+        public RemoteAgentBuilder(
+                Table inputTable,
+                StreamTableEnvironment tableEnv,
+                KeySelector<Object, K> keySelector,
+                StreamExecutionEnvironment env) {
+            this.inputDataStream = (DataStream<T>) tableEnv.toDataStream(inputTable);
+            this.keySelector = (KeySelector<T, K>) keySelector;
+            this.env = env;
+            this.tableEnv = tableEnv;
+        }
+
+        @Override
+        public AgentBuilder apply(Agent agent) {
+            try {
+                this.agentPlan = new AgentPlan(agent);
+                return this;
+            } catch (Exception e) {
+                throw new RuntimeException("Failed to create agent plan from agent", e);
+            }
+        }
+
+        @Override
+        public List<Map<String, Object>> toList() {
+            throw new UnsupportedOperationException(
+                    "RemoteAgentBuilder does not support toList. Use toDataStream or toTable instead.");
+        }
+
+        @Override
+        public DataStream<Object> toDataStream() {
+            if (agentPlan == null) {
+                throw new IllegalStateException("Must apply agent before calling toDataStream");
+            }
+
+            if (outputDataStream == null) {
+                if (keySelector != null) {
+                    outputDataStream =
+                            CompileUtils.connectToAgent(inputDataStream, keySelector, agentPlan);
+                } else {
+                    // If no key selector provided, use a simple pass-through key selector
+                    outputDataStream =
+                            CompileUtils.connectToAgent(inputDataStream, x -> x, agentPlan);
+                }
+            }
+
+            return outputDataStream;
+        }
+
+        @Override
+        public Table toTable(Schema schema) {
+            if (tableEnv == null) {
+                throw new IllegalStateException(
+                        "Table environment not available. Use fromTable() method to enable table output.");
+            }
+
+            DataStream<Object> dataStream = toDataStream();
+            return tableEnv.fromDataStream(dataStream, schema);
+        }
+    }
+}