This is an automated email from the ASF dual-hosted git repository.
wenjin272 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 ce684fd0 [docs] Clarify API and language choices (#1257)
ce684fd0 is described below
commit ce684fd0aca4568fb107ca1226cd1f7f6613ccda
Author: Wenjin Xie <[email protected]>
AuthorDate: Wed Oct 14 20:38:49 2026 +0800
[docs] Clarify API and language choices (#1257)
Generated-by: Codex (GPT-6)
Co-authored-by: Codex <[email protected]>
---
.../development/calling-llms/chat-models/_index.md | 11 +-
docs/content/docs/development/calling-llms/mcp.md | 4 +
.../docs/development/calling-llms/skills.md | 6 +-
.../docs/development/create-agent/_index.md | 1 +
.../docs/development/create-agent/actions.md | 164 ++++++++++------
.../create-agent/choose-apis-and-languages.md | 207 +++++++++++++++++++++
.../docs/development/create-agent/events.md | 7 +-
.../docs/development/create-agent/overview.md | 11 +-
docs/content/docs/development/create-agent/yaml.md | 17 +-
docs/content/docs/development/react_agent.md | 5 -
.../vector-search/embedding_models/_index.md | 10 +-
.../vector-search/vector_stores/_index.md | 10 +-
docs/content/docs/faq/faq.md | 89 +--------
docs/content/docs/get-started/overview.md | 2 +-
.../docs/get-started/quickstart/parallel_llm.md | 6 +-
docs/content/docs/get-started/setup.md | 42 +++--
docs/content/docs/operations/configuration.md | 4 +-
docs/content/docs/operations/deployment.md | 21 ++-
18 files changed, 409 insertions(+), 208 deletions(-)
diff --git a/docs/content/docs/development/calling-llms/chat-models/_index.md
b/docs/content/docs/development/calling-llms/chat-models/_index.md
index b25dd780..22eb163a 100644
--- a/docs/content/docs/development/calling-llms/chat-models/_index.md
+++ b/docs/content/docs/development/calling-llms/chat-models/_index.md
@@ -51,12 +51,11 @@ The `@chat_model_setup` decorator or `@ChatModelSetup`
annotation marks a method
Flink Agents supports cross-language chat model integration, allowing you to
use chat models implemented in one language (Java or Python) from agents
written in the other language. This is particularly useful when a chat model
provider is only available in one language (e.g., the DashScope integration for
Alibaba Cloud Model Studio is currently Python-only).
-{{< hint warning >}}
-**Limitations:**
-
-- Cross-language resources are currently supported only when [running in
Flink]({{< ref "docs/operations/deployment#run-in-flink" >}}), not in local
development mode
-- Complex object serialization between languages may have limitations
-{{< /hint >}}
+Choose a Java or Python provider implementation and install its dependencies
in the
+job's environment, following [the setup instructions]({{< ref
"docs/development/create-agent/choose-apis-and-languages#integrate-the-agent-into-a-flink-job"
>}}).
+When provider results are carried in Event payloads, those payloads must use
the supported
+[Java and Python data types]({{< ref
"docs/development/create-agent/choose-apis-and-languages#data-passed-between-java-and-python"
>}}).
+For async calls, also check the [cross-language execution requirements]({{<
ref "docs/development/create-agent/actions#cross-language-async-requirements"
>}}).
### How To Use
diff --git a/docs/content/docs/development/calling-llms/mcp.md
b/docs/content/docs/development/calling-llms/mcp.md
index 36365590..167dd052 100644
--- a/docs/content/docs/development/calling-llms/mcp.md
+++ b/docs/content/docs/development/calling-llms/mcp.md
@@ -223,6 +223,10 @@ Flink Agents offers two implementations of MCP support,
based on MCP SDKs in dif
| Java | JDK 16 and below | Python SDK |
+When the selected implementation uses Python, install its Python dependencies
and
+configure the Python environment even for a Java Flink job; see
+[dependency setup]({{< ref
"docs/development/create-agent/choose-apis-and-languages#integrate-the-agent-into-a-flink-job"
>}}).
+
As shown in the table above, for Java agents running on JDK 17+, the framework
automatically uses the Java SDK implementation. If you need to use the Python
SDK instead (not recommended), you can set the `lang` parameter to `"python"`
in the `@MCPServer` annotation:
```java
@MCPServer(lang = "python")
diff --git a/docs/content/docs/development/calling-llms/skills.md
b/docs/content/docs/development/calling-llms/skills.md
index eb21803e..ed401881 100644
--- a/docs/content/docs/development/calling-llms/skills.md
+++ b/docs/content/docs/development/calling-llms/skills.md
@@ -310,11 +310,11 @@ This keeps each request lean — a skill the agent never
activates costs only it
The complete example sends arithmetic questions such as `What is (2 + 3) * 4?`
to `MathAgent`. Its model loads `math-calculator`, uses `bash` to run `bc`, and
returns the numeric result through the normal chat response path. For the chat
request and response Actions, see [Chat with Models]({{< ref
"docs/development/calling-llms/chat" >}}).
-| Language | Flink job entry point | Agent definition | Skill instructions |
-|----------|-----------------------|------------------|--------------------|
+| Language | Example job | Agent definition | Skill instructions |
+|----------|-------------|------------------|--------------------|
| Python |
[skills_agent_example.py](https://github.com/apache/flink-agents/blob/main/python/flink_agents/examples/quickstart/skills_agent_example.py)
|
[MathAgent](https://github.com/apache/flink-agents/blob/main/python/flink_agents/examples/quickstart/agents/math_agent.py)
|
[SKILL.md](https://github.com/apache/flink-agents/blob/main/python/flink_agents/examples/quickstart/resources/skills/math-calculator/SKILL.md)
|
| Java |
[SkillsAgentExample.java](https://github.com/apache/flink-agents/blob/main/examples/src/main/java/org/apache/flink/agents/examples/SkillsAgentExample.java)
|
[MathAgent](https://github.com/apache/flink-agents/blob/main/examples/src/main/java/org/apache/flink/agents/examples/agents/MathAgent.java)
|
[SKILL.md](https://github.com/apache/flink-agents/blob/main/examples/src/main/resources/skills/math-calculator/SKILL.md)
|
The Python example loads its bundled skill through `Skills.from_package`; the
Java example uses `Skills.fromClasspath`. Make `bash` and `bc` available on the
TaskManagers and prepare the Ollama model configured by the example
(`qwen3.5:9b`).
-Follow [Setup]({{< ref "docs/get-started/setup" >}}) for dependencies and
[Build Your First Agent]({{< ref
"docs/get-started/quickstart/create-agent/single-agent#run-the-example" >}})
for the build and submission workflow, substituting the Skills job entry point
above. See [Integrate with Flink]({{< ref
"docs/development/integrate_with_flink" >}}) for stream integration details.
+Follow [Setup]({{< ref "docs/get-started/setup" >}}) for dependencies and
[Build Your First Agent]({{< ref
"docs/get-started/quickstart/create-agent/single-agent#run-the-example" >}})
for the build and submission workflow, using the corresponding Skills example
job above. See [Integrate with Flink]({{< ref
"docs/development/integrate_with_flink" >}}) for stream integration details.
diff --git a/docs/content/docs/development/create-agent/_index.md
b/docs/content/docs/development/create-agent/_index.md
index 601023ab..7d624da3 100644
--- a/docs/content/docs/development/create-agent/_index.md
+++ b/docs/content/docs/development/create-agent/_index.md
@@ -26,4 +26,5 @@ under the License.
- [Overview]({{< ref "docs/development/create-agent/overview" >}})
- [Actions]({{< ref "docs/development/create-agent/actions" >}})
- [Events]({{< ref "docs/development/create-agent/events" >}})
+- [Choose APIs and Languages]({{< ref
"docs/development/create-agent/choose-apis-and-languages" >}})
- [YAML API]({{< ref "docs/development/create-agent/yaml" >}})
diff --git a/docs/content/docs/development/create-agent/actions.md
b/docs/content/docs/development/create-agent/actions.md
index 1c5b968d..4ceeb2a9 100644
--- a/docs/content/docs/development/create-agent/actions.md
+++ b/docs/content/docs/development/create-agent/actions.md
@@ -243,6 +243,72 @@ evaluated as doubles and may lose precision.
start. This happens before event-time evaluation and is not controlled by
the condition evaluation
failure strategy. Dynamic access inside a selected top-level attribute
remains supported.
+### Cross-language Actions
+
+To declare a cross-language Action, apply `action(...)` to a `Function`
descriptor
+in Python, or annotate a `static final` `Function` field in Java. The
descriptor
+identifies the function to execute.
+
+{{< tabs "Cross-language Actions" >}}
+
+{{< tab "Python" >}}
+```python
+from flink_agents.api.function import JavaFunction
+
+class MyAgent(Agent):
+ # Action signatures are fixed (Event, RunnerContext), so for_action
+ # fills the Java parameter types for you — only the class and method.
+ handle_input = action(InputEvent.EVENT_TYPE)(
+ JavaFunction.for_action("com.example.MyHandlers", "handleInput"))
+```
+{{< /tab >}}
+
+{{< tab "Java" >}}
+```java
+import org.apache.flink.agents.api.function.PythonFunction;
+
+public class MyAgent extends Agent {
+ @Action(EventType.InputEvent)
+ private static final PythonFunction handleInput =
+ PythonFunction.of("my_pkg.handlers", "handle_input");
+}
+```
+{{< /tab >}}
+
+{{< /tabs >}}
+
+**Override the Action name (optional)**
+
+By default, the examples above use the member name as the Action name:
+`handle_input` in Python and `handleInput` in Java. Set `name` to give the
Action
+a different name. These declarations name the Action `process_input`:
+
+{{< tabs "Override Cross-language Action Name" >}}
+
+{{< tab "Python" >}}
+```python
+class MyAgent(Agent):
+ handle_input = action(InputEvent.EVENT_TYPE, name="process_input")(
+ JavaFunction.for_action("com.example.MyHandlers", "handleInput")
+ )
+```
+{{< /tab >}}
+
+{{< tab "Java" >}}
+```java
+public class MyAgent extends Agent {
+ @Action(value = EventType.InputEvent, name = "process_input")
+ private static final PythonFunction handleInput =
+ PythonFunction.of("my_pkg.handlers", "handle_input");
+}
+```
+{{< /tab >}}
+
+{{< /tabs >}}
+
+For dependency setup and supported payload types, see
+[Choose APIs and Languages]({{< ref
"docs/development/create-agent/choose-apis-and-languages" >}}).
+
### Async Execution
Use `execute_async` (Python) or `executeAsync` (Java) to run a function
@@ -296,6 +362,48 @@ Obtain resources before creating calls, and update memory
or send events after
awaiting results. Callbacks must not access `RunnerContext`, and any clients
they
share must support concurrent use.
+#### JDK and scheduling requirements
+
+For concurrency between Actions:
+
+- **Java on JDK 21+:** enable continuation-based execution by adding
+ `--add-exports=java.base/jdk.internal.vm=ALL-UNNAMED` to the JVM options,
including
+ `env.java.opts.all` when running on a cluster.
+- **Java on JDK 11–20:** the experimental parallel execution engine is enabled
by
+ default for plans whose Actions are all Java. If the plan declares Python
Resources,
+ it also requires a Flink version supporting cross-language async calls
(below).
+ Setting `parallel-execution.enabled` to `false`, or including Python Actions,
+ disables this engine; a Java single-call `executeAsync(...).await()` then
runs
+ synchronously. Use `gather` to run a batch concurrently.
+- **Python Actions:** use `async def` and the framework's
`AsyncFuture`/`gather` APIs.
+ Use `gather` to await multiple calls concurrently; awaiting each call in
turn runs
+ them sequentially.
+
+See [Core Options]({{< ref "docs/operations/configuration#core-options" >}})
+for worker-pool and concurrency limits. These scheduling rules also apply to
durable
+async calls; persistence adds the [durable execution
requirements](#durable-execution).
+
+#### Cross-language async requirements
+
+Async calls across Java/Python require Flink **1.20.5+**, **2.0.2+**,
**2.1.3+**,
+**2.2.1+**, or **2.3+**, within the respective release line. Use these
versions for
+custom cross-language async calls and for asynchronous built-in chat and
+context-retrieval Actions that use an opposite-language Resource.
+
+{{< hint warning >}}
+Async actions in either language may call cross-language resources. Within one
async execution,
+keep the cross-language call chain to one reverse callback. Only the following
call shapes are
+supported:
+
+- Python action → Java resource → Python callback
+- Java action → Python resource → Java callback
+
+For example, a Python action may use a Java `ChatModelSetup` backed by a Python
+`ChatModelConnection`. Multiple or deeper cross-language callbacks, such as
+Python→Java→Python→Java or Java→Python→Java→Python, are not recommended and
may deadlock
+when an outer call occupies an async or interpreter worker while waiting for
another worker.
+{{< /hint >}}
+
### Durable Execution
Use durable execution when an operation needs result persistence and recovery
replay. When a matching persisted result is available during recovery, the
framework reuses it without invoking the function again. When recovery
re-enters an action that has not been recorded as completed, code outside
`durable_execute` / `durable_execute_async` will still be re-executed.
@@ -497,61 +605,5 @@ public static void processInput(Event event, RunnerContext
ctx) throws Exception
}
```
-{{< hint info >}}
-To use async execution on JDK 21+, user should append jvm option
`--add-exports=java.base/jdk.internal.vm=ALL-UNNAMED` to
[env.java.opts.all](https://nightlies.apache.org/flink/flink-docs-stable/docs/deployment/config/#env-java-opts-all)
before start the flink cluster.
-{{< /hint >}}
-{{< /tab >}}
-{{< /tabs >}}
-
-{{< hint warning >}}
-Async actions in either language may call cross-language resources. Within one
async execution,
-keep the cross-language call chain to one reverse callback. Only the following
call shapes are
-supported:
-
-- Python action → Java resource → Python callback
-- Java action → Python resource → Java callback
-
-For example, a Python action may use a Java `ChatModelSetup` backed by a Python
-`ChatModelConnection`. Multiple or deeper cross-language callbacks, such as
-Python→Java→Python→Java or Java→Python→Java→Python, are not recommended and
may deadlock
-when an outer call occupies an async or interpreter worker while waiting for
another worker.
-{{< /hint >}}
-
-### Cross-language Actions
-
-An action declared in one language can dispatch its body to the other
language. The declared member *is* the executable target, so no placeholder
body is needed: apply `action(...)` to a `Function` descriptor in Python, or
annotate a `static final` `Function` field in Java. The member name becomes the
action name, and can be overridden with `name=` (Python) or `name` (Java).
-
-{{< tabs "Cross-language Actions" >}}
-
-{{< tab "Python" >}}
-```python
-from flink_agents.api.function import JavaFunction
-
-class MyAgent(Agent):
- # Action signatures are fixed (Event, RunnerContext), so for_action
- # fills the Java parameter types for you — only the class and method.
- handle_input = action(InputEvent.EVENT_TYPE)(
- JavaFunction.for_action("com.example.MyHandlers", "handleInput"))
-```
-{{< /tab >}}
-
-{{< tab "Java" >}}
-```java
-import org.apache.flink.agents.api.function.PythonFunction;
-
-public class MyAgent extends Agent {
- @Action(EventType.InputEvent)
- private static final PythonFunction handleInput =
- PythonFunction.of("my_pkg.handlers", "handle_input");
-}
-```
{{< /tab >}}
-
{{< /tabs >}}
-
-{{< hint warning >}}
-**Limitations:**
-
-- Cross-language actions are currently supported only when [running in
Flink]({{< ref "docs/operations/deployment#run-in-flink" >}}), not in local
development mode
-- Complex object serialization between languages may have limitations
-{{< /hint >}}
diff --git
a/docs/content/docs/development/create-agent/choose-apis-and-languages.md
b/docs/content/docs/development/create-agent/choose-apis-and-languages.md
new file mode 100644
index 00000000..21a4e228
--- /dev/null
+++ b/docs/content/docs/development/create-agent/choose-apis-and-languages.md
@@ -0,0 +1,207 @@
+---
+title: "Choose APIs and Languages"
+weight: 4
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+Flink Agents provides Java, Python, and YAML APIs for defining an Agent. All
three
+APIs use the same core concepts: Actions process Events and use Resources.
+
+Actions and Resources can be implemented in Java or Python and used across
languages
+where supported. Flink Agents aims to keep its APIs and component behavior
consistent
+across languages. However, language features, runtime requirements, and
available
+ecosystem integrations may lead to differences in capabilities and setup.
+
+## Define an Agent
+
+Choose one of the three APIs to define the Agent:
+
+| API | How the Agent is defined | Guide |
+|---|---|---|
+| Java | Define an `Agent` class in Java. | [Create a Single Agent (Java)]({{<
ref "docs/get-started/quickstart/create-agent/single-agent" >}}) |
+| Python | Define an `Agent` class in Python. | [Create a Single Agent
(Python)]({{< ref "docs/get-started/quickstart/create-agent/single-agent" >}}) |
+| YAML | Describe the Agent in a YAML file. | [YAML API]({{< ref
"docs/development/create-agent/yaml" >}}) |
+
+## Use Java and Python Actions and Resources
+
+The language used to define the Agent does not require every Action and
Resource to
+use the same language. A Java-defined Agent can use supported Python
components, and
+a Python-defined Agent can use supported Java components. In YAML, set `type`
to
+`java` or `python` for each component; an omitted `type` defaults to `python`.
+
+Cross-language support is available for the following component APIs:
+
+| Component | Authoring guide |
+|---|---|
+| Actions | [Cross-language Actions]({{< ref
"docs/development/create-agent/actions#cross-language-actions" >}}) |
+| Function Tools | [YAML cross-language example]({{< ref
"docs/development/create-agent/yaml#cross-language-agents" >}}) and [Tool
Use]({{< ref "docs/development/calling-llms/tool_use" >}}) |
+| Chat model connections and setups | [Using Cross-Language Chat
Providers]({{< ref
"docs/development/calling-llms/chat-models#using-cross-language-providers" >}})
|
+| Embedding model connections and setups | [Using Cross-Language Embedding
Providers]({{< ref
"docs/development/vector-search/embedding_models#using-cross-language-providers"
>}}) |
+| Vector Stores | [Using Cross-Language Vector Stores]({{< ref
"docs/development/vector-search/vector_stores#using-cross-language-providers"
>}}) |
+
+For YAML examples, see
+[Cross-language agents]({{< ref
"docs/development/create-agent/yaml#cross-language-agents" >}}).
+
+## Integrate the Agent into a Flink job
+
+An Agent runs as part of a Flink job. For Agents defined with the Java or
Python API,
+the API determines how they are added to Flink: a Java Agent is added to a
Java Flink
+job, and a Python Agent is added to a PyFlink job. YAML is flexible and can be
loaded
+from either type of job.
+
+| Agent API | Flink job | How the Agent is added |
+|---|---|---|
+| Java | Java Flink job | Pass the Java `Agent` instance to `apply(...)`. |
+| Python | PyFlink job | Pass the Python `Agent` instance to `apply(...)`. |
+| YAML | Java Flink or PyFlink job | Load the YAML with `loadYaml(...)` or
`load_yaml(...)`, then pass the Agent name to `apply(...)`. |
+
+For a Java Flink job, add the
+[Maven dependencies]({{< ref
"docs/get-started/setup#maven-dependencies-for-java" >}})
+and [Flink Agents Java runtime JAR]({{< ref
"docs/get-started/setup#install-flink-agents-java-library-java-flink-jobs" >}}).
+For a PyFlink job, install the
+[Python package]({{< ref "docs/get-started/setup#install-flink-agents-package"
>}})
+and configure [PYTHONPATH]({{< ref
"docs/get-started/setup#configure-pythonpath" >}}).
+`AgentsExecutionEnvironment.get_execution_environment(env=...)` registers the
Flink
+Agents JARs bundled with the Python package.
+
+When using components implemented in the other language, provide their
dependencies
+as well. For a PyFlink job that uses Java components, add the required
application and
+provider JARs. For a Java Flink job that uses Python components, install the
Flink
+Agents Python package, component modules, and provider dependencies in the
Python
+environment used for submission and on the Flink workers.
+
+See [Integrate with Flink]({{< ref "docs/development/integrate_with_flink"
>}}) for
+DataStream and Table API usage, [Loading and Running YAML]({{< ref
"docs/development/create-agent/yaml#loading-and-running" >}})
+for YAML loading, and [Deployment]({{< ref
"docs/operations/deployment#submit-to-flink-cluster" >}})
+for submission commands.
+
+## Differences between the Java and Python APIs
+
+The Java and Python APIs provide the same core Agent model, but their Action
syntax,
+execution requirements, and available ecosystem integrations differ.
+
+### Async Action execution
+
+Both APIs provide asynchronous execution and `gather` for running multiple
calls.
+Python Actions use `async def` and `await`. Java Actions use
+`executeAsync(...).await()`, and Action scheduling and required JVM options
depend on
+the JDK version. See [Async Execution]({{< ref
"docs/development/create-agent/actions#async-execution" >}})
+for the complete API and runtime requirements.
+
+### Available integrations by language
+
+The tables below show the available implementation languages for each built-in
+integration. If an integration is available in only one language, use its
+cross-language support where available and install its dependencies.
+
+**Chat Models**
+
+| Provider | Python | Java |
+|---|---|---|
+| [Amazon Bedrock]({{< ref
"docs/development/calling-llms/chat-models/providers#amazon-bedrock" >}}) | ❌ |
✅ |
+| [Anthropic]({{< ref
"docs/development/calling-llms/chat-models/providers#anthropic" >}}) | ✅ | ✅ |
+| [Azure OpenAI]({{< ref
"docs/development/calling-llms/chat-models/providers#azure-openai" >}}) | ✅ | ✅
|
+| [Gemini]({{< ref
"docs/development/calling-llms/chat-models/providers#gemini" >}}) | ❌ | ✅ |
+| [Ollama]({{< ref
"docs/development/calling-llms/chat-models/providers#ollama" >}}) | ✅ | ✅ |
+| [OpenAI]({{< ref
"docs/development/calling-llms/chat-models/providers#openai" >}}) | ✅ | ✅ |
+| [Alibaba Cloud Model Studio (DashScope)]({{< ref
"docs/development/calling-llms/chat-models/providers#alibaba-cloud-model-studio-dashscope"
>}}) | ✅ | ❌ |
+| [vLLM]({{< ref "docs/development/calling-llms/chat-models/providers#vllm"
>}}) | ✅ | ✅ |
+| [Watsonx (IBM watsonx.ai)]({{< ref
"docs/development/calling-llms/chat-models/providers#watsonx-ibm-watsonxai"
>}}) | ✅ | ✅ |
+
+**Embedding Models**
+
+| Provider | Python | Java |
+|---|---|---|
+| [Amazon Bedrock]({{< ref
"docs/development/vector-search/embedding_models/providers#amazon-bedrock" >}})
| ❌ | ✅ |
+| [Ollama]({{< ref
"docs/development/vector-search/embedding_models/providers#ollama" >}}) | ✅ | ✅
|
+| [OpenAI]({{< ref
"docs/development/vector-search/embedding_models/providers#openai" >}}) | ✅ | ✅
|
+| [Alibaba Cloud Model Studio (DashScope)]({{< ref
"docs/development/vector-search/embedding_models/providers#alibaba-cloud-model-studio-dashscope"
>}}) | ✅ | ❌ |
+
+**Vector Stores**
+
+| Provider | Python | Java |
+|---|---|---|
+| [Amazon OpenSearch]({{< ref
"docs/development/vector-search/vector_stores/providers#amazon-opensearch" >}})
| ❌ | ✅ |
+| [Amazon S3 Vectors]({{< ref
"docs/development/vector-search/vector_stores/providers#amazon-s3-vectors" >}})
| ❌ | ✅ |
+| [Chroma]({{< ref
"docs/development/vector-search/vector_stores/providers#chroma" >}}) | ✅ | ❌ |
+| [Elasticsearch]({{< ref
"docs/development/vector-search/vector_stores/providers#elasticsearch" >}}) | ❌
| ✅ |
+| [Mem0]({{< ref "docs/development/vector-search/vector_stores/providers#mem0"
>}}) | ✅ | ❌ |
+| [Milvus]({{< ref
"docs/development/vector-search/vector_stores/providers#milvus" >}}) | ❌ | ✅ |
+
+**MCP Server**
+
+| Provider | Python | Java |
+|---|---|---|
+| [MCP Server]({{< ref "docs/development/calling-llms/mcp" >}}) | ✅ | ✅ |
+
+> **Note**: Java native MCP support requires **JDK 17+**. For JDK 11-16, the
framework automatically uses the Python SDK via cross-language support, which
requires a configured Python environment and the Python MCP dependencies. See
[MCP]({{< ref "docs/development/calling-llms/mcp" >}}) for details.
+
+## Cross-language requirements
+
+Python Agents cross the Python-Java boundary when exchanging data with the Java
+runtime. Agents that call components implemented in the other language also
have
+additional async execution requirements.
+
+### Data passed between Java and Python
+
+Event attributes passed between Java and Python, including `InputEvent.input`
and
+`OutputEvent.output`, support the following portable JSON value shapes:
+
+| Value | Java representation | Python representation |
+|---|---|---|
+| Null | `null` | `None` |
+| Boolean | `boolean` / `Boolean` | `bool` |
+| Integer | Integral numbers, such as `Integer` or `Long` | `int` |
+| Floating-point number | `Float` or `Double` | `float` |
+| Text | `String` | `str` |
+| Sequence | JSON arrays, read as `List` | `list` |
+| Object / mapping | `Map<String, Object>` | `dict` with string keys |
+
+Follow these rules:
+
+- Sequences and mappings can contain any of the values in the table.
+- Numeric wrapper types, collection classes, and custom classes are not
preserved.
+ JSON-serializable Java POJOs and Python models arrive as `Map` or `dict`
values;
+ reconstruct the target-language type explicitly. Objects that cannot be
serialized
+ to JSON are not supported.
+- Keep integers within the target type's range and use finite floating-point
values.
+ Encode exact decimals and larger numbers as strings when precision must be
preserved.
+
+{{< hint info >}}
+Flink Agents uses a Java runtime. Data from the Python API crosses the
Python-Java
+boundary even when every Action and Resource is implemented in Python. The
rules in
+this section therefore apply to every Python Agent.
+{{< /hint >}}
+
+#### Memory values
+
+Python sensory and short-term memory accept built-in `None`, `bool`, `int`,
`float`,
+`str`, `bytes`, `list`, and string-keyed `dict` values recursively. Convert
custom
+models, tuples, sets, and enums before storing them. On this path, `bytes`
maps to Java
+`byte[]`; raw bytes are not supported in JSON Event attributes. See
+[Sensory and Short-Term Memory]({{< ref
"docs/development/memory/sensory_and_short_term_memory" >}}).
+
+### Async calls between Java and Python
+
+Async calls across Java and Python require a supported Flink version. Keep each
+cross-language call chain to one reverse callback; deeper callback chains may
deadlock.
+See [Cross-language async requirements]({{< ref
"docs/development/create-agent/actions#cross-language-async-requirements" >}})
+for supported Flink versions and call shapes.
diff --git a/docs/content/docs/development/create-agent/events.md
b/docs/content/docs/development/create-agent/events.md
index 80c5e2c8..3c00aa58 100644
--- a/docs/content/docs/development/create-agent/events.md
+++ b/docs/content/docs/development/create-agent/events.md
@@ -94,7 +94,9 @@ to the replayed trigger again.
Events are serialized as JSON when passed between Python actions or across the
Java-Python boundary. When an event crosses that boundary, its **type** and its
**payload** are handled differently.
-**Built-in event types are restored automatically.** At the JSON boundary
(`Event.fromJson` in Java, `Event.from_json` in Python) the framework restores
every built-in event type to its concrete subclass and validates its fixed
attribute schema. So inside an action, a dispatched `InputEvent`,
`ChatRequestEvent`, `ChatResponseEvent`, or any other built-in event is already
its concrete type: use it directly (with a cast in Java) instead of calling
`from_event` / `fromEvent`. Those reconstr [...]
+**Built-in event types are restored automatically.** A dispatched `InputEvent`,
+`ChatRequestEvent`, `ChatResponseEvent`, or other built-in Event has its
concrete
+type and validated attributes. Use it directly inside an Action, with a cast
in Java.
**Custom event types stay generic.** A user-defined event type is not known to
the framework, so it arrives as a generic `Event`; call your subclass's
`from_event` / `fromEvent` to reconstruct it (see [Custom Event
Subclasses](#custom-event-subclasses)).
@@ -106,6 +108,9 @@ Events are serialized as JSON when passed between Python
actions or across the J
input_data = ItemData.model_validate(event.input)
```
+For supported payload values, see
+[Data passed between Java and Python]({{< ref
"docs/development/create-agent/choose-apis-and-languages#data-passed-between-java-and-python"
>}}).
+
### Custom Event Subclasses
Users can also define custom event subclasses for reusable, structured events.
Data should be stored in the `attributes` map, and the subclass must implement
a `from_event` / `fromEvent` factory method that validates required attributes
and reconstructs typed objects from the deserialized data.
diff --git a/docs/content/docs/development/create-agent/overview.md
b/docs/content/docs/development/create-agent/overview.md
index 0ccb7327..aef72747 100644
--- a/docs/content/docs/development/create-agent/overview.md
+++ b/docs/content/docs/development/create-agent/overview.md
@@ -37,10 +37,6 @@ contain cycles. Each node is an action, and each edge
represents an event flow b
An 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.
-{{< hint info >}}
-For guidance on choosing Java or Python, see [Should I choose Java or
Python?]({{< ref "docs/faq/faq#q3-should-i-choose-java-or-python" >}}).
-{{< /hint >}}
-
## Agent Example
{{< tabs "Agent Example" >}}
@@ -235,4 +231,9 @@ public class ReviewAnalysisAgent extends Agent {
{{< /tabs >}}
-Continue with [Actions]({{< ref "docs/development/create-agent/actions" >}})
and [Events]({{< ref "docs/development/create-agent/events" >}}).
+Next, learn how [Actions]({{< ref "docs/development/create-agent/actions" >}})
+process incoming Events and emit new Events, and how
+[Events]({{< ref "docs/development/create-agent/events" >}}) carry data and
trigger
+Actions. Then see
+[Choose APIs and Languages]({{< ref
"docs/development/create-agent/choose-apis-and-languages" >}})
+to choose among the Java, Python, and YAML APIs and combine Java and Python
components.
diff --git a/docs/content/docs/development/create-agent/yaml.md
b/docs/content/docs/development/create-agent/yaml.md
index 6de28fd6..5f0fb6f8 100644
--- a/docs/content/docs/development/create-agent/yaml.md
+++ b/docs/content/docs/development/create-agent/yaml.md
@@ -421,6 +421,11 @@ Composing one agent across multiple YAML files is **not**
supported. If two file
## Loading and Running
+YAML describes an Agent but is not submitted to Flink by itself. Create a Java
Flink
+or PyFlink job that loads the YAML and applies the Agent, then submit that
job. Install
+the Java and Python dependencies required by the implementations referenced in
the
+YAML. See [Choose APIs and Languages]({{< ref
"docs/development/create-agent/choose-apis-and-languages#integrate-the-agent-into-a-flink-job"
>}}).
+
`AgentsExecutionEnvironment` exposes a `load_yaml` / `loadYaml` method that
parses one or more YAML files and:
- registers all shared resources on the environment, and
@@ -661,7 +666,10 @@ Loaded with `agents_env.load_yaml(...)` on the Python
side, this produces an age
- `math_chat_model` is a Python Ollama setup that calls a Java function tool
through the cross-language tool bridge.
- `creative_chat_model` is a Java Ollama setup driven from the Python loader
via the Java chat-model wrapper.
-The bridge is symmetric: the same file loaded by the **Java loader** can
declare `type: python` resources, and the Java loader wraps each Python
implementation through its Python wrapper. So a Java-side agent can drive a
Python chat model or call a Python tool, just as the example above drives Java
pieces from the Python loader.
+The **Java loader** also supports `type: python` for these components. Load
the YAML
+in a Java Flink job and use each component's `type:` to select its
implementation.
+Application payloads must use the supported
+[Java and Python data types]({{< ref
"docs/development/create-agent/choose-apis-and-languages#data-passed-between-java-and-python"
>}}).
Not every resource type is cross-language. Currently `actions`, `tools`,
`chat_model_connections`, `chat_model_setups`, `embedding_model_connections`,
`embedding_model_setups`, and `vector_stores` support `type:` on the opposite
language; others (e.g. `mcp_servers`) do not.
@@ -698,4 +706,9 @@ Continuous tests then verify cross-runtime consistency:
- the Pydantic specs stay aligned with the Python `Agent` API;
- the Java POJOs stay aligned with the Java `Agent` API.
-This keeps the YAML API a true cross-language contract: a YAML file that
validates against the schema is guaranteed to load and run on either the Python
or the Java loader (subject only to the language-specific differences
documented above, such as `parameter_types` on Java tools).
+These checks keep the YAML structure aligned across loaders. Schema validation
does
+not verify that referenced classes/functions are installed, that a component
supports
+the selected implementation language, or that its provider is reachable. Before
+running the job, follow [Choose APIs and Languages]({{< ref
"docs/development/create-agent/choose-apis-and-languages" >}})
+to check language support and provision the required dependencies. Java Tools
also
+require the documented `parameter_types`.
diff --git a/docs/content/docs/development/react_agent.md
b/docs/content/docs/development/react_agent.md
index ba7b68ca..430ffc66 100644
--- a/docs/content/docs/development/react_agent.md
+++ b/docs/content/docs/development/react_agent.md
@@ -28,10 +28,6 @@ Flink Agents provides `ReActAgent` as a built-in subclass of
`Agent` that implem
ReAct Agent is a general paradigm that combines reasoning and action
capabilities to solve complex tasks. Leveraging this paradigm, the user only
needs to specify the goal with prompt and provide available tools, and the LLM
will decide how to achieve the goal and take actions autonomously.
-{{< hint info >}}
-For guidance on choosing Java or Python, see [Should I choose Java or
Python?]({{< ref "docs/faq/faq#q3-should-i-choose-java-or-python" >}}).
-{{< /hint >}}
-
{{< hint info >}}
The snippets on this page are fragments that each focus on a single concept.
For an end-to-end runnable walkthrough, see the [Use the Built-in ReAct
Agent]({{< ref "docs/get-started/quickstart/react_agent" >}}) and the full
source:
[`react_agent_example.py`](https://github.com/apache/flink-agents/blob/main/python/flink_agents/examples/quickstart/react_agent_example.py)
(Python) and
[`ReActAgentExample.java`](https://github.com/apache/flink-agents/blob/main/examples/src/main/java/org/apac
[...]
{{< /hint >}}
@@ -402,4 +398,3 @@ The constructor registers those sources on the agent, so
they do not also need `
## As a Sub-Agent
A ReActAgent can run as a sub-agent of another agent, delegated to by the
parent's chat model or called from the parent's actions. See [Use a ReActAgent
as the child]({{< ref
"docs/development/multi-agent/subagents#use-a-reactagent-as-the-child" >}}).
-
diff --git
a/docs/content/docs/development/vector-search/embedding_models/_index.md
b/docs/content/docs/development/vector-search/embedding_models/_index.md
index 13a4f111..a800a655 100644
--- a/docs/content/docs/development/vector-search/embedding_models/_index.md
+++ b/docs/content/docs/development/vector-search/embedding_models/_index.md
@@ -193,11 +193,11 @@ public class MyAgent extends Agent {
Flink Agents supports cross-language embedding model integration, allowing you
to use embedding models implemented in one language (Java or Python) from
agents written in the other language. This is particularly useful when an
embedding model provider is only available in one language (e.g., the DashScope
embedding integration for Alibaba Cloud Model Studio is currently Python-only).
-{{< hint warning >}}
-**Limitations:**
-- Cross-language resources are currently supported only when [running in
Flink]({{< ref "docs/operations/deployment#run-in-flink" >}}), not in local
development mode
-- Complex object serialization between languages may have limitations
-{{< /hint >}}
+Choose a Java or Python provider implementation and install its dependencies
in the
+job's environment, following [the setup instructions]({{< ref
"docs/development/create-agent/choose-apis-and-languages#integrate-the-agent-into-a-flink-job"
>}}).
+When provider results are carried in Event payloads, those payloads must use
the supported
+[Java and Python data types]({{< ref
"docs/development/create-agent/choose-apis-and-languages#data-passed-between-java-and-python"
>}}).
+For async calls, also check the [cross-language execution requirements]({{<
ref "docs/development/create-agent/actions#cross-language-async-requirements"
>}}).
### How To Use
To use a resource implemented in another language, declare its implementation
class with the corresponding cross-language resource descriptor:
diff --git
a/docs/content/docs/development/vector-search/vector_stores/_index.md
b/docs/content/docs/development/vector-search/vector_stores/_index.md
index 6c3186b8..382e3f41 100644
--- a/docs/content/docs/development/vector-search/vector_stores/_index.md
+++ b/docs/content/docs/development/vector-search/vector_stores/_index.md
@@ -448,11 +448,11 @@ public class MyAgent extends Agent {
Flink Agents supports cross-language vector store integration, allowing you to
use vector stores implemented in one language (Java or Python) from agents
written in the other language. This is particularly useful when a vector store
provider is only available in one language (e.g., Elasticsearch and Milvus are
currently Java-only, Chroma is currently Python-only).
-{{< hint warning >}}
-**Limitations:**
-- Cross-language resources are currently supported only when [running in
Flink]({{< ref "docs/operations/deployment#run-in-flink" >}}), not in local
development mode
-- Complex object serialization between languages may have limitations
-{{< /hint >}}
+Choose a Java or Python provider implementation and install its dependencies
in the
+job's environment, following [the setup instructions]({{< ref
"docs/development/create-agent/choose-apis-and-languages#integrate-the-agent-into-a-flink-job"
>}}).
+When provider results are carried in Event payloads, those payloads must use
the supported
+[Java and Python data types]({{< ref
"docs/development/create-agent/choose-apis-and-languages#data-passed-between-java-and-python"
>}}).
+For async calls, also check the [cross-language execution requirements]({{<
ref "docs/development/create-agent/actions#cross-language-async-requirements"
>}}).
### How To Use
diff --git a/docs/content/docs/faq/faq.md b/docs/content/docs/faq/faq.md
index 1ca449ec..1e31f9bf 100644
--- a/docs/content/docs/faq/faq.md
+++ b/docs/content/docs/faq/faq.md
@@ -25,9 +25,10 @@ under the License.
This page describes the solutions to some common questions for Flink Agents
users.
-## Q1: What are the Python environment considerations when running Flink
Agents jobs?
+## Q1: What are the Python environment considerations when using Python with
Flink Agents?
-To ensure stability and compatibility when running Flink Agents jobs, please
be aware of the following Python environment guidelines:
+When using a PyFlink job, Python components, or another Flink Agents feature
that
+uses Python, follow these Python environment guidelines:
- **Recommended Python versions**: It is advised to use officially supported
Python versions such as Python 3.10, 3.11 or 3.12. These versions have been
thoroughly tested and offer the best compatibility with Flink Agents.
@@ -40,7 +41,7 @@ To ensure stability and compatibility when running Flink
Agents jobs, please be
- **For macOS users**: Use Homebrew to install Python (e.g., `brew install
python`).
- **For Windows users**: Download and install the official version from
the [Python website](https://www.python.org/downloads/).
-- **Avoid using Python installed via uv**: Currently, it is not recommended to
run Flink Agents jobs with a Python interpreter installed via the `uv` tool, as
this may lead to potential compatibility issues or instability. For example,
you may encounter the following gRPC-related error:
+- **Avoid using Python installed via uv**: Currently, it is not recommended to
use a Python interpreter installed via the `uv` tool with Flink Agents, as this
may lead to potential compatibility issues or instability. For example, you may
encounter the following gRPC-related error:
```
Logging client failed: <_MultiThreadedRendezvous of RPC that terminated
with:
@@ -55,87 +56,7 @@ To ensure stability and compatibility when running Flink
Agents jobs, please be
If you see an error like this, switch immediately to one of the officially
recommended installation methods and confirm that you're using a supported
Python version.
-## Q2: Why do cross-language resources not work in local development mode?
-
-Cross-language resources, such as using Java resources from Python or vice
versa, are currently supported only when running in Flink. Local development
mode does not support cross-language resources.
-
-This limitation exists because cross-language communication requires the Flink
runtime environment to effectively bridge Java and Python processes. In local
development mode, this bridge is unavailable.
-
-To use cross-language resources, please test the functionality by deploying to
a Flink standalone cluster.
-
-## Q3: Should I choose Java or Python?
-
-When choosing between Flink Agents' Java API and Python API, consider the
following factors:
-
-1. **Team experience and preferences**
-2. **JDK version** (for Java users)
-3. **Integration supports**
-
-### Understanding Async Execution and JDK Versions
-
-Async execution can significantly improve performance by allowing multiple
operations to run concurrently. However, async execution support varies by
language and JDK version:
-
-| Environment | Async Execution Support |
-|-------------|------------------------|
-| Python | ✅ Supported |
-| Java (JDK 21+) | ✅ Supported (via Continuation API) |
-| Java (JDK < 21) | ❌ Not supported (falls back to synchronous execution) |
-
-This is important because:
-
-- **For Python users**: Async execution is always available.
-- **For Java users on JDK 21+**: Async execution is available.
-- **For Java users on JDK < 21**: Async execution is not available and falls
back to synchronous execution.
-
-> **Cross-language async note**: Async execution for cross-language resources
requires the pemja 0.5.7 fix, available in Flink 1.20.5+ / 2.0.2+ / 2.1.3+ /
2.2.1+ / 2.3+. Current builds target Flink 2.3.0, which includes the fix, so
cross-language async is enabled by default; on older Flink versions it falls
back to synchronous execution automatically.
-
-### Native Integration Support Matrix
-
-Flink Agents provides built-in integrations for many ecosystem providers. Some
integrations are only available in one language. For those marked as ❌, you can
still use them from the other language via cross-language support.
-
-**Chat Models**
-
-| Provider | Python | Java |
-|---|---|---|
-| [Amazon Bedrock]({{< ref
"docs/development/calling-llms/chat-models/providers#amazon-bedrock" >}}) | ❌ |
✅ |
-| [Anthropic]({{< ref
"docs/development/calling-llms/chat-models/providers#anthropic" >}}) | ✅ | ✅ |
-| [Azure OpenAI]({{< ref
"docs/development/calling-llms/chat-models/providers#azure-openai" >}}) | ✅ | ✅
|
-| [Gemini]({{< ref
"docs/development/calling-llms/chat-models/providers#gemini" >}}) | ❌ | ✅ |
-| [Ollama]({{< ref
"docs/development/calling-llms/chat-models/providers#ollama" >}}) | ✅ | ✅ |
-| [OpenAI]({{< ref
"docs/development/calling-llms/chat-models/providers#openai" >}}) | ✅ | ✅ |
-| [Alibaba Cloud Model Studio (DashScope)]({{< ref
"docs/development/calling-llms/chat-models/providers#alibaba-cloud-model-studio-dashscope"
>}}) | ✅ | ❌ |
-| [vLLM]({{< ref "docs/development/calling-llms/chat-models/providers#vllm"
>}}) | ✅ | ✅ |
-| [Watsonx (IBM watsonx.ai)]({{< ref
"docs/development/calling-llms/chat-models/providers#watsonx-ibm-watsonxai"
>}}) | ✅ | ✅ |
-
-**Embedding Models**
-
-| Provider | Python | Java |
-|---|---|---|
-| [Amazon Bedrock]({{< ref
"docs/development/vector-search/embedding_models/providers#amazon-bedrock" >}})
| ❌ | ✅ |
-| [Ollama]({{< ref
"docs/development/vector-search/embedding_models/providers#ollama" >}}) | ✅ | ✅
|
-| [OpenAI]({{< ref
"docs/development/vector-search/embedding_models/providers#openai" >}}) | ✅ | ✅
|
-| [Alibaba Cloud Model Studio (DashScope)]({{< ref
"docs/development/vector-search/embedding_models/providers#alibaba-cloud-model-studio-dashscope"
>}}) | ✅ | ❌ |
-
-**Vector Stores**
-
-| Provider | Python | Java |
-|---|---|---|
-| [Amazon OpenSearch]({{< ref
"docs/development/vector-search/vector_stores/providers#amazon-opensearch" >}})
| ❌ | ✅ |
-| [Amazon S3 Vectors]({{< ref
"docs/development/vector-search/vector_stores/providers#amazon-s3-vectors" >}})
| ❌ | ✅ |
-| [Chroma]({{< ref
"docs/development/vector-search/vector_stores/providers#chroma" >}}) | ✅ | ❌ |
-| [Elasticsearch]({{< ref
"docs/development/vector-search/vector_stores/providers#elasticsearch" >}}) | ❌
| ✅ |
-| [Mem0]({{< ref "docs/development/vector-search/vector_stores/providers#mem0"
>}}) | ✅ | ❌ |
-| [Milvus]({{< ref
"docs/development/vector-search/vector_stores/providers#milvus" >}}) | ❌ | ✅ |
-
-**MCP Server**
-
-| Provider | Python | Java |
-|---|---|---|
-| [MCP Server]({{< ref "docs/development/calling-llms/mcp" >}}) | ✅ | ✅ |
-
-> **Note**: Java native MCP support requires **JDK 17+**. For JDK 11-16, the
framework automatically uses the Python SDK via cross-language support, which
works seamlessly without additional configuration. See [MCP]({{< ref
"docs/development/calling-llms/mcp" >}}) for details.
-
-## Q4: How to run agent in IDE.
+## Q2: How do I run an Agent in an IDE?
To avoid potential conflict with Flink cluster, the scope of the dependencies
related to Flink and Flink Agents for agent job are provided. See [Maven
Dependencies]({{< ref "docs/get-started/setup#maven-dependencies-for-java" >}})
for details.
diff --git a/docs/content/docs/get-started/overview.md
b/docs/content/docs/get-started/overview.md
index fb8defa9..7af8e5a5 100644
--- a/docs/content/docs/get-started/overview.md
+++ b/docs/content/docs/get-started/overview.md
@@ -35,7 +35,7 @@ The key features of Apache Flink Agents include:
- **Seamless Data and AI Integration**: Agents interact directly with Flink's
DataStream and Table APIs for input and output, enabling a smooth integration
of structured data processing and semantic AI capabilities within Flink.
- **Reliable and Exactly-Once Execution**: Ensures exactly-once consistency
for agent actions and their side effects by integrating Flink's checkpointing
with an external write-ahead log, and supports durable execution - optionally
with reconcilers to reconcile in-flight side effects upon failure recovery - so
agents run reliably without human supervision.
- **Familiar Agent Abstractions**: Leverages well-known AI agent concepts -
skills, short/long-term memory, prompts, tools, and dynamic orchestration -
making it easy for developers experienced with agent-based systems to quickly
adopt and build on Apache Flink Agents without a steep learning curve.
-- **Multi-Language Supports**: Provides native APIs in Python, Java, and a
declarative YAML API, enabling seamless integration into diverse development
environments and allowing teams to use their preferred programming style. You
can even mix languages, authoring actions, tools, and events in one and running
them in an agent built in the other. For guidance on choosing Java or Python,
see [Should I choose Java or Python?]({{< ref
"docs/faq/faq#q3-should-i-choose-java-or-python" >}}).
+- **Multi-Language Support**: Provides Java, Python, and YAML APIs for
defining Agents. Actions and supported Resources can be implemented in Java or
Python and used across languages. See [Choose APIs and Languages]({{< ref
"docs/development/create-agent/choose-apis-and-languages" >}}).
- **Rich Ecosystem**: Natively integrates mainstream LLMs, vector stores from
diverse providers, and tools or prompts hosted on MCP servers into your agents,
while enabling customizable extensions.
- **Observability**: Adopts an event-centric orchestration approach, where all
agent actions are connected and controlled by events, enabling observation and
understanding of agent behavior through the event log.
diff --git a/docs/content/docs/get-started/quickstart/parallel_llm.md
b/docs/content/docs/get-started/quickstart/parallel_llm.md
index c161c34b..d140bb6b 100644
--- a/docs/content/docs/get-started/quickstart/parallel_llm.md
+++ b/docs/content/docs/get-started/quickstart/parallel_llm.md
@@ -31,10 +31,6 @@ This quickstart introduces an example that demonstrates how
to build a parallel
The **Parallel Sentiment Analysis** agent processes a restaurant review and
judges sentiment along two dimensions (taste / service) in parallel, then
aggregates the results into a one-line summary with a final LLM call. The
end-to-end wall clock time is roughly "slowest single branch + aggregation
call", rather than the sum of all three calls.
-{{< hint info >}}
-**JDK version note (Java only):** On JDK 21+, the framework uses the
Continuation API to execute concurrent chat actions in parallel. On JDK < 21,
the framework silently falls back to sequential execution — the result is
identical, but the LLM calls run one after another. Python uses native
coroutines and always executes in parallel regardless of the JDK version.
-{{< /hint >}}
-
## Code Walkthrough
### Prepare Agents Execution Environment
@@ -382,7 +378,7 @@ agentsEnv.execute();
* Unix-like environment (we use Linux, Mac OS X, Cygwin, WSL)
* Git
-* Java 11+ (Java 21+ recommended for parallel execution on the Java side)
+* Java 11+
* Python 3.10, 3.11 or 3.12
### Preparation
diff --git a/docs/content/docs/get-started/setup.md
b/docs/content/docs/get-started/setup.md
index 8e10e69d..f15fc120 100644
--- a/docs/content/docs/get-started/setup.md
+++ b/docs/content/docs/get-started/setup.md
@@ -25,9 +25,9 @@ under the License.
-->
## Overview
-Flink Agents provides both Python and Java APIs to define a Flink Agents job.
-
-The sections below show how to install the required dependencies.
+Flink Agents runs as part of a Java Flink or PyFlink job. Follow the setup for
that
+job. A YAML Agent can be loaded by either type of job. If the Agent contains
both
+Java and Python components, install the dependencies required by both.
{{< hint warning >}}
__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).
@@ -37,8 +37,8 @@ __NOTE:__ To run on a Flink cluster, Flink-Agents requires a
stable release of F
Both the script-based and manual installation paths require:
-* **Java 11+** on your `PATH`. Java 21+ is recommended when using the Java API
— see the table below for the version-specific limitations.
-* **Python 3.10, 3.11, or 3.12** (only required if you plan to use the Python
API or PyFlink).
+* **Java 11+** on your `PATH`, using a JDK supported by your chosen Flink
release. See [Java Versions](#java-versions) for feature-specific requirements.
+* **Python 3.10, 3.11, or 3.12** when using a PyFlink job, Python Actions or
Resources, or another feature that uses Python, such as the Python MCP SDK.
This includes Java Flink jobs that use those components.
For building Flink Agents from source, you additionally need:
- Unix-like environment (Linux, macOS, Cygwin, or WSL)
@@ -47,14 +47,15 @@ For building Flink Agents from source, you additionally
need:
### Java Versions
-For running an agent built with the **Python API**, you can use any Java
version 11 or higher.
-
-When using the **Java API**, there are some functionality limitations for
earlier Java versions, as detailed below:
+The Flink Agents Java baseline is JDK 11. The JDK must also be supported by the
+Flink release you deploy. Concurrency and integration requirements depend on
the
+feature:
-| Java Version | Limitations |
-|--------------|------------------------|
-| Java 21+ | No limitations. |
-| Java 11-20 | Async execution is unavailable. |
+- Java Action scheduling differs between JDK 21+ and earlier JDKs. See
+ [Async Execution]({{< ref
"docs/development/create-agent/actions#async-execution" >}})
+ for configuration and the JDK 21+ JVM option.
+- Java-native MCP requires JDK 17+; on earlier supported JDKs, it uses the
Python SDK
+ and requires its Python dependencies. See [MCP SDK]({{< ref
"docs/development/calling-llms/mcp#mcp-sdk" >}}).
{{< hint info >}}
**Note**: Python 3.12 requires Flink 2.1 or above and Flink Agents 0.3 or
above.
@@ -91,7 +92,7 @@ tar -xzf flink-${FLINK_VERSION}-bin-scala_2.12.tgz
# Set FLINK_HOME environment variable
export FLINK_HOME=$(pwd)/flink-${FLINK_VERSION}
-# Copy the flink-python JAR from opt to lib (required for PyFlink)
+# Copy the flink-python JAR from opt to lib (required for PyFlink or Python
components)
cp $FLINK_HOME/opt/flink-python-${FLINK_VERSION}.jar $FLINK_HOME/lib/
```
@@ -211,19 +212,19 @@ export PYTHONPATH=$(python -c 'import sysconfig;
print(sysconfig.get_paths()["pu
**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 (Java jobs only)
+### Install Flink Agents Java Library (Java Flink jobs)
{{< hint info >}}
-**Skip this section if you only use the Python API.** When you call
+**Skip the manual JAR copy for PyFlink jobs.** When you call
`AgentsExecutionEnvironment.get_execution_environment(env=...)`, the framework
automatically registers the required JARs via `pipeline.jars` so Flink loads
them into the user-code classloader. No manual JAR copy into
`$FLINK_HOME/lib/` is needed.
{{< /hint >}}
-This step is for Java jobs (or other deployments that don't go through the
-Python entry point). Copy the Flink Agents distribution JAR to your Flink
-installation's `lib` directory:
+This step is for Java Flink jobs, including those that load YAML Agents or use
Python
+components. Copy the Flink Agents distribution JAR to your Flink
installation's `lib`
+directory:
{{< tabs "Install Flink Agents Java Library" >}}
@@ -282,7 +283,7 @@ For developing Flink Agents applications in Java, add the
following dependencies
{{< hint info >}}
All the above dependencies should be in provided scope, to avoid potential
conflict with the Flink cluster.
-For execution in IDE, enable the feature `add dependencies with provided scope
to classpath` in your IDE. See [FAQ]({{< ref
"docs/faq/faq#q4-how-to-run-agent-in-ide" >}}) for details.
+For execution in IDE, enable the feature `add dependencies with provided scope
to classpath` in your IDE. See [FAQ]({{< ref
"docs/faq/faq#q2-how-do-i-run-an-agent-in-an-ide" >}}) for details.
{{< /hint >}}
**Example `pom.xml`**
@@ -354,4 +355,5 @@ $FLINK_HOME/bin/flink run -c <your.main.class>
/path/to/your-job.jar
{{< /tabs >}}
-See [deployment]({{< ref "docs/operations/deployment" >}}) for more details on
running Flink Agents jobs.
+See [deployment]({{< ref "docs/operations/deployment" >}}) for more details on
+running Java Flink and PyFlink jobs with Flink Agents.
diff --git a/docs/content/docs/operations/configuration.md
b/docs/content/docs/operations/configuration.md
index 5b5ac7f3..18a98609 100644
--- a/docs/content/docs/operations/configuration.md
+++ b/docs/content/docs/operations/configuration.md
@@ -138,8 +138,8 @@ Here is the list of all built-in core configuration options.
| `async.batch.timeout.ms` | -1 (disabled) | long (milliseconds) | Overall
timeout for one async batch, including ordinary calls, durable calls, and
built-in async tool calls. Non-positive values disable it. Completed calls keep
their outcomes; unfinished calls receive timeout failures. For durable calls,
started calls are recorded as failures while unstarted calls remain pending for
recovery. Running callbacks may continue after timeout, occupy workers, and
produce external effects, so [...]
| `rag.async` | true | boolean
| Whether retrieve context asynchronously for built-in context retrieval
action.
|
| `num-async-threads` | os cpu count * 2 | int
| Size of the async worker pool shared by all keys on an operator subtask. On
JDK 21+ and in Python, chat, RAG, and batches use this pool. On older JDKs,
Java uses a separate batch pool of this size in addition to its Action workers.
Default `async.batch.parallelism` is `os cpu count`, so one full batch can
occupy up to half of this pool; multiple keys running large batches can
saturate it. |
-| `parallel-execution.enabled` | true | boolean
| Whether pure-**Java** agents run actions concurrently on the parallel
execution engine when the continuation-based engine is unavailable (**JDK <
21**). Same-key input records still commit in input order, and checkpoint
(exactly-once) semantics are unchanged. Set to `false` to fall back to the
serial engine. Ignored when the JDK 21 coroutine engine is available, and for
plans containing **Python** actions, [...]
-| `max-in-flight-input-records` | 100 | int
| Maximum number of input records that may be in flight concurrently. Only
enforced by the **JDK < 21** parallel execution engine for pure-**Java**
agents; the JDK 21 coroutine engine and plans containing **Python** actions
ignore it. Every admitted record consumes one unit of budget; at the cap,
admission of further records blocks until an in-flight record retires. |
+| `parallel-execution.enabled` | true | boolean
| Whether plans with only **Java Actions** run Actions concurrently on the
parallel execution engine when the continuation-based engine is unavailable
(**JDK < 21**). Plans declaring Python Resources additionally require a Flink
version supporting [cross-language async calls]({{< ref
"docs/development/create-agent/actions#cross-language-async-requirements" >}}).
Same-key input records commit in input order, [...]
+| `max-in-flight-input-records` | 100 | int
| Maximum number of input records that may be in flight concurrently. Only
enforced by the **JDK < 21** parallel execution engine for plans with only
**Java Actions**; the JDK 21 coroutine engine and plans containing **Python**
actions ignore it. Every admitted record consumes one unit of budget; at the
cap, admission of further records blocks until an in-flight record retires. |
| `job-identifier` | none | String
| The unique identifier of job, remaining consistent after restoring from a
savepoint. If not set, uses flink job id.
|
| `event-log.level` | STANDARD | EventLogLevel
| Global default verbosity for the [Event Log]({{< ref
"docs/operations/monitoring#event-log" >}}). Valid values: `OFF` (skip event),
`STANDARD` (payload may be truncated/summarized to keep logs concise),
`VERBOSE` (full payload). Can be overridden per event type — see
[Per-event-type log levels]({{< ref
"docs/operations/monitoring#per-event-type-log-levels" >}}). |
| `event-log.trace.enabled` | false | boolean
| Whether to persist Agent Trace information in the Event Log. When enabled,
business Events include trace context and Action/LLM/Parser/Tool lifecycle
Events are logged. |
diff --git a/docs/content/docs/operations/deployment.md
b/docs/content/docs/operations/deployment.md
index 129d55d3..b43afb98 100644
--- a/docs/content/docs/operations/deployment.md
+++ b/docs/content/docs/operations/deployment.md
@@ -24,9 +24,8 @@ under the License.
## Overview
-Flink Agents jobs run on Flink:
+Flink Agents runs as part of Java Flink or PyFlink jobs:
-- **Language Support**: Python & Java
- **Input and Output**: DataStream or Table
- **Suitable Use Case**: Production
@@ -35,7 +34,7 @@ Flink Agents jobs run on Flink:
### Prerequisites
- **Operating System**: Unix-like environment (Linux, macOS, Cygwin, or WSL)
-- **Python**: Version 3.10, 3.11 or 3.12
+- **Python**: Version 3.10, 3.11 or 3.12 when the job uses PyFlink or Python
components/features
- **Flink**: A running Flink cluster with version above 1.20.3 (including
1.20.3) and the Flink Agents dependency installed
{{< hint info >}}
@@ -44,16 +43,21 @@ Flink Agents jobs run on Flink:
### Prepare Flink Agents
-We recommend creating a Python virtual environment to install the Flink Agents
Python library.
-
-Follow the [instructions]({{< ref "docs/get-started/setup" >}}) to install the
Flink Agents Python and Java libraries.
+Follow [Setup]({{< ref "docs/get-started/setup" >}}) to install Flink Agents
for
+the Java Flink or PyFlink job. When the Agent uses Actions or Resources
implemented
+in the other language, also install their dependencies.
### Submit to Flink Cluster
+Submit the Java Flink or PyFlink job to the cluster. If the Agent is defined
in YAML,
+[load it in that job]({{< ref
"docs/development/create-agent/yaml#loading-and-running" >}})
+before submission.
+
{{< tabs "Submit to Flink Cluster" >}}
{{< tab "Python" >}}
-Submitting Flink Agent jobs to the Flink Cluster is the same as submitting
PyFlink jobs. For more details on all available options, please refer to the
[Flink CLI
documentation](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/deployment/cli/#submitting-pyflink-jobs).
+Submit a PyFlink job with Flink Agents in the same way as any other PyFlink
job. For
+all available options, see the [Flink CLI
documentation](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/deployment/cli/#submitting-pyflink-jobs).
```bash
<FLINK_HOME>/bin/flink run \
@@ -63,7 +67,8 @@ Submitting Flink Agent jobs to the Flink Cluster is the same
as submitting PyFli
{{< /tab >}}
{{< tab "Java" >}}
-Submitting Flink Agent jobs to the Flink Cluster is the same as submitting
Flink jobs. For more details on all available options, please refer to the
[Flink CLI
documentation](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/deployment/cli/#submitting-a-job).
+Submit a Java Flink job with Flink Agents in the same way as any other Java
Flink job.
+For all available options, see the [Flink CLI
documentation](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/deployment/cli/#submitting-a-job).
```bash
<FLINK_HOME>/bin/flink run \
