Re: [PR] [docs] Add decision model entries to the resource, event, and cross-language indexes [flink-agents]

["wenjin272 (via GitHub)" <gi...@apache.org>]

wenjin272 commented on code in PR #1300:
URL: https://github.com/apache/flink-agents/pull/1300#discussion_r4332591200


##########
docs/content/docs/development/create-agent/resources.md:
##########
@@ -269,10 +271,11 @@ for these workflows.
 ## Cross-Language Resources
 
 An Agent can use supported Resource implementations from either Java or Python.
-This applies to chat model connections and setups, embedding model connections
-and setups, and vector stores. Choose an implementation based on the provider
-capabilities you need; the Agent's definition language does not require the
-implementation to use that same language.
+This applies to chat model connections and setups, decision model connections
+and setups, embedding model connections and setups, and vector stores. Choose
+an implementation based on the provider capabilities you need; the Agent's
+definition language does not require the implementation to use that same
+language.

Review Comment:
   Could we explicitly distinguish decision models from the resources that support both cross-language directions? Adding them to this general statement, followed by the Python-using-Java descriptor table, suggests that Python Agents can use Java decision models too. That path is currently rejected by `JavaResourceProvider.get()` with `Unsupported Java resource type`, as covered by `test_java_decision_implementations_are_rejected`.
   
   Suggested wording:
   
   ```suggestion
   Chat model connections and setups, embedding model connections and setups, and
   vector stores support cross-language use in both directions. Decision model
   connections and setups support cross-language use only from Java to Python:
   Java Agents can use Python implementations, but Python Agents cannot use Java
   implementations. Within these limits, choose an implementation based on the
   provider capabilities you need.
   ```



##########
docs/content/docs/development/create-agent/yaml.md:
##########
@@ -809,7 +809,7 @@ in a Java Flink job and use each component's `type:` to select its implementatio
 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` and external `subagents`) do not.
+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, and `decision_model_connections` and `decision_model_setups` support `type: python` on the Java loader; others (e.g. `mcp_servers` and external `subagents`) do not.

Review Comment:
   Could we restructure this paragraph around the supported directions? The Java-loader statement is correct, but the long sentence mixes implementation-language selection with cross-language support and leaves the unsupported reverse direction implicit. Also, “components” would cover Actions as well as Resources.
   
   Suggested replacement:
   
   ```suggestion
   Cross-language support varies by component:
   
   - `actions`, `tools`, `chat_model_connections`, `chat_model_setups`, `embedding_model_connections`, `embedding_model_setups`, and `vector_stores` support both directions: `type: python` when loaded from Java, and `type: java` when loaded from Python.
   - `decision_model_connections` and `decision_model_setups` support only Java-to-Python cross-language use: Java-loaded YAML can use Python implementations, but Python-loaded YAML cannot use Java implementations.
   - Other components, including `mcp_servers` and external `subagents`, do not support cross-language use.
   ```



-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org