sangkyoonnam commented on code in PR #1271:
URL: https://github.com/apache/flink-agents/pull/1271#discussion_r4302865335
##########
docs/content/docs/get-started/quickstart/_index.md:
##########
@@ -23,6 +24,84 @@ specific language governing permissions and limitations
under the License.
-->
-- [Build an Agent]({{< ref "docs/get-started/quickstart/create-agent" >}})
+Each Quickstart below is a complete, runnable Flink job. All three read the
same stream
+of product reviews and call the same local Ollama model, so the preparation is
shared and
+collected in [Before You Begin](#before-you-begin). They differ only in how
you declare
+the Agent.
+
+- [Build an Agent]({{< ref "docs/get-started/quickstart/create-agent" >}})
declares Actions
+ and Events in Python or Java code, and wires a prompt, a chat model, and a
tool together.
+ Start here if you are new to Flink Agents.
- [Use the Built-in ReAct Agent]({{< ref
"docs/get-started/quickstart/react_agent" >}})
-- [Define an Agent with YAML]({{< ref "docs/get-started/quickstart/yaml_agent"
>}})
+ configures the built-in `ReActAgent` with a prompt, tools, and an output
schema, and lets
+ the model plan the steps.
+- [Define an Agent with YAML]({{< ref "docs/get-started/quickstart/yaml_agent"
>}}) declares
+ the same wiring in one YAML file and loads it into the environment by Agent
name.
+
+## Before You Begin
+
+### Install Flink and Flink Agents
+
+Follow [Setup]({{< ref "docs/get-started/setup" >}}). Note which job type you
installed
+for, because every submit command below is shown for both types. A PyFlink job
submits with
+`flink run -py`, and a Java Flink job submits with `flink run -c`.
+
+### Get the Example Source
+
+The Quickstarts submit the example programs that ship with the repository, so
you need
+them locally. Clone the repository:
+
+```bash
+git clone https://github.com/apache/flink-agents.git
+cd flink-agents
+```
+
+For a PyFlink job, the same examples are installed inside the `flink_agents`
package, at
+`python/flink_agents/examples/quickstart` in that tree. Each Quickstart gives
both submit
+commands.
+
+A Java Quickstart needs the examples JAR, which the repository build produces.
Build from
+source with `./tools/build.sh`, then use
`examples/target/flink-agents-examples-*.jar`.
+
+### Prepare a Model Server
+
+The examples call a local Ollama server, so install Ollama from the official
+[website](https://ollama.com/download) at version **0.9.0** or higher, and
pull the model
+the Quickstarts use:
+
+```bash
+ollama pull qwen3:8b
+```
+
+Leave the server running. The examples connect to `http://localhost:11434`,
which is the
+default endpoint of the Ollama chat model connection.
+
+### Start a Local Flink Cluster
+
+{{< tabs "Start a Local Flink Cluster" >}}
+
+{{< tab "Python" >}}
+```bash
+# Required: lets the Flink JVM locate the flink-agents package
+export PYTHONPATH=$(python -c 'import sysconfig;
print(sysconfig.get_paths()["purelib"])')
+
+$FLINK_HOME/bin/start-cluster.sh
+```
+{{< /tab >}}
+
+{{< tab "Java" >}}
+```bash
+$FLINK_HOME/bin/start-cluster.sh
+```
+{{< /tab >}}
+
+{{< /tabs >}}
+
+The web UI is at [localhost:8081](http://localhost:8081). If it does not open,
check
+`$FLINK_HOME/log`. A port conflict is fixed in `$FLINK_HOME/conf/config.yaml`.
+
+A Java job that waits inside an Action needs a JVM option on some JDK
versions, so set it
+before you start the cluster. See
+[JDK and Scheduling Requirements]({{< ref
"docs/development/create-agent/actions#jdk-and-scheduling-requirements" >}}).
Review Comment:
On JDK 21 this isn't limited to Java jobs that wait inside an Action.
Without the option, the Python Quickstart failed before producing any analysis
results:
```
java.lang.IllegalAccessError: class
org.apache.flink.agents.runtime.async.ContinuationActionExecutor (in unnamed
module @0x6a5b9bed) cannot access class jdk.internal.vm.ContinuationScope (in
module java.base) because module java.base does not export jdk.internal.vm to
unnamed module @0x6a5b9bed
```
`ActionExecutionOperator.open()` calls
`ContinuationActionExecutor.isContinuationSupported()` unconditionally, and on
JDK 21 that initializes the class's static `ContinuationScope` field before any
Action runs, Python Agents included. With the option in `env.java.opts.all`,
the Python and Java jobs both printed results. Main had the option under each
Quickstart's Java tab; putting it here covers both languages:
```suggestion
On JDK 21 or later, append
`--add-exports=java.base/jdk.internal.vm=ALL-UNNAMED` to
`env.java.opts.all` in `$FLINK_HOME/conf/config.yaml` before starting the
cluster.
Both the Python and the Java Quickstarts need it. See
[JDK and Scheduling Requirements]({{< ref
"docs/development/create-agent/actions#jdk-and-scheduling-requirements" >}}).
```
##########
docs/content/docs/get-started/quickstart/_index.md:
##########
@@ -2,6 +2,7 @@
title: Quickstart
bold: true
bookCollapseSection: true
+type: docs
Review Comment:
This removes `/docs/get-started/quickstart/parallel_llm/` from the main docs
without a redirect, so bookmarks and outside links to that URL will break; the
page was published with 0.3. Other moved pages carry `aliases`, and pointing
this one at the Quickstart index keeps the old URL working:
```suggestion
type: docs
aliases:
- /docs/get-started/quickstart/parallel_llm/
```
##########
docs/content/docs/get-started/setup.md:
##########
@@ -181,12 +219,29 @@ This script will:
**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.
Review Comment:
`tools/build.sh` installs the wheel into `python/.venv`, not into the
activated environment. uv says so during the build (`VIRTUAL_ENV=... does not
match the project environment path .venv and will be ignored`), and `import
flink_agents` then failed in my venv. This changed in #979 (`uv pip install
--python .venv`), so it predates this PR, but this note is what a From Source
reader follows next. Installing the built wheel fixed it. The bullet above
("Install the Python package into your current Python environment") has the
same problem:
```suggestion
**Note:** `tools/build.sh` installs the Python package into `python/.venv`
in the repository, not into an activated virtual environment. To use your own
environment, install the built wheel into it from the repository root with `pip
install python/dist/flink_agents-*.whl`.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
