This is an automated email from the ASF dual-hosted git repository. xtsong pushed a commit to branch release-0.2 in repository https://gitbox.apache.org/repos/asf/flink-agents.git
commit fd63710893e0646139a62df423427cc1247522a8 Author: youjin <[email protected]> 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 >}}
