General FAQ

This page describes the solutions to some common questions for Flink Agents users.

Q1: What are the Python environment considerations when running Flink Agents jobs?

To ensure stability and compatibility when running Flink Agents jobs, please be aware of the following Python environment guidelines:

• Recommended Python versions: It is advised to use officially supported Python versions such as Python 3.10, 3.11 or 3.12. These versions have been thoroughly tested and offer the best compatibility with Flink Agents.

  Note: Python 3.12 must work with Flink above 2.1 (including 2.1).

• Installation recommendations:

  • For Linux users: We recommend installing Python via your system package manager (e.g., using apt: sudo apt install python3).
  • For macOS users: Use Homebrew to install Python (e.g., brew install python).
  • For Windows users: Download and install the official version from the Python website.

• Avoid using Python installed via uv: Currently, it is not recommended to run Flink Agents jobs with a Python interpreter installed via the uv tool, as this may lead to potential compatibility issues or instability. For example, you may encounter the following gRPC-related error:

  Logging client failed: <_MultiThreadedRendezvous of RPC that terminated with:
      status = StatusCode.UNAVAILABLE
      details = "Socket closed"
      debug_error_string = "UNKNOWN:Error received from peer ipv6:%5B::1%5D:58663 {grpc_message:"Socket closed", grpc_status:14}"
  >... resetting
  Exception in thread read_grpc_client_inputs:
  ...
  py4j.protocol.Py4JError: An error occurred while calling o12.execute

  If you see an error like this, switch immediately to one of the officially recommended installation methods and confirm that you’re using a supported Python version.

Q2: Why do cross-language resources not work in local development mode?

Cross-language resources, such as using Java resources from Python or vice versa, are currently supported only when running in Flink. Local development mode does not support cross-language resources.

This limitation exists because cross-language communication requires the Flink runtime environment to effectively bridge Java and Python processes. In local development mode, this bridge is unavailable.

To use cross-language resources, please test the functionality by deploying to a Flink standalone cluster.

Q3: Should I choose Java or Python?

When choosing between Flink Agents’ Java API and Python API, consider the following factors:

1. Team experience and preferences
2. JDK version (for Java users)
3. Integration supports

Understanding Async Execution and JDK Versions

Async execution can significantly improve performance by allowing multiple operations to run concurrently. However, async execution support varies by language and JDK version:

This is important because:

• For Python users: Async execution is always available.
• For Java users on JDK 21+: Async execution is available.
• For Java users on JDK < 21: Async execution is not available and falls back to synchronous execution.

Cross-language async note: Async execution for cross-language resources requires the pemja 0.5.7 fix, available in Flink 1.20.5+ / 2.0.2+ / 2.1.3+ / 2.2.1+ / 2.3+. Current builds target Flink 2.3.0, which includes the fix, so cross-language async is enabled by default; on older Flink versions it falls back to synchronous execution automatically.

Native Integration Support Matrix

Flink Agents provides built-in integrations for many ecosystem providers. Some integrations are only available in one language. For those marked as ❌, you can still use them from the other language via cross-language support.

Chat Models

Embedding Models

Vector Stores

MCP Server

Note: Java native MCP support requires JDK 17+. For JDK 11-16, the framework automatically uses the Python SDK via cross-language support, which works seamlessly without additional configuration. See MCP for details.

Q4: How to run agent in IDE.

To avoid potential conflict with Flink cluster, the scope of the dependencies related to Flink and Flink Agents for agent job are provided. See Maven Dependencies for details.

To run the examples in IDE, users must enable the IDE feature: add dependencies with provided scope to classpath.

• For IDEA, edit the Run/Debug Configuration and enable add dependencies with provided scope to classpath . See Run/Debug Configuration for details.