Skip to content

[Docs] Cross-Language Actions #714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xintongsong merged 2 commits into from
May 31, 2026
+53 −1
Merged

[Docs] Cross-Language Actions #714

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
02975f6
[Docs] Cross-Language Actions
addu390 May 29, 2026
e5830ec
[Review] Add limitation hit for cross-language local
addu390 May 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions docs/content/docs/development/workflow_agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -490,6 +490,58 @@ To use async execution on JDK 21+, user should append jvm option `--add-exports=
{{< /tab >}}
{{< /tabs >}}

### Cross-language Actions

An action declared in one language can dispatch its body to the other language by setting a `target` on the decorator/annotation. The decorated function or annotated method then acts as a stub — it should raise so direct calls outside the framework fail loud.
Copy link
Copy Markdown
Collaborator

@weiqingy weiqingy May 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The three other cross-language sections — chat models (chat_models.md), embedding models, and vector stores — each carry the same caveat: "Cross-language resources are currently supported only when running in Flink, not in local development mode." The Java-from-Python action path documented here goes through the same Pemja bridge inside ActionExecutionOperator (CrossLanguageActionRuntimeTest exercises it via the Flink operator harness, not local mode). Does that same local-dev limitation apply to cross-language actions? If so, a matching one-line note here would save users a confusing local-mode failure — and there's no general caveat elsewhere in this page that already covers it.


{{< tabs "Cross-language Actions" >}}

{{< tab "Python" >}}
```python
from flink_agents.api.function import JavaFunction

class MyAgent(Agent):
@action(
InputEvent.EVENT_TYPE,
target=JavaFunction(
qualname="com.example.MyHandlers",
method_name="handleInput",
parameter_types=[
"org.apache.flink.agents.api.Event",
"org.apache.flink.agents.api.context.RunnerContext",
],
),
)
@staticmethod
def handle_input(event: Event, ctx: RunnerContext) -> None:
raise NotImplementedError("cross-language stub")
```
{{< /tab >}}

{{< tab "Java" >}}
```java
public class MyAgent extends Agent {
@Action(
listenEventTypes = {InputEvent.EVENT_TYPE},
target = @PythonFunction(
module = "my_pkg.handlers",
qualname = "handle_input"))
public static void handleInput(Event event, RunnerContext ctx) {
throw new UnsupportedOperationException("cross-language stub");
}
}
```
{{< /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 >}}

## Event

Events are JSON-serializable messages passed between actions. Every event has a `type` string used for routing and an `attributes` map that carries the payload. A single event may trigger multiple actions if they are all listening to its type.
Expand Down
2 changes: 1 addition & 1 deletion docs/content/docs/development/yaml.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -525,7 +525,7 @@ 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.

Not every resource type is cross-language. Currently `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.
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.

## YAML API Specification

Expand Down
Loading