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
The following commit(s) were added to refs/heads/main by this push:
new 5807983 [Doc] Reorganize installation guide and simplify quickstart
preparation sections (#266)
5807983 is described below
commit 58079833604cb3bc5206cda82dcc57bbcaba9c2d
Author: Alan Z. <[email protected]>
AuthorDate: Thu Oct 9 22:36:46 2025 -0700
[Doc] Reorganize installation guide and simplify quickstart preparation
sections (#266)
---
docs/content/docs/get-started/installation.md | 183 ++++++++++++++++-----
.../docs/get-started/quickstart/react_agent.md | 24 +--
.../docs/get-started/quickstart/workflow_agent.md | 24 +--
3 files changed, 150 insertions(+), 81 deletions(-)
diff --git a/docs/content/docs/get-started/installation.md
b/docs/content/docs/get-started/installation.md
index b3b9226..b1a8686 100644
--- a/docs/content/docs/get-started/installation.md
+++ b/docs/content/docs/get-started/installation.md
@@ -30,84 +30,185 @@ 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.
{{< /hint >}}
-## Install the Official Release
-#### Install Python Packages
+## Install Apache Flink
-{{< hint warning >}}
-__Note:__ This will be available after Flink Agents is released.
+Before installing Flink Agents, you need to have Apache Flink 1.20.3 installed.
+
+Download and extract Flink 1.20.3:
+
+```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
+
+# Extract the archive
+tar -xzf flink-1.20.3-bin-scala_2.12.tgz
+
+# Set FLINK_HOME environment variable
+export FLINK_HOME=$(pwd)/flink-1.20.3
+
+# 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/
+```
+
+{{< hint info >}}
+**Note:** For more detailed Flink installation instructions, refer to the
[Flink local installation
guide](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/try-flink/local_installation/).
{{< /hint >}}
-We recommand creating a Python virtual environment to install the Flink Agents
Python library.
+## Install Flink Agents
+
+### Prerequisites
+
+* Python 3.10 or 3.11
+* For building from source, you also need:
+ - Unix-like environment (Linux, Mac OS X, Cygwin, or WSL)
+ - Git
+ - Maven 3
+ - Java 11
+
+### Set Up Python Environment (Recommended)
+
+We recommend using a Python virtual environment to isolate Flink Agents
dependencies from your system Python packages.
-To install the latest Flink Agents release, run:
+**Create a virtual environment:**
+Using `venv` (built-in with Python 3):
```shell
-python -m pip install flink-agents
+# Create a virtual environment in a directory named 'venv'
+python3 -m venv venv
+
+# Activate the virtual environment
+# On Linux/macOS:
+source venv/bin/activate
+# On Windows:
+# venv\Scripts\activate
```
-#### Install Java Package
-To run java job on a Flink cluster, ensure the Flink Agents Java JARs are
placed in the Flink lib directory:
+{{< hint info >}}
+**Note:** If `python3` command is not found, try `python` instead. Some
systems alias `python` to Python 3.
+{{< /hint >}}
-<!-- TODO: fill in the command after Flink Agents is released -->
+**To deactivate when you're done:**
```shell
-# Download the Flink Agents released flink-agents-dist jar.
-
-# After downloading the bundle jar, copy it to Flink's lib directory.
-cp flink-agents-dist-$VERSION.jar $FLINK_HOME/lib/
+deactivate
```
+### Install Flink Agents Package
-## Build and Install from Source
+Choose one of the following installation methods:
-Prerequisites for building Flink Agents:
+#### From Official Release
-* Unix-like environment (we use Linux, Mac OS X, Cygwin, WSL)
-* Git
-* Maven
-* Java 11
-* Python 3.10 or 3.11
+{{< hint warning >}}
+__Note:__ This will be available after Flink Agents is released.
+{{< /hint >}}
-To clone from Git, run:
+Install Flink Agents using pip:
```shell
-git clone https://github.com/apache/flink-agents.git
+pip install flink-agents
```
-### Build
-To run on a Flink cluster, we need build the whole project.
+#### From Source
-We provide a script to run:
+**Clone the repository:**
```shell
+git clone https://github.com/apache/flink-agents.git
cd flink-agents
+```
+
+**Build and install:**
+
+Run the build script to build both Java and Python components:
+
+```shell
./tools/build.sh
```
-### Install Flink Agents to Flink
+This script will:
+- Build all Java modules using Maven
+- Build the Python package
+- Install the Python package into your current Python environment
+- Package the distribution JAR with all dependencies
+
+{{< hint info >}}
+**Note:** If you activated a virtual environment earlier, the Python package
will be installed into that virtual environment. Otherwise, it will be
installed into your system Python environment.
+{{< /hint >}}
+After building:
+- The Python package is installed and ready to use
+- The distribution JAR is located at: `dist/target/flink-agents-dist-*.jar`
-To install the Java dependencies to Flink, run:
+## Deploy to Flink Cluster
+
+After installing Flink Agents package, you need to deploy it to your Flink
cluster so that Flink can run your agent jobs.
+
+### Configure PYTHONPATH
+
+Flink runs in its own JVM process and needs the `PYTHONPATH` environment
variable to locate the flink-agents Python package. You need to set
`PYTHONPATH` to the directory where flink-agents is installed.
+
+**Determine your Python package installation path:**
+
+The path depends on your Python environment setup:
+- If using a virtual environment, it's the site-packages directory within your
venv
+- If using system Python, it's the system site-packages directory
+
+**Tip:** You can use this command to help find the path:
```shell
-cd flink-agents
-# copy the Flink Agents JARs to Flink's lib directory
-cp dist/target/flink-agents-dist-0.1-SNAPSHOT.jar $FLINK_HOME/lib/
+python3 -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])'
```
-To install the Python package, just set the `PYTHONPATH` environment variable.
+**Set PYTHONPATH before starting Flink:**
-User can set the system environment variable once.
```shell
-vi ~/.bash_profile # or ~/.bashrc, ~/.zprofile, depends on your os
-# Append the below line to the file
+# Set PYTHONPATH to your Python site-packages directory
+
export PYTHONPATH=$(python -c 'import sysconfig;
print(sysconfig.get_paths()["purelib"])')
-source ~/.bash_profile
```
-Here, the command `python -c 'import sysconfig;
print(sysconfig.get_paths()["purelib"])` is to get the python path in current
environment. It should be the python path which installed flink-agents.
-Or, if the user have multiple `PYTHONPATH` and don't want to set a system
environment variable, they can export the `PYTHONPATH` before start flink
cluster and submit flink job. See [deployment]({{< ref
"docs/operations/deployment" >}}) for more details.
+{{< hint info >}}
+**Note:** You can add the `export PYTHONPATH=...` line to your shell profile
(`~/.bash_profile`, `~/.bashrc`, `~/.zprofile`, or `~/.zshrc`) to set it
permanently. This way, it will be automatically configured in all future
terminal sessions.
+{{< /hint >}}
+
+### Install Flink Agents Java Library
+
+Copy the Flink Agents distribution JAR to your Flink installation's `lib`
directory:
+
+{{< tabs "Install Flink Agents Java Library" >}}
+
+{{< tab "From Official Release" >}}
+The Flink Agents JAR is bundled inside the Python package. Use the PYTHONPATH
you configured above to locate and copy it:
+
```shell
-export PYTHONPATH=$(python -c 'import sysconfig;
print(sysconfig.get_paths()["purelib"])')
-# start cluster or submit job
-```
\ No newline at end of file
+# Copy the JAR from the Python package to Flink's lib directory
+cp $PYTHONPATH/flink_agents/lib/flink-agents-dist-*.jar $FLINK_HOME/lib/
+```
+
+{{< /tab >}}
+
+{{< tab "From Source" >}}
+After building from source, the distribution JAR is located in the
`dist/target/` directory:
+
+```shell
+# Copy the JAR to Flink's lib directory
+cp dist/target/flink-agents-dist-*.jar $FLINK_HOME/lib/
+```
+{{< /tab >}}
+
+{{< /tabs >}}
+
+### Start Flink Cluster or Submit Job
+
+Once the Java library is installed and PYTHONPATH is configured, you can start
your Flink cluster or submit jobs:
+
+```shell
+# Start your Flink cluster
+$FLINK_HOME/bin/start-cluster.sh
+
+# Or submit your job directly
+$FLINK_HOME/bin/flink run -py /path/to/your/job.py
+```
+
+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 613049b..142da1d 100644
--- a/docs/content/docs/get-started/quickstart/react_agent.md
+++ b/docs/content/docs/get-started/quickstart/react_agent.md
@@ -218,31 +218,15 @@ reviewAnalysisResStream.print();
### Preparation
-#### Prepare Flink
+#### Prepare Flink and Flink Agents
-Download a stable release of Flink 1.20.3, then extract the archive:
+Follow the [installation]({{< ref "docs/get-started/installation" >}})
instructions to setup Flink and the Flink Agents.
-```bash
-curl -LO
https://archive.apache.org/dist/flink/flink-1.20.3/flink-1.20.3-bin-scala_2.12.tgz
-tar -xzf flink-1.20.3-bin-scala_2.12.tgz
-
-# Copy the flink-python jar from opt to lib
-cp ./flink-1.20.3/opt/flink-python-1.20.3.jar ./flink-1.20.3/lib
-```
-You can refer to the [local
installation](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/try-flink/local_installation/)
instructions for more detailed step.
-
-
-#### Prepare Flink Agents
-
-We recommend creating a Python virtual environment to install the Flink Agents
Python library.
-
-Follow the [installation]({{< ref "docs/get-started/installation" >}})
instructions to install the Flink Agents Python and Java libraries.
-
-#### Clone the Flink Agents repo
+#### Clone the Flink Agents Repository (if not done already)
-Clone the Flink Agents repo to get quickstart example code.
```bash
git clone https://github.com/apache/flink-agents.git
+cd flink-agents
```
#### Deploy a Standalone Flink Cluster
diff --git a/docs/content/docs/get-started/quickstart/workflow_agent.md
b/docs/content/docs/get-started/quickstart/workflow_agent.md
index e58dbbe..0c22fb9 100644
--- a/docs/content/docs/get-started/quickstart/workflow_agent.md
+++ b/docs/content/docs/get-started/quickstart/workflow_agent.md
@@ -342,31 +342,15 @@ agentsEnv.execute();
### Preparation
-#### Prepare Flink
+#### Prepare Flink and Flink Agents
-Download a stable release of Flink 1.20.3, then extract the archive:
+Follow the [installation]({{< ref "docs/get-started/installation" >}})
instructions to setup Flink and the Flink Agents.
-```bash
-curl -LO
https://archive.apache.org/dist/flink/flink-1.20.3/flink-1.20.3-bin-scala_2.12.tgz
-tar -xzf flink-1.20.3-bin-scala_2.12.tgz
-
-# Copy the flink-python jar from opt to lib
-cp ./flink-1.20.3/opt/flink-python-1.20.3.jar ./flink-1.20.3/lib
-```
-You can refer to the [local
installation](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/try-flink/local_installation/)
instructions for more detailed step.
-
-
-#### Prepare Flink Agents
-
-We recommend creating a Python virtual environment to install the Flink Agents
Python library.
-
-Follow the [installation]({{< ref "docs/get-started/installation" >}})
instructions to install the Flink Agents Python and Java libraries.
-
-#### Clone the Flink Agents repo
+#### Clone the Flink Agents Repository (if not done already)
-Clone the Flink Agents repo to get quickstart example code.
```bash
git clone https://github.com/apache/flink-agents.git
+cd flink-agents
```
#### Deploy a Standalone Flink Cluster
