xintongsong commented on code in PR #459:
URL: https://github.com/apache/flink-agents/pull/459#discussion_r2711198880
##########
docs/content/docs/faq/faq.md:
##########
@@ -50,3 +50,20 @@ 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 (using Java resources from Python or vice versa) are
currently supported only when [running in Flink]({{< ref
"docs/operations/deployment#run-in-flink" >}}). Local development mode does not
support cross-language resources.
+
+This is because cross-language communication requires the Flink runtime
environment to properly bridge between Java and Python processes. In local
development mode, this bridge is not available.
+
+**Workarounds for local development:**
+
+- Use native implementations of the resources in your development language
+- Test cross-language functionality by deploying to a Flink cluster
+- Mock the cross-language resources for local testing
Review Comment:
I think we can just suggest using a Flink standalone cluster for testing.
The other two options don't really make sense.
##########
docs/content/docs/faq/faq.md:
##########
@@ -50,3 +50,20 @@ 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 (using Java resources from Python or vice versa) are
currently supported only when [running in Flink]({{< ref
"docs/operations/deployment#run-in-flink" >}}). Local development mode does not
support cross-language resources.
+
+This is because cross-language communication requires the Flink runtime
environment to properly bridge between Java and Python processes. In local
development mode, this bridge is not available.
+
+**Workarounds for local development:**
+
+- Use native implementations of the resources in your development language
+- Test cross-language functionality by deploying to a Flink cluster
+- Mock the cross-language resources for local testing
+
+**Additional considerations:**
+
+- Cross-language calls have a small performance overhead compared to native
calls
Review Comment:
No need to mention this.
##########
docs/content/docs/development/chat_models.md:
##########
@@ -603,6 +603,128 @@ Some popular options include:
Model availability and specifications may change. Always check the official
DashScope documentation for the latest information before implementing in
production.
{{< /hint >}}
+## Using Cross-Language Resources
+
+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., Tongyi is
currently Python-only)
+- You want to leverage existing implementations without rewriting them
+- Your team has expertise in a specific language but needs to integrate with
agents in another
+
+{{< hint info >}}
+If you encounter any issues with cross-language resources, please check the
[FAQ]({{< ref
"docs/faq/faq#q2-why-do-cross-language-resources-not-work-in-local-development-mode"
>}}) first.
+{{< /hint >}}
+
+### How It Works
+
+Cross-language providers use a bridge mechanism to invoke chat models across
the Java-Python boundary:
+
+- **From Python to Java**: Use `Constant.JAVA_CHAT_MODEL_CONNECTION` and
`Constant.JAVA_CHAT_MODEL_SETUP` with the `java_clazz` parameter pointing to
the Java implementation
+- **From Java to Python**: Use `Constant.PYTHON_CHAT_MODEL_CONNECTION` and
`Constant.PYTHON_CHAT_MODEL_SETUP` with `module` and `clazz` parameters
pointing to the Python implementation
+
+
+
+### Usage Example
+
+{{< tabs "Cross-Language Chat Model Usage Example" >}}
+
+{{< tab "Python" >}}
Review Comment:
It's confusing what does `python` mean here. I think we should say something
like "using python models in java", or "using java models in python".
##########
docs/content/docs/development/chat_models.md:
##########
@@ -603,6 +603,128 @@ Some popular options include:
Model availability and specifications may change. Always check the official
DashScope documentation for the latest information before implementing in
production.
{{< /hint >}}
+## Using Cross-Language Resources
+
+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., Tongyi is
currently Python-only)
+- You want to leverage existing implementations without rewriting them
+- Your team has expertise in a specific language but needs to integrate with
agents in another
+
+{{< hint info >}}
+If you encounter any issues with cross-language resources, please check the
[FAQ]({{< ref
"docs/faq/faq#q2-why-do-cross-language-resources-not-work-in-local-development-mode"
>}}) first.
+{{< /hint >}}
Review Comment:
This doesn't really make sense:
1. It says you can check FAQ when encountering any issue, while the FAQ only
has guidelines for one particular issue.
2. It says check the FAQ *first*. What should we do next?
I think we can just remove this hint, or we can just say this feature is not
supported for the local runner.
##########
docs/content/docs/development/chat_models.md:
##########
@@ -603,6 +603,128 @@ Some popular options include:
Model availability and specifications may change. Always check the official
DashScope documentation for the latest information before implementing in
production.
{{< /hint >}}
+## Using Cross-Language Resources
Review Comment:
```suggestion
## Using Cross-Language Providers
```
##########
docs/content/docs/development/mcp.md:
##########
@@ -187,4 +183,27 @@ public class ReviewAnalysisAgent extends Agent {
**Key points:**
- All tools and prompts from the MCP server are automatically registered.
-- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use#define-tool-as-static-method-in-agent-class" >}}) .
\ No newline at end of file
+- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use#define-tool-as-static-method-in-agent-class" >}}) .
+
+## Appendix
+
+### MCP Server Implementation
+
+Flink Agents provides two MCP SDK implementations for connecting to MCP
servers:
+
+| Agent Language | JDK Version | Default Implementation |
+|----------------|------------------|------------------------|
+| Python | Any | Python Native MCP SDK |
+| Java | JDK 17+ | Java Native MCP SDK |
+| Java | JDK 16 and below | Python Native MCP SDK |
Review Comment:
```suggestion
| Python | Any | Python SDK |
| Java | JDK 17+ | Java SDK |
| Java | JDK 16 and below | Python SDK |
```
##########
docs/content/docs/development/mcp.md:
##########
@@ -187,4 +183,27 @@ public class ReviewAnalysisAgent extends Agent {
**Key points:**
- All tools and prompts from the MCP server are automatically registered.
-- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use#define-tool-as-static-method-in-agent-class" >}}) .
\ No newline at end of file
+- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use#define-tool-as-static-method-in-agent-class" >}}) .
+
+## Appendix
+
+### MCP Server Implementation
+
+Flink Agents provides two MCP SDK implementations for connecting to MCP
servers:
Review Comment:
Normally, users don't need to be aware of this. The framework will
automatically decide based on language and version. The default behavior is
described as follows:
##########
docs/content/docs/development/chat_models.md:
##########
@@ -603,6 +603,128 @@ Some popular options include:
Model availability and specifications may change. Always check the official
DashScope documentation for the latest information before implementing in
production.
{{< /hint >}}
+## Using Cross-Language Resources
+
+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., Tongyi is
currently Python-only)
+- You want to leverage existing implementations without rewriting them
+- Your team has expertise in a specific language but needs to integrate with
agents in another
Review Comment:
These 3 points are the same thing?
##########
docs/content/docs/development/mcp.md:
##########
@@ -187,4 +183,27 @@ public class ReviewAnalysisAgent extends Agent {
**Key points:**
- All tools and prompts from the MCP server are automatically registered.
-- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use#define-tool-as-static-method-in-agent-class" >}}) .
\ No newline at end of file
+- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use#define-tool-as-static-method-in-agent-class" >}}) .
+
+## Appendix
+
+### MCP Server Implementation
Review Comment:
```suggestion
### MCP SDK
```
##########
docs/content/docs/development/chat_models.md:
##########
@@ -603,6 +603,128 @@ Some popular options include:
Model availability and specifications may change. Always check the official
DashScope documentation for the latest information before implementing in
production.
{{< /hint >}}
+## Using Cross-Language Resources
+
+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., Tongyi is
currently Python-only)
+- You want to leverage existing implementations without rewriting them
+- Your team has expertise in a specific language but needs to integrate with
agents in another
+
+{{< hint info >}}
+If you encounter any issues with cross-language resources, please check the
[FAQ]({{< ref
"docs/faq/faq#q2-why-do-cross-language-resources-not-work-in-local-development-mode"
>}}) first.
+{{< /hint >}}
+
+### How It Works
+
+Cross-language providers use a bridge mechanism to invoke chat models across
the Java-Python boundary:
+
+- **From Python to Java**: Use `Constant.JAVA_CHAT_MODEL_CONNECTION` and
`Constant.JAVA_CHAT_MODEL_SETUP` with the `java_clazz` parameter pointing to
the Java implementation
+- **From Java to Python**: Use `Constant.PYTHON_CHAT_MODEL_CONNECTION` and
`Constant.PYTHON_CHAT_MODEL_SETUP` with `module` and `clazz` parameters
pointing to the Python implementation
+
+
+
+### Usage Example
+
+{{< tabs "Cross-Language Chat Model Usage Example" >}}
+
+{{< tab "Python" >}}
+```python
+class MyAgent(Agent):
+
+ @chat_model_connection
+ @staticmethod
+ def java_chat_model_connection() -> ResourceDescriptor:
+ """ChatModelConnection responsible for ollama model service
connection."""
+ return ResourceDescriptor(
+ clazz=Constant.JAVA_CHAT_MODEL_CONNECTION,
+
java_clazz="org.apache.flink.agents.integrations.chatmodels.ollama.OllamaChatModelConnection",
+ endpoint="http://localhost:11434";,
+ requestTimeout=120,
+ )
Review Comment:
And we'd better provide the java code how `OllamaChatModelConnection` is
originally used in comments, so that users can compare and understand how this
wrapping works.
##########
docs/content/docs/development/mcp.md:
##########
@@ -187,4 +183,27 @@ public class ReviewAnalysisAgent extends Agent {
**Key points:**
- All tools and prompts from the MCP server are automatically registered.
-- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use#define-tool-as-static-method-in-agent-class" >}}) .
\ No newline at end of file
+- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use#define-tool-as-static-method-in-agent-class" >}}) .
+
+## Appendix
+
+### MCP Server Implementation
+
+Flink Agents provides two MCP SDK implementations for connecting to MCP
servers:
+
+| Agent Language | JDK Version | Default Implementation |
+|----------------|------------------|------------------------|
+| Python | Any | Python Native MCP SDK |
+| Java | JDK 17+ | Java Native MCP SDK |
+| Java | JDK 16 and below | Python Native MCP SDK |
+
+#### Overriding the Default (Java API Only)
+
+In most cases, the default `auto` selection works well. For **advanced users**
who need to override the implementation, use the `lang` parameter in the
`@MCPServer` annotation:
Review Comment:
In case users need to change the default behavior (not recommended), there's
an option...
##########
docs/content/docs/development/mcp.md:
##########
@@ -187,4 +183,27 @@ public class ReviewAnalysisAgent extends Agent {
**Key points:**
- All tools and prompts from the MCP server are automatically registered.
-- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use#define-tool-as-static-method-in-agent-class" >}}) .
\ No newline at end of file
+- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use#define-tool-as-static-method-in-agent-class" >}}) .
+
+## Appendix
+
+### MCP Server Implementation
+
+Flink Agents provides two MCP SDK implementations for connecting to MCP
servers:
Review Comment:
```suggestion
Flink Agents provides two implementations of MCP supports, based on MCP SDKs
in different languages (python & java):
```
##########
docs/content/docs/development/chat_models.md:
##########
@@ -603,6 +603,128 @@ Some popular options include:
Model availability and specifications may change. Always check the official
DashScope documentation for the latest information before implementing in
production.
{{< /hint >}}
+## Using Cross-Language Resources
+
+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., Tongyi is
currently Python-only)
+- You want to leverage existing implementations without rewriting them
+- Your team has expertise in a specific language but needs to integrate with
agents in another
+
+{{< hint info >}}
+If you encounter any issues with cross-language resources, please check the
[FAQ]({{< ref
"docs/faq/faq#q2-why-do-cross-language-resources-not-work-in-local-development-mode"
>}}) first.
+{{< /hint >}}
+
+### How It Works
+
+Cross-language providers use a bridge mechanism to invoke chat models across
the Java-Python boundary:
Review Comment:
Users should not care about the bridge mechanism. Just say using a special
wrapper model provider, and suggest the original provider as an argument.
--
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]
