Flink Agents Support Multi-JDK Versions

[Sxnan]

Background

The Flink Agents project needs to support JDK 11 and above to ensure compatibility with the Apache Flink ecosystem. However, some external dependencies introduced in the project only support higher JDK versions, which presents challenges for multi-JDK support.

Taking the flink-agents-api module as an example, this module introduces the MCP (Model Context Protocol) SDK to support the MCP protocol, and MCP SDK only supports JDK 17+. This means:

• If the released jar is compiled with JDK 17 and includes MCP code, JDK 11 users won't be able to use it due to class version incompatibility
• If the released jar is compiled with JDK 11 and excludes MCP code, JDK 17+ users won't be able to use MCP features

Module-Specific Designs

flink-agents-api

Since users depend on flink-agents-api via Maven, and this module as a framework API is not suitable for shading external dependencies, the Maven Classifier approach is adopted:

flink-agents-api-{version}-jdk11.jar     # JDK 11 version, without JDK 17+ features
flink-agents-api-{version}.jar     # Default version, includes MCP and other JDK 17+ features

Design Principles

1. Default version ensures complete functionality: The default jar (no classifier) is compiled with JDK 17, ensuring all JDK 17+ users can use it directly with JDK 17+ features

• Lower JDK compatibility provided via classifier: Users needing JDK versions below 17 explicitly specify the classifier

1. Unified dependency for the same module: Users only need to depend on the same artifactId, differentiating versions via classifier

User Usage

JDK 11+ users (without MCP features)

<dependency>
    <groupId>org.apache.flink</groupId>
    <artifactId>flink-agents-api</artifactId>
    <version>${flink-agents.version}</version>
    <classifier>jdk11</classifier>
</dependency>

JDK 17+ users (need MCP features):

<dependency>
    <groupId>org.apache.flink</groupId>
    <artifactId>flink-agents-api</artifactId>
    <version>${flink-agents.version}</version>
</dependency>

Version Contents

Version	JDK Requirement	Included Content
jdk11	JDK 11+	Core API, Agent, Tool, Prompt, ChatModel, and other basic features
Default (no classifier)	JDK 17+	Basic features + MCP-related implementations (MCPServer, MCPTool, MCPPrompt, etc.)

flink-agents-dist

flink-agents-dist is an uber jar distributed with the Python package; users need to deploy it to the Flink cluster's lib directory. Because:

• dist itself is an uber jar that already shades all dependencies
• Python package distribution requires a single jar file
• Users don't depend on this module via Maven

The Multi-release JAR approach is adopted, where the JVM automatically selects the correct classes based on version at runtime:

JAR Structure

flink-agents-dist-{version}.jar
├── org/apache/flink/agents/...              # JDK 11 version classes (without MCP)
├── (shaded common dependencies)             # Common dependencies
└── META-INF/
    └── versions/
        └── 17/
            ├── org/apache/flink/agents/api/mcp/...   # MCP-related classes
            └── (shaded MCP SDK)                      # MCP SDK dependencies

Runtime Behavior

• JDK 11 environment: JVM loads classes from the root directory, MCP-related code is ignored
• JDK 17+ environment: JVM preferentially loads classes from META-INF/versions/17/, MCP features are available

Advantages

• Transparent to users: No configuration needed, JVM adapts automatically
• Single jar distribution: Python package only needs to include one jar file
• Consistent architecture: Follows the uber jar design philosophy of shading all dependencies

flink-agents-plan / flink-agents-runtime

These two modules don't need multi-JDK support:

• Users don't directly depend on these modules
• Source code uses reflection to call MCP classes, avoiding compile-time dependencies
• Only test code involves JDK 17+ features, which doesn't affect the released jar

Other Modules

integrations/* and other modules currently have no JDK 17+ specific dependencies and don't need multi-version support for now.

Summary

Module	Approach	Reason
flink-agents-api	Maven Classifier	Users depend via Maven; API module not suitable for shading external dependencies
flink-agents-dist	Multi-release JAR	uber jar already shades dependencies; Python package needs single jar; transparent automatic adaptation for users
flink-agents-plan	Not needed	Users don't directly depend on it; uses reflection to avoid compile-time dependencies
flink-agents-runtime	Not needed	Users don't directly depend on it; no JDK 17+ specific dependencies
integrations/*	Not needed	Currently no JDK 17+ specific dependencies