This is an automated email from the ASF dual-hosted git repository.
sxnan 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 5287163b [doc] Add documentation about how to choose between Java &
Python APIs (#471)
5287163b is described below
commit 5287163b3d3979f35eba3648567bbee01fb6475c
Author: Xuannan <[email protected]>
AuthorDate: Mon Jan 26 10:13:53 2026 +0800
[doc] Add documentation about how to choose between Java & Python APIs
(#471)
* [doc] Add documentation about how to choose between Java & Python APIs
Co-authored-by: Xintong Song <[email protected]>
---
docs/content/docs/development/react_agent.md | 4 +++
docs/content/docs/development/workflow_agent.md | 4 +++
docs/content/docs/faq/faq.md | 38 +++++++++++++++++++++++++
docs/content/docs/get-started/overview.md | 2 +-
4 files changed, 47 insertions(+), 1 deletion(-)
diff --git a/docs/content/docs/development/react_agent.md
b/docs/content/docs/development/react_agent.md
index c1dbfa5b..dad49a64 100644
--- a/docs/content/docs/development/react_agent.md
+++ b/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" >}}
diff --git a/docs/content/docs/development/workflow_agent.md
b/docs/content/docs/development/workflow_agent.md
index e799018e..6500caad 100644
--- a/docs/content/docs/development/workflow_agent.md
+++ b/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" >}}
diff --git a/docs/content/docs/faq/faq.md b/docs/content/docs/faq/faq.md
index a0f3a038..beb6cf85 100644
--- a/docs/content/docs/faq/faq.md
+++ b/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 perfo [...]
+
+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.
diff --git a/docs/content/docs/get-started/overview.md
b/docs/content/docs/get-started/overview.md
index 4306eb38..fb31c74f 100644
--- a/docs/content/docs/get-started/overview.md
+++ b/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.
