You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by xt...@apache.org on 2026/01/27 12:47:05 UTC
(flink-agents) 03/03: [doc] Update the documents in the get-started section
This is an automated email from the ASF dual-hosted git repository.
xtsong pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-agents.git
commit b94c9ebe52613b54e15c1fadea76cd17cfa9eb35
Author: youjin <me...@gmail.com>
AuthorDate: Tue Jan 27 10:12:09 2026 +0800
[doc] Update the documents in the get-started section
---
docs/content/docs/get-started/installation.md | 64 +++++++++++++++-------
.../docs/get-started/quickstart/react_agent.md | 24 +++-----
.../docs/get-started/quickstart/workflow_agent.md | 15 ++---
3 files changed, 61 insertions(+), 42 deletions(-)
diff --git a/docs/content/docs/get-started/installation.md b/docs/content/docs/get-started/installation.md
index 7ed3d4f5..0ca156d5 100644
--- a/docs/content/docs/get-started/installation.md
+++ b/docs/content/docs/get-started/installation.md
@@ -28,27 +28,28 @@ Flink Agents provides both Python and Java APIs to define a Flink Agents job.
The sections below show how to install the required dependencies.
{{< hint warning >}}
-__NOTE:__ To run on flink cluster, Flink-Agents requires flink version be a stable release of Flink 1.20.3.
+__NOTE:__ To run on a Flink cluster, Flink-Agents requires a stable release of Flink version 1.20.3 or higher. We highly recommend using the **latest stable release of your chosen Flink minor version** (e.g., for minor version 2.2, use the latest 2.2.x release).
{{< /hint >}}
## Install Apache Flink
-Before installing Flink Agents, you need to have Apache Flink 1.20.3 installed.
+Before installing Flink Agents, you need to have Apache Flink installed.
-Download and extract Flink 1.20.3:
+Download and extract Flink:
```shell
-# Download Flink 1.20.3: https://www.apache.org/dyn/closer.lua/flink/flink-1.20.3/flink-1.20.3-bin-scala_2.12.tgz
-curl -LO https://archive.apache.org/dist/flink/flink-1.20.3/flink-1.20.3-bin-scala_2.12.tgz
+# 1. Go to https://flink.apache.org/downloads/ and download the latest stable release of your desired Flink version
+# 2. Set the Flink version you downloaded (e.g., 2.2.x)
+export FLINK_VERSION=<version>
-# Extract the archive
-tar -xzf flink-1.20.3-bin-scala_2.12.tgz
+# 3. Extract the archive
+tar -xzf flink-${FLINK_VERSION}-bin-scala_2.12.tgz
# Set FLINK_HOME environment variable
-export FLINK_HOME=$(pwd)/flink-1.20.3
+export FLINK_HOME=$(pwd)/flink-${FLINK_VERSION}
# Copy the flink-python JAR from opt to lib (required for PyFlink)
-cp $FLINK_HOME/opt/flink-python-1.20.3.jar $FLINK_HOME/lib/
+cp $FLINK_HOME/opt/flink-python-${FLINK_VERSION}.jar $FLINK_HOME/lib/
```
{{< hint info >}}
@@ -64,7 +65,7 @@ cp $FLINK_HOME/opt/flink-python-1.20.3.jar $FLINK_HOME/lib/
- Unix-like environment (Linux, Mac OS X, Cygwin, or WSL)
- Git
- Maven 3
- - Java 17+ (full functionality), or Java 11+ (some features unavailable)
+ - Java 21+ (full functionality), or Java 11+ (some features unavailable)
### Java Versions
@@ -72,10 +73,10 @@ For running an agent built with **Python API**, you can use any Java version 11
When using **Java API**, there are some functionality limitations for earlier Java versions, as detailed below:
-| Java Version | Limitations |
-|--------------|-------------------------------|
-| Java 17+ | No limitations. |
-| Java 11-16 | MCP supports are unavailable. |
+| Java Version | Limitations |
+|--------------|------------------------|
+| Java 21+ | No limitations. |
+| Java 11-20 | Async execution is unavailable. |
### Set Up Python Environment (Recommended)
@@ -117,7 +118,8 @@ __Note:__ This will be available after Flink Agents is released.
Install Flink Agents using pip:
```shell
-pip install flink-agents
+# Install Flink Agents and Flink Python package
+pip install flink-agents apache-flink==${FLINK_VERSION}
```
#### From Source
@@ -126,7 +128,6 @@ pip install flink-agents
```shell
git clone https://github.com/apache/flink-agents.git
-cd flink-agents
```
**Build and install:**
@@ -134,7 +135,13 @@ cd flink-agents
Run the build script to build both Java and Python components:
```shell
+# Install Flink Python package
+pip install apache-flink==${FLINK_VERSION}
+
+# Build Flink Agents
+cd flink-agents
./tools/build.sh
+cd ..
```
This script will:
@@ -149,7 +156,7 @@ This script will:
After building:
- The Python package is installed and ready to use
-- The distribution JAR is located at: `dist/target/flink-agents-dist-*.jar`
+- The distribution JAR is located at: `dist/flink-${FLINK_VERSION%.*}/target/flink-agents-dist-*.jar`
## Maven Dependencies (For Java)
@@ -253,7 +260,7 @@ The Flink Agents JAR is bundled inside the Python package. Use the PYTHONPATH yo
```shell
# Copy the JAR from the Python package to Flink's lib directory
-cp $PYTHONPATH/flink_agents/lib/flink-agents-dist-*.jar $FLINK_HOME/lib/
+cp $PYTHONPATH/flink_agents/lib/flink-${FLINK_VERSION%.*}/flink-agents-dist-*.jar $FLINK_HOME/lib/
```
{{< /tab >}}
@@ -263,7 +270,7 @@ After building from source, the distribution JAR is located in the `dist/target/
```shell
# Copy the JAR to Flink's lib directory
-cp dist/target/flink-agents-dist-*.jar $FLINK_HOME/lib/
+cp dist/flink-${FLINK_VERSION%.*}/target/flink-agents-dist-*.jar $FLINK_HOME/lib/
```
{{< /tab >}}
@@ -273,7 +280,10 @@ cp dist/target/flink-agents-dist-*.jar $FLINK_HOME/lib/
Once the Java library is installed and PYTHONPATH is configured, you can start your Flink cluster or submit jobs:
-```shell
+{{< tabs "Start Flink Cluster or Submit Job" >}}
+
+{{< tab "Python" >}}
+```bash
# Start your Flink cluster
$FLINK_HOME/bin/start-cluster.sh
@@ -281,4 +291,18 @@ $FLINK_HOME/bin/start-cluster.sh
$FLINK_HOME/bin/flink run -py /path/to/your/job.py
```
+{{< /tab >}}
+
+{{< tab "Java" >}}
+```bash
+# Start your Flink cluster
+$FLINK_HOME/bin/start-cluster.sh
+
+# Or submit your job directly
+$FLINK_HOME/bin/flink run -c <your.main.class> /path/to/your-job.jar
+```
+{{< /tab >}}
+
+{{< /tabs >}}
+
See [deployment]({{< ref "docs/operations/deployment" >}}) for more details on running Flink Agents jobs.
\ No newline at end of file
diff --git a/docs/content/docs/get-started/quickstart/react_agent.md b/docs/content/docs/get-started/quickstart/react_agent.md
index 48cfaff2..1002691f 100644
--- a/docs/content/docs/get-started/quickstart/react_agent.md
+++ b/docs/content/docs/get-started/quickstart/react_agent.md
@@ -167,15 +167,9 @@ review_analysis_res_stream.print()
// Each element represents a ProductReview.
DataStream<Row> productReviewStream =
env.fromSource(
- FileSource.forRecordStreamFormat(
- new TextLineFormat(),
- new Path(
- Objects.requireNonNull(
- ReActAgentExample.class
- .getClassLoader()
- .getResource(
- "input_data.txt"))
- .getPath()))
+ FileSource.forRecordStreamFormat(
+ new TextLineInputFormat(),
+ new Path(inputDataFile.getAbsolutePath()))
.monitorContinuously(Duration.ofMinutes(1))
.build(),
WatermarkStrategy.noWatermarks(),
@@ -214,7 +208,7 @@ reviewAnalysisResStream.print();
* Unix-like environment (we use Linux, Mac OS X, Cygwin, WSL)
* Git
-* Java 11
+* Java 11+
* Python 3.10 or 3.11
### Preparation
@@ -239,7 +233,7 @@ You can deploy a standalone Flink cluster in your local environment with the fol
{{< tab "Python" >}}
```bash
export PYTHONPATH=$(python -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])')
-./flink-1.20.3/bin/start-cluster.sh
+$FLINK_HOME/bin/start-cluster.sh
```
{{< /tab >}}
@@ -247,7 +241,7 @@ export PYTHONPATH=$(python -c 'import sysconfig; print(sysconfig.get_paths()["pu
1. Build Flink Agents from source to generate example jar. See [installation]({{< ref "docs/get-started/installation" >}}) for more details.
2. Start the Flink cluster
```bash
- ./flink-1.20.3/bin/start-cluster.sh
+ $FLINK_HOME/bin/start-cluster.sh
```
{{< /tab >}}
@@ -256,7 +250,7 @@ You can refer to the [local cluster](https://nightlies.apache.org/flink/flink-do
{{< hint info >}}
-If you can't navigate to the web UI at [localhost:8081](localhost:8081), you can find the reason in `./flink-1.20.3/log`. If the reason is port conflict, you can change the port in `./flink-1.20.3/conf/config.yaml`.
+If you can't navigate to the web UI at [localhost:8081](localhost:8081), you can find the reason in `$FLINK_HOME/log`. If the reason is port conflict, you can change the port in `$FLINK_HOME/conf/config.yaml`.
{{< /hint >}}
#### Prepare Ollama
@@ -280,13 +274,13 @@ ollama run qwen3:8b
export PYTHONPATH=$(python -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])')
# Run review analysis example
-./flink-1.20.3/bin/flink run -py ./flink-agents/python/flink_agents/examples/quickstart/react_agent_example.py
+$FLINK_HOME/bin/flink run -py ./flink-agents/python/flink_agents/examples/quickstart/react_agent_example.py
```
{{< /tab >}}
{{< tab "Java" >}}
```bash
-./flink-1.20.3/bin/flink run -c org.apache.flink.agents.examples.ReActAgentExample ./flink-agents/examples/target/flink-agents-examples-$VERSION.jar
+$FLINK_HOME/bin/flink run -c org.apache.flink.agents.examples.ReActAgentExample ./flink-agents/examples/target/flink-agents-examples-$VERSION.jar
```
{{< /tab >}}
diff --git a/docs/content/docs/get-started/quickstart/workflow_agent.md b/docs/content/docs/get-started/quickstart/workflow_agent.md
index 6dc3282c..45e861d5 100644
--- a/docs/content/docs/get-started/quickstart/workflow_agent.md
+++ b/docs/content/docs/get-started/quickstart/workflow_agent.md
@@ -52,6 +52,7 @@ agents_env = AgentsExecutionEnvironment.get_execution_environment(env)
# and ProductSuggestionAgent.
agents_env.add_resource(
"ollama_server",
+ ResourceType.CHAT_MODEL_CONNECTION,
ollama_server_descriptor,
)
```
@@ -362,7 +363,7 @@ You can deploy a standalone Flink cluster in your local environment with the fol
{{< tab "Python" >}}
```bash
export PYTHONPATH=$(python -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])')
-./flink-1.20.3/bin/start-cluster.sh
+$FLINK_HOME/bin/start-cluster.sh
```
{{< /tab >}}
@@ -370,7 +371,7 @@ export PYTHONPATH=$(python -c 'import sysconfig; print(sysconfig.get_paths()["pu
1. Build Flink Agents from source to generate example jar. See [installation]({{< ref "docs/get-started/installation" >}}) for more details.
2. Start the Flink cluster
```bash
- ./flink-1.20.3/bin/start-cluster.sh
+ $FLINK_HOME/bin/start-cluster.sh
```
{{< /tab >}}
@@ -379,7 +380,7 @@ You can refer to the [local cluster](https://nightlies.apache.org/flink/flink-do
{{< hint info >}}
-If you can't navigate to the web UI at [localhost:8081](localhost:8081), you can find the reason in `./flink-1.20.3/log`. If the reason is port conflict, you can change the port in `./flink-1.20.3/conf/config.yaml`.
+If you can't navigate to the web UI at [localhost:8081](localhost:8081), you can find the reason in `$FLINK_HOME/log`. If the reason is port conflict, you can change the port in `$FLINK_HOME/conf/config.yaml`.
{{< /hint >}}
#### Prepare Ollama
@@ -403,20 +404,20 @@ ollama run qwen3:8b
export PYTHONPATH=$(python -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])')
# Run review analysis example
-./flink-1.20.3/bin/flink run -py ./flink-agents/python/flink_agents/examples/quickstart/workflow_single_agent_example.py
+$FLINK_HOME/bin/flink run -py ./flink-agents/python/flink_agents/examples/quickstart/workflow_single_agent_example.py
# Run product suggestion example
-./flink-1.20.3/bin/flink run -py ./flink-agents/python/flink_agents/examples/quickstart/workflow_multiple_agent_example.py
+$FLINK_HOME/bin/flink run -py ./flink-agents/python/flink_agents/examples/quickstart/workflow_multiple_agent_example.py
```
{{< /tab >}}
{{< tab "Java" >}}
```bash
# Run review analysis example
-./flink-1.20.3/bin/flink run -c org.apache.flink.agents.examples.WorkflowSingleAgentExample ./flink-agents/examples/target/flink-agents-examples-$VERSION.jar
+$FLINK_HOME/bin/flink run -c org.apache.flink.agents.examples.WorkflowSingleAgentExample ./flink-agents/examples/target/flink-agents-examples-$VERSION.jar
# Run product suggestion example
-./flink-1.20.3/bin/flink run -c org.apache.flink.agents.examples.WorkflowMultipleAgentExample ./flink-agents/examples/target/flink-agents-examples-$VERSION.jar
+$FLINK_HOME/bin/flink run -c org.apache.flink.agents.examples.WorkflowMultipleAgentExample ./flink-agents/examples/target/flink-agents-examples-$VERSION.jar
```
{{< /tab >}}