[doc] Add documentation about how to choose between Java & Python APIs

docs/content/docs/development/react_agent.md

@@ -26,6 +26,10 @@ under the License.
 
 ReAct Agent is a general paradigm that combines reasoning and action capabilities to solve complex tasks. Leveraging this paradigm, the user only needs to specify the goal with prompt and provide available tools, and the LLM will decide how to achieve the goal and take actions autonomously
 
+{{< hint info >}}
+For guidance on choosing Java or Python, see [Should I choose Java or Python?]({{< ref "docs/faq/faq#q3-should-i-choose-java-or-python" >}}).
+{{< /hint >}}
+
 ## ReAct Agent Example
 
 {{< tabs "ReAct Agent Example" >}}

docs/content/docs/development/workflow_agent.md

@@ -30,6 +30,10 @@ In Flink-Agents, a workflow agent is defined as a class that inherits from the `
 
 A workflow agent is well-suited for scenarios where the solution requires explicit orchestration, branching, or multi-step reasoning, such as data enrichment, multi-tool pipelines, or complex business logic.
 
+{{< hint info >}}
+For guidance on choosing Java or Python, see [Should I choose Java or Python?]({{< ref "docs/faq/faq#q3-should-i-choose-java-or-python" >}}).
+{{< /hint >}}
+
 ## Workflow Agent Example
 
 {{< tabs "Workflow Agent Example" >}}

docs/content/docs/faq/faq.md

@@ -58,3 +58,41 @@ Cross-language resources, such as using Java resources from Python or vice versa
 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, besides the team's experience and preferences, there's another thing needs to be considered. Flink Agents provides built-in integration supports for many echosystem providers. Some of these supports are in only one language. While you can still use them when building agents in another language, leveraging Flink Agents' cross-language supports, this comes with a limitation of not supporting async execution, which may bring performance concerns. 
+
+The following matrix shows the native integration support status of providers over languages. For those marked as ❌, cross-langauge is needed thus async execution is not supported.
+
+**Chat Models**
+
+| provider | Python | Java |
+|---|---|---|
+| [OpenAI]({{< ref "docs/development/chat_models#openai" >}}) | ✅ | ✅ |
+| [Anthropic]({{< ref "docs/development/chat_models#anthropic" >}}) | ✅ | ❌ |
+| [Ollama]({{< ref "docs/development/chat_models#ollama" >}}) | ✅ | ✅ |
+| [Tongyi (DashScope)]({{< ref "docs/development/chat_models#tongyi-dashscope" >}}) | ✅ | ❌ |
+| [Azure AI]({{< ref "docs/development/chat_models#azure-ai" >}}) | ❌ | ✅ |
+
+**Embedding Models**
+
+| provider | Python | Java |
+|---|---|---|
+| [OpenAI]({{< ref "docs/development/embedding_models#openai" >}}) | ✅ | ❌ |
+| [Ollama]({{< ref "docs/development/embedding_models#ollama" >}}) | ✅ | ✅ |
+
+**Vector Stores**
+
+| provider | Python | Java |
+|---|---|---|
+| [Chroma]({{< ref "docs/development/vector_stores#chroma" >}}) | ✅ | ❌ |
+| [Elasticsearch]({{< ref "docs/development/vector_stores#elasticsearch" >}}) | ❌ | ✅ |
+
+**MCP Server**
+
+| provider | Python | Java 17+ | Java 11-16 |
+|---|---|---|---|
+| [MCP Server]({{< ref "docs/development/mcp" >}}) | ✅ | ✅ | ❌ |
+
+Java native MCP support requires **JDK 17+**. See [MCP]({{< ref "docs/development/mcp" >}}) for details.

docs/content/docs/get-started/overview.md

@@ -35,7 +35,7 @@ The key features of Apache Flink Agents include:
 - **Seamless Data and AI Integration**: Agents interact directly with Flink's DataStream and Table APIs for input and output, enabling a smooth integration of structured data processing and semantic AI capabilities within Flink.
 - **Exactly-Once Action Consistency**: Ensures exactly-once consistency for agent actions and their side effects by integrating Flink's checkpointing with an external write-ahead log.
 - **Familiar Agent Abstractions**: Leverages well-known AI agent concepts, making it easy for developers experienced with agent-based systems to quickly adopt and build on Apache Flink Agents without a steep learning curve.
-- **Multi-Language Supports**: Provides native APIs in both Python and Java, enabling seamless integration into diverse development environments and allowing teams to use their preferred programming language.
+- **Multi-Language Supports**: Provides native APIs in both Python and Java, enabling seamless integration into diverse development environments and allowing teams to use their preferred programming language. For guidance on choosing Java or Python, see [Should I choose Java or Python?]({{< ref "docs/faq/faq#q3-should-i-choose-java-or-python" >}}).
 - **Rich Ecosystem**: Natively integrates mainstream LLMs, vector stores from diverse providers, and tools or prompts hosted on MCP servers into your agents, while enabling customizable extensions.
 - **Observability**: Adopts an event-centric orchestration approach, where all agent actions are connected and controlled by events, enabling observation and understanding of agent behavior through the event log.