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 or 3.11. These versions have been thoroughly tested and offer the best compatibility with Flink Agents.

• 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:

Cross-language async limitation: When using cross-language resources (e.g., calling Java integrations from Python or vice versa), async execution is not supported. Cross-language calls always execute synchronously regardless of your JDK version.

This is important because:

• For Python users: Async execution is always available.
• For Java users on JDK 21+: Async execution is available, so using native integrations (instead of cross-language) matters for performance.
• For Java users on JDK < 21: Async execution is not available regardless of whether you use native or cross-language integrations. Therefore, the cross-language async limitation has no additional performance impact for these users.

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, but cross-language calls do not support async execution.

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.