From 829586d1c4c9dce34147f3f4ced74f1db611503b Mon Sep 17 00:00:00 2001 From: sxnan Date: Fri, 19 Sep 2025 14:36:33 +0800 Subject: [PATCH] [Docs] Draft the barebones of project docs --- docs/config.toml | 9 +- docs/content/_index.md | 2 +- docs/content/docs/development/_index.md | 3 +- .../content/docs/development/chat_with_llm.md | 57 ++++++++ .../docs/development/embed_and_vector.md | 45 ++++++ .../docs/development/integrate_with_flink.md | 35 +++++ docs/content/docs/development/react_agent.md | 35 +++++ docs/content/docs/development/tool_use.md | 54 +++++++ .../docs/development/workflow_agent.md | 138 ++++++++++++++++++ .../_index.md | 2 +- .../installation.md | 2 +- docs/content/docs/get-started/overview.md | 41 ++++++ .../docs/get-started/quickstart/_index.md | 24 +++ .../get-started/quickstart/react_agent.md | 27 ++++ .../get-started/quickstart/workflow_agent.md | 114 +++++++++++++++ docs/content/docs/operations/_index.md | 2 +- docs/content/docs/operations/configuration.md | 29 ++++ docs/content/docs/operations/deployment.md | 41 ++++++ docs/content/docs/operations/monitoring.md | 47 ++++++ 19 files changed, 697 insertions(+), 10 deletions(-) create mode 100644 docs/content/docs/development/chat_with_llm.md create mode 100644 docs/content/docs/development/embed_and_vector.md create mode 100644 docs/content/docs/development/integrate_with_flink.md create mode 100644 docs/content/docs/development/react_agent.md create mode 100644 docs/content/docs/development/tool_use.md create mode 100644 docs/content/docs/development/workflow_agent.md rename docs/content/docs/{try-flink-agents => get-started}/_index.md (97%) rename docs/content/docs/{try-flink-agents => get-started}/installation.md (99%) create mode 100644 docs/content/docs/get-started/overview.md create mode 100644 docs/content/docs/get-started/quickstart/_index.md create mode 100644 docs/content/docs/get-started/quickstart/react_agent.md create mode 100644 docs/content/docs/get-started/quickstart/workflow_agent.md create mode 100644 docs/content/docs/operations/configuration.md create mode 100644 docs/content/docs/operations/deployment.md create mode 100644 docs/content/docs/operations/monitoring.md diff --git a/docs/config.toml b/docs/config.toml index 947b1cf6..243f9075 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -70,10 +70,11 @@ pygmentsUseClasses = true contentDir = 'content' weight = 1 -[languages.zh] - languageName = '中文版' - contentDir = 'content.zh' - weight = 2 +# TODO: Add Chinese support +# [languages.zh] +# languageName = '中文版' +# contentDir = 'content.zh' +# weight = 2 [module] [[module.imports.mounts]] diff --git a/docs/content/_index.md b/docs/content/_index.md index f21cdd21..4a22864c 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -27,7 +27,7 @@ under the License. {{< columns >}} ## Try Flink Agents -If you’re interested in playing around with Flink Agents, check out our [example codes]({{< ref "docs/try-flink-agents/installation" >}}). +If you’re interested in playing around with Flink Agents, check out our [example codes]({{< ref "docs/get-started/installation" >}}). It provides a step by step introduction to the APIs and guides you through real applications. <---> diff --git a/docs/content/docs/development/_index.md b/docs/content/docs/development/_index.md index 54de96f8..1239b945 100644 --- a/docs/content/docs/development/_index.md +++ b/docs/content/docs/development/_index.md @@ -1,9 +1,8 @@ --- -title: Development +title: How to Build an Agent icon: bold: true bookCollapseSection: true -sectionBreak: true weight: 2 --- + +## ChatModel + +{{< hint warning >}} +**TODO**: What is ChatModel. How to define and ChatModelConnection, and ChatModelSetup. How to reuse ChatModelConnection in ChatModelSetup. + +**TODO**: How to send ChatRequestEvent and handle ChatResponseEvent. +{{< /hint >}} + +{{< hint warning >}} +**TODO**: List of all built-in Model and configuration, Ollama, Tongyi, etc. +{{< /hint >}} + +### Ollama + +### Tongyi + +## Prompt + +{{< hint warning >}} +**TODO**: What is Prompt. What are the differences between Local Prompt and MCP Prompt. +{{< /hint >}} + +### Local Prompt + +{{< hint warning >}} +**TODO**: How to define and use a Local Prompt. +{{< /hint >}} + +### MCP Prompt + +{{< hint warning >}} +**TODO**: Link to MCP Prompt documentation. +{{< /hint >}} diff --git a/docs/content/docs/development/embed_and_vector.md b/docs/content/docs/development/embed_and_vector.md new file mode 100644 index 00000000..1e5aa731 --- /dev/null +++ b/docs/content/docs/development/embed_and_vector.md @@ -0,0 +1,45 @@ +--- +title: Embed and Vector Search +weight: 4 +type: docs +--- + + + +## Embedding Model + +{{< hint warning >}} +**TODO**: What is Embedding Model. How to define and use EmbedingModelConnection and EmbedingModelSetup. + +{{< /hint >}} + +{{< hint warning >}} +**TODO**: List of all built-in Embedding Model and configuration. +{{< /hint >}} + +## Vector Store + +{{< hint warning >}} +**TODO**: What is Vector Store. How to define and use VectorStoreConnection and VectorStoreSetup. +{{< /hint >}} + +{{< hint warning >}} +**TODO**: How to use a Vector Store. List of all built-in Vector Store and configuration. +{{< /hint >}} \ No newline at end of file diff --git a/docs/content/docs/development/integrate_with_flink.md b/docs/content/docs/development/integrate_with_flink.md new file mode 100644 index 00000000..4de85efd --- /dev/null +++ b/docs/content/docs/development/integrate_with_flink.md @@ -0,0 +1,35 @@ +--- +title: Integrate with Flink +weight: 6 +type: docs +--- + + +## From/To Flink DataStream API + +{{< hint warning >}} +**TODO**: How to integrate with Flink DataStream API. +{{< /hint >}} + +## From/To Flink Table API + +{{< hint warning >}} +**TODO**: How to integrate with Flink Table API. +{{< /hint >}} \ No newline at end of file diff --git a/docs/content/docs/development/react_agent.md b/docs/content/docs/development/react_agent.md new file mode 100644 index 00000000..980aa8ce --- /dev/null +++ b/docs/content/docs/development/react_agent.md @@ -0,0 +1,35 @@ +--- +title: ReAct Agent +weight: 1 +type: docs +--- + + +## Overview + +{{< hint warning >}} +**TODO**: What is ReAct agent. When to use it. +{{< /hint >}} + +## ReAct Agent Example + +{{< hint warning >}} +**TODO**: Add the quickstart example code here. And briefly explain the code component by component. Link to the detailed documentation for each component, such as ChatModel, Prompt, Tool, etc. +{{< /hint >}} diff --git a/docs/content/docs/development/tool_use.md b/docs/content/docs/development/tool_use.md new file mode 100644 index 00000000..4d7679c7 --- /dev/null +++ b/docs/content/docs/development/tool_use.md @@ -0,0 +1,54 @@ +--- +title: Tool Use +weight: 5 +type: docs +--- + + + +## Local Function as Tool + +{{< hint warning >}} +**TODO**: How to define and use a Local Function as Tool. +{{< /hint >}} + +## How to Integrate with MCP Server + +{{< hint warning >}} +**TODO**: How to integrate with MCP Server. +{{< /hint >}} + +### MCP Tools + +{{< hint warning >}} +**TODO**: How to use the tools provided by MCP Server. +{{< /hint >}} + +### MCP Prompt + +{{< hint warning >}} +**TODO**: How to use the prompts provided by MCP Server. +{{< /hint >}} + +## Built-in Events for Tool + +{{< hint warning >}} +**TODO**: How to use the built-in events for tool call request and tool call response, such as ToolRequestEvent and ToolResponseEvent. +{{< /hint >}} \ No newline at end of file diff --git a/docs/content/docs/development/workflow_agent.md b/docs/content/docs/development/workflow_agent.md new file mode 100644 index 00000000..873b5ea2 --- /dev/null +++ b/docs/content/docs/development/workflow_agent.md @@ -0,0 +1,138 @@ +--- +title: Workflow Agent +weight: 1 +type: docs +--- + + +## Overview + +A workflow style agent in Flink-Agents is an agent whose reasoning and behavior are organized as a directed workflow of modular steps, called actions, connected by events. This design is inspired by the need to orchestrate complex, multi-stage tasks in a transparent, extensible, and data-centric way, leveraging Apache Flink's streaming architecture. + +In Flink-Agents, a workflow agent is defined as a class that inherits from the `Agent` base class. The agent's logic is expressed as a set of actions, each of which is a function decorated with `@action(EventType)`. Actions consume events, perform reasoning or tool calls, and emit new events, which may trigger downstream actions. This event-driven workflow forms a directed acyclic graph (DAG) of computation, where each node is an action and each edge is an event type. + +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. + +## Workflow Agent Example + +```python +class ReviewAnalysisAgent(Agent): + """An agent that uses a large language model (LLM) to analyze product reviews + and generate a satisfaction score and potential reasons for dissatisfaction. + + This agent receives a product review and produces a satisfaction score and a list + of reasons for dissatisfaction. It handles prompt construction, LLM interaction, + and output parsing. + """ + + @prompt + @staticmethod + def review_analysis_prompt() -> Prompt: + """Prompt for review analysis.""" + prompt_str = """ + Analyze the user review and product information to determine a + satisfaction score (1-5) and potential reasons for dissatisfaction. + + Example input format: + {{ + "id": "12345", + "review": "The headphones broke after one week of use. Very poor quality." + }} + + Ensure your response can be parsed by Python JSON, using this format as an example: + {{ + "score": 1, + "reasons": [ + "poor quality" + ] + }} + + input: + {input} + """ + return Prompt.from_text("review_analysis_prompt", prompt_str) + + @chat_model_setup + @staticmethod + def review_analysis_model() -> Tuple[Type[BaseChatModelSetup], Dict[str, Any]]: + """ChatModel which focus on review analysis.""" + return OllamaChatModelSetup, { + "name": "review_analysis_model", + "connection": "ollama_server", + "prompt": "review_analysis_prompt", + "extract_reasoning": True, + } + + @action(InputEvent) + @staticmethod + def process_input(event: InputEvent, ctx: RunnerContext) -> None: + """Process input event and send chat request for review analysis.""" + input: ProductReview = event.input + ctx.get_short_term_memory().set("id", input.id) + + content = f""" + "id": {input.id}, + "review": {input.review} + """ + msg = ChatMessage(role=MessageRole.USER, extra_args={"input": content}) + ctx.send_event(ChatRequestEvent(model="review_analysis_model", messages=[msg])) + + @action(ChatResponseEvent) + @staticmethod + def process_chat_response(event: ChatResponseEvent, ctx: RunnerContext) -> None: + """Process chat response event and send output event.""" + try: + json_content = json.loads(event.response.content) + ctx.send_event( + OutputEvent( + output=ProductReviewAnalysisRes( + id=ctx.get_short_term_memory().get("id"), + score=json_content["score"], + reasons=json_content["reasons"], + ) + ) + ) + except Exception: + logging.exception( + f"Error processing chat response {event.response.content}" + ) + + # To fail the agent, you can raise an exception here. +``` + +## Action + +{{< hint warning >}} +**TODO**: How to define an action. +{{< /hint >}} + +## Event + +{{< hint warning >}} +**TODO**: How to define, send and handle an event, including InputEvent, OutputEvent, and event between actions. + +{{< /hint >}} + +## Memory + +{{< hint warning >}} +**TODO**: How to use short-term memory and long-term memory. +{{< /hint >}} + diff --git a/docs/content/docs/try-flink-agents/_index.md b/docs/content/docs/get-started/_index.md similarity index 97% rename from docs/content/docs/try-flink-agents/_index.md rename to docs/content/docs/get-started/_index.md index 89072e1f..ba6ff295 100644 --- a/docs/content/docs/try-flink-agents/_index.md +++ b/docs/content/docs/get-started/_index.md @@ -1,5 +1,5 @@ --- -title: Try Flink Agents +title: Get Started icon: bold: true bookCollapseSection: true diff --git a/docs/content/docs/try-flink-agents/installation.md b/docs/content/docs/get-started/installation.md similarity index 99% rename from docs/content/docs/try-flink-agents/installation.md rename to docs/content/docs/get-started/installation.md index b82e8531..8545fbc2 100644 --- a/docs/content/docs/try-flink-agents/installation.md +++ b/docs/content/docs/get-started/installation.md @@ -1,6 +1,6 @@ --- title: 'Installation' -weight: 1 +weight: 2 type: docs --- + +## What is Flink Agents? + +{{< hint warning >}} +**TODO**: Add a description of Flink Agents. +{{< /hint >}} + +## Features + +{{< hint warning >}} +**TODO**: Add the features of Flink Agents. +{{< /hint >}} + +## Getting Started + +- [Install Flink Agents]({{< ref "docs/get-started/installation" >}}) +- [Workflow Agent Quickstart]({{< ref "docs/get-started/quickstart/workflow_agent" >}}) +- [ReAct Agent Quickstart]({{< ref "docs/get-started/quickstart/react_agent" >}}) diff --git a/docs/content/docs/get-started/quickstart/_index.md b/docs/content/docs/get-started/quickstart/_index.md new file mode 100644 index 00000000..ade34fbd --- /dev/null +++ b/docs/content/docs/get-started/quickstart/_index.md @@ -0,0 +1,24 @@ +--- +title: Quickstart +bold: true +bookCollapseSection: true +weight: 2 +--- + diff --git a/docs/content/docs/get-started/quickstart/react_agent.md b/docs/content/docs/get-started/quickstart/react_agent.md new file mode 100644 index 00000000..73bba445 --- /dev/null +++ b/docs/content/docs/get-started/quickstart/react_agent.md @@ -0,0 +1,27 @@ +--- +title: 'ReAct Agent' +weight: 2 +type: docs +--- + + +{{< hint warning >}} +**TODO**: Follow the same structure as workflow_agent.md, and add the content. +{{< /hint >}} diff --git a/docs/content/docs/get-started/quickstart/workflow_agent.md b/docs/content/docs/get-started/quickstart/workflow_agent.md new file mode 100644 index 00000000..05e58530 --- /dev/null +++ b/docs/content/docs/get-started/quickstart/workflow_agent.md @@ -0,0 +1,114 @@ +--- +title: 'Workflow Agent' +weight: 1 +type: docs +--- + + +## Overview + +{{< hint warning >}} +**TODO**: Briefly describe what is workflow agent, what is can do, and when to use it. +{{< /hint >}} + +This quickstart introduces two small, progressive streaming examples that demonstrate how to build LLM-powered workflows with Flink Agents: + +- **Review Analysis**: Processes a stream of product reviews and uses a single agent to extract a rating (1–5) and unsatisfied reasons from each review. + +- **Product Improvement Suggestions**: Builds on the first example by aggregating per-review analysis in windows to produce product-level summaries (score distribution and common complaints), then applies a second agent to generate concrete improvement suggestions for each product. + +Together, these examples show how to build a multi-agent workflow with Flink Agents and run it on a Flink standalone cluster. + +{{< hint warning >}} +**TODO**: Add the example code here. And briefly explain the code. +{{< /hint >}} + +## Prerequisites + +* Unix-like environment (we use Linux, Mac OS X, Cygwin, WSL) +* Git +* Java 11 +* Python 3.10 or 3.11 + +## Preparation + +### Prepare Flink + +Download a stable release of Flink 1.20.3, then extract the archive: + +```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 recommand creating a Python virtual environment to install the Flink Agents Python library. + +Follow the {{< ref "docs/get-started/installation" >}} instructions to install the Flink Agents Python and Java libraries. + +### Prepare Ollama + +Download and install Ollama from the official [website](https://ollama.com/download). + +Then pull the qwen3:8b model, which is required by the quickstart examples + +```bash +ollama pull qwen3:8b +``` + +### Deploy a Standalone Flink Cluster + +You can deploy a standalone Flink cluster in your local environment with the following command. + +```bash +export PYTHONPATH=$(python -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])') +./flink-1.20.3/bin/start-cluster.sh +``` + +You should be able to navigate to the web UI at [localhost:8081](localhost:8081) to view the Flink dashboard and see that the cluster is up and running. + +## Submit Flink Agents Job to Standalone Flink Cluster + +### Clone the Flink Agents repo + +```bash +git clone https://github.com/apache/flink-agents.git +``` + +### Submit to Flink Cluster +```bash +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/product_review_analysis.py + +# Run product suggestion example +./flink-1.20.3/bin/flink run -py ./flink-agents/python/flink_agents/examples/quickstart/product_improve_suggestion.py +``` + +Now you should see a Flink job submitted to the Flink Cluster in Flink web UI [localhost:8081](localhost:8081) + +After a few minutes, you can check for the output in the TaskManager output log. diff --git a/docs/content/docs/operations/_index.md b/docs/content/docs/operations/_index.md index 0b15093c..54c2d1ee 100644 --- a/docs/content/docs/operations/_index.md +++ b/docs/content/docs/operations/_index.md @@ -1,5 +1,5 @@ --- -title: Operations +title: How to Build an Agent icon: bold: true bookCollapseSection: true diff --git a/docs/content/docs/operations/configuration.md b/docs/content/docs/operations/configuration.md new file mode 100644 index 00000000..7bea4757 --- /dev/null +++ b/docs/content/docs/operations/configuration.md @@ -0,0 +1,29 @@ +--- +title: Configuration +weight: 2 +type: docs +--- + + +{{< hint warning >}} +**TODO**: How to configure Flink Agents for local execution and Flink cluster execution. + +**TODO**: List of all built-in Configuration options. +{{< /hint >}} \ No newline at end of file diff --git a/docs/content/docs/operations/deployment.md b/docs/content/docs/operations/deployment.md new file mode 100644 index 00000000..18b3c234 --- /dev/null +++ b/docs/content/docs/operations/deployment.md @@ -0,0 +1,41 @@ +--- +title: Deployment +weight: 1 +type: docs +--- + + +## Local Run with Test Data + +{{< hint warning >}} +**TODO**: How to run with test data with LocalExecutorEnvironment. +{{< /hint >}} + +## Local Run with Flink MiniCluster + +{{< hint warning >}} +**TODO**: How to run with Flink MiniCluster locally. +{{< /hint >}} + +## Run in Flink Cluster + +{{< hint warning >}} +**TODO**: How to run in Flink Cluster. +{{< /hint >}} \ No newline at end of file diff --git a/docs/content/docs/operations/monitoring.md b/docs/content/docs/operations/monitoring.md new file mode 100644 index 00000000..e008e154 --- /dev/null +++ b/docs/content/docs/operations/monitoring.md @@ -0,0 +1,47 @@ +--- +title: Monitoring +weight: 3 +type: docs +--- + + +## Metric + +{{< hint warning >}} +**TODO**: How to use add custom metrics. + +**TODO**: List of all built-in Metrics. + +**TODO**: How to check the metrics with Flink executor. +{{< /hint >}} + +## Log + +{{< hint warning >}} +**TODO**: How to add log in Flink Agents. + +**TODO**: How to check the logs with Flink executor. +{{< /hint >}} + +## Event Log + +{{< hint warning >}} +**TODO**: How to use and check the event logs. +{{< /hint >}} \ No newline at end of file